From b0f7466ebaf398be007980954522998c6eb316f6 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Sun, 1 Mar 2026 10:32:20 -0800
Subject: [PATCH 001/267] chore(llm): Fixing test image selection (#8902)

---
 .github/actions/build-integration-image/action.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/actions/build-integration-image/action.yml b/.github/actions/build-integration-image/action.yml
index 254f1c67c85..c0e5d8146b9 100644
--- a/.github/actions/build-integration-image/action.yml
+++ b/.github/actions/build-integration-image/action.yml
@@ -54,6 +54,7 @@ runs:
       shell: bash
       env:
         RUNS_ON_ECR_CACHE: ${{ inputs.runs-on-ecr-cache }}
+        INTEGRATION_REPOSITORY: ${{ inputs.runs-on-ecr-cache }}
         TAG: nightly-llm-it-${{ inputs.run-id }}
         CACHE_SUFFIX: ${{ steps.format-branch.outputs.cache-suffix }}
         HEAD_SHA: ${{ inputs.github-sha }}

From 22a335fffaf40baba3eed07ad94468c963393a47 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Sun, 1 Mar 2026 18:35:31 -0800
Subject: [PATCH 002/267] feat: bg tasks via fastapi (#8861)

---
 ...4b1c89d2_add_indexing_to_userfilestatus.py |  51 ++++++
 .../tasks/user_file_processing/tasks.py       |  53 +++---
 backend/onyx/background/task_utils.py         | 169 ++++++++++++++++++
 backend/onyx/chat/llm_loop.py                 |  21 ++-
 backend/onyx/db/enums.py                      |   1 +
 backend/onyx/db/projects.py                   |  36 ++--
 backend/onyx/server/features/projects/api.py  |  71 +++++---
 .../tools/test_python_tool.py                 |   2 +
 .../tests/indexing/test_checkpointing.py      |  25 ++-
 .../indexing/test_repeated_error_state.py     |   4 +-
 .../test_user_file_impl_redis_locking.py      |  34 ++--
 .../test_user_file_processing_no_vectordb.py  |  34 ++--
 web/src/hooks/useCCPairs.ts                   |   6 +-
 web/src/lib/hooks.ts                          |   7 +-
 web/src/providers/SettingsProvider.tsx        |   3 +-
 .../popovers/ActionsPopover/index.tsx         |   5 +-
 web/src/refresh-pages/AppPage.tsx             |  14 +-
 web/src/sections/input/AppInputBar.tsx        |   4 +-
 .../sections/knowledge/AgentKnowledgePane.tsx |   2 +-
 .../sections/sidebar/UserAvatarPopover.tsx    |   7 +-
 20 files changed, 425 insertions(+), 124 deletions(-)
 create mode 100644 backend/alembic/versions/4a1e4b1c89d2_add_indexing_to_userfilestatus.py

diff --git a/backend/alembic/versions/4a1e4b1c89d2_add_indexing_to_userfilestatus.py b/backend/alembic/versions/4a1e4b1c89d2_add_indexing_to_userfilestatus.py
new file mode 100644
index 00000000000..7ceb195b2e6
--- /dev/null
+++ b/backend/alembic/versions/4a1e4b1c89d2_add_indexing_to_userfilestatus.py
@@ -0,0 +1,51 @@
+"""Add INDEXING to UserFileStatus
+
+Revision ID: 4a1e4b1c89d2
+Revises: 6b3b4083c5aa
+Create Date: 2026-02-28 00:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "4a1e4b1c89d2"
+down_revision = "6b3b4083c5aa"
+branch_labels = None
+depends_on = None
+
+TABLE = "user_file"
+COLUMN = "status"
+CONSTRAINT_NAME = "ck_user_file_status"
+
+OLD_VALUES = ("PROCESSING", "COMPLETED", "FAILED", "CANCELED", "DELETING")
+NEW_VALUES = ("PROCESSING", "INDEXING", "COMPLETED", "FAILED", "CANCELED", "DELETING")
+
+
+def _drop_status_check_constraint() -> None:
+    """Drop the existing CHECK constraint on user_file.status.
+
+    The constraint name is auto-generated by SQLAlchemy and unknown,
+    so we look it up via the inspector.
+    """
+    inspector = sa.inspect(op.get_bind())
+    for constraint in inspector.get_check_constraints(TABLE):
+        if COLUMN in constraint.get("sqltext", ""):
+            constraint_name = constraint["name"]
+            if constraint_name is not None:
+                op.drop_constraint(constraint_name, TABLE, type_="check")
+
+
+def upgrade() -> None:
+    _drop_status_check_constraint()
+    in_clause = ", ".join(f"'{v}'" for v in NEW_VALUES)
+    op.create_check_constraint(CONSTRAINT_NAME, TABLE, f"{COLUMN} IN ({in_clause})")
+
+
+def downgrade() -> None:
+    op.execute(
+        f"UPDATE {TABLE} SET {COLUMN} = 'PROCESSING' WHERE {COLUMN} = 'INDEXING'"
+    )
+    op.drop_constraint(CONSTRAINT_NAME, TABLE, type_="check")
+    in_clause = ", ".join(f"'{v}'" for v in OLD_VALUES)
+    op.create_check_constraint(CONSTRAINT_NAME, TABLE, f"{COLUMN} IN ({in_clause})")
diff --git a/backend/onyx/background/celery/tasks/user_file_processing/tasks.py b/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
index 6b1b3290eef..8c21071908c 100644
--- a/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
+++ b/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
@@ -414,7 +414,7 @@ def _process_user_file_with_indexing(
         raise RuntimeError(f"Indexing pipeline failed for user file {user_file_id}")
 
 
-def _process_user_file_impl(
+def process_user_file_impl(
     *, user_file_id: str, tenant_id: str, redis_locking: bool
 ) -> None:
     """Core implementation for processing a single user file.
@@ -423,7 +423,7 @@ def _process_user_file_impl(
     queued-key guard (Celery path).  When redis_locking=False, skips all Redis
     operations (BackgroundTask path).
     """
-    task_logger.info(f"_process_user_file_impl - Starting id={user_file_id}")
+    task_logger.info(f"process_user_file_impl - Starting id={user_file_id}")
     start = time.monotonic()
 
     file_lock: RedisLock | None = None
@@ -436,7 +436,7 @@ def _process_user_file_impl(
         )
         if file_lock is not None and not file_lock.acquire(blocking=False):
             task_logger.info(
-                f"_process_user_file_impl - Lock held, skipping user_file_id={user_file_id}"
+                f"process_user_file_impl - Lock held, skipping user_file_id={user_file_id}"
             )
             return
 
@@ -446,13 +446,16 @@ def _process_user_file_impl(
             uf = db_session.get(UserFile, _as_uuid(user_file_id))
             if not uf:
                 task_logger.warning(
-                    f"_process_user_file_impl - UserFile not found id={user_file_id}"
+                    f"process_user_file_impl - UserFile not found id={user_file_id}"
                 )
                 return
 
-            if uf.status != UserFileStatus.PROCESSING:
+            if uf.status not in (
+                UserFileStatus.PROCESSING,
+                UserFileStatus.INDEXING,
+            ):
                 task_logger.info(
-                    f"_process_user_file_impl - Skipping id={user_file_id} status={uf.status}"
+                    f"process_user_file_impl - Skipping id={user_file_id} status={uf.status}"
                 )
                 return
 
@@ -489,7 +492,7 @@ def _process_user_file_impl(
 
             except Exception as e:
                 task_logger.exception(
-                    f"_process_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
+                    f"process_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
                 )
                 current_user_file = db_session.get(UserFile, _as_uuid(user_file_id))
                 if (
@@ -503,7 +506,7 @@ def _process_user_file_impl(
 
         elapsed = time.monotonic() - start
         task_logger.info(
-            f"_process_user_file_impl - Finished id={user_file_id} docs={len(documents)} elapsed={elapsed:.2f}s"
+            f"process_user_file_impl - Finished id={user_file_id} docs={len(documents)} elapsed={elapsed:.2f}s"
         )
     except Exception as e:
         with get_session_with_current_tenant() as db_session:
@@ -515,7 +518,7 @@ def _process_user_file_impl(
                 db_session.commit()
 
         task_logger.exception(
-            f"_process_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
+            f"process_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
         )
     finally:
         if file_lock is not None and file_lock.owned():
@@ -530,7 +533,7 @@ def _process_user_file_impl(
 def process_single_user_file(
     self: Task, *, user_file_id: str, tenant_id: str  # noqa: ARG001
 ) -> None:
-    _process_user_file_impl(
+    process_user_file_impl(
         user_file_id=user_file_id, tenant_id=tenant_id, redis_locking=True
     )
 
@@ -585,7 +588,7 @@ def check_for_user_file_delete(self: Task, *, tenant_id: str) -> None:
     return None
 
 
-def _delete_user_file_impl(
+def delete_user_file_impl(
     *, user_file_id: str, tenant_id: str, redis_locking: bool
 ) -> None:
     """Core implementation for deleting a single user file.
@@ -593,7 +596,7 @@ def _delete_user_file_impl(
     When redis_locking=True, acquires a per-file Redis lock (Celery path).
     When redis_locking=False, skips Redis operations (BackgroundTask path).
     """
-    task_logger.info(f"_delete_user_file_impl - Starting id={user_file_id}")
+    task_logger.info(f"delete_user_file_impl - Starting id={user_file_id}")
 
     file_lock: RedisLock | None = None
     if redis_locking:
@@ -604,7 +607,7 @@ def _delete_user_file_impl(
         )
         if file_lock is not None and not file_lock.acquire(blocking=False):
             task_logger.info(
-                f"_delete_user_file_impl - Lock held, skipping user_file_id={user_file_id}"
+                f"delete_user_file_impl - Lock held, skipping user_file_id={user_file_id}"
             )
             return
 
@@ -613,7 +616,7 @@ def _delete_user_file_impl(
             user_file = db_session.get(UserFile, _as_uuid(user_file_id))
             if not user_file:
                 task_logger.info(
-                    f"_delete_user_file_impl - User file not found id={user_file_id}"
+                    f"delete_user_file_impl - User file not found id={user_file_id}"
                 )
                 return
 
@@ -662,15 +665,15 @@ def _delete_user_file_impl(
                 )
             except Exception as e:
                 task_logger.exception(
-                    f"_delete_user_file_impl - Error deleting file id={user_file.id} - {e.__class__.__name__}"
+                    f"delete_user_file_impl - Error deleting file id={user_file.id} - {e.__class__.__name__}"
                 )
 
             db_session.delete(user_file)
             db_session.commit()
-            task_logger.info(f"_delete_user_file_impl - Completed id={user_file_id}")
+            task_logger.info(f"delete_user_file_impl - Completed id={user_file_id}")
     except Exception as e:
         task_logger.exception(
-            f"_delete_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
+            f"delete_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
         )
     finally:
         if file_lock is not None and file_lock.owned():
@@ -685,7 +688,7 @@ def _delete_user_file_impl(
 def process_single_user_file_delete(
     self: Task, *, user_file_id: str, tenant_id: str  # noqa: ARG001
 ) -> None:
-    _delete_user_file_impl(
+    delete_user_file_impl(
         user_file_id=user_file_id, tenant_id=tenant_id, redis_locking=True
     )
 
@@ -759,7 +762,7 @@ def check_for_user_file_project_sync(self: Task, *, tenant_id: str) -> None:
     return None
 
 
-def _project_sync_user_file_impl(
+def project_sync_user_file_impl(
     *, user_file_id: str, tenant_id: str, redis_locking: bool
 ) -> None:
     """Core implementation for syncing a user file's project/persona metadata.
@@ -768,7 +771,7 @@ def _project_sync_user_file_impl(
     queued-key guard (Celery path).  When redis_locking=False, skips Redis
     operations (BackgroundTask path).
     """
-    task_logger.info(f"_project_sync_user_file_impl - Starting id={user_file_id}")
+    task_logger.info(f"project_sync_user_file_impl - Starting id={user_file_id}")
 
     file_lock: RedisLock | None = None
     if redis_locking:
@@ -780,7 +783,7 @@ def _project_sync_user_file_impl(
         )
         if file_lock is not None and not file_lock.acquire(blocking=False):
             task_logger.info(
-                f"_project_sync_user_file_impl - Lock held, skipping user_file_id={user_file_id}"
+                f"project_sync_user_file_impl - Lock held, skipping user_file_id={user_file_id}"
             )
             return
 
@@ -793,7 +796,7 @@ def _project_sync_user_file_impl(
             ).scalar_one_or_none()
             if not user_file:
                 task_logger.info(
-                    f"_project_sync_user_file_impl - User file not found id={user_file_id}"
+                    f"project_sync_user_file_impl - User file not found id={user_file_id}"
                 )
                 return
 
@@ -831,7 +834,7 @@ def _project_sync_user_file_impl(
                     )
 
             task_logger.info(
-                f"_project_sync_user_file_impl - User file id={user_file_id}"
+                f"project_sync_user_file_impl - User file id={user_file_id}"
             )
 
             user_file.needs_project_sync = False
@@ -844,7 +847,7 @@ def _project_sync_user_file_impl(
 
     except Exception as e:
         task_logger.exception(
-            f"_project_sync_user_file_impl - Error syncing project for file id={user_file_id} - {e.__class__.__name__}"
+            f"project_sync_user_file_impl - Error syncing project for file id={user_file_id} - {e.__class__.__name__}"
         )
     finally:
         if file_lock is not None and file_lock.owned():
@@ -859,6 +862,6 @@ def _project_sync_user_file_impl(
 def process_single_user_file_project_sync(
     self: Task, *, user_file_id: str, tenant_id: str  # noqa: ARG001
 ) -> None:
-    _project_sync_user_file_impl(
+    project_sync_user_file_impl(
         user_file_id=user_file_id, tenant_id=tenant_id, redis_locking=True
     )
diff --git a/backend/onyx/background/task_utils.py b/backend/onyx/background/task_utils.py
index a49a56745e6..070b26b6701 100644
--- a/backend/onyx/background/task_utils.py
+++ b/backend/onyx/background/task_utils.py
@@ -1,3 +1,33 @@
+"""Background task utilities.
+
+Contains query-history report helpers (used by all deployment modes) and
+in-process background task execution helpers for NO_VECTOR_DB mode:
+
+- Atomic claim-and-mark helpers that prevent duplicate processing
+- Drain loops that process all pending user file work
+
+Each claim function runs a short-lived transaction: SELECT ... FOR UPDATE
+SKIP LOCKED, UPDATE the row to remove it from future queries, COMMIT.
+After the commit the row lock is released, but the row is no longer
+eligible for re-claiming.  No long-lived sessions or advisory locks.
+"""
+
+from uuid import UUID
+
+import sqlalchemy as sa
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from onyx.db.enums import UserFileStatus
+from onyx.db.models import UserFile
+from onyx.utils.logger import setup_logger
+
+logger = setup_logger()
+
+# ------------------------------------------------------------------
+# Query-history report helpers (pre-existing, used by all modes)
+# ------------------------------------------------------------------
+
 QUERY_REPORT_NAME_PREFIX = "query-history"
 
 
@@ -9,3 +39,142 @@ def construct_query_history_report_name(
 
 def extract_task_id_from_query_history_report_name(name: str) -> str:
     return name.removeprefix(f"{QUERY_REPORT_NAME_PREFIX}-").removesuffix(".csv")
+
+
+# ------------------------------------------------------------------
+# Atomic claim-and-mark helpers
+# ------------------------------------------------------------------
+# Each function runs inside a single short-lived session/transaction:
+#   1. SELECT ... FOR UPDATE SKIP LOCKED  (locks one eligible row)
+#   2. UPDATE the row so it is no longer eligible
+#   3. COMMIT  (releases the row lock)
+# After the commit, no other drain loop can claim the same row.
+
+
+def _claim_next_processing_file(db_session: Session) -> UUID | None:
+    """Claim the next PROCESSING file by transitioning it to INDEXING.
+
+    Returns the file id, or None when no eligible files remain.
+    """
+    file_id = db_session.execute(
+        select(UserFile.id)
+        .where(UserFile.status == UserFileStatus.PROCESSING)
+        .order_by(UserFile.created_at)
+        .limit(1)
+        .with_for_update(skip_locked=True)
+    ).scalar_one_or_none()
+    if file_id is None:
+        return None
+
+    db_session.execute(
+        sa.update(UserFile)
+        .where(UserFile.id == file_id)
+        .values(status=UserFileStatus.INDEXING)
+    )
+    db_session.commit()
+    return file_id
+
+
+def _claim_next_deleting_file(db_session: Session) -> UUID | None:
+    """Claim the next DELETING file.
+
+    No status transition needed — the impl deletes the row on success.
+    The short-lived FOR UPDATE lock prevents concurrent claims.
+    """
+    file_id = db_session.execute(
+        select(UserFile.id)
+        .where(UserFile.status == UserFileStatus.DELETING)
+        .order_by(UserFile.created_at)
+        .limit(1)
+        .with_for_update(skip_locked=True)
+    ).scalar_one_or_none()
+    # Commit to release the row lock promptly.
+    db_session.commit()
+    return file_id
+
+
+def _claim_next_sync_file(db_session: Session) -> UUID | None:
+    """Claim the next file needing project/persona sync.
+
+    No status transition needed — the impl clears the sync flags on
+    success.  The short-lived FOR UPDATE lock prevents concurrent claims.
+    """
+    file_id = db_session.execute(
+        select(UserFile.id)
+        .where(
+            sa.and_(
+                sa.or_(
+                    UserFile.needs_project_sync.is_(True),
+                    UserFile.needs_persona_sync.is_(True),
+                ),
+                UserFile.status == UserFileStatus.COMPLETED,
+            )
+        )
+        .order_by(UserFile.created_at)
+        .limit(1)
+        .with_for_update(skip_locked=True)
+    ).scalar_one_or_none()
+    db_session.commit()
+    return file_id
+
+
+# ------------------------------------------------------------------
+# Drain loops — process *all* pending work of each type
+# ------------------------------------------------------------------
+
+
+def drain_processing_loop(tenant_id: str) -> None:
+    """Process all pending PROCESSING user files."""
+    from onyx.background.celery.tasks.user_file_processing.tasks import (
+        process_user_file_impl,
+    )
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+    while True:
+        with get_session_with_current_tenant() as session:
+            file_id = _claim_next_processing_file(session)
+        if file_id is None:
+            break
+        process_user_file_impl(
+            user_file_id=str(file_id),
+            tenant_id=tenant_id,
+            redis_locking=False,
+        )
+
+
+def drain_delete_loop(tenant_id: str) -> None:
+    """Delete all pending DELETING user files."""
+    from onyx.background.celery.tasks.user_file_processing.tasks import (
+        delete_user_file_impl,
+    )
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+    while True:
+        with get_session_with_current_tenant() as session:
+            file_id = _claim_next_deleting_file(session)
+        if file_id is None:
+            break
+        delete_user_file_impl(
+            user_file_id=str(file_id),
+            tenant_id=tenant_id,
+            redis_locking=False,
+        )
+
+
+def drain_project_sync_loop(tenant_id: str) -> None:
+    """Sync all pending project/persona metadata for user files."""
+    from onyx.background.celery.tasks.user_file_processing.tasks import (
+        project_sync_user_file_impl,
+    )
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+    while True:
+        with get_session_with_current_tenant() as session:
+            file_id = _claim_next_sync_file(session)
+        if file_id is None:
+            break
+        project_sync_user_file_impl(
+            user_file_id=str(file_id),
+            tenant_id=tenant_id,
+            redis_locking=False,
+        )
diff --git a/backend/onyx/chat/llm_loop.py b/backend/onyx/chat/llm_loop.py
index bc802ce95bd..bbe05bb68a6 100644
--- a/backend/onyx/chat/llm_loop.py
+++ b/backend/onyx/chat/llm_loop.py
@@ -1,6 +1,7 @@
 import json
 import time
 from collections.abc import Callable
+from typing import Any
 from typing import Literal
 
 from sqlalchemy.orm import Session
@@ -530,11 +531,13 @@ def _create_file_tool_metadata_message(
     """
     lines = [
         "You have access to the following files. Use the read_file tool to "
-        "read sections of any file:"
+        "read sections of any file. You MUST pass the file_id UUID (not the "
+        "filename) to read_file:"
     ]
     for meta in file_metadata:
         lines.append(
-            f'- {meta.file_id}: "{meta.filename}" (~{meta.approx_char_count:,} chars)'
+            f'- file_id="{meta.file_id}" filename="{meta.filename}" '
+            f"(~{meta.approx_char_count:,} chars)"
         )
 
     message_content = "\n".join(lines)
@@ -558,12 +561,16 @@ def _create_context_files_message(
     # Format as documents JSON as described in README
     documents_list = []
     for idx, file_text in enumerate(context_files.file_texts, start=1):
-        documents_list.append(
-            {
-                "document": idx,
-                "contents": file_text,
-            }
+        title = (
+            context_files.file_metadata[idx - 1].filename
+            if idx - 1 < len(context_files.file_metadata)
+            else None
         )
+        entry: dict[str, Any] = {"document": idx}
+        if title:
+            entry["title"] = title
+        entry["contents"] = file_text
+        documents_list.append(entry)
 
     documents_json = json.dumps({"documents": documents_list}, indent=2)
     message_content = f"Here are some documents provided for context, they may not all be relevant:\n{documents_json}"
diff --git a/backend/onyx/db/enums.py b/backend/onyx/db/enums.py
index e6191db1baa..de7b666d4b7 100644
--- a/backend/onyx/db/enums.py
+++ b/backend/onyx/db/enums.py
@@ -186,6 +186,7 @@ class EmbeddingPrecision(str, PyEnum):
 
 class UserFileStatus(str, PyEnum):
     PROCESSING = "PROCESSING"
+    INDEXING = "INDEXING"
     COMPLETED = "COMPLETED"
     FAILED = "FAILED"
     CANCELED = "CANCELED"
diff --git a/backend/onyx/db/projects.py b/backend/onyx/db/projects.py
index 428e9cb56cf..740ff77ac41 100644
--- a/backend/onyx/db/projects.py
+++ b/backend/onyx/db/projects.py
@@ -9,8 +9,9 @@
 from pydantic import ConfigDict
 from sqlalchemy import func
 from sqlalchemy.orm import Session
+from starlette.background import BackgroundTasks
 
-from onyx.background.celery.versioned_apps.client import app as client_app
+from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.configs.constants import FileOrigin
 from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryQueues
@@ -105,8 +106,8 @@ def upload_files_to_user_files_with_indexing(
     user: User,
     temp_id_map: dict[str, str] | None,
     db_session: Session,
+    background_tasks: BackgroundTasks | None = None,
 ) -> CategorizedFilesResult:
-    # Validate project ownership if a project_id is provided
     if project_id is not None and user is not None:
         if not check_project_ownership(project_id, user.id, db_session):
             raise HTTPException(status_code=404, detail="Project not found")
@@ -127,16 +128,27 @@ def upload_files_to_user_files_with_indexing(
         logger.warning(
             f"File {rejected_file.filename} rejected for {rejected_file.reason}"
         )
-    for user_file in user_files:
-        task = client_app.send_task(
-            OnyxCeleryTask.PROCESS_SINGLE_USER_FILE,
-            kwargs={"user_file_id": user_file.id, "tenant_id": tenant_id},
-            queue=OnyxCeleryQueues.USER_FILE_PROCESSING,
-            priority=OnyxCeleryPriority.HIGH,
-        )
-        logger.info(
-            f"Triggered indexing for user_file_id={user_file.id} with task_id={task.id}"
-        )
+
+    if DISABLE_VECTOR_DB and background_tasks is not None:
+        from onyx.background.task_utils import drain_processing_loop
+
+        background_tasks.add_task(drain_processing_loop, tenant_id)
+        for user_file in user_files:
+            logger.info(f"Queued in-process processing for user_file_id={user_file.id}")
+    else:
+        from onyx.background.celery.versioned_apps.client import app as client_app
+
+        for user_file in user_files:
+            task = client_app.send_task(
+                OnyxCeleryTask.PROCESS_SINGLE_USER_FILE,
+                kwargs={"user_file_id": user_file.id, "tenant_id": tenant_id},
+                queue=OnyxCeleryQueues.USER_FILE_PROCESSING,
+                priority=OnyxCeleryPriority.HIGH,
+            )
+            logger.info(
+                f"Triggered indexing for user_file_id={user_file.id} "
+                f"with task_id={task.id}"
+            )
 
     return CategorizedFilesResult(
         user_files=user_files,
diff --git a/backend/onyx/server/features/projects/api.py b/backend/onyx/server/features/projects/api.py
index 5ad7a7a6089..bcd55003433 100644
--- a/backend/onyx/server/features/projects/api.py
+++ b/backend/onyx/server/features/projects/api.py
@@ -2,6 +2,7 @@
 from uuid import UUID
 
 from fastapi import APIRouter
+from fastapi import BackgroundTasks
 from fastapi import Depends
 from fastapi import File
 from fastapi import Form
@@ -12,13 +13,7 @@
 from sqlalchemy.orm import Session
 
 from onyx.auth.users import current_user
-from onyx.background.celery.tasks.user_file_processing.tasks import (
-    enqueue_user_file_project_sync_task,
-)
-from onyx.background.celery.tasks.user_file_processing.tasks import (
-    get_user_file_project_sync_queue_depth,
-)
-from onyx.background.celery.versioned_apps.client import app as client_app
+from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryQueues
 from onyx.configs.constants import OnyxCeleryTask
@@ -34,7 +29,6 @@
 from onyx.db.persona import get_personas_by_ids
 from onyx.db.projects import get_project_token_count
 from onyx.db.projects import upload_files_to_user_files_with_indexing
-from onyx.redis.redis_pool import get_redis_client
 from onyx.server.features.projects.models import CategorizedFilesSnapshot
 from onyx.server.features.projects.models import ChatSessionRequest
 from onyx.server.features.projects.models import TokenCountResponse
@@ -55,7 +49,27 @@ class UserFileDeleteResult(BaseModel):
     assistant_names: list[str] = []
 
 
-def _trigger_user_file_project_sync(user_file_id: UUID, tenant_id: str) -> None:
+def _trigger_user_file_project_sync(
+    user_file_id: UUID,
+    tenant_id: str,
+    background_tasks: BackgroundTasks | None = None,
+) -> None:
+    if DISABLE_VECTOR_DB and background_tasks is not None:
+        from onyx.background.task_utils import drain_project_sync_loop
+
+        background_tasks.add_task(drain_project_sync_loop, tenant_id)
+        logger.info(f"Queued in-process project sync for user_file_id={user_file_id}")
+        return
+
+    from onyx.background.celery.tasks.user_file_processing.tasks import (
+        enqueue_user_file_project_sync_task,
+    )
+    from onyx.background.celery.tasks.user_file_processing.tasks import (
+        get_user_file_project_sync_queue_depth,
+    )
+    from onyx.background.celery.versioned_apps.client import app as client_app
+    from onyx.redis.redis_pool import get_redis_client
+
     queue_depth = get_user_file_project_sync_queue_depth(client_app)
     if queue_depth > USER_FILE_PROJECT_SYNC_MAX_QUEUE_DEPTH:
         logger.warning(
@@ -111,6 +125,7 @@ def create_project(
 
 @router.post("/file/upload", tags=PUBLIC_API_TAGS)
 def upload_user_files(
+    bg_tasks: BackgroundTasks,
     files: list[UploadFile] = File(...),
     project_id: int | None = Form(None),
     temp_id_map: str | None = Form(None),  # JSON string mapping hashed key -> temp_id
@@ -137,12 +152,12 @@ def upload_user_files(
             user=user,
             temp_id_map=parsed_temp_id_map,
             db_session=db_session,
+            background_tasks=bg_tasks if DISABLE_VECTOR_DB else None,
         )
 
         return CategorizedFilesSnapshot.from_result(categorized_files_result)
 
     except Exception as e:
-        # Log error with type, message, and stack for easier debugging
         logger.exception(f"Error uploading files - {type(e).__name__}: {str(e)}")
         raise HTTPException(
             status_code=500,
@@ -192,6 +207,7 @@ def get_files_in_project(
 def unlink_user_file_from_project(
     project_id: int,
     file_id: UUID,
+    bg_tasks: BackgroundTasks,
     user: User = Depends(current_user),
     db_session: Session = Depends(get_session),
 ) -> Response:
@@ -208,7 +224,6 @@ def unlink_user_file_from_project(
     if project is None:
         raise HTTPException(status_code=404, detail="Project not found")
 
-    user_id = user.id
     user_file = (
         db_session.query(UserFile)
         .filter(UserFile.id == file_id, UserFile.user_id == user_id)
@@ -224,7 +239,7 @@ def unlink_user_file_from_project(
         db_session.commit()
 
     tenant_id = get_current_tenant_id()
-    _trigger_user_file_project_sync(user_file.id, tenant_id)
+    _trigger_user_file_project_sync(user_file.id, tenant_id, bg_tasks)
 
     return Response(status_code=204)
 
@@ -237,6 +252,7 @@ def unlink_user_file_from_project(
 def link_user_file_to_project(
     project_id: int,
     file_id: UUID,
+    bg_tasks: BackgroundTasks,
     user: User = Depends(current_user),
     db_session: Session = Depends(get_session),
 ) -> UserFileSnapshot:
@@ -268,7 +284,7 @@ def link_user_file_to_project(
         db_session.commit()
 
     tenant_id = get_current_tenant_id()
-    _trigger_user_file_project_sync(user_file.id, tenant_id)
+    _trigger_user_file_project_sync(user_file.id, tenant_id, bg_tasks)
 
     return UserFileSnapshot.from_model(user_file)
 
@@ -424,6 +440,7 @@ def delete_project(
 @router.delete("/file/{file_id}", tags=PUBLIC_API_TAGS)
 def delete_user_file(
     file_id: UUID,
+    bg_tasks: BackgroundTasks,
     user: User = Depends(current_user),
     db_session: Session = Depends(get_session),
 ) -> UserFileDeleteResult:
@@ -456,15 +473,25 @@ def delete_user_file(
     db_session.commit()
 
     tenant_id = get_current_tenant_id()
-    task = client_app.send_task(
-        OnyxCeleryTask.DELETE_SINGLE_USER_FILE,
-        kwargs={"user_file_id": str(user_file.id), "tenant_id": tenant_id},
-        queue=OnyxCeleryQueues.USER_FILE_DELETE,
-        priority=OnyxCeleryPriority.HIGH,
-    )
-    logger.info(
-        f"Triggered delete for user_file_id={user_file.id} with task_id={task.id}"
-    )
+    if DISABLE_VECTOR_DB:
+        from onyx.background.task_utils import drain_delete_loop
+
+        bg_tasks.add_task(drain_delete_loop, tenant_id)
+        logger.info(f"Queued in-process delete for user_file_id={user_file.id}")
+    else:
+        from onyx.background.celery.versioned_apps.client import app as client_app
+
+        task = client_app.send_task(
+            OnyxCeleryTask.DELETE_SINGLE_USER_FILE,
+            kwargs={"user_file_id": str(user_file.id), "tenant_id": tenant_id},
+            queue=OnyxCeleryQueues.USER_FILE_DELETE,
+            priority=OnyxCeleryPriority.HIGH,
+        )
+        logger.info(
+            f"Triggered delete for user_file_id={user_file.id} "
+            f"with task_id={task.id}"
+        )
+
     return UserFileDeleteResult(
         has_associations=False, project_names=[], assistant_names=[]
     )
diff --git a/backend/tests/external_dependency_unit/tools/test_python_tool.py b/backend/tests/external_dependency_unit/tools/test_python_tool.py
index 5e0915b9560..d96b4cdbfea 100644
--- a/backend/tests/external_dependency_unit/tools/test_python_tool.py
+++ b/backend/tests/external_dependency_unit/tools/test_python_tool.py
@@ -933,6 +933,7 @@
 
 import pytest
 from fastapi import UploadFile
+from fastapi.background import BackgroundTasks
 from sqlalchemy.orm import Session
 from starlette.datastructures import Headers
 
@@ -1139,6 +1140,7 @@ def test_code_interpreter_receives_chat_files(
     # Upload a test CSV
     csv_content = b"name,age,city\nAlice,30,NYC\nBob,25,SF\n"
     result = upload_user_files(
+        bg_tasks=BackgroundTasks(),
         files=[
             UploadFile(
                 file=io.BytesIO(csv_content),
diff --git a/backend/tests/integration/tests/indexing/test_checkpointing.py b/backend/tests/integration/tests/indexing/test_checkpointing.py
index 7760234d24e..869272a1848 100644
--- a/backend/tests/integration/tests/indexing/test_checkpointing.py
+++ b/backend/tests/integration/tests/indexing/test_checkpointing.py
@@ -414,6 +414,24 @@ def test_mock_connector_checkpoint_recovery(
     )
     assert finished_index_attempt.status == IndexingStatus.FAILED
 
+    # Pause the connector immediately to prevent check_for_indexing from
+    # creating automatic retry attempts while we reset the mock server.
+    # Without this, the INITIAL_INDEXING status causes immediate retries
+    # that would consume (or fail against) the mock server before we can
+    # set up the recovery behavior.
+    CCPairManager.pause_cc_pair(cc_pair, user_performing_action=admin_user)
+
+    # Collect all index attempt IDs created so far (the initial one plus
+    # any automatic retries that may have started before the pause took effect).
+    all_prior_attempt_ids: list[int] = []
+    index_attempts_page = IndexAttemptManager.get_index_attempt_page(
+        cc_pair_id=cc_pair.id,
+        page=0,
+        page_size=100,
+        user_performing_action=admin_user,
+    )
+    all_prior_attempt_ids = [ia.id for ia in index_attempts_page.items]
+
     # Verify initial state: both docs should be indexed
     with get_session_with_current_tenant() as db_session:
         documents = DocumentManager.fetch_documents_for_cc_pair(
@@ -465,17 +483,14 @@ def test_mock_connector_checkpoint_recovery(
     )
     assert response.status_code == 200
 
-    # After the failure, the connector is in repeated error state and paused.
-    # Set the manual indexing trigger first (while paused), then unpause.
-    # This ensures the trigger is set before CHECK_FOR_INDEXING runs, which will
-    # prevent the connector from being re-paused when repeated error state is detected.
+    # Set the manual indexing trigger, then unpause to allow the recovery run.
     CCPairManager.run_once(
         cc_pair, from_beginning=False, user_performing_action=admin_user
     )
     CCPairManager.unpause_cc_pair(cc_pair, user_performing_action=admin_user)
     recovery_index_attempt = IndexAttemptManager.wait_for_index_attempt_start(
         cc_pair_id=cc_pair.id,
-        index_attempts_to_ignore=[initial_index_attempt.id],
+        index_attempts_to_ignore=all_prior_attempt_ids,
         user_performing_action=admin_user,
     )
     IndexAttemptManager.wait_for_index_attempt_completion(
diff --git a/backend/tests/integration/tests/indexing/test_repeated_error_state.py b/backend/tests/integration/tests/indexing/test_repeated_error_state.py
index 039da0e6148..cea30095fca 100644
--- a/backend/tests/integration/tests/indexing/test_repeated_error_state.py
+++ b/backend/tests/integration/tests/indexing/test_repeated_error_state.py
@@ -130,8 +130,8 @@ def test_repeated_error_state_detection_and_recovery(
                 #     )
                 break
 
-        if time.monotonic() - start_time > 30:
-            assert False, "CC pair did not enter repeated error state within 30 seconds"
+        if time.monotonic() - start_time > 90:
+            assert False, "CC pair did not enter repeated error state within 90 seconds"
 
         time.sleep(2)
 
diff --git a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py
index 5fc77b5c8d5..4ae9f297b1f 100644
--- a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py
+++ b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py
@@ -11,13 +11,13 @@
 from uuid import uuid4
 
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _delete_user_file_impl,
+    delete_user_file_impl,
 )
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _process_user_file_impl,
+    process_user_file_impl,
 )
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _project_sync_user_file_impl,
+    project_sync_user_file_impl,
 )
 
 TASKS_MODULE = "onyx.background.celery.tasks.user_file_processing.tasks"
@@ -32,7 +32,7 @@ def _mock_session_returning_none() -> MagicMock:
 
 
 # ------------------------------------------------------------------
-# _process_user_file_impl
+# process_user_file_impl
 # ------------------------------------------------------------------
 
 
@@ -55,7 +55,7 @@ def test_redis_locking_true_acquires_and_releases_lock(
         mock_get_session.return_value.__enter__.return_value = session
 
         user_file_id = str(uuid4())
-        _process_user_file_impl(
+        process_user_file_impl(
             user_file_id=user_file_id,
             tenant_id="test-tenant",
             redis_locking=True,
@@ -79,7 +79,7 @@ def test_redis_locking_true_skips_when_lock_held(
         redis_client.lock.return_value = lock
         mock_get_redis.return_value = redis_client
 
-        _process_user_file_impl(
+        process_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=True,
@@ -98,7 +98,7 @@ def test_redis_locking_false_skips_redis_entirely(
         session = _mock_session_returning_none()
         mock_get_session.return_value.__enter__.return_value = session
 
-        _process_user_file_impl(
+        process_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=False,
@@ -127,21 +127,21 @@ def test_both_paths_call_db_get(
 
         uid = str(uuid4())
 
-        _process_user_file_impl(user_file_id=uid, tenant_id="t", redis_locking=True)
+        process_user_file_impl(user_file_id=uid, tenant_id="t", redis_locking=True)
         call_count_true = session.get.call_count
 
         session.reset_mock()
         mock_get_session.reset_mock()
         mock_get_session.return_value.__enter__.return_value = session
 
-        _process_user_file_impl(user_file_id=uid, tenant_id="t", redis_locking=False)
+        process_user_file_impl(user_file_id=uid, tenant_id="t", redis_locking=False)
         call_count_false = session.get.call_count
 
         assert call_count_true == call_count_false == 1
 
 
 # ------------------------------------------------------------------
-# _delete_user_file_impl
+# delete_user_file_impl
 # ------------------------------------------------------------------
 
 
@@ -163,7 +163,7 @@ def test_redis_locking_true_acquires_and_releases_lock(
         session = _mock_session_returning_none()
         mock_get_session.return_value.__enter__.return_value = session
 
-        _delete_user_file_impl(
+        delete_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=True,
@@ -186,7 +186,7 @@ def test_redis_locking_true_skips_when_lock_held(
         redis_client.lock.return_value = lock
         mock_get_redis.return_value = redis_client
 
-        _delete_user_file_impl(
+        delete_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=True,
@@ -205,7 +205,7 @@ def test_redis_locking_false_skips_redis_entirely(
         session = _mock_session_returning_none()
         mock_get_session.return_value.__enter__.return_value = session
 
-        _delete_user_file_impl(
+        delete_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=False,
@@ -216,7 +216,7 @@ def test_redis_locking_false_skips_redis_entirely(
 
 
 # ------------------------------------------------------------------
-# _project_sync_user_file_impl
+# project_sync_user_file_impl
 # ------------------------------------------------------------------
 
 
@@ -238,7 +238,7 @@ def test_redis_locking_true_acquires_and_releases_lock(
         session = _mock_session_returning_none()
         mock_get_session.return_value.__enter__.return_value = session
 
-        _project_sync_user_file_impl(
+        project_sync_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=True,
@@ -262,7 +262,7 @@ def test_redis_locking_true_skips_when_lock_held(
         redis_client.lock.return_value = lock
         mock_get_redis.return_value = redis_client
 
-        _project_sync_user_file_impl(
+        project_sync_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=True,
@@ -281,7 +281,7 @@ def test_redis_locking_false_skips_redis_entirely(
         session = _mock_session_returning_none()
         mock_get_session.return_value.__enter__.return_value = session
 
-        _project_sync_user_file_impl(
+        project_sync_user_file_impl(
             user_file_id=str(uuid4()),
             tenant_id="test-tenant",
             redis_locking=False,
diff --git a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py
index dcaf15f9a45..6171c4e4a5d 100644
--- a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py
+++ b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py
@@ -1,11 +1,11 @@
 """Tests for no-vector-DB user file processing paths.
 
 Verifies that when DISABLE_VECTOR_DB is True:
-- _process_user_file_impl calls _process_user_file_without_vector_db (not indexing)
+- process_user_file_impl calls _process_user_file_without_vector_db (not indexing)
 - _process_user_file_without_vector_db extracts text, counts tokens, stores plaintext,
   sets status=COMPLETED and chunk_count=0
-- _delete_user_file_impl skips vector DB chunk deletion
-- _project_sync_user_file_impl skips vector DB metadata update
+- delete_user_file_impl skips vector DB chunk deletion
+- project_sync_user_file_impl skips vector DB metadata update
 """
 
 from unittest.mock import MagicMock
@@ -13,16 +13,16 @@
 from uuid import uuid4
 
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _delete_user_file_impl,
+    _process_user_file_without_vector_db,
 )
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _process_user_file_impl,
+    delete_user_file_impl,
 )
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _process_user_file_without_vector_db,
+    process_user_file_impl,
 )
 from onyx.background.celery.tasks.user_file_processing.tasks import (
-    _project_sync_user_file_impl,
+    project_sync_user_file_impl,
 )
 from onyx.configs.constants import DocumentSource
 from onyx.connectors.models import Document
@@ -203,7 +203,7 @@ def test_preserves_deleting_status(
 
 
 # ------------------------------------------------------------------
-# _process_user_file_impl — branching on DISABLE_VECTOR_DB
+# process_user_file_impl — branching on DISABLE_VECTOR_DB
 # ------------------------------------------------------------------
 
 
@@ -227,7 +227,7 @@ def test_calls_without_vector_db_when_disabled(
         connector_mock.load_from_state.return_value = [_make_documents(["hello"])]
 
         with patch(f"{TASKS_MODULE}.LocalFileConnector", return_value=connector_mock):
-            _process_user_file_impl(
+            process_user_file_impl(
                 user_file_id=str(uf.id),
                 tenant_id="test-tenant",
                 redis_locking=False,
@@ -255,7 +255,7 @@ def test_calls_with_indexing_when_vector_db_enabled(
         connector_mock.load_from_state.return_value = [_make_documents(["hello"])]
 
         with patch(f"{TASKS_MODULE}.LocalFileConnector", return_value=connector_mock):
-            _process_user_file_impl(
+            process_user_file_impl(
                 user_file_id=str(uf.id),
                 tenant_id="test-tenant",
                 redis_locking=False,
@@ -291,7 +291,7 @@ def test_indexing_pipeline_not_called_when_disabled(
                 return_value=MagicMock(return_value=[1, 2, 3]),
             ),
         ):
-            _process_user_file_impl(
+            process_user_file_impl(
                 user_file_id=str(uf.id),
                 tenant_id="test-tenant",
                 redis_locking=False,
@@ -301,7 +301,7 @@ def test_indexing_pipeline_not_called_when_disabled(
 
 
 # ------------------------------------------------------------------
-# _delete_user_file_impl — vector DB skip
+# delete_user_file_impl — vector DB skip
 # ------------------------------------------------------------------
 
 
@@ -325,7 +325,7 @@ def test_skips_vector_db_deletion(
             patch(f"{TASKS_MODULE}.get_active_search_settings") as mock_get_ss,
             patch(f"{TASKS_MODULE}.httpx_init_vespa_pool") as mock_vespa_pool,
         ):
-            _delete_user_file_impl(
+            delete_user_file_impl(
                 user_file_id=str(uf.id),
                 tenant_id="test-tenant",
                 redis_locking=False,
@@ -354,7 +354,7 @@ def test_still_deletes_file_store_and_db_record(
         file_store = MagicMock()
         mock_get_file_store.return_value = file_store
 
-        _delete_user_file_impl(
+        delete_user_file_impl(
             user_file_id=str(uf.id),
             tenant_id="test-tenant",
             redis_locking=False,
@@ -366,7 +366,7 @@ def test_still_deletes_file_store_and_db_record(
 
 
 # ------------------------------------------------------------------
-# _project_sync_user_file_impl — vector DB skip
+# project_sync_user_file_impl — vector DB skip
 # ------------------------------------------------------------------
 
 
@@ -387,7 +387,7 @@ def test_skips_vector_db_update(
             patch(f"{TASKS_MODULE}.get_active_search_settings") as mock_get_ss,
             patch(f"{TASKS_MODULE}.httpx_init_vespa_pool") as mock_vespa_pool,
         ):
-            _project_sync_user_file_impl(
+            project_sync_user_file_impl(
                 user_file_id=str(uf.id),
                 tenant_id="test-tenant",
                 redis_locking=False,
@@ -408,7 +408,7 @@ def test_still_clears_sync_flags(
         session.execute.return_value.scalar_one_or_none.return_value = uf
         mock_get_session.return_value.__enter__.return_value = session
 
-        _project_sync_user_file_impl(
+        project_sync_user_file_impl(
             user_file_id=str(uf.id),
             tenant_id="test-tenant",
             redis_locking=False,
diff --git a/web/src/hooks/useCCPairs.ts b/web/src/hooks/useCCPairs.ts
index 4b52b6ea371..fe6bb0d2fbb 100644
--- a/web/src/hooks/useCCPairs.ts
+++ b/web/src/hooks/useCCPairs.ts
@@ -66,15 +66,15 @@ import { errorHandlingFetcher } from "@/lib/fetcher";
  * };
  * ```
  */
-export default function useCCPairs() {
+export default function useCCPairs(enabled: boolean = true) {
   const { data, error, isLoading, mutate } = useSWR<CCPairBasicInfo[]>(
-    "/api/manage/connector-status",
+    enabled ? "/api/manage/connector-status" : null,
     errorHandlingFetcher
   );
 
   return {
     ccPairs: data ?? [],
-    isLoading,
+    isLoading: enabled && isLoading,
     error,
     refetch: mutate,
   };
diff --git a/web/src/lib/hooks.ts b/web/src/lib/hooks.ts
index 14cf980bf5a..9a7fdf5fccd 100644
--- a/web/src/lib/hooks.ts
+++ b/web/src/lib/hooks.ts
@@ -222,9 +222,12 @@ export const useConnectorStatus = (refreshInterval = 30000) => {
   };
 };
 
-export const useBasicConnectorStatus = () => {
+export const useBasicConnectorStatus = (enabled: boolean = true) => {
   const url = "/api/manage/connector-status";
-  const swrResponse = useSWR<CCPairBasicInfo[]>(url, errorHandlingFetcher);
+  const swrResponse = useSWR<CCPairBasicInfo[]>(
+    enabled ? url : null,
+    errorHandlingFetcher
+  );
   return {
     ...swrResponse,
     refreshIndexingStatus: () => mutate(url),
diff --git a/web/src/providers/SettingsProvider.tsx b/web/src/providers/SettingsProvider.tsx
index aad0564aeac..02f1c095c72 100644
--- a/web/src/providers/SettingsProvider.tsx
+++ b/web/src/providers/SettingsProvider.tsx
@@ -19,7 +19,8 @@ export function SettingsProvider({
   settings: CombinedSettings;
 }) {
   const [isMobile, setIsMobile] = useState<boolean | undefined>();
-  const { ccPairs } = useCCPairs();
+  const vectorDbEnabled = settings.settings.vector_db_enabled !== false;
+  const { ccPairs } = useCCPairs(vectorDbEnabled);
 
   useEffect(() => {
     const checkMobile = () => {
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index c4749932a79..7f058c5b615 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -29,6 +29,7 @@ import { SourceMetadata } from "@/lib/search/interfaces";
 import { SourceIcon } from "@/components/SourceIcon";
 import { useAvailableTools } from "@/hooks/useAvailableTools";
 import useCCPairs from "@/hooks/useCCPairs";
+import { useSettingsContext } from "@/providers/SettingsProvider";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { useToolOAuthStatus } from "@/lib/hooks/useToolOAuthStatus";
 import LineItem from "@/refresh-components/buttons/LineItem";
@@ -274,9 +275,11 @@ export default function ActionsPopover({
   }, [selectedAssistant.id, setForcedToolIds]);
 
   const { isAdmin, isCurator } = useUser();
+  const settings = useSettingsContext();
+  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
 
   const { tools: availableTools } = useAvailableTools();
-  const { ccPairs } = useCCPairs();
+  const { ccPairs } = useCCPairs(vectorDbEnabled);
   const { currentProjectId, allCurrentProjectFiles } = useProjectsContext();
   const availableToolIdSet = new Set(availableTools.map((tool) => tool.id));
 
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 36e5947d51e..fe6d6a33d47 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -138,7 +138,13 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     currentChatSessionId,
     isLoading: isLoadingChatSessions,
   } = useChatSessions();
-  const { ccPairs } = useCCPairs();
+  // handle redirect if chat page is disabled
+  // NOTE: this must be done here, in a client component since
+  // settings are passed in via Context and therefore aren't
+  // available in server-side components
+  const settings = useSettingsContext();
+  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
+  const { ccPairs } = useCCPairs(vectorDbEnabled);
   const { tags } = useTags();
   const { documentSets } = useDocumentSets();
   const {
@@ -156,12 +162,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     setForcedToolIds([]);
   }, [currentProjectId, setForcedToolIds]);
 
-  // handle redirect if chat page is disabled
-  // NOTE: this must be done here, in a client component since
-  // settings are passed in via Context and therefore aren't
-  // available in server-side components
-  const settings = useSettingsContext();
-
   const isInitialLoad = useRef(true);
 
   const { agents, isLoading: isLoadingAgents } = useAgents();
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index 23d5f343dd9..de99d815eef 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -294,7 +294,9 @@ const AppInputBar = React.memo(
     );
 
     const { activePromptShortcuts } = usePromptShortcuts();
-    const { ccPairs, isLoading: ccPairsLoading } = useCCPairs();
+    const vectorDbEnabled =
+      combinedSettings?.settings.vector_db_enabled !== false;
+    const { ccPairs, isLoading: ccPairsLoading } = useCCPairs(vectorDbEnabled);
     const { data: federatedConnectorsData, isLoading: federatedLoading } =
       useFederatedConnectors();
 
diff --git a/web/src/sections/knowledge/AgentKnowledgePane.tsx b/web/src/sections/knowledge/AgentKnowledgePane.tsx
index 6ca132568ee..6bfbef134ac 100644
--- a/web/src/sections/knowledge/AgentKnowledgePane.tsx
+++ b/web/src/sections/knowledge/AgentKnowledgePane.tsx
@@ -892,7 +892,7 @@ export default function AgentKnowledgePane({
   }, [enableKnowledge]);
 
   // Get connected sources from CC pairs
-  const { ccPairs } = useCCPairs();
+  const { ccPairs } = useCCPairs(vectorDbEnabled);
   const connectedSources: ConnectedSource[] = useMemo(() => {
     if (!ccPairs || ccPairs.length === 0) return [];
     const sourceSet = new Set<ValidSources>();
diff --git a/web/src/sections/sidebar/UserAvatarPopover.tsx b/web/src/sections/sidebar/UserAvatarPopover.tsx
index 343c0e5f11d..c7413edf920 100644
--- a/web/src/sections/sidebar/UserAvatarPopover.tsx
+++ b/web/src/sections/sidebar/UserAvatarPopover.tsx
@@ -25,6 +25,7 @@ import {
 import { Section } from "@/layouts/general-layouts";
 import { toast } from "@/hooks/useToast";
 import useAppFocus from "@/hooks/useAppFocus";
+import { useSettingsContext } from "@/providers/SettingsProvider";
 
 function getDisplayName(email?: string, personalName?: string): string {
   // Prioritize custom personal name if set
@@ -165,6 +166,8 @@ export default function UserAvatarPopover({
   const { user } = useUser();
   const router = useRouter();
   const appFocus = useAppFocus();
+  const settings = useSettingsContext();
+  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
 
   // Fetch notifications for display
   // The GET endpoint also triggers a refresh if release notes are stale
@@ -183,7 +186,9 @@ export default function UserAvatarPopover({
       // Prefetch user settings data when popover opens for instant modal display
       preload("/api/user/pats", errorHandlingFetcher);
       preload("/api/federated/oauth-status", errorHandlingFetcher);
-      preload("/api/manage/connector-status", errorHandlingFetcher);
+      if (vectorDbEnabled) {
+        preload("/api/manage/connector-status", errorHandlingFetcher);
+      }
       preload("/api/llm/provider", errorHandlingFetcher);
       setPopupState("Settings");
     } else {

From 14fab7fcdfafe4107346cafa2c06c795c0fb54d6 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Sun, 1 Mar 2026 19:51:18 -0800
Subject: [PATCH 003/267] feat: no vector db beat tasks (#8865)

---
 backend/onyx/background/periodic_poller.py    | 284 ++++++++++++++++++
 backend/onyx/main.py                          |  12 +
 .../background/test_periodic_task_claim.py    | 257 ++++++++++++++++
 .../background/test_startup_recovery.py       | 219 ++++++++++++++
 4 files changed, 772 insertions(+)
 create mode 100644 backend/onyx/background/periodic_poller.py
 create mode 100644 backend/tests/external_dependency_unit/background/test_periodic_task_claim.py
 create mode 100644 backend/tests/external_dependency_unit/background/test_startup_recovery.py

diff --git a/backend/onyx/background/periodic_poller.py b/backend/onyx/background/periodic_poller.py
new file mode 100644
index 00000000000..9580fb7d652
--- /dev/null
+++ b/backend/onyx/background/periodic_poller.py
@@ -0,0 +1,284 @@
+"""Periodic poller for NO_VECTOR_DB deployments.
+
+Replaces Celery Beat and background workers with a lightweight daemon thread
+that runs from the API server process.  Two responsibilities:
+
+1. Recovery polling (every 30 s): re-processes user files stuck in
+   PROCESSING / DELETING / needs_sync states via the drain loops defined
+   in ``task_utils.py``.
+
+2. Periodic task execution (configurable intervals): runs LLM model updates
+   and scheduled evals at their configured cadences, with Postgres advisory
+   lock deduplication across multiple API server instances.
+"""
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from dataclasses import field
+
+from onyx.utils.logger import setup_logger
+
+logger = setup_logger()
+
+RECOVERY_INTERVAL_SECONDS = 30
+PERIODIC_TASK_LOCK_BASE = 20_000
+PERIODIC_TASK_KV_PREFIX = "periodic_poller:last_claimed:"
+
+
+# ------------------------------------------------------------------
+# Periodic task definitions
+# ------------------------------------------------------------------
+
+
+@dataclass
+class _PeriodicTaskDef:
+    name: str
+    interval_seconds: float
+    lock_id: int
+    run_fn: Callable[[], None]
+    last_run_at: float = field(default=0.0)
+
+
+def _run_auto_llm_update() -> None:
+    from onyx.configs.app_configs import AUTO_LLM_CONFIG_URL
+
+    if not AUTO_LLM_CONFIG_URL:
+        return
+
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+    from onyx.llm.well_known_providers.auto_update_service import (
+        sync_llm_models_from_github,
+    )
+
+    with get_session_with_current_tenant() as db_session:
+        sync_llm_models_from_github(db_session)
+
+
+def _run_scheduled_eval() -> None:
+    from onyx.configs.app_configs import BRAINTRUST_API_KEY
+    from onyx.configs.app_configs import SCHEDULED_EVAL_DATASET_NAMES
+    from onyx.configs.app_configs import SCHEDULED_EVAL_PERMISSIONS_EMAIL
+    from onyx.configs.app_configs import SCHEDULED_EVAL_PROJECT
+
+    if not all(
+        [
+            BRAINTRUST_API_KEY,
+            SCHEDULED_EVAL_PROJECT,
+            SCHEDULED_EVAL_DATASET_NAMES,
+            SCHEDULED_EVAL_PERMISSIONS_EMAIL,
+        ]
+    ):
+        return
+
+    from datetime import datetime
+    from datetime import timezone
+
+    from onyx.evals.eval import run_eval
+    from onyx.evals.models import EvalConfigurationOptions
+
+    run_timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    for dataset_name in SCHEDULED_EVAL_DATASET_NAMES:
+        try:
+            run_eval(
+                configuration=EvalConfigurationOptions(
+                    search_permissions_email=SCHEDULED_EVAL_PERMISSIONS_EMAIL,
+                    dataset_name=dataset_name,
+                    no_send_logs=False,
+                    braintrust_project=SCHEDULED_EVAL_PROJECT,
+                    experiment_name=f"{dataset_name} - {run_timestamp}",
+                ),
+                remote_dataset_name=dataset_name,
+            )
+        except Exception:
+            logger.exception(
+                f"Periodic poller - Failed scheduled eval for dataset {dataset_name}"
+            )
+
+
+def _build_periodic_tasks() -> list[_PeriodicTaskDef]:
+    from onyx.configs.app_configs import AUTO_LLM_CONFIG_URL
+    from onyx.configs.app_configs import AUTO_LLM_UPDATE_INTERVAL_SECONDS
+    from onyx.configs.app_configs import SCHEDULED_EVAL_DATASET_NAMES
+
+    tasks: list[_PeriodicTaskDef] = []
+    if AUTO_LLM_CONFIG_URL:
+        tasks.append(
+            _PeriodicTaskDef(
+                name="auto-llm-update",
+                interval_seconds=AUTO_LLM_UPDATE_INTERVAL_SECONDS,
+                lock_id=PERIODIC_TASK_LOCK_BASE,
+                run_fn=_run_auto_llm_update,
+            )
+        )
+    if SCHEDULED_EVAL_DATASET_NAMES:
+        tasks.append(
+            _PeriodicTaskDef(
+                name="scheduled-eval",
+                interval_seconds=7 * 24 * 3600,
+                lock_id=PERIODIC_TASK_LOCK_BASE + 1,
+                run_fn=_run_scheduled_eval,
+            )
+        )
+    return tasks
+
+
+# ------------------------------------------------------------------
+# Periodic task runner with advisory-lock-guarded claim
+# ------------------------------------------------------------------
+
+
+def _try_claim_task(task_def: _PeriodicTaskDef) -> bool:
+    """Atomically check whether *task_def* should run and record a claim.
+
+    Uses a transaction-scoped advisory lock for atomicity combined with a
+    ``KVStore`` timestamp for cross-instance dedup.  The DB session is held
+    only for this brief claim transaction, not during task execution.
+    """
+    from datetime import datetime
+    from datetime import timezone
+
+    from sqlalchemy import text
+
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+    from onyx.db.models import KVStore
+
+    kv_key = PERIODIC_TASK_KV_PREFIX + task_def.name
+
+    with get_session_with_current_tenant() as db_session:
+        acquired = db_session.execute(
+            text("SELECT pg_try_advisory_xact_lock(:id)"),
+            {"id": task_def.lock_id},
+        ).scalar()
+        if not acquired:
+            return False
+
+        row = db_session.query(KVStore).filter_by(key=kv_key).first()
+        if row and row.value is not None:
+            last_claimed = datetime.fromisoformat(str(row.value))
+            elapsed = (datetime.now(timezone.utc) - last_claimed).total_seconds()
+            if elapsed < task_def.interval_seconds:
+                return False
+
+        now_ts = datetime.now(timezone.utc).isoformat()
+        if row:
+            row.value = now_ts
+        else:
+            db_session.add(KVStore(key=kv_key, value=now_ts))
+        db_session.commit()
+
+    return True
+
+
+def _try_run_periodic_task(task_def: _PeriodicTaskDef) -> None:
+    """Run *task_def* if its interval has elapsed and no peer holds the lock."""
+    now = time.monotonic()
+    if now - task_def.last_run_at < task_def.interval_seconds:
+        return
+
+    if not _try_claim_task(task_def):
+        return
+
+    try:
+        task_def.run_fn()
+        task_def.last_run_at = now
+    except Exception:
+        logger.exception(
+            f"Periodic poller - Error running periodic task {task_def.name}"
+        )
+
+
+# ------------------------------------------------------------------
+# Recovery / drain loop runner
+# ------------------------------------------------------------------
+
+
+def _run_drain_loops(tenant_id: str) -> None:
+    from onyx.background.task_utils import drain_delete_loop
+    from onyx.background.task_utils import drain_processing_loop
+    from onyx.background.task_utils import drain_project_sync_loop
+
+    drain_processing_loop(tenant_id)
+    drain_delete_loop(tenant_id)
+    drain_project_sync_loop(tenant_id)
+
+
+# ------------------------------------------------------------------
+# Startup recovery (10g)
+# ------------------------------------------------------------------
+
+
+def recover_stuck_user_files(tenant_id: str) -> None:
+    """Run all drain loops once to re-process files left in intermediate states.
+
+    Called from ``lifespan()`` on startup when ``DISABLE_VECTOR_DB`` is set.
+    """
+    logger.info("recover_stuck_user_files - Checking for stuck user files")
+    try:
+        _run_drain_loops(tenant_id)
+    except Exception:
+        logger.exception("recover_stuck_user_files - Error during recovery")
+
+
+# ------------------------------------------------------------------
+# Daemon thread (10f)
+# ------------------------------------------------------------------
+
+_shutdown_event = threading.Event()
+_poller_thread: threading.Thread | None = None
+
+
+def _poller_loop(tenant_id: str) -> None:
+    from shared_configs.contextvars import CURRENT_TENANT_ID_CONTEXTVAR
+
+    CURRENT_TENANT_ID_CONTEXTVAR.set(tenant_id)
+
+    periodic_tasks = _build_periodic_tasks()
+    logger.info(
+        f"Periodic poller started with {len(periodic_tasks)} periodic task(s): "
+        f"{[t.name for t in periodic_tasks]}"
+    )
+
+    while not _shutdown_event.is_set():
+        try:
+            _run_drain_loops(tenant_id)
+        except Exception:
+            logger.exception("Periodic poller - Error in recovery polling")
+
+        for task_def in periodic_tasks:
+            try:
+                _try_run_periodic_task(task_def)
+            except Exception:
+                logger.exception(
+                    f"Periodic poller - Unhandled error checking task {task_def.name}"
+                )
+
+        _shutdown_event.wait(RECOVERY_INTERVAL_SECONDS)
+
+
+def start_periodic_poller(tenant_id: str) -> None:
+    """Start the periodic poller daemon thread."""
+    global _poller_thread  # noqa: PLW0603
+    _shutdown_event.clear()
+    _poller_thread = threading.Thread(
+        target=_poller_loop,
+        args=(tenant_id,),
+        daemon=True,
+        name="no-vectordb-periodic-poller",
+    )
+    _poller_thread.start()
+    logger.info("Periodic poller thread started")
+
+
+def stop_periodic_poller() -> None:
+    """Signal the periodic poller to stop and wait for it to exit."""
+    global _poller_thread  # noqa: PLW0603
+    if _poller_thread is None:
+        return
+    _shutdown_event.set()
+    _poller_thread.join(timeout=10)
+    if _poller_thread.is_alive():
+        logger.warning("Periodic poller thread did not stop within timeout")
+    _poller_thread = None
+    logger.info("Periodic poller thread stopped")
diff --git a/backend/onyx/main.py b/backend/onyx/main.py
index 405581aa7b5..2b692abb0d9 100644
--- a/backend/onyx/main.py
+++ b/backend/onyx/main.py
@@ -355,8 +355,20 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:  # noqa: ARG001
     if AUTH_RATE_LIMITING_ENABLED:
         await setup_auth_limiter()
 
+    if DISABLE_VECTOR_DB:
+        from onyx.background.periodic_poller import recover_stuck_user_files
+        from onyx.background.periodic_poller import start_periodic_poller
+
+        recover_stuck_user_files(POSTGRES_DEFAULT_SCHEMA)
+        start_periodic_poller(POSTGRES_DEFAULT_SCHEMA)
+
     yield
 
+    if DISABLE_VECTOR_DB:
+        from onyx.background.periodic_poller import stop_periodic_poller
+
+        stop_periodic_poller()
+
     SqlEngine.reset_engine()
 
     if AUTH_RATE_LIMITING_ENABLED:
diff --git a/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py b/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py
new file mode 100644
index 00000000000..92132e1db0d
--- /dev/null
+++ b/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py
@@ -0,0 +1,257 @@
+"""External dependency unit tests for periodic task claiming.
+
+Tests ``_try_claim_task`` and ``_try_run_periodic_task`` against real
+PostgreSQL, verifying happy-path behavior and concurrent-access safety.
+
+The claim mechanism uses a transaction-scoped advisory lock + a KVStore
+timestamp for cross-instance dedup.  The DB session is released before
+the task runs, so long-running tasks don't hold connections.
+"""
+
+import time
+from collections.abc import Generator
+from concurrent.futures import as_completed
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+from unittest.mock import MagicMock
+from uuid import uuid4
+
+import pytest
+
+from onyx.background.periodic_poller import _PeriodicTaskDef
+from onyx.background.periodic_poller import _try_claim_task
+from onyx.background.periodic_poller import _try_run_periodic_task
+from onyx.background.periodic_poller import PERIODIC_TASK_KV_PREFIX
+from onyx.db.engine.sql_engine import get_session_with_current_tenant
+from onyx.db.engine.sql_engine import SqlEngine
+from onyx.db.models import KVStore
+from shared_configs.contextvars import CURRENT_TENANT_ID_CONTEXTVAR
+from tests.external_dependency_unit.constants import TEST_TENANT_ID
+
+_TEST_LOCK_BASE = 90_000
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _init_engine() -> None:
+    SqlEngine.init_engine(pool_size=10, max_overflow=5)
+
+
+def _make_task(
+    *,
+    name: str | None = None,
+    interval: float = 3600,
+    lock_id: int | None = None,
+    run_fn: MagicMock | None = None,
+) -> _PeriodicTaskDef:
+    return _PeriodicTaskDef(
+        name=name or f"test-{uuid4().hex[:8]}",
+        interval_seconds=interval,
+        lock_id=lock_id or _TEST_LOCK_BASE,
+        run_fn=run_fn or MagicMock(),
+    )
+
+
+@pytest.fixture(autouse=True)
+def _cleanup_kv(
+    tenant_context: None,  # noqa: ARG001
+) -> Generator[None, None, None]:
+    yield
+    with get_session_with_current_tenant() as db_session:
+        db_session.query(KVStore).filter(
+            KVStore.key.like(f"{PERIODIC_TASK_KV_PREFIX}test-%")
+        ).delete(synchronize_session=False)
+        db_session.commit()
+
+
+# ------------------------------------------------------------------
+# Happy-path: _try_claim_task
+# ------------------------------------------------------------------
+
+
+class TestClaimHappyPath:
+    def test_first_claim_succeeds(self) -> None:
+        assert _try_claim_task(_make_task()) is True
+
+    def test_first_claim_creates_kv_row(self) -> None:
+        task = _make_task()
+        _try_claim_task(task)
+
+        with get_session_with_current_tenant() as db_session:
+            row = (
+                db_session.query(KVStore)
+                .filter_by(key=PERIODIC_TASK_KV_PREFIX + task.name)
+                .first()
+            )
+        assert row is not None
+        assert row.value is not None
+
+    def test_second_claim_within_interval_fails(self) -> None:
+        task = _make_task(interval=3600)
+        assert _try_claim_task(task) is True
+        assert _try_claim_task(task) is False
+
+    def test_claim_after_interval_succeeds(self) -> None:
+        task = _make_task(interval=1)
+        assert _try_claim_task(task) is True
+
+        kv_key = PERIODIC_TASK_KV_PREFIX + task.name
+        with get_session_with_current_tenant() as db_session:
+            row = db_session.query(KVStore).filter_by(key=kv_key).first()
+            assert row is not None
+            row.value = (datetime.now(timezone.utc) - timedelta(seconds=10)).isoformat()
+            db_session.commit()
+
+        assert _try_claim_task(task) is True
+
+
+# ------------------------------------------------------------------
+# Happy-path: _try_run_periodic_task
+# ------------------------------------------------------------------
+
+
+class TestRunHappyPath:
+    def test_runs_task_and_updates_last_run_at(self) -> None:
+        mock_fn = MagicMock()
+        task = _make_task(run_fn=mock_fn)
+
+        _try_run_periodic_task(task)
+
+        mock_fn.assert_called_once()
+        assert task.last_run_at > 0
+
+    def test_skips_when_in_memory_interval_not_elapsed(self) -> None:
+        mock_fn = MagicMock()
+        task = _make_task(run_fn=mock_fn, interval=3600)
+        task.last_run_at = time.monotonic()
+
+        _try_run_periodic_task(task)
+
+        mock_fn.assert_not_called()
+
+    def test_skips_when_db_claim_blocked(self) -> None:
+        name = f"test-{uuid4().hex[:8]}"
+        lock_id = _TEST_LOCK_BASE + 10
+
+        _try_claim_task(_make_task(name=name, lock_id=lock_id, interval=3600))
+
+        mock_fn = MagicMock()
+        task = _make_task(name=name, lock_id=lock_id, interval=3600, run_fn=mock_fn)
+        _try_run_periodic_task(task)
+
+        mock_fn.assert_not_called()
+
+    def test_task_exception_does_not_propagate(self) -> None:
+        task = _make_task(run_fn=MagicMock(side_effect=RuntimeError("boom")))
+        _try_run_periodic_task(task)
+
+    def test_claim_committed_before_task_runs(self) -> None:
+        """The KV claim must be visible in the DB when run_fn executes."""
+        task_name = f"test-order-{uuid4().hex[:8]}"
+        kv_key = PERIODIC_TASK_KV_PREFIX + task_name
+        claim_visible: list[bool] = []
+
+        def check_claim() -> None:
+            with get_session_with_current_tenant() as db_session:
+                row = db_session.query(KVStore).filter_by(key=kv_key).first()
+                claim_visible.append(row is not None and row.value is not None)
+
+        task = _PeriodicTaskDef(
+            name=task_name,
+            interval_seconds=3600,
+            lock_id=_TEST_LOCK_BASE + 11,
+            run_fn=check_claim,
+        )
+
+        _try_run_periodic_task(task)
+
+        assert claim_visible == [True]
+
+
+# ------------------------------------------------------------------
+# Concurrency: only one claimer should win
+# ------------------------------------------------------------------
+
+
+class TestClaimConcurrency:
+    def test_concurrent_claims_single_winner(self) -> None:
+        """Many threads claim the same task — exactly one should succeed."""
+        num_threads = 20
+        task_name = f"test-race-{uuid4().hex[:8]}"
+        lock_id = _TEST_LOCK_BASE + 20
+
+        def claim() -> bool:
+            CURRENT_TENANT_ID_CONTEXTVAR.set(TEST_TENANT_ID)
+            return _try_claim_task(
+                _PeriodicTaskDef(
+                    name=task_name,
+                    interval_seconds=3600,
+                    lock_id=lock_id,
+                    run_fn=lambda: None,
+                )
+            )
+
+        results: list[bool] = []
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [executor.submit(claim) for _ in range(num_threads)]
+            for future in as_completed(futures):
+                results.append(future.result())
+
+        winners = sum(1 for r in results if r)
+        assert winners == 1, f"Expected 1 winner, got {winners}"
+
+    def test_concurrent_run_single_execution(self) -> None:
+        """Many threads run the same task — run_fn fires exactly once."""
+        num_threads = 20
+        task_name = f"test-run-race-{uuid4().hex[:8]}"
+        lock_id = _TEST_LOCK_BASE + 21
+        counter = MagicMock()
+
+        def run() -> None:
+            CURRENT_TENANT_ID_CONTEXTVAR.set(TEST_TENANT_ID)
+            _try_run_periodic_task(
+                _PeriodicTaskDef(
+                    name=task_name,
+                    interval_seconds=3600,
+                    lock_id=lock_id,
+                    run_fn=counter,
+                )
+            )
+
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [executor.submit(run) for _ in range(num_threads)]
+            for future in as_completed(futures):
+                future.result()
+
+        assert (
+            counter.call_count == 1
+        ), f"Expected run_fn called once, got {counter.call_count}"
+
+    def test_no_errors_under_contention(self) -> None:
+        """All threads complete without exceptions under high contention."""
+        num_threads = 30
+        task_name = f"test-err-{uuid4().hex[:8]}"
+        lock_id = _TEST_LOCK_BASE + 22
+        errors: list[Exception] = []
+
+        def claim() -> bool:
+            CURRENT_TENANT_ID_CONTEXTVAR.set(TEST_TENANT_ID)
+            return _try_claim_task(
+                _PeriodicTaskDef(
+                    name=task_name,
+                    interval_seconds=3600,
+                    lock_id=lock_id,
+                    run_fn=lambda: None,
+                )
+            )
+
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [executor.submit(claim) for _ in range(num_threads)]
+            for future in as_completed(futures):
+                try:
+                    future.result()
+                except Exception as e:
+                    errors.append(e)
+
+        assert errors == [], f"Got {len(errors)} errors: {errors}"
diff --git a/backend/tests/external_dependency_unit/background/test_startup_recovery.py b/backend/tests/external_dependency_unit/background/test_startup_recovery.py
new file mode 100644
index 00000000000..01248efe7a2
--- /dev/null
+++ b/backend/tests/external_dependency_unit/background/test_startup_recovery.py
@@ -0,0 +1,219 @@
+"""External dependency unit tests for startup recovery (Step 10g).
+
+Seeds ``UserFile`` records in stuck states (PROCESSING, DELETING,
+needs_project_sync) then calls ``recover_stuck_user_files`` and verifies
+the drain loops pick them up via ``FOR UPDATE SKIP LOCKED``.
+
+Uses real PostgreSQL (via ``db_session`` / ``tenant_context`` fixtures).
+The per-file ``*_impl`` functions are mocked so no real file store or
+connector is needed — we only verify that recovery finds and dispatches
+the correct files.
+"""
+
+from collections.abc import Generator
+from unittest.mock import MagicMock
+from unittest.mock import patch
+from uuid import uuid4
+
+import pytest
+from sqlalchemy.orm import Session
+
+from onyx.background.periodic_poller import recover_stuck_user_files
+from onyx.db.enums import UserFileStatus
+from onyx.db.models import UserFile
+from tests.external_dependency_unit.conftest import create_test_user
+from tests.external_dependency_unit.constants import TEST_TENANT_ID
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_IMPL_MODULE = "onyx.background.celery.tasks.user_file_processing.tasks"
+
+
+def _create_user_file(
+    db_session: Session,
+    user_id: object,
+    *,
+    status: UserFileStatus = UserFileStatus.PROCESSING,
+    needs_project_sync: bool = False,
+    needs_persona_sync: bool = False,
+) -> UserFile:
+    uf = UserFile(
+        id=uuid4(),
+        user_id=user_id,
+        file_id=f"test_file_{uuid4().hex[:8]}",
+        name=f"test_{uuid4().hex[:8]}.txt",
+        file_type="text/plain",
+        status=status,
+        needs_project_sync=needs_project_sync,
+        needs_persona_sync=needs_persona_sync,
+    )
+    db_session.add(uf)
+    db_session.commit()
+    db_session.refresh(uf)
+    return uf
+
+
+@pytest.fixture()
+def _cleanup_user_files(db_session: Session) -> Generator[list[UserFile], None, None]:
+    """Track created UserFile rows and delete them after each test."""
+    created: list[UserFile] = []
+    yield created
+    for uf in created:
+        existing = db_session.get(UserFile, uf.id)
+        if existing:
+            db_session.delete(existing)
+    db_session.commit()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestRecoverProcessingFiles:
+    """Files in PROCESSING status are re-processed via the processing drain loop."""
+
+    def test_processing_files_recovered(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "recovery_proc")
+        uf = _create_user_file(db_session, user.id, status=UserFileStatus.PROCESSING)
+        _cleanup_user_files.append(uf)
+
+        mock_impl = MagicMock()
+        with patch(f"{_IMPL_MODULE}.process_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert (
+            str(uf.id) in called_ids
+        ), f"Expected file {uf.id} to be recovered but got: {called_ids}"
+
+    def test_completed_files_not_recovered(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "recovery_comp")
+        uf = _create_user_file(db_session, user.id, status=UserFileStatus.COMPLETED)
+        _cleanup_user_files.append(uf)
+
+        mock_impl = MagicMock()
+        with patch(f"{_IMPL_MODULE}.process_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert (
+            str(uf.id) not in called_ids
+        ), f"COMPLETED file {uf.id} should not have been recovered"
+
+
+class TestRecoverDeletingFiles:
+    """Files in DELETING status are recovered via the delete drain loop."""
+
+    def test_deleting_files_recovered(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "recovery_del")
+        uf = _create_user_file(db_session, user.id, status=UserFileStatus.DELETING)
+        _cleanup_user_files.append(uf)
+
+        mock_impl = MagicMock()
+        with patch(f"{_IMPL_MODULE}.delete_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert (
+            str(uf.id) in called_ids
+        ), f"Expected file {uf.id} to be recovered for deletion but got: {called_ids}"
+
+
+class TestRecoverSyncFiles:
+    """Files needing project/persona sync are recovered via the sync drain loop."""
+
+    def test_needs_project_sync_recovered(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "recovery_sync")
+        uf = _create_user_file(
+            db_session,
+            user.id,
+            status=UserFileStatus.COMPLETED,
+            needs_project_sync=True,
+        )
+        _cleanup_user_files.append(uf)
+
+        mock_impl = MagicMock()
+        with patch(f"{_IMPL_MODULE}.project_sync_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert (
+            str(uf.id) in called_ids
+        ), f"Expected file {uf.id} to be recovered for sync but got: {called_ids}"
+
+    def test_needs_persona_sync_recovered(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "recovery_psync")
+        uf = _create_user_file(
+            db_session,
+            user.id,
+            status=UserFileStatus.COMPLETED,
+            needs_persona_sync=True,
+        )
+        _cleanup_user_files.append(uf)
+
+        mock_impl = MagicMock()
+        with patch(f"{_IMPL_MODULE}.project_sync_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert (
+            str(uf.id) in called_ids
+        ), f"Expected file {uf.id} to be recovered for persona sync but got: {called_ids}"
+
+
+class TestRecoveryMultipleFiles:
+    """Recovery processes all stuck files in one pass, not just the first."""
+
+    def test_multiple_processing_files(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "recovery_multi")
+        files = []
+        for _ in range(3):
+            uf = _create_user_file(
+                db_session, user.id, status=UserFileStatus.PROCESSING
+            )
+            _cleanup_user_files.append(uf)
+            files.append(uf)
+
+        mock_impl = MagicMock()
+        with patch(f"{_IMPL_MODULE}.process_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = {call.kwargs["user_file_id"] for call in mock_impl.call_args_list}
+        expected_ids = {str(uf.id) for uf in files}
+        assert expected_ids.issubset(called_ids), (
+            f"Expected all {len(files)} files to be recovered. "
+            f"Missing: {expected_ids - called_ids}"
+        )

From 3fb4f5d6e6975348968a72ecd1baea70105be9f1 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 2 Mar 2026 07:11:32 -0800
Subject: [PATCH 004/267] refactor(opal): split ContentLg into ContentXl +
 ContentLg (#8904)

---
 web/lib/opal/src/components/Tag/README.md     |   2 +-
 .../opal/src/layouts/Content/ContentLg.tsx    | 198 +++++++++++++
 .../opal/src/layouts/Content/ContentMd.tsx    | 279 ++++++++++++++++++
 .../opal/src/layouts/Content/ContentSm.tsx    | 129 ++++++++
 .../opal/src/layouts/Content/ContentXl.tsx    | 256 ++++++++++++++++
 web/lib/opal/src/layouts/Content/README.md    |  57 ++--
 .../opal/src/layouts/Content/components.tsx   | 100 ++++---
 web/lib/opal/src/layouts/Content/styles.css   | 194 +++++++++---
 web/lib/opal/src/layouts/README.md            |   9 +-
 web/lib/opal/src/shared.ts                    |   2 +-
 10 files changed, 1122 insertions(+), 104 deletions(-)
 create mode 100644 web/lib/opal/src/layouts/Content/ContentLg.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/ContentMd.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/ContentSm.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/ContentXl.tsx

diff --git a/web/lib/opal/src/components/Tag/README.md b/web/lib/opal/src/components/Tag/README.md
index 9a4ad7ef05e..6bfd5feb828 100644
--- a/web/lib/opal/src/components/Tag/README.md
+++ b/web/lib/opal/src/components/Tag/README.md
@@ -42,7 +42,7 @@ import SvgStar from "@opal/icons/star";
 
 ## Usage inside Content
 
-Tag can be rendered as an accessory inside `Content`'s LabelLayout via the `tag` prop:
+Tag can be rendered as an accessory inside `Content`'s ContentMd via the `tag` prop:
 
 ```tsx
 import { Content } from "@opal/layouts";
diff --git a/web/lib/opal/src/layouts/Content/ContentLg.tsx b/web/lib/opal/src/layouts/Content/ContentLg.tsx
new file mode 100644
index 00000000000..8d26674e2b8
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/ContentLg.tsx
@@ -0,0 +1,198 @@
+"use client";
+
+import { Button } from "@opal/components/buttons/Button/components";
+import type { SizeVariant } from "@opal/shared";
+import SvgEdit from "@opal/icons/edit";
+import type { IconFunctionComponent } from "@opal/types";
+import { cn } from "@opal/utils";
+import { useState } from "react";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ContentLgSizePreset = "headline" | "section";
+
+interface ContentLgPresetConfig {
+  /** Icon width/height (CSS value). */
+  iconSize: string;
+  /** Tailwind padding class for the icon container. */
+  iconContainerPadding: string;
+  /** Gap between icon container and content (CSS value). */
+  gap: string;
+  /** Tailwind font class for the title. */
+  titleFont: string;
+  /** Title line-height — also used as icon container min-height (CSS value). */
+  lineHeight: string;
+  /** Button `size` prop for the edit button. Uses the shared `SizeVariant` scale. */
+  editButtonSize: SizeVariant;
+  /** Tailwind padding class for the edit button container. */
+  editButtonPadding: string;
+}
+
+interface ContentLgProps {
+  /** Optional icon component. */
+  icon?: IconFunctionComponent;
+
+  /** Main title text. */
+  title: string;
+
+  /** Optional description below the title. */
+  description?: string;
+
+  /** Enable inline editing of the title. */
+  editable?: boolean;
+
+  /** Called when the user commits an edit. */
+  onTitleChange?: (newTitle: string) => void;
+
+  /** Size preset. Default: `"headline"`. */
+  sizePreset?: ContentLgSizePreset;
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+const CONTENT_LG_PRESETS: Record<ContentLgSizePreset, ContentLgPresetConfig> = {
+  headline: {
+    iconSize: "2rem",
+    iconContainerPadding: "p-0.5",
+    gap: "0.25rem",
+    titleFont: "font-heading-h2",
+    lineHeight: "2.25rem",
+    editButtonSize: "md",
+    editButtonPadding: "p-1",
+  },
+  section: {
+    iconSize: "1.25rem",
+    iconContainerPadding: "p-1",
+    gap: "0rem",
+    titleFont: "font-heading-h3-muted",
+    lineHeight: "1.75rem",
+    editButtonSize: "sm",
+    editButtonPadding: "p-0.5",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ContentLg
+// ---------------------------------------------------------------------------
+
+function ContentLg({
+  sizePreset = "headline",
+  icon: Icon,
+  title,
+  description,
+  editable,
+  onTitleChange,
+}: ContentLgProps) {
+  const [editing, setEditing] = useState(false);
+  const [editValue, setEditValue] = useState(title);
+
+  const config = CONTENT_LG_PRESETS[sizePreset];
+
+  function startEditing() {
+    setEditValue(title);
+    setEditing(true);
+  }
+
+  function commit() {
+    const value = editValue.trim();
+    if (value && value !== title) onTitleChange?.(value);
+    setEditing(false);
+  }
+
+  return (
+    <div className="opal-content-lg" style={{ gap: config.gap }}>
+      {Icon && (
+        <div
+          className={cn(
+            "opal-content-lg-icon-container shrink-0",
+            config.iconContainerPadding
+          )}
+          style={{ minHeight: config.lineHeight }}
+        >
+          <Icon
+            className="opal-content-lg-icon"
+            style={{ width: config.iconSize, height: config.iconSize }}
+          />
+        </div>
+      )}
+
+      <div className="opal-content-lg-body">
+        <div className="opal-content-lg-title-row">
+          {editing ? (
+            <div className="opal-content-lg-input-sizer">
+              <span
+                className={cn("opal-content-lg-input-mirror", config.titleFont)}
+              >
+                {editValue || "\u00A0"}
+              </span>
+              <input
+                className={cn(
+                  "opal-content-lg-input",
+                  config.titleFont,
+                  "text-text-04"
+                )}
+                value={editValue}
+                onChange={(e) => setEditValue(e.target.value)}
+                size={1}
+                autoFocus
+                onFocus={(e) => e.currentTarget.select()}
+                onBlur={commit}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") commit();
+                  if (e.key === "Escape") {
+                    setEditValue(title);
+                    setEditing(false);
+                  }
+                }}
+                style={{ height: config.lineHeight }}
+              />
+            </div>
+          ) : (
+            <span
+              className={cn(
+                "opal-content-lg-title",
+                config.titleFont,
+                "text-text-04",
+                editable && "cursor-pointer"
+              )}
+              onClick={editable ? startEditing : undefined}
+              style={{ height: config.lineHeight }}
+            >
+              {title}
+            </span>
+          )}
+
+          {editable && !editing && (
+            <div
+              className={cn(
+                "opal-content-lg-edit-button",
+                config.editButtonPadding
+              )}
+            >
+              <Button
+                icon={SvgEdit}
+                prominence="internal"
+                size={config.editButtonSize}
+                tooltip="Edit"
+                tooltipSide="right"
+                onClick={startEditing}
+              />
+            </div>
+          )}
+        </div>
+
+        {description && (
+          <div className="opal-content-lg-description font-secondary-body text-text-03">
+            {description}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export { ContentLg, type ContentLgProps, type ContentLgSizePreset };
diff --git a/web/lib/opal/src/layouts/Content/ContentMd.tsx b/web/lib/opal/src/layouts/Content/ContentMd.tsx
new file mode 100644
index 00000000000..44b55b3e44a
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/ContentMd.tsx
@@ -0,0 +1,279 @@
+"use client";
+
+import { Button } from "@opal/components/buttons/Button/components";
+import { Tag, type TagProps } from "@opal/components/Tag/components";
+import type { SizeVariant } from "@opal/shared";
+import SvgAlertCircle from "@opal/icons/alert-circle";
+import SvgAlertTriangle from "@opal/icons/alert-triangle";
+import SvgEdit from "@opal/icons/edit";
+import SvgXOctagon from "@opal/icons/x-octagon";
+import type { IconFunctionComponent } from "@opal/types";
+import { cn } from "@opal/utils";
+import { useRef, useState } from "react";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ContentMdSizePreset = "main-content" | "main-ui" | "secondary";
+
+type ContentMdAuxIcon = "info-gray" | "info-blue" | "warning" | "error";
+
+interface ContentMdPresetConfig {
+  iconSize: string;
+  iconContainerPadding: string;
+  iconColorClass: string;
+  titleFont: string;
+  lineHeight: string;
+  gap: string;
+  /** Button `size` prop for the edit button. Uses the shared `SizeVariant` scale. */
+  editButtonSize: SizeVariant;
+  editButtonPadding: string;
+  optionalFont: string;
+  /** Aux icon size = lineHeight − 2 × p-0.5. */
+  auxIconSize: string;
+}
+
+interface ContentMdProps {
+  /** Optional icon component. */
+  icon?: IconFunctionComponent;
+
+  /** Main title text. */
+  title: string;
+
+  /** Optional description text below the title. */
+  description?: string;
+
+  /** Enable inline editing of the title. */
+  editable?: boolean;
+
+  /** Called when the user commits an edit. */
+  onTitleChange?: (newTitle: string) => void;
+
+  /** When `true`, renders "(Optional)" beside the title. */
+  optional?: boolean;
+
+  /** Auxiliary status icon rendered beside the title. */
+  auxIcon?: ContentMdAuxIcon;
+
+  /** Tag rendered beside the title. */
+  tag?: TagProps;
+
+  /** Size preset. Default: `"main-ui"`. */
+  sizePreset?: ContentMdSizePreset;
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+const CONTENT_MD_PRESETS: Record<ContentMdSizePreset, ContentMdPresetConfig> = {
+  "main-content": {
+    iconSize: "1rem",
+    iconContainerPadding: "p-1",
+    iconColorClass: "text-text-04",
+    titleFont: "font-main-content-emphasis",
+    lineHeight: "1.5rem",
+    gap: "0.125rem",
+    editButtonSize: "sm",
+    editButtonPadding: "p-0",
+    optionalFont: "font-main-content-muted",
+    auxIconSize: "1.25rem",
+  },
+  "main-ui": {
+    iconSize: "1rem",
+    iconContainerPadding: "p-0.5",
+    iconColorClass: "text-text-03",
+    titleFont: "font-main-ui-action",
+    lineHeight: "1.25rem",
+    gap: "0.25rem",
+    editButtonSize: "xs",
+    editButtonPadding: "p-0",
+    optionalFont: "font-main-ui-muted",
+    auxIconSize: "1rem",
+  },
+  secondary: {
+    iconSize: "0.75rem",
+    iconContainerPadding: "p-0.5",
+    iconColorClass: "text-text-04",
+    titleFont: "font-secondary-action",
+    lineHeight: "1rem",
+    gap: "0.125rem",
+    editButtonSize: "2xs",
+    editButtonPadding: "p-0",
+    optionalFont: "font-secondary-action",
+    auxIconSize: "0.75rem",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ContentMd
+// ---------------------------------------------------------------------------
+
+const AUX_ICON_CONFIG: Record<
+  ContentMdAuxIcon,
+  { icon: IconFunctionComponent; colorClass: string }
+> = {
+  "info-gray": { icon: SvgAlertCircle, colorClass: "text-text-02" },
+  "info-blue": { icon: SvgAlertCircle, colorClass: "text-status-info-05" },
+  warning: { icon: SvgAlertTriangle, colorClass: "text-status-warning-05" },
+  error: { icon: SvgXOctagon, colorClass: "text-status-error-05" },
+};
+
+function ContentMd({
+  icon: Icon,
+  title,
+  description,
+  editable,
+  onTitleChange,
+  optional,
+  auxIcon,
+  tag,
+  sizePreset = "main-ui",
+}: ContentMdProps) {
+  const [editing, setEditing] = useState(false);
+  const [editValue, setEditValue] = useState(title);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const config = CONTENT_MD_PRESETS[sizePreset];
+
+  function startEditing() {
+    setEditValue(title);
+    setEditing(true);
+  }
+
+  function commit() {
+    const value = editValue.trim();
+    if (value && value !== title) onTitleChange?.(value);
+    setEditing(false);
+  }
+
+  return (
+    <div className="opal-content-md" style={{ gap: config.gap }}>
+      {Icon && (
+        <div
+          className={cn(
+            "opal-content-md-icon-container shrink-0",
+            config.iconContainerPadding
+          )}
+          style={{ minHeight: config.lineHeight }}
+        >
+          <Icon
+            className={cn("opal-content-md-icon", config.iconColorClass)}
+            style={{ width: config.iconSize, height: config.iconSize }}
+          />
+        </div>
+      )}
+
+      <div className="opal-content-md-body">
+        <div className="opal-content-md-title-row">
+          {editing ? (
+            <div className="opal-content-md-input-sizer">
+              <span
+                className={cn("opal-content-md-input-mirror", config.titleFont)}
+              >
+                {editValue || "\u00A0"}
+              </span>
+              <input
+                ref={inputRef}
+                className={cn(
+                  "opal-content-md-input",
+                  config.titleFont,
+                  "text-text-04"
+                )}
+                value={editValue}
+                onChange={(e) => setEditValue(e.target.value)}
+                size={1}
+                autoFocus
+                onFocus={(e) => e.currentTarget.select()}
+                onBlur={commit}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") commit();
+                  if (e.key === "Escape") {
+                    setEditValue(title);
+                    setEditing(false);
+                  }
+                }}
+                style={{ height: config.lineHeight }}
+              />
+            </div>
+          ) : (
+            <span
+              className={cn(
+                "opal-content-md-title",
+                config.titleFont,
+                "text-text-04",
+                editable && "cursor-pointer"
+              )}
+              onClick={editable ? startEditing : undefined}
+              style={{ height: config.lineHeight }}
+            >
+              {title}
+            </span>
+          )}
+
+          {optional && (
+            <span
+              className={cn(config.optionalFont, "text-text-03 shrink-0")}
+              style={{ height: config.lineHeight }}
+            >
+              (Optional)
+            </span>
+          )}
+
+          {auxIcon &&
+            (() => {
+              const { icon: AuxIcon, colorClass } = AUX_ICON_CONFIG[auxIcon];
+              return (
+                <div
+                  className="opal-content-md-aux-icon shrink-0 p-0.5"
+                  style={{ height: config.lineHeight }}
+                >
+                  <AuxIcon
+                    className={colorClass}
+                    style={{
+                      width: config.auxIconSize,
+                      height: config.auxIconSize,
+                    }}
+                  />
+                </div>
+              );
+            })()}
+
+          {tag && <Tag {...tag} />}
+
+          {editable && !editing && (
+            <div
+              className={cn(
+                "opal-content-md-edit-button",
+                config.editButtonPadding
+              )}
+            >
+              <Button
+                icon={SvgEdit}
+                prominence="internal"
+                size={config.editButtonSize}
+                tooltip="Edit"
+                tooltipSide="right"
+                onClick={startEditing}
+              />
+            </div>
+          )}
+        </div>
+
+        {description && (
+          <div className="opal-content-md-description font-secondary-body text-text-03">
+            {description}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export {
+  ContentMd,
+  type ContentMdProps,
+  type ContentMdSizePreset,
+  type ContentMdAuxIcon,
+};
diff --git a/web/lib/opal/src/layouts/Content/ContentSm.tsx b/web/lib/opal/src/layouts/Content/ContentSm.tsx
new file mode 100644
index 00000000000..ec5b1e8aa42
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/ContentSm.tsx
@@ -0,0 +1,129 @@
+"use client";
+
+import type { IconFunctionComponent } from "@opal/types";
+import { cn } from "@opal/utils";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ContentSmSizePreset = "main-content" | "main-ui" | "secondary";
+type ContentSmOrientation = "vertical" | "inline" | "reverse";
+type ContentSmProminence = "default" | "muted";
+
+interface ContentSmPresetConfig {
+  /** Icon width/height (CSS value). */
+  iconSize: string;
+  /** Tailwind padding class for the icon container. */
+  iconContainerPadding: string;
+  /** Tailwind font class for the title. */
+  titleFont: string;
+  /** Title line-height — also used as icon container min-height (CSS value). */
+  lineHeight: string;
+  /** Gap between icon container and title (CSS value). */
+  gap: string;
+}
+
+/** Props for {@link ContentSm}. Does not support editing or descriptions. */
+interface ContentSmProps {
+  /** Optional icon component. */
+  icon?: IconFunctionComponent;
+
+  /** Main title text (read-only — editing is not supported). */
+  title: string;
+
+  /** Size preset. Default: `"main-ui"`. */
+  sizePreset?: ContentSmSizePreset;
+
+  /** Layout orientation. Default: `"inline"`. */
+  orientation?: ContentSmOrientation;
+
+  /** Title prominence. Default: `"default"`. */
+  prominence?: ContentSmProminence;
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+const CONTENT_SM_PRESETS: Record<ContentSmSizePreset, ContentSmPresetConfig> = {
+  "main-content": {
+    iconSize: "1rem",
+    iconContainerPadding: "p-1",
+    titleFont: "font-main-content-body",
+    lineHeight: "1.5rem",
+    gap: "0.125rem",
+  },
+  "main-ui": {
+    iconSize: "1rem",
+    iconContainerPadding: "p-0.5",
+    titleFont: "font-main-ui-action",
+    lineHeight: "1.25rem",
+    gap: "0.25rem",
+  },
+  secondary: {
+    iconSize: "0.75rem",
+    iconContainerPadding: "p-0.5",
+    titleFont: "font-secondary-action",
+    lineHeight: "1rem",
+    gap: "0.125rem",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ContentSm
+// ---------------------------------------------------------------------------
+
+function ContentSm({
+  icon: Icon,
+  title,
+  sizePreset = "main-ui",
+  orientation = "inline",
+  prominence = "default",
+}: ContentSmProps) {
+  const config = CONTENT_SM_PRESETS[sizePreset];
+  const titleColorClass =
+    prominence === "muted" ? "text-text-03" : "text-text-04";
+
+  return (
+    <div
+      className="opal-content-sm"
+      data-orientation={orientation}
+      style={{ gap: config.gap }}
+    >
+      {Icon && (
+        <div
+          className={cn(
+            "opal-content-sm-icon-container shrink-0",
+            config.iconContainerPadding
+          )}
+          style={{ minHeight: config.lineHeight }}
+        >
+          <Icon
+            className="opal-content-sm-icon text-text-03"
+            style={{ width: config.iconSize, height: config.iconSize }}
+          />
+        </div>
+      )}
+
+      <span
+        className={cn(
+          "opal-content-sm-title",
+          config.titleFont,
+          titleColorClass
+        )}
+        style={{ height: config.lineHeight }}
+      >
+        {title}
+      </span>
+    </div>
+  );
+}
+
+export {
+  ContentSm,
+  type ContentSmProps,
+  type ContentSmSizePreset,
+  type ContentSmOrientation,
+  type ContentSmProminence,
+};
diff --git a/web/lib/opal/src/layouts/Content/ContentXl.tsx b/web/lib/opal/src/layouts/Content/ContentXl.tsx
new file mode 100644
index 00000000000..08b36fd56d3
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/ContentXl.tsx
@@ -0,0 +1,256 @@
+"use client";
+
+import { Button } from "@opal/components/buttons/Button/components";
+import type { SizeVariant } from "@opal/shared";
+import SvgEdit from "@opal/icons/edit";
+import type { IconFunctionComponent } from "@opal/types";
+import { cn } from "@opal/utils";
+import { useState } from "react";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ContentXlSizePreset = "headline" | "section";
+
+interface ContentXlPresetConfig {
+  /** Icon width/height (CSS value). */
+  iconSize: string;
+  /** Tailwind padding class for the icon container. */
+  iconContainerPadding: string;
+  /** More-icon-1 width/height (CSS value). */
+  moreIcon1Size: string;
+  /** Tailwind padding class for the more-icon-1 container. */
+  moreIcon1ContainerPadding: string;
+  /** More-icon-2 width/height (CSS value). */
+  moreIcon2Size: string;
+  /** Tailwind padding class for the more-icon-2 container. */
+  moreIcon2ContainerPadding: string;
+  /** Tailwind font class for the title. */
+  titleFont: string;
+  /** Title line-height — also used as icon container min-height (CSS value). */
+  lineHeight: string;
+  /** Button `size` prop for the edit button. Uses the shared `SizeVariant` scale. */
+  editButtonSize: SizeVariant;
+  /** Tailwind padding class for the edit button container. */
+  editButtonPadding: string;
+}
+
+interface ContentXlProps {
+  /** Optional icon component. */
+  icon?: IconFunctionComponent;
+
+  /** Main title text. */
+  title: string;
+
+  /** Optional description below the title. */
+  description?: string;
+
+  /** Enable inline editing of the title. */
+  editable?: boolean;
+
+  /** Called when the user commits an edit. */
+  onTitleChange?: (newTitle: string) => void;
+
+  /** Size preset. Default: `"headline"`. */
+  sizePreset?: ContentXlSizePreset;
+
+  /** Optional secondary icon rendered in the icon row. */
+  moreIcon1?: IconFunctionComponent;
+
+  /** Optional tertiary icon rendered in the icon row. */
+  moreIcon2?: IconFunctionComponent;
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+const CONTENT_XL_PRESETS: Record<ContentXlSizePreset, ContentXlPresetConfig> = {
+  headline: {
+    iconSize: "2rem",
+    iconContainerPadding: "p-0.5",
+    moreIcon1Size: "1rem",
+    moreIcon1ContainerPadding: "p-0.5",
+    moreIcon2Size: "2rem",
+    moreIcon2ContainerPadding: "p-0.5",
+    titleFont: "font-heading-h2",
+    lineHeight: "2.25rem",
+    editButtonSize: "md",
+    editButtonPadding: "p-1",
+  },
+  section: {
+    iconSize: "1.5rem",
+    iconContainerPadding: "p-0.5",
+    moreIcon1Size: "0.75rem",
+    moreIcon1ContainerPadding: "p-0.5",
+    moreIcon2Size: "1.5rem",
+    moreIcon2ContainerPadding: "p-0.5",
+    titleFont: "font-heading-h3",
+    lineHeight: "1.75rem",
+    editButtonSize: "sm",
+    editButtonPadding: "p-0.5",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ContentXl
+// ---------------------------------------------------------------------------
+
+function ContentXl({
+  sizePreset = "headline",
+  icon: Icon,
+  title,
+  description,
+  editable,
+  onTitleChange,
+  moreIcon1: MoreIcon1,
+  moreIcon2: MoreIcon2,
+}: ContentXlProps) {
+  const [editing, setEditing] = useState(false);
+  const [editValue, setEditValue] = useState(title);
+
+  const config = CONTENT_XL_PRESETS[sizePreset];
+
+  function startEditing() {
+    setEditValue(title);
+    setEditing(true);
+  }
+
+  function commit() {
+    const value = editValue.trim();
+    if (value && value !== title) onTitleChange?.(value);
+    setEditing(false);
+  }
+
+  return (
+    <div className="opal-content-xl">
+      {(Icon || MoreIcon1 || MoreIcon2) && (
+        <div className="opal-content-xl-icon-row">
+          {Icon && (
+            <div
+              className={cn(
+                "opal-content-xl-icon-container shrink-0",
+                config.iconContainerPadding
+              )}
+              style={{ minHeight: config.lineHeight }}
+            >
+              <Icon
+                className="opal-content-xl-icon"
+                style={{ width: config.iconSize, height: config.iconSize }}
+              />
+            </div>
+          )}
+
+          {MoreIcon1 && (
+            <div
+              className={cn(
+                "opal-content-xl-more-icon-container shrink-0",
+                config.moreIcon1ContainerPadding
+              )}
+            >
+              <MoreIcon1
+                className="opal-content-xl-icon"
+                style={{
+                  width: config.moreIcon1Size,
+                  height: config.moreIcon1Size,
+                }}
+              />
+            </div>
+          )}
+
+          {MoreIcon2 && (
+            <div
+              className={cn(
+                "opal-content-xl-more-icon-container shrink-0",
+                config.moreIcon2ContainerPadding
+              )}
+            >
+              <MoreIcon2
+                className="opal-content-xl-icon"
+                style={{
+                  width: config.moreIcon2Size,
+                  height: config.moreIcon2Size,
+                }}
+              />
+            </div>
+          )}
+        </div>
+      )}
+
+      <div className="opal-content-xl-body">
+        <div className="opal-content-xl-title-row">
+          {editing ? (
+            <div className="opal-content-xl-input-sizer">
+              <span
+                className={cn("opal-content-xl-input-mirror", config.titleFont)}
+              >
+                {editValue || "\u00A0"}
+              </span>
+              <input
+                className={cn(
+                  "opal-content-xl-input",
+                  config.titleFont,
+                  "text-text-04"
+                )}
+                value={editValue}
+                onChange={(e) => setEditValue(e.target.value)}
+                size={1}
+                autoFocus
+                onFocus={(e) => e.currentTarget.select()}
+                onBlur={commit}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") commit();
+                  if (e.key === "Escape") {
+                    setEditValue(title);
+                    setEditing(false);
+                  }
+                }}
+                style={{ height: config.lineHeight }}
+              />
+            </div>
+          ) : (
+            <span
+              className={cn(
+                "opal-content-xl-title",
+                config.titleFont,
+                "text-text-04",
+                editable && "cursor-pointer"
+              )}
+              onClick={editable ? startEditing : undefined}
+              style={{ height: config.lineHeight }}
+            >
+              {title}
+            </span>
+          )}
+
+          {editable && !editing && (
+            <div
+              className={cn(
+                "opal-content-xl-edit-button",
+                config.editButtonPadding
+              )}
+            >
+              <Button
+                icon={SvgEdit}
+                prominence="internal"
+                size={config.editButtonSize}
+                tooltip="Edit"
+                tooltipSide="right"
+                onClick={startEditing}
+              />
+            </div>
+          )}
+        </div>
+
+        {description && (
+          <div className="opal-content-xl-description font-secondary-body text-text-03">
+            {description}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export { ContentXl, type ContentXlProps, type ContentXlSizePreset };
diff --git a/web/lib/opal/src/layouts/Content/README.md b/web/lib/opal/src/layouts/Content/README.md
index bc711ed166e..b0c7e0b0f4c 100644
--- a/web/lib/opal/src/layouts/Content/README.md
+++ b/web/lib/opal/src/layouts/Content/README.md
@@ -8,14 +8,21 @@ A two-axis layout component for displaying icon + title + description rows. Rout
 
 ### `sizePreset` — controls sizing (icon, padding, gap, font)
 
-#### HeadingLayout presets
+#### ContentXl presets (variant="heading")
+
+| Preset | Icon | Icon padding | moreIcon1 | mI1 padding | moreIcon2 | mI2 padding | Title font | Line-height |
+|---|---|---|---|---|---|---|---|---|
+| `headline` | 2rem (32px) | `p-0.5` (2px) | 1rem (16px) | `p-0.5` (2px) | 2rem (32px) | `p-0.5` (2px) | `font-heading-h2` | 2.25rem (36px) |
+| `section` | 1.5rem (24px) | `p-0.5` (2px) | 0.75rem (12px) | `p-0.5` (2px) | 1.5rem (24px) | `p-0.5` (2px) | `font-heading-h3` | 1.75rem (28px) |
+
+#### ContentLg presets (variant="section")
 
 | Preset | Icon | Icon padding | Gap | Title font | Line-height |
 |---|---|---|---|---|---|
 | `headline` | 2rem (32px) | `p-0.5` (2px) | 0.25rem (4px) | `font-heading-h2` | 2.25rem (36px) |
-| `section` | 1.25rem (20px) | `p-1` (4px) | 0rem | `font-heading-h3` | 1.75rem (28px) |
+| `section` | 1.25rem (20px) | `p-1` (4px) | 0rem | `font-heading-h3-muted` | 1.75rem (28px) |
 
-#### LabelLayout presets
+#### ContentMd presets
 
 | Preset | Icon | Icon padding | Icon color | Gap | Title font | Line-height |
 |---|---|---|---|---|---|---|
@@ -29,18 +36,18 @@ A two-axis layout component for displaying icon + title + description rows. Rout
 
 | variant | Description |
 |---|---|
-| `heading` | Icon on **top** (flex-col) — HeadingLayout |
-| `section` | Icon **inline** (flex-row) — HeadingLayout or LabelLayout |
-| `body` | Body text layout — BodyLayout (future) |
+| `heading` | Icon on **top** (flex-col) — ContentXl |
+| `section` | Icon **inline** (flex-row) — ContentLg or ContentMd |
+| `body` | Body text layout — ContentSm |
 
 ### Valid Combinations -> Internal Routing
 
 | sizePreset | variant | Routes to |
 |---|---|---|
-| `headline` / `section` | `heading` | **HeadingLayout** (icon on top) |
-| `headline` / `section` | `section` | **HeadingLayout** (icon inline) |
-| `main-content` / `main-ui` / `secondary` | `section` | **LabelLayout** |
-| `main-content` / `main-ui` / `secondary` | `body` | BodyLayout (future) |
+| `headline` / `section` | `heading` | **ContentXl** (icon on top) |
+| `headline` / `section` | `section` | **ContentLg** (icon inline) |
+| `main-content` / `main-ui` / `secondary` | `section` | **ContentMd** |
+| `main-content` / `main-ui` / `secondary` | `body` | **ContentSm** |
 
 Invalid combinations (e.g. `sizePreset="headline" + variant="body"`) are excluded at the type level.
 
@@ -55,14 +62,20 @@ Invalid combinations (e.g. `sizePreset="headline" + variant="body"`) are exclude
 | `description` | `string` | — | Optional description below the title |
 | `editable` | `boolean` | `false` | Enable inline editing of the title |
 | `onTitleChange` | `(newTitle: string) => void` | — | Called when user commits an edit |
+| `moreIcon1` | `IconFunctionComponent` | — | Secondary icon in icon row (ContentXl only) |
+| `moreIcon2` | `IconFunctionComponent` | — | Tertiary icon in icon row (ContentXl only) |
 
 ## Internal Layouts
 
-### HeadingLayout
+### ContentXl
+
+For `headline` / `section` presets with `variant="heading"`. Icon row on top (flex-col), supports `moreIcon1` and `moreIcon2` in the icon row. Description is always `font-secondary-body text-text-03`.
 
-For `headline` / `section` presets. Supports `variant="heading"` (icon on top) and `variant="section"` (icon inline). Description is always `font-secondary-body text-text-03`.
+### ContentLg
 
-### LabelLayout
+For `headline` / `section` presets with `variant="section"`. Always inline (flex-row). Description is always `font-secondary-body text-text-03`.
+
+### ContentMd
 
 For `main-content` / `main-ui` / `secondary` presets. Always inline. Both `icon` and `description` are optional. Description is always `font-secondary-body text-text-03`.
 
@@ -72,7 +85,7 @@ For `main-content` / `main-ui` / `secondary` presets. Always inline. Both `icon`
 import { Content } from "@opal/layouts";
 import SvgSearch from "@opal/icons/search";
 
-// HeadingLayout — headline, icon on top
+// ContentXl — headline, icon on top
 <Content
   icon={SvgSearch}
   sizePreset="headline"
@@ -81,7 +94,17 @@ import SvgSearch from "@opal/icons/search";
   description="Configure your agent's behavior"
 />
 
-// HeadingLayout — section, icon inline
+// ContentXl — with more icons
+<Content
+  icon={SvgSearch}
+  sizePreset="headline"
+  variant="heading"
+  title="Agent Settings"
+  moreIcon1={SvgStar}
+  moreIcon2={SvgLock}
+/>
+
+// ContentLg — section, icon inline
 <Content
   icon={SvgSearch}
   sizePreset="section"
@@ -90,7 +113,7 @@ import SvgSearch from "@opal/icons/search";
   description="Connected integrations"
 />
 
-// LabelLayout — with icon and description
+// ContentMd — with icon and description
 <Content
   icon={SvgSearch}
   sizePreset="main-ui"
@@ -98,7 +121,7 @@ import SvgSearch from "@opal/icons/search";
   description="Agent system prompt"
 />
 
-// LabelLayout — title only (no icon, no description)
+// ContentMd — title only (no icon, no description)
 <Content
   sizePreset="main-content"
   title="Featured Agent"
diff --git a/web/lib/opal/src/layouts/Content/components.tsx b/web/lib/opal/src/layouts/Content/components.tsx
index 6bba887fe8b..b0a3660cd9b 100644
--- a/web/lib/opal/src/layouts/Content/components.tsx
+++ b/web/lib/opal/src/layouts/Content/components.tsx
@@ -1,21 +1,24 @@
 import "@opal/layouts/Content/styles.css";
 import {
-  BodyLayout,
-  type BodyOrientation,
-  type BodyProminence,
-} from "@opal/layouts/Content/BodyLayout";
+  ContentSm,
+  type ContentSmOrientation,
+  type ContentSmProminence,
+} from "@opal/layouts/Content/ContentSm";
 import {
-  HeadingLayout,
-  type HeadingLayoutProps,
-} from "@opal/layouts/Content/HeadingLayout";
+  ContentXl,
+  type ContentXlProps,
+} from "@opal/layouts/Content/ContentXl";
 import {
-  LabelLayout,
-  type LabelLayoutProps,
-} from "@opal/layouts/Content/LabelLayout";
+  ContentLg,
+  type ContentLgProps,
+} from "@opal/layouts/Content/ContentLg";
+import {
+  ContentMd,
+  type ContentMdProps,
+} from "@opal/layouts/Content/ContentMd";
 import type { TagProps } from "@opal/components/Tag/components";
 import type { IconFunctionComponent } from "@opal/types";
 import { widthVariants, type WidthVariant } from "@opal/shared";
-import { cn } from "@opal/utils";
 
 // ---------------------------------------------------------------------------
 // Shared types
@@ -62,14 +65,25 @@ interface ContentBaseProps {
 // Discriminated union: valid sizePreset × variant combinations
 // ---------------------------------------------------------------------------
 
-type HeadingContentProps = ContentBaseProps & {
+type XlContentProps = ContentBaseProps & {
   /** Size preset. Default: `"headline"`. */
   sizePreset?: "headline" | "section";
   /** Variant. Default: `"heading"` for heading-eligible presets. */
-  variant?: "heading" | "section";
+  variant?: "heading";
+  /** Optional secondary icon rendered in the icon row (ContentXl only). */
+  moreIcon1?: IconFunctionComponent;
+  /** Optional tertiary icon rendered in the icon row (ContentXl only). */
+  moreIcon2?: IconFunctionComponent;
+};
+
+type LgContentProps = ContentBaseProps & {
+  /** Size preset. Default: `"headline"`. */
+  sizePreset?: "headline" | "section";
+  /** Variant. */
+  variant: "section";
 };
 
-type LabelContentProps = ContentBaseProps & {
+type MdContentProps = ContentBaseProps & {
   sizePreset: "main-content" | "main-ui" | "secondary";
   variant?: "section";
   /** When `true`, renders "(Optional)" beside the title in the muted font variant. */
@@ -80,20 +94,24 @@ type LabelContentProps = ContentBaseProps & {
   tag?: TagProps;
 };
 
-/** BodyLayout does not support descriptions or inline editing. */
-type BodyContentProps = Omit<
+/** ContentSm does not support descriptions or inline editing. */
+type SmContentProps = Omit<
   ContentBaseProps,
   "description" | "editable" | "onTitleChange"
 > & {
   sizePreset: "main-content" | "main-ui" | "secondary";
   variant: "body";
   /** Layout orientation. Default: `"inline"`. */
-  orientation?: BodyOrientation;
+  orientation?: ContentSmOrientation;
   /** Title prominence. Default: `"default"`. */
-  prominence?: BodyProminence;
+  prominence?: ContentSmProminence;
 };
 
-type ContentProps = HeadingContentProps | LabelContentProps | BodyContentProps;
+type ContentProps =
+  | XlContentProps
+  | LgContentProps
+  | MdContentProps
+  | SmContentProps;
 
 // ---------------------------------------------------------------------------
 // Content — routes to the appropriate internal layout
@@ -111,34 +129,43 @@ function Content(props: ContentProps) {
 
   let layout: React.ReactNode = null;
 
-  // Heading layout: headline/section presets with heading/section variant
+  // ContentXl / ContentLg: headline/section presets
   if (sizePreset === "headline" || sizePreset === "section") {
-    layout = (
-      <HeadingLayout
-        sizePreset={sizePreset}
-        variant={variant as HeadingLayoutProps["variant"]}
-        {...rest}
-      />
-    );
+    if (variant === "heading") {
+      layout = (
+        <ContentXl
+          sizePreset={sizePreset}
+          {...(rest as Omit<ContentXlProps, "sizePreset">)}
+        />
+      );
+    } else {
+      layout = (
+        <ContentLg
+          sizePreset={sizePreset}
+          {...(rest as Omit<ContentLgProps, "sizePreset">)}
+        />
+      );
+    }
   }
 
-  // Label layout: main-content/main-ui/secondary with section variant
+  // ContentMd: main-content/main-ui/secondary with section/heading variant
+  // (variant defaults to "heading" when omitted on MdContentProps, so both arms are needed)
   else if (variant === "section" || variant === "heading") {
     layout = (
-      <LabelLayout
+      <ContentMd
         sizePreset={sizePreset}
-        {...(rest as Omit<LabelLayoutProps, "sizePreset">)}
+        {...(rest as Omit<ContentMdProps, "sizePreset">)}
       />
     );
   }
 
-  // Body layout: main-content/main-ui/secondary with body variant
+  // ContentSm: main-content/main-ui/secondary with body variant
   else if (variant === "body") {
     layout = (
-      <BodyLayout
+      <ContentSm
         sizePreset={sizePreset}
         {...(rest as Omit<
-          React.ComponentProps<typeof BodyLayout>,
+          React.ComponentProps<typeof ContentSm>,
           "sizePreset"
         >)}
       />
@@ -167,7 +194,8 @@ export {
   type ContentProps,
   type SizePreset,
   type ContentVariant,
-  type HeadingContentProps,
-  type LabelContentProps,
-  type BodyContentProps,
+  type XlContentProps,
+  type LgContentProps,
+  type MdContentProps,
+  type SmContentProps,
 };
diff --git a/web/lib/opal/src/layouts/Content/styles.css b/web/lib/opal/src/layouts/Content/styles.css
index e1621a66421..7aceb2305af 100644
--- a/web/lib/opal/src/layouts/Content/styles.css
+++ b/web/lib/opal/src/layouts/Content/styles.css
@@ -1,41 +1,145 @@
-/* ---------------------------------------------------------------------------
-   Content — HeadingLayout
+/* ===========================================================================
+   Content — ContentXl
 
-   Two icon placement modes (driven by variant):
-     left  (variant="section") : flex-row  — icon beside content
-     top   (variant="heading") : flex-col  — icon above content
+   Icon row on top (flex-col). Icon row contains main icon + optional
+   moreIcon1 / moreIcon2 in a flex-row.
 
    Sizing (icon size, gap, padding, font, line-height) is driven by the
    sizePreset prop via inline styles + Tailwind classes in the component.
+   =========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Layout — flex-col (icon row above body)
    --------------------------------------------------------------------------- */
 
+.opal-content-xl {
+  @apply flex flex-col items-start;
+}
+
 /* ---------------------------------------------------------------------------
-   Layout — icon placement
+   Icon row — flex-row containing main icon + more icons
    --------------------------------------------------------------------------- */
 
-.opal-content-heading {
-  @apply flex items-start;
+.opal-content-xl-icon-row {
+  @apply flex flex-row items-center;
 }
 
-.opal-content-heading[data-icon-placement="left"] {
-  @apply flex-row;
+/* ---------------------------------------------------------------------------
+   Icons
+   --------------------------------------------------------------------------- */
+
+.opal-content-xl-icon-container {
+  display: flex;
+  align-items: center;
+  justify-content: center;
 }
 
-.opal-content-heading[data-icon-placement="top"] {
-  @apply flex-col;
+.opal-content-xl-more-icon-container {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.opal-content-xl-icon {
+  color: var(--text-04);
+}
+
+/* ---------------------------------------------------------------------------
+   Body column
+   --------------------------------------------------------------------------- */
+
+.opal-content-xl-body {
+  @apply flex flex-1 flex-col items-start;
+  min-width: 0.0625rem;
+}
+
+/* ---------------------------------------------------------------------------
+   Title row — title (or input) + edit button
+   --------------------------------------------------------------------------- */
+
+.opal-content-xl-title-row {
+  @apply flex items-center w-full;
+  gap: 0.25rem;
+}
+
+.opal-content-xl-title {
+  @apply text-left overflow-hidden;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 1;
+  padding: 0 0.125rem;
+  min-width: 0.0625rem;
+}
+
+.opal-content-xl-input-sizer {
+  display: inline-grid;
+  align-items: stretch;
+}
+
+.opal-content-xl-input-sizer > * {
+  grid-area: 1 / 1;
+  padding: 0 0.125rem;
+  min-width: 0.0625rem;
+}
+
+.opal-content-xl-input-mirror {
+  visibility: hidden;
+  white-space: pre;
+}
+
+.opal-content-xl-input {
+  @apply bg-transparent outline-none border-none;
+}
+
+/* ---------------------------------------------------------------------------
+   Edit button — visible only on hover of the outer container
+   --------------------------------------------------------------------------- */
+
+.opal-content-xl-edit-button {
+  @apply opacity-0 transition-opacity shrink-0;
+}
+
+.opal-content-xl:hover .opal-content-xl-edit-button {
+  @apply opacity-100;
+}
+
+/* ---------------------------------------------------------------------------
+   Description
+   --------------------------------------------------------------------------- */
+
+.opal-content-xl-description {
+  @apply text-left w-full;
+  padding: 0 0.125rem;
+}
+
+/* ===========================================================================
+   Content — ContentLg
+
+   Always inline (flex-row) — icon beside content.
+
+   Sizing (icon size, gap, padding, font, line-height) is driven by the
+   sizePreset prop via inline styles + Tailwind classes in the component.
+   =========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Layout
+   --------------------------------------------------------------------------- */
+
+.opal-content-lg {
+  @apply flex flex-row items-start;
 }
 
 /* ---------------------------------------------------------------------------
    Icon
    --------------------------------------------------------------------------- */
 
-.opal-content-heading-icon-container {
+.opal-content-lg-icon-container {
   display: flex;
   align-items: center;
   justify-content: center;
 }
 
-.opal-content-heading-icon {
+.opal-content-lg-icon {
   color: var(--text-04);
 }
 
@@ -43,7 +147,7 @@
    Body column
    --------------------------------------------------------------------------- */
 
-.opal-content-heading-body {
+.opal-content-lg-body {
   @apply flex flex-1 flex-col items-start;
   min-width: 0.0625rem;
 }
@@ -52,12 +156,12 @@
    Title row — title (or input) + edit button
    --------------------------------------------------------------------------- */
 
-.opal-content-heading-title-row {
+.opal-content-lg-title-row {
   @apply flex items-center w-full;
   gap: 0.25rem;
 }
 
-.opal-content-heading-title {
+.opal-content-lg-title {
   @apply text-left overflow-hidden;
   display: -webkit-box;
   -webkit-box-orient: vertical;
@@ -66,23 +170,23 @@
   min-width: 0.0625rem;
 }
 
-.opal-content-heading-input-sizer {
+.opal-content-lg-input-sizer {
   display: inline-grid;
   align-items: stretch;
 }
 
-.opal-content-heading-input-sizer > * {
+.opal-content-lg-input-sizer > * {
   grid-area: 1 / 1;
   padding: 0 0.125rem;
   min-width: 0.0625rem;
 }
 
-.opal-content-heading-input-mirror {
+.opal-content-lg-input-mirror {
   visibility: hidden;
   white-space: pre;
 }
 
-.opal-content-heading-input {
+.opal-content-lg-input {
   @apply bg-transparent outline-none border-none;
 }
 
@@ -90,11 +194,11 @@
    Edit button — visible only on hover of the outer container
    --------------------------------------------------------------------------- */
 
-.opal-content-heading-edit-button {
+.opal-content-lg-edit-button {
   @apply opacity-0 transition-opacity shrink-0;
 }
 
-.opal-content-heading:hover .opal-content-heading-edit-button {
+.opal-content-lg:hover .opal-content-lg-edit-button {
   @apply opacity-100;
 }
 
@@ -102,13 +206,13 @@
    Description
    --------------------------------------------------------------------------- */
 
-.opal-content-heading-description {
+.opal-content-lg-description {
   @apply text-left w-full;
   padding: 0 0.125rem;
 }
 
 /* ===========================================================================
-   Content — LabelLayout
+   Content — ContentMd
 
    Always inline (flex-row). Icon color varies per sizePreset and is applied
    via Tailwind class from the component.
@@ -118,7 +222,7 @@
    Layout
    --------------------------------------------------------------------------- */
 
-.opal-content-label {
+.opal-content-md {
   @apply flex flex-row items-start;
 }
 
@@ -126,7 +230,7 @@
    Icon
    --------------------------------------------------------------------------- */
 
-.opal-content-label-icon-container {
+.opal-content-md-icon-container {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -136,7 +240,7 @@
    Body column
    --------------------------------------------------------------------------- */
 
-.opal-content-label-body {
+.opal-content-md-body {
   @apply flex flex-1 flex-col items-start;
   min-width: 0.0625rem;
 }
@@ -145,12 +249,12 @@
    Title row — title (or input) + edit button
    --------------------------------------------------------------------------- */
 
-.opal-content-label-title-row {
+.opal-content-md-title-row {
   @apply flex items-center w-full;
   gap: 0.25rem;
 }
 
-.opal-content-label-title {
+.opal-content-md-title {
   @apply text-left overflow-hidden;
   display: -webkit-box;
   -webkit-box-orient: vertical;
@@ -159,23 +263,23 @@
   min-width: 0.0625rem;
 }
 
-.opal-content-label-input-sizer {
+.opal-content-md-input-sizer {
   display: inline-grid;
   align-items: stretch;
 }
 
-.opal-content-label-input-sizer > * {
+.opal-content-md-input-sizer > * {
   grid-area: 1 / 1;
   padding: 0 0.125rem;
   min-width: 0.0625rem;
 }
 
-.opal-content-label-input-mirror {
+.opal-content-md-input-mirror {
   visibility: hidden;
   white-space: pre;
 }
 
-.opal-content-label-input {
+.opal-content-md-input {
   @apply bg-transparent outline-none border-none;
 }
 
@@ -183,7 +287,7 @@
    Aux icon
    --------------------------------------------------------------------------- */
 
-.opal-content-label-aux-icon {
+.opal-content-md-aux-icon {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -193,11 +297,11 @@
    Edit button — visible only on hover of the outer container
    --------------------------------------------------------------------------- */
 
-.opal-content-label-edit-button {
+.opal-content-md-edit-button {
   @apply opacity-0 transition-opacity shrink-0;
 }
 
-.opal-content-label:hover .opal-content-label-edit-button {
+.opal-content-md:hover .opal-content-md-edit-button {
   @apply opacity-100;
 }
 
@@ -205,13 +309,13 @@
    Description
    --------------------------------------------------------------------------- */
 
-.opal-content-label-description {
+.opal-content-md-description {
   @apply text-left w-full;
   padding: 0 0.125rem;
 }
 
 /* ===========================================================================
-   Content — BodyLayout
+   Content — ContentSm
 
    Three orientation modes (driven by orientation prop):
      inline  : flex-row         — icon left, title right
@@ -226,19 +330,19 @@
    Layout — orientation
    --------------------------------------------------------------------------- */
 
-.opal-content-body {
+.opal-content-sm {
   @apply flex items-start;
 }
 
-.opal-content-body[data-orientation="inline"] {
+.opal-content-sm[data-orientation="inline"] {
   @apply flex-row;
 }
 
-.opal-content-body[data-orientation="vertical"] {
+.opal-content-sm[data-orientation="vertical"] {
   @apply flex-col;
 }
 
-.opal-content-body[data-orientation="reverse"] {
+.opal-content-sm[data-orientation="reverse"] {
   @apply flex-row-reverse;
 }
 
@@ -246,7 +350,7 @@
    Icon
    --------------------------------------------------------------------------- */
 
-.opal-content-body-icon-container {
+.opal-content-sm-icon-container {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -256,7 +360,7 @@
    Title
    --------------------------------------------------------------------------- */
 
-.opal-content-body-title {
+.opal-content-sm-title {
   @apply text-left overflow-hidden;
   display: -webkit-box;
   -webkit-box-orient: vertical;
diff --git a/web/lib/opal/src/layouts/README.md b/web/lib/opal/src/layouts/README.md
index c357b740989..b63c9cec179 100644
--- a/web/lib/opal/src/layouts/README.md
+++ b/web/lib/opal/src/layouts/README.md
@@ -8,7 +8,7 @@ Layout primitives for composing icon + title + description rows. These component
 
 | Component | Description | Docs |
 |---|---|---|
-| [`Content`](./Content/README.md) | Icon + title + description row. Routes to an internal layout (`HeadingLayout`, `LabelLayout`, or `BodyLayout`) based on `sizePreset` and `variant`. | [Content README](./Content/README.md) |
+| [`Content`](./Content/README.md) | Icon + title + description row. Routes to an internal layout (`ContentXl`, `ContentLg`, `ContentMd`, or `ContentSm`) based on `sizePreset` and `variant`. | [Content README](./Content/README.md) |
 | [`ContentAction`](./ContentAction/README.md) | Wraps `Content` in a flex-row with an optional `rightChildren` slot for action buttons. Adds padding alignment via the shared `SizeVariant` scale. | [ContentAction README](./ContentAction/README.md) |
 
 ## Quick Start
@@ -88,6 +88,7 @@ These are not exported — `Content` routes to them automatically:
 
 | Layout | Used when | File |
 |---|---|---|
-| `HeadingLayout` | `sizePreset` is `headline` or `section` | `Content/HeadingLayout.tsx` |
-| `LabelLayout` | `sizePreset` is `main-content`, `main-ui`, or `secondary` with `variant="section"` | `Content/LabelLayout.tsx` |
-| `BodyLayout` | `variant="body"` | `Content/BodyLayout.tsx` |
+| `ContentXl` | `sizePreset` is `headline` or `section` with `variant="heading"` | `Content/ContentXl.tsx` |
+| `ContentLg` | `sizePreset` is `headline` or `section` with `variant="section"` | `Content/ContentLg.tsx` |
+| `ContentMd` | `sizePreset` is `main-content`, `main-ui`, or `secondary` with `variant="section"` | `Content/ContentMd.tsx` |
+| `ContentSm` | `variant="body"` | `Content/ContentSm.tsx` |
diff --git a/web/lib/opal/src/shared.ts b/web/lib/opal/src/shared.ts
index 63a9b51440d..0559d17c0e2 100644
--- a/web/lib/opal/src/shared.ts
+++ b/web/lib/opal/src/shared.ts
@@ -16,7 +16,7 @@
 //   - Interactive.Container  (height + min-width + padding)
 //   - Button                 (icon sizing)
 //   - ContentAction          (padding only)
-//   - Content (HeadingLayout / LabelLayout)  (edit-button size)
+//   - Content (ContentXl / ContentLg / ContentMd)  (edit-button size)
 // ---------------------------------------------------------------------------
 
 /**

From 16c07c8756e3cbc396109fa42202c6ef6d99ab65 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 09:03:24 -0800
Subject: [PATCH 005/267] feat(desktop): option to hide alt-menu (#8882)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
---
 desktop/src-tauri/src/main.rs | 305 ++++++++++++++++++++++++++++++++--
 1 file changed, 295 insertions(+), 10 deletions(-)

diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
index 379b8a8dbf5..392d36bb7dd 100644
--- a/desktop/src-tauri/src/main.rs
+++ b/desktop/src-tauri/src/main.rs
@@ -40,6 +40,8 @@ const TRAY_MENU_OPEN_APP_ID: &str = "tray_open_app";
 const TRAY_MENU_OPEN_CHAT_ID: &str = "tray_open_chat";
 const TRAY_MENU_SHOW_IN_BAR_ID: &str = "tray_show_in_menu_bar";
 const TRAY_MENU_QUIT_ID: &str = "tray_quit";
+const MENU_SHOW_MENU_BAR_ID: &str = "show_menu_bar";
+const MENU_HIDE_DECORATIONS_ID: &str = "hide_window_decorations";
 const CHAT_LINK_INTERCEPT_SCRIPT: &str = r##"
 (() => {
   if (window.__ONYX_CHAT_LINK_INTERCEPT_INSTALLED__) {
@@ -171,25 +173,92 @@ const CHAT_LINK_INTERCEPT_SCRIPT: &str = r##"
 })();
 "##;
 
+#[cfg(not(target_os = "macos"))]
+const MENU_KEY_HANDLER_SCRIPT: &str = r#"
+(() => {
+  if (window.__ONYX_MENU_KEY_HANDLER__) return;
+  window.__ONYX_MENU_KEY_HANDLER__ = true;
+
+  let altHeld = false;
+
+  function invoke(cmd) {
+    const fn_ =
+      window.__TAURI__?.core?.invoke || window.__TAURI_INTERNALS__?.invoke;
+    if (typeof fn_ === 'function') fn_(cmd);
+  }
+
+  function releaseAltAndHideMenu() {
+    if (!altHeld) {
+      return;
+    }
+    altHeld = false;
+    invoke('hide_menu_bar_temporary');
+  }
+
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Alt') {
+      if (!altHeld) {
+        altHeld = true;
+        invoke('show_menu_bar_temporarily');
+      }
+      return;
+    }
+    if (e.altKey && e.key === 'F1') {
+      e.preventDefault();
+      e.stopPropagation();
+      altHeld = false;
+      invoke('toggle_menu_bar');
+      return;
+    }
+  }, true);
+
+  document.addEventListener('keyup', (e) => {
+    if (e.key === 'Alt' && altHeld) {
+      releaseAltAndHideMenu();
+    }
+  }, true);
+
+  window.addEventListener('blur', () => {
+    releaseAltAndHideMenu();
+  });
+
+  document.addEventListener('visibilitychange', () => {
+    if (document.hidden) {
+      releaseAltAndHideMenu();
+    }
+  });
+})();
+"#;
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AppConfig {
-    /// The Onyx server URL (default: https://cloud.onyx.app)
     pub server_url: String,
 
-    /// Optional: Custom window title
     #[serde(default = "default_window_title")]
     pub window_title: String,
+
+    #[serde(default = "default_show_menu_bar")]
+    pub show_menu_bar: bool,
+
+    #[serde(default)]
+    pub hide_window_decorations: bool,
 }
 
 fn default_window_title() -> String {
     "Onyx".to_string()
 }
 
+fn default_show_menu_bar() -> bool {
+    true
+}
+
 impl Default for AppConfig {
     fn default() -> Self {
         Self {
             server_url: DEFAULT_SERVER_URL.to_string(),
             window_title: default_window_title(),
+            show_menu_bar: true,
+            hide_window_decorations: false,
         }
     }
 }
@@ -247,6 +316,7 @@ struct ConfigState {
     config: RwLock<AppConfig>,
     config_initialized: RwLock<bool>,
     app_base_url: RwLock<Option<Url>>,
+    menu_temporarily_visible: RwLock<bool>,
 }
 
 fn focus_main_window(app: &AppHandle) {
@@ -301,6 +371,7 @@ fn trigger_new_window(app: &AppHandle) {
                 inject_titlebar(window.clone());
             }
 
+            apply_settings_to_window(&handle, &window);
             let _ = window.set_focus();
         }
     });
@@ -577,18 +648,15 @@ async fn new_window(app: AppHandle, state: tauri::State<'_, ConfigState>) -> Res
     #[cfg(target_os = "linux")]
     let builder = builder.background_color(tauri::window::Color(0x1a, 0x1a, 0x2e, 0xff));
 
+    let window = builder.build().map_err(|e| e.to_string())?;
+
     #[cfg(target_os = "macos")]
     {
-        let window = builder.build().map_err(|e| e.to_string())?;
-        // Apply vibrancy effect and inject titlebar
         let _ = apply_vibrancy(&window, NSVisualEffectMaterial::Sidebar, None, None);
         inject_titlebar(window.clone());
     }
 
-    #[cfg(not(target_os = "macos"))]
-    {
-        let _window = builder.build().map_err(|e| e.to_string())?;
-    }
+    apply_settings_to_window(&app, &window);
 
     Ok(())
 }
@@ -624,6 +692,142 @@ async fn start_drag_window(window: tauri::Window) -> Result<(), String> {
     window.start_dragging().map_err(|e| e.to_string())
 }
 
+// ============================================================================
+// Window Settings
+// ============================================================================
+
+fn find_check_menu_item(
+    app: &AppHandle,
+    id: &str,
+) -> Option<CheckMenuItem<tauri::Wry>> {
+    let menu = app.menu()?;
+    for item in menu.items().ok()? {
+        if let Some(submenu) = item.as_submenu() {
+            for sub_item in submenu.items().ok()? {
+                if let Some(check) = sub_item.as_check_menuitem() {
+                    if check.id().as_ref() == id {
+                        return Some(check.clone());
+                    }
+                }
+            }
+        }
+    }
+    None
+}
+
+fn apply_settings_to_window(app: &AppHandle, window: &tauri::WebviewWindow) {
+    if cfg!(target_os = "macos") {
+        return;
+    }
+    let state = app.state::<ConfigState>();
+    let config = state.config.read().unwrap();
+    let temp_visible = *state.menu_temporarily_visible.read().unwrap();
+    if !config.show_menu_bar && !temp_visible {
+        let _ = window.hide_menu();
+    }
+    if config.hide_window_decorations {
+        let _ = window.set_decorations(false);
+    }
+}
+
+fn handle_menu_bar_toggle(app: &AppHandle) {
+    if cfg!(target_os = "macos") {
+        return;
+    }
+    let state = app.state::<ConfigState>();
+    let show = {
+        let mut config = state.config.write().unwrap();
+        config.show_menu_bar = !config.show_menu_bar;
+        let _ = save_config(&config);
+        config.show_menu_bar
+    };
+
+    *state.menu_temporarily_visible.write().unwrap() = false;
+
+    for (_, window) in app.webview_windows() {
+        if show {
+            let _ = window.show_menu();
+        } else {
+            let _ = window.hide_menu();
+        }
+    }
+}
+
+fn handle_decorations_toggle(app: &AppHandle) {
+    if cfg!(target_os = "macos") {
+        return;
+    }
+    let state = app.state::<ConfigState>();
+    let hide = {
+        let mut config = state.config.write().unwrap();
+        config.hide_window_decorations = !config.hide_window_decorations;
+        let _ = save_config(&config);
+        config.hide_window_decorations
+    };
+
+    for (_, window) in app.webview_windows() {
+        let _ = window.set_decorations(!hide);
+    }
+}
+
+#[tauri::command]
+fn toggle_menu_bar(app: AppHandle) {
+    if cfg!(target_os = "macos") {
+        return;
+    }
+    handle_menu_bar_toggle(&app);
+
+    let state = app.state::<ConfigState>();
+    let checked = state.config.read().unwrap().show_menu_bar;
+    if let Some(check) = find_check_menu_item(&app, MENU_SHOW_MENU_BAR_ID) {
+        let _ = check.set_checked(checked);
+    }
+}
+
+#[tauri::command]
+fn show_menu_bar_temporarily(app: AppHandle) {
+    if cfg!(target_os = "macos") {
+        return;
+    }
+    let state = app.state::<ConfigState>();
+    if state.config.read().unwrap().show_menu_bar {
+        return;
+    }
+
+    let mut temp = state.menu_temporarily_visible.write().unwrap();
+    if *temp {
+        return;
+    }
+    *temp = true;
+    drop(temp);
+
+    for (_, window) in app.webview_windows() {
+        let _ = window.show_menu();
+    }
+}
+
+#[tauri::command]
+fn hide_menu_bar_temporary(app: AppHandle) {
+    if cfg!(target_os = "macos") {
+        return;
+    }
+    let state = app.state::<ConfigState>();
+    let mut temp = state.menu_temporarily_visible.write().unwrap();
+    if !*temp {
+        return;
+    }
+    *temp = false;
+    drop(temp);
+
+    if state.config.read().unwrap().show_menu_bar {
+        return;
+    }
+
+    for (_, window) in app.webview_windows() {
+        let _ = window.hide_menu();
+    }
+}
+
 // ============================================================================
 // Menu Setup
 // ============================================================================
@@ -667,6 +871,59 @@ fn setup_app_menu(app: &AppHandle) -> tauri::Result<()> {
         menu.prepend(&file_menu)?;
     }
 
+    #[cfg(not(target_os = "macos"))]
+    {
+        let config = app.state::<ConfigState>();
+        let config_guard = config.config.read().unwrap();
+
+        let show_menu_bar_item = CheckMenuItem::with_id(
+            app,
+            MENU_SHOW_MENU_BAR_ID,
+            "Show Menu Bar",
+            true,
+            config_guard.show_menu_bar,
+            None::<&str>,
+        )?;
+
+        let hide_decorations_item = CheckMenuItem::with_id(
+            app,
+            MENU_HIDE_DECORATIONS_ID,
+            "Hide Window Decorations",
+            true,
+            config_guard.hide_window_decorations,
+            None::<&str>,
+        )?;
+
+        drop(config_guard);
+
+        if let Some(window_menu) = menu
+            .items()?
+            .into_iter()
+            .filter_map(|item| item.as_submenu().cloned())
+            .find(|submenu| submenu.text().ok().as_deref() == Some("Window"))
+        {
+            window_menu.append(&show_menu_bar_item)?;
+            window_menu.append(&hide_decorations_item)?;
+        } else {
+            let window_menu = SubmenuBuilder::new(app, "Window")
+                .item(&show_menu_bar_item)
+                .item(&hide_decorations_item)
+                .build()?;
+
+            let items = menu.items()?;
+            let help_idx = items
+                .iter()
+                .position(|item| {
+                    item.as_submenu()
+                        .and_then(|s| s.text().ok())
+                        .as_deref()
+                        == Some("Help")
+                })
+                .unwrap_or(items.len());
+            menu.insert(&window_menu, help_idx)?;
+        }
+    }
+
     if let Some(help_menu) = menu
         .get(HELP_SUBMENU_ID)
         .and_then(|item| item.as_submenu().cloned())
@@ -801,6 +1058,7 @@ fn main() {
             config: RwLock::new(config),
             config_initialized: RwLock::new(config_initialized),
             app_base_url: RwLock::new(None),
+            menu_temporarily_visible: RwLock::new(false),
         })
         .invoke_handler(tauri::generate_handler![
             get_server_url,
@@ -816,13 +1074,18 @@ fn main() {
             go_forward,
             new_window,
             reset_config,
-            start_drag_window
+            start_drag_window,
+            toggle_menu_bar,
+            show_menu_bar_temporarily,
+            hide_menu_bar_temporary
         ])
         .on_menu_event(|app, event| match event.id().as_ref() {
             "open_docs" => open_docs(),
             "new_chat" => trigger_new_chat(app),
             "new_window" => trigger_new_window(app),
             "open_settings" => open_settings(app),
+            "show_menu_bar" => handle_menu_bar_toggle(app),
+            "hide_window_decorations" => handle_decorations_toggle(app),
             _ => {}
         })
         .setup(move |app| {
@@ -855,6 +1118,8 @@ fn main() {
                 #[cfg(target_os = "macos")]
                 inject_titlebar(window.clone());
 
+                apply_settings_to_window(&app_handle, &window);
+
                 let _ = window.set_focus();
             }
 
@@ -863,7 +1128,27 @@ fn main() {
         .on_page_load(|webview: &Webview, _payload: &PageLoadPayload| {
             inject_chat_link_intercept(webview);
 
-            // Re-inject titlebar after every navigation/page load (macOS only)
+            #[cfg(not(target_os = "macos"))]
+            {
+                let _ = webview.eval(MENU_KEY_HANDLER_SCRIPT);
+
+                let app = webview.app_handle();
+                let state = app.state::<ConfigState>();
+                let config = state.config.read().unwrap();
+                let temp_visible = *state.menu_temporarily_visible.read().unwrap();
+                let label = webview.label().to_string();
+                if !config.show_menu_bar && !temp_visible {
+                    if let Some(win) = app.get_webview_window(&label) {
+                        let _ = win.hide_menu();
+                    }
+                }
+                if config.hide_window_decorations {
+                    if let Some(win) = app.get_webview_window(&label) {
+                        let _ = win.set_decorations(false);
+                    }
+                }
+            }
+
             #[cfg(target_os = "macos")]
             let _ = webview.eval(TITLEBAR_SCRIPT);
         })

From 4d2aa096549efaf835ad8f643fa36fed9a96f76a Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 2 Mar 2026 09:20:23 -0800
Subject: [PATCH 006/267] feat: infinite chat session sidebar scroll (#8874)

---
 backend/onyx/db/chat.py                       |   4 +
 .../server/query_and_chat/chat_backend.py     |  18 +-
 backend/onyx/server/query_and_chat/models.py  |   1 +
 .../sidebar/ChatSessionMorePopup.tsx          |  11 +-
 web/src/hooks/useChatSessions.ts              | 171 ++++++++++++++----
 web/src/layouts/app-layouts.tsx               |  12 +-
 .../skeletons/SidebarTabSkeleton.tsx          |  22 +++
 web/src/sections/sidebar/AppSidebar.tsx       |  83 ++++++++-
 web/src/sections/sidebar/ChatButton.tsx       |   3 +-
 9 files changed, 274 insertions(+), 51 deletions(-)
 create mode 100644 web/src/refresh-components/skeletons/SidebarTabSkeleton.tsx

diff --git a/backend/onyx/db/chat.py b/backend/onyx/db/chat.py
index 2ca7e5a2a24..ac30bc7b45a 100644
--- a/backend/onyx/db/chat.py
+++ b/backend/onyx/db/chat.py
@@ -98,6 +98,7 @@ def get_chat_sessions_by_user(
     db_session: Session,
     include_onyxbot_flows: bool = False,
     limit: int = 50,
+    before: datetime | None = None,
     project_id: int | None = None,
     only_non_project_chats: bool = False,
     include_failed_chats: bool = False,
@@ -112,6 +113,9 @@ def get_chat_sessions_by_user(
     if deleted is not None:
         stmt = stmt.where(ChatSession.deleted == deleted)
 
+    if before is not None:
+        stmt = stmt.where(ChatSession.time_updated < before)
+
     if limit:
         stmt = stmt.limit(limit)
 
diff --git a/backend/onyx/server/query_and_chat/chat_backend.py b/backend/onyx/server/query_and_chat/chat_backend.py
index d1729f111d9..97daf47b5bb 100644
--- a/backend/onyx/server/query_and_chat/chat_backend.py
+++ b/backend/onyx/server/query_and_chat/chat_backend.py
@@ -152,10 +152,20 @@ def get_user_chat_sessions(
     project_id: int | None = None,
     only_non_project_chats: bool = True,
     include_failed_chats: bool = False,
+    page_size: int = Query(default=50, ge=1, le=100),
+    before: str | None = Query(default=None),
 ) -> ChatSessionsResponse:
     user_id = user.id
 
     try:
+        before_dt = (
+            datetime.datetime.fromisoformat(before) if before is not None else None
+        )
+    except ValueError:
+        raise HTTPException(status_code=422, detail="Invalid 'before' timestamp format")
+
+    try:
+        # Fetch one extra to determine if there are more results
         chat_sessions = get_chat_sessions_by_user(
             user_id=user_id,
             deleted=False,
@@ -163,11 +173,16 @@ def get_user_chat_sessions(
             project_id=project_id,
             only_non_project_chats=only_non_project_chats,
             include_failed_chats=include_failed_chats,
+            limit=page_size + 1,
+            before=before_dt,
         )
 
     except ValueError:
         raise ValueError("Chat session does not exist or has been deleted")
 
+    has_more = len(chat_sessions) > page_size
+    chat_sessions = chat_sessions[:page_size]
+
     return ChatSessionsResponse(
         sessions=[
             ChatSessionDetails(
@@ -181,7 +196,8 @@ def get_user_chat_sessions(
                 current_temperature_override=chat.temperature_override,
             )
             for chat in chat_sessions
-        ]
+        ],
+        has_more=has_more,
     )
 
 
diff --git a/backend/onyx/server/query_and_chat/models.py b/backend/onyx/server/query_and_chat/models.py
index 776dbbaa79a..76a4afd4ae0 100644
--- a/backend/onyx/server/query_and_chat/models.py
+++ b/backend/onyx/server/query_and_chat/models.py
@@ -192,6 +192,7 @@ def from_model(cls, model: ChatSession) -> "ChatSessionDetails":
 
 class ChatSessionsResponse(BaseModel):
     sessions: list[ChatSessionDetails]
+    has_more: bool = False
 
 
 class ChatMessageDetail(BaseModel):
diff --git a/web/src/components/sidebar/ChatSessionMorePopup.tsx b/web/src/components/sidebar/ChatSessionMorePopup.tsx
index cbc92a2b391..464e1fb7610 100644
--- a/web/src/components/sidebar/ChatSessionMorePopup.tsx
+++ b/web/src/components/sidebar/ChatSessionMorePopup.tsx
@@ -52,7 +52,7 @@ export function ChatSessionMorePopup({
 }: ChatSessionMorePopupProps) {
   const [popoverOpen, setPopoverOpen] = useState(false);
   const [isDeleteModalOpen, setIsDeleteModalOpen] = useState(false);
-  const { refreshChatSessions } = useChatSessions();
+  const { refreshChatSessions, removeSession } = useChatSessions();
   const { fetchProjects, projects } = useProjectsContext();
 
   const [pendingMoveProjectId, setPendingMoveProjectId] = useState<
@@ -79,13 +79,20 @@ export function ChatSessionMorePopup({
     async (e: React.MouseEvent<HTMLButtonElement>) => {
       e.stopPropagation();
       await deleteChatSession(chatSession.id);
+      removeSession(chatSession.id);
       await refreshChatSessions();
       await fetchProjects();
       setIsDeleteModalOpen(false);
       setPopoverOpen(false);
       afterDelete?.();
     },
-    [chatSession, refreshChatSessions, fetchProjects, afterDelete]
+    [
+      chatSession,
+      refreshChatSessions,
+      removeSession,
+      fetchProjects,
+      afterDelete,
+    ]
   );
 
   const performMove = useCallback(
diff --git a/web/src/hooks/useChatSessions.ts b/web/src/hooks/useChatSessions.ts
index aeda60a7e98..96bb2c57c4f 100644
--- a/web/src/hooks/useChatSessions.ts
+++ b/web/src/hooks/useChatSessions.ts
@@ -1,7 +1,13 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
-import useSWR, { KeyedMutator } from "swr";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import useSWRInfinite from "swr/infinite";
 import { ChatSession, ChatSessionSharedStatus } from "@/app/app/interfaces";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
@@ -9,8 +15,12 @@ import useAppFocus from "./useAppFocus";
 import { useAgents } from "./useAgents";
 import { DEFAULT_ASSISTANT_ID } from "@/lib/constants";
 
+const PAGE_SIZE = 50;
+const MIN_LOADING_DURATION_MS = 500;
+
 interface ChatSessionsResponse {
   sessions: ChatSession[];
+  has_more: boolean;
 }
 
 export interface PendingChatSessionParams {
@@ -26,17 +36,24 @@ interface UseChatSessionsOutput {
   agentForCurrentChatSession: MinimalPersonaSnapshot | null;
   isLoading: boolean;
   error: any;
-  refreshChatSessions: KeyedMutator<ChatSessionsResponse>;
+  refreshChatSessions: () => Promise<ChatSessionsResponse[] | undefined>;
   addPendingChatSession: (params: PendingChatSessionParams) => void;
+  removeSession: (sessionId: string) => void;
+  hasMore: boolean;
+  isLoadingMore: boolean;
+  loadMore: () => void;
 }
 
-// Module-level store for pending chat sessions
-// This persists across SWR revalidations and component re-renders
-// Pending sessions are shown in the sidebar until the server returns them
+// ---------------------------------------------------------------------------
+// Shared module-level store for pending chat sessions
+// ---------------------------------------------------------------------------
+// Pending sessions are optimistic new sessions shown in the sidebar before
+// the server returns them. This must be module-level so all hook instances
+// (sidebar, ChatButton, etc.) share the same state.
+
 const pendingSessionsStore = {
   sessions: new Map<string, ChatSession>(),
   listeners: new Set<() => void>(),
-  // Cached snapshot to avoid creating new array references on every call
   cachedSnapshot: [] as ChatSession[],
 
   add(session: ChatSession) {
@@ -74,7 +91,7 @@ const pendingSessionsStore = {
   },
 };
 
-// Stable empty array for SSR - must be defined outside component to avoid infinite loop
+// Stable empty array for SSR
 const EMPTY_SESSIONS: ChatSession[] = [];
 
 function usePendingSessions(): ChatSession[] {
@@ -85,6 +102,10 @@ function usePendingSessions(): ChatSession[] {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Helper hooks
+// ---------------------------------------------------------------------------
+
 function useFindAgentForCurrentChatSession(
   currentChatSession: ChatSession | null
 ): MinimalPersonaSnapshot | null {
@@ -111,35 +132,102 @@ function useFindAgentForCurrentChatSession(
   return agents.find((agent) => agent.id === agentIdToFind) ?? null;
 }
 
+// ---------------------------------------------------------------------------
+// Main hook
+// ---------------------------------------------------------------------------
+
 export default function useChatSessions(): UseChatSessionsOutput {
-  const { data, error, mutate } = useSWR<ChatSessionsResponse>(
-    "/api/chat/get-user-chat-sessions",
+  const getKey = (
+    pageIndex: number,
+    previousPageData: ChatSessionsResponse | null
+  ): string | null => {
+    // No more pages
+    if (previousPageData && !previousPageData.has_more) return null;
+
+    // First page — no cursor
+    if (pageIndex === 0) {
+      return `/api/chat/get-user-chat-sessions?page_size=${PAGE_SIZE}`;
+    }
+
+    // Subsequent pages — cursor from the last session of the previous page
+    const lastSession =
+      previousPageData!.sessions[previousPageData!.sessions.length - 1];
+    if (!lastSession) return null;
+
+    const params = new URLSearchParams({
+      page_size: PAGE_SIZE.toString(),
+      before: lastSession.time_updated,
+    });
+    return `/api/chat/get-user-chat-sessions?${params.toString()}`;
+  };
+
+  const { data, error, setSize, mutate } = useSWRInfinite<ChatSessionsResponse>(
+    getKey,
     errorHandlingFetcher,
     {
       revalidateOnFocus: false,
+      revalidateFirstPage: true,
+      revalidateAll: false,
       dedupingInterval: 30000,
     }
   );
 
   const appFocus = useAppFocus();
   const pendingSessions = usePendingSessions();
-  const fetchedSessions = data?.sessions ?? [];
+
+  // Flatten all pages into a single session list
+  const allFetchedSessions = useMemo(
+    () => (data ? data.flatMap((page) => page.sessions) : []),
+    [data]
+  );
+
+  // hasMore: check the last loaded page
+  const hasMore = useMemo(() => {
+    if (!data || data.length === 0) return false;
+    const lastPage = data[data.length - 1];
+    return lastPage ? lastPage.has_more : false;
+  }, [data]);
+
+  const [isLoadingMore, setIsLoadingMore] = useState(false);
+
+  const loadMore = useCallback(async () => {
+    if (isLoadingMore || !hasMore) return;
+
+    setIsLoadingMore(true);
+    const loadStart = Date.now();
+
+    try {
+      await setSize((s) => s + 1);
+
+      // Enforce minimum loading duration to avoid skeleton flash
+      const elapsed = Date.now() - loadStart;
+      if (elapsed < MIN_LOADING_DURATION_MS) {
+        await new Promise((r) =>
+          setTimeout(r, MIN_LOADING_DURATION_MS - elapsed)
+        );
+      }
+    } catch (err) {
+      console.error("Failed to load more chat sessions:", err);
+    } finally {
+      setIsLoadingMore(false);
+    }
+  }, [isLoadingMore, hasMore, setSize]);
 
   // Clean up pending sessions that now appear in fetched data
   // (they now have messages and the server returns them)
   useEffect(() => {
-    const fetchedIds = new Set(fetchedSessions.map((s) => s.id));
+    const fetchedIds = new Set(allFetchedSessions.map((s) => s.id));
     pendingSessions.forEach((pending) => {
       if (fetchedIds.has(pending.id)) {
         pendingSessionsStore.remove(pending.id);
       }
     });
-  }, [fetchedSessions, pendingSessions]);
+  }, [allFetchedSessions, pendingSessions]);
 
-  // Merge fetched sessions with pending sessions
-  // This ensures pending sessions persist across SWR revalidations
+  // Merge fetched sessions with pending sessions.
+  // This ensures pending sessions persist across SWR revalidations.
   const chatSessions = useMemo(() => {
-    const fetchedIds = new Set(fetchedSessions.map((s) => s.id));
+    const fetchedIds = new Set(allFetchedSessions.map((s) => s.id));
 
     // Get pending sessions that are not yet in fetched data
     const remainingPending = pendingSessions.filter(
@@ -147,8 +235,8 @@ export default function useChatSessions(): UseChatSessionsOutput {
     );
 
     // Pending sessions go first (most recent), then fetched sessions
-    return [...remainingPending, ...fetchedSessions];
-  }, [fetchedSessions, pendingSessions]);
+    return [...remainingPending, ...allFetchedSessions];
+  }, [allFetchedSessions, pendingSessions]);
 
   const currentChatSessionId = appFocus.isChat() ? appFocus.getId() : null;
   const currentChatSession =
@@ -159,27 +247,18 @@ export default function useChatSessions(): UseChatSessionsOutput {
   const agentForCurrentChatSession =
     useFindAgentForCurrentChatSession(currentChatSession);
 
-  // Add a pending chat session that will persist across SWR revalidations
-  // The session will be automatically removed once it appears in the server response
+  // Add a pending chat session that will persist across SWR revalidations.
+  // The session will be automatically removed once it appears in the server response.
   const addPendingChatSession = useCallback(
     ({ chatSessionId, personaId, projectId }: PendingChatSessionParams) => {
       // Don't add sessions that belong to a project
-      if (projectId != null) {
-        return;
-      }
+      if (projectId != null) return;
 
       // Don't add if already in pending store (duplicates are also filtered during merge)
-      if (pendingSessionsStore.has(chatSessionId)) {
-        return;
-      }
-
-      // Note: This check uses stale fetchedSessions due to empty deps, but is defensive
-      if (fetchedSessions.some((s) => s.id === chatSessionId)) {
-        return;
-      }
+      if (pendingSessionsStore.has(chatSessionId)) return;
 
       const now = new Date().toISOString();
-      const pendingSession: ChatSession = {
+      pendingSessionsStore.add({
         id: chatSessionId,
         name: "", // Empty name will display as "New Chat" via UNNAMED_CHAT constant
         persona_id: personaId,
@@ -189,13 +268,29 @@ export default function useChatSessions(): UseChatSessionsOutput {
         project_id: projectId ?? null,
         current_alternate_model: "",
         current_temperature_override: null,
-      };
-
-      pendingSessionsStore.add(pendingSession);
+      });
     },
     []
   );
 
+  const removeSession = useCallback(
+    (sessionId: string) => {
+      pendingSessionsStore.remove(sessionId);
+      // Optimistically remove from all loaded pages
+      mutate(
+        (pages) =>
+          pages?.map((page) => ({
+            ...page,
+            sessions: page.sessions.filter((s) => s.id !== sessionId),
+          })),
+        { revalidate: false }
+      );
+    },
+    [mutate]
+  );
+
+  const refreshChatSessions = useCallback(() => mutate(), [mutate]);
+
   return {
     chatSessions,
     currentChatSessionId,
@@ -203,7 +298,11 @@ export default function useChatSessions(): UseChatSessionsOutput {
     agentForCurrentChatSession,
     isLoading: !error && !data,
     error,
-    refreshChatSessions: mutate,
+    refreshChatSessions,
     addPendingChatSession,
+    removeSession,
+    hasMore,
+    isLoadingMore,
+    loadMore,
   };
 }
diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index 2f2336a116c..bc036c785a8 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -104,7 +104,8 @@ function Header() {
     refreshCurrentProjectDetails,
     currentProjectId,
   } = useProjectsContext();
-  const { currentChatSession, refreshChatSessions } = useChatSessions();
+  const { currentChatSession, refreshChatSessions, removeSession } =
+    useChatSessions();
   const router = useRouter();
   const appFocus = useAppFocus();
   const { classification } = useQueryController();
@@ -186,6 +187,7 @@ function Header() {
       if (!response.ok) {
         throw new Error("Failed to delete chat session");
       }
+      removeSession(currentChatSession.id);
       await Promise.all([refreshChatSessions(), fetchProjects()]);
       router.replace("/app");
       setDeleteModalOpen(false);
@@ -193,7 +195,13 @@ function Header() {
       console.error("Failed to delete chat:", error);
       showErrorNotification("Failed to delete chat. Please try again.");
     }
-  }, [currentChatSession, refreshChatSessions, fetchProjects, router]);
+  }, [
+    currentChatSession,
+    refreshChatSessions,
+    removeSession,
+    fetchProjects,
+    router,
+  ]);
 
   const setDeleteConfirmationModalOpen = useCallback((open: boolean) => {
     setDeleteModalOpen(open);
diff --git a/web/src/refresh-components/skeletons/SidebarTabSkeleton.tsx b/web/src/refresh-components/skeletons/SidebarTabSkeleton.tsx
new file mode 100644
index 00000000000..c23b87b87ec
--- /dev/null
+++ b/web/src/refresh-components/skeletons/SidebarTabSkeleton.tsx
@@ -0,0 +1,22 @@
+import { cn } from "@/lib/utils";
+
+interface SidebarTabSkeletonProps {
+  textWidth?: string;
+}
+
+export default function SidebarTabSkeleton({
+  textWidth = "w-2/3",
+}: SidebarTabSkeletonProps) {
+  return (
+    <div className="w-full rounded-08 p-1.5">
+      <div className="h-[1.5rem] flex flex-row items-center px-1 py-0.5">
+        <div
+          className={cn(
+            "h-3 rounded bg-background-tint-04 animate-pulse",
+            textWidth
+          )}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/web/src/sections/sidebar/AppSidebar.tsx b/web/src/sections/sidebar/AppSidebar.tsx
index 38943408c22..09c66f9cd96 100644
--- a/web/src/sections/sidebar/AppSidebar.tsx
+++ b/web/src/sections/sidebar/AppSidebar.tsx
@@ -67,6 +67,7 @@ import {
   SvgSearchMenu,
   SvgSettings,
 } from "@opal/icons";
+import SidebarTabSkeleton from "@/refresh-components/skeletons/SidebarTabSkeleton";
 import BuildModeIntroBackground from "@/app/craft/components/IntroBackground";
 import BuildModeIntroContent from "@/app/craft/components/IntroContent";
 import { CRAFT_PATH } from "@/app/craft/v1/constants";
@@ -99,11 +100,25 @@ function buildVisibleAgents(
   return [visibleAgents, currentAgentIsPinned];
 }
 
+const SKELETON_WIDTHS_BASE = ["w-4/5", "w-4/5", "w-3/5"];
+
+function shuffleWidths(): string[] {
+  return [...SKELETON_WIDTHS_BASE].sort(() => Math.random() - 0.5);
+}
+
 interface RecentsSectionProps {
   chatSessions: ChatSession[];
+  hasMore: boolean;
+  isLoadingMore: boolean;
+  onLoadMore: () => void;
 }
 
-function RecentsSection({ chatSessions }: RecentsSectionProps) {
+function RecentsSection({
+  chatSessions,
+  hasMore,
+  isLoadingMore,
+  onLoadMore,
+}: RecentsSectionProps) {
   const { setNodeRef, isOver } = useDroppable({
     id: DRAG_TYPES.RECENTS,
     data: {
@@ -111,6 +126,33 @@ function RecentsSection({ chatSessions }: RecentsSectionProps) {
     },
   });
 
+  // Re-shuffle skeleton widths each time loaded session count changes
+  const skeletonWidths = useMemo(shuffleWidths, [chatSessions.length]);
+
+  // Sentinel ref for IntersectionObserver-based infinite scroll
+  const sentinelRef = useRef<HTMLDivElement | null>(null);
+  const onLoadMoreRef = useRef(onLoadMore);
+  onLoadMoreRef.current = onLoadMore;
+
+  useEffect(() => {
+    if (!hasMore || isLoadingMore) return;
+
+    const sentinel = sentinelRef.current;
+    if (!sentinel) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0]?.isIntersecting) {
+          onLoadMoreRef.current();
+        }
+      },
+      { threshold: 0 }
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [hasMore, isLoadingMore]);
+
   return (
     <div
       ref={setNodeRef}
@@ -125,13 +167,28 @@ function RecentsSection({ chatSessions }: RecentsSectionProps) {
             Try sending a message! Your chat history will appear here.
           </Text>
         ) : (
-          chatSessions.map((chatSession) => (
-            <ChatButton
-              key={chatSession.id}
-              chatSession={chatSession}
-              draggable
-            />
-          ))
+          <>
+            {chatSessions.map((chatSession) => (
+              <ChatButton
+                key={chatSession.id}
+                chatSession={chatSession}
+                draggable
+              />
+            ))}
+            {hasMore &&
+              skeletonWidths.map((width, i) => (
+                <div
+                  key={i}
+                  ref={i === 0 ? sentinelRef : undefined}
+                  className={cn(
+                    "transition-opacity duration-300",
+                    isLoadingMore ? "opacity-100" : "opacity-40"
+                  )}
+                >
+                  <SidebarTabSkeleton textWidth={width} />
+                </div>
+              ))}
+          </>
         )}
       </SidebarSection>
     </div>
@@ -157,6 +214,9 @@ const MemoizedAppSidebarInner = memo(
       chatSessions,
       refreshChatSessions,
       isLoading: isLoadingChatSessions,
+      hasMore,
+      isLoadingMore,
+      loadMore,
     } = useChatSessions();
     const {
       projects,
@@ -700,7 +760,12 @@ const MemoizedAppSidebarInner = memo(
                   </SidebarSection>
 
                   {/* Recents */}
-                  <RecentsSection chatSessions={chatSessions} />
+                  <RecentsSection
+                    chatSessions={chatSessions}
+                    hasMore={hasMore}
+                    isLoadingMore={isLoadingMore}
+                    onLoadMore={loadMore}
+                  />
                 </DndContext>
               </>
             )}
diff --git a/web/src/sections/sidebar/ChatButton.tsx b/web/src/sections/sidebar/ChatButton.tsx
index 2630126da37..c47d980603e 100644
--- a/web/src/sections/sidebar/ChatButton.tsx
+++ b/web/src/sections/sidebar/ChatButton.tsx
@@ -122,7 +122,7 @@ const ChatButton = memo(
     const [showShareModal, setShowShareModal] = useState(false);
     const [searchTerm, setSearchTerm] = useState("");
     const [popoverItems, setPopoverItems] = useState<React.ReactNode[]>([]);
-    const { refreshChatSessions } = useChatSessions();
+    const { refreshChatSessions, removeSession } = useChatSessions();
     const {
       refreshCurrentProjectDetails,
       projects,
@@ -302,6 +302,7 @@ const ChatButton = memo(
     async function handleChatDelete() {
       try {
         await deleteChatSession(chatSession.id);
+        removeSession(chatSession.id);
 
         if (project) {
           await fetchProjects();

From 9c05bd215df50ad7454a06c84586be2da2c42908 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 09:22:01 -0800
Subject: [PATCH 007/267] fix(a11y): settings popover buttons prefer href
 (#8880)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
---
 web/src/refresh-components/buttons/LineItem.tsx | 10 +++++++++-
 web/src/sections/sidebar/UserAvatarPopover.tsx  | 17 ++++++++---------
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/web/src/refresh-components/buttons/LineItem.tsx b/web/src/refresh-components/buttons/LineItem.tsx
index baa9ff116b7..30e38ed0eef 100644
--- a/web/src/refresh-components/buttons/LineItem.tsx
+++ b/web/src/refresh-components/buttons/LineItem.tsx
@@ -72,6 +72,8 @@ export interface LineItemProps
   description?: string;
   rightChildren?: React.ReactNode;
   href?: string;
+  rel?: string;
+  target?: string;
   ref?: React.Ref<HTMLDivElement>;
   children?: React.ReactNode;
 }
@@ -141,6 +143,8 @@ export default function LineItem({
   children,
   rightChildren,
   href,
+  rel,
+  target,
   ref,
   ...props
 }: LineItemProps) {
@@ -241,5 +245,9 @@ export default function LineItem({
   );
 
   if (!href) return content;
-  return <Link href={href as Route}>{content}</Link>;
+  return (
+    <Link href={href as Route} rel={rel} target={target}>
+      {content}
+    </Link>
+  );
 }
diff --git a/web/src/sections/sidebar/UserAvatarPopover.tsx b/web/src/sections/sidebar/UserAvatarPopover.tsx
index c7413edf920..17db2aa4604 100644
--- a/web/src/sections/sidebar/UserAvatarPopover.tsx
+++ b/web/src/sections/sidebar/UserAvatarPopover.tsx
@@ -103,7 +103,11 @@ function SettingsPopover({
       <PopoverMenu>
         {[
           <div key="user-settings" data-testid="Settings/user-settings">
-            <LineItem icon={SvgUser} onClick={onUserSettingsClick}>
+            <LineItem
+              icon={SvgUser}
+              href="/app/settings"
+              onClick={onUserSettingsClick}
+            >
               User Settings
             </LineItem>
           </div>,
@@ -119,13 +123,9 @@ function SettingsPopover({
           <LineItem
             key="help-faq"
             icon={SvgExternalLink}
-            onClick={() =>
-              window.open(
-                "https://docs.onyx.app",
-                "_blank",
-                "noopener,noreferrer"
-              )
-            }
+            href="https://docs.onyx.app"
+            target="_blank"
+            rel="noopener noreferrer"
           >
             Help & FAQ
           </LineItem>,
@@ -238,7 +238,6 @@ export default function UserAvatarPopover({
           <SettingsPopover
             onUserSettingsClick={() => {
               setPopupState(undefined);
-              router.push("/app/settings");
             }}
             onOpenNotifications={() => setPopupState("Notifications")}
           />

From 59d3725fc696494e1cb5991ac418bdb2aff5233e Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 09:34:22 -0800
Subject: [PATCH 008/267] chore(gha): rm docker-compose.opensearch.yml ref
 (#8912)

---
 .github/workflows/pr-external-dependency-unit-tests.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pr-external-dependency-unit-tests.yml b/.github/workflows/pr-external-dependency-unit-tests.yml
index 673dbb5e200..f26aa69141d 100644
--- a/.github/workflows/pr-external-dependency-unit-tests.yml
+++ b/.github/workflows/pr-external-dependency-unit-tests.yml
@@ -160,7 +160,7 @@ jobs:
           cd deployment/docker_compose
 
           # Get list of running containers
-          containers=$(docker compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.opensearch.yml ps -q)
+          containers=$(docker compose -f docker-compose.yml -f docker-compose.dev.yml ps -q)
 
           # Collect logs from each container
           for container in $containers; do

From ba79539d6dea077cd884c10bb38d0b69c1037797 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:10:13 -0800
Subject: [PATCH 009/267] feat(slack): add Slack user deactivation and
 seat-aware reactivation (#8887)

---
 backend/onyx/auth/users.py                    |   8 ++
 .../onyxbot/slack/handlers/handle_message.py  |  40 ++++++
 .../users/test_slack_user_deactivation.py     | 121 ++++++++++++++++++
 .../admin/users/SignedUpUserTable.tsx         |  30 ++---
 4 files changed, 184 insertions(+), 15 deletions(-)
 create mode 100644 backend/tests/integration/tests/users/test_slack_user_deactivation.py

diff --git a/backend/onyx/auth/users.py b/backend/onyx/auth/users.py
index 28a48487652..46733480949 100644
--- a/backend/onyx/auth/users.py
+++ b/backend/onyx/auth/users.py
@@ -725,11 +725,19 @@ async def oauth_callback(
                         if user_by_session:
                             user = user_by_session
 
+                # If the user is inactive, check seat availability before
+                # upgrading role — otherwise they'd become an inactive BASIC
+                # user who still can't log in.
+                if not user.is_active:
+                    with get_session_with_current_tenant() as sync_db:
+                        enforce_seat_limit(sync_db)
+
                 await self.user_db.update(
                     user,
                     {
                         "is_verified": is_verified_by_default,
                         "role": UserRole.BASIC,
+                        **({"is_active": True} if not user.is_active else {}),
                     },
                 )
 
diff --git a/backend/onyx/onyxbot/slack/handlers/handle_message.py b/backend/onyx/onyxbot/slack/handlers/handle_message.py
index 971c1dca029..f16b52c3520 100644
--- a/backend/onyx/onyxbot/slack/handlers/handle_message.py
+++ b/backend/onyx/onyxbot/slack/handlers/handle_message.py
@@ -3,10 +3,12 @@
 from slack_sdk import WebClient
 from slack_sdk.errors import SlackApiError
 
+from onyx.auth.schemas import UserRole
 from onyx.configs.onyxbot_configs import ONYX_BOT_FEEDBACK_REMINDER
 from onyx.configs.onyxbot_configs import ONYX_BOT_REACT_EMOJI
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.models import SlackChannelConfig
+from onyx.db.user_preferences import activate_user
 from onyx.db.users import add_slack_user_if_not_exists
 from onyx.db.users import get_user_by_email
 from onyx.onyxbot.slack.blocks import get_feedback_reminder_blocks
@@ -243,6 +245,44 @@ def handle_message(
                     )
                     return False
 
+            elif (
+                not existing_user.is_active
+                and existing_user.role == UserRole.SLACK_USER
+            ):
+                check_seat_fn = fetch_ee_implementation_or_noop(
+                    "onyx.db.license",
+                    "check_seat_availability",
+                    None,
+                )
+                seat_result = check_seat_fn(db_session=db_session)
+                if seat_result is not None and not seat_result.available:
+                    logger.info(
+                        f"Blocked inactive Slack user {message_info.email}: "
+                        f"{seat_result.error_message}"
+                    )
+                    respond_in_thread_or_channel(
+                        client=client,
+                        channel=channel,
+                        thread_ts=message_info.msg_to_respond,
+                        text=(
+                            "We weren't able to respond because your organization "
+                            "has reached its user seat limit. Your account is "
+                            "currently deactivated and cannot be reactivated "
+                            "until more seats are available. Please contact "
+                            "your Onyx administrator."
+                        ),
+                    )
+                    return False
+
+                activate_user(existing_user, db_session)
+                invalidate_license_cache_fn = fetch_ee_implementation_or_noop(
+                    "onyx.db.license",
+                    "invalidate_license_cache",
+                    None,
+                )
+                invalidate_license_cache_fn()
+                logger.info(f"Reactivated inactive Slack user {message_info.email}")
+
             add_slack_user_if_not_exists(db_session, message_info.email)
 
         # first check if we need to respond with a standard answer
diff --git a/backend/tests/integration/tests/users/test_slack_user_deactivation.py b/backend/tests/integration/tests/users/test_slack_user_deactivation.py
new file mode 100644
index 00000000000..d96f5f34a86
--- /dev/null
+++ b/backend/tests/integration/tests/users/test_slack_user_deactivation.py
@@ -0,0 +1,121 @@
+"""Integration tests for Slack user deactivation and reactivation via admin endpoints.
+
+Verifies that:
+- Slack users can be deactivated by admins
+- Deactivated Slack users can be reactivated by admins
+- Reactivation is blocked when the seat limit is reached
+"""
+
+from datetime import datetime
+from datetime import timedelta
+
+import redis
+import requests
+
+from ee.onyx.server.license.models import LicenseMetadata
+from ee.onyx.server.license.models import LicenseSource
+from ee.onyx.server.license.models import PlanType
+from onyx.auth.schemas import UserRole
+from onyx.configs.app_configs import REDIS_DB_NUMBER
+from onyx.configs.app_configs import REDIS_HOST
+from onyx.configs.app_configs import REDIS_PORT
+from onyx.server.settings.models import ApplicationStatus
+from tests.integration.common_utils.constants import API_SERVER_URL
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.test_models import DATestUser
+
+_LICENSE_REDIS_KEY = "public:license:metadata"
+
+
+def _seed_license(r: redis.Redis, seats: int) -> None:
+    now = datetime.utcnow()
+    metadata = LicenseMetadata(
+        tenant_id="public",
+        organization_name="Test Org",
+        seats=seats,
+        used_seats=0,
+        plan_type=PlanType.ANNUAL,
+        issued_at=now,
+        expires_at=now + timedelta(days=365),
+        status=ApplicationStatus.ACTIVE,
+        source=LicenseSource.MANUAL_UPLOAD,
+    )
+    r.set(_LICENSE_REDIS_KEY, metadata.model_dump_json(), ex=300)
+
+
+def _clear_license(r: redis.Redis) -> None:
+    r.delete(_LICENSE_REDIS_KEY)
+
+
+def _redis() -> redis.Redis:
+    return redis.Redis(host=REDIS_HOST, port=REDIS_PORT, db=REDIS_DB_NUMBER)
+
+
+def _get_user_is_active(email: str, admin_user: DATestUser) -> bool:
+    """Look up a user's is_active flag via the admin users list endpoint."""
+    result = UserManager.get_user_page(
+        user_performing_action=admin_user,
+        search_query=email,
+    )
+    matching = [u for u in result.items if u.email == email]
+    assert len(matching) == 1, f"Expected exactly 1 user with email {email}"
+    return matching[0].is_active
+
+
+def test_slack_user_deactivate_and_reactivate(reset: None) -> None:  # noqa: ARG001
+    """Admin can deactivate and then reactivate a Slack user."""
+    admin_user = UserManager.create(name="admin_user")
+
+    slack_user = UserManager.create(name="slack_test_user")
+    slack_user = UserManager.set_role(
+        user_to_set=slack_user,
+        target_role=UserRole.SLACK_USER,
+        user_performing_action=admin_user,
+        explicit_override=True,
+    )
+
+    # Deactivate the Slack user
+    UserManager.set_status(
+        slack_user, target_status=False, user_performing_action=admin_user
+    )
+    assert _get_user_is_active(slack_user.email, admin_user) is False
+
+    # Reactivate the Slack user
+    UserManager.set_status(
+        slack_user, target_status=True, user_performing_action=admin_user
+    )
+    assert _get_user_is_active(slack_user.email, admin_user) is True
+
+
+def test_slack_user_reactivation_blocked_by_seat_limit(
+    reset: None,  # noqa: ARG001
+) -> None:
+    """Reactivating a deactivated Slack user returns 402 when seats are full."""
+    r = _redis()
+
+    admin_user = UserManager.create(name="admin_user")
+
+    slack_user = UserManager.create(name="slack_test_user")
+    slack_user = UserManager.set_role(
+        user_to_set=slack_user,
+        target_role=UserRole.SLACK_USER,
+        user_performing_action=admin_user,
+        explicit_override=True,
+    )
+
+    UserManager.set_status(
+        slack_user, target_status=False, user_performing_action=admin_user
+    )
+
+    # License allows 1 seat — only admin counts
+    _seed_license(r, seats=1)
+
+    try:
+        response = requests.patch(
+            url=f"{API_SERVER_URL}/manage/admin/activate-user",
+            json={"user_email": slack_user.email},
+            headers=admin_user.headers,
+        )
+        assert response.status_code == 402
+    finally:
+        _clear_license(r)
diff --git a/web/src/components/admin/users/SignedUpUserTable.tsx b/web/src/components/admin/users/SignedUpUserTable.tsx
index 32a5aa109fd..668a2d3ed08 100644
--- a/web/src/components/admin/users/SignedUpUserTable.tsx
+++ b/web/src/components/admin/users/SignedUpUserTable.tsx
@@ -310,23 +310,23 @@ export default function SignedUpUserTable({
   };
 
   const renderActionButtons = (user: User) => {
-    if (user.role === UserRole.SLACK_USER) {
-      return (
-        <InviteUserButton
+    return (
+      <div className="flex items-center justify-end gap-2">
+        {user.role === UserRole.SLACK_USER && (
+          <InviteUserButton
+            user={user}
+            invited={invitedEmails.includes(user.email.toLowerCase())}
+            mutate={[refresh, invitedUsersMutate]}
+          />
+        )}
+        <ActionMenu
           user={user}
-          invited={invitedEmails.includes(user.email.toLowerCase())}
-          mutate={[refresh, invitedUsersMutate]}
+          currentUser={currentUser}
+          refresh={refresh}
+          invitedUsersMutate={invitedUsersMutate}
+          handleResetPassword={handleResetPassword}
         />
-      );
-    }
-    return (
-      <ActionMenu
-        user={user}
-        currentUser={currentUser}
-        refresh={refresh}
-        invitedUsersMutate={invitedUsersMutate}
-        handleResetPassword={handleResetPassword}
-      />
+      </div>
     );
   };
 

From 15d8946f40ce3b58a25d907128acd3b5c16f6d48 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:19:23 -0800
Subject: [PATCH 010/267] =?UTF-8?q?refactor(fe):=20rename=20assistant=20?=
 =?UTF-8?q?=E2=86=92=20agent=20identifiers=20(#8869)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web/next.config.js                            |  19 +++
 .../CollapsibleSection.tsx                    |   0
 .../{assistants => agents}/PersonaTable.tsx   |   0
 .../{assistants => agents}/interfaces.ts      |   0
 .../app/admin/{assistants => agents}/lib.ts   |   2 +-
 .../app/admin/{assistants => agents}/page.tsx |   0
 .../SlackChannelConfigCreationForm.tsx        |  16 +--
 .../channels/SlackChannelConfigFormFields.tsx |  85 ++++++-----
 .../bots/[bot-id]/channels/[id]/page.tsx      |  16 +--
 .../admin/bots/[bot-id]/channels/new/page.tsx |  23 ++-
 web/src/app/admin/bots/[bot-id]/lib.ts        |   2 +-
 .../[connector]/pages/FieldRendering.tsx      |   2 +-
 .../[guild-id]/DiscordChannelsTable.tsx       |   2 +-
 .../app/admin/discord-bot/[guild-id]/page.tsx |   2 +-
 .../app/app/components/AgentDescription.tsx   |   2 +-
 web/src/app/app/components/WelcomeMessage.tsx |   4 +-
 .../projects/ProjectChatSessionList.tsx       |   8 +-
 web/src/app/app/interfaces.ts                 |  12 +-
 .../messageComponents/AgentMessage.tsx        |   6 +-
 .../message/messageComponents/interfaces.ts   |   4 +-
 .../renderMessageComponent.tsx                |   2 +-
 .../timeline/AgentTimeline.tsx                |   8 +-
 web/src/app/app/services/actionUtils.ts       |   2 +-
 web/src/app/app/services/lib.tsx              |  12 +-
 web/src/app/app/services/messageTree.ts       |  12 +-
 web/src/app/app/services/searchParams.ts      |   2 +-
 .../app/shared/[chatId]/SharedChatDisplay.tsx |   4 +-
 web/src/app/app/shared/[chatId]/page.tsx      |   2 +-
 .../app/craft/components/BuildMessageList.tsx |  10 +-
 web/src/app/craft/components/ChatPanel.tsx    |  14 +-
 .../craft/components/ConnectorBannersRow.tsx  |   2 +-
 .../craft/components/SuggestionBubbles.tsx    |   2 +-
 .../app/craft/hooks/useBuildSessionStore.ts   |  50 +++----
 web/src/app/craft/hooks/useBuildStreaming.ts  |  10 +-
 web/src/app/craft/services/apiServices.ts     |   4 +-
 web/src/app/craft/types/streamingTypes.ts     |   2 +-
 .../usage/PersonaMessagesChart.tsx            |   2 +-
 .../stats/[id]/AgentStats.tsx}                |  55 ++++---
 .../stats/[id]/page.tsx                       |   4 +-
 web/src/app/nrf/NRFPage.tsx                   |  38 ++---
 ...{NoAssistantModal.tsx => NoAgentModal.tsx} |   4 +-
 .../sidebar/ChatSessionMorePopup.tsx          |   7 +-
 web/src/components/sidebar/types.ts           |   2 +-
 web/src/hooks/appNavigation.ts                |  10 +-
 web/src/hooks/useAdminPersonas.ts             |   2 +-
 web/src/hooks/useAgentController.ts           |  89 +++++-------
 web/src/hooks/useAgentPreferences.ts          |  51 ++++---
 web/src/hooks/useAgents.ts                    |   4 +-
 web/src/hooks/useChatController.ts            |  90 ++++++------
 web/src/hooks/useChatSessionController.ts     |  10 +-
 web/src/hooks/useChatSessions.ts              |   6 +-
 web/src/hooks/useDeepResearchToggle.ts        |   8 +-
 web/src/hooks/useIsDefaultAgent.ts            |  20 +--
 web/src/hooks/useShowOnboarding.ts            |   8 +-
 web/src/lib/agents.ts                         |  40 +++---
 web/src/lib/agentsSS.ts                       |   8 +-
 web/src/lib/chat/fetchAgentData.ts            |  20 +++
 web/src/lib/chat/fetchAssistantdata.ts        |  20 ---
 web/src/lib/constants.ts                      |   2 +-
 web/src/lib/filters.ts                        |   2 +-
 web/src/lib/hooks.ts                          |  43 +++---
 web/src/lib/hooks/useToolOAuthStatus.ts       |   4 +-
 web/src/lib/llmConfig/utils.ts                |   8 +-
 web/src/lib/search/interfaces.ts              |   2 +-
 web/src/lib/sources.ts                        |   2 +-
 web/src/lib/types.ts                          |   9 +-
 web/src/providers/UserProvider.tsx            |  32 ++---
 web/src/proxy.ts                              |   8 +-
 .../avatars/AgentAvatar.tsx                   |   6 +-
 .../__tests__/useShowOnboarding.test.tsx      |   8 +-
 .../onboarding/useOnboardingState.ts          |  12 +-
 .../popovers/ActionsPopover/index.tsx         |  80 +++++------
 web/src/refresh-pages/AgentEditorPage.tsx     |   8 +-
 .../refresh-pages/AgentsNavigationPage.tsx    |   4 +-
 web/src/refresh-pages/AppPage.tsx             |  59 ++++----
 .../admin/ChatPreferencesPage.tsx             |  24 ++--
 web/src/sections/cards/AgentCard.tsx          |   8 +-
 web/src/sections/chat/ChatUI.tsx              |   8 +-
 web/src/sections/input/AppInputBar.tsx        |  26 ++--
 .../sections/knowledge/AgentKnowledgePane.tsx |   2 +-
 .../knowledge/SourceHierarchyBrowser.tsx      |   2 +-
 web/src/sections/modals/AgentViewerModal.tsx  |   4 +-
 web/src/sections/modals/ShareAgentModal.tsx   |   4 +-
 web/src/sections/sidebar/AdminSidebar.tsx     |   9 +-
 web/src/sections/sidebar/AgentButton.tsx      |   4 +-
 web/src/sections/sidebar/AppSidebar.tsx       |  10 +-
 .../sidebar/ChatSearchCommandMenu.tsx         |   2 +-
 web/tests/e2e/admin/admin_pages.spec.ts       |   2 +-
 ...ssistant.spec.ts => default-agent.spec.ts} |   2 +-
 ....spec.ts => disable_default_agent.spec.ts} |  46 +++---
 .../admin/discord-bot/channel-config.spec.ts  |   4 +-
 .../oauth_config/test_tool_oauth.spec.ts      |  20 +--
 .../create_and_edit_agent.spec.ts}            |  63 ++++----
 .../llm_provider_rbac.spec.ts                 |   0
 .../user_file_attachment.spec.ts              |  44 +++---
 .../e2e/chat/chat_message_rendering.spec.ts   |  16 +--
 ...ssistant.spec.ts => current_agent.spec.ts} |  17 +--
 ...ssistant.spec.ts => default_agent.spec.ts} |  30 ++--
 ...e_assistant.spec.ts => live_agent.spec.ts} |  16 +--
 web/tests/e2e/chat/llm_ordering.spec.ts       |   2 +-
 .../e2e/chat/llm_runtime_selection.spec.ts    |   8 +-
 web/tests/e2e/chat/welcome_page.spec.ts       |   2 +-
 ...-mcp.spec.ts => default-agent-mcp.spec.ts} |  34 ++---
 web/tests/e2e/mcp/mcp_oauth_flow.spec.ts      | 134 ++++++++----------
 .../{assistantUtils.ts => agentUtils.ts}      |  16 +--
 web/tests/e2e/utils/chatActions.ts            |  16 +--
 web/tests/e2e/utils/onyxApiClient.ts          |  20 +--
 .../setup/mocks/components/UserProvider.tsx   |   8 +-
 108 files changed, 829 insertions(+), 904 deletions(-)
 rename web/src/app/admin/{assistants => agents}/CollapsibleSection.tsx (100%)
 rename web/src/app/admin/{assistants => agents}/PersonaTable.tsx (100%)
 rename web/src/app/admin/{assistants => agents}/interfaces.ts (100%)
 rename web/src/app/admin/{assistants => agents}/lib.ts (99%)
 rename web/src/app/admin/{assistants => agents}/page.tsx (100%)
 rename web/src/app/ee/{assistants/stats/[id]/AssistantStats.tsx => agents/stats/[id]/AgentStats.tsx} (74%)
 rename web/src/app/ee/{assistants => agents}/stats/[id]/page.tsx (89%)
 rename web/src/components/modals/{NoAssistantModal.tsx => NoAgentModal.tsx} (90%)
 create mode 100644 web/src/lib/chat/fetchAgentData.ts
 delete mode 100644 web/src/lib/chat/fetchAssistantdata.ts
 rename web/tests/e2e/admin/{default-assistant.spec.ts => default-agent.spec.ts} (99%)
 rename web/tests/e2e/admin/{disable_default_assistant.spec.ts => disable_default_agent.spec.ts} (86%)
 rename web/tests/e2e/{assistants/create_and_edit_assistant.spec.ts => agents/create_and_edit_agent.spec.ts} (87%)
 rename web/tests/e2e/{assistants => agents}/llm_provider_rbac.spec.ts (100%)
 rename web/tests/e2e/{assistants => agents}/user_file_attachment.spec.ts (90%)
 rename web/tests/e2e/chat/{current_assistant.spec.ts => current_agent.spec.ts} (91%)
 rename web/tests/e2e/chat/{default_assistant.spec.ts => default_agent.spec.ts} (96%)
 rename web/tests/e2e/chat/{live_assistant.spec.ts => live_agent.spec.ts} (81%)
 rename web/tests/e2e/mcp/{default-assistant-mcp.spec.ts => default-agent-mcp.spec.ts} (96%)
 rename web/tests/e2e/utils/{assistantUtils.ts => agentUtils.ts} (91%)

diff --git a/web/next.config.js b/web/next.config.js
index bf092a7ab43..59fb98ab0ce 100644
--- a/web/next.config.js
+++ b/web/next.config.js
@@ -122,6 +122,25 @@ const nextConfig = {
         destination: "/app/:path*",
         permanent: true,
       },
+      // Legacy /assistants → /agents redirects (added in PR #8869).
+      // Preserves backward compatibility for bookmarks, shared links, and
+      // hardcoded URLs that still reference the old /assistants paths.
+      // TODO: Remove these redirects in v4.0 — https://linear.app/onyx-app/issue/ENG-3771
+      {
+        source: "/admin/assistants",
+        destination: "/admin/agents",
+        permanent: true,
+      },
+      {
+        source: "/admin/assistants/:path*",
+        destination: "/admin/agents/:path*",
+        permanent: true,
+      },
+      {
+        source: "/ee/assistants/:path*",
+        destination: "/ee/agents/:path*",
+        permanent: true,
+      },
     ];
   },
 };
diff --git a/web/src/app/admin/assistants/CollapsibleSection.tsx b/web/src/app/admin/agents/CollapsibleSection.tsx
similarity index 100%
rename from web/src/app/admin/assistants/CollapsibleSection.tsx
rename to web/src/app/admin/agents/CollapsibleSection.tsx
diff --git a/web/src/app/admin/assistants/PersonaTable.tsx b/web/src/app/admin/agents/PersonaTable.tsx
similarity index 100%
rename from web/src/app/admin/assistants/PersonaTable.tsx
rename to web/src/app/admin/agents/PersonaTable.tsx
diff --git a/web/src/app/admin/assistants/interfaces.ts b/web/src/app/admin/agents/interfaces.ts
similarity index 100%
rename from web/src/app/admin/assistants/interfaces.ts
rename to web/src/app/admin/agents/interfaces.ts
diff --git a/web/src/app/admin/assistants/lib.ts b/web/src/app/admin/agents/lib.ts
similarity index 99%
rename from web/src/app/admin/assistants/lib.ts
rename to web/src/app/admin/agents/lib.ts
index a4b6f756eef..5986caf8da7 100644
--- a/web/src/app/admin/assistants/lib.ts
+++ b/web/src/app/admin/agents/lib.ts
@@ -2,7 +2,7 @@ import {
   MinimalPersonaSnapshot,
   Persona,
   StarterMessage,
-} from "@/app/admin/assistants/interfaces";
+} from "@/app/admin/agents/interfaces";
 
 interface PersonaUpsertRequest {
   name: string;
diff --git a/web/src/app/admin/assistants/page.tsx b/web/src/app/admin/agents/page.tsx
similarity index 100%
rename from web/src/app/admin/assistants/page.tsx
rename to web/src/app/admin/agents/page.tsx
diff --git a/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm.tsx b/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm.tsx
index 0d32055781c..bceb648c3b5 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm.tsx
@@ -16,7 +16,7 @@ import {
 } from "../lib";
 import CardSection from "@/components/admin/CardSection";
 import { useRouter } from "next/navigation";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { StandardAnswerCategoryResponse } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 import { SEARCH_TOOL_ID } from "@/app/app/components/tools/constants";
 import { SlackChannelConfigFormFields } from "./SlackChannelConfigFormFields";
@@ -46,7 +46,7 @@ export const SlackChannelConfigCreationForm = ({
       )
     : false;
 
-  const [searchEnabledAssistants, nonSearchAssistants] = useMemo(() => {
+  const [searchEnabledAgents, nonSearchAgents] = useMemo(() => {
     return personas.reduce(
       (acc, persona) => {
         if (
@@ -115,7 +115,7 @@ export const SlackChannelConfigCreationForm = ({
           knowledge_source: existingSlackBotUsesPersona
             ? existingPersonaHasSearchTool
               ? "assistant"
-              : "non_search_assistant"
+              : "non_search_agent"
             : existingSlackChannelConfig?.persona
               ? "document_sets"
               : "all_public",
@@ -165,7 +165,7 @@ export const SlackChannelConfigCreationForm = ({
               "all_public",
               "document_sets",
               "assistant",
-              "non_search_assistant",
+              "non_search_agent",
             ])
             .required(),
           disabled: Yup.boolean().optional().default(false),
@@ -180,14 +180,14 @@ export const SlackChannelConfigCreationForm = ({
             respond_member_group_list: values.respond_member_group_list,
             usePersona:
               values.knowledge_source === "assistant" ||
-              values.knowledge_source === "non_search_assistant",
+              values.knowledge_source === "non_search_agent",
             document_sets:
               values.knowledge_source === "document_sets"
                 ? values.document_sets
                 : [],
             persona_id:
               values.knowledge_source === "assistant" ||
-              values.knowledge_source === "non_search_assistant"
+              values.knowledge_source === "non_search_agent"
                 ? values.persona_id
                 : null,
             standard_answer_categories: values.standard_answer_categories.map(
@@ -234,8 +234,8 @@ export const SlackChannelConfigCreationForm = ({
                 isUpdate={isUpdate}
                 isDefault={isDefault}
                 documentSets={documentSets}
-                searchEnabledAssistants={searchEnabledAssistants}
-                nonSearchAssistants={nonSearchAssistants}
+                searchEnabledAgents={searchEnabledAgents}
+                nonSearchAgents={nonSearchAgents}
                 standardAnswerCategoryResponse={standardAnswerCategoryResponse}
                 slack_bot_id={slack_bot_id}
                 formikProps={formikProps}
diff --git a/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx b/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx
index 1b715586c71..d45f4bedb60 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx
@@ -12,9 +12,9 @@ import {
   TextFormField,
 } from "@/components/Field";
 import Button from "@/refresh-components/buttons/Button";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import DocumentSetCard from "@/sections/cards/DocumentSetCard";
-import CollapsibleSection from "@/app/admin/assistants/CollapsibleSection";
+import CollapsibleSection from "@/app/admin/agents/CollapsibleSection";
 import { StandardAnswerCategoryResponse } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 import { StandardAnswerCategoryDropdownField } from "@/components/standardAnswers/StandardAnswerCategoryDropdown";
 import { RadioGroup } from "@/components/ui/radio-group";
@@ -45,8 +45,8 @@ export interface SlackChannelConfigFormFieldsProps {
   isUpdate: boolean;
   isDefault: boolean;
   documentSets: DocumentSetSummary[];
-  searchEnabledAssistants: MinimalPersonaSnapshot[];
-  nonSearchAssistants: MinimalPersonaSnapshot[];
+  searchEnabledAgents: MinimalPersonaSnapshot[];
+  nonSearchAgents: MinimalPersonaSnapshot[];
   standardAnswerCategoryResponse: StandardAnswerCategoryResponse;
   slack_bot_id: number;
   formikProps: any;
@@ -56,8 +56,8 @@ export function SlackChannelConfigFormFields({
   isUpdate,
   isDefault,
   documentSets,
-  searchEnabledAssistants,
-  nonSearchAssistants,
+  searchEnabledAgents,
+  nonSearchAgents,
   standardAnswerCategoryResponse,
   slack_bot_id,
   formikProps,
@@ -65,8 +65,7 @@ export function SlackChannelConfigFormFields({
   const router = useRouter();
   const { values, setFieldValue } = useFormikContext<any>();
   const [viewUnselectableSets, setViewUnselectableSets] = useState(false);
-  const [viewSyncEnabledAssistants, setViewSyncEnabledAssistants] =
-    useState(false);
+  const [viewSyncEnabledAgents, setViewSyncEnabledAgents] = useState(false);
 
   // Helper function to check if a document set contains sync connectors
   const documentSetContainsSync = (documentSet: DocumentSetSummary) => {
@@ -87,11 +86,11 @@ export function SlackChannelConfigFormFields({
     return documentSet.cc_pair_summaries;
   };
 
-  const [syncEnabledAssistants, availableAssistants] = useMemo(() => {
+  const [syncEnabledAgents, availableAgents] = useMemo(() => {
     const sync: MinimalPersonaSnapshot[] = [];
     const available: MinimalPersonaSnapshot[] = [];
 
-    searchEnabledAssistants.forEach((persona) => {
+    searchEnabledAgents.forEach((persona) => {
       const hasSyncSet = persona.document_sets.some(documentSetContainsSync);
       if (hasSyncSet) {
         sync.push(persona);
@@ -101,7 +100,7 @@ export function SlackChannelConfigFormFields({
     });
 
     return [sync, available];
-  }, [searchEnabledAssistants]);
+  }, [searchEnabledAgents]);
 
   const unselectableSets = useMemo(() => {
     return documentSets.filter(documentSetContainsSync);
@@ -151,10 +150,10 @@ export function SlackChannelConfigFormFields({
       );
       return selectedSets.some((ds) => documentSetContainsPrivate(ds));
     } else if (values.knowledge_source === "assistant") {
-      const chosenAssistant = searchEnabledAssistants.find(
+      const chosenAgent = searchEnabledAgents.find(
         (p) => p.id == values.persona_id
       );
-      return chosenAssistant?.document_sets.some((ds) =>
+      return chosenAgent?.document_sets.some((ds) =>
         documentSetContainsPrivate(ds)
       );
     }
@@ -228,8 +227,8 @@ export function SlackChannelConfigFormFields({
               sublabel="Control both the documents and the prompt to use for answering questions"
             />
             <RadioGroupItemField
-              value="non_search_assistant"
-              id="non_search_assistant"
+              value="non_search_agent"
+              id="non_search_agent"
               label="Non-Search Agent"
               sublabel="Chat with an agent that does not use documents"
             />
@@ -329,7 +328,7 @@ export function SlackChannelConfigFormFields({
               <>
                 Select the search-enabled agent OnyxBot will use while answering
                 questions in Slack.
-                {syncEnabledAssistants.length > 0 && (
+                {syncEnabledAgents.length > 0 && (
                   <>
                     <br />
                     <span className="text-sm text-text-dark/80">
@@ -339,14 +338,13 @@ export function SlackChannelConfigFormFields({
                       <button
                         type="button"
                         onClick={() =>
-                          setViewSyncEnabledAssistants(
-                            (viewSyncEnabledAssistants) =>
-                              !viewSyncEnabledAssistants
+                          setViewSyncEnabledAgents(
+                            (viewSyncEnabledAgents) => !viewSyncEnabledAgents
                           )
                         }
                         className="text-sm text-action-link-05"
                       >
-                        {viewSyncEnabledAssistants
+                        {viewSyncEnabledAgents
                           ? "Hide un-selectable "
                           : "View all "}
                         agents
@@ -359,44 +357,42 @@ export function SlackChannelConfigFormFields({
 
             <SelectorFormField
               name="persona_id"
-              options={availableAssistants.map((persona) => ({
+              options={availableAgents.map((persona) => ({
                 name: persona.name,
                 value: persona.id,
               }))}
             />
-            {viewSyncEnabledAssistants && syncEnabledAssistants.length > 0 && (
+            {viewSyncEnabledAgents && syncEnabledAgents.length > 0 && (
               <div className="mt-4">
                 <p className="text-sm text-text-dark/80">
                   Un-selectable agents:
                 </p>
                 <div className="mb-3 mt-2 flex gap-2 flex-wrap text-sm">
-                  {syncEnabledAssistants.map(
-                    (persona: MinimalPersonaSnapshot) => (
-                      <button
-                        type="button"
-                        onClick={() =>
-                          router.push(`/app/agents/edit/${persona.id}` as Route)
-                        }
-                        key={persona.id}
-                        className="p-2 bg-background-100 cursor-pointer rounded-md flex items-center gap-2"
-                      >
-                        <AgentAvatar agent={persona} size={16} />
-                        {persona.name}
-                      </button>
-                    )
-                  )}
+                  {syncEnabledAgents.map((persona: MinimalPersonaSnapshot) => (
+                    <button
+                      type="button"
+                      onClick={() =>
+                        router.push(`/app/agents/edit/${persona.id}` as Route)
+                      }
+                      key={persona.id}
+                      className="p-2 bg-background-100 cursor-pointer rounded-md flex items-center gap-2"
+                    >
+                      <AgentAvatar agent={persona} size={16} />
+                      {persona.name}
+                    </button>
+                  ))}
                 </div>
               </div>
             )}
           </div>
         )}
-        {values.knowledge_source === "non_search_assistant" && (
+        {values.knowledge_source === "non_search_agent" && (
           <div className="mt-4">
             <SubLabel>
               <>
                 Select the non-search agent OnyxBot will use while answering
                 questions in Slack.
-                {syncEnabledAssistants.length > 0 && (
+                {syncEnabledAgents.length > 0 && (
                   <>
                     <br />
                     <span className="text-sm text-text-dark/80">
@@ -406,14 +402,13 @@ export function SlackChannelConfigFormFields({
                       <button
                         type="button"
                         onClick={() =>
-                          setViewSyncEnabledAssistants(
-                            (viewSyncEnabledAssistants) =>
-                              !viewSyncEnabledAssistants
+                          setViewSyncEnabledAgents(
+                            (viewSyncEnabledAgents) => !viewSyncEnabledAgents
                           )
                         }
                         className="text-sm text-action-link-05"
                       >
-                        {viewSyncEnabledAssistants
+                        {viewSyncEnabledAgents
                           ? "Hide un-selectable "
                           : "View all "}
                         agents
@@ -426,7 +421,7 @@ export function SlackChannelConfigFormFields({
 
             <SelectorFormField
               name="persona_id"
-              options={nonSearchAssistants.map((persona) => ({
+              options={nonSearchAgents.map((persona) => ({
                 name: persona.name,
                 value: persona.id,
               }))}
@@ -436,7 +431,7 @@ export function SlackChannelConfigFormFields({
       </div>
       <Separator className="my-4" />
       <Accordion type="multiple" className="gap-y-2 w-full">
-        {values.knowledge_source !== "non_search_assistant" && (
+        {values.knowledge_source !== "non_search_agent" && (
           <AccordionItem value="search-options">
             <AccordionTrigger className="text-text">
               Search Configuration
diff --git a/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx b/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
index a6cb2d0ed2b..e0e69d67972 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
@@ -10,7 +10,7 @@ import {
 } from "@/lib/types";
 import BackButton from "@/refresh-components/buttons/BackButton";
 import { InstantSSRAutoRefresh } from "@/components/SSRAutoRefresh";
-import { FetchAssistantsResponse, fetchAssistantsSS } from "@/lib/agentsSS";
+import { FetchAgentsResponse, fetchAgentsSS } from "@/lib/agentsSS";
 import { getStandardAnswerCategoriesIfEE } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 
 async function EditslackChannelConfigPage(props: {
@@ -20,18 +20,14 @@ async function EditslackChannelConfigPage(props: {
   const tasks = [
     fetchSS("/manage/admin/slack-app/channel"),
     fetchSS("/manage/document-set"),
-    fetchAssistantsSS(),
+    fetchAgentsSS(),
   ];
 
   const [
     slackChannelsResponse,
     documentSetsResponse,
-    [assistants, assistantsFetchError],
-  ] = (await Promise.all(tasks)) as [
-    Response,
-    Response,
-    FetchAssistantsResponse,
-  ];
+    [assistants, agentsFetchError],
+  ] = (await Promise.all(tasks)) as [Response, Response, FetchAgentsResponse];
 
   const eeStandardAnswerCategoryResponse =
     await getStandardAnswerCategoriesIfEE();
@@ -71,11 +67,11 @@ async function EditslackChannelConfigPage(props: {
   const response = await documentSetsResponse.json();
   const documentSets = response as DocumentSetSummary[];
 
-  if (assistantsFetchError) {
+  if (agentsFetchError) {
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch personas - ${assistantsFetchError}`}
+        errorMsg={`Failed to fetch personas - ${agentsFetchError}`}
       />
     );
   }
diff --git a/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx b/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
index dae7aa1d42d..7094043e364 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
@@ -4,7 +4,7 @@ import { fetchSS } from "@/lib/utilsSS";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { DocumentSetSummary, ValidSources } from "@/lib/types";
 import BackButton from "@/refresh-components/buttons/BackButton";
-import { fetchAssistantsSS } from "@/lib/agentsSS";
+import { fetchAgentsSS } from "@/lib/agentsSS";
 import { getStandardAnswerCategoriesIfEE } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 import { redirect } from "next/navigation";
 import { SourceIcon } from "@/components/SourceIcon";
@@ -22,15 +22,12 @@ async function NewChannelConfigPage(props: {
     return null;
   }
 
-  const [
-    documentSetsResponse,
-    assistantsResponse,
-    standardAnswerCategoryResponse,
-  ] = await Promise.all([
-    fetchSS("/manage/document-set") as Promise<Response>,
-    fetchAssistantsSS(),
-    getStandardAnswerCategoriesIfEE(),
-  ]);
+  const [documentSetsResponse, agentsResponse, standardAnswerCategoryResponse] =
+    await Promise.all([
+      fetchSS("/manage/document-set") as Promise<Response>,
+      fetchAgentsSS(),
+      getStandardAnswerCategoriesIfEE(),
+    ]);
 
   if (!documentSetsResponse.ok) {
     return (
@@ -43,11 +40,11 @@ async function NewChannelConfigPage(props: {
   const documentSets =
     (await documentSetsResponse.json()) as DocumentSetSummary[];
 
-  if (assistantsResponse[1]) {
+  if (agentsResponse[1]) {
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch assistants - ${assistantsResponse[1]}`}
+        errorMsg={`Failed to fetch agents - ${agentsResponse[1]}`}
       />
     );
   }
@@ -63,7 +60,7 @@ async function NewChannelConfigPage(props: {
       <SlackChannelConfigCreationForm
         slack_bot_id={slack_bot_id}
         documentSets={documentSets}
-        personas={assistantsResponse[0]}
+        personas={agentsResponse[0]}
         standardAnswerCategoryResponse={standardAnswerCategoryResponse}
       />
     </>
diff --git a/web/src/app/admin/bots/[bot-id]/lib.ts b/web/src/app/admin/bots/[bot-id]/lib.ts
index 5a1e506b96b..2da011ecc56 100644
--- a/web/src/app/admin/bots/[bot-id]/lib.ts
+++ b/web/src/app/admin/bots/[bot-id]/lib.ts
@@ -1,5 +1,5 @@
 import { SlackBotResponseType } from "@/lib/types";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 interface SlackChannelConfigCreationRequest {
   slack_bot_id: number;
diff --git a/web/src/app/admin/connectors/[connector]/pages/FieldRendering.tsx b/web/src/app/admin/connectors/[connector]/pages/FieldRendering.tsx
index 0ced4437a27..c6326570b94 100644
--- a/web/src/app/admin/connectors/[connector]/pages/FieldRendering.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/FieldRendering.tsx
@@ -7,7 +7,7 @@ import ListInput from "./ConnectorInput/ListInput";
 import FileInput from "./ConnectorInput/FileInput";
 import { ConfigurableSources } from "@/lib/types";
 import { Credential } from "@/lib/connectors/credentials";
-import CollapsibleSection from "@/app/admin/assistants/CollapsibleSection";
+import CollapsibleSection from "@/app/admin/agents/CollapsibleSection";
 import Tabs from "@/refresh-components/Tabs";
 import { useFormikContext } from "formik";
 import * as GeneralLayouts from "@/layouts/general-layouts";
diff --git a/web/src/app/admin/discord-bot/[guild-id]/DiscordChannelsTable.tsx b/web/src/app/admin/discord-bot/[guild-id]/DiscordChannelsTable.tsx
index b2bdca3c674..07193c6709c 100644
--- a/web/src/app/admin/discord-bot/[guild-id]/DiscordChannelsTable.tsx
+++ b/web/src/app/admin/discord-bot/[guild-id]/DiscordChannelsTable.tsx
@@ -19,7 +19,7 @@ import {
 } from "@/app/admin/discord-bot/types";
 import { SvgHash, SvgBubbleText, SvgLock } from "@opal/icons";
 import { IconProps } from "@opal/types";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 function getChannelIcon(
   channelType: DiscordChannelType,
diff --git a/web/src/app/admin/discord-bot/[guild-id]/page.tsx b/web/src/app/admin/discord-bot/[guild-id]/page.tsx
index c3a569dc90e..f2f7f1b425e 100644
--- a/web/src/app/admin/discord-bot/[guild-id]/page.tsx
+++ b/web/src/app/admin/discord-bot/[guild-id]/page.tsx
@@ -26,7 +26,7 @@ import {
 import { DiscordChannelsTable } from "@/app/admin/discord-bot/[guild-id]/DiscordChannelsTable";
 import { DiscordChannelConfig } from "@/app/admin/discord-bot/types";
 import { useAdminPersonas } from "@/hooks/useAdminPersonas";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 interface Props {
   params: Promise<{ "guild-id": string }>;
diff --git a/web/src/app/app/components/AgentDescription.tsx b/web/src/app/app/components/AgentDescription.tsx
index 380045807a0..fb9ff6bf367 100644
--- a/web/src/app/app/components/AgentDescription.tsx
+++ b/web/src/app/app/components/AgentDescription.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import Text from "@/refresh-components/texts/Text";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 
 export interface AgentDescriptionProps {
   agent?: MinimalPersonaSnapshot;
diff --git a/web/src/app/app/components/WelcomeMessage.tsx b/web/src/app/app/components/WelcomeMessage.tsx
index 876ada6c1f9..66f087c08a9 100644
--- a/web/src/app/app/components/WelcomeMessage.tsx
+++ b/web/src/app/app/components/WelcomeMessage.tsx
@@ -7,7 +7,7 @@ import {
 } from "@/lib/chat/greetingMessages";
 import AgentAvatar from "@/refresh-components/avatars/AgentAvatar";
 import Text from "@/refresh-components/texts/Text";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { useState, useEffect } from "react";
 import { useSettingsContext } from "@/providers/SettingsProvider";
 import FrostedDiv from "@/refresh-components/FrostedDiv";
@@ -50,7 +50,7 @@ export default function WelcomeMessage({
     content = (
       <>
         <div
-          data-testid="assistant-name-display"
+          data-testid="agent-name-display"
           className="flex flex-row items-center gap-3"
         >
           <AgentAvatar agent={agent} size={36} />
diff --git a/web/src/app/app/components/projects/ProjectChatSessionList.tsx b/web/src/app/app/components/projects/ProjectChatSessionList.tsx
index 75519ff1f47..388a2b3f0a5 100644
--- a/web/src/app/app/components/projects/ProjectChatSessionList.tsx
+++ b/web/src/app/app/components/projects/ProjectChatSessionList.tsx
@@ -21,7 +21,7 @@ export default function ProjectChatSessionList() {
     refreshCurrentProjectDetails,
     isLoadingProjectDetails,
   } = useProjectsContext();
-  const { agents: assistants } = useAgents();
+  const { agents } = useAgents();
   const [isRenamingChat, setIsRenamingChat] = React.useState<string | null>(
     null
   );
@@ -78,13 +78,13 @@ export default function ProjectChatSessionList() {
                         currentProjectDetails?.persona_id_to_featured || {};
                       const isFeatured = personaIdToFeatured[chat.persona_id];
                       if (isFeatured === false) {
-                        const assistant = assistants.find(
+                        const agent = agents.find(
                           (a) => a.id === chat.persona_id
                         );
-                        if (assistant) {
+                        if (agent) {
                           return (
                             <div className="h-full pt-1">
-                              <AgentAvatar agent={assistant} size={18} />
+                              <AgentAvatar agent={agent} size={18} />
                             </div>
                           );
                         }
diff --git a/web/src/app/app/interfaces.ts b/web/src/app/app/interfaces.ts
index 5bc3ed7b67d..51547090a6e 100644
--- a/web/src/app/app/interfaces.ts
+++ b/web/src/app/app/interfaces.ts
@@ -141,7 +141,7 @@ export interface Message {
   messageId?: number;
   nodeId: number; // Unique identifier for tree structure (can be negative for temp messages)
   message: string;
-  type: "user" | "assistant" | "system" | "error";
+  type: "user" | "assistant" | "system" | "error"; // TODO: rename "assistant" to "agent" — https://linear.app/onyx-app/issue/ENG-3766
   retrievalType?: RetrievalType;
   researchType?: ResearchType;
   query?: string | null;
@@ -151,7 +151,7 @@ export interface Message {
   parentNodeId: number | null;
   childrenNodeIds?: number[];
   latestChildNodeId?: number | null;
-  alternateAssistantID?: number | null;
+  alternateAgentID?: number | null;
   stackTrace?: string | null;
   errorCode?: string | null;
   isRetryable?: boolean;
@@ -170,7 +170,7 @@ export interface Message {
   // feedback state
   currentFeedback?: FeedbackType | null;
 
-  // Duration in seconds for processing this message (assistant messages only)
+  // Duration in seconds for processing this message (agent messages only)
   processingDurationSeconds?: number;
 }
 
@@ -216,13 +216,13 @@ export interface BackendMessage {
   context_docs: OnyxDocument[] | null;
   time_sent: string;
   overridden_model: string;
-  alternate_assistant_id: number | null;
+  alternate_assistant_id: number | null; // TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
   chat_session_id: string;
   citations: CitationMap | null;
   files: FileDescriptor[];
   tool_call: ToolCallFinalResult | null;
   current_feedback: string | null;
-  // Duration in seconds for processing this message (assistant messages only)
+  // Duration in seconds for processing this message (agent messages only)
   processing_duration_seconds?: number;
 
   sub_questions: SubQuestionDetail[];
@@ -235,7 +235,7 @@ export interface BackendMessage {
 
 export interface MessageResponseIDInfo {
   user_message_id: number | null;
-  reserved_assistant_message_id: number;
+  reserved_assistant_message_id: number; // TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
 }
 
 export interface UserKnowledgeFilePacket {
diff --git a/web/src/app/app/message/messageComponents/AgentMessage.tsx b/web/src/app/app/message/messageComponents/AgentMessage.tsx
index 467dc07ab87..96144eb8d22 100644
--- a/web/src/app/app/message/messageComponents/AgentMessage.tsx
+++ b/web/src/app/app/message/messageComponents/AgentMessage.tsx
@@ -36,7 +36,7 @@ export interface AgentMessageProps {
   onRegenerate?: RegenerationFactory;
   // Parent message needed to construct regeneration request
   parentMessage?: Message | null;
-  // Duration in seconds for processing this message (assistant messages only)
+  // Duration in seconds for processing this message (agent messages only)
   processingDurationSeconds?: number;
 }
 
@@ -55,7 +55,7 @@ function arePropsEqual(
     // Compare packetCount (primitive) instead of rawPackets.length
     // The array is mutated in place, so reading .length from prev and next would return same value
     prev.packetCount === next.packetCount &&
-    prev.chatState.assistant?.id === next.chatState.assistant?.id &&
+    prev.chatState.agent?.id === next.chatState.agent?.id &&
     prev.chatState.docs === next.chatState.docs &&
     prev.chatState.citations === next.chatState.citations &&
     prev.chatState.overriddenModel === next.chatState.overriddenModel &&
@@ -137,7 +137,7 @@ const AgentMessage = React.memo(function AgentMessage({
       citations: mergedCitations,
     }),
     [
-      chatState.assistant,
+      chatState.agent,
       chatState.docs,
       chatState.setPresentingDocument,
       chatState.overriddenModel,
diff --git a/web/src/app/app/message/messageComponents/interfaces.ts b/web/src/app/app/message/messageComponents/interfaces.ts
index f8d36ef67d4..dadb518259a 100644
--- a/web/src/app/app/message/messageComponents/interfaces.ts
+++ b/web/src/app/app/message/messageComponents/interfaces.ts
@@ -1,5 +1,5 @@
 import { JSX } from "react";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { Packet, StopReason } from "../../services/streamingModels";
 import { OnyxDocument, MinimalOnyxDocument } from "@/lib/search/interfaces";
 import { ProjectFile } from "../../projects/projectsService";
@@ -23,7 +23,7 @@ export enum RenderType {
 export type TimelineLayout = "timeline" | "content";
 
 export interface FullChatState {
-  assistant: MinimalPersonaSnapshot;
+  agent: MinimalPersonaSnapshot;
   // Document-related context for citations
   docs?: OnyxDocument[] | null;
   userFiles?: ProjectFile[];
diff --git a/web/src/app/app/message/messageComponents/renderMessageComponent.tsx b/web/src/app/app/message/messageComponents/renderMessageComponent.tsx
index 683d1a74786..b41576c6efd 100644
--- a/web/src/app/app/message/messageComponents/renderMessageComponent.tsx
+++ b/web/src/app/app/message/messageComponents/renderMessageComponent.tsx
@@ -222,7 +222,7 @@ function areRendererPropsEqual(
     prev.stopPacketSeen === next.stopPacketSeen &&
     prev.stopReason === next.stopReason &&
     prev.animate === next.animate &&
-    prev.chatState.assistant?.id === next.chatState.assistant?.id
+    prev.chatState.agent?.id === next.chatState.agent?.id
     // Skip: onComplete, children (function refs), chatState (memoized upstream)
   );
 }
diff --git a/web/src/app/app/message/messageComponents/timeline/AgentTimeline.tsx b/web/src/app/app/message/messageComponents/timeline/AgentTimeline.tsx
index 19db8daf161..9e6dc54ce76 100644
--- a/web/src/app/app/message/messageComponents/timeline/AgentTimeline.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/AgentTimeline.tsx
@@ -36,7 +36,7 @@ import { TimelineHeaderRow } from "@/app/app/message/messageComponents/timeline/
 // =============================================================================
 
 interface TimelineContainerProps {
-  agent: FullChatState["assistant"];
+  agent: FullChatState["agent"];
   headerContent?: React.ReactNode;
   children?: React.ReactNode;
 }
@@ -343,7 +343,7 @@ export const AgentTimeline = React.memo(function AgentTimeline({
   if (uiState === TimelineUIState.EMPTY) {
     return (
       <TimelineContainer
-        agent={chatState.assistant}
+        agent={chatState.agent}
         headerContent={
           <div className="flex w-full h-full items-center pl-[var(--timeline-header-padding-left)] pr-[var(--timeline-header-padding-right)]">
             <Text
@@ -362,12 +362,12 @@ export const AgentTimeline = React.memo(function AgentTimeline({
 
   // Display content only (no timeline steps) - but show header for image generation
   if (uiState === TimelineUIState.DISPLAY_CONTENT_ONLY) {
-    return <TimelineContainer agent={chatState.assistant} />;
+    return <TimelineContainer agent={chatState.agent} />;
   }
 
   return (
     <TimelineContainer
-      agent={chatState.assistant}
+      agent={chatState.agent}
       headerContent={
         <div
           className={cn(
diff --git a/web/src/app/app/services/actionUtils.ts b/web/src/app/app/services/actionUtils.ts
index c85156dfe94..ea2192920bb 100644
--- a/web/src/app/app/services/actionUtils.ts
+++ b/web/src/app/app/services/actionUtils.ts
@@ -59,7 +59,7 @@ export function getIconForAction(
   return SvgCpu;
 }
 
-// Check if the assistant has either search tool or web search tool available
+// Check if the agent has either search tool or web search tool available
 export function hasSearchToolsAvailable(tools: ToolSnapshot[]): boolean {
   return tools.some((tool) => isSearchTool(tool) || isWebSearchTool(tool));
 }
diff --git a/web/src/app/app/services/lib.tsx b/web/src/app/app/services/lib.tsx
index 56af04d6a01..b89a29741e3 100644
--- a/web/src/app/app/services/lib.tsx
+++ b/web/src/app/app/services/lib.tsx
@@ -18,7 +18,7 @@ import {
   ToolCallMetadata,
   UserKnowledgeFilePacket,
 } from "../interfaces";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { ReadonlyURLSearchParams } from "next/navigation";
 import { SEARCH_PARAM_NAMES } from "./searchParams";
 import { WEB_SEARCH_TOOL_ID } from "@/app/app/components/tools/constants";
@@ -306,12 +306,12 @@ export function processRawChatHistory(
   const messages: Map<number, Message> = new Map();
   const parentMessageChildrenMap: Map<number, number[]> = new Map();
 
-  let assistantMessageInd = 0;
+  let agentMessageInd = 0;
 
   rawMessages.forEach((messageInfo, _ind) => {
-    const packetsForMessage = packets[assistantMessageInd];
+    const packetsForMessage = packets[agentMessageInd];
     if (messageInfo.message_type === "assistant") {
-      assistantMessageInd++;
+      agentMessageInd++;
     }
 
     const hasContextDocs = (messageInfo?.context_docs || []).length > 0;
@@ -334,11 +334,11 @@ export function processRawChatHistory(
       message: messageInfo.message,
       type: messageInfo.message_type as "user" | "assistant",
       files: messageInfo.files,
-      alternateAssistantID:
+      alternateAgentID:
         messageInfo.alternate_assistant_id !== null
           ? Number(messageInfo.alternate_assistant_id)
           : null,
-      // only include these fields if this is an assistant message so that
+      // only include these fields if this is an agent message so that
       // this is identical to what is computed at streaming time
       ...(messageInfo.message_type === "assistant"
         ? {
diff --git a/web/src/app/app/services/messageTree.ts b/web/src/app/app/services/messageTree.ts
index 66adb917c20..2550f0ac63e 100644
--- a/web/src/app/app/services/messageTree.ts
+++ b/web/src/app/app/services/messageTree.ts
@@ -320,7 +320,7 @@ export function getHumanAndAIMessageFromMessageNumber(
     if (!message) return { humanMessage: null, aiMessage: null };
 
     if (message.type === "user") {
-      // Find its latest child that is an assistant
+      // Find its latest child that is an agent
       const potentialAiMessage =
         message.latestChildNodeId !== null &&
         message.latestChildNodeId !== undefined
@@ -437,7 +437,7 @@ export const buildImmediateMessages = (
   messageToResend?: Message
 ): {
   initialUserNode: Message;
-  initialAssistantNode: Message;
+  initialAgentNode: Message;
 } => {
   // Always create a NEW message with a new nodeId for proper branching.
   // When editing (messageToResend exists), this creates a sibling to the original
@@ -448,17 +448,17 @@ export const buildImmediateMessages = (
     message: userInput,
     files,
   });
-  const initialAssistantNode = buildEmptyMessage({
+  const initialAgentNode = buildEmptyMessage({
     messageType: "assistant",
     parentNodeId: initialUserNode.nodeId,
     nodeIdOffset: 1,
   });
 
-  initialUserNode.childrenNodeIds = [initialAssistantNode.nodeId];
-  initialUserNode.latestChildNodeId = initialAssistantNode.nodeId;
+  initialUserNode.childrenNodeIds = [initialAgentNode.nodeId];
+  initialUserNode.latestChildNodeId = initialAgentNode.nodeId;
 
   return {
     initialUserNode,
-    initialAssistantNode,
+    initialAgentNode,
   };
 };
diff --git a/web/src/app/app/services/searchParams.ts b/web/src/app/app/services/searchParams.ts
index e4a04ec0b86..b45597ee840 100644
--- a/web/src/app/app/services/searchParams.ts
+++ b/web/src/app/app/services/searchParams.ts
@@ -4,7 +4,7 @@ import { ReadonlyURLSearchParams } from "next/navigation";
 export const SEARCH_PARAM_NAMES = {
   CHAT_ID: "chatId",
   SEARCH_ID: "searchId",
-  PERSONA_ID: "assistantId",
+  PERSONA_ID: "agentId",
   PROJECT_ID: "projectId",
   ALL_MY_DOCUMENTS: "allMyDocuments",
   // overrides
diff --git a/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx b/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx
index 654ace58f6f..9649727753f 100644
--- a/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx
+++ b/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx
@@ -9,7 +9,7 @@ import HumanMessage from "@/app/app/message/HumanMessage";
 import AgentMessage from "@/app/app/message/messageComponents/AgentMessage";
 import { Callout } from "@/components/ui/callout";
 import OnyxInitializingLoader from "@/components/OnyxInitializingLoader";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import TextViewModal from "@/sections/modals/TextViewModal";
 import { UNNAMED_CHAT } from "@/lib/constants";
@@ -106,7 +106,7 @@ export default function SharedChatDisplay({
                       key={message.messageId}
                       rawPackets={message.packets}
                       chatState={{
-                        assistant: persona,
+                        agent: persona,
                         docs: message.documents,
                         citations: message.citations,
                         setPresentingDocument: setPresentingDocument,
diff --git a/web/src/app/app/shared/[chatId]/page.tsx b/web/src/app/app/shared/[chatId]/page.tsx
index 03d97b4298c..6047974a85c 100644
--- a/web/src/app/app/shared/[chatId]/page.tsx
+++ b/web/src/app/app/shared/[chatId]/page.tsx
@@ -4,7 +4,7 @@ import type { Route } from "next";
 import { requireAuth } from "@/lib/auth/requireAuth";
 import SharedChatDisplay from "@/app/app/shared/[chatId]/SharedChatDisplay";
 import * as AppLayouts from "@/layouts/app-layouts";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 // This is used for rendering a persona in the shared chat display
 export function constructMiniFiedPersona(name: string, id: number): Persona {
diff --git a/web/src/app/craft/components/BuildMessageList.tsx b/web/src/app/craft/components/BuildMessageList.tsx
index 025f58d0b4f..cd7e2f90d23 100644
--- a/web/src/app/craft/components/BuildMessageList.tsx
+++ b/web/src/app/craft/components/BuildMessageList.tsx
@@ -78,7 +78,7 @@ interface BuildMessageListProps {
  * BuildMessageList - Displays the conversation history with FIFO rendering
  *
  * User messages are shown as right-aligned bubbles.
- * Assistant responses render streamItems in exact chronological order:
+ * Agent responses render streamItems in exact chronological order:
  * text, thinking, and tool calls appear exactly as they arrived.
  */
 export default function BuildMessageList({
@@ -161,8 +161,8 @@ export default function BuildMessageList({
     });
   };
 
-  // Helper to render an assistant message
-  const renderAssistantMessage = (message: BuildMessage) => {
+  // Helper to render an agent message
+  const renderAgentMessage = (message: BuildMessage) => {
     // Check if we have saved stream items in message_metadata
     const savedStreamItems = message.message_metadata?.streamItems as
       | StreamItem[]
@@ -189,12 +189,12 @@ export default function BuildMessageList({
   return (
     <div className="flex flex-col items-center px-4 pb-4">
       <div className="w-full max-w-2xl backdrop-blur-md rounded-16 p-4">
-        {/* Render messages in order (user and assistant interleaved) */}
+        {/* Render messages in order (user and agent interleaved) */}
         {messages.map((message) =>
           message.type === "user" ? (
             <UserMessage key={message.id} content={message.content} />
           ) : message.type === "assistant" ? (
-            renderAssistantMessage(message)
+            renderAgentMessage(message)
           ) : null
         )}
 
diff --git a/web/src/app/craft/components/ChatPanel.tsx b/web/src/app/craft/components/ChatPanel.tsx
index 3abecea59ed..c8a8b04d768 100644
--- a/web/src/app/craft/components/ChatPanel.tsx
+++ b/web/src/app/craft/components/ChatPanel.tsx
@@ -233,18 +233,18 @@ export default function BuildChatPanel({
     inputBarRef.current?.setMessage(text);
   }, []);
 
-  // Check if assistant has finished streaming at least one message
-  // Show banner only after first assistant message completes streaming
+  // Check if agent has finished streaming at least one message
+  // Show banner only after first agent message completes streaming
   const shouldShowConnectorBanner = useMemo(() => {
     // Don't show if currently streaming
     if (isRunning) {
       return false;
     }
-    // Check if there's at least one assistant message in the session
-    const hasAssistantMessage = session?.messages?.some(
+    // Check if there's at least one agent message in the session
+    const hasAgentMessage = session?.messages?.some(
       (msg) => msg.type === "assistant"
     );
-    return hasAssistantMessage ?? false;
+    return hasAgentMessage ?? false;
   }, [isRunning, session?.messages]);
 
   const handleSubmit = useCallback(
@@ -466,7 +466,7 @@ export default function BuildChatPanel({
                   </SimpleTooltip>
                 </div>
               )}
-              {/* Follow-up suggestion bubbles - show after first assistant message */}
+              {/* Follow-up suggestion bubbles - show after first agent message */}
               {(followupSuggestions || suggestionsLoading) && (
                 <div className="mb-3">
                   <SuggestionBubbles
@@ -476,7 +476,7 @@ export default function BuildChatPanel({
                   />
                 </div>
               )}
-              {/* Connector banners - show after first assistant message finishes streaming */}
+              {/* Connector banners - show after first agent message finishes streaming */}
               {shouldShowConnectorBanner && (
                 <ConnectorBannersRow className="" />
               )}
diff --git a/web/src/app/craft/components/ConnectorBannersRow.tsx b/web/src/app/craft/components/ConnectorBannersRow.tsx
index 24e9aa33d8f..9b044ded1b8 100644
--- a/web/src/app/craft/components/ConnectorBannersRow.tsx
+++ b/web/src/app/craft/components/ConnectorBannersRow.tsx
@@ -30,7 +30,7 @@ function IconWrapper({ children }: { children: React.ReactNode }) {
 }
 
 /**
- * Row of two banners that appear above the InputBar after first assistant response.
+ * Row of two banners that appear above the InputBar after first agent response.
  * - Left: "Connect your data" - exact same look as welcome page banner, but flipped
  * - Right: "Get help setting up connectors" - links to cal.com booking
  *
diff --git a/web/src/app/craft/components/SuggestionBubbles.tsx b/web/src/app/craft/components/SuggestionBubbles.tsx
index fb74295ce61..2ffe3040506 100644
--- a/web/src/app/craft/components/SuggestionBubbles.tsx
+++ b/web/src/app/craft/components/SuggestionBubbles.tsx
@@ -24,7 +24,7 @@ function getThemeStyles(theme: string): string {
 }
 
 /**
- * Displays follow-up suggestion bubbles after the first assistant message.
+ * Displays follow-up suggestion bubbles after the first agent message.
  * Styled like user chat messages - stacked vertically and right-aligned.
  * Each bubble is clickable and populates the input bar with the suggestion text.
  */
diff --git a/web/src/app/craft/hooks/useBuildSessionStore.ts b/web/src/app/craft/hooks/useBuildSessionStore.ts
index f8c00920ef1..37445b1ca5e 100644
--- a/web/src/app/craft/hooks/useBuildSessionStore.ts
+++ b/web/src/app/craft/hooks/useBuildSessionStore.ts
@@ -51,7 +51,7 @@ import { parsePacket } from "@/app/craft/utils/parsePacket";
  * - tool_call_progress: Full tool call data with status="completed"
  * - agent_plan_update: Plan entries (not rendered as stream items)
  *
- * This function converts assistant messages to StreamItem[] for rendering.
+ * This function converts agent messages to StreamItem[] for rendering.
  */
 function convertMessagesToStreamItems(messages: BuildMessage[]): StreamItem[] {
   const items: StreamItem[] = [];
@@ -149,40 +149,38 @@ function convertMessagesToStreamItems(messages: BuildMessage[]): StreamItem[] {
  * Consolidate raw backend messages into proper conversation turns.
  *
  * The backend stores each streaming packet as a separate message. This function:
- * 1. Groups consecutive assistant messages (between user messages) into turns
+ * 1. Groups consecutive agent messages (between user messages) into turns
  * 2. Converts each group's packets to streamItems
  * 3. Creates consolidated messages with streamItems in message_metadata
  *
- * Returns: Array of consolidated messages (user messages + one assistant message per turn)
+ * Returns: Array of consolidated messages (user messages + one agent message per turn)
  */
 function consolidateMessagesIntoTurns(
   rawMessages: BuildMessage[]
 ): BuildMessage[] {
   const consolidated: BuildMessage[] = [];
-  let currentAssistantPackets: BuildMessage[] = [];
+  let currentAgentPackets: BuildMessage[] = [];
 
   for (const message of rawMessages) {
     if (message.type === "user") {
-      // If we have accumulated assistant packets, consolidate them into one message
-      if (currentAssistantPackets.length > 0) {
-        const streamItems = convertMessagesToStreamItems(
-          currentAssistantPackets
-        );
+      // If we have accumulated agent packets, consolidate them into one message
+      if (currentAgentPackets.length > 0) {
+        const streamItems = convertMessagesToStreamItems(currentAgentPackets);
         const textContent = streamItems
           .filter((item) => item.type === "text")
           .map((item) => item.content)
           .join("");
 
         consolidated.push({
-          id: currentAssistantPackets[0]?.id || genId("assistant-msg"),
+          id: currentAgentPackets[0]?.id || genId("agent-msg"),
           type: "assistant",
           content: textContent,
-          timestamp: currentAssistantPackets[0]?.timestamp || new Date(),
+          timestamp: currentAgentPackets[0]?.timestamp || new Date(),
           message_metadata: {
             streamItems,
           },
         });
-        currentAssistantPackets = [];
+        currentAgentPackets = [];
       }
       // Add the user message as-is
       consolidated.push(message);
@@ -190,48 +188,46 @@ function consolidateMessagesIntoTurns(
       // Check if this message already has consolidated streamItems (from new format)
       if (message.message_metadata?.streamItems) {
         // Already consolidated, add as-is
-        if (currentAssistantPackets.length > 0) {
+        if (currentAgentPackets.length > 0) {
           // Flush any pending packets first
-          const streamItems = convertMessagesToStreamItems(
-            currentAssistantPackets
-          );
+          const streamItems = convertMessagesToStreamItems(currentAgentPackets);
           const textContent = streamItems
             .filter((item) => item.type === "text")
             .map((item) => item.content)
             .join("");
 
           consolidated.push({
-            id: currentAssistantPackets[0]?.id || genId("assistant-msg"),
+            id: currentAgentPackets[0]?.id || genId("agent-msg"),
             type: "assistant",
             content: textContent,
-            timestamp: currentAssistantPackets[0]?.timestamp || new Date(),
+            timestamp: currentAgentPackets[0]?.timestamp || new Date(),
             message_metadata: {
               streamItems,
             },
           });
-          currentAssistantPackets = [];
+          currentAgentPackets = [];
         }
         consolidated.push(message);
       } else {
         // Old format - accumulate for consolidation
-        currentAssistantPackets.push(message);
+        currentAgentPackets.push(message);
       }
     }
   }
 
-  // Don't forget any trailing assistant packets
-  if (currentAssistantPackets.length > 0) {
-    const streamItems = convertMessagesToStreamItems(currentAssistantPackets);
+  // Don't forget any trailing agent packets
+  if (currentAgentPackets.length > 0) {
+    const streamItems = convertMessagesToStreamItems(currentAgentPackets);
     const textContent = streamItems
       .filter((item) => item.type === "text")
       .map((item) => item.content)
       .join("");
 
     consolidated.push({
-      id: currentAssistantPackets[0]?.id || genId("assistant-msg"),
+      id: currentAgentPackets[0]?.id || genId("agent-msg"),
       type: "assistant",
       content: textContent,
-      timestamp: currentAssistantPackets[0]?.timestamp || new Date(),
+      timestamp: currentAgentPackets[0]?.timestamp || new Date(),
       message_metadata: {
         streamItems,
       },
@@ -309,7 +305,7 @@ export interface BuildSessionData {
   /** Active tool calls for the current response */
   toolCalls: ToolCall[];
   /**
-   * FIFO stream items for the current assistant turn.
+   * FIFO stream items for the current agent turn.
    * Items are stored in chronological order as they arrive.
    * Rendered directly without transformation.
    */
@@ -336,7 +332,7 @@ export interface BuildSessionData {
   filesTabState: FilesTabState;
   /** Browser-style tab navigation history for back/forward */
   tabHistory: TabNavigationHistory;
-  /** Follow-up suggestions after first assistant message */
+  /** Follow-up suggestions after first agent message */
   followupSuggestions: SuggestionBubble[] | null;
   /** Whether suggestions are currently being generated */
   suggestionsLoading: boolean;
diff --git a/web/src/app/craft/hooks/useBuildStreaming.ts b/web/src/app/craft/hooks/useBuildStreaming.ts
index 4513f737c95..a93fc9b38b0 100644
--- a/web/src/app/craft/hooks/useBuildStreaming.ts
+++ b/web/src/app/craft/hooks/useBuildStreaming.ts
@@ -347,7 +347,7 @@ export function useBuildStreaming() {
                   .map((item) => item.content)
                   .join("");
 
-                const isFirstAssistantMessage =
+                const isFirstAgentMessage =
                   session.messages.filter((m) => m.type === "assistant")
                     .length === 0;
 
@@ -355,11 +355,7 @@ export function useBuildStreaming() {
                   (m) => m.type === "user"
                 );
 
-                if (
-                  isFirstAssistantMessage &&
-                  firstUserMessage &&
-                  textContent
-                ) {
+                if (isFirstAgentMessage && firstUserMessage && textContent) {
                   (async () => {
                     try {
                       setSuggestionsLoading(sessionId, true);
@@ -377,7 +373,7 @@ export function useBuildStreaming() {
                 }
 
                 appendMessageToSession(sessionId, {
-                  id: genId("assistant-msg"),
+                  id: genId("agent-msg"),
                   type: "assistant",
                   content: textContent,
                   timestamp: new Date(),
diff --git a/web/src/app/craft/services/apiServices.ts b/web/src/app/craft/services/apiServices.ts
index 17e04e2eca2..1c314577d1a 100644
--- a/web/src/app/craft/services/apiServices.ts
+++ b/web/src/app/craft/services/apiServices.ts
@@ -162,7 +162,7 @@ export interface SuggestionBubble {
 export async function generateFollowupSuggestions(
   sessionId: string,
   userMessage: string,
-  assistantMessage: string
+  agentMessage: string
 ): Promise<SuggestionBubble[]> {
   const res = await fetch(
     `${API_BASE}/sessions/${sessionId}/generate-suggestions`,
@@ -171,7 +171,7 @@ export async function generateFollowupSuggestions(
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         user_message: userMessage,
-        assistant_message: assistantMessage,
+        assistant_message: agentMessage,
       }),
     }
   );
diff --git a/web/src/app/craft/types/streamingTypes.ts b/web/src/app/craft/types/streamingTypes.ts
index 32b51ddd6fd..216a706b905 100644
--- a/web/src/app/craft/types/streamingTypes.ts
+++ b/web/src/app/craft/types/streamingTypes.ts
@@ -76,7 +76,7 @@ export interface BuildMessage {
   timestamp: Date;
   /** Structured ACP event data (tool calls, thinking, plans) */
   message_metadata?: Record<string, any> | null;
-  /** Tool calls associated with this message (for assistant messages) */
+  /** Tool calls associated with this message (for agent messages) */
   toolCalls?: ToolCall[];
 }
 
diff --git a/web/src/app/ee/admin/performance/usage/PersonaMessagesChart.tsx b/web/src/app/ee/admin/performance/usage/PersonaMessagesChart.tsx
index 096007ef06d..a13a075cff8 100644
--- a/web/src/app/ee/admin/performance/usage/PersonaMessagesChart.tsx
+++ b/web/src/app/ee/admin/performance/usage/PersonaMessagesChart.tsx
@@ -18,7 +18,7 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 import { useState, useMemo, useEffect } from "react";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 export function PersonaMessagesChart({
   availablePersonas,
diff --git a/web/src/app/ee/assistants/stats/[id]/AssistantStats.tsx b/web/src/app/ee/agents/stats/[id]/AgentStats.tsx
similarity index 74%
rename from web/src/app/ee/assistants/stats/[id]/AssistantStats.tsx
rename to web/src/app/ee/agents/stats/[id]/AgentStats.tsx
index 92901426343..bb192c1da37 100644
--- a/web/src/app/ee/assistants/stats/[id]/AssistantStats.tsx
+++ b/web/src/app/ee/agents/stats/[id]/AgentStats.tsx
@@ -12,22 +12,21 @@ import AgentAvatar from "@/refresh-components/avatars/AgentAvatar";
 import { Card, CardContent, CardHeader } from "@/components/ui/card";
 import { AreaChartDisplay } from "@/components/ui/areaChart";
 
-type AssistantDailyUsageEntry = {
+type AgentDailyUsageEntry = {
   date: string;
   total_messages: number;
   total_unique_users: number;
 };
 
-type AssistantStatsResponse = {
-  daily_stats: AssistantDailyUsageEntry[];
+type AgentStatsResponse = {
+  daily_stats: AgentDailyUsageEntry[];
   total_messages: number;
   total_unique_users: number;
 };
 
-export function AssistantStats({ assistantId }: { assistantId: number }) {
-  const [assistantStats, setAssistantStats] =
-    useState<AssistantStatsResponse | null>(null);
-  const { agents: assistants } = useAgents();
+export function AgentStats({ agentId }: { agentId: number }) {
+  const [agentStats, setAgentStats] = useState<AgentStatsResponse | null>(null);
+  const { agents } = useAgents();
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [dateRange, setDateRange] = useState<DateRange>({
@@ -35,9 +34,9 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
     to: new Date(),
   });
 
-  const assistant = useMemo(() => {
-    return assistants.find((a) => a.id === assistantId);
-  }, [assistants, assistantId]);
+  const agent = useMemo(() => {
+    return agents.find((a) => a.id === agentId);
+  }, [agents, agentId]);
 
   useEffect(() => {
     async function fetchStats() {
@@ -46,7 +45,7 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
         setError(null);
 
         const res = await fetch(
-          `/api/analytics/assistant/${assistantId}/stats?start=${
+          `/api/analytics/assistant/${agentId}/stats?start=${
             dateRange?.from?.toISOString() || ""
           }&end=${dateRange?.to?.toISOString() || ""}`
         );
@@ -55,11 +54,11 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
           if (res.status === 403) {
             throw new Error("You don't have permission to view these stats.");
           }
-          throw new Error("Failed to fetch assistant stats");
+          throw new Error("Failed to fetch agent stats");
         }
 
-        const data = (await res.json()) as AssistantStatsResponse;
-        setAssistantStats(data);
+        const data = (await res.json()) as AgentStatsResponse;
+        setAgentStats(data);
       } catch (err) {
         setError(
           err instanceof Error ? err.message : "An unknown error occurred"
@@ -70,10 +69,10 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
     }
 
     fetchStats();
-  }, [assistantId, dateRange]);
+  }, [agentId, dateRange]);
 
   const chartData = useMemo(() => {
-    if (!assistantStats?.daily_stats?.length || !dateRange) {
+    if (!agentStats?.daily_stats?.length || !dateRange) {
       return null;
     }
 
@@ -81,7 +80,7 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
       dateRange.from ||
       new Date(
         Math.min(
-          ...assistantStats.daily_stats.map((entry) =>
+          ...agentStats.daily_stats.map((entry) =>
             new Date(entry.date).getTime()
           )
         )
@@ -91,7 +90,7 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
     const dateRangeList = getDatesList(initialDate);
 
     const statsMap = new Map(
-      assistantStats.daily_stats.map((entry) => [entry.date, entry])
+      agentStats.daily_stats.map((entry) => [entry.date, entry])
     );
 
     return dateRangeList
@@ -104,13 +103,13 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
           "Unique Users": dayData?.total_unique_users || 0,
         };
       });
-  }, [assistantStats, dateRange]);
+  }, [agentStats, dateRange]);
 
-  const totalMessages = assistantStats?.total_messages ?? 0;
-  const totalUniqueUsers = assistantStats?.total_unique_users ?? 0;
+  const totalMessages = agentStats?.total_messages ?? 0;
+  const totalUniqueUsers = agentStats?.total_unique_users ?? 0;
 
   let content;
-  if (isLoading || !assistant) {
+  if (isLoading || !agent) {
     content = (
       <div className="h-80 flex flex-col">
         <ThreeDotsLoader />
@@ -122,11 +121,11 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
         <p className="m-auto">{error}</p>
       </div>
     );
-  } else if (!assistantStats?.daily_stats?.length) {
+  } else if (!agentStats?.daily_stats?.length) {
     content = (
       <div className="h-80 text-text-500 flex flex-col">
         <p className="m-auto">
-          No data found for this assistant in the selected date range
+          No data found for this agent in the selected date range
         </p>
       </div>
     );
@@ -157,12 +156,10 @@ export function AssistantStats({ assistantId }: { assistantId: number }) {
           <Card>
             <CardContent className="pt-6">
               <div className="flex items-center space-x-4">
-                {assistant && <AgentAvatar agent={assistant} />}
+                {agent && <AgentAvatar agent={agent} />}
                 <div>
-                  <h3 className="text-lg font-normal">{assistant?.name}</h3>
-                  <p className="text-sm text-text-500">
-                    {assistant?.description}
-                  </p>
+                  <h3 className="text-lg font-normal">{agent?.name}</h3>
+                  <p className="text-sm text-text-500">{agent?.description}</p>
                 </div>
               </div>
             </CardContent>
diff --git a/web/src/app/ee/assistants/stats/[id]/page.tsx b/web/src/app/ee/agents/stats/[id]/page.tsx
similarity index 89%
rename from web/src/app/ee/assistants/stats/[id]/page.tsx
rename to web/src/app/ee/agents/stats/[id]/page.tsx
index 5813df9c022..bd96ef74c01 100644
--- a/web/src/app/ee/assistants/stats/[id]/page.tsx
+++ b/web/src/app/ee/agents/stats/[id]/page.tsx
@@ -3,7 +3,7 @@ import { unstable_noStore as noStore } from "next/cache";
 import { redirect } from "next/navigation";
 import type { Route } from "next";
 import { requireAuth } from "@/lib/auth/requireAuth";
-import { AssistantStats } from "./AssistantStats";
+import { AgentStats } from "./AgentStats";
 import BackButton from "@/refresh-components/buttons/BackButton";
 
 export default async function GalleryPage(props: {
@@ -29,7 +29,7 @@ export default async function GalleryPage(props: {
         <div className="px-32">
           <InstantSSRAutoRefresh />
           <div className="max-w-4xl mx-auto !border-none !bg-transparent !ring-none">
-            <AssistantStats assistantId={parseInt(params.id)} />
+            <AgentStats agentId={parseInt(params.id)} />
           </div>
         </div>
       </div>
diff --git a/web/src/app/nrf/NRFPage.tsx b/web/src/app/nrf/NRFPage.tsx
index 88130db4d46..533c9350577 100644
--- a/web/src/app/nrf/NRFPage.tsx
+++ b/web/src/app/nrf/NRFPage.tsx
@@ -67,8 +67,8 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
   const { refreshChatSessions } = useChatSessions();
   const existingChatSessionId = null; // NRF always starts new chats
 
-  // Get agents for assistant selection
-  const { agents: availableAssistants } = useAgents();
+  // Get agents for agent selection
+  const { agents: availableAgents } = useAgents();
 
   // Projects context for file handling
   const {
@@ -92,25 +92,25 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
   }, [lastFailedFiles, clearLastFailedFiles]);
 
   // Assistant controller
-  const { selectedAssistant, setSelectedAssistantFromId, liveAssistant } =
+  const { selectedAgent, setSelectedAgentFromId, liveAgent } =
     useAgentController({
       selectedChatSession: undefined,
-      onAssistantSelect: () => {},
+      onAgentSelect: () => {},
     });
 
   // LLM manager for model selection.
   // - currentChatSession: undefined because NRF always starts new chats
-  // - liveAssistant: uses the selected assistant, or undefined to fall back
+  // - liveAgent: uses the selected assistant, or undefined to fall back
   //   to system-wide default LLM provider.
   //
   // If no LLM provider is configured (e.g., fresh signup), the input bar is
   // disabled and a "Set up an LLM" button is shown (see bottom of component).
-  const llmManager = useLlmManager(undefined, liveAssistant ?? undefined);
+  const llmManager = useLlmManager(undefined, liveAgent ?? undefined);
 
   // Deep research toggle
   const { deepResearchEnabled, toggleDeepResearch } = useDeepResearchToggle({
     chatSessionId: existingChatSessionId,
-    assistantId: selectedAssistant?.id,
+    agentId: selectedAgent?.id,
   });
 
   // State
@@ -169,7 +169,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
   const hasMessages = messageHistory.length > 0;
 
   // Resolved assistant to use throughout the component
-  const resolvedAssistant = liveAssistant ?? undefined;
+  const resolvedAgent = liveAgent ?? undefined;
 
   // Auto-scroll preference from user settings (matches ChatPage pattern)
   const autoScrollEnabled = user?.preferences?.auto_scroll !== false;
@@ -178,13 +178,13 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
   // Query controller for search/chat classification (EE feature)
   const { submit: submitQuery, classification } = useQueryController();
 
-  // Determine if retrieval (search) is enabled based on the assistant
+  // Determine if retrieval (search) is enabled based on the agent
   const retrievalEnabled = useMemo(() => {
-    if (liveAssistant) {
-      return personaIncludesRetrieval(liveAssistant);
+    if (liveAgent) {
+      return personaIncludesRetrieval(liveAgent);
     }
     return false;
-  }, [liveAssistant]);
+  }, [liveAgent]);
 
   // Check if we're in search mode
   const isSearch = classification === "search";
@@ -248,13 +248,13 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
     useChatController({
       filterManager,
       llmManager,
-      availableAssistants: availableAssistants || [],
-      liveAssistant,
+      availableAgents: availableAgents || [],
+      liveAgent,
       existingChatSessionId,
       selectedDocuments: [],
       searchParams: searchParams!,
       resetInputBar,
-      setSelectedAssistantFromId,
+      setSelectedAgentFromId,
     });
 
   // Chat session controller for loading sessions
@@ -263,7 +263,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
     searchParams: searchParams!,
     filterManager,
     firstMessage: undefined,
-    setSelectedAssistantFromId,
+    setSelectedAgentFromId,
     setSelectedDocuments: () => {}, // No-op: NRF doesn't support document selection
     setCurrentMessageFiles,
     chatSessionIdRef: { current: null },
@@ -437,7 +437,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
             )}
           >
             {/* Chat area with messages */}
-            {hasMessages && resolvedAssistant && (
+            {hasMessages && resolvedAgent && (
               <>
                 {/* Fake header - pushes content below absolute settings button (non-side-panel only) */}
                 {!isSidePanel && <Spacer rem={2} />}
@@ -449,7 +449,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
                   hideScrollbar={isSidePanel}
                 >
                   <ChatUI
-                    liveAssistant={resolvedAssistant}
+                    liveAgent={resolvedAgent}
                     llmManager={llmManager}
                     currentMessageFiles={currentMessageFiles}
                     setPresentingDocument={setPresentingDocument}
@@ -497,7 +497,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
                 chatState={currentChatState}
                 currentSessionFileTokenCount={currentSessionFileTokenCount}
                 availableContextTokens={AVAILABLE_CONTEXT_TOKENS}
-                selectedAssistant={liveAssistant ?? undefined}
+                selectedAgent={liveAgent ?? undefined}
                 handleFileUpload={handleFileUpload}
                 disabled={
                   !llmManager.isLoadingProviders && !llmManager.hasAnyProvider
diff --git a/web/src/components/modals/NoAssistantModal.tsx b/web/src/components/modals/NoAgentModal.tsx
similarity index 90%
rename from web/src/components/modals/NoAssistantModal.tsx
rename to web/src/components/modals/NoAgentModal.tsx
index 1d1829e6e08..a115a825f46 100644
--- a/web/src/components/modals/NoAssistantModal.tsx
+++ b/web/src/components/modals/NoAgentModal.tsx
@@ -6,7 +6,7 @@ import Text from "@/refresh-components/texts/Text";
 import { useUser } from "@/providers/UserProvider";
 import { SvgUser } from "@opal/icons";
 
-export default function NoAssistantModal() {
+export default function NoAgentModal() {
   const { isAdmin } = useUser();
 
   return (
@@ -24,7 +24,7 @@ export default function NoAssistantModal() {
                 As an administrator, you can create a new agent by visiting the
                 admin panel.
               </Text>
-              <Button className="w-full" href="/admin/assistants">
+              <Button className="w-full" href="/admin/agents">
                 Go to Admin Panel
               </Button>
             </>
diff --git a/web/src/components/sidebar/ChatSessionMorePopup.tsx b/web/src/components/sidebar/ChatSessionMorePopup.tsx
index 464e1fb7610..b539d8e4ab7 100644
--- a/web/src/components/sidebar/ChatSessionMorePopup.tsx
+++ b/web/src/components/sidebar/ChatSessionMorePopup.tsx
@@ -61,8 +61,7 @@ export function ChatSessionMorePopup({
   const [showMoveCustomAgentModal, setShowMoveCustomAgentModal] =
     useState(false);
 
-  const isChatUsingDefaultAssistant =
-    chatSession.persona_id === DEFAULT_PERSONA_ID;
+  const isChatUsingDefaultAgent = chatSession.persona_id === DEFAULT_PERSONA_ID;
 
   const [showMoveOptions, setShowMoveOptions] = useState(false);
   const [searchTerm, setSearchTerm] = useState("");
@@ -114,7 +113,7 @@ export function ChatSessionMorePopup({
         window.localStorage.getItem(LS_HIDE_MOVE_CUSTOM_AGENT_MODAL_KEY) ===
           "true";
 
-      if (!isChatUsingDefaultAssistant && !hideModal) {
+      if (!isChatUsingDefaultAgent && !hideModal) {
         setPendingMoveProjectId(targetProjectId);
         setShowMoveCustomAgentModal(true);
         return;
@@ -122,7 +121,7 @@ export function ChatSessionMorePopup({
 
       await performMove(targetProjectId);
     },
-    [isChatUsingDefaultAssistant, performMove]
+    [isChatUsingDefaultAgent, performMove]
   );
 
   const handleRemoveChatSessionFromProject = useCallback(async () => {
diff --git a/web/src/components/sidebar/types.ts b/web/src/components/sidebar/types.ts
index 6aeffb84c8e..71241b1658a 100644
--- a/web/src/components/sidebar/types.ts
+++ b/web/src/components/sidebar/types.ts
@@ -1 +1 @@
-export type pageType = "search" | "chat" | "assistants" | "admin" | "shared";
+export type pageType = "search" | "chat" | "agents" | "admin" | "shared";
diff --git a/web/src/hooks/appNavigation.ts b/web/src/hooks/appNavigation.ts
index 04f81248030..e7fba2d34c9 100644
--- a/web/src/hooks/appNavigation.ts
+++ b/web/src/hooks/appNavigation.ts
@@ -9,18 +9,12 @@ interface UseAppRouterProps {
   chatSessionId?: string;
   agentId?: number;
   projectId?: number;
-  assistantId?: number;
 }
 
 export function useAppRouter() {
   const router = useRouter();
   return useCallback(
-    ({
-      chatSessionId,
-      agentId,
-      projectId,
-      assistantId,
-    }: UseAppRouterProps = {}) => {
+    ({ chatSessionId, agentId, projectId }: UseAppRouterProps = {}) => {
       const finalParams = [];
 
       if (chatSessionId)
@@ -29,8 +23,6 @@ export function useAppRouter() {
         finalParams.push(`${SEARCH_PARAM_NAMES.PERSONA_ID}=${agentId}`);
       else if (projectId)
         finalParams.push(`${SEARCH_PARAM_NAMES.PROJECT_ID}=${projectId}`);
-      else if (assistantId)
-        finalParams.push(`${SEARCH_PARAM_NAMES.PERSONA_ID}=${assistantId}`);
 
       const finalString = finalParams.join("&");
       const finalUrl = `/app?${finalString}`;
diff --git a/web/src/hooks/useAdminPersonas.ts b/web/src/hooks/useAdminPersonas.ts
index f8a5321162c..d6432d761de 100644
--- a/web/src/hooks/useAdminPersonas.ts
+++ b/web/src/hooks/useAdminPersonas.ts
@@ -3,7 +3,7 @@
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { buildApiPath } from "@/lib/urlBuilder";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 interface UseAdminPersonasOptions {
   includeDeleted?: boolean;
diff --git a/web/src/hooks/useAgentController.ts b/web/src/hooks/useAgentController.ts
index 00bb1ef9062..fe221087072 100644
--- a/web/src/hooks/useAgentController.ts
+++ b/web/src/hooks/useAgentController.ts
@@ -1,6 +1,6 @@
 "use client";
 
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { useCallback, useMemo, useState } from "react";
 import { ChatSession } from "@/app/app/interfaces";
 import { useAgents, usePinnedAgents } from "@/hooks/useAgents";
@@ -10,38 +10,34 @@ import { useSettingsContext } from "@/providers/SettingsProvider";
 
 export default function useAgentController({
   selectedChatSession,
-  onAssistantSelect,
+  onAgentSelect,
 }: {
   selectedChatSession: ChatSession | null | undefined;
-  onAssistantSelect?: () => void;
+  onAgentSelect?: () => void;
 }) {
   const searchParams = useSearchParams();
-  const { agents: availableAssistants } = useAgents();
-  const { pinnedAgents: pinnedAssistants } = usePinnedAgents();
+  const { agents: availableAgents } = useAgents();
+  const { pinnedAgents: pinnedAgents } = usePinnedAgents();
   const combinedSettings = useSettingsContext();
 
-  const defaultAssistantIdRaw = searchParams?.get(
-    SEARCH_PARAM_NAMES.PERSONA_ID
-  );
-  const defaultAssistantId = defaultAssistantIdRaw
-    ? parseInt(defaultAssistantIdRaw)
+  const defaultAgentIdRaw = searchParams?.get(SEARCH_PARAM_NAMES.PERSONA_ID);
+  const defaultAgentId = defaultAgentIdRaw
+    ? parseInt(defaultAgentIdRaw)
     : undefined;
 
-  const existingChatSessionAssistantId = selectedChatSession?.persona_id;
-  const [selectedAssistant, setSelectedAssistant] = useState<
+  const existingChatSessionAgentId = selectedChatSession?.persona_id;
+  const [selectedAgent, setSelectedAssistant] = useState<
     MinimalPersonaSnapshot | undefined
   >(
     // NOTE: look through available assistants here, so that even if the user
-    // has hidden this assistant it still shows the correct assistant when
+    // has hidden this agent it still shows the correct assistant when
     // going back to an old chat session
-    existingChatSessionAssistantId !== undefined
-      ? availableAssistants.find(
-          (assistant) => assistant.id === existingChatSessionAssistantId
+    existingChatSessionAgentId !== undefined
+      ? availableAgents.find(
+          (assistant) => assistant.id === existingChatSessionAgentId
         )
-      : defaultAssistantId !== undefined
-        ? availableAssistants.find(
-            (assistant) => assistant.id === defaultAssistantId
-          )
+      : defaultAgentId !== undefined
+        ? availableAgents.find((assistant) => assistant.id === defaultAgentId)
         : undefined
   );
 
@@ -52,8 +48,8 @@ export default function useAgentController({
   // 4. First pinned assistants (ordered list of pinned assistants)
   // 5. Available assistants (ordered list of available assistants)
   // Relevant test: `live_assistant.spec.ts`
-  const liveAssistant: MinimalPersonaSnapshot | undefined = useMemo(() => {
-    if (selectedAssistant) return selectedAssistant;
+  const liveAgent: MinimalPersonaSnapshot | undefined = useMemo(() => {
+    if (selectedAgent) return selectedAgent;
 
     const disableDefaultAssistant =
       combinedSettings?.settings?.disable_default_assistant ?? false;
@@ -61,58 +57,51 @@ export default function useAgentController({
     if (disableDefaultAssistant) {
       // Skip unified assistant (ID 0), go straight to pinned/available
       // Filter out ID 0 from both pinned and available assistants
-      const nonDefaultPinned = pinnedAssistants.filter((a) => a.id !== 0);
-      const nonDefaultAvailable = availableAssistants.filter((a) => a.id !== 0);
+      const nonDefaultPinned = pinnedAgents.filter((a) => a.id !== 0);
+      const nonDefaultAvailable = availableAgents.filter((a) => a.id !== 0);
 
       return (
-        nonDefaultPinned[0] || nonDefaultAvailable[0] || availableAssistants[0] // Last resort fallback
+        nonDefaultPinned[0] || nonDefaultAvailable[0] || availableAgents[0] // Last resort fallback
       );
     }
 
     // Try to use the unified assistant (ID 0) as default
-    const unifiedAssistant = availableAssistants.find((a) => a.id === 0);
-    if (unifiedAssistant) return unifiedAssistant;
+    const unifiedAgent = availableAgents.find((a) => a.id === 0);
+    if (unifiedAgent) return unifiedAgent;
 
     // Fall back to pinned or available assistants
-    return pinnedAssistants[0] || availableAssistants[0];
-  }, [
-    selectedAssistant,
-    pinnedAssistants,
-    availableAssistants,
-    combinedSettings,
-  ]);
+    return pinnedAgents[0] || availableAgents[0];
+  }, [selectedAgent, pinnedAgents, availableAgents, combinedSettings]);
 
-  const setSelectedAssistantFromId = useCallback(
-    (assistantId: number | null | undefined) => {
+  const setSelectedAgentFromId = useCallback(
+    (agentId: number | null | undefined) => {
       // NOTE: also intentionally look through available assistants here, so that
-      // even if the user has hidden an assistant they can still go back to it
+      // even if the user has hidden an agent they can still go back to it
       // for old chats
       let newAssistant =
-        assistantId !== null
-          ? availableAssistants.find(
-              (assistant) => assistant.id === assistantId
-            )
+        agentId !== null
+          ? availableAgents.find((assistant) => assistant.id === agentId)
           : undefined;
 
-      // if no assistant was passed in / found, use the default assistant
-      if (!newAssistant && defaultAssistantId !== undefined) {
-        newAssistant = availableAssistants.find(
-          (assistant) => assistant.id === defaultAssistantId
+      // if no assistant was passed in / found, use the default agent
+      if (!newAssistant && defaultAgentId !== undefined) {
+        newAssistant = availableAgents.find(
+          (assistant) => assistant.id === defaultAgentId
         );
       }
 
       setSelectedAssistant(newAssistant);
-      onAssistantSelect?.();
+      onAgentSelect?.();
     },
-    [availableAssistants, defaultAssistantId, onAssistantSelect]
+    [availableAgents, defaultAgentId, onAgentSelect]
   );
 
   return {
     // main assistant selection
-    selectedAssistant,
-    setSelectedAssistantFromId,
+    selectedAgent,
+    setSelectedAgentFromId,
 
     // final computed assistant
-    liveAssistant,
+    liveAgent,
   };
 }
diff --git a/web/src/hooks/useAgentPreferences.ts b/web/src/hooks/useAgentPreferences.ts
index 399ca903de1..c52a90bf43e 100644
--- a/web/src/hooks/useAgentPreferences.ts
+++ b/web/src/hooks/useAgentPreferences.ts
@@ -2,24 +2,26 @@
 
 import useSWR from "swr";
 import {
-  UserSpecificAssistantPreference,
-  UserSpecificAssistantPreferences,
+  UserSpecificAgentPreference,
+  UserSpecificAgentPreferences,
 } from "@/lib/types";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { useCallback } from "react";
 
-const ASSISTANT_PREFERENCES_URL = "/api/user/assistant/preferences";
+// TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
+const AGENT_PREFERENCES_URL = "/api/user/assistant/preferences";
 
-const buildUpdateAssistantPreferenceUrl = (assistantId: number) =>
-  `/api/user/assistant/${assistantId}/preferences`;
+// TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
+const buildUpdateAgentPreferenceUrl = (agentId: number) =>
+  `/api/user/assistant/${agentId}/preferences`;
 
 /**
- * Hook for managing user-specific assistant preferences using SWR.
+ * Hook for managing user-specific agent preferences using SWR.
  * Provides automatic caching, deduplication, and revalidation.
  */
 export default function useAgentPreferences() {
-  const { data, mutate } = useSWR<UserSpecificAssistantPreferences>(
-    ASSISTANT_PREFERENCES_URL,
+  const { data, mutate } = useSWR<UserSpecificAgentPreferences>(
+    AGENT_PREFERENCES_URL,
     errorHandlingFetcher,
     {
       revalidateOnFocus: false,
@@ -27,39 +29,36 @@ export default function useAgentPreferences() {
     }
   );
 
-  const setSpecificAssistantPreferences = useCallback(
+  const setSpecificAgentPreferences = useCallback(
     async (
-      assistantId: number,
-      newAssistantPreference: UserSpecificAssistantPreference
+      agentId: number,
+      newAgentPreference: UserSpecificAgentPreference
     ) => {
       // Optimistic update
       mutate(
         {
           ...data,
-          [assistantId]: newAssistantPreference,
+          [agentId]: newAgentPreference,
         },
         false
       );
 
       try {
-        const response = await fetch(
-          buildUpdateAssistantPreferenceUrl(assistantId),
-          {
-            method: "PATCH",
-            headers: {
-              "Content-Type": "application/json",
-            },
-            body: JSON.stringify(newAssistantPreference),
-          }
-        );
+        const response = await fetch(buildUpdateAgentPreferenceUrl(agentId), {
+          method: "PATCH",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(newAgentPreference),
+        });
 
         if (!response.ok) {
           console.error(
-            `Failed to update assistant preferences: ${response.status}`
+            `Failed to update agent preferences: ${response.status}`
           );
         }
       } catch (error) {
-        console.error("Error updating assistant preferences:", error);
+        console.error("Error updating agent preferences:", error);
       }
 
       // Revalidate after update
@@ -69,7 +68,7 @@ export default function useAgentPreferences() {
   );
 
   return {
-    assistantPreferences: data ?? null,
-    setSpecificAssistantPreferences,
+    agentPreferences: data ?? null,
+    setSpecificAgentPreferences,
   };
 }
diff --git a/web/src/hooks/useAgents.ts b/web/src/hooks/useAgents.ts
index 08463cc6900..7d3b7d54bdb 100644
--- a/web/src/hooks/useAgents.ts
+++ b/web/src/hooks/useAgents.ts
@@ -5,7 +5,7 @@ import { useState, useEffect, useMemo, useCallback } from "react";
 import {
   MinimalPersonaSnapshot,
   FullPersona,
-} from "@/app/admin/assistants/interfaces";
+} from "@/app/admin/agents/interfaces";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { pinAgents } from "@/lib/agents";
 import { useUser } from "@/providers/UserProvider";
@@ -169,7 +169,7 @@ export function usePinnedAgents() {
 
 /**
  * Hook to determine the currently active agent based on:
- * 1. URL param `assistantId`
+ * 1. URL param `agentId`
  * 2. Chat session's `persona_id`
  * 3. Falls back to null if neither is present
  */
diff --git a/web/src/hooks/useChatController.ts b/web/src/hooks/useChatController.ts
index 4693d28c23e..633a6d95a2b 100644
--- a/web/src/hooks/useChatController.ts
+++ b/web/src/hooks/useChatController.ts
@@ -17,7 +17,7 @@ import {
   buildImmediateMessages,
   buildEmptyMessage,
 } from "@/app/app/services/messageTree";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
 import { SEARCH_TOOL_ID } from "@/app/app/components/tools/constants";
 import { OnyxDocument } from "@/lib/search/interfaces";
@@ -102,13 +102,13 @@ interface RegenerationRequest {
 interface UseChatControllerProps {
   filterManager: FilterManager;
   llmManager: LlmManager;
-  liveAssistant: MinimalPersonaSnapshot | undefined;
-  availableAssistants: MinimalPersonaSnapshot[];
+  liveAgent: MinimalPersonaSnapshot | undefined;
+  availableAgents: MinimalPersonaSnapshot[];
   existingChatSessionId: string | null;
   selectedDocuments: OnyxDocument[];
   searchParams: ReadonlyURLSearchParams;
   resetInputBar: () => void;
-  setSelectedAssistantFromId: (assistantId: number | null) => void;
+  setSelectedAgentFromId: (agentId: number | null) => void;
 }
 
 async function stopChatSession(chatSessionId: string): Promise<void> {
@@ -127,12 +127,12 @@ async function stopChatSession(chatSessionId: string): Promise<void> {
 export default function useChatController({
   filterManager,
   llmManager,
-  availableAssistants,
-  liveAssistant,
+  availableAgents,
+  liveAgent,
   existingChatSessionId,
   selectedDocuments,
   resetInputBar,
-  setSelectedAssistantFromId,
+  setSelectedAgentFromId,
 }: UseChatControllerProps) {
   const pathname = usePathname();
   const router = useRouter();
@@ -140,7 +140,7 @@ export default function useChatController({
   const params = useAppParams();
   const { refreshChatSessions, addPendingChatSession } = useChatSessions();
   const { pinnedAgents, togglePinnedAgent } = usePinnedAgents();
-  const { assistantPreferences } = useAgentPreferences();
+  const { agentPreferences } = useAgentPreferences();
   const { forcedToolIds } = useForcedTools();
   const { fetchProjects, setCurrentMessageFiles, beginUpload } =
     useProjectsContext();
@@ -462,12 +462,12 @@ export default function useChatController({
       }
 
       // Auto-pin the agent to sidebar when sending a message if not already pinned
-      if (liveAssistant) {
+      if (liveAgent) {
         const isAlreadyPinned = pinnedAgents.some(
-          (agent) => agent.id === liveAssistant.id
+          (agent) => agent.id === liveAgent.id
         );
         if (!isAlreadyPinned) {
-          togglePinnedAgent(liveAssistant, true).catch((err) => {
+          togglePinnedAgent(liveAgent, true).catch((err) => {
             console.error("Failed to auto-pin agent:", err);
           });
         }
@@ -481,14 +481,14 @@ export default function useChatController({
 
       const searchParamBasedChatSessionName =
         searchParams?.get(SEARCH_PARAM_NAMES.TITLE) || null;
-      // Auto-name only once, after the first assistant response, and only when the chat isn't
+      // Auto-name only once, after the first agent response, and only when the chat isn't
       // already explicitly named (e.g. `?title=...`).
       const hadAnyUserMessagesBeforeSubmit = currentHistory.some(
         (m) => m.type === "user"
       );
       if (isNewSession) {
         currChatSessionId = await createChatSession(
-          liveAssistant?.id || 0,
+          liveAgent?.id || 0,
           searchParamBasedChatSessionName,
           projectId ? parseInt(projectId) : null
         );
@@ -497,7 +497,7 @@ export default function useChatController({
         // This ensures "New Chat" appears immediately, even before any messages are saved
         addPendingChatSession({
           chatSessionId: currChatSessionId,
-          personaId: liveAssistant?.id || 0,
+          personaId: liveAgent?.id || 0,
           projectId: projectId ? parseInt(projectId) : null,
         });
       } else {
@@ -601,12 +601,12 @@ export default function useChatController({
       // Add user message immediately to the message tree so that the chat
       // immediately reflects the user message
       let initialUserNode: Message;
-      let initialAssistantNode: Message;
+      let initialAgentNode: Message;
 
       if (regenerationRequest) {
-        // For regeneration: keep the existing user message, only create new assistant
+        // For regeneration: keep the existing user message, only create new agent
         initialUserNode = regenerationRequest.parentMessage;
-        initialAssistantNode = buildEmptyMessage({
+        initialAgentNode = buildEmptyMessage({
           messageType: "assistant",
           parentNodeId: initialUserNode.nodeId,
           nodeIdOffset: 1,
@@ -623,13 +623,13 @@ export default function useChatController({
           messageToResend
         );
         initialUserNode = result.initialUserNode;
-        initialAssistantNode = result.initialAssistantNode;
+        initialAgentNode = result.initialAgentNode;
       }
 
       // make messages appear + clear input bar
       const messagesToUpsert = regenerationRequest
-        ? [initialAssistantNode] // Only upsert the new assistant for regeneration
-        : [initialUserNode, initialAssistantNode]; // Upsert both for normal/edit flow
+        ? [initialAgentNode] // Only upsert the new agent for regeneration
+        : [initialUserNode, initialAgentNode]; // Upsert both for normal/edit flow
       currentMessageTreeLocal = upsertToCompleteMessageTree({
         messages: messagesToUpsert,
         completeMessageTreeOverride: currentMessageTreeLocal,
@@ -661,18 +661,18 @@ export default function useChatController({
       let packetsVersion = 0;
 
       let newUserMessageId: number | null = null;
-      let newAssistantMessageId: number | null = null;
+      let newAgentMessageId: number | null = null;
 
       try {
         const lastSuccessfulMessageId = getLastSuccessfulMessageId(
           currentMessageTreeLocal
         );
-        const disabledToolIds = liveAssistant
-          ? assistantPreferences?.[liveAssistant?.id]?.disabled_tool_ids
+        const disabledToolIds = liveAgent
+          ? agentPreferences?.[liveAgent?.id]?.disabled_tool_ids
           : undefined;
 
         // Find the search tool's numeric ID for forceSearch
-        const searchToolNumericId = liveAssistant?.tools.find(
+        const searchToolNumericId = liveAgent?.tools.find(
           (tool) => tool.in_code_tool_id === SEARCH_TOOL_ID
         )?.id;
 
@@ -721,8 +721,8 @@ export default function useChatController({
           temperature: llmManager.temperature || undefined,
           deepResearch,
           enabledToolIds:
-            disabledToolIds && liveAssistant
-              ? liveAssistant.tools
+            disabledToolIds && liveAgent
+              ? liveAgent.tools
                   .filter((tool) => !disabledToolIds?.includes(tool.id))
                   .map((tool) => tool.id)
               : undefined,
@@ -767,7 +767,7 @@ export default function useChatController({
               if (isExtension && posthog) {
                 posthog.capture("extension_chat_query", {
                   extension_context: extensionContext,
-                  assistant_id: liveAssistant?.id,
+                  assistant_id: liveAgent?.id,
                   has_files: effectiveFileDescriptors.length > 0,
                   deep_research: deepResearch,
                 });
@@ -777,7 +777,7 @@ export default function useChatController({
             if (
               (packet as MessageResponseIDInfo).reserved_assistant_message_id
             ) {
-              newAssistantMessageId = (packet as MessageResponseIDInfo)
+              newAgentMessageId = (packet as MessageResponseIDInfo)
                 .reserved_assistant_message_id;
             }
 
@@ -848,7 +848,7 @@ export default function useChatController({
                   documents = messageStart.final_documents;
                   updateSelectedNodeForDocDisplay(
                     frozenSessionId,
-                    initialAssistantNode.nodeId
+                    initialAgentNode.nodeId
                   );
                 }
               }
@@ -869,8 +869,8 @@ export default function useChatController({
                   files: files,
                 },
                 {
-                  ...initialAssistantNode,
-                  messageId: newAssistantMessageId ?? undefined,
+                  ...initialAgentNode,
+                  messageId: newAgentMessageId ?? undefined,
                   message: error || answer,
                   type: error ? "error" : "assistant",
                   retrievalType,
@@ -918,7 +918,7 @@ export default function useChatController({
               packetCount: 0,
             },
             {
-              nodeId: initialAssistantNode.nodeId,
+              nodeId: initialAgentNode.nodeId,
               message: errorMsg,
               type: "error",
               files: aiMessageImages || [],
@@ -955,20 +955,20 @@ export default function useChatController({
       llmManager.currentLlm,
       llmManager.temperature,
       // Others that affect logic
-      liveAssistant,
-      availableAssistants,
+      liveAgent,
+      availableAgents,
       existingChatSessionId,
       selectedDocuments,
       searchParams,
       resetInputBar,
-      setSelectedAssistantFromId,
+      setSelectedAgentFromId,
       updateSelectedNodeForDocDisplay,
       currentMessageTree,
       currentChatState,
       // Ensure latest forced tools are used when submitting
       forcedToolIds,
       // Keep tool preference-derived values fresh
-      assistantPreferences,
+      agentPreferences,
       fetchProjects,
       // For auto-pinning agents
       pinnedAgents,
@@ -980,7 +980,7 @@ export default function useChatController({
     async (acceptedFiles: File[]) => {
       const [_, llmModel] = getFinalLLM(
         llmManager.llmProviders || [],
-        liveAssistant || null,
+        liveAgent || null,
         llmManager.currentLlm
       );
       const llmAcceptsImages = modelSupportsImageInput(
@@ -1006,7 +1006,7 @@ export default function useChatController({
       setCurrentMessageFiles((prev) => [...prev, ...uploadedMessageFiles]);
       updateChatStateAction(getCurrentSessionId(), "input");
     },
-    [liveAssistant, llmManager, forcedToolIds]
+    [liveAgent, llmManager, forcedToolIds]
   );
 
   useEffect(() => {
@@ -1025,13 +1025,9 @@ export default function useChatController({
   useEffect(() => {
     if (currentMessageHistory.length === 0 && existingChatSessionId === null) {
       // Select from available assistants so shared assistants appear.
-      setSelectedAssistantFromId(null);
+      setSelectedAgentFromId(null);
     }
-  }, [
-    existingChatSessionId,
-    availableAssistants,
-    currentMessageHistory.length,
-  ]);
+  }, [existingChatSessionId, availableAgents, currentMessageHistory.length]);
 
   useEffect(() => {
     const handleSlackChatRedirect = async () => {
@@ -1073,11 +1069,11 @@ export default function useChatController({
 
   // fetch # of allowed document tokens for the selected Persona
   useEffect(() => {
-    if (!liveAssistant?.id) return; // avoid calling with undefined persona id
+    if (!liveAgent?.id) return; // avoid calling with undefined persona id
 
     async function fetchMaxTokens() {
       const response = await fetch(
-        `/api/chat/max-selected-document-tokens?persona_id=${liveAssistant?.id}`
+        `/api/chat/max-selected-document-tokens?persona_id=${liveAgent?.id}`
       );
       if (response.ok) {
         const maxTokens = (await response.json()).max_tokens as number;
@@ -1085,7 +1081,7 @@ export default function useChatController({
       }
     }
     fetchMaxTokens();
-  }, [liveAssistant]);
+  }, [liveAgent]);
 
   // check if there's an image file in the message history so that we know
   // which LLMs are available to use
diff --git a/web/src/hooks/useChatSessionController.ts b/web/src/hooks/useChatSessionController.ts
index 215a689bee3..3f6a9d50961 100644
--- a/web/src/hooks/useChatSessionController.ts
+++ b/web/src/hooks/useChatSessionController.ts
@@ -38,7 +38,7 @@ interface UseChatSessionControllerProps {
   firstMessage?: string;
 
   // UI state setters
-  setSelectedAssistantFromId: (assistantId: number | null) => void;
+  setSelectedAgentFromId: (agentId: number | null) => void;
   setSelectedDocuments: (documents: OnyxDocument[]) => void;
   setCurrentMessageFiles: (
     files: ProjectFile[] | ((prev: ProjectFile[]) => ProjectFile[])
@@ -66,7 +66,7 @@ export default function useChatSessionController({
   searchParams,
   filterManager,
   firstMessage,
-  setSelectedAssistantFromId,
+  setSelectedAgentFromId,
   setSelectedDocuments,
   setCurrentMessageFiles,
   chatSessionIdRef,
@@ -155,8 +155,8 @@ export default function useChatSessionController({
         // Clear the current session in the store to show intro messages
         setCurrentSession(null);
 
-        // Reset the selected assistant back to default
-        setSelectedAssistantFromId(null);
+        // Reset the selected agent back to default
+        setSelectedAgentFromId(null);
         updateCurrentChatSessionSharedStatus(ChatSessionSharedStatus.Private);
 
         // If we're supposed to submit on initial load, then do that here
@@ -184,7 +184,7 @@ export default function useChatSessionController({
 
       const session = await response.json();
       const chatSession = session as BackendChatSession;
-      setSelectedAssistantFromId(chatSession.persona_id);
+      setSelectedAgentFromId(chatSession.persona_id);
 
       // Ensure the current session is set to the actual session ID from the response
       setCurrentSession(chatSession.chat_session_id);
diff --git a/web/src/hooks/useChatSessions.ts b/web/src/hooks/useChatSessions.ts
index 96bb2c57c4f..d85c93fc8a7 100644
--- a/web/src/hooks/useChatSessions.ts
+++ b/web/src/hooks/useChatSessions.ts
@@ -10,10 +10,10 @@ import {
 import useSWRInfinite from "swr/infinite";
 import { ChatSession, ChatSessionSharedStatus } from "@/app/app/interfaces";
 import { errorHandlingFetcher } from "@/lib/fetcher";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import useAppFocus from "./useAppFocus";
 import { useAgents } from "./useAgents";
-import { DEFAULT_ASSISTANT_ID } from "@/lib/constants";
+import { DEFAULT_AGENT_ID } from "@/lib/constants";
 
 const PAGE_SIZE = 50;
 const MIN_LOADING_DURATION_MS = 500;
@@ -121,7 +121,7 @@ function useFindAgentForCurrentChatSession(
 
   // This could be a new chat-session. Therefore, `currentChatSession` is false, but there could still be some agent.
   else if (appFocus.isNewSession()) {
-    agentIdToFind = DEFAULT_ASSISTANT_ID;
+    agentIdToFind = DEFAULT_AGENT_ID;
   }
 
   // Or this could be a new chat-session with an agent.
diff --git a/web/src/hooks/useDeepResearchToggle.ts b/web/src/hooks/useDeepResearchToggle.ts
index 883b136dc9a..bd8f9c6407a 100644
--- a/web/src/hooks/useDeepResearchToggle.ts
+++ b/web/src/hooks/useDeepResearchToggle.ts
@@ -4,7 +4,7 @@ import { useState, useEffect, useRef, useCallback } from "react";
 
 interface UseDeepResearchToggleProps {
   chatSessionId: string | null;
-  assistantId: number | undefined;
+  agentId: number | undefined;
 }
 
 /**
@@ -17,12 +17,12 @@ interface UseDeepResearchToggleProps {
  * The toggle is preserved when transitioning from no chat session to a new session.
  *
  * @param chatSessionId - The current chat session ID
- * @param assistantId - The current assistant ID
+ * @param agentId - The current agent ID
  * @returns An object containing the toggle state and toggle function
  */
 export default function useDeepResearchToggle({
   chatSessionId,
-  assistantId,
+  agentId,
 }: UseDeepResearchToggleProps) {
   const [deepResearchEnabled, setDeepResearchEnabled] = useState(false);
   const previousChatSessionId = useRef<string | null>(chatSessionId);
@@ -41,7 +41,7 @@ export default function useDeepResearchToggle({
   // Reset when switching assistants
   useEffect(() => {
     setDeepResearchEnabled(false);
-  }, [assistantId]);
+  }, [agentId]);
 
   const toggleDeepResearch = useCallback(() => {
     setDeepResearchEnabled(!deepResearchEnabled);
diff --git a/web/src/hooks/useIsDefaultAgent.ts b/web/src/hooks/useIsDefaultAgent.ts
index 3fa949b53ea..aacf829bb08 100644
--- a/web/src/hooks/useIsDefaultAgent.ts
+++ b/web/src/hooks/useIsDefaultAgent.ts
@@ -5,22 +5,22 @@ import { useSearchParams } from "next/navigation";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
 import { CombinedSettings } from "@/interfaces/settings";
 import { ChatSession } from "@/app/app/interfaces";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
-import { DEFAULT_ASSISTANT_ID } from "@/lib/constants";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
+import { DEFAULT_AGENT_ID } from "@/lib/constants";
 
 /**
  * Determines if the current assistant is the default agent based on:
  * 1. Whether default agent is disabled in settings
- * 2. If URL has an assistantId specified
+ * 2. If URL has an agentId specified
  * 3. Based on the current chat session
  */
 export default function useIsDefaultAgent({
-  liveAssistant,
+  liveAgent,
   existingChatSessionId,
   selectedChatSession,
   settings,
 }: {
-  liveAssistant: MinimalPersonaSnapshot | undefined;
+  liveAgent: MinimalPersonaSnapshot | undefined;
   existingChatSessionId: string | null;
   selectedChatSession: ChatSession | undefined;
   settings: CombinedSettings | null;
@@ -29,15 +29,15 @@ export default function useIsDefaultAgent({
   const urlAssistantId = searchParams?.get(SEARCH_PARAM_NAMES.PERSONA_ID);
 
   return useMemo(() => {
-    // If default assistant is disabled, it can never be the default agent
+    // If default agent is disabled, it can never be the default agent
     if (settings?.settings?.disable_default_assistant) {
       return false;
     }
 
-    // If URL has an assistantId, it's explicitly selected, not default
+    // If URL has an agentId, it's explicitly selected, not default
     if (
       urlAssistantId !== null &&
-      urlAssistantId !== DEFAULT_ASSISTANT_ID.toString()
+      urlAssistantId !== DEFAULT_AGENT_ID.toString()
     ) {
       return false;
     }
@@ -45,7 +45,7 @@ export default function useIsDefaultAgent({
     // If there's an existing chat session with a persona_id, it's not default
     if (
       existingChatSessionId &&
-      selectedChatSession?.persona_id !== DEFAULT_ASSISTANT_ID
+      selectedChatSession?.persona_id !== DEFAULT_AGENT_ID
     ) {
       return false;
     }
@@ -57,6 +57,6 @@ export default function useIsDefaultAgent({
     urlAssistantId,
     existingChatSessionId,
     selectedChatSession?.persona_id,
-    liveAssistant?.id,
+    liveAgent?.id,
   ]);
 }
diff --git a/web/src/hooks/useShowOnboarding.ts b/web/src/hooks/useShowOnboarding.ts
index 2c7b981e789..8254f014dbd 100644
--- a/web/src/hooks/useShowOnboarding.ts
+++ b/web/src/hooks/useShowOnboarding.ts
@@ -1,7 +1,7 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { useOnboardingState } from "@/refresh-components/onboarding/useOnboardingState";
 
 function getOnboardingCompletedKey(userId: string): string {
@@ -9,7 +9,7 @@ function getOnboardingCompletedKey(userId: string): string {
 }
 
 interface UseShowOnboardingParams {
-  liveAssistant: MinimalPersonaSnapshot | undefined;
+  liveAgent: MinimalPersonaSnapshot | undefined;
   isLoadingProviders: boolean;
   hasAnyProvider: boolean | undefined;
   isLoadingChatSessions: boolean;
@@ -18,7 +18,7 @@ interface UseShowOnboardingParams {
 }
 
 export function useShowOnboarding({
-  liveAssistant,
+  liveAgent,
   isLoadingProviders,
   hasAnyProvider,
   isLoadingChatSessions,
@@ -42,7 +42,7 @@ export function useShowOnboarding({
     actions: onboardingActions,
     llmDescriptors,
     isLoading: isLoadingOnboarding,
-  } = useOnboardingState(liveAssistant);
+  } = useOnboardingState(liveAgent);
 
   // Track which user we've already evaluated onboarding for.
   // Re-check when userId changes (logout/login, account switching without full reload).
diff --git a/web/src/lib/agents.ts b/web/src/lib/agents.ts
index 0a631d9b13e..3141b3116dd 100644
--- a/web/src/lib/agents.ts
+++ b/web/src/lib/agents.ts
@@ -1,48 +1,45 @@
-import {
-  MinimalPersonaSnapshot,
-  Persona,
-} from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot, Persona } from "@/app/admin/agents/interfaces";
 import { User } from "./types";
 import { checkUserIsNoAuthUser } from "./user";
-import { personaComparator } from "@/app/admin/assistants/lib";
+import { personaComparator } from "@/app/admin/agents/lib";
 
 /**
  * Checks if the given user owns the specified assistant.
  *
  * @param user - The user to check ownership for, or null if no user is logged in
  * @param assistant - The assistant to check ownership of
- * @returns true if the user owns the assistant (or no auth is required), false otherwise
+ * @returns true if the user owns the agent (or no auth is required), false otherwise
  */
-export function checkUserOwnsAssistant(
+export function checkUserOwnsAgent(
   user: User | null,
-  assistant: MinimalPersonaSnapshot | Persona
+  agent: MinimalPersonaSnapshot | Persona
 ) {
-  return checkUserIdOwnsAssistant(user?.id, assistant);
+  return checkUserIdOwnsAgent(user?.id, agent);
 }
 
 /**
  * Checks if the given user ID owns the specified assistant.
  *
  * Returns true if a valid user ID is provided and any of the following conditions
- * are met (and the assistant is not built-in):
+ * are met (and the agent is not built-in):
  * - The user is a no-auth user (authentication is disabled)
- * - The user ID matches the assistant owner's ID
+ * - The user ID matches the agent owner's ID
  *
  * Returns false if userId is undefined (e.g., user is loading or unauthenticated)
  * to prevent granting ownership access prematurely.
  *
  * @param userId - The user ID to check ownership for
  * @param assistant - The assistant to check ownership of
- * @returns true if the user owns the assistant, false otherwise
+ * @returns true if the user owns the agent, false otherwise
  */
-export function checkUserIdOwnsAssistant(
+export function checkUserIdOwnsAgent(
   userId: string | undefined,
-  assistant: MinimalPersonaSnapshot | Persona
+  agent: MinimalPersonaSnapshot | Persona
 ) {
   return (
     !!userId &&
-    (checkUserIsNoAuthUser(userId) || assistant.owner?.id === userId) &&
-    !assistant.builtin_persona
+    (checkUserIsNoAuthUser(userId) || agent.owner?.id === userId) &&
+    !agent.builtin_persona
   );
 }
 
@@ -53,13 +50,14 @@ export function checkUserIdOwnsAssistant(
  * @throws Error if the API request fails
  */
 export async function pinAgents(pinnedAgentIds: number[]) {
+  // TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
   const response = await fetch(`/api/user/pinned-assistants`, {
     method: "PATCH",
     headers: {
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
-      ordered_assistant_ids: pinnedAgentIds,
+      ordered_assistant_ids: pinnedAgentIds, // TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
     }),
   });
   if (!response.ok) {
@@ -75,13 +73,11 @@ export async function pinAgents(pinnedAgentIds: number[]) {
  * @param assistants - Array of assistants to filter
  * @returns Filtered and sorted array of visible assistants
  */
-export function filterAssistants(
+export function filterAgents(
   assistants: MinimalPersonaSnapshot[]
 ): MinimalPersonaSnapshot[] {
-  let filteredAssistants = assistants.filter(
-    (assistant) => assistant.is_visible
-  );
-  return filteredAssistants.sort(personaComparator);
+  let filteredAgents = assistants.filter((assistant) => assistant.is_visible);
+  return filteredAgents.sort(personaComparator);
 }
 
 /**
diff --git a/web/src/lib/agentsSS.ts b/web/src/lib/agentsSS.ts
index 2238c7ca8d9..84c8fe2528d 100644
--- a/web/src/lib/agentsSS.ts
+++ b/web/src/lib/agentsSS.ts
@@ -1,10 +1,10 @@
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { fetchSS } from "./utilsSS";
 
-export type FetchAssistantsResponse = [MinimalPersonaSnapshot[], string | null];
+export type FetchAgentsResponse = [MinimalPersonaSnapshot[], string | null];
 
-// Fetch assistants server-side
-export async function fetchAssistantsSS(): Promise<FetchAssistantsResponse> {
+// Fetch agents server-side
+export async function fetchAgentsSS(): Promise<FetchAgentsResponse> {
   const response = await fetchSS("/persona");
   if (response.ok) {
     return [(await response.json()) as MinimalPersonaSnapshot[], null];
diff --git a/web/src/lib/chat/fetchAgentData.ts b/web/src/lib/chat/fetchAgentData.ts
new file mode 100644
index 00000000000..8f504b24519
--- /dev/null
+++ b/web/src/lib/chat/fetchAgentData.ts
@@ -0,0 +1,20 @@
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
+import { filterAgents } from "@/lib/agents";
+import { fetchAgentsSS } from "@/lib/agentsSS";
+
+export async function fetchAgentData(): Promise<MinimalPersonaSnapshot[]> {
+  try {
+    // Fetch core assistants data
+    const [assistants, agentsFetchError] = await fetchAgentsSS();
+    if (agentsFetchError) {
+      // This is not a critical error and occurs when the user is not logged in
+      console.warn(`Failed to fetch agents - ${agentsFetchError}`);
+      return [];
+    }
+
+    return filterAgents(assistants);
+  } catch (error) {
+    console.error("Unexpected error in fetchAgentData:", error);
+    return [];
+  }
+}
diff --git a/web/src/lib/chat/fetchAssistantdata.ts b/web/src/lib/chat/fetchAssistantdata.ts
deleted file mode 100644
index 741aa54bbbe..00000000000
--- a/web/src/lib/chat/fetchAssistantdata.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
-import { filterAssistants } from "@/lib/agents";
-import { fetchAssistantsSS } from "@/lib/agentsSS";
-
-export async function fetchAssistantData(): Promise<MinimalPersonaSnapshot[]> {
-  try {
-    // Fetch core assistants data
-    const [assistants, assistantsFetchError] = await fetchAssistantsSS();
-    if (assistantsFetchError) {
-      // This is not a critical error and occurs when the user is not logged in
-      console.warn(`Failed to fetch assistants - ${assistantsFetchError}`);
-      return [];
-    }
-
-    return filterAssistants(assistants);
-  } catch (error) {
-    console.error("Unexpected error in fetchAssistantData:", error);
-    return [];
-  }
-}
diff --git a/web/src/lib/constants.ts b/web/src/lib/constants.ts
index 28c83c8c71e..eed061a0af5 100644
--- a/web/src/lib/constants.ts
+++ b/web/src/lib/constants.ts
@@ -111,7 +111,7 @@ export const MODAL_ROOT_ID = "modal-root";
 export const ANONYMOUS_USER_NAME = "Anonymous";
 export const UNNAMED_CHAT = "New Chat";
 
-export const DEFAULT_ASSISTANT_ID = 0;
+export const DEFAULT_AGENT_ID = 0;
 export const GENERAL_ASSISTANT_ID = -1;
 export const IMAGE_ASSISTANT_ID = -2;
 export const ART_ASSISTANT_ID = -3;
diff --git a/web/src/lib/filters.ts b/web/src/lib/filters.ts
index e11267f92cc..d7a74956b17 100644
--- a/web/src/lib/filters.ts
+++ b/web/src/lib/filters.ts
@@ -1,4 +1,4 @@
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 import { DocumentSetSummary, ValidSources } from "./types";
 import { getSourcesForPersona } from "./sources";
 
diff --git a/web/src/lib/hooks.ts b/web/src/lib/hooks.ts
index 9a7fdf5fccd..f7b291f385f 100644
--- a/web/src/lib/hooks.ts
+++ b/web/src/lib/hooks.ts
@@ -30,7 +30,7 @@ import { SettingsContext } from "@/providers/SettingsProvider";
 import {
   MinimalPersonaSnapshot,
   PersonaLabel,
-} from "@/app/admin/assistants/interfaces";
+} from "@/app/admin/agents/interfaces";
 import { DefaultModel, LLMProviderDescriptor } from "@/interfaces/llm";
 import { isAnthropic } from "@/app/admin/configuration/llm/utils";
 import { getSourceMetadataForSources } from "./sources";
@@ -486,7 +486,7 @@ export interface LlmManager {
   updateModelOverrideBasedOnChatSession: (chatSession?: ChatSession) => void;
   imageFilesPresent: boolean;
   updateImageFilesPresent: (present: boolean) => void;
-  liveAssistant: MinimalPersonaSnapshot | null;
+  liveAgent: MinimalPersonaSnapshot | null;
   maxTemperature: number;
   llmProviders: LLMProviderDescriptor[] | undefined;
   isLoadingProviders: boolean;
@@ -514,8 +514,8 @@ Thus, the input should be
 - Current assistant
 
 Changes take place as
-- liveAssistant or currentChatSession changes (and the associated model override is set)
-- (updateCurrentLlm) User explicitly setting a model override (and we explicitly override and set the userSpecifiedOverride which we'll use in place of the user preferences unless overridden by an assistant)
+- liveAgent or currentChatSession changes (and the associated model override is set)
+- (updateCurrentLlm) User explicitly setting a model override (and we explicitly override and set the userSpecifiedOverride which we'll use in place of the user preferences unless overridden by an agent)
 
 If we have a live assistant, we should use that model override
 
@@ -638,7 +638,7 @@ export function getValidLlmDescriptorForProviders(
 
 export function useLlmManager(
   currentChatSession?: ChatSession,
-  liveAssistant?: MinimalPersonaSnapshot
+  liveAgent?: MinimalPersonaSnapshot
 ): LlmManager {
   const { user } = useUser();
 
@@ -650,9 +650,8 @@ export function useLlmManager(
     isLoading: isLoadingAllProviders,
   } = useLLMProviders();
   // Fetch persona-specific providers to enforce RBAC restrictions per assistant
-  // Only fetch if we have an assistant selected
-  const personaId =
-    liveAssistant?.id !== undefined ? liveAssistant.id : undefined;
+  // Only fetch if we have an agent selected
+  const personaId = liveAgent?.id !== undefined ? liveAgent.id : undefined;
   const {
     llmProviders: personaProviders,
     defaultText: personaDefaultText,
@@ -674,20 +673,20 @@ export function useLlmManager(
   });
 
   // Track the previous assistant ID to detect when it changes
-  const prevAssistantIdRef = useRef<number | undefined>(undefined);
+  const prevAgentIdRef = useRef<number | undefined>(undefined);
 
   // Reset manual override when switching to a different assistant
   useEffect(() => {
     if (
-      liveAssistant?.id !== undefined &&
-      prevAssistantIdRef.current !== undefined &&
-      liveAssistant.id !== prevAssistantIdRef.current
+      liveAgent?.id !== undefined &&
+      prevAgentIdRef.current !== undefined &&
+      liveAgent.id !== prevAgentIdRef.current
     ) {
       // User switched to a different assistant - reset manual override
       setUserHasManuallyOverriddenLLM(false);
     }
-    prevAssistantIdRef.current = liveAssistant?.id;
-  }, [liveAssistant?.id]);
+    prevAgentIdRef.current = liveAgent?.id;
+  }, [liveAgent?.id]);
 
   const llmUpdate = () => {
     /* Should be called when the live assistant or current chat session changes */
@@ -710,9 +709,9 @@ export function useLlmManager(
         setCurrentLlm(
           getValidLlmDescriptor(currentChatSession.current_alternate_model)
         );
-      } else if (liveAssistant?.llm_model_version_override) {
+      } else if (liveAgent?.llm_model_version_override) {
         setCurrentLlm(
-          getValidLlmDescriptor(liveAssistant.llm_model_version_override)
+          getValidLlmDescriptor(liveAgent.llm_model_version_override)
         );
       } else if (userHasManuallyOverriddenLLM) {
         // if the user has an override and there's nothing special about the
@@ -774,9 +773,7 @@ export function useLlmManager(
         currentChatSession.current_temperature_override,
         isAnthropicModel ? 1.0 : 2.0
       );
-    } else if (
-      liveAssistant?.tools.some((tool) => tool.name === SEARCH_TOOL_ID)
-    ) {
+    } else if (liveAgent?.tools.some((tool) => tool.name === SEARCH_TOOL_ID)) {
       return 0;
     }
     return 0.5;
@@ -823,15 +820,13 @@ export function useLlmManager(
 
     if (currentChatSession?.current_temperature_override) {
       setTemperature(currentChatSession.current_temperature_override);
-    } else if (
-      liveAssistant?.tools.some((tool) => tool.name === SEARCH_TOOL_ID)
-    ) {
+    } else if (liveAgent?.tools.some((tool) => tool.name === SEARCH_TOOL_ID)) {
       setTemperature(0);
     } else {
       setTemperature(0.5);
     }
   }, [
-    liveAssistant,
+    liveAgent,
     currentChatSession,
     llmProviders,
     user?.preferences?.default_model,
@@ -858,7 +853,7 @@ export function useLlmManager(
     updateTemperature,
     imageFilesPresent,
     updateImageFilesPresent,
-    liveAssistant: liveAssistant ?? null,
+    liveAgent: liveAgent ?? null,
     maxTemperature,
     llmProviders,
     isLoadingProviders:
diff --git a/web/src/lib/hooks/useToolOAuthStatus.ts b/web/src/lib/hooks/useToolOAuthStatus.ts
index 91874954a98..2d5203f7b3d 100644
--- a/web/src/lib/hooks/useToolOAuthStatus.ts
+++ b/web/src/lib/hooks/useToolOAuthStatus.ts
@@ -9,7 +9,7 @@ export interface ToolAuthStatus {
   isTokenExpired: boolean;
 }
 
-export function useToolOAuthStatus(assistantId?: number) {
+export function useToolOAuthStatus(agentId?: number) {
   const [oauthTokenStatuses, setOauthTokenStatuses] = useState<
     OAuthTokenStatus[]
   >([]);
@@ -32,7 +32,7 @@ export function useToolOAuthStatus(assistantId?: number) {
 
   useEffect(() => {
     fetchOAuthStatus();
-  }, [assistantId, fetchOAuthStatus]);
+  }, [agentId, fetchOAuthStatus]);
 
   /**
    * Get OAuth status for a specific tool
diff --git a/web/src/lib/llmConfig/utils.ts b/web/src/lib/llmConfig/utils.ts
index 8c8635ed8bc..150b33bf8b8 100644
--- a/web/src/lib/llmConfig/utils.ts
+++ b/web/src/lib/llmConfig/utils.ts
@@ -1,4 +1,4 @@
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import {
   DefaultModel,
   LLMProviderDescriptor,
@@ -45,11 +45,11 @@ export function getFinalLLM(
 }
 
 export function getLLMProviderOverrideForPersona(
-  liveAssistant: MinimalPersonaSnapshot,
+  liveAgent: MinimalPersonaSnapshot,
   llmProviders: LLMProviderDescriptor[]
 ): LlmDescriptor | null {
-  const overrideProvider = liveAssistant.llm_model_provider_override;
-  const overrideModel = liveAssistant.llm_model_version_override;
+  const overrideProvider = liveAgent.llm_model_provider_override;
+  const overrideModel = liveAgent.llm_model_version_override;
 
   if (!overrideModel) {
     return null;
diff --git a/web/src/lib/search/interfaces.ts b/web/src/lib/search/interfaces.ts
index b5a0e3d40e2..c54c2f64c17 100644
--- a/web/src/lib/search/interfaces.ts
+++ b/web/src/lib/search/interfaces.ts
@@ -1,6 +1,6 @@
 import { DateRangePickerValue } from "@/components/dateRangeSelectors/AdminDateRangeSelector";
 import { Tag, ValidSources } from "../types";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 
 export const FlowType = {
   SEARCH: "search",
diff --git a/web/src/lib/sources.ts b/web/src/lib/sources.ts
index d5aa566fee7..429b82e26c3 100644
--- a/web/src/lib/sources.ts
+++ b/web/src/lib/sources.ts
@@ -50,7 +50,7 @@ import {
 } from "@/components/icons/icons";
 import { ValidSources } from "./types";
 import { SourceCategory, SourceMetadata } from "./search/interfaces";
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 import React from "react";
 import { DOCS_ADMINS_PATH } from "./constants";
 import { SvgFileText, SvgGlobe } from "@opal/icons";
diff --git a/web/src/lib/types.ts b/web/src/lib/types.ts
index 7bf9edba493..1d39aabdf5f 100644
--- a/web/src/lib/types.ts
+++ b/web/src/lib/types.ts
@@ -1,15 +1,15 @@
-import { Persona } from "@/app/admin/assistants/interfaces";
+import { Persona } from "@/app/admin/agents/interfaces";
 import { Credential } from "./connectors/credentials";
 import { Connector } from "./connectors/connectors";
 import { ConnectorCredentialPairStatus } from "@/app/admin/connector/[ccPairId]/types";
 
-export interface UserSpecificAssistantPreference {
+export interface UserSpecificAgentPreference {
   disabled_tool_ids?: number[];
 }
 
-export type UserSpecificAssistantPreferences = Record<
+export type UserSpecificAgentPreferences = Record<
   number,
-  UserSpecificAssistantPreference
+  UserSpecificAgentPreference
 >;
 
 export enum ThemePreference {
@@ -19,6 +19,7 @@ export enum ThemePreference {
 }
 
 interface UserPreferences {
+  // TODO: rename to agent — https://linear.app/onyx-app/issue/ENG-3766
   chosen_assistants: number[] | null;
   visible_assistants: number[];
   hidden_assistants: number[];
diff --git a/web/src/providers/UserProvider.tsx b/web/src/providers/UserProvider.tsx
index 14aee86e9eb..af2fbfcf04f 100644
--- a/web/src/providers/UserProvider.tsx
+++ b/web/src/providers/UserProvider.tsx
@@ -31,9 +31,9 @@ interface UserContextType {
   authTypeMetadata: AuthTypeMetadata;
   updateUserAutoScroll: (autoScroll: boolean) => Promise<void>;
   updateUserShortcuts: (enabled: boolean) => Promise<void>;
-  toggleAssistantPinnedStatus: (
-    currentPinnedAssistantIDs: number[],
-    assistantId: number,
+  toggleAgentPinnedStatus: (
+    currentPinnedAgentIDs: number[],
+    agentId: number,
     isPinned: boolean
   ) => Promise<boolean>;
   updateUserTemperatureOverrideEnabled: (enabled: boolean) => Promise<void>;
@@ -282,9 +282,9 @@ export function UserProvider({
     }
   };
 
-  const toggleAssistantPinnedStatus = async (
-    currentPinnedAssistantIDs: number[],
-    assistantId: number,
+  const toggleAgentPinnedStatus = async (
+    currentPinnedAgentIDs: number[],
+    agentId: number,
     isPinned: boolean
   ) => {
     setUpToDateUser((prevUser) => {
@@ -294,21 +294,15 @@ export function UserProvider({
         preferences: {
           ...prevUser.preferences,
           pinned_assistants: isPinned
-            ? [...currentPinnedAssistantIDs, assistantId]
-            : currentPinnedAssistantIDs.filter((id) => id !== assistantId),
+            ? [...currentPinnedAgentIDs, agentId]
+            : currentPinnedAgentIDs.filter((id) => id !== agentId),
         },
       };
     });
 
-    let updatedPinnedAssistantsIds = currentPinnedAssistantIDs;
-
-    if (isPinned) {
-      updatedPinnedAssistantsIds.push(assistantId);
-    } else {
-      updatedPinnedAssistantsIds = updatedPinnedAssistantsIds.filter(
-        (id) => id !== assistantId
-      );
-    }
+    let updatedPinnedAgentsIds = isPinned
+      ? [...currentPinnedAgentIDs, agentId]
+      : currentPinnedAgentIDs.filter((id) => id !== agentId);
     try {
       const response = await fetch(`/api/user/pinned-assistants`, {
         method: "PATCH",
@@ -316,7 +310,7 @@ export function UserProvider({
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          ordered_assistant_ids: updatedPinnedAssistantsIds,
+          ordered_assistant_ids: updatedPinnedAgentsIds,
         }),
       });
 
@@ -484,7 +478,7 @@ export function UserProvider({
         updateUserChatBackground,
         updateUserDefaultModel,
         updateUserDefaultAppMode,
-        toggleAssistantPinnedStatus,
+        toggleAgentPinnedStatus,
         isAdmin: upToDateUser?.role === UserRole.ADMIN,
         // Curator status applies for either global or basic curator
         isCurator:
diff --git a/web/src/proxy.ts b/web/src/proxy.ts
index 379c1d2e5b3..02e4efd83b4 100644
--- a/web/src/proxy.ts
+++ b/web/src/proxy.ts
@@ -11,7 +11,7 @@ const FASTAPI_USERS_AUTH_COOKIE_NAME = "fastapiusersauth";
 const ANONYMOUS_USER_COOKIE_NAME = "onyx_anonymous_user";
 
 // Protected route prefixes (require authentication)
-const PROTECTED_ROUTES = ["/app", "/admin", "/assistants", "/connector"];
+const PROTECTED_ROUTES = ["/app", "/admin", "/agents", "/connector"];
 
 // Public route prefixes (no authentication required)
 const PUBLIC_ROUTES = ["/auth", "/anonymous", "/_next", "/api"];
@@ -23,7 +23,7 @@ export const config = {
     // Auth-protected routes (for middleware auth check)
     "/app/:path*",
     "/admin/:path*",
-    "/assistants/:path*",
+    "/agents/:path*",
     "/connector/:path*",
 
     // Enterprise Edition routes (for /ee rewriting)
@@ -34,7 +34,7 @@ export const config = {
     "/admin/theme/:path*",
     "/admin/performance/custom-analytics/:path*",
     "/admin/standard-answer/:path*",
-    "/assistants/stats/:path*",
+    "/agents/stats/:path*",
 
     // Cloud only
     "/admin/billing/:path*",
@@ -49,7 +49,7 @@ const EE_ROUTES = [
   "/admin/theme",
   "/admin/performance/custom-analytics",
   "/admin/standard-answer",
-  "/assistants/stats",
+  "/agents/stats",
 ];
 
 export async function proxy(request: NextRequest) {
diff --git a/web/src/refresh-components/avatars/AgentAvatar.tsx b/web/src/refresh-components/avatars/AgentAvatar.tsx
index e42fb919e8e..d9ed6252552 100644
--- a/web/src/refresh-components/avatars/AgentAvatar.tsx
+++ b/web/src/refresh-components/avatars/AgentAvatar.tsx
@@ -1,12 +1,12 @@
 "use client";
 
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
 import { OnyxIcon } from "@/components/icons/icons";
 import { useSettingsContext } from "@/providers/SettingsProvider";
 import {
   DEFAULT_AGENT_AVATAR_SIZE_PX,
-  DEFAULT_ASSISTANT_ID,
+  DEFAULT_AGENT_ID,
 } from "@/lib/constants";
 import CustomAgentAvatar from "@/refresh-components/avatars/CustomAgentAvatar";
 import Image from "next/image";
@@ -23,7 +23,7 @@ export default function AgentAvatar({
 }: AgentAvatarProps) {
   const settings = useSettingsContext();
 
-  if (agent.id === DEFAULT_ASSISTANT_ID) {
+  if (agent.id === DEFAULT_AGENT_ID) {
     return settings.enterpriseSettings?.use_custom_logo ? (
       <div
         className="aspect-square rounded-full overflow-hidden relative"
diff --git a/web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx b/web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx
index def01b5f2db..8800c82ab30 100644
--- a/web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx
+++ b/web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx
@@ -45,7 +45,7 @@ function renderUseShowOnboarding(
   } = {}
 ) {
   const defaultParams = {
-    liveAssistant: undefined,
+    liveAgent: undefined,
     isLoadingProviders: false,
     hasAnyProvider: false,
     isLoadingChatSessions: false,
@@ -121,7 +121,7 @@ describe("useShowOnboarding", () => {
 
     // Re-render with same userId but provider data now available
     rerender({
-      liveAssistant: undefined,
+      liveAgent: undefined,
       isLoadingProviders: false,
       hasAnyProvider: true,
       isLoadingChatSessions: false,
@@ -146,7 +146,7 @@ describe("useShowOnboarding", () => {
 
     // Re-render with same userId but provider data now available
     rerender({
-      liveAssistant: undefined,
+      liveAgent: undefined,
       isLoadingProviders: false,
       hasAnyProvider: true,
       isLoadingChatSessions: false,
@@ -168,7 +168,7 @@ describe("useShowOnboarding", () => {
 
     // Change to a new userId with providers available
     rerender({
-      liveAssistant: undefined,
+      liveAgent: undefined,
       isLoadingProviders: false,
       hasAnyProvider: true,
       isLoadingChatSessions: false,
diff --git a/web/src/refresh-components/onboarding/useOnboardingState.ts b/web/src/refresh-components/onboarding/useOnboardingState.ts
index 2b602c86fa9..12fff6f682c 100644
--- a/web/src/refresh-components/onboarding/useOnboardingState.ts
+++ b/web/src/refresh-components/onboarding/useOnboardingState.ts
@@ -10,11 +10,11 @@ import {
 import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
 import { updateUserPersonalization } from "@/lib/userSettings";
 import { useUser } from "@/providers/UserProvider";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { useLLMProviders } from "@/hooks/useLLMProviders";
 import { useProviderStatus } from "@/components/chat/ProviderContext";
 
-export function useOnboardingState(liveAssistant?: MinimalPersonaSnapshot): {
+export function useOnboardingState(liveAgent?: MinimalPersonaSnapshot): {
   state: OnboardingState;
   llmDescriptors: WellKnownLLMProviderDescriptor[];
   actions: OnboardingActions;
@@ -33,9 +33,7 @@ export function useOnboardingState(liveAssistant?: MinimalPersonaSnapshot): {
   } = useProviderStatus();
 
   // Only fetch persona-specific providers (different endpoint)
-  const { refetch: refreshPersonaProviders } = useLLMProviders(
-    liveAssistant?.id
-  );
+  const { refetch: refreshPersonaProviders } = useLLMProviders(liveAgent?.id);
 
   const userName = user?.personalization?.name;
   const llmDescriptors = providerOptions;
@@ -121,7 +119,7 @@ export function useOnboardingState(liveAssistant?: MinimalPersonaSnapshot): {
 
     if (state.currentStep === OnboardingStep.LlmSetup) {
       refreshProviderInfo();
-      if (liveAssistant) {
+      if (liveAgent) {
         refreshPersonaProviders();
       }
     }
@@ -237,6 +235,6 @@ export function useOnboardingState(liveAssistant?: MinimalPersonaSnapshot): {
       setError,
       reset,
     },
-    isLoading: isLoadingProviders || !!liveAssistant,
+    isLoading: isLoadingProviders || !!liveAgent,
   };
 }
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index 7f058c5b615..dad2dc53417 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -12,7 +12,7 @@ import Popover, { PopoverMenu } from "@/refresh-components/Popover";
 import SwitchList, {
   SwitchListItem,
 } from "@/refresh-components/popovers/ActionsPopover/SwitchList";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import {
   MCPAuthenticationType,
   MCPAuthenticationPerformer,
@@ -133,14 +133,14 @@ type SecondaryViewState =
   | { type: "mcp"; serverId: number };
 
 export interface ActionsPopoverProps {
-  selectedAssistant: MinimalPersonaSnapshot;
+  selectedAgent: MinimalPersonaSnapshot;
   filterManager: FilterManager;
   availableSources?: ValidSources[];
   disabled?: boolean;
 }
 
 export default function ActionsPopover({
-  selectedAssistant,
+  selectedAgent,
   filterManager,
   availableSources = [],
   disabled = false,
@@ -157,7 +157,7 @@ export default function ActionsPopover({
 
   // Use the OAuth hook
   const { getToolAuthStatus, authenticateTool } = useToolOAuthStatus(
-    selectedAssistant.id
+    selectedAgent.id
   );
 
   const {
@@ -176,10 +176,10 @@ export default function ActionsPopover({
   // Store previously enabled sources when search tool is disabled
   const previouslyEnabledSourcesRef = useRef<SourceMetadata[]>([]);
 
-  const isDefaultAgent = selectedAssistant.id === 0;
+  const isDefaultAgent = selectedAgent.id === 0;
 
   // Check if the search tool is explicitly enabled on this persona (admin enabled "Use Knowledge")
-  const hasSearchTool = selectedAssistant.tools.some(
+  const hasSearchTool = selectedAgent.tools.some(
     (tool) => tool.in_code_tool_id === SEARCH_TOOL_ID
   );
 
@@ -193,7 +193,7 @@ export default function ActionsPopover({
     const sourceSet = new Set<string>();
 
     // Add sources from document sets
-    selectedAssistant.document_sets.forEach((docSet) => {
+    selectedAgent.document_sets.forEach((docSet) => {
       // Check cc_pair_summaries (regular connectors)
       docSet.cc_pair_summaries?.forEach((ccPair) => {
         // Normalize by removing federated_ prefix
@@ -210,7 +210,7 @@ export default function ActionsPopover({
     });
 
     // Add sources from hierarchy nodes and attached documents (via knowledge_sources)
-    selectedAssistant.knowledge_sources?.forEach((source) => {
+    selectedAgent.knowledge_sources?.forEach((source) => {
       // Normalize by removing federated_ prefix
       const normalized = source.replace("federated_", "");
       sourceSet.add(normalized);
@@ -224,8 +224,8 @@ export default function ActionsPopover({
     return sourceSet;
   }, [
     isDefaultAgent,
-    selectedAssistant.document_sets,
-    selectedAssistant.knowledge_sources,
+    selectedAgent.document_sets,
+    selectedAgent.knowledge_sources,
     hasSearchTool,
   ]);
 
@@ -235,11 +235,11 @@ export default function ActionsPopover({
   const hasNoKnowledgeSources =
     !isDefaultAgent &&
     !hasSearchTool &&
-    selectedAssistant.document_sets.length === 0 &&
-    (selectedAssistant.hierarchy_node_count ?? 0) === 0 &&
-    (selectedAssistant.attached_document_count ?? 0) === 0;
+    selectedAgent.document_sets.length === 0 &&
+    (selectedAgent.hierarchy_node_count ?? 0) === 0 &&
+    (selectedAgent.attached_document_count ?? 0) === 0;
 
-  // Store MCP server auth/loading state (tools are part of selectedAssistant.tools)
+  // Store MCP server auth/loading state (tools are part of selectedAgent.tools)
   const [mcpServerData, setMcpServerData] = useState<{
     [serverId: number]: {
       isAuthenticated: boolean;
@@ -264,15 +264,15 @@ export default function ActionsPopover({
     isAuthenticated: false,
   });
 
-  // Get the assistant preference for this assistant
-  const { assistantPreferences, setSpecificAssistantPreferences } =
+  // Get the agent preference for this assistant
+  const { agentPreferences, setSpecificAgentPreferences } =
     useAgentPreferences();
   const { forcedToolIds, setForcedToolIds } = useForcedTools();
 
   // Reset state when assistant changes
   useEffect(() => {
     setForcedToolIds([]);
-  }, [selectedAssistant.id, setForcedToolIds]);
+  }, [selectedAgent.id, setForcedToolIds]);
 
   const { isAdmin, isCurator } = useUser();
   const settings = useSettingsContext();
@@ -286,11 +286,11 @@ export default function ActionsPopover({
   // Check if there are any connectors available
   const hasNoConnectors = ccPairs.length === 0;
 
-  const assistantPreference = assistantPreferences?.[selectedAssistant.id];
-  const disabledToolIds = assistantPreference?.disabled_tool_ids || [];
-  const toggleToolForCurrentAssistant = (toolId: number) => {
+  const agentPreference = agentPreferences?.[selectedAgent.id];
+  const disabledToolIds = agentPreference?.disabled_tool_ids || [];
+  const toggleToolForCurrentAgent = (toolId: number) => {
     const disabled = disabledToolIds.includes(toolId);
-    setSpecificAssistantPreferences(selectedAssistant.id, {
+    setSpecificAgentPreferences(selectedAgent.id, {
       disabled_tool_ids: disabled
         ? disabledToolIds.filter((id) => id !== toolId)
         : [...disabledToolIds, toolId],
@@ -315,10 +315,10 @@ export default function ActionsPopover({
   // Get internal search tool reference for auto-pin logic
   const internalSearchTool = useMemo(
     () =>
-      selectedAssistant.tools.find(
+      selectedAgent.tools.find(
         (tool) => tool.in_code_tool_id === SEARCH_TOOL_ID && !tool.mcp_server_id
       ),
-    [selectedAssistant.tools]
+    [selectedAgent.tools]
   );
 
   // Handle explicit force toggle from ActionLineItem
@@ -425,7 +425,7 @@ export default function ActionsPopover({
   // Filter out MCP tools from the main list (they have mcp_server_id)
   // Also filter out internal search tool for basic users when there are no connectors
   // Also filter out tools that are not chat-selectable (e.g., OpenURL)
-  const displayTools = selectedAssistant.tools.filter((tool) => {
+  const displayTools = selectedAgent.tools.filter((tool) => {
     // Filter out MCP tools
     if (tool.mcp_server_id) return false;
 
@@ -468,16 +468,16 @@ export default function ActionsPopover({
     displayTools.find((tool) => tool.in_code_tool_id === SEARCH_TOOL_ID)?.id ??
     null;
 
-  // Fetch MCP servers for the assistant on mount
+  // Fetch MCP servers for the agent on mount
   useEffect(() => {
-    if (selectedAssistant == null || selectedAssistant.id == null) return;
+    if (selectedAgent == null || selectedAgent.id == null) return;
 
     const abortController = new AbortController();
 
     const fetchMCPServers = async () => {
       try {
         const response = await fetch(
-          `/api/mcp/servers/persona/${selectedAssistant.id}`,
+          `/api/mcp/servers/persona/${selectedAgent.id}`,
           {
             signal: abortController.signal,
           }
@@ -511,9 +511,9 @@ export default function ActionsPopover({
     return () => {
       abortController.abort();
     };
-  }, [selectedAssistant?.id]);
+  }, [selectedAgent?.id]);
 
-  // No separate MCP tool loading; tools already exist in selectedAssistant.tools
+  // No separate MCP tool loading; tools already exist in selectedAgent.tools
 
   // Handle MCP authentication
   const handleMCPAuthenticate = async (
@@ -678,7 +678,7 @@ export default function ActionsPopover({
     : undefined;
   const selectedMcpTools =
     selectedMcpServerId !== null
-      ? selectedAssistant.tools.filter(
+      ? selectedAgent.tools.filter(
           (t) => t.mcp_server_id === Number(selectedMcpServerId)
         )
       : [];
@@ -703,7 +703,7 @@ export default function ActionsPopover({
     label: tool.display_name || tool.name,
     description: tool.description,
     isEnabled: !disabledToolIds.includes(tool.id),
-    onToggle: () => toggleToolForCurrentAssistant(tool.id),
+    onToggle: () => toggleToolForCurrentAgent(tool.id),
   }));
 
   const mcpAllDisabled = selectedMcpTools.every((tool) =>
@@ -714,7 +714,7 @@ export default function ActionsPopover({
     if (!selectedMcpServer) return;
     const serverToolIds = selectedMcpTools.map((tool) => tool.id);
     const merged = Array.from(new Set([...disabledToolIds, ...serverToolIds]));
-    setSpecificAssistantPreferences(selectedAssistant.id, {
+    setSpecificAgentPreferences(selectedAgent.id, {
       disabled_tool_ids: merged,
     });
     setForcedToolIds(forcedToolIds.filter((id) => !serverToolIds.includes(id)));
@@ -723,7 +723,7 @@ export default function ActionsPopover({
   const enableAllToolsForSelectedServer = () => {
     if (!selectedMcpServer) return;
     const serverToolIdSet = new Set(selectedMcpTools.map((tool) => tool.id));
-    setSpecificAssistantPreferences(selectedAssistant.id, {
+    setSpecificAgentPreferences(selectedAgent.id, {
       disabled_tool_ids: disabledToolIds.filter(
         (id) => !serverToolIdSet.has(id)
       ),
@@ -771,17 +771,17 @@ export default function ActionsPopover({
     const hasEnabledSources = numSourcesEnabled > 0;
     if (hasEnabledSources && searchToolDisabled) {
       // Sources are enabled but search tool is disabled - enable it
-      toggleToolForCurrentAssistant(searchToolId);
+      toggleToolForCurrentAgent(searchToolId);
     } else if (!hasEnabledSources && !searchToolDisabled) {
       // No sources enabled but search tool is enabled - disable it
-      toggleToolForCurrentAssistant(searchToolId);
+      toggleToolForCurrentAgent(searchToolId);
     }
   }, [
     searchToolId,
     numSourcesEnabled,
     searchToolDisabled,
     sourcesInitialized,
-    toggleToolForCurrentAssistant,
+    toggleToolForCurrentAgent,
   ]);
 
   // Set search tool to a specific enabled/disabled state (only toggles if needed)
@@ -789,9 +789,9 @@ export default function ActionsPopover({
     if (searchToolId === null) return;
 
     if (enabled && searchToolDisabled) {
-      toggleToolForCurrentAssistant(searchToolId);
+      toggleToolForCurrentAgent(searchToolId);
     } else if (!enabled && !searchToolDisabled) {
-      toggleToolForCurrentAssistant(searchToolId);
+      toggleToolForCurrentAgent(searchToolId);
     }
   };
 
@@ -815,7 +815,7 @@ export default function ActionsPopover({
 
   const handleToggleTool = (toolId: number) => {
     const wasDisabled = disabledToolIds.includes(toolId);
-    toggleToolForCurrentAssistant(toolId);
+    toggleToolForCurrentAgent(toolId);
 
     if (toolId === searchToolId) {
       if (wasDisabled) {
@@ -935,7 +935,7 @@ export default function ActionsPopover({
           };
 
           // Tools for this server come from assistant.tools
-          const serverTools = selectedAssistant.tools.filter(
+          const serverTools = selectedAgent.tools.filter(
             (t) => t.mcp_server_id === Number(server.id)
           );
           const enabledTools = serverTools.filter(
diff --git a/web/src/refresh-pages/AgentEditorPage.tsx b/web/src/refresh-pages/AgentEditorPage.tsx
index 1394ce625d6..4eff2ff33a2 100644
--- a/web/src/refresh-pages/AgentEditorPage.tsx
+++ b/web/src/refresh-pages/AgentEditorPage.tsx
@@ -5,7 +5,7 @@ import { useRouter } from "next/navigation";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import * as GeneralLayouts from "@/layouts/general-layouts";
 import Button from "@/refresh-components/buttons/Button";
-import { FullPersona } from "@/app/admin/assistants/interfaces";
+import { FullPersona } from "@/app/admin/agents/interfaces";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
 import { Formik, Form, FieldArray } from "formik";
 import * as Yup from "yup";
@@ -69,7 +69,7 @@ import {
   createPersona,
   updatePersona,
   PersonaUpsertParameters,
-} from "@/app/admin/assistants/lib";
+} from "@/app/admin/agents/lib";
 import useMcpServersForAgentEditor from "@/hooks/useMcpServersForAgentEditor";
 import useOpenApiTools from "@/hooks/useOpenApiTools";
 import { useAvailableTools } from "@/hooks/useAvailableTools";
@@ -587,9 +587,9 @@ export default function AgentEditorPage({
     replace_base_system_prompt:
       existingAgent?.replace_base_system_prompt ?? false,
     reminders: existingAgent?.task_prompt ?? "",
-    // For new assistants, default to false for optional tools to avoid
+    // For new agents, default to false for optional tools to avoid
     // "Tool not available" errors when the tool isn't configured.
-    // For existing assistants, preserve the current tool configuration.
+    // For existing agents, preserve the current tool configuration.
     image_generation:
       !!imageGenTool &&
       (existingAgent?.tools?.some(
diff --git a/web/src/refresh-pages/AgentsNavigationPage.tsx b/web/src/refresh-pages/AgentsNavigationPage.tsx
index 826c750de73..719a6c8dfdf 100644
--- a/web/src/refresh-pages/AgentsNavigationPage.tsx
+++ b/web/src/refresh-pages/AgentsNavigationPage.tsx
@@ -3,9 +3,9 @@
 import { useMemo, useState, useRef, useEffect } from "react";
 import AgentCard from "@/sections/cards/AgentCard";
 import { useUser } from "@/providers/UserProvider";
-import { checkUserOwnsAssistant as checkUserOwnsAgent } from "@/lib/agents";
+import { checkUserOwnsAgent as checkUserOwnsAgent } from "@/lib/agents";
 import { useAgents } from "@/hooks/useAgents";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index fe6d6a33d47..0813bc7a050 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -24,7 +24,7 @@ import { useAgents } from "@/hooks/useAgents";
 import { AppPopup } from "@/app/app/components/AppPopup";
 import ExceptionTraceModal from "@/components/modals/ExceptionTraceModal";
 import { useUser } from "@/providers/UserProvider";
-import NoAssistantModal from "@/components/modals/NoAssistantModal";
+import NoAgentModal from "@/components/modals/NoAgentModal";
 import PreviewModal from "@/sections/modals/PreviewModal";
 import Modal from "@/refresh-components/Modal";
 import { useSendMessageToParent } from "@/lib/extension/utils";
@@ -196,12 +196,12 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     }
   }
 
-  const { selectedAssistant, setSelectedAssistantFromId, liveAssistant } =
+  const { selectedAgent, setSelectedAgentFromId, liveAgent } =
     useAgentController({
       selectedChatSession: currentChatSession,
-      onAssistantSelect: () => {
-        // Only remove project context if user explicitly selected an assistant
-        // (i.e., assistantId is present). Avoid clearing project when assistantId was removed.
+      onAgentSelect: () => {
+        // Only remove project context if user explicitly selected an agent
+        // (i.e., agentId is present). Avoid clearing project when agentId was removed.
         const newSearchParams = new URLSearchParams(
           searchParams?.toString() || ""
         );
@@ -214,16 +214,13 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
 
   const { deepResearchEnabled, toggleDeepResearch } = useDeepResearchToggle({
     chatSessionId: currentChatSessionId,
-    assistantId: selectedAssistant?.id,
+    agentId: selectedAgent?.id,
   });
 
   const [presentingDocument, setPresentingDocument] =
     useState<MinimalOnyxDocument | null>(null);
 
-  const llmManager = useLlmManager(
-    currentChatSession ?? undefined,
-    liveAssistant
-  );
+  const llmManager = useLlmManager(currentChatSession ?? undefined, liveAgent);
 
   const {
     showOnboarding,
@@ -235,7 +232,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     finishOnboarding,
     hideOnboarding,
   } = useShowOnboarding({
-    liveAssistant,
+    liveAgent,
     isLoadingProviders: llmManager.isLoadingProviders,
     hasAnyProvider: llmManager.hasAnyProvider,
     isLoadingChatSessions,
@@ -243,7 +240,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     userId: user?.id,
   });
 
-  const noAssistants = liveAssistant === null || liveAssistant === undefined;
+  const noAgents = liveAgent === null || liveAgent === undefined;
 
   const availableSources: ValidSources[] = useMemo(() => {
     return ccPairs.map((ccPair) => ccPair.source);
@@ -292,7 +289,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
   const filterManager = useFilters();
 
   const isDefaultAgent = useIsDefaultAgent({
-    liveAssistant,
+    liveAgent,
     existingChatSessionId: currentChatSessionId,
     selectedChatSession: currentChatSession ?? undefined,
     settings,
@@ -372,13 +369,13 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     useChatController({
       filterManager,
       llmManager,
-      availableAssistants: agents,
-      liveAssistant,
+      availableAgents: agents,
+      liveAgent,
       existingChatSessionId: currentChatSessionId,
       selectedDocuments,
       searchParams,
       resetInputBar,
-      setSelectedAssistantFromId,
+      setSelectedAgentFromId,
     });
 
   const { onMessageSelection, currentSessionFileTokenCount } =
@@ -387,7 +384,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       searchParams,
       filterManager,
       firstMessage,
-      setSelectedAssistantFromId,
+      setSelectedAgentFromId,
       setSelectedDocuments,
       setCurrentMessageFiles,
       chatSessionIdRef,
@@ -402,11 +399,11 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
   useSendMessageToParent();
 
   const retrievalEnabled = useMemo(() => {
-    if (liveAssistant) {
-      return personaIncludesRetrieval(liveAssistant);
+    if (liveAgent) {
+      return personaIncludesRetrieval(liveAgent);
     }
     return false;
-  }, [liveAssistant]);
+  }, [liveAgent]);
 
   useEffect(() => {
     if (
@@ -607,7 +604,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
             (available ?? DEFAULT_CONTEXT_TOKENS) * 0.5;
           if (!cancelled) setAvailableContextTokens(capped_context_tokens);
         } else {
-          const personaId = (selectedAssistant || liveAssistant)?.id;
+          const personaId = (selectedAgent || liveAgent)?.id;
           if (personaId !== undefined && personaId !== null) {
             const maxTokens = await getMaxSelectedDocumentTokens(personaId);
             const capped_context_tokens =
@@ -625,20 +622,20 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     return () => {
       cancelled = true;
     };
-  }, [currentChatSessionId, selectedAssistant?.id, liveAssistant?.id]);
+  }, [currentChatSessionId, selectedAgent?.id, liveAgent?.id]);
 
   // handle error case where no assistants are available
   // Only show this after agents have loaded to prevent flash during initial load
-  if (noAssistants && !isLoadingAgents) {
+  if (noAgents && !isLoadingAgents) {
     return (
       <>
         <HealthCheckBanner />
-        <NoAssistantModal />
+        <NoAgentModal />
       </>
     );
   }
 
-  const hasStarterMessages = (liveAssistant?.starter_messages?.length ?? 0) > 0;
+  const hasStarterMessages = (liveAgent?.starter_messages?.length ?? 0) > 0;
 
   const isSearch = classification === "search";
   const gridStyle = {
@@ -726,9 +723,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                   {/* ChatUI */}
                   <Fade
                     show={
-                      appFocus.isChat() &&
-                      !!currentChatSessionId &&
-                      !!liveAssistant
+                      appFocus.isChat() && !!currentChatSessionId && !!liveAgent
                     }
                     className="h-full w-full flex flex-col items-center"
                   >
@@ -741,7 +736,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                       onScrollButtonVisibilityChange={setShowScrollButton}
                     >
                       <ChatUI
-                        liveAssistant={liveAssistant!}
+                        liveAgent={liveAgent!}
                         llmManager={llmManager}
                         deepResearchEnabled={deepResearchEnabled}
                         currentMessageFiles={currentMessageFiles}
@@ -775,7 +770,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                     className="w-full flex-1 flex flex-col items-center justify-end"
                   >
                     <WelcomeMessage
-                      agent={liveAssistant}
+                      agent={liveAgent}
                       isDefaultAgent={isDefaultAgent}
                     />
                     <Spacer rem={1.5} />
@@ -860,7 +855,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                             : projectContextTokenCount
                         }
                         availableContextTokens={availableContextTokens}
-                        selectedAssistant={selectedAssistant || liveAssistant}
+                        selectedAgent={selectedAgent || liveAgent}
                         handleFileUpload={handleMessageSpecificFileUpload}
                         setPresentingDocument={setPresentingDocument}
                         // Intentionally enabled during name-only onboarding (showOnboarding=false)
@@ -891,7 +886,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                     !isDefaultAgent && (
                       <>
                         <Spacer rem={1} />
-                        <AgentDescription agent={liveAssistant} />
+                        <AgentDescription agent={liveAgent} />
                         <Spacer rem={1.5} />
                       </>
                     )}
diff --git a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
index 3f5625c7647..131c33ccd13 100644
--- a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
+++ b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
@@ -55,7 +55,7 @@ import useFilter from "@/hooks/useFilter";
 import { MCPServer } from "@/lib/tools/interfaces";
 import type { IconProps } from "@opal/types";
 
-interface DefaultAssistantConfiguration {
+interface DefaultAgentConfiguration {
   tool_ids: number[];
   system_prompt: string | null;
   default_system_prompt: string;
@@ -223,14 +223,14 @@ function ChatPreferencesForm() {
       })),
   }));
 
-  // Default assistant configuration (system prompt)
-  const { data: defaultAssistantConfig, mutate: mutateDefaultAssistant } =
-    useSWR<DefaultAssistantConfiguration>(
+  // Default agent configuration (system prompt)
+  const { data: defaultAgentConfig, mutate: mutateDefaultAgent } =
+    useSWR<DefaultAgentConfiguration>(
       "/api/admin/default-assistant/configuration",
       errorHandlingFetcher
     );
 
-  const enabledToolIds = defaultAssistantConfig?.tool_ids ?? [];
+  const enabledToolIds = defaultAgentConfig?.tool_ids ?? [];
 
   const isToolEnabled = useCallback(
     (toolDbId: number) => enabledToolIds.includes(toolDbId),
@@ -240,11 +240,11 @@ function ChatPreferencesForm() {
   const saveToolIds = useCallback(
     async (newToolIds: number[]) => {
       // Optimistic update so subsequent toggles read fresh state
-      const optimisticData = defaultAssistantConfig
-        ? { ...defaultAssistantConfig, tool_ids: newToolIds }
+      const optimisticData = defaultAgentConfig
+        ? { ...defaultAgentConfig, tool_ids: newToolIds }
         : undefined;
       try {
-        await mutateDefaultAssistant(
+        await mutateDefaultAgent(
           async () => {
             const response = await fetch("/api/admin/default-assistant", {
               method: "PATCH",
@@ -264,7 +264,7 @@ function ChatPreferencesForm() {
         toast.error("Failed to update tools");
       }
     },
-    [defaultAssistantConfig, mutateDefaultAssistant]
+    [defaultAgentConfig, mutateDefaultAgent]
   );
 
   const toggleTool = useCallback(
@@ -385,8 +385,8 @@ function ChatPreferencesForm() {
               icon={SvgAddLines}
               onClick={() => {
                 setSystemPromptValue(
-                  defaultAssistantConfig?.system_prompt ??
-                    defaultAssistantConfig?.default_system_prompt ??
+                  defaultAgentConfig?.system_prompt ??
+                    defaultAgentConfig?.default_system_prompt ??
                     ""
                 );
                 setSystemPromptModalOpen(true);
@@ -784,7 +784,7 @@ function ChatPreferencesForm() {
                     const errorMsg = (await response.json()).detail;
                     throw new Error(errorMsg);
                   }
-                  await mutateDefaultAssistant();
+                  await mutateDefaultAgent();
                   setSystemPromptModalOpen(false);
                   toast.success("System prompt updated");
                 } catch {
diff --git a/web/src/sections/cards/AgentCard.tsx b/web/src/sections/cards/AgentCard.tsx
index 2229c9a88c8..78a56c6c24b 100644
--- a/web/src/sections/cards/AgentCard.tsx
+++ b/web/src/sections/cards/AgentCard.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useMemo, useCallback } from "react";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import AgentAvatar from "@/refresh-components/avatars/AgentAvatar";
 import Button from "@/refresh-components/buttons/Button";
 import { useAppRouter } from "@/hooks/appNavigation";
@@ -12,7 +12,7 @@ import { useRouter } from "next/navigation";
 import type { Route } from "next";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import {
-  checkUserOwnsAssistant,
+  checkUserOwnsAgent,
   updateAgentSharedStatus,
   updateAgentFeaturedStatus,
 } from "@/lib/agents";
@@ -51,7 +51,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
   const { user, isAdmin, isCurator } = useUser();
   const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
   const canUpdateFeaturedStatus = isAdmin || isCurator;
-  const isOwnedByUser = checkUserOwnsAssistant(user, agent);
+  const isOwnedByUser = checkUserOwnsAgent(user, agent);
   const shareAgentModal = useCreateModal();
   const agentViewerModal = useCreateModal();
   const { agent: fullAgent, refresh: refreshAgent } = useAgent(agent.id);
@@ -150,7 +150,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
                       icon={SvgBarChart}
                       tertiary
                       onClick={noProp(() =>
-                        router.push(`/ee/assistants/stats/${agent.id}` as Route)
+                        router.push(`/ee/agents/stats/${agent.id}` as Route)
                       )}
                       tooltip="View Agent Stats"
                       className="hidden group-hover/AgentCard:flex"
diff --git a/web/src/sections/chat/ChatUI.tsx b/web/src/sections/chat/ChatUI.tsx
index 80161dacd9b..fd206cba8d2 100644
--- a/web/src/sections/chat/ChatUI.tsx
+++ b/web/src/sections/chat/ChatUI.tsx
@@ -5,7 +5,7 @@ import { Message } from "@/app/app/interfaces";
 import { OnyxDocument, MinimalOnyxDocument } from "@/lib/search/interfaces";
 import HumanMessage from "@/app/app/message/HumanMessage";
 import { ErrorBanner } from "@/app/app/message/Resubmit";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { LlmDescriptor, LlmManager } from "@/lib/hooks";
 import AgentMessage from "@/app/app/message/messageComponents/AgentMessage";
 import Spacer from "@/refresh-components/Spacer";
@@ -18,7 +18,7 @@ import {
 } from "@/app/app/stores/useChatSessionStore";
 
 export interface ChatUIProps {
-  liveAssistant: MinimalPersonaSnapshot;
+  liveAgent: MinimalPersonaSnapshot;
   llmManager: LlmManager;
   setPresentingDocument: (doc: MinimalOnyxDocument | null) => void;
   onMessageSelection: (nodeId: number) => void;
@@ -52,7 +52,7 @@ export interface ChatUIProps {
 
 const ChatUI = React.memo(
   ({
-    liveAssistant,
+    liveAgent,
     llmManager,
     setPresentingDocument,
     onMessageSelection,
@@ -165,7 +165,7 @@ const ChatUI = React.memo(
 
               const previousMessage = i !== 0 ? messages[i - 1] : null;
               const chatStateData = {
-                assistant: liveAssistant,
+                agent: liveAgent,
                 docs: message.documents ?? emptyDocs,
                 citations: message.citations,
                 setPresentingDocument,
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index de99d815eef..831aac93544 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -9,7 +9,7 @@ import React, {
   useState,
 } from "react";
 import LineItem from "@/refresh-components/buttons/LineItem";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import LLMPopover from "@/refresh-components/popovers/LLMPopover";
 import { InputPrompt } from "@/app/app/interfaces";
 import { FilterManager, LlmManager, useFederatedConnectors } from "@/lib/hooks";
@@ -117,8 +117,8 @@ export interface AppInputBarProps {
   currentSessionFileTokenCount: number;
   availableContextTokens: number;
 
-  // assistants
-  selectedAssistant: MinimalPersonaSnapshot | undefined;
+  // agents
+  selectedAgent: MinimalPersonaSnapshot | undefined;
 
   toggleDocumentSidebar: () => void;
   handleFileUpload: (files: File[]) => void;
@@ -148,8 +148,8 @@ const AppInputBar = React.memo(
     chatState,
     currentSessionFileTokenCount,
     availableContextTokens,
-    // assistants
-    selectedAssistant,
+    // agents
+    selectedAgent,
 
     handleFileUpload,
     llmManager,
@@ -304,7 +304,7 @@ const AppInputBar = React.memo(
     const controlsLoading =
       ccPairsLoading ||
       federatedLoading ||
-      !selectedAssistant ||
+      !selectedAgent ||
       llmManager.isLoadingProviders;
     const [showPrompts, setShowPrompts] = useState(false);
 
@@ -398,17 +398,17 @@ const AppInputBar = React.memo(
       [currentMessageFiles]
     );
 
-    // Check if the assistant has search tools available (internal search or web search)
+    // Check if the agent has search tools available (internal search or web search)
     // AND if deep research is globally enabled in admin settings
     const showDeepResearch = useMemo(() => {
       const deepResearchGloballyEnabled =
         combinedSettings?.settings?.deep_research_enabled ?? true;
       return (
         deepResearchGloballyEnabled &&
-        hasSearchToolsAvailable(selectedAssistant?.tools || [])
+        hasSearchToolsAvailable(selectedAgent?.tools || [])
       );
     }, [
-      selectedAssistant?.tools,
+      selectedAgent?.tools,
       combinedSettings?.settings?.deep_research_enabled,
     ]);
 
@@ -710,9 +710,9 @@ const AppInputBar = React.memo(
                     controlsLoading && "invisible"
                   )}
                 >
-                  {selectedAssistant && selectedAssistant.tools.length > 0 && (
+                  {selectedAgent && selectedAgent.tools.length > 0 && (
                     <ActionsPopover
-                      selectedAssistant={selectedAssistant}
+                      selectedAgent={selectedAgent}
                       filterManager={filterManager}
                       availableSources={memoizedAvailableSources}
                       disabled={disabled}
@@ -754,10 +754,10 @@ const AppInputBar = React.memo(
                     )
                   )}
 
-                  {selectedAssistant &&
+                  {selectedAgent &&
                     forcedToolIds.length > 0 &&
                     forcedToolIds.map((toolId) => {
-                      const tool = selectedAssistant.tools.find(
+                      const tool = selectedAgent.tools.find(
                         (tool) => tool.id === toolId
                       );
                       if (!tool) {
diff --git a/web/src/sections/knowledge/AgentKnowledgePane.tsx b/web/src/sections/knowledge/AgentKnowledgePane.tsx
index 6bfbef134ac..d00b0f4459b 100644
--- a/web/src/sections/knowledge/AgentKnowledgePane.tsx
+++ b/web/src/sections/knowledge/AgentKnowledgePane.tsx
@@ -36,7 +36,7 @@ import { ProjectFile } from "@/app/app/projects/projectsService";
 import {
   AttachedDocumentSnapshot,
   HierarchyNodeSnapshot,
-} from "@/app/admin/assistants/interfaces";
+} from "@/app/admin/agents/interfaces";
 import { timeAgo } from "@/lib/time";
 import Spacer from "@/refresh-components/Spacer";
 import { Disabled } from "@/refresh-components/Disabled";
diff --git a/web/src/sections/knowledge/SourceHierarchyBrowser.tsx b/web/src/sections/knowledge/SourceHierarchyBrowser.tsx
index 2ec7c3c4688..0fb7c4ba200 100644
--- a/web/src/sections/knowledge/SourceHierarchyBrowser.tsx
+++ b/web/src/sections/knowledge/SourceHierarchyBrowser.tsx
@@ -45,7 +45,7 @@ import {
   fetchHierarchyNodes,
   fetchHierarchyNodeDocuments,
 } from "@/lib/hierarchy/svc";
-import { AttachedDocumentSnapshot } from "@/app/admin/assistants/interfaces";
+import { AttachedDocumentSnapshot } from "@/app/admin/agents/interfaces";
 import { timeAgo } from "@/lib/time";
 import Spacer from "@/refresh-components/Spacer";
 
diff --git a/web/src/sections/modals/AgentViewerModal.tsx b/web/src/sections/modals/AgentViewerModal.tsx
index b87d057aafa..adceaef1728 100644
--- a/web/src/sections/modals/AgentViewerModal.tsx
+++ b/web/src/sections/modals/AgentViewerModal.tsx
@@ -3,7 +3,7 @@
 import { useCallback, useMemo, useState } from "react";
 import { useRouter } from "next/navigation";
 import type { Route } from "next";
-import { FullPersona } from "@/app/admin/assistants/interfaces";
+import { FullPersona } from "@/app/admin/agents/interfaces";
 import { useModal } from "@/refresh-components/contexts/ModalContext";
 import Modal from "@/refresh-components/Modal";
 import { Section } from "@/layouts/general-layouts";
@@ -136,7 +136,7 @@ function AgentChatInput({ agent, onSubmit }: AgentChatInputProps) {
       llmManager={llmManager}
       chatState="input"
       filterManager={filterManager}
-      selectedAssistant={agent}
+      selectedAgent={agent}
       selectedDocuments={EMPTY_DOCS}
       removeDocs={() => {}}
       stopGenerating={() => {}}
diff --git a/web/src/sections/modals/ShareAgentModal.tsx b/web/src/sections/modals/ShareAgentModal.tsx
index 50dff82bf02..6c77f66f43a 100644
--- a/web/src/sections/modals/ShareAgentModal.tsx
+++ b/web/src/sections/modals/ShareAgentModal.tsx
@@ -30,7 +30,7 @@ import { Formik, useFormikContext } from "formik";
 import { useAgent } from "@/hooks/useAgents";
 import { Button as OpalButton } from "@opal/components";
 import { useLabels } from "@/lib/hooks";
-import { PersonaLabel } from "@/app/admin/assistants/interfaces";
+import { PersonaLabel } from "@/app/admin/agents/interfaces";
 
 const YOUR_ORGANIZATION_TAB = "Your Organization";
 const USERS_AND_GROUPS_TAB = "Users & Groups";
@@ -112,7 +112,7 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
 
   function handleCopyLink() {
     if (!agentId) return;
-    const url = `${window.location.origin}/chat?assistantId=${agentId}`;
+    const url = `${window.location.origin}/chat?agentId=${agentId}`;
     navigator.clipboard.writeText(url);
   }
 
diff --git a/web/src/sections/sidebar/AdminSidebar.tsx b/web/src/sections/sidebar/AdminSidebar.tsx
index d790413d2b7..e2764d27bce 100644
--- a/web/src/sections/sidebar/AdminSidebar.tsx
+++ b/web/src/sections/sidebar/AdminSidebar.tsx
@@ -86,15 +86,12 @@ const document_management_items = () => [
   },
 ];
 
-const custom_assistants_items = (
-  isCurator: boolean,
-  enableEnterprise: boolean
-) => {
+const custom_agents_items = (isCurator: boolean, enableEnterprise: boolean) => {
   const items = [
     {
       name: "Agents",
       icon: SvgOnyxOctagon,
-      link: "/admin/assistants",
+      link: "/admin/agents",
     },
   ];
 
@@ -167,7 +164,7 @@ const collections = (
       : []),
     {
       name: "Custom Agents",
-      items: custom_assistants_items(isCurator, enableEnterprise),
+      items: custom_agents_items(isCurator, enableEnterprise),
     },
     ...(isCurator && enableEnterprise
       ? [
diff --git a/web/src/sections/sidebar/AgentButton.tsx b/web/src/sections/sidebar/AgentButton.tsx
index d9271af4a72..bb523fd66b8 100644
--- a/web/src/sections/sidebar/AgentButton.tsx
+++ b/web/src/sections/sidebar/AgentButton.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import React, { memo } from "react";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import { usePinnedAgents, useCurrentAgent } from "@/hooks/useAgents";
 import { cn, noProp } from "@/lib/utils";
 import SidebarTab from "@/refresh-components/buttons/SidebarTab";
@@ -64,7 +64,7 @@ const AgentButton = memo(({ agent }: AgentButtonProps) => {
         <SidebarTab
           key={agent.id}
           leftIcon={() => <AgentAvatar agent={agent} />}
-          href={`/app?assistantId=${agent.id}`}
+          href={`/app?agentId=${agent.id}`}
           onClick={handleClick}
           transient={isCurrentAgent}
           rightChildren={
diff --git a/web/src/sections/sidebar/AppSidebar.tsx b/web/src/sections/sidebar/AppSidebar.tsx
index 09c66f9cd96..52bc6d9783b 100644
--- a/web/src/sections/sidebar/AppSidebar.tsx
+++ b/web/src/sections/sidebar/AppSidebar.tsx
@@ -4,7 +4,7 @@ import { useCallback, memo, useMemo, useState, useEffect, useRef } from "react";
 import useSWR from "swr";
 import { useRouter } from "next/navigation";
 import { useSettingsContext } from "@/providers/SettingsProvider";
-import { MinimalPersonaSnapshot } from "@/app/admin/assistants/interfaces";
+import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import Text from "@/refresh-components/texts/Text";
 import ChatButton from "@/sections/sidebar/ChatButton";
 import AgentButton from "@/sections/sidebar/AgentButton";
@@ -438,10 +438,10 @@ const MemoizedAppSidebarInner = memo(
               LOCAL_STORAGE_KEYS.HIDE_MOVE_CUSTOM_AGENT_MODAL
             ) === "true";
 
-          const isChatUsingDefaultAssistant =
+          const isChatUsingDefaultAgent =
             chatSession.persona_id === DEFAULT_PERSONA_ID;
 
-          if (!isChatUsingDefaultAssistant && !hideModal) {
+          if (!isChatUsingDefaultAgent && !hideModal) {
             setPendingMoveChatSession(chatSession);
             setPendingMoveProjectId(targetProject.id);
             setShowMoveCustomAgentModal(true);
@@ -495,7 +495,7 @@ const MemoizedAppSidebarInner = memo(
     const newSessionButton = useMemo(() => {
       const href =
         combinedSettings?.settings?.disable_default_assistant && currentAgent
-          ? `/app?assistantId=${currentAgent.id}`
+          ? `/app?agentId=${currentAgent.id}`
           : "/app";
       return (
         <div data-testid="AppSidebar/new-session">
@@ -592,7 +592,7 @@ const MemoizedAppSidebarInner = memo(
       combinedSettings?.settings?.vector_db_enabled !== false;
     const adminDefaultHref = vectorDbEnabled
       ? "/admin/indexing/status"
-      : "/admin/assistants";
+      : "/admin/agents";
 
     const settingsButton = useMemo(
       () => (
diff --git a/web/src/sections/sidebar/ChatSearchCommandMenu.tsx b/web/src/sections/sidebar/ChatSearchCommandMenu.tsx
index 329c2cd7099..8f8d7d593cc 100644
--- a/web/src/sections/sidebar/ChatSearchCommandMenu.tsx
+++ b/web/src/sections/sidebar/ChatSearchCommandMenu.tsx
@@ -156,7 +156,7 @@ export default function ChatSearchCommandMenu({
   const handleNewSession = useCallback(() => {
     const href =
       combinedSettings?.settings?.disable_default_assistant && currentAgent
-        ? `/app?assistantId=${currentAgent.id}`
+        ? `/app?agentId=${currentAgent.id}`
         : "/app";
     router.push(href as Route);
     setOpen(false);
diff --git a/web/tests/e2e/admin/admin_pages.spec.ts b/web/tests/e2e/admin/admin_pages.spec.ts
index 655bc1c5207..e5d95aacd5a 100644
--- a/web/tests/e2e/admin/admin_pages.spec.ts
+++ b/web/tests/e2e/admin/admin_pages.spec.ts
@@ -30,7 +30,7 @@ const ADMIN_PAGES: AdminPageSnapshot[] = [
   },
   {
     name: "Custom Agents - Agents",
-    path: "assistants",
+    path: "agents",
     pageTitle: "Agents",
     options: {
       paragraphText:
diff --git a/web/tests/e2e/admin/default-assistant.spec.ts b/web/tests/e2e/admin/default-agent.spec.ts
similarity index 99%
rename from web/tests/e2e/admin/default-assistant.spec.ts
rename to web/tests/e2e/admin/default-agent.spec.ts
index 385152bb929..09b5522a6e7 100644
--- a/web/tests/e2e/admin/default-assistant.spec.ts
+++ b/web/tests/e2e/admin/default-agent.spec.ts
@@ -621,7 +621,7 @@ test.describe("Chat Preferences Admin Page", () => {
       );
       const configData = await configResp.json();
       console.log(
-        `[toggle-all] Default assistant config: ${JSON.stringify(configData)}`
+        `[toggle-all] Default agent config: ${JSON.stringify(configData)}`
       );
     } catch (e) {
       console.warn(`[toggle-all] Failed to fetch config: ${e}`);
diff --git a/web/tests/e2e/admin/disable_default_assistant.spec.ts b/web/tests/e2e/admin/disable_default_agent.spec.ts
similarity index 86%
rename from web/tests/e2e/admin/disable_default_assistant.spec.ts
rename to web/tests/e2e/admin/disable_default_agent.spec.ts
index 8fcf091a8fe..17be175817f 100644
--- a/web/tests/e2e/admin/disable_default_assistant.spec.ts
+++ b/web/tests/e2e/admin/disable_default_agent.spec.ts
@@ -1,6 +1,6 @@
 import { test, expect, Page } from "@playwright/test";
 import { loginAs } from "@tests/e2e/utils/auth";
-import { createAssistant } from "@tests/e2e/utils/assistantUtils";
+import { createAgent } from "@tests/e2e/utils/agentUtils";
 import { OnyxApiClient } from "@tests/e2e/utils/onyxApiClient";
 
 const MAX_SETTING_SAVE_ATTEMPTS = 5;
@@ -32,7 +32,7 @@ async function expandAdvancedOptions(page: Page): Promise<void> {
 }
 
 /**
- * Toggle the "Always Start with an Agent" setting (formerly "Disable Default Assistant")
+ * Toggle the "Always Start with an Agent" setting (formerly "Disable Default Agent")
  * on the Chat Preferences page. Uses auto-save via the SwitchField.
  *
  * The switch is a SwitchField with name="disable_default_assistant" which renders
@@ -91,7 +91,7 @@ async function setDisableDefaultAssistantSetting(
   );
 }
 
-test.describe("Disable Default Assistant Setting @exclusive", () => {
+test.describe("Disable Default Agent Setting @exclusive", () => {
   let createdAssistantId: number | null = null;
 
   test.beforeEach(async ({ page }) => {
@@ -104,11 +104,11 @@ test.describe("Disable Default Assistant Setting @exclusive", () => {
     // Clean up any assistant created during the test
     if (createdAssistantId !== null) {
       const client = new OnyxApiClient(page.request);
-      await client.deleteAssistant(createdAssistantId);
+      await client.deleteAgent(createdAssistantId);
       createdAssistantId = null;
     }
 
-    // Ensure default assistant is enabled (switch unchecked) after each test
+    // Ensure default agent is enabled (switch unchecked) after each test
     // to avoid interfering with other tests
     await setDisableDefaultAssistantSetting(page, false);
   });
@@ -129,21 +129,21 @@ test.describe("Disable Default Assistant Setting @exclusive", () => {
 
     // Navigate to app and create a new assistant to ensure there's one besides the default
     await page.goto("/app");
-    const assistantName = `Test Assistant ${Date.now()}`;
-    await createAssistant(page, {
-      name: assistantName,
+    const agentName = `Test Assistant ${Date.now()}`;
+    await createAgent(page, {
+      name: agentName,
       description: "Test assistant for new session button test",
       instructions: "You are a helpful test assistant.",
     });
 
     // Extract the assistant ID from the URL
     const currentUrl = page.url();
-    const assistantIdMatch = currentUrl.match(/assistantId=(\d+)/);
-    expect(assistantIdMatch).toBeTruthy();
+    const agentIdMatch = currentUrl.match(/agentId=(\d+)/);
+    expect(agentIdMatch).toBeTruthy();
 
     // Store for cleanup
-    if (assistantIdMatch) {
-      createdAssistantId = Number(assistantIdMatch[1]);
+    if (agentIdMatch) {
+      createdAssistantId = Number(agentIdMatch[1]);
     }
 
     // Click the "New Session" button
@@ -152,11 +152,11 @@ test.describe("Disable Default Assistant Setting @exclusive", () => {
     );
     await newSessionButton.click();
 
-    // Verify the WelcomeMessage shown is NOT from the default assistant
-    // Default assistant shows onyx-logo, custom assistants show assistant-name-display
+    // Verify the WelcomeMessage shown is NOT from the default agent
+    // Default agent shows onyx-logo, custom agents show agent-name-display
     await expect(page.locator('[data-testid="onyx-logo"]')).not.toBeVisible();
     await expect(
-      page.locator('[data-testid="assistant-name-display"]')
+      page.locator('[data-testid="agent-name-display"]')
     ).toBeVisible();
   });
 
@@ -169,12 +169,12 @@ test.describe("Disable Default Assistant Setting @exclusive", () => {
     // Navigate directly to /app
     await page.goto("/app");
 
-    // Verify that we didn't land on the default assistant (ID 0)
+    // Verify that we didn't land on the default agent (ID 0)
     // The assistant selection should be a pinned or available assistant (not ID 0)
     const currentUrl = page.url();
-    // If assistantId is in URL, it should not be 0
-    if (currentUrl.includes("assistantId=")) {
-      expect(currentUrl).not.toContain("assistantId=0");
+    // If agentId is in URL, it should not be 0
+    if (currentUrl.includes("agentId=")) {
+      expect(currentUrl).not.toContain("agentId=0");
     }
   });
 
@@ -228,7 +228,7 @@ test.describe("Disable Default Assistant Setting @exclusive", () => {
     );
   });
 
-  test("default assistant is available again when setting is disabled", async ({
+  test("default agent is available again when setting is disabled", async ({
     page,
   }) => {
     // Navigate to settings and ensure setting is disabled
@@ -237,18 +237,18 @@ test.describe("Disable Default Assistant Setting @exclusive", () => {
     // Navigate directly to /app without parameters
     await page.goto("/app");
 
-    // The default assistant (ID 0) should be available
+    // The default agent (ID 0) should be available
     // We can verify this by checking that the app loads successfully
     // and doesn't force navigation to a specific assistant
     expect(page.url()).toContain("/app");
 
-    // Verify the new session button navigates to /app without assistantId
+    // Verify the new session button navigates to /app without agentId
     const newSessionButton = page.locator(
       '[data-testid="AppSidebar/new-session"]'
     );
     await newSessionButton.click();
 
-    // Should navigate to /app without assistantId parameter
+    // Should navigate to /app without agentId parameter
     const newUrl = page.url();
     expect(newUrl).toContain("/app");
   });
diff --git a/web/tests/e2e/admin/discord-bot/channel-config.spec.ts b/web/tests/e2e/admin/discord-bot/channel-config.spec.ts
index 05de7fffeb2..7ee14122132 100644
--- a/web/tests/e2e/admin/discord-bot/channel-config.spec.ts
+++ b/web/tests/e2e/admin/discord-bot/channel-config.spec.ts
@@ -51,9 +51,7 @@ test.describe("Guild Detail Page & Channel Configuration", () => {
     });
 
     // Find the persona/agent dropdown (InputSelect)
-    const agentDropdown = adminPage.locator(
-      'button:has-text("Default Assistant")'
-    );
+    const agentDropdown = adminPage.locator('button:has-text("Default Agent")');
 
     if (await agentDropdown.isVisible({ timeout: 5000 }).catch(() => false)) {
       await agentDropdown.click();
diff --git a/web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts b/web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts
index f8c7b172094..4b1337b37ba 100644
--- a/web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts
+++ b/web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts
@@ -61,7 +61,7 @@ test.afterAll(async ({ browser }: { browser: Browser }) => {
 
   // Delete the assistant first (it references the tool)
   if (createdAssistantId !== null) {
-    await client.deleteAssistant(createdAssistantId);
+    await client.deleteAgent(createdAssistantId);
   }
 
   // Then delete the tool
@@ -211,12 +211,12 @@ test("Tool OAuth Configuration: Creation, Selection, and Assistant Integration",
   await page.waitForLoadState("networkidle");
 
   // Fill in basic assistant details
-  const assistantName = `Test Assistant ${Date.now()}`;
-  const assistantDescription = "Assistant with OAuth tool";
+  const agentName = `Test Assistant ${Date.now()}`;
+  const agentDescription = "Assistant with OAuth tool";
   const assistantInstructions = "Use the tool when needed";
 
-  await page.locator('input[name="name"]').fill(assistantName);
-  await page.locator('textarea[name="description"]').fill(assistantDescription);
+  await page.locator('input[name="name"]').fill(agentName);
+  await page.locator('textarea[name="description"]').fill(agentDescription);
   await page
     .locator('textarea[name="instructions"]')
     .fill(assistantInstructions);
@@ -241,14 +241,14 @@ test("Tool OAuth Configuration: Creation, Selection, and Assistant Integration",
   await createButton.click();
 
   // Verify redirection to app page with the new assistant ID
-  await page.waitForURL(/.*\/app\?assistantId=\d+.*/, { timeout: 10000 });
+  await page.waitForURL(/.*\/app\?agentId=\d+.*/, { timeout: 10000 });
   const assistantUrl = page.url();
-  const assistantIdMatch = assistantUrl.match(/assistantId=(\d+)/);
-  expect(assistantIdMatch).toBeTruthy();
+  const agentIdMatch = assistantUrl.match(/agentId=(\d+)/);
+  expect(agentIdMatch).toBeTruthy();
 
   // Store assistant ID for cleanup
-  if (assistantIdMatch) {
-    createdAssistantId = Number(assistantIdMatch[1]);
+  if (agentIdMatch) {
+    createdAssistantId = Number(agentIdMatch[1]);
   }
 
   // Test complete! We've verified:
diff --git a/web/tests/e2e/assistants/create_and_edit_assistant.spec.ts b/web/tests/e2e/agents/create_and_edit_agent.spec.ts
similarity index 87%
rename from web/tests/e2e/assistants/create_and_edit_assistant.spec.ts
rename to web/tests/e2e/agents/create_and_edit_agent.spec.ts
index e07ed24cde0..068b5e9e6b1 100644
--- a/web/tests/e2e/assistants/create_and_edit_assistant.spec.ts
+++ b/web/tests/e2e/agents/create_and_edit_agent.spec.ts
@@ -129,7 +129,7 @@ test.describe("Assistant Creation and Edit Verification", () => {
         });
         const page = await context.newPage();
         const cleanupClient = new OnyxApiClient(page.request);
-        await cleanupClient.deleteAssistant(userFilesAssistantId);
+        await cleanupClient.deleteAgent(userFilesAssistantId);
         await context.close();
         console.log(
           "[test] Cleanup completed - deleted User Files Only assistant"
@@ -143,16 +143,15 @@ test.describe("Assistant Creation and Edit Verification", () => {
       await page.context().clearCookies();
       await loginAsWorkerUser(page, testInfo.workerIndex);
 
-      const assistantName = "E2E User Files Assistant";
-      const assistantDescription =
-        "Testing user file uploads without connectors";
+      const agentName = "E2E User Files Assistant";
+      const agentDescription = "Testing user file uploads without connectors";
       const assistantInstructions = "Help users with their documents.";
 
       await page.goto("/app/agents/create");
 
       // Fill in basic assistant details
-      await getNameInput(page).fill(assistantName);
-      await getDescriptionInput(page).fill(assistantDescription);
+      await getNameInput(page).fill(agentName);
+      await getDescriptionInput(page).fill(agentDescription);
       await getInstructionsTextarea(page).fill(assistantInstructions);
 
       // Enable Knowledge toggle
@@ -174,18 +173,18 @@ test.describe("Assistant Creation and Edit Verification", () => {
       await getCreateSubmitButton(page).click();
 
       // Verify redirection to chat page with the new assistant
-      await page.waitForURL(/.*\/app\?assistantId=\d+.*/);
+      await page.waitForURL(/.*\/app\?agentId=\d+.*/);
       const url = page.url();
-      const assistantIdMatch = url.match(/assistantId=(\d+)/);
-      expect(assistantIdMatch).toBeTruthy();
+      const agentIdMatch = url.match(/agentId=(\d+)/);
+      expect(agentIdMatch).toBeTruthy();
 
       // Store assistant ID for cleanup
-      if (assistantIdMatch) {
-        userFilesAssistantId = Number(assistantIdMatch[1]);
+      if (agentIdMatch) {
+        userFilesAssistantId = Number(agentIdMatch[1]);
       }
 
       console.log(
-        `[test] Successfully created assistant without connectors: ${assistantName}`
+        `[test] Successfully created assistant without connectors: ${agentName}`
       );
     });
   });
@@ -204,7 +203,7 @@ test.describe("Assistant Creation and Edit Verification", () => {
       const cleanupClient = new OnyxApiClient(page.request);
 
       if (knowledgeAssistantId !== null) {
-        await cleanupClient.deleteAssistant(knowledgeAssistantId);
+        await cleanupClient.deleteAgent(knowledgeAssistantId);
       }
       if (ccPairId && documentSetId) {
         await cleanupClient.deleteDocumentSet(documentSetId);
@@ -241,8 +240,8 @@ test.describe("Assistant Creation and Edit Verification", () => {
       await loginAsWorkerUser(page, testInfo.workerIndex);
 
       // --- Initial Values ---
-      const assistantName = "Test Assistant 1";
-      const assistantDescription = "This is a test assistant description.";
+      const agentName = "Test Assistant 1";
+      const agentDescription = "This is a test assistant description.";
       const assistantInstructions = "These are the test instructions.";
       const assistantReminder = "Initial reminder.";
       const assistantStarterMessage = "Initial starter message?";
@@ -258,8 +257,8 @@ test.describe("Assistant Creation and Edit Verification", () => {
       await page.goto("/app/agents/create");
 
       // --- Fill in Initial Assistant Details ---
-      await getNameInput(page).fill(assistantName);
-      await getDescriptionInput(page).fill(assistantDescription);
+      await getNameInput(page).fill(agentName);
+      await getDescriptionInput(page).fill(agentDescription);
       await getInstructionsTextarea(page).fill(assistantInstructions);
 
       // Reminder
@@ -287,24 +286,24 @@ test.describe("Assistant Creation and Edit Verification", () => {
       await getCreateSubmitButton(page).click();
 
       // Verify redirection to chat page with the new assistant ID
-      await page.waitForURL(/.*\/app\?assistantId=\d+.*/);
+      await page.waitForURL(/.*\/app\?agentId=\d+.*/);
       const url = page.url();
-      const assistantIdMatch = url.match(/assistantId=(\d+)/);
-      expect(assistantIdMatch).toBeTruthy();
-      const assistantId = assistantIdMatch ? assistantIdMatch[1] : null;
-      expect(assistantId).not.toBeNull();
+      const agentIdMatch = url.match(/agentId=(\d+)/);
+      expect(agentIdMatch).toBeTruthy();
+      const agentId = agentIdMatch ? agentIdMatch[1] : null;
+      expect(agentId).not.toBeNull();
       await expectScreenshot(page, { name: "welcome-page-with-assistant" });
 
       // Store assistant ID for cleanup
-      knowledgeAssistantId = Number(assistantId);
+      knowledgeAssistantId = Number(agentId);
 
       // Navigate directly to the edit page
-      await page.goto(`/app/agents/edit/${assistantId}`);
-      await page.waitForURL(`**/app/agents/edit/${assistantId}`);
+      await page.goto(`/app/agents/edit/${agentId}`);
+      await page.waitForURL(`**/app/agents/edit/${agentId}`);
 
       // Verify basic fields
-      await expect(getNameInput(page)).toHaveValue(assistantName);
-      await expect(getDescriptionInput(page)).toHaveValue(assistantDescription);
+      await expect(getNameInput(page)).toHaveValue(agentName);
+      await expect(getDescriptionInput(page)).toHaveValue(agentDescription);
       await expect(getInstructionsTextarea(page)).toHaveValue(
         assistantInstructions
       );
@@ -341,12 +340,12 @@ test.describe("Assistant Creation and Edit Verification", () => {
       await getUpdateSubmitButton(page).click();
 
       // Verify redirection back to the chat page
-      await page.waitForURL(/.*\/app\?assistantId=\d+.*/);
-      expect(page.url()).toContain(`assistantId=${assistantId}`);
+      await page.waitForURL(/.*\/app\?agentId=\d+.*/);
+      expect(page.url()).toContain(`agentId=${agentId}`);
 
       // --- Navigate to Edit Page Again and Verify Edited Values ---
-      await page.goto(`/app/agents/edit/${assistantId}`);
-      await page.waitForURL(`**/app/agents/edit/${assistantId}`);
+      await page.goto(`/app/agents/edit/${agentId}`);
+      await page.waitForURL(`**/app/agents/edit/${agentId}`);
 
       // Verify basic fields
       await expect(getNameInput(page)).toHaveValue(editedAssistantName);
@@ -381,7 +380,7 @@ test.describe("Assistant Creation and Edit Verification", () => {
       );
 
       console.log(
-        `[test] Successfully tested Knowledge-enabled assistant: ${assistantName}`
+        `[test] Successfully tested Knowledge-enabled assistant: ${agentName}`
       );
     });
   });
diff --git a/web/tests/e2e/assistants/llm_provider_rbac.spec.ts b/web/tests/e2e/agents/llm_provider_rbac.spec.ts
similarity index 100%
rename from web/tests/e2e/assistants/llm_provider_rbac.spec.ts
rename to web/tests/e2e/agents/llm_provider_rbac.spec.ts
diff --git a/web/tests/e2e/assistants/user_file_attachment.spec.ts b/web/tests/e2e/agents/user_file_attachment.spec.ts
similarity index 90%
rename from web/tests/e2e/assistants/user_file_attachment.spec.ts
rename to web/tests/e2e/agents/user_file_attachment.spec.ts
index fe6085d2c06..7ff71309041 100644
--- a/web/tests/e2e/assistants/user_file_attachment.spec.ts
+++ b/web/tests/e2e/agents/user_file_attachment.spec.ts
@@ -39,7 +39,7 @@ const extractAssistantIdFromCreateResponse = (
   return null;
 };
 
-const createAssistantAndGetId = async (page: Page): Promise<number> => {
+const createAgentAndGetId = async (page: Page): Promise<number> => {
   const createResponsePromise = page.waitForResponse(
     (response) => {
       if (response.request().method() !== "POST" || !response.ok()) {
@@ -62,23 +62,23 @@ const createAssistantAndGetId = async (page: Page): Promise<number> => {
   await page.waitForURL(
     (url) => {
       const href = typeof url === "string" ? url : url.toString();
-      return /\/app\?assistantId=\d+/.test(href) || /\/app\?chatId=/.test(href);
+      return /\/app\?agentId=\d+/.test(href) || /\/app\?chatId=/.test(href);
     },
     { timeout: 20000 }
   );
 
-  const assistantIdFromUrl = page.url().match(/assistantId=(\d+)/);
-  if (assistantIdFromUrl?.[1]) {
-    return Number(assistantIdFromUrl[1]);
+  const agentIdFromUrl = page.url().match(/agentId=(\d+)/);
+  if (agentIdFromUrl?.[1]) {
+    return Number(agentIdFromUrl[1]);
   }
 
   const createPayload = (await createResponse
     .json()
     .catch(() => null)) as Record<string, unknown> | null;
-  const assistantIdFromResponse =
+  const agentIdFromResponse =
     extractAssistantIdFromCreateResponse(createPayload);
-  if (assistantIdFromResponse !== null) {
-    return assistantIdFromResponse;
+  if (agentIdFromResponse !== null) {
+    return agentIdFromResponse;
   }
 
   throw new Error(
@@ -245,8 +245,8 @@ test.describe("User File Attachment to Assistant", () => {
     await page.context().clearCookies();
     await loginAsRandomUser(page);
 
-    const assistantName = `User File Test ${Date.now()}`;
-    const assistantDescription = "Testing user file persistence";
+    const agentName = `User File Test ${Date.now()}`;
+    const agentDescription = "Testing user file persistence";
     const assistantInstructions = "Help users with their uploaded files.";
     const testFileName = `test-file-${Date.now()}.txt`;
     const testFileContent =
@@ -257,8 +257,8 @@ test.describe("User File Attachment to Assistant", () => {
     await page.waitForLoadState("networkidle");
 
     // Fill in basic assistant details
-    await getNameInput(page).fill(assistantName);
-    await getDescriptionInput(page).fill(assistantDescription);
+    await getNameInput(page).fill(agentName);
+    await getDescriptionInput(page).fill(agentDescription);
     await getInstructionsTextarea(page).fill(assistantInstructions);
 
     // Enable Knowledge toggle
@@ -282,15 +282,15 @@ test.describe("User File Attachment to Assistant", () => {
     await expect(fileText).toBeVisible();
 
     // Submit the assistant creation form and resolve assistant ID from URL or API response.
-    const assistantId = await createAssistantAndGetId(page);
+    const agentId = await createAgentAndGetId(page);
 
     console.log(
-      `[test] Created assistant ${assistantName} with ID ${assistantId}, now verifying file persistence...`
+      `[test] Created assistant ${agentName} with ID ${agentId}, now verifying file persistence...`
     );
 
     // Navigate to the edit page for the assistant
-    await page.goto(`/app/agents/edit/${assistantId}`);
-    await page.waitForURL(`**/app/agents/edit/${assistantId}`);
+    await page.goto(`/app/agents/edit/${agentId}`);
+    await page.waitForURL(`**/app/agents/edit/${agentId}`);
     await page.waitForLoadState("networkidle");
 
     // Verify knowledge toggle is still enabled
@@ -325,7 +325,7 @@ test.describe("User File Attachment to Assistant", () => {
     await expect(fileRowAfterEdit).toBeVisible({ timeout: 5000 });
 
     console.log(
-      `[test] Successfully verified user file ${testFileName} is persisted and selected for assistant ${assistantName}`
+      `[test] Successfully verified user file ${testFileName} is persisted and selected for assistant ${agentName}`
     );
   });
 
@@ -338,7 +338,7 @@ test.describe("User File Attachment to Assistant", () => {
     await page.context().clearCookies();
     await loginAsRandomUser(page);
 
-    const assistantName = `Multi-File Test ${Date.now()}`;
+    const agentName = `Multi-File Test ${Date.now()}`;
     const testFileName1 = `test-file-1-${Date.now()}.txt`;
     const testFileName2 = `test-file-2-${Date.now()}.txt`;
     const testFileContent = "Test content for multi-file test.";
@@ -348,7 +348,7 @@ test.describe("User File Attachment to Assistant", () => {
     await page.waitForLoadState("networkidle");
 
     // Fill in basic assistant details
-    await getNameInput(page).fill(assistantName);
+    await getNameInput(page).fill(agentName);
     await getDescriptionInput(page).fill("Testing multiple user files");
     await getInstructionsTextarea(page).fill("Help with multiple files.");
 
@@ -370,10 +370,10 @@ test.describe("User File Attachment to Assistant", () => {
     // already adds files to user_file_ids. Clicking would toggle them OFF.
 
     // Create the assistant and resolve assistant ID from URL or API response.
-    const assistantId = await createAssistantAndGetId(page);
+    const agentId = await createAgentAndGetId(page);
 
     // Go to edit page
-    await page.goto(`/app/agents/edit/${assistantId}`);
+    await page.goto(`/app/agents/edit/${agentId}`);
     await page.waitForLoadState("networkidle");
 
     // Navigate to files view
@@ -398,7 +398,7 @@ test.describe("User File Attachment to Assistant", () => {
     }
 
     console.log(
-      `[test] Successfully verified multiple user files are persisted for assistant ${assistantName}`
+      `[test] Successfully verified multiple user files are persisted for assistant ${agentName}`
     );
   });
 });
diff --git a/web/tests/e2e/chat/chat_message_rendering.spec.ts b/web/tests/e2e/chat/chat_message_rendering.spec.ts
index 634b07f1c07..018011725cc 100644
--- a/web/tests/e2e/chat/chat_message_rendering.spec.ts
+++ b/web/tests/e2e/chat/chat_message_rendering.spec.ts
@@ -116,18 +116,18 @@ let turnCounter = 0;
 function buildMockStream(content: string): string {
   turnCounter += 1;
   const userMessageId = turnCounter * 100 + 1;
-  const assistantMessageId = turnCounter * 100 + 2;
+  const agentMessageId = turnCounter * 100 + 2;
 
   const packets = [
     {
       user_message_id: userMessageId,
-      reserved_assistant_message_id: assistantMessageId,
+      reserved_assistant_message_id: agentMessageId,
     },
     {
       placement: { turn_index: 0, tab_index: 0 },
       obj: {
         type: "message_start",
-        id: `mock-${assistantMessageId}`,
+        id: `mock-${agentMessageId}`,
         content,
         final_documents: null,
       },
@@ -137,7 +137,7 @@ function buildMockStream(content: string): string {
       obj: { type: "stop", stop_reason: "finished" },
     },
     {
-      message_id: assistantMessageId,
+      message_id: agentMessageId,
       citations: {},
       files: [],
     },
@@ -149,7 +149,7 @@ function buildMockStream(content: string): string {
 function buildMockSearchStream(options: SearchMockOptions): string {
   turnCounter += 1;
   const userMessageId = turnCounter * 100 + 1;
-  const assistantMessageId = turnCounter * 100 + 2;
+  const agentMessageId = turnCounter * 100 + 2;
 
   const fullDocs = options.documents.map((doc) => ({
     ...doc,
@@ -167,7 +167,7 @@ function buildMockSearchStream(options: SearchMockOptions): string {
   const packets: Record<string, unknown>[] = [
     {
       user_message_id: userMessageId,
-      reserved_assistant_message_id: assistantMessageId,
+      reserved_assistant_message_id: agentMessageId,
     },
     {
       placement: { turn_index: 0, tab_index: 0 },
@@ -194,7 +194,7 @@ function buildMockSearchStream(options: SearchMockOptions): string {
       placement: { turn_index: 1, tab_index: 0 },
       obj: {
         type: "message_start",
-        id: `mock-${assistantMessageId}`,
+        id: `mock-${agentMessageId}`,
         content: options.content,
         final_documents: fullDocs,
       },
@@ -212,7 +212,7 @@ function buildMockSearchStream(options: SearchMockOptions): string {
       obj: { type: "stop", stop_reason: "finished" },
     },
     {
-      message_id: assistantMessageId,
+      message_id: agentMessageId,
       citations: options.citations,
       files: [],
     },
diff --git a/web/tests/e2e/chat/current_assistant.spec.ts b/web/tests/e2e/chat/current_agent.spec.ts
similarity index 91%
rename from web/tests/e2e/chat/current_assistant.spec.ts
rename to web/tests/e2e/chat/current_agent.spec.ts
index 7006e2b5697..bb78b7ad4e7 100644
--- a/web/tests/e2e/chat/current_assistant.spec.ts
+++ b/web/tests/e2e/chat/current_agent.spec.ts
@@ -1,10 +1,7 @@
 import { test, expect } from "@playwright/test";
 import { dragElementAbove, dragElementBelow } from "@tests/e2e/utils/dragUtils";
 import { loginAsRandomUser } from "@tests/e2e/utils/auth";
-import {
-  createAssistant,
-  pinAssistantByName,
-} from "@tests/e2e/utils/assistantUtils";
+import { createAgent, pinAgentByName } from "@tests/e2e/utils/agentUtils";
 
 // TODO (chris): figure out why this test is flakey
 test.skip("Assistant Drag and Drop", async ({ page }) => {
@@ -19,32 +16,32 @@ test.skip("Assistant Drag and Drop", async ({ page }) => {
   const nameA = `E2E Assistant A ${ts}`;
   const nameB = `E2E Assistant B ${ts}`;
   const nameC = `E2E Assistant C ${ts}`;
-  await createAssistant(page, {
+  await createAgent(page, {
     name: nameA,
     description: "E2E-created assistant A",
     instructions: "Assistant A instructions",
   });
-  await pinAssistantByName(page, nameA);
+  await pinAgentByName(page, nameA);
   await expect(
     page.locator('[data-testid^="assistant-["]').filter({ hasText: nameA })
   ).toBeVisible();
 
-  await createAssistant(page, {
+  await createAgent(page, {
     name: nameB,
     description: "E2E-created assistant B",
     instructions: "Assistant B instructions",
   });
-  await pinAssistantByName(page, nameB);
+  await pinAgentByName(page, nameB);
   await expect(
     page.locator('[data-testid^="assistant-["]').filter({ hasText: nameB })
   ).toBeVisible();
 
-  await createAssistant(page, {
+  await createAgent(page, {
     name: nameC,
     description: "E2E-created assistant C",
     instructions: "Assistant C instructions",
   });
-  await pinAssistantByName(page, nameC);
+  await pinAgentByName(page, nameC);
   await expect(
     page.locator('[data-testid^="assistant-["]').filter({ hasText: nameC })
   ).toBeVisible();
diff --git a/web/tests/e2e/chat/default_assistant.spec.ts b/web/tests/e2e/chat/default_agent.spec.ts
similarity index 96%
rename from web/tests/e2e/chat/default_assistant.spec.ts
rename to web/tests/e2e/chat/default_agent.spec.ts
index 48089c4bde3..fbfedf6f90f 100644
--- a/web/tests/e2e/chat/default_assistant.spec.ts
+++ b/web/tests/e2e/chat/default_agent.spec.ts
@@ -4,8 +4,8 @@ import { loginAsRandomUser, loginAs } from "@tests/e2e/utils/auth";
 import {
   sendMessage,
   startNewChat,
-  verifyAssistantIsChosen,
-  verifyDefaultAssistantIsChosen,
+  verifyAgentIsChosen,
+  verifyDefaultAgentIsChosen,
 } from "@tests/e2e/utils/chatActions";
 import {
   TOOL_IDS,
@@ -119,7 +119,7 @@ test.describe("Default Agent Tests", () => {
       await page.getByRole("button", { name: "Create" }).click();
 
       // Wait for agent to be created and selected
-      await verifyAssistantIsChosen(page, "Custom Test Agent");
+      await verifyAgentIsChosen(page, "Custom Test Agent");
 
       // Greeting should NOT appear for custom agent
       const customGreeting = await page.$('[data-testid="onyx-logo"]');
@@ -137,10 +137,10 @@ test.describe("Default Agent Tests", () => {
       expect(logoElement).toBeTruthy();
 
       // Should NOT show agent name for default agent
-      const assistantNameElement = await page.$(
-        '[data-testid="assistant-name-display"]'
+      const agentNameElement = await page.$(
+        '[data-testid="agent-name-display"]'
       );
-      expect(assistantNameElement).toBeNull();
+      expect(agentNameElement).toBeNull();
     });
 
     test("custom agents should show name and icon instead of logo", async ({
@@ -162,14 +162,14 @@ test.describe("Default Agent Tests", () => {
       await page.getByRole("button", { name: "Create" }).click();
 
       // Wait for agent to be created and selected
-      await verifyAssistantIsChosen(page, "Custom Agent");
+      await verifyAgentIsChosen(page, "Custom Agent");
 
       // Should show agent name and icon, not Onyx logo
-      const assistantNameElement = await page.waitForSelector(
-        '[data-testid="assistant-name-display"]',
+      const agentNameElement = await page.waitForSelector(
+        '[data-testid="agent-name-display"]',
         { timeout: 5000 }
       );
-      const nameText = await assistantNameElement.textContent();
+      const nameText = await agentNameElement.textContent();
       expect(nameText).toContain("Custom Agent");
 
       // Onyx logo should NOT be shown
@@ -211,7 +211,7 @@ test.describe("Default Agent Tests", () => {
       await page.getByRole("button", { name: "Create" }).click();
 
       // Wait for assistant to be created and selected
-      await verifyAssistantIsChosen(page, "Test Agent with Starters");
+      await verifyAgentIsChosen(page, "Test Agent with Starters");
 
       // Starter messages container might exist but be empty for custom agents
       const starterMessagesContainer = await page.$(
@@ -231,7 +231,7 @@ test.describe("Default Agent Tests", () => {
   test.describe("Agent Selection", () => {
     test("default agent should be selected for new chats", async ({ page }) => {
       // Verify the input placeholder indicates default agent (Onyx)
-      await verifyDefaultAssistantIsChosen(page);
+      await verifyDefaultAgentIsChosen(page);
     });
 
     test("default agent should NOT appear in agent selector", async ({
@@ -247,7 +247,7 @@ test.describe("Default Agent Tests", () => {
         .waitFor({ state: "visible", timeout: 5000 });
 
       // Look for default agent by name - it should NOT be there
-      const assistantElements = await page.$$('[data-testid^="assistant-"]');
+      const assistantElements = await page.$$('[data-testid^="agent-"]');
       const assistantTexts = await Promise.all(
         assistantElements.map((el) => el.textContent())
       );
@@ -284,13 +284,13 @@ test.describe("Default Agent Tests", () => {
       await page.getByRole("button", { name: "Create" }).click();
 
       // Verify switched to custom agent
-      await verifyAssistantIsChosen(page, "Switch Test Agent");
+      await verifyAgentIsChosen(page, "Switch Test Agent");
 
       // Start new chat to go back to default
       await startNewChat(page);
 
       // Should be back to default agent
-      await verifyDefaultAssistantIsChosen(page);
+      await verifyDefaultAgentIsChosen(page);
     });
   });
 
diff --git a/web/tests/e2e/chat/live_assistant.spec.ts b/web/tests/e2e/chat/live_agent.spec.ts
similarity index 81%
rename from web/tests/e2e/chat/live_assistant.spec.ts
rename to web/tests/e2e/chat/live_agent.spec.ts
index 939de45d317..d044b26bbb6 100644
--- a/web/tests/e2e/chat/live_assistant.spec.ts
+++ b/web/tests/e2e/chat/live_agent.spec.ts
@@ -3,8 +3,8 @@ import { loginAsRandomUser } from "@tests/e2e/utils/auth";
 import {
   sendMessage,
   startNewChat,
-  verifyAssistantIsChosen,
-  verifyDefaultAssistantIsChosen,
+  verifyAgentIsChosen,
+  verifyDefaultAgentIsChosen,
 } from "@tests/e2e/utils/chatActions";
 
 test("Chat workflow", async ({ page }) => {
@@ -12,7 +12,7 @@ test("Chat workflow", async ({ page }) => {
   await page.context().clearCookies();
   // Use waitForSelector for robustness instead of expect().toBeVisible()
   // await page.waitForSelector(
-  //   `//div[@aria-label="Agents Modal"]//*[contains(text(), "${assistantName}") and not(contains(@class, 'invisible'))]`,
+  //   `//div[@aria-label="Agents Modal"]//*[contains(text(), "${agentName}") and not(contains(@class, 'invisible'))]`,
   //   { state: "visible", timeout: 10000 }
   // );
   await loginAsRandomUser(page);
@@ -21,14 +21,14 @@ test("Chat workflow", async ({ page }) => {
   await page.goto("/app");
   await page.waitForLoadState("networkidle");
 
-  // Test interaction with the Default assistant
+  // Test interaction with the Default agent
   await sendMessage(page, "Hi");
 
   // Start a new chat session
   await startNewChat(page);
 
   // Verify the presence of the expected text
-  await verifyDefaultAssistantIsChosen(page);
+  await verifyDefaultAgentIsChosen(page);
 
   // Test creation of a new assistant
   await page.getByTestId("AppSidebar/more-agents").click();
@@ -46,12 +46,12 @@ test("Chat workflow", async ({ page }) => {
   await page.getByRole("button", { name: "Create" }).click();
 
   // Verify the successful creation of the new assistant
-  await verifyAssistantIsChosen(page, "Test Assistant");
+  await verifyAgentIsChosen(page, "Test Assistant");
 
   // Start another new chat session
   await startNewChat(page);
   await page.waitForLoadState("networkidle");
 
-  // Verify the presence of the default assistant text
-  await verifyDefaultAssistantIsChosen(page);
+  // Verify the presence of the default agent text
+  await verifyDefaultAgentIsChosen(page);
 });
diff --git a/web/tests/e2e/chat/llm_ordering.spec.ts b/web/tests/e2e/chat/llm_ordering.spec.ts
index f9ab482e8f4..bbe67bda8f2 100644
--- a/web/tests/e2e/chat/llm_ordering.spec.ts
+++ b/web/tests/e2e/chat/llm_ordering.spec.ts
@@ -1,7 +1,7 @@
 import { test, expect } from "@playwright/test";
 import { loginAs } from "@tests/e2e/utils/auth";
 import { verifyCurrentModel } from "@tests/e2e/utils/chatActions";
-import { ensureImageGenerationEnabled } from "@tests/e2e/utils/assistantUtils";
+import { ensureImageGenerationEnabled } from "@tests/e2e/utils/agentUtils";
 import { OnyxApiClient } from "@tests/e2e/utils/onyxApiClient";
 
 test.describe("LLM Ordering", () => {
diff --git a/web/tests/e2e/chat/llm_runtime_selection.spec.ts b/web/tests/e2e/chat/llm_runtime_selection.spec.ts
index 47b48dd2388..af669eb94c2 100644
--- a/web/tests/e2e/chat/llm_runtime_selection.spec.ts
+++ b/web/tests/e2e/chat/llm_runtime_selection.spec.ts
@@ -130,18 +130,18 @@ async function waitForModelOnProvider(
 
 function buildMockStreamResponse(turn: number): string {
   const userMessageId = turn * 100 + 1;
-  const assistantMessageId = turn * 100 + 2;
+  const agentMessageId = turn * 100 + 2;
 
   const packets = [
     {
       user_message_id: userMessageId,
-      reserved_assistant_message_id: assistantMessageId,
+      reserved_assistant_message_id: agentMessageId,
     },
     {
       placement: { turn_index: 0, tab_index: 0 },
       obj: {
         type: "message_start",
-        id: `mock-${assistantMessageId}`,
+        id: `mock-${agentMessageId}`,
         content: "Mock response for provider collision assertion.",
         final_documents: null,
       },
@@ -151,7 +151,7 @@ function buildMockStreamResponse(turn: number): string {
       obj: { type: "stop", stop_reason: "finished" },
     },
     {
-      message_id: assistantMessageId,
+      message_id: agentMessageId,
       citations: {},
       files: [],
     },
diff --git a/web/tests/e2e/chat/welcome_page.spec.ts b/web/tests/e2e/chat/welcome_page.spec.ts
index d0e44010901..16f7837ce14 100644
--- a/web/tests/e2e/chat/welcome_page.spec.ts
+++ b/web/tests/e2e/chat/welcome_page.spec.ts
@@ -66,7 +66,7 @@ for (const theme of THEMES) {
 
     // ── Content assertions ────────────────────────────────────────────
 
-    test("displays greeting from default assistant", async ({ page }) => {
+    test("displays greeting from default agent", async ({ page }) => {
       const greetingContainer = page.getByTestId("onyx-logo");
       await greetingContainer.waitFor({ state: "visible", timeout: 10000 });
 
diff --git a/web/tests/e2e/mcp/default-assistant-mcp.spec.ts b/web/tests/e2e/mcp/default-agent-mcp.spec.ts
similarity index 96%
rename from web/tests/e2e/mcp/default-assistant-mcp.spec.ts
rename to web/tests/e2e/mcp/default-agent-mcp.spec.ts
index 46728f4cb4b..f2eed126fa2 100644
--- a/web/tests/e2e/mcp/default-assistant-mcp.spec.ts
+++ b/web/tests/e2e/mcp/default-agent-mcp.spec.ts
@@ -84,7 +84,7 @@ async function fetchMcpToolIdByName(
   return matchedTool!.id;
 }
 
-test.describe("Default Assistant MCP Integration", () => {
+test.describe("Default Agent MCP Integration", () => {
   test.describe.configure({ mode: "serial" });
 
   let serverProcess: McpServerProcess | null = null;
@@ -170,7 +170,7 @@ test.describe("Default Assistant MCP Integration", () => {
     }
   });
 
-  test("Admin configures API key MCP server and adds tools to default assistant", async ({
+  test("Admin configures API key MCP server and adds tools to default agent", async ({
     page,
   }) => {
     await page.context().clearCookies();
@@ -319,7 +319,7 @@ test.describe("Default Assistant MCP Integration", () => {
     );
   });
 
-  test("Admin adds MCP tools to default assistant via chat preferences page", async ({
+  test("Admin adds MCP tools to default agent via chat preferences page", async ({
     page,
   }) => {
     test.skip(!serverId, "MCP server must be created first");
@@ -369,10 +369,10 @@ test.describe("Default Assistant MCP Integration", () => {
         timeout: 10000,
       });
     }
-    console.log(`[test] MCP tools successfully added to default assistant`);
+    console.log(`[test] MCP tools successfully added to default agent`);
   });
 
-  test("Basic user can see and toggle MCP tools in default assistant", async ({
+  test("Basic user can see and toggle MCP tools in default agent", async ({
     page,
   }) => {
     test.skip(!serverId, "MCP server must be configured first");
@@ -382,7 +382,7 @@ test.describe("Default Assistant MCP Integration", () => {
     await apiLogin(page, basicUserEmail, basicUserPassword);
     console.log(`[test] Logged in as basic user: ${basicUserEmail}`);
 
-    // Navigate to chat (which uses default assistant for new users)
+    // Navigate to chat (which uses default agent for new users)
     await page.goto("/app");
     await page.waitForURL("**/app**");
     await ensureOnboardingComplete(page);
@@ -499,8 +499,8 @@ test.describe("Default Assistant MCP Integration", () => {
     await page.getByLabel("AgentsPage/new-agent-button").click();
     await page.waitForURL("**/app/agents/create");
 
-    const assistantName = `MCP Assistant ${Date.now()}`;
-    await page.locator('input[name="name"]').fill(assistantName);
+    const agentName = `MCP Assistant ${Date.now()}`;
+    await page.locator('input[name="name"]').fill(agentName);
     await page
       .locator('textarea[name="description"]')
       .fill("Assistant with MCP actions attached.");
@@ -529,14 +529,14 @@ test.describe("Default Assistant MCP Integration", () => {
 
     await page.getByRole("button", { name: "Create" }).click();
 
-    await page.waitForURL(/.*\/app\?assistantId=\d+.*/);
-    const assistantIdMatch = page.url().match(/assistantId=(\d+)/);
-    expect(assistantIdMatch).toBeTruthy();
-    const assistantId = assistantIdMatch ? assistantIdMatch[1] : null;
-    expect(assistantId).not.toBeNull();
+    await page.waitForURL(/.*\/app\?agentId=\d+.*/);
+    const agentIdMatch = page.url().match(/agentId=(\d+)/);
+    expect(agentIdMatch).toBeTruthy();
+    const agentId = agentIdMatch ? agentIdMatch[1] : null;
+    expect(agentId).not.toBeNull();
 
     const client = new OnyxApiClient(page.request);
-    const assistant = await client.getAssistant(Number(assistantId));
+    const assistant = await client.getAssistant(Number(agentId));
     const hasMcpTool = assistant.tools.some(
       (tool) => tool.mcp_server_id === serverId
     );
@@ -629,7 +629,7 @@ test.describe("Default Assistant MCP Integration", () => {
     expect(disabledCounts.debug).toBe(0);
   });
 
-  test("Admin can modify MCP tools in default assistant", async ({ page }) => {
+  test("Admin can modify MCP tools in default agent", async ({ page }) => {
     test.skip(!serverId, "MCP server must be configured first");
 
     await page.context().clearCookies();
@@ -779,7 +779,7 @@ test.describe("Default Assistant MCP Integration", () => {
     await modalAfter.getByRole("button", { name: "Cancel" }).click();
   });
 
-  test("MCP tools appear in basic user's chat actions after being added to default assistant", async ({
+  test("MCP tools appear in basic user's chat actions after being added to default agent", async ({
     page,
   }) => {
     test.skip(!serverId, "MCP server must be configured first");
@@ -822,7 +822,7 @@ test.describe("Default Assistant MCP Integration", () => {
     expect(toolCount).toBeGreaterThan(0);
 
     console.log(
-      `[test] Basic user can see ${toolCount} MCP tools from default assistant`
+      `[test] Basic user can see ${toolCount} MCP tools from default agent`
     );
   });
 });
diff --git a/web/tests/e2e/mcp/mcp_oauth_flow.spec.ts b/web/tests/e2e/mcp/mcp_oauth_flow.spec.ts
index 127ec933d2e..ee9a0c16b50 100644
--- a/web/tests/e2e/mcp/mcp_oauth_flow.spec.ts
+++ b/web/tests/e2e/mcp/mcp_oauth_flow.spec.ts
@@ -62,8 +62,8 @@ type Credentials = {
 type FlowArtifacts = {
   serverId: number;
   serverName: string;
-  assistantId: number;
-  assistantName: string;
+  agentId: number;
+  agentName: string;
   toolName: string;
   toolId: number | null;
 };
@@ -615,9 +615,9 @@ async function completeOauthFlow(
     if (url.includes(returnSubstring)) {
       return true;
     }
-    // Re-auth flows can return to a chat session URL instead of assistantId URL.
+    // Re-auth flows can return to a chat session URL instead of agentId URL.
     if (
-      returnSubstring.includes("/app?assistantId=") &&
+      returnSubstring.includes("/app?agentId=") &&
       url.includes("/app?chatId=")
     ) {
       return true;
@@ -962,11 +962,11 @@ async function openActionsPopover(page: Page) {
   await ensureActionPopoverInPrimaryView(page);
 }
 
-async function restoreAssistantContext(page: Page, assistantId: number) {
-  const assistantPath = `/app?assistantId=${assistantId}`;
+async function restoreAssistantContext(page: Page, agentId: number) {
+  const assistantPath = `/app?agentId=${agentId}`;
   logOauthEvent(
     page,
-    `Restoring assistant context for assistantId=${assistantId} (current url=${page.url()})`
+    `Restoring assistant context for agentId=${agentId} (current url=${page.url()})`
   );
 
   // Clear chat-focused URL state first, then explicitly reselect assistant.
@@ -975,14 +975,12 @@ async function restoreAssistantContext(page: Page, assistantId: number) {
     .waitForLoadState("networkidle", { timeout: 10000 })
     .catch(() => {});
 
-  const assistantLink = page
-    .locator(`a[href*="assistantId=${assistantId}"]`)
-    .first();
+  const assistantLink = page.locator(`a[href*="agentId=${agentId}"]`).first();
   if ((await assistantLink.count()) > 0) {
     await clickAndWaitForPossibleUrlChange(
       page,
       () => assistantLink.click(),
-      `Restore assistant ${assistantId} from sidebar`
+      `Restore assistant ${agentId} from sidebar`
     );
   } else {
     await page.goto(`${APP_BASE_URL}${assistantPath}`, {
@@ -1343,7 +1341,7 @@ async function ensureServerVisibleInActions(
   page: Page,
   serverName: string,
   options?: {
-    assistantId?: number;
+    agentId?: number;
   }
 ) {
   for (let attempt = 0; attempt < 2; attempt++) {
@@ -1366,12 +1364,12 @@ async function ensureServerVisibleInActions(
     );
     await page.keyboard.press("Escape").catch(() => {});
 
-    if (attempt === 0 && options?.assistantId) {
+    if (attempt === 0 && options?.agentId) {
       logOauthEvent(
         page,
-        `Server ${serverName} missing in actions, retrying after restoring assistant ${options.assistantId} context`
+        `Server ${serverName} missing in actions, retrying after restoring assistant ${options.agentId} context`
       );
-      await restoreAssistantContext(page, options.assistantId);
+      await restoreAssistantContext(page, options.agentId);
       continue;
     }
 
@@ -1397,12 +1395,12 @@ async function waitForUserRecord(
 
 async function waitForAssistantByName(
   client: OnyxApiClient,
-  assistantName: string,
+  agentName: string,
   timeoutMs: number = 20_000
 ) {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const assistant = await client.findAssistantByName(assistantName, {
+    const assistant = await client.findAgentByName(agentName, {
       getEditable: true,
     });
     if (assistant) {
@@ -1410,18 +1408,18 @@ async function waitForAssistantByName(
     }
     await new Promise((resolve) => setTimeout(resolve, 500));
   }
-  throw new Error(`Timed out waiting for assistant ${assistantName}`);
+  throw new Error(`Timed out waiting for assistant ${agentName}`);
 }
 
 async function waitForAssistantTools(
   client: OnyxApiClient,
-  assistantName: string,
+  agentName: string,
   requiredToolNames: string[],
   timeoutMs: number = 30_000
 ) {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const assistant = await client.findAssistantByName(assistantName, {
+    const assistant = await client.findAgentByName(agentName, {
       getEditable: true,
     });
     if (
@@ -1441,7 +1439,7 @@ async function waitForAssistantTools(
     await new Promise((resolve) => setTimeout(resolve, 500));
   }
   throw new Error(
-    `Timed out waiting for assistant ${assistantName} to include tools: ${requiredToolNames.join(
+    `Timed out waiting for assistant ${agentName} to include tools: ${requiredToolNames.join(
       ", "
     )}`
   );
@@ -1614,11 +1612,11 @@ async function openAssistantEditor(
   options.logStep("Assistant editor loaded");
 }
 
-async function createAssistantAndWaitForTool(
+async function createAgentAndWaitForTool(
   page: Page,
   options: {
     apiClient: OnyxApiClient;
-    assistantName: string;
+    agentName: string;
     instructions: string;
     description: string;
     serverId: number;
@@ -1628,7 +1626,7 @@ async function createAssistantAndWaitForTool(
 ): Promise<number> {
   const {
     apiClient,
-    assistantName,
+    agentName,
     instructions,
     description,
     serverId,
@@ -1636,7 +1634,7 @@ async function createAssistantAndWaitForTool(
     logStep,
   } = options;
 
-  await page.locator('input[name="name"]').fill(assistantName);
+  await page.locator('input[name="name"]').fill(agentName);
   await page.locator('textarea[name="instructions"]').fill(instructions);
   await page.locator('textarea[name="description"]').fill(description);
   await selectMcpTools(page, serverId);
@@ -1645,32 +1643,26 @@ async function createAssistantAndWaitForTool(
   await page.waitForURL(
     (url) => {
       const href = typeof url === "string" ? url : url.toString();
-      return (
-        /\/app\?assistantId=\d+/.test(href) ||
-        href.includes("/admin/assistants")
-      );
+      return /\/app\?agentId=\d+/.test(href) || href.includes("/admin/agents");
     },
     { timeout: 20000 }
   );
 
-  let assistantId = getNumericQueryParam(page.url(), "assistantId");
-  if (assistantId === null) {
-    const assistantRecord = await waitForAssistantByName(
-      apiClient,
-      assistantName
-    );
-    assistantId = assistantRecord.id;
-    await page.goto(`/app?assistantId=${assistantId}`);
-    await page.waitForURL(/\/app\?assistantId=\d+/, { timeout: 20000 });
+  let agentId = getNumericQueryParam(page.url(), "agentId");
+  if (agentId === null) {
+    const assistantRecord = await waitForAssistantByName(apiClient, agentName);
+    agentId = assistantRecord.id;
+    await page.goto(`/app?agentId=${agentId}`);
+    await page.waitForURL(/\/app\?agentId=\d+/, { timeout: 20000 });
   }
-  if (assistantId === null) {
+  if (agentId === null) {
     throw new Error("Assistant ID could not be determined");
   }
-  logStep(`Assistant created with id ${assistantId}`);
+  logStep(`Assistant created with id ${agentId}`);
 
-  await waitForAssistantTools(apiClient, assistantName, [toolName]);
+  await waitForAssistantTools(apiClient, agentName, [toolName]);
   logStep("Confirmed assistant tools are available");
-  return assistantId;
+  return agentId;
 }
 
 test.describe("MCP OAuth flows", () => {
@@ -1787,15 +1779,15 @@ test.describe("MCP OAuth flows", () => {
     const adminPage = await adminContext.newPage();
     const adminClient = new OnyxApiClient(adminPage.request);
 
-    if (adminArtifacts?.assistantId) {
-      await adminClient.deleteAssistant(adminArtifacts.assistantId);
+    if (adminArtifacts?.agentId) {
+      await adminClient.deleteAgent(adminArtifacts.agentId);
     }
     if (adminArtifacts?.serverId) {
       await adminClient.deleteMcpServer(adminArtifacts.serverId);
     }
 
-    if (curatorArtifacts?.assistantId) {
-      await adminClient.deleteAssistant(curatorArtifacts.assistantId);
+    if (curatorArtifacts?.agentId) {
+      await adminClient.deleteAgent(curatorArtifacts.agentId);
     }
     if (curatorArtifacts?.serverId) {
       await adminClient.deleteMcpServer(curatorArtifacts.serverId);
@@ -1836,7 +1828,7 @@ test.describe("MCP OAuth flows", () => {
     logStep("Logged in as admin");
 
     const serverName = `PW MCP Admin ${Date.now()}`;
-    const assistantName = `PW Admin Assistant ${Date.now()}`;
+    const agentName = `PW Admin Assistant ${Date.now()}`;
 
     const serverId = await configureOauthServerAndEnableTool(page, {
       serverName,
@@ -1859,9 +1851,9 @@ test.describe("MCP OAuth flows", () => {
       },
     });
 
-    const assistantId = await createAssistantAndWaitForTool(page, {
+    const agentId = await createAgentAndWaitForTool(page, {
       apiClient: adminApiClient,
-      assistantName,
+      agentName,
       instructions: "Assist with MCP OAuth testing.",
       description: "Playwright admin MCP assistant.",
       serverId,
@@ -1874,7 +1866,7 @@ test.describe("MCP OAuth flows", () => {
       TOOL_NAMES.admin
     );
 
-    await ensureServerVisibleInActions(page, serverName, { assistantId });
+    await ensureServerVisibleInActions(page, serverName, { agentId });
     await verifyMcpToolRowVisible(page, serverName, TOOL_NAMES.admin);
     await ensureMcpToolEnabledInActions(page, serverName, TOOL_NAMES.admin);
     logStep("Verified admin MCP tool row visible before reauth");
@@ -1886,12 +1878,8 @@ test.describe("MCP OAuth flows", () => {
     );
     logStep("Verified admin MCP tool invocation before reauth");
 
-    await reauthenticateFromChat(
-      page,
-      serverName,
-      `/app?assistantId=${assistantId}`
-    );
-    await ensureServerVisibleInActions(page, serverName, { assistantId });
+    await reauthenticateFromChat(page, serverName, `/app?agentId=${agentId}`);
+    await ensureServerVisibleInActions(page, serverName, { agentId });
     await verifyMcpToolRowVisible(page, serverName, TOOL_NAMES.admin);
     await ensureMcpToolEnabledInActions(page, serverName, TOOL_NAMES.admin);
     logStep("Verified admin MCP tool row visible after reauth");
@@ -1914,8 +1902,8 @@ test.describe("MCP OAuth flows", () => {
     adminArtifacts = {
       serverId,
       serverName,
-      assistantId,
-      assistantName,
+      agentId,
+      agentName,
       toolName: TOOL_NAMES.admin,
       toolId: adminToolId,
     };
@@ -1954,7 +1942,7 @@ test.describe("MCP OAuth flows", () => {
     const curatorApiClient = new OnyxApiClient(page.request);
 
     const serverName = `PW MCP Curator ${Date.now()}`;
-    const assistantName = `PW Curator Assistant ${Date.now()}`;
+    const agentName = `PW Curator Assistant ${Date.now()}`;
 
     let curatorServerProcess: McpServerProcess | null = null;
     let curatorRuntimeMcpServerUrl = runtimeMcpServerUrl;
@@ -1980,9 +1968,9 @@ test.describe("MCP OAuth flows", () => {
 
       await openAssistantEditor(page, { logStep });
 
-      const assistantId = await createAssistantAndWaitForTool(page, {
+      const agentId = await createAgentAndWaitForTool(page, {
         apiClient: curatorApiClient,
-        assistantName,
+        agentName,
         instructions: "Curator MCP OAuth assistant.",
         description: "Playwright curator MCP assistant.",
         serverId,
@@ -1990,24 +1978,20 @@ test.describe("MCP OAuth flows", () => {
         logStep,
       });
 
-      await ensureServerVisibleInActions(page, serverName, { assistantId });
+      await ensureServerVisibleInActions(page, serverName, { agentId });
       await verifyMcpToolRowVisible(page, serverName, TOOL_NAMES.curator);
       logStep("Verified curator MCP tool row visible before reauth");
 
-      await reauthenticateFromChat(
-        page,
-        serverName,
-        `/app?assistantId=${assistantId}`
-      );
-      await ensureServerVisibleInActions(page, serverName, { assistantId });
+      await reauthenticateFromChat(page, serverName, `/app?agentId=${agentId}`);
+      await ensureServerVisibleInActions(page, serverName, { agentId });
       await verifyMcpToolRowVisible(page, serverName, TOOL_NAMES.curator);
       logStep("Verified curator MCP tool row visible after reauth");
 
       curatorArtifacts = {
         serverId,
         serverName,
-        assistantId,
-        assistantName,
+        agentId,
+        agentName,
         toolName: TOOL_NAMES.curator,
         toolId: null,
       };
@@ -2064,14 +2048,14 @@ test.describe("MCP OAuth flows", () => {
     await loginAsWorkerUser(page, testInfo.workerIndex);
     logStep("Logged in as worker user");
 
-    const assistantId = adminArtifacts!.assistantId;
+    const agentId = adminArtifacts!.agentId;
     const serverName = adminArtifacts!.serverName;
     const toolName = adminArtifacts!.toolName;
 
-    await page.goto(`/app?assistantId=${assistantId}`, {
+    await page.goto(`/app?agentId=${agentId}`, {
       waitUntil: "load",
     });
-    await ensureServerVisibleInActions(page, serverName, { assistantId });
+    await ensureServerVisibleInActions(page, serverName, { agentId });
     logStep("Opened chat as user and ensured server visible");
 
     await openActionsPopover(page);
@@ -2111,11 +2095,11 @@ test.describe("MCP OAuth flows", () => {
     }
 
     await completeOauthFlow(page, {
-      expectReturnPathContains: `/app?assistantId=${assistantId}`,
+      expectReturnPathContains: `/app?agentId=${agentId}`,
     });
     logStep("Completed user OAuth reauthentication");
 
-    await ensureServerVisibleInActions(page, serverName, { assistantId });
+    await ensureServerVisibleInActions(page, serverName, { agentId });
     await verifyMcpToolRowVisible(page, serverName, toolName);
     await ensureMcpToolEnabledInActions(page, serverName, toolName);
     logStep("Verified user MCP tool row visible after reauth");
diff --git a/web/tests/e2e/utils/assistantUtils.ts b/web/tests/e2e/utils/agentUtils.ts
similarity index 91%
rename from web/tests/e2e/utils/assistantUtils.ts
rename to web/tests/e2e/utils/agentUtils.ts
index dcdf2ca8040..a23ac4c8ed8 100644
--- a/web/tests/e2e/utils/assistantUtils.ts
+++ b/web/tests/e2e/utils/agentUtils.ts
@@ -1,15 +1,15 @@
 import { Page } from "@playwright/test";
 import { expect } from "@playwright/test";
-import { verifyAssistantIsChosen } from "./chatActions";
+import { verifyAgentIsChosen } from "./chatActions";
 
-export type AssistantParams = {
+export type AgentParams = {
   name: string;
   description?: string;
   instructions?: string; // system_prompt
 };
 
 // Create an assistant via the UI from the app page and wait until it is active
-export async function createAssistant(page: Page, params: AssistantParams) {
+export async function createAgent(page: Page, params: AgentParams) {
   const { name, description = "", instructions = "Test Instructions" } = params;
 
   // Navigate to creation flow
@@ -33,18 +33,18 @@ export async function createAssistant(page: Page, params: AssistantParams) {
   await page.getByRole("button", { name: "Create" }).click();
 
   // Verify it is selected in chat (placeholder contains assistant name)
-  await verifyAssistantIsChosen(page, name);
+  await verifyAgentIsChosen(page, name);
 }
 
 // Pin an assistant by its visible name in the sidebar list.
 // If already pinned, this will leave it pinned (no-op).
-export async function pinAssistantByName(
+export async function pinAgentByName(
   page: Page,
-  assistantName: string
+  agentName: string
 ): Promise<void> {
   const row = page
     .locator('[data-testid^="assistant-["]')
-    .filter({ hasText: assistantName })
+    .filter({ hasText: agentName })
     .first();
 
   await row.waitFor({ state: "visible", timeout: 10000 });
@@ -70,7 +70,7 @@ export async function pinAssistantByName(
 }
 
 /**
- * Ensures the Image Generation tool is enabled in the default assistant configuration.
+ * Ensures the Image Generation tool is enabled in the default agent configuration.
  * If it's not enabled, it will toggle it on.
  *
  * Navigates to the Chat Preferences page and toggles the Image Generation switch
diff --git a/web/tests/e2e/utils/chatActions.ts b/web/tests/e2e/utils/chatActions.ts
index 62d81a009ce..3f96ec3c875 100644
--- a/web/tests/e2e/utils/chatActions.ts
+++ b/web/tests/e2e/utils/chatActions.ts
@@ -1,30 +1,30 @@
 import { Page } from "@playwright/test";
 import { expect } from "@playwright/test";
 
-export async function verifyDefaultAssistantIsChosen(page: Page) {
+export async function verifyDefaultAgentIsChosen(page: Page) {
   await expect(page.getByTestId("onyx-logo")).toBeVisible({ timeout: 5000 });
 }
 
-export async function verifyAssistantIsChosen(
+export async function verifyAgentIsChosen(
   page: Page,
-  assistantName: string,
+  agentName: string,
   timeout: number = 5000
 ) {
   await expect(
-    page.getByTestId("assistant-name-display").getByText(assistantName)
+    page.getByTestId("agent-name-display").getByText(agentName)
   ).toBeVisible({ timeout });
 }
 
-export async function navigateToAssistantInHistorySidebar(
+export async function navigateToAgentInHistorySidebar(
   page: Page,
   testId: string,
-  assistantName: string
+  agentName: string
 ) {
   await page.getByTestId(`assistant-${testId}`).click();
   try {
-    await verifyAssistantIsChosen(page, assistantName);
+    await verifyAgentIsChosen(page, agentName);
   } catch (error) {
-    console.error("Error in navigateToAssistantInHistorySidebar:", error);
+    console.error("Error in navigateToAgentInHistorySidebar:", error);
     const pageText = await page.textContent("body");
     console.log("Page text:", pageText);
     throw error;
diff --git a/web/tests/e2e/utils/onyxApiClient.ts b/web/tests/e2e/utils/onyxApiClient.ts
index bb15f7f368e..6b6f1a67a80 100644
--- a/web/tests/e2e/utils/onyxApiClient.ts
+++ b/web/tests/e2e/utils/onyxApiClient.ts
@@ -640,28 +640,28 @@ export class OnyxApiClient {
     return tools.find((tool) => tool.name === name) ?? null;
   }
 
-  async deleteAssistant(assistantId: number): Promise<boolean> {
+  async deleteAgent(agentId: number): Promise<boolean> {
     const response = await this.request.delete(
-      `${this.baseUrl}/persona/${assistantId}`
+      `${this.baseUrl}/persona/${agentId}`
     );
     const success = await this.handleResponseSoft(
       response,
-      `Failed to delete assistant ${assistantId}`
+      `Failed to delete assistant ${agentId}`
     );
     if (success) {
-      this.log(`Deleted assistant ${assistantId}`);
+      this.log(`Deleted assistant ${agentId}`);
     }
     return success;
   }
 
-  async getAssistant(assistantId: number): Promise<{
+  async getAssistant(agentId: number): Promise<{
     id: number;
     tools: Array<{ id: number; mcp_server_id?: number | null }>;
   }> {
-    const response = await this.get(`/persona/${assistantId}`);
+    const response = await this.get(`/persona/${agentId}`);
     return await this.handleResponse(
       response,
-      `Failed to fetch assistant ${assistantId}`
+      `Failed to fetch assistant ${agentId}`
     );
   }
 
@@ -674,7 +674,7 @@ export class OnyxApiClient {
     return data.mcp_servers;
   }
 
-  async listAssistants(options?: {
+  async listAgents(options?: {
     includeDeleted?: boolean;
     getEditable?: boolean;
   }): Promise<any[]> {
@@ -695,11 +695,11 @@ export class OnyxApiClient {
     );
   }
 
-  async findAssistantByName(
+  async findAgentByName(
     name: string,
     options?: { includeDeleted?: boolean; getEditable?: boolean }
   ): Promise<any | null> {
-    const assistants = await this.listAssistants(options);
+    const assistants = await this.listAgents(options);
     return assistants.find((assistant) => assistant.name === name) ?? null;
   }
 
diff --git a/web/tests/setup/mocks/components/UserProvider.tsx b/web/tests/setup/mocks/components/UserProvider.tsx
index 079fd2ec9be..ccf8d652cb8 100644
--- a/web/tests/setup/mocks/components/UserProvider.tsx
+++ b/web/tests/setup/mocks/components/UserProvider.tsx
@@ -25,9 +25,9 @@ interface UserContextType {
   isCloudSuperuser: boolean;
   updateUserAutoScroll: (autoScroll: boolean) => Promise<void>;
   updateUserShortcuts: (enabled: boolean) => Promise<void>;
-  toggleAssistantPinnedStatus: (
-    currentPinnedAssistantIDs: number[],
-    assistantId: number,
+  toggleAgentPinnedStatus: (
+    currentPinnedAgentIDs: number[],
+    agentId: number,
     isPinned: boolean
   ) => Promise<boolean>;
   updateUserTemperatureOverrideEnabled: (enabled: boolean) => Promise<void>;
@@ -42,7 +42,7 @@ const mockUserContext: UserContextType = {
   isCloudSuperuser: false,
   updateUserAutoScroll: async () => {},
   updateUserShortcuts: async () => {},
-  toggleAssistantPinnedStatus: async () => true,
+  toggleAgentPinnedStatus: async () => true,
   updateUserTemperatureOverrideEnabled: async () => {},
   updateUserPersonalization: async () => {},
 };

From a9769757fe107abed9c42be3df83e5a20bdb4860 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:20:03 -0800
Subject: [PATCH 011/267] fix(llm): enforce persona restrictions on public LLM
 providers (#8846)

Co-authored-by: Dane <dane@onyx.app>
---
 backend/onyx/db/llm.py                        |  55 ++++-----
 backend/onyx/server/manage/llm/api.py         |  12 +-
 .../test_llm_provider_access_control.py       | 110 ++++++++++++++++++
 web/src/lib/hooks.ts                          |   6 +-
 4 files changed, 144 insertions(+), 39 deletions(-)

diff --git a/backend/onyx/db/llm.py b/backend/onyx/db/llm.py
index 4ee1e88251e..3b6e239f40a 100644
--- a/backend/onyx/db/llm.py
+++ b/backend/onyx/db/llm.py
@@ -109,45 +109,38 @@ def can_user_access_llm_provider(
         is_admin: If True, bypass user group restrictions but still respect persona restrictions
 
     Access logic:
-    1. If is_public=True → everyone has access (public override)
-    2. If is_public=False:
-       - Both groups AND personas set → must satisfy BOTH (AND logic, admins bypass group check)
-       - Only groups set → must be in one of the groups (OR across groups, admins bypass)
-       - Only personas set → must use one of the personas (OR across personas, applies to admins)
-       - Neither set → NOBODY has access unless admin (locked, admin-only)
+    - is_public controls USER access (group bypass): when True, all users can access
+      regardless of group membership. When False, user must be in a whitelisted group
+      (or be admin).
+    - Persona restrictions are ALWAYS enforced when set, regardless of is_public.
+      This allows admins to make a provider available to all users while still
+      restricting which personas (assistants) can use it.
+
+    Decision matrix:
+    1. is_public=True, no personas set → everyone has access
+    2. is_public=True, personas set → all users, but only whitelisted personas
+    3. is_public=False, groups+personas set → must satisfy BOTH (admins bypass groups)
+    4. is_public=False, only groups set → must be in group (admins bypass)
+    5. is_public=False, only personas set → must use whitelisted persona
+    6. is_public=False, neither set → admin-only (locked)
     """
-    # Public override - everyone has access
-    if provider.is_public:
-        return True
-
-    # Extract IDs once to avoid multiple iterations
-    provider_group_ids = (
-        {group.id for group in provider.groups} if provider.groups else set()
-    )
-    provider_persona_ids = (
-        {p.id for p in provider.personas} if provider.personas else set()
-    )
-
+    provider_group_ids = {g.id for g in (provider.groups or [])}
+    provider_persona_ids = {p.id for p in (provider.personas or [])}
     has_groups = bool(provider_group_ids)
     has_personas = bool(provider_persona_ids)
 
-    # Both groups AND personas set → AND logic (must satisfy both)
-    if has_groups and has_personas:
-        # Admins bypass group check but still must satisfy persona restrictions
-        user_in_group = is_admin or bool(user_group_ids & provider_group_ids)
-        persona_allowed = persona.id in provider_persona_ids if persona else False
-        return user_in_group and persona_allowed
+    # Persona restrictions are always enforced when set, regardless of is_public
+    if has_personas and not (persona and persona.id in provider_persona_ids):
+        return False
+
+    if provider.is_public:
+        return True
 
-    # Only groups set → user must be in one of the groups (admins bypass)
     if has_groups:
         return is_admin or bool(user_group_ids & provider_group_ids)
 
-    # Only personas set → persona must be in allowed list (applies to admins too)
-    if has_personas:
-        return persona.id in provider_persona_ids if persona else False
-
-    # Neither groups nor personas set, and not public → admins can access
-    return is_admin
+    # No groups: either persona-whitelisted (already passed) or admin-only if locked
+    return has_personas or is_admin
 
 
 def validate_persona_ids_exist(
diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index 0fe5bad013f..9503a828bf8 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -603,9 +603,9 @@ def list_llm_provider_basics(
     for provider in all_providers:
         # Use centralized access control logic with persona=None since we're
         # listing providers without a specific persona context. This correctly:
-        # - Includes all public providers
+        # - Includes public providers WITHOUT persona restrictions
         # - Includes providers user can access via group membership
-        # - Excludes persona-only restricted providers (requires specific persona)
+        # - Excludes providers with persona restrictions (requires specific persona)
         # - Excludes non-public providers with no restrictions (admin-only)
         if can_user_access_llm_provider(
             provider, user_group_ids, persona=None, is_admin=is_admin
@@ -638,7 +638,7 @@ def get_valid_model_names_for_persona(
 
     Returns a list of model names (e.g., ["gpt-4o", "claude-3-5-sonnet"]) that are
     available to the user when using this persona, respecting all RBAC restrictions.
-    Public providers are always included.
+    Public providers are included unless they have persona restrictions that exclude this persona.
     """
     persona = fetch_persona_with_groups(db_session, persona_id)
     if not persona:
@@ -652,7 +652,7 @@ def get_valid_model_names_for_persona(
 
     valid_models = []
     for llm_provider_model in all_providers:
-        # Public providers always included, restricted checked via RBAC
+        # Check access with persona context — respects all RBAC restrictions
         if can_user_access_llm_provider(
             llm_provider_model, user_group_ids, persona, is_admin=is_admin
         ):
@@ -673,7 +673,7 @@ def list_llm_providers_for_persona(
     """Get LLM providers for a specific persona.
 
     Returns providers that the user can access when using this persona:
-    - All public providers (is_public=True) - ALWAYS included
+    - Public providers (respecting persona restrictions if set)
     - Restricted providers user can access via group/persona restrictions
 
     This endpoint is used for background fetching of restricted providers
@@ -702,7 +702,7 @@ def list_llm_providers_for_persona(
     llm_provider_list: list[LLMProviderDescriptor] = []
 
     for llm_provider_model in all_providers:
-        # Use simplified access check - public providers always included
+        # Check access with persona context — respects persona restrictions
         if can_user_access_llm_provider(
             llm_provider_model, user_group_ids, persona, is_admin=is_admin
         ):
diff --git a/backend/tests/integration/tests/llm_provider/test_llm_provider_access_control.py b/backend/tests/integration/tests/llm_provider/test_llm_provider_access_control.py
index b1ce4bf34e9..f66e19fef24 100644
--- a/backend/tests/integration/tests/llm_provider/test_llm_provider_access_control.py
+++ b/backend/tests/integration/tests/llm_provider/test_llm_provider_access_control.py
@@ -243,6 +243,116 @@ def test_can_user_access_llm_provider_or_logic(
         )
 
 
+def test_public_provider_with_persona_restrictions(
+    users: tuple[DATestUser, DATestUser],
+) -> None:
+    """Public providers should still enforce persona restrictions.
+
+    Regression test for the bug where is_public=True caused
+    can_user_access_llm_provider() to return True immediately,
+    bypassing persona whitelist checks entirely.
+    """
+    admin_user, _basic_user = users
+
+    with get_session_with_current_tenant() as db_session:
+        # Public provider with persona restrictions
+        public_restricted = _create_llm_provider(
+            db_session,
+            name="public-persona-restricted",
+            default_model_name="gpt-4o",
+            is_public=True,
+            is_default=True,
+        )
+
+        whitelisted_persona = _create_persona(
+            db_session,
+            name="whitelisted-persona",
+            provider_name=public_restricted.name,
+        )
+        non_whitelisted_persona = _create_persona(
+            db_session,
+            name="non-whitelisted-persona",
+            provider_name=public_restricted.name,
+        )
+
+        # Only whitelist one persona
+        db_session.add(
+            LLMProvider__Persona(
+                llm_provider_id=public_restricted.id,
+                persona_id=whitelisted_persona.id,
+            )
+        )
+        db_session.flush()
+        db_session.refresh(public_restricted)
+
+        admin_model = db_session.get(User, admin_user.id)
+        assert admin_model is not None
+        admin_group_ids = fetch_user_group_ids(db_session, admin_model)
+
+        # Whitelisted persona — should be allowed
+        assert can_user_access_llm_provider(
+            public_restricted,
+            admin_group_ids,
+            whitelisted_persona,
+        )
+
+        # Non-whitelisted persona — should be denied despite is_public=True
+        assert not can_user_access_llm_provider(
+            public_restricted,
+            admin_group_ids,
+            non_whitelisted_persona,
+        )
+
+        # No persona context (e.g. global provider list) — should be denied
+        # because provider has persona restrictions set
+        assert not can_user_access_llm_provider(
+            public_restricted,
+            admin_group_ids,
+            persona=None,
+        )
+
+
+def test_public_provider_without_persona_restrictions(
+    users: tuple[DATestUser, DATestUser],
+) -> None:
+    """Public providers with no persona restrictions remain accessible to all."""
+    admin_user, basic_user = users
+
+    with get_session_with_current_tenant() as db_session:
+        public_unrestricted = _create_llm_provider(
+            db_session,
+            name="public-unrestricted",
+            default_model_name="gpt-4o",
+            is_public=True,
+            is_default=True,
+        )
+
+        any_persona = _create_persona(
+            db_session,
+            name="any-persona",
+            provider_name=public_unrestricted.name,
+        )
+
+        admin_model = db_session.get(User, admin_user.id)
+        basic_model = db_session.get(User, basic_user.id)
+        assert admin_model is not None
+        assert basic_model is not None
+
+        admin_group_ids = fetch_user_group_ids(db_session, admin_model)
+        basic_group_ids = fetch_user_group_ids(db_session, basic_model)
+
+        # Any user, any persona — all allowed
+        assert can_user_access_llm_provider(
+            public_unrestricted, admin_group_ids, any_persona
+        )
+        assert can_user_access_llm_provider(
+            public_unrestricted, basic_group_ids, any_persona
+        )
+        assert can_user_access_llm_provider(
+            public_unrestricted, admin_group_ids, persona=None
+        )
+
+
 def test_get_llm_for_persona_falls_back_when_access_denied(
     users: tuple[DATestUser, DATestUser],
 ) -> None:
diff --git a/web/src/lib/hooks.ts b/web/src/lib/hooks.ts
index f7b291f385f..93e67799b72 100644
--- a/web/src/lib/hooks.ts
+++ b/web/src/lib/hooks.ts
@@ -842,8 +842,10 @@ export function useLlmManager(
     }
   };
 
-  // Track if any provider exists (for onboarding checks)
-  const hasAnyProvider = (allUserProviders?.length ?? 0) > 0;
+  // Track if any provider exists for the current persona context.
+  // Uses the persona-aware list so chat input reflects actual access,
+  // falling back to the global list when no persona is selected.
+  const hasAnyProvider = (llmProviders?.length ?? 0) > 0;
 
   return {
     updateModelOverrideBasedOnChatSession,

From 0c35dfc0e47f5c457c18d27d505e6e90b7783b9c Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 10:59:02 -0800
Subject: [PATCH 012/267] fix(search): re-sync search/chat preference on user
 data load (#8868)

---
 web/src/ee/providers/AppModeProvider.tsx    | 18 ++++++++----
 web/src/layouts/app-layouts.tsx             |  1 +
 web/src/refresh-pages/AppPage.tsx           |  9 +++---
 web/tests/e2e/chat/default_app_mode.spec.ts | 31 +++++++++++++++++++++
 web/tests/e2e/utils/onyxApiClient.ts        | 19 +++++++++++++
 5 files changed, 68 insertions(+), 10 deletions(-)
 create mode 100644 web/tests/e2e/chat/default_app_mode.spec.ts

diff --git a/web/src/ee/providers/AppModeProvider.tsx b/web/src/ee/providers/AppModeProvider.tsx
index d637ca9ed52..2e9468c7be1 100644
--- a/web/src/ee/providers/AppModeProvider.tsx
+++ b/web/src/ee/providers/AppModeProvider.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import React, { useState, useCallback } from "react";
+import React, { useState, useCallback, useEffect } from "react";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import { AppModeContext, AppMode } from "@/providers/AppModeProvider";
 import { useUser } from "@/providers/UserProvider";
@@ -27,12 +27,18 @@ export function AppModeProvider({ children }: AppModeProviderProps) {
   const { isSearchModeAvailable } = settings;
 
   const persistedMode = user?.preferences?.default_app_mode;
-  const initialMode: AppMode =
-    isPaidEnterpriseFeaturesEnabled && isSearchModeAvailable && persistedMode
-      ? (persistedMode.toLowerCase() as AppMode)
-      : "chat";
+  const [appMode, setAppModeState] = useState<AppMode>("chat");
 
-  const [appMode, setAppModeState] = useState<AppMode>(initialMode);
+  useEffect(() => {
+    if (!isPaidEnterpriseFeaturesEnabled || !isSearchModeAvailable) {
+      setAppModeState("chat");
+      return;
+    }
+
+    if (persistedMode) {
+      setAppModeState(persistedMode.toLowerCase() as AppMode);
+    }
+  }, [isPaidEnterpriseFeaturesEnabled, isSearchModeAvailable, persistedMode]);
 
   const setAppMode = useCallback(
     (mode: AppMode) => {
diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index bc036c785a8..61264e34a5c 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -327,6 +327,7 @@ function Header() {
               <Popover open={modePopoverOpen} onOpenChange={setModePopoverOpen}>
                 <Popover.Trigger asChild>
                   <OpenButton
+                    aria-label="Change app mode"
                     icon={
                       effectiveMode === "search" ? SvgSearchMenu : SvgBubbleText
                     }
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 0813bc7a050..cca29af3c39 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -480,13 +480,14 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     (user?.preferences?.default_app_mode?.toLowerCase() as "chat" | "search") ??
     "chat";
 
+  const isNewSession = appFocus.isNewSession();
+
   // 1. Reset the app-mode back to the user's default when navigating back to the "New Sessions" tab.
   // 2. If we're navigating away from the "New Session" tab after performing a search, we reset the app-input-bar.
   useEffect(() => {
-    if (appFocus.isNewSession()) setAppMode(defaultAppMode);
-    if (!appFocus.isNewSession() && classification === "search")
-      resetInputBar();
-  }, [appFocus.isNewSession()]);
+    if (isNewSession) setAppMode(defaultAppMode);
+    if (!isNewSession && classification === "search") resetInputBar();
+  }, [isNewSession, defaultAppMode, classification, resetInputBar, setAppMode]);
 
   const handleSearchDocumentClick = useCallback(
     (doc: MinimalOnyxDocument) => setPresentingDocument(doc),
diff --git a/web/tests/e2e/chat/default_app_mode.spec.ts b/web/tests/e2e/chat/default_app_mode.spec.ts
new file mode 100644
index 00000000000..5a3fd670e43
--- /dev/null
+++ b/web/tests/e2e/chat/default_app_mode.spec.ts
@@ -0,0 +1,31 @@
+import { test, expect } from "@playwright/test";
+import { loginAs } from "@tests/e2e/utils/auth";
+import { OnyxApiClient } from "@tests/e2e/utils/onyxApiClient";
+
+test.describe("Default App Mode", () => {
+  test("loads persisted Search mode after refresh", async ({ page }) => {
+    await page.context().clearCookies();
+    await loginAs(page, "admin");
+
+    // Arrange
+    const apiClient = new OnyxApiClient(page.request);
+    const ccPairId = await apiClient.createFileConnector(
+      "Default App Mode Test Connector"
+    );
+    await apiClient.setDefaultAppMode("SEARCH");
+
+    try {
+      // Act
+      await page.goto("/app");
+      await page.waitForLoadState("networkidle");
+
+      // Assert
+      const appModeButton = page.getByLabel("Change app mode");
+      await appModeButton.waitFor({ state: "visible", timeout: 10000 });
+      await expect(appModeButton).toHaveText(/Search/);
+    } finally {
+      await apiClient.setDefaultAppMode("CHAT");
+      await apiClient.deleteCCPair(ccPairId);
+    }
+  });
+});
diff --git a/web/tests/e2e/utils/onyxApiClient.ts b/web/tests/e2e/utils/onyxApiClient.ts
index 6b6f1a67a80..63b336b7368 100644
--- a/web/tests/e2e/utils/onyxApiClient.ts
+++ b/web/tests/e2e/utils/onyxApiClient.ts
@@ -1124,4 +1124,23 @@ export class OnyxApiClient {
     );
     this.log(`Deleted project: ${projectId}`);
   }
+
+  /**
+   * Sets the current user's default app mode preference.
+   *
+   * @param mode - The default mode to persist ("CHAT" or "SEARCH")
+   */
+  async setDefaultAppMode(mode: "CHAT" | "SEARCH"): Promise<void> {
+    const response = await this.request.patch(
+      `${this.baseUrl}/user/default-app-mode`,
+      {
+        data: { default_app_mode: mode },
+      }
+    );
+    await this.handleResponse(
+      response,
+      `Failed to set default app mode to ${mode}`
+    );
+    this.log(`Set default app mode: ${mode}`);
+  }
 }

From 31aef36f78992ffd7f30b68616e032aa65fc6990 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Mon, 2 Mar 2026 11:28:43 -0800
Subject: [PATCH 013/267] chore(llm): Use AWS Secrrets Manager (#8913)

---
 .../workflows/nightly-llm-provider-chat.yml   |  13 +-
 .../reusable-nightly-llm-provider-chat.yml    | 133 ++++++++++++------
 2 files changed, 93 insertions(+), 53 deletions(-)

diff --git a/.github/workflows/nightly-llm-provider-chat.yml b/.github/workflows/nightly-llm-provider-chat.yml
index a6fbdea6569..ff5914eb8e8 100644
--- a/.github/workflows/nightly-llm-provider-chat.yml
+++ b/.github/workflows/nightly-llm-provider-chat.yml
@@ -15,6 +15,9 @@ permissions:
 jobs:
   provider-chat-test:
     uses: ./.github/workflows/reusable-nightly-llm-provider-chat.yml
+    permissions:
+      contents: read
+      id-token: write
     with:
       openai_models: ${{ vars.NIGHTLY_LLM_OPENAI_MODELS }}
       anthropic_models: ${{ vars.NIGHTLY_LLM_ANTHROPIC_MODELS }}
@@ -25,16 +28,6 @@ jobs:
       ollama_models: ${{ vars.NIGHTLY_LLM_OLLAMA_MODELS }}
       openrouter_models: ${{ vars.NIGHTLY_LLM_OPENROUTER_MODELS }}
       strict: true
-    secrets:
-      openai_api_key: ${{ secrets.OPENAI_API_KEY }}
-      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-      bedrock_api_key: ${{ secrets.BEDROCK_API_KEY }}
-      vertex_ai_custom_config_json: ${{ secrets.NIGHTLY_LLM_VERTEX_AI_CUSTOM_CONFIG_JSON }}
-      azure_api_key: ${{ secrets.AZURE_API_KEY }}
-      ollama_api_key: ${{ secrets.OLLAMA_API_KEY }}
-      openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
-      DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
-      DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
 
   notify-slack-on-failure:
     needs: [provider-chat-test]
diff --git a/.github/workflows/reusable-nightly-llm-provider-chat.yml b/.github/workflows/reusable-nightly-llm-provider-chat.yml
index 20417e2e88c..35b41116f50 100644
--- a/.github/workflows/reusable-nightly-llm-provider-chat.yml
+++ b/.github/workflows/reusable-nightly-llm-provider-chat.yml
@@ -48,28 +48,10 @@ on:
         required: false
         default: true
         type: boolean
-    secrets:
-      openai_api_key:
-        required: false
-      anthropic_api_key:
-        required: false
-      bedrock_api_key:
-        required: false
-      vertex_ai_custom_config_json:
-        required: false
-      azure_api_key:
-        required: false
-      ollama_api_key:
-        required: false
-      openrouter_api_key:
-        required: false
-      DOCKER_USERNAME:
-        required: true
-      DOCKER_TOKEN:
-        required: true
 
 permissions:
   contents: read
+  id-token: write
 
 jobs:
   build-backend-image:
@@ -81,6 +63,7 @@ jobs:
         "extras=ecr-cache",
       ]
     timeout-minutes: 45
+    environment: ci-protected
     steps:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
@@ -89,6 +72,19 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, test/docker-username
+            DOCKER_TOKEN, test/docker-token
+
       - name: Build backend image
         uses: ./.github/actions/build-backend-image
         with:
@@ -97,8 +93,8 @@ jobs:
           pr-number: ${{ github.event.pull_request.number }}
           github-sha: ${{ github.sha }}
           run-id: ${{ github.run_id }}
-          docker-username: ${{ secrets.DOCKER_USERNAME }}
-          docker-token: ${{ secrets.DOCKER_TOKEN }}
+          docker-username: ${{ env.DOCKER_USERNAME }}
+          docker-token: ${{ env.DOCKER_TOKEN }}
           docker-no-cache: ${{ vars.DOCKER_NO_CACHE == 'true' && 'true' || 'false' }}
 
   build-model-server-image:
@@ -110,6 +106,7 @@ jobs:
         "extras=ecr-cache",
       ]
     timeout-minutes: 45
+    environment: ci-protected
     steps:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
@@ -118,6 +115,19 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, test/docker-username
+            DOCKER_TOKEN, test/docker-token
+
       - name: Build model server image
         uses: ./.github/actions/build-model-server-image
         with:
@@ -126,8 +136,8 @@ jobs:
           pr-number: ${{ github.event.pull_request.number }}
           github-sha: ${{ github.sha }}
           run-id: ${{ github.run_id }}
-          docker-username: ${{ secrets.DOCKER_USERNAME }}
-          docker-token: ${{ secrets.DOCKER_TOKEN }}
+          docker-username: ${{ env.DOCKER_USERNAME }}
+          docker-token: ${{ env.DOCKER_TOKEN }}
 
   build-integration-image:
     runs-on:
@@ -138,6 +148,7 @@ jobs:
         "extras=ecr-cache",
       ]
     timeout-minutes: 45
+    environment: ci-protected
     steps:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
@@ -146,6 +157,19 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, test/docker-username
+            DOCKER_TOKEN, test/docker-token
+
       - name: Build integration image
         uses: ./.github/actions/build-integration-image
         with:
@@ -154,8 +178,8 @@ jobs:
           pr-number: ${{ github.event.pull_request.number }}
           github-sha: ${{ github.sha }}
           run-id: ${{ github.run_id }}
-          docker-username: ${{ secrets.DOCKER_USERNAME }}
-          docker-token: ${{ secrets.DOCKER_TOKEN }}
+          docker-username: ${{ env.DOCKER_USERNAME }}
+          docker-token: ${{ env.DOCKER_TOKEN }}
 
   provider-chat-test:
     needs:
@@ -170,56 +194,56 @@ jobs:
         include:
           - provider: openai
             models: ${{ inputs.openai_models }}
-            api_key_secret: openai_api_key
-            custom_config_secret: ""
+            api_key_env: OPENAI_API_KEY
+            custom_config_env: ""
             api_base: ""
             api_version: ""
             deployment_name: ""
             required: true
           - provider: anthropic
             models: ${{ inputs.anthropic_models }}
-            api_key_secret: anthropic_api_key
-            custom_config_secret: ""
+            api_key_env: ANTHROPIC_API_KEY
+            custom_config_env: ""
             api_base: ""
             api_version: ""
             deployment_name: ""
             required: true
           - provider: bedrock
             models: ${{ inputs.bedrock_models }}
-            api_key_secret: bedrock_api_key
-            custom_config_secret: ""
+            api_key_env: BEDROCK_API_KEY
+            custom_config_env: ""
             api_base: ""
             api_version: ""
             deployment_name: ""
             required: false
           - provider: vertex_ai
             models: ${{ inputs.vertex_ai_models }}
-            api_key_secret: ""
-            custom_config_secret: vertex_ai_custom_config_json
+            api_key_env: ""
+            custom_config_env: NIGHTLY_LLM_VERTEX_AI_CUSTOM_CONFIG_JSON
             api_base: ""
             api_version: ""
             deployment_name: ""
             required: false
           - provider: azure
             models: ${{ inputs.azure_models }}
-            api_key_secret: azure_api_key
-            custom_config_secret: ""
+            api_key_env: AZURE_API_KEY
+            custom_config_env: ""
             api_base: ${{ inputs.azure_api_base }}
             api_version: "2025-04-01-preview"
             deployment_name: ""
             required: false
           - provider: ollama_chat
             models: ${{ inputs.ollama_models }}
-            api_key_secret: ollama_api_key
-            custom_config_secret: ""
+            api_key_env: OLLAMA_API_KEY
+            custom_config_env: ""
             api_base: "https://ollama.com"
             api_version: ""
             deployment_name: ""
             required: false
           - provider: openrouter
             models: ${{ inputs.openrouter_models }}
-            api_key_secret: openrouter_api_key
-            custom_config_secret: ""
+            api_key_env: OPENROUTER_API_KEY
+            custom_config_env: ""
             api_base: "https://openrouter.ai/api/v1"
             api_version: ""
             deployment_name: ""
@@ -230,6 +254,7 @@ jobs:
       - "run-id=${{ github.run_id }}-nightly-${{ matrix.provider }}-provider-chat-test"
       - extras=ecr-cache
     timeout-minutes: 45
+    environment: ci-protected
     steps:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
@@ -238,21 +263,43 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          # Keep JSON values unparsed so vertex custom config is passed as raw JSON.
+          parse-json-secrets: false
+          secret-ids: |
+            DOCKER_USERNAME, test/docker-username
+            DOCKER_TOKEN, test/docker-token
+            OPENAI_API_KEY, test/openai-api-key
+            ANTHROPIC_API_KEY, test/anthropic-api-key
+            BEDROCK_API_KEY, test/bedrock-api-key
+            NIGHTLY_LLM_VERTEX_AI_CUSTOM_CONFIG_JSON, test/nightly-llm-vertex-ai-custom-config-json
+            AZURE_API_KEY, test/azure-api-key
+            OLLAMA_API_KEY, test/ollama-api-key
+            OPENROUTER_API_KEY, test/openrouter-api-key
+
       - name: Run nightly provider chat test
         uses: ./.github/actions/run-nightly-provider-chat-test
         with:
           provider: ${{ matrix.provider }}
           models: ${{ matrix.models }}
-          provider-api-key: ${{ matrix.api_key_secret && secrets[matrix.api_key_secret] || '' }}
+          provider-api-key: ${{ matrix.api_key_env && env[matrix.api_key_env] || '' }}
           strict: ${{ inputs.strict && 'true' || 'false' }}
           api-base: ${{ matrix.api_base }}
           api-version: ${{ matrix.api_version }}
           deployment-name: ${{ matrix.deployment_name }}
-          custom-config-json: ${{ matrix.custom_config_secret && secrets[matrix.custom_config_secret] || '' }}
+          custom-config-json: ${{ matrix.custom_config_env && env[matrix.custom_config_env] || '' }}
           runs-on-ecr-cache: ${{ env.RUNS_ON_ECR_CACHE }}
           run-id: ${{ github.run_id }}
-          docker-username: ${{ secrets.DOCKER_USERNAME }}
-          docker-token: ${{ secrets.DOCKER_TOKEN }}
+          docker-username: ${{ env.DOCKER_USERNAME }}
+          docker-token: ${{ env.DOCKER_TOKEN }}
 
       - name: Dump API server logs
         if: always()

From 0cdd438f463f32e929750126021f39f042354f03 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Mon, 2 Mar 2026 11:28:49 -0800
Subject: [PATCH 014/267] chore(ui): Update the Share Agent Modal (#8915)

---
 web/src/sections/modals/ShareAgentModal.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/src/sections/modals/ShareAgentModal.tsx b/web/src/sections/modals/ShareAgentModal.tsx
index 6c77f66f43a..901d32c8355 100644
--- a/web/src/sections/modals/ShareAgentModal.tsx
+++ b/web/src/sections/modals/ShareAgentModal.tsx
@@ -350,12 +350,12 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
           }
           cancel={
             <Button secondary onClick={handleClose}>
-              Done
+              Cancel
             </Button>
           }
           submit={
             <Button onClick={() => handleSubmit()} disabled={!dirty}>
-              Share
+              Save
             </Button>
           }
         />

From c93617df5dbb3b66acbae7f493037732d8a1e078 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 11:38:33 -0800
Subject: [PATCH 015/267] test(scim): add integration tests for SCIM user CRUD
 (#8825)

---
 .../common_utils/managers/scim_client.py      |  66 +++
 .../common_utils/managers/scim_token.py       |  27 -
 .../tests/scim/test_scim_tokens.py            |  20 +-
 .../integration/tests/scim/test_scim_users.py | 517 ++++++++++++++++++
 backend/tests/unit/ee/onyx/db/test_license.py | 114 ++++
 .../tests/unit/onyx/server/scim/conftest.py   |  13 +-
 6 files changed, 715 insertions(+), 42 deletions(-)
 create mode 100644 backend/tests/integration/common_utils/managers/scim_client.py
 create mode 100644 backend/tests/integration/tests/scim/test_scim_users.py

diff --git a/backend/tests/integration/common_utils/managers/scim_client.py b/backend/tests/integration/common_utils/managers/scim_client.py
new file mode 100644
index 00000000000..e1becbf752b
--- /dev/null
+++ b/backend/tests/integration/common_utils/managers/scim_client.py
@@ -0,0 +1,66 @@
+import requests
+
+from tests.integration.common_utils.constants import API_SERVER_URL
+from tests.integration.common_utils.constants import GENERAL_HEADERS
+
+
+class ScimClient:
+    """HTTP client for making authenticated SCIM v2 requests."""
+
+    @staticmethod
+    def _headers(raw_token: str) -> dict[str, str]:
+        return {
+            **GENERAL_HEADERS,
+            "Authorization": f"Bearer {raw_token}",
+        }
+
+    @staticmethod
+    def get(path: str, raw_token: str) -> requests.Response:
+        return requests.get(
+            f"{API_SERVER_URL}/scim/v2{path}",
+            headers=ScimClient._headers(raw_token),
+            timeout=60,
+        )
+
+    @staticmethod
+    def post(path: str, raw_token: str, json: dict) -> requests.Response:
+        return requests.post(
+            f"{API_SERVER_URL}/scim/v2{path}",
+            json=json,
+            headers=ScimClient._headers(raw_token),
+            timeout=60,
+        )
+
+    @staticmethod
+    def put(path: str, raw_token: str, json: dict) -> requests.Response:
+        return requests.put(
+            f"{API_SERVER_URL}/scim/v2{path}",
+            json=json,
+            headers=ScimClient._headers(raw_token),
+            timeout=60,
+        )
+
+    @staticmethod
+    def patch(path: str, raw_token: str, json: dict) -> requests.Response:
+        return requests.patch(
+            f"{API_SERVER_URL}/scim/v2{path}",
+            json=json,
+            headers=ScimClient._headers(raw_token),
+            timeout=60,
+        )
+
+    @staticmethod
+    def delete(path: str, raw_token: str) -> requests.Response:
+        return requests.delete(
+            f"{API_SERVER_URL}/scim/v2{path}",
+            headers=ScimClient._headers(raw_token),
+            timeout=60,
+        )
+
+    @staticmethod
+    def get_no_auth(path: str) -> requests.Response:
+        return requests.get(
+            f"{API_SERVER_URL}/scim/v2{path}",
+            headers=GENERAL_HEADERS,
+            timeout=60,
+        )
diff --git a/backend/tests/integration/common_utils/managers/scim_token.py b/backend/tests/integration/common_utils/managers/scim_token.py
index 3ea020a07e2..1894ed4f321 100644
--- a/backend/tests/integration/common_utils/managers/scim_token.py
+++ b/backend/tests/integration/common_utils/managers/scim_token.py
@@ -1,7 +1,6 @@
 import requests
 
 from tests.integration.common_utils.constants import API_SERVER_URL
-from tests.integration.common_utils.constants import GENERAL_HEADERS
 from tests.integration.common_utils.test_models import DATestScimToken
 from tests.integration.common_utils.test_models import DATestUser
 
@@ -51,29 +50,3 @@ def get_active(
             created_at=data["created_at"],
             last_used_at=data.get("last_used_at"),
         )
-
-    @staticmethod
-    def get_scim_headers(raw_token: str) -> dict[str, str]:
-        return {
-            **GENERAL_HEADERS,
-            "Authorization": f"Bearer {raw_token}",
-        }
-
-    @staticmethod
-    def scim_get(
-        path: str,
-        raw_token: str,
-    ) -> requests.Response:
-        return requests.get(
-            f"{API_SERVER_URL}/scim/v2{path}",
-            headers=ScimTokenManager.get_scim_headers(raw_token),
-            timeout=60,
-        )
-
-    @staticmethod
-    def scim_get_no_auth(path: str) -> requests.Response:
-        return requests.get(
-            f"{API_SERVER_URL}/scim/v2{path}",
-            headers=GENERAL_HEADERS,
-            timeout=60,
-        )
diff --git a/backend/tests/integration/tests/scim/test_scim_tokens.py b/backend/tests/integration/tests/scim/test_scim_tokens.py
index 19c95acbbdc..9476df86ef7 100644
--- a/backend/tests/integration/tests/scim/test_scim_tokens.py
+++ b/backend/tests/integration/tests/scim/test_scim_tokens.py
@@ -15,6 +15,7 @@
 import requests
 
 from tests.integration.common_utils.constants import API_SERVER_URL
+from tests.integration.common_utils.managers.scim_client import ScimClient
 from tests.integration.common_utils.managers.scim_token import ScimTokenManager
 from tests.integration.common_utils.managers.user import UserManager
 from tests.integration.common_utils.test_models import DATestUser
@@ -39,7 +40,7 @@ def test_scim_token_lifecycle(admin_user: DATestUser) -> None:
     assert active == token.model_copy(update={"raw_token": None})
 
     # Token works for SCIM requests
-    response = ScimTokenManager.scim_get("/Users", token.raw_token)
+    response = ScimClient.get("/Users", token.raw_token)
     assert response.status_code == 200
     body = response.json()
     assert "Resources" in body
@@ -54,7 +55,7 @@ def test_scim_token_rotation_revokes_previous(admin_user: DATestUser) -> None:
     )
     assert first.raw_token is not None
 
-    response = ScimTokenManager.scim_get("/Users", first.raw_token)
+    response = ScimClient.get("/Users", first.raw_token)
     assert response.status_code == 200
 
     # Create second token — should revoke first
@@ -69,25 +70,22 @@ def test_scim_token_rotation_revokes_previous(admin_user: DATestUser) -> None:
     assert active == second.model_copy(update={"raw_token": None})
 
     # First token rejected, second works
-    assert ScimTokenManager.scim_get("/Users", first.raw_token).status_code == 401
-    assert ScimTokenManager.scim_get("/Users", second.raw_token).status_code == 200
+    assert ScimClient.get("/Users", first.raw_token).status_code == 401
+    assert ScimClient.get("/Users", second.raw_token).status_code == 200
 
 
 def test_scim_request_without_token_rejected(
     admin_user: DATestUser,  # noqa: ARG001
 ) -> None:
     """SCIM endpoints reject requests with no Authorization header."""
-    assert ScimTokenManager.scim_get_no_auth("/Users").status_code == 401
+    assert ScimClient.get_no_auth("/Users").status_code == 401
 
 
 def test_scim_request_with_bad_token_rejected(
     admin_user: DATestUser,  # noqa: ARG001
 ) -> None:
     """SCIM endpoints reject requests with an invalid token."""
-    assert (
-        ScimTokenManager.scim_get("/Users", "onyx_scim_bogus_token_value").status_code
-        == 401
-    )
+    assert ScimClient.get("/Users", "onyx_scim_bogus_token_value").status_code == 401
 
 
 def test_non_admin_cannot_create_token(
@@ -139,7 +137,7 @@ def test_service_discovery_no_auth_required(
 ) -> None:
     """Service discovery endpoints work without any authentication."""
     for path in ["/ServiceProviderConfig", "/ResourceTypes", "/Schemas"]:
-        response = ScimTokenManager.scim_get_no_auth(path)
+        response = ScimClient.get_no_auth(path)
         assert response.status_code == 200, f"{path} returned {response.status_code}"
 
 
@@ -158,7 +156,7 @@ def test_last_used_at_updated_after_scim_request(
     assert active.last_used_at is None
 
     # Make a SCIM request, then verify last_used_at is set
-    assert ScimTokenManager.scim_get("/Users", token.raw_token).status_code == 200
+    assert ScimClient.get("/Users", token.raw_token).status_code == 200
     time.sleep(0.5)
 
     active_after = ScimTokenManager.get_active(user_performing_action=admin_user)
diff --git a/backend/tests/integration/tests/scim/test_scim_users.py b/backend/tests/integration/tests/scim/test_scim_users.py
new file mode 100644
index 00000000000..7a242960686
--- /dev/null
+++ b/backend/tests/integration/tests/scim/test_scim_users.py
@@ -0,0 +1,517 @@
+"""Integration tests for SCIM user provisioning endpoints.
+
+Covers the full user lifecycle as driven by an IdP (Okta / Azure AD):
+1. Create a user via POST /Users
+2. Retrieve a user via GET /Users/{id}
+3. List, filter, and paginate users via GET /Users
+4. Replace a user via PUT /Users/{id}
+5. Patch a user (deactivate/reactivate) via PATCH /Users/{id}
+6. Delete a user via DELETE /Users/{id}
+7. Error cases: missing externalId, duplicate email, not-found, seat limit
+
+All tests are parameterized across IdP request styles:
+- **Okta**: lowercase PATCH ops, minimal payloads (core schema only).
+- **Entra**: capitalized ops (``"Replace"``), enterprise extension data
+  (department, manager), and structured email arrays.
+
+The server normalizes both — these tests verify that all IdP-specific fields
+are accepted and round-tripped correctly.
+
+Auth, revoked-token, and service-discovery tests live in test_scim_tokens.py.
+"""
+
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+
+import pytest
+import redis
+import requests
+
+from ee.onyx.server.license.models import LicenseMetadata
+from ee.onyx.server.license.models import LicenseSource
+from ee.onyx.server.license.models import PlanType
+from onyx.auth.schemas import UserRole
+from onyx.configs.app_configs import REDIS_DB_NUMBER
+from onyx.configs.app_configs import REDIS_HOST
+from onyx.configs.app_configs import REDIS_PORT
+from onyx.server.settings.models import ApplicationStatus
+from tests.integration.common_utils.managers.scim_client import ScimClient
+from tests.integration.common_utils.managers.scim_token import ScimTokenManager
+
+
+SCIM_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
+SCIM_ENTERPRISE_USER_SCHEMA = (
+    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
+)
+SCIM_PATCH_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
+
+_LICENSE_REDIS_KEY = "public:license:metadata"
+
+
+@pytest.fixture(scope="module", params=["okta", "entra"])
+def idp_style(request: pytest.FixtureRequest) -> str:
+    """Parameterized IdP style — runs every test with both Okta and Entra request formats."""
+    return request.param
+
+
+@pytest.fixture(scope="module")
+def scim_token(idp_style: str) -> str:
+    """Create a single SCIM token shared across all tests in this module.
+
+    Creating a new token revokes the previous one, so we create exactly once
+    per IdP-style run and reuse. Uses UserManager directly to avoid
+    fixture-scope conflicts with the function-scoped admin_user fixture.
+    """
+    from tests.integration.common_utils.constants import ADMIN_USER_NAME
+    from tests.integration.common_utils.constants import GENERAL_HEADERS
+    from tests.integration.common_utils.managers.user import build_email
+    from tests.integration.common_utils.managers.user import DEFAULT_PASSWORD
+    from tests.integration.common_utils.managers.user import UserManager
+    from tests.integration.common_utils.test_models import DATestUser
+
+    try:
+        admin = UserManager.create(name=ADMIN_USER_NAME)
+    except Exception:
+        admin = UserManager.login_as_user(
+            DATestUser(
+                id="",
+                email=build_email(ADMIN_USER_NAME),
+                password=DEFAULT_PASSWORD,
+                headers=GENERAL_HEADERS,
+                role=UserRole.ADMIN,
+                is_active=True,
+            )
+        )
+
+    token = ScimTokenManager.create(
+        name=f"scim-user-tests-{idp_style}",
+        user_performing_action=admin,
+    ).raw_token
+    assert token is not None
+    return token
+
+
+def _make_user_resource(
+    email: str,
+    external_id: str,
+    given_name: str = "Test",
+    family_name: str = "User",
+    active: bool = True,
+    idp_style: str = "okta",
+    department: str | None = None,
+    manager_id: str | None = None,
+) -> dict:
+    """Build a SCIM UserResource payload appropriate for the IdP style.
+
+    Entra sends richer payloads including enterprise extension data (department,
+    manager), structured email arrays, and the enterprise schema URN. Okta sends
+    minimal payloads with just core user fields.
+    """
+    resource: dict = {
+        "schemas": [SCIM_USER_SCHEMA],
+        "userName": email,
+        "externalId": external_id,
+        "name": {
+            "givenName": given_name,
+            "familyName": family_name,
+        },
+        "active": active,
+    }
+    if idp_style == "entra":
+        dept = department or "Engineering"
+        mgr = manager_id or "mgr-ext-001"
+        resource["schemas"].append(SCIM_ENTERPRISE_USER_SCHEMA)
+        resource[SCIM_ENTERPRISE_USER_SCHEMA] = {
+            "department": dept,
+            "manager": {"value": mgr},
+        }
+        resource["emails"] = [
+            {"value": email, "type": "work", "primary": True},
+        ]
+    return resource
+
+
+def _make_patch_request(operations: list[dict], idp_style: str = "okta") -> dict:
+    """Build a SCIM PatchOp payload, applying IdP-specific operation casing.
+
+    Entra sends capitalized operations (e.g. ``"Replace"`` instead of
+    ``"replace"``). The server's ``normalize_operation`` validator lowercases
+    them — these tests verify that both casings are accepted.
+    """
+    cased_operations = []
+    for operation in operations:
+        cased = dict(operation)
+        if idp_style == "entra":
+            cased["op"] = operation["op"].capitalize()
+        cased_operations.append(cased)
+    return {
+        "schemas": [SCIM_PATCH_SCHEMA],
+        "Operations": cased_operations,
+    }
+
+
+def _create_scim_user(
+    token: str,
+    email: str,
+    external_id: str,
+    idp_style: str = "okta",
+) -> requests.Response:
+    return ScimClient.post(
+        "/Users",
+        token,
+        json=_make_user_resource(email, external_id, idp_style=idp_style),
+    )
+
+
+def _assert_entra_extension(
+    body: dict,
+    expected_department: str = "Engineering",
+    expected_manager: str = "mgr-ext-001",
+) -> None:
+    """Assert that Entra enterprise extension fields round-tripped correctly."""
+    assert SCIM_ENTERPRISE_USER_SCHEMA in body["schemas"]
+    ext = body[SCIM_ENTERPRISE_USER_SCHEMA]
+    assert ext["department"] == expected_department
+    assert ext["manager"]["value"] == expected_manager
+
+
+def _assert_entra_emails(body: dict, expected_email: str) -> None:
+    """Assert that structured email metadata round-tripped correctly."""
+    emails = body["emails"]
+    assert len(emails) >= 1
+    work_email = next(e for e in emails if e.get("type") == "work")
+    assert work_email["value"] == expected_email
+    assert work_email["primary"] is True
+
+
+# ------------------------------------------------------------------
+# Lifecycle: create -> get -> list -> replace -> patch -> delete
+# ------------------------------------------------------------------
+
+
+def test_create_user(scim_token: str, idp_style: str) -> None:
+    """POST /Users creates a provisioned user and returns 201."""
+    email = f"scim_create_{idp_style}@example.com"
+    ext_id = f"ext-create-{idp_style}"
+    resp = _create_scim_user(scim_token, email, ext_id, idp_style)
+    assert resp.status_code == 201
+
+    body = resp.json()
+    assert body["userName"] == email
+    assert body["externalId"] == ext_id
+    assert body["active"] is True
+    assert body["id"]  # UUID assigned by server
+    assert body["meta"]["resourceType"] == "User"
+    assert body["name"]["givenName"] == "Test"
+    assert body["name"]["familyName"] == "User"
+
+    if idp_style == "entra":
+        _assert_entra_extension(body)
+        _assert_entra_emails(body, email)
+
+
+def test_get_user(scim_token: str, idp_style: str) -> None:
+    """GET /Users/{id} returns the user resource with all stored fields."""
+    email = f"scim_get_{idp_style}@example.com"
+    ext_id = f"ext-get-{idp_style}"
+    created = _create_scim_user(scim_token, email, ext_id, idp_style).json()
+
+    resp = ScimClient.get(f"/Users/{created['id']}", scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["id"] == created["id"]
+    assert body["userName"] == email
+    assert body["externalId"] == ext_id
+    assert body["name"]["givenName"] == "Test"
+    assert body["name"]["familyName"] == "User"
+
+    if idp_style == "entra":
+        _assert_entra_extension(body)
+        _assert_entra_emails(body, email)
+
+
+def test_list_users(scim_token: str, idp_style: str) -> None:
+    """GET /Users returns a ListResponse containing provisioned users."""
+    email = f"scim_list_{idp_style}@example.com"
+    _create_scim_user(scim_token, email, f"ext-list-{idp_style}", idp_style)
+
+    resp = ScimClient.get("/Users", scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["totalResults"] >= 1
+    emails = [r["userName"] for r in body["Resources"]]
+    assert email in emails
+
+
+def test_list_users_pagination(scim_token: str, idp_style: str) -> None:
+    """GET /Users with startIndex and count returns correct pagination."""
+    _create_scim_user(
+        scim_token,
+        f"scim_page1_{idp_style}@example.com",
+        f"ext-page-1-{idp_style}",
+        idp_style,
+    )
+    _create_scim_user(
+        scim_token,
+        f"scim_page2_{idp_style}@example.com",
+        f"ext-page-2-{idp_style}",
+        idp_style,
+    )
+
+    resp = ScimClient.get("/Users?startIndex=1&count=1", scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["startIndex"] == 1
+    assert body["itemsPerPage"] == 1
+    assert body["totalResults"] >= 2
+    assert len(body["Resources"]) == 1
+
+
+def test_filter_users_by_username(scim_token: str, idp_style: str) -> None:
+    """GET /Users?filter=userName eq '...' returns only matching users."""
+    email = f"scim_filter_{idp_style}@example.com"
+    _create_scim_user(scim_token, email, f"ext-filter-{idp_style}", idp_style)
+
+    resp = ScimClient.get(f'/Users?filter=userName eq "{email}"', scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["totalResults"] == 1
+    assert body["Resources"][0]["userName"] == email
+
+
+def test_replace_user(scim_token: str, idp_style: str) -> None:
+    """PUT /Users/{id} replaces the user resource including enterprise fields."""
+    email = f"scim_replace_{idp_style}@example.com"
+    ext_id = f"ext-replace-{idp_style}"
+    created = _create_scim_user(scim_token, email, ext_id, idp_style).json()
+
+    updated_resource = _make_user_resource(
+        email=email,
+        external_id=ext_id,
+        given_name="Updated",
+        family_name="Name",
+        idp_style=idp_style,
+        department="Product",
+    )
+    resp = ScimClient.put(f"/Users/{created['id']}", scim_token, json=updated_resource)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["name"]["givenName"] == "Updated"
+    assert body["name"]["familyName"] == "Name"
+
+    if idp_style == "entra":
+        _assert_entra_extension(body, expected_department="Product")
+        _assert_entra_emails(body, email)
+
+
+def test_patch_deactivate_user(scim_token: str, idp_style: str) -> None:
+    """PATCH /Users/{id} with active=false deactivates the user."""
+    created = _create_scim_user(
+        scim_token,
+        f"scim_deactivate_{idp_style}@example.com",
+        f"ext-deactivate-{idp_style}",
+        idp_style,
+    ).json()
+    assert created["active"] is True
+
+    resp = ScimClient.patch(
+        f"/Users/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "replace", "path": "active", "value": False}], idp_style
+        ),
+    )
+    assert resp.status_code == 200
+    assert resp.json()["active"] is False
+
+    # Confirm via GET
+    get_resp = ScimClient.get(f"/Users/{created['id']}", scim_token)
+    assert get_resp.json()["active"] is False
+
+
+def test_patch_reactivate_user(scim_token: str, idp_style: str) -> None:
+    """PATCH active=true reactivates a previously deactivated user."""
+    created = _create_scim_user(
+        scim_token,
+        f"scim_reactivate_{idp_style}@example.com",
+        f"ext-reactivate-{idp_style}",
+        idp_style,
+    ).json()
+
+    # Deactivate
+    deactivate_resp = ScimClient.patch(
+        f"/Users/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "replace", "path": "active", "value": False}], idp_style
+        ),
+    )
+    assert deactivate_resp.status_code == 200
+    assert deactivate_resp.json()["active"] is False
+
+    # Reactivate
+    resp = ScimClient.patch(
+        f"/Users/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "replace", "path": "active", "value": True}], idp_style
+        ),
+    )
+    assert resp.status_code == 200
+    assert resp.json()["active"] is True
+
+
+def test_delete_user(scim_token: str, idp_style: str) -> None:
+    """DELETE /Users/{id} deactivates and removes the SCIM mapping."""
+    created = _create_scim_user(
+        scim_token,
+        f"scim_delete_{idp_style}@example.com",
+        f"ext-delete-{idp_style}",
+        idp_style,
+    ).json()
+
+    resp = ScimClient.delete(f"/Users/{created['id']}", scim_token)
+    assert resp.status_code == 204
+
+    # Second DELETE returns 404 per RFC 7644 §3.6 (mapping removed)
+    resp2 = ScimClient.delete(f"/Users/{created['id']}", scim_token)
+    assert resp2.status_code == 404
+
+
+# ------------------------------------------------------------------
+# Error cases
+# ------------------------------------------------------------------
+
+
+def test_create_user_missing_external_id(scim_token: str) -> None:
+    """POST /Users without externalId returns 400."""
+    resp = ScimClient.post(
+        "/Users",
+        scim_token,
+        json={
+            "schemas": [SCIM_USER_SCHEMA],
+            "userName": "scim_no_extid@example.com",
+            "active": True,
+        },
+    )
+    assert resp.status_code == 400
+    assert "externalId" in resp.json()["detail"]
+
+
+def test_create_user_duplicate_email(scim_token: str, idp_style: str) -> None:
+    """POST /Users with an already-taken email returns 409."""
+    email = f"scim_dup_{idp_style}@example.com"
+    resp1 = _create_scim_user(scim_token, email, f"ext-dup-1-{idp_style}", idp_style)
+    assert resp1.status_code == 201
+
+    resp2 = _create_scim_user(scim_token, email, f"ext-dup-2-{idp_style}", idp_style)
+    assert resp2.status_code == 409
+
+
+def test_get_nonexistent_user(scim_token: str) -> None:
+    """GET /Users/{bad-id} returns 404."""
+    resp = ScimClient.get("/Users/00000000-0000-0000-0000-000000000000", scim_token)
+    assert resp.status_code == 404
+
+
+def test_filter_users_by_external_id(scim_token: str, idp_style: str) -> None:
+    """GET /Users?filter=externalId eq '...' returns the matching user."""
+    ext_id = f"ext-unique-filter-id-{idp_style}"
+    _create_scim_user(
+        scim_token, f"scim_extfilter_{idp_style}@example.com", ext_id, idp_style
+    )
+
+    resp = ScimClient.get(f'/Users?filter=externalId eq "{ext_id}"', scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["totalResults"] == 1
+    assert body["Resources"][0]["externalId"] == ext_id
+
+
+# ------------------------------------------------------------------
+# Seat-limit enforcement
+# ------------------------------------------------------------------
+
+
+def _seed_license(r: redis.Redis, seats: int) -> None:
+    """Write a LicenseMetadata entry into Redis with the given seat cap."""
+    now = datetime.now(timezone.utc)
+    metadata = LicenseMetadata(
+        tenant_id="public",
+        organization_name="Test Org",
+        seats=seats,
+        used_seats=0,  # check_seat_availability recalculates from DB
+        plan_type=PlanType.ANNUAL,
+        issued_at=now,
+        expires_at=now + timedelta(days=365),
+        status=ApplicationStatus.ACTIVE,
+        source=LicenseSource.MANUAL_UPLOAD,
+    )
+    r.set(_LICENSE_REDIS_KEY, metadata.model_dump_json(), ex=300)
+
+
+def test_create_user_seat_limit(scim_token: str, idp_style: str) -> None:
+    """POST /Users returns 403 when the seat limit is reached."""
+    r = redis.Redis(host=REDIS_HOST, port=REDIS_PORT, db=REDIS_DB_NUMBER)
+
+    # admin_user already occupies 1 seat; cap at 1 -> full
+    _seed_license(r, seats=1)
+
+    try:
+        resp = _create_scim_user(
+            scim_token,
+            f"scim_blocked_{idp_style}@example.com",
+            f"ext-blocked-{idp_style}",
+            idp_style,
+        )
+        assert resp.status_code == 403
+        assert "seat" in resp.json()["detail"].lower()
+    finally:
+        r.delete(_LICENSE_REDIS_KEY)
+
+
+def test_reactivate_user_seat_limit(scim_token: str, idp_style: str) -> None:
+    """PATCH active=true returns 403 when the seat limit is reached."""
+    # Create and deactivate a user (before license is seeded)
+    created = _create_scim_user(
+        scim_token,
+        f"scim_reactivate_blocked_{idp_style}@example.com",
+        f"ext-reactivate-blocked-{idp_style}",
+        idp_style,
+    ).json()
+    assert created["active"] is True
+
+    deactivate_resp = ScimClient.patch(
+        f"/Users/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "replace", "path": "active", "value": False}], idp_style
+        ),
+    )
+    assert deactivate_resp.status_code == 200
+    assert deactivate_resp.json()["active"] is False
+
+    r = redis.Redis(host=REDIS_HOST, port=REDIS_PORT, db=REDIS_DB_NUMBER)
+
+    # Seed license capped at current active users -> reactivation should fail
+    _seed_license(r, seats=1)
+
+    try:
+        resp = ScimClient.patch(
+            f"/Users/{created['id']}",
+            scim_token,
+            json=_make_patch_request(
+                [{"op": "replace", "path": "active", "value": True}], idp_style
+            ),
+        )
+        assert resp.status_code == 403
+        assert "seat" in resp.json()["detail"].lower()
+    finally:
+        r.delete(_LICENSE_REDIS_KEY)
diff --git a/backend/tests/unit/ee/onyx/db/test_license.py b/backend/tests/unit/ee/onyx/db/test_license.py
index c05a3b9481e..9dae27d08d1 100644
--- a/backend/tests/unit/ee/onyx/db/test_license.py
+++ b/backend/tests/unit/ee/onyx/db/test_license.py
@@ -1,11 +1,20 @@
 """Tests for license database CRUD operations."""
 
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
 from unittest.mock import MagicMock
+from unittest.mock import patch
 
+from ee.onyx.db.license import check_seat_availability
 from ee.onyx.db.license import delete_license
 from ee.onyx.db.license import get_license
 from ee.onyx.db.license import upsert_license
+from ee.onyx.server.license.models import LicenseMetadata
+from ee.onyx.server.license.models import LicenseSource
+from ee.onyx.server.license.models import PlanType
 from onyx.db.models import License
+from onyx.server.settings.models import ApplicationStatus
 
 
 class TestGetLicense:
@@ -100,3 +109,108 @@ def test_delete_no_license(self) -> None:
         assert result is False
         mock_session.delete.assert_not_called()
         mock_session.commit.assert_not_called()
+
+
+def _make_license_metadata(seats: int = 10) -> LicenseMetadata:
+    now = datetime.now(timezone.utc)
+    return LicenseMetadata(
+        tenant_id="public",
+        seats=seats,
+        used_seats=0,
+        plan_type=PlanType.ANNUAL,
+        issued_at=now,
+        expires_at=now + timedelta(days=365),
+        status=ApplicationStatus.ACTIVE,
+        source=LicenseSource.MANUAL_UPLOAD,
+    )
+
+
+class TestCheckSeatAvailabilitySelfHosted:
+    """Seat checks for self-hosted (MULTI_TENANT=False)."""
+
+    @patch("ee.onyx.db.license.get_license_metadata", return_value=None)
+    def test_no_license_means_unlimited(self, _mock_meta: MagicMock) -> None:
+        result = check_seat_availability(MagicMock(), seats_needed=1)
+        assert result.available is True
+
+    @patch("ee.onyx.db.license.get_used_seats", return_value=5)
+    @patch("ee.onyx.db.license.get_license_metadata")
+    def test_seats_available(self, mock_meta: MagicMock, _mock_used: MagicMock) -> None:
+        mock_meta.return_value = _make_license_metadata(seats=10)
+        result = check_seat_availability(MagicMock(), seats_needed=1)
+        assert result.available is True
+
+    @patch("ee.onyx.db.license.get_used_seats", return_value=10)
+    @patch("ee.onyx.db.license.get_license_metadata")
+    def test_seats_full_blocks_creation(
+        self, mock_meta: MagicMock, _mock_used: MagicMock
+    ) -> None:
+        mock_meta.return_value = _make_license_metadata(seats=10)
+        result = check_seat_availability(MagicMock(), seats_needed=1)
+        assert result.available is False
+        assert result.error_message is not None
+        assert "10 of 10" in result.error_message
+
+    @patch("ee.onyx.db.license.get_used_seats", return_value=10)
+    @patch("ee.onyx.db.license.get_license_metadata")
+    def test_exactly_at_capacity_allows_no_more(
+        self, mock_meta: MagicMock, _mock_used: MagicMock
+    ) -> None:
+        """Filling to 100% is allowed; exceeding is not."""
+        mock_meta.return_value = _make_license_metadata(seats=10)
+        result = check_seat_availability(MagicMock(), seats_needed=1)
+        assert result.available is False
+
+    @patch("ee.onyx.db.license.get_used_seats", return_value=9)
+    @patch("ee.onyx.db.license.get_license_metadata")
+    def test_filling_to_capacity_is_allowed(
+        self, mock_meta: MagicMock, _mock_used: MagicMock
+    ) -> None:
+        mock_meta.return_value = _make_license_metadata(seats=10)
+        result = check_seat_availability(MagicMock(), seats_needed=1)
+        assert result.available is True
+
+
+class TestCheckSeatAvailabilityMultiTenant:
+    """Seat checks for multi-tenant cloud (MULTI_TENANT=True).
+
+    Verifies that get_used_seats takes the MULTI_TENANT branch
+    and delegates to get_tenant_count.
+    """
+
+    @patch("ee.onyx.db.license.MULTI_TENANT", True)
+    @patch(
+        "ee.onyx.server.tenants.user_mapping.get_tenant_count",
+        return_value=5,
+    )
+    @patch("ee.onyx.db.license.get_license_metadata")
+    def test_seats_available_multi_tenant(
+        self,
+        mock_meta: MagicMock,
+        mock_tenant_count: MagicMock,
+    ) -> None:
+        mock_meta.return_value = _make_license_metadata(seats=10)
+        result = check_seat_availability(
+            MagicMock(), seats_needed=1, tenant_id="tenant-abc"
+        )
+        assert result.available is True
+        mock_tenant_count.assert_called_once_with("tenant-abc")
+
+    @patch("ee.onyx.db.license.MULTI_TENANT", True)
+    @patch(
+        "ee.onyx.server.tenants.user_mapping.get_tenant_count",
+        return_value=10,
+    )
+    @patch("ee.onyx.db.license.get_license_metadata")
+    def test_seats_full_multi_tenant(
+        self,
+        mock_meta: MagicMock,
+        mock_tenant_count: MagicMock,
+    ) -> None:
+        mock_meta.return_value = _make_license_metadata(seats=10)
+        result = check_seat_availability(
+            MagicMock(), seats_needed=1, tenant_id="tenant-abc"
+        )
+        assert result.available is False
+        assert result.error_message is not None
+        mock_tenant_count.assert_called_once_with("tenant-abc")
diff --git a/backend/tests/unit/onyx/server/scim/conftest.py b/backend/tests/unit/onyx/server/scim/conftest.py
index 351a0fcec0c..515d94eb776 100644
--- a/backend/tests/unit/onyx/server/scim/conftest.py
+++ b/backend/tests/unit/onyx/server/scim/conftest.py
@@ -19,6 +19,7 @@
 from ee.onyx.server.scim.models import ScimName
 from ee.onyx.server.scim.models import ScimUserResource
 from ee.onyx.server.scim.providers.base import ScimProvider
+from ee.onyx.server.scim.providers.entra import EntraProvider
 from ee.onyx.server.scim.providers.okta import OktaProvider
 from onyx.db.models import ScimToken
 from onyx.db.models import ScimUserMapping
@@ -26,6 +27,10 @@
 from onyx.db.models import UserGroup
 from onyx.db.models import UserRole
 
+# Every supported SCIM provider must appear here so that all endpoint tests
+# run against it.  When adding a new provider, add its class to this list.
+SCIM_PROVIDERS: list[type[ScimProvider]] = [OktaProvider, EntraProvider]
+
 
 @pytest.fixture
 def mock_db_session() -> MagicMock:
@@ -41,10 +46,10 @@ def mock_token() -> MagicMock:
     return token
 
 
-@pytest.fixture
-def provider() -> ScimProvider:
-    """An OktaProvider instance for endpoint tests."""
-    return OktaProvider()
+@pytest.fixture(params=SCIM_PROVIDERS, ids=[p.__name__ for p in SCIM_PROVIDERS])
+def provider(request: pytest.FixtureRequest) -> ScimProvider:
+    """Parameterized provider — runs each test with every provider in SCIM_PROVIDERS."""
+    return request.param()
 
 
 @pytest.fixture

From 11c54bafb503f3560223f0d9940be3ca5a53f1fa Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Mon, 2 Mar 2026 12:01:26 -0800
Subject: [PATCH 016/267] chore: no vector db deployment (#8867)

---
 backend/onyx/background/periodic_poller.py    |   5 +-
 .../background/test_periodic_task_claim.py    |   6 +-
 .../test_no_vectordb_file_lifecycle.py        | 160 ++++++++++++++++++
 .../docker-compose.no-vectordb.yml            |  17 +-
 .../charts/onyx/templates/celery-beat.yaml    |   2 +-
 .../templates/celery-worker-heavy-hpa.yaml    |   2 +-
 .../celery-worker-heavy-scaledobject.yaml     |   2 +-
 .../onyx/templates/celery-worker-heavy.yaml   |   2 +-
 .../templates/celery-worker-light-hpa.yaml    |   2 +-
 .../celery-worker-light-scaledobject.yaml     |   2 +-
 .../onyx/templates/celery-worker-light.yaml   |   2 +-
 .../celery-worker-monitoring-hpa.yaml         |   2 +-
 ...celery-worker-monitoring-scaledobject.yaml |   2 +-
 .../templates/celery-worker-monitoring.yaml   |   2 +-
 .../templates/celery-worker-primary-hpa.yaml  |   2 +-
 .../celery-worker-primary-scaledobject.yaml   |   2 +-
 .../onyx/templates/celery-worker-primary.yaml |   2 +-
 ...elery-worker-user-file-processing-hpa.yaml |   2 +-
 ...ker-user-file-processing-scaledobject.yaml |   2 +-
 .../celery-worker-user-file-processing.yaml   |   2 +-
 deployment/helm/charts/onyx/values.yaml       |   4 +-
 21 files changed, 196 insertions(+), 28 deletions(-)
 create mode 100644 backend/tests/integration/tests/no_vectordb/test_no_vectordb_file_lifecycle.py

diff --git a/backend/onyx/background/periodic_poller.py b/backend/onyx/background/periodic_poller.py
index 9580fb7d652..f7a836e6dda 100644
--- a/backend/onyx/background/periodic_poller.py
+++ b/backend/onyx/background/periodic_poller.py
@@ -32,13 +32,16 @@
 # ------------------------------------------------------------------
 
 
+_NEVER_RAN: float = -1e18
+
+
 @dataclass
 class _PeriodicTaskDef:
     name: str
     interval_seconds: float
     lock_id: int
     run_fn: Callable[[], None]
-    last_run_at: float = field(default=0.0)
+    last_run_at: float = field(default=_NEVER_RAN)
 
 
 def _run_auto_llm_update() -> None:
diff --git a/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py b/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py
index 92132e1db0d..de5fc44edf4 100644
--- a/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py
+++ b/backend/tests/external_dependency_unit/background/test_periodic_task_claim.py
@@ -46,10 +46,10 @@ def _make_task(
     run_fn: MagicMock | None = None,
 ) -> _PeriodicTaskDef:
     return _PeriodicTaskDef(
-        name=name or f"test-{uuid4().hex[:8]}",
+        name=name if name is not None else f"test-{uuid4().hex[:8]}",
         interval_seconds=interval,
-        lock_id=lock_id or _TEST_LOCK_BASE,
-        run_fn=run_fn or MagicMock(),
+        lock_id=lock_id if lock_id is not None else _TEST_LOCK_BASE,
+        run_fn=run_fn if run_fn is not None else MagicMock(),
     )
 
 
diff --git a/backend/tests/integration/tests/no_vectordb/test_no_vectordb_file_lifecycle.py b/backend/tests/integration/tests/no_vectordb/test_no_vectordb_file_lifecycle.py
new file mode 100644
index 00000000000..fa552b4d7aa
--- /dev/null
+++ b/backend/tests/integration/tests/no_vectordb/test_no_vectordb_file_lifecycle.py
@@ -0,0 +1,160 @@
+"""Integration test for the full user-file lifecycle in no-vector-DB mode.
+
+Covers: upload → COMPLETED → unlink from project → delete → gone.
+
+The entire lifecycle is handled by FastAPI BackgroundTasks (no Celery workers
+needed).  The conftest-level ``pytestmark`` ensures these tests are skipped
+when the server is running with vector DB enabled.
+"""
+
+import time
+from uuid import UUID
+
+import requests
+
+from onyx.db.enums import UserFileStatus
+from tests.integration.common_utils.constants import API_SERVER_URL
+from tests.integration.common_utils.managers.project import ProjectManager
+from tests.integration.common_utils.test_models import DATestLLMProvider
+from tests.integration.common_utils.test_models import DATestUser
+
+POLL_INTERVAL_SECONDS = 1
+POLL_TIMEOUT_SECONDS = 30
+
+
+def _poll_file_status(
+    file_id: UUID,
+    user: DATestUser,
+    target_status: UserFileStatus,
+    timeout: int = POLL_TIMEOUT_SECONDS,
+) -> None:
+    """Poll GET /user/projects/file/{file_id} until the file reaches *target_status*."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        resp = requests.get(
+            f"{API_SERVER_URL}/user/projects/file/{file_id}",
+            headers=user.headers,
+        )
+        if resp.ok:
+            status = resp.json().get("status")
+            if status == target_status.value:
+                return
+        time.sleep(POLL_INTERVAL_SECONDS)
+    raise TimeoutError(
+        f"File {file_id} did not reach {target_status.value} within {timeout}s"
+    )
+
+
+def _file_is_gone(file_id: UUID, user: DATestUser, timeout: int = 15) -> None:
+    """Poll until GET /user/projects/file/{file_id} returns 404."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        resp = requests.get(
+            f"{API_SERVER_URL}/user/projects/file/{file_id}",
+            headers=user.headers,
+        )
+        if resp.status_code == 404:
+            return
+        time.sleep(POLL_INTERVAL_SECONDS)
+    raise TimeoutError(
+        f"File {file_id} still accessible after {timeout}s (expected 404)"
+    )
+
+
+def test_file_upload_process_delete_lifecycle(
+    reset: None,  # noqa: ARG001
+    admin_user: DATestUser,
+    llm_provider: DATestLLMProvider,  # noqa: ARG001
+) -> None:
+    """Full lifecycle: upload → COMPLETED → unlink → delete → 404.
+
+    Validates that the API server handles all background processing
+    (via FastAPI BackgroundTasks) without any Celery workers running.
+    """
+    project = ProjectManager.create(
+        name="lifecycle-test", user_performing_action=admin_user
+    )
+
+    file_content = b"Integration test file content for lifecycle verification."
+    upload_result = ProjectManager.upload_files(
+        project_id=project.id,
+        files=[("lifecycle.txt", file_content)],
+        user_performing_action=admin_user,
+    )
+    assert upload_result.user_files, "Expected at least one file in upload response"
+
+    user_file = upload_result.user_files[0]
+    file_id = user_file.id
+
+    _poll_file_status(file_id, admin_user, UserFileStatus.COMPLETED)
+
+    project_files = ProjectManager.get_project_files(project.id, admin_user)
+    assert any(
+        f.id == file_id for f in project_files
+    ), "File should be listed in project files after processing"
+
+    # Unlink the file from the project so the delete endpoint will proceed
+    unlink_resp = requests.delete(
+        f"{API_SERVER_URL}/user/projects/{project.id}/files/{file_id}",
+        headers=admin_user.headers,
+    )
+    assert (
+        unlink_resp.status_code == 204
+    ), f"Expected 204 on unlink, got {unlink_resp.status_code}: {unlink_resp.text}"
+
+    delete_resp = requests.delete(
+        f"{API_SERVER_URL}/user/projects/file/{file_id}",
+        headers=admin_user.headers,
+    )
+    assert (
+        delete_resp.ok
+    ), f"Delete request failed: {delete_resp.status_code} {delete_resp.text}"
+    body = delete_resp.json()
+    assert (
+        body["has_associations"] is False
+    ), f"File still has associations after unlink: {body}"
+
+    _file_is_gone(file_id, admin_user)
+
+    project_files_after = ProjectManager.get_project_files(project.id, admin_user)
+    assert not any(
+        f.id == file_id for f in project_files_after
+    ), "Deleted file should not appear in project files"
+
+
+def test_delete_blocked_while_associated(
+    reset: None,  # noqa: ARG001
+    admin_user: DATestUser,
+    llm_provider: DATestLLMProvider,  # noqa: ARG001
+) -> None:
+    """Deleting a file that still belongs to a project should return
+    has_associations=True without actually deleting the file."""
+    project = ProjectManager.create(
+        name="assoc-test", user_performing_action=admin_user
+    )
+
+    upload_result = ProjectManager.upload_files(
+        project_id=project.id,
+        files=[("assoc.txt", b"associated file content")],
+        user_performing_action=admin_user,
+    )
+    file_id = upload_result.user_files[0].id
+
+    _poll_file_status(file_id, admin_user, UserFileStatus.COMPLETED)
+
+    # Attempt to delete while still linked
+    delete_resp = requests.delete(
+        f"{API_SERVER_URL}/user/projects/file/{file_id}",
+        headers=admin_user.headers,
+    )
+    assert delete_resp.ok
+    body = delete_resp.json()
+    assert body["has_associations"] is True, "Should report existing associations"
+    assert project.name in body["project_names"]
+
+    # File should still be accessible
+    get_resp = requests.get(
+        f"{API_SERVER_URL}/user/projects/file/{file_id}",
+        headers=admin_user.headers,
+    )
+    assert get_resp.status_code == 200, "File should still exist after blocked delete"
diff --git a/deployment/docker_compose/docker-compose.no-vectordb.yml b/deployment/docker_compose/docker-compose.no-vectordb.yml
index 2709700df46..1c7fd766280 100644
--- a/deployment/docker_compose/docker-compose.no-vectordb.yml
+++ b/deployment/docker_compose/docker-compose.no-vectordb.yml
@@ -16,12 +16,15 @@
 # This overlay:
 #   - Moves Vespa (index), both model servers, and code-interpreter to profiles
 #     so they do not start by default
-#   - Makes the depends_on references to those services optional
-#   - Sets DISABLE_VECTOR_DB=true on backend services
+#   - Moves the background worker to the "background" profile (the API server
+#     handles all background work via FastAPI BackgroundTasks)
+#   - Makes the depends_on references to removed services optional
+#   - Sets DISABLE_VECTOR_DB=true on the api_server
 #
 # To selectively bring services back:
 #   --profile vectordb          Vespa + indexing model server
 #   --profile inference         Inference model server
+#   --profile background        Background worker (Celery)
 #   --profile code-interpreter  Code interpreter
 # =============================================================================
 
@@ -43,20 +46,20 @@ services:
       - DISABLE_VECTOR_DB=true
       - FILE_STORE_BACKEND=postgres
 
+  # Move the background worker to a profile so it does not start by default.
+  # The API server handles all background work in NO_VECTOR_DB mode.
   background:
+    profiles: ["background"]
     depends_on:
       index:
         condition: service_started
         required: false
-      indexing_model_server:
+      inference_model_server:
         condition: service_started
         required: false
-      inference_model_server:
+      indexing_model_server:
         condition: service_started
         required: false
-    environment:
-      - DISABLE_VECTOR_DB=true
-      - FILE_STORE_BACKEND=postgres
 
   # Move Vespa and indexing model server to a profile so they do not start.
   index:
diff --git a/deployment/helm/charts/onyx/templates/celery-beat.yaml b/deployment/helm/charts/onyx/templates/celery-beat.yaml
index 49a72014cd8..eb8ef2eeafa 100644
--- a/deployment/helm/charts/onyx/templates/celery-beat.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-beat.yaml
@@ -1,4 +1,4 @@
-{{- if gt (int .Values.celery_beat.replicaCount) 0 }}
+{{- if and .Values.vectorDB.enabled (gt (int .Values.celery_beat.replicaCount) 0) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-heavy-hpa.yaml b/deployment/helm/charts/onyx/templates/celery-worker-heavy-hpa.yaml
index 832ef85686d..ca8924a9aa1 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-heavy-hpa.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-heavy-hpa.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_heavy.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_heavy.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-heavy-scaledobject.yaml b/deployment/helm/charts/onyx/templates/celery-worker-heavy-scaledobject.yaml
index d06fa2895ad..1d29781f11a 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-heavy-scaledobject.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-heavy-scaledobject.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_heavy.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_heavy.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: keda.sh/v1alpha1
 kind: ScaledObject
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml b/deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml
index 9a6877b5b0f..3b4b8bc46c8 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-heavy.yaml
@@ -1,4 +1,4 @@
-{{- if gt (int .Values.celery_worker_heavy.replicaCount) 0 }}
+{{- if and .Values.vectorDB.enabled (gt (int .Values.celery_worker_heavy.replicaCount) 0) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-light-hpa.yaml b/deployment/helm/charts/onyx/templates/celery-worker-light-hpa.yaml
index 8a9e06b297f..388cc5827c5 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-light-hpa.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-light-hpa.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_light.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_light.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-light-scaledobject.yaml b/deployment/helm/charts/onyx/templates/celery-worker-light-scaledobject.yaml
index 6bc1215eb6b..0897dd7f724 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-light-scaledobject.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-light-scaledobject.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_light.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_light.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: keda.sh/v1alpha1
 kind: ScaledObject
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-light.yaml b/deployment/helm/charts/onyx/templates/celery-worker-light.yaml
index 802be2607e6..db4d72cc392 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-light.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-light.yaml
@@ -1,4 +1,4 @@
-{{- if gt (int .Values.celery_worker_light.replicaCount) 0 }}
+{{- if and .Values.vectorDB.enabled (gt (int .Values.celery_worker_light.replicaCount) 0) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-monitoring-hpa.yaml b/deployment/helm/charts/onyx/templates/celery-worker-monitoring-hpa.yaml
index 60c487b0045..c5bc0ae4ac8 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-monitoring-hpa.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-monitoring-hpa.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_monitoring.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_monitoring.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-monitoring-scaledobject.yaml b/deployment/helm/charts/onyx/templates/celery-worker-monitoring-scaledobject.yaml
index f2870e5c2e1..61e53214365 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-monitoring-scaledobject.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-monitoring-scaledobject.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_monitoring.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_monitoring.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: keda.sh/v1alpha1
 kind: ScaledObject
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml b/deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml
index 203139ab6da..f1e6e3a20b4 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-monitoring.yaml
@@ -1,4 +1,4 @@
-{{- if gt (int .Values.celery_worker_monitoring.replicaCount) 0 }}
+{{- if and .Values.vectorDB.enabled (gt (int .Values.celery_worker_monitoring.replicaCount) 0) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-primary-hpa.yaml b/deployment/helm/charts/onyx/templates/celery-worker-primary-hpa.yaml
index 9902d137728..529efde05ab 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-primary-hpa.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-primary-hpa.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_primary.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_primary.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-primary-scaledobject.yaml b/deployment/helm/charts/onyx/templates/celery-worker-primary-scaledobject.yaml
index 464be55aa67..a6995f2224d 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-primary-scaledobject.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-primary-scaledobject.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_primary.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_primary.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: keda.sh/v1alpha1
 kind: ScaledObject
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-primary.yaml b/deployment/helm/charts/onyx/templates/celery-worker-primary.yaml
index 618a779a2c4..16260b44523 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-primary.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-primary.yaml
@@ -1,4 +1,4 @@
-{{- if gt (int .Values.celery_worker_primary.replicaCount) 0 }}
+{{- if and .Values.vectorDB.enabled (gt (int .Values.celery_worker_primary.replicaCount) 0) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-hpa.yaml b/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-hpa.yaml
index b04b85f37aa..81ea5e146ba 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-hpa.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-hpa.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_user_file_processing.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_user_file_processing.autoscaling.enabled) (ne (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-scaledobject.yaml b/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-scaledobject.yaml
index e380083038d..3d7e83bb79b 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-scaledobject.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing-scaledobject.yaml
@@ -1,4 +1,4 @@
-{{- if and (.Values.celery_worker_user_file_processing.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
+{{- if and .Values.vectorDB.enabled (.Values.celery_worker_user_file_processing.autoscaling.enabled) (eq (include "onyx.autoscaling.engine" .) "keda") }}
 apiVersion: keda.sh/v1alpha1
 kind: ScaledObject
 metadata:
diff --git a/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing.yaml b/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing.yaml
index 47209772265..9f837050e31 100644
--- a/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing.yaml
+++ b/deployment/helm/charts/onyx/templates/celery-worker-user-file-processing.yaml
@@ -1,4 +1,4 @@
-{{- if gt (int .Values.celery_worker_user_file_processing.replicaCount) 0 }}
+{{- if and .Values.vectorDB.enabled (gt (int .Values.celery_worker_user_file_processing.replicaCount) 0) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/deployment/helm/charts/onyx/values.yaml b/deployment/helm/charts/onyx/values.yaml
index cf6bd686f33..e4c602a3d05 100644
--- a/deployment/helm/charts/onyx/values.yaml
+++ b/deployment/helm/charts/onyx/values.yaml
@@ -28,7 +28,9 @@ postgresql:
 # -- Master toggle for vector database support. When false:
 #   - Sets DISABLE_VECTOR_DB=true on all backend pods
 #   - Skips the indexing model server deployment (embeddings not needed)
-#   - Skips docprocessing and docfetching celery workers
+#   - Skips ALL celery worker deployments (beat, primary, light, heavy,
+#     monitoring, user-file-processing, docprocessing, docfetching) — the
+#     API server handles background work via FastAPI BackgroundTasks
 #   - You should also set vespa.enabled=false and opensearch.enabled=false
 #     to prevent those subcharts from deploying
 vectorDB:

From fd322a8a10d6c7ee78d554c0ae11efb64041c73e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 2 Mar 2026 20:03:36 +0000
Subject: [PATCH 017/267] chore(deps): bump lxml-html-clean from 0.4.3 to 0.4.4
 (#8919)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt | 2 +-
 uv.lock                          | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 799d2ac3bae..438e56bde09 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -528,7 +528,7 @@ lxml==5.3.0
     #   unstructured
     #   xmlsec
     #   zeep
-lxml-html-clean==0.4.3
+lxml-html-clean==0.4.4
     # via lxml
 magika==0.6.3
     # via markitdown
diff --git a/uv.lock b/uv.lock
index 82a6c50d14f..5848b04425a 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3426,14 +3426,14 @@ html-clean = [
 
 [[package]]
 name = "lxml-html-clean"
-version = "0.4.3"
+version = "0.4.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "lxml" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d9/cb/c9c5bb2a9c47292e236a808dd233a03531f53b626f36259dcd32b49c76da/lxml_html_clean-0.4.3.tar.gz", hash = "sha256:c9df91925b00f836c807beab127aac82575110eacff54d0a75187914f1bd9d8c", size = 21498, upload-time = "2025-10-02T20:49:24.895Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/9a/a4/5c62acfacd69ff4f5db395100f5cfb9b54e7ac8c69a235e4e939fd13f021/lxml_html_clean-0.4.4.tar.gz", hash = "sha256:58f39a9d632711202ed1d6d0b9b47a904e306c85de5761543b90e3e3f736acfb", size = 23899, upload-time = "2026-02-27T09:35:52.911Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/10/4a/63a9540e3ca73709f4200564a737d63a4c8c9c4dd032bab8535f507c190a/lxml_html_clean-0.4.3-py3-none-any.whl", hash = "sha256:63fd7b0b9c3a2e4176611c2ca5d61c4c07ffca2de76c14059a81a2825833731e", size = 14177, upload-time = "2025-10-02T20:49:23.749Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/76/7ffc1d3005cf7749123bc47cb3ea343cd97b0ac2211bab40f57283577d0e/lxml_html_clean-0.4.4-py3-none-any.whl", hash = "sha256:ce2ef506614ecb85ee1c5fe0a2aa45b06a19514ec7949e9c8f34f06925cfabcb", size = 14565, upload-time = "2026-02-27T09:35:51.86Z" },
 ]
 
 [[package]]

From 897e181d677457cb8ca804cdd95c5b874f5cc6a9 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 2 Mar 2026 12:04:35 -0800
Subject: [PATCH 018/267] refactor(opal): update `ModalHeader` to use `Content`
 (#8885)

---
 web/src/refresh-components/Modal.tsx          | 100 +++++++++---------
 web/tests/e2e/chat/file_preview_modal.spec.ts |  14 ++-
 2 files changed, 62 insertions(+), 52 deletions(-)

diff --git a/web/src/refresh-components/Modal.tsx b/web/src/refresh-components/Modal.tsx
index 2f7f15b2000..30244982591 100644
--- a/web/src/refresh-components/Modal.tsx
+++ b/web/src/refresh-components/Modal.tsx
@@ -3,9 +3,9 @@
 import React from "react";
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { cn } from "@/lib/utils";
-import type { IconProps } from "@opal/types";
-import Text from "@/refresh-components/texts/Text";
+import type { IconFunctionComponent } from "@opal/types";
 import { Button } from "@opal/components";
+import { Content } from "@opal/layouts";
 import { SvgX } from "@opal/icons";
 import { WithoutStyles } from "@/types";
 import { Section, SectionProps } from "@/layouts/general-layouts";
@@ -407,17 +407,29 @@ ModalContent.displayName = DialogPrimitive.Content.displayName;
  * ```
  */
 interface ModalHeaderProps extends WithoutStyles<SectionProps> {
-  icon?: React.FunctionComponent<IconProps>;
+  icon?: IconFunctionComponent;
+  moreIcon1?: IconFunctionComponent;
+  moreIcon2?: IconFunctionComponent;
   title: string;
   description?: string;
   onClose?: () => void;
 }
 const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
-  ({ icon: Icon, title, description, onClose, children, ...props }, ref) => {
+  (
+    {
+      icon,
+      moreIcon1,
+      moreIcon2,
+      title,
+      description,
+      onClose,
+      children,
+      ...props
+    },
+    ref
+  ) => {
     const { closeButtonRef, setHasDescription } = useModalContext();
 
-    // useLayoutEffect ensures aria-describedby is set before paint,
-    // so screen readers announce the description when the dialog opens
     React.useLayoutEffect(() => {
       setHasDescription(!!description);
     }, [description, setHasDescription]);
@@ -440,52 +452,40 @@ const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
 
     return (
       <Section ref={ref} padding={1} alignItems="start" height="fit" {...props}>
-        <Section gap={0.5}>
-          {Icon && (
-            <Section
-              gap={0}
-              padding={0}
-              flexDirection="row"
-              justifyContent="between"
-            >
-              {/*
-                The `h-[1.5rem]` and `w-[1.5rem]` were added as backups here.
-                However, prop-resolution technically resolves to choosing classNames over size props, so technically the `size={24}` is the backup.
-                We specify both to be safe.
-
-                # Note
-                1.5rem === 24px
-              */}
-              <Icon
-                className="stroke-text-04 h-[1.5rem] w-[1.5rem]"
-                size={24}
-              />
-              {closeButton}
-            </Section>
-          )}
-
-          <Section
-            alignItems="start"
-            gap={0}
-            padding={0}
-            flexDirection="row"
-            justifyContent="between"
-          >
-            <Section alignItems="start" padding={0} gap={0}>
-              <DialogPrimitive.Title asChild>
-                <Text headingH3>{title}</Text>
-              </DialogPrimitive.Title>
-              {description && (
-                <DialogPrimitive.Description asChild>
-                  <Text secondaryBody text03>
+        <Section
+          flexDirection="row"
+          justifyContent="between"
+          alignItems="start"
+          gap={0}
+          padding={0}
+        >
+          <div className="relative w-full">
+            {/* Close button is absolutely positioned because:
+               1. Figma mocks place it overlapping the top-right of the content area
+               2. Using ContentAction with rightChildren causes the description
+                  to wrap to the second line early due to the button reserving space */}
+            <div className="absolute top-0 right-0">{closeButton}</div>
+            <DialogPrimitive.Title asChild>
+              <div>
+                <Content
+                  icon={icon}
+                  moreIcon1={moreIcon1}
+                  moreIcon2={moreIcon2}
+                  title={title}
+                  description={description}
+                  sizePreset="section"
+                  variant="heading"
+                />
+                {description && (
+                  <DialogPrimitive.Description className="hidden">
                     {description}
-                  </Text>
-                </DialogPrimitive.Description>
-              )}
-            </Section>
-            {!Icon && closeButton}
-          </Section>
+                  </DialogPrimitive.Description>
+                )}
+              </div>
+            </DialogPrimitive.Title>
+          </div>
         </Section>
+
         {children}
       </Section>
     );
diff --git a/web/tests/e2e/chat/file_preview_modal.spec.ts b/web/tests/e2e/chat/file_preview_modal.spec.ts
index 69eb88aab27..9db6dce2bd3 100644
--- a/web/tests/e2e/chat/file_preview_modal.spec.ts
+++ b/web/tests/e2e/chat/file_preview_modal.spec.ts
@@ -181,8 +181,18 @@ test.describe("File preview modal from chat file links", () => {
     await expect(modal.getByText("app.py")).toBeVisible();
 
     // Verify the header description shows language and line info
-    await expect(modal.getByText(/python/i)).toBeVisible();
-    await expect(modal.getByText("2 lines", { exact: true })).toBeVisible();
+    await expect(
+      modal
+        .locator("div")
+        .filter({ hasText: /python/i })
+        .first()
+    ).toBeVisible();
+    await expect(
+      modal
+        .locator("div")
+        .filter({ hasText: /2 lines/ })
+        .first()
+    ).toBeVisible();
 
     // Verify the code content is rendered
     await expect(modal.getByText("Hello, world!")).toBeVisible();

From 580d41dc23427d8a5d424dbbe6384fdcd30e3c4c Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 12:04:54 -0800
Subject: [PATCH 019/267] chore(mypy): run from repro root in CI (#6995)

---
 .github/workflows/pr-python-checks.yml       | 21 ++++++------
 backend/pyproject.toml                       | 34 --------------------
 pyproject.toml                               | 34 ++++++++++++++++++++
 tools/ods/internal/openapi/openapi_schema.py |  2 +-
 4 files changed, 45 insertions(+), 46 deletions(-)

diff --git a/.github/workflows/pr-python-checks.yml b/.github/workflows/pr-python-checks.yml
index a9f95d985af..b1289f51b2d 100644
--- a/.github/workflows/pr-python-checks.yml
+++ b/.github/workflows/pr-python-checks.yml
@@ -8,7 +8,7 @@ on:
   pull_request:
     branches:
       - main
-      - 'release/**'
+      - "release/**"
   push:
     tags:
       - "v*.*.*"
@@ -21,7 +21,13 @@ jobs:
     # See https://runs-on.com/runners/linux/
     # Note: Mypy seems quite optimized for x64 compared to arm64.
     # Similarly, mypy is single-threaded and incremental, so 2cpu is sufficient.
-    runs-on: [runs-on, runner=2cpu-linux-x64, "run-id=${{ github.run_id }}-mypy-check", "extras=s3-cache"]
+    runs-on:
+      [
+        runs-on,
+        runner=2cpu-linux-x64,
+        "run-id=${{ github.run_id }}-mypy-check",
+        "extras=s3-cache",
+      ]
     timeout-minutes: 45
 
     steps:
@@ -52,21 +58,14 @@ jobs:
         if: ${{ vars.DISABLE_MYPY_CACHE != 'true' }}
         uses: runs-on/cache@50350ad4242587b6c8c2baa2e740b1bc11285ff4 # ratchet:runs-on/cache@v4
         with:
-          path: backend/.mypy_cache
-          key: mypy-${{ runner.os }}-${{ github.base_ref || github.event.merge_group.base_ref || 'main' }}-${{ hashFiles('**/*.py', '**/*.pyi', 'backend/pyproject.toml') }}
+          path: .mypy_cache
+          key: mypy-${{ runner.os }}-${{ github.base_ref || github.event.merge_group.base_ref || 'main' }}-${{ hashFiles('**/*.py', '**/*.pyi', 'pyproject.toml') }}
           restore-keys: |
             mypy-${{ runner.os }}-${{ github.base_ref || github.event.merge_group.base_ref || 'main' }}-
             mypy-${{ runner.os }}-
 
       - name: Run MyPy
-        working-directory: ./backend
         env:
           MYPY_FORCE_COLOR: 1
           TERM: xterm-256color
         run: mypy .
-
-      - name: Run MyPy (tools/)
-        env:
-          MYPY_FORCE_COLOR: 1
-          TERM: xterm-256color
-        run: mypy tools/
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 56069c8f064..8a1b00b3e61 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -8,37 +8,3 @@ dependencies = [
 
 [tool.uv.sources]
 onyx = { workspace = true }
-
-[tool.mypy]
-plugins = "sqlalchemy.ext.mypy.plugin"
-mypy_path = "backend"
-explicit_package_bases = true
-disallow_untyped_defs = true
-warn_unused_ignores = true
-enable_error_code = ["possibly-undefined"]
-strict_equality = true
-# Patterns match paths whether mypy is run from backend/ (CI) or repo root (e.g. VS Code extension with target ./backend)
-exclude = [
-  "(?:^|/)generated/",
-  "(?:^|/)\\.venv/",
-  "(?:^|/)onyx/server/features/build/sandbox/kubernetes/docker/skills/",
-  "(?:^|/)onyx/server/features/build/sandbox/kubernetes/docker/templates/",
-]
-
-[[tool.mypy.overrides]]
-module = "alembic.versions.*"
-disable_error_code = ["var-annotated"]
-
-[[tool.mypy.overrides]]
-module = "alembic_tenants.versions.*"
-disable_error_code = ["var-annotated"]
-
-[[tool.mypy.overrides]]
-module = "generated.*"
-follow_imports = "silent"
-ignore_errors = true
-
-[[tool.mypy.overrides]]
-module = "transformers.*"
-follow_imports = "skip"
-ignore_errors = true
diff --git a/pyproject.toml b/pyproject.toml
index 9338f290c81..203a85c9eb7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -191,6 +191,40 @@ model_server = [
     "sentry-sdk[fastapi,celery,starlette]==2.14.0",
 ]
 
+[tool.mypy]
+plugins = "sqlalchemy.ext.mypy.plugin"
+mypy_path = "backend"
+explicit_package_bases = true
+disallow_untyped_defs = true
+warn_unused_ignores = true
+enable_error_code = ["possibly-undefined"]
+strict_equality = true
+# Patterns match paths whether mypy is run from backend/ (CI) or repo root (e.g. VS Code extension with target ./backend)
+exclude = [
+  "(?:^|/)generated/",
+  "(?:^|/)\\.venv/",
+  "(?:^|/)onyx/server/features/build/sandbox/kubernetes/docker/skills/",
+  "(?:^|/)onyx/server/features/build/sandbox/kubernetes/docker/templates/",
+]
+
+[[tool.mypy.overrides]]
+module = "alembic.versions.*"
+disable_error_code = ["var-annotated"]
+
+[[tool.mypy.overrides]]
+module = "alembic_tenants.versions.*"
+disable_error_code = ["var-annotated"]
+
+[[tool.mypy.overrides]]
+module = "generated.*"
+follow_imports = "silent"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "transformers.*"
+follow_imports = "skip"
+ignore_errors = true
+
 [tool.uv.workspace]
 members = ["backend", "tools/ods"]
 
diff --git a/tools/ods/internal/openapi/openapi_schema.py b/tools/ods/internal/openapi/openapi_schema.py
index ff0775343b3..a01f0d39513 100644
--- a/tools/ods/internal/openapi/openapi_schema.py
+++ b/tools/ods/internal/openapi/openapi_schema.py
@@ -33,7 +33,7 @@ def generate_schema(output_path: str, tagged_for_docs: str | None = None) -> boo
     try:
         # Import here to avoid requiring backend dependencies when not generating schema
         from fastapi.openapi.utils import get_openapi
-        from onyx.main import app as app_fn  # type: ignore
+        from onyx.main import app as app_fn
     except ImportError as e:
         print(f"Error: Failed to import required modules: {e}", file=sys.stderr)
         print(

From 4f3c54f282c29e403d474daabbf3c9fde26ee4fc Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 12:10:21 -0800
Subject: [PATCH 020/267] chore(playwright): hide actions toolbar buttons in
 screenshots (#8914)

---
 web/src/sections/input/AppInputBar.tsx  | 1 +
 web/tests/e2e/utils/visualRegression.ts | 6 +++++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index 831aac93544..3ab7e96699b 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -705,6 +705,7 @@ const AppInputBar = React.memo(
 
                 {/* Controls that load in when data is ready */}
                 <div
+                  data-testid="actions-container"
                   className={cn(
                     "flex flex-row items-center",
                     controlsLoading && "invisible"
diff --git a/web/tests/e2e/utils/visualRegression.ts b/web/tests/e2e/utils/visualRegression.ts
index 9ec94dc73ab..cedaab91850 100644
--- a/web/tests/e2e/utils/visualRegression.ts
+++ b/web/tests/e2e/utils/visualRegression.ts
@@ -29,7 +29,11 @@ const DEFAULT_MASK_SELECTORS: string[] = [
  * Default selectors to hide (visibility: hidden) across all screenshots.
  * These elements are overlays or ephemeral UI that would cause spurious diffs.
  */
-const DEFAULT_HIDE_SELECTORS: string[] = ['[data-testid="toast-container"]'];
+const DEFAULT_HIDE_SELECTORS: string[] = [
+  '[data-testid="toast-container"]',
+  // TODO: Remove once it loads consistently.
+  '[data-testid="actions-container"]',
+];
 
 interface ScreenshotOptions {
   /**

From 30704f427fbb45a0ec751c2c87c08acb6358b36d Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Mon, 2 Mar 2026 12:50:13 -0800
Subject: [PATCH 021/267] refactor: add abstraction for cache backend (#8870)

---
 backend/onyx/cache/factory.py       | 45 ++++++++++++++
 backend/onyx/cache/interface.py     | 89 ++++++++++++++++++++++++++++
 backend/onyx/cache/redis_backend.py | 92 +++++++++++++++++++++++++++++
 backend/onyx/configs/app_configs.py |  7 +++
 backend/onyx/main.py                | 17 ++++++
 5 files changed, 250 insertions(+)
 create mode 100644 backend/onyx/cache/factory.py
 create mode 100644 backend/onyx/cache/interface.py
 create mode 100644 backend/onyx/cache/redis_backend.py

diff --git a/backend/onyx/cache/factory.py b/backend/onyx/cache/factory.py
new file mode 100644
index 00000000000..02a231ac719
--- /dev/null
+++ b/backend/onyx/cache/factory.py
@@ -0,0 +1,45 @@
+from collections.abc import Callable
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.interface import CacheBackendType
+from onyx.configs.app_configs import CACHE_BACKEND
+
+
+def _build_redis_backend(tenant_id: str) -> CacheBackend:
+    from onyx.cache.redis_backend import RedisCacheBackend
+    from onyx.redis.redis_pool import redis_pool
+
+    return RedisCacheBackend(redis_pool.get_client(tenant_id))
+
+
+_BACKEND_BUILDERS: dict[CacheBackendType, Callable[[str], CacheBackend]] = {
+    CacheBackendType.REDIS: _build_redis_backend,
+    # CacheBackendType.POSTGRES will be added in a follow-up PR.
+}
+
+
+def get_cache_backend(*, tenant_id: str | None = None) -> CacheBackend:
+    """Return a tenant-aware ``CacheBackend``.
+
+    If *tenant_id* is ``None``, the current tenant is read from the
+    thread-local context variable (same behaviour as ``get_redis_client``).
+    """
+    if tenant_id is None:
+        from shared_configs.contextvars import get_current_tenant_id
+
+        tenant_id = get_current_tenant_id()
+
+    builder = _BACKEND_BUILDERS.get(CACHE_BACKEND)
+    if builder is None:
+        raise ValueError(
+            f"Unsupported CACHE_BACKEND={CACHE_BACKEND!r}. "
+            f"Supported values: {[t.value for t in CacheBackendType]}"
+        )
+    return builder(tenant_id)
+
+
+def get_shared_cache_backend() -> CacheBackend:
+    """Return a ``CacheBackend`` in the shared (cross-tenant) namespace."""
+    from shared_configs.configs import DEFAULT_REDIS_PREFIX
+
+    return get_cache_backend(tenant_id=DEFAULT_REDIS_PREFIX)
diff --git a/backend/onyx/cache/interface.py b/backend/onyx/cache/interface.py
new file mode 100644
index 00000000000..3f19781d2b7
--- /dev/null
+++ b/backend/onyx/cache/interface.py
@@ -0,0 +1,89 @@
+import abc
+from enum import Enum
+
+
+class CacheBackendType(str, Enum):
+    REDIS = "redis"
+    POSTGRES = "postgres"
+
+
+class CacheLock(abc.ABC):
+    """Abstract distributed lock returned by CacheBackend.lock()."""
+
+    @abc.abstractmethod
+    def acquire(
+        self,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def release(self) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def owned(self) -> bool:
+        raise NotImplementedError
+
+
+class CacheBackend(abc.ABC):
+    """Thin abstraction over a key-value cache with TTL, locks, and blocking lists.
+
+    Covers the subset of Redis operations used outside of Celery. When
+    CACHE_BACKEND=postgres, a PostgreSQL-backed implementation is used instead.
+    """
+
+    # -- basic key/value ---------------------------------------------------
+
+    @abc.abstractmethod
+    def get(self, key: str) -> bytes | None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def set(
+        self,
+        key: str,
+        value: str | bytes | int | float,
+        ex: int | None = None,
+    ) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def delete(self, key: str) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def exists(self, key: str) -> bool:
+        raise NotImplementedError
+
+    # -- TTL ---------------------------------------------------------------
+
+    @abc.abstractmethod
+    def expire(self, key: str, seconds: int) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def ttl(self, key: str) -> int:
+        """Return remaining TTL in seconds. -1 if no expiry, -2 if key missing."""
+        raise NotImplementedError
+
+    # -- distributed lock --------------------------------------------------
+
+    @abc.abstractmethod
+    def lock(self, name: str, timeout: float | None = None) -> CacheLock:
+        raise NotImplementedError
+
+    # -- blocking list (used by MCP OAuth BLPOP pattern) -------------------
+
+    @abc.abstractmethod
+    def rpush(self, key: str, value: str | bytes) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def blpop(self, keys: list[str], timeout: int = 0) -> tuple[bytes, bytes] | None:
+        """Block until a value is available on one of *keys*, or *timeout* expires.
+
+        Returns ``(key, value)`` or ``None`` on timeout.
+        """
+        raise NotImplementedError
diff --git a/backend/onyx/cache/redis_backend.py b/backend/onyx/cache/redis_backend.py
new file mode 100644
index 00000000000..6730307aee6
--- /dev/null
+++ b/backend/onyx/cache/redis_backend.py
@@ -0,0 +1,92 @@
+from typing import cast
+
+from redis.client import Redis
+from redis.lock import Lock as RedisLock
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.interface import CacheLock
+
+
+class RedisCacheLock(CacheLock):
+    """Wraps ``redis.lock.Lock`` behind the ``CacheLock`` interface."""
+
+    def __init__(self, lock: RedisLock) -> None:
+        self._lock = lock
+
+    def acquire(
+        self,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> bool:
+        return bool(
+            self._lock.acquire(
+                blocking=blocking,
+                blocking_timeout=blocking_timeout,
+            )
+        )
+
+    def release(self) -> None:
+        self._lock.release()
+
+    def owned(self) -> bool:
+        return bool(self._lock.owned())
+
+
+class RedisCacheBackend(CacheBackend):
+    """``CacheBackend`` implementation that delegates to a ``redis.Redis`` client.
+
+    This is a thin pass-through — every method maps 1-to-1 to the underlying
+    Redis command.  ``TenantRedis`` key-prefixing is handled by the client
+    itself (provided by ``get_redis_client``).
+    """
+
+    def __init__(self, redis_client: Redis) -> None:
+        self._r = redis_client
+
+    # -- basic key/value ---------------------------------------------------
+
+    def get(self, key: str) -> bytes | None:
+        val = self._r.get(key)
+        if val is None:
+            return None
+        if isinstance(val, bytes):
+            return val
+        return str(val).encode()
+
+    def set(
+        self,
+        key: str,
+        value: str | bytes | int | float,
+        ex: int | None = None,
+    ) -> None:
+        self._r.set(key, value, ex=ex)
+
+    def delete(self, key: str) -> None:
+        self._r.delete(key)
+
+    def exists(self, key: str) -> bool:
+        return bool(self._r.exists(key))
+
+    # -- TTL ---------------------------------------------------------------
+
+    def expire(self, key: str, seconds: int) -> None:
+        self._r.expire(key, seconds)
+
+    def ttl(self, key: str) -> int:
+        return cast(int, self._r.ttl(key))
+
+    # -- distributed lock --------------------------------------------------
+
+    def lock(self, name: str, timeout: float | None = None) -> CacheLock:
+        return RedisCacheLock(self._r.lock(name, timeout=timeout))
+
+    # -- blocking list (MCP OAuth BLPOP pattern) ---------------------------
+
+    def rpush(self, key: str, value: str | bytes) -> None:
+        self._r.rpush(key, value)
+
+    def blpop(self, keys: list[str], timeout: int = 0) -> tuple[bytes, bytes] | None:
+        result = cast(list[bytes] | None, self._r.blpop(keys, timeout=timeout))
+        if result is None:
+            return None
+        return (result[0], result[1])
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 7f54659192c..67e89b0eff0 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -6,6 +6,7 @@
 from typing import cast
 
 from onyx.auth.schemas import AuthBackend
+from onyx.cache.interface import CacheBackendType
 from onyx.configs.constants import AuthType
 from onyx.configs.constants import QueryHistoryType
 from onyx.file_processing.enums import HtmlBasedConnectorTransformLinksStrategy
@@ -54,6 +55,12 @@
 # are disabled but core chat, tools, user file uploads, and Projects still work.
 DISABLE_VECTOR_DB = os.environ.get("DISABLE_VECTOR_DB", "").lower() == "true"
 
+# Which backend to use for caching, locks, and ephemeral state.
+# "redis" (default) or "postgres" (only valid when DISABLE_VECTOR_DB=true).
+CACHE_BACKEND = CacheBackendType(
+    os.environ.get("CACHE_BACKEND", CacheBackendType.REDIS)
+)
+
 # Maximum token count for a single uploaded file. Files exceeding this are rejected.
 # Defaults to 100k tokens (or 10M when vector DB is disabled).
 _DEFAULT_FILE_TOKEN_LIMIT = 10_000_000 if DISABLE_VECTOR_DB else 100_000
diff --git a/backend/onyx/main.py b/backend/onyx/main.py
index 2b692abb0d9..078e11652b5 100644
--- a/backend/onyx/main.py
+++ b/backend/onyx/main.py
@@ -32,11 +32,13 @@
 from onyx.auth.users import auth_backend
 from onyx.auth.users import create_onyx_oauth_router
 from onyx.auth.users import fastapi_users
+from onyx.cache.interface import CacheBackendType
 from onyx.configs.app_configs import APP_API_PREFIX
 from onyx.configs.app_configs import APP_HOST
 from onyx.configs.app_configs import APP_PORT
 from onyx.configs.app_configs import AUTH_RATE_LIMITING_ENABLED
 from onyx.configs.app_configs import AUTH_TYPE
+from onyx.configs.app_configs import CACHE_BACKEND
 from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.configs.app_configs import LOG_ENDPOINT_LATENCY
 from onyx.configs.app_configs import OAUTH_CLIENT_ID
@@ -255,6 +257,20 @@ def include_auth_router_with_prefix(
     )
 
 
+def validate_cache_backend_settings() -> None:
+    """Validate that CACHE_BACKEND=postgres is only used with DISABLE_VECTOR_DB.
+
+    The Postgres cache backend eliminates the Redis dependency, but only works
+    when Celery is not running (which requires DISABLE_VECTOR_DB=true).
+    """
+    if CACHE_BACKEND == CacheBackendType.POSTGRES and not DISABLE_VECTOR_DB:
+        raise RuntimeError(
+            "CACHE_BACKEND=postgres requires DISABLE_VECTOR_DB=true. "
+            "The Postgres cache backend is only supported in no-vector-DB "
+            "deployments where Celery is replaced by the in-process task runner."
+        )
+
+
 def validate_no_vector_db_settings() -> None:
     """Validate that DISABLE_VECTOR_DB is not combined with incompatible settings.
 
@@ -286,6 +302,7 @@ def validate_no_vector_db_settings() -> None:
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:  # noqa: ARG001
     validate_no_vector_db_settings()
+    validate_cache_backend_settings()
 
     # Set recursion limit
     if SYSTEM_RECURSION_LIMIT is not None:

From 13d60dcb0e98393cf54651ab8b13e8a457964361 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 12:51:59 -0800
Subject: [PATCH 022/267] test(scim): add integration tests for SCIM group CRUD
 (#8830)

---
 .../tests/scim/test_scim_groups.py            | 552 ++++++++++++++++++
 1 file changed, 552 insertions(+)
 create mode 100644 backend/tests/integration/tests/scim/test_scim_groups.py

diff --git a/backend/tests/integration/tests/scim/test_scim_groups.py b/backend/tests/integration/tests/scim/test_scim_groups.py
new file mode 100644
index 00000000000..03b8b8e576d
--- /dev/null
+++ b/backend/tests/integration/tests/scim/test_scim_groups.py
@@ -0,0 +1,552 @@
+"""Integration tests for SCIM group provisioning endpoints.
+
+Covers the full group lifecycle as driven by an IdP (Okta / Azure AD):
+1. Create a group via POST /Groups
+2. Retrieve a group via GET /Groups/{id}
+3. List, filter, and paginate groups via GET /Groups
+4. Replace a group via PUT /Groups/{id}
+5. Patch a group (add/remove members, rename) via PATCH /Groups/{id}
+6. Delete a group via DELETE /Groups/{id}
+7. Error cases: duplicate name, not-found, invalid member IDs
+
+All tests are parameterized across IdP request styles (Okta sends lowercase
+PATCH ops; Entra sends capitalized ops like ``"Replace"``). The server
+normalizes both — these tests verify that.
+
+Auth tests live in test_scim_tokens.py.
+User lifecycle tests live in test_scim_users.py.
+"""
+
+import pytest
+import requests
+
+from onyx.auth.schemas import UserRole
+from tests.integration.common_utils.managers.scim_client import ScimClient
+from tests.integration.common_utils.managers.scim_token import ScimTokenManager
+
+
+SCIM_GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group"
+SCIM_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
+SCIM_PATCH_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
+
+
+@pytest.fixture(scope="module", params=["okta", "entra"])
+def idp_style(request: pytest.FixtureRequest) -> str:
+    """Parameterized IdP style — runs every test with both Okta and Entra request formats."""
+    return request.param
+
+
+@pytest.fixture(scope="module")
+def scim_token(idp_style: str) -> str:
+    """Create a single SCIM token shared across all tests in this module.
+
+    Creating a new token revokes the previous one, so we create exactly once
+    per IdP-style run and reuse. Uses UserManager directly to avoid
+    fixture-scope conflicts with the function-scoped admin_user fixture.
+    """
+    from tests.integration.common_utils.constants import ADMIN_USER_NAME
+    from tests.integration.common_utils.constants import GENERAL_HEADERS
+    from tests.integration.common_utils.managers.user import build_email
+    from tests.integration.common_utils.managers.user import DEFAULT_PASSWORD
+    from tests.integration.common_utils.managers.user import UserManager
+    from tests.integration.common_utils.test_models import DATestUser
+
+    try:
+        admin = UserManager.create(name=ADMIN_USER_NAME)
+    except Exception:
+        admin = UserManager.login_as_user(
+            DATestUser(
+                id="",
+                email=build_email(ADMIN_USER_NAME),
+                password=DEFAULT_PASSWORD,
+                headers=GENERAL_HEADERS,
+                role=UserRole.ADMIN,
+                is_active=True,
+            )
+        )
+
+    token = ScimTokenManager.create(
+        name=f"scim-group-tests-{idp_style}",
+        user_performing_action=admin,
+    ).raw_token
+    assert token is not None
+    return token
+
+
+def _make_group_resource(
+    display_name: str,
+    external_id: str | None = None,
+    members: list[dict] | None = None,
+) -> dict:
+    """Build a minimal SCIM GroupResource payload."""
+    resource: dict = {
+        "schemas": [SCIM_GROUP_SCHEMA],
+        "displayName": display_name,
+    }
+    if external_id is not None:
+        resource["externalId"] = external_id
+    if members is not None:
+        resource["members"] = members
+    return resource
+
+
+def _make_user_resource(email: str, external_id: str) -> dict:
+    """Build a minimal SCIM UserResource payload for member creation."""
+    return {
+        "schemas": [SCIM_USER_SCHEMA],
+        "userName": email,
+        "externalId": external_id,
+        "name": {"givenName": "Test", "familyName": "User"},
+        "active": True,
+    }
+
+
+def _make_patch_request(operations: list[dict], idp_style: str = "okta") -> dict:
+    """Build a SCIM PatchOp payload, applying IdP-specific operation casing.
+
+    Entra sends capitalized operations (e.g. ``"Replace"`` instead of
+    ``"replace"``). The server's ``normalize_operation`` validator lowercases
+    them — these tests verify that both casings are accepted.
+    """
+    cased_operations = []
+    for operation in operations:
+        cased = dict(operation)
+        if idp_style == "entra":
+            cased["op"] = operation["op"].capitalize()
+        cased_operations.append(cased)
+    return {
+        "schemas": [SCIM_PATCH_SCHEMA],
+        "Operations": cased_operations,
+    }
+
+
+def _create_scim_user(token: str, email: str, external_id: str) -> requests.Response:
+    return ScimClient.post(
+        "/Users", token, json=_make_user_resource(email, external_id)
+    )
+
+
+def _create_scim_group(
+    token: str,
+    display_name: str,
+    external_id: str | None = None,
+    members: list[dict] | None = None,
+) -> requests.Response:
+    return ScimClient.post(
+        "/Groups",
+        token,
+        json=_make_group_resource(display_name, external_id, members),
+    )
+
+
+# ------------------------------------------------------------------
+# Lifecycle: create → get → list → replace → patch → delete
+# ------------------------------------------------------------------
+
+
+def test_create_group(scim_token: str, idp_style: str) -> None:
+    """POST /Groups creates a group and returns 201."""
+    name = f"Engineering {idp_style}"
+    resp = _create_scim_group(scim_token, name, external_id=f"ext-eng-{idp_style}")
+    assert resp.status_code == 201
+
+    body = resp.json()
+    assert body["displayName"] == name
+    assert body["externalId"] == f"ext-eng-{idp_style}"
+    assert body["id"]  # integer ID assigned by server
+    assert body["meta"]["resourceType"] == "Group"
+
+
+def test_create_group_with_members(scim_token: str, idp_style: str) -> None:
+    """POST /Groups with members populates the member list."""
+    user = _create_scim_user(
+        scim_token, f"grp_member1_{idp_style}@example.com", f"ext-gm-{idp_style}"
+    ).json()
+
+    resp = _create_scim_group(
+        scim_token,
+        f"Backend Team {idp_style}",
+        external_id=f"ext-backend-{idp_style}",
+        members=[{"value": user["id"]}],
+    )
+    assert resp.status_code == 201
+
+    body = resp.json()
+    member_ids = [m["value"] for m in body["members"]]
+    assert user["id"] in member_ids
+
+
+def test_get_group(scim_token: str, idp_style: str) -> None:
+    """GET /Groups/{id} returns the group resource including members."""
+    user = _create_scim_user(
+        scim_token, f"grp_get_m_{idp_style}@example.com", f"ext-ggm-{idp_style}"
+    ).json()
+    created = _create_scim_group(
+        scim_token,
+        f"Frontend Team {idp_style}",
+        external_id=f"ext-fe-{idp_style}",
+        members=[{"value": user["id"]}],
+    ).json()
+
+    resp = ScimClient.get(f"/Groups/{created['id']}", scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["id"] == created["id"]
+    assert body["displayName"] == f"Frontend Team {idp_style}"
+    assert body["externalId"] == f"ext-fe-{idp_style}"
+    member_ids = [m["value"] for m in body["members"]]
+    assert user["id"] in member_ids
+
+
+def test_list_groups(scim_token: str, idp_style: str) -> None:
+    """GET /Groups returns a ListResponse containing provisioned groups."""
+    name = f"DevOps Team {idp_style}"
+    _create_scim_group(scim_token, name, external_id=f"ext-devops-{idp_style}")
+
+    resp = ScimClient.get("/Groups", scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["totalResults"] >= 1
+    names = [r["displayName"] for r in body["Resources"]]
+    assert name in names
+
+
+def test_list_groups_pagination(scim_token: str, idp_style: str) -> None:
+    """GET /Groups with startIndex and count returns correct pagination."""
+    _create_scim_group(
+        scim_token, f"Page Group A {idp_style}", external_id=f"ext-page-a-{idp_style}"
+    )
+    _create_scim_group(
+        scim_token, f"Page Group B {idp_style}", external_id=f"ext-page-b-{idp_style}"
+    )
+
+    resp = ScimClient.get("/Groups?startIndex=1&count=1", scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["startIndex"] == 1
+    assert body["itemsPerPage"] == 1
+    assert body["totalResults"] >= 2
+    assert len(body["Resources"]) == 1
+
+
+def test_filter_groups_by_display_name(scim_token: str, idp_style: str) -> None:
+    """GET /Groups?filter=displayName eq '...' returns only matching groups."""
+    name = f"Unique QA Team {idp_style}"
+    _create_scim_group(scim_token, name, external_id=f"ext-qa-filter-{idp_style}")
+
+    resp = ScimClient.get(f'/Groups?filter=displayName eq "{name}"', scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["totalResults"] == 1
+    assert body["Resources"][0]["displayName"] == name
+
+
+def test_filter_groups_by_external_id(scim_token: str, idp_style: str) -> None:
+    """GET /Groups?filter=externalId eq '...' returns the matching group."""
+    ext_id = f"ext-unique-group-id-{idp_style}"
+    _create_scim_group(
+        scim_token, f"ExtId Filter Group {idp_style}", external_id=ext_id
+    )
+
+    resp = ScimClient.get(f'/Groups?filter=externalId eq "{ext_id}"', scim_token)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["totalResults"] == 1
+    assert body["Resources"][0]["externalId"] == ext_id
+
+
+def test_replace_group(scim_token: str, idp_style: str) -> None:
+    """PUT /Groups/{id} replaces the group resource."""
+    created = _create_scim_group(
+        scim_token,
+        f"Original Name {idp_style}",
+        external_id=f"ext-replace-g-{idp_style}",
+    ).json()
+
+    user = _create_scim_user(
+        scim_token, f"grp_replace_m_{idp_style}@example.com", f"ext-grm-{idp_style}"
+    ).json()
+
+    updated_resource = _make_group_resource(
+        display_name=f"Renamed Group {idp_style}",
+        external_id=f"ext-replace-g-{idp_style}",
+        members=[{"value": user["id"]}],
+    )
+    resp = ScimClient.put(f"/Groups/{created['id']}", scim_token, json=updated_resource)
+    assert resp.status_code == 200
+
+    body = resp.json()
+    assert body["displayName"] == f"Renamed Group {idp_style}"
+    member_ids = [m["value"] for m in body["members"]]
+    assert user["id"] in member_ids
+
+
+def test_replace_group_clears_members(scim_token: str, idp_style: str) -> None:
+    """PUT /Groups/{id} with empty members removes all memberships."""
+    user = _create_scim_user(
+        scim_token, f"grp_clear_m_{idp_style}@example.com", f"ext-gcm-{idp_style}"
+    ).json()
+    created = _create_scim_group(
+        scim_token,
+        f"Clear Members Group {idp_style}",
+        external_id=f"ext-clear-g-{idp_style}",
+        members=[{"value": user["id"]}],
+    ).json()
+
+    assert len(created["members"]) == 1
+
+    resp = ScimClient.put(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_group_resource(
+            f"Clear Members Group {idp_style}", f"ext-clear-g-{idp_style}", members=[]
+        ),
+    )
+    assert resp.status_code == 200
+    assert resp.json()["members"] == []
+
+
+def test_patch_add_member(scim_token: str, idp_style: str) -> None:
+    """PATCH /Groups/{id} with op=add adds a member."""
+    created = _create_scim_group(
+        scim_token,
+        f"Patch Add Group {idp_style}",
+        external_id=f"ext-patch-add-{idp_style}",
+    ).json()
+    user = _create_scim_user(
+        scim_token, f"grp_patch_add_{idp_style}@example.com", f"ext-gpa-{idp_style}"
+    ).json()
+
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "add", "path": "members", "value": [{"value": user["id"]}]}],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 200
+
+    member_ids = [m["value"] for m in resp.json()["members"]]
+    assert user["id"] in member_ids
+
+
+def test_patch_remove_member(scim_token: str, idp_style: str) -> None:
+    """PATCH /Groups/{id} with op=remove removes a specific member."""
+    user = _create_scim_user(
+        scim_token, f"grp_patch_rm_{idp_style}@example.com", f"ext-gpr-{idp_style}"
+    ).json()
+    created = _create_scim_group(
+        scim_token,
+        f"Patch Remove Group {idp_style}",
+        external_id=f"ext-patch-rm-{idp_style}",
+        members=[{"value": user["id"]}],
+    ).json()
+    assert len(created["members"]) == 1
+
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [
+                {
+                    "op": "remove",
+                    "path": f'members[value eq "{user["id"]}"]',
+                }
+            ],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 200
+    assert resp.json()["members"] == []
+
+
+def test_patch_replace_members(scim_token: str, idp_style: str) -> None:
+    """PATCH /Groups/{id} with op=replace on members swaps the entire list."""
+    user_a = _create_scim_user(
+        scim_token, f"grp_repl_a_{idp_style}@example.com", f"ext-gra-{idp_style}"
+    ).json()
+    user_b = _create_scim_user(
+        scim_token, f"grp_repl_b_{idp_style}@example.com", f"ext-grb-{idp_style}"
+    ).json()
+    created = _create_scim_group(
+        scim_token,
+        f"Patch Replace Group {idp_style}",
+        external_id=f"ext-patch-repl-{idp_style}",
+        members=[{"value": user_a["id"]}],
+    ).json()
+
+    # Replace member list: swap A for B
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [
+                {
+                    "op": "replace",
+                    "path": "members",
+                    "value": [{"value": user_b["id"]}],
+                }
+            ],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 200
+
+    member_ids = [m["value"] for m in resp.json()["members"]]
+    assert user_b["id"] in member_ids
+    assert user_a["id"] not in member_ids
+
+
+def test_patch_rename_group(scim_token: str, idp_style: str) -> None:
+    """PATCH /Groups/{id} with op=replace on displayName renames the group."""
+    created = _create_scim_group(
+        scim_token,
+        f"Old Group Name {idp_style}",
+        external_id=f"ext-rename-g-{idp_style}",
+    ).json()
+
+    new_name = f"New Group Name {idp_style}"
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "replace", "path": "displayName", "value": new_name}],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 200
+    assert resp.json()["displayName"] == new_name
+
+    # Confirm via GET
+    get_resp = ScimClient.get(f"/Groups/{created['id']}", scim_token)
+    assert get_resp.json()["displayName"] == new_name
+
+
+def test_delete_group(scim_token: str, idp_style: str) -> None:
+    """DELETE /Groups/{id} removes the group."""
+    created = _create_scim_group(
+        scim_token,
+        f"Delete Me Group {idp_style}",
+        external_id=f"ext-del-g-{idp_style}",
+    ).json()
+
+    resp = ScimClient.delete(f"/Groups/{created['id']}", scim_token)
+    assert resp.status_code == 204
+
+    # Second DELETE returns 404 (group hard-deleted)
+    resp2 = ScimClient.delete(f"/Groups/{created['id']}", scim_token)
+    assert resp2.status_code == 404
+
+
+def test_delete_group_preserves_members(scim_token: str, idp_style: str) -> None:
+    """DELETE /Groups/{id} removes memberships but does not deactivate users."""
+    user = _create_scim_user(
+        scim_token, f"grp_del_member_{idp_style}@example.com", f"ext-gdm-{idp_style}"
+    ).json()
+    created = _create_scim_group(
+        scim_token,
+        f"Delete With Members {idp_style}",
+        external_id=f"ext-del-wm-{idp_style}",
+        members=[{"value": user["id"]}],
+    ).json()
+
+    resp = ScimClient.delete(f"/Groups/{created['id']}", scim_token)
+    assert resp.status_code == 204
+
+    # User should still be active and retrievable
+    user_resp = ScimClient.get(f"/Users/{user['id']}", scim_token)
+    assert user_resp.status_code == 200
+    assert user_resp.json()["active"] is True
+
+
+# ------------------------------------------------------------------
+# Error cases
+# ------------------------------------------------------------------
+
+
+def test_create_group_duplicate_name(scim_token: str, idp_style: str) -> None:
+    """POST /Groups with an already-taken displayName returns 409."""
+    name = f"Dup Name Group {idp_style}"
+    resp1 = _create_scim_group(scim_token, name, external_id=f"ext-dup-g1-{idp_style}")
+    assert resp1.status_code == 201
+
+    resp2 = _create_scim_group(scim_token, name, external_id=f"ext-dup-g2-{idp_style}")
+    assert resp2.status_code == 409
+
+
+def test_get_nonexistent_group(scim_token: str) -> None:
+    """GET /Groups/{bad-id} returns 404."""
+    resp = ScimClient.get("/Groups/999999999", scim_token)
+    assert resp.status_code == 404
+
+
+def test_create_group_with_invalid_member(scim_token: str, idp_style: str) -> None:
+    """POST /Groups with a non-existent member UUID returns 400."""
+    resp = _create_scim_group(
+        scim_token,
+        f"Bad Member Group {idp_style}",
+        external_id=f"ext-bad-m-{idp_style}",
+        members=[{"value": "00000000-0000-0000-0000-000000000000"}],
+    )
+    assert resp.status_code == 400
+    assert "not found" in resp.json()["detail"].lower()
+
+
+def test_patch_add_nonexistent_member(scim_token: str, idp_style: str) -> None:
+    """PATCH /Groups/{id} adding a non-existent member returns 400."""
+    created = _create_scim_group(
+        scim_token,
+        f"Patch Bad Member Group {idp_style}",
+        external_id=f"ext-pbm-{idp_style}",
+    ).json()
+
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [
+                {
+                    "op": "add",
+                    "path": "members",
+                    "value": [{"value": "00000000-0000-0000-0000-000000000000"}],
+                }
+            ],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 400
+    assert "not found" in resp.json()["detail"].lower()
+
+
+def test_patch_add_duplicate_member_is_idempotent(
+    scim_token: str, idp_style: str
+) -> None:
+    """PATCH /Groups/{id} adding an already-present member succeeds silently."""
+    user = _create_scim_user(
+        scim_token, f"grp_dup_add_{idp_style}@example.com", f"ext-gda-{idp_style}"
+    ).json()
+    created = _create_scim_group(
+        scim_token,
+        f"Idempotent Add Group {idp_style}",
+        external_id=f"ext-idem-g-{idp_style}",
+        members=[{"value": user["id"]}],
+    ).json()
+    assert len(created["members"]) == 1
+
+    # Add same member again
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "add", "path": "members", "value": [{"value": user["id"]}]}],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 200
+    assert len(resp.json()["members"]) == 1  # still just one member

From dfa27c08ef2520f957ebc2699842c0450fd0f38e Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 12:58:46 -0800
Subject: [PATCH 023/267] chore(deployment): optimize layer caching (#8924)

---
 .github/workflows/deployment.yml | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
index 01c135d527f..ea8ad0fc290 100644
--- a/.github/workflows/deployment.yml
+++ b/.github/workflows/deployment.yml
@@ -426,8 +426,9 @@ jobs:
             ONYX_VERSION=${{ github.ref_name }}
             NODE_OPTIONS=--max-old-space-size=8192
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-amd64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:edge
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-amd64,mode=max
@@ -499,8 +500,9 @@ jobs:
             ONYX_VERSION=${{ github.ref_name }}
             NODE_OPTIONS=--max-old-space-size=8192
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-arm64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:edge
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-arm64,mode=max
@@ -646,8 +648,8 @@ jobs:
             NEXT_PUBLIC_INCLUDE_ERROR_POPUP_SUPPORT_LINK=true
             NODE_OPTIONS=--max-old-space-size=8192
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:cloudweb-cache-amd64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:cloudweb-cache-amd64,mode=max
@@ -728,8 +730,8 @@ jobs:
             NEXT_PUBLIC_INCLUDE_ERROR_POPUP_SUPPORT_LINK=true
             NODE_OPTIONS=--max-old-space-size=8192
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:cloudweb-cache-arm64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:cloudweb-cache-arm64,mode=max
@@ -862,8 +864,9 @@ jobs:
           build-args: |
             ONYX_VERSION=${{ github.ref_name }}
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-amd64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:edge
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-amd64,mode=max
@@ -934,8 +937,9 @@ jobs:
           build-args: |
             ONYX_VERSION=${{ github.ref_name }}
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-arm64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:edge
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-arm64,mode=max
@@ -1072,8 +1076,8 @@ jobs:
             ONYX_VERSION=${{ github.ref_name }}
             ENABLE_CRAFT=true
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-craft-cache-amd64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-craft-cache-amd64,mode=max
@@ -1145,8 +1149,8 @@ jobs:
             ONYX_VERSION=${{ github.ref_name }}
             ENABLE_CRAFT=true
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-craft-cache-arm64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-craft-cache-arm64,mode=max
@@ -1287,8 +1291,9 @@ jobs:
           build-args: |
             ONYX_VERSION=${{ github.ref_name }}
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-amd64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:edge
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-amd64,mode=max
@@ -1366,8 +1371,9 @@ jobs:
           build-args: |
             ONYX_VERSION=${{ github.ref_name }}
           cache-from: |
-            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-arm64
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:edge
+            type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
           cache-to: |
             type=inline
             type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-arm64,mode=max

From 709e3f4ca77c7b7bddfc72192b2459239de7de27 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 2 Mar 2026 14:04:36 -0800
Subject: [PATCH 024/267] chore(icons): add SvgCreditCard and SvgNetworkGraph
 to @opal/icons (#8927)

---
 web/lib/opal/src/icons/credit-card.tsx   | 20 ++++++++++++++++++
 web/lib/opal/src/icons/index.ts          |  2 ++
 web/lib/opal/src/icons/network-graph.tsx | 27 ++++++++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 web/lib/opal/src/icons/credit-card.tsx
 create mode 100644 web/lib/opal/src/icons/network-graph.tsx

diff --git a/web/lib/opal/src/icons/credit-card.tsx b/web/lib/opal/src/icons/credit-card.tsx
new file mode 100644
index 00000000000..5240c8080dc
--- /dev/null
+++ b/web/lib/opal/src/icons/credit-card.tsx
@@ -0,0 +1,20 @@
+import type { IconProps } from "@opal/types";
+const SvgCreditCard = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M14.6667 6V4.00008C14.6667 3.26675 14.0667 2.66675 13.3333 2.66675H2.66668C1.93334 2.66675 1.33334 3.26675 1.33334 4.00008V6M14.6667 6V12.0001C14.6667 12.7334 14.0667 13.3334 13.3333 13.3334H2.66668C1.93334 13.3334 1.33334 12.7334 1.33334 12.0001V6M14.6667 6H1.33334"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgCreditCard;
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index 1a861744f1f..583ca87bca3 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -51,6 +51,7 @@ export { default as SvgCode } from "@opal/icons/code";
 export { default as SvgCopy } from "@opal/icons/copy";
 export { default as SvgCornerRightUpDot } from "@opal/icons/corner-right-up-dot";
 export { default as SvgCpu } from "@opal/icons/cpu";
+export { default as SvgCreditCard } from "@opal/icons/credit-card";
 export { default as SvgDashboard } from "@opal/icons/dashboard";
 export { default as SvgDevKit } from "@opal/icons/dev-kit";
 export { default as SvgDownload } from "@opal/icons/download";
@@ -106,6 +107,7 @@ export { default as SvgMinusCircle } from "@opal/icons/minus-circle";
 export { default as SvgMoon } from "@opal/icons/moon";
 export { default as SvgMoreHorizontal } from "@opal/icons/more-horizontal";
 export { default as SvgMusicSmall } from "@opal/icons/music-small";
+export { default as SvgNetworkGraph } from "@opal/icons/network-graph";
 export { default as SvgNotificationBubble } from "@opal/icons/notification-bubble";
 export { default as SvgOllama } from "@opal/icons/ollama";
 export { default as SvgOnyxLogo } from "@opal/icons/onyx-logo";
diff --git a/web/lib/opal/src/icons/network-graph.tsx b/web/lib/opal/src/icons/network-graph.tsx
new file mode 100644
index 00000000000..226a1d39f70
--- /dev/null
+++ b/web/lib/opal/src/icons/network-graph.tsx
@@ -0,0 +1,27 @@
+import type { IconProps } from "@opal/types";
+const SvgNetworkGraph = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <g clipPath="url(#clip0_2828_22555)">
+      <path
+        d="M9.23744 4.48744C9.92086 3.80402 9.92086 2.69598 9.23744 2.01256C8.55402 1.32915 7.44598 1.32915 6.76256 2.01256C6.07915 2.69598 6.07915 3.80402 6.76256 4.48744M9.23744 4.48744C8.89573 4.82915 8.44787 5 8 5M9.23744 4.48744L11.7626 8.01256M6.76256 4.48744C7.10427 4.82915 7.55214 5 8 5M6.76256 4.48744L4.23744 8.01256M8 11C7.0335 11 6.25001 11.7835 6.25001 12.75C6.25001 13.7165 7.03351 14.5 8.00001 14.5C8.9665 14.5 9.75 13.7165 9.75 12.75C9.75 11.7835 8.9665 11 8 11ZM8 11V5M4.23744 8.01256C4.92085 8.69598 4.92422 9.81658 4.2408 10.5C3.55739 11.1834 2.44598 11.1709 1.76256 10.4874C1.07915 9.80402 1.07915 8.69598 1.76256 8.01256C2.44598 7.32915 3.55402 7.32915 4.23744 8.01256ZM11.7626 8.01256C11.0791 8.69598 11.0791 9.80402 11.7626 10.4874C12.446 11.1709 13.554 11.1709 14.2374 10.4874C14.9209 9.80402 14.9209 8.69598 14.2374 8.01256C13.554 7.32915 12.446 7.32915 11.7626 8.01256Z"
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </g>
+    <defs>
+      <clipPath id="clip0_2828_22555">
+        <rect width="16" height="16" fill="white" />
+      </clipPath>
+    </defs>
+  </svg>
+);
+export default SvgNetworkGraph;

From 3c1d29d3cf2320a7c40c41639128c09b2c1bba7d Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Mon, 2 Mar 2026 14:16:05 -0800
Subject: [PATCH 025/267] chore(opensearch): Configure index settings for
 multitenant cloud (#8921)

---
 .../opensearch/opensearch_document_index.py   |  8 +---
 .../onyx/document_index/opensearch/schema.py  | 41 ++++++++++++++++++-
 2 files changed, 41 insertions(+), 8 deletions(-)

diff --git a/backend/onyx/document_index/opensearch/opensearch_document_index.py b/backend/onyx/document_index/opensearch/opensearch_document_index.py
index 2013f5ede90..7eb0d20cf8b 100644
--- a/backend/onyx/document_index/opensearch/opensearch_document_index.py
+++ b/backend/onyx/document_index/opensearch/opensearch_document_index.py
@@ -6,7 +6,6 @@
 from opensearchpy import NotFoundError
 
 from onyx.access.models import DocumentAccess
-from onyx.configs.app_configs import USING_AWS_MANAGED_OPENSEARCH
 from onyx.configs.app_configs import VERIFY_CREATE_OPENSEARCH_INDEX_ON_INIT_MT
 from onyx.configs.chat_configs import NUM_RETURNED_HITS
 from onyx.configs.chat_configs import TITLE_CONTENT_RATIO
@@ -563,12 +562,7 @@ def verify_and_create_index_if_necessary(
         )
 
         if not self._client.index_exists():
-            if USING_AWS_MANAGED_OPENSEARCH:
-                index_settings = (
-                    DocumentSchema.get_index_settings_for_aws_managed_opensearch()
-                )
-            else:
-                index_settings = DocumentSchema.get_index_settings()
+            index_settings = DocumentSchema.get_index_settings_based_on_environment()
             self._client.create_index(
                 mappings=expected_mappings,
                 settings=index_settings,
diff --git a/backend/onyx/document_index/opensearch/schema.py b/backend/onyx/document_index/opensearch/schema.py
index cac59aaad09..a43ec897747 100644
--- a/backend/onyx/document_index/opensearch/schema.py
+++ b/backend/onyx/document_index/opensearch/schema.py
@@ -12,6 +12,7 @@
 from pydantic import SerializerFunctionWrapHandler
 
 from onyx.configs.app_configs import OPENSEARCH_TEXT_ANALYZER
+from onyx.configs.app_configs import USING_AWS_MANAGED_OPENSEARCH
 from onyx.document_index.interfaces_new import TenantState
 from onyx.document_index.opensearch.constants import DEFAULT_MAX_CHUNK_SIZE
 from onyx.document_index.opensearch.constants import EF_CONSTRUCTION
@@ -525,7 +526,7 @@ def get_index_settings() -> dict[str, Any]:
         }
 
     @staticmethod
-    def get_index_settings_for_aws_managed_opensearch() -> dict[str, Any]:
+    def get_index_settings_for_aws_managed_opensearch_st_dev() -> dict[str, Any]:
         """
         Settings for AWS-managed OpenSearch.
 
@@ -546,3 +547,41 @@ def get_index_settings_for_aws_managed_opensearch() -> dict[str, Any]:
                 "knn.algo_param.ef_search": EF_SEARCH,
             }
         }
+
+    @staticmethod
+    def get_index_settings_for_aws_managed_opensearch_mt_cloud() -> dict[str, Any]:
+        """
+        Settings for AWS-managed OpenSearch in multi-tenant cloud.
+
+        324 shards very roughly targets a storage load of ~30Gb per shard, which
+        according to AWS OpenSearch documentation is within a good target range.
+
+        As documented above we need 2 replicas for a total of 3 copies of the
+        data because the cluster is configured with 3-AZ awareness.
+        """
+        return {
+            "index": {
+                "number_of_shards": 324,
+                "number_of_replicas": 2,
+                # Required for vector search.
+                "knn": True,
+                "knn.algo_param.ef_search": EF_SEARCH,
+            }
+        }
+
+    @staticmethod
+    def get_index_settings_based_on_environment() -> dict[str, Any]:
+        """
+        Returns the index settings based on the environment.
+        """
+        if USING_AWS_MANAGED_OPENSEARCH:
+            if MULTI_TENANT:
+                return (
+                    DocumentSchema.get_index_settings_for_aws_managed_opensearch_mt_cloud()
+                )
+            else:
+                return (
+                    DocumentSchema.get_index_settings_for_aws_managed_opensearch_st_dev()
+                )
+        else:
+            return DocumentSchema.get_index_settings()

From 1f5050f9f6219bb73b6680757db503f81889f5c7 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 2 Mar 2026 14:21:47 -0800
Subject: [PATCH 026/267] refactor(admin): update admin-page
 `HealthCheckBanner` (#8922)

---
 .../embeddings/pages/EmbeddingFormPage.tsx    |  5 +-
 web/src/app/auth/impersonate/page.tsx         |  6 +-
 web/src/app/auth/join/page.tsx                |  2 -
 web/src/app/auth/login/page.tsx               |  5 --
 web/src/app/auth/signup/page.tsx              |  2 -
 web/src/app/auth/verify-email/Verify.tsx      |  4 --
 .../app/auth/waiting-on-verification/page.tsx |  5 +-
 web/src/app/layout.tsx                        |  6 +-
 web/src/components/admin/Title.tsx            |  4 --
 web/src/components/health/refreshUtils.ts     | 64 -------------------
 web/src/hooks/useCurrentUser.ts               | 42 ++++++++++++
 web/src/lib/user.ts                           | 41 ++++++++++++
 web/src/refresh-pages/AppPage.tsx             | 10 +--
 .../AppHealthBanner.tsx}                      | 44 ++++++-------
 14 files changed, 110 insertions(+), 130 deletions(-)
 delete mode 100644 web/src/components/health/refreshUtils.ts
 create mode 100644 web/src/hooks/useCurrentUser.ts
 rename web/src/{components/health/healthcheck.tsx => sections/AppHealthBanner.tsx} (84%)

diff --git a/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx b/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
index 831a4d54456..bea3929c16c 100644
--- a/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
+++ b/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { toast } from "@/hooks/useToast";
-import { HealthCheckBanner } from "@/components/health/healthcheck";
+
 import EmbeddingModelSelection from "../EmbeddingModelSelectionForm";
 import { useCallback, useEffect, useMemo, useState, useRef } from "react";
 import Text from "@/refresh-components/texts/Text";
@@ -481,9 +481,6 @@ export default function EmbeddingForm() {
 
   return (
     <div className="mx-auto mb-8 w-full">
-      <div className="mb-4">
-        <HealthCheckBanner />
-      </div>
       <div className="mx-auto max-w-4xl">
         {formStep == 0 && (
           <>
diff --git a/web/src/app/auth/impersonate/page.tsx b/web/src/app/auth/impersonate/page.tsx
index de5f3541841..81d20f195e4 100644
--- a/web/src/app/auth/impersonate/page.tsx
+++ b/web/src/app/auth/impersonate/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
-import { HealthCheckBanner } from "@/components/health/healthcheck";
+
 import { useUser } from "@/providers/UserProvider";
 import { redirect, useRouter } from "next/navigation";
 import type { Route } from "next";
@@ -61,10 +61,6 @@ export default function ImpersonatePage() {
 
   return (
     <AuthFlowContainer>
-      <div className="absolute top-10x w-full">
-        <HealthCheckBanner />
-      </div>
-
       <div className="flex flex-col w-full justify-center">
         <div className="w-full flex flex-col items-center justify-center">
           <Text as="p" headingH3 className="mb-6 text-center">
diff --git a/web/src/app/auth/join/page.tsx b/web/src/app/auth/join/page.tsx
index 448762eca17..1dd5aec90c2 100644
--- a/web/src/app/auth/join/page.tsx
+++ b/web/src/app/auth/join/page.tsx
@@ -1,4 +1,3 @@
-import { HealthCheckBanner } from "@/components/health/healthcheck";
 import { User } from "@/lib/types";
 import {
   getCurrentUserSS,
@@ -65,7 +64,6 @@ const Page = async (props: {
 
   return (
     <AuthFlowContainer authState="join">
-      <HealthCheckBanner />
       <AuthErrorDisplay searchParams={searchParams} />
 
       <>
diff --git a/web/src/app/auth/login/page.tsx b/web/src/app/auth/login/page.tsx
index d64ba3f5a46..7b0c9d489dc 100644
--- a/web/src/app/auth/login/page.tsx
+++ b/web/src/app/auth/login/page.tsx
@@ -1,4 +1,3 @@
-import { HealthCheckBanner } from "@/components/health/healthcheck";
 import { User } from "@/lib/types";
 import {
   getCurrentUserSS,
@@ -105,10 +104,6 @@ export default async function Page(props: PageProps) {
         authState="login"
         footerContent={ssoLoginFooterContent}
       >
-        <div className="absolute top-10x w-full">
-          <HealthCheckBanner />
-        </div>
-
         <LoginPage
           authUrl={authUrl}
           authTypeMetadata={authTypeMetadata}
diff --git a/web/src/app/auth/signup/page.tsx b/web/src/app/auth/signup/page.tsx
index 7acbe544424..eeebbdb2d22 100644
--- a/web/src/app/auth/signup/page.tsx
+++ b/web/src/app/auth/signup/page.tsx
@@ -1,4 +1,3 @@
-import { HealthCheckBanner } from "@/components/health/healthcheck";
 import { User } from "@/lib/types";
 import {
   getCurrentUserSS,
@@ -63,7 +62,6 @@ const Page = async (props: {
 
   return (
     <AuthFlowContainer authState="signup">
-      <HealthCheckBanner />
       <AuthErrorDisplay searchParams={searchParams} />
 
       <>
diff --git a/web/src/app/auth/verify-email/Verify.tsx b/web/src/app/auth/verify-email/Verify.tsx
index 146cbc46b94..f8d792d6189 100644
--- a/web/src/app/auth/verify-email/Verify.tsx
+++ b/web/src/app/auth/verify-email/Verify.tsx
@@ -1,6 +1,5 @@
 "use client";
 
-import { HealthCheckBanner } from "@/components/health/healthcheck";
 import { useSearchParams } from "next/navigation";
 import { useCallback, useEffect, useState } from "react";
 import Text from "@/components/ui/text";
@@ -63,9 +62,6 @@ export default function Verify({ user }: VerifyProps) {
 
   return (
     <main>
-      <div className="absolute top-10x w-full">
-        <HealthCheckBanner />
-      </div>
       <div className="min-h-screen flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
         <Logo folded size={64} className="mx-auto w-fit animate-pulse" />
         {!error ? (
diff --git a/web/src/app/auth/waiting-on-verification/page.tsx b/web/src/app/auth/waiting-on-verification/page.tsx
index 2597c85fccc..42fe919ede6 100644
--- a/web/src/app/auth/waiting-on-verification/page.tsx
+++ b/web/src/app/auth/waiting-on-verification/page.tsx
@@ -4,7 +4,7 @@ import {
   getCurrentUserSS,
 } from "@/lib/userSS";
 import { redirect } from "next/navigation";
-import { HealthCheckBanner } from "@/components/health/healthcheck";
+
 import { User } from "@/lib/types";
 import Text from "@/components/ui/text";
 import { RequestNewVerificationEmail } from "./RequestNewVerificationEmail";
@@ -35,9 +35,6 @@ export default async function Page() {
 
   return (
     <main>
-      <div className="absolute top-10x w-full">
-        <HealthCheckBanner />
-      </div>
       <div className="min-h-screen flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
         <Logo folded size={64} className="mx-auto w-fit" />
         <div className="flex">
diff --git a/web/src/app/layout.tsx b/web/src/app/layout.tsx
index b7fdd9a9267..a65a09459e1 100644
--- a/web/src/app/layout.tsx
+++ b/web/src/app/layout.tsx
@@ -30,6 +30,7 @@ import GatedContentWrapper from "@/components/GatedContentWrapper";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { fetchAppSidebarMetadata } from "@/lib/appSidebarSS";
 import StatsOverlayLoader from "@/components/dev/StatsOverlayLoader";
+import AppHealthBanner from "@/sections/AppHealthBanner";
 
 const inter = Inter({
   subsets: ["latin"],
@@ -128,7 +129,10 @@ export default async function RootLayout({
         >
           <div className="text-text min-h-screen bg-background">
             <TooltipProvider>
-              <PHProvider>{content}</PHProvider>
+              <PHProvider>
+                <AppHealthBanner />
+                {content}
+              </PHProvider>
             </TooltipProvider>
           </div>
         </ThemeProvider>
diff --git a/web/src/components/admin/Title.tsx b/web/src/components/admin/Title.tsx
index 0d4072b1e89..988aeceaf8e 100644
--- a/web/src/components/admin/Title.tsx
+++ b/web/src/components/admin/Title.tsx
@@ -1,7 +1,6 @@
 "use client";
 
 import { JSX } from "react";
-import { HealthCheckBanner } from "../health/healthcheck";
 import Separator from "@/refresh-components/Separator";
 import type { IconProps } from "@opal/types";
 import Text from "@/refresh-components/texts/Text";
@@ -21,9 +20,6 @@ export function AdminPageTitle({
 }: AdminPageTitleProps) {
   return (
     <div className="w-full">
-      <div className="mb-4">
-        <HealthCheckBanner />
-      </div>
       <div className="w-full flex flex-row justify-between">
         <div className="flex flex-row gap-2">
           {typeof Icon === "function" ? (
diff --git a/web/src/components/health/refreshUtils.ts b/web/src/components/health/refreshUtils.ts
deleted file mode 100644
index 0ce66fdece7..00000000000
--- a/web/src/components/health/refreshUtils.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-export interface CustomRefreshTokenResponse {
-  access_token: string;
-  refresh_token: string;
-  session: {
-    exp: number;
-  };
-  userinfo: {
-    sub: string;
-    familyName: string;
-    givenName: string;
-    fullName: string;
-    userId: string;
-    email: string;
-  };
-}
-
-export function mockedRefreshToken(): CustomRefreshTokenResponse {
-  /**
-   * This function mocks the response from a token refresh endpoint.
-   * It generates a mock access token, refresh token, and user information
-   * with an expiration time set to 1 hour from now.
-   * This is useful for testing or development when the actual refresh endpoint is not available.
-   */
-  const mockExp = Date.now() + 3600000; // 1 hour from now in milliseconds
-  const data: CustomRefreshTokenResponse = {
-    access_token: "Mock access token",
-    refresh_token: "Mock refresh token",
-    session: { exp: mockExp },
-    userinfo: {
-      sub: "Mock email",
-      familyName: "Mock name",
-      givenName: "Mock name",
-      fullName: "Mock name",
-      userId: "Mock User ID",
-      email: "email@onyx.app",
-    },
-  };
-  return data;
-}
-
-export async function refreshToken(
-  customRefreshUrl: string
-): Promise<CustomRefreshTokenResponse | null> {
-  try {
-    console.debug("Sending request to custom refresh URL");
-    // support both absolute and relative
-    const url = customRefreshUrl.startsWith("http")
-      ? new URL(customRefreshUrl)
-      : new URL(customRefreshUrl, window.location.origin);
-    url.searchParams.append("info", "json");
-    url.searchParams.append("access_token_refresh_interval", "3600");
-
-    const response = await fetch(url.toString());
-    if (!response.ok) {
-      console.error(`Failed to refresh token: ${await response.text()}`);
-      return null;
-    }
-
-    return await response.json();
-  } catch (error) {
-    console.error("Error refreshing token:", error);
-    throw error;
-  }
-}
diff --git a/web/src/hooks/useCurrentUser.ts b/web/src/hooks/useCurrentUser.ts
new file mode 100644
index 00000000000..57c493e366e
--- /dev/null
+++ b/web/src/hooks/useCurrentUser.ts
@@ -0,0 +1,42 @@
+import useSWR, { type KeyedMutator } from "swr";
+import { errorHandlingFetcher } from "@/lib/fetcher";
+import { User } from "@/lib/types";
+
+/**
+ * Fetches the current authenticated user via SWR (`/api/me`).
+ *
+ * This hook is intentionally configured with conservative revalidation
+ * settings to avoid hammering the backend on every focus/reconnect event:
+ *
+ * - `revalidateOnFocus: false`      — tab switches won't trigger a refetch
+ * - `revalidateOnReconnect: false`   — network recovery won't trigger a refetch
+ * - `dedupingInterval: 30_000`       — duplicate requests within 30 s are deduped
+ *
+ * The returned `mutateUser` handle lets callers imperatively refetch (e.g.
+ * after a token refresh) without changing the global SWR config.
+ *
+ * @example
+ * ```ts
+ * const { user, mutateUser, userError } = useCurrentUser();
+ * ```
+ */
+export function useCurrentUser(): {
+  /** The authenticated user, or `undefined` while loading. */
+  user: User | undefined;
+  /** Imperatively revalidate / update the cached user. */
+  mutateUser: KeyedMutator<User>;
+  /** The error thrown by the fetcher, if any. */
+  userError: (Error & { status?: number }) | undefined;
+} {
+  const { data, mutate, error } = useSWR<User>(
+    "/api/me",
+    errorHandlingFetcher,
+    {
+      revalidateOnFocus: false,
+      revalidateOnReconnect: false,
+      dedupingInterval: 30_000,
+    }
+  );
+
+  return { user: data, mutateUser: mutate, userError: error };
+}
diff --git a/web/src/lib/user.ts b/web/src/lib/user.ts
index beab90b6834..78c6fb26043 100644
--- a/web/src/lib/user.ts
+++ b/web/src/lib/user.ts
@@ -72,3 +72,44 @@ export const basicSignup = async (
   });
   return response;
 };
+
+export interface CustomRefreshTokenResponse {
+  access_token: string;
+  refresh_token: string;
+  session: {
+    exp: number;
+  };
+  userinfo: {
+    sub: string;
+    familyName: string;
+    givenName: string;
+    fullName: string;
+    userId: string;
+    email: string;
+  };
+}
+
+export async function refreshToken(
+  customRefreshUrl: string
+): Promise<CustomRefreshTokenResponse | null> {
+  try {
+    console.debug("Sending request to custom refresh URL");
+    // support both absolute and relative
+    const url = customRefreshUrl.startsWith("http")
+      ? new URL(customRefreshUrl)
+      : new URL(customRefreshUrl, window.location.origin);
+    url.searchParams.append("info", "json");
+    url.searchParams.append("access_token_refresh_interval", "3600");
+
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+      console.error(`Failed to refresh token: ${await response.text()}`);
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error("Error refreshing token:", error);
+    throw error;
+  }
+}
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index cca29af3c39..130195c9120 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -1,7 +1,6 @@
 "use client";
 
 import { redirect, useRouter, useSearchParams } from "next/navigation";
-import { HealthCheckBanner } from "@/components/health/healthcheck";
 import {
   personaIncludesRetrieval,
   getAvailableContextTokens,
@@ -628,12 +627,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
   // handle error case where no assistants are available
   // Only show this after agents have loaded to prevent flash during initial load
   if (noAgents && !isLoadingAgents) {
-    return (
-      <>
-        <HealthCheckBanner />
-        <NoAgentModal />
-      </>
-    );
+    return <NoAgentModal />;
   }
 
   const hasStarterMessages = (liveAgent?.starter_messages?.length ?? 0) > 0;
@@ -654,8 +648,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
 
   return (
     <>
-      <HealthCheckBanner />
-
       <AppPopup />
 
       {retrievalEnabled && documentSidebarVisible && settings.isMobile && (
diff --git a/web/src/components/health/healthcheck.tsx b/web/src/sections/AppHealthBanner.tsx
similarity index 84%
rename from web/src/components/health/healthcheck.tsx
rename to web/src/sections/AppHealthBanner.tsx
index e8cf0dc4821..d5527af1cdd 100644
--- a/web/src/components/health/healthcheck.tsx
+++ b/web/src/sections/AppHealthBanner.tsx
@@ -5,14 +5,16 @@ import useSWR from "swr";
 import Modal from "@/refresh-components/Modal";
 import { useCallback, useEffect, useState, useRef } from "react";
 import { getSecondsUntilExpiration } from "@/lib/time";
-import { User } from "@/lib/types";
-import { refreshToken } from "./refreshUtils";
+import { refreshToken } from "@/lib/user";
 import { NEXT_PUBLIC_CUSTOM_REFRESH_URL } from "@/lib/constants";
 import Button from "@/refresh-components/buttons/Button";
 import { logout } from "@/lib/user";
 import { usePathname, useRouter } from "next/navigation";
-import { SvgLogOut } from "@opal/icons";
-export const HealthCheckBanner = () => {
+import { SvgAlertTriangle, SvgLogOut } from "@opal/icons";
+import { Content } from "@opal/layouts";
+import { useCurrentUser } from "@/hooks/useCurrentUser";
+
+export default function AppHealthBanner() {
   const router = useRouter();
   const { error } = useSWR("/api/health", errorHandlingFetcher);
   const [expired, setExpired] = useState(false);
@@ -21,16 +23,7 @@ export const HealthCheckBanner = () => {
   const expirationTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const refreshIntervalRef = useRef<NodeJS.Timer | null>(null);
 
-  // Reduce revalidation frequency with dedicated SWR config
-  const {
-    data: user,
-    mutate: mutateUser,
-    error: userError,
-  } = useSWR<User>("/api/me", errorHandlingFetcher, {
-    revalidateOnFocus: false,
-    revalidateOnReconnect: false,
-    dedupingInterval: 30000, // 30 seconds
-  });
+  const { user, mutateUser, userError } = useCurrentUser();
 
   // Handle 403 errors from the /api/me endpoint
   useEffect(() => {
@@ -44,10 +37,10 @@ export const HealthCheckBanner = () => {
   }, [userError, pathname]);
 
   // Function to handle the "Log in" button click
-  const handleLogin = () => {
+  function handleLogin() {
     setShowLoggedOutModal(false);
     router.push("/auth/login");
-  };
+  }
 
   // Function to set up expiration timeout
   const setupExpirationTimeout = useCallback(
@@ -211,16 +204,15 @@ export const HealthCheckBanner = () => {
     return null;
   } else {
     return (
-      <div className="fixed top-0 left-0 z-[101] w-full text-xs mx-auto bg-gradient-to-r from-red-900 to-red-700 p-2 rounded-sm border-hidden text-neutral-50 dark:text-neutral-100">
-        <p className="font-bold pb-1">The backend is currently unavailable.</p>
-
-        <p className="px-1">
-          If this is your initial setup or you just updated your Onyx
-          deployment, this is likely because the backend is still starting up.
-          Give it a minute or two, and then refresh the page. If that does not
-          work, make sure the backend is setup and/or contact an administrator.
-        </p>
+      <div className="fixed top-0 left-0 z-[101] w-full bg-status-error-01 p-3">
+        <Content
+          icon={SvgAlertTriangle}
+          title="The backend is currently unavailable"
+          description="If this is your initial setup or you just updated your Onyx deployment, this is likely because the backend is still starting up. Give it a minute or two, and then refresh the page. If that does not work, make sure the backend is setup and/or contact an administrator."
+          sizePreset="main-content"
+          variant="section"
+        />
       </div>
     );
   }
-};
+}

From 28332fa24b3ac54b7f50d0d2278cdce325cf53ed Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Mon, 2 Mar 2026 14:44:09 -0800
Subject: [PATCH 027/267] fix(ui): InputComboBox search for users/groups
 (#8928)

---
 .../inputs/InputComboBox/InputComboBox.test.tsx    | 14 ++++++--------
 .../inputs/InputComboBox/InputComboBox.tsx         |  9 ++++++---
 .../inputs/InputComboBox/types.ts                  |  5 +++++
 3 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx
index 03a6210941c..53fd7d9c2a5 100644
--- a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx
+++ b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx
@@ -195,12 +195,11 @@ describe("InputComboBox", () => {
 
       await user.type(input, "app");
 
-      // Get all options and check the first one contains Apple
+      // Search should only show matching options by default
       const options = screen.getAllByRole("option");
-      expect(options.length).toBeGreaterThan(0);
+      expect(options.length).toBe(1);
       expect(options[0]!.textContent).toBe("Apple");
-      // Banana and Cherry should be in "Other options" section
-      expect(screen.getByText("Banana")).toBeInTheDocument();
+      expect(screen.queryByText("Banana")).not.toBeInTheDocument();
     });
 
     test("shows 'No options found' when no matches and strict mode", async () => {
@@ -217,12 +216,10 @@ describe("InputComboBox", () => {
 
       await user.type(input, "xyz");
 
-      // In strict mode with no matches, all options go to "Other options" section
-      // which shows all options (not "No options found")
-      expect(screen.getByText("Other options")).toBeInTheDocument();
+      expect(screen.getByText("No options found")).toBeInTheDocument();
     });
 
-    test("shows separator between matched and unmatched options", async () => {
+    test("shows separator between matched and unmatched options when enabled", async () => {
       const user = setupUser();
       render(
         <InputComboBox
@@ -230,6 +227,7 @@ describe("InputComboBox", () => {
           value=""
           options={mockOptions}
           separatorLabel="Other fruits"
+          showOtherOptions
         />
       );
       const input = screen.getByPlaceholderText("Select");
diff --git a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
index 7a3ae079090..3f2c5e8b91d 100644
--- a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
+++ b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
@@ -129,6 +129,7 @@ const InputComboBox = ({
   leftSearchIcon = false,
   rightSection,
   separatorLabel = "Other options",
+  showOtherOptions = false,
   ...rest
 }: WithoutStyles<InputComboBoxProps>) => {
   const inputRef = useRef<HTMLInputElement>(null);
@@ -152,6 +153,8 @@ const InputComboBox = ({
   // Filtering Hook
   const { matchedOptions, unmatchedOptions, hasSearchTerm } =
     useOptionFiltering({ options, inputValue });
+  const visibleUnmatchedOptions =
+    hasSearchTerm && showOtherOptions ? unmatchedOptions : [];
 
   // Whether to show the create option (only when no partial matches)
   const showCreateOption =
@@ -162,13 +165,13 @@ const InputComboBox = ({
 
   // Combined list for keyboard navigation (includes create option when shown)
   const allVisibleOptions = useMemo(() => {
-    const baseOptions = [...matchedOptions, ...unmatchedOptions];
+    const baseOptions = [...matchedOptions, ...visibleUnmatchedOptions];
     if (showCreateOption) {
       // Prepend a synthetic option for the "create new" item
       return [{ value: inputValue, label: inputValue }, ...baseOptions];
     }
     return baseOptions;
-  }, [matchedOptions, unmatchedOptions, showCreateOption, inputValue]);
+  }, [matchedOptions, visibleUnmatchedOptions, showCreateOption, inputValue]);
 
   // Floating UI for dropdown positioning
   const { refs, floatingStyles } = useFloating({
@@ -418,7 +421,7 @@ const InputComboBox = ({
           fieldId={fieldId}
           placeholder={placeholder}
           matchedOptions={matchedOptions}
-          unmatchedOptions={unmatchedOptions}
+          unmatchedOptions={visibleUnmatchedOptions}
           hasSearchTerm={hasSearchTerm}
           separatorLabel={separatorLabel}
           value={value}
diff --git a/web/src/refresh-components/inputs/InputComboBox/types.ts b/web/src/refresh-components/inputs/InputComboBox/types.ts
index 5febbc1ce3d..3e9ea5f234a 100644
--- a/web/src/refresh-components/inputs/InputComboBox/types.ts
+++ b/web/src/refresh-components/inputs/InputComboBox/types.ts
@@ -40,4 +40,9 @@ export interface InputComboBoxProps
   rightSection?: React.ReactNode;
   /** Label for the separator between matched and unmatched options */
   separatorLabel?: string;
+  /**
+   * When true, keep non-matching options visible under a separator while searching.
+   * Defaults to false so search results are strictly filtered.
+   */
+  showOtherOptions?: boolean;
 }

From 30fa43b5fcd1ea0b8b00a77029dc758c175f4905 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 2 Mar 2026 22:48:54 +0000
Subject: [PATCH 028/267] chore(deps): bump pypdf from 6.7.3 to 6.7.4 (#8905)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt | 2 +-
 pyproject.toml                   | 2 +-
 uv.lock                          | 8 ++++----
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 438e56bde09..efdbad05411 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -809,7 +809,7 @@ pypandoc-binary==1.16.2
     # via onyx
 pyparsing==3.2.5
     # via httplib2
-pypdf==6.7.3
+pypdf==6.7.4
     # via
     #   onyx
     #   unstructured-client
diff --git a/pyproject.toml b/pyproject.toml
index 203a85c9eb7..f0cfd09feac 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -92,7 +92,7 @@ backend = [
     "python-gitlab==5.6.0",
     "python-pptx==0.6.23",
     "pypandoc_binary==1.16.2",
-    "pypdf==6.7.3",
+    "pypdf==6.7.4",
     "pytest-mock==3.12.0",
     "pytest-playwright==0.7.0",
     "python-docx==1.1.2",
diff --git a/uv.lock b/uv.lock
index 5848b04425a..ad93c9ebc18 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4678,7 +4678,7 @@ requires-dist = [
     { name = "pygithub", marker = "extra == 'backend'", specifier = "==2.5.0" },
     { name = "pympler", marker = "extra == 'backend'", specifier = "==1.1" },
     { name = "pypandoc-binary", marker = "extra == 'backend'", specifier = "==1.16.2" },
-    { name = "pypdf", marker = "extra == 'backend'", specifier = "==6.7.3" },
+    { name = "pypdf", marker = "extra == 'backend'", specifier = "==6.7.4" },
     { name = "pytest", marker = "extra == 'dev'", specifier = "==8.3.5" },
     { name = "pytest-alembic", marker = "extra == 'dev'", specifier = "==0.12.1" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = "==1.3.0" },
@@ -5925,11 +5925,11 @@ wheels = [
 
 [[package]]
 name = "pypdf"
-version = "6.7.3"
+version = "6.7.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/53/9b/63e767042fc852384dc71e5ff6f990ee4e1b165b1526cf3f9c23a4eebb47/pypdf-6.7.3.tar.gz", hash = "sha256:eca55c78d0ec7baa06f9288e2be5c4e8242d5cbb62c7a4b94f2716f8e50076d2", size = 5303304, upload-time = "2026-02-24T17:23:11.42Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/09/dc/f52deef12797ad58b88e4663f097a343f53b9361338aef6573f135ac302f/pypdf-6.7.4.tar.gz", hash = "sha256:9edd1cd47938bb35ec87795f61225fd58a07cfaf0c5699018ae1a47d6f8ab0e3", size = 5304821, upload-time = "2026-02-27T10:44:39.395Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b0/90/3308a9b8b46c1424181fdf3f4580d2b423c5471425799e7fc62f92d183f4/pypdf-6.7.3-py3-none-any.whl", hash = "sha256:cd25ac508f20b554a9fafd825186e3ba29591a69b78c156783c5d8a2d63a1c0a", size = 331263, upload-time = "2026-02-24T17:23:09.932Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/be/cded021305f5c81b47265b8c5292b99388615a4391c21ff00fd538d34a56/pypdf-6.7.4-py3-none-any.whl", hash = "sha256:527d6da23274a6c70a9cb59d1986d93946ba8e36a6bc17f3f7cce86331492dda", size = 331496, upload-time = "2026-02-27T10:44:37.527Z" },
 ]
 
 [[package]]

From 1a65217bafe196b758448f3ab48db1c1d55e353b Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 15:03:38 -0800
Subject: [PATCH 029/267] fix(scim): pass Okta Runscope spec test for OIN
 submission (#8925)

---
 backend/ee/onyx/main.py                       |  2 +
 backend/ee/onyx/server/scim/api.py            | 42 +++++++++++++------
 backend/ee/onyx/server/scim/auth.py           | 31 ++++++++------
 backend/ee/onyx/server/scim/providers/base.py | 14 ++++---
 .../integration/tests/scim/test_scim_users.py | 13 +++---
 .../tests/unit/onyx/server/scim/test_auth.py  | 10 ++---
 .../unit/onyx/server/scim/test_providers.py   |  4 +-
 .../onyx/server/scim/test_user_endpoints.py   | 13 ++++--
 8 files changed, 82 insertions(+), 47 deletions(-)

diff --git a/backend/ee/onyx/main.py b/backend/ee/onyx/main.py
index 612db0efeb7..575c159250a 100644
--- a/backend/ee/onyx/main.py
+++ b/backend/ee/onyx/main.py
@@ -31,6 +31,7 @@
 from ee.onyx.server.query_and_chat.search_backend import router as search_router
 from ee.onyx.server.query_history.api import router as query_history_router
 from ee.onyx.server.reporting.usage_export_api import router as usage_export_router
+from ee.onyx.server.scim.api import register_scim_exception_handlers
 from ee.onyx.server.scim.api import scim_router
 from ee.onyx.server.seeding import seed_db
 from ee.onyx.server.tenants.api import router as tenants_router
@@ -167,6 +168,7 @@ def get_application() -> FastAPI:
     # they use their own SCIM bearer token auth).
     # Not behind APP_API_PREFIX because IdPs expect /scim/v2/... directly.
     application.include_router(scim_router)
+    register_scim_exception_handlers(application)
 
     # Ensure all routes have auth enabled or are explicitly marked as public
     check_ee_router_auth(application)
diff --git a/backend/ee/onyx/server/scim/api.py b/backend/ee/onyx/server/scim/api.py
index 3f9fc55f050..b8a5b8225e3 100644
--- a/backend/ee/onyx/server/scim/api.py
+++ b/backend/ee/onyx/server/scim/api.py
@@ -15,7 +15,9 @@
 
 from fastapi import APIRouter
 from fastapi import Depends
+from fastapi import FastAPI
 from fastapi import Query
+from fastapi import Request
 from fastapi import Response
 from fastapi.responses import JSONResponse
 from fastapi_users.password import PasswordHelper
@@ -24,6 +26,7 @@
 from sqlalchemy.orm import Session
 
 from ee.onyx.db.scim import ScimDAL
+from ee.onyx.server.scim.auth import ScimAuthError
 from ee.onyx.server.scim.auth import verify_scim_token
 from ee.onyx.server.scim.filtering import parse_scim_filter
 from ee.onyx.server.scim.models import SCIM_LIST_RESPONSE_SCHEMA
@@ -77,6 +80,22 @@ class ScimJSONResponse(JSONResponse):
 _pw_helper = PasswordHelper()
 
 
+def register_scim_exception_handlers(app: FastAPI) -> None:
+    """Register SCIM-specific exception handlers on the FastAPI app.
+
+    Call this after ``app.include_router(scim_router)`` so that auth
+    failures from ``verify_scim_token`` return RFC 7644 §3.12 error
+    envelopes (with ``schemas`` and ``status`` fields) instead of
+    FastAPI's default ``{"detail": "..."}`` format.
+    """
+
+    @app.exception_handler(ScimAuthError)
+    async def _handle_scim_auth_error(
+        _request: Request, exc: ScimAuthError
+    ) -> ScimJSONResponse:
+        return _scim_error_response(exc.status_code, exc.detail)
+
+
 def _get_provider(
     _token: ScimToken = Depends(verify_scim_token),
 ) -> ScimProvider:
@@ -404,12 +423,6 @@ def create_user(
 
     email = user_resource.userName.strip()
 
-    # externalId is how the IdP correlates this user on subsequent requests.
-    # Without it, the IdP can't find the user and will try to re-create,
-    # hitting a 409 conflict — so we require it up front.
-    if not user_resource.externalId:
-        return _scim_error_response(400, "externalId is required")
-
     # Enforce seat limit
     seat_error = _check_seat_availability(dal)
     if seat_error:
@@ -436,16 +449,19 @@ def create_user(
         dal.rollback()
         return _scim_error_response(409, f"User with email {email} already exists")
 
-    # Create SCIM mapping (externalId is validated above, always present)
+    # Create SCIM mapping when externalId is provided — this is how the IdP
+    # correlates this user on subsequent requests.  Per RFC 7643, externalId
+    # is optional and assigned by the provisioning client.
     external_id = user_resource.externalId
     scim_username = user_resource.userName.strip()
     fields = _fields_from_resource(user_resource)
-    dal.create_user_mapping(
-        external_id=external_id,
-        user_id=user.id,
-        scim_username=scim_username,
-        fields=fields,
-    )
+    if external_id:
+        dal.create_user_mapping(
+            external_id=external_id,
+            user_id=user.id,
+            scim_username=scim_username,
+            fields=fields,
+        )
 
     dal.commit()
 
diff --git a/backend/ee/onyx/server/scim/auth.py b/backend/ee/onyx/server/scim/auth.py
index d05a1bd140b..e8965815053 100644
--- a/backend/ee/onyx/server/scim/auth.py
+++ b/backend/ee/onyx/server/scim/auth.py
@@ -19,7 +19,6 @@
 import secrets
 
 from fastapi import Depends
-from fastapi import HTTPException
 from fastapi import Request
 from sqlalchemy.orm import Session
 
@@ -28,6 +27,21 @@
 from onyx.db.engine.sql_engine import get_session
 from onyx.db.models import ScimToken
 
+
+class ScimAuthError(Exception):
+    """Raised when SCIM bearer token authentication fails.
+
+    Unlike HTTPException, this carries the status and detail so the SCIM
+    exception handler can wrap them in an RFC 7644 §3.12 error envelope
+    with ``schemas`` and ``status`` fields.
+    """
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(detail)
+
+
 SCIM_TOKEN_PREFIX = "onyx_scim_"
 SCIM_TOKEN_LENGTH = 48
 
@@ -82,23 +96,14 @@ def verify_scim_token(
     """
     hashed = _get_hashed_scim_token_from_request(request)
     if not hashed:
-        raise HTTPException(
-            status_code=401,
-            detail="Missing or invalid SCIM bearer token",
-        )
+        raise ScimAuthError(401, "Missing or invalid SCIM bearer token")
 
     token = dal.get_token_by_hash(hashed)
 
     if not token:
-        raise HTTPException(
-            status_code=401,
-            detail="Invalid SCIM bearer token",
-        )
+        raise ScimAuthError(401, "Invalid SCIM bearer token")
 
     if not token.is_active:
-        raise HTTPException(
-            status_code=401,
-            detail="SCIM token has been revoked",
-        )
+        raise ScimAuthError(401, "SCIM token has been revoked")
 
     return token
diff --git a/backend/ee/onyx/server/scim/providers/base.py b/backend/ee/onyx/server/scim/providers/base.py
index 5dc5fac3049..8f738c0d134 100644
--- a/backend/ee/onyx/server/scim/providers/base.py
+++ b/backend/ee/onyx/server/scim/providers/base.py
@@ -153,26 +153,28 @@ def build_scim_name(
         self,
         user: User,
         fields: ScimMappingFields,
-    ) -> ScimName | None:
+    ) -> ScimName:
         """Build SCIM name components for the response.
 
         Round-trips stored ``given_name``/``family_name`` when available (so
         the IdP gets back what it sent). Falls back to splitting
         ``personal_name`` for users provisioned before we stored components.
+        Always returns a ScimName — Okta's spec tests expect ``name``
+        (with ``givenName``/``familyName``) on every user resource.
         Providers may override for custom behavior.
         """
         if fields.given_name is not None or fields.family_name is not None:
             return ScimName(
-                givenName=fields.given_name,
-                familyName=fields.family_name,
-                formatted=user.personal_name,
+                givenName=fields.given_name or "",
+                familyName=fields.family_name or "",
+                formatted=user.personal_name or "",
             )
         if not user.personal_name:
-            return None
+            return ScimName(givenName="", familyName="", formatted="")
         parts = user.personal_name.split(" ", 1)
         return ScimName(
             givenName=parts[0],
-            familyName=parts[1] if len(parts) > 1 else None,
+            familyName=parts[1] if len(parts) > 1 else "",
             formatted=user.personal_name,
         )
 
diff --git a/backend/tests/integration/tests/scim/test_scim_users.py b/backend/tests/integration/tests/scim/test_scim_users.py
index 7a242960686..c7c844175c9 100644
--- a/backend/tests/integration/tests/scim/test_scim_users.py
+++ b/backend/tests/integration/tests/scim/test_scim_users.py
@@ -389,19 +389,22 @@ def test_delete_user(scim_token: str, idp_style: str) -> None:
 # ------------------------------------------------------------------
 
 
-def test_create_user_missing_external_id(scim_token: str) -> None:
-    """POST /Users without externalId returns 400."""
+def test_create_user_missing_external_id(scim_token: str, idp_style: str) -> None:
+    """POST /Users without externalId succeeds (RFC 7643: externalId is optional)."""
+    email = f"scim_no_extid_{idp_style}@example.com"
     resp = ScimClient.post(
         "/Users",
         scim_token,
         json={
             "schemas": [SCIM_USER_SCHEMA],
-            "userName": "scim_no_extid@example.com",
+            "userName": email,
             "active": True,
         },
     )
-    assert resp.status_code == 400
-    assert "externalId" in resp.json()["detail"]
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["userName"] == email
+    assert body.get("externalId") is None
 
 
 def test_create_user_duplicate_email(scim_token: str, idp_style: str) -> None:
diff --git a/backend/tests/unit/onyx/server/scim/test_auth.py b/backend/tests/unit/onyx/server/scim/test_auth.py
index a482ac18981..ac645c843d1 100644
--- a/backend/tests/unit/onyx/server/scim/test_auth.py
+++ b/backend/tests/unit/onyx/server/scim/test_auth.py
@@ -1,11 +1,11 @@
 from unittest.mock import MagicMock
 
 import pytest
-from fastapi import HTTPException
 
 from ee.onyx.server.scim.auth import _hash_scim_token
 from ee.onyx.server.scim.auth import generate_scim_token
 from ee.onyx.server.scim.auth import SCIM_TOKEN_PREFIX
+from ee.onyx.server.scim.auth import ScimAuthError
 from ee.onyx.server.scim.auth import verify_scim_token
 
 
@@ -60,7 +60,7 @@ def _make_dal(self, token: MagicMock | None = None) -> MagicMock:
     def test_missing_header_raises_401(self) -> None:
         request = self._make_request(None)
         dal = self._make_dal()
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(ScimAuthError) as exc_info:
             verify_scim_token(request, dal)
         assert exc_info.value.status_code == 401
         assert "Missing" in str(exc_info.value.detail)
@@ -68,7 +68,7 @@ def test_missing_header_raises_401(self) -> None:
     def test_wrong_prefix_raises_401(self) -> None:
         request = self._make_request("Bearer on_some_api_key")
         dal = self._make_dal()
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(ScimAuthError) as exc_info:
             verify_scim_token(request, dal)
         assert exc_info.value.status_code == 401
 
@@ -76,7 +76,7 @@ def test_token_not_in_db_raises_401(self) -> None:
         raw, _, _ = generate_scim_token()
         request = self._make_request(f"Bearer {raw}")
         dal = self._make_dal(token=None)
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(ScimAuthError) as exc_info:
             verify_scim_token(request, dal)
         assert exc_info.value.status_code == 401
         assert "Invalid" in str(exc_info.value.detail)
@@ -87,7 +87,7 @@ def test_inactive_token_raises_401(self) -> None:
         mock_token = MagicMock()
         mock_token.is_active = False
         dal = self._make_dal(token=mock_token)
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(ScimAuthError) as exc_info:
             verify_scim_token(request, dal)
         assert exc_info.value.status_code == 401
         assert "revoked" in str(exc_info.value.detail)
diff --git a/backend/tests/unit/onyx/server/scim/test_providers.py b/backend/tests/unit/onyx/server/scim/test_providers.py
index bccd57fc765..60bbff89aae 100644
--- a/backend/tests/unit/onyx/server/scim/test_providers.py
+++ b/backend/tests/unit/onyx/server/scim/test_providers.py
@@ -109,7 +109,7 @@ def test_build_user_resource_single_name(self) -> None:
         result = provider.build_user_resource(user, None)
 
         assert result.name == ScimName(
-            givenName="Madonna", familyName=None, formatted="Madonna"
+            givenName="Madonna", familyName="", formatted="Madonna"
         )
 
     def test_build_user_resource_no_name(self) -> None:
@@ -117,7 +117,7 @@ def test_build_user_resource_no_name(self) -> None:
         user = _make_mock_user(personal_name=None)
         result = provider.build_user_resource(user, None)
 
-        assert result.name is None
+        assert result.name == ScimName(givenName="", familyName="", formatted="")
         assert result.displayName is None
 
     def test_build_user_resource_scim_username_preserves_case(self) -> None:
diff --git a/backend/tests/unit/onyx/server/scim/test_user_endpoints.py b/backend/tests/unit/onyx/server/scim/test_user_endpoints.py
index d0d70b867d0..b1bd5e07fa9 100644
--- a/backend/tests/unit/onyx/server/scim/test_user_endpoints.py
+++ b/backend/tests/unit/onyx/server/scim/test_user_endpoints.py
@@ -214,13 +214,16 @@ def test_success(
         mock_dal.add_user.assert_called_once()
         mock_dal.commit.assert_called_once()
 
-    def test_missing_external_id_returns_400(
+    @patch("ee.onyx.server.scim.api._check_seat_availability", return_value=None)
+    def test_missing_external_id_creates_user_without_mapping(
         self,
+        mock_seats: MagicMock,  # noqa: ARG002
         mock_db_session: MagicMock,
         mock_token: MagicMock,
-        mock_dal: MagicMock,  # noqa: ARG002
+        mock_dal: MagicMock,
         provider: ScimProvider,
     ) -> None:
+        mock_dal.get_user_by_email.return_value = None
         resource = make_scim_user(externalId=None)
 
         result = create_user(
@@ -230,7 +233,11 @@ def test_missing_external_id_returns_400(
             db_session=mock_db_session,
         )
 
-        assert_scim_error(result, 400)
+        parsed = parse_scim_user(result, status=201)
+        assert parsed.userName is not None
+        mock_dal.add_user.assert_called_once()
+        mock_dal.create_user_mapping.assert_not_called()
+        mock_dal.commit.assert_called_once()
 
     @patch("ee.onyx.server.scim.api._check_seat_availability", return_value=None)
     def test_duplicate_email_returns_409(

From 71a1faa47ec44bf6aba38c66233a27ed9f4ae6e4 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 15:47:35 -0800
Subject: [PATCH 030/267] fix(fe): break long words in human messages (#8929)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
---
 web/src/app/app/message/HumanMessage.tsx      |  2 +-
 web/tailwind-themes/tailwind.config.js        |  7 ++++
 .../e2e/chat/chat_message_rendering.spec.ts   | 33 +++++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/web/src/app/app/message/HumanMessage.tsx b/web/src/app/app/message/HumanMessage.tsx
index bedd8f2c841..097145cd20e 100644
--- a/web/src/app/app/message/HumanMessage.tsx
+++ b/web/src/app/app/message/HumanMessage.tsx
@@ -195,7 +195,7 @@ const HumanMessage = React.memo(function HumanMessage({
             <div className="md:max-w-[37.5rem] flex basis-[100%] md:basis-auto justify-end md:order-1">
               <div
                 className={
-                  "max-w-[30rem] md:max-w-[37.5rem] whitespace-break-spaces rounded-t-16 rounded-bl-16 bg-background-tint-02 py-2 px-3"
+                  "max-w-[30rem] md:max-w-[37.5rem] whitespace-break-spaces break-anywhere rounded-t-16 rounded-bl-16 bg-background-tint-02 py-2 px-3"
                 }
                 onCopy={(e) => {
                   const selection = window.getSelection();
diff --git a/web/tailwind-themes/tailwind.config.js b/web/tailwind-themes/tailwind.config.js
index 261c192ca6f..ca3d2d75e04 100644
--- a/web/tailwind-themes/tailwind.config.js
+++ b/web/tailwind-themes/tailwind.config.js
@@ -370,5 +370,12 @@ module.exports = {
     plugin(({ addVariant }) => {
       addVariant("focus-within-nonactive", "&:focus-within:not(:active)");
     }),
+    plugin(({ addUtilities }) => {
+      addUtilities({
+        ".break-anywhere": {
+          "overflow-wrap": "anywhere",
+        },
+      });
+    }),
   ],
 };
diff --git a/web/tests/e2e/chat/chat_message_rendering.spec.ts b/web/tests/e2e/chat/chat_message_rendering.spec.ts
index 018011725cc..99229ca81c8 100644
--- a/web/tests/e2e/chat/chat_message_rendering.spec.ts
+++ b/web/tests/e2e/chat/chat_message_rendering.spec.ts
@@ -6,6 +6,9 @@ import { expectElementScreenshot } from "@tests/e2e/utils/visualRegression";
 
 const SHORT_USER_MESSAGE = "What is Onyx?";
 
+const LONG_WORD_USER_MESSAGE =
+  "Please look into this issue: __________________________________________ and also this token: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA and this URL: https://example.com/a/very/long/path/that/keeps/going/and/going/and/going/without/any/breaks/whatsoever/to/test/overflow";
+
 const LONG_USER_MESSAGE = `I've been evaluating several enterprise search and AI platforms for our organization, and I have a number of detailed questions about Onyx that I'd like to understand before we make a decision.
 
 First, can you explain how Onyx handles document indexing across multiple data sources? We currently use Confluence, Google Drive, Slack, and GitHub, and we need to ensure that all of these can be indexed simultaneously without performance degradation.
@@ -369,6 +372,36 @@ for (const theme of THEMES) {
         );
       });
 
+      test("user message with very long words wraps without overflowing", async ({
+        page,
+      }) => {
+        await openChat(page);
+        await mockChatEndpoint(page, SHORT_AI_RESPONSE);
+
+        await sendMessage(page, LONG_WORD_USER_MESSAGE);
+
+        const userMessage = page.locator("#onyx-human-message").first();
+        await expect(userMessage).toContainText("__________");
+
+        await screenshotChatContainer(
+          page,
+          `chat-long-word-user-message-${theme}`
+        );
+
+        // Assert the message bubble does not overflow horizontally.
+        const overflows = await userMessage.evaluate((el) => {
+          const bubble = el.querySelector<HTMLElement>(
+            ".whitespace-break-spaces"
+          );
+          if (!bubble)
+            throw new Error(
+              "Expected human message bubble (.whitespace-break-spaces) to exist"
+            );
+          return bubble.scrollWidth > bubble.offsetWidth;
+        });
+        expect(overflows).toBe(false);
+      });
+
       test("long user message with long AI response renders correctly", async ({
         page,
       }) => {

From 6cfd49439a8637ddab60c29c5f36b911d493926c Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Mon, 2 Mar 2026 15:49:58 -0800
Subject: [PATCH 031/267] chore: Bump code interpreter to 0.3.1 (#8937)

---
 deployment/helm/charts/onyx/Chart.lock | 6 +++---
 deployment/helm/charts/onyx/Chart.yaml | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/deployment/helm/charts/onyx/Chart.lock b/deployment/helm/charts/onyx/Chart.lock
index 7ca59d8f8e9..979ac2e3b88 100644
--- a/deployment/helm/charts/onyx/Chart.lock
+++ b/deployment/helm/charts/onyx/Chart.lock
@@ -19,6 +19,6 @@ dependencies:
   version: 5.4.0
 - name: code-interpreter
   repository: https://onyx-dot-app.github.io/python-sandbox/
-  version: 0.3.0
-digest: sha256:cf8f01906d46034962c6ce894770621ee183ac761e6942951118aeb48540eddd
-generated: "2026-02-24T10:59:38.78318-08:00"
+  version: 0.3.1
+digest: sha256:4965b6ea3674c37163832a2192cd3bc8004f2228729fca170af0b9f457e8f987
+generated: "2026-03-02T15:29:39.632344-08:00"
diff --git a/deployment/helm/charts/onyx/Chart.yaml b/deployment/helm/charts/onyx/Chart.yaml
index 1c6ddeb5325..8e3459577a6 100644
--- a/deployment/helm/charts/onyx/Chart.yaml
+++ b/deployment/helm/charts/onyx/Chart.yaml
@@ -45,6 +45,6 @@ dependencies:
     repository: https://charts.min.io/
     condition: minio.enabled
   - name: code-interpreter
-    version: 0.3.0
+    version: 0.3.1
     repository: https://onyx-dot-app.github.io/python-sandbox/
     condition: codeInterpreter.enabled

From 4fc802e19d81e8459776810a0a9d974cc8806089 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 2 Mar 2026 23:55:34 +0000
Subject: [PATCH 032/267] chore(deps): bump pypdf from 6.7.4 to 6.7.5 (#8932)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt | 2 +-
 pyproject.toml                   | 2 +-
 uv.lock                          | 8 ++++----
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index efdbad05411..59a94f1d976 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -809,7 +809,7 @@ pypandoc-binary==1.16.2
     # via onyx
 pyparsing==3.2.5
     # via httplib2
-pypdf==6.7.4
+pypdf==6.7.5
     # via
     #   onyx
     #   unstructured-client
diff --git a/pyproject.toml b/pyproject.toml
index f0cfd09feac..5b3d8710e58 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -92,7 +92,7 @@ backend = [
     "python-gitlab==5.6.0",
     "python-pptx==0.6.23",
     "pypandoc_binary==1.16.2",
-    "pypdf==6.7.4",
+    "pypdf==6.7.5",
     "pytest-mock==3.12.0",
     "pytest-playwright==0.7.0",
     "python-docx==1.1.2",
diff --git a/uv.lock b/uv.lock
index ad93c9ebc18..d843f03b9ae 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4678,7 +4678,7 @@ requires-dist = [
     { name = "pygithub", marker = "extra == 'backend'", specifier = "==2.5.0" },
     { name = "pympler", marker = "extra == 'backend'", specifier = "==1.1" },
     { name = "pypandoc-binary", marker = "extra == 'backend'", specifier = "==1.16.2" },
-    { name = "pypdf", marker = "extra == 'backend'", specifier = "==6.7.4" },
+    { name = "pypdf", marker = "extra == 'backend'", specifier = "==6.7.5" },
     { name = "pytest", marker = "extra == 'dev'", specifier = "==8.3.5" },
     { name = "pytest-alembic", marker = "extra == 'dev'", specifier = "==0.12.1" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = "==1.3.0" },
@@ -5925,11 +5925,11 @@ wheels = [
 
 [[package]]
 name = "pypdf"
-version = "6.7.4"
+version = "6.7.5"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/09/dc/f52deef12797ad58b88e4663f097a343f53b9361338aef6573f135ac302f/pypdf-6.7.4.tar.gz", hash = "sha256:9edd1cd47938bb35ec87795f61225fd58a07cfaf0c5699018ae1a47d6f8ab0e3", size = 5304821, upload-time = "2026-02-27T10:44:39.395Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/52/37cc0aa9e9d1bf7729a737a0d83f8b3f851c8eb137373d9f71eafb0a3405/pypdf-6.7.5.tar.gz", hash = "sha256:40bb2e2e872078655f12b9b89e2f900888bb505e88a82150b64f9f34fa25651d", size = 5304278, upload-time = "2026-03-02T09:05:21.464Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c1/be/cded021305f5c81b47265b8c5292b99388615a4391c21ff00fd538d34a56/pypdf-6.7.4-py3-none-any.whl", hash = "sha256:527d6da23274a6c70a9cb59d1986d93946ba8e36a6bc17f3f7cce86331492dda", size = 331496, upload-time = "2026-02-27T10:44:37.527Z" },
+    { url = "https://files.pythonhosted.org/packages/05/89/336673efd0a88956562658aba4f0bbef7cb92a6fbcbcaf94926dbc82b408/pypdf-6.7.5-py3-none-any.whl", hash = "sha256:07ba7f1d6e6d9aa2a17f5452e320a84718d4ce863367f7ede2fd72280349ab13", size = 331421, upload-time = "2026-03-02T09:05:19.722Z" },
 ]
 
 [[package]]

From a84f8238ecc93216de6af093e47c326e61832c7a Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 2 Mar 2026 15:56:08 -0800
Subject: [PATCH 033/267] chore(fe): space between Manage All connectors button
 (#8938)

---
 .../admin/ChatPreferencesPage.tsx             | 41 +++++++++++--------
 1 file changed, 24 insertions(+), 17 deletions(-)

diff --git a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
index 131c33ccd13..a0a8ae8343f 100644
--- a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
+++ b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
@@ -472,7 +472,7 @@ function ChatPreferencesForm() {
 
                   <Section
                     flexDirection="row"
-                    justifyContent="start"
+                    justifyContent="between"
                     alignItems="center"
                     gap={0.25}
                   >
@@ -480,22 +480,29 @@ function ChatPreferencesForm() {
                       <EmptyMessage title="No connectors set up" />
                     ) : (
                       <>
-                        {uniqueSources.slice(0, 3).map((source) => {
-                          const meta = getSourceMetadata(source);
-                          return (
-                            <Card
-                              key={source}
-                              padding={0.75}
-                              className="w-[10rem]"
-                            >
-                              <Content
-                                icon={meta.icon}
-                                title={meta.displayName}
-                                sizePreset="main-ui"
-                              />
-                            </Card>
-                          );
-                        })}
+                        <Section
+                          flexDirection="row"
+                          justifyContent="start"
+                          alignItems="center"
+                          gap={0.25}
+                        >
+                          {uniqueSources.slice(0, 3).map((source) => {
+                            const meta = getSourceMetadata(source);
+                            return (
+                              <Card
+                                key={source}
+                                padding={0.75}
+                                className="w-[10rem]"
+                              >
+                                <Content
+                                  icon={meta.icon}
+                                  title={meta.displayName}
+                                  sizePreset="main-ui"
+                                />
+                              </Card>
+                            );
+                          })}
+                        </Section>
 
                         <Button
                           href="/admin/indexing/status"

From 700ca0e0fc83d2e22d38930d818e92aefa659973 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Mon, 2 Mar 2026 16:08:17 -0800
Subject: [PATCH 034/267] fix: Sticky background in CSV Preview Variant (#8939)

---
 web/src/sections/modals/PreviewModal/variants/csvVariant.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx b/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx
index e9638aff310..c9d18954a01 100644
--- a/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx
@@ -46,7 +46,7 @@ export const csvVariant: PreviewVariant = {
     return (
       <Section justifyContent="start" alignItems="start" padding={1}>
         <Table>
-          <TableHeader className="sticky top-0 z-sticky">
+          <TableHeader className="sticky top-0 z-sticky bg-background-tint-01">
             <TableRow noHover>
               {headers.map((h: string, i: number) => (
                 <TableHead key={i}>
@@ -64,7 +64,7 @@ export const csvVariant: PreviewVariant = {
                   <TableCell
                     key={cIdx}
                     className={cn(
-                      cIdx === 0 && "sticky left-0",
+                      cIdx === 0 && "sticky left-0 bg-background-tint-01",
                       "py-4 px-4 whitespace-normal break-words"
                     )}
                   >

From fe014776f7aa27f111fe9e9be935f3c207819f90 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Mon, 2 Mar 2026 16:57:56 -0800
Subject: [PATCH 035/267] feat: embed code interpreter images in chat (#8875)

---
 .../files/images/InMessageImage.tsx           | 28 ++++++++++----
 .../app/app/components/files/images/utils.ts  | 18 +++++++++
 .../messageComponents/markdownUtils.tsx       | 38 +++++++++++++------
 3 files changed, 65 insertions(+), 19 deletions(-)

diff --git a/web/src/app/app/components/files/images/InMessageImage.tsx b/web/src/app/app/components/files/images/InMessageImage.tsx
index 118ef40b1ff..41e690c094f 100644
--- a/web/src/app/app/components/files/images/InMessageImage.tsx
+++ b/web/src/app/app/components/files/images/InMessageImage.tsx
@@ -1,5 +1,5 @@
-import { useState } from "react";
-import { FiDownload } from "react-icons/fi";
+import { memo, useState } from "react";
+import { SvgDownload } from "@opal/icons";
 import { ImageShape } from "@/app/app/services/streamingModels";
 import { FullImageModal } from "@/app/app/components/files/images/FullImageModal";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
@@ -24,17 +24,22 @@ const SHAPE_CLASSES: Record<ImageShape, { container: string; image: string }> =
     },
   };
 
+// Used to stop image flashing as images are loaded and response continues
+const loadedImages = new Set<string>();
+
 interface InMessageImageProps {
   fileId: string;
+  fileName?: string;
   shape?: ImageShape;
 }
 
-export function InMessageImage({
+export const InMessageImage = memo(function InMessageImage({
   fileId,
+  fileName,
   shape = DEFAULT_SHAPE,
 }: InMessageImageProps) {
   const [fullImageShowing, setFullImageShowing] = useState(false);
-  const [imageLoaded, setImageLoaded] = useState(false);
+  const [imageLoaded, setImageLoaded] = useState(loadedImages.has(fileId));
 
   const normalizedShape = SHAPE_CLASSES[shape] ? shape : DEFAULT_SHAPE;
   const { container: shapeContainerClasses, image: shapeImageClasses } =
@@ -45,11 +50,15 @@ export function InMessageImage({
 
     try {
       const response = await fetch(buildImgUrl(fileId));
+      if (!response.ok) {
+        console.error("Failed to download image:", response.status);
+        return;
+      }
       const blob = await response.blob();
       const url = window.URL.createObjectURL(blob);
       const a = document.createElement("a");
       a.href = url;
-      a.download = `image-${fileId}.png`; // You can adjust the filename/extension as needed
+      a.download = fileName || `image-${fileId}.png`;
       document.body.appendChild(a);
       a.click();
       window.URL.revokeObjectURL(url);
@@ -76,7 +85,10 @@ export function InMessageImage({
           width={1200}
           height={1200}
           alt="Chat Message Image"
-          onLoad={() => setImageLoaded(true)}
+          onLoad={() => {
+            loadedImages.add(fileId);
+            setImageLoaded(true);
+          }}
           className={cn(
             "object-contain object-left overflow-hidden rounded-lg w-full h-full transition-opacity duration-300 cursor-pointer",
             shapeImageClasses,
@@ -94,7 +106,7 @@ export function InMessageImage({
           )}
         >
           <Button
-            icon={FiDownload}
+            icon={SvgDownload}
             tooltip="Download"
             onClick={handleDownload}
           />
@@ -102,4 +114,4 @@ export function InMessageImage({
       </div>
     </>
   );
-}
+});
diff --git a/web/src/app/app/components/files/images/utils.ts b/web/src/app/app/components/files/images/utils.ts
index 5a18fd27004..affff012673 100644
--- a/web/src/app/app/components/files/images/utils.ts
+++ b/web/src/app/app/components/files/images/utils.ts
@@ -1,3 +1,21 @@
+const CHAT_FILE_URL_REGEX = /\/api\/chat\/file\/([^/?#]+)/;
+const IMAGE_EXTENSIONS = /\.(png|jpe?g|gif|webp|svg|bmp|ico|tiff?)$/i;
+
 export function buildImgUrl(fileId: string) {
   return `/api/chat/file/${fileId}`;
 }
+
+/**
+ * If `href` points to a chat file and `linkText` ends with an image extension,
+ * returns the file ID. Otherwise returns null.
+ */
+export function extractChatImageFileId(
+  href: string | undefined,
+  linkText: string
+): string | null {
+  if (!href) return null;
+  const match = CHAT_FILE_URL_REGEX.exec(href);
+  if (!match?.[1]) return null;
+  if (!IMAGE_EXTENSIONS.test(linkText)) return null;
+  return match[1];
+}
diff --git a/web/src/app/app/message/messageComponents/markdownUtils.tsx b/web/src/app/app/message/messageComponents/markdownUtils.tsx
index 618609c7b35..dd4b7bc5bb0 100644
--- a/web/src/app/app/message/messageComponents/markdownUtils.tsx
+++ b/web/src/app/app/message/messageComponents/markdownUtils.tsx
@@ -14,6 +14,8 @@ import {
 import { extractCodeText, preprocessLaTeX } from "@/app/app/message/codeUtils";
 import { CodeBlock } from "@/app/app/message/CodeBlock";
 import { transformLinkUri, cn } from "@/lib/utils";
+import { InMessageImage } from "@/app/app/components/files/images/InMessageImage";
+import { extractChatImageFileId } from "@/app/app/components/files/images/utils";
 
 /**
  * Processes content for markdown rendering by handling code blocks and LaTeX
@@ -58,17 +60,31 @@ export const useMarkdownComponents = (
   );
 
   const anchorCallback = useCallback(
-    (props: any) => (
-      <MemoizedAnchor
-        updatePresentingDocument={state?.setPresentingDocument || (() => {})}
-        docs={state?.docs || []}
-        userFiles={state?.userFiles || []}
-        citations={state?.citations}
-        href={props.href}
-      >
-        {props.children}
-      </MemoizedAnchor>
-    ),
+    (props: any) => {
+      const imageFileId = extractChatImageFileId(
+        props.href,
+        String(props.children ?? "")
+      );
+      if (imageFileId) {
+        return (
+          <InMessageImage
+            fileId={imageFileId}
+            fileName={String(props.children ?? "")}
+          />
+        );
+      }
+      return (
+        <MemoizedAnchor
+          updatePresentingDocument={state?.setPresentingDocument || (() => {})}
+          docs={state?.docs || []}
+          userFiles={state?.userFiles || []}
+          citations={state?.citations}
+          href={props.href}
+        >
+          {props.children}
+        </MemoizedAnchor>
+      );
+    },
     [
       state?.docs,
       state?.userFiles,

From d789c74024c7da070a3461c69af2c74850b06a02 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 2 Mar 2026 17:07:24 -0800
Subject: [PATCH 036/267] chore(icons): add `SvgBookmark` to `@opal/icons`
 (#8933)

---
 web/lib/opal/src/icons/bookmark.tsx | 20 ++++++++++++++++++++
 web/lib/opal/src/icons/index.ts     |  1 +
 2 files changed, 21 insertions(+)
 create mode 100644 web/lib/opal/src/icons/bookmark.tsx

diff --git a/web/lib/opal/src/icons/bookmark.tsx b/web/lib/opal/src/icons/bookmark.tsx
new file mode 100644
index 00000000000..9fe6417566f
--- /dev/null
+++ b/web/lib/opal/src/icons/bookmark.tsx
@@ -0,0 +1,20 @@
+import type { IconProps } from "@opal/types";
+const SvgBookmark = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M12.6667 14L7.99999 10.6667L3.33333 14V3.33333C3.33333 2.97971 3.4738 2.64057 3.72385 2.39052C3.9739 2.14048 4.31304 2 4.66666 2H11.3333C11.6869 2 12.0261 2.14048 12.2761 2.39052C12.5262 2.64057 12.6667 2.97971 12.6667 3.33333V14Z"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgBookmark;
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index 583ca87bca3..22509667b8a 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -25,6 +25,7 @@ export { default as SvgBarChartSmall } from "@opal/icons/bar-chart-small";
 export { default as SvgBell } from "@opal/icons/bell";
 export { default as SvgBlocks } from "@opal/icons/blocks";
 export { default as SvgBookOpen } from "@opal/icons/book-open";
+export { default as SvgBookmark } from "@opal/icons/bookmark";
 export { default as SvgBooksLineSmall } from "@opal/icons/books-line-small";
 export { default as SvgBooksStackSmall } from "@opal/icons/books-stack-small";
 export { default as SvgBracketCurly } from "@opal/icons/bracket-curly";

From 21ec93663b9c55efaf87c2032829afa992041575 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 2 Mar 2026 17:43:15 -0800
Subject: [PATCH 037/267] chore: proxy cloud ph (#8961)

---
 web/next.config.js        | 10 ++++++++++
 web/src/app/providers.tsx |  8 ++++----
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/web/next.config.js b/web/next.config.js
index 59fb98ab0ce..75e16a3bbfb 100644
--- a/web/next.config.js
+++ b/web/next.config.js
@@ -78,6 +78,16 @@ const nextConfig = {
   },
   async rewrites() {
     return [
+      {
+        source: "/ph_ingest/static/:path*",
+        destination: "https://us-assets.i.posthog.com/static/:path*",
+      },
+      {
+        source: "/ph_ingest/:path*",
+        destination: `${
+          process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com"
+        }/:path*`,
+      },
       {
         source: "/api/docs/:path*", // catch /api/docs and /api/docs/...
         destination: `${
diff --git a/web/src/app/providers.tsx b/web/src/app/providers.tsx
index 62c2d2dff7e..87b7cde79dc 100644
--- a/web/src/app/providers.tsx
+++ b/web/src/app/providers.tsx
@@ -3,9 +3,7 @@ import posthog from "posthog-js";
 import { PostHogProvider } from "posthog-js/react";
 import { useEffect } from "react";
 
-const isPostHogEnabled = !!(
-  process.env.NEXT_PUBLIC_POSTHOG_KEY && process.env.NEXT_PUBLIC_POSTHOG_HOST
-);
+const isPostHogEnabled = !!process.env.NEXT_PUBLIC_POSTHOG_KEY;
 
 type PHProviderProps = { children: React.ReactNode };
 
@@ -13,7 +11,9 @@ export function PHProvider({ children }: PHProviderProps) {
   useEffect(() => {
     if (isPostHogEnabled) {
       posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
-        api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST!,
+        api_host: "/ph_ingest",
+        ui_host:
+          process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.posthog.com",
         person_profiles: "identified_only",
         capture_pageview: false,
         session_recording: {

From f380a75df3ad7dcf1b60605880d95171a1184eaf Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Mon, 2 Mar 2026 17:58:45 -0800
Subject: [PATCH 038/267] fix: Non-intuitive llm auth exceptions (#8960)

---
 .../llm/litellm_singleton/monkey_patches.py   | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/backend/onyx/llm/litellm_singleton/monkey_patches.py b/backend/onyx/llm/litellm_singleton/monkey_patches.py
index 78587bd3dff..8feb6329fd9 100644
--- a/backend/onyx/llm/litellm_singleton/monkey_patches.py
+++ b/backend/onyx/llm/litellm_singleton/monkey_patches.py
@@ -67,6 +67,18 @@
    STATUS: STILL NEEDED - litellm_core_utils/litellm_logging.py lines 3185-3199 set
            usage as a dict with chat completion format instead of keeping it as
            ResponseAPIUsage. Our patch creates a deep copy before modification.
+
+7. Responses API metadata=None TypeError (_patch_responses_metadata_none):
+   - LiteLLM's @client decorator wrapper in utils.py uses kwargs.get("metadata", {})
+     to check for router calls, but when metadata is explicitly None (key exists with
+     value None), the default {} is not used
+   - This causes "argument of type 'NoneType' is not iterable" TypeError which swallows
+     the real exception (e.g. AuthenticationError for wrong API key)
+   - Surfaces as: APIConnectionError: OpenAIException - argument of type 'NoneType' is
+     not iterable
+   STATUS: STILL NEEDED - litellm/utils.py wrapper function (line 1721) does not guard
+           against metadata being explicitly None. Triggered when Responses API bridge
+           passes **litellm_params containing metadata=None.
 """
 
 import time
@@ -725,6 +737,44 @@ def _patched_get_assembled_streaming_response(
     LiteLLMLoggingObj._get_assembled_streaming_response = _patched_get_assembled_streaming_response  # type: ignore[method-assign]
 
 
+def _patch_responses_metadata_none() -> None:
+    """
+    Patches litellm.responses to normalize metadata=None to metadata={} in kwargs.
+
+    LiteLLM's @client decorator wrapper in utils.py (line 1721) does:
+        _is_litellm_router_call = "model_group" in kwargs.get("metadata", {})
+    When metadata is explicitly None in kwargs, kwargs.get("metadata", {}) returns
+    None (the key exists, so the default is not used), causing:
+        TypeError: argument of type 'NoneType' is not iterable
+
+    This swallows the real exception (e.g. AuthenticationError) and surfaces as:
+        APIConnectionError: OpenAIException - argument of type 'NoneType' is not iterable
+
+    This happens when the Responses API bridge calls litellm.responses() with
+    **litellm_params which may contain metadata=None.
+
+    STATUS: STILL NEEDED - litellm/utils.py wrapper function uses kwargs.get("metadata", {})
+            which does not guard against metadata being explicitly None. Same pattern exists
+            on line 1407 for async path.
+    """
+    import litellm as _litellm
+    from functools import wraps
+
+    original_responses = _litellm.responses
+
+    if getattr(original_responses, "_metadata_patched", False):
+        return
+
+    @wraps(original_responses)
+    def _patched_responses(*args: Any, **kwargs: Any) -> Any:
+        if kwargs.get("metadata") is None:
+            kwargs["metadata"] = {}
+        return original_responses(*args, **kwargs)
+
+    _patched_responses._metadata_patched = True  # type: ignore[attr-defined]
+    _litellm.responses = _patched_responses
+
+
 def apply_monkey_patches() -> None:
     """
     Apply all necessary monkey patches to LiteLLM for compatibility.
@@ -736,6 +786,7 @@ def apply_monkey_patches() -> None:
     - Patching AzureOpenAIResponsesAPIConfig.should_fake_stream to enable native streaming
     - Patching ResponsesAPIResponse.model_construct to fix usage format in all code paths
     - Patching LiteLLMLoggingObj._get_assembled_streaming_response to avoid mutating original response
+    - Patching litellm.responses to fix metadata=None causing TypeError in error handling
     """
     _patch_ollama_chunk_parser()
     _patch_openai_responses_parallel_tool_calls()
@@ -743,3 +794,4 @@ def apply_monkey_patches() -> None:
     _patch_azure_responses_should_fake_stream()
     _patch_responses_api_usage_format()
     _patch_logging_assembled_streaming_response()
+    _patch_responses_metadata_none()

From be8b108ae4674106ef153d0316de5ec622018c20 Mon Sep 17 00:00:00 2001
From: Jessica Singh <86633231+jessicasingh7@users.noreply.github.com>
Date: Mon, 2 Mar 2026 18:34:04 -0800
Subject: [PATCH 039/267] chore(auth): ecs fargate deployment cleanup (#8589)

---
 .../aws_ecs_fargate/cloudformation/onyx_cluster_template.yaml | 4 +++-
 .../services/onyx_backend_api_server_service_template.yaml    | 4 +++-
 .../onyx_backend_background_server_service_template.yaml      | 4 +++-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/deployment/aws_ecs_fargate/cloudformation/onyx_cluster_template.yaml b/deployment/aws_ecs_fargate/cloudformation/onyx_cluster_template.yaml
index 2b30a53165d..c8639376313 100644
--- a/deployment/aws_ecs_fargate/cloudformation/onyx_cluster_template.yaml
+++ b/deployment/aws_ecs_fargate/cloudformation/onyx_cluster_template.yaml
@@ -126,7 +126,9 @@ Resources:
               - Effect: Allow
                 Action:
                   - secretsmanager:GetSecretValue
-                Resource: !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/postgres/user/password-*
+                Resource:
+                  - !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/postgres/user/password-*
+                  - !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/onyx/user-auth-secret-*
 
 Outputs:
   OutputEcsCluster:
diff --git a/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_api_server_service_template.yaml b/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_api_server_service_template.yaml
index d0d949f16b4..1d948e1a5b2 100644
--- a/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_api_server_service_template.yaml
+++ b/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_api_server_service_template.yaml
@@ -167,10 +167,12 @@ Resources:
                 - ImportedNamespace: !ImportValue
                     Fn::Sub: "${Environment}-onyx-cluster-OnyxNamespaceName"
             - Name: AUTH_TYPE
-              Value: disabled
+              Value: basic
           Secrets:
             - Name: POSTGRES_PASSWORD
               ValueFrom: !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/postgres/user/password
+            - Name: USER_AUTH_SECRET
+              ValueFrom: !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/onyx/user-auth-secret
           VolumesFrom: []
           SystemControls: []
 
diff --git a/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_background_server_service_template.yaml b/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_background_server_service_template.yaml
index 34333bcc212..79ea204d85f 100644
--- a/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_background_server_service_template.yaml
+++ b/deployment/aws_ecs_fargate/cloudformation/services/onyx_backend_background_server_service_template.yaml
@@ -166,9 +166,11 @@ Resources:
                 - ImportedNamespace: !ImportValue
                     Fn::Sub: "${Environment}-onyx-cluster-OnyxNamespaceName"
             - Name: AUTH_TYPE
-              Value: disabled
+              Value: basic
           Secrets:
             - Name: POSTGRES_PASSWORD
               ValueFrom: !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/postgres/user/password
+            - Name: USER_AUTH_SECRET
+              ValueFrom: !Sub arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${Environment}/onyx/user-auth-secret
           VolumesFrom: []
           SystemControls: []

From 24ac8b37d3ec64cff9e6c703a664a06aeefd61a7 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 2 Mar 2026 19:11:18 -0800
Subject: [PATCH 040/267] refactor(fe): define settings layout width presets as
 CSS variables (#8936)

---
 web/src/app/css/sizes.css            |  6 ++++++
 web/src/layouts/settings-layouts.tsx | 16 ++++++++++------
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/web/src/app/css/sizes.css b/web/src/app/css/sizes.css
index ddec3c7bd8f..6af016b9a33 100644
--- a/web/src/app/css/sizes.css
+++ b/web/src/app/css/sizes.css
@@ -1,4 +1,10 @@
 :root {
   --app-page-main-content-width: 52.5rem;
   --block-width-form-input-min: 10rem;
+
+  --container-sm: 42rem;
+  --container-sm-md: 47rem;
+  --container-md: 54.5rem;
+  --container-lg: 62rem;
+  --container-full: 100%;
 }
diff --git a/web/src/layouts/settings-layouts.tsx b/web/src/layouts/settings-layouts.tsx
index 734e51071b4..fccb163c93f 100644
--- a/web/src/layouts/settings-layouts.tsx
+++ b/web/src/layouts/settings-layouts.tsx
@@ -43,8 +43,11 @@ import { Content } from "@opal/layouts";
 import Spacer from "@/refresh-components/Spacer";
 
 const widthClasses = {
-  md: "w-[min(50rem,100%)]",
-  lg: "w-[min(60rem,100%)]",
+  sm: "w-[min(var(--container-sm),100%)]",
+  "sm-md": "w-[min(var(--container-sm-md),100%)]",
+  md: "w-[min(var(--container-md),100%)]",
+  lg: "w-[min(var(--container-lg),100%)]",
+  full: "w-[var(--container-full)]",
 };
 
 /**
@@ -57,18 +60,19 @@ const widthClasses = {
  * - Full height container with centered content
  * - Automatic overflow-y scrolling
  * - Contains the scroll container ID that Settings.Header uses for shadow detection
- * - Configurable width: "md" (50rem max) or "full" (full width with 4rem padding)
+ * - Configurable width via CSS variables defined in sizes.css:
+ *   "sm" (672px), "sm-md" (752px), "md" (872px, default), "lg" (992px), "full" (100%)
  *
  * @example
  * ```tsx
- * // Default medium width (50rem max)
+ * // Default medium width (872px max)
  * <SettingsLayouts.Root>
  *   <SettingsLayouts.Header {...} />
  *   <SettingsLayouts.Body>...</SettingsLayouts.Body>
  * </SettingsLayouts.Root>
  *
- * // Full width with padding
- * <SettingsLayouts.Root width="full">
+ * // Large width (992px max)
+ * <SettingsLayouts.Root width="lg">
  *   <SettingsLayouts.Header {...} />
  *   <SettingsLayouts.Body>...</SettingsLayouts.Body>
  * </SettingsLayouts.Root>

From fa29cc384990d052af0ccb8871d2266b5467e9a0 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Mon, 2 Mar 2026 20:33:47 -0800
Subject: [PATCH 041/267] feat: postgres cache backend (#8879)

---
 .../2664261bfaab_add_cache_store_table.py     |  37 ++
 backend/onyx/background/periodic_poller.py    |  20 ++
 backend/onyx/background/task_utils.py         |  35 +-
 backend/onyx/cache/factory.py                 |   8 +-
 backend/onyx/cache/interface.py               |  17 +-
 backend/onyx/cache/postgres_backend.py        | 323 ++++++++++++++++++
 backend/onyx/db/models.py                     |  22 ++
 .../cache/conftest.py                         |  57 ++++
 .../cache/test_cache_backend_parity.py        | 100 ++++++
 .../cache/test_postgres_cache_backend.py      | 229 +++++++++++++
 10 files changed, 837 insertions(+), 11 deletions(-)
 create mode 100644 backend/alembic/versions/2664261bfaab_add_cache_store_table.py
 create mode 100644 backend/onyx/cache/postgres_backend.py
 create mode 100644 backend/tests/external_dependency_unit/cache/conftest.py
 create mode 100644 backend/tests/external_dependency_unit/cache/test_cache_backend_parity.py
 create mode 100644 backend/tests/external_dependency_unit/cache/test_postgres_cache_backend.py

diff --git a/backend/alembic/versions/2664261bfaab_add_cache_store_table.py b/backend/alembic/versions/2664261bfaab_add_cache_store_table.py
new file mode 100644
index 00000000000..90d4bd9b1d7
--- /dev/null
+++ b/backend/alembic/versions/2664261bfaab_add_cache_store_table.py
@@ -0,0 +1,37 @@
+"""add cache_store table
+
+Revision ID: 2664261bfaab
+Revises: 4a1e4b1c89d2
+Create Date: 2026-02-27 00:00:00.000000
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "2664261bfaab"
+down_revision = "4a1e4b1c89d2"
+branch_labels: None = None
+depends_on: None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "cache_store",
+        sa.Column("key", sa.String(), nullable=False),
+        sa.Column("value", sa.LargeBinary(), nullable=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.PrimaryKeyConstraint("key"),
+    )
+    op.create_index(
+        "ix_cache_store_expires",
+        "cache_store",
+        ["expires_at"],
+        postgresql_where=sa.text("expires_at IS NOT NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_cache_store_expires", table_name="cache_store")
+    op.drop_table("cache_store")
diff --git a/backend/onyx/background/periodic_poller.py b/backend/onyx/background/periodic_poller.py
index f7a836e6dda..59f0eadce4d 100644
--- a/backend/onyx/background/periodic_poller.py
+++ b/backend/onyx/background/periodic_poller.py
@@ -59,6 +59,12 @@ def _run_auto_llm_update() -> None:
         sync_llm_models_from_github(db_session)
 
 
+def _run_cache_cleanup() -> None:
+    from onyx.cache.postgres_backend import cleanup_expired_cache_entries
+
+    cleanup_expired_cache_entries()
+
+
 def _run_scheduled_eval() -> None:
     from onyx.configs.app_configs import BRAINTRUST_API_KEY
     from onyx.configs.app_configs import SCHEDULED_EVAL_DATASET_NAMES
@@ -100,12 +106,26 @@ def _run_scheduled_eval() -> None:
             )
 
 
+_CACHE_CLEANUP_INTERVAL_SECONDS = 300
+
+
 def _build_periodic_tasks() -> list[_PeriodicTaskDef]:
+    from onyx.cache.interface import CacheBackendType
     from onyx.configs.app_configs import AUTO_LLM_CONFIG_URL
     from onyx.configs.app_configs import AUTO_LLM_UPDATE_INTERVAL_SECONDS
+    from onyx.configs.app_configs import CACHE_BACKEND
     from onyx.configs.app_configs import SCHEDULED_EVAL_DATASET_NAMES
 
     tasks: list[_PeriodicTaskDef] = []
+    if CACHE_BACKEND == CacheBackendType.POSTGRES:
+        tasks.append(
+            _PeriodicTaskDef(
+                name="cache-cleanup",
+                interval_seconds=_CACHE_CLEANUP_INTERVAL_SECONDS,
+                lock_id=PERIODIC_TASK_LOCK_BASE + 2,
+                run_fn=_run_cache_cleanup,
+            )
+        )
     if AUTO_LLM_CONFIG_URL:
         tasks.append(
             _PeriodicTaskDef(
diff --git a/backend/onyx/background/task_utils.py b/backend/onyx/background/task_utils.py
index 070b26b6701..0a93e35cc68 100644
--- a/backend/onyx/background/task_utils.py
+++ b/backend/onyx/background/task_utils.py
@@ -75,31 +75,41 @@ def _claim_next_processing_file(db_session: Session) -> UUID | None:
     return file_id
 
 
-def _claim_next_deleting_file(db_session: Session) -> UUID | None:
+def _claim_next_deleting_file(
+    db_session: Session,
+    exclude_ids: set[UUID] | None = None,
+) -> UUID | None:
     """Claim the next DELETING file.
 
     No status transition needed — the impl deletes the row on success.
     The short-lived FOR UPDATE lock prevents concurrent claims.
+    *exclude_ids* prevents re-processing the same file if the impl fails.
     """
-    file_id = db_session.execute(
+    stmt = (
         select(UserFile.id)
         .where(UserFile.status == UserFileStatus.DELETING)
         .order_by(UserFile.created_at)
         .limit(1)
         .with_for_update(skip_locked=True)
-    ).scalar_one_or_none()
-    # Commit to release the row lock promptly.
+    )
+    if exclude_ids:
+        stmt = stmt.where(UserFile.id.notin_(exclude_ids))
+    file_id = db_session.execute(stmt).scalar_one_or_none()
     db_session.commit()
     return file_id
 
 
-def _claim_next_sync_file(db_session: Session) -> UUID | None:
+def _claim_next_sync_file(
+    db_session: Session,
+    exclude_ids: set[UUID] | None = None,
+) -> UUID | None:
     """Claim the next file needing project/persona sync.
 
     No status transition needed — the impl clears the sync flags on
     success.  The short-lived FOR UPDATE lock prevents concurrent claims.
+    *exclude_ids* prevents re-processing the same file if the impl fails.
     """
-    file_id = db_session.execute(
+    stmt = (
         select(UserFile.id)
         .where(
             sa.and_(
@@ -113,7 +123,10 @@ def _claim_next_sync_file(db_session: Session) -> UUID | None:
         .order_by(UserFile.created_at)
         .limit(1)
         .with_for_update(skip_locked=True)
-    ).scalar_one_or_none()
+    )
+    if exclude_ids:
+        stmt = stmt.where(UserFile.id.notin_(exclude_ids))
+    file_id = db_session.execute(stmt).scalar_one_or_none()
     db_session.commit()
     return file_id
 
@@ -149,11 +162,13 @@ def drain_delete_loop(tenant_id: str) -> None:
     )
     from onyx.db.engine.sql_engine import get_session_with_current_tenant
 
+    seen: set[UUID] = set()
     while True:
         with get_session_with_current_tenant() as session:
-            file_id = _claim_next_deleting_file(session)
+            file_id = _claim_next_deleting_file(session, exclude_ids=seen)
         if file_id is None:
             break
+        seen.add(file_id)
         delete_user_file_impl(
             user_file_id=str(file_id),
             tenant_id=tenant_id,
@@ -168,11 +183,13 @@ def drain_project_sync_loop(tenant_id: str) -> None:
     )
     from onyx.db.engine.sql_engine import get_session_with_current_tenant
 
+    seen: set[UUID] = set()
     while True:
         with get_session_with_current_tenant() as session:
-            file_id = _claim_next_sync_file(session)
+            file_id = _claim_next_sync_file(session, exclude_ids=seen)
         if file_id is None:
             break
+        seen.add(file_id)
         project_sync_user_file_impl(
             user_file_id=str(file_id),
             tenant_id=tenant_id,
diff --git a/backend/onyx/cache/factory.py b/backend/onyx/cache/factory.py
index 02a231ac719..6b7c6694f50 100644
--- a/backend/onyx/cache/factory.py
+++ b/backend/onyx/cache/factory.py
@@ -12,9 +12,15 @@ def _build_redis_backend(tenant_id: str) -> CacheBackend:
     return RedisCacheBackend(redis_pool.get_client(tenant_id))
 
 
+def _build_postgres_backend(tenant_id: str) -> CacheBackend:
+    from onyx.cache.postgres_backend import PostgresCacheBackend
+
+    return PostgresCacheBackend(tenant_id)
+
+
 _BACKEND_BUILDERS: dict[CacheBackendType, Callable[[str], CacheBackend]] = {
     CacheBackendType.REDIS: _build_redis_backend,
-    # CacheBackendType.POSTGRES will be added in a follow-up PR.
+    CacheBackendType.POSTGRES: _build_postgres_backend,
 }
 
 
diff --git a/backend/onyx/cache/interface.py b/backend/onyx/cache/interface.py
index 3f19781d2b7..a78532a0187 100644
--- a/backend/onyx/cache/interface.py
+++ b/backend/onyx/cache/interface.py
@@ -1,6 +1,9 @@
 import abc
 from enum import Enum
 
+TTL_KEY_NOT_FOUND = -2
+TTL_NO_EXPIRY = -1
+
 
 class CacheBackendType(str, Enum):
     REDIS = "redis"
@@ -26,6 +29,14 @@ def release(self) -> None:
     def owned(self) -> bool:
         raise NotImplementedError
 
+    def __enter__(self) -> "CacheLock":
+        if not self.acquire():
+            raise RuntimeError("Failed to acquire lock")
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.release()
+
 
 class CacheBackend(abc.ABC):
     """Thin abstraction over a key-value cache with TTL, locks, and blocking lists.
@@ -65,7 +76,11 @@ def expire(self, key: str, seconds: int) -> None:
 
     @abc.abstractmethod
     def ttl(self, key: str) -> int:
-        """Return remaining TTL in seconds. -1 if no expiry, -2 if key missing."""
+        """Return remaining TTL in seconds.
+
+        Returns ``TTL_NO_EXPIRY`` (-1) if key exists without expiry,
+        ``TTL_KEY_NOT_FOUND`` (-2) if key is missing or expired.
+        """
         raise NotImplementedError
 
     # -- distributed lock --------------------------------------------------
diff --git a/backend/onyx/cache/postgres_backend.py b/backend/onyx/cache/postgres_backend.py
new file mode 100644
index 00000000000..03219761975
--- /dev/null
+++ b/backend/onyx/cache/postgres_backend.py
@@ -0,0 +1,323 @@
+"""PostgreSQL-backed ``CacheBackend`` for NO_VECTOR_DB deployments.
+
+Uses the ``cache_store`` table for key-value storage, PostgreSQL advisory locks
+for distributed locking, and a polling loop for the BLPOP pattern.
+"""
+
+import hashlib
+import struct
+import time
+import uuid
+from contextlib import AbstractContextManager
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+
+from sqlalchemy import delete
+from sqlalchemy import func
+from sqlalchemy import or_
+from sqlalchemy import select
+from sqlalchemy import update
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.orm import Session
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.interface import CacheLock
+from onyx.cache.interface import TTL_KEY_NOT_FOUND
+from onyx.cache.interface import TTL_NO_EXPIRY
+from onyx.db.models import CacheStore
+
+_LIST_KEY_PREFIX = "_q:"
+# ASCII: ':' (0x3A) < ';' (0x3B). Upper bound for range queries so [prefix+, prefix;)
+# captures all list-item keys (e.g. _q:mylist:123:uuid) without including other
+# lists whose names share a prefix (e.g. _q:mylist2:...).
+_LIST_KEY_RANGE_TERMINATOR = ";"
+_LIST_ITEM_TTL_SECONDS = 3600
+_LOCK_POLL_INTERVAL = 0.1
+_BLPOP_POLL_INTERVAL = 0.25
+
+
+def _list_item_key(key: str) -> str:
+    """Unique key for a list item. Timestamp for FIFO ordering; UUID prevents
+    collision when concurrent rpush calls occur within the same nanosecond.
+    """
+    return f"{_LIST_KEY_PREFIX}{key}:{time.time_ns()}:{uuid.uuid4().hex}"
+
+
+def _to_bytes(value: str | bytes | int | float) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    return str(value).encode()
+
+
+# ------------------------------------------------------------------
+# Lock
+# ------------------------------------------------------------------
+
+
+class PostgresCacheLock(CacheLock):
+    """Advisory-lock-based distributed lock.
+
+    Uses ``get_session_with_tenant`` for connection lifecycle.  The lock is tied
+    to the session's connection; releasing or closing the session frees it.
+
+    NOTE: Unlike Redis locks, advisory locks do not auto-expire after
+    ``timeout`` seconds.  They are released when ``release()`` is
+    called or when the session is closed.
+    """
+
+    def __init__(self, lock_id: int, timeout: float | None, tenant_id: str) -> None:
+        self._lock_id = lock_id
+        self._timeout = timeout
+        self._tenant_id = tenant_id
+        self._session_cm: AbstractContextManager[Session] | None = None
+        self._session: Session | None = None
+        self._acquired = False
+
+    def acquire(
+        self,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> bool:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        self._session_cm = get_session_with_tenant(tenant_id=self._tenant_id)
+        self._session = self._session_cm.__enter__()
+        try:
+            if not blocking:
+                return self._try_lock()
+
+            effective_timeout = blocking_timeout or self._timeout
+            deadline = (
+                (time.monotonic() + effective_timeout) if effective_timeout else None
+            )
+            while True:
+                if self._try_lock():
+                    return True
+                if deadline is not None and time.monotonic() >= deadline:
+                    return False
+                time.sleep(_LOCK_POLL_INTERVAL)
+        finally:
+            if not self._acquired:
+                self._close_session()
+
+    def release(self) -> None:
+        if not self._acquired or self._session is None:
+            return
+        try:
+            self._session.execute(select(func.pg_advisory_unlock(self._lock_id)))
+        finally:
+            self._acquired = False
+            self._close_session()
+
+    def owned(self) -> bool:
+        return self._acquired
+
+    def _close_session(self) -> None:
+        if self._session_cm is not None:
+            try:
+                self._session_cm.__exit__(None, None, None)
+            finally:
+                self._session_cm = None
+                self._session = None
+
+    def _try_lock(self) -> bool:
+        assert self._session is not None
+        result = self._session.execute(
+            select(func.pg_try_advisory_lock(self._lock_id))
+        ).scalar()
+        if result:
+            self._acquired = True
+            return True
+        return False
+
+
+# ------------------------------------------------------------------
+# Backend
+# ------------------------------------------------------------------
+
+
+class PostgresCacheBackend(CacheBackend):
+    """``CacheBackend`` backed by the ``cache_store`` table in PostgreSQL.
+
+    Each operation opens and closes its own database session so the backend
+    is safe to share across threads.  Tenant isolation is handled by
+    SQLAlchemy's ``schema_translate_map`` (set by ``get_session_with_tenant``).
+    """
+
+    def __init__(self, tenant_id: str) -> None:
+        self._tenant_id = tenant_id
+
+    # -- basic key/value ---------------------------------------------------
+
+    def get(self, key: str) -> bytes | None:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        stmt = select(CacheStore.value).where(
+            CacheStore.key == key,
+            or_(CacheStore.expires_at.is_(None), CacheStore.expires_at > func.now()),
+        )
+        with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+            value = session.execute(stmt).scalar_one_or_none()
+        if value is None:
+            return None
+        return bytes(value)
+
+    def set(
+        self,
+        key: str,
+        value: str | bytes | int | float,
+        ex: int | None = None,
+    ) -> None:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        value_bytes = _to_bytes(value)
+        expires_at = (
+            datetime.now(timezone.utc) + timedelta(seconds=ex)
+            if ex is not None
+            else None
+        )
+        stmt = (
+            pg_insert(CacheStore)
+            .values(key=key, value=value_bytes, expires_at=expires_at)
+            .on_conflict_do_update(
+                index_elements=[CacheStore.key],
+                set_={"value": value_bytes, "expires_at": expires_at},
+            )
+        )
+        with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+            session.execute(stmt)
+            session.commit()
+
+    def delete(self, key: str) -> None:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+            session.execute(delete(CacheStore).where(CacheStore.key == key))
+            session.commit()
+
+    def exists(self, key: str) -> bool:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        stmt = (
+            select(CacheStore.key)
+            .where(
+                CacheStore.key == key,
+                or_(
+                    CacheStore.expires_at.is_(None),
+                    CacheStore.expires_at > func.now(),
+                ),
+            )
+            .limit(1)
+        )
+        with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+            return session.execute(stmt).first() is not None
+
+    # -- TTL ---------------------------------------------------------------
+
+    def expire(self, key: str, seconds: int) -> None:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        new_exp = datetime.now(timezone.utc) + timedelta(seconds=seconds)
+        stmt = (
+            update(CacheStore).where(CacheStore.key == key).values(expires_at=new_exp)
+        )
+        with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+            session.execute(stmt)
+            session.commit()
+
+    def ttl(self, key: str) -> int:
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        stmt = select(CacheStore.expires_at).where(CacheStore.key == key)
+        with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+            result = session.execute(stmt).first()
+        if result is None:
+            return TTL_KEY_NOT_FOUND
+        expires_at: datetime | None = result[0]
+        if expires_at is None:
+            return TTL_NO_EXPIRY
+        remaining = (expires_at - datetime.now(timezone.utc)).total_seconds()
+        if remaining <= 0:
+            return TTL_KEY_NOT_FOUND
+        return int(remaining)
+
+    # -- distributed lock --------------------------------------------------
+
+    def lock(self, name: str, timeout: float | None = None) -> CacheLock:
+        return PostgresCacheLock(
+            self._lock_id_for(name), timeout, tenant_id=self._tenant_id
+        )
+
+    # -- blocking list (MCP OAuth BLPOP pattern) ---------------------------
+
+    def rpush(self, key: str, value: str | bytes) -> None:
+        self.set(_list_item_key(key), value, ex=_LIST_ITEM_TTL_SECONDS)
+
+    def blpop(self, keys: list[str], timeout: int = 0) -> tuple[bytes, bytes] | None:
+        if timeout <= 0:
+            raise ValueError(
+                "PostgresCacheBackend.blpop requires timeout > 0. "
+                "timeout=0 would block the calling thread indefinitely "
+                "with no way to interrupt short of process termination."
+            )
+        from onyx.db.engine.sql_engine import get_session_with_tenant
+
+        deadline = time.monotonic() + timeout
+        while True:
+            for key in keys:
+                lower = f"{_LIST_KEY_PREFIX}{key}:"
+                upper = f"{_LIST_KEY_PREFIX}{key}{_LIST_KEY_RANGE_TERMINATOR}"
+                stmt = (
+                    select(CacheStore)
+                    .where(
+                        CacheStore.key >= lower,
+                        CacheStore.key < upper,
+                        or_(
+                            CacheStore.expires_at.is_(None),
+                            CacheStore.expires_at > func.now(),
+                        ),
+                    )
+                    .order_by(CacheStore.key)
+                    .limit(1)
+                    .with_for_update(skip_locked=True)
+                )
+                with get_session_with_tenant(tenant_id=self._tenant_id) as session:
+                    row = session.execute(stmt).scalars().first()
+                    if row is not None:
+                        value = bytes(row.value) if row.value else b""
+                        session.delete(row)
+                        session.commit()
+                        return (key.encode(), value)
+            if time.monotonic() >= deadline:
+                return None
+            time.sleep(_BLPOP_POLL_INTERVAL)
+
+    # -- helpers -----------------------------------------------------------
+
+    def _lock_id_for(self, name: str) -> int:
+        """Map *name* to a 64-bit signed int for ``pg_advisory_lock``."""
+        h = hashlib.md5(f"{self._tenant_id}:{name}".encode()).digest()
+        return struct.unpack("q", h[:8])[0]
+
+
+# ------------------------------------------------------------------
+# Periodic cleanup
+# ------------------------------------------------------------------
+
+
+def cleanup_expired_cache_entries() -> None:
+    """Delete rows whose ``expires_at`` is in the past.
+
+    Called by the periodic poller every 5 minutes.
+    """
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+    with get_session_with_current_tenant() as session:
+        session.execute(
+            delete(CacheStore).where(
+                CacheStore.expires_at.is_not(None),
+                CacheStore.expires_at < func.now(),
+            )
+        )
+        session.commit()
diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index 5987385bfd3..ec381ba474e 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -4983,3 +4983,25 @@ class CodeInterpreterServer(Base):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True)
     server_enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+
+
+class CacheStore(Base):
+    """Key-value cache table used by ``PostgresCacheBackend``.
+
+    Replaces Redis for simple KV caching, locks, and list operations
+    when ``CACHE_BACKEND=postgres`` (NO_VECTOR_DB deployments).
+
+    Intentionally separate from ``KVStore``:
+    - Stores raw bytes (LargeBinary) vs JSONB, matching Redis semantics.
+    - Has ``expires_at`` for TTL; rows are periodically garbage-collected.
+    - Holds ephemeral data (tokens, stop signals, lock state) not
+      persistent application config, so cleanup can be aggressive.
+    """
+
+    __tablename__ = "cache_store"
+
+    key: Mapped[str] = mapped_column(String, primary_key=True)
+    value: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    expires_at: Mapped[datetime.datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
diff --git a/backend/tests/external_dependency_unit/cache/conftest.py b/backend/tests/external_dependency_unit/cache/conftest.py
new file mode 100644
index 00000000000..0bbdfd5139d
--- /dev/null
+++ b/backend/tests/external_dependency_unit/cache/conftest.py
@@ -0,0 +1,57 @@
+"""Fixtures for cache backend tests.
+
+Requires a running PostgreSQL instance (and Redis for parity tests).
+Run with::
+
+    python -m dotenv -f .vscode/.env run -- pytest tests/external_dependency_unit/cache/
+"""
+
+from collections.abc import Generator
+
+import pytest
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.postgres_backend import PostgresCacheBackend
+from onyx.cache.redis_backend import RedisCacheBackend
+from onyx.db.engine.sql_engine import SqlEngine
+from shared_configs.contextvars import CURRENT_TENANT_ID_CONTEXTVAR
+from tests.external_dependency_unit.constants import TEST_TENANT_ID
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _init_db() -> Generator[None, None, None]:
+    """Initialize DB engine. Assumes Postgres has migrations applied (e.g. via docker compose)."""
+    SqlEngine.init_engine(pool_size=5, max_overflow=2)
+    yield
+
+
+@pytest.fixture(autouse=True)
+def _tenant_context() -> Generator[None, None, None]:
+    token = CURRENT_TENANT_ID_CONTEXTVAR.set(TEST_TENANT_ID)
+    try:
+        yield
+    finally:
+        CURRENT_TENANT_ID_CONTEXTVAR.reset(token)
+
+
+@pytest.fixture
+def pg_cache() -> PostgresCacheBackend:
+    return PostgresCacheBackend(TEST_TENANT_ID)
+
+
+@pytest.fixture
+def redis_cache() -> RedisCacheBackend:
+    from onyx.redis.redis_pool import redis_pool
+
+    return RedisCacheBackend(redis_pool.get_client(TEST_TENANT_ID))
+
+
+@pytest.fixture(params=["postgres", "redis"], ids=["postgres", "redis"])
+def cache(
+    request: pytest.FixtureRequest,
+    pg_cache: PostgresCacheBackend,
+    redis_cache: RedisCacheBackend,
+) -> CacheBackend:
+    if request.param == "postgres":
+        return pg_cache
+    return redis_cache
diff --git a/backend/tests/external_dependency_unit/cache/test_cache_backend_parity.py b/backend/tests/external_dependency_unit/cache/test_cache_backend_parity.py
new file mode 100644
index 00000000000..7f1f0164d2c
--- /dev/null
+++ b/backend/tests/external_dependency_unit/cache/test_cache_backend_parity.py
@@ -0,0 +1,100 @@
+"""Parameterized tests that run the same CacheBackend operations against
+both Redis and PostgreSQL, asserting identical return values.
+
+Each test runs twice (once per backend) via the ``cache`` fixture defined
+in conftest.py.
+"""
+
+import time
+from uuid import uuid4
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.interface import TTL_KEY_NOT_FOUND
+from onyx.cache.interface import TTL_NO_EXPIRY
+
+
+def _key() -> str:
+    return f"parity_{uuid4().hex[:12]}"
+
+
+class TestKVParity:
+    def test_get_missing(self, cache: CacheBackend) -> None:
+        assert cache.get(_key()) is None
+
+    def test_get_set(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, b"value")
+        assert cache.get(k) == b"value"
+
+    def test_overwrite(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, b"a")
+        cache.set(k, b"b")
+        assert cache.get(k) == b"b"
+
+    def test_set_string(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, "hello")
+        assert cache.get(k) == b"hello"
+
+    def test_set_int(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, 42)
+        assert cache.get(k) == b"42"
+
+    def test_delete(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, b"x")
+        cache.delete(k)
+        assert cache.get(k) is None
+
+    def test_exists(self, cache: CacheBackend) -> None:
+        k = _key()
+        assert not cache.exists(k)
+        cache.set(k, b"x")
+        assert cache.exists(k)
+
+
+class TestTTLParity:
+    def test_ttl_missing(self, cache: CacheBackend) -> None:
+        assert cache.ttl(_key()) == TTL_KEY_NOT_FOUND
+
+    def test_ttl_no_expiry(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, b"x")
+        assert cache.ttl(k) == TTL_NO_EXPIRY
+
+    def test_ttl_remaining(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, b"x", ex=10)
+        remaining = cache.ttl(k)
+        assert 8 <= remaining <= 10
+
+    def test_set_with_ttl_expires(self, cache: CacheBackend) -> None:
+        k = _key()
+        cache.set(k, b"x", ex=1)
+        assert cache.get(k) == b"x"
+        time.sleep(1.5)
+        assert cache.get(k) is None
+
+
+class TestLockParity:
+    def test_acquire_release(self, cache: CacheBackend) -> None:
+        lock = cache.lock(f"parity_lock_{uuid4().hex[:8]}")
+        assert lock.acquire(blocking=False)
+        assert lock.owned()
+        lock.release()
+        assert not lock.owned()
+
+
+class TestListParity:
+    def test_rpush_blpop(self, cache: CacheBackend) -> None:
+        k = f"parity_list_{uuid4().hex[:8]}"
+        cache.rpush(k, b"item")
+        result = cache.blpop([k], timeout=1)
+        assert result is not None
+        assert result[1] == b"item"
+
+    def test_blpop_timeout(self, cache: CacheBackend) -> None:
+        result = cache.blpop([f"parity_empty_{uuid4().hex[:8]}"], timeout=1)
+        assert result is None
diff --git a/backend/tests/external_dependency_unit/cache/test_postgres_cache_backend.py b/backend/tests/external_dependency_unit/cache/test_postgres_cache_backend.py
new file mode 100644
index 00000000000..54975c54a5b
--- /dev/null
+++ b/backend/tests/external_dependency_unit/cache/test_postgres_cache_backend.py
@@ -0,0 +1,229 @@
+"""Tests for PostgresCacheBackend against real PostgreSQL.
+
+Covers every method on the backend: KV CRUD, TTL behaviour, advisory
+locks (acquire / release / contention), list operations (rpush / blpop),
+and the periodic cleanup function.
+"""
+
+import time
+from uuid import uuid4
+
+from sqlalchemy import select
+
+from onyx.cache.interface import TTL_KEY_NOT_FOUND
+from onyx.cache.interface import TTL_NO_EXPIRY
+from onyx.cache.postgres_backend import cleanup_expired_cache_entries
+from onyx.cache.postgres_backend import PostgresCacheBackend
+from onyx.db.models import CacheStore
+
+
+def _key() -> str:
+    return f"test_{uuid4().hex[:12]}"
+
+
+# ------------------------------------------------------------------
+# Basic KV
+# ------------------------------------------------------------------
+
+
+class TestKV:
+    def test_get_set(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"hello")
+        assert pg_cache.get(k) == b"hello"
+
+    def test_get_missing(self, pg_cache: PostgresCacheBackend) -> None:
+        assert pg_cache.get(_key()) is None
+
+    def test_set_overwrite(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"first")
+        pg_cache.set(k, b"second")
+        assert pg_cache.get(k) == b"second"
+
+    def test_set_string_value(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, "string_val")
+        assert pg_cache.get(k) == b"string_val"
+
+    def test_set_int_value(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, 42)
+        assert pg_cache.get(k) == b"42"
+
+    def test_delete(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"to_delete")
+        pg_cache.delete(k)
+        assert pg_cache.get(k) is None
+
+    def test_delete_missing_is_noop(self, pg_cache: PostgresCacheBackend) -> None:
+        pg_cache.delete(_key())
+
+    def test_exists(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        assert not pg_cache.exists(k)
+        pg_cache.set(k, b"x")
+        assert pg_cache.exists(k)
+
+
+# ------------------------------------------------------------------
+# TTL
+# ------------------------------------------------------------------
+
+
+class TestTTL:
+    def test_set_with_ttl_expires(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"ephemeral", ex=1)
+        assert pg_cache.get(k) == b"ephemeral"
+        time.sleep(1.5)
+        assert pg_cache.get(k) is None
+
+    def test_ttl_no_expiry(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"forever")
+        assert pg_cache.ttl(k) == TTL_NO_EXPIRY
+
+    def test_ttl_missing_key(self, pg_cache: PostgresCacheBackend) -> None:
+        assert pg_cache.ttl(_key()) == TTL_KEY_NOT_FOUND
+
+    def test_ttl_remaining(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"x", ex=10)
+        remaining = pg_cache.ttl(k)
+        assert 8 <= remaining <= 10
+
+    def test_ttl_expired_key(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"x", ex=1)
+        time.sleep(1.5)
+        assert pg_cache.ttl(k) == TTL_KEY_NOT_FOUND
+
+    def test_expire_adds_ttl(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"x")
+        assert pg_cache.ttl(k) == TTL_NO_EXPIRY
+        pg_cache.expire(k, 10)
+        assert 8 <= pg_cache.ttl(k) <= 10
+
+    def test_exists_respects_ttl(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"x", ex=1)
+        assert pg_cache.exists(k)
+        time.sleep(1.5)
+        assert not pg_cache.exists(k)
+
+
+# ------------------------------------------------------------------
+# Locks
+# ------------------------------------------------------------------
+
+
+class TestLock:
+    def test_acquire_release(self, pg_cache: PostgresCacheBackend) -> None:
+        lock = pg_cache.lock(f"lock_{uuid4().hex[:8]}")
+        assert lock.acquire(blocking=False)
+        assert lock.owned()
+        lock.release()
+        assert not lock.owned()
+
+    def test_contention(self, pg_cache: PostgresCacheBackend) -> None:
+        name = f"contention_{uuid4().hex[:8]}"
+        lock1 = pg_cache.lock(name)
+        lock2 = pg_cache.lock(name)
+
+        assert lock1.acquire(blocking=False)
+        assert not lock2.acquire(blocking=False)
+
+        lock1.release()
+        assert lock2.acquire(blocking=False)
+        lock2.release()
+
+    def test_context_manager(self, pg_cache: PostgresCacheBackend) -> None:
+        with pg_cache.lock(f"ctx_{uuid4().hex[:8]}") as lock:
+            assert lock.owned()
+        assert not lock.owned()
+
+    def test_blocking_timeout(self, pg_cache: PostgresCacheBackend) -> None:
+        name = f"timeout_{uuid4().hex[:8]}"
+        holder = pg_cache.lock(name)
+        holder.acquire(blocking=False)
+
+        waiter = pg_cache.lock(name, timeout=0.3)
+        start = time.monotonic()
+        assert not waiter.acquire(blocking=True, blocking_timeout=0.3)
+        elapsed = time.monotonic() - start
+        assert elapsed >= 0.25
+
+        holder.release()
+
+
+# ------------------------------------------------------------------
+# List (rpush / blpop)
+# ------------------------------------------------------------------
+
+
+class TestList:
+    def test_rpush_blpop(self, pg_cache: PostgresCacheBackend) -> None:
+        k = f"list_{uuid4().hex[:8]}"
+        pg_cache.rpush(k, b"item1")
+        result = pg_cache.blpop([k], timeout=1)
+        assert result is not None
+        assert result == (k.encode(), b"item1")
+
+    def test_blpop_timeout(self, pg_cache: PostgresCacheBackend) -> None:
+        result = pg_cache.blpop([f"empty_{uuid4().hex[:8]}"], timeout=1)
+        assert result is None
+
+    def test_fifo_order(self, pg_cache: PostgresCacheBackend) -> None:
+        k = f"fifo_{uuid4().hex[:8]}"
+        pg_cache.rpush(k, b"first")
+        time.sleep(0.01)
+        pg_cache.rpush(k, b"second")
+
+        r1 = pg_cache.blpop([k], timeout=1)
+        r2 = pg_cache.blpop([k], timeout=1)
+        assert r1 is not None and r1[1] == b"first"
+        assert r2 is not None and r2[1] == b"second"
+
+    def test_multiple_keys(self, pg_cache: PostgresCacheBackend) -> None:
+        k1 = f"mk1_{uuid4().hex[:8]}"
+        k2 = f"mk2_{uuid4().hex[:8]}"
+        pg_cache.rpush(k2, b"from_k2")
+
+        result = pg_cache.blpop([k1, k2], timeout=1)
+        assert result is not None
+        assert result == (k2.encode(), b"from_k2")
+
+
+# ------------------------------------------------------------------
+# Cleanup
+# ------------------------------------------------------------------
+
+
+class TestCleanup:
+    def test_removes_expired_rows(self, pg_cache: PostgresCacheBackend) -> None:
+        from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+        k = _key()
+        pg_cache.set(k, b"stale", ex=1)
+        time.sleep(1.5)
+        cleanup_expired_cache_entries()
+
+        stmt = select(CacheStore.key).where(CacheStore.key == k)
+        with get_session_with_current_tenant() as session:
+            row = session.execute(stmt).first()
+        assert row is None, "expired row should be physically deleted"
+
+    def test_preserves_unexpired_rows(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"fresh", ex=300)
+        cleanup_expired_cache_entries()
+        assert pg_cache.get(k) == b"fresh"
+
+    def test_preserves_no_ttl_rows(self, pg_cache: PostgresCacheBackend) -> None:
+        k = _key()
+        pg_cache.set(k, b"permanent")
+        cleanup_expired_cache_entries()
+        assert pg_cache.get(k) == b"permanent"

From 2c3e9aecd194139a4eb3573cf5a6d28fd5dc1aa3 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 2 Mar 2026 21:36:43 -0800
Subject: [PATCH 042/267] fix(scim): only list SCIM-managed users and link
 pre-existing users (#8959)

---
 ...d9e2f1c4_make_scim_external_id_nullable.py | 34 +++++++++
 backend/ee/onyx/db/scim.py                    | 64 +++++++++-------
 backend/ee/onyx/server/scim/api.py            | 76 +++++++++++++++----
 backend/ee/onyx/server/scim/providers/base.py |  5 +-
 backend/onyx/db/models.py                     |  4 +-
 .../unit/onyx/server/scim/test_providers.py   |  5 +-
 .../onyx/server/scim/test_user_endpoints.py   | 48 +++++++++++-
 7 files changed, 189 insertions(+), 47 deletions(-)
 create mode 100644 backend/alembic/versions/a3b8d9e2f1c4_make_scim_external_id_nullable.py

diff --git a/backend/alembic/versions/a3b8d9e2f1c4_make_scim_external_id_nullable.py b/backend/alembic/versions/a3b8d9e2f1c4_make_scim_external_id_nullable.py
new file mode 100644
index 00000000000..1d9cf7c3d70
--- /dev/null
+++ b/backend/alembic/versions/a3b8d9e2f1c4_make_scim_external_id_nullable.py
@@ -0,0 +1,34 @@
+"""make scim_user_mapping.external_id nullable
+
+Revision ID: a3b8d9e2f1c4
+Revises: 2664261bfaab
+Create Date: 2026-03-02
+
+"""
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision = "a3b8d9e2f1c4"
+down_revision = "2664261bfaab"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.alter_column(
+        "scim_user_mapping",
+        "external_id",
+        nullable=True,
+    )
+
+
+def downgrade() -> None:
+    # Delete any rows where external_id is NULL before re-applying NOT NULL
+    op.execute("DELETE FROM scim_user_mapping WHERE external_id IS NULL")
+    op.alter_column(
+        "scim_user_mapping",
+        "external_id",
+        nullable=False,
+    )
diff --git a/backend/ee/onyx/db/scim.py b/backend/ee/onyx/db/scim.py
index b9cbc5b2d22..498298b7299 100644
--- a/backend/ee/onyx/db/scim.py
+++ b/backend/ee/onyx/db/scim.py
@@ -126,12 +126,16 @@ def update_token_last_used(self, token_id: int) -> None:
 
     def create_user_mapping(
         self,
-        external_id: str,
+        external_id: str | None,
         user_id: UUID,
         scim_username: str | None = None,
         fields: ScimMappingFields | None = None,
     ) -> ScimUserMapping:
-        """Create a mapping between a SCIM externalId and an Onyx user."""
+        """Create a SCIM mapping for a user.
+
+        ``external_id`` may be ``None`` when the IdP omits it (RFC 7643
+        allows this). The mapping still marks the user as SCIM-managed.
+        """
         f = fields or ScimMappingFields()
         mapping = ScimUserMapping(
             external_id=external_id,
@@ -270,8 +274,13 @@ def list_users(
         Raises:
             ValueError: If the filter uses an unsupported attribute.
         """
-        query = select(User).where(
-            User.role.notin_([UserRole.SLACK_USER, UserRole.EXT_PERM_USER])
+        # Inner-join with ScimUserMapping so only SCIM-managed users appear.
+        # Pre-existing system accounts (anonymous, admin, etc.) are excluded
+        # unless they were explicitly linked via SCIM provisioning.
+        query = (
+            select(User)
+            .join(ScimUserMapping, ScimUserMapping.user_id == User.id)
+            .where(User.role.notin_([UserRole.SLACK_USER, UserRole.EXT_PERM_USER]))
         )
 
         if scim_filter:
@@ -321,34 +330,37 @@ def sync_user_external_id(
         scim_username: str | None = None,
         fields: ScimMappingFields | None = None,
     ) -> None:
-        """Create, update, or delete the external ID mapping for a user.
+        """Sync the SCIM mapping for a user.
+
+        If a mapping already exists, its fields are updated (including
+        setting ``external_id`` to ``None`` when the IdP omits it).
+        If no mapping exists and ``new_external_id`` is provided, a new
+        mapping is created.  A mapping is never deleted here — SCIM-managed
+        users must retain their mapping to remain visible in ``GET /Users``.
 
         When *fields* is provided, all mapping fields are written
         unconditionally — including ``None`` values — so that a caller can
         clear a previously-set field (e.g. removing a department).
         """
         mapping = self.get_user_mapping_by_user_id(user_id)
-        if new_external_id:
-            if mapping:
-                if mapping.external_id != new_external_id:
-                    mapping.external_id = new_external_id
-                if scim_username is not None:
-                    mapping.scim_username = scim_username
-                if fields is not None:
-                    mapping.department = fields.department
-                    mapping.manager = fields.manager
-                    mapping.given_name = fields.given_name
-                    mapping.family_name = fields.family_name
-                    mapping.scim_emails_json = fields.scim_emails_json
-            else:
-                self.create_user_mapping(
-                    external_id=new_external_id,
-                    user_id=user_id,
-                    scim_username=scim_username,
-                    fields=fields,
-                )
-        elif mapping:
-            self.delete_user_mapping(mapping.id)
+        if mapping:
+            if mapping.external_id != new_external_id:
+                mapping.external_id = new_external_id
+            if scim_username is not None:
+                mapping.scim_username = scim_username
+            if fields is not None:
+                mapping.department = fields.department
+                mapping.manager = fields.manager
+                mapping.given_name = fields.given_name
+                mapping.family_name = fields.family_name
+                mapping.scim_emails_json = fields.scim_emails_json
+        elif new_external_id:
+            self.create_user_mapping(
+                external_id=new_external_id,
+                user_id=user_id,
+                scim_username=scim_username,
+                fields=fields,
+            )
 
     def _get_user_mappings_batch(
         self, user_ids: list[UUID]
diff --git a/backend/ee/onyx/server/scim/api.py b/backend/ee/onyx/server/scim/api.py
index b8a5b8225e3..ef8cce40fbf 100644
--- a/backend/ee/onyx/server/scim/api.py
+++ b/backend/ee/onyx/server/scim/api.py
@@ -423,15 +423,63 @@ def create_user(
 
     email = user_resource.userName.strip()
 
-    # Enforce seat limit
+    # Check for existing user — if they exist but aren't SCIM-managed yet,
+    # link them to the IdP rather than rejecting with 409.
+    external_id: str | None = user_resource.externalId
+    scim_username: str = user_resource.userName.strip()
+    fields: ScimMappingFields = _fields_from_resource(user_resource)
+
+    existing_user = dal.get_user_by_email(email)
+    if existing_user:
+        existing_mapping = dal.get_user_mapping_by_user_id(existing_user.id)
+        if existing_mapping:
+            return _scim_error_response(409, f"User with email {email} already exists")
+
+        # Adopt pre-existing user into SCIM management.
+        # Reactivating a deactivated user consumes a seat, so enforce the
+        # seat limit the same way replace_user does.
+        if user_resource.active and not existing_user.is_active:
+            seat_error = _check_seat_availability(dal)
+            if seat_error:
+                return _scim_error_response(403, seat_error)
+
+        personal_name = _scim_name_to_str(user_resource.name)
+        dal.update_user(
+            existing_user,
+            is_active=user_resource.active,
+            **({"personal_name": personal_name} if personal_name else {}),
+        )
+
+        try:
+            dal.create_user_mapping(
+                external_id=external_id,
+                user_id=existing_user.id,
+                scim_username=scim_username,
+                fields=fields,
+            )
+            dal.commit()
+        except IntegrityError:
+            dal.rollback()
+            return _scim_error_response(
+                409, f"User with email {email} already has a SCIM mapping"
+            )
+
+        return _scim_resource_response(
+            provider.build_user_resource(
+                existing_user,
+                external_id,
+                scim_username=scim_username,
+                fields=fields,
+            ),
+            status_code=201,
+        )
+
+    # Only enforce seat limit for net-new users — adopting a pre-existing
+    # user doesn't consume a new seat.
     seat_error = _check_seat_availability(dal)
     if seat_error:
         return _scim_error_response(403, seat_error)
 
-    # Check for existing user
-    if dal.get_user_by_email(email):
-        return _scim_error_response(409, f"User with email {email} already exists")
-
     # Create user with a random password (SCIM users authenticate via IdP)
     personal_name = _scim_name_to_str(user_resource.name)
     user = User(
@@ -449,21 +497,21 @@ def create_user(
         dal.rollback()
         return _scim_error_response(409, f"User with email {email} already exists")
 
-    # Create SCIM mapping when externalId is provided — this is how the IdP
-    # correlates this user on subsequent requests.  Per RFC 7643, externalId
-    # is optional and assigned by the provisioning client.
-    external_id = user_resource.externalId
-    scim_username = user_resource.userName.strip()
-    fields = _fields_from_resource(user_resource)
-    if external_id:
+    # Always create a SCIM mapping so that the user is marked as
+    # SCIM-managed. externalId may be None (RFC 7643 says it's optional).
+    try:
         dal.create_user_mapping(
             external_id=external_id,
             user_id=user.id,
             scim_username=scim_username,
             fields=fields,
         )
-
-    dal.commit()
+        dal.commit()
+    except IntegrityError:
+        dal.rollback()
+        return _scim_error_response(
+            409, f"User with email {email} already has a SCIM mapping"
+        )
 
     return _scim_resource_response(
         provider.build_user_resource(
diff --git a/backend/ee/onyx/server/scim/providers/base.py b/backend/ee/onyx/server/scim/providers/base.py
index 8f738c0d134..af660b32e53 100644
--- a/backend/ee/onyx/server/scim/providers/base.py
+++ b/backend/ee/onyx/server/scim/providers/base.py
@@ -170,7 +170,10 @@ def build_scim_name(
                 formatted=user.personal_name or "",
             )
         if not user.personal_name:
-            return ScimName(givenName="", familyName="", formatted="")
+            # Derive a reasonable name from the email so that SCIM spec tests
+            # see non-empty givenName / familyName for every user resource.
+            local = user.email.split("@")[0] if user.email else ""
+            return ScimName(givenName=local, familyName="", formatted=local)
         parts = user.personal_name.split(" ", 1)
         return ScimName(
             givenName=parts[0],
diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index ec381ba474e..3d3f734d4de 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -4926,7 +4926,9 @@ class ScimUserMapping(Base):
     __tablename__ = "scim_user_mapping"
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True)
-    external_id: Mapped[str] = mapped_column(String, unique=True, index=True)
+    external_id: Mapped[str | None] = mapped_column(
+        String, unique=True, index=True, nullable=True
+    )
     user_id: Mapped[UUID] = mapped_column(
         ForeignKey("user.id", ondelete="CASCADE"), unique=True, nullable=False
     )
diff --git a/backend/tests/unit/onyx/server/scim/test_providers.py b/backend/tests/unit/onyx/server/scim/test_providers.py
index 60bbff89aae..79228386acd 100644
--- a/backend/tests/unit/onyx/server/scim/test_providers.py
+++ b/backend/tests/unit/onyx/server/scim/test_providers.py
@@ -117,7 +117,10 @@ def test_build_user_resource_no_name(self) -> None:
         user = _make_mock_user(personal_name=None)
         result = provider.build_user_resource(user, None)
 
-        assert result.name == ScimName(givenName="", familyName="", formatted="")
+        # Falls back to deriving name from email local part
+        assert result.name == ScimName(
+            givenName="test", familyName="", formatted="test"
+        )
         assert result.displayName is None
 
     def test_build_user_resource_scim_username_preserves_case(self) -> None:
diff --git a/backend/tests/unit/onyx/server/scim/test_user_endpoints.py b/backend/tests/unit/onyx/server/scim/test_user_endpoints.py
index b1bd5e07fa9..df823c5a276 100644
--- a/backend/tests/unit/onyx/server/scim/test_user_endpoints.py
+++ b/backend/tests/unit/onyx/server/scim/test_user_endpoints.py
@@ -215,7 +215,7 @@ def test_success(
         mock_dal.commit.assert_called_once()
 
     @patch("ee.onyx.server.scim.api._check_seat_availability", return_value=None)
-    def test_missing_external_id_creates_user_without_mapping(
+    def test_missing_external_id_still_creates_mapping(
         self,
         mock_seats: MagicMock,  # noqa: ARG002
         mock_db_session: MagicMock,
@@ -223,6 +223,7 @@ def test_missing_external_id_creates_user_without_mapping(
         mock_dal: MagicMock,
         provider: ScimProvider,
     ) -> None:
+        """Mapping is always created to mark user as SCIM-managed."""
         mock_dal.get_user_by_email.return_value = None
         resource = make_scim_user(externalId=None)
 
@@ -236,11 +237,11 @@ def test_missing_external_id_creates_user_without_mapping(
         parsed = parse_scim_user(result, status=201)
         assert parsed.userName is not None
         mock_dal.add_user.assert_called_once()
-        mock_dal.create_user_mapping.assert_not_called()
+        mock_dal.create_user_mapping.assert_called_once()
         mock_dal.commit.assert_called_once()
 
     @patch("ee.onyx.server.scim.api._check_seat_availability", return_value=None)
-    def test_duplicate_email_returns_409(
+    def test_duplicate_scim_managed_email_returns_409(
         self,
         mock_seats: MagicMock,  # noqa: ARG002
         mock_db_session: MagicMock,
@@ -248,7 +249,12 @@ def test_duplicate_email_returns_409(
         mock_dal: MagicMock,
         provider: ScimProvider,
     ) -> None:
-        mock_dal.get_user_by_email.return_value = make_db_user()
+        """409 only when the existing user already has a SCIM mapping."""
+        existing = make_db_user()
+        mock_dal.get_user_by_email.return_value = existing
+        mock_dal.get_user_mapping_by_user_id.return_value = make_user_mapping(
+            user_id=existing.id
+        )
         resource = make_scim_user()
 
         result = create_user(
@@ -260,6 +266,40 @@ def test_duplicate_email_returns_409(
 
         assert_scim_error(result, 409)
 
+    @patch("ee.onyx.server.scim.api._check_seat_availability", return_value=None)
+    def test_existing_user_without_mapping_gets_linked(
+        self,
+        mock_seats: MagicMock,  # noqa: ARG002
+        mock_db_session: MagicMock,
+        mock_token: MagicMock,
+        mock_dal: MagicMock,
+        provider: ScimProvider,
+    ) -> None:
+        """Pre-existing user without SCIM mapping gets adopted (linked)."""
+        existing = make_db_user(email="admin@example.com", personal_name=None)
+        mock_dal.get_user_by_email.return_value = existing
+        mock_dal.get_user_mapping_by_user_id.return_value = None
+        resource = make_scim_user(userName="admin@example.com", externalId="ext-admin")
+
+        result = create_user(
+            user_resource=resource,
+            _token=mock_token,
+            provider=provider,
+            db_session=mock_db_session,
+        )
+
+        parsed = parse_scim_user(result, status=201)
+        assert parsed.userName == "admin@example.com"
+        # Should NOT create a new user — reuse existing
+        mock_dal.add_user.assert_not_called()
+        # Should sync is_active and personal_name from the SCIM request
+        mock_dal.update_user.assert_called_once_with(
+            existing, is_active=True, personal_name="Test User"
+        )
+        # Should create a SCIM mapping for the existing user
+        mock_dal.create_user_mapping.assert_called_once()
+        mock_dal.commit.assert_called_once()
+
     @patch("ee.onyx.server.scim.api._check_seat_availability", return_value=None)
     def test_integrity_error_returns_409(
         self,

From 07915a6c01d8d10a8adaea3c2a2f3d754ccee694 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Mon, 2 Mar 2026 22:19:47 -0800
Subject: [PATCH 043/267] fix: Update frontend route calls to use new endpoints
 (#8968)

---
 web/src/lib/llmConfig/visionLLM.ts            | 29 +++++++-------
 .../forms/OnboardingFormWrapper.tsx           | 39 +++++++++++++++----
 .../modals/llmConfig/CustomModal.test.tsx     | 20 ++++++----
 3 files changed, 59 insertions(+), 29 deletions(-)

diff --git a/web/src/lib/llmConfig/visionLLM.ts b/web/src/lib/llmConfig/visionLLM.ts
index 971090663ab..1d66344d4f6 100644
--- a/web/src/lib/llmConfig/visionLLM.ts
+++ b/web/src/lib/llmConfig/visionLLM.ts
@@ -1,7 +1,8 @@
-import { VisionProvider } from "@/interfaces/llm";
+import { LLMProviderResponse, VisionProvider } from "@/interfaces/llm";
+import { LLM_ADMIN_URL } from "@/lib/llmConfig/constants";
 
 export async function fetchVisionProviders(): Promise<VisionProvider[]> {
-  const response = await fetch("/api/admin/llm/vision-providers", {
+  const response = await fetch(`${LLM_ADMIN_URL}/vision-providers`, {
     headers: {
       "Content-Type": "application/json",
     },
@@ -11,24 +12,24 @@ export async function fetchVisionProviders(): Promise<VisionProvider[]> {
       `Failed to fetch vision providers: ${await response.text()}`
     );
   }
-  return response.json();
+  const data = (await response.json()) as LLMProviderResponse<VisionProvider>;
+  return data.providers;
 }
 
 export async function setDefaultVisionProvider(
   providerId: number,
   visionModel: string
 ): Promise<void> {
-  const response = await fetch(
-    `/api/admin/llm/provider/${providerId}/default-vision?vision_model=${encodeURIComponent(
-      visionModel
-    )}`,
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-    }
-  );
+  const response = await fetch(`${LLM_ADMIN_URL}/default-vision`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      provider_id: providerId,
+      model_name: visionModel,
+    }),
+  });
 
   if (!response.ok) {
     const errorMsg = await response.text();
diff --git a/web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx b/web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx
index 9a40d29a26c..de998e6d089 100644
--- a/web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx
+++ b/web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx
@@ -6,7 +6,10 @@ import {
   ModelConfiguration,
   WellKnownLLMProviderDescriptor,
 } from "@/interfaces/llm";
-import { LLM_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
+import {
+  LLM_ADMIN_URL,
+  LLM_PROVIDERS_ADMIN_URL,
+} from "@/lib/llmConfig/constants";
 import { OnboardingActions, OnboardingState } from "../types";
 import { APIFormFieldState } from "@/refresh-components/form/types";
 import {
@@ -225,13 +228,33 @@ export function OnboardingFormWrapper<T extends Record<string, any>>({
       try {
         const newLlmProvider = await response.json();
         if (newLlmProvider?.id != null) {
-          const setDefaultResponse = await fetch(
-            `${LLM_PROVIDERS_ADMIN_URL}/${newLlmProvider.id}/default`,
-            { method: "POST" }
-          );
-          if (!setDefaultResponse.ok) {
-            const err = await setDefaultResponse.json().catch(() => ({}));
-            console.error("Failed to set provider as default", err?.detail);
+          const defaultModelName =
+            (payload as Record<string, any>).default_model_name ??
+            (payload as Record<string, any>).model_configurations?.[0]?.name ??
+            "";
+
+          if (!defaultModelName) {
+            console.error(
+              "No model name available to set as default — skipping set-default call"
+            );
+          } else {
+            const setDefaultResponse = await fetch(`${LLM_ADMIN_URL}/default`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                provider_id: newLlmProvider.id,
+                model_name: defaultModelName,
+              }),
+            });
+            if (!setDefaultResponse.ok) {
+              const err = await setDefaultResponse.json().catch(() => ({}));
+              setErrorMessage(
+                err?.detail ?? "Failed to set provider as default"
+              );
+              setApiStatus("error");
+              setIsSubmitting(false);
+              return;
+            }
           }
         }
       } catch (_e) {
diff --git a/web/src/sections/modals/llmConfig/CustomModal.test.tsx b/web/src/sections/modals/llmConfig/CustomModal.test.tsx
index 2c973adee1c..d32f7112c72 100644
--- a/web/src/sections/modals/llmConfig/CustomModal.test.tsx
+++ b/web/src/sections/modals/llmConfig/CustomModal.test.tsx
@@ -412,7 +412,7 @@ describe("Custom LLM Provider Configuration Workflow", () => {
       }),
     } as Response);
 
-    // Mock POST /api/admin/llm/provider/5/default
+    // Mock POST /api/admin/llm/default
     fetchSpy.mockResolvedValueOnce({
       ok: true,
       json: async () => ({}),
@@ -431,14 +431,20 @@ describe("Custom LLM Provider Configuration Workflow", () => {
     const submitButton = screen.getByRole("button", { name: /enable/i });
     await user.click(submitButton);
 
-    // Verify set as default API was called
+    // Verify set as default API was called with correct endpoint and body
     await waitFor(() => {
-      expect(fetchSpy).toHaveBeenCalledWith(
-        "/api/admin/llm/provider/5/default",
-        expect.objectContaining({
-          method: "POST",
-        })
+      const defaultCall = fetchSpy.mock.calls.find(
+        ([url]) => url === "/api/admin/llm/default"
       );
+      expect(defaultCall).toBeDefined();
+
+      const [, options] = defaultCall!;
+      expect(options.method).toBe("POST");
+      expect(options.headers).toEqual({ "Content-Type": "application/json" });
+
+      const body = JSON.parse(options.body);
+      expect(body.provider_id).toBe(5);
+      expect(body).toHaveProperty("model_name");
     });
   });
 

From eda436de01af813cf9be83ba998d669e36333e09 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Mon, 2 Mar 2026 22:36:29 -0800
Subject: [PATCH 044/267] fix: Block deleting default provider (#8962)

---
 backend/onyx/server/manage/llm/api.py         |  10 +
 .../tests/llm_provider/test_llm_provider.py   | 255 ++++++++++++++++++
 .../e2e/onboarding/onboarding_flow.spec.ts    |   2 +-
 web/tests/e2e/utils/onyxApiClient.ts          |  10 +-
 4 files changed, 274 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index 9503a828bf8..f15430cbcf8 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -479,10 +479,20 @@ def put_llm_provider(
 @admin_router.delete("/provider/{provider_id}")
 def delete_llm_provider(
     provider_id: int,
+    force: bool = Query(False),
     _: User = Depends(current_admin_user),
     db_session: Session = Depends(get_session),
 ) -> None:
     try:
+        if not force:
+            model = fetch_default_llm_model(db_session)
+
+            if model and model.llm_provider_id == provider_id:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Cannot delete the default LLM provider",
+                )
+
         remove_llm_provider(db_session, provider_id)
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
diff --git a/backend/tests/integration/tests/llm_provider/test_llm_provider.py b/backend/tests/integration/tests/llm_provider/test_llm_provider.py
index 945924068a5..af1a1694618 100644
--- a/backend/tests/integration/tests/llm_provider/test_llm_provider.py
+++ b/backend/tests/integration/tests/llm_provider/test_llm_provider.py
@@ -386,6 +386,261 @@ def test_delete_llm_provider(
     assert provider_data is None
 
 
+def test_delete_default_llm_provider_rejected(reset: None) -> None:  # noqa: ARG001
+    """Deleting the default LLM provider should return 400."""
+    admin_user = UserManager.create(name="admin_user")
+
+    # Create a provider
+    response = requests.put(
+        f"{API_SERVER_URL}/admin/llm/provider?is_creation=true",
+        headers=admin_user.headers,
+        json={
+            "name": "test-provider-default-delete",
+            "provider": LlmProviderNames.OPENAI,
+            "api_key": "sk-000000000000000000000000000000000000000000000000",
+            "model_configurations": [
+                ModelConfigurationUpsertRequest(
+                    name="gpt-4o-mini", is_visible=True
+                ).model_dump()
+            ],
+            "is_public": True,
+            "groups": [],
+        },
+    )
+    assert response.status_code == 200
+    created_provider = response.json()
+
+    # Set this provider as the default
+    set_default_response = requests.post(
+        f"{API_SERVER_URL}/admin/llm/default",
+        headers=admin_user.headers,
+        json={
+            "provider_id": created_provider["id"],
+            "model_name": "gpt-4o-mini",
+        },
+    )
+    assert set_default_response.status_code == 200
+
+    # Attempt to delete the default provider — should be rejected
+    delete_response = requests.delete(
+        f"{API_SERVER_URL}/admin/llm/provider/{created_provider['id']}",
+        headers=admin_user.headers,
+    )
+    assert delete_response.status_code == 400
+    assert "Cannot delete the default LLM provider" in delete_response.json()["detail"]
+
+    # Verify provider still exists
+    provider_data = _get_provider_by_id(admin_user, created_provider["id"])
+    assert provider_data is not None
+
+
+def test_delete_non_default_llm_provider_with_default_set(
+    reset: None,  # noqa: ARG001
+) -> None:
+    """Deleting a non-default provider should succeed even when a default is set."""
+    admin_user = UserManager.create(name="admin_user")
+
+    # Create two providers
+    response_default = requests.put(
+        f"{API_SERVER_URL}/admin/llm/provider?is_creation=true",
+        headers=admin_user.headers,
+        json={
+            "name": "default-provider",
+            "provider": LlmProviderNames.OPENAI,
+            "api_key": "sk-000000000000000000000000000000000000000000000000",
+            "model_configurations": [
+                ModelConfigurationUpsertRequest(
+                    name="gpt-4o-mini", is_visible=True
+                ).model_dump()
+            ],
+            "is_public": True,
+            "groups": [],
+        },
+    )
+    assert response_default.status_code == 200
+    default_provider = response_default.json()
+
+    response_other = requests.put(
+        f"{API_SERVER_URL}/admin/llm/provider?is_creation=true",
+        headers=admin_user.headers,
+        json={
+            "name": "other-provider",
+            "provider": LlmProviderNames.OPENAI,
+            "api_key": "sk-000000000000000000000000000000000000000000000000",
+            "model_configurations": [
+                ModelConfigurationUpsertRequest(
+                    name="gpt-4o", is_visible=True
+                ).model_dump()
+            ],
+            "is_public": True,
+            "groups": [],
+        },
+    )
+    assert response_other.status_code == 200
+    other_provider = response_other.json()
+
+    # Set the first provider as default
+    set_default_response = requests.post(
+        f"{API_SERVER_URL}/admin/llm/default",
+        headers=admin_user.headers,
+        json={
+            "provider_id": default_provider["id"],
+            "model_name": "gpt-4o-mini",
+        },
+    )
+    assert set_default_response.status_code == 200
+
+    # Delete the non-default provider — should succeed
+    delete_response = requests.delete(
+        f"{API_SERVER_URL}/admin/llm/provider/{other_provider['id']}",
+        headers=admin_user.headers,
+    )
+    assert delete_response.status_code == 200
+
+    # Verify the non-default provider is gone
+    provider_data = _get_provider_by_id(admin_user, other_provider["id"])
+    assert provider_data is None
+
+    # Verify the default provider still exists
+    default_data = _get_provider_by_id(admin_user, default_provider["id"])
+    assert default_data is not None
+
+
+def test_force_delete_default_llm_provider(
+    reset: None,  # noqa: ARG001
+) -> None:
+    """Force-deleting the default LLM provider should succeed."""
+    admin_user = UserManager.create(name="admin_user")
+
+    # Create a provider
+    response = requests.put(
+        f"{API_SERVER_URL}/admin/llm/provider?is_creation=true",
+        headers=admin_user.headers,
+        json={
+            "name": "test-provider-force-delete",
+            "provider": LlmProviderNames.OPENAI,
+            "api_key": "sk-000000000000000000000000000000000000000000000000",
+            "model_configurations": [
+                ModelConfigurationUpsertRequest(
+                    name="gpt-4o-mini", is_visible=True
+                ).model_dump()
+            ],
+            "is_public": True,
+            "groups": [],
+        },
+    )
+    assert response.status_code == 200
+    created_provider = response.json()
+
+    # Set this provider as the default
+    set_default_response = requests.post(
+        f"{API_SERVER_URL}/admin/llm/default",
+        headers=admin_user.headers,
+        json={
+            "provider_id": created_provider["id"],
+            "model_name": "gpt-4o-mini",
+        },
+    )
+    assert set_default_response.status_code == 200
+
+    # Attempt to delete without force — should be rejected
+    delete_response = requests.delete(
+        f"{API_SERVER_URL}/admin/llm/provider/{created_provider['id']}",
+        headers=admin_user.headers,
+    )
+    assert delete_response.status_code == 400
+
+    # Force delete — should succeed
+    force_delete_response = requests.delete(
+        f"{API_SERVER_URL}/admin/llm/provider/{created_provider['id']}?force=true",
+        headers=admin_user.headers,
+    )
+    assert force_delete_response.status_code == 200
+
+    # Verify provider is gone
+    provider_data = _get_provider_by_id(admin_user, created_provider["id"])
+    assert provider_data is None
+
+
+def test_delete_default_vision_provider_clears_vision_default(
+    reset: None,  # noqa: ARG001
+) -> None:
+    """Deleting the default vision provider should succeed and clear the vision default."""
+    admin_user = UserManager.create(name="admin_user")
+
+    # Create a text provider and set it as default (so we have a default text provider)
+    text_response = requests.put(
+        f"{API_SERVER_URL}/admin/llm/provider?is_creation=true",
+        headers=admin_user.headers,
+        json={
+            "name": "text-provider",
+            "provider": LlmProviderNames.OPENAI,
+            "api_key": "sk-000000000000000000000000000000000000000000000001",
+            "model_configurations": [
+                ModelConfigurationUpsertRequest(
+                    name="gpt-4o-mini", is_visible=True
+                ).model_dump()
+            ],
+            "is_public": True,
+            "groups": [],
+        },
+    )
+    assert text_response.status_code == 200
+    text_provider = text_response.json()
+    _set_default_provider(admin_user, text_provider["id"], "gpt-4o-mini")
+
+    # Create a vision provider and set it as default vision
+    vision_response = requests.put(
+        f"{API_SERVER_URL}/admin/llm/provider?is_creation=true",
+        headers=admin_user.headers,
+        json={
+            "name": "vision-provider",
+            "provider": LlmProviderNames.OPENAI,
+            "api_key": "sk-000000000000000000000000000000000000000000000002",
+            "model_configurations": [
+                ModelConfigurationUpsertRequest(
+                    name="gpt-4o",
+                    is_visible=True,
+                    supports_image_input=True,
+                ).model_dump()
+            ],
+            "is_public": True,
+            "groups": [],
+        },
+    )
+    assert vision_response.status_code == 200
+    vision_provider = vision_response.json()
+    _set_default_vision_provider(admin_user, vision_provider["id"], "gpt-4o")
+
+    # Verify vision default is set
+    data = _get_providers_admin(admin_user)
+    assert data is not None
+    _, _, vision_default = _unpack_data(data)
+    assert vision_default is not None
+    assert vision_default["provider_id"] == vision_provider["id"]
+
+    # Delete the vision provider — should succeed (only text default is protected)
+    delete_response = requests.delete(
+        f"{API_SERVER_URL}/admin/llm/provider/{vision_provider['id']}",
+        headers=admin_user.headers,
+    )
+    assert delete_response.status_code == 200
+
+    # Verify the vision provider is gone
+    provider_data = _get_provider_by_id(admin_user, vision_provider["id"])
+    assert provider_data is None
+
+    # Verify there is no default vision provider
+    data = _get_providers_admin(admin_user)
+    assert data is not None
+    _, text_default, vision_default = _unpack_data(data)
+    assert vision_default is None
+
+    # Verify the text default is still intact
+    assert text_default is not None
+    assert text_default["provider_id"] == text_provider["id"]
+
+
 def test_duplicate_provider_name_rejected(reset: None) -> None:  # noqa: ARG001
     """Creating a provider with a name that already exists should return 400."""
     admin_user = UserManager.create(name="admin_user")
diff --git a/web/tests/e2e/onboarding/onboarding_flow.spec.ts b/web/tests/e2e/onboarding/onboarding_flow.spec.ts
index 8ecb9ca2d81..57020c4eaa8 100644
--- a/web/tests/e2e/onboarding/onboarding_flow.spec.ts
+++ b/web/tests/e2e/onboarding/onboarding_flow.spec.ts
@@ -20,7 +20,7 @@ async function deleteAllProviders(client: OnyxApiClient): Promise<void> {
   const providers = await client.listLlmProviders();
   for (const provider of providers) {
     try {
-      await client.deleteProvider(provider.id);
+      await client.deleteProvider(provider.id, { force: true });
     } catch (error) {
       console.warn(
         `Failed to delete provider ${provider.id}: ${String(error)}`
diff --git a/web/tests/e2e/utils/onyxApiClient.ts b/web/tests/e2e/utils/onyxApiClient.ts
index 63b336b7368..14c1ee01795 100644
--- a/web/tests/e2e/utils/onyxApiClient.ts
+++ b/web/tests/e2e/utils/onyxApiClient.ts
@@ -526,8 +526,14 @@ export class OnyxApiClient {
    *
    * @param providerId - The provider ID to delete
    */
-  async deleteProvider(providerId: number): Promise<void> {
-    const response = await this.delete(`/admin/llm/provider/${providerId}`);
+  async deleteProvider(
+    providerId: number,
+    { force = false }: { force?: boolean } = {}
+  ): Promise<void> {
+    const query = force ? "?force=true" : "";
+    const response = await this.delete(
+      `/admin/llm/provider/${providerId}${query}`
+    );
 
     await this.handleResponseSoft(
       response,

From 6aa56821d6106d0168bb29d81175072f0fa61c37 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Mon, 2 Mar 2026 23:14:39 -0800
Subject: [PATCH 045/267] feat: use new cache backend where appropriate (#8889)

---
 .../tasks/user_file_processing/tasks.py       |   3 +
 backend/onyx/background/task_utils.py         |  51 +++---
 backend/onyx/chat/chat_processing_checker.py  |  33 ++--
 backend/onyx/chat/process_message.py          |  18 +-
 backend/onyx/chat/stop_signal_checker.py      |  43 ++---
 .../onyx/federated_connectors/oauth_utils.py  |  60 +++----
 backend/onyx/key_value_store/store.py         |  49 +++---
 .../auto_update_service.py                    |  33 ++--
 .../server/features/release_notes/utils.py    |  49 ++----
 .../server/query_and_chat/chat_backend.py     |  10 +-
 backend/onyx/server/settings/store.py         |  25 +--
 .../background/test_startup_recovery.py       | 141 ++++++++++++++-
 .../cache/test_kv_store_cache_layer.py        | 129 ++++++++++++++
 .../onyx/chat/test_stop_signal_checker.py     | 166 ++++++++++++++++++
 .../federated_connectors/test_oauth_utils.py  | 163 +++++++++++++++++
 15 files changed, 754 insertions(+), 219 deletions(-)
 create mode 100644 backend/tests/external_dependency_unit/cache/test_kv_store_cache_layer.py
 create mode 100644 backend/tests/unit/onyx/chat/test_stop_signal_checker.py
 create mode 100644 backend/tests/unit/onyx/federated_connectors/test_oauth_utils.py

diff --git a/backend/onyx/background/celery/tasks/user_file_processing/tasks.py b/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
index 8c21071908c..8f088c0f693 100644
--- a/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
+++ b/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
@@ -520,6 +520,7 @@ def process_user_file_impl(
         task_logger.exception(
             f"process_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
         )
+        raise
     finally:
         if file_lock is not None and file_lock.owned():
             file_lock.release()
@@ -675,6 +676,7 @@ def delete_user_file_impl(
         task_logger.exception(
             f"delete_user_file_impl - Error processing file id={user_file_id} - {e.__class__.__name__}"
         )
+        raise
     finally:
         if file_lock is not None and file_lock.owned():
             file_lock.release()
@@ -849,6 +851,7 @@ def project_sync_user_file_impl(
         task_logger.exception(
             f"project_sync_user_file_impl - Error syncing project for file id={user_file_id} - {e.__class__.__name__}"
         )
+        raise
     finally:
         if file_lock is not None and file_lock.owned():
             file_lock.release()
diff --git a/backend/onyx/background/task_utils.py b/backend/onyx/background/task_utils.py
index 0a93e35cc68..191f0486140 100644
--- a/backend/onyx/background/task_utils.py
+++ b/backend/onyx/background/task_utils.py
@@ -148,11 +148,14 @@ def drain_processing_loop(tenant_id: str) -> None:
             file_id = _claim_next_processing_file(session)
         if file_id is None:
             break
-        process_user_file_impl(
-            user_file_id=str(file_id),
-            tenant_id=tenant_id,
-            redis_locking=False,
-        )
+        try:
+            process_user_file_impl(
+                user_file_id=str(file_id),
+                tenant_id=tenant_id,
+                redis_locking=False,
+            )
+        except Exception:
+            logger.exception(f"Failed to process user file {file_id}")
 
 
 def drain_delete_loop(tenant_id: str) -> None:
@@ -162,18 +165,21 @@ def drain_delete_loop(tenant_id: str) -> None:
     )
     from onyx.db.engine.sql_engine import get_session_with_current_tenant
 
-    seen: set[UUID] = set()
+    failed: set[UUID] = set()
     while True:
         with get_session_with_current_tenant() as session:
-            file_id = _claim_next_deleting_file(session, exclude_ids=seen)
+            file_id = _claim_next_deleting_file(session, exclude_ids=failed)
         if file_id is None:
             break
-        seen.add(file_id)
-        delete_user_file_impl(
-            user_file_id=str(file_id),
-            tenant_id=tenant_id,
-            redis_locking=False,
-        )
+        try:
+            delete_user_file_impl(
+                user_file_id=str(file_id),
+                tenant_id=tenant_id,
+                redis_locking=False,
+            )
+        except Exception:
+            logger.exception(f"Failed to delete user file {file_id}")
+            failed.add(file_id)
 
 
 def drain_project_sync_loop(tenant_id: str) -> None:
@@ -183,15 +189,18 @@ def drain_project_sync_loop(tenant_id: str) -> None:
     )
     from onyx.db.engine.sql_engine import get_session_with_current_tenant
 
-    seen: set[UUID] = set()
+    failed: set[UUID] = set()
     while True:
         with get_session_with_current_tenant() as session:
-            file_id = _claim_next_sync_file(session, exclude_ids=seen)
+            file_id = _claim_next_sync_file(session, exclude_ids=failed)
         if file_id is None:
             break
-        seen.add(file_id)
-        project_sync_user_file_impl(
-            user_file_id=str(file_id),
-            tenant_id=tenant_id,
-            redis_locking=False,
-        )
+        try:
+            project_sync_user_file_impl(
+                user_file_id=str(file_id),
+                tenant_id=tenant_id,
+                redis_locking=False,
+            )
+        except Exception:
+            logger.exception(f"Failed to sync user file {file_id}")
+            failed.add(file_id)
diff --git a/backend/onyx/chat/chat_processing_checker.py b/backend/onyx/chat/chat_processing_checker.py
index f7b6923ce8f..41dc9a207f8 100644
--- a/backend/onyx/chat/chat_processing_checker.py
+++ b/backend/onyx/chat/chat_processing_checker.py
@@ -1,57 +1,52 @@
 from uuid import UUID
 
-from redis.client import Redis
+from onyx.cache.interface import CacheBackend
 
-# Redis key prefixes for chat message processing
 PREFIX = "chatprocessing"
 FENCE_PREFIX = f"{PREFIX}_fence"
 FENCE_TTL = 30 * 60  # 30 minutes
 
 
 def _get_fence_key(chat_session_id: UUID) -> str:
-    """
-    Generate the Redis key for a chat session processing a message.
+    """Generate the cache key for a chat session processing fence.
 
     Args:
         chat_session_id: The UUID of the chat session
 
     Returns:
-        The fence key string (tenant_id is automatically added by the Redis client)
+        The fence key string. Tenant isolation is handled automatically
+        by the cache backend (Redis key-prefixing or Postgres schema routing).
     """
     return f"{FENCE_PREFIX}_{chat_session_id}"
 
 
 def set_processing_status(
-    chat_session_id: UUID, redis_client: Redis, value: bool
+    chat_session_id: UUID, cache: CacheBackend, value: bool
 ) -> None:
-    """
-    Set or clear the fence for a chat session processing a message.
+    """Set or clear the fence for a chat session processing a message.
 
-    If the key exists, we are processing a message. If the key does not exist, we are not processing a message.
+    If the key exists, a message is being processed.
 
     Args:
         chat_session_id: The UUID of the chat session
-        redis_client: The Redis client to use
+        cache: Tenant-aware cache backend
         value: True to set the fence, False to clear it
     """
     fence_key = _get_fence_key(chat_session_id)
-
     if value:
-        redis_client.set(fence_key, 0, ex=FENCE_TTL)
+        cache.set(fence_key, 0, ex=FENCE_TTL)
     else:
-        redis_client.delete(fence_key)
+        cache.delete(fence_key)
 
 
-def is_chat_session_processing(chat_session_id: UUID, redis_client: Redis) -> bool:
-    """
-    Check if the chat session is processing a message.
+def is_chat_session_processing(chat_session_id: UUID, cache: CacheBackend) -> bool:
+    """Check if the chat session is processing a message.
 
     Args:
         chat_session_id: The UUID of the chat session
-        redis_client: The Redis client to use
+        cache: Tenant-aware cache backend
 
     Returns:
         True if the chat session is processing a message, False otherwise
     """
-    fence_key = _get_fence_key(chat_session_id)
-    return bool(redis_client.exists(fence_key))
+    return cache.exists(_get_fence_key(chat_session_id))
diff --git a/backend/onyx/chat/process_message.py b/backend/onyx/chat/process_message.py
index 0234d964c30..d5d1151cc66 100644
--- a/backend/onyx/chat/process_message.py
+++ b/backend/onyx/chat/process_message.py
@@ -11,9 +11,10 @@
 from uuid import UUID
 
 from pydantic import BaseModel
-from redis.client import Redis
 from sqlalchemy.orm import Session
 
+from onyx.cache.factory import get_cache_backend
+from onyx.cache.interface import CacheBackend
 from onyx.chat.chat_processing_checker import set_processing_status
 from onyx.chat.chat_state import ChatStateContainer
 from onyx.chat.chat_state import run_chat_loop_with_state_containers
@@ -79,7 +80,6 @@
 from onyx.llm.request_context import set_llm_mock_response
 from onyx.llm.utils import litellm_exception_to_error_msg
 from onyx.onyxbot.slack.models import SlackContext
-from onyx.redis.redis_pool import get_redis_client
 from onyx.server.query_and_chat.models import AUTO_PLACE_AFTER_LATEST_MESSAGE
 from onyx.server.query_and_chat.models import MessageResponseIDInfo
 from onyx.server.query_and_chat.models import SendMessageRequest
@@ -448,7 +448,7 @@ def handle_stream_message_objects(
 
     llm: LLM | None = None
     chat_session: ChatSession | None = None
-    redis_client: Redis | None = None
+    cache: CacheBackend | None = None
 
     user_id = user.id
     if user.is_anonymous:
@@ -809,19 +809,19 @@ def handle_stream_message_objects(
             )
             simple_chat_history.insert(0, summary_simple)
 
-        redis_client = get_redis_client()
+        cache = get_cache_backend()
 
         reset_cancel_status(
             chat_session.id,
-            redis_client,
+            cache,
         )
 
         def check_is_connected() -> bool:
-            return check_stop_signal(chat_session.id, redis_client)
+            return check_stop_signal(chat_session.id, cache)
 
         set_processing_status(
             chat_session_id=chat_session.id,
-            redis_client=redis_client,
+            cache=cache,
             value=True,
         )
 
@@ -968,10 +968,10 @@ def llm_loop_completion_callback(
             reset_llm_mock_response(mock_response_token)
 
         try:
-            if redis_client is not None and chat_session is not None:
+            if cache is not None and chat_session is not None:
                 set_processing_status(
                     chat_session_id=chat_session.id,
-                    redis_client=redis_client,
+                    cache=cache,
                     value=False,
                 )
         except Exception:
diff --git a/backend/onyx/chat/stop_signal_checker.py b/backend/onyx/chat/stop_signal_checker.py
index 4caa55976f3..518f5cd2e1b 100644
--- a/backend/onyx/chat/stop_signal_checker.py
+++ b/backend/onyx/chat/stop_signal_checker.py
@@ -1,65 +1,58 @@
 from uuid import UUID
 
-from redis.client import Redis
+from onyx.cache.interface import CacheBackend
 
-# Redis key prefixes for chat session stop signals
 PREFIX = "chatsessionstop"
 FENCE_PREFIX = f"{PREFIX}_fence"
-FENCE_TTL = 10 * 60  # 10 minutes - defensive TTL to prevent memory leaks
+FENCE_TTL = 10 * 60  # 10 minutes
 
 
 def _get_fence_key(chat_session_id: UUID) -> str:
-    """
-    Generate the Redis key for a chat session stop signal fence.
+    """Generate the cache key for a chat session stop signal fence.
 
     Args:
         chat_session_id: The UUID of the chat session
 
     Returns:
-        The fence key string (tenant_id is automatically added by the Redis client)
+        The fence key string. Tenant isolation is handled automatically
+        by the cache backend (Redis key-prefixing or Postgres schema routing).
     """
     return f"{FENCE_PREFIX}_{chat_session_id}"
 
 
-def set_fence(chat_session_id: UUID, redis_client: Redis, value: bool) -> None:
-    """
-    Set or clear the stop signal fence for a chat session.
+def set_fence(chat_session_id: UUID, cache: CacheBackend, value: bool) -> None:
+    """Set or clear the stop signal fence for a chat session.
 
     Args:
         chat_session_id: The UUID of the chat session
-        redis_client: Redis client to use (tenant-aware client that auto-prefixes keys)
+        cache: Tenant-aware cache backend
         value: True to set the fence (stop signal), False to clear it
     """
     fence_key = _get_fence_key(chat_session_id)
     if not value:
-        redis_client.delete(fence_key)
+        cache.delete(fence_key)
         return
+    cache.set(fence_key, 0, ex=FENCE_TTL)
 
-    redis_client.set(fence_key, 0, ex=FENCE_TTL)
 
-
-def is_connected(chat_session_id: UUID, redis_client: Redis) -> bool:
-    """
-    Check if the chat session should continue (not stopped).
+def is_connected(chat_session_id: UUID, cache: CacheBackend) -> bool:
+    """Check if the chat session should continue (not stopped).
 
     Args:
         chat_session_id: The UUID of the chat session to check
-        redis_client: Redis client to use for checking the stop signal (tenant-aware client that auto-prefixes keys)
+        cache: Tenant-aware cache backend
 
     Returns:
         True if the session should continue, False if it should stop
     """
-    fence_key = _get_fence_key(chat_session_id)
-    return not bool(redis_client.exists(fence_key))
+    return not cache.exists(_get_fence_key(chat_session_id))
 
 
-def reset_cancel_status(chat_session_id: UUID, redis_client: Redis) -> None:
-    """
-    Clear the stop signal for a chat session.
+def reset_cancel_status(chat_session_id: UUID, cache: CacheBackend) -> None:
+    """Clear the stop signal for a chat session.
 
     Args:
         chat_session_id: The UUID of the chat session
-        redis_client: Redis client to use (tenant-aware client that auto-prefixes keys)
+        cache: Tenant-aware cache backend
     """
-    fence_key = _get_fence_key(chat_session_id)
-    redis_client.delete(fence_key)
+    cache.delete(_get_fence_key(chat_session_id))
diff --git a/backend/onyx/federated_connectors/oauth_utils.py b/backend/onyx/federated_connectors/oauth_utils.py
index 7876d3fda8b..0b17d97f723 100644
--- a/backend/onyx/federated_connectors/oauth_utils.py
+++ b/backend/onyx/federated_connectors/oauth_utils.py
@@ -4,39 +4,33 @@
 import json
 import uuid
 from typing import Any
-from typing import cast
-from typing import Dict
-from typing import Optional
 
+from onyx.cache.factory import get_cache_backend
 from onyx.configs.app_configs import WEB_DOMAIN
-from onyx.redis.redis_pool import get_redis_client
 from onyx.utils.logger import setup_logger
 
 logger = setup_logger()
 
-# Redis key prefix for OAuth state
 OAUTH_STATE_PREFIX = "federated_oauth"
-# Default TTL for OAuth state (5 minutes)
-OAUTH_STATE_TTL = 300
+OAUTH_STATE_TTL = 300  # 5 minutes
 
 
 class OAuthSession:
-    """Represents an OAuth session stored in Redis."""
+    """Represents an OAuth session stored in the cache backend."""
 
     def __init__(
         self,
         federated_connector_id: int,
         user_id: str,
-        redirect_uri: Optional[str] = None,
-        additional_data: Optional[Dict[str, Any]] = None,
+        redirect_uri: str | None = None,
+        additional_data: dict[str, Any] | None = None,
     ):
         self.federated_connector_id = federated_connector_id
         self.user_id = user_id
         self.redirect_uri = redirect_uri
         self.additional_data = additional_data or {}
 
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary for Redis storage."""
+    def to_dict(self) -> dict[str, Any]:
         return {
             "federated_connector_id": self.federated_connector_id,
             "user_id": self.user_id,
@@ -45,8 +39,7 @@ def to_dict(self) -> Dict[str, Any]:
         }
 
     @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "OAuthSession":
-        """Create from dictionary retrieved from Redis."""
+    def from_dict(cls, data: dict[str, Any]) -> "OAuthSession":
         return cls(
             federated_connector_id=data["federated_connector_id"],
             user_id=data["user_id"],
@@ -58,31 +51,27 @@ def from_dict(cls, data: Dict[str, Any]) -> "OAuthSession":
 def generate_oauth_state(
     federated_connector_id: int,
     user_id: str,
-    redirect_uri: Optional[str] = None,
-    additional_data: Optional[Dict[str, Any]] = None,
+    redirect_uri: str | None = None,
+    additional_data: dict[str, Any] | None = None,
     ttl: int = OAUTH_STATE_TTL,
 ) -> str:
     """
-    Generate a secure state parameter and store session data in Redis.
+    Generate a secure state parameter and store session data in the cache backend.
 
     Args:
         federated_connector_id: ID of the federated connector
         user_id: ID of the user initiating OAuth
         redirect_uri: Optional redirect URI after OAuth completion
         additional_data: Any additional data to store with the session
-        ttl: Time-to-live in seconds for the Redis key
+        ttl: Time-to-live in seconds for the cache key
 
     Returns:
         Base64-encoded state parameter
     """
     # Generate a random UUID for the state
     state_uuid = uuid.uuid4()
+    state_b64 = base64.urlsafe_b64encode(state_uuid.bytes).decode("utf-8").rstrip("=")
 
-    # Convert UUID to base64 for URL-safe state parameter
-    state_bytes = state_uuid.bytes
-    state_b64 = base64.urlsafe_b64encode(state_bytes).decode("utf-8").rstrip("=")
-
-    # Create session object
     session = OAuthSession(
         federated_connector_id=federated_connector_id,
         user_id=user_id,
@@ -90,15 +79,9 @@ def generate_oauth_state(
         additional_data=additional_data,
     )
 
-    # Store in Redis with TTL
-    redis_client = get_redis_client()
-    redis_key = f"{OAUTH_STATE_PREFIX}:{state_uuid}"
-
-    redis_client.set(
-        redis_key,
-        json.dumps(session.to_dict()),
-        ex=ttl,
-    )
+    cache = get_cache_backend()
+    cache_key = f"{OAUTH_STATE_PREFIX}:{state_uuid}"
+    cache.set(cache_key, json.dumps(session.to_dict()), ex=ttl)
 
     logger.info(
         f"Generated OAuth state for federated_connector_id={federated_connector_id}, "
@@ -125,18 +108,15 @@ def verify_oauth_state(state: str) -> OAuthSession:
     state_bytes = base64.urlsafe_b64decode(padded_state)
     state_uuid = uuid.UUID(bytes=state_bytes)
 
-    # Look up in Redis
-    redis_client = get_redis_client()
-    redis_key = f"{OAUTH_STATE_PREFIX}:{state_uuid}"
+    cache = get_cache_backend()
+    cache_key = f"{OAUTH_STATE_PREFIX}:{state_uuid}"
 
-    session_data = cast(bytes, redis_client.get(redis_key))
+    session_data = cache.get(cache_key)
     if not session_data:
-        raise ValueError(f"OAuth state not found in Redis: {state}")
+        raise ValueError(f"OAuth state not found: {state}")
 
-    # Delete the key after retrieval (one-time use)
-    redis_client.delete(redis_key)
+    cache.delete(cache_key)
 
-    # Parse and return session
     session_dict = json.loads(session_data)
     return OAuthSession.from_dict(session_dict)
 
diff --git a/backend/onyx/key_value_store/store.py b/backend/onyx/key_value_store/store.py
index 58dc2e8abe9..b44d6bc2712 100644
--- a/backend/onyx/key_value_store/store.py
+++ b/backend/onyx/key_value_store/store.py
@@ -1,13 +1,11 @@
 import json
 from typing import cast
 
-from redis.client import Redis
-
+from onyx.cache.interface import CacheBackend
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.models import KVStore
 from onyx.key_value_store.interface import KeyValueStore
 from onyx.key_value_store.interface import KvKeyNotFoundError
-from onyx.redis.redis_pool import get_redis_client
 from onyx.utils.logger import setup_logger
 from onyx.utils.special_types import JSON_ro
 
@@ -20,22 +18,27 @@
 
 
 class PgRedisKVStore(KeyValueStore):
-    def __init__(self, redis_client: Redis | None = None) -> None:
-        # If no redis_client is provided, fall back to the context var
-        if redis_client is not None:
-            self.redis_client = redis_client
-        else:
-            self.redis_client = get_redis_client()
+    def __init__(self, cache: CacheBackend | None = None) -> None:
+        self._cache = cache
+
+    def _get_cache(self) -> CacheBackend:
+        if self._cache is None:
+            from onyx.cache.factory import get_cache_backend
+
+            self._cache = get_cache_backend()
+        return self._cache
 
     def store(self, key: str, val: JSON_ro, encrypt: bool = False) -> None:
-        # Not encrypted in Redis, but encrypted in Postgres
+        # Not encrypted in Cache backend (typically Redis), but encrypted in Postgres
         try:
-            self.redis_client.set(
+            self._get_cache().set(
                 REDIS_KEY_PREFIX + key, json.dumps(val), ex=KV_REDIS_KEY_EXPIRATION
             )
         except Exception as e:
-            # Fallback gracefully to Postgres if Redis fails
-            logger.error(f"Failed to set value in Redis for key '{key}': {str(e)}")
+            # Fallback gracefully to Postgres if Cache backend fails
+            logger.error(
+                f"Failed to set value in Cache backend for key '{key}': {str(e)}"
+            )
 
         encrypted_val = val if encrypt else None
         plain_val = val if not encrypt else None
@@ -53,16 +56,12 @@ def store(self, key: str, val: JSON_ro, encrypt: bool = False) -> None:
     def load(self, key: str, refresh_cache: bool = False) -> JSON_ro:
         if not refresh_cache:
             try:
-                redis_value = self.redis_client.get(REDIS_KEY_PREFIX + key)
-                if redis_value:
-                    if not isinstance(redis_value, bytes):
-                        raise ValueError(
-                            f"Redis value for key '{key}' is not a bytes object"
-                        )
-                    return json.loads(redis_value.decode("utf-8"))
+                cached = self._get_cache().get(REDIS_KEY_PREFIX + key)
+                if cached is not None:
+                    return json.loads(cached.decode("utf-8"))
             except Exception as e:
                 logger.error(
-                    f"Failed to get value from Redis for key '{key}': {str(e)}"
+                    f"Failed to get value from cache for key '{key}': {str(e)}"
                 )
 
         with get_session_with_current_tenant() as db_session:
@@ -79,21 +78,21 @@ def load(self, key: str, refresh_cache: bool = False) -> JSON_ro:
                 value = None
 
             try:
-                self.redis_client.set(
+                self._get_cache().set(
                     REDIS_KEY_PREFIX + key,
                     json.dumps(value),
                     ex=KV_REDIS_KEY_EXPIRATION,
                 )
             except Exception as e:
-                logger.error(f"Failed to set value in Redis for key '{key}': {str(e)}")
+                logger.error(f"Failed to set value in cache for key '{key}': {str(e)}")
 
             return cast(JSON_ro, value)
 
     def delete(self, key: str) -> None:
         try:
-            self.redis_client.delete(REDIS_KEY_PREFIX + key)
+            self._get_cache().delete(REDIS_KEY_PREFIX + key)
         except Exception as e:
-            logger.error(f"Failed to delete value from Redis for key '{key}': {str(e)}")
+            logger.error(f"Failed to delete value from cache for key '{key}': {str(e)}")
 
         with get_session_with_current_tenant() as db_session:
             result = db_session.query(KVStore).filter_by(key=key).delete()
diff --git a/backend/onyx/llm/well_known_providers/auto_update_service.py b/backend/onyx/llm/well_known_providers/auto_update_service.py
index c48cc7cfb6a..92a6bd83043 100644
--- a/backend/onyx/llm/well_known_providers/auto_update_service.py
+++ b/backend/onyx/llm/well_known_providers/auto_update_service.py
@@ -13,44 +13,38 @@
 import httpx
 from sqlalchemy.orm import Session
 
+from onyx.cache.factory import get_cache_backend
 from onyx.configs.app_configs import AUTO_LLM_CONFIG_URL
 from onyx.db.llm import fetch_auto_mode_providers
 from onyx.db.llm import sync_auto_mode_models
 from onyx.llm.well_known_providers.auto_update_models import LLMRecommendations
-from onyx.redis.redis_pool import get_redis_client
 from onyx.utils.logger import setup_logger
 
 logger = setup_logger()
 
-# Redis key for caching the last updated timestamp (per-tenant)
-_REDIS_KEY_LAST_UPDATED_AT = "auto_llm_update:last_updated_at"
+_CACHE_KEY_LAST_UPDATED_AT = "auto_llm_update:last_updated_at"
+_CACHE_TTL_SECONDS = 60 * 60 * 24  # 24 hours
 
 
 def _get_cached_last_updated_at() -> datetime | None:
-    """Get the cached last_updated_at timestamp from Redis."""
     try:
-        redis_client = get_redis_client()
-        value = redis_client.get(_REDIS_KEY_LAST_UPDATED_AT)
-        if value and isinstance(value, bytes):
-            # Value is bytes, decode to string then parse as ISO format
+        value = get_cache_backend().get(_CACHE_KEY_LAST_UPDATED_AT)
+        if value is not None:
             return datetime.fromisoformat(value.decode("utf-8"))
     except Exception as e:
-        logger.warning(f"Failed to get cached last_updated_at from Redis: {e}")
+        logger.warning(f"Failed to get cached last_updated_at: {e}")
     return None
 
 
 def _set_cached_last_updated_at(updated_at: datetime) -> None:
-    """Set the cached last_updated_at timestamp in Redis."""
     try:
-        redis_client = get_redis_client()
-        # Store as ISO format string, with 24 hour expiration
-        redis_client.set(
-            _REDIS_KEY_LAST_UPDATED_AT,
+        get_cache_backend().set(
+            _CACHE_KEY_LAST_UPDATED_AT,
             updated_at.isoformat(),
-            ex=60 * 60 * 24,  # 24 hours
+            ex=_CACHE_TTL_SECONDS,
         )
     except Exception as e:
-        logger.warning(f"Failed to set cached last_updated_at in Redis: {e}")
+        logger.warning(f"Failed to set cached last_updated_at: {e}")
 
 
 def fetch_llm_recommendations_from_github(
@@ -148,9 +142,8 @@ def sync_llm_models_from_github(
 
 
 def reset_cache() -> None:
-    """Reset the cache timestamp in Redis. Useful for testing."""
+    """Reset the cache timestamp. Useful for testing."""
     try:
-        redis_client = get_redis_client()
-        redis_client.delete(_REDIS_KEY_LAST_UPDATED_AT)
+        get_cache_backend().delete(_CACHE_KEY_LAST_UPDATED_AT)
     except Exception as e:
-        logger.warning(f"Failed to reset cache in Redis: {e}")
+        logger.warning(f"Failed to reset cache: {e}")
diff --git a/backend/onyx/server/features/release_notes/utils.py b/backend/onyx/server/features/release_notes/utils.py
index a6092045aff..bb99a427c84 100644
--- a/backend/onyx/server/features/release_notes/utils.py
+++ b/backend/onyx/server/features/release_notes/utils.py
@@ -8,10 +8,10 @@
 from sqlalchemy.orm import Session
 
 from onyx import __version__
+from onyx.cache.factory import get_shared_cache_backend
 from onyx.configs.app_configs import INSTANCE_TYPE
 from onyx.configs.constants import OnyxRedisLocks
 from onyx.db.release_notes import create_release_notifications_for_versions
-from onyx.redis.redis_pool import get_shared_redis_client
 from onyx.server.features.release_notes.constants import AUTO_REFRESH_THRESHOLD_SECONDS
 from onyx.server.features.release_notes.constants import FETCH_TIMEOUT
 from onyx.server.features.release_notes.constants import GITHUB_CHANGELOG_RAW_URL
@@ -113,60 +113,46 @@ def parse_mdx_to_release_note_entries(mdx_content: str) -> list[ReleaseNoteEntry
 
 
 def get_cached_etag() -> str | None:
-    """Get the cached GitHub ETag from Redis."""
-    redis_client = get_shared_redis_client()
+    cache = get_shared_cache_backend()
     try:
-        etag = redis_client.get(REDIS_KEY_ETAG)
+        etag = cache.get(REDIS_KEY_ETAG)
         if etag:
-            return etag.decode("utf-8") if isinstance(etag, bytes) else str(etag)
+            return etag.decode("utf-8")
         return None
     except Exception as e:
-        logger.error(f"Failed to get cached etag from Redis: {e}")
+        logger.error(f"Failed to get cached etag: {e}")
         return None
 
 
 def get_last_fetch_time() -> datetime | None:
-    """Get the last fetch timestamp from Redis."""
-    redis_client = get_shared_redis_client()
+    cache = get_shared_cache_backend()
     try:
-        fetched_at_str = redis_client.get(REDIS_KEY_FETCHED_AT)
-        if not fetched_at_str:
+        raw = cache.get(REDIS_KEY_FETCHED_AT)
+        if not raw:
             return None
 
-        decoded = (
-            fetched_at_str.decode("utf-8")
-            if isinstance(fetched_at_str, bytes)
-            else str(fetched_at_str)
-        )
-
-        last_fetch = datetime.fromisoformat(decoded)
-
-        # Defensively ensure timezone awareness
-        # fromisoformat() returns naive datetime if input lacks timezone
+        last_fetch = datetime.fromisoformat(raw.decode("utf-8"))
         if last_fetch.tzinfo is None:
-            # Assume UTC for naive datetimes
             last_fetch = last_fetch.replace(tzinfo=timezone.utc)
         else:
-            # Convert to UTC if timezone-aware
             last_fetch = last_fetch.astimezone(timezone.utc)
 
         return last_fetch
     except Exception as e:
-        logger.error(f"Failed to get last fetch time from Redis: {e}")
+        logger.error(f"Failed to get last fetch time from cache: {e}")
         return None
 
 
 def save_fetch_metadata(etag: str | None) -> None:
-    """Save ETag and fetch timestamp to Redis."""
-    redis_client = get_shared_redis_client()
+    cache = get_shared_cache_backend()
     now = datetime.now(timezone.utc)
 
     try:
-        redis_client.set(REDIS_KEY_FETCHED_AT, now.isoformat(), ex=REDIS_CACHE_TTL)
+        cache.set(REDIS_KEY_FETCHED_AT, now.isoformat(), ex=REDIS_CACHE_TTL)
         if etag:
-            redis_client.set(REDIS_KEY_ETAG, etag, ex=REDIS_CACHE_TTL)
+            cache.set(REDIS_KEY_ETAG, etag, ex=REDIS_CACHE_TTL)
     except Exception as e:
-        logger.error(f"Failed to save fetch metadata to Redis: {e}")
+        logger.error(f"Failed to save fetch metadata to cache: {e}")
 
 
 def is_cache_stale() -> bool:
@@ -196,11 +182,10 @@ def ensure_release_notes_fresh_and_notify(db_session: Session) -> None:
     if not is_cache_stale():
         return
 
-    # Acquire lock to prevent concurrent fetches
-    redis_client = get_shared_redis_client()
-    lock = redis_client.lock(
+    cache = get_shared_cache_backend()
+    lock = cache.lock(
         OnyxRedisLocks.RELEASE_NOTES_FETCH_LOCK,
-        timeout=90,  # 90 second timeout for the lock
+        timeout=90,
     )
 
     # Non-blocking acquire - if we can't get the lock, another request is handling it
diff --git a/backend/onyx/server/query_and_chat/chat_backend.py b/backend/onyx/server/query_and_chat/chat_backend.py
index 97daf47b5bb..72f7c80123e 100644
--- a/backend/onyx/server/query_and_chat/chat_backend.py
+++ b/backend/onyx/server/query_and_chat/chat_backend.py
@@ -13,13 +13,13 @@
 from fastapi import Response
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
-from redis.client import Redis
 from sqlalchemy.orm import Session
 
 from onyx.auth.api_key import get_hashed_api_key_from_request
 from onyx.auth.pat import get_hashed_pat_from_request
 from onyx.auth.users import current_chat_accessible_user
 from onyx.auth.users import current_user
+from onyx.cache.factory import get_cache_backend
 from onyx.chat.chat_processing_checker import is_chat_session_processing
 from onyx.chat.chat_state import ChatStateContainer
 from onyx.chat.chat_utils import convert_chat_history_basic
@@ -67,7 +67,6 @@
 from onyx.llm.factory import get_default_llm
 from onyx.llm.factory import get_llm_for_persona
 from onyx.llm.factory import get_llm_token_counter
-from onyx.redis.redis_pool import get_redis_client
 from onyx.secondary_llm_flows.chat_session_naming import generate_chat_session_name
 from onyx.server.api_key_usage import check_api_key_usage
 from onyx.server.query_and_chat.models import ChatFeedbackRequest
@@ -330,7 +329,7 @@ def get_chat_session(
     ]
 
     try:
-        is_processing = is_chat_session_processing(session_id, get_redis_client())
+        is_processing = is_chat_session_processing(session_id, get_cache_backend())
         # Edit the last message to indicate loading (Overriding default message value)
         if is_processing and chat_message_details:
             last_msg = chat_message_details[-1]
@@ -927,11 +926,10 @@ async def search_chats(
 def stop_chat_session(
     chat_session_id: UUID,
     user: User = Depends(current_user),  # noqa: ARG001
-    redis_client: Redis = Depends(get_redis_client),
 ) -> dict[str, str]:
     """
-    Stop a chat session by setting a stop signal in Redis.
+    Stop a chat session by setting a stop signal.
     This endpoint is called by the frontend when the user clicks the stop button.
     """
-    set_fence(chat_session_id, redis_client, True)
+    set_fence(chat_session_id, get_cache_backend(), True)
     return {"message": "Chat session stopped"}
diff --git a/backend/onyx/server/settings/store.py b/backend/onyx/server/settings/store.py
index 5c6f4a4aaba..de9e8ad4099 100644
--- a/backend/onyx/server/settings/store.py
+++ b/backend/onyx/server/settings/store.py
@@ -1,3 +1,4 @@
+from onyx.cache.factory import get_cache_backend
 from onyx.configs.app_configs import DISABLE_USER_KNOWLEDGE
 from onyx.configs.app_configs import ENABLE_OPENSEARCH_INDEXING_FOR_ONYX
 from onyx.configs.app_configs import ONYX_QUERY_HISTORY_TYPE
@@ -6,11 +7,8 @@
 from onyx.configs.constants import OnyxRedisLocks
 from onyx.key_value_store.factory import get_kv_store
 from onyx.key_value_store.interface import KvKeyNotFoundError
-from onyx.redis.redis_pool import get_redis_client
 from onyx.server.settings.models import Settings
 from onyx.utils.logger import setup_logger
-from shared_configs.configs import MULTI_TENANT
-from shared_configs.contextvars import get_current_tenant_id
 
 logger = setup_logger()
 
@@ -33,30 +31,22 @@ def load_settings() -> Settings:
         logger.error(f"Error loading settings from KV store: {str(e)}")
         settings = Settings()
 
-    tenant_id = get_current_tenant_id() if MULTI_TENANT else None
-    redis_client = get_redis_client(tenant_id=tenant_id)
+    cache = get_cache_backend()
 
     try:
-        value = redis_client.get(OnyxRedisLocks.ANONYMOUS_USER_ENABLED)
+        value = cache.get(OnyxRedisLocks.ANONYMOUS_USER_ENABLED)
         if value is not None:
-            assert isinstance(value, bytes)
             anonymous_user_enabled = int(value.decode("utf-8")) == 1
         else:
-            # Default to False
             anonymous_user_enabled = False
-            # Optionally store the default back to Redis
-            redis_client.set(
-                OnyxRedisLocks.ANONYMOUS_USER_ENABLED, "0", ex=SETTINGS_TTL
-            )
+            cache.set(OnyxRedisLocks.ANONYMOUS_USER_ENABLED, "0", ex=SETTINGS_TTL)
     except Exception as e:
-        # Log the error and reset to default
-        logger.error(f"Error loading anonymous user setting from Redis: {str(e)}")
+        logger.error(f"Error loading anonymous user setting from cache: {str(e)}")
         anonymous_user_enabled = False
 
     settings.anonymous_user_enabled = anonymous_user_enabled
     settings.query_history_type = ONYX_QUERY_HISTORY_TYPE
 
-    # Override user knowledge setting if disabled via environment variable
     if DISABLE_USER_KNOWLEDGE:
         settings.user_knowledge_enabled = False
 
@@ -66,11 +56,10 @@ def load_settings() -> Settings:
 
 
 def store_settings(settings: Settings) -> None:
-    tenant_id = get_current_tenant_id() if MULTI_TENANT else None
-    redis_client = get_redis_client(tenant_id=tenant_id)
+    cache = get_cache_backend()
 
     if settings.anonymous_user_enabled is not None:
-        redis_client.set(
+        cache.set(
             OnyxRedisLocks.ANONYMOUS_USER_ENABLED,
             "1" if settings.anonymous_user_enabled else "0",
             ex=SETTINGS_TTL,
diff --git a/backend/tests/external_dependency_unit/background/test_startup_recovery.py b/backend/tests/external_dependency_unit/background/test_startup_recovery.py
index 01248efe7a2..1769b92f3e7 100644
--- a/backend/tests/external_dependency_unit/background/test_startup_recovery.py
+++ b/backend/tests/external_dependency_unit/background/test_startup_recovery.py
@@ -13,9 +13,11 @@
 from collections.abc import Generator
 from unittest.mock import MagicMock
 from unittest.mock import patch
+from uuid import UUID
 from uuid import uuid4
 
 import pytest
+import sqlalchemy as sa
 from sqlalchemy.orm import Session
 
 from onyx.background.periodic_poller import recover_stuck_user_files
@@ -55,6 +57,32 @@ def _create_user_file(
     return uf
 
 
+def _fake_delete_impl(
+    user_file_id: str, tenant_id: str, redis_locking: bool  # noqa: ARG001
+) -> None:
+    """Mock side-effect: delete the row so the drain loop terminates."""
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+    with get_session_with_current_tenant() as session:
+        session.execute(sa.delete(UserFile).where(UserFile.id == UUID(user_file_id)))
+        session.commit()
+
+
+def _fake_sync_impl(
+    user_file_id: str, tenant_id: str, redis_locking: bool  # noqa: ARG001
+) -> None:
+    """Mock side-effect: clear sync flags so the drain loop terminates."""
+    from onyx.db.engine.sql_engine import get_session_with_current_tenant
+
+    with get_session_with_current_tenant() as session:
+        session.execute(
+            sa.update(UserFile)
+            .where(UserFile.id == UUID(user_file_id))
+            .values(needs_project_sync=False, needs_persona_sync=False)
+        )
+        session.commit()
+
+
 @pytest.fixture()
 def _cleanup_user_files(db_session: Session) -> Generator[list[UserFile], None, None]:
     """Track created UserFile rows and delete them after each test."""
@@ -125,9 +153,9 @@ def test_deleting_files_recovered(
     ) -> None:
         user = create_test_user(db_session, "recovery_del")
         uf = _create_user_file(db_session, user.id, status=UserFileStatus.DELETING)
-        _cleanup_user_files.append(uf)
+        # Row is deleted by _fake_delete_impl, so no cleanup needed.
 
-        mock_impl = MagicMock()
+        mock_impl = MagicMock(side_effect=_fake_delete_impl)
         with patch(f"{_IMPL_MODULE}.delete_user_file_impl", mock_impl):
             recover_stuck_user_files(TEST_TENANT_ID)
 
@@ -155,7 +183,7 @@ def test_needs_project_sync_recovered(
         )
         _cleanup_user_files.append(uf)
 
-        mock_impl = MagicMock()
+        mock_impl = MagicMock(side_effect=_fake_sync_impl)
         with patch(f"{_IMPL_MODULE}.project_sync_user_file_impl", mock_impl):
             recover_stuck_user_files(TEST_TENANT_ID)
 
@@ -179,7 +207,7 @@ def test_needs_persona_sync_recovered(
         )
         _cleanup_user_files.append(uf)
 
-        mock_impl = MagicMock()
+        mock_impl = MagicMock(side_effect=_fake_sync_impl)
         with patch(f"{_IMPL_MODULE}.project_sync_user_file_impl", mock_impl):
             recover_stuck_user_files(TEST_TENANT_ID)
 
@@ -217,3 +245,108 @@ def test_multiple_processing_files(
             f"Expected all {len(files)} files to be recovered. "
             f"Missing: {expected_ids - called_ids}"
         )
+
+
+class TestTransientFailures:
+    """Drain loops skip failed files, process the rest, and terminate."""
+
+    def test_processing_failure_skips_and_continues(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "fail_proc")
+        uf_fail = _create_user_file(
+            db_session, user.id, status=UserFileStatus.PROCESSING
+        )
+        uf_ok = _create_user_file(db_session, user.id, status=UserFileStatus.PROCESSING)
+        _cleanup_user_files.extend([uf_fail, uf_ok])
+
+        fail_id = str(uf_fail.id)
+
+        def side_effect(
+            *, user_file_id: str, tenant_id: str, redis_locking: bool  # noqa: ARG001
+        ) -> None:
+            if user_file_id == fail_id:
+                raise RuntimeError("transient failure")
+
+        mock_impl = MagicMock(side_effect=side_effect)
+        with patch(f"{_IMPL_MODULE}.process_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert fail_id in called_ids, "Failed file should have been attempted"
+        assert str(uf_ok.id) in called_ids, "Healthy file should have been processed"
+        assert called_ids.count(fail_id) == 1, "Failed file retried — infinite loop"
+        assert called_ids.count(str(uf_ok.id)) == 1
+
+    def test_delete_failure_skips_and_continues(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "fail_del")
+        uf_fail = _create_user_file(db_session, user.id, status=UserFileStatus.DELETING)
+        uf_ok = _create_user_file(db_session, user.id, status=UserFileStatus.DELETING)
+        _cleanup_user_files.append(uf_fail)
+
+        fail_id = str(uf_fail.id)
+
+        def side_effect(
+            *, user_file_id: str, tenant_id: str, redis_locking: bool
+        ) -> None:
+            if user_file_id == fail_id:
+                raise RuntimeError("transient failure")
+            _fake_delete_impl(user_file_id, tenant_id, redis_locking)
+
+        mock_impl = MagicMock(side_effect=side_effect)
+        with patch(f"{_IMPL_MODULE}.delete_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert fail_id in called_ids, "Failed file should have been attempted"
+        assert str(uf_ok.id) in called_ids, "Healthy file should have been deleted"
+        assert called_ids.count(fail_id) == 1, "Failed file retried — infinite loop"
+        assert called_ids.count(str(uf_ok.id)) == 1
+
+    def test_sync_failure_skips_and_continues(
+        self,
+        db_session: Session,
+        tenant_context: None,  # noqa: ARG002
+        _cleanup_user_files: list[UserFile],
+    ) -> None:
+        user = create_test_user(db_session, "fail_sync")
+        uf_fail = _create_user_file(
+            db_session,
+            user.id,
+            status=UserFileStatus.COMPLETED,
+            needs_project_sync=True,
+        )
+        uf_ok = _create_user_file(
+            db_session,
+            user.id,
+            status=UserFileStatus.COMPLETED,
+            needs_persona_sync=True,
+        )
+        _cleanup_user_files.extend([uf_fail, uf_ok])
+
+        fail_id = str(uf_fail.id)
+
+        def side_effect(
+            *, user_file_id: str, tenant_id: str, redis_locking: bool
+        ) -> None:
+            if user_file_id == fail_id:
+                raise RuntimeError("transient failure")
+            _fake_sync_impl(user_file_id, tenant_id, redis_locking)
+
+        mock_impl = MagicMock(side_effect=side_effect)
+        with patch(f"{_IMPL_MODULE}.project_sync_user_file_impl", mock_impl):
+            recover_stuck_user_files(TEST_TENANT_ID)
+
+        called_ids = [call.kwargs["user_file_id"] for call in mock_impl.call_args_list]
+        assert fail_id in called_ids, "Failed file should have been attempted"
+        assert str(uf_ok.id) in called_ids, "Healthy file should have been synced"
+        assert called_ids.count(fail_id) == 1, "Failed file retried — infinite loop"
+        assert called_ids.count(str(uf_ok.id)) == 1
diff --git a/backend/tests/external_dependency_unit/cache/test_kv_store_cache_layer.py b/backend/tests/external_dependency_unit/cache/test_kv_store_cache_layer.py
new file mode 100644
index 00000000000..d74efcc1157
--- /dev/null
+++ b/backend/tests/external_dependency_unit/cache/test_kv_store_cache_layer.py
@@ -0,0 +1,129 @@
+"""Tests for PgRedisKVStore's cache layer integration with CacheBackend.
+
+Verifies that the KV store correctly uses the CacheBackend for caching
+in front of PostgreSQL: cache hits, cache misses falling through to PG,
+cache population after PG reads, cache invalidation on delete, and
+graceful degradation when the cache backend raises.
+
+Requires running PostgreSQL.
+"""
+
+import json
+from collections.abc import Generator
+from unittest.mock import MagicMock
+
+import pytest
+from sqlalchemy import delete
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.postgres_backend import PostgresCacheBackend
+from onyx.db.engine.sql_engine import get_session_with_tenant
+from onyx.db.models import CacheStore
+from onyx.db.models import KVStore
+from onyx.key_value_store.interface import KvKeyNotFoundError
+from onyx.key_value_store.store import PgRedisKVStore
+from onyx.key_value_store.store import REDIS_KEY_PREFIX
+from tests.external_dependency_unit.constants import TEST_TENANT_ID
+
+
+@pytest.fixture(autouse=True)
+def _clean_kv() -> Generator[None, None, None]:
+    yield
+    with get_session_with_tenant(tenant_id=TEST_TENANT_ID) as session:
+        session.execute(delete(KVStore))
+        session.execute(delete(CacheStore))
+        session.commit()
+
+
+@pytest.fixture
+def kv_store(pg_cache: PostgresCacheBackend) -> PgRedisKVStore:
+    return PgRedisKVStore(cache=pg_cache)
+
+
+class TestStoreAndLoad:
+    def test_store_populates_cache_and_pg(
+        self, kv_store: PgRedisKVStore, pg_cache: PostgresCacheBackend
+    ) -> None:
+        kv_store.store("k1", {"hello": "world"})
+
+        cached = pg_cache.get(REDIS_KEY_PREFIX + "k1")
+        assert cached is not None
+        assert json.loads(cached) == {"hello": "world"}
+
+        loaded = kv_store.load("k1")
+        assert loaded == {"hello": "world"}
+
+    def test_load_returns_cached_value_without_pg_hit(
+        self, pg_cache: PostgresCacheBackend
+    ) -> None:
+        """If the cache already has the value, PG should not be queried."""
+        pg_cache.set(REDIS_KEY_PREFIX + "cached_only", json.dumps({"from": "cache"}))
+        kv = PgRedisKVStore(cache=pg_cache)
+        assert kv.load("cached_only") == {"from": "cache"}
+
+    def test_load_falls_through_to_pg_on_cache_miss(
+        self, kv_store: PgRedisKVStore, pg_cache: PostgresCacheBackend
+    ) -> None:
+        kv_store.store("k2", [1, 2, 3])
+
+        pg_cache.delete(REDIS_KEY_PREFIX + "k2")
+        assert pg_cache.get(REDIS_KEY_PREFIX + "k2") is None
+
+        loaded = kv_store.load("k2")
+        assert loaded == [1, 2, 3]
+
+        repopulated = pg_cache.get(REDIS_KEY_PREFIX + "k2")
+        assert repopulated is not None
+        assert json.loads(repopulated) == [1, 2, 3]
+
+    def test_load_with_refresh_cache_skips_cache(
+        self, kv_store: PgRedisKVStore, pg_cache: PostgresCacheBackend
+    ) -> None:
+        kv_store.store("k3", "original")
+
+        pg_cache.set(REDIS_KEY_PREFIX + "k3", json.dumps("stale"))
+
+        loaded = kv_store.load("k3", refresh_cache=True)
+        assert loaded == "original"
+
+
+class TestDelete:
+    def test_delete_removes_from_cache_and_pg(
+        self, kv_store: PgRedisKVStore, pg_cache: PostgresCacheBackend
+    ) -> None:
+        kv_store.store("del_me", "bye")
+        kv_store.delete("del_me")
+
+        assert pg_cache.get(REDIS_KEY_PREFIX + "del_me") is None
+
+        with pytest.raises(KvKeyNotFoundError):
+            kv_store.load("del_me")
+
+    def test_delete_missing_key_raises(self, kv_store: PgRedisKVStore) -> None:
+        with pytest.raises(KvKeyNotFoundError):
+            kv_store.delete("nonexistent")
+
+
+class TestCacheFailureGracefulDegradation:
+    def test_store_succeeds_when_cache_set_raises(self) -> None:
+        failing_cache = MagicMock(spec=CacheBackend)
+        failing_cache.set.side_effect = ConnectionError("cache down")
+
+        kv = PgRedisKVStore(cache=failing_cache)
+        kv.store("resilient", {"data": True})
+
+        working_cache = MagicMock(spec=CacheBackend)
+        working_cache.get.return_value = None
+        kv_reader = PgRedisKVStore(cache=working_cache)
+        loaded = kv_reader.load("resilient")
+        assert loaded == {"data": True}
+
+    def test_load_falls_through_when_cache_get_raises(self) -> None:
+        failing_cache = MagicMock(spec=CacheBackend)
+        failing_cache.get.side_effect = ConnectionError("cache down")
+        failing_cache.set.side_effect = ConnectionError("cache down")
+
+        kv = PgRedisKVStore(cache=failing_cache)
+        kv.store("survive", 42)
+        loaded = kv.load("survive")
+        assert loaded == 42
diff --git a/backend/tests/unit/onyx/chat/test_stop_signal_checker.py b/backend/tests/unit/onyx/chat/test_stop_signal_checker.py
new file mode 100644
index 00000000000..845f35d1d25
--- /dev/null
+++ b/backend/tests/unit/onyx/chat/test_stop_signal_checker.py
@@ -0,0 +1,166 @@
+"""Unit tests for stop_signal_checker and chat_processing_checker.
+
+These modules are safety-critical — they control whether a chat stream
+continues or stops.  The tests use a simple in-memory CacheBackend stub
+so no external services are needed.
+"""
+
+from uuid import uuid4
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.interface import CacheLock
+from onyx.chat.chat_processing_checker import is_chat_session_processing
+from onyx.chat.chat_processing_checker import set_processing_status
+from onyx.chat.stop_signal_checker import FENCE_TTL
+from onyx.chat.stop_signal_checker import is_connected
+from onyx.chat.stop_signal_checker import reset_cancel_status
+from onyx.chat.stop_signal_checker import set_fence
+
+
+class _MemoryCacheBackend(CacheBackend):
+    """Minimal in-memory CacheBackend for unit tests."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, bytes] = {}
+
+    def get(self, key: str) -> bytes | None:
+        return self._store.get(key)
+
+    def set(
+        self,
+        key: str,
+        value: str | bytes | int | float,
+        ex: int | None = None,  # noqa: ARG002
+    ) -> None:
+        if isinstance(value, bytes):
+            self._store[key] = value
+        else:
+            self._store[key] = str(value).encode()
+
+    def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def exists(self, key: str) -> bool:
+        return key in self._store
+
+    def expire(self, key: str, seconds: int) -> None:
+        pass
+
+    def ttl(self, key: str) -> int:
+        return -2 if key not in self._store else -1
+
+    def lock(self, name: str, timeout: float | None = None) -> CacheLock:
+        raise NotImplementedError
+
+    def rpush(self, key: str, value: str | bytes) -> None:
+        raise NotImplementedError
+
+    def blpop(self, keys: list[str], timeout: int = 0) -> tuple[bytes, bytes] | None:
+        raise NotImplementedError
+
+
+# ── stop_signal_checker ──────────────────────────────────────────────
+
+
+class TestSetFence:
+    def test_set_fence_true_creates_key(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_fence(sid, cache, True)
+        assert not is_connected(sid, cache)
+
+    def test_set_fence_false_removes_key(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_fence(sid, cache, True)
+        set_fence(sid, cache, False)
+        assert is_connected(sid, cache)
+
+    def test_set_fence_false_noop_when_absent(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_fence(sid, cache, False)
+        assert is_connected(sid, cache)
+
+    def test_set_fence_uses_ttl(self) -> None:
+        """Verify set_fence passes ex=FENCE_TTL to cache.set."""
+        calls: list[dict[str, object]] = []
+        cache = _MemoryCacheBackend()
+        original_set = cache.set
+
+        def tracking_set(
+            key: str,
+            value: str | bytes | int | float,
+            ex: int | None = None,
+        ) -> None:
+            calls.append({"key": key, "ex": ex})
+            original_set(key, value, ex=ex)
+
+        cache.set = tracking_set  # type: ignore[method-assign]
+
+        set_fence(uuid4(), cache, True)
+        assert len(calls) == 1
+        assert calls[0]["ex"] == FENCE_TTL
+
+
+class TestIsConnected:
+    def test_connected_when_no_fence(self) -> None:
+        cache = _MemoryCacheBackend()
+        assert is_connected(uuid4(), cache)
+
+    def test_disconnected_when_fence_set(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_fence(sid, cache, True)
+        assert not is_connected(sid, cache)
+
+    def test_sessions_are_isolated(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid1, sid2 = uuid4(), uuid4()
+        set_fence(sid1, cache, True)
+        assert not is_connected(sid1, cache)
+        assert is_connected(sid2, cache)
+
+
+class TestResetCancelStatus:
+    def test_clears_fence(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_fence(sid, cache, True)
+        reset_cancel_status(sid, cache)
+        assert is_connected(sid, cache)
+
+    def test_noop_when_no_fence(self) -> None:
+        cache = _MemoryCacheBackend()
+        reset_cancel_status(uuid4(), cache)
+
+
+# ── chat_processing_checker ──────────────────────────────────────────
+
+
+class TestSetProcessingStatus:
+    def test_set_true_marks_processing(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_processing_status(sid, cache, True)
+        assert is_chat_session_processing(sid, cache)
+
+    def test_set_false_clears_processing(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid = uuid4()
+        set_processing_status(sid, cache, True)
+        set_processing_status(sid, cache, False)
+        assert not is_chat_session_processing(sid, cache)
+
+
+class TestIsChatSessionProcessing:
+    def test_not_processing_by_default(self) -> None:
+        cache = _MemoryCacheBackend()
+        assert not is_chat_session_processing(uuid4(), cache)
+
+    def test_sessions_are_isolated(self) -> None:
+        cache = _MemoryCacheBackend()
+        sid1, sid2 = uuid4(), uuid4()
+        set_processing_status(sid1, cache, True)
+        assert is_chat_session_processing(sid1, cache)
+        assert not is_chat_session_processing(sid2, cache)
diff --git a/backend/tests/unit/onyx/federated_connectors/test_oauth_utils.py b/backend/tests/unit/onyx/federated_connectors/test_oauth_utils.py
new file mode 100644
index 00000000000..03d37e6a076
--- /dev/null
+++ b/backend/tests/unit/onyx/federated_connectors/test_oauth_utils.py
@@ -0,0 +1,163 @@
+"""Unit tests for federated OAuth state generation and verification.
+
+Uses unittest.mock to patch get_cache_backend so no external services
+are needed.  Verifies the generate -> verify round-trip, one-time-use
+semantics, TTL propagation, and error handling.
+"""
+
+from unittest.mock import patch
+
+import pytest
+
+from onyx.cache.interface import CacheBackend
+from onyx.cache.interface import CacheLock
+from onyx.federated_connectors.oauth_utils import generate_oauth_state
+from onyx.federated_connectors.oauth_utils import OAUTH_STATE_TTL
+from onyx.federated_connectors.oauth_utils import OAuthSession
+from onyx.federated_connectors.oauth_utils import verify_oauth_state
+
+
+class _MemoryCacheBackend(CacheBackend):
+    """Minimal in-memory CacheBackend for unit tests."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, bytes] = {}
+        self.set_calls: list[dict[str, object]] = []
+
+    def get(self, key: str) -> bytes | None:
+        return self._store.get(key)
+
+    def set(
+        self,
+        key: str,
+        value: str | bytes | int | float,
+        ex: int | None = None,
+    ) -> None:
+        self.set_calls.append({"key": key, "ex": ex})
+        if isinstance(value, bytes):
+            self._store[key] = value
+        else:
+            self._store[key] = str(value).encode()
+
+    def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def exists(self, key: str) -> bool:
+        return key in self._store
+
+    def expire(self, key: str, seconds: int) -> None:
+        pass
+
+    def ttl(self, key: str) -> int:
+        return -2 if key not in self._store else -1
+
+    def lock(self, name: str, timeout: float | None = None) -> CacheLock:
+        raise NotImplementedError
+
+    def rpush(self, key: str, value: str | bytes) -> None:
+        raise NotImplementedError
+
+    def blpop(self, keys: list[str], timeout: int = 0) -> tuple[bytes, bytes] | None:
+        raise NotImplementedError
+
+
+def _patched(cache: _MemoryCacheBackend):  # type: ignore[no-untyped-def]
+    return patch(
+        "onyx.federated_connectors.oauth_utils.get_cache_backend",
+        return_value=cache,
+    )
+
+
+class TestGenerateAndVerifyRoundTrip:
+    def test_round_trip_basic(self) -> None:
+        cache = _MemoryCacheBackend()
+        with _patched(cache):
+            state = generate_oauth_state(
+                federated_connector_id=42,
+                user_id="user-abc",
+            )
+            session = verify_oauth_state(state)
+
+        assert session.federated_connector_id == 42
+        assert session.user_id == "user-abc"
+        assert session.redirect_uri is None
+        assert session.additional_data == {}
+
+    def test_round_trip_with_all_fields(self) -> None:
+        cache = _MemoryCacheBackend()
+        with _patched(cache):
+            state = generate_oauth_state(
+                federated_connector_id=7,
+                user_id="user-xyz",
+                redirect_uri="https://example.com/callback",
+                additional_data={"scope": "read"},
+            )
+            session = verify_oauth_state(state)
+
+        assert session.federated_connector_id == 7
+        assert session.user_id == "user-xyz"
+        assert session.redirect_uri == "https://example.com/callback"
+        assert session.additional_data == {"scope": "read"}
+
+
+class TestOneTimeUse:
+    def test_verify_deletes_state(self) -> None:
+        cache = _MemoryCacheBackend()
+        with _patched(cache):
+            state = generate_oauth_state(federated_connector_id=1, user_id="u")
+            verify_oauth_state(state)
+
+            with pytest.raises(ValueError, match="OAuth state not found"):
+                verify_oauth_state(state)
+
+
+class TestTTLPropagation:
+    def test_default_ttl(self) -> None:
+        cache = _MemoryCacheBackend()
+        with _patched(cache):
+            generate_oauth_state(federated_connector_id=1, user_id="u")
+
+        assert len(cache.set_calls) == 1
+        assert cache.set_calls[0]["ex"] == OAUTH_STATE_TTL
+
+    def test_custom_ttl(self) -> None:
+        cache = _MemoryCacheBackend()
+        with _patched(cache):
+            generate_oauth_state(federated_connector_id=1, user_id="u", ttl=600)
+
+        assert cache.set_calls[0]["ex"] == 600
+
+
+class TestVerifyInvalidState:
+    def test_missing_state_raises(self) -> None:
+        cache = _MemoryCacheBackend()
+        with _patched(cache):
+            state = generate_oauth_state(federated_connector_id=1, user_id="u")
+            # Manually clear the cache to simulate expiration
+            cache._store.clear()
+
+            with pytest.raises(ValueError, match="OAuth state not found"):
+                verify_oauth_state(state)
+
+
+class TestOAuthSessionSerialization:
+    def test_to_dict_from_dict_round_trip(self) -> None:
+        session = OAuthSession(
+            federated_connector_id=5,
+            user_id="u-123",
+            redirect_uri="https://redir.example.com",
+            additional_data={"key": "val"},
+        )
+        d = session.to_dict()
+        restored = OAuthSession.from_dict(d)
+
+        assert restored.federated_connector_id == 5
+        assert restored.user_id == "u-123"
+        assert restored.redirect_uri == "https://redir.example.com"
+        assert restored.additional_data == {"key": "val"}
+
+    def test_from_dict_defaults(self) -> None:
+        minimal = {"federated_connector_id": 1, "user_id": "u"}
+        session = OAuthSession.from_dict(minimal)
+        assert session.redirect_uri is None
+        assert session.additional_data == {}

From 60fe3e9ad6411c4508003e4d0184b3462bbd20d4 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Tue, 3 Mar 2026 00:34:58 -0800
Subject: [PATCH 046/267] refactor(fe): migrate admin pages from AdminPageTitle
 to SettingsLayouts (#8930)

---
 web/src/app/admin/actions/mcp/page.tsx        |   8 +-
 web/src/app/admin/actions/open-api/page.tsx   |   8 +-
 web/src/app/admin/add-connector/page.tsx      | 101 ++++----
 web/src/app/admin/agents/page.tsx             |  53 ++--
 web/src/app/admin/api-key/page.tsx            |  16 +-
 .../app/admin/bots/SlackBotCreationForm.tsx   |  34 ++-
 .../bots/[bot-id]/channels/[id]/page.tsx      |  40 ++-
 .../admin/bots/[bot-id]/channels/new/page.tsx |  33 +--
 web/src/app/admin/bots/page.tsx               |  33 ++-
 .../document-processing/page.tsx              |  19 +-
 .../configuration/image-generation/page.tsx   |   8 +-
 .../app/admin/configuration/search/page.tsx   |  17 +-
 .../admin/configuration/web-search/page.tsx   |  15 +-
 web/src/app/admin/debug/page.tsx              |  23 +-
 web/src/app/admin/discord-bot/page.tsx        |   8 +-
 .../admin/document-index-migration/page.tsx   |   9 +-
 .../explorer/DocumentExplorerPage.tsx         |  35 +++
 web/src/app/admin/documents/explorer/page.tsx |  22 +-
 web/src/app/admin/documents/feedback/page.tsx |  28 +-
 .../documents/sets/[documentSetId]/page.tsx   |  49 ++--
 web/src/app/admin/documents/sets/new/page.tsx |  30 +--
 web/src/app/admin/documents/sets/page.tsx     |  28 +-
 .../status/CCPairIndexingStatusTable.tsx      |   6 +-
 web/src/app/admin/indexing/status/page.tsx    |  24 +-
 web/src/app/admin/kg/page.tsx                 |  19 +-
 web/src/app/admin/token-rate-limits/page.tsx  |  17 +-
 web/src/app/admin/users/page.tsx              |  35 +--
 web/src/app/ee/admin/billing/page.tsx         |  17 +-
 .../app/ee/admin/groups/[groupId]/page.tsx    |  43 +--
 web/src/app/ee/admin/groups/page.tsx          |  28 +-
 .../performance/custom-analytics/page.tsx     |  20 +-
 .../admin/performance/query-history/page.tsx  |  17 +-
 .../app/ee/admin/performance/usage/page.tsx   |  40 +--
 .../ee/admin/standard-answer/[id]/page.tsx    |  47 ++--
 .../app/ee/admin/standard-answer/new/page.tsx |  27 +-
 web/src/app/ee/admin/standard-answer/page.tsx |  33 ++-
 web/src/app/ee/admin/theme/page.tsx           |   8 +-
 web/src/components/admin/ClientLayout.tsx     |  37 ++-
 web/src/lib/admin-routes.ts                   | 245 ++++++++++++++++++
 .../admin/ChatPreferencesPage.tsx             |   8 +-
 .../admin/CodeInterpreterPage.tsx             |   7 +-
 .../admin/LLMConfigurationPage.tsx            |   7 +-
 web/src/sections/sidebar/AdminSidebar.tsx     | 237 +++--------------
 43 files changed, 872 insertions(+), 667 deletions(-)
 create mode 100644 web/src/app/admin/documents/explorer/DocumentExplorerPage.tsx
 create mode 100644 web/src/lib/admin-routes.ts

diff --git a/web/src/app/admin/actions/mcp/page.tsx b/web/src/app/admin/actions/mcp/page.tsx
index f03fda9aeef..3f5b9bde708 100644
--- a/web/src/app/admin/actions/mcp/page.tsx
+++ b/web/src/app/admin/actions/mcp/page.tsx
@@ -1,15 +1,17 @@
 "use client";
 
-import { SvgMcp } from "@opal/icons";
 import MCPPageContent from "@/sections/actions/MCPPageContent";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.MCP_ACTIONS]!;
 
 export default function Main() {
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
-        icon={SvgMcp}
-        title="MCP Actions"
+        icon={route.icon}
+        title={route.title}
         description="Connect MCP (Model Context Protocol) servers to add custom actions and tools for your agents."
         separator
       />
diff --git a/web/src/app/admin/actions/open-api/page.tsx b/web/src/app/admin/actions/open-api/page.tsx
index cfe4ef06be8..20f3df1f7d7 100644
--- a/web/src/app/admin/actions/open-api/page.tsx
+++ b/web/src/app/admin/actions/open-api/page.tsx
@@ -1,15 +1,17 @@
 "use client";
 
-import { SvgActions } from "@opal/icons";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import OpenApiPageContent from "@/sections/actions/OpenApiPageContent";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.OPENAPI_ACTIONS]!;
 
 export default function Main() {
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
-        icon={SvgActions}
-        title="OpenAPI Actions"
+        icon={route.icon}
+        title={route.title}
         description="Connect OpenAPI servers to add custom actions and tools for your agents."
         separator
       />
diff --git a/web/src/app/admin/add-connector/page.tsx b/web/src/app/admin/add-connector/page.tsx
index b9db7cdb6b7..4b1ef6fb132 100644
--- a/web/src/app/admin/add-connector/page.tsx
+++ b/web/src/app/admin/add-connector/page.tsx
@@ -1,5 +1,5 @@
 "use client";
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { SourceCategory, SourceMetadata } from "@/lib/search/interfaces";
 import { listSourceMetadata } from "@/lib/sources";
 import Button from "@/refresh-components/buttons/Button";
@@ -32,7 +32,7 @@ import { SettingsContext } from "@/providers/SettingsProvider";
 import SourceTile from "@/components/SourceTile";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import Text from "@/refresh-components/texts/Text";
-import { SvgUploadCloud } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 function SourceTileTooltipWrapper({
   sourceMetadata,
   preSelect,
@@ -124,6 +124,7 @@ function SourceTileTooltipWrapper({
 }
 
 export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.ADD_CONNECTOR]!;
   const sources = useMemo(() => listSourceMetadata(), []);
 
   const [rawSearchTerm, setSearchTerm] = useState("");
@@ -248,61 +249,37 @@ export default function Page() {
   };
 
   return (
-    <>
-      <AdminPageTitle
-        icon={SvgUploadCloud}
-        title="Add Connector"
-        farRightElement={
+    <SettingsLayouts.Root width="full">
+      <SettingsLayouts.Header
+        icon={route.icon}
+        title={route.title}
+        rightChildren={
           <Button href="/admin/indexing/status" primary>
             See Connectors
           </Button>
         }
+        separator
       />
+      <SettingsLayouts.Body>
+        <InputTypeIn
+          type="text"
+          placeholder="Search Connectors"
+          ref={searchInputRef}
+          value={rawSearchTerm} // keep the input bound to immediate state
+          onChange={(event) => setSearchTerm(event.target.value)}
+          onKeyDown={handleKeyPress}
+          className="w-96 flex-none"
+        />
 
-      <InputTypeIn
-        type="text"
-        placeholder="Search Connectors"
-        ref={searchInputRef}
-        value={rawSearchTerm} // keep the input bound to immediate state
-        onChange={(event) => setSearchTerm(event.target.value)}
-        onKeyDown={handleKeyPress}
-        className="w-96 flex-none"
-      />
-
-      {dedupedPopular.length > 0 && (
-        <div className="pt-8">
-          <Text as="p" headingH3>
-            Popular
-          </Text>
-          <div className="flex flex-wrap gap-4 p-4">
-            {dedupedPopular.map((source) => (
-              <SourceTileTooltipWrapper
-                preSelect={false}
-                key={source.internalName}
-                sourceMetadata={source}
-                federatedConnectors={federatedConnectors}
-                slackCredentials={slackCredentials}
-              />
-            ))}
-          </div>
-        </div>
-      )}
-
-      {Object.entries(categorizedSources)
-        .filter(([_, sources]) => sources.length > 0)
-        .map(([category, sources], categoryInd) => (
-          <div key={category} className="pt-8">
+        {dedupedPopular.length > 0 && (
+          <div className="pt-8">
             <Text as="p" headingH3>
-              {category}
+              Popular
             </Text>
             <div className="flex flex-wrap gap-4 p-4">
-              {sources.map((source, sourceInd) => (
+              {dedupedPopular.map((source) => (
                 <SourceTileTooltipWrapper
-                  preSelect={
-                    (searchTerm?.length ?? 0) > 0 &&
-                    categoryInd == 0 &&
-                    sourceInd == 0
-                  }
+                  preSelect={false}
                   key={source.internalName}
                   sourceMetadata={source}
                   federatedConnectors={federatedConnectors}
@@ -311,7 +288,33 @@ export default function Page() {
               ))}
             </div>
           </div>
-        ))}
-    </>
+        )}
+
+        {Object.entries(categorizedSources)
+          .filter(([_, sources]) => sources.length > 0)
+          .map(([category, sources], categoryInd) => (
+            <div key={category} className="pt-8">
+              <Text as="p" headingH3>
+                {category}
+              </Text>
+              <div className="flex flex-wrap gap-4 p-4">
+                {sources.map((source, sourceInd) => (
+                  <SourceTileTooltipWrapper
+                    preSelect={
+                      (searchTerm?.length ?? 0) > 0 &&
+                      categoryInd == 0 &&
+                      sourceInd == 0
+                    }
+                    key={source.internalName}
+                    sourceMetadata={source}
+                    federatedConnectors={federatedConnectors}
+                    slackCredentials={slackCredentials}
+                  />
+                ))}
+              </div>
+            </div>
+          ))}
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/agents/page.tsx b/web/src/app/admin/agents/page.tsx
index 2fc2aa4a924..edbd19c5f1f 100644
--- a/web/src/app/admin/agents/page.tsx
+++ b/web/src/app/admin/agents/page.tsx
@@ -4,14 +4,14 @@ import { PersonasTable } from "./PersonaTable";
 import Text from "@/components/ui/text";
 import Title from "@/components/ui/title";
 import Separator from "@/refresh-components/Separator";
-import { AdminPageTitle } from "@/components/admin/Title";
 import { SubLabel } from "@/components/Field";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { useAdminPersonas } from "@/hooks/useAdminPersonas";
 import { Persona } from "./interfaces";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import { SvgOnyxOctagon } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { useState, useEffect } from "react";
 import Pagination from "@/refresh-components/Pagination";
 
@@ -120,6 +120,7 @@ function MainContent({
 }
 
 export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.AGENTS]!;
   const [currentPage, setCurrentPage] = useState(1);
   const { personas, totalItems, isLoading, error, refresh } = useAdminPersonas({
     pageNum: currentPage - 1, // Backend uses 0-indexed pages
@@ -127,31 +128,33 @@ export default function Page() {
   });
 
   return (
-    <>
-      <AdminPageTitle icon={SvgOnyxOctagon} title="Agents" />
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
 
-      {isLoading && <ThreeDotsLoader />}
+      <SettingsLayouts.Body>
+        {isLoading && <ThreeDotsLoader />}
 
-      {error && (
-        <ErrorCallout
-          errorTitle="Failed to load agents"
-          errorMsg={
-            error?.info?.message ||
-            error?.info?.detail ||
-            "An unknown error occurred"
-          }
-        />
-      )}
+        {error && (
+          <ErrorCallout
+            errorTitle="Failed to load agents"
+            errorMsg={
+              error?.info?.message ||
+              error?.info?.detail ||
+              "An unknown error occurred"
+            }
+          />
+        )}
 
-      {!isLoading && !error && (
-        <MainContent
-          personas={personas}
-          totalItems={totalItems}
-          currentPage={currentPage}
-          onPageChange={setCurrentPage}
-          refreshPersonas={refresh}
-        />
-      )}
-    </>
+        {!isLoading && !error && (
+          <MainContent
+            personas={personas}
+            totalItems={totalItems}
+            currentPage={currentPage}
+            onPageChange={setCurrentPage}
+            refreshPersonas={refresh}
+          />
+        )}
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/api-key/page.tsx b/web/src/app/admin/api-key/page.tsx
index d99a6005a18..f08bc637495 100644
--- a/web/src/app/admin/api-key/page.tsx
+++ b/web/src/app/admin/api-key/page.tsx
@@ -1,8 +1,8 @@
 "use client";
 
 import { ThreeDotsLoader } from "@/components/Loading";
-import { AdminPageTitle } from "@/components/admin/Title";
 import { errorHandlingFetcher } from "@/lib/fetcher";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import useSWR, { mutate } from "swr";
 import Separator from "@/refresh-components/Separator";
@@ -32,6 +32,9 @@ import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import Text from "@/refresh-components/texts/Text";
 import { SvgEdit, SvgKey, SvgRefreshCw } from "@opal/icons";
 import { useCloudSubscription } from "@/hooks/useCloudSubscription";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.API_KEYS]!;
 
 function Main() {
   const {
@@ -233,10 +236,11 @@ function Main() {
 
 export default function Page() {
   return (
-    <>
-      <AdminPageTitle title="API Keys" icon={SvgKey} />
-
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header title={route.title} icon={route.icon} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/bots/SlackBotCreationForm.tsx b/web/src/app/admin/bots/SlackBotCreationForm.tsx
index e4860424545..17a7f1bb81b 100644
--- a/web/src/app/admin/bots/SlackBotCreationForm.tsx
+++ b/web/src/app/admin/bots/SlackBotCreationForm.tsx
@@ -4,9 +4,8 @@ import CardSection from "@/components/admin/CardSection";
 import { useRouter } from "next/navigation";
 import { useState } from "react";
 import { SlackTokensForm } from "./SlackTokensForm";
-import { SourceIcon } from "@/components/SourceIcon";
-import { AdminPageTitle } from "@/components/admin/Title";
-import { ValidSources } from "@/lib/types";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { SvgSlack } from "@opal/icons";
 
 export const NewSlackBotForm = () => {
   const [formValues] = useState({
@@ -19,20 +18,19 @@ export const NewSlackBotForm = () => {
   const router = useRouter();
 
   return (
-    <div>
-      <AdminPageTitle
-        icon={<SourceIcon iconSize={36} sourceType={ValidSources.Slack} />}
-        title="New Slack Bot"
-      />
-      <CardSection>
-        <div className="p-4">
-          <SlackTokensForm
-            isUpdate={false}
-            initialValues={formValues}
-            router={router}
-          />
-        </div>
-      </CardSection>
-    </div>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={SvgSlack} title="New Slack Bot" separator />
+      <SettingsLayouts.Body>
+        <CardSection>
+          <div className="p-4">
+            <SlackTokensForm
+              isUpdate={false}
+              initialValues={formValues}
+              router={router}
+            />
+          </div>
+        </CardSection>
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 };
diff --git a/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx b/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
index e0e69d67972..de4af1a36d3 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
@@ -1,15 +1,10 @@
-import { AdminPageTitle } from "@/components/admin/Title";
-import { SourceIcon } from "@/components/SourceIcon";
 import { SlackChannelConfigCreationForm } from "../SlackChannelConfigCreationForm";
 import { fetchSS } from "@/lib/utilsSS";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import {
-  DocumentSetSummary,
-  SlackChannelConfig,
-  ValidSources,
-} from "@/lib/types";
-import BackButton from "@/refresh-components/buttons/BackButton";
+import { DocumentSetSummary, SlackChannelConfig } from "@/lib/types";
 import { InstantSSRAutoRefresh } from "@/components/SSRAutoRefresh";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { SvgSlack } from "@opal/icons";
 import { FetchAgentsResponse, fetchAgentsSS } from "@/lib/agentsSS";
 import { getStandardAnswerCategoriesIfEE } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 
@@ -77,27 +72,28 @@ async function EditslackChannelConfigPage(props: {
   }
 
   return (
-    <div className="max-w-4xl container">
+    <SettingsLayouts.Root>
       <InstantSSRAutoRefresh />
-
-      <BackButton />
-      <AdminPageTitle
-        icon={<SourceIcon sourceType={ValidSources.Slack} iconSize={32} />}
+      <SettingsLayouts.Header
+        icon={SvgSlack}
         title={
           slackChannelConfig.is_default
             ? "Edit Default Slack Config"
             : "Edit Slack Channel Config"
         }
+        separator
+        backButton
       />
-
-      <SlackChannelConfigCreationForm
-        slack_bot_id={slackChannelConfig.slack_bot_id}
-        documentSets={documentSets}
-        personas={assistants}
-        standardAnswerCategoryResponse={eeStandardAnswerCategoryResponse}
-        existingSlackChannelConfig={slackChannelConfig}
-      />
-    </div>
+      <SettingsLayouts.Body>
+        <SlackChannelConfigCreationForm
+          slack_bot_id={slackChannelConfig.slack_bot_id}
+          documentSets={documentSets}
+          personas={assistants}
+          standardAnswerCategoryResponse={eeStandardAnswerCategoryResponse}
+          existingSlackChannelConfig={slackChannelConfig}
+        />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
 
diff --git a/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx b/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
index 7094043e364..8ef6cf32a28 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
@@ -1,13 +1,12 @@
-import { AdminPageTitle } from "@/components/admin/Title";
 import { SlackChannelConfigCreationForm } from "../SlackChannelConfigCreationForm";
 import { fetchSS } from "@/lib/utilsSS";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import { DocumentSetSummary, ValidSources } from "@/lib/types";
-import BackButton from "@/refresh-components/buttons/BackButton";
+import { DocumentSetSummary } from "@/lib/types";
 import { fetchAgentsSS } from "@/lib/agentsSS";
 import { getStandardAnswerCategoriesIfEE } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 import { redirect } from "next/navigation";
-import { SourceIcon } from "@/components/SourceIcon";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { SvgSlack } from "@opal/icons";
 
 async function NewChannelConfigPage(props: {
   params: Promise<{ "bot-id": string }>;
@@ -50,20 +49,22 @@ async function NewChannelConfigPage(props: {
   }
 
   return (
-    <>
-      <BackButton />
-      <AdminPageTitle
-        icon={<SourceIcon iconSize={32} sourceType={ValidSources.Slack} />}
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={SvgSlack}
         title="Configure OnyxBot for Slack Channel"
+        separator
+        backButton
       />
-
-      <SlackChannelConfigCreationForm
-        slack_bot_id={slack_bot_id}
-        documentSets={documentSets}
-        personas={agentsResponse[0]}
-        standardAnswerCategoryResponse={standardAnswerCategoryResponse}
-      />
-    </>
+      <SettingsLayouts.Body>
+        <SlackChannelConfigCreationForm
+          slack_bot_id={slack_bot_id}
+          documentSets={documentSets}
+          personas={agentsResponse[0]}
+          standardAnswerCategoryResponse={standardAnswerCategoryResponse}
+        />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
 
diff --git a/web/src/app/admin/bots/page.tsx b/web/src/app/admin/bots/page.tsx
index f04a71c5814..39a1aaba11d 100644
--- a/web/src/app/admin/bots/page.tsx
+++ b/web/src/app/admin/bots/page.tsx
@@ -3,15 +3,14 @@
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { InstantSSRAutoRefresh } from "@/components/SSRAutoRefresh";
-import { AdminPageTitle } from "@/components/admin/Title";
-import { SourceIcon } from "@/components/SourceIcon";
 import { SlackBotTable } from "./SlackBotTable";
 import { useSlackBots } from "./[bot-id]/hooks";
-import { ValidSources } from "@/lib/types";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { DOCS_ADMINS_PATH } from "@/lib/constants";
 
-const Main = () => {
+function Main() {
   const {
     data: slackBots,
     isLoading: isSlackBotsLoading,
@@ -73,20 +72,18 @@ const Main = () => {
       <SlackBotTable slackBots={slackBots} />
     </div>
   );
-};
+}
 
-const Page = () => {
-  return (
-    <>
-      <AdminPageTitle
-        icon={<SourceIcon iconSize={36} sourceType={ValidSources.Slack} />}
-        title="Slack Bots"
-      />
-      <InstantSSRAutoRefresh />
+export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.SLACK_BOTS]!;
 
-      <Main />
-    </>
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <InstantSSRAutoRefresh />
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/admin/configuration/document-processing/page.tsx b/web/src/app/admin/configuration/document-processing/page.tsx
index c44bc4d9a32..65ccc9e85db 100644
--- a/web/src/app/admin/configuration/document-processing/page.tsx
+++ b/web/src/app/admin/configuration/document-processing/page.tsx
@@ -4,13 +4,15 @@ import { useState } from "react";
 import CardSection from "@/components/admin/CardSection";
 import Button from "@/refresh-components/buttons/Button";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
-import { DocumentIcon2 } from "@/components/icons/icons";
 import useSWR from "swr";
 import { ThreeDotsLoader } from "@/components/Loading";
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 import { SvgLock } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DOCUMENT_PROCESSING]!;
 
 function Main() {
   const {
@@ -149,12 +151,11 @@ function Main() {
 
 export default function Page() {
   return (
-    <>
-      <AdminPageTitle
-        title="Document Processing"
-        icon={<DocumentIcon2 size={32} className="my-auto" />}
-      />
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/configuration/image-generation/page.tsx b/web/src/app/admin/configuration/image-generation/page.tsx
index 2f2fe1b7103..7df01bb1818 100644
--- a/web/src/app/admin/configuration/image-generation/page.tsx
+++ b/web/src/app/admin/configuration/image-generation/page.tsx
@@ -1,15 +1,17 @@
 "use client";
 
-import { SvgImage } from "@opal/icons";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import ImageGenerationContent from "./ImageGenerationContent";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.IMAGE_GENERATION]!;
 
 export default function Page() {
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
-        icon={SvgImage}
-        title="Image Generation"
+        icon={route.icon}
+        title={route.title}
         description="Settings for in-chat image generation."
       />
       <SettingsLayouts.Body>
diff --git a/web/src/app/admin/configuration/search/page.tsx b/web/src/app/admin/configuration/search/page.tsx
index 9ed12c2914d..25cef77e892 100644
--- a/web/src/app/admin/configuration/search/page.tsx
+++ b/web/src/app/admin/configuration/search/page.tsx
@@ -1,8 +1,8 @@
 "use client";
 
 import { ThreeDotsLoader } from "@/components/Loading";
-import { AdminPageTitle } from "@/components/admin/Title";
 import { errorHandlingFetcher } from "@/lib/fetcher";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Text from "@/components/ui/text";
 import Title from "@/components/ui/title";
 import Button from "@/refresh-components/buttons/Button";
@@ -19,7 +19,10 @@ import { SettingsContext } from "@/providers/SettingsProvider";
 import CardSection from "@/components/admin/CardSection";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { useToastFromQuery } from "@/hooks/useToast";
-import { SvgSearch } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.SEARCH_SETTINGS]!;
+
 export interface EmbeddingDetails {
   api_key: string;
   custom_config: any;
@@ -141,9 +144,11 @@ function Main() {
 
 export default function Page() {
   return (
-    <>
-      <AdminPageTitle title="Search Settings" icon={SvgSearch} />
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header title={route.title} icon={route.icon} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/configuration/web-search/page.tsx b/web/src/app/admin/configuration/web-search/page.tsx
index 0ee3d4b655e..f2df18db974 100644
--- a/web/src/app/admin/configuration/web-search/page.tsx
+++ b/web/src/app/admin/configuration/web-search/page.tsx
@@ -22,7 +22,10 @@ import {
   SvgOnyxLogo,
   SvgX,
 } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { WebProviderSetupModal } from "@/app/admin/configuration/web-search/WebProviderSetupModal";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.WEB_SEARCH]!;
 import {
   SEARCH_PROVIDERS_URL,
   SEARCH_PROVIDER_DETAILS,
@@ -403,8 +406,8 @@ export default function Page() {
     return (
       <SettingsLayouts.Root>
         <SettingsLayouts.Header
-          icon={SvgGlobe}
-          title="Web Search"
+          icon={route.icon}
+          title={route.title}
           description="Search settings for external search across the internet."
           separator
         />
@@ -426,8 +429,8 @@ export default function Page() {
     return (
       <SettingsLayouts.Root>
         <SettingsLayouts.Header
-          icon={SvgGlobe}
-          title="Web Search"
+          icon={route.icon}
+          title={route.title}
           description="Search settings for external search across the internet."
           separator
         />
@@ -832,8 +835,8 @@ export default function Page() {
     <>
       <SettingsLayouts.Root>
         <SettingsLayouts.Header
-          icon={SvgGlobe}
-          title="Web Search"
+          icon={route.icon}
+          title={route.title}
           description="Search settings for external search across the internet."
           separator
         />
diff --git a/web/src/app/admin/debug/page.tsx b/web/src/app/admin/debug/page.tsx
index 1055ac82d8f..d1f3d3d98e2 100644
--- a/web/src/app/admin/debug/page.tsx
+++ b/web/src/app/admin/debug/page.tsx
@@ -1,8 +1,7 @@
 "use client";
 
 import { useState, useEffect } from "react";
-import { AdminPageTitle } from "@/components/admin/Title";
-import { FiDownload } from "react-icons/fi";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { ThreeDotsLoader } from "@/components/Loading";
 import {
   Table,
@@ -17,6 +16,10 @@ import { Card } from "@/components/ui/card";
 import Text from "@/components/ui/text";
 import { Spinner } from "@/components/Spinner";
 import { SvgDownloadCloud } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DEBUG]!;
+
 function Main() {
   const [categories, setCategories] = useState<string[]>([]);
   const [isLoading, setIsLoading] = useState(true);
@@ -114,13 +117,13 @@ function Main() {
   );
 }
 
-const Page = () => {
+export default function Page() {
   return (
-    <>
-      <AdminPageTitle icon={<FiDownload size={32} />} title="Debug Logs" />
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/admin/discord-bot/page.tsx b/web/src/app/admin/discord-bot/page.tsx
index e6a0cad9040..e4dbe9ab752 100644
--- a/web/src/app/admin/discord-bot/page.tsx
+++ b/web/src/app/admin/discord-bot/page.tsx
@@ -19,7 +19,7 @@ import {
 import { createGuildConfig } from "@/app/admin/discord-bot/lib";
 import { DiscordGuildsTable } from "@/app/admin/discord-bot/DiscordGuildsTable";
 import { BotConfigCard } from "@/app/admin/discord-bot/BotConfigCard";
-import { SvgDiscordMono } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 
 function DiscordBotContent() {
   const { data: guilds, isLoading, error, refreshGuilds } = useDiscordGuilds();
@@ -118,11 +118,13 @@ function DiscordBotContent() {
 }
 
 export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DISCORD_BOTS]!;
+
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
-        icon={SvgDiscordMono}
-        title="Discord Bots"
+        icon={route.icon}
+        title={route.title}
         description="Connect Onyx to your Discord servers. Users can ask questions directly in Discord channels."
       />
       <SettingsLayouts.Body>
diff --git a/web/src/app/admin/document-index-migration/page.tsx b/web/src/app/admin/document-index-migration/page.tsx
index 19d0320ddc1..142764eec82 100644
--- a/web/src/app/admin/document-index-migration/page.tsx
+++ b/web/src/app/admin/document-index-migration/page.tsx
@@ -2,8 +2,11 @@
 
 import { useState } from "react";
 import useSWR from "swr";
-import { SvgArrowExchange } from "@opal/icons";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.INDEX_MIGRATION]!;
+
 import Card from "@/refresh-components/cards/Card";
 import { Content, ContentAction } from "@opal/layouts";
 import Text from "@/refresh-components/texts/Text";
@@ -213,8 +216,8 @@ export default function Page() {
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
-        icon={SvgArrowExchange}
-        title="Document Index Migration"
+        icon={route.icon}
+        title={route.title}
         description="Monitor the migration from Vespa to OpenSearch and control the active retrieval source."
         separator
       />
diff --git a/web/src/app/admin/documents/explorer/DocumentExplorerPage.tsx b/web/src/app/admin/documents/explorer/DocumentExplorerPage.tsx
new file mode 100644
index 00000000000..bf356277e1f
--- /dev/null
+++ b/web/src/app/admin/documents/explorer/DocumentExplorerPage.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+import { Explorer } from "./Explorer";
+import { Connector } from "@/lib/connectors/connectors";
+import { DocumentSetSummary } from "@/lib/types";
+
+interface DocumentExplorerPageProps {
+  initialSearchValue: string | undefined;
+  connectors: Connector<any>[];
+  documentSets: DocumentSetSummary[];
+}
+
+export default function DocumentExplorerPage({
+  initialSearchValue,
+  connectors,
+  documentSets,
+}: DocumentExplorerPageProps) {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DOCUMENT_EXPLORER]!;
+
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+
+      <SettingsLayouts.Body>
+        <Explorer
+          initialSearchValue={initialSearchValue}
+          connectors={connectors}
+          documentSets={documentSets}
+        />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
+  );
+}
diff --git a/web/src/app/admin/documents/explorer/page.tsx b/web/src/app/admin/documents/explorer/page.tsx
index 5dace8d1e0f..ef724cdc1b7 100644
--- a/web/src/app/admin/documents/explorer/page.tsx
+++ b/web/src/app/admin/documents/explorer/page.tsx
@@ -1,7 +1,6 @@
-import { AdminPageTitle } from "@/components/admin/Title";
-import { Explorer } from "./Explorer";
 import { fetchValidFilterInfo } from "@/lib/search/utilsSS";
-import { SvgZoomIn } from "@opal/icons";
+import DocumentExplorerPage from "./DocumentExplorerPage";
+
 export default async function Page(props: {
   searchParams: Promise<{ [key: string]: string }>;
 }) {
@@ -9,17 +8,10 @@ export default async function Page(props: {
   const { connectors, documentSets } = await fetchValidFilterInfo();
 
   return (
-    <>
-      <AdminPageTitle
-        icon={<SvgZoomIn className="stroke-text-04 h-8 w-8" />}
-        title="Document Explorer"
-      />
-
-      <Explorer
-        initialSearchValue={searchParams.query}
-        connectors={connectors}
-        documentSets={documentSets}
-      />
-    </>
+    <DocumentExplorerPage
+      initialSearchValue={searchParams.query}
+      connectors={connectors}
+      documentSets={documentSets}
+    />
   );
 }
diff --git a/web/src/app/admin/documents/feedback/page.tsx b/web/src/app/admin/documents/feedback/page.tsx
index e7296d54f7d..ec63bd776ab 100644
--- a/web/src/app/admin/documents/feedback/page.tsx
+++ b/web/src/app/admin/documents/feedback/page.tsx
@@ -4,10 +4,11 @@ import { LoadingAnimation } from "@/components/Loading";
 import { useMostReactedToDocuments } from "@/lib/hooks";
 import { DocumentFeedbackTable } from "./DocumentFeedbackTable";
 import { numPages, numToDisplay } from "./constants";
-import { AdminPageTitle } from "@/components/admin/Title";
 import Title from "@/components/ui/title";
-import { SvgThumbsUp } from "@opal/icons";
-const Main = () => {
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+function Main() {
   const {
     data: mostLikedDocuments,
     isLoading: isMostLikedDocumentsLoading,
@@ -57,16 +58,17 @@ const Main = () => {
       />
     </div>
   );
-};
+}
 
-const Page = () => {
-  return (
-    <>
-      <AdminPageTitle icon={SvgThumbsUp} title="Document Feedback" />
+export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DOCUMENT_FEEDBACK]!;
 
-      <Main />
-    </>
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/admin/documents/sets/[documentSetId]/page.tsx b/web/src/app/admin/documents/sets/[documentSetId]/page.tsx
index 05eb550b220..b12ca3d724e 100644
--- a/web/src/app/admin/documents/sets/[documentSetId]/page.tsx
+++ b/web/src/app/admin/documents/sets/[documentSetId]/page.tsx
@@ -5,9 +5,8 @@ import { ErrorCallout } from "@/components/ErrorCallout";
 import { refreshDocumentSets, useDocumentSets } from "../hooks";
 import { useConnectorStatus, useUserGroups } from "@/lib/hooks";
 import { ThreeDotsLoader } from "@/components/Loading";
-import { AdminPageTitle } from "@/components/admin/Title";
-import { BookmarkIcon } from "@/components/icons/icons";
-import BackButton from "@/refresh-components/buttons/BackButton";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import CardSection from "@/components/admin/CardSection";
 import { DocumentSetCreationForm } from "../DocumentSetCreationForm";
 import { useRouter } from "next/navigation";
@@ -69,24 +68,17 @@ function Main({ documentSetId }: { documentSetId: number }) {
   }
 
   return (
-    <div>
-      <AdminPageTitle
-        icon={<BookmarkIcon size={32} />}
-        title={documentSet.name}
+    <CardSection>
+      <DocumentSetCreationForm
+        ccPairs={ccPairs}
+        userGroups={userGroups}
+        onClose={() => {
+          refreshDocumentSets();
+          router.push("/admin/documents/sets");
+        }}
+        existingDocumentSet={documentSet}
       />
-
-      <CardSection>
-        <DocumentSetCreationForm
-          ccPairs={ccPairs}
-          userGroups={userGroups}
-          onClose={() => {
-            refreshDocumentSets();
-            router.push("/admin/documents/sets");
-          }}
-          existingDocumentSet={documentSet}
-        />
-      </CardSection>
-    </div>
+    </CardSection>
   );
 }
 
@@ -95,12 +87,19 @@ export default function Page(props: {
 }) {
   const params = use(props.params);
   const documentSetId = parseInt(params.documentSetId);
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DOCUMENT_SETS]!;
 
   return (
-    <>
-      <BackButton />
-
-      <Main documentSetId={documentSetId} />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={route.icon}
+        title="Edit Document Set"
+        separator
+        backButton
+      />
+      <SettingsLayouts.Body>
+        <Main documentSetId={documentSetId} />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/documents/sets/new/page.tsx b/web/src/app/admin/documents/sets/new/page.tsx
index a23580f6454..0b0a6c34857 100644
--- a/web/src/app/admin/documents/sets/new/page.tsx
+++ b/web/src/app/admin/documents/sets/new/page.tsx
@@ -1,11 +1,10 @@
 "use client";
 
-import { AdminPageTitle } from "@/components/admin/Title";
-import { BookmarkIcon } from "@/components/icons/icons";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { DocumentSetCreationForm } from "../DocumentSetCreationForm";
 import { useConnectorStatus, useUserGroups } from "@/lib/hooks";
 import { ThreeDotsLoader } from "@/components/Loading";
-import BackButton from "@/refresh-components/buttons/BackButton";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { useRouter } from "next/navigation";
 import { refreshDocumentSets } from "../hooks";
@@ -56,19 +55,20 @@ function Main() {
   );
 }
 
-const Page = () => {
-  return (
-    <>
-      <BackButton />
+export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DOCUMENT_SETS]!;
 
-      <AdminPageTitle
-        icon={<BookmarkIcon size={32} />}
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={route.icon}
         title="New Document Set"
+        separator
+        backButton
       />
-
-      <Main />
-    </>
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/admin/documents/sets/page.tsx b/web/src/app/admin/documents/sets/page.tsx
index dcd4f1da114..aa251d86e80 100644
--- a/web/src/app/admin/documents/sets/page.tsx
+++ b/web/src/app/admin/documents/sets/page.tsx
@@ -2,7 +2,7 @@
 
 import { ThreeDotsLoader } from "@/components/Loading";
 import { PageSelector } from "@/components/PageSelector";
-import { BookmarkIcon, InfoIcon } from "@/components/icons/icons";
+import { InfoIcon } from "@/components/icons/icons";
 import {
   Table,
   TableHead,
@@ -19,7 +19,8 @@ import { useDocumentSets } from "./hooks";
 import { ConnectorTitle } from "@/components/admin/connectors/ConnectorTitle";
 import { deleteDocumentSet } from "./lib";
 import { toast } from "@/hooks/useToast";
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import {
   FiAlertTriangle,
   FiCheckCircle,
@@ -358,7 +359,7 @@ const DocumentSetTable = ({
   );
 };
 
-const Main = () => {
+function Main() {
   const {
     data: documentSets,
     isLoading: isDocumentSetsLoading,
@@ -418,16 +419,17 @@ const Main = () => {
       )}
     </div>
   );
-};
+}
 
-const Page = () => {
-  return (
-    <>
-      <AdminPageTitle icon={<BookmarkIcon size={32} />} title="Document Sets" />
+export default function Page() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.DOCUMENT_SETS]!;
 
-      <Main />
-    </>
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx b/web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx
index 4311a444054..ace8da49d1a 100644
--- a/web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx
+++ b/web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx
@@ -165,7 +165,7 @@ function ConnectorRow({
       onClick={handleRowClick}
     >
       <TableCell className="">
-        <p className="lg:w-[200px] xl:w-[400px] inline-block ellipsis truncate">
+        <p className="max-w-[200px] xl:max-w-[400px] inline-block ellipsis truncate">
           {ccPairsIndexingStatus.name}
         </p>
       </TableCell>
@@ -246,7 +246,7 @@ function FederatedConnectorRow({
       onClick={handleRowClick}
     >
       <TableCell className="">
-        <p className="lg:w-[200px] xl:w-[400px] inline-block ellipsis truncate">
+        <p className="max-w-[200px] xl:max-w-[400px] inline-block ellipsis truncate">
           {federatedConnector.name}
         </p>
       </TableCell>
@@ -293,7 +293,7 @@ export function CCPairIndexingStatusTable({
   const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
 
   return (
-    <Table className="-mt-8">
+    <Table className="-mt-8 table-fixed">
       <TableHeader>
         <ConnectorRow
           invisible
diff --git a/web/src/app/admin/indexing/status/page.tsx b/web/src/app/admin/indexing/status/page.tsx
index fdb96be626f..48725c14292 100644
--- a/web/src/app/admin/indexing/status/page.tsx
+++ b/web/src/app/admin/indexing/status/page.tsx
@@ -1,10 +1,10 @@
 "use client";
 
-import { NotebookIcon } from "@/components/icons/icons";
 import { CCPairIndexingStatusTable } from "./CCPairIndexingStatusTable";
 import { SearchAndFilterControls } from "./SearchAndFilterControls";
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Link from "next/link";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import Text from "@/components/ui/text";
 import { useConnectorIndexingStatusWithPagination } from "@/lib/hooks";
 import { useToastFromQuery } from "@/hooks/useToast";
@@ -201,6 +201,8 @@ function Main() {
 }
 
 export default function Status() {
+  const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.INDEXING_STATUS]!;
+
   useToastFromQuery({
     "connector-created": {
       message: "Connector created successfully",
@@ -213,16 +215,18 @@ export default function Status() {
   });
 
   return (
-    <>
-      <AdminPageTitle
-        icon={<NotebookIcon size={32} />}
-        title="Existing Connectors"
-        farRightElement={
+    <SettingsLayouts.Root width="full">
+      <SettingsLayouts.Header
+        icon={route.icon}
+        title={route.title}
+        rightChildren={
           <Button href="/admin/add-connector">Add Connector</Button>
         }
+        separator
       />
-
-      <Main />
-    </>
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/kg/page.tsx b/web/src/app/admin/kg/page.tsx
index 0b159c439b2..a2dc19d21cd 100644
--- a/web/src/app/admin/kg/page.tsx
+++ b/web/src/app/admin/kg/page.tsx
@@ -1,14 +1,13 @@
 "use client";
 
 import CardSection from "@/components/admin/CardSection";
-import { AdminPageTitle } from "@/components/admin/Title";
 import {
   DatePickerField,
   FieldLabel,
   TextArrayField,
   TextFormField,
 } from "@/components/Field";
-import { BrainIcon } from "@/components/icons/icons";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Modal from "@/refresh-components/Modal";
 import Button from "@/refresh-components/buttons/Button";
 import SwitchField from "@/refresh-components/form/SwitchField";
@@ -31,6 +30,9 @@ import KGEntityTypes from "@/app/admin/kg/KGEntityTypes";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 import { SvgSettings } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.KNOWLEDGE_GRAPH]!;
 
 function createDomainField(
   name: string,
@@ -324,12 +326,11 @@ export default function Page() {
   }
 
   return (
-    <>
-      <AdminPageTitle
-        title="Knowledge Graph"
-        icon={<BrainIcon size={32} className="my-auto" />}
-      />
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/token-rate-limits/page.tsx b/web/src/app/admin/token-rate-limits/page.tsx
index 0a300b3a43d..b60db098174 100644
--- a/web/src/app/admin/token-rate-limits/page.tsx
+++ b/web/src/app/admin/token-rate-limits/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
-import { AdminPageTitle } from "@/components/admin/Title";
 import SimpleTabs from "@/refresh-components/SimpleTabs";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Text from "@/components/ui/text";
 import { useState } from "react";
 import {
@@ -16,8 +16,11 @@ import { toast } from "@/hooks/useToast";
 import CreateRateLimitModal from "./CreateRateLimitModal";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import { SvgGlobe, SvgShield, SvgUser, SvgUsers } from "@opal/icons";
+import { SvgGlobe, SvgUser, SvgUsers } from "@opal/icons";
 import { Section } from "@/layouts/general-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.TOKEN_RATE_LIMITS]!;
 const BASE_URL = "/api/admin/token-rate-limits";
 const GLOBAL_TOKEN_FETCH_URL = `${BASE_URL}/global`;
 const USER_TOKEN_FETCH_URL = `${BASE_URL}/users`;
@@ -208,9 +211,11 @@ function Main() {
 
 export default function Page() {
   return (
-    <>
-      <AdminPageTitle title="Token Rate Limits" icon={SvgShield} />
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header title={route.title} icon={route.icon} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/users/page.tsx b/web/src/app/admin/users/page.tsx
index 4e99c9c855e..fd98bfdbeec 100644
--- a/web/src/app/admin/users/page.tsx
+++ b/web/src/app/admin/users/page.tsx
@@ -5,11 +5,10 @@ import SimpleTabs from "@/refresh-components/SimpleTabs";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import InvitedUserTable from "@/components/admin/users/InvitedUserTable";
 import SignedUpUserTable from "@/components/admin/users/SignedUpUserTable";
-
 import Modal from "@/refresh-components/Modal";
 import { ThreeDotsLoader } from "@/components/Loading";
-import { AdminPageTitle } from "@/components/admin/Title";
 import { toast } from "@/hooks/useToast";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import useSWR, { mutate } from "swr";
 import { ErrorCallout } from "@/components/ErrorCallout";
@@ -22,7 +21,11 @@ import CreateButton from "@/refresh-components/buttons/CreateButton";
 import Button from "@/refresh-components/buttons/Button";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { Spinner } from "@/components/Spinner";
-import { SvgDownloadCloud, SvgUser, SvgUserPlus } from "@opal/icons";
+import { SvgDownloadCloud, SvgUserPlus } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.USERS]!;
+
 interface CountDisplayProps {
   label: string;
   value: number | null;
@@ -48,7 +51,7 @@ function CountDisplay({ label, value, isLoading }: CountDisplayProps) {
   );
 }
 
-const UsersTables = ({
+function UsersTables({
   q,
   isDownloadingUsers,
   setIsDownloadingUsers,
@@ -56,7 +59,7 @@ const UsersTables = ({
   q: string;
   isDownloadingUsers: boolean;
   setIsDownloadingUsers: (loading: boolean) => void;
-}) => {
+}) {
   const [currentUsersCount, setCurrentUsersCount] = useState<number | null>(
     null
   );
@@ -236,9 +239,9 @@ const UsersTables = ({
   });
 
   return <SimpleTabs tabs={tabs} defaultValue="current" />;
-};
+}
 
-const SearchableTables = () => {
+function SearchableTables() {
   const [query, setQuery] = useState("");
   const [isDownloadingUsers, setIsDownloadingUsers] = useState(false);
 
@@ -262,7 +265,7 @@ const SearchableTables = () => {
       </div>
     </div>
   );
-};
+}
 
 function AddUserButton() {
   const [bulkAddUsersModal, setBulkAddUsersModal] = useState(false);
@@ -325,13 +328,13 @@ function AddUserButton() {
   );
 }
 
-const Page = () => {
+export default function Page() {
   return (
-    <>
-      <AdminPageTitle title="Manage Users" icon={SvgUser} />
-      <SearchableTables />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header title={route.title} icon={route.icon} separator />
+      <SettingsLayouts.Body>
+        <SearchableTables />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/ee/admin/billing/page.tsx b/web/src/app/ee/admin/billing/page.tsx
index c1bea079d56..e69288b694f 100644
--- a/web/src/app/ee/admin/billing/page.tsx
+++ b/web/src/app/ee/admin/billing/page.tsx
@@ -1,6 +1,6 @@
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import BillingInformationPage from "./BillingInformationPage";
-import { MdOutlineCreditCard } from "react-icons/md";
+import { SvgCreditCard } from "@opal/icons";
 
 export interface BillingInformation {
   stripe_subscription_id: string;
@@ -18,12 +18,15 @@ export interface BillingInformation {
 
 export default function page() {
   return (
-    <>
-      <AdminPageTitle
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={SvgCreditCard}
         title="Billing Information"
-        icon={<MdOutlineCreditCard size={32} className="my-auto" />}
+        separator
       />
-      <BillingInformationPage />
-    </>
+      <SettingsLayouts.Body>
+        <BillingInformationPage />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/ee/admin/groups/[groupId]/page.tsx b/web/src/app/ee/admin/groups/[groupId]/page.tsx
index ee30626a23c..1cfd5b4234f 100644
--- a/web/src/app/ee/admin/groups/[groupId]/page.tsx
+++ b/web/src/app/ee/admin/groups/[groupId]/page.tsx
@@ -1,25 +1,23 @@
 "use client";
-import { use } from "react";
 
+import { use } from "react";
 import { GroupDisplay } from "./GroupDisplay";
 import { useSpecificUserGroup } from "./hook";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { useConnectorStatus } from "@/lib/hooks";
-import { useRouter } from "next/navigation";
 import useUsers from "@/hooks/useUsers";
-import BackButton from "@/refresh-components/buttons/BackButton";
-import { AdminPageTitle } from "@/components/admin/Title";
-import { SvgUsers } from "@opal/icons";
-const Page = (props: { params: Promise<{ groupId: string }> }) => {
-  const params = use(props.params);
-  const router = useRouter();
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.GROUPS]!;
+
+function Main({ groupId }: { groupId: string }) {
   const {
     userGroup,
     isLoading: userGroupIsLoading,
     error: userGroupError,
     refreshUserGroup,
-  } = useSpecificUserGroup(params.groupId);
+  } = useSpecificUserGroup(groupId);
   const {
     data: users,
     isLoading: userIsLoading,
@@ -53,22 +51,31 @@ const Page = (props: { params: Promise<{ groupId: string }> }) => {
 
   return (
     <>
-      <BackButton />
-
-      <AdminPageTitle title={userGroup.name || "Unknown"} icon={SvgUsers} />
+      <SettingsLayouts.Header
+        icon={route.icon}
+        title={userGroup.name || "Unknown"}
+        separator
+        backButton
+      />
 
-      {userGroup ? (
+      <SettingsLayouts.Body>
         <GroupDisplay
           users={users.accepted}
           ccPairs={ccPairs}
           userGroup={userGroup}
           refreshUserGroup={refreshUserGroup}
         />
-      ) : (
-        <div>Unable to fetch User Group :(</div>
-      )}
+      </SettingsLayouts.Body>
     </>
   );
-};
+}
 
-export default Page;
+export default function Page(props: { params: Promise<{ groupId: string }> }) {
+  const params = use(props.params);
+
+  return (
+    <SettingsLayouts.Root>
+      <Main groupId={params.groupId} />
+    </SettingsLayouts.Root>
+  );
+}
diff --git a/web/src/app/ee/admin/groups/page.tsx b/web/src/app/ee/admin/groups/page.tsx
index 110631c5bd8..d6a977d2205 100644
--- a/web/src/app/ee/admin/groups/page.tsx
+++ b/web/src/app/ee/admin/groups/page.tsx
@@ -5,13 +5,15 @@ import UserGroupCreationForm from "./UserGroupCreationForm";
 import { useState } from "react";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { useConnectorStatus, useUserGroups } from "@/lib/hooks";
-import { AdminPageTitle } from "@/components/admin/Title";
 import useUsers from "@/hooks/useUsers";
-
 import { useUser } from "@/providers/UserProvider";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import { SvgUsers } from "@opal/icons";
-const Main = () => {
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.GROUPS]!;
+
+function Main() {
   const [showForm, setShowForm] = useState(false);
 
   const { data, isLoading, error, refreshUserGroups } = useUserGroups();
@@ -70,16 +72,16 @@ const Main = () => {
       )}
     </>
   );
-};
+}
 
-const Page = () => {
+export default function Page() {
   return (
-    <>
-      <AdminPageTitle title="Manage User Groups" icon={SvgUsers} />
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
 
-      <Main />
-    </>
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/ee/admin/performance/custom-analytics/page.tsx b/web/src/app/ee/admin/performance/custom-analytics/page.tsx
index 7e22fe5cade..7cad4c95483 100644
--- a/web/src/app/ee/admin/performance/custom-analytics/page.tsx
+++ b/web/src/app/ee/admin/performance/custom-analytics/page.tsx
@@ -1,10 +1,12 @@
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { CUSTOM_ANALYTICS_ENABLED } from "@/lib/constants";
 import { Callout } from "@/components/ui/callout";
-import { FiBarChart2 } from "react-icons/fi";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import Text from "@/components/ui/text";
 import { CustomAnalyticsUpdateForm } from "./CustomAnalyticsUpdateForm";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.CUSTOM_ANALYTICS]!;
+
 function Main() {
   if (!CUSTOM_ANALYTICS_ENABLED) {
     return (
@@ -35,13 +37,11 @@ function Main() {
 
 export default function Page() {
   return (
-    <main className="pt-4 mx-auto container">
-      <AdminPageTitle
-        title="Custom Analytics"
-        icon={<FiBarChart2 size={32} />}
-      />
-
-      <Main />
-    </main>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/ee/admin/performance/query-history/page.tsx b/web/src/app/ee/admin/performance/query-history/page.tsx
index 4d8437fc178..f3c3020043f 100644
--- a/web/src/app/ee/admin/performance/query-history/page.tsx
+++ b/web/src/app/ee/admin/performance/query-history/page.tsx
@@ -1,14 +1,19 @@
 "use client";
 
-import { AdminPageTitle } from "@/components/admin/Title";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { QueryHistoryTable } from "@/app/ee/admin/performance/query-history/QueryHistoryTable";
-import { SvgServer } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.QUERY_HISTORY]!;
+
 export default function QueryHistoryPage() {
   return (
-    <>
-      <AdminPageTitle title="Query History" icon={SvgServer} />
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
 
-      <QueryHistoryTable />
-    </>
+      <SettingsLayouts.Body>
+        <QueryHistoryTable />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/ee/admin/performance/usage/page.tsx b/web/src/app/ee/admin/performance/usage/page.tsx
index e3add6b195d..07a69cd86ea 100644
--- a/web/src/app/ee/admin/performance/usage/page.tsx
+++ b/web/src/app/ee/admin/performance/usage/page.tsx
@@ -6,32 +6,36 @@ import { FeedbackChart } from "@/app/ee/admin/performance/usage/FeedbackChart";
 import { QueryPerformanceChart } from "@/app/ee/admin/performance/usage/QueryPerformanceChart";
 import { PersonaMessagesChart } from "@/app/ee/admin/performance/usage/PersonaMessagesChart";
 import { useTimeRange } from "@/app/ee/admin/performance/lib";
-import { AdminPageTitle } from "@/components/admin/Title";
 import UsageReports from "@/app/ee/admin/performance/usage/UsageReports";
 import Separator from "@/refresh-components/Separator";
 import { useAdminPersonas } from "@/hooks/useAdminPersonas";
-import { SvgActivity } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.USAGE]!;
 
 export default function AnalyticsPage() {
   const [timeRange, setTimeRange] = useTimeRange();
   const { personas } = useAdminPersonas();
 
   return (
-    <>
-      <AdminPageTitle title="Usage Statistics" icon={SvgActivity} />
-      <AdminDateRangeSelector
-        value={timeRange}
-        onValueChange={(value) => setTimeRange(value as any)}
-      />
-      <QueryPerformanceChart timeRange={timeRange} />
-      <FeedbackChart timeRange={timeRange} />
-      <OnyxBotChart timeRange={timeRange} />
-      <PersonaMessagesChart
-        availablePersonas={personas}
-        timeRange={timeRange}
-      />
-      <Separator />
-      <UsageReports />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <AdminDateRangeSelector
+          value={timeRange}
+          onValueChange={(value) => setTimeRange(value as any)}
+        />
+        <QueryPerformanceChart timeRange={timeRange} />
+        <FeedbackChart timeRange={timeRange} />
+        <OnyxBotChart timeRange={timeRange} />
+        <PersonaMessagesChart
+          availablePersonas={personas}
+          timeRange={timeRange}
+        />
+        <Separator />
+        <UsageReports />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/ee/admin/standard-answer/[id]/page.tsx b/web/src/app/ee/admin/standard-answer/[id]/page.tsx
index ec5a96bcf1b..0fb3e7faddf 100644
--- a/web/src/app/ee/admin/standard-answer/[id]/page.tsx
+++ b/web/src/app/ee/admin/standard-answer/[id]/page.tsx
@@ -1,13 +1,13 @@
-import { AdminPageTitle } from "@/components/admin/Title";
 import { StandardAnswerCreationForm } from "@/app/ee/admin/standard-answer/StandardAnswerCreationForm";
 import { fetchSS } from "@/lib/utilsSS";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import BackButton from "@/refresh-components/buttons/BackButton";
-import { ClipboardIcon } from "@/components/icons/icons";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { StandardAnswer, StandardAnswerCategory } from "@/lib/types";
 
-async function Page(props: { params: Promise<{ id: string }> }) {
-  const params = await props.params;
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.STANDARD_ANSWERS]!;
+
+async function Main({ id }: { id: string }) {
   const tasks = [
     fetchSS("/manage/admin/standard-answer"),
     fetchSS(`/manage/admin/standard-answer/category`),
@@ -35,14 +35,14 @@ async function Page(props: { params: Promise<{ id: string }> }) {
   const allStandardAnswers =
     (await standardAnswersResponse.json()) as StandardAnswer[];
   const standardAnswer = allStandardAnswers.find(
-    (answer) => answer.id.toString() === params.id
+    (answer) => answer.id.toString() === id
   );
 
   if (!standardAnswer) {
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Did not find standard answer with ID: ${params.id}`}
+        errorMsg={`Did not find standard answer with ID: ${id}`}
       />
     );
   }
@@ -67,20 +67,29 @@ async function Page(props: { params: Promise<{ id: string }> }) {
 
   const standardAnswerCategories =
     (await standardAnswerCategoriesResponse.json()) as StandardAnswerCategory[];
+
   return (
-    <>
-      <BackButton />
-      <AdminPageTitle
-        title="Edit Standard Answer"
-        icon={<ClipboardIcon size={32} />}
-      />
+    <StandardAnswerCreationForm
+      standardAnswerCategories={standardAnswerCategories}
+      existingStandardAnswer={standardAnswer}
+    />
+  );
+}
+
+export default async function Page(props: { params: Promise<{ id: string }> }) {
+  const params = await props.params;
 
-      <StandardAnswerCreationForm
-        standardAnswerCategories={standardAnswerCategories}
-        existingStandardAnswer={standardAnswer}
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={route.icon}
+        title="Edit Standard Answer"
+        backButton
+        separator
       />
-    </>
+      <SettingsLayouts.Body>
+        <Main id={params.id} />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
-
-export default Page;
diff --git a/web/src/app/ee/admin/standard-answer/new/page.tsx b/web/src/app/ee/admin/standard-answer/new/page.tsx
index 0352e8fb865..9de73e3db2f 100644
--- a/web/src/app/ee/admin/standard-answer/new/page.tsx
+++ b/web/src/app/ee/admin/standard-answer/new/page.tsx
@@ -1,11 +1,12 @@
-import { AdminPageTitle } from "@/components/admin/Title";
 import { StandardAnswerCreationForm } from "@/app/ee/admin/standard-answer/StandardAnswerCreationForm";
 import { fetchSS } from "@/lib/utilsSS";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import BackButton from "@/refresh-components/buttons/BackButton";
-import { ClipboardIcon } from "@/components/icons/icons";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { StandardAnswerCategory } from "@/lib/types";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.STANDARD_ANSWERS]!;
+
 async function Page() {
   const standardAnswerCategoriesResponse = await fetchSS(
     "/manage/admin/standard-answer/category"
@@ -23,17 +24,19 @@ async function Page() {
     (await standardAnswerCategoriesResponse.json()) as StandardAnswerCategory[];
 
   return (
-    <>
-      <BackButton />
-      <AdminPageTitle
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={route.icon}
         title="New Standard Answer"
-        icon={<ClipboardIcon size={32} />}
-      />
-
-      <StandardAnswerCreationForm
-        standardAnswerCategories={standardAnswerCategories}
+        backButton
+        separator
       />
-    </>
+      <SettingsLayouts.Body>
+        <StandardAnswerCreationForm
+          standardAnswerCategories={standardAnswerCategories}
+        />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
 
diff --git a/web/src/app/ee/admin/standard-answer/page.tsx b/web/src/app/ee/admin/standard-answer/page.tsx
index ce5540e20e4..19976d396b7 100644
--- a/web/src/app/ee/admin/standard-answer/page.tsx
+++ b/web/src/app/ee/admin/standard-answer/page.tsx
@@ -1,7 +1,6 @@
 "use client";
 
-import { AdminPageTitle } from "@/components/admin/Title";
-import { ClipboardIcon, EditIcon } from "@/components/icons/icons";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { toast } from "@/hooks/useToast";
 import { useStandardAnswers, useStandardAnswerCategories } from "./hooks";
 import { ThreeDotsLoader } from "@/components/Loading";
@@ -29,10 +28,13 @@ import { PageSelector } from "@/components/PageSelector";
 import Text from "@/components/ui/text";
 import { TableHeader } from "@/components/ui/table";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import { SvgTrash } from "@opal/icons";
+import { SvgEdit, SvgTrash } from "@opal/icons";
 import { Button } from "@opal/components";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 const NUM_RESULTS_PER_PAGE = 10;
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.STANDARD_ANSWERS]!;
+
 type Displayable = JSX.Element | string;
 
 const RowTemplate = ({
@@ -113,7 +115,7 @@ const StandardAnswersTableRow = ({
           key={`edit-${standardAnswer.id}`}
           href={`/ee/admin/standard-answer/${standardAnswer.id}` as Route}
         >
-          <EditIcon />
+          <SvgEdit size={16} />
         </Link>,
         <div key={`categories-${standardAnswer.id}`}>
           {standardAnswer.categories.map((category) => (
@@ -344,7 +346,7 @@ const StandardAnswersTable = ({
   );
 };
 
-const Main = () => {
+function Main() {
   const {
     data: standardAnswers,
     error: standardAnswersError,
@@ -413,18 +415,15 @@ const Main = () => {
       </div>
     </div>
   );
-};
+}
 
-const Page = () => {
+export default function Page() {
   return (
-    <>
-      <AdminPageTitle
-        icon={<ClipboardIcon size={32} />}
-        title="Standard Answers"
-      />
-      <Main />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
-};
-
-export default Page;
+}
diff --git a/web/src/app/ee/admin/theme/page.tsx b/web/src/app/ee/admin/theme/page.tsx
index bd8cbb4f035..0af15a1e6c1 100644
--- a/web/src/app/ee/admin/theme/page.tsx
+++ b/web/src/app/ee/admin/theme/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import * as SettingsLayouts from "@/layouts/settings-layouts";
-import { SvgPaintBrush } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import Button from "@/refresh-components/buttons/Button";
 import {
   AppearanceThemeSettings,
@@ -15,6 +15,8 @@ import * as Yup from "yup";
 import { EnterpriseSettings } from "@/interfaces/settings";
 import { useRouter } from "next/navigation";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.THEME]!;
+
 const CHAR_LIMITS = {
   application_name: 50,
   custom_greeting_message: 50,
@@ -211,9 +213,9 @@ export default function ThemePage() {
           <Form className="w-full h-full">
             <SettingsLayouts.Root>
               <SettingsLayouts.Header
-                title="Appearance & Theming"
+                title={route.title}
                 description="Customize how the application appears to users across your organization."
-                icon={SvgPaintBrush}
+                icon={route.icon}
                 rightChildren={
                   <Button
                     type="button"
diff --git a/web/src/components/admin/ClientLayout.tsx b/web/src/components/admin/ClientLayout.tsx
index faabe77438d..20f21ca7d27 100644
--- a/web/src/components/admin/ClientLayout.tsx
+++ b/web/src/components/admin/ClientLayout.tsx
@@ -6,6 +6,7 @@ import { useSettingsContext } from "@/providers/SettingsProvider";
 import { ApplicationStatus } from "@/interfaces/settings";
 import Button from "@/refresh-components/buttons/Button";
 import { cn } from "@/lib/utils";
+import { ADMIN_PATHS } from "@/lib/admin-routes";
 
 export interface ClientLayoutProps {
   children: React.ReactNode;
@@ -18,16 +19,32 @@ export interface ClientLayoutProps {
 // the `py-10 px-4 md:px-12` padding below can be removed entirely and
 // this prefix list can be deleted.
 const SETTINGS_LAYOUT_PREFIXES = [
-  "/admin/configuration/chat-preferences",
-  "/admin/configuration/image-generation",
-  "/admin/configuration/web-search",
-  "/admin/actions/mcp",
-  "/admin/actions/open-api",
-  "/admin/billing",
-  "/admin/document-index-migration",
-  "/admin/discord-bot",
-  "/admin/theme",
-  "/admin/configuration/llm",
+  ADMIN_PATHS.CHAT_PREFERENCES,
+  ADMIN_PATHS.IMAGE_GENERATION,
+  ADMIN_PATHS.WEB_SEARCH,
+  ADMIN_PATHS.MCP_ACTIONS,
+  ADMIN_PATHS.OPENAPI_ACTIONS,
+  ADMIN_PATHS.BILLING,
+  ADMIN_PATHS.INDEX_MIGRATION,
+  ADMIN_PATHS.DISCORD_BOTS,
+  ADMIN_PATHS.THEME,
+  ADMIN_PATHS.LLM_MODELS,
+  ADMIN_PATHS.AGENTS,
+  ADMIN_PATHS.USERS,
+  ADMIN_PATHS.TOKEN_RATE_LIMITS,
+  ADMIN_PATHS.SEARCH_SETTINGS,
+  ADMIN_PATHS.DOCUMENT_PROCESSING,
+  ADMIN_PATHS.CODE_INTERPRETER,
+  ADMIN_PATHS.API_KEYS,
+  ADMIN_PATHS.ADD_CONNECTOR,
+  ADMIN_PATHS.INDEXING_STATUS,
+  ADMIN_PATHS.DOCUMENTS,
+  ADMIN_PATHS.DEBUG,
+  ADMIN_PATHS.KNOWLEDGE_GRAPH,
+  ADMIN_PATHS.SLACK_BOTS,
+  ADMIN_PATHS.STANDARD_ANSWERS,
+  ADMIN_PATHS.GROUPS,
+  ADMIN_PATHS.PERFORMANCE,
 ];
 
 export function ClientLayout({
diff --git a/web/src/lib/admin-routes.ts b/web/src/lib/admin-routes.ts
new file mode 100644
index 00000000000..132617e1d65
--- /dev/null
+++ b/web/src/lib/admin-routes.ts
@@ -0,0 +1,245 @@
+import { IconFunctionComponent } from "@opal/types";
+import {
+  SvgActions,
+  SvgActivity,
+  SvgArrowExchange,
+  SvgBarChart,
+  SvgBookOpen,
+  SvgBubbleText,
+  SvgClipboard,
+  SvgCpu,
+  SvgDiscordMono,
+  SvgDownload,
+  SvgFileText,
+  SvgFolder,
+  SvgGlobe,
+  SvgImage,
+  SvgKey,
+  SvgMcp,
+  SvgNetworkGraph,
+  SvgOnyxOctagon,
+  SvgPaintBrush,
+  SvgSearch,
+  SvgServer,
+  SvgShield,
+  SvgSlack,
+  SvgTerminal,
+  SvgThumbsUp,
+  SvgUploadCloud,
+  SvgUser,
+  SvgUsers,
+  SvgWallet,
+  SvgZoomIn,
+} from "@opal/icons";
+
+/**
+ * Canonical path constants for every admin route.
+ */
+export const ADMIN_PATHS = {
+  INDEXING_STATUS: "/admin/indexing/status",
+  ADD_CONNECTOR: "/admin/add-connector",
+  DOCUMENT_SETS: "/admin/documents/sets",
+  DOCUMENT_EXPLORER: "/admin/documents/explorer",
+  DOCUMENT_FEEDBACK: "/admin/documents/feedback",
+  AGENTS: "/admin/agents",
+  SLACK_BOTS: "/admin/bots",
+  DISCORD_BOTS: "/admin/discord-bot",
+  MCP_ACTIONS: "/admin/actions/mcp",
+  OPENAPI_ACTIONS: "/admin/actions/open-api",
+  STANDARD_ANSWERS: "/admin/standard-answer",
+  GROUPS: "/admin/groups",
+  CHAT_PREFERENCES: "/admin/configuration/chat-preferences",
+  LLM_MODELS: "/admin/configuration/llm",
+  WEB_SEARCH: "/admin/configuration/web-search",
+  IMAGE_GENERATION: "/admin/configuration/image-generation",
+  CODE_INTERPRETER: "/admin/configuration/code-interpreter",
+  SEARCH_SETTINGS: "/admin/configuration/search",
+  DOCUMENT_PROCESSING: "/admin/configuration/document-processing",
+  KNOWLEDGE_GRAPH: "/admin/kg",
+  USERS: "/admin/users",
+  API_KEYS: "/admin/api-key",
+  TOKEN_RATE_LIMITS: "/admin/token-rate-limits",
+  USAGE: "/admin/performance/usage",
+  QUERY_HISTORY: "/admin/performance/query-history",
+  CUSTOM_ANALYTICS: "/admin/performance/custom-analytics",
+  THEME: "/admin/theme",
+  BILLING: "/admin/billing",
+  INDEX_MIGRATION: "/admin/document-index-migration",
+  DEBUG: "/admin/debug",
+  // Prefix-only entries (used in SETTINGS_LAYOUT_PREFIXES but have no
+  // single page header of their own)
+  DOCUMENTS: "/admin/documents",
+  PERFORMANCE: "/admin/performance",
+} as const;
+
+interface AdminRouteConfig {
+  icon: IconFunctionComponent;
+  title: string;
+  sidebarLabel: string;
+}
+
+/**
+ * Single source of truth for icon, page-header title, and sidebar label
+ * for every admin route. Keyed by path from `ADMIN_PATHS`.
+ */
+export const ADMIN_ROUTE_CONFIG: Record<string, AdminRouteConfig> = {
+  [ADMIN_PATHS.INDEXING_STATUS]: {
+    icon: SvgBookOpen,
+    title: "Existing Connectors",
+    sidebarLabel: "Existing Connectors",
+  },
+  [ADMIN_PATHS.ADD_CONNECTOR]: {
+    icon: SvgUploadCloud,
+    title: "Add Connector",
+    sidebarLabel: "Add Connector",
+  },
+  [ADMIN_PATHS.DOCUMENT_SETS]: {
+    icon: SvgFolder,
+    title: "Document Sets",
+    sidebarLabel: "Document Sets",
+  },
+  [ADMIN_PATHS.DOCUMENT_EXPLORER]: {
+    icon: SvgZoomIn,
+    title: "Document Explorer",
+    sidebarLabel: "Explorer",
+  },
+  [ADMIN_PATHS.DOCUMENT_FEEDBACK]: {
+    icon: SvgThumbsUp,
+    title: "Document Feedback",
+    sidebarLabel: "Feedback",
+  },
+  [ADMIN_PATHS.AGENTS]: {
+    icon: SvgOnyxOctagon,
+    title: "Agents",
+    sidebarLabel: "Agents",
+  },
+  [ADMIN_PATHS.SLACK_BOTS]: {
+    icon: SvgSlack,
+    title: "Slack Bots",
+    sidebarLabel: "Slack Bots",
+  },
+  [ADMIN_PATHS.DISCORD_BOTS]: {
+    icon: SvgDiscordMono,
+    title: "Discord Bots",
+    sidebarLabel: "Discord Bots",
+  },
+  [ADMIN_PATHS.MCP_ACTIONS]: {
+    icon: SvgMcp,
+    title: "MCP Actions",
+    sidebarLabel: "MCP Actions",
+  },
+  [ADMIN_PATHS.OPENAPI_ACTIONS]: {
+    icon: SvgActions,
+    title: "OpenAPI Actions",
+    sidebarLabel: "OpenAPI Actions",
+  },
+  [ADMIN_PATHS.STANDARD_ANSWERS]: {
+    icon: SvgClipboard,
+    title: "Standard Answers",
+    sidebarLabel: "Standard Answers",
+  },
+  [ADMIN_PATHS.GROUPS]: {
+    icon: SvgUsers,
+    title: "Manage User Groups",
+    sidebarLabel: "Groups",
+  },
+  [ADMIN_PATHS.CHAT_PREFERENCES]: {
+    icon: SvgBubbleText,
+    title: "Chat Preferences",
+    sidebarLabel: "Chat Preferences",
+  },
+  [ADMIN_PATHS.LLM_MODELS]: {
+    icon: SvgCpu,
+    title: "LLM Models",
+    sidebarLabel: "LLM Models",
+  },
+  [ADMIN_PATHS.WEB_SEARCH]: {
+    icon: SvgGlobe,
+    title: "Web Search",
+    sidebarLabel: "Web Search",
+  },
+  [ADMIN_PATHS.IMAGE_GENERATION]: {
+    icon: SvgImage,
+    title: "Image Generation",
+    sidebarLabel: "Image Generation",
+  },
+  [ADMIN_PATHS.CODE_INTERPRETER]: {
+    icon: SvgTerminal,
+    title: "Code Interpreter",
+    sidebarLabel: "Code Interpreter",
+  },
+  [ADMIN_PATHS.SEARCH_SETTINGS]: {
+    icon: SvgSearch,
+    title: "Search Settings",
+    sidebarLabel: "Search Settings",
+  },
+  [ADMIN_PATHS.DOCUMENT_PROCESSING]: {
+    icon: SvgFileText,
+    title: "Document Processing",
+    sidebarLabel: "Document Processing",
+  },
+  [ADMIN_PATHS.KNOWLEDGE_GRAPH]: {
+    icon: SvgNetworkGraph,
+    title: "Knowledge Graph",
+    sidebarLabel: "Knowledge Graph",
+  },
+  [ADMIN_PATHS.USERS]: {
+    icon: SvgUser,
+    title: "Manage Users",
+    sidebarLabel: "Users",
+  },
+  [ADMIN_PATHS.API_KEYS]: {
+    icon: SvgKey,
+    title: "API Keys",
+    sidebarLabel: "API Keys",
+  },
+  [ADMIN_PATHS.TOKEN_RATE_LIMITS]: {
+    icon: SvgShield,
+    title: "Token Rate Limits",
+    sidebarLabel: "Token Rate Limits",
+  },
+  [ADMIN_PATHS.USAGE]: {
+    icon: SvgActivity,
+    title: "Usage Statistics",
+    sidebarLabel: "Usage Statistics",
+  },
+  [ADMIN_PATHS.QUERY_HISTORY]: {
+    icon: SvgServer,
+    title: "Query History",
+    sidebarLabel: "Query History",
+  },
+  [ADMIN_PATHS.CUSTOM_ANALYTICS]: {
+    icon: SvgBarChart,
+    title: "Custom Analytics",
+    sidebarLabel: "Custom Analytics",
+  },
+  [ADMIN_PATHS.THEME]: {
+    icon: SvgPaintBrush,
+    title: "Appearance & Theming",
+    sidebarLabel: "Appearance & Theming",
+  },
+  [ADMIN_PATHS.BILLING]: {
+    icon: SvgWallet,
+    title: "Plans & Billing",
+    sidebarLabel: "Plans & Billing",
+  },
+  [ADMIN_PATHS.INDEX_MIGRATION]: {
+    icon: SvgArrowExchange,
+    title: "Document Index Migration",
+    sidebarLabel: "Document Index Migration",
+  },
+  [ADMIN_PATHS.DEBUG]: {
+    icon: SvgDownload,
+    title: "Debug Logs",
+    sidebarLabel: "Debug Logs",
+  },
+};
+
+/**
+ * Helper that converts a route config entry into the `{ name, icon, link }`
+ * shape expected by the sidebar. Extra fields (e.g. `error`) can be spread in.
+ */
+export function sidebarItem(path: string) {
+  const config = ADMIN_ROUTE_CONFIG[path]!;
+  return { name: config.sidebarLabel, icon: config.icon, link: path };
+}
diff --git a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
index a0a8ae8343f..75826bd23a4 100644
--- a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
+++ b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
@@ -18,13 +18,13 @@ import InputTextAreaField from "@/refresh-components/form/InputTextAreaField";
 import InputSelectField from "@/refresh-components/form/InputSelectField";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import {
-  SvgBubbleText,
   SvgAddLines,
   SvgActions,
   SvgExpand,
   SvgFold,
   SvgExternalLink,
 } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { Content } from "@opal/layouts";
 import { useSettingsContext } from "@/providers/SettingsProvider";
 import useCCPairs from "@/hooks/useCCPairs";
@@ -55,6 +55,8 @@ import useFilter from "@/hooks/useFilter";
 import { MCPServer } from "@/lib/tools/interfaces";
 import type { IconProps } from "@opal/types";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.CHAT_PREFERENCES]!;
+
 interface DefaultAgentConfiguration {
   tool_ids: number[];
   system_prompt: string | null;
@@ -323,8 +325,8 @@ function ChatPreferencesForm() {
     <>
       <SettingsLayouts.Root>
         <SettingsLayouts.Header
-          icon={SvgBubbleText}
-          title="Chat Preferences"
+          icon={route.icon}
+          title={route.title}
           description="Organization-wide chat settings and defaults. Users can override some of these in their personal settings."
           separator
         />
diff --git a/web/src/refresh-pages/admin/CodeInterpreterPage.tsx b/web/src/refresh-pages/admin/CodeInterpreterPage.tsx
index 30789147b90..f6875714795 100644
--- a/web/src/refresh-pages/admin/CodeInterpreterPage.tsx
+++ b/web/src/refresh-pages/admin/CodeInterpreterPage.tsx
@@ -11,6 +11,7 @@ import {
   SvgUnplug,
   SvgXOctagon,
 } from "@opal/icons";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { Section } from "@/layouts/general-layouts";
 import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
@@ -21,6 +22,8 @@ import { updateCodeInterpreter } from "@/lib/admin/code-interpreter/svc";
 import { ContentAction } from "@opal/layouts";
 import { toast } from "@/hooks/useToast";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.CODE_INTERPRETER]!;
+
 interface CodeInterpreterCardProps {
   variant?: CardProps["variant"];
   title: string;
@@ -161,8 +164,8 @@ export default function CodeInterpreterPage() {
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
-        icon={SvgTerminal}
-        title="Code Interpreter"
+        icon={route.icon}
+        title={route.title}
         description="Safe and sandboxed Python runtime available to your LLM. See docs for more details."
         separator
       />
diff --git a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
index d6a4521b659..5553c3927ea 100644
--- a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
+++ b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
@@ -11,8 +11,9 @@ import { ThreeDotsLoader } from "@/components/Loading";
 import { Content, ContentAction } from "@opal/layouts";
 import { Button } from "@opal/components";
 import { Hoverable } from "@opal/core";
-import { SvgCpu, SvgArrowExchange, SvgSettings, SvgTrash } from "@opal/icons";
+import { SvgArrowExchange, SvgSettings, SvgTrash } from "@opal/icons";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import * as GeneralLayouts from "@/layouts/general-layouts";
 import {
   getProviderDisplayName,
@@ -44,6 +45,8 @@ import { OpenRouterModal } from "@/sections/modals/llmConfig/OpenRouterModal";
 import { CustomModal } from "@/sections/modals/llmConfig/CustomModal";
 import { Section } from "@/layouts/general-layouts";
 
+const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.LLM_MODELS]!;
+
 // ============================================================================
 // Provider form mapping (keyed by provider name from the API)
 // ============================================================================
@@ -344,7 +347,7 @@ export default function LLMConfigurationPage() {
 
   return (
     <SettingsLayouts.Root>
-      <SettingsLayouts.Header icon={SvgCpu} title="LLM Models" separator />
+      <SettingsLayouts.Header icon={route.icon} title={route.title} separator />
 
       <SettingsLayouts.Body>
         {hasProviders ? (
diff --git a/web/src/sections/sidebar/AdminSidebar.tsx b/web/src/sections/sidebar/AdminSidebar.tsx
index e2764d27bce..eb797d931e3 100644
--- a/web/src/sections/sidebar/AdminSidebar.tsx
+++ b/web/src/sections/sidebar/AdminSidebar.tsx
@@ -16,119 +16,41 @@ import {
   hasActiveSubscription,
 } from "@/lib/billing";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
-import {
-  ClipboardIcon,
-  NotebookIconSkeleton,
-  SlackIconSkeleton,
-  BrainIcon,
-} from "@/components/icons/icons";
 import { CombinedSettings } from "@/interfaces/settings";
 import SidebarTab from "@/refresh-components/buttons/SidebarTab";
 import SidebarBody from "@/sections/sidebar/SidebarBody";
-import {
-  SvgActions,
-  SvgActivity,
-  SvgArrowUpCircle,
-  SvgBarChart,
-  SvgBubbleText,
-  SvgCpu,
-  SvgFileText,
-  SvgFolder,
-  SvgGlobe,
-  SvgArrowExchange,
-  SvgImage,
-  SvgKey,
-  SvgOnyxOctagon,
-  SvgSearch,
-  SvgServer,
-  SvgShield,
-  SvgThumbsUp,
-  SvgUploadCloud,
-  SvgUser,
-  SvgUsers,
-  SvgZoomIn,
-  SvgPaintBrush,
-  SvgDiscordMono,
-  SvgWallet,
-  SvgTerminal,
-} from "@opal/icons";
-import SvgMcp from "@opal/icons/mcp";
+import { SvgArrowUpCircle } from "@opal/icons";
+import { ADMIN_PATHS, sidebarItem } from "@/lib/admin-routes";
 import UserAvatarPopover from "@/sections/sidebar/UserAvatarPopover";
 
 const connectors_items = () => [
-  {
-    name: "Existing Connectors",
-    icon: NotebookIconSkeleton,
-    link: "/admin/indexing/status",
-  },
-  {
-    name: "Add Connector",
-    icon: SvgUploadCloud,
-    link: "/admin/add-connector",
-  },
+  sidebarItem(ADMIN_PATHS.INDEXING_STATUS),
+  sidebarItem(ADMIN_PATHS.ADD_CONNECTOR),
 ];
 
 const document_management_items = () => [
-  {
-    name: "Document Sets",
-    icon: SvgFolder,
-    link: "/admin/documents/sets",
-  },
-  {
-    name: "Explorer",
-    icon: SvgZoomIn,
-    link: "/admin/documents/explorer",
-  },
-  {
-    name: "Feedback",
-    icon: SvgThumbsUp,
-    link: "/admin/documents/feedback",
-  },
+  sidebarItem(ADMIN_PATHS.DOCUMENT_SETS),
+  sidebarItem(ADMIN_PATHS.DOCUMENT_EXPLORER),
+  sidebarItem(ADMIN_PATHS.DOCUMENT_FEEDBACK),
 ];
 
 const custom_agents_items = (isCurator: boolean, enableEnterprise: boolean) => {
-  const items = [
-    {
-      name: "Agents",
-      icon: SvgOnyxOctagon,
-      link: "/admin/agents",
-    },
-  ];
+  const items = [sidebarItem(ADMIN_PATHS.AGENTS)];
 
   if (!isCurator) {
     items.push(
-      {
-        name: "Slack Bots",
-        icon: SlackIconSkeleton,
-        link: "/admin/bots",
-      },
-      {
-        name: "Discord Bots",
-        icon: SvgDiscordMono,
-        link: "/admin/discord-bot",
-      }
+      sidebarItem(ADMIN_PATHS.SLACK_BOTS),
+      sidebarItem(ADMIN_PATHS.DISCORD_BOTS)
     );
   }
 
   items.push(
-    {
-      name: "MCP Actions",
-      icon: SvgMcp,
-      link: "/admin/actions/mcp",
-    },
-    {
-      name: "OpenAPI Actions",
-      icon: SvgActions,
-      link: "/admin/actions/open-api",
-    }
+    sidebarItem(ADMIN_PATHS.MCP_ACTIONS),
+    sidebarItem(ADMIN_PATHS.OPENAPI_ACTIONS)
   );
 
   if (enableEnterprise) {
-    items.push({
-      name: "Standard Answers",
-      icon: ClipboardIcon,
-      link: "/admin/standard-answer",
-    });
+    items.push(sidebarItem(ADMIN_PATHS.STANDARD_ANSWERS));
   }
 
   return items;
@@ -170,13 +92,7 @@ const collections = (
       ? [
           {
             name: "User Management",
-            items: [
-              {
-                name: "Groups",
-                icon: SvgUsers,
-                link: "/admin/groups",
-              },
-            ],
+            items: [sidebarItem(ADMIN_PATHS.GROUPS)],
           },
         ]
       : []),
@@ -185,84 +101,30 @@ const collections = (
           {
             name: "Configuration",
             items: [
-              {
-                name: "Chat Preferences",
-                icon: SvgBubbleText,
-                link: "/admin/configuration/chat-preferences",
-              },
-              {
-                name: "LLM Models",
-                icon: SvgCpu,
-                link: "/admin/configuration/llm",
-              },
-              {
-                name: "Web Search",
-                icon: SvgGlobe,
-                link: "/admin/configuration/web-search",
-              },
-              {
-                name: "Image Generation",
-                icon: SvgImage,
-                link: "/admin/configuration/image-generation",
-              },
-              {
-                name: "Code Interpreter",
-                icon: SvgTerminal,
-                link: "/admin/configuration/code-interpreter",
-              },
+              sidebarItem(ADMIN_PATHS.CHAT_PREFERENCES),
+              sidebarItem(ADMIN_PATHS.LLM_MODELS),
+              sidebarItem(ADMIN_PATHS.WEB_SEARCH),
+              sidebarItem(ADMIN_PATHS.IMAGE_GENERATION),
+              sidebarItem(ADMIN_PATHS.CODE_INTERPRETER),
               ...(!enableCloud && vectorDbEnabled
                 ? [
                     {
+                      ...sidebarItem(ADMIN_PATHS.SEARCH_SETTINGS),
                       error: settings?.settings.needs_reindexing,
-                      name: "Search Settings",
-                      icon: SvgSearch,
-                      link: "/admin/configuration/search",
-                    },
-                  ]
-                : []),
-              {
-                name: "Document Processing",
-                icon: SvgFileText,
-                link: "/admin/configuration/document-processing",
-              },
-              ...(kgExposed
-                ? [
-                    {
-                      name: "Knowledge Graph",
-                      icon: BrainIcon,
-                      link: "/admin/kg",
                     },
                   ]
                 : []),
+              sidebarItem(ADMIN_PATHS.DOCUMENT_PROCESSING),
+              ...(kgExposed ? [sidebarItem(ADMIN_PATHS.KNOWLEDGE_GRAPH)] : []),
             ],
           },
           {
             name: "User Management",
             items: [
-              {
-                name: "Users",
-                icon: SvgUser,
-                link: "/admin/users",
-              },
-              ...(enableEnterprise
-                ? [
-                    {
-                      name: "Groups",
-                      icon: SvgUsers,
-                      link: "/admin/groups",
-                    },
-                  ]
-                : []),
-              {
-                name: "API Keys",
-                icon: SvgKey,
-                link: "/admin/api-key",
-              },
-              {
-                name: "Token Rate Limits",
-                icon: SvgShield,
-                link: "/admin/token-rate-limits",
-              },
+              sidebarItem(ADMIN_PATHS.USERS),
+              ...(enableEnterprise ? [sidebarItem(ADMIN_PATHS.GROUPS)] : []),
+              sidebarItem(ADMIN_PATHS.API_KEYS),
+              sidebarItem(ADMIN_PATHS.TOKEN_RATE_LIMITS),
             ],
           },
           ...(enableEnterprise
@@ -270,28 +132,12 @@ const collections = (
                 {
                   name: "Performance",
                   items: [
-                    {
-                      name: "Usage Statistics",
-                      icon: SvgActivity,
-                      link: "/admin/performance/usage",
-                    },
+                    sidebarItem(ADMIN_PATHS.USAGE),
                     ...(settings?.settings.query_history_type !== "disabled"
-                      ? [
-                          {
-                            name: "Query History",
-                            icon: SvgServer,
-                            link: "/admin/performance/query-history",
-                          },
-                        ]
+                      ? [sidebarItem(ADMIN_PATHS.QUERY_HISTORY)]
                       : []),
                     ...(!enableCloud && customAnalyticsEnabled
-                      ? [
-                          {
-                            name: "Custom Analytics",
-                            icon: SvgBarChart,
-                            link: "/admin/performance/custom-analytics",
-                          },
-                        ]
+                      ? [sidebarItem(ADMIN_PATHS.CUSTOM_ANALYTICS)]
                       : []),
                   ],
                 },
@@ -300,29 +146,16 @@ const collections = (
           {
             name: "Settings",
             items: [
-              ...(enableEnterprise
-                ? [
-                    {
-                      name: "Appearance & Theming",
-                      icon: SvgPaintBrush,
-                      link: "/admin/theme",
-                    },
-                  ]
-                : []),
+              ...(enableEnterprise ? [sidebarItem(ADMIN_PATHS.THEME)] : []),
               // Always show billing/upgrade - community users need access to upgrade
               {
-                name: hasSubscription ? "Plans & Billing" : "Upgrade Plan",
-                icon: hasSubscription ? SvgWallet : SvgArrowUpCircle,
-                link: "/admin/billing",
+                ...sidebarItem(ADMIN_PATHS.BILLING),
+                ...(hasSubscription
+                  ? {}
+                  : { name: "Upgrade Plan", icon: SvgArrowUpCircle }),
               },
               ...(settings?.settings.opensearch_indexing_enabled
-                ? [
-                    {
-                      name: "Document Index Migration",
-                      icon: SvgArrowExchange,
-                      link: "/admin/document-index-migration",
-                    },
-                  ]
+                ? [sidebarItem(ADMIN_PATHS.INDEX_MIGRATION)]
                 : []),
             ],
           },

From 1de522f9ae435224858656cc25c942ef5d6fe561 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 3 Mar 2026 09:09:50 -0800
Subject: [PATCH 047/267] fix: sandbox rollback db on pod deletion failure
 (#8965)

---
 .../build/sandbox/kubernetes/kubernetes_sandbox_manager.py  | 6 ++++--
 backend/onyx/server/features/build/sandbox/tasks/tasks.py   | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py b/backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py
index c6a20290ff5..8fe3e9ef3bd 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py
@@ -1133,7 +1133,8 @@ def _cleanup_kubernetes_resources(
                 # Already deleted
                 service_deleted = True
             else:
-                logger.warning(f"Error deleting Service {service_name}: {e}")
+                logger.error(f"Error deleting Service {service_name}: {e}")
+                raise
 
         pod_deleted = False
         try:
@@ -1148,7 +1149,8 @@ def _cleanup_kubernetes_resources(
                 # Already deleted
                 pod_deleted = True
             else:
-                logger.warning(f"Error deleting Pod {pod_name}: {e}")
+                logger.error(f"Error deleting Pod {pod_name}: {e}")
+                raise
 
         # Wait for resources to be fully deleted to prevent 409 conflicts
         # on immediate re-provisioning
diff --git a/backend/onyx/server/features/build/sandbox/tasks/tasks.py b/backend/onyx/server/features/build/sandbox/tasks/tasks.py
index 1b335146486..b62fccacd9d 100644
--- a/backend/onyx/server/features/build/sandbox/tasks/tasks.py
+++ b/backend/onyx/server/features/build/sandbox/tasks/tasks.py
@@ -80,7 +80,7 @@ def cleanup_idle_sandboxes_task(self: Task, *, tenant_id: str) -> None:  # noqa:
 
     # Prevent overlapping runs of this task
     if not lock.acquire(blocking=False):
-        task_logger.debug("cleanup_idle_sandboxes_task - lock not acquired, skipping")
+        task_logger.info("cleanup_idle_sandboxes_task - lock not acquired, skipping")
         return
 
     try:

From 5fd0fe192b47cd9fe449ad4a85060dde861514db Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 3 Mar 2026 10:35:15 -0800
Subject: [PATCH 048/267] fix: Tokeniser does not rely on llm (#8967)

---
 backend/onyx/db/llm.py                            |  1 +
 backend/onyx/db/projects.py                       |  2 +-
 .../features/projects/projects_file_utils.py      | 15 +++++++++------
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/backend/onyx/db/llm.py b/backend/onyx/db/llm.py
index 3b6e239f40a..c3f7c279853 100644
--- a/backend/onyx/db/llm.py
+++ b/backend/onyx/db/llm.py
@@ -532,6 +532,7 @@ def fetch_default_model(
 ) -> ModelConfiguration | None:
     model_config = db_session.scalar(
         select(ModelConfiguration)
+        .options(selectinload(ModelConfiguration.llm_provider))
         .join(LLMModelFlow)
         .where(
             ModelConfiguration.is_visible == True,  # noqa: E712
diff --git a/backend/onyx/db/projects.py b/backend/onyx/db/projects.py
index 740ff77ac41..ce74a650c24 100644
--- a/backend/onyx/db/projects.py
+++ b/backend/onyx/db/projects.py
@@ -52,7 +52,7 @@ def create_user_files(
 ) -> CategorizedFilesResult:
 
     # Categorize the files
-    categorized_files = categorize_uploaded_files(files)
+    categorized_files = categorize_uploaded_files(files, db_session)
     # NOTE: At the moment, zip metadata is not used for user files.
     # Should revisit to decide whether this should be a feature.
     upload_response = upload_files(categorized_files.acceptable, FileOrigin.USER_FILE)
diff --git a/backend/onyx/server/features/projects/projects_file_utils.py b/backend/onyx/server/features/projects/projects_file_utils.py
index 9237348461d..5b882c76974 100644
--- a/backend/onyx/server/features/projects/projects_file_utils.py
+++ b/backend/onyx/server/features/projects/projects_file_utils.py
@@ -7,13 +7,14 @@
 from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import Field
+from sqlalchemy.orm import Session
 
 from onyx.configs.app_configs import FILE_TOKEN_COUNT_THRESHOLD
+from onyx.db.llm import fetch_default_llm_model
 from onyx.file_processing.extract_file_text import extract_file_text
 from onyx.file_processing.extract_file_text import get_file_ext
 from onyx.file_processing.file_types import OnyxFileExtensions
 from onyx.file_processing.password_validation import is_file_password_protected
-from onyx.llm.factory import get_default_llm
 from onyx.natural_language_processing.utils import get_tokenizer
 from onyx.utils.logger import setup_logger
 from shared_configs.configs import MULTI_TENANT
@@ -116,7 +117,9 @@ def estimate_image_tokens_for_upload(
             pass
 
 
-def categorize_uploaded_files(files: list[UploadFile]) -> CategorizedFiles:
+def categorize_uploaded_files(
+    files: list[UploadFile], db_session: Session
+) -> CategorizedFiles:
     """
     Categorize uploaded files based on text extractability and tokenized length.
 
@@ -128,11 +131,11 @@ def categorize_uploaded_files(files: list[UploadFile]) -> CategorizedFiles:
     """
 
     results = CategorizedFiles()
-    llm = get_default_llm()
+    default_model = fetch_default_llm_model(db_session)
 
-    tokenizer = get_tokenizer(
-        model_name=llm.config.model_name, provider_type=llm.config.model_provider
-    )
+    model_name = default_model.name if default_model else None
+    provider_type = default_model.llm_provider.provider if default_model else None
+    tokenizer = get_tokenizer(model_name=model_name, provider_type=provider_type)
 
     # Check if threshold checks should be skipped
     skip_threshold = False

From 1b32a7d94e743ce67131ed3d5eca092911503a23 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 3 Mar 2026 10:35:20 -0800
Subject: [PATCH 049/267] fix: Default code interpreter base url (#8969)

---
 backend/onyx/configs/app_configs.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 67e89b0eff0..cb3ad1cf84d 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -819,7 +819,9 @@ def get_current_tz_offset() -> int:
 # Tool Configs
 #####
 # Code Interpreter Service Configuration
-CODE_INTERPRETER_BASE_URL = os.environ.get("CODE_INTERPRETER_BASE_URL")
+CODE_INTERPRETER_BASE_URL = os.environ.get(
+    "CODE_INTERPRETER_BASE_URL", "http://localhost:8000"
+)
 
 CODE_INTERPRETER_DEFAULT_TIMEOUT_MS = int(
     os.environ.get("CODE_INTERPRETER_DEFAULT_TIMEOUT_MS") or 60_000

From 6532c942306783e4e6a9f7c75cce452f163f2458 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Tue, 3 Mar 2026 11:58:05 -0800
Subject: [PATCH 050/267] chore: Add greptile.json configuration file (#8978)

---
 greptile.json | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 greptile.json

diff --git a/greptile.json b/greptile.json
new file mode 100644
index 00000000000..4b1fb81ea5c
--- /dev/null
+++ b/greptile.json
@@ -0,0 +1,72 @@
+{
+    "labels": [],
+    "comment": "",
+    "fixWithAI": true,
+    "hideFooter": false,
+    "strictness": 2,
+    "statusCheck": true,
+    "commentTypes": [
+      "logic",
+      "syntax",
+      "style"
+    ],
+    "instructions": "",
+    "disabledLabels": [],
+    "excludeAuthors": [
+      "dependabot[bot]",
+      "renovate[bot]"
+    ],
+    "ignoreKeywords": "",
+    "ignorePatterns": "greptile.json\n",
+    "includeAuthors": [],
+    "summarySection": {
+      "included": true,
+      "collapsible": false,
+      "defaultOpen": false
+    },
+    "excludeBranches": [],
+    "fileChangeLimit": 300,
+    "includeBranches": [],
+    "includeKeywords": "",
+    "triggerOnUpdates": true,
+    "updateExistingSummaryComment": true,
+    "updateSummaryOnly": false,
+    "issuesTableSection": {
+      "included": true,
+      "collapsible": false,
+      "defaultOpen": false
+    },
+    "statusCommentsEnabled": true,
+    "confidenceScoreSection": {
+      "included": true,
+      "collapsible": false
+    },
+    "sequenceDiagramSection": {
+      "included": true,
+      "collapsible": false,
+      "defaultOpen": false
+    },
+    "shouldUpdateDescription": false,
+    "customContext": {
+      "other": [
+        {
+          "scope": [],
+          "content": ""
+        }
+      ],
+      "rules": [
+        {
+          "scope": [],
+          "rule": ""
+        }
+      ],
+      "files": [
+        {
+          "scope": [],
+          "path": "",
+          "description": ""
+        }
+      ]
+    }
+  }
+  

From 03553114c5028288090061c335b0d2598a19c10e Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 3 Mar 2026 12:08:57 -0800
Subject: [PATCH 051/267] fix(ollama): debounce API url input and properly
 handle model fetch request with abort signal (#8986)

---
 web/src/app/admin/configuration/llm/utils.ts  |  1 +
 web/src/interfaces/llm.ts                     |  1 +
 .../sections/modals/llmConfig/OllamaModal.tsx | 41 ++++++++++++++-----
 3 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/web/src/app/admin/configuration/llm/utils.ts b/web/src/app/admin/configuration/llm/utils.ts
index d612a2f14ab..9b61dd48e99 100644
--- a/web/src/app/admin/configuration/llm/utils.ts
+++ b/web/src/app/admin/configuration/llm/utils.ts
@@ -187,6 +187,7 @@ export const fetchOllamaModels = async (
         api_base: apiBase,
         provider_name: params.provider_name,
       }),
+      signal: params.signal,
     });
 
     if (!response.ok) {
diff --git a/web/src/interfaces/llm.ts b/web/src/interfaces/llm.ts
index 91c25a597a2..5d01c4bb886 100644
--- a/web/src/interfaces/llm.ts
+++ b/web/src/interfaces/llm.ts
@@ -118,6 +118,7 @@ export interface BedrockFetchParams {
 export interface OllamaFetchParams {
   api_base?: string;
   provider_name?: string;
+  signal?: AbortSignal;
 }
 
 export interface OpenRouterFetchParams {
diff --git a/web/src/sections/modals/llmConfig/OllamaModal.tsx b/web/src/sections/modals/llmConfig/OllamaModal.tsx
index b8fbbc0f9ff..69d3c69c3e6 100644
--- a/web/src/sections/modals/llmConfig/OllamaModal.tsx
+++ b/web/src/sections/modals/llmConfig/OllamaModal.tsx
@@ -23,8 +23,9 @@ import {
 } from "./formUtils";
 import { AdvancedOptions } from "./components/AdvancedOptions";
 import { DisplayModels } from "./components/DisplayModels";
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { fetchOllamaModels } from "@/app/admin/configuration/llm/utils";
+import debounce from "lodash/debounce";
 
 export const OLLAMA_PROVIDER_NAME = "ollama_chat";
 const DEFAULT_API_BASE = "http://127.0.0.1:11434";
@@ -61,14 +62,16 @@ function OllamaModalContent({
 }: OllamaModalContentProps) {
   const [isLoadingModels, setIsLoadingModels] = useState(true);
 
-  useEffect(() => {
-    if (formikProps.values.api_base) {
+  const fetchModels = useCallback(
+    (apiBase: string, signal: AbortSignal) => {
       setIsLoadingModels(true);
       fetchOllamaModels({
-        api_base: formikProps.values.api_base,
+        api_base: apiBase,
         provider_name: existingLlmProvider?.name,
+        signal,
       })
         .then((data) => {
+          if (signal.aborted) return;
           if (data.error) {
             console.error("Error fetching models:", data.error);
             setFetchedModels([]);
@@ -77,14 +80,32 @@ function OllamaModalContent({
           setFetchedModels(data.models);
         })
         .finally(() => {
-          setIsLoadingModels(false);
+          if (!signal.aborted) {
+            setIsLoadingModels(false);
+          }
         });
+    },
+    [existingLlmProvider?.name, setFetchedModels]
+  );
+
+  const debouncedFetchModels = useMemo(
+    () => debounce(fetchModels, 500),
+    [fetchModels]
+  );
+
+  useEffect(() => {
+    if (formikProps.values.api_base) {
+      const controller = new AbortController();
+      debouncedFetchModels(formikProps.values.api_base, controller.signal);
+      return () => {
+        debouncedFetchModels.cancel();
+        controller.abort();
+      };
+    } else {
+      setIsLoadingModels(false);
+      setFetchedModels([]);
     }
-  }, [
-    formikProps.values.api_base,
-    existingLlmProvider?.name,
-    setFetchedModels,
-  ]);
+  }, [formikProps.values.api_base, debouncedFetchModels, setFetchedModels]);
 
   const currentModels =
     fetchedModels.length > 0

From c98aa486e48958960f63e8d477801c4fb3a641ad Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Tue, 3 Mar 2026 12:46:40 -0800
Subject: [PATCH 052/267] refactor(fe): migrate onboarding components to
 Content/ContentAction (#8983)

---
 .../onboarding/components/NonAdminStep.tsx    | 95 ++++++++++---------
 .../onboarding/steps/LLMStep.tsx              | 30 +++---
 .../onboarding/steps/NameStep.tsx             | 38 ++++----
 3 files changed, 82 insertions(+), 81 deletions(-)

diff --git a/web/src/refresh-components/onboarding/components/NonAdminStep.tsx b/web/src/refresh-components/onboarding/components/NonAdminStep.tsx
index 0ab7c4d3e6b..c7b79f07b30 100644
--- a/web/src/refresh-components/onboarding/components/NonAdminStep.tsx
+++ b/web/src/refresh-components/onboarding/components/NonAdminStep.tsx
@@ -9,6 +9,7 @@ import { Button as OpalButton } from "@opal/components";
 import InputAvatar from "@/refresh-components/inputs/InputAvatar";
 import { cn } from "@/lib/utils";
 import { SvgCheckCircle, SvgEdit, SvgUser, SvgX } from "@opal/icons";
+import { ContentAction } from "@opal/layouts";
 
 export default function NonAdminStep() {
   const inputRef = useRef<HTMLInputElement>(null);
@@ -54,17 +55,26 @@ export default function NonAdminStep() {
           className="flex items-center justify-between w-full min-h-11 py-1 pl-3 pr-2 bg-background-tint-00 rounded-16 shadow-01 mb-2"
           aria-label="non-admin-confirmation"
         >
-          <div className="flex items-center gap-1">
-            <SvgCheckCircle className="w-4 h-4 stroke-status-success-05" />
-            <Text as="p" text03 mainUiBody>
-              You're all set!
-            </Text>
-          </div>
-          <OpalButton
-            prominence="tertiary"
-            size="sm"
-            icon={SvgX}
-            onClick={handleDismissConfirmation}
+          <ContentAction
+            icon={({ className, ...props }) => (
+              <SvgCheckCircle
+                className={cn(className, "stroke-status-success-05")}
+                {...props}
+              />
+            )}
+            title="You're all set!"
+            sizePreset="main-ui"
+            variant="body"
+            prominence="muted"
+            paddingVariant="fit"
+            rightChildren={
+              <OpalButton
+                prominence="tertiary"
+                size="sm"
+                icon={SvgX}
+                onClick={handleDismissConfirmation}
+              />
+            }
           />
         </div>
       )}
@@ -75,39 +85,36 @@ export default function NonAdminStep() {
           role="group"
           aria-label="non-admin-name-prompt"
         >
-          <div className="flex items-center gap-1 h-full">
-            <div className="h-full p-0.5">
-              <SvgUser className="w-4 h-4 stroke-text-03" />
-            </div>
-            <div>
-              <Text as="p" text04 mainUiAction>
-                What should Onyx call you?
-              </Text>
-              <Text as="p" text03 secondaryBody>
-                We will display this name in the app.
-              </Text>
-            </div>
-          </div>
-          <div className="flex items-center justify-end gap-2">
-            <InputTypeIn
-              ref={inputRef}
-              placeholder="Your name"
-              value={name || ""}
-              onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
-                setName(e.target.value)
-              }
-              onKeyDown={(e) => {
-                if (e.key === "Enter" && name && name.trim().length > 0) {
-                  e.preventDefault();
-                  handleSave();
-                }
-              }}
-              className="w-[26%] min-w-40"
-            />
-            <Button disabled={name === ""} onClick={handleSave}>
-              Save
-            </Button>
-          </div>
+          <ContentAction
+            icon={SvgUser}
+            title="What should Onyx call you?"
+            description="We will display this name in the app."
+            sizePreset="main-ui"
+            variant="section"
+            paddingVariant="fit"
+            rightChildren={
+              <div className="flex items-center justify-end gap-2">
+                <InputTypeIn
+                  ref={inputRef}
+                  placeholder="Your name"
+                  value={name || ""}
+                  onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
+                    setName(e.target.value)
+                  }
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter" && name && name.trim().length > 0) {
+                      e.preventDefault();
+                      handleSave();
+                    }
+                  }}
+                  className="w-[26%] min-w-40"
+                />
+                <Button disabled={name === ""} onClick={handleSave}>
+                  Save
+                </Button>
+              </div>
+            }
+          />
         </div>
       ) : (
         <div
diff --git a/web/src/refresh-components/onboarding/steps/LLMStep.tsx b/web/src/refresh-components/onboarding/steps/LLMStep.tsx
index 604615e0808..7c7c029ed0a 100644
--- a/web/src/refresh-components/onboarding/steps/LLMStep.tsx
+++ b/web/src/refresh-components/onboarding/steps/LLMStep.tsx
@@ -1,3 +1,5 @@
+"use client";
+
 import { memo, useState, useCallback } from "react";
 import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
@@ -12,6 +14,7 @@ import {
 import { Disabled } from "@/refresh-components/Disabled";
 import { ProviderIcon } from "@/app/admin/configuration/llm/ProviderIcon";
 import { SvgCheckCircle, SvgCpu, SvgExternalLink } from "@opal/icons";
+import { ContentAction } from "@opal/layouts";
 
 type LLMStepProps = {
   state: OnboardingState;
@@ -122,21 +125,14 @@ const LLMStepInner = ({
           className="flex flex-col items-center justify-between w-full p-1 rounded-16 border border-border-01 bg-background-tint-00"
           aria-label="onboarding-llm-step"
         >
-          <div className="flex gap-2 justify-between h-full w-full">
-            <div className="flex mx-2 mt-2 gap-1">
-              <div className="h-full p-0.5">
-                <SvgCpu className="w-4 h-4 stroke-text-03" />
-              </div>
-              <div>
-                <Text as="p" text04 mainUiAction>
-                  Connect your LLM models
-                </Text>
-                <Text as="p" text03 secondaryBody>
-                  Onyx supports both self-hosted models and popular providers.
-                </Text>
-              </div>
-            </div>
-            <div className="p-0.5">
+          <ContentAction
+            icon={SvgCpu}
+            title="Connect your LLM models"
+            description="Onyx supports both self-hosted models and popular providers."
+            sizePreset="main-ui"
+            variant="section"
+            paddingVariant="lg"
+            rightChildren={
               <Button
                 tertiary
                 rightIcon={SvgExternalLink}
@@ -145,8 +141,8 @@ const LLMStepInner = ({
               >
                 View in Admin Panel
               </Button>
-            </div>
-          </div>
+            }
+          />
           <Separator />
           <div className="flex flex-wrap gap-1 [&>*:last-child:nth-child(odd)]:basis-full">
             {isLoading ? (
diff --git a/web/src/refresh-components/onboarding/steps/NameStep.tsx b/web/src/refresh-components/onboarding/steps/NameStep.tsx
index 040b1f69542..2c4d1e332c4 100644
--- a/web/src/refresh-components/onboarding/steps/NameStep.tsx
+++ b/web/src/refresh-components/onboarding/steps/NameStep.tsx
@@ -8,6 +8,7 @@ import InputAvatar from "@/refresh-components/inputs/InputAvatar";
 import { cn } from "@/lib/utils";
 import IconButton from "@/refresh-components/buttons/IconButton";
 import { SvgCheckCircle, SvgEdit, SvgUser } from "@opal/icons";
+import { ContentAction } from "@opal/layouts";
 
 export interface NameStepProps {
   state: OnboardingState;
@@ -40,26 +41,23 @@ const NameStep = React.memo(
         role="group"
         aria-label="onboarding-name-step"
       >
-        <div className="flex items-center gap-1 h-full">
-          <div className="h-full p-0.5">
-            <SvgUser className="w-4 h-4 stroke-text-03" />
-          </div>
-          <div>
-            <Text as="p" text04 mainUiAction>
-              What should Onyx call you?
-            </Text>
-            <Text as="p" text03 secondaryBody>
-              We will display this name in the app.
-            </Text>
-          </div>
-        </div>
-        <InputTypeIn
-          ref={inputRef}
-          placeholder="Your name"
-          value={userName || ""}
-          onChange={(e) => updateName(e.target.value)}
-          onKeyDown={handleKeyDown}
-          className="max-w-60"
+        <ContentAction
+          icon={SvgUser}
+          title="What should Onyx call you?"
+          description="We will display this name in the app."
+          sizePreset="main-ui"
+          variant="section"
+          paddingVariant="fit"
+          rightChildren={
+            <InputTypeIn
+              ref={inputRef}
+              placeholder="Your name"
+              value={userName || ""}
+              onChange={(e) => updateName(e.target.value)}
+              onKeyDown={handleKeyDown}
+              className="max-w-60"
+            />
+          }
         />
       </div>
     ) : (

From 69c8aa08b31fcdbb28e699139ca01a61ebf28a33 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Tue, 3 Mar 2026 12:49:12 -0800
Subject: [PATCH 053/267] fix(ci): Add secrets inheritance to nightly LLM
 provider chat workflow (#8984)

---
 .github/workflows/nightly-llm-provider-chat.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/nightly-llm-provider-chat.yml b/.github/workflows/nightly-llm-provider-chat.yml
index ff5914eb8e8..15fc1f83a7b 100644
--- a/.github/workflows/nightly-llm-provider-chat.yml
+++ b/.github/workflows/nightly-llm-provider-chat.yml
@@ -15,6 +15,7 @@ permissions:
 jobs:
   provider-chat-test:
     uses: ./.github/workflows/reusable-nightly-llm-provider-chat.yml
+    secrets: inherit
     permissions:
       contents: read
       id-token: write

From f9027272151c5f3395db6a6748223ca95ab73643 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 3 Mar 2026 13:10:35 -0800
Subject: [PATCH 054/267] chore(devtools): `npm run test:diff` on changed files
 (#8991)

---
 web/package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/web/package.json b/web/package.json
index 7bc60de3221..4173006ad5d 100644
--- a/web/package.json
+++ b/web/package.json
@@ -23,6 +23,7 @@
     "test:verbose": "jest --verbose",
     "test:ci": "jest --ci --maxWorkers=2 --silent --bail",
     "test:changed": "jest --onlyChanged",
+    "test:diff": "jest --changedSince=main",
     "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand"
   },
   "dependencies": {

From 328c305d268f2cf91e61293aada76f9b0ae59ef7 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 3 Mar 2026 13:06:28 -0800
Subject: [PATCH 055/267] chore: remove dead code from admin theming (#8979)

---
 web/src/app/ee/admin/theme/ImageUpload.tsx | 76 ----------------------
 1 file changed, 76 deletions(-)
 delete mode 100644 web/src/app/ee/admin/theme/ImageUpload.tsx

diff --git a/web/src/app/ee/admin/theme/ImageUpload.tsx b/web/src/app/ee/admin/theme/ImageUpload.tsx
deleted file mode 100644
index 86fb964f69c..00000000000
--- a/web/src/app/ee/admin/theme/ImageUpload.tsx
+++ /dev/null
@@ -1,76 +0,0 @@
-import { SubLabel } from "@/components/Field";
-import { toast } from "@/hooks/useToast";
-import { useEffect, useState } from "react";
-import Dropzone from "react-dropzone";
-
-export function ImageUpload({
-  selectedFile,
-  setSelectedFile,
-}: {
-  selectedFile: File | null;
-  setSelectedFile: (file: File) => void;
-}) {
-  const [tmpImageUrl, setTmpImageUrl] = useState<string>("");
-
-  useEffect(() => {
-    if (selectedFile) {
-      setTmpImageUrl(URL.createObjectURL(selectedFile));
-    } else {
-      setTmpImageUrl("");
-    }
-  }, [selectedFile]);
-
-  const [dragActive, setDragActive] = useState(false);
-
-  return (
-    <Dropzone
-      onDrop={(acceptedFiles) => {
-        if (acceptedFiles.length !== 1) {
-          toast.error("Only one file can be uploaded at a time");
-          return;
-        }
-
-        const acceptedFile = acceptedFiles[0];
-        if (acceptedFile === undefined) {
-          toast.error("acceptedFile cannot be undefined");
-          return;
-        }
-
-        setTmpImageUrl(URL.createObjectURL(acceptedFile));
-        setSelectedFile(acceptedFile);
-        setDragActive(false);
-      }}
-      onDragLeave={() => setDragActive(false)}
-      onDragEnter={() => setDragActive(true)}
-    >
-      {({ getRootProps, getInputProps }) => (
-        <section>
-          <div
-            {...getRootProps()}
-            className={
-              "flex flex-col items-center w-full px-4 py-12 rounded " +
-              "shadow-lg tracking-wide border border-border cursor-pointer" +
-              (dragActive ? " border-accent" : "")
-            }
-          >
-            <input {...getInputProps()} />
-            <b className="text-text-darker">
-              Drag and drop a .png or .jpg file, or click to select a file!
-            </b>
-          </div>
-
-          {tmpImageUrl && (
-            <div className="mt-4 mb-8">
-              <SubLabel>Uploaded Image:</SubLabel>
-              <img
-                alt="Uploaded Image"
-                src={tmpImageUrl}
-                className="mt-4 max-w-xs max-h-64"
-              />
-            </div>
-          )}
-        </section>
-      )}
-    </Dropzone>
-  );
-}

From 4fded5b0a1a76b7f80548e4ee7b4b3960cecae48 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 3 Mar 2026 13:11:07 -0800
Subject: [PATCH 056/267] chore: remove dead code from expandable content
 component (#8981)

---
 web/src/components/tools/CSVContent.tsx       |  4 +---
 .../tools/ExpandableContentWrapper.tsx        | 21 +------------------
 2 files changed, 2 insertions(+), 23 deletions(-)

diff --git a/web/src/components/tools/CSVContent.tsx b/web/src/components/tools/CSVContent.tsx
index 6d94f53411f..1982327b8a9 100644
--- a/web/src/components/tools/CSVContent.tsx
+++ b/web/src/components/tools/CSVContent.tsx
@@ -16,8 +16,6 @@ import { cn } from "@/lib/utils";
 
 const CsvContent: React.FC<ContentComponentProps> = ({
   fileDescriptor,
-  isLoading,
-  fadeIn,
   expanded = false,
 }) => {
   const [data, setData] = useState<Record<string, string>[]>([]);
@@ -94,7 +92,7 @@ const CsvContent: React.FC<ContentComponentProps> = ({
     }
   };
 
-  if (isLoading || isFetching) {
+  if (isFetching) {
     return (
       <div className="flex items-center justify-center h-[300px]">
         <SimpleLoader />
diff --git a/web/src/components/tools/ExpandableContentWrapper.tsx b/web/src/components/tools/ExpandableContentWrapper.tsx
index 2e06fd0b53a..d7c1896502f 100644
--- a/web/src/components/tools/ExpandableContentWrapper.tsx
+++ b/web/src/components/tools/ExpandableContentWrapper.tsx
@@ -1,5 +1,5 @@
 // ExpandableContentWrapper
-import React, { useState, useEffect } from "react";
+import React, { useState } from "react";
 import { SvgDownloadCloud, SvgFold, SvgMaximize2, SvgX } from "@opal/icons";
 import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
 import { Button } from "@opal/components";
@@ -17,8 +17,6 @@ export interface ExpandableContentWrapperProps {
 
 export interface ContentComponentProps {
   fileDescriptor: FileDescriptor;
-  isLoading: boolean;
-  fadeIn: boolean;
   expanded?: boolean;
 }
 
@@ -28,24 +26,9 @@ export default function ExpandableContentWrapper({
   ContentComponent,
 }: ExpandableContentWrapperProps) {
   const [expanded, setExpanded] = useState(false);
-  const [isLoading, setIsLoading] = useState(true);
-  const [fadeIn, setFadeIn] = useState(false);
 
   const toggleExpand = () => setExpanded((prev) => !prev);
 
-  // Prevent a jarring fade in
-  useEffect(() => {
-    setTimeout(() => setIsLoading(false), 300);
-  }, []);
-
-  useEffect(() => {
-    if (!isLoading) {
-      setTimeout(() => setFadeIn(true), 50);
-    } else {
-      setFadeIn(false);
-    }
-  }, [isLoading]);
-
   const downloadFile = () => {
     const a = document.createElement("a");
     a.href = `api/chat/file/${fileDescriptor.id}`;
@@ -103,8 +86,6 @@ export default function ExpandableContentWrapper({
           {!expanded && (
             <ContentComponent
               fileDescriptor={fileDescriptor}
-              isLoading={isLoading}
-              fadeIn={fadeIn}
               expanded={expanded}
             />
           )}

From 98e3602dd6632953449b42e5bae8ea1c4c50106b Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 3 Mar 2026 13:18:30 -0800
Subject: [PATCH 057/267] fix: google connectors redirect to connector page
 instead of auth error (#8989)

---
 .../[connector]/ConnectorWrapper.tsx          |  8 ++++++
 .../[connector]/auth/callback/route.ts        | 27 +++++++------------
 .../[connector]/oauth/callback/page.tsx       |  3 +--
 .../[connector]/pages/gdrive/Credential.tsx   | 11 +-------
 .../[connector]/pages/gmail/Credential.tsx    |  8 +-----
 web/src/lib/constants.ts                      |  5 ----
 6 files changed, 21 insertions(+), 41 deletions(-)

diff --git a/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx b/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx
index 3253f318624..a0b2d3f7aa5 100644
--- a/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx
+++ b/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx
@@ -20,6 +20,7 @@ import { buildSimilarCredentialInfoURL } from "@/app/admin/connector/[ccPairId]/
 import { Credential } from "@/lib/connectors/credentials";
 import { useFederatedConnectors } from "@/lib/hooks";
 import Text from "@/refresh-components/texts/Text";
+import { useToastFromQuery } from "@/hooks/useToast";
 
 export default function ConnectorWrapper({
   connector,
@@ -29,6 +30,13 @@ export default function ConnectorWrapper({
   const searchParams = useSearchParams();
   const mode = searchParams?.get("mode"); // 'federated' or 'regular'
 
+  useToastFromQuery({
+    oauth_failed: {
+      message: "OAuth authentication failed. Please try again.",
+      type: "error",
+    },
+  });
+
   // Check if the connector is valid
   if (!isValidSource(connector)) {
     return (
diff --git a/web/src/app/admin/connectors/[connector]/auth/callback/route.ts b/web/src/app/admin/connectors/[connector]/auth/callback/route.ts
index 59d533b7497..c0f32dc14fd 100644
--- a/web/src/app/admin/connectors/[connector]/auth/callback/route.ts
+++ b/web/src/app/admin/connectors/[connector]/auth/callback/route.ts
@@ -2,10 +2,6 @@ import { getDomain } from "@/lib/redirectSS";
 import { buildUrl } from "@/lib/utilsSS";
 import { NextRequest, NextResponse } from "next/server";
 import { cookies } from "next/headers";
-import {
-  GMAIL_AUTH_IS_ADMIN_COOKIE_NAME,
-  GOOGLE_DRIVE_AUTH_IS_ADMIN_COOKIE_NAME,
-} from "@/lib/constants";
 import {
   CRAFT_OAUTH_COOKIE_NAME,
   CRAFT_CONFIGURE_PATH,
@@ -15,6 +11,7 @@ import { processCookies } from "@/lib/userSS";
 export const GET = async (request: NextRequest) => {
   const requestCookies = await cookies();
   const connector = request.url.includes("gmail") ? "gmail" : "google-drive";
+
   const callbackEndpoint = `/manage/connector/${connector}/callback`;
   const url = new URL(buildUrl(callbackEndpoint));
   url.search = request.nextUrl.search;
@@ -26,7 +23,12 @@ export const GET = async (request: NextRequest) => {
   });
 
   if (!response.ok) {
-    return NextResponse.redirect(new URL("/auth/error", getDomain(request)));
+    return NextResponse.redirect(
+      new URL(
+        `/admin/connectors/${connector}?message=oauth_failed`,
+        getDomain(request)
+      )
+    );
   }
 
   // Check for build mode OAuth flag (redirects to build admin panel)
@@ -40,16 +42,7 @@ export const GET = async (request: NextRequest) => {
     return redirectResponse;
   }
 
-  const authCookieName =
-    connector === "gmail"
-      ? GMAIL_AUTH_IS_ADMIN_COOKIE_NAME
-      : GOOGLE_DRIVE_AUTH_IS_ADMIN_COOKIE_NAME;
-
-  if (requestCookies.get(authCookieName)?.value?.toLowerCase() === "true") {
-    return NextResponse.redirect(
-      new URL(`/admin/connectors/${connector}`, getDomain(request))
-    );
-  }
-
-  return NextResponse.redirect(new URL("/user/connectors", getDomain(request)));
+  return NextResponse.redirect(
+    new URL(`/admin/connectors/${connector}`, getDomain(request))
+  );
 };
diff --git a/web/src/app/admin/connectors/[connector]/oauth/callback/page.tsx b/web/src/app/admin/connectors/[connector]/oauth/callback/page.tsx
index 7fe3ff63a4b..e8b489c7a5a 100644
--- a/web/src/app/admin/connectors/[connector]/oauth/callback/page.tsx
+++ b/web/src/app/admin/connectors/[connector]/oauth/callback/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useState } from "react";
-import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { usePathname, useSearchParams } from "next/navigation";
 import { AdminPageTitle } from "@/components/admin/Title";
 import { getSourceMetadata, isValidSource } from "@/lib/sources";
 import { ValidSources } from "@/lib/types";
@@ -9,7 +9,6 @@ import CardSection from "@/components/admin/CardSection";
 import { handleOAuthAuthorizationResponse } from "@/lib/oauth_utils";
 import { SvgKey } from "@opal/icons";
 export default function OAuthCallbackPage() {
-  const router = useRouter();
   const searchParams = useSearchParams();
 
   const [statusMessage, setStatusMessage] = useState("Processing...");
diff --git a/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx b/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
index 9e65226b0d7..2e208808470 100644
--- a/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
@@ -6,11 +6,7 @@ import { useRouter } from "next/navigation";
 import type { Route } from "next";
 import { adminDeleteCredential } from "@/lib/credential";
 import { setupGoogleDriveOAuth } from "@/lib/googleDrive";
-import {
-  DOCS_ADMINS_PATH,
-  GOOGLE_DRIVE_AUTH_IS_ADMIN_COOKIE_NAME,
-} from "@/lib/constants";
-import Cookies from "js-cookie";
+import { DOCS_ADMINS_PATH } from "@/lib/constants";
 import { TextFormField, SectionHeader } from "@/components/Field";
 import { Form, Formik } from "formik";
 import { User } from "@/lib/types";
@@ -592,11 +588,6 @@ export const DriveAuthSection = ({
           onClick={async () => {
             setIsAuthenticating(true);
             try {
-              // cookie used by callback to determine where to finally redirect to
-              Cookies.set(GOOGLE_DRIVE_AUTH_IS_ADMIN_COOKIE_NAME, "true", {
-                path: "/",
-              });
-
               const [authUrl, errorMsg] = await setupGoogleDriveOAuth({
                 isAdmin: true,
                 name: "OAuth (uploaded)",
diff --git a/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx b/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
index 3a8e43285e5..f4f7111a641 100644
--- a/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
@@ -7,10 +7,7 @@ import { useRouter } from "next/navigation";
 import type { Route } from "next";
 import { adminDeleteCredential } from "@/lib/credential";
 import { setupGmailOAuth } from "@/lib/gmail";
-import {
-  DOCS_ADMINS_PATH,
-  GMAIL_AUTH_IS_ADMIN_COOKIE_NAME,
-} from "@/lib/constants";
+import { DOCS_ADMINS_PATH } from "@/lib/constants";
 import { CRAFT_OAUTH_COOKIE_NAME } from "@/app/craft/v1/constants";
 import Cookies from "js-cookie";
 import { TextFormField, SectionHeader } from "@/components/Field";
@@ -602,9 +599,6 @@ export const GmailAuthSection = ({
           onClick={async () => {
             setIsAuthenticating(true);
             try {
-              Cookies.set(GMAIL_AUTH_IS_ADMIN_COOKIE_NAME, "true", {
-                path: "/",
-              });
               if (buildMode) {
                 Cookies.set(CRAFT_OAUTH_COOKIE_NAME, "true", {
                   path: "/",
diff --git a/web/src/lib/constants.ts b/web/src/lib/constants.ts
index eed061a0af5..9a447868d44 100644
--- a/web/src/lib/constants.ts
+++ b/web/src/lib/constants.ts
@@ -28,11 +28,6 @@ export const NEXT_PUBLIC_DO_NOT_USE_TOGGLE_OFF_DANSWER_POWERED =
 
 export const TENANT_ID_COOKIE_NAME = "onyx_tid";
 
-export const GMAIL_AUTH_IS_ADMIN_COOKIE_NAME = "gmail_auth_is_admin";
-
-export const GOOGLE_DRIVE_AUTH_IS_ADMIN_COOKIE_NAME =
-  "google_drive_auth_is_admin";
-
 export const SEARCH_TYPE_COOKIE_NAME = "search_type";
 export const AGENTIC_SEARCH_TYPE_COOKIE_NAME = "agentic_type";
 

From 3e67ea9df77dd38febe069e0fd50f8c1bd359492 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 3 Mar 2026 13:22:37 -0800
Subject: [PATCH 058/267] feat: Code Interpreter responsive in actions dropdown
 (#8982)

---
 .../python/code_interpreter_client.py         |  20 ++-
 .../python/python_tool.py                     |   6 +-
 .../tools/test_python_tool.py                 |  15 ++
 .../tools/test_python_tool_availability.py    | 168 +++++++++++++++---
 .../popovers/ActionsPopover/index.tsx         |   4 +
 5 files changed, 183 insertions(+), 30 deletions(-)

diff --git a/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py b/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
index e2de2e4b4d3..1f21c273c69 100644
--- a/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
+++ b/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
@@ -1,4 +1,5 @@
 import json
+import time
 from collections.abc import Generator
 from typing import Literal
 from typing import TypedDict
@@ -12,6 +13,9 @@
 
 logger = setup_logger()
 
+_HEALTH_CACHE_TTL_SECONDS = 30
+_health_cache: dict[str, tuple[float, bool]] = {}
+
 
 class FileInput(TypedDict):
     """Input file to be staged in execution workspace"""
@@ -98,16 +102,26 @@ def _build_payload(
             payload["files"] = files
         return payload
 
-    def health(self) -> bool:
+    def health(self, use_cache: bool = False) -> bool:
         """Check if the Code Interpreter service is healthy"""
+        if use_cache:
+            cached = _health_cache.get(self.base_url)
+            if cached is not None:
+                cached_at, cached_result = cached
+                if time.monotonic() - cached_at < _HEALTH_CACHE_TTL_SECONDS:
+                    return cached_result
+
         url = f"{self.base_url}/health"
         try:
             response = self.session.get(url, timeout=5)
             response.raise_for_status()
-            return response.json().get("status") == "ok"
+            result = response.json().get("status") == "ok"
         except Exception as e:
             logger.warning(f"Exception caught when checking health, e={e}")
-            return False
+            result = False
+
+        _health_cache[self.base_url] = (time.monotonic(), result)
+        return result
 
     def execute(
         self,
diff --git a/backend/onyx/tools/tool_implementations/python/python_tool.py b/backend/onyx/tools/tool_implementations/python/python_tool.py
index 5f0fafb5624..bfeda2255cc 100644
--- a/backend/onyx/tools/tool_implementations/python/python_tool.py
+++ b/backend/onyx/tools/tool_implementations/python/python_tool.py
@@ -107,7 +107,11 @@ def is_available(cls, db_session: Session) -> bool:
         if not CODE_INTERPRETER_BASE_URL:
             return False
         server = fetch_code_interpreter_server(db_session)
-        return server.server_enabled
+        if not server.server_enabled:
+            return False
+
+        client = CodeInterpreterClient()
+        return client.health(use_cache=True)
 
     def tool_definition(self) -> dict:
         return {
diff --git a/backend/tests/external_dependency_unit/tools/test_python_tool.py b/backend/tests/external_dependency_unit/tools/test_python_tool.py
index d96b4cdbfea..35119a7469f 100644
--- a/backend/tests/external_dependency_unit/tools/test_python_tool.py
+++ b/backend/tests/external_dependency_unit/tools/test_python_tool.py
@@ -1027,6 +1027,13 @@ def do_POST(self) -> None:
         else:
             self._respond_json(404, {"error": "not found"})
 
+    def do_GET(self) -> None:
+        self._capture("GET", b"")
+        if self.path == "/health":
+            self._respond_json(200, {"status": "ok"})
+        else:
+            self._respond_json(404, {"error": "not found"})
+
     def do_DELETE(self) -> None:
         self._capture("DELETE", b"")
         self.send_response(200)
@@ -1107,6 +1114,14 @@ def mock_ci_server() -> Generator[MockCodeInterpreterServer, None, None]:
     server.shutdown()
 
 
+@pytest.fixture(autouse=True)
+def _clear_health_cache() -> None:
+    """Reset the health check cache before every test."""
+    import onyx.tools.tool_implementations.python.code_interpreter_client as mod
+
+    mod._health_cache = {}
+
+
 @pytest.fixture()
 def _attach_python_tool_to_default_persona(db_session: Session) -> None:
     """Ensure the default persona (id=0) has the PythonTool attached."""
diff --git a/backend/tests/unit/onyx/tools/test_python_tool_availability.py b/backend/tests/unit/onyx/tools/test_python_tool_availability.py
index a1b371bede2..a5a6531412c 100644
--- a/backend/tests/unit/onyx/tools/test_python_tool_availability.py
+++ b/backend/tests/unit/onyx/tools/test_python_tool_availability.py
@@ -1,25 +1,37 @@
-"""Tests for PythonTool availability based on server_enabled flag.
+"""Tests for PythonTool availability based on server_enabled flag and health check.
 
 Verifies that PythonTool reports itself as unavailable when either:
 - CODE_INTERPRETER_BASE_URL is not set, or
-- CodeInterpreterServer.server_enabled is False in the database.
+- CodeInterpreterServer.server_enabled is False in the database, or
+- The Code Interpreter service health check fails.
+
+Also verifies that the health check result is cached with a TTL.
 """
 
 from unittest.mock import MagicMock
 from unittest.mock import patch
 
+import pytest
 from sqlalchemy.orm import Session
 
+TOOL_MODULE = "onyx.tools.tool_implementations.python.python_tool"
+CLIENT_MODULE = "onyx.tools.tool_implementations.python.code_interpreter_client"
+
+
+@pytest.fixture(autouse=True)
+def _clear_health_cache() -> None:
+    """Reset the health check cache before every test."""
+    import onyx.tools.tool_implementations.python.code_interpreter_client as mod
+
+    mod._health_cache = {}
+
 
 # ------------------------------------------------------------------
 # Unavailable when CODE_INTERPRETER_BASE_URL is not set
 # ------------------------------------------------------------------
 
 
-@patch(
-    "onyx.tools.tool_implementations.python.python_tool.CODE_INTERPRETER_BASE_URL",
-    None,
-)
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", None)
 def test_python_tool_unavailable_without_base_url() -> None:
     from onyx.tools.tool_implementations.python.python_tool import PythonTool
 
@@ -27,10 +39,7 @@ def test_python_tool_unavailable_without_base_url() -> None:
     assert PythonTool.is_available(db_session) is False
 
 
-@patch(
-    "onyx.tools.tool_implementations.python.python_tool.CODE_INTERPRETER_BASE_URL",
-    "",
-)
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "")
 def test_python_tool_unavailable_with_empty_base_url() -> None:
     from onyx.tools.tool_implementations.python.python_tool import PythonTool
 
@@ -43,13 +52,8 @@ def test_python_tool_unavailable_with_empty_base_url() -> None:
 # ------------------------------------------------------------------
 
 
-@patch(
-    "onyx.tools.tool_implementations.python.python_tool.CODE_INTERPRETER_BASE_URL",
-    "http://localhost:8000",
-)
-@patch(
-    "onyx.tools.tool_implementations.python.python_tool.fetch_code_interpreter_server",
-)
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://localhost:8000")
+@patch(f"{TOOL_MODULE}.fetch_code_interpreter_server")
 def test_python_tool_unavailable_when_server_disabled(
     mock_fetch: MagicMock,
 ) -> None:
@@ -64,18 +68,15 @@ def test_python_tool_unavailable_when_server_disabled(
 
 
 # ------------------------------------------------------------------
-# Available when both conditions are met
+# Health check determines availability when URL + server are OK
 # ------------------------------------------------------------------
 
 
-@patch(
-    "onyx.tools.tool_implementations.python.python_tool.CODE_INTERPRETER_BASE_URL",
-    "http://localhost:8000",
-)
-@patch(
-    "onyx.tools.tool_implementations.python.python_tool.fetch_code_interpreter_server",
-)
-def test_python_tool_available_when_server_enabled(
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://localhost:8000")
+@patch(f"{TOOL_MODULE}.fetch_code_interpreter_server")
+@patch(f"{TOOL_MODULE}.CodeInterpreterClient")
+def test_python_tool_available_when_health_check_passes(
+    mock_client_cls: MagicMock,
     mock_fetch: MagicMock,
 ) -> None:
     from onyx.tools.tool_implementations.python.python_tool import PythonTool
@@ -84,5 +85,120 @@ def test_python_tool_available_when_server_enabled(
     mock_server.server_enabled = True
     mock_fetch.return_value = mock_server
 
+    mock_client = MagicMock()
+    mock_client.health.return_value = True
+    mock_client_cls.return_value = mock_client
+
     db_session = MagicMock(spec=Session)
     assert PythonTool.is_available(db_session) is True
+    mock_client.health.assert_called_once_with(use_cache=True)
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://localhost:8000")
+@patch(f"{TOOL_MODULE}.fetch_code_interpreter_server")
+@patch(f"{TOOL_MODULE}.CodeInterpreterClient")
+def test_python_tool_unavailable_when_health_check_fails(
+    mock_client_cls: MagicMock,
+    mock_fetch: MagicMock,
+) -> None:
+    from onyx.tools.tool_implementations.python.python_tool import PythonTool
+
+    mock_server = MagicMock()
+    mock_server.server_enabled = True
+    mock_fetch.return_value = mock_server
+
+    mock_client = MagicMock()
+    mock_client.health.return_value = False
+    mock_client_cls.return_value = mock_client
+
+    db_session = MagicMock(spec=Session)
+    assert PythonTool.is_available(db_session) is False
+    mock_client.health.assert_called_once_with(use_cache=True)
+
+
+# ------------------------------------------------------------------
+# Health check is NOT reached when preconditions fail
+# ------------------------------------------------------------------
+
+
+@patch(f"{TOOL_MODULE}.CODE_INTERPRETER_BASE_URL", "http://localhost:8000")
+@patch(f"{TOOL_MODULE}.fetch_code_interpreter_server")
+@patch(f"{TOOL_MODULE}.CodeInterpreterClient")
+def test_health_check_not_called_when_server_disabled(
+    mock_client_cls: MagicMock,
+    mock_fetch: MagicMock,
+) -> None:
+    from onyx.tools.tool_implementations.python.python_tool import PythonTool
+
+    mock_server = MagicMock()
+    mock_server.server_enabled = False
+    mock_fetch.return_value = mock_server
+
+    db_session = MagicMock(spec=Session)
+    assert PythonTool.is_available(db_session) is False
+    mock_client_cls.assert_not_called()
+
+
+# ------------------------------------------------------------------
+# Health check caching (tested at the client level)
+# ------------------------------------------------------------------
+
+
+def test_health_check_cached_on_second_call() -> None:
+    from onyx.tools.tool_implementations.python.code_interpreter_client import (
+        CodeInterpreterClient,
+    )
+
+    client = CodeInterpreterClient(base_url="http://fake:9000")
+    mock_response = MagicMock()
+    mock_response.json.return_value = {"status": "ok"}
+
+    with patch.object(client.session, "get", return_value=mock_response) as mock_get:
+        assert client.health(use_cache=True) is True
+        assert client.health(use_cache=True) is True
+        # Only one HTTP call — the second used the cache
+        mock_get.assert_called_once()
+
+
+@patch(f"{CLIENT_MODULE}.time")
+def test_health_check_refreshed_after_ttl_expires(mock_time: MagicMock) -> None:
+    from onyx.tools.tool_implementations.python.code_interpreter_client import (
+        CodeInterpreterClient,
+        _HEALTH_CACHE_TTL_SECONDS,
+    )
+
+    client = CodeInterpreterClient(base_url="http://fake:9000")
+    mock_response = MagicMock()
+    mock_response.json.return_value = {"status": "ok"}
+
+    with patch.object(client.session, "get", return_value=mock_response) as mock_get:
+        # First call at t=0 — cache miss
+        mock_time.monotonic.return_value = 0.0
+        assert client.health(use_cache=True) is True
+        assert mock_get.call_count == 1
+
+        # Second call within TTL — cache hit
+        mock_time.monotonic.return_value = float(_HEALTH_CACHE_TTL_SECONDS - 1)
+        assert client.health(use_cache=True) is True
+        assert mock_get.call_count == 1
+
+        # Third call after TTL — cache miss, fresh request
+        mock_time.monotonic.return_value = float(_HEALTH_CACHE_TTL_SECONDS + 1)
+        assert client.health(use_cache=True) is True
+        assert mock_get.call_count == 2
+
+
+def test_health_check_no_cache_by_default() -> None:
+    from onyx.tools.tool_implementations.python.code_interpreter_client import (
+        CodeInterpreterClient,
+    )
+
+    client = CodeInterpreterClient(base_url="http://fake:9000")
+    mock_response = MagicMock()
+    mock_response.json.return_value = {"status": "ok"}
+
+    with patch.object(client.session, "get", return_value=mock_response) as mock_get:
+        assert client.health() is True
+        assert client.health() is True
+        # Both calls hit the network when use_cache=False (default)
+        assert mock_get.call_count == 2
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index dad2dc53417..f1f4118e0a6 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -72,6 +72,10 @@ const ADMIN_CONFIG_LINKS: Record<string, { href: string; tooltip: string }> = {
     href: "/admin/configuration/web-search",
     tooltip: "Configure Web Search",
   },
+  [PYTHON_TOOL_ID]: {
+    href: "/admin/configuration/code-interpreter",
+    tooltip: "Configure Code Interpreter",
+  },
   KnowledgeGraphTool: {
     href: "/admin/kg",
     tooltip: "Configure Knowledge Graph",

From 2b1f1fe3114c2caa5a0153dc9742882044c383d6 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 3 Mar 2026 13:46:17 -0800
Subject: [PATCH 059/267] chore: use abort controller to properly manage oauth
 requests (#8994)

---
 web/src/components/oauth/OAuthCallbackPage.tsx | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/web/src/components/oauth/OAuthCallbackPage.tsx b/web/src/components/oauth/OAuthCallbackPage.tsx
index 95496264021..159d9e7af63 100644
--- a/web/src/components/oauth/OAuthCallbackPage.tsx
+++ b/web/src/components/oauth/OAuthCallbackPage.tsx
@@ -86,6 +86,8 @@ export default function OAuthCallbackPage({ config }: OAuthCallbackPageProps) {
   ]);
 
   useEffect(() => {
+    const controller = new AbortController();
+
     const handleOAuthCallback = async () => {
       // Handle OAuth error from provider
       if (error) {
@@ -122,6 +124,7 @@ export default function OAuthCallbackPage({ config }: OAuthCallbackPageProps) {
             "Content-Type": "application/json",
           },
           credentials: "include",
+          signal: controller.signal,
         });
 
         if (!response.ok) {
@@ -181,6 +184,7 @@ export default function OAuthCallbackPage({ config }: OAuthCallbackPageProps) {
         setIsError(false);
         setIsLoading(false);
       } catch (error) {
+        if (controller.signal.aborted) return;
         console.error("OAuth callback error:", error);
         setStatusMessage(config.errorMessage || "Something Went Wrong");
         setStatusDetails(
@@ -194,6 +198,7 @@ export default function OAuthCallbackPage({ config }: OAuthCallbackPageProps) {
     };
 
     handleOAuthCallback();
+    return () => controller.abort();
   }, [code, state, error, errorDescription, searchParams, config]);
 
   const getStatusIcon = () => {

From 49b509a0a741f976e5acc0a38777f5f80f2869a1 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Tue, 3 Mar 2026 14:13:11 -0800
Subject: [PATCH 060/267] fix(permissions): Add file connector access control
 for global curators (#8990)

---
 backend/onyx/server/documents/connector.py    |  62 ++++-
 .../test_file_connector_permissions.py        | 234 ++++++++++++++++++
 .../app/admin/connector/[ccPairId]/page.tsx   |  26 +-
 3 files changed, 305 insertions(+), 17 deletions(-)
 create mode 100644 backend/tests/integration/tests/permissions/test_file_connector_permissions.py

diff --git a/backend/onyx/server/documents/connector.py b/backend/onyx/server/documents/connector.py
index 20fb2a07a41..41d6f68fb82 100644
--- a/backend/onyx/server/documents/connector.py
+++ b/backend/onyx/server/documents/connector.py
@@ -92,6 +92,7 @@
 from onyx.db.connector_credential_pair import (
     get_connector_credential_pairs_for_user_parallel,
 )
+from onyx.db.connector_credential_pair import verify_user_has_access_to_cc_pair
 from onyx.db.credentials import cleanup_gmail_credentials
 from onyx.db.credentials import cleanup_google_drive_credentials
 from onyx.db.credentials import create_credential
@@ -572,6 +573,43 @@ def _normalize_file_names_for_backwards_compatibility(
     return file_names + file_locations[len(file_names) :]
 
 
+def _fetch_and_check_file_connector_cc_pair_permissions(
+    connector_id: int,
+    user: User,
+    db_session: Session,
+    require_editable: bool,
+) -> ConnectorCredentialPair:
+    cc_pair = fetch_connector_credential_pair_for_connector(db_session, connector_id)
+    if cc_pair is None:
+        raise HTTPException(
+            status_code=404,
+            detail="No Connector-Credential Pair found for this connector",
+        )
+
+    has_requested_access = verify_user_has_access_to_cc_pair(
+        cc_pair_id=cc_pair.id,
+        db_session=db_session,
+        user=user,
+        get_editable=require_editable,
+    )
+    if has_requested_access:
+        return cc_pair
+
+    # Special case: global curators should be able to manage files
+    # for public file connectors even when they are not the creator.
+    if (
+        require_editable
+        and user.role == UserRole.GLOBAL_CURATOR
+        and cc_pair.access_type == AccessType.PUBLIC
+    ):
+        return cc_pair
+
+    raise HTTPException(
+        status_code=403,
+        detail="Access denied. User cannot manage files for this connector.",
+    )
+
+
 @router.post("/admin/connector/file/upload", tags=PUBLIC_API_TAGS)
 def upload_files_api(
     files: list[UploadFile],
@@ -583,7 +621,7 @@ def upload_files_api(
 @router.get("/admin/connector/{connector_id}/files", tags=PUBLIC_API_TAGS)
 def list_connector_files(
     connector_id: int,
-    user: User = Depends(current_curator_or_admin_user),  # noqa: ARG001
+    user: User = Depends(current_curator_or_admin_user),
     db_session: Session = Depends(get_session),
 ) -> ConnectorFilesResponse:
     """List all files in a file connector."""
@@ -596,6 +634,13 @@ def list_connector_files(
             status_code=400, detail="This endpoint only works with file connectors"
         )
 
+    _ = _fetch_and_check_file_connector_cc_pair_permissions(
+        connector_id=connector_id,
+        user=user,
+        db_session=db_session,
+        require_editable=False,
+    )
+
     file_locations = connector.connector_specific_config.get("file_locations", [])
     file_names = connector.connector_specific_config.get("file_names", [])
 
@@ -645,7 +690,7 @@ def update_connector_files(
     connector_id: int,
     files: list[UploadFile] | None = File(None),
     file_ids_to_remove: str = Form("[]"),
-    user: User = Depends(current_curator_or_admin_user),  # noqa: ARG001
+    user: User = Depends(current_curator_or_admin_user),
     db_session: Session = Depends(get_session),
 ) -> FileUploadResponse:
     """
@@ -663,12 +708,13 @@ def update_connector_files(
         )
 
     # Get the connector-credential pair for indexing/pruning triggers
-    cc_pair = fetch_connector_credential_pair_for_connector(db_session, connector_id)
-    if cc_pair is None:
-        raise HTTPException(
-            status_code=404,
-            detail="No Connector-Credential Pair found for this connector",
-        )
+    # and validate user permissions for file management.
+    cc_pair = _fetch_and_check_file_connector_cc_pair_permissions(
+        connector_id=connector_id,
+        user=user,
+        db_session=db_session,
+        require_editable=True,
+    )
 
     # Parse file IDs to remove
     try:
diff --git a/backend/tests/integration/tests/permissions/test_file_connector_permissions.py b/backend/tests/integration/tests/permissions/test_file_connector_permissions.py
new file mode 100644
index 00000000000..2b582e636ce
--- /dev/null
+++ b/backend/tests/integration/tests/permissions/test_file_connector_permissions.py
@@ -0,0 +1,234 @@
+import io
+import json
+import os
+
+import pytest
+import requests
+
+from onyx.db.enums import AccessType
+from onyx.db.models import UserRole
+from onyx.server.documents.models import DocumentSource
+from tests.integration.common_utils.constants import API_SERVER_URL
+from tests.integration.common_utils.managers.cc_pair import CCPairManager
+from tests.integration.common_utils.managers.connector import ConnectorManager
+from tests.integration.common_utils.managers.credential import CredentialManager
+from tests.integration.common_utils.managers.user import DATestUser
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.managers.user_group import UserGroupManager
+
+
+def _upload_connector_file(
+    *,
+    user_performing_action: DATestUser,
+    file_name: str,
+    content: bytes,
+) -> tuple[str, str]:
+    headers = user_performing_action.headers.copy()
+    headers.pop("Content-Type", None)
+
+    response = requests.post(
+        f"{API_SERVER_URL}/manage/admin/connector/file/upload",
+        files=[("files", (file_name, io.BytesIO(content), "text/plain"))],
+        headers=headers,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    return payload["file_paths"][0], payload["file_names"][0]
+
+
+def _update_connector_files(
+    *,
+    connector_id: int,
+    user_performing_action: DATestUser,
+    file_ids_to_remove: list[str],
+    new_file_name: str,
+    new_file_content: bytes,
+) -> requests.Response:
+    headers = user_performing_action.headers.copy()
+    headers.pop("Content-Type", None)
+
+    return requests.post(
+        f"{API_SERVER_URL}/manage/admin/connector/{connector_id}/files/update",
+        data={"file_ids_to_remove": json.dumps(file_ids_to_remove)},
+        files=[("files", (new_file_name, io.BytesIO(new_file_content), "text/plain"))],
+        headers=headers,
+    )
+
+
+def _list_connector_files(
+    *,
+    connector_id: int,
+    user_performing_action: DATestUser,
+) -> requests.Response:
+    return requests.get(
+        f"{API_SERVER_URL}/manage/admin/connector/{connector_id}/files",
+        headers=user_performing_action.headers,
+    )
+
+
+@pytest.mark.skipif(
+    os.environ.get("ENABLE_PAID_ENTERPRISE_EDITION_FEATURES", "").lower() != "true",
+    reason="Curator and user group tests are enterprise only",
+)
+@pytest.mark.usefixtures("reset")
+def test_only_global_curator_can_update_public_file_connector_files() -> None:
+    admin_user = UserManager.create(name="admin_user")
+
+    global_curator_creator = UserManager.create(name="global_curator_creator")
+    global_curator_creator = UserManager.set_role(
+        user_to_set=global_curator_creator,
+        target_role=UserRole.GLOBAL_CURATOR,
+        user_performing_action=admin_user,
+    )
+
+    global_curator_editor = UserManager.create(name="global_curator_editor")
+    global_curator_editor = UserManager.set_role(
+        user_to_set=global_curator_editor,
+        target_role=UserRole.GLOBAL_CURATOR,
+        user_performing_action=admin_user,
+    )
+
+    curator_user = UserManager.create(name="curator_user")
+    curator_group = UserGroupManager.create(
+        name="curator_group",
+        user_ids=[curator_user.id],
+        cc_pair_ids=[],
+        user_performing_action=admin_user,
+    )
+    UserGroupManager.wait_for_sync(
+        user_groups_to_check=[curator_group],
+        user_performing_action=admin_user,
+    )
+    UserGroupManager.set_curator_status(
+        test_user_group=curator_group,
+        user_to_set_as_curator=curator_user,
+        user_performing_action=admin_user,
+    )
+
+    initial_file_id, initial_file_name = _upload_connector_file(
+        user_performing_action=global_curator_creator,
+        file_name="initial-file.txt",
+        content=b"initial file content",
+    )
+
+    connector = ConnectorManager.create(
+        user_performing_action=global_curator_creator,
+        name="public_file_connector",
+        source=DocumentSource.FILE,
+        connector_specific_config={
+            "file_locations": [initial_file_id],
+            "file_names": [initial_file_name],
+            "zip_metadata_file_id": None,
+        },
+        access_type=AccessType.PUBLIC,
+        groups=[],
+    )
+    credential = CredentialManager.create(
+        user_performing_action=global_curator_creator,
+        source=DocumentSource.FILE,
+        curator_public=True,
+        groups=[],
+        name="public_file_connector_credential",
+    )
+    CCPairManager.create(
+        connector_id=connector.id,
+        credential_id=credential.id,
+        user_performing_action=global_curator_creator,
+        access_type=AccessType.PUBLIC,
+        groups=[],
+        name="public_file_connector_cc_pair",
+    )
+
+    curator_list_response = _list_connector_files(
+        connector_id=connector.id,
+        user_performing_action=curator_user,
+    )
+    curator_list_response.raise_for_status()
+    curator_list_payload = curator_list_response.json()
+    assert any(f["file_id"] == initial_file_id for f in curator_list_payload["files"])
+
+    global_curator_list_response = _list_connector_files(
+        connector_id=connector.id,
+        user_performing_action=global_curator_editor,
+    )
+    global_curator_list_response.raise_for_status()
+    global_curator_list_payload = global_curator_list_response.json()
+    assert any(
+        f["file_id"] == initial_file_id for f in global_curator_list_payload["files"]
+    )
+
+    denied_response = _update_connector_files(
+        connector_id=connector.id,
+        user_performing_action=curator_user,
+        file_ids_to_remove=[initial_file_id],
+        new_file_name="curator-file.txt",
+        new_file_content=b"curator updated file",
+    )
+    assert denied_response.status_code == 403
+
+    allowed_response = _update_connector_files(
+        connector_id=connector.id,
+        user_performing_action=global_curator_editor,
+        file_ids_to_remove=[initial_file_id],
+        new_file_name="global-curator-file.txt",
+        new_file_content=b"global curator updated file",
+    )
+    allowed_response.raise_for_status()
+
+    payload = allowed_response.json()
+    assert initial_file_id not in payload["file_paths"]
+    assert "global-curator-file.txt" in payload["file_names"]
+
+    creator_group = UserGroupManager.create(
+        name="creator_group",
+        user_ids=[global_curator_creator.id],
+        cc_pair_ids=[],
+        user_performing_action=admin_user,
+    )
+    UserGroupManager.wait_for_sync(
+        user_groups_to_check=[creator_group],
+        user_performing_action=admin_user,
+    )
+
+    private_file_id, private_file_name = _upload_connector_file(
+        user_performing_action=global_curator_creator,
+        file_name="private-initial-file.txt",
+        content=b"private initial file content",
+    )
+
+    private_connector = ConnectorManager.create(
+        user_performing_action=global_curator_creator,
+        name="private_file_connector",
+        source=DocumentSource.FILE,
+        connector_specific_config={
+            "file_locations": [private_file_id],
+            "file_names": [private_file_name],
+            "zip_metadata_file_id": None,
+        },
+        access_type=AccessType.PRIVATE,
+        groups=[creator_group.id],
+    )
+    private_credential = CredentialManager.create(
+        user_performing_action=global_curator_creator,
+        source=DocumentSource.FILE,
+        curator_public=False,
+        groups=[creator_group.id],
+        name="private_file_connector_credential",
+    )
+    CCPairManager.create(
+        connector_id=private_connector.id,
+        credential_id=private_credential.id,
+        user_performing_action=global_curator_creator,
+        access_type=AccessType.PRIVATE,
+        groups=[creator_group.id],
+        name="private_file_connector_cc_pair",
+    )
+
+    private_denied_response = _update_connector_files(
+        connector_id=private_connector.id,
+        user_performing_action=global_curator_editor,
+        file_ids_to_remove=[private_file_id],
+        new_file_name="global-curator-private-file.txt",
+        new_file_content=b"global curator private update",
+    )
+    assert private_denied_response.status_code == 403
diff --git a/web/src/app/admin/connector/[ccPairId]/page.tsx b/web/src/app/admin/connector/[ccPairId]/page.tsx
index 0aba3590141..b40ee6e1470 100644
--- a/web/src/app/admin/connector/[ccPairId]/page.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/page.tsx
@@ -64,6 +64,8 @@ import { useStatusChange } from "./useStatusChange";
 import { useReIndexModal } from "./ReIndexModal";
 import Button from "@/refresh-components/buttons/Button";
 import { SvgSettings } from "@opal/icons";
+import { UserRole } from "@/lib/types";
+import { useUser } from "@/providers/UserProvider";
 // synchronize these validations with the SQLAlchemy connector class until we have a
 // centralized schema for both frontend and backend
 const RefreshFrequencySchema = Yup.object().shape({
@@ -89,6 +91,7 @@ const PAGES_PER_BATCH = 8;
 
 function Main({ ccPairId }: { ccPairId: number }) {
   const router = useRouter();
+  const { user } = useUser();
 
   const {
     data: ccPair,
@@ -176,6 +179,12 @@ function Main({ ccPairId }: { ccPairId: number }) {
   }, [ccPair, refresh]);
 
   const latestIndexAttempt = indexAttempts?.[0];
+  const canManageInlineFileConnectorFiles =
+    ccPair?.connector.source === "file" &&
+    (ccPair.is_editable_for_current_user ||
+      (user?.role === UserRole.GLOBAL_CURATOR &&
+        ccPair.access_type === "public"));
+
   const isResolvingErrors =
     (latestIndexAttempt?.status === "in_progress" ||
       latestIndexAttempt?.status === "not_started") &&
@@ -691,15 +700,14 @@ function Main({ ccPairId }: { ccPairId: number }) {
               />
 
               {/* Inline file management for file connectors */}
-              {ccPair.connector.source === "file" &&
-                ccPair.is_editable_for_current_user && (
-                  <div className="mt-6">
-                    <InlineFileManagement
-                      connectorId={ccPair.connector.id}
-                      onRefresh={refresh}
-                    />
-                  </div>
-                )}
+              {canManageInlineFileConnectorFiles && (
+                <div className="mt-6">
+                  <InlineFileManagement
+                    connectorId={ccPair.connector.id}
+                    onRefresh={refresh}
+                  />
+                </div>
+              )}
             </Card>
           </>
         )}

From c63fdf1c13a27b0515c779130e7073151936a80b Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Tue, 3 Mar 2026 14:40:50 -0800
Subject: [PATCH 061/267] fix(opensearch): Increase the Vespa http client
 timeout to 120s for the OpenSearch migration (#8966)

---
 .../celery/tasks/opensearch_migration/tasks.py       | 10 +++++++++-
 backend/onyx/configs/app_configs.py                  |  3 +++
 backend/onyx/document_index/vespa/chunk_retrieval.py | 12 ++++++++++--
 .../onyx/document_index/vespa/shared_utils/utils.py  |  6 ++++--
 4 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/backend/onyx/background/celery/tasks/opensearch_migration/tasks.py b/backend/onyx/background/celery/tasks/opensearch_migration/tasks.py
index 503af958b97..79807a1aca7 100644
--- a/backend/onyx/background/celery/tasks/opensearch_migration/tasks.py
+++ b/backend/onyx/background/celery/tasks/opensearch_migration/tasks.py
@@ -30,6 +30,7 @@
     transform_vespa_chunks_to_opensearch_chunks,
 )
 from onyx.configs.app_configs import ENABLE_OPENSEARCH_INDEXING_FOR_ONYX
+from onyx.configs.app_configs import VESPA_MIGRATION_REQUEST_TIMEOUT_S
 from onyx.configs.constants import OnyxCeleryTask
 from onyx.configs.constants import OnyxRedisLocks
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
@@ -47,6 +48,7 @@
 from onyx.document_index.opensearch.opensearch_document_index import (
     OpenSearchDocumentIndex,
 )
+from onyx.document_index.vespa.shared_utils.utils import get_vespa_http_client
 from onyx.document_index.vespa.vespa_document_index import VespaDocumentIndex
 from onyx.indexing.models import IndexingSetting
 from onyx.redis.redis_pool import get_redis_client
@@ -146,7 +148,12 @@ def migrate_chunks_from_vespa_to_opensearch_task(
             task_logger.error(err_str)
             return False
 
-        with get_session_with_current_tenant() as db_session:
+        with (
+            get_session_with_current_tenant() as db_session,
+            get_vespa_http_client(
+                timeout=VESPA_MIGRATION_REQUEST_TIMEOUT_S
+            ) as vespa_client,
+        ):
             try_insert_opensearch_tenant_migration_record_with_commit(db_session)
             search_settings = get_current_search_settings(db_session)
             tenant_state = TenantState(tenant_id=tenant_id, multitenant=MULTI_TENANT)
@@ -161,6 +168,7 @@ def migrate_chunks_from_vespa_to_opensearch_task(
                 index_name=search_settings.index_name,
                 tenant_state=tenant_state,
                 large_chunks_enabled=False,
+                httpx_client=vespa_client,
             )
 
             sanitized_doc_start_time = time.monotonic()
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index cb3ad1cf84d..46ef7afdb2b 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -902,6 +902,9 @@ def get_current_tz_offset() -> int:
 )
 
 VESPA_REQUEST_TIMEOUT = int(os.environ.get("VESPA_REQUEST_TIMEOUT") or "15")
+VESPA_MIGRATION_REQUEST_TIMEOUT_S = int(
+    os.environ.get("VESPA_MIGRATION_REQUEST_TIMEOUT_S") or "120"
+)
 
 SYSTEM_RECURSION_LIMIT = int(os.environ.get("SYSTEM_RECURSION_LIMIT") or "1000")
 
diff --git a/backend/onyx/document_index/vespa/chunk_retrieval.py b/backend/onyx/document_index/vespa/chunk_retrieval.py
index 49124995b4e..dd3258fab65 100644
--- a/backend/onyx/document_index/vespa/chunk_retrieval.py
+++ b/backend/onyx/document_index/vespa/chunk_retrieval.py
@@ -1,5 +1,6 @@
 import json
 import string
+import time
 from collections.abc import Callable
 from collections.abc import Mapping
 from datetime import datetime
@@ -18,6 +19,7 @@
 )
 from onyx.configs.app_configs import LOG_VESPA_TIMING_INFORMATION
 from onyx.configs.app_configs import VESPA_LANGUAGE_OVERRIDE
+from onyx.configs.app_configs import VESPA_MIGRATION_REQUEST_TIMEOUT_S
 from onyx.context.search.models import IndexFilters
 from onyx.context.search.models import InferenceChunkUncleaned
 from onyx.document_index.interfaces import VespaChunkRequest
@@ -338,12 +340,18 @@ def _get_all_chunks_paginated_for_slice(
             params["continuation"] = continuation_token
 
         response: httpx.Response | None = None
+        start_time = time.monotonic()
         try:
-            with get_vespa_http_client() as http_client:
+            with get_vespa_http_client(
+                timeout=VESPA_MIGRATION_REQUEST_TIMEOUT_S
+            ) as http_client:
                 response = http_client.get(url, params=params)
                 response.raise_for_status()
         except httpx.HTTPError as e:
-            error_base = f"Failed to get chunks from Vespa slice {slice_id} with continuation token {continuation_token}."
+            error_base = (
+                f"Failed to get chunks from Vespa slice {slice_id} with continuation token "
+                f"{continuation_token} in {time.monotonic() - start_time:.3f} seconds."
+            )
             logger.exception(
                 f"Request URL: {e.request.url}\n"
                 f"Request Headers: {e.request.headers}\n"
diff --git a/backend/onyx/document_index/vespa/shared_utils/utils.py b/backend/onyx/document_index/vespa/shared_utils/utils.py
index 74e185cdef4..c52eefa9bd2 100644
--- a/backend/onyx/document_index/vespa/shared_utils/utils.py
+++ b/backend/onyx/document_index/vespa/shared_utils/utils.py
@@ -52,7 +52,9 @@ def replace_invalid_doc_id_characters(text: str) -> str:
     return text.replace("'", "_")
 
 
-def get_vespa_http_client(no_timeout: bool = False, http2: bool = True) -> httpx.Client:
+def get_vespa_http_client(
+    no_timeout: bool = False, http2: bool = True, timeout: int | None = None
+) -> httpx.Client:
     """
     Configures and returns an HTTP client for communicating with Vespa,
     including authentication if needed.
@@ -64,7 +66,7 @@ def get_vespa_http_client(no_timeout: bool = False, http2: bool = True) -> httpx
             else None
         ),
         verify=False if not MANAGED_VESPA else True,
-        timeout=None if no_timeout else VESPA_REQUEST_TIMEOUT,
+        timeout=None if no_timeout else (timeout or VESPA_REQUEST_TIMEOUT),
         http2=http2,
     )
 

From 98e63461526c84affc420c5706fb4a9bf609d29c Mon Sep 17 00:00:00 2001
From: Bo-Onyx <bo@onyx.app>
Date: Tue, 3 Mar 2026 15:36:18 -0800
Subject: [PATCH 062/267] chore: [Running GitHub actions for #8972] (#8996)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jean Caillé <jean.caille@helsing.ai>
---
 .../web_search/web_search_tool.py             |  33 +++-
 .../websearch/test_web_search_tool_run.py     | 164 ++++++++++++++++++
 2 files changed, 189 insertions(+), 8 deletions(-)
 create mode 100644 backend/tests/unit/onyx/tools/tool_implementations/websearch/test_web_search_tool_run.py

diff --git a/backend/onyx/tools/tool_implementations/web_search/web_search_tool.py b/backend/onyx/tools/tool_implementations/web_search/web_search_tool.py
index 6c1adfc1923..cb06368d253 100644
--- a/backend/onyx/tools/tool_implementations/web_search/web_search_tool.py
+++ b/backend/onyx/tools/tool_implementations/web_search/web_search_tool.py
@@ -1,6 +1,5 @@
 import json
 from typing import Any
-from typing import cast
 
 from sqlalchemy.orm import Session
 from typing_extensions import override
@@ -57,6 +56,30 @@ def _sanitize_query(query: str) -> str:
     return " ".join(sanitized.split())
 
 
+def _normalize_queries_input(raw: Any) -> list[str]:
+    """Coerce LLM output to a list of sanitized query strings.
+
+    Accepts a bare string or a list (possibly with non-string elements).
+    Sanitizes each query (strip control chars, normalize whitespace) and
+    drops empty or whitespace-only entries.
+    """
+    if isinstance(raw, str):
+        raw = raw.strip()
+        if not raw:
+            return []
+        raw = [raw]
+    elif not isinstance(raw, list):
+        return []
+    result: list[str] = []
+    for q in raw:
+        if q is None:
+            continue
+        sanitized = _sanitize_query(str(q))
+        if sanitized:
+            result.append(sanitized)
+    return result
+
+
 class WebSearchTool(Tool[WebSearchToolOverrideKwargs]):
     NAME = "web_search"
     DESCRIPTION = "Search the web for information."
@@ -189,13 +212,7 @@ def run(
                     f'like: {{"queries": ["your search query here"]}}'
                 ),
             )
-        raw_queries = cast(list[str], llm_kwargs[QUERIES_FIELD])
-
-        # Normalize queries:
-        # - remove control characters (null bytes, etc.) that LLMs sometimes produce
-        # - collapse whitespace and strip
-        # - drop empty/whitespace-only queries
-        queries = [sanitized for q in raw_queries if (sanitized := _sanitize_query(q))]
+        queries = _normalize_queries_input(llm_kwargs[QUERIES_FIELD])
         if not queries:
             raise ToolCallException(
                 message=(
diff --git a/backend/tests/unit/onyx/tools/tool_implementations/websearch/test_web_search_tool_run.py b/backend/tests/unit/onyx/tools/tool_implementations/websearch/test_web_search_tool_run.py
new file mode 100644
index 00000000000..221b210f261
--- /dev/null
+++ b/backend/tests/unit/onyx/tools/tool_implementations/websearch/test_web_search_tool_run.py
@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import Any
+from typing import cast
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import pytest
+
+from onyx.server.query_and_chat.placement import Placement
+from onyx.tools.models import ToolCallException
+from onyx.tools.models import WebSearchToolOverrideKwargs
+from onyx.tools.tool_implementations.web_search.models import WebSearchResult
+from onyx.tools.tool_implementations.web_search.web_search_tool import (
+    _normalize_queries_input,
+)
+from onyx.tools.tool_implementations.web_search.web_search_tool import WebSearchTool
+
+
+def _make_result(
+    title: str = "Title", link: str = "https://example.com"
+) -> WebSearchResult:
+    return WebSearchResult(title=title, link=link, snippet="snippet")
+
+
+def _make_tool(mock_provider: Any) -> WebSearchTool:
+    """Instantiate WebSearchTool with all DB/provider deps mocked out."""
+    provider_model = MagicMock()
+    provider_model.provider_type = "brave"
+    provider_model.api_key = MagicMock()
+    provider_model.api_key.get_value.return_value = "fake-key"
+    provider_model.config = {}
+
+    with (
+        patch(
+            "onyx.tools.tool_implementations.web_search.web_search_tool.get_session_with_current_tenant"
+        ) as mock_session_ctx,
+        patch(
+            "onyx.tools.tool_implementations.web_search.web_search_tool.fetch_active_web_search_provider",
+            return_value=provider_model,
+        ),
+        patch(
+            "onyx.tools.tool_implementations.web_search.web_search_tool.build_search_provider_from_config",
+            return_value=mock_provider,
+        ),
+    ):
+        mock_session_ctx.return_value.__enter__ = MagicMock(return_value=MagicMock())
+        mock_session_ctx.return_value.__exit__ = MagicMock(return_value=False)
+        tool = WebSearchTool(tool_id=1, emitter=MagicMock())
+
+    return tool
+
+
+def _run(tool: WebSearchTool, queries: Any) -> list[str]:
+    """Call tool.run() and return the list of query strings passed to provider.search."""
+    placement = Placement(turn_index=0, tab_index=0)
+    override_kwargs = WebSearchToolOverrideKwargs(starting_citation_num=1)
+    tool.run(placement=placement, override_kwargs=override_kwargs, queries=queries)
+    search_mock = cast(MagicMock, tool._provider.search)  # noqa: SLF001
+    return [call.args[0] for call in search_mock.call_args_list]
+
+
+class TestNormalizeQueriesInput:
+    """Unit tests for _normalize_queries_input (coercion + sanitization)."""
+
+    def test_bare_string_returns_single_element_list(self) -> None:
+        assert _normalize_queries_input("hello") == ["hello"]
+
+    def test_bare_string_stripped_and_sanitized(self) -> None:
+        assert _normalize_queries_input("  hello  ") == ["hello"]
+        # Control chars (e.g. null) removed; no space inserted
+        assert _normalize_queries_input("hello\x00world") == ["helloworld"]
+
+    def test_empty_string_returns_empty_list(self) -> None:
+        assert _normalize_queries_input("") == []
+        assert _normalize_queries_input("   ") == []
+
+    def test_list_of_strings_returned_sanitized(self) -> None:
+        assert _normalize_queries_input(["a", "b"]) == ["a", "b"]
+        # Leading/trailing space stripped; control chars (e.g. tab) removed
+        assert _normalize_queries_input(["  a  ", "b\tb"]) == ["a", "bb"]
+
+    def test_list_none_skipped(self) -> None:
+        assert _normalize_queries_input(["a", None, "b"]) == ["a", "b"]
+
+    def test_list_non_string_coerced(self) -> None:
+        assert _normalize_queries_input([1, "two"]) == ["1", "two"]
+
+    def test_list_whitespace_only_dropped(self) -> None:
+        assert _normalize_queries_input(["a", "", "  ", "b"]) == ["a", "b"]
+
+    def test_non_list_non_string_returns_empty_list(self) -> None:
+        assert _normalize_queries_input(42) == []
+        assert _normalize_queries_input({}) == []
+
+
+class TestWebSearchToolRunQueryCoercion:
+    def test_list_of_strings_dispatches_each_query(self) -> None:
+        """Normal case: list of queries → one search call per query."""
+        mock_provider = MagicMock()
+        mock_provider.search.return_value = [_make_result()]
+        mock_provider.supports_site_filter = False
+        tool = _make_tool(mock_provider)
+
+        dispatched = _run(tool, ["python decorators", "python generators"])
+
+        # run_functions_tuples_in_parallel uses a thread pool; call_args_list order is non-deterministic.
+        assert sorted(dispatched) == ["python decorators", "python generators"]
+
+    def test_bare_string_dispatches_as_single_query(self) -> None:
+        """LLM returns a bare string instead of an array — must NOT be split char-by-char."""
+        mock_provider = MagicMock()
+        mock_provider.search.return_value = [_make_result()]
+        mock_provider.supports_site_filter = False
+        tool = _make_tool(mock_provider)
+
+        dispatched = _run(tool, "what is the capital of France")
+
+        assert len(dispatched) == 1
+        assert dispatched[0] == "what is the capital of France"
+
+    def test_bare_string_does_not_search_individual_characters(self) -> None:
+        """Regression: single-char searches must not occur."""
+        mock_provider = MagicMock()
+        mock_provider.search.return_value = [_make_result()]
+        mock_provider.supports_site_filter = False
+        tool = _make_tool(mock_provider)
+
+        dispatched = _run(tool, "hi")
+        for query_arg in dispatched:
+            assert (
+                len(query_arg) > 1
+            ), f"Single-character query dispatched: {query_arg!r}"
+
+    def test_control_characters_sanitized_before_dispatch(self) -> None:
+        """Queries with control chars have those chars removed before dispatch."""
+        mock_provider = MagicMock()
+        mock_provider.search.return_value = [_make_result()]
+        mock_provider.supports_site_filter = False
+        tool = _make_tool(mock_provider)
+
+        dispatched = _run(tool, ["foo\x00bar", "baz\tbaz"])
+
+        # run_functions_tuples_in_parallel uses a thread pool; call_args_list is in
+        # execution order, not submission order, so compare in sorted order.
+        assert sorted(dispatched) == ["bazbaz", "foobar"]
+
+    def test_all_empty_or_whitespace_raises_tool_call_exception(self) -> None:
+        """When normalization yields no valid queries, run() raises ToolCallException."""
+        mock_provider = MagicMock()
+        mock_provider.supports_site_filter = False
+        tool = _make_tool(mock_provider)
+        placement = Placement(turn_index=0, tab_index=0)
+        override_kwargs = WebSearchToolOverrideKwargs(starting_citation_num=1)
+
+        with pytest.raises(ToolCallException) as exc_info:
+            tool.run(
+                placement=placement,
+                override_kwargs=override_kwargs,
+                queries="   ",
+            )
+
+        assert "No valid" in str(exc_info.value)
+        cast(MagicMock, mock_provider.search).assert_not_called()

From 19c7809a4331b57695d8d94eb44141eb1c8959a0 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Tue, 3 Mar 2026 16:59:47 -0800
Subject: [PATCH 063/267] feat: Add illustrations to `opal` (#8993)

---
 web/lib/opal/package.json                     |   4 +
 web/lib/opal/scripts/README.md                |  99 ++++++++++++++
 web/lib/opal/scripts/convert-svg.sh           | 123 ++++++++++++++++++
 .../{src/icons => }/scripts/icon-template.js  |   0
 web/lib/opal/src/icons/README.md              |  58 ---------
 web/lib/opal/src/icons/scripts/convert-svg.sh |  72 ----------
 web/lib/opal/src/illustrations/broken-key.tsx |  27 ++++
 web/lib/opal/src/illustrations/connect.tsx    |  35 +++++
 web/lib/opal/src/illustrations/connected.tsx  |  42 ++++++
 .../opal/src/illustrations/disconnected.tsx   |  42 ++++++
 web/lib/opal/src/illustrations/empty.tsx      |  32 +++++
 .../opal/src/illustrations/end-of-line.tsx    |  41 ++++++
 web/lib/opal/src/illustrations/index.ts       |  16 +++
 .../opal/src/illustrations/limit-alert.tsx    |  57 ++++++++
 web/lib/opal/src/illustrations/long-wait.tsx  |  44 +++++++
 web/lib/opal/src/illustrations/no-access.tsx  |  31 +++++
 web/lib/opal/src/illustrations/no-result.tsx  |  32 +++++
 web/lib/opal/src/illustrations/not-found.tsx  |  45 +++++++
 web/lib/opal/src/illustrations/overflow.tsx   |  28 ++++
 .../opal/src/illustrations/plug-broken.tsx    |  31 +++++
 web/lib/opal/src/illustrations/timeout.tsx    |  45 +++++++
 web/lib/opal/src/illustrations/un-plugged.tsx |  67 ++++++++++
 .../opal/src/illustrations/usage-alert.tsx    |  42 ++++++
 23 files changed, 883 insertions(+), 130 deletions(-)
 create mode 100644 web/lib/opal/scripts/README.md
 create mode 100755 web/lib/opal/scripts/convert-svg.sh
 rename web/lib/opal/{src/icons => }/scripts/icon-template.js (100%)
 delete mode 100644 web/lib/opal/src/icons/README.md
 delete mode 100755 web/lib/opal/src/icons/scripts/convert-svg.sh
 create mode 100644 web/lib/opal/src/illustrations/broken-key.tsx
 create mode 100644 web/lib/opal/src/illustrations/connect.tsx
 create mode 100644 web/lib/opal/src/illustrations/connected.tsx
 create mode 100644 web/lib/opal/src/illustrations/disconnected.tsx
 create mode 100644 web/lib/opal/src/illustrations/empty.tsx
 create mode 100644 web/lib/opal/src/illustrations/end-of-line.tsx
 create mode 100644 web/lib/opal/src/illustrations/index.ts
 create mode 100644 web/lib/opal/src/illustrations/limit-alert.tsx
 create mode 100644 web/lib/opal/src/illustrations/long-wait.tsx
 create mode 100644 web/lib/opal/src/illustrations/no-access.tsx
 create mode 100644 web/lib/opal/src/illustrations/no-result.tsx
 create mode 100644 web/lib/opal/src/illustrations/not-found.tsx
 create mode 100644 web/lib/opal/src/illustrations/overflow.tsx
 create mode 100644 web/lib/opal/src/illustrations/plug-broken.tsx
 create mode 100644 web/lib/opal/src/illustrations/timeout.tsx
 create mode 100644 web/lib/opal/src/illustrations/un-plugged.tsx
 create mode 100644 web/lib/opal/src/illustrations/usage-alert.tsx

diff --git a/web/lib/opal/package.json b/web/lib/opal/package.json
index 63e5c08b1be..450a22f64d3 100644
--- a/web/lib/opal/package.json
+++ b/web/lib/opal/package.json
@@ -18,6 +18,10 @@
       "types": "./src/icons/index.ts",
       "default": "./src/icons/index.ts"
     },
+    "./illustrations": {
+      "types": "./src/illustrations/index.ts",
+      "default": "./src/illustrations/index.ts"
+    },
     "./types": {
       "types": "./src/types.ts",
       "default": "./src/types.ts"
diff --git a/web/lib/opal/scripts/README.md b/web/lib/opal/scripts/README.md
new file mode 100644
index 00000000000..7899a48ed8b
--- /dev/null
+++ b/web/lib/opal/scripts/README.md
@@ -0,0 +1,99 @@
+# SVG-to-TSX Conversion Scripts
+
+## Overview
+
+Integrating `@svgr/webpack` into the TypeScript compiler was not working via the recommended route (Next.js webpack configuration).
+The automatic SVG-to-React component conversion was causing compilation issues and import resolution problems.
+Therefore, we manually convert each SVG into a TSX file using SVGR CLI with a custom template.
+
+All scripts in this directory should be run from the **opal package root** (`web/lib/opal/`).
+
+## Directory Layout
+
+```
+web/lib/opal/
+├── scripts/                          # SVG conversion tooling (this directory)
+│   ├── convert-svg.sh                # Converts SVGs into React components
+│   └── icon-template.js              # Shared SVGR template (used for both icons and illustrations)
+├── src/
+│   ├── icons/                        # Small, single-colour icons (stroke = currentColor)
+│   └── illustrations/                # Larger, multi-colour illustrations (colours preserved)
+└── package.json
+```
+
+## Icons vs Illustrations
+
+| | Icons | Illustrations |
+|---|---|---|
+| **Import path** | `@opal/icons` | `@opal/illustrations` |
+| **Location** | `src/icons/` | `src/illustrations/` |
+| **Colour** | Overridable via `currentColor` | Fixed — original SVG colours preserved |
+| **Script flag** | (none) | `--illustration` |
+
+## Files in This Directory
+
+### `icon-template.js`
+
+A custom SVGR template that generates components with the following features:
+- Imports `IconProps` from `@opal/types` for consistent typing
+- Supports the `size` prop for controlling icon dimensions
+- Includes `width` and `height` attributes bound to the `size` prop
+- Maintains all standard SVG props (className, color, title, etc.)
+
+### `convert-svg.sh`
+
+Converts an SVG into a React component. Behaviour depends on the mode:
+
+**Icon mode** (default):
+- Strips `stroke`, `stroke-opacity`, `width`, and `height` attributes
+- Adds `width={size}`, `height={size}`, and `stroke="currentColor"`
+- Result is colour-overridable via CSS `color` property
+
+**Illustration mode** (`--illustration`):
+- Strips only `width` and `height` attributes (all colours preserved)
+- Adds `width={size}` and `height={size}`
+- Does **not** add `stroke="currentColor"` — illustrations keep their original colours
+
+Both modes automatically delete the source SVG file after successful conversion.
+
+## Adding New SVGs
+
+### Icons
+
+```sh
+# From web/lib/opal/
+./scripts/convert-svg.sh src/icons/my-icon.svg
+```
+
+Then add the export to `src/icons/index.ts`:
+```ts
+export { default as SvgMyIcon } from "@opal/icons/my-icon";
+```
+
+### Illustrations
+
+```sh
+# From web/lib/opal/
+./scripts/convert-svg.sh --illustration src/illustrations/my-illustration.svg
+```
+
+Then add the export to `src/illustrations/index.ts`:
+```ts
+export { default as SvgMyIllustration } from "@opal/illustrations/my-illustration";
+```
+
+## Manual Conversion
+
+If you prefer to run the SVGR command directly:
+
+**For icons** (strips colours):
+```sh
+bunx @svgr/cli <file>.svg --typescript --svgo-config '{"plugins":[{"name":"removeAttrs","params":{"attrs":["stroke","stroke-opacity","width","height"]}}]}' --template scripts/icon-template.js > <file>.tsx
+```
+
+**For illustrations** (preserves colours):
+```sh
+bunx @svgr/cli <file>.svg --typescript --svgo-config '{"plugins":[{"name":"removeAttrs","params":{"attrs":["width","height"]}}]}' --template scripts/icon-template.js > <file>.tsx
+```
+
+After running either manual command, remember to delete the original SVG file.
diff --git a/web/lib/opal/scripts/convert-svg.sh b/web/lib/opal/scripts/convert-svg.sh
new file mode 100755
index 00000000000..1382406afd4
--- /dev/null
+++ b/web/lib/opal/scripts/convert-svg.sh
@@ -0,0 +1,123 @@
+#!/bin/bash
+
+# Convert an SVG file to a TypeScript React component.
+#
+# By default, converts to a colour-overridable icon (stroke colours stripped, replaced with currentColor).
+# With --illustration, converts to a fixed-colour illustration (all original colours preserved).
+#
+# Usage (from the opal package root — web/lib/opal/):
+#   ./scripts/convert-svg.sh src/icons/<filename.svg>
+#   ./scripts/convert-svg.sh --illustration src/illustrations/<filename.svg>
+
+ILLUSTRATION=false
+
+# Parse flags
+while [[ "$1" == --* ]]; do
+  case "$1" in
+    --illustration)
+      ILLUSTRATION=true
+      shift
+      ;;
+    *)
+      echo "Unknown flag: $1" >&2
+      echo "Usage: ./scripts/convert-svg.sh [--illustration] <filename.svg>" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$1" ]; then
+  echo "Usage: ./scripts/convert-svg.sh [--illustration] <filename.svg>" >&2
+  exit 1
+fi
+
+SVG_FILE="$1"
+
+# Check if file exists
+if [ ! -f "$SVG_FILE" ]; then
+  echo "Error: File '$SVG_FILE' not found" >&2
+  exit 1
+fi
+
+# Check if it's an SVG file
+if [[ ! "$SVG_FILE" == *.svg ]]; then
+  echo "Error: File must have .svg extension" >&2
+  exit 1
+fi
+
+# Get the base name without extension
+BASE_NAME="${SVG_FILE%.svg}"
+
+# Build the SVGO config based on mode
+if [ "$ILLUSTRATION" = true ]; then
+  # Illustrations: only strip width and height (preserve all colours)
+  SVGO_CONFIG='{"plugins":[{"name":"removeAttrs","params":{"attrs":["width","height"]}}]}'
+else
+  # Icons: strip stroke, stroke-opacity, width, and height
+  SVGO_CONFIG='{"plugins":[{"name":"removeAttrs","params":{"attrs":["stroke","stroke-opacity","width","height"]}}]}'
+fi
+
+# Resolve the template path relative to this script (not the caller's CWD)
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+
+# Run the conversion into a temp file so a failed run doesn't destroy an existing .tsx
+TMPFILE="${BASE_NAME}.tsx.tmp"
+bunx @svgr/cli "$SVG_FILE" --typescript --svgo-config "$SVGO_CONFIG" --template "${SCRIPT_DIR}/icon-template.js" > "$TMPFILE"
+
+if [ $? -eq 0 ]; then
+  # Verify the temp file has content before replacing the destination
+  if [ ! -s "$TMPFILE" ]; then
+    rm -f "$TMPFILE"
+    echo "Error: Output file was not created or is empty" >&2
+    exit 1
+  fi
+
+  mv "$TMPFILE" "${BASE_NAME}.tsx" || { echo "Error: Failed to move temp file" >&2; exit 1; }
+
+  # Post-process the file to add width and height attributes bound to the size prop
+  # Using perl for cross-platform compatibility (works on macOS, Linux, Windows with WSL)
+  # Note: perl -i returns 0 even on some failures, so we validate the output
+
+  perl -i -pe 's/<svg/<svg width={size} height={size}/g' "${BASE_NAME}.tsx"
+  if [ $? -ne 0 ]; then
+    echo "Error: Failed to add width/height attributes" >&2
+    exit 1
+  fi
+
+  # Icons additionally get stroke="currentColor"
+  if [ "$ILLUSTRATION" = false ]; then
+    perl -i -pe 's/\{\.\.\.props\}/stroke="currentColor" {...props}/g' "${BASE_NAME}.tsx"
+    if [ $? -ne 0 ]; then
+      echo "Error: Failed to add stroke attribute" >&2
+      exit 1
+    fi
+  fi
+
+  # Verify the file still exists and has content after post-processing
+  if [ ! -s "${BASE_NAME}.tsx" ]; then
+    echo "Error: Output file corrupted during post-processing" >&2
+    exit 1
+  fi
+
+  # Verify required attributes are present in the output
+  if ! grep -q 'width={size}' "${BASE_NAME}.tsx" || ! grep -q 'height={size}' "${BASE_NAME}.tsx"; then
+    echo "Error: Post-processing did not add required attributes" >&2
+    exit 1
+  fi
+
+  # For icons, also verify stroke="currentColor" was added
+  if [ "$ILLUSTRATION" = false ]; then
+    if ! grep -q 'stroke="currentColor"' "${BASE_NAME}.tsx"; then
+      echo "Error: Post-processing did not add stroke=\"currentColor\"" >&2
+      exit 1
+    fi
+  fi
+
+  echo "Created ${BASE_NAME}.tsx"
+  rm "$SVG_FILE"
+  echo "Deleted $SVG_FILE"
+else
+  rm -f "$TMPFILE"
+  echo "Error: Conversion failed" >&2
+  exit 1
+fi
diff --git a/web/lib/opal/src/icons/scripts/icon-template.js b/web/lib/opal/scripts/icon-template.js
similarity index 100%
rename from web/lib/opal/src/icons/scripts/icon-template.js
rename to web/lib/opal/scripts/icon-template.js
diff --git a/web/lib/opal/src/icons/README.md b/web/lib/opal/src/icons/README.md
deleted file mode 100644
index 1e06d57e2a2..00000000000
--- a/web/lib/opal/src/icons/README.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Compilation of SVGs into TypeScript React Components
-
-## Overview
-
-Integrating `@svgr/webpack` into the TypeScript compiler was not working via the recommended route (Next.js webpack configuration).
-The automatic SVG-to-React component conversion was causing compilation issues and import resolution problems.
-Therefore, we manually convert each SVG into a TSX file using SVGR CLI with a custom template.
-
-## Files in This Directory
-
-### `scripts/icon-template.js`
-
-A custom SVGR template that generates icon components with the following features:
-- Imports `IconProps` from `@opal/types` for consistent typing
-- Supports the `size` prop for controlling icon dimensions
-- Includes `width` and `height` attributes bound to the `size` prop
-- Maintains all standard SVG props (className, color, title, etc.)
-
-This ensures all generated icons have a consistent API and type definitions.
-
-### `scripts/convert-svg.sh`
-
-A convenience script that automates the SVG-to-TSX conversion process. It:
-- Validates the input file
-- Runs SVGR with the correct configuration and template
-- Post-processes the output to add `width`, `height`, and `stroke` attributes using perl (cross-platform compatible)
-- Automatically deletes the source SVG file after successful conversion
-- Provides error handling and user feedback
-
-**Usage:**
-```sh
-./scripts/convert-svg.sh <filename.svg>
-```
-
-## Adding New SVGs
-
-**Recommended Method:**
-
-Use the conversion script for the easiest experience:
-
-```sh
-./scripts/convert-svg.sh my-icon.svg
-```
-
-**Manual Method:**
-
-If you prefer to run the command directly:
-
-```sh
-bunx @svgr/cli ${SVG_FILE_NAME}.svg --typescript --svgo-config '{"plugins":[{"name":"removeAttrs","params":{"attrs":["stroke","stroke-opacity","width","height"]}}]}' --template scripts/icon-template.js > ${SVG_FILE_NAME}.tsx
-```
-
-This command:
-- Converts SVG files to TypeScript React components (`--typescript`)
-- Removes `stroke`, `stroke-opacity`, `width`, and `height` attributes from SVG elements (`--svgo-config` with `removeAttrs` plugin)
-- Uses the custom template (`icon-template.js`) to generate components with `IconProps` and `size` prop support
-
-After running the manual command, remember to delete the original SVG file.
diff --git a/web/lib/opal/src/icons/scripts/convert-svg.sh b/web/lib/opal/src/icons/scripts/convert-svg.sh
deleted file mode 100755
index 82597b7366a..00000000000
--- a/web/lib/opal/src/icons/scripts/convert-svg.sh
+++ /dev/null
@@ -1,72 +0,0 @@
-#!/bin/bash
-
-# Convert an SVG file to a TypeScript React component
-# Usage: ./convert-svg.sh <filename.svg>
-
-if [ -z "$1" ]; then
-  echo "Usage: ./convert-svg.sh <filename.svg>" >&2
-  exit 1
-fi
-
-SVG_FILE="$1"
-
-# Check if file exists
-if [ ! -f "$SVG_FILE" ]; then
-  echo "Error: File '$SVG_FILE' not found" >&2
-  exit 1
-fi
-
-# Check if it's an SVG file
-if [[ ! "$SVG_FILE" == *.svg ]]; then
-  echo "Error: File must have .svg extension" >&2
-  exit 1
-fi
-
-# Get the base name without extension
-BASE_NAME="${SVG_FILE%.svg}"
-
-# Run the conversion with relative path to template
-bunx @svgr/cli "$SVG_FILE" --typescript --svgo-config '{"plugins":[{"name":"removeAttrs","params":{"attrs":["stroke","stroke-opacity","width","height"]}}]}' --template "scripts/icon-template.js" > "${BASE_NAME}.tsx"
-
-if [ $? -eq 0 ]; then
-  # Verify the output file was created and has content
-  if [ ! -s "${BASE_NAME}.tsx" ]; then
-    echo "Error: Output file was not created or is empty" >&2
-    exit 1
-  fi
-
-  # Post-process the file to add width, height, and stroke attributes
-  # Using perl for cross-platform compatibility (works on macOS, Linux, Windows with WSL)
-  # Note: perl -i returns 0 even on some failures, so we validate the output
-
-  perl -i -pe 's/<svg/<svg width={size} height={size}/g' "${BASE_NAME}.tsx"
-  if [ $? -ne 0 ]; then
-    echo "Error: Failed to add width/height attributes" >&2
-    exit 1
-  fi
-
-  perl -i -pe 's/\{\.\.\.props\}/stroke="currentColor" {...props}/g' "${BASE_NAME}.tsx"
-  if [ $? -ne 0 ]; then
-    echo "Error: Failed to add stroke attribute" >&2
-    exit 1
-  fi
-
-  # Verify the file still exists and has content after post-processing
-  if [ ! -s "${BASE_NAME}.tsx" ]; then
-    echo "Error: Output file corrupted during post-processing" >&2
-    exit 1
-  fi
-
-  # Verify required attributes are present in the output
-  if ! grep -q 'width={size}' "${BASE_NAME}.tsx" || ! grep -q 'stroke="currentColor"' "${BASE_NAME}.tsx"; then
-    echo "Error: Post-processing did not add required attributes" >&2
-    exit 1
-  fi
-
-  echo "Created ${BASE_NAME}.tsx"
-  rm "$SVG_FILE"
-  echo "Deleted $SVG_FILE"
-else
-  echo "Error: Conversion failed" >&2
-  exit 1
-fi
diff --git a/web/lib/opal/src/illustrations/broken-key.tsx b/web/lib/opal/src/illustrations/broken-key.tsx
new file mode 100644
index 00000000000..a131755caf8
--- /dev/null
+++ b/web/lib/opal/src/illustrations/broken-key.tsx
@@ -0,0 +1,27 @@
+import type { IconProps } from "@opal/types";
+const SvgBrokenKey = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M54.375 43.125H43.125M69.375 28.125V16.875M58.125 31.875L48.75 22.5"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M108.75 18.75L98.5535 24.6369M98.5535 24.6369L104.044 34.1465L91.7404 41.25L86.25 31.7404M98.5535 24.6369L86.25 31.7404M86.25 31.7404L78.7499 36.0705M49.6599 62.8401C45.5882 58.7684 39.9632 56.25 33.75 56.25C21.3236 56.25 11.25 66.3236 11.25 78.75C11.25 91.1764 21.3236 101.25 33.75 101.25C46.1764 101.25 56.25 91.1764 56.25 78.75C56.25 72.5368 53.7316 66.9118 49.6599 62.8401ZM49.6599 62.8401L49.6406 62.8594M49.6599 62.8401L60 52.5"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgBrokenKey;
diff --git a/web/lib/opal/src/illustrations/connect.tsx b/web/lib/opal/src/illustrations/connect.tsx
new file mode 100644
index 00000000000..9af710bf12f
--- /dev/null
+++ b/web/lib/opal/src/illustrations/connect.tsx
@@ -0,0 +1,35 @@
+import type { IconProps } from "@opal/types";
+const SvgConnect = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M43.125 86.2644H73.379M73.379 86.2644H90.9447C95.6006 86.2644 99.375 90.0388 99.375 94.6947C99.375 99.3506 95.6006 103.125 90.9447 103.125H89.6455C86.3575 103.125 83.292 101.464 81.4959 98.7104L73.379 86.2644ZM73.379 86.2644L39.1266 33.7441M69.375 33.7372L39.1266 33.7441M39.1266 33.7441L21.5635 33.7481C16.9034 33.7491 13.125 29.9717 13.125 25.3115C13.125 20.6522 16.9022 16.875 21.5616 16.875H22.8545C26.1425 16.875 29.208 18.5356 31.0041 21.2896L39.1266 33.7441Z"
+      stroke="#286DF8"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M99.3626 50.625V43.125V24.375V16.875L86.2376 16.875C76.9178 16.875 69.3626 24.4302 69.3626 33.75C69.3626 43.0698 76.9178 50.625 86.2376 50.625H99.3626Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M13.1126 103.125L13.1126 69.3751L26.2376 69.375C35.5574 69.375 43.1126 76.9302 43.1126 86.25C43.1126 95.5698 35.5574 103.125 26.2376 103.125L13.1126 103.125Z"
+      fill="white"
+    />
+    <path
+      d="M99.3626 43.125H110.613M99.3626 43.125V24.375M99.3626 43.125V50.625M99.3626 24.375H110.613M99.3626 24.375V16.875M99.3626 50.625H86.2376C76.9178 50.625 69.3626 43.0698 69.3626 33.75C69.3626 24.4302 76.9178 16.875 86.2376 16.875L99.3626 16.875M99.3626 50.625V54.375M99.3626 16.875V13.125M13.1126 103.125L26.2376 103.125C35.5574 103.125 43.1126 95.5698 43.1126 86.25C43.1126 76.9302 35.5574 69.375 26.2376 69.375L13.1126 69.3751M13.1126 103.125L13.1126 69.3751M13.1126 103.125L13.1126 106.875M13.1126 69.3751V65.6251"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgConnect;
diff --git a/web/lib/opal/src/illustrations/connected.tsx b/web/lib/opal/src/illustrations/connected.tsx
new file mode 100644
index 00000000000..0cdf1786fa7
--- /dev/null
+++ b/web/lib/opal/src/illustrations/connected.tsx
@@ -0,0 +1,42 @@
+import type { IconProps } from "@opal/types";
+const SvgConnected = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M48.0722 48.0722L53.4375 53.4375L66.5625 66.5625L71.9324 71.9416L82.5 61.3648C89.0901 54.7747 89.0901 44.0901 82.5 37.5C75.9099 30.9099 65.2253 30.9099 58.6352 37.5L48.0722 48.0722Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M48.0722 48.0722L58.6352 37.5C65.2253 30.9099 75.9099 30.9099 82.5 37.5M48.0722 48.0722L43.125 43.125M48.0722 48.0722L53.4375 53.4375M71.9324 71.9416L82.5 61.3648C89.0901 54.7747 89.0901 44.0901 82.5 37.5M71.9324 71.9416L76.875 76.8842M71.9324 71.9416L66.5625 66.5625M82.5 37.5L105 15M53.4375 53.4375L43.125 63.75M53.4375 53.4375L66.5625 66.5625M66.5625 66.5625L56.25 76.875"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M71.9278 71.937L48.0676 48.0675L37.5 58.6443C30.9099 65.2344 30.9099 75.9191 37.5 82.5092C44.0901 89.0993 54.7748 89.0993 61.3649 82.5092L71.9278 71.937Z"
+      fill="white"
+    />
+    <path
+      d="M71.9278 71.937L61.3649 82.5092C54.7748 89.0993 44.0901 89.0993 37.5 82.5092M71.9278 71.937L48.0676 48.0675M71.9278 71.937L76.875 76.8842M48.0676 48.0675L37.5 58.6443C30.9099 65.2344 30.9099 75.9191 37.5 82.5092M48.0676 48.0675L43.125 43.125M37.5 82.5092L15 105"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M24.375 24.375L33.75 33.75L52.5 15"
+      stroke="#286DF8"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgConnected;
diff --git a/web/lib/opal/src/illustrations/disconnected.tsx b/web/lib/opal/src/illustrations/disconnected.tsx
new file mode 100644
index 00000000000..976be1a8044
--- /dev/null
+++ b/web/lib/opal/src/illustrations/disconnected.tsx
@@ -0,0 +1,42 @@
+import type { IconProps } from "@opal/types";
+const SvgDisconnected = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M60 83.8554L36.1351 59.9906L26.25 69.8849C19.6599 76.475 19.6599 87.1597 26.25 93.7498C32.8401 100.34 43.5248 100.34 50.1149 93.7498L60 83.8554Z"
+      fill="white"
+    />
+    <path
+      d="M60 83.8554L50.1149 93.7498C43.5248 100.34 32.8401 100.34 26.25 93.7498M60 83.8554L36.1351 59.9906M60 83.8554L63.75 87.6055M36.1351 59.9906L26.25 69.8849C19.6599 76.475 19.6599 87.1597 26.25 93.7498M36.1351 59.9906L32.3946 56.25M26.25 93.7498L15 105"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M60 36.1443L65.3033 41.4476L78.5616 54.7059L83.8649 60.0092L93.75 50.1148C100.34 43.5247 100.34 32.8401 93.75 26.25C87.1599 19.6599 76.4752 19.6599 69.8851 26.25L60 36.1443Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M65.3033 41.4476L56.25 50.5009M65.3033 41.4476L60 36.1443M65.3033 41.4476L78.5616 54.7059M60 36.1443L69.8851 26.25C76.4752 19.6599 87.1599 19.6599 93.75 26.25M60 36.1443L56.25 32.3942M83.8649 60.0092L93.75 50.1148C100.34 43.5247 100.34 32.8401 93.75 26.25M83.8649 60.0092L78.5616 54.7059M83.8649 60.0092L87.6054 63.7498M78.5616 54.7059L69.5177 63.7498M93.75 26.25L105 15"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M30 45H18.75M45 30V18.75M33.75 33.75L24.375 24.375"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgDisconnected;
diff --git a/web/lib/opal/src/illustrations/empty.tsx b/web/lib/opal/src/illustrations/empty.tsx
new file mode 100644
index 00000000000..8d4358a12e1
--- /dev/null
+++ b/web/lib/opal/src/illustrations/empty.tsx
@@ -0,0 +1,32 @@
+import type { IconProps } from "@opal/types";
+const SvgEmpty = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M18.75 71.25V90C18.75 94.1421 22.1079 97.5 26.25 97.5H93.75C97.8921 97.5 101.25 94.1422 101.25 90V71.25H18.75Z"
+      fill="#E6E6E6"
+    />
+    <path d="M18.75 71.25H101.25L86.25 48.75H33.75L18.75 71.25Z" fill="white" />
+    <path
+      d="M18.75 71.25V90C18.75 94.1421 22.1079 97.5 26.25 97.5H93.75C97.8921 97.5 101.25 94.1422 101.25 90V71.25M18.75 71.25H101.25M18.75 71.25L33.75 48.75H86.25L101.25 71.25M54.375 80.625H65.625"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M43.125 35.625L33.75 26.25M76.875 35.625L86.25 26.25M60 28.125V15"
+      stroke="#FFC733"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgEmpty;
diff --git a/web/lib/opal/src/illustrations/end-of-line.tsx b/web/lib/opal/src/illustrations/end-of-line.tsx
new file mode 100644
index 00000000000..8ba746e9a3a
--- /dev/null
+++ b/web/lib/opal/src/illustrations/end-of-line.tsx
@@ -0,0 +1,41 @@
+import type { IconProps } from "@opal/types";
+const SvgEndOfLine = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M67.5 33.75H88.125C93.3027 33.75 97.5 29.5527 97.5 24.375C97.5 19.1973 93.3027 15 88.125 15H76.875C71.6973 15 67.5 19.1973 67.5 24.375V33.75ZM67.5 33.75H15M67.5 33.75V82.5"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M30 82.5H105"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M41.25 93.75H93.75"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M52.5 105H82.5"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgEndOfLine;
diff --git a/web/lib/opal/src/illustrations/index.ts b/web/lib/opal/src/illustrations/index.ts
new file mode 100644
index 00000000000..7844f65ad64
--- /dev/null
+++ b/web/lib/opal/src/illustrations/index.ts
@@ -0,0 +1,16 @@
+export { default as SvgBrokenKey } from "@opal/illustrations/broken-key";
+export { default as SvgConnect } from "@opal/illustrations/connect";
+export { default as SvgConnected } from "@opal/illustrations/connected";
+export { default as SvgDisconnected } from "@opal/illustrations/disconnected";
+export { default as SvgEmpty } from "@opal/illustrations/empty";
+export { default as SvgEndOfLine } from "@opal/illustrations/end-of-line";
+export { default as SvgLimitAlert } from "@opal/illustrations/limit-alert";
+export { default as SvgLongWait } from "@opal/illustrations/long-wait";
+export { default as SvgNoAccess } from "@opal/illustrations/no-access";
+export { default as SvgNoResult } from "@opal/illustrations/no-result";
+export { default as SvgNotFound } from "@opal/illustrations/not-found";
+export { default as SvgOverflow } from "@opal/illustrations/overflow";
+export { default as SvgPlugBroken } from "@opal/illustrations/plug-broken";
+export { default as SvgTimeout } from "@opal/illustrations/timeout";
+export { default as SvgUnPlugged } from "@opal/illustrations/un-plugged";
+export { default as SvgUsageAlert } from "@opal/illustrations/usage-alert";
diff --git a/web/lib/opal/src/illustrations/limit-alert.tsx b/web/lib/opal/src/illustrations/limit-alert.tsx
new file mode 100644
index 00000000000..f1809107b67
--- /dev/null
+++ b/web/lib/opal/src/illustrations/limit-alert.tsx
@@ -0,0 +1,57 @@
+import type { IconProps } from "@opal/types";
+const SvgLimitAlert = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M15 82.5C15 78.3579 18.3579 75 22.5 75L97.5 75C101.642 75 105 78.3579 105 82.5V90C105 94.1421 101.642 97.5 97.5 97.5L22.5 97.5C18.3579 97.5 15 94.1421 15 90V82.5Z"
+      fill="#FBEAE4"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M93.75 86.25H78.75"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M67.5 86.2499H26.25"
+      stroke="#F5A88B"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M15 48.75C15 44.6079 18.3579 41.25 22.5 41.25L52.5 41.25C56.6421 41.25 60 44.6079 60 48.75L60 56.25C60 60.3921 56.6421 63.75 52.5 63.75H22.5C18.3579 63.75 15 60.3921 15 56.25L15 48.75Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M45 52.5H26.25M52.5 63.75H22.5C18.3579 63.75 15 60.3921 15 56.25L15 48.75C15 44.6079 18.3579 41.25 22.5 41.25L52.5 41.25C56.6421 41.25 60 44.6079 60 48.75L60 56.25C60 60.3921 56.6421 63.75 52.5 63.75Z"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M86.25 41.25C81.0723 41.25 76.875 45.4473 76.875 50.625L76.875 63.75L86.25 63.75L95.625 63.75V50.625C95.625 45.4473 91.4277 41.25 86.25 41.25Z"
+      fill="#FBEAE4"
+    />
+    <path
+      d="M76.875 63.75L76.875 50.625C76.875 45.4473 81.0723 41.25 86.25 41.25C91.4277 41.25 95.625 45.4473 95.625 50.625V63.75M76.875 63.75L86.25 63.75M76.875 63.75L73.125 63.75M95.625 63.75H99.375M95.625 63.75L86.25 63.75M86.25 52.5V63.75M76.875 33.75L71.25 28.125M95.625 33.75L101.25 28.125M86.25 30L86.25 22.5"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgLimitAlert;
diff --git a/web/lib/opal/src/illustrations/long-wait.tsx b/web/lib/opal/src/illustrations/long-wait.tsx
new file mode 100644
index 00000000000..22fba7ac0da
--- /dev/null
+++ b/web/lib/opal/src/illustrations/long-wait.tsx
@@ -0,0 +1,44 @@
+import type { IconProps } from "@opal/types";
+const SvgLongWait = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M103.253 47.5404C104.391 51.4971 105 55.6774 105 60C105 84.8528 84.8528 105 60 105C35.1472 105 15 84.8528 15 60C15 35.1472 35.1472 15 60 15C64.3226 15 68.5029 15.6095 72.4596 16.7472C70.4991 20.0854 69.375 23.9739 69.375 28.125C69.375 40.5514 79.4486 50.625 91.875 50.625C96.0261 50.625 99.9146 49.5009 103.253 47.5404Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M69.375 28.125C69.375 40.5514 79.4486 50.625 91.875 50.625C96.0261 50.625 99.9146 49.5009 103.253 47.5404C109.908 43.6322 114.375 36.4003 114.375 28.125C114.375 15.6986 104.301 5.625 91.875 5.625C83.5997 5.625 76.3678 10.0925 72.4596 16.7472C70.4991 20.0854 69.375 23.9739 69.375 28.125Z"
+      fill="white"
+    />
+    <path
+      d="M54.1223 104.615C56.0462 104.866 58.0077 105 60 105C61.9911 105 63.9513 104.866 65.874 104.615M42.7771 101.576C39.1175 100.058 35.7047 98.0716 32.6074 95.6909M87.3889 95.6909C84.2914 98.0715 80.8791 100.058 77.2192 101.576M24.3054 87.3889C21.9251 84.2915 19.9377 80.8789 18.4204 77.2192M101.576 77.2192C100.058 80.8791 98.0715 84.2914 95.6909 87.3889M15.3809 54.1223C15.1299 56.046 15 58.0079 15 60C15 61.9909 15.1302 63.9515 15.3809 65.874M104.615 65.874C104.866 63.9513 105 61.9911 105 60C105 58.0077 104.866 56.0462 104.615 54.1223M18.4204 42.7771C19.9379 39.1177 21.925 35.7046 24.3054 32.6074M32.6074 24.3054C35.7046 21.925 39.1177 19.9379 42.7771 18.4204M65.874 15.3809C63.9515 15.1302 61.9909 15 60 15C58.0079 15 56.046 15.1299 54.1223 15.3809"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M60 33.0001V60.0001L78 69.0001"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M84.375 20.625H99.375L84.375 35.625H99.375"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgLongWait;
diff --git a/web/lib/opal/src/illustrations/no-access.tsx b/web/lib/opal/src/illustrations/no-access.tsx
new file mode 100644
index 00000000000..89ad7d86153
--- /dev/null
+++ b/web/lib/opal/src/illustrations/no-access.tsx
@@ -0,0 +1,31 @@
+import type { IconProps } from "@opal/types";
+const SvgNoAccess = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M18.75 22.5V105L60 105L101.25 105V22.5C101.25 18.3578 97.8921 15 93.75 15H60H26.25C22.1079 15 18.75 18.3578 18.75 22.5Z"
+      fill="white"
+    />
+    <path
+      d="M18.75 105V22.5C18.75 18.3578 22.1079 15 26.25 15H60M18.75 105L60 105M18.75 105L11.25 105M101.25 105V22.5C101.25 18.3578 97.8921 15 93.75 15H60M101.25 105L60 105M101.25 105H108.75M60 93.75V105M60 15V26.25"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M46.875 58.1249V50.625C46.875 43.3762 52.7512 37.5 60 37.5C67.2487 37.5 73.125 43.3762 73.125 50.625V58.125M46.875 58.1249L44.9999 58.1249C42.9289 58.125 41.25 59.8039 41.25 61.8749V78.75C41.25 80.821 42.9289 82.5 45 82.5L75 82.5C77.071 82.5 78.75 80.821 78.75 78.75V61.875C78.75 59.8039 77.071 58.125 75 58.125H73.125M46.875 58.1249L73.125 58.125M60 67.4999V73.1249"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgNoAccess;
diff --git a/web/lib/opal/src/illustrations/no-result.tsx b/web/lib/opal/src/illustrations/no-result.tsx
new file mode 100644
index 00000000000..218cfae2e8f
--- /dev/null
+++ b/web/lib/opal/src/illustrations/no-result.tsx
@@ -0,0 +1,32 @@
+import type { IconProps } from "@opal/types";
+const SvgNoResult = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path d="M91.875 45H28.125L11.25 112.5H108.75L91.875 45Z" fill="white" />
+    <path
+      d="M26.25 45L50.0345 23.8582C52.8762 21.3323 56.4381 20.0693 60 20.0693C63.5619 20.0693 67.1238 21.3323 69.9655 23.8582L93.75 45H26.25Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M60 7.5V20.0693M60 20.0693C56.4381 20.0693 52.8762 21.3323 50.0345 23.8582L26.25 45H93.75L69.9655 23.8582C67.1238 21.3323 63.5619 20.0693 60 20.0693Z"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M43.125 99.375L33.75 90M60 91.875V78.75M76.875 99.375L86.25 90"
+      stroke="#FFC733"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgNoResult;
diff --git a/web/lib/opal/src/illustrations/not-found.tsx b/web/lib/opal/src/illustrations/not-found.tsx
new file mode 100644
index 00000000000..17c0ecf3d95
--- /dev/null
+++ b/web/lib/opal/src/illustrations/not-found.tsx
@@ -0,0 +1,45 @@
+import type { IconProps } from "@opal/types";
+const SvgNotFound = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M61.875 95.625C80.5146 95.625 95.625 80.5146 95.625 61.875C95.625 43.2354 80.5146 28.125 61.875 28.125C43.2354 28.125 28.125 43.2354 28.125 61.875C28.125 80.5146 43.2354 95.625 61.875 95.625Z"
+      fill="white"
+    />
+    <path
+      d="M103.125 103.125L85.7109 85.7109M95.625 61.875C95.625 80.5146 80.5146 95.625 61.875 95.625C43.2354 95.625 28.125 80.5146 28.125 61.875C28.125 43.2354 43.2354 28.125 61.875 28.125C80.5146 28.125 95.625 43.2354 95.625 61.875Z"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M56.713 46.3302C54.7486 47.4847 53.2561 49.2972 52.5 51.4466H51.5625V51.1341C52.3923 48.7766 54.0843 46.7901 56.239 45.5237C58.3943 44.257 60.9272 43.7937 63.3911 44.2163C65.855 44.639 68.091 45.9183 69.7009 47.8308C71.3108 49.7433 72.1912 52.1645 72.1875 54.6643C72.1868 58.3647 69.5002 61.0222 67.0935 62.6734C65.8647 63.5165 64.6397 64.1423 63.728 64.5594C63.2713 64.7682 62.8885 64.9259 62.6184 65.0318V67.5H61.875L61.875 64.3111C61.875 64.3111 71.25 61.095 71.25 54.6628C71.2534 52.3842 70.4503 50.178 68.9829 48.4348C67.5155 46.6917 65.4785 45.5241 63.2328 45.1389C60.987 44.7537 58.6774 45.1757 56.713 46.3302Z"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M62.8125 76.875H60.9375V78.75H62.8125V76.875Z"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M20.625 50.625H11.25M30 30L22.5 22.5M50.625 20.625V11.25"
+      stroke="#FFC733"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgNotFound;
diff --git a/web/lib/opal/src/illustrations/overflow.tsx b/web/lib/opal/src/illustrations/overflow.tsx
new file mode 100644
index 00000000000..561cb06af5f
--- /dev/null
+++ b/web/lib/opal/src/illustrations/overflow.tsx
@@ -0,0 +1,28 @@
+import type { IconProps } from "@opal/types";
+const SvgOverflow = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M22.5 71.2501L25.3301 91.0607C25.8579 94.7555 29.0223 97.5 32.7547 97.5H87.2453C90.9777 97.5 94.1421 94.7555 94.6699 91.0607L97.5 71.2501H22.5Z"
+      fill="#E6E6E6"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M18.7501 46.8752L78.5183 52.4717M32.7965 34.583L91.8752 45.0002M45.1839 22.5002L103.125 38.0255M90.0002 61.8752H30.0002"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgOverflow;
diff --git a/web/lib/opal/src/illustrations/plug-broken.tsx b/web/lib/opal/src/illustrations/plug-broken.tsx
new file mode 100644
index 00000000000..e5eb3ccd946
--- /dev/null
+++ b/web/lib/opal/src/illustrations/plug-broken.tsx
@@ -0,0 +1,31 @@
+import type { IconProps } from "@opal/types";
+const SvgPlugBroken = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M31.875 78.75L24.375 71.25M50.625 78.75L58.125 71.25M41.25 73.125V63.75"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M97.5 30H90H71.25H63.75V43.125C63.75 52.4448 71.3052 60 80.625 60C89.9448 60 97.5 52.4448 97.5 43.125V30Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M50.625 90H95.625C99.7671 90 103.125 93.3579 103.125 97.5C103.125 101.642 99.7671 105 95.625 105H88.125C83.9829 105 80.625 101.642 80.625 97.5V60M31.875 90H16.875M90 30V18.75M90 30H97.5M90 30H71.25M97.5 30V43.125C97.5 52.4448 89.9448 60 80.625 60M97.5 30H103.125M63.75 30V43.125C63.75 52.4448 71.3052 60 80.625 60M63.75 30H71.25M63.75 30H58.125M71.25 30V18.75"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgPlugBroken;
diff --git a/web/lib/opal/src/illustrations/timeout.tsx b/web/lib/opal/src/illustrations/timeout.tsx
new file mode 100644
index 00000000000..300c01e946a
--- /dev/null
+++ b/web/lib/opal/src/illustrations/timeout.tsx
@@ -0,0 +1,45 @@
+import type { IconProps } from "@opal/types";
+const SvgTimeout = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M26.25 101.25H78.75V93.75L62.6392 83.3931C56.4628 79.4225 48.5372 79.4225 42.3608 83.3931L26.25 93.75V101.25Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M74.4446 77.8572L52.5 63.75L30.5554 77.8572C27.8721 79.5822 26.25 82.5533 26.25 85.7433V93.75L42.3608 83.3931C48.5372 79.4225 56.4628 79.4225 62.6392 83.3931L78.75 93.75V85.7433C78.75 82.5533 77.1279 79.5822 74.4446 77.8572Z"
+      fill="white"
+    />
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M26.25 26.25H68.7803C67.9512 28.5958 67.5 31.1202 67.5 33.75C67.5 40.0285 70.0716 45.7064 74.219 49.7878L52.5 63.75L30.5554 49.6428C27.8721 47.9178 26.25 44.9467 26.25 41.7567V26.25Z"
+      fill="white"
+    />
+    <path
+      d="M112.5 33.75C112.5 21.3236 102.426 11.25 90 11.25C80.2034 11.25 71.8691 17.511 68.7803 26.25C67.9512 28.5958 67.5 31.1202 67.5 33.75C67.5 40.0285 70.0716 45.7064 74.219 49.7878C78.2801 53.7843 83.8521 56.25 90 56.25C102.426 56.25 112.5 46.1764 112.5 33.75Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M52.5 63.75L30.5554 49.6428C27.8721 47.9178 26.25 44.9467 26.25 41.7567V26.25M52.5 63.75L74.4446 77.8572C77.1279 79.5822 78.75 82.5533 78.75 85.7433V101.25M52.5 63.75L30.5554 77.8572C27.8721 79.5822 26.25 82.5533 26.25 85.7433V101.25M52.5 63.75L72.6052 50.8252M26.25 26.25H18.75M26.25 26.25H66.8006M78.75 101.25H26.25M78.75 101.25H86.25M26.25 101.25H18.75"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M82.5 26.25H97.5L82.5 41.25H97.5"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgTimeout;
diff --git a/web/lib/opal/src/illustrations/un-plugged.tsx b/web/lib/opal/src/illustrations/un-plugged.tsx
new file mode 100644
index 00000000000..103197e77b7
--- /dev/null
+++ b/web/lib/opal/src/illustrations/un-plugged.tsx
@@ -0,0 +1,67 @@
+import type { IconProps } from "@opal/types";
+const SvgUnPlugged = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M56.25 16.875C43.8236 16.875 33.75 26.9486 33.75 39.375L33.75 54.375C33.75 66.8014 43.8236 76.875 56.25 76.875H71.25C83.6764 76.875 93.75 66.8014 93.75 54.375V39.375C93.75 26.9486 83.6764 16.875 71.25 16.875H56.25ZM67.5 65.625V60C67.5 56.8934 64.9816 54.375 61.875 54.375C58.7684 54.375 56.25 56.8934 56.25 60V65.625H67.5Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M67.5 60V65.625H56.25V60C56.25 56.8934 58.7684 54.375 61.875 54.375C64.9816 54.375 67.5 56.8934 67.5 60Z"
+      fill="white"
+    />
+    <path
+      d="M48.75 46.875V35.625M75 46.875V35.625M67.5 65.625V60C67.5 56.8934 64.9816 54.375 61.875 54.375C58.7684 54.375 56.25 56.8934 56.25 60V65.625H67.5ZM56.25 76.875H71.25C83.6764 76.875 93.75 66.8014 93.75 54.375V39.375C93.75 26.9486 83.6764 16.875 71.25 16.875H56.25C43.8236 16.875 33.75 26.9486 33.75 39.375L33.75 54.375C33.75 66.8014 43.8236 76.875 56.25 76.875Z"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path d="M26.25 87.1875V97.5H28.125V87.1875H26.25Z" fill="#F0F0F0" />
+    <path
+      d="M52.5 88.125V97.5H50.625V88.125C50.625 87.6072 51.0447 87.1875 51.5625 87.1875C52.0803 87.1875 52.5 87.6072 52.5 88.125Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M26.25 87.1875V97.5H28.125V87.1875H26.25Z"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M52.5 88.125V97.5H50.625V88.125C50.625 87.6072 51.0447 87.1875 51.5625 87.1875C52.0803 87.1875 52.5 87.6072 52.5 88.125Z"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M18.1798 109.239C16.3504 108.958 15 107.384 15 105.533V97.5H63.75V105V108.75C63.75 110.821 62.0711 112.5 60 112.5H39.6618C39.4709 112.5 39.2802 112.485 39.0916 112.456L18.1798 109.239Z"
+      fill="#E6E6E6"
+    />
+    <path
+      d="M63.75 105H105M63.75 105V108.75C63.75 110.821 62.0711 112.5 60 112.5H39.6618C39.4709 112.5 39.2802 112.485 39.0916 112.456L18.1798 109.239C16.3504 108.958 15 107.384 15 105.533V97.5H63.75V105Z"
+      stroke="#A4A4A4"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M93.75 15L95.625 9.37498M103.125 31.875L108.75 33.75M101.25 22.5L106.875 18.75"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgUnPlugged;
diff --git a/web/lib/opal/src/illustrations/usage-alert.tsx b/web/lib/opal/src/illustrations/usage-alert.tsx
new file mode 100644
index 00000000000..6bce11204aa
--- /dev/null
+++ b/web/lib/opal/src/illustrations/usage-alert.tsx
@@ -0,0 +1,42 @@
+import type { IconProps } from "@opal/types";
+const SvgUsageAlert = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 120 120"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M15 90C15 85.8578 18.3579 82.5 22.5 82.5L60 82.5C64.1421 82.5 67.5 85.8578 67.5 90L67.5 97.5C67.5 101.642 64.1421 105 60 105H22.5C18.3579 105 15 101.642 15 97.5L15 90Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M15 22.5C15 18.3579 18.3579 15 22.5 15H45C49.1421 15 52.5 18.3579 52.5 22.5L52.5 29.9999C52.5 34.1421 49.1421 37.4999 45 37.4999H22.5C18.3579 37.4999 15 34.1421 15 29.9999V22.5Z"
+      fill="#F0F0F0"
+    />
+    <path
+      d="M52.5 93.75H26.25M37.5 26.25H26.25M22.5 15H45C49.1421 15 52.5 18.3579 52.5 22.5L52.5 29.9999C52.5 34.1421 49.1421 37.4999 45 37.4999H22.5C18.3579 37.4999 15 34.1421 15 29.9999V22.5C15 18.3579 18.3579 15 22.5 15ZM60 105H22.5C18.3579 105 15 101.642 15 97.5L15 90C15 85.8578 18.3579 82.5 22.5 82.5L60 82.5C64.1421 82.5 67.5 85.8578 67.5 90L67.5 97.5C67.5 101.642 64.1421 105 60 105Z"
+      stroke="#CCCCCC"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M78.75 60H71.25M90 37.5V30M103.125 50.625H110.625M99.375 41.25L105 35.625M82.5 71.25L22.5 71.25C18.3579 71.25 15 67.8922 15 63.75V56.25C15 52.1079 18.3579 48.75 22.5 48.75L82.5 48.75C86.6421 48.75 90 52.1079 90 56.25V63.75C90 67.8922 86.6421 71.25 82.5 71.25Z"
+      stroke="#EC5B13"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M60 60H26.25"
+      stroke="#F5A88B"
+      strokeWidth={3.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgUsageAlert;

From 01d347397469121837e4fa740be57f191c5161f4 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Tue, 3 Mar 2026 17:04:15 -0800
Subject: [PATCH 064/267] chore: port Greptile custom context rules to
 greptile.json (#9003)

---
 greptile.json | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/greptile.json b/greptile.json
index 4b1fb81ea5c..7414674129a 100644
--- a/greptile.json
+++ b/greptile.json
@@ -51,20 +51,41 @@
       "other": [
         {
           "scope": [],
-          "content": ""
+          "content": "Use explicit type annotations for variables to enhance code clarity, especially when moving type hints around in the code."
         }
       ],
       "rules": [
         {
           "scope": [],
-          "rule": ""
+          "rule": "Whenever a TODO is added, there must always be an associated name or ticket with that TODO in the style of TODO(name): ... or TODO(1234): ..."
+        },
+        {
+          "scope": ["web/**"],
+          "rule": "For frontend changes (changes that touch the /web directory), make sure to enforce all standards described in the web/STANDARDS.md file."
+        },
+        {
+          "scope": [],
+          "rule": "Remove temporary debugging code before merging to production, especially tenant-specific debugging logs."
+        },
+        {
+          "scope": [],
+          "rule": "When hardcoding a boolean variable to a constant value, remove the variable entirely and clean up all places where it's used rather than just setting it to a constant."
+        },
+        {
+          "scope": ["backend/**/*.py"],
+          "rule": "Never raise HTTPException directly in business code. Use `raise OnyxError(OnyxErrorCode.XXX, \"message\")` from `onyx.error_handling.exceptions`. A global FastAPI exception handler converts OnyxError into structured JSON responses with {\"error_code\": \"...\", \"message\": \"...\"}. Error codes are defined in `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors with dynamic HTTP status codes, use `status_code_override`: `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`."
         }
       ],
       "files": [
         {
           "scope": [],
-          "path": "",
-          "description": ""
+          "path": "contributing_guides/best_practices.md",
+          "description": "Best practices for contributing to the codebase"
+        },
+        {
+          "scope": [],
+          "path": "CLAUDE.md",
+          "description": "Project instructions and coding standards"
         }
       ]
     }

From 003d94546a3e7bedda2e825db94c6b48cedc4431 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 3 Mar 2026 17:13:31 -0800
Subject: [PATCH 065/267] fix(a11y): prevent show password button losing focus
 on tab (#9000)

---
 .../inputs/PasswordInputTypeIn.tsx            | 84 ++++++++++++-------
 1 file changed, 52 insertions(+), 32 deletions(-)

diff --git a/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx b/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx
index d508897c6f7..f43a8369a30 100644
--- a/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx
+++ b/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx
@@ -172,6 +172,7 @@ export default function PasswordInputTypeIn({
 }: PasswordInputTypeInProps) {
   const [isPasswordVisible, setIsPasswordVisible] = React.useState(false);
   const [isFocused, setIsFocused] = React.useState(false);
+  const containerRef = React.useRef<HTMLDivElement>(null);
 
   // Track selection range before changes occur
   const selectionRef = React.useRef<{ start: number; end: number }>({
@@ -192,9 +193,22 @@ export default function PasswordInputTypeIn({
     return realValue;
   };
 
+  const handleContainerFocus = React.useCallback(() => {
+    setIsFocused(true);
+  }, []);
+
+  const handleContainerBlur = React.useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      if (containerRef.current?.contains(e.relatedTarget as Node)) {
+        return;
+      }
+      setIsFocused(false);
+    },
+    []
+  );
+
   const handleFocus = React.useCallback(
     (e: React.FocusEvent<HTMLInputElement>) => {
-      setIsFocused(true);
       onFocus?.(e);
     },
     [onFocus]
@@ -202,7 +216,6 @@ export default function PasswordInputTypeIn({
 
   const handleBlur = React.useCallback(
     (e: React.FocusEvent<HTMLInputElement>) => {
-      setIsFocused(false);
       onBlur?.(e);
     },
     [onBlur]
@@ -272,35 +285,42 @@ export default function PasswordInputTypeIn({
       : "Show password";
 
   return (
-    <InputTypeIn
-      ref={ref}
-      value={getDisplayValue()}
-      onChange={handleChange}
-      onFocus={handleFocus}
-      onBlur={handleBlur}
-      onSelect={captureSelection}
-      onKeyDown={captureSelection}
-      variant={disabled ? "disabled" : error ? "error" : undefined}
-      showClearButton={showClearButton}
-      autoComplete="off"
-      data-ph-no-capture
-      rightSection={
-        showToggleButton ? (
-          <Button
-            icon={isRevealed ? SvgEye : SvgEyeClosed}
-            disabled={disabled || effectiveNonRevealable}
-            onClick={noProp(() => setIsPasswordVisible((v) => !v))}
-            type="button"
-            variant={isRevealed ? "action" : undefined}
-            prominence="tertiary"
-            size="sm"
-            tooltipSide="left"
-            tooltip={toggleLabel}
-            aria-label={toggleLabel}
-          />
-        ) : undefined
-      }
-      {...props}
-    />
+    <div
+      ref={containerRef}
+      className="contents"
+      onFocus={handleContainerFocus}
+      onBlur={handleContainerBlur}
+    >
+      <InputTypeIn
+        ref={ref}
+        value={getDisplayValue()}
+        onChange={handleChange}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onSelect={captureSelection}
+        onKeyDown={captureSelection}
+        variant={disabled ? "disabled" : error ? "error" : undefined}
+        showClearButton={showClearButton}
+        autoComplete="off"
+        data-ph-no-capture
+        rightSection={
+          showToggleButton ? (
+            <Button
+              icon={isRevealed ? SvgEye : SvgEyeClosed}
+              disabled={disabled || effectiveNonRevealable}
+              onClick={noProp(() => setIsPasswordVisible((v) => !v))}
+              type="button"
+              variant={isRevealed ? "action" : undefined}
+              prominence="tertiary"
+              size="sm"
+              tooltipSide="left"
+              tooltip={toggleLabel}
+              aria-label={toggleLabel}
+            />
+          ) : undefined
+        }
+        {...props}
+      />
+    </div>
   );
 }

From 9862fbd4a6ab954a5cf47f4aade717636d62ed58 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Tue, 3 Mar 2026 17:38:02 -0800
Subject: [PATCH 066/267] chore: deploying onyx lite (#9004)

---
 .github/workflows/pr-integration-tests.yml    | 51 ++++++++-----------
 backend/ee/onyx/db/license.py                 | 49 ++++++++----------
 .../server/middleware/license_enforcement.py  |  6 +--
 backend/ee/onyx/server/settings/api.py        |  3 +-
 backend/onyx/auth/users.py                    |  8 +--
 backend/onyx/cache/interface.py               | 11 ++++
 ...tordb.yml => docker-compose.onyx-lite.yml} | 40 ++++++++++-----
 deployment/helm/charts/onyx/values-lite.yaml  | 31 +++++++++++
 8 files changed, 121 insertions(+), 78 deletions(-)
 rename deployment/docker_compose/{docker-compose.no-vectordb.yml => docker-compose.onyx-lite.yml} (55%)
 create mode 100644 deployment/helm/charts/onyx/values-lite.yaml

diff --git a/.github/workflows/pr-integration-tests.yml b/.github/workflows/pr-integration-tests.yml
index 6797f3d03d8..07b608522a4 100644
--- a/.github/workflows/pr-integration-tests.yml
+++ b/.github/workflows/pr-integration-tests.yml
@@ -471,13 +471,13 @@ jobs:
           path: ${{ github.workspace }}/docker-compose.log
       # ------------------------------------------------------------
 
-  no-vectordb-tests:
+  onyx-lite-tests:
     needs: [build-backend-image, build-integration-image]
     runs-on:
       [
         runs-on,
         runner=4cpu-linux-arm64,
-        "run-id=${{ github.run_id }}-no-vectordb-tests",
+        "run-id=${{ github.run_id }}-onyx-lite-tests",
         "extras=ecr-cache",
       ]
     timeout-minutes: 45
@@ -495,13 +495,12 @@ jobs:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_TOKEN }}
 
-      - name: Create .env file for no-vectordb Docker Compose
+      - name: Create .env file for Onyx Lite Docker Compose
         env:
           ECR_CACHE: ${{ env.RUNS_ON_ECR_CACHE }}
           RUN_ID: ${{ github.run_id }}
         run: |
           cat <<EOF > deployment/docker_compose/.env
-          COMPOSE_PROFILES=s3-filestore
           ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=true
           LICENSE_ENFORCEMENT_ENABLED=false
           AUTH_TYPE=basic
@@ -509,28 +508,23 @@ jobs:
           POSTGRES_USE_NULL_POOL=true
           REQUIRE_EMAIL_VERIFICATION=false
           DISABLE_TELEMETRY=true
-          DISABLE_VECTOR_DB=true
           ONYX_BACKEND_IMAGE=${ECR_CACHE}:integration-test-backend-test-${RUN_ID}
           INTEGRATION_TESTS_MODE=true
-          USE_LIGHTWEIGHT_BACKGROUND_WORKER=true
           EOF
 
-      # Start only the services needed for no-vectordb mode (no Vespa, no model servers)
-      - name: Start Docker containers (no-vectordb)
+      # Start only the services needed for Onyx Lite (Postgres + API server)
+      - name: Start Docker containers (onyx-lite)
         run: |
           cd deployment/docker_compose
-          docker compose -f docker-compose.yml -f docker-compose.no-vectordb.yml -f docker-compose.dev.yml up \
+          docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml -f docker-compose.dev.yml up \
             relational_db \
-            cache \
-            minio \
             api_server \
-            background \
             -d
-        id: start_docker_no_vectordb
+        id: start_docker_onyx_lite
 
       - name: Wait for services to be ready
         run: |
-          echo "Starting wait-for-service script (no-vectordb)..."
+          echo "Starting wait-for-service script (onyx-lite)..."
           start_time=$(date +%s)
           timeout=300
           while true; do
@@ -552,14 +546,14 @@ jobs:
             sleep 5
           done
 
-      - name: Run No-VectorDB Integration Tests
+      - name: Run Onyx Lite Integration Tests
         uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # ratchet:nick-fields/retry@v3
         with:
           timeout_minutes: 20
           max_attempts: 3
           retry_wait_seconds: 10
           command: |
-            echo "Running no-vectordb integration tests..."
+            echo "Running onyx-lite integration tests..."
             docker run --rm --network onyx_default \
               --name test-runner \
               -e POSTGRES_HOST=relational_db \
@@ -570,39 +564,38 @@ jobs:
               -e DB_READONLY_PASSWORD=password \
               -e POSTGRES_POOL_PRE_PING=true \
               -e POSTGRES_USE_NULL_POOL=true \
-              -e REDIS_HOST=cache \
               -e API_SERVER_HOST=api_server \
               -e OPENAI_API_KEY=${OPENAI_API_KEY} \
               -e TEST_WEB_HOSTNAME=test-runner \
               ${{ env.RUNS_ON_ECR_CACHE }}:integration-test-${{ github.run_id }} \
               /app/tests/integration/tests/no_vectordb
 
-      - name: Dump API server logs (no-vectordb)
+      - name: Dump API server logs (onyx-lite)
         if: always()
         run: |
           cd deployment/docker_compose
-          docker compose -f docker-compose.yml -f docker-compose.no-vectordb.yml -f docker-compose.dev.yml \
-            logs --no-color api_server > $GITHUB_WORKSPACE/api_server_no_vectordb.log || true
+          docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml -f docker-compose.dev.yml \
+            logs --no-color api_server > $GITHUB_WORKSPACE/api_server_onyx_lite.log || true
 
-      - name: Dump all-container logs (no-vectordb)
+      - name: Dump all-container logs (onyx-lite)
         if: always()
         run: |
           cd deployment/docker_compose
-          docker compose -f docker-compose.yml -f docker-compose.no-vectordb.yml -f docker-compose.dev.yml \
-            logs --no-color > $GITHUB_WORKSPACE/docker-compose-no-vectordb.log || true
+          docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml -f docker-compose.dev.yml \
+            logs --no-color > $GITHUB_WORKSPACE/docker-compose-onyx-lite.log || true
 
-      - name: Upload logs (no-vectordb)
+      - name: Upload logs (onyx-lite)
         if: always()
         uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
         with:
-          name: docker-all-logs-no-vectordb
-          path: ${{ github.workspace }}/docker-compose-no-vectordb.log
+          name: docker-all-logs-onyx-lite
+          path: ${{ github.workspace }}/docker-compose-onyx-lite.log
 
-      - name: Stop Docker containers (no-vectordb)
+      - name: Stop Docker containers (onyx-lite)
         if: always()
         run: |
           cd deployment/docker_compose
-          docker compose -f docker-compose.yml -f docker-compose.no-vectordb.yml -f docker-compose.dev.yml down -v
+          docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml -f docker-compose.dev.yml down -v
 
   multitenant-tests:
     needs:
@@ -744,7 +737,7 @@ jobs:
     # NOTE: Github-hosted runners have about 20s faster queue times and are preferred here.
     runs-on: ubuntu-slim
     timeout-minutes: 45
-    needs: [integration-tests, no-vectordb-tests, multitenant-tests]
+    needs: [integration-tests, onyx-lite-tests, multitenant-tests]
     if: ${{ always() }}
     steps:
       - name: Check job status
diff --git a/backend/ee/onyx/db/license.py b/backend/ee/onyx/db/license.py
index 85b79060215..97bdc03aafa 100644
--- a/backend/ee/onyx/db/license.py
+++ b/backend/ee/onyx/db/license.py
@@ -11,11 +11,10 @@
 from ee.onyx.server.license.models import LicensePayload
 from ee.onyx.server.license.models import LicenseSource
 from onyx.auth.schemas import UserRole
+from onyx.cache.factory import get_cache_backend
 from onyx.configs.constants import ANONYMOUS_USER_EMAIL
 from onyx.db.models import License
 from onyx.db.models import User
-from onyx.redis.redis_pool import get_redis_client
-from onyx.redis.redis_pool import get_redis_replica_client
 from onyx.utils.logger import setup_logger
 from shared_configs.configs import MULTI_TENANT
 from shared_configs.contextvars import get_current_tenant_id
@@ -142,7 +141,7 @@ def get_used_seats(tenant_id: str | None = None) -> int:
 
 def get_cached_license_metadata(tenant_id: str | None = None) -> LicenseMetadata | None:
     """
-    Get license metadata from Redis cache.
+    Get license metadata from cache.
 
     Args:
         tenant_id: Tenant ID (for multi-tenant deployments)
@@ -150,38 +149,34 @@ def get_cached_license_metadata(tenant_id: str | None = None) -> LicenseMetadata
     Returns:
         LicenseMetadata if cached, None otherwise
     """
-    tenant = tenant_id or get_current_tenant_id()
-    redis_client = get_redis_replica_client(tenant_id=tenant)
+    cache = get_cache_backend(tenant_id=tenant_id)
+    cached = cache.get(LICENSE_METADATA_KEY)
+    if not cached:
+        return None
 
-    cached = redis_client.get(LICENSE_METADATA_KEY)
-    if cached:
-        try:
-            cached_str: str
-            if isinstance(cached, bytes):
-                cached_str = cached.decode("utf-8")
-            else:
-                cached_str = str(cached)
-            return LicenseMetadata.model_validate_json(cached_str)
-        except Exception as e:
-            logger.warning(f"Failed to parse cached license metadata: {e}")
-            return None
-    return None
+    try:
+        cached_str = (
+            cached.decode("utf-8") if isinstance(cached, bytes) else str(cached)
+        )
+        return LicenseMetadata.model_validate_json(cached_str)
+    except Exception as e:
+        logger.warning(f"Failed to parse cached license metadata: {e}")
+        return None
 
 
 def invalidate_license_cache(tenant_id: str | None = None) -> None:
     """
     Invalidate the license metadata cache (not the license itself).
 
-    This deletes the cached LicenseMetadata from Redis. The actual license
-    in the database is not affected. Redis delete is idempotent - if the
-    key doesn't exist, this is a no-op.
+    Deletes the cached LicenseMetadata. The actual license in the database
+    is not affected. Delete is idempotent — if the key doesn't exist, this
+    is a no-op.
 
     Args:
         tenant_id: Tenant ID (for multi-tenant deployments)
     """
-    tenant = tenant_id or get_current_tenant_id()
-    redis_client = get_redis_client(tenant_id=tenant)
-    redis_client.delete(LICENSE_METADATA_KEY)
+    cache = get_cache_backend(tenant_id=tenant_id)
+    cache.delete(LICENSE_METADATA_KEY)
     logger.info("License cache invalidated")
 
 
@@ -192,7 +187,7 @@ def update_license_cache(
     tenant_id: str | None = None,
 ) -> LicenseMetadata:
     """
-    Update the Redis cache with license metadata.
+    Update the cache with license metadata.
 
     We cache all license statuses (ACTIVE, GRACE_PERIOD, GATED_ACCESS) because:
     1. Frontend needs status to show appropriate UI/banners
@@ -211,7 +206,7 @@ def update_license_cache(
     from ee.onyx.utils.license import get_license_status
 
     tenant = tenant_id or get_current_tenant_id()
-    redis_client = get_redis_client(tenant_id=tenant)
+    cache = get_cache_backend(tenant_id=tenant_id)
 
     used_seats = get_used_seats(tenant)
     status = get_license_status(payload, grace_period_end)
@@ -230,7 +225,7 @@ def update_license_cache(
         stripe_subscription_id=payload.stripe_subscription_id,
     )
 
-    redis_client.set(
+    cache.set(
         LICENSE_METADATA_KEY,
         metadata.model_dump_json(),
         ex=LICENSE_CACHE_TTL_SECONDS,
diff --git a/backend/ee/onyx/server/middleware/license_enforcement.py b/backend/ee/onyx/server/middleware/license_enforcement.py
index 133f598233b..03a73c4367e 100644
--- a/backend/ee/onyx/server/middleware/license_enforcement.py
+++ b/backend/ee/onyx/server/middleware/license_enforcement.py
@@ -46,7 +46,6 @@
 from fastapi import Request
 from fastapi import Response
 from fastapi.responses import JSONResponse
-from redis.exceptions import RedisError
 from sqlalchemy.exc import SQLAlchemyError
 
 from ee.onyx.configs.app_configs import LICENSE_ENFORCEMENT_ENABLED
@@ -56,6 +55,7 @@
 )
 from ee.onyx.db.license import get_cached_license_metadata
 from ee.onyx.db.license import refresh_license_cache
+from onyx.cache.interface import CACHE_TRANSIENT_ERRORS
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.server.settings.models import ApplicationStatus
 from shared_configs.contextvars import get_current_tenant_id
@@ -164,9 +164,9 @@ async def enforce_license(
                     "[license_enforcement] No license, allowing community features"
                 )
                 is_gated = False
-        except RedisError as e:
+        except CACHE_TRANSIENT_ERRORS as e:
             logger.warning(f"Failed to check license metadata: {e}")
-            # Fail open - don't block users due to Redis connectivity issues
+            # Fail open - don't block users due to cache connectivity issues
             is_gated = False
 
         if is_gated:
diff --git a/backend/ee/onyx/server/settings/api.py b/backend/ee/onyx/server/settings/api.py
index 35ce9cb1802..a79eb546291 100644
--- a/backend/ee/onyx/server/settings/api.py
+++ b/backend/ee/onyx/server/settings/api.py
@@ -6,6 +6,7 @@
 from ee.onyx.configs.app_configs import LICENSE_ENFORCEMENT_ENABLED
 from ee.onyx.db.license import get_cached_license_metadata
 from ee.onyx.db.license import refresh_license_cache
+from onyx.cache.interface import CACHE_TRANSIENT_ERRORS
 from onyx.configs.app_configs import ENTERPRISE_EDITION_ENABLED
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.server.settings.models import ApplicationStatus
@@ -125,7 +126,7 @@ def apply_license_status_to_settings(settings: Settings) -> Settings:
                 # syncing) means indexed data may need protection.
                 settings.application_status = _BLOCKING_STATUS
             settings.ee_features_enabled = False
-    except RedisError as e:
+    except CACHE_TRANSIENT_ERRORS as e:
         logger.warning(f"Failed to check license metadata for settings: {e}")
         # Fail closed - disable EE features if we can't verify license
         settings.ee_features_enabled = False
diff --git a/backend/onyx/auth/users.py b/backend/onyx/auth/users.py
index 46733480949..bcb3f891d2c 100644
--- a/backend/onyx/auth/users.py
+++ b/backend/onyx/auth/users.py
@@ -120,7 +120,6 @@
 from onyx.db.pat import fetch_user_for_pat
 from onyx.db.users import get_user_by_email
 from onyx.redis.redis_pool import get_async_redis_connection
-from onyx.redis.redis_pool import get_redis_client
 from onyx.server.settings.store import load_settings
 from onyx.server.utils import BasicAuthenticationError
 from onyx.utils.logger import setup_logger
@@ -201,13 +200,14 @@ def user_needs_to_be_verified() -> bool:
 
 
 def anonymous_user_enabled(*, tenant_id: str | None = None) -> bool:
-    redis_client = get_redis_client(tenant_id=tenant_id)
-    value = redis_client.get(OnyxRedisLocks.ANONYMOUS_USER_ENABLED)
+    from onyx.cache.factory import get_cache_backend
+
+    cache = get_cache_backend(tenant_id=tenant_id)
+    value = cache.get(OnyxRedisLocks.ANONYMOUS_USER_ENABLED)
 
     if value is None:
         return False
 
-    assert isinstance(value, bytes)
     return int(value.decode("utf-8")) == 1
 
 
diff --git a/backend/onyx/cache/interface.py b/backend/onyx/cache/interface.py
index a78532a0187..810d4cece9e 100644
--- a/backend/onyx/cache/interface.py
+++ b/backend/onyx/cache/interface.py
@@ -1,9 +1,20 @@
 import abc
 from enum import Enum
 
+from redis.exceptions import RedisError
+from sqlalchemy.exc import SQLAlchemyError
+
 TTL_KEY_NOT_FOUND = -2
 TTL_NO_EXPIRY = -1
 
+CACHE_TRANSIENT_ERRORS: tuple[type[Exception], ...] = (RedisError, SQLAlchemyError)
+"""Exception types that represent transient cache connectivity / operational
+failures.  Callers that want to fail-open (or fail-closed) on cache errors
+should catch this tuple instead of bare ``Exception``.
+
+When adding a new ``CacheBackend`` implementation, add its transient error
+base class(es) here so all call-sites pick it up automatically."""
+
 
 class CacheBackendType(str, Enum):
     REDIS = "redis"
diff --git a/deployment/docker_compose/docker-compose.no-vectordb.yml b/deployment/docker_compose/docker-compose.onyx-lite.yml
similarity index 55%
rename from deployment/docker_compose/docker-compose.no-vectordb.yml
rename to deployment/docker_compose/docker-compose.onyx-lite.yml
index 1c7fd766280..d6cddc566bf 100644
--- a/deployment/docker_compose/docker-compose.no-vectordb.yml
+++ b/deployment/docker_compose/docker-compose.onyx-lite.yml
@@ -1,30 +1,32 @@
 # =============================================================================
-# ONYX NO-VECTOR-DB OVERLAY
+# ONYX LITE — MINIMAL DEPLOYMENT OVERLAY
 # =============================================================================
-# Overlay to run Onyx without a vector database (Vespa), model servers, or
-# code interpreter. In this mode, connectors and RAG search are disabled, but
-# the core chat experience (LLM conversations, tools, user file uploads,
-# Projects, Agent knowledge) still works.
+# Overlay to run Onyx in a minimal configuration: no vector database (Vespa),
+# no Redis, no model servers, and no background workers. Only PostgreSQL is
+# required. In this mode, connectors and RAG search are disabled, but the core
+# chat experience (LLM conversations, tools, user file uploads, Projects,
+# Agent knowledge, code interpreter) still works.
 #
 # Usage:
-#   docker compose -f docker-compose.yml -f docker-compose.no-vectordb.yml up -d
+#   docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml up -d
 #
 # With dev ports:
-#   docker compose -f docker-compose.yml -f docker-compose.no-vectordb.yml \
+#   docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml \
 #                  -f docker-compose.dev.yml up -d --wait
 #
 # This overlay:
-#   - Moves Vespa (index), both model servers, and code-interpreter to profiles
-#     so they do not start by default
-#   - Moves the background worker to the "background" profile (the API server
-#     handles all background work via FastAPI BackgroundTasks)
-#   - Makes the depends_on references to removed services optional
+#   - Moves Vespa (index), both model servers, code-interpreter, Redis (cache),
+#     and the background worker to profiles so they do not start by default
+#   - Makes depends_on references to removed services optional
 #   - Sets DISABLE_VECTOR_DB=true on the api_server
+#   - Uses PostgreSQL for caching and auth instead of Redis
+#   - Uses PostgreSQL for file storage instead of S3/MinIO
 #
 # To selectively bring services back:
 #   --profile vectordb          Vespa + indexing model server
 #   --profile inference         Inference model server
-#   --profile background        Background worker (Celery)
+#   --profile background        Background worker (Celery) — also needs redis
+#   --profile redis             Redis cache
 #   --profile code-interpreter  Code interpreter
 # =============================================================================
 
@@ -36,6 +38,9 @@ services:
       index:
         condition: service_started
         required: false
+      cache:
+        condition: service_started
+        required: false
       inference_model_server:
         condition: service_started
         required: false
@@ -45,9 +50,11 @@ services:
     environment:
       - DISABLE_VECTOR_DB=true
       - FILE_STORE_BACKEND=postgres
+      - CACHE_BACKEND=postgres
+      - AUTH_BACKEND=postgres
 
   # Move the background worker to a profile so it does not start by default.
-  # The API server handles all background work in NO_VECTOR_DB mode.
+  # The API server handles all background work in lite mode.
   background:
     profiles: ["background"]
     depends_on:
@@ -61,6 +68,11 @@ services:
         condition: service_started
         required: false
 
+  # Move Redis to a profile so it does not start by default.
+  # The Postgres cache backend replaces Redis in lite mode.
+  cache:
+    profiles: ["redis"]
+
   # Move Vespa and indexing model server to a profile so they do not start.
   index:
     profiles: ["vectordb"]
diff --git a/deployment/helm/charts/onyx/values-lite.yaml b/deployment/helm/charts/onyx/values-lite.yaml
new file mode 100644
index 00000000000..68c546c7846
--- /dev/null
+++ b/deployment/helm/charts/onyx/values-lite.yaml
@@ -0,0 +1,31 @@
+# =============================================================================
+# ONYX LITE — MINIMAL DEPLOYMENT VALUES
+# =============================================================================
+# Minimal Onyx deployment: no vector database, no Redis, no model servers.
+# Only PostgreSQL is required. Connectors and RAG search are disabled, but the
+# core chat experience (LLM conversations, tools, user file uploads, Projects,
+# Agent knowledge) still works.
+#
+# Usage:
+#   helm install onyx ./deployment/helm/charts/onyx \
+#     -f ./deployment/helm/charts/onyx/values-lite.yaml
+#
+# Or merged with your own overrides:
+#   helm install onyx ./deployment/helm/charts/onyx \
+#     -f ./deployment/helm/charts/onyx/values-lite.yaml \
+#     -f my-overrides.yaml
+# =============================================================================
+
+vectorDB:
+  enabled: false
+
+vespa:
+  enabled: false
+
+redis:
+  enabled: false
+
+configMap:
+  CACHE_BACKEND: "postgres"
+  AUTH_BACKEND: "postgres"
+  FILE_STORE_BACKEND: "postgres"

From 50575d0f6bbe6518c9753f951562524916c7e459 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Tue, 3 Mar 2026 17:40:34 -0800
Subject: [PATCH 067/267] chore(ui): Rename from LLM Models to Language Models
 (#9007)

---
 web/src/lib/admin-routes.ts                    | 4 ++--
 web/tests/e2e/admin/admin_pages.spec.ts        | 2 +-
 web/tests/e2e/admin/llm_provider_setup.spec.ts | 4 +++-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/web/src/lib/admin-routes.ts b/web/src/lib/admin-routes.ts
index 132617e1d65..619bd2b3b31 100644
--- a/web/src/lib/admin-routes.ts
+++ b/web/src/lib/admin-routes.ts
@@ -150,8 +150,8 @@ export const ADMIN_ROUTE_CONFIG: Record<string, AdminRouteConfig> = {
   },
   [ADMIN_PATHS.LLM_MODELS]: {
     icon: SvgCpu,
-    title: "LLM Models",
-    sidebarLabel: "LLM Models",
+    title: "Language Models",
+    sidebarLabel: "Language Models",
   },
   [ADMIN_PATHS.WEB_SEARCH]: {
     icon: SvgGlobe,
diff --git a/web/tests/e2e/admin/admin_pages.spec.ts b/web/tests/e2e/admin/admin_pages.spec.ts
index e5d95aacd5a..895329f4f65 100644
--- a/web/tests/e2e/admin/admin_pages.spec.ts
+++ b/web/tests/e2e/admin/admin_pages.spec.ts
@@ -78,7 +78,7 @@ const ADMIN_PAGES: AdminPageSnapshot[] = [
   {
     name: "Configuration - LLM",
     path: "configuration/llm",
-    pageTitle: "LLM Models",
+    pageTitle: "Language Models",
   },
   {
     name: "Connectors - Existing Connectors",
diff --git a/web/tests/e2e/admin/llm_provider_setup.spec.ts b/web/tests/e2e/admin/llm_provider_setup.spec.ts
index bf13b5fbfe4..3e84409863f 100644
--- a/web/tests/e2e/admin/llm_provider_setup.spec.ts
+++ b/web/tests/e2e/admin/llm_provider_setup.spec.ts
@@ -121,7 +121,9 @@ test.describe("LLM Provider Setup @exclusive", () => {
     await loginAs(page, "admin");
     await page.goto(LLM_SETUP_URL);
     await page.waitForLoadState("networkidle");
-    await expect(page.getByLabel("admin-page-title")).toHaveText(/^LLM Models/);
+    await expect(page.getByLabel("admin-page-title")).toHaveText(
+      /^Language Models/
+    );
   });
 
   test.afterEach(async ({ page }) => {

From 0dbabfe445b519267ca2f9ce0327e18a6d498dc2 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 3 Mar 2026 17:55:44 -0800
Subject: [PATCH 068/267] feat: Support intermediate code interpreter file
 generation (#9006)

---
 backend/onyx/chat/llm_loop.py                 |   9 +
 backend/onyx/chat/save_chat.py                |  37 ++++
 backend/onyx/tools/models.py                  |   9 +
 .../python/python_tool.py                     |   5 +-
 .../unit/onyx/chat/test_save_chat_files.py    | 178 ++++++++++++++++++
 5 files changed, 237 insertions(+), 1 deletion(-)
 create mode 100644 backend/tests/unit/onyx/chat/test_save_chat_files.py

diff --git a/backend/onyx/chat/llm_loop.py b/backend/onyx/chat/llm_loop.py
index bbe05bb68a6..66bd7e7a817 100644
--- a/backend/onyx/chat/llm_loop.py
+++ b/backend/onyx/chat/llm_loop.py
@@ -52,6 +52,7 @@
 from onyx.tools.interface import Tool
 from onyx.tools.models import ChatFile
 from onyx.tools.models import MemoryToolResponseSnapshot
+from onyx.tools.models import PythonToolRichResponse
 from onyx.tools.models import ToolCallInfo
 from onyx.tools.models import ToolCallKickoff
 from onyx.tools.models import ToolResponse
@@ -966,6 +967,13 @@ def run_llm_loop(
                 ):
                     generated_images = tool_response.rich_response.generated_images
 
+                # Extract generated_files if this is a code interpreter response
+                generated_files = None
+                if isinstance(tool_response.rich_response, PythonToolRichResponse):
+                    generated_files = (
+                        tool_response.rich_response.generated_files or None
+                    )
+
                 # Persist memory if this is a memory tool response
                 memory_snapshot: MemoryToolResponseSnapshot | None = None
                 if isinstance(tool_response.rich_response, MemoryToolResponse):
@@ -1017,6 +1025,7 @@ def run_llm_loop(
                     tool_call_response=saved_response,
                     search_docs=displayed_docs or search_docs,
                     generated_images=generated_images,
+                    generated_files=generated_files,
                 )
                 # Add to state container for partial save support
                 state_container.add_tool_call(tool_call_info)
diff --git a/backend/onyx/chat/save_chat.py b/backend/onyx/chat/save_chat.py
index 4a0dd7a94d8..fcc7eae1275 100644
--- a/backend/onyx/chat/save_chat.py
+++ b/backend/onyx/chat/save_chat.py
@@ -1,4 +1,5 @@
 import json
+import mimetypes
 
 from sqlalchemy.orm import Session
 
@@ -12,14 +13,41 @@
 from onyx.db.models import ChatMessage
 from onyx.db.models import ToolCall
 from onyx.db.tools import create_tool_call_no_commit
+from onyx.file_store.models import FileDescriptor
 from onyx.natural_language_processing.utils import BaseTokenizer
 from onyx.natural_language_processing.utils import get_tokenizer
+from onyx.server.query_and_chat.chat_utils import mime_type_to_chat_file_type
 from onyx.tools.models import ToolCallInfo
 from onyx.utils.logger import setup_logger
 
 logger = setup_logger()
 
 
+def _extract_referenced_file_descriptors(
+    tool_calls: list[ToolCallInfo],
+    message_text: str,
+) -> list[FileDescriptor]:
+    """Extract FileDescriptors for code interpreter files referenced in the message text."""
+    descriptors: list[FileDescriptor] = []
+    for tool_call_info in tool_calls:
+        if not tool_call_info.generated_files:
+            continue
+        for gen_file in tool_call_info.generated_files:
+            file_id = (
+                gen_file.file_link.rsplit("/", 1)[-1] if gen_file.file_link else ""
+            )
+            if file_id and file_id in message_text:
+                mime_type, _ = mimetypes.guess_type(gen_file.filename)
+                descriptors.append(
+                    FileDescriptor(
+                        id=file_id,
+                        type=mime_type_to_chat_file_type(mime_type),
+                        name=gen_file.filename,
+                    )
+                )
+    return descriptors
+
+
 def _create_and_link_tool_calls(
     tool_calls: list[ToolCallInfo],
     assistant_message: ChatMessage,
@@ -297,5 +325,14 @@ def save_chat_turn(
         citation_number_to_search_doc_id if citation_number_to_search_doc_id else None
     )
 
+    # 8. Attach code interpreter generated files that the assistant actually
+    # referenced in its response, so they are available via load_all_chat_files
+    # on subsequent turns. Files not mentioned are intermediate artifacts.
+    if message_text:
+        referenced = _extract_referenced_file_descriptors(tool_calls, message_text)
+        if referenced:
+            existing_files = assistant_message.files or []
+            assistant_message.files = existing_files + referenced
+
     # Finally save the messages, tool calls, and docs
     db_session.commit()
diff --git a/backend/onyx/tools/models.py b/backend/onyx/tools/models.py
index 686b9bf2a69..99962dd2094 100644
--- a/backend/onyx/tools/models.py
+++ b/backend/onyx/tools/models.py
@@ -93,6 +93,8 @@ class ToolResponse(BaseModel):
         # | WebContentResponse
         # This comes from custom tools, tool result needs to be saved
         | CustomToolCallSummary
+        # This comes from code interpreter, carries generated files
+        | PythonToolRichResponse
         # If the rich response is a string, this is what's saved to the tool call in the DB
         | str
         | None  # If nothing needs to be persisted outside of the string value passed to the LLM
@@ -193,6 +195,12 @@ class ChatFile(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
 
+class PythonToolRichResponse(BaseModel):
+    """Rich response from the Python tool carrying generated files."""
+
+    generated_files: list[PythonExecutionFile] = []
+
+
 class PythonToolOverrideKwargs(BaseModel):
     """Override kwargs for the Python/Code Interpreter tool."""
 
@@ -245,6 +253,7 @@ class ToolCallInfo(BaseModel):
     tool_call_response: str
     search_docs: list[SearchDoc] | None = None
     generated_images: list[GeneratedImage] | None = None
+    generated_files: list[PythonExecutionFile] | None = None
 
 
 CHAT_SESSION_ID_PLACEHOLDER = "CHAT_SESSION_ID"
diff --git a/backend/onyx/tools/tool_implementations/python/python_tool.py b/backend/onyx/tools/tool_implementations/python/python_tool.py
index bfeda2255cc..257dff74a68 100644
--- a/backend/onyx/tools/tool_implementations/python/python_tool.py
+++ b/backend/onyx/tools/tool_implementations/python/python_tool.py
@@ -23,6 +23,7 @@
 from onyx.tools.models import LlmPythonExecutionResult
 from onyx.tools.models import PythonExecutionFile
 from onyx.tools.models import PythonToolOverrideKwargs
+from onyx.tools.models import PythonToolRichResponse
 from onyx.tools.models import ToolCallException
 from onyx.tools.models import ToolResponse
 from onyx.tools.tool_implementations.python.code_interpreter_client import (
@@ -329,7 +330,9 @@ def run(
             llm_response = adapter.dump_json(result).decode()
 
             return ToolResponse(
-                rich_response=None,  # No rich response needed for Python tool
+                rich_response=PythonToolRichResponse(
+                    generated_files=generated_files,
+                ),
                 llm_facing_response=llm_response,
             )
 
diff --git a/backend/tests/unit/onyx/chat/test_save_chat_files.py b/backend/tests/unit/onyx/chat/test_save_chat_files.py
new file mode 100644
index 00000000000..fbdca47da17
--- /dev/null
+++ b/backend/tests/unit/onyx/chat/test_save_chat_files.py
@@ -0,0 +1,178 @@
+"""Tests for _extract_referenced_file_descriptors in save_chat.py.
+
+Verifies that only code interpreter generated files actually referenced
+in the assistant's message text are extracted as FileDescriptors for
+cross-turn persistence.
+"""
+
+from onyx.chat.save_chat import _extract_referenced_file_descriptors
+from onyx.file_store.models import ChatFileType
+from onyx.tools.models import PythonExecutionFile
+from onyx.tools.models import ToolCallInfo
+
+
+def _make_tool_call_info(
+    generated_files: list[PythonExecutionFile] | None = None,
+    tool_name: str = "python",
+) -> ToolCallInfo:
+    return ToolCallInfo(
+        parent_tool_call_id=None,
+        turn_index=0,
+        tab_index=0,
+        tool_name=tool_name,
+        tool_call_id="tc_1",
+        tool_id=1,
+        reasoning_tokens=None,
+        tool_call_arguments={"code": "print('hi')"},
+        tool_call_response="{}",
+        generated_files=generated_files,
+    )
+
+
+def test_returns_empty_when_no_generated_files() -> None:
+    tool_call = _make_tool_call_info(generated_files=None)
+    result = _extract_referenced_file_descriptors([tool_call], "some message")
+    assert result == []
+
+
+def test_returns_empty_when_file_not_referenced() -> None:
+    files = [
+        PythonExecutionFile(
+            filename="chart.png",
+            file_link="http://localhost/api/chat/file/abc-123",
+        )
+    ]
+    tool_call = _make_tool_call_info(generated_files=files)
+    result = _extract_referenced_file_descriptors([tool_call], "Here is your answer.")
+    assert result == []
+
+
+def test_extracts_referenced_file() -> None:
+    file_id = "abc-123-def"
+    files = [
+        PythonExecutionFile(
+            filename="chart.png",
+            file_link=f"http://localhost/api/chat/file/{file_id}",
+        )
+    ]
+    tool_call = _make_tool_call_info(generated_files=files)
+    message = (
+        f"Here is the chart: [chart.png](http://localhost/api/chat/file/{file_id})"
+    )
+
+    result = _extract_referenced_file_descriptors([tool_call], message)
+
+    assert len(result) == 1
+    assert result[0]["id"] == file_id
+    assert result[0]["type"] == ChatFileType.IMAGE
+    assert result[0]["name"] == "chart.png"
+
+
+def test_filters_unreferenced_files() -> None:
+    referenced_id = "ref-111"
+    unreferenced_id = "unref-222"
+    files = [
+        PythonExecutionFile(
+            filename="chart.png",
+            file_link=f"http://localhost/api/chat/file/{referenced_id}",
+        ),
+        PythonExecutionFile(
+            filename="data.csv",
+            file_link=f"http://localhost/api/chat/file/{unreferenced_id}",
+        ),
+    ]
+    tool_call = _make_tool_call_info(generated_files=files)
+    message = f"Here is the chart: [chart.png](http://localhost/api/chat/file/{referenced_id})"
+
+    result = _extract_referenced_file_descriptors([tool_call], message)
+
+    assert len(result) == 1
+    assert result[0]["id"] == referenced_id
+    assert result[0]["name"] == "chart.png"
+
+
+def test_extracts_from_multiple_tool_calls() -> None:
+    id_1 = "file-aaa"
+    id_2 = "file-bbb"
+    tc1 = _make_tool_call_info(
+        generated_files=[
+            PythonExecutionFile(
+                filename="plot.png",
+                file_link=f"http://localhost/api/chat/file/{id_1}",
+            )
+        ]
+    )
+    tc2 = _make_tool_call_info(
+        generated_files=[
+            PythonExecutionFile(
+                filename="report.csv",
+                file_link=f"http://localhost/api/chat/file/{id_2}",
+            )
+        ]
+    )
+    message = (
+        f"[plot.png](http://localhost/api/chat/file/{id_1}) "
+        f"and [report.csv](http://localhost/api/chat/file/{id_2})"
+    )
+
+    result = _extract_referenced_file_descriptors([tc1, tc2], message)
+
+    assert len(result) == 2
+    ids = {d["id"] for d in result}
+    assert ids == {id_1, id_2}
+
+
+def test_csv_file_type() -> None:
+    file_id = "csv-123"
+    files = [
+        PythonExecutionFile(
+            filename="data.csv",
+            file_link=f"http://localhost/api/chat/file/{file_id}",
+        )
+    ]
+    tool_call = _make_tool_call_info(generated_files=files)
+    message = f"[data.csv](http://localhost/api/chat/file/{file_id})"
+
+    result = _extract_referenced_file_descriptors([tool_call], message)
+
+    assert len(result) == 1
+    assert result[0]["type"] == ChatFileType.CSV
+
+
+def test_unknown_extension_defaults_to_plain_text() -> None:
+    file_id = "bin-456"
+    files = [
+        PythonExecutionFile(
+            filename="output.xyz",
+            file_link=f"http://localhost/api/chat/file/{file_id}",
+        )
+    ]
+    tool_call = _make_tool_call_info(generated_files=files)
+    message = f"[output.xyz](http://localhost/api/chat/file/{file_id})"
+
+    result = _extract_referenced_file_descriptors([tool_call], message)
+
+    assert len(result) == 1
+    assert result[0]["type"] == ChatFileType.PLAIN_TEXT
+
+
+def test_skips_tool_calls_without_generated_files() -> None:
+    file_id = "img-789"
+    tc_no_files = _make_tool_call_info(generated_files=None)
+    tc_empty = _make_tool_call_info(generated_files=[])
+    tc_with_files = _make_tool_call_info(
+        generated_files=[
+            PythonExecutionFile(
+                filename="result.png",
+                file_link=f"http://localhost/api/chat/file/{file_id}",
+            )
+        ]
+    )
+    message = f"[result.png](http://localhost/api/chat/file/{file_id})"
+
+    result = _extract_referenced_file_descriptors(
+        [tc_no_files, tc_empty, tc_with_files], message
+    )
+
+    assert len(result) == 1
+    assert result[0]["id"] == file_id

From 8ef504acd5859ad257a2a31f859f1e985c6f6986 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Tue, 3 Mar 2026 18:03:38 -0800
Subject: [PATCH 069/267] refactor: add OnyxErrorCode enum and migrate
 billing/license routers (#8975)

---
 AGENTS.md                                     |  39 +++++++
 backend/ee/onyx/server/billing/api.py         | 108 ++++++++----------
 backend/ee/onyx/server/billing/service.py     |  23 ++--
 backend/ee/onyx/server/license/api.py         |  48 ++++----
 backend/ee/onyx/server/tenants/billing_api.py |  56 +++++----
 backend/onyx/error_handling/__init__.py       |   0
 backend/onyx/error_handling/error_codes.py    | 101 ++++++++++++++++
 backend/onyx/error_handling/exceptions.py     |  82 +++++++++++++
 backend/onyx/main.py                          |   3 +
 .../onyx/server/billing/test_billing_api.py   |  94 ++++++++-------
 .../server/billing/test_billing_service.py    |  13 ++-
 .../onyx/server/tenants/test_billing_api.py   |  31 +++--
 .../unit/onyx/error_handling/__init__.py      |   0
 .../onyx/error_handling/test_exceptions.py    |  90 +++++++++++++++
 14 files changed, 511 insertions(+), 177 deletions(-)
 create mode 100644 backend/onyx/error_handling/__init__.py
 create mode 100644 backend/onyx/error_handling/error_codes.py
 create mode 100644 backend/onyx/error_handling/exceptions.py
 create mode 100644 backend/tests/unit/onyx/error_handling/__init__.py
 create mode 100644 backend/tests/unit/onyx/error_handling/test_exceptions.py

diff --git a/AGENTS.md b/AGENTS.md
index 5acea7ecfe5..24ff123383d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -617,6 +617,45 @@ Keep it high level. You can reference certain files or functions though.
 
 Before writing your plan, make sure to do research. Explore the relevant sections in the codebase.
 
+## Error Handling
+
+**Always raise `OnyxError` from `onyx.error_handling.exceptions` instead of `HTTPException`.
+Never hardcode status codes or use `starlette.status` / `fastapi.status` constants directly.**
+
+A global FastAPI exception handler converts `OnyxError` into a JSON response with the standard
+`{"error_code": "...", "message": "..."}` shape. This eliminates boilerplate and keeps error
+handling consistent across the entire backend.
+
+```python
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+
+# ✅ Good
+raise OnyxError(OnyxErrorCode.NOT_FOUND, "Session not found")
+
+# ✅ Good — no extra message needed
+raise OnyxError(OnyxErrorCode.UNAUTHENTICATED)
+
+# ✅ Good — upstream service with dynamic status code
+raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)
+
+# ❌ Bad — using HTTPException directly
+raise HTTPException(status_code=404, detail="Session not found")
+
+# ❌ Bad — starlette constant
+raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+```
+
+Available error codes are defined in `backend/onyx/error_handling/error_codes.py`. If a new error
+category is needed, add it there first — do not invent ad-hoc codes.
+
+**Upstream service errors:** When forwarding errors from an upstream service where the HTTP
+status code is dynamic (comes from the upstream response), use `status_code_override`:
+
+```python
+raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=e.response.status_code)
+```
+
 ## Best Practices
 
 In addition to the other content in this file, best practices for contributing
diff --git a/backend/ee/onyx/server/billing/api.py b/backend/ee/onyx/server/billing/api.py
index a5495bf57d9..96aa3b4a0d0 100644
--- a/backend/ee/onyx/server/billing/api.py
+++ b/backend/ee/onyx/server/billing/api.py
@@ -26,7 +26,6 @@
 import httpx
 from fastapi import APIRouter
 from fastapi import Depends
-from fastapi import HTTPException
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
@@ -42,7 +41,6 @@
 from ee.onyx.server.billing.models import SeatUpdateResponse
 from ee.onyx.server.billing.models import StripePublishableKeyResponse
 from ee.onyx.server.billing.models import SubscriptionStatusResponse
-from ee.onyx.server.billing.service import BillingServiceError
 from ee.onyx.server.billing.service import (
     create_checkout_session as create_checkout_service,
 )
@@ -58,6 +56,8 @@
 from onyx.configs.app_configs import STRIPE_PUBLISHABLE_KEY_URL
 from onyx.configs.app_configs import WEB_DOMAIN
 from onyx.db.engine.sql_engine import get_session
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.redis.redis_pool import get_shared_redis_client
 from onyx.utils.logger import setup_logger
 from shared_configs.configs import MULTI_TENANT
@@ -169,26 +169,23 @@ async def create_checkout_session(
     if seats is not None:
         used_seats = get_used_seats(tenant_id)
         if seats < used_seats:
-            raise HTTPException(
-                status_code=400,
-                detail=f"Cannot subscribe with fewer seats than current usage. "
+            raise OnyxError(
+                OnyxErrorCode.VALIDATION_ERROR,
+                f"Cannot subscribe with fewer seats than current usage. "
                 f"You have {used_seats} active users/integrations but requested {seats} seats.",
             )
 
     # Build redirect URL for after checkout completion
     redirect_url = f"{WEB_DOMAIN}/admin/billing?checkout=success"
 
-    try:
-        return await create_checkout_service(
-            billing_period=billing_period,
-            seats=seats,
-            email=email,
-            license_data=license_data,
-            redirect_url=redirect_url,
-            tenant_id=tenant_id,
-        )
-    except BillingServiceError as e:
-        raise HTTPException(status_code=e.status_code, detail=e.message)
+    return await create_checkout_service(
+        billing_period=billing_period,
+        seats=seats,
+        email=email,
+        license_data=license_data,
+        redirect_url=redirect_url,
+        tenant_id=tenant_id,
+    )
 
 
 @router.post("/create-customer-portal-session")
@@ -206,18 +203,15 @@ async def create_customer_portal_session(
 
     # Self-hosted requires license
     if not MULTI_TENANT and not license_data:
-        raise HTTPException(status_code=400, detail="No license found")
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, "No license found")
 
     return_url = request.return_url if request else f"{WEB_DOMAIN}/admin/billing"
 
-    try:
-        return await create_portal_service(
-            license_data=license_data,
-            return_url=return_url,
-            tenant_id=tenant_id,
-        )
-    except BillingServiceError as e:
-        raise HTTPException(status_code=e.status_code, detail=e.message)
+    return await create_portal_service(
+        license_data=license_data,
+        return_url=return_url,
+        tenant_id=tenant_id,
+    )
 
 
 @router.get("/billing-information")
@@ -240,9 +234,9 @@ async def get_billing_information(
 
     # Check circuit breaker (self-hosted only)
     if _is_billing_circuit_open():
-        raise HTTPException(
-            status_code=503,
-            detail="Stripe connection temporarily disabled. Click 'Connect to Stripe' to retry.",
+        raise OnyxError(
+            OnyxErrorCode.SERVICE_UNAVAILABLE,
+            "Stripe connection temporarily disabled. Click 'Connect to Stripe' to retry.",
         )
 
     try:
@@ -250,11 +244,11 @@ async def get_billing_information(
             license_data=license_data,
             tenant_id=tenant_id,
         )
-    except BillingServiceError as e:
+    except OnyxError as e:
         # Open circuit breaker on connection failures (self-hosted only)
         if e.status_code in (502, 503, 504):
             _open_billing_circuit()
-        raise HTTPException(status_code=e.status_code, detail=e.message)
+        raise
 
 
 @router.post("/seats/update")
@@ -274,31 +268,25 @@ async def update_seats(
 
     # Self-hosted requires license
     if not MULTI_TENANT and not license_data:
-        raise HTTPException(status_code=400, detail="No license found")
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, "No license found")
 
     # Validate that new seat count is not less than current used seats
     used_seats = get_used_seats(tenant_id)
     if request.new_seat_count < used_seats:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Cannot reduce seats below current usage. "
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            f"Cannot reduce seats below current usage. "
             f"You have {used_seats} active users/integrations but requested {request.new_seat_count} seats.",
         )
 
-    try:
-        result = await update_seat_service(
-            new_seat_count=request.new_seat_count,
-            license_data=license_data,
-            tenant_id=tenant_id,
-        )
-
-        # Note: Don't store license here - the control plane may still be processing
-        # the subscription update. The frontend should call /license/claim after a
-        # short delay to get the freshly generated license.
-
-        return result
-    except BillingServiceError as e:
-        raise HTTPException(status_code=e.status_code, detail=e.message)
+    # Note: Don't store license here - the control plane may still be processing
+    # the subscription update. The frontend should call /license/claim after a
+    # short delay to get the freshly generated license.
+    return await update_seat_service(
+        new_seat_count=request.new_seat_count,
+        license_data=license_data,
+        tenant_id=tenant_id,
+    )
 
 
 @router.get("/stripe-publishable-key")
@@ -329,18 +317,18 @@ async def get_stripe_publishable_key() -> StripePublishableKeyResponse:
         if STRIPE_PUBLISHABLE_KEY_OVERRIDE:
             key = STRIPE_PUBLISHABLE_KEY_OVERRIDE.strip()
             if not key.startswith("pk_"):
-                raise HTTPException(
-                    status_code=500,
-                    detail="Invalid Stripe publishable key format",
+                raise OnyxError(
+                    OnyxErrorCode.INTERNAL_ERROR,
+                    "Invalid Stripe publishable key format",
                 )
             _stripe_publishable_key_cache = key
             return StripePublishableKeyResponse(publishable_key=key)
 
         # Fall back to S3 bucket
         if not STRIPE_PUBLISHABLE_KEY_URL:
-            raise HTTPException(
-                status_code=500,
-                detail="Stripe publishable key is not configured",
+            raise OnyxError(
+                OnyxErrorCode.INTERNAL_ERROR,
+                "Stripe publishable key is not configured",
             )
 
         try:
@@ -351,17 +339,17 @@ async def get_stripe_publishable_key() -> StripePublishableKeyResponse:
 
                 # Validate key format
                 if not key.startswith("pk_"):
-                    raise HTTPException(
-                        status_code=500,
-                        detail="Invalid Stripe publishable key format",
+                    raise OnyxError(
+                        OnyxErrorCode.INTERNAL_ERROR,
+                        "Invalid Stripe publishable key format",
                     )
 
                 _stripe_publishable_key_cache = key
                 return StripePublishableKeyResponse(publishable_key=key)
         except httpx.HTTPError:
-            raise HTTPException(
-                status_code=500,
-                detail="Failed to fetch Stripe publishable key",
+            raise OnyxError(
+                OnyxErrorCode.INTERNAL_ERROR,
+                "Failed to fetch Stripe publishable key",
             )
 
 
diff --git a/backend/ee/onyx/server/billing/service.py b/backend/ee/onyx/server/billing/service.py
index 041a975d0af..941e96cc7e6 100644
--- a/backend/ee/onyx/server/billing/service.py
+++ b/backend/ee/onyx/server/billing/service.py
@@ -22,6 +22,8 @@
 from ee.onyx.server.billing.models import SubscriptionStatusResponse
 from ee.onyx.server.tenants.access import generate_data_plane_token
 from onyx.configs.app_configs import CONTROL_PLANE_API_BASE_URL
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.utils.logger import setup_logger
 from shared_configs.configs import MULTI_TENANT
 
@@ -31,15 +33,6 @@
 _REQUEST_TIMEOUT = 30.0
 
 
-class BillingServiceError(Exception):
-    """Exception raised for billing service errors."""
-
-    def __init__(self, message: str, status_code: int = 500):
-        self.message = message
-        self.status_code = status_code
-        super().__init__(self.message)
-
-
 def _get_proxy_headers(license_data: str | None) -> dict[str, str]:
     """Build headers for proxy requests (self-hosted).
 
@@ -101,7 +94,7 @@ async def _make_billing_request(
         Response JSON as dict
 
     Raises:
-        BillingServiceError: If request fails
+        OnyxError: If request fails
     """
 
     base_url = _get_base_url()
@@ -128,11 +121,17 @@ async def _make_billing_request(
         except Exception:
             pass
         logger.error(f"{error_message}: {e.response.status_code} - {detail}")
-        raise BillingServiceError(detail, e.response.status_code)
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            detail,
+            status_code_override=e.response.status_code,
+        )
 
     except httpx.RequestError:
         logger.exception("Failed to connect to billing service")
-        raise BillingServiceError("Failed to connect to billing service", 502)
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY, "Failed to connect to billing service"
+        )
 
 
 async def create_checkout_session(
diff --git a/backend/ee/onyx/server/license/api.py b/backend/ee/onyx/server/license/api.py
index 416b13cb5a3..5c16f4e3192 100644
--- a/backend/ee/onyx/server/license/api.py
+++ b/backend/ee/onyx/server/license/api.py
@@ -14,7 +14,6 @@
 from fastapi import APIRouter
 from fastapi import Depends
 from fastapi import File
-from fastapi import HTTPException
 from fastapi import UploadFile
 from sqlalchemy.orm import Session
 
@@ -35,6 +34,8 @@
 from ee.onyx.utils.license import verify_license_signature
 from onyx.auth.users import User
 from onyx.db.engine.sql_engine import get_session
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.utils.logger import setup_logger
 from shared_configs.configs import MULTI_TENANT
 
@@ -127,9 +128,9 @@ async def claim_license(
     2. Without session_id: Re-claim using existing license for auth
     """
     if MULTI_TENANT:
-        raise HTTPException(
-            status_code=400,
-            detail="License claiming is only available for self-hosted deployments",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "License claiming is only available for self-hosted deployments",
         )
 
     try:
@@ -146,15 +147,16 @@ async def claim_license(
             # Re-claim using existing license for auth
             metadata = get_license_metadata(db_session)
             if not metadata or not metadata.tenant_id:
-                raise HTTPException(
-                    status_code=400,
-                    detail="No license found. Provide session_id after checkout.",
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    "No license found. Provide session_id after checkout.",
                 )
 
             license_row = get_license(db_session)
             if not license_row or not license_row.license_data:
-                raise HTTPException(
-                    status_code=400, detail="No license found in database"
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    "No license found in database",
                 )
 
             url = f"{CLOUD_DATA_PLANE_URL}/proxy/license/{metadata.tenant_id}"
@@ -173,7 +175,7 @@ async def claim_license(
         license_data = data.get("license")
 
         if not license_data:
-            raise HTTPException(status_code=404, detail="No license in response")
+            raise OnyxError(OnyxErrorCode.NOT_FOUND, "No license in response")
 
         # Verify signature before persisting
         payload = verify_license_signature(license_data)
@@ -199,12 +201,14 @@ async def claim_license(
             detail = error_data.get("detail", detail)
         except Exception:
             pass
-        raise HTTPException(status_code=status_code, detail=detail)
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=status_code
+        )
     except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, str(e))
     except requests.RequestException:
-        raise HTTPException(
-            status_code=502, detail="Failed to connect to license server"
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY, "Failed to connect to license server"
         )
 
 
@@ -221,9 +225,9 @@ async def upload_license(
     The license file must be cryptographically signed by Onyx.
     """
     if MULTI_TENANT:
-        raise HTTPException(
-            status_code=400,
-            detail="License upload is only available for self-hosted deployments",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "License upload is only available for self-hosted deployments",
         )
 
     try:
@@ -234,14 +238,14 @@ async def upload_license(
         # Remove any stray whitespace/newlines from user input
         license_data = license_data.strip()
     except UnicodeDecodeError:
-        raise HTTPException(status_code=400, detail="Invalid license file format")
+        raise OnyxError(OnyxErrorCode.INVALID_INPUT, "Invalid license file format")
 
     # Verify cryptographic signature - this is the only validation needed
     # The license's tenant_id identifies the customer in control plane, not locally
     try:
         payload = verify_license_signature(license_data)
     except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, str(e))
 
     # Persist to DB and update cache
     upsert_license(db_session, license_data)
@@ -297,9 +301,9 @@ async def delete_license(
     Admin only - removes license from database and invalidates cache.
     """
     if MULTI_TENANT:
-        raise HTTPException(
-            status_code=400,
-            detail="License deletion is only available for self-hosted deployments",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "License deletion is only available for self-hosted deployments",
         )
 
     try:
diff --git a/backend/ee/onyx/server/tenants/billing_api.py b/backend/ee/onyx/server/tenants/billing_api.py
index c357215681c..63018462261 100644
--- a/backend/ee/onyx/server/tenants/billing_api.py
+++ b/backend/ee/onyx/server/tenants/billing_api.py
@@ -21,7 +21,6 @@
 import httpx
 from fastapi import APIRouter
 from fastapi import Depends
-from fastapi import HTTPException
 
 from ee.onyx.auth.users import current_admin_user
 from ee.onyx.server.tenants.access import control_plane_dep
@@ -43,6 +42,8 @@
 from onyx.configs.app_configs import STRIPE_PUBLISHABLE_KEY_OVERRIDE
 from onyx.configs.app_configs import STRIPE_PUBLISHABLE_KEY_URL
 from onyx.configs.app_configs import WEB_DOMAIN
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.utils.logger import setup_logger
 from shared_configs.contextvars import CURRENT_TENANT_ID_CONTEXTVAR
 from shared_configs.contextvars import get_current_tenant_id
@@ -116,9 +117,14 @@ async def create_customer_portal_session(
     try:
         portal_url = fetch_customer_portal_session(tenant_id, return_url)
         return {"stripe_customer_portal_url": portal_url}
-    except Exception as e:
+    except OnyxError:
+        raise
+    except Exception:
         logger.exception("Failed to create customer portal session")
-        raise HTTPException(status_code=500, detail=str(e))
+        raise OnyxError(
+            OnyxErrorCode.INTERNAL_ERROR,
+            "Failed to create customer portal session",
+        )
 
 
 @router.post("/create-checkout-session")
@@ -134,9 +140,14 @@ async def create_checkout_session(
     try:
         checkout_url = fetch_stripe_checkout_session(tenant_id, billing_period, seats)
         return {"stripe_checkout_url": checkout_url}
-    except Exception as e:
+    except OnyxError:
+        raise
+    except Exception:
         logger.exception("Failed to create checkout session")
-        raise HTTPException(status_code=500, detail=str(e))
+        raise OnyxError(
+            OnyxErrorCode.INTERNAL_ERROR,
+            "Failed to create checkout session",
+        )
 
 
 @router.post("/create-subscription-session")
@@ -147,15 +158,20 @@ async def create_subscription_session(
     try:
         tenant_id = CURRENT_TENANT_ID_CONTEXTVAR.get()
         if not tenant_id:
-            raise HTTPException(status_code=400, detail="Tenant ID not found")
+            raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, "Tenant ID not found")
 
         billing_period = request.billing_period if request else "monthly"
         session_id = fetch_stripe_checkout_session(tenant_id, billing_period)
         return SubscriptionSessionResponse(sessionId=session_id)
 
-    except Exception as e:
+    except OnyxError:
+        raise
+    except Exception:
         logger.exception("Failed to create subscription session")
-        raise HTTPException(status_code=500, detail=str(e))
+        raise OnyxError(
+            OnyxErrorCode.INTERNAL_ERROR,
+            "Failed to create subscription session",
+        )
 
 
 @router.get("/stripe-publishable-key")
@@ -186,18 +202,18 @@ async def get_stripe_publishable_key() -> StripePublishableKeyResponse:
         if STRIPE_PUBLISHABLE_KEY_OVERRIDE:
             key = STRIPE_PUBLISHABLE_KEY_OVERRIDE.strip()
             if not key.startswith("pk_"):
-                raise HTTPException(
-                    status_code=500,
-                    detail="Invalid Stripe publishable key format",
+                raise OnyxError(
+                    OnyxErrorCode.INTERNAL_ERROR,
+                    "Invalid Stripe publishable key format",
                 )
             _stripe_publishable_key_cache = key
             return StripePublishableKeyResponse(publishable_key=key)
 
         # Fall back to S3 bucket
         if not STRIPE_PUBLISHABLE_KEY_URL:
-            raise HTTPException(
-                status_code=500,
-                detail="Stripe publishable key is not configured",
+            raise OnyxError(
+                OnyxErrorCode.INTERNAL_ERROR,
+                "Stripe publishable key is not configured",
             )
 
         try:
@@ -208,15 +224,15 @@ async def get_stripe_publishable_key() -> StripePublishableKeyResponse:
 
                 # Validate key format
                 if not key.startswith("pk_"):
-                    raise HTTPException(
-                        status_code=500,
-                        detail="Invalid Stripe publishable key format",
+                    raise OnyxError(
+                        OnyxErrorCode.INTERNAL_ERROR,
+                        "Invalid Stripe publishable key format",
                     )
 
                 _stripe_publishable_key_cache = key
                 return StripePublishableKeyResponse(publishable_key=key)
         except httpx.HTTPError:
-            raise HTTPException(
-                status_code=500,
-                detail="Failed to fetch Stripe publishable key",
+            raise OnyxError(
+                OnyxErrorCode.INTERNAL_ERROR,
+                "Failed to fetch Stripe publishable key",
             )
diff --git a/backend/onyx/error_handling/__init__.py b/backend/onyx/error_handling/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/backend/onyx/error_handling/error_codes.py b/backend/onyx/error_handling/error_codes.py
new file mode 100644
index 00000000000..035797722e2
--- /dev/null
+++ b/backend/onyx/error_handling/error_codes.py
@@ -0,0 +1,101 @@
+"""
+Standardized error codes for the Onyx backend.
+
+Usage:
+    from onyx.error_handling.error_codes import OnyxErrorCode
+    from onyx.error_handling.exceptions import OnyxError
+
+    raise OnyxError(OnyxErrorCode.UNAUTHENTICATED, "Token expired")
+"""
+
+from enum import Enum
+
+
+class OnyxErrorCode(Enum):
+    """
+    Each member is a tuple of (error_code_string, http_status_code).
+
+    The error_code_string is a stable, machine-readable identifier that
+    API consumers can match on. The http_status_code is the default HTTP
+    status to return.
+    """
+
+    # ------------------------------------------------------------------
+    # Authentication (401)
+    # ------------------------------------------------------------------
+    UNAUTHENTICATED = ("UNAUTHENTICATED", 401)
+    INVALID_TOKEN = ("INVALID_TOKEN", 401)
+    TOKEN_EXPIRED = ("TOKEN_EXPIRED", 401)
+    CSRF_FAILURE = ("CSRF_FAILURE", 403)
+
+    # ------------------------------------------------------------------
+    # Authorization (403)
+    # ------------------------------------------------------------------
+    UNAUTHORIZED = ("UNAUTHORIZED", 403)
+    INSUFFICIENT_PERMISSIONS = ("INSUFFICIENT_PERMISSIONS", 403)
+    ADMIN_ONLY = ("ADMIN_ONLY", 403)
+    EE_REQUIRED = ("EE_REQUIRED", 403)
+
+    # ------------------------------------------------------------------
+    # Validation / Bad Request (400)
+    # ------------------------------------------------------------------
+    VALIDATION_ERROR = ("VALIDATION_ERROR", 400)
+    INVALID_INPUT = ("INVALID_INPUT", 400)
+    MISSING_REQUIRED_FIELD = ("MISSING_REQUIRED_FIELD", 400)
+
+    # ------------------------------------------------------------------
+    # Not Found (404)
+    # ------------------------------------------------------------------
+    NOT_FOUND = ("NOT_FOUND", 404)
+    CONNECTOR_NOT_FOUND = ("CONNECTOR_NOT_FOUND", 404)
+    CREDENTIAL_NOT_FOUND = ("CREDENTIAL_NOT_FOUND", 404)
+    PERSONA_NOT_FOUND = ("PERSONA_NOT_FOUND", 404)
+    DOCUMENT_NOT_FOUND = ("DOCUMENT_NOT_FOUND", 404)
+    SESSION_NOT_FOUND = ("SESSION_NOT_FOUND", 404)
+    USER_NOT_FOUND = ("USER_NOT_FOUND", 404)
+
+    # ------------------------------------------------------------------
+    # Conflict (409)
+    # ------------------------------------------------------------------
+    CONFLICT = ("CONFLICT", 409)
+    DUPLICATE_RESOURCE = ("DUPLICATE_RESOURCE", 409)
+
+    # ------------------------------------------------------------------
+    # Rate Limiting / Quotas (429 / 402)
+    # ------------------------------------------------------------------
+    RATE_LIMITED = ("RATE_LIMITED", 429)
+    SEAT_LIMIT_EXCEEDED = ("SEAT_LIMIT_EXCEEDED", 402)
+
+    # ------------------------------------------------------------------
+    # Connector / Credential Errors (400-range)
+    # ------------------------------------------------------------------
+    CONNECTOR_VALIDATION_FAILED = ("CONNECTOR_VALIDATION_FAILED", 400)
+    CREDENTIAL_INVALID = ("CREDENTIAL_INVALID", 400)
+    CREDENTIAL_EXPIRED = ("CREDENTIAL_EXPIRED", 401)
+
+    # ------------------------------------------------------------------
+    # Server Errors (5xx)
+    # ------------------------------------------------------------------
+    INTERNAL_ERROR = ("INTERNAL_ERROR", 500)
+    NOT_IMPLEMENTED = ("NOT_IMPLEMENTED", 501)
+    SERVICE_UNAVAILABLE = ("SERVICE_UNAVAILABLE", 503)
+    BAD_GATEWAY = ("BAD_GATEWAY", 502)
+    LLM_PROVIDER_ERROR = ("LLM_PROVIDER_ERROR", 502)
+    GATEWAY_TIMEOUT = ("GATEWAY_TIMEOUT", 504)
+
+    def __init__(self, code: str, status_code: int) -> None:
+        self.code = code
+        self.status_code = status_code
+
+    def detail(self, message: str | None = None) -> dict[str, str]:
+        """Build a structured error detail dict.
+
+        Returns a dict like:
+            {"error_code": "UNAUTHENTICATED", "message": "Token expired"}
+
+        If no message is supplied, the error code itself is used as the message.
+        """
+        return {
+            "error_code": self.code,
+            "message": message or self.code,
+        }
diff --git a/backend/onyx/error_handling/exceptions.py b/backend/onyx/error_handling/exceptions.py
new file mode 100644
index 00000000000..63338210c47
--- /dev/null
+++ b/backend/onyx/error_handling/exceptions.py
@@ -0,0 +1,82 @@
+"""OnyxError — the single exception type for all Onyx business errors.
+
+Raise ``OnyxError`` instead of ``HTTPException`` in business code.  A global
+FastAPI exception handler (registered via ``register_onyx_exception_handlers``)
+converts it into a JSON response with the standard
+``{"error_code": "...", "message": "..."}`` shape.
+
+Usage::
+
+    from onyx.error_handling.error_codes import OnyxErrorCode
+    from onyx.error_handling.exceptions import OnyxError
+
+    raise OnyxError(OnyxErrorCode.NOT_FOUND, "Session not found")
+
+For upstream errors with a dynamic HTTP status (e.g. billing service),
+use ``status_code_override``::
+
+    raise OnyxError(
+        OnyxErrorCode.BAD_GATEWAY,
+        detail,
+        status_code_override=upstream_status,
+    )
+"""
+
+from fastapi import FastAPI
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.utils.logger import setup_logger
+
+logger = setup_logger()
+
+
+class OnyxError(Exception):
+    """Structured error that maps to a specific ``OnyxErrorCode``.
+
+    Attributes:
+        error_code: The ``OnyxErrorCode`` enum member.
+        message: Human-readable message (defaults to the error code string).
+        status_code: HTTP status — either overridden or from the error code.
+    """
+
+    def __init__(
+        self,
+        error_code: OnyxErrorCode,
+        message: str | None = None,
+        *,
+        status_code_override: int | None = None,
+    ) -> None:
+        self.error_code = error_code
+        self.message = message or error_code.code
+        self._status_code_override = status_code_override
+        super().__init__(self.message)
+
+    @property
+    def status_code(self) -> int:
+        return self._status_code_override or self.error_code.status_code
+
+
+def register_onyx_exception_handlers(app: FastAPI) -> None:
+    """Register a global handler that converts ``OnyxError`` to JSON responses.
+
+    Must be called *after* the app is created but *before* it starts serving.
+    The handler logs at WARNING for 4xx and ERROR for 5xx.
+    """
+
+    @app.exception_handler(OnyxError)
+    async def _handle_onyx_error(
+        request: Request,  # noqa: ARG001
+        exc: OnyxError,
+    ) -> JSONResponse:
+        status_code = exc.status_code
+        if status_code >= 500:
+            logger.error(f"OnyxError {exc.error_code.code}: {exc.message}")
+        elif status_code >= 400:
+            logger.warning(f"OnyxError {exc.error_code.code}: {exc.message}")
+
+        return JSONResponse(
+            status_code=status_code,
+            content=exc.error_code.detail(exc.message),
+        )
diff --git a/backend/onyx/main.py b/backend/onyx/main.py
index 078e11652b5..f457159695c 100644
--- a/backend/onyx/main.py
+++ b/backend/onyx/main.py
@@ -59,6 +59,7 @@
 from onyx.db.engine.connection_warmup import warm_up_connections
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.engine.sql_engine import SqlEngine
+from onyx.error_handling.exceptions import register_onyx_exception_handlers
 from onyx.file_store.file_store import get_default_file_store
 from onyx.server.api_key.api import router as api_key_router
 from onyx.server.auth_check import check_router_auth
@@ -444,6 +445,8 @@ def get_application(lifespan_override: Lifespan | None = None) -> FastAPI:
         status.HTTP_500_INTERNAL_SERVER_ERROR, log_http_error
     )
 
+    register_onyx_exception_handlers(application)
+
     include_router_with_global_prefix_prepended(application, password_router)
     include_router_with_global_prefix_prepended(application, chat_router)
     include_router_with_global_prefix_prepended(application, query_router)
diff --git a/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py b/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
index f889099441e..cda9fa9dd83 100644
--- a/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
+++ b/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
@@ -11,7 +11,8 @@
 from ee.onyx.server.billing.models import CreateCustomerPortalSessionResponse
 from ee.onyx.server.billing.models import SeatUpdateResponse
 from ee.onyx.server.billing.models import SubscriptionStatusResponse
-from ee.onyx.server.billing.service import BillingServiceError
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 
 
 class TestCreateCheckoutSession:
@@ -88,22 +89,25 @@ async def test_raises_on_service_error(
         mock_get_tenant: MagicMock,
         mock_service: AsyncMock,
     ) -> None:
-        """Should raise HTTPException when service fails."""
-        from fastapi import HTTPException
-
+        """Should propagate OnyxError when service fails."""
         from ee.onyx.server.billing.api import create_checkout_session
 
         mock_get_license.return_value = None
         mock_get_tenant.return_value = "tenant_123"
-        mock_service.side_effect = BillingServiceError("Stripe error", 502)
+        mock_service.side_effect = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Stripe error",
+            status_code_override=502,
+        )
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await create_checkout_session(
                 request=None, _=MagicMock(), db_session=MagicMock()
             )
 
         assert exc_info.value.status_code == 502
-        assert "Stripe error" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
+        assert exc_info.value.message == "Stripe error"
 
 
 class TestCreateCustomerPortalSession:
@@ -121,20 +125,19 @@ async def test_requires_license_for_self_hosted(
         mock_service: AsyncMock,  # noqa: ARG002
     ) -> None:
         """Should reject self-hosted without license."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import create_customer_portal_session
 
         mock_get_license.return_value = None
         mock_get_tenant.return_value = None
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await create_customer_portal_session(
                 request=None, _=MagicMock(), db_session=MagicMock()
             )
 
         assert exc_info.value.status_code == 400
-        assert "No license found" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.VALIDATION_ERROR
+        assert exc_info.value.message == "No license found"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.api.create_portal_service")
@@ -227,8 +230,6 @@ async def test_requires_license_for_self_hosted(
         mock_get_tenant: MagicMock,
     ) -> None:
         """Should reject self-hosted without license."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import update_seats
         from ee.onyx.server.billing.models import SeatUpdateRequest
 
@@ -237,11 +238,12 @@ async def test_requires_license_for_self_hosted(
 
         request = SeatUpdateRequest(new_seat_count=10)
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await update_seats(request=request, _=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 400
-        assert "No license found" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.VALIDATION_ERROR
+        assert exc_info.value.message == "No license found"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.api.get_used_seats")
@@ -295,26 +297,27 @@ async def test_handles_billing_service_error(
         mock_service: AsyncMock,
         mock_get_used_seats: MagicMock,
     ) -> None:
-        """Should convert BillingServiceError to HTTPException."""
-        from fastapi import HTTPException
-
+        """Should propagate OnyxError from service layer."""
         from ee.onyx.server.billing.api import update_seats
         from ee.onyx.server.billing.models import SeatUpdateRequest
 
         mock_get_license.return_value = "license_blob"
         mock_get_tenant.return_value = None
         mock_get_used_seats.return_value = 0
-        mock_service.side_effect = BillingServiceError(
-            "Cannot reduce below 10 seats", 400
+        mock_service.side_effect = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Cannot reduce below 10 seats",
+            status_code_override=400,
         )
 
         request = SeatUpdateRequest(new_seat_count=5)
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await update_seats(request=request, _=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 400
-        assert "Cannot reduce below 10 seats" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
+        assert exc_info.value.message == "Cannot reduce below 10 seats"
 
 
 class TestCircuitBreaker:
@@ -332,19 +335,18 @@ async def test_returns_503_when_circuit_open(
         mock_circuit_open: MagicMock,
     ) -> None:
         """Should return 503 when circuit breaker is open."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import get_billing_information
 
         mock_get_license.return_value = "license_blob"
         mock_get_tenant.return_value = None
         mock_circuit_open.return_value = True
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_billing_information(_=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 503
-        assert "Connect to Stripe" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.SERVICE_UNAVAILABLE
+        assert "Connect to Stripe" in exc_info.value.message
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.api.MULTI_TENANT", False)
@@ -362,16 +364,18 @@ async def test_opens_circuit_on_502_error(
         mock_open_circuit: MagicMock,
     ) -> None:
         """Should open circuit breaker on 502 error."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import get_billing_information
 
         mock_get_license.return_value = "license_blob"
         mock_get_tenant.return_value = None
         mock_circuit_open_check.return_value = False
-        mock_service.side_effect = BillingServiceError("Connection failed", 502)
+        mock_service.side_effect = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Connection failed",
+            status_code_override=502,
+        )
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_billing_information(_=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 502
@@ -393,16 +397,18 @@ async def test_opens_circuit_on_503_error(
         mock_open_circuit: MagicMock,
     ) -> None:
         """Should open circuit breaker on 503 error."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import get_billing_information
 
         mock_get_license.return_value = "license_blob"
         mock_get_tenant.return_value = None
         mock_circuit_open_check.return_value = False
-        mock_service.side_effect = BillingServiceError("Service unavailable", 503)
+        mock_service.side_effect = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Service unavailable",
+            status_code_override=503,
+        )
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_billing_information(_=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 503
@@ -424,16 +430,18 @@ async def test_opens_circuit_on_504_error(
         mock_open_circuit: MagicMock,
     ) -> None:
         """Should open circuit breaker on 504 error."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import get_billing_information
 
         mock_get_license.return_value = "license_blob"
         mock_get_tenant.return_value = None
         mock_circuit_open_check.return_value = False
-        mock_service.side_effect = BillingServiceError("Gateway timeout", 504)
+        mock_service.side_effect = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Gateway timeout",
+            status_code_override=504,
+        )
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_billing_information(_=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 504
@@ -455,16 +463,18 @@ async def test_does_not_open_circuit_on_400_error(
         mock_open_circuit: MagicMock,
     ) -> None:
         """Should NOT open circuit breaker on 400 error (client error)."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.billing.api import get_billing_information
 
         mock_get_license.return_value = "license_blob"
         mock_get_tenant.return_value = None
         mock_circuit_open_check.return_value = False
-        mock_service.side_effect = BillingServiceError("Bad request", 400)
+        mock_service.side_effect = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Bad request",
+            status_code_override=400,
+        )
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_billing_information(_=MagicMock(), db_session=MagicMock())
 
         assert exc_info.value.status_code == 400
diff --git a/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py b/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
index aa2bfdd217d..1376839b205 100644
--- a/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
+++ b/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
@@ -14,7 +14,8 @@
 from ee.onyx.server.billing.models import CreateCustomerPortalSessionResponse
 from ee.onyx.server.billing.models import SeatUpdateResponse
 from ee.onyx.server.billing.models import SubscriptionStatusResponse
-from ee.onyx.server.billing.service import BillingServiceError
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 
 
 class TestMakeBillingRequest:
@@ -78,7 +79,7 @@ async def test_raises_on_http_error(
         mock_base_url: MagicMock,
         mock_headers: MagicMock,
     ) -> None:
-        """Should raise BillingServiceError on HTTP error."""
+        """Should raise OnyxError on HTTP error."""
         from ee.onyx.server.billing.service import _make_billing_request
 
         mock_base_url.return_value = "https://api.example.com"
@@ -91,7 +92,7 @@ async def test_raises_on_http_error(
         mock_client = make_mock_http_client("post", side_effect=error)
 
         with patch("httpx.AsyncClient", mock_client):
-            with pytest.raises(BillingServiceError) as exc_info:
+            with pytest.raises(OnyxError) as exc_info:
                 await _make_billing_request(
                     method="POST",
                     path="/test",
@@ -99,6 +100,7 @@ async def test_raises_on_http_error(
                 )
 
         assert exc_info.value.status_code == 400
+        assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
         assert "Bad request" in exc_info.value.message
 
     @pytest.mark.asyncio
@@ -136,7 +138,7 @@ async def test_raises_on_connection_error(
         mock_base_url: MagicMock,
         mock_headers: MagicMock,
     ) -> None:
-        """Should raise BillingServiceError on connection error."""
+        """Should raise OnyxError on connection error."""
         from ee.onyx.server.billing.service import _make_billing_request
 
         mock_base_url.return_value = "https://api.example.com"
@@ -145,10 +147,11 @@ async def test_raises_on_connection_error(
         mock_client = make_mock_http_client("post", side_effect=error)
 
         with patch("httpx.AsyncClient", mock_client):
-            with pytest.raises(BillingServiceError) as exc_info:
+            with pytest.raises(OnyxError) as exc_info:
                 await _make_billing_request(method="POST", path="/test")
 
         assert exc_info.value.status_code == 502
+        assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
         assert "Failed to connect" in exc_info.value.message
 
 
diff --git a/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py b/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
index 754e3651732..ddb60b69d7c 100644
--- a/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
+++ b/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
@@ -7,6 +7,9 @@
 import httpx
 import pytest
 
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+
 
 class TestGetStripePublishableKey:
     """Tests for get_stripe_publishable_key endpoint."""
@@ -62,15 +65,14 @@ async def test_uses_env_var_override_when_set(self) -> None:
     )
     async def test_rejects_invalid_env_var_key_format(self) -> None:
         """Should reject keys that don't start with pk_."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.tenants.billing_api import get_stripe_publishable_key
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_stripe_publishable_key()
 
         assert exc_info.value.status_code == 500
-        assert "Invalid Stripe publishable key format" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
+        assert exc_info.value.message == "Invalid Stripe publishable key format"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_OVERRIDE", None)
@@ -80,8 +82,6 @@ async def test_rejects_invalid_env_var_key_format(self) -> None:
     )
     async def test_rejects_invalid_s3_key_format(self) -> None:
         """Should reject keys from S3 that don't start with pk_."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.tenants.billing_api import get_stripe_publishable_key
 
         mock_response = MagicMock()
@@ -92,11 +92,12 @@ async def test_rejects_invalid_s3_key_format(self) -> None:
             mock_client.return_value.__aenter__.return_value.get = AsyncMock(
                 return_value=mock_response
             )
-            with pytest.raises(HTTPException) as exc_info:
+            with pytest.raises(OnyxError) as exc_info:
                 await get_stripe_publishable_key()
 
         assert exc_info.value.status_code == 500
-        assert "Invalid Stripe publishable key format" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
+        assert exc_info.value.message == "Invalid Stripe publishable key format"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_OVERRIDE", None)
@@ -106,34 +107,32 @@ async def test_rejects_invalid_s3_key_format(self) -> None:
     )
     async def test_handles_s3_fetch_error(self) -> None:
         """Should return error when S3 fetch fails."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.tenants.billing_api import get_stripe_publishable_key
 
         with patch("httpx.AsyncClient") as mock_client:
             mock_client.return_value.__aenter__.return_value.get = AsyncMock(
                 side_effect=httpx.HTTPError("Connection failed")
             )
-            with pytest.raises(HTTPException) as exc_info:
+            with pytest.raises(OnyxError) as exc_info:
                 await get_stripe_publishable_key()
 
         assert exc_info.value.status_code == 500
-        assert "Failed to fetch Stripe publishable key" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
+        assert exc_info.value.message == "Failed to fetch Stripe publishable key"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_OVERRIDE", None)
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_URL", None)
     async def test_error_when_no_config(self) -> None:
         """Should return error when neither env var nor S3 URL is configured."""
-        from fastapi import HTTPException
-
         from ee.onyx.server.tenants.billing_api import get_stripe_publishable_key
 
-        with pytest.raises(HTTPException) as exc_info:
+        with pytest.raises(OnyxError) as exc_info:
             await get_stripe_publishable_key()
 
         assert exc_info.value.status_code == 500
-        assert "not configured" in exc_info.value.detail
+        assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
+        assert "not configured" in exc_info.value.message
 
     @pytest.mark.asyncio
     @patch(
diff --git a/backend/tests/unit/onyx/error_handling/__init__.py b/backend/tests/unit/onyx/error_handling/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/backend/tests/unit/onyx/error_handling/test_exceptions.py b/backend/tests/unit/onyx/error_handling/test_exceptions.py
new file mode 100644
index 00000000000..f09224e8d71
--- /dev/null
+++ b/backend/tests/unit/onyx/error_handling/test_exceptions.py
@@ -0,0 +1,90 @@
+"""Tests for OnyxError and the global exception handler."""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.error_handling.exceptions import register_onyx_exception_handlers
+
+
+class TestOnyxError:
+    """Unit tests for OnyxError construction and properties."""
+
+    def test_basic_construction(self) -> None:
+        err = OnyxError(OnyxErrorCode.NOT_FOUND, "Session not found")
+        assert err.error_code is OnyxErrorCode.NOT_FOUND
+        assert err.message == "Session not found"
+        assert err.status_code == 404
+
+    def test_message_defaults_to_code(self) -> None:
+        err = OnyxError(OnyxErrorCode.UNAUTHENTICATED)
+        assert err.message == "UNAUTHENTICATED"
+        assert str(err) == "UNAUTHENTICATED"
+
+    def test_status_code_override(self) -> None:
+        err = OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "upstream failed",
+            status_code_override=503,
+        )
+        assert err.status_code == 503
+        # error_code still reports its own default
+        assert err.error_code.status_code == 502
+
+    def test_no_override_uses_error_code_status(self) -> None:
+        err = OnyxError(OnyxErrorCode.RATE_LIMITED, "slow down")
+        assert err.status_code == 429
+
+    def test_is_exception(self) -> None:
+        err = OnyxError(OnyxErrorCode.INTERNAL_ERROR)
+        assert isinstance(err, Exception)
+
+
+class TestExceptionHandler:
+    """Integration test: OnyxError → JSON response via FastAPI TestClient."""
+
+    @pytest.fixture()
+    def client(self) -> TestClient:
+        app = FastAPI()
+        register_onyx_exception_handlers(app)
+
+        @app.get("/boom")
+        def _boom() -> None:
+            raise OnyxError(OnyxErrorCode.NOT_FOUND, "Thing not found")
+
+        @app.get("/boom-override")
+        def _boom_override() -> None:
+            raise OnyxError(
+                OnyxErrorCode.BAD_GATEWAY,
+                "upstream 503",
+                status_code_override=503,
+            )
+
+        @app.get("/boom-default-msg")
+        def _boom_default() -> None:
+            raise OnyxError(OnyxErrorCode.UNAUTHENTICATED)
+
+        return TestClient(app, raise_server_exceptions=False)
+
+    def test_returns_correct_status_and_body(self, client: TestClient) -> None:
+        resp = client.get("/boom")
+        assert resp.status_code == 404
+        body = resp.json()
+        assert body["error_code"] == "NOT_FOUND"
+        assert body["message"] == "Thing not found"
+
+    def test_status_code_override_in_response(self, client: TestClient) -> None:
+        resp = client.get("/boom-override")
+        assert resp.status_code == 503
+        body = resp.json()
+        assert body["error_code"] == "BAD_GATEWAY"
+        assert body["message"] == "upstream 503"
+
+    def test_default_message(self, client: TestClient) -> None:
+        resp = client.get("/boom-default-msg")
+        assert resp.status_code == 401
+        body = resp.json()
+        assert body["error_code"] == "UNAUTHENTICATED"
+        assert body["message"] == "UNAUTHENTICATED"

From 7a7350f38750634f53a31a8258396c3836084231 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 3 Mar 2026 18:16:00 -0800
Subject: [PATCH 070/267] fix: Markdown does not show all texts (#9009)

---
 .../sections/modals/PreviewModal/variants/markdownVariant.tsx   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx b/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
index 2d1c9586f04..6fae1e50d9d 100644
--- a/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
@@ -30,7 +30,7 @@ export const markdownVariant: PreviewVariant = {
     <ScrollIndicatorDiv className="flex-1 min-h-0 p-4" variant="shadow">
       <MinimalMarkdown
         content={ctx.fileContent}
-        className="w-full pb-4 h-full text-lg break-words"
+        className="w-full pb-4 text-lg break-words"
       />
     </ScrollIndicatorDiv>
   ),

From d2f35e1fae07847bea27dafcbdeb65e908661a83 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 3 Mar 2026 20:32:30 -0800
Subject: [PATCH 071/267] feat: Align action tool tips (#8997)

---
 .../python/code_interpreter_client.py         |  8 ++-
 .../ActionsPopover/ActionLineItem.tsx         |  6 +-
 .../popovers/ActionsPopover/index.tsx         | 70 ++++++++++++-------
 3 files changed, 53 insertions(+), 31 deletions(-)

diff --git a/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py b/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
index 1f21c273c69..e4d204ab739 100644
--- a/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
+++ b/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
@@ -103,7 +103,13 @@ def _build_payload(
         return payload
 
     def health(self, use_cache: bool = False) -> bool:
-        """Check if the Code Interpreter service is healthy"""
+        """Check if the Code Interpreter service is healthy
+
+        Args:
+            use_cache: When True, return a cached result if available and
+                       within the TTL window. The cache is always populated
+                       after a live request regardless of this flag.
+        """
         if use_cache:
             cached = _health_cache.get(self.base_url)
             if cached is not None:
diff --git a/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx b/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
index 90a57c5b5db..8b585a7782e 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
@@ -25,7 +25,7 @@ export interface ActionItemProps {
   disabled: boolean;
   isForced: boolean;
   isUnavailable?: boolean;
-  unavailableReason?: string;
+  tooltip?: string;
   showAdminConfigure?: boolean;
   adminConfigureHref?: string;
   adminConfigureTooltip?: string;
@@ -47,7 +47,7 @@ export default function ActionLineItem({
   disabled,
   isForced,
   isUnavailable = false,
-  unavailableReason,
+  tooltip,
   showAdminConfigure = false,
   adminConfigureHref,
   adminConfigureTooltip = "Configure",
@@ -88,7 +88,7 @@ export default function ActionLineItem({
     sourceCounts.enabled > 0 &&
     sourceCounts.enabled < sourceCounts.total;
 
-  const tooltipText = isUnavailable ? unavailableReason : tool?.description;
+  const tooltipText = tooltip || tool?.description;
 
   return (
     <SimpleTooltip tooltip={tooltipText} className="max-w-[30rem]">
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index f1f4118e0a6..5329706909b 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -42,26 +42,45 @@ import { useProjectsContext } from "@/providers/ProjectsContext";
 import { SvgActions, SvgChevronRight, SvgKey, SvgSliders } from "@opal/icons";
 import { Button } from "@opal/components";
 
-const UNAVAILABLE_TOOL_TOOLTIP_FALLBACK =
-  "This action is not configured yet. Ask an admin to enable it.";
-const UNAVAILABLE_TOOL_TOOLTIP_ADMIN_FALLBACK =
-  "This action is not configured yet. If you have access, enable it in the admin panel.";
-const UNAVAILABLE_TOOL_TOOLTIPS: Record<string, string> = {
-  [IMAGE_GENERATION_TOOL_ID]:
-    "Image generation requires a configured model. If you have access, set one up under Settings > Image Generation, or ask an admin.",
-  [WEB_SEARCH_TOOL_ID]:
-    "Web search requires a configured provider. If you have access, set one up under Settings > Web Search, or ask an admin.",
-  [PYTHON_TOOL_ID]:
-    "Code Interpreter requires the service to be configured with a valid base URL. If you have access, configure it in the admin panel, or ask an admin.",
+function buildTooltipMessage(
+  actionDescription: string,
+  isConfigured: boolean,
+  canManageAction: boolean
+) {
+  const _CONFIGURE_MESSAGE = "Press the settings cog to enable.";
+  const _USER_NOT_ADMIN_MESSAGE = "Ask an admin to configure.";
+
+  if (isConfigured) {
+    return actionDescription;
+  }
+
+  if (canManageAction) {
+    return actionDescription + " " + _CONFIGURE_MESSAGE;
+  }
+
+  return actionDescription + " " + _USER_NOT_ADMIN_MESSAGE;
+}
+
+const TOOL_DESCRIPTIONS: Record<string, string> = {
+  [SEARCH_TOOL_ID]: "Search through connected knowledge to inform the answer.",
+  [IMAGE_GENERATION_TOOL_ID]: "Generate images based on a prompt.",
+  [WEB_SEARCH_TOOL_ID]: "Search the web for up-to-date information.",
+  [PYTHON_TOOL_ID]: "Execute code for complex analysis.",
 };
-const getUnavailableToolTooltip = (
-  inCodeToolId?: string | null,
-  canAdminConfigure?: boolean
-) =>
-  (inCodeToolId && UNAVAILABLE_TOOL_TOOLTIPS[inCodeToolId]) ??
-  (canAdminConfigure
-    ? UNAVAILABLE_TOOL_TOOLTIP_ADMIN_FALLBACK
-    : UNAVAILABLE_TOOL_TOOLTIP_FALLBACK);
+
+const DEFAULT_TOOL_DESCRIPTION = "This action is not configured yet.";
+
+function getToolTooltip(
+  tool: ToolSnapshot,
+  isConfigured: boolean,
+  canManageAction: boolean
+): string {
+  const description =
+    (tool.in_code_tool_id && TOOL_DESCRIPTIONS[tool.in_code_tool_id]) ||
+    tool.description ||
+    DEFAULT_TOOL_DESCRIPTION;
+  return buildTooltipMessage(description, isConfigured, canManageAction);
+}
 
 const ADMIN_CONFIG_LINKS: Record<string, { href: string; tooltip: string }> = {
   [IMAGE_GENERATION_TOOL_ID]: {
@@ -896,14 +915,11 @@ export default function ActionsPopover({
                 disabled={disabledToolIds.includes(tool.id)}
                 isForced={forcedToolIds.includes(tool.id)}
                 isUnavailable={isUnavailable}
-                unavailableReason={
-                  isUnavailable
-                    ? getUnavailableToolTooltip(
-                        tool.in_code_tool_id,
-                        canAdminConfigure
-                      )
-                    : undefined
-                }
+                tooltip={getToolTooltip(
+                  tool,
+                  isToolAvailable,
+                  canAdminConfigure
+                )}
                 showAdminConfigure={!!adminConfigureInfo}
                 adminConfigureHref={adminConfigureInfo?.href}
                 adminConfigureTooltip={adminConfigureInfo?.tooltip}

From 60891b2f449361f2b81df054817f611e9df7502d Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Tue, 3 Mar 2026 22:14:21 -0800
Subject: [PATCH 072/267] feat: Add IllustrationContent layout component to
 opal (#9011)

---
 .../src/layouts/IllustrationContent/README.md | 87 +++++++++++++++++++
 .../IllustrationContent/components.tsx        | 83 ++++++++++++++++++
 web/lib/opal/src/layouts/README.md            | 17 +++-
 web/lib/opal/src/layouts/index.ts             |  6 ++
 4 files changed, 190 insertions(+), 3 deletions(-)
 create mode 100644 web/lib/opal/src/layouts/IllustrationContent/README.md
 create mode 100644 web/lib/opal/src/layouts/IllustrationContent/components.tsx

diff --git a/web/lib/opal/src/layouts/IllustrationContent/README.md b/web/lib/opal/src/layouts/IllustrationContent/README.md
new file mode 100644
index 00000000000..44bc659bd3f
--- /dev/null
+++ b/web/lib/opal/src/layouts/IllustrationContent/README.md
@@ -0,0 +1,87 @@
+# IllustrationContent
+
+**Import:** `import { IllustrationContent, type IllustrationContentProps } from "@opal/layouts";`
+
+A vertically-stacked, center-aligned layout for empty states, error pages, and informational placeholders. Pairs a large illustration with a title and optional description.
+
+## Why IllustrationContent?
+
+Empty states and placeholder screens share a recurring pattern: a large illustration centered above a title and description. `IllustrationContent` standardises that pattern so every empty state looks consistent without hand-rolling flex containers and spacing each time.
+
+## Layout Structure
+
+```
+┌─────────────────────────────────┐
+│          (1.25rem pad)          │
+│     ┌───────────────────┐       │
+│     │   illustration    │       │
+│     │   7.5rem × 7.5rem │       │
+│     └───────────────────┘       │
+│         (0.75rem gap)           │
+│          title (center)         │
+│         (0.75rem gap)           │
+│      description (center)       │
+│          (1.25rem pad)          │
+└─────────────────────────────────┘
+```
+
+- Outer container: `flex flex-col items-center gap-3 p-5 text-center`.
+- Illustration: `w-[7.5rem] h-[7.5rem]` (120px), no extra padding.
+- Title: `<p>` with `font-main-content-emphasis text-text-04`.
+- Description: `<p>` with `font-secondary-body text-text-03`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `illustration` | `IconFunctionComponent` | — | Optional illustration component rendered at 7.5rem × 7.5rem, centered. Works with any `@opal/illustrations` SVG. |
+| `title` | `string` | **(required)** | Main title text, center-aligned. |
+| `description` | `string` | — | Optional description below the title, center-aligned. |
+
+## Usage Examples
+
+### Empty search results
+
+```tsx
+import { IllustrationContent } from "@opal/layouts";
+import SvgNoResult from "@opal/illustrations/no-result";
+
+<IllustrationContent
+  illustration={SvgNoResult}
+  title="No results found"
+  description="Try adjusting your search or filters."
+/>
+```
+
+### Not found page
+
+```tsx
+import { IllustrationContent } from "@opal/layouts";
+import SvgNotFound from "@opal/illustrations/not-found";
+
+<IllustrationContent
+  illustration={SvgNotFound}
+  title="Page not found"
+  description="The page you're looking for doesn't exist or has been moved."
+/>
+```
+
+### Title only (no illustration, no description)
+
+```tsx
+import { IllustrationContent } from "@opal/layouts";
+
+<IllustrationContent title="Nothing here yet" />
+```
+
+### Empty state with illustration and title (no description)
+
+```tsx
+import { IllustrationContent } from "@opal/layouts";
+import SvgEmpty from "@opal/illustrations/empty";
+
+<IllustrationContent
+  illustration={SvgEmpty}
+  title="No items"
+/>
+```
diff --git a/web/lib/opal/src/layouts/IllustrationContent/components.tsx b/web/lib/opal/src/layouts/IllustrationContent/components.tsx
new file mode 100644
index 00000000000..fdac4a585ac
--- /dev/null
+++ b/web/lib/opal/src/layouts/IllustrationContent/components.tsx
@@ -0,0 +1,83 @@
+import type { IconFunctionComponent } from "@opal/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface IllustrationContentProps {
+  /** Optional illustration rendered at 7.5rem × 7.5rem (120px), centered. */
+  illustration?: IconFunctionComponent;
+
+  /** Main title text, center-aligned. Uses `font-main-content-emphasis`. */
+  title: string;
+
+  /** Optional description below the title, center-aligned. Uses `font-secondary-body`. */
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// IllustrationContent
+// ---------------------------------------------------------------------------
+
+/**
+ * A vertically-stacked, center-aligned layout for empty states, error pages,
+ * and informational placeholders.
+ *
+ * Renders an optional illustration on top, followed by a title and an optional
+ * description — all center-aligned with consistent spacing.
+ *
+ * **Layout structure:**
+ *
+ * ```
+ * ┌─────────────────────────────────┐
+ * │          (1.25rem pad)          │
+ * │     ┌───────────────────┐       │
+ * │     │   illustration    │       │
+ * │     │   7.5rem × 7.5rem │       │
+ * │     └───────────────────┘       │
+ * │         (0.75rem gap)           │
+ * │          title (center)         │
+ * │         (0.75rem gap)           │
+ * │      description (center)       │
+ * │          (1.25rem pad)          │
+ * └─────────────────────────────────┘
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import { IllustrationContent } from "@opal/layouts";
+ * import SvgNoResult from "@opal/illustrations/no-result";
+ *
+ * <IllustrationContent
+ *   illustration={SvgNoResult}
+ *   title="No results found"
+ *   description="Try adjusting your search or filters."
+ * />
+ * ```
+ */
+function IllustrationContent({
+  illustration: Illustration,
+  title,
+  description,
+}: IllustrationContentProps) {
+  return (
+    <div className="flex flex-col items-center gap-3 p-5 text-center">
+      {Illustration && (
+        <Illustration
+          aria-hidden="true"
+          className="shrink-0 w-[7.5rem] h-[7.5rem]"
+        />
+      )}
+      <p className="font-main-content-emphasis text-text-04">{title}</p>
+      {description && (
+        <p className="font-secondary-body text-text-03">{description}</p>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export { IllustrationContent, type IllustrationContentProps };
diff --git a/web/lib/opal/src/layouts/README.md b/web/lib/opal/src/layouts/README.md
index b63c9cec179..31b3461db0e 100644
--- a/web/lib/opal/src/layouts/README.md
+++ b/web/lib/opal/src/layouts/README.md
@@ -1,8 +1,8 @@
 # @opal/layouts
 
-**Import:** `import { Content, ContentAction } from "@opal/layouts";`
+**Import:** `import { Content, ContentAction, IllustrationContent } from "@opal/layouts";`
 
-Layout primitives for composing icon + title + description rows. These components handle sizing, font selection, icon alignment, and optional inline editing — things that are tedious to get right by hand and easy to get wrong.
+Layout primitives for composing content blocks. These components handle sizing, font selection, icon alignment, and optional inline editing — things that are tedious to get right by hand and easy to get wrong.
 
 ## Components
 
@@ -10,13 +10,15 @@ Layout primitives for composing icon + title + description rows. These component
 |---|---|---|
 | [`Content`](./Content/README.md) | Icon + title + description row. Routes to an internal layout (`ContentXl`, `ContentLg`, `ContentMd`, or `ContentSm`) based on `sizePreset` and `variant`. | [Content README](./Content/README.md) |
 | [`ContentAction`](./ContentAction/README.md) | Wraps `Content` in a flex-row with an optional `rightChildren` slot for action buttons. Adds padding alignment via the shared `SizeVariant` scale. | [ContentAction README](./ContentAction/README.md) |
+| [`IllustrationContent`](./IllustrationContent/README.md) | Center-aligned illustration + title + description stack for empty states, error pages, and placeholders. | [IllustrationContent README](./IllustrationContent/README.md) |
 
 ## Quick Start
 
 ```tsx
-import { Content, ContentAction } from "@opal/layouts";
+import { Content, ContentAction, IllustrationContent } from "@opal/layouts";
 import { Button } from "@opal/components";
 import SvgSettings from "@opal/icons/settings";
+import SvgNoResult from "@opal/illustrations/no-result";
 
 // Simple heading
 <Content
@@ -49,6 +51,13 @@ import SvgSettings from "@opal/icons/settings";
     <Button icon={SvgSettings} prominence="tertiary" />
   }
 />
+
+// Empty state with illustration
+<IllustrationContent
+  illustration={SvgNoResult}
+  title="No results found"
+  description="Try adjusting your search or filters."
+/>
 ```
 
 ## Architecture
@@ -74,10 +83,12 @@ From `@opal/layouts`:
 // Components
 Content
 ContentAction
+IllustrationContent
 
 // Types
 ContentProps
 ContentActionProps
+IllustrationContentProps
 SizePreset
 ContentVariant
 ```
diff --git a/web/lib/opal/src/layouts/index.ts b/web/lib/opal/src/layouts/index.ts
index 78af01b3436..6b703e1e8f9 100644
--- a/web/lib/opal/src/layouts/index.ts
+++ b/web/lib/opal/src/layouts/index.ts
@@ -11,3 +11,9 @@ export {
   ContentAction,
   type ContentActionProps,
 } from "@opal/layouts/ContentAction/components";
+
+/* IllustrationContent */
+export {
+  IllustrationContent,
+  type IllustrationContentProps,
+} from "@opal/layouts/IllustrationContent/components";

From a8cdc3965dc3e892684d902c3c5c51833551f57c Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Wed, 4 Mar 2026 02:51:20 -0800
Subject: [PATCH 073/267] refactor(fe): move onboarding to sections/,
 consolidate hooks, move types (#8985)

---
 web/jest.config.js                            |   3 +
 .../components/BuildOnboardingModal.tsx       |   2 +-
 .../__tests__/useShowOnboarding.test.tsx      | 121 ++++-----
 web/src/hooks/useShowOnboarding.ts            | 257 +++++++++++++++++-
 .../types.ts => interfaces/onboarding.ts}     |   0
 .../onboarding/useOnboardingState.ts          | 240 ----------------
 web/src/refresh-pages/AppPage.tsx             |   6 +-
 .../sections/modals/llmConfig/formUtils.ts    |   5 +-
 .../onboarding/OnboardingFlow.tsx             |  15 +-
 .../__tests__/onboardingReducer.test.ts       |   2 +-
 .../onboarding/components/LLMProviderCard.tsx |   4 +-
 .../onboarding/components/NonAdminStep.tsx    |   8 +
 .../components/OnboardingHeader.tsx           |   4 +-
 .../components/llmConnectionHelpers.ts        |   0
 .../onboarding/constants.ts                   |   5 +-
 .../forms/AnthropicOnboardingForm.tsx         |   6 +-
 .../onboarding/forms/AzureOnboardingForm.tsx  |   6 +-
 .../forms/BedrockOnboardingForm.tsx           |   6 +-
 .../onboarding/forms/CustomOnboardingForm.tsx |   4 +-
 .../onboarding/forms/OllamaOnboardingForm.tsx |   2 +-
 .../forms/OnboardingFormWrapper.tsx           |   4 +-
 .../onboarding/forms/OpenAIOnboardingForm.tsx |   6 +-
 .../forms/OpenRouterOnboardingForm.tsx        |   6 +-
 .../forms/VertexAIOnboardingForm.tsx          |   8 +-
 .../AnthropicOnboardingForm.test.tsx          |   0
 .../__tests__/AzureOnboardingForm.test.tsx    |   0
 .../__tests__/BedrockOnboardingForm.test.tsx  |   0
 .../__tests__/CustomOnboardingForm.test.tsx   |   0
 .../__tests__/OllamaOnboardingForm.test.tsx   |   0
 .../__tests__/OpenAIOnboardingForm.test.tsx   |   0
 .../OpenRouterOnboardingForm.test.tsx         |   0
 .../__tests__/VertexAIOnboardingForm.test.tsx |   0
 .../forms/__tests__/testHelpers.tsx           |   2 +-
 .../onboarding/forms/getOnboardingForm.tsx    |   2 +-
 .../onboarding/reducer.ts                     |   2 +-
 .../onboarding/steps/FinalStep.tsx            |   4 +-
 .../onboarding/steps/LLMStep.tsx              |   8 +-
 .../onboarding/steps/NameStep.tsx             |   6 +-
 38 files changed, 387 insertions(+), 357 deletions(-)
 rename web/src/{refresh-components/onboarding => hooks}/__tests__/useShowOnboarding.test.tsx (76%)
 rename web/src/{refresh-components/onboarding/types.ts => interfaces/onboarding.ts} (100%)
 delete mode 100644 web/src/refresh-components/onboarding/useOnboardingState.ts
 rename web/src/{refresh-components => sections}/onboarding/OnboardingFlow.tsx (92%)
 rename web/src/{refresh-components => sections}/onboarding/__tests__/onboardingReducer.test.ts (99%)
 rename web/src/{refresh-components => sections}/onboarding/components/LLMProviderCard.tsx (98%)
 rename web/src/{refresh-components => sections}/onboarding/components/NonAdminStep.tsx (92%)
 rename web/src/{refresh-components => sections}/onboarding/components/OnboardingHeader.tsx (95%)
 rename web/src/{refresh-components => sections}/onboarding/components/llmConnectionHelpers.ts (100%)
 rename web/src/{refresh-components => sections}/onboarding/constants.ts (95%)
 rename web/src/{refresh-components => sections}/onboarding/forms/AnthropicOnboardingForm.tsx (97%)
 rename web/src/{refresh-components => sections}/onboarding/forms/AzureOnboardingForm.tsx (98%)
 rename web/src/{refresh-components => sections}/onboarding/forms/BedrockOnboardingForm.tsx (99%)
 rename web/src/{refresh-components => sections}/onboarding/forms/CustomOnboardingForm.tsx (99%)
 rename web/src/{refresh-components => sections}/onboarding/forms/OllamaOnboardingForm.tsx (99%)
 rename web/src/{refresh-components => sections}/onboarding/forms/OnboardingFormWrapper.tsx (99%)
 rename web/src/{refresh-components => sections}/onboarding/forms/OpenAIOnboardingForm.tsx (97%)
 rename web/src/{refresh-components => sections}/onboarding/forms/OpenRouterOnboardingForm.tsx (98%)
 rename web/src/{refresh-components => sections}/onboarding/forms/VertexAIOnboardingForm.tsx (97%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/AzureOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/BedrockOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/CustomOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/OllamaOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/OpenRouterOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx (100%)
 rename web/src/{refresh-components => sections}/onboarding/forms/__tests__/testHelpers.tsx (99%)
 rename web/src/{refresh-components => sections}/onboarding/forms/getOnboardingForm.tsx (98%)
 rename web/src/{refresh-components => sections}/onboarding/reducer.ts (98%)
 rename web/src/{refresh-components => sections}/onboarding/steps/FinalStep.tsx (90%)
 rename web/src/{refresh-components => sections}/onboarding/steps/LLMStep.tsx (98%)
 rename web/src/{refresh-components => sections}/onboarding/steps/NameStep.tsx (97%)

diff --git a/web/jest.config.js b/web/jest.config.js
index 939f7fe5f11..83c97d69ea3 100644
--- a/web/jest.config.js
+++ b/web/jest.config.js
@@ -143,6 +143,7 @@ module.exports = {
         "**/src/app/**/utils/*.test.ts",
         "**/src/app/**/hooks/*.test.ts", // Pure packet processor tests
         "**/src/refresh-components/**/*.test.ts",
+        "**/src/sections/**/*.test.ts",
         // Add more patterns here as you add more unit tests
       ],
     },
@@ -156,6 +157,8 @@ module.exports = {
         "**/src/components/**/*.test.tsx",
         "**/src/lib/**/*.test.tsx",
         "**/src/refresh-components/**/*.test.tsx",
+        "**/src/hooks/**/*.test.tsx",
+        "**/src/sections/**/*.test.tsx",
         // Add more patterns here as you add more integration tests
       ],
     },
diff --git a/web/src/app/craft/onboarding/components/BuildOnboardingModal.tsx b/web/src/app/craft/onboarding/components/BuildOnboardingModal.tsx
index da35d5bc8f6..09508e2104a 100644
--- a/web/src/app/craft/onboarding/components/BuildOnboardingModal.tsx
+++ b/web/src/app/craft/onboarding/components/BuildOnboardingModal.tsx
@@ -23,7 +23,7 @@ import { LLM_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
 import {
   buildInitialValues,
   testApiKeyHelper,
-} from "@/refresh-components/onboarding/components/llmConnectionHelpers";
+} from "@/sections/onboarding/components/llmConnectionHelpers";
 import OnboardingInfoPages from "@/app/craft/onboarding/components/OnboardingInfoPages";
 import OnboardingUserInfo from "@/app/craft/onboarding/components/OnboardingUserInfo";
 import OnboardingLlmSetup, {
diff --git a/web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx b/web/src/hooks/__tests__/useShowOnboarding.test.tsx
similarity index 76%
rename from web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx
rename to web/src/hooks/__tests__/useShowOnboarding.test.tsx
index 8800c82ab30..494fbd03fd1 100644
--- a/web/src/refresh-components/onboarding/__tests__/useShowOnboarding.test.tsx
+++ b/web/src/hooks/__tests__/useShowOnboarding.test.tsx
@@ -2,39 +2,39 @@ import React from "react";
 import { renderHook, act } from "@testing-library/react";
 import "@testing-library/jest-dom";
 import { useShowOnboarding } from "@/hooks/useShowOnboarding";
-import { OnboardingStep } from "../types";
-
-// Mock useOnboardingState to isolate useShowOnboarding logic
-const mockActions = {
-  nextStep: jest.fn(),
-  prevStep: jest.fn(),
-  goToStep: jest.fn(),
-  setButtonActive: jest.fn(),
-  updateName: jest.fn(),
-  updateData: jest.fn(),
-  setLoading: jest.fn(),
-  setError: jest.fn(),
-  reset: jest.fn(),
+import { OnboardingStep } from "@/interfaces/onboarding";
+
+// Mock underlying dependencies used by the inlined useOnboardingState
+jest.mock("@/providers/UserProvider", () => ({
+  useUser: () => ({
+    user: null,
+    refreshUser: jest.fn(),
+  }),
+}));
+
+// Configurable mock for useProviderStatus
+const mockProviderStatus = {
+  llmProviders: [] as unknown[],
+  isLoadingProviders: false,
+  hasProviders: false,
+  providerOptions: [],
+  refreshProviderInfo: jest.fn(),
 };
 
-let mockStepIndex = 0;
-
-jest.mock("@/refresh-components/onboarding/useOnboardingState", () => ({
-  useOnboardingState: () => ({
-    state: {
-      currentStep: OnboardingStep.Welcome,
-      stepIndex: mockStepIndex,
-      totalSteps: 3,
-      data: {},
-      isButtonActive: true,
-      isLoading: false,
-    },
-    llmDescriptors: [],
-    actions: mockActions,
-    isLoading: false,
+jest.mock("@/components/chat/ProviderContext", () => ({
+  useProviderStatus: () => mockProviderStatus,
+}));
+
+jest.mock("@/hooks/useLLMProviders", () => ({
+  useLLMProviders: () => ({
+    refetch: jest.fn(),
   }),
 }));
 
+jest.mock("@/lib/userSettings", () => ({
+  updateUserPersonalization: jest.fn(),
+}));
+
 function renderUseShowOnboarding(
   overrides: {
     isLoadingProviders?: boolean;
@@ -44,14 +44,18 @@ function renderUseShowOnboarding(
     userId?: string;
   } = {}
 ) {
+  // Configure the provider mock based on overrides
+  mockProviderStatus.isLoadingProviders = overrides.isLoadingProviders ?? false;
+  mockProviderStatus.hasProviders = overrides.hasAnyProvider ?? false;
+  mockProviderStatus.llmProviders = overrides.hasAnyProvider
+    ? [{ provider: "openai" }]
+    : [];
+
   const defaultParams = {
-    liveAgent: undefined,
-    isLoadingProviders: false,
-    hasAnyProvider: false,
-    isLoadingChatSessions: false,
-    chatSessionsCount: 0,
-    userId: "user-1",
-    ...overrides,
+    liveAgent: undefined as undefined,
+    isLoadingChatSessions: overrides.isLoadingChatSessions ?? false,
+    chatSessionsCount: overrides.chatSessionsCount ?? 0,
+    userId: "userId" in overrides ? overrides.userId : "user-1",
   };
 
   return renderHook((props) => useShowOnboarding(props), {
@@ -63,7 +67,11 @@ describe("useShowOnboarding", () => {
   beforeEach(() => {
     jest.clearAllMocks();
     localStorage.clear();
-    mockStepIndex = 0;
+    // Reset mock to defaults
+    mockProviderStatus.llmProviders = [];
+    mockProviderStatus.isLoadingProviders = false;
+    mockProviderStatus.hasProviders = false;
+    mockProviderStatus.providerOptions = [];
   });
 
   it("returns showOnboarding=false while providers are loading", () => {
@@ -119,11 +127,12 @@ describe("useShowOnboarding", () => {
     });
     expect(result.current.showOnboarding).toBe(true);
 
-    // Re-render with same userId but provider data now available
+    // Simulate providers arriving — update the mock
+    mockProviderStatus.hasProviders = true;
+    mockProviderStatus.llmProviders = [{ provider: "openai" }];
+
     rerender({
       liveAgent: undefined,
-      isLoadingProviders: false,
-      hasAnyProvider: true,
       isLoadingChatSessions: false,
       chatSessionsCount: 0,
       userId: "user-1",
@@ -133,31 +142,6 @@ describe("useShowOnboarding", () => {
     expect(result.current.showOnboarding).toBe(false);
   });
 
-  it("does not self-correct when user has advanced past Welcome step", () => {
-    const { result, rerender } = renderUseShowOnboarding({
-      hasAnyProvider: false,
-      chatSessionsCount: 0,
-      userId: "user-1",
-    });
-    expect(result.current.showOnboarding).toBe(true);
-
-    // Simulate user advancing past Welcome (e.g. they configured an LLM provider)
-    mockStepIndex = 1;
-
-    // Re-render with same userId but provider data now available
-    rerender({
-      liveAgent: undefined,
-      isLoadingProviders: false,
-      hasAnyProvider: true,
-      isLoadingChatSessions: false,
-      chatSessionsCount: 0,
-      userId: "user-1",
-    });
-
-    // Should stay true — user is actively using onboarding
-    expect(result.current.showOnboarding).toBe(true);
-  });
-
   it("re-evaluates when userId changes", () => {
     const { result, rerender } = renderUseShowOnboarding({
       hasAnyProvider: false,
@@ -166,11 +150,12 @@ describe("useShowOnboarding", () => {
     });
     expect(result.current.showOnboarding).toBe(true);
 
-    // Change to a new userId with providers available
+    // Change to a new userId with providers available — update the mock
+    mockProviderStatus.hasProviders = true;
+    mockProviderStatus.llmProviders = [{ provider: "openai" }];
+
     rerender({
       liveAgent: undefined,
-      isLoadingProviders: false,
-      hasAnyProvider: true,
       isLoadingChatSessions: false,
       chatSessionsCount: 0,
       userId: "user-2",
@@ -207,7 +192,7 @@ describe("useShowOnboarding", () => {
     expect(result.current.showOnboarding).toBe(false);
   });
 
-  it("returns onboardingState and actions from useOnboardingState", () => {
+  it("returns onboardingState and actions", () => {
     const { result } = renderUseShowOnboarding();
     expect(result.current.onboardingState.currentStep).toBe(
       OnboardingStep.Welcome
diff --git a/web/src/hooks/useShowOnboarding.ts b/web/src/hooks/useShowOnboarding.ts
index 8254f014dbd..e386ebb4adc 100644
--- a/web/src/hooks/useShowOnboarding.ts
+++ b/web/src/hooks/useShowOnboarding.ts
@@ -1,17 +1,259 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useReducer, useCallback, useEffect, useRef, useState } from "react";
+import { onboardingReducer, initialState } from "@/sections/onboarding/reducer";
+import {
+  OnboardingActions,
+  OnboardingActionType,
+  OnboardingData,
+  OnboardingState,
+  OnboardingStep,
+} from "@/interfaces/onboarding";
+import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
+import { updateUserPersonalization } from "@/lib/userSettings";
+import { useUser } from "@/providers/UserProvider";
 import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
-import { useOnboardingState } from "@/refresh-components/onboarding/useOnboardingState";
+import { useLLMProviders } from "@/hooks/useLLMProviders";
+import { useProviderStatus } from "@/components/chat/ProviderContext";
 
 function getOnboardingCompletedKey(userId: string): string {
   return `onyx:onboardingCompleted:${userId}`;
 }
 
+function useOnboardingState(liveAgent?: MinimalPersonaSnapshot): {
+  state: OnboardingState;
+  llmDescriptors: WellKnownLLMProviderDescriptor[];
+  actions: OnboardingActions;
+  isLoading: boolean;
+  hasProviders: boolean;
+} {
+  const [state, dispatch] = useReducer(onboardingReducer, initialState);
+  const { user, refreshUser } = useUser();
+
+  // Get provider data from ProviderContext instead of duplicating the call
+  const {
+    llmProviders,
+    isLoadingProviders,
+    hasProviders: hasLlmProviders,
+    providerOptions,
+    refreshProviderInfo,
+  } = useProviderStatus();
+
+  // Only fetch persona-specific providers (different endpoint)
+  const { refetch: refreshPersonaProviders } = useLLMProviders(liveAgent?.id);
+
+  const userName = user?.personalization?.name;
+  const llmDescriptors = providerOptions;
+
+  const nameUpdateTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(
+    null
+  );
+  const hasInitializedForUserRef = useRef<string | undefined>(undefined);
+
+  // Initialize onboarding to the earliest incomplete step — runs once per user
+  // after both user data and provider data have loaded.  After initialization,
+  // user actions (Next / Prev / goToStep) drive navigation; the effect never
+  // re-runs so it cannot override user-driven state (e.g. button active).
+  useEffect(() => {
+    if (
+      isLoadingProviders ||
+      !user ||
+      hasInitializedForUserRef.current === user.id
+    ) {
+      return;
+    }
+    hasInitializedForUserRef.current = user.id;
+
+    // Pre-populate state with existing data
+    if (userName) {
+      dispatch({
+        type: OnboardingActionType.UPDATE_DATA,
+        payload: { userName },
+      });
+    }
+    dispatch({
+      type: OnboardingActionType.UPDATE_DATA,
+      payload: { llmProviders: (llmProviders ?? []).map((p) => p.provider) },
+    });
+
+    // Determine the earliest incomplete step
+    // Name step is incomplete if userName is not set
+    if (!userName) {
+      // Stay at Welcome/Name step (no dispatch needed, this is the initial state)
+      return;
+    }
+
+    // LlmSetup step is incomplete if no LLM providers are configured
+    if (!hasLlmProviders) {
+      dispatch({
+        type: OnboardingActionType.SET_BUTTON_ACTIVE,
+        isButtonActive: false,
+      });
+      dispatch({
+        type: OnboardingActionType.GO_TO_STEP,
+        step: OnboardingStep.LlmSetup,
+      });
+      return;
+    }
+
+    // All steps complete - go to Complete step
+    dispatch({
+      type: OnboardingActionType.SET_BUTTON_ACTIVE,
+      isButtonActive: true,
+    });
+    dispatch({
+      type: OnboardingActionType.GO_TO_STEP,
+      step: OnboardingStep.Complete,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [llmProviders, isLoadingProviders, userName, hasLlmProviders, user]);
+
+  const nextStep = useCallback(() => {
+    dispatch({
+      type: OnboardingActionType.SET_BUTTON_ACTIVE,
+      isButtonActive: false,
+    });
+
+    if (state.currentStep === OnboardingStep.Name) {
+      const hasProviders = (state.data.llmProviders?.length ?? 0) > 0;
+      if (hasProviders) {
+        dispatch({
+          type: OnboardingActionType.SET_BUTTON_ACTIVE,
+          isButtonActive: true,
+        });
+      } else {
+        dispatch({
+          type: OnboardingActionType.SET_BUTTON_ACTIVE,
+          isButtonActive: false,
+        });
+      }
+    }
+
+    if (state.currentStep === OnboardingStep.LlmSetup) {
+      refreshProviderInfo();
+      if (liveAgent) {
+        refreshPersonaProviders();
+      }
+    }
+    dispatch({ type: OnboardingActionType.NEXT_STEP });
+  }, [state, refreshProviderInfo, refreshPersonaProviders, liveAgent]);
+
+  const prevStep = useCallback(() => {
+    dispatch({ type: OnboardingActionType.PREV_STEP });
+  }, []);
+
+  const goToStep = useCallback(
+    (step: OnboardingStep) => {
+      const hasProviders = (state.data.llmProviders?.length ?? 0) > 0;
+      if (step === OnboardingStep.LlmSetup && hasProviders) {
+        dispatch({
+          type: OnboardingActionType.SET_BUTTON_ACTIVE,
+          isButtonActive: true,
+        });
+      } else if (step === OnboardingStep.LlmSetup) {
+        dispatch({
+          type: OnboardingActionType.SET_BUTTON_ACTIVE,
+          isButtonActive: false,
+        });
+      }
+      dispatch({ type: OnboardingActionType.GO_TO_STEP, step });
+    },
+    [state]
+  );
+
+  const updateName = useCallback(
+    (name: string) => {
+      dispatch({
+        type: OnboardingActionType.UPDATE_DATA,
+        payload: { userName: name },
+      });
+
+      if (nameUpdateTimeoutRef.current) {
+        clearTimeout(nameUpdateTimeoutRef.current);
+      }
+
+      if (name === "") {
+        dispatch({
+          type: OnboardingActionType.SET_BUTTON_ACTIVE,
+          isButtonActive: false,
+        });
+      } else {
+        dispatch({
+          type: OnboardingActionType.SET_BUTTON_ACTIVE,
+          isButtonActive: true,
+        });
+      }
+
+      nameUpdateTimeoutRef.current = setTimeout(async () => {
+        try {
+          await updateUserPersonalization({ name });
+          await refreshUser();
+        } catch (_e) {
+          dispatch({
+            type: OnboardingActionType.SET_BUTTON_ACTIVE,
+            isButtonActive: false,
+          });
+          console.error("Error updating user name:", _e);
+        } finally {
+          nameUpdateTimeoutRef.current = null;
+        }
+      }, 500);
+    },
+    [refreshUser]
+  );
+
+  const updateData = useCallback((data: Partial<OnboardingData>) => {
+    dispatch({ type: OnboardingActionType.UPDATE_DATA, payload: data });
+  }, []);
+
+  const setLoading = useCallback((isLoading: boolean) => {
+    dispatch({ type: OnboardingActionType.SET_LOADING, isLoading });
+  }, []);
+
+  const setButtonActive = useCallback((active: boolean) => {
+    dispatch({
+      type: OnboardingActionType.SET_BUTTON_ACTIVE,
+      isButtonActive: active,
+    });
+  }, []);
+
+  const setError = useCallback((error: string | undefined) => {
+    dispatch({ type: OnboardingActionType.SET_ERROR, error });
+  }, []);
+
+  const reset = useCallback(() => {
+    dispatch({ type: OnboardingActionType.RESET });
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (nameUpdateTimeoutRef.current) {
+        clearTimeout(nameUpdateTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    state,
+    llmDescriptors,
+    actions: {
+      nextStep,
+      prevStep,
+      goToStep,
+      setButtonActive,
+      updateName,
+      updateData,
+      setLoading,
+      setError,
+      reset,
+    },
+    isLoading: isLoadingProviders,
+    hasProviders: hasLlmProviders,
+  };
+}
+
 interface UseShowOnboardingParams {
   liveAgent: MinimalPersonaSnapshot | undefined;
-  isLoadingProviders: boolean;
-  hasAnyProvider: boolean | undefined;
   isLoadingChatSessions: boolean;
   chatSessionsCount: number;
   userId: string | undefined;
@@ -19,8 +261,6 @@ interface UseShowOnboardingParams {
 
 export function useShowOnboarding({
   liveAgent,
-  isLoadingProviders,
-  hasAnyProvider,
   isLoadingChatSessions,
   chatSessionsCount,
   userId,
@@ -36,14 +276,17 @@ export function useShowOnboarding({
     setOnboardingDismissed(dismissed);
   }, [userId]);
 
-  // Initialize onboarding state
+  // Initialize onboarding state — single source of truth for provider data
   const {
     state: onboardingState,
     actions: onboardingActions,
     llmDescriptors,
     isLoading: isLoadingOnboarding,
+    hasProviders: hasAnyProvider,
   } = useOnboardingState(liveAgent);
 
+  const isLoadingProviders = isLoadingOnboarding;
+
   // Track which user we've already evaluated onboarding for.
   // Re-check when userId changes (logout/login, account switching without full reload).
   const hasCheckedOnboardingForUserId = useRef<string | undefined>(undefined);
diff --git a/web/src/refresh-components/onboarding/types.ts b/web/src/interfaces/onboarding.ts
similarity index 100%
rename from web/src/refresh-components/onboarding/types.ts
rename to web/src/interfaces/onboarding.ts
diff --git a/web/src/refresh-components/onboarding/useOnboardingState.ts b/web/src/refresh-components/onboarding/useOnboardingState.ts
deleted file mode 100644
index 12fff6f682c..00000000000
--- a/web/src/refresh-components/onboarding/useOnboardingState.ts
+++ /dev/null
@@ -1,240 +0,0 @@
-import { useReducer, useCallback, useEffect, useRef } from "react";
-import { onboardingReducer, initialState } from "./reducer";
-import {
-  OnboardingActions,
-  OnboardingActionType,
-  OnboardingData,
-  OnboardingState,
-  OnboardingStep,
-} from "./types";
-import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
-import { updateUserPersonalization } from "@/lib/userSettings";
-import { useUser } from "@/providers/UserProvider";
-import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
-import { useLLMProviders } from "@/hooks/useLLMProviders";
-import { useProviderStatus } from "@/components/chat/ProviderContext";
-
-export function useOnboardingState(liveAgent?: MinimalPersonaSnapshot): {
-  state: OnboardingState;
-  llmDescriptors: WellKnownLLMProviderDescriptor[];
-  actions: OnboardingActions;
-  isLoading: boolean;
-} {
-  const [state, dispatch] = useReducer(onboardingReducer, initialState);
-  const { user, refreshUser } = useUser();
-
-  // Get provider data from ProviderContext instead of duplicating the call
-  const {
-    llmProviders,
-    isLoadingProviders,
-    hasProviders: hasLlmProviders,
-    providerOptions,
-    refreshProviderInfo,
-  } = useProviderStatus();
-
-  // Only fetch persona-specific providers (different endpoint)
-  const { refetch: refreshPersonaProviders } = useLLMProviders(liveAgent?.id);
-
-  const userName = user?.personalization?.name;
-  const llmDescriptors = providerOptions;
-
-  const nameUpdateTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(
-    null
-  );
-
-  // Navigate to the earliest incomplete step in the onboarding flow.
-  // Step order: Welcome -> Name -> LlmSetup -> Complete
-  // We check steps in order and stop at the first incomplete one.
-  useEffect(() => {
-    // Don't run logic until data has loaded
-    if (isLoadingProviders) {
-      return;
-    }
-
-    // Pre-populate state with existing data
-    if (userName) {
-      dispatch({
-        type: OnboardingActionType.UPDATE_DATA,
-        payload: { userName },
-      });
-    }
-    if (hasLlmProviders) {
-      dispatch({
-        type: OnboardingActionType.UPDATE_DATA,
-        payload: { llmProviders: (llmProviders ?? []).map((p) => p.provider) },
-      });
-    }
-
-    // Determine the earliest incomplete step
-    // Name step is incomplete if userName is not set
-    if (!userName) {
-      // Stay at Welcome/Name step (no dispatch needed, this is the initial state)
-      return;
-    }
-
-    // LlmSetup step is incomplete if no LLM providers are configured
-    if (!hasLlmProviders) {
-      dispatch({
-        type: OnboardingActionType.SET_BUTTON_ACTIVE,
-        isButtonActive: false,
-      });
-      dispatch({
-        type: OnboardingActionType.GO_TO_STEP,
-        step: OnboardingStep.LlmSetup,
-      });
-      return;
-    }
-
-    // All steps complete - go to Complete step
-    dispatch({
-      type: OnboardingActionType.SET_BUTTON_ACTIVE,
-      isButtonActive: true,
-    });
-    dispatch({
-      type: OnboardingActionType.GO_TO_STEP,
-      step: OnboardingStep.Complete,
-    });
-  }, [llmProviders, isLoadingProviders]);
-
-  const nextStep = useCallback(() => {
-    dispatch({
-      type: OnboardingActionType.SET_BUTTON_ACTIVE,
-      isButtonActive: false,
-    });
-
-    if (state.currentStep === OnboardingStep.Name) {
-      const hasProviders = (state.data.llmProviders?.length ?? 0) > 0;
-      if (hasProviders) {
-        dispatch({
-          type: OnboardingActionType.SET_BUTTON_ACTIVE,
-          isButtonActive: true,
-        });
-      } else {
-        dispatch({
-          type: OnboardingActionType.SET_BUTTON_ACTIVE,
-          isButtonActive: false,
-        });
-      }
-    }
-
-    if (state.currentStep === OnboardingStep.LlmSetup) {
-      refreshProviderInfo();
-      if (liveAgent) {
-        refreshPersonaProviders();
-      }
-    }
-    dispatch({ type: OnboardingActionType.NEXT_STEP });
-  }, [state, refreshProviderInfo, llmProviders, refreshPersonaProviders]);
-
-  const prevStep = useCallback(() => {
-    dispatch({ type: OnboardingActionType.PREV_STEP });
-  }, []);
-
-  const goToStep = useCallback(
-    (step: OnboardingStep) => {
-      const hasProviders = state.data.llmProviders?.length || 0 > 0;
-      if (step === OnboardingStep.LlmSetup && hasProviders) {
-        dispatch({
-          type: OnboardingActionType.SET_BUTTON_ACTIVE,
-          isButtonActive: true,
-        });
-      } else if (step === OnboardingStep.LlmSetup) {
-        dispatch({
-          type: OnboardingActionType.SET_BUTTON_ACTIVE,
-          isButtonActive: false,
-        });
-      }
-      dispatch({ type: OnboardingActionType.GO_TO_STEP, step });
-    },
-    [llmProviders]
-  );
-
-  const updateName = useCallback(
-    (name: string) => {
-      dispatch({
-        type: OnboardingActionType.UPDATE_DATA,
-        payload: { userName: name },
-      });
-
-      if (nameUpdateTimeoutRef.current) {
-        clearTimeout(nameUpdateTimeoutRef.current);
-      }
-
-      if (name === "") {
-        dispatch({
-          type: OnboardingActionType.SET_BUTTON_ACTIVE,
-          isButtonActive: false,
-        });
-      } else {
-        dispatch({
-          type: OnboardingActionType.SET_BUTTON_ACTIVE,
-          isButtonActive: true,
-        });
-      }
-
-      nameUpdateTimeoutRef.current = setTimeout(async () => {
-        try {
-          await updateUserPersonalization({ name });
-          await refreshUser();
-        } catch (_e) {
-          dispatch({
-            type: OnboardingActionType.SET_BUTTON_ACTIVE,
-            isButtonActive: false,
-          });
-          console.error("Error updating user name:", _e);
-        } finally {
-          nameUpdateTimeoutRef.current = null;
-        }
-      }, 500);
-    },
-    [refreshUser]
-  );
-
-  const updateData = useCallback((data: Partial<OnboardingData>) => {
-    dispatch({ type: OnboardingActionType.UPDATE_DATA, payload: data });
-  }, []);
-
-  const setLoading = useCallback((isLoading: boolean) => {
-    dispatch({ type: OnboardingActionType.SET_LOADING, isLoading });
-  }, []);
-
-  const setButtonActive = useCallback((active: boolean) => {
-    dispatch({
-      type: OnboardingActionType.SET_BUTTON_ACTIVE,
-      isButtonActive: active,
-    });
-  }, []);
-
-  const setError = useCallback((error: string | undefined) => {
-    dispatch({ type: OnboardingActionType.SET_ERROR, error });
-  }, []);
-
-  const reset = useCallback(() => {
-    dispatch({ type: OnboardingActionType.RESET });
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      if (nameUpdateTimeoutRef.current) {
-        clearTimeout(nameUpdateTimeoutRef.current);
-      }
-    };
-  }, []);
-
-  return {
-    state,
-    llmDescriptors,
-    actions: {
-      nextStep,
-      prevStep,
-      goToStep,
-      setButtonActive,
-      updateName,
-      updateData,
-      setLoading,
-      setError,
-      reset,
-    },
-    isLoading: isLoadingProviders || !!liveAgent,
-  };
-}
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 130195c9120..418786686db 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -60,8 +60,8 @@ import {
 import ProjectChatSessionList from "@/app/app/components/projects/ProjectChatSessionList";
 import { cn } from "@/lib/utils";
 import Suggestions from "@/sections/Suggestions";
-import OnboardingFlow from "@/refresh-components/onboarding/OnboardingFlow";
-import { OnboardingStep } from "@/refresh-components/onboarding/types";
+import OnboardingFlow from "@/sections/onboarding/OnboardingFlow";
+import { OnboardingStep } from "@/interfaces/onboarding";
 import { useShowOnboarding } from "@/hooks/useShowOnboarding";
 import * as AppLayouts from "@/layouts/app-layouts";
 import { SvgChevronDown, SvgFileText } from "@opal/icons";
@@ -232,8 +232,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     hideOnboarding,
   } = useShowOnboarding({
     liveAgent,
-    isLoadingProviders: llmManager.isLoadingProviders,
-    hasAnyProvider: llmManager.hasAnyProvider,
     isLoadingChatSessions,
     chatSessionsCount: chatSessions.length,
     userId: user?.id,
diff --git a/web/src/sections/modals/llmConfig/formUtils.ts b/web/src/sections/modals/llmConfig/formUtils.ts
index bd581ba0957..730d074cace 100644
--- a/web/src/sections/modals/llmConfig/formUtils.ts
+++ b/web/src/sections/modals/llmConfig/formUtils.ts
@@ -18,7 +18,10 @@ export const buildDefaultInitialValues = (
   existingLlmProvider?: LLMProviderView,
   modelConfigurations?: ModelConfiguration[]
 ) => {
-  const defaultModelName = modelConfigurations?.[0]?.name ?? "";
+  const defaultModelName =
+    existingLlmProvider?.model_configurations?.[0]?.name ??
+    modelConfigurations?.[0]?.name ??
+    "";
 
   // Auto mode must be explicitly enabled by the user
   // Default to false for new providers, preserve existing value when editing
diff --git a/web/src/refresh-components/onboarding/OnboardingFlow.tsx b/web/src/sections/onboarding/OnboardingFlow.tsx
similarity index 92%
rename from web/src/refresh-components/onboarding/OnboardingFlow.tsx
rename to web/src/sections/onboarding/OnboardingFlow.tsx
index 944712aa454..4b746aef7cb 100644
--- a/web/src/refresh-components/onboarding/OnboardingFlow.tsx
+++ b/web/src/sections/onboarding/OnboardingFlow.tsx
@@ -1,9 +1,15 @@
+"use client";
+
 import { memo } from "react";
 import OnboardingHeader from "./components/OnboardingHeader";
 import NameStep from "./steps/NameStep";
 import LLMStep from "./steps/LLMStep";
 import FinalStep from "./steps/FinalStep";
-import { OnboardingActions, OnboardingState, OnboardingStep } from "./types";
+import {
+  OnboardingActions,
+  OnboardingState,
+  OnboardingStep,
+} from "@/interfaces/onboarding";
 import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
 import { useUser } from "@/providers/UserProvider";
 import { UserRole } from "@/lib/types";
@@ -27,9 +33,12 @@ const OnboardingFlowInner = ({
   llmDescriptors,
 }: OnboardingFlowProps) => {
   const { user } = useUser();
+
+  if (!user) return null;
+
   const hasStarted = onboardingState.currentStep !== OnboardingStep.Welcome;
 
-  return user?.role === UserRole.ADMIN ? (
+  return user.role === UserRole.ADMIN ? (
     showOnboarding ? (
       <div
         className="flex flex-col items-center justify-center w-full max-w-[var(--app-page-main-content-width)] gap-2 mb-4"
@@ -74,7 +83,7 @@ const OnboardingFlowInner = ({
       // if the admin hasn't set their name.
       <NonAdminStep />
     )
-  ) : !user?.personalization?.name ? (
+  ) : !user.personalization?.name ? (
     <NonAdminStep />
   ) : null;
 };
diff --git a/web/src/refresh-components/onboarding/__tests__/onboardingReducer.test.ts b/web/src/sections/onboarding/__tests__/onboardingReducer.test.ts
similarity index 99%
rename from web/src/refresh-components/onboarding/__tests__/onboardingReducer.test.ts
rename to web/src/sections/onboarding/__tests__/onboardingReducer.test.ts
index 345bf855c3b..12f868f5e90 100644
--- a/web/src/refresh-components/onboarding/__tests__/onboardingReducer.test.ts
+++ b/web/src/sections/onboarding/__tests__/onboardingReducer.test.ts
@@ -3,7 +3,7 @@ import {
   OnboardingActionType,
   OnboardingStep,
   OnboardingState,
-} from "../types";
+} from "@/interfaces/onboarding";
 
 describe("onboardingReducer", () => {
   describe("initial state", () => {
diff --git a/web/src/refresh-components/onboarding/components/LLMProviderCard.tsx b/web/src/sections/onboarding/components/LLMProviderCard.tsx
similarity index 98%
rename from web/src/refresh-components/onboarding/components/LLMProviderCard.tsx
rename to web/src/sections/onboarding/components/LLMProviderCard.tsx
index b13cb819094..75abc35fd9e 100644
--- a/web/src/refresh-components/onboarding/components/LLMProviderCard.tsx
+++ b/web/src/sections/onboarding/components/LLMProviderCard.tsx
@@ -1,4 +1,6 @@
-import React, { memo, useCallback, useState } from "react";
+"use client";
+
+import { memo, useCallback, useState } from "react";
 import Text from "@/refresh-components/texts/Text";
 import Truncated from "@/refresh-components/texts/Truncated";
 import IconButton from "@/refresh-components/buttons/IconButton";
diff --git a/web/src/refresh-components/onboarding/components/NonAdminStep.tsx b/web/src/sections/onboarding/components/NonAdminStep.tsx
similarity index 92%
rename from web/src/refresh-components/onboarding/components/NonAdminStep.tsx
rename to web/src/sections/onboarding/components/NonAdminStep.tsx
index c7b79f07b30..5408c23882c 100644
--- a/web/src/refresh-components/onboarding/components/NonAdminStep.tsx
+++ b/web/src/sections/onboarding/components/NonAdminStep.tsx
@@ -1,9 +1,12 @@
+"use client";
+
 import React, { useRef, useState, useEffect } from "react";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import Button from "@/refresh-components/buttons/Button";
 import { updateUserPersonalization } from "@/lib/userSettings";
 import { useUser } from "@/providers/UserProvider";
+import { toast } from "@/hooks/useToast";
 import IconButton from "@/refresh-components/buttons/IconButton";
 import { Button as OpalButton } from "@opal/components";
 import InputAvatar from "@/refresh-components/inputs/InputAvatar";
@@ -37,8 +40,13 @@ export default function NonAdminStep() {
         setSavedName(name);
         setShowHeader(true);
         setIsEditing(false);
+        // Don't call refreshUser() here — it would cause OnboardingFlow to
+        // unmount this component (since user.personalization.name becomes set),
+        // hiding the confirmation banner before the user sees it.
+        // refreshUser() is called in handleDismissConfirmation instead.
       })
       .catch((error) => {
+        toast.error("Failed to save name. Please try again.");
         console.error(error);
       });
   };
diff --git a/web/src/refresh-components/onboarding/components/OnboardingHeader.tsx b/web/src/sections/onboarding/components/OnboardingHeader.tsx
similarity index 95%
rename from web/src/refresh-components/onboarding/components/OnboardingHeader.tsx
rename to web/src/sections/onboarding/components/OnboardingHeader.tsx
index 07cccb6e144..fbc76863b89 100644
--- a/web/src/refresh-components/onboarding/components/OnboardingHeader.tsx
+++ b/web/src/sections/onboarding/components/OnboardingHeader.tsx
@@ -1,10 +1,10 @@
 import React from "react";
-import { STEP_CONFIG } from "@/refresh-components/onboarding/constants";
+import { STEP_CONFIG } from "@/sections/onboarding/constants";
 import {
   OnboardingActions,
   OnboardingState,
   OnboardingStep,
-} from "@/refresh-components/onboarding/types";
+} from "@/interfaces/onboarding";
 import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
diff --git a/web/src/refresh-components/onboarding/components/llmConnectionHelpers.ts b/web/src/sections/onboarding/components/llmConnectionHelpers.ts
similarity index 100%
rename from web/src/refresh-components/onboarding/components/llmConnectionHelpers.ts
rename to web/src/sections/onboarding/components/llmConnectionHelpers.ts
diff --git a/web/src/refresh-components/onboarding/constants.ts b/web/src/sections/onboarding/constants.ts
similarity index 95%
rename from web/src/refresh-components/onboarding/constants.ts
rename to web/src/sections/onboarding/constants.ts
index ba9a710a680..e98680d4c90 100644
--- a/web/src/refresh-components/onboarding/constants.ts
+++ b/web/src/sections/onboarding/constants.ts
@@ -1,7 +1,4 @@
-import {
-  OnboardingStep,
-  FinalStepItemProps,
-} from "@/refresh-components/onboarding/types";
+import { OnboardingStep, FinalStepItemProps } from "@/interfaces/onboarding";
 import { SvgGlobe, SvgImage, SvgUsers } from "@opal/icons";
 
 type StepConfig = {
diff --git a/web/src/refresh-components/onboarding/forms/AnthropicOnboardingForm.tsx b/web/src/sections/onboarding/forms/AnthropicOnboardingForm.tsx
similarity index 97%
rename from web/src/refresh-components/onboarding/forms/AnthropicOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/AnthropicOnboardingForm.tsx
index a3169bd885f..ada4f3ce538 100644
--- a/web/src/refresh-components/onboarding/forms/AnthropicOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/AnthropicOnboardingForm.tsx
@@ -1,4 +1,6 @@
-import React, { useMemo } from "react";
+"use client";
+
+import { useMemo } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
@@ -13,7 +15,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
diff --git a/web/src/refresh-components/onboarding/forms/AzureOnboardingForm.tsx b/web/src/sections/onboarding/forms/AzureOnboardingForm.tsx
similarity index 98%
rename from web/src/refresh-components/onboarding/forms/AzureOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/AzureOnboardingForm.tsx
index 69d9d545668..be4f6ae9ab4 100644
--- a/web/src/refresh-components/onboarding/forms/AzureOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/AzureOnboardingForm.tsx
@@ -1,4 +1,6 @@
-import React, { useMemo } from "react";
+"use client";
+
+import { useMemo } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
@@ -11,7 +13,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
diff --git a/web/src/refresh-components/onboarding/forms/BedrockOnboardingForm.tsx b/web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx
similarity index 99%
rename from web/src/refresh-components/onboarding/forms/BedrockOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx
index 95ca0dad413..3b3653058cb 100644
--- a/web/src/refresh-components/onboarding/forms/BedrockOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx
@@ -1,4 +1,6 @@
-import React, { useMemo } from "react";
+"use client";
+
+import { useMemo } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
@@ -16,7 +18,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
diff --git a/web/src/refresh-components/onboarding/forms/CustomOnboardingForm.tsx b/web/src/sections/onboarding/forms/CustomOnboardingForm.tsx
similarity index 99%
rename from web/src/refresh-components/onboarding/forms/CustomOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/CustomOnboardingForm.tsx
index b821cac3fe0..d41c7bb799e 100644
--- a/web/src/refresh-components/onboarding/forms/CustomOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/CustomOnboardingForm.tsx
@@ -1,3 +1,5 @@
+"use client";
+
 import { useMemo, useState } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
@@ -14,7 +16,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 
diff --git a/web/src/refresh-components/onboarding/forms/OllamaOnboardingForm.tsx b/web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx
similarity index 99%
rename from web/src/refresh-components/onboarding/forms/OllamaOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx
index d14cfad0fe7..5f5c14cc656 100644
--- a/web/src/refresh-components/onboarding/forms/OllamaOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx
@@ -17,7 +17,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
diff --git a/web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx b/web/src/sections/onboarding/forms/OnboardingFormWrapper.tsx
similarity index 99%
rename from web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx
rename to web/src/sections/onboarding/forms/OnboardingFormWrapper.tsx
index de998e6d089..85e15a160ed 100644
--- a/web/src/refresh-components/onboarding/forms/OnboardingFormWrapper.tsx
+++ b/web/src/sections/onboarding/forms/OnboardingFormWrapper.tsx
@@ -1,3 +1,5 @@
+"use client";
+
 import React, { useState, useMemo, ReactNode } from "react";
 import { Form, Formik, FormikProps } from "formik";
 import * as Yup from "yup";
@@ -10,7 +12,7 @@ import {
   LLM_ADMIN_URL,
   LLM_PROVIDERS_ADMIN_URL,
 } from "@/lib/llmConfig/constants";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { APIFormFieldState } from "@/refresh-components/form/types";
 import {
   testApiKeyHelper,
diff --git a/web/src/refresh-components/onboarding/forms/OpenAIOnboardingForm.tsx b/web/src/sections/onboarding/forms/OpenAIOnboardingForm.tsx
similarity index 97%
rename from web/src/refresh-components/onboarding/forms/OpenAIOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/OpenAIOnboardingForm.tsx
index 4b79e795174..9398034229f 100644
--- a/web/src/refresh-components/onboarding/forms/OpenAIOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/OpenAIOnboardingForm.tsx
@@ -1,4 +1,6 @@
-import React, { useMemo } from "react";
+"use client";
+
+import { useMemo } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
@@ -13,7 +15,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
diff --git a/web/src/refresh-components/onboarding/forms/OpenRouterOnboardingForm.tsx b/web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx
similarity index 98%
rename from web/src/refresh-components/onboarding/forms/OpenRouterOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx
index 5aaba9e0544..db17b94c968 100644
--- a/web/src/refresh-components/onboarding/forms/OpenRouterOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx
@@ -1,4 +1,6 @@
-import React, { useMemo } from "react";
+"use client";
+
+import { useMemo } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
@@ -13,7 +15,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { buildInitialValues } from "../components/llmConnectionHelpers";
 import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
diff --git a/web/src/refresh-components/onboarding/forms/VertexAIOnboardingForm.tsx b/web/src/sections/onboarding/forms/VertexAIOnboardingForm.tsx
similarity index 97%
rename from web/src/refresh-components/onboarding/forms/VertexAIOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/VertexAIOnboardingForm.tsx
index 7c351e0728b..b10cbcda934 100644
--- a/web/src/refresh-components/onboarding/forms/VertexAIOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/VertexAIOnboardingForm.tsx
@@ -1,12 +1,12 @@
-import React, { useMemo } from "react";
+"use client";
+
+import { useMemo } from "react";
 import * as Yup from "yup";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
 import InputComboBox from "@/refresh-components/inputs/InputComboBox";
 import InputFile from "@/refresh-components/inputs/InputFile";
 import Separator from "@/refresh-components/Separator";
-import { cn, noProp } from "@/lib/utils";
-import { SvgRefreshCw } from "@opal/icons";
 import {
   ModelConfiguration,
   WellKnownLLMProviderDescriptor,
@@ -15,7 +15,7 @@ import {
   OnboardingFormWrapper,
   OnboardingFormChildProps,
 } from "./OnboardingFormWrapper";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import {
   buildInitialValues,
   testApiKeyHelper,
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/AzureOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/AzureOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/AzureOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/AzureOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/BedrockOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/BedrockOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/BedrockOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/BedrockOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/CustomOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/CustomOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/CustomOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/CustomOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/OllamaOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/OllamaOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/OllamaOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/OllamaOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/OpenRouterOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/OpenRouterOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/OpenRouterOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/OpenRouterOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx
similarity index 100%
rename from web/src/refresh-components/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx
rename to web/src/sections/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx
diff --git a/web/src/refresh-components/onboarding/forms/__tests__/testHelpers.tsx b/web/src/sections/onboarding/forms/__tests__/testHelpers.tsx
similarity index 99%
rename from web/src/refresh-components/onboarding/forms/__tests__/testHelpers.tsx
rename to web/src/sections/onboarding/forms/__tests__/testHelpers.tsx
index e5f4220ef90..5f146728e3d 100644
--- a/web/src/refresh-components/onboarding/forms/__tests__/testHelpers.tsx
+++ b/web/src/sections/onboarding/forms/__tests__/testHelpers.tsx
@@ -14,7 +14,7 @@ import {
   OnboardingState,
   OnboardingActions,
   OnboardingStep,
-} from "../../types";
+} from "@/interfaces/onboarding";
 
 /**
  * Creates a mock WellKnownLLMProviderDescriptor for testing
diff --git a/web/src/refresh-components/onboarding/forms/getOnboardingForm.tsx b/web/src/sections/onboarding/forms/getOnboardingForm.tsx
similarity index 98%
rename from web/src/refresh-components/onboarding/forms/getOnboardingForm.tsx
rename to web/src/sections/onboarding/forms/getOnboardingForm.tsx
index 4e4c862e55b..1d436d4f13d 100644
--- a/web/src/refresh-components/onboarding/forms/getOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/getOnboardingForm.tsx
@@ -3,7 +3,7 @@ import {
   WellKnownLLMProviderDescriptor,
   LLMProviderName,
 } from "@/interfaces/llm";
-import { OnboardingActions, OnboardingState } from "../types";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { OpenAIOnboardingForm } from "./OpenAIOnboardingForm";
 import { AnthropicOnboardingForm } from "./AnthropicOnboardingForm";
 import { OllamaOnboardingForm } from "./OllamaOnboardingForm";
diff --git a/web/src/refresh-components/onboarding/reducer.ts b/web/src/sections/onboarding/reducer.ts
similarity index 98%
rename from web/src/refresh-components/onboarding/reducer.ts
rename to web/src/sections/onboarding/reducer.ts
index a9df107bd62..7ced5a4b1bb 100644
--- a/web/src/refresh-components/onboarding/reducer.ts
+++ b/web/src/sections/onboarding/reducer.ts
@@ -3,7 +3,7 @@ import {
   OnboardingAction,
   OnboardingActionType,
   OnboardingStep,
-} from "./types";
+} from "@/interfaces/onboarding";
 import { STEP_NAVIGATION, STEP_CONFIG, TOTAL_STEPS } from "./constants";
 
 export const initialState: OnboardingState = {
diff --git a/web/src/refresh-components/onboarding/steps/FinalStep.tsx b/web/src/sections/onboarding/steps/FinalStep.tsx
similarity index 90%
rename from web/src/refresh-components/onboarding/steps/FinalStep.tsx
rename to web/src/sections/onboarding/steps/FinalStep.tsx
index 8264a38dd14..e7ced14c4e9 100644
--- a/web/src/refresh-components/onboarding/steps/FinalStep.tsx
+++ b/web/src/sections/onboarding/steps/FinalStep.tsx
@@ -2,8 +2,8 @@ import React from "react";
 import Link from "next/link";
 import type { Route } from "next";
 import Button from "@/refresh-components/buttons/Button";
-import { FINAL_SETUP_CONFIG } from "@/refresh-components/onboarding/constants";
-import { FinalStepItemProps } from "@/refresh-components/onboarding/types";
+import { FINAL_SETUP_CONFIG } from "@/sections/onboarding/constants";
+import { FinalStepItemProps } from "@/interfaces/onboarding";
 import { SvgExternalLink } from "@opal/icons";
 import { Section } from "@/layouts/general-layouts";
 import { ContentAction } from "@opal/layouts";
diff --git a/web/src/refresh-components/onboarding/steps/LLMStep.tsx b/web/src/sections/onboarding/steps/LLMStep.tsx
similarity index 98%
rename from web/src/refresh-components/onboarding/steps/LLMStep.tsx
rename to web/src/sections/onboarding/steps/LLMStep.tsx
index 7c7c029ed0a..d3e2a9f484d 100644
--- a/web/src/refresh-components/onboarding/steps/LLMStep.tsx
+++ b/web/src/sections/onboarding/steps/LLMStep.tsx
@@ -5,7 +5,11 @@ import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
 import Separator from "@/refresh-components/Separator";
 import LLMProviderCard from "../components/LLMProviderCard";
-import { OnboardingActions, OnboardingState, OnboardingStep } from "../types";
+import {
+  OnboardingActions,
+  OnboardingState,
+  OnboardingStep,
+} from "@/interfaces/onboarding";
 import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
 import {
   getOnboardingForm,
@@ -137,7 +141,7 @@ const LLMStepInner = ({
                 tertiary
                 rightIcon={SvgExternalLink}
                 disabled={disabled}
-                href="admin/configuration/llm"
+                href="/admin/configuration/llm"
               >
                 View in Admin Panel
               </Button>
diff --git a/web/src/refresh-components/onboarding/steps/NameStep.tsx b/web/src/sections/onboarding/steps/NameStep.tsx
similarity index 97%
rename from web/src/refresh-components/onboarding/steps/NameStep.tsx
rename to web/src/sections/onboarding/steps/NameStep.tsx
index 2c4d1e332c4..360e833ea09 100644
--- a/web/src/refresh-components/onboarding/steps/NameStep.tsx
+++ b/web/src/sections/onboarding/steps/NameStep.tsx
@@ -3,7 +3,11 @@
 import React, { useRef } from "react";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
-import { OnboardingState, OnboardingActions, OnboardingStep } from "../types";
+import {
+  OnboardingState,
+  OnboardingActions,
+  OnboardingStep,
+} from "@/interfaces/onboarding";
 import InputAvatar from "@/refresh-components/inputs/InputAvatar";
 import { cn } from "@/lib/utils";
 import IconButton from "@/refresh-components/buttons/IconButton";

From c627cea17da5a7b9a3d18719f114a2ca26f3d41d Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Wed, 4 Mar 2026 07:52:56 -0800
Subject: [PATCH 074/267] feat(opal): add sidebar variant to Interactive +
 refactor SidebarTab (#9016)

---
 web/lib/opal/src/core/index.ts                |   2 +
 web/lib/opal/src/core/interactive/README.md   |  38 +++++
 .../opal/src/core/interactive/components.tsx  |  21 ++-
 web/lib/opal/src/core/interactive/styles.css  |  20 +++
 .../opal/src/layouts/Content/ContentSm.tsx    |  13 +-
 web/lib/opal/src/layouts/Content/styles.css   |  23 ++-
 web/src/app/app/settings/layout.tsx           |   8 +-
 web/src/app/craft/components/SideBar.tsx      |  15 +-
 web/src/ee/sections/SearchUI.tsx              |   9 +-
 .../refresh-components/buttons/SidebarTab.tsx | 155 +++++++++---------
 web/src/sections/sidebar/AdminSidebar.tsx     |   6 +-
 web/src/sections/sidebar/AgentButton.tsx      |   4 +-
 web/src/sections/sidebar/AppSidebar.tsx       |  31 ++--
 web/src/sections/sidebar/ChatButton.tsx       |   3 +-
 .../sections/sidebar/ProjectFolderButton.tsx  |   5 +-
 .../sections/sidebar/StepSidebarWrapper.tsx   |   6 +-
 .../sections/sidebar/UserAvatarPopover.tsx    |  12 +-
 17 files changed, 239 insertions(+), 132 deletions(-)

diff --git a/web/lib/opal/src/core/index.ts b/web/lib/opal/src/core/index.ts
index a3295203aee..ed3d7f644db 100644
--- a/web/lib/opal/src/core/index.ts
+++ b/web/lib/opal/src/core/index.ts
@@ -11,6 +11,8 @@ export {
   Interactive,
   type InteractiveBaseProps,
   type InteractiveBaseVariantProps,
+  type InteractiveBaseSidebarVariantProps,
+  type InteractiveBaseSidebarProminenceTypes,
   type InteractiveContainerProps,
   type InteractiveContainerRoundingVariant,
 } from "@opal/core/interactive/components";
diff --git a/web/lib/opal/src/core/interactive/README.md b/web/lib/opal/src/core/interactive/README.md
index 69c8a9d1694..6445cfe61c6 100644
--- a/web/lib/opal/src/core/interactive/README.md
+++ b/web/lib/opal/src/core/interactive/README.md
@@ -104,6 +104,44 @@ The foundational layer for all clickable surfaces in the design system. Defines
 | **Active** | `action-link-05` | `action-link-05` |
 | **Disabled** | `action-link-03` | `action-link-03` |
 
+### Sidebar (unselected)
+
+> No CSS `:active` state — only hover/transient and selected.
+
+**Background**
+
+| | Light |
+|---|---|
+| **Rest** | `transparent` |
+| **Hover / Transient** | `background-tint-03` |
+| **Disabled** | `transparent` |
+
+**Foreground**
+
+| | Light |
+|---|---|
+| **Rest** | `text-03` |
+| **Hover / Transient** | `text-04` |
+| **Disabled** | `text-01` |
+
+### Sidebar (selected)
+
+> Completely static — hover and transient have no effect.
+
+**Background**
+
+| | Light |
+|---|---|
+| **All states** | `background-tint-00` |
+| **Disabled** | `transparent` |
+
+**Foreground**
+
+| | Light |
+|---|---|
+| **All states** | `text-03` (icon: `text-02`) |
+| **Disabled** | `text-01` |
+
 ## Sub-components
 
 | Sub-component | Role |
diff --git a/web/lib/opal/src/core/interactive/components.tsx b/web/lib/opal/src/core/interactive/components.tsx
index dfc4be39c5b..7c2fa2e44a4 100644
--- a/web/lib/opal/src/core/interactive/components.tsx
+++ b/web/lib/opal/src/core/interactive/components.tsx
@@ -1,3 +1,5 @@
+import Link from "next/link";
+import type { Route } from "next";
 import "@opal/core/interactive/styles.css";
 import React from "react";
 import { Slot } from "@radix-ui/react-slot";
@@ -26,18 +28,28 @@ type InteractiveBaseSelectVariantProps = {
   selected?: boolean;
 };
 
+type InteractiveBaseSidebarProminenceTypes = "light";
+type InteractiveBaseSidebarVariantProps = {
+  variant: "sidebar";
+  prominence?: InteractiveBaseSidebarProminenceTypes;
+  selected?: boolean;
+};
+
 /**
  * Discriminated union tying `variant` to `prominence`.
  *
  * - `"none"` accepts no prominence (`prominence` must not be provided)
  * - `"select"` accepts an optional prominence (defaults to `"light"`) and
  *   an optional `selected` boolean that switches foreground to action-link colours
+ * - `"sidebar"` accepts an optional prominence (defaults to `"light"`) and
+ *   an optional `selected` boolean for the focused/active-item state
  * - `"default"`, `"action"`, and `"danger"` accept an optional prominence
  *   (defaults to `"primary"`)
  */
 type InteractiveBaseVariantProps =
   | { variant?: "none"; prominence?: never; selected?: never }
   | InteractiveBaseSelectVariantProps
+  | InteractiveBaseSidebarVariantProps
   | {
       variant?: InteractiveBaseVariantTypes;
       prominence?: InteractiveBaseProminenceTypes;
@@ -218,7 +230,8 @@ function InteractiveBase({
   ...props
 }: InteractiveBaseProps) {
   const effectiveProminence =
-    prominence ?? (variant === "select" ? "light" : "primary");
+    prominence ??
+    (variant === "select" || variant === "sidebar" ? "light" : "primary");
   const classes = cn(
     "interactive",
     !props.onClick && !href && "!cursor-default !select-auto",
@@ -417,9 +430,9 @@ function InteractiveContainer({
   // so all styling (backgrounds, rounding, overflow) lives on one element.
   if (href) {
     return (
-      <a
+      <Link
         ref={ref as React.Ref<HTMLAnchorElement>}
-        href={href}
+        href={href as Route}
         target={target}
         rel={rel}
         {...(sharedProps as React.HTMLAttributes<HTMLAnchorElement>)}
@@ -482,6 +495,8 @@ export {
   type InteractiveBaseProps,
   type InteractiveBaseVariantProps,
   type InteractiveBaseSelectVariantProps,
+  type InteractiveBaseSidebarVariantProps,
+  type InteractiveBaseSidebarProminenceTypes,
   type InteractiveContainerProps,
   type InteractiveContainerRoundingVariant,
 };
diff --git a/web/lib/opal/src/core/interactive/styles.css b/web/lib/opal/src/core/interactive/styles.css
index a3812ee5d2a..a10f279b275 100644
--- a/web/lib/opal/src/core/interactive/styles.css
+++ b/web/lib/opal/src/core/interactive/styles.css
@@ -419,3 +419,23 @@
   ) {
   @apply bg-background-tint-00;
 }
+
+/* ---------------------------------------------------------------------------
+   Sidebar + Light
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"] {
+  @apply bg-transparent;
+}
+.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"][data-transient="true"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-03;
+}
+.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"][data-selected="true"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
diff --git a/web/lib/opal/src/layouts/Content/ContentSm.tsx b/web/lib/opal/src/layouts/Content/ContentSm.tsx
index ec5b1e8aa42..fe967366761 100644
--- a/web/lib/opal/src/layouts/Content/ContentSm.tsx
+++ b/web/lib/opal/src/layouts/Content/ContentSm.tsx
@@ -9,7 +9,7 @@ import { cn } from "@opal/utils";
 
 type ContentSmSizePreset = "main-content" | "main-ui" | "secondary";
 type ContentSmOrientation = "vertical" | "inline" | "reverse";
-type ContentSmProminence = "default" | "muted";
+type ContentSmProminence = "default" | "muted" | "muted-2x";
 
 interface ContentSmPresetConfig {
   /** Icon width/height (CSS value). */
@@ -82,13 +82,12 @@ function ContentSm({
   prominence = "default",
 }: ContentSmProps) {
   const config = CONTENT_SM_PRESETS[sizePreset];
-  const titleColorClass =
-    prominence === "muted" ? "text-text-03" : "text-text-04";
 
   return (
     <div
       className="opal-content-sm"
       data-orientation={orientation}
+      data-prominence={prominence}
       style={{ gap: config.gap }}
     >
       {Icon && (
@@ -100,18 +99,14 @@ function ContentSm({
           style={{ minHeight: config.lineHeight }}
         >
           <Icon
-            className="opal-content-sm-icon text-text-03"
+            className="opal-content-sm-icon"
             style={{ width: config.iconSize, height: config.iconSize }}
           />
         </div>
       )}
 
       <span
-        className={cn(
-          "opal-content-sm-title",
-          config.titleFont,
-          titleColorClass
-        )}
+        className={cn("opal-content-sm-title", config.titleFont)}
         style={{ height: config.lineHeight }}
       >
         {title}
diff --git a/web/lib/opal/src/layouts/Content/styles.css b/web/lib/opal/src/layouts/Content/styles.css
index 7aceb2305af..ae232231bb4 100644
--- a/web/lib/opal/src/layouts/Content/styles.css
+++ b/web/lib/opal/src/layouts/Content/styles.css
@@ -323,7 +323,7 @@
      reverse : flex-row-reverse — title left, icon right
 
    Icon color is always text-03. Title color varies by prominence
-   (text-04 default, text-03 muted) and is applied via Tailwind class.
+   (text-04 default, text-03 muted, text-02 muted-2x) via data-prominence.
    =========================================================================== */
 
 /* ---------------------------------------------------------------------------
@@ -331,7 +331,8 @@
    --------------------------------------------------------------------------- */
 
 .opal-content-sm {
-  @apply flex items-start;
+  /* since `ContentSm` doesn't have a description, it's possible to center-align the icon and text */
+  @apply flex items-center;
 }
 
 .opal-content-sm[data-orientation="inline"] {
@@ -356,15 +357,31 @@
   justify-content: center;
 }
 
+.opal-content-sm-icon {
+  @apply text-text-03;
+}
+
+.opal-content-sm[data-prominence="muted-2x"] .opal-content-sm-icon {
+  @apply text-text-02 stroke-text-02;
+}
+
 /* ---------------------------------------------------------------------------
    Title
    --------------------------------------------------------------------------- */
 
 .opal-content-sm-title {
-  @apply text-left overflow-hidden;
+  @apply text-left overflow-hidden text-text-04 truncate;
   display: -webkit-box;
   -webkit-box-orient: vertical;
   -webkit-line-clamp: 1;
   padding: 0 0.125rem;
   min-width: 0.0625rem;
 }
+
+.opal-content-sm[data-prominence="muted"] .opal-content-sm-title {
+  @apply text-text-03;
+}
+
+.opal-content-sm[data-prominence="muted-2x"] .opal-content-sm-title {
+  @apply text-text-02;
+}
diff --git a/web/src/app/app/settings/layout.tsx b/web/src/app/app/settings/layout.tsx
index 52512c8a01d..65777022a80 100644
--- a/web/src/app/app/settings/layout.tsx
+++ b/web/src/app/app/settings/layout.tsx
@@ -33,27 +33,27 @@ export default function Layout({ children }: LayoutProps) {
             <div className="flex flex-col px-2 w-[12.5rem]">
               <SidebarTab
                 href="/app/settings/general"
-                transient={pathname === "/app/settings/general"}
+                selected={pathname === "/app/settings/general"}
               >
                 General
               </SidebarTab>
               <SidebarTab
                 href="/app/settings/chat-preferences"
-                transient={pathname === "/app/settings/chat-preferences"}
+                selected={pathname === "/app/settings/chat-preferences"}
               >
                 Chat Preferences
               </SidebarTab>
               {showAccountsAccessTab && (
                 <SidebarTab
                   href="/app/settings/accounts-access"
-                  transient={pathname === "/app/settings/accounts-access"}
+                  selected={pathname === "/app/settings/accounts-access"}
                 >
                   Accounts & Access
                 </SidebarTab>
               )}
               <SidebarTab
                 href="/app/settings/connectors"
-                transient={pathname === "/app/settings/connectors"}
+                selected={pathname === "/app/settings/connectors"}
               >
                 Connectors
               </SidebarTab>
diff --git a/web/src/app/craft/components/SideBar.tsx b/web/src/app/craft/components/SideBar.tsx
index f26171c3de1..973ced4af95 100644
--- a/web/src/app/craft/components/SideBar.tsx
+++ b/web/src/app/craft/components/SideBar.tsx
@@ -224,9 +224,8 @@ function BuildSessionButton({
         <Popover.Anchor>
           <SidebarTab
             onClick={onLoad}
-            transient={isActive}
+            selected={isActive}
             rightChildren={rightMenu}
-            focused={renaming}
           >
             {renaming ? (
               <ButtonRenaming
@@ -366,11 +365,7 @@ const MemoizedBuildSidebarInner = memo(
 
     const newBuildButton = useMemo(
       () => (
-        <SidebarTab
-          leftIcon={SvgEditBig}
-          folded={folded}
-          onClick={handleNewBuild}
-        >
+        <SidebarTab icon={SvgEditBig} folded={folded} onClick={handleNewBuild}>
           Start Crafting
         </SidebarTab>
       ),
@@ -380,10 +375,10 @@ const MemoizedBuildSidebarInner = memo(
     const buildConfigurePanel = useMemo(
       () => (
         <SidebarTab
-          leftIcon={SvgSettings}
+          icon={SvgSettings}
           folded={folded}
           href={CRAFT_CONFIGURE_PATH}
-          transient={pathname.startsWith(CRAFT_CONFIGURE_PATH)}
+          selected={pathname.startsWith(CRAFT_CONFIGURE_PATH)}
         >
           Configure
         </SidebarTab>
@@ -393,7 +388,7 @@ const MemoizedBuildSidebarInner = memo(
 
     const backToChatButton = useMemo(
       () => (
-        <SidebarTab leftIcon={SvgArrowLeft} folded={folded} href="/app">
+        <SidebarTab icon={SvgArrowLeft} folded={folded} href="/app">
           Back to Chat
         </SidebarTab>
       ),
diff --git a/web/src/ee/sections/SearchUI.tsx b/web/src/ee/sections/SearchUI.tsx
index 29f1b8757b0..f8a6bc4b8b1 100644
--- a/web/src/ee/sections/SearchUI.tsx
+++ b/web/src/ee/sections/SearchUI.tsx
@@ -10,6 +10,8 @@ import SearchCard from "@/ee/sections/SearchCard";
 import Pagination from "@/refresh-components/Pagination";
 import Separator from "@/refresh-components/Separator";
 import EmptyMessage from "@/refresh-components/EmptyMessage";
+import { IllustrationContent } from "@opal/layouts";
+import SvgNoResult from "@opal/illustrations/no-result";
 import { getSourceMetadata } from "@/lib/sources";
 import { Tag, ValidSources } from "@/lib/types";
 import { getTimeFilterDate, TimeFilter } from "@/lib/time";
@@ -329,9 +331,10 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
               ))}
             </>
           ) : (
-            <EmptyMessage
-              title="No documents found"
-              description="Try searching for something else"
+            <IllustrationContent
+              illustration={SvgNoResult}
+              title="No results found"
+              description="Check your connectors/filters or try a different search term."
             />
           )}
         </div>
diff --git a/web/src/refresh-components/buttons/SidebarTab.tsx b/web/src/refresh-components/buttons/SidebarTab.tsx
index 44f63803b34..a2f9d119371 100644
--- a/web/src/refresh-components/buttons/SidebarTab.tsx
+++ b/web/src/refresh-components/buttons/SidebarTab.tsx
@@ -1,107 +1,116 @@
 "use client";
 
 import React from "react";
-import type { IconProps } from "@opal/types";
-import { cn } from "@/lib/utils";
-import SimpleTooltip from "@/refresh-components/SimpleTooltip";
-import Link from "next/link";
+import type { IconFunctionComponent, IconProps } from "@opal/types";
 import type { Route } from "next";
-import Truncated from "@/refresh-components/texts/Truncated";
+import { Interactive } from "@opal/core";
+import { ContentAction } from "@opal/layouts";
+import Link from "next/link";
+import SimpleTooltip from "@/refresh-components/SimpleTooltip";
 
 export interface SidebarTabProps {
   // Button states:
   folded?: boolean;
-  transient?: boolean;
-  focused?: boolean;
+  selected?: boolean;
   lowlight?: boolean;
   nested?: boolean;
 
   // Button properties:
-  onClick?: React.MouseEventHandler<HTMLDivElement>;
+  onClick?: React.MouseEventHandler<HTMLElement>;
   href?: string;
-  className?: string;
-  leftIcon?: React.FunctionComponent<IconProps>;
-  rightChildren?: React.ReactNode;
+  icon?: React.FunctionComponent<IconProps>;
   children?: React.ReactNode;
+  rightChildren?: React.ReactNode;
 }
 
 export default function SidebarTab({
   folded,
-  transient,
-  focused,
+  selected,
   lowlight,
   nested,
 
   onClick,
   href,
-  className,
-  leftIcon: LeftIcon,
+  icon,
   rightChildren,
   children,
 }: SidebarTabProps) {
-  const variant = lowlight ? "lowlight" : focused ? "focused" : "defaulted";
-  const state = transient ? "active" : "inactive";
+  const Icon =
+    icon ??
+    (nested
+      ? ((() => (
+          <div className="w-6" aria-hidden="true" />
+        )) as IconFunctionComponent)
+      : null);
+
+  // NOTE (@raunakab)
+  //
+  // The `rightChildren` node NEEDS to be absolutely positioned since it needs to live on top of the absolutely positioned `Link`.
+  // However, having the `rightChildren` be absolutely positioned means that it cannot appropriately truncate the title.
+  // Therefore, we add a dummy node solely for the truncation effects that we obtain.
+  const truncationSpacer = rightChildren && (
+    <div className="w-0 group-hover/SidebarTab:w-6" />
+  );
 
   const content = (
-    <div
-      data-state={state}
-      className={cn(
-        "relative flex flex-row justify-start items-start p-1.5 gap-1 rounded-08 cursor-pointer group/SidebarTab w-full select-none",
-        `sidebar-tab-background-${variant}`,
-        className
-      )}
-      onClick={onClick}
-    >
-      {href && (
-        <Link
-          href={href as Route}
-          scroll={false}
-          className="absolute inset-0 rounded-08"
-          tabIndex={-1}
-        />
-      )}
-      <div
-        data-state={state}
-        className={cn(
-          "relative flex-1 h-[1.5rem] flex flex-row items-center px-1 py-0.5 gap-2 justify-start",
-          !focused && "pointer-events-none"
-        )}
+    <div className="relative">
+      <Interactive.Base
+        variant="sidebar"
+        selected={selected}
+        onClick={onClick}
+        group="group/SidebarTab"
       >
-        {nested && !LeftIcon && (
-          <div className="w-4 shrink-0" aria-hidden="true" />
-        )}
-        {LeftIcon && (
-          <div
-            className={cn(
-              "w-[1rem] flex items-center justify-center",
-              !folded && "pointer-events-auto"
-            )}
-          >
-            <LeftIcon
-              data-state={state}
-              className={`h-[1rem] w-[1rem] sidebar-tab-icon-${variant}`}
+        <Interactive.Container
+          roundingVariant="compact"
+          heightVariant="lg"
+          widthVariant="full"
+        >
+          {href && (
+            <Link
+              href={href as Route}
+              scroll={false}
+              className="absolute z-[99] inset-0 rounded-08"
+              tabIndex={-1}
+            />
+          )}
+
+          {!folded && rightChildren && (
+            <div className="absolute z-[100] right-1.5 top-0 bottom-0 flex flex-col justify-center items-center pointer-events-auto">
+              {rightChildren}
+            </div>
+          )}
+
+          {typeof children === "string" ? (
+            <ContentAction
+              icon={Icon ?? undefined}
+              title={folded ? "" : children}
+              sizePreset="main-ui"
+              variant="body"
+              prominence={
+                lowlight ? "muted-2x" : selected ? "default" : "muted"
+              }
+              widthVariant="full"
+              paddingVariant="fit"
+              rightChildren={truncationSpacer}
             />
-          </div>
-        )}
-        {!folded &&
-          (typeof children === "string" ? (
-            <Truncated
-              data-state={state}
-              className={`sidebar-tab-text-${variant}`}
-              side="right"
-              sideOffset={40}
-            >
-              {children}
-            </Truncated>
           ) : (
-            children
-          ))}
-      </div>
-      {!folded && (
-        <div className="relative h-[1.5rem] flex items-center">
-          {rightChildren}
-        </div>
-      )}
+            <div className="flex flex-row items-center gap-2 flex-1">
+              {Icon && (
+                <div className="flex items-center justify-center p-0.5">
+                  <Icon className="h-[1rem] w-[1rem] text-text-03" />
+                </div>
+              )}
+              {children}
+              {
+                // NOTE (@raunakab)
+                //
+                // Adding the `truncationSpacer` here for the same reason as above.
+                truncationSpacer
+              }
+            </div>
+          )}
+        </Interactive.Container>
+      </Interactive.Base>
     </div>
   );
 
diff --git a/web/src/sections/sidebar/AdminSidebar.tsx b/web/src/sections/sidebar/AdminSidebar.tsx
index eb797d931e3..07363141651 100644
--- a/web/src/sections/sidebar/AdminSidebar.tsx
+++ b/web/src/sections/sidebar/AdminSidebar.tsx
@@ -214,7 +214,7 @@ export default function AdminSidebar({
         scrollKey="admin-sidebar"
         actionButtons={
           <SidebarTab
-            leftIcon={({ className }) => (
+            icon={({ className }) => (
               <CgArrowsExpandUpLeft className={className} size={16} />
             )}
             href="/app"
@@ -240,8 +240,8 @@ export default function AdminSidebar({
                 <SidebarTab
                   key={index}
                   href={link}
-                  transient={pathname.startsWith(link)}
-                  leftIcon={({ className }) => (
+                  selected={pathname.startsWith(link)}
+                  icon={({ className }) => (
                     <Icon className={className} size={16} />
                   )}
                 >
diff --git a/web/src/sections/sidebar/AgentButton.tsx b/web/src/sections/sidebar/AgentButton.tsx
index bb523fd66b8..fac1ea39f5d 100644
--- a/web/src/sections/sidebar/AgentButton.tsx
+++ b/web/src/sections/sidebar/AgentButton.tsx
@@ -63,10 +63,10 @@ const AgentButton = memo(({ agent }: AgentButtonProps) => {
       <div className="flex flex-col w-full h-full">
         <SidebarTab
           key={agent.id}
-          leftIcon={() => <AgentAvatar agent={agent} />}
+          icon={() => <AgentAvatar agent={agent} />}
           href={`/app?agentId=${agent.id}`}
           onClick={handleClick}
-          transient={isCurrentAgent}
+          selected={isCurrentAgent}
           rightChildren={
             // Hide unpin button for current agent since auto-pin would immediately re-pin
             isCurrentAgent ? null : (
diff --git a/web/src/sections/sidebar/AppSidebar.tsx b/web/src/sections/sidebar/AppSidebar.tsx
index 52bc6d9783b..a58e8241087 100644
--- a/web/src/sections/sidebar/AppSidebar.tsx
+++ b/web/src/sections/sidebar/AppSidebar.tsx
@@ -500,10 +500,10 @@ const MemoizedAppSidebarInner = memo(
       return (
         <div data-testid="AppSidebar/new-session">
           <SidebarTab
-            leftIcon={SvgEditBig}
+            icon={SvgEditBig}
             folded={folded}
             href={href}
-            transient={activeSidebarTab.isNewSession()}
+            selected={activeSidebarTab.isNewSession()}
             onClick={() => {
               if (!activeSidebarTab.isNewSession()) return;
               setAppMode(defaultAppMode);
@@ -526,7 +526,7 @@ const MemoizedAppSidebarInner = memo(
       () => (
         <div data-testid="AppSidebar/build">
           <SidebarTab
-            leftIcon={SvgDevKit}
+            icon={SvgDevKit}
             folded={folded}
             href={CRAFT_PATH}
             onClick={() => posthog?.capture("clicked_craft_in_sidebar")}
@@ -542,7 +542,18 @@ const MemoizedAppSidebarInner = memo(
       () => (
         <ChatSearchCommandMenu
           trigger={
-            <SidebarTab leftIcon={SvgSearchMenu} folded={folded}>
+            <SidebarTab
+              icon={SvgSearchMenu}
+              folded={folded}
+              // TODO (@raunakab)
+              //
+              // The internals of `SidebarTab` (`Interactive.Base`) was designed such that providing an `onClick` or `href` would trigger rendering a `cursor-pointer`.
+              // However, since instance is wired up as a "trigger", it doesn't have either of those explicitly specified.
+              // Therefore, the default cursor would be rendered.
+              //
+              // Specifying a dummy `onClick` handler solves that.
+              onClick={() => undefined}
+            >
               Search Chats
             </SidebarTab>
           }
@@ -554,14 +565,14 @@ const MemoizedAppSidebarInner = memo(
       () => (
         <div data-testid="AppSidebar/more-agents">
           <SidebarTab
-            leftIcon={
+            icon={
               folded || visibleAgents.length === 0
                 ? SvgOnyxOctagon
                 : SvgMoreHorizontal
             }
             href="/app/agents"
             folded={folded}
-            transient={activeSidebarTab.isMoreAgents()}
+            selected={activeSidebarTab.isMoreAgents()}
             lowlight={!folded}
           >
             {visibleAgents.length === 0 ? "Explore Agents" : "More Agents"}
@@ -573,9 +584,9 @@ const MemoizedAppSidebarInner = memo(
     const newProjectButton = useMemo(
       () => (
         <SidebarTab
-          leftIcon={SvgFolderPlus}
+          icon={SvgFolderPlus}
           onClick={() => createProjectModal.toggle(true)}
-          transient={createProjectModal.isOpen}
+          selected={createProjectModal.isOpen}
           folded={folded}
           lowlight={!folded}
         >
@@ -600,7 +611,7 @@ const MemoizedAppSidebarInner = memo(
           {(isAdmin || isCurator) && (
             <SidebarTab
               href={adminDefaultHref}
-              leftIcon={SvgSettings}
+              icon={SvgSettings}
               folded={folded}
             >
               {isAdmin ? "Admin Panel" : "Curator Panel"}
@@ -693,7 +704,7 @@ const MemoizedAppSidebarInner = memo(
             scrollKey="app-sidebar"
             footer={settingsButton}
             actionButtons={
-              <div className="flex flex-col gap-0.5">
+              <div className="flex flex-col">
                 {newSessionButton}
                 {searchChatsButton}
                 {isOnyxCraftEnabled && buildButton}
diff --git a/web/src/sections/sidebar/ChatButton.tsx b/web/src/sections/sidebar/ChatButton.tsx
index c47d980603e..7f9e9329daf 100644
--- a/web/src/sections/sidebar/ChatButton.tsx
+++ b/web/src/sections/sidebar/ChatButton.tsx
@@ -429,9 +429,8 @@ const ChatButton = memo(
           <SidebarTab
             href={isDragging ? undefined : `/app?chatId=${chatSession.id}`}
             onClick={handleClick}
-            transient={active}
+            selected={active}
             rightChildren={rightMenu}
-            focused={renaming}
             nested={!!project}
           >
             {renaming ? (
diff --git a/web/src/sections/sidebar/ProjectFolderButton.tsx b/web/src/sections/sidebar/ProjectFolderButton.tsx
index 93b0301d864..bf9bf559f20 100644
--- a/web/src/sections/sidebar/ProjectFolderButton.tsx
+++ b/web/src/sections/sidebar/ProjectFolderButton.tsx
@@ -137,7 +137,7 @@ const ProjectFolderButton = memo(({ project }: ProjectFolderButtonProps) => {
       <Popover onOpenChange={setPopoverOpen}>
         <Popover.Anchor>
           <SidebarTab
-            leftIcon={() => (
+            icon={() => (
               <OpalButton
                 onMouseEnter={() => handleIconHover(true)}
                 onMouseLeave={() => handleIconHover(false)}
@@ -147,12 +147,11 @@ const ProjectFolderButton = memo(({ project }: ProjectFolderButtonProps) => {
                 onClick={noProp(handleIconClick)}
               />
             )}
-            transient={
+            selected={
               activeSidebar.isProject() &&
               activeSidebar.getId() === String(project.id)
             }
             onClick={noProp(handleTextClick)}
-            focused={isEditing}
             rightChildren={
               <>
                 <Popover.Trigger asChild onClick={noProp()}>
diff --git a/web/src/sections/sidebar/StepSidebarWrapper.tsx b/web/src/sections/sidebar/StepSidebarWrapper.tsx
index c30be49afd5..78522e542ad 100644
--- a/web/src/sections/sidebar/StepSidebarWrapper.tsx
+++ b/web/src/sections/sidebar/StepSidebarWrapper.tsx
@@ -19,11 +19,7 @@ export default function StepSidebar({
   return (
     <SidebarWrapper>
       <div className="px-2">
-        <SidebarTab
-          leftIcon={buttonIcon}
-          className="bg-background-tint-00"
-          href={buttonHref}
-        >
+        <SidebarTab icon={buttonIcon} href={buttonHref}>
           {buttonName}
         </SidebarTab>
       </div>
diff --git a/web/src/sections/sidebar/UserAvatarPopover.tsx b/web/src/sections/sidebar/UserAvatarPopover.tsx
index 17db2aa4604..0b95e6afb40 100644
--- a/web/src/sections/sidebar/UserAvatarPopover.tsx
+++ b/web/src/sections/sidebar/UserAvatarPopover.tsx
@@ -201,7 +201,7 @@ export default function UserAvatarPopover({
       <Popover.Trigger asChild>
         <div id="onyx-user-dropdown">
           <SidebarTab
-            leftIcon={({ className }) => (
+            icon={({ className }) => (
               <InputAvatar
                 className={cn(
                   "flex items-center justify-center bg-background-neutral-inverted-00",
@@ -221,8 +221,16 @@ export default function UserAvatarPopover({
                 </Section>
               ) : undefined
             }
-            transient={!!popupState || appFocus.isUserSettings()}
+            selected={!!popupState || appFocus.isUserSettings()}
             folded={folded}
+            // TODO (@raunakab)
+            //
+            // The internals of `SidebarTab` (`Interactive.Base`) was designed such that providing an `onClick` or `href` would trigger rendering a `cursor-pointer`.
+            // However, since instance is wired up as a "trigger", it doesn't have either of those explicitly specified.
+            // Therefore, the default cursor would be rendered.
+            //
+            // Specifying a dummy `onClick` handler solves that.
+            onClick={() => undefined}
           >
             {displayName}
           </SidebarTab>

From 96f7cbd25a12857182c1c817d36128fba961d1eb Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Wed, 4 Mar 2026 08:54:23 -0800
Subject: [PATCH 075/267] fix: Use `IllustrationContent` for empty search
 results (#9013)

---
 .../IllustrationContent/components.tsx        | 11 ++-
 web/src/ee/sections/SearchUI.tsx              | 94 +++++++++++--------
 2 files changed, 60 insertions(+), 45 deletions(-)

diff --git a/web/lib/opal/src/layouts/IllustrationContent/components.tsx b/web/lib/opal/src/layouts/IllustrationContent/components.tsx
index fdac4a585ac..9a049e470d5 100644
--- a/web/lib/opal/src/layouts/IllustrationContent/components.tsx
+++ b/web/lib/opal/src/layouts/IllustrationContent/components.tsx
@@ -37,7 +37,6 @@ interface IllustrationContentProps {
  * │     └───────────────────┘       │
  * │         (0.75rem gap)           │
  * │          title (center)         │
- * │         (0.75rem gap)           │
  * │      description (center)       │
  * │          (1.25rem pad)          │
  * └─────────────────────────────────┘
@@ -68,10 +67,12 @@ function IllustrationContent({
           className="shrink-0 w-[7.5rem] h-[7.5rem]"
         />
       )}
-      <p className="font-main-content-emphasis text-text-04">{title}</p>
-      {description && (
-        <p className="font-secondary-body text-text-03">{description}</p>
-      )}
+      <div className="flex flex-col items-center text-center">
+        <p className="font-main-content-emphasis text-text-04">{title}</p>
+        {description && (
+          <p className="font-secondary-body text-text-03">{description}</p>
+        )}
+      </div>
     </div>
   );
 }
diff --git a/web/src/ee/sections/SearchUI.tsx b/web/src/ee/sections/SearchUI.tsx
index f8a6bc4b8b1..47d88e604b6 100644
--- a/web/src/ee/sections/SearchUI.tsx
+++ b/web/src/ee/sections/SearchUI.tsx
@@ -26,6 +26,7 @@ import FilterButton from "@/refresh-components/buttons/FilterButton";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useFilter from "@/hooks/useFilter";
 import { useQueryController } from "@/providers/QueryControllerProvider";
+import { cn } from "@/lib/utils";
 import { toast } from "@/hooks/useToast";
 
 // ============================================================================
@@ -194,12 +195,14 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
     }
   };
 
+  const showEmpty = !error && results.length === 0;
+
   return (
     <>
       <div
         className="flex-1 min-h-0 w-full grid gap-x-4"
         style={{
-          gridTemplateColumns: "3fr 1fr",
+          gridTemplateColumns: showEmpty ? "1fr" : "3fr 1fr",
           gridTemplateRows: "auto 1fr auto",
         }}
       >
@@ -305,18 +308,25 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
         </div>
 
         {/* Top-right: Number of results */}
-        <div className="row-start-1 col-start-2 flex flex-col justify-end gap-3">
-          <Section alignItems="start">
-            <Text text03 mainUiMuted>
-              {results.length} Results
-            </Text>
-          </Section>
-
-          <Separator noPadding />
-        </div>
+        {!showEmpty && (
+          <div className="row-start-1 col-start-2 flex flex-col justify-end gap-3">
+            <Section alignItems="start">
+              <Text text03 mainUiMuted>
+                {results.length} Results
+              </Text>
+            </Section>
+
+            <Separator noPadding />
+          </div>
+        )}
 
         {/* Bottom-left: Search results */}
-        <div className="row-start-2 col-start-1 min-h-0 overflow-y-scroll py-3 flex flex-col gap-2">
+        <div
+          className={cn(
+            "row-start-2 col-start-1 min-h-0 overflow-y-scroll py-3 flex flex-col gap-2",
+            showEmpty && "justify-center"
+          )}
+        >
           {error ? (
             <EmptyMessage title="Search failed" description={error} />
           ) : paginatedResults.length > 0 ? (
@@ -340,37 +350,41 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
         </div>
 
         {/* Pagination */}
-        <div className="row-start-3 col-start-1 col-span-2 pt-3">
-          <Pagination
-            currentPage={currentPage}
-            totalPages={totalPages}
-            onPageChange={setCurrentPage}
-          />
-        </div>
+        {!showEmpty && (
+          <div className="row-start-3 col-start-1 col-span-2 pt-3">
+            <Pagination
+              currentPage={currentPage}
+              totalPages={totalPages}
+              onPageChange={setCurrentPage}
+            />
+          </div>
+        )}
 
         {/* Bottom-right: Source filter */}
-        <div className="row-start-2 col-start-2 min-h-0 overflow-y-auto flex flex-col gap-4 px-1 py-3">
-          <Section gap={0.25} height="fit">
-            {sourcesWithMeta.map(({ source, meta, count }) => (
-              <LineItem
-                key={source}
-                icon={(props) => (
-                  <SourceIcon
-                    sourceType={source as ValidSources}
-                    iconSize={16}
-                    {...props}
-                  />
-                )}
-                onClick={() => handleSourceToggle(source)}
-                selected={selectedSources.includes(source)}
-                emphasized
-                rightChildren={<Text text03>{count}</Text>}
-              >
-                {meta.displayName}
-              </LineItem>
-            ))}
-          </Section>
-        </div>
+        {!showEmpty && (
+          <div className="row-start-2 col-start-2 min-h-0 overflow-y-auto flex flex-col gap-4 px-1 py-3">
+            <Section gap={0.25} height="fit">
+              {sourcesWithMeta.map(({ source, meta, count }) => (
+                <LineItem
+                  key={source}
+                  icon={(props) => (
+                    <SourceIcon
+                      sourceType={source as ValidSources}
+                      iconSize={16}
+                      {...props}
+                    />
+                  )}
+                  onClick={() => handleSourceToggle(source)}
+                  selected={selectedSources.includes(source)}
+                  emphasized
+                  rightChildren={<Text text03>{count}</Text>}
+                >
+                  {meta.displayName}
+                </LineItem>
+              ))}
+            </Section>
+          </div>
+        )}
       </div>
     </>
   );

From 0f74da33020ff839a6baf86ec051810736cdd16f Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 4 Mar 2026 09:46:35 -0800
Subject: [PATCH 076/267] fix(fe): dont align center modals on small screens
 (#8988)

---
 web/src/hooks/useContainerCenter.ts | 10 +++++++---
 web/src/hooks/useScreenSize.ts      | 10 ++++++++--
 web/src/lib/constants.ts            |  1 +
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/web/src/hooks/useContainerCenter.ts b/web/src/hooks/useContainerCenter.ts
index b17aef1b5d9..311ecbbebca 100644
--- a/web/src/hooks/useContainerCenter.ts
+++ b/web/src/hooks/useContainerCenter.ts
@@ -2,6 +2,7 @@
 
 import { useState, useEffect } from "react";
 import { usePathname } from "next/navigation";
+import useScreenSize from "@/hooks/useScreenSize";
 
 const SELECTOR = "[data-main-container]";
 
@@ -37,6 +38,7 @@ function measure(el: HTMLElement): { x: number; y: number } | null {
  */
 export default function useContainerCenter(): ContainerCenter {
   const pathname = usePathname();
+  const { isSmallScreen } = useScreenSize();
   const [center, setCenter] = useState<{ x: number | null; y: number | null }>(
     () => {
       if (typeof document === "undefined") return NULL_CENTER;
@@ -66,8 +68,10 @@ export default function useContainerCenter(): ContainerCenter {
   }, [pathname]);
 
   return {
-    centerX: center.x,
-    centerY: center.y,
-    hasContainerCenter: center.x !== null && center.y !== null,
+    centerX: isSmallScreen ? null : center.x,
+    centerY: isSmallScreen ? null : center.y,
+    hasContainerCenter: isSmallScreen
+      ? false
+      : center.x !== null && center.y !== null,
   };
 }
diff --git a/web/src/hooks/useScreenSize.ts b/web/src/hooks/useScreenSize.ts
index 610135192a6..dc08b508909 100644
--- a/web/src/hooks/useScreenSize.ts
+++ b/web/src/hooks/useScreenSize.ts
@@ -1,6 +1,9 @@
 "use client";
 
-import { MOBILE_SIDEBAR_BREAKPOINT_PX } from "@/lib/constants";
+import {
+  DESKTOP_SMALL_BREAKPOINT_PX,
+  MOBILE_SIDEBAR_BREAKPOINT_PX,
+} from "@/lib/constants";
 import { useState, useCallback } from "react";
 import useOnMount from "@/hooks/useOnMount";
 
@@ -8,6 +11,7 @@ export interface ScreenSize {
   height: number;
   width: number;
   isMobile: boolean;
+  isSmallScreen: boolean;
 }
 
 export default function useScreenSize(): ScreenSize {
@@ -29,10 +33,12 @@ export default function useScreenSize(): ScreenSize {
   });
 
   const isMobile = sizes.width <= MOBILE_SIDEBAR_BREAKPOINT_PX;
+  const isSmall = sizes.width <= DESKTOP_SMALL_BREAKPOINT_PX;
 
   return {
     height: sizes.height,
     width: sizes.width,
-    isMobile: isMounted ? isMobile : false,
+    isMobile: isMounted && isMobile,
+    isSmallScreen: isMounted && isSmall,
   };
 }
diff --git a/web/src/lib/constants.ts b/web/src/lib/constants.ts
index 9a447868d44..ba106168938 100644
--- a/web/src/lib/constants.ts
+++ b/web/src/lib/constants.ts
@@ -117,6 +117,7 @@ export const MAX_FILES_TO_SHOW = 3;
 
 // SIZES
 export const MOBILE_SIDEBAR_BREAKPOINT_PX = 640;
+export const DESKTOP_SMALL_BREAKPOINT_PX = 912;
 export const DEFAULT_AGENT_AVATAR_SIZE_PX = 18;
 export const HORIZON_DISTANCE_PX = 800;
 export const LOGO_FOLDED_SIZE_PX = 24;

From 367808951c8585517a1ef87b69cace1dfbfad33f Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Wed, 4 Mar 2026 10:26:05 -0800
Subject: [PATCH 077/267] chore: remove lightweight mode (#9014)

---
 .github/workflows/pr-integration-tests.yml    |   1 -
 .vscode/launch.json                           |  43 +---
 AGENTS.md                                     |  31 ---
 .../onyx/background/celery/apps/background.py |  15 --
 .../onyx/background/celery/apps/background.py | 142 -------------
 .../background/celery/configs/background.py   |  23 --
 .../celery/versioned_apps/background.py       |  10 -
 backend/onyx/configs/app_configs.py           |   9 +-
 backend/onyx/configs/constants.py             |   1 -
 backend/scripts/dev_run_background_jobs.py    | 197 ++++++------------
 backend/scripts/supervisord_entrypoint.sh     |  20 +-
 backend/supervisord.conf                      |  28 ---
 .../docker-compose.multitenant-dev.yml        |   1 -
 .../docker-compose.prod-cloud.yml             |   1 -
 .../docker-compose.prod-no-letsencrypt.yml    |   1 -
 .../docker_compose/docker-compose.prod.yml    |   1 -
 .../docker-compose.search-testing.yml         |   1 -
 deployment/docker_compose/docker-compose.yml  |   1 -
 18 files changed, 64 insertions(+), 462 deletions(-)
 delete mode 100644 backend/ee/onyx/background/celery/apps/background.py
 delete mode 100644 backend/onyx/background/celery/apps/background.py
 delete mode 100644 backend/onyx/background/celery/configs/background.py
 delete mode 100644 backend/onyx/background/celery/versioned_apps/background.py

diff --git a/.github/workflows/pr-integration-tests.yml b/.github/workflows/pr-integration-tests.yml
index 07b608522a4..18357102459 100644
--- a/.github/workflows/pr-integration-tests.yml
+++ b/.github/workflows/pr-integration-tests.yml
@@ -335,7 +335,6 @@ jobs:
           # TODO(Nik): https://linear.app/onyx-app/issue/ENG-1/update-test-infra-to-use-test-license
           LICENSE_ENFORCEMENT_ENABLED=false
           CHECK_TTL_MANAGEMENT_TASK_FREQUENCY_IN_HOURS=0.001
-          USE_LIGHTWEIGHT_BACKGROUND_WORKER=false
           EOF
           fi
 
diff --git a/.vscode/launch.json b/.vscode/launch.json
index 41a8164c45f..09f9c5bf55a 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -40,19 +40,7 @@
       }
     },
     {
-      "name": "Celery (lightweight mode)",
-      "configurations": [
-        "Celery primary",
-        "Celery background",
-        "Celery beat"
-      ],
-      "presentation": {
-        "group": "1"
-      },
-      "stopAll": true
-    },
-    {
-      "name": "Celery (standard mode)",
+      "name": "Celery",
       "configurations": [
         "Celery primary",
         "Celery light",
@@ -253,35 +241,6 @@
       },
       "consoleTitle": "Celery light Console"
     },
-    {
-      "name": "Celery background",
-      "type": "debugpy",
-      "request": "launch",
-      "module": "celery",
-      "cwd": "${workspaceFolder}/backend",
-      "envFile": "${workspaceFolder}/.vscode/.env",
-      "env": {
-        "LOG_LEVEL": "INFO",
-        "PYTHONUNBUFFERED": "1",
-        "PYTHONPATH": "."
-      },
-      "args": [
-        "-A",
-        "onyx.background.celery.versioned_apps.background",
-        "worker",
-        "--pool=threads",
-        "--concurrency=20",
-        "--prefetch-multiplier=4",
-        "--loglevel=INFO",
-        "--hostname=background@%n",
-        "-Q",
-        "vespa_metadata_sync,connector_deletion,doc_permissions_upsert,checkpoint_cleanup,index_attempt_cleanup,docprocessing,connector_doc_fetching,connector_pruning,connector_doc_permissions_sync,connector_external_group_sync,csv_generation,kg_processing,monitoring,user_file_processing,user_file_project_sync,user_file_delete,opensearch_migration"
-      ],
-      "presentation": {
-        "group": "2"
-      },
-      "consoleTitle": "Celery background Console"
-    },
     {
       "name": "Celery heavy",
       "type": "debugpy",
diff --git a/AGENTS.md b/AGENTS.md
index 24ff123383d..9b6f5a3ddaa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,37 +86,6 @@ Onyx uses Celery for asynchronous task processing with multiple specialized work
      - Monitoring tasks (every 5 minutes)
      - Cleanup tasks (hourly)
 
-#### Worker Deployment Modes
-
-Onyx supports two deployment modes for background workers, controlled by the `USE_LIGHTWEIGHT_BACKGROUND_WORKER` environment variable:
-
-**Lightweight Mode** (default, `USE_LIGHTWEIGHT_BACKGROUND_WORKER=true`):
-
-- Runs a single consolidated `background` worker that handles all background tasks:
-  - Light worker tasks (Vespa operations, permissions sync, deletion)
-  - Document processing (indexing pipeline)
-  - Document fetching (connector data retrieval)
-  - Pruning operations (from `heavy` worker)
-  - Knowledge graph processing (from `kg_processing` worker)
-  - Monitoring tasks (from `monitoring` worker)
-  - User file processing (from `user_file_processing` worker)
-- Lower resource footprint (fewer worker processes)
-- Suitable for smaller deployments or development environments
-- Default concurrency: 20 threads (increased to handle combined workload)
-
-**Standard Mode** (`USE_LIGHTWEIGHT_BACKGROUND_WORKER=false`):
-
-- Runs separate specialized workers as documented above (light, docprocessing, docfetching, heavy, kg_processing, monitoring, user_file_processing)
-- Better isolation and scalability
-- Can scale individual workers independently based on workload
-- Suitable for production deployments with higher load
-
-The deployment mode affects:
-
-- **Backend**: Worker processes spawned by supervisord or dev scripts
-- **Helm**: Which Kubernetes deployments are created
-- **Dev Environment**: Which workers `dev_run_background_jobs.py` spawns
-
 #### Key Features
 
 - **Thread-based Workers**: All workers use thread pools (not processes) for stability
diff --git a/backend/ee/onyx/background/celery/apps/background.py b/backend/ee/onyx/background/celery/apps/background.py
deleted file mode 100644
index 45fb0bc4702..00000000000
--- a/backend/ee/onyx/background/celery/apps/background.py
+++ /dev/null
@@ -1,15 +0,0 @@
-from onyx.background.celery.apps import app_base
-from onyx.background.celery.apps.background import celery_app
-
-
-celery_app.autodiscover_tasks(
-    app_base.filter_task_modules(
-        [
-            "ee.onyx.background.celery.tasks.doc_permission_syncing",
-            "ee.onyx.background.celery.tasks.external_group_syncing",
-            "ee.onyx.background.celery.tasks.cleanup",
-            "ee.onyx.background.celery.tasks.tenant_provisioning",
-            "ee.onyx.background.celery.tasks.query_history",
-        ]
-    )
-)
diff --git a/backend/onyx/background/celery/apps/background.py b/backend/onyx/background/celery/apps/background.py
deleted file mode 100644
index 137d14bdb3e..00000000000
--- a/backend/onyx/background/celery/apps/background.py
+++ /dev/null
@@ -1,142 +0,0 @@
-from typing import Any
-from typing import cast
-
-from celery import Celery
-from celery import signals
-from celery import Task
-from celery.apps.worker import Worker
-from celery.signals import celeryd_init
-from celery.signals import worker_init
-from celery.signals import worker_process_init
-from celery.signals import worker_ready
-from celery.signals import worker_shutdown
-
-import onyx.background.celery.apps.app_base as app_base
-from onyx.background.celery.celery_utils import httpx_init_vespa_pool
-from onyx.configs.app_configs import MANAGED_VESPA
-from onyx.configs.app_configs import VESPA_CLOUD_CERT_PATH
-from onyx.configs.app_configs import VESPA_CLOUD_KEY_PATH
-from onyx.configs.constants import POSTGRES_CELERY_WORKER_BACKGROUND_APP_NAME
-from onyx.db.engine.sql_engine import SqlEngine
-from onyx.utils.logger import setup_logger
-from shared_configs.configs import MULTI_TENANT
-
-
-logger = setup_logger()
-
-celery_app = Celery(__name__)
-celery_app.config_from_object("onyx.background.celery.configs.background")
-celery_app.Task = app_base.TenantAwareTask  # type: ignore [misc]
-
-
-@signals.task_prerun.connect
-def on_task_prerun(
-    sender: Any | None = None,
-    task_id: str | None = None,
-    task: Task | None = None,
-    args: tuple | None = None,
-    kwargs: dict | None = None,
-    **kwds: Any,
-) -> None:
-    app_base.on_task_prerun(sender, task_id, task, args, kwargs, **kwds)
-
-
-@signals.task_postrun.connect
-def on_task_postrun(
-    sender: Any | None = None,
-    task_id: str | None = None,
-    task: Task | None = None,
-    args: tuple | None = None,
-    kwargs: dict | None = None,
-    retval: Any | None = None,
-    state: str | None = None,
-    **kwds: Any,
-) -> None:
-    app_base.on_task_postrun(sender, task_id, task, args, kwargs, retval, state, **kwds)
-
-
-@celeryd_init.connect
-def on_celeryd_init(sender: str, conf: Any = None, **kwargs: Any) -> None:
-    app_base.on_celeryd_init(sender, conf, **kwargs)
-
-
-@worker_init.connect
-def on_worker_init(sender: Worker, **kwargs: Any) -> None:
-    EXTRA_CONCURRENCY = 8  # small extra fudge factor for connection limits
-
-    logger.info("worker_init signal received for consolidated background worker.")
-
-    SqlEngine.set_app_name(POSTGRES_CELERY_WORKER_BACKGROUND_APP_NAME)
-    pool_size = cast(int, sender.concurrency)  # type: ignore
-    SqlEngine.init_engine(pool_size=pool_size, max_overflow=EXTRA_CONCURRENCY)
-
-    # Initialize Vespa httpx pool (needed for light worker tasks)
-    if MANAGED_VESPA:
-        httpx_init_vespa_pool(
-            sender.concurrency + EXTRA_CONCURRENCY,  # type: ignore
-            ssl_cert=VESPA_CLOUD_CERT_PATH,
-            ssl_key=VESPA_CLOUD_KEY_PATH,
-        )
-    else:
-        httpx_init_vespa_pool(sender.concurrency + EXTRA_CONCURRENCY)  # type: ignore
-
-    app_base.wait_for_redis(sender, **kwargs)
-    app_base.wait_for_db(sender, **kwargs)
-    app_base.wait_for_vespa_or_shutdown(sender, **kwargs)
-
-    # Less startup checks in multi-tenant case
-    if MULTI_TENANT:
-        return
-
-    app_base.on_secondary_worker_init(sender, **kwargs)
-
-
-@worker_ready.connect
-def on_worker_ready(sender: Any, **kwargs: Any) -> None:
-    app_base.on_worker_ready(sender, **kwargs)
-
-
-@worker_shutdown.connect
-def on_worker_shutdown(sender: Any, **kwargs: Any) -> None:
-    app_base.on_worker_shutdown(sender, **kwargs)
-
-
-@worker_process_init.connect
-def init_worker(**kwargs: Any) -> None:  # noqa: ARG001
-    SqlEngine.reset_engine()
-
-
-@signals.setup_logging.connect
-def on_setup_logging(
-    loglevel: Any, logfile: Any, format: Any, colorize: Any, **kwargs: Any
-) -> None:
-    app_base.on_setup_logging(loglevel, logfile, format, colorize, **kwargs)
-
-
-base_bootsteps = app_base.get_bootsteps()
-for bootstep in base_bootsteps:
-    celery_app.steps["worker"].add(bootstep)
-
-celery_app.autodiscover_tasks(
-    app_base.filter_task_modules(
-        [
-            # Original background worker tasks
-            "onyx.background.celery.tasks.pruning",
-            "onyx.background.celery.tasks.monitoring",
-            "onyx.background.celery.tasks.user_file_processing",
-            "onyx.background.celery.tasks.llm_model_update",
-            # Light worker tasks
-            "onyx.background.celery.tasks.shared",
-            "onyx.background.celery.tasks.vespa",
-            "onyx.background.celery.tasks.connector_deletion",
-            "onyx.background.celery.tasks.doc_permission_syncing",
-            "onyx.background.celery.tasks.opensearch_migration",
-            # Docprocessing worker tasks
-            "onyx.background.celery.tasks.docprocessing",
-            # Docfetching worker tasks
-            "onyx.background.celery.tasks.docfetching",
-            # Sandbox cleanup tasks (isolated in build feature)
-            "onyx.server.features.build.sandbox.tasks",
-        ]
-    )
-)
diff --git a/backend/onyx/background/celery/configs/background.py b/backend/onyx/background/celery/configs/background.py
deleted file mode 100644
index 64350c8f2b7..00000000000
--- a/backend/onyx/background/celery/configs/background.py
+++ /dev/null
@@ -1,23 +0,0 @@
-import onyx.background.celery.configs.base as shared_config
-from onyx.configs.app_configs import CELERY_WORKER_BACKGROUND_CONCURRENCY
-
-broker_url = shared_config.broker_url
-broker_connection_retry_on_startup = shared_config.broker_connection_retry_on_startup
-broker_pool_limit = shared_config.broker_pool_limit
-broker_transport_options = shared_config.broker_transport_options
-
-redis_socket_keepalive = shared_config.redis_socket_keepalive
-redis_retry_on_timeout = shared_config.redis_retry_on_timeout
-redis_backend_health_check_interval = shared_config.redis_backend_health_check_interval
-
-result_backend = shared_config.result_backend
-result_expires = shared_config.result_expires  # 86400 seconds is the default
-
-task_default_priority = shared_config.task_default_priority
-task_acks_late = shared_config.task_acks_late
-
-worker_concurrency = CELERY_WORKER_BACKGROUND_CONCURRENCY
-worker_pool = "threads"
-# Increased from 1 to 4 to handle fast light worker tasks more efficiently
-# This allows the worker to prefetch multiple tasks per thread
-worker_prefetch_multiplier = 4
diff --git a/backend/onyx/background/celery/versioned_apps/background.py b/backend/onyx/background/celery/versioned_apps/background.py
deleted file mode 100644
index 2d060068958..00000000000
--- a/backend/onyx/background/celery/versioned_apps/background.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from celery import Celery
-
-from onyx.utils.variable_functionality import fetch_versioned_implementation
-from onyx.utils.variable_functionality import set_is_ee_based_on_env_variable
-
-set_is_ee_based_on_env_variable()
-app: Celery = fetch_versioned_implementation(
-    "onyx.background.celery.apps.background",
-    "celery_app",
-)
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 46ef7afdb2b..32f2c77c099 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -495,14 +495,7 @@
     os.environ.get("CELERY_WORKER_PRIMARY_POOL_OVERFLOW") or 4
 )
 
-# Consolidated background worker (light, docprocessing, docfetching, heavy, monitoring, user_file_processing)
-# separate workers' defaults: light=24, docprocessing=6, docfetching=1, heavy=4, kg=2, monitoring=1, user_file=2
-# Total would be 40, but we use a more conservative default of 20 for the consolidated worker
-CELERY_WORKER_BACKGROUND_CONCURRENCY = int(
-    os.environ.get("CELERY_WORKER_BACKGROUND_CONCURRENCY") or 20
-)
-
-# Individual worker concurrency settings (used when USE_LIGHTWEIGHT_BACKGROUND_WORKER is False or on Kuberenetes deployments)
+# Individual worker concurrency settings
 CELERY_WORKER_HEAVY_CONCURRENCY = int(
     os.environ.get("CELERY_WORKER_HEAVY_CONCURRENCY") or 4
 )
diff --git a/backend/onyx/configs/constants.py b/backend/onyx/configs/constants.py
index dd5af81206d..b7c14b82967 100644
--- a/backend/onyx/configs/constants.py
+++ b/backend/onyx/configs/constants.py
@@ -84,7 +84,6 @@
 POSTGRES_CELERY_WORKER_DOCPROCESSING_APP_NAME = "celery_worker_docprocessing"
 POSTGRES_CELERY_WORKER_DOCFETCHING_APP_NAME = "celery_worker_docfetching"
 POSTGRES_CELERY_WORKER_INDEXING_CHILD_APP_NAME = "celery_worker_indexing_child"
-POSTGRES_CELERY_WORKER_BACKGROUND_APP_NAME = "celery_worker_background"
 POSTGRES_CELERY_WORKER_HEAVY_APP_NAME = "celery_worker_heavy"
 POSTGRES_CELERY_WORKER_MONITORING_APP_NAME = "celery_worker_monitoring"
 POSTGRES_CELERY_WORKER_USER_FILE_PROCESSING_APP_NAME = (
diff --git a/backend/scripts/dev_run_background_jobs.py b/backend/scripts/dev_run_background_jobs.py
index 1c26827043f..115391910c5 100644
--- a/backend/scripts/dev_run_background_jobs.py
+++ b/backend/scripts/dev_run_background_jobs.py
@@ -16,10 +16,6 @@ def monitor_process(process_name: str, process: subprocess.Popen) -> None:
 
 
 def run_jobs() -> None:
-    # Check if we should use lightweight mode, defaults to True, change to False to use separate background workers
-    use_lightweight = True
-
-    # command setup
     cmd_worker_primary = [
         "celery",
         "-A",
@@ -74,6 +70,48 @@ def run_jobs() -> None:
         "--queues=connector_doc_fetching",
     ]
 
+    cmd_worker_heavy = [
+        "celery",
+        "-A",
+        "onyx.background.celery.versioned_apps.heavy",
+        "worker",
+        "--pool=threads",
+        "--concurrency=4",
+        "--prefetch-multiplier=1",
+        "--loglevel=INFO",
+        "--hostname=heavy@%n",
+        "-Q",
+        "connector_pruning,connector_doc_permissions_sync,connector_external_group_sync,csv_generation,sandbox",
+    ]
+
+    cmd_worker_monitoring = [
+        "celery",
+        "-A",
+        "onyx.background.celery.versioned_apps.monitoring",
+        "worker",
+        "--pool=threads",
+        "--concurrency=1",
+        "--prefetch-multiplier=1",
+        "--loglevel=INFO",
+        "--hostname=monitoring@%n",
+        "-Q",
+        "monitoring",
+    ]
+
+    cmd_worker_user_file_processing = [
+        "celery",
+        "-A",
+        "onyx.background.celery.versioned_apps.user_file_processing",
+        "worker",
+        "--pool=threads",
+        "--concurrency=2",
+        "--prefetch-multiplier=1",
+        "--loglevel=INFO",
+        "--hostname=user_file_processing@%n",
+        "-Q",
+        "user_file_processing,user_file_project_sync,user_file_delete",
+    ]
+
     cmd_beat = [
         "celery",
         "-A",
@@ -82,144 +120,31 @@ def run_jobs() -> None:
         "--loglevel=INFO",
     ]
 
-    # Prepare background worker commands based on mode
-    if use_lightweight:
-        print("Starting workers in LIGHTWEIGHT mode (single background worker)")
-        cmd_worker_background = [
-            "celery",
-            "-A",
-            "onyx.background.celery.versioned_apps.background",
-            "worker",
-            "--pool=threads",
-            "--concurrency=6",
-            "--prefetch-multiplier=1",
-            "--loglevel=INFO",
-            "--hostname=background@%n",
-            "-Q",
-            "connector_pruning,connector_doc_permissions_sync,connector_external_group_sync,csv_generation,monitoring,user_file_processing,user_file_project_sync,user_file_delete,opensearch_migration",
-        ]
-        background_workers = [("BACKGROUND", cmd_worker_background)]
-    else:
-        print("Starting workers in STANDARD mode (separate background workers)")
-        cmd_worker_heavy = [
-            "celery",
-            "-A",
-            "onyx.background.celery.versioned_apps.heavy",
-            "worker",
-            "--pool=threads",
-            "--concurrency=4",
-            "--prefetch-multiplier=1",
-            "--loglevel=INFO",
-            "--hostname=heavy@%n",
-            "-Q",
-            "connector_pruning,sandbox",
-        ]
-        cmd_worker_monitoring = [
-            "celery",
-            "-A",
-            "onyx.background.celery.versioned_apps.monitoring",
-            "worker",
-            "--pool=threads",
-            "--concurrency=1",
-            "--prefetch-multiplier=1",
-            "--loglevel=INFO",
-            "--hostname=monitoring@%n",
-            "-Q",
-            "monitoring",
-        ]
-        cmd_worker_user_file_processing = [
-            "celery",
-            "-A",
-            "onyx.background.celery.versioned_apps.user_file_processing",
-            "worker",
-            "--pool=threads",
-            "--concurrency=2",
-            "--prefetch-multiplier=1",
-            "--loglevel=INFO",
-            "--hostname=user_file_processing@%n",
-            "-Q",
-            "user_file_processing,user_file_project_sync,connector_doc_permissions_sync,connector_external_group_sync,csv_generation,user_file_delete",
-        ]
-        background_workers = [
-            ("HEAVY", cmd_worker_heavy),
-            ("MONITORING", cmd_worker_monitoring),
-            ("USER_FILE_PROCESSING", cmd_worker_user_file_processing),
-        ]
-
-    # spawn processes
-    worker_primary_process = subprocess.Popen(
-        cmd_worker_primary, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
-    )
-
-    worker_light_process = subprocess.Popen(
-        cmd_worker_light, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
-    )
-
-    worker_docprocessing_process = subprocess.Popen(
-        cmd_worker_docprocessing,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-    )
-
-    worker_docfetching_process = subprocess.Popen(
-        cmd_worker_docfetching,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-    )
-
-    beat_process = subprocess.Popen(
-        cmd_beat, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
-    )
-
-    # Spawn background worker processes based on mode
-    background_processes = []
-    for name, cmd in background_workers:
+    all_workers = [
+        ("PRIMARY", cmd_worker_primary),
+        ("LIGHT", cmd_worker_light),
+        ("DOCPROCESSING", cmd_worker_docprocessing),
+        ("DOCFETCHING", cmd_worker_docfetching),
+        ("HEAVY", cmd_worker_heavy),
+        ("MONITORING", cmd_worker_monitoring),
+        ("USER_FILE_PROCESSING", cmd_worker_user_file_processing),
+        ("BEAT", cmd_beat),
+    ]
+
+    processes = []
+    for name, cmd in all_workers:
         process = subprocess.Popen(
             cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
         )
-        background_processes.append((name, process))
-
-    # monitor threads
-    worker_primary_thread = threading.Thread(
-        target=monitor_process, args=("PRIMARY", worker_primary_process)
-    )
-    worker_light_thread = threading.Thread(
-        target=monitor_process, args=("LIGHT", worker_light_process)
-    )
-    worker_docprocessing_thread = threading.Thread(
-        target=monitor_process, args=("DOCPROCESSING", worker_docprocessing_process)
-    )
-    worker_docfetching_thread = threading.Thread(
-        target=monitor_process, args=("DOCFETCHING", worker_docfetching_process)
-    )
-    beat_thread = threading.Thread(target=monitor_process, args=("BEAT", beat_process))
-
-    # Create monitor threads for background workers
-    background_threads = []
-    for name, process in background_processes:
-        thread = threading.Thread(target=monitor_process, args=(name, process))
-        background_threads.append(thread)
-
-    # Start all threads
-    worker_primary_thread.start()
-    worker_light_thread.start()
-    worker_docprocessing_thread.start()
-    worker_docfetching_thread.start()
-    beat_thread.start()
+        processes.append((name, process))
 
-    for thread in background_threads:
+    threads = []
+    for name, process in processes:
+        thread = threading.Thread(target=monitor_process, args=(name, process))
+        threads.append(thread)
         thread.start()
 
-    # Wait for all threads
-    worker_primary_thread.join()
-    worker_light_thread.join()
-    worker_docprocessing_thread.join()
-    worker_docfetching_thread.join()
-    beat_thread.join()
-
-    for thread in background_threads:
+    for thread in threads:
         thread.join()
 
 
diff --git a/backend/scripts/supervisord_entrypoint.sh b/backend/scripts/supervisord_entrypoint.sh
index 463b6dae2b2..21cdf5bc81d 100755
--- a/backend/scripts/supervisord_entrypoint.sh
+++ b/backend/scripts/supervisord_entrypoint.sh
@@ -1,23 +1,5 @@
 #!/bin/sh
-# Entrypoint script for supervisord that sets environment variables
-# for controlling which celery workers to start
-
-# Default to lightweight mode if not set
-if [ -z "$USE_LIGHTWEIGHT_BACKGROUND_WORKER" ]; then
-    export USE_LIGHTWEIGHT_BACKGROUND_WORKER="true"
-fi
-
-# Set the complementary variable for supervisord
-# because it doesn't support %(not ENV_USE_LIGHTWEIGHT_BACKGROUND_WORKER) syntax
-if [ "$USE_LIGHTWEIGHT_BACKGROUND_WORKER" = "true" ]; then
-    export USE_SEPARATE_BACKGROUND_WORKERS="false"
-else
-    export USE_SEPARATE_BACKGROUND_WORKERS="true"
-fi
-
-echo "Worker mode configuration:"
-echo "  USE_LIGHTWEIGHT_BACKGROUND_WORKER=$USE_LIGHTWEIGHT_BACKGROUND_WORKER"
-echo "  USE_SEPARATE_BACKGROUND_WORKERS=$USE_SEPARATE_BACKGROUND_WORKERS"
+# Entrypoint script for supervisord
 
 # Launch supervisord with environment variables available
 exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf
diff --git a/backend/supervisord.conf b/backend/supervisord.conf
index 446dfddd946..4847689dc57 100644
--- a/backend/supervisord.conf
+++ b/backend/supervisord.conf
@@ -39,7 +39,6 @@ autorestart=true
 startsecs=10
 stopasgroup=true
 
-# Standard mode: Light worker for fast operations
 # NOTE: only allowing configuration here and not in the other celery workers,
 # since this is often the bottleneck for "sync" jobs (e.g. document set syncing,
 # user group syncing, deletion, etc.)
@@ -54,26 +53,7 @@ redirect_stderr=true
 autorestart=true
 startsecs=10
 stopasgroup=true
-autostart=%(ENV_USE_SEPARATE_BACKGROUND_WORKERS)s
 
-# Lightweight mode: single consolidated background worker
-# Used when USE_LIGHTWEIGHT_BACKGROUND_WORKER=true (default)
-# Consolidates: light, docprocessing, docfetching, heavy, monitoring, user_file_processing
-[program:celery_worker_background]
-command=celery -A onyx.background.celery.versioned_apps.background worker
-    --loglevel=INFO
-    --hostname=background@%%n
-    -Q vespa_metadata_sync,connector_deletion,doc_permissions_upsert,checkpoint_cleanup,index_attempt_cleanup,sandbox,docprocessing,connector_doc_fetching,connector_pruning,connector_doc_permissions_sync,connector_external_group_sync,csv_generation,monitoring,user_file_processing,user_file_project_sync,opensearch_migration
-stdout_logfile=/var/log/celery_worker_background.log
-stdout_logfile_maxbytes=16MB
-redirect_stderr=true
-autorestart=true
-startsecs=10
-stopasgroup=true
-autostart=%(ENV_USE_LIGHTWEIGHT_BACKGROUND_WORKER)s
-
-# Standard mode: separate workers for different background tasks
-# Used when USE_LIGHTWEIGHT_BACKGROUND_WORKER=false
 [program:celery_worker_heavy]
 command=celery -A onyx.background.celery.versioned_apps.heavy worker
     --loglevel=INFO
@@ -85,9 +65,7 @@ redirect_stderr=true
 autorestart=true
 startsecs=10
 stopasgroup=true
-autostart=%(ENV_USE_SEPARATE_BACKGROUND_WORKERS)s
 
-# Standard mode: Document processing worker
 [program:celery_worker_docprocessing]
 command=celery -A onyx.background.celery.versioned_apps.docprocessing worker
     --loglevel=INFO
@@ -99,7 +77,6 @@ redirect_stderr=true
 autorestart=true
 startsecs=10
 stopasgroup=true
-autostart=%(ENV_USE_SEPARATE_BACKGROUND_WORKERS)s
 
 [program:celery_worker_user_file_processing]
 command=celery -A onyx.background.celery.versioned_apps.user_file_processing worker
@@ -112,9 +89,7 @@ redirect_stderr=true
 autorestart=true
 startsecs=10
 stopasgroup=true
-autostart=%(ENV_USE_SEPARATE_BACKGROUND_WORKERS)s
 
-# Standard mode: Document fetching worker
 [program:celery_worker_docfetching]
 command=celery -A onyx.background.celery.versioned_apps.docfetching worker
     --loglevel=INFO
@@ -126,7 +101,6 @@ redirect_stderr=true
 autorestart=true
 startsecs=10
 stopasgroup=true
-autostart=%(ENV_USE_SEPARATE_BACKGROUND_WORKERS)s
 
 [program:celery_worker_monitoring]
 command=celery -A onyx.background.celery.versioned_apps.monitoring worker
@@ -139,7 +113,6 @@ redirect_stderr=true
 autorestart=true
 startsecs=10
 stopasgroup=true
-autostart=%(ENV_USE_SEPARATE_BACKGROUND_WORKERS)s
 
 
 # Job scheduler for periodic tasks
@@ -197,7 +170,6 @@ command=tail -qF
     /var/log/celery_beat.log
     /var/log/celery_worker_primary.log
     /var/log/celery_worker_light.log
-    /var/log/celery_worker_background.log
     /var/log/celery_worker_heavy.log
     /var/log/celery_worker_docprocessing.log
     /var/log/celery_worker_monitoring.log
diff --git a/deployment/docker_compose/docker-compose.multitenant-dev.yml b/deployment/docker_compose/docker-compose.multitenant-dev.yml
index 1656d40c6e4..c1366bc7e91 100644
--- a/deployment/docker_compose/docker-compose.multitenant-dev.yml
+++ b/deployment/docker_compose/docker-compose.multitenant-dev.yml
@@ -138,7 +138,6 @@ services:
       - indexing_model_server
     restart: unless-stopped
     environment:
-      - USE_LIGHTWEIGHT_BACKGROUND_WORKER=${USE_LIGHTWEIGHT_BACKGROUND_WORKER:-true}
       - ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=true
       - MULTI_TENANT=true
       - LOG_LEVEL=DEBUG
diff --git a/deployment/docker_compose/docker-compose.prod-cloud.yml b/deployment/docker_compose/docker-compose.prod-cloud.yml
index aba7b1c516e..3153440fcf3 100644
--- a/deployment/docker_compose/docker-compose.prod-cloud.yml
+++ b/deployment/docker_compose/docker-compose.prod-cloud.yml
@@ -52,7 +52,6 @@ services:
       - indexing_model_server
     restart: unless-stopped
     environment:
-      - USE_LIGHTWEIGHT_BACKGROUND_WORKER=${USE_LIGHTWEIGHT_BACKGROUND_WORKER:-true}
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
diff --git a/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml b/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
index 626cc730fa2..e1a2cfa4ef5 100644
--- a/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
+++ b/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
@@ -65,7 +65,6 @@ services:
       - indexing_model_server
     restart: unless-stopped
     environment:
-      - USE_LIGHTWEIGHT_BACKGROUND_WORKER=${USE_LIGHTWEIGHT_BACKGROUND_WORKER:-true}
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
diff --git a/deployment/docker_compose/docker-compose.prod.yml b/deployment/docker_compose/docker-compose.prod.yml
index b77b38db3bd..fbb4bcc5c43 100644
--- a/deployment/docker_compose/docker-compose.prod.yml
+++ b/deployment/docker_compose/docker-compose.prod.yml
@@ -70,7 +70,6 @@ services:
       - indexing_model_server
     restart: unless-stopped
     environment:
-      - USE_LIGHTWEIGHT_BACKGROUND_WORKER=${USE_LIGHTWEIGHT_BACKGROUND_WORKER:-true}
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
diff --git a/deployment/docker_compose/docker-compose.search-testing.yml b/deployment/docker_compose/docker-compose.search-testing.yml
index a7d9389920d..5bb6f90d805 100644
--- a/deployment/docker_compose/docker-compose.search-testing.yml
+++ b/deployment/docker_compose/docker-compose.search-testing.yml
@@ -58,7 +58,6 @@ services:
     env_file:
       - .env_eval
     environment:
-      - USE_LIGHTWEIGHT_BACKGROUND_WORKER=${USE_LIGHTWEIGHT_BACKGROUND_WORKER:-true}
       - AUTH_TYPE=disabled
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
diff --git a/deployment/docker_compose/docker-compose.yml b/deployment/docker_compose/docker-compose.yml
index e9d9800a001..d82cd1cb3cd 100644
--- a/deployment/docker_compose/docker-compose.yml
+++ b/deployment/docker_compose/docker-compose.yml
@@ -146,7 +146,6 @@ services:
       - indexing_model_server
     restart: unless-stopped
     environment:
-      - USE_LIGHTWEIGHT_BACKGROUND_WORKER=${USE_LIGHTWEIGHT_BACKGROUND_WORKER:-true}
       - FILE_STORE_BACKEND=${FILE_STORE_BACKEND:-s3}
       - POSTGRES_HOST=${POSTGRES_HOST:-relational_db}
       - VESPA_HOST=${VESPA_HOST:-index}

From b148065e1d4c94a897e143660db055e6c233217d Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 4 Mar 2026 11:07:52 -0800
Subject: [PATCH 078/267] chore(devtools): `--debug` mode for desktop (#9027)

---
 desktop/README.md             |  38 ++++--
 desktop/package.json          |   1 +
 desktop/src-tauri/Cargo.toml  |   1 +
 desktop/src-tauri/src/main.rs | 247 +++++++++++++++++++++++++++++++++-
 4 files changed, 273 insertions(+), 14 deletions(-)

diff --git a/desktop/README.md b/desktop/README.md
index bededcb8779..17fec4efaea 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -14,30 +14,32 @@ Built with [Tauri](https://tauri.app) for minimal bundle size (~10MB vs Electron
 
 ## Keyboard Shortcuts
 
-| Shortcut | Action |
-|----------|--------|
-| `⌘ N` | New Chat |
-| `⌘ ⇧ N` | New Window |
-| `⌘ R` | Reload |
-| `⌘ [` | Go Back |
-| `⌘ ]` | Go Forward |
-| `⌘ ,` | Open Config File |
-| `⌘ W` | Close Window |
-| `⌘ Q` | Quit |
+| Shortcut | Action           |
+| -------- | ---------------- |
+| `⌘ N`    | New Chat         |
+| `⌘ ⇧ N`  | New Window       |
+| `⌘ R`    | Reload           |
+| `⌘ [`    | Go Back          |
+| `⌘ ]`    | Go Forward       |
+| `⌘ ,`    | Open Config File |
+| `⌘ W`    | Close Window     |
+| `⌘ Q`    | Quit             |
 
 ## Prerequisites
 
 1. **Rust** (latest stable)
+
    ```bash
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    source $HOME/.cargo/env
    ```
 
 2. **Node.js** (18+)
+
    ```bash
    # Using homebrew
    brew install node
-   
+
    # Or using nvm
    nvm install 18
    ```
@@ -55,16 +57,21 @@ npm install
 
 # Run in development mode
 npm run dev
+
+# Run in debug mode
+npm run debug
 ```
 
 ## Building
 
 ### Build for current architecture
+
 ```bash
 npm run build
 ```
 
 ### Build Universal Binary (Intel + Apple Silicon)
+
 ```bash
 # First, add the targets
 rustup target add x86_64-apple-darwin
@@ -103,6 +110,7 @@ Before building, add your app icons to `src-tauri/icons/`:
 - `icon.ico` (Windows, optional)
 
 You can generate these from a 1024x1024 source image using:
+
 ```bash
 # Using tauri's icon generator
 npm run tauri icon path/to/your-icon.png
@@ -115,6 +123,7 @@ npm run tauri icon path/to/your-icon.png
 The app defaults to `https://cloud.onyx.app` but supports any Onyx instance.
 
 **Config file location:**
+
 - macOS: `~/Library/Application Support/app.onyx.desktop/config.json`
 - Linux: `~/.config/app.onyx.desktop/config.json`
 - Windows: `%APPDATA%/app.onyx.desktop/config.json`
@@ -135,6 +144,7 @@ The app defaults to `https://cloud.onyx.app` but supports any Onyx instance.
 4. Restart the app
 
 **Quick edit via terminal:**
+
 ```bash
 # macOS
 open -t ~/Library/Application\ Support/app.onyx.desktop/config.json
@@ -146,6 +156,7 @@ code ~/Library/Application\ Support/app.onyx.desktop/config.json
 ### Change the default URL in build
 
 Edit `src-tauri/tauri.conf.json`:
+
 ```json
 {
   "app": {
@@ -165,6 +176,7 @@ Edit `src-tauri/src/main.rs` in the `setup_shortcuts` function.
 ### Window appearance
 
 Modify the window configuration in `src-tauri/tauri.conf.json`:
+
 - `titleBarStyle`: `"Overlay"` (macOS native) or `"Visible"`
 - `decorations`: Window chrome
 - `transparent`: For custom backgrounds
@@ -172,16 +184,20 @@ Modify the window configuration in `src-tauri/tauri.conf.json`:
 ## Troubleshooting
 
 ### "Unable to resolve host"
+
 Make sure you have an internet connection. The app loads content from `cloud.onyx.app`.
 
 ### Build fails on M1/M2 Mac
+
 ```bash
 # Ensure you have the right target
 rustup target add aarch64-apple-darwin
 ```
 
 ### Code signing for distribution
+
 For distributing outside the App Store, you'll need to:
+
 1. Get an Apple Developer certificate
 2. Sign the app: `codesign --deep --force --sign "Developer ID" target/release/bundle/macos/Onyx.app`
 3. Notarize with Apple
diff --git a/desktop/package.json b/desktop/package.json
index 2d940d61e78..2b8b6056340 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -4,6 +4,7 @@
   "description": "Lightweight desktop app for Onyx Cloud",
   "scripts": {
     "dev": "tauri dev",
+    "debug": "tauri dev -- -- --debug",
     "build": "tauri build",
     "build:dmg": "tauri build --target universal-apple-darwin",
     "build:linux": "tauri build --bundles deb,rpm"
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index cfb299a9238..fe84604ca33 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -23,3 +23,4 @@ url = "2.5"
 [features]
 default = ["custom-protocol"]
 custom-protocol = ["tauri/custom-protocol"]
+devtools = ["tauri/devtools"]
diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
index 392d36bb7dd..b3a32bb9b74 100644
--- a/desktop/src-tauri/src/main.rs
+++ b/desktop/src-tauri/src/main.rs
@@ -6,7 +6,9 @@ use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::PathBuf;
 use std::process::Command;
-use std::sync::RwLock;
+use std::sync::{Mutex, RwLock};
+use std::io::Write as IoWrite;
+use std::time::SystemTime;
 #[cfg(target_os = "macos")]
 use std::time::Duration;
 use tauri::image::Image;
@@ -230,6 +232,63 @@ const MENU_KEY_HANDLER_SCRIPT: &str = r#"
 })();
 "#;
 
+const CONSOLE_CAPTURE_SCRIPT: &str = r#"
+(() => {
+  if (window.__ONYX_CONSOLE_CAPTURE__) return;
+  window.__ONYX_CONSOLE_CAPTURE__ = true;
+
+  const levels = ['log', 'warn', 'error', 'info', 'debug'];
+  const originals = {};
+
+  levels.forEach(level => {
+    originals[level] = console[level];
+    console[level] = function(...args) {
+      originals[level].apply(console, args);
+      try {
+        const invoke =
+          window.__TAURI__?.core?.invoke || window.__TAURI_INTERNALS__?.invoke;
+        if (typeof invoke === 'function') {
+          const message = args.map(a => {
+            try { return typeof a === 'string' ? a : JSON.stringify(a); }
+            catch { return String(a); }
+          }).join(' ');
+          invoke('log_from_frontend', { level, message });
+        }
+      } catch {}
+    };
+  });
+
+  window.addEventListener('error', (event) => {
+    try {
+      const invoke =
+        window.__TAURI__?.core?.invoke || window.__TAURI_INTERNALS__?.invoke;
+      if (typeof invoke === 'function') {
+        invoke('log_from_frontend', {
+          level: 'error',
+          message: `[uncaught] ${event.message} at ${event.filename}:${event.lineno}:${event.colno}`
+        });
+      }
+    } catch {}
+  });
+
+  window.addEventListener('unhandledrejection', (event) => {
+    try {
+      const invoke =
+        window.__TAURI__?.core?.invoke || window.__TAURI_INTERNALS__?.invoke;
+      if (typeof invoke === 'function') {
+        invoke('log_from_frontend', {
+          level: 'error',
+          message: `[unhandled rejection] ${event.reason}`
+        });
+      }
+    } catch {}
+  });
+})();
+"#;
+
+const MENU_TOGGLE_DEVTOOLS_ID: &str = "toggle_devtools";
+const MENU_OPEN_DEBUG_LOG_ID: &str = "open_debug_log";
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AppConfig {
     pub server_url: String,
@@ -311,12 +370,87 @@ fn save_config(config: &AppConfig) -> Result<(), String> {
     Ok(())
 }
 
+// ============================================================================
+// Debug Mode
+// ============================================================================
+
+fn is_debug_mode() -> bool {
+    std::env::args().any(|arg| arg == "--debug") || std::env::var("ONYX_DEBUG").is_ok()
+}
+
+fn get_debug_log_path() -> Option<PathBuf> {
+    get_config_dir().map(|dir| dir.join("frontend_debug.log"))
+}
+
+fn init_debug_log_file() -> Option<fs::File> {
+    let log_path = get_debug_log_path()?;
+    if let Some(parent) = log_path.parent() {
+        let _ = fs::create_dir_all(parent);
+    }
+    fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&log_path)
+        .ok()
+}
+
+fn format_utc_timestamp() -> String {
+    let now = SystemTime::now()
+        .duration_since(SystemTime::UNIX_EPOCH)
+        .unwrap_or_default();
+    let total_secs = now.as_secs();
+    let millis = now.subsec_millis();
+
+    let days = total_secs / 86400;
+    let secs_of_day = total_secs % 86400;
+    let hours = secs_of_day / 3600;
+    let mins = (secs_of_day % 3600) / 60;
+    let secs = secs_of_day % 60;
+
+    // Days since Unix epoch -> Y/M/D via civil calendar arithmetic
+    let z = days as i64 + 719468;
+    let era = z / 146097;
+    let doe = z - era * 146097;
+    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
+    let y = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = doy - (153 * mp + 2) / 5 + 1;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 };
+    let y = if m <= 2 { y + 1 } else { y };
+
+    format!(
+        "{:04}-{:02}-{:02}T{:02}:{:02}:{:02}.{:03}Z",
+        y, m, d, hours, mins, secs, millis
+    )
+}
+
+fn inject_console_capture(webview: &Webview) {
+    let _ = webview.eval(CONSOLE_CAPTURE_SCRIPT);
+}
+
+fn maybe_open_devtools(app: &AppHandle, window: &tauri::WebviewWindow) {
+    #[cfg(any(debug_assertions, feature = "devtools"))]
+    {
+        let state = app.state::<ConfigState>();
+        if state.debug_mode {
+            window.open_devtools();
+        }
+    }
+    #[cfg(not(any(debug_assertions, feature = "devtools")))]
+    {
+        let _ = (app, window);
+    }
+}
+
 // Global config state
 struct ConfigState {
     config: RwLock<AppConfig>,
     config_initialized: RwLock<bool>,
     app_base_url: RwLock<Option<Url>>,
     menu_temporarily_visible: RwLock<bool>,
+    debug_mode: bool,
+    debug_log_file: Mutex<Option<fs::File>>,
 }
 
 fn focus_main_window(app: &AppHandle) {
@@ -372,6 +506,7 @@ fn trigger_new_window(app: &AppHandle) {
             }
 
             apply_settings_to_window(&handle, &window);
+            maybe_open_devtools(&handle, &window);
             let _ = window.set_focus();
         }
     });
@@ -467,10 +602,65 @@ fn inject_chat_link_intercept(webview: &Webview) {
     let _ = webview.eval(CHAT_LINK_INTERCEPT_SCRIPT);
 }
 
+fn handle_toggle_devtools(app: &AppHandle) {
+    #[cfg(any(debug_assertions, feature = "devtools"))]
+    {
+        let windows: Vec<_> = app.webview_windows().into_values().collect();
+        let any_open = windows.iter().any(|w| w.is_devtools_open());
+        for window in &windows {
+            if any_open {
+                window.close_devtools();
+            } else {
+                window.open_devtools();
+            }
+        }
+    }
+    #[cfg(not(any(debug_assertions, feature = "devtools")))]
+    {
+        let _ = app;
+    }
+}
+
+fn handle_open_debug_log() {
+    let log_path = match get_debug_log_path() {
+        Some(p) => p,
+        None => return,
+    };
+
+    if !log_path.exists() {
+        eprintln!("[ONYX DEBUG] Log file does not exist yet: {:?}", log_path);
+        return;
+    }
+
+    let url_path = log_path.to_string_lossy().replace('\\', "/");
+    let _ = open_in_default_browser(&format!(
+        "file:///{}",
+        url_path.trim_start_matches('/')
+    ));
+}
+
 // ============================================================================
 // Tauri Commands
 // ============================================================================
 
+#[tauri::command]
+fn log_from_frontend(level: String, message: String, state: tauri::State<ConfigState>) {
+    if !state.debug_mode {
+        return;
+    }
+    let timestamp = format_utc_timestamp();
+    let log_line = format!("[{}] [{}] {}", timestamp, level.to_uppercase(), message);
+
+    eprintln!("{}", log_line);
+
+    if let Ok(mut guard) = state.debug_log_file.lock() {
+        if let Some(ref mut file) = *guard {
+            let _ = writeln!(file, "{}", log_line);
+            let _ = file.flush();
+        }
+    }
+}
+
 /// Get the current server URL
 #[tauri::command]
 fn get_server_url(state: tauri::State<ConfigState>) -> String {
@@ -657,6 +847,7 @@ async fn new_window(app: AppHandle, state: tauri::State<'_, ConfigState>) -> Res
     }
 
     apply_settings_to_window(&app, &window);
+    maybe_open_devtools(&app, &window);
 
     Ok(())
 }
@@ -936,6 +1127,30 @@ fn setup_app_menu(app: &AppHandle) -> tauri::Result<()> {
         menu.append(&help_menu)?;
     }
 
+    let state = app.state::<ConfigState>();
+    if state.debug_mode {
+        let toggle_devtools_item = MenuItem::with_id(
+            app,
+            MENU_TOGGLE_DEVTOOLS_ID,
+            "Toggle DevTools",
+            true,
+            Some("F12"),
+        )?;
+        let open_log_item = MenuItem::with_id(
+            app,
+            MENU_OPEN_DEBUG_LOG_ID,
+            "Open Debug Log",
+            true,
+            None::<&str>,
+        )?;
+
+        let debug_menu = SubmenuBuilder::new(app, "Debug")
+            .item(&toggle_devtools_item)
+            .item(&open_log_item)
+            .build()?;
+        menu.append(&debug_menu)?;
+    }
+
     app.set_menu(menu)?;
     Ok(())
 }
@@ -1027,8 +1242,20 @@ fn setup_tray_icon(app: &AppHandle) -> tauri::Result<()> {
 // ============================================================================
 
 fn main() {
-    // Load config at startup
     let (config, config_initialized) = load_config();
+    let debug_mode = is_debug_mode();
+
+    let debug_log_file = if debug_mode {
+        eprintln!("[ONYX DEBUG] Debug mode enabled");
+        if let Some(path) = get_debug_log_path() {
+            eprintln!("[ONYX DEBUG] Frontend logs: {}", path.display());
+        }
+        eprintln!("[ONYX DEBUG] DevTools will open automatically");
+        eprintln!("[ONYX DEBUG] Capturing console.log/warn/error/info/debug from webview");
+        init_debug_log_file()
+    } else {
+        None
+    };
 
     tauri::Builder::default()
         .plugin(tauri_plugin_shell::init())
@@ -1059,6 +1286,8 @@ fn main() {
             config_initialized: RwLock::new(config_initialized),
             app_base_url: RwLock::new(None),
             menu_temporarily_visible: RwLock::new(false),
+            debug_mode,
+            debug_log_file: Mutex::new(debug_log_file),
         })
         .invoke_handler(tauri::generate_handler![
             get_server_url,
@@ -1077,7 +1306,8 @@ fn main() {
             start_drag_window,
             toggle_menu_bar,
             show_menu_bar_temporarily,
-            hide_menu_bar_temporary
+            hide_menu_bar_temporary,
+            log_from_frontend
         ])
         .on_menu_event(|app, event| match event.id().as_ref() {
             "open_docs" => open_docs(),
@@ -1086,6 +1316,8 @@ fn main() {
             "open_settings" => open_settings(app),
             "show_menu_bar" => handle_menu_bar_toggle(app),
             "hide_window_decorations" => handle_decorations_toggle(app),
+            MENU_TOGGLE_DEVTOOLS_ID => handle_toggle_devtools(app),
+            MENU_OPEN_DEBUG_LOG_ID => handle_open_debug_log(),
             _ => {}
         })
         .setup(move |app| {
@@ -1119,6 +1351,7 @@ fn main() {
                 inject_titlebar(window.clone());
 
                 apply_settings_to_window(&app_handle, &window);
+                maybe_open_devtools(&app_handle, &window);
 
                 let _ = window.set_focus();
             }
@@ -1128,6 +1361,14 @@ fn main() {
         .on_page_load(|webview: &Webview, _payload: &PageLoadPayload| {
             inject_chat_link_intercept(webview);
 
+            {
+                let app = webview.app_handle();
+                let state = app.state::<ConfigState>();
+                if state.debug_mode {
+                    inject_console_capture(webview);
+                }
+            }
+
             #[cfg(not(target_os = "macos"))]
             {
                 let _ = webview.eval(MENU_KEY_HANDLER_SCRIPT);

From e5e2bc614935c396f64b282d08c61b51a114393d Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 4 Mar 2026 11:08:14 -0800
Subject: [PATCH 079/267] chore(fe): "Share Chat"->"Share" (#9022)

---
 web/src/layouts/app-layouts.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index 61264e34a5c..18ec196064b 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -399,7 +399,7 @@ function Header() {
                 onClick={() => setShowShareModal(true)}
                 aria-label="share-chat-button"
               >
-                Share Chat
+                Share
               </Button>
               <SimplePopover
                 trigger={

From 649c7fe8b9aedde813d0041358d4be9954213bbe Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 4 Mar 2026 11:16:50 -0800
Subject: [PATCH 080/267] feat(slack): convert markdown tables to
 Slack-friendly format (#8999)

---
 backend/onyx/onyxbot/slack/formatting.py      | 50 +++++++++-
 .../onyx/onyxbot/test_slack_formatting.py     | 99 +++++++++++++++++++
 2 files changed, 148 insertions(+), 1 deletion(-)

diff --git a/backend/onyx/onyxbot/slack/formatting.py b/backend/onyx/onyxbot/slack/formatting.py
index 78a7ad40184..33551b4c155 100644
--- a/backend/onyx/onyxbot/slack/formatting.py
+++ b/backend/onyx/onyxbot/slack/formatting.py
@@ -130,7 +130,7 @@ def format_slack_message(message: str | None) -> str:
     message = _transform_outside_code_blocks(message, _sanitize_html)
     message = _convert_slack_links_to_markdown(message)
     normalized_message = _normalize_link_destinations(message)
-    md = create_markdown(renderer=SlackRenderer(), plugins=["strikethrough"])
+    md = create_markdown(renderer=SlackRenderer(), plugins=["strikethrough", "table"])
     result = md(normalized_message)
     # With HTMLRenderer, result is always str (not AST list)
     assert isinstance(result, str)
@@ -146,6 +146,11 @@ class SlackRenderer(HTMLRenderer):
 
     SPECIALS: dict[str, str] = {"&": "&amp;", "<": "&lt;", ">": "&gt;"}
 
+    def __init__(self) -> None:
+        super().__init__()
+        self._table_headers: list[str] = []
+        self._current_row_cells: list[str] = []
+
     def escape_special(self, text: str) -> str:
         for special, replacement in self.SPECIALS.items():
             text = text.replace(special, replacement)
@@ -218,5 +223,48 @@ def text(self, text: str) -> str:
         # as literal &quot; text since Slack doesn't recognize that entity.
         return self.escape_special(text)
 
+    # -- Table rendering (converts markdown tables to vertical cards) --
+
+    def table_cell(
+        self, text: str, align: str | None = None, head: bool = False  # noqa: ARG002
+    ) -> str:
+        if head:
+            self._table_headers.append(text.strip())
+        else:
+            self._current_row_cells.append(text.strip())
+        return ""
+
+    def table_head(self, text: str) -> str:  # noqa: ARG002
+        self._current_row_cells = []
+        return ""
+
+    def table_row(self, text: str) -> str:  # noqa: ARG002
+        cells = self._current_row_cells
+        self._current_row_cells = []
+        # First column becomes the bold title, remaining columns are bulleted fields
+        lines: list[str] = []
+        if cells:
+            title = cells[0]
+            if title:
+                # Avoid double-wrapping if cell already contains bold markup
+                if title.startswith("*") and title.endswith("*") and len(title) > 1:
+                    lines.append(title)
+                else:
+                    lines.append(f"*{title}*")
+            for i, cell in enumerate(cells[1:], start=1):
+                if i < len(self._table_headers):
+                    lines.append(f"  • {self._table_headers[i]}: {cell}")
+                else:
+                    lines.append(f"  • {cell}")
+        return "\n".join(lines) + "\n\n"
+
+    def table_body(self, text: str) -> str:
+        return text
+
+    def table(self, text: str) -> str:
+        self._table_headers = []
+        self._current_row_cells = []
+        return text + "\n"
+
     def paragraph(self, text: str) -> str:
         return f"{text}\n\n"
diff --git a/backend/tests/unit/onyx/onyxbot/test_slack_formatting.py b/backend/tests/unit/onyx/onyxbot/test_slack_formatting.py
index 25afe07753d..6aedb8324f5 100644
--- a/backend/tests/unit/onyx/onyxbot/test_slack_formatting.py
+++ b/backend/tests/unit/onyx/onyxbot/test_slack_formatting.py
@@ -104,3 +104,102 @@ def test_format_slack_message_ampersand_not_double_escaped() -> None:
 
     assert "&amp;" in formatted
     assert "&quot;" not in formatted
+
+
+# -- Table rendering tests --
+
+
+def test_table_renders_as_vertical_cards() -> None:
+    message = (
+        "| Feature | Status | Owner |\n"
+        "|---------|--------|-------|\n"
+        "| Auth | Done | Alice |\n"
+        "| Search | In Progress | Bob |\n"
+    )
+
+    formatted = format_slack_message(message)
+
+    assert "*Auth*\n  • Status: Done\n  • Owner: Alice" in formatted
+    assert "*Search*\n  • Status: In Progress\n  • Owner: Bob" in formatted
+    # Cards separated by blank line
+    assert "Owner: Alice\n\n*Search*" in formatted
+    # No raw pipe-and-dash table syntax
+    assert "---|" not in formatted
+
+
+def test_table_single_column() -> None:
+    message = "| Name |\n|------|\n| Alice |\n| Bob |\n"
+
+    formatted = format_slack_message(message)
+
+    assert "*Alice*" in formatted
+    assert "*Bob*" in formatted
+
+
+def test_table_embedded_in_text() -> None:
+    message = (
+        "Here are the results:\n\n"
+        "| Item | Count |\n"
+        "|------|-------|\n"
+        "| Apples | 5 |\n"
+        "\n"
+        "That's all."
+    )
+
+    formatted = format_slack_message(message)
+
+    assert "Here are the results:" in formatted
+    assert "*Apples*\n  • Count: 5" in formatted
+    assert "That's all." in formatted
+
+
+def test_table_with_formatted_cells() -> None:
+    message = (
+        "| Name | Link |\n"
+        "|------|------|\n"
+        "| **Alice** | [profile](https://example.com) |\n"
+    )
+
+    formatted = format_slack_message(message)
+
+    # Bold cell should not double-wrap: *Alice* not **Alice**
+    assert "*Alice*" in formatted
+    assert "**Alice**" not in formatted
+    assert "<https://example.com|profile>" in formatted
+
+
+def test_table_with_alignment_specifiers() -> None:
+    message = (
+        "| Left | Center | Right |\n" "|:-----|:------:|------:|\n" "| a | b | c |\n"
+    )
+
+    formatted = format_slack_message(message)
+
+    assert "*a*\n  • Center: b\n  • Right: c" in formatted
+
+
+def test_two_tables_in_same_message_use_independent_headers() -> None:
+    message = (
+        "| A | B |\n"
+        "|---|---|\n"
+        "| 1 | 2 |\n"
+        "\n"
+        "| X | Y | Z |\n"
+        "|---|---|---|\n"
+        "| p | q | r |\n"
+    )
+
+    formatted = format_slack_message(message)
+
+    assert "*1*\n  • B: 2" in formatted
+    assert "*p*\n  • Y: q\n  • Z: r" in formatted
+
+
+def test_table_empty_first_column_no_bare_asterisks() -> None:
+    message = "| Name | Status |\n" "|------|--------|\n" "| | Done |\n"
+
+    formatted = format_slack_message(message)
+
+    # Empty title should not produce "**" (bare asterisks)
+    assert "**" not in formatted
+    assert "  • Status: Done" in formatted

From 57d3ab3b4026b3e6b1d04db4b7b0036204539ef4 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 4 Mar 2026 11:48:37 -0800
Subject: [PATCH 081/267] feat: add SCIM token management page  (#9001)

---
 .../ee/onyx/server/enterprise_settings/api.py |  10 ++
 backend/ee/onyx/server/scim/models.py         |   1 +
 web/lib/opal/src/icons/index.ts               |   1 +
 web/lib/opal/src/icons/user-sync.tsx          |  22 +++
 web/src/app/admin/scim/ScimModal.tsx          | 138 +++++++++++++++++
 web/src/app/admin/scim/ScimSyncCard.tsx       | 117 +++++++++++++++
 web/src/app/admin/scim/interfaces.ts          |  17 +++
 web/src/app/admin/scim/page.tsx               | 140 ++++++++++++++++++
 web/src/app/admin/scim/svc.ts                 |   7 +
 web/src/components/admin/ClientLayout.tsx     |   1 +
 web/src/hooks/useScimToken.ts                 |  16 ++
 web/src/lib/admin-routes.ts                   |   7 +
 web/src/lib/download.ts                       |  34 +++++
 .../inputs/InputTextArea.tsx                  |   9 +-
 web/src/sections/sidebar/AdminSidebar.tsx     |   8 +
 web/tests/e2e/admin/scim/fixtures.ts          | 114 ++++++++++++++
 web/tests/e2e/admin/scim/scim.spec.ts         |  81 ++++++++++
 17 files changed, 722 insertions(+), 1 deletion(-)
 create mode 100644 web/lib/opal/src/icons/user-sync.tsx
 create mode 100644 web/src/app/admin/scim/ScimModal.tsx
 create mode 100644 web/src/app/admin/scim/ScimSyncCard.tsx
 create mode 100644 web/src/app/admin/scim/interfaces.ts
 create mode 100644 web/src/app/admin/scim/page.tsx
 create mode 100644 web/src/app/admin/scim/svc.ts
 create mode 100644 web/src/hooks/useScimToken.ts
 create mode 100644 web/src/lib/download.ts
 create mode 100644 web/tests/e2e/admin/scim/fixtures.ts
 create mode 100644 web/tests/e2e/admin/scim/scim.spec.ts

diff --git a/backend/ee/onyx/server/enterprise_settings/api.py b/backend/ee/onyx/server/enterprise_settings/api.py
index b938e07bd85..73b367bea71 100644
--- a/backend/ee/onyx/server/enterprise_settings/api.py
+++ b/backend/ee/onyx/server/enterprise_settings/api.py
@@ -223,6 +223,15 @@ def get_active_scim_token(
     token = dal.get_active_token()
     if not token:
         raise HTTPException(status_code=404, detail="No active SCIM token")
+
+    # Derive the IdP domain from the first synced user as a heuristic.
+    idp_domain: str | None = None
+    mappings, _total = dal.list_user_mappings(start_index=1, count=1)
+    if mappings:
+        user = dal.get_user(mappings[0].user_id)
+        if user and "@" in user.email:
+            idp_domain = user.email.rsplit("@", 1)[1]
+
     return ScimTokenResponse(
         id=token.id,
         name=token.name,
@@ -230,6 +239,7 @@ def get_active_scim_token(
         is_active=token.is_active,
         created_at=token.created_at,
         last_used_at=token.last_used_at,
+        idp_domain=idp_domain,
     )
 
 
diff --git a/backend/ee/onyx/server/scim/models.py b/backend/ee/onyx/server/scim/models.py
index 64221e417f0..441d60fbe05 100644
--- a/backend/ee/onyx/server/scim/models.py
+++ b/backend/ee/onyx/server/scim/models.py
@@ -365,6 +365,7 @@ class ScimTokenResponse(BaseModel):
     is_active: bool
     created_at: datetime
     last_used_at: datetime | None = None
+    idp_domain: str | None = None
 
 
 class ScimTokenCreatedResponse(ScimTokenResponse):
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index 22509667b8a..9ed6903bf6c 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -169,6 +169,7 @@ export { default as SvgUploadCloud } from "@opal/icons/upload-cloud";
 export { default as SvgUser } from "@opal/icons/user";
 export { default as SvgUserManage } from "@opal/icons/user-manage";
 export { default as SvgUserPlus } from "@opal/icons/user-plus";
+export { default as SvgUserSync } from "@opal/icons/user-sync";
 export { default as SvgUsers } from "@opal/icons/users";
 export { default as SvgWallet } from "@opal/icons/wallet";
 export { default as SvgWorkflow } from "@opal/icons/workflow";
diff --git a/web/lib/opal/src/icons/user-sync.tsx b/web/lib/opal/src/icons/user-sync.tsx
new file mode 100644
index 00000000000..3c6c9f684fb
--- /dev/null
+++ b/web/lib/opal/src/icons/user-sync.tsx
@@ -0,0 +1,22 @@
+import type { IconProps } from "@opal/types";
+
+const SvgUserSync = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M1 14C1 13.6667 1 13.3333 1 13C1 11.3431 2.34316 10 4.00002 10H7M11 8.5L9.5 10L14.5 9.99985M13 14L14.5 12.5L9.5 12.5M8.75 4.75C8.75 6.26878 7.51878 7.5 6 7.5C4.48122 7.5 3.25 6.26878 3.25 4.75C3.25 3.23122 4.48122 2 6 2C7.51878 2 8.75 3.23122 8.75 4.75Z"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+export default SvgUserSync;
diff --git a/web/src/app/admin/scim/ScimModal.tsx b/web/src/app/admin/scim/ScimModal.tsx
new file mode 100644
index 00000000000..a0029b1e099
--- /dev/null
+++ b/web/src/app/admin/scim/ScimModal.tsx
@@ -0,0 +1,138 @@
+import { SvgDownload, SvgKey, SvgRefreshCw } from "@opal/icons";
+import { Interactive } from "@opal/core";
+import { Section } from "@/layouts/general-layouts";
+import { Button } from "@opal/components";
+import Text from "@/refresh-components/texts/Text";
+import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
+import InputTextArea from "@/refresh-components/inputs/InputTextArea";
+import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
+import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
+import { toast } from "@/hooks/useToast";
+import { downloadFile } from "@/lib/download";
+
+import type { ScimModalView } from "./interfaces";
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+interface ScimModalProps {
+  view: ScimModalView;
+  isSubmitting: boolean;
+  onRegenerate: () => void;
+  onClose: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function copyToClipboard(text: string) {
+  try {
+    await navigator.clipboard.writeText(text);
+    toast.success("Token copied to clipboard");
+  } catch {
+    toast.error("Failed to copy token");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function ScimModal({
+  view,
+  isSubmitting,
+  onRegenerate,
+  onClose,
+}: ScimModalProps) {
+  switch (view.kind) {
+    case "regenerate":
+      return (
+        <ConfirmationModalLayout
+          icon={SvgRefreshCw}
+          title="Regenerate SCIM Token"
+          onClose={onClose}
+          submit={
+            <Button
+              variant="danger"
+              onClick={onRegenerate}
+              disabled={isSubmitting}
+            >
+              Regenerate Token
+            </Button>
+          }
+        >
+          <Section alignItems="start" gap={0.5}>
+            <Text as="p" text03>
+              Your current SCIM token will be revoked and a new token will be
+              generated. You will need to update the token on your identity
+              provider before SCIM provisioning will resume.
+            </Text>
+          </Section>
+        </ConfirmationModalLayout>
+      );
+
+    case "token":
+      return (
+        <Modal open onOpenChange={(open) => !open && onClose()}>
+          <Modal.Content width="sm">
+            <Modal.Header
+              icon={SvgKey}
+              title="SCIM Token"
+              description="Save this key before continuing. It won't be shown again."
+              onClose={onClose}
+            />
+            <Modal.Body>
+              <Interactive.Base
+                group="group/token"
+                onClick={() => copyToClipboard(view.rawToken)}
+              >
+                <InputTextArea
+                  value={view.rawToken}
+                  readOnly
+                  autoResize
+                  resizable={false}
+                  rows={2}
+                  className="font-main-ui-mono break-all cursor-pointer [&_textarea]:cursor-pointer"
+                  rightSection={
+                    <div
+                      className="opacity-0 group-hover/token:opacity-100 transition-opacity"
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      <CopyIconButton getCopyText={() => view.rawToken} />
+                    </div>
+                  }
+                />
+              </Interactive.Base>
+            </Modal.Body>
+            <Modal.Footer>
+              <BasicModalFooter
+                left={
+                  <Button
+                    prominence="secondary"
+                    icon={SvgDownload}
+                    onClick={() =>
+                      downloadFile(`onyx-scim-token-${Date.now()}.txt`, {
+                        content: view.rawToken,
+                      })
+                    }
+                  >
+                    Download
+                  </Button>
+                }
+                submit={
+                  <Button
+                    autoFocus
+                    onClick={() => copyToClipboard(view.rawToken)}
+                  >
+                    Copy Token
+                  </Button>
+                }
+              />
+            </Modal.Footer>
+          </Modal.Content>
+        </Modal>
+      );
+  }
+}
diff --git a/web/src/app/admin/scim/ScimSyncCard.tsx b/web/src/app/admin/scim/ScimSyncCard.tsx
new file mode 100644
index 00000000000..9bd562c2ad5
--- /dev/null
+++ b/web/src/app/admin/scim/ScimSyncCard.tsx
@@ -0,0 +1,117 @@
+import { SvgCheckCircle, SvgClock, SvgKey, SvgRefreshCw } from "@opal/icons";
+import { ContentAction } from "@opal/layouts";
+import { Section } from "@/layouts/general-layouts";
+import Card from "@/refresh-components/cards/Card";
+import { Button } from "@opal/components";
+import Text from "@/refresh-components/texts/Text";
+import Separator from "@/refresh-components/Separator";
+import { timeAgo } from "@/lib/time";
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+interface ScimSyncCardProps {
+  hasToken: boolean;
+  isConnected: boolean;
+  lastUsedAt: string | null;
+  idpDomain: string | null;
+  isSubmitting: boolean;
+  onGenerate: () => void;
+  onRegenerate: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function ScimSyncCard({
+  hasToken,
+  isConnected,
+  lastUsedAt,
+  idpDomain,
+  isSubmitting,
+  onGenerate,
+  onRegenerate,
+}: ScimSyncCardProps) {
+  return (
+    <Card gap={0.75}>
+      <ContentAction
+        title="SCIM Sync"
+        description="Connect your identity provider to import and sync users and groups."
+        sizePreset="main-ui"
+        variant="section"
+        paddingVariant="fit"
+        rightChildren={
+          hasToken ? (
+            <Button
+              variant="danger"
+              prominence="secondary"
+              onClick={onRegenerate}
+              icon={SvgRefreshCw}
+            >
+              Regenerate Token
+            </Button>
+          ) : (
+            <Button
+              rightIcon={SvgKey}
+              onClick={onGenerate}
+              disabled={isSubmitting}
+            >
+              Generate SCIM Token
+            </Button>
+          )
+        }
+      />
+
+      {hasToken && (
+        <>
+          <Separator noPadding />
+
+          <Section
+            flexDirection="row"
+            justifyContent="between"
+            alignItems="end"
+            gap={1}
+          >
+            <Section alignItems="start" gap={0} width="fit">
+              {isConnected ? (
+                <SvgCheckCircle size={15} className="text-status-success-05" />
+              ) : (
+                <SvgClock size={15} className="text-theme-amber-05" />
+              )}
+              <Text as="p" mainUiBody text04>
+                {isConnected ? "Connected" : "Waiting for Connection"}
+              </Text>
+            </Section>
+
+            <Section alignItems="end" gap={0} width="fit">
+              {isConnected ? (
+                <>
+                  {idpDomain && (
+                    <Text as="p" secondaryAction text03>
+                      {idpDomain}
+                    </Text>
+                  )}
+                  <Text as="p" secondaryBody text03>
+                    {timeAgo(lastUsedAt)}
+                  </Text>
+                </>
+              ) : (
+                <Text
+                  as="p"
+                  secondaryBody
+                  text03
+                  className="max-w-[240px] text-right"
+                >
+                  Provide the SCIM key to your identity provider to begin
+                  syncing users and groups.
+                </Text>
+              )}
+            </Section>
+          </Section>
+        </>
+      )}
+    </Card>
+  );
+}
diff --git a/web/src/app/admin/scim/interfaces.ts b/web/src/app/admin/scim/interfaces.ts
new file mode 100644
index 00000000000..37331340eda
--- /dev/null
+++ b/web/src/app/admin/scim/interfaces.ts
@@ -0,0 +1,17 @@
+export interface ScimTokenResponse {
+  id: number;
+  name: string;
+  token_display: string;
+  is_active: boolean;
+  created_at: string;
+  last_used_at: string | null;
+  idp_domain: string | null;
+}
+
+export interface ScimTokenCreatedResponse extends ScimTokenResponse {
+  raw_token: string;
+}
+
+export type ScimModalView =
+  | { kind: "regenerate" }
+  | { kind: "token"; rawToken: string };
diff --git a/web/src/app/admin/scim/page.tsx b/web/src/app/admin/scim/page.tsx
new file mode 100644
index 00000000000..14d844b60e2
--- /dev/null
+++ b/web/src/app/admin/scim/page.tsx
@@ -0,0 +1,140 @@
+"use client";
+
+import { useState } from "react";
+
+import { SvgUserSync } from "@opal/icons";
+import { toast } from "@/hooks/useToast";
+import { useScimToken } from "@/hooks/useScimToken";
+import { useCreateModal } from "@/refresh-components/contexts/ModalContext";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import Text from "@/refresh-components/texts/Text";
+import { ThreeDotsLoader } from "@/components/Loading";
+
+import type { ScimTokenCreatedResponse, ScimModalView } from "./interfaces";
+import { generateScimToken } from "./svc";
+import ScimSyncCard from "./ScimSyncCard";
+import ScimModal from "./ScimModal";
+
+// ---------------------------------------------------------------------------
+// SCIM Content
+// ---------------------------------------------------------------------------
+
+function ScimContent() {
+  const { data: token, error: tokenError, isLoading, mutate } = useScimToken();
+
+  const modal = useCreateModal();
+
+  const [modalView, setModalView] = useState<ScimModalView | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const hasToken = !!token;
+  const isConnected = hasToken && token.last_used_at !== null;
+
+  // 404 means no active token — not an error
+  const is404 =
+    tokenError &&
+    typeof tokenError === "object" &&
+    "status" in tokenError &&
+    (tokenError as { status: number }).status === 404;
+
+  if (isLoading) {
+    return <ThreeDotsLoader />;
+  }
+
+  if (tokenError && !is404) {
+    return (
+      <Text as="p" text03>
+        Failed to load SCIM token status.
+      </Text>
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // Handlers
+  // -----------------------------------------------------------------------
+
+  function openModal(view: ScimModalView) {
+    setModalView(view);
+    modal.toggle(true);
+  }
+
+  function closeModal() {
+    modal.toggle(false);
+    setModalView(null);
+  }
+
+  async function handleCreateToken() {
+    setIsSubmitting(true);
+    try {
+      const response = await generateScimToken("default");
+      if (!response.ok) {
+        let detail: string;
+        try {
+          const body = await response.clone().json();
+          detail = body.detail ?? JSON.stringify(body);
+        } catch {
+          detail = await response.text();
+        }
+        toast.error(`Failed to generate token: ${detail}`);
+        return;
+      }
+      const created: ScimTokenCreatedResponse = await response.json();
+      await mutate();
+      openModal({ kind: "token", rawToken: created.raw_token });
+      if (hasToken) toast.success("Token regenerated");
+    } catch {
+      toast.error("Something went wrong. Please try again.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Render
+  // -----------------------------------------------------------------------
+
+  return (
+    <>
+      <ScimSyncCard
+        hasToken={hasToken}
+        isConnected={isConnected}
+        lastUsedAt={token?.last_used_at ?? null}
+        idpDomain={token?.idp_domain ?? null}
+        isSubmitting={isSubmitting}
+        onGenerate={handleCreateToken}
+        onRegenerate={() => openModal({ kind: "regenerate" })}
+      />
+
+      {modal.isOpen && modalView && (
+        <modal.Provider>
+          <ScimModal
+            view={modalView}
+            isSubmitting={isSubmitting}
+            onRegenerate={handleCreateToken}
+            onClose={closeModal}
+          />
+        </modal.Provider>
+      )}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
+export default function Page() {
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={SvgUserSync}
+        title="SCIM"
+        description="Sync users and groups via System for Cross-domain Identity Management (SCIM) protocol."
+        separator
+      />
+      <SettingsLayouts.Body>
+        <ScimContent />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
+  );
+}
diff --git a/web/src/app/admin/scim/svc.ts b/web/src/app/admin/scim/svc.ts
new file mode 100644
index 00000000000..ced9a3a62a9
--- /dev/null
+++ b/web/src/app/admin/scim/svc.ts
@@ -0,0 +1,7 @@
+export async function generateScimToken(name: string) {
+  return fetch("/api/admin/enterprise-settings/scim/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name }),
+  });
+}
diff --git a/web/src/components/admin/ClientLayout.tsx b/web/src/components/admin/ClientLayout.tsx
index 20f21ca7d27..13d66ef6ffe 100644
--- a/web/src/components/admin/ClientLayout.tsx
+++ b/web/src/components/admin/ClientLayout.tsx
@@ -45,6 +45,7 @@ const SETTINGS_LAYOUT_PREFIXES = [
   ADMIN_PATHS.STANDARD_ANSWERS,
   ADMIN_PATHS.GROUPS,
   ADMIN_PATHS.PERFORMANCE,
+  ADMIN_PATHS.SCIM,
 ];
 
 export function ClientLayout({
diff --git a/web/src/hooks/useScimToken.ts b/web/src/hooks/useScimToken.ts
new file mode 100644
index 00000000000..8e2619de3ad
--- /dev/null
+++ b/web/src/hooks/useScimToken.ts
@@ -0,0 +1,16 @@
+import useSWR from "swr";
+
+import { errorHandlingFetcher } from "@/lib/fetcher";
+import type { ScimTokenResponse } from "@/app/admin/scim/interfaces";
+
+const TOKEN_URL = "/api/admin/enterprise-settings/scim/token";
+
+export function useScimToken() {
+  const { data, error, isLoading, mutate } = useSWR<ScimTokenResponse>(
+    TOKEN_URL,
+    errorHandlingFetcher,
+    { shouldRetryOnError: false }
+  );
+
+  return { data, error, isLoading, mutate };
+}
diff --git a/web/src/lib/admin-routes.ts b/web/src/lib/admin-routes.ts
index 619bd2b3b31..adafc8c2b1d 100644
--- a/web/src/lib/admin-routes.ts
+++ b/web/src/lib/admin-routes.ts
@@ -27,6 +27,7 @@ import {
   SvgThumbsUp,
   SvgUploadCloud,
   SvgUser,
+  SvgUserSync,
   SvgUsers,
   SvgWallet,
   SvgZoomIn,
@@ -65,6 +66,7 @@ export const ADMIN_PATHS = {
   THEME: "/admin/theme",
   BILLING: "/admin/billing",
   INDEX_MIGRATION: "/admin/document-index-migration",
+  SCIM: "/admin/scim",
   DEBUG: "/admin/debug",
   // Prefix-only entries (used in SETTINGS_LAYOUT_PREFIXES but have no
   // single page header of their own)
@@ -228,6 +230,11 @@ export const ADMIN_ROUTE_CONFIG: Record<string, AdminRouteConfig> = {
     title: "Document Index Migration",
     sidebarLabel: "Document Index Migration",
   },
+  [ADMIN_PATHS.SCIM]: {
+    icon: SvgUserSync,
+    title: "SCIM",
+    sidebarLabel: "SCIM",
+  },
   [ADMIN_PATHS.DEBUG]: {
     icon: SvgDownload,
     title: "Debug Logs",
diff --git a/web/src/lib/download.ts b/web/src/lib/download.ts
new file mode 100644
index 00000000000..6460569f01f
--- /dev/null
+++ b/web/src/lib/download.ts
@@ -0,0 +1,34 @@
+/**
+ * Trigger a browser file download.
+ *
+ * Supports two modes:
+ *  1. **From content** — pass `content` (string) and optional `mimeType`.
+ *     A Blob is created, downloaded, and the object URL is revoked.
+ *  2. **From URL** — pass `url` (string). The browser navigates to the
+ *     URL with the `download` attribute set.
+ */
+export function downloadFile(
+  filename: string,
+  opts: { content: string; mimeType?: string } | { url: string }
+): void {
+  const a = document.createElement("a");
+
+  if ("content" in opts) {
+    const blob = new Blob([opts.content], {
+      type: opts.mimeType ?? "text/plain",
+    });
+    const url = URL.createObjectURL(blob);
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+  } else {
+    a.href = opts.url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  }
+}
diff --git a/web/src/refresh-components/inputs/InputTextArea.tsx b/web/src/refresh-components/inputs/InputTextArea.tsx
index 99f7211a64f..04300b408c8 100644
--- a/web/src/refresh-components/inputs/InputTextArea.tsx
+++ b/web/src/refresh-components/inputs/InputTextArea.tsx
@@ -53,6 +53,7 @@ export interface InputTextAreaProps
   autoResize?: boolean;
   maxRows?: number;
   resizable?: boolean;
+  rightSection?: React.ReactNode;
 }
 const InputTextArea = React.forwardRef<HTMLTextAreaElement, InputTextAreaProps>(
   (
@@ -64,6 +65,7 @@ const InputTextArea = React.forwardRef<HTMLTextAreaElement, InputTextAreaProps>(
       autoResize = false,
       maxRows,
       resizable = true,
+      rightSection,
       ...props
     },
     ref
@@ -122,7 +124,7 @@ const InputTextArea = React.forwardRef<HTMLTextAreaElement, InputTextAreaProps>(
           disabled={disabled}
           readOnly={isReadOnly}
           className={cn(
-            "w-full min-h-[3rem] bg-transparent focus:outline-none p-0.5",
+            "w-full min-w-0 flex-1 min-h-[3rem] bg-transparent focus:outline-none p-0.5",
             resizeClass,
             innerClasses[variant],
             textClasses[variant]
@@ -130,6 +132,11 @@ const InputTextArea = React.forwardRef<HTMLTextAreaElement, InputTextAreaProps>(
           rows={rows}
           {...props}
         />
+        {rightSection && (
+          <div className="shrink-0 self-start -my-1 -mr-1 font-sans text-base">
+            {rightSection}
+          </div>
+        )}
       </div>
     );
   }
diff --git a/web/src/sections/sidebar/AdminSidebar.tsx b/web/src/sections/sidebar/AdminSidebar.tsx
index 07363141651..fadd543c52b 100644
--- a/web/src/sections/sidebar/AdminSidebar.tsx
+++ b/web/src/sections/sidebar/AdminSidebar.tsx
@@ -127,6 +127,14 @@ const collections = (
               sidebarItem(ADMIN_PATHS.TOKEN_RATE_LIMITS),
             ],
           },
+          ...(enableEnterprise
+            ? [
+                {
+                  name: "Permissions",
+                  items: [sidebarItem(ADMIN_PATHS.SCIM)],
+                },
+              ]
+            : []),
           ...(enableEnterprise
             ? [
                 {
diff --git a/web/tests/e2e/admin/scim/fixtures.ts b/web/tests/e2e/admin/scim/fixtures.ts
new file mode 100644
index 00000000000..2ba21015601
--- /dev/null
+++ b/web/tests/e2e/admin/scim/fixtures.ts
@@ -0,0 +1,114 @@
+/**
+ * Playwright fixtures for SCIM admin UI tests.
+ *
+ * Provides:
+ * - Authenticated admin page
+ * - Stateful mock for the SCIM token endpoint
+ *   (GET starts as 404; POST creates a token and flips GET to 200)
+ */
+
+import { test as base, expect, Page } from "@playwright/test";
+import { loginAs } from "@tests/e2e/utils/auth";
+import type { ScimTokenResponse } from "@/app/admin/scim/interfaces";
+
+// ---------------------------------------------------------------------------
+// Fixture control interface
+// ---------------------------------------------------------------------------
+
+interface MockTokenControl {
+  /** Pre-seed the mock so GET returns an existing token (200). */
+  seedToken: () => ScimTokenResponse;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function authenticateAdmin(page: Page): Promise<void> {
+  await page.context().clearCookies();
+  await loginAs(page, "admin");
+}
+
+function jsonResponse(data: unknown, status = 200) {
+  return {
+    status,
+    contentType: "application/json",
+    body: JSON.stringify(data),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Extended test fixture
+// ---------------------------------------------------------------------------
+
+export const test = base.extend<{
+  adminPage: Page;
+  mockTokenEndpoint: MockTokenControl;
+}>({
+  adminPage: async ({ page }, use) => {
+    await authenticateAdmin(page);
+    await use(page);
+  },
+
+  mockTokenEndpoint: async ({ adminPage }, use) => {
+    let currentToken: ScimTokenResponse | null = null;
+    let tokenCounter = 0;
+
+    function makeToken(): { token: ScimTokenResponse; rawToken: string } {
+      tokenCounter++;
+      const rawToken = `scim_test_token_${tokenCounter}_${Date.now()}`;
+      const token: ScimTokenResponse = {
+        id: tokenCounter,
+        name: "default",
+        token_display: rawToken.slice(0, 16) + "...",
+        is_active: true,
+        created_at: new Date().toISOString(),
+        last_used_at: null,
+        idp_domain: null,
+      };
+      return { token, rawToken };
+    }
+
+    await adminPage.route(
+      "**/api/admin/enterprise-settings/scim/token",
+      async (route) => {
+        const method = route.request().method();
+
+        if (method === "GET") {
+          if (currentToken) {
+            await route.fulfill(jsonResponse(currentToken));
+          } else {
+            await route.fulfill(jsonResponse({ detail: "Not found" }, 404));
+          }
+        } else if (method === "POST") {
+          const { token, rawToken } = makeToken();
+          currentToken = token;
+          await route.fulfill(jsonResponse({ ...token, raw_token: rawToken }));
+        } else {
+          await route.continue();
+        }
+      }
+    );
+
+    await use({
+      seedToken: () => {
+        const { token } = makeToken();
+        currentToken = token;
+        return token;
+      },
+    });
+  },
+});
+
+export { expect };
+
+// ---------------------------------------------------------------------------
+// Navigation helper
+// ---------------------------------------------------------------------------
+
+export async function gotoScimPage(adminPage: Page): Promise<void> {
+  await adminPage.goto("/admin/scim");
+  await expect(adminPage.getByText("SCIM Sync")).toBeVisible({
+    timeout: 15000,
+  });
+}
diff --git a/web/tests/e2e/admin/scim/scim.spec.ts b/web/tests/e2e/admin/scim/scim.spec.ts
new file mode 100644
index 00000000000..05e483812ae
--- /dev/null
+++ b/web/tests/e2e/admin/scim/scim.spec.ts
@@ -0,0 +1,81 @@
+/**
+ * E2E Tests: SCIM Token Management
+ *
+ * Tests the full lifecycle of SCIM tokens — generation, clipboard copy,
+ * file download, and regeneration with confirmation.
+ */
+
+import { test, expect, gotoScimPage } from "./fixtures";
+
+test.describe("SCIM Token Management", () => {
+  test("generate token, copy, and download", async ({
+    adminPage,
+    mockTokenEndpoint: _mockTokenEndpoint,
+  }) => {
+    await gotoScimPage(adminPage);
+
+    // No token yet — click generate
+    await adminPage
+      .getByRole("button", { name: "Generate SCIM Token" })
+      .click();
+
+    // Token modal opens (.first() to skip hidden Radix aria-describedby element)
+    await expect(
+      adminPage.getByText("Save this key before continuing").first()
+    ).toBeVisible({ timeout: 10000 });
+
+    // Grab the raw token from the textarea
+    const textarea = adminPage.locator("textarea");
+    await textarea.waitFor({ state: "visible" });
+    const tokenValue = await textarea.inputValue();
+    expect(tokenValue).toContain("scim_test_token_");
+
+    // Copy to clipboard
+    await adminPage
+      .context()
+      .grantPermissions(["clipboard-read", "clipboard-write"]);
+    await adminPage.getByRole("button", { name: "Copy Token" }).click();
+    await expect(adminPage.getByText("Token copied to clipboard")).toBeVisible({
+      timeout: 5000,
+    });
+    const clipboardText = await adminPage.evaluate(() =>
+      navigator.clipboard.readText()
+    );
+    expect(clipboardText).toBe(tokenValue);
+
+    // Download
+    const downloadPromise = adminPage.waitForEvent("download");
+    await adminPage.getByRole("button", { name: "Download" }).click();
+    const download = await downloadPromise;
+    expect(download.suggestedFilename()).toMatch(/^onyx-scim-token-\d+\.txt$/);
+  });
+
+  test("regenerate token", async ({ adminPage, mockTokenEndpoint }) => {
+    // Start with an existing token so the card shows "Regenerate"
+    mockTokenEndpoint.seedToken();
+    await gotoScimPage(adminPage);
+
+    // Click regenerate on the card
+    await adminPage.getByRole("button", { name: "Regenerate Token" }).click();
+
+    // Confirmation modal appears
+    await expect(adminPage.getByText("Regenerate SCIM Token")).toBeVisible();
+    await expect(
+      adminPage.getByText("Your current SCIM token will be revoked")
+    ).toBeVisible();
+
+    // Confirm via the danger button inside the dialog
+    const dialog = adminPage.locator('[role="dialog"]');
+    await dialog.getByRole("button", { name: "Regenerate Token" }).click();
+
+    // Token display modal replaces the confirmation modal
+    await expect(
+      adminPage.getByText("Save this key before continuing").first()
+    ).toBeVisible({ timeout: 10000 });
+
+    const textarea = adminPage.locator("textarea");
+    await textarea.waitFor({ state: "visible" });
+    const tokenValue = await textarea.inputValue();
+    expect(tokenValue).toContain("scim_test_token_");
+  });
+});

From 5da8870fd27d8a67fbd5ba329c741343f5485e15 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Wed, 4 Mar 2026 12:18:09 -0800
Subject: [PATCH 082/267] fix: stop calling unsupported endpoints no vectordb
 (#9012)

---
 .github/workflows/pr-playwright-tests.yml     | 108 ++++++++++++-
 backend/ee/onyx/db/user_group.py              |   8 +-
 backend/ee/onyx/server/user_group/api.py      |   8 +
 backend/onyx/db/document_set.py               |   5 +-
 .../onyx/server/features/document_set/api.py  |   6 +-
 web/playwright.config.ts                      |  12 +-
 .../configuration/search/UpgradingPage.tsx    |  15 +-
 .../documents/sets/[documentSetId]/page.tsx   |  14 +-
 web/src/app/admin/documents/sets/new/page.tsx |  10 +-
 web/src/app/admin/indexing/status/page.tsx    |   5 +-
 .../ee/admin/groups/UserGroupCreationForm.tsx |  41 +++--
 .../app/ee/admin/groups/[groupId]/page.tsx    |  14 +-
 web/src/app/ee/admin/groups/page.tsx          |  10 +-
 web/src/lib/hooks.ts                          |  20 ++-
 web/src/providers/SettingsProvider.tsx        |   5 +
 .../popovers/ActionsPopover/index.tsx         |   5 +-
 web/src/refresh-pages/AgentEditorPage.tsx     |   5 +-
 web/src/refresh-pages/AppPage.tsx             |   7 +-
 .../admin/ChatPreferencesPage.tsx             |   7 +-
 .../sections/sidebar/UserAvatarPopover.tsx    |   5 +-
 web/tests/e2e/admin/user_groups.spec.ts       | 148 ++++++++++++++++++
 web/tests/e2e/utils/onyxApiClient.ts          |  27 +++-
 22 files changed, 416 insertions(+), 69 deletions(-)
 create mode 100644 web/tests/e2e/admin/user_groups.spec.ts

diff --git a/.github/workflows/pr-playwright-tests.yml b/.github/workflows/pr-playwright-tests.yml
index 6abaad2a525..7dceeda642d 100644
--- a/.github/workflows/pr-playwright-tests.yml
+++ b/.github/workflows/pr-playwright-tests.yml
@@ -268,10 +268,11 @@ jobs:
           persist-credentials: false
 
       - name: Setup node
+        # zizmor: ignore[cache-poisoning] ephemeral runners; no release artifacts
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # ratchet:actions/setup-node@v4
         with:
           node-version: 22
-          cache: "npm"
+          cache: "npm" # zizmor: ignore[cache-poisoning]
           cache-dependency-path: ./web/package-lock.json
 
       - name: Install node dependencies
@@ -279,6 +280,7 @@ jobs:
         run: npm ci
 
       - name: Cache playwright cache
+        # zizmor: ignore[cache-poisoning] ephemeral runners; no release artifacts
         uses: runs-on/cache@50350ad4242587b6c8c2baa2e740b1bc11285ff4 # ratchet:runs-on/cache@v4
         with:
           path: ~/.cache/ms-playwright
@@ -590,6 +592,108 @@ jobs:
           name: docker-logs-${{ matrix.project }}-${{ github.run_id }}
           path: ${{ github.workspace }}/docker-compose.log
 
+  playwright-tests-lite:
+    needs: [build-web-image, build-backend-image]
+    name: Playwright Tests (lite)
+    runs-on:
+      - runs-on
+      - runner=4cpu-linux-arm64
+      - "run-id=${{ github.run_id }}-playwright-tests-lite"
+      - "extras=ecr-cache"
+    timeout-minutes: 30
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Setup node
+        # zizmor: ignore[cache-poisoning] ephemeral runners; no release artifacts
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # ratchet:actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "npm" # zizmor: ignore[cache-poisoning]
+          cache-dependency-path: ./web/package-lock.json
+
+      - name: Install node dependencies
+        working-directory: ./web
+        run: npm ci
+
+      - name: Cache playwright cache
+        # zizmor: ignore[cache-poisoning] ephemeral runners; no release artifacts
+        uses: runs-on/cache@50350ad4242587b6c8c2baa2e740b1bc11285ff4 # ratchet:runs-on/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-npm-${{ hashFiles('web/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-npm-
+
+      - name: Install playwright browsers
+        working-directory: ./web
+        run: npx playwright install --with-deps
+
+      - name: Create .env file for Docker Compose
+        env:
+          OPENAI_API_KEY_VALUE: ${{ env.OPENAI_API_KEY }}
+          ECR_CACHE: ${{ env.RUNS_ON_ECR_CACHE }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          cat <<EOF > deployment/docker_compose/.env
+          ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=true
+          LICENSE_ENFORCEMENT_ENABLED=false
+          AUTH_TYPE=basic
+          INTEGRATION_TESTS_MODE=true
+          GEN_AI_API_KEY=${OPENAI_API_KEY_VALUE}
+          MOCK_LLM_RESPONSE=true
+          REQUIRE_EMAIL_VERIFICATION=false
+          DISABLE_TELEMETRY=true
+          ONYX_BACKEND_IMAGE=${ECR_CACHE}:playwright-test-backend-${RUN_ID}
+          ONYX_WEB_SERVER_IMAGE=${ECR_CACHE}:playwright-test-web-${RUN_ID}
+          EOF
+
+      # needed for pulling external images otherwise, we hit the "Unauthenticated users" limit
+      # https://docs.docker.com/docker-hub/usage/
+      - name: Login to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # ratchet:docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_TOKEN }}
+
+      - name: Start Docker containers (lite)
+        run: |
+          cd deployment/docker_compose
+          docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml -f docker-compose.dev.yml up -d
+        id: start_docker
+
+      - name: Run Playwright tests (lite)
+        working-directory: ./web
+        run: npx playwright test --project lite
+
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        if: always()
+        with:
+          name: playwright-test-results-lite-${{ github.run_id }}
+          path: ./web/output/playwright/
+          retention-days: 30
+
+      - name: Save Docker logs
+        if: success() || failure()
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        run: |
+          cd deployment/docker_compose
+          docker compose logs > docker-compose.log
+          mv docker-compose.log ${WORKSPACE}/docker-compose.log
+
+      - name: Upload logs
+        if: success() || failure()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        with:
+          name: docker-logs-lite-${{ github.run_id }}
+          path: ${{ github.workspace }}/docker-compose.log
+
   # Post a single combined visual regression comment after all matrix jobs finish
   visual-regression-comment:
     needs: [playwright-tests]
@@ -686,7 +790,7 @@ jobs:
     # NOTE: Github-hosted runners have about 20s faster queue times and are preferred here.
     runs-on: ubuntu-slim
     timeout-minutes: 45
-    needs: [playwright-tests]
+    needs: [playwright-tests, playwright-tests-lite]
     if: ${{ always() }}
     steps:
       - name: Check job status
diff --git a/backend/ee/onyx/db/user_group.py b/backend/ee/onyx/db/user_group.py
index 9087b2f9d04..7860c0678a0 100644
--- a/backend/ee/onyx/db/user_group.py
+++ b/backend/ee/onyx/db/user_group.py
@@ -15,6 +15,7 @@
 from ee.onyx.server.user_group.models import SetCuratorRequest
 from ee.onyx.server.user_group.models import UserGroupCreate
 from ee.onyx.server.user_group.models import UserGroupUpdate
+from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.db.connector_credential_pair import get_connector_credential_pair_from_id
 from onyx.db.enums import AccessType
 from onyx.db.enums import ConnectorCredentialPairStatus
@@ -471,7 +472,9 @@ def _add_user_group__cc_pair_relationships__no_commit(
 
 def insert_user_group(db_session: Session, user_group: UserGroupCreate) -> UserGroup:
     db_user_group = UserGroup(
-        name=user_group.name, time_last_modified_by_user=func.now()
+        name=user_group.name,
+        time_last_modified_by_user=func.now(),
+        is_up_to_date=DISABLE_VECTOR_DB,
     )
     db_session.add(db_user_group)
     db_session.flush()  # give the group an ID
@@ -774,8 +777,7 @@ def update_user_group(
             cc_pair_ids=user_group_update.cc_pair_ids,
         )
 
-    # only needs to sync with Vespa if the cc_pairs have been updated
-    if cc_pairs_updated:
+    if cc_pairs_updated and not DISABLE_VECTOR_DB:
         db_user_group.is_up_to_date = False
 
     removed_users = db_session.scalars(
diff --git a/backend/ee/onyx/server/user_group/api.py b/backend/ee/onyx/server/user_group/api.py
index b56a65c303c..9c2709955c5 100644
--- a/backend/ee/onyx/server/user_group/api.py
+++ b/backend/ee/onyx/server/user_group/api.py
@@ -5,6 +5,8 @@
 from sqlalchemy.orm import Session
 
 from ee.onyx.db.user_group import add_users_to_user_group
+from ee.onyx.db.user_group import delete_user_group as db_delete_user_group
+from ee.onyx.db.user_group import fetch_user_group
 from ee.onyx.db.user_group import fetch_user_groups
 from ee.onyx.db.user_group import fetch_user_groups_for_user
 from ee.onyx.db.user_group import insert_user_group
@@ -20,6 +22,7 @@
 from onyx.auth.users import current_admin_user
 from onyx.auth.users import current_curator_or_admin_user
 from onyx.auth.users import current_user
+from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.configs.constants import PUBLIC_API_TAGS
 from onyx.db.engine.sql_engine import get_session
 from onyx.db.models import User
@@ -153,3 +156,8 @@ def delete_user_group(
         prepare_user_group_for_deletion(db_session, user_group_id)
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
+
+    if DISABLE_VECTOR_DB:
+        user_group = fetch_user_group(db_session, user_group_id)
+        if user_group:
+            db_delete_user_group(db_session, user_group)
diff --git a/backend/onyx/db/document_set.py b/backend/onyx/db/document_set.py
index 277f41ac280..b39114ac88f 100644
--- a/backend/onyx/db/document_set.py
+++ b/backend/onyx/db/document_set.py
@@ -13,6 +13,7 @@
 from sqlalchemy.orm import selectinload
 from sqlalchemy.orm import Session
 
+from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.db.connector_credential_pair import get_cc_pair_groups_for_ids
 from onyx.db.connector_credential_pair import get_connector_credential_pairs
 from onyx.db.enums import AccessType
@@ -246,6 +247,7 @@ def insert_document_set(
             description=document_set_creation_request.description,
             user_id=user_id,
             is_public=document_set_creation_request.is_public,
+            is_up_to_date=DISABLE_VECTOR_DB,
             time_last_modified_by_user=func.now(),
         )
         db_session.add(new_document_set_row)
@@ -336,7 +338,8 @@ def update_document_set(
             )
 
         document_set_row.description = document_set_update_request.description
-        document_set_row.is_up_to_date = False
+        if not DISABLE_VECTOR_DB:
+            document_set_row.is_up_to_date = False
         document_set_row.is_public = document_set_update_request.is_public
         document_set_row.time_last_modified_by_user = func.now()
         versioned_private_doc_set_fn = fetch_versioned_implementation(
diff --git a/backend/onyx/server/features/document_set/api.py b/backend/onyx/server/features/document_set/api.py
index 262e1ba649b..8e71cf689d9 100644
--- a/backend/onyx/server/features/document_set/api.py
+++ b/backend/onyx/server/features/document_set/api.py
@@ -11,6 +11,7 @@
 from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryTask
 from onyx.db.document_set import check_document_sets_are_public
+from onyx.db.document_set import delete_document_set as db_delete_document_set
 from onyx.db.document_set import fetch_all_document_sets_for_user
 from onyx.db.document_set import get_document_set_by_id
 from onyx.db.document_set import insert_document_set
@@ -142,7 +143,10 @@ def delete_document_set(
     except Exception as e:
         raise HTTPException(status_code=400, detail=str(e))
 
-    if not DISABLE_VECTOR_DB:
+    if DISABLE_VECTOR_DB:
+        db_session.refresh(document_set)
+        db_delete_document_set(document_set, db_session)
+    else:
         client_app.send_task(
             OnyxCeleryTask.CHECK_FOR_VESPA_SYNC_TASK,
             kwargs={"tenant_id": tenant_id},
diff --git a/web/playwright.config.ts b/web/playwright.config.ts
index 3b07d4e6ed1..4c6efcd4dce 100644
--- a/web/playwright.config.ts
+++ b/web/playwright.config.ts
@@ -41,7 +41,7 @@ export default defineConfig({
         viewport: { width: 1280, height: 720 },
         storageState: "admin_auth.json",
       },
-      grepInvert: /@exclusive/,
+      grepInvert: [/@exclusive/, /@lite/],
     },
     {
       // this suite runs independently and serially + slower
@@ -55,5 +55,15 @@ export default defineConfig({
       grep: /@exclusive/,
       workers: 1,
     },
+    {
+      // runs against the Onyx Lite stack (DISABLE_VECTOR_DB=true, no Vespa/Redis)
+      name: "lite",
+      use: {
+        ...devices["Desktop Chrome"],
+        viewport: { width: 1280, height: 720 },
+        storageState: "admin_auth.json",
+      },
+      grep: /@lite/,
+    },
   ],
 });
diff --git a/web/src/app/admin/configuration/search/UpgradingPage.tsx b/web/src/app/admin/configuration/search/UpgradingPage.tsx
index dc18250b3d1..5d957b0f81d 100644
--- a/web/src/app/admin/configuration/search/UpgradingPage.tsx
+++ b/web/src/app/admin/configuration/search/UpgradingPage.tsx
@@ -23,6 +23,7 @@ import { FailedReIndexAttempts } from "@/components/embedding/FailedReIndexAttem
 import { useConnectorIndexingStatusWithPagination } from "@/lib/hooks";
 import { SvgX } from "@opal/icons";
 import { ConnectorCredentialPairStatus } from "@/app/admin/connector/[ccPairId]/types";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 
 export default function UpgradingPage({
   futureEmbeddingModel,
@@ -30,11 +31,12 @@ export default function UpgradingPage({
   futureEmbeddingModel: CloudEmbeddingModel | HostedEmbeddingModel;
 }) {
   const [isCancelling, setIsCancelling] = useState<boolean>(false);
+  const vectorDbEnabled = useVectorDbEnabled();
 
   const { data: connectors, isLoading: isLoadingConnectors } = useSWR<
     Connector<any>[]
-  >("/api/manage/connector", errorHandlingFetcher, {
-    refreshInterval: 5000, // 5 seconds
+  >(vectorDbEnabled ? "/api/manage/connector" : null, errorHandlingFetcher, {
+    refreshInterval: 5000,
   });
 
   const {
@@ -42,7 +44,8 @@ export default function UpgradingPage({
     isLoading: isLoadingOngoingReIndexingStatus,
   } = useConnectorIndexingStatusWithPagination(
     { secondary_index: true, get_all_connectors: true },
-    5000
+    5000,
+    vectorDbEnabled
   ) as {
     data: ConnectorIndexingStatusLiteResponse[];
     isLoading: boolean;
@@ -51,9 +54,11 @@ export default function UpgradingPage({
   const { data: failedIndexingStatus } = useSWR<
     FailedConnectorIndexingStatus[]
   >(
-    "/api/manage/admin/connector/failed-indexing-status?secondary_index=true",
+    vectorDbEnabled
+      ? "/api/manage/admin/connector/failed-indexing-status?secondary_index=true"
+      : null,
     errorHandlingFetcher,
-    { refreshInterval: 5000 } // 5 seconds
+    { refreshInterval: 5000 }
   );
 
   const onCancel = async () => {
diff --git a/web/src/app/admin/documents/sets/[documentSetId]/page.tsx b/web/src/app/admin/documents/sets/[documentSetId]/page.tsx
index b12ca3d724e..33edc03c308 100644
--- a/web/src/app/admin/documents/sets/[documentSetId]/page.tsx
+++ b/web/src/app/admin/documents/sets/[documentSetId]/page.tsx
@@ -10,9 +10,11 @@ import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import CardSection from "@/components/admin/CardSection";
 import { DocumentSetCreationForm } from "../DocumentSetCreationForm";
 import { useRouter } from "next/navigation";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 
 function Main({ documentSetId }: { documentSetId: number }) {
   const router = useRouter();
+  const vectorDbEnabled = useVectorDbEnabled();
 
   const {
     data: documentSets,
@@ -24,12 +26,16 @@ function Main({ documentSetId }: { documentSetId: number }) {
     data: ccPairs,
     isLoading: isCCPairsLoading,
     error: ccPairsError,
-  } = useConnectorStatus();
+  } = useConnectorStatus(30000, vectorDbEnabled);
 
   // EE only
   const { data: userGroups, isLoading: userGroupsIsLoading } = useUserGroups();
 
-  if (isDocumentSetsLoading || isCCPairsLoading || userGroupsIsLoading) {
+  if (
+    isDocumentSetsLoading ||
+    (vectorDbEnabled && isCCPairsLoading) ||
+    userGroupsIsLoading
+  ) {
     return (
       <div className="flex justify-center items-center min-h-[400px]">
         <ThreeDotsLoader />
@@ -46,7 +52,7 @@ function Main({ documentSetId }: { documentSetId: number }) {
     );
   }
 
-  if (ccPairsError || !ccPairs) {
+  if (vectorDbEnabled && (ccPairsError || !ccPairs)) {
     return (
       <ErrorCallout
         errorTitle="Failed to fetch Connectors"
@@ -70,7 +76,7 @@ function Main({ documentSetId }: { documentSetId: number }) {
   return (
     <CardSection>
       <DocumentSetCreationForm
-        ccPairs={ccPairs}
+        ccPairs={ccPairs ?? []}
         userGroups={userGroups}
         onClose={() => {
           refreshDocumentSets();
diff --git a/web/src/app/admin/documents/sets/new/page.tsx b/web/src/app/admin/documents/sets/new/page.tsx
index 0b0a6c34857..598ad894682 100644
--- a/web/src/app/admin/documents/sets/new/page.tsx
+++ b/web/src/app/admin/documents/sets/new/page.tsx
@@ -9,20 +9,22 @@ import { ErrorCallout } from "@/components/ErrorCallout";
 import { useRouter } from "next/navigation";
 import { refreshDocumentSets } from "../hooks";
 import CardSection from "@/components/admin/CardSection";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 
 function Main() {
   const router = useRouter();
+  const vectorDbEnabled = useVectorDbEnabled();
 
   const {
     data: ccPairs,
     isLoading: isCCPairsLoading,
     error: ccPairsError,
-  } = useConnectorStatus();
+  } = useConnectorStatus(30000, vectorDbEnabled);
 
   // EE only
   const { data: userGroups, isLoading: userGroupsIsLoading } = useUserGroups();
 
-  if (isCCPairsLoading || userGroupsIsLoading) {
+  if ((vectorDbEnabled && isCCPairsLoading) || userGroupsIsLoading) {
     return (
       <div className="flex justify-center items-center min-h-[400px]">
         <ThreeDotsLoader />
@@ -30,7 +32,7 @@ function Main() {
     );
   }
 
-  if (ccPairsError || !ccPairs) {
+  if (vectorDbEnabled && (ccPairsError || !ccPairs)) {
     return (
       <ErrorCallout
         errorTitle="Failed to fetch Connectors"
@@ -43,7 +45,7 @@ function Main() {
     <>
       <CardSection>
         <DocumentSetCreationForm
-          ccPairs={ccPairs}
+          ccPairs={ccPairs ?? []}
           userGroups={userGroups}
           onClose={() => {
             refreshDocumentSets();
diff --git a/web/src/app/admin/indexing/status/page.tsx b/web/src/app/admin/indexing/status/page.tsx
index 48725c14292..90212882bf4 100644
--- a/web/src/app/admin/indexing/status/page.tsx
+++ b/web/src/app/admin/indexing/status/page.tsx
@@ -9,6 +9,7 @@ import Text from "@/components/ui/text";
 import { useConnectorIndexingStatusWithPagination } from "@/lib/hooks";
 import { useToastFromQuery } from "@/hooks/useToast";
 import Button from "@/refresh-components/buttons/Button";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 import { useState, useRef, useMemo, RefObject } from "react";
 import { FilterOptions } from "./FilterComponent";
 import { ValidSources } from "@/lib/types";
@@ -18,6 +19,8 @@ import { ConnectorStaggeredSkeleton } from "./ConnectorRowSkeleton";
 import { IndexingStatusRequest } from "@/lib/types";
 
 function Main() {
+  const vectorDbEnabled = useVectorDbEnabled();
+
   // State for filter management
   const [filterOptions, setFilterOptions] = useState<FilterOptions>({
     accessType: null,
@@ -65,7 +68,7 @@ function Main() {
     sourcePages,
     sourceLoadingStates,
     resetPagination,
-  } = useConnectorIndexingStatusWithPagination(request, 30000);
+  } = useConnectorIndexingStatusWithPagination(request, 30000, vectorDbEnabled);
 
   // Check if filters are active
   const hasActiveFilters = useMemo(() => {
diff --git a/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx b/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx
index 09e5e5c288e..52fa890ed76 100644
--- a/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx
+++ b/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx
@@ -11,6 +11,7 @@ import Button from "@/refresh-components/buttons/Button";
 import Separator from "@/refresh-components/Separator";
 import Text from "@/refresh-components/texts/Text";
 import { SvgUsers } from "@opal/icons";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 export interface UserGroupCreationFormProps {
   onClose: () => void;
   users: User[];
@@ -25,8 +26,8 @@ export default function UserGroupCreationForm({
   existingUserGroup,
 }: UserGroupCreationFormProps) {
   const isUpdate = existingUserGroup !== undefined;
+  const vectorDbEnabled = useVectorDbEnabled();
 
-  // Filter out ccPairs that aren't access_type "private"
   const privateCcPairs = ccPairs.filter(
     (ccPair) => ccPair.access_type === "private"
   );
@@ -87,21 +88,31 @@ export default function UserGroupCreationForm({
 
                 <Separator />
 
-                <Text as="p" className="font-medium">
-                  Select which private connectors this group has access to:
-                </Text>
-                <Text as="p" text02>
-                  All documents indexed by the selected connectors will be
-                  visible to users in this group.
-                </Text>
+                {vectorDbEnabled ? (
+                  <>
+                    <Text as="p" className="font-medium">
+                      Select which private connectors this group has access to:
+                    </Text>
+                    <Text as="p" text02>
+                      All documents indexed by the selected connectors will be
+                      visible to users in this group.
+                    </Text>
 
-                <ConnectorEditor
-                  allCCPairs={privateCcPairs}
-                  selectedCCPairIds={values.cc_pair_ids}
-                  setSetCCPairIds={(ccPairsIds) =>
-                    setFieldValue("cc_pair_ids", ccPairsIds)
-                  }
-                />
+                    <ConnectorEditor
+                      allCCPairs={privateCcPairs}
+                      selectedCCPairIds={values.cc_pair_ids}
+                      setSetCCPairIds={(ccPairsIds) =>
+                        setFieldValue("cc_pair_ids", ccPairsIds)
+                      }
+                    />
+                  </>
+                ) : (
+                  <Text as="p" text03>
+                    Connectors are not available in Onyx Lite. Redeploy Onyx
+                    with DISABLE_VECTOR_DB=false to index knowledge via
+                    connectors.
+                  </Text>
+                )}
 
                 <Separator />
 
diff --git a/web/src/app/ee/admin/groups/[groupId]/page.tsx b/web/src/app/ee/admin/groups/[groupId]/page.tsx
index 1cfd5b4234f..5e5e3eb441b 100644
--- a/web/src/app/ee/admin/groups/[groupId]/page.tsx
+++ b/web/src/app/ee/admin/groups/[groupId]/page.tsx
@@ -8,10 +8,12 @@ import { useConnectorStatus } from "@/lib/hooks";
 import useUsers from "@/hooks/useUsers";
 import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 
 const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.GROUPS]!;
 
 function Main({ groupId }: { groupId: string }) {
+  const vectorDbEnabled = useVectorDbEnabled();
   const {
     userGroup,
     isLoading: userGroupIsLoading,
@@ -27,9 +29,13 @@ function Main({ groupId }: { groupId: string }) {
     data: ccPairs,
     isLoading: isCCPairsLoading,
     error: ccPairsError,
-  } = useConnectorStatus();
+  } = useConnectorStatus(30000, vectorDbEnabled);
 
-  if (userGroupIsLoading || userIsLoading || isCCPairsLoading) {
+  if (
+    userGroupIsLoading ||
+    userIsLoading ||
+    (vectorDbEnabled && isCCPairsLoading)
+  ) {
     return (
       <div className="h-full">
         <div className="my-auto">
@@ -45,7 +51,7 @@ function Main({ groupId }: { groupId: string }) {
   if (!users || usersError) {
     return <div>Error loading users</div>;
   }
-  if (!ccPairs || ccPairsError) {
+  if (vectorDbEnabled && (!ccPairs || ccPairsError)) {
     return <div>Error loading connectors</div>;
   }
 
@@ -61,7 +67,7 @@ function Main({ groupId }: { groupId: string }) {
       <SettingsLayouts.Body>
         <GroupDisplay
           users={users.accepted}
-          ccPairs={ccPairs}
+          ccPairs={ccPairs ?? []}
           userGroup={userGroup}
           refreshUserGroup={refreshUserGroup}
         />
diff --git a/web/src/app/ee/admin/groups/page.tsx b/web/src/app/ee/admin/groups/page.tsx
index d6a977d2205..bf7cc733fcd 100644
--- a/web/src/app/ee/admin/groups/page.tsx
+++ b/web/src/app/ee/admin/groups/page.tsx
@@ -10,11 +10,13 @@ import { useUser } from "@/providers/UserProvider";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 
 const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.GROUPS]!;
 
 function Main() {
   const [showForm, setShowForm] = useState(false);
+  const vectorDbEnabled = useVectorDbEnabled();
 
   const { data, isLoading, error, refreshUserGroups } = useUserGroups();
 
@@ -22,7 +24,7 @@ function Main() {
     data: ccPairs,
     isLoading: isCCPairsLoading,
     error: ccPairsError,
-  } = useConnectorStatus();
+  } = useConnectorStatus(30000, vectorDbEnabled);
 
   const {
     data: users,
@@ -32,7 +34,7 @@ function Main() {
 
   const { isAdmin } = useUser();
 
-  if (isLoading || isCCPairsLoading || userIsLoading) {
+  if (isLoading || (vectorDbEnabled && isCCPairsLoading) || userIsLoading) {
     return <ThreeDotsLoader />;
   }
 
@@ -40,7 +42,7 @@ function Main() {
     return <div className="text-red-600">Error loading users</div>;
   }
 
-  if (ccPairsError || !ccPairs) {
+  if (vectorDbEnabled && (ccPairsError || !ccPairs)) {
     return <div className="text-red-600">Error loading connectors</div>;
   }
 
@@ -67,7 +69,7 @@ function Main() {
             setShowForm(false);
           }}
           users={users.accepted}
-          ccPairs={ccPairs}
+          ccPairs={ccPairs ?? []}
         />
       )}
     </>
diff --git a/web/src/lib/hooks.ts b/web/src/lib/hooks.ts
index 93e67799b72..b58edb5e269 100644
--- a/web/src/lib/hooks.ts
+++ b/web/src/lib/hooks.ts
@@ -92,7 +92,8 @@ const CONNECTOR_STATUS_URL = "/api/manage/admin/connector/status";
 
 export const useConnectorIndexingStatusWithPagination = (
   filters: Omit<IndexingStatusRequest, "source" | "source_to_page"> = {},
-  refreshInterval = 30000
+  refreshInterval = 30000,
+  enabled: boolean = true
 ) => {
   const { mutate } = useSWRConfig();
   //maintains the current page for each source
@@ -124,7 +125,9 @@ export const useConnectorIndexingStatusWithPagination = (
     [filters]
   );
 
-  const swrKey = [INDEXING_STATUS_URL, JSON.stringify(mainRequest)];
+  const swrKey = enabled
+    ? [INDEXING_STATUS_URL, JSON.stringify(mainRequest)]
+    : null;
 
   // Main data fetch with auto-refresh
   const { data, isLoading, error } = useSWR<
@@ -187,7 +190,7 @@ export const useConnectorIndexingStatusWithPagination = (
 
   // Function to refresh all data (maintains current pagination)
   const refreshAllData = useCallback(() => {
-    mutate(swrKey);
+    if (swrKey) mutate(swrKey);
   }, [mutate, swrKey]);
 
   // Reset pagination when filters change (but not search)
@@ -207,18 +210,21 @@ export const useConnectorIndexingStatusWithPagination = (
   };
 };
 
-export const useConnectorStatus = (refreshInterval = 30000) => {
+export const useConnectorStatus = (
+  refreshInterval = 30000,
+  enabled: boolean = true
+) => {
   const { mutate } = useSWRConfig();
   const url = CONNECTOR_STATUS_URL;
   const swrResponse = useSWR<ConnectorStatus<any, any>[]>(
-    url,
+    enabled ? url : null,
     errorHandlingFetcher,
     { refreshInterval: refreshInterval }
   );
 
   return {
     ...swrResponse,
-    refreshIndexingStatus: () => mutate(url),
+    refreshIndexingStatus: enabled ? () => mutate(url) : () => {},
   };
 };
 
@@ -230,7 +236,7 @@ export const useBasicConnectorStatus = (enabled: boolean = true) => {
   );
   return {
     ...swrResponse,
-    refreshIndexingStatus: () => mutate(url),
+    refreshIndexingStatus: enabled ? () => mutate(url) : () => {},
   };
 };
 
diff --git a/web/src/providers/SettingsProvider.tsx b/web/src/providers/SettingsProvider.tsx
index 02f1c095c72..85a9557605d 100644
--- a/web/src/providers/SettingsProvider.tsx
+++ b/web/src/providers/SettingsProvider.tsx
@@ -66,3 +66,8 @@ export function useSettingsContext() {
   }
   return context;
 }
+
+export function useVectorDbEnabled(): boolean {
+  const settings = useSettingsContext();
+  return settings.settings.vector_db_enabled !== false;
+}
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index 5329706909b..57da4db2f2b 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -29,7 +29,7 @@ import { SourceMetadata } from "@/lib/search/interfaces";
 import { SourceIcon } from "@/components/SourceIcon";
 import { useAvailableTools } from "@/hooks/useAvailableTools";
 import useCCPairs from "@/hooks/useCCPairs";
-import { useSettingsContext } from "@/providers/SettingsProvider";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { useToolOAuthStatus } from "@/lib/hooks/useToolOAuthStatus";
 import LineItem from "@/refresh-components/buttons/LineItem";
@@ -298,8 +298,7 @@ export default function ActionsPopover({
   }, [selectedAgent.id, setForcedToolIds]);
 
   const { isAdmin, isCurator } = useUser();
-  const settings = useSettingsContext();
-  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
+  const vectorDbEnabled = useVectorDbEnabled();
 
   const { tools: availableTools } = useAvailableTools();
   const { ccPairs } = useCCPairs(vectorDbEnabled);
diff --git a/web/src/refresh-pages/AgentEditorPage.tsx b/web/src/refresh-pages/AgentEditorPage.tsx
index 4eff2ff33a2..58465f33213 100644
--- a/web/src/refresh-pages/AgentEditorPage.tsx
+++ b/web/src/refresh-pages/AgentEditorPage.tsx
@@ -86,7 +86,7 @@ import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationMo
 import ShareAgentModal from "@/sections/modals/ShareAgentModal";
 import AgentKnowledgePane from "@/sections/knowledge/AgentKnowledgePane";
 import { ValidSources } from "@/lib/types";
-import { useSettingsContext } from "@/providers/SettingsProvider";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 import { useUser } from "@/providers/UserProvider";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 
@@ -447,10 +447,9 @@ export default function AgentEditorPage({
   const { refresh: refreshAgents } = useAgents();
   const shareAgentModal = useCreateModal();
   const deleteAgentModal = useCreateModal();
-  const settings = useSettingsContext();
   const { isAdmin, isCurator } = useUser();
   const canUpdateFeaturedStatus = isAdmin || isCurator;
-  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
+  const vectorDbEnabled = useVectorDbEnabled();
 
   // LLM Model Selection
   const getCurrentLlm = useCallback(
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 418786686db..24a5c86747c 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -12,7 +12,10 @@ import { useFederatedConnectors, useFilters, useLlmManager } from "@/lib/hooks";
 import { useForcedTools } from "@/lib/hooks/useForcedTools";
 import OnyxInitializingLoader from "@/components/OnyxInitializingLoader";
 import { OnyxDocument, MinimalOnyxDocument } from "@/lib/search/interfaces";
-import { useSettingsContext } from "@/providers/SettingsProvider";
+import {
+  useSettingsContext,
+  useVectorDbEnabled,
+} from "@/providers/SettingsProvider";
 import Dropzone from "react-dropzone";
 import AppInputBar, { AppInputBarHandle } from "@/sections/input/AppInputBar";
 import useChatSessions from "@/hooks/useChatSessions";
@@ -142,7 +145,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
   // settings are passed in via Context and therefore aren't
   // available in server-side components
   const settings = useSettingsContext();
-  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
+  const vectorDbEnabled = useVectorDbEnabled();
   const { ccPairs } = useCCPairs(vectorDbEnabled);
   const { tags } = useTags();
   const { documentSets } = useDocumentSets();
diff --git a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
index 75826bd23a4..46d4fc62ff9 100644
--- a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
+++ b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
@@ -26,7 +26,10 @@ import {
 } from "@opal/icons";
 import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { Content } from "@opal/layouts";
-import { useSettingsContext } from "@/providers/SettingsProvider";
+import {
+  useSettingsContext,
+  useVectorDbEnabled,
+} from "@/providers/SettingsProvider";
 import useCCPairs from "@/hooks/useCCPairs";
 import { getSourceMetadata } from "@/lib/sources";
 import EmptyMessage from "@/refresh-components/EmptyMessage";
@@ -186,7 +189,7 @@ function ChatPreferencesForm() {
 
   // Tools availability
   const { tools: availableTools } = useAvailableTools();
-  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
+  const vectorDbEnabled = useVectorDbEnabled();
   const searchTool = availableTools.find(
     (t) => t.in_code_tool_id === SEARCH_TOOL_ID
   );
diff --git a/web/src/sections/sidebar/UserAvatarPopover.tsx b/web/src/sections/sidebar/UserAvatarPopover.tsx
index 0b95e6afb40..fa8489a9330 100644
--- a/web/src/sections/sidebar/UserAvatarPopover.tsx
+++ b/web/src/sections/sidebar/UserAvatarPopover.tsx
@@ -25,7 +25,7 @@ import {
 import { Section } from "@/layouts/general-layouts";
 import { toast } from "@/hooks/useToast";
 import useAppFocus from "@/hooks/useAppFocus";
-import { useSettingsContext } from "@/providers/SettingsProvider";
+import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 
 function getDisplayName(email?: string, personalName?: string): string {
   // Prioritize custom personal name if set
@@ -166,8 +166,7 @@ export default function UserAvatarPopover({
   const { user } = useUser();
   const router = useRouter();
   const appFocus = useAppFocus();
-  const settings = useSettingsContext();
-  const vectorDbEnabled = settings?.settings.vector_db_enabled !== false;
+  const vectorDbEnabled = useVectorDbEnabled();
 
   // Fetch notifications for display
   // The GET endpoint also triggers a refresh if release notes are stale
diff --git a/web/tests/e2e/admin/user_groups.spec.ts b/web/tests/e2e/admin/user_groups.spec.ts
new file mode 100644
index 00000000000..fcf6cb64c4d
--- /dev/null
+++ b/web/tests/e2e/admin/user_groups.spec.ts
@@ -0,0 +1,148 @@
+import { test, expect, BrowserContext } from "@playwright/test";
+import { OnyxApiClient } from "@tests/e2e/utils/onyxApiClient";
+
+test.use({ storageState: "admin_auth.json" });
+
+test.describe("User Groups - No Vector DB @lite", () => {
+  test.beforeAll(async ({ browser }) => {
+    const context = await browser.newContext({
+      storageState: "admin_auth.json",
+    });
+    try {
+      const client = new OnyxApiClient(context.request);
+      const vectorDbEnabled = await client.isVectorDbEnabled();
+      test.skip(
+        vectorDbEnabled,
+        "Skipped: vector DB is enabled in this deployment"
+      );
+    } finally {
+      await context.close();
+    }
+  });
+
+  test("should show user group as synced immediately on creation", async ({
+    page,
+  }) => {
+    const groupName = `E2E-NoVectorDB-Group-${Date.now()}`;
+    let groupId: number | undefined;
+
+    try {
+      await page.goto("/admin/groups");
+      await page.waitForLoadState("networkidle");
+
+      await page.getByRole("button", { name: "Create New User Group" }).click();
+
+      const dialog = page.getByRole("dialog");
+      await expect(dialog).toBeVisible();
+
+      await dialog.locator('input[name="name"]').fill(groupName);
+
+      await expect(
+        dialog.getByText("Connectors are not available in Onyx Lite")
+      ).toBeVisible();
+
+      await dialog.getByRole("button", { name: "Create!" }).click();
+
+      await expect(dialog).not.toBeVisible({ timeout: 10000 });
+
+      const groupRow = page.getByRole("row").filter({ hasText: groupName });
+      await expect(groupRow).toBeVisible({ timeout: 10000 });
+      await expect(groupRow.getByText("Up to date!")).toBeVisible();
+
+      const groupLink = groupRow.getByRole("link", { name: groupName });
+      const href = await groupLink.getAttribute("href");
+      const match = href?.match(/\/admin\/groups\/(\d+)/);
+      if (match) {
+        groupId = parseInt(match[1] ?? "", 10);
+      }
+
+      await groupLink.click();
+      await page.waitForLoadState("networkidle");
+
+      await expect(page.getByText("Up to date")).toBeVisible({ timeout: 5000 });
+
+      const addUsersButton = page.getByRole("button", {
+        name: "Add Users",
+      });
+      await expect(addUsersButton).toBeEnabled();
+    } finally {
+      if (groupId !== undefined) {
+        const apiClient = new OnyxApiClient(page.request);
+        await apiClient.deleteUserGroup(groupId);
+      }
+    }
+  });
+});
+
+test.describe("User Groups - Standard Deployment @exclusive", () => {
+  let cleanupContext: BrowserContext | undefined;
+  let client: OnyxApiClient;
+  let ccPairId: number | undefined;
+  let groupId: number | undefined;
+
+  test.beforeAll(async ({ browser }) => {
+    const context = await browser.newContext({
+      storageState: "admin_auth.json",
+    });
+    try {
+      client = new OnyxApiClient(context.request);
+      const vectorDbEnabled = await client.isVectorDbEnabled();
+      if (!vectorDbEnabled) {
+        await context.close();
+        test.skip(true, "Skipped: vector DB is disabled in this deployment");
+        return;
+      }
+      cleanupContext = context;
+    } catch (e) {
+      await context.close();
+      throw e;
+    }
+  });
+
+  test.afterAll(async () => {
+    try {
+      if (groupId !== undefined) {
+        await client.deleteUserGroup(groupId).catch(() => {});
+      }
+      if (ccPairId !== undefined) {
+        await client.deleteCCPair(ccPairId).catch(() => {});
+      }
+    } finally {
+      await cleanupContext?.close();
+    }
+  });
+
+  test("should sync user group with connector", async ({ page }) => {
+    const apiClient = new OnyxApiClient(page.request);
+    const groupName = `E2E-Sync-Group-${Date.now()}`;
+
+    ccPairId = await apiClient.createFileConnector(
+      `E2E-Group-Connector-${Date.now()}`,
+      "private"
+    );
+
+    groupId = await apiClient.createUserGroup(groupName, [], [ccPairId]);
+
+    await page.goto("/admin/groups");
+    await page.waitForLoadState("networkidle");
+
+    const groupRow = page.getByRole("row").filter({ hasText: groupName });
+    await expect(groupRow).toBeVisible({ timeout: 10000 });
+
+    const upToDate = groupRow.getByText("Up to date!");
+    const deadline = Date.now() + 120_000;
+    while (Date.now() < deadline) {
+      if (await upToDate.isVisible().catch(() => false)) break;
+      await page.waitForTimeout(3000);
+      await page.reload();
+      await page.waitForLoadState("networkidle");
+    }
+    await expect(upToDate).toBeVisible({ timeout: 5000 });
+
+    const groupLink = groupRow.getByRole("link", { name: groupName });
+    await groupLink.click();
+    await page.waitForLoadState("networkidle");
+
+    await expect(page.getByText("Up to date")).toBeVisible({ timeout: 10000 });
+  });
+});
diff --git a/web/tests/e2e/utils/onyxApiClient.ts b/web/tests/e2e/utils/onyxApiClient.ts
index 14c1ee01795..5ac5aa2e860 100644
--- a/web/tests/e2e/utils/onyxApiClient.ts
+++ b/web/tests/e2e/utils/onyxApiClient.ts
@@ -217,16 +217,32 @@ export class OnyxApiClient {
     console.log(`[OnyxApiClient] ${message}`);
   }
 
+  /**
+   * Checks whether the vector database is enabled in this deployment.
+   *
+   * @returns true if vector DB is enabled, false if DISABLE_VECTOR_DB is set
+   */
+  async isVectorDbEnabled(): Promise<boolean> {
+    const response = await this.get("/settings");
+    const data = await this.handleResponse<{ vector_db_enabled: boolean }>(
+      response,
+      "Failed to fetch settings"
+    );
+    return data.vector_db_enabled;
+  }
+
   /**
    * Creates a simple file connector with mock credentials.
    * This enables the Knowledge toggle in assistant creation.
    *
    * @param connectorName - Name for the connector (defaults to "Test File Connector")
+   * @param accessType - Access type for the connector (defaults to "public")
    * @returns The connector-credential pair ID (ccPairId)
    * @throws Error if the connector creation fails
    */
   async createFileConnector(
-    connectorName: string = "Test File Connector"
+    connectorName: string = "Test File Connector",
+    accessType: "public" | "private" = "public"
   ): Promise<number> {
     const response = await this.post(
       "/manage/admin/connector-with-mock-credential",
@@ -240,7 +256,7 @@ export class OnyxApiClient {
         refresh_freq: null,
         prune_freq: null,
         indexing_start: null,
-        access_type: "public",
+        access_type: accessType,
         groups: [],
       }
     );
@@ -547,17 +563,20 @@ export class OnyxApiClient {
    * Creates a user group.
    *
    * @param groupName - Name for the user group
+   * @param userIds - Optional list of user IDs to add to the group
+   * @param ccPairIds - Optional list of connector-credential pair IDs to associate
    * @returns The user group ID
    * @throws Error if the user group creation fails
    */
   async createUserGroup(
     groupName: string,
-    userIds: string[] = []
+    userIds: string[] = [],
+    ccPairIds: number[] = []
   ): Promise<number> {
     const response = await this.post("/manage/admin/user-group", {
       name: groupName,
       user_ids: userIds,
-      cc_pair_ids: [],
+      cc_pair_ids: ccPairIds,
     });
 
     const responseData = await this.handleResponse<{ id: number }>(

From 5322aeed90f59bd0eb723fb26c35e80fe13e9805 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 4 Mar 2026 12:51:05 -0800
Subject: [PATCH 083/267] chore(deps): bump hono from 4.11.7 to 4.12.5 in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#9044)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../docker/templates/outputs/web/package-lock.json          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index 1cbc5a3a508..b6591c03116 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -7424,9 +7424,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.11.7",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.11.7.tgz",
-      "integrity": "sha512-l7qMiNee7t82bH3SeyUCt9UF15EVmaBvsppY2zQtrbIhl/yzBTny+YUxsVjSjQ6gaqaeVtZmGocom8TzBlA4Yw==",
+      "version": "4.12.5",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.5.tgz",
+      "integrity": "sha512-3qq+FUBtlTHhtYxbxheZgY8NIFnkkC/MR8u5TTsr7YZ3wixryQ3cCwn3iZbg8p8B88iDBBAYSfZDS75t8MN7Vg==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"

From f1cf3c4589db0e74bad7f0f7cc3f6be224057429 Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Thu, 5 Mar 2026 02:36:53 +0530
Subject: [PATCH 084/267] feat(table): add table primitive components and
 styles (#9017)

---
 web/lib/opal/src/icons/column.tsx             |  22 ++
 web/lib/opal/src/icons/handle.tsx             |  20 ++
 web/lib/opal/src/icons/index.ts               |   4 +
 web/lib/opal/src/icons/sort-order.tsx         |  21 ++
 web/lib/opal/src/icons/sort.tsx               |  27 ++
 web/src/app/css/table.css                     | 143 ++++++++++
 web/src/app/globals.css                       |   1 +
 web/src/refresh-components/Divider.tsx        |  11 +-
 .../table/ActionsContainer.tsx                |  33 +++
 .../table/DragOverlayRow.tsx                  |  36 +++
 .../table/QualifierContainer.tsx              |  33 +++
 web/src/refresh-components/table/Table.tsx    |  26 ++
 .../refresh-components/table/TableBody.tsx    |  85 ++++++
 .../refresh-components/table/TableCell.tsx    |  39 +++
 .../refresh-components/table/TableHead.tsx    | 148 ++++++++++
 .../refresh-components/table/TableHeader.tsx  |  13 +
 .../table/TableQualifier.tsx                  | 178 ++++++++++++
 web/src/refresh-components/table/TableRow.tsx | 150 +++++++++++
 .../table/TableSizeContext.tsx                |  27 ++
 web/src/refresh-components/table/columns.ts   | 253 ++++++++++++++++++
 web/src/refresh-components/table/types.ts     | 162 +++++++++++
 21 files changed, 1426 insertions(+), 6 deletions(-)
 create mode 100644 web/lib/opal/src/icons/column.tsx
 create mode 100644 web/lib/opal/src/icons/handle.tsx
 create mode 100644 web/lib/opal/src/icons/sort-order.tsx
 create mode 100644 web/lib/opal/src/icons/sort.tsx
 create mode 100644 web/src/app/css/table.css
 create mode 100644 web/src/refresh-components/table/ActionsContainer.tsx
 create mode 100644 web/src/refresh-components/table/DragOverlayRow.tsx
 create mode 100644 web/src/refresh-components/table/QualifierContainer.tsx
 create mode 100644 web/src/refresh-components/table/Table.tsx
 create mode 100644 web/src/refresh-components/table/TableBody.tsx
 create mode 100644 web/src/refresh-components/table/TableCell.tsx
 create mode 100644 web/src/refresh-components/table/TableHead.tsx
 create mode 100644 web/src/refresh-components/table/TableHeader.tsx
 create mode 100644 web/src/refresh-components/table/TableQualifier.tsx
 create mode 100644 web/src/refresh-components/table/TableRow.tsx
 create mode 100644 web/src/refresh-components/table/TableSizeContext.tsx
 create mode 100644 web/src/refresh-components/table/columns.ts
 create mode 100644 web/src/refresh-components/table/types.ts

diff --git a/web/lib/opal/src/icons/column.tsx b/web/lib/opal/src/icons/column.tsx
new file mode 100644
index 00000000000..ef8a8f1bd9d
--- /dev/null
+++ b/web/lib/opal/src/icons/column.tsx
@@ -0,0 +1,22 @@
+import type { IconProps } from "@opal/types";
+
+const SvgColumn = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M6 14H3.33333C2.59695 14 2 13.403 2 12.6667V3.33333C2 2.59695 2.59695 2 3.33333 2H6M6 14V2M6 14H10M6 2H10M10 2H12.6667C13.403 2 14 2.59695 14 3.33333V12.6667C14 13.403 13.403 14 12.6667 14H10M10 2V14"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+export default SvgColumn;
diff --git a/web/lib/opal/src/icons/handle.tsx b/web/lib/opal/src/icons/handle.tsx
new file mode 100644
index 00000000000..c74fccf138c
--- /dev/null
+++ b/web/lib/opal/src/icons/handle.tsx
@@ -0,0 +1,20 @@
+import type { IconProps } from "@opal/types";
+
+const SvgHandle = ({ size = 16, ...props }: IconProps) => (
+  <svg
+    width={Math.round((size * 3) / 17)}
+    height={size}
+    viewBox="0 0 3 17"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M0.5 0.5V16.5M2.5 0.5V16.5"
+      stroke="currentColor"
+      strokeLinecap="round"
+    />
+  </svg>
+);
+
+export default SvgHandle;
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index 9ed6903bf6c..c954d8e1acf 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -49,6 +49,7 @@ export { default as SvgClock } from "@opal/icons/clock";
 export { default as SvgClockHandsSmall } from "@opal/icons/clock-hands-small";
 export { default as SvgCloud } from "@opal/icons/cloud";
 export { default as SvgCode } from "@opal/icons/code";
+export { default as SvgColumn } from "@opal/icons/column";
 export { default as SvgCopy } from "@opal/icons/copy";
 export { default as SvgCornerRightUpDot } from "@opal/icons/corner-right-up-dot";
 export { default as SvgCpu } from "@opal/icons/cpu";
@@ -79,6 +80,7 @@ export { default as SvgFolderPartialOpen } from "@opal/icons/folder-partial-open
 export { default as SvgFolderPlus } from "@opal/icons/folder-plus";
 export { default as SvgGemini } from "@opal/icons/gemini";
 export { default as SvgGlobe } from "@opal/icons/globe";
+export { default as SvgHandle } from "@opal/icons/handle";
 export { default as SvgHardDrive } from "@opal/icons/hard-drive";
 export { default as SvgHashSmall } from "@opal/icons/hash-small";
 export { default as SvgHash } from "@opal/icons/hash";
@@ -146,6 +148,8 @@ export { default as SvgSlack } from "@opal/icons/slack";
 export { default as SvgSlash } from "@opal/icons/slash";
 export { default as SvgSliders } from "@opal/icons/sliders";
 export { default as SvgSlidersSmall } from "@opal/icons/sliders-small";
+export { default as SvgSort } from "@opal/icons/sort";
+export { default as SvgSortOrder } from "@opal/icons/sort-order";
 export { default as SvgSparkle } from "@opal/icons/sparkle";
 export { default as SvgStar } from "@opal/icons/star";
 export { default as SvgStep1 } from "@opal/icons/step1";
diff --git a/web/lib/opal/src/icons/sort-order.tsx b/web/lib/opal/src/icons/sort-order.tsx
new file mode 100644
index 00000000000..8fce7992d7e
--- /dev/null
+++ b/web/lib/opal/src/icons/sort-order.tsx
@@ -0,0 +1,21 @@
+import type { IconProps } from "@opal/types";
+
+const SvgSortOrder = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M2.66675 12L7.67009 12.0001M2.66675 8H10.5001M2.66675 4H13.3334"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgSortOrder;
diff --git a/web/lib/opal/src/icons/sort.tsx b/web/lib/opal/src/icons/sort.tsx
new file mode 100644
index 00000000000..5dd28299503
--- /dev/null
+++ b/web/lib/opal/src/icons/sort.tsx
@@ -0,0 +1,27 @@
+import type { IconProps } from "@opal/types";
+
+const SvgSort = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M2 4.5H10M2 8H7M2 11.5H5"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M12 5V12M12 12L14 10M12 12L10 10"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgSort;
diff --git a/web/src/app/css/table.css b/web/src/app/css/table.css
new file mode 100644
index 00000000000..202c81bdd62
--- /dev/null
+++ b/web/src/app/css/table.css
@@ -0,0 +1,143 @@
+/* ---------------------------------------------------------------------------
+ * Table primitives — data-attribute driven styling
+ * Follows the same pattern as card.css / line-item.css.
+ * ------------------------------------------------------------------------- */
+
+/* ---- TableCell ---- */
+
+.tbl-cell[data-size="regular"] {
+  @apply px-1 py-0.5;
+}
+.tbl-cell[data-size="small"] {
+  @apply pl-0.5 pr-1.5 py-1.5;
+}
+
+.tbl-cell-inner[data-size="regular"] {
+  @apply h-10 px-1;
+}
+.tbl-cell-inner[data-size="small"] {
+  @apply h-6 px-0.5;
+}
+
+/* ---- TableHead ---- */
+
+.table-head {
+  @apply relative sticky top-0 z-20;
+  background: var(--table-header-bg, transparent);
+}
+.table-head[data-size="regular"] {
+  @apply px-2 py-1;
+}
+.table-head[data-size="small"] {
+  @apply p-1.5;
+}
+.table-head[data-bottom-border] {
+  @apply border-b border-transparent hover:border-border-03;
+}
+
+/* Inner text wrapper */
+.table-head[data-size="regular"] .table-head-label {
+  @apply py-2 px-0.5;
+}
+.table-head[data-size="small"] .table-head-label {
+  @apply py-1;
+}
+
+/* Sort button wrapper */
+.table-head[data-size="regular"] .table-head-sort {
+  @apply py-1.5;
+}
+
+/* ---- TableRow ---- */
+
+.tbl-row > td {
+  @apply bg-background-tint-00;
+}
+
+.tbl-row[data-variant="table"] > td {
+  @apply border-b border-border-01;
+}
+
+.tbl-row[data-variant="list"] > td {
+  @apply bg-clip-padding border-y-[4px] border-x-0 border-transparent;
+}
+.tbl-row[data-variant="list"] > td:first-child {
+  @apply rounded-l-12;
+}
+.tbl-row[data-variant="list"] > td:last-child {
+  @apply rounded-r-12;
+}
+
+/* When a drag handle is present the second-to-last td gets the rounding */
+.tbl-row[data-variant="list"][data-drag-handle] > td:nth-last-child(2) {
+  @apply rounded-r-12;
+}
+.tbl-row[data-variant="list"][data-drag-handle] > td:last-child {
+  border-radius: 0;
+}
+
+/* ---- Row states (list variant) ---- */
+
+.tbl-row[data-variant="list"]:hover > td {
+  @apply bg-background-tint-02;
+}
+.tbl-row[data-variant="list"]:focus-visible > td,
+.tbl-row[data-variant="list"]:has(:focus-visible) > td {
+  @apply bg-action-link-01;
+}
+
+.tbl-row[data-disabled] {
+  @apply pointer-events-none;
+}
+
+/* ---- Row states (table variant) ---- */
+
+.tbl-row[data-variant="table"]:hover > td {
+  @apply bg-background-tint-02;
+}
+.tbl-row[data-variant="table"]:focus-visible > td,
+.tbl-row[data-variant="table"]:has(:focus-visible) > td {
+  @apply bg-action-link-01;
+}
+
+/* Suppress default focus ring on rows — the row bg is the indicator */
+.tbl-row:focus,
+.tbl-row:focus-visible {
+  outline: none;
+}
+
+/* ---- QualifierContainer ---- */
+
+.tbl-qualifier[data-type="head"] {
+  @apply w-px whitespace-nowrap py-1 sticky top-0 z-20;
+  background: var(--table-header-bg, transparent);
+}
+.tbl-qualifier[data-type="head"][data-size="small"] {
+  @apply py-0.5;
+}
+
+.tbl-qualifier[data-type="cell"] {
+  @apply w-px whitespace-nowrap py-1 pl-1;
+}
+.tbl-qualifier[data-type="cell"][data-size="small"] {
+  @apply py-0.5 pl-0.5;
+}
+
+/* ---- ActionsContainer ---- */
+
+.tbl-actions {
+  @apply sticky right-0 w-px whitespace-nowrap;
+}
+.tbl-actions[data-type="head"] {
+  @apply z-30 sticky top-0;
+  background: var(--table-header-bg, transparent);
+}
+
+/* ---- Footer ---- */
+
+.table-footer[data-size="regular"] {
+  @apply min-h-[2.75rem];
+}
+.table-footer[data-size="small"] {
+  @apply min-h-[2.25rem];
+}
diff --git a/web/src/app/globals.css b/web/src/app/globals.css
index 561e10f6f17..7c684a4dead 100644
--- a/web/src/app/globals.css
+++ b/web/src/app/globals.css
@@ -16,6 +16,7 @@
 @import "css/sizes.css";
 @import "css/square-button.css";
 @import "css/switch.css";
+@import "css/table.css";
 @import "css/z-index.css";
 
 /* KH Teka Font */
diff --git a/web/src/refresh-components/Divider.tsx b/web/src/refresh-components/Divider.tsx
index 1b6a07e154c..3091f8fd5ac 100644
--- a/web/src/refresh-components/Divider.tsx
+++ b/web/src/refresh-components/Divider.tsx
@@ -140,14 +140,13 @@ export default function Divider({
       <div
         className={cn(
           "flex items-center py-1",
-          !dividerLine && (foldable ? "pl-1.5" : "px-2")
+          !dividerLine && (foldable ? "pl-1.5" : "px-2"),
+          dividerLine && !foldable && "pl-1.5"
         )}
       >
-        {/* Left divider line */}
-        {dividerLine && (
-          <div
-            className={cn("h-px bg-border-01", foldable ? "w-1.5" : "w-2")}
-          />
+        {/* Left divider line (only for foldable dividers) */}
+        {dividerLine && foldable && (
+          <div className={cn("h-px bg-border-01 w-1.5")} />
         )}
 
         {/* Content container */}
diff --git a/web/src/refresh-components/table/ActionsContainer.tsx b/web/src/refresh-components/table/ActionsContainer.tsx
new file mode 100644
index 00000000000..5fa7b31c15e
--- /dev/null
+++ b/web/src/refresh-components/table/ActionsContainer.tsx
@@ -0,0 +1,33 @@
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+
+interface ActionsContainerProps {
+  type: "head" | "cell";
+  children: React.ReactNode;
+  size?: TableSize;
+  /** Pass-through click handler (e.g. stopPropagation on body cells). */
+  onClick?: (e: React.MouseEvent) => void;
+}
+
+export default function ActionsContainer({
+  type,
+  children,
+  size,
+  onClick,
+}: ActionsContainerProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = size ?? contextSize;
+
+  const Tag = type === "head" ? "th" : "td";
+
+  return (
+    <Tag
+      className="tbl-actions"
+      data-type={type}
+      data-size={resolvedSize}
+      onClick={onClick}
+    >
+      <div className="flex h-full items-center justify-center">{children}</div>
+    </Tag>
+  );
+}
diff --git a/web/src/refresh-components/table/DragOverlayRow.tsx b/web/src/refresh-components/table/DragOverlayRow.tsx
new file mode 100644
index 00000000000..437f12669b7
--- /dev/null
+++ b/web/src/refresh-components/table/DragOverlayRow.tsx
@@ -0,0 +1,36 @@
+import { memo } from "react";
+import { type Row, flexRender } from "@tanstack/react-table";
+import TableRow from "@/refresh-components/table/TableRow";
+import TableCell from "@/refresh-components/table/TableCell";
+
+interface DragOverlayRowProps<TData> {
+  row: Row<TData>;
+  variant?: "table" | "list";
+}
+
+function DragOverlayRowInner<TData>({
+  row,
+  variant,
+}: DragOverlayRowProps<TData>) {
+  return (
+    <table
+      className="min-w-full border-collapse"
+      style={{ tableLayout: "fixed" }}
+    >
+      <tbody>
+        <TableRow variant={variant} selected={row.getIsSelected()}>
+          {row.getVisibleCells().map((cell) => (
+            <TableCell key={cell.id} width={cell.column.getSize()}>
+              {flexRender(cell.column.columnDef.cell, cell.getContext())}
+            </TableCell>
+          ))}
+        </TableRow>
+      </tbody>
+    </table>
+  );
+}
+
+const DragOverlayRow = memo(DragOverlayRowInner) as typeof DragOverlayRowInner;
+
+export default DragOverlayRow;
+export type { DragOverlayRowProps };
diff --git a/web/src/refresh-components/table/QualifierContainer.tsx b/web/src/refresh-components/table/QualifierContainer.tsx
new file mode 100644
index 00000000000..66425cc2c7f
--- /dev/null
+++ b/web/src/refresh-components/table/QualifierContainer.tsx
@@ -0,0 +1,33 @@
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+
+interface QualifierContainerProps {
+  type: "head" | "cell";
+  children?: React.ReactNode;
+  size?: TableSize;
+  /** Pass-through click handler (e.g. stopPropagation on body cells). */
+  onClick?: (e: React.MouseEvent) => void;
+}
+
+export default function QualifierContainer({
+  type,
+  children,
+  size,
+  onClick,
+}: QualifierContainerProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = size ?? contextSize;
+
+  const Tag = type === "head" ? "th" : "td";
+
+  return (
+    <Tag
+      className="tbl-qualifier"
+      data-type={type}
+      data-size={resolvedSize}
+      onClick={onClick}
+    >
+      <div className="flex h-full items-center justify-center">{children}</div>
+    </Tag>
+  );
+}
diff --git a/web/src/refresh-components/table/Table.tsx b/web/src/refresh-components/table/Table.tsx
new file mode 100644
index 00000000000..8727cde7898
--- /dev/null
+++ b/web/src/refresh-components/table/Table.tsx
@@ -0,0 +1,26 @@
+import { cn } from "@/lib/utils";
+import type { WithoutStyles } from "@/types";
+
+interface TableProps
+  extends WithoutStyles<React.TableHTMLAttributes<HTMLTableElement>> {
+  ref?: React.Ref<HTMLTableElement>;
+  /** Explicit pixel width for the table (e.g. from `table.getTotalSize()`).
+   *  When provided the table uses exactly this width instead of stretching
+   *  to fill its container, which prevents `table-layout: fixed` from
+   *  redistributing extra space across columns on resize. */
+  width?: number;
+}
+
+function Table({ ref, width, ...props }: TableProps) {
+  return (
+    <table
+      ref={ref}
+      className={cn("border-separate border-spacing-0", "min-w-full")}
+      style={{ tableLayout: "fixed", width: width ?? undefined }}
+      {...props}
+    />
+  );
+}
+
+export default Table;
+export type { TableProps };
diff --git a/web/src/refresh-components/table/TableBody.tsx b/web/src/refresh-components/table/TableBody.tsx
new file mode 100644
index 00000000000..ed20e1bb7fb
--- /dev/null
+++ b/web/src/refresh-components/table/TableBody.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import type { ReactNode } from "react";
+import {
+  DndContext,
+  DragOverlay,
+  type DragStartEvent,
+  type DragEndEvent,
+  type CollisionDetection,
+  type Modifier,
+  type SensorDescriptor,
+  type SensorOptions,
+} from "@dnd-kit/core";
+import {
+  SortableContext,
+  verticalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import type { WithoutStyles } from "@/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface DraggableProps {
+  dndContextProps: {
+    sensors: SensorDescriptor<SensorOptions>[];
+    collisionDetection: CollisionDetection;
+    modifiers: Modifier[];
+    onDragStart: (event: DragStartEvent) => void;
+    onDragEnd: (event: DragEndEvent) => void;
+    onDragCancel: () => void;
+  };
+  sortableItems: string[];
+  activeId: string | null;
+  isEnabled: boolean;
+}
+
+interface TableBodyProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLTableSectionElement>> {
+  ref?: React.Ref<HTMLTableSectionElement>;
+  /** DnD context props from useDraggableRows — enables drag-and-drop reordering */
+  dndSortable?: DraggableProps;
+  /** Render function for the drag overlay row */
+  renderDragOverlay?: (activeId: string) => ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+function TableBody({
+  ref,
+  dndSortable,
+  renderDragOverlay,
+  ...props
+}: TableBodyProps) {
+  if (dndSortable?.isEnabled) {
+    const { dndContextProps, sortableItems, activeId } = dndSortable;
+    return (
+      <DndContext
+        sensors={dndContextProps.sensors}
+        collisionDetection={dndContextProps.collisionDetection}
+        modifiers={dndContextProps.modifiers}
+        onDragStart={dndContextProps.onDragStart}
+        onDragEnd={dndContextProps.onDragEnd}
+        onDragCancel={dndContextProps.onDragCancel}
+      >
+        <SortableContext
+          items={sortableItems}
+          strategy={verticalListSortingStrategy}
+        >
+          <tbody ref={ref} {...props} />
+        </SortableContext>
+        <DragOverlay dropAnimation={null}>
+          {activeId && renderDragOverlay ? renderDragOverlay(activeId) : null}
+        </DragOverlay>
+      </DndContext>
+    );
+  }
+
+  return <tbody ref={ref} {...props} />;
+}
+
+export default TableBody;
+export type { TableBodyProps, DraggableProps };
diff --git a/web/src/refresh-components/table/TableCell.tsx b/web/src/refresh-components/table/TableCell.tsx
new file mode 100644
index 00000000000..dbeb95c6e4a
--- /dev/null
+++ b/web/src/refresh-components/table/TableCell.tsx
@@ -0,0 +1,39 @@
+import { cn } from "@/lib/utils";
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { WithoutStyles } from "@/types";
+
+interface TableCellProps
+  extends WithoutStyles<React.TdHTMLAttributes<HTMLTableCellElement>> {
+  children: React.ReactNode;
+  size?: TableSize;
+  /** Explicit pixel width for the cell. */
+  width?: number;
+}
+
+export default function TableCell({
+  size,
+  width,
+  children,
+  ...props
+}: TableCellProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = size ?? contextSize;
+  return (
+    <td
+      className="tbl-cell"
+      data-size={resolvedSize}
+      style={width != null ? { width } : undefined}
+      {...props}
+    >
+      <div
+        className={cn("tbl-cell-inner", "flex items-center")}
+        data-size={resolvedSize}
+      >
+        {children}
+      </div>
+    </td>
+  );
+}
+
+export type { TableCellProps };
diff --git a/web/src/refresh-components/table/TableHead.tsx b/web/src/refresh-components/table/TableHead.tsx
new file mode 100644
index 00000000000..9c3cdac67ee
--- /dev/null
+++ b/web/src/refresh-components/table/TableHead.tsx
@@ -0,0 +1,148 @@
+import { cn } from "@/lib/utils";
+import Text from "@/refresh-components/texts/Text";
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { WithoutStyles } from "@/types";
+import { Button } from "@opal/components";
+import { SvgChevronDown, SvgChevronUp, SvgHandle, SvgSort } from "@opal/icons";
+import type { IconFunctionComponent } from "@opal/types";
+
+export type SortDirection = "none" | "ascending" | "descending";
+
+/**
+ * A table header cell with optional sort controls and a resize handle indicator.
+ * Renders as a `<th>` element with Figma-matched typography and spacing.
+ */
+interface TableHeadCustomProps {
+  /** Header label content. */
+  children: React.ReactNode;
+  /** Current sort state. When omitted, no sort button is shown. */
+  sorted?: SortDirection;
+  /** Called when the sort button is clicked. Required to show the sort button. */
+  onSort?: () => void;
+  /** When `true`, renders a thin resize handle on the right edge. */
+  resizable?: boolean;
+  /** Called when a resize drag begins on the handle. Attach TanStack's
+   *  `header.getResizeHandler()` here to enable column resizing. */
+  onResizeStart?: (event: React.MouseEvent | React.TouchEvent) => void;
+  /** Override the sort icon for this column. Receives the current sort state and
+   *  returns the icon component to render. Falls back to the built-in icons. */
+  icon?: (sorted: SortDirection) => IconFunctionComponent;
+  /** Text alignment for the column. Defaults to `"left"`. */
+  alignment?: "left" | "center" | "right";
+  /** Cell density. `"small"` uses tighter padding for denser layouts. */
+  size?: TableSize;
+  /** Column width in pixels. Applied as an inline style on the `<th>`. */
+  width?: number;
+  /** When `true`, shows a bottom border on hover. Defaults to `true`. */
+  bottomBorder?: boolean;
+}
+
+type TableHeadProps = WithoutStyles<
+  TableHeadCustomProps &
+    Omit<
+      React.ThHTMLAttributes<HTMLTableCellElement>,
+      keyof TableHeadCustomProps
+    >
+>;
+
+/**
+ * Table header cell primitive. Displays a column label with optional sort
+ * functionality and a resize handle indicator.
+ */
+function defaultSortIcon(sorted: SortDirection): IconFunctionComponent {
+  switch (sorted) {
+    case "ascending":
+      return SvgChevronUp;
+    case "descending":
+      return SvgChevronDown;
+    default:
+      return SvgSort;
+  }
+}
+
+const alignmentThClass = {
+  left: "text-left",
+  center: "text-center",
+  right: "text-right",
+} as const;
+
+const alignmentFlexClass = {
+  left: "justify-start",
+  center: "justify-center",
+  right: "justify-end",
+} as const;
+
+export default function TableHead({
+  children,
+  sorted,
+  onSort,
+  icon: iconFn = defaultSortIcon,
+  resizable,
+  onResizeStart,
+  alignment = "left",
+  size,
+  width,
+  bottomBorder = true,
+  ...thProps
+}: TableHeadProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = size ?? contextSize;
+  const isSmall = resolvedSize === "small";
+  return (
+    <th
+      {...thProps}
+      style={width != null ? { width } : undefined}
+      className={cn("table-head group", alignmentThClass[alignment])}
+      data-size={resolvedSize}
+      data-bottom-border={bottomBorder || undefined}
+    >
+      <div
+        className={cn("flex items-center gap-1", alignmentFlexClass[alignment])}
+      >
+        <div className="table-head-label">
+          <Text
+            mainUiAction={!isSmall}
+            secondaryAction={isSmall}
+            text04
+            className="truncate"
+          >
+            {children}
+          </Text>
+        </div>
+        <div
+          className={cn(
+            "table-head-sort",
+            "opacity-0 group-hover:opacity-100 transition-opacity"
+          )}
+        >
+          {onSort && (
+            <Button
+              icon={iconFn(sorted ?? "none")}
+              onClick={onSort}
+              tooltip="Sort"
+              tooltipSide="top"
+              prominence="internal"
+              size="sm"
+            />
+          )}
+        </div>
+      </div>
+      {resizable && (
+        <div
+          onMouseDown={onResizeStart}
+          onTouchStart={onResizeStart}
+          className={cn(
+            "absolute right-0 top-0 flex h-full items-center",
+            "text-border-02",
+            "opacity-0 group-hover:opacity-100",
+            "cursor-col-resize",
+            "select-none touch-none"
+          )}
+        >
+          <SvgHandle size={22} className="stroke-border-02" />
+        </div>
+      )}
+    </th>
+  );
+}
diff --git a/web/src/refresh-components/table/TableHeader.tsx b/web/src/refresh-components/table/TableHeader.tsx
new file mode 100644
index 00000000000..c405453aec8
--- /dev/null
+++ b/web/src/refresh-components/table/TableHeader.tsx
@@ -0,0 +1,13 @@
+import type { WithoutStyles } from "@/types";
+
+interface TableHeaderProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLTableSectionElement>> {
+  ref?: React.Ref<HTMLTableSectionElement>;
+}
+
+function TableHeader({ ref, ...props }: TableHeaderProps) {
+  return <thead ref={ref} {...props} />;
+}
+
+export default TableHeader;
+export type { TableHeaderProps };
diff --git a/web/src/refresh-components/table/TableQualifier.tsx b/web/src/refresh-components/table/TableQualifier.tsx
new file mode 100644
index 00000000000..047602654c4
--- /dev/null
+++ b/web/src/refresh-components/table/TableQualifier.tsx
@@ -0,0 +1,178 @@
+"use client";
+
+import React from "react";
+import { cn } from "@/lib/utils";
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { SvgUser } from "@opal/icons";
+import type { IconFunctionComponent } from "@opal/types";
+import type { QualifierContentType } from "@/refresh-components/table/types";
+import Checkbox from "@/refresh-components/inputs/Checkbox";
+import Text from "@/refresh-components/texts/Text";
+
+interface TableQualifierProps {
+  className?: string;
+  /** Content type displayed in the qualifier */
+  content: QualifierContentType;
+  /** Size variant */
+  size?: TableSize;
+  /** Disables interaction */
+  disabled?: boolean;
+  /** Whether to show a selection checkbox overlay */
+  selectable?: boolean;
+  /** Whether the row is currently selected */
+  selected?: boolean;
+  /** Called when the checkbox is toggled */
+  onSelectChange?: (selected: boolean) => void;
+  /** Icon component to render (for "icon" content type) */
+  icon?: IconFunctionComponent;
+  /** Image source URL (for "image" content type) */
+  imageSrc?: string;
+  /** Image alt text */
+  imageAlt?: string;
+  /** User initials (for "avatar-user" content type) */
+  initials?: string;
+}
+
+const iconSizes = {
+  regular: 16,
+  small: 14,
+} as const;
+
+function getQualifierStyles(selected: boolean, disabled: boolean) {
+  if (disabled) {
+    return {
+      container: "bg-background-neutral-03",
+      icon: "stroke-text-02",
+      overlay: selected ? "flex bg-action-link-00" : "hidden",
+      overlayImage: selected ? "flex bg-mask-01 backdrop-blur-02" : "hidden",
+    };
+  }
+
+  if (selected) {
+    return {
+      container: "bg-action-link-00",
+      icon: "stroke-text-03",
+      overlay: "flex bg-action-link-00",
+      overlayImage: "flex bg-mask-01 backdrop-blur-02",
+    };
+  }
+
+  return {
+    container: "bg-background-tint-01",
+    icon: "stroke-text-03",
+    overlay:
+      "flex opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 bg-background-tint-01",
+    overlayImage:
+      "flex opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 bg-mask-01 group-hover:backdrop-blur-02 group-focus-within:backdrop-blur-02",
+  };
+}
+
+function TableQualifier({
+  className,
+  content,
+  size,
+  disabled = false,
+  selectable = false,
+  selected = false,
+  onSelectChange,
+  icon: Icon,
+  imageSrc,
+  imageAlt = "",
+  initials,
+}: TableQualifierProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = size ?? contextSize;
+  const isRound = content === "avatar-icon" || content === "avatar-user";
+  const iconSize = iconSizes[resolvedSize];
+  const styles = getQualifierStyles(selected, disabled);
+
+  function renderContent() {
+    switch (content) {
+      case "icon":
+        return Icon ? <Icon size={iconSize} className={styles.icon} /> : null;
+
+      case "simple":
+        return null;
+
+      case "image":
+        return imageSrc ? (
+          <img
+            src={imageSrc}
+            alt={imageAlt}
+            className={cn(
+              "h-full w-full object-cover",
+              isRound ? "rounded-full" : "rounded-08"
+            )}
+          />
+        ) : null;
+
+      case "avatar-icon":
+        return <SvgUser size={iconSize} className={styles.icon} />;
+
+      case "avatar-user":
+        return (
+          <div
+            className={cn(
+              "flex items-center justify-center rounded-full bg-text-05",
+              resolvedSize === "regular" ? "h-7 w-7" : "h-6 w-6"
+            )}
+          >
+            <Text secondaryAction textLight05 className="select-none uppercase">
+              {initials}
+            </Text>
+          </div>
+        );
+
+      default:
+        return null;
+    }
+  }
+
+  return (
+    <div
+      className={cn(
+        "group relative inline-flex shrink-0 items-center justify-center",
+        resolvedSize === "regular" ? "h-9 w-9" : "h-7 w-7",
+        disabled ? "cursor-not-allowed" : "cursor-default",
+        className
+      )}
+    >
+      {/* Inner qualifier container */}
+      <div
+        className={cn(
+          "flex items-center justify-center overflow-hidden transition-colors",
+          resolvedSize === "regular" ? "h-9 w-9" : "h-7 w-7",
+          isRound ? "rounded-full" : "rounded-08",
+          styles.container,
+          content === "image" && disabled && !selected && "opacity-50"
+        )}
+      >
+        {renderContent()}
+      </div>
+
+      {/* Selection overlay */}
+      {selectable && (
+        <div
+          className={cn(
+            "absolute inset-0 items-center justify-center",
+            isRound ? "rounded-full" : "rounded-08",
+            content === "simple"
+              ? "flex"
+              : content === "image"
+                ? styles.overlayImage
+                : styles.overlay
+          )}
+        >
+          <Checkbox
+            checked={selected}
+            onCheckedChange={onSelectChange}
+            disabled={disabled}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default TableQualifier;
diff --git a/web/src/refresh-components/table/TableRow.tsx b/web/src/refresh-components/table/TableRow.tsx
new file mode 100644
index 00000000000..46e259e7708
--- /dev/null
+++ b/web/src/refresh-components/table/TableRow.tsx
@@ -0,0 +1,150 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { WithoutStyles } from "@/types";
+import { useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { SvgHandle } from "@opal/icons";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface TableRowProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLTableRowElement>> {
+  ref?: React.Ref<HTMLTableRowElement>;
+  selected?: boolean;
+  /** Disables interaction and applies disabled styling */
+  disabled?: boolean;
+  /** Visual variant: "table" adds a bottom border, "list" adds rounded corners. Defaults to "list". */
+  variant?: "table" | "list";
+  /** When provided, makes this row sortable via @dnd-kit */
+  sortableId?: string;
+  /** Show drag handle overlay. Defaults to true when sortableId is set. */
+  showDragHandle?: boolean;
+  /** Size variant for the drag handle */
+  size?: TableSize;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: sortable row
+// ---------------------------------------------------------------------------
+
+function SortableTableRow({
+  sortableId,
+  showDragHandle = true,
+  size,
+  variant = "list",
+  selected,
+  disabled,
+  ref: _externalRef,
+  children,
+  ...props
+}: TableRowProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = size ?? contextSize;
+
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: sortableId! });
+
+  const style: React.CSSProperties = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    opacity: isDragging ? 0 : undefined,
+  };
+
+  return (
+    <tr
+      ref={setNodeRef}
+      style={style}
+      className="tbl-row group/row"
+      data-variant={variant}
+      data-drag-handle={showDragHandle || undefined}
+      data-selected={selected || undefined}
+      data-disabled={disabled || undefined}
+      {...attributes}
+      {...props}
+    >
+      {children}
+      {showDragHandle && (
+        <td
+          style={{
+            width: 0,
+            padding: 0,
+            position: "relative",
+            zIndex: 20,
+          }}
+        >
+          <button
+            type="button"
+            className={cn(
+              "absolute right-0 top-1/2 -translate-y-1/2 cursor-grab",
+              "opacity-0 group-hover/row:opacity-100 transition-opacity",
+              "flex items-center justify-center rounded"
+            )}
+            aria-label="Drag to reorder"
+            onMouseDown={(e) => e.preventDefault()}
+            {...listeners}
+          >
+            <SvgHandle
+              size={resolvedSize === "small" ? 12 : 16}
+              className="text-border-02"
+            />
+          </button>
+        </td>
+      )}
+    </tr>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+function TableRow({
+  sortableId,
+  showDragHandle,
+  size,
+  variant = "list",
+  selected,
+  disabled,
+  ref,
+  ...props
+}: TableRowProps) {
+  if (sortableId) {
+    return (
+      <SortableTableRow
+        sortableId={sortableId}
+        showDragHandle={showDragHandle}
+        size={size}
+        variant={variant}
+        selected={selected}
+        disabled={disabled}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+
+  return (
+    <tr
+      ref={ref}
+      className="tbl-row group/row"
+      data-variant={variant}
+      data-selected={selected || undefined}
+      data-disabled={disabled || undefined}
+      {...props}
+    />
+  );
+}
+
+export default TableRow;
+export type { TableRowProps };
diff --git a/web/src/refresh-components/table/TableSizeContext.tsx b/web/src/refresh-components/table/TableSizeContext.tsx
new file mode 100644
index 00000000000..bf3f6c1ec67
--- /dev/null
+++ b/web/src/refresh-components/table/TableSizeContext.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+type TableSize = "regular" | "small";
+
+const TableSizeContext = createContext<TableSize>("regular");
+
+interface TableSizeProviderProps {
+  size: TableSize;
+  children: React.ReactNode;
+}
+
+function TableSizeProvider({ size, children }: TableSizeProviderProps) {
+  return (
+    <TableSizeContext.Provider value={size}>
+      {children}
+    </TableSizeContext.Provider>
+  );
+}
+
+function useTableSize(): TableSize {
+  return useContext(TableSizeContext);
+}
+
+export { TableSizeProvider, useTableSize };
+export type { TableSize };
diff --git a/web/src/refresh-components/table/columns.ts b/web/src/refresh-components/table/columns.ts
new file mode 100644
index 00000000000..45979949840
--- /dev/null
+++ b/web/src/refresh-components/table/columns.ts
@@ -0,0 +1,253 @@
+import type { ReactNode } from "react";
+import {
+  createColumnHelper,
+  type ColumnDef,
+  type DeepKeys,
+  type DeepValue,
+  type CellContext,
+} from "@tanstack/react-table";
+import type {
+  ColumnWidth,
+  QualifierContentType,
+  OnyxQualifierColumn,
+  OnyxDataColumn,
+  OnyxDisplayColumn,
+  OnyxActionsColumn,
+  OnyxColumnDef,
+} from "@/refresh-components/table/types";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { IconFunctionComponent } from "@opal/types";
+import type { SortDirection } from "@/refresh-components/table/TableHead";
+
+// ---------------------------------------------------------------------------
+// Qualifier column config
+// ---------------------------------------------------------------------------
+
+interface QualifierConfig<TData> {
+  /** Content type for body-row `<TableQualifier>`. @default "simple" */
+  content?: QualifierContentType;
+  /** Content type for the header `<TableQualifier>`. @default "simple" */
+  headerContentType?: QualifierContentType;
+  /** Extract initials from a row (for "avatar-user" content). */
+  getInitials?: (row: TData) => string;
+  /** Extract icon from a row (for "icon" / "avatar-icon" content). */
+  getIcon?: (row: TData) => IconFunctionComponent;
+  /** Extract image src from a row (for "image" content). */
+  getImageSrc?: (row: TData) => string;
+  /** Whether to show selection checkboxes on the qualifier. @default true */
+  selectable?: boolean;
+  /** Whether to render qualifier content in the header. @default true */
+  header?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Data column config
+// ---------------------------------------------------------------------------
+
+interface DataColumnConfig<TData, TValue> {
+  /** Column header label. */
+  header: string;
+  /** Custom cell renderer. If omitted, the value is rendered as a string. */
+  cell?: (value: TValue, row: TData) => ReactNode;
+  /** Enable sorting for this column. @default true */
+  enableSorting?: boolean;
+  /** Enable resizing for this column. @default true */
+  enableResizing?: boolean;
+  /** Enable hiding for this column. @default true */
+  enableHiding?: boolean;
+  /** Override the sort icon for this column. */
+  icon?: (sorted: SortDirection) => IconFunctionComponent;
+  /** Column weight for proportional distribution. @default 20 */
+  weight?: number;
+  /** Minimum column width in pixels. @default 50 */
+  minWidth?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Display column config
+// ---------------------------------------------------------------------------
+
+interface DisplayColumnConfig<TData> {
+  /** Unique column ID. */
+  id: string;
+  /** Column header label. */
+  header?: string;
+  /** Cell renderer. */
+  cell: (row: TData) => ReactNode;
+  /** Column width config. */
+  width: ColumnWidth;
+  /** Enable hiding. @default true */
+  enableHiding?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Actions column config
+// ---------------------------------------------------------------------------
+
+interface ActionsConfig {
+  /** Show column visibility popover. @default true */
+  showColumnVisibility?: boolean;
+  /** Show sorting popover. @default true */
+  showSorting?: boolean;
+  /** Footer text for the sorting popover. */
+  sortingFooterText?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Builder return type
+// ---------------------------------------------------------------------------
+
+interface TableColumnsBuilder<TData> {
+  /** Create a qualifier (leading avatar/checkbox) column. */
+  qualifier(config?: QualifierConfig<TData>): OnyxQualifierColumn<TData>;
+
+  /** Create a data (accessor) column. */
+  column<TKey extends DeepKeys<TData>>(
+    accessor: TKey,
+    config: DataColumnConfig<TData, DeepValue<TData, TKey>>
+  ): OnyxDataColumn<TData>;
+
+  /** Create a display (non-accessor) column. */
+  displayColumn(config: DisplayColumnConfig<TData>): OnyxDisplayColumn<TData>;
+
+  /** Create an actions column (visibility/sorting popovers). */
+  actions(config?: ActionsConfig): OnyxActionsColumn<TData>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a typed column builder for a given row type.
+ *
+ * Internally uses TanStack's `createColumnHelper<TData>()` to get free
+ * `DeepKeys`/`DeepValue` inference for accessor columns.
+ *
+ * **Important**: Define columns at module scope or wrap in `useMemo` to avoid
+ * creating new array references per render.
+ *
+ * @example
+ * ```ts
+ * const tc = createTableColumns<TeamMember>();
+ * const columns = [
+ *   tc.qualifier({ content: "avatar-user", getInitials: (r) => r.initials }),
+ *   tc.column("name", { header: "Name", weight: 23, minWidth: 120 }),
+ *   tc.column("email", { header: "Email", weight: 28, minWidth: 150 }),
+ *   tc.actions(),
+ * ];
+ * ```
+ */
+export function createTableColumns<TData>(): TableColumnsBuilder<TData> {
+  const helper = createColumnHelper<TData>();
+
+  return {
+    qualifier(config?: QualifierConfig<TData>): OnyxQualifierColumn<TData> {
+      const content = config?.content ?? "simple";
+
+      const def: ColumnDef<TData, any> = helper.display({
+        id: "qualifier",
+        enableResizing: false,
+        enableSorting: false,
+        enableHiding: false,
+        // Cell rendering is handled by DataTable based on the qualifier config
+        cell: () => null,
+      });
+
+      return {
+        kind: "qualifier",
+        id: "qualifier",
+        def,
+        width: (size: TableSize) =>
+          size === "small" ? { fixed: 40 } : { fixed: 56 },
+        content,
+        headerContentType: config?.headerContentType,
+        getInitials: config?.getInitials,
+        getIcon: config?.getIcon,
+        getImageSrc: config?.getImageSrc,
+        selectable: config?.selectable,
+        header: config?.header,
+      };
+    },
+
+    column<TKey extends DeepKeys<TData>>(
+      accessor: TKey,
+      config: DataColumnConfig<TData, DeepValue<TData, TKey>>
+    ): OnyxDataColumn<TData> {
+      const {
+        header,
+        cell,
+        enableSorting = true,
+        enableResizing = true,
+        enableHiding = true,
+        icon,
+        weight = 20,
+        minWidth = 50,
+      } = config;
+
+      const def = helper.accessor(accessor as any, {
+        header,
+        enableSorting,
+        enableResizing,
+        enableHiding,
+        cell: cell
+          ? (info: CellContext<TData, any>) =>
+              cell(info.getValue(), info.row.original)
+          : undefined,
+      }) as ColumnDef<TData, any>;
+
+      return {
+        kind: "data",
+        id: accessor as string,
+        def,
+        width: { weight, minWidth },
+        icon,
+      };
+    },
+
+    displayColumn(
+      config: DisplayColumnConfig<TData>
+    ): OnyxDisplayColumn<TData> {
+      const { id, header, cell, width, enableHiding = true } = config;
+
+      const def: ColumnDef<TData, any> = helper.display({
+        id,
+        header: header ?? undefined,
+        enableHiding,
+        enableSorting: false,
+        enableResizing: false,
+        cell: (info) => cell(info.row.original),
+      });
+
+      return {
+        kind: "display",
+        id,
+        def,
+        width,
+      };
+    },
+
+    actions(config?: ActionsConfig): OnyxActionsColumn<TData> {
+      const def: ColumnDef<TData, any> = {
+        id: "__actions",
+        enableHiding: false,
+        enableSorting: false,
+        enableResizing: false,
+        // Header rendering is handled by DataTable based on the actions config
+        header: () => null,
+        cell: () => null,
+      };
+
+      return {
+        kind: "actions",
+        id: "__actions",
+        def,
+        width: (size: TableSize) =>
+          size === "small" ? { fixed: 20 } : { fixed: 88 },
+        showColumnVisibility: config?.showColumnVisibility ?? true,
+        showSorting: config?.showSorting ?? true,
+        sortingFooterText: config?.sortingFooterText,
+      };
+    },
+  };
+}
diff --git a/web/src/refresh-components/table/types.ts b/web/src/refresh-components/table/types.ts
new file mode 100644
index 00000000000..d464371b404
--- /dev/null
+++ b/web/src/refresh-components/table/types.ts
@@ -0,0 +1,162 @@
+import type { ReactNode } from "react";
+import type {
+  ColumnDef,
+  SortingState,
+  VisibilityState,
+} from "@tanstack/react-table";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { IconFunctionComponent } from "@opal/types";
+import type { SortDirection } from "@/refresh-components/table/TableHead";
+
+// ---------------------------------------------------------------------------
+// Column width (mirrors useColumnWidths types)
+// ---------------------------------------------------------------------------
+
+/** Width config for a data column (participates in proportional distribution). */
+export interface DataColumnWidth {
+  weight: number;
+  minWidth?: number;
+}
+
+/** Width config for a fixed column (exact pixels, no proportional distribution). */
+export interface FixedColumnWidth {
+  fixed: number;
+}
+
+export type ColumnWidth = DataColumnWidth | FixedColumnWidth;
+
+// ---------------------------------------------------------------------------
+// Column kind discriminant
+// ---------------------------------------------------------------------------
+
+export type QualifierContentType =
+  | "icon"
+  | "simple"
+  | "image"
+  | "avatar-icon"
+  | "avatar-user";
+
+export type OnyxColumnKind = "qualifier" | "data" | "display" | "actions";
+
+// ---------------------------------------------------------------------------
+// Column definitions (discriminated union on `kind`)
+// ---------------------------------------------------------------------------
+
+interface OnyxColumnBase<TData> {
+  kind: OnyxColumnKind;
+  /** Stable column identifier (mirrors the TanStack column ID). */
+  id: string;
+  def: ColumnDef<TData, any>;
+  width: ColumnWidth | ((size: TableSize) => ColumnWidth);
+}
+
+/** Qualifier column — leading avatar/icon/checkbox column. */
+export interface OnyxQualifierColumn<TData> extends OnyxColumnBase<TData> {
+  kind: "qualifier";
+  /** Content type for body-row `<TableQualifier>`. */
+  content: QualifierContentType;
+  /** Content type for the header `<TableQualifier>`. @default "simple" */
+  headerContentType?: QualifierContentType;
+  /** Extract initials from a row (for "avatar-user" content). */
+  getInitials?: (row: TData) => string;
+  /** Extract icon from a row (for "icon" / "avatar-icon" content). */
+  getIcon?: (row: TData) => IconFunctionComponent;
+  /** Extract image src from a row (for "image" content). */
+  getImageSrc?: (row: TData) => string;
+  /** Whether to show selection checkboxes on the qualifier. @default true */
+  selectable?: boolean;
+  /** Whether to render qualifier content in the header. @default true */
+  header?: boolean;
+}
+
+/** Data column — accessor-based column with sorting/resizing. */
+export interface OnyxDataColumn<TData> extends OnyxColumnBase<TData> {
+  kind: "data";
+  /** Override the sort icon for this column. */
+  icon?: (sorted: SortDirection) => IconFunctionComponent;
+}
+
+/** Display column — non-accessor column with custom rendering. */
+export interface OnyxDisplayColumn<TData> extends OnyxColumnBase<TData> {
+  kind: "display";
+}
+
+/** Actions column — fixed column with visibility/sorting popovers. */
+export interface OnyxActionsColumn<TData> extends OnyxColumnBase<TData> {
+  kind: "actions";
+  /** Show column visibility popover. @default true */
+  showColumnVisibility?: boolean;
+  /** Show sorting popover. @default true */
+  showSorting?: boolean;
+  /** Footer text for the sorting popover. */
+  sortingFooterText?: string;
+}
+
+/** Discriminated union of all column types. */
+export type OnyxColumnDef<TData> =
+  | OnyxQualifierColumn<TData>
+  | OnyxDataColumn<TData>
+  | OnyxDisplayColumn<TData>
+  | OnyxActionsColumn<TData>;
+
+// ---------------------------------------------------------------------------
+// DataTable props
+// ---------------------------------------------------------------------------
+
+export interface DataTableDraggableConfig<TData> {
+  /** Extract a unique string ID from each row. */
+  getRowId: (row: TData) => string;
+  /** Called after a successful reorder with the new ID order and changed positions. */
+  onReorder: (
+    ids: string[],
+    changedOrders: Record<string, number>
+  ) => void | Promise<void>;
+}
+
+export interface DataTableFooterSelection {
+  mode: "selection";
+  /** Whether the table supports selecting multiple rows. @default true */
+  multiSelect?: boolean;
+  /** Handler for the "View" button. */
+  onView?: () => void;
+  /** Handler for the "Clear" button. When omitted, the default clearSelection is used. */
+  onClear?: () => void;
+}
+
+export interface DataTableFooterSummary {
+  mode: "summary";
+}
+
+export type DataTableFooterConfig =
+  | DataTableFooterSelection
+  | DataTableFooterSummary;
+
+export interface DataTableProps<TData> {
+  /** Row data array. */
+  data: TData[];
+  /** Column definitions created via `createTableColumns()`. */
+  columns: OnyxColumnDef<TData>[];
+  /** Rows per page. Set `Infinity` to disable pagination. @default 10 */
+  pageSize?: number;
+  /** Initial sorting state. */
+  initialSorting?: SortingState;
+  /** Initial column visibility state. */
+  initialColumnVisibility?: VisibilityState;
+  /** Enable drag-and-drop row reordering. */
+  draggable?: DataTableDraggableConfig<TData>;
+  /** Footer configuration. */
+  footer?: DataTableFooterConfig;
+  /** Table size variant. @default "regular" */
+  size?: TableSize;
+  /** Called when a row is clicked (replaces the default selection toggle). */
+  onRowClick?: (row: TData) => void;
+  /**
+   * Max height of the scrollable table area. When set, the table body scrolls
+   * vertically while the header stays pinned at the top.
+   * Accepts a pixel number (e.g. `300`) or a CSS value string (e.g. `"50vh"`).
+   */
+  height?: number | string;
+  /** Background color for the sticky header row, preventing rows from showing
+   *  through when scrolling. Accepts any CSS color value. */
+  headerBackground?: string;
+}

From 52db41a00b8b5e6dd6ad362ac4492007eb31c5fd Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:21:37 -0800
Subject: [PATCH 085/267] chore(deps): bump nltk from 3.9.1 to 3.9.3 (#9045)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt | 2 +-
 uv.lock                          | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 59a94f1d976..ef4196af65c 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -596,7 +596,7 @@ mypy-extensions==1.0.0
     #   typing-inspect
 nest-asyncio==1.6.0
     # via onyx
-nltk==3.9.1
+nltk==3.9.3
     # via unstructured
 numpy==2.4.1
     # via
diff --git a/uv.lock b/uv.lock
index d843f03b9ae..951041b1bfe 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4106,7 +4106,7 @@ wheels = [
 
 [[package]]
 name = "nltk"
-version = "3.9.1"
+version = "3.9.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "click" },
@@ -4114,9 +4114,9 @@ dependencies = [
     { name = "regex" },
     { name = "tqdm" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/3c/87/db8be88ad32c2d042420b6fd9ffd4a149f9a0d7f0e86b3f543be2eeeedd2/nltk-3.9.1.tar.gz", hash = "sha256:87d127bd3de4bd89a4f81265e5fa59cb1b199b27440175370f7417d2bc7ae868", size = 2904691, upload-time = "2024-08-18T19:48:37.769Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e1/8f/915e1c12df07c70ed779d18ab83d065718a926e70d3ea33eb0cd66ffb7c0/nltk-3.9.3.tar.gz", hash = "sha256:cb5945d6424a98d694c2b9a0264519fab4363711065a46aa0ae7a2195b92e71f", size = 2923673, upload-time = "2026-02-24T12:05:53.833Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4d/66/7d9e26593edda06e8cb531874633f7c2372279c3b0f46235539fe546df8b/nltk-3.9.1-py3-none-any.whl", hash = "sha256:4fa26829c5b00715afe3061398a8989dc643b92ce7dd93fb4585a70930d168a1", size = 1505442, upload-time = "2024-08-18T19:48:21.909Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/7e/9af5a710a1236e4772de8dfcc6af942a561327bb9f42b5b4a24d0cf100fd/nltk-3.9.3-py3-none-any.whl", hash = "sha256:60b3db6e9995b3dd976b1f0fa7dec22069b2677e759c28eb69b62ddd44870522", size = 1525385, upload-time = "2026-02-24T12:05:46.54Z" },
 ]
 
 [[package]]

From 8193aa4fd04b04258f7373dcf119f793243bbdc2 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:34:50 -0800
Subject: [PATCH 086/267] fix(ui): Persist agent sharing changes immediately
 for existing agents (#9024)

---
 web/src/refresh-pages/AgentEditorPage.tsx   | 112 ++++++++++++++++++--
 web/src/sections/modals/ShareAgentModal.tsx |  48 ++++++---
 2 files changed, 138 insertions(+), 22 deletions(-)

diff --git a/web/src/refresh-pages/AgentEditorPage.tsx b/web/src/refresh-pages/AgentEditorPage.tsx
index 58465f33213..fb1d3539287 100644
--- a/web/src/refresh-pages/AgentEditorPage.tsx
+++ b/web/src/refresh-pages/AgentEditorPage.tsx
@@ -81,7 +81,11 @@ import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useFilter from "@/hooks/useFilter";
 import EnabledCount from "@/refresh-components/EnabledCount";
 import { useAppRouter } from "@/hooks/appNavigation";
-import { deleteAgent } from "@/lib/agents";
+import {
+  deleteAgent,
+  updateAgentFeaturedStatus,
+  updateAgentSharedStatus,
+} from "@/lib/agents";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
 import ShareAgentModal from "@/sections/modals/ShareAgentModal";
 import AgentKnowledgePane from "@/sections/knowledge/AgentKnowledgePane";
@@ -89,6 +93,7 @@ import { ValidSources } from "@/lib/types";
 import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 import { useUser } from "@/providers/UserProvider";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
+import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 
 interface AgentIconEditorProps {
   existingAgent?: FullPersona | null;
@@ -450,6 +455,7 @@ export default function AgentEditorPage({
   const { isAdmin, isCurator } = useUser();
   const canUpdateFeaturedStatus = isAdmin || isCurator;
   const vectorDbEnabled = useVectorDbEnabled();
+  const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
 
   // LLM Model Selection
   const getCurrentLlm = useCallback(
@@ -1044,19 +1050,111 @@ export default function AgentEditorPage({
                     isPublic={values.is_public}
                     isFeatured={values.featured}
                     labelIds={values.label_ids}
-                    onShare={(
+                    onShare={async (
                       userIds,
                       groupIds,
                       isPublic,
                       isFeatured,
                       labelIds
                     ) => {
-                      setFieldValue("shared_user_ids", userIds);
-                      setFieldValue("shared_group_ids", groupIds);
-                      setFieldValue("is_public", isPublic);
-                      setFieldValue("featured", isFeatured);
-                      setFieldValue("label_ids", labelIds);
+                      if (!existingAgent) {
+                        // New agents are not persisted until the main Create action.
+                        setFieldValue("shared_user_ids", userIds);
+                        setFieldValue("shared_group_ids", groupIds);
+                        setFieldValue("is_public", isPublic);
+                        setFieldValue("featured", isFeatured);
+                        setFieldValue("label_ids", labelIds);
+                        shareAgentModal.toggle(false);
+                        return;
+                      }
+
+                      const applySharingFields = () => {
+                        setFieldValue("shared_user_ids", userIds);
+                        setFieldValue("shared_group_ids", groupIds);
+                        setFieldValue("is_public", isPublic);
+                        setFieldValue("label_ids", labelIds);
+                      };
+
+                      const refreshSharedUi = async () => {
+                        try {
+                          await refreshAgents();
+                          refreshAgent?.();
+                        } catch (error) {
+                          console.error(
+                            "Refresh failed after successful share:",
+                            error
+                          );
+                          toast.error(
+                            "Agent sharing was saved, but failed to refresh. Please reload."
+                          );
+                        }
+                      };
+
+                      let shareError: string | null;
+                      try {
+                        shareError = await updateAgentSharedStatus(
+                          existingAgent.id,
+                          userIds,
+                          groupIds,
+                          isPublic,
+                          isPaidEnterpriseFeaturesEnabled,
+                          labelIds
+                        );
+                      } catch (error) {
+                        console.error(
+                          "Share agent mutation failed unexpectedly:",
+                          error
+                        );
+                        toast.error("Failed to share agent. Please try again.");
+                        return;
+                      }
+
+                      if (shareError) {
+                        toast.error(`Failed to share agent: ${shareError}`);
+                        return;
+                      }
+
+                      if (canUpdateFeaturedStatus) {
+                        let featuredError: string | null;
+                        try {
+                          featuredError = await updateAgentFeaturedStatus(
+                            existingAgent.id,
+                            isFeatured
+                          );
+                        } catch (error) {
+                          console.error(
+                            "Featured mutation failed unexpectedly:",
+                            error
+                          );
+                          // Share succeeded; sync form and UI before returning.
+                          applySharingFields();
+                          await refreshSharedUi();
+                          toast.error(
+                            "Failed to update featured status. Please try again."
+                          );
+                          return;
+                        }
+
+                        if (featuredError) {
+                          // Share succeeded, featured failed: keep modal open for retry.
+                          applySharingFields();
+                          await refreshSharedUi();
+                          toast.error(
+                            `Failed to update featured status: ${featuredError}`
+                          );
+                          return;
+                        }
+
+                        applySharingFields();
+                        setFieldValue("featured", isFeatured);
+                        shareAgentModal.toggle(false);
+                        await refreshSharedUi();
+                        return;
+                      }
+
+                      applySharingFields();
                       shareAgentModal.toggle(false);
+                      await refreshSharedUi();
                     }}
                   />
                 </shareAgentModal.Provider>
diff --git a/web/src/sections/modals/ShareAgentModal.tsx b/web/src/sections/modals/ShareAgentModal.tsx
index 901d32c8355..761376e0cd4 100644
--- a/web/src/sections/modals/ShareAgentModal.tsx
+++ b/web/src/sections/modals/ShareAgentModal.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
 import Button from "@/refresh-components/buttons/Button";
 import {
@@ -56,7 +56,7 @@ interface ShareAgentFormContentProps {
 }
 
 function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
-  const { values, setFieldValue, handleSubmit, dirty } =
+  const { values, setFieldValue, handleSubmit, dirty, isSubmitting } =
     useFormikContext<ShareAgentFormValues>();
   const { data: usersData } = useShareableUsers({ includeApiKeys: true });
   const { data: groupsData } = useShareableGroups();
@@ -349,12 +349,15 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
             ) : undefined
           }
           cancel={
-            <Button secondary onClick={handleClose}>
+            <Button secondary onClick={handleClose} disabled={isSubmitting}>
               Cancel
             </Button>
           }
           submit={
-            <Button onClick={() => handleSubmit()} disabled={!dirty}>
+            <Button
+              onClick={() => handleSubmit()}
+              disabled={!dirty || isSubmitting}
+            >
               Save
             </Button>
           }
@@ -381,7 +384,7 @@ export interface ShareAgentModalProps {
     isPublic: boolean,
     isFeatured: boolean,
     labelIds: number[]
-  ) => void;
+  ) => Promise<void> | void;
 }
 
 export default function ShareAgentModal({
@@ -395,16 +398,31 @@ export default function ShareAgentModal({
 }: ShareAgentModalProps) {
   const shareAgentModal = useModal();
 
-  const initialValues: ShareAgentFormValues = {
-    selectedUserIds: userIds,
-    selectedGroupIds: groupIds,
-    isPublic: isPublic,
-    isFeatured: isFeatured,
-    labelIds: labelIds,
-  };
+  const initialValues = useMemo(
+    (): ShareAgentFormValues => ({
+      selectedUserIds: userIds,
+      selectedGroupIds: groupIds,
+      isPublic: isPublic,
+      isFeatured: isFeatured,
+      labelIds: labelIds,
+    }),
+    [userIds, groupIds, isPublic, isFeatured, labelIds]
+  );
+  const [modalInitialValues, setModalInitialValues] =
+    useState<ShareAgentFormValues>(initialValues);
+  const wasOpenRef = useRef(false);
+
+  useEffect(() => {
+    // Capture fresh props exactly when the modal opens, then keep them stable
+    // while open so in-flight parent updates don't reset form state.
+    if (shareAgentModal.isOpen && !wasOpenRef.current) {
+      setModalInitialValues(initialValues);
+    }
+    wasOpenRef.current = shareAgentModal.isOpen;
+  }, [shareAgentModal.isOpen, initialValues]);
 
-  function handleSubmit(values: ShareAgentFormValues) {
-    onShare?.(
+  async function handleSubmit(values: ShareAgentFormValues) {
+    await onShare?.(
       values.selectedUserIds,
       values.selectedGroupIds,
       values.isPublic,
@@ -416,7 +434,7 @@ export default function ShareAgentModal({
   return (
     <Modal open={shareAgentModal.isOpen} onOpenChange={shareAgentModal.toggle}>
       <Formik
-        initialValues={initialValues}
+        initialValues={modalInitialValues}
         onSubmit={handleSubmit}
         enableReinitialize
       >

From b2720855431fc2d8798cfb0ebb0c5bd614da5f5f Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:58:00 -0800
Subject: [PATCH 087/267] fix: Code Interpreter Client session clean up (#9028)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../python/code_interpreter_client.py         |  22 +-
 .../python/python_tool.py                     | 339 +++++++++---------
 .../tools/test_python_tool_availability.py    |   6 +-
 3 files changed, 197 insertions(+), 170 deletions(-)

diff --git a/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py b/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
index e4d204ab739..442b76a9f20 100644
--- a/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
+++ b/backend/onyx/tools/tool_implementations/python/code_interpreter_client.py
@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import json
 import time
 from collections.abc import Generator
@@ -84,6 +86,19 @@ def __init__(self, base_url: str | None = CODE_INTERPRETER_BASE_URL):
             raise ValueError("CODE_INTERPRETER_BASE_URL not configured")
         self.base_url = base_url.rstrip("/")
         self.session = requests.Session()
+        self._closed = False
+
+    def __enter__(self) -> CodeInterpreterClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self.session.close()
+        self._closed = True
 
     def _build_payload(
         self,
@@ -177,8 +192,11 @@ def execute_streaming(
             yield from self._batch_as_stream(code, stdin, timeout_ms, files)
             return
 
-        response.raise_for_status()
-        yield from self._parse_sse(response)
+        try:
+            response.raise_for_status()
+            yield from self._parse_sse(response)
+        finally:
+            response.close()
 
     def _parse_sse(
         self, response: requests.Response
diff --git a/backend/onyx/tools/tool_implementations/python/python_tool.py b/backend/onyx/tools/tool_implementations/python/python_tool.py
index 257dff74a68..21268975fb9 100644
--- a/backend/onyx/tools/tool_implementations/python/python_tool.py
+++ b/backend/onyx/tools/tool_implementations/python/python_tool.py
@@ -111,8 +111,8 @@ def is_available(cls, db_session: Session) -> bool:
         if not server.server_enabled:
             return False
 
-        client = CodeInterpreterClient()
-        return client.health(use_cache=True)
+        with CodeInterpreterClient() as client:
+            return client.health(use_cache=True)
 
     def tool_definition(self) -> dict:
         return {
@@ -176,196 +176,203 @@ def run(
             )
         )
 
-        # Create Code Interpreter client
-        client = CodeInterpreterClient()
+        # Create Code Interpreter client — context manager ensures
+        # session.close() is called on every exit path.
+        with CodeInterpreterClient() as client:
+            # Stage chat files for execution
+            files_to_stage: list[FileInput] = []
+            for ind, chat_file in enumerate(chat_files):
+                file_name = chat_file.filename or f"file_{ind}"
+                try:
+                    # Upload to Code Interpreter
+                    ci_file_id = client.upload_file(chat_file.content, file_name)
 
-        # Stage chat files for execution
-        files_to_stage: list[FileInput] = []
-        for ind, chat_file in enumerate(chat_files):
-            file_name = chat_file.filename or f"file_{ind}"
-            try:
-                # Upload to Code Interpreter
-                ci_file_id = client.upload_file(chat_file.content, file_name)
+                    # Stage for execution
+                    files_to_stage.append({"path": file_name, "file_id": ci_file_id})
 
-                # Stage for execution
-                files_to_stage.append({"path": file_name, "file_id": ci_file_id})
+                    logger.info(f"Staged file for Python execution: {file_name}")
 
-                logger.info(f"Staged file for Python execution: {file_name}")
+                except Exception as e:
+                    logger.warning(f"Failed to stage file {file_name}: {e}")
 
-            except Exception as e:
-                logger.warning(f"Failed to stage file {file_name}: {e}")
-
-        try:
-            logger.debug(f"Executing code: {code}")
-
-            # Execute code with streaming (falls back to batch if unavailable)
-            stdout_parts: list[str] = []
-            stderr_parts: list[str] = []
-            result_event: StreamResultEvent | None = None
-
-            for event in client.execute_streaming(
-                code=code,
-                timeout_ms=CODE_INTERPRETER_DEFAULT_TIMEOUT_MS,
-                files=files_to_stage or None,
-            ):
-                if isinstance(event, StreamOutputEvent):
-                    if event.stream == "stdout":
-                        stdout_parts.append(event.data)
-                    else:
-                        stderr_parts.append(event.data)
-                    # Emit incremental delta to frontend
-                    self.emitter.emit(
-                        Packet(
-                            placement=placement,
-                            obj=PythonToolDelta(
-                                stdout=event.data if event.stream == "stdout" else "",
-                                stderr=event.data if event.stream == "stderr" else "",
-                            ),
+            try:
+                logger.debug(f"Executing code: {code}")
+
+                # Execute code with streaming (falls back to batch if unavailable)
+                stdout_parts: list[str] = []
+                stderr_parts: list[str] = []
+                result_event: StreamResultEvent | None = None
+
+                for event in client.execute_streaming(
+                    code=code,
+                    timeout_ms=CODE_INTERPRETER_DEFAULT_TIMEOUT_MS,
+                    files=files_to_stage or None,
+                ):
+                    if isinstance(event, StreamOutputEvent):
+                        if event.stream == "stdout":
+                            stdout_parts.append(event.data)
+                        else:
+                            stderr_parts.append(event.data)
+                        # Emit incremental delta to frontend
+                        self.emitter.emit(
+                            Packet(
+                                placement=placement,
+                                obj=PythonToolDelta(
+                                    stdout=(
+                                        event.data if event.stream == "stdout" else ""
+                                    ),
+                                    stderr=(
+                                        event.data if event.stream == "stderr" else ""
+                                    ),
+                                ),
+                            )
                         )
+                    elif isinstance(event, StreamResultEvent):
+                        result_event = event
+                    elif isinstance(event, StreamErrorEvent):
+                        raise RuntimeError(f"Code interpreter error: {event.message}")
+
+                if result_event is None:
+                    raise RuntimeError(
+                        "Code interpreter stream ended without a result event"
                     )
-                elif isinstance(event, StreamResultEvent):
-                    result_event = event
-                elif isinstance(event, StreamErrorEvent):
-                    raise RuntimeError(f"Code interpreter error: {event.message}")
-
-            if result_event is None:
-                raise RuntimeError(
-                    "Code interpreter stream ended without a result event"
+
+                full_stdout = "".join(stdout_parts)
+                full_stderr = "".join(stderr_parts)
+
+                # Truncate output for LLM consumption
+                truncated_stdout = _truncate_output(
+                    full_stdout, CODE_INTERPRETER_MAX_OUTPUT_LENGTH, "stdout"
+                )
+                truncated_stderr = _truncate_output(
+                    full_stderr, CODE_INTERPRETER_MAX_OUTPUT_LENGTH, "stderr"
                 )
 
-            full_stdout = "".join(stdout_parts)
-            full_stderr = "".join(stderr_parts)
+                # Handle generated files
+                generated_files: list[PythonExecutionFile] = []
+                generated_file_ids: list[str] = []
+                file_ids_to_cleanup: list[str] = []
+                file_store = get_default_file_store()
+
+                for workspace_file in result_event.files:
+                    if workspace_file.kind != "file" or not workspace_file.file_id:
+                        continue
+
+                    try:
+                        # Download file from Code Interpreter
+                        file_content = client.download_file(workspace_file.file_id)
+
+                        # Determine MIME type from file extension
+                        filename = workspace_file.path.split("/")[-1]
+                        mime_type, _ = mimetypes.guess_type(filename)
+                        # Default to binary if we can't determine the type
+                        mime_type = mime_type or "application/octet-stream"
+
+                        # Save to Onyx file store
+                        onyx_file_id = file_store.save_file(
+                            content=BytesIO(file_content),
+                            display_name=filename,
+                            file_origin=FileOrigin.CHAT_UPLOAD,
+                            file_type=mime_type,
+                        )
 
-            # Truncate output for LLM consumption
-            truncated_stdout = _truncate_output(
-                full_stdout, CODE_INTERPRETER_MAX_OUTPUT_LENGTH, "stdout"
-            )
-            truncated_stderr = _truncate_output(
-                full_stderr, CODE_INTERPRETER_MAX_OUTPUT_LENGTH, "stderr"
-            )
+                        generated_files.append(
+                            PythonExecutionFile(
+                                filename=filename,
+                                file_link=build_full_frontend_file_url(onyx_file_id),
+                            )
+                        )
+                        generated_file_ids.append(onyx_file_id)
 
-            # Handle generated files
-            generated_files: list[PythonExecutionFile] = []
-            generated_file_ids: list[str] = []
-            file_ids_to_cleanup: list[str] = []
-            file_store = get_default_file_store()
+                        # Mark for cleanup
+                        file_ids_to_cleanup.append(workspace_file.file_id)
 
-            for workspace_file in result_event.files:
-                if workspace_file.kind != "file" or not workspace_file.file_id:
-                    continue
+                    except Exception as e:
+                        logger.error(
+                            f"Failed to handle generated file "
+                            f"{workspace_file.path}: {e}"
+                        )
 
-                try:
-                    # Download file from Code Interpreter
-                    file_content = client.download_file(workspace_file.file_id)
-
-                    # Determine MIME type from file extension
-                    filename = workspace_file.path.split("/")[-1]
-                    mime_type, _ = mimetypes.guess_type(filename)
-                    # Default to binary if we can't determine the type
-                    mime_type = mime_type or "application/octet-stream"
-
-                    # Save to Onyx file store
-                    onyx_file_id = file_store.save_file(
-                        content=BytesIO(file_content),
-                        display_name=filename,
-                        file_origin=FileOrigin.CHAT_UPLOAD,
-                        file_type=mime_type,
-                    )
+                # Cleanup Code Interpreter files (generated files)
+                for ci_file_id in file_ids_to_cleanup:
+                    try:
+                        client.delete_file(ci_file_id)
+                    except Exception as e:
+                        logger.error(
+                            f"Failed to delete Code Interpreter generated "
+                            f"file {ci_file_id}: {e}"
+                        )
 
-                    generated_files.append(
-                        PythonExecutionFile(
-                            filename=filename,
-                            file_link=build_full_frontend_file_url(onyx_file_id),
+                # Cleanup staged input files
+                for file_mapping in files_to_stage:
+                    try:
+                        client.delete_file(file_mapping["file_id"])
+                    except Exception as e:
+                        logger.error(
+                            f"Failed to delete Code Interpreter staged "
+                            f"file {file_mapping['file_id']}: {e}"
+                        )
+
+                # Emit file_ids once files are processed
+                if generated_file_ids:
+                    self.emitter.emit(
+                        Packet(
+                            placement=placement,
+                            obj=PythonToolDelta(file_ids=generated_file_ids),
                         )
                     )
-                    generated_file_ids.append(onyx_file_id)
 
-                    # Mark for cleanup
-                    file_ids_to_cleanup.append(workspace_file.file_id)
+                # Build result
+                result = LlmPythonExecutionResult(
+                    stdout=truncated_stdout,
+                    stderr=truncated_stderr,
+                    exit_code=result_event.exit_code,
+                    timed_out=result_event.timed_out,
+                    generated_files=generated_files,
+                    error=(None if result_event.exit_code == 0 else truncated_stderr),
+                )
 
-                except Exception as e:
-                    logger.error(
-                        f"Failed to handle generated file {workspace_file.path}: {e}"
-                    )
+                # Serialize result for LLM
+                adapter = TypeAdapter(LlmPythonExecutionResult)
+                llm_response = adapter.dump_json(result).decode()
 
-            # Cleanup Code Interpreter files (generated files)
-            for ci_file_id in file_ids_to_cleanup:
-                try:
-                    client.delete_file(ci_file_id)
-                except Exception as e:
-                    logger.error(
-                        f"Failed to delete Code Interpreter generated file {ci_file_id}: {e}"
-                    )
+                return ToolResponse(
+                    rich_response=PythonToolRichResponse(
+                        generated_files=generated_files,
+                    ),
+                    llm_facing_response=llm_response,
+                )
 
-            # Cleanup staged input files
-            for file_mapping in files_to_stage:
-                try:
-                    client.delete_file(file_mapping["file_id"])
-                except Exception as e:
-                    logger.error(
-                        f"Failed to delete Code Interpreter staged file {file_mapping['file_id']}: {e}"
-                    )
+            except Exception as e:
+                logger.error(f"Python execution failed: {e}")
+                error_msg = str(e)
 
-            # Emit file_ids once files are processed
-            if generated_file_ids:
+                # Emit error delta
                 self.emitter.emit(
                     Packet(
                         placement=placement,
-                        obj=PythonToolDelta(file_ids=generated_file_ids),
+                        obj=PythonToolDelta(
+                            stdout="",
+                            stderr=error_msg,
+                            file_ids=[],
+                        ),
                     )
                 )
 
-            # Build result
-            result = LlmPythonExecutionResult(
-                stdout=truncated_stdout,
-                stderr=truncated_stderr,
-                exit_code=result_event.exit_code,
-                timed_out=result_event.timed_out,
-                generated_files=generated_files,
-                error=None if result_event.exit_code == 0 else truncated_stderr,
-            )
-
-            # Serialize result for LLM
-            adapter = TypeAdapter(LlmPythonExecutionResult)
-            llm_response = adapter.dump_json(result).decode()
-
-            return ToolResponse(
-                rich_response=PythonToolRichResponse(
-                    generated_files=generated_files,
-                ),
-                llm_facing_response=llm_response,
-            )
-
-        except Exception as e:
-            logger.error(f"Python execution failed: {e}")
-            error_msg = str(e)
-
-            # Emit error delta
-            self.emitter.emit(
-                Packet(
-                    placement=placement,
-                    obj=PythonToolDelta(
-                        stdout="",
-                        stderr=error_msg,
-                        file_ids=[],
-                    ),
+                # Return error result
+                result = LlmPythonExecutionResult(
+                    stdout="",
+                    stderr=error_msg,
+                    exit_code=-1,
+                    timed_out=False,
+                    generated_files=[],
+                    error=error_msg,
                 )
-            )
-
-            # Return error result
-            result = LlmPythonExecutionResult(
-                stdout="",
-                stderr=error_msg,
-                exit_code=-1,
-                timed_out=False,
-                generated_files=[],
-                error=error_msg,
-            )
 
-            adapter = TypeAdapter(LlmPythonExecutionResult)
-            llm_response = adapter.dump_json(result).decode()
+                adapter = TypeAdapter(LlmPythonExecutionResult)
+                llm_response = adapter.dump_json(result).decode()
 
-            return ToolResponse(
-                rich_response=None,
-                llm_facing_response=llm_response,
-            )
+                return ToolResponse(
+                    rich_response=None,
+                    llm_facing_response=llm_response,
+                )
diff --git a/backend/tests/unit/onyx/tools/test_python_tool_availability.py b/backend/tests/unit/onyx/tools/test_python_tool_availability.py
index a5a6531412c..1eb4e4ebf3f 100644
--- a/backend/tests/unit/onyx/tools/test_python_tool_availability.py
+++ b/backend/tests/unit/onyx/tools/test_python_tool_availability.py
@@ -87,7 +87,8 @@ def test_python_tool_available_when_health_check_passes(
 
     mock_client = MagicMock()
     mock_client.health.return_value = True
-    mock_client_cls.return_value = mock_client
+    mock_client_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
+    mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
 
     db_session = MagicMock(spec=Session)
     assert PythonTool.is_available(db_session) is True
@@ -109,7 +110,8 @@ def test_python_tool_unavailable_when_health_check_fails(
 
     mock_client = MagicMock()
     mock_client.health.return_value = False
-    mock_client_cls.return_value = mock_client
+    mock_client_cls.return_value.__enter__ = MagicMock(return_value=mock_client)
+    mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
 
     db_session = MagicMock(spec=Session)
     assert PythonTool.is_available(db_session) is False

From b2956f795bbc74da4826cffd1bab662eec504ada Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 4 Mar 2026 14:09:25 -0800
Subject: [PATCH 088/267] refactor: migrate LLM & embedding management to
 OnyxError (#9025)

---
 backend/onyx/server/manage/embedding/api.py   |  10 +-
 backend/onyx/server/manage/llm/api.py         | 144 +++++++++---------
 .../llm/test_llm_provider.py                  |  28 ++--
 .../llm/test_llm_provider_api_base.py         |  27 ++--
 .../tests/llm_provider/test_llm_provider.py   |   8 +-
 .../test_llm_provider_persona_access.py       |   4 +-
 6 files changed, 111 insertions(+), 110 deletions(-)

diff --git a/backend/onyx/server/manage/embedding/api.py b/backend/onyx/server/manage/embedding/api.py
index ef659a4fac5..55688d204d0 100644
--- a/backend/onyx/server/manage/embedding/api.py
+++ b/backend/onyx/server/manage/embedding/api.py
@@ -1,6 +1,5 @@
 from fastapi import APIRouter
 from fastapi import Depends
-from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
 from onyx.auth.users import current_admin_user
@@ -11,6 +10,8 @@
 from onyx.db.models import User
 from onyx.db.search_settings import get_all_search_settings
 from onyx.db.search_settings import get_current_db_embedding_provider
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.indexing.models import EmbeddingModelDetail
 from onyx.natural_language_processing.search_nlp_models import EmbeddingModel
 from onyx.server.manage.embedding.models import CloudEmbeddingProvider
@@ -59,7 +60,7 @@ def test_embedding_configuration(
     except Exception as e:
         error_msg = "An error occurred while testing your embedding model. Please check your configuration."
         logger.error(f"{error_msg} Error message: {e}", exc_info=True)
-        raise HTTPException(status_code=400, detail=error_msg)
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, error_msg)
 
 
 @admin_router.get("", response_model=list[EmbeddingModelDetail])
@@ -93,8 +94,9 @@ def delete_embedding_provider(
         embedding_provider is not None
         and provider_type == embedding_provider.provider_type
     ):
-        raise HTTPException(
-            status_code=400, detail="You can't delete a currently active model"
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "You can't delete a currently active model",
         )
 
     remove_embedding_provider(db_session, provider_type=provider_type)
diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index f15430cbcf8..6c7b0e8affe 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -11,7 +11,6 @@
 from botocore.exceptions import NoCredentialsError
 from fastapi import APIRouter
 from fastapi import Depends
-from fastapi import HTTPException
 from fastapi import Query
 from pydantic import ValidationError
 from sqlalchemy.orm import Session
@@ -38,6 +37,8 @@
 from onyx.db.llm import validate_persona_ids_exist
 from onyx.db.models import User
 from onyx.db.persona import user_can_access_persona
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.llm.factory import get_default_llm
 from onyx.llm.factory import get_llm
 from onyx.llm.factory import get_max_input_tokens_from_llm_provider
@@ -186,7 +187,7 @@ def _validate_llm_provider_change(
     Only enforced in MULTI_TENANT mode.
 
     Raises:
-        HTTPException: If api_base or custom_config changed without changing API key
+        OnyxError: If api_base or custom_config changed without changing API key
     """
     if not MULTI_TENANT or api_key_changed:
         return
@@ -200,9 +201,9 @@ def _validate_llm_provider_change(
     )
 
     if api_base_changed or custom_config_changed:
-        raise HTTPException(
-            status_code=400,
-            detail="API base and/or custom config cannot be changed without changing the API key",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "API base and/or custom config cannot be changed without changing the API key",
         )
 
 
@@ -222,7 +223,7 @@ def fetch_llm_provider_options(
     for well_known_llm in well_known_llms:
         if well_known_llm.name == provider_name:
             return well_known_llm
-    raise HTTPException(status_code=404, detail=f"Provider {provider_name} not found")
+    raise OnyxError(OnyxErrorCode.NOT_FOUND, f"Provider {provider_name} not found")
 
 
 @admin_router.post("/test")
@@ -281,7 +282,7 @@ def test_llm_configuration(
     error_msg = test_llm(llm)
 
     if error_msg:
-        raise HTTPException(status_code=400, detail=error_msg)
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, error_msg)
 
 
 @admin_router.post("/test/default")
@@ -292,11 +293,11 @@ def test_default_provider(
         llm = get_default_llm()
     except ValueError:
         logger.exception("Failed to fetch default LLM Provider")
-        raise HTTPException(status_code=400, detail="No LLM Provider setup")
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, "No LLM Provider setup")
 
     error = test_llm(llm)
     if error:
-        raise HTTPException(status_code=400, detail=str(error))
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, str(error))
 
 
 @admin_router.get("/provider")
@@ -362,35 +363,31 @@ def put_llm_provider(
     # Check name constraints
     # TODO: Once port from name to id is complete, unique name will no longer be required
     if existing_provider and llm_provider_upsert_request.name != existing_provider.name:
-        raise HTTPException(
-            status_code=400,
-            detail="Renaming providers is not currently supported",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "Renaming providers is not currently supported",
         )
 
     found_provider = fetch_existing_llm_provider(
         name=llm_provider_upsert_request.name, db_session=db_session
     )
     if found_provider is not None and found_provider is not existing_provider:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Provider with name={llm_provider_upsert_request.name} already exists",
+        raise OnyxError(
+            OnyxErrorCode.DUPLICATE_RESOURCE,
+            f"Provider with name={llm_provider_upsert_request.name} already exists",
         )
 
     if existing_provider and is_creation:
-        raise HTTPException(
-            status_code=400,
-            detail=(
-                f"LLM Provider with name {llm_provider_upsert_request.name} and "
-                f"id={llm_provider_upsert_request.id} already exists"
-            ),
+        raise OnyxError(
+            OnyxErrorCode.DUPLICATE_RESOURCE,
+            f"LLM Provider with name {llm_provider_upsert_request.name} and "
+            f"id={llm_provider_upsert_request.id} already exists",
         )
     elif not existing_provider and not is_creation:
-        raise HTTPException(
-            status_code=400,
-            detail=(
-                f"LLM Provider with name {llm_provider_upsert_request.name} and "
-                f"id={llm_provider_upsert_request.id} does not exist"
-            ),
+        raise OnyxError(
+            OnyxErrorCode.NOT_FOUND,
+            f"LLM Provider with name {llm_provider_upsert_request.name} and "
+            f"id={llm_provider_upsert_request.id} does not exist",
         )
 
     # SSRF Protection: Validate api_base and custom_config match stored values
@@ -415,9 +412,9 @@ def put_llm_provider(
             db_session, persona_ids
         )
         if missing_personas:
-            raise HTTPException(
-                status_code=400,
-                detail=f"Invalid persona IDs: {', '.join(map(str, missing_personas))}",
+            raise OnyxError(
+                OnyxErrorCode.VALIDATION_ERROR,
+                f"Invalid persona IDs: {', '.join(map(str, missing_personas))}",
             )
         # Remove duplicates while preserving order
         seen: set[int] = set()
@@ -473,7 +470,7 @@ def put_llm_provider(
         return result
     except ValueError as e:
         logger.exception("Failed to upsert LLM Provider")
-        raise HTTPException(status_code=400, detail=str(e))
+        raise OnyxError(OnyxErrorCode.VALIDATION_ERROR, str(e))
 
 
 @admin_router.delete("/provider/{provider_id}")
@@ -483,19 +480,19 @@ def delete_llm_provider(
     _: User = Depends(current_admin_user),
     db_session: Session = Depends(get_session),
 ) -> None:
-    try:
-        if not force:
-            model = fetch_default_llm_model(db_session)
+    if not force:
+        model = fetch_default_llm_model(db_session)
 
-            if model and model.llm_provider_id == provider_id:
-                raise HTTPException(
-                    status_code=400,
-                    detail="Cannot delete the default LLM provider",
-                )
+        if model and model.llm_provider_id == provider_id:
+            raise OnyxError(
+                OnyxErrorCode.VALIDATION_ERROR,
+                "Cannot delete the default LLM provider",
+            )
 
+    try:
         remove_llm_provider(db_session, provider_id)
     except ValueError as e:
-        raise HTTPException(status_code=404, detail=str(e))
+        raise OnyxError(OnyxErrorCode.NOT_FOUND, str(e))
 
 
 @admin_router.post("/default")
@@ -535,9 +532,9 @@ def get_auto_config(
     """
     config = fetch_llm_recommendations_from_github()
     if not config:
-        raise HTTPException(
-            status_code=502,
-            detail="Failed to fetch configuration from GitHub",
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            "Failed to fetch configuration from GitHub",
         )
     return config.model_dump()
 
@@ -694,13 +691,13 @@ def list_llm_providers_for_persona(
 
     persona = fetch_persona_with_groups(db_session, persona_id)
     if not persona:
-        raise HTTPException(status_code=404, detail="Persona not found")
+        raise OnyxError(OnyxErrorCode.PERSONA_NOT_FOUND, "Persona not found")
 
     # Verify user has access to this persona
     if not user_can_access_persona(db_session, persona_id, user, get_editable=False):
-        raise HTTPException(
-            status_code=403,
-            detail="You don't have access to this assistant",
+        raise OnyxError(
+            OnyxErrorCode.INSUFFICIENT_PERMISSIONS,
+            "You don't have access to this assistant",
         )
 
     is_admin = user.role == UserRole.ADMIN
@@ -854,9 +851,9 @@ def get_bedrock_available_models(
         try:
             bedrock = session.client("bedrock")
         except Exception as e:
-            raise HTTPException(
-                status_code=400,
-                detail=f"Failed to create Bedrock client: {e}. Check AWS credentials and region.",
+            raise OnyxError(
+                OnyxErrorCode.CREDENTIAL_INVALID,
+                f"Failed to create Bedrock client: {e}. Check AWS credentials and region.",
             )
 
         # Build model info dict from foundation models (modelId -> metadata)
@@ -975,14 +972,14 @@ def get_bedrock_available_models(
         return results
 
     except (ClientError, NoCredentialsError, BotoCoreError) as e:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Failed to connect to AWS Bedrock: {e}",
+        raise OnyxError(
+            OnyxErrorCode.CREDENTIAL_INVALID,
+            f"Failed to connect to AWS Bedrock: {e}",
         )
     except Exception as e:
-        raise HTTPException(
-            status_code=500,
-            detail=f"Unexpected error fetching Bedrock models: {e}",
+        raise OnyxError(
+            OnyxErrorCode.INTERNAL_ERROR,
+            f"Unexpected error fetching Bedrock models: {e}",
         )
 
 
@@ -994,9 +991,9 @@ def _get_ollama_available_model_names(api_base: str) -> set[str]:
         response.raise_for_status()
         response_json = response.json()
     except Exception as e:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Failed to fetch Ollama models: {e}",
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            f"Failed to fetch Ollama models: {e}",
         )
 
     models = response_json.get("models", [])
@@ -1013,9 +1010,9 @@ def get_ollama_available_models(
 
     cleaned_api_base = request.api_base.strip().rstrip("/")
     if not cleaned_api_base:
-        raise HTTPException(
-            status_code=400,
-            detail="API base URL is required to fetch Ollama models.",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "API base URL is required to fetch Ollama models.",
         )
 
     # NOTE: most people run Ollama locally, so we don't disallow internal URLs
@@ -1024,9 +1021,9 @@ def get_ollama_available_models(
     # with the same response format
     model_names = _get_ollama_available_model_names(cleaned_api_base)
     if not model_names:
-        raise HTTPException(
-            status_code=400,
-            detail="No models found from your Ollama server",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No models found from your Ollama server",
         )
 
     all_models_with_context_size_and_vision: list[OllamaFinalModelResponse] = []
@@ -1128,9 +1125,9 @@ def _get_openrouter_models_response(api_base: str, api_key: str) -> dict:
         response.raise_for_status()
         return response.json()
     except Exception as e:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Failed to fetch OpenRouter models: {e}",
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            f"Failed to fetch OpenRouter models: {e}",
         )
 
 
@@ -1151,9 +1148,9 @@ def get_openrouter_available_models(
 
     data = response_json.get("data", [])
     if not isinstance(data, list) or len(data) == 0:
-        raise HTTPException(
-            status_code=400,
-            detail="No models found from your OpenRouter endpoint",
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No models found from your OpenRouter endpoint",
         )
 
     results: list[OpenRouterFinalModelResponse] = []
@@ -1188,8 +1185,9 @@ def get_openrouter_available_models(
             )
 
     if not results:
-        raise HTTPException(
-            status_code=400, detail="No compatible models found from OpenRouter"
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No compatible models found from OpenRouter",
         )
 
     sorted_results = sorted(results, key=lambda m: m.name.lower())
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider.py b/backend/tests/external_dependency_unit/llm/test_llm_provider.py
index 6c1a01f2bac..82ab4d07d32 100644
--- a/backend/tests/external_dependency_unit/llm/test_llm_provider.py
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider.py
@@ -11,7 +11,6 @@
 from uuid import uuid4
 
 import pytest
-from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
 from onyx.db.enums import LLMModelFlowType
@@ -20,6 +19,8 @@
 from onyx.db.llm import update_default_provider
 from onyx.db.llm import upsert_llm_provider
 from onyx.db.models import UserRole
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.llm.constants import LlmProviderNames
 from onyx.llm.interfaces import LLM
 from onyx.server.manage.llm.api import (
@@ -122,16 +123,16 @@ def mock_test_llm_success(llm: LLM) -> str | None:
         finally:
             db_session.rollback()
 
-    def test_failed_llm_test_raises_http_exception(
+    def test_failed_llm_test_raises_onyx_error(
         self,
         db_session: Session,
         provider_name: str,  # noqa: ARG002
     ) -> None:
         """
-        Test that a failed LLM test raises an HTTPException with status 400.
+        Test that a failed LLM test raises an OnyxError with VALIDATION_ERROR.
 
         When test_llm returns an error message, the endpoint should raise
-        an HTTPException with the error details.
+        an OnyxError with the error details.
         """
         error_message = "Invalid API key: Authentication failed"
 
@@ -143,7 +144,7 @@ def mock_test_llm_failure(llm: LLM) -> str | None:  # noqa: ARG001
             with patch(
                 "onyx.server.manage.llm.api.test_llm", side_effect=mock_test_llm_failure
             ):
-                with pytest.raises(HTTPException) as exc_info:
+                with pytest.raises(OnyxError) as exc_info:
                     run_test_llm_configuration(
                         test_llm_request=LLMTestRequest(
                             provider=LlmProviderNames.OPENAI,
@@ -156,9 +157,8 @@ def mock_test_llm_failure(llm: LLM) -> str | None:  # noqa: ARG001
                         db_session=db_session,
                     )
 
-                # Verify the exception details
-                assert exc_info.value.status_code == 400
-                assert exc_info.value.detail == error_message
+                assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
+                assert exc_info.value.message == error_message
 
         finally:
             db_session.rollback()
@@ -536,11 +536,11 @@ def test_no_default_provider_raises_exception(
                 remove_llm_provider(db_session, provider.id)
 
             # Now run_test_default_provider should fail
-            with pytest.raises(HTTPException) as exc_info:
+            with pytest.raises(OnyxError) as exc_info:
                 run_test_default_provider(_=_create_mock_admin())
 
-            assert exc_info.value.status_code == 400
-            assert "No LLM Provider setup" in exc_info.value.detail
+            assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
+            assert "No LLM Provider setup" in exc_info.value.message
 
         finally:
             db_session.rollback()
@@ -581,11 +581,11 @@ def mock_test_llm_failure(llm: LLM) -> str | None:  # noqa: ARG001
             with patch(
                 "onyx.server.manage.llm.api.test_llm", side_effect=mock_test_llm_failure
             ):
-                with pytest.raises(HTTPException) as exc_info:
+                with pytest.raises(OnyxError) as exc_info:
                     run_test_default_provider(_=_create_mock_admin())
 
-                assert exc_info.value.status_code == 400
-                assert exc_info.value.detail == error_message
+                assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
+                assert exc_info.value.message == error_message
 
         finally:
             db_session.rollback()
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py b/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py
index 40468bd2105..cc656440d3d 100644
--- a/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py
@@ -16,13 +16,14 @@
 from uuid import uuid4
 
 import pytest
-from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
 from onyx.db.llm import fetch_existing_llm_provider
 from onyx.db.llm import remove_llm_provider
 from onyx.db.llm import upsert_llm_provider
 from onyx.db.models import UserRole
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
 from onyx.llm.constants import LlmProviderNames
 from onyx.server.manage.llm.api import _mask_string
 from onyx.server.manage.llm.api import put_llm_provider
@@ -100,7 +101,7 @@ def test_blocks_api_base_change_without_key_change__multi_tenant(
                     api_base="https://attacker.example.com",
                 )
 
-                with pytest.raises(HTTPException) as exc_info:
+                with pytest.raises(OnyxError) as exc_info:
                     put_llm_provider(
                         llm_provider_upsert_request=update_request,
                         is_creation=False,
@@ -108,9 +109,9 @@ def test_blocks_api_base_change_without_key_change__multi_tenant(
                         db_session=db_session,
                     )
 
-                assert exc_info.value.status_code == 400
+                assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.detail
+                    exc_info.value.message
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
@@ -236,7 +237,7 @@ def test_blocks_clearing_api_base__multi_tenant(
                     api_base=None,
                 )
 
-                with pytest.raises(HTTPException) as exc_info:
+                with pytest.raises(OnyxError) as exc_info:
                     put_llm_provider(
                         llm_provider_upsert_request=update_request,
                         is_creation=False,
@@ -244,9 +245,9 @@ def test_blocks_clearing_api_base__multi_tenant(
                         db_session=db_session,
                     )
 
-                assert exc_info.value.status_code == 400
+                assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.detail
+                    exc_info.value.message
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
@@ -339,7 +340,7 @@ def test_blocks_custom_config_change_without_key_change__multi_tenant(
                     custom_config_changed=True,
                 )
 
-                with pytest.raises(HTTPException) as exc_info:
+                with pytest.raises(OnyxError) as exc_info:
                     put_llm_provider(
                         llm_provider_upsert_request=update_request,
                         is_creation=False,
@@ -347,9 +348,9 @@ def test_blocks_custom_config_change_without_key_change__multi_tenant(
                         db_session=db_session,
                     )
 
-                assert exc_info.value.status_code == 400
+                assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.detail
+                    exc_info.value.message
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
@@ -375,7 +376,7 @@ def test_blocks_adding_custom_config_without_key_change__multi_tenant(
                     custom_config_changed=True,
                 )
 
-                with pytest.raises(HTTPException) as exc_info:
+                with pytest.raises(OnyxError) as exc_info:
                     put_llm_provider(
                         llm_provider_upsert_request=update_request,
                         is_creation=False,
@@ -383,9 +384,9 @@ def test_blocks_adding_custom_config_without_key_change__multi_tenant(
                         db_session=db_session,
                     )
 
-                assert exc_info.value.status_code == 400
+                assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.detail
+                    exc_info.value.message
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
diff --git a/backend/tests/integration/tests/llm_provider/test_llm_provider.py b/backend/tests/integration/tests/llm_provider/test_llm_provider.py
index af1a1694618..c3893fc209c 100644
--- a/backend/tests/integration/tests/llm_provider/test_llm_provider.py
+++ b/backend/tests/integration/tests/llm_provider/test_llm_provider.py
@@ -427,7 +427,7 @@ def test_delete_default_llm_provider_rejected(reset: None) -> None:  # noqa: ARG
         headers=admin_user.headers,
     )
     assert delete_response.status_code == 400
-    assert "Cannot delete the default LLM provider" in delete_response.json()["detail"]
+    assert "Cannot delete the default LLM provider" in delete_response.json()["message"]
 
     # Verify provider still exists
     provider_data = _get_provider_by_id(admin_user, created_provider["id"])
@@ -673,8 +673,8 @@ def test_duplicate_provider_name_rejected(reset: None) -> None:  # noqa: ARG001
         headers=admin_user.headers,
         json=base_payload,
     )
-    assert response.status_code == 400
-    assert "already exists" in response.json()["detail"]
+    assert response.status_code == 409
+    assert "already exists" in response.json()["message"]
 
 
 def test_rename_provider_rejected(reset: None) -> None:  # noqa: ARG001
@@ -711,7 +711,7 @@ def test_rename_provider_rejected(reset: None) -> None:  # noqa: ARG001
         json=update_payload,
     )
     assert response.status_code == 400
-    assert "not currently supported" in response.json()["detail"]
+    assert "not currently supported" in response.json()["message"]
 
     # Verify no duplicate was created — only the original provider should exist
     provider = _get_provider_by_id(admin_user, provider_id)
diff --git a/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py b/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py
index 77924ae4e1a..6a1be7b157f 100644
--- a/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py
+++ b/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py
@@ -69,7 +69,7 @@ def test_unauthorized_persona_access_returns_403(
 
     # Should return 403 Forbidden
     assert response.status_code == 403
-    assert "don't have access to this assistant" in response.json()["detail"]
+    assert "don't have access to this assistant" in response.json()["message"]
 
 
 def test_authorized_persona_access_returns_filtered_providers(
@@ -245,4 +245,4 @@ def test_nonexistent_persona_returns_404(
 
     # Should return 404
     assert response.status_code == 404
-    assert "Persona not found" in response.json()["detail"]
+    assert "Persona not found" in response.json()["message"]

From 2d996e05a4e383637c535d6202728df7f98b6af3 Mon Sep 17 00:00:00 2001
From: Bo-Onyx <bo@onyx.app>
Date: Wed, 4 Mar 2026 14:52:49 -0800
Subject: [PATCH 089/267] chore(fe): opal button migration (#8864)

---
 web/src/app/admin/add-connector/page.tsx      |  6 +-
 web/src/app/admin/agents/PersonaTable.tsx     |  5 +-
 web/src/app/admin/api-key/OnyxApiKeyForm.tsx  |  2 +-
 web/src/app/admin/api-key/page.tsx            | 12 ++--
 .../app/admin/billing/BillingDetailsView.tsx  | 63 +++++++++----------
 web/src/app/admin/billing/CheckoutView.tsx    |  6 +-
 .../admin/billing/LicenseActivationCard.tsx   | 14 +++--
 web/src/app/admin/billing/PlansView.tsx       | 14 +++--
 web/src/app/admin/billing/page.tsx            |  2 +
 web/src/app/admin/bots/SlackBotUpdateForm.tsx | 10 +--
 web/src/app/admin/bots/SlackTokensForm.tsx    |  2 +-
 .../[bot-id]/SlackChannelConfigsTable.tsx     |  9 ++-
 .../channels/SlackChannelConfigFormFields.tsx |  4 +-
 .../document-processing/page.tsx              |  6 +-
 .../configuration/search/UpgradingPage.tsx    | 11 +++-
 .../app/admin/configuration/search/page.tsx   |  4 +-
 .../web-search/WebProviderSetupModal.tsx      |  6 +-
 .../admin/configuration/web-search/page.tsx   | 15 +++--
 .../connector/[ccPairId]/ConfigDisplay.tsx    | 14 +++--
 .../[ccPairId]/IndexAttemptErrorsModal.tsx    |  1 +
 .../[ccPairId]/InlineFileManagement.tsx       | 22 +++----
 .../connector/[ccPairId]/ReIndexModal.tsx     |  2 +-
 .../app/admin/connector/[ccPairId]/page.tsx   |  4 +-
 .../[connector]/AddConnectorPage.tsx          |  4 +-
 .../[connector]/ConnectorWrapper.tsx          |  1 +
 .../connectors/[connector]/NavigationRow.tsx  | 12 ++--
 .../[connector]/oauth/finalize/page.tsx       |  2 +-
 .../connectors/[connector]/pages/Advanced.tsx |  4 +-
 .../[connector]/pages/gdrive/Credential.tsx   |  6 +-
 .../[connector]/pages/gmail/Credential.tsx    | 11 ++--
 web/src/app/admin/debug/page.tsx              |  6 +-
 .../app/admin/discord-bot/BotConfigCard.tsx   |  4 +-
 .../admin/discord-bot/DiscordGuildsTable.tsx  |  6 +-
 .../app/admin/discord-bot/[guild-id]/page.tsx | 10 ++-
 .../admin/document-index-migration/page.tsx   |  1 +
 .../sets/DocumentSetCreationForm.tsx          |  1 +
 .../EmbeddingModelSelectionForm.tsx           |  4 +-
 .../admin/embeddings/RerankingFormPage.tsx    |  2 +-
 .../embeddings/modals/AlreadyPickedModal.tsx  |  2 +-
 .../modals/ChangeCredentialsModal.tsx         |  2 +
 .../modals/DeleteCredentialsModal.tsx         |  6 +-
 .../modals/InstantSwitchConfirmModal.tsx      |  4 +-
 .../embeddings/modals/ModelSelectionModal.tsx |  4 +-
 .../modals/ProviderCreationModal.tsx          | 23 +++----
 .../embeddings/modals/SelectModelModal.tsx    |  4 +-
 .../embeddings/pages/EmbeddingFormPage.tsx    | 46 ++++++++------
 .../embeddings/pages/OpenEmbeddingPage.tsx    |  1 +
 .../admin/indexing/status/FilterComponent.tsx | 17 ++---
 .../status/SearchAndFilterControls.tsx        |  2 +-
 web/src/app/admin/indexing/status/page.tsx    |  2 +-
 web/src/app/admin/kg/KGEntityTypes.tsx        |  7 +--
 web/src/app/admin/kg/page.tsx                 |  4 +-
 .../CreateRateLimitModal.tsx                  |  2 +-
 web/src/app/admin/users/page.tsx              |  4 +-
 web/src/app/app/components/AppPopup.tsx       |  2 +-
 .../projects/ProjectContextPanel.tsx          |  7 ++-
 web/src/app/app/message/Resubmit.tsx          |  8 +--
 .../primitives/TimelineStepContent.tsx        |  7 +--
 web/src/app/auth/create-account/page.tsx      |  6 +-
 web/src/app/auth/error/page.tsx               |  4 +-
 web/src/app/auth/forgot-password/page.tsx     |  8 +--
 web/src/app/auth/impersonate/page.tsx         |  4 +-
 web/src/app/auth/login/EmailPasswordForm.tsx  |  6 +-
 web/src/app/auth/login/LoginPage.tsx          |  2 +-
 web/src/app/auth/login/SignInButton.tsx       | 12 ++--
 web/src/app/auth/reset-password/page.tsx      |  8 +--
 web/src/app/craft/components/ChatPanel.tsx    |  1 +
 web/src/app/craft/components/FileBrowser.tsx  | 14 +++--
 .../app/craft/components/FilePreviewModal.tsx | 10 ++-
 web/src/app/craft/components/InputBar.tsx     |  1 +
 web/src/app/craft/components/ShareButton.tsx  | 15 +++--
 web/src/app/craft/components/SideBar.tsx      | 11 ++--
 .../components/output-panel/ArtifactsTab.tsx  | 14 ++---
 .../craft/components/output-panel/UrlBar.tsx  |  8 +--
 .../components/ConfigureConnectorModal.tsx    |  6 +-
 .../v1/configure/components/ConnectorCard.tsx |  3 +-
 .../components/ConnectorConfigStep.tsx        | 13 ++--
 .../components/CreateCredentialInline.tsx     | 11 ++--
 .../configure/components/CredentialStep.tsx   |  5 +-
 .../configure/components/UserLibraryModal.tsx | 23 +++----
 web/src/app/craft/v1/configure/page.tsx       |  4 +-
 .../admin/billing/BillingInformationPage.tsx  |  6 +-
 web/src/app/ee/admin/groups/UserEditor.tsx    |  1 +
 .../ee/admin/groups/UserGroupCreationForm.tsx |  1 +
 .../app/ee/admin/groups/UserGroupsTable.tsx   |  1 +
 .../groups/[groupId]/AddConnectorForm.tsx     |  2 +-
 .../admin/groups/[groupId]/GroupDisplay.tsx   | 15 ++---
 .../CustomAnalyticsUpdateForm.tsx             |  9 ++-
 .../query-history/KickoffCSVExport.tsx        |  1 +
 .../query-history/QueryHistoryTable.tsx       |  4 +-
 .../admin/performance/usage/UsageReports.tsx  | 44 ++++++-------
 .../StandardAnswerCreationForm.tsx            |  1 +
 .../admin/theme/AppearanceThemeSettings.tsx   |  6 +-
 web/src/app/ee/admin/theme/page.tsx           |  2 +-
 web/src/app/nrf/NRFChrome.tsx                 |  6 +-
 web/src/app/nrf/NRFPage.tsx                   | 22 ++++---
 .../app/nrf/side-panel/SidePanelHeader.tsx    | 10 +--
 web/src/components/AdvancedOptionsToggle.tsx  |  1 +
 .../components/EditableStringFieldDisplay.tsx |  2 +
 web/src/components/GenericMultiSelect.tsx     |  1 +
 web/src/components/admin/ClientLayout.tsx     |  4 +-
 .../connectors/AccessTypeGroupSelector.tsx    |  7 +--
 .../federated/FederatedConnectorForm.tsx      |  7 ++-
 web/src/components/admin/users/BulkAdd.tsx    |  1 +
 .../admin/users/PendingUsersTable.tsx         |  6 +-
 .../admin/users/ResetPasswordModal.tsx        |  1 +
 .../admin/users/SignedUpUserTable.tsx         |  1 +
 .../users/buttons/DeactivateUserButton.tsx    |  1 +
 .../admin/users/buttons/DeleteUserButton.tsx  |  1 +
 .../admin/users/buttons/InviteUserButton.tsx  |  2 +-
 .../users/buttons/LeaveOrganizationButton.tsx |  1 +
 .../components/chat/FederatedOAuthModal.tsx   |  4 +-
 web/src/components/chat/MCPApiKeyModal.tsx    |  8 ++-
 .../credentials/actions/CreateCredential.tsx  |  8 ++-
 .../actions/CreateStdOAuthCredential.tsx      |  2 +-
 .../credentials/actions/EditCredential.tsx    | 11 +---
 .../credentials/actions/ModifyCredential.tsx  | 37 ++++-------
 .../AdminDateRangeSelector.tsx                | 10 +--
 .../embedding/CustomEmbeddingModelForm.tsx    |  1 +
 .../components/embedding/CustomModelForm.tsx  |  1 +
 .../embedding/FailedReIndexAttempts.tsx       |  6 +-
 .../errorPages/AccessRestrictedPage.tsx       |  4 +-
 .../components/modals/AddInstructionModal.tsx |  4 +-
 .../components/modals/ConfirmEntityModal.tsx  |  4 +-
 .../components/modals/CreateProjectModal.tsx  |  4 +-
 .../components/modals/EditPropertyModal.tsx   |  2 +-
 .../components/modals/GenericConfirmModal.tsx |  2 +-
 .../modals/MoveCustomAgentChatModal.tsx       |  6 +-
 web/src/components/modals/NewTeamModal.tsx    | 16 ++---
 web/src/components/modals/NoAgentModal.tsx    |  4 +-
 web/src/components/modals/ProviderModal.tsx   | 10 ++-
 web/src/components/modals/UserFilesModal.tsx  |  9 ++-
 .../components/oauth/OAuthCallbackPage.tsx    |  4 +-
 .../sidebar/ChatSessionMorePopup.tsx          |  4 +-
 web/src/layouts/app-layouts.tsx               | 10 +--
 web/src/refresh-components/Calendar.tsx       |  1 +
 .../buttons/AttachmentButton.tsx              |  1 +
 .../source-tag/SourceTagDetailsCard.tsx       | 16 +++--
 web/src/refresh-components/cards/Select.tsx   | 10 ++-
 .../inputs/InputDatePicker.tsx                |  4 +-
 .../refresh-components/inputs/InputImage.tsx  |  1 +
 .../inputs/InputKeyValue.tsx                  |  9 ++-
 .../refresh-components/inputs/InputTypeIn.tsx |  4 +-
 .../inputs/ListFieldInput.tsx                 |  1 +
 .../refresh-components/messages/Message.tsx   |  2 +
 .../modals/MemoriesModal.tsx                  |  9 ++-
 .../ActionsPopover/ActionLineItem.tsx         |  1 +
 .../popovers/FilePickerPopover.tsx            |  1 +
 web/src/refresh-pages/AgentEditorPage.tsx     | 41 ++++++------
 web/src/refresh-pages/SettingsPage.tsx        | 32 +++++-----
 web/src/sections/AppHealthBanner.tsx          |  2 +-
 web/src/sections/actions/ActionCardHeader.tsx |  1 +
 web/src/sections/actions/Actionbar.tsx        |  4 +-
 web/src/sections/actions/Actions.tsx          | 21 +++----
 web/src/sections/actions/MCPActionCard.tsx    | 13 ++--
 .../sections/actions/OpenApiActionCard.tsx    |  4 +-
 web/src/sections/actions/ToolsList.tsx        | 12 ++--
 web/src/sections/actions/ToolsSection.tsx     |  4 +-
 .../actions/modals/AddMCPServerModal.tsx      | 10 ++-
 .../actions/modals/AddOpenAPIActionModal.tsx  | 14 ++---
 .../actions/modals/DisconnectEntityModal.tsx  | 15 +++--
 .../actions/modals/MCPAuthenticationModal.tsx |  7 +--
 .../modals/OpenAPIAuthenticationModal.tsx     | 10 +--
 web/src/sections/cards/AgentCard.tsx          |  8 ++-
 .../sections/knowledge/AgentKnowledgePane.tsx | 13 ++--
 .../knowledge/SourceHierarchyBrowser.tsx      | 19 +++---
 web/src/sections/modals/AgentViewerModal.tsx  |  4 +-
 web/src/sections/modals/FeedbackModal.tsx     |  4 +-
 web/src/sections/modals/NewTenantModal.tsx    |  6 +-
 web/src/sections/modals/ShareAgentModal.tsx   | 19 ++++--
 .../sections/modals/ShareChatSessionModal.tsx | 12 ++--
 web/src/sections/modals/TextViewModal.tsx     |  9 ++-
 .../sections/modals/llmConfig/CustomModal.tsx |  1 +
 .../llmConfig/components/DisplayModels.tsx    |  3 +
 .../components/FetchModelsButton.tsx          |  2 +-
 .../components/FormActionButtons.tsx          |  5 +-
 .../llmConfig/components/FormWrapper.tsx      | 10 +--
 .../onboarding/components/LLMProviderCard.tsx |  1 +
 .../onboarding/components/NonAdminStep.tsx    |  6 +-
 .../components/OnboardingHeader.tsx           |  5 +-
 .../sections/onboarding/steps/FinalStep.tsx   |  4 +-
 web/src/sections/onboarding/steps/LLMStep.tsx |  4 +-
 .../sections/onboarding/steps/NameStep.tsx    |  1 +
 web/src/sections/settings/Memories.tsx        |  6 +-
 web/src/sections/sidebar/AgentButton.tsx      |  1 +
 web/src/sections/sidebar/ChatButton.tsx       |  8 +--
 .../sections/sidebar/ProjectFolderButton.tsx  |  8 +--
 187 files changed, 729 insertions(+), 669 deletions(-)

diff --git a/web/src/app/admin/add-connector/page.tsx b/web/src/app/admin/add-connector/page.tsx
index 4b1ef6fb132..8a03053c7e7 100644
--- a/web/src/app/admin/add-connector/page.tsx
+++ b/web/src/app/admin/add-connector/page.tsx
@@ -2,7 +2,7 @@
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { SourceCategory, SourceMetadata } from "@/lib/search/interfaces";
 import { listSourceMetadata } from "@/lib/sources";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   useCallback,
   useContext,
@@ -254,9 +254,7 @@ export default function Page() {
         icon={route.icon}
         title={route.title}
         rightChildren={
-          <Button href="/admin/indexing/status" primary>
-            See Connectors
-          </Button>
+          <Button href="/admin/indexing/status">See Connectors</Button>
         }
         separator
       />
diff --git a/web/src/app/admin/agents/PersonaTable.tsx b/web/src/app/admin/agents/PersonaTable.tsx
index a3b518a1f50..f32d3a0093c 100644
--- a/web/src/app/admin/agents/PersonaTable.tsx
+++ b/web/src/app/admin/agents/PersonaTable.tsx
@@ -16,9 +16,8 @@ import {
 } from "./lib";
 import { FiEdit2 } from "react-icons/fi";
 import { useUser } from "@/providers/UserProvider";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
 import { SvgAlertCircle, SvgTrash } from "@opal/icons";
 import type { Route } from "next";
 
@@ -300,7 +299,7 @@ export function PersonasTable({
               <div key="edit" className="flex">
                 <div className="mr-auto my-auto">
                   {!persona.builtin_persona && isEditable ? (
-                    <OpalButton
+                    <Button
                       icon={SvgTrash}
                       prominence="tertiary"
                       onClick={() => openDeleteModal(persona)}
diff --git a/web/src/app/admin/api-key/OnyxApiKeyForm.tsx b/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
index 0a24b062866..07a80d3df94 100644
--- a/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
+++ b/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
@@ -2,7 +2,7 @@ import { Form, Formik } from "formik";
 import { toast } from "@/hooks/useToast";
 import { createApiKey, updateApiKey } from "./lib";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import InputComboBox from "@/refresh-components/inputs/InputComboBox";
diff --git a/web/src/app/admin/api-key/page.tsx b/web/src/app/admin/api-key/page.tsx
index f08bc637495..356231220cb 100644
--- a/web/src/app/admin/api-key/page.tsx
+++ b/web/src/app/admin/api-key/page.tsx
@@ -27,7 +27,7 @@ import {
   DISCORD_SERVICE_API_KEY_NAME,
 } from "@/app/admin/api-key/types";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import Text from "@/refresh-components/texts/Text";
 import { SvgEdit, SvgKey, SvgRefreshCw } from "@opal/icons";
@@ -161,11 +161,11 @@ function Main() {
                 <TableRow key={apiKey.api_key_id}>
                   <TableCell>
                     <Button
-                      internal
+                      prominence="internal"
                       onClick={() => handleEdit(apiKey)}
-                      leftIcon={SvgEdit}
+                      icon={SvgEdit}
                     >
-                      {apiKey.api_key_name || <i>null</i>}
+                      {apiKey.api_key_name || "null"}
                     </Button>
                   </TableCell>
                   <TableCell className="max-w-64">
@@ -176,8 +176,8 @@ function Main() {
                   </TableCell>
                   <TableCell>
                     <Button
-                      internal
-                      leftIcon={SvgRefreshCw}
+                      prominence="internal"
+                      icon={SvgRefreshCw}
                       onClick={async () => {
                         setKeyIsGenerating(true);
                         const response = await regenerateApiKey(apiKey);
diff --git a/web/src/app/admin/billing/BillingDetailsView.tsx b/web/src/app/admin/billing/BillingDetailsView.tsx
index 775c37f0e13..76a68e4f419 100644
--- a/web/src/app/admin/billing/BillingDetailsView.tsx
+++ b/web/src/app/admin/billing/BillingDetailsView.tsx
@@ -7,6 +7,7 @@ import { Content } from "@opal/layouts";
 import * as InputLayouts from "@/layouts/input-layouts";
 import Card from "@/refresh-components/cards/Card";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import Message from "@/refresh-components/messages/Message";
 import InfoBlock from "@/refresh-components/messages/InfoBlock";
@@ -244,25 +245,20 @@ function SubscriptionCard({
               to make changes.
             </Text>
           ) : disabled ? (
-            <Button
-              main
-              secondary
+            <OpalButton
+              prominence="secondary"
               onClick={handleReconnect}
               rightIcon={SvgArrowRight}
               disabled={isReconnecting}
             >
               {isReconnecting ? "Connecting..." : "Connect to Stripe"}
-            </Button>
+            </OpalButton>
           ) : (
-            <Button
-              main
-              primary
-              onClick={handleManagePlan}
-              rightIcon={SvgExternalLink}
-            >
+            <OpalButton onClick={handleManagePlan} rightIcon={SvgExternalLink}>
               Manage Plan
-            </Button>
+            </OpalButton>
           )}
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <Button tertiary onClick={onViewPlans} className="billing-text-link">
             <Text secondaryBody text03>
               View Plan Details
@@ -379,9 +375,13 @@ function SeatsCard({
             sizePreset="main-content"
             variant="section"
           />
-          <Button main secondary onClick={handleCancel} disabled={isSubmitting}>
+          <OpalButton
+            prominence="secondary"
+            onClick={handleCancel}
+            disabled={isSubmitting}
+          >
             Cancel
-          </Button>
+          </OpalButton>
         </Section>
 
         <div className="billing-content-area">
@@ -463,16 +463,14 @@ function SeatsCard({
               No changes to your billing.
             </Text>
           )}
-          <Button
-            main
-            primary
+          <OpalButton
             onClick={handleConfirm}
             disabled={
               isSubmitting || newSeatCount === totalSeats || isBelowMinimum
             }
           >
             {isSubmitting ? "Saving..." : "Confirm Change"}
-          </Button>
+          </OpalButton>
         </Section>
       </Card>
     );
@@ -502,19 +500,22 @@ function SeatsCard({
           height="auto"
           width="auto"
         >
-          <Button main tertiary href="/admin/users" leftIcon={SvgExternalLink}>
+          <OpalButton
+            prominence="tertiary"
+            href="/admin/users"
+            icon={SvgExternalLink}
+          >
             View Users
-          </Button>
+          </OpalButton>
           {!hideUpdateSeats && (
-            <Button
-              main
-              secondary
+            <OpalButton
+              prominence="secondary"
               onClick={handleStartEdit}
-              leftIcon={SvgPlus}
+              icon={SvgPlus}
               disabled={isLoadingUsers || disabled || !billing}
             >
               Update Seats
-            </Button>
+            </OpalButton>
           )}
         </Section>
       </Section>
@@ -566,14 +567,13 @@ function PaymentSection({ billing }: { billing: BillingInformation }) {
                 title="Visa ending in 1234"
                 description="Payment method"
               />
-              <Button
-                main
-                tertiary
+              <OpalButton
+                prominence="tertiary"
                 onClick={handleOpenPortal}
                 rightIcon={SvgExternalLink}
               >
                 Update
-              </Button>
+              </OpalButton>
             </Section>
           </Card>
           {lastPaymentDate && (
@@ -589,14 +589,13 @@ function PaymentSection({ billing }: { billing: BillingInformation }) {
                   title={lastPaymentDate}
                   description="Last payment"
                 />
-                <Button
-                  main
-                  tertiary
+                <OpalButton
+                  prominence="tertiary"
                   onClick={handleOpenPortal}
                   rightIcon={SvgExternalLink}
                 >
                   View Invoice
-                </Button>
+                </OpalButton>
               </Section>
             </Card>
           )}
diff --git a/web/src/app/admin/billing/CheckoutView.tsx b/web/src/app/admin/billing/CheckoutView.tsx
index 73583d4e508..9b22cc01374 100644
--- a/web/src/app/admin/billing/CheckoutView.tsx
+++ b/web/src/app/admin/billing/CheckoutView.tsx
@@ -3,7 +3,7 @@
 import { useState, useMemo, useEffect } from "react";
 import { Section } from "@/layouts/general-layouts";
 import * as InputLayouts from "@/layouts/input-layouts";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import Card from "@/refresh-components/cards/Card";
 import Separator from "@/refresh-components/Separator";
@@ -176,7 +176,7 @@ export default function CheckoutView({ onAdjustPlan }: CheckoutViewProps) {
             Business
           </Text>
         </Section>
-        <Button secondary onClick={onAdjustPlan}>
+        <Button prominence="secondary" onClick={onAdjustPlan}>
           Adjust Plan
         </Button>
       </Section>
@@ -262,7 +262,7 @@ export default function CheckoutView({ onAdjustPlan }: CheckoutViewProps) {
           // Empty div to maintain space-between alignment
           <div></div>
         )}
-        <Button main primary onClick={handleSubmit} disabled={isSubmitting}>
+        <Button onClick={handleSubmit} disabled={isSubmitting}>
           {isSubmitting ? "Loading..." : "Continue to Payment"}
         </Button>
       </Section>
diff --git a/web/src/app/admin/billing/LicenseActivationCard.tsx b/web/src/app/admin/billing/LicenseActivationCard.tsx
index b1cc841cb5f..5c63469506d 100644
--- a/web/src/app/admin/billing/LicenseActivationCard.tsx
+++ b/web/src/app/admin/billing/LicenseActivationCard.tsx
@@ -2,7 +2,7 @@
 
 import { useState } from "react";
 import Card from "@/refresh-components/cards/Card";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import InputFile from "@/refresh-components/inputs/InputFile";
 import { Section } from "@/layouts/general-layouts";
@@ -119,11 +119,11 @@ export default function LicenseActivationCard({
             </Text>
           </Section>
           <Section flexDirection="row" gap={0.5} height="auto" width="auto">
-            <Button main secondary onClick={() => setShowInput(true)}>
+            <Button prominence="secondary" onClick={() => setShowInput(true)}>
               Update Key
             </Button>
             {!hideClose && (
-              <Button main tertiary onClick={handleClose}>
+              <Button prominence="tertiary" onClick={handleClose}>
                 Close
               </Button>
             )}
@@ -146,7 +146,11 @@ export default function LicenseActivationCard({
           <Text headingH3>
             {hasLicense ? "Update License Key" : "Activate License Key"}
           </Text>
-          <Button secondary onClick={handleClose} disabled={isActivating}>
+          <Button
+            prominence="secondary"
+            onClick={handleClose}
+            disabled={isActivating}
+          >
             Cancel
           </Button>
         </Section>
@@ -219,8 +223,6 @@ export default function LicenseActivationCard({
       {/* Footer */}
       <Section flexDirection="row" justifyContent="end" padding={1}>
         <Button
-          main
-          primary
           onClick={handleActivate}
           disabled={isActivating || !licenseKey.trim() || success}
         >
diff --git a/web/src/app/admin/billing/PlansView.tsx b/web/src/app/admin/billing/PlansView.tsx
index 05014bad5a2..928e0b9340f 100644
--- a/web/src/app/admin/billing/PlansView.tsx
+++ b/web/src/app/admin/billing/PlansView.tsx
@@ -21,6 +21,7 @@ import "@/app/admin/billing/billing.css";
 import type { IconProps } from "@opal/types";
 import Card from "@/refresh-components/cards/Card";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { Section } from "@/layouts/general-layouts";
 
@@ -146,26 +147,27 @@ function PlanCard({
         {/* Button */}
         <div className="plan-card-button">
           {isCurrentPlan ? (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <Button tertiary transient className="pointer-events-none">
               <Text mainUiAction text03>
                 Your Current Plan
               </Text>
             </Button>
           ) : href ? (
-            <Button
-              main
-              secondary
+            <OpalButton
+              prominence="secondary"
               href={href}
               target="_blank"
               rel="noopener noreferrer"
             >
               {buttonLabel}
-            </Button>
+            </OpalButton>
           ) : onClick ? (
-            <Button main primary onClick={onClick} leftIcon={ButtonIcon}>
+            <OpalButton onClick={onClick} icon={ButtonIcon}>
               {buttonLabel}
-            </Button>
+            </OpalButton>
           ) : (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <Button tertiary transient className="pointer-events-none">
               <Text mainUiAction text03>
                 Included in your plan
diff --git a/web/src/app/admin/billing/page.tsx b/web/src/app/admin/billing/page.tsx
index 370fcc6b948..3f41014ce67 100644
--- a/web/src/app/admin/billing/page.tsx
+++ b/web/src/app/admin/billing/page.tsx
@@ -66,6 +66,7 @@ function FooterLinks({
           <Text secondaryBody text03>
             Have a license key?
           </Text>
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <Button action tertiary onClick={onActivateLicense}>
             <Text secondaryBody text05 className="underline">
               {licenseText}
@@ -73,6 +74,7 @@ function FooterLinks({
           </Button>
         </>
       )}
+      {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
       <Button
         action
         tertiary
diff --git a/web/src/app/admin/bots/SlackBotUpdateForm.tsx b/web/src/app/admin/bots/SlackBotUpdateForm.tsx
index a4fe3830cbf..818bee61dd2 100644
--- a/web/src/app/admin/bots/SlackBotUpdateForm.tsx
+++ b/web/src/app/admin/bots/SlackBotUpdateForm.tsx
@@ -10,7 +10,7 @@ import { SourceIcon } from "@/components/SourceIcon";
 import { EditableStringFieldDisplay } from "@/components/EditableStringFieldDisplay";
 import { deleteSlackBot } from "./new/lib";
 import GenericConfirmModal from "@/components/modals/GenericConfirmModal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { cn } from "@/lib/utils";
 import { SvgChevronDownSmall, SvgTrash } from "@opal/icons";
 
@@ -106,20 +106,20 @@ export const ExistingSlackBotForm = ({
         <div className="flex flex-col" ref={dropdownRef}>
           <div className="flex items-center gap-4">
             <Button
-              leftIcon={({ className }) => (
+              prominence="secondary"
+              icon={({ className }) => (
                 <SvgChevronDownSmall
                   className={cn(className, !isExpanded && "-rotate-90")}
                 />
               )}
               onClick={() => setIsExpanded(!isExpanded)}
-              secondary
             >
               Update Tokens
             </Button>
             <Button
-              danger
+              variant="danger"
               onClick={() => setShowDeleteModal(true)}
-              leftIcon={SvgTrash}
+              icon={SvgTrash}
             >
               Delete
             </Button>
diff --git a/web/src/app/admin/bots/SlackTokensForm.tsx b/web/src/app/admin/bots/SlackTokensForm.tsx
index 32d22679590..b831e0fb316 100644
--- a/web/src/app/admin/bots/SlackTokensForm.tsx
+++ b/web/src/app/admin/bots/SlackTokensForm.tsx
@@ -4,7 +4,7 @@ import { TextFormField } from "@/components/Field";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { createSlackBot, updateSlackBot } from "./new/lib";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Separator from "@/refresh-components/Separator";
 import { useEffect } from "react";
 import { DOCS_ADMINS_PATH } from "@/lib/constants";
diff --git a/web/src/app/admin/bots/[bot-id]/SlackChannelConfigsTable.tsx b/web/src/app/admin/bots/[bot-id]/SlackChannelConfigsTable.tsx
index 05684b3479b..f06e95198e7 100644
--- a/web/src/app/admin/bots/[bot-id]/SlackChannelConfigsTable.tsx
+++ b/web/src/app/admin/bots/[bot-id]/SlackChannelConfigsTable.tsx
@@ -17,9 +17,8 @@ import type { Route } from "next";
 import { useState } from "react";
 import { deleteSlackChannelConfig, isPersonaASlackBotPersona } from "./lib";
 import { Card } from "@/components/ui/card";
-import Button from "@/refresh-components/buttons/Button";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import { SvgSettings, SvgTrash } from "@opal/icons";
 const numToDisplay = 50;
 
@@ -45,11 +44,11 @@ export default function SlackChannelConfigsTable({
     <div className="space-y-8">
       <div className="flex justify-between items-center mb-6">
         <Button
+          prominence="secondary"
           onClick={() => {
             window.location.href = `/admin/bots/${slackBotId}/channels/${defaultConfig?.id}`;
           }}
-          secondary
-          leftIcon={SvgSettings}
+          icon={SvgSettings}
         >
           Edit Default Configuration
         </Button>
@@ -121,7 +120,7 @@ export default function SlackChannelConfigsTable({
                         </div>
                       </TableCell>
                       <TableCell onClick={(e) => e.stopPropagation()}>
-                        <OpalButton
+                        <Button
                           onClick={async (e) => {
                             e.stopPropagation();
                             const response = await deleteSlackChannelConfig(
diff --git a/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx b/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx
index d45f4bedb60..b39c389df12 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx
@@ -11,7 +11,7 @@ import {
   TextArrayField,
   TextFormField,
 } from "@/components/Field";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import DocumentSetCard from "@/sections/cards/DocumentSetCard";
 import CollapsibleSection from "@/app/admin/agents/CollapsibleSection";
@@ -598,7 +598,7 @@ export function SlackChannelConfigFormFields({
           </TooltipProvider>
         )}
         <Button type="submit">{isUpdate ? "Update" : "Create"}</Button>
-        <Button secondary onClick={() => router.back()}>
+        <Button prominence="secondary" onClick={() => router.back()}>
           Cancel
         </Button>
       </div>
diff --git a/web/src/app/admin/configuration/document-processing/page.tsx b/web/src/app/admin/configuration/document-processing/page.tsx
index 65ccc9e85db..bf4a42b2c75 100644
--- a/web/src/app/admin/configuration/document-processing/page.tsx
+++ b/web/src/app/admin/configuration/document-processing/page.tsx
@@ -2,7 +2,7 @@
 
 import { useState } from "react";
 import CardSection from "@/components/admin/CardSection";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useSWR from "swr";
 import { ThreeDotsLoader } from "@/components/Loading";
@@ -129,7 +129,7 @@ function Main() {
             <div className="flex flex-col gap-2 desktop:flex-row desktop:items-center desktop:gap-2">
               {isApiKeySet ? (
                 <>
-                  <Button onClick={handleDelete} danger>
+                  <Button variant="danger" onClick={handleDelete}>
                     Delete API Key
                   </Button>
                   <Text as="p" mainContentBody text04 className="desktop:mt-0">
@@ -137,7 +137,7 @@ function Main() {
                   </Text>
                 </>
               ) : (
-                <Button onClick={handleSave} action>
+                <Button variant="action" onClick={handleSave}>
                   Save API Key
                 </Button>
               )}
diff --git a/web/src/app/admin/configuration/search/UpgradingPage.tsx b/web/src/app/admin/configuration/search/UpgradingPage.tsx
index 5d957b0f81d..7ec404e7796 100644
--- a/web/src/app/admin/configuration/search/UpgradingPage.tsx
+++ b/web/src/app/admin/configuration/search/UpgradingPage.tsx
@@ -10,6 +10,7 @@ import {
 import Text from "@/components/ui/text";
 import Title from "@/components/ui/title";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import { useMemo, useState } from "react";
 import useSWR, { mutate } from "swr";
 import { ReindexingProgressTable } from "../../../../components/embedding/ReindexingProgressTable";
@@ -145,10 +146,13 @@ export default function UpgradingPage({
               </div>
             </Modal.Body>
             <Modal.Footer>
-              <Button onClick={onCancel}>Confirm</Button>
-              <Button onClick={() => setIsCancelling(false)} secondary>
+              <OpalButton onClick={onCancel}>Confirm</OpalButton>
+              <OpalButton
+                prominence="secondary"
+                onClick={() => setIsCancelling(false)}
+              >
                 Cancel
-              </Button>
+              </OpalButton>
             </Modal.Footer>
           </Modal.Content>
         </Modal>
@@ -163,6 +167,7 @@ export default function UpgradingPage({
               {futureEmbeddingModel.model_name}
             </div>
 
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               danger
               className="mt-4"
diff --git a/web/src/app/admin/configuration/search/page.tsx b/web/src/app/admin/configuration/search/page.tsx
index 25cef77e892..031e39eabec 100644
--- a/web/src/app/admin/configuration/search/page.tsx
+++ b/web/src/app/admin/configuration/search/page.tsx
@@ -5,7 +5,7 @@ import { errorHandlingFetcher } from "@/lib/fetcher";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Text from "@/components/ui/text";
 import Title from "@/components/ui/title";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import useSWR from "swr";
 import { ModelPreview } from "@/components/embedding/ModelSelector";
 import {
@@ -130,7 +130,7 @@ function Main() {
           </CardSection>
 
           <div className="mt-4">
-            <Button action href="/admin/embeddings">
+            <Button variant="action" href="/admin/embeddings">
               Update Search Settings
             </Button>
           </div>
diff --git a/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx b/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx
index 40303da7903..0ba6e8e7401 100644
--- a/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx
+++ b/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx
@@ -6,7 +6,7 @@ import { FormField } from "@/refresh-components/form/FormField";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 
 import { SvgArrowExchange, SvgOnyxLogo } from "@opal/icons";
 import type { IconProps } from "@opal/types";
@@ -244,13 +244,11 @@ export const WebProviderSetupModal = memo(
             )}
           </Modal.Body>
           <Modal.Footer>
-            <Button type="button" main secondary onClick={onClose}>
+            <Button prominence="secondary" type="button" onClick={onClose}>
               Cancel
             </Button>
             <Button
               type="button"
-              main
-              primary
               disabled={!canConnect || isProcessing}
               onClick={onConnect}
             >
diff --git a/web/src/app/admin/configuration/web-search/page.tsx b/web/src/app/admin/configuration/web-search/page.tsx
index f2df18db974..12d6712940b 100644
--- a/web/src/app/admin/configuration/web-search/page.tsx
+++ b/web/src/app/admin/configuration/web-search/page.tsx
@@ -91,6 +91,7 @@ function HoverIconButton({
 }: HoverIconButtonProps) {
   return (
     <div onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+      {/* TODO(@raunakab): migrate to opal Button once HoverIconButtonProps typing is resolved */}
       <Button {...buttonProps} rightIcon={isHovered ? SvgX : SvgCheckSquare}>
         {children}
       </Button>
@@ -1010,9 +1011,8 @@ export default function Page() {
                             {buttonState.label}
                           </HoverIconButton>
                         ) : (
-                          <Button
-                            action={false}
-                            tertiary
+                          <OpalButton
+                            prominence="tertiary"
                             disabled={
                               buttonState.disabled || !buttonState.onClick
                             }
@@ -1029,7 +1029,7 @@ export default function Page() {
                             }
                           >
                             {buttonState.label}
-                          </Button>
+                          </OpalButton>
                         )}
                       </div>
                     </div>
@@ -1202,9 +1202,8 @@ export default function Page() {
                           {buttonState.label}
                         </HoverIconButton>
                       ) : (
-                        <Button
-                          action={false}
-                          tertiary
+                        <OpalButton
+                          prominence="tertiary"
                           disabled={
                             buttonState.disabled || !buttonState.onClick
                           }
@@ -1221,7 +1220,7 @@ export default function Page() {
                           }
                         >
                           {buttonState.label}
-                        </Button>
+                        </OpalButton>
                       )}
                     </div>
                   </div>
diff --git a/web/src/app/admin/connector/[ccPairId]/ConfigDisplay.tsx b/web/src/app/admin/connector/[ccPairId]/ConfigDisplay.tsx
index fc68ea80603..f7b92e42cef 100644
--- a/web/src/app/admin/connector/[ccPairId]/ConfigDisplay.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/ConfigDisplay.tsx
@@ -5,8 +5,7 @@ import { useState } from "react";
 import { ValidSources } from "@/lib/types";
 import { Section } from "@/layouts/general-layouts";
 import Text from "@/refresh-components/texts/Text";
-import IconButton from "@/refresh-components/buttons/IconButton";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Separator from "@/refresh-components/Separator";
 import { SvgChevronUp, SvgChevronDown, SvgEdit } from "@opal/icons";
 import Truncated from "@/refresh-components/texts/Truncated";
@@ -119,16 +118,21 @@ function ConfigItem({ label, value, onEdit }: ConfigItemProps) {
 
         {isExpandable && (
           <Button
-            tertiary
+            prominence="tertiary"
             size="md"
-            leftIcon={isExpanded ? SvgChevronUp : SvgChevronDown}
+            icon={isExpanded ? SvgChevronUp : SvgChevronDown}
             onClick={() => setIsExpanded(!isExpanded)}
           >
             {isExpanded ? "Show less" : `Show all (${value.length} items)`}
           </Button>
         )}
         {onEdit && (
-          <IconButton icon={SvgEdit} tertiary onClick={onEdit} tooltip="Edit" />
+          <Button
+            prominence="tertiary"
+            icon={SvgEdit}
+            onClick={onEdit}
+            tooltip="Edit"
+          />
         )}
       </Section>
     </Section>
diff --git a/web/src/app/admin/connector/[ccPairId]/IndexAttemptErrorsModal.tsx b/web/src/app/admin/connector/[ccPairId]/IndexAttemptErrorsModal.tsx
index a75adf8e94d..30fe45d2fb2 100644
--- a/web/src/app/admin/connector/[ccPairId]/IndexAttemptErrorsModal.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/IndexAttemptErrorsModal.tsx
@@ -229,6 +229,7 @@ export default function IndexAttemptErrorsModal({
             <div className="flex w-full">
               <div className="flex gap-2 ml-auto">
                 {hasUnresolvedErrors && !isResolvingErrors && (
+                  // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
                   <Button
                     onClick={onResolveAll}
                     className="ml-4 whitespace-nowrap"
diff --git a/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx b/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx
index fbac4a88fb4..5550b3df3d4 100644
--- a/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx
@@ -1,8 +1,7 @@
 "use client";
 
 import { useState, useRef } from "react";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import {
   Table,
   TableBody,
@@ -176,26 +175,25 @@ export default function InlineFileManagement({
         <div className="flex gap-2">
           {!isEditing ? (
             <Button
+              prominence="secondary"
               onClick={() => setIsEditing(true)}
-              secondary
-              leftIcon={SvgEdit}
+              icon={SvgEdit}
             >
               Edit
             </Button>
           ) : (
             <>
               <Button
+                prominence="secondary"
                 onClick={handleCancel}
-                secondary
-                leftIcon={SvgX}
+                icon={SvgX}
                 disabled={isSaving}
               >
                 Cancel
               </Button>
               <Button
                 onClick={handleSaveClick}
-                primary
-                leftIcon={SvgCheck}
+                icon={SvgCheck}
                 disabled={
                   isSaving ||
                   (selectedFilesToRemove.size === 0 && filesToAdd.length === 0)
@@ -295,7 +293,7 @@ export default function InlineFileManagement({
                   >
                     {isEditing && (
                       <TableCell>
-                        <OpalButton
+                        <Button
                           icon={SvgX}
                           variant="danger"
                           prominence="tertiary"
@@ -335,9 +333,9 @@ export default function InlineFileManagement({
             id={`file-upload-${connectorId}`}
           />
           <Button
+            prominence="secondary"
             onClick={() => fileInputRef.current?.click()}
-            secondary
-            leftIcon={SvgPlusCircle}
+            icon={SvgPlusCircle}
             disabled={isSaving}
           >
             Add Files
@@ -398,8 +396,8 @@ export default function InlineFileManagement({
 
           <Modal.Footer>
             <Button
+              prominence="secondary"
               onClick={() => setShowSaveConfirm(false)}
-              secondary
               disabled={isSaving}
             >
               Cancel
diff --git a/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx b/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx
index 902b52d8a45..5987e28447e 100644
--- a/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useState } from "react";
 import { toast } from "@/hooks/useToast";
 import { triggerIndexing } from "@/app/admin/connector/[ccPairId]/lib";
diff --git a/web/src/app/admin/connector/[ccPairId]/page.tsx b/web/src/app/admin/connector/[ccPairId]/page.tsx
index b40ee6e1470..9e45630fa30 100644
--- a/web/src/app/admin/connector/[ccPairId]/page.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/page.tsx
@@ -62,7 +62,7 @@ import { DropdownMenuItemWithTooltip } from "@/components/ui/dropdown-menu-with-
 import { timeAgo } from "@/lib/time";
 import { useStatusChange } from "./useStatusChange";
 import { useReIndexModal } from "./ReIndexModal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SvgSettings } from "@opal/icons";
 import { UserRole } from "@/lib/types";
 import { useUser } from "@/providers/UserProvider";
@@ -456,7 +456,7 @@ function Main({ ccPairId }: { ccPairId: number }) {
           {ccPair.is_editable_for_current_user && (
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
-                <Button leftIcon={SvgSettings} secondary>
+                <Button prominence="secondary" icon={SvgSettings}>
                   Manage
                 </Button>
               </DropdownMenuTrigger>
diff --git a/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx b/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
index 837ccded499..28190b7ef3f 100644
--- a/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
+++ b/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
@@ -55,7 +55,7 @@ import {
 } from "@/lib/connectors/oauth";
 import { CreateStdOAuthCredential } from "@/components/credentials/actions/CreateStdOAuthCredential";
 import { Spinner } from "@/components/Spinner";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { deleteConnector } from "@/lib/connector";
 import ConnectorDocsLink from "@/components/admin/connectors/ConnectorDocsLink";
 import Text from "@/refresh-components/texts/Text";
@@ -580,7 +580,7 @@ export default function AddConnector({
                       {oauthSupportedSources.includes(connector) &&
                         (NEXT_PUBLIC_CLOUD_ENABLED || NEXT_PUBLIC_TEST_ENV) && (
                           <Button
-                            action
+                            variant="action"
                             onClick={handleAuthorize}
                             disabled={isAuthorizing}
                             hidden={!isAuthorizeVisible}
diff --git a/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx b/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx
index a0b2d3f7aa5..c8b4d0e44b7 100644
--- a/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx
+++ b/web/src/app/admin/connectors/[connector]/ConnectorWrapper.tsx
@@ -48,6 +48,7 @@ export default function ConnectorWrapper({
               <HeaderTitle>
                 <p>&lsquo;{connector}&rsquo; is not a valid Connector Type!</p>
               </HeaderTitle>
+              {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
               <Button
                 onClick={() => window.open("/admin/indexing/status", "_self")}
                 className="mr-auto"
diff --git a/web/src/app/admin/connectors/[connector]/NavigationRow.tsx b/web/src/app/admin/connectors/[connector]/NavigationRow.tsx
index 3384aaccd20..3e612a231e5 100644
--- a/web/src/app/admin/connectors/[connector]/NavigationRow.tsx
+++ b/web/src/app/admin/connectors/[connector]/NavigationRow.tsx
@@ -1,5 +1,5 @@
 import { useFormContext } from "@/components/context/FormContext";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SvgArrowLeft, SvgArrowRight, SvgPlusCircle } from "@opal/icons";
 
 const NavigationRow = ({
@@ -22,7 +22,11 @@ const NavigationRow = ({
       <div>
         {((formStep > 0 && !noCredentials) ||
           (formStep > 1 && !noAdvanced)) && (
-          <Button secondary onClick={prevFormStep} leftIcon={SvgArrowLeft}>
+          <Button
+            prominence="secondary"
+            onClick={prevFormStep}
+            icon={SvgArrowLeft}
+          >
             Previous
           </Button>
         )}
@@ -41,7 +45,7 @@ const NavigationRow = ({
       <div className="flex justify-end">
         {formStep === 0 && (
           <Button
-            action
+            variant="action"
             disabled={!activatedCredential}
             rightIcon={SvgArrowRight}
             onClick={() => nextFormStep()}
@@ -51,7 +55,7 @@ const NavigationRow = ({
         )}
         {!noAdvanced && formStep === 1 && (
           <Button
-            secondary
+            prominence="secondary"
             disabled={!isValid}
             rightIcon={SvgArrowRight}
             onClick={() => nextFormStep()}
diff --git a/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx b/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx
index 4b2b739f904..fc86523b72e 100644
--- a/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx
+++ b/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx
@@ -3,7 +3,7 @@
 import { useEffect, useState } from "react";
 import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import { AdminPageTitle } from "@/components/admin/Title";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { getSourceMetadata, isValidSource } from "@/lib/sources";
 import { ConfluenceAccessibleResource, ValidSources } from "@/lib/types";
 import CardSection from "@/components/admin/CardSection";
diff --git a/web/src/app/admin/connectors/[connector]/pages/Advanced.tsx b/web/src/app/admin/connectors/[connector]/pages/Advanced.tsx
index 3b4a0a31249..37f039ae701 100644
--- a/web/src/app/admin/connectors/[connector]/pages/Advanced.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/Advanced.tsx
@@ -1,7 +1,7 @@
 import React from "react";
 import NumberInput from "./ConnectorInput/NumberInput";
 import { TextFormField } from "@/components/Field";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SvgTrash } from "@opal/icons";
 export default function AdvancedFormPage() {
   return (
@@ -35,7 +35,7 @@ export default function AdvancedFormPage() {
         name="indexingStart"
       />
       <div className="mt-4 flex w-full mx-auto max-w-2xl justify-start">
-        <Button leftIcon={SvgTrash} danger type="submit">
+        <Button variant="danger" icon={SvgTrash} type="submit">
           Reset
         </Button>
       </div>
diff --git a/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx b/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
index 2e208808470..09d7d9a0b11 100644
--- a/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
@@ -10,7 +10,7 @@ import { DOCS_ADMINS_PATH } from "@/lib/constants";
 import { TextFormField, SectionHeader } from "@/components/Field";
 import { Form, Formik } from "formik";
 import { User } from "@/lib/types";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   Credential,
   GoogleDriveCredentialJson,
@@ -314,7 +314,7 @@ export const DriveJsonUploadSection = ({
           {isAdmin && !existingAuthCredential && (
             <div className="mt-2">
               <Button
-                danger
+                variant="danger"
                 onClick={async () => {
                   const endpoint =
                     localServiceAccountData?.service_account_email
@@ -467,7 +467,7 @@ export const DriveAuthSection = ({
             </div>
           </div>
           <Button
-            danger
+            variant="danger"
             onClick={async () => {
               handleRevokeAccess(
                 connectorAssociated,
diff --git a/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx b/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
index f4f7111a641..cb544076fb7 100644
--- a/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
@@ -1,4 +1,4 @@
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { toast } from "@/hooks/useToast";
 import React, { useState, useEffect } from "react";
 import { useSWRConfig } from "swr";
@@ -314,7 +314,7 @@ export const GmailJsonUploadSection = ({
           {isAdmin && !existingAuthCredential && (
             <div className="mt-2">
               <Button
-                danger
+                variant="danger"
                 onClick={async () => {
                   const endpoint =
                     localServiceAccountData?.service_account_email
@@ -470,7 +470,7 @@ export const GmailAuthSection = ({
           </div>
           <Section flexDirection="row" justifyContent="between" height="fit">
             <Button
-              danger
+              variant="danger"
               onClick={async () => {
                 handleRevokeAccess(
                   connectorExists,
@@ -482,10 +482,7 @@ export const GmailAuthSection = ({
               Revoke Access
             </Button>
             {buildMode && onCredentialCreated && (
-              <Button
-                primary
-                onClick={() => onCredentialCreated(existingCredential)}
-              >
+              <Button onClick={() => onCredentialCreated(existingCredential)}>
                 Continue
               </Button>
             )}
diff --git a/web/src/app/admin/debug/page.tsx b/web/src/app/admin/debug/page.tsx
index d1f3d3d98e2..95c297f159a 100644
--- a/web/src/app/admin/debug/page.tsx
+++ b/web/src/app/admin/debug/page.tsx
@@ -11,7 +11,7 @@ import {
   TableHeader,
   TableRow,
 } from "@/components/ui/table";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Card } from "@/components/ui/card";
 import Text from "@/components/ui/text";
 import { Spinner } from "@/components/Spinner";
@@ -99,9 +99,9 @@ function Main() {
                     <TableCell className="font-medium">{category}</TableCell>
                     <TableCell>
                       <Button
+                        prominence="secondary"
                         onClick={() => handleDownload(category)}
-                        secondary
-                        leftIcon={SvgDownloadCloud}
+                        icon={SvgDownloadCloud}
                       >
                         Download Logs
                       </Button>
diff --git a/web/src/app/admin/discord-bot/BotConfigCard.tsx b/web/src/app/admin/discord-bot/BotConfigCard.tsx
index 37618730465..3e6622b11d8 100644
--- a/web/src/app/admin/discord-bot/BotConfigCard.tsx
+++ b/web/src/app/admin/discord-bot/BotConfigCard.tsx
@@ -4,7 +4,7 @@ import { useState } from "react";
 import { Section } from "@/layouts/general-layouts";
 import Text from "@/refresh-components/texts/Text";
 import Card from "@/refresh-components/cards/Card";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Badge } from "@/components/ui/badge";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
 import { ThreeDotsLoader } from "@/components/Loading";
@@ -126,9 +126,9 @@ export function BotConfigCard() {
               disabled={!hasServerConfigs}
             >
               <Button
+                variant="danger"
                 onClick={() => setShowDeleteConfirm(true)}
                 disabled={isSubmitting || hasServerConfigs}
-                danger
               >
                 Delete Discord Token
               </Button>
diff --git a/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx b/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx
index 23b8e3228a1..a8a932c9bf4 100644
--- a/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx
+++ b/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx
@@ -12,7 +12,7 @@ import {
 } from "@/components/ui/table";
 import { Badge } from "@/components/ui/badge";
 import { DeleteButton } from "@/components/DeleteButton";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Switch from "@/refresh-components/inputs/Switch";
 import { SvgEdit, SvgServer } from "@opal/icons";
 import EmptyMessage from "@/refresh-components/EmptyMessage";
@@ -116,10 +116,10 @@ export function DiscordGuildsTable({ guilds, onRefresh }: Props) {
             <TableRow key={guild.id}>
               <TableCell>
                 <Button
-                  internal
+                  prominence="internal"
                   disabled={!guild.guild_id}
                   onClick={() => router.push(`/admin/discord-bot/${guild.id}`)}
-                  leftIcon={SvgEdit}
+                  icon={SvgEdit}
                 >
                   {guild.guild_name || `Server #${guild.id}`}
                 </Button>
diff --git a/web/src/app/admin/discord-bot/[guild-id]/page.tsx b/web/src/app/admin/discord-bot/[guild-id]/page.tsx
index f2f7f1b425e..44ce90ce4ad 100644
--- a/web/src/app/admin/discord-bot/[guild-id]/page.tsx
+++ b/web/src/app/admin/discord-bot/[guild-id]/page.tsx
@@ -12,7 +12,7 @@ import Text from "@/refresh-components/texts/Text";
 import Card from "@/refresh-components/cards/Card";
 import { Callout } from "@/components/ui/callout";
 import Message from "@/refresh-components/messages/Message";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SvgServer } from "@opal/icons";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import {
@@ -104,13 +104,17 @@ function GuildDetailContent({
                 width="fit"
                 gap={0.5}
               >
-                <Button onClick={handleEnableAll} disabled={disabled} secondary>
+                <Button
+                  prominence="secondary"
+                  onClick={handleEnableAll}
+                  disabled={disabled}
+                >
                   Enable All
                 </Button>
                 <Button
+                  prominence="secondary"
                   onClick={handleDisableAll}
                   disabled={disabled}
-                  secondary
                 >
                   Disable All
                 </Button>
diff --git a/web/src/app/admin/document-index-migration/page.tsx b/web/src/app/admin/document-index-migration/page.tsx
index 142764eec82..1e1c1bcde90 100644
--- a/web/src/app/admin/document-index-migration/page.tsx
+++ b/web/src/app/admin/document-index-migration/page.tsx
@@ -200,6 +200,7 @@ function RetrievalSourceSection() {
       </InputSelect>
 
       {hasChanges && (
+        // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
         <Button
           className="self-center"
           onClick={handleUpdate}
diff --git a/web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx b/web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx
index 146d7e49b2f..ce24da7dbc2 100644
--- a/web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx
+++ b/web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx
@@ -257,6 +257,7 @@ export const DocumentSetCreationForm = ({
               </div>
 
               <div className="flex mt-6 pt-4 border-t border-border-02">
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                 <Button
                   type="submit"
                   disabled={props.isSubmitting}
diff --git a/web/src/app/admin/embeddings/EmbeddingModelSelectionForm.tsx b/web/src/app/admin/embeddings/EmbeddingModelSelectionForm.tsx
index f6002484bad..e2d2c104951 100644
--- a/web/src/app/admin/embeddings/EmbeddingModelSelectionForm.tsx
+++ b/web/src/app/admin/embeddings/EmbeddingModelSelectionForm.tsx
@@ -27,7 +27,7 @@ import {
   EMBEDDING_PROVIDERS_ADMIN_URL,
 } from "@/lib/llmConfig/constants";
 import { AdvancedSearchConfiguration } from "@/app/admin/embeddings/interfaces";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 
 export interface EmbeddingDetails {
   api_key?: string;
@@ -279,7 +279,7 @@ export default function EmbeddingModelSelection({
           {currentEmbeddingModel?.provider_type && (
             <div className="mt-2">
               <Button
-                secondary
+                prominence="secondary"
                 onClick={() => {
                   const allProviders = [
                     ...AVAILABLE_CLOUD_PROVIDERS,
diff --git a/web/src/app/admin/embeddings/RerankingFormPage.tsx b/web/src/app/admin/embeddings/RerankingFormPage.tsx
index 31d9b33b437..db27aeace46 100644
--- a/web/src/app/admin/embeddings/RerankingFormPage.tsx
+++ b/web/src/app/admin/embeddings/RerankingFormPage.tsx
@@ -21,7 +21,7 @@ import {
   MixedBreadIcon,
 } from "@/components/icons/icons";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { TextFormField } from "@/components/Field";
 import { SettingsContext } from "@/providers/SettingsProvider";
 import { SvgAlertTriangle, SvgKey } from "@opal/icons";
diff --git a/web/src/app/admin/embeddings/modals/AlreadyPickedModal.tsx b/web/src/app/admin/embeddings/modals/AlreadyPickedModal.tsx
index 367c8db1e6a..c0c8538a76c 100644
--- a/web/src/app/admin/embeddings/modals/AlreadyPickedModal.tsx
+++ b/web/src/app/admin/embeddings/modals/AlreadyPickedModal.tsx
@@ -1,5 +1,5 @@
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { CloudEmbeddingModel } from "../../../../components/embedding/interfaces";
 import { SvgCheck } from "@opal/icons";
 
diff --git a/web/src/app/admin/embeddings/modals/ChangeCredentialsModal.tsx b/web/src/app/admin/embeddings/modals/ChangeCredentialsModal.tsx
index 1a760f56819..6709a59f63a 100644
--- a/web/src/app/admin/embeddings/modals/ChangeCredentialsModal.tsx
+++ b/web/src/app/admin/embeddings/modals/ChangeCredentialsModal.tsx
@@ -268,6 +268,7 @@ export default function ChangeCredentialsModal({
                   </Callout>
                 )}
 
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                 <Button
                   className="mr-auto mt-4"
                   onClick={() => handleSubmit()}
@@ -289,6 +290,7 @@ export default function ChangeCredentialsModal({
             embedding type!
           </Text>
 
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <Button className="mr-auto" onClick={handleDelete} danger>
             Delete Configuration
           </Button>
diff --git a/web/src/app/admin/embeddings/modals/DeleteCredentialsModal.tsx b/web/src/app/admin/embeddings/modals/DeleteCredentialsModal.tsx
index 008a9891f14..b77296d9674 100644
--- a/web/src/app/admin/embeddings/modals/DeleteCredentialsModal.tsx
+++ b/web/src/app/admin/embeddings/modals/DeleteCredentialsModal.tsx
@@ -1,6 +1,6 @@
 import Modal from "@/refresh-components/Modal";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Callout } from "@/components/ui/callout";
 import {
   CloudEmbeddingProvider,
@@ -38,10 +38,10 @@ export default function DeleteCredentialsModal({
           <Callout type="danger" title="Point of No Return" />
         </Modal.Body>
         <Modal.Footer>
-          <Button secondary onClick={onCancel}>
+          <Button prominence="secondary" onClick={onCancel}>
             Keep Credentials
           </Button>
-          <Button danger onClick={onConfirm}>
+          <Button variant="danger" onClick={onConfirm}>
             Delete Credentials
           </Button>
         </Modal.Footer>
diff --git a/web/src/app/admin/embeddings/modals/InstantSwitchConfirmModal.tsx b/web/src/app/admin/embeddings/modals/InstantSwitchConfirmModal.tsx
index 427423e574e..02c761e1bcf 100644
--- a/web/src/app/admin/embeddings/modals/InstantSwitchConfirmModal.tsx
+++ b/web/src/app/admin/embeddings/modals/InstantSwitchConfirmModal.tsx
@@ -1,5 +1,5 @@
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { SvgAlertTriangle } from "@opal/icons";
 export interface InstantSwitchConfirmModalProps {
@@ -31,7 +31,7 @@ export default function InstantSwitchConfirmModal({
         </Modal.Body>
         <Modal.Footer>
           <Button onClick={onConfirm}>Confirm</Button>
-          <Button secondary onClick={onClose}>
+          <Button prominence="secondary" onClick={onClose}>
             Cancel
           </Button>
         </Modal.Footer>
diff --git a/web/src/app/admin/embeddings/modals/ModelSelectionModal.tsx b/web/src/app/admin/embeddings/modals/ModelSelectionModal.tsx
index 92c1b502fd1..b25c27a8079 100644
--- a/web/src/app/admin/embeddings/modals/ModelSelectionModal.tsx
+++ b/web/src/app/admin/embeddings/modals/ModelSelectionModal.tsx
@@ -1,7 +1,7 @@
 import Modal from "@/refresh-components/Modal";
 import Text from "@/refresh-components/texts/Text";
 import { Callout } from "@/components/ui/callout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { HostedEmbeddingModel } from "@/components/embedding/interfaces";
 import { SvgServer } from "@opal/icons";
 
@@ -57,7 +57,7 @@ export default function ModelSelectionConfirmationModal({
         </Modal.Body>
         <Modal.Footer>
           <Button onClick={onConfirm}>Confirm</Button>
-          <Button secondary onClick={onCancel}>
+          <Button prominence="secondary" onClick={onCancel}>
             Cancel
           </Button>
         </Modal.Footer>
diff --git a/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx b/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx
index 490b6065a6c..dc2b9f8962b 100644
--- a/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx
+++ b/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx
@@ -1,11 +1,10 @@
 import React, { useRef, useState } from "react";
 import Text from "@/refresh-components/texts/Text";
 import { Callout } from "@/components/ui/callout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Formik, Form } from "formik";
 import * as Yup from "yup";
 import { Label, TextFormField } from "@/components/Field";
-import { LoadingAnimation } from "@/components/Loading";
 import {
   CloudEmbeddingProvider,
   EmbeddingProvider,
@@ -14,6 +13,7 @@ import {
 import { EMBEDDING_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
 import Modal from "@/refresh-components/Modal";
 import { SvgSettings } from "@opal/icons";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 export interface ProviderCreationModalProps {
   updateCurrentModel: (
     newModel: string,
@@ -39,7 +39,6 @@ export default function ProviderCreationModal({
   const useFileUpload =
     selectedProvider.provider_type == EmbeddingProvider.GOOGLE;
 
-  const [isProcessing, setIsProcessing] = useState(false);
   const [errorMsg, setErrorMsg] = useState<string>("");
   const [fileName, setFileName] = useState<string>("");
 
@@ -110,7 +109,6 @@ export default function ProviderCreationModal({
     values: any,
     { setSubmitting }: { setSubmitting: (isSubmitting: boolean) => void }
   ) => {
-    setIsProcessing(true);
     setErrorMsg("");
     try {
       const customConfig = Object.fromEntries(values.custom_config);
@@ -141,7 +139,6 @@ export default function ProviderCreationModal({
       if (!initialResponse.ok) {
         const errorMsg = (await initialResponse.json()).detail;
         setErrorMsg(errorMsg);
-        setIsProcessing(false);
         setSubmitting(false);
         return;
       }
@@ -179,7 +176,6 @@ export default function ProviderCreationModal({
         setErrorMsg("An unknown error occurred");
       }
     } finally {
-      setIsProcessing(false);
       setSubmitting(false);
     }
   };
@@ -302,16 +298,15 @@ export default function ProviderCreationModal({
 
                 <Button
                   type="submit"
-                  className="w-full"
+                  width="full"
                   disabled={isSubmitting}
+                  icon={isSubmitting ? SimpleLoader : undefined}
                 >
-                  {isProcessing ? (
-                    <LoadingAnimation />
-                  ) : existingProvider ? (
-                    "Update"
-                  ) : (
-                    "Create"
-                  )}
+                  {isSubmitting
+                    ? "Submitting"
+                    : existingProvider
+                      ? "Update"
+                      : "Create"}
                 </Button>
               </Form>
             )}
diff --git a/web/src/app/admin/embeddings/modals/SelectModelModal.tsx b/web/src/app/admin/embeddings/modals/SelectModelModal.tsx
index 8df59da0989..34e7fc7bb7f 100644
--- a/web/src/app/admin/embeddings/modals/SelectModelModal.tsx
+++ b/web/src/app/admin/embeddings/modals/SelectModelModal.tsx
@@ -1,5 +1,5 @@
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { CloudEmbeddingModel } from "@/components/embedding/interfaces";
 import { SvgServer } from "@opal/icons";
@@ -32,7 +32,7 @@ export default function SelectModelModal({
         </Modal.Body>
         <Modal.Footer>
           <Button onClick={onConfirm}>Confirm</Button>
-          <Button secondary onClick={onCancel}>
+          <Button prominence="secondary" onClick={onCancel}>
             Cancel
           </Button>
         </Modal.Footer>
diff --git a/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx b/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
index bea3929c16c..78469cb9c45 100644
--- a/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
+++ b/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
@@ -6,6 +6,7 @@ import EmbeddingModelSelection from "../EmbeddingModelSelectionForm";
 import { useCallback, useEffect, useMemo, useState, useRef } from "react";
 import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import { WarningCircle, Warning, CaretDownIcon } from "@phosphor-icons/react";
 import {
   CloudEmbeddingModel,
@@ -247,6 +248,7 @@ export default function EmbeddingForm() {
       return needsReIndex ? (
         <div className="flex mx-auto gap-x-1 ml-auto items-center">
           <div className="flex items-center h-fit">
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               onClick={() => {
                 if (switchoverType == SwitchoverType.INSTANT) {
@@ -268,6 +270,7 @@ export default function EmbeddingForm() {
             </Button>
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                 <Button
                   disabled={!isOverallFormValid}
                   action
@@ -373,7 +376,7 @@ export default function EmbeddingForm() {
         </div>
       ) : (
         <div className="flex mx-auto gap-x-1 ml-auto items-center">
-          <Button
+          <OpalButton
             onClick={() => {
               updateSearch();
               navigateToEmbeddingPage("search settings");
@@ -381,7 +384,7 @@ export default function EmbeddingForm() {
             disabled={!isOverallFormValid}
           >
             Update Search
-          </Button>
+          </OpalButton>
           {!isOverallFormValid &&
             Object.keys(combinedFormErrors).length > 0 && (
               <div className="relative group">
@@ -507,7 +510,8 @@ export default function EmbeddingForm() {
               />
             </CardSection>
             <div className="mt-4 flex w-full justify-end">
-              <Button
+              <OpalButton
+                variant="action"
                 onClick={() => {
                   if (
                     selectedProvider.model_name.includes("e5") &&
@@ -522,10 +526,9 @@ export default function EmbeddingForm() {
                   }
                 }}
                 rightIcon={SvgArrowRight}
-                action
               >
                 Continue
-              </Button>
+              </OpalButton>
             </div>
           </>
         )}
@@ -557,10 +560,13 @@ export default function EmbeddingForm() {
                 </div>
               </Modal.Body>
               <Modal.Footer>
-                <Button secondary onClick={() => setShowPoorModel(false)}>
+                <OpalButton
+                  prominence="secondary"
+                  onClick={() => setShowPoorModel(false)}
+                >
                   Cancel update
-                </Button>
-                <Button
+                </OpalButton>
+                <OpalButton
                   onClick={() => {
                     setShowPoorModel(false);
                     // Skip reranking step (step 1), go directly to advanced settings (step 2)
@@ -569,7 +575,7 @@ export default function EmbeddingForm() {
                   }}
                 >
                   {`Continue with ${selectedProvider.model_name}`}
-                </Button>
+                </OpalButton>
               </Modal.Footer>
             </Modal.Content>
           </Modal>
@@ -615,26 +621,26 @@ export default function EmbeddingForm() {
             </CardSection>
 
             <div className={`mt-4 w-full grid grid-cols-3`}>
-              <Button
-                leftIcon={SvgArrowLeft}
+              <OpalButton
+                prominence="secondary"
+                icon={SvgArrowLeft}
                 onClick={() => prevFormStep()}
-                secondary
               >
                 Previous
-              </Button>
+              </OpalButton>
 
               <ReIndexingButton needsReIndex={needsReIndex} />
 
               <div className="flex w-full justify-end">
-                <Button
+                <OpalButton
+                  prominence="secondary"
                   onClick={() => {
                     nextFormStep();
                   }}
                   rightIcon={SvgArrowRight}
-                  secondary
                 >
                   Advanced
-                </Button>
+                </OpalButton>
               </div>
             </div>
           </>
@@ -660,17 +666,17 @@ export default function EmbeddingForm() {
             </CardSection>
 
             <div className={`mt-4 grid  grid-cols-3 w-full `}>
-              <Button
+              <OpalButton
+                prominence="secondary"
                 onClick={() => {
                   // Skip reranking step (step 1), go back to embedding model (step 0)
                   prevFormStep();
                   prevFormStep();
                 }}
-                leftIcon={SvgArrowLeft}
-                secondary
+                icon={SvgArrowLeft}
               >
                 Previous
-              </Button>
+              </OpalButton>
 
               <ReIndexingButton needsReIndex={needsReIndex} />
             </div>
diff --git a/web/src/app/admin/embeddings/pages/OpenEmbeddingPage.tsx b/web/src/app/admin/embeddings/pages/OpenEmbeddingPage.tsx
index 9708c55df5a..fbb1a9db29b 100644
--- a/web/src/app/admin/embeddings/pages/OpenEmbeddingPage.tsx
+++ b/web/src/app/admin/embeddings/pages/OpenEmbeddingPage.tsx
@@ -62,6 +62,7 @@ export default function OpenEmbeddingPage({
         Onyx team.
       </Text>
       {!configureModel && (
+        // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
         <Button
           onClick={() => setConfigureModel(true)}
           className="mt-4"
diff --git a/web/src/app/admin/indexing/status/FilterComponent.tsx b/web/src/app/admin/indexing/status/FilterComponent.tsx
index e044b5d6219..65156c10bb0 100644
--- a/web/src/app/admin/indexing/status/FilterComponent.tsx
+++ b/web/src/app/admin/indexing/status/FilterComponent.tsx
@@ -10,11 +10,10 @@ import {
   DropdownMenuTrigger,
   DropdownMenuCheckboxItem,
 } from "@/components/ui/dropdown-menu";
-import Button from "@/refresh-components/buttons/Button";
 import { Input } from "@/components/ui/input";
 import { Badge } from "@/components/ui/badge";
 import { AccessType, ValidStatuses } from "@/lib/types";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import { SvgFilter } from "@opal/icons";
 export interface FilterOptions {
   accessType: AccessType[] | null;
@@ -128,11 +127,7 @@ export const FilterComponent = forwardRef<
     <div className="relative">
       <DropdownMenu open={isOpen} onOpenChange={handleOpenChange}>
         <DropdownMenuTrigger asChild>
-          <OpalButton
-            icon={SvgFilter}
-            prominence="secondary"
-            transient={isOpen}
-          />
+          <Button icon={SvgFilter} prominence="secondary" transient={isOpen} />
         </DropdownMenuTrigger>
         <DropdownMenuContent
           align="end"
@@ -242,7 +237,7 @@ export const FilterComponent = forwardRef<
             >
               <div className="flex gap-2">
                 <Button
-                  secondary={docsOperator !== ">"}
+                  prominence={docsOperator !== ">" ? "secondary" : "primary"}
                   onClick={(e) => {
                     e.preventDefault();
                     e.stopPropagation();
@@ -253,7 +248,7 @@ export const FilterComponent = forwardRef<
                   &gt;
                 </Button>
                 <Button
-                  secondary={docsOperator !== "<"}
+                  prominence={docsOperator !== "<" ? "secondary" : "primary"}
                   onClick={(e) => {
                     e.preventDefault();
                     e.stopPropagation();
@@ -264,7 +259,7 @@ export const FilterComponent = forwardRef<
                   &lt;
                 </Button>
                 <Button
-                  secondary={docsOperator !== "="}
+                  prominence={docsOperator !== "=" ? "secondary" : "primary"}
                   onClick={(e) => {
                     e.preventDefault();
                     e.stopPropagation();
@@ -286,7 +281,7 @@ export const FilterComponent = forwardRef<
             </div>
             <div className="px-2 py-1.5">
               <Button
-                className="w-full"
+                width="full"
                 onClick={(e) => {
                   e.preventDefault();
                   e.stopPropagation();
diff --git a/web/src/app/admin/indexing/status/SearchAndFilterControls.tsx b/web/src/app/admin/indexing/status/SearchAndFilterControls.tsx
index 46dd33cbf1e..7c1d2a62a51 100644
--- a/web/src/app/admin/indexing/status/SearchAndFilterControls.tsx
+++ b/web/src/app/admin/indexing/status/SearchAndFilterControls.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState, useEffect } from "react";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Badge } from "@/components/ui/badge";
 import { FilterComponent, FilterOptions } from "./FilterComponent";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
diff --git a/web/src/app/admin/indexing/status/page.tsx b/web/src/app/admin/indexing/status/page.tsx
index 90212882bf4..67ae367c8c2 100644
--- a/web/src/app/admin/indexing/status/page.tsx
+++ b/web/src/app/admin/indexing/status/page.tsx
@@ -8,7 +8,7 @@ import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import Text from "@/components/ui/text";
 import { useConnectorIndexingStatusWithPagination } from "@/lib/hooks";
 import { useToastFromQuery } from "@/hooks/useToast";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 import { useState, useRef, useMemo, RefObject } from "react";
 import { FilterOptions } from "./FilterComponent";
diff --git a/web/src/app/admin/kg/KGEntityTypes.tsx b/web/src/app/admin/kg/KGEntityTypes.tsx
index 08c84db1bb2..1b4facdd7dc 100644
--- a/web/src/app/admin/kg/KGEntityTypes.tsx
+++ b/web/src/app/admin/kg/KGEntityTypes.tsx
@@ -7,7 +7,7 @@ import CollapsibleCard from "@/components/CollapsibleCard";
 import { ValidSources } from "@/lib/types";
 import { FaCircleQuestion } from "react-icons/fa6";
 import { CheckmarkIcon } from "@/components/icons/icons";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { cn } from "@/lib/utils";
@@ -237,10 +237,7 @@ export default function KGEntityTypes({
           value={search}
           onChange={(event) => setSearch(event.target.value)}
         />
-        <Button
-          className="h-9"
-          onClick={allClosed ? handleExpandAll : handleCollapseAll}
-        >
+        <Button onClick={allClosed ? handleExpandAll : handleCollapseAll}>
           {allClosed ? "Expand All" : "Collapse All"}
         </Button>
       </div>
diff --git a/web/src/app/admin/kg/page.tsx b/web/src/app/admin/kg/page.tsx
index a2dc19d21cd..bea909aa178 100644
--- a/web/src/app/admin/kg/page.tsx
+++ b/web/src/app/admin/kg/page.tsx
@@ -9,7 +9,7 @@ import {
 } from "@/components/Field";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import SwitchField from "@/refresh-components/form/SwitchField";
 import { Form, Formik, FormikState, useFormikContext } from "formik";
 import { useState } from "react";
@@ -274,7 +274,7 @@ function Main() {
             entities you want to model afterwards.
           </Text>
           <Button
-            leftIcon={SvgSettings}
+            icon={SvgSettings}
             onClick={() => setConfigureModalShown(true)}
           >
             Configure Knowledge Graph
diff --git a/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx b/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx
index 215c2bbee4b..bb7bffcc49e 100644
--- a/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx
+++ b/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import * as Yup from "yup";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useEffect, useState } from "react";
 import Modal from "@/refresh-components/Modal";
 import { Form, Formik } from "formik";
diff --git a/web/src/app/admin/users/page.tsx b/web/src/app/admin/users/page.tsx
index fd98bfdbeec..de548157c58 100644
--- a/web/src/app/admin/users/page.tsx
+++ b/web/src/app/admin/users/page.tsx
@@ -18,7 +18,7 @@ import { InvitedUserSnapshot } from "@/lib/types";
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
 import PendingUsersTable from "@/components/admin/users/PendingUsersTable";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { Spinner } from "@/components/Spinner";
 import { SvgDownloadCloud, SvgUserPlus } from "@opal/icons";
@@ -150,7 +150,7 @@ function UsersTables({
             <div className="flex justify-between items-center gap-1">
               <CardTitle>Current Users</CardTitle>
               <Button
-                leftIcon={SvgDownloadCloud}
+                icon={SvgDownloadCloud}
                 disabled={isDownloadingUsers}
                 onClick={() => downloadAllUsers()}
               >
diff --git a/web/src/app/app/components/AppPopup.tsx b/web/src/app/app/components/AppPopup.tsx
index 78ee27e1492..59ef2a521e7 100644
--- a/web/src/app/app/components/AppPopup.tsx
+++ b/web/src/app/app/components/AppPopup.tsx
@@ -2,7 +2,7 @@
 
 import Modal from "@/refresh-components/Modal";
 import { SettingsContext } from "@/providers/SettingsProvider";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { FormField } from "@/refresh-components/form/FormField";
 import Checkbox from "@/refresh-components/inputs/Checkbox";
diff --git a/web/src/app/app/components/projects/ProjectContextPanel.tsx b/web/src/app/app/components/projects/ProjectContextPanel.tsx
index 7fc05daee6e..42f12db65f4 100644
--- a/web/src/app/app/components/projects/ProjectContextPanel.tsx
+++ b/web/src/app/app/components/projects/ProjectContextPanel.tsx
@@ -7,7 +7,7 @@ import { useProjectsContext } from "@/providers/ProjectsContext";
 import FilePickerPopover from "@/refresh-components/popovers/FilePickerPopover";
 import type { ProjectFile } from "../../projects/projectsService";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 
 import AddInstructionModal from "@/components/modals/AddInstructionModal";
 import UserFilesModal from "@/components/modals/UserFilesModal";
@@ -150,6 +150,7 @@ export default function ProjectContextPanel({
                 <Text as="p" headingH2 className="font-heading-h2">
                   {projectName}
                 </Text>
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                 <IconButton
                   icon={SvgEdit}
                   internal
@@ -181,9 +182,9 @@ export default function ProjectContextPanel({
             )}
           </div>
           <Button
-            leftIcon={SvgAddLines}
+            prominence="tertiary"
+            icon={SvgAddLines}
             onClick={() => addInstructionModal.toggle(true)}
-            tertiary
           >
             Set Instructions
           </Button>
diff --git a/web/src/app/app/message/Resubmit.tsx b/web/src/app/app/message/Resubmit.tsx
index 0250f5e1902..22c27f7605d 100644
--- a/web/src/app/app/message/Resubmit.tsx
+++ b/web/src/app/app/message/Resubmit.tsx
@@ -1,7 +1,7 @@
 import { useState } from "react";
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
 import { SvgChevronDown, SvgChevronRight } from "@opal/icons";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import { getErrorIcon, getErrorTitle } from "./errorHelpers";
 
@@ -59,10 +59,8 @@ export const ErrorBanner = ({
             <div className="mt-2 border-t border-neutral-200 dark:border-neutral-700 pt-2">
               <div className="flex flex-1 items-center justify-between">
                 <Button
-                  tertiary
-                  leftIcon={
-                    isStackTraceExpanded ? SvgChevronDown : SvgChevronRight
-                  }
+                  prominence="tertiary"
+                  icon={isStackTraceExpanded ? SvgChevronDown : SvgChevronRight}
                   onClick={() => setIsStackTraceExpanded(!isStackTraceExpanded)}
                 >
                   Stack trace
diff --git a/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx b/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx
index 0375b1e2bbb..b85ff5e2ed4 100644
--- a/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx
@@ -2,8 +2,7 @@ import React, { FunctionComponent } from "react";
 import { cn } from "@/lib/utils";
 import { SvgFold, SvgExpand } from "@opal/icons";
 import { IconProps } from "@opal/types";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 
 export interface TimelineStepContentProps {
@@ -51,8 +50,8 @@ export function TimelineStepContent({
             {showCollapseControls &&
               (buttonTitle ? (
                 <Button
+                  prominence="tertiary"
                   size="md"
-                  tertiary
                   onClick={onToggle}
                   rightIcon={
                     isExpanded ? SvgFold : CollapsedIconComponent || SvgExpand
@@ -61,7 +60,7 @@ export function TimelineStepContent({
                   {buttonTitle}
                 </Button>
               ) : (
-                <OpalButton
+                <Button
                   prominence="tertiary"
                   size="md"
                   onClick={onToggle}
diff --git a/web/src/app/auth/create-account/page.tsx b/web/src/app/auth/create-account/page.tsx
index 0c9909acbab..57e8453c005 100644
--- a/web/src/app/auth/create-account/page.tsx
+++ b/web/src/app/auth/create-account/page.tsx
@@ -2,7 +2,7 @@
 
 import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
 import { REGISTRATION_URL } from "@/lib/constants";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Link from "next/link";
 import { SvgImport } from "@opal/icons";
 
@@ -24,8 +24,8 @@ export default function Page() {
         <div className="flex justify-center">
           <Button
             href={`${REGISTRATION_URL}/register`}
-            className="w-full"
-            leftIcon={SvgImport}
+            width="full"
+            icon={SvgImport}
           >
             Create New Organization
           </Button>
diff --git a/web/src/app/auth/error/page.tsx b/web/src/app/auth/error/page.tsx
index 8c272449d65..b00722229f9 100644
--- a/web/src/app/auth/error/page.tsx
+++ b/web/src/app/auth/error/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
 
@@ -35,7 +35,7 @@ const Page = () => {
           </ul>
         </div>
 
-        <Button href="/auth/login" className="w-full">
+        <Button href="/auth/login" width="full">
           Return to Login Page
         </Button>
         <p className="text-sm text-text-500 text-center">
diff --git a/web/src/app/auth/forgot-password/page.tsx b/web/src/app/auth/forgot-password/page.tsx
index 6aa26258567..452c0672b39 100644
--- a/web/src/app/auth/forgot-password/page.tsx
+++ b/web/src/app/auth/forgot-password/page.tsx
@@ -5,7 +5,7 @@ import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
 import Title from "@/components/ui/title";
 import Text from "@/components/ui/text";
 import Link from "next/link";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { TextFormField } from "@/components/Field";
@@ -63,11 +63,7 @@ const ForgotPasswordPage: React.FC = () => {
               />
 
               <div className="flex">
-                <Button
-                  type="submit"
-                  disabled={isSubmitting}
-                  className="mx-auto w-full"
-                >
+                <Button type="submit" disabled={isSubmitting} width="full">
                   Reset Password
                 </Button>
               </div>
diff --git a/web/src/app/auth/impersonate/page.tsx b/web/src/app/auth/impersonate/page.tsx
index 81d20f195e4..a6c38da2f46 100644
--- a/web/src/app/auth/impersonate/page.tsx
+++ b/web/src/app/auth/impersonate/page.tsx
@@ -9,7 +9,7 @@ import { Formik, Form, FormikHelpers } from "formik";
 import * as Yup from "yup";
 import { toast } from "@/hooks/useToast";
 import { TextFormField } from "@/components/Field";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 
 const ImpersonateSchema = Yup.object().shape({
@@ -89,7 +89,7 @@ export default function ImpersonatePage() {
                 placeholder="Enter API Key"
               />
 
-              <Button type="submit" className="w-full" disabled={isSubmitting}>
+              <Button type="submit" width="full" disabled={isSubmitting}>
                 Impersonate User
               </Button>
             </Form>
diff --git a/web/src/app/auth/login/EmailPasswordForm.tsx b/web/src/app/auth/login/EmailPasswordForm.tsx
index 947f9aa83b6..fe30b4cc4b8 100644
--- a/web/src/app/auth/login/EmailPasswordForm.tsx
+++ b/web/src/app/auth/login/EmailPasswordForm.tsx
@@ -2,7 +2,7 @@
 
 import { toast } from "@/hooks/useToast";
 import { basicLogin, basicSignup } from "@/lib/user";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { requestEmailVerification } from "../lib";
@@ -18,6 +18,7 @@ import { validateInternalRedirect } from "@/lib/auth/redirectValidation";
 import { APIFormFieldState } from "@/refresh-components/form/types";
 import { SvgArrowRightCircle } from "@opal/icons";
 import { useCaptcha } from "@/lib/hooks/useCaptcha";
+import Spacer from "@/refresh-components/Spacer";
 
 interface EmailPasswordFormProps {
   isSignup?: boolean;
@@ -239,9 +240,10 @@ export default function EmailPasswordForm({
                 )}
               />
 
+              <Spacer rem={0.25} />
               <Button
                 type="submit"
-                className="w-full mt-1"
+                width="full"
                 disabled={isSubmitting || !isValid || !dirty}
                 rightIcon={SvgArrowRightCircle}
               >
diff --git a/web/src/app/auth/login/LoginPage.tsx b/web/src/app/auth/login/LoginPage.tsx
index d3ec552ef7e..6a54ff43ac8 100644
--- a/web/src/app/auth/login/LoginPage.tsx
+++ b/web/src/app/auth/login/LoginPage.tsx
@@ -7,7 +7,7 @@ import EmailPasswordForm from "./EmailPasswordForm";
 import { AuthType, NEXT_PUBLIC_FORGOT_PASSWORD_ENABLED } from "@/lib/constants";
 import { useSendAuthRequiredMessage } from "@/lib/extension/utils";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Message from "@/refresh-components/messages/Message";
 
 interface LoginPageProps {
diff --git a/web/src/app/auth/login/SignInButton.tsx b/web/src/app/auth/login/SignInButton.tsx
index dfc93b3f191..011100980cd 100644
--- a/web/src/app/auth/login/SignInButton.tsx
+++ b/web/src/app/auth/login/SignInButton.tsx
@@ -18,7 +18,7 @@
 
 "use client";
 
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { AuthType } from "@/lib/constants";
 import { FcGoogle } from "react-icons/fc";
 import type { IconProps } from "@opal/types";
@@ -32,7 +32,7 @@ export default function SignInButton({
   authorizeUrl,
   authType,
 }: SignInButtonProps) {
-  let button: React.ReactNode;
+  let button: string | undefined;
   let icon: React.FunctionComponent<IconProps> | undefined;
 
   if (authType === AuthType.GOOGLE_OAUTH || authType === AuthType.CLOUD) {
@@ -50,11 +50,13 @@ export default function SignInButton({
 
   return (
     <Button
-      secondary={
+      prominence={
         authType === AuthType.GOOGLE_OAUTH || authType === AuthType.CLOUD
+          ? "secondary"
+          : "primary"
       }
-      className="!w-full"
-      leftIcon={icon}
+      width="full"
+      icon={icon}
       href={authorizeUrl}
     >
       {button}
diff --git a/web/src/app/auth/reset-password/page.tsx b/web/src/app/auth/reset-password/page.tsx
index 3b75f2c3f3b..9feb9ca5d98 100644
--- a/web/src/app/auth/reset-password/page.tsx
+++ b/web/src/app/auth/reset-password/page.tsx
@@ -5,7 +5,7 @@ import AuthFlowContainer from "@/components/auth/AuthFlowContainer";
 import Title from "@/components/ui/title";
 import Text from "@/components/ui/text";
 import Link from "next/link";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { TextFormField } from "@/components/Field";
@@ -99,11 +99,7 @@ const ResetPasswordPage: React.FC = () => {
               />
 
               <div className="flex">
-                <Button
-                  type="submit"
-                  disabled={isSubmitting}
-                  className="mx-auto w-full"
-                >
+                <Button type="submit" disabled={isSubmitting} width="full">
                   Reset Password
                 </Button>
               </div>
diff --git a/web/src/app/craft/components/ChatPanel.tsx b/web/src/app/craft/components/ChatPanel.tsx
index c8a8b04d768..00a0790688a 100644
--- a/web/src/app/craft/components/ChatPanel.tsx
+++ b/web/src/app/craft/components/ChatPanel.tsx
@@ -401,6 +401,7 @@ export default function BuildChatPanel({
           </div>
           {/* Output panel toggle - only show when panel is fully closed (after animation) */}
           {isOutputPanelFullyClosed && (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <IconButton
               icon={SvgSidebar}
               onClick={toggleOutputPanel}
diff --git a/web/src/app/craft/components/FileBrowser.tsx b/web/src/app/craft/components/FileBrowser.tsx
index 07f0e467d7e..43ec61321f7 100644
--- a/web/src/app/craft/components/FileBrowser.tsx
+++ b/web/src/app/craft/components/FileBrowser.tsx
@@ -2,7 +2,7 @@
 
 import { useState, useCallback, useEffect } from "react";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   Collapsible,
   CollapsibleContent,
@@ -180,9 +180,9 @@ function FileNode({ entry, sessionId, depth, onPreview }: FileNodeProps) {
       <div className="flex flex-row gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
         {canPreview && (
           <Button
-            action
-            tertiary
-            leftIcon={SvgEye}
+            variant="action"
+            prominence="tertiary"
+            icon={SvgEye}
             onClick={(e) => {
               e.stopPropagation();
               onPreview(entry);
@@ -196,7 +196,11 @@ function FileNode({ entry, sessionId, depth, onPreview }: FileNodeProps) {
           download={entry.name}
           onClick={(e) => e.stopPropagation()}
         >
-          <Button action tertiary leftIcon={SvgDownloadCloud}>
+          <Button
+            variant="action"
+            prominence="tertiary"
+            icon={SvgDownloadCloud}
+          >
             Download
           </Button>
         </a>
diff --git a/web/src/app/craft/components/FilePreviewModal.tsx b/web/src/app/craft/components/FilePreviewModal.tsx
index c2ce96f4d08..b5d3b621302 100644
--- a/web/src/app/craft/components/FilePreviewModal.tsx
+++ b/web/src/app/craft/components/FilePreviewModal.tsx
@@ -3,7 +3,7 @@
 import { useState, useEffect } from "react";
 import Modal from "@/refresh-components/Modal";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import { SvgFileText, SvgDownloadCloud, SvgImage } from "@opal/icons";
 import { getArtifactUrl, FileSystemEntry } from "@/lib/build/client";
@@ -89,11 +89,15 @@ export default function FilePreviewModal({
         </Modal.Body>
         <Modal.Footer>
           <a href={downloadUrl} download={entry.name}>
-            <Button action secondary leftIcon={SvgDownloadCloud}>
+            <Button
+              variant="action"
+              prominence="secondary"
+              icon={SvgDownloadCloud}
+            >
               Download
             </Button>
           </a>
-          <Button action primary onClick={onClose}>
+          <Button variant="action" onClick={onClose}>
             Close
           </Button>
         </Modal.Footer>
diff --git a/web/src/app/craft/components/InputBar.tsx b/web/src/app/craft/components/InputBar.tsx
index 3b2e94e9f53..7011687f969 100644
--- a/web/src/app/craft/components/InputBar.tsx
+++ b/web/src/app/craft/components/InputBar.tsx
@@ -406,6 +406,7 @@ const InputBar = memo(
               {/* Bottom right controls */}
               <div className="flex flex-row items-center gap-1">
                 {/* Submit button */}
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                 <IconButton
                   icon={sandboxInitializing ? SvgLoader : SvgArrowUp}
                   onClick={handleSubmit}
diff --git a/web/src/app/craft/components/ShareButton.tsx b/web/src/app/craft/components/ShareButton.tsx
index bf956e60abb..b492e0e2425 100644
--- a/web/src/app/craft/components/ShareButton.tsx
+++ b/web/src/app/craft/components/ShareButton.tsx
@@ -2,7 +2,7 @@
 
 import { useState, useEffect } from "react";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SvgLink, SvgCopy, SvgCheck, SvgX } from "@opal/icons";
 import { setSessionSharing } from "@/app/craft/services/apiServices";
 import type { SharingScope } from "@/app/craft/types/streamingTypes";
@@ -98,10 +98,9 @@ export default function ShareButton({
       <Popover open={isOpen} onOpenChange={setIsOpen}>
         <Popover.Trigger asChild>
           <Button
-            action
-            primary={isShared}
-            tertiary={!isShared}
-            leftIcon={SvgLink}
+            variant="action"
+            prominence={isShared ? "primary" : "tertiary"}
+            icon={SvgLink}
             aria-label="Share webapp"
           >
             {isShared ? "Shared" : "Share"}
@@ -162,10 +161,10 @@ export default function ShareButton({
                     </Truncated>
                   </div>
                   <Button
-                    action
-                    tertiary
+                    variant="action"
+                    prominence="tertiary"
                     size="md"
-                    leftIcon={
+                    icon={
                       copyState === "copied"
                         ? SvgCheck
                         : copyState === "error"
diff --git a/web/src/app/craft/components/SideBar.tsx b/web/src/app/craft/components/SideBar.tsx
index 973ced4af95..559ae1eb532 100644
--- a/web/src/app/craft/components/SideBar.tsx
+++ b/web/src/app/craft/components/SideBar.tsx
@@ -33,7 +33,7 @@ import {
   SvgCheckCircle,
 } from "@opal/icons";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import TypewriterText from "@/app/craft/components/TypewriterText";
 import {
@@ -178,6 +178,7 @@ function BuildSessionButton({
     <>
       <Popover.Trigger asChild onClick={noProp()}>
         <div>
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <IconButton
             icon={SvgMoreHorizontal}
             className={cn(
@@ -270,19 +271,19 @@ function BuildSessionButton({
           twoTone={!isDeleting && !deleteSuccess && !deleteError}
           submit={
             deleteSuccess ? (
-              <Button action disabled leftIcon={SvgCheckCircle}>
+              <Button variant="action" disabled icon={SvgCheckCircle}>
                 Done
               </Button>
             ) : deleteError ? (
-              <Button danger onClick={closeModal}>
+              <Button variant="danger" onClick={closeModal}>
                 Close
               </Button>
             ) : (
               <Button
-                danger
+                variant="danger"
                 onClick={handleConfirmDelete}
                 disabled={isDeleting}
-                leftIcon={isDeleting ? SimpleLoader : undefined}
+                icon={isDeleting ? SimpleLoader : undefined}
               >
                 {isDeleting ? "Deleting..." : "Delete"}
               </Button>
diff --git a/web/src/app/craft/components/output-panel/ArtifactsTab.tsx b/web/src/app/craft/components/output-panel/ArtifactsTab.tsx
index b222fb0de4b..bb6299a29ec 100644
--- a/web/src/app/craft/components/output-panel/ArtifactsTab.tsx
+++ b/web/src/app/craft/components/output-panel/ArtifactsTab.tsx
@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useState } from "react";
 import useSWR from "swr";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   SvgGlobe,
   SvgDownloadCloud,
@@ -162,9 +162,9 @@ export default function ArtifactsTab({
 
               <div className="flex items-center gap-2">
                 <Button
-                  tertiary
-                  action
-                  leftIcon={SvgDownloadCloud}
+                  variant="action"
+                  prominence="tertiary"
+                  icon={SvgDownloadCloud}
                   onClick={handleWebappDownload}
                 >
                   Download
@@ -263,9 +263,9 @@ function OutputEntryRow({
 
         <div className="flex items-center gap-2">
           <Button
-            tertiary
-            action
-            leftIcon={SvgDownloadCloud}
+            variant="action"
+            prominence="tertiary"
+            icon={SvgDownloadCloud}
             onClick={(e) => {
               e.stopPropagation();
               onDownload(entry.path, entry.is_directory);
diff --git a/web/src/app/craft/components/output-panel/UrlBar.tsx b/web/src/app/craft/components/output-panel/UrlBar.tsx
index 33dc122ac51..302ced200c8 100644
--- a/web/src/app/craft/components/output-panel/UrlBar.tsx
+++ b/web/src/app/craft/components/output-panel/UrlBar.tsx
@@ -3,7 +3,7 @@
 import React from "react";
 import { cn } from "@/lib/utils";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   SvgDownloadCloud,
   SvgLoader,
@@ -154,9 +154,9 @@ export default function UrlBar({
         {/* Export button — shown for downloadable file previews (e.g. markdown → docx) */}
         {onDownload && (
           <Button
-            action
-            tertiary
-            leftIcon={isDownloading ? SpinningLoader : SvgExternalLink}
+            variant="action"
+            prominence="tertiary"
+            icon={isDownloading ? SpinningLoader : SvgExternalLink}
             disabled={isDownloading}
             onClick={onDownload}
           >
diff --git a/web/src/app/craft/v1/configure/components/ConfigureConnectorModal.tsx b/web/src/app/craft/v1/configure/components/ConfigureConnectorModal.tsx
index 4da0a61323d..4f42553cae4 100644
--- a/web/src/app/craft/v1/configure/components/ConfigureConnectorModal.tsx
+++ b/web/src/app/craft/v1/configure/components/ConfigureConnectorModal.tsx
@@ -13,7 +13,7 @@ import CredentialStep from "@/app/craft/v1/configure/components/CredentialStep";
 import ConnectorConfigStep from "@/app/craft/v1/configure/components/ConnectorConfigStep";
 import { OAUTH_STATE_KEY } from "@/app/craft/v1/constants";
 import { connectorConfigs } from "@/lib/connectors/connectors";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Section } from "@/layouts/general-layouts";
 
 type ModalStep = "credential" | "configure";
@@ -163,11 +163,11 @@ export default function ConfigureConnectorModal({
               <Section flexDirection="row" justifyContent="end" width="full">
                 <div className="pr-10">
                   <Button
+                    variant="action"
+                    prominence="tertiary"
                     rightIcon={SvgExternalLink}
                     href={getSourceDocLink(connectorType)!}
                     target="_blank"
-                    tertiary
-                    action
                   >
                     View setup documentation
                   </Button>
diff --git a/web/src/app/craft/v1/configure/components/ConnectorCard.tsx b/web/src/app/craft/v1/configure/components/ConnectorCard.tsx
index 06a804044b8..269f83ed466 100644
--- a/web/src/app/craft/v1/configure/components/ConnectorCard.tsx
+++ b/web/src/app/craft/v1/configure/components/ConnectorCard.tsx
@@ -11,7 +11,6 @@ import { SvgMoreHorizontal, SvgPlug, SvgSettings, SvgTrash } from "@opal/icons";
 import { Button } from "@opal/components";
 import { useRouter } from "next/navigation";
 import { cn } from "@/lib/utils";
-import IconButton from "@/refresh-components/buttons/IconButton";
 
 export type ConnectorStatus =
   | "not_connected"
@@ -98,7 +97,7 @@ export default function ConnectorCard({
   // Always-connected connectors show a settings icon
   // Regular connectors show popover menu when connected, plug icon when not
   const rightContent = isDeleting ? null : isAlwaysConnected ? (
-    <IconButton icon={SvgSettings} internal />
+    <Button prominence="internal" icon={SvgSettings} />
   ) : isConnected ? (
     <Popover open={popoverOpen} onOpenChange={setPopoverOpen}>
       <Popover.Trigger asChild>
diff --git a/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx b/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx
index 12ef58f6f62..2a551bb9a26 100644
--- a/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx
+++ b/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx
@@ -3,7 +3,7 @@
 import { useState } from "react";
 import { Formik, Form, useFormikContext } from "formik";
 import { Section } from "@/layouts/general-layouts";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { toast } from "@/hooks/useToast";
 import { ValidSources } from "@/lib/types";
 import { Credential } from "@/lib/connectors/credentials";
@@ -95,15 +95,14 @@ function ConnectorConfigForm({
             />
           ))}
         <Section flexDirection="row" justifyContent="between" height="fit">
-          <Button secondary onClick={onBack} disabled={isSubmitting}>
-            Back
-          </Button>
           <Button
-            primary
-            type="button"
-            onClick={handleSubmit}
+            prominence="secondary"
+            onClick={onBack}
             disabled={isSubmitting}
           >
+            Back
+          </Button>
+          <Button type="button" onClick={handleSubmit} disabled={isSubmitting}>
             {isSubmitting ? "Creating..." : "Create Connector"}
           </Button>
         </Section>
diff --git a/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx b/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx
index 7455c30fd55..4f6ddd46647 100644
--- a/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx
+++ b/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx
@@ -5,7 +5,7 @@ import { Formik, Form } from "formik";
 import * as Yup from "yup";
 import { Section } from "@/layouts/general-layouts";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { TextFormField } from "@/components/Field";
 import { ValidSources } from "@/lib/types";
 import {
@@ -40,7 +40,7 @@ export default function CreateCredentialInline({
           No credential configuration available for {sourceMetadata.displayName}
           .
         </Text>
-        <Button action secondary onClick={onCancel}>
+        <Button variant="action" prominence="secondary" onClick={onCancel}>
           Cancel
         </Button>
       </Section>
@@ -150,16 +150,15 @@ export default function CreateCredentialInline({
               height="fit"
             >
               <Button
-                action
-                secondary
+                variant="action"
+                prominence="secondary"
                 onClick={onCancel}
                 disabled={isSubmitting}
               >
                 Cancel
               </Button>
               <Button
-                action
-                primary
+                variant="action"
                 type="submit"
                 disabled={!isValid || !dirty || isSubmitting}
               >
diff --git a/web/src/app/craft/v1/configure/components/CredentialStep.tsx b/web/src/app/craft/v1/configure/components/CredentialStep.tsx
index 4f4b8bab293..b3dccf52ae8 100644
--- a/web/src/app/craft/v1/configure/components/CredentialStep.tsx
+++ b/web/src/app/craft/v1/configure/components/CredentialStep.tsx
@@ -2,7 +2,7 @@
 
 import { useState } from "react";
 import { Section } from "@/layouts/general-layouts";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Modal from "@/refresh-components/Modal";
 import { SvgKey } from "@opal/icons";
 import {
@@ -229,7 +229,7 @@ export default function CredentialStep({
                   ) &&
                     (NEXT_PUBLIC_CLOUD_ENABLED || NEXT_PUBLIC_TEST_ENV) && (
                       <Button
-                        action
+                        variant="action"
                         onClick={handleAuthorize}
                         disabled={isAuthorizing}
                         hidden={!isAuthorizeVisible}
@@ -244,7 +244,6 @@ export default function CredentialStep({
                 </div>
                 {hasCredentials && (
                   <Button
-                    primary
                     onClick={isSingleStep ? handleConnect : onContinue}
                     disabled={!selectedCredential || isConnecting}
                   >
diff --git a/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx b/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx
index 96f61921559..4009ded1f2c 100644
--- a/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx
+++ b/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx
@@ -12,7 +12,7 @@ import {
 } from "@/app/craft/services/apiServices";
 import { LibraryEntry } from "@/app/craft/types/user-library";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Modal from "@/refresh-components/Modal";
 import ShadowDiv from "@/refresh-components/ShadowDiv";
 import { Section } from "@/layouts/general-layouts";
@@ -245,10 +245,10 @@ export default function UserLibraryModal({
                   gap={0.5}
                   padding={0.5}
                 >
-                  <IconButton
+                  <Button
+                    prominence="secondary"
                     icon={SvgFolderPlus}
                     onClick={() => setShowNewFolderModal(true)}
-                    secondary
                     tooltip="New Folder"
                   />
                   <input
@@ -260,13 +260,13 @@ export default function UserLibraryModal({
                     disabled={isUploading}
                     accept=".xlsx,.xls,.docx,.doc,.pptx,.ppt,.csv,.json,.txt,.pdf,.zip"
                   />
-                  <IconButton
+                  <Button
+                    prominence="secondary"
                     icon={SvgUploadCloud}
                     onClick={() => handleUploadToFolder("/")}
                     disabled={isUploading}
                     tooltip={isUploading ? "Uploading..." : "Upload"}
                     aria-label={isUploading ? "Uploading..." : "Upload"}
-                    secondary
                   />
                 </Section>
 
@@ -373,7 +373,7 @@ export default function UserLibraryModal({
           </Modal.Body>
           <Modal.Footer>
             <Button
-              secondary
+              prominence="secondary"
               onClick={() => {
                 setShowNewFolderModal(false);
                 setNewFolderName("");
@@ -457,6 +457,7 @@ function LibraryTreeView({
 
               {/* Expand/collapse for directories */}
               {entry.is_directory ? (
+                // TODO(@raunakab): migrate to opal Button once it supports style prop
                 <IconButton
                   icon={SvgChevronRight}
                   onClick={() => onToggleFolder(entry.path)}
@@ -516,7 +517,8 @@ function LibraryTreeView({
                 height="fit"
               >
                 {entry.is_directory && (
-                  <IconButton
+                  <Button
+                    size="sm"
                     icon={SvgUploadCloud}
                     onClick={(e) => {
                       e.stopPropagation();
@@ -524,15 +526,14 @@ function LibraryTreeView({
                         entry.path.replace(/^user_library/, "") || "/";
                       onUploadToFolder(uploadPath);
                     }}
-                    small
                     tooltip="Upload to this folder"
                   />
                 )}
-                <IconButton
+                <Button
+                  variant="danger"
+                  size="sm"
                   icon={SvgTrash}
                   onClick={() => onDelete(entry)}
-                  small
-                  danger
                   tooltip="Delete"
                 />
               </Section>
diff --git a/web/src/app/craft/v1/configure/page.tsx b/web/src/app/craft/v1/configure/page.tsx
index 334aec27b7c..c3e399e8cc4 100644
--- a/web/src/app/craft/v1/configure/page.tsx
+++ b/web/src/app/craft/v1/configure/page.tsx
@@ -35,7 +35,7 @@ import {
 import { ConfirmEntityModal } from "@/components/modals/ConfirmEntityModal";
 import { getSourceMetadata } from "@/lib/sources";
 import { deleteConnector } from "@/app/craft/services/apiServices";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   OAUTH_STATE_KEY,
   getDemoDataEnabled,
@@ -377,7 +377,7 @@ export default function BuildConfigPage() {
           rightChildren={
             <div className="flex items-center gap-2">
               <Button
-                secondary
+                prominence="secondary"
                 onClick={handleRestoreChanges}
                 disabled={!hasChanges || isUpdating}
               >
diff --git a/web/src/app/ee/admin/billing/BillingInformationPage.tsx b/web/src/app/ee/admin/billing/BillingInformationPage.tsx
index 17a8a2e778a..28329122b72 100644
--- a/web/src/app/ee/admin/billing/BillingInformationPage.tsx
+++ b/web/src/app/ee/admin/billing/BillingInformationPage.tsx
@@ -15,7 +15,7 @@ import {
   CardHeader,
   CardTitle,
 } from "@/components/ui/card";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SubscriptionSummary } from "./SubscriptionSummary";
 import { BillingAlerts } from "./BillingAlerts";
 import { SvgClipboard, SvgWallet } from "@opal/icons";
@@ -97,8 +97,8 @@ export default function BillingInformationPage() {
         <CardContent>
           <Button
             onClick={handleManageSubscription}
-            className="w-full"
-            leftIcon={SvgClipboard}
+            width="full"
+            icon={SvgClipboard}
           >
             Manage Subscription
           </Button>
diff --git a/web/src/app/ee/admin/groups/UserEditor.tsx b/web/src/app/ee/admin/groups/UserEditor.tsx
index 586b4a6f87e..e2965720255 100644
--- a/web/src/app/ee/admin/groups/UserEditor.tsx
+++ b/web/src/app/ee/admin/groups/UserEditor.tsx
@@ -73,6 +73,7 @@ export const UserEditor = ({
           leftSearchIcon
         />
         {onSubmit && (
+          // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
           <Button
             className="ml-3 flex-nowrap w-32"
             onClick={() => onSubmit(selectedUsers)}
diff --git a/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx b/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx
index 52fa890ed76..b5d24873a46 100644
--- a/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx
+++ b/web/src/app/ee/admin/groups/UserGroupCreationForm.tsx
@@ -134,6 +134,7 @@ export default function UserGroupCreationForm({
                   />
                 </div>
                 <div className="flex">
+                  {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                   <Button
                     type="submit"
                     disabled={isSubmitting}
diff --git a/web/src/app/ee/admin/groups/UserGroupsTable.tsx b/web/src/app/ee/admin/groups/UserGroupsTable.tsx
index c6e12125bcf..7acea8beee6 100644
--- a/web/src/app/ee/admin/groups/UserGroupsTable.tsx
+++ b/web/src/app/ee/admin/groups/UserGroupsTable.tsx
@@ -70,6 +70,7 @@ export const UserGroupsTable = ({
               return (
                 <TableRow key={userGroup.id}>
                   <TableCell>
+                    {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                     <Button
                       internal
                       leftIcon={SvgEdit}
diff --git a/web/src/app/ee/admin/groups/[groupId]/AddConnectorForm.tsx b/web/src/app/ee/admin/groups/[groupId]/AddConnectorForm.tsx
index 1fd214fa29c..f309110e3b8 100644
--- a/web/src/app/ee/admin/groups/[groupId]/AddConnectorForm.tsx
+++ b/web/src/app/ee/admin/groups/[groupId]/AddConnectorForm.tsx
@@ -1,4 +1,4 @@
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Modal from "@/refresh-components/Modal";
 import { useState } from "react";
 import { updateUserGroup } from "./lib";
diff --git a/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx b/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx
index 8562667fa91..f1dc014dc93 100644
--- a/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx
+++ b/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx
@@ -26,7 +26,7 @@ import {
   TableRow,
 } from "@/components/ui/table";
 import SimpleTooltip from "@/refresh-components/SimpleTooltip";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { DeleteButton } from "@/components/DeleteButton";
 import { Bubble } from "@/components/Bubble";
 import { BookmarkIcon, RobotIcon } from "@/components/icons/icons";
@@ -34,6 +34,7 @@ import { AddTokenRateLimitForm } from "./AddTokenRateLimitForm";
 import { GenericTokenRateLimitTable } from "@/app/admin/token-rate-limits/TokenRateLimitTables";
 import { useUser } from "@/providers/UserProvider";
 import GenericConfirmModal from "@/components/modals/GenericConfirmModal";
+import Spacer from "@/refresh-components/Spacer";
 
 interface GroupDisplayProps {
   users: User[];
@@ -467,12 +468,12 @@ export const GroupDisplay = ({
       />
 
       {isAdmin && (
-        <Button
-          className="mt-3"
-          onClick={() => setAddRateLimitFormVisible(true)}
-        >
-          Create a Token Rate Limit
-        </Button>
+        <>
+          <Spacer rem={0.75} />
+          <Button onClick={() => setAddRateLimitFormVisible(true)}>
+            Create a Token Rate Limit
+          </Button>
+        </>
       )}
     </div>
   );
diff --git a/web/src/app/ee/admin/performance/custom-analytics/CustomAnalyticsUpdateForm.tsx b/web/src/app/ee/admin/performance/custom-analytics/CustomAnalyticsUpdateForm.tsx
index bf7301b89a6..b79c9363838 100644
--- a/web/src/app/ee/admin/performance/custom-analytics/CustomAnalyticsUpdateForm.tsx
+++ b/web/src/app/ee/admin/performance/custom-analytics/CustomAnalyticsUpdateForm.tsx
@@ -3,11 +3,12 @@
 import { Label, SubLabel } from "@/components/Field";
 import { toast } from "@/hooks/useToast";
 import { SettingsContext } from "@/providers/SettingsProvider";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Callout } from "@/components/ui/callout";
 import Text from "@/components/ui/text";
 import { useContext, useState } from "react";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
+import Spacer from "@/refresh-components/Spacer";
 
 export function CustomAnalyticsUpdateForm() {
   const settings = useContext(SettingsContext);
@@ -94,10 +95,8 @@ export function CustomAnalyticsUpdateForm() {
           value={secretKey}
           onChange={(e) => setSecretKey(e.target.value)}
         />
-
-        <Button className="mt-4" type="submit">
-          Update
-        </Button>
+        <Spacer rem={1} />
+        <Button type="submit">Update</Button>
       </form>
     </div>
   );
diff --git a/web/src/app/ee/admin/performance/query-history/KickoffCSVExport.tsx b/web/src/app/ee/admin/performance/query-history/KickoffCSVExport.tsx
index 97b7ce2c532..0ef76fdd56d 100644
--- a/web/src/app/ee/admin/performance/query-history/KickoffCSVExport.tsx
+++ b/web/src/app/ee/admin/performance/query-history/KickoffCSVExport.tsx
@@ -111,6 +111,7 @@ export default function KickoffCSVExport({
 
   return (
     <div className="flex flex-1 flex-col w-full justify-center">
+      {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
       <Button
         className="ml-auto"
         onClick={startExport}
diff --git a/web/src/app/ee/admin/performance/query-history/QueryHistoryTable.tsx b/web/src/app/ee/admin/performance/query-history/QueryHistoryTable.tsx
index 75bf9b64aed..a418604b598 100644
--- a/web/src/app/ee/admin/performance/query-history/QueryHistoryTable.tsx
+++ b/web/src/app/ee/admin/performance/query-history/QueryHistoryTable.tsx
@@ -40,7 +40,7 @@ import {
 } from "@/app/ee/admin/performance/query-history/constants";
 import { humanReadableFormatWithTime } from "@/lib/time";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Badge } from "@/components/ui/badge";
 import {
   SvgDownloadCloud,
@@ -324,7 +324,7 @@ export function QueryHistoryTable() {
           </div>
           <div className="flex flex-row w-full items-center gap-x-2">
             <KickoffCSVExport dateRange={dateRange} />
-            <Button secondary onClick={() => setShowModal(true)}>
+            <Button prominence="secondary" onClick={() => setShowModal(true)}>
               {PREVIOUS_CSV_TASK_BUTTON_NAME}
             </Button>
           </div>
diff --git a/web/src/app/ee/admin/performance/usage/UsageReports.tsx b/web/src/app/ee/admin/performance/usage/UsageReports.tsx
index a34ee885c69..d7db896dc13 100644
--- a/web/src/app/ee/admin/performance/usage/UsageReports.tsx
+++ b/web/src/app/ee/admin/performance/usage/UsageReports.tsx
@@ -3,7 +3,7 @@
 import { format } from "date-fns";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 
-import { FiDownload, FiDownloadCloud } from "react-icons/fi";
+import { FiDownload } from "react-icons/fi";
 import {
   Table,
   TableBody,
@@ -15,6 +15,7 @@ import {
 import Text from "@/components/ui/text";
 import Title from "@/components/ui/title";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import useSWR from "swr";
 import React, { useState } from "react";
 import { UsageReport } from "./types";
@@ -29,7 +30,7 @@ import Popover from "@/refresh-components/Popover";
 import Calendar from "@/refresh-components/Calendar";
 import { cn } from "@/lib/utils";
 import { Spinner } from "@/components/Spinner";
-import { SvgCalendar } from "@opal/icons";
+import { SvgCalendar, SvgDownloadCloud } from "@opal/icons";
 
 function GenerateReportInput({
   onReportGenerated,
@@ -102,6 +103,7 @@ function GenerateReportInput({
       <div className="grid gap-2 mb-3">
         <Popover>
           <Popover.Trigger asChild>
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               secondary
               className={cn(
@@ -142,9 +144,9 @@ function GenerateReportInput({
               disabled={(date) => date > new Date()}
             />
             <div className="border-t p-3">
-              <Button
-                tertiary
-                className="w-full justify-start"
+              <OpalButton
+                prominence="tertiary"
+                width="full"
                 onClick={() => {
                   setDateRange({
                     from: lastWeek,
@@ -154,10 +156,10 @@ function GenerateReportInput({
                 }}
               >
                 Last 7 days
-              </Button>
-              <Button
-                tertiary
-                className="w-full justify-start"
+              </OpalButton>
+              <OpalButton
+                prominence="tertiary"
+                width="full"
                 onClick={() => {
                   setDateRange({
                     from: lastMonth,
@@ -167,10 +169,10 @@ function GenerateReportInput({
                 }}
               >
                 Last 30 days
-              </Button>
-              <Button
-                tertiary
-                className="w-full justify-start"
+              </OpalButton>
+              <OpalButton
+                prominence="tertiary"
+                width="full"
                 onClick={() => {
                   setDateRange({
                     from: lastYear,
@@ -180,10 +182,10 @@ function GenerateReportInput({
                 }}
               >
                 Last year
-              </Button>
-              <Button
-                tertiary
-                className="w-full justify-start"
+              </OpalButton>
+              <OpalButton
+                prominence="tertiary"
+                width="full"
                 onClick={() => {
                   setDateRange({
                     from: new Date(1970, 0, 1),
@@ -193,19 +195,19 @@ function GenerateReportInput({
                 }}
               >
                 All time
-              </Button>
+              </OpalButton>
             </div>
           </Popover.Content>
         </Popover>
       </div>
-      <Button
+      <OpalButton
         color={"blue"}
-        leftIcon={FiDownloadCloud}
+        icon={SvgDownloadCloud}
         disabled={isLoading || isWaitingForReport}
         onClick={() => requestReport()}
       >
         {isWaitingForReport ? "Generating..." : "Generate Report"}
-      </Button>
+      </OpalButton>
       <p className="mt-1 text-xs">
         {isWaitingForReport
           ? "A report is currently being generated. Please wait..."
diff --git a/web/src/app/ee/admin/standard-answer/StandardAnswerCreationForm.tsx b/web/src/app/ee/admin/standard-answer/StandardAnswerCreationForm.tsx
index 20416782b46..3b34ea771c4 100644
--- a/web/src/app/ee/admin/standard-answer/StandardAnswerCreationForm.tsx
+++ b/web/src/app/ee/admin/standard-answer/StandardAnswerCreationForm.tsx
@@ -198,6 +198,7 @@ export const StandardAnswerCreationForm = ({
                 />
               </div>
               <div className="py-4 flex">
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                 <Button
                   type="submit"
                   disabled={isSubmitting}
diff --git a/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx b/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
index d3cfb97345a..5734f3cc151 100644
--- a/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
+++ b/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
@@ -9,7 +9,7 @@ import InputTextArea from "@/refresh-components/inputs/InputTextArea";
 import Switch from "@/refresh-components/inputs/Switch";
 import CharacterCount from "@/refresh-components/CharacterCount";
 import InputImage from "@/refresh-components/inputs/InputImage";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useFormikContext } from "formik";
 import {
   forwardRef,
@@ -313,10 +313,10 @@ export const AppearanceThemeSettings = forwardRef<
           </FormField.Control>
           <div className="mt-2 w-full justify-center items-center flex">
             <Button
-              secondary
+              prominence="secondary"
               disabled={!hasLogo}
               onClick={handleLogoEdit}
-              leftIcon={SvgEdit}
+              icon={SvgEdit}
             >
               Update
             </Button>
diff --git a/web/src/app/ee/admin/theme/page.tsx b/web/src/app/ee/admin/theme/page.tsx
index 0af15a1e6c1..89264a89068 100644
--- a/web/src/app/ee/admin/theme/page.tsx
+++ b/web/src/app/ee/admin/theme/page.tsx
@@ -2,7 +2,7 @@
 
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   AppearanceThemeSettings,
   AppearanceThemeSettingsRef,
diff --git a/web/src/app/nrf/NRFChrome.tsx b/web/src/app/nrf/NRFChrome.tsx
index 5cfe5e1d0b1..02d995ab401 100644
--- a/web/src/app/nrf/NRFChrome.tsx
+++ b/web/src/app/nrf/NRFChrome.tsx
@@ -7,7 +7,7 @@ import Text from "@/refresh-components/texts/Text";
 import Popover from "@/refresh-components/Popover";
 import { OpenButton } from "@opal/components";
 import LineItem from "@/refresh-components/buttons/LineItem";
-import IconButton from "@/refresh-components/buttons/IconButton";
+import { Button } from "@opal/components";
 import { SvgBubbleText, SvgSearchMenu, SvgSidebar } from "@opal/icons";
 import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
 import { useSettingsContext } from "@/providers/SettingsProvider";
@@ -88,10 +88,10 @@ export default function NRFChrome() {
       {showHeader && (
         <div className="absolute top-0 left-0 p-4 z-10 flex flex-row items-center gap-2">
           {isMobile && (
-            <IconButton
+            <Button
+              prominence="internal"
               icon={SvgSidebar}
               onClick={() => setFolded(false)}
-              internal
             />
           )}
           {showModeToggle && (
diff --git a/web/src/app/nrf/NRFPage.tsx b/web/src/app/nrf/NRFPage.tsx
index 533c9350577..702a8b9e775 100644
--- a/web/src/app/nrf/NRFPage.tsx
+++ b/web/src/app/nrf/NRFPage.tsx
@@ -5,9 +5,8 @@ import { useSearchParams } from "next/navigation";
 import { useUser } from "@/providers/UserProvider";
 import { toast } from "@/hooks/useToast";
 import { AuthType } from "@/lib/constants";
-import Button from "@/refresh-components/buttons/Button";
 import AppInputBar, { AppInputBarHandle } from "@/sections/input/AppInputBar";
-import IconButton from "@/refresh-components/buttons/IconButton";
+import { Button } from "@opal/components";
 import Modal from "@/refresh-components/Modal";
 import { useFilters, useLlmManager } from "@/lib/hooks";
 import Dropzone from "react-dropzone";
@@ -418,10 +417,10 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
       {/* Settings button */}
       {!isSidePanel && (
         <div className="absolute top-0 right-0 p-4 z-10">
-          <IconButton
+          <Button
+            prominence="secondary"
             icon={SvgMenu}
             onClick={toggleSettings}
-            secondary
             tooltip="Open settings"
           />
         </div>
@@ -566,10 +565,13 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
                 onClose={() => setShowTurnOffModal(false)}
               />
               <Modal.Footer>
-                <Button secondary onClick={() => setShowTurnOffModal(false)}>
+                <Button
+                  prominence="secondary"
+                  onClick={() => setShowTurnOffModal(false)}
+                >
                   Cancel
                 </Button>
-                <Button danger onClick={confirmTurnOff}>
+                <Button variant="danger" onClick={confirmTurnOff}>
                   Turn off
                 </Button>
               </Modal.Footer>
@@ -592,8 +594,8 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
               ) : (
                 <div className="flex flex-col items-center">
                   <Button
-                    className="w-full"
-                    secondary
+                    width="full"
+                    prominence="secondary"
                     onClick={() => {
                       if (window.top) {
                         window.top.location.href = "/auth/login";
@@ -613,8 +615,8 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
 
       {user && !llmManager.isLoadingProviders && !llmManager.hasAnyProvider && (
         <Button
-          className="w-full"
-          secondary
+          width="full"
+          prominence="secondary"
           onClick={() => {
             window.location.href = "/admin/configuration/llm";
           }}
diff --git a/web/src/app/nrf/side-panel/SidePanelHeader.tsx b/web/src/app/nrf/side-panel/SidePanelHeader.tsx
index 0c98cdb5279..c799bb8d383 100644
--- a/web/src/app/nrf/side-panel/SidePanelHeader.tsx
+++ b/web/src/app/nrf/side-panel/SidePanelHeader.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import Logo from "@/refresh-components/Logo";
-import IconButton from "@/refresh-components/buttons/IconButton";
+import { Button } from "@opal/components";
 import { SvgEditBig, SvgExternalLink } from "@opal/icons";
 
 interface SidePanelHeaderProps {
@@ -22,16 +22,16 @@ export default function SidePanelHeader({
     <header className="flex items-center justify-between px-4 py-3 border-b border-border-01 bg-background">
       <Logo />
       <div className="flex items-center gap-1">
-        <IconButton
+        <Button
+          prominence="tertiary"
           icon={SvgEditBig}
           onClick={onNewChat}
-          tertiary
           tooltip="New chat"
         />
-        <IconButton
+        <Button
+          prominence="tertiary"
           icon={SvgExternalLink}
           onClick={handleOpenInOnyx}
-          tertiary
           tooltip="Open in Onyx"
         />
       </div>
diff --git a/web/src/components/AdvancedOptionsToggle.tsx b/web/src/components/AdvancedOptionsToggle.tsx
index 4f5f27478e3..d0897316b22 100644
--- a/web/src/components/AdvancedOptionsToggle.tsx
+++ b/web/src/components/AdvancedOptionsToggle.tsx
@@ -13,6 +13,7 @@ export function AdvancedOptionsToggle({
   title,
 }: AdvancedOptionsToggleProps) {
   return (
+    // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
     <Button
       internal
       leftIcon={({ className }) => (
diff --git a/web/src/components/EditableStringFieldDisplay.tsx b/web/src/components/EditableStringFieldDisplay.tsx
index 7b92173a54f..39e457d5db5 100644
--- a/web/src/components/EditableStringFieldDisplay.tsx
+++ b/web/src/components/EditableStringFieldDisplay.tsx
@@ -101,12 +101,14 @@ export function EditableStringFieldDisplay({
       {isEditing && isEditable ? (
         <>
           <div className={cn("flex", "flex-row")}>
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <IconButton
               onClick={handleUpdate}
               internal
               className="ml-2"
               icon={SvgCheck}
             />
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <IconButton
               onClick={resetEditing}
               internal
diff --git a/web/src/components/GenericMultiSelect.tsx b/web/src/components/GenericMultiSelect.tsx
index fddb04b8e7c..cc3731ba099 100644
--- a/web/src/components/GenericMultiSelect.tsx
+++ b/web/src/components/GenericMultiSelect.tsx
@@ -140,6 +140,7 @@ export function GenericMultiSelect<
       {selectedItems.length > 0 && (
         <div className="flex flex-wrap gap-2">
           {selectedItems.map((item) => (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <Button
               key={item.id}
               secondary
diff --git a/web/src/components/admin/ClientLayout.tsx b/web/src/components/admin/ClientLayout.tsx
index 13d66ef6ffe..028f11806c4 100644
--- a/web/src/components/admin/ClientLayout.tsx
+++ b/web/src/components/admin/ClientLayout.tsx
@@ -4,7 +4,7 @@ import AdminSidebar from "@/sections/sidebar/AdminSidebar";
 import { usePathname } from "next/navigation";
 import { useSettingsContext } from "@/providers/SettingsProvider";
 import { ApplicationStatus } from "@/interfaces/settings";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { cn } from "@/lib/utils";
 import { ADMIN_PATHS } from "@/lib/admin-routes";
 
@@ -75,7 +75,7 @@ export function ClientLayout({
           <strong className="font-bold">Warning:</strong> Your trial ends in
           less than 5 days and no payment method has been added.
           <div className="mt-2">
-            <Button className="w-full" href="/admin/billing">
+            <Button width="full" href="/admin/billing">
               Update Billing Information
             </Button>
           </div>
diff --git a/web/src/components/admin/connectors/AccessTypeGroupSelector.tsx b/web/src/components/admin/connectors/AccessTypeGroupSelector.tsx
index aa26b836699..b6098afdb06 100644
--- a/web/src/components/admin/connectors/AccessTypeGroupSelector.tsx
+++ b/web/src/components/admin/connectors/AccessTypeGroupSelector.tsx
@@ -2,7 +2,7 @@ import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidE
 import React, { useState, useEffect } from "react";
 import { FieldArray, ArrayHelpers, ErrorMessage, useField } from "formik";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Separator from "@/refresh-components/Separator";
 import { UserGroup, UserRole } from "@/lib/types";
 import { useUserGroups } from "@/lib/hooks";
@@ -136,10 +136,9 @@ export function AccessTypeGroupSelector({
                       let isSelected = ind !== -1;
                       return (
                         <Button
+                          variant={isSelected ? "action" : "default"}
                           key={userGroup.id}
-                          primary
-                          action={isSelected}
-                          leftIcon={SvgUsers}
+                          icon={SvgUsers}
                           onClick={() => {
                             if (isSelected) {
                               arrayHelpers.remove(ind);
diff --git a/web/src/components/admin/federated/FederatedConnectorForm.tsx b/web/src/components/admin/federated/FederatedConnectorForm.tsx
index 028c9b73d46..d2f937f2c36 100644
--- a/web/src/components/admin/federated/FederatedConnectorForm.tsx
+++ b/web/src/components/admin/federated/FederatedConnectorForm.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useEffect } from "react";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import {
   ConfigurableSources,
   CredentialFieldSpec,
@@ -780,9 +781,9 @@ export function FederatedConnectorForm({
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
                 <div>
-                  <Button secondary leftIcon={SvgSettings}>
+                  <OpalButton prominence="secondary" icon={SvgSettings}>
                     Manage
-                  </Button>
+                  </OpalButton>
                 </div>
               </DropdownMenuTrigger>
               <DropdownMenuContent align="end">
@@ -839,6 +840,7 @@ export function FederatedConnectorForm({
                 </div>
               )}
 
+              {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
               <Button
                 type="button"
                 secondary
@@ -848,6 +850,7 @@ export function FederatedConnectorForm({
               >
                 {isValidating ? "Validating..." : "Validate"}
               </Button>
+              {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
               <Button
                 type="submit"
                 disabled={isSubmitting || !formState.schema}
diff --git a/web/src/components/admin/users/BulkAdd.tsx b/web/src/components/admin/users/BulkAdd.tsx
index 479e8fa958a..c50239b1233 100644
--- a/web/src/components/admin/users/BulkAdd.tsx
+++ b/web/src/components/admin/users/BulkAdd.tsx
@@ -60,6 +60,7 @@ const AddUserFormRenderer = ({
     {touched.emails && errors.emails && (
       <div className="text-error text-sm">{errors.emails}</div>
     )}
+    {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
     <Button type="submit" disabled={isSubmitting} className="self-end">
       Add
     </Button>
diff --git a/web/src/components/admin/users/PendingUsersTable.tsx b/web/src/components/admin/users/PendingUsersTable.tsx
index 8d49d23a8b1..6448c8d8cb2 100644
--- a/web/src/components/admin/users/PendingUsersTable.tsx
+++ b/web/src/components/admin/users/PendingUsersTable.tsx
@@ -11,7 +11,7 @@ import CenteredPageSelector from "./CenteredPageSelector";
 import { ThreeDotsLoader } from "@/components/Loading";
 import { InvitedUserSnapshot } from "@/lib/types";
 import { TableHeader } from "@/components/ui/table";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { FetchError } from "@/lib/fetcher";
 import { ConfirmEntityModal } from "@/components/modals/ConfirmEntityModal";
@@ -107,9 +107,9 @@ const PendingUsersTable = ({ users, mutate, error, isLoading, q }: Props) => {
                 <TableCell>
                   <div className="flex justify-end">
                     <Button
-                      secondary
+                      prominence="secondary"
                       onClick={() => setUserToApprove(user.email.toLowerCase())}
-                      leftIcon={SvgCheck}
+                      icon={SvgCheck}
                     >
                       Accept Join Request
                     </Button>
diff --git a/web/src/components/admin/users/ResetPasswordModal.tsx b/web/src/components/admin/users/ResetPasswordModal.tsx
index 47ca71ef70e..370951e1560 100644
--- a/web/src/components/admin/users/ResetPasswordModal.tsx
+++ b/web/src/components/admin/users/ResetPasswordModal.tsx
@@ -74,6 +74,7 @@ export default function ResetPasswordModal({
               </Text>
             </div>
           ) : (
+            // TODO(@raunakab): migrate to opal Button once it supports ReactNode children
             <Button
               onClick={handleResetPassword}
               disabled={isLoading}
diff --git a/web/src/components/admin/users/SignedUpUserTable.tsx b/web/src/components/admin/users/SignedUpUserTable.tsx
index 668a2d3ed08..9812e342bf3 100644
--- a/web/src/components/admin/users/SignedUpUserTable.tsx
+++ b/web/src/components/admin/users/SignedUpUserTable.tsx
@@ -295,6 +295,7 @@ export default function SignedUpUserTable({
               </>
             )}
             {user.password_configured && (
+              // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
               <Button
                 className={buttonClassName}
                 onClick={() => handleResetPassword(user)}
diff --git a/web/src/components/admin/users/buttons/DeactivateUserButton.tsx b/web/src/components/admin/users/buttons/DeactivateUserButton.tsx
index 4796faee543..6451beafeb0 100644
--- a/web/src/components/admin/users/buttons/DeactivateUserButton.tsx
+++ b/web/src/components/admin/users/buttons/DeactivateUserButton.tsx
@@ -31,6 +31,7 @@ const DeactivateUserButton = ({
     }
   );
   return (
+    // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
     <Button
       className={className}
       onClick={() => trigger({ user_email: user.email })}
diff --git a/web/src/components/admin/users/buttons/DeleteUserButton.tsx b/web/src/components/admin/users/buttons/DeleteUserButton.tsx
index c33224dc8ca..4dfad2e426e 100644
--- a/web/src/components/admin/users/buttons/DeleteUserButton.tsx
+++ b/web/src/components/admin/users/buttons/DeleteUserButton.tsx
@@ -43,6 +43,7 @@ const DeleteUserButton = ({
         />
       )}
 
+      {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
       <Button
         className={className}
         onClick={() => setShowDeleteModal(true)}
diff --git a/web/src/components/admin/users/buttons/InviteUserButton.tsx b/web/src/components/admin/users/buttons/InviteUserButton.tsx
index 1dce674cf5d..4e9ee594d41 100644
--- a/web/src/components/admin/users/buttons/InviteUserButton.tsx
+++ b/web/src/components/admin/users/buttons/InviteUserButton.tsx
@@ -5,7 +5,7 @@ import {
 
 import { toast } from "@/hooks/useToast";
 import useSWRMutation from "swr/mutation";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import GenericConfirmModal from "@/components/modals/GenericConfirmModal";
 import { useState } from "react";
 
diff --git a/web/src/components/admin/users/buttons/LeaveOrganizationButton.tsx b/web/src/components/admin/users/buttons/LeaveOrganizationButton.tsx
index 8340ea76e79..cabf02b18fc 100644
--- a/web/src/components/admin/users/buttons/LeaveOrganizationButton.tsx
+++ b/web/src/components/admin/users/buttons/LeaveOrganizationButton.tsx
@@ -51,6 +51,7 @@ export const LeaveOrganizationButton = ({
         />
       )}
 
+      {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
       <Button
         className={className}
         onClick={() => setShowLeaveModal(true)}
diff --git a/web/src/components/chat/FederatedOAuthModal.tsx b/web/src/components/chat/FederatedOAuthModal.tsx
index 842b365e4b6..7f8799f5b98 100644
--- a/web/src/components/chat/FederatedOAuthModal.tsx
+++ b/web/src/components/chat/FederatedOAuthModal.tsx
@@ -2,7 +2,7 @@
 
 import { useContext, useState } from "react";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { ValidSources } from "@/lib/types";
 import { SettingsContext } from "@/providers/SettingsProvider";
 import { getSourceMetadata } from "@/lib/sources";
@@ -144,7 +144,7 @@ export default function FederatedOAuthModal() {
                   variant="section"
                   rightChildren={
                     <Button
-                      secondary
+                      prominence="secondary"
                       target="_blank"
                       href={connector.authorize_url}
                     >
diff --git a/web/src/components/chat/MCPApiKeyModal.tsx b/web/src/components/chat/MCPApiKeyModal.tsx
index 422e58cd1eb..a17d90489a9 100644
--- a/web/src/components/chat/MCPApiKeyModal.tsx
+++ b/web/src/components/chat/MCPApiKeyModal.tsx
@@ -2,7 +2,7 @@
 
 import { useState, useEffect } from "react";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { Input } from "@/components/ui/input";
 import Label from "@/refresh-components/form/Label";
 import Text from "@/refresh-components/texts/Text";
@@ -250,7 +250,11 @@ export default function MCPApiKeyModal({
             )}
 
             <div className="flex justify-end space-x-2 pt-4">
-              <Button secondary onClick={handleClose} disabled={isSubmitting}>
+              <Button
+                prominence="secondary"
+                onClick={handleClose}
+                disabled={isSubmitting}
+              >
                 Cancel
               </Button>
               <Button
diff --git a/web/src/components/credentials/actions/CreateCredential.tsx b/web/src/components/credentials/actions/CreateCredential.tsx
index f7404a7aeed..3235bb70d1b 100644
--- a/web/src/components/credentials/actions/CreateCredential.tsx
+++ b/web/src/components/credentials/actions/CreateCredential.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import { ValidSources, AccessType } from "@/lib/types";
 import { FaAccusoft } from "react-icons/fa";
 import { submitCredential } from "@/components/admin/connectors/CredentialForm";
@@ -35,13 +36,13 @@ const CreateButton = ({
   isAdmin: boolean;
   groups: number[];
 }) => (
-  <Button
+  <OpalButton
     onClick={onClick}
     disabled={isSubmitting || (!isAdmin && groups.length === 0)}
-    leftIcon={SvgPlusCircle}
+    icon={SvgPlusCircle}
   >
     Create
-  </Button>
+  </OpalButton>
 );
 
 type formType = IsPublicGroupSelectorFormType & {
@@ -257,6 +258,7 @@ export default function CreateCredential({
               )}
             </CardSection>
             {swapConnector && (
+              // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
               <Button
                 className="bg-rose-500 hover:bg-rose-400"
                 onClick={() =>
diff --git a/web/src/components/credentials/actions/CreateStdOAuthCredential.tsx b/web/src/components/credentials/actions/CreateStdOAuthCredential.tsx
index 57849c1956b..3cf312f8431 100644
--- a/web/src/components/credentials/actions/CreateStdOAuthCredential.tsx
+++ b/web/src/components/credentials/actions/CreateStdOAuthCredential.tsx
@@ -1,6 +1,6 @@
 import * as Yup from "yup";
 
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { ValidSources } from "@/lib/types";
 import { TextFormField } from "@/components/Field";
 import { Form, Formik, FormikHelpers } from "formik";
diff --git a/web/src/components/credentials/actions/EditCredential.tsx b/web/src/components/credentials/actions/EditCredential.tsx
index 1e44f81e73d..28d66f14157 100644
--- a/web/src/components/credentials/actions/EditCredential.tsx
+++ b/web/src/components/credentials/actions/EditCredential.tsx
@@ -1,4 +1,4 @@
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/components/ui/text";
 
 import { FaNewspaper, FaTrash } from "react-icons/fa";
@@ -93,15 +93,10 @@ export default function EditCredential({
               )
             )}
             <div className="flex justify-between w-full">
-              <Button onClick={() => resetForm()} leftIcon={SvgTrash}>
+              <Button onClick={() => resetForm()} icon={SvgTrash}>
                 Reset Changes
               </Button>
-              <Button
-                type="submit"
-                disabled={isSubmitting}
-                className="bg-indigo-500 hover:bg-indigo-400"
-                leftIcon={FaNewspaper}
-              >
+              <Button type="submit" disabled={isSubmitting} icon={FaNewspaper}>
                 Update
               </Button>
             </div>
diff --git a/web/src/components/credentials/actions/ModifyCredential.tsx b/web/src/components/credentials/actions/ModifyCredential.tsx
index 121ad923f1b..12d30e07868 100644
--- a/web/src/components/credentials/actions/ModifyCredential.tsx
+++ b/web/src/components/credentials/actions/ModifyCredential.tsx
@@ -1,6 +1,5 @@
 import React, { useState } from "react";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
 import Text from "@/refresh-components/texts/Text";
 import { Badge } from "@/components/ui/badge";
 import { AccessType } from "@/lib/types";
@@ -10,8 +9,13 @@ import {
   Credential,
 } from "@/lib/connectors/credentials";
 import { Connector } from "@/lib/connectors/connectors";
-import { SvgAlertTriangle, SvgTrash } from "@opal/icons";
-import { Button as OpalButton } from "@opal/components";
+import {
+  SvgArrowExchange,
+  SvgAlertTriangle,
+  SvgBubbleText,
+  SvgTrash,
+} from "@opal/icons";
+import { Button } from "@opal/components";
 interface CredentialSelectionTableProps {
   credentials: Credential<any>[];
   editableCredentials: Credential<any>[];
@@ -115,7 +119,7 @@ function CredentialSelectionTable({
                     {new Date(credential.time_updated).toLocaleString()}
                   </td>
                   <td className="p-2 flex gap-x-2 content-center mt-auto">
-                    <OpalButton
+                    <Button
                       onClick={async () => {
                         onDeleteCredential(credential);
                       }}
@@ -212,7 +216,7 @@ export default function ModifyCredential({
                 Confirm
               </Button>
               <Button
-                secondary
+                prominence="secondary"
                 onClick={() => setConfirmDeletionCredential(null)}
               >
                 Cancel
@@ -255,18 +259,8 @@ export default function ModifyCredential({
         {!showIfEmpty && (
           <div className="flex mt-8 justify-between">
             {onCreateNew ? (
-              <Button
-                onClick={() => {
-                  onCreateNew();
-                }}
-                className="bg-background-500 disabled:border-transparent
-              transition-colors duration-150 ease-in disabled:bg-background-300
-              disabled:hover:bg-background-300 hover:bg-background-600 cursor-pointer"
-              >
-                <div className="flex gap-x-2 items-center w-full border-none">
-                  <NewChatIcon className="text-white" />
-                  <p>Create</p>
-                </div>
+              <Button onClick={onCreateNew} icon={SvgBubbleText}>
+                Create
               </Button>
             ) : (
               <div />
@@ -285,14 +279,9 @@ export default function ModifyCredential({
                   onSwitch(selectedCredential!);
                 }
               }}
-              className="bg-indigo-500 disabled:border-transparent
-              transition-colors duration-150 ease-in disabled:bg-indigo-300
-              disabled:hover:bg-indigo-300 hover:bg-indigo-600 cursor-pointer"
+              icon={SvgArrowExchange}
             >
-              <div className="flex gap-x-2 items-center w-full border-none">
-                <SwapIcon className="text-white" />
-                <p>Select</p>
-              </div>
+              Select
             </Button>
           </div>
         )}
diff --git a/web/src/components/dateRangeSelectors/AdminDateRangeSelector.tsx b/web/src/components/dateRangeSelectors/AdminDateRangeSelector.tsx
index a0a0f22ce2c..5b19b7584fa 100644
--- a/web/src/components/dateRangeSelectors/AdminDateRangeSelector.tsx
+++ b/web/src/components/dateRangeSelectors/AdminDateRangeSelector.tsx
@@ -2,6 +2,7 @@ import React, { memo, useState } from "react";
 import Calendar from "@/refresh-components/Calendar";
 import Popover from "@/refresh-components/Popover";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import { cn } from "@/lib/utils";
 import { format } from "date-fns";
 import { getXDaysAgo } from "./dateUtils";
@@ -49,6 +50,7 @@ export const AdminDateRangeSelector = memo(function AdminDateRangeSelector({
     <div className="grid gap-2">
       <Popover open={isOpen} onOpenChange={setIsOpen}>
         <Popover.Trigger asChild>
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <Button
             secondary
             className={cn("justify-start", !value && "text-muted-foreground")}
@@ -87,16 +89,16 @@ export const AdminDateRangeSelector = memo(function AdminDateRangeSelector({
           />
           <div className="border-t p-3">
             {presets.map((preset) => (
-              <Button
+              <OpalButton
                 key={preset.label}
-                internal
-                className="w-full justify-start"
+                prominence="internal"
+                width="full"
                 onClick={() => {
                   onValueChange(preset.value);
                 }}
               >
                 {preset.label}
-              </Button>
+              </OpalButton>
             ))}
           </div>
         </Popover.Content>
diff --git a/web/src/components/embedding/CustomEmbeddingModelForm.tsx b/web/src/components/embedding/CustomEmbeddingModelForm.tsx
index ef5afdcedb5..4a7441ce41d 100644
--- a/web/src/components/embedding/CustomEmbeddingModelForm.tsx
+++ b/web/src/components/embedding/CustomEmbeddingModelForm.tsx
@@ -99,6 +99,7 @@ export function CustomEmbeddingModelForm({
               subtext="Prefix for passage embeddings"
             />
 
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               type="submit"
               disabled={isSubmitting}
diff --git a/web/src/components/embedding/CustomModelForm.tsx b/web/src/components/embedding/CustomModelForm.tsx
index 22b88485029..d5cabc7fe1a 100644
--- a/web/src/components/embedding/CustomModelForm.tsx
+++ b/web/src/components/embedding/CustomModelForm.tsx
@@ -100,6 +100,7 @@ export function CustomModelForm({
               subtext="Whether or not to normalize the embeddings generated by the model. When in doubt, leave this checked."
             />
 
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               type="submit"
               disabled={isSubmitting}
diff --git a/web/src/components/embedding/FailedReIndexAttempts.tsx b/web/src/components/embedding/FailedReIndexAttempts.tsx
index ea716df375b..f86d1175c98 100644
--- a/web/src/components/embedding/FailedReIndexAttempts.tsx
+++ b/web/src/components/embedding/FailedReIndexAttempts.tsx
@@ -3,7 +3,7 @@ import { PageSelector } from "@/components/PageSelector";
 import { IndexAttemptStatus } from "@/components/Status";
 import { deleteCCPair } from "@/lib/documentDeletion";
 import { FailedConnectorIndexingStatus } from "@/lib/types";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { ConfirmEntityModal } from "@/components/modals/ConfirmEntityModal";
 import {
   Table,
@@ -129,7 +129,7 @@ export function FailedReIndexAttempts({
                     </TableCell>
                     <TableCell>
                       <Button
-                        danger
+                        variant="danger"
                         onClick={async () => {
                           if (shouldConfirmConnectorDeletion) {
                             setPendingConnectorDeletion({
@@ -159,7 +159,7 @@ export function FailedReIndexAttempts({
                             );
                           }
                         }}
-                        leftIcon={SvgTrash}
+                        icon={SvgTrash}
                         disabled={!reindexingProgress.is_deletable}
                       >
                         Delete
diff --git a/web/src/components/errorPages/AccessRestrictedPage.tsx b/web/src/components/errorPages/AccessRestrictedPage.tsx
index 39c48431325..d6b3129b0c8 100644
--- a/web/src/components/errorPages/AccessRestrictedPage.tsx
+++ b/web/src/components/errorPages/AccessRestrictedPage.tsx
@@ -3,7 +3,7 @@
 import { useState } from "react";
 import Link from "next/link";
 import ErrorPageLayout from "@/components/errorPages/ErrorPageLayout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
 import { logout } from "@/lib/user";
 import { loadStripe } from "@stripe/stripe-js";
@@ -140,7 +140,7 @@ export default function AccessRestricted() {
               {isLoading ? "Loading..." : "Resubscribe"}
             </Button>
             <Button
-              secondary
+              prominence="secondary"
               onClick={async () => {
                 await logout();
                 window.location.reload();
diff --git a/web/src/components/modals/AddInstructionModal.tsx b/web/src/components/modals/AddInstructionModal.tsx
index 68717b48331..e8e2f131456 100644
--- a/web/src/components/modals/AddInstructionModal.tsx
+++ b/web/src/components/modals/AddInstructionModal.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useState } from "react";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useProjectsContext } from "@/providers/ProjectsContext";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
 import { useModal } from "@/refresh-components/contexts/ModalContext";
@@ -46,7 +46,7 @@ export default function AddInstructionModal() {
           />
         </Modal.Body>
         <Modal.Footer>
-          <Button secondary onClick={() => modal.toggle(false)}>
+          <Button prominence="secondary" onClick={() => modal.toggle(false)}>
             Cancel
           </Button>
           <Button onClick={handleSubmit}>Save Instructions</Button>
diff --git a/web/src/components/modals/ConfirmEntityModal.tsx b/web/src/components/modals/ConfirmEntityModal.tsx
index 3b028348669..12f7203018a 100644
--- a/web/src/components/modals/ConfirmEntityModal.tsx
+++ b/web/src/components/modals/ConfirmEntityModal.tsx
@@ -1,5 +1,5 @@
 import Modal from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { SvgAlertCircle } from "@opal/icons";
 import type { IconProps } from "@opal/types";
@@ -54,7 +54,7 @@ export function ConfirmEntityModal({
       title={`${buttonText} ${entityType}`}
       onClose={onClose}
       submit={
-        <Button onClick={onSubmit} danger={danger}>
+        <Button variant={danger ? "danger" : "default"} onClick={onSubmit}>
           {buttonText}
         </Button>
       }
diff --git a/web/src/components/modals/CreateProjectModal.tsx b/web/src/components/modals/CreateProjectModal.tsx
index 58ec3683746..9e3d8d8a791 100644
--- a/web/src/components/modals/CreateProjectModal.tsx
+++ b/web/src/components/modals/CreateProjectModal.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState, useEffect } from "react";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useProjectsContext } from "@/providers/ProjectsContext";
 import { useKeyPress } from "@/hooks/useKeyPress";
 import * as InputLayouts from "@/layouts/input-layouts";
@@ -65,7 +65,7 @@ export default function CreateProjectModal({
             </InputLayouts.Vertical>
           </Modal.Body>
           <Modal.Footer>
-            <Button secondary onClick={() => modal.toggle(false)}>
+            <Button prominence="secondary" onClick={() => modal.toggle(false)}>
               Cancel
             </Button>
             <Button onClick={handleSubmit}>Create Project</Button>
diff --git a/web/src/components/modals/EditPropertyModal.tsx b/web/src/components/modals/EditPropertyModal.tsx
index 3de62ef9b1f..dd93300c51a 100644
--- a/web/src/components/modals/EditPropertyModal.tsx
+++ b/web/src/components/modals/EditPropertyModal.tsx
@@ -1,6 +1,6 @@
 import { Formik, Form } from "formik";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { TextFormField } from "@/components/Field";
 import { SvgEdit } from "@opal/icons";
 export interface EditPropertyModalProps {
diff --git a/web/src/components/modals/GenericConfirmModal.tsx b/web/src/components/modals/GenericConfirmModal.tsx
index 062689adc81..f9f4f8bbdec 100644
--- a/web/src/components/modals/GenericConfirmModal.tsx
+++ b/web/src/components/modals/GenericConfirmModal.tsx
@@ -1,5 +1,5 @@
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { SvgCheck } from "@opal/icons";
 export interface GenericConfirmModalProps {
diff --git a/web/src/components/modals/MoveCustomAgentChatModal.tsx b/web/src/components/modals/MoveCustomAgentChatModal.tsx
index 727013046b0..82cc822829f 100644
--- a/web/src/components/modals/MoveCustomAgentChatModal.tsx
+++ b/web/src/components/modals/MoveCustomAgentChatModal.tsx
@@ -2,7 +2,7 @@
 
 import { useState } from "react";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Checkbox from "@/refresh-components/inputs/Checkbox";
 import Text from "@/refresh-components/texts/Text";
 import { SvgAlertCircle } from "@opal/icons";
@@ -23,9 +23,7 @@ export default function MoveCustomAgentChatModal({
       title="Move Custom Agent Chat"
       onClose={onCancel}
       submit={
-        <Button primary onClick={() => onConfirm(doNotShowAgain)}>
-          Confirm Move
-        </Button>
+        <Button onClick={() => onConfirm(doNotShowAgain)}>Confirm Move</Button>
       }
     >
       <div className="flex flex-col gap-4">
diff --git a/web/src/components/modals/NewTeamModal.tsx b/web/src/components/modals/NewTeamModal.tsx
index 9a3f8a2caac..3b2a818ce0b 100644
--- a/web/src/components/modals/NewTeamModal.tsx
+++ b/web/src/components/modals/NewTeamModal.tsx
@@ -4,7 +4,7 @@ import { useState, useEffect } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import type { Route } from "next";
 import { Dialog } from "@headlessui/react";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { toast } from "@/hooks/useToast";
 import { useUser } from "@/providers/UserProvider";
 import { useModalContext } from "../context/ModalContext";
@@ -160,7 +160,7 @@ export default function NewTeamModal() {
               <div className="flex w-full pt-2">
                 <Button
                   onClick={handleContinueToNewOrg}
-                  className="w-full"
+                  width="full"
                   rightIcon={SvgArrowRight}
                 >
                   Continue with new team
@@ -177,7 +177,7 @@ export default function NewTeamModal() {
               <div className="flex w-full pt-2">
                 <Button
                   onClick={handleContinueToNewOrg}
-                  className="w-full"
+                  width="full"
                   rightIcon={SvgArrowRight}
                 >
                   Try Onyx while waiting
@@ -192,9 +192,9 @@ export default function NewTeamModal() {
               <div className="flex flex-col items-center justify-center gap-4 mt-4">
                 <Button
                   onClick={handleRequestInvite}
-                  className="w-full"
+                  width="full"
                   disabled={isSubmitting}
-                  leftIcon={isSubmitting ? SimpleLoader : SvgArrowUp}
+                  icon={isSubmitting ? SimpleLoader : SvgArrowUp}
                 >
                   {isSubmitting
                     ? "Sending request..."
@@ -203,9 +203,9 @@ export default function NewTeamModal() {
               </div>
               <Button
                 onClick={handleContinueToNewOrg}
-                className="w-full"
-                leftIcon={SvgPlus}
-                secondary
+                width="full"
+                icon={SvgPlus}
+                prominence="secondary"
               >
                 Continue with new team
               </Button>
diff --git a/web/src/components/modals/NoAgentModal.tsx b/web/src/components/modals/NoAgentModal.tsx
index a115a825f46..8fce6055e7d 100644
--- a/web/src/components/modals/NoAgentModal.tsx
+++ b/web/src/components/modals/NoAgentModal.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { useUser } from "@/providers/UserProvider";
 import { SvgUser } from "@opal/icons";
@@ -24,7 +24,7 @@ export default function NoAgentModal() {
                 As an administrator, you can create a new agent by visiting the
                 admin panel.
               </Text>
-              <Button className="w-full" href="/admin/agents">
+              <Button width="full" href="/admin/agents">
                 Go to Admin Panel
               </Button>
             </>
diff --git a/web/src/components/modals/ProviderModal.tsx b/web/src/components/modals/ProviderModal.tsx
index 8cc5f07b9c2..90ea974fce8 100644
--- a/web/src/components/modals/ProviderModal.tsx
+++ b/web/src/components/modals/ProviderModal.tsx
@@ -1,5 +1,5 @@
 import React from "react";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import type { IconProps } from "@opal/types";
 import Modal from "@/refresh-components/Modal";
 import { SvgLoader } from "@opal/icons";
@@ -76,14 +76,18 @@ export default function ProviderModal({
 
         {onSubmit && (
           <Modal.Footer>
-            <Button type="button" secondary onClick={() => onOpenChange(false)}>
+            <Button
+              prominence="secondary"
+              type="button"
+              onClick={() => onOpenChange(false)}
+            >
               {cancelLabel}
             </Button>
             <Button
               type="button"
               onClick={onSubmit}
               disabled={submitDisabled || isSubmitting}
-              leftIcon={isSubmitting ? SpinningLoader : undefined}
+              icon={isSubmitting ? SpinningLoader : undefined}
             >
               {submitLabel}
             </Button>
diff --git a/web/src/components/modals/UserFilesModal.tsx b/web/src/components/modals/UserFilesModal.tsx
index 5a0bc2e2198..ddd53c746c0 100644
--- a/web/src/components/modals/UserFilesModal.tsx
+++ b/web/src/components/modals/UserFilesModal.tsx
@@ -9,7 +9,6 @@ import type { IconProps } from "@opal/types";
 import { getFileExtension, isImageExtension } from "@/lib/utils";
 import { UserFileStatus } from "@/app/app/projects/projectsService";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import Button from "@/refresh-components/buttons/Button";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import AttachmentButton from "@/refresh-components/buttons/AttachmentButton";
 import Modal from "@/refresh-components/Modal";
@@ -25,7 +24,7 @@ import {
 } from "@opal/icons";
 import { Section } from "@/layouts/general-layouts";
 import useFilter from "@/hooks/useFilter";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import ScrollIndicatorDiv from "@/refresh-components/ScrollIndicatorDiv";
 
 function getIcon(
@@ -269,14 +268,14 @@ export default function UserFilesModal({
                   {selectedCount} {selectedCount === 1 ? "file" : "files"}{" "}
                   selected
                 </Text>
-                <OpalButton
+                <Button
                   icon={SvgEye}
                   prominence="tertiary"
                   size="sm"
                   onClick={() => setShowOnlySelected(!showOnlySelected)}
                   transient={showOnlySelected}
                 />
-                <OpalButton
+                <Button
                   icon={SvgXCircle}
                   prominence="tertiary"
                   size="sm"
@@ -287,7 +286,7 @@ export default function UserFilesModal({
             )}
 
             {/* Right side: Done button */}
-            <Button secondary onClick={() => toggle(false)}>
+            <Button prominence="secondary" onClick={() => toggle(false)}>
               Done
             </Button>
           </Modal.Footer>
diff --git a/web/src/components/oauth/OAuthCallbackPage.tsx b/web/src/components/oauth/OAuthCallbackPage.tsx
index 159d9e7af63..e6964817d32 100644
--- a/web/src/components/oauth/OAuthCallbackPage.tsx
+++ b/web/src/components/oauth/OAuthCallbackPage.tsx
@@ -5,7 +5,7 @@ import { useRouter, useSearchParams } from "next/navigation";
 import type { Route } from "next";
 import { CheckmarkIcon, TriangleAlertIcon } from "@/components/icons/icons";
 import CardSection from "@/components/admin/CardSection";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 
 interface OAuthCallbackConfig {
   // UI customization
@@ -265,7 +265,7 @@ export default function OAuthCallbackPage({ config }: OAuthCallbackPageProps) {
                         redirectPath || config.defaultRedirectPath || "/app";
                       router.push(target as Route);
                     }}
-                    className="w-full"
+                    width="full"
                   >
                     {config.backButtonText || "Back to Chat"}
                   </Button>
diff --git a/web/src/components/sidebar/ChatSessionMorePopup.tsx b/web/src/components/sidebar/ChatSessionMorePopup.tsx
index b539d8e4ab7..5c957cfc856 100644
--- a/web/src/components/sidebar/ChatSessionMorePopup.tsx
+++ b/web/src/components/sidebar/ChatSessionMorePopup.tsx
@@ -15,7 +15,7 @@ import MoveCustomAgentChatModal from "@/components/modals/MoveCustomAgentChatMod
 // PopoverMenu already imported above
 import { cn, noProp } from "@/lib/utils";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { PopoverSearchInput } from "@/sections/sidebar/ChatButton";
 import LineItem from "@/refresh-components/buttons/LineItem";
 import { SvgFolder, SvgFolderIn, SvgShare, SvgTrash } from "@opal/icons";
@@ -252,7 +252,7 @@ export function ChatSessionMorePopup({
           icon={SvgTrash}
           onClose={() => setIsDeleteModalOpen(false)}
           submit={
-            <Button danger onClick={handleConfirmDelete}>
+            <Button variant="danger" onClick={handleConfirmDelete}>
               Delete
             </Button>
           }
diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index 18ec196064b..c15446dd006 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -23,7 +23,6 @@
 import { cn, ensureHrefProtocol, noProp } from "@/lib/utils";
 import type { Components } from "react-markdown";
 import Text from "@/refresh-components/texts/Text";
-import RefreshButton from "@/refresh-components/buttons/Button";
 import { useCallback, useMemo, useState, useEffect } from "react";
 import { useAppBackground } from "@/providers/AppBackgroundProvider";
 import { useTheme } from "next-themes";
@@ -287,9 +286,9 @@ function Header() {
           icon={SvgTrash}
           onClose={() => setDeleteModalOpen(false)}
           submit={
-            <RefreshButton danger onClick={handleDeleteChat}>
+            <Button variant="danger" onClick={handleDeleteChat}>
               Delete
-            </RefreshButton>
+            </Button>
           }
         >
           Are you sure you want to delete this chat? This action cannot be
@@ -314,10 +313,10 @@ function Header() {
         */}
         <div className="flex-1 flex flex-row items-center gap-2 h-[3.3rem]">
           {isMobile && (
-            <IconButton
+            <Button
+              prominence="internal"
               icon={SvgSidebar}
               onClick={() => setFolded(false)}
-              internal
             />
           )}
           {isPaidEnterpriseFeaturesEnabled &&
@@ -403,6 +402,7 @@ function Header() {
               </Button>
               <SimplePopover
                 trigger={
+                  /* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */
                   <IconButton
                     icon={SvgMoreHorizontal}
                     className="ml-2"
diff --git a/web/src/refresh-components/Calendar.tsx b/web/src/refresh-components/Calendar.tsx
index 1e8192c500e..1b6bc6e20a0 100644
--- a/web/src/refresh-components/Calendar.tsx
+++ b/web/src/refresh-components/Calendar.tsx
@@ -19,6 +19,7 @@ function CalendarDayButton({
   }, [modifiers.focused]);
 
   return (
+    // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
     <Button
       ref={ref}
       tertiary
diff --git a/web/src/refresh-components/buttons/AttachmentButton.tsx b/web/src/refresh-components/buttons/AttachmentButton.tsx
index 8a74324a8f3..79d497bab88 100644
--- a/web/src/refresh-components/buttons/AttachmentButton.tsx
+++ b/web/src/refresh-components/buttons/AttachmentButton.tsx
@@ -129,6 +129,7 @@ export default function AttachmentButton({
               </Truncated>
             </div>
             {onView && (
+              // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
               <IconButton
                 icon={SvgExternalLink}
                 onClick={noProp(onView)}
diff --git a/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx b/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx
index 5069c798037..45d3eee5c82 100644
--- a/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx
+++ b/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx
@@ -2,7 +2,7 @@
 
 import React, { memo } from "react";
 import Text from "@/refresh-components/texts/Text";
-import IconButton from "@/refresh-components/buttons/IconButton";
+import { Button } from "@opal/components";
 import {
   SvgArrowLeft,
   SvgArrowRight,
@@ -90,21 +90,19 @@ const SourceTagDetailsCardInner = ({
       {showNavigation && (
         <div className="flex items-center justify-between p-2 bg-background-tint-01 border-b border-border-01">
           <div className="flex items-center gap-1">
-            <IconButton
-              main
-              internal
+            <Button
+              prominence="internal"
               icon={SvgArrowLeft}
               onClick={onPrev}
               disabled={isFirst}
-              className="!p-0.5"
+              size="sm"
             />
-            <IconButton
-              main
-              internal
+            <Button
+              prominence="internal"
               icon={SvgArrowRight}
               onClick={onNext}
               disabled={isLast}
-              className="!p-0.5"
+              size="sm"
             />
           </div>
           <Text secondaryBody text03 className="px-1">
diff --git a/web/src/refresh-components/cards/Select.tsx b/web/src/refresh-components/cards/Select.tsx
index 3c6b37626a4..11a32bcc186 100644
--- a/web/src/refresh-components/cards/Select.tsx
+++ b/web/src/refresh-components/cards/Select.tsx
@@ -5,8 +5,7 @@ import type { IconProps } from "@opal/types";
 import { cn, noProp } from "@/lib/utils";
 import { Disabled } from "@/refresh-components/Disabled";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import SelectButton from "@/refresh-components/buttons/SelectButton";
 import {
   SvgArrowExchange,
@@ -126,8 +125,7 @@ export default function Select({
           {/* Disconnected: Show Connect button */}
           {isDisconnected && (
             <Button
-              action={false}
-              tertiary
+              prominence="tertiary"
               disabled={disabled || !onConnect}
               onClick={noProp(onConnect)}
               rightIcon={SvgArrowExchange}
@@ -150,7 +148,7 @@ export default function Select({
                 {selectLabel}
               </SelectButton>
               {onEdit && (
-                <OpalButton
+                <Button
                   icon={SvgSettings}
                   tooltip="Edit"
                   prominence="tertiary"
@@ -176,7 +174,7 @@ export default function Select({
                 {selectedLabel}
               </SelectButton>
               {onEdit && (
-                <OpalButton
+                <Button
                   icon={SvgSettings}
                   tooltip="Edit"
                   prominence="tertiary"
diff --git a/web/src/refresh-components/inputs/InputDatePicker.tsx b/web/src/refresh-components/inputs/InputDatePicker.tsx
index 15aef08ce64..7c57d835358 100644
--- a/web/src/refresh-components/inputs/InputDatePicker.tsx
+++ b/web/src/refresh-components/inputs/InputDatePicker.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Calendar from "@/refresh-components/Calendar";
 import Popover from "@/refresh-components/Popover";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
@@ -40,7 +40,7 @@ export default function InputDatePicker({
   return (
     <Popover open={open} onOpenChange={setOpen}>
       <Popover.Trigger asChild id={name} name={name}>
-        <Button leftIcon={SvgCalendar} secondary disabled={disabled}>
+        <Button prominence="secondary" icon={SvgCalendar} disabled={disabled}>
           {selectedDate ? selectedDate.toLocaleDateString() : "Select Date"}
         </Button>
       </Popover.Trigger>
diff --git a/web/src/refresh-components/inputs/InputImage.tsx b/web/src/refresh-components/inputs/InputImage.tsx
index a8e004ce4e4..623fbe0e70e 100644
--- a/web/src/refresh-components/inputs/InputImage.tsx
+++ b/web/src/refresh-components/inputs/InputImage.tsx
@@ -259,6 +259,7 @@ export default function InputImage({
             "transition-opacity duration-150"
           )}
         >
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <IconButton
             icon={SvgX}
             onClick={noProp(onRemove)}
diff --git a/web/src/refresh-components/inputs/InputKeyValue.tsx b/web/src/refresh-components/inputs/InputKeyValue.tsx
index afb8eedc34a..e326a56c88b 100644
--- a/web/src/refresh-components/inputs/InputKeyValue.tsx
+++ b/web/src/refresh-components/inputs/InputKeyValue.tsx
@@ -78,8 +78,7 @@ import React, {
 } from "react";
 import { cn } from "@/lib/utils";
 import InputTypeIn from "./InputTypeIn";
-import { Button as OpalButton } from "@opal/components";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { FieldContext } from "../form/FieldContext";
 import { FieldMessage } from "../messages/FieldMessage";
@@ -178,7 +177,7 @@ const KeyValueInputItem = ({
         </div>
       </div>
       <div className="flex items-start pt-[2px]">
-        <OpalButton
+        <Button
           prominence="tertiary"
           size="sm"
           icon={SvgMinusCircle}
@@ -489,10 +488,10 @@ const KeyValueInput = ({
 
       <div>
         <Button
+          prominence="secondary"
           onClick={handleAdd}
-          secondary
           disabled={disabled}
-          leftIcon={SvgPlusCircle}
+          icon={SvgPlusCircle}
           aria-label={`Add ${keyTitle} and ${valueTitle} pair`}
           type="button"
         >
diff --git a/web/src/refresh-components/inputs/InputTypeIn.tsx b/web/src/refresh-components/inputs/InputTypeIn.tsx
index b72ba4ec80e..0b51cbeb90d 100644
--- a/web/src/refresh-components/inputs/InputTypeIn.tsx
+++ b/web/src/refresh-components/inputs/InputTypeIn.tsx
@@ -3,6 +3,7 @@
 import * as React from "react";
 import { cn, noProp } from "@/lib/utils";
 import IconButton from "@/refresh-components/buttons/IconButton";
+import { Button } from "@opal/components";
 import {
   innerClasses,
   textClasses,
@@ -52,7 +53,7 @@ import { SvgSearch, SvgX } from "@opal/icons";
  *   value={password}
  *   onChange={(e) => setPassword(e.target.value)}
  *   type={showPassword ? "text" : "password"}
- *   rightSection={<IconButton icon={SvgEye} onClick={togglePassword} />}
+ *   rightSection={<Button icon={SvgEye} onClick={togglePassword}/>}
  * />
  *
  * // Without clear button
@@ -165,6 +166,7 @@ const InputTypeIn = React.forwardRef<HTMLInputElement, InputTypeInProps>(
         />
 
         {showClearButton && !disabled && !isReadOnly && (
+          // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
           <IconButton
             icon={SvgX}
             disabled={disabled}
diff --git a/web/src/refresh-components/inputs/ListFieldInput.tsx b/web/src/refresh-components/inputs/ListFieldInput.tsx
index 071ed5e3d41..e56bcb4970a 100644
--- a/web/src/refresh-components/inputs/ListFieldInput.tsx
+++ b/web/src/refresh-components/inputs/ListFieldInput.tsx
@@ -59,6 +59,7 @@ export function ListFieldInput({
       <div className="mt-3">
         <div className="flex flex-wrap gap-1.5">
           {values.map((value, index) => (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <Button
               key={index}
               internal
diff --git a/web/src/refresh-components/messages/Message.tsx b/web/src/refresh-components/messages/Message.tsx
index 56ffe2e3b9c..5de07fd95fb 100644
--- a/web/src/refresh-components/messages/Message.tsx
+++ b/web/src/refresh-components/messages/Message.tsx
@@ -337,6 +337,7 @@ function MessageInner(
       {/* Actions */}
       {actions && (
         <div className="flex items-center justify-end shrink-0 self-center pr-2">
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <Button
             secondary
             onClick={onAction}
@@ -351,6 +352,7 @@ function MessageInner(
       {close && (
         <div className="flex items-center justify-center shrink-0">
           <div className={cn("flex items-start", closeButtonSize)}>
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <IconButton
               internal
               icon={SvgX}
diff --git a/web/src/refresh-components/modals/MemoriesModal.tsx b/web/src/refresh-components/modals/MemoriesModal.tsx
index d47dd68f686..26bf1f418bc 100644
--- a/web/src/refresh-components/modals/MemoriesModal.tsx
+++ b/web/src/refresh-components/modals/MemoriesModal.tsx
@@ -5,9 +5,8 @@ import Modal from "@/refresh-components/Modal";
 import { Section } from "@/layouts/general-layouts";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
-import IconButton from "@/refresh-components/buttons/IconButton";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import CharacterCount from "@/refresh-components/CharacterCount";
 import Separator from "@/refresh-components/Separator";
 import TextSeparator from "@/refresh-components/TextSeparator";
@@ -102,10 +101,10 @@ function MemoryItem({
             resizable={false}
             className={cn(!isFocused && "bg-transparent")}
           />
-          <IconButton
+          <Button
+            prominence="tertiary"
             icon={SvgMinusCircle}
             onClick={() => void onRemove(originalIndex)}
-            tertiary
             disabled={!memory.content.trim() && memory.isNew}
             aria-label="Remove Line"
             tooltip="Remove Line"
@@ -242,8 +241,8 @@ export default function MemoriesModal({
               className="w-full !bg-transparent !border-transparent [&:is(:hover,:active,:focus,:focus-within)]:!bg-background-neutral-00 [&:is(:hover)]:!border-border-01 [&:is(:focus,:focus-within)]:!shadow-none"
             />
             <Button
+              prominence="tertiary"
               onClick={onAddLine}
-              tertiary
               rightIcon={SvgPlusCircle}
               disabled={!canAddMemory}
               title={
diff --git a/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx b/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
index 8b585a7782e..3943cd553a6 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
@@ -130,6 +130,7 @@ export default function ActionLineItem({
               )}
 
               {!isSearchToolWithNoConnectors && !isUnavailable && (
+                // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
                 <IconButton
                   icon={SvgSlash}
                   onClick={noProp(onToggle)}
diff --git a/web/src/refresh-components/popovers/FilePickerPopover.tsx b/web/src/refresh-components/popovers/FilePickerPopover.tsx
index 7b9997c91f4..de2353afeaf 100644
--- a/web/src/refresh-components/popovers/FilePickerPopover.tsx
+++ b/web/src/refresh-components/popovers/FilePickerPopover.tsx
@@ -73,6 +73,7 @@ function FileLineItem({
       }
       rightChildren={
         <div className="h-[1rem] flex flex-col justify-center">
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <IconButton
             icon={SvgExternalLink}
             onClick={noProp(() => onFileClick(projectFile))}
diff --git a/web/src/refresh-pages/AgentEditorPage.tsx b/web/src/refresh-pages/AgentEditorPage.tsx
index fb1d3539287..8b6784ee77a 100644
--- a/web/src/refresh-pages/AgentEditorPage.tsx
+++ b/web/src/refresh-pages/AgentEditorPage.tsx
@@ -5,6 +5,7 @@ import { useRouter } from "next/navigation";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import * as GeneralLayouts from "@/layouts/general-layouts";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import { FullPersona } from "@/app/admin/agents/interfaces";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
 import { Formik, Form, FieldArray } from "formik";
@@ -217,6 +218,7 @@ function AgentIconEditor({ existingAgent }: AgentIconEditorProps) {
               iconName={values.icon_name ?? undefined}
               name={values.name}
             />
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               className="absolute bottom-0 left-1/2 -translate-x-1/2 h-[1.75rem] mb-2 invisible group-hover/InputAvatar:visible"
               secondary
@@ -349,13 +351,13 @@ function MCPServerCard({
             onChange={(e) => setQuery(e.target.value)}
           />
           {enabledTools.length > 0 && (
-            <Button
-              internal
+            <OpalButton
+              prominence="internal"
               rightIcon={isFolded ? SvgExpand : SvgFold}
               onClick={() => setIsFolded((prev) => !prev)}
             >
               {isFolded ? "Expand" : "Fold"}
-            </Button>
+            </OpalButton>
           )}
         </GeneralLayouts.Section>
       </ActionsLayouts.Header>
@@ -1164,9 +1166,12 @@ export default function AgentEditorPage({
                       icon={SvgTrash}
                       title="Delete Agent"
                       submit={
-                        <Button danger onClick={handleDeleteAgent}>
+                        <OpalButton
+                          variant="danger"
+                          onClick={handleDeleteAgent}
+                        >
                           Delete Agent
-                        </Button>
+                        </OpalButton>
                       }
                       onClose={() => deleteAgentModal.toggle(false)}
                     >
@@ -1188,14 +1193,14 @@ export default function AgentEditorPage({
                       title={existingAgent ? "Edit Agent" : "Create Agent"}
                       rightChildren={
                         <div className="flex gap-2">
-                          <Button
+                          <OpalButton
+                            prominence="secondary"
                             type="button"
-                            secondary
                             onClick={() => router.back()}
                           >
                             Cancel
-                          </Button>
-                          <Button
+                          </OpalButton>
+                          <OpalButton
                             type="submit"
                             disabled={
                               isSubmitting ||
@@ -1205,7 +1210,7 @@ export default function AgentEditorPage({
                             }
                           >
                             {existingAgent ? "Save" : "Create"}
-                          </Button>
+                          </OpalButton>
                         </div>
                       }
                       backButton
@@ -1458,13 +1463,13 @@ export default function AgentEditorPage({
                                 description="with other users, groups, or everyone in your organization."
                                 center
                               >
-                                <Button
-                                  secondary
-                                  leftIcon={isShared ? SvgUsers : SvgLock}
+                                <OpalButton
+                                  prominence="secondary"
+                                  icon={isShared ? SvgUsers : SvgLock}
                                   onClick={() => shareAgentModal.toggle(true)}
                                 >
                                   Share
-                                </Button>
+                                </OpalButton>
                               </InputLayouts.Horizontal>
                               {canUpdateFeaturedStatus && (
                                 <>
@@ -1553,13 +1558,13 @@ export default function AgentEditorPage({
                               description="Anyone using this agent will no longer be able to access it."
                               center
                             >
-                              <Button
-                                secondary
-                                danger
+                              <OpalButton
+                                variant="danger"
+                                prominence="secondary"
                                 onClick={() => deleteAgentModal.toggle(true)}
                               >
                                 Delete Agent
-                              </Button>
+                              </OpalButton>
                             </InputLayouts.Horizontal>
                           </Card>
                         </>
diff --git a/web/src/refresh-pages/SettingsPage.tsx b/web/src/refresh-pages/SettingsPage.tsx
index d0351faddbd..0abefd0c975 100644
--- a/web/src/refresh-pages/SettingsPage.tsx
+++ b/web/src/refresh-pages/SettingsPage.tsx
@@ -21,7 +21,6 @@ import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
-import Button from "@/refresh-components/buttons/Button";
 import Switch from "@/refresh-components/inputs/Switch";
 import { useUser } from "@/providers/UserProvider";
 import { useTheme } from "next-themes";
@@ -36,7 +35,7 @@ import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import useFilter from "@/hooks/useFilter";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import useFederatedOAuthStatus from "@/hooks/useFederatedOAuthStatus";
 import useCCPairs from "@/hooks/useCCPairs";
 import { ValidSources } from "@/lib/types";
@@ -238,7 +237,7 @@ function GeneralSettings() {
           onClose={() => setShowDeleteConfirmation(false)}
           submit={
             <Button
-              danger
+              variant="danger"
               onClick={() => {
                 void handleDeleteAllChats();
               }}
@@ -444,10 +443,10 @@ function GeneralSettings() {
               center
             >
               <Button
-                danger
-                secondary
+                variant="danger"
+                prominence="secondary"
                 onClick={() => setShowDeleteConfirmation(true)}
-                leftIcon={SvgTrash}
+                icon={SvgTrash}
                 transient={showDeleteConfirmation}
               >
                 Delete All Chats
@@ -698,7 +697,7 @@ function PromptShortcuts() {
                   }
                 />
                 <Section>
-                  <OpalButton
+                  <Button
                     icon={SvgMinusCircle}
                     onClick={() => void handleRemoveShortcut(index)}
                     prominence="tertiary"
@@ -1123,7 +1122,10 @@ function AccountsAccessSettings() {
           title="Revoke Access Token"
           onClose={() => setTokenToDelete(null)}
           submit={
-            <Button danger onClick={() => deletePAT(tokenToDelete.id)}>
+            <Button
+              variant="danger"
+              onClick={() => deletePAT(tokenToDelete.id)}
+            >
               Revoke
             </Button>
           }
@@ -1265,8 +1267,8 @@ function AccountsAccessSettings() {
                 center
               >
                 <Button
-                  secondary
-                  leftIcon={SvgLock}
+                  prominence="secondary"
+                  icon={SvgLock}
                   onClick={() => setShowPasswordModal(true)}
                   transient={showPasswordModal}
                 >
@@ -1355,7 +1357,7 @@ function AccountsAccessSettings() {
                               description={pat.token_display}
                               middleText={middleText}
                               rightChildren={
-                                <OpalButton
+                                <Button
                                   icon={SvgTrash}
                                   onClick={() => setTokenToDelete(pat)}
                                   prominence="tertiary"
@@ -1377,7 +1379,7 @@ function AccountsAccessSettings() {
                   <Text text03 secondaryBody>
                     Access tokens require an active paid subscription.
                   </Text>
-                  <Button secondary href="/admin/billing">
+                  <Button prominence="secondary" href="/admin/billing">
                     Upgrade Plan
                   </Button>
                 </Section>
@@ -1456,7 +1458,7 @@ function FederatedConnectorCard({
           onClose={() => setShowDisconnectConfirmation(false)}
           submit={
             <Button
-              danger
+              variant="danger"
               onClick={() => void handleDisconnect()}
               disabled={isDisconnecting}
             >
@@ -1490,7 +1492,7 @@ function FederatedConnectorCard({
           paddingVariant="sm"
           rightChildren={
             connector.has_oauth_token ? (
-              <OpalButton
+              <Button
                 icon={SvgUnplug}
                 prominence="tertiary"
                 size="sm"
@@ -1499,9 +1501,9 @@ function FederatedConnectorCard({
               />
             ) : connector.authorize_url ? (
               <Button
+                prominence="internal"
                 href={connector.authorize_url}
                 target="_blank"
-                internal
                 rightIcon={SvgArrowExchange}
               >
                 Connect
diff --git a/web/src/sections/AppHealthBanner.tsx b/web/src/sections/AppHealthBanner.tsx
index d5527af1cdd..ae81abf27ef 100644
--- a/web/src/sections/AppHealthBanner.tsx
+++ b/web/src/sections/AppHealthBanner.tsx
@@ -7,7 +7,7 @@ import { useCallback, useEffect, useState, useRef } from "react";
 import { getSecondsUntilExpiration } from "@/lib/time";
 import { refreshToken } from "@/lib/user";
 import { NEXT_PUBLIC_CUSTOM_REFRESH_URL } from "@/lib/constants";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { logout } from "@/lib/user";
 import { usePathname, useRouter } from "next/navigation";
 import { SvgAlertTriangle, SvgLogOut } from "@opal/icons";
diff --git a/web/src/sections/actions/ActionCardHeader.tsx b/web/src/sections/actions/ActionCardHeader.tsx
index be01ded8f05..c8e78289682 100644
--- a/web/src/sections/actions/ActionCardHeader.tsx
+++ b/web/src/sections/actions/ActionCardHeader.tsx
@@ -116,6 +116,7 @@ function ActionCardHeader({
             </Text>
           )}
           {showRenameIcon && (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <IconButton
               icon={SvgEdit}
               tooltip="Rename"
diff --git a/web/src/sections/actions/Actionbar.tsx b/web/src/sections/actions/Actionbar.tsx
index 503ea235dee..f74aa5820ef 100644
--- a/web/src/sections/actions/Actionbar.tsx
+++ b/web/src/sections/actions/Actionbar.tsx
@@ -2,7 +2,7 @@
 
 import React from "react";
 import { cn } from "@/lib/utils";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import Text from "@/refresh-components/texts/Text";
 import { SvgPlusCircle } from "@opal/icons";
@@ -57,7 +57,7 @@ const Actionbar: React.FC<ActionbarProps> = ({
       )}
 
       <div className="flex gap-2 items-center justify-end">
-        <Button main primary leftIcon={SvgPlusCircle} onClick={onAddAction}>
+        <Button icon={SvgPlusCircle} onClick={onAddAction}>
           {buttonText}
         </Button>
       </div>
diff --git a/web/src/sections/actions/Actions.tsx b/web/src/sections/actions/Actions.tsx
index 3404d48fbbc..bca3da21433 100644
--- a/web/src/sections/actions/Actions.tsx
+++ b/web/src/sections/actions/Actions.tsx
@@ -1,8 +1,7 @@
 "use client";
 import { ActionStatus } from "@/lib/tools/interfaces";
 import React from "react";
-import { Button as OpalButton } from "@opal/components";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   SvgArrowExchange,
   SvgChevronDown,
@@ -62,7 +61,7 @@ const Actions = React.memo(
                     : "opacity-0 translate-x-2 pointer-events-none"
                 )}
               >
-                <OpalButton
+                <Button
                   icon={SvgUnplug}
                   tooltip="Disconnect Server"
                   prominence="tertiary"
@@ -72,7 +71,7 @@ const Actions = React.memo(
               </div>
             )}
             {onManage && (
-              <OpalButton
+              <Button
                 icon={SvgSettings}
                 tooltip="Manage Server"
                 prominence="tertiary"
@@ -83,7 +82,7 @@ const Actions = React.memo(
           </div>
           {showViewToolsButton && (
             <Button
-              tertiary
+              prominence="tertiary"
               onClick={onToggleTools}
               rightIcon={SvgChevronDown}
               aria-label={`View tools for ${serverName}`}
@@ -103,7 +102,7 @@ const Actions = React.memo(
         <div className="flex flex-col gap-1 items-end shrink-0">
           {onAuthenticate && (
             <Button
-              tertiary
+              prominence="tertiary"
               onClick={onAuthenticate}
               rightIcon={SvgArrowExchange}
               aria-label={`Authenticate and connect to ${serverName}`}
@@ -120,7 +119,7 @@ const Actions = React.memo(
             )}
           >
             {onDelete && (
-              <OpalButton
+              <Button
                 icon={SvgTrash}
                 tooltip="Delete Server"
                 prominence="tertiary"
@@ -129,7 +128,7 @@ const Actions = React.memo(
               />
             )}
             {onManage && (
-              <OpalButton
+              <Button
                 icon={SvgSettings}
                 tooltip="Manage Server"
                 prominence="tertiary"
@@ -148,7 +147,7 @@ const Actions = React.memo(
         <div className="flex gap-1 items-end">
           {onReconnect && (
             <Button
-              secondary
+              prominence="secondary"
               onClick={onReconnect}
               rightIcon={SvgPlug}
               aria-label={`Reconnect to ${serverName}`}
@@ -157,7 +156,7 @@ const Actions = React.memo(
             </Button>
           )}
           {onManage && (
-            <OpalButton
+            <Button
               icon={SvgSettings}
               tooltip="Manage Server"
               prominence="tertiary"
@@ -168,7 +167,7 @@ const Actions = React.memo(
         </div>
         {showViewToolsButton && (
           <Button
-            tertiary
+            prominence="tertiary"
             onClick={onToggleTools}
             rightIcon={SvgChevronDown}
             aria-label={`View tools for ${serverName}`}
diff --git a/web/src/sections/actions/MCPActionCard.tsx b/web/src/sections/actions/MCPActionCard.tsx
index 5943204da00..5a6e6bf7b8a 100644
--- a/web/src/sections/actions/MCPActionCard.tsx
+++ b/web/src/sections/actions/MCPActionCard.tsx
@@ -22,8 +22,8 @@ import useServerTools from "@/hooks/useServerTools";
 import { KeyedMutator } from "swr";
 import type { IconProps } from "@opal/types";
 import { SvgRefreshCw, SvgServer, SvgTrash } from "@opal/icons";
-import IconButton from "@/refresh-components/buttons/IconButton";
-import Button from "@/refresh-components/buttons/Button";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { timeAgo } from "@/lib/time";
 import { cn } from "@/lib/utils";
@@ -247,13 +247,12 @@ export default function MCPActionCard({
 
     return (
       <div className="flex items-center gap-2">
-        <IconButton
-          icon={SvgRefreshCw}
-          internal
+        <Button
+          icon={isToolsRefreshing ? SimpleLoader : SvgRefreshCw}
+          prominence="internal"
           onClick={handleRefreshTools}
           tooltip="Refresh tools"
           aria-label="Refresh tools"
-          className={cn(isToolsRefreshing && "animate-spin")}
         />
         {lastRefreshedText && (
           <Text as="p" text03 mainUiBody className="whitespace-nowrap">
@@ -333,7 +332,7 @@ export default function MCPActionCard({
           onClose={() => deleteModal.toggle(false)}
           submit={
             <Button
-              danger
+              variant="danger"
               onClick={async () => {
                 if (!onDelete) return;
                 try {
diff --git a/web/src/sections/actions/OpenApiActionCard.tsx b/web/src/sections/actions/OpenApiActionCard.tsx
index 63048339bc9..dc476b0cba2 100644
--- a/web/src/sections/actions/OpenApiActionCard.tsx
+++ b/web/src/sections/actions/OpenApiActionCard.tsx
@@ -12,7 +12,7 @@ import { extractMethodSpecsFromDefinition } from "@/lib/tools/openApiService";
 import { updateToolStatus } from "@/lib/tools/mcpService";
 import { SvgServer, SvgTrash } from "@opal/icons";
 import Modal from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 
@@ -199,7 +199,7 @@ export default function OpenApiActionCard({
           onClose={() => deleteModal.toggle(false)}
           submit={
             <Button
-              danger
+              variant="danger"
               onClick={async () => {
                 await onDelete(tool);
                 deleteModal.toggle(false);
diff --git a/web/src/sections/actions/ToolsList.tsx b/web/src/sections/actions/ToolsList.tsx
index 88be6112ea9..74f7a3ddf18 100644
--- a/web/src/sections/actions/ToolsList.tsx
+++ b/web/src/sections/actions/ToolsList.tsx
@@ -3,12 +3,11 @@
 import React from "react";
 import { cn } from "@/lib/utils";
 import Text from "@/refresh-components/texts/Text";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import FadingEdgeContainer from "@/refresh-components/FadingEdgeContainer";
 import ToolItemSkeleton from "@/sections/actions/skeleton/ToolItemSkeleton";
 import EnabledCount from "@/refresh-components/EnabledCount";
 import { SvgEye, SvgXCircle } from "@opal/icons";
-import Button from "@/refresh-components/buttons/Button";
 
 export interface ToolsListProps {
   // Loading state
@@ -96,7 +95,7 @@ const ToolsList: React.FC<ToolsListProps> = ({
                 />
               )}
               {onToggleShowOnlyEnabled && enabledCount > 0 && (
-                <OpalButton
+                <Button
                   icon={SvgEye}
                   prominence="tertiary"
                   size="sm"
@@ -113,7 +112,7 @@ const ToolsList: React.FC<ToolsListProps> = ({
                 />
               )}
               {onUpdateToolsStatus && enabledCount > 0 && (
-                <OpalButton
+                <Button
                   icon={SvgXCircle}
                   prominence="tertiary"
                   size="sm"
@@ -123,7 +122,10 @@ const ToolsList: React.FC<ToolsListProps> = ({
                 />
               )}
               {onUpdateToolsStatus && enabledCount === 0 && (
-                <Button tertiary onClick={() => onUpdateToolsStatus(true)}>
+                <Button
+                  prominence="tertiary"
+                  onClick={() => onUpdateToolsStatus(true)}
+                >
                   Enable all
                 </Button>
               )}
diff --git a/web/src/sections/actions/ToolsSection.tsx b/web/src/sections/actions/ToolsSection.tsx
index 75a32eb2bad..18ca64cfefb 100644
--- a/web/src/sections/actions/ToolsSection.tsx
+++ b/web/src/sections/actions/ToolsSection.tsx
@@ -2,7 +2,7 @@
 
 import React from "react";
 import { cn } from "@/lib/utils";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { SvgFold } from "@opal/icons";
 interface ToolsSectionProps {
@@ -42,7 +42,7 @@ const ToolsSection: React.FC<ToolsSectionProps> = ({
         <div className="flex gap-1 items-center p-1">
           {/* Fold Button */}
           {onFold && (
-            <Button tertiary onClick={onFold} rightIcon={SvgFold}>
+            <Button prominence="tertiary" onClick={onFold} rightIcon={SvgFold}>
               Fold
             </Button>
           )}
diff --git a/web/src/sections/actions/modals/AddMCPServerModal.tsx b/web/src/sections/actions/modals/AddMCPServerModal.tsx
index 9a39306ca57..f9722cfd9fa 100644
--- a/web/src/sections/actions/modals/AddMCPServerModal.tsx
+++ b/web/src/sections/actions/modals/AddMCPServerModal.tsx
@@ -7,7 +7,6 @@ import Modal from "@/refresh-components/Modal";
 import * as InputLayouts from "@/layouts/input-layouts";
 import InputTypeInField from "@/refresh-components/form/InputTypeInField";
 import InputTextAreaField from "@/refresh-components/form/InputTextAreaField";
-import Button from "@/refresh-components/buttons/Button";
 import { createMCPServer, updateMCPServer } from "@/lib/tools/mcpService";
 import {
   MCPServerCreateRequest,
@@ -16,7 +15,7 @@ import {
 } from "@/lib/tools/interfaces";
 import { useModal } from "@/refresh-components/contexts/ModalContext";
 import Separator from "@/refresh-components/Separator";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import { toast } from "@/hooks/useToast";
 import { ModalCreationInterface } from "@/refresh-components/contexts/ModalContext";
 import { SvgCheckCircle, SvgServer, SvgUnplug } from "@opal/icons";
@@ -214,7 +213,7 @@ export default function AddMCPServerModal({
                         alignItems="center"
                         width="fit"
                       >
-                        <OpalButton
+                        <Button
                           icon={SvgUnplug}
                           prominence="tertiary"
                           type="button"
@@ -222,7 +221,7 @@ export default function AddMCPServerModal({
                           onClick={handleDisconnectClick}
                         />
                         <Button
-                          secondary
+                          prominence="secondary"
                           type="button"
                           onClick={() => {
                             // Close this modal and open the auth modal for this server
@@ -239,7 +238,7 @@ export default function AddMCPServerModal({
 
               <Modal.Footer>
                 <Button
-                  secondary
+                  prominence="secondary"
                   type="button"
                   onClick={() => handleModalClose(false)}
                   disabled={isSubmitting}
@@ -247,7 +246,6 @@ export default function AddMCPServerModal({
                   Cancel
                 </Button>
                 <Button
-                  primary
                   type="submit"
                   disabled={isSubmitting || !isValid || !dirty}
                 >
diff --git a/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx b/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
index c808bf6720e..5d6e320df99 100644
--- a/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
+++ b/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
@@ -2,7 +2,6 @@
 
 import Link from "next/link";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
 import Text from "@/refresh-components/texts/Text";
 import * as InputLayouts from "@/layouts/input-layouts";
 import InputTextAreaField from "@/refresh-components/form/InputTextAreaField";
@@ -10,7 +9,7 @@ import SimpleTooltip from "@/refresh-components/SimpleTooltip";
 import Separator from "@/refresh-components/Separator";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import { MethodSpec, ToolSnapshot } from "@/lib/tools/interfaces";
 import {
   validateToolDefinition,
@@ -270,7 +269,7 @@ function FormContent({
                   getCopyText={() => values.definition}
                   tooltip="Copy definition"
                 />
-                <OpalButton
+                <Button
                   prominence="tertiary"
                   size="sm"
                   icon={SvgBracketCurly}
@@ -363,7 +362,7 @@ function FormContent({
               alignItems="center"
               width="fit"
             >
-              <OpalButton
+              <Button
                 icon={SvgUnplug}
                 prominence="tertiary"
                 type="button"
@@ -376,7 +375,7 @@ function FormContent({
                 }}
               />
               <Button
-                secondary
+                prominence="secondary"
                 type="button"
                 onClick={handleEditAuthenticationClick}
                 disabled={!onEditAuthentication}
@@ -390,15 +389,14 @@ function FormContent({
 
       <Modal.Footer>
         <Button
-          main
-          secondary
+          prominence="secondary"
           type="button"
           onClick={handleClose}
           disabled={isSubmitting}
         >
           Cancel
         </Button>
-        <Button main primary type="submit" disabled={isSubmitting || !dirty}>
+        <Button type="submit" disabled={isSubmitting || !dirty}>
           {primaryButtonLabel}
         </Button>
       </Modal.Footer>
diff --git a/web/src/sections/actions/modals/DisconnectEntityModal.tsx b/web/src/sections/actions/modals/DisconnectEntityModal.tsx
index 92e360bd8e6..fb22defde38 100644
--- a/web/src/sections/actions/modals/DisconnectEntityModal.tsx
+++ b/web/src/sections/actions/modals/DisconnectEntityModal.tsx
@@ -2,7 +2,7 @@
 
 import { useRef } from "react";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 import { SvgUnplug } from "@opal/icons";
@@ -66,13 +66,17 @@ export default function DisconnectEntityModal({
         </Modal.Body>
 
         <Modal.Footer>
-          <Button main secondary onClick={onClose} disabled={isDisconnecting}>
+          <Button
+            prominence="secondary"
+            onClick={onClose}
+            disabled={isDisconnecting}
+          >
             Cancel
           </Button>
           {onConfirmDisconnectAndDelete && (
             <Button
-              danger
-              secondary
+              variant="danger"
+              prominence="secondary"
               onClick={onConfirmDisconnectAndDelete}
               disabled={isDisconnecting}
             >
@@ -80,8 +84,7 @@ export default function DisconnectEntityModal({
             </Button>
           )}
           <Button
-            danger
-            primary
+            variant="danger"
             onClick={onConfirmDisconnect}
             disabled={isDisconnecting}
             ref={disconnectButtonRef}
diff --git a/web/src/sections/actions/modals/MCPAuthenticationModal.tsx b/web/src/sections/actions/modals/MCPAuthenticationModal.tsx
index 96b68315514..f778b320834 100644
--- a/web/src/sections/actions/modals/MCPAuthenticationModal.tsx
+++ b/web/src/sections/actions/modals/MCPAuthenticationModal.tsx
@@ -8,7 +8,7 @@ import { FormField } from "@/refresh-components/form/FormField";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import Text from "@/refresh-components/texts/Text";
 import { Formik, Form } from "formik";
@@ -633,16 +633,13 @@ export default function MCPAuthenticationModal({
 
                 <Modal.Footer>
                   <Button
-                    main
-                    tertiary
+                    prominence="tertiary"
                     type="button"
                     onClick={() => toggle(false)}
                   >
                     Cancel
                   </Button>
                   <Button
-                    main
-                    primary
                     type="submit"
                     disabled={!isValid || isSubmitting}
                     data-testid="mcp-auth-connect-button"
diff --git a/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx b/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx
index 50a1b624dd5..d14a3ebe1b4 100644
--- a/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx
+++ b/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx
@@ -4,7 +4,7 @@ import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { Formik, Form, FormikHelpers } from "formik";
 import * as Yup from "yup";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
@@ -663,12 +663,14 @@ export default function OpenAPIAuthenticationModal({
               </Modal.Body>
 
               <Modal.Footer>
-                <Button main tertiary type="button" onClick={handleSkip}>
+                <Button
+                  prominence="tertiary"
+                  type="button"
+                  onClick={handleSkip}
+                >
                   Cancel
                 </Button>
                 <Button
-                  main
-                  primary
                   type="submit"
                   disabled={
                     !isValid || isSubmitting || shouldDisableForm || !dirty
diff --git a/web/src/sections/cards/AgentCard.tsx b/web/src/sections/cards/AgentCard.tsx
index 78a56c6c24b..502f7470345 100644
--- a/web/src/sections/cards/AgentCard.tsx
+++ b/web/src/sections/cards/AgentCard.tsx
@@ -3,7 +3,7 @@
 import { useMemo, useCallback } from "react";
 import { MinimalPersonaSnapshot } from "@/app/admin/agents/interfaces";
 import AgentAvatar from "@/refresh-components/avatars/AgentAvatar";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { useAppRouter } from "@/hooks/appNavigation";
 import IconButton from "@/refresh-components/buttons/IconButton";
 import { usePinnedAgents, useAgent } from "@/hooks/useAgents";
@@ -146,6 +146,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
               rightChildren={
                 <>
                   {isOwnedByUser && isPaidEnterpriseFeaturesEnabled && (
+                    // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
                     <IconButton
                       icon={SvgBarChart}
                       tertiary
@@ -157,6 +158,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
                     />
                   )}
                   {isOwnedByUser && (
+                    // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
                     <IconButton
                       icon={SvgEdit}
                       tertiary
@@ -168,6 +170,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
                     />
                   )}
                   {isOwnedByUser && (
+                    // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
                     <IconButton
                       icon={SvgShare}
                       tertiary
@@ -176,6 +179,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
                       className="hidden group-hover/AgentCard:flex"
                     />
                   )}
+                  {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                   <IconButton
                     icon={pinned ? SvgPinned : SvgPin}
                     tertiary
@@ -219,7 +223,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
             {/* Right side - Start Chat button */}
             <div className="p-0.5">
               <Button
-                tertiary
+                prominence="tertiary"
                 rightIcon={SvgBubbleText}
                 onClick={noProp(handleStartChat)}
               >
diff --git a/web/src/sections/knowledge/AgentKnowledgePane.tsx b/web/src/sections/knowledge/AgentKnowledgePane.tsx
index d00b0f4459b..900c73b90a1 100644
--- a/web/src/sections/knowledge/AgentKnowledgePane.tsx
+++ b/web/src/sections/knowledge/AgentKnowledgePane.tsx
@@ -13,8 +13,7 @@ import { Content } from "@opal/layouts";
 import * as TableLayouts from "@/layouts/table-layouts";
 import * as InputLayouts from "@/layouts/input-layouts";
 import { Card } from "@/refresh-components/cards";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import LineItem from "@/refresh-components/buttons/LineItem";
 import Separator from "@/refresh-components/Separator";
@@ -489,8 +488,8 @@ function RecentFilesTableContent({
         ariaLabelPrefix="user-file-row"
         headerActions={
           <Button
-            internal
-            leftIcon={SvgPlusCircle}
+            prominence="internal"
+            icon={SvgPlusCircle}
             onClick={() => fileInputRef.current?.click()}
           >
             Add File
@@ -786,7 +785,7 @@ const KnowledgeMainContent = memo(function KnowledgeMainContent({
         <Text text03 secondaryBody>
           Add documents or connected sources to use for this agent.
         </Text>
-        <OpalButton
+        <Button
           icon={SvgPlusCircle}
           onClick={onAddKnowledge}
           prominence="tertiary"
@@ -816,8 +815,8 @@ const KnowledgeMainContent = memo(function KnowledgeMainContent({
         selected
       </Text>
       <Button
-        internal
-        leftIcon={SvgArrowUpRight}
+        prominence="internal"
+        icon={SvgArrowUpRight}
         onClick={onViewEdit}
         aria-label="knowledge-view-edit"
       >
diff --git a/web/src/sections/knowledge/SourceHierarchyBrowser.tsx b/web/src/sections/knowledge/SourceHierarchyBrowser.tsx
index 0fb7c4ba200..18ba2d66b94 100644
--- a/web/src/sections/knowledge/SourceHierarchyBrowser.tsx
+++ b/web/src/sections/knowledge/SourceHierarchyBrowser.tsx
@@ -9,8 +9,7 @@ import React, {
 } from "react";
 import * as GeneralLayouts from "@/layouts/general-layouts";
 import * as TableLayouts from "@/layouts/table-layouts";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import Truncated from "@/refresh-components/texts/Truncated";
 import Separator from "@/refresh-components/Separator";
@@ -81,7 +80,7 @@ function HierarchyBreadcrumb({
     >
       {/* Root source link */}
       {path.length > 0 ? (
-        <Button tertiary onClick={onNavigateToRoot}>
+        <Button prominence="tertiary" onClick={onNavigateToRoot}>
           {sourceMetadata.displayName}
         </Button>
       ) : (
@@ -112,7 +111,7 @@ function HierarchyBreadcrumb({
               <Text text03>{node.title}</Text>
             ) : (
               <Button
-                tertiary
+                prominence="tertiary"
                 onClick={() => onNavigateToNode(node, actualIndex)}
               >
                 {node.title}
@@ -698,7 +697,11 @@ export default function SourceHierarchyBrowser({
       {viewSelectedOnly ? (
         <>
           <Spacer rem={0.5} />
-          <Button action tertiary onClick={handleToggleViewSelected}>
+          <Button
+            variant="action"
+            prominence="tertiary"
+            onClick={handleToggleViewSelected}
+          >
             Selected items
           </Button>
         </>
@@ -868,7 +871,7 @@ export default function SourceHierarchyBrowser({
                     >
                       <Truncated>{item.data.title}</Truncated>
                       {isFolder && (
-                        <OpalButton
+                        <Button
                           icon={SvgChevronRight}
                           prominence="tertiary"
                           size="sm"
@@ -922,14 +925,14 @@ export default function SourceHierarchyBrowser({
               {currentSourceSelectedCount}{" "}
               {currentSourceSelectedCount === 1 ? "item" : "items"} selected
             </Text>
-            <OpalButton
+            <Button
               icon={SvgEye}
               variant={viewSelectedOnly ? "action" : undefined}
               prominence="tertiary"
               size={viewSelectedOnly ? undefined : "sm"}
               onClick={handleToggleViewSelected}
             />
-            <OpalButton
+            <Button
               icon={SvgXCircle}
               prominence="tertiary"
               size="sm"
diff --git a/web/src/sections/modals/AgentViewerModal.tsx b/web/src/sections/modals/AgentViewerModal.tsx
index adceaef1728..dd73fa8d547 100644
--- a/web/src/sections/modals/AgentViewerModal.tsx
+++ b/web/src/sections/modals/AgentViewerModal.tsx
@@ -29,7 +29,7 @@ import { MCPServer, ToolSnapshot } from "@/lib/tools/interfaces";
 import EmptyMessage from "@/refresh-components/EmptyMessage";
 import { Horizontal } from "@/layouts/input-layouts";
 import Switch from "@/refresh-components/inputs/Switch";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
 import AppInputBar from "@/sections/input/AppInputBar";
 import { useFilters, useLlmManager } from "@/lib/hooks";
@@ -66,7 +66,7 @@ function ViewerMCPServerCard({ server, tools }: ViewerMCPServerCardProps) {
             variant="section"
             rightChildren={
               <Button
-                internal
+                prominence="internal"
                 rightIcon={folded ? SvgExpand : SvgFold}
                 onClick={() => setFolded((prev) => !prev)}
               >
diff --git a/web/src/sections/modals/FeedbackModal.tsx b/web/src/sections/modals/FeedbackModal.tsx
index 08e9988a8ce..ac8e3bcfa9c 100644
--- a/web/src/sections/modals/FeedbackModal.tsx
+++ b/web/src/sections/modals/FeedbackModal.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { FeedbackType } from "@/app/app/interfaces";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import useFeedbackController from "@/hooks/useFeedbackController";
 import { useModal } from "@/refresh-components/contexts/ModalContext";
 import { SvgThumbsDown, SvgThumbsUp } from "@opal/icons";
@@ -90,8 +90,8 @@ export default function FeedbackModal({
 
                 <Modal.Footer>
                   <Button
+                    prominence="secondary"
                     onClick={() => modal.toggle(false)}
-                    secondary
                     type="button"
                   >
                     Cancel
diff --git a/web/src/sections/modals/NewTenantModal.tsx b/web/src/sections/modals/NewTenantModal.tsx
index 355f781fa3f..ac1dbde615b 100644
--- a/web/src/sections/modals/NewTenantModal.tsx
+++ b/web/src/sections/modals/NewTenantModal.tsx
@@ -2,7 +2,7 @@
 
 import { useState } from "react";
 import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { toast } from "@/hooks/useToast";
 import { SvgArrowRight, SvgUsers, SvgX } from "@opal/icons";
 import { logout } from "@/lib/user";
@@ -137,10 +137,10 @@ export default function NewTenantModal({
             cancel={
               isInvite ? (
                 <Button
+                  prominence="secondary"
                   onClick={handleRejectInvite}
-                  secondary
                   disabled={isLoading}
-                  leftIcon={SvgX}
+                  icon={SvgX}
                 >
                   Decline
                 </Button>
diff --git a/web/src/sections/modals/ShareAgentModal.tsx b/web/src/sections/modals/ShareAgentModal.tsx
index 761376e0cd4..b75e4e95a04 100644
--- a/web/src/sections/modals/ShareAgentModal.tsx
+++ b/web/src/sections/modals/ShareAgentModal.tsx
@@ -2,7 +2,6 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
 import {
   SvgLink,
   SvgOrganization,
@@ -28,7 +27,7 @@ import { useModal } from "@/refresh-components/contexts/ModalContext";
 import { useUser } from "@/providers/UserProvider";
 import { Formik, useFormikContext } from "formik";
 import { useAgent } from "@/hooks/useAgents";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import { useLabels } from "@/lib/hooks";
 import { PersonaLabel } from "@/app/admin/agents/interfaces";
 
@@ -250,7 +249,7 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
                             ) : (
                               // For all other cases (including for "self-unsharing"),
                               // we render an `IconButton SvgX` to remove a person from the list.
-                              <OpalButton
+                              <Button
                                 prominence="tertiary"
                                 size="sm"
                                 icon={SvgX}
@@ -270,7 +269,7 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
                         key={`group-${group.id}`}
                         icon={SvgUsers}
                         rightChildren={
-                          <OpalButton
+                          <Button
                             prominence="tertiary"
                             size="sm"
                             icon={SvgX}
@@ -343,13 +342,21 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
         <BasicModalFooter
           left={
             agentId ? (
-              <Button secondary leftIcon={SvgLink} onClick={handleCopyLink}>
+              <Button
+                prominence="secondary"
+                icon={SvgLink}
+                onClick={handleCopyLink}
+              >
                 Copy Link
               </Button>
             ) : undefined
           }
           cancel={
-            <Button secondary onClick={handleClose} disabled={isSubmitting}>
+            <Button
+              prominence="secondary"
+              onClick={handleClose}
+              disabled={isSubmitting}
+            >
               Cancel
             </Button>
           }
diff --git a/web/src/sections/modals/ShareChatSessionModal.tsx b/web/src/sections/modals/ShareChatSessionModal.tsx
index ebf8b795762..7ae3ac12520 100644
--- a/web/src/sections/modals/ShareChatSessionModal.tsx
+++ b/web/src/sections/modals/ShareChatSessionModal.tsx
@@ -8,7 +8,7 @@ import { useChatSessionStore } from "@/app/app/stores/useChatSessionStore";
 import { copyAll } from "@/app/app/message/copyingUtils";
 import { Section } from "@/layouts/general-layouts";
 import Modal from "@/refresh-components/Modal";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import Text from "@/refresh-components/texts/Text";
@@ -235,15 +235,19 @@ export default function ShareChatSessionModal({
         </Modal.Body>
         <Modal.Footer>
           {!isShared && (
-            <Button secondary onClick={onClose} aria-label="share-modal-cancel">
+            <Button
+              prominence="secondary"
+              onClick={onClose}
+              aria-label="share-modal-cancel"
+            >
               Cancel
             </Button>
           )}
           <Button
             onClick={handleSubmit}
             disabled={isLoading}
-            leftIcon={isShared ? SvgLink : undefined}
-            className={isShared ? "w-full" : undefined}
+            icon={isShared ? SvgLink : undefined}
+            width={isShared ? "full" : undefined}
             aria-label="share-modal-submit"
           >
             {submitButtonText}
diff --git a/web/src/sections/modals/TextViewModal.tsx b/web/src/sections/modals/TextViewModal.tsx
index 7985eae4a29..fa39b816d5f 100644
--- a/web/src/sections/modals/TextViewModal.tsx
+++ b/web/src/sections/modals/TextViewModal.tsx
@@ -1,7 +1,6 @@
 "use client";
 
 import { useState, useEffect, useCallback, useMemo } from "react";
-import Button from "@/refresh-components/buttons/Button";
 import {
   Table,
   TableBody,
@@ -12,7 +11,7 @@ import {
 } from "@/components/ui/table";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
 import Text from "@/refresh-components/texts/Text";
 import {
@@ -214,20 +213,20 @@ export default function TextViewModal({
           onClose={onClose}
         >
           <Section flexDirection="row" justifyContent="start" gap={0.25}>
-            <OpalButton
+            <Button
               prominence="tertiary"
               onClick={handleZoomOut}
               icon={SvgZoomOut}
               tooltip="Zoom Out"
             />
             <Text mainUiBody>{zoom}%</Text>
-            <OpalButton
+            <Button
               prominence="tertiary"
               onClick={handleZoomIn}
               icon={SvgZoomIn}
               tooltip="Zoom In"
             />
-            <OpalButton
+            <Button
               prominence="tertiary"
               onClick={handleDownload}
               icon={SvgDownloadCloud}
diff --git a/web/src/sections/modals/llmConfig/CustomModal.tsx b/web/src/sections/modals/llmConfig/CustomModal.tsx
index ff362fc8dd9..0b5438c8ea1 100644
--- a/web/src/sections/modals/llmConfig/CustomModal.tsx
+++ b/web/src/sections/modals/llmConfig/CustomModal.tsx
@@ -281,6 +281,7 @@ export function CustomModal({
                                   </div>
                                 </div>
                                 <div className="my-auto">
+                                  {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                                   <IconButton
                                     icon={SvgX}
                                     className="my-auto"
diff --git a/web/src/sections/modals/llmConfig/components/DisplayModels.tsx b/web/src/sections/modals/llmConfig/components/DisplayModels.tsx
index 89e4393e092..22bde96e388 100644
--- a/web/src/sections/modals/llmConfig/components/DisplayModels.tsx
+++ b/web/src/sections/modals/llmConfig/components/DisplayModels.tsx
@@ -194,6 +194,7 @@ export function DisplayModels<T extends BaseLLMFormValues>({
               }
               aria-label="Select all models"
             />
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <Button
               main
               internal
@@ -217,6 +218,7 @@ export function DisplayModels<T extends BaseLLMFormValues>({
             </Button>
           </Section>
           {areSomeModelsSelected && (
+            // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
             <Button
               main
               internal
@@ -348,6 +350,7 @@ export function DisplayModels<T extends BaseLLMFormValues>({
                         {modelConfiguration.name}
                       </Text>
                     </div>
+                    {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                     <Button
                       main
                       internal
diff --git a/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx b/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx
index 00d8858f9cb..6bc960a1f7d 100644
--- a/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx
+++ b/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx
@@ -1,5 +1,5 @@
 import { useState, useEffect } from "react";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import SimpleTooltip from "@/refresh-components/SimpleTooltip";
 import { ModelConfiguration } from "@/interfaces/llm";
diff --git a/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx b/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
index ae03b666ef2..7c36f12ae92 100644
--- a/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
+++ b/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
@@ -1,6 +1,7 @@
 import { LoadingAnimation } from "@/components/Loading";
 import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
+import { Button as OpalButton } from "@opal/components";
 import { SvgTrash } from "@opal/icons";
 import { LLMProviderView } from "@/interfaces/llm";
 import { LLM_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
@@ -57,9 +58,9 @@ export function FormActionButtons({
           )}
         </Button>
         {existingLlmProvider && (
-          <Button danger leftIcon={SvgTrash} onClick={handleDelete}>
+          <OpalButton variant="danger" icon={SvgTrash} onClick={handleDelete}>
             Delete
-          </Button>
+          </OpalButton>
         )}
       </div>
     </>
diff --git a/web/src/sections/modals/llmConfig/components/FormWrapper.tsx b/web/src/sections/modals/llmConfig/components/FormWrapper.tsx
index 9f969577595..f7e6deb2122 100644
--- a/web/src/sections/modals/llmConfig/components/FormWrapper.tsx
+++ b/web/src/sections/modals/llmConfig/components/FormWrapper.tsx
@@ -10,7 +10,7 @@ import {
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import Modal from "@/refresh-components/Modal";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { SvgSettings } from "@opal/icons";
 import { Badge } from "@/components/ui/badge";
 import { cn } from "@/lib/utils";
@@ -142,7 +142,7 @@ export function ProviderFormEntrypointWrapper({
   if (buttonMode && !existingLlmProvider) {
     return (
       <>
-        <Button action onClick={() => setFormIsVisible(true)}>
+        <Button variant="action" onClick={() => setFormIsVisible(true)}>
           {buttonText ?? `Add ${providerName}`}
         </Button>
         {renderModal(formIsVisible, `Setup ${providerName}`)}
@@ -185,8 +185,8 @@ export function ProviderFormEntrypointWrapper({
 
             <div className="ml-auto my-auto">
               <Button
-                action={!existingLlmProvider}
-                secondary={!!existingLlmProvider}
+                variant={!existingLlmProvider ? "action" : "default"}
+                prominence={!!existingLlmProvider ? "secondary" : "primary"}
                 onClick={() => setFormIsVisible(true)}
               >
                 Edit
@@ -201,7 +201,7 @@ export function ProviderFormEntrypointWrapper({
               </Text>
             </div>
             <div className="ml-auto my-auto">
-              <Button action onClick={() => setFormIsVisible(true)}>
+              <Button variant="action" onClick={() => setFormIsVisible(true)}>
                 Set up
               </Button>
             </div>
diff --git a/web/src/sections/onboarding/components/LLMProviderCard.tsx b/web/src/sections/onboarding/components/LLMProviderCard.tsx
index 75abc35fd9e..9d798013018 100644
--- a/web/src/sections/onboarding/components/LLMProviderCard.tsx
+++ b/web/src/sections/onboarding/components/LLMProviderCard.tsx
@@ -92,6 +92,7 @@ function LLMProviderCardInner({
         {isConnected ? (
           <div className="flex items-start gap-1 p-1">
             {isHovered && (
+              // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
               <IconButton
                 internal
                 icon={SvgSettings}
diff --git a/web/src/sections/onboarding/components/NonAdminStep.tsx b/web/src/sections/onboarding/components/NonAdminStep.tsx
index 5408c23882c..5a8564ec295 100644
--- a/web/src/sections/onboarding/components/NonAdminStep.tsx
+++ b/web/src/sections/onboarding/components/NonAdminStep.tsx
@@ -3,12 +3,11 @@
 import React, { useRef, useState, useEffect } from "react";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
-import Button from "@/refresh-components/buttons/Button";
 import { updateUserPersonalization } from "@/lib/userSettings";
 import { useUser } from "@/providers/UserProvider";
 import { toast } from "@/hooks/useToast";
 import IconButton from "@/refresh-components/buttons/IconButton";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import InputAvatar from "@/refresh-components/inputs/InputAvatar";
 import { cn } from "@/lib/utils";
 import { SvgCheckCircle, SvgEdit, SvgUser, SvgX } from "@opal/icons";
@@ -76,7 +75,7 @@ export default function NonAdminStep() {
             prominence="muted"
             paddingVariant="fit"
             rightChildren={
-              <OpalButton
+              <Button
                 prominence="tertiary"
                 size="sm"
                 icon={SvgX}
@@ -151,6 +150,7 @@ export default function NonAdminStep() {
             </Text>
           </div>
           <div className="p-1 flex items-center gap-1">
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <IconButton
               internal
               icon={SvgEdit}
diff --git a/web/src/sections/onboarding/components/OnboardingHeader.tsx b/web/src/sections/onboarding/components/OnboardingHeader.tsx
index fbc76863b89..9017962bce2 100644
--- a/web/src/sections/onboarding/components/OnboardingHeader.tsx
+++ b/web/src/sections/onboarding/components/OnboardingHeader.tsx
@@ -6,8 +6,7 @@ import {
   OnboardingStep,
 } from "@/interfaces/onboarding";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import { SvgProgressCircle, SvgX } from "@opal/icons";
 import { Card } from "@/refresh-components/cards";
 import { Section } from "@/layouts/general-layouts";
@@ -67,7 +66,7 @@ const OnboardingHeader = React.memo(
                 </Button>
               </Section>
             ) : (
-              <OpalButton
+              <Button
                 prominence="tertiary"
                 size="sm"
                 icon={SvgX}
diff --git a/web/src/sections/onboarding/steps/FinalStep.tsx b/web/src/sections/onboarding/steps/FinalStep.tsx
index e7ced14c4e9..87e9b9cd8bf 100644
--- a/web/src/sections/onboarding/steps/FinalStep.tsx
+++ b/web/src/sections/onboarding/steps/FinalStep.tsx
@@ -1,7 +1,7 @@
 import React from "react";
 import Link from "next/link";
 import type { Route } from "next";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import { FINAL_SETUP_CONFIG } from "@/sections/onboarding/constants";
 import { FinalStepItemProps } from "@/interfaces/onboarding";
 import { SvgExternalLink } from "@opal/icons";
@@ -33,7 +33,7 @@ const FinalStepItem = React.memo(
           paddingVariant="sm"
           rightChildren={
             <Link href={buttonHref as Route} {...linkProps}>
-              <Button tertiary rightIcon={SvgExternalLink}>
+              <Button prominence="tertiary" rightIcon={SvgExternalLink}>
                 {buttonText}
               </Button>
             </Link>
diff --git a/web/src/sections/onboarding/steps/LLMStep.tsx b/web/src/sections/onboarding/steps/LLMStep.tsx
index d3e2a9f484d..3d26757d04f 100644
--- a/web/src/sections/onboarding/steps/LLMStep.tsx
+++ b/web/src/sections/onboarding/steps/LLMStep.tsx
@@ -2,7 +2,7 @@
 
 import { memo, useState, useCallback } from "react";
 import Text from "@/refresh-components/texts/Text";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import Separator from "@/refresh-components/Separator";
 import LLMProviderCard from "../components/LLMProviderCard";
 import {
@@ -138,7 +138,7 @@ const LLMStepInner = ({
             paddingVariant="lg"
             rightChildren={
               <Button
-                tertiary
+                prominence="tertiary"
                 rightIcon={SvgExternalLink}
                 disabled={disabled}
                 href="/admin/configuration/llm"
diff --git a/web/src/sections/onboarding/steps/NameStep.tsx b/web/src/sections/onboarding/steps/NameStep.tsx
index 360e833ea09..417149dda55 100644
--- a/web/src/sections/onboarding/steps/NameStep.tsx
+++ b/web/src/sections/onboarding/steps/NameStep.tsx
@@ -93,6 +93,7 @@ const NameStep = React.memo(
           </Text>
         </div>
         <div className="p-1 flex items-center gap-1">
+          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <IconButton
             internal
             icon={SvgEdit}
diff --git a/web/src/sections/settings/Memories.tsx b/web/src/sections/settings/Memories.tsx
index 9db59ec3905..8a9e53b9ba2 100644
--- a/web/src/sections/settings/Memories.tsx
+++ b/web/src/sections/settings/Memories.tsx
@@ -6,7 +6,7 @@ import ButtonTile from "@/refresh-components/tiles/ButtonTile";
 import { SvgAddLines, SvgFilter, SvgMenu, SvgPlusCircle } from "@opal/icons";
 import MemoriesModal from "@/refresh-components/modals/MemoriesModal";
 import LineItem from "@/refresh-components/buttons/LineItem";
-import IconButton from "@/refresh-components/buttons/IconButton";
+import { Button } from "@opal/components";
 import { useCreateModal } from "@/refresh-components/contexts/ModalContext";
 import { MemoryItem } from "@/lib/types";
 
@@ -30,8 +30,8 @@ export default function Memories({ memories, onSaveMemories }: MemoriesProps) {
             memoriesModal.toggle(true);
           }}
           rightChildren={
-            <IconButton
-              internal
+            <Button
+              prominence="internal"
               icon={SvgPlusCircle}
               onClick={() => {
                 setTargetMemoryId(null);
diff --git a/web/src/sections/sidebar/AgentButton.tsx b/web/src/sections/sidebar/AgentButton.tsx
index fac1ea39f5d..c9530b6a8d0 100644
--- a/web/src/sections/sidebar/AgentButton.tsx
+++ b/web/src/sections/sidebar/AgentButton.tsx
@@ -70,6 +70,7 @@ const AgentButton = memo(({ agent }: AgentButtonProps) => {
           rightChildren={
             // Hide unpin button for current agent since auto-pin would immediately re-pin
             isCurrentAgent ? null : (
+              // TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved
               <IconButton
                 icon={
                   SvgX /* We only show the unpin button for pinned agents */
diff --git a/web/src/sections/sidebar/ChatButton.tsx b/web/src/sections/sidebar/ChatButton.tsx
index 7f9e9329daf..2972a976ca7 100644
--- a/web/src/sections/sidebar/ChatButton.tsx
+++ b/web/src/sections/sidebar/ChatButton.tsx
@@ -6,7 +6,6 @@ import useChatSessions from "@/hooks/useChatSessions";
 import { deleteChatSession, renameChatSession } from "@/app/app/services/lib";
 import { ChatSession } from "@/app/app/interfaces";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
 import { cn, noProp } from "@/lib/utils";
 import Popover, { PopoverMenu } from "@/refresh-components/Popover";
 import { useAppRouter } from "@/hooks/appNavigation";
@@ -21,7 +20,7 @@ import { UNNAMED_CHAT } from "@/lib/constants";
 import ShareChatSessionModal from "@/sections/modals/ShareChatSessionModal";
 import SidebarTab from "@/refresh-components/buttons/SidebarTab";
 import IconButton from "@/refresh-components/buttons/IconButton";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { DRAG_TYPES, LOCAL_STORAGE_KEYS } from "@/sections/sidebar/constants";
 import {
@@ -75,7 +74,7 @@ export function PopoverSearchInput({
 
   return (
     <div className="flex flex-row items-center">
-      <OpalButton
+      <Button
         icon={SvgChevronLeft}
         onClick={handleClickBackButton}
         prominence="tertiary"
@@ -398,6 +397,7 @@ const ChatButton = memo(
       <>
         <Popover.Trigger asChild onClick={noProp()}>
           <div>
+            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
             <IconButton
               icon={SvgMoreHorizontal}
               className={cn(
@@ -456,7 +456,7 @@ const ChatButton = memo(
             onClose={() => setDeleteConfirmationModalOpen(false)}
             submit={
               <Button
-                danger
+                variant="danger"
                 onClick={() => {
                   setDeleteConfirmationModalOpen(false);
                   handleChatDelete();
diff --git a/web/src/sections/sidebar/ProjectFolderButton.tsx b/web/src/sections/sidebar/ProjectFolderButton.tsx
index bf9bf559f20..cd2771836ce 100644
--- a/web/src/sections/sidebar/ProjectFolderButton.tsx
+++ b/web/src/sections/sidebar/ProjectFolderButton.tsx
@@ -6,14 +6,13 @@ import { useDroppable } from "@dnd-kit/core";
 import LineItem from "@/refresh-components/buttons/LineItem";
 import Popover, { PopoverMenu } from "@/refresh-components/Popover";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
-import Button from "@/refresh-components/buttons/Button";
 import ChatButton from "@/sections/sidebar/ChatButton";
 import { useAppRouter } from "@/hooks/appNavigation";
 import { cn, noProp } from "@/lib/utils";
 import { DRAG_TYPES } from "./constants";
 import SidebarTab from "@/refresh-components/buttons/SidebarTab";
 import IconButton from "@/refresh-components/buttons/IconButton";
-import { Button as OpalButton } from "@opal/components";
+import { Button } from "@opal/components";
 import ButtonRenaming from "@/refresh-components/buttons/ButtonRenaming";
 import type { IconProps } from "@opal/types";
 import useAppFocus from "@/hooks/useAppFocus";
@@ -118,7 +117,7 @@ const ProjectFolderButton = memo(({ project }: ProjectFolderButtonProps) => {
           onClose={() => setDeleteConfirmationModalOpen(false)}
           submit={
             <Button
-              danger
+              variant="danger"
               onClick={() => {
                 setDeleteConfirmationModalOpen(false);
                 deleteProject(project.id);
@@ -138,7 +137,7 @@ const ProjectFolderButton = memo(({ project }: ProjectFolderButtonProps) => {
         <Popover.Anchor>
           <SidebarTab
             icon={() => (
-              <OpalButton
+              <Button
                 onMouseEnter={() => handleIconHover(true)}
                 onMouseLeave={() => handleIconHover(false)}
                 icon={getFolderIcon()}
@@ -156,6 +155,7 @@ const ProjectFolderButton = memo(({ project }: ProjectFolderButtonProps) => {
               <>
                 <Popover.Trigger asChild onClick={noProp()}>
                   <div>
+                    {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
                     <IconButton
                       icon={SvgMoreHorizontal}
                       className={cn(

From 92538084e9eedb8f1a3a0b65a18838449eb8b199 Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Thu, 5 Mar 2026 05:30:06 +0530
Subject: [PATCH 090/267] feat(table): add useColumnWidths, useDataTable, and
 useDraggableRows hooks (#9018)

Co-authored-by: Nik <nikolas.garza5@gmail.com>
---
 web/src/refresh-components/table/columns.ts   |   1 -
 .../table/hooks/useColumnWidths.ts            | 342 ++++++++++++++++++
 .../table/hooks/useDataTable.ts               | 249 +++++++++++++
 .../table/hooks/useDraggableRows.ts           | 156 ++++++++
 4 files changed, 747 insertions(+), 1 deletion(-)
 create mode 100644 web/src/refresh-components/table/hooks/useColumnWidths.ts
 create mode 100644 web/src/refresh-components/table/hooks/useDataTable.ts
 create mode 100644 web/src/refresh-components/table/hooks/useDraggableRows.ts

diff --git a/web/src/refresh-components/table/columns.ts b/web/src/refresh-components/table/columns.ts
index 45979949840..7ffc71ed5a4 100644
--- a/web/src/refresh-components/table/columns.ts
+++ b/web/src/refresh-components/table/columns.ts
@@ -13,7 +13,6 @@ import type {
   OnyxDataColumn,
   OnyxDisplayColumn,
   OnyxActionsColumn,
-  OnyxColumnDef,
 } from "@/refresh-components/table/types";
 import type { TableSize } from "@/refresh-components/table/TableSizeContext";
 import type { IconFunctionComponent } from "@opal/types";
diff --git a/web/src/refresh-components/table/hooks/useColumnWidths.ts b/web/src/refresh-components/table/hooks/useColumnWidths.ts
new file mode 100644
index 00000000000..2375fa47cdf
--- /dev/null
+++ b/web/src/refresh-components/table/hooks/useColumnWidths.ts
@@ -0,0 +1,342 @@
+"use client";
+
+/**
+ * useColumnWidths — Proportional column widths with splitter resize.
+ *
+ * WHY NOT TANSTACK'S BUILT-IN COLUMN SIZING?
+ *
+ * TanStack Table's column resize system (columnSizing state,
+ * header.getResizeHandler(), columnResizeMode) doesn't support the
+ * behavior our design requires:
+ *
+ * 1. No proportional fill — TanStack uses absolute pixel widths from
+ *    columnDef.size. When the container is wider than the sum of sizes,
+ *    the extra space is not distributed. We need weight-based proportional
+ *    distribution so columns fill the container at any width.
+ *
+ * 2. No splitter semantics — TanStack's resize changes one column's size
+ *    in isolation (the total table width grows/shrinks). We need "splitter"
+ *    behavior: dragging column i's right edge grows column i and shrinks
+ *    column i+1 by the same amount, keeping the total fixed. This prevents
+ *    the actions column from jittering.
+ *
+ * 3. No per-column min-width enforcement during drag — TanStack only has a
+ *    global minSize default. We enforce per-column min-widths and clamp the
+ *    drag delta so neither the dragged column nor its neighbor can shrink
+ *    below their floor.
+ *
+ * 4. No weight-based resize persistence — TanStack stores absolute pixel
+ *    deltas. When the window resizes after a column drag, the proportions
+ *    drift. We store weights, so a user-resized column scales proportionally
+ *    with the container — the ratio is preserved, not the pixel count.
+ *
+ * APPROACH:
+ *
+ * We still rely on TanStack for everything else (sorting, pagination,
+ * visibility, row selection). Only column width computation and resize
+ * interaction are handled here. The columnDef.size values are used as
+ * initial weights, and TanStack's enableResizing / getCanResize() flags
+ * are still respected in the render loop.
+ */
+
+import {
+  useState,
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+} from "react";
+import { Header } from "@tanstack/react-table";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Extracted config ready to pass to useColumnWidths. */
+export interface WidthConfig {
+  fixedColumnIds: Set<string>;
+  columnWeights: Record<string, number>;
+  columnMinWidths: Record<string, number>;
+}
+
+interface UseColumnWidthsOptions {
+  /** Visible headers from TanStack's first header group. */
+  headers: Header<any, unknown>[];
+  /** Column IDs that have fixed pixel widths (e.g. qualifier, actions). */
+  fixedColumnIds: Set<string>;
+  /** Explicit column weights (takes precedence over columnDef.size). */
+  columnWeights?: Record<string, number>;
+  /** Per-column minimum widths for data (non-fixed) columns. */
+  columnMinWidths: Record<string, number>;
+}
+
+interface UseColumnWidthsReturn {
+  /** Attach to the scrollable container for width measurement. */
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  /** Computed pixel widths keyed by column ID. */
+  columnWidths: Record<string, number>;
+  /** Factory to create a splitter resize handler for a column pair. */
+  createResizeHandler: (
+    columnId: string,
+    neighborId: string
+  ) => (event: React.MouseEvent | React.TouchEvent) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: measure container width via ResizeObserver
+// ---------------------------------------------------------------------------
+
+/** Tracks an element's content width via ResizeObserver, returning a ref and the current width. */
+function useElementWidth(): [React.RefObject<HTMLDivElement | null>, number] {
+  const ref = useRef<HTMLDivElement>(null);
+  const [width, setWidth] = useState(0);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    setWidth(el.clientWidth);
+    const ro = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) setWidth(entry.contentRect.width);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  return [ref, width];
+}
+
+// ---------------------------------------------------------------------------
+// Pure function: compute pixel widths from weights
+// ---------------------------------------------------------------------------
+
+/** Converts column weights into pixel widths, enforcing per-column minimums and fixed-column sizes. */
+function computeColumnWidths(
+  containerWidth: number,
+  headers: Header<any, unknown>[],
+  customWeights: Record<string, number>,
+  fixedColumnIds: Set<string>,
+  columnWeights: Record<string, number>,
+  columnMinWidths: Record<string, number>
+): Record<string, number> {
+  const result: Record<string, number> = {};
+
+  let fixedTotal = 0;
+  const dataColumns: { id: string; weight: number; minWidth: number }[] = [];
+
+  for (const h of headers) {
+    const baseSize = h.column.columnDef.size ?? 20;
+    if (fixedColumnIds.has(h.id)) {
+      fixedTotal += baseSize;
+    } else {
+      dataColumns.push({
+        id: h.id,
+        weight: customWeights[h.id] ?? columnWeights[h.id] ?? baseSize,
+        minWidth: columnMinWidths[h.id] ?? 50,
+      });
+    }
+  }
+
+  const tableMinWidth =
+    fixedTotal + dataColumns.reduce((sum, col) => sum + col.minWidth, 0);
+  const tableWidth =
+    containerWidth > 0 ? Math.max(containerWidth, tableMinWidth) : 0;
+
+  if (tableWidth === 0) {
+    for (const h of headers) {
+      result[h.id] = h.column.columnDef.size ?? 20;
+    }
+    return result;
+  }
+
+  const available = tableWidth - fixedTotal;
+
+  // Iterative proportional allocation with min-width clamping.
+  // Each pass clamps columns whose proportional share falls below their
+  // minimum, then redistributes remaining space. Repeats until stable.
+  let clampedTotal = 0;
+  const clamped = new Set<string>();
+
+  let stable = false;
+  while (!stable) {
+    stable = true;
+    const unclamped = dataColumns.filter((col) => !clamped.has(col.id));
+    const unclampedWeight = unclamped.reduce((s, c) => s + c.weight, 0);
+    const remaining = available - clampedTotal;
+
+    for (const col of unclamped) {
+      const proportional = remaining * (col.weight / unclampedWeight);
+      if (proportional < col.minWidth) {
+        result[col.id] = col.minWidth;
+        clampedTotal += col.minWidth;
+        clamped.add(col.id);
+        stable = false;
+      }
+    }
+  }
+
+  // Distribute remaining space among unclamped columns
+  const unclampedCols = dataColumns.filter((col) => !clamped.has(col.id));
+  const unclampedWeight = unclampedCols.reduce((s, c) => s + c.weight, 0);
+  const remainingSpace = available - clampedTotal;
+  let assigned = 0;
+
+  for (let i = 0; i < unclampedCols.length; i++) {
+    const col = unclampedCols[i]!;
+    if (i === unclampedCols.length - 1) {
+      result[col.id] = remainingSpace - assigned;
+    } else {
+      const w = Math.round(remainingSpace * (col.weight / unclampedWeight));
+      result[col.id] = w;
+      assigned += w;
+    }
+  }
+
+  // Fixed columns keep their base size
+  for (const h of headers) {
+    if (fixedColumnIds.has(h.id)) {
+      result[h.id] = h.column.columnDef.size ?? 20;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Pure function: create a splitter resize handler for a column pair
+// ---------------------------------------------------------------------------
+
+/** Creates a mouse/touch drag handler that redistributes weight between two adjacent columns. */
+function createSplitterResizeHandler(
+  columnId: string,
+  neighborId: string,
+  startColumnWidth: number,
+  startNeighborWidth: number,
+  startColumnWeight: number,
+  startNeighborWeight: number,
+  columnMinWidth: number,
+  neighborMinWidth: number,
+  setter: (value: React.SetStateAction<Record<string, number>>) => void,
+  isDraggingRef: React.MutableRefObject<boolean>
+): (event: React.MouseEvent | React.TouchEvent) => void {
+  return (event: React.MouseEvent | React.TouchEvent) => {
+    const startX =
+      "touches" in event ? event.touches[0]!.clientX : event.clientX;
+
+    isDraggingRef.current = true;
+
+    const onMove = (e: MouseEvent | TouchEvent) => {
+      const currentX =
+        "touches" in e
+          ? (e as TouchEvent).touches[0]!.clientX
+          : (e as MouseEvent).clientX;
+      const rawDelta = currentX - startX;
+      const minDelta = columnMinWidth - startColumnWidth;
+      const maxDelta = startNeighborWidth - neighborMinWidth;
+      const delta = Math.max(minDelta, Math.min(maxDelta, rawDelta));
+
+      setter((prev) => ({
+        ...prev,
+        [columnId]:
+          startColumnWeight * ((startColumnWidth + delta) / startColumnWidth),
+        [neighborId]:
+          startNeighborWeight *
+          ((startNeighborWidth - delta) / startNeighborWidth),
+      }));
+    };
+
+    const onUp = () => {
+      document.removeEventListener("mousemove", onMove);
+      document.removeEventListener("mouseup", onUp);
+      document.removeEventListener("touchmove", onMove);
+      document.removeEventListener("touchend", onUp);
+      document.removeEventListener("touchcancel", onUp);
+      document.body.style.userSelect = "";
+      document.body.style.cursor = "";
+      isDraggingRef.current = false;
+    };
+
+    document.body.style.userSelect = "none";
+    document.body.style.cursor = "col-resize";
+    document.addEventListener("mousemove", onMove);
+    document.addEventListener("mouseup", onUp);
+    document.addEventListener("touchmove", onMove);
+    document.addEventListener("touchend", onUp);
+    document.addEventListener("touchcancel", onUp);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes proportional column pixel widths from weights and provides
+ * splitter-style resize handlers that keep total table width constant.
+ *
+ * @example
+ * ```tsx
+ * const { containerRef, columnWidths, createResizeHandler } = useColumnWidths({
+ *   headers: table.getHeaderGroups()[0].headers,
+ *   fixedColumnIds: new Set(["actions"]),
+ *   columnMinWidths: { name: 120, status: 80 },
+ * });
+ * ```
+ */
+export default function useColumnWidths({
+  headers,
+  fixedColumnIds,
+  columnWeights = {},
+  columnMinWidths,
+}: UseColumnWidthsOptions): UseColumnWidthsReturn {
+  const [containerRef, containerWidth] = useElementWidth();
+  const [customWeights, setCustomWeights] = useState<Record<string, number>>(
+    {}
+  );
+  const isDraggingRef = useRef(false);
+
+  useEffect(() => {
+    return () => {
+      if (isDraggingRef.current) {
+        document.body.style.userSelect = "";
+        document.body.style.cursor = "";
+      }
+    };
+  }, []);
+
+  const columnWidths = computeColumnWidths(
+    containerWidth,
+    headers,
+    customWeights,
+    fixedColumnIds,
+    columnWeights,
+    columnMinWidths
+  );
+
+  const createResizeHandler = useCallback(
+    (columnId: string, neighborId: string) => {
+      const header = headers.find((h) => h.id === columnId);
+      const neighbor = headers.find((h) => h.id === neighborId);
+
+      return createSplitterResizeHandler(
+        columnId,
+        neighborId,
+        columnWidths[columnId] ?? 0,
+        columnWidths[neighborId] ?? 0,
+        customWeights[columnId] ??
+          columnWeights[columnId] ??
+          header?.column.columnDef.size ??
+          20,
+        customWeights[neighborId] ??
+          columnWeights[neighborId] ??
+          neighbor?.column.columnDef.size ??
+          20,
+        columnMinWidths[columnId] ?? 50,
+        columnMinWidths[neighborId] ?? 50,
+        setCustomWeights,
+        isDraggingRef
+      );
+    },
+    [headers, columnWidths, customWeights, columnWeights, columnMinWidths]
+  );
+
+  return { containerRef, columnWidths, createResizeHandler };
+}
diff --git a/web/src/refresh-components/table/hooks/useDataTable.ts b/web/src/refresh-components/table/hooks/useDataTable.ts
new file mode 100644
index 00000000000..f304299e9ac
--- /dev/null
+++ b/web/src/refresh-components/table/hooks/useDataTable.ts
@@ -0,0 +1,249 @@
+"use client";
+"use no memo";
+
+import { useState, useEffect } from "react";
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getPaginationRowModel,
+  type Table,
+  type ColumnDef,
+  type RowData,
+  type SortingState,
+  type RowSelectionState,
+  type ColumnSizingState,
+  type PaginationState,
+  type ColumnResizeMode,
+  type TableOptions,
+  type VisibilityState,
+} from "@tanstack/react-table";
+
+// ---------------------------------------------------------------------------
+// Exported types
+// ---------------------------------------------------------------------------
+
+export type OnyxSortDirection = "none" | "ascending" | "descending";
+export type OnyxSelectionState = "none" | "partial" | "all";
+
+// ---------------------------------------------------------------------------
+// Exported utility
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a TanStack sort direction to an Onyx sort direction string.
+ *
+ * This is a **named export** (not on the return object) because it is used
+ * statically inside JSX header loops, not tied to hook state.
+ */
+export function toOnyxSortDirection(
+  dir: false | "asc" | "desc"
+): OnyxSortDirection {
+  if (dir === "asc") return "ascending";
+  if (dir === "desc") return "descending";
+  return "none";
+}
+
+// ---------------------------------------------------------------------------
+// Hook options & return types
+// ---------------------------------------------------------------------------
+
+/** Keys managed internally — callers cannot override these via `tableOptions`. */
+type ManagedKeys =
+  | "data"
+  | "columns"
+  | "state"
+  | "onSortingChange"
+  | "onRowSelectionChange"
+  | "onColumnSizingChange"
+  | "onColumnVisibilityChange"
+  | "onPaginationChange"
+  | "getCoreRowModel"
+  | "getSortedRowModel"
+  | "getPaginationRowModel"
+  | "columnResizeMode"
+  | "enableRowSelection"
+  | "enableColumnResizing";
+
+/**
+ * Options accepted by {@link useDataTable}.
+ *
+ * Only `data` and `columns` are required — everything else has sensible defaults.
+ */
+interface UseDataTableOptions<TData extends RowData> {
+  /** The row data array. */
+  data: TData[];
+  /** TanStack column definitions. */
+  columns: ColumnDef<TData, any>[];
+  /** Rows per page. Set `Infinity` to disable pagination. @default 10 */
+  pageSize?: number;
+  /** Whether rows can be selected. @default true */
+  enableRowSelection?: boolean;
+  /** Whether columns can be resized. @default true */
+  enableColumnResizing?: boolean;
+  /** Resize strategy. @default "onChange" */
+  columnResizeMode?: ColumnResizeMode;
+  /** Initial sorting state. @default [] */
+  initialSorting?: SortingState;
+  /** Initial column visibility state. @default {} */
+  initialColumnVisibility?: VisibilityState;
+  /** Escape-hatch: extra options spread into `useReactTable`. Managed keys are excluded. */
+  tableOptions?: Partial<Omit<TableOptions<TData>, ManagedKeys>>;
+}
+
+/**
+ * Values returned by {@link useDataTable}.
+ */
+interface UseDataTableReturn<TData extends RowData> {
+  /** Full TanStack table instance for rendering. */
+  table: Table<TData>;
+
+  // Pagination (1-based, matching Onyx Footer)
+  /** Current page number (1-based). */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Total number of rows. */
+  totalItems: number;
+  /** Rows per page. */
+  pageSize: number;
+  /** Navigate to a page (1-based, clamped to valid range). */
+  setPage: (page: number) => void;
+  /** Whether pagination is active (pageSize is finite). */
+  isPaginated: boolean;
+
+  // Selection (pre-computed for Onyx Footer)
+  /** Aggregate selection state for the current page. */
+  selectionState: OnyxSelectionState;
+  /** Number of selected rows. */
+  selectedCount: number;
+  /** Whether every row on the current page is selected. */
+  isAllPageRowsSelected: boolean;
+  /** Deselect all rows. */
+  clearSelection: () => void;
+  /** Select or deselect all rows on the current page. */
+  toggleAllPageRowsSelected: (selected: boolean) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps TanStack `useReactTable` with Onyx-specific defaults and derived
+ * state so that consumers only need to provide `data` + `columns`.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   table, currentPage, totalPages, setPage, pageSize,
+ *   selectionState, selectedCount, clearSelection,
+ * } = useDataTable({ data: rows, columns });
+ * ```
+ */
+export default function useDataTable<TData extends RowData>(
+  options: UseDataTableOptions<TData>
+): UseDataTableReturn<TData> {
+  const {
+    data,
+    columns,
+    pageSize: pageSizeOption = 10,
+    enableRowSelection = true,
+    enableColumnResizing = true,
+    columnResizeMode = "onChange",
+    initialSorting = [],
+    initialColumnVisibility = {},
+    tableOptions,
+  } = options;
+
+  // ---- internal state -----------------------------------------------------
+  const [sorting, setSorting] = useState<SortingState>(initialSorting);
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+  const [columnSizing, setColumnSizing] = useState<ColumnSizingState>({});
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(
+    initialColumnVisibility
+  );
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: pageSizeOption,
+  });
+
+  // ---- sync pageSize prop to internal state --------------------------------
+  useEffect(() => {
+    setPagination((prev) => ({
+      ...prev,
+      pageSize: pageSizeOption,
+      pageIndex: 0,
+    }));
+  }, [pageSizeOption]);
+
+  // ---- TanStack table instance --------------------------------------------
+  const table = useReactTable({
+    data,
+    columns,
+    state: {
+      sorting,
+      rowSelection,
+      columnSizing,
+      columnVisibility,
+      pagination,
+    },
+    onSortingChange: setSorting,
+    onRowSelectionChange: setRowSelection,
+    onColumnSizingChange: setColumnSizing,
+    onColumnVisibilityChange: setColumnVisibility,
+    onPaginationChange: setPagination,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    columnResizeMode,
+    enableRowSelection,
+    enableColumnResizing,
+    ...tableOptions,
+  });
+
+  // ---- derived values -----------------------------------------------------
+  const isAllPageRowsSelected = table.getIsAllPageRowsSelected();
+  const isSomePageRowsSelected = table.getIsSomePageRowsSelected();
+
+  const selectionState: OnyxSelectionState = isAllPageRowsSelected
+    ? "all"
+    : isSomePageRowsSelected
+      ? "partial"
+      : "none";
+
+  const selectedCount = Object.keys(rowSelection).length;
+  const totalPages = Math.max(1, table.getPageCount());
+  const currentPage = pagination.pageIndex + 1;
+  const totalItems = data.length;
+  const isPaginated = isFinite(pagination.pageSize);
+
+  // ---- actions ------------------------------------------------------------
+  const setPage = (page: number) => {
+    const clamped = Math.max(1, Math.min(page, totalPages));
+    setPagination((prev) => ({ ...prev, pageIndex: clamped - 1 }));
+  };
+
+  const clearSelection = () => {
+    table.resetRowSelection();
+  };
+
+  const toggleAllPageRowsSelected = (selected: boolean) => {
+    table.toggleAllPageRowsSelected(selected);
+  };
+
+  return {
+    table,
+    currentPage,
+    totalPages,
+    totalItems,
+    pageSize: pagination.pageSize,
+    setPage,
+    isPaginated,
+    selectionState,
+    selectedCount,
+    isAllPageRowsSelected,
+    clearSelection,
+    toggleAllPageRowsSelected,
+  };
+}
diff --git a/web/src/refresh-components/table/hooks/useDraggableRows.ts b/web/src/refresh-components/table/hooks/useDraggableRows.ts
new file mode 100644
index 00000000000..c646048a325
--- /dev/null
+++ b/web/src/refresh-components/table/hooks/useDraggableRows.ts
@@ -0,0 +1,156 @@
+"use client";
+
+import { useState, useCallback, useMemo } from "react";
+import {
+  useSensors,
+  useSensor,
+  PointerSensor,
+  KeyboardSensor,
+  closestCenter,
+  type DragStartEvent,
+  type DragEndEvent,
+} from "@dnd-kit/core";
+import { arrayMove, sortableKeyboardCoordinates } from "@dnd-kit/sortable";
+import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface UseDraggableRowsOptions<TData> {
+  /** Current display-order data. */
+  data: TData[];
+  /** Extract a unique string ID from each row. */
+  getRowId: (row: TData) => string;
+  /** Whether DnD row reordering is active (e.g. set to `false` when column sorting is active). @default true */
+  enabled?: boolean;
+  /** Called after a successful reorder with the new ID order and a map of changed positions. */
+  onReorder?: (
+    ids: string[],
+    changedOrders: Record<string, number>
+  ) => void | Promise<void>;
+}
+
+interface DraggableRowsReturn {
+  /** Props to pass to TableBody's `dndSortable` prop. */
+  dndContextProps: {
+    sensors: ReturnType<typeof useSensors>;
+    collisionDetection: typeof closestCenter;
+    modifiers: Array<typeof restrictToVerticalAxis>;
+    onDragStart: (event: DragStartEvent) => void;
+    onDragEnd: (event: DragEndEvent) => void;
+    onDragCancel: () => void;
+  };
+  /** Ordered list of IDs for SortableContext. */
+  sortableItems: string[];
+  /** ID of the currently dragged row, or null. */
+  activeId: string | null;
+  /** Whether a drag is in progress. */
+  isDragging: boolean;
+  /** Whether DnD is enabled. */
+  isEnabled: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Manages drag-and-drop row reordering using @dnd-kit, providing sensor
+ * configuration, sortable item IDs, drag state, and a reorder callback
+ * that reports only the changed positions.
+ *
+ * @example
+ * ```tsx
+ * const { dndContextProps, sortableItems, activeId } = useDraggableRows({
+ *   data: rows,
+ *   getRowId: (row) => row.id,
+ *   onReorder: (ids, changed) => saveNewOrder(changed),
+ * });
+ * ```
+ */
+export default function useDraggableRows<TData>(
+  options: UseDraggableRowsOptions<TData>
+): DraggableRowsReturn {
+  const { data, getRowId, enabled = true, onReorder } = options;
+
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: 5 },
+    }),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    })
+  );
+
+  const sortableItems = useMemo(
+    () => data.map((row) => getRowId(row)),
+    [data, getRowId]
+  );
+
+  const sortableIndexMap = useMemo(() => {
+    const map = new Map<string, number>();
+    for (let i = 0; i < sortableItems.length; i++) {
+      const item = sortableItems[i];
+      if (item !== undefined) {
+        map.set(item, i);
+      }
+    }
+    return map;
+  }, [sortableItems]);
+
+  const handleDragStart = useCallback((event: DragStartEvent) => {
+    setActiveId(String(event.active.id));
+  }, []);
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      setActiveId(null);
+      if (event.activatorEvent instanceof PointerEvent) {
+        (document.activeElement as HTMLElement)?.blur();
+      }
+      const { active, over } = event;
+      if (!over || active.id === over.id) return;
+
+      const oldIndex = sortableIndexMap.get(String(active.id));
+      const newIndex = sortableIndexMap.get(String(over.id));
+      if (oldIndex === undefined || newIndex === undefined) return;
+
+      const reordered = arrayMove(sortableItems, oldIndex, newIndex);
+
+      const minIdx = Math.min(oldIndex, newIndex);
+      const maxIdx = Math.max(oldIndex, newIndex);
+      const changedOrders: Record<string, number> = {};
+      for (let i = minIdx; i <= maxIdx; i++) {
+        const id = reordered[i];
+        if (id !== undefined) {
+          changedOrders[id] = i;
+        }
+      }
+
+      onReorder?.(reordered, changedOrders);
+    },
+    [sortableItems, sortableIndexMap, onReorder]
+  );
+
+  const handleDragCancel = useCallback(() => {
+    setActiveId(null);
+  }, []);
+
+  return {
+    dndContextProps: {
+      sensors,
+      collisionDetection: closestCenter,
+      modifiers: [restrictToVerticalAxis],
+      onDragStart: handleDragStart,
+      onDragEnd: handleDragEnd,
+      onDragCancel: handleDragCancel,
+    },
+    sortableItems,
+    activeId,
+    isDragging: activeId !== null,
+    isEnabled: enabled,
+  };
+}

From 5176fd7386f2272944808f486d1757798a670f8c Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Wed, 4 Mar 2026 17:00:45 -0800
Subject: [PATCH 091/267] fix(llm): Final LLM Cleanup for Nightly Tests (#9055)

---
 .../test_nightly_provider_chat_workflow.py    | 122 ++++++++++++++++--
 1 file changed, 108 insertions(+), 14 deletions(-)

diff --git a/backend/tests/integration/tests/llm_workflows/test_nightly_provider_chat_workflow.py b/backend/tests/integration/tests/llm_workflows/test_nightly_provider_chat_workflow.py
index 2df6fbeac73..50b9124f049 100644
--- a/backend/tests/integration/tests/llm_workflows/test_nightly_provider_chat_workflow.py
+++ b/backend/tests/integration/tests/llm_workflows/test_nightly_provider_chat_workflow.py
@@ -42,6 +42,78 @@ class NightlyProviderConfig(BaseModel):
     strict: bool
 
 
+def _stringify_custom_config_value(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (dict, list)):
+        return json.dumps(value)
+    return str(value)
+
+
+def _looks_like_vertex_credentials_payload(
+    raw_custom_config: dict[object, object],
+) -> bool:
+    normalized_keys = {str(key).strip().lower() for key in raw_custom_config}
+    provider_specific_keys = {
+        "vertex_credentials",
+        "credentials_file",
+        "vertex_credentials_file",
+        "google_application_credentials",
+        "vertex_location",
+        "location",
+        "vertex_region",
+        "region",
+    }
+    if normalized_keys & provider_specific_keys:
+        return False
+
+    normalized_type = str(raw_custom_config.get("type", "")).strip().lower()
+    if normalized_type not in {"service_account", "external_account"}:
+        return False
+
+    # Service account JSON usually includes private_key/client_email, while external
+    # account JSON includes credential_source. Either shape should be accepted.
+    has_service_account_markers = any(
+        key in normalized_keys for key in {"private_key", "client_email"}
+    )
+    has_external_account_markers = "credential_source" in normalized_keys
+    return has_service_account_markers or has_external_account_markers
+
+
+def _normalize_custom_config(
+    provider: str, raw_custom_config: dict[object, object]
+) -> dict[str, str]:
+    if provider == "vertex_ai" and _looks_like_vertex_credentials_payload(
+        raw_custom_config
+    ):
+        return {"vertex_credentials": json.dumps(raw_custom_config)}
+
+    normalized: dict[str, str] = {}
+    for raw_key, raw_value in raw_custom_config.items():
+        key = str(raw_key).strip()
+        key_lower = key.lower()
+
+        if provider == "vertex_ai":
+            if key_lower in {
+                "vertex_credentials",
+                "credentials_file",
+                "vertex_credentials_file",
+                "google_application_credentials",
+            }:
+                key = "vertex_credentials"
+            elif key_lower in {
+                "vertex_location",
+                "location",
+                "vertex_region",
+                "region",
+            }:
+                key = "vertex_location"
+
+        normalized[key] = _stringify_custom_config_value(raw_value)
+
+    return normalized
+
+
 def _env_true(env_var: str, default: bool = False) -> bool:
     value = os.environ.get(env_var)
     if value is None:
@@ -80,7 +152,9 @@ def _load_provider_config() -> NightlyProviderConfig:
         parsed = json.loads(custom_config_json)
         if not isinstance(parsed, dict):
             raise ValueError(f"{_ENV_CUSTOM_CONFIG_JSON} must be a JSON object")
-        custom_config = {str(key): str(value) for key, value in parsed.items()}
+        custom_config = _normalize_custom_config(
+            provider=provider, raw_custom_config=parsed
+        )
 
     if provider == "ollama_chat" and api_key and not custom_config:
         custom_config = {"OLLAMA_API_KEY": api_key}
@@ -148,6 +222,23 @@ def _validate_provider_config(config: NightlyProviderConfig) -> None:
                 ),
             )
 
+    if config.provider == "vertex_ai":
+        has_vertex_credentials = bool(
+            config.custom_config and config.custom_config.get("vertex_credentials")
+        )
+        if not has_vertex_credentials:
+            configured_keys = (
+                sorted(config.custom_config.keys()) if config.custom_config else []
+            )
+            _skip_or_fail(
+                strict=config.strict,
+                message=(
+                    f"{_ENV_CUSTOM_CONFIG_JSON} must include 'vertex_credentials' "
+                    f"for provider '{config.provider}'. "
+                    f"Found keys: {configured_keys}"
+                ),
+            )
+
 
 def _assert_integration_mode_enabled() -> None:
     assert (
@@ -193,6 +284,7 @@ def _create_provider_payload(
     return {
         "name": provider_name,
         "provider": provider,
+        "model": model_name,
         "api_key": api_key,
         "api_base": api_base,
         "api_version": api_version,
@@ -208,24 +300,23 @@ def _create_provider_payload(
     }
 
 
-def _ensure_provider_is_default(provider_id: int, admin_user: DATestUser) -> None:
+def _ensure_provider_is_default(
+    provider_id: int, model_name: str, admin_user: DATestUser
+) -> None:
     list_response = requests.get(
         f"{API_SERVER_URL}/admin/llm/provider",
         headers=admin_user.headers,
     )
     list_response.raise_for_status()
-    providers = list_response.json()
-
-    current_default = next(
-        (provider for provider in providers if provider.get("is_default_provider")),
-        None,
+    default_text = list_response.json().get("default_text")
+    assert default_text is not None, "Expected a default provider after setting default"
+    assert default_text.get("provider_id") == provider_id, (
+        f"Expected provider {provider_id} to be default, "
+        f"found {default_text.get('provider_id')}"
     )
     assert (
-        current_default is not None
-    ), "Expected a default provider after setting provider as default"
-    assert (
-        current_default["id"] == provider_id
-    ), f"Expected provider {provider_id} to be default, found {current_default['id']}"
+        default_text.get("model_name") == model_name
+    ), f"Expected default model {model_name}, found {default_text.get('model_name')}"
 
 
 def _run_chat_assertions(
@@ -326,8 +417,9 @@ def _create_and_test_provider_for_model(
 
     try:
         set_default_response = requests.post(
-            f"{API_SERVER_URL}/admin/llm/provider/{provider_id}/default",
+            f"{API_SERVER_URL}/admin/llm/default",
             headers=admin_user.headers,
+            json={"provider_id": provider_id, "model_name": model_name},
         )
         assert set_default_response.status_code == 200, (
             f"Setting default provider failed for provider={config.provider} "
@@ -335,7 +427,9 @@ def _create_and_test_provider_for_model(
             f"{set_default_response.text}"
         )
 
-        _ensure_provider_is_default(provider_id=provider_id, admin_user=admin_user)
+        _ensure_provider_is_default(
+            provider_id=provider_id, model_name=model_name, admin_user=admin_user
+        )
         _run_chat_assertions(
             admin_user=admin_user,
             search_tool_id=search_tool_id,

From aca466b35d73bdf2275de7c8b4201e5a5e5113e8 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Wed, 4 Mar 2026 17:30:36 -0800
Subject: [PATCH 092/267] fix: doc to hierarchynode connection in pruning
 (#9046)

---
 .../onyx/background/celery/celery_utils.py    |  44 +++-
 .../background/celery/tasks/pruning/tasks.py  |  75 +++++-
 .../onyx/connectors/confluence/connector.py   |   4 +
 .../connectors/google_drive/doc_conversion.py |   1 +
 backend/onyx/connectors/jira/connector.py     |   5 +
 backend/onyx/connectors/models.py             |   1 +
 .../onyx/connectors/sharepoint/connector.py   |  25 +-
 backend/onyx/connectors/slack/connector.py    |   1 +
 backend/onyx/db/hierarchy.py                  |  49 ++++
 .../celery/test_pruning_hierarchy_nodes.py    | 241 +++++++++++++++++-
 10 files changed, 412 insertions(+), 34 deletions(-)

diff --git a/backend/onyx/background/celery/celery_utils.py b/backend/onyx/background/celery/celery_utils.py
index 4e2e9fd2f03..e4c236d560f 100644
--- a/backend/onyx/background/celery/celery_utils.py
+++ b/backend/onyx/background/celery/celery_utils.py
@@ -39,9 +39,13 @@
 
 
 class SlimConnectorExtractionResult(BaseModel):
-    """Result of extracting document IDs and hierarchy nodes from a connector."""
+    """Result of extracting document IDs and hierarchy nodes from a connector.
 
-    doc_ids: set[str]
+    raw_id_to_parent maps document ID → parent_hierarchy_raw_node_id (or None).
+    Use raw_id_to_parent.keys() wherever the old set of IDs was needed.
+    """
+
+    raw_id_to_parent: dict[str, str | None]
     hierarchy_nodes: list[HierarchyNode]
 
 
@@ -93,30 +97,37 @@ def _get_failure_id(failure: ConnectorFailure) -> str | None:
     return None
 
 
+class BatchResult(BaseModel):
+    raw_id_to_parent: dict[str, str | None]
+    hierarchy_nodes: list[HierarchyNode]
+
+
 def _extract_from_batch(
     doc_list: Sequence[Document | SlimDocument | HierarchyNode | ConnectorFailure],
-) -> tuple[set[str], list[HierarchyNode]]:
-    """Separate a batch into document IDs and hierarchy nodes.
+) -> BatchResult:
+    """Separate a batch into document IDs (with parent mapping) and hierarchy nodes.
 
     ConnectorFailure items have their failed document/entity IDs added to the
-    ID set so that failed-to-retrieve documents are not accidentally pruned.
+    ID dict so that failed-to-retrieve documents are not accidentally pruned.
     """
-    ids: set[str] = set()
+    ids: dict[str, str | None] = {}
     hierarchy_nodes: list[HierarchyNode] = []
     for item in doc_list:
         if isinstance(item, HierarchyNode):
             hierarchy_nodes.append(item)
-            ids.add(item.raw_node_id)
+            if item.raw_node_id not in ids:
+                ids[item.raw_node_id] = None
         elif isinstance(item, ConnectorFailure):
             failed_id = _get_failure_id(item)
             if failed_id:
-                ids.add(failed_id)
+                ids[failed_id] = None
             logger.warning(
                 f"Failed to retrieve document {failed_id}: " f"{item.failure_message}"
             )
         else:
-            ids.add(item.id)
-    return ids, hierarchy_nodes
+            parent_raw = getattr(item, "parent_hierarchy_raw_node_id", None)
+            ids[item.id] = parent_raw
+    return BatchResult(raw_id_to_parent=ids, hierarchy_nodes=hierarchy_nodes)
 
 
 def extract_ids_from_runnable_connector(
@@ -132,7 +143,7 @@ def extract_ids_from_runnable_connector(
 
     Optionally, a callback can be passed to handle the length of each document batch.
     """
-    all_connector_doc_ids: set[str] = set()
+    all_raw_id_to_parent: dict[str, str | None] = {}
     all_hierarchy_nodes: list[HierarchyNode] = []
 
     # Sequence (covariant) lets all the specific list[...] iterator types unify here
@@ -177,15 +188,20 @@ def extract_ids_from_runnable_connector(
                 "extract_ids_from_runnable_connector: Stop signal detected"
             )
 
-        batch_ids, batch_nodes = _extract_from_batch(doc_list)
-        all_connector_doc_ids.update(doc_batch_processing_func(batch_ids))
+        batch_result = _extract_from_batch(doc_list)
+        batch_ids = batch_result.raw_id_to_parent
+        batch_nodes = batch_result.hierarchy_nodes
+        doc_batch_processing_func(batch_ids)
+        for k, v in batch_ids.items():
+            if v is not None or k not in all_raw_id_to_parent:
+                all_raw_id_to_parent[k] = v
         all_hierarchy_nodes.extend(batch_nodes)
 
         if callback:
             callback.progress("extract_ids_from_runnable_connector", len(batch_ids))
 
     return SlimConnectorExtractionResult(
-        doc_ids=all_connector_doc_ids,
+        raw_id_to_parent=all_raw_id_to_parent,
         hierarchy_nodes=all_hierarchy_nodes,
     )
 
diff --git a/backend/onyx/background/celery/tasks/pruning/tasks.py b/backend/onyx/background/celery/tasks/pruning/tasks.py
index fadd7841ae5..4c8add72703 100644
--- a/backend/onyx/background/celery/tasks/pruning/tasks.py
+++ b/backend/onyx/background/celery/tasks/pruning/tasks.py
@@ -29,6 +29,7 @@
 from onyx.configs.constants import CELERY_PRUNING_LOCK_TIMEOUT
 from onyx.configs.constants import CELERY_TASK_WAIT_FOR_FENCE_TIMEOUT
 from onyx.configs.constants import DANSWER_REDIS_FUNCTION_LOCK_PREFIX
+from onyx.configs.constants import DocumentSource
 from onyx.configs.constants import OnyxCeleryPriority
 from onyx.configs.constants import OnyxCeleryQueues
 from onyx.configs.constants import OnyxCeleryTask
@@ -47,6 +48,8 @@
 from onyx.db.enums import ConnectorCredentialPairStatus
 from onyx.db.enums import SyncStatus
 from onyx.db.enums import SyncType
+from onyx.db.hierarchy import link_hierarchy_nodes_to_documents
+from onyx.db.hierarchy import update_document_parent_hierarchy_nodes
 from onyx.db.hierarchy import upsert_hierarchy_nodes_batch
 from onyx.db.models import ConnectorCredentialPair
 from onyx.db.sync_record import insert_sync_record
@@ -57,6 +60,8 @@
 from onyx.redis.redis_connector_prune import RedisConnectorPrunePayload
 from onyx.redis.redis_hierarchy import cache_hierarchy_nodes_batch
 from onyx.redis.redis_hierarchy import ensure_source_node_exists
+from onyx.redis.redis_hierarchy import get_node_id_from_raw_id
+from onyx.redis.redis_hierarchy import get_source_node_id_from_cache
 from onyx.redis.redis_hierarchy import HierarchyNodeCacheEntry
 from onyx.redis.redis_pool import get_redis_client
 from onyx.redis.redis_pool import get_redis_replica_client
@@ -113,6 +118,38 @@ def progress(self, tag: str, amount: int) -> None:
         super().progress(tag, amount)
 
 
+def _resolve_and_update_document_parents(
+    db_session: Session,
+    redis_client: Redis,
+    source: DocumentSource,
+    raw_id_to_parent: dict[str, str | None],
+) -> None:
+    """Resolve parent_hierarchy_raw_node_id → parent_hierarchy_node_id for
+    each document and bulk-update the DB. Mirrors the resolution logic in
+    run_docfetching.py."""
+    source_node_id = get_source_node_id_from_cache(redis_client, db_session, source)
+
+    resolved: dict[str, int | None] = {}
+    for doc_id, raw_parent_id in raw_id_to_parent.items():
+        if raw_parent_id is None:
+            continue
+        node_id, found = get_node_id_from_raw_id(redis_client, source, raw_parent_id)
+        resolved[doc_id] = node_id if found else source_node_id
+
+    if not resolved:
+        return
+
+    update_document_parent_hierarchy_nodes(
+        db_session=db_session,
+        doc_parent_map=resolved,
+        commit=True,
+    )
+    task_logger.info(
+        f"Pruning: resolved and updated parent hierarchy for "
+        f"{len(resolved)} documents (source={source.value})"
+    )
+
+
 """Jobs / utils for kicking off pruning tasks."""
 
 
@@ -535,22 +572,22 @@ def connector_pruning_generator_task(
             extraction_result = extract_ids_from_runnable_connector(
                 runnable_connector, callback
             )
-            all_connector_doc_ids = extraction_result.doc_ids
+            all_connector_doc_ids = extraction_result.raw_id_to_parent
 
             # Process hierarchy nodes (same as docfetching):
             # upsert to Postgres and cache in Redis
+            source = cc_pair.connector.source
+            redis_client = get_redis_client(tenant_id=tenant_id)
+
             if extraction_result.hierarchy_nodes:
                 is_connector_public = cc_pair.access_type == AccessType.PUBLIC
 
-                redis_client = get_redis_client(tenant_id=tenant_id)
-                ensure_source_node_exists(
-                    redis_client, db_session, cc_pair.connector.source
-                )
+                ensure_source_node_exists(redis_client, db_session, source)
 
                 upserted_nodes = upsert_hierarchy_nodes_batch(
                     db_session=db_session,
                     nodes=extraction_result.hierarchy_nodes,
-                    source=cc_pair.connector.source,
+                    source=source,
                     commit=True,
                     is_connector_public=is_connector_public,
                 )
@@ -561,7 +598,7 @@ def connector_pruning_generator_task(
                 ]
                 cache_hierarchy_nodes_batch(
                     redis_client=redis_client,
-                    source=cc_pair.connector.source,
+                    source=source,
                     entries=cache_entries,
                 )
 
@@ -570,6 +607,26 @@ def connector_pruning_generator_task(
                     f"hierarchy nodes for cc_pair={cc_pair_id}"
                 )
 
+            ensure_source_node_exists(redis_client, db_session, source)
+            # Resolve parent_hierarchy_raw_node_id → parent_hierarchy_node_id
+            # and bulk-update documents, mirroring the docfetching resolution
+            _resolve_and_update_document_parents(
+                db_session=db_session,
+                redis_client=redis_client,
+                source=source,
+                raw_id_to_parent=all_connector_doc_ids,
+            )
+
+            # Link hierarchy nodes to documents for sources where pages can be
+            # both hierarchy nodes AND documents (e.g. Notion, Confluence)
+            all_doc_id_list = list(all_connector_doc_ids.keys())
+            link_hierarchy_nodes_to_documents(
+                db_session=db_session,
+                document_ids=all_doc_id_list,
+                source=source,
+                commit=True,
+            )
+
             # a list of docs in our local index
             all_indexed_document_ids = {
                 doc.id
@@ -581,7 +638,9 @@ def connector_pruning_generator_task(
             }
 
             # generate list of docs to remove (no longer in the source)
-            doc_ids_to_remove = list(all_indexed_document_ids - all_connector_doc_ids)
+            doc_ids_to_remove = list(
+                all_indexed_document_ids - all_connector_doc_ids.keys()
+            )
 
             task_logger.info(
                 "Pruning set collected: "
diff --git a/backend/onyx/connectors/confluence/connector.py b/backend/onyx/connectors/confluence/connector.py
index bbd343bb1cf..462cd625d55 100644
--- a/backend/onyx/connectors/confluence/connector.py
+++ b/backend/onyx/connectors/confluence/connector.py
@@ -943,6 +943,9 @@ def get_external_access(
                         if include_permissions
                         else None
                     ),
+                    parent_hierarchy_raw_node_id=self._get_parent_hierarchy_raw_id(
+                        page
+                    ),
                 )
             )
 
@@ -992,6 +995,7 @@ def get_external_access(
                             if include_permissions
                             else None
                         ),
+                        parent_hierarchy_raw_node_id=page_id,
                     )
                 )
 
diff --git a/backend/onyx/connectors/google_drive/doc_conversion.py b/backend/onyx/connectors/google_drive/doc_conversion.py
index 2e8cf3d9f92..4aa731a2a8a 100644
--- a/backend/onyx/connectors/google_drive/doc_conversion.py
+++ b/backend/onyx/connectors/google_drive/doc_conversion.py
@@ -781,4 +781,5 @@ def build_slim_document(
     return SlimDocument(
         id=onyx_document_id_from_drive_file(file),
         external_access=external_access,
+        parent_hierarchy_raw_node_id=(file.get("parents") or [None])[0],
     )
diff --git a/backend/onyx/connectors/jira/connector.py b/backend/onyx/connectors/jira/connector.py
index 2050a7901ae..4751705307f 100644
--- a/backend/onyx/connectors/jira/connector.py
+++ b/backend/onyx/connectors/jira/connector.py
@@ -902,6 +902,11 @@ def retrieve_all_slim_docs_perm_sync(
                         external_access=self._get_project_permissions(
                             project_key, add_prefix=False
                         ),
+                        parent_hierarchy_raw_node_id=(
+                            self._get_parent_hierarchy_raw_node_id(issue, project_key)
+                            if project_key
+                            else None
+                        ),
                     )
                 )
                 current_offset += 1
diff --git a/backend/onyx/connectors/models.py b/backend/onyx/connectors/models.py
index 1298e18653e..a2cb446dcd7 100644
--- a/backend/onyx/connectors/models.py
+++ b/backend/onyx/connectors/models.py
@@ -385,6 +385,7 @@ def get_total_char_length(self) -> int:
 class SlimDocument(BaseModel):
     id: str
     external_access: ExternalAccess | None = None
+    parent_hierarchy_raw_node_id: str | None = None
 
 
 class HierarchyNode(BaseModel):
diff --git a/backend/onyx/connectors/sharepoint/connector.py b/backend/onyx/connectors/sharepoint/connector.py
index ab009f059e2..5a38015cee5 100644
--- a/backend/onyx/connectors/sharepoint/connector.py
+++ b/backend/onyx/connectors/sharepoint/connector.py
@@ -772,6 +772,7 @@ def _convert_driveitem_to_slim_document(
     drive_name: str,
     ctx: ClientContext,
     graph_client: GraphClient,
+    parent_hierarchy_raw_node_id: str | None = None,
 ) -> SlimDocument:
     if driveitem.id is None:
         raise ValueError("DriveItem ID is required")
@@ -787,11 +788,15 @@ def _convert_driveitem_to_slim_document(
     return SlimDocument(
         id=driveitem.id,
         external_access=external_access,
+        parent_hierarchy_raw_node_id=parent_hierarchy_raw_node_id,
     )
 
 
 def _convert_sitepage_to_slim_document(
-    site_page: dict[str, Any], ctx: ClientContext | None, graph_client: GraphClient
+    site_page: dict[str, Any],
+    ctx: ClientContext | None,
+    graph_client: GraphClient,
+    parent_hierarchy_raw_node_id: str | None = None,
 ) -> SlimDocument:
     """Convert a SharePoint site page to a SlimDocument object."""
     if site_page.get("id") is None:
@@ -808,6 +813,7 @@ def _convert_sitepage_to_slim_document(
     return SlimDocument(
         id=id,
         external_access=external_access,
+        parent_hierarchy_raw_node_id=parent_hierarchy_raw_node_id,
     )
 
 
@@ -1594,12 +1600,22 @@ def _fetch_slim_documents_from_sharepoint(self) -> GenerateSlimDocumentOutput:
                             )
                         )
 
+                    parent_hierarchy_url: str | None = None
+                    if drive_web_url:
+                        parent_hierarchy_url = self._get_parent_hierarchy_url(
+                            site_url, drive_web_url, drive_name, driveitem
+                        )
+
                     try:
                         logger.debug(f"Processing: {driveitem.web_url}")
                         ctx = self._create_rest_client_context(site_descriptor.url)
                         doc_batch.append(
                             _convert_driveitem_to_slim_document(
-                                driveitem, drive_name, ctx, self.graph_client
+                                driveitem,
+                                drive_name,
+                                ctx,
+                                self.graph_client,
+                                parent_hierarchy_raw_node_id=parent_hierarchy_url,
                             )
                         )
                     except Exception as e:
@@ -1619,7 +1635,10 @@ def _fetch_slim_documents_from_sharepoint(self) -> GenerateSlimDocumentOutput:
                     ctx = self._create_rest_client_context(site_descriptor.url)
                     doc_batch.append(
                         _convert_sitepage_to_slim_document(
-                            site_page, ctx, self.graph_client
+                            site_page,
+                            ctx,
+                            self.graph_client,
+                            parent_hierarchy_raw_node_id=site_descriptor.url,
                         )
                     )
                     if len(doc_batch) >= SLIM_BATCH_SIZE:
diff --git a/backend/onyx/connectors/slack/connector.py b/backend/onyx/connectors/slack/connector.py
index ce30399d2fe..ea6c2200656 100644
--- a/backend/onyx/connectors/slack/connector.py
+++ b/backend/onyx/connectors/slack/connector.py
@@ -565,6 +565,7 @@ def _get_all_doc_ids(
                             channel_id=channel_id, thread_ts=message["ts"]
                         ),
                         external_access=external_access,
+                        parent_hierarchy_raw_node_id=channel_id,
                     )
                 )
 
diff --git a/backend/onyx/db/hierarchy.py b/backend/onyx/db/hierarchy.py
index 4b9aceba2b4..bf2bf996477 100644
--- a/backend/onyx/db/hierarchy.py
+++ b/backend/onyx/db/hierarchy.py
@@ -1,5 +1,7 @@
 """CRUD operations for HierarchyNode."""
 
+from collections import defaultdict
+
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
@@ -525,6 +527,53 @@ def get_document_parent_hierarchy_node_ids(
     return {doc_id: parent_id for doc_id, parent_id in results}
 
 
+def update_document_parent_hierarchy_nodes(
+    db_session: Session,
+    doc_parent_map: dict[str, int | None],
+    commit: bool = True,
+) -> int:
+    """Bulk-update Document.parent_hierarchy_node_id for multiple documents.
+
+    Only updates rows whose current value differs from the desired value to
+    avoid unnecessary writes.
+
+    Args:
+        db_session: SQLAlchemy session
+        doc_parent_map: Mapping of document_id → desired parent_hierarchy_node_id
+        commit: Whether to commit the transaction
+
+    Returns:
+        Number of documents actually updated
+    """
+    if not doc_parent_map:
+        return 0
+
+    doc_ids = list(doc_parent_map.keys())
+    existing = get_document_parent_hierarchy_node_ids(db_session, doc_ids)
+
+    by_parent: dict[int | None, list[str]] = defaultdict(list)
+    for doc_id, desired_parent_id in doc_parent_map.items():
+        current = existing.get(doc_id)
+        if current == desired_parent_id or doc_id not in existing:
+            continue
+        by_parent[desired_parent_id].append(doc_id)
+
+    updated = 0
+    for desired_parent_id, ids in by_parent.items():
+        db_session.query(Document).filter(Document.id.in_(ids)).update(
+            {Document.parent_hierarchy_node_id: desired_parent_id},
+            synchronize_session=False,
+        )
+        updated += len(ids)
+
+    if commit:
+        db_session.commit()
+    elif updated:
+        db_session.flush()
+
+    return updated
+
+
 def update_hierarchy_node_permissions(
     db_session: Session,
     raw_node_id: str,
diff --git a/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py b/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py
index 4e40b8adbc3..719614ac6ab 100644
--- a/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py
+++ b/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py
@@ -5,6 +5,8 @@
 1. extract_ids_from_runnable_connector correctly separates hierarchy nodes from doc IDs
 2. Extracted hierarchy nodes are correctly upserted to Postgres via upsert_hierarchy_nodes_batch
 3. Upserting is idempotent (running twice doesn't duplicate nodes)
+4. Document-to-hierarchy-node linkage is updated during pruning
+5. link_hierarchy_nodes_to_documents links nodes that are also documents
 
 Uses a mock SlimConnectorWithPermSync that yields known hierarchy nodes and slim documents,
 combined with a real PostgreSQL database for verifying persistence.
@@ -27,9 +29,13 @@
 from onyx.db.hierarchy import ensure_source_node_exists
 from onyx.db.hierarchy import get_all_hierarchy_nodes_for_source
 from onyx.db.hierarchy import get_hierarchy_node_by_raw_id
+from onyx.db.hierarchy import link_hierarchy_nodes_to_documents
+from onyx.db.hierarchy import update_document_parent_hierarchy_nodes
 from onyx.db.hierarchy import upsert_hierarchy_nodes_batch
+from onyx.db.models import Document as DbDocument
 from onyx.db.models import HierarchyNode as DBHierarchyNode
 from onyx.indexing.indexing_heartbeat import IndexingHeartbeatInterface
+from onyx.kg.models import KGStage
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -89,8 +95,18 @@ def _make_hierarchy_nodes() -> list[PydanticHierarchyNode]:
     ]
 
 
+DOC_PARENT_MAP = {
+    "msg-001": CHANNEL_A_ID,
+    "msg-002": CHANNEL_A_ID,
+    "msg-003": CHANNEL_B_ID,
+}
+
+
 def _make_slim_docs() -> list[SlimDocument | PydanticHierarchyNode]:
-    return [SlimDocument(id=doc_id) for doc_id in SLIM_DOC_IDS]
+    return [
+        SlimDocument(id=doc_id, parent_hierarchy_raw_node_id=DOC_PARENT_MAP.get(doc_id))
+        for doc_id in SLIM_DOC_IDS
+    ]
 
 
 class MockSlimConnectorWithPermSync(SlimConnectorWithPermSync):
@@ -126,14 +142,31 @@ def _generate(self) -> Iterator[list[SlimDocument | PydanticHierarchyNode]]:
 # ---------------------------------------------------------------------------
 
 
-def _cleanup_test_hierarchy_nodes(db_session: Session) -> None:
-    """Remove all hierarchy nodes for TEST_SOURCE to isolate tests."""
+def _cleanup_test_data(db_session: Session) -> None:
+    """Remove all test hierarchy nodes and documents to isolate tests."""
+    for doc_id in SLIM_DOC_IDS:
+        db_session.query(DbDocument).filter(DbDocument.id == doc_id).delete()
     db_session.query(DBHierarchyNode).filter(
         DBHierarchyNode.source == TEST_SOURCE
     ).delete()
     db_session.commit()
 
 
+def _create_test_documents(db_session: Session) -> list[DbDocument]:
+    """Insert minimal Document rows for our test doc IDs."""
+    docs = []
+    for doc_id in SLIM_DOC_IDS:
+        doc = DbDocument(
+            id=doc_id,
+            semantic_id=doc_id,
+            kg_stage=KGStage.NOT_STARTED,
+        )
+        db_session.add(doc)
+        docs.append(doc)
+    db_session.commit()
+    return docs
+
+
 # ---------------------------------------------------------------------------
 # Tests
 # ---------------------------------------------------------------------------
@@ -147,14 +180,14 @@ def test_pruning_extracts_hierarchy_nodes(db_session: Session) -> None:  # noqa:
     result = extract_ids_from_runnable_connector(connector, callback=None)
 
     # Doc IDs should include both slim doc IDs and hierarchy node raw_node_ids
-    # (hierarchy node IDs are added to doc_ids so they aren't pruned)
+    # (hierarchy node IDs are added to raw_id_to_parent so they aren't pruned)
     expected_ids = {
         CHANNEL_A_ID,
         CHANNEL_B_ID,
         CHANNEL_C_ID,
         *SLIM_DOC_IDS,
     }
-    assert result.doc_ids == expected_ids
+    assert result.raw_id_to_parent.keys() == expected_ids
 
     # Hierarchy nodes should be the 3 channels
     assert len(result.hierarchy_nodes) == 3
@@ -165,7 +198,7 @@ def test_pruning_extracts_hierarchy_nodes(db_session: Session) -> None:  # noqa:
 def test_pruning_upserts_hierarchy_nodes_to_db(db_session: Session) -> None:
     """Full flow: extract hierarchy nodes from mock connector, upsert to Postgres,
     then verify the DB state (node count, parent relationships, permissions)."""
-    _cleanup_test_hierarchy_nodes(db_session)
+    _cleanup_test_data(db_session)
 
     # Step 1: ensure the SOURCE node exists (mirrors what the pruning task does)
     source_node = ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
@@ -230,7 +263,7 @@ def test_pruning_upserts_hierarchy_nodes_public_connector(
 ) -> None:
     """When the connector's access type is PUBLIC, all hierarchy nodes must be
     marked is_public=True regardless of their external_access settings."""
-    _cleanup_test_hierarchy_nodes(db_session)
+    _cleanup_test_data(db_session)
 
     ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
 
@@ -257,7 +290,7 @@ def test_pruning_upserts_hierarchy_nodes_public_connector(
 def test_pruning_hierarchy_node_upsert_idempotency(db_session: Session) -> None:
     """Upserting the same hierarchy nodes twice must not create duplicates.
     The second call should update existing rows in place."""
-    _cleanup_test_hierarchy_nodes(db_session)
+    _cleanup_test_data(db_session)
 
     ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
 
@@ -295,7 +328,7 @@ def test_pruning_hierarchy_node_upsert_idempotency(db_session: Session) -> None:
 
 def test_pruning_hierarchy_node_upsert_updates_fields(db_session: Session) -> None:
     """Upserting a hierarchy node with changed fields should update the existing row."""
-    _cleanup_test_hierarchy_nodes(db_session)
+    _cleanup_test_data(db_session)
 
     ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
 
@@ -342,3 +375,193 @@ def test_pruning_hierarchy_node_upsert_updates_fields(db_session: Session) -> No
     assert db_node.is_public is True
     assert db_node.external_user_emails is not None
     assert set(db_node.external_user_emails) == {"new_user@example.com"}
+
+
+# ---------------------------------------------------------------------------
+# Document-to-hierarchy-node linkage tests
+# ---------------------------------------------------------------------------
+
+
+def test_extraction_preserves_parent_hierarchy_raw_node_id(
+    db_session: Session,  # noqa: ARG001
+) -> None:
+    """extract_ids_from_runnable_connector should carry the
+    parent_hierarchy_raw_node_id from SlimDocument into the raw_id_to_parent dict."""
+    connector = MockSlimConnectorWithPermSync()
+    result = extract_ids_from_runnable_connector(connector, callback=None)
+
+    for doc_id, expected_parent in DOC_PARENT_MAP.items():
+        assert (
+            result.raw_id_to_parent[doc_id] == expected_parent
+        ), f"raw_id_to_parent[{doc_id}] should be {expected_parent}"
+
+    # Hierarchy node entries have None parent (they aren't documents)
+    for channel_id in [CHANNEL_A_ID, CHANNEL_B_ID, CHANNEL_C_ID]:
+        assert result.raw_id_to_parent[channel_id] is None
+
+
+def test_update_document_parent_hierarchy_nodes(db_session: Session) -> None:
+    """update_document_parent_hierarchy_nodes should set
+    Document.parent_hierarchy_node_id for each document in the mapping."""
+    _cleanup_test_data(db_session)
+
+    source_node = ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
+    upserted = upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=_make_hierarchy_nodes(),
+        source=TEST_SOURCE,
+        commit=True,
+        is_connector_public=False,
+    )
+    node_id_by_raw = {n.raw_node_id: n.id for n in upserted}
+
+    # Create documents with no parent set
+    docs = _create_test_documents(db_session)
+    for doc in docs:
+        assert doc.parent_hierarchy_node_id is None
+
+    # Build resolved map (same logic as _resolve_and_update_document_parents)
+    resolved: dict[str, int | None] = {}
+    for doc_id, raw_parent in DOC_PARENT_MAP.items():
+        resolved[doc_id] = node_id_by_raw.get(raw_parent, source_node.id)
+
+    updated = update_document_parent_hierarchy_nodes(
+        db_session=db_session,
+        doc_parent_map=resolved,
+        commit=True,
+    )
+    assert updated == len(SLIM_DOC_IDS)
+
+    # Verify each document now points to the correct hierarchy node
+    db_session.expire_all()
+    for doc_id, raw_parent in DOC_PARENT_MAP.items():
+        tmp_doc = db_session.get(DbDocument, doc_id)
+        assert tmp_doc is not None
+        doc = tmp_doc
+        expected_node_id = node_id_by_raw[raw_parent]
+        assert (
+            doc.parent_hierarchy_node_id == expected_node_id
+        ), f"Document {doc_id} should point to node for {raw_parent}"
+
+
+def test_update_document_parent_is_idempotent(db_session: Session) -> None:
+    """Running update_document_parent_hierarchy_nodes a second time with the
+    same mapping should update zero rows."""
+    _cleanup_test_data(db_session)
+
+    ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
+    upserted = upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=_make_hierarchy_nodes(),
+        source=TEST_SOURCE,
+        commit=True,
+        is_connector_public=False,
+    )
+    node_id_by_raw = {n.raw_node_id: n.id for n in upserted}
+    _create_test_documents(db_session)
+
+    resolved: dict[str, int | None] = {
+        doc_id: node_id_by_raw[raw_parent]
+        for doc_id, raw_parent in DOC_PARENT_MAP.items()
+    }
+
+    first_updated = update_document_parent_hierarchy_nodes(
+        db_session=db_session,
+        doc_parent_map=resolved,
+        commit=True,
+    )
+    assert first_updated == len(SLIM_DOC_IDS)
+
+    second_updated = update_document_parent_hierarchy_nodes(
+        db_session=db_session,
+        doc_parent_map=resolved,
+        commit=True,
+    )
+    assert second_updated == 0
+
+
+def test_link_hierarchy_nodes_to_documents_for_confluence(
+    db_session: Session,
+) -> None:
+    """For sources in SOURCES_WITH_HIERARCHY_NODE_DOCUMENTS (e.g. Confluence),
+    link_hierarchy_nodes_to_documents should set HierarchyNode.document_id
+    when a hierarchy node's raw_node_id matches a document ID."""
+    _cleanup_test_data(db_session)
+    confluence_source = DocumentSource.CONFLUENCE
+
+    # Clean up any existing Confluence hierarchy nodes
+    db_session.query(DBHierarchyNode).filter(
+        DBHierarchyNode.source == confluence_source
+    ).delete()
+    db_session.commit()
+
+    ensure_source_node_exists(db_session, confluence_source, commit=True)
+
+    # Create a hierarchy node whose raw_node_id matches a document ID
+    page_node_id = "confluence-page-123"
+    nodes = [
+        PydanticHierarchyNode(
+            raw_node_id=page_node_id,
+            raw_parent_id=None,
+            display_name="Test Page",
+            link="https://wiki.example.com/page/123",
+            node_type=HierarchyNodeType.PAGE,
+        ),
+    ]
+    upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=nodes,
+        source=confluence_source,
+        commit=True,
+        is_connector_public=False,
+    )
+
+    # Verify the node exists but has no document_id yet
+    db_node = get_hierarchy_node_by_raw_id(db_session, page_node_id, confluence_source)
+    assert db_node is not None
+    assert db_node.document_id is None
+
+    # Create a document with the same ID as the hierarchy node
+    doc = DbDocument(
+        id=page_node_id,
+        semantic_id="Test Page",
+        kg_stage=KGStage.NOT_STARTED,
+    )
+    db_session.add(doc)
+    db_session.commit()
+
+    # Link nodes to documents
+    linked = link_hierarchy_nodes_to_documents(
+        db_session=db_session,
+        document_ids=[page_node_id],
+        source=confluence_source,
+        commit=True,
+    )
+    assert linked == 1
+
+    # Verify the hierarchy node now has document_id set
+    db_session.expire_all()
+    db_node = get_hierarchy_node_by_raw_id(db_session, page_node_id, confluence_source)
+    assert db_node is not None
+    assert db_node.document_id == page_node_id
+
+    # Cleanup
+    db_session.query(DbDocument).filter(DbDocument.id == page_node_id).delete()
+    db_session.query(DBHierarchyNode).filter(
+        DBHierarchyNode.source == confluence_source
+    ).delete()
+    db_session.commit()
+
+
+def test_link_hierarchy_nodes_skips_non_hierarchy_sources(
+    db_session: Session,
+) -> None:
+    """link_hierarchy_nodes_to_documents should return 0 for sources that
+    don't support hierarchy-node-as-document (e.g. Slack, Google Drive)."""
+    linked = link_hierarchy_nodes_to_documents(
+        db_session=db_session,
+        document_ids=SLIM_DOC_IDS,
+        source=TEST_SOURCE,  # Slack — not in SOURCES_WITH_HIERARCHY_NODE_DOCUMENTS
+        commit=False,
+    )
+    assert linked == 0

From 47d9a9e1ac8077ef944002d1f501a2d3abe766f1 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Wed, 4 Mar 2026 17:41:03 -0800
Subject: [PATCH 093/267] feat(document index): Re-enable search settings swap
 (#9005)

---
 backend/onyx/db/search_settings.py            |   2 +-
 .../document_index/document_index_utils.py    |   3 -
 backend/onyx/document_index/factory.py        |  52 ++++-
 .../opensearch/opensearch_document_index.py   |  70 +++++-
 backend/onyx/document_index/vespa/index.py    |  63 ++++--
 backend/onyx/server/manage/search_settings.py | 201 +++++++++---------
 .../search_settings/test_search_settings.py   |  12 +-
 .../search_settings/test_search_settings.py   |   5 -
 8 files changed, 265 insertions(+), 143 deletions(-)

diff --git a/backend/onyx/db/search_settings.py b/backend/onyx/db/search_settings.py
index ed6477205e4..b16f517eec2 100644
--- a/backend/onyx/db/search_settings.py
+++ b/backend/onyx/db/search_settings.py
@@ -129,7 +129,7 @@ def get_current_search_settings(db_session: Session) -> SearchSettings:
     latest_settings = result.scalars().first()
 
     if not latest_settings:
-        raise RuntimeError("No search settings specified, DB is not in a valid state")
+        raise RuntimeError("No search settings specified; DB is not in a valid state.")
     return latest_settings
 
 
diff --git a/backend/onyx/document_index/document_index_utils.py b/backend/onyx/document_index/document_index_utils.py
index dc78921412d..f3b8489e79e 100644
--- a/backend/onyx/document_index/document_index_utils.py
+++ b/backend/onyx/document_index/document_index_utils.py
@@ -32,9 +32,6 @@ def get_multipass_config(search_settings: SearchSettings) -> MultipassConfig:
     Determines whether to enable multipass and large chunks by examining
     the current search settings and the embedder configuration.
     """
-    if not search_settings:
-        return MultipassConfig(multipass_indexing=False, enable_large_chunks=False)
-
     multipass = should_use_multipass(search_settings)
     enable_large_chunks = SearchSettings.can_use_large_chunks(
         multipass, search_settings.model_name, search_settings.provider_type
diff --git a/backend/onyx/document_index/factory.py b/backend/onyx/document_index/factory.py
index 1bf6a03f026..a7db8e54cca 100644
--- a/backend/onyx/document_index/factory.py
+++ b/backend/onyx/document_index/factory.py
@@ -26,11 +26,10 @@ def get_default_document_index(
     To be used for retrieval only. Indexing should be done through both indices
     until Vespa is deprecated.
 
-    Pre-existing docstring for this function, although secondary indices are not
-    currently supported:
     Primary index is the index that is used for querying/updating etc. Secondary
     index is for when both the currently used index and the upcoming index both
-    need to be updated, updates are applied to both indices.
+    need to be updated. Updates are applied to both indices.
+    WARNING: In that case, get_all_document_indices should be used.
     """
     if DISABLE_VECTOR_DB:
         return DisabledDocumentIndex(
@@ -51,11 +50,26 @@ def get_default_document_index(
     opensearch_retrieval_enabled = get_opensearch_retrieval_state(db_session)
     if opensearch_retrieval_enabled:
         indexing_setting = IndexingSetting.from_db_model(search_settings)
+        secondary_indexing_setting = (
+            IndexingSetting.from_db_model(secondary_search_settings)
+            if secondary_search_settings
+            else None
+        )
         return OpenSearchOldDocumentIndex(
             index_name=search_settings.index_name,
             embedding_dim=indexing_setting.final_embedding_dim,
             embedding_precision=indexing_setting.embedding_precision,
             secondary_index_name=secondary_index_name,
+            secondary_embedding_dim=(
+                secondary_indexing_setting.final_embedding_dim
+                if secondary_indexing_setting
+                else None
+            ),
+            secondary_embedding_precision=(
+                secondary_indexing_setting.embedding_precision
+                if secondary_indexing_setting
+                else None
+            ),
             large_chunks_enabled=search_settings.large_chunks_enabled,
             secondary_large_chunks_enabled=secondary_large_chunks_enabled,
             multitenant=MULTI_TENANT,
@@ -86,8 +100,7 @@ def get_all_document_indices(
     Used for indexing only. Until Vespa is deprecated we will index into both
     document indices. Retrieval is done through only one index however.
 
-    Large chunks and secondary indices are not currently supported so we
-    hardcode appropriate values.
+    Large chunks are not currently supported so we hardcode appropriate values.
 
     NOTE: Make sure the Vespa index object is returned first. In the rare event
     that there is some conflict between indexing and the migration task, it is
@@ -123,13 +136,36 @@ def get_all_document_indices(
     opensearch_document_index: OpenSearchOldDocumentIndex | None = None
     if ENABLE_OPENSEARCH_INDEXING_FOR_ONYX:
         indexing_setting = IndexingSetting.from_db_model(search_settings)
+        secondary_indexing_setting = (
+            IndexingSetting.from_db_model(secondary_search_settings)
+            if secondary_search_settings
+            else None
+        )
         opensearch_document_index = OpenSearchOldDocumentIndex(
             index_name=search_settings.index_name,
             embedding_dim=indexing_setting.final_embedding_dim,
             embedding_precision=indexing_setting.embedding_precision,
-            secondary_index_name=None,
-            large_chunks_enabled=False,
-            secondary_large_chunks_enabled=None,
+            secondary_index_name=(
+                secondary_search_settings.index_name
+                if secondary_search_settings
+                else None
+            ),
+            secondary_embedding_dim=(
+                secondary_indexing_setting.final_embedding_dim
+                if secondary_indexing_setting
+                else None
+            ),
+            secondary_embedding_precision=(
+                secondary_indexing_setting.embedding_precision
+                if secondary_indexing_setting
+                else None
+            ),
+            large_chunks_enabled=search_settings.large_chunks_enabled,
+            secondary_large_chunks_enabled=(
+                secondary_search_settings.large_chunks_enabled
+                if secondary_search_settings
+                else None
+            ),
             multitenant=MULTI_TENANT,
             httpx_client=httpx_client,
         )
diff --git a/backend/onyx/document_index/opensearch/opensearch_document_index.py b/backend/onyx/document_index/opensearch/opensearch_document_index.py
index 7eb0d20cf8b..035faa1b87a 100644
--- a/backend/onyx/document_index/opensearch/opensearch_document_index.py
+++ b/backend/onyx/document_index/opensearch/opensearch_document_index.py
@@ -271,6 +271,9 @@ def __init__(
         embedding_dim: int,
         embedding_precision: EmbeddingPrecision,
         secondary_index_name: str | None,
+        secondary_embedding_dim: int | None,
+        secondary_embedding_precision: EmbeddingPrecision | None,
+        # NOTE: We do not support large chunks right now.
         large_chunks_enabled: bool,  # noqa: ARG002
         secondary_large_chunks_enabled: bool | None,  # noqa: ARG002
         multitenant: bool = False,
@@ -286,12 +289,25 @@ def __init__(
                 f"Expected {MULTI_TENANT}, got {multitenant}."
             )
         tenant_id = get_current_tenant_id()
+        tenant_state = TenantState(tenant_id=tenant_id, multitenant=multitenant)
         self._real_index = OpenSearchDocumentIndex(
-            tenant_state=TenantState(tenant_id=tenant_id, multitenant=multitenant),
+            tenant_state=tenant_state,
             index_name=index_name,
             embedding_dim=embedding_dim,
             embedding_precision=embedding_precision,
         )
+        self._secondary_real_index: OpenSearchDocumentIndex | None = None
+        if self.secondary_index_name:
+            if secondary_embedding_dim is None or secondary_embedding_precision is None:
+                raise ValueError(
+                    "Bug: Secondary index embedding dimension and precision are not set."
+                )
+            self._secondary_real_index = OpenSearchDocumentIndex(
+                tenant_state=tenant_state,
+                index_name=self.secondary_index_name,
+                embedding_dim=secondary_embedding_dim,
+                embedding_precision=secondary_embedding_precision,
+            )
 
     @staticmethod
     def register_multitenant_indices(
@@ -307,19 +323,38 @@ def ensure_indices_exist(
         self,
         primary_embedding_dim: int,
         primary_embedding_precision: EmbeddingPrecision,
-        secondary_index_embedding_dim: int | None,  # noqa: ARG002
-        secondary_index_embedding_precision: EmbeddingPrecision | None,  # noqa: ARG002
+        secondary_index_embedding_dim: int | None,
+        secondary_index_embedding_precision: EmbeddingPrecision | None,
     ) -> None:
-        # Only handle primary index for now, ignore secondary.
-        return self._real_index.verify_and_create_index_if_necessary(
+        self._real_index.verify_and_create_index_if_necessary(
             primary_embedding_dim, primary_embedding_precision
         )
+        if self.secondary_index_name:
+            if (
+                secondary_index_embedding_dim is None
+                or secondary_index_embedding_precision is None
+            ):
+                raise ValueError(
+                    "Bug: Secondary index embedding dimension and precision are not set."
+                )
+            assert (
+                self._secondary_real_index is not None
+            ), "Bug: Secondary index is not initialized."
+            self._secondary_real_index.verify_and_create_index_if_necessary(
+                secondary_index_embedding_dim, secondary_index_embedding_precision
+            )
 
     def index(
         self,
         chunks: list[DocMetadataAwareIndexChunk],
         index_batch_params: IndexBatchParams,
     ) -> set[OldDocumentInsertionRecord]:
+        """
+        NOTE: Do NOT consider the secondary index here. A separate indexing
+        pipeline will be responsible for indexing to the secondary index. This
+        design is not ideal and we should reconsider this when revamping index
+        swapping.
+        """
         # Convert IndexBatchParams to IndexingMetadata.
         chunk_counts: dict[str, IndexingMetadata.ChunkCounts] = {}
         for doc_id in index_batch_params.doc_id_to_new_chunk_cnt:
@@ -351,7 +386,20 @@ def delete_single(
         tenant_id: str,  # noqa: ARG002
         chunk_count: int | None,
     ) -> int:
-        return self._real_index.delete(doc_id, chunk_count)
+        """
+        NOTE: Remember to handle the secondary index here. There is no separate
+        pipeline for deleting chunks in the secondary index. This design is not
+        ideal and we should reconsider this when revamping index swapping.
+        """
+        total_chunks_deleted = self._real_index.delete(doc_id, chunk_count)
+        if self.secondary_index_name:
+            assert (
+                self._secondary_real_index is not None
+            ), "Bug: Secondary index is not initialized."
+            total_chunks_deleted += self._secondary_real_index.delete(
+                doc_id, chunk_count
+            )
+        return total_chunks_deleted
 
     def update_single(
         self,
@@ -362,6 +410,11 @@ def update_single(
         fields: VespaDocumentFields | None,
         user_fields: VespaDocumentUserFields | None,
     ) -> None:
+        """
+        NOTE: Remember to handle the secondary index here. There is no separate
+        pipeline for updating chunks in the secondary index. This design is not
+        ideal and we should reconsider this when revamping index swapping.
+        """
         if fields is None and user_fields is None:
             logger.warning(
                 f"Tried to update document {doc_id} with no updated fields or user fields."
@@ -392,6 +445,11 @@ def update_single(
 
         try:
             self._real_index.update([update_request])
+            if self.secondary_index_name:
+                assert (
+                    self._secondary_real_index is not None
+                ), "Bug: Secondary index is not initialized."
+                self._secondary_real_index.update([update_request])
         except NotFoundError:
             logger.exception(
                 f"Tried to update document {doc_id} but at least one of its chunks was not found in OpenSearch. "
diff --git a/backend/onyx/document_index/vespa/index.py b/backend/onyx/document_index/vespa/index.py
index da029f47cae..5e2d8d2732b 100644
--- a/backend/onyx/document_index/vespa/index.py
+++ b/backend/onyx/document_index/vespa/index.py
@@ -465,6 +465,12 @@ def index(
         chunks: list[DocMetadataAwareIndexChunk],
         index_batch_params: IndexBatchParams,
     ) -> set[OldDocumentInsertionRecord]:
+        """
+        NOTE: Do NOT consider the secondary index here. A separate indexing
+        pipeline will be responsible for indexing to the secondary index. This
+        design is not ideal and we should reconsider this when revamping index
+        swapping.
+        """
         if len(index_batch_params.doc_id_to_previous_chunk_cnt) != len(
             index_batch_params.doc_id_to_new_chunk_cnt
         ):
@@ -659,6 +665,10 @@ def update_single(
         """Note: if the document id does not exist, the update will be a no-op and the
         function will complete with no errors or exceptions.
         Handle other exceptions if you wish to implement retry behavior
+
+        NOTE: Remember to handle the secondary index here. There is no separate
+        pipeline for updating chunks in the secondary index. This design is not
+        ideal and we should reconsider this when revamping index swapping.
         """
         if fields is None and user_fields is None:
             logger.warning(
@@ -679,13 +689,6 @@ def update_single(
                 f"Bug: Tenant ID mismatch. Expected {tenant_state.tenant_id}, got {tenant_id}."
             )
 
-        vespa_document_index = VespaDocumentIndex(
-            index_name=self.index_name,
-            tenant_state=tenant_state,
-            large_chunks_enabled=self.large_chunks_enabled,
-            httpx_client=self.httpx_client,
-        )
-
         project_ids: set[int] | None = None
         if user_fields is not None and user_fields.user_projects is not None:
             project_ids = set(user_fields.user_projects)
@@ -705,7 +708,20 @@ def update_single(
             persona_ids=persona_ids,
         )
 
-        vespa_document_index.update([update_request])
+        indices = [self.index_name]
+        if self.secondary_index_name:
+            indices.append(self.secondary_index_name)
+
+        for index_name in indices:
+            vespa_document_index = VespaDocumentIndex(
+                index_name=index_name,
+                tenant_state=tenant_state,
+                large_chunks_enabled=self.index_to_large_chunks_enabled.get(
+                    index_name, False
+                ),
+                httpx_client=self.httpx_client,
+            )
+            vespa_document_index.update([update_request])
 
     def delete_single(
         self,
@@ -714,6 +730,11 @@ def delete_single(
         tenant_id: str,
         chunk_count: int | None,
     ) -> int:
+        """
+        NOTE: Remember to handle the secondary index here. There is no separate
+        pipeline for deleting chunks in the secondary index. This design is not
+        ideal and we should reconsider this when revamping index swapping.
+        """
         tenant_state = TenantState(
             tenant_id=get_current_tenant_id(),
             multitenant=MULTI_TENANT,
@@ -726,13 +747,25 @@ def delete_single(
             raise ValueError(
                 f"Bug: Tenant ID mismatch. Expected {tenant_state.tenant_id}, got {tenant_id}."
             )
-        vespa_document_index = VespaDocumentIndex(
-            index_name=self.index_name,
-            tenant_state=tenant_state,
-            large_chunks_enabled=self.large_chunks_enabled,
-            httpx_client=self.httpx_client,
-        )
-        return vespa_document_index.delete(document_id=doc_id, chunk_count=chunk_count)
+        indices = [self.index_name]
+        if self.secondary_index_name:
+            indices.append(self.secondary_index_name)
+
+        total_chunks_deleted = 0
+        for index_name in indices:
+            vespa_document_index = VespaDocumentIndex(
+                index_name=index_name,
+                tenant_state=tenant_state,
+                large_chunks_enabled=self.index_to_large_chunks_enabled.get(
+                    index_name, False
+                ),
+                httpx_client=self.httpx_client,
+            )
+            total_chunks_deleted += vespa_document_index.delete(
+                document_id=doc_id, chunk_count=chunk_count
+            )
+
+        return total_chunks_deleted
 
     def id_based_retrieval(
         self,
diff --git a/backend/onyx/server/manage/search_settings.py b/backend/onyx/server/manage/search_settings.py
index 7f3181f5021..a7cf129195d 100644
--- a/backend/onyx/server/manage/search_settings.py
+++ b/backend/onyx/server/manage/search_settings.py
@@ -6,8 +6,11 @@
 
 from onyx.auth.users import current_admin_user
 from onyx.auth.users import current_user
+from onyx.configs.app_configs import DISABLE_INDEX_UPDATE_ON_SWAP
 from onyx.context.search.models import SavedSearchSettings
 from onyx.context.search.models import SearchSettingsCreationRequest
+from onyx.db.connector_credential_pair import get_connector_credential_pairs
+from onyx.db.connector_credential_pair import resync_cc_pair
 from onyx.db.engine.sql_engine import get_session
 from onyx.db.index_attempt import expire_index_attempts
 from onyx.db.llm import fetch_existing_llm_provider
@@ -15,20 +18,25 @@
 from onyx.db.llm import update_no_default_contextual_rag_provider
 from onyx.db.models import IndexModelStatus
 from onyx.db.models import User
+from onyx.db.search_settings import create_search_settings
 from onyx.db.search_settings import delete_search_settings
 from onyx.db.search_settings import get_current_search_settings
+from onyx.db.search_settings import get_embedding_provider_from_provider_type
 from onyx.db.search_settings import get_secondary_search_settings
 from onyx.db.search_settings import update_current_search_settings
 from onyx.db.search_settings import update_search_settings_status
+from onyx.document_index.factory import get_all_document_indices
 from onyx.document_index.factory import get_default_document_index
 from onyx.file_processing.unstructured import delete_unstructured_api_key
 from onyx.file_processing.unstructured import get_unstructured_api_key
 from onyx.file_processing.unstructured import update_unstructured_api_key
+from onyx.natural_language_processing.search_nlp_models import clean_model_name
 from onyx.server.manage.embedding.models import SearchSettingsDeleteRequest
 from onyx.server.manage.models import FullModelVersionResponse
 from onyx.server.models import IdReturn
 from onyx.server.utils_vector_db import require_vector_db
 from onyx.utils.logger import setup_logger
+from shared_configs.configs import ALT_INDEX_SUFFIX
 from shared_configs.configs import MULTI_TENANT
 
 router = APIRouter(prefix="/search-settings")
@@ -41,110 +49,99 @@ def set_new_search_settings(
     _: User = Depends(current_admin_user),
     db_session: Session = Depends(get_session),  # noqa: ARG001
 ) -> IdReturn:
-    """Creates a new EmbeddingModel row and cancels the previous secondary indexing if any
-    Gives an error if the same model name is used as the current or secondary index
     """
-    # TODO(andrei): Re-enable.
-    # NOTE Enable integration external dependency tests in test_search_settings.py
-    # when this is reenabled. They are currently skipped
-    logger.error("Setting new search settings is temporarily disabled.")
-    raise HTTPException(
-        status_code=status.HTTP_501_NOT_IMPLEMENTED,
-        detail="Setting new search settings is temporarily disabled.",
+    Creates a new SearchSettings row and cancels the previous secondary indexing
+    if any exists.
+    """
+    if search_settings_new.index_name:
+        logger.warning("Index name was specified by request, this is not suggested")
+
+    # Disallow contextual RAG for cloud deployments.
+    if MULTI_TENANT and search_settings_new.enable_contextual_rag:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Contextual RAG disabled in Onyx Cloud",
+        )
+
+    # Validate cloud provider exists or create new LiteLLM provider.
+    if search_settings_new.provider_type is not None:
+        cloud_provider = get_embedding_provider_from_provider_type(
+            db_session, provider_type=search_settings_new.provider_type
+        )
+
+        if cloud_provider is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"No embedding provider exists for cloud embedding type {search_settings_new.provider_type}",
+            )
+
+    validate_contextual_rag_model(
+        provider_name=search_settings_new.contextual_rag_llm_provider,
+        model_name=search_settings_new.contextual_rag_llm_name,
+        db_session=db_session,
     )
-    # if search_settings_new.index_name:
-    #     logger.warning("Index name was specified by request, this is not suggested")
-
-    # # Disallow contextual RAG for cloud deployments
-    # if MULTI_TENANT and search_settings_new.enable_contextual_rag:
-    #     raise HTTPException(
-    #         status_code=status.HTTP_400_BAD_REQUEST,
-    #         detail="Contextual RAG disabled in Onyx Cloud",
-    #     )
-
-    # # Validate cloud provider exists or create new LiteLLM provider
-    # if search_settings_new.provider_type is not None:
-    #     cloud_provider = get_embedding_provider_from_provider_type(
-    #         db_session, provider_type=search_settings_new.provider_type
-    #     )
-
-    #     if cloud_provider is None:
-    #         raise HTTPException(
-    #             status_code=status.HTTP_400_BAD_REQUEST,
-    #             detail=f"No embedding provider exists for cloud embedding type {search_settings_new.provider_type}",
-    #         )
-
-    # validate_contextual_rag_model(
-    #     provider_name=search_settings_new.contextual_rag_llm_provider,
-    #     model_name=search_settings_new.contextual_rag_llm_name,
-    #     db_session=db_session,
-    # )
-
-    # search_settings = get_current_search_settings(db_session)
-
-    # if search_settings_new.index_name is None:
-    #     # We define index name here
-    #     index_name = f"danswer_chunk_{clean_model_name(search_settings_new.model_name)}"
-    #     if (
-    #         search_settings_new.model_name == search_settings.model_name
-    #         and not search_settings.index_name.endswith(ALT_INDEX_SUFFIX)
-    #     ):
-    #         index_name += ALT_INDEX_SUFFIX
-    #     search_values = search_settings_new.model_dump()
-    #     search_values["index_name"] = index_name
-    #     new_search_settings_request = SavedSearchSettings(**search_values)
-    # else:
-    #     new_search_settings_request = SavedSearchSettings(
-    #         **search_settings_new.model_dump()
-    #     )
-
-    # secondary_search_settings = get_secondary_search_settings(db_session)
-
-    # if secondary_search_settings:
-    #     # Cancel any background indexing jobs
-    #     expire_index_attempts(
-    #         search_settings_id=secondary_search_settings.id, db_session=db_session
-    #     )
-
-    #     # Mark previous model as a past model directly
-    #     update_search_settings_status(
-    #         search_settings=secondary_search_settings,
-    #         new_status=IndexModelStatus.PAST,
-    #         db_session=db_session,
-    #     )
-
-    # new_search_settings = create_search_settings(
-    #     search_settings=new_search_settings_request, db_session=db_session
-    # )
-
-    # # Ensure Vespa has the new index immediately
-    # get_multipass_config(search_settings)
-    # get_multipass_config(new_search_settings)
-    # document_index = get_default_document_index(
-    #     search_settings, new_search_settings, db_session
-    # )
-
-    # document_index.ensure_indices_exist(
-    #     primary_embedding_dim=search_settings.final_embedding_dim,
-    #     primary_embedding_precision=search_settings.embedding_precision,
-    #     secondary_index_embedding_dim=new_search_settings.final_embedding_dim,
-    #     secondary_index_embedding_precision=new_search_settings.embedding_precision,
-    # )
-
-    # # Pause index attempts for the currently in use index to preserve resources
-    # if DISABLE_INDEX_UPDATE_ON_SWAP:
-    #     expire_index_attempts(
-    #         search_settings_id=search_settings.id, db_session=db_session
-    #     )
-    #     for cc_pair in get_connector_credential_pairs(db_session):
-    #         resync_cc_pair(
-    #             cc_pair=cc_pair,
-    #             search_settings_id=new_search_settings.id,
-    #             db_session=db_session,
-    #         )
-
-    # db_session.commit()
-    # return IdReturn(id=new_search_settings.id)
+
+    search_settings = get_current_search_settings(db_session)
+
+    if search_settings_new.index_name is None:
+        # We define index name here.
+        index_name = f"danswer_chunk_{clean_model_name(search_settings_new.model_name)}"
+        if (
+            search_settings_new.model_name == search_settings.model_name
+            and not search_settings.index_name.endswith(ALT_INDEX_SUFFIX)
+        ):
+            index_name += ALT_INDEX_SUFFIX
+        search_values = search_settings_new.model_dump()
+        search_values["index_name"] = index_name
+        new_search_settings_request = SavedSearchSettings(**search_values)
+    else:
+        new_search_settings_request = SavedSearchSettings(
+            **search_settings_new.model_dump()
+        )
+
+    secondary_search_settings = get_secondary_search_settings(db_session)
+
+    if secondary_search_settings:
+        # Cancel any background indexing jobs.
+        expire_index_attempts(
+            search_settings_id=secondary_search_settings.id, db_session=db_session
+        )
+
+        # Mark previous model as a past model directly.
+        update_search_settings_status(
+            search_settings=secondary_search_settings,
+            new_status=IndexModelStatus.PAST,
+            db_session=db_session,
+        )
+
+    new_search_settings = create_search_settings(
+        search_settings=new_search_settings_request, db_session=db_session
+    )
+
+    # Ensure the document indices have the new index immediately.
+    document_indices = get_all_document_indices(search_settings, new_search_settings)
+    for document_index in document_indices:
+        document_index.ensure_indices_exist(
+            primary_embedding_dim=search_settings.final_embedding_dim,
+            primary_embedding_precision=search_settings.embedding_precision,
+            secondary_index_embedding_dim=new_search_settings.final_embedding_dim,
+            secondary_index_embedding_precision=new_search_settings.embedding_precision,
+        )
+
+    # Pause index attempts for the currently in-use index to preserve resources.
+    if DISABLE_INDEX_UPDATE_ON_SWAP:
+        expire_index_attempts(
+            search_settings_id=search_settings.id, db_session=db_session
+        )
+        for cc_pair in get_connector_credential_pairs(db_session):
+            resync_cc_pair(
+                cc_pair=cc_pair,
+                search_settings_id=new_search_settings.id,
+                db_session=db_session,
+            )
+
+    db_session.commit()
+    return IdReturn(id=new_search_settings.id)
 
 
 @router.post("/cancel-new-embedding", dependencies=[Depends(require_vector_db)])
diff --git a/backend/tests/external_dependency_unit/search_settings/test_search_settings.py b/backend/tests/external_dependency_unit/search_settings/test_search_settings.py
index 94d7e139186..6236706e8ca 100644
--- a/backend/tests/external_dependency_unit/search_settings/test_search_settings.py
+++ b/backend/tests/external_dependency_unit/search_settings/test_search_settings.py
@@ -11,6 +11,7 @@
 from onyx.context.search.models import SearchSettingsCreationRequest
 from onyx.db.enums import EmbeddingPrecision
 from onyx.db.llm import fetch_default_contextual_rag_model
+from onyx.db.llm import fetch_existing_llm_provider
 from onyx.db.llm import update_default_contextual_model
 from onyx.db.llm import upsert_llm_provider
 from onyx.db.models import IndexModelStatus
@@ -37,6 +38,8 @@ def _create_llm_provider_and_model(
     model_name: str,
 ) -> None:
     """Insert an LLM provider with a single visible model configuration."""
+    if fetch_existing_llm_provider(name=provider_name, db_session=db_session):
+        return
     upsert_llm_provider(
         LLMProviderUpsertRequest(
             name=provider_name,
@@ -146,8 +149,8 @@ def baseline_search_settings(
     )
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
 @patch("onyx.db.swap_index.get_all_document_indices")
+@patch("onyx.server.manage.search_settings.get_all_document_indices")
 @patch("onyx.server.manage.search_settings.get_default_document_index")
 @patch("onyx.indexing.indexing_pipeline.get_llm_for_contextual_rag")
 @patch("onyx.indexing.indexing_pipeline.index_doc_batch_with_handler")
@@ -155,6 +158,7 @@ def test_indexing_pipeline_uses_contextual_rag_settings_from_create(
     mock_index_handler: MagicMock,
     mock_get_llm: MagicMock,
     mock_get_doc_index: MagicMock,  # noqa: ARG001
+    mock_get_all_doc_indices_search_settings: MagicMock,  # noqa: ARG001
     mock_get_all_doc_indices: MagicMock,
     baseline_search_settings: None,  # noqa: ARG001
     db_session: Session,
@@ -196,8 +200,8 @@ def test_indexing_pipeline_uses_contextual_rag_settings_from_create(
     )
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
 @patch("onyx.db.swap_index.get_all_document_indices")
+@patch("onyx.server.manage.search_settings.get_all_document_indices")
 @patch("onyx.server.manage.search_settings.get_default_document_index")
 @patch("onyx.indexing.indexing_pipeline.get_llm_for_contextual_rag")
 @patch("onyx.indexing.indexing_pipeline.index_doc_batch_with_handler")
@@ -205,6 +209,7 @@ def test_indexing_pipeline_uses_updated_contextual_rag_settings(
     mock_index_handler: MagicMock,
     mock_get_llm: MagicMock,
     mock_get_doc_index: MagicMock,  # noqa: ARG001
+    mock_get_all_doc_indices_search_settings: MagicMock,  # noqa: ARG001
     mock_get_all_doc_indices: MagicMock,
     baseline_search_settings: None,  # noqa: ARG001
     db_session: Session,
@@ -266,7 +271,7 @@ def test_indexing_pipeline_uses_updated_contextual_rag_settings(
     )
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
+@patch("onyx.server.manage.search_settings.get_all_document_indices")
 @patch("onyx.server.manage.search_settings.get_default_document_index")
 @patch("onyx.indexing.indexing_pipeline.get_llm_for_contextual_rag")
 @patch("onyx.indexing.indexing_pipeline.index_doc_batch_with_handler")
@@ -274,6 +279,7 @@ def test_indexing_pipeline_skips_llm_when_contextual_rag_disabled(
     mock_index_handler: MagicMock,
     mock_get_llm: MagicMock,
     mock_get_doc_index: MagicMock,  # noqa: ARG001
+    mock_get_all_doc_indices_search_settings: MagicMock,  # noqa: ARG001
     baseline_search_settings: None,  # noqa: ARG001
     db_session: Session,
 ) -> None:
diff --git a/backend/tests/integration/tests/search_settings/test_search_settings.py b/backend/tests/integration/tests/search_settings/test_search_settings.py
index 02b7b1e768f..b6debb519ad 100644
--- a/backend/tests/integration/tests/search_settings/test_search_settings.py
+++ b/backend/tests/integration/tests/search_settings/test_search_settings.py
@@ -1,4 +1,3 @@
-import pytest
 import requests
 
 from tests.integration.common_utils.constants import API_SERVER_URL
@@ -365,7 +364,6 @@ def test_update_contextual_rag_missing_model_name(
     assert "Provider name and model name are required" in response.json()["detail"]
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
 def test_set_new_search_settings_with_contextual_rag(
     reset: None,  # noqa: ARG001
     admin_user: DATestUser,
@@ -394,7 +392,6 @@ def test_set_new_search_settings_with_contextual_rag(
     _cancel_new_embedding(admin_user)
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
 def test_set_new_search_settings_without_contextual_rag(
     reset: None,  # noqa: ARG001
     admin_user: DATestUser,
@@ -419,7 +416,6 @@ def test_set_new_search_settings_without_contextual_rag(
     _cancel_new_embedding(admin_user)
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
 def test_set_new_then_update_inference_settings(
     reset: None,  # noqa: ARG001
     admin_user: DATestUser,
@@ -457,7 +453,6 @@ def test_set_new_then_update_inference_settings(
     _cancel_new_embedding(admin_user)
 
 
-@pytest.mark.skip(reason="Set new search settings is temporarily disabled.")
 def test_set_new_search_settings_replaces_previous_secondary(
     reset: None,  # noqa: ARG001
     admin_user: DATestUser,

From eb3e15c1953fabc87ac8ef9532731e644f780aea Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Thu, 5 Mar 2026 07:13:37 +0530
Subject: [PATCH 094/267] feat(table): add ColumnVisibilityPopover, Footer,
 Pagination, and SortingPopover components (#9019)

Co-authored-by: Nik <nikolas.garza5@gmail.com>
---
 .../app/admin/demo/table-qualifier/page.tsx   | 190 +++++++++
 .../table/ColumnVisibilityPopover.tsx         | 106 +++++
 web/src/refresh-components/table/Footer.tsx   | 260 ++++++++++++
 .../refresh-components/table/Pagination.tsx   | 393 ++++++++++++++++++
 .../table/SortingPopover.tsx                  | 181 ++++++++
 5 files changed, 1130 insertions(+)
 create mode 100644 web/src/app/admin/demo/table-qualifier/page.tsx
 create mode 100644 web/src/refresh-components/table/ColumnVisibilityPopover.tsx
 create mode 100644 web/src/refresh-components/table/Footer.tsx
 create mode 100644 web/src/refresh-components/table/Pagination.tsx
 create mode 100644 web/src/refresh-components/table/SortingPopover.tsx

diff --git a/web/src/app/admin/demo/table-qualifier/page.tsx b/web/src/app/admin/demo/table-qualifier/page.tsx
new file mode 100644
index 00000000000..8649365cafc
--- /dev/null
+++ b/web/src/app/admin/demo/table-qualifier/page.tsx
@@ -0,0 +1,190 @@
+"use client";
+
+import { useState } from "react";
+import Text from "@/refresh-components/texts/Text";
+import TableQualifier from "@/refresh-components/table/TableQualifier";
+import { TableSizeProvider } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import type { QualifierContentType } from "@/refresh-components/table/types";
+import { SvgCheckCircle } from "@opal/icons";
+
+// ---------------------------------------------------------------------------
+// Content type configurations
+// ---------------------------------------------------------------------------
+
+interface ContentConfig {
+  label: string;
+  content: QualifierContentType;
+  extraProps: Record<string, unknown>;
+}
+
+const CONTENT_TYPES: ContentConfig[] = [
+  {
+    label: "Simple",
+    content: "simple",
+    extraProps: {},
+  },
+  {
+    label: "Icon",
+    content: "icon",
+    extraProps: { icon: SvgCheckCircle },
+  },
+  {
+    label: "Image",
+    content: "image",
+    extraProps: {
+      imageSrc: "https://picsum.photos/36",
+      imageAlt: "Placeholder",
+    },
+  },
+  {
+    label: "Avatar Icon",
+    content: "avatar-icon",
+    extraProps: {},
+  },
+  {
+    label: "Avatar User",
+    content: "avatar-user",
+    extraProps: { initials: "AJ" },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Row of qualifier states for a single content type
+// ---------------------------------------------------------------------------
+
+interface QualifierRowProps {
+  config: ContentConfig;
+}
+
+function QualifierRow({ config }: QualifierRowProps) {
+  const [selectableSelected, setSelectableSelected] = useState(false);
+  const [permanentSelected, setPermanentSelected] = useState(true);
+
+  return (
+    <div className="space-y-2">
+      <Text mainUiAction text02>
+        {config.label}
+      </Text>
+
+      <div className="flex items-start gap-8">
+        {/* Default */}
+        <div className="flex w-20 flex-col items-center gap-2">
+          <TableQualifier
+            content={config.content}
+            selectable={false}
+            selected={false}
+            disabled={false}
+            {...config.extraProps}
+          />
+          <Text secondaryBody text04>
+            Default
+          </Text>
+        </div>
+
+        {/* Selectable (hover to reveal checkbox) */}
+        <div className="flex w-20 flex-col items-center gap-2">
+          <TableQualifier
+            content={config.content}
+            selectable={true}
+            selected={selectableSelected}
+            disabled={false}
+            onSelectChange={setSelectableSelected}
+            {...config.extraProps}
+          />
+          <Text secondaryBody text04>
+            Selectable
+          </Text>
+        </div>
+
+        {/* Selected */}
+        <div className="flex w-20 flex-col items-center gap-2">
+          <TableQualifier
+            content={config.content}
+            selectable={true}
+            selected={permanentSelected}
+            disabled={false}
+            onSelectChange={setPermanentSelected}
+            {...config.extraProps}
+          />
+          <Text secondaryBody text04>
+            Selected
+          </Text>
+        </div>
+
+        {/* Disabled (unselected) */}
+        <div className="flex w-20 flex-col items-center gap-2">
+          <TableQualifier
+            content={config.content}
+            selectable={true}
+            selected={false}
+            disabled={true}
+            {...config.extraProps}
+          />
+          <Text secondaryBody text04>
+            Disabled
+          </Text>
+        </div>
+
+        {/* Disabled (selected) */}
+        <div className="flex w-20 flex-col items-center gap-2">
+          <TableQualifier
+            content={config.content}
+            selectable={true}
+            selected={true}
+            disabled={true}
+            {...config.extraProps}
+          />
+          <Text secondaryBody text04>
+            Disabled+Sel
+          </Text>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Size section — all content types at a given size
+// ---------------------------------------------------------------------------
+
+interface SizeSectionProps {
+  size: TableSize;
+  title: string;
+}
+
+function SizeSection({ size, title }: SizeSectionProps) {
+  return (
+    <div className="space-y-6">
+      <Text headingH3>{title}</Text>
+      <TableSizeProvider size={size}>
+        <div className="flex flex-col gap-8">
+          {CONTENT_TYPES.map((config) => (
+            <QualifierRow key={`${size}-${config.content}`} config={config} />
+          ))}
+        </div>
+      </TableSizeProvider>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
+export default function TableQualifierDemoPage() {
+  return (
+    <div className="p-6 space-y-10">
+      <div className="space-y-4">
+        <Text headingH2>TableQualifier Demo</Text>
+        <Text mainContentMuted text03>
+          All content types, sizes, and interactive states. Hover selectable
+          variants to reveal the checkbox; click to toggle.
+        </Text>
+      </div>
+
+      <SizeSection size="regular" title="Regular (36px)" />
+      <SizeSection size="small" title="Small (28px)" />
+    </div>
+  );
+}
diff --git a/web/src/refresh-components/table/ColumnVisibilityPopover.tsx b/web/src/refresh-components/table/ColumnVisibilityPopover.tsx
new file mode 100644
index 00000000000..2436d1947d1
--- /dev/null
+++ b/web/src/refresh-components/table/ColumnVisibilityPopover.tsx
@@ -0,0 +1,106 @@
+"use client";
+
+import { useState } from "react";
+import {
+  type Table,
+  type ColumnDef,
+  type RowData,
+  type VisibilityState,
+} from "@tanstack/react-table";
+import { Button } from "@opal/components";
+import { SvgColumn, SvgCheck } from "@opal/icons";
+import Popover from "@/refresh-components/Popover";
+import LineItem from "@/refresh-components/buttons/LineItem";
+import Divider from "@/refresh-components/Divider";
+
+// ---------------------------------------------------------------------------
+// Popover UI
+// ---------------------------------------------------------------------------
+
+interface ColumnVisibilityPopoverProps<TData extends RowData = RowData> {
+  table: Table<TData>;
+  columnVisibility: VisibilityState;
+  size?: "regular" | "small";
+}
+
+function ColumnVisibilityPopover<TData extends RowData>({
+  table,
+  columnVisibility,
+  size = "regular",
+}: ColumnVisibilityPopoverProps<TData>) {
+  const [open, setOpen] = useState(false);
+  const hideableColumns = table
+    .getAllLeafColumns()
+    .filter((col) => col.getCanHide());
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button
+          icon={SvgColumn}
+          transient={open}
+          size={size === "small" ? "sm" : "md"}
+          prominence="internal"
+          tooltip="Columns"
+        />
+      </Popover.Trigger>
+
+      <Popover.Content width="lg" align="end" side="bottom">
+        <Divider showTitle text="Shown Columns" />
+        <Popover.Menu>
+          {hideableColumns.map((column) => {
+            const isVisible = columnVisibility[column.id] !== false;
+            const label =
+              typeof column.columnDef.header === "string"
+                ? column.columnDef.header
+                : column.id;
+
+            return (
+              <LineItem
+                key={column.id}
+                selected={isVisible}
+                emphasized
+                rightChildren={isVisible ? <SvgCheck size={16} /> : undefined}
+                onClick={() => {
+                  column.toggleVisibility();
+                }}
+              >
+                {label}
+              </LineItem>
+            );
+          })}
+        </Popover.Menu>
+      </Popover.Content>
+    </Popover>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Column definition factory
+// ---------------------------------------------------------------------------
+
+interface CreateColumnVisibilityColumnOptions {
+  size?: "regular" | "small";
+}
+
+function createColumnVisibilityColumn<TData>(
+  options?: CreateColumnVisibilityColumnOptions
+): ColumnDef<TData, unknown> {
+  return {
+    id: "__columnVisibility",
+    size: 44,
+    enableHiding: false,
+    enableSorting: false,
+    enableResizing: false,
+    header: ({ table }) => (
+      <ColumnVisibilityPopover
+        table={table}
+        columnVisibility={table.getState().columnVisibility}
+        size={options?.size}
+      />
+    ),
+    cell: () => null,
+  };
+}
+
+export { ColumnVisibilityPopover, createColumnVisibilityColumn };
diff --git a/web/src/refresh-components/table/Footer.tsx b/web/src/refresh-components/table/Footer.tsx
new file mode 100644
index 00000000000..9f292757922
--- /dev/null
+++ b/web/src/refresh-components/table/Footer.tsx
@@ -0,0 +1,260 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import { Button } from "@opal/components";
+import Text from "@/refresh-components/texts/Text";
+import Pagination from "@/refresh-components/table/Pagination";
+import { useTableSize } from "@/refresh-components/table/TableSizeContext";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+import { SvgEye, SvgXCircle } from "@opal/icons";
+
+type SelectionState = "none" | "partial" | "all";
+
+/**
+ * Footer mode for tables with selectable rows.
+ * Displays a selection message on the left (with optional view/clear actions)
+ * and a `count`-type pagination on the right.
+ */
+interface FooterSelectionModeProps {
+  mode: "selection";
+  /** Whether the table supports selecting multiple rows. */
+  multiSelect: boolean;
+  /** Current selection state: `"none"`, `"partial"`, or `"all"`. */
+  selectionState: SelectionState;
+  /** Number of currently selected items. */
+  selectedCount: number;
+  /** If provided, renders a "View" icon button when items are selected. */
+  onView?: () => void;
+  /** If provided, renders a "Clear" icon button when items are selected. */
+  onClear?: () => void;
+  /** Number of items displayed per page. */
+  pageSize: number;
+  /** Total number of items across all pages. */
+  totalItems: number;
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** Controls overall footer sizing. `"regular"` (default) or `"small"`. */
+  size?: TableSize;
+  className?: string;
+}
+
+/**
+ * Footer mode for read-only tables (no row selection).
+ * Displays "Showing X~Y of Z" on the left and a `list`-type pagination
+ * on the right.
+ */
+interface FooterSummaryModeProps {
+  mode: "summary";
+  /** First item number in the current page (e.g. `1`). */
+  rangeStart: number;
+  /** Last item number in the current page (e.g. `25`). */
+  rangeEnd: number;
+  /** Total number of items across all pages. */
+  totalItems: number;
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** Controls overall footer sizing. `"regular"` (default) or `"small"`. */
+  size?: TableSize;
+  className?: string;
+}
+
+/**
+ * Discriminated union of footer modes.
+ * Use `mode: "selection"` for tables with selectable rows, or
+ * `mode: "summary"` for read-only tables.
+ */
+export type FooterProps = FooterSelectionModeProps | FooterSummaryModeProps;
+
+function getSelectionMessage(
+  state: SelectionState,
+  multi: boolean,
+  count: number
+): string {
+  if (state === "none") {
+    return multi ? "Select items to continue" : "Select an item to continue";
+  }
+  if (!multi) return "Item selected";
+  return `${count} item${count !== 1 ? "s" : ""} selected`;
+}
+
+/**
+ * Table footer combining status information on the left with pagination on the
+ * right. Use `mode: "selection"` for tables with selectable rows, or
+ * `mode: "summary"` for read-only tables.
+ */
+export default function Footer(props: FooterProps) {
+  const contextSize = useTableSize();
+  const resolvedSize = props.size ?? contextSize;
+  const isSmall = resolvedSize === "small";
+  return (
+    <div
+      className={cn(
+        "table-footer",
+        "flex w-full items-center justify-between border-t border-border-01",
+        props.className
+      )}
+      data-size={resolvedSize}
+    >
+      {/* Left side */}
+      <div className="flex items-center gap-1 px-1">
+        {props.mode === "selection" ? (
+          <SelectionLeft
+            selectionState={props.selectionState}
+            multiSelect={props.multiSelect}
+            selectedCount={props.selectedCount}
+            onView={props.onView}
+            onClear={props.onClear}
+            isSmall={isSmall}
+          />
+        ) : (
+          <SummaryLeft
+            rangeStart={props.rangeStart}
+            rangeEnd={props.rangeEnd}
+            totalItems={props.totalItems}
+            isSmall={isSmall}
+          />
+        )}
+      </div>
+
+      {/* Right side */}
+      <div className="flex items-center gap-2 px-1 py-2">
+        {props.mode === "selection" ? (
+          <Pagination
+            type="count"
+            pageSize={props.pageSize}
+            totalItems={props.totalItems}
+            currentPage={props.currentPage}
+            totalPages={props.totalPages}
+            onPageChange={props.onPageChange}
+            showUnits
+            size={isSmall ? "sm" : "md"}
+          />
+        ) : (
+          <Pagination
+            type="list"
+            currentPage={props.currentPage}
+            totalPages={props.totalPages}
+            onPageChange={props.onPageChange}
+            size={isSmall ? "md" : "lg"}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface SelectionLeftProps {
+  selectionState: SelectionState;
+  multiSelect: boolean;
+  selectedCount: number;
+  onView?: () => void;
+  onClear?: () => void;
+  isSmall: boolean;
+}
+
+function SelectionLeft({
+  selectionState,
+  multiSelect,
+  selectedCount,
+  onView,
+  onClear,
+  isSmall,
+}: SelectionLeftProps) {
+  const message = getSelectionMessage(
+    selectionState,
+    multiSelect,
+    selectedCount
+  );
+  const hasSelection = selectionState !== "none";
+
+  return (
+    <div className="flex flex-row gap-1 items-center justify-center w-fit flex-shrink-0 h-fit px-1">
+      {isSmall ? (
+        <Text
+          secondaryAction={hasSelection}
+          secondaryBody={!hasSelection}
+          text03
+        >
+          {message}
+        </Text>
+      ) : (
+        <Text mainUiBody={hasSelection} mainUiMuted={!hasSelection} text03>
+          {message}
+        </Text>
+      )}
+
+      {hasSelection && (
+        <div className="flex flex-row items-center w-fit flex-shrink-0 h-fit">
+          {onView && (
+            <Button
+              icon={SvgEye}
+              onClick={onView}
+              tooltip="View"
+              size={isSmall ? "sm" : "md"}
+              prominence="tertiary"
+            />
+          )}
+          {onClear && (
+            <Button
+              icon={SvgXCircle}
+              onClick={onClear}
+              tooltip="Clear selection"
+              size={isSmall ? "sm" : "md"}
+              prominence="tertiary"
+            />
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface SummaryLeftProps {
+  rangeStart: number;
+  rangeEnd: number;
+  totalItems: number;
+  isSmall: boolean;
+}
+
+function SummaryLeft({
+  rangeStart,
+  rangeEnd,
+  totalItems,
+  isSmall,
+}: SummaryLeftProps) {
+  return (
+    <div className="flex flex-row gap-1 items-center w-fit h-fit px-1">
+      {isSmall ? (
+        <Text secondaryBody text03>
+          Showing{" "}
+          <Text as="span" secondaryMono text03>
+            {rangeStart}~{rangeEnd}
+          </Text>{" "}
+          of{" "}
+          <Text as="span" secondaryMono text03>
+            {totalItems}
+          </Text>
+        </Text>
+      ) : (
+        <Text mainUiMuted text03>
+          Showing{" "}
+          <Text as="span" mainUiMono text03>
+            {rangeStart}~{rangeEnd}
+          </Text>{" "}
+          of{" "}
+          <Text as="span" mainUiMono text03>
+            {totalItems}
+          </Text>
+        </Text>
+      )}
+    </div>
+  );
+}
diff --git a/web/src/refresh-components/table/Pagination.tsx b/web/src/refresh-components/table/Pagination.tsx
new file mode 100644
index 00000000000..f1ec24289a3
--- /dev/null
+++ b/web/src/refresh-components/table/Pagination.tsx
@@ -0,0 +1,393 @@
+"use client";
+
+import { Button } from "@opal/components";
+import Text from "@/refresh-components/texts/Text";
+import { cn } from "@/lib/utils";
+import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
+
+type PaginationSize = "lg" | "md" | "sm";
+
+/**
+ * Minimal page navigation showing `currentPage / totalPages` with prev/next arrows.
+ * Use when you only need simple forward/backward navigation.
+ */
+interface SimplePaginationProps {
+  type: "simple";
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** When `true`, displays the word "pages" after the page indicator. */
+  showUnits?: boolean;
+  /** When `false`, hides the page indicator between the prev/next arrows. Defaults to `true`. */
+  showPageIndicator?: boolean;
+  /** Controls button and text sizing. Defaults to `"lg"`. */
+  size?: PaginationSize;
+  className?: string;
+}
+
+/**
+ * Item-count pagination showing `currentItems of totalItems` with optional page
+ * controls and a "Go to" button. Use inside table footers that need to communicate
+ * how many items the user is viewing.
+ */
+interface CountPaginationProps {
+  type: "count";
+  /** Number of items displayed per page. Used to compute the visible range. */
+  pageSize: number;
+  /** Total number of items across all pages. */
+  totalItems: number;
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** When `false`, hides the page number between the prev/next arrows (arrows still visible). Defaults to `true`. */
+  showPageIndicator?: boolean;
+  /** When `true`, renders a "Go to" button. Requires `onGoTo`. */
+  showGoTo?: boolean;
+  /** Callback invoked when the "Go to" button is clicked. */
+  onGoTo?: () => void;
+  /** When `true`, displays the word "items" after the total count. */
+  showUnits?: boolean;
+  /** Controls button and text sizing. Defaults to `"lg"`. */
+  size?: PaginationSize;
+  className?: string;
+}
+
+/**
+ * Numbered page-list pagination with clickable page buttons and ellipsis
+ * truncation for large page counts. Does not support `"sm"` size.
+ */
+interface ListPaginationProps {
+  type: "list";
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** When `false`, hides the page buttons between the prev/next arrows. Defaults to `true`. */
+  showPageIndicator?: boolean;
+  /** Controls button and text sizing. Defaults to `"lg"`. Only `"lg"` and `"md"` are supported. */
+  size?: Exclude<PaginationSize, "sm">;
+  className?: string;
+}
+
+/**
+ * Discriminated union of all pagination variants.
+ * Use the `type` prop to select between `"simple"`, `"count"`, and `"list"`.
+ */
+export type PaginationProps =
+  | SimplePaginationProps
+  | CountPaginationProps
+  | ListPaginationProps;
+
+function getPageNumbers(currentPage: number, totalPages: number) {
+  const pages: (number | string)[] = [];
+  const maxPagesToShow = 7;
+
+  if (totalPages <= maxPagesToShow) {
+    for (let i = 1; i <= totalPages; i++) {
+      pages.push(i);
+    }
+  } else {
+    pages.push(1);
+
+    let startPage = Math.max(2, currentPage - 1);
+    let endPage = Math.min(totalPages - 1, currentPage + 1);
+
+    if (currentPage <= 3) {
+      endPage = 5;
+    } else if (currentPage >= totalPages - 2) {
+      startPage = totalPages - 4;
+    }
+
+    if (startPage > 2) {
+      if (startPage === 3) {
+        pages.push(2);
+      } else {
+        pages.push("start-ellipsis");
+      }
+    }
+
+    for (let i = startPage; i <= endPage; i++) {
+      pages.push(i);
+    }
+
+    if (endPage < totalPages - 1) {
+      if (endPage === totalPages - 2) {
+        pages.push(totalPages - 1);
+      } else {
+        pages.push("end-ellipsis");
+      }
+    }
+
+    pages.push(totalPages);
+  }
+
+  return pages;
+}
+
+function sizedTextProps(isSmall: boolean, variant: "mono" | "muted") {
+  if (variant === "mono") {
+    return isSmall ? { secondaryMono: true } : { mainUiMono: true };
+  }
+  return isSmall ? { secondaryBody: true } : { mainUiMuted: true };
+}
+
+interface NavButtonsProps {
+  currentPage: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+  size: PaginationSize;
+  children?: React.ReactNode;
+}
+
+function NavButtons({
+  currentPage,
+  totalPages,
+  onPageChange,
+  size,
+  children,
+}: NavButtonsProps) {
+  return (
+    <>
+      <Button
+        icon={SvgChevronLeft}
+        onClick={() => onPageChange(currentPage - 1)}
+        disabled={currentPage <= 1}
+        size={size}
+        prominence="tertiary"
+        tooltip="Previous page"
+      />
+      {children}
+      <Button
+        icon={SvgChevronRight}
+        onClick={() => onPageChange(currentPage + 1)}
+        disabled={currentPage >= totalPages}
+        size={size}
+        prominence="tertiary"
+        tooltip="Next page"
+      />
+    </>
+  );
+}
+
+/**
+ * Table pagination component with three variants: `simple`, `count`, and `list`.
+ * Pass the `type` prop to select the variant, and the component will render the
+ * appropriate UI.
+ */
+export default function Pagination(props: PaginationProps) {
+  const normalized = { ...props, totalPages: Math.max(1, props.totalPages) };
+  switch (normalized.type) {
+    case "simple":
+      return <SimplePaginationInner {...normalized} />;
+    case "count":
+      return <CountPaginationInner {...normalized} />;
+    case "list":
+      return <ListPaginationInner {...normalized} />;
+  }
+}
+
+function SimplePaginationInner({
+  currentPage,
+  totalPages,
+  onPageChange,
+  showUnits,
+  showPageIndicator = true,
+  size = "lg",
+  className,
+}: SimplePaginationProps) {
+  const isSmall = size === "sm";
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      <NavButtons
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={onPageChange}
+        size={size}
+      >
+        {showPageIndicator && (
+          <>
+            <Text {...sizedTextProps(isSmall, "mono")} text03>
+              {currentPage}
+              <Text as="span" {...sizedTextProps(isSmall, "muted")} text03>
+                /
+              </Text>
+              {totalPages}
+            </Text>
+            {showUnits && (
+              <Text {...sizedTextProps(isSmall, "muted")} text03>
+                pages
+              </Text>
+            )}
+          </>
+        )}
+      </NavButtons>
+    </div>
+  );
+}
+
+function CountPaginationInner({
+  pageSize,
+  totalItems,
+  currentPage,
+  totalPages,
+  onPageChange,
+  showPageIndicator = true,
+  showGoTo,
+  onGoTo,
+  showUnits,
+  size = "lg",
+  className,
+}: CountPaginationProps) {
+  const isSmall = size === "sm";
+  const rangeStart = totalItems === 0 ? 0 : (currentPage - 1) * pageSize + 1;
+  const rangeEnd = Math.min(currentPage * pageSize, totalItems);
+  const currentItems = `${rangeStart}~${rangeEnd}`;
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      <Text {...sizedTextProps(isSmall, "mono")} text03>
+        {currentItems}
+      </Text>
+      <Text {...sizedTextProps(isSmall, "muted")} text03>
+        of
+      </Text>
+      <Text {...sizedTextProps(isSmall, "mono")} text03>
+        {totalItems}
+      </Text>
+      {showUnits && (
+        <Text {...sizedTextProps(isSmall, "muted")} text03>
+          items
+        </Text>
+      )}
+
+      <NavButtons
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={onPageChange}
+        size={size}
+      >
+        {showPageIndicator && (
+          <Text {...sizedTextProps(isSmall, "mono")} text03>
+            {currentPage}
+          </Text>
+        )}
+      </NavButtons>
+
+      {showGoTo && onGoTo && (
+        <Button onClick={onGoTo} size={size} prominence="tertiary">
+          Go to
+        </Button>
+      )}
+    </div>
+  );
+}
+
+interface PageNumberIconProps {
+  className?: string;
+  pageNum: number;
+  isActive: boolean;
+  isLarge: boolean;
+}
+
+function PageNumberIcon({
+  className: iconClassName,
+  pageNum,
+  isActive,
+  isLarge,
+}: PageNumberIconProps) {
+  return (
+    <div className={cn(iconClassName, "flex flex-col justify-center")}>
+      {isLarge ? (
+        <Text
+          mainUiBody={isActive}
+          mainUiMuted={!isActive}
+          text04={isActive}
+          text02={!isActive}
+        >
+          {pageNum}
+        </Text>
+      ) : (
+        <Text
+          secondaryAction={isActive}
+          secondaryBody={!isActive}
+          text04={isActive}
+          text02={!isActive}
+        >
+          {pageNum}
+        </Text>
+      )}
+    </div>
+  );
+}
+
+function ListPaginationInner({
+  currentPage,
+  totalPages,
+  onPageChange,
+  showPageIndicator = true,
+  size = "lg",
+  className,
+}: ListPaginationProps) {
+  const pageNumbers = getPageNumbers(currentPage, totalPages);
+  const isLarge = size === "lg";
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      <NavButtons
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={onPageChange}
+        size={size}
+      >
+        {showPageIndicator && (
+          <div className="flex items-center">
+            {pageNumbers.map((page) => {
+              if (typeof page === "string") {
+                return (
+                  <Text
+                    key={page}
+                    mainUiMuted={isLarge}
+                    secondaryBody={!isLarge}
+                    text03
+                  >
+                    ...
+                  </Text>
+                );
+              }
+
+              const pageNum = page as number;
+              const isActive = pageNum === currentPage;
+
+              return (
+                <Button
+                  key={pageNum}
+                  onClick={() => onPageChange(pageNum)}
+                  size={size}
+                  prominence="tertiary"
+                  transient={isActive}
+                  icon={({ className: iconClassName }) => (
+                    <PageNumberIcon
+                      className={iconClassName}
+                      pageNum={pageNum}
+                      isActive={isActive}
+                      isLarge={isLarge}
+                    />
+                  )}
+                />
+              );
+            })}
+          </div>
+        )}
+      </NavButtons>
+    </div>
+  );
+}
diff --git a/web/src/refresh-components/table/SortingPopover.tsx b/web/src/refresh-components/table/SortingPopover.tsx
new file mode 100644
index 00000000000..82d94da438c
--- /dev/null
+++ b/web/src/refresh-components/table/SortingPopover.tsx
@@ -0,0 +1,181 @@
+"use client";
+
+import { useState } from "react";
+import {
+  type Table,
+  type ColumnDef,
+  type RowData,
+  type SortingState,
+} from "@tanstack/react-table";
+import { Button } from "@opal/components";
+import { SvgArrowUpDown, SvgSortOrder, SvgCheck } from "@opal/icons";
+import Popover from "@/refresh-components/Popover";
+import Divider from "@/refresh-components/Divider";
+import LineItem from "@/refresh-components/buttons/LineItem";
+import Text from "@/refresh-components/texts/Text";
+
+// ---------------------------------------------------------------------------
+// Popover UI
+// ---------------------------------------------------------------------------
+
+interface SortingPopoverProps<TData extends RowData = RowData> {
+  table: Table<TData>;
+  sorting: SortingState;
+  size?: "regular" | "small";
+  footerText?: string;
+  ascendingLabel?: string;
+  descendingLabel?: string;
+}
+
+function SortingPopover<TData extends RowData>({
+  table,
+  sorting,
+  size = "regular",
+  footerText,
+  ascendingLabel = "Ascending",
+  descendingLabel = "Descending",
+}: SortingPopoverProps<TData>) {
+  const [open, setOpen] = useState(false);
+  const sortableColumns = table
+    .getAllLeafColumns()
+    .filter((col) => col.getCanSort());
+
+  const currentSort = sorting[0] ?? null;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button
+          icon={currentSort === null ? SvgArrowUpDown : SvgSortOrder}
+          transient={open}
+          size={size === "small" ? "sm" : "md"}
+          prominence="internal"
+          tooltip="Sort"
+        />
+      </Popover.Trigger>
+
+      <Popover.Content width="lg" align="end" side="bottom">
+        <Popover.Menu
+          footer={
+            footerText ? (
+              <div className="px-2 py-1">
+                <Text secondaryBody text03>
+                  {footerText}
+                </Text>
+              </div>
+            ) : undefined
+          }
+        >
+          <Divider showTitle text="Sort by" />
+
+          <LineItem
+            selected={currentSort === null}
+            emphasized
+            rightChildren={
+              currentSort === null ? <SvgCheck size={16} /> : undefined
+            }
+            onClick={() => {
+              table.resetSorting();
+            }}
+          >
+            Manual Ordering
+          </LineItem>
+
+          {sortableColumns.map((column) => {
+            const isSorted = currentSort?.id === column.id;
+            const label =
+              typeof column.columnDef.header === "string"
+                ? column.columnDef.header
+                : column.id;
+
+            return (
+              <LineItem
+                key={column.id}
+                selected={isSorted}
+                emphasized
+                rightChildren={isSorted ? <SvgCheck size={16} /> : undefined}
+                onClick={() => {
+                  if (isSorted) {
+                    table.resetSorting();
+                    return;
+                  }
+                  column.toggleSorting(false);
+                }}
+              >
+                {label}
+              </LineItem>
+            );
+          })}
+
+          {currentSort !== null && (
+            <>
+              <Divider showTitle text="Sorting Order" />
+
+              <LineItem
+                selected={!currentSort.desc}
+                emphasized
+                rightChildren={
+                  !currentSort.desc ? <SvgCheck size={16} /> : undefined
+                }
+                onClick={() => {
+                  table.setSorting([{ id: currentSort.id, desc: false }]);
+                }}
+              >
+                {ascendingLabel}
+              </LineItem>
+
+              <LineItem
+                selected={currentSort.desc}
+                emphasized
+                rightChildren={
+                  currentSort.desc ? <SvgCheck size={16} /> : undefined
+                }
+                onClick={() => {
+                  table.setSorting([{ id: currentSort.id, desc: true }]);
+                }}
+              >
+                {descendingLabel}
+              </LineItem>
+            </>
+          )}
+        </Popover.Menu>
+      </Popover.Content>
+    </Popover>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Column definition factory
+// ---------------------------------------------------------------------------
+
+interface CreateSortingColumnOptions {
+  size?: "regular" | "small";
+  footerText?: string;
+  ascendingLabel?: string;
+  descendingLabel?: string;
+}
+
+function createSortingColumn<TData>(
+  options?: CreateSortingColumnOptions
+): ColumnDef<TData, unknown> {
+  return {
+    id: "__sorting",
+    size: 44,
+    enableHiding: false,
+    enableSorting: false,
+    enableResizing: false,
+    header: ({ table }) => (
+      <SortingPopover
+        table={table}
+        sorting={table.getState().sorting}
+        size={options?.size}
+        footerText={options?.footerText}
+        ascendingLabel={options?.ascendingLabel}
+        descendingLabel={options?.descendingLabel}
+      />
+    ),
+    cell: () => null,
+  };
+}
+
+export { SortingPopover, createSortingColumn };

From b18baff4d0aa812c7cff07506c3e1cefc4248ac8 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Wed, 4 Mar 2026 17:43:58 -0800
Subject: [PATCH 095/267] fix: Correct file_id for docs (#9058)

---
 backend/onyx/server/query_and_chat/chat_backend.py | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/backend/onyx/server/query_and_chat/chat_backend.py b/backend/onyx/server/query_and_chat/chat_backend.py
index 72f7c80123e..83162a00352 100644
--- a/backend/onyx/server/query_and_chat/chat_backend.py
+++ b/backend/onyx/server/query_and_chat/chat_backend.py
@@ -1,6 +1,5 @@
 import datetime
 import json
-import os
 from collections.abc import Generator
 from datetime import timedelta
 from uuid import UUID
@@ -61,7 +60,6 @@
 from onyx.db.usage import increment_usage
 from onyx.db.usage import UsageType
 from onyx.db.user_file import get_file_id_by_user_file_id
-from onyx.file_processing.extract_file_text import docx_to_txt_filename
 from onyx.file_store.file_store import get_default_file_store
 from onyx.llm.constants import LlmProviderNames
 from onyx.llm.factory import get_default_llm
@@ -812,18 +810,6 @@ def fetch_chat_file(
     if not file_record:
         raise HTTPException(status_code=404, detail="File not found")
 
-    original_file_name = file_record.display_name
-    if file_record.file_type.startswith(
-        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
-    ):
-        # Check if a converted text file exists for .docx files
-        txt_file_name = docx_to_txt_filename(original_file_name)
-        txt_file_id = os.path.join(os.path.dirname(file_id), txt_file_name)
-        txt_file_record = file_store.read_file_record(txt_file_id)
-        if txt_file_record:
-            file_record = txt_file_record
-            file_id = txt_file_id
-
     media_type = file_record.file_type
     file_io = file_store.read_file(file_id, mode="b")
 

From c5c236d098c2202a315ddaf794937e59824b59d4 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Wed, 4 Mar 2026 17:54:02 -0800
Subject: [PATCH 096/267] chore(opensearch): Fix and consolidate the dev script
 used to start OpenSearch locally (#9036)

---
 .vscode/launch.json                           | 15 -----
 backend/scripts/restart_containers.sh         | 62 ++++++++++++++++---
 .../scripts/restart_opensearch_container.sh   | 10 ---
 3 files changed, 52 insertions(+), 35 deletions(-)
 delete mode 100644 backend/scripts/restart_opensearch_container.sh

diff --git a/.vscode/launch.json b/.vscode/launch.json
index 09f9c5bf55a..6c17e103e31 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -485,21 +485,6 @@
         "group": "3"
       }
     },
-    {
-      "name": "Clear and Restart OpenSearch Container",
-      // Generic debugger type, required arg but has no bearing on bash.
-      "type": "node",
-      "request": "launch",
-      "runtimeExecutable": "bash",
-      "runtimeArgs": [
-        "${workspaceFolder}/backend/scripts/restart_opensearch_container.sh"
-      ],
-      "cwd": "${workspaceFolder}",
-      "console": "integratedTerminal",
-      "presentation": {
-        "group": "3"
-      }
-    },
     {
       "name": "Eval CLI",
       "type": "debugpy",
diff --git a/backend/scripts/restart_containers.sh b/backend/scripts/restart_containers.sh
index 708e1921cd6..759ba6933b9 100755
--- a/backend/scripts/restart_containers.sh
+++ b/backend/scripts/restart_containers.sh
@@ -1,10 +1,20 @@
 #!/bin/bash
 set -e
 
-cleanup() {
-  echo "Error occurred. Cleaning up..."
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+COMPOSE_FILE="$SCRIPT_DIR/../../deployment/docker_compose/docker-compose.yml"
+COMPOSE_DEV_FILE="$SCRIPT_DIR/../../deployment/docker_compose/docker-compose.dev.yml"
+
+stop_and_remove_containers() {
   docker stop onyx_postgres onyx_vespa onyx_redis onyx_minio onyx_code_interpreter 2>/dev/null || true
   docker rm onyx_postgres onyx_vespa onyx_redis onyx_minio onyx_code_interpreter 2>/dev/null || true
+  docker compose -f "$COMPOSE_FILE" -f "$COMPOSE_DEV_FILE" --profile opensearch-enabled stop opensearch 2>/dev/null || true
+  docker compose -f "$COMPOSE_FILE" -f "$COMPOSE_DEV_FILE" --profile opensearch-enabled rm -f opensearch 2>/dev/null || true
+}
+
+cleanup() {
+  echo "Error occurred. Cleaning up..."
+  stop_and_remove_containers
 }
 
 # Trap errors and output a message, then cleanup
@@ -12,16 +22,26 @@ trap 'echo "Error occurred on line $LINENO. Exiting script." >&2; cleanup' ERR
 
 # Usage of the script with optional volume arguments
 # ./restart_containers.sh [vespa_volume] [postgres_volume] [redis_volume]
-
-VESPA_VOLUME=${1:-""}  # Default is empty if not provided
-POSTGRES_VOLUME=${2:-""}  # Default is empty if not provided
-REDIS_VOLUME=${3:-""}  # Default is empty if not provided
-MINIO_VOLUME=${4:-""}  # Default is empty if not provided
+# [minio_volume] [--keep-opensearch-data]
+
+KEEP_OPENSEARCH_DATA=false
+POSITIONAL_ARGS=()
+for arg in "$@"; do
+    if [[ "$arg" == "--keep-opensearch-data" ]]; then
+        KEEP_OPENSEARCH_DATA=true
+    else
+        POSITIONAL_ARGS+=("$arg")
+    fi
+done
+
+VESPA_VOLUME=${POSITIONAL_ARGS[0]:-""}
+POSTGRES_VOLUME=${POSITIONAL_ARGS[1]:-""}
+REDIS_VOLUME=${POSITIONAL_ARGS[2]:-""}
+MINIO_VOLUME=${POSITIONAL_ARGS[3]:-""}
 
 # Stop and remove the existing containers
 echo "Stopping and removing existing containers..."
-docker stop onyx_postgres onyx_vespa onyx_redis onyx_minio onyx_code_interpreter 2>/dev/null || true
-docker rm onyx_postgres onyx_vespa onyx_redis onyx_minio onyx_code_interpreter 2>/dev/null || true
+stop_and_remove_containers
 
 # Start the PostgreSQL container with optional volume
 echo "Starting PostgreSQL container..."
@@ -39,6 +59,29 @@ else
     docker run --detach --name onyx_vespa --hostname vespa-container --publish 8081:8081 --publish 19071:19071 vespaengine/vespa:8
 fi
 
+# If OPENSEARCH_ADMIN_PASSWORD is not already set, try loading it from
+# .vscode/.env so existing dev setups that stored it there aren't silently
+# broken.
+VSCODE_ENV="$SCRIPT_DIR/../../.vscode/.env"
+if [[ -z "${OPENSEARCH_ADMIN_PASSWORD:-}" && -f "$VSCODE_ENV" ]]; then
+    set -a
+    # shellcheck source=/dev/null
+    source "$VSCODE_ENV"
+    set +a
+fi
+
+# Start the OpenSearch container using the same service from docker-compose that
+# our users use, setting OPENSEARCH_INITIAL_ADMIN_PASSWORD from the env's
+# OPENSEARCH_ADMIN_PASSWORD if it exists, else defaulting to StrongPassword123!.
+# Pass --keep-opensearch-data to preserve the opensearch-data volume across
+# restarts, else the volume is deleted so the container starts fresh.
+if [[ "$KEEP_OPENSEARCH_DATA" == "false" ]]; then
+    echo "Deleting opensearch-data volume..."
+    docker volume rm onyx_opensearch-data 2>/dev/null || true
+fi
+echo "Starting OpenSearch container..."
+docker compose -f "$COMPOSE_FILE" -f "$COMPOSE_DEV_FILE" --profile opensearch-enabled up --force-recreate -d opensearch
+
 # Start the Redis container with optional volume
 echo "Starting Redis container..."
 if [[ -n "$REDIS_VOLUME" ]]; then
@@ -60,7 +103,6 @@ echo "Starting Code Interpreter container..."
 docker run --detach --name onyx_code_interpreter --publish 8000:8000 --user root -v /var/run/docker.sock:/var/run/docker.sock onyxdotapp/code-interpreter:latest bash ./entrypoint.sh code-interpreter-api
 
 # Ensure alembic runs in the correct directory (backend/)
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 PARENT_DIR="$(dirname "$SCRIPT_DIR")"
 cd "$PARENT_DIR"
 
diff --git a/backend/scripts/restart_opensearch_container.sh b/backend/scripts/restart_opensearch_container.sh
deleted file mode 100644
index ad3f2903091..00000000000
--- a/backend/scripts/restart_opensearch_container.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/bash
-
-# We get OPENSEARCH_ADMIN_PASSWORD from the repo .env file.
-source "$(dirname "$0")/../../.vscode/.env"
-
-cd "$(dirname "$0")/../../deployment/docker_compose"
-
-# Start OpenSearch.
-echo "Forcefully starting fresh OpenSearch container..."
-docker compose -f docker-compose.opensearch.yml up --force-recreate -d opensearch

From 3a7d4dad56d48763d45ccbdc4ece6a69b22c792b Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Wed, 4 Mar 2026 19:11:53 -0800
Subject: [PATCH 097/267] fix(ui): Improve text truncation and overflow
 handling in FileCard layout (#9061)

---
 web/src/layouts/general-layouts.tsx | 17 ++++++++++-------
 web/src/sections/cards/FileCard.tsx | 26 ++++++++++++++------------
 2 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/web/src/layouts/general-layouts.tsx b/web/src/layouts/general-layouts.tsx
index 6b80ac76e3a..e6c38662bae 100644
--- a/web/src/layouts/general-layouts.tsx
+++ b/web/src/layouts/general-layouts.tsx
@@ -190,14 +190,17 @@ function AttachmentItemLayout({
         alignItems="center"
         gap={1.5}
       >
-        <Content
-          title={title}
-          description={description}
-          sizePreset="main-ui"
-          variant="section"
-        />
+        <div className="flex-1 min-w-0">
+          <Content
+            title={title}
+            description={description}
+            sizePreset="main-ui"
+            variant="section"
+            widthVariant="full"
+          />
+        </div>
         {middleText && (
-          <div className="flex-1">
+          <div className="flex-1 min-w-0">
             <Truncated text03 secondaryBody>
               {middleText}
             </Truncated>
diff --git a/web/src/sections/cards/FileCard.tsx b/web/src/sections/cards/FileCard.tsx
index 5b53303edf4..d201477050d 100644
--- a/web/src/sections/cards/FileCard.tsx
+++ b/web/src/sections/cards/FileCard.tsx
@@ -173,19 +173,21 @@ export function FileCard({
         removeFile && doneUploading ? () => removeFile(file.id) : undefined
       }
     >
-      <div className="max-w-[12rem]">
+      <div className="min-w-0 max-w-[12rem]">
         <Interactive.Container border heightVariant="fit">
-          <AttachmentItemLayout
-            icon={isProcessing ? SimpleLoader : SvgFileText}
-            title={file.name}
-            description={
-              isProcessing
-                ? file.status === UserFileStatus.UPLOADING
-                  ? "Uploading..."
-                  : "Processing..."
-                : typeLabel
-            }
-          />
+          <div className="[&_.opal-content-md-body]:min-w-0 [&_.opal-content-md-title]:break-all">
+            <AttachmentItemLayout
+              icon={isProcessing ? SimpleLoader : SvgFileText}
+              title={file.name}
+              description={
+                isProcessing
+                  ? file.status === UserFileStatus.UPLOADING
+                    ? "Uploading..."
+                    : "Processing..."
+                  : typeLabel
+              }
+            />
+          </div>
           <Spacer horizontal rem={0.5} />
         </Interactive.Container>
       </div>

From 2c0a4a60a549e7f3da1cea31a8814e48af78b240 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Wed, 4 Mar 2026 19:16:36 -0800
Subject: [PATCH 098/267] refactor: consolidate AppInputBar search/chat
 rendering with animated transitions (#9054)

---
 web/src/app/nrf/NRFPage.tsx                  |   4 -
 web/src/ee/providers/AppModeProvider.tsx     |   3 +-
 web/src/refresh-pages/AppPage.tsx            |   4 -
 web/src/sections/input/AppInputBar.tsx       | 639 ++++++++-----------
 web/src/sections/modals/AgentViewerModal.tsx |   6 -
 5 files changed, 275 insertions(+), 381 deletions(-)

diff --git a/web/src/app/nrf/NRFPage.tsx b/web/src/app/nrf/NRFPage.tsx
index 702a8b9e775..ff93044c278 100644
--- a/web/src/app/nrf/NRFPage.tsx
+++ b/web/src/app/nrf/NRFPage.tsx
@@ -484,12 +484,8 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
                 ref={chatInputBarRef}
                 deepResearchEnabled={deepResearchEnabled}
                 toggleDeepResearch={toggleDeepResearch}
-                toggleDocumentSidebar={() => {}}
                 filterManager={filterManager}
                 llmManager={llmManager}
-                removeDocs={() => {}}
-                retrievalEnabled={retrievalEnabled}
-                selectedDocuments={[]}
                 initialMessage={message}
                 stopGenerating={stopGenerating}
                 onSubmit={handleChatInputSubmit}
diff --git a/web/src/ee/providers/AppModeProvider.tsx b/web/src/ee/providers/AppModeProvider.tsx
index 2e9468c7be1..75a4026c455 100644
--- a/web/src/ee/providers/AppModeProvider.tsx
+++ b/web/src/ee/providers/AppModeProvider.tsx
@@ -23,8 +23,7 @@ export interface AppModeProviderProps {
 export function AppModeProvider({ children }: AppModeProviderProps) {
   const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
   const { user } = useUser();
-  const settings = useSettingsContext();
-  const { isSearchModeAvailable } = settings;
+  const { isSearchModeAvailable } = useSettingsContext();
 
   const persistedMode = user?.preferences?.default_app_mode;
   const [appMode, setAppModeState] = useState<AppMode>("chat");
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 24a5c86747c..b426d930495 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -830,12 +830,8 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                         ref={chatInputBarRef}
                         deepResearchEnabled={deepResearchEnabled}
                         toggleDeepResearch={toggleDeepResearch}
-                        toggleDocumentSidebar={toggleDocumentSidebar}
                         filterManager={filterManager}
                         llmManager={llmManager}
-                        removeDocs={() => setSelectedDocuments([])}
-                        retrievalEnabled={retrievalEnabled}
-                        selectedDocuments={selectedDocuments}
                         initialMessage={
                           searchParams?.get(SEARCH_PARAM_NAMES.USER_PROMPT) ||
                           ""
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index 3ab7e96699b..7e3d59c7349 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -16,16 +16,18 @@ import { FilterManager, LlmManager, useFederatedConnectors } from "@/lib/hooks";
 import usePromptShortcuts from "@/hooks/usePromptShortcuts";
 import useFilter from "@/hooks/useFilter";
 import useCCPairs from "@/hooks/useCCPairs";
-import { OnyxDocument, MinimalOnyxDocument } from "@/lib/search/interfaces";
+import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import { ChatState } from "@/app/app/interfaces";
 import { useForcedTools } from "@/lib/hooks/useForcedTools";
 import { useAppMode } from "@/providers/AppModeProvider";
 import useAppFocus from "@/hooks/useAppFocus";
-import { getFormattedDateRangeString } from "@/lib/dateUtils";
-import { truncateString, cn, isImageFile } from "@/lib/utils";
+import { cn, isImageFile } from "@/lib/utils";
 import { Disabled } from "@/refresh-components/Disabled";
 import { useUser } from "@/providers/UserProvider";
-import { SettingsContext } from "@/providers/SettingsProvider";
+import {
+  SettingsContext,
+  useVectorDbEnabled,
+} from "@/providers/SettingsProvider";
 import { useProjectsContext } from "@/providers/ProjectsContext";
 import { FileCard } from "@/sections/cards/FileCard";
 import {
@@ -40,9 +42,6 @@ import {
 } from "@/app/app/services/actionUtils";
 import {
   SvgArrowUp,
-  SvgCalendar,
-  SvgFiles,
-  SvgFileText,
   SvgGlobe,
   SvgHourglass,
   SvgPlus,
@@ -51,64 +50,22 @@ import {
   SvgStop,
   SvgX,
 } from "@opal/icons";
-import { Button, OpenButton } from "@opal/components";
+import { Button } from "@opal/components";
 import Popover from "@/refresh-components/Popover";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import { Section } from "@/layouts/general-layouts";
 import Spacer from "@/refresh-components/Spacer";
 
-const LINE_HEIGHT = 24;
 const MIN_INPUT_HEIGHT = 44;
 const MAX_INPUT_HEIGHT = 200;
 
-export interface SourceChipProps {
-  icon?: React.ReactNode;
-  title: string;
-  onRemove?: () => void;
-  onClick?: () => void;
-  truncateTitle?: boolean;
-}
-
-export function SourceChip({
-  icon,
-  title,
-  onRemove,
-  onClick,
-  truncateTitle = true,
-}: SourceChipProps) {
-  return (
-    <div
-      onClick={onClick ? onClick : undefined}
-      className={cn(
-        "flex-none flex items-center px-1 bg-background-neutral-01 text-xs text-text-04 border border-border-01 rounded-08 box-border gap-x-1 h-6",
-        onClick && "cursor-pointer"
-      )}
-    >
-      {icon}
-      {truncateTitle ? truncateString(title, 20) : title}
-      {onRemove && (
-        <SvgX
-          size={12}
-          className="text-text-01 ml-auto cursor-pointer"
-          onClick={(e: React.MouseEvent<SVGSVGElement>) => {
-            e.stopPropagation();
-            onRemove();
-          }}
-        />
-      )}
-    </div>
-  );
-}
-
 export interface AppInputBarHandle {
   reset: () => void;
   focus: () => void;
 }
 
 export interface AppInputBarProps {
-  removeDocs: () => void;
-  selectedDocuments: OnyxDocument[];
   initialMessage?: string;
   stopGenerating: () => void;
   onSubmit: (message: string) => void;
@@ -120,10 +77,8 @@ export interface AppInputBarProps {
   // agents
   selectedAgent: MinimalPersonaSnapshot | undefined;
 
-  toggleDocumentSidebar: () => void;
   handleFileUpload: (files: File[]) => void;
   filterManager: FilterManager;
-  retrievalEnabled: boolean;
   deepResearchEnabled: boolean;
   setPresentingDocument?: (document: MinimalOnyxDocument) => void;
   toggleDeepResearch: () => void;
@@ -137,18 +92,13 @@ export interface AppInputBarProps {
 
 const AppInputBar = React.memo(
   ({
-    retrievalEnabled,
-    removeDocs,
-    toggleDocumentSidebar,
     filterManager,
-    selectedDocuments,
     initialMessage = "",
     stopGenerating,
     onSubmit,
     chatState,
     currentSessionFileTokenCount,
     availableContextTokens,
-    // agents
     selectedAgent,
 
     handleFileUpload,
@@ -165,6 +115,9 @@ const AppInputBar = React.memo(
     // Internal message state - kept local to avoid parent re-renders on every keystroke
     const [message, setMessage] = useState(initialMessage);
     const textAreaRef = useRef<HTMLTextAreaElement>(null);
+    const textAreaWrapperRef = useRef<HTMLDivElement>(null);
+    const filesWrapperRef = useRef<HTMLDivElement>(null);
+    const filesContentRef = useRef<HTMLDivElement>(null);
     const containerRef = useRef<HTMLDivElement>(null);
     const { user } = useUser();
     const { isClassifying, classification } = useQueryController();
@@ -178,6 +131,16 @@ const AppInputBar = React.memo(
         textAreaRef.current?.focus();
       },
     }));
+
+    // Sync non-empty prop changes to internal state (e.g. NRFPage reads URL params
+    // after mount). Intentionally skips empty strings — clearing is handled via the
+    // imperative ref.reset() method, not by passing initialMessage="".
+    useEffect(() => {
+      if (initialMessage) {
+        setMessage(initialMessage);
+      }
+    }, [initialMessage]);
+
     const { appMode } = useAppMode();
     const appFocus = useAppFocus();
     const isSearchMode =
@@ -227,46 +190,39 @@ const AppInputBar = React.memo(
 
     const combinedSettings = useContext(SettingsContext);
 
-    // Track previous message to detect when lines might decrease
-    const prevMessageRef = useRef("");
-
-    // Auto-resize textarea based on content
+    // TODO(@raunakab): Replace this useEffect with CSS `field-sizing: content` once
+    // Firefox ships it unflagged (currently behind `layout.css.field-sizing.enabled`).
+    // Auto-resize textarea based on content (chat mode only).
+    // Reset to min-height first so scrollHeight reflects actual content size,
+    // then clamp between min and max. This handles both growing and shrinking.
     useEffect(() => {
-      if (isSearchMode) return;
+      const wrapper = textAreaWrapperRef.current;
       const textarea = textAreaRef.current;
-      if (textarea) {
-        const prevLineCount = (prevMessageRef.current.match(/\n/g) || [])
-          .length;
-        const currLineCount = (message.match(/\n/g) || []).length;
-        const lineRemoved = currLineCount < prevLineCount;
-        prevMessageRef.current = message;
-
-        if (message.length === 0) {
-          textarea.style.height = `${MIN_INPUT_HEIGHT}px`;
-          return;
-        } else if (lineRemoved) {
-          const linesRemoved = prevLineCount - currLineCount;
-          textarea.style.height = `${Math.max(
-            MIN_INPUT_HEIGHT,
-            Math.min(
-              textarea.scrollHeight - LINE_HEIGHT * linesRemoved,
-              MAX_INPUT_HEIGHT
-            )
-          )}px`;
-        } else {
-          textarea.style.height = `${Math.min(
-            textarea.scrollHeight,
-            MAX_INPUT_HEIGHT
-          )}px`;
-        }
-      }
+      if (!wrapper || !textarea) return;
+
+      wrapper.style.height = `${MIN_INPUT_HEIGHT}px`;
+      wrapper.style.height = `${Math.min(
+        Math.max(textarea.scrollHeight, MIN_INPUT_HEIGHT),
+        MAX_INPUT_HEIGHT
+      )}px`;
     }, [message, isSearchMode]);
 
+    // Animate attached files wrapper to its content height so CSS transitions
+    // can interpolate between concrete pixel values (0px ↔ Npx).
+    const showFiles = !isSearchMode && currentMessageFiles.length > 0;
     useEffect(() => {
-      if (initialMessage) {
-        setMessage(initialMessage);
+      const wrapper = filesWrapperRef.current;
+      const content = filesContentRef.current;
+      if (!wrapper || !content) return;
+
+      if (showFiles) {
+        // Measure the inner content's actual height, then add padding (p-1 = 8px total)
+        const PADDING = 8;
+        wrapper.style.height = `${content.offsetHeight + PADDING}px`;
+      } else {
+        wrapper.style.height = "0px";
       }
-    }, [initialMessage]);
+    }, [showFiles, currentMessageFiles]);
 
     function handlePaste(event: React.ClipboardEvent) {
       const items = event.clipboardData?.items;
@@ -294,8 +250,7 @@ const AppInputBar = React.memo(
     );
 
     const { activePromptShortcuts } = usePromptShortcuts();
-    const vectorDbEnabled =
-      combinedSettings?.settings.vector_db_enabled !== false;
+    const vectorDbEnabled = useVectorDbEnabled();
     const { ccPairs, isLoading: ccPairsLoading } = useCCPairs(vectorDbEnabled);
     const { data: federatedConnectorsData, isLoading: federatedLoading } =
       useFederatedConnectors();
@@ -412,7 +367,9 @@ const AppInputBar = React.memo(
       combinedSettings?.settings?.deep_research_enabled,
     ]);
 
-    function handleKeyDown(e: React.KeyboardEvent<HTMLTextAreaElement>) {
+    function handleKeyDownForPromptShortcuts(
+      e: React.KeyboardEvent<HTMLTextAreaElement>
+    ) {
       if (!user?.preferences?.shortcut_enabled || !showPrompts) return;
 
       if (e.key === "Enter") {
@@ -447,6 +404,171 @@ const AppInputBar = React.memo(
       }
     }
 
+    const chatControls = (
+      <div
+        {...(isSearchMode ? { inert: true } : {})}
+        className={cn(
+          "flex justify-between items-center w-full",
+          isSearchMode
+            ? "opacity-0 p-0 h-0 overflow-hidden pointer-events-none"
+            : "opacity-100 p-1 h-[2.75rem] pointer-events-auto",
+          "transition-all duration-150"
+        )}
+      >
+        {/* Bottom left controls */}
+        <div className="flex flex-row items-center">
+          {/* (+) button - always visible */}
+          <FilePickerPopover
+            onFileClick={handleFileClick}
+            onPickRecent={(file: ProjectFile) => {
+              // Check if file with same ID already exists
+              if (
+                !currentMessageFiles.some(
+                  (existingFile) => existingFile.file_id === file.file_id
+                )
+              ) {
+                setCurrentMessageFiles((prev) => [...prev, file]);
+              }
+            }}
+            onUnpickRecent={(file: ProjectFile) => {
+              setCurrentMessageFiles((prev) =>
+                prev.filter(
+                  (existingFile) => existingFile.file_id !== file.file_id
+                )
+              );
+            }}
+            handleUploadChange={handleUploadChange}
+            trigger={(open) => (
+              <Button
+                icon={SvgPlusCircle}
+                tooltip="Attach Files"
+                transient={open}
+                disabled={disabled}
+                prominence="tertiary"
+              />
+            )}
+            selectedFileIds={currentMessageFiles.map((f) => f.id)}
+          />
+
+          {/* Controls that load in when data is ready */}
+          <div
+            data-testid="actions-container"
+            className={cn(
+              "flex flex-row items-center",
+              controlsLoading && "invisible"
+            )}
+          >
+            {selectedAgent && selectedAgent.tools.length > 0 && (
+              <ActionsPopover
+                selectedAgent={selectedAgent}
+                filterManager={filterManager}
+                availableSources={memoizedAvailableSources}
+                disabled={disabled}
+              />
+            )}
+            {onToggleTabReading ? (
+              <Button
+                icon={SvgGlobe}
+                onClick={onToggleTabReading}
+                variant="select"
+                selected={tabReadingEnabled}
+                foldable={!tabReadingEnabled}
+                disabled={disabled}
+              >
+                {tabReadingEnabled
+                  ? currentTabUrl
+                    ? (() => {
+                        try {
+                          return new URL(currentTabUrl).hostname;
+                        } catch {
+                          return currentTabUrl;
+                        }
+                      })()
+                    : "Reading tab..."
+                  : "Read this tab"}
+              </Button>
+            ) : (
+              showDeepResearch && (
+                <Button
+                  icon={SvgHourglass}
+                  onClick={toggleDeepResearch}
+                  variant="select"
+                  selected={deepResearchEnabled}
+                  foldable={!deepResearchEnabled}
+                  disabled={disabled}
+                >
+                  Deep Research
+                </Button>
+              )
+            )}
+
+            {selectedAgent &&
+              forcedToolIds.length > 0 &&
+              forcedToolIds.map((toolId) => {
+                const tool = selectedAgent.tools.find(
+                  (tool) => tool.id === toolId
+                );
+                if (!tool) {
+                  return null;
+                }
+                return (
+                  <Button
+                    key={toolId}
+                    icon={getIconForAction(tool)}
+                    onClick={() => {
+                      setForcedToolIds(
+                        forcedToolIds.filter((id) => id !== toolId)
+                      );
+                    }}
+                    variant="select"
+                    selected
+                    disabled={disabled}
+                  >
+                    {tool.display_name}
+                  </Button>
+                );
+              })}
+          </div>
+        </div>
+
+        {/* Bottom right controls */}
+        <div className="flex flex-row items-center gap-1">
+          <div
+            data-testid="AppInputBar/llm-popover-trigger"
+            className={cn(controlsLoading && "invisible")}
+          >
+            <LLMPopover
+              llmManager={llmManager}
+              requiresImageInput={hasImageFiles}
+              disabled={disabled}
+            />
+          </div>
+          <Button
+            id="onyx-chat-input-send-button"
+            icon={
+              isClassifying
+                ? SimpleLoader
+                : chatState === "input"
+                  ? SvgArrowUp
+                  : SvgStop
+            }
+            disabled={
+              (chatState === "input" && !message) ||
+              hasUploadingFiles ||
+              isClassifying
+            }
+            onClick={() => {
+              if (chatState == "streaming") {
+                stopGenerating();
+              } else if (message) {
+                onSubmit(message);
+              }
+            }}
+          />
+        </div>
+      </div>
+    );
+
     return (
       <Disabled disabled={disabled} allowClick>
         <div
@@ -467,8 +589,17 @@ const AppInputBar = React.memo(
           )}
         >
           {/* Attached Files */}
-          {currentMessageFiles.length > 0 && (
-            <div className="p-2 rounded-t-16 flex flex-wrap gap-1">
+          <div
+            ref={filesWrapperRef}
+            {...(!showFiles ? { inert: true } : {})}
+            className={cn(
+              "transition-all duration-150",
+              showFiles
+                ? "opacity-100 p-1"
+                : "opacity-0 p-0 overflow-hidden pointer-events-none"
+            )}
+          >
+            <div ref={filesContentRef} className="flex flex-wrap gap-1">
               {currentMessageFiles.map((file) => (
                 <FileCard
                   key={file.id}
@@ -480,76 +611,61 @@ const AppInputBar = React.memo(
                 />
               ))}
             </div>
-          )}
+          </div>
 
-          {/* Input area */}
-          <div
-            className={cn(
-              "flex flex-row items-center w-full",
-              isSearchMode && "p-1"
-            )}
-          >
+          <div className="flex flex-row items-center w-full">
             <Popover
               open={user?.preferences?.shortcut_enabled && showPrompts}
               onOpenChange={setShowPrompts}
             >
               <Popover.Anchor asChild>
-                <textarea
-                  onPaste={handlePaste}
-                  onKeyDownCapture={handleKeyDown}
-                  onChange={handleInputChange}
-                  ref={textAreaRef}
-                  id="onyx-chat-input-textarea"
-                  className={cn(
-                    "w-full",
-                    "outline-none",
-                    "bg-transparent",
-                    "resize-none",
-                    "placeholder:text-text-03",
-                    "whitespace-pre-wrap",
-                    "break-word",
-                    "overscroll-contain",
-                    "px-3",
-                    isSearchMode
-                      ? "h-[40px] py-2.5 overflow-hidden"
-                      : [
-                          "h-[44px]", // Fixed initial height to prevent flash - useEffect will adjust as needed
-                          "overflow-y-auto",
-                          "pb-2",
-                          "pt-3",
-                        ]
-                  )}
-                  autoFocus
-                  style={{ scrollbarWidth: "thin" }}
-                  role="textarea"
-                  aria-multiline
-                  placeholder={
-                    isSearchMode
-                      ? "Search connected sources"
-                      : "How can I help you today"
-                  }
-                  value={message}
-                  onKeyDown={(event) => {
-                    if (
-                      event.key === "Enter" &&
-                      !showPrompts &&
-                      !event.shiftKey &&
-                      !(event.nativeEvent as any).isComposing
-                    ) {
-                      event.preventDefault();
+                <div
+                  ref={textAreaWrapperRef}
+                  className="px-3 py-2 flex-1 flex h-[2.75rem]"
+                >
+                  <textarea
+                    id="onyx-chat-input-textarea"
+                    role="textarea"
+                    ref={textAreaRef}
+                    onPaste={handlePaste}
+                    onKeyDownCapture={handleKeyDownForPromptShortcuts}
+                    onChange={handleInputChange}
+                    className={cn(
+                      "p-[2px] w-full h-full outline-none bg-transparent resize-none placeholder:text-text-03 whitespace-pre-wrap break-words",
+                      "overflow-y-auto"
+                    )}
+                    autoFocus
+                    rows={1}
+                    style={{ scrollbarWidth: "thin" }}
+                    aria-multiline={true}
+                    placeholder={
+                      isSearchMode
+                        ? "Search connected sources"
+                        : "How can I help you today?"
+                    }
+                    value={message}
+                    onKeyDown={(event) => {
                       if (
-                        message &&
-                        !disabled &&
-                        !isClassifying &&
-                        !hasUploadingFiles
+                        event.key === "Enter" &&
+                        !showPrompts &&
+                        !event.shiftKey &&
+                        !(event.nativeEvent as any).isComposing
                       ) {
-                        onSubmit(message);
+                        event.preventDefault();
+                        if (
+                          message &&
+                          !disabled &&
+                          !isClassifying &&
+                          !hasUploadingFiles
+                        ) {
+                          onSubmit(message);
+                        }
                       }
-                    }
-                  }}
-                  suppressContentEditableWarning={true}
-                  disabled={disabled}
-                />
+                    }}
+                    suppressContentEditableWarning={true}
+                    disabled={disabled}
+                  />
+                </div>
               </Popover.Anchor>
 
               <Popover.Content
@@ -616,214 +732,7 @@ const AppInputBar = React.memo(
             )}
           </div>
 
-          {/* Source chips */}
-          {(selectedDocuments.length > 0 ||
-            filterManager.timeRange ||
-            filterManager.selectedDocumentSets.length > 0) && (
-            <div className="flex gap-x-.5 px-2">
-              <div className="flex gap-x-1 px-2 overflow-visible overflow-x-scroll items-end miniscroll">
-                {filterManager.timeRange && (
-                  <SourceChip
-                    truncateTitle={false}
-                    key="time-range"
-                    icon={<SvgCalendar size={12} />}
-                    title={`${getFormattedDateRangeString(
-                      filterManager.timeRange.from,
-                      filterManager.timeRange.to
-                    )}`}
-                    onRemove={() => {
-                      filterManager.setTimeRange(null);
-                    }}
-                  />
-                )}
-                {filterManager.selectedDocumentSets.length > 0 &&
-                  filterManager.selectedDocumentSets.map((docSet, index) => (
-                    <SourceChip
-                      key={`doc-set-${index}`}
-                      icon={<SvgFiles size={16} />}
-                      title={docSet}
-                      onRemove={() => {
-                        filterManager.setSelectedDocumentSets(
-                          filterManager.selectedDocumentSets.filter(
-                            (ds) => ds !== docSet
-                          )
-                        );
-                      }}
-                    />
-                  ))}
-                {selectedDocuments.length > 0 && (
-                  <SourceChip
-                    key="selected-documents"
-                    onClick={() => {
-                      toggleDocumentSidebar();
-                    }}
-                    icon={<SvgFileText size={16} />}
-                    title={`${selectedDocuments.length} selected`}
-                    onRemove={removeDocs}
-                  />
-                )}
-              </div>
-            </div>
-          )}
-
-          {!isSearchMode && (
-            <div className="flex justify-between items-center w-full p-1 min-h-[40px]">
-              {/* Bottom left controls */}
-              <div className="flex flex-row items-center">
-                {/* (+) button - always visible */}
-                <FilePickerPopover
-                  onFileClick={handleFileClick}
-                  onPickRecent={(file: ProjectFile) => {
-                    // Check if file with same ID already exists
-                    if (
-                      !currentMessageFiles.some(
-                        (existingFile) => existingFile.file_id === file.file_id
-                      )
-                    ) {
-                      setCurrentMessageFiles((prev) => [...prev, file]);
-                    }
-                  }}
-                  onUnpickRecent={(file: ProjectFile) => {
-                    setCurrentMessageFiles((prev) =>
-                      prev.filter(
-                        (existingFile) => existingFile.file_id !== file.file_id
-                      )
-                    );
-                  }}
-                  handleUploadChange={handleUploadChange}
-                  trigger={(open) => (
-                    <Button
-                      icon={SvgPlusCircle}
-                      tooltip="Attach Files"
-                      transient={open}
-                      disabled={disabled}
-                      prominence="tertiary"
-                    />
-                  )}
-                  selectedFileIds={currentMessageFiles.map((f) => f.id)}
-                />
-
-                {/* Controls that load in when data is ready */}
-                <div
-                  data-testid="actions-container"
-                  className={cn(
-                    "flex flex-row items-center",
-                    controlsLoading && "invisible"
-                  )}
-                >
-                  {selectedAgent && selectedAgent.tools.length > 0 && (
-                    <ActionsPopover
-                      selectedAgent={selectedAgent}
-                      filterManager={filterManager}
-                      availableSources={memoizedAvailableSources}
-                      disabled={disabled}
-                    />
-                  )}
-                  {onToggleTabReading ? (
-                    <Button
-                      icon={SvgGlobe}
-                      onClick={onToggleTabReading}
-                      variant="select"
-                      selected={tabReadingEnabled}
-                      foldable={!tabReadingEnabled}
-                      disabled={disabled}
-                    >
-                      {tabReadingEnabled
-                        ? currentTabUrl
-                          ? (() => {
-                              try {
-                                return new URL(currentTabUrl).hostname;
-                              } catch {
-                                return currentTabUrl;
-                              }
-                            })()
-                          : "Reading tab..."
-                        : "Read this tab"}
-                    </Button>
-                  ) : (
-                    showDeepResearch && (
-                      <Button
-                        icon={SvgHourglass}
-                        onClick={toggleDeepResearch}
-                        variant="select"
-                        selected={deepResearchEnabled}
-                        foldable={!deepResearchEnabled}
-                        disabled={disabled}
-                      >
-                        Deep Research
-                      </Button>
-                    )
-                  )}
-
-                  {selectedAgent &&
-                    forcedToolIds.length > 0 &&
-                    forcedToolIds.map((toolId) => {
-                      const tool = selectedAgent.tools.find(
-                        (tool) => tool.id === toolId
-                      );
-                      if (!tool) {
-                        return null;
-                      }
-                      return (
-                        <Button
-                          key={toolId}
-                          icon={getIconForAction(tool)}
-                          onClick={() => {
-                            setForcedToolIds(
-                              forcedToolIds.filter((id) => id !== toolId)
-                            );
-                          }}
-                          variant="select"
-                          selected
-                          disabled={disabled}
-                        >
-                          {tool.display_name}
-                        </Button>
-                      );
-                    })}
-                </div>
-              </div>
-
-              {/* Bottom right controls */}
-              <div className="flex flex-row items-center gap-1">
-                {/* LLM popover - loads when ready */}
-                <div
-                  data-testid="AppInputBar/llm-popover-trigger"
-                  className={cn(controlsLoading && "invisible")}
-                >
-                  <LLMPopover
-                    llmManager={llmManager}
-                    requiresImageInput={hasImageFiles}
-                    disabled={disabled}
-                  />
-                </div>
-
-                {/* Submit button */}
-                <Button
-                  id="onyx-chat-input-send-button"
-                  icon={
-                    isClassifying
-                      ? SimpleLoader
-                      : chatState === "input"
-                        ? SvgArrowUp
-                        : SvgStop
-                  }
-                  disabled={
-                    (chatState === "input" && !message) ||
-                    hasUploadingFiles ||
-                    isClassifying
-                  }
-                  onClick={() => {
-                    if (chatState == "streaming") {
-                      stopGenerating();
-                    } else if (message) {
-                      onSubmit(message);
-                    }
-                  }}
-                />
-              </div>
-            </div>
-          )}
+          {chatControls}
         </div>
       </Disabled>
     );
diff --git a/web/src/sections/modals/AgentViewerModal.tsx b/web/src/sections/modals/AgentViewerModal.tsx
index dd73fa8d547..ca7393c4028 100644
--- a/web/src/sections/modals/AgentViewerModal.tsx
+++ b/web/src/sections/modals/AgentViewerModal.tsx
@@ -116,8 +116,6 @@ function ViewerOpenApiToolCard({ tool }: { tool: ToolSnapshot }) {
   );
 }
 
-const EMPTY_DOCS: [] = [];
-
 /**
  * Floating ChatInputBar below the AgentViewerModal.
  * On submit, navigates to the agent's chat with the message pre-filled.
@@ -137,14 +135,10 @@ function AgentChatInput({ agent, onSubmit }: AgentChatInputProps) {
       chatState="input"
       filterManager={filterManager}
       selectedAgent={agent}
-      selectedDocuments={EMPTY_DOCS}
-      removeDocs={() => {}}
       stopGenerating={() => {}}
       handleFileUpload={() => {}}
-      toggleDocumentSidebar={() => {}}
       currentSessionFileTokenCount={0}
       availableContextTokens={Infinity}
-      retrievalEnabled={false}
       deepResearchEnabled={false}
       toggleDeepResearch={() => {}}
       disabled={false}

From e0d91b9ea7a22db16901a87b2f546870e16a945b Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 4 Mar 2026 19:26:50 -0800
Subject: [PATCH 099/267] chore(fe): rm unreachable code (#9069)

---
 web/src/app/app/message/HumanMessage.tsx | 23 ++---------------------
 1 file changed, 2 insertions(+), 21 deletions(-)

diff --git a/web/src/app/app/message/HumanMessage.tsx b/web/src/app/app/message/HumanMessage.tsx
index 097145cd20e..f49f71d2ce1 100644
--- a/web/src/app/app/message/HumanMessage.tsx
+++ b/web/src/app/app/message/HumanMessage.tsx
@@ -190,7 +190,7 @@ const HumanMessage = React.memo(function HumanMessage({
             }}
             onCancelEdit={() => setIsEditing(false)}
           />
-        ) : typeof content === "string" ? (
+        ) : (
           <>
             <div className="md:max-w-[37.5rem] flex basis-[100%] md:basis-auto justify-end md:order-1">
               <div
@@ -218,7 +218,7 @@ const HumanMessage = React.memo(function HumanMessage({
                 </Text>
               </div>
             </div>
-            {onEdit && !isEditing && (
+            {onEdit && (
               <div className="absolute md:relative right-0 z-content flex flex-row p-1 opacity-0 group-hover:opacity-100 transition-opacity">
                 <CopyIconButton
                   getCopyText={() => content}
@@ -235,25 +235,6 @@ const HumanMessage = React.memo(function HumanMessage({
               </div>
             )}
           </>
-        ) : (
-          <>
-            <div
-              className={cn(
-                "my-auto",
-                onEdit && !isEditing
-                  ? "opacity-0 group-hover:opacity-100 transition-opacity"
-                  : "invisible"
-              )}
-            >
-              <Button
-                icon={SvgEdit}
-                onClick={() => setIsEditing(true)}
-                prominence="tertiary"
-                tooltip="Edit"
-              />
-            </div>
-            <div className="ml-auto rounded-lg p-1">{content}</div>
-          </>
         )}
         <div className="md:min-w-[100%] flex justify-end order-1 mt-1">
           {currentMessageInd !== undefined &&

From f7630f56482d2c195236a4cfc4d9c417f0ebcdd6 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 4 Mar 2026 19:44:16 -0800
Subject: [PATCH 100/267] fix: EE route gating for upgrading CE users (#9026)

---
 backend/ee/onyx/main.py                       | 10 ++---
 backend/onyx/server/settings/models.py        |  8 ++--
 .../test_license_enforcement_settings.py      |  5 ++-
 web/src/app/ee/EEFeatureRedirect.tsx          | 18 ++++++++
 web/src/app/ee/layout.tsx                     | 17 ++------
 web/src/hooks/useBillingInformation.ts        | 24 +----------
 web/src/hooks/useLicense.ts                   | 28 ++----------
 web/src/interfaces/settings.ts                |  4 +-
 web/src/lib/constants.ts                      |  7 ++-
 web/src/providers/ToastProvider.tsx           | 10 -----
 .../e2e/admin/ee_feature_redirect.spec.ts     | 20 +++++++++
 .../theme/appearance_theme_settings.spec.ts   | 27 ++++++------
 web/tests/e2e/fixtures/eeFeatures.ts          | 43 +++++++++++++++++++
 13 files changed, 121 insertions(+), 100 deletions(-)
 create mode 100644 web/src/app/ee/EEFeatureRedirect.tsx
 create mode 100644 web/tests/e2e/admin/ee_feature_redirect.spec.ts
 create mode 100644 web/tests/e2e/fixtures/eeFeatures.ts

diff --git a/backend/ee/onyx/main.py b/backend/ee/onyx/main.py
index 575c159250a..1755dd0ba3a 100644
--- a/backend/ee/onyx/main.py
+++ b/backend/ee/onyx/main.py
@@ -4,7 +4,6 @@
 from fastapi import FastAPI
 from httpx_oauth.clients.google import GoogleOAuth2
 
-from ee.onyx.configs.app_configs import LICENSE_ENFORCEMENT_ENABLED
 from ee.onyx.server.analytics.api import router as analytics_router
 from ee.onyx.server.auth_check import check_ee_router_auth
 from ee.onyx.server.billing.api import router as billing_router
@@ -153,12 +152,9 @@ def get_application() -> FastAPI:
     # License management
     include_router_with_global_prefix_prepended(application, license_router)
 
-    # Unified billing API - available when license system is enabled
-    # Works for both self-hosted and cloud deployments
-    # TODO(ENG-3533): Once frontend migrates to /admin/billing/*, this becomes the
-    # primary billing API and /tenants/* billing endpoints can be removed
-    if LICENSE_ENFORCEMENT_ENABLED:
-        include_router_with_global_prefix_prepended(application, billing_router)
+    # Unified billing API - always registered in EE.
+    # Each endpoint is protected by the `current_admin_user` dependency (admin auth).
+    include_router_with_global_prefix_prepended(application, billing_router)
 
     if MULTI_TENANT:
         # Tenant management
diff --git a/backend/onyx/server/settings/models.py b/backend/onyx/server/settings/models.py
index 3eabefb2254..63c814ec783 100644
--- a/backend/onyx/server/settings/models.py
+++ b/backend/onyx/server/settings/models.py
@@ -60,9 +60,11 @@ class Settings(BaseModel):
     deep_research_enabled: bool | None = None
     search_ui_enabled: bool | None = None
 
-    # Enterprise features flag - set by license enforcement at runtime
-    # When LICENSE_ENFORCEMENT_ENABLED=true, this reflects license status
-    # When LICENSE_ENFORCEMENT_ENABLED=false, defaults to False
+    # Whether EE features are unlocked for use.
+    # Depends on license status: True when the user has a valid license
+    # (ACTIVE, GRACE_PERIOD, PAYMENT_REMINDER), False when there's no license
+    # or the license is expired (GATED_ACCESS).
+    # This controls UI visibility of EE features (user groups, analytics, RBAC, etc.).
     ee_features_enabled: bool = False
 
     temperature_override_enabled: bool | None = False
diff --git a/backend/tests/unit/ee/onyx/server/settings/test_license_enforcement_settings.py b/backend/tests/unit/ee/onyx/server/settings/test_license_enforcement_settings.py
index 8463e28675e..1d2dad763d0 100644
--- a/backend/tests/unit/ee/onyx/server/settings/test_license_enforcement_settings.py
+++ b/backend/tests/unit/ee/onyx/server/settings/test_license_enforcement_settings.py
@@ -281,9 +281,10 @@ def test_redis_error_disables_ee_features(
         }
 
 
-class TestSettingsDefaultEEDisabled:
-    """Verify the Settings model defaults ee_features_enabled to False."""
+class TestSettingsDefaults:
+    """Verify Settings model defaults for CE deployments."""
 
     def test_default_ee_features_disabled(self) -> None:
+        """CE default: ee_features_enabled is False."""
         settings = Settings()
         assert settings.ee_features_enabled is False
diff --git a/web/src/app/ee/EEFeatureRedirect.tsx b/web/src/app/ee/EEFeatureRedirect.tsx
new file mode 100644
index 00000000000..420ae6cc578
--- /dev/null
+++ b/web/src/app/ee/EEFeatureRedirect.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { toast } from "@/hooks/useToast";
+
+export default function EEFeatureRedirect() {
+  const router = useRouter();
+
+  useEffect(() => {
+    toast.error(
+      "This feature requires a license. Please upgrade your plan to access."
+    );
+    router.replace("/app");
+  }, [router]);
+
+  return null;
+}
diff --git a/web/src/app/ee/layout.tsx b/web/src/app/ee/layout.tsx
index c89795f13ed..e6aa2a90a15 100644
--- a/web/src/app/ee/layout.tsx
+++ b/web/src/app/ee/layout.tsx
@@ -1,5 +1,6 @@
 import { SERVER_SIDE_ONLY__PAID_ENTERPRISE_FEATURES_ENABLED } from "@/lib/constants";
 import { fetchStandardSettingsSS } from "@/components/settings/lib";
+import EEFeatureRedirect from "@/app/ee/EEFeatureRedirect";
 
 export default async function AdminLayout({
   children,
@@ -8,13 +9,7 @@ export default async function AdminLayout({
 }) {
   // First check build-time constant (fast path)
   if (!SERVER_SIDE_ONLY__PAID_ENTERPRISE_FEATURES_ENABLED) {
-    return (
-      <div className="flex h-screen">
-        <div className="mx-auto my-auto text-lg font-bold text-red-500">
-          This functionality is only available in the Enterprise Edition :(
-        </div>
-      </div>
-    );
+    return <EEFeatureRedirect />;
   }
 
   // Then check runtime license status (for license enforcement mode)
@@ -31,13 +26,7 @@ export default async function AdminLayout({
           return children;
         }
 
-        return (
-          <div className="flex h-screen">
-            <div className="mx-auto my-auto text-lg font-bold text-red-500">
-              This functionality requires an active Enterprise license.
-            </div>
-          </div>
-        );
+        return <EEFeatureRedirect />;
       }
     }
   } catch (error) {
diff --git a/web/src/hooks/useBillingInformation.ts b/web/src/hooks/useBillingInformation.ts
index 5f75675c351..41860402b7e 100644
--- a/web/src/hooks/useBillingInformation.ts
+++ b/web/src/hooks/useBillingInformation.ts
@@ -11,21 +11,8 @@ import {
  * Hook to fetch billing information from Stripe.
  *
  * Works for both cloud and self-hosted deployments:
- * - Cloud: fetches from /api/tenants/billing-information (legacy endpoint)
+ * - Cloud: fetches from /api/tenants/billing-information
  * - Self-hosted: fetches from /api/admin/billing/billing-information
- *
- * Returns subscription status, seats, billing period, etc.
- *
- * @example
- * ```tsx
- * const { data, isLoading, error, refresh } = useBillingInformation();
- *
- * if (isLoading) return <Loading />;
- * if (error) return <Error />;
- * if (!data || !hasActiveSubscription(data)) return <NoSubscription />;
- *
- * return <BillingDetails billing={data} />;
- * ```
  */
 export function useBillingInformation() {
   const url = NEXT_PUBLIC_CLOUD_ENABLED
@@ -38,16 +25,9 @@ export function useBillingInformation() {
     revalidateOnFocus: false,
     revalidateOnReconnect: false,
     dedupingInterval: 30000,
-    // Don't auto-retry on errors (circuit breaker will block requests anyway)
     shouldRetryOnError: false,
-    // Keep previous data while revalidating to prevent UI flashing
     keepPreviousData: true,
   });
 
-  return {
-    data,
-    isLoading,
-    error,
-    refresh: mutate,
-  };
+  return { data, isLoading, error, refresh: mutate };
 }
diff --git a/web/src/hooks/useLicense.ts b/web/src/hooks/useLicense.ts
index 63875764ddb..ad44a69755a 100644
--- a/web/src/hooks/useLicense.ts
+++ b/web/src/hooks/useLicense.ts
@@ -7,23 +7,9 @@ import { LicenseStatus } from "@/lib/billing/interfaces";
 /**
  * Hook to fetch license status for self-hosted deployments.
  *
- * Returns license information including seats, expiry, and status.
- * Only fetches for self-hosted deployments (cloud uses tenant auth instead).
- *
- * @example
- * ```tsx
- * const { data, isLoading, error, refresh } = useLicense();
- *
- * if (isLoading) return <Loading />;
- * if (error) return <Error />;
- * if (!data?.has_license) return <NoLicense />;
- *
- * return <LicenseDetails license={data} />;
- * ```
+ * Skips the fetch on cloud deployments (uses tenant auth instead).
  */
 export function useLicense() {
-  // Only fetch license for self-hosted deployments
-  // Cloud deployments use tenant-based auth, not license files
   const url = NEXT_PUBLIC_CLOUD_ENABLED ? null : "/api/license";
 
   const { data, error, mutate, isLoading } = useSWR<LicenseStatus>(
@@ -38,20 +24,14 @@ export function useLicense() {
     }
   );
 
-  // Return empty state for cloud deployments
-  if (NEXT_PUBLIC_CLOUD_ENABLED) {
+  if (!url) {
     return {
-      data: null,
+      data: undefined,
       isLoading: false,
       error: undefined,
       refresh: () => Promise.resolve(undefined),
     };
   }
 
-  return {
-    data,
-    isLoading,
-    error,
-    refresh: mutate,
-  };
+  return { data, isLoading, error, refresh: mutate };
 }
diff --git a/web/src/interfaces/settings.ts b/web/src/interfaces/settings.ts
index a963b9a0871..a0e0a1cf62e 100644
--- a/web/src/interfaces/settings.ts
+++ b/web/src/interfaces/settings.ts
@@ -46,8 +46,8 @@ export interface Settings {
   // Onyx Craft (Build Mode) feature flag
   onyx_craft_enabled?: boolean;
 
-  // Enterprise features flag - controlled by license enforcement at runtime
-  // True when user has a valid license, False for community edition
+  // Whether EE features are unlocked (user has a valid enterprise license).
+  // Controls UI visibility of EE features like user groups, analytics, RBAC.
   ee_features_enabled?: boolean;
 
   // Seat usage - populated when seat limit is exceeded
diff --git a/web/src/lib/constants.ts b/web/src/lib/constants.ts
index ba106168938..de232adb2b4 100644
--- a/web/src/lib/constants.ts
+++ b/web/src/lib/constants.ts
@@ -42,8 +42,13 @@ export const NEXT_PUBLIC_CUSTOM_REFRESH_URL =
 
 // NOTE: this should ONLY be used on the server-side. If used client side,
 // it will not be accurate (will always be false).
+// Mirrors backend logic: EE is enabled if EITHER the legacy flag OR license
+// enforcement is active. LICENSE_ENFORCEMENT_ENABLED defaults to true on the
+// backend, so we treat undefined as enabled here to match.
 export const SERVER_SIDE_ONLY__PAID_ENTERPRISE_FEATURES_ENABLED =
-  process.env.ENABLE_PAID_ENTERPRISE_EDITION_FEATURES?.toLowerCase() === "true";
+  process.env.ENABLE_PAID_ENTERPRISE_EDITION_FEATURES?.toLowerCase() ===
+    "true" ||
+  process.env.LICENSE_ENFORCEMENT_ENABLED?.toLowerCase() !== "false";
 // NOTE: since this is a `NEXT_PUBLIC_` variable, it will be set at
 // build-time
 // TODO: consider moving this to an API call so that the api_server
diff --git a/web/src/providers/ToastProvider.tsx b/web/src/providers/ToastProvider.tsx
index f2bf0db318d..36eb556581a 100644
--- a/web/src/providers/ToastProvider.tsx
+++ b/web/src/providers/ToastProvider.tsx
@@ -51,16 +51,6 @@ function ToastContainer() {
     }, ANIMATION_DURATION);
   }, []);
 
-  // NOTE (@raunakab):
-  //
-  // Keep this here for debugging purposes.
-  // useOnMount(() => {
-  //   toast.success("Test success toast", { duration: Infinity });
-  //   toast.error("Test error toast", { duration: Infinity });
-  //   toast.warning("Test warning toast", { duration: Infinity });
-  //   toast.info("Test info toast", { duration: Infinity });
-  // });
-
   if (visible.length === 0) return null;
 
   return (
diff --git a/web/tests/e2e/admin/ee_feature_redirect.spec.ts b/web/tests/e2e/admin/ee_feature_redirect.spec.ts
new file mode 100644
index 00000000000..9fe554aab40
--- /dev/null
+++ b/web/tests/e2e/admin/ee_feature_redirect.spec.ts
@@ -0,0 +1,20 @@
+import { test, expect } from "@tests/e2e/fixtures/eeFeatures";
+
+test.describe("EE Feature Redirect", () => {
+  test("redirects to /chat with toast when EE features are not licensed", async ({
+    page,
+    eeEnabled,
+  }) => {
+    test.skip(eeEnabled, "Redirect only happens without Enterprise license");
+
+    await page.goto("/admin/theme");
+
+    await expect(page).toHaveURL(/\/chat/, { timeout: 10_000 });
+
+    const toastContainer = page.getByTestId("toast-container");
+    await expect(toastContainer).toBeVisible({ timeout: 5_000 });
+    await expect(
+      toastContainer.getByText(/only accessible with a paid license/i)
+    ).toBeVisible();
+  });
+});
diff --git a/web/tests/e2e/admin/theme/appearance_theme_settings.spec.ts b/web/tests/e2e/admin/theme/appearance_theme_settings.spec.ts
index 8c35f69c51b..3ed30cc99bf 100644
--- a/web/tests/e2e/admin/theme/appearance_theme_settings.spec.ts
+++ b/web/tests/e2e/admin/theme/appearance_theme_settings.spec.ts
@@ -1,4 +1,4 @@
-import { test, expect } from "@playwright/test";
+import { test, expect } from "@tests/e2e/fixtures/eeFeatures";
 import { loginAs } from "@tests/e2e/utils/auth";
 
 test.describe("Appearance Theme Settings @exclusive", () => {
@@ -12,24 +12,21 @@ test.describe("Appearance Theme Settings @exclusive", () => {
     consentPrompt: "I agree to the terms",
   };
 
-  test.beforeEach(async ({ page }) => {
+  test.beforeEach(async ({ page, eeEnabled }) => {
+    test.skip(
+      !eeEnabled,
+      "Enterprise license not active — skipping theme tests"
+    );
+
+    // Fresh session — the eeEnabled fixture already logged in to check the
+    // setting, so clear cookies and re-login for a clean test state.
     await page.context().clearCookies();
     await loginAs(page, "admin");
 
-    // Navigate first so localStorage is accessible (API-based login
-    // doesn't navigate, leaving the page on about:blank).
     await page.goto("/admin/theme");
-    await page.waitForLoadState("networkidle");
-
-    // Skip the entire test when Enterprise features are not licensed.
-    // The /admin/theme page is gated behind ee_features_enabled and
-    // renders a license-required message instead of the settings form.
-    const eeLocked = page.getByText(
-      "This functionality requires an active Enterprise license."
-    );
-    if (await eeLocked.isVisible({ timeout: 1000 }).catch(() => false)) {
-      test.skip(true, "Enterprise license not active — skipping theme tests");
-    }
+    await expect(
+      page.locator('[data-label="application-name-input"]')
+    ).toBeVisible({ timeout: 10_000 });
 
     // Clear localStorage to ensure consent modal shows
     await page.evaluate(() => {
diff --git a/web/tests/e2e/fixtures/eeFeatures.ts b/web/tests/e2e/fixtures/eeFeatures.ts
new file mode 100644
index 00000000000..2141eeac88e
--- /dev/null
+++ b/web/tests/e2e/fixtures/eeFeatures.ts
@@ -0,0 +1,43 @@
+/**
+ * Playwright fixture that detects EE (Enterprise Edition) license state.
+ *
+ * Usage:
+ * ```ts
+ * import { test, expect } from "@tests/e2e/fixtures/eeFeatures";
+ *
+ * test("my EE-gated test", async ({ page, eeEnabled }) => {
+ *   test.skip(!eeEnabled, "Requires active Enterprise license");
+ *   // ... rest of test
+ * });
+ * ```
+ *
+ * The fixture:
+ * - Authenticates as admin
+ * - Fetches /api/settings to check ee_features_enabled
+ * - Provides a boolean to the test BEFORE any navigation happens
+ *
+ * This lets tests call test.skip() synchronously at the top, which is the
+ * correct Playwright pattern — never navigate then decide to skip.
+ */
+
+import { test as base, expect } from "@playwright/test";
+import { loginAs } from "@tests/e2e/utils/auth";
+
+export const test = base.extend<{
+  /** Whether EE features are enabled (valid enterprise license). */
+  eeEnabled: boolean;
+}>({
+  eeEnabled: async ({ page }, use) => {
+    await loginAs(page, "admin");
+    const res = await page.request.get("/api/settings");
+    if (!res.ok()) {
+      // Fail open — if we can't determine, assume EE is not enabled
+      await use(false);
+      return;
+    }
+    const settings = await res.json();
+    await use(settings.ee_features_enabled === true);
+  },
+});
+
+export { expect };

From ee181147390fbcf74975a69456c7fd99ef86ecd2 Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Thu, 5 Mar 2026 09:51:38 +0530
Subject: [PATCH 101/267] feat(table): add DataTable config-driven wrapper
 component (#9020)

Co-authored-by: Nik <nikolas.garza5@gmail.com>
---
 .../app/admin/demo/table-qualifier/page.tsx   | 190 --------
 .../refresh-components/table/DataTable.tsx    | 455 ++++++++++++++++++
 web/src/refresh-components/table/README.md    | 317 ++++++++++++
 3 files changed, 772 insertions(+), 190 deletions(-)
 delete mode 100644 web/src/app/admin/demo/table-qualifier/page.tsx
 create mode 100644 web/src/refresh-components/table/DataTable.tsx
 create mode 100644 web/src/refresh-components/table/README.md

diff --git a/web/src/app/admin/demo/table-qualifier/page.tsx b/web/src/app/admin/demo/table-qualifier/page.tsx
deleted file mode 100644
index 8649365cafc..00000000000
--- a/web/src/app/admin/demo/table-qualifier/page.tsx
+++ /dev/null
@@ -1,190 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import Text from "@/refresh-components/texts/Text";
-import TableQualifier from "@/refresh-components/table/TableQualifier";
-import { TableSizeProvider } from "@/refresh-components/table/TableSizeContext";
-import type { TableSize } from "@/refresh-components/table/TableSizeContext";
-import type { QualifierContentType } from "@/refresh-components/table/types";
-import { SvgCheckCircle } from "@opal/icons";
-
-// ---------------------------------------------------------------------------
-// Content type configurations
-// ---------------------------------------------------------------------------
-
-interface ContentConfig {
-  label: string;
-  content: QualifierContentType;
-  extraProps: Record<string, unknown>;
-}
-
-const CONTENT_TYPES: ContentConfig[] = [
-  {
-    label: "Simple",
-    content: "simple",
-    extraProps: {},
-  },
-  {
-    label: "Icon",
-    content: "icon",
-    extraProps: { icon: SvgCheckCircle },
-  },
-  {
-    label: "Image",
-    content: "image",
-    extraProps: {
-      imageSrc: "https://picsum.photos/36",
-      imageAlt: "Placeholder",
-    },
-  },
-  {
-    label: "Avatar Icon",
-    content: "avatar-icon",
-    extraProps: {},
-  },
-  {
-    label: "Avatar User",
-    content: "avatar-user",
-    extraProps: { initials: "AJ" },
-  },
-];
-
-// ---------------------------------------------------------------------------
-// Row of qualifier states for a single content type
-// ---------------------------------------------------------------------------
-
-interface QualifierRowProps {
-  config: ContentConfig;
-}
-
-function QualifierRow({ config }: QualifierRowProps) {
-  const [selectableSelected, setSelectableSelected] = useState(false);
-  const [permanentSelected, setPermanentSelected] = useState(true);
-
-  return (
-    <div className="space-y-2">
-      <Text mainUiAction text02>
-        {config.label}
-      </Text>
-
-      <div className="flex items-start gap-8">
-        {/* Default */}
-        <div className="flex w-20 flex-col items-center gap-2">
-          <TableQualifier
-            content={config.content}
-            selectable={false}
-            selected={false}
-            disabled={false}
-            {...config.extraProps}
-          />
-          <Text secondaryBody text04>
-            Default
-          </Text>
-        </div>
-
-        {/* Selectable (hover to reveal checkbox) */}
-        <div className="flex w-20 flex-col items-center gap-2">
-          <TableQualifier
-            content={config.content}
-            selectable={true}
-            selected={selectableSelected}
-            disabled={false}
-            onSelectChange={setSelectableSelected}
-            {...config.extraProps}
-          />
-          <Text secondaryBody text04>
-            Selectable
-          </Text>
-        </div>
-
-        {/* Selected */}
-        <div className="flex w-20 flex-col items-center gap-2">
-          <TableQualifier
-            content={config.content}
-            selectable={true}
-            selected={permanentSelected}
-            disabled={false}
-            onSelectChange={setPermanentSelected}
-            {...config.extraProps}
-          />
-          <Text secondaryBody text04>
-            Selected
-          </Text>
-        </div>
-
-        {/* Disabled (unselected) */}
-        <div className="flex w-20 flex-col items-center gap-2">
-          <TableQualifier
-            content={config.content}
-            selectable={true}
-            selected={false}
-            disabled={true}
-            {...config.extraProps}
-          />
-          <Text secondaryBody text04>
-            Disabled
-          </Text>
-        </div>
-
-        {/* Disabled (selected) */}
-        <div className="flex w-20 flex-col items-center gap-2">
-          <TableQualifier
-            content={config.content}
-            selectable={true}
-            selected={true}
-            disabled={true}
-            {...config.extraProps}
-          />
-          <Text secondaryBody text04>
-            Disabled+Sel
-          </Text>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Size section — all content types at a given size
-// ---------------------------------------------------------------------------
-
-interface SizeSectionProps {
-  size: TableSize;
-  title: string;
-}
-
-function SizeSection({ size, title }: SizeSectionProps) {
-  return (
-    <div className="space-y-6">
-      <Text headingH3>{title}</Text>
-      <TableSizeProvider size={size}>
-        <div className="flex flex-col gap-8">
-          {CONTENT_TYPES.map((config) => (
-            <QualifierRow key={`${size}-${config.content}`} config={config} />
-          ))}
-        </div>
-      </TableSizeProvider>
-    </div>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Page
-// ---------------------------------------------------------------------------
-
-export default function TableQualifierDemoPage() {
-  return (
-    <div className="p-6 space-y-10">
-      <div className="space-y-4">
-        <Text headingH2>TableQualifier Demo</Text>
-        <Text mainContentMuted text03>
-          All content types, sizes, and interactive states. Hover selectable
-          variants to reveal the checkbox; click to toggle.
-        </Text>
-      </div>
-
-      <SizeSection size="regular" title="Regular (36px)" />
-      <SizeSection size="small" title="Small (28px)" />
-    </div>
-  );
-}
diff --git a/web/src/refresh-components/table/DataTable.tsx b/web/src/refresh-components/table/DataTable.tsx
new file mode 100644
index 00000000000..9ed6f027015
--- /dev/null
+++ b/web/src/refresh-components/table/DataTable.tsx
@@ -0,0 +1,455 @@
+"use client";
+"use no memo";
+
+import { useMemo } from "react";
+import { flexRender } from "@tanstack/react-table";
+import useDataTable, {
+  toOnyxSortDirection,
+} from "@/refresh-components/table/hooks/useDataTable";
+import useColumnWidths from "@/refresh-components/table/hooks/useColumnWidths";
+import useDraggableRows from "@/refresh-components/table/hooks/useDraggableRows";
+import Table from "@/refresh-components/table/Table";
+import TableHeader from "@/refresh-components/table/TableHeader";
+import TableBody from "@/refresh-components/table/TableBody";
+import TableRow from "@/refresh-components/table/TableRow";
+import TableHead from "@/refresh-components/table/TableHead";
+import TableCell from "@/refresh-components/table/TableCell";
+import TableQualifier from "@/refresh-components/table/TableQualifier";
+import QualifierContainer from "@/refresh-components/table/QualifierContainer";
+import ActionsContainer from "@/refresh-components/table/ActionsContainer";
+import DragOverlayRow from "@/refresh-components/table/DragOverlayRow";
+import Footer from "@/refresh-components/table/Footer";
+import { TableSizeProvider } from "@/refresh-components/table/TableSizeContext";
+import { ColumnVisibilityPopover } from "@/refresh-components/table/ColumnVisibilityPopover";
+import { SortingPopover } from "@/refresh-components/table/SortingPopover";
+import type { WidthConfig } from "@/refresh-components/table/hooks/useColumnWidths";
+import type { ColumnDef } from "@tanstack/react-table";
+import type {
+  DataTableProps,
+  DataTableFooterConfig,
+  OnyxColumnDef,
+  OnyxDataColumn,
+  OnyxQualifierColumn,
+  OnyxActionsColumn,
+} from "@/refresh-components/table/types";
+import type { TableSize } from "@/refresh-components/table/TableSizeContext";
+
+const noopGetRowId = () => "";
+
+// ---------------------------------------------------------------------------
+// Internal: resolve size-dependent widths and build TanStack columns
+// ---------------------------------------------------------------------------
+
+interface ProcessedColumns<TData> {
+  tanstackColumns: ColumnDef<TData, any>[];
+  widthConfig: WidthConfig;
+  qualifierColumn: OnyxQualifierColumn<TData> | null;
+  /** Map from column ID → OnyxColumnDef for dispatch in render loops. */
+  columnKindMap: Map<string, OnyxColumnDef<TData>>;
+}
+
+function processColumns<TData>(
+  columns: OnyxColumnDef<TData>[],
+  size: TableSize
+): ProcessedColumns<TData> {
+  const tanstackColumns: ColumnDef<TData, any>[] = [];
+  const fixedColumnIds = new Set<string>();
+  const columnWeights: Record<string, number> = {};
+  const columnMinWidths: Record<string, number> = {};
+  const columnKindMap = new Map<string, OnyxColumnDef<TData>>();
+  let qualifierColumn: OnyxQualifierColumn<TData> | null = null;
+
+  for (const col of columns) {
+    const resolvedWidth =
+      typeof col.width === "function" ? col.width(size) : col.width;
+
+    // Clone def to avoid mutating the caller's column definitions
+    const clonedDef: ColumnDef<TData, any> = {
+      ...col.def,
+      id: col.id,
+      size:
+        "fixed" in resolvedWidth ? resolvedWidth.fixed : resolvedWidth.weight,
+    };
+
+    tanstackColumns.push(clonedDef);
+
+    const id = col.id;
+    columnKindMap.set(id, col);
+
+    if ("fixed" in resolvedWidth) {
+      fixedColumnIds.add(id);
+    } else {
+      columnWeights[id] = resolvedWidth.weight;
+      columnMinWidths[id] = resolvedWidth.minWidth ?? 50;
+    }
+
+    if (col.kind === "qualifier") qualifierColumn = col;
+  }
+
+  return {
+    tanstackColumns,
+    widthConfig: { fixedColumnIds, columnWeights, columnMinWidths },
+    qualifierColumn,
+    columnKindMap,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// DataTable component
+// ---------------------------------------------------------------------------
+
+/**
+ * Config-driven table component that wires together `useDataTable`,
+ * `useColumnWidths`, and `useDraggableRows` automatically.
+ *
+ * Full flexibility via the column definitions from `createTableColumns()`.
+ *
+ * @example
+ * ```tsx
+ * const tc = createTableColumns<TeamMember>();
+ * const columns = [
+ *   tc.qualifier({ content: "avatar-user", getInitials: (r) => r.initials }),
+ *   tc.column("name", { header: "Name", weight: 23, minWidth: 120 }),
+ *   tc.column("email", { header: "Email", weight: 28 }),
+ *   tc.actions(),
+ * ];
+ *
+ * <DataTable data={items} columns={columns} footer={{ mode: "selection" }} />
+ * ```
+ */
+export default function DataTable<TData>(props: DataTableProps<TData>) {
+  const {
+    data,
+    columns,
+    pageSize,
+    initialSorting,
+    initialColumnVisibility,
+    draggable,
+    footer,
+    size = "regular",
+    onRowClick,
+    height,
+    headerBackground,
+  } = props;
+
+  const effectivePageSize = pageSize ?? (footer ? 10 : data.length);
+
+  // 1. Process columns (memoized on columns + size)
+  const { tanstackColumns, widthConfig, qualifierColumn, columnKindMap } =
+    useMemo(() => processColumns(columns, size), [columns, size]);
+
+  // 2. Call useDataTable
+  const {
+    table,
+    currentPage,
+    totalPages,
+    totalItems,
+    setPage,
+    pageSize: resolvedPageSize,
+    selectionState,
+    selectedCount,
+    clearSelection,
+    toggleAllPageRowsSelected,
+    isAllPageRowsSelected,
+  } = useDataTable({
+    data,
+    columns: tanstackColumns,
+    pageSize: effectivePageSize,
+    initialSorting,
+    initialColumnVisibility,
+  });
+
+  // 3. Call useColumnWidths
+  const { containerRef, columnWidths, createResizeHandler } = useColumnWidths({
+    headers: table.getHeaderGroups()[0]?.headers ?? [],
+    ...widthConfig,
+  });
+
+  // 4. Call useDraggableRows (conditional)
+  const draggableReturn = useDraggableRows({
+    data,
+    getRowId: draggable?.getRowId ?? noopGetRowId,
+    enabled: !!draggable && table.getState().sorting.length === 0,
+    onReorder: draggable?.onReorder,
+  });
+
+  const hasDraggable = !!draggable;
+  const rowVariant = hasDraggable ? "table" : "list";
+
+  const isSelectable =
+    qualifierColumn != null && qualifierColumn.selectable !== false;
+
+  // ---------------------------------------------------------------------------
+  // Render
+  // ---------------------------------------------------------------------------
+
+  function renderContent() {
+    return (
+      <div>
+        <div
+          className="overflow-x-auto"
+          ref={containerRef}
+          style={{
+            ...(height != null
+              ? {
+                  maxHeight:
+                    typeof height === "number" ? `${height}px` : height,
+                  overflowY: "auto" as const,
+                }
+              : undefined),
+            ...(headerBackground
+              ? ({
+                  "--table-header-bg": headerBackground,
+                } as React.CSSProperties)
+              : undefined),
+          }}
+        >
+          <Table>
+            <TableHeader>
+              {table.getHeaderGroups().map((headerGroup) => (
+                <TableRow key={headerGroup.id}>
+                  {headerGroup.headers.map((header, headerIndex) => {
+                    const colDef = columnKindMap.get(header.id);
+
+                    // Qualifier header
+                    if (colDef?.kind === "qualifier") {
+                      if (qualifierColumn?.header === false) {
+                        return (
+                          <QualifierContainer key={header.id} type="head" />
+                        );
+                      }
+                      return (
+                        <QualifierContainer key={header.id} type="head">
+                          <TableQualifier
+                            content={
+                              qualifierColumn?.headerContentType ?? "simple"
+                            }
+                            selectable={isSelectable}
+                            selected={isSelectable && isAllPageRowsSelected}
+                            onSelectChange={
+                              isSelectable
+                                ? (checked) =>
+                                    toggleAllPageRowsSelected(checked)
+                                : undefined
+                            }
+                          />
+                        </QualifierContainer>
+                      );
+                    }
+
+                    // Actions header
+                    if (colDef?.kind === "actions") {
+                      const actionsDef = colDef as OnyxActionsColumn<TData>;
+                      return (
+                        <ActionsContainer key={header.id} type="head">
+                          {actionsDef.showColumnVisibility !== false && (
+                            <ColumnVisibilityPopover
+                              table={table}
+                              columnVisibility={
+                                table.getState().columnVisibility
+                              }
+                              size={size}
+                            />
+                          )}
+                          {actionsDef.showSorting !== false && (
+                            <SortingPopover
+                              table={table}
+                              sorting={table.getState().sorting}
+                              size={size}
+                              footerText={actionsDef.sortingFooterText}
+                            />
+                          )}
+                        </ActionsContainer>
+                      );
+                    }
+
+                    // Data / Display header
+                    const canSort = header.column.getCanSort();
+                    const sortDir = header.column.getIsSorted();
+                    const nextHeader = headerGroup.headers[headerIndex + 1];
+                    const canResize =
+                      header.column.getCanResize() &&
+                      !!nextHeader &&
+                      !widthConfig.fixedColumnIds.has(nextHeader.id);
+
+                    const dataCol =
+                      colDef?.kind === "data"
+                        ? (colDef as OnyxDataColumn<TData>)
+                        : null;
+
+                    return (
+                      <TableHead
+                        key={header.id}
+                        width={columnWidths[header.id]}
+                        sorted={
+                          canSort ? toOnyxSortDirection(sortDir) : undefined
+                        }
+                        onSort={
+                          canSort
+                            ? () => header.column.toggleSorting()
+                            : undefined
+                        }
+                        icon={dataCol?.icon}
+                        resizable={canResize}
+                        onResizeStart={
+                          canResize
+                            ? createResizeHandler(header.id, nextHeader.id)
+                            : undefined
+                        }
+                      >
+                        {flexRender(
+                          header.column.columnDef.header,
+                          header.getContext()
+                        )}
+                      </TableHead>
+                    );
+                  })}
+                </TableRow>
+              ))}
+            </TableHeader>
+
+            <TableBody
+              dndSortable={hasDraggable ? draggableReturn : undefined}
+              renderDragOverlay={
+                hasDraggable
+                  ? (activeId) => {
+                      const row = table
+                        .getRowModel()
+                        .rows.find(
+                          (r) => draggable!.getRowId(r.original) === activeId
+                        );
+                      if (!row) return null;
+                      return <DragOverlayRow row={row} variant={rowVariant} />;
+                    }
+                  : undefined
+              }
+            >
+              {table.getRowModel().rows.map((row) => {
+                const rowId = hasDraggable
+                  ? draggable!.getRowId(row.original)
+                  : undefined;
+
+                return (
+                  <TableRow
+                    key={row.id}
+                    variant={rowVariant}
+                    sortableId={rowId}
+                    selected={row.getIsSelected()}
+                    onClick={() => {
+                      if (onRowClick) {
+                        onRowClick(row.original);
+                      } else if (isSelectable) {
+                        row.toggleSelected();
+                      }
+                    }}
+                  >
+                    {row.getVisibleCells().map((cell) => {
+                      const cellColDef = columnKindMap.get(cell.column.id);
+
+                      // Qualifier cell
+                      if (cellColDef?.kind === "qualifier") {
+                        const qDef = cellColDef as OnyxQualifierColumn<TData>;
+                        return (
+                          <QualifierContainer
+                            key={cell.id}
+                            type="cell"
+                            onClick={(e) => e.stopPropagation()}
+                          >
+                            <TableQualifier
+                              content={qDef.content}
+                              initials={qDef.getInitials?.(row.original)}
+                              icon={qDef.getIcon?.(row.original)}
+                              imageSrc={qDef.getImageSrc?.(row.original)}
+                              selectable={isSelectable}
+                              selected={isSelectable && row.getIsSelected()}
+                              onSelectChange={
+                                isSelectable
+                                  ? (checked) => {
+                                      row.toggleSelected(checked);
+                                    }
+                                  : undefined
+                              }
+                            />
+                          </QualifierContainer>
+                        );
+                      }
+
+                      // Actions cell
+                      if (cellColDef?.kind === "actions") {
+                        return (
+                          <ActionsContainer key={cell.id} type="cell">
+                            {flexRender(
+                              cell.column.columnDef.cell,
+                              cell.getContext()
+                            )}
+                          </ActionsContainer>
+                        );
+                      }
+
+                      // Data / Display cell
+                      return (
+                        <TableCell key={cell.id}>
+                          {flexRender(
+                            cell.column.columnDef.cell,
+                            cell.getContext()
+                          )}
+                        </TableCell>
+                      );
+                    })}
+                  </TableRow>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </div>
+
+        {footer && renderFooter(footer)}
+      </div>
+    );
+  }
+
+  function renderFooter(footerConfig: DataTableFooterConfig) {
+    if (footerConfig.mode === "selection") {
+      return (
+        <Footer
+          mode="selection"
+          multiSelect={footerConfig.multiSelect !== false}
+          selectionState={selectionState}
+          selectedCount={selectedCount}
+          onClear={footerConfig.onClear ?? clearSelection}
+          onView={footerConfig.onView}
+          pageSize={resolvedPageSize}
+          totalItems={totalItems}
+          currentPage={currentPage}
+          totalPages={totalPages}
+          onPageChange={setPage}
+        />
+      );
+    }
+
+    // Summary mode
+    const rangeStart =
+      totalItems === 0
+        ? 0
+        : !isFinite(resolvedPageSize)
+          ? 1
+          : (currentPage - 1) * resolvedPageSize + 1;
+    const rangeEnd = !isFinite(resolvedPageSize)
+      ? totalItems
+      : Math.min(currentPage * resolvedPageSize, totalItems);
+
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={rangeStart}
+        rangeEnd={rangeEnd}
+        totalItems={totalItems}
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={setPage}
+      />
+    );
+  }
+
+  return <TableSizeProvider size={size}>{renderContent()}</TableSizeProvider>;
+}
diff --git a/web/src/refresh-components/table/README.md b/web/src/refresh-components/table/README.md
new file mode 100644
index 00000000000..f03e2e75491
--- /dev/null
+++ b/web/src/refresh-components/table/README.md
@@ -0,0 +1,317 @@
+# DataTable
+
+Config-driven table built on [TanStack Table](https://tanstack.com/table). Handles column sizing (weight-based proportional distribution), drag-and-drop row reordering, pagination, row selection, column visibility, and sorting out of the box.
+
+## Quick Start
+
+```tsx
+import DataTable from "@/refresh-components/table/DataTable";
+import { createTableColumns } from "@/refresh-components/table/columns";
+
+interface Person {
+  name: string;
+  email: string;
+  role: string;
+}
+
+// Define columns at module scope (stable reference, no re-renders)
+const tc = createTableColumns<Person>();
+const columns = [
+  tc.qualifier(),
+  tc.column("name", { header: "Name", weight: 30, minWidth: 120 }),
+  tc.column("email", { header: "Email", weight: 40, minWidth: 150 }),
+  tc.column("role", { header: "Role", weight: 30, minWidth: 80 }),
+  tc.actions(),
+];
+
+function PeopleTable({ data }: { data: Person[] }) {
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      pageSize={10}
+      footer={{ mode: "selection" }}
+    />
+  );
+}
+```
+
+## Column Builder API
+
+`createTableColumns<TData>()` returns a typed builder with four methods. Each returns an `OnyxColumnDef<TData>` that you pass to the `columns` prop.
+
+### `tc.qualifier(config?)`
+
+Leading column for avatars, icons, images, or checkboxes.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `content` | `"simple" \| "icon" \| "image" \| "avatar-icon" \| "avatar-user"` | `"simple"` | Body row content type |
+| `headerContentType` | same as `content` | `"simple"` | Header row content type |
+| `getInitials` | `(row: TData) => string` | - | Extract initials (for `"avatar-user"`) |
+| `getIcon` | `(row: TData) => IconFunctionComponent` | - | Extract icon (for `"icon"` / `"avatar-icon"`) |
+| `getImageSrc` | `(row: TData) => string` | - | Extract image src (for `"image"`) |
+| `selectable` | `boolean` | `true` | Show selection checkboxes |
+| `header` | `boolean` | `true` | Render qualifier content in the header |
+
+Width is fixed: 56px at `"regular"` size, 40px at `"small"`.
+
+```ts
+tc.qualifier({
+  content: "avatar-user",
+  getInitials: (row) => row.initials,
+})
+```
+
+### `tc.column(accessor, config)`
+
+Data column with sorting, resizing, and hiding. The `accessor` is a type-safe deep key into `TData`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `header` | `string` | **required** | Column header label |
+| `cell` | `(value: TValue, row: TData) => ReactNode` | renders value as string | Custom cell renderer |
+| `enableSorting` | `boolean` | `true` | Allow sorting |
+| `enableResizing` | `boolean` | `true` | Allow column resize |
+| `enableHiding` | `boolean` | `true` | Allow hiding via actions popover |
+| `icon` | `(sorted: SortDirection) => IconFunctionComponent` | - | Override the sort indicator icon |
+| `weight` | `number` | `20` | Proportional width weight |
+| `minWidth` | `number` | `50` | Minimum width in pixels |
+
+```ts
+tc.column("email", {
+  header: "Email",
+  weight: 28,
+  minWidth: 150,
+  cell: (value) => <Content sizePreset="main-ui" variant="body" title={value} prominence="muted" />,
+})
+```
+
+### `tc.displayColumn(config)`
+
+Non-accessor column for custom content (e.g. computed values, action buttons per row).
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | **required** | Unique column ID |
+| `header` | `string` | - | Optional header label |
+| `cell` | `(row: TData) => ReactNode` | **required** | Cell renderer |
+| `width` | `ColumnWidth` | **required** | `{ weight, minWidth? }` or `{ fixed }` |
+| `enableHiding` | `boolean` | `true` | Allow hiding |
+
+```ts
+tc.displayColumn({
+  id: "fullName",
+  header: "Full Name",
+  cell: (row) => `${row.firstName} ${row.lastName}`,
+  width: { weight: 25, minWidth: 100 },
+})
+```
+
+### `tc.actions(config?)`
+
+Fixed-width column rendered at the trailing edge. Houses column visibility and sorting popovers in the header.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `showColumnVisibility` | `boolean` | `true` | Show the column visibility popover |
+| `showSorting` | `boolean` | `true` | Show the sorting popover |
+| `sortingFooterText` | `string` | - | Footer text inside the sorting popover |
+
+Width is fixed: 88px at `"regular"`, 20px at `"small"`.
+
+```ts
+tc.actions({
+  sortingFooterText: "Everyone will see agents in this order.",
+})
+```
+
+## DataTable Props
+
+`DataTableProps<TData>`:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `TData[]` | **required** | Row data |
+| `columns` | `OnyxColumnDef<TData>[]` | **required** | Columns from `createTableColumns()` |
+| `pageSize` | `number` | `10` (with footer) or `data.length` (without) | Rows per page. `Infinity` disables pagination |
+| `initialSorting` | `SortingState` | `[]` | TanStack sorting state |
+| `initialColumnVisibility` | `VisibilityState` | `{}` | Map of column ID to `false` to hide initially |
+| `draggable` | `DataTableDraggableConfig<TData>` | - | Enable drag-and-drop (see below) |
+| `footer` | `DataTableFooterConfig` | - | Footer mode (see below) |
+| `size` | `"regular" \| "small"` | `"regular"` | Table density variant |
+| `onRowClick` | `(row: TData) => void` | toggles selection | Called on row click, replaces default selection toggle |
+| `height` | `number \| string` | - | Max height for scrollable body (header stays pinned). `300` or `"50vh"` |
+| `headerBackground` | `string` | - | CSS color for the sticky header (prevents content showing through) |
+
+## Footer Config
+
+The `footer` prop accepts a discriminated union on `mode`.
+
+### Selection mode
+
+For tables with selectable rows. Shows a selection message + count pagination.
+
+```ts
+footer={{
+  mode: "selection",
+  multiSelect: true,        // default true
+  onView: () => { ... },    // optional "View" button
+  onClear: () => { ... },   // optional "Clear" button (falls back to default clearSelection)
+}}
+```
+
+### Summary mode
+
+For read-only tables. Shows "Showing X~Y of Z" + list pagination.
+
+```ts
+footer={{ mode: "summary" }}
+```
+
+## Draggable Config
+
+Enable drag-and-drop row reordering. DnD is automatically disabled when column sorting is active.
+
+```ts
+<DataTable
+  data={items}
+  columns={columns}
+  draggable={{
+    getRowId: (row) => row.id,
+    onReorder: (ids, changedOrders) => {
+      // ids: new ordered array of all row IDs
+      // changedOrders: { [id]: newIndex } for rows that moved
+      setItems(ids.map((id) => items.find((r) => r.id === id)!));
+    },
+  }}
+/>
+```
+
+| Option | Type | Description |
+|---|---|---|
+| `getRowId` | `(row: TData) => string` | Extract a unique string ID from each row |
+| `onReorder` | `(ids: string[], changedOrders: Record<string, number>) => void \| Promise<void>` | Called after a successful reorder |
+
+## Sizing
+
+The `size` prop (`"regular"` or `"small"`) affects:
+
+- Qualifier column width (56px vs 40px)
+- Actions column width (88px vs 20px)
+- Footer text styles and pagination size
+- All child components via `TableSizeContext`
+
+Column widths can be responsive to size using a function:
+
+```ts
+// In types.ts, width accepts:
+width: ColumnWidth | ((size: TableSize) => ColumnWidth)
+
+// Example (this is what qualifier/actions use internally):
+width: (size) => size === "small" ? { fixed: 40 } : { fixed: 56 }
+```
+
+### Width system
+
+Data columns use **weight-based proportional distribution**. A column with `weight: 40` gets twice the space of one with `weight: 20`. When the container is narrower than the sum of `minWidth` values, columns clamp to their minimums.
+
+Fixed columns (`{ fixed: N }`) take exactly N pixels and don't participate in proportional distribution.
+
+Resizing uses **splitter semantics**: dragging a column border grows that column and shrinks its neighbor by the same amount, keeping total width constant.
+
+## Advanced Examples
+
+### Scrollable table with pinned header
+
+```tsx
+<DataTable
+  data={allRows}
+  columns={columns}
+  height={300}
+  headerBackground="var(--background-tint-00)"
+/>
+```
+
+### Hidden columns on load
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  initialColumnVisibility={{ department: false, joinDate: false }}
+  footer={{ mode: "selection" }}
+/>
+```
+
+### Icon-based data column
+
+```tsx
+const STATUS_ICONS = {
+  active: SvgCheckCircle,
+  pending: SvgClock,
+  inactive: SvgAlertCircle,
+} as const;
+
+tc.column("status", {
+  header: "Status",
+  weight: 14,
+  minWidth: 80,
+  cell: (value) => (
+    <Content
+      sizePreset="main-ui"
+      variant="body"
+      icon={STATUS_ICONS[value]}
+      title={value.charAt(0).toUpperCase() + value.slice(1)}
+    />
+  ),
+})
+```
+
+### Non-selectable qualifier with icons
+
+```ts
+tc.qualifier({
+  content: "icon",
+  getIcon: (row) => row.icon,
+  selectable: false,
+  header: false,
+})
+```
+
+### Small variant in a bordered container
+
+```tsx
+<div className="border border-border-01 rounded-lg overflow-hidden">
+  <DataTable
+    data={data}
+    columns={columns}
+    size="small"
+    pageSize={10}
+    footer={{ mode: "selection" }}
+  />
+</div>
+```
+
+### Custom row click handler
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  onRowClick={(row) => router.push(`/users/${row.id}`)}
+/>
+```
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `DataTable.tsx` | Main component |
+| `columns.ts` | `createTableColumns` builder |
+| `types.ts` | All TypeScript interfaces |
+| `hooks/useDataTable.ts` | TanStack table wrapper hook |
+| `hooks/useColumnWidths.ts` | Weight-based width system |
+| `hooks/useDraggableRows.ts` | DnD hook (`@dnd-kit`) |
+| `Footer.tsx` | Selection / Summary footer modes |
+| `TableSizeContext.tsx` | Size context provider |

From 7eabfa125c628a39527c25aa0e0115f15c456744 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 4 Mar 2026 20:36:11 -0800
Subject: [PATCH 102/267] fix(fe): properly wrap copy and edit buttons on
 mobile (#9073)

---
 web/src/app/app/message/HumanMessage.tsx | 174 ++++++++++++-----------
 1 file changed, 90 insertions(+), 84 deletions(-)

diff --git a/web/src/app/app/message/HumanMessage.tsx b/web/src/app/app/message/HumanMessage.tsx
index f49f71d2ce1..3a5ab0447ac 100644
--- a/web/src/app/app/message/HumanMessage.tsx
+++ b/web/src/app/app/message/HumanMessage.tsx
@@ -1,11 +1,12 @@
 "use client";
 
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useMemo, useRef, useState } from "react";
 import { FileDescriptor } from "@/app/app/interfaces";
 import "katex/dist/katex.min.css";
 import MessageSwitcher from "@/app/app/message/MessageSwitcher";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
+import useScreenSize from "@/hooks/useScreenSize";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import { Button } from "@opal/components";
 import { SvgEdit } from "@opal/icons";
@@ -137,6 +138,7 @@ const HumanMessage = React.memo(function HumanMessage({
   const [content, setContent] = useState(initialContent);
 
   const [isEditing, setIsEditing] = useState(false);
+  const { isMobile } = useScreenSize();
 
   // Use nodeId for switching (finding position in siblings)
   const indexInSiblings = otherMessagesCanSwitchTo?.indexOf(nodeId);
@@ -168,100 +170,104 @@ const HumanMessage = React.memo(function HumanMessage({
     return undefined;
   };
 
+  const copyEditButton = useMemo(
+    () => (
+      <div className="flex flex-row flex-shrink px-1 opacity-0 group-hover:opacity-100 transition-opacity">
+        <CopyIconButton
+          getCopyText={() => content}
+          prominence="tertiary"
+          data-testid="HumanMessage/copy-button"
+        />
+        <Button
+          icon={SvgEdit}
+          prominence="tertiary"
+          tooltip="Edit"
+          onClick={() => setIsEditing(true)}
+          data-testid="HumanMessage/edit-button"
+        />
+      </div>
+    ),
+    [content]
+  );
+
   return (
     <div
       id="onyx-human-message"
       className="group flex flex-col justify-end w-full relative"
     >
       <FileDisplay alignBubble files={files || []} />
-      <div className="md:flex md:flex-wrap relative justify-end break-words">
-        {isEditing ? (
-          <MessageEditing
-            content={content}
-            onSubmitEdit={(editedContent) => {
-              // Don't update UI for edits that can't be persisted
-              if (messageId === undefined || messageId === null) {
-                setIsEditing(false);
-                return;
-              }
-              onEdit?.(editedContent, messageId);
-              setContent(editedContent);
+      {isEditing ? (
+        <MessageEditing
+          content={content}
+          onSubmitEdit={(editedContent) => {
+            // Don't update UI for edits that can't be persisted
+            if (messageId === undefined || messageId === null) {
               setIsEditing(false);
-            }}
-            onCancelEdit={() => setIsEditing(false)}
-          />
-        ) : (
-          <>
-            <div className="md:max-w-[37.5rem] flex basis-[100%] md:basis-auto justify-end md:order-1">
-              <div
-                className={
-                  "max-w-[30rem] md:max-w-[37.5rem] whitespace-break-spaces break-anywhere rounded-t-16 rounded-bl-16 bg-background-tint-02 py-2 px-3"
+              return;
+            }
+            onEdit?.(editedContent, messageId);
+            setContent(editedContent);
+            setIsEditing(false);
+          }}
+          onCancelEdit={() => setIsEditing(false)}
+        />
+      ) : (
+        <div className="flex justify-end">
+          {onEdit && !isMobile && copyEditButton}
+          <div className="md:max-w-[37.5rem]">
+            <div
+              className={
+                "max-w-[30rem] md:max-w-[37.5rem] whitespace-break-spaces break-anywhere rounded-t-16 rounded-bl-16 bg-background-tint-02 py-2 px-3"
+              }
+              onCopy={(e) => {
+                const selection = window.getSelection();
+                if (selection) {
+                  e.preventDefault();
+                  const text = selection
+                    .toString()
+                    .replace(/\n{2,}/g, "\n")
+                    .trim();
+                  e.clipboardData.setData("text/plain", text);
                 }
-                onCopy={(e) => {
-                  const selection = window.getSelection();
-                  if (selection) {
-                    e.preventDefault();
-                    const text = selection
-                      .toString()
-                      .replace(/\n{2,}/g, "\n")
-                      .trim();
-                    e.clipboardData.setData("text/plain", text);
-                  }
-                }}
+              }}
+            >
+              <Text
+                as="p"
+                className="inline-block align-middle"
+                mainContentBody
               >
-                <Text
-                  as="p"
-                  className="inline-block align-middle"
-                  mainContentBody
-                >
-                  {content}
-                </Text>
-              </div>
+                {content}
+              </Text>
             </div>
-            {onEdit && (
-              <div className="absolute md:relative right-0 z-content flex flex-row p-1 opacity-0 group-hover:opacity-100 transition-opacity">
-                <CopyIconButton
-                  getCopyText={() => content}
-                  prominence="tertiary"
-                  data-testid="HumanMessage/copy-button"
-                />
-                <Button
-                  icon={SvgEdit}
-                  prominence="tertiary"
-                  tooltip="Edit"
-                  onClick={() => setIsEditing(true)}
-                  data-testid="HumanMessage/edit-button"
-                />
-              </div>
-            )}
-          </>
-        )}
-        <div className="md:min-w-[100%] flex justify-end order-1 mt-1">
-          {currentMessageInd !== undefined &&
-            onMessageSelection &&
-            otherMessagesCanSwitchTo &&
-            otherMessagesCanSwitchTo.length > 1 && (
-              <MessageSwitcher
-                disableForStreaming={disableSwitchingForStreaming}
-                currentPage={currentMessageInd + 1}
-                totalPages={otherMessagesCanSwitchTo.length}
-                handlePrevious={() => {
-                  stopGenerating();
-                  const prevMessage = getPreviousMessage();
-                  if (prevMessage !== undefined) {
-                    onMessageSelection(prevMessage);
-                  }
-                }}
-                handleNext={() => {
-                  stopGenerating();
-                  const nextMessage = getNextMessage();
-                  if (nextMessage !== undefined) {
-                    onMessageSelection(nextMessage);
-                  }
-                }}
-              />
-            )}
+          </div>
         </div>
+      )}
+      <div className="flex justify-end pt-1">
+        {!isEditing && onEdit && isMobile && copyEditButton}
+        {currentMessageInd !== undefined &&
+          onMessageSelection &&
+          otherMessagesCanSwitchTo &&
+          otherMessagesCanSwitchTo.length > 1 && (
+            <MessageSwitcher
+              disableForStreaming={disableSwitchingForStreaming}
+              currentPage={currentMessageInd + 1}
+              totalPages={otherMessagesCanSwitchTo.length}
+              handlePrevious={() => {
+                stopGenerating();
+                const prevMessage = getPreviousMessage();
+                if (prevMessage !== undefined) {
+                  onMessageSelection(prevMessage);
+                }
+              }}
+              handleNext={() => {
+                stopGenerating();
+                const nextMessage = getNextMessage();
+                if (nextMessage !== undefined) {
+                  onMessageSelection(nextMessage);
+                }
+              }}
+            />
+          )}
       </div>
     </div>
   );

From 62ef6f59bb671213ed8551b272c18557482788d8 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 08:35:46 -0800
Subject: [PATCH 103/267] chore(playwright): screenshot tests for user settings
 pages (#9078)

---
 web/src/app/app/settings/layout.tsx           |  5 ++-
 web/tests/e2e/settings/settings_pages.spec.ts | 36 +++++++++++++++++++
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 web/tests/e2e/settings/settings_pages.spec.ts

diff --git a/web/src/app/app/settings/layout.tsx b/web/src/app/app/settings/layout.tsx
index 65777022a80..3db75168752 100644
--- a/web/src/app/app/settings/layout.tsx
+++ b/web/src/app/app/settings/layout.tsx
@@ -30,7 +30,10 @@ export default function Layout({ children }: LayoutProps) {
         <SettingsLayouts.Body>
           <div className="grid grid-cols-[auto_1fr]">
             {/* Left: Tab Navigation */}
-            <div className="flex flex-col px-2 w-[12.5rem]">
+            <div
+              data-testid="settings-left-tab-navigation"
+              className="flex flex-col px-2 w-[12.5rem]"
+            >
               <SidebarTab
                 href="/app/settings/general"
                 selected={pathname === "/app/settings/general"}
diff --git a/web/tests/e2e/settings/settings_pages.spec.ts b/web/tests/e2e/settings/settings_pages.spec.ts
new file mode 100644
index 00000000000..21d300baf89
--- /dev/null
+++ b/web/tests/e2e/settings/settings_pages.spec.ts
@@ -0,0 +1,36 @@
+import { expect, test } from "@playwright/test";
+import { THEMES, setThemeBeforeNavigation } from "@tests/e2e/utils/theme";
+import { expectScreenshot } from "@tests/e2e/utils/visualRegression";
+
+test.use({ storageState: "admin_auth.json" });
+
+for (const theme of THEMES) {
+  test.describe(`Settings pages (${theme} mode)`, () => {
+    test.beforeEach(async ({ page }) => {
+      await setThemeBeforeNavigation(page, theme);
+    });
+
+    test("should screenshot each settings tab", async ({ page }) => {
+      await page.goto("/app/settings");
+      await page.waitForLoadState("networkidle");
+
+      const nav = page.getByTestId("settings-left-tab-navigation");
+      const tabs = nav.locator("a");
+      const count = await tabs.count();
+
+      expect(count).toBeGreaterThan(0);
+      for (let i = 0; i < count; i++) {
+        const tab = tabs.nth(i);
+        const href = await tab.getAttribute("href");
+        const slug = href ? href.replace("/app/settings/", "") : `tab-${i}`;
+
+        await tab.click();
+        await page.waitForLoadState("networkidle");
+
+        await expectScreenshot(page, {
+          name: `settings-${theme}-${slug}`,
+        });
+      }
+    });
+  });
+}

From 8c5859ba4dfd32ae67991356b3110de2665cf2a5 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 10:29:15 -0800
Subject: [PATCH 104/267] fix(fe): disable projects modal button unless project
 is named (#9093)

---
 web/src/components/modals/CreateProjectModal.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/web/src/components/modals/CreateProjectModal.tsx b/web/src/components/modals/CreateProjectModal.tsx
index 9e3d8d8a791..9b9d4caef37 100644
--- a/web/src/components/modals/CreateProjectModal.tsx
+++ b/web/src/components/modals/CreateProjectModal.tsx
@@ -68,7 +68,9 @@ export default function CreateProjectModal({
             <Button prominence="secondary" onClick={() => modal.toggle(false)}>
               Cancel
             </Button>
-            <Button onClick={handleSubmit}>Create Project</Button>
+            <Button disabled={!projectName.trim()} onClick={handleSubmit}>
+              Create Project
+            </Button>
           </Modal.Footer>
         </Modal.Content>
       </Modal>

From 8247fdd45bcc622ba0eff1186f7371d414a2ca4f Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Thu, 5 Mar 2026 11:06:35 -0800
Subject: [PATCH 105/267] fix(llm): Handle Bedrock tool content in message
 history without toolConfig (#9063)

---
 backend/onyx/chat/llm_loop.py                 |  30 +--
 backend/onyx/llm/multi_llm.py                 | 111 ++++++++-
 backend/tests/unit/onyx/chat/test_llm_loop.py |  43 ----
 backend/tests/unit/onyx/llm/test_multi_llm.py | 215 ++++++++++++++++++
 4 files changed, 326 insertions(+), 73 deletions(-)

diff --git a/backend/onyx/chat/llm_loop.py b/backend/onyx/chat/llm_loop.py
index 66bd7e7a817..324baf5e00a 100644
--- a/backend/onyx/chat/llm_loop.py
+++ b/backend/onyx/chat/llm_loop.py
@@ -36,7 +36,6 @@
 from onyx.db.memory import update_memory_at_index
 from onyx.db.memory import UserMemoryContext
 from onyx.db.models import Persona
-from onyx.llm.constants import LlmProviderNames
 from onyx.llm.interfaces import LLM
 from onyx.llm.interfaces import LLMUserIdentity
 from onyx.llm.interfaces import ToolChoiceOptions
@@ -84,28 +83,6 @@ def _looks_like_xml_tool_call_payload(text: str | None) -> bool:
     )
 
 
-def _should_keep_bedrock_tool_definitions(
-    llm: object, simple_chat_history: list[ChatMessageSimple]
-) -> bool:
-    """Bedrock requires tool config when history includes toolUse/toolResult blocks."""
-    model_provider = getattr(getattr(llm, "config", None), "model_provider", None)
-    if model_provider not in {
-        LlmProviderNames.BEDROCK,
-        LlmProviderNames.BEDROCK_CONVERSE,
-    }:
-        return False
-
-    return any(
-        (
-            msg.message_type == MessageType.ASSISTANT
-            and msg.tool_calls
-            and len(msg.tool_calls) > 0
-        )
-        or msg.message_type == MessageType.TOOL_CALL_RESPONSE
-        for msg in simple_chat_history
-    )
-
-
 def _try_fallback_tool_extraction(
     llm_step_result: LlmStepResult,
     tool_choice: ToolChoiceOptions,
@@ -686,12 +663,7 @@ def run_llm_loop(
             elif out_of_cycles or ran_image_gen:
                 # Last cycle, no tools allowed, just answer!
                 tool_choice = ToolChoiceOptions.NONE
-                # Bedrock requires tool config in requests that include toolUse/toolResult history.
-                final_tools = (
-                    tools
-                    if _should_keep_bedrock_tool_definitions(llm, simple_chat_history)
-                    else []
-                )
+                final_tools = []
             else:
                 tool_choice = ToolChoiceOptions.AUTO
                 final_tools = tools
diff --git a/backend/onyx/llm/multi_llm.py b/backend/onyx/llm/multi_llm.py
index fc10b8a98f0..3c288fec895 100644
--- a/backend/onyx/llm/multi_llm.py
+++ b/backend/onyx/llm/multi_llm.py
@@ -92,6 +92,98 @@ def _prompt_to_dicts(prompt: LanguageModelInput) -> list[dict[str, Any]]:
     return [prompt.model_dump(exclude_none=True)]
 
 
+def _normalize_content(raw: Any) -> str:
+    """Normalize a message content field to a plain string.
+
+    Content can be a string, None, or a list of content-block dicts
+    (e.g. [{"type": "text", "text": "..."}]).
+    """
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        return "\n".join(
+            block.get("text", "") if isinstance(block, dict) else str(block)
+            for block in raw
+        )
+    return str(raw)
+
+
+def _strip_tool_content_from_messages(
+    messages: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Convert tool-related messages to plain text.
+
+    Bedrock's Converse API requires toolConfig when messages contain
+    toolUse/toolResult content blocks. When no tools are provided for the
+    current request, we must convert any tool-related history into plain text
+    to avoid the "toolConfig field must be defined" error.
+
+    This is the same approach used by _OllamaHistoryMessageFormatter.
+    """
+    result: list[dict[str, Any]] = []
+    for msg in messages:
+        role = msg.get("role")
+        tool_calls = msg.get("tool_calls")
+
+        if role == "assistant" and tool_calls:
+            # Convert structured tool calls to text representation
+            tool_call_lines = []
+            for tc in tool_calls:
+                func = tc.get("function", {})
+                name = func.get("name", "unknown")
+                args = func.get("arguments", "{}")
+                tc_id = tc.get("id", "")
+                tool_call_lines.append(
+                    f"[Tool Call] name={name} id={tc_id} args={args}"
+                )
+
+            existing_content = _normalize_content(msg.get("content"))
+            parts = (
+                [existing_content] + tool_call_lines
+                if existing_content
+                else tool_call_lines
+            )
+            new_msg = {
+                "role": "assistant",
+                "content": "\n".join(parts),
+            }
+            result.append(new_msg)
+
+        elif role == "tool":
+            # Convert tool response to user message with text content
+            tool_call_id = msg.get("tool_call_id", "")
+            content = _normalize_content(msg.get("content"))
+            tool_result_text = f"[Tool Result] id={tool_call_id}\n{content}"
+            # Merge into previous user message if it is also a converted
+            # tool result to avoid consecutive user messages (Bedrock requires
+            # strict user/assistant alternation).
+            if (
+                result
+                and result[-1]["role"] == "user"
+                and "[Tool Result]" in result[-1].get("content", "")
+            ):
+                result[-1]["content"] += "\n\n" + tool_result_text
+            else:
+                result.append({"role": "user", "content": tool_result_text})
+
+        else:
+            result.append(msg)
+
+    return result
+
+
+def _messages_contain_tool_content(messages: list[dict[str, Any]]) -> bool:
+    """Check if any messages contain tool-related content blocks."""
+    for msg in messages:
+        if msg.get("role") == "tool":
+            return True
+        if msg.get("role") == "assistant" and msg.get("tool_calls"):
+            return True
+    return False
+
+
 def _is_vertex_model_rejecting_output_config(model_name: str) -> bool:
     normalized_model_name = model_name.lower()
     return any(
@@ -404,13 +496,30 @@ def _completion(
                 else nullcontext()
             )
             with env_ctx:
+                messages = _prompt_to_dicts(prompt)
+
+                # Bedrock's Converse API requires toolConfig when messages
+                # contain toolUse/toolResult content blocks. When no tools are
+                # provided for this request but the history contains tool
+                # content from previous turns, strip it to plain text.
+                is_bedrock = self._model_provider in {
+                    LlmProviderNames.BEDROCK,
+                    LlmProviderNames.BEDROCK_CONVERSE,
+                }
+                if (
+                    is_bedrock
+                    and not tools
+                    and _messages_contain_tool_content(messages)
+                ):
+                    messages = _strip_tool_content_from_messages(messages)
+
                 response = litellm.completion(
                     mock_response=get_llm_mock_response() or MOCK_LLM_RESPONSE,
                     model=model,
                     base_url=self._api_base or None,
                     api_version=self._api_version or None,
                     custom_llm_provider=self._custom_llm_provider or None,
-                    messages=_prompt_to_dicts(prompt),
+                    messages=messages,
                     tools=tools,
                     tool_choice=tool_choice,
                     stream=stream,
diff --git a/backend/tests/unit/onyx/chat/test_llm_loop.py b/backend/tests/unit/onyx/chat/test_llm_loop.py
index 28c7b1e8297..daf86930e61 100644
--- a/backend/tests/unit/onyx/chat/test_llm_loop.py
+++ b/backend/tests/unit/onyx/chat/test_llm_loop.py
@@ -2,7 +2,6 @@
 
 import pytest
 
-from onyx.chat.llm_loop import _should_keep_bedrock_tool_definitions
 from onyx.chat.llm_loop import _try_fallback_tool_extraction
 from onyx.chat.llm_loop import construct_message_history
 from onyx.chat.models import ChatLoadedFile
@@ -14,22 +13,11 @@
 from onyx.chat.models import ToolCallSimple
 from onyx.configs.constants import MessageType
 from onyx.file_store.models import ChatFileType
-from onyx.llm.constants import LlmProviderNames
 from onyx.llm.interfaces import ToolChoiceOptions
 from onyx.server.query_and_chat.placement import Placement
 from onyx.tools.models import ToolCallKickoff
 
 
-class _StubConfig:
-    def __init__(self, model_provider: str) -> None:
-        self.model_provider = model_provider
-
-
-class _StubLLM:
-    def __init__(self, model_provider: str) -> None:
-        self.config = _StubConfig(model_provider=model_provider)
-
-
 def create_message(
     content: str, message_type: MessageType, token_count: int | None = None
 ) -> ChatMessageSimple:
@@ -946,37 +934,6 @@ def test_forgotten_metadata_persists_across_many_turns(self) -> None:
             assert "moby_dick.txt" in forgotten.message
 
 
-class TestBedrockToolConfigGuard:
-    def test_bedrock_with_tool_history_keeps_tool_definitions(self) -> None:
-        llm = _StubLLM(LlmProviderNames.BEDROCK)
-        history = [
-            create_message("Question", MessageType.USER, 5),
-            create_assistant_with_tool_call("tc_1", "search", 5),
-            create_tool_response("tc_1", "Tool output", 5),
-        ]
-
-        assert _should_keep_bedrock_tool_definitions(llm, history) is True
-
-    def test_bedrock_without_tool_history_does_not_keep_tool_definitions(self) -> None:
-        llm = _StubLLM(LlmProviderNames.BEDROCK)
-        history = [
-            create_message("Question", MessageType.USER, 5),
-            create_message("Answer", MessageType.ASSISTANT, 5),
-        ]
-
-        assert _should_keep_bedrock_tool_definitions(llm, history) is False
-
-    def test_non_bedrock_with_tool_history_does_not_keep_tool_definitions(self) -> None:
-        llm = _StubLLM(LlmProviderNames.OPENAI)
-        history = [
-            create_message("Question", MessageType.USER, 5),
-            create_assistant_with_tool_call("tc_1", "search", 5),
-            create_tool_response("tc_1", "Tool output", 5),
-        ]
-
-        assert _should_keep_bedrock_tool_definitions(llm, history) is False
-
-
 class TestFallbackToolExtraction:
     def _tool_defs(self) -> list[dict]:
         return [
diff --git a/backend/tests/unit/onyx/llm/test_multi_llm.py b/backend/tests/unit/onyx/llm/test_multi_llm.py
index 71c8f82abde..7b47d4f07c7 100644
--- a/backend/tests/unit/onyx/llm/test_multi_llm.py
+++ b/backend/tests/unit/onyx/llm/test_multi_llm.py
@@ -1214,3 +1214,218 @@ def run_llm(llm: LitellmLLM) -> None:
 
     # The env lock context manager should never have been called
     mock_env_lock.assert_not_called()
+
+
+# ---- Tests for Bedrock tool content stripping ----
+
+
+def test_messages_contain_tool_content_with_tool_role() -> None:
+    from onyx.llm.multi_llm import _messages_contain_tool_content
+
+    messages: list[dict[str, Any]] = [
+        {"role": "user", "content": "Hello"},
+        {"role": "assistant", "content": "I'll search for that."},
+        {"role": "tool", "content": "search results", "tool_call_id": "tc_1"},
+    ]
+    assert _messages_contain_tool_content(messages) is True
+
+
+def test_messages_contain_tool_content_with_tool_calls() -> None:
+    from onyx.llm.multi_llm import _messages_contain_tool_content
+
+    messages: list[dict[str, Any]] = [
+        {"role": "user", "content": "Hello"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "tc_1",
+                    "type": "function",
+                    "function": {"name": "search", "arguments": "{}"},
+                }
+            ],
+        },
+    ]
+    assert _messages_contain_tool_content(messages) is True
+
+
+def test_messages_contain_tool_content_without_tools() -> None:
+    from onyx.llm.multi_llm import _messages_contain_tool_content
+
+    messages: list[dict[str, Any]] = [
+        {"role": "user", "content": "Hello"},
+        {"role": "assistant", "content": "Hi there!"},
+    ]
+    assert _messages_contain_tool_content(messages) is False
+
+
+def test_strip_tool_content_converts_assistant_tool_calls_to_text() -> None:
+    from onyx.llm.multi_llm import _strip_tool_content_from_messages
+
+    messages: list[dict[str, Any]] = [
+        {"role": "user", "content": "Search for cats"},
+        {
+            "role": "assistant",
+            "content": "Let me search.",
+            "tool_calls": [
+                {
+                    "id": "tc_1",
+                    "type": "function",
+                    "function": {
+                        "name": "search",
+                        "arguments": '{"query": "cats"}',
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "content": "Found 3 results about cats.",
+            "tool_call_id": "tc_1",
+        },
+        {"role": "assistant", "content": "Here are the results."},
+    ]
+
+    result = _strip_tool_content_from_messages(messages)
+
+    assert len(result) == 4
+
+    # First message unchanged
+    assert result[0] == {"role": "user", "content": "Search for cats"}
+
+    # Assistant with tool calls → plain text
+    assert result[1]["role"] == "assistant"
+    assert "tool_calls" not in result[1]
+    assert "Let me search." in result[1]["content"]
+    assert "[Tool Call]" in result[1]["content"]
+    assert "search" in result[1]["content"]
+    assert "tc_1" in result[1]["content"]
+
+    # Tool response → user message
+    assert result[2]["role"] == "user"
+    assert "[Tool Result]" in result[2]["content"]
+    assert "tc_1" in result[2]["content"]
+    assert "Found 3 results about cats." in result[2]["content"]
+
+    # Final assistant message unchanged
+    assert result[3] == {"role": "assistant", "content": "Here are the results."}
+
+
+def test_strip_tool_content_handles_assistant_with_no_text_content() -> None:
+    from onyx.llm.multi_llm import _strip_tool_content_from_messages
+
+    messages: list[dict[str, Any]] = [
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "tc_1",
+                    "type": "function",
+                    "function": {"name": "search", "arguments": "{}"},
+                }
+            ],
+        },
+    ]
+
+    result = _strip_tool_content_from_messages(messages)
+    assert result[0]["role"] == "assistant"
+    assert "[Tool Call]" in result[0]["content"]
+    assert "tool_calls" not in result[0]
+
+
+def test_strip_tool_content_passes_through_non_tool_messages() -> None:
+    from onyx.llm.multi_llm import _strip_tool_content_from_messages
+
+    messages: list[dict[str, Any]] = [
+        {"role": "system", "content": "You are helpful."},
+        {"role": "user", "content": "Hello"},
+        {"role": "assistant", "content": "Hi!"},
+    ]
+
+    result = _strip_tool_content_from_messages(messages)
+    assert result == messages
+
+
+def test_strip_tool_content_handles_list_content_blocks() -> None:
+    from onyx.llm.multi_llm import _strip_tool_content_from_messages
+
+    messages: list[dict[str, Any]] = [
+        {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "Searching now."}],
+            "tool_calls": [
+                {
+                    "id": "tc_1",
+                    "type": "function",
+                    "function": {"name": "search", "arguments": "{}"},
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "content": [
+                {"type": "text", "text": "result A"},
+                {"type": "text", "text": "result B"},
+            ],
+            "tool_call_id": "tc_1",
+        },
+    ]
+
+    result = _strip_tool_content_from_messages(messages)
+
+    # Assistant: list content flattened + tool call appended
+    assert result[0]["role"] == "assistant"
+    assert "Searching now." in result[0]["content"]
+    assert "[Tool Call]" in result[0]["content"]
+    assert isinstance(result[0]["content"], str)
+
+    # Tool: list content flattened into user message
+    assert result[1]["role"] == "user"
+    assert "result A" in result[1]["content"]
+    assert "result B" in result[1]["content"]
+    assert isinstance(result[1]["content"], str)
+
+
+def test_strip_tool_content_merges_consecutive_tool_results() -> None:
+    """Bedrock requires strict user/assistant alternation. Multiple parallel
+    tool results must be merged into a single user message."""
+    from onyx.llm.multi_llm import _strip_tool_content_from_messages
+
+    messages: list[dict[str, Any]] = [
+        {"role": "user", "content": "weather and news?"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "tc_1",
+                    "type": "function",
+                    "function": {"name": "search_weather", "arguments": "{}"},
+                },
+                {
+                    "id": "tc_2",
+                    "type": "function",
+                    "function": {"name": "search_news", "arguments": "{}"},
+                },
+            ],
+        },
+        {"role": "tool", "content": "sunny 72F", "tool_call_id": "tc_1"},
+        {"role": "tool", "content": "headline news", "tool_call_id": "tc_2"},
+        {"role": "assistant", "content": "Here are the results."},
+    ]
+
+    result = _strip_tool_content_from_messages(messages)
+
+    # user, assistant (flattened), user (merged tool results), assistant
+    assert len(result) == 4
+    roles = [m["role"] for m in result]
+    assert roles == ["user", "assistant", "user", "assistant"]
+
+    # Both tool results merged into one user message
+    merged = result[2]["content"]
+    assert "tc_1" in merged
+    assert "sunny 72F" in merged
+    assert "tc_2" in merged
+    assert "headline news" in merged

From 8fd91b6e83358170bf0b5367000d0b84dd5adcf5 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 11:38:02 -0800
Subject: [PATCH 106/267] chore(devtools): `ods desktop` (#9100)

---
 tools/ods/cmd/desktop.go | 144 +++++++++++++++++++++++++++++++++++++++
 tools/ods/cmd/root.go    |   1 +
 2 files changed, 145 insertions(+)
 create mode 100644 tools/ods/cmd/desktop.go

diff --git a/tools/ods/cmd/desktop.go b/tools/ods/cmd/desktop.go
new file mode 100644
index 00000000000..f6f985c663c
--- /dev/null
+++ b/tools/ods/cmd/desktop.go
@@ -0,0 +1,144 @@
+package cmd
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+
+	"github.com/onyx-dot-app/onyx/tools/ods/internal/paths"
+)
+
+type desktopPackageJSON struct {
+	Scripts map[string]string `json:"scripts"`
+}
+
+// NewDesktopCommand creates a command that runs npm scripts from the desktop directory.
+func NewDesktopCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "desktop <script> [args...]",
+		Short: "Run desktop/package.json npm scripts",
+		Long:  desktopHelpDescription(),
+		Args:  cobra.MinimumNArgs(1),
+		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+			if len(args) > 0 {
+				return nil, cobra.ShellCompDirectiveNoFileComp
+			}
+			return desktopScriptNames(), cobra.ShellCompDirectiveNoFileComp
+		},
+		Run: func(cmd *cobra.Command, args []string) {
+			runDesktopScript(args)
+		},
+	}
+	cmd.Flags().SetInterspersed(false)
+
+	return cmd
+}
+
+func runDesktopScript(args []string) {
+	desktopDir, err := desktopDir()
+	if err != nil {
+		log.Fatalf("Failed to find desktop directory: %v", err)
+	}
+
+	scriptName := args[0]
+	scriptArgs := args[1:]
+	if len(scriptArgs) > 0 && scriptArgs[0] == "--" {
+		scriptArgs = scriptArgs[1:]
+	}
+
+	npmArgs := []string{"run", scriptName}
+	if len(scriptArgs) > 0 {
+		// npm requires "--" to forward flags to the underlying script.
+		npmArgs = append(npmArgs, "--")
+		npmArgs = append(npmArgs, scriptArgs...)
+	}
+	log.Debugf("Running in %s: npm %v", desktopDir, npmArgs)
+
+	desktopCmd := exec.Command("npm", npmArgs...)
+	desktopCmd.Dir = desktopDir
+	desktopCmd.Stdout = os.Stdout
+	desktopCmd.Stderr = os.Stderr
+	desktopCmd.Stdin = os.Stdin
+
+	if err := desktopCmd.Run(); err != nil {
+		// For wrapped commands, preserve the child process's exit code and
+		// avoid duplicating already-printed stderr output.
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			if code := exitErr.ExitCode(); code != -1 {
+				os.Exit(code)
+			}
+		}
+		log.Fatalf("Failed to run npm: %v", err)
+	}
+}
+
+func desktopScriptNames() []string {
+	scripts, err := loadDesktopScripts()
+	if err != nil {
+		return nil
+	}
+
+	names := make([]string, 0, len(scripts))
+	for name := range scripts {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+func desktopHelpDescription() string {
+	description := `Run npm scripts from desktop/package.json.
+
+Examples:
+  ods desktop dev
+  ods desktop build
+  ods desktop build:dmg`
+
+	scripts := desktopScriptNames()
+	if len(scripts) == 0 {
+		return description + "\n\nAvailable scripts: (unable to load)"
+	}
+
+	return description + "\n\nAvailable scripts:\n  " + strings.Join(scripts, "\n  ")
+}
+
+func loadDesktopScripts() (map[string]string, error) {
+	desktopDir, err := desktopDir()
+	if err != nil {
+		return nil, err
+	}
+
+	packageJSONPath := filepath.Join(desktopDir, "package.json")
+	data, err := os.ReadFile(packageJSONPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read %s: %w", packageJSONPath, err)
+	}
+
+	var pkg desktopPackageJSON
+	if err := json.Unmarshal(data, &pkg); err != nil {
+		return nil, fmt.Errorf("failed to parse %s: %w", packageJSONPath, err)
+	}
+
+	if pkg.Scripts == nil {
+		return nil, nil
+	}
+
+	return pkg.Scripts, nil
+}
+
+func desktopDir() (string, error) {
+	root, err := paths.GitRoot()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(root, "desktop"), nil
+}
diff --git a/tools/ods/cmd/root.go b/tools/ods/cmd/root.go
index e93f07284ca..d6b41ff2f81 100644
--- a/tools/ods/cmd/root.go
+++ b/tools/ods/cmd/root.go
@@ -50,6 +50,7 @@ func NewRootCommand() *cobra.Command {
 	cmd.AddCommand(NewPullCommand())
 	cmd.AddCommand(NewRunCICommand())
 	cmd.AddCommand(NewScreenshotDiffCommand())
+	cmd.AddCommand(NewDesktopCommand())
 	cmd.AddCommand(NewWebCommand())
 	cmd.AddCommand(NewWhoisCommand())
 

From fde0d44bc1396bc6caeabef879890122541f934f Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 12:24:57 -0800
Subject: [PATCH 107/267] chore(devtools): upgrade `ods` to go 1.26 (#9103)

---
 tools/ods/go.mod         | 4 ++--
 tools/ods/pyproject.toml | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tools/ods/go.mod b/tools/ods/go.mod
index 93ac5cd02fc..7ffcbc6a099 100644
--- a/tools/ods/go.mod
+++ b/tools/ods/go.mod
@@ -1,14 +1,14 @@
 module github.com/onyx-dot-app/onyx/tools/ods
 
-go 1.24.11
+go 1.26.0
 
 require (
 	github.com/sirupsen/logrus v1.9.3
 	github.com/spf13/cobra v1.10.1
+	github.com/spf13/pflag v1.0.9
 )
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/spf13/pflag v1.0.9 // indirect
 	golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 // indirect
 )
diff --git a/tools/ods/pyproject.toml b/tools/ods/pyproject.toml
index 642e9f0dc4e..6518359fa4f 100644
--- a/tools/ods/pyproject.toml
+++ b/tools/ods/pyproject.toml
@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling", "go-bin~=1.24.11", "manygo"]
+requires = ["hatchling", "go-bin~=1.26.0", "manygo"]
 build-backend = "hatchling.build"
 
 [project]

From 20a4dd32eb51a3155ffc944d52405126185feeef Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 12:37:51 -0800
Subject: [PATCH 108/267] chore(devtools): pull release branch and support PR #
 args (#9102)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 tools/ods/cmd/cherry-pick.go  | 76 +++++++++++++++++++++++++++++++----
 tools/ods/internal/git/git.go | 38 ++++++++++++++++++
 2 files changed, 107 insertions(+), 7 deletions(-)

diff --git a/tools/ods/cmd/cherry-pick.go b/tools/ods/cmd/cherry-pick.go
index 48e170ae329..2db18064c49 100644
--- a/tools/ods/cmd/cherry-pick.go
+++ b/tools/ods/cmd/cherry-pick.go
@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"regexp"
+	"strconv"
 	"strings"
 
 	log "github.com/sirupsen/logrus"
@@ -33,11 +34,15 @@ func NewCherryPickCommand() *cobra.Command {
 	opts := &CherryPickOptions{}
 
 	cmd := &cobra.Command{
-		Use:     "cherry-pick <commit-sha> [<commit-sha>...]",
+		Use:     "cherry-pick <commit-or-pr> [<commit-or-pr>...]",
 		Aliases: []string{"cp"},
-		Short:   "Cherry-pick one or more commits to a release branch",
+		Short:   "Cherry-pick one or more commits (or PRs) to a release branch",
 		Long: `Cherry-pick one or more commits to a release branch and create a PR.
 
+Arguments can be commit SHAs or GitHub PR numbers. A purely numeric argument
+with fewer than 6 digits is treated as a PR number and resolved to its merge
+commit automatically.
+
 This command will:
   1. Find the nearest stable version tag
   2. Fetch the corresponding release branch(es)
@@ -54,7 +59,8 @@ If a cherry-pick hits a merge conflict, resolve it manually, then run:
 Example usage:
 
 	$ ods cherry-pick foo123 bar456 --release 2.5 --release 2.6
-	$ ods cp foo123 --release 2.5`,
+	$ ods cp foo123 --release 2.5
+	$ ods cp 1234 --release 2.5   # cherry-pick merge commit of PR #1234`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			cont, _ := cmd.Flags().GetBool("continue")
 			if cont {
@@ -90,11 +96,12 @@ Example usage:
 func runCherryPick(cmd *cobra.Command, args []string, opts *CherryPickOptions) {
 	git.CheckGitHubCLI()
 
-	commitSHAs := args
+	// Resolve any PR numbers (e.g. "1234") to their merge commit SHAs
+	commitSHAs, labels := resolveArgs(args)
 	if len(commitSHAs) == 1 {
-		log.Debugf("Cherry-picking commit: %s", commitSHAs[0])
+		log.Debugf("Cherry-picking %s (%s)", labels[0], commitSHAs[0])
 	} else {
-		log.Debugf("Cherry-picking %d commits: %s", len(commitSHAs), strings.Join(commitSHAs, ", "))
+		log.Debugf("Cherry-picking %d commits: %s", len(commitSHAs), strings.Join(labels, ", "))
 	}
 
 	if opts.DryRun {
@@ -294,6 +301,11 @@ func runCherryPickContinue() {
 
 	log.Infof("Resuming cherry-pick (original branch: %s, releases: %v)", state.OriginalBranch, state.Releases)
 
+	// If a rebase is in progress (REBASE_HEAD exists), it must be resolved first
+	if git.IsRebaseInProgress() {
+		log.Fatal("A git rebase is in progress. Resolve it first:\n  To continue: git rebase --continue\n  To abort:    git rebase --abort\nThen re-run: ods cherry-pick --continue")
+	}
+
 	// If git cherry-pick is still in progress (CHERRY_PICK_HEAD exists), continue it
 	if git.IsCherryPickInProgress() {
 		log.Info("Continuing in-progress cherry-pick...")
@@ -327,6 +339,23 @@ func cherryPickToRelease(commitSHAs, commitMessages []string, branchSuffix, vers
 			return "", fmt.Errorf("failed to checkout existing hotfix branch: %w", err)
 		}
 
+		// Only rebase when the branch has no unique commits (pure fast-forward).
+		// If unique commits exist (e.g. after --continue resolved a cherry-pick
+		// conflict), rebasing would re-apply them and risk the same conflicts.
+		remoteRef := fmt.Sprintf("origin/%s", releaseBranch)
+		uniqueCount, err := git.CountUniqueCommits(hotfixBranch, remoteRef)
+		if err != nil {
+			log.Warnf("Could not determine unique commits, skipping rebase: %v", err)
+		} else if uniqueCount == 0 {
+			log.Infof("Rebasing %s onto %s", hotfixBranch, releaseBranch)
+			if err := git.RunCommand("rebase", "--quiet", remoteRef); err != nil {
+				_ = git.RunCommand("rebase", "--abort")
+				return "", fmt.Errorf("failed to rebase hotfix branch onto %s (rebase aborted, re-run to retry): %w", releaseBranch, err)
+			}
+		} else {
+			log.Infof("Branch %s has %d unique commit(s), skipping rebase", hotfixBranch, uniqueCount)
+		}
+
 		// Check which commits need to be cherry-picked
 		commitsToCherry := []string{}
 		for _, sha := range commitSHAs {
@@ -364,7 +393,6 @@ func cherryPickToRelease(commitSHAs, commitMessages []string, branchSuffix, vers
 		return "", nil
 	}
 
-	// Push the hotfix branch
 	log.Infof("Pushing hotfix branch: %s", hotfixBranch)
 	pushArgs := []string{"push", "-u", "origin", hotfixBranch}
 	if noVerify {
@@ -432,6 +460,40 @@ func performCherryPick(commitSHAs []string) error {
 	return nil
 }
 
+// isPRNumber returns true if the argument looks like a GitHub PR number
+// (purely numeric with fewer than 6 digits).
+func isPRNumber(arg string) bool {
+	if len(arg) == 0 || len(arg) >= 6 {
+		return false
+	}
+	n, err := strconv.Atoi(arg)
+	return err == nil && n > 0
+}
+
+// resolveArgs resolves arguments that may be PR numbers into commit SHAs.
+// Returns the resolved commit SHAs and a display-friendly label for logging
+// (e.g. "PR #1234" instead of raw SHA).
+func resolveArgs(args []string) (commitSHAs []string, labels []string) {
+	commitSHAs = make([]string, len(args))
+	labels = make([]string, len(args))
+	for i, arg := range args {
+		if isPRNumber(arg) {
+			log.Infof("Resolving PR #%s to merge commit...", arg)
+			sha, err := git.ResolvePRToMergeCommit(arg)
+			if err != nil {
+				log.Fatalf("Failed to resolve PR #%s: %v", arg, err)
+			}
+			log.Infof("PR #%s → %s", arg, sha)
+			commitSHAs[i] = sha
+			labels[i] = fmt.Sprintf("PR #%s", arg)
+		} else {
+			commitSHAs[i] = arg
+			labels[i] = arg
+		}
+	}
+	return commitSHAs, labels
+}
+
 // normalizeVersion ensures the version has a 'v' prefix
 func normalizeVersion(version string) string {
 	if !strings.HasPrefix(version, "v") {
diff --git a/tools/ods/internal/git/git.go b/tools/ods/internal/git/git.go
index 914ef902cc9..c46245ebaa0 100644
--- a/tools/ods/internal/git/git.go
+++ b/tools/ods/internal/git/git.go
@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	log "github.com/sirupsen/logrus"
@@ -173,6 +174,26 @@ func IsCherryPickInProgress() bool {
 	return cmd.Run() == nil
 }
 
+// CountUniqueCommits returns the number of commits on branch that are not on upstream.
+func CountUniqueCommits(branch, upstream string) (int, error) {
+	cmd := exec.Command("git", "rev-list", "--count", fmt.Sprintf("%s..%s", upstream, branch))
+	output, err := cmd.Output()
+	if err != nil {
+		return 0, fmt.Errorf("git rev-list --count failed: %w", err)
+	}
+	count, err := strconv.Atoi(strings.TrimSpace(string(output)))
+	if err != nil {
+		return 0, fmt.Errorf("failed to parse commit count: %w", err)
+	}
+	return count, nil
+}
+
+// IsRebaseInProgress checks if a rebase is currently in progress
+func IsRebaseInProgress() bool {
+	cmd := exec.Command("git", "rev-parse", "--verify", "--quiet", "REBASE_HEAD")
+	return cmd.Run() == nil
+}
+
 // HasStagedChanges checks if there are staged changes in the index
 func HasStagedChanges() bool {
 	cmd := exec.Command("git", "diff", "--quiet", "--cached")
@@ -216,6 +237,23 @@ func IsCommitAppliedOnBranch(commitSHA, branchName string) bool {
 	return false
 }
 
+// ResolvePRToMergeCommit resolves a GitHub PR number to its merge commit SHA
+func ResolvePRToMergeCommit(prNumber string) (string, error) {
+	cmd := exec.Command("gh", "pr", "view", prNumber, "--json", "mergeCommit", "--jq", ".mergeCommit.oid")
+	output, err := cmd.Output()
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			return "", fmt.Errorf("gh pr view failed: %w: %s", err, string(exitErr.Stderr))
+		}
+		return "", fmt.Errorf("gh pr view failed: %w", err)
+	}
+	sha := strings.TrimSpace(string(output))
+	if sha == "" || sha == "null" {
+		return "", fmt.Errorf("PR #%s has no merge commit (is it merged?)", prNumber)
+	}
+	return sha, nil
+}
+
 // RunCherryPickContinue runs git cherry-pick --continue --no-edit
 func RunCherryPickContinue() error {
 	return RunCommandVerboseOnError("cherry-pick", "--continue", "--no-edit")

From b5c873077e5ce71efcbab4941070ddd26f196013 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 13:04:51 -0800
Subject: [PATCH 109/267] chore(devtools): upgrade `ods`: 0.6.2->0.6.3 (#9105)

---
 backend/requirements/dev.txt |  2 +-
 pyproject.toml               |  2 +-
 uv.lock                      | 26 +++++++++++++++++---------
 3 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/backend/requirements/dev.txt b/backend/requirements/dev.txt
index 88c5f4065ce..95cf9792928 100644
--- a/backend/requirements/dev.txt
+++ b/backend/requirements/dev.txt
@@ -317,7 +317,7 @@ oauthlib==3.2.2
     # via
     #   kubernetes
     #   requests-oauthlib
-onyx-devtools==0.6.2
+onyx-devtools==0.6.3
     # via onyx
 openai==2.14.0
     # via
diff --git a/pyproject.toml b/pyproject.toml
index 5b3d8710e58..54c1cd43162 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -144,7 +144,7 @@ dev = [
     "matplotlib==3.10.8",
     "mypy-extensions==1.0.0",
     "mypy==1.13.0",
-    "onyx-devtools==0.6.2",
+    "onyx-devtools==0.6.3",
     "openapi-generator-cli==7.17.0",
     "pandas-stubs~=2.3.3",
     "pre-commit==3.2.2",
diff --git a/uv.lock b/uv.lock
index 951041b1bfe..006bf897571 100644
--- a/uv.lock
+++ b/uv.lock
@@ -756,12 +756,20 @@ sdist = { url = "https://files.pythonhosted.org/packages/92/88/b8527e1b00c1811db
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/90/543f556fcfcfa270713eef906b6352ab048e1e557afec12925c991dc93c2/caio-0.9.25-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:d6956d9e4a27021c8bd6c9677f3a59eb1d820cc32d0343cea7961a03b1371965", size = 36839, upload-time = "2025-12-26T15:21:40.267Z" },
     { url = "https://files.pythonhosted.org/packages/51/3b/36f3e8ec38dafe8de4831decd2e44c69303d2a3892d16ceda42afed44e1b/caio-0.9.25-cp311-cp311-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:bf84bfa039f25ad91f4f52944452a5f6f405e8afab4d445450978cd6241d1478", size = 80255, upload-time = "2025-12-26T15:22:20.271Z" },
+    { url = "https://files.pythonhosted.org/packages/df/ce/65e64867d928e6aff1b4f0e12dba0ef6d5bf412c240dc1df9d421ac10573/caio-0.9.25-cp311-cp311-manylinux_2_34_aarch64.whl", hash = "sha256:ae3d62587332bce600f861a8de6256b1014d6485cfd25d68c15caf1611dd1f7c", size = 80052, upload-time = "2026-03-04T22:08:20.402Z" },
+    { url = "https://files.pythonhosted.org/packages/46/90/e278863c47e14ec58309aa2e38a45882fbe67b4cc29ec9bc8f65852d3e45/caio-0.9.25-cp311-cp311-manylinux_2_34_x86_64.whl", hash = "sha256:fc220b8533dcf0f238a6b1a4a937f92024c71e7b10b5a2dfc1c73604a25709bc", size = 78273, upload-time = "2026-03-04T22:08:21.368Z" },
     { url = "https://files.pythonhosted.org/packages/d3/25/79c98ebe12df31548ba4eaf44db11b7cad6b3e7b4203718335620939083c/caio-0.9.25-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:fb7ff95af4c31ad3f03179149aab61097a71fd85e05f89b4786de0359dffd044", size = 36983, upload-time = "2025-12-26T15:21:36.075Z" },
     { url = "https://files.pythonhosted.org/packages/a3/2b/21288691f16d479945968a0a4f2856818c1c5be56881d51d4dac9b255d26/caio-0.9.25-cp312-cp312-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:97084e4e30dfa598449d874c4d8e0c8d5ea17d2f752ef5e48e150ff9d240cd64", size = 82012, upload-time = "2025-12-26T15:22:20.983Z" },
+    { url = "https://files.pythonhosted.org/packages/03/c4/8a1b580875303500a9c12b9e0af58cb82e47f5bcf888c2457742a138273c/caio-0.9.25-cp312-cp312-manylinux_2_34_aarch64.whl", hash = "sha256:4fa69eba47e0f041b9d4f336e2ad40740681c43e686b18b191b6c5f4c5544bfb", size = 81502, upload-time = "2026-03-04T22:08:22.381Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1c/0fe770b8ffc8362c48134d1592d653a81a3d8748d764bec33864db36319d/caio-0.9.25-cp312-cp312-manylinux_2_34_x86_64.whl", hash = "sha256:6bebf6f079f1341d19f7386db9b8b1f07e8cc15ae13bfdaff573371ba0575d69", size = 80200, upload-time = "2026-03-04T22:08:23.382Z" },
     { url = "https://files.pythonhosted.org/packages/31/57/5e6ff127e6f62c9f15d989560435c642144aa4210882f9494204bc892305/caio-0.9.25-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d6c2a3411af97762a2b03840c3cec2f7f728921ff8adda53d7ea2315a8563451", size = 36979, upload-time = "2025-12-26T15:21:35.484Z" },
     { url = "https://files.pythonhosted.org/packages/a3/9f/f21af50e72117eb528c422d4276cbac11fb941b1b812b182e0a9c70d19c5/caio-0.9.25-cp313-cp313-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0998210a4d5cd5cb565b32ccfe4e53d67303f868a76f212e002a8554692870e6", size = 81900, upload-time = "2025-12-26T15:22:21.919Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/12/c39ae2a4037cb10ad5eb3578eb4d5f8c1a2575c62bba675f3406b7ef0824/caio-0.9.25-cp313-cp313-manylinux_2_34_aarch64.whl", hash = "sha256:1a177d4777141b96f175fe2c37a3d96dec7911ed9ad5f02bac38aaa1c936611f", size = 81523, upload-time = "2026-03-04T22:08:25.187Z" },
+    { url = "https://files.pythonhosted.org/packages/22/59/f8f2e950eb4f1a5a3883e198dca514b9d475415cb6cd7b78b9213a0dd45a/caio-0.9.25-cp313-cp313-manylinux_2_34_x86_64.whl", hash = "sha256:9ed3cfb28c0e99fec5e208c934e5c157d0866aa9c32aa4dc5e9b6034af6286b7", size = 80243, upload-time = "2026-03-04T22:08:26.449Z" },
     { url = "https://files.pythonhosted.org/packages/69/ca/a08fdc7efdcc24e6a6131a93c85be1f204d41c58f474c42b0670af8c016b/caio-0.9.25-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:fab6078b9348e883c80a5e14b382e6ad6aabbc4429ca034e76e730cf464269db", size = 36978, upload-time = "2025-12-26T15:21:41.055Z" },
     { url = "https://files.pythonhosted.org/packages/5e/6c/d4d24f65e690213c097174d26eda6831f45f4734d9d036d81790a27e7b78/caio-0.9.25-cp314-cp314-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:44a6b58e52d488c75cfaa5ecaa404b2b41cc965e6c417e03251e868ecd5b6d77", size = 81832, upload-time = "2025-12-26T15:22:22.757Z" },
+    { url = "https://files.pythonhosted.org/packages/87/a4/e534cf7d2d0e8d880e25dd61e8d921ffcfe15bd696734589826f5a2df727/caio-0.9.25-cp314-cp314-manylinux_2_34_aarch64.whl", hash = "sha256:628a630eb7fb22381dd8e3c8ab7f59e854b9c806639811fc3f4310c6bd711d79", size = 81565, upload-time = "2026-03-04T22:08:27.483Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/ed/bf81aeac1d290017e5e5ac3e880fd56ee15e50a6d0353986799d1bc5cfd5/caio-0.9.25-cp314-cp314-manylinux_2_34_x86_64.whl", hash = "sha256:0ba16aa605ccb174665357fc729cf500679c2d94d5f1458a6f0d5ca48f2060a7", size = 80071, upload-time = "2026-03-04T22:08:28.751Z" },
     { url = "https://files.pythonhosted.org/packages/86/93/1f76c8d1bafe3b0614e06b2195784a3765bbf7b0a067661af9e2dd47fc33/caio-0.9.25-py3-none-any.whl", hash = "sha256:06c0bb02d6b929119b1cfbe1ca403c768b2013a369e2db46bfa2a5761cf82e40", size = 19087, upload-time = "2025-12-26T15:22:00.221Z" },
 ]
 
@@ -4655,7 +4663,7 @@ requires-dist = [
     { name = "numpy", marker = "extra == 'model-server'", specifier = "==2.4.1" },
     { name = "oauthlib", marker = "extra == 'backend'", specifier = "==3.2.2" },
     { name = "office365-rest-python-client", marker = "extra == 'backend'", specifier = "==2.6.2" },
-    { name = "onyx-devtools", marker = "extra == 'dev'", specifier = "==0.6.2" },
+    { name = "onyx-devtools", marker = "extra == 'dev'", specifier = "==0.6.3" },
     { name = "openai", specifier = "==2.14.0" },
     { name = "openapi-generator-cli", marker = "extra == 'dev'", specifier = "==7.17.0" },
     { name = "openinference-instrumentation", marker = "extra == 'backend'", specifier = "==0.1.42" },
@@ -4760,20 +4768,20 @@ requires-dist = [{ name = "onyx", extras = ["backend", "dev", "ee"], editable =
 
 [[package]]
 name = "onyx-devtools"
-version = "0.6.2"
+version = "0.6.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "fastapi" },
     { name = "openapi-generator-cli" },
 ]
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/cc/20/d9f6089616044b0fb6e097cbae82122de24f3acd97820be4868d5c28ee3f/onyx_devtools-0.6.2-py3-none-any.whl", hash = "sha256:e48d14695d39d62ec3247a4c76ea56604bc5fb635af84c4ff3e9628bcc67b4fb", size = 3785941, upload-time = "2026-02-25T22:33:43.585Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/f5/f754a717f6b011050eb52ef09895cfa2f048f567f4aa3d5e0f773657dea4/onyx_devtools-0.6.2-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:505f9910a04868ab62d99bb483dc37c9f4ad94fa80e6ac0e6a10b86351c31420", size = 3832182, upload-time = "2026-02-25T22:33:43.283Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/35/6e653398c62078e87ebb0d03dc944df6691d92ca427c92867309d2d803b7/onyx_devtools-0.6.2-py3-none-macosx_11_0_arm64.whl", hash = "sha256:edec98e3acc0fa22cf9102c2070409ea7bcf99d7ded72bd8cb184ece8171c36a", size = 3576948, upload-time = "2026-02-25T22:33:42.962Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/97/cff707c5c3d2acd714365b1023f0100676abc99816a29558319e8ef01d5f/onyx_devtools-0.6.2-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:97abab61216866cdccd8c0a7e27af328776083756ce4fb57c4bd723030449e3b", size = 3439359, upload-time = "2026-02-25T22:33:44.684Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/98/3b768d18e5599178834b966b447075626d224e048d6eb264d89d19abacb4/onyx_devtools-0.6.2-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:681b038ab6f1457409d14b2490782c7a8014fc0f0f1b9cd69bb2b7199f99aef1", size = 3785959, upload-time = "2026-02-25T22:33:44.342Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/38/9b047f9e61c14ccf22b8f386c7a57da3965f90737453f3a577a97da45cdf/onyx_devtools-0.6.2-py3-none-win_amd64.whl", hash = "sha256:a2063be6be104b50a7538cf0d26c7f7ab9159d53327dd6f3e91db05d793c95f3", size = 3878776, upload-time = "2026-02-25T22:33:45.229Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/0f/742f644bae84f5f8f7b500094a2f58da3ff8027fc739944622577e2e2850/onyx_devtools-0.6.2-py3-none-win_arm64.whl", hash = "sha256:00fb90a49a15c932b5cacf818b1b4918e5b5c574bde243dc1828b57690dd5046", size = 3501112, upload-time = "2026-02-25T22:33:41.512Z" },
+    { url = "https://files.pythonhosted.org/packages/84/e2/e7619722c3ccd18eb38100f776fb3dd6b4ae0fbbee09fca5af7c69a279b5/onyx_devtools-0.6.3-py3-none-any.whl", hash = "sha256:d3a5422945d9da12cafc185f64b39f6e727ee4cc92b37427deb7a38f9aad4966", size = 3945381, upload-time = "2026-03-05T20:39:25.896Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/09/513d2dabedc1e54ad4376830fc9b34a3d9c164bdbcdedfcdbb8b8154dc5a/onyx_devtools-0.6.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:efe300e9f3a2e7ae75f88a4f9e0a5c4c471478296cb1615b6a1f03d247582e13", size = 3978761, upload-time = "2026-03-05T20:39:28.822Z" },
+    { url = "https://files.pythonhosted.org/packages/39/41/e757602a0de032d74ed01c7ee57f30e57728fb9cd4f922f50d2affda3889/onyx_devtools-0.6.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:594066eed3f917cfab5a8c7eac3d4a210df30259f2049f664787749709345e19", size = 3665378, upload-time = "2026-03-05T20:44:22.696Z" },
+    { url = "https://files.pythonhosted.org/packages/33/1c/c93b65d0b32e202596a2647922a75c7011cb982f899ddfcfd171f792c58f/onyx_devtools-0.6.3-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:384ef66030b55c0fd68b3898782b5b4b868ff3de119569dfc8544e2ce534b98a", size = 3540890, upload-time = "2026-03-05T20:39:28.886Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/33/760eb656013f7f0cdff24570480d3dc4e52bbd8e6147ea1e8cf6fad7554f/onyx_devtools-0.6.3-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:82e218f3a49f64910c2c4c34d5dc12d1ea1520a27e0b0f6e4c0949ff9abaf0e1", size = 3945396, upload-time = "2026-03-05T20:39:34.323Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/eb/f54b3675c464df8a51194ff75afc97c2417659e3a209dc46948b47c28860/onyx_devtools-0.6.3-py3-none-win_amd64.whl", hash = "sha256:8af614ae7229290ef2417cb85270184a1e826ed9a3a34658da93851edb36df57", size = 4045936, upload-time = "2026-03-05T20:39:28.375Z" },
+    { url = "https://files.pythonhosted.org/packages/04/b8/5bee38e748f3d4b8ec935766224db1bbc1214c91092e5822c080fccd9130/onyx_devtools-0.6.3-py3-none-win_arm64.whl", hash = "sha256:717589db4b42528d33ae96f8006ee6aad3555034dcfee724705b6576be6a6ec4", size = 3608268, upload-time = "2026-03-05T20:39:28.731Z" },
 ]
 
 [[package]]

From 8afc283410dc16d13c566d6c24a4ce8ae52fe822 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Thu, 5 Mar 2026 13:18:21 -0800
Subject: [PATCH 110/267] fix(chrome-extension): open login in new tab when
 session expires (#9091)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 web/src/sections/AppHealthBanner.tsx | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/web/src/sections/AppHealthBanner.tsx b/web/src/sections/AppHealthBanner.tsx
index ae81abf27ef..8ceca78460e 100644
--- a/web/src/sections/AppHealthBanner.tsx
+++ b/web/src/sections/AppHealthBanner.tsx
@@ -13,6 +13,7 @@ import { usePathname, useRouter } from "next/navigation";
 import { SvgAlertTriangle, SvgLogOut } from "@opal/icons";
 import { Content } from "@opal/layouts";
 import { useCurrentUser } from "@/hooks/useCurrentUser";
+import { getExtensionContext } from "@/lib/extension/utils";
 
 export default function AppHealthBanner() {
   const router = useRouter();
@@ -39,7 +40,18 @@ export default function AppHealthBanner() {
   // Function to handle the "Log in" button click
   function handleLogin() {
     setShowLoggedOutModal(false);
-    router.push("/auth/login");
+    const { isExtension } = getExtensionContext();
+    if (isExtension) {
+      // In the Chrome extension, open login in a new tab so OAuth popups
+      // work correctly (the extension iframe has no navigable URL origin).
+      window.open(
+        window.location.origin + "/auth/login",
+        "_blank",
+        "noopener,noreferrer"
+      );
+    } else {
+      router.push("/auth/login");
+    }
   }
 
   // Function to set up expiration timeout

From 41713d42a23a768a4b929afeea43391139be04d5 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Thu, 5 Mar 2026 13:22:56 -0800
Subject: [PATCH 111/267] chore: upgrade golangci-lint to v2.10.1 for Go 1.26
 support (#9107)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .pre-commit-config.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c996ce2dc07..fca45fd4af6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -119,9 +119,10 @@ repos:
           ]
 
   - repo: https://github.com/golangci/golangci-lint
-    rev: 9f61b0f53f80672872fced07b6874397c3ed197b # frozen: v2.7.2
+    rev: 5d1e709b7be35cb2025444e19de266b056b7b7ee # frozen: v2.10.1
     hooks:
       - id: golangci-lint
+        language_version: "1.26.0"
         entry: bash -c "find tools/ -name go.mod -print0 | xargs -0 -I{} bash -c 'cd \"$(dirname {})\" && golangci-lint run ./...'"
 
   - repo: https://github.com/astral-sh/ruff-pre-commit

From 9d6ce26ea32906e59610ae29676c9e93271f4056 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 13:35:43 -0800
Subject: [PATCH 112/267] fix(fe): show modal body on Safari/desktop (#9035)

---
 web/src/app/app/settings/layout.tsx           | 10 +--
 web/src/layouts/general-layouts.tsx           |  2 +-
 web/src/refresh-components/Modal.tsx          | 10 ++-
 .../sections/modals/ShareChatSessionModal.tsx | 72 +++++++++----------
 web/tests/e2e/chat/share_chat.spec.ts         |  5 +-
 5 files changed, 47 insertions(+), 52 deletions(-)

diff --git a/web/src/app/app/settings/layout.tsx b/web/src/app/app/settings/layout.tsx
index 3db75168752..64a18095075 100644
--- a/web/src/app/app/settings/layout.tsx
+++ b/web/src/app/app/settings/layout.tsx
@@ -7,7 +7,7 @@ import SidebarTab from "@/refresh-components/buttons/SidebarTab";
 import { SvgSliders } from "@opal/icons";
 import { useUser } from "@/providers/UserProvider";
 import { useAuthType } from "@/lib/hooks";
-import { AuthType } from "@/lib/constants";
+import { Section } from "@/layouts/general-layouts";
 
 interface LayoutProps {
   children: React.ReactNode;
@@ -28,11 +28,11 @@ export default function Layout({ children }: LayoutProps) {
         <SettingsLayouts.Header icon={SvgSliders} title="Settings" separator />
 
         <SettingsLayouts.Body>
-          <div className="grid grid-cols-[auto_1fr]">
+          <Section flexDirection="row" alignItems="start" gap={1.5}>
             {/* Left: Tab Navigation */}
             <div
               data-testid="settings-left-tab-navigation"
-              className="flex flex-col px-2 w-[12.5rem]"
+              className="flex flex-col px-2 min-w-[12.5rem]"
             >
               <SidebarTab
                 href="/app/settings/general"
@@ -63,8 +63,8 @@ export default function Layout({ children }: LayoutProps) {
             </div>
 
             {/* Right: Tab Content */}
-            <div className="px-4">{children}</div>
-          </div>
+            {children}
+          </Section>
         </SettingsLayouts.Body>
       </SettingsLayouts.Root>
     </AppLayouts.Root>
diff --git a/web/src/layouts/general-layouts.tsx b/web/src/layouts/general-layouts.tsx
index e6c38662bae..7d399abba3b 100644
--- a/web/src/layouts/general-layouts.tsx
+++ b/web/src/layouts/general-layouts.tsx
@@ -35,7 +35,7 @@ export const widthClassmap: Record<Length, string> = {
 export const heightClassmap: Record<Length, string> = {
   auto: "h-auto",
   fit: "h-fit",
-  full: "h-full",
+  full: "h-full min-h-0",
 };
 
 /**
diff --git a/web/src/refresh-components/Modal.tsx b/web/src/refresh-components/Modal.tsx
index 30244982591..d35b3be28b0 100644
--- a/web/src/refresh-components/Modal.tsx
+++ b/web/src/refresh-components/Modal.tsx
@@ -515,10 +515,16 @@ const ModalBody = React.forwardRef<HTMLDivElement, ModalBodyProps>(
         ref={ref}
         className={cn(
           twoTone && "bg-background-tint-01",
-          "h-full min-h-0 overflow-y-auto w-full"
+          "flex-auto min-h-0 overflow-y-auto w-full"
         )}
       >
-        <Section padding={1} gap={1} alignItems="start" {...props}>
+        <Section
+          height="auto"
+          padding={1}
+          gap={1}
+          alignItems="start"
+          {...props}
+        >
           {children}
         </Section>
       </div>
diff --git a/web/src/sections/modals/ShareChatSessionModal.tsx b/web/src/sections/modals/ShareChatSessionModal.tsx
index 7ae3ac12520..5aa7c7ecca4 100644
--- a/web/src/sections/modals/ShareChatSessionModal.tsx
+++ b/web/src/sections/modals/ShareChatSessionModal.tsx
@@ -188,50 +188,42 @@ export default function ShareChatSessionModal({
           <Section
             justifyContent="start"
             alignItems="stretch"
-            gap={1}
             height="auto"
+            gap={0.12}
           >
-            <Section
-              justifyContent="start"
-              alignItems="stretch"
-              height="auto"
-              gap={0.12}
-            >
-              <PrivacyOption
-                icon={SvgLock}
-                title="Private"
-                description="Only you have access to this chat."
-                selected={selectedPrivacy === "private"}
-                onClick={() => setSelectedPrivacy("private")}
-                ariaLabel="share-modal-option-private"
-              />
-              <PrivacyOption
-                icon={SvgUsers}
-                title="Your Organization"
-                description="Anyone in your organization can view this chat."
-                selected={selectedPrivacy === "public"}
-                onClick={() => setSelectedPrivacy("public")}
-                ariaLabel="share-modal-option-public"
-              />
-            </Section>
+            <PrivacyOption
+              icon={SvgLock}
+              title="Private"
+              description="Only you have access to this chat."
+              selected={selectedPrivacy === "private"}
+              onClick={() => setSelectedPrivacy("private")}
+              ariaLabel="share-modal-option-private"
+            />
+            <PrivacyOption
+              icon={SvgUsers}
+              title="Your Organization"
+              description="Anyone in your organization can view this chat."
+              selected={selectedPrivacy === "public"}
+              onClick={() => setSelectedPrivacy("public")}
+              ariaLabel="share-modal-option-public"
+            />
+          </Section>
 
-            {isShared && (
-              <div aria-label="share-modal-link-input">
-                <InputTypeIn
-                  readOnly
-                  value={shareLink}
-                  rightSection={
-                    <CopyIconButton
-                      getCopyText={() => shareLink}
-                      tooltip="Copy link"
-                      size="sm"
-                      aria-label="share-modal-copy-link"
-                    />
-                  }
+          {isShared && (
+            <InputTypeIn
+              aria-label="share-modal-link-input"
+              readOnly
+              value={shareLink}
+              rightSection={
+                <CopyIconButton
+                  getCopyText={() => shareLink}
+                  tooltip="Copy link"
+                  size="sm"
+                  aria-label="share-modal-copy-link"
                 />
-              </div>
-            )}
-          </Section>
+              }
+            />
+          )}
         </Modal.Body>
         <Modal.Footer>
           {!isShared && (
diff --git a/web/tests/e2e/chat/share_chat.spec.ts b/web/tests/e2e/chat/share_chat.spec.ts
index 6890f9c93c2..0642b9cd2be 100644
--- a/web/tests/e2e/chat/share_chat.spec.ts
+++ b/web/tests/e2e/chat/share_chat.spec.ts
@@ -156,10 +156,7 @@ test.describe("Share Chat Session Modal", () => {
     expect(patchBody).toEqual({ sharing_status: "public" });
 
     const linkInput = dialog.locator('[aria-label="share-modal-link-input"]');
-    await expect(linkInput).toBeVisible({ timeout: 5000 });
-
-    const inputValue = await linkInput.locator("input").inputValue();
-    expect(inputValue).toContain("/app/shared/");
+    await expect(linkInput).toHaveValue(/\/app\/shared\//, { timeout: 5000 });
 
     await expect(submitButton).toHaveText("Copy Link");
     await expect(dialog.getByText("Chat shared")).toBeVisible();

From 7e3f7d01c26c2974ba7e7d00e0d406658d869ff1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 22:14:44 +0000
Subject: [PATCH 113/267] chore(deps): bump authlib from 1.6.6 to 1.6.7 (#9049)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt | 2 +-
 uv.lock                          | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index ef4196af65c..4f6740754df 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -65,7 +65,7 @@ attrs==25.4.0
     #   jsonschema
     #   referencing
     #   zeep
-authlib==1.6.6
+authlib==1.6.7
     # via fastmcp
 babel==2.17.0
     # via courlan
diff --git a/uv.lock b/uv.lock
index 006bf897571..2fe8908365e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -453,14 +453,14 @@ wheels = [
 
 [[package]]
 name = "authlib"
-version = "1.6.6"
+version = "1.6.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "cryptography" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/bb/9b/b1661026ff24bc641b76b78c5222d614776b0c085bcfdac9bd15a1cb4b35/authlib-1.6.6.tar.gz", hash = "sha256:45770e8e056d0f283451d9996fbb59b70d45722b45d854d58f32878d0a40c38e", size = 164894, upload-time = "2025-12-12T08:01:41.464Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/49/dc/ed1681bf1339dd6ea1ce56136bad4baabc6f7ad466e375810702b0237047/authlib-1.6.7.tar.gz", hash = "sha256:dbf10100011d1e1b34048c9d120e83f13b35d69a826ae762b93d2fb5aafc337b", size = 164950, upload-time = "2026-02-06T14:04:14.171Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/54/51/321e821856452f7386c4e9df866f196720b1ad0c5ea1623ea7399969ae3b/authlib-1.6.6-py2.py3-none-any.whl", hash = "sha256:7d9e9bc535c13974313a87f53e8430eb6ea3d1cf6ae4f6efcd793f2e949143fd", size = 244005, upload-time = "2025-12-12T08:01:40.209Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/00/3ed12264094ec91f534fae429945efbaa9f8c666f3aa7061cc3b2a26a0cd/authlib-1.6.7-py2.py3-none-any.whl", hash = "sha256:c637340d9a02789d2efa1d003a7437d10d3e565237bcb5fcbc6c134c7b95bab0", size = 244115, upload-time = "2026-02-06T14:04:12.141Z" },
 ]
 
 [[package]]

From 2d75b4b1f8c5c056cc15520240f6be9f1822df80 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 14:45:53 -0800
Subject: [PATCH 114/267] chore(deps): bump dompurify from 3.3.1 to 3.3.2 in
 /widget (#9106)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 widget/package-lock.json | 11 +++++++----
 widget/package.json      |  2 +-
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/widget/package-lock.json b/widget/package-lock.json
index f315662ff9b..cc1fd5f9034 100644
--- a/widget/package-lock.json
+++ b/widget/package-lock.json
@@ -8,7 +8,7 @@
       "name": "onyx-chat-widget",
       "version": "1.0.0",
       "dependencies": {
-        "dompurify": "^3.0.0",
+        "dompurify": "^3.3.2",
         "lit": "^3.1.0",
         "marked": "^12.0.0"
       },
@@ -860,10 +860,13 @@
       "license": "MIT"
     },
     "node_modules/dompurify": {
-      "version": "3.3.1",
-      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.3.1.tgz",
-      "integrity": "sha512-qkdCKzLNtrgPFP1Vo+98FRzJnBRGe4ffyCea9IwHB1fyxPOeNTHpLKYGd4Uk9xvNoH0ZoOjwZxNptyMwqrId1Q==",
+      "version": "3.3.2",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.3.2.tgz",
+      "integrity": "sha512-6obghkliLdmKa56xdbLOpUZ43pAR6xFy1uOrxBaIDjT+yaRuuybLjGS9eVBoSR/UPU5fq3OXClEHLJNGvbxKpQ==",
       "license": "(MPL-2.0 OR Apache-2.0)",
+      "engines": {
+        "node": ">=20"
+      },
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
       }
diff --git a/widget/package.json b/widget/package.json
index 820734abd9e..962e230e183 100644
--- a/widget/package.json
+++ b/widget/package.json
@@ -17,7 +17,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "dompurify": "^3.0.0",
+    "dompurify": "^3.3.2",
     "lit": "^3.1.0",
     "marked": "^12.0.0"
   },

From b02590d2b2cb78942ae7237c43ffadbddd8a0fb3 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 14:49:29 -0800
Subject: [PATCH 115/267] chore(deps): bump
 aws-actions/configure-aws-credentials from 5.1.1 to 6.0.0 (#8478)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/deployment.yml              | 40 +++++++++----------
 .github/workflows/pr-playwright-tests.yml     |  2 +-
 .../reusable-nightly-llm-provider-chat.yml    |  8 ++--
 .github/workflows/sandbox-deployment.yml      |  6 +--
 4 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
index ea8ad0fc290..3edfade16bb 100644
--- a/.github/workflows/deployment.yml
+++ b/.github/workflows/deployment.yml
@@ -213,7 +213,7 @@ jobs:
 
       - name: Configure AWS credentials
         if: startsWith(matrix.platform, 'macos-')
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -384,7 +384,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -458,7 +458,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -527,7 +527,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -597,7 +597,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -679,7 +679,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -756,7 +756,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -823,7 +823,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -896,7 +896,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -964,7 +964,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1034,7 +1034,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1107,7 +1107,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1176,7 +1176,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1246,7 +1246,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1326,7 +1326,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1400,7 +1400,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1465,7 +1465,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1520,7 +1520,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1580,7 +1580,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -1637,7 +1637,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
diff --git a/.github/workflows/pr-playwright-tests.yml b/.github/workflows/pr-playwright-tests.yml
index 7dceeda642d..8943f80a663 100644
--- a/.github/workflows/pr-playwright-tests.yml
+++ b/.github/workflows/pr-playwright-tests.yml
@@ -461,7 +461,7 @@ jobs:
       # --- Visual Regression Diff ---
       - name: Configure AWS credentials
         if: always()
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
diff --git a/.github/workflows/reusable-nightly-llm-provider-chat.yml b/.github/workflows/reusable-nightly-llm-provider-chat.yml
index 35b41116f50..ed4edb14b1e 100644
--- a/.github/workflows/reusable-nightly-llm-provider-chat.yml
+++ b/.github/workflows/reusable-nightly-llm-provider-chat.yml
@@ -73,7 +73,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -116,7 +116,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -158,7 +158,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -264,7 +264,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
diff --git a/.github/workflows/sandbox-deployment.yml b/.github/workflows/sandbox-deployment.yml
index 151addc2380..6add52b6894 100644
--- a/.github/workflows/sandbox-deployment.yml
+++ b/.github/workflows/sandbox-deployment.yml
@@ -110,7 +110,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -180,7 +180,7 @@ jobs:
           persist-credentials: false
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2
@@ -244,7 +244,7 @@ jobs:
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           aws-region: us-east-2

From 911f3439ea440dd6ad54cb72d81d2c16d78ba0b1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 14:50:06 -0800
Subject: [PATCH 116/267] chore(deps): bump helm/kind-action from 1.13.0 to
 1.14.0 (#8917)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pr-helm-chart-testing.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pr-helm-chart-testing.yml b/.github/workflows/pr-helm-chart-testing.yml
index 3bd8f53d6d1..a07fd3bcbb8 100644
--- a/.github/workflows/pr-helm-chart-testing.yml
+++ b/.github/workflows/pr-helm-chart-testing.yml
@@ -71,7 +71,7 @@ jobs:
 
       - name: Create kind cluster
         if: steps.list-changed.outputs.changed == 'true'
-        uses: helm/kind-action@92086f6be054225fa813e0a4b13787fc9088faab # ratchet:helm/kind-action@v1.13.0
+        uses: helm/kind-action@ef37e7f390d99f746eb8b610417061a60e82a6cc # ratchet:helm/kind-action@v1.14.0
 
       - name: Pre-install cluster status check
         if: steps.list-changed.outputs.changed == 'true'

From f88ce32bd4aca49731076d76aff88cf49578bafc Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 14:51:22 -0800
Subject: [PATCH 117/267] chore(deps): bump @hono/node-server from 1.19.9 to
 1.19.10 in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#9048)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../docker/templates/outputs/web/package-lock.json          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index b6591c03116..455ced3dcf3 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -961,9 +961,9 @@
       "license": "MIT"
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.9",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.9.tgz",
-      "integrity": "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==",
+      "version": "1.19.10",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.10.tgz",
+      "integrity": "sha512-hZ7nOssGqRgyV3FVVQdfi+U4q02uB23bpnYpdvNXkYTRRyWx84b7yf1ans+dnJ/7h41sGL3CeQTfO+ZGxuO+Iw==",
       "license": "MIT",
       "engines": {
         "node": ">=18.14.1"

From 108cde4f55c289f2a6849971d87ae7489126cad1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 15:13:00 -0800
Subject: [PATCH 118/267] chore(deps): bump j178/prek-action from 1.0.12 to
 1.1.1 (#8477)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 .github/workflows/pr-quality-checks.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pr-quality-checks.yml b/.github/workflows/pr-quality-checks.yml
index ac9a9bd36f5..8e6d57b9d83 100644
--- a/.github/workflows/pr-quality-checks.yml
+++ b/.github/workflows/pr-quality-checks.yml
@@ -38,9 +38,9 @@ jobs:
       - name: Install node dependencies
         working-directory: ./web
         run: npm ci
-      - uses: j178/prek-action@9d6a3097e0c1865ecce00cfb89fe80f2ee91b547 # ratchet:j178/prek-action@v1
+      - uses: j178/prek-action@0bb87d7f00b0c99306c8bcb8b8beba1eb581c037 # ratchet:j178/prek-action@v1
         with:
-          prek-version: '0.2.21'
+          prek-version: '0.3.4'
           extra-args: ${{ github.event_name == 'pull_request' && format('--from-ref {0} --to-ref {1}', github.event.pull_request.base.sha, github.event.pull_request.head.sha) || github.event_name == 'merge_group' && format('--from-ref {0} --to-ref {1}', github.event.merge_group.base_sha, github.event.merge_group.head_sha) || github.ref_name == 'main' && '--all-files' || '' }}
       - name: Check Actions
         uses: giner/check-actions@28d366c7cbbe235f9624a88aa31a628167eee28c # ratchet:giner/check-actions@v1.0.1

From 413fa85134c9d5b147e0cfee8c07f47ae1cab1d9 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 15:13:57 -0800
Subject: [PATCH 119/267] chore(deps): bump minimatch in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#8828)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../templates/outputs/web/package-lock.json   | 66 +++++++++----------
 1 file changed, 33 insertions(+), 33 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index 455ced3dcf3..3bd86d708db 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -1573,27 +1573,6 @@
         }
       }
     },
-    "node_modules/@isaacs/balanced-match": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/@isaacs/balanced-match/-/balanced-match-4.0.1.tgz",
-      "integrity": "sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==",
-      "license": "MIT",
-      "engines": {
-        "node": "20 || >=22"
-      }
-    },
-    "node_modules/@isaacs/brace-expansion": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/@isaacs/brace-expansion/-/brace-expansion-5.0.1.tgz",
-      "integrity": "sha512-WMz71T1JS624nWj2n2fnYAuPovhv7EUhk69R6i9dsVyzxt5eM3bjwvgk9L+APE1TRscGysAVMANkB0jh0LQZrQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@isaacs/balanced-match": "^4.0.1"
-      },
-      "engines": {
-        "node": "20 || >=22"
-      }
-    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -3855,6 +3834,27 @@
         "path-browserify": "^1.0.1"
       }
     },
+    "node_modules/@ts-morph/common/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/@ts-morph/common/node_modules/brace-expansion": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.3.tgz",
+      "integrity": "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==",
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/@ts-morph/common/node_modules/fast-glob": {
       "version": "3.3.3",
       "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz",
@@ -3884,15 +3884,15 @@
       }
     },
     "node_modules/@ts-morph/common/node_modules/minimatch": {
-      "version": "10.1.1",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.1.1.tgz",
-      "integrity": "sha512-enIvLvRAFZYXJzkCYG5RKmPfrFArdLv+R+lbQ53BmIMLIry74bjKzX6iHAm8WYamJkhSSEabrWN5D97XnKObjQ==",
+      "version": "10.2.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
+      "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
-        "@isaacs/brace-expansion": "^5.0.0"
+        "brace-expansion": "^5.0.2"
       },
       "engines": {
-        "node": "20 || >=22"
+        "node": "18 || 20 || >=22"
       },
       "funding": {
         "url": "https://github.com/sponsors/isaacs"
@@ -4234,13 +4234,13 @@
       }
     },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -8831,9 +8831,9 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {

From 45d77be4ebcc38c246179a8466aa1d27ba78db49 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 15:14:50 -0800
Subject: [PATCH 120/267] chore(deps): bump ajv in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#8655)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../templates/outputs/web/package-lock.json    | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index 3bd86d708db..3e8caa1a2c0 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -1659,9 +1659,9 @@
       }
     },
     "node_modules/@modelcontextprotocol/sdk/node_modules/ajv": {
-      "version": "8.17.1",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
-      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "license": "MIT",
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
@@ -4619,9 +4619,9 @@
       }
     },
     "node_modules/ajv": {
-      "version": "6.12.6",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
-      "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==",
+      "version": "6.14.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
+      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4653,9 +4653,9 @@
       }
     },
     "node_modules/ajv-formats/node_modules/ajv": {
-      "version": "8.17.1",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
-      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "license": "MIT",
       "dependencies": {
         "fast-deep-equal": "^3.1.3",

From 091f41fd1f201b74bbb9653d470161e62584ee06 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 22:54:42 +0000
Subject: [PATCH 121/267] chore(deps): bump google-cloud-aiplatform from
 1.121.0 to 1.133.0 (#8658)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt      | 13 +++++--------
 backend/requirements/dev.txt          | 13 +++++--------
 backend/requirements/ee.txt           | 16 ++++++----------
 backend/requirements/model_server.txt | 13 +++++--------
 pyproject.toml                        |  2 +-
 uv.lock                               | 17 ++++++++---------
 6 files changed, 30 insertions(+), 44 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 4f6740754df..94806b315ef 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -109,9 +109,7 @@ brotli==1.2.0
 bytecode==0.17.0
     # via ddtrace
 cachetools==6.2.2
-    # via
-    #   google-auth
-    #   py-key-value-aio
+    # via py-key-value-aio
 caio==0.9.25
     # via aiofile
 celery==5.5.1
@@ -190,6 +188,7 @@ courlan==1.3.2
 cryptography==46.0.5
     # via
     #   authlib
+    #   google-auth
     #   msal
     #   msoffcrypto-tool
     #   pdfminer-six
@@ -306,7 +305,7 @@ google-api-core==2.28.1
     #   google-cloud-storage
 google-api-python-client==2.86.0
     # via onyx
-google-auth==2.43.0
+google-auth==2.48.0
     # via
     #   google-api-core
     #   google-api-python-client
@@ -325,7 +324,7 @@ google-auth-httplib2==0.1.0
     #   onyx
 google-auth-oauthlib==1.0.0
     # via onyx
-google-cloud-aiplatform==1.121.0
+google-cloud-aiplatform==1.133.0
     # via onyx
 google-cloud-bigquery==3.38.0
     # via google-cloud-aiplatform
@@ -1002,9 +1001,7 @@ sendgrid==6.12.5
 sentry-sdk==2.14.0
     # via onyx
 shapely==2.0.6
-    # via
-    #   google-cloud-aiplatform
-    #   onyx
+    # via onyx
 shellingham==1.5.4
     # via typer
 simple-salesforce==1.12.6
diff --git a/backend/requirements/dev.txt b/backend/requirements/dev.txt
index 95cf9792928..dfde5cf6dfe 100644
--- a/backend/requirements/dev.txt
+++ b/backend/requirements/dev.txt
@@ -59,8 +59,6 @@ botocore==1.39.11
     #   s3transfer
 brotli==1.2.0
     # via onyx
-cachetools==6.2.2
-    # via google-auth
 celery-types==0.19.0
     # via onyx
 certifi==2025.11.12
@@ -100,7 +98,9 @@ comm==0.2.3
 contourpy==1.3.3
     # via matplotlib
 cryptography==46.0.5
-    # via pyjwt
+    # via
+    #   google-auth
+    #   pyjwt
 cycler==0.12.1
     # via matplotlib
 debugpy==1.8.17
@@ -152,7 +152,7 @@ google-api-core==2.28.1
     #   google-cloud-core
     #   google-cloud-resource-manager
     #   google-cloud-storage
-google-auth==2.43.0
+google-auth==2.48.0
     # via
     #   google-api-core
     #   google-cloud-aiplatform
@@ -162,7 +162,7 @@ google-auth==2.43.0
     #   google-cloud-storage
     #   google-genai
     #   kubernetes
-google-cloud-aiplatform==1.121.0
+google-cloud-aiplatform==1.133.0
     # via onyx
 google-cloud-bigquery==3.38.0
     # via google-cloud-aiplatform
@@ -311,7 +311,6 @@ numpy==2.4.1
     #   contourpy
     #   matplotlib
     #   pandas-stubs
-    #   shapely
     #   voyageai
 oauthlib==3.2.2
     # via
@@ -510,8 +509,6 @@ s3transfer==0.13.1
     # via boto3
 sentry-sdk==2.14.0
     # via onyx
-shapely==2.0.6
-    # via google-cloud-aiplatform
 six==1.17.0
     # via
     #   kubernetes
diff --git a/backend/requirements/ee.txt b/backend/requirements/ee.txt
index 3b89c50164b..17d0f85a3e3 100644
--- a/backend/requirements/ee.txt
+++ b/backend/requirements/ee.txt
@@ -53,8 +53,6 @@ botocore==1.39.11
     #   s3transfer
 brotli==1.2.0
     # via onyx
-cachetools==6.2.2
-    # via google-auth
 certifi==2025.11.12
     # via
     #   httpcore
@@ -79,7 +77,9 @@ colorama==0.4.6 ; sys_platform == 'win32'
     #   click
     #   tqdm
 cryptography==46.0.5
-    # via pyjwt
+    # via
+    #   google-auth
+    #   pyjwt
 decorator==5.2.1
     # via retry
 discord-py==2.4.0
@@ -111,7 +111,7 @@ google-api-core==2.28.1
     #   google-cloud-core
     #   google-cloud-resource-manager
     #   google-cloud-storage
-google-auth==2.43.0
+google-auth==2.48.0
     # via
     #   google-api-core
     #   google-cloud-aiplatform
@@ -121,7 +121,7 @@ google-auth==2.43.0
     #   google-cloud-storage
     #   google-genai
     #   kubernetes
-google-cloud-aiplatform==1.121.0
+google-cloud-aiplatform==1.133.0
     # via onyx
 google-cloud-bigquery==3.38.0
     # via google-cloud-aiplatform
@@ -221,9 +221,7 @@ multidict==6.7.0
     #   aiohttp
     #   yarl
 numpy==2.4.1
-    # via
-    #   shapely
-    #   voyageai
+    # via voyageai
 oauthlib==3.2.2
     # via
     #   kubernetes
@@ -345,8 +343,6 @@ s3transfer==0.13.1
     # via boto3
 sentry-sdk==2.14.0
     # via onyx
-shapely==2.0.6
-    # via google-cloud-aiplatform
 six==1.17.0
     # via
     #   kubernetes
diff --git a/backend/requirements/model_server.txt b/backend/requirements/model_server.txt
index 1190245a2f5..a69285e624c 100644
--- a/backend/requirements/model_server.txt
+++ b/backend/requirements/model_server.txt
@@ -57,8 +57,6 @@ botocore==1.39.11
     #   s3transfer
 brotli==1.2.0
     # via onyx
-cachetools==6.2.2
-    # via google-auth
 celery==5.5.1
     # via sentry-sdk
 certifi==2025.11.12
@@ -95,7 +93,9 @@ colorama==0.4.6 ; sys_platform == 'win32'
     #   click
     #   tqdm
 cryptography==46.0.5
-    # via pyjwt
+    # via
+    #   google-auth
+    #   pyjwt
 decorator==5.2.1
     # via retry
 discord-py==2.4.0
@@ -136,7 +136,7 @@ google-api-core==2.28.1
     #   google-cloud-core
     #   google-cloud-resource-manager
     #   google-cloud-storage
-google-auth==2.43.0
+google-auth==2.48.0
     # via
     #   google-api-core
     #   google-cloud-aiplatform
@@ -146,7 +146,7 @@ google-auth==2.43.0
     #   google-cloud-storage
     #   google-genai
     #   kubernetes
-google-cloud-aiplatform==1.121.0
+google-cloud-aiplatform==1.133.0
     # via onyx
 google-cloud-bigquery==3.38.0
     # via google-cloud-aiplatform
@@ -263,7 +263,6 @@ numpy==2.4.1
     #   onyx
     #   scikit-learn
     #   scipy
-    #   shapely
     #   transformers
     #   voyageai
 nvidia-cublas-cu12==12.8.4.1 ; platform_machine == 'x86_64' and sys_platform == 'linux'
@@ -452,8 +451,6 @@ sentry-sdk==2.14.0
     # via onyx
 setuptools==80.9.0 ; python_full_version >= '3.12'
     # via torch
-shapely==2.0.6
-    # via google-cloud-aiplatform
 six==1.17.0
     # via
     #   kubernetes
diff --git a/pyproject.toml b/pyproject.toml
index 54c1cd43162..941136d9735 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -11,7 +11,7 @@ dependencies = [
     "aioboto3==15.1.0",
     "cohere==5.6.1",
     "fastapi==0.133.1",
-    "google-cloud-aiplatform==1.121.0",
+    "google-cloud-aiplatform==1.133.0",
     "google-genai==1.52.0",
     "litellm==1.81.6",
     "openai==2.14.0",
diff --git a/uv.lock b/uv.lock
index 2fe8908365e..0b2cca147a2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2131,16 +2131,16 @@ wheels = [
 
 [[package]]
 name = "google-auth"
-version = "2.43.0"
+version = "2.48.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "cachetools" },
+    { name = "cryptography" },
     { name = "pyasn1-modules" },
     { name = "rsa" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/ff/ef/66d14cf0e01b08d2d51ffc3c20410c4e134a1548fc246a6081eae585a4fe/google_auth-2.43.0.tar.gz", hash = "sha256:88228eee5fc21b62a1b5fe773ca15e67778cb07dc8363adcb4a8827b52d81483", size = 296359, upload-time = "2025-11-06T00:13:36.587Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/0c/41/242044323fbd746615884b1c16639749e73665b718209946ebad7ba8a813/google_auth-2.48.0.tar.gz", hash = "sha256:4f7e706b0cd3208a3d940a19a822c37a476ddba5450156c3e6624a71f7c841ce", size = 326522, upload-time = "2026-01-26T19:22:47.157Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6f/d1/385110a9ae86d91cc14c5282c61fe9f4dc41c0b9f7d423c6ad77038c4448/google_auth-2.43.0-py2.py3-none-any.whl", hash = "sha256:af628ba6fa493f75c7e9dbe9373d148ca9f4399b5ea29976519e0a3848eddd16", size = 223114, upload-time = "2025-11-06T00:13:35.209Z" },
+    { url = "https://files.pythonhosted.org/packages/83/1d/d6466de3a5249d35e832a52834115ca9d1d0de6abc22065f049707516d47/google_auth-2.48.0-py3-none-any.whl", hash = "sha256:2e2a537873d449434252a9632c28bfc268b0adb1e53f9fb62afc5333a975903f", size = 236499, upload-time = "2026-01-26T19:22:45.099Z" },
 ]
 
 [[package]]
@@ -2172,7 +2172,7 @@ wheels = [
 
 [[package]]
 name = "google-cloud-aiplatform"
-version = "1.121.0"
+version = "1.133.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2186,12 +2186,11 @@ dependencies = [
     { name = "proto-plus" },
     { name = "protobuf" },
     { name = "pydantic" },
-    { name = "shapely" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b1/86/d1bad9a342122f0f5913cd8b7758ab340aac3f579cffb800d294da605a7c/google_cloud_aiplatform-1.121.0.tar.gz", hash = "sha256:65710396238fa461dbea9b2af9ed23f95458d70d9684e75519c7c9c1601ff308", size = 9705200, upload-time = "2025-10-15T20:27:59.262Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d4/be/31ce7fd658ddebafbe5583977ddee536b2bacc491ad10b5a067388aec66f/google_cloud_aiplatform-1.133.0.tar.gz", hash = "sha256:3a6540711956dd178daaab3c2c05db476e46d94ac25912b8cf4f59b00b058ae0", size = 9921309, upload-time = "2026-01-08T22:11:25.079Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/bd/f6/806b39f86f912133a3071ffa9ff99801a12868216069e26c83a48943116b/google_cloud_aiplatform-1.121.0-py2.py3-none-any.whl", hash = "sha256:1e7105dfd17963207e966550c9544264508efdfded29cf4924c5b86ff4a22efd", size = 8067568, upload-time = "2025-10-15T20:27:54.842Z" },
+    { url = "https://files.pythonhosted.org/packages/01/5b/ef74ff65aebb74eaba51078e33ddd897247ba0d1197fd5a7953126205519/google_cloud_aiplatform-1.133.0-py2.py3-none-any.whl", hash = "sha256:dfc81228e987ca10d1c32c7204e2131b3c8d6b7c8e0b4e23bf7c56816bc4c566", size = 8184595, upload-time = "2026-01-08T22:11:22.067Z" },
 ]
 
 [[package]]
@@ -4630,7 +4629,7 @@ requires-dist = [
     { name = "google-api-python-client", marker = "extra == 'backend'", specifier = "==2.86.0" },
     { name = "google-auth-httplib2", marker = "extra == 'backend'", specifier = "==0.1.0" },
     { name = "google-auth-oauthlib", marker = "extra == 'backend'", specifier = "==1.0.0" },
-    { name = "google-cloud-aiplatform", specifier = "==1.121.0" },
+    { name = "google-cloud-aiplatform", specifier = "==1.133.0" },
     { name = "google-genai", specifier = "==1.52.0" },
     { name = "hatchling", marker = "extra == 'dev'", specifier = "==1.28.0" },
     { name = "httpcore", marker = "extra == 'backend'", specifier = "==1.0.9" },

From c10ffbb46479bfb599c59288f2aa0269c0f7558c Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 15:54:25 -0800
Subject: [PATCH 122/267] fix(safari): chat background blur ignores text
 (#9111)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 web/src/hooks/useBrowserInfo.ts | 64 +++++++++++++++++++++++++++++++++
 web/src/layouts/app-layouts.tsx | 47 ++++++++++++++----------
 2 files changed, 92 insertions(+), 19 deletions(-)
 create mode 100644 web/src/hooks/useBrowserInfo.ts

diff --git a/web/src/hooks/useBrowserInfo.ts b/web/src/hooks/useBrowserInfo.ts
new file mode 100644
index 00000000000..e09123f8549
--- /dev/null
+++ b/web/src/hooks/useBrowserInfo.ts
@@ -0,0 +1,64 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export interface BrowserInfo {
+  isSafari: boolean;
+  isFirefox: boolean;
+  isChrome: boolean;
+  isChromium: boolean;
+  isEdge: boolean;
+  isOpera: boolean;
+  isIOS: boolean;
+  isMac: boolean;
+  isWindows: boolean;
+}
+
+const DEFAULT_BROWSER_INFO: BrowserInfo = {
+  isSafari: false,
+  isFirefox: false,
+  isChrome: false,
+  isChromium: false,
+  isEdge: false,
+  isOpera: false,
+  isIOS: false,
+  isMac: false,
+  isWindows: false,
+};
+
+export default function useBrowserInfo(): BrowserInfo {
+  const [browserInfo, setBrowserInfo] =
+    useState<BrowserInfo>(DEFAULT_BROWSER_INFO);
+  useEffect(() => {
+    const userAgent = window.navigator.userAgent;
+
+    const isEdge = /Edg/i.test(userAgent);
+    const isOpera = /OPR|Opera/i.test(userAgent);
+    const isFirefox = /Firefox|FxiOS/i.test(userAgent);
+    const isChrome = /Chrome|CriOS/i.test(userAgent) && !isEdge && !isOpera;
+    const isChromium = /Chromium/i.test(userAgent) || isChrome;
+    const isSafari =
+      /Safari/i.test(userAgent) &&
+      !isChromium &&
+      !isEdge &&
+      !isOpera &&
+      !isFirefox;
+    const isIOS = /iPhone|iPad|iPod/i.test(userAgent);
+    const isMac = /Macintosh|Mac OS X/i.test(userAgent);
+    const isWindows = /Win/i.test(userAgent);
+
+    setBrowserInfo({
+      isSafari,
+      isFirefox,
+      isChrome,
+      isChromium,
+      isEdge,
+      isOpera,
+      isIOS,
+      isMac,
+      isWindows,
+    });
+  }, []);
+
+  return browserInfo;
+}
diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index c15446dd006..266a791a2e5 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -64,6 +64,7 @@ import { AppMode, useAppMode } from "@/providers/AppModeProvider";
 import useAppFocus from "@/hooks/useAppFocus";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
+import useBrowserInfo from "@/hooks/useBrowserInfo";
 
 /**
  * App Header Component
@@ -527,8 +528,16 @@ function Root({ children, enableBackground }: AppRootProps) {
   const { hasBackground, appBackgroundUrl } = useAppBackground();
   const { resolvedTheme } = useTheme();
   const appFocus = useAppFocus();
+  const { isSafari } = useBrowserInfo();
   const isLightMode = resolvedTheme === "light";
   const showBackground = hasBackground && enableBackground;
+  const horizontalBlurMask = `linear-gradient(
+    to right,
+    transparent 0%,
+    black max(0%, calc(50% - 25rem)),
+    black min(100%, calc(50% + 25rem)),
+    transparent 100%
+  )`;
 
   return (
     /* NOTE: Some elements, markdown tables in particular, refer to this `@container` in order to
@@ -568,25 +577,25 @@ function Root({ children, enableBackground }: AppRootProps) {
       {showBackground && appFocus.isChat() && (
         <>
           <div className="absolute inset-0 backdrop-blur-[1px] pointer-events-none" />
-          <div
-            className="absolute z-0 inset-0 backdrop-blur-md transition-all duration-600 pointer-events-none"
-            style={{
-              maskImage: `linear-gradient(
-                to right,
-                transparent 0%,
-                black max(0%, calc(50% - 25rem)),
-                black min(100%, calc(50% + 25rem)),
-                transparent 100%
-              )`,
-              WebkitMaskImage: `linear-gradient(
-                to right,
-                transparent 0%,
-                black max(0%, calc(50% - 25rem)),
-                black min(100%, calc(50% + 25rem)),
-                transparent 100%
-              )`,
-            }}
-          />
+          {isSafari ? (
+            <div
+              className="absolute z-0 inset-0 bg-cover bg-center bg-fixed pointer-events-none"
+              style={{
+                backgroundImage: `url(${appBackgroundUrl})`,
+                filter: "blur(16px)",
+                maskImage: horizontalBlurMask,
+                WebkitMaskImage: horizontalBlurMask,
+              }}
+            />
+          ) : (
+            <div
+              className="absolute z-0 inset-0 backdrop-blur-md transition-all duration-600 pointer-events-none"
+              style={{
+                maskImage: horizontalBlurMask,
+                WebkitMaskImage: horizontalBlurMask,
+              }}
+            />
+          )}
         </>
       )}
 

From 192639a801b1c3948c37c465cc3ddcfcab943b76 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Thu, 5 Mar 2026 15:02:18 -0800
Subject: [PATCH 123/267] chore: bump recommended models (#9112)

---
 backend/onyx/llm/model_metadata_enrichments.json          | 4 ++++
 .../onyx/llm/well_known_providers/recommended-models.json | 8 ++++----
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/backend/onyx/llm/model_metadata_enrichments.json b/backend/onyx/llm/model_metadata_enrichments.json
index 4b6c2452dd4..654ee3ed9ab 100644
--- a/backend/onyx/llm/model_metadata_enrichments.json
+++ b/backend/onyx/llm/model_metadata_enrichments.json
@@ -2516,6 +2516,10 @@
     "model_vendor": "openai",
     "model_version": "2025-10-06"
   },
+  "gpt-5.4": {
+    "display_name": "GPT-5.4",
+    "model_vendor": "openai"
+  },
   "gpt-5.2-pro-2025-12-11": {
     "display_name": "GPT-5.2 Pro",
     "model_vendor": "openai",
diff --git a/backend/onyx/llm/well_known_providers/recommended-models.json b/backend/onyx/llm/well_known_providers/recommended-models.json
index ffce42f3279..17abd40804f 100644
--- a/backend/onyx/llm/well_known_providers/recommended-models.json
+++ b/backend/onyx/llm/well_known_providers/recommended-models.json
@@ -1,12 +1,12 @@
 {
   "version": "1.1",
-  "updated_at": "2026-02-05T00:00:00Z",
+  "updated_at": "2026-03-05T00:00:00Z",
   "providers": {
     "openai": {
-      "default_model": { "name": "gpt-5.2" },
+      "default_model": { "name": "gpt-5.4" },
       "additional_visible_models": [
-        { "name": "gpt-5-mini" },
-        { "name": "gpt-4.1" }
+        { "name": "gpt-5.4" },
+        { "name": "gpt-5.2" }
       ]
     },
     "anthropic": {

From 57349bdbd10fd54b3f2d9647258cc3eac02984ac Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Thu, 5 Mar 2026 15:21:38 -0800
Subject: [PATCH 124/267] chore: OnyxError cleanup (#9071)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 backend/ee/onyx/server/billing/api.py     | 6 +++++-
 backend/onyx/error_handling/exceptions.py | 5 +++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/backend/ee/onyx/server/billing/api.py b/backend/ee/onyx/server/billing/api.py
index 96aa3b4a0d0..cbeb0c4c6b6 100644
--- a/backend/ee/onyx/server/billing/api.py
+++ b/backend/ee/onyx/server/billing/api.py
@@ -246,7 +246,11 @@ async def get_billing_information(
         )
     except OnyxError as e:
         # Open circuit breaker on connection failures (self-hosted only)
-        if e.status_code in (502, 503, 504):
+        if e.status_code in (
+            OnyxErrorCode.BAD_GATEWAY.status_code,
+            OnyxErrorCode.SERVICE_UNAVAILABLE.status_code,
+            OnyxErrorCode.GATEWAY_TIMEOUT.status_code,
+        ):
             _open_billing_circuit()
         raise
 
diff --git a/backend/onyx/error_handling/exceptions.py b/backend/onyx/error_handling/exceptions.py
index 63338210c47..61c895791d7 100644
--- a/backend/onyx/error_handling/exceptions.py
+++ b/backend/onyx/error_handling/exceptions.py
@@ -48,10 +48,11 @@ def __init__(
         *,
         status_code_override: int | None = None,
     ) -> None:
+        resolved_message = message or error_code.code
+        super().__init__(resolved_message)
         self.error_code = error_code
-        self.message = message or error_code.code
+        self.message = resolved_message
         self._status_code_override = status_code_override
-        super().__init__(self.message)
 
     @property
     def status_code(self) -> int:

From f59aaa902d254b93bd49ac19b54ce283bbd3b7f4 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 15:58:07 -0800
Subject: [PATCH 125/267] chore(playwright): tighten how elements are hidden
 (#9117)

---
 web/tests/e2e/utils/visualRegression.ts | 28 +++++++++++++++----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/web/tests/e2e/utils/visualRegression.ts b/web/tests/e2e/utils/visualRegression.ts
index cedaab91850..0a568744bc8 100644
--- a/web/tests/e2e/utils/visualRegression.ts
+++ b/web/tests/e2e/utils/visualRegression.ts
@@ -165,11 +165,6 @@ export async function expectScreenshot(
     threshold,
   } = options;
 
-  // Wait for any in-flight CSS animations / transitions to settle so that
-  // screenshots are deterministic (e.g. slide-in card animations on the
-  // onboarding flow).
-  await waitForAnimations(page);
-
   // Merge default hide selectors with per-call selectors
   const allHideSelectors = [...DEFAULT_HIDE_SELECTORS, ...hide];
 
@@ -178,7 +173,10 @@ export async function expectScreenshot(
   if (allHideSelectors.length > 0) {
     styleHandle = await page.addStyleTag({
       content: allHideSelectors
-        .map((selector) => `${selector} { visibility: hidden !important; }`)
+        .map(
+          (selector) =>
+            `${selector} { visibility: hidden !important; opacity: 0 !important; pointer-events: none !important; }`
+        )
         .join("\n"),
     });
   }
@@ -190,6 +188,11 @@ export async function expectScreenshot(
       page.locator(selector)
     );
 
+    // Wait for any in-flight CSS animations / transitions to settle so that
+    // screenshots are deterministic (e.g. slide-in card animations on the
+    // onboarding flow).
+    await waitForAnimations(page);
+
     // Build the screenshot name array (Playwright expects string[])
     const nameArg = name ? [name + ".png"] : undefined;
 
@@ -253,10 +256,6 @@ export async function expectElementScreenshot(
 
   const page = locator.page();
 
-  // Wait for any in-flight CSS animations / transitions to settle so that
-  // element screenshots are deterministic (same reasoning as expectScreenshot).
-  await waitForAnimations(page);
-
   // Merge default hide selectors with per-call selectors
   const allHideSelectors = [...DEFAULT_HIDE_SELECTORS, ...hide];
 
@@ -265,7 +264,10 @@ export async function expectElementScreenshot(
   if (allHideSelectors.length > 0) {
     styleHandle = await page.addStyleTag({
       content: allHideSelectors
-        .map((selector) => `${selector} { visibility: hidden !important; }`)
+        .map(
+          (selector) =>
+            `${selector} { visibility: hidden !important; opacity: 0 !important; pointer-events: none !important; }`
+        )
         .join("\n"),
     });
   }
@@ -277,6 +279,10 @@ export async function expectElementScreenshot(
       page.locator(selector)
     );
 
+    // Wait for any in-flight CSS animations / transitions to settle so that
+    // element screenshots are deterministic (same reasoning as expectScreenshot).
+    await waitForAnimations(page);
+
     // Build the screenshot name array (Playwright expects string[])
     const nameArg = name ? [name + ".png"] : undefined;
 

From eced88fa7a93df1eb3b82aaba5134eca727e18e3 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 16:39:02 -0800
Subject: [PATCH 126/267] chore(tests): run golang tests in CI (#9118)

---
 .github/workflows/pr-golang-tests.yml | 56 +++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 .github/workflows/pr-golang-tests.yml

diff --git a/.github/workflows/pr-golang-tests.yml b/.github/workflows/pr-golang-tests.yml
new file mode 100644
index 00000000000..ae158482df3
--- /dev/null
+++ b/.github/workflows/pr-golang-tests.yml
@@ -0,0 +1,56 @@
+name: Golang Tests
+concurrency:
+  group: Golang-Tests-${{ github.workflow }}-${{ github.head_ref || github.event.workflow_run.head_branch || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  merge_group:
+  pull_request:
+    branches:
+      - main
+      - "release/**"
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions: {}
+
+env:
+  GO_VERSION: "1.26"
+
+jobs:
+  detect-modules:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      modules: ${{ steps.set-modules.outputs.modules }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
+        with:
+          persist-credentials: false
+      - id: set-modules
+        run: echo "modules=$(find . -name 'go.mod' -exec dirname {} \; | jq -Rc '[.,inputs]')" >> "$GITHUB_OUTPUT"
+
+  golang:
+    needs: detect-modules
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        modules: ${{ fromJSON(needs.detect-modules.outputs.modules) }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # zizmor: ignore[cache-poisoning]
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: "**/go.sum"
+
+      - run: go mod tidy
+        working-directory: ${{ matrix.modules }}
+      - run: git diff --exit-code go.mod go.sum
+        working-directory: ${{ matrix.modules }}
+
+      - run: go test ./...
+        working-directory: ${{ matrix.modules }}

From 23b3a0a6ae01887b72f99a0b74bd72689de6694a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 16:41:43 -0800
Subject: [PATCH 127/267] chore(deps): bump minimatch in /examples/widget
 (#8886)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 examples/widget/package-lock.json | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/examples/widget/package-lock.json b/examples/widget/package-lock.json
index d43e0223419..dc784394b7d 100644
--- a/examples/widget/package-lock.json
+++ b/examples/widget/package-lock.json
@@ -1868,13 +1868,13 @@
       }
     },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -5857,10 +5857,11 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
+      "license": "ISC",
       "dependencies": {
         "brace-expansion": "^1.1.7"
       },

From 5888f9d69f39750f93478c68e8ac042dda38dbe1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 5 Mar 2026 16:42:17 -0800
Subject: [PATCH 128/267] chore(deps): bump qs from 6.14.1 to 6.14.2 in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#8390)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../docker/templates/outputs/web/package-lock.json          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index 3e8caa1a2c0..adb3fd12c99 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -9699,9 +9699,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.14.1",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.1.tgz",
-      "integrity": "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==",
+      "version": "6.14.2",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.2.tgz",
+      "integrity": "sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==",
       "license": "BSD-3-Clause",
       "dependencies": {
         "side-channel": "^1.1.0"

From ba2a5a60e13d439ca2b6a9ffa7f04c0f9d16e1ff Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Thu, 5 Mar 2026 16:05:53 -0800
Subject: [PATCH 129/267] chore: Add docx preview depend (#9059)

---
 web/package-lock.json | 10 ++++++++++
 web/package.json      |  1 +
 2 files changed, 11 insertions(+)

diff --git a/web/package-lock.json b/web/package-lock.json
index 0e008b58454..61116c5771f 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -48,6 +48,7 @@
         "cmdk": "^1.0.0",
         "cookies-next": "^5.1.0",
         "date-fns": "^3.6.0",
+        "docx-preview": "^0.3.7",
         "favicon-fetch": "^1.0.0",
         "formik": "^2.2.9",
         "highlight.js": "^11.11.1",
@@ -7958,6 +7959,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/docx-preview": {
+      "version": "0.3.7",
+      "resolved": "https://registry.npmjs.org/docx-preview/-/docx-preview-0.3.7.tgz",
+      "integrity": "sha512-Lav69CTA/IYZPJTsKH7oYeoZjyg96N0wEJMNslGJnZJ+dMUZK85Lt5ASC79yUlD48ecWjuv+rkcmFt6EVPV0Xg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "jszip": ">=3.0.0"
+      }
+    },
     "node_modules/dom-accessibility-api": {
       "version": "0.6.3",
       "dev": true,
diff --git a/web/package.json b/web/package.json
index 4173006ad5d..12a26f67f50 100644
--- a/web/package.json
+++ b/web/package.json
@@ -64,6 +64,7 @@
     "cmdk": "^1.0.0",
     "cookies-next": "^5.1.0",
     "date-fns": "^3.6.0",
+    "docx-preview": "^0.3.7",
     "favicon-fetch": "^1.0.0",
     "formik": "^2.2.9",
     "highlight.js": "^11.11.1",

From 2b82743bf514071dadc8eb784d08d14fb32248c4 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Thu, 5 Mar 2026 17:07:56 -0800
Subject: [PATCH 130/267] feat: lm studio provider (#8253)

---
 backend/onyx/llm/constants.py                 |   4 +
 backend/onyx/llm/factory.py                   |  20 +-
 backend/onyx/llm/multi_llm.py                 |  17 +
 backend/onyx/llm/utils.py                     |   2 +-
 .../llm/well_known_providers/constants.py     |  11 +
 .../llm_provider_options.py                   |   3 +
 backend/onyx/server/manage/llm/api.py         | 118 +++++++
 backend/onyx/server/manage/llm/models.py      |  16 +
 backend/onyx/server/manage/llm/utils.py       |  17 +
 .../manage/llm/test_fetch_models_api.py       | 297 ++++++++++++++++++
 web/lib/opal/src/icons/index.ts               |   1 +
 web/lib/opal/src/icons/lm-studio.tsx          | 141 +++++++++
 web/public/lm_studio.png                      | Bin 0 -> 12829 bytes
 web/src/app/admin/configuration/llm/utils.ts  |  81 ++++-
 web/src/components/icons/icons.tsx            |   2 +
 web/src/interfaces/llm.ts                     |  18 ++
 web/src/lib/llmConfig/providers.ts            |   4 +
 .../admin/LLMConfigurationPage.tsx            |   8 +
 .../modals/llmConfig/LMStudioForm.tsx         | 284 +++++++++++++++++
 .../sections/modals/llmConfig/getModal.tsx    |   3 +
 .../forms/LMStudioOnboardingForm.tsx          | 292 +++++++++++++++++
 .../onboarding/forms/getOnboardingForm.tsx    |  16 +
 22 files changed, 1343 insertions(+), 12 deletions(-)
 create mode 100644 web/lib/opal/src/icons/lm-studio.tsx
 create mode 100644 web/public/lm_studio.png
 create mode 100644 web/src/sections/modals/llmConfig/LMStudioForm.tsx
 create mode 100644 web/src/sections/onboarding/forms/LMStudioOnboardingForm.tsx

diff --git a/backend/onyx/llm/constants.py b/backend/onyx/llm/constants.py
index 5480e4622be..aa5768479df 100644
--- a/backend/onyx/llm/constants.py
+++ b/backend/onyx/llm/constants.py
@@ -22,6 +22,7 @@ class LlmProviderNames(str, Enum):
     OPENROUTER = "openrouter"
     AZURE = "azure"
     OLLAMA_CHAT = "ollama_chat"
+    LM_STUDIO = "lm_studio"
     MISTRAL = "mistral"
     LITELLM_PROXY = "litellm_proxy"
 
@@ -41,6 +42,7 @@ def __str__(self) -> str:
     LlmProviderNames.OPENROUTER,
     LlmProviderNames.AZURE,
     LlmProviderNames.OLLAMA_CHAT,
+    LlmProviderNames.LM_STUDIO,
 ]
 
 
@@ -56,6 +58,7 @@ def __str__(self) -> str:
     LlmProviderNames.AZURE: "Azure",
     "ollama": "Ollama",
     LlmProviderNames.OLLAMA_CHAT: "Ollama",
+    LlmProviderNames.LM_STUDIO: "LM Studio",
     "groq": "Groq",
     "anyscale": "Anyscale",
     "deepseek": "DeepSeek",
@@ -103,6 +106,7 @@ def __str__(self) -> str:
     LlmProviderNames.BEDROCK_CONVERSE,
     LlmProviderNames.OPENROUTER,
     LlmProviderNames.OLLAMA_CHAT,
+    LlmProviderNames.LM_STUDIO,
     LlmProviderNames.VERTEX_AI,
     LlmProviderNames.AZURE,
 }
diff --git a/backend/onyx/llm/factory.py b/backend/onyx/llm/factory.py
index 14ce113fa88..085a7c411f8 100644
--- a/backend/onyx/llm/factory.py
+++ b/backend/onyx/llm/factory.py
@@ -20,7 +20,9 @@
 from onyx.llm.override_models import LLMOverride
 from onyx.llm.utils import get_max_input_tokens_from_llm_provider
 from onyx.llm.utils import model_supports_image_input
-from onyx.llm.well_known_providers.constants import OLLAMA_API_KEY_CONFIG_KEY
+from onyx.llm.well_known_providers.constants import (
+    PROVIDERS_WITH_SPECIAL_API_KEY_HANDLING,
+)
 from onyx.natural_language_processing.utils import get_tokenizer
 from onyx.server.manage.llm.models import LLMProviderView
 from onyx.utils.headers import build_llm_extra_headers
@@ -32,14 +34,18 @@
 def _build_provider_extra_headers(
     provider: str, custom_config: dict[str, str] | None
 ) -> dict[str, str]:
-    if provider == LlmProviderNames.OLLAMA_CHAT and custom_config:
-        raw_api_key = custom_config.get(OLLAMA_API_KEY_CONFIG_KEY)
-        api_key = raw_api_key.strip() if raw_api_key else None
+    if provider in PROVIDERS_WITH_SPECIAL_API_KEY_HANDLING and custom_config:
+        raw = custom_config.get(PROVIDERS_WITH_SPECIAL_API_KEY_HANDLING[provider])
+        api_key = raw.strip() if raw else None
         if not api_key:
             return {}
-        if not api_key.lower().startswith("bearer "):
-            api_key = f"Bearer {api_key}"
-        return {"Authorization": api_key}
+        return {
+            "Authorization": (
+                api_key
+                if api_key.lower().startswith("bearer ")
+                else f"Bearer {api_key}"
+            )
+        }
 
     # Passing these will put Onyx on the OpenRouter leaderboard
     elif provider == LlmProviderNames.OPENROUTER:
diff --git a/backend/onyx/llm/multi_llm.py b/backend/onyx/llm/multi_llm.py
index 3c288fec895..9b2087b9a75 100644
--- a/backend/onyx/llm/multi_llm.py
+++ b/backend/onyx/llm/multi_llm.py
@@ -42,6 +42,7 @@
 from onyx.llm.well_known_providers.constants import (
     AWS_SECRET_ACCESS_KEY_KWARG_ENV_VAR_FORMAT,
 )
+from onyx.llm.well_known_providers.constants import LM_STUDIO_API_KEY_CONFIG_KEY
 from onyx.llm.well_known_providers.constants import OLLAMA_API_KEY_CONFIG_KEY
 from onyx.llm.well_known_providers.constants import VERTEX_CREDENTIALS_FILE_KWARG
 from onyx.llm.well_known_providers.constants import (
@@ -249,6 +250,9 @@ def __init__(
                 elif model_provider == LlmProviderNames.OLLAMA_CHAT:
                     if k == OLLAMA_API_KEY_CONFIG_KEY:
                         model_kwargs["api_key"] = v
+                elif model_provider == LlmProviderNames.LM_STUDIO:
+                    if k == LM_STUDIO_API_KEY_CONFIG_KEY:
+                        model_kwargs["api_key"] = v
                 elif model_provider == LlmProviderNames.BEDROCK:
                     if k == AWS_REGION_NAME_KWARG:
                         model_kwargs[k] = v
@@ -265,6 +269,19 @@ def __init__(
                     elif k == AWS_SECRET_ACCESS_KEY_KWARG_ENV_VAR_FORMAT:
                         model_kwargs[AWS_SECRET_ACCESS_KEY_KWARG] = v
 
+        # LM Studio: LiteLLM defaults to "fake-api-key" when no key is provided,
+        # which LM Studio rejects. Ensure we always pass an explicit key (or empty
+        # string) to prevent LiteLLM from injecting its fake default.
+        if model_provider == LlmProviderNames.LM_STUDIO:
+            model_kwargs.setdefault("api_key", "")
+
+            # Users provide the server root (e.g. http://localhost:1234) but LiteLLM
+            # needs /v1 for OpenAI-compatible calls.
+            if self._api_base is not None:
+                base = self._api_base.rstrip("/")
+                self._api_base = base if base.endswith("/v1") else f"{base}/v1"
+                model_kwargs["api_base"] = self._api_base
+
         # Default vertex_location to "global" if not provided for Vertex AI
         # Latest gemini models are only available through the global region
         if (
diff --git a/backend/onyx/llm/utils.py b/backend/onyx/llm/utils.py
index 86eb83970e4..c19a21a3a58 100644
--- a/backend/onyx/llm/utils.py
+++ b/backend/onyx/llm/utils.py
@@ -322,7 +322,7 @@ def test_llm(llm: LLM) -> str | None:
     error_msg = None
     for _ in range(2):
         try:
-            llm.invoke(UserMessage(content="Do not respond"))
+            llm.invoke(UserMessage(content="Do not respond"), max_tokens=50)
             return None
         except Exception as e:
             error_msg = str(e)
diff --git a/backend/onyx/llm/well_known_providers/constants.py b/backend/onyx/llm/well_known_providers/constants.py
index 2094ee4924c..ae023c72dbd 100644
--- a/backend/onyx/llm/well_known_providers/constants.py
+++ b/backend/onyx/llm/well_known_providers/constants.py
@@ -1,3 +1,5 @@
+from onyx.llm.constants import LlmProviderNames
+
 OPENAI_PROVIDER_NAME = "openai"
 # Curated list of OpenAI models to show by default in the UI
 OPENAI_VISIBLE_MODEL_NAMES = {
@@ -35,6 +37,15 @@ def _fallback_bedrock_regions() -> list[str]:
 OLLAMA_PROVIDER_NAME = "ollama_chat"
 OLLAMA_API_KEY_CONFIG_KEY = "OLLAMA_API_KEY"
 
+LM_STUDIO_PROVIDER_NAME = "lm_studio"
+LM_STUDIO_API_KEY_CONFIG_KEY = "LM_STUDIO_API_KEY"
+
+# Providers that use optional Bearer auth from custom_config
+PROVIDERS_WITH_SPECIAL_API_KEY_HANDLING: dict[str, str] = {
+    LlmProviderNames.OLLAMA_CHAT: OLLAMA_API_KEY_CONFIG_KEY,
+    LlmProviderNames.LM_STUDIO: LM_STUDIO_API_KEY_CONFIG_KEY,
+}
+
 # OpenRouter
 OPENROUTER_PROVIDER_NAME = "openrouter"
 
diff --git a/backend/onyx/llm/well_known_providers/llm_provider_options.py b/backend/onyx/llm/well_known_providers/llm_provider_options.py
index b5b95784450..535acab42d0 100644
--- a/backend/onyx/llm/well_known_providers/llm_provider_options.py
+++ b/backend/onyx/llm/well_known_providers/llm_provider_options.py
@@ -15,6 +15,7 @@
 from onyx.llm.well_known_providers.constants import ANTHROPIC_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import AZURE_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import BEDROCK_PROVIDER_NAME
+from onyx.llm.well_known_providers.constants import LM_STUDIO_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import OLLAMA_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import OPENAI_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import OPENROUTER_PROVIDER_NAME
@@ -44,6 +45,7 @@ def _get_provider_to_models_map() -> dict[str, list[str]]:
         ANTHROPIC_PROVIDER_NAME: get_anthropic_model_names(),
         VERTEXAI_PROVIDER_NAME: get_vertexai_model_names(),
         OLLAMA_PROVIDER_NAME: [],  # Dynamic - fetched from Ollama API
+        LM_STUDIO_PROVIDER_NAME: [],  # Dynamic - fetched from LM Studio API
         OPENROUTER_PROVIDER_NAME: [],  # Dynamic - fetched from OpenRouter API
     }
 
@@ -323,6 +325,7 @@ def get_provider_display_name(provider_name: str) -> str:
     _ONYX_PROVIDER_DISPLAY_NAMES: dict[str, str] = {
         OPENAI_PROVIDER_NAME: "ChatGPT (OpenAI)",
         OLLAMA_PROVIDER_NAME: "Ollama",
+        LM_STUDIO_PROVIDER_NAME: "LM Studio",
         ANTHROPIC_PROVIDER_NAME: "Claude (Anthropic)",
         AZURE_PROVIDER_NAME: "Azure OpenAI",
         BEDROCK_PROVIDER_NAME: "Amazon Bedrock",
diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index 6c7b0e8affe..8b2ad82e6c1 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -48,6 +48,7 @@
 from onyx.llm.well_known_providers.auto_update_service import (
     fetch_llm_recommendations_from_github,
 )
+from onyx.llm.well_known_providers.constants import LM_STUDIO_API_KEY_CONFIG_KEY
 from onyx.llm.well_known_providers.llm_provider_options import (
     fetch_available_well_known_llms,
 )
@@ -62,6 +63,8 @@
 from onyx.server.manage.llm.models import LLMProviderResponse
 from onyx.server.manage.llm.models import LLMProviderUpsertRequest
 from onyx.server.manage.llm.models import LLMProviderView
+from onyx.server.manage.llm.models import LMStudioFinalModelResponse
+from onyx.server.manage.llm.models import LMStudioModelsRequest
 from onyx.server.manage.llm.models import OllamaFinalModelResponse
 from onyx.server.manage.llm.models import OllamaModelDetails
 from onyx.server.manage.llm.models import OllamaModelsRequest
@@ -73,6 +76,7 @@
 from onyx.server.manage.llm.utils import generate_bedrock_display_name
 from onyx.server.manage.llm.utils import generate_ollama_display_name
 from onyx.server.manage.llm.utils import infer_vision_support
+from onyx.server.manage.llm.utils import is_reasoning_model
 from onyx.server.manage.llm.utils import is_valid_bedrock_model
 from onyx.server.manage.llm.utils import ModelMetadata
 from onyx.server.manage.llm.utils import strip_openrouter_vendor_prefix
@@ -1217,3 +1221,117 @@ def get_openrouter_available_models(
             logger.warning(f"Failed to sync OpenRouter models to DB: {e}")
 
     return sorted_results
+
+
+@admin_router.post("/lm-studio/available-models")
+def get_lm_studio_available_models(
+    request: LMStudioModelsRequest,
+    _: User = Depends(current_admin_user),
+    db_session: Session = Depends(get_session),
+) -> list[LMStudioFinalModelResponse]:
+    """Fetch available models from an LM Studio server.
+
+    Uses the LM Studio-native /api/v1/models endpoint which exposes
+    rich metadata including capabilities (vision, reasoning),
+    display names, and context lengths.
+    """
+    cleaned_api_base = request.api_base.strip().rstrip("/")
+    # Strip /v1 suffix that users may copy from OpenAI-compatible tool configs;
+    # the native metadata endpoint lives at /api/v1/models, not /v1/api/v1/models.
+    cleaned_api_base = cleaned_api_base.removesuffix("/v1")
+    if not cleaned_api_base:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "API base URL is required to fetch LM Studio models.",
+        )
+
+    # If provider_name is given and the api_key hasn't been changed by the user,
+    # fall back to the stored API key from the database (the form value is masked).
+    api_key = request.api_key
+    if request.provider_name and not request.api_key_changed:
+        existing_provider = fetch_existing_llm_provider(
+            name=request.provider_name, db_session=db_session
+        )
+        if existing_provider and existing_provider.custom_config:
+            api_key = existing_provider.custom_config.get(LM_STUDIO_API_KEY_CONFIG_KEY)
+
+    url = f"{cleaned_api_base}/api/v1/models"
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    try:
+        response = httpx.get(url, headers=headers, timeout=10.0)
+        response.raise_for_status()
+        response_json = response.json()
+    except Exception as e:
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            f"Failed to fetch LM Studio models: {e}",
+        )
+
+    models = response_json.get("models", [])
+    if not isinstance(models, list) or len(models) == 0:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No models found from your LM Studio server.",
+        )
+
+    results: list[LMStudioFinalModelResponse] = []
+    for item in models:
+        # Filter to LLM-type models only (skip embeddings, etc.)
+        if item.get("type") != "llm":
+            continue
+
+        model_key = item.get("key")
+        if not model_key:
+            continue
+
+        display_name = item.get("display_name") or model_key
+        max_context_length = item.get("max_context_length")
+        capabilities = item.get("capabilities") or {}
+
+        results.append(
+            LMStudioFinalModelResponse(
+                name=model_key,
+                display_name=display_name,
+                max_input_tokens=max_context_length,
+                supports_image_input=capabilities.get("vision", False),
+                supports_reasoning=capabilities.get("reasoning", False)
+                or is_reasoning_model(model_key, display_name),
+            )
+        )
+
+    if not results:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No compatible models found from LM Studio server.",
+        )
+
+    sorted_results = sorted(results, key=lambda m: m.name.lower())
+
+    # Sync new models to DB if provider_name is specified
+    if request.provider_name:
+        try:
+            models_to_sync = [
+                {
+                    "name": r.name,
+                    "display_name": r.display_name,
+                    "max_input_tokens": r.max_input_tokens,
+                    "supports_image_input": r.supports_image_input,
+                }
+                for r in sorted_results
+            ]
+            new_count = sync_model_configurations(
+                db_session=db_session,
+                provider_name=request.provider_name,
+                models=models_to_sync,
+            )
+            if new_count > 0:
+                logger.info(
+                    f"Added {new_count} new LM Studio models to provider '{request.provider_name}'"
+                )
+        except ValueError as e:
+            logger.warning(f"Failed to sync LM Studio models to DB: {e}")
+
+    return sorted_results
diff --git a/backend/onyx/server/manage/llm/models.py b/backend/onyx/server/manage/llm/models.py
index 623e0654b31..2345f0337f4 100644
--- a/backend/onyx/server/manage/llm/models.py
+++ b/backend/onyx/server/manage/llm/models.py
@@ -371,6 +371,22 @@ class OpenRouterFinalModelResponse(BaseModel):
     supports_image_input: bool
 
 
+# LM Studio dynamic models fetch
+class LMStudioModelsRequest(BaseModel):
+    api_base: str
+    api_key: str | None = None
+    api_key_changed: bool = False
+    provider_name: str | None = None  # Optional: to save models to existing provider
+
+
+class LMStudioFinalModelResponse(BaseModel):
+    name: str  # Model ID from LM Studio (e.g., "lmstudio-community/Meta-Llama-3-8B")
+    display_name: str  # Human-readable name
+    max_input_tokens: int | None  # From LM Studio API or None if unavailable
+    supports_image_input: bool
+    supports_reasoning: bool
+
+
 class DefaultModel(BaseModel):
     provider_id: int
     model_name: str
diff --git a/backend/onyx/server/manage/llm/utils.py b/backend/onyx/server/manage/llm/utils.py
index 1237da5b9f1..bdef898cabc 100644
--- a/backend/onyx/server/manage/llm/utils.py
+++ b/backend/onyx/server/manage/llm/utils.py
@@ -12,6 +12,7 @@
 
 from onyx.llm.constants import BEDROCK_MODEL_NAME_MAPPINGS
 from onyx.llm.constants import LlmProviderNames
+from onyx.llm.constants import MODEL_PREFIX_TO_VENDOR
 from onyx.llm.constants import OLLAMA_MODEL_NAME_MAPPINGS
 from onyx.llm.constants import OLLAMA_MODEL_TO_VENDOR
 from onyx.llm.constants import PROVIDER_DISPLAY_NAMES
@@ -23,6 +24,7 @@
         LlmProviderNames.OPENROUTER,
         LlmProviderNames.BEDROCK,
         LlmProviderNames.OLLAMA_CHAT,
+        LlmProviderNames.LM_STUDIO,
     }
 )
 
@@ -348,4 +350,19 @@ def extract_vendor_from_model_name(model_name: str, provider: str) -> str | None
         # Fallback: capitalize the base name as vendor
         return base_name.split("-")[0].title()
 
+    elif provider == LlmProviderNames.LM_STUDIO:
+        # LM Studio model IDs can be paths like "publisher/model-name"
+        # or simple names. Use MODEL_PREFIX_TO_VENDOR for matching.
+
+        model_lower = model_name.lower()
+        # Check for slash-separated vendor prefix first
+        if "/" in model_lower:
+            vendor_key = model_lower.split("/")[0]
+            return PROVIDER_DISPLAY_NAMES.get(vendor_key, vendor_key.title())
+        # Fallback to model prefix matching
+        for prefix, vendor in MODEL_PREFIX_TO_VENDOR.items():
+            if model_lower.startswith(prefix):
+                return PROVIDER_DISPLAY_NAMES.get(vendor, vendor.title())
+        return None
+
     return None
diff --git a/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py b/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
index 0e62fca5512..614e164d469 100644
--- a/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
+++ b/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
@@ -10,6 +10,8 @@
 
 import pytest
 
+from onyx.server.manage.llm.models import LMStudioFinalModelResponse
+from onyx.server.manage.llm.models import LMStudioModelsRequest
 from onyx.server.manage.llm.models import OllamaFinalModelResponse
 from onyx.server.manage.llm.models import OllamaModelsRequest
 from onyx.server.manage.llm.models import OpenRouterFinalModelResponse
@@ -317,3 +319,298 @@ def test_no_sync_when_provider_name_not_specified(
             # No DB operations should happen
             mock_session.execute.assert_not_called()
             mock_session.commit.assert_not_called()
+
+
+class TestGetLMStudioAvailableModels:
+    """Tests for the LM Studio model fetch endpoint."""
+
+    @pytest.fixture
+    def mock_lm_studio_response(self) -> dict:
+        """Mock response from LM Studio /api/v1/models endpoint."""
+        return {
+            "models": [
+                {
+                    "key": "lmstudio-community/Meta-Llama-3-8B",
+                    "type": "llm",
+                    "display_name": "Meta Llama 3 8B",
+                    "max_context_length": 8192,
+                    "capabilities": {"vision": False},
+                },
+                {
+                    "key": "lmstudio-community/Qwen2.5-VL-7B",
+                    "type": "llm",
+                    "display_name": "Qwen 2.5 VL 7B",
+                    "max_context_length": 32768,
+                    "capabilities": {"vision": True},
+                },
+                {
+                    "key": "text-embedding-nomic-embed-text-v1.5",
+                    "type": "embedding",
+                    "display_name": "Nomic Embed Text v1.5",
+                    "max_context_length": 2048,
+                    "capabilities": {},
+                },
+                {
+                    "key": "lmstudio-community/DeepSeek-R1-8B",
+                    "type": "llm",
+                    "display_name": "DeepSeek R1 8B",
+                    "max_context_length": 65536,
+                    "capabilities": {"vision": False},
+                },
+            ]
+        }
+
+    def test_returns_model_list(self, mock_lm_studio_response: dict) -> None:
+        """Test that endpoint returns properly formatted LLM-only model list."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_lm_studio_response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234")
+            results = get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            # Only LLM-type models should be returned (embedding filtered out)
+            assert len(results) == 3
+            assert all(isinstance(r, LMStudioFinalModelResponse) for r in results)
+            names = [r.name for r in results]
+            assert "text-embedding-nomic-embed-text-v1.5" not in names
+            # Results should be alphabetically sorted by model name
+            assert names == sorted(names, key=str.lower)
+
+    def test_infers_vision_support(self, mock_lm_studio_response: dict) -> None:
+        """Test that vision support is correctly read from capabilities."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_lm_studio_response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234")
+            results = get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            qwen = next(r for r in results if "Qwen" in r.display_name)
+            llama = next(r for r in results if "Llama" in r.display_name)
+
+            assert qwen.supports_image_input is True
+            assert llama.supports_image_input is False
+
+    def test_infers_reasoning_from_model_name(self) -> None:
+        """Test that reasoning is inferred from model name when not in capabilities."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+        response = {
+            "models": [
+                {
+                    "key": "lmstudio-community/DeepSeek-R1-8B",
+                    "type": "llm",
+                    "display_name": "DeepSeek R1 8B",
+                    "max_context_length": 65536,
+                    "capabilities": {},
+                },
+                {
+                    "key": "lmstudio-community/Meta-Llama-3-8B",
+                    "type": "llm",
+                    "display_name": "Meta Llama 3 8B",
+                    "max_context_length": 8192,
+                    "capabilities": {},
+                },
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234")
+            results = get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            deepseek = next(r for r in results if "DeepSeek" in r.display_name)
+            llama = next(r for r in results if "Llama" in r.display_name)
+
+            assert deepseek.supports_reasoning is True
+            assert llama.supports_reasoning is False
+
+    def test_uses_display_name_from_api(self, mock_lm_studio_response: dict) -> None:
+        """Test that display_name from the API is used directly."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_lm_studio_response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234")
+            results = get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            llama = next(r for r in results if "Llama" in r.name)
+            assert llama.display_name == "Meta Llama 3 8B"
+            assert llama.max_input_tokens == 8192
+
+    def test_strips_trailing_v1_from_api_base(self) -> None:
+        """Test that /v1 suffix is stripped before building the native API URL."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+        response = {
+            "models": [
+                {
+                    "key": "test-model",
+                    "type": "llm",
+                    "display_name": "Test",
+                    "max_context_length": 4096,
+                    "capabilities": {},
+                },
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234/v1")
+            get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            # Should hit /api/v1/models, not /v1/api/v1/models
+            mock_httpx.get.assert_called_once()
+            called_url = mock_httpx.get.call_args[0][0]
+            assert called_url == "http://localhost:1234/api/v1/models"
+
+    def test_falls_back_to_stored_api_key(self) -> None:
+        """Test that stored API key is used when api_key_changed is False."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+        mock_provider = MagicMock()
+        mock_provider.custom_config = {"LM_STUDIO_API_KEY": "stored-secret"}
+
+        response = {
+            "models": [
+                {
+                    "key": "test-model",
+                    "type": "llm",
+                    "display_name": "Test",
+                    "max_context_length": 4096,
+                    "capabilities": {},
+                },
+            ]
+        }
+
+        with (
+            patch("onyx.server.manage.llm.api.httpx") as mock_httpx,
+            patch(
+                "onyx.server.manage.llm.api.fetch_existing_llm_provider",
+                return_value=mock_provider,
+            ),
+        ):
+            mock_response = MagicMock()
+            mock_response.json.return_value = response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(
+                api_base="http://localhost:1234",
+                api_key="masked-value",
+                api_key_changed=False,
+                provider_name="my-lm-studio",
+            )
+            get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            headers = mock_httpx.get.call_args[1]["headers"]
+            assert headers["Authorization"] == "Bearer stored-secret"
+
+    def test_uses_submitted_api_key_when_changed(self) -> None:
+        """Test that submitted API key is used when api_key_changed is True."""
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+        response = {
+            "models": [
+                {
+                    "key": "test-model",
+                    "type": "llm",
+                    "display_name": "Test",
+                    "max_context_length": 4096,
+                    "capabilities": {},
+                },
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(
+                api_base="http://localhost:1234",
+                api_key="new-secret",
+                api_key_changed=True,
+                provider_name="my-lm-studio",
+            )
+            get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+            headers = mock_httpx.get.call_args[1]["headers"]
+            assert headers["Authorization"] == "Bearer new-secret"
+
+    def test_raises_on_empty_models(self) -> None:
+        """Test that an error is raised when no models are returned."""
+        from onyx.error_handling.exceptions import OnyxError
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = {"models": []}
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234")
+            with pytest.raises(OnyxError):
+                get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+    def test_raises_on_only_non_llm_models(self) -> None:
+        """Test that an error is raised when all models are non-LLM type."""
+        from onyx.error_handling.exceptions import OnyxError
+        from onyx.server.manage.llm.api import get_lm_studio_available_models
+
+        mock_session = MagicMock()
+        response = {
+            "models": [
+                {
+                    "key": "embedding-model",
+                    "type": "embedding",
+                    "display_name": "Embedding",
+                    "max_context_length": 2048,
+                    "capabilities": {},
+                },
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx") as mock_httpx:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response
+            mock_response.raise_for_status = MagicMock()
+            mock_httpx.get.return_value = mock_response
+
+            request = LMStudioModelsRequest(api_base="http://localhost:1234")
+            with pytest.raises(OnyxError):
+                get_lm_studio_available_models(request, MagicMock(), mock_session)
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index c954d8e1acf..4dd0f6a00f2 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -99,6 +99,7 @@ export { default as SvgLineChartUp } from "@opal/icons/line-chart-up";
 export { default as SvgLink } from "@opal/icons/link";
 export { default as SvgLinkedDots } from "@opal/icons/linked-dots";
 export { default as SvgLitellm } from "@opal/icons/litellm";
+export { default as SvgLmStudio } from "@opal/icons/lm-studio";
 export { default as SvgLoader } from "@opal/icons/loader";
 export { default as SvgLock } from "@opal/icons/lock";
 export { default as SvgLogOut } from "@opal/icons/log-out";
diff --git a/web/lib/opal/src/icons/lm-studio.tsx b/web/lib/opal/src/icons/lm-studio.tsx
new file mode 100644
index 00000000000..a45550d28c9
--- /dev/null
+++ b/web/lib/opal/src/icons/lm-studio.tsx
@@ -0,0 +1,141 @@
+import React from "react";
+import type { IconProps } from "@opal/types";
+
+const SvgLmStudio = ({ size, ...props }: IconProps) => {
+  const gradientId = React.useId();
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 480 480"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <rect width={480} height={480} rx={96} fill={`url(#${gradientId})`} />
+      <rect
+        opacity={0.25}
+        x={128}
+        y={80}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.9}
+        x={64}
+        y={80}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.25}
+        x={208}
+        y={136}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.9}
+        x={144}
+        y={136}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.25}
+        x={160}
+        y={192}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.9}
+        x={96}
+        y={192}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.25}
+        x={104}
+        y={248}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.9}
+        x={40}
+        y={248}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.25}
+        x={160}
+        y={304}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.9}
+        x={96}
+        y={304}
+        width={208}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.25}
+        x={296}
+        y={360}
+        width={136}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <rect
+        opacity={0.9}
+        x={224}
+        y={360}
+        width={144}
+        height={40}
+        rx={20}
+        fill="white"
+      />
+      <defs>
+        <linearGradient
+          id={gradientId}
+          x1={-206.055}
+          y1={215.087}
+          x2={224.119}
+          y2={658.689}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#6E7EF3" />
+          <stop offset={1} stopColor="#4F13BE" />
+        </linearGradient>
+      </defs>
+    </svg>
+  );
+};
+
+export default SvgLmStudio;
diff --git a/web/public/lm_studio.png b/web/public/lm_studio.png
new file mode 100644
index 0000000000000000000000000000000000000000..9359c5f7a82407acbc0b60f6e0ba6838e25e02a4
GIT binary patch
literal 12829
zcmW+-cRbYpA3u9LdxVn}MP?zKozZYAlI%@nWQ60+9-%XetTRhUcBt%`k-aYBP}Uu1
zeViPA_x=5GcaO(CZoKdHdB30YafzlThAfPi7(pNqi?NaZL-J$Ce>Zws^8LdFFFFuN
zVa-@y$1E6wn}Nc9X$$uIy?e*@QB0bNNkFcMnTx|wYAo~1Edis;nsgJizv$Ht)a<pt
zgKR0CZcCPO^cThQ&@+6wdr9GP^Y8gPJE3XU6U_Dt4gPKHQ??<uXUE?OZ@rn)RWTb1
z_pMS*HL?;3X>6vjz+b=h9KWg(ZFkqiZgKgTwcY64NJ5kCHtbdX!@^7^_j1u6rm`2b
z&?I>jkBdoEGeJgyN6z&7mSFE{GM^K6m|N_xrPc$l*COU5-|Gp?9SIy|Q>Tw^*zN7a
zgbuwsv%P8fy_^{L*Vf<m!347(F8lAjKOeIoY42`SmKq<hwyUJuKV6B*rqB(t<9cD`
zDE^J&ioXb(+NIPk$?%6nPZf{il0~GnbkJ_y7PIu%5}oP!$eeJ{%}Vh~o^%U-kCj*Z
ziNdQZ{gkWi0n>d2$4LeB2^Sid&y_B<OG_c1b*dmPg+C`rT9afn5rZlS$G>xu=hoV!
z7~}i$F<#sWY&#d}s%U5jT`g4~3k!XV1KY{OFW31J6PNDI_?-Ik4WOv_7LDL})hA3s
z4EStiy}MckA*zZP)(TTTSA7ZU+?yn<f>Z3)R^6rrw0e7liPMsMlT`Gt?E?I;bp5at
z&bYhG0!>dS)Tu?Bl++v#GlHHf|9j_pR63I{V%gN>GIDKoBkk_dfUG7W6f~j^|9LTr
z#?0&8uQ56trqCyWK{5Oy7W}_5yZ(+%9gIS+`!m0a`kKD|1r+FJF^>0C3FS$Iz&CKl
zQ$0(%^=@rC^=@C<=EbHJ;LSwggFoN|t>|KIr)*DoSKJ*Z!ze|^fSZ9N!sM=w;2Ffa
z{`tpW$6+LxGCZ9n4~oK&!iah9(XOM1lfw|UzcGqoB=q=jc);O6AJD<%U$fZ-dyjzL
z-FnYAm9N1n+;Za+iz|#|_Y=Z#CJgM9mZd1YUR8Z4+oE5QV`Zl!*Lw8u4#=s4IzEB&
z3YW&0`R}>n6598_E{1N?9GM<HJc_u6d2{sprD^%^zAJ2c^fB)fpS!a^ThqvIr`u;%
zK5+iKmn@un``_S?vvq8Ac8Gl^8j?R39gi9k(29hfboXa-HqZ3DUi`iyc;ohxi)L67
zjSYWDvz-wA2e;TgH<!NAIB4X`{OUvo^elO9vO5#Hwx@Tp%G<RXzr19L4g9h+Y+)s%
zWHFbv?(p>yAM&9qDFAnJPvt;wFitL=E(-go#;tx0$8R<Q`M5Br_kCY1H&uw^BENAl
zSrT70lrJHCP9*-m=|Idlx2FXcWI{`l=T^--AOp8M(K?N|c`0X9N))v9QceFu4Y*)V
zJ)LB-?FO-tCQ5};>*~2;6}4U4a{YFsz3ZUxJz+)*gc%pyfWMXwbwODtX?X=_`M4WG
z4;Frw7NF$kt|aln%i#R$=hc_0=@w@hoBT+5e{t4=VaSpMoUg{M>ihhp!4HVWd6!DW
z)z`QWMD|&Z0>7yXKl3K(cGdG6*ZAQ(4{G}D9^kGDo=d=;$x|%QLMTAyb3%HuSCk0(
z+H?n0a7DvE-RQ-AhtWc19RI^1v@Oe=Q(DVDXFqHN@@h}7bnhUTq}#QfR+U&Vap*=#
zjN~1*dkWynT~Suo;R|e309UFZ1H9&_e17u2IwED>|1K4<yw^?eyWhfEb)QsvrQo33
zFn>@JAKB?S3W3Gexjl)4n$FjjC9%VYV^`z7uFXFp(k66z&R_;!@*Ke__p+?BOGSZX
zj}getmjM&?@fwKvU)fjt!0df?<G7IFH_%|B>Ag=1abEXpOB=JRKeV-CpSNR=$`#t{
zu$5;YGtf}3)%IqbWjP2~#;y`&+>%G0x_jr+-z&B0+HmQ+;83%}`6)Vr%jn?g@7+e9
z3(Y%qU2Wc9O>UX}G(DhhzBFz8wRWUT0>1N>6aGbZUauSdORcW|P#NfP?gQUWGxsX1
zPP@?FJ0tntJveb5JvbPIbP<eK?WR%CCaL+!hvM+$kX0YmpL|wbqnxP_JLdC6isOSv
zHSsHha{QVOB$r+^#RM_Q72F#wQ+yQY1cSe?rF*3-A7-4!<wpOKtw1KapATy+>p-ZM
z&V)h?aDH4vkRRN3DJQ#9&M;mkAhjRn3bqr3U)opHxATwNkXu=Ot7u1H_OTaj9L<D&
z<HF5fsqcUP%P`*=m?N*KQUU&zt8Sh12v?gi=X9l3^0NxumsToDRnNJg5`~l+5)O{A
zVTVJO8T(;FXq$uq$bPg;7H<3%l(nmS+YIO7(gD#3vxa_WDAp?Yaar{%wTVxmJ-9a;
zO5Xg=oe;h-ml`@$0TizKd`?WL{hbJ@x|QO!^^emifB46K*rBEboWz9_3AK|0yi(`8
z%@yGg3uQQg=oiR7Wg&0|940<rD*YX)S2>sh^|qO-?~Q{#UYytSdnzze#iCYMmfe9i
z=z3c)0I{}P^lMCWhqta#s|gEQsG@&MO9IW7b#4*taLwr)XeFkuEQJC-l_D&fEX>%w
zjc$}(h(QvC;_KBORR=hY+RWhQC*DH!xNwm-TwuInz&n>Ys<b($Yw1vylONV6BAY}{
z|JJ&hxGVOj<||i6<jU@Lq1i71V+AvD@i2SvbhHe4Iq@Cnox6Z(9T_cFz4brPX}-3r
zj1n8fzWLj=r$iph-dbpl+q)hJ{Kp(sN!hKMS2qx6bCXYJa6bf)e3qVKNJgKC<BH`l
zgs|WPMB2PkM+CHIPx8nG_KgQ;Y+4uZ)(crkv8H>C(%rS_6fR438I_8J9ydCmEP{^~
zV}nwC^dD-cBL&uf8T?j(8roKiqr{IN%Z?h$65CVnVy^6~^=gdOG`I~YiF*(Nb|N#B
zQ@`1z>tP<PeMxG$oGb1v<kowu%5z{IJ}kUpV!JrTSsS%WIacwctd!OLPqM(moe>Dc
zaRA~W(lbq(eoTYRzTGMOVT?4FF4vBTL=Y9C5odVNh#V>UFE1?Wf-@)U3-W7A7teYu
z&+#}%19f#ekCDsRghtUVnvoCw*LB+q%<tgXy>;BZuf%>phDNqsc+-X7{E`?YCg28y
zEN^a-B&(86OjNLM*DMXed7kb)=hQ4Ot3KMpidBIdSy502BUh40Z4TR36+`#~8e}Ft
zssIgz#Nt}CzQjXDAcZ~q$PFa$lcfG?dvNt8vLjDvefXYh`n=+*YONc`ZnkP_=Ukt%
z>r#w(!!8Fs1B3i!1~z&xV8q@{!PUr7verp(_gn1qASMR<L%FTY&<9P*;@U=0YYXMM
z#VylG=n7l&z^2d@f6X$Nn6t^_w)23aZ^vqaDxIq*PW0aU<M)Gmk-NL6V$6q0%+zDT
z2LC8qLUIwb;jJp2_^%ZBDlx*=&{+-K^QF8MTa*5Kt#7F#pZDg)YfBaw%tuuV#k*<w
z56s=cG<Kram;<Q-z?7&!d`KaFQM%V0q2AIriT<PJIr_CuQ}yIe;6`66{3?OMm$qPI
zv&Gl}EPAPXv~Mz;>NociKj2-m%*hqXk6Rv^H~J)3qt{2Nl>aZMvFv68prIq*H9CXd
z6vX&T6NkJXA@6j=24J7udtioPDzI=O9x-ZmvLe@_M}-kxn|#r;h{aLAeWh-g*=3U_
z1#&!{Bzlk0Rflm%Vma}t4~MUSSQEe{jl>*OT6{Jorc6N|qNS!Gh_5&&U*CAcXrQJW
zg_~QBDCY8<@`R-q05`79K&ZRr9%x-&zV^_mA^u7IXWksEKIREXanrghvpYB!wInq4
z0V<#uTfhjqYUdE29P&w|vCkc**hGHwEQC=@{Qh&kPD*0N_-QjB)Xc1$s~{ZAz-%N#
ze(#sR+cnj9Ebt7Dzm#lJTgQg6q&!S?(X1W(9oA0ywoJrT79>Z52biYdNMd%}NpCse
z_l+wgedhRrnwQC4OmK}*519NPlR3+si0=}vdX4dm16}3Ni|!fn*NWWx2(1i`pL$3k
zcrne^yh!T~j%-J<ue(ip2*ef$5w;4UILZN(lD{YHRS{-#pbE-`(6v{o-mZ^3T$f{6
zQ9?SIAVlwk6>O-0z6Elz?(TQU?hw@b4Vg9TN`@&~l17pV{>j(Y#?hN!J;8fU44qQ=
zP6F@3*U5VSW6%?IZ$f;#6+2%lpX$;44Vz2o<+b%m2=lp#J~MK9OLoB4KFaJhVfzDg
zGNdtnDqaY&#zEib4yG-TlEp`2FzhDy2PP<$$4n7zLg(GPwB&(bi(olX9(czofzj)n
zHHJ%(5;~gRzNdT8_-<wFAgl9_;?ChNPiOnmEbk+XUINzVb35y4Q%m41B!pOCGfN}A
zGV-(`zA41U4POrS+viMlBytM(QPQ&_YXGjR;}9VH{7)=|h~NEeZyKm|^35f<RmI5!
zE>GGxHw433CLoUYUFkwEN@pNJ<ZT|)ajPmt>QK>;TeJ;My4`E5y7!m6=9kX~58@iA
zxc}5pK{Yg9OBXZg&#88=gplhLPX2NEBtFE97Xpttco&ILGS5Ds;|0MrT7a9SH0PgW
z_PY+^>6Q<+9OQHR<!eZo?vCwFpSbsI_YLryN582bZPVwGg6VD5)^6T|f2qbt?f(gq
zy4T>FN8<XI@NCq~9HU2~XVOjsVpx%FaeHgMy^y(@B06;V7ceVsH$Ixq$4|TO90VLu
zyy)n+z17MAkGdswesXY1H8;x?4;-<<U2qJY-nV|+2Zdk@QTdu0J+J+OSvNC-A3OTI
z75JjL8na(4D>YKvU2#t!O^3@ZK-=$Y@(up-gtta%PLajVOftMST5d%QihpxN4;tLm
zP=G0cTODaiV2E@ws=9<1A;wK{SSHg3y{?tO&6DVzl-nz6C4@NddFlmRdZ<1t9_S~+
zdEe*VZTA^8Kc-Rg>OG7ejj1Ge#GUnZVROEjxB3{~N6yB4Dix_niL}TP##;?;ajcjF
zqbH5=jLYrY+NrvuRZxuEL4AK_3^S7Tdg0@Rj@N7QP4fFO!VlOHF@9S^-32?+pxgdx
zn^Q0gO#A7L-5=HUfCh&*zK9?ebq((jBRuZom6&7&pL4p)JcWLrHUpVln?ZYECm_t4
zA~81b7h*+FT&;v^Ymw?GMdkkOeag)!^A`PDRGx{bl|iPUI+xoWE|G~*{kY_ST;bau
zkpV`fgGQSXZ?8U1bmlkKl;Idk&=qG_xGPT0CReNRliJcBb2<ERWzVFd>lZc{y9Z49
z^dKgg-zcMJm7^SG99vioSm&6+*XYktw{A6-X_o-b{?A}vDe(@(^O;xP!54U)W;3`@
zjzAiF7|RC-$}Rqcb|25LtoZ9<_Rm;!l1y&ct(RSW2lQ=^nW-}ue7^~zYf^LAzV<EQ
ze(@ZwRT!6u5Qns$L+tfficgo7*R33ED){&RHfX;HZipv}@MuqYpoUEGKiES)4A2O-
zYEdul2yl|^>vju8c<XBTHvx&mdp#^02frh>j%B+$@6h3bKX9h5r#5Qh2n#u;bK;MO
zq~1Qz)sW_yiDOoB)*K(6L0@IYhdjv!><OISA{$yoExC5^y5w1O-L$tV{NJT!8w2Ws
zjlJLYh;i;SY#F6?Xs_evTY)sJ-hKmJKI^Pn+@L)#V>+*&_1Zg=BU_D<sw8?blF@bg
z&OuIF@^!47hQvR^|G4YlaiY}Cg`myp+U+F3K4%ozfXt}fG=<IB5Uzx1*u}4agk9=~
z?9RjP#e{=rWQa|T)xwI%L?n2^><KAw%t3qm25)!x<QM_I@DZAEF;zBej|eQaswC4K
z19Q8+AKjb2ChWI}-xxg&eVPvB{v$&7H<a}Kvq^NZ1|4GVrU`uG5JiJ`c(J))KG$O6
zL^OtrKNc|q<-Qn61>8$0FwvcoF?{1_hH7Q6Uvn%xlOJ`klA#LX8BgKf_YxL0C=I{d
zTI-yxfa=%w0HV^)(0S(=fDP<OK}@-_J_h+aO?!mNC^3S+*;#tO%|aJ+6w&H5yi7?y
zRq%vS6Wfr|F?711_6!_bP@~(q;A%i5<7^j-9+$DyT@AhEV0kZ6z6+Lgm30S*T2xjx
zAzVBJZ86$&y~e-X`~>9+6CSDs-SC7xAIPv<5v9-2g---G^dqH*{NF-qa>%KW)_A-~
zA_d-I+=D-ox4{2}#@{!l9Orn^Td<o~$IzyOdNdu3$S$fUAcZn$e!%|F4)8|yrS7Bd
zz*WWwP3nGkLgLIn&l=Bs8%Ag+|M?hA&HE0@%}D`%tVJOdOydFG1959}d4NyX+~Nyb
zQA`(SJ-f30)CH>w?l3RjjzqiATV2)q<O$p5PSO6*a)=dn2%mGwC&d)bmi)AC#6)jY
zLx%<OrTxDaz7OeXru4mY80x4(VzIM3(mK0)#B>2zd0BevoGILcul%85Q^I8QV0w%!
zaw-QG#$5H;RT)rBOEiws#9-lpg&WLrUN1kYo~X0+Vxm!+m5-kkx;rElVWNAM<V2(<
z&>GOj{vQ*NHp6`5!P(TmGWFfB2fbBKr*B3xM!YJV<rJWau(&LXZlg3j{%YTUX|;i_
zo%B?pX<nYZTREd_G2M^RzMf=?@%Tbi`n`xmWbyt)gmCBOJ6(zz?c3&|T5Dy$ejI9s
z4NTEloR=mHCN0)f7f;IL=kwg+R(h*aHCrjtKS+&3m^In~Q;MkwwyCax66iebGZ-WJ
z3Bo+nN5AVH#wNU<e(I?uE|^FirA5z4)af}yPsk*4h(9u+Ti(vWf$G)*jGSpx$0;f=
zlDQw3(WUYv&^#`CT4-j%=$L7nF>)?${D#EO`9?<U)ygjsw;*X}twl;B9>qyRC1)si
zlw{hKM9G}Xll{!XDXAx_X(H*0RgsXu7oISD42DyVrl7f+mMyX=B)_Y=9dO>RfC`>{
z`-I<4I-GAaxt`2;><4{5=7so~4aL3Hzax2rlT4TDqy)ADj2_lvp*t5l+u@yGgH#c+
z)MmjA(@gP&>UvPAixHC{wtXEH&euS(XWww#rCbQKNTUWOI@01J^!U^Rg`|*gl(eA3
z|43lOKhSD%NDPe1SQ;eTTX*|)ciZ*3o&kC?p3vBBd!5rpjsNK7vnsv^=d%zna|iqR
zu+Tp!gI;ByKucg6$pWRmD;pYvoy0VZ;;^%1IyiV-_JF)PL+Zr_$wx4}Ljmd5)%=<d
zV+`D$)~2<Oo$rGxUEZh_S(_w+>E2YQKM*wHUH0s)u;LopjCv)ycl_e9Xg)`5(N*aN
zy?I9dAu6ewlUfli>JUve@fQ*^>raZrdns=nU@pTy59EPdn{;Myj}t8^G!}J-#T5(o
z$C<NXcS=Xyd6Gn5HPSh_gJXqHF2(#PhMsuX)V%*B@Eh*Q=Joib%4D%x(P#t*%{VY9
z`{v1Pf>fqAJpSfz94A{I8D5oqGucEoc2?jE?_CyLNWIl%?j(mg_tDmKEUKN3DS{m#
zi~liZ2Y>umb@|AGZjI%799Kk>K($i8fl|_>CSyUX66jP}joIDSP_0LIBO<W;N*Jy@
z8kpj*gdYE^H)Gb~C<ZNrVY=B75}10?N+!)S0%LQY3Nsjq9A5ZS=Hn|Dc8eN5NI0CW
zM5+)&^=^NeYI9EjG<r&)T%={nj%CiMAiSUAzn6_3u+JO+`VqhBUdu)cST5B58kksx
zM88B%GO5qJxaVW9QpZL#Np<A7nNS2BHpr}b2IlSn*MOvm58gwKe!P&Jnql_OCy~Ox
zXZU$B<N|S?zBP4sD}iJI1cUV2h+~8NvuQNlTX$Fr<$qd0_s|1e3(r;24rl(_z9jJL
zdU80#<4vM6-XUIiKGnOJ;Q5~nTn+anD^{&$ko+Nb2JI|r#yh)<^q(IiWSsUtBPNdi
z-kG(8M==#DE-{x+UMjYQi_3yUO^GEsWbr!CFU%ZU4sz6i&*fD@rp)0{)k;njPcE<4
z_PNiJweD^bP2p3xV)8gy%I{&n>D4Xwzo6jb4qF*^%Ssu8Y^_~O|4lI={5&BP-?@Cs
z#+M@FFb(;N(I)M`M=+O<)39}8C4ZmVR4e1Jx(2-vnH!4=|IXN-DK&+rQ*Bs>!~tPT
z!kuFbBe*J=WWwF!kZZHwiYAp^y})vfa((Xrw#C;Ef<2n<BJnz}5*ibqGj>-u0Uy;)
z5-++aO)H=zteYoz^`Vu6D{mg@@D-W3eBT)3@=5ymP3fBI?~@?B$d@Xvvx{+B1U@8H
z4<6ioVHZ=_MAj~zDCnBz=S6c!O#|u@4<eK|VT7RWB}N!zT3ndK&`Y!Po$E?-$$1wo
z8#a=ec2%FcyHV2eEx^XW(PA7#-0URNj{yt47S_*c*V`+0$wN3&1qF9l&td37NqO6X
zSub+*J>pP7_|7qbYN(Ome!;p<f-IiF-La)HQ9*K?)=H(h@bAJ+U-cta@`t22u-`i;
zz~65^?+374bP{c&Wl+^F=RZ+AM(C&2rtoJa+HiT|Ln6CQBT(w+4&%^+b67Hc#3NE<
zPOb*2HcV0#gsW0#J&P-<-TC_BSsIq1nbv6Xy@Pw_pP&@c`+_$V-QOiR98HPM7PbJF
z@=gNS5aFc)U$W+W8H8#z-VJIwMGjK(pS&2>NAoL-wYYv9Q0%NAW4c<Et>wk%r}&no
zCwK-~(8-VLZ$Qo0<|%KxvU8g-3n?Q=d?_n3^Q1->QJhSDi)R3pRm)YYs}prwR5Rjz
zf~DwB=93qhm#-jsPTk{4xACcxZbc~N0V}qSutaNT+e$5emtl{{;p~xA*(&kdVbaEl
z{iIHTJfmxhHYQZ1nxalQ`ixN(B_Bc-rSL8BR`7&xwV*@t9#0`-d8{yl5TXlt(qK+&
zc(J1qGv4v@-9q8_$ovn=rFX_wJY1>Z_4FmktlEg279{V3=C~VawdqC~fCk(Db++ys
zPn00p1Mo0v)oD9W44bnf$Q~a3yJKfb;v-T;mDCep0InumgCouqS*)NH2RpuKIRhBz
zg3$|d=A=wOX685yi2O7i=y@`(#8igln+hUg*b$4az{dB8oCZTn-mG&nFoUb0JvQsw
z2{!mzsWHfThL$-DpUp0U&#t%)-_mslb1Y)?@=7QZ8UW|MuYiU}A)uj)DGBmops{NN
zd=GbRr%K5>$Qv)Rqx%tbIF1(I!uD>moW2aj651e+)md|^qX(KnbTvbqIr$LP?{}S>
z=w4ITF>SVuVDndNsQfrb*++*$X5#NUsz*OptYBMz&YFn(wH8rf9wcR~tcQJ=VWiI0
z_v6U~t8|omG<TAVOnPn2H0lqN{@*6u9UM>CV7I~-@nnpDdm6?cT@HOgef5yK`e1b~
zUF;N&U778+_ZFsE7?|_Oa+r*lWzTX--jm3B*mu~gpz!&p!bZbuZO=3L@8>VT%LD27
zO1ysg^RPQ=3FeBgT(|-|l+!BS3Yl8k$EFj5^01uI7=N8?U_t09Jd?<{3^xPiG?b~%
zQUt$T!Yc;9h?eBxF`ev6te@8NwXgT`VyL?!o@~GaETTt3c=8qm9q=uD=9p-i6Ld_W
zIs9?8ukKNqg~EnGyq2pgFwheGmr)S2VxMw-{5#6?(Px_eH~t>rtFV}cb-I5ZWPQrk
z;12stJhec93)A^7AyDc;P1VPteaovVrw;2%`Ix^zja(!4h-T{YAIw2XVq<)GW26{q
zs=cxRSl}*&nt_&}Oi=|uX$2fpAM~CxXRA8i!ONJO%}{x62dY~C88e3W`8Zo@R!azC
zqGOEVKc%N2jIA2v{GbG?Nic@h91B3dh-Y@e3g{50{@~TASvQFXmT?T}AGV61k)5bi
zfK;Z4w~UIR*Ao3Wjh3;b$P32T`C-e@i^hEC0u|*5AMMT5r@DLl9+#}r0i*8HX|!s1
zLwqwQ6G#vC@sid44?2r3^0hQ*h#xu0(2H{i*DW@MLzgJCQ8(l4;5(D%WJ0k1zm~Wz
zo#<<JEA~RppNyHPynoK7yANW`KsTD=`!ajJ12yDBaK{yJj+Fta3x?Oq$@s(nh5pAO
z-_M?*OfXJDO(}klUh{uzx>5<qM~zOP>&ejkGotV@eC;KC@U9IpMUHk_Ths=G<+s|O
zT+iETaC=LM*Kxj{T)Fy-57Rx~UfBeM6}*QgxZ*|H{At;AhOYGe;m;?qBdBmUg1s1?
znI^}zk4mRpU#Rc&jvxbc6VDT0_QpLW_?)DcH0k?)R9_C_Nuqz&XvnBl>(a_}uS%>h
zrl6y+Clz3`5fbwasJ<Hs1bm!<<jgz8a{K36V%KNUry<?dWq|$iTMrahn67C#RG+f8
ztU@43yXj@r7^i@*m$BD>;R!Gd!DAkoyGN!s^BCoDSmG@&$>L9BAHhF@c2e1zc}yj#
zt3|4;*Q3Bo{M5NFQysMu6I@Mg=pTGxU5htgVWK6q#7JQnF|8wM#rwhgt8{kZjqz?q
z&(|8`P0rQnb*cbrxq>T<5Aiica|~KqQ&c{!2!72_H+oIPOW&~HBAWYqL6@`6Lbesd
zWZDp-=f?%@TJ(}yx^aZJL|;nH)Q`YwUC-$qKEgVb=DRvbnA8R)^enahW>rlu)%ZpE
z$5K&|UFovR3q|MB+$dwE&bWpk?V0xtddAk$Yns#a<rj~t;{mB}7`8J^w-o60pGnKT
zPc%~rgEUi2*N0_gW4<;Mc}>eilh18LYmiwlDFQi5VjqYGT*!9iEp*hzP1)mHRJI!9
ziKxj4`s4?(f=Y0{>&e4}`q1DJvQXwUB(i`08yGeJ-K6I9Wtssweyfdp6D8b;@o%EU
zKk(mQQZS)dn1Q%p-KYz=5v~Vcw`hSI<w%PdT^QEwMh#saiMoF-z5iAh%9NPqC#fP+
zLK`G;J^3MF(;LQ2cAA<dWn}3@KFw++A^CUVuD6Zgkm*m*il=-Y>_YK?MyWh0)RXMA
z#|IqA3ghB64Vwd5Y#G|ZABt8$Sw0csAHlmcin7UvF@V@e&b1Kw37U8XrN%PVX-2u7
zpzhr2!%jL$THSrbWuJjfNraZBFnXik<offx4bC*%v*7Lm6k>GwC~<>kt$Q{UTeWH%
z9Fj$)y#CJNe%SW)r{bA+J{hc}x+Y2#xkpVWN!&@ht^XtH$`gfpiV1}E&=HHA$LL9o
z=YNP4Fbmo7c<%bQ;mZWG!1ujv&5gPg+WQW^Vu$rSzWQGetNc-{!EeXQlpyPTX6=jM
z_-nYD)-lRo76VVbfii7JtH`VG!uUfJU)(o+>lEeI<CxCqph%XK8^4}_5<@*v<}dN(
zPq!m-lq~v%^j2mP(cX;JuE}7iz$lA*RV!_Okh(LCya|y#7F#{|c9Jz$33K@(F;pgM
zV-kI#+D)(Zf|2?@roJZ_e^stQue;ZiqI0$#6dDLdt}%gXZ?JTaR;W>RRbL_MbL(Q;
z@4L7PIKwI@ZQu>+TIwV-5Cb#ba!?9XrT1*TzESdJBF*oRR^e!$24EwwB}M384G(B<
z`jo1sey-RCPI8xgfpK{BR6zW<UH7do`bEG(c@o)XlB|3w>^DOG23%4s3b8>84Oh*k
zj6*1?IH}4sX$ttLN{3zuz4ofxeh)ogV~d4N``>eCZ3l?t1fnj3tZ6I@cRaxRlZ)Pr
zZ93TF=Hhk`u^X00jLn6?=dhA>zY4u9m3o#qTgjj(8RI?)Imxp2X`k^SV~FkSlVo@B
zH&9zxlU4(;MviW3&6$yJ2m0Rd7$Iun{7NR-@D6lZMsN~)R|WK7`uYbVv1-U5kEGAb
zt?fn5%iXm2P1z7_8OZJH${)UH4}v`pC(-JS9;3x$l3IJ!c99(~8~@9)mpPHa??*cb
zo-!bxLr+xRR#Pa;IOG~=Q|R($WDY~ax^+)Od=yy?u@~#WCsHE_VsuR{@};yf1sg#t
zZV|>6P>2i7*e@t;J9K5j2F?~j;br8WNh-jTp}zh}1|ZKAQKaE8Ms6UMt7P8uKXz}s
z;blrpw1pi$10xBEuV)-o&1Q-+0MiYstMB}-=3%<&FRo^i&rK8!n+M*(`q@y9Pt@$|
zqo~Ts2m)tt;N`xC_>DkRXPM7ohkvYVUwQQvQV~<3XgSRa(pM)I7%PX7!(u^9J;6?%
z6iLHYW(w!=b05{n1Zt{pRNrarI;sB5$Au{Fhw|uQ^lr>rM^bI8Gmk+WA3c*U)w1Rk
zC9M}fB#U7t9})d*fUQ2EabAcp56|j!5GFS$LF_%rz+tmN(cdH;)w*$IZ(?P@82Z&3
z&p`I$yTW1ol1P2>v|!ldz0oHi_8ACZgLvk8H9@J9N!^;5-H}SjU^S-58OAty3dE_{
zzUW3jOrj;bt#-u{?mK^#wI`zOl)9?d4BXz4Q!KfC2_9`j>V|kEMc`NBI=8f!Z}2xJ
zTg<Fbgq34;GPLL<Hg8eWy6M)}ewu!uWtpg>;@82QbJlY~TL*icF;|%iRSXhib<CoA
zy}0rx--a-GJ$SK`x{~LH&bUTei{_;w_t(kuJ%jTsJu>_-u_F$p?IHq?H2M=SjHLD?
zXlb@oLkAQ6aSFXl_%Ed>`hT#d_6+q^R(1mN8^3LRJ^9DNuh}DaTS-0}>x4GWoZVGR
zy=SCh$jUvw|G&61MFvMGqx-Mfv4XF4t}|+N{c0Cj=z14ZJ<x;YEn1em%Bb}XnI(j1
zWWgmHKPMZI+gOwy-%B{Las6I18RE;VXj0jyF?#ZSnQWa{!;Liyjh3P`end?8zS5;R
z@~+oz?#rxkJD8PsJ@CI-$F`(&4=zu5)#!!|mb}nnrz{D9e!^r_R00H*>i#w$tjY$y
z^Ewp>vuYuCU@-bml`JGoGzmG0{<krUhKrU$U%vQHtC=7JF$bf`1hJ)mQH+=8j>Sr$
zN`W)zesWk|j>{;hf(EAUXM{@G&N0h*Z^pouaM4M2ES>M`De|%-CI>EOgzoL$%oB+E
zz+?ex=kt8fliD-OF~S?SyuzD>U0n)YcFR>SyjD*$xRP7w<w3uaYB0C#l$hMhQe-&=
z+P*z={bRg2Y+7dqC9Az+<5tTSFbQF7Bl83?3GgL%AkY2PEQURzELdAW0<$*21MXzD
zFNvEwmtrAJICzvdemTpF#f=vGw$-NQX35QWhdiQHG+&5D&mjeGu4rFNb53MQ+7j87
zyjgSjbCMjLa(7U&i>Q(^=g9qI9!Bgq9D+Y#Pdm^T3)?pkR{bOv7q_&^*W01kRn212
zPfx;1G|3PXWQYq`No7gp&cS|9haW;^=I*0e_wbg>tGQ1=m<Bp3tu|m-*%a>TK8r4;
zcZco2x$C>~k&f#5;SU&gSDCf!NKJ5Q{)cRY8QIc^%ae@H*Y2M@6(;i}9S_LgsEXWs
zkSo{xf0)MgG~fT0_~j2zHw@7f9-{{*mY;-yf_NG{#>nABTFPEZ4Q@v%ry-s!8Y>#y
z&<6OBoZ~feBmrS4BP+KIgf*RAn@R_7SkH&UL*b(3cna98)b}Ue(}mDal$T#Y+WELh
zw~L}iXCN!W<S^I+<?+IEw1FIXKv(5*mY7FwTCk{{FjPO9DDd6?Ipi(W5Z_sMWv-?M
zvT}aL6^FJWi(1Lsr7t72&Thk{hz2I^vM|qh;GgGKm(L>@N}5DNm{xCn1v|f^Z%#}z
zkg~G|Gb}-?Zjc6=CAD}ux{#z5Sky<T*j7WozOUW$gz*33QURqNO84eIzb!)~MINFW
z#@x)a?iMe6)yfQ<xTIe7U$XL$B2SRLrvofC1tHHQ_%TQ0$62%?%hZ3pL+2Rha3#z8
zyH5+>XO@AAts@tl2-s?<fjgL6+fl5L@_Os)8y>vKIaYl5B0htP$ZDUXN+Ksng5)A%
zEKs4hdyD5$>HTli>skV4AEBh+uU%FkC^;!<8FWn`lUuuGX@Ki>^f_NB*`P{l#V*Ag
zvvnh$DZ0bzp5oKq7?wWB27KcR!b_Bh-lI%!gYr$n0jDwBm%%28(m!2nxT{_&`ecMP
zdT)dYcXR2S6-2zdNZER%+ZQ(EcN?P=Uj(gp_N^9w=CH7x{T-9R=KKEECRR=Lc;1B^
zH51efx;YTAb*a4IaR#eN%4o8dG^Kc>X<m5`-u7b(vLf&VWGBe0_&5974UbWo-qU6_
z#`e#c?sint#oGE(f8&+UG_q#k7qoW0Sq?uR=rI+}-lUx-lgaDvkMkSK(o$oQc$}J1
z^Ff0wnU(tsDy2;$|I)_Wl>ozLW#sZW7Sqj&AS>zc0y|PZxoXi8k{2hLQPYN94!Rrg
z%U~H_;vKA9Hf@TxRH|eZ4&N$<mTDT^M9`z9OGlr#OFOllRPf-9|I9)}2OA~RVDNXj
zd>QB8cvyWJC|E!DdJf{VKI_6;@5tWQUNo0iv8J*blAn7T-}$=_RTaWFymE0cd>ZcS
zoX@YE)VbJj&p>n{I5&ksai!m(97U^rZRJv-mmgF^sf@J_84S@n-1-EiKerAK+*x|O
zB;ovX`(Nf0P$T)QgqLJEQ3O&qxV=JS9wkZr?#%tSswRbAqINN^GEL)%T6-)7^A<^`
zd@_SG<WH9p(<!zlwTPDUE5|unUcO(WkoM8YJ?bb)!2VD2(*YuuW*~T=;E*oupodCv
z$M7db`d@e}tgqEgV&@i9xt1!^(2g2a(#3u3B-*E998&spWw+9E{cN$^Cy{0hnDsc2
zsqRY#?veZ1n1>LF=gD0EsP)HLZMPOv+<;wCa#T*;pZ9Z@di1YkRPHQqqKrXX_^at3
zz5eAXcI1=bs1tTx@dSjtPESdC%Xc2=xZz{Mh|m660%Z~W&+8>=^h`k*QqI0{A!4HB
ziX4@-XbNhPS&Z6$ybuP2#4&OQN^TX}P`RSp@~4#N8JeSqF?{E?2D}yl?xTmk9;m&u
zZ`A$6keJ$J*{{5hYFq)nLTJF&&?ebuX29s%kQ2O9XDJ)!BOVvCzt7HY1ol#Zw0h{m
z{fet9JFK^i-lYcU_tHs;+1#$_n}3YEa+Il-MOL`?2Y#PW5t;hBbqSHYbu#lCu_GTv
zs81Z8S1M?5avIBDPHfpYj`*Qq23|+(LXQ`$PVcw1oClwwCt*IL$8eeB-3k}fkwyN2
zInbN}J%ZP|-I*fEoIN_xH?5Wsrj>VhFC*N-B{I~N(RHGw;-Gn5ye=^KTj<Zab>t>4
zF{?iQJ@WLHevqLu@QIzLL(R>sNFTVIGuzq&VJKmIfIFFC2bK-Fm7lnP-Db-+%d)Lt
zVYlXu2C3SZ?XIOX=R#Ar=BQ}oGN9jWmTny!D*(Q`D~`BGXB;+LcoeOcgmdVH`Nyz5
z)YIfqk<;{vUa|9!g66ExD>X^N5r8I~p!duYTQdJ>CtL#_q}UWRU)_`jyIlbX*ph{X
zW4o5pdm&%8r5$14#BiN3cUEIJu&YVg?7W^o)44{D8fjFdt2j@GD(jB1)VX=2-gBAQ
zAjA#0YAi}#D--&O*gNN6F$n3I<FLdPwOl&BFX55GX-ndPe-Y;C(2uR9(<;sMZ_r_Y
zKXqlRKMCO-zv>8!)(41|bu@*ro&melM5Bdfq6T$ryQu$DfwmB#UWfstC-?<F?!;IW
z{`rmz7@=Dq2H>uRWlHaLPl`BRspGxVWKY5OZ9ZdO_WT+=sFrRb1s7tEhAv4t!txma
z`fQ{m=ee;MwxI3ya9?%niP-!TkFaIkAIpck6%Men__@hJ2bjALP+EiYc-VtpotW=l
zIuWtlTW2Po25%*`quB0|CLV1>tl0I{8Tv!vkRL9vN>SiO(YzC0^Ydyk4tw9bCIxzU
zky(VVjkXtid+Ape{`z63sQgr&+qfmr;4r5&q|m-mq>QUH$({GtO@-S18b&)Q*Tlc4
zFhrj|boLUiy;O4wb`5<c;0};FCJuk1+)$=sNuj`Sa~4#m1;?&6RLxWy|Gtg=_z!KO
zjZUtsJv(!^WXF|w=zy#&DcqX)H&A_dHK(xvdOfIq{oJhwz2Lg?QS<vG&e4fEPnxLM
z+FJ{&mu%0^mWqN3?urfjfZ;#M^GOnzquRU;XzT8wBm~Zn*!lg$iiO91^6sz(@G9Rb
zVSMfe`|3ESr1vNpIs$PVwGafRhFrnFPF4*icMYQcQHV;;Nm9r}V24|};tp_@AM5&+
za1OCP7nMJ)vrn$V+0?bp)hW2nE{9R_J)E1|R0gykUxJ%RIgZw%c#(Ov{m$em|BKDa
zUg{kC$`qcxk>L`&?PTNtn{x&7xSdBmsNv1WyMs>P3swI=b&|C<#D9w6)5c~rXZhMm
zJZkn7$=#Il)+6Zp{W<bAQ^18JxPqk-IskPo?qu{5obm}!V;8)Mvc^H%yNo((8Lp?d
zSKSt_4t@o7OT~FK4xo98R^;4Z85#iLCBmZCjpiJ$tp0nsxcRpYeW&ibG10q~zS2XP
zR{$ot70u7FbzK)>^ZrZsaXQT9+>WC>YuBI?!zO{(SP)t|Up+VPTuB#>rKySId-6vd
z&KF`<Q#St=*Exzy>qg(i{0N-S`quUH;G5>}nK5ASUg;bylRfn-MC*6LNNric$X}Ho
z=v$*T>lGe=c3Q3r%#<BY={m2}Vj?i-0hW92v=;E91*za%ayMo68w9Mgw=QDWK^gq0
z?LcmB5bfzY?|+9KZlcx$Ic!kw%;npbsb6PVW0Lx(p%MQZC0j1?mMd|f<mtP=LAKjZ
zzf<*Ixcxirz4ZiCO+6Pag<!y){Nx9g-2n2A5PAhYoa>TSd!Nl(5xXv=_F4Wx<!t&O
zs_CXmcW?A;SMR@bpf}?zpGoV3`Z{v9>n^gi`{1~cSU^q!V%9x_FMX+BZy=wJO2<*C
z1kRZDLyEKg*3H%w1@?D{JG*PevmE2OmK%S#0yMRR9<YX(a{K+Jpd4cms)~n+kpK1p
NGQMr1|5?{Q>VHmRRPq1-

literal 0
HcmV?d00001

diff --git a/web/src/app/admin/configuration/llm/utils.ts b/web/src/app/admin/configuration/llm/utils.ts
index 9b61dd48e99..eba24b779e4 100644
--- a/web/src/app/admin/configuration/llm/utils.ts
+++ b/web/src/app/admin/configuration/llm/utils.ts
@@ -13,16 +13,19 @@ import {
   OpenAISVG,
   QwenIcon,
   OllamaIcon,
+  LMStudioIcon,
   ZAIIcon,
 } from "@/components/icons/icons";
 import {
   OllamaModelResponse,
   OpenRouterModelResponse,
   BedrockModelResponse,
+  LMStudioModelResponse,
   ModelConfiguration,
   LLMProviderName,
   BedrockFetchParams,
   OllamaFetchParams,
+  LMStudioFetchParams,
   OpenRouterFetchParams,
 } from "@/interfaces/llm";
 import { SvgAws, SvgOpenrouter } from "@opal/icons";
@@ -33,6 +36,7 @@ export const AGGREGATOR_PROVIDERS = new Set([
   "bedrock_converse",
   "openrouter",
   "ollama_chat",
+  "lm_studio",
   "vertex_ai",
 ]);
 
@@ -51,6 +55,7 @@ export const getProviderIcon = (
     llama: MetaIcon,
     ollama_chat: OllamaIcon,
     ollama: OllamaIcon,
+    lm_studio: LMStudioIcon,
     gemini: GeminiIcon,
     deepseek: DeepseekIcon,
     claude: AnthropicIcon,
@@ -140,7 +145,7 @@ export const fetchBedrockModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.detail || errorMessage;
+        errorMessage = errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
@@ -194,7 +199,7 @@ export const fetchOllamaModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.detail || errorMessage;
+        errorMessage = errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
@@ -252,7 +257,7 @@ export const fetchOpenRouterModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.detail || errorMessage;
+        errorMessage = errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
@@ -277,6 +282,62 @@ export const fetchOpenRouterModels = async (
   }
 };
 
+/**
+ * Fetches LM Studio models directly without any form state dependencies.
+ * Uses snake_case params to match API structure.
+ */
+export const fetchLMStudioModels = async (
+  params: LMStudioFetchParams
+): Promise<{ models: ModelConfiguration[]; error?: string }> => {
+  const apiBase = params.api_base;
+  if (!apiBase) {
+    return { models: [], error: "API Base is required" };
+  }
+
+  try {
+    const response = await fetch("/api/admin/llm/lm-studio/available-models", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        api_base: apiBase,
+        api_key: params.api_key,
+        api_key_changed: params.api_key_changed ?? false,
+        provider_name: params.provider_name,
+      }),
+      signal: params.signal,
+    });
+
+    if (!response.ok) {
+      let errorMessage = "Failed to fetch models";
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.message || errorMessage;
+      } catch {
+        // ignore JSON parsing errors
+      }
+      return { models: [], error: errorMessage };
+    }
+
+    const data: LMStudioModelResponse[] = await response.json();
+    const models: ModelConfiguration[] = data.map((modelData) => ({
+      name: modelData.name,
+      display_name: modelData.display_name,
+      is_visible: true,
+      max_input_tokens: modelData.max_input_tokens,
+      supports_image_input: modelData.supports_image_input,
+      supports_reasoning: modelData.supports_reasoning,
+    }));
+
+    return { models };
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    return { models: [], error: errorMessage };
+  }
+};
+
 /**
  * Fetches models for a provider. Accepts form values directly and maps them
  * to the expected fetch params format internally.
@@ -286,10 +347,12 @@ export const fetchModels = async (
   formValues: {
     api_base?: string;
     api_key?: string;
+    api_key_changed?: boolean;
     name?: string;
     custom_config?: Record<string, string>;
     model_configurations?: ModelConfiguration[];
-  }
+  },
+  signal?: AbortSignal
 ) => {
   const customConfig = formValues.custom_config || {};
 
@@ -306,6 +369,15 @@ export const fetchModels = async (
       return fetchOllamaModels({
         api_base: formValues.api_base,
         provider_name: formValues.name,
+        signal,
+      });
+    case LLMProviderName.LM_STUDIO:
+      return fetchLMStudioModels({
+        api_base: formValues.api_base,
+        api_key: formValues.custom_config?.LM_STUDIO_API_KEY,
+        api_key_changed: formValues.api_key_changed ?? false,
+        provider_name: formValues.name,
+        signal,
       });
     case LLMProviderName.OPENROUTER:
       return fetchOpenRouterModels({
@@ -323,6 +395,7 @@ export function canProviderFetchModels(providerName?: string) {
   switch (providerName) {
     case LLMProviderName.BEDROCK:
     case LLMProviderName.OLLAMA_CHAT:
+    case LLMProviderName.LM_STUDIO:
     case LLMProviderName.OPENROUTER:
       return true;
     default:
diff --git a/web/src/components/icons/icons.tsx b/web/src/components/icons/icons.tsx
index 2d999f6daae..7dc9689077e 100644
--- a/web/src/components/icons/icons.tsx
+++ b/web/src/components/icons/icons.tsx
@@ -56,6 +56,7 @@ import jiraSVG from "@public/Jira.svg";
 import kimiIcon from "@public/Kimi.png";
 import linearIcon from "@public/Linear.png";
 import litellmIcon from "@public/litellm.png";
+import lmStudioIcon from "@public/lm_studio.png";
 import mediawikiIcon from "@public/MediaWiki.svg";
 import metaSVG from "@public/Meta.svg";
 import microsoftIcon from "@public/microsoft.png";
@@ -880,6 +881,7 @@ export const CodaIcon = createLogoIcon(codaIcon);
 export const NotionIcon = createLogoIcon(notionIcon, { monochromatic: true });
 export const OCIStorageIcon = createLogoIcon(OCIStorageSVG);
 export const OllamaIcon = createLogoIcon(ollamaIcon);
+export const LMStudioIcon = createLogoIcon(lmStudioIcon);
 export const TestRailIcon = createLogoIcon(testrailSVG);
 export const OpenAIISVG = ({
   size = 16,
diff --git a/web/src/interfaces/llm.ts b/web/src/interfaces/llm.ts
index 5d01c4bb886..c0eb5add152 100644
--- a/web/src/interfaces/llm.ts
+++ b/web/src/interfaces/llm.ts
@@ -2,6 +2,7 @@ export enum LLMProviderName {
   OPENAI = "openai",
   ANTHROPIC = "anthropic",
   OLLAMA_CHAT = "ollama_chat",
+  LM_STUDIO = "lm_studio",
   AZURE = "azure",
   OPENROUTER = "openrouter",
   VERTEX_AI = "vertex_ai",
@@ -88,6 +89,14 @@ export interface BedrockModelResponse {
   supports_image_input: boolean;
 }
 
+export interface LMStudioModelResponse {
+  name: string;
+  display_name: string;
+  max_input_tokens: number | null;
+  supports_image_input: boolean;
+  supports_reasoning: boolean;
+}
+
 export interface DefaultModel {
   provider_id: number;
   model_name: string;
@@ -121,6 +130,14 @@ export interface OllamaFetchParams {
   signal?: AbortSignal;
 }
 
+export interface LMStudioFetchParams {
+  api_base?: string;
+  api_key?: string;
+  api_key_changed?: boolean;
+  provider_name?: string;
+  signal?: AbortSignal;
+}
+
 export interface OpenRouterFetchParams {
   api_base?: string;
   api_key?: string;
@@ -134,5 +151,6 @@ export interface VertexAIFetchParams {
 export type FetchModelsParams =
   | BedrockFetchParams
   | OllamaFetchParams
+  | LMStudioFetchParams
   | OpenRouterFetchParams
   | VertexAIFetchParams;
diff --git a/web/src/lib/llmConfig/providers.ts b/web/src/lib/llmConfig/providers.ts
index d8e294c58bd..3283cd9ad18 100644
--- a/web/src/lib/llmConfig/providers.ts
+++ b/web/src/lib/llmConfig/providers.ts
@@ -11,6 +11,7 @@ import {
   SvgAzure,
   SvgGemini,
   SvgLitellm,
+  SvgLmStudio,
 } from "@opal/icons";
 import { LLMProviderName } from "@/interfaces/llm";
 
@@ -23,6 +24,7 @@ const PROVIDER_ICONS: Record<string, IconFunctionComponent> = {
   litellm: SvgLitellm,
   [LLMProviderName.OLLAMA_CHAT]: SvgOllama,
   [LLMProviderName.OPENROUTER]: SvgOpenrouter,
+  [LLMProviderName.LM_STUDIO]: SvgLmStudio,
 
   // fallback
   [LLMProviderName.CUSTOM]: SvgServer,
@@ -37,6 +39,7 @@ const PROVIDER_PRODUCT_NAMES: Record<string, string> = {
   litellm: "LiteLLM",
   [LLMProviderName.OLLAMA_CHAT]: "Ollama",
   [LLMProviderName.OPENROUTER]: "OpenRouter",
+  [LLMProviderName.LM_STUDIO]: "LM Studio",
 
   // fallback
   [LLMProviderName.CUSTOM]: "Custom Models",
@@ -51,6 +54,7 @@ const PROVIDER_DISPLAY_NAMES: Record<string, string> = {
   litellm: "LiteLLM",
   [LLMProviderName.OLLAMA_CHAT]: "Ollama",
   [LLMProviderName.OPENROUTER]: "OpenRouter",
+  [LLMProviderName.LM_STUDIO]: "LM Studio",
 
   // fallback
   [LLMProviderName.CUSTOM]: "Other providers or self-hosted",
diff --git a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
index 5553c3927ea..1b557ea0917 100644
--- a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
+++ b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
@@ -43,6 +43,7 @@ import { BedrockModal } from "@/sections/modals/llmConfig/BedrockModal";
 import { VertexAIModal } from "@/sections/modals/llmConfig/VertexAIModal";
 import { OpenRouterModal } from "@/sections/modals/llmConfig/OpenRouterModal";
 import { CustomModal } from "@/sections/modals/llmConfig/CustomModal";
+import { LMStudioForm } from "@/sections/modals/llmConfig/LMStudioForm";
 import { Section } from "@/layouts/general-layouts";
 
 const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.LLM_MODELS]!;
@@ -108,6 +109,13 @@ const PROVIDER_MODAL_MAP: Record<
       onOpenChange={onOpenChange}
     />
   ),
+  lm_studio: (d, open, onOpenChange) => (
+    <LMStudioForm
+      shouldMarkAsDefault={d}
+      open={open}
+      onOpenChange={onOpenChange}
+    />
+  ),
 };
 
 // ============================================================================
diff --git a/web/src/sections/modals/llmConfig/LMStudioForm.tsx b/web/src/sections/modals/llmConfig/LMStudioForm.tsx
new file mode 100644
index 00000000000..d96784ee468
--- /dev/null
+++ b/web/src/sections/modals/llmConfig/LMStudioForm.tsx
@@ -0,0 +1,284 @@
+import { Form, Formik, FormikProps } from "formik";
+import { TextFormField } from "@/components/Field";
+import PasswordInputTypeInField from "@/refresh-components/form/PasswordInputTypeInField";
+import {
+  LLMProviderFormProps,
+  LLMProviderName,
+  LLMProviderView,
+  ModelConfiguration,
+} from "@/interfaces/llm";
+import * as Yup from "yup";
+import {
+  ProviderFormEntrypointWrapper,
+  ProviderFormContext,
+} from "./components/FormWrapper";
+import { DisplayNameField } from "./components/DisplayNameField";
+import { FormActionButtons } from "./components/FormActionButtons";
+import {
+  buildDefaultInitialValues,
+  buildDefaultValidationSchema,
+  buildAvailableModelConfigurations,
+  submitLLMProvider,
+  BaseLLMFormValues,
+  LLM_FORM_CLASS_NAME,
+} from "./formUtils";
+import { AdvancedOptions } from "./components/AdvancedOptions";
+import { DisplayModels } from "./components/DisplayModels";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { fetchModels } from "@/app/admin/configuration/llm/utils";
+import debounce from "lodash/debounce";
+
+const DEFAULT_API_BASE = "http://localhost:1234";
+
+interface LMStudioFormValues extends BaseLLMFormValues {
+  api_base: string;
+  custom_config: {
+    LM_STUDIO_API_KEY?: string;
+  };
+}
+
+interface LMStudioFormContentProps {
+  formikProps: FormikProps<LMStudioFormValues>;
+  existingLlmProvider?: LLMProviderView;
+  fetchedModels: ModelConfiguration[];
+  setFetchedModels: (models: ModelConfiguration[]) => void;
+  hasFetched: boolean;
+  setHasFetched: (value: boolean) => void;
+  isTesting: boolean;
+  testError: string;
+  mutate: () => void;
+  onClose: () => void;
+  isFormValid: boolean;
+}
+
+function LMStudioFormContent({
+  formikProps,
+  existingLlmProvider,
+  fetchedModels,
+  setFetchedModels,
+  hasFetched,
+  setHasFetched,
+  isTesting,
+  testError,
+  mutate,
+  onClose,
+  isFormValid,
+}: LMStudioFormContentProps) {
+  const [isLoadingModels, setIsLoadingModels] = useState(true);
+  const [fetchError, setFetchError] = useState<string | null>(null);
+
+  const initialApiKey =
+    (existingLlmProvider?.custom_config?.LM_STUDIO_API_KEY as string) ?? "";
+
+  const doFetchModels = useCallback(
+    (apiBase: string, apiKey: string | undefined, signal: AbortSignal) => {
+      setIsLoadingModels(true);
+      setFetchError(null);
+      fetchModels(
+        LLMProviderName.LM_STUDIO,
+        {
+          api_base: apiBase,
+          custom_config: apiKey ? { LM_STUDIO_API_KEY: apiKey } : {},
+          api_key_changed: apiKey !== initialApiKey,
+          name: existingLlmProvider?.name,
+        },
+        signal
+      )
+        .then((data) => {
+          if (signal.aborted) return;
+          if (data.error) {
+            setFetchError(data.error);
+            setHasFetched(false);
+            setFetchedModels([]);
+            return;
+          }
+          setHasFetched(true);
+          setFetchedModels(data.models);
+        })
+        .finally(() => {
+          if (!signal.aborted) {
+            setIsLoadingModels(false);
+          }
+        });
+    },
+    [existingLlmProvider?.name, initialApiKey, setFetchedModels]
+  );
+
+  const debouncedFetchModels = useMemo(
+    () => debounce(doFetchModels, 500),
+    [doFetchModels]
+  );
+
+  const apiBase = formikProps.values.api_base;
+  const apiKey = formikProps.values.custom_config?.LM_STUDIO_API_KEY;
+
+  useEffect(() => {
+    if (apiBase) {
+      const controller = new AbortController();
+      debouncedFetchModels(apiBase, apiKey, controller.signal);
+      return () => {
+        debouncedFetchModels.cancel();
+        controller.abort();
+      };
+    } else {
+      setIsLoadingModels(false);
+      setFetchedModels([]);
+      setFetchError(null);
+    }
+  }, [apiBase, apiKey, debouncedFetchModels, setFetchedModels]);
+
+  const currentModels = hasFetched
+    ? fetchedModels
+    : existingLlmProvider?.model_configurations || [];
+
+  return (
+    <Form className={LLM_FORM_CLASS_NAME}>
+      <DisplayNameField disabled={!!existingLlmProvider} />
+
+      <TextFormField
+        name="api_base"
+        label="API Base URL"
+        subtext="The base URL for your LM Studio server (e.g., http://localhost:1234)"
+        placeholder={DEFAULT_API_BASE}
+      />
+
+      <PasswordInputTypeInField
+        name="custom_config.LM_STUDIO_API_KEY"
+        label="API Key (Optional)"
+        subtext="Optional API key if your LM Studio server requires authentication."
+      />
+
+      {fetchError && currentModels.length > 0 && (
+        <p className="text-sm text-status-error-05">{fetchError}</p>
+      )}
+
+      <DisplayModels
+        modelConfigurations={currentModels}
+        formikProps={formikProps}
+        noModelConfigurationsMessage={
+          fetchError || "No models found. Please provide a valid API base URL."
+        }
+        isLoading={isLoadingModels}
+        recommendedDefaultModel={null}
+        shouldShowAutoUpdateToggle={false}
+      />
+
+      <AdvancedOptions formikProps={formikProps} />
+
+      <FormActionButtons
+        isTesting={isTesting}
+        testError={testError}
+        existingLlmProvider={existingLlmProvider}
+        mutate={mutate}
+        onClose={onClose}
+        isFormValid={isFormValid}
+      />
+    </Form>
+  );
+}
+
+export function LMStudioForm({
+  existingLlmProvider,
+  shouldMarkAsDefault,
+  open,
+  onOpenChange,
+}: LLMProviderFormProps) {
+  const [fetchedModels, setFetchedModels] = useState<ModelConfiguration[]>([]);
+  const [hasFetched, setHasFetched] = useState(false);
+
+  return (
+    <ProviderFormEntrypointWrapper
+      providerName="LM Studio"
+      existingLlmProvider={existingLlmProvider}
+      open={open}
+      onOpenChange={onOpenChange}
+    >
+      {({
+        onClose,
+        mutate,
+        isTesting,
+        setIsTesting,
+        testError,
+        setTestError,
+        wellKnownLLMProvider,
+      }: ProviderFormContext) => {
+        const modelConfigurations = buildAvailableModelConfigurations(
+          existingLlmProvider,
+          wellKnownLLMProvider
+        );
+        const initialValues: LMStudioFormValues = {
+          ...buildDefaultInitialValues(
+            existingLlmProvider,
+            modelConfigurations
+          ),
+          api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
+          custom_config: {
+            LM_STUDIO_API_KEY:
+              (existingLlmProvider?.custom_config
+                ?.LM_STUDIO_API_KEY as string) ?? "",
+          },
+        };
+
+        const validationSchema = buildDefaultValidationSchema().shape({
+          api_base: Yup.string().required("API Base URL is required"),
+        });
+
+        return (
+          <Formik
+            initialValues={initialValues}
+            validationSchema={validationSchema}
+            validateOnMount={true}
+            onSubmit={async (values, { setSubmitting }) => {
+              // Filter out empty custom_config values
+              const filteredCustomConfig = Object.fromEntries(
+                Object.entries(values.custom_config || {}).filter(
+                  ([, v]) => v !== ""
+                )
+              );
+
+              const submitValues = {
+                ...values,
+                custom_config:
+                  Object.keys(filteredCustomConfig).length > 0
+                    ? filteredCustomConfig
+                    : undefined,
+              };
+
+              await submitLLMProvider({
+                providerName: LLMProviderName.LM_STUDIO,
+                values: submitValues,
+                initialValues,
+                modelConfigurations: hasFetched
+                  ? fetchedModels
+                  : modelConfigurations,
+                existingLlmProvider,
+                shouldMarkAsDefault,
+                setIsTesting,
+                setTestError,
+                mutate,
+                onClose,
+                setSubmitting,
+              });
+            }}
+          >
+            {(formikProps) => (
+              <LMStudioFormContent
+                formikProps={formikProps}
+                existingLlmProvider={existingLlmProvider}
+                fetchedModels={fetchedModels}
+                setFetchedModels={setFetchedModels}
+                hasFetched={hasFetched}
+                setHasFetched={setHasFetched}
+                isTesting={isTesting}
+                testError={testError}
+                mutate={mutate}
+                onClose={onClose}
+                isFormValid={formikProps.isValid}
+              />
+            )}
+          </Formik>
+        );
+      }}
+    </ProviderFormEntrypointWrapper>
+  );
+}
diff --git a/web/src/sections/modals/llmConfig/getModal.tsx b/web/src/sections/modals/llmConfig/getModal.tsx
index 9f5c1ab4a0a..ebb411004fd 100644
--- a/web/src/sections/modals/llmConfig/getModal.tsx
+++ b/web/src/sections/modals/llmConfig/getModal.tsx
@@ -7,6 +7,7 @@ import { VertexAIModal } from "./VertexAIModal";
 import { OpenRouterModal } from "./OpenRouterModal";
 import { CustomModal } from "./CustomModal";
 import { BedrockModal } from "./BedrockModal";
+import { LMStudioForm } from "./LMStudioForm";
 
 export function detectIfRealOpenAIProvider(provider: LLMProviderView) {
   return (
@@ -44,6 +45,8 @@ export function getModalForExistingProvider(
       return <BedrockModal {...props} />;
     case LLMProviderName.OPENROUTER:
       return <OpenRouterModal {...props} />;
+    case LLMProviderName.LM_STUDIO:
+      return <LMStudioForm {...props} />;
     default:
       return <CustomModal {...props} />;
   }
diff --git a/web/src/sections/onboarding/forms/LMStudioOnboardingForm.tsx b/web/src/sections/onboarding/forms/LMStudioOnboardingForm.tsx
new file mode 100644
index 00000000000..2fae890c823
--- /dev/null
+++ b/web/src/sections/onboarding/forms/LMStudioOnboardingForm.tsx
@@ -0,0 +1,292 @@
+"use client";
+
+import { useMemo } from "react";
+import * as Yup from "yup";
+import { FormikField } from "@/refresh-components/form/FormikField";
+import { FormField } from "@/refresh-components/form/FormField";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
+import InputComboBox from "@/refresh-components/inputs/InputComboBox";
+import Separator from "@/refresh-components/Separator";
+import IconButton from "@/refresh-components/buttons/IconButton";
+import { cn, noProp } from "@/lib/utils";
+import { SvgRefreshCw } from "@opal/icons";
+import {
+  ModelConfiguration,
+  WellKnownLLMProviderDescriptor,
+} from "@/interfaces/llm";
+import {
+  OnboardingFormWrapper,
+  OnboardingFormChildProps,
+} from "./OnboardingFormWrapper";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
+import { buildInitialValues } from "../components/llmConnectionHelpers";
+import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
+import { ProviderIcon } from "@/app/admin/configuration/llm/ProviderIcon";
+
+// Field name constants
+const FIELD_API_BASE = "api_base";
+const FIELD_DEFAULT_MODEL_NAME = "default_model_name";
+const FIELD_LM_STUDIO_API_KEY = "custom_config.LM_STUDIO_API_KEY";
+
+const LM_STUDIO_DEFAULT_URL = "http://localhost:1234";
+
+interface LMStudioOnboardingFormProps {
+  llmDescriptor: WellKnownLLMProviderDescriptor;
+  onboardingState: OnboardingState;
+  onboardingActions: OnboardingActions;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+interface LMStudioFormValues {
+  name: string;
+  provider: string;
+  api_base: string;
+  api_key_changed: boolean;
+  default_model_name: string;
+  model_configurations: ModelConfiguration[];
+  groups: number[];
+  is_public: boolean;
+  custom_config: {
+    LM_STUDIO_API_KEY?: string;
+  };
+}
+
+function LMStudioFormFields(
+  props: OnboardingFormChildProps<LMStudioFormValues>
+) {
+  const {
+    formikProps,
+    apiStatus,
+    showApiMessage,
+    errorMessage,
+    modelOptions,
+    isFetchingModels,
+    handleFetchModels,
+    modelsApiStatus,
+    modelsErrorMessage,
+    showModelsApiErrorMessage,
+    disabled,
+  } = props;
+
+  const handleFetchOnBlur = () => {
+    if (formikProps.values.api_base) {
+      handleFetchModels();
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-4 w-full">
+      <FormikField<string>
+        name={FIELD_API_BASE}
+        render={(field, helper, meta, state) => (
+          <FormField name={FIELD_API_BASE} state={state} className="w-full">
+            <FormField.Label>API Base URL</FormField.Label>
+            <FormField.Control>
+              <InputTypeIn
+                {...field}
+                placeholder={LM_STUDIO_DEFAULT_URL}
+                variant={
+                  disabled
+                    ? "disabled"
+                    : apiStatus === "error"
+                      ? "error"
+                      : undefined
+                }
+                showClearButton={false}
+                onBlur={(e) => {
+                  field.onBlur(e);
+                  handleFetchOnBlur();
+                }}
+              />
+            </FormField.Control>
+            {showApiMessage && (
+              <FormField.APIMessage
+                state={apiStatus}
+                messages={{
+                  loading: "Checking connection to LM Studio...",
+                  success: "Connected successfully.",
+                  error: errorMessage || "Failed to connect",
+                }}
+              />
+            )}
+            {!showApiMessage && (
+              <FormField.Message
+                messages={{
+                  idle: "Your LM Studio server URL (default: http://localhost:1234).",
+                  error: meta.error,
+                }}
+              />
+            )}
+          </FormField>
+        )}
+      />
+
+      <FormikField<string>
+        name={FIELD_LM_STUDIO_API_KEY}
+        render={(field, helper, meta, state) => (
+          <FormField
+            name={FIELD_LM_STUDIO_API_KEY}
+            state={state}
+            className="w-full"
+          >
+            <FormField.Label>API Key (Optional)</FormField.Label>
+            <FormField.Control>
+              <PasswordInputTypeIn
+                {...field}
+                placeholder=""
+                disabled={disabled}
+                error={false}
+                showClearButton={false}
+                onBlur={(e) => {
+                  field.onBlur(e);
+                  handleFetchOnBlur();
+                }}
+              />
+            </FormField.Control>
+            <FormField.Message
+              messages={{
+                idle: "Optional API key if your LM Studio server requires authentication.",
+                error: meta.error,
+              }}
+            />
+          </FormField>
+        )}
+      />
+
+      <Separator className="my-0" />
+
+      <FormikField<string>
+        name={FIELD_DEFAULT_MODEL_NAME}
+        render={(field, helper, meta, state) => (
+          <FormField
+            name={FIELD_DEFAULT_MODEL_NAME}
+            state={state}
+            className="w-full"
+          >
+            <FormField.Label>Default Model</FormField.Label>
+            <FormField.Control>
+              <InputComboBox
+                value={field.value}
+                onValueChange={(value) => helper.setValue(value)}
+                onChange={(e) => helper.setValue(e.target.value)}
+                options={modelOptions}
+                disabled={disabled || isFetchingModels}
+                rightSection={
+                  <IconButton
+                    internal
+                    icon={({ className }) => (
+                      <SvgRefreshCw
+                        className={cn(
+                          className,
+                          isFetchingModels && "animate-spin"
+                        )}
+                      />
+                    )}
+                    onClick={noProp((e) => {
+                      e.preventDefault();
+                      handleFetchModels();
+                    })}
+                    tooltip="Fetch available models"
+                    disabled={disabled || isFetchingModels}
+                  />
+                }
+                onBlur={field.onBlur}
+                placeholder="Select a model"
+              />
+            </FormField.Control>
+            {showModelsApiErrorMessage && (
+              <FormField.APIMessage
+                state={modelsApiStatus}
+                messages={{
+                  loading: "Fetching models...",
+                  success: "Models fetched successfully.",
+                  error: modelsErrorMessage || "Failed to fetch models",
+                }}
+              />
+            )}
+            {!showModelsApiErrorMessage && (
+              <FormField.Message
+                messages={{
+                  idle: "This model will be used by Onyx by default.",
+                  error: meta.error,
+                }}
+              />
+            )}
+          </FormField>
+        )}
+      />
+    </div>
+  );
+}
+
+export function LMStudioOnboardingForm({
+  llmDescriptor,
+  onboardingState,
+  onboardingActions,
+  open,
+  onOpenChange,
+}: LMStudioOnboardingFormProps) {
+  const initialValues = useMemo(
+    (): LMStudioFormValues => ({
+      ...buildInitialValues(),
+      name: llmDescriptor.name,
+      provider: llmDescriptor.name,
+      api_base: LM_STUDIO_DEFAULT_URL,
+      custom_config: {
+        LM_STUDIO_API_KEY: "",
+      },
+    }),
+    [llmDescriptor.name]
+  );
+
+  const validationSchema = useMemo(
+    () =>
+      Yup.object().shape({
+        [FIELD_API_BASE]: Yup.string().required("API Base URL is required"),
+        [FIELD_DEFAULT_MODEL_NAME]: Yup.string().required(
+          "Model name is required"
+        ),
+      }),
+    []
+  );
+
+  const icon = () => (
+    <ConnectionProviderIcon
+      icon={<ProviderIcon provider={llmDescriptor.name} size={24} />}
+    />
+  );
+
+  return (
+    <OnboardingFormWrapper<LMStudioFormValues>
+      icon={icon}
+      title="Set up LM Studio"
+      description="Connect to your LM Studio models."
+      llmDescriptor={llmDescriptor}
+      onboardingState={onboardingState}
+      onboardingActions={onboardingActions}
+      open={open}
+      onOpenChange={onOpenChange}
+      initialValues={initialValues}
+      validationSchema={validationSchema}
+      transformValues={(values, fetchedModels) => {
+        // Filter out empty custom_config values
+        const filteredCustomConfig = Object.fromEntries(
+          Object.entries(values.custom_config || {}).filter(([, v]) => v !== "")
+        );
+
+        return {
+          ...values,
+          custom_config:
+            Object.keys(filteredCustomConfig).length > 0
+              ? filteredCustomConfig
+              : undefined,
+          model_configurations: fetchedModels,
+        };
+      }}
+    >
+      {(props) => <LMStudioFormFields {...props} />}
+    </OnboardingFormWrapper>
+  );
+}
diff --git a/web/src/sections/onboarding/forms/getOnboardingForm.tsx b/web/src/sections/onboarding/forms/getOnboardingForm.tsx
index 1d436d4f13d..90a56a4ebd0 100644
--- a/web/src/sections/onboarding/forms/getOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/getOnboardingForm.tsx
@@ -7,6 +7,7 @@ import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
 import { OpenAIOnboardingForm } from "./OpenAIOnboardingForm";
 import { AnthropicOnboardingForm } from "./AnthropicOnboardingForm";
 import { OllamaOnboardingForm } from "./OllamaOnboardingForm";
+import { LMStudioOnboardingForm } from "./LMStudioOnboardingForm";
 import { AzureOnboardingForm } from "./AzureOnboardingForm";
 import { BedrockOnboardingForm } from "./BedrockOnboardingForm";
 import { VertexAIOnboardingForm } from "./VertexAIOnboardingForm";
@@ -37,6 +38,10 @@ const PROVIDER_DISPLAY_INFO: Record<
     title: "OpenRouter",
     displayName: "OpenRouter",
   },
+  [LLMProviderName.LM_STUDIO]: {
+    title: "LM Studio",
+    displayName: "LM Studio",
+  },
 };
 
 export function getProviderDisplayInfo(providerName: string): {
@@ -115,6 +120,17 @@ export function getOnboardingForm({
         />
       );
 
+    case LLMProviderName.LM_STUDIO:
+      return (
+        <LMStudioOnboardingForm
+          llmDescriptor={llmDescriptor}
+          onboardingState={onboardingState}
+          onboardingActions={onboardingActions}
+          open={open}
+          onOpenChange={onOpenChange}
+        />
+      );
+
     case LLMProviderName.AZURE:
       return (
         <AzureOnboardingForm

From 189c07a9139a33e9f39631d232efdbc85a7bec67 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Thu, 5 Mar 2026 17:20:18 -0800
Subject: [PATCH 131/267] chore(devtools): AGENTS.md warns against enqueueing
 tasks without an expiration (#8654)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 AGENTS.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 9b6f5a3ddaa..bfabe9c991f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -104,6 +104,10 @@ Onyx uses Celery for asynchronous task processing with multiple specialized work
 
 - Always use `@shared_task` rather than `@celery_app`
 - Put tasks under `background/celery/tasks/` or `ee/background/celery/tasks`
+- Never enqueue a task without an expiration. Always supply `expires=` when
+  sending tasks, either from the beat schedule or directly from another task. It
+  should never be acceptable to submit code which enqueues tasks without an
+  expiration, as doing so can lead to unbounded task queue growth.
 
 **Defining APIs**:
 When creating new FastAPI APIs, do NOT use the `response_model` field. Instead, just type the

From ae893079c33f7bf8f5da5ad4ad8ca46e646b6952 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Thu, 5 Mar 2026 17:20:40 -0800
Subject: [PATCH 132/267] chore(documentation): Add comment in
 `contributing_guides/best_practices.md` about async (#8759)

---
 contributing_guides/best_practices.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/contributing_guides/best_practices.md b/contributing_guides/best_practices.md
index 2556d17d74a..de67375fd8d 100644
--- a/contributing_guides/best_practices.md
+++ b/contributing_guides/best_practices.md
@@ -92,6 +92,12 @@ Add clear comments:
 - Connector code (data → Onyx documents):
   - Any in-memory structure that can grow without bound based on input must be periodically size-checked.
   - If a connector is OOMing (often shows up as “missing celery tasks”), this is a top thing to check retroactively.
+- Async and event loops:
+  - Never introduce new async/event loop Python code, and try to make existing
+    async code synchronous when possible if it makes sense.
+    - Writing async code without 100% understanding the code and having a
+      concrete reason to do so is likely to introduce bugs and not add any
+      meaningful performance gains.
 
 ---
 

From 3f004cf02febc20effb291153d9743513c951a48 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Thu, 5 Mar 2026 17:23:13 -0800
Subject: [PATCH 133/267] chore(opensearch): Debug util script (#8815)

---
 .../onyx/document_index/opensearch/client.py  |  55 +++++-
 .../opensearch/opensearch_document_index.py   |  32 ++--
 .../onyx/document_index/opensearch/schema.py  |  22 ++-
 .../debugging/opensearch/opensearch_debug.py  | 171 ++++++++++++++++++
 4 files changed, 257 insertions(+), 23 deletions(-)
 create mode 100644 backend/scripts/debugging/opensearch/opensearch_debug.py

diff --git a/backend/onyx/document_index/opensearch/client.py b/backend/onyx/document_index/opensearch/client.py
index 7fe80358796..351bbe89278 100644
--- a/backend/onyx/document_index/opensearch/client.py
+++ b/backend/onyx/document_index/opensearch/client.py
@@ -61,6 +61,25 @@ class SearchHit(BaseModel, Generic[SchemaDocumentModel]):
     explanation: dict[str, Any] | None = None
 
 
+class IndexInfo(BaseModel):
+    """
+    Represents information about an OpenSearch index.
+    """
+
+    model_config = {"frozen": True}
+
+    name: str
+    health: str
+    status: str
+    num_primary_shards: str
+    num_replica_shards: str
+    docs_count: str
+    docs_deleted: str
+    created_at: str
+    total_size: str
+    primary_shards_size: str
+
+
 def get_new_body_without_vectors(body: dict[str, Any]) -> dict[str, Any]:
     """Recursively replaces vectors in the body with their length.
 
@@ -159,8 +178,8 @@ def create_search_pipeline(
         Raises:
             Exception: There was an error creating the search pipeline.
         """
-        result = self._client.search_pipeline.put(id=pipeline_id, body=pipeline_body)
-        if not result.get("acknowledged", False):
+        response = self._client.search_pipeline.put(id=pipeline_id, body=pipeline_body)
+        if not response.get("acknowledged", False):
             raise RuntimeError(f"Failed to create search pipeline {pipeline_id}.")
 
     @log_function_time(print_only=True, debug_only=True, include_args=True)
@@ -173,8 +192,8 @@ def delete_search_pipeline(self, pipeline_id: str) -> None:
         Raises:
             Exception: There was an error deleting the search pipeline.
         """
-        result = self._client.search_pipeline.delete(id=pipeline_id)
-        if not result.get("acknowledged", False):
+        response = self._client.search_pipeline.delete(id=pipeline_id)
+        if not response.get("acknowledged", False):
             raise RuntimeError(f"Failed to delete search pipeline {pipeline_id}.")
 
     @log_function_time(print_only=True, debug_only=True, include_args=True)
@@ -198,6 +217,34 @@ def put_cluster_settings(self, settings: dict[str, Any]) -> bool:
             logger.error(f"Failed to put cluster settings: {response}.")
             return False
 
+    @log_function_time(print_only=True, debug_only=True)
+    def list_indices_with_info(self) -> list[IndexInfo]:
+        """
+        Lists the indices in the OpenSearch cluster with information about each
+        index.
+
+        Returns:
+            A list of IndexInfo objects for each index.
+        """
+        response = self._client.cat.indices(format="json")
+        indices: list[IndexInfo] = []
+        for raw_index_info in response:
+            indices.append(
+                IndexInfo(
+                    name=raw_index_info.get("index", ""),
+                    health=raw_index_info.get("health", ""),
+                    status=raw_index_info.get("status", ""),
+                    num_primary_shards=raw_index_info.get("pri", ""),
+                    num_replica_shards=raw_index_info.get("rep", ""),
+                    docs_count=raw_index_info.get("docs.count", ""),
+                    docs_deleted=raw_index_info.get("docs.deleted", ""),
+                    created_at=raw_index_info.get("creation.date.string", ""),
+                    total_size=raw_index_info.get("store.size", ""),
+                    primary_shards_size=raw_index_info.get("pri.store.size", ""),
+                )
+            )
+        return indices
+
     @log_function_time(print_only=True, debug_only=True)
     def ping(self) -> bool:
         """Pings the OpenSearch cluster.
diff --git a/backend/onyx/document_index/opensearch/opensearch_document_index.py b/backend/onyx/document_index/opensearch/opensearch_document_index.py
index 035faa1b87a..62dfdaa8ba9 100644
--- a/backend/onyx/document_index/opensearch/opensearch_document_index.py
+++ b/backend/onyx/document_index/opensearch/opensearch_document_index.py
@@ -739,7 +739,8 @@ def delete(
             The number of chunks successfully deleted.
         """
         logger.debug(
-            f"[OpenSearchDocumentIndex] Deleting document {document_id} from index {self._index_name}."
+            f"[OpenSearchDocumentIndex] Deleting document {document_id} from index "
+            f"{self._index_name}."
         )
         query_body = DocumentQuery.delete_from_document_id_query(
             document_id=document_id,
@@ -775,7 +776,8 @@ def update(
                 specified documents.
         """
         logger.debug(
-            f"[OpenSearchDocumentIndex] Updating {len(update_requests)} chunks for index {self._index_name}."
+            f"[OpenSearchDocumentIndex] Updating {len(update_requests)} chunks for index "
+            f"{self._index_name}."
         )
         for update_request in update_requests:
             properties_to_update: dict[str, Any] = dict()
@@ -831,9 +833,11 @@ def update(
                     # here.
                     # TODO(andrei): Fix the aforementioned race condition.
                     raise ChunkCountNotFoundError(
-                        f"Tried to update document {doc_id} but its chunk count is not known. Older versions of the "
-                        "application used to permit this but is not a supported state for a document when using OpenSearch. "
-                        "The document was likely just added to the indexing pipeline and the chunk count will be updated shortly."
+                        f"Tried to update document {doc_id} but its chunk count is not known. "
+                        "Older versions of the application used to permit this but is not a "
+                        "supported state for a document when using OpenSearch. The document was "
+                        "likely just added to the indexing pipeline and the chunk count will be "
+                        "updated shortly."
                     )
                 if doc_chunk_count == 0:
                     raise ValueError(
@@ -865,7 +869,8 @@ def id_based_retrieval(
         chunk IDs vs querying for matching document chunks.
         """
         logger.debug(
-            f"[OpenSearchDocumentIndex] Retrieving {len(chunk_requests)} chunks for index {self._index_name}."
+            f"[OpenSearchDocumentIndex] Retrieving {len(chunk_requests)} chunks for index "
+            f"{self._index_name}."
         )
         results: list[InferenceChunk] = []
         for chunk_request in chunk_requests:
@@ -912,7 +917,8 @@ def hybrid_retrieval(
         num_to_retrieve: int,
     ) -> list[InferenceChunk]:
         logger.debug(
-            f"[OpenSearchDocumentIndex] Hybrid retrieving {num_to_retrieve} chunks for index {self._index_name}."
+            f"[OpenSearchDocumentIndex] Hybrid retrieving {num_to_retrieve} chunks for index "
+            f"{self._index_name}."
         )
         # TODO(andrei): This could be better, the caller should just make this
         # decision when passing in the query param. See the above comment in the
@@ -932,8 +938,10 @@ def hybrid_retrieval(
             index_filters=filters,
             include_hidden=False,
         )
-        # NOTE: Using z-score normalization here because it's better for hybrid search from a theoretical standpoint.
-        # Empirically on a small dataset of up to 10K docs, it's not very different. Likely more impactful at scale.
+        # NOTE: Using z-score normalization here because it's better for hybrid
+        # search from a theoretical standpoint. Empirically on a small dataset
+        # of up to 10K docs, it's not very different. Likely more impactful at
+        # scale.
         # https://opensearch.org/blog/introducing-the-z-score-normalization-technique-for-hybrid-search/
         search_hits: list[SearchHit[DocumentChunk]] = self._client.search(
             body=query_body,
@@ -960,7 +968,8 @@ def random_retrieval(
         dirty: bool | None = None,  # noqa: ARG002
     ) -> list[InferenceChunk]:
         logger.debug(
-            f"[OpenSearchDocumentIndex] Randomly retrieving {num_to_retrieve} chunks for index {self._index_name}."
+            f"[OpenSearchDocumentIndex] Randomly retrieving {num_to_retrieve} chunks for index "
+            f"{self._index_name}."
         )
         query_body = DocumentQuery.get_random_search_query(
             tenant_state=self._tenant_state,
@@ -990,7 +999,8 @@ def index_raw_chunks(self, chunks: list[DocumentChunk]) -> None:
         complete.
         """
         logger.debug(
-            f"[OpenSearchDocumentIndex] Indexing {len(chunks)} raw chunks for index {self._index_name}."
+            f"[OpenSearchDocumentIndex] Indexing {len(chunks)} raw chunks for index "
+            f"{self._index_name}."
         )
         # Do not raise if the document already exists, just update. This is
         # because the document may already have been indexed during the
diff --git a/backend/onyx/document_index/opensearch/schema.py b/backend/onyx/document_index/opensearch/schema.py
index a43ec897747..10e8a19792d 100644
--- a/backend/onyx/document_index/opensearch/schema.py
+++ b/backend/onyx/document_index/opensearch/schema.py
@@ -243,7 +243,8 @@ def parse_epoch_seconds_to_datetime(cls, value: Any) -> datetime | None:
             return value
         if not isinstance(value, int):
             raise ValueError(
-                f"Bug: Expected an int for the last_updated property from OpenSearch, got {type(value)} instead."
+                f"Bug: Expected an int for the last_updated property from OpenSearch, got "
+                f"{type(value)} instead."
             )
         return datetime.fromtimestamp(value, tz=timezone.utc)
 
@@ -284,19 +285,22 @@ def parse_tenant_id(cls, value: Any) -> TenantState:
         elif isinstance(value, TenantState):
             if MULTI_TENANT != value.multitenant:
                 raise ValueError(
-                    f"Bug: An existing TenantState object was supplied to the DocumentChunk model but its multi-tenant mode "
-                    f"({value.multitenant}) does not match the program's current global tenancy state."
+                    f"Bug: An existing TenantState object was supplied to the DocumentChunk model "
+                    f"but its multi-tenant mode ({value.multitenant}) does not match the program's "
+                    "current global tenancy state."
                 )
             return value
         elif not isinstance(value, str):
             raise ValueError(
-                f"Bug: Expected a str for the tenant_id property from OpenSearch, got {type(value)} instead."
+                f"Bug: Expected a str for the tenant_id property from OpenSearch, got "
+                f"{type(value)} instead."
             )
         else:
             if not MULTI_TENANT:
                 raise ValueError(
-                    "Bug: Got a non-null str for the tenant_id property from OpenSearch but multi-tenant mode is not enabled. "
-                    "This is unexpected because in single-tenant mode we don't expect to see a tenant_id."
+                    "Bug: Got a non-null str for the tenant_id property from OpenSearch but "
+                    "multi-tenant mode is not enabled. This is unexpected because in single-tenant "
+                    "mode we don't expect to see a tenant_id."
                 )
             return TenantState(tenant_id=value, multitenant=MULTI_TENANT)
 
@@ -352,8 +356,10 @@ def get_document_schema(vector_dimension: int, multitenant: bool) -> dict[str, A
             "properties": {
                 TITLE_FIELD_NAME: {
                     "type": "text",
-                    # Language analyzer (e.g. english) stems at index and search time for variant matching.
-                    # Configure via OPENSEARCH_TEXT_ANALYZER. Existing indices need reindexing after a change.
+                    # Language analyzer (e.g. english) stems at index and search
+                    # time for variant matching. Configure via
+                    # OPENSEARCH_TEXT_ANALYZER. Existing indices need reindexing
+                    # after a change.
                     "analyzer": OPENSEARCH_TEXT_ANALYZER,
                     "fields": {
                         # Subfield accessed as title.keyword. Not indexed for
diff --git a/backend/scripts/debugging/opensearch/opensearch_debug.py b/backend/scripts/debugging/opensearch/opensearch_debug.py
new file mode 100644
index 00000000000..cc14ad4c735
--- /dev/null
+++ b/backend/scripts/debugging/opensearch/opensearch_debug.py
@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""A utility to interact with OpenSearch.
+
+Usage:
+    python3 opensearch_debug.py --help
+    python3 opensearch_debug.py list
+    python3 opensearch_debug.py delete <index_name>
+
+Environment Variables:
+    OPENSEARCH_HOST: OpenSearch host
+    OPENSEARCH_REST_API_PORT: OpenSearch port
+    OPENSEARCH_ADMIN_USERNAME: Admin username
+    OPENSEARCH_ADMIN_PASSWORD: Admin password
+
+Dependencies:
+    backend/shared_configs/configs.py
+    backend/onyx/document_index/opensearch/client.py
+"""
+
+import argparse
+import os
+import sys
+
+from onyx.document_index.opensearch.client import OpenSearchClient
+from onyx.document_index.opensearch.client import OpenSearchIndexClient
+from shared_configs.configs import MULTI_TENANT
+
+
+def list_indices(client: OpenSearchClient) -> None:
+    indices = client.list_indices_with_info()
+    print(f"Found {len(indices)} indices.")
+    print("-" * 80)
+    for index in sorted(indices, key=lambda x: x.name):
+        print(f"Index: {index.name}")
+        print(f"Health: {index.health}")
+        print(f"Status: {index.status}")
+        print(f"Num Primary Shards: {index.num_primary_shards}")
+        print(f"Num Replica Shards: {index.num_replica_shards}")
+        print(f"Docs Count: {index.docs_count}")
+        print(f"Docs Deleted: {index.docs_deleted}")
+        print(f"Created At: {index.created_at}")
+        print(f"Total Size: {index.total_size}")
+        print(f"Primary Shards Size: {index.primary_shards_size}")
+        print("-" * 80)
+
+
+def delete_index(client: OpenSearchIndexClient) -> None:
+    if not client.index_exists():
+        print(f"Index '{client._index_name}' does not exist.")
+        return
+
+    confirm = input(f"Delete index '{client._index_name}'? (yes/no): ")
+    if confirm.lower() != "yes":
+        print("Aborted.")
+        return
+
+    if client.delete_index():
+        print(f"Deleted index '{client._index_name}'.")
+    else:
+        print(f"Failed to delete index '{client._index_name}' for an unknown reason.")
+
+
+def main() -> None:
+    def add_standard_arguments(parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--host",
+            help="OpenSearch host. If not provided, will fall back to OPENSEARCH_HOST, then prompt "
+            "for input.",
+            type=str,
+            default=os.environ.get("OPENSEARCH_HOST", ""),
+        )
+        parser.add_argument(
+            "--port",
+            help="OpenSearch port. If not provided, will fall back to OPENSEARCH_REST_API_PORT, "
+            "then prompt for input.",
+            type=int,
+            default=int(os.environ.get("OPENSEARCH_REST_API_PORT", 0)),
+        )
+        parser.add_argument(
+            "--username",
+            help="OpenSearch username. If not provided, will fall back to OPENSEARCH_ADMIN_USERNAME, "
+            "then prompt for input.",
+            type=str,
+            default=os.environ.get("OPENSEARCH_ADMIN_USERNAME", ""),
+        )
+        parser.add_argument(
+            "--password",
+            help="OpenSearch password. If not provided, will fall back to OPENSEARCH_ADMIN_PASSWORD, "
+            "then prompt for input.",
+            type=str,
+            default=os.environ.get("OPENSEARCH_ADMIN_PASSWORD", ""),
+        )
+        parser.add_argument(
+            "--no-ssl", help="Disable SSL.", action="store_true", default=False
+        )
+        parser.add_argument(
+            "--no-verify-certs",
+            help="Disable certificate verification (for self-signed certs).",
+            action="store_true",
+            default=False,
+        )
+        parser.add_argument(
+            "--use-aws-managed-opensearch",
+            help="Whether to use AWS-managed OpenSearch. If not provided, will fall back to checking "
+            "USING_AWS_MANAGED_OPENSEARCH=='true', then default to False.",
+            action=argparse.BooleanOptionalAction,
+            default=os.environ.get("USING_AWS_MANAGED_OPENSEARCH", "").lower()
+            == "true",
+        )
+
+    parser = argparse.ArgumentParser(
+        description="A utility to interact with OpenSearch."
+    )
+    subparsers = parser.add_subparsers(
+        dest="command", help="Command to execute.", required=True
+    )
+
+    list_parser = subparsers.add_parser("list", help="List all indices with info.")
+    add_standard_arguments(list_parser)
+
+    delete_parser = subparsers.add_parser("delete", help="Delete an index.")
+    delete_parser.add_argument("index", help="Index name.", type=str)
+    add_standard_arguments(delete_parser)
+
+    args = parser.parse_args()
+
+    if not (host := args.host or input("Enter the OpenSearch host: ")):
+        print("Error: OpenSearch host is required.")
+        sys.exit(1)
+    if not (port := args.port or int(input("Enter the OpenSearch port: "))):
+        print("Error: OpenSearch port is required.")
+        sys.exit(1)
+    if not (username := args.username or input("Enter the OpenSearch username: ")):
+        print("Error: OpenSearch username is required.")
+        sys.exit(1)
+    if not (password := args.password or input("Enter the OpenSearch password: ")):
+        print("Error: OpenSearch password is required.")
+        sys.exit(1)
+    print("Using AWS-managed OpenSearch: ", args.use_aws_managed_opensearch)
+    print(f"MULTI_TENANT: {MULTI_TENANT}")
+
+    with (
+        OpenSearchIndexClient(
+            index_name=args.index,
+            host=host,
+            port=port,
+            auth=(username, password),
+            use_ssl=not args.no_ssl,
+            verify_certs=not args.no_verify_certs,
+        )
+        if args.command == "delete"
+        else OpenSearchClient(
+            host=host,
+            port=port,
+            auth=(username, password),
+            use_ssl=not args.no_ssl,
+            verify_certs=not args.no_verify_certs,
+        )
+    ) as client:
+        if not client.ping():
+            print("Error: Could not connect to OpenSearch.")
+            sys.exit(1)
+
+        if args.command == "list":
+            list_indices(client)
+        elif args.command == "delete":
+            delete_index(client)
+
+
+if __name__ == "__main__":
+    main()

From dde7a18bb7a4613154bf0fdc8565b671517f1566 Mon Sep 17 00:00:00 2001
From: Bo-Onyx <bo@onyx.app>
Date: Thu, 5 Mar 2026 17:31:50 -0800
Subject: [PATCH 134/267] fix(dr-opti): Fix snippet matcher for special
 characters (#9123)

---
 .../open_url/snippet_matcher.py               | 27 ++++++-----
 ...pet_finding.py => test_snippet_matcher.py} | 45 +++++++++++++++++++
 2 files changed, 62 insertions(+), 10 deletions(-)
 rename backend/tests/unit/onyx/tools/tool_implementations/open_url/{test_snippet_finding.py => test_snippet_matcher.py} (72%)

diff --git a/backend/onyx/tools/tool_implementations/open_url/snippet_matcher.py b/backend/onyx/tools/tool_implementations/open_url/snippet_matcher.py
index b9d1fe0c00f..7c8c078ae03 100644
--- a/backend/onyx/tools/tool_implementations/open_url/snippet_matcher.py
+++ b/backend/onyx/tools/tool_implementations/open_url/snippet_matcher.py
@@ -111,19 +111,26 @@ def _normalize_text_with_mapping(text: str) -> tuple[str, list[int]]:
     # Step 1: NFC normalization with position mapping
     nfc_text = unicodedata.normalize("NFC", text)
 
-    # Build mapping from NFC positions to original start positions
+    # Map NFD positions → original positions.
+    # NFD only decomposes, so each original char produces 1+ NFD chars.
+    nfd_to_orig: list[int] = []
+    for orig_idx, orig_char in enumerate(original_text):
+        nfd_of_char = unicodedata.normalize("NFD", orig_char)
+        for _ in nfd_of_char:
+            nfd_to_orig.append(orig_idx)
+
+    # Map NFC positions → NFD positions.
+    # Each NFC char, when decomposed, tells us exactly how many NFD
+    # chars it was composed from.
     nfc_to_orig: list[int] = []
-    orig_idx = 0
+    nfd_idx = 0
     for nfc_char in nfc_text:
-        nfc_to_orig.append(orig_idx)
-        # Find how many original chars contributed to this NFC char
-        for length in range(1, len(original_text) - orig_idx + 1):
-            substr = original_text[orig_idx : orig_idx + length]
-            if unicodedata.normalize("NFC", substr) == nfc_char:
-                orig_idx += length
-                break
+        if nfd_idx < len(nfd_to_orig):
+            nfc_to_orig.append(nfd_to_orig[nfd_idx])
         else:
-            orig_idx += 1  # Fallback
+            nfc_to_orig.append(len(original_text) - 1)
+        nfd_of_nfc = unicodedata.normalize("NFD", nfc_char)
+        nfd_idx += len(nfd_of_nfc)
 
     # Work with NFC text from here
     text = nfc_text
diff --git a/backend/tests/unit/onyx/tools/tool_implementations/open_url/test_snippet_finding.py b/backend/tests/unit/onyx/tools/tool_implementations/open_url/test_snippet_matcher.py
similarity index 72%
rename from backend/tests/unit/onyx/tools/tool_implementations/open_url/test_snippet_finding.py
rename to backend/tests/unit/onyx/tools/tool_implementations/open_url/test_snippet_matcher.py
index 43ba1905fcc..0d1cf1b302c 100644
--- a/backend/tests/unit/onyx/tools/tool_implementations/open_url/test_snippet_finding.py
+++ b/backend/tests/unit/onyx/tools/tool_implementations/open_url/test_snippet_matcher.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import unicodedata  # used to verify NFC expansion test preconditions
 from pathlib import Path
 
 import pytest
@@ -158,3 +159,47 @@ def test_snippet_finding(test_data: TestSchema) -> None:
         f"end_idx mismatch: expected {test_data.expected_result.expected_end_idx}, "
         f"got {result.end_idx}"
     )
+
+
+# Characters confirmed to expand from 1 → 2 codepoints under NFC
+NFC_EXPANDING_CHARS = [
+    ("\u0958", "Devanagari letter qa"),
+    ("\u0959", "Devanagari letter khha"),
+    ("\u095a", "Devanagari letter ghha"),
+]
+
+
+@pytest.mark.parametrize(
+    "char,description",
+    NFC_EXPANDING_CHARS,
+)
+def test_nfc_expanding_char_snippet_match(char: str, description: str) -> None:
+    """Snippet matching should produce valid indices for content
+    containing characters that expand under NFC normalization."""
+    nfc = unicodedata.normalize("NFC", char)
+    if len(nfc) <= 1:
+        pytest.skip(f"{description} does not expand under NFC on this platform")
+
+    content = f"before {char} after"
+    snippet = f"{char} after"
+
+    result = find_snippet_in_content(content, snippet)
+
+    assert result.snippet_located, f"[{description}] Snippet should be found in content"
+    assert (
+        0 <= result.start_idx < len(content)
+    ), f"[{description}] start_idx {result.start_idx} out of bounds"
+    assert (
+        0 <= result.end_idx < len(content)
+    ), f"[{description}] end_idx {result.end_idx} out of bounds"
+    assert (
+        result.start_idx <= result.end_idx
+    ), f"[{description}] start_idx {result.start_idx} > end_idx {result.end_idx}"
+
+    matched = content[result.start_idx : result.end_idx + 1]
+    matched_nfc = unicodedata.normalize("NFC", matched)
+    snippet_nfc = unicodedata.normalize("NFC", snippet)
+    assert snippet_nfc in matched_nfc or matched_nfc in snippet_nfc, (
+        f"[{description}] Matched span '{matched}' does not overlap "
+        f"with expected snippet '{snippet}'"
+    )

From d2d4b89286c0280c131234337643cd4bc7b7edfd Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 17:32:06 -0800
Subject: [PATCH 135/267] chore(deps): rm `google-cloud-aiplatform` (#9114)

---
 backend/requirements/default.txt      |  71 +--------
 backend/requirements/dev.txt          |  78 +--------
 backend/requirements/ee.txt           |  81 +---------
 backend/requirements/model_server.txt |  78 +--------
 pyproject.toml                        |   1 -
 uv.lock                               | 219 --------------------------
 6 files changed, 8 insertions(+), 520 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 94806b315ef..6667091a349 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -229,9 +229,7 @@ distro==1.9.0
 dnspython==2.8.0
     # via email-validator
 docstring-parser==0.17.0
-    # via
-    #   cyclopts
-    #   google-cloud-aiplatform
+    # via cyclopts
 docutils==0.22.3
     # via rich-rst
 dropbox==12.0.2
@@ -296,13 +294,7 @@ gitdb==4.0.12
 gitpython==3.1.45
     # via braintrust
 google-api-core==2.28.1
-    # via
-    #   google-api-python-client
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
+    # via google-api-python-client
 google-api-python-client==2.86.0
     # via onyx
 google-auth==2.48.0
@@ -311,11 +303,6 @@ google-auth==2.48.0
     #   google-api-python-client
     #   google-auth-httplib2
     #   google-auth-oauthlib
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
     #   google-genai
     #   kubernetes
 google-auth-httplib2==0.1.0
@@ -324,51 +311,16 @@ google-auth-httplib2==0.1.0
     #   onyx
 google-auth-oauthlib==1.0.0
     # via onyx
-google-cloud-aiplatform==1.133.0
-    # via onyx
-google-cloud-bigquery==3.38.0
-    # via google-cloud-aiplatform
-google-cloud-core==2.5.0
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-google-cloud-resource-manager==1.15.0
-    # via google-cloud-aiplatform
-google-cloud-storage==2.19.0
-    # via google-cloud-aiplatform
-google-crc32c==1.7.1
-    # via
-    #   google-cloud-storage
-    #   google-resumable-media
 google-genai==1.52.0
-    # via
-    #   google-cloud-aiplatform
-    #   onyx
-google-resumable-media==2.7.2
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
+    # via onyx
 googleapis-common-protos==1.72.0
     # via
     #   google-api-core
-    #   grpc-google-iam-v1
-    #   grpcio-status
     #   opentelemetry-exporter-otlp-proto-http
 greenlet==3.2.4
     # via
     #   playwright
     #   sqlalchemy
-grpc-google-iam-v1==0.14.3
-    # via google-cloud-resource-manager
-grpcio==1.76.0
-    # via
-    #   google-api-core
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-grpcio-status==1.76.0
-    # via google-api-core
 h11==0.16.0
     # via
     #   httpcore
@@ -669,8 +621,6 @@ packaging==24.2
     #   dask
     #   distributed
     #   fastmcp
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
     #   huggingface-hub
     #   jira
     #   kombu
@@ -720,19 +670,12 @@ propcache==0.4.1
     #   aiohttp
     #   yarl
 proto-plus==1.26.1
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
+    # via google-api-core
 protobuf==6.33.5
     # via
     #   ddtrace
     #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
     #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
     #   onnxruntime
     #   opentelemetry-proto
     #   proto-plus
@@ -770,7 +713,6 @@ pydantic==2.11.7
     #   exa-py
     #   fastapi
     #   fastmcp
-    #   google-cloud-aiplatform
     #   google-genai
     #   langchain-core
     #   langfuse
@@ -834,7 +776,6 @@ python-dateutil==2.8.2
     #   botocore
     #   celery
     #   dateparser
-    #   google-cloud-bigquery
     #   htmldate
     #   hubspot-api-client
     #   kubernetes
@@ -926,8 +867,6 @@ requests==2.32.5
     #   dropbox
     #   exa-py
     #   google-api-core
-    #   google-cloud-bigquery
-    #   google-cloud-storage
     #   google-genai
     #   hubspot-api-client
     #   huggingface-hub
@@ -1115,9 +1054,7 @@ typing-extensions==4.15.0
     #   exa-py
     #   exceptiongroup
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
-    #   grpcio
     #   huggingface-hub
     #   jira
     #   langchain-core
diff --git a/backend/requirements/dev.txt b/backend/requirements/dev.txt
index dfde5cf6dfe..1945f138f1f 100644
--- a/backend/requirements/dev.txt
+++ b/backend/requirements/dev.txt
@@ -115,8 +115,6 @@ distlib==0.4.0
     # via virtualenv
 distro==1.9.0
     # via openai
-docstring-parser==0.17.0
-    # via google-cloud-aiplatform
 durationpy==0.10
     # via kubernetes
 execnet==2.1.2
@@ -145,65 +143,14 @@ frozenlist==1.8.0
     #   aiosignal
 fsspec==2025.10.0
     # via huggingface-hub
-google-api-core==2.28.1
-    # via
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
 google-auth==2.48.0
     # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
     #   google-genai
     #   kubernetes
-google-cloud-aiplatform==1.133.0
-    # via onyx
-google-cloud-bigquery==3.38.0
-    # via google-cloud-aiplatform
-google-cloud-core==2.5.0
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-google-cloud-resource-manager==1.15.0
-    # via google-cloud-aiplatform
-google-cloud-storage==2.19.0
-    # via google-cloud-aiplatform
-google-crc32c==1.7.1
-    # via
-    #   google-cloud-storage
-    #   google-resumable-media
 google-genai==1.52.0
-    # via
-    #   google-cloud-aiplatform
-    #   onyx
-google-resumable-media==2.7.2
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-googleapis-common-protos==1.72.0
-    # via
-    #   google-api-core
-    #   grpc-google-iam-v1
-    #   grpcio-status
+    # via onyx
 greenlet==3.2.4 ; platform_machine == 'AMD64' or platform_machine == 'WIN32' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'ppc64le' or platform_machine == 'win32' or platform_machine == 'x86_64'
     # via sqlalchemy
-grpc-google-iam-v1==0.14.3
-    # via google-cloud-resource-manager
-grpcio==1.76.0
-    # via
-    #   google-api-core
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-grpcio-status==1.76.0
-    # via google-api-core
 h11==0.16.0
     # via
     #   httpcore
@@ -329,8 +276,6 @@ openapi-generator-cli==7.17.0
 packaging==24.2
     # via
     #   black
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
     #   hatchling
     #   huggingface-hub
     #   ipykernel
@@ -373,20 +318,6 @@ propcache==0.4.1
     # via
     #   aiohttp
     #   yarl
-proto-plus==1.26.1
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
-protobuf==6.33.5
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-    #   proto-plus
 psutil==7.1.3
     # via ipykernel
 ptyprocess==0.7.0 ; sys_platform != 'emscripten' and sys_platform != 'win32'
@@ -408,7 +339,6 @@ pydantic==2.11.7
     #   agent-client-protocol
     #   cohere
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
     #   litellm
     #   mcp
@@ -449,7 +379,6 @@ python-dateutil==2.8.2
     # via
     #   aiobotocore
     #   botocore
-    #   google-cloud-bigquery
     #   jupyter-client
     #   kubernetes
     #   matplotlib
@@ -484,9 +413,6 @@ reorder-python-imports-black==3.14.0
 requests==2.32.5
     # via
     #   cohere
-    #   google-api-core
-    #   google-cloud-bigquery
-    #   google-cloud-storage
     #   google-genai
     #   huggingface-hub
     #   kubernetes
@@ -599,9 +525,7 @@ typing-extensions==4.15.0
     #   celery-types
     #   cohere
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
-    #   grpcio
     #   huggingface-hub
     #   ipython
     #   mcp
diff --git a/backend/requirements/ee.txt b/backend/requirements/ee.txt
index 17d0f85a3e3..17a6508bf4f 100644
--- a/backend/requirements/ee.txt
+++ b/backend/requirements/ee.txt
@@ -86,8 +86,6 @@ discord-py==2.4.0
     # via onyx
 distro==1.9.0
     # via openai
-docstring-parser==0.17.0
-    # via google-cloud-aiplatform
 durationpy==0.10
     # via kubernetes
 fastapi==0.133.1
@@ -104,63 +102,12 @@ frozenlist==1.8.0
     #   aiosignal
 fsspec==2025.10.0
     # via huggingface-hub
-google-api-core==2.28.1
-    # via
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
 google-auth==2.48.0
     # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
     #   google-genai
     #   kubernetes
-google-cloud-aiplatform==1.133.0
-    # via onyx
-google-cloud-bigquery==3.38.0
-    # via google-cloud-aiplatform
-google-cloud-core==2.5.0
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-google-cloud-resource-manager==1.15.0
-    # via google-cloud-aiplatform
-google-cloud-storage==2.19.0
-    # via google-cloud-aiplatform
-google-crc32c==1.7.1
-    # via
-    #   google-cloud-storage
-    #   google-resumable-media
 google-genai==1.52.0
-    # via
-    #   google-cloud-aiplatform
-    #   onyx
-google-resumable-media==2.7.2
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-googleapis-common-protos==1.72.0
-    # via
-    #   google-api-core
-    #   grpc-google-iam-v1
-    #   grpcio-status
-grpc-google-iam-v1==0.14.3
-    # via google-cloud-resource-manager
-grpcio==1.76.0
-    # via
-    #   google-api-core
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-grpcio-status==1.76.0
-    # via google-api-core
+    # via onyx
 h11==0.16.0
     # via
     #   httpcore
@@ -231,10 +178,7 @@ openai==2.14.0
     #   litellm
     #   onyx
 packaging==24.2
-    # via
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   huggingface-hub
+    # via huggingface-hub
 parameterized==0.9.0
     # via cohere
 posthog==3.7.4
@@ -249,20 +193,6 @@ propcache==0.4.1
     # via
     #   aiohttp
     #   yarl
-proto-plus==1.26.1
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
-protobuf==6.33.5
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-    #   proto-plus
 py==1.11.0
     # via retry
 pyasn1==0.6.2
@@ -278,7 +208,6 @@ pydantic==2.11.7
     #   agent-client-protocol
     #   cohere
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
     #   litellm
     #   mcp
@@ -295,7 +224,6 @@ python-dateutil==2.8.2
     # via
     #   aiobotocore
     #   botocore
-    #   google-cloud-bigquery
     #   kubernetes
     #   posthog
 python-dotenv==1.1.1
@@ -319,9 +247,6 @@ regex==2025.11.3
 requests==2.32.5
     # via
     #   cohere
-    #   google-api-core
-    #   google-cloud-bigquery
-    #   google-cloud-storage
     #   google-genai
     #   huggingface-hub
     #   kubernetes
@@ -381,9 +306,7 @@ typing-extensions==4.15.0
     #   anyio
     #   cohere
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
-    #   grpcio
     #   huggingface-hub
     #   mcp
     #   openai
diff --git a/backend/requirements/model_server.txt b/backend/requirements/model_server.txt
index a69285e624c..4f0bc2b9f9e 100644
--- a/backend/requirements/model_server.txt
+++ b/backend/requirements/model_server.txt
@@ -102,8 +102,6 @@ discord-py==2.4.0
     # via onyx
 distro==1.9.0
     # via openai
-docstring-parser==0.17.0
-    # via google-cloud-aiplatform
 durationpy==0.10
     # via kubernetes
 einops==0.8.1
@@ -129,63 +127,12 @@ fsspec==2025.10.0
     # via
     #   huggingface-hub
     #   torch
-google-api-core==2.28.1
-    # via
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
 google-auth==2.48.0
     # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
-    #   google-cloud-core
-    #   google-cloud-resource-manager
-    #   google-cloud-storage
     #   google-genai
     #   kubernetes
-google-cloud-aiplatform==1.133.0
-    # via onyx
-google-cloud-bigquery==3.38.0
-    # via google-cloud-aiplatform
-google-cloud-core==2.5.0
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-google-cloud-resource-manager==1.15.0
-    # via google-cloud-aiplatform
-google-cloud-storage==2.19.0
-    # via google-cloud-aiplatform
-google-crc32c==1.7.1
-    # via
-    #   google-cloud-storage
-    #   google-resumable-media
 google-genai==1.52.0
-    # via
-    #   google-cloud-aiplatform
-    #   onyx
-google-resumable-media==2.7.2
-    # via
-    #   google-cloud-bigquery
-    #   google-cloud-storage
-googleapis-common-protos==1.72.0
-    # via
-    #   google-api-core
-    #   grpc-google-iam-v1
-    #   grpcio-status
-grpc-google-iam-v1==0.14.3
-    # via google-cloud-resource-manager
-grpcio==1.76.0
-    # via
-    #   google-api-core
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-grpcio-status==1.76.0
-    # via google-api-core
+    # via onyx
 h11==0.16.0
     # via
     #   httpcore
@@ -315,8 +262,6 @@ openai==2.14.0
 packaging==24.2
     # via
     #   accelerate
-    #   google-cloud-aiplatform
-    #   google-cloud-bigquery
     #   huggingface-hub
     #   kombu
     #   transformers
@@ -336,20 +281,6 @@ propcache==0.4.1
     # via
     #   aiohttp
     #   yarl
-proto-plus==1.26.1
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
-protobuf==6.33.5
-    # via
-    #   google-api-core
-    #   google-cloud-aiplatform
-    #   google-cloud-resource-manager
-    #   googleapis-common-protos
-    #   grpc-google-iam-v1
-    #   grpcio-status
-    #   proto-plus
 psutil==7.1.3
     # via accelerate
 py==1.11.0
@@ -367,7 +298,6 @@ pydantic==2.11.7
     #   agent-client-protocol
     #   cohere
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
     #   litellm
     #   mcp
@@ -385,7 +315,6 @@ python-dateutil==2.8.2
     #   aiobotocore
     #   botocore
     #   celery
-    #   google-cloud-bigquery
     #   kubernetes
 python-dotenv==1.1.1
     # via
@@ -412,9 +341,6 @@ regex==2025.11.3
 requests==2.32.5
     # via
     #   cohere
-    #   google-api-core
-    #   google-cloud-bigquery
-    #   google-cloud-storage
     #   google-genai
     #   huggingface-hub
     #   kubernetes
@@ -507,9 +433,7 @@ typing-extensions==4.15.0
     #   anyio
     #   cohere
     #   fastapi
-    #   google-cloud-aiplatform
     #   google-genai
-    #   grpcio
     #   huggingface-hub
     #   mcp
     #   openai
diff --git a/pyproject.toml b/pyproject.toml
index 941136d9735..1bcc0c1ebb9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -11,7 +11,6 @@ dependencies = [
     "aioboto3==15.1.0",
     "cohere==5.6.1",
     "fastapi==0.133.1",
-    "google-cloud-aiplatform==1.133.0",
     "google-genai==1.52.0",
     "litellm==1.81.6",
     "openai==2.14.0",
diff --git a/uv.lock b/uv.lock
index 0b2cca147a2..343ff1c0505 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2107,12 +2107,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ed/d4/90197b416cb61cefd316964fd9e7bd8324bcbafabf40eef14a9f20b81974/google_api_core-2.28.1-py3-none-any.whl", hash = "sha256:4021b0f8ceb77a6fb4de6fde4502cecab45062e66ff4f2895169e0b35bc9466c", size = 173706, upload-time = "2025-10-28T21:34:50.151Z" },
 ]
 
-[package.optional-dependencies]
-grpc = [
-    { name = "grpcio" },
-    { name = "grpcio-status" },
-]
-
 [[package]]
 name = "google-api-python-client"
 version = "2.86.0"
@@ -2170,121 +2164,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4a/07/8d9a8186e6768b55dfffeb57c719bc03770cf8a970a074616ae6f9e26a57/google_auth_oauthlib-1.0.0-py2.py3-none-any.whl", hash = "sha256:95880ca704928c300f48194d1770cf5b1462835b6e49db61445a520f793fd5fb", size = 18926, upload-time = "2023-02-07T20:53:18.837Z" },
 ]
 
-[[package]]
-name = "google-cloud-aiplatform"
-version = "1.133.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "docstring-parser" },
-    { name = "google-api-core", extra = ["grpc"] },
-    { name = "google-auth" },
-    { name = "google-cloud-bigquery" },
-    { name = "google-cloud-resource-manager" },
-    { name = "google-cloud-storage" },
-    { name = "google-genai" },
-    { name = "packaging" },
-    { name = "proto-plus" },
-    { name = "protobuf" },
-    { name = "pydantic" },
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/d4/be/31ce7fd658ddebafbe5583977ddee536b2bacc491ad10b5a067388aec66f/google_cloud_aiplatform-1.133.0.tar.gz", hash = "sha256:3a6540711956dd178daaab3c2c05db476e46d94ac25912b8cf4f59b00b058ae0", size = 9921309, upload-time = "2026-01-08T22:11:25.079Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/01/5b/ef74ff65aebb74eaba51078e33ddd897247ba0d1197fd5a7953126205519/google_cloud_aiplatform-1.133.0-py2.py3-none-any.whl", hash = "sha256:dfc81228e987ca10d1c32c7204e2131b3c8d6b7c8e0b4e23bf7c56816bc4c566", size = 8184595, upload-time = "2026-01-08T22:11:22.067Z" },
-]
-
-[[package]]
-name = "google-cloud-bigquery"
-version = "3.38.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-api-core", extra = ["grpc"] },
-    { name = "google-auth" },
-    { name = "google-cloud-core" },
-    { name = "google-resumable-media" },
-    { name = "packaging" },
-    { name = "python-dateutil" },
-    { name = "requests" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/07/b2/a17e40afcf9487e3d17db5e36728ffe75c8d5671c46f419d7b6528a5728a/google_cloud_bigquery-3.38.0.tar.gz", hash = "sha256:8afcb7116f5eac849097a344eb8bfda78b7cfaae128e60e019193dd483873520", size = 503666, upload-time = "2025-09-17T20:33:33.47Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/3c/c8cada9ec282b29232ed9aed5a0b5cca6cf5367cb2ffa8ad0d2583d743f1/google_cloud_bigquery-3.38.0-py3-none-any.whl", hash = "sha256:e06e93ff7b245b239945ef59cb59616057598d369edac457ebf292bd61984da6", size = 259257, upload-time = "2025-09-17T20:33:31.404Z" },
-]
-
-[[package]]
-name = "google-cloud-core"
-version = "2.5.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-api-core" },
-    { name = "google-auth" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/a6/03/ef0bc99d0e0faf4fdbe67ac445e18cdaa74824fd93cd069e7bb6548cb52d/google_cloud_core-2.5.0.tar.gz", hash = "sha256:7c1b7ef5c92311717bd05301aa1a91ffbc565673d3b0b4163a52d8413a186963", size = 36027, upload-time = "2025-10-29T23:17:39.513Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/89/20/bfa472e327c8edee00f04beecc80baeddd2ab33ee0e86fd7654da49d45e9/google_cloud_core-2.5.0-py3-none-any.whl", hash = "sha256:67d977b41ae6c7211ee830c7912e41003ea8194bff15ae7d72fd6f51e57acabc", size = 29469, upload-time = "2025-10-29T23:17:38.548Z" },
-]
-
-[[package]]
-name = "google-cloud-resource-manager"
-version = "1.15.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-api-core", extra = ["grpc"] },
-    { name = "google-auth" },
-    { name = "grpc-google-iam-v1" },
-    { name = "grpcio" },
-    { name = "proto-plus" },
-    { name = "protobuf" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/fc/19/b95d0e8814ce42522e434cdd85c0cb6236d874d9adf6685fc8e6d1fda9d1/google_cloud_resource_manager-1.15.0.tar.gz", hash = "sha256:3d0b78c3daa713f956d24e525b35e9e9a76d597c438837171304d431084cedaf", size = 449227, upload-time = "2025-10-20T14:57:01.108Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/8c/93/5aef41a5f146ad4559dd7040ae5fa8e7ddcab4dfadbef6cb4b66d775e690/google_cloud_resource_manager-1.15.0-py3-none-any.whl", hash = "sha256:0ccde5db644b269ddfdf7b407a2c7b60bdbf459f8e666344a5285601d00c7f6d", size = 397151, upload-time = "2025-10-20T14:53:45.409Z" },
-]
-
-[[package]]
-name = "google-cloud-storage"
-version = "2.19.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-api-core" },
-    { name = "google-auth" },
-    { name = "google-cloud-core" },
-    { name = "google-crc32c" },
-    { name = "google-resumable-media" },
-    { name = "requests" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/36/76/4d965702e96bb67976e755bed9828fa50306dca003dbee08b67f41dd265e/google_cloud_storage-2.19.0.tar.gz", hash = "sha256:cd05e9e7191ba6cb68934d8eb76054d9be4562aa89dbc4236feee4d7d51342b2", size = 5535488, upload-time = "2024-12-05T01:35:06.49Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/d5/94/6db383d8ee1adf45dc6c73477152b82731fa4c4a46d9c1932cc8757e0fd4/google_cloud_storage-2.19.0-py2.py3-none-any.whl", hash = "sha256:aeb971b5c29cf8ab98445082cbfe7b161a1f48ed275822f59ed3f1524ea54fba", size = 131787, upload-time = "2024-12-05T01:35:04.736Z" },
-]
-
-[[package]]
-name = "google-crc32c"
-version = "1.7.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/19/ae/87802e6d9f9d69adfaedfcfd599266bf386a54d0be058b532d04c794f76d/google_crc32c-1.7.1.tar.gz", hash = "sha256:2bff2305f98846f3e825dbeec9ee406f89da7962accdb29356e4eadc251bd472", size = 14495, upload-time = "2025-03-26T14:29:13.32Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/f7/94/220139ea87822b6fdfdab4fb9ba81b3fff7ea2c82e2af34adc726085bffc/google_crc32c-1.7.1-cp311-cp311-macosx_12_0_arm64.whl", hash = "sha256:6fbab4b935989e2c3610371963ba1b86afb09537fd0c633049be82afe153ac06", size = 30468, upload-time = "2025-03-26T14:32:52.215Z" },
-    { url = "https://files.pythonhosted.org/packages/94/97/789b23bdeeb9d15dc2904660463ad539d0318286d7633fe2760c10ed0c1c/google_crc32c-1.7.1-cp311-cp311-macosx_12_0_x86_64.whl", hash = "sha256:ed66cbe1ed9cbaaad9392b5259b3eba4a9e565420d734e6238813c428c3336c9", size = 30313, upload-time = "2025-03-26T14:57:38.758Z" },
-    { url = "https://files.pythonhosted.org/packages/81/b8/976a2b843610c211e7ccb3e248996a61e87dbb2c09b1499847e295080aec/google_crc32c-1.7.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ee6547b657621b6cbed3562ea7826c3e11cab01cd33b74e1f677690652883e77", size = 33048, upload-time = "2025-03-26T14:41:30.679Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/16/a3842c2cf591093b111d4a5e2bfb478ac6692d02f1b386d2a33283a19dc9/google_crc32c-1.7.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d68e17bad8f7dd9a49181a1f5a8f4b251c6dbc8cc96fb79f1d321dfd57d66f53", size = 32669, upload-time = "2025-03-26T14:41:31.432Z" },
-    { url = "https://files.pythonhosted.org/packages/04/17/ed9aba495916fcf5fe4ecb2267ceb851fc5f273c4e4625ae453350cfd564/google_crc32c-1.7.1-cp311-cp311-win_amd64.whl", hash = "sha256:6335de12921f06e1f774d0dd1fbea6bf610abe0887a1638f64d694013138be5d", size = 33476, upload-time = "2025-03-26T14:29:10.211Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/b7/787e2453cf8639c94b3d06c9d61f512234a82e1d12d13d18584bd3049904/google_crc32c-1.7.1-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:2d73a68a653c57281401871dd4aeebbb6af3191dcac751a76ce430df4d403194", size = 30470, upload-time = "2025-03-26T14:34:31.655Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/b4/6042c2b0cbac3ec3a69bb4c49b28d2f517b7a0f4a0232603c42c58e22b44/google_crc32c-1.7.1-cp312-cp312-macosx_12_0_x86_64.whl", hash = "sha256:22beacf83baaf59f9d3ab2bbb4db0fb018da8e5aebdce07ef9f09fce8220285e", size = 30315, upload-time = "2025-03-26T15:01:54.634Z" },
-    { url = "https://files.pythonhosted.org/packages/29/ad/01e7a61a5d059bc57b702d9ff6a18b2585ad97f720bd0a0dbe215df1ab0e/google_crc32c-1.7.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:19eafa0e4af11b0a4eb3974483d55d2d77ad1911e6cf6f832e1574f6781fd337", size = 33180, upload-time = "2025-03-26T14:41:32.168Z" },
-    { url = "https://files.pythonhosted.org/packages/3b/a5/7279055cf004561894ed3a7bfdf5bf90a53f28fadd01af7cd166e88ddf16/google_crc32c-1.7.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b6d86616faaea68101195c6bdc40c494e4d76f41e07a37ffdef270879c15fb65", size = 32794, upload-time = "2025-03-26T14:41:33.264Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/d6/77060dbd140c624e42ae3ece3df53b9d811000729a5c821b9fd671ceaac6/google_crc32c-1.7.1-cp312-cp312-win_amd64.whl", hash = "sha256:b7491bdc0c7564fcf48c0179d2048ab2f7c7ba36b84ccd3a3e1c3f7a72d3bba6", size = 33477, upload-time = "2025-03-26T14:29:10.94Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/72/b8d785e9184ba6297a8620c8a37cf6e39b81a8ca01bb0796d7cbb28b3386/google_crc32c-1.7.1-cp313-cp313-macosx_12_0_arm64.whl", hash = "sha256:df8b38bdaf1629d62d51be8bdd04888f37c451564c2042d36e5812da9eff3c35", size = 30467, upload-time = "2025-03-26T14:36:06.909Z" },
-    { url = "https://files.pythonhosted.org/packages/34/25/5f18076968212067c4e8ea95bf3b69669f9fc698476e5f5eb97d5b37999f/google_crc32c-1.7.1-cp313-cp313-macosx_12_0_x86_64.whl", hash = "sha256:e42e20a83a29aa2709a0cf271c7f8aefaa23b7ab52e53b322585297bb94d4638", size = 30309, upload-time = "2025-03-26T15:06:15.318Z" },
-    { url = "https://files.pythonhosted.org/packages/92/83/9228fe65bf70e93e419f38bdf6c5ca5083fc6d32886ee79b450ceefd1dbd/google_crc32c-1.7.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:905a385140bf492ac300026717af339790921f411c0dfd9aa5a9e69a08ed32eb", size = 33133, upload-time = "2025-03-26T14:41:34.388Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/ca/1ea2fd13ff9f8955b85e7956872fdb7050c4ace8a2306a6d177edb9cf7fe/google_crc32c-1.7.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6b211ddaf20f7ebeec5c333448582c224a7c90a9d98826fbab82c0ddc11348e6", size = 32773, upload-time = "2025-03-26T14:41:35.19Z" },
-    { url = "https://files.pythonhosted.org/packages/89/32/a22a281806e3ef21b72db16f948cad22ec68e4bdd384139291e00ff82fe2/google_crc32c-1.7.1-cp313-cp313-win_amd64.whl", hash = "sha256:0f99eaa09a9a7e642a61e06742856eec8b19fc0037832e03f941fe7cf0c8e4db", size = 33475, upload-time = "2025-03-26T14:29:11.771Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/c5/002975aff514e57fc084ba155697a049b3f9b52225ec3bc0f542871dd524/google_crc32c-1.7.1-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:32d1da0d74ec5634a05f53ef7df18fc646666a25efaaca9fc7dcfd4caf1d98c3", size = 33243, upload-time = "2025-03-26T14:41:35.975Z" },
-    { url = "https://files.pythonhosted.org/packages/61/cb/c585282a03a0cea70fcaa1bf55d5d702d0f2351094d663ec3be1c6c67c52/google_crc32c-1.7.1-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e10554d4abc5238823112c2ad7e4560f96c7bf3820b202660373d769d9e6e4c9", size = 32870, upload-time = "2025-03-26T14:41:37.08Z" },
-    { url = "https://files.pythonhosted.org/packages/16/1b/1693372bf423ada422f80fd88260dbfd140754adb15cbc4d7e9a68b1cb8e/google_crc32c-1.7.1-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:85fef7fae11494e747c9fd1359a527e5970fc9603c90764843caabd3a16a0a48", size = 28241, upload-time = "2025-03-26T14:41:45.898Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/3c/2a19a60a473de48717b4efb19398c3f914795b64a96cf3fbe82588044f78/google_crc32c-1.7.1-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6efb97eb4369d52593ad6f75e7e10d053cf00c48983f7a973105bc70b0ac4d82", size = 28048, upload-time = "2025-03-26T14:41:46.696Z" },
-]
-
 [[package]]
 name = "google-genai"
 version = "1.52.0"
@@ -2304,18 +2183,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/66/03f663e7bca7abe9ccfebe6cb3fe7da9a118fd723a5abb278d6117e7990e/google_genai-1.52.0-py3-none-any.whl", hash = "sha256:c8352b9f065ae14b9322b949c7debab8562982f03bf71d44130cd2b798c20743", size = 261219, upload-time = "2025-11-21T02:18:54.515Z" },
 ]
 
-[[package]]
-name = "google-resumable-media"
-version = "2.7.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-crc32c" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/58/5a/0efdc02665dca14e0837b62c8a1a93132c264bd02054a15abb2218afe0ae/google_resumable_media-2.7.2.tar.gz", hash = "sha256:5280aed4629f2b60b847b0d42f9857fd4935c11af266744df33d8074cae92fe0", size = 2163099, upload-time = "2024-08-07T22:20:38.555Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/82/35/b8d3baf8c46695858cb9d8835a53baa1eeb9906ddaf2f728a5f5b640fd1e/google_resumable_media-2.7.2-py2.py3-none-any.whl", hash = "sha256:3ce7551e9fe6d99e9a126101d2536612bb73486721951e9562fee0f90c6ababa", size = 81251, upload-time = "2024-08-07T22:20:36.409Z" },
-]
-
 [[package]]
 name = "googleapis-common-protos"
 version = "1.72.0"
@@ -2328,11 +2195,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c4/ab/09169d5a4612a5f92490806649ac8d41e3ec9129c636754575b3553f4ea4/googleapis_common_protos-1.72.0-py3-none-any.whl", hash = "sha256:4299c5a82d5ae1a9702ada957347726b167f9f8d1fc352477702a1e851ff4038", size = 297515, upload-time = "2025-11-06T18:29:13.14Z" },
 ]
 
-[package.optional-dependencies]
-grpc = [
-    { name = "grpcio" },
-]
-
 [[package]]
 name = "greenlet"
 version = "3.2.4"
@@ -2383,85 +2245,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e3/a5/6ddab2b4c112be95601c13428db1d8b6608a8b6039816f2ba09c346c08fc/greenlet-3.2.4-cp314-cp314-win_amd64.whl", hash = "sha256:e37ab26028f12dbb0ff65f29a8d3d44a765c61e729647bf2ddfbbed621726f01", size = 303425, upload-time = "2025-08-07T13:32:27.59Z" },
 ]
 
-[[package]]
-name = "grpc-google-iam-v1"
-version = "0.14.3"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "googleapis-common-protos", extra = ["grpc"] },
-    { name = "grpcio" },
-    { name = "protobuf" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/76/1e/1011451679a983f2f5c6771a1682542ecb027776762ad031fd0d7129164b/grpc_google_iam_v1-0.14.3.tar.gz", hash = "sha256:879ac4ef33136c5491a6300e27575a9ec760f6cdf9a2518798c1b8977a5dc389", size = 23745, upload-time = "2025-10-15T21:14:53.318Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/bd/330a1bbdb1afe0b96311249e699b6dc9cfc17916394fd4503ac5aca2514b/grpc_google_iam_v1-0.14.3-py3-none-any.whl", hash = "sha256:7a7f697e017a067206a3dfef44e4c634a34d3dee135fe7d7a4613fe3e59217e6", size = 32690, upload-time = "2025-10-15T21:14:51.72Z" },
-]
-
-[[package]]
-name = "grpcio"
-version = "1.76.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/b6/e0/318c1ce3ae5a17894d5791e87aea147587c9e702f24122cc7a5c8bbaeeb1/grpcio-1.76.0.tar.gz", hash = "sha256:7be78388d6da1a25c0d5ec506523db58b18be22d9c37d8d3a32c08be4987bd73", size = 12785182, upload-time = "2025-10-21T16:23:12.106Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/a0/00/8163a1beeb6971f66b4bbe6ac9457b97948beba8dd2fc8e1281dce7f79ec/grpcio-1.76.0-cp311-cp311-linux_armv7l.whl", hash = "sha256:2e1743fbd7f5fa713a1b0a8ac8ebabf0ec980b5d8809ec358d488e273b9cf02a", size = 5843567, upload-time = "2025-10-21T16:20:52.829Z" },
-    { url = "https://files.pythonhosted.org/packages/10/c1/934202f5cf335e6d852530ce14ddb0fef21be612ba9ecbbcbd4d748ca32d/grpcio-1.76.0-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:a8c2cf1209497cf659a667d7dea88985e834c24b7c3b605e6254cbb5076d985c", size = 11848017, upload-time = "2025-10-21T16:20:56.705Z" },
-    { url = "https://files.pythonhosted.org/packages/11/0b/8dec16b1863d74af6eb3543928600ec2195af49ca58b16334972f6775663/grpcio-1.76.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:08caea849a9d3c71a542827d6df9d5a69067b0a1efbea8a855633ff5d9571465", size = 6412027, upload-time = "2025-10-21T16:20:59.3Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/64/7b9e6e7ab910bea9d46f2c090380bab274a0b91fb0a2fe9b0cd399fffa12/grpcio-1.76.0-cp311-cp311-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:f0e34c2079d47ae9f6188211db9e777c619a21d4faba6977774e8fa43b085e48", size = 7075913, upload-time = "2025-10-21T16:21:01.645Z" },
-    { url = "https://files.pythonhosted.org/packages/68/86/093c46e9546073cefa789bd76d44c5cb2abc824ca62af0c18be590ff13ba/grpcio-1.76.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8843114c0cfce61b40ad48df65abcfc00d4dba82eae8718fab5352390848c5da", size = 6615417, upload-time = "2025-10-21T16:21:03.844Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/b6/5709a3a68500a9c03da6fb71740dcdd5ef245e39266461a03f31a57036d8/grpcio-1.76.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:8eddfb4d203a237da6f3cc8a540dad0517d274b5a1e9e636fd8d2c79b5c1d397", size = 7199683, upload-time = "2025-10-21T16:21:06.195Z" },
-    { url = "https://files.pythonhosted.org/packages/91/d3/4b1f2bf16ed52ce0b508161df3a2d186e4935379a159a834cb4a7d687429/grpcio-1.76.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:32483fe2aab2c3794101c2a159070584e5db11d0aa091b2c0ea9c4fc43d0d749", size = 8163109, upload-time = "2025-10-21T16:21:08.498Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/61/d9043f95f5f4cf085ac5dd6137b469d41befb04bd80280952ffa2a4c3f12/grpcio-1.76.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:dcfe41187da8992c5f40aa8c5ec086fa3672834d2be57a32384c08d5a05b4c00", size = 7626676, upload-time = "2025-10-21T16:21:10.693Z" },
-    { url = "https://files.pythonhosted.org/packages/36/95/fd9a5152ca02d8881e4dd419cdd790e11805979f499a2e5b96488b85cf27/grpcio-1.76.0-cp311-cp311-win32.whl", hash = "sha256:2107b0c024d1b35f4083f11245c0e23846ae64d02f40b2b226684840260ed054", size = 3997688, upload-time = "2025-10-21T16:21:12.746Z" },
-    { url = "https://files.pythonhosted.org/packages/60/9c/5c359c8d4c9176cfa3c61ecd4efe5affe1f38d9bae81e81ac7186b4c9cc8/grpcio-1.76.0-cp311-cp311-win_amd64.whl", hash = "sha256:522175aba7af9113c48ec10cc471b9b9bd4f6ceb36aeb4544a8e2c80ed9d252d", size = 4709315, upload-time = "2025-10-21T16:21:15.26Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/05/8e29121994b8d959ffa0afd28996d452f291b48cfc0875619de0bde2c50c/grpcio-1.76.0-cp312-cp312-linux_armv7l.whl", hash = "sha256:81fd9652b37b36f16138611c7e884eb82e0cec137c40d3ef7c3f9b3ed00f6ed8", size = 5799718, upload-time = "2025-10-21T16:21:17.939Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/75/11d0e66b3cdf998c996489581bdad8900db79ebd83513e45c19548f1cba4/grpcio-1.76.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:04bbe1bfe3a68bbfd4e52402ab7d4eb59d72d02647ae2042204326cf4bbad280", size = 11825627, upload-time = "2025-10-21T16:21:20.466Z" },
-    { url = "https://files.pythonhosted.org/packages/28/50/2f0aa0498bc188048f5d9504dcc5c2c24f2eb1a9337cd0fa09a61a2e75f0/grpcio-1.76.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d388087771c837cdb6515539f43b9d4bf0b0f23593a24054ac16f7a960be16f4", size = 6359167, upload-time = "2025-10-21T16:21:23.122Z" },
-    { url = "https://files.pythonhosted.org/packages/66/e5/bbf0bb97d29ede1d59d6588af40018cfc345b17ce979b7b45424628dc8bb/grpcio-1.76.0-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:9f8f757bebaaea112c00dba718fc0d3260052ce714e25804a03f93f5d1c6cc11", size = 7044267, upload-time = "2025-10-21T16:21:25.995Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/86/f6ec2164f743d9609691115ae8ece098c76b894ebe4f7c94a655c6b03e98/grpcio-1.76.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:980a846182ce88c4f2f7e2c22c56aefd515daeb36149d1c897f83cf57999e0b6", size = 6573963, upload-time = "2025-10-21T16:21:28.631Z" },
-    { url = "https://files.pythonhosted.org/packages/60/bc/8d9d0d8505feccfdf38a766d262c71e73639c165b311c9457208b56d92ae/grpcio-1.76.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f92f88e6c033db65a5ae3d97905c8fea9c725b63e28d5a75cb73b49bda5024d8", size = 7164484, upload-time = "2025-10-21T16:21:30.837Z" },
-    { url = "https://files.pythonhosted.org/packages/67/e6/5d6c2fc10b95edf6df9b8f19cf10a34263b7fd48493936fffd5085521292/grpcio-1.76.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:4baf3cbe2f0be3289eb68ac8ae771156971848bb8aaff60bad42005539431980", size = 8127777, upload-time = "2025-10-21T16:21:33.577Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/c8/dce8ff21c86abe025efe304d9e31fdb0deaaa3b502b6a78141080f206da0/grpcio-1.76.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:615ba64c208aaceb5ec83bfdce7728b80bfeb8be97562944836a7a0a9647d882", size = 7594014, upload-time = "2025-10-21T16:21:41.882Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/42/ad28191ebf983a5d0ecef90bab66baa5a6b18f2bfdef9d0a63b1973d9f75/grpcio-1.76.0-cp312-cp312-win32.whl", hash = "sha256:45d59a649a82df5718fd9527ce775fd66d1af35e6d31abdcdc906a49c6822958", size = 3984750, upload-time = "2025-10-21T16:21:44.006Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/00/7bd478cbb851c04a48baccaa49b75abaa8e4122f7d86da797500cccdd771/grpcio-1.76.0-cp312-cp312-win_amd64.whl", hash = "sha256:c088e7a90b6017307f423efbb9d1ba97a22aa2170876223f9709e9d1de0b5347", size = 4704003, upload-time = "2025-10-21T16:21:46.244Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/ed/71467ab770effc9e8cef5f2e7388beb2be26ed642d567697bb103a790c72/grpcio-1.76.0-cp313-cp313-linux_armv7l.whl", hash = "sha256:26ef06c73eb53267c2b319f43e6634c7556ea37672029241a056629af27c10e2", size = 5807716, upload-time = "2025-10-21T16:21:48.475Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/85/c6ed56f9817fab03fa8a111ca91469941fb514e3e3ce6d793cb8f1e1347b/grpcio-1.76.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:45e0111e73f43f735d70786557dc38141185072d7ff8dc1829d6a77ac1471468", size = 11821522, upload-time = "2025-10-21T16:21:51.142Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/31/2b8a235ab40c39cbc141ef647f8a6eb7b0028f023015a4842933bc0d6831/grpcio-1.76.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:83d57312a58dcfe2a3a0f9d1389b299438909a02db60e2f2ea2ae2d8034909d3", size = 6362558, upload-time = "2025-10-21T16:21:54.213Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/64/9784eab483358e08847498ee56faf8ff6ea8e0a4592568d9f68edc97e9e9/grpcio-1.76.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:3e2a27c89eb9ac3d81ec8835e12414d73536c6e620355d65102503064a4ed6eb", size = 7049990, upload-time = "2025-10-21T16:21:56.476Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/94/8c12319a6369434e7a184b987e8e9f3b49a114c489b8315f029e24de4837/grpcio-1.76.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:61f69297cba3950a524f61c7c8ee12e55c486cb5f7db47ff9dcee33da6f0d3ae", size = 6575387, upload-time = "2025-10-21T16:21:59.051Z" },
-    { url = "https://files.pythonhosted.org/packages/15/0f/f12c32b03f731f4a6242f771f63039df182c8b8e2cf8075b245b409259d4/grpcio-1.76.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:6a15c17af8839b6801d554263c546c69c4d7718ad4321e3166175b37eaacca77", size = 7166668, upload-time = "2025-10-21T16:22:02.049Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/2d/3ec9ce0c2b1d92dd59d1c3264aaec9f0f7c817d6e8ac683b97198a36ed5a/grpcio-1.76.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:25a18e9810fbc7e7f03ec2516addc116a957f8cbb8cbc95ccc80faa072743d03", size = 8124928, upload-time = "2025-10-21T16:22:04.984Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/74/fd3317be5672f4856bcdd1a9e7b5e17554692d3db9a3b273879dc02d657d/grpcio-1.76.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:931091142fd8cc14edccc0845a79248bc155425eee9a98b2db2ea4f00a235a42", size = 7589983, upload-time = "2025-10-21T16:22:07.881Z" },
-    { url = "https://files.pythonhosted.org/packages/45/bb/ca038cf420f405971f19821c8c15bcbc875505f6ffadafe9ffd77871dc4c/grpcio-1.76.0-cp313-cp313-win32.whl", hash = "sha256:5e8571632780e08526f118f74170ad8d50fb0a48c23a746bef2a6ebade3abd6f", size = 3984727, upload-time = "2025-10-21T16:22:10.032Z" },
-    { url = "https://files.pythonhosted.org/packages/41/80/84087dc56437ced7cdd4b13d7875e7439a52a261e3ab4e06488ba6173b0a/grpcio-1.76.0-cp313-cp313-win_amd64.whl", hash = "sha256:f9f7bd5faab55f47231ad8dba7787866b69f5e93bc306e3915606779bbfb4ba8", size = 4702799, upload-time = "2025-10-21T16:22:12.709Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/46/39adac80de49d678e6e073b70204091e76631e03e94928b9ea4ecf0f6e0e/grpcio-1.76.0-cp314-cp314-linux_armv7l.whl", hash = "sha256:ff8a59ea85a1f2191a0ffcc61298c571bc566332f82e5f5be1b83c9d8e668a62", size = 5808417, upload-time = "2025-10-21T16:22:15.02Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/f5/a4531f7fb8b4e2a60b94e39d5d924469b7a6988176b3422487be61fe2998/grpcio-1.76.0-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:06c3d6b076e7b593905d04fdba6a0525711b3466f43b3400266f04ff735de0cd", size = 11828219, upload-time = "2025-10-21T16:22:17.954Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/1c/de55d868ed7a8bd6acc6b1d6ddc4aa36d07a9f31d33c912c804adb1b971b/grpcio-1.76.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:fd5ef5932f6475c436c4a55e4336ebbe47bd3272be04964a03d316bbf4afbcbc", size = 6367826, upload-time = "2025-10-21T16:22:20.721Z" },
-    { url = "https://files.pythonhosted.org/packages/59/64/99e44c02b5adb0ad13ab3adc89cb33cb54bfa90c74770f2607eea629b86f/grpcio-1.76.0-cp314-cp314-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:b331680e46239e090f5b3cead313cc772f6caa7d0fc8de349337563125361a4a", size = 7049550, upload-time = "2025-10-21T16:22:23.637Z" },
-    { url = "https://files.pythonhosted.org/packages/43/28/40a5be3f9a86949b83e7d6a2ad6011d993cbe9b6bd27bea881f61c7788b6/grpcio-1.76.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:2229ae655ec4e8999599469559e97630185fdd53ae1e8997d147b7c9b2b72cba", size = 6575564, upload-time = "2025-10-21T16:22:26.016Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/a9/1be18e6055b64467440208a8559afac243c66a8b904213af6f392dc2212f/grpcio-1.76.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:490fa6d203992c47c7b9e4a9d39003a0c2bcc1c9aa3c058730884bbbb0ee9f09", size = 7176236, upload-time = "2025-10-21T16:22:28.362Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/55/dba05d3fcc151ce6e81327541d2cc8394f442f6b350fead67401661bf041/grpcio-1.76.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:479496325ce554792dba6548fae3df31a72cef7bad71ca2e12b0e58f9b336bfc", size = 8125795, upload-time = "2025-10-21T16:22:31.075Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/45/122df922d05655f63930cf42c9e3f72ba20aadb26c100ee105cad4ce4257/grpcio-1.76.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:1c9b93f79f48b03ada57ea24725d83a30284a012ec27eab2cf7e50a550cbbbcc", size = 7592214, upload-time = "2025-10-21T16:22:33.831Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/6e/0b899b7f6b66e5af39e377055fb4a6675c9ee28431df5708139df2e93233/grpcio-1.76.0-cp314-cp314-win32.whl", hash = "sha256:747fa73efa9b8b1488a95d0ba1039c8e2dca0f741612d80415b1e1c560febf4e", size = 4062961, upload-time = "2025-10-21T16:22:36.468Z" },
-    { url = "https://files.pythonhosted.org/packages/19/41/0b430b01a2eb38ee887f88c1f07644a1df8e289353b78e82b37ef988fb64/grpcio-1.76.0-cp314-cp314-win_amd64.whl", hash = "sha256:922fa70ba549fce362d2e2871ab542082d66e2aaf0c19480ea453905b01f384e", size = 4834462, upload-time = "2025-10-21T16:22:39.772Z" },
-]
-
-[[package]]
-name = "grpcio-status"
-version = "1.76.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "googleapis-common-protos" },
-    { name = "grpcio" },
-    { name = "protobuf" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/3f/46/e9f19d5be65e8423f886813a2a9d0056ba94757b0c5007aa59aed1a961fa/grpcio_status-1.76.0.tar.gz", hash = "sha256:25fcbfec74c15d1a1cb5da3fab8ee9672852dc16a5a9eeb5baf7d7a9952943cd", size = 13679, upload-time = "2025-10-21T16:28:52.545Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/8c/cc/27ba60ad5a5f2067963e6a858743500df408eb5855e98be778eaef8c9b02/grpcio_status-1.76.0-py3-none-any.whl", hash = "sha256:380568794055a8efbbd8871162df92012e0228a5f6dffaf57f2a00c534103b18", size = 14425, upload-time = "2025-10-21T16:28:40.853Z" },
-]
-
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -4424,7 +4207,6 @@ dependencies = [
     { name = "cohere" },
     { name = "discord-py" },
     { name = "fastapi" },
-    { name = "google-cloud-aiplatform" },
     { name = "google-genai" },
     { name = "kubernetes" },
     { name = "litellm" },
@@ -4629,7 +4411,6 @@ requires-dist = [
     { name = "google-api-python-client", marker = "extra == 'backend'", specifier = "==2.86.0" },
     { name = "google-auth-httplib2", marker = "extra == 'backend'", specifier = "==0.1.0" },
     { name = "google-auth-oauthlib", marker = "extra == 'backend'", specifier = "==1.0.0" },
-    { name = "google-cloud-aiplatform", specifier = "==1.133.0" },
     { name = "google-genai", specifier = "==1.52.0" },
     { name = "hatchling", marker = "extra == 'dev'", specifier = "==1.28.0" },
     { name = "httpcore", marker = "extra == 'backend'", specifier = "==1.0.9" },

From 376adff94a04a1bb5e517a26f20dfca33537a7c1 Mon Sep 17 00:00:00 2001
From: Bo-Onyx <bo@onyx.app>
Date: Thu, 5 Mar 2026 17:33:08 -0800
Subject: [PATCH 136/267] chore(dr-tune): Move postgres sanitization and use it
 for DR output save (#9113)

---
 .../background/indexing/run_docfetching.py    |  4 +-
 backend/onyx/chat/llm_step.py                 | 21 ++---
 backend/onyx/chat/save_chat.py                | 22 ++++--
 backend/onyx/db/chat.py                       | 36 +++------
 backend/onyx/db/tools.py                      | 12 ++-
 backend/onyx/indexing/indexing_pipeline.py    |  2 +-
 .../postgres_sanitization.py                  | 79 ++++++++++++-------
 .../celery/test_docprocessing_priority.py     |  5 ++
 backend/tests/unit/onyx/chat/test_llm_step.py | 32 ++++----
 ...t_save_chat_files.py => test_save_chat.py} | 45 ++++++++++-
 backend/tests/unit/onyx/db/test_tools.py      | 27 +++++++
 .../test_postgres_sanitization.py             | 75 +++++++++++++++++-
 12 files changed, 255 insertions(+), 105 deletions(-)
 rename backend/onyx/{indexing => utils}/postgres_sanitization.py (58%)
 rename backend/tests/unit/onyx/chat/{test_save_chat_files.py => test_save_chat.py} (82%)
 create mode 100644 backend/tests/unit/onyx/db/test_tools.py
 rename backend/tests/unit/onyx/{indexing => utils}/test_postgres_sanitization.py (71%)

diff --git a/backend/onyx/background/indexing/run_docfetching.py b/backend/onyx/background/indexing/run_docfetching.py
index 52dc393cbeb..79adf545e04 100644
--- a/backend/onyx/background/indexing/run_docfetching.py
+++ b/backend/onyx/background/indexing/run_docfetching.py
@@ -58,8 +58,6 @@
 from onyx.file_store.document_batch_storage import get_document_batch_storage
 from onyx.indexing.indexing_heartbeat import IndexingHeartbeatInterface
 from onyx.indexing.indexing_pipeline import index_doc_batch_prepare
-from onyx.indexing.postgres_sanitization import sanitize_document_for_postgres
-from onyx.indexing.postgres_sanitization import sanitize_hierarchy_nodes_for_postgres
 from onyx.redis.redis_hierarchy import cache_hierarchy_nodes_batch
 from onyx.redis.redis_hierarchy import ensure_source_node_exists
 from onyx.redis.redis_hierarchy import get_node_id_from_raw_id
@@ -71,6 +69,8 @@
 )
 from onyx.utils.logger import setup_logger
 from onyx.utils.middleware import make_randomized_onyx_request_id
+from onyx.utils.postgres_sanitization import sanitize_document_for_postgres
+from onyx.utils.postgres_sanitization import sanitize_hierarchy_nodes_for_postgres
 from onyx.utils.variable_functionality import global_version
 from shared_configs.configs import MULTI_TENANT
 from shared_configs.contextvars import INDEX_ATTEMPT_INFO_CONTEXTVAR
diff --git a/backend/onyx/chat/llm_step.py b/backend/onyx/chat/llm_step.py
index 4c15f0654e7..6b48fabc8f3 100644
--- a/backend/onyx/chat/llm_step.py
+++ b/backend/onyx/chat/llm_step.py
@@ -55,6 +55,7 @@
 from onyx.tracing.framework.create import generation_span
 from onyx.utils.b64 import get_image_type_from_bytes
 from onyx.utils.logger import setup_logger
+from onyx.utils.postgres_sanitization import sanitize_string
 from onyx.utils.text_processing import find_all_json_objects
 
 logger = setup_logger()
@@ -166,15 +167,6 @@ def _find_function_calls_open_marker(text_lower: str) -> int:
         search_from = idx + 1
 
 
-def _sanitize_llm_output(value: str) -> str:
-    """Remove characters that PostgreSQL's text/JSONB types cannot store.
-
-    - NULL bytes (\x00): Not allowed in PostgreSQL text types
-    - UTF-16 surrogates (\ud800-\udfff): Invalid in UTF-8 encoding
-    """
-    return "".join(c for c in value if c != "\x00" and not ("\ud800" <= c <= "\udfff"))
-
-
 def _try_parse_json_string(value: Any) -> Any:
     """Attempt to parse a JSON string value into its Python equivalent.
 
@@ -222,9 +214,7 @@ def _parse_tool_args_to_dict(raw_args: Any) -> dict[str, Any]:
     if isinstance(raw_args, dict):
         # Parse any string values that look like JSON arrays/objects
         return {
-            k: _try_parse_json_string(
-                _sanitize_llm_output(v) if isinstance(v, str) else v
-            )
+            k: _try_parse_json_string(sanitize_string(v) if isinstance(v, str) else v)
             for k, v in raw_args.items()
         }
 
@@ -232,7 +222,7 @@ def _parse_tool_args_to_dict(raw_args: Any) -> dict[str, Any]:
         return {}
 
     # Sanitize before parsing to remove NULL bytes and surrogates
-    raw_args = _sanitize_llm_output(raw_args)
+    raw_args = sanitize_string(raw_args)
 
     try:
         parsed1: Any = json.loads(raw_args)
@@ -545,12 +535,12 @@ def _extract_xml_attribute(attrs: str, attr_name: str) -> str | None:
     )
     if not attr_match:
         return None
-    return _sanitize_llm_output(unescape(attr_match.group(2).strip()))
+    return sanitize_string(unescape(attr_match.group(2).strip()))
 
 
 def _parse_xml_parameter_value(raw_value: str, string_attr: str | None) -> Any:
     """Parse a parameter value from XML-style tool call payloads."""
-    value = _sanitize_llm_output(unescape(raw_value).strip())
+    value = sanitize_string(unescape(raw_value).strip())
 
     if string_attr and string_attr.lower() == "true":
         return value
@@ -569,6 +559,7 @@ def _resolve_tool_arguments(obj: dict[str, Any]) -> dict[str, Any] | None:
     """
     arguments = obj.get("arguments", obj.get("parameters", {}))
     if isinstance(arguments, str):
+        arguments = sanitize_string(arguments)
         try:
             arguments = json.loads(arguments)
         except json.JSONDecodeError:
diff --git a/backend/onyx/chat/save_chat.py b/backend/onyx/chat/save_chat.py
index fcc7eae1275..a36ebed9492 100644
--- a/backend/onyx/chat/save_chat.py
+++ b/backend/onyx/chat/save_chat.py
@@ -19,6 +19,7 @@
 from onyx.server.query_and_chat.chat_utils import mime_type_to_chat_file_type
 from onyx.tools.models import ToolCallInfo
 from onyx.utils.logger import setup_logger
+from onyx.utils.postgres_sanitization import sanitize_string
 
 logger = setup_logger()
 
@@ -201,8 +202,13 @@ def save_chat_turn(
         pre_answer_processing_time: Duration of processing before answer starts (in seconds)
     """
     # 1. Update ChatMessage with message content, reasoning tokens, and token count
-    assistant_message.message = message_text
-    assistant_message.reasoning_tokens = reasoning_tokens
+    sanitized_message_text = (
+        sanitize_string(message_text) if message_text else message_text
+    )
+    assistant_message.message = sanitized_message_text
+    assistant_message.reasoning_tokens = (
+        sanitize_string(reasoning_tokens) if reasoning_tokens else reasoning_tokens
+    )
     assistant_message.is_clarification = is_clarification
 
     # Use pre-answer processing time (captured when MESSAGE_START was emitted)
@@ -212,8 +218,10 @@ def save_chat_turn(
     # Calculate token count using default tokenizer, when storing, this should not use the LLM
     # specific one so we use a system default tokenizer here.
     default_tokenizer = get_tokenizer(None, None)
-    if message_text:
-        assistant_message.token_count = len(default_tokenizer.encode(message_text))
+    if sanitized_message_text:
+        assistant_message.token_count = len(
+            default_tokenizer.encode(sanitized_message_text)
+        )
     else:
         assistant_message.token_count = 0
 
@@ -328,8 +336,10 @@ def save_chat_turn(
     # 8. Attach code interpreter generated files that the assistant actually
     # referenced in its response, so they are available via load_all_chat_files
     # on subsequent turns. Files not mentioned are intermediate artifacts.
-    if message_text:
-        referenced = _extract_referenced_file_descriptors(tool_calls, message_text)
+    if sanitized_message_text:
+        referenced = _extract_referenced_file_descriptors(
+            tool_calls, sanitized_message_text
+        )
         if referenced:
             existing_files = assistant_message.files or []
             assistant_message.files = existing_files + referenced
diff --git a/backend/onyx/db/chat.py b/backend/onyx/db/chat.py
index ac30bc7b45a..1588508f19b 100644
--- a/backend/onyx/db/chat.py
+++ b/backend/onyx/db/chat.py
@@ -38,6 +38,7 @@
 from onyx.llm.override_models import PromptOverride
 from onyx.server.query_and_chat.models import ChatMessageDetail
 from onyx.utils.logger import setup_logger
+from onyx.utils.postgres_sanitization import sanitize_string
 
 
 logger = setup_logger()
@@ -675,58 +676,43 @@ def set_as_latest_chat_message(
     db_session.commit()
 
 
-def _sanitize_for_postgres(value: str) -> str:
-    """Remove NUL (0x00) characters from strings as PostgreSQL doesn't allow them."""
-    sanitized = value.replace("\x00", "")
-    if value and not sanitized:
-        logger.warning("Sanitization removed all characters from string")
-    return sanitized
-
-
-def _sanitize_list_for_postgres(values: list[str]) -> list[str]:
-    """Remove NUL (0x00) characters from all strings in a list."""
-    return [_sanitize_for_postgres(v) for v in values]
-
-
 def create_db_search_doc(
     server_search_doc: ServerSearchDoc,
     db_session: Session,
     commit: bool = True,
 ) -> DBSearchDoc:
-    # Sanitize string fields to remove NUL characters (PostgreSQL doesn't allow them)
     db_search_doc = DBSearchDoc(
-        document_id=_sanitize_for_postgres(server_search_doc.document_id),
+        document_id=sanitize_string(server_search_doc.document_id),
         chunk_ind=server_search_doc.chunk_ind,
-        semantic_id=_sanitize_for_postgres(server_search_doc.semantic_identifier),
+        semantic_id=sanitize_string(server_search_doc.semantic_identifier),
         link=(
-            _sanitize_for_postgres(server_search_doc.link)
+            sanitize_string(server_search_doc.link)
             if server_search_doc.link is not None
             else None
         ),
-        blurb=_sanitize_for_postgres(server_search_doc.blurb),
+        blurb=sanitize_string(server_search_doc.blurb),
         source_type=server_search_doc.source_type,
         boost=server_search_doc.boost,
         hidden=server_search_doc.hidden,
         doc_metadata=server_search_doc.metadata,
         is_relevant=server_search_doc.is_relevant,
         relevance_explanation=(
-            _sanitize_for_postgres(server_search_doc.relevance_explanation)
+            sanitize_string(server_search_doc.relevance_explanation)
             if server_search_doc.relevance_explanation is not None
             else None
         ),
-        # For docs further down that aren't reranked, we can't use the retrieval score
         score=server_search_doc.score or 0.0,
-        match_highlights=_sanitize_list_for_postgres(
-            server_search_doc.match_highlights
-        ),
+        match_highlights=[
+            sanitize_string(h) for h in server_search_doc.match_highlights
+        ],
         updated_at=server_search_doc.updated_at,
         primary_owners=(
-            _sanitize_list_for_postgres(server_search_doc.primary_owners)
+            [sanitize_string(o) for o in server_search_doc.primary_owners]
             if server_search_doc.primary_owners is not None
             else None
         ),
         secondary_owners=(
-            _sanitize_list_for_postgres(server_search_doc.secondary_owners)
+            [sanitize_string(o) for o in server_search_doc.secondary_owners]
             if server_search_doc.secondary_owners is not None
             else None
         ),
diff --git a/backend/onyx/db/tools.py b/backend/onyx/db/tools.py
index af2606525e8..04640d0c8b6 100644
--- a/backend/onyx/db/tools.py
+++ b/backend/onyx/db/tools.py
@@ -19,6 +19,8 @@
 from onyx.tools.built_in_tools import BUILT_IN_TOOL_TYPES
 from onyx.utils.headers import HeaderItemDict
 from onyx.utils.logger import setup_logger
+from onyx.utils.postgres_sanitization import sanitize_json_like
+from onyx.utils.postgres_sanitization import sanitize_string
 
 if TYPE_CHECKING:
     pass
@@ -256,11 +258,13 @@ def create_tool_call_no_commit(
         tab_index=tab_index,
         tool_id=tool_id,
         tool_call_id=tool_call_id,
-        reasoning_tokens=reasoning_tokens,
-        tool_call_arguments=tool_call_arguments,
-        tool_call_response=tool_call_response,
+        reasoning_tokens=(
+            sanitize_string(reasoning_tokens) if reasoning_tokens else reasoning_tokens
+        ),
+        tool_call_arguments=sanitize_json_like(tool_call_arguments),
+        tool_call_response=sanitize_json_like(tool_call_response),
         tool_call_tokens=tool_call_tokens,
-        generated_images=generated_images,
+        generated_images=sanitize_json_like(generated_images),
     )
 
     db_session.add(tool_call)
diff --git a/backend/onyx/indexing/indexing_pipeline.py b/backend/onyx/indexing/indexing_pipeline.py
index 251f70194ee..da5ac417fcc 100644
--- a/backend/onyx/indexing/indexing_pipeline.py
+++ b/backend/onyx/indexing/indexing_pipeline.py
@@ -49,7 +49,6 @@
 from onyx.indexing.models import DocAwareChunk
 from onyx.indexing.models import IndexingBatchAdapter
 from onyx.indexing.models import UpdatableChunkData
-from onyx.indexing.postgres_sanitization import sanitize_documents_for_postgres
 from onyx.indexing.vector_db_insertion import write_chunks_to_vector_db_with_backoff
 from onyx.llm.factory import get_default_llm_with_vision
 from onyx.llm.factory import get_llm_for_contextual_rag
@@ -65,6 +64,7 @@
 from onyx.prompts.contextual_retrieval import CONTEXTUAL_RAG_PROMPT2
 from onyx.prompts.contextual_retrieval import DOCUMENT_SUMMARY_PROMPT
 from onyx.utils.logger import setup_logger
+from onyx.utils.postgres_sanitization import sanitize_documents_for_postgres
 from onyx.utils.threadpool_concurrency import run_functions_tuples_in_parallel
 from onyx.utils.timing import log_function_time
 
diff --git a/backend/onyx/indexing/postgres_sanitization.py b/backend/onyx/utils/postgres_sanitization.py
similarity index 58%
rename from backend/onyx/indexing/postgres_sanitization.py
rename to backend/onyx/utils/postgres_sanitization.py
index 098e5aca05d..9ce6de11cad 100644
--- a/backend/onyx/indexing/postgres_sanitization.py
+++ b/backend/onyx/utils/postgres_sanitization.py
@@ -1,30 +1,49 @@
+import re
 from typing import Any
 
 from onyx.access.models import ExternalAccess
 from onyx.connectors.models import BasicExpertInfo
 from onyx.connectors.models import Document
 from onyx.connectors.models import HierarchyNode
+from onyx.utils.logger import setup_logger
 
+logger = setup_logger()
 
-def _sanitize_string(value: str) -> str:
-    return value.replace("\x00", "")
+_SURROGATE_RE = re.compile(r"[\ud800-\udfff]")
 
 
-def _sanitize_json_like(value: Any) -> Any:
+def sanitize_string(value: str) -> str:
+    """Strip characters that PostgreSQL text/JSONB columns cannot store.
+
+    Removes:
+    - NUL bytes (\\x00)
+    - UTF-16 surrogates (\\ud800-\\udfff), which are invalid in UTF-8
+    """
+    sanitized = value.replace("\x00", "")
+    sanitized = _SURROGATE_RE.sub("", sanitized)
+    if value and not sanitized:
+        logger.warning(
+            "sanitize_string: all characters were removed from a non-empty string"
+        )
+    return sanitized
+
+
+def sanitize_json_like(value: Any) -> Any:
+    """Recursively sanitize all strings in a JSON-like structure (dict/list/tuple)."""
     if isinstance(value, str):
-        return _sanitize_string(value)
+        return sanitize_string(value)
 
     if isinstance(value, list):
-        return [_sanitize_json_like(item) for item in value]
+        return [sanitize_json_like(item) for item in value]
 
     if isinstance(value, tuple):
-        return tuple(_sanitize_json_like(item) for item in value)
+        return tuple(sanitize_json_like(item) for item in value)
 
     if isinstance(value, dict):
         sanitized: dict[Any, Any] = {}
         for key, nested_value in value.items():
-            cleaned_key = _sanitize_string(key) if isinstance(key, str) else key
-            sanitized[cleaned_key] = _sanitize_json_like(nested_value)
+            cleaned_key = sanitize_string(key) if isinstance(key, str) else key
+            sanitized[cleaned_key] = sanitize_json_like(nested_value)
         return sanitized
 
     return value
@@ -34,27 +53,27 @@ def _sanitize_expert_info(expert: BasicExpertInfo) -> BasicExpertInfo:
     return expert.model_copy(
         update={
             "display_name": (
-                _sanitize_string(expert.display_name)
+                sanitize_string(expert.display_name)
                 if expert.display_name is not None
                 else None
             ),
             "first_name": (
-                _sanitize_string(expert.first_name)
+                sanitize_string(expert.first_name)
                 if expert.first_name is not None
                 else None
             ),
             "middle_initial": (
-                _sanitize_string(expert.middle_initial)
+                sanitize_string(expert.middle_initial)
                 if expert.middle_initial is not None
                 else None
             ),
             "last_name": (
-                _sanitize_string(expert.last_name)
+                sanitize_string(expert.last_name)
                 if expert.last_name is not None
                 else None
             ),
             "email": (
-                _sanitize_string(expert.email) if expert.email is not None else None
+                sanitize_string(expert.email) if expert.email is not None else None
             ),
         }
     )
@@ -63,10 +82,10 @@ def _sanitize_expert_info(expert: BasicExpertInfo) -> BasicExpertInfo:
 def _sanitize_external_access(external_access: ExternalAccess) -> ExternalAccess:
     return ExternalAccess(
         external_user_emails={
-            _sanitize_string(email) for email in external_access.external_user_emails
+            sanitize_string(email) for email in external_access.external_user_emails
         },
         external_user_group_ids={
-            _sanitize_string(group_id)
+            sanitize_string(group_id)
             for group_id in external_access.external_user_group_ids
         },
         is_public=external_access.is_public,
@@ -76,26 +95,26 @@ def _sanitize_external_access(external_access: ExternalAccess) -> ExternalAccess
 def sanitize_document_for_postgres(document: Document) -> Document:
     cleaned_doc = document.model_copy(deep=True)
 
-    cleaned_doc.id = _sanitize_string(cleaned_doc.id)
-    cleaned_doc.semantic_identifier = _sanitize_string(cleaned_doc.semantic_identifier)
+    cleaned_doc.id = sanitize_string(cleaned_doc.id)
+    cleaned_doc.semantic_identifier = sanitize_string(cleaned_doc.semantic_identifier)
     if cleaned_doc.title is not None:
-        cleaned_doc.title = _sanitize_string(cleaned_doc.title)
+        cleaned_doc.title = sanitize_string(cleaned_doc.title)
     if cleaned_doc.parent_hierarchy_raw_node_id is not None:
-        cleaned_doc.parent_hierarchy_raw_node_id = _sanitize_string(
+        cleaned_doc.parent_hierarchy_raw_node_id = sanitize_string(
             cleaned_doc.parent_hierarchy_raw_node_id
         )
 
     cleaned_doc.metadata = {
-        _sanitize_string(key): (
-            [_sanitize_string(item) for item in value]
+        sanitize_string(key): (
+            [sanitize_string(item) for item in value]
             if isinstance(value, list)
-            else _sanitize_string(value)
+            else sanitize_string(value)
         )
         for key, value in cleaned_doc.metadata.items()
     }
 
     if cleaned_doc.doc_metadata is not None:
-        cleaned_doc.doc_metadata = _sanitize_json_like(cleaned_doc.doc_metadata)
+        cleaned_doc.doc_metadata = sanitize_json_like(cleaned_doc.doc_metadata)
 
     if cleaned_doc.primary_owners is not None:
         cleaned_doc.primary_owners = [
@@ -113,11 +132,11 @@ def sanitize_document_for_postgres(document: Document) -> Document:
 
     for section in cleaned_doc.sections:
         if section.link is not None:
-            section.link = _sanitize_string(section.link)
+            section.link = sanitize_string(section.link)
         if section.text is not None:
-            section.text = _sanitize_string(section.text)
+            section.text = sanitize_string(section.text)
         if section.image_file_id is not None:
-            section.image_file_id = _sanitize_string(section.image_file_id)
+            section.image_file_id = sanitize_string(section.image_file_id)
 
     return cleaned_doc
 
@@ -129,12 +148,12 @@ def sanitize_documents_for_postgres(documents: list[Document]) -> list[Document]
 def sanitize_hierarchy_node_for_postgres(node: HierarchyNode) -> HierarchyNode:
     cleaned_node = node.model_copy(deep=True)
 
-    cleaned_node.raw_node_id = _sanitize_string(cleaned_node.raw_node_id)
-    cleaned_node.display_name = _sanitize_string(cleaned_node.display_name)
+    cleaned_node.raw_node_id = sanitize_string(cleaned_node.raw_node_id)
+    cleaned_node.display_name = sanitize_string(cleaned_node.display_name)
     if cleaned_node.raw_parent_id is not None:
-        cleaned_node.raw_parent_id = _sanitize_string(cleaned_node.raw_parent_id)
+        cleaned_node.raw_parent_id = sanitize_string(cleaned_node.raw_parent_id)
     if cleaned_node.link is not None:
-        cleaned_node.link = _sanitize_string(cleaned_node.link)
+        cleaned_node.link = sanitize_string(cleaned_node.link)
 
     if cleaned_node.external_access is not None:
         cleaned_node.external_access = _sanitize_external_access(
diff --git a/backend/tests/external_dependency_unit/celery/test_docprocessing_priority.py b/backend/tests/external_dependency_unit/celery/test_docprocessing_priority.py
index 3fb0a64d00e..c8db850546a 100644
--- a/backend/tests/external_dependency_unit/celery/test_docprocessing_priority.py
+++ b/backend/tests/external_dependency_unit/celery/test_docprocessing_priority.py
@@ -145,6 +145,10 @@ class TestDocprocessingPriorityInDocumentExtraction:
     @patch("onyx.background.indexing.run_docfetching.get_document_batch_storage")
     @patch("onyx.background.indexing.run_docfetching.MemoryTracer")
     @patch("onyx.background.indexing.run_docfetching._get_connector_runner")
+    @patch(
+        "onyx.background.indexing.run_docfetching.strip_null_characters",
+        side_effect=lambda batch: batch,
+    )
     @patch(
         "onyx.background.indexing.run_docfetching.get_recent_completed_attempts_for_cc_pair"
     )
@@ -169,6 +173,7 @@ def test_docprocessing_priority_based_on_last_successful_index_time(
         mock_save_checkpoint: MagicMock,  # noqa: ARG002
         mock_get_last_successful_attempt_poll_range_end: MagicMock,
         mock_get_recent_completed_attempts: MagicMock,
+        mock_strip_null_characters: MagicMock,  # noqa: ARG002
         mock_get_connector_runner: MagicMock,
         mock_memory_tracer_class: MagicMock,
         mock_get_batch_storage: MagicMock,
diff --git a/backend/tests/unit/onyx/chat/test_llm_step.py b/backend/tests/unit/onyx/chat/test_llm_step.py
index 889e3ec7496..d96c06669f5 100644
--- a/backend/tests/unit/onyx/chat/test_llm_step.py
+++ b/backend/tests/unit/onyx/chat/test_llm_step.py
@@ -8,7 +8,6 @@
 from onyx.chat.llm_step import _increment_turns
 from onyx.chat.llm_step import _parse_tool_args_to_dict
 from onyx.chat.llm_step import _resolve_tool_arguments
-from onyx.chat.llm_step import _sanitize_llm_output
 from onyx.chat.llm_step import _XmlToolCallContentFilter
 from onyx.chat.llm_step import extract_tool_calls_from_response_text
 from onyx.chat.llm_step import translate_history_to_llm_format
@@ -21,48 +20,49 @@
 from onyx.llm.models import ToolMessage
 from onyx.llm.models import UserMessage
 from onyx.server.query_and_chat.placement import Placement
+from onyx.utils.postgres_sanitization import sanitize_string
 
 
 class TestSanitizeLlmOutput:
-    """Tests for the _sanitize_llm_output function."""
+    """Tests for the sanitize_string function."""
 
     def test_removes_null_bytes(self) -> None:
         """Test that NULL bytes are removed from strings."""
-        assert _sanitize_llm_output("hello\x00world") == "helloworld"
-        assert _sanitize_llm_output("\x00start") == "start"
-        assert _sanitize_llm_output("end\x00") == "end"
-        assert _sanitize_llm_output("\x00\x00\x00") == ""
+        assert sanitize_string("hello\x00world") == "helloworld"
+        assert sanitize_string("\x00start") == "start"
+        assert sanitize_string("end\x00") == "end"
+        assert sanitize_string("\x00\x00\x00") == ""
 
     def test_removes_surrogates(self) -> None:
         """Test that UTF-16 surrogates are removed from strings."""
         # Low surrogate
-        assert _sanitize_llm_output("hello\ud800world") == "helloworld"
+        assert sanitize_string("hello\ud800world") == "helloworld"
         # High surrogate
-        assert _sanitize_llm_output("hello\udfffworld") == "helloworld"
+        assert sanitize_string("hello\udfffworld") == "helloworld"
         # Middle of surrogate range
-        assert _sanitize_llm_output("test\uda00value") == "testvalue"
+        assert sanitize_string("test\uda00value") == "testvalue"
 
     def test_removes_mixed_bad_characters(self) -> None:
         """Test removal of both NULL bytes and surrogates together."""
-        assert _sanitize_llm_output("a\x00b\ud800c\udfffd") == "abcd"
+        assert sanitize_string("a\x00b\ud800c\udfffd") == "abcd"
 
     def test_preserves_valid_unicode(self) -> None:
         """Test that valid Unicode characters are preserved."""
         # Emojis
-        assert _sanitize_llm_output("hello 👋 world") == "hello 👋 world"
+        assert sanitize_string("hello 👋 world") == "hello 👋 world"
         # Chinese characters
-        assert _sanitize_llm_output("你好世界") == "你好世界"
+        assert sanitize_string("你好世界") == "你好世界"
         # Mixed scripts
-        assert _sanitize_llm_output("Hello мир 世界") == "Hello мир 世界"
+        assert sanitize_string("Hello мир 世界") == "Hello мир 世界"
 
     def test_empty_string(self) -> None:
         """Test that empty strings are handled correctly."""
-        assert _sanitize_llm_output("") == ""
+        assert sanitize_string("") == ""
 
     def test_normal_ascii(self) -> None:
         """Test that normal ASCII strings pass through unchanged."""
-        assert _sanitize_llm_output("hello world") == "hello world"
-        assert _sanitize_llm_output('{"key": "value"}') == '{"key": "value"}'
+        assert sanitize_string("hello world") == "hello world"
+        assert sanitize_string('{"key": "value"}') == '{"key": "value"}'
 
 
 class TestParseToolArgsToDict:
diff --git a/backend/tests/unit/onyx/chat/test_save_chat_files.py b/backend/tests/unit/onyx/chat/test_save_chat.py
similarity index 82%
rename from backend/tests/unit/onyx/chat/test_save_chat_files.py
rename to backend/tests/unit/onyx/chat/test_save_chat.py
index fbdca47da17..548ac6f590f 100644
--- a/backend/tests/unit/onyx/chat/test_save_chat_files.py
+++ b/backend/tests/unit/onyx/chat/test_save_chat.py
@@ -1,10 +1,13 @@
-"""Tests for _extract_referenced_file_descriptors in save_chat.py.
+"""Tests for save_chat.py.
 
-Verifies that only code interpreter generated files actually referenced
-in the assistant's message text are extracted as FileDescriptors for
-cross-turn persistence.
+Covers _extract_referenced_file_descriptors and sanitization in save_chat_turn.
 """
 
+from unittest.mock import MagicMock
+
+from pytest import MonkeyPatch
+
+from onyx.chat import save_chat
 from onyx.chat.save_chat import _extract_referenced_file_descriptors
 from onyx.file_store.models import ChatFileType
 from onyx.tools.models import PythonExecutionFile
@@ -29,6 +32,9 @@ def _make_tool_call_info(
     )
 
 
+# ---- _extract_referenced_file_descriptors tests ----
+
+
 def test_returns_empty_when_no_generated_files() -> None:
     tool_call = _make_tool_call_info(generated_files=None)
     result = _extract_referenced_file_descriptors([tool_call], "some message")
@@ -176,3 +182,34 @@ def test_skips_tool_calls_without_generated_files() -> None:
 
     assert len(result) == 1
     assert result[0]["id"] == file_id
+
+
+# ---- save_chat_turn sanitization test ----
+
+
+def test_save_chat_turn_sanitizes_message_and_reasoning(
+    monkeypatch: MonkeyPatch,
+) -> None:
+    mock_tokenizer = MagicMock()
+    mock_tokenizer.encode.return_value = [1, 2, 3]
+    monkeypatch.setattr(save_chat, "get_tokenizer", lambda *_a, **_kw: mock_tokenizer)
+
+    mock_msg = MagicMock()
+    mock_msg.id = 1
+    mock_msg.chat_session_id = "test"
+    mock_msg.files = None
+
+    mock_session = MagicMock()
+
+    save_chat.save_chat_turn(
+        message_text="hello\x00world\ud800",
+        reasoning_tokens="think\x00ing\udfff",
+        tool_calls=[],
+        citation_to_doc={},
+        all_search_docs={},
+        db_session=mock_session,
+        assistant_message=mock_msg,
+    )
+
+    assert mock_msg.message == "helloworld"
+    assert mock_msg.reasoning_tokens == "thinking"
diff --git a/backend/tests/unit/onyx/db/test_tools.py b/backend/tests/unit/onyx/db/test_tools.py
new file mode 100644
index 00000000000..66e70d53d89
--- /dev/null
+++ b/backend/tests/unit/onyx/db/test_tools.py
@@ -0,0 +1,27 @@
+from unittest.mock import MagicMock
+from uuid import uuid4
+
+from onyx.db import tools as tools_mod
+
+
+def test_create_tool_call_no_commit_sanitizes_fields() -> None:
+    mock_session = MagicMock()
+
+    tool_call = tools_mod.create_tool_call_no_commit(
+        chat_session_id=uuid4(),
+        parent_chat_message_id=1,
+        turn_number=0,
+        tool_id=1,
+        tool_call_id="tc-1",
+        tool_call_arguments={"task\x00": "research\ud800 topic"},
+        tool_call_response="report\x00 text\udfff here",
+        tool_call_tokens=10,
+        db_session=mock_session,
+        reasoning_tokens="reason\x00ing\ud800",
+        generated_images=[{"url": "img\x00.png\udfff"}],
+    )
+
+    assert tool_call.tool_call_response == "report text here"
+    assert tool_call.reasoning_tokens == "reasoning"
+    assert tool_call.tool_call_arguments == {"task": "research topic"}
+    assert tool_call.generated_images == [{"url": "img.png"}]
diff --git a/backend/tests/unit/onyx/indexing/test_postgres_sanitization.py b/backend/tests/unit/onyx/utils/test_postgres_sanitization.py
similarity index 71%
rename from backend/tests/unit/onyx/indexing/test_postgres_sanitization.py
rename to backend/tests/unit/onyx/utils/test_postgres_sanitization.py
index e93eb831c01..940926674eb 100644
--- a/backend/tests/unit/onyx/indexing/test_postgres_sanitization.py
+++ b/backend/tests/unit/onyx/utils/test_postgres_sanitization.py
@@ -9,8 +9,79 @@
 from onyx.connectors.models import TextSection
 from onyx.db.enums import HierarchyNodeType
 from onyx.indexing import indexing_pipeline
-from onyx.indexing.postgres_sanitization import sanitize_document_for_postgres
-from onyx.indexing.postgres_sanitization import sanitize_hierarchy_node_for_postgres
+from onyx.utils.postgres_sanitization import sanitize_document_for_postgres
+from onyx.utils.postgres_sanitization import sanitize_hierarchy_node_for_postgres
+from onyx.utils.postgres_sanitization import sanitize_json_like
+from onyx.utils.postgres_sanitization import sanitize_string
+
+
+# ---- sanitize_string tests ----
+
+
+def test_sanitize_string_strips_nul_bytes() -> None:
+    assert sanitize_string("hello\x00world") == "helloworld"
+    assert sanitize_string("\x00\x00\x00") == ""
+    assert sanitize_string("clean") == "clean"
+
+
+def test_sanitize_string_strips_high_surrogates() -> None:
+    assert sanitize_string("before\ud800after") == "beforeafter"
+    assert sanitize_string("a\udbffb") == "ab"
+
+
+def test_sanitize_string_strips_low_surrogates() -> None:
+    assert sanitize_string("before\udc00after") == "beforeafter"
+    assert sanitize_string("a\udfffb") == "ab"
+
+
+def test_sanitize_string_strips_nul_and_surrogates_together() -> None:
+    assert sanitize_string("he\x00llo\ud800 wo\udfffrld\x00") == "hello world"
+
+
+def test_sanitize_string_preserves_valid_unicode() -> None:
+    assert sanitize_string("café ☕ 日本語 😀") == "café ☕ 日本語 😀"
+
+
+def test_sanitize_string_empty_input() -> None:
+    assert sanitize_string("") == ""
+
+
+# ---- sanitize_json_like tests ----
+
+
+def test_sanitize_json_like_handles_plain_string() -> None:
+    assert sanitize_json_like("he\x00llo\ud800") == "hello"
+
+
+def test_sanitize_json_like_handles_nested_dict() -> None:
+    dirty = {
+        "ke\x00y": "va\ud800lue",
+        "nested": {"inne\x00r": "de\udfffep"},
+    }
+    assert sanitize_json_like(dirty) == {
+        "key": "value",
+        "nested": {"inner": "deep"},
+    }
+
+
+def test_sanitize_json_like_handles_list_with_surrogates() -> None:
+    dirty = ["a\x00", "b\ud800", {"c\udc00": "d\udfff"}]
+    assert sanitize_json_like(dirty) == ["a", "b", {"c": "d"}]
+
+
+def test_sanitize_json_like_handles_tuple() -> None:
+    dirty = ("a\x00", "b\ud800")
+    assert sanitize_json_like(dirty) == ("a", "b")
+
+
+def test_sanitize_json_like_passes_through_non_strings() -> None:
+    assert sanitize_json_like(42) == 42
+    assert sanitize_json_like(3.14) == 3.14
+    assert sanitize_json_like(True) is True
+    assert sanitize_json_like(None) is None
+
+
+# ---- sanitize_document_for_postgres tests ----
 
 
 def test_sanitize_document_for_postgres_removes_nul_bytes() -> None:

From bda03bafca1b43d91dc073ea579b8d5d520b1213 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 6 Mar 2026 01:52:22 +0000
Subject: [PATCH 137/267] chore(deps): bump serialize-javascript and
 terser-webpack-plugin in /web (#9125)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 web/package-lock.json | 42 +++---------------------------------------
 1 file changed, 3 insertions(+), 39 deletions(-)

diff --git a/web/package-lock.json b/web/package-lock.json
index 61116c5771f..30b3b0abf3b 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -13904,14 +13904,6 @@
       ],
       "license": "MIT"
     },
-    "node_modules/randombytes": {
-      "version": "2.1.0",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "safe-buffer": "^5.1.0"
-      }
-    },
     "node_modules/react": {
       "version": "19.2.4",
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
@@ -14608,25 +14600,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/safe-buffer": {
-      "version": "5.2.1",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/safe-push-apply": {
       "version": "1.0.0",
       "dev": true,
@@ -14706,14 +14679,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/serialize-javascript": {
-      "version": "6.0.2",
-      "license": "BSD-3-Clause",
-      "peer": true,
-      "dependencies": {
-        "randombytes": "^2.1.0"
-      }
-    },
     "node_modules/set-function-length": {
       "version": "1.2.2",
       "dev": true,
@@ -15521,16 +15486,15 @@
       }
     },
     "node_modules/terser-webpack-plugin": {
-      "version": "5.3.16",
-      "resolved": "https://registry.npmjs.org/terser-webpack-plugin/-/terser-webpack-plugin-5.3.16.tgz",
-      "integrity": "sha512-h9oBFCWrq78NyWWVcSwZarJkZ01c2AyGrzs1crmHZO3QUg9D61Wu4NPjBy69n7JqylFF5y+CsUZYmYEIZ3mR+Q==",
+      "version": "5.3.17",
+      "resolved": "https://registry.npmjs.org/terser-webpack-plugin/-/terser-webpack-plugin-5.3.17.tgz",
+      "integrity": "sha512-YR7PtUp6GMU91BgSJmlaX/rS2lGDbAF7D+Wtq7hRO+MiljNmodYvqslzCFiYVAgW+Qoaaia/QUIP4lGXufjdZw==",
       "license": "MIT",
       "peer": true,
       "dependencies": {
         "@jridgewell/trace-mapping": "^0.3.25",
         "jest-worker": "^27.4.5",
         "schema-utils": "^4.3.0",
-        "serialize-javascript": "^6.0.2",
         "terser": "^5.31.1"
       },
       "engines": {

From d0836e2603c4198e369d6a8003aa9f009a955eb0 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Thu, 5 Mar 2026 18:13:21 -0800
Subject: [PATCH 138/267] fix(ci): Cleaning up Release Tags (#8172)

---
 .github/workflows/deployment.yml | 56 ++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
index 3edfade16bb..66105c0257e 100644
--- a/.github/workflows/deployment.yml
+++ b/.github/workflows/deployment.yml
@@ -182,9 +182,53 @@ jobs:
           title: "🚨 Version Tag Check Failed"
           ref-name: ${{ github.ref_name }}
 
-  build-desktop:
+  # Create GitHub release first, before desktop builds start.
+  # This ensures all desktop matrix jobs upload to the same release instead of
+  # racing to create duplicate releases.
+  create-release:
     needs: determine-builds
     if: needs.determine-builds.outputs.build-desktop == 'true'
+    runs-on: ubuntu-slim
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    outputs:
+      release-id: ${{ steps.create-release.outputs.id }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Determine release tag
+        id: release-tag
+        env:
+          IS_TEST_RUN: ${{ needs.determine-builds.outputs.is-test-run }}
+          SHORT_SHA: ${{ needs.determine-builds.outputs.short-sha }}
+        run: |
+          if [ "${IS_TEST_RUN}" == "true" ]; then
+            echo "tag=v0.0.0-dev+${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Release
+        id: create-release
+        uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # ratchet:softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.release-tag.outputs.tag }}
+          name: ${{ steps.release-tag.outputs.tag }}
+          body: "See the assets to download this version and install."
+          draft: true
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-desktop:
+    needs:
+      - determine-builds
+      - create-release
+    if: needs.determine-builds.outputs.build-desktop == 'true'
     permissions:
       id-token: write
       contents: write
@@ -208,7 +252,7 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6.0.2
         with:
-          # NOTE: persist-credentials is needed for tauri-action to create GitHub releases.
+          # NOTE: persist-credentials is needed for tauri-action to upload assets to GitHub releases.
           persist-credentials: true # zizmor: ignore[artipacked]
 
       - name: Configure AWS credentials
@@ -353,11 +397,9 @@ jobs:
           APPLE_SIGNING_IDENTITY: ${{ env.CERT_ID }}
           APPLE_TEAM_ID: ${{ env.APPLE_TEAM_ID }}
         with:
-          tagName: ${{ needs.determine-builds.outputs.is-test-run != 'true' && 'v__VERSION__' || format('v0.0.0-dev+{0}', needs.determine-builds.outputs.short-sha) }}
-          releaseName: ${{ needs.determine-builds.outputs.is-test-run != 'true' && 'v__VERSION__' || format('v0.0.0-dev+{0}', needs.determine-builds.outputs.short-sha) }}
-          releaseBody: "See the assets to download this version and install."
-          releaseDraft: true
-          prerelease: false
+          # Use the release created by the create-release job to avoid race conditions
+          # when multiple matrix jobs try to create/update the same release simultaneously
+          releaseId: ${{ needs.create-release.outputs.release-id }}
           assetNamePattern: "[name]_[arch][ext]"
           args: ${{ matrix.args }}
 

From 0f6ae6f69cb6f92212d049221a65e4acbdb61d7f Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Thu, 5 Mar 2026 19:36:27 -0800
Subject: [PATCH 139/267] fix: Sync does not update default model (#9129)

---
 backend/onyx/db/llm.py                        |  40 +++++++
 backend/onyx/server/manage/llm/api.py         |  25 ++++
 .../llm/test_llm_provider_auto_mode.py        | 110 +++++++++++++++++-
 3 files changed, 169 insertions(+), 6 deletions(-)

diff --git a/backend/onyx/db/llm.py b/backend/onyx/db/llm.py
index c3f7c279853..5a8e32229cc 100644
--- a/backend/onyx/db/llm.py
+++ b/backend/onyx/db/llm.py
@@ -25,8 +25,11 @@
 from onyx.server.manage.embedding.models import CloudEmbeddingProviderCreationRequest
 from onyx.server.manage.llm.models import LLMProviderUpsertRequest
 from onyx.server.manage.llm.models import LLMProviderView
+from onyx.utils.logger import setup_logger
 from shared_configs.enums import EmbeddingProvider
 
+logger = setup_logger()
+
 
 def update_group_llm_provider_relationships__no_commit(
     llm_provider_id: int,
@@ -812,6 +815,43 @@ def sync_auto_mode_models(
             changes += 1
 
     db_session.commit()
+
+    # Update the default if this provider currently holds the global CHAT default
+    recommended_default = llm_recommendations.get_default_model(provider.provider)
+    if recommended_default:
+        current_default_name = db_session.scalar(
+            select(ModelConfiguration.name)
+            .join(
+                LLMModelFlow,
+                LLMModelFlow.model_configuration_id == ModelConfiguration.id,
+            )
+            .where(
+                ModelConfiguration.llm_provider_id == provider.id,
+                LLMModelFlow.llm_model_flow_type == LLMModelFlowType.CHAT,
+                LLMModelFlow.is_default == True,  # noqa: E712
+            )
+        )
+
+        if (
+            current_default_name is not None
+            and current_default_name != recommended_default.name
+        ):
+            try:
+                _update_default_model(
+                    db_session=db_session,
+                    provider_id=provider.id,
+                    model=recommended_default.name,
+                    flow_type=LLMModelFlowType.CHAT,
+                )
+                changes += 1
+            except ValueError:
+                logger.warning(
+                    "Recommended default model '%s' not found "
+                    "for provider_id=%s; skipping default update.",
+                    recommended_default.name,
+                    provider.id,
+                )
+
     return changes
 
 
diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index 8b2ad82e6c1..0676775772f 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -445,6 +445,17 @@ def put_llm_provider(
         not existing_provider or not existing_provider.is_auto_mode
     )
 
+    # Before the upsert, check if this provider currently owns the global
+    # CHAT default. The upsert may cascade-delete model_configurations
+    # (and their flow mappings), so we need to remember this beforehand.
+    was_default_provider = False
+    if existing_provider and transitioning_to_auto_mode:
+        current_default = fetch_default_llm_model(db_session)
+        was_default_provider = (
+            current_default is not None
+            and current_default.llm_provider_id == existing_provider.id
+        )
+
     try:
         result = upsert_llm_provider(
             llm_provider_upsert_request=llm_provider_upsert_request,
@@ -467,6 +478,20 @@ def put_llm_provider(
                         updated_provider,
                         config,
                     )
+
+                    # If this provider was the default before the transition,
+                    # restore the default using the recommended model.
+                    if was_default_provider:
+                        recommended = config.get_default_model(
+                            llm_provider_upsert_request.provider
+                        )
+                        if recommended:
+                            update_default_provider(
+                                provider_id=updated_provider.id,
+                                model_name=recommended.name,
+                                db_session=db_session,
+                            )
+
                     # Refresh result with synced models
                     result = LLMProviderView.from_model(updated_provider)
 
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py b/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
index d0510f3a73f..ef986bb73ab 100644
--- a/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
@@ -698,6 +698,99 @@ def test_sync_auto_mode_creates_flow_rows(
 class TestAutoModeTransitionsAndResync:
     """Tests for auto/manual transitions, config evolution, and sync idempotency."""
 
+    def test_transition_to_auto_mode_preserves_default(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """When the default provider transitions from manual to auto mode,
+        the global default should be preserved (set to the recommended model).
+
+        Steps:
+        1. Create a manual-mode provider with models, set it as global default.
+        2. Transition to auto mode (model_configurations=[] triggers cascade
+           delete of old ModelConfigurations and their LLMModelFlow rows).
+        3. Verify the provider is still the global default, now using the
+           recommended default model from the GitHub config.
+        """
+        initial_models = [
+            ModelConfigurationUpsertRequest(name="gpt-4o", is_visible=True),
+            ModelConfigurationUpsertRequest(name="gpt-4o-mini", is_visible=True),
+        ]
+
+        auto_config = _create_mock_llm_recommendations(
+            provider=LlmProviderNames.OPENAI,
+            default_model_name="gpt-4o-mini",
+            additional_models=["gpt-4o"],
+        )
+
+        try:
+            # Step 1: Create manual-mode provider and set as default
+            put_llm_provider(
+                llm_provider_upsert_request=LLMProviderUpsertRequest(
+                    name=provider_name,
+                    provider=LlmProviderNames.OPENAI,
+                    api_key="sk-test-key-00000000000000000000000000000000000",
+                    api_key_changed=True,
+                    is_auto_mode=False,
+                    model_configurations=initial_models,
+                ),
+                is_creation=True,
+                _=_create_mock_admin(),
+                db_session=db_session,
+            )
+
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+            update_default_provider(provider.id, "gpt-4o", db_session)
+
+            default_before = fetch_default_llm_model(db_session)
+            assert default_before is not None
+            assert default_before.name == "gpt-4o"
+            assert default_before.llm_provider_id == provider.id
+
+            # Step 2: Transition to auto mode
+            with patch(
+                "onyx.server.manage.llm.api.fetch_llm_recommendations_from_github",
+                return_value=auto_config,
+            ):
+                put_llm_provider(
+                    llm_provider_upsert_request=LLMProviderUpsertRequest(
+                        id=provider.id,
+                        name=provider_name,
+                        provider=LlmProviderNames.OPENAI,
+                        api_key=None,
+                        api_key_changed=False,
+                        is_auto_mode=True,
+                        model_configurations=[],
+                    ),
+                    is_creation=False,
+                    _=_create_mock_admin(),
+                    db_session=db_session,
+                )
+
+            # Step 3: Default should be preserved on this provider
+            db_session.expire_all()
+            default_after = fetch_default_llm_model(db_session)
+            assert default_after is not None, (
+                "Default model should not be None after transitioning to auto mode — "
+                "the provider was the default before and should remain so"
+            )
+            assert (
+                default_after.llm_provider_id == provider.id
+            ), "Default should still belong to the same provider after transition"
+            assert default_after.name == "gpt-4o-mini", (
+                f"Default should be updated to the recommended model 'gpt-4o-mini', "
+                f"got '{default_after.name}'"
+            )
+
+        finally:
+            db_session.rollback()
+            _cleanup_provider(db_session, provider_name)
+
     def test_auto_to_manual_mode_preserves_models_and_stops_syncing(
         self,
         db_session: Session,
@@ -1042,14 +1135,19 @@ def test_default_model_hidden_when_removed_from_config(
             assert visibility["gpt-4o"] is False, "Removed default should be hidden"
             assert visibility["gpt-4o-mini"] is True, "New default should be visible"
 
-            # The LLMModelFlow row for gpt-4o still exists (is_default=True),
-            # but the model is hidden. fetch_default_llm_model filters on
-            # is_visible=True, so it should NOT return gpt-4o.
+            # The old default (gpt-4o) is now hidden. sync_auto_mode_models
+            # should update the global default to the new recommended default
+            # (gpt-4o-mini) so that it is not silently lost.
             db_session.expire_all()
             default_after = fetch_default_llm_model(db_session)
-            assert (
-                default_after is None or default_after.name != "gpt-4o"
-            ), "Hidden model should not be returned as the default"
+            assert default_after is not None, (
+                "Default model should not be None — sync should set the new "
+                "recommended default when the old one is hidden"
+            )
+            assert default_after.name == "gpt-4o-mini", (
+                f"Default should be updated to the new recommended model "
+                f"'gpt-4o-mini', but got '{default_after.name}'"
+            )
 
         finally:
             db_session.rollback()

From c826d0469ef996a88f84819ec0bcff4b49df54ce Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 5 Mar 2026 19:49:03 -0800
Subject: [PATCH 140/267] fix(fe): make BlinkingBar smaller (#9132)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 web/src/app/app/message/BlinkingBar.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/src/app/app/message/BlinkingBar.tsx b/web/src/app/app/message/BlinkingBar.tsx
index e3b710b460a..0edf3f4ac41 100644
--- a/web/src/app/app/message/BlinkingBar.tsx
+++ b/web/src/app/app/message/BlinkingBar.tsx
@@ -4,7 +4,7 @@ export function BlinkingBar({ addMargin = false }: { addMargin?: boolean }) {
   return (
     <span
       className={cn(
-        "animate-pulse flex-none bg-theme-primary-05 relative top-[0.25rem] inline-block w-[0.5em] h-[1.25em]",
+        "animate-pulse flex-none bg-theme-primary-05 relative top-[0.15rem] inline-block w-[0.5rem] h-[1rem]",
         addMargin && "ml-1"
       )}
     ></span>

From a51f0d7cb226c41afe700de87034c8a45606d413 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Thu, 5 Mar 2026 21:42:20 -0800
Subject: [PATCH 141/267] feat: Onyx CLI (#8958)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 .cursor/skills/onyx-cli/SKILL.md      | 161 +++++++
 .pre-commit-config.yaml               |   2 +-
 cli/.gitignore                        |   3 +
 cli/README.md                         | 118 +++++
 cli/cmd/agents.go                     |  63 +++
 cli/cmd/ask.go                        | 124 +++++
 cli/cmd/chat.go                       |  33 ++
 cli/cmd/configure.go                  |  19 +
 cli/cmd/root.go                       |  40 ++
 cli/cmd/validate.go                   |  41 ++
 cli/go.mod                            |  45 ++
 cli/go.sum                            |  94 ++++
 cli/internal/api/client.go            | 284 ++++++++++++
 cli/internal/api/errors.go            |  13 +
 cli/internal/api/stream.go            | 136 ++++++
 cli/internal/config/config.go         | 101 ++++
 cli/internal/config/config_test.go    | 215 +++++++++
 cli/internal/models/events.go         | 193 ++++++++
 cli/internal/models/models.go         | 112 +++++
 cli/internal/onboarding/onboarding.go | 170 +++++++
 cli/internal/parser/parser.go         | 248 ++++++++++
 cli/internal/parser/parser_test.go    | 419 +++++++++++++++++
 cli/internal/tui/app.go               | 639 ++++++++++++++++++++++++++
 cli/internal/tui/commands.go          | 200 ++++++++
 cli/internal/tui/help.go              |  23 +
 cli/internal/tui/input.go             | 241 ++++++++++
 cli/internal/tui/messages.go          |  36 ++
 cli/internal/tui/splash.go            |  79 ++++
 cli/internal/tui/statusbar.go         |  60 +++
 cli/internal/tui/styles.go            |  29 ++
 cli/internal/tui/viewport.go          | 448 ++++++++++++++++++
 cli/internal/tui/viewport_test.go     | 264 +++++++++++
 cli/internal/util/browser.go          |  29 ++
 cli/internal/util/styles.go           |  13 +
 cli/main.go                           |  23 +
 35 files changed, 4717 insertions(+), 1 deletion(-)
 create mode 100644 .cursor/skills/onyx-cli/SKILL.md
 create mode 100644 cli/.gitignore
 create mode 100644 cli/README.md
 create mode 100644 cli/cmd/agents.go
 create mode 100644 cli/cmd/ask.go
 create mode 100644 cli/cmd/chat.go
 create mode 100644 cli/cmd/configure.go
 create mode 100644 cli/cmd/root.go
 create mode 100644 cli/cmd/validate.go
 create mode 100644 cli/go.mod
 create mode 100644 cli/go.sum
 create mode 100644 cli/internal/api/client.go
 create mode 100644 cli/internal/api/errors.go
 create mode 100644 cli/internal/api/stream.go
 create mode 100644 cli/internal/config/config.go
 create mode 100644 cli/internal/config/config_test.go
 create mode 100644 cli/internal/models/events.go
 create mode 100644 cli/internal/models/models.go
 create mode 100644 cli/internal/onboarding/onboarding.go
 create mode 100644 cli/internal/parser/parser.go
 create mode 100644 cli/internal/parser/parser_test.go
 create mode 100644 cli/internal/tui/app.go
 create mode 100644 cli/internal/tui/commands.go
 create mode 100644 cli/internal/tui/help.go
 create mode 100644 cli/internal/tui/input.go
 create mode 100644 cli/internal/tui/messages.go
 create mode 100644 cli/internal/tui/splash.go
 create mode 100644 cli/internal/tui/statusbar.go
 create mode 100644 cli/internal/tui/styles.go
 create mode 100644 cli/internal/tui/viewport.go
 create mode 100644 cli/internal/tui/viewport_test.go
 create mode 100644 cli/internal/util/browser.go
 create mode 100644 cli/internal/util/styles.go
 create mode 100644 cli/main.go

diff --git a/.cursor/skills/onyx-cli/SKILL.md b/.cursor/skills/onyx-cli/SKILL.md
new file mode 100644
index 00000000000..bd5606284d4
--- /dev/null
+++ b/.cursor/skills/onyx-cli/SKILL.md
@@ -0,0 +1,161 @@
+---
+name: onyx-cli
+description: Query the Onyx knowledge base using the onyx-cli command. Use when the user wants to search company documents, ask questions about internal knowledge, query connected data sources, or look up information stored in Onyx.
+---
+
+# Onyx CLI — Agent Tool
+
+Onyx is an enterprise search and Gen-AI platform that connects to company documents, apps, and people. The `onyx-cli` CLI provides non-interactive commands to query the Onyx knowledge base and list available agents.
+
+## Prerequisites
+
+### 1. Check if installed
+
+```bash
+which onyx-cli
+```
+
+### 2. Install (if needed)
+
+**Primary — pip:**
+
+```bash
+pip install onyx-cli
+```
+
+**From source (Go):**
+
+```bash
+cd cli && go build -o onyx-cli . && sudo mv onyx-cli /usr/local/bin/
+```
+
+### 3. Check if configured
+
+```bash
+onyx-cli validate-config
+```
+
+This checks the config file exists, API key is present, and tests the server connection via `/api/me`. Exit code 0 on success, non-zero with a descriptive error on failure.
+
+If unconfigured, you have two options:
+
+**Option A — Interactive setup (requires user input):**
+
+```bash
+onyx-cli configure
+```
+
+This prompts for the Onyx server URL and API key, tests the connection, and saves config.
+
+**Option B — Environment variables (non-interactive, preferred for agents):**
+
+```bash
+export ONYX_SERVER_URL="https://your-onyx-server.com"  # default: https://cloud.onyx.app
+export ONYX_API_KEY="your-api-key"
+```
+
+Environment variables override the config file. If these are set, no config file is needed.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ONYX_SERVER_URL` | No | Onyx server base URL (default: `https://cloud.onyx.app`) |
+| `ONYX_API_KEY` | Yes | API key for authentication |
+| `ONYX_PERSONA_ID` | No | Default agent/persona ID |
+
+If neither the config file nor environment variables are set, tell the user that `onyx-cli` needs to be configured and ask them to either:
+- Run `onyx-cli configure` interactively, or
+- Set `ONYX_SERVER_URL` and `ONYX_API_KEY` environment variables
+
+## Commands
+
+### Validate configuration
+
+```bash
+onyx-cli validate-config
+```
+
+Checks config file exists, API key is present, and tests the server connection. Use this before `ask` or `agents` to confirm the CLI is properly set up.
+
+### List available agents
+
+```bash
+onyx-cli agents
+```
+
+Prints a table of agent IDs, names, and descriptions. Use `--json` for structured output:
+
+```bash
+onyx-cli agents --json
+```
+
+Use agent IDs with `ask --agent-id` to query a specific agent.
+
+### Basic query (plain text output)
+
+```bash
+onyx-cli ask "What is our company's PTO policy?"
+```
+
+Streams the answer as plain text to stdout. Exit code 0 on success, non-zero on error.
+
+### JSON output (structured events)
+
+```bash
+onyx-cli ask --json "What authentication methods do we support?"
+```
+
+Outputs JSON-encoded parsed stream events (one object per line). Key event objects include message deltas, stop, errors, search-start, and citation payloads.
+
+| Event Type | Description |
+|------------|-------------|
+| `message_delta` | Content token — concatenate all `content` fields for the full answer |
+| `stop` | Stream complete |
+| `error` | Error with `error` message field |
+| `search_tool_start` | Onyx started searching documents |
+| `citation_info` | Source citation with `citation_number` and `document_id` |
+
+### Specify an agent
+
+```bash
+onyx-cli ask --agent-id 5 "Summarize our Q4 roadmap"
+```
+
+Uses a specific Onyx agent/persona instead of the default.
+
+### All flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--agent-id` | int | Agent ID to use (overrides default) |
+| `--json` | bool | Output raw NDJSON events instead of plain text |
+
+## When to Use
+
+Use `onyx-cli ask` when:
+
+- The user asks about company-specific information (policies, docs, processes)
+- You need to search internal knowledge bases or connected data sources
+- The user references Onyx, asks you to "search Onyx", or wants to query their documents
+- You need context from company wikis, Confluence, Google Drive, Slack, or other connected sources
+
+Do NOT use when:
+
+- The question is about general programming knowledge (use your own knowledge)
+- The user is asking about code in the current repository (use grep/read tools)
+- The user hasn't mentioned Onyx and the question doesn't require internal company data
+
+## Examples
+
+```bash
+# Simple question
+onyx-cli ask "What are the steps to deploy to production?"
+
+# Get structured output for parsing
+onyx-cli ask --json "List all active API integrations"
+
+# Use a specialized agent
+onyx-cli ask --agent-id 3 "What were the action items from last week's standup?"
+
+# Pipe the answer into another command
+onyx-cli ask "What is the database schema for users?" | head -20
+```
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index fca45fd4af6..3d37c042cfa 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -123,7 +123,7 @@ repos:
     hooks:
       - id: golangci-lint
         language_version: "1.26.0"
-        entry: bash -c "find tools/ -name go.mod -print0 | xargs -0 -I{} bash -c 'cd \"$(dirname {})\" && golangci-lint run ./...'"
+        entry: bash -c "find . -name go.mod -not -path './.venv/*' -print0 | xargs -0 -I{} bash -c 'cd \"$(dirname {})\" && golangci-lint run ./...'"
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
diff --git a/cli/.gitignore b/cli/.gitignore
new file mode 100644
index 00000000000..fb062fff6ab
--- /dev/null
+++ b/cli/.gitignore
@@ -0,0 +1,3 @@
+onyx-cli
+cli
+onyx.cli
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 00000000000..f86ad7476f9
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,118 @@
+# Onyx CLI
+
+A terminal interface for chatting with your [Onyx](https://github.com/onyx-dot-app/onyx) agent. Built with Go using [Bubble Tea](https://github.com/charmbracelet/bubbletea) for the TUI framework.
+
+## Installation
+
+```shell
+pip install onyx-cli
+```
+
+Or with uv:
+
+```shell
+uv pip install onyx-cli
+```
+
+## Setup
+
+Run the interactive setup:
+
+```shell
+onyx-cli configure
+```
+
+This prompts for your Onyx server URL and API key, tests the connection, and saves config to `~/.config/onyx-cli/config.json`.
+
+Environment variables override config file values:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ONYX_SERVER_URL` | No | Server base URL (default: `http://localhost:3000`) |
+| `ONYX_API_KEY` | Yes | API key for authentication |
+| `ONYX_PERSONA_ID` | No | Default agent/persona ID |
+
+## Usage
+
+### Interactive chat (default)
+
+```shell
+onyx-cli
+```
+
+### One-shot question
+
+```shell
+onyx-cli ask "What is our company's PTO policy?"
+onyx-cli ask --agent-id 5 "Summarize this topic"
+onyx-cli ask --json "Hello"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--agent-id <int>` | Agent ID to use (overrides default) |
+| `--json` | Output raw NDJSON events instead of plain text |
+
+### List agents
+
+```shell
+onyx-cli agents
+onyx-cli agents --json
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `chat` | Launch the interactive chat TUI (default) |
+| `ask` | Ask a one-shot question (non-interactive) |
+| `agents` | List available agents |
+| `configure` | Configure server URL and API key |
+
+## Slash Commands (in TUI)
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help message |
+| `/new` | Start a new chat session |
+| `/agent` | List and switch agents |
+| `/attach <path>` | Attach a file to next message |
+| `/sessions` | List recent chat sessions |
+| `/clear` | Clear the chat display |
+| `/configure` | Re-run connection setup |
+| `/connectors` | Open connectors in browser |
+| `/settings` | Open settings in browser |
+| `/quit` | Exit Onyx CLI |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Send message |
+| `Escape` | Cancel current generation |
+| `Ctrl+O` | Toggle source citations |
+| `Ctrl+D` | Quit (press twice) |
+| `Scroll` / `Shift+Up/Down` | Scroll chat history |
+| `Page Up` / `Page Down` | Scroll half page |
+
+## Building from Source
+
+Requires [Go 1.24+](https://go.dev/dl/).
+
+```shell
+cd cli
+go build -o onyx-cli .
+```
+
+## Development
+
+```shell
+# Run tests
+go test ./...
+
+# Build
+go build -o onyx-cli .
+
+# Lint
+staticcheck ./...
+```
diff --git a/cli/cmd/agents.go b/cli/cmd/agents.go
new file mode 100644
index 00000000000..af870dbff13
--- /dev/null
+++ b/cli/cmd/agents.go
@@ -0,0 +1,63 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"text/tabwriter"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/api"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/spf13/cobra"
+)
+
+func newAgentsCmd() *cobra.Command {
+	var agentsJSON bool
+
+	cmd := &cobra.Command{
+		Use:   "agents",
+		Short: "List available agents",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := config.Load()
+			if !cfg.IsConfigured() {
+				return fmt.Errorf("onyx CLI is not configured — run 'onyx-cli configure' first")
+			}
+
+			client := api.NewClient(cfg)
+			agents, err := client.ListAgents(cmd.Context())
+			if err != nil {
+				return fmt.Errorf("failed to list agents: %w", err)
+			}
+
+			if agentsJSON {
+				data, err := json.MarshalIndent(agents, "", "  ")
+				if err != nil {
+					return fmt.Errorf("failed to marshal agents: %w", err)
+				}
+				fmt.Println(string(data))
+				return nil
+			}
+
+			if len(agents) == 0 {
+				fmt.Println("No agents available.")
+				return nil
+			}
+
+			w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 4, 2, ' ', 0)
+			_, _ = fmt.Fprintln(w, "ID\tNAME\tDESCRIPTION")
+			for _, a := range agents {
+				desc := a.Description
+				if len(desc) > 60 {
+					desc = desc[:57] + "..."
+				}
+				_, _ = fmt.Fprintf(w, "%d\t%s\t%s\n", a.ID, a.Name, desc)
+			}
+			_ = w.Flush()
+
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&agentsJSON, "json", false, "Output agents as JSON")
+
+	return cmd
+}
diff --git a/cli/cmd/ask.go b/cli/cmd/ask.go
new file mode 100644
index 00000000000..2696da3be77
--- /dev/null
+++ b/cli/cmd/ask.go
@@ -0,0 +1,124 @@
+package cmd
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/api"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+	"github.com/spf13/cobra"
+)
+
+func newAskCmd() *cobra.Command {
+	var (
+		askAgentID int
+		askJSON    bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "ask [question]",
+		Short: "Ask a one-shot question (non-interactive)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := config.Load()
+			if !cfg.IsConfigured() {
+				return fmt.Errorf("onyx CLI is not configured — run 'onyx-cli configure' first")
+			}
+
+			question := args[0]
+			agentID := cfg.DefaultAgentID
+			if cmd.Flags().Changed("agent-id") {
+				agentID = askAgentID
+			}
+
+			ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM)
+			defer stop()
+
+			client := api.NewClient(cfg)
+			parentID := -1
+			ch := client.SendMessageStream(
+				ctx,
+				question,
+				nil,
+				agentID,
+				&parentID,
+				nil,
+			)
+
+			var sessionID string
+			var lastErr error
+			gotStop := false
+			for event := range ch {
+				if e, ok := event.(models.SessionCreatedEvent); ok {
+					sessionID = e.ChatSessionID
+				}
+
+				if askJSON {
+					wrapped := struct {
+						Type  string             `json:"type"`
+						Event models.StreamEvent `json:"event"`
+					}{
+						Type:  event.EventType(),
+						Event: event,
+					}
+					data, err := json.Marshal(wrapped)
+					if err != nil {
+						return fmt.Errorf("error marshaling event: %w", err)
+					}
+					fmt.Println(string(data))
+					if _, ok := event.(models.ErrorEvent); ok {
+						lastErr = fmt.Errorf("%s", event.(models.ErrorEvent).Error)
+					}
+					if _, ok := event.(models.StopEvent); ok {
+						gotStop = true
+					}
+					continue
+				}
+
+				switch e := event.(type) {
+				case models.MessageDeltaEvent:
+					fmt.Print(e.Content)
+				case models.ErrorEvent:
+					return fmt.Errorf("%s", e.Error)
+				case models.StopEvent:
+					fmt.Println()
+					return nil
+				}
+			}
+
+			if ctx.Err() != nil {
+				if sessionID != "" {
+					client.StopChatSession(context.Background(), sessionID)
+				}
+				if !askJSON {
+					fmt.Println()
+				}
+				return nil
+			}
+
+			if lastErr != nil {
+				return lastErr
+			}
+			if !gotStop {
+				if !askJSON {
+					fmt.Println()
+				}
+				return fmt.Errorf("stream ended unexpectedly")
+			}
+			if !askJSON {
+				fmt.Println()
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().IntVar(&askAgentID, "agent-id", 0, "Agent ID to use")
+	cmd.Flags().BoolVar(&askJSON, "json", false, "Output raw JSON events")
+	// Suppress cobra's default error/usage on RunE errors
+	return cmd
+}
diff --git a/cli/cmd/chat.go b/cli/cmd/chat.go
new file mode 100644
index 00000000000..823a84313b4
--- /dev/null
+++ b/cli/cmd/chat.go
@@ -0,0 +1,33 @@
+package cmd
+
+import (
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/onboarding"
+	"github.com/onyx-dot-app/onyx/cli/internal/tui"
+	"github.com/spf13/cobra"
+)
+
+func newChatCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "chat",
+		Short: "Launch the interactive chat TUI (default)",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := config.Load()
+
+			// First-run: onboarding
+			if !config.ConfigExists() || !cfg.IsConfigured() {
+				result := onboarding.Run(&cfg)
+				if result == nil {
+					return nil
+				}
+				cfg = *result
+			}
+
+			m := tui.NewModel(cfg)
+			p := tea.NewProgram(m, tea.WithAltScreen(), tea.WithMouseCellMotion())
+			_, err := p.Run()
+			return err
+		},
+	}
+}
diff --git a/cli/cmd/configure.go b/cli/cmd/configure.go
new file mode 100644
index 00000000000..6c7b00c1e0a
--- /dev/null
+++ b/cli/cmd/configure.go
@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/onboarding"
+	"github.com/spf13/cobra"
+)
+
+func newConfigureCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "configure",
+		Short: "Configure server URL and API key",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := config.Load()
+			onboarding.Run(&cfg)
+			return nil
+		},
+	}
+}
diff --git a/cli/cmd/root.go b/cli/cmd/root.go
new file mode 100644
index 00000000000..c47d3bd7682
--- /dev/null
+++ b/cli/cmd/root.go
@@ -0,0 +1,40 @@
+// Package cmd implements Cobra CLI commands for the Onyx CLI.
+package cmd
+
+import "github.com/spf13/cobra"
+
+// Version and Commit are set via ldflags at build time.
+var (
+	Version string
+	Commit  string
+)
+
+func fullVersion() string {
+	if Commit != "" && Commit != "none" && len(Commit) > 7 {
+		return Version + " (" + Commit[:7] + ")"
+	}
+	return Version
+}
+
+// Execute creates and runs the root command.
+func Execute() error {
+	rootCmd := &cobra.Command{
+		Use:     "onyx-cli",
+		Short:   "Terminal UI for chatting with Onyx",
+		Long:    "Onyx CLI — a terminal interface for chatting with your Onyx agent.",
+		Version: fullVersion(),
+	}
+
+	// Register subcommands
+	chatCmd := newChatCmd()
+	rootCmd.AddCommand(chatCmd)
+	rootCmd.AddCommand(newAskCmd())
+	rootCmd.AddCommand(newAgentsCmd())
+	rootCmd.AddCommand(newConfigureCmd())
+	rootCmd.AddCommand(newValidateConfigCmd())
+
+	// Default command is chat
+	rootCmd.RunE = chatCmd.RunE
+
+	return rootCmd.Execute()
+}
diff --git a/cli/cmd/validate.go b/cli/cmd/validate.go
new file mode 100644
index 00000000000..79aed768a5c
--- /dev/null
+++ b/cli/cmd/validate.go
@@ -0,0 +1,41 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/api"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/spf13/cobra"
+)
+
+func newValidateConfigCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "validate-config",
+		Short: "Validate configuration and test server connection",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			// Check config file
+			if !config.ConfigExists() {
+				return fmt.Errorf("config file not found at %s\n  Run 'onyx-cli configure' to set up", config.ConfigFilePath())
+			}
+
+			cfg := config.Load()
+
+			// Check API key
+			if !cfg.IsConfigured() {
+				return fmt.Errorf("API key is missing\n  Run 'onyx-cli configure' to set up")
+			}
+
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Config:  %s\n", config.ConfigFilePath())
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Server:  %s\n", cfg.ServerURL)
+
+			// Test connection
+			client := api.NewClient(cfg)
+			if err := client.TestConnection(cmd.Context()); err != nil {
+				return fmt.Errorf("connection failed: %w", err)
+			}
+
+			_, _ = fmt.Fprintln(cmd.OutOrStdout(), "Status:  connected and authenticated")
+			return nil
+		},
+	}
+}
diff --git a/cli/go.mod b/cli/go.mod
new file mode 100644
index 00000000000..408147be0c0
--- /dev/null
+++ b/cli/go.mod
@@ -0,0 +1,45 @@
+module github.com/onyx-dot-app/onyx/cli
+
+go 1.26.0
+
+require (
+	github.com/charmbracelet/bubbles v0.20.0
+	github.com/charmbracelet/bubbletea v1.3.4
+	github.com/charmbracelet/glamour v0.8.0
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/spf13/cobra v1.9.1
+	golang.org/x/term v0.22.0
+	golang.org/x/text v0.34.0
+)
+
+require (
+	github.com/alecthomas/chroma/v2 v2.14.0 // indirect
+	github.com/atotto/clipboard v0.1.4 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/aymerick/douceur v0.2.0 // indirect
+	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
+	github.com/charmbracelet/x/ansi v0.8.0 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/dlclark/regexp2 v1.11.0 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/gorilla/css v1.0.1 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/reflow v0.3.0 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/spf13/pflag v1.0.6 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	github.com/yuin/goldmark v1.7.4 // indirect
+	github.com/yuin/goldmark-emoji v1.0.3 // indirect
+	golang.org/x/net v0.27.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.30.0 // indirect
+)
diff --git a/cli/go.sum b/cli/go.sum
new file mode 100644
index 00000000000..4ba0b3b2c0c
--- /dev/null
+++ b/cli/go.sum
@@ -0,0 +1,94 @@
+github.com/alecthomas/assert/v2 v2.7.0 h1:QtqSACNS3tF7oasA8CU6A6sXZSBDqnm7RfpLl9bZqbE=
+github.com/alecthomas/assert/v2 v2.7.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
+github.com/alecthomas/chroma/v2 v2.14.0 h1:R3+wzpnUArGcQz7fCETQBzO5n9IMNi13iIs46aU4V9E=
+github.com/alecthomas/chroma/v2 v2.14.0/go.mod h1:QolEbTfmUHIMVpBqxeDnNBj2uoeI4EbYP4i6n68SG4I=
+github.com/alecthomas/repr v0.4.0 h1:GhI2A8MACjfegCPVq9f1FLvIBS+DrQ2KQBFZP1iFzXc=
+github.com/alecthomas/repr v0.4.0/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
+github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
+github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/aymanbagabas/go-udiff v0.2.0 h1:TK0fH4MteXUDspT88n8CKzvK0X9O2xu9yQjWpi6yML8=
+github.com/aymanbagabas/go-udiff v0.2.0/go.mod h1:RE4Ex0qsGkTAJoQdQQCA0uG+nAzJO/pI/QwceO5fgrA=
+github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
+github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
+github.com/charmbracelet/bubbles v0.20.0 h1:jSZu6qD8cRQ6k9OMfR1WlM+ruM8fkPWkHvQWD9LIutE=
+github.com/charmbracelet/bubbles v0.20.0/go.mod h1:39slydyswPy+uVOHZ5x/GjwVAFkCsV8IIVy+4MhzwwU=
+github.com/charmbracelet/bubbletea v1.3.4 h1:kCg7B+jSCFPLYRA52SDZjr51kG/fMUEoPoZrkaDHyoI=
+github.com/charmbracelet/bubbletea v1.3.4/go.mod h1:dtcUCyCGEX3g9tosuYiut3MXgY/Jsv9nKVdibKKRRXo=
+github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
+github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc/go.mod h1:X4/0JoqgTIPSFcRA/P6INZzIuyqdFY5rm8tb41s9okk=
+github.com/charmbracelet/glamour v0.8.0 h1:tPrjL3aRcQbn++7t18wOpgLyl8wrOHUEDS7IZ68QtZs=
+github.com/charmbracelet/glamour v0.8.0/go.mod h1:ViRgmKkf3u5S7uakt2czJ272WSg2ZenlYEZXT2x7Bjw=
+github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
+github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
+github.com/charmbracelet/x/ansi v0.8.0 h1:9GTq3xq9caJW8ZrBTe0LIe2fvfLR/bYXKTx2llXn7xE=
+github.com/charmbracelet/x/ansi v0.8.0/go.mod h1:wdYl/ONOLHLIVmQaxbIYEC/cRKOQyjTkowiI4blgS9Q=
+github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0GVL4jeHEwG5YOXDmi86oYw2yuYUGqz6a8sLwg0X8=
+github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
+github.com/charmbracelet/x/exp/golden v0.0.0-20240815200342-61de596daa2b h1:MnAMdlwSltxJyULnrYbkZpp4k58Co7Tah3ciKhSNo0Q=
+github.com/charmbracelet/x/exp/golden v0.0.0-20240815200342-61de596daa2b/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
+github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
+github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
+github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
+github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
+github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
+github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
+github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
+github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
+github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
+github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
+github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
+github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
+github.com/muesli/reflow v0.3.0 h1:IFsN6K9NfGtjeggFP+68I4chLZV2yIKsXJFNZ+eWh6s=
+github.com/muesli/reflow v0.3.0/go.mod h1:pbwTDkVPibjO2kyvBQRBxTWEEGDGq0FlB1BIKtnHY/8=
+github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
+github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
+github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
+github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
+github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.7.1/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
+github.com/yuin/goldmark v1.7.4 h1:BDXOHExt+A7gwPCJgPIIq7ENvceR7we7rOS9TNoLZeg=
+github.com/yuin/goldmark v1.7.4/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
+github.com/yuin/goldmark-emoji v1.0.3 h1:aLRkLHOuBR2czCY4R8olwMjID+tENfhyFDMCRhbIQY4=
+github.com/yuin/goldmark-emoji v1.0.3/go.mod h1:tTkZEbwu5wkPmgTcitqddVxY9osFZiavD+r4AzQrh1U=
+golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561 h1:MDc5xs78ZrZr3HMQugiXOAkSZtfTpbJLDr/lwfgO53E=
+golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561/go.mod h1:cyybsKvd6eL0RnXn6p/Grxp8F5bW7iYuBgsNCOHpMYE=
+golang.org/x/net v0.27.0 h1:5K3Njcw06/l2y9vpGCSdcxWOYHOUk3dVNGDXN+FvAys=
+golang.org/x/net v0.27.0/go.mod h1:dDi0PyhWNoiUOrAS8uXv/vnScO4wnHQO4mj9fn/RytE=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.22.0 h1:BbsgPEJULsl2fV/AT3v15Mjva5yXKQDyKf+TbDz7QJk=
+golang.org/x/term v0.22.0/go.mod h1:F3qCibpT5AMpCRfhfT53vVJwhLtIVHhB9XDjfFvnMI4=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/cli/internal/api/client.go b/cli/internal/api/client.go
new file mode 100644
index 00000000000..2150cc39072
--- /dev/null
+++ b/cli/internal/api/client.go
@@ -0,0 +1,284 @@
+// Package api provides the HTTP client for communicating with the Onyx server.
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+)
+
+// Client is the Onyx API client.
+type Client struct {
+	baseURL        string
+	apiKey         string
+	httpClient     *http.Client // default 30s timeout for quick requests
+	longHTTPClient *http.Client // 5min timeout for streaming/uploads
+}
+
+// NewClient creates a new API client from config.
+func NewClient(cfg config.OnyxCliConfig) *Client {
+	var transport *http.Transport
+	if t, ok := http.DefaultTransport.(*http.Transport); ok {
+		transport = t.Clone()
+	} else {
+		transport = &http.Transport{}
+	}
+	return &Client{
+		baseURL: strings.TrimRight(cfg.ServerURL, "/"),
+		apiKey:  cfg.APIKey,
+		httpClient: &http.Client{
+			Timeout:   30 * time.Second,
+			Transport: transport,
+		},
+		longHTTPClient: &http.Client{
+			Timeout:   5 * time.Minute,
+			Transport: transport,
+		},
+	}
+}
+
+// UpdateConfig replaces the client's config.
+func (c *Client) UpdateConfig(cfg config.OnyxCliConfig) {
+	c.baseURL = strings.TrimRight(cfg.ServerURL, "/")
+	c.apiKey = cfg.APIKey
+}
+
+func (c *Client) newRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error) {
+	req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, body)
+	if err != nil {
+		return nil, err
+	}
+	if c.apiKey != "" {
+		bearer := "Bearer " + c.apiKey
+		req.Header.Set("Authorization", bearer)
+		req.Header.Set("X-Onyx-Authorization", bearer)
+	}
+	return req, nil
+}
+
+func (c *Client) doJSON(ctx context.Context, method, path string, reqBody any, result any) error {
+	var body io.Reader
+	if reqBody != nil {
+		data, err := json.Marshal(reqBody)
+		if err != nil {
+			return err
+		}
+		body = bytes.NewReader(data)
+	}
+
+	req, err := c.newRequest(ctx, method, path, body)
+	if err != nil {
+		return err
+	}
+	if reqBody != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		respBody, _ := io.ReadAll(resp.Body)
+		return &OnyxAPIError{StatusCode: resp.StatusCode, Detail: string(respBody)}
+	}
+
+	if result != nil {
+		return json.NewDecoder(resp.Body).Decode(result)
+	}
+	return nil
+}
+
+// TestConnection checks if the server is reachable and credentials are valid.
+// Returns nil on success, or an error with a descriptive message on failure.
+func (c *Client) TestConnection(ctx context.Context) error {
+	// Step 1: Basic reachability
+	req, err := c.newRequest(ctx, "GET", "/", nil)
+	if err != nil {
+		return fmt.Errorf("cannot connect to %s: %w", c.baseURL, err)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("cannot connect to %s — is the server running?", c.baseURL)
+	}
+	_ = resp.Body.Close()
+
+	serverHeader := strings.ToLower(resp.Header.Get("Server"))
+
+	if resp.StatusCode == 403 {
+		if strings.Contains(serverHeader, "awselb") || strings.Contains(serverHeader, "amazons3") {
+			return fmt.Errorf("blocked by AWS load balancer (HTTP 403 on all requests).\n  Your IP address may not be in the ALB's security group or WAF allowlist")
+		}
+		return fmt.Errorf("HTTP 403 on base URL — the server is blocking all traffic.\n  This is likely a firewall, WAF, or IP allowlist restriction")
+	}
+
+	// Step 2: Authenticated check
+	req2, err := c.newRequest(ctx, "GET", "/api/me", nil)
+	if err != nil {
+		return fmt.Errorf("server reachable but API error: %w", err)
+	}
+
+	resp2, err := c.httpClient.Do(req2)
+	if err != nil {
+		return fmt.Errorf("server reachable but API error: %w", err)
+	}
+	defer func() { _ = resp2.Body.Close() }()
+
+	if resp2.StatusCode == 200 {
+		return nil
+	}
+
+	bodyBytes, _ := io.ReadAll(io.LimitReader(resp2.Body, 300))
+	body := string(bodyBytes)
+	isHTML := strings.HasPrefix(strings.TrimSpace(body), "<")
+	respServer := strings.ToLower(resp2.Header.Get("Server"))
+
+	if resp2.StatusCode == 401 || resp2.StatusCode == 403 {
+		if isHTML || strings.Contains(respServer, "awselb") {
+			return fmt.Errorf("HTTP %d from a reverse proxy (not the Onyx backend).\n  Check your deployment's ingress / proxy configuration", resp2.StatusCode)
+		}
+		if resp2.StatusCode == 401 {
+			return fmt.Errorf("invalid API key or token.\n  %s", body)
+		}
+		return fmt.Errorf("access denied — check that the API key is valid.\n  %s", body)
+	}
+
+	detail := fmt.Sprintf("HTTP %d", resp2.StatusCode)
+	if body != "" {
+		detail += fmt.Sprintf("\n  Response: %s", body)
+	}
+	return fmt.Errorf("%s", detail)
+}
+
+// ListAgents returns visible agents.
+func (c *Client) ListAgents(ctx context.Context) ([]models.AgentSummary, error) {
+	var raw []models.AgentSummary
+	if err := c.doJSON(ctx, "GET", "/api/persona", nil, &raw); err != nil {
+		return nil, err
+	}
+	var result []models.AgentSummary
+	for _, p := range raw {
+		if p.IsVisible {
+			result = append(result, p)
+		}
+	}
+	return result, nil
+}
+
+// ListChatSessions returns recent chat sessions.
+func (c *Client) ListChatSessions(ctx context.Context) ([]models.ChatSessionDetails, error) {
+	var resp struct {
+		Sessions []models.ChatSessionDetails `json:"sessions"`
+	}
+	if err := c.doJSON(ctx, "GET", "/api/chat/get-user-chat-sessions", nil, &resp); err != nil {
+		return nil, err
+	}
+	return resp.Sessions, nil
+}
+
+// GetChatSession returns full details for a session.
+func (c *Client) GetChatSession(ctx context.Context, sessionID string) (*models.ChatSessionDetailResponse, error) {
+	var resp models.ChatSessionDetailResponse
+	if err := c.doJSON(ctx, "GET", "/api/chat/get-chat-session/"+sessionID, nil, &resp); err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+// RenameChatSession renames a session. If name is empty, the backend auto-generates one.
+func (c *Client) RenameChatSession(ctx context.Context, sessionID string, name *string) (string, error) {
+	payload := map[string]any{
+		"chat_session_id": sessionID,
+	}
+	if name != nil {
+		payload["name"] = *name
+	}
+	var resp struct {
+		NewName string `json:"new_name"`
+	}
+	if err := c.doJSON(ctx, "PUT", "/api/chat/rename-chat-session", payload, &resp); err != nil {
+		return "", err
+	}
+	return resp.NewName, nil
+}
+
+// UploadFile uploads a file and returns a file descriptor.
+func (c *Client) UploadFile(ctx context.Context, filePath string) (*models.FileDescriptorPayload, error) {
+	file, err := os.Open(filePath)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = file.Close() }()
+
+	var buf bytes.Buffer
+	writer := multipart.NewWriter(&buf)
+
+	part, err := writer.CreateFormFile("files", filepath.Base(filePath))
+	if err != nil {
+		return nil, err
+	}
+	if _, err := io.Copy(part, file); err != nil {
+		return nil, err
+	}
+	_ = writer.Close()
+
+	req, err := c.newRequest(ctx, "POST", "/api/user/projects/file/upload", &buf)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+
+	resp, err := c.longHTTPClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, &OnyxAPIError{StatusCode: resp.StatusCode, Detail: string(body)}
+	}
+
+	var snapshot models.CategorizedFilesSnapshot
+	if err := json.NewDecoder(resp.Body).Decode(&snapshot); err != nil {
+		return nil, err
+	}
+
+	if len(snapshot.UserFiles) == 0 {
+		return nil, &OnyxAPIError{StatusCode: 400, Detail: "File upload returned no files"}
+	}
+
+	uf := snapshot.UserFiles[0]
+	return &models.FileDescriptorPayload{
+		ID:   uf.FileID,
+		Type: uf.ChatFileType,
+		Name: filepath.Base(filePath),
+	}, nil
+}
+
+// StopChatSession sends a stop signal for a streaming session (best-effort).
+func (c *Client) StopChatSession(ctx context.Context, sessionID string) {
+	req, err := c.newRequest(ctx, "POST", "/api/chat/stop-chat-session/"+sessionID, nil)
+	if err != nil {
+		return
+	}
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return
+	}
+	_ = resp.Body.Close()
+}
diff --git a/cli/internal/api/errors.go b/cli/internal/api/errors.go
new file mode 100644
index 00000000000..c5183e27bf9
--- /dev/null
+++ b/cli/internal/api/errors.go
@@ -0,0 +1,13 @@
+package api
+
+import "fmt"
+
+// OnyxAPIError is returned when an Onyx API call fails.
+type OnyxAPIError struct {
+	StatusCode int
+	Detail     string
+}
+
+func (e *OnyxAPIError) Error() string {
+	return fmt.Sprintf("HTTP %d: %s", e.StatusCode, e.Detail)
+}
diff --git a/cli/internal/api/stream.go b/cli/internal/api/stream.go
new file mode 100644
index 00000000000..e96ac859ec0
--- /dev/null
+++ b/cli/internal/api/stream.go
@@ -0,0 +1,136 @@
+package api
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+	"github.com/onyx-dot-app/onyx/cli/internal/parser"
+)
+
+// StreamEventMsg wraps a StreamEvent for Bubble Tea.
+type StreamEventMsg struct {
+	Event models.StreamEvent
+}
+
+// StreamDoneMsg signals the stream has ended.
+type StreamDoneMsg struct {
+	Err error
+}
+
+// SendMessageStream starts streaming a chat message response.
+// It reads NDJSON lines, parses them, and sends events on the returned channel.
+// The goroutine stops when ctx is cancelled or the stream ends.
+func (c *Client) SendMessageStream(
+	ctx context.Context,
+	message string,
+	chatSessionID *string,
+	agentID int,
+	parentMessageID *int,
+	fileDescriptors []models.FileDescriptorPayload,
+) <-chan models.StreamEvent {
+	ch := make(chan models.StreamEvent, 64)
+
+	go func() {
+		defer close(ch)
+
+		payload := models.SendMessagePayload{
+			Message:          message,
+			ParentMessageID:  parentMessageID,
+			FileDescriptors:  fileDescriptors,
+			Origin:           "api",
+			IncludeCitations: true,
+			Stream:           true,
+		}
+		if payload.FileDescriptors == nil {
+			payload.FileDescriptors = []models.FileDescriptorPayload{}
+		}
+
+		if chatSessionID != nil {
+			payload.ChatSessionID = chatSessionID
+		} else {
+			payload.ChatSessionInfo = &models.ChatSessionCreationInfo{AgentID: agentID}
+		}
+
+		body, err := json.Marshal(payload)
+		if err != nil {
+			ch <- models.ErrorEvent{Error: fmt.Sprintf("marshal error: %v", err), IsRetryable: false}
+			return
+		}
+
+		req, err := http.NewRequestWithContext(ctx, "POST", c.baseURL+"/api/chat/send-chat-message", nil)
+		if err != nil {
+			ch <- models.ErrorEvent{Error: fmt.Sprintf("request error: %v", err), IsRetryable: false}
+			return
+		}
+
+		req.Body = io.NopCloser(bytes.NewReader(body))
+		req.ContentLength = int64(len(body))
+		req.Header.Set("Content-Type", "application/json")
+		if c.apiKey != "" {
+			bearer := "Bearer " + c.apiKey
+			req.Header.Set("Authorization", bearer)
+			req.Header.Set("X-Onyx-Authorization", bearer)
+		}
+
+		resp, err := c.longHTTPClient.Do(req)
+		if err != nil {
+			if ctx.Err() != nil {
+				return // cancelled
+			}
+			ch <- models.ErrorEvent{Error: fmt.Sprintf("connection error: %v", err), IsRetryable: true}
+			return
+		}
+		defer func() { _ = resp.Body.Close() }()
+
+		if resp.StatusCode != 200 {
+			var respBody [4096]byte
+			n, _ := resp.Body.Read(respBody[:])
+			ch <- models.ErrorEvent{
+				Error:       fmt.Sprintf("HTTP %d: %s", resp.StatusCode, string(respBody[:n])),
+				IsRetryable: resp.StatusCode >= 500,
+			}
+			return
+		}
+
+		scanner := bufio.NewScanner(resp.Body)
+		scanner.Buffer(make([]byte, 0, 1024*1024), 1024*1024)
+		for scanner.Scan() {
+			if ctx.Err() != nil {
+				return
+			}
+			event := parser.ParseStreamLine(scanner.Text())
+			if event != nil {
+				select {
+				case ch <- event:
+				case <-ctx.Done():
+					return
+				}
+			}
+		}
+		if err := scanner.Err(); err != nil && ctx.Err() == nil {
+			ch <- models.ErrorEvent{Error: fmt.Sprintf("stream read error: %v", err), IsRetryable: true}
+		}
+	}()
+
+	return ch
+}
+
+// WaitForStreamEvent returns a tea.Cmd that reads one event from the channel.
+// On channel close, it returns StreamDoneMsg.
+func WaitForStreamEvent(ch <-chan models.StreamEvent) tea.Cmd {
+	return func() tea.Msg {
+		event, ok := <-ch
+		if !ok {
+			return StreamDoneMsg{}
+		}
+		return StreamEventMsg{Event: event}
+	}
+}
+
diff --git a/cli/internal/config/config.go b/cli/internal/config/config.go
new file mode 100644
index 00000000000..a7ea148d0c5
--- /dev/null
+++ b/cli/internal/config/config.go
@@ -0,0 +1,101 @@
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+)
+
+const (
+	EnvServerURL    = "ONYX_SERVER_URL"
+	EnvAPIKey = "ONYX_API_KEY"
+	EnvAgentID    = "ONYX_PERSONA_ID"
+)
+
+// OnyxCliConfig holds the CLI configuration.
+type OnyxCliConfig struct {
+	ServerURL        string `json:"server_url"`
+	APIKey           string `json:"api_key"`
+	DefaultAgentID int    `json:"default_persona_id"`
+}
+
+// DefaultConfig returns a config with default values.
+func DefaultConfig() OnyxCliConfig {
+	return OnyxCliConfig{
+		ServerURL:        "https://cloud.onyx.app",
+		APIKey:           "",
+		DefaultAgentID: 0,
+	}
+}
+
+// IsConfigured returns true if the config has an API key.
+func (c OnyxCliConfig) IsConfigured() bool {
+	return c.APIKey != ""
+}
+
+// configDir returns ~/.config/onyx-cli
+func configDir() string {
+	if xdg := os.Getenv("XDG_CONFIG_HOME"); xdg != "" {
+		return filepath.Join(xdg, "onyx-cli")
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return filepath.Join(".", ".config", "onyx-cli")
+	}
+	return filepath.Join(home, ".config", "onyx-cli")
+}
+
+// ConfigFilePath returns the full path to the config file.
+func ConfigFilePath() string {
+	return filepath.Join(configDir(), "config.json")
+}
+
+// ConfigExists checks if the config file exists on disk.
+func ConfigExists() bool {
+	_, err := os.Stat(ConfigFilePath())
+	return err == nil
+}
+
+// Load reads config from file and applies environment variable overrides.
+func Load() OnyxCliConfig {
+	cfg := DefaultConfig()
+
+	data, err := os.ReadFile(ConfigFilePath())
+	if err == nil {
+		if jsonErr := json.Unmarshal(data, &cfg); jsonErr != nil {
+			fmt.Fprintf(os.Stderr, "warning: config file %s is malformed: %v (using defaults)\n", ConfigFilePath(), jsonErr)
+		}
+	}
+
+	// Environment overrides
+	if v := os.Getenv(EnvServerURL); v != "" {
+		cfg.ServerURL = v
+	}
+	if v := os.Getenv(EnvAPIKey); v != "" {
+		cfg.APIKey = v
+	}
+	if v := os.Getenv(EnvAgentID); v != "" {
+		if id, err := strconv.Atoi(v); err == nil {
+			cfg.DefaultAgentID = id
+		}
+	}
+
+	return cfg
+}
+
+// Save writes the config to disk, creating parent directories if needed.
+func Save(cfg OnyxCliConfig) error {
+	dir := configDir()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return err
+	}
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(ConfigFilePath(), data, 0o600)
+}
diff --git a/cli/internal/config/config_test.go b/cli/internal/config/config_test.go
new file mode 100644
index 00000000000..8856974ebb6
--- /dev/null
+++ b/cli/internal/config/config_test.go
@@ -0,0 +1,215 @@
+package config
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func clearEnvVars(t *testing.T) {
+	t.Helper()
+	for _, key := range []string{EnvServerURL, EnvAPIKey, EnvAgentID} {
+		t.Setenv(key, "")
+		if err := os.Unsetenv(key); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func writeConfig(t *testing.T, dir string, data []byte) {
+	t.Helper()
+	onyxDir := filepath.Join(dir, "onyx-cli")
+	if err := os.MkdirAll(onyxDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(onyxDir, "config.json"), data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestDefaultConfig(t *testing.T) {
+	cfg := DefaultConfig()
+	if cfg.ServerURL != "https://cloud.onyx.app" {
+		t.Errorf("expected default server URL, got %s", cfg.ServerURL)
+	}
+	if cfg.APIKey != "" {
+		t.Errorf("expected empty API key, got %s", cfg.APIKey)
+	}
+	if cfg.DefaultAgentID != 0 {
+		t.Errorf("expected default agent ID 0, got %d", cfg.DefaultAgentID)
+	}
+}
+
+func TestIsConfigured(t *testing.T) {
+	cfg := DefaultConfig()
+	if cfg.IsConfigured() {
+		t.Error("empty config should not be configured")
+	}
+	cfg.APIKey = "some-key"
+	if !cfg.IsConfigured() {
+		t.Error("config with API key should be configured")
+	}
+}
+
+func TestLoadDefaults(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	cfg := Load()
+	if cfg.ServerURL != "https://cloud.onyx.app" {
+		t.Errorf("expected default URL, got %s", cfg.ServerURL)
+	}
+	if cfg.APIKey != "" {
+		t.Errorf("expected empty key, got %s", cfg.APIKey)
+	}
+}
+
+func TestLoadFromFile(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	data, _ := json.Marshal(map[string]interface{}{
+		"server_url":         "https://my-onyx.example.com",
+		"api_key":            "test-key-123",
+		"default_persona_id": 5,
+	})
+	writeConfig(t, dir, data)
+
+	cfg := Load()
+	if cfg.ServerURL != "https://my-onyx.example.com" {
+		t.Errorf("got %s", cfg.ServerURL)
+	}
+	if cfg.APIKey != "test-key-123" {
+		t.Errorf("got %s", cfg.APIKey)
+	}
+	if cfg.DefaultAgentID != 5 {
+		t.Errorf("got %d", cfg.DefaultAgentID)
+	}
+}
+
+func TestLoadCorruptFile(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	writeConfig(t, dir, []byte("not valid json {{{"))
+
+	cfg := Load()
+	if cfg.ServerURL != "https://cloud.onyx.app" {
+		t.Errorf("expected default URL on corrupt file, got %s", cfg.ServerURL)
+	}
+}
+
+func TestEnvOverrideServerURL(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv(EnvServerURL, "https://env-override.com")
+
+	cfg := Load()
+	if cfg.ServerURL != "https://env-override.com" {
+		t.Errorf("got %s", cfg.ServerURL)
+	}
+}
+
+func TestEnvOverrideAPIKey(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv(EnvAPIKey, "env-key")
+
+	cfg := Load()
+	if cfg.APIKey != "env-key" {
+		t.Errorf("got %s", cfg.APIKey)
+	}
+}
+
+func TestEnvOverrideAgentID(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv(EnvAgentID, "42")
+
+	cfg := Load()
+	if cfg.DefaultAgentID != 42 {
+		t.Errorf("got %d", cfg.DefaultAgentID)
+	}
+}
+
+func TestEnvOverrideInvalidAgentID(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv(EnvAgentID, "not-a-number")
+
+	cfg := Load()
+	if cfg.DefaultAgentID != 0 {
+		t.Errorf("got %d", cfg.DefaultAgentID)
+	}
+}
+
+func TestEnvOverridesFileValues(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	data, _ := json.Marshal(map[string]interface{}{
+		"server_url": "https://file-url.com",
+		"api_key":    "file-key",
+	})
+	writeConfig(t, dir, data)
+
+	t.Setenv(EnvServerURL, "https://env-url.com")
+
+	cfg := Load()
+	if cfg.ServerURL != "https://env-url.com" {
+		t.Errorf("env should override file, got %s", cfg.ServerURL)
+	}
+	if cfg.APIKey != "file-key" {
+		t.Errorf("file value should be kept, got %s", cfg.APIKey)
+	}
+}
+
+func TestSaveAndReload(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	cfg := OnyxCliConfig{
+		ServerURL:      "https://saved.example.com",
+		APIKey:         "saved-key",
+		DefaultAgentID: 10,
+	}
+	if err := Save(cfg); err != nil {
+		t.Fatal(err)
+	}
+
+	loaded := Load()
+	if loaded.ServerURL != "https://saved.example.com" {
+		t.Errorf("got %s", loaded.ServerURL)
+	}
+	if loaded.APIKey != "saved-key" {
+		t.Errorf("got %s", loaded.APIKey)
+	}
+	if loaded.DefaultAgentID != 10 {
+		t.Errorf("got %d", loaded.DefaultAgentID)
+	}
+}
+
+func TestSaveCreatesParentDirs(t *testing.T) {
+	clearEnvVars(t)
+	dir := t.TempDir()
+	nested := filepath.Join(dir, "deep", "nested")
+	t.Setenv("XDG_CONFIG_HOME", nested)
+
+	if err := Save(OnyxCliConfig{APIKey: "test"}); err != nil {
+		t.Fatal(err)
+	}
+
+	if !ConfigExists() {
+		t.Error("config file should exist after save")
+	}
+}
diff --git a/cli/internal/models/events.go b/cli/internal/models/events.go
new file mode 100644
index 00000000000..ac8c22bccdf
--- /dev/null
+++ b/cli/internal/models/events.go
@@ -0,0 +1,193 @@
+package models
+
+// StreamEvent is the interface for all parsed stream events.
+type StreamEvent interface {
+	EventType() string
+}
+
+// Event type constants matching the Python StreamEventType enum.
+const (
+	EventSessionCreated       = "session_created"
+	EventMessageIDInfo        = "message_id_info"
+	EventStop                 = "stop"
+	EventError                = "error"
+	EventMessageStart         = "message_start"
+	EventMessageDelta         = "message_delta"
+	EventSearchStart          = "search_tool_start"
+	EventSearchQueries        = "search_tool_queries_delta"
+	EventSearchDocuments      = "search_tool_documents_delta"
+	EventReasoningStart       = "reasoning_start"
+	EventReasoningDelta       = "reasoning_delta"
+	EventReasoningDone        = "reasoning_done"
+	EventCitationInfo         = "citation_info"
+	EventOpenURLStart         = "open_url_start"
+	EventImageGenStart        = "image_generation_start"
+	EventPythonToolStart      = "python_tool_start"
+	EventCustomToolStart      = "custom_tool_start"
+	EventFileReaderStart      = "file_reader_start"
+	EventDeepResearchPlan     = "deep_research_plan_start"
+	EventDeepResearchDelta    = "deep_research_plan_delta"
+	EventResearchAgentStart   = "research_agent_start"
+	EventIntermediateReport   = "intermediate_report_start"
+	EventIntermediateReportDt = "intermediate_report_delta"
+	EventUnknown              = "unknown"
+)
+
+// SessionCreatedEvent is emitted when a new chat session is created.
+type SessionCreatedEvent struct {
+	ChatSessionID string `json:"chat_session_id"`
+}
+
+func (e SessionCreatedEvent) EventType() string { return EventSessionCreated }
+
+// MessageIDEvent carries the user and agent message IDs.
+type MessageIDEvent struct {
+	UserMessageID          *int `json:"user_message_id,omitempty"`
+	ReservedAgentMessageID int  `json:"reserved_agent_message_id"`
+}
+
+func (e MessageIDEvent) EventType() string { return EventMessageIDInfo }
+
+// StopEvent signals the end of a stream.
+type StopEvent struct {
+	Placement  *Placement `json:"placement,omitempty"`
+	StopReason *string    `json:"stop_reason,omitempty"`
+}
+
+func (e StopEvent) EventType() string { return EventStop }
+
+// ErrorEvent signals an error.
+type ErrorEvent struct {
+	Placement   *Placement `json:"placement,omitempty"`
+	Error       string     `json:"error"`
+	StackTrace  *string    `json:"stack_trace,omitempty"`
+	IsRetryable bool       `json:"is_retryable"`
+}
+
+func (e ErrorEvent) EventType() string { return EventError }
+
+// MessageStartEvent signals the beginning of an agent message.
+type MessageStartEvent struct {
+	Placement *Placement  `json:"placement,omitempty"`
+	Documents []SearchDoc `json:"documents,omitempty"`
+}
+
+func (e MessageStartEvent) EventType() string { return EventMessageStart }
+
+// MessageDeltaEvent carries a token of agent content.
+type MessageDeltaEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+	Content   string     `json:"content"`
+}
+
+func (e MessageDeltaEvent) EventType() string { return EventMessageDelta }
+
+// SearchStartEvent signals the beginning of a search.
+type SearchStartEvent struct {
+	Placement        *Placement `json:"placement,omitempty"`
+	IsInternetSearch bool       `json:"is_internet_search"`
+}
+
+func (e SearchStartEvent) EventType() string { return EventSearchStart }
+
+// SearchQueriesEvent carries search queries.
+type SearchQueriesEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+	Queries   []string   `json:"queries"`
+}
+
+func (e SearchQueriesEvent) EventType() string { return EventSearchQueries }
+
+// SearchDocumentsEvent carries found documents.
+type SearchDocumentsEvent struct {
+	Placement *Placement  `json:"placement,omitempty"`
+	Documents []SearchDoc `json:"documents"`
+}
+
+func (e SearchDocumentsEvent) EventType() string { return EventSearchDocuments }
+
+// ReasoningStartEvent signals the beginning of a reasoning block.
+type ReasoningStartEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+}
+
+func (e ReasoningStartEvent) EventType() string { return EventReasoningStart }
+
+// ReasoningDeltaEvent carries reasoning text.
+type ReasoningDeltaEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+	Reasoning string     `json:"reasoning"`
+}
+
+func (e ReasoningDeltaEvent) EventType() string { return EventReasoningDelta }
+
+// ReasoningDoneEvent signals the end of reasoning.
+type ReasoningDoneEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+}
+
+func (e ReasoningDoneEvent) EventType() string { return EventReasoningDone }
+
+// CitationEvent carries citation info.
+type CitationEvent struct {
+	Placement      *Placement `json:"placement,omitempty"`
+	CitationNumber int        `json:"citation_number"`
+	DocumentID     string     `json:"document_id"`
+}
+
+func (e CitationEvent) EventType() string { return EventCitationInfo }
+
+// ToolStartEvent signals the start of a tool usage.
+type ToolStartEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+	Type      string     `json:"type"`
+	ToolName  string     `json:"tool_name"`
+}
+
+func (e ToolStartEvent) EventType() string { return e.Type }
+
+// DeepResearchPlanStartEvent signals the start of a deep research plan.
+type DeepResearchPlanStartEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+}
+
+func (e DeepResearchPlanStartEvent) EventType() string { return EventDeepResearchPlan }
+
+// DeepResearchPlanDeltaEvent carries deep research plan content.
+type DeepResearchPlanDeltaEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+	Content   string     `json:"content"`
+}
+
+func (e DeepResearchPlanDeltaEvent) EventType() string { return EventDeepResearchDelta }
+
+// ResearchAgentStartEvent signals a research sub-task.
+type ResearchAgentStartEvent struct {
+	Placement    *Placement `json:"placement,omitempty"`
+	ResearchTask string     `json:"research_task"`
+}
+
+func (e ResearchAgentStartEvent) EventType() string { return EventResearchAgentStart }
+
+// IntermediateReportStartEvent signals the start of an intermediate report.
+type IntermediateReportStartEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+}
+
+func (e IntermediateReportStartEvent) EventType() string { return EventIntermediateReport }
+
+// IntermediateReportDeltaEvent carries intermediate report content.
+type IntermediateReportDeltaEvent struct {
+	Placement *Placement `json:"placement,omitempty"`
+	Content   string     `json:"content"`
+}
+
+func (e IntermediateReportDeltaEvent) EventType() string { return EventIntermediateReportDt }
+
+// UnknownEvent is a catch-all for unrecognized stream data.
+type UnknownEvent struct {
+	Placement *Placement     `json:"placement,omitempty"`
+	RawData   map[string]any `json:"raw_data,omitempty"`
+}
+
+func (e UnknownEvent) EventType() string { return EventUnknown }
diff --git a/cli/internal/models/models.go b/cli/internal/models/models.go
new file mode 100644
index 00000000000..2212566df92
--- /dev/null
+++ b/cli/internal/models/models.go
@@ -0,0 +1,112 @@
+// Package models defines API request/response types for the Onyx CLI.
+package models
+
+import "time"
+
+// AgentSummary represents an agent from the API.
+type AgentSummary struct {
+	ID               int    `json:"id"`
+	Name             string `json:"name"`
+	Description      string `json:"description"`
+	IsDefaultPersona bool   `json:"is_default_persona"`
+	IsVisible        bool   `json:"is_visible"`
+}
+
+// ChatSessionSummary is a brief session listing.
+type ChatSessionSummary struct {
+	ID        string    `json:"id"`
+	Name      *string   `json:"name"`
+	AgentID *int      `json:"persona_id"`
+	Created   time.Time `json:"time_created"`
+}
+
+// ChatSessionDetails is a session with timestamps as strings.
+type ChatSessionDetails struct {
+	ID        string  `json:"id"`
+	Name      *string `json:"name"`
+	AgentID *int    `json:"persona_id"`
+	Created   string  `json:"time_created"`
+	Updated   string  `json:"time_updated"`
+}
+
+// ChatMessageDetail is a single message in a session.
+type ChatMessageDetail struct {
+	MessageID          int     `json:"message_id"`
+	ParentMessage      *int    `json:"parent_message"`
+	LatestChildMessage *int    `json:"latest_child_message"`
+	Message            string  `json:"message"`
+	MessageType        string  `json:"message_type"`
+	TimeSent           string  `json:"time_sent"`
+	Error              *string `json:"error"`
+}
+
+// ChatSessionDetailResponse is the full session detail from the API.
+type ChatSessionDetailResponse struct {
+	ChatSessionID string              `json:"chat_session_id"`
+	Description   *string             `json:"description"`
+	AgentID     *int                `json:"persona_id"`
+	AgentName   *string             `json:"persona_name"`
+	Messages      []ChatMessageDetail `json:"messages"`
+}
+
+// ChatFileType represents a file type for uploads.
+type ChatFileType string
+
+const (
+	ChatFileImage     ChatFileType = "image"
+	ChatFileDoc       ChatFileType = "document"
+	ChatFilePlainText ChatFileType = "plain_text"
+	ChatFileCSV       ChatFileType = "csv"
+)
+
+// FileDescriptorPayload is a file descriptor for send-message requests.
+type FileDescriptorPayload struct {
+	ID   string       `json:"id"`
+	Type ChatFileType `json:"type"`
+	Name string       `json:"name,omitempty"`
+}
+
+// UserFileSnapshot represents an uploaded file.
+type UserFileSnapshot struct {
+	ID           string       `json:"id"`
+	Name         string       `json:"name"`
+	FileID       string       `json:"file_id"`
+	ChatFileType ChatFileType `json:"chat_file_type"`
+}
+
+// CategorizedFilesSnapshot is the response from file upload.
+type CategorizedFilesSnapshot struct {
+	UserFiles []UserFileSnapshot `json:"user_files"`
+}
+
+// ChatSessionCreationInfo is included when creating a new session inline.
+type ChatSessionCreationInfo struct {
+	AgentID int `json:"persona_id"`
+}
+
+// SendMessagePayload is the request body for POST /api/chat/send-chat-message.
+type SendMessagePayload struct {
+	Message          string                   `json:"message"`
+	ChatSessionID    *string                  `json:"chat_session_id,omitempty"`
+	ChatSessionInfo  *ChatSessionCreationInfo `json:"chat_session_info,omitempty"`
+	ParentMessageID  *int                     `json:"parent_message_id"`
+	FileDescriptors  []FileDescriptorPayload `json:"file_descriptors"`
+	Origin           string                   `json:"origin"`
+	IncludeCitations bool                     `json:"include_citations"`
+	Stream           bool                     `json:"stream"`
+}
+
+// SearchDoc represents a document found during search.
+type SearchDoc struct {
+	DocumentID         string  `json:"document_id"`
+	SemanticIdentifier string  `json:"semantic_identifier"`
+	Link               *string `json:"link"`
+	SourceType         string  `json:"source_type"`
+}
+
+// Placement indicates where a stream event belongs in the conversation.
+type Placement struct {
+	TurnIndex    int  `json:"turn_index"`
+	TabIndex     int  `json:"tab_index"`
+	SubTurnIndex *int `json:"sub_turn_index"`
+}
diff --git a/cli/internal/onboarding/onboarding.go b/cli/internal/onboarding/onboarding.go
new file mode 100644
index 00000000000..b907a5d4285
--- /dev/null
+++ b/cli/internal/onboarding/onboarding.go
@@ -0,0 +1,170 @@
+// Package onboarding handles the first-run setup flow for Onyx CLI.
+package onboarding
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/api"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/tui"
+	"github.com/onyx-dot-app/onyx/cli/internal/util"
+	"golang.org/x/term"
+)
+
+// Aliases for shared styles.
+var (
+	boldStyle   = util.BoldStyle
+	dimStyle    = util.DimStyle
+	greenStyle  = util.GreenStyle
+	redStyle    = util.RedStyle
+	yellowStyle = util.YellowStyle
+)
+
+func getTermSize() (int, int) {
+	w, h, err := term.GetSize(int(os.Stdout.Fd()))
+	if err != nil {
+		return 80, 24
+	}
+	return w, h
+}
+
+// Run executes the interactive onboarding flow.
+// Returns the validated config, or nil if the user cancels.
+func Run(existing *config.OnyxCliConfig) *config.OnyxCliConfig {
+	cfg := config.DefaultConfig()
+	if existing != nil {
+		cfg = *existing
+	}
+
+	w, h := getTermSize()
+	fmt.Print(tui.RenderSplashOnboarding(w, h))
+
+	fmt.Println()
+	fmt.Println("  Welcome to " + boldStyle.Render("Onyx CLI") + ".")
+	fmt.Println()
+
+	reader := bufio.NewReader(os.Stdin)
+
+	// Server URL
+	serverURL := prompt(reader, "  Onyx server URL", cfg.ServerURL)
+	if serverURL == "" {
+		return nil
+	}
+	if !strings.HasPrefix(serverURL, "http://") && !strings.HasPrefix(serverURL, "https://") {
+		fmt.Println("  " + redStyle.Render("Server URL must start with http:// or https://"))
+		return nil
+	}
+
+	// API Key
+	fmt.Println()
+	fmt.Println("  " + dimStyle.Render("Need an API key? Press Enter to open the admin panel in your browser,"))
+	fmt.Println("  " + dimStyle.Render("or paste your key below."))
+	fmt.Println()
+
+	apiKey := promptSecret("  API key", cfg.APIKey)
+
+	if apiKey == "" {
+		// Open browser to API key page
+		url := strings.TrimRight(serverURL, "/") + "/app/settings/accounts-access"
+		fmt.Printf("\n  Opening %s ...\n", url)
+		util.OpenBrowser(url)
+		fmt.Println("  " + dimStyle.Render("Copy your API key, then paste it here."))
+		fmt.Println()
+
+		apiKey = promptSecret("  API key", "")
+		if apiKey == "" {
+			fmt.Println("\n  " + redStyle.Render("No API key provided. Exiting."))
+			return nil
+		}
+	}
+
+	// Test connection
+	cfg = config.OnyxCliConfig{
+		ServerURL:        serverURL,
+		APIKey:           apiKey,
+		DefaultAgentID: cfg.DefaultAgentID,
+	}
+
+	fmt.Println("\n  " + yellowStyle.Render("Testing connection..."))
+
+	client := api.NewClient(cfg)
+	if err := client.TestConnection(context.Background()); err != nil {
+		fmt.Println("  " + redStyle.Render("Connection failed.") + " " + err.Error())
+		fmt.Println()
+		fmt.Println("  " + dimStyle.Render("Run ") + boldStyle.Render("onyx-cli configure") + dimStyle.Render(" to try again."))
+		return nil
+	}
+
+	if err := config.Save(cfg); err != nil {
+		fmt.Println("  " + redStyle.Render("Could not save config: "+err.Error()))
+		return nil
+	}
+	fmt.Println("  " + greenStyle.Render("Connected and authenticated."))
+	fmt.Println()
+	printQuickStart()
+	return &cfg
+}
+
+func promptSecret(label, defaultVal string) string {
+	if defaultVal != "" {
+		fmt.Printf("%s %s: ", label, dimStyle.Render("[hidden]"))
+	} else {
+		fmt.Printf("%s: ", label)
+	}
+
+	password, err := term.ReadPassword(int(os.Stdin.Fd()))
+	fmt.Println() // ReadPassword doesn't echo a newline
+	if err != nil {
+		return defaultVal
+	}
+	line := strings.TrimSpace(string(password))
+	if line == "" {
+		return defaultVal
+	}
+	return line
+}
+
+func prompt(reader *bufio.Reader, label, defaultVal string) string {
+	if defaultVal != "" {
+		fmt.Printf("%s %s: ", label, dimStyle.Render("["+defaultVal+"]"))
+	} else {
+		fmt.Printf("%s: ", label)
+	}
+
+	line, err := reader.ReadString('\n')
+	// ReadString may return partial data along with an error (e.g. EOF without newline)
+	line = strings.TrimSpace(line)
+	if line != "" {
+		return line
+	}
+	if err != nil {
+		return defaultVal
+	}
+	return defaultVal
+}
+
+func printQuickStart() {
+	fmt.Println("  " + boldStyle.Render("Quick start"))
+	fmt.Println()
+	fmt.Println("  Just type to chat with your Onyx agent.")
+	fmt.Println()
+
+	rows := [][2]string{
+		{"/help", "Show all commands"},
+		{"/attach", "Attach a file"},
+		{"/agent", "Switch agent"},
+		{"/new", "New conversation"},
+		{"/sessions", "Browse previous chats"},
+		{"Esc", "Cancel generation"},
+		{"Ctrl+D", "Quit"},
+	}
+	for _, r := range rows {
+		fmt.Printf("    %-12s %s\n", boldStyle.Render(r[0]), dimStyle.Render(r[1]))
+	}
+	fmt.Println()
+}
+
diff --git a/cli/internal/parser/parser.go b/cli/internal/parser/parser.go
new file mode 100644
index 00000000000..c017ad77b36
--- /dev/null
+++ b/cli/internal/parser/parser.go
@@ -0,0 +1,248 @@
+// Package parser handles NDJSON stream parsing for Onyx chat responses.
+package parser
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+	"golang.org/x/text/cases"
+	"golang.org/x/text/language"
+)
+
+// ParseStreamLine parses a single NDJSON line into a typed StreamEvent.
+// Returns nil for empty lines or unparseable content.
+func ParseStreamLine(line string) models.StreamEvent {
+	line = strings.TrimSpace(line)
+	if line == "" {
+		return nil
+	}
+
+	var data map[string]any
+	if err := json.Unmarshal([]byte(line), &data); err != nil {
+		return models.ErrorEvent{Error: fmt.Sprintf("malformed stream data: %v", err), IsRetryable: false}
+	}
+
+	// Case 1: CreateChatSessionID
+	if _, ok := data["chat_session_id"]; ok {
+		if _, hasPlacement := data["placement"]; !hasPlacement {
+			sid, _ := data["chat_session_id"].(string)
+			return models.SessionCreatedEvent{ChatSessionID: sid}
+		}
+	}
+
+	// Case 2: MessageResponseIDInfo
+	if _, ok := data["reserved_assistant_message_id"]; ok {
+		reservedID := jsonInt(data["reserved_assistant_message_id"])
+		var userMsgID *int
+		if v, ok := data["user_message_id"]; ok && v != nil {
+			id := jsonInt(v)
+			userMsgID = &id
+		}
+		return models.MessageIDEvent{
+			UserMessageID:              userMsgID,
+			ReservedAgentMessageID: reservedID,
+		}
+	}
+
+	// Case 3: StreamingError (top-level error without placement)
+	if _, ok := data["error"]; ok {
+		if _, hasPlacement := data["placement"]; !hasPlacement {
+			errStr, _ := data["error"].(string)
+			var stackTrace *string
+			if st, ok := data["stack_trace"].(string); ok {
+				stackTrace = &st
+			}
+			isRetryable := true
+			if v, ok := data["is_retryable"].(bool); ok {
+				isRetryable = v
+			}
+			return models.ErrorEvent{
+				Error:       errStr,
+				StackTrace:  stackTrace,
+				IsRetryable: isRetryable,
+			}
+		}
+	}
+
+	// Case 4: Packet with placement + obj
+	if rawPlacement, ok := data["placement"]; ok {
+		if rawObj, ok := data["obj"]; ok {
+			placement := parsePlacement(rawPlacement)
+			obj, _ := rawObj.(map[string]any)
+			if obj == nil {
+				return models.UnknownEvent{Placement: placement, RawData: data}
+			}
+			return parsePacketObj(obj, placement)
+		}
+	}
+
+	// Fallback
+	return models.UnknownEvent{RawData: data}
+}
+
+func parsePlacement(raw interface{}) *models.Placement {
+	m, ok := raw.(map[string]any)
+	if !ok {
+		return nil
+	}
+	p := &models.Placement{
+		TurnIndex: jsonInt(m["turn_index"]),
+		TabIndex:  jsonInt(m["tab_index"]),
+	}
+	if v, ok := m["sub_turn_index"]; ok && v != nil {
+		st := jsonInt(v)
+		p.SubTurnIndex = &st
+	}
+	return p
+}
+
+func parsePacketObj(obj map[string]any, placement *models.Placement) models.StreamEvent {
+	objType, _ := obj["type"].(string)
+
+	switch objType {
+	case "stop":
+		var reason *string
+		if r, ok := obj["stop_reason"].(string); ok {
+			reason = &r
+		}
+		return models.StopEvent{Placement: placement, StopReason: reason}
+
+	case "error":
+		errMsg := "Unknown error"
+		if e, ok := obj["exception"]; ok {
+			errMsg = toString(e)
+		}
+		return models.ErrorEvent{Placement: placement, Error: errMsg, IsRetryable: true}
+
+	case "message_start":
+		var docs []models.SearchDoc
+		if rawDocs, ok := obj["final_documents"].([]any); ok {
+			docs = parseSearchDocs(rawDocs)
+		}
+		return models.MessageStartEvent{Placement: placement, Documents: docs}
+
+	case "message_delta":
+		content, _ := obj["content"].(string)
+		return models.MessageDeltaEvent{Placement: placement, Content: content}
+
+	case "search_tool_start":
+		isInternet, _ := obj["is_internet_search"].(bool)
+		return models.SearchStartEvent{Placement: placement, IsInternetSearch: isInternet}
+
+	case "search_tool_queries_delta":
+		var queries []string
+		if raw, ok := obj["queries"].([]any); ok {
+			for _, q := range raw {
+				if s, ok := q.(string); ok {
+					queries = append(queries, s)
+				}
+			}
+		}
+		return models.SearchQueriesEvent{Placement: placement, Queries: queries}
+
+	case "search_tool_documents_delta":
+		var docs []models.SearchDoc
+		if rawDocs, ok := obj["documents"].([]any); ok {
+			docs = parseSearchDocs(rawDocs)
+		}
+		return models.SearchDocumentsEvent{Placement: placement, Documents: docs}
+
+	case "reasoning_start":
+		return models.ReasoningStartEvent{Placement: placement}
+
+	case "reasoning_delta":
+		reasoning, _ := obj["reasoning"].(string)
+		return models.ReasoningDeltaEvent{Placement: placement, Reasoning: reasoning}
+
+	case "reasoning_done":
+		return models.ReasoningDoneEvent{Placement: placement}
+
+	case "citation_info":
+		return models.CitationEvent{
+			Placement:      placement,
+			CitationNumber: jsonInt(obj["citation_number"]),
+			DocumentID:     jsonString(obj["document_id"]),
+		}
+
+	case "open_url_start", "image_generation_start", "python_tool_start", "file_reader_start":
+		toolName := strings.ReplaceAll(strings.TrimSuffix(objType, "_start"), "_", " ")
+		toolName = cases.Title(language.English).String(toolName)
+		return models.ToolStartEvent{Placement: placement, Type: objType, ToolName: toolName}
+
+	case "custom_tool_start":
+		toolName := jsonString(obj["tool_name"])
+		if toolName == "" {
+			toolName = "Custom Tool"
+		}
+		return models.ToolStartEvent{Placement: placement, Type: models.EventCustomToolStart, ToolName: toolName}
+
+	case "deep_research_plan_start":
+		return models.DeepResearchPlanStartEvent{Placement: placement}
+
+	case "deep_research_plan_delta":
+		content, _ := obj["content"].(string)
+		return models.DeepResearchPlanDeltaEvent{Placement: placement, Content: content}
+
+	case "research_agent_start":
+		task, _ := obj["research_task"].(string)
+		return models.ResearchAgentStartEvent{Placement: placement, ResearchTask: task}
+
+	case "intermediate_report_start":
+		return models.IntermediateReportStartEvent{Placement: placement}
+
+	case "intermediate_report_delta":
+		content, _ := obj["content"].(string)
+		return models.IntermediateReportDeltaEvent{Placement: placement, Content: content}
+
+	default:
+		return models.UnknownEvent{Placement: placement, RawData: obj}
+	}
+}
+
+func parseSearchDocs(raw []any) []models.SearchDoc {
+	var docs []models.SearchDoc
+	for _, item := range raw {
+		m, ok := item.(map[string]any)
+		if !ok {
+			continue
+		}
+		doc := models.SearchDoc{
+			DocumentID:         jsonString(m["document_id"]),
+			SemanticIdentifier: jsonString(m["semantic_identifier"]),
+			SourceType:         jsonString(m["source_type"]),
+		}
+		if link, ok := m["link"].(string); ok {
+			doc.Link = &link
+		}
+		docs = append(docs, doc)
+	}
+	return docs
+}
+
+func jsonInt(v any) int {
+	switch n := v.(type) {
+	case float64:
+		return int(n)
+	case int:
+		return n
+	default:
+		return 0
+	}
+}
+
+func jsonString(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+func toString(v any) string {
+	switch s := v.(type) {
+	case string:
+		return s
+	default:
+		b, _ := json.Marshal(v)
+		return string(b)
+	}
+}
diff --git a/cli/internal/parser/parser_test.go b/cli/internal/parser/parser_test.go
new file mode 100644
index 00000000000..7ae6035bed5
--- /dev/null
+++ b/cli/internal/parser/parser_test.go
@@ -0,0 +1,419 @@
+package parser
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+)
+
+func TestEmptyLineReturnsNil(t *testing.T) {
+	for _, line := range []string{"", "  ", "\n"} {
+		if ParseStreamLine(line) != nil {
+			t.Errorf("expected nil for %q", line)
+		}
+	}
+}
+
+func TestInvalidJSONReturnsErrorEvent(t *testing.T) {
+	for _, line := range []string{"not json", "{broken"} {
+		event := ParseStreamLine(line)
+		if event == nil {
+			t.Errorf("expected ErrorEvent for %q, got nil", line)
+			continue
+		}
+		if _, ok := event.(models.ErrorEvent); !ok {
+			t.Errorf("expected ErrorEvent for %q, got %T", line, event)
+		}
+	}
+}
+
+func TestSessionCreated(t *testing.T) {
+	line := mustJSON(map[string]interface{}{
+		"chat_session_id": "550e8400-e29b-41d4-a716-446655440000",
+	})
+	event := ParseStreamLine(line)
+	e, ok := event.(models.SessionCreatedEvent)
+	if !ok {
+		t.Fatalf("expected SessionCreatedEvent, got %T", event)
+	}
+	if e.ChatSessionID != "550e8400-e29b-41d4-a716-446655440000" {
+		t.Errorf("got %s", e.ChatSessionID)
+	}
+}
+
+func TestMessageIDInfo(t *testing.T) {
+	line := mustJSON(map[string]interface{}{
+		"user_message_id":              1,
+		"reserved_assistant_message_id": 2,
+	})
+	event := ParseStreamLine(line)
+	e, ok := event.(models.MessageIDEvent)
+	if !ok {
+		t.Fatalf("expected MessageIDEvent, got %T", event)
+	}
+	if e.UserMessageID == nil || *e.UserMessageID != 1 {
+		t.Errorf("expected user_message_id=1")
+	}
+	if e.ReservedAgentMessageID != 2 {
+		t.Errorf("got %d", e.ReservedAgentMessageID)
+	}
+}
+
+func TestMessageIDInfoNullUserID(t *testing.T) {
+	line := mustJSON(map[string]interface{}{
+		"user_message_id":              nil,
+		"reserved_assistant_message_id": 5,
+	})
+	event := ParseStreamLine(line)
+	e, ok := event.(models.MessageIDEvent)
+	if !ok {
+		t.Fatalf("expected MessageIDEvent, got %T", event)
+	}
+	if e.UserMessageID != nil {
+		t.Error("expected nil user_message_id")
+	}
+	if e.ReservedAgentMessageID != 5 {
+		t.Errorf("got %d", e.ReservedAgentMessageID)
+	}
+}
+
+func TestTopLevelError(t *testing.T) {
+	line := mustJSON(map[string]interface{}{
+		"error":        "Rate limit exceeded",
+		"stack_trace":  "...",
+		"is_retryable": true,
+	})
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ErrorEvent)
+	if !ok {
+		t.Fatalf("expected ErrorEvent, got %T", event)
+	}
+	if e.Error != "Rate limit exceeded" {
+		t.Errorf("got %s", e.Error)
+	}
+	if e.StackTrace == nil || *e.StackTrace != "..." {
+		t.Error("expected stack_trace")
+	}
+	if !e.IsRetryable {
+		t.Error("expected retryable")
+	}
+}
+
+func TestTopLevelErrorMinimal(t *testing.T) {
+	line := mustJSON(map[string]interface{}{
+		"error": "Something broke",
+	})
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ErrorEvent)
+	if !ok {
+		t.Fatalf("expected ErrorEvent, got %T", event)
+	}
+	if e.Error != "Something broke" {
+		t.Errorf("got %s", e.Error)
+	}
+	if !e.IsRetryable {
+		t.Error("expected default retryable=true")
+	}
+}
+
+func makePacket(obj map[string]interface{}, turnIndex, tabIndex int) string {
+	return mustJSON(map[string]interface{}{
+		"placement": map[string]interface{}{"turn_index": turnIndex, "tab_index": tabIndex},
+		"obj":       obj,
+	})
+}
+
+func TestStopPacket(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "stop", "stop_reason": "completed"}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.StopEvent)
+	if !ok {
+		t.Fatalf("expected StopEvent, got %T", event)
+	}
+	if e.StopReason == nil || *e.StopReason != "completed" {
+		t.Error("expected stop_reason=completed")
+	}
+	if e.Placement == nil || e.Placement.TurnIndex != 0 {
+		t.Error("expected placement")
+	}
+}
+
+func TestStopPacketNoReason(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "stop"}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.StopEvent)
+	if !ok {
+		t.Fatalf("expected StopEvent, got %T", event)
+	}
+	if e.StopReason != nil {
+		t.Error("expected nil stop_reason")
+	}
+}
+
+func TestMessageStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "message_start"}, 0, 0)
+	event := ParseStreamLine(line)
+	_, ok := event.(models.MessageStartEvent)
+	if !ok {
+		t.Fatalf("expected MessageStartEvent, got %T", event)
+	}
+}
+
+func TestMessageStartWithDocuments(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "message_start",
+		"final_documents": []interface{}{
+			map[string]interface{}{"document_id": "doc1", "semantic_identifier": "Doc 1"},
+		},
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.MessageStartEvent)
+	if !ok {
+		t.Fatalf("expected MessageStartEvent, got %T", event)
+	}
+	if len(e.Documents) != 1 || e.Documents[0].DocumentID != "doc1" {
+		t.Error("expected 1 document with id doc1")
+	}
+}
+
+func TestMessageDelta(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "message_delta", "content": "Hello"}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.MessageDeltaEvent)
+	if !ok {
+		t.Fatalf("expected MessageDeltaEvent, got %T", event)
+	}
+	if e.Content != "Hello" {
+		t.Errorf("got %s", e.Content)
+	}
+}
+
+func TestMessageDeltaEmpty(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "message_delta", "content": ""}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.MessageDeltaEvent)
+	if !ok {
+		t.Fatalf("expected MessageDeltaEvent, got %T", event)
+	}
+	if e.Content != "" {
+		t.Errorf("expected empty, got %s", e.Content)
+	}
+}
+
+func TestSearchToolStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "search_tool_start", "is_internet_search": true,
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.SearchStartEvent)
+	if !ok {
+		t.Fatalf("expected SearchStartEvent, got %T", event)
+	}
+	if !e.IsInternetSearch {
+		t.Error("expected internet search")
+	}
+}
+
+func TestSearchToolQueries(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type":    "search_tool_queries_delta",
+		"queries": []interface{}{"query 1", "query 2"},
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.SearchQueriesEvent)
+	if !ok {
+		t.Fatalf("expected SearchQueriesEvent, got %T", event)
+	}
+	if len(e.Queries) != 2 || e.Queries[0] != "query 1" {
+		t.Error("unexpected queries")
+	}
+}
+
+func TestSearchToolDocuments(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "search_tool_documents_delta",
+		"documents": []interface{}{
+			map[string]interface{}{"document_id": "d1", "semantic_identifier": "First Doc", "link": "http://example.com"},
+			map[string]interface{}{"document_id": "d2", "semantic_identifier": "Second Doc"},
+		},
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.SearchDocumentsEvent)
+	if !ok {
+		t.Fatalf("expected SearchDocumentsEvent, got %T", event)
+	}
+	if len(e.Documents) != 2 {
+		t.Errorf("expected 2 docs, got %d", len(e.Documents))
+	}
+	if e.Documents[0].Link == nil || *e.Documents[0].Link != "http://example.com" {
+		t.Error("expected link on first doc")
+	}
+}
+
+func TestReasoningStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "reasoning_start"}, 0, 0)
+	event := ParseStreamLine(line)
+	if _, ok := event.(models.ReasoningStartEvent); !ok {
+		t.Fatalf("expected ReasoningStartEvent, got %T", event)
+	}
+}
+
+func TestReasoningDelta(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "reasoning_delta", "reasoning": "Let me think...",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ReasoningDeltaEvent)
+	if !ok {
+		t.Fatalf("expected ReasoningDeltaEvent, got %T", event)
+	}
+	if e.Reasoning != "Let me think..." {
+		t.Errorf("got %s", e.Reasoning)
+	}
+}
+
+func TestReasoningDone(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "reasoning_done"}, 0, 0)
+	event := ParseStreamLine(line)
+	if _, ok := event.(models.ReasoningDoneEvent); !ok {
+		t.Fatalf("expected ReasoningDoneEvent, got %T", event)
+	}
+}
+
+func TestCitationInfo(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "citation_info", "citation_number": 1, "document_id": "doc_abc",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.CitationEvent)
+	if !ok {
+		t.Fatalf("expected CitationEvent, got %T", event)
+	}
+	if e.CitationNumber != 1 || e.DocumentID != "doc_abc" {
+		t.Errorf("got %d, %s", e.CitationNumber, e.DocumentID)
+	}
+}
+
+func TestOpenURLStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "open_url_start"}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ToolStartEvent)
+	if !ok {
+		t.Fatalf("expected ToolStartEvent, got %T", event)
+	}
+	if e.Type != "open_url_start" {
+		t.Errorf("got type %s", e.Type)
+	}
+}
+
+func TestPythonToolStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "python_tool_start", "code": "print('hi')",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ToolStartEvent)
+	if !ok {
+		t.Fatalf("expected ToolStartEvent, got %T", event)
+	}
+	if e.ToolName != "Python Tool" {
+		t.Errorf("got %s", e.ToolName)
+	}
+}
+
+func TestCustomToolStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "custom_tool_start", "tool_name": "MyTool",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ToolStartEvent)
+	if !ok {
+		t.Fatalf("expected ToolStartEvent, got %T", event)
+	}
+	if e.ToolName != "MyTool" {
+		t.Errorf("got %s", e.ToolName)
+	}
+}
+
+func TestDeepResearchPlanDelta(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "deep_research_plan_delta", "content": "Step 1: ...",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.DeepResearchPlanDeltaEvent)
+	if !ok {
+		t.Fatalf("expected DeepResearchPlanDeltaEvent, got %T", event)
+	}
+	if e.Content != "Step 1: ..." {
+		t.Errorf("got %s", e.Content)
+	}
+}
+
+func TestResearchAgentStart(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "research_agent_start", "research_task": "Find info about X",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.ResearchAgentStartEvent)
+	if !ok {
+		t.Fatalf("expected ResearchAgentStartEvent, got %T", event)
+	}
+	if e.ResearchTask != "Find info about X" {
+		t.Errorf("got %s", e.ResearchTask)
+	}
+}
+
+func TestIntermediateReportDelta(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "intermediate_report_delta", "content": "Report text",
+	}, 0, 0)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.IntermediateReportDeltaEvent)
+	if !ok {
+		t.Fatalf("expected IntermediateReportDeltaEvent, got %T", event)
+	}
+	if e.Content != "Report text" {
+		t.Errorf("got %s", e.Content)
+	}
+}
+
+func TestUnknownPacketType(t *testing.T) {
+	line := makePacket(map[string]interface{}{"type": "section_end"}, 0, 0)
+	event := ParseStreamLine(line)
+	if _, ok := event.(models.UnknownEvent); !ok {
+		t.Fatalf("expected UnknownEvent, got %T", event)
+	}
+}
+
+func TestUnknownTopLevel(t *testing.T) {
+	line := mustJSON(map[string]interface{}{"some_unknown_field": "value"})
+	event := ParseStreamLine(line)
+	if _, ok := event.(models.UnknownEvent); !ok {
+		t.Fatalf("expected UnknownEvent, got %T", event)
+	}
+}
+
+func TestPlacementPreserved(t *testing.T) {
+	line := makePacket(map[string]interface{}{
+		"type": "message_delta", "content": "x",
+	}, 3, 1)
+	event := ParseStreamLine(line)
+	e, ok := event.(models.MessageDeltaEvent)
+	if !ok {
+		t.Fatalf("expected MessageDeltaEvent, got %T", event)
+	}
+	if e.Placement == nil {
+		t.Fatal("expected placement")
+	}
+	if e.Placement.TurnIndex != 3 || e.Placement.TabIndex != 1 {
+		t.Errorf("got turn=%d tab=%d", e.Placement.TurnIndex, e.Placement.TabIndex)
+	}
+}
+
+func mustJSON(v interface{}) string {
+	b, err := json.Marshal(v)
+	if err != nil {
+		panic(err)
+	}
+	return string(b)
+}
diff --git a/cli/internal/tui/app.go b/cli/internal/tui/app.go
new file mode 100644
index 00000000000..3a92e575dc8
--- /dev/null
+++ b/cli/internal/tui/app.go
@@ -0,0 +1,639 @@
+// Package tui implements the Bubble Tea TUI for Onyx CLI.
+package tui
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+	"github.com/onyx-dot-app/onyx/cli/internal/api"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+)
+
+// Model is the root Bubble Tea model.
+type Model struct {
+	config config.OnyxCliConfig
+	client *api.Client
+
+	viewport *viewport
+	input    inputModel
+	status   statusBar
+
+	width  int
+	height int
+
+	// Chat state
+	chatSessionID   *string
+	agentID       int
+	agentName     string
+	agents        []models.AgentSummary
+	parentMessageID *int
+	isStreaming      bool
+	streamCancel    context.CancelFunc
+	streamCh        <-chan models.StreamEvent
+	citations       map[int]string
+	attachedFiles   []models.FileDescriptorPayload
+	needsRename     bool
+	agentStarted bool
+
+	// Quit state
+	quitPending    bool
+	splashShown    bool
+	initInputReady bool // true once terminal init responses have passed
+}
+
+// NewModel creates a new TUI model.
+func NewModel(cfg config.OnyxCliConfig) Model {
+	client := api.NewClient(cfg)
+	parentID := -1
+
+	return Model{
+		config:          cfg,
+		client:          client,
+		viewport:        newViewport(80),
+		input:           newInputModel(),
+		status:          newStatusBar(),
+		agentID:       cfg.DefaultAgentID,
+		agentName:     "Default",
+		parentMessageID: &parentID,
+		citations:       make(map[int]string),
+	}
+}
+
+// Init initializes the model.
+func (m Model) Init() tea.Cmd {
+	return loadAgentsCmd(m.client)
+}
+
+// Update handles messages.
+func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	// Filter out terminal query responses (OSC 11 background color, cursor
+	// position reports, etc.) that arrive as key events with raw escape content.
+	// These arrive split across multiple key events, so we use a brief window
+	// after startup to swallow them all.
+	if keyMsg, ok := msg.(tea.KeyMsg); ok && !m.initInputReady {
+		// During init, drop ALL key events — they're terminal query responses
+		_ = keyMsg
+		return m, nil
+	}
+
+	switch msg := msg.(type) {
+	case tea.WindowSizeMsg:
+		m.width = msg.Width
+		m.height = msg.Height
+		m.viewport.setWidth(msg.Width)
+		m.status.setWidth(msg.Width)
+		m.input.textInput.Width = msg.Width - 4
+		if !m.splashShown {
+			m.splashShown = true
+			// bottomHeight = sep + input + sep + status = 4 (approx)
+			viewportHeight := msg.Height - 4
+			if viewportHeight < 1 {
+				viewportHeight = msg.Height
+			}
+			m.viewport.addSplash(viewportHeight)
+			// Delay input focus to let terminal query responses flush
+			return m, tea.Tick(100*time.Millisecond, func(time.Time) tea.Msg {
+				return inputReadyMsg{}
+			})
+		}
+		return m, nil
+
+	case tea.MouseMsg:
+		switch msg.Button {
+		case tea.MouseButtonWheelUp:
+			m.viewport.scrollUp(3, m.viewportHeight())
+			return m, nil
+		case tea.MouseButtonWheelDown:
+			m.viewport.scrollDown(3)
+			return m, nil
+		}
+
+	case tea.KeyMsg:
+		return m.handleKey(msg)
+
+	case submitMsg:
+		return m.handleSubmit(msg.text)
+
+	case fileDropMsg:
+		return m.handleFileDrop(msg.path)
+
+	case InitDoneMsg:
+		return m.handleInitDone(msg)
+
+	case api.StreamEventMsg:
+		return m.handleStreamEvent(msg)
+
+	case api.StreamDoneMsg:
+		return m.handleStreamDone(msg)
+
+	case AgentsLoadedMsg:
+		return m.handleAgentsLoaded(msg)
+
+	case SessionsLoadedMsg:
+		return m.handleSessionsLoaded(msg)
+
+	case SessionResumedMsg:
+		return m.handleSessionResumed(msg)
+
+	case FileUploadedMsg:
+		return m.handleFileUploaded(msg)
+
+	case inputReadyMsg:
+		m.initInputReady = true
+		m.input.textInput.Focus()
+		m.input.textInput.SetValue("")
+		return m, m.input.textInput.Cursor.BlinkCmd()
+
+	case resetQuitMsg:
+		m.quitPending = false
+		return m, nil
+	}
+
+	// Only forward messages to the text input after it's been focused
+	if m.splashShown {
+		var cmd tea.Cmd
+		m.input, cmd = m.input.update(msg)
+		return m, cmd
+	}
+	return m, nil
+}
+
+// View renders the UI.
+// viewportHeight returns the number of visible chat rows, accounting for the
+// dynamic bottom area (separator, menu, file badges, input, status bar).
+func (m Model) viewportHeight() int {
+	menuHeight := 0
+	if m.input.menuVisible {
+		menuHeight = len(m.input.menuItems)
+	}
+	fileHeight := 0
+	if len(m.input.attachedFiles) > 0 {
+		fileHeight = 1
+	}
+	h := m.height - (1 + menuHeight + fileHeight + 1 + 1 + 1)
+	if h < 1 {
+		return 1
+	}
+	return h
+}
+
+func (m Model) View() string {
+	if m.width == 0 || m.height == 0 {
+		return ""
+	}
+
+	separator := lipgloss.NewStyle().Foreground(separatorColor).Render(
+		strings.Repeat("─", m.width),
+	)
+
+	menuView := m.input.viewMenu(m.width)
+	viewportHeight := m.viewportHeight()
+
+	var parts []string
+	parts = append(parts, m.viewport.view(viewportHeight))
+	parts = append(parts, separator)
+	if menuView != "" {
+		parts = append(parts, menuView)
+	}
+	parts = append(parts, m.input.viewInput())
+	parts = append(parts, separator)
+	parts = append(parts, m.status.view())
+
+	return strings.Join(parts, "\n")
+}
+
+// handleKey processes keyboard input.
+func (m Model) handleKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
+	switch msg.Type {
+	case tea.KeyEscape:
+		// Cancel streaming or close menu
+		if m.input.menuVisible {
+			m.input.menuVisible = false
+			return m, nil
+		}
+		if m.isStreaming {
+			return m.cancelStream()
+		}
+		// Dismiss picker
+		if m.viewport.pickerActive {
+			m.viewport.pickerActive = false
+			return m, nil
+		}
+		return m, nil
+
+	case tea.KeyCtrlD:
+		// If streaming, cancel first; require a fresh Ctrl+D pair to quit
+		if m.isStreaming {
+			return m.cancelStream()
+		}
+		if m.quitPending {
+			return m, tea.Quit
+		}
+		m.quitPending = true
+		m.viewport.addInfo("Press Ctrl+D again to quit.")
+		return m, tea.Tick(2*time.Second, func(t time.Time) tea.Msg {
+			return resetQuitMsg{}
+		})
+
+	case tea.KeyCtrlO:
+		m.viewport.showSources = !m.viewport.showSources
+		return m, nil
+
+	case tea.KeyEnter:
+		if m.viewport.pickerActive {
+			if len(m.viewport.pickerItems) > 0 {
+				item := m.viewport.pickerItems[m.viewport.pickerIndex]
+				if item.id == "" {
+					return m, nil
+				}
+				m.viewport.pickerActive = false
+				switch m.viewport.pickerType {
+				case pickerSession:
+					return cmdResume(m, item.id)
+				case pickerAgent:
+					return cmdSelectAgent(m, item.id)
+				}
+			}
+			return m, nil
+		}
+
+	case tea.KeyUp:
+		if m.viewport.pickerActive {
+			if m.viewport.pickerIndex > 0 {
+				m.viewport.pickerIndex--
+			}
+			return m, nil
+		}
+
+	case tea.KeyDown:
+		if m.viewport.pickerActive {
+			if m.viewport.pickerIndex < len(m.viewport.pickerItems)-1 {
+				m.viewport.pickerIndex++
+			}
+			return m, nil
+		}
+
+	case tea.KeyPgUp:
+		m.viewport.scrollUp(m.viewportHeight()/2, m.viewportHeight())
+		return m, nil
+
+	case tea.KeyPgDown:
+		m.viewport.scrollDown(m.viewportHeight() / 2)
+		return m, nil
+
+	case tea.KeyShiftUp:
+		m.viewport.scrollUp(3, m.viewportHeight())
+		return m, nil
+
+	case tea.KeyShiftDown:
+		m.viewport.scrollDown(3)
+		return m, nil
+	}
+
+	// Pass to input
+	var cmd tea.Cmd
+	m.input, cmd = m.input.update(msg)
+	return m, cmd
+}
+
+func (m Model) handleSubmit(text string) (tea.Model, tea.Cmd) {
+	if strings.HasPrefix(text, "/") {
+		return handleSlashCommand(m, text)
+	}
+	return m.sendMessage(text)
+}
+
+func (m Model) handleFileDrop(path string) (tea.Model, tea.Cmd) {
+	return cmdAttach(m, path)
+}
+
+func (m Model) cancelStream() (Model, tea.Cmd) {
+	if m.streamCancel != nil {
+		m.streamCancel()
+	}
+	if m.chatSessionID != nil {
+		sid := *m.chatSessionID
+		go m.client.StopChatSession(context.Background(), sid)
+	}
+	m, cmd := m.finishStream(nil)
+	m.viewport.addInfo("Generation stopped.")
+	return m, cmd
+}
+
+func (m Model) sendMessage(message string) (Model, tea.Cmd) {
+	if m.isStreaming {
+		return m, nil
+	}
+
+	m.viewport.addUserMessage(message)
+	m.viewport.startAgent()
+
+	// Prepare file descriptors
+	fileDescs := make([]models.FileDescriptorPayload, len(m.attachedFiles))
+	copy(fileDescs, m.attachedFiles)
+	m.attachedFiles = nil
+	m.input.clearFiles()
+
+	m.isStreaming = true
+	m.agentStarted = false
+	m.citations = make(map[int]string)
+	m.status.setStreaming(true)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	m.streamCancel = cancel
+
+	ch := m.client.SendMessageStream(
+		ctx,
+		message,
+		m.chatSessionID,
+		m.agentID,
+		m.parentMessageID,
+		fileDescs,
+	)
+	m.streamCh = ch
+
+	return m, api.WaitForStreamEvent(ch)
+}
+
+func (m Model) handleStreamEvent(msg api.StreamEventMsg) (tea.Model, tea.Cmd) {
+	// Ignore stale events after cancellation
+	if !m.isStreaming {
+		return m, nil
+	}
+	switch e := msg.Event.(type) {
+	case models.SessionCreatedEvent:
+		m.chatSessionID = &e.ChatSessionID
+		m.needsRename = true
+		m.status.setSession(e.ChatSessionID)
+
+	case models.MessageIDEvent:
+		m.parentMessageID = &e.ReservedAgentMessageID
+
+	case models.MessageStartEvent:
+		m.agentStarted = true
+
+	case models.MessageDeltaEvent:
+		m.agentStarted = true
+		m.viewport.appendToken(e.Content)
+
+	case models.SearchStartEvent:
+		if e.IsInternetSearch {
+			m.viewport.addInfo("Web search…")
+		} else {
+			m.viewport.addInfo("Searching…")
+		}
+
+	case models.SearchQueriesEvent:
+		if len(e.Queries) > 0 {
+			queries := e.Queries
+			if len(queries) > 3 {
+				queries = queries[:3]
+			}
+			parts := make([]string, len(queries))
+			for i, q := range queries {
+				parts[i] = "\"" + q + "\""
+			}
+			m.viewport.addInfo("Searching: " + strings.Join(parts, ", "))
+		}
+
+	case models.SearchDocumentsEvent:
+		count := len(e.Documents)
+		suffix := "s"
+		if count == 1 {
+			suffix = ""
+		}
+		m.viewport.addInfo("Found " + strconv.Itoa(count) + " document" + suffix)
+
+	case models.ReasoningStartEvent:
+		m.viewport.addInfo("Thinking…")
+
+	case models.ReasoningDeltaEvent:
+		// We don't display reasoning text, just the indicator
+
+	case models.ReasoningDoneEvent:
+		// No-op
+
+	case models.CitationEvent:
+		m.citations[e.CitationNumber] = e.DocumentID
+
+	case models.ToolStartEvent:
+		m.viewport.addInfo("Using " + e.ToolName + "…")
+
+	case models.ResearchAgentStartEvent:
+		m.viewport.addInfo("Researching: " + e.ResearchTask)
+
+	case models.DeepResearchPlanDeltaEvent:
+		m.viewport.appendToken(e.Content)
+
+	case models.IntermediateReportDeltaEvent:
+		m.viewport.appendToken(e.Content)
+
+	case models.StopEvent:
+		return m.finishStream(nil)
+
+	case models.ErrorEvent:
+		m.viewport.addError(e.Error)
+		return m.finishStream(nil)
+	}
+
+	return m, api.WaitForStreamEvent(m.streamCh)
+}
+
+func (m Model) handleStreamDone(msg api.StreamDoneMsg) (tea.Model, tea.Cmd) {
+	// Ignore if already cancelled
+	if !m.isStreaming {
+		return m, nil
+	}
+	return m.finishStream(msg.Err)
+}
+
+func (m Model) finishStream(err error) (Model, tea.Cmd) {
+	m.viewport.finishAgent()
+	if m.agentStarted && len(m.citations) > 0 {
+		m.viewport.addCitations(m.citations)
+	}
+	m.isStreaming = false
+	m.agentStarted = false
+	m.status.setStreaming(false)
+	if m.streamCancel != nil {
+		m.streamCancel()
+	}
+	m.streamCancel = nil
+	m.streamCh = nil
+
+	// Auto-rename new sessions
+	if m.needsRename && m.chatSessionID != nil {
+		m.needsRename = false
+		sessionID := *m.chatSessionID
+		client := m.client
+		go func() {
+			_, _ = client.RenameChatSession(context.Background(), sessionID, nil)
+		}()
+	}
+
+	return m, nil
+}
+
+func (m Model) handleInitDone(msg InitDoneMsg) (tea.Model, tea.Cmd) {
+	if msg.Err != nil {
+		m.viewport.addWarning("Could not load agents. Using default.")
+	} else {
+		m.agents = msg.Agents
+		for _, p := range m.agents {
+			if p.ID == m.agentID {
+				m.agentName = p.Name
+				break
+			}
+		}
+	}
+	m.status.setServer(m.config.ServerURL)
+	m.status.setAgent(m.agentName)
+	return m, nil
+}
+
+func (m Model) handleAgentsLoaded(msg AgentsLoadedMsg) (tea.Model, tea.Cmd) {
+	if msg.Err != nil {
+		m.viewport.addError("Could not load agents: " + msg.Err.Error())
+		return m, nil
+	}
+	m.agents = msg.Agents
+	if len(m.agents) == 0 {
+		m.viewport.addInfo("No agents available.")
+		return m, nil
+	}
+
+	m.viewport.addInfo("Select an agent (Enter to select, Esc to cancel):")
+
+	var items []pickerItem
+	for _, p := range m.agents {
+		label := fmt.Sprintf("%d: %s", p.ID, p.Name)
+		if p.ID == m.agentID {
+			label += " *"
+		}
+		desc := p.Description
+		if len(desc) > 50 {
+			desc = desc[:50] + "..."
+		}
+		if desc != "" {
+			label += " - " + desc
+		}
+		items = append(items, pickerItem{
+			id:    strconv.Itoa(p.ID),
+			label: label,
+		})
+	}
+	m.viewport.showPicker(pickerAgent, items)
+	return m, nil
+}
+
+func (m Model) handleSessionsLoaded(msg SessionsLoadedMsg) (tea.Model, tea.Cmd) {
+	if msg.Err != nil {
+		m.viewport.addError("Could not load sessions: " + msg.Err.Error())
+		return m, nil
+	}
+	if len(msg.Sessions) == 0 {
+		m.viewport.addInfo("No previous sessions found.")
+		return m, nil
+	}
+
+	m.viewport.addInfo("Select a session to resume (Enter to select, Esc to cancel):")
+
+	const maxSessions = 15
+	var items []pickerItem
+	for i, s := range msg.Sessions {
+		if i >= maxSessions {
+			break
+		}
+		name := "Untitled"
+		if s.Name != nil && *s.Name != "" {
+			name = *s.Name
+		}
+		sid := s.ID
+		if len(sid) > 8 {
+			sid = sid[:8]
+		}
+		items = append(items, pickerItem{
+			id:    s.ID,
+			label: sid + "  " + name + "  (" + s.Created + ")",
+		})
+	}
+	if len(msg.Sessions) > maxSessions {
+		items = append(items, pickerItem{
+			id:    "",
+			label: fmt.Sprintf("… and %d more (use /resume <id> to open)", len(msg.Sessions)-maxSessions),
+		})
+	}
+	m.viewport.showPicker(pickerSession, items)
+	return m, nil
+}
+
+func (m Model) handleSessionResumed(msg SessionResumedMsg) (tea.Model, tea.Cmd) {
+	if msg.Err != nil {
+		m.viewport.addError("Could not load session: " + msg.Err.Error())
+		return m, nil
+	}
+
+	// Cancel any in-progress stream before replacing the session
+	if m.isStreaming {
+		m, _ = m.cancelStream()
+	}
+
+	detail := msg.Detail
+	m.chatSessionID = &detail.ChatSessionID
+	m.viewport.clearDisplay()
+	m.status.setSession(detail.ChatSessionID)
+
+	if detail.AgentName != nil {
+		m.agentName = *detail.AgentName
+		m.status.setAgent(*detail.AgentName)
+	}
+	if detail.AgentID != nil {
+		m.agentID = *detail.AgentID
+	}
+
+	// Replay messages
+	for _, chatMsg := range detail.Messages {
+		switch chatMsg.MessageType {
+		case "user":
+			m.viewport.addUserMessage(chatMsg.Message)
+		case "assistant":
+			m.viewport.startAgent()
+			m.viewport.appendToken(chatMsg.Message)
+			m.viewport.finishAgent()
+		}
+	}
+
+	// Set parent to last message
+	if len(detail.Messages) > 0 {
+		lastID := detail.Messages[len(detail.Messages)-1].MessageID
+		m.parentMessageID = &lastID
+	}
+
+	desc := "Untitled"
+	if detail.Description != nil && *detail.Description != "" {
+		desc = *detail.Description
+	}
+	m.viewport.addInfo("Resumed session: " + desc)
+	return m, nil
+}
+
+func (m Model) handleFileUploaded(msg FileUploadedMsg) (tea.Model, tea.Cmd) {
+	if msg.Err != nil {
+		m.viewport.addError("Upload failed: " + msg.Err.Error())
+		return m, nil
+	}
+	m.attachedFiles = append(m.attachedFiles, *msg.Descriptor)
+	m.input.addFile(msg.FileName)
+	m.viewport.addInfo("Attached: " + msg.FileName)
+	return m, nil
+}
+
+type inputReadyMsg struct{}
+type resetQuitMsg struct{}
+
diff --git a/cli/internal/tui/commands.go b/cli/internal/tui/commands.go
new file mode 100644
index 00000000000..f54a545e60a
--- /dev/null
+++ b/cli/internal/tui/commands.go
@@ -0,0 +1,200 @@
+package tui
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/onyx-dot-app/onyx/cli/internal/api"
+	"github.com/onyx-dot-app/onyx/cli/internal/config"
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+	"github.com/onyx-dot-app/onyx/cli/internal/util"
+)
+
+// handleSlashCommand dispatches slash commands and returns updated model + cmd.
+func handleSlashCommand(m Model, text string) (Model, tea.Cmd) {
+	parts := strings.SplitN(text, " ", 2)
+	command := strings.ToLower(parts[0])
+	arg := ""
+	if len(parts) > 1 {
+		arg = parts[1]
+	}
+
+	switch command {
+	case "/help":
+		m.viewport.addInfo(helpText)
+		return m, nil
+
+	case "/agent":
+		if arg != "" {
+			return cmdSelectAgent(m, arg)
+		}
+		return cmdShowAgents(m)
+
+	case "/attach":
+		return cmdAttach(m, arg)
+
+	case "/sessions", "/resume":
+		if strings.TrimSpace(arg) != "" {
+			return cmdResume(m, arg)
+		}
+		return cmdSessions(m)
+
+	case "/configure":
+		m.viewport.addInfo("Run 'onyx-cli configure' to change connection settings.")
+		return m, nil
+
+	case "/clear", "/new":
+		return cmdNew(m)
+
+	case "/connectors":
+		url := m.config.ServerURL + "/admin/indexing/status"
+		if util.OpenBrowser(url) {
+			m.viewport.addInfo("Opened " + url + " in browser")
+		} else {
+			m.viewport.addWarning("Failed to open browser. Visit: " + url)
+		}
+		return m, nil
+
+	case "/settings":
+		url := m.config.ServerURL + "/app/settings/general"
+		if util.OpenBrowser(url) {
+			m.viewport.addInfo("Opened " + url + " in browser")
+		} else {
+			m.viewport.addWarning("Failed to open browser. Visit: " + url)
+		}
+		return m, nil
+
+	case "/quit":
+		return m, tea.Quit
+
+	default:
+		m.viewport.addWarning(fmt.Sprintf("Unknown command: %s. Type /help for available commands.", command))
+		return m, nil
+	}
+}
+
+func cmdNew(m Model) (Model, tea.Cmd) {
+	if m.isStreaming {
+		m, _ = m.cancelStream()
+	}
+	m.chatSessionID = nil
+	parentID := -1
+	m.parentMessageID = &parentID
+	m.needsRename = false
+	m.citations = nil
+	m.viewport.clearAll()
+	// Re-add splash as a scrollable entry
+	viewportHeight := m.viewportHeight()
+	if viewportHeight < 1 {
+		viewportHeight = m.height
+	}
+	m.viewport.addSplash(viewportHeight)
+	m.status.setSession("")
+	return m, nil
+}
+
+func cmdShowAgents(m Model) (Model, tea.Cmd) {
+	m.viewport.addInfo("Loading agents...")
+	client := m.client
+	return m, func() tea.Msg {
+		agents, err := client.ListAgents(context.Background())
+		return AgentsLoadedMsg{Agents: agents, Err: err}
+	}
+}
+
+func cmdSelectAgent(m Model, idStr string) (Model, tea.Cmd) {
+	pid, err := strconv.Atoi(strings.TrimSpace(idStr))
+	if err != nil {
+		m.viewport.addWarning("Invalid agent ID. Use a number.")
+		return m, nil
+	}
+
+	var target *models.AgentSummary
+	for i := range m.agents {
+		if m.agents[i].ID == pid {
+			target = &m.agents[i]
+			break
+		}
+	}
+
+	if target == nil {
+		m.viewport.addWarning(fmt.Sprintf("Agent %d not found. Use /agent to see available agents.", pid))
+		return m, nil
+	}
+
+	m.agentID = target.ID
+	m.agentName = target.Name
+	m.status.setAgent(target.Name)
+	m.viewport.addInfo("Switched to agent: " + target.Name)
+
+	// Save preference
+	m.config.DefaultAgentID = target.ID
+	_ = config.Save(m.config)
+
+	return m, nil
+}
+
+func cmdAttach(m Model, pathStr string) (Model, tea.Cmd) {
+	if pathStr == "" {
+		m.viewport.addWarning("Usage: /attach <file_path>")
+		return m, nil
+	}
+
+	m.viewport.addInfo("Uploading " + pathStr + "...")
+
+	client := m.client
+	return m, func() tea.Msg {
+		fd, err := client.UploadFile(context.Background(), pathStr)
+		if err != nil {
+			return FileUploadedMsg{Err: err, FileName: pathStr}
+		}
+		return FileUploadedMsg{Descriptor: fd, FileName: pathStr}
+	}
+}
+
+func cmdSessions(m Model) (Model, tea.Cmd) {
+	m.viewport.addInfo("Loading sessions...")
+	client := m.client
+	return m, func() tea.Msg {
+		sessions, err := client.ListChatSessions(context.Background())
+		return SessionsLoadedMsg{Sessions: sessions, Err: err}
+	}
+}
+
+func cmdResume(m Model, sessionIDStr string) (Model, tea.Cmd) {
+	client := m.client
+	return m, func() tea.Msg {
+		targetID := sessionIDStr
+
+		// Short prefix — scan the list for a match
+		if len(sessionIDStr) < 36 {
+			sessions, err := client.ListChatSessions(context.Background())
+			if err != nil {
+				return SessionResumedMsg{Err: err}
+			}
+			for _, s := range sessions {
+				if strings.HasPrefix(s.ID, sessionIDStr) {
+					targetID = s.ID
+					break
+				}
+			}
+		}
+
+		detail, err := client.GetChatSession(context.Background(), targetID)
+		if err != nil {
+			return SessionResumedMsg{Err: fmt.Errorf("session not found: %s", sessionIDStr)}
+		}
+		return SessionResumedMsg{Detail: detail}
+	}
+}
+
+// loadAgentsCmd returns a tea.Cmd that loads agents from the API.
+func loadAgentsCmd(client *api.Client) tea.Cmd {
+	return func() tea.Msg {
+		agents, err := client.ListAgents(context.Background())
+		return InitDoneMsg{Agents: agents, Err: err}
+	}
+}
diff --git a/cli/internal/tui/help.go b/cli/internal/tui/help.go
new file mode 100644
index 00000000000..d13365d250a
--- /dev/null
+++ b/cli/internal/tui/help.go
@@ -0,0 +1,23 @@
+package tui
+
+const helpText = `Onyx CLI Commands
+
+  /help              Show this help message
+  /clear             Clear chat and start a new session
+  /agent             List and switch agents
+  /attach <path>     Attach a file to next message
+  /sessions          Browse and resume previous sessions
+  /configure         Re-run connection setup
+  /connectors        Open connectors page in browser
+  /settings          Open Onyx settings in browser
+  /quit              Exit Onyx CLI
+
+Keyboard Shortcuts
+
+  Enter              Send message
+  Escape             Cancel current generation
+  Ctrl+O             Toggle source citations
+  Ctrl+D             Quit (press twice)
+  Scroll Up/Down     Mouse wheel or Shift+Up/Down
+  Page Up/Down       Scroll half page
+`
diff --git a/cli/internal/tui/input.go b/cli/internal/tui/input.go
new file mode 100644
index 00000000000..4eb33ed416b
--- /dev/null
+++ b/cli/internal/tui/input.go
@@ -0,0 +1,241 @@
+package tui
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/charmbracelet/bubbles/textinput"
+	tea "github.com/charmbracelet/bubbletea"
+)
+
+// slashCommand defines a slash command with its description.
+type slashCommand struct {
+	command     string
+	description string
+}
+
+var slashCommands = []slashCommand{
+	{"/help", "Show help message"},
+	{"/clear", "Clear chat and start a new session"},
+	{"/agent", "List and switch agents"},
+	{"/attach", "Attach a file to next message"},
+	{"/sessions", "Browse and resume previous sessions"},
+	{"/configure", "Re-run connection setup"},
+	{"/connectors", "Open connectors in browser"},
+	{"/settings", "Open settings in browser"},
+	{"/quit", "Exit Onyx CLI"},
+}
+
+// Commands that take arguments (filled in with trailing space on Tab/Enter).
+var argCommands = map[string]bool{
+	"/attach": true,
+}
+
+// inputModel manages the text input and slash command menu.
+type inputModel struct {
+	textInput    textinput.Model
+	menuVisible  bool
+	menuItems    []slashCommand
+	menuIndex    int
+	attachedFiles []string
+}
+
+func newInputModel() inputModel {
+	ti := textinput.New()
+	ti.Prompt = "" // We render our own prompt in viewInput()
+	ti.Placeholder = "Send a message…"
+	ti.CharLimit = 10000
+	// Don't focus here — focus after first WindowSizeMsg to avoid
+	// capturing terminal init escape sequences as input.
+
+	return inputModel{
+		textInput: ti,
+	}
+}
+
+func (m inputModel) update(msg tea.Msg) (inputModel, tea.Cmd) {
+	switch msg := msg.(type) {
+	case tea.KeyMsg:
+		return m.handleKey(msg)
+	}
+
+	var cmd tea.Cmd
+	m.textInput, cmd = m.textInput.Update(msg)
+	m = m.updateMenu()
+	return m, cmd
+}
+
+func (m inputModel) handleKey(msg tea.KeyMsg) (inputModel, tea.Cmd) {
+	switch msg.Type {
+	case tea.KeyUp:
+		if m.menuVisible && m.menuIndex > 0 {
+			m.menuIndex--
+			return m, nil
+		}
+	case tea.KeyDown:
+		if m.menuVisible && m.menuIndex < len(m.menuItems)-1 {
+			m.menuIndex++
+			return m, nil
+		}
+	case tea.KeyTab:
+		if m.menuVisible && len(m.menuItems) > 0 {
+			cmd := m.menuItems[m.menuIndex].command
+			if argCommands[cmd] {
+				m.textInput.SetValue(cmd + " ")
+				m.textInput.SetCursor(len(cmd) + 1)
+			} else {
+				m.textInput.SetValue(cmd)
+				m.textInput.SetCursor(len(cmd))
+			}
+			m.menuVisible = false
+			return m, nil
+		}
+	case tea.KeyEnter:
+		if m.menuVisible && len(m.menuItems) > 0 {
+			cmd := m.menuItems[m.menuIndex].command
+			if argCommands[cmd] {
+				m.textInput.SetValue(cmd + " ")
+				m.textInput.SetCursor(len(cmd) + 1)
+				m.menuVisible = false
+				return m, nil
+			}
+			// Execute immediately
+			m.textInput.SetValue("")
+			m.menuVisible = false
+			return m, func() tea.Msg { return submitMsg{text: cmd} }
+		}
+
+		text := strings.TrimSpace(m.textInput.Value())
+		if text == "" {
+			return m, nil
+		}
+
+		// Check for file path (drag-and-drop)
+		if dropped := detectFileDrop(text); dropped != "" {
+			m.textInput.SetValue("")
+			return m, func() tea.Msg { return fileDropMsg{path: dropped} }
+		}
+
+		m.textInput.SetValue("")
+		m.menuVisible = false
+		return m, func() tea.Msg { return submitMsg{text: text} }
+
+	case tea.KeyEscape:
+		if m.menuVisible {
+			m.menuVisible = false
+			return m, nil
+		}
+	}
+
+	var cmd tea.Cmd
+	m.textInput, cmd = m.textInput.Update(msg)
+	m = m.updateMenu()
+	return m, cmd
+}
+
+func (m inputModel) updateMenu() inputModel {
+	val := strings.TrimSpace(m.textInput.Value())
+	if strings.HasPrefix(val, "/") && !strings.Contains(val, " ") {
+		needle := strings.ToLower(val)
+		var filtered []slashCommand
+		for _, sc := range slashCommands {
+			if strings.HasPrefix(sc.command, needle) {
+				filtered = append(filtered, sc)
+			}
+		}
+		if len(filtered) > 0 {
+			m.menuVisible = true
+			m.menuItems = filtered
+			if m.menuIndex >= len(filtered) {
+				m.menuIndex = 0
+			}
+		} else {
+			m.menuVisible = false
+		}
+	} else {
+		m.menuVisible = false
+	}
+	return m
+}
+
+func (m *inputModel) addFile(name string) {
+	m.attachedFiles = append(m.attachedFiles, name)
+}
+
+func (m *inputModel) clearFiles() {
+	m.attachedFiles = nil
+}
+
+// submitMsg is sent when user submits text.
+type submitMsg struct {
+	text string
+}
+
+// fileDropMsg is sent when a file path is detected.
+type fileDropMsg struct {
+	path string
+}
+
+// detectFileDrop checks if the text looks like a file path.
+func detectFileDrop(text string) string {
+	cleaned := strings.Trim(text, "'\"")
+	if cleaned == "" {
+		return ""
+	}
+	// Only treat as a file drop if it looks explicitly path-like
+	if !strings.HasPrefix(cleaned, "/") && !strings.HasPrefix(cleaned, "~") &&
+		!strings.HasPrefix(cleaned, "./") && !strings.HasPrefix(cleaned, "../") {
+		return ""
+	}
+	// Expand ~ to home dir
+	if strings.HasPrefix(cleaned, "~") {
+		home, err := os.UserHomeDir()
+		if err == nil {
+			cleaned = filepath.Join(home, cleaned[1:])
+		}
+	}
+	abs, err := filepath.Abs(cleaned)
+	if err != nil {
+		return ""
+	}
+	info, err := os.Stat(abs)
+	if err != nil {
+		return ""
+	}
+	if info.IsDir() {
+		return ""
+	}
+	return abs
+}
+
+// viewMenu renders the slash command menu.
+func (m inputModel) viewMenu(width int) string {
+	if !m.menuVisible || len(m.menuItems) == 0 {
+		return ""
+	}
+
+	var lines []string
+	for i, item := range m.menuItems {
+		prefix := "  "
+		if i == m.menuIndex {
+			prefix = "> "
+		}
+		line := prefix + item.command + "  " + statusMsgStyle.Render(item.description)
+		lines = append(lines, line)
+	}
+	return strings.Join(lines, "\n")
+}
+
+// viewInput renders the input line with prompt and optional file badges.
+func (m inputModel) viewInput() string {
+	var parts []string
+
+	if len(m.attachedFiles) > 0 {
+		badges := strings.Join(m.attachedFiles, "] [")
+		parts = append(parts, statusMsgStyle.Render("Attached: ["+badges+"]"))
+	}
+
+	parts = append(parts, inputPrompt+m.textInput.View())
+	return strings.Join(parts, "\n")
+}
diff --git a/cli/internal/tui/messages.go b/cli/internal/tui/messages.go
new file mode 100644
index 00000000000..edcdbea8e30
--- /dev/null
+++ b/cli/internal/tui/messages.go
@@ -0,0 +1,36 @@
+package tui
+
+import (
+	"github.com/onyx-dot-app/onyx/cli/internal/models"
+)
+
+// InitDoneMsg signals that async initialization is complete.
+type InitDoneMsg struct {
+	Agents []models.AgentSummary
+	Err      error
+}
+
+// SessionsLoadedMsg carries loaded chat sessions.
+type SessionsLoadedMsg struct {
+	Sessions []models.ChatSessionDetails
+	Err      error
+}
+
+// SessionResumedMsg carries a loaded session detail.
+type SessionResumedMsg struct {
+	Detail *models.ChatSessionDetailResponse
+	Err    error
+}
+
+// FileUploadedMsg carries an uploaded file descriptor.
+type FileUploadedMsg struct {
+	Descriptor *models.FileDescriptorPayload
+	FileName   string
+	Err        error
+}
+
+// AgentsLoadedMsg carries freshly fetched agents from the API.
+type AgentsLoadedMsg struct {
+	Agents []models.AgentSummary
+	Err    error
+}
diff --git a/cli/internal/tui/splash.go b/cli/internal/tui/splash.go
new file mode 100644
index 00000000000..3fd05833d03
--- /dev/null
+++ b/cli/internal/tui/splash.go
@@ -0,0 +1,79 @@
+package tui
+
+import (
+	"strings"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+const onyxLogo = `   ██████╗ ███╗   ██╗██╗   ██╗██╗  ██╗
+  ██╔═══██╗████╗  ██║╚██╗ ██╔╝╚██╗██╔╝
+  ██║   ██║██╔██╗ ██║ ╚████╔╝  ╚███╔╝
+  ██║   ██║██║╚██╗██║  ╚██╔╝   ██╔██╗
+  ╚██████╔╝██║ ╚████║   ██║   ██╔╝ ██╗
+   ╚═════╝ ╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝`
+
+const tagline = "Your terminal interface for Onyx"
+const splashHint = "Type a message to begin  ·  /help for commands"
+
+// renderSplash renders the splash screen centered for the given dimensions.
+func renderSplash(width, height int) string {
+	// Render the logo as a single block (don't center individual lines)
+	logo := splashStyle.Render(onyxLogo)
+
+	// Center tagline and hint relative to the logo block width
+	logoWidth := lipgloss.Width(logo)
+	tag := lipgloss.NewStyle().Width(logoWidth).Align(lipgloss.Center).Render(
+		taglineStyle.Render(tagline),
+	)
+	hint := lipgloss.NewStyle().Width(logoWidth).Align(lipgloss.Center).Render(
+		hintStyle.Render(splashHint),
+	)
+
+	block := lipgloss.JoinVertical(lipgloss.Left, logo, "", tag, hint)
+
+	return lipgloss.Place(width, height, lipgloss.Center, lipgloss.Center, block)
+}
+
+// RenderSplashOnboarding renders splash for the terminal onboarding screen.
+func RenderSplashOnboarding(width, height int) string {
+	// Render the logo as a styled block, then center it as a unit
+	styledLogo := splashStyle.Render(onyxLogo)
+	logoWidth := lipgloss.Width(styledLogo)
+	logoLines := strings.Split(styledLogo, "\n")
+
+	logoHeight := len(logoLines)
+	contentHeight := logoHeight + 2 // logo + blank + tagline
+	topPad := (height - contentHeight) / 2
+	if topPad < 1 {
+		topPad = 1
+	}
+
+	// Center the entire logo block horizontally
+	blockPad := (width - logoWidth) / 2
+	if blockPad < 0 {
+		blockPad = 0
+	}
+
+	var b strings.Builder
+	for i := 0; i < topPad; i++ {
+		b.WriteByte('\n')
+	}
+
+	for _, line := range logoLines {
+		b.WriteString(strings.Repeat(" ", blockPad))
+		b.WriteString(line)
+		b.WriteByte('\n')
+	}
+
+	b.WriteByte('\n')
+	tagPad := (width - len(tagline)) / 2
+	if tagPad < 0 {
+		tagPad = 0
+	}
+	b.WriteString(strings.Repeat(" ", tagPad))
+	b.WriteString(taglineStyle.Render(tagline))
+	b.WriteByte('\n')
+
+	return b.String()
+}
diff --git a/cli/internal/tui/statusbar.go b/cli/internal/tui/statusbar.go
new file mode 100644
index 00000000000..08164ed4f81
--- /dev/null
+++ b/cli/internal/tui/statusbar.go
@@ -0,0 +1,60 @@
+package tui
+
+import (
+	"strings"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+// statusBar manages the footer status display.
+type statusBar struct {
+	agentName string
+	serverURL   string
+	sessionID   string
+	streaming   bool
+	width       int
+}
+
+func newStatusBar() statusBar {
+	return statusBar{
+		agentName: "Default",
+	}
+}
+
+func (s *statusBar) setAgent(name string) { s.agentName = name }
+func (s *statusBar) setServer(url string)    { s.serverURL = url }
+func (s *statusBar) setSession(id string) {
+	if len(id) > 8 {
+		id = id[:8]
+	}
+	s.sessionID = id
+}
+func (s *statusBar) setStreaming(v bool) { s.streaming = v }
+func (s *statusBar) setWidth(w int)     { s.width = w }
+
+func (s statusBar) view() string {
+	var leftParts []string
+	if s.serverURL != "" {
+		leftParts = append(leftParts, s.serverURL)
+	}
+	name := s.agentName
+	if name == "" {
+		name = "Default"
+	}
+	leftParts = append(leftParts, name)
+	left := statusBarStyle.Render(strings.Join(leftParts, " · "))
+
+	right := "Ctrl+D to quit"
+	if s.streaming {
+		right = "Esc to cancel"
+	}
+	rightRendered := statusBarStyle.Render(right)
+
+	// Fill space between left and right
+	gap := s.width - lipgloss.Width(left) - lipgloss.Width(rightRendered)
+	if gap < 1 {
+		gap = 1
+	}
+
+	return left + strings.Repeat(" ", gap) + rightRendered
+}
diff --git a/cli/internal/tui/styles.go b/cli/internal/tui/styles.go
new file mode 100644
index 00000000000..2e48db06fdd
--- /dev/null
+++ b/cli/internal/tui/styles.go
@@ -0,0 +1,29 @@
+package tui
+
+import "github.com/charmbracelet/lipgloss"
+
+var (
+	// Colors
+	accentColor    = lipgloss.Color("#6c8ebf")
+	dimColor       = lipgloss.Color("#555577")
+	errorColor     = lipgloss.Color("#ff5555")
+	splashColor    = lipgloss.Color("#7C6AEF")
+	separatorColor = lipgloss.Color("#333355")
+	citationColor  = lipgloss.Color("#666688")
+
+	// Styles
+	userPrefixStyle = lipgloss.NewStyle().Foreground(dimColor)
+	agentDot    = lipgloss.NewStyle().Foreground(accentColor).Bold(true).Render("◉")
+	infoStyle       = lipgloss.NewStyle().Foreground(lipgloss.Color("#b0b0cc"))
+	dimInfoStyle    = lipgloss.NewStyle().Foreground(dimColor)
+	statusMsgStyle  = dimInfoStyle // used for slash menu descriptions, file badges
+	errorStyle      = lipgloss.NewStyle().Foreground(errorColor).Bold(true)
+	warnStyle       = lipgloss.NewStyle().Foreground(lipgloss.Color("#ffcc00"))
+	citationStyle   = lipgloss.NewStyle().Foreground(citationColor)
+	statusBarStyle  = lipgloss.NewStyle().Foreground(dimColor)
+	inputPrompt     = lipgloss.NewStyle().Foreground(accentColor).Render("❯ ")
+
+	splashStyle = lipgloss.NewStyle().Foreground(splashColor).Bold(true)
+	taglineStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("#A0A0A0"))
+	hintStyle    = lipgloss.NewStyle().Foreground(dimColor)
+)
diff --git a/cli/internal/tui/viewport.go b/cli/internal/tui/viewport.go
new file mode 100644
index 00000000000..a967cb0a5ff
--- /dev/null
+++ b/cli/internal/tui/viewport.go
@@ -0,0 +1,448 @@
+package tui
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/charmbracelet/glamour"
+	"github.com/charmbracelet/glamour/styles"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+// entryKind is the type of chat entry.
+type entryKind int
+
+const (
+	entryUser entryKind = iota
+	entryAgent
+	entryInfo
+	entryError
+	entryCitation
+)
+
+// chatEntry is a single rendered entry in the chat history.
+type chatEntry struct {
+	kind      entryKind
+	content   string   // raw content (for agent: the markdown source)
+	rendered  string   // pre-rendered output
+	citations []string // citation lines (for citation entries)
+}
+
+// pickerKind distinguishes what the picker is selecting.
+type pickerKind int
+
+const (
+	pickerSession pickerKind = iota
+	pickerAgent
+)
+
+// pickerItem is a selectable item in the picker.
+type pickerItem struct {
+	id    string
+	label string
+}
+
+// viewport manages the chat display.
+type viewport struct {
+	entries      []chatEntry
+	width        int
+	streaming    bool
+	streamBuf    string
+	showSources  bool
+	renderer     *glamour.TermRenderer
+	pickerItems  []pickerItem
+	pickerActive bool
+	pickerIndex  int
+	pickerType   pickerKind
+	scrollOffset int // lines scrolled up from bottom (0 = pinned to bottom)
+}
+
+// newMarkdownRenderer creates a Glamour renderer with zero left margin.
+func newMarkdownRenderer(width int) *glamour.TermRenderer {
+	style := styles.DarkStyleConfig
+	zero := uint(0)
+	style.Document.Margin = &zero
+	r, _ := glamour.NewTermRenderer(
+		glamour.WithStyles(style),
+		glamour.WithWordWrap(width-4),
+	)
+	return r
+}
+
+func newViewport(width int) *viewport {
+	return &viewport{
+		width:    width,
+		renderer: newMarkdownRenderer(width),
+	}
+}
+
+func (v *viewport) addSplash(height int) {
+	splash := renderSplash(v.width, height)
+	v.entries = append(v.entries, chatEntry{
+		kind:     entryInfo,
+		rendered: splash,
+	})
+}
+
+func (v *viewport) setWidth(w int) {
+	v.width = w
+	v.renderer = newMarkdownRenderer(w)
+	for i := range v.entries {
+		if v.entries[i].kind == entryAgent && v.entries[i].content != "" {
+			v.entries[i].rendered = v.renderAgentContent(v.entries[i].content)
+		}
+	}
+}
+
+func (v *viewport) addUserMessage(msg string) {
+	rendered := "\n" + userPrefixStyle.Render("❯ ") + msg
+	v.entries = append(v.entries, chatEntry{
+		kind:     entryUser,
+		content:  msg,
+		rendered: rendered,
+	})
+}
+
+func (v *viewport) startAgent() {
+	v.streaming = true
+	v.streamBuf = ""
+	// Add a blank-line spacer entry before the agent message
+	v.entries = append(v.entries, chatEntry{kind: entryInfo, rendered: ""})
+}
+
+func (v *viewport) appendToken(token string) {
+	v.streamBuf += token
+}
+
+func (v *viewport) finishAgent() {
+	if v.streamBuf == "" {
+		v.streaming = false
+		// Remove the blank spacer entry added by startAgent()
+		if len(v.entries) > 0 && v.entries[len(v.entries)-1].kind == entryInfo && v.entries[len(v.entries)-1].rendered == "" {
+			v.entries = v.entries[:len(v.entries)-1]
+		}
+		return
+	}
+
+	rendered := v.renderAgentContent(v.streamBuf)
+
+	v.entries = append(v.entries, chatEntry{
+		kind:     entryAgent,
+		content:  v.streamBuf,
+		rendered: rendered,
+	})
+	v.streaming = false
+	v.streamBuf = ""
+}
+
+func (v *viewport) renderAgentContent(content string) string {
+	rendered := v.renderMarkdown(content)
+	rendered = strings.TrimLeft(rendered, "\n")
+	rendered = strings.TrimRight(rendered, "\n")
+	lines := strings.Split(rendered, "\n")
+	if len(lines) > 0 {
+		lines[0] = agentDot + " " + lines[0]
+		for i := 1; i < len(lines); i++ {
+			lines[i] = "  " + lines[i]
+		}
+	}
+	return strings.Join(lines, "\n")
+}
+
+func (v *viewport) renderMarkdown(md string) string {
+	if v.renderer == nil {
+		return md
+	}
+	out, err := v.renderer.Render(md)
+	if err != nil {
+		return md
+	}
+	return out
+}
+
+func (v *viewport) addInfo(msg string) {
+	rendered := infoStyle.Render("● " + msg)
+	v.entries = append(v.entries, chatEntry{
+		kind:     entryInfo,
+		content:  msg,
+		rendered: rendered,
+	})
+}
+
+func (v *viewport) addWarning(msg string) {
+	rendered := warnStyle.Render("● " + msg)
+	v.entries = append(v.entries, chatEntry{
+		kind:     entryError,
+		content:  msg,
+		rendered: rendered,
+	})
+}
+
+func (v *viewport) addError(msg string) {
+	rendered := errorStyle.Render("● Error: ") + msg
+	v.entries = append(v.entries, chatEntry{
+		kind:     entryError,
+		content:  msg,
+		rendered: rendered,
+	})
+}
+
+func (v *viewport) addCitations(citations map[int]string) {
+	if len(citations) == 0 {
+		return
+	}
+	keys := make([]int, 0, len(citations))
+	for k := range citations {
+		keys = append(keys, k)
+	}
+	sort.Ints(keys)
+	var parts []string
+	for _, num := range keys {
+		parts = append(parts, fmt.Sprintf("[%d] %s", num, citations[num]))
+	}
+	text := fmt.Sprintf("Sources (%d): %s", len(citations), strings.Join(parts, "  "))
+	var citLines []string
+	citLines = append(citLines, text)
+
+	v.entries = append(v.entries, chatEntry{
+		kind:      entryCitation,
+		content:   text,
+		rendered:  citationStyle.Render("● "+text),
+		citations: citLines,
+	})
+}
+
+func (v *viewport) showPicker(kind pickerKind, items []pickerItem) {
+	v.pickerItems = items
+	v.pickerType = kind
+	v.pickerActive = true
+	v.pickerIndex = 0
+}
+
+func (v *viewport) scrollUp(n int, height int) {
+	v.scrollOffset += n
+	maxScroll := v.totalLines() - height
+	if maxScroll < 0 {
+		maxScroll = 0
+	}
+	if v.scrollOffset > maxScroll {
+		v.scrollOffset = maxScroll
+	}
+}
+
+func (v *viewport) scrollDown(n int) {
+	v.scrollOffset -= n
+	if v.scrollOffset < 0 {
+		v.scrollOffset = 0
+	}
+}
+
+func (v *viewport) clearAll() {
+	v.entries = nil
+	v.streaming = false
+	v.streamBuf = ""
+	v.pickerItems = nil
+	v.pickerActive = false
+	v.scrollOffset = 0
+}
+
+func (v *viewport) clearDisplay() {
+	v.entries = nil
+	v.scrollOffset = 0
+	v.streaming = false
+	v.streamBuf = ""
+}
+
+// pickerTitle returns a title for the current picker kind.
+func (v *viewport) pickerTitle() string {
+	switch v.pickerType {
+	case pickerAgent:
+		return "Select Agent"
+	case pickerSession:
+		return "Resume Session"
+	default:
+		return "Select"
+	}
+}
+
+// renderPicker renders the picker as a bordered overlay.
+func (v *viewport) renderPicker(width, height int) string {
+	title := v.pickerTitle()
+
+	// Determine picker dimensions
+	maxItems := len(v.pickerItems)
+	panelWidth := width - 4
+	if panelWidth < 30 {
+		panelWidth = 30
+	}
+	if panelWidth > 70 {
+		panelWidth = 70
+	}
+	innerWidth := panelWidth - 4 // border + padding
+
+	// Visible window of items (scroll if too many)
+	maxVisible := height - 6 // room for border, title, hint
+	if maxVisible < 3 {
+		maxVisible = 3
+	}
+	if maxVisible > maxItems {
+		maxVisible = maxItems
+	}
+
+	// Calculate scroll window around current index
+	startIdx := 0
+	if v.pickerIndex >= maxVisible {
+		startIdx = v.pickerIndex - maxVisible + 1
+	}
+	endIdx := startIdx + maxVisible
+	if endIdx > maxItems {
+		endIdx = maxItems
+		startIdx = endIdx - maxVisible
+		if startIdx < 0 {
+			startIdx = 0
+		}
+	}
+
+	var itemLines []string
+	for i := startIdx; i < endIdx; i++ {
+		item := v.pickerItems[i]
+		label := item.label
+		labelRunes := []rune(label)
+		if len(labelRunes) > innerWidth-4 {
+			label = string(labelRunes[:innerWidth-7]) + "..."
+		}
+		if i == v.pickerIndex {
+			line := lipgloss.NewStyle().Foreground(accentColor).Bold(true).Render("> " + label)
+			itemLines = append(itemLines, line)
+		} else {
+			itemLines = append(itemLines, "  "+label)
+		}
+	}
+
+	hint := lipgloss.NewStyle().Foreground(dimColor).Render("↑↓ navigate • enter select • esc cancel")
+
+	body := strings.Join(itemLines, "\n") + "\n\n" + hint
+
+	panel := lipgloss.NewStyle().
+		Border(lipgloss.RoundedBorder()).
+		BorderForeground(accentColor).
+		Padding(1, 2).
+		Width(panelWidth).
+		Render(body)
+
+	titleRendered := lipgloss.NewStyle().
+		Foreground(accentColor).
+		Bold(true).
+		Render(" " + title + " ")
+
+	// Build top border manually to avoid ANSI-corrupted rune slicing.
+	// panelWidth+2 accounts for the left and right border characters.
+	borderColor := lipgloss.NewStyle().Foreground(accentColor)
+	titleWidth := lipgloss.Width(titleRendered)
+	rightDashes := panelWidth + 2 - 3 - titleWidth // total - "╭─" - "╮" - title
+	if rightDashes < 0 {
+		rightDashes = 0
+	}
+	topBorder := borderColor.Render("╭─") + titleRendered +
+		borderColor.Render(strings.Repeat("─", rightDashes)+"╮")
+
+	panelLines := strings.Split(panel, "\n")
+	if len(panelLines) > 0 {
+		panelLines[0] = topBorder
+	}
+	panel = strings.Join(panelLines, "\n")
+
+	// Center the panel in the viewport
+	return lipgloss.Place(width, height, lipgloss.Center, lipgloss.Center, panel)
+}
+
+// totalLines computes the total number of rendered content lines.
+func (v *viewport) totalLines() int {
+	var lines []string
+	for _, e := range v.entries {
+		if e.kind == entryCitation && !v.showSources {
+			continue
+		}
+		lines = append(lines, e.rendered)
+	}
+	if v.streaming && v.streamBuf != "" {
+		bufLines := strings.Split(v.streamBuf, "\n")
+		if len(bufLines) > 0 {
+			bufLines[0] = agentDot + " " + bufLines[0]
+			for i := 1; i < len(bufLines); i++ {
+				bufLines[i] = "  " + bufLines[i]
+			}
+		}
+		lines = append(lines, strings.Join(bufLines, "\n"))
+	} else if v.streaming {
+		lines = append(lines, agentDot+" ")
+	}
+	content := strings.Join(lines, "\n")
+	return len(strings.Split(content, "\n"))
+}
+
+// view renders the full viewport content.
+func (v *viewport) view(height int) string {
+	// If picker is active, render it as an overlay
+	if v.pickerActive && len(v.pickerItems) > 0 {
+		return v.renderPicker(v.width, height)
+	}
+
+	var lines []string
+
+	for _, e := range v.entries {
+		if e.kind == entryCitation && !v.showSources {
+			continue
+		}
+		lines = append(lines, e.rendered)
+	}
+
+	// Streaming buffer (plain text, not markdown)
+	if v.streaming && v.streamBuf != "" {
+		bufLines := strings.Split(v.streamBuf, "\n")
+		if len(bufLines) > 0 {
+			bufLines[0] = agentDot + " " + bufLines[0]
+			for i := 1; i < len(bufLines); i++ {
+				bufLines[i] = "  " + bufLines[i]
+			}
+		}
+		lines = append(lines, strings.Join(bufLines, "\n"))
+	} else if v.streaming {
+		lines = append(lines, agentDot+" ")
+	}
+
+	content := strings.Join(lines, "\n")
+	contentLines := strings.Split(content, "\n")
+	total := len(contentLines)
+
+	maxScroll := total - height
+	if maxScroll < 0 {
+		maxScroll = 0
+	}
+	scrollOffset := v.scrollOffset
+	if scrollOffset > maxScroll {
+		scrollOffset = maxScroll
+	}
+
+	if total <= height {
+		// Content fits — pad with empty lines at top to push content down
+		padding := make([]string, height-total)
+		for i := range padding {
+			padding[i] = ""
+		}
+		contentLines = append(padding, contentLines...)
+	} else {
+		// Show a window: end is (total - scrollOffset), start is (end - height)
+		end := total - scrollOffset
+		start := end - height
+		if start < 0 {
+			start = 0
+		}
+		contentLines = contentLines[start:end]
+	}
+
+	return strings.Join(contentLines, "\n")
+}
+
diff --git a/cli/internal/tui/viewport_test.go b/cli/internal/tui/viewport_test.go
new file mode 100644
index 00000000000..c307f12437c
--- /dev/null
+++ b/cli/internal/tui/viewport_test.go
@@ -0,0 +1,264 @@
+package tui
+
+import (
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// stripANSI removes ANSI escape sequences for test comparisons.
+var ansiRegex = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+
+func stripANSI(s string) string {
+	return ansiRegex.ReplaceAllString(s, "")
+}
+
+func TestAddUserMessage(t *testing.T) {
+	v := newViewport(80)
+	v.addUserMessage("hello world")
+
+	if len(v.entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(v.entries))
+	}
+	e := v.entries[0]
+	if e.kind != entryUser {
+		t.Errorf("expected entryUser, got %d", e.kind)
+	}
+	if e.content != "hello world" {
+		t.Errorf("expected content 'hello world', got %q", e.content)
+	}
+	plain := stripANSI(e.rendered)
+	if !strings.Contains(plain, "❯") {
+		t.Errorf("expected rendered to contain ❯, got %q", plain)
+	}
+	if !strings.Contains(plain, "hello world") {
+		t.Errorf("expected rendered to contain message text, got %q", plain)
+	}
+}
+
+func TestStartAndFinishAgent(t *testing.T) {
+	v := newViewport(80)
+	v.startAgent()
+
+	if !v.streaming {
+		t.Error("expected streaming to be true after startAgent")
+	}
+	if len(v.entries) != 1 {
+		t.Fatalf("expected 1 spacer entry, got %d", len(v.entries))
+	}
+	if v.entries[0].rendered != "" {
+		t.Errorf("expected empty spacer, got %q", v.entries[0].rendered)
+	}
+
+	v.appendToken("Hello ")
+	v.appendToken("world")
+
+	if v.streamBuf != "Hello world" {
+		t.Errorf("expected streamBuf 'Hello world', got %q", v.streamBuf)
+	}
+
+	v.finishAgent()
+
+	if v.streaming {
+		t.Error("expected streaming to be false after finishAgent")
+	}
+	if v.streamBuf != "" {
+		t.Errorf("expected empty streamBuf after finish, got %q", v.streamBuf)
+	}
+	if len(v.entries) != 2 {
+		t.Fatalf("expected 2 entries (spacer + agent), got %d", len(v.entries))
+	}
+
+	e := v.entries[1]
+	if e.kind != entryAgent {
+		t.Errorf("expected entryAgent, got %d", e.kind)
+	}
+	if e.content != "Hello world" {
+		t.Errorf("expected content 'Hello world', got %q", e.content)
+	}
+	plain := stripANSI(e.rendered)
+	if !strings.Contains(plain, "Hello world") {
+		t.Errorf("expected rendered to contain message text, got %q", plain)
+	}
+}
+
+func TestFinishAgentNoPadding(t *testing.T) {
+	v := newViewport(80)
+	v.startAgent()
+	v.appendToken("Test message")
+	v.finishAgent()
+
+	e := v.entries[1]
+	// First line should not start with plain spaces (ANSI codes are OK)
+	plain := stripANSI(e.rendered)
+	lines := strings.Split(plain, "\n")
+	if strings.HasPrefix(lines[0], " ") {
+		t.Errorf("first line should not start with spaces, got %q", lines[0])
+	}
+}
+
+func TestFinishAgentMultiline(t *testing.T) {
+	v := newViewport(80)
+	v.startAgent()
+	v.appendToken("Line one\n\nLine three")
+	v.finishAgent()
+
+	e := v.entries[1]
+	plain := stripANSI(e.rendered)
+	// Glamour may merge or reformat lines; just check content is present
+	if !strings.Contains(plain, "Line one") {
+		t.Errorf("expected 'Line one' in rendered, got %q", plain)
+	}
+	if !strings.Contains(plain, "Line three") {
+		t.Errorf("expected 'Line three' in rendered, got %q", plain)
+	}
+}
+
+func TestFinishAgentEmpty(t *testing.T) {
+	v := newViewport(80)
+	v.startAgent()
+	v.finishAgent()
+
+	if v.streaming {
+		t.Error("expected streaming to be false")
+	}
+	if len(v.entries) != 0 {
+		t.Errorf("expected 0 entries (spacer removed), got %d", len(v.entries))
+	}
+}
+
+func TestAddInfo(t *testing.T) {
+	v := newViewport(80)
+	v.addInfo("test info")
+
+	if len(v.entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(v.entries))
+	}
+	e := v.entries[0]
+	if e.kind != entryInfo {
+		t.Errorf("expected entryInfo, got %d", e.kind)
+	}
+	plain := stripANSI(e.rendered)
+	if strings.HasPrefix(plain, " ") {
+		t.Errorf("info should not have leading spaces, got %q", plain)
+	}
+}
+
+func TestAddError(t *testing.T) {
+	v := newViewport(80)
+	v.addError("something broke")
+
+	if len(v.entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(v.entries))
+	}
+	e := v.entries[0]
+	if e.kind != entryError {
+		t.Errorf("expected entryError, got %d", e.kind)
+	}
+	plain := stripANSI(e.rendered)
+	if !strings.Contains(plain, "something broke") {
+		t.Errorf("expected error message in rendered, got %q", plain)
+	}
+}
+
+func TestAddCitations(t *testing.T) {
+	v := newViewport(80)
+	v.addCitations(map[int]string{1: "doc-a", 2: "doc-b"})
+
+	if len(v.entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(v.entries))
+	}
+	e := v.entries[0]
+	if e.kind != entryCitation {
+		t.Errorf("expected entryCitation, got %d", e.kind)
+	}
+	plain := stripANSI(e.rendered)
+	if !strings.Contains(plain, "Sources (2)") {
+		t.Errorf("expected sources count in rendered, got %q", plain)
+	}
+	if strings.HasPrefix(plain, " ") {
+		t.Errorf("citation should not have leading spaces, got %q", plain)
+	}
+}
+
+func TestAddCitationsEmpty(t *testing.T) {
+	v := newViewport(80)
+	v.addCitations(map[int]string{})
+
+	if len(v.entries) != 0 {
+		t.Errorf("expected no entries for empty citations, got %d", len(v.entries))
+	}
+}
+
+func TestCitationVisibility(t *testing.T) {
+	v := newViewport(80)
+	v.addInfo("hello")
+	v.addCitations(map[int]string{1: "doc"})
+
+	v.showSources = false
+	view := v.view(20)
+	plain := stripANSI(view)
+	if strings.Contains(plain, "Sources") {
+		t.Error("expected citations hidden when showSources=false")
+	}
+
+	v.showSources = true
+	view = v.view(20)
+	plain = stripANSI(view)
+	if !strings.Contains(plain, "Sources") {
+		t.Error("expected citations visible when showSources=true")
+	}
+}
+
+func TestClearAll(t *testing.T) {
+	v := newViewport(80)
+	v.addUserMessage("test")
+	v.startAgent()
+	v.appendToken("response")
+
+	v.clearAll()
+
+	if len(v.entries) != 0 {
+		t.Errorf("expected no entries after clearAll, got %d", len(v.entries))
+	}
+	if v.streaming {
+		t.Error("expected streaming=false after clearAll")
+	}
+	if v.streamBuf != "" {
+		t.Errorf("expected empty streamBuf after clearAll, got %q", v.streamBuf)
+	}
+}
+
+func TestClearDisplay(t *testing.T) {
+	v := newViewport(80)
+	v.addUserMessage("test")
+	v.clearDisplay()
+
+	if len(v.entries) != 0 {
+		t.Errorf("expected no entries after clearDisplay, got %d", len(v.entries))
+	}
+}
+
+func TestViewPadsShortContent(t *testing.T) {
+	v := newViewport(80)
+	v.addInfo("hello")
+
+	view := v.view(10)
+	lines := strings.Split(view, "\n")
+	if len(lines) != 10 {
+		t.Errorf("expected 10 lines (padded), got %d", len(lines))
+	}
+}
+
+func TestViewTruncatesTallContent(t *testing.T) {
+	v := newViewport(80)
+	for i := 0; i < 20; i++ {
+		v.addInfo("line")
+	}
+
+	view := v.view(5)
+	lines := strings.Split(view, "\n")
+	if len(lines) != 5 {
+		t.Errorf("expected 5 lines (truncated), got %d", len(lines))
+	}
+}
diff --git a/cli/internal/util/browser.go b/cli/internal/util/browser.go
new file mode 100644
index 00000000000..5e9101b8f71
--- /dev/null
+++ b/cli/internal/util/browser.go
@@ -0,0 +1,29 @@
+// Package util provides shared utility functions.
+package util
+
+import (
+	"os/exec"
+	"runtime"
+)
+
+// OpenBrowser opens the given URL in the user's default browser.
+// Returns true if the browser was launched successfully.
+func OpenBrowser(url string) bool {
+	var cmd *exec.Cmd
+	switch runtime.GOOS {
+	case "darwin":
+		cmd = exec.Command("open", url)
+	case "linux":
+		cmd = exec.Command("xdg-open", url)
+	case "windows":
+		cmd = exec.Command("rundll32", "url.dll,FileProtocolHandler", url)
+	}
+	if cmd != nil {
+		if err := cmd.Start(); err == nil {
+			// Reap the child process to avoid zombies.
+			go func() { _ = cmd.Wait() }()
+			return true
+		}
+	}
+	return false
+}
diff --git a/cli/internal/util/styles.go b/cli/internal/util/styles.go
new file mode 100644
index 00000000000..16b67f402be
--- /dev/null
+++ b/cli/internal/util/styles.go
@@ -0,0 +1,13 @@
+// Package util provides shared utilities for the Onyx CLI.
+package util
+
+import "github.com/charmbracelet/lipgloss"
+
+// Shared text styles used across the CLI.
+var (
+	BoldStyle   = lipgloss.NewStyle().Bold(true)
+	DimStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("#555577"))
+	GreenStyle  = lipgloss.NewStyle().Foreground(lipgloss.Color("#00cc66")).Bold(true)
+	RedStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("#ff5555")).Bold(true)
+	YellowStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("#ffcc00"))
+)
diff --git a/cli/main.go b/cli/main.go
new file mode 100644
index 00000000000..b07df16f802
--- /dev/null
+++ b/cli/main.go
@@ -0,0 +1,23 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/onyx-dot-app/onyx/cli/cmd"
+)
+
+var (
+	version = "dev"
+	commit  = "none"
+)
+
+func main() {
+	cmd.Version = version
+	cmd.Commit = commit
+
+	if err := cmd.Execute(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}

From 893e8da79a073ee6de510d6c43d85a9df51e857b Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Fri, 6 Mar 2026 12:48:58 +0530
Subject: [PATCH 142/267] feat(table): add server-side pagination, search
 filtering, view mode, and DragOverlay improvements (#9085)

---
 .../refresh-components/table/DataTable.tsx    | 197 ++++++++++------
 .../table/DragOverlayRow.tsx                  |  73 +++++-
 web/src/refresh-components/table/README.md    | 145 ++++++++++++
 web/src/refresh-components/table/columns.ts   |  12 +-
 .../table/hooks/useDataTable.ts               | 217 +++++++++++++++++-
 .../table/hooks/useDraggableRows.ts           |  11 +-
 web/src/refresh-components/table/types.ts     |  43 +++-
 7 files changed, 606 insertions(+), 92 deletions(-)

diff --git a/web/src/refresh-components/table/DataTable.tsx b/web/src/refresh-components/table/DataTable.tsx
index 9ed6f027015..5d03b59dc0d 100644
--- a/web/src/refresh-components/table/DataTable.tsx
+++ b/web/src/refresh-components/table/DataTable.tsx
@@ -1,7 +1,7 @@
 "use client";
 "use no memo";
 
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { flexRender } from "@tanstack/react-table";
 import useDataTable, {
   toOnyxSortDirection,
@@ -24,6 +24,7 @@ import { ColumnVisibilityPopover } from "@/refresh-components/table/ColumnVisibi
 import { SortingPopover } from "@/refresh-components/table/SortingPopover";
 import type { WidthConfig } from "@/refresh-components/table/hooks/useColumnWidths";
 import type { ColumnDef } from "@tanstack/react-table";
+import { cn } from "@/lib/utils";
 import type {
   DataTableProps,
   DataTableFooterConfig,
@@ -34,8 +35,6 @@ import type {
 } from "@/refresh-components/table/types";
 import type { TableSize } from "@/refresh-components/table/TableSizeContext";
 
-const noopGetRowId = () => "";
-
 // ---------------------------------------------------------------------------
 // Internal: resolve size-dependent widths and build TanStack columns
 // ---------------------------------------------------------------------------
@@ -121,15 +120,19 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
   const {
     data,
     columns,
+    getRowId,
     pageSize,
     initialSorting,
     initialColumnVisibility,
     draggable,
     footer,
     size = "regular",
+    onSelectionChange,
     onRowClick,
+    searchTerm,
     height,
     headerBackground,
+    serverSide,
   } = props;
 
   const effectivePageSize = pageSize ?? (footer ? 10 : data.length);
@@ -148,15 +151,30 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
     pageSize: resolvedPageSize,
     selectionState,
     selectedCount,
+    selectedRowIds,
     clearSelection,
     toggleAllPageRowsSelected,
     isAllPageRowsSelected,
+    isViewingSelected,
+    enterViewMode,
+    exitViewMode,
   } = useDataTable({
     data,
     columns: tanstackColumns,
     pageSize: effectivePageSize,
     initialSorting,
     initialColumnVisibility,
+    getRowId,
+    onSelectionChange,
+    searchTerm,
+    serverSide: serverSide
+      ? {
+          totalItems: serverSide.totalItems,
+          onSortingChange: serverSide.onSortingChange,
+          onPaginationChange: serverSide.onPaginationChange,
+          onSearchTermChange: serverSide.onSearchTermChange,
+        }
+      : undefined,
   });
 
   // 3. Call useColumnWidths
@@ -165,15 +183,34 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
     ...widthConfig,
   });
 
-  // 4. Call useDraggableRows (conditional)
+  // 4. Call useDraggableRows (conditional — disabled in server-side mode)
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "production" && serverSide && draggable) {
+      console.warn(
+        "DataTable: `draggable` is ignored when `serverSide` is enabled. " +
+          "Drag-and-drop reordering is not supported with server-side pagination."
+      );
+    }
+  }, [!!serverSide, !!draggable]); // eslint-disable-line react-hooks/exhaustive-deps
+  const footerShowView =
+    footer?.mode === "selection" ? footer.showView : undefined;
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "production" && serverSide && footerShowView) {
+      console.warn(
+        "DataTable: `showView` is ignored when `serverSide` is enabled. " +
+          "View mode requires client-side filtering."
+      );
+    }
+  }, [!!serverSide, !!footerShowView]); // eslint-disable-line react-hooks/exhaustive-deps
+  const effectiveDraggable = serverSide ? undefined : draggable;
   const draggableReturn = useDraggableRows({
     data,
-    getRowId: draggable?.getRowId ?? noopGetRowId,
-    enabled: !!draggable && table.getState().sorting.length === 0,
-    onReorder: draggable?.onReorder,
+    getRowId,
+    enabled: !!effectiveDraggable && table.getState().sorting.length === 0,
+    onReorder: effectiveDraggable?.onReorder,
   });
 
-  const hasDraggable = !!draggable;
+  const hasDraggable = !!effectiveDraggable;
   const rowVariant = hasDraggable ? "table" : "list";
 
   const isSelectable =
@@ -183,11 +220,71 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
   // Render
   // ---------------------------------------------------------------------------
 
-  function renderContent() {
+  const isServerLoading = !!serverSide?.isLoading;
+
+  function renderFooter(footerConfig: DataTableFooterConfig) {
+    if (footerConfig.mode === "selection") {
+      return (
+        <Footer
+          mode="selection"
+          multiSelect={footerConfig.multiSelect !== false}
+          selectionState={selectionState}
+          selectedCount={selectedCount}
+          onClear={
+            footerConfig.onClear ??
+            (() => {
+              if (isViewingSelected) exitViewMode();
+              clearSelection();
+            })
+          }
+          onView={
+            footerConfig.showView
+              ? isViewingSelected
+                ? exitViewMode
+                : enterViewMode
+              : undefined
+          }
+          pageSize={resolvedPageSize}
+          totalItems={totalItems}
+          currentPage={currentPage}
+          totalPages={totalPages}
+          onPageChange={setPage}
+        />
+      );
+    }
+
+    // Summary mode
+    const rangeStart =
+      totalItems === 0
+        ? 0
+        : !isFinite(resolvedPageSize)
+          ? 1
+          : (currentPage - 1) * resolvedPageSize + 1;
+    const rangeEnd = !isFinite(resolvedPageSize)
+      ? totalItems
+      : Math.min(currentPage * resolvedPageSize, totalItems);
+
     return (
+      <Footer
+        mode="summary"
+        rangeStart={rangeStart}
+        rangeEnd={rangeEnd}
+        totalItems={totalItems}
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={setPage}
+      />
+    );
+  }
+
+  return (
+    <TableSizeProvider size={size}>
       <div>
         <div
-          className="overflow-x-auto"
+          className={cn(
+            "overflow-x-auto transition-opacity duration-150",
+            isServerLoading && "opacity-50 pointer-events-none"
+          )}
           ref={containerRef}
           style={{
             ...(height != null
@@ -315,19 +412,24 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                   ? (activeId) => {
                       const row = table
                         .getRowModel()
-                        .rows.find(
-                          (r) => draggable!.getRowId(r.original) === activeId
-                        );
+                        .rows.find((r) => getRowId(r.original) === activeId);
                       if (!row) return null;
-                      return <DragOverlayRow row={row} variant={rowVariant} />;
+                      return (
+                        <DragOverlayRow
+                          row={row}
+                          variant={rowVariant}
+                          columnWidths={columnWidths}
+                          columnKindMap={columnKindMap}
+                          qualifierColumn={qualifierColumn}
+                          isSelectable={isSelectable}
+                        />
+                      );
                     }
                   : undefined
               }
             >
               {table.getRowModel().rows.map((row) => {
-                const rowId = hasDraggable
-                  ? draggable!.getRowId(row.original)
-                  : undefined;
+                const rowId = hasDraggable ? getRowId(row.original) : undefined;
 
                 return (
                   <TableRow
@@ -336,6 +438,12 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                     sortableId={rowId}
                     selected={row.getIsSelected()}
                     onClick={() => {
+                      if (
+                        hasDraggable &&
+                        draggableReturn.wasDraggingRef.current
+                      ) {
+                        return;
+                      }
                       if (onRowClick) {
                         onRowClick(row.original);
                       } else if (isSelectable) {
@@ -377,7 +485,11 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                       // Actions cell
                       if (cellColDef?.kind === "actions") {
                         return (
-                          <ActionsContainer key={cell.id} type="cell">
+                          <ActionsContainer
+                            key={cell.id}
+                            type="cell"
+                            onClick={(e) => e.stopPropagation()}
+                          >
                             {flexRender(
                               cell.column.columnDef.cell,
                               cell.getContext()
@@ -405,51 +517,6 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
 
         {footer && renderFooter(footer)}
       </div>
-    );
-  }
-
-  function renderFooter(footerConfig: DataTableFooterConfig) {
-    if (footerConfig.mode === "selection") {
-      return (
-        <Footer
-          mode="selection"
-          multiSelect={footerConfig.multiSelect !== false}
-          selectionState={selectionState}
-          selectedCount={selectedCount}
-          onClear={footerConfig.onClear ?? clearSelection}
-          onView={footerConfig.onView}
-          pageSize={resolvedPageSize}
-          totalItems={totalItems}
-          currentPage={currentPage}
-          totalPages={totalPages}
-          onPageChange={setPage}
-        />
-      );
-    }
-
-    // Summary mode
-    const rangeStart =
-      totalItems === 0
-        ? 0
-        : !isFinite(resolvedPageSize)
-          ? 1
-          : (currentPage - 1) * resolvedPageSize + 1;
-    const rangeEnd = !isFinite(resolvedPageSize)
-      ? totalItems
-      : Math.min(currentPage * resolvedPageSize, totalItems);
-
-    return (
-      <Footer
-        mode="summary"
-        rangeStart={rangeStart}
-        rangeEnd={rangeEnd}
-        totalItems={totalItems}
-        currentPage={currentPage}
-        totalPages={totalPages}
-        onPageChange={setPage}
-      />
-    );
-  }
-
-  return <TableSizeProvider size={size}>{renderContent()}</TableSizeProvider>;
+    </TableSizeProvider>
+  );
 }
diff --git a/web/src/refresh-components/table/DragOverlayRow.tsx b/web/src/refresh-components/table/DragOverlayRow.tsx
index 437f12669b7..1fde666a0bb 100644
--- a/web/src/refresh-components/table/DragOverlayRow.tsx
+++ b/web/src/refresh-components/table/DragOverlayRow.tsx
@@ -2,28 +2,87 @@ import { memo } from "react";
 import { type Row, flexRender } from "@tanstack/react-table";
 import TableRow from "@/refresh-components/table/TableRow";
 import TableCell from "@/refresh-components/table/TableCell";
+import QualifierContainer from "@/refresh-components/table/QualifierContainer";
+import TableQualifier from "@/refresh-components/table/TableQualifier";
+import ActionsContainer from "@/refresh-components/table/ActionsContainer";
+import type {
+  OnyxColumnDef,
+  OnyxQualifierColumn,
+} from "@/refresh-components/table/types";
 
 interface DragOverlayRowProps<TData> {
   row: Row<TData>;
   variant?: "table" | "list";
+  columnWidths?: Record<string, number>;
+  columnKindMap?: Map<string, OnyxColumnDef<TData>>;
+  qualifierColumn?: OnyxQualifierColumn<TData> | null;
+  isSelectable?: boolean;
 }
 
 function DragOverlayRowInner<TData>({
   row,
   variant,
+  columnWidths,
+  columnKindMap,
+  qualifierColumn,
+  isSelectable = false,
 }: DragOverlayRowProps<TData>) {
+  const tableWidth = columnWidths
+    ? Object.values(columnWidths).reduce((sum, w) => sum + w, 0)
+    : undefined;
+
   return (
     <table
-      className="min-w-full border-collapse"
-      style={{ tableLayout: "fixed" }}
+      className="border-collapse"
+      style={{
+        tableLayout: "fixed",
+        ...(tableWidth != null ? { width: tableWidth } : { minWidth: "100%" }),
+      }}
     >
-      <tbody>
-        <TableRow variant={variant} selected={row.getIsSelected()}>
+      {columnWidths && (
+        <colgroup>
           {row.getVisibleCells().map((cell) => (
-            <TableCell key={cell.id} width={cell.column.getSize()}>
-              {flexRender(cell.column.columnDef.cell, cell.getContext())}
-            </TableCell>
+            <col
+              key={cell.column.id}
+              style={{ width: columnWidths[cell.column.id] }}
+            />
           ))}
+        </colgroup>
+      )}
+      <tbody>
+        <TableRow variant={variant} selected={row.getIsSelected()}>
+          {row.getVisibleCells().map((cell) => {
+            const colDef = columnKindMap?.get(cell.column.id);
+
+            if (colDef?.kind === "qualifier" && qualifierColumn) {
+              return (
+                <QualifierContainer key={cell.id} type="cell">
+                  <TableQualifier
+                    content={qualifierColumn.content}
+                    initials={qualifierColumn.getInitials?.(row.original)}
+                    icon={qualifierColumn.getIcon?.(row.original)}
+                    imageSrc={qualifierColumn.getImageSrc?.(row.original)}
+                    selectable={isSelectable}
+                    selected={isSelectable && row.getIsSelected()}
+                  />
+                </QualifierContainer>
+              );
+            }
+
+            if (colDef?.kind === "actions") {
+              return (
+                <ActionsContainer key={cell.id} type="cell">
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </ActionsContainer>
+              );
+            }
+
+            return (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            );
+          })}
         </TableRow>
       </tbody>
     </table>
diff --git a/web/src/refresh-components/table/README.md b/web/src/refresh-components/table/README.md
index f03e2e75491..2dd9db5a668 100644
--- a/web/src/refresh-components/table/README.md
+++ b/web/src/refresh-components/table/README.md
@@ -117,6 +117,7 @@ Fixed-width column rendered at the trailing edge. Houses column visibility and s
 | `showColumnVisibility` | `boolean` | `true` | Show the column visibility popover |
 | `showSorting` | `boolean` | `true` | Show the sorting popover |
 | `sortingFooterText` | `string` | - | Footer text inside the sorting popover |
+| `cell` | `(row: TData) => ReactNode` | - | Row-level cell renderer for action buttons |
 
 Width is fixed: 88px at `"regular"`, 20px at `"small"`.
 
@@ -126,6 +127,19 @@ tc.actions({
 })
 ```
 
+Row-level actions — the `cell` callback receives the row data and renders content in each body row. Clicks inside the cell automatically call `stopPropagation`, so they won't trigger row selection.
+
+```tsx
+tc.actions({
+  cell: (row) => (
+    <div className="flex gap-x-1">
+      <IconButton icon={SvgPencil} onClick={() => openEdit(row.id)} />
+      <IconButton icon={SvgTrash} onClick={() => confirmDelete(row.id)} />
+    </div>
+  ),
+})
+```
+
 ## DataTable Props
 
 `DataTableProps<TData>`:
@@ -143,6 +157,8 @@ tc.actions({
 | `onRowClick` | `(row: TData) => void` | toggles selection | Called on row click, replaces default selection toggle |
 | `height` | `number \| string` | - | Max height for scrollable body (header stays pinned). `300` or `"50vh"` |
 | `headerBackground` | `string` | - | CSS color for the sticky header (prevents content showing through) |
+| `searchTerm` | `string` | - | Search term for client-side global text filtering (case-insensitive match across all accessor columns) |
+| `serverSide` | `ServerSideConfig` | - | Enable server-side mode for manual pagination, sorting, and filtering ([see below](#server-side-mode)) |
 
 ## Footer Config
 
@@ -193,6 +209,110 @@ Enable drag-and-drop row reordering. DnD is automatically disabled when column s
 | `getRowId` | `(row: TData) => string` | Extract a unique string ID from each row |
 | `onReorder` | `(ids: string[], changedOrders: Record<string, number>) => void \| Promise<void>` | Called after a successful reorder |
 
+## Server-Side Mode
+
+Pass the `serverSide` prop to switch from client-side to server-side pagination, sorting, and filtering. In this mode `data` should contain **only the current page slice** — TanStack operates with `manualPagination`, `manualSorting`, and `manualFiltering` enabled. Drag-and-drop is automatically disabled.
+
+### `ServerSideConfig`
+
+| Prop | Type | Description |
+|---|---|---|
+| `totalItems` | `number` | Total row count from the server, used to compute page count |
+| `isLoading` | `boolean` | Shows a loading overlay (opacity + pointer-events-none) while data is being fetched |
+| `onSortingChange` | `(sorting: SortingState) => void` | Fired when the user clicks a column header |
+| `onPaginationChange` | `(pageIndex: number, pageSize: number) => void` | Fired on page navigation and on automatic resets from sort/search changes |
+| `onSearchTermChange` | `(searchTerm: string) => void` | Fired when the `searchTerm` prop changes |
+
+### Callback contract
+
+The callbacks fire in a predictable order:
+
+- **Sort change** — `onSortingChange` fires first, then the page resets to 0 and `onPaginationChange(0, pageSize)` fires.
+- **Page navigation** — only `onPaginationChange` fires.
+- **Search change** — `onSearchTermChange` fires, and the page resets to 0. `onPaginationChange` only fires if the page was actually on a non-zero page. When already on page 0, `searchTerm` drives the re-fetch independently (e.g. via your SWR key) — no `onPaginationChange` is needed.
+
+Your data-fetching layer should include `searchTerm` in its fetch dependencies (e.g. SWR key) so that search changes trigger re-fetches regardless of pagination state.
+
+### Full example
+
+```tsx
+import { useState } from "react";
+import useSWR from "swr";
+import type { SortingState } from "@tanstack/react-table";
+import DataTable from "@/refresh-components/table/DataTable";
+import { createTableColumns } from "@/refresh-components/table/columns";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const tc = createTableColumns<User>();
+const columns = [
+  tc.qualifier(),
+  tc.column("name", { header: "Name", weight: 40, minWidth: 120 }),
+  tc.column("email", { header: "Email", weight: 60, minWidth: 150 }),
+  tc.actions(),
+];
+
+function UsersTable() {
+  const [searchTerm, setSearchTerm] = useState("");
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [pageIndex, setPageIndex] = useState(0);
+  const [pageSize, setPageSize] = useState(10);
+
+  const { data: response, isLoading } = useSWR(
+    ["/api/users", sorting, pageIndex, pageSize, searchTerm],
+    ([url, sorting, pageIndex, pageSize, searchTerm]) =>
+      fetch(
+        `${url}?` +
+          new URLSearchParams({
+            page: String(pageIndex),
+            size: String(pageSize),
+            search: searchTerm,
+            ...(sorting[0] && {
+              sortBy: sorting[0].id,
+              sortDir: sorting[0].desc ? "desc" : "asc",
+            }),
+          })
+      ).then((r) => r.json())
+  );
+
+  return (
+    <div className="space-y-4">
+      <InputTypeIn
+        value={searchTerm}
+        onChange={(e) => setSearchTerm(e.target.value)}
+        placeholder="Search users..."
+      />
+      <DataTable
+        data={response?.items ?? []}
+        columns={columns}
+        getRowId={(row) => row.id}
+        searchTerm={searchTerm}
+        pageSize={pageSize}
+        footer={{ mode: "summary" }}
+        serverSide={{
+          totalItems: response?.total ?? 0,
+          isLoading,
+          onSortingChange: setSorting,
+          onPaginationChange: (idx, size) => {
+            setPageIndex(idx);
+            setPageSize(size);
+          },
+          onSearchTermChange: () => {
+            // search state is already managed above via searchTerm prop;
+            // this callback is useful for analytics or debouncing
+          },
+        }}
+      />
+    </div>
+  );
+}
+```
+
 ## Sizing
 
 The `size` prop (`"regular"` or `"small"`) affects:
@@ -293,6 +413,31 @@ tc.qualifier({
 </div>
 ```
 
+### Server-side pagination
+
+Minimal wiring for server-side mode — manage sorting/pagination state externally and pass the current page slice as `data`.
+
+```tsx
+<DataTable
+  data={currentPageRows}
+  columns={columns}
+  getRowId={(row) => row.id}
+  searchTerm={searchTerm}
+  pageSize={pageSize}
+  footer={{ mode: "summary" }}
+  serverSide={{
+    totalItems: totalCount,
+    isLoading,
+    onSortingChange: setSorting,
+    onPaginationChange: (idx, size) => {
+      setPageIndex(idx);
+      setPageSize(size);
+    },
+    onSearchTermChange: (term) => setSearchTerm(term),
+  }}
+/>
+```
+
 ### Custom row click handler
 
 ```tsx
diff --git a/web/src/refresh-components/table/columns.ts b/web/src/refresh-components/table/columns.ts
index 7ffc71ed5a4..d8246cc4158 100644
--- a/web/src/refresh-components/table/columns.ts
+++ b/web/src/refresh-components/table/columns.ts
@@ -83,13 +83,15 @@ interface DisplayColumnConfig<TData> {
 // Actions column config
 // ---------------------------------------------------------------------------
 
-interface ActionsConfig {
+interface ActionsConfig<TData = any> {
   /** Show column visibility popover. @default true */
   showColumnVisibility?: boolean;
   /** Show sorting popover. @default true */
   showSorting?: boolean;
   /** Footer text for the sorting popover. */
   sortingFooterText?: string;
+  /** Optional cell renderer for row-level action buttons. */
+  cell?: (row: TData) => ReactNode;
 }
 
 // ---------------------------------------------------------------------------
@@ -110,7 +112,7 @@ interface TableColumnsBuilder<TData> {
   displayColumn(config: DisplayColumnConfig<TData>): OnyxDisplayColumn<TData>;
 
   /** Create an actions column (visibility/sorting popovers). */
-  actions(config?: ActionsConfig): OnyxActionsColumn<TData>;
+  actions(config?: ActionsConfig<TData>): OnyxActionsColumn<TData>;
 }
 
 // ---------------------------------------------------------------------------
@@ -226,7 +228,7 @@ export function createTableColumns<TData>(): TableColumnsBuilder<TData> {
       };
     },
 
-    actions(config?: ActionsConfig): OnyxActionsColumn<TData> {
+    actions(config?: ActionsConfig<TData>): OnyxActionsColumn<TData> {
       const def: ColumnDef<TData, any> = {
         id: "__actions",
         enableHiding: false,
@@ -234,7 +236,9 @@ export function createTableColumns<TData>(): TableColumnsBuilder<TData> {
         enableResizing: false,
         // Header rendering is handled by DataTable based on the actions config
         header: () => null,
-        cell: () => null,
+        cell: config?.cell
+          ? (info: CellContext<TData, any>) => config.cell!(info.row.original)
+          : () => null,
       };
 
       return {
diff --git a/web/src/refresh-components/table/hooks/useDataTable.ts b/web/src/refresh-components/table/hooks/useDataTable.ts
index f304299e9ac..d5094531422 100644
--- a/web/src/refresh-components/table/hooks/useDataTable.ts
+++ b/web/src/refresh-components/table/hooks/useDataTable.ts
@@ -1,12 +1,13 @@
 "use client";
 "use no memo";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useMemo, useRef } from "react";
 import {
   useReactTable,
   getCoreRowModel,
   getSortedRowModel,
   getPaginationRowModel,
+  getFilteredRowModel,
   type Table,
   type ColumnDef,
   type RowData,
@@ -44,6 +45,15 @@ export function toOnyxSortDirection(
   return "none";
 }
 
+// ---------------------------------------------------------------------------
+// Global filter value (combines view-mode + text search)
+// ---------------------------------------------------------------------------
+
+interface GlobalFilterValue {
+  selectedIds: Set<string> | null;
+  searchTerm: string;
+}
+
 // ---------------------------------------------------------------------------
 // Hook options & return types
 // ---------------------------------------------------------------------------
@@ -58,12 +68,16 @@ type ManagedKeys =
   | "onColumnSizingChange"
   | "onColumnVisibilityChange"
   | "onPaginationChange"
+  | "onGlobalFilterChange"
   | "getCoreRowModel"
   | "getSortedRowModel"
   | "getPaginationRowModel"
+  | "getFilteredRowModel"
+  | "globalFilterFn"
   | "columnResizeMode"
   | "enableRowSelection"
-  | "enableColumnResizing";
+  | "enableColumnResizing"
+  | "getRowId";
 
 /**
  * Options accepted by {@link useDataTable}.
@@ -81,12 +95,26 @@ interface UseDataTableOptions<TData extends RowData> {
   enableRowSelection?: boolean;
   /** Whether columns can be resized. @default true */
   enableColumnResizing?: boolean;
+  /** Stable row identity function. TanStack tracks selection by ID instead of array index. */
+  getRowId: TableOptions<TData>["getRowId"];
   /** Resize strategy. @default "onChange" */
   columnResizeMode?: ColumnResizeMode;
   /** Initial sorting state. @default [] */
   initialSorting?: SortingState;
   /** Initial column visibility state. @default {} */
   initialColumnVisibility?: VisibilityState;
+  /** Called whenever the set of selected row IDs changes. */
+  onSelectionChange?: (selectedIds: string[]) => void;
+  /** Search term for global text filtering. Rows are filtered to those containing
+   *  the term in any accessor column value (case-insensitive). */
+  searchTerm?: string;
+  /** Server-side configuration. When provided, enables manual pagination/sorting/filtering. */
+  serverSide?: {
+    totalItems: number;
+    onSortingChange: (sorting: SortingState) => void;
+    onPaginationChange: (pageIndex: number, pageSize: number) => void;
+    onSearchTermChange: (searchTerm: string) => void;
+  };
   /** Escape-hatch: extra options spread into `useReactTable`. Managed keys are excluded. */
   tableOptions?: Partial<Omit<TableOptions<TData>, ManagedKeys>>;
 }
@@ -119,10 +147,20 @@ interface UseDataTableReturn<TData extends RowData> {
   selectedCount: number;
   /** Whether every row on the current page is selected. */
   isAllPageRowsSelected: boolean;
+  /** IDs of currently selected rows (derived from `getRowId`). */
+  selectedRowIds: string[];
   /** Deselect all rows. */
   clearSelection: () => void;
   /** Select or deselect all rows on the current page. */
   toggleAllPageRowsSelected: (selected: boolean) => void;
+
+  // View-mode (filter to selected rows)
+  /** Whether the table is currently filtered to show only selected rows. */
+  isViewingSelected: boolean;
+  /** Enter view mode — freeze the current selection as a filter. */
+  enterViewMode: () => void;
+  /** Exit view mode — remove the selection filter. */
+  exitViewMode: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -153,9 +191,15 @@ export default function useDataTable<TData extends RowData>(
     columnResizeMode = "onChange",
     initialSorting = [],
     initialColumnVisibility = {},
+    getRowId,
+    onSelectionChange,
+    searchTerm,
+    serverSide,
     tableOptions,
   } = options;
 
+  const isServerSide = !!serverSide;
+
   // ---- internal state -----------------------------------------------------
   const [sorting, setSorting] = useState<SortingState>(initialSorting);
   const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
@@ -167,6 +211,11 @@ export default function useDataTable<TData extends RowData>(
     pageIndex: 0,
     pageSize: pageSizeOption,
   });
+  /** Combined global filter: view-mode (selected IDs) + text search. */
+  const [globalFilter, setGlobalFilter] = useState<GlobalFilterValue>({
+    selectedIds: null,
+    searchTerm: "",
+  });
 
   // ---- sync pageSize prop to internal state --------------------------------
   useEffect(() => {
@@ -177,30 +226,132 @@ export default function useDataTable<TData extends RowData>(
     }));
   }, [pageSizeOption]);
 
+  // ---- sync external searchTerm prop into combined filter state ------------
+  // (client-side only — server-side uses separate callbacks instead)
+  const preSearchPageRef = useRef<number>(0);
+
+  useEffect(() => {
+    if (isServerSide) return;
+    const term = searchTerm ?? "";
+    const wasSearching = !!globalFilter.searchTerm;
+
+    if (!wasSearching && term) {
+      // Entering search — save current page, reset to 0
+      preSearchPageRef.current = pagination.pageIndex;
+      setPagination((p) => ({ ...p, pageIndex: 0 }));
+    } else if (wasSearching && !term) {
+      // Clearing search — restore saved page
+      setPagination((p) => ({ ...p, pageIndex: preSearchPageRef.current }));
+    }
+
+    setGlobalFilter((prev) => ({ ...prev, searchTerm: term }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- Intentionally
+    // omits `globalFilter` and `pagination.pageIndex`: we only read snapshot
+    // values to detect the search enter/clear transition, not to react to
+    // every filter or page change.
+  }, [searchTerm, isServerSide]);
+
+  // ---- server-side: 3 separate callbacks -----------------------------------
+  // Single ref for the whole serverSide config — prevents effects from
+  // re-firing when the consumer passes an inline object each render.
+  const serverSideRef = useRef(serverSide);
+  serverSideRef.current = serverSide;
+
+  useEffect(() => {
+    if (!isServerSide) return;
+    serverSideRef.current!.onSortingChange(sorting);
+  }, [sorting, isServerSide]);
+
+  useEffect(() => {
+    if (!isServerSide) return;
+    serverSideRef.current!.onPaginationChange(
+      pagination.pageIndex,
+      pagination.pageSize
+    );
+  }, [pagination.pageIndex, pagination.pageSize, isServerSide]);
+
+  useEffect(() => {
+    if (!isServerSide) return;
+    setPagination((p) => ({ ...p, pageIndex: 0 }));
+    serverSideRef.current!.onSearchTermChange(searchTerm ?? "");
+  }, [searchTerm, isServerSide]);
+
   // ---- TanStack table instance --------------------------------------------
-  const table = useReactTable({
+  const serverPageCount = isServerSide
+    ? isFinite(pagination.pageSize) && pagination.pageSize > 0
+      ? Math.ceil((serverSide!.totalItems || 0) / pagination.pageSize)
+      : 1
+    : undefined;
+
+  const tableOpts: TableOptions<TData> = {
     data,
     columns,
+    getRowId,
     state: {
       sorting,
       rowSelection,
       columnSizing,
       columnVisibility,
       pagination,
+      ...(isServerSide ? {} : { globalFilter }),
     },
-    onSortingChange: setSorting,
+    onSortingChange: isServerSide
+      ? (updater) => {
+          setSorting(updater);
+          setPagination((p) => ({ ...p, pageIndex: 0 }));
+        }
+      : setSorting,
     onRowSelectionChange: setRowSelection,
     onColumnSizingChange: setColumnSizing,
     onColumnVisibilityChange: setColumnVisibility,
     onPaginationChange: setPagination,
     getCoreRowModel: getCoreRowModel(),
-    getSortedRowModel: getSortedRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
+    // We manage page resets explicitly (search enter/clear, view mode,
+    // pageSize change) so disable TanStack's auto-reset which would
+    // clobber our restored page index when the filter changes.
+    autoResetPageIndex: false,
     columnResizeMode,
     enableRowSelection,
     enableColumnResizing,
     ...tableOptions,
-  });
+  };
+
+  if (isServerSide) {
+    tableOpts.manualPagination = true;
+    tableOpts.manualSorting = true;
+    tableOpts.manualFiltering = true;
+    tableOpts.pageCount = serverPageCount;
+  } else {
+    tableOpts.onGlobalFilterChange = setGlobalFilter;
+    tableOpts.getSortedRowModel = getSortedRowModel();
+    tableOpts.getPaginationRowModel = getPaginationRowModel();
+    tableOpts.getFilteredRowModel = getFilteredRowModel();
+    tableOpts.globalFilterFn = (
+      row,
+      _columnId,
+      filterValue: GlobalFilterValue
+    ) => {
+      // View-mode filter (selected IDs)
+      if (
+        filterValue.selectedIds != null &&
+        !filterValue.selectedIds.has(row.id)
+      ) {
+        return false;
+      }
+      // Text search filter
+      if (filterValue.searchTerm) {
+        const term = filterValue.searchTerm.toLowerCase();
+        return row.getAllCells().some((cell) => {
+          const value = cell.getValue();
+          if (value == null) return false;
+          return String(value).toLowerCase().includes(term);
+        });
+      }
+      return true;
+    };
+  }
+
+  const table = useReactTable(tableOpts);
 
   // ---- derived values -----------------------------------------------------
   const isAllPageRowsSelected = table.getIsAllPageRowsSelected();
@@ -212,12 +363,36 @@ export default function useDataTable<TData extends RowData>(
       ? "partial"
       : "none";
 
-  const selectedCount = Object.keys(rowSelection).length;
+  const selectedRowIds = useMemo(
+    () => Object.keys(rowSelection),
+    [rowSelection]
+  );
+  const selectedCount = selectedRowIds.length;
   const totalPages = Math.max(1, table.getPageCount());
   const currentPage = pagination.pageIndex + 1;
-  const totalItems = data.length;
+  const hasActiveFilter =
+    !isServerSide &&
+    (globalFilter.selectedIds != null || !!globalFilter.searchTerm);
+  const totalItems = isServerSide
+    ? serverSide!.totalItems
+    : hasActiveFilter
+      ? table.getPrePaginationRowModel().rows.length
+      : data.length;
   const isPaginated = isFinite(pagination.pageSize);
 
+  // ---- selection change callback ------------------------------------------
+  const isFirstRenderRef = useRef(true);
+  const onSelectionChangeRef = useRef(onSelectionChange);
+  onSelectionChangeRef.current = onSelectionChange;
+
+  useEffect(() => {
+    if (isFirstRenderRef.current) {
+      isFirstRenderRef.current = false;
+      return;
+    }
+    onSelectionChangeRef.current?.(selectedRowIds);
+  }, [selectedRowIds]);
+
   // ---- actions ------------------------------------------------------------
   const setPage = (page: number) => {
     const clamped = Math.max(1, Math.min(page, totalPages));
@@ -232,6 +407,26 @@ export default function useDataTable<TData extends RowData>(
     table.toggleAllPageRowsSelected(selected);
   };
 
+  // ---- view mode (filter to selected rows) --------------------------------
+  const isViewingSelected = globalFilter.selectedIds != null;
+
+  const enterViewMode = () => {
+    if (isServerSide) return;
+    if (selectedRowIds.length > 0) {
+      setGlobalFilter((prev) => ({
+        ...prev,
+        selectedIds: new Set(selectedRowIds),
+      }));
+      setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+    }
+  };
+
+  const exitViewMode = () => {
+    if (isServerSide) return;
+    setGlobalFilter((prev) => ({ ...prev, selectedIds: null }));
+    setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+  };
+
   return {
     table,
     currentPage,
@@ -242,8 +437,12 @@ export default function useDataTable<TData extends RowData>(
     isPaginated,
     selectionState,
     selectedCount,
+    selectedRowIds,
     isAllPageRowsSelected,
     clearSelection,
     toggleAllPageRowsSelected,
+    isViewingSelected,
+    enterViewMode,
+    exitViewMode,
   };
 }
diff --git a/web/src/refresh-components/table/hooks/useDraggableRows.ts b/web/src/refresh-components/table/hooks/useDraggableRows.ts
index c646048a325..52e5dcb8ccd 100644
--- a/web/src/refresh-components/table/hooks/useDraggableRows.ts
+++ b/web/src/refresh-components/table/hooks/useDraggableRows.ts
@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useCallback, useMemo } from "react";
+import { useState, useCallback, useMemo, useRef } from "react";
 import {
   useSensors,
   useSensor,
@@ -49,6 +49,8 @@ interface DraggableRowsReturn {
   isDragging: boolean;
   /** Whether DnD is enabled. */
   isEnabled: boolean;
+  /** Ref that is `true` briefly after a drag ends, used to suppress the trailing click. */
+  wasDraggingRef: React.RefObject<boolean>;
 }
 
 // ---------------------------------------------------------------------------
@@ -75,6 +77,7 @@ export default function useDraggableRows<TData>(
   const { data, getRowId, enabled = true, onReorder } = options;
 
   const [activeId, setActiveId] = useState<string | null>(null);
+  const wasDraggingRef = useRef(false);
 
   const sensors = useSensors(
     useSensor(PointerSensor, {
@@ -108,6 +111,11 @@ export default function useDraggableRows<TData>(
   const handleDragEnd = useCallback(
     (event: DragEndEvent) => {
       setActiveId(null);
+      // Suppress the trailing click event that the browser fires after pointerup.
+      wasDraggingRef.current = true;
+      requestAnimationFrame(() => {
+        wasDraggingRef.current = false;
+      });
       if (event.activatorEvent instanceof PointerEvent) {
         (document.activeElement as HTMLElement)?.blur();
       }
@@ -152,5 +160,6 @@ export default function useDraggableRows<TData>(
     activeId,
     isDragging: activeId !== null,
     isEnabled: enabled,
+    wasDraggingRef,
   };
 }
diff --git a/web/src/refresh-components/table/types.ts b/web/src/refresh-components/table/types.ts
index d464371b404..f245dbb8547 100644
--- a/web/src/refresh-components/table/types.ts
+++ b/web/src/refresh-components/table/types.ts
@@ -99,13 +99,29 @@ export type OnyxColumnDef<TData> =
   | OnyxDisplayColumn<TData>
   | OnyxActionsColumn<TData>;
 
+// ---------------------------------------------------------------------------
+// Server-side pagination / sorting / search
+// ---------------------------------------------------------------------------
+
+/** Server-side configuration for DataTable. */
+export interface ServerSideConfig {
+  /** Total row count from the server. Used to compute page count. */
+  totalItems: number;
+  /** Whether data is currently being fetched. Shows loading state. */
+  isLoading?: boolean;
+  /** Fired when sorting state changes. */
+  onSortingChange: (sorting: SortingState) => void;
+  /** Fired when pagination changes (including page resets from sort/search). */
+  onPaginationChange: (pageIndex: number, pageSize: number) => void;
+  /** Fired when searchTerm changes. */
+  onSearchTermChange: (searchTerm: string) => void;
+}
+
 // ---------------------------------------------------------------------------
 // DataTable props
 // ---------------------------------------------------------------------------
 
-export interface DataTableDraggableConfig<TData> {
-  /** Extract a unique string ID from each row. */
-  getRowId: (row: TData) => string;
+export interface DataTableDraggableConfig {
   /** Called after a successful reorder with the new ID order and changed positions. */
   onReorder: (
     ids: string[],
@@ -117,8 +133,8 @@ export interface DataTableFooterSelection {
   mode: "selection";
   /** Whether the table supports selecting multiple rows. @default true */
   multiSelect?: boolean;
-  /** Handler for the "View" button. */
-  onView?: () => void;
+  /** When true, shows a "View" button that filters the table to only selected rows. @default false */
+  showView?: boolean;
   /** Handler for the "Clear" button. When omitted, the default clearSelection is used. */
   onClear?: () => void;
 }
@@ -136,6 +152,8 @@ export interface DataTableProps<TData> {
   data: TData[];
   /** Column definitions created via `createTableColumns()`. */
   columns: OnyxColumnDef<TData>[];
+  /** Extract a unique string ID from each row. Used for stable row identity. */
+  getRowId: (row: TData) => string;
   /** Rows per page. Set `Infinity` to disable pagination. @default 10 */
   pageSize?: number;
   /** Initial sorting state. */
@@ -143,13 +161,18 @@ export interface DataTableProps<TData> {
   /** Initial column visibility state. */
   initialColumnVisibility?: VisibilityState;
   /** Enable drag-and-drop row reordering. */
-  draggable?: DataTableDraggableConfig<TData>;
+  draggable?: DataTableDraggableConfig;
   /** Footer configuration. */
   footer?: DataTableFooterConfig;
   /** Table size variant. @default "regular" */
   size?: TableSize;
+  /** Called whenever the set of selected row IDs changes. Receives IDs produced by `getRowId`. */
+  onSelectionChange?: (selectedIds: string[]) => void;
   /** Called when a row is clicked (replaces the default selection toggle). */
   onRowClick?: (row: TData) => void;
+  /** Search term for global text filtering. When provided, rows are filtered
+   *  to those containing the term in any accessor column value (case-insensitive). */
+  searchTerm?: string;
   /**
    * Max height of the scrollable table area. When set, the table body scrolls
    * vertically while the header stays pinned at the top.
@@ -159,4 +182,12 @@ export interface DataTableProps<TData> {
   /** Background color for the sticky header row, preventing rows from showing
    *  through when scrolling. Accepts any CSS color value. */
   headerBackground?: string;
+  /**
+   * Enable server-side mode. When provided:
+   * - TanStack uses manualPagination/manualSorting/manualFiltering
+   * - `data` should contain only the current page's rows
+   * - Dragging is automatically disabled
+   * - Fires separate callbacks for sorting, pagination, and search changes
+   */
+  serverSide?: ServerSideConfig;
 }

From b45277a8b07279473b580dc3f13560c2f57c280e Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Fri, 6 Mar 2026 13:04:32 +0530
Subject: [PATCH 143/267] fix(tools): clean up orphaned OAuthConfig and
 preserve settings on OpenAPI tool update (#9086)

---
 backend/onyx/db/tools.py                      | 34 +++++++-
 .../tools/test_oauth_config_crud.py           | 81 +++++++++++++++++++
 .../actions/modals/AddOpenAPIActionModal.tsx  |  6 ++
 3 files changed, 119 insertions(+), 2 deletions(-)

diff --git a/backend/onyx/db/tools.py b/backend/onyx/db/tools.py
index 04640d0c8b6..e51409bb49f 100644
--- a/backend/onyx/db/tools.py
+++ b/backend/onyx/db/tools.py
@@ -13,6 +13,7 @@
 from onyx.db.constants import UnsetType
 from onyx.db.enums import MCPServerStatus
 from onyx.db.models import MCPServer
+from onyx.db.models import OAuthConfig
 from onyx.db.models import Tool
 from onyx.db.models import ToolCall
 from onyx.server.features.tool.models import Header
@@ -161,10 +162,26 @@ def update_tool(
         ]
     if passthrough_auth is not None:
         tool.passthrough_auth = passthrough_auth
+    old_oauth_config_id = tool.oauth_config_id
     if not isinstance(oauth_config_id, UnsetType):
         tool.oauth_config_id = oauth_config_id
-    db_session.commit()
+        db_session.flush()
+
+    # Clean up orphaned OAuthConfig if the oauth_config_id was changed
+    if (
+        old_oauth_config_id is not None
+        and not isinstance(oauth_config_id, UnsetType)
+        and old_oauth_config_id != oauth_config_id
+    ):
+        other_tools = db_session.scalars(
+            select(Tool).where(Tool.oauth_config_id == old_oauth_config_id)
+        ).all()
+        if not other_tools:
+            oauth_config = db_session.get(OAuthConfig, old_oauth_config_id)
+            if oauth_config:
+                db_session.delete(oauth_config)
 
+    db_session.commit()
     return tool
 
 
@@ -173,8 +190,21 @@ def delete_tool__no_commit(tool_id: int, db_session: Session) -> None:
     if tool is None:
         raise ValueError(f"Tool with ID {tool_id} does not exist")
 
+    oauth_config_id = tool.oauth_config_id
+
     db_session.delete(tool)
-    db_session.flush()  # Don't commit yet, let caller decide when to commit
+    db_session.flush()
+
+    # Clean up orphaned OAuthConfig if no other tools reference it
+    if oauth_config_id is not None:
+        other_tools = db_session.scalars(
+            select(Tool).where(Tool.oauth_config_id == oauth_config_id)
+        ).all()
+        if not other_tools:
+            oauth_config = db_session.get(OAuthConfig, oauth_config_id)
+            if oauth_config:
+                db_session.delete(oauth_config)
+                db_session.flush()
 
 
 def get_builtin_tool(
diff --git a/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py b/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py
index 77917968059..094f13d45bb 100644
--- a/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py
+++ b/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py
@@ -21,6 +21,8 @@
 from onyx.db.oauth_config import get_user_oauth_token
 from onyx.db.oauth_config import update_oauth_config
 from onyx.db.oauth_config import upsert_user_oauth_token
+from onyx.db.tools import delete_tool__no_commit
+from onyx.db.tools import update_tool
 from tests.external_dependency_unit.conftest import create_test_user
 
 
@@ -312,6 +314,85 @@ def test_delete_oauth_config_sets_tool_reference_to_null(
         # Tool should still exist but oauth_config_id should be NULL
         assert tool.oauth_config_id is None
 
+    def test_update_tool_cleans_up_orphaned_oauth_config(
+        self, db_session: Session
+    ) -> None:
+        """Test that changing a tool's oauth_config_id deletes the old config if no other tool uses it."""
+        old_config = _create_test_oauth_config(db_session)
+        new_config = _create_test_oauth_config(db_session)
+        tool = _create_test_tool_with_oauth(db_session, old_config)
+        old_config_id = old_config.id
+
+        update_tool(
+            tool_id=tool.id,
+            name=None,
+            description=None,
+            openapi_schema=None,
+            custom_headers=None,
+            user_id=None,
+            db_session=db_session,
+            passthrough_auth=None,
+            oauth_config_id=new_config.id,
+        )
+
+        assert tool.oauth_config_id == new_config.id
+        assert get_oauth_config(old_config_id, db_session) is None
+
+    def test_delete_tool_cleans_up_orphaned_oauth_config(
+        self, db_session: Session
+    ) -> None:
+        """Test that deleting the last tool referencing an OAuthConfig also deletes the config."""
+        config = _create_test_oauth_config(db_session)
+        tool = _create_test_tool_with_oauth(db_session, config)
+        config_id = config.id
+
+        delete_tool__no_commit(tool.id, db_session)
+        db_session.commit()
+
+        assert get_oauth_config(config_id, db_session) is None
+
+    def test_update_tool_preserves_shared_oauth_config(
+        self, db_session: Session
+    ) -> None:
+        """Test that updating one tool's oauth_config_id preserves the config when another tool still uses it."""
+        shared_config = _create_test_oauth_config(db_session)
+        new_config = _create_test_oauth_config(db_session)
+        tool_a = _create_test_tool_with_oauth(db_session, shared_config)
+        tool_b = _create_test_tool_with_oauth(db_session, shared_config)
+        shared_config_id = shared_config.id
+
+        # Move tool_a to a new config; tool_b still references shared_config
+        update_tool(
+            tool_id=tool_a.id,
+            name=None,
+            description=None,
+            openapi_schema=None,
+            custom_headers=None,
+            user_id=None,
+            db_session=db_session,
+            passthrough_auth=None,
+            oauth_config_id=new_config.id,
+        )
+
+        assert tool_a.oauth_config_id == new_config.id
+        assert tool_b.oauth_config_id == shared_config_id
+        assert get_oauth_config(shared_config_id, db_session) is not None
+
+    def test_delete_tool_preserves_shared_oauth_config(
+        self, db_session: Session
+    ) -> None:
+        """Test that deleting one tool preserves the config when another tool still uses it."""
+        shared_config = _create_test_oauth_config(db_session)
+        tool_a = _create_test_tool_with_oauth(db_session, shared_config)
+        tool_b = _create_test_tool_with_oauth(db_session, shared_config)
+        shared_config_id = shared_config.id
+
+        delete_tool__no_commit(tool_a.id, db_session)
+        db_session.commit()
+
+        assert tool_b.oauth_config_id == shared_config_id
+        assert get_oauth_config(shared_config_id, db_session) is not None
+
 
 class TestOAuthUserTokenCRUD:
     """Tests for OAuth user token CRUD operations"""
diff --git a/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx b/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
index 5d6e320df99..8c9ae477ffa 100644
--- a/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
+++ b/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
@@ -457,8 +457,14 @@ export default function AddOpenAPIActionModal({
           name?: string;
           description?: string;
           definition: Record<string, any>;
+          custom_headers?: { key: string; value: string }[];
+          passthrough_auth?: boolean;
+          oauth_config_id?: number | null;
         } = {
           definition: parsedDefinition,
+          custom_headers: existingTool.custom_headers,
+          passthrough_auth: existingTool.passthrough_auth,
+          oauth_config_id: existingTool.oauth_config_id,
         };
 
         if (derivedName) {

From b015a37cea9e3e06edc3fab1fc5a37c11e4dc1c3 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Fri, 6 Mar 2026 00:20:33 -0800
Subject: [PATCH 144/267] feat: Docx preview variant (#9060)

---
 .../PreviewModal/variants/docxVariant.tsx     | 174 ++++++++++++++++++
 .../modals/PreviewModal/variants/index.ts     |   2 +
 web/tests/e2e/chat/file_preview_modal.spec.ts |  94 ++++++++++
 web/tests/e2e/fixtures/three_images.docx      | Bin 0 -> 48578 bytes
 4 files changed, 270 insertions(+)
 create mode 100644 web/src/sections/modals/PreviewModal/variants/docxVariant.tsx
 create mode 100644 web/tests/e2e/fixtures/three_images.docx

diff --git a/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx b/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx
new file mode 100644
index 00000000000..2cb8a5fc983
--- /dev/null
+++ b/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx
@@ -0,0 +1,174 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { renderAsync } from "docx-preview";
+import ScrollIndicatorDiv from "@/refresh-components/ScrollIndicatorDiv";
+import Text from "@/refresh-components/texts/Text";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
+import { Section } from "@/layouts/general-layouts";
+import { PreviewContext } from "@/sections/modals/PreviewModal/interfaces";
+import { PreviewVariant } from "@/sections/modals/PreviewModal/interfaces";
+import {
+  CopyButton,
+  DownloadButton,
+} from "@/sections/modals/PreviewModal/variants/shared";
+
+const DOCX_MIMES = [
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/msword",
+];
+
+function isLegacyDoc(fileName: string): boolean {
+  const lower = fileName.toLowerCase();
+  return lower.endsWith(".doc") && !lower.endsWith(".docx");
+}
+
+interface DocxLoadResult {
+  plainText: string;
+  wordCount: number;
+}
+
+interface DocxPreviewProps {
+  fileUrl: string;
+  onLoad: (result: DocxLoadResult) => void;
+}
+
+function DocxPreview({ fileUrl, onLoad }: DocxPreviewProps) {
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const styleRef = useRef<HTMLDivElement>(null);
+  const onLoadRef = useRef(onLoad);
+  onLoadRef.current = onLoad;
+
+  useEffect(() => {
+    async function loadDocument() {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const response = await fetch(fileUrl);
+        if (!response.ok) {
+          throw new Error(`Failed to fetch document: ${response.status}`);
+        }
+        const buffer = await response.arrayBuffer();
+
+        // Render the DOCX with full layout fidelity
+        if (bodyRef.current && styleRef.current) {
+          bodyRef.current.innerHTML = "";
+          styleRef.current.innerHTML = "";
+
+          await renderAsync(buffer, bodyRef.current, styleRef.current, {
+            className: "docx",
+            inWrapper: false,
+            ignoreWidth: false,
+            ignoreHeight: false,
+            ignoreFonts: false,
+            breakPages: true,
+            useBase64URL: true,
+            renderHeaders: true,
+            renderFooters: true,
+            renderFootnotes: true,
+            renderEndnotes: true,
+          });
+        }
+
+        // Extract plain text from the rendered DOM
+        const text = bodyRef.current?.innerText ?? "";
+        const words = text
+          .split(/\s+/)
+          .filter((w: string) => w.length > 0).length;
+
+        onLoadRef.current({ plainText: text, wordCount: words });
+      } catch {
+        setError(
+          "Could not preview this document. Download the file to view it."
+        );
+      } finally {
+        setIsLoading(false);
+      }
+    }
+    loadDocument();
+  }, [fileUrl]);
+
+  if (error) {
+    return (
+      <Section justifyContent="center" alignItems="center" padding={1.5}>
+        <Text text03 mainUiBody>
+          {error}
+        </Text>
+      </Section>
+    );
+  }
+
+  return (
+    <ScrollIndicatorDiv
+      className="flex-1 min-h-0 bg-background-tint-00"
+      variant="shadow"
+    >
+      {isLoading && (
+        <Section>
+          <SimpleLoader className="h-8 w-8" />
+        </Section>
+      )}
+      {/* Style container for docx-preview generated styles */}
+      <div ref={styleRef} />
+      {/* Body container where docx-preview renders the document */}
+      <div ref={bodyRef} className="docx-host px-32 pb-16" />
+    </ScrollIndicatorDiv>
+  );
+}
+
+// Store parsed result outside the variant so footer can access it
+let lastDocxResult: DocxLoadResult | null = null;
+
+export const docxVariant: PreviewVariant = {
+  matches: (name, mime) => {
+    if (DOCX_MIMES.some((m) => mime === m)) return true;
+    const lower = (name || "").toLowerCase();
+    return lower.endsWith(".docx") || lower.endsWith(".doc");
+  },
+  width: "lg",
+  height: "full",
+  needsTextContent: false,
+  headerDescription: () => {
+    if (lastDocxResult) {
+      const count = lastDocxResult.wordCount;
+      return `Word Document • ${count.toLocaleString()} ${
+        count === 1 ? "word" : "words"
+      }`;
+    }
+    return "Word Document";
+  },
+
+  renderContent: (ctx: PreviewContext) => {
+    if (isLegacyDoc(ctx.fileName)) {
+      lastDocxResult = null;
+      return (
+        <Section justifyContent="center" alignItems="center" padding={1.5}>
+          <Text text03 mainUiBody>
+            Legacy .doc format cannot be previewed. Download the file to view
+            it.
+          </Text>
+        </Section>
+      );
+    }
+    return (
+      <DocxPreview
+        fileUrl={ctx.fileUrl}
+        onLoad={(result) => {
+          lastDocxResult = result;
+        }}
+      />
+    );
+  },
+
+  renderFooterLeft: () => null,
+  renderFooterRight: (ctx: PreviewContext) => (
+    <Section flexDirection="row" width="fit">
+      {lastDocxResult && (
+        <CopyButton getText={() => lastDocxResult?.plainText ?? ""} />
+      )}
+      <DownloadButton fileUrl={ctx.fileUrl} fileName={ctx.fileName} />
+    </Section>
+  ),
+};
diff --git a/web/src/sections/modals/PreviewModal/variants/index.ts b/web/src/sections/modals/PreviewModal/variants/index.ts
index 14e22c652e9..877f00bf458 100644
--- a/web/src/sections/modals/PreviewModal/variants/index.ts
+++ b/web/src/sections/modals/PreviewModal/variants/index.ts
@@ -6,6 +6,7 @@ import { csvVariant } from "@/sections/modals/PreviewModal/variants/csvVariant";
 import { markdownVariant } from "@/sections/modals/PreviewModal/variants/markdownVariant";
 import { dataVariant } from "@/sections/modals/PreviewModal/variants/dataVariant";
 import { unsupportedVariant } from "@/sections/modals/PreviewModal/variants/unsupportedVariant";
+import { docxVariant } from "@/sections/modals/PreviewModal/variants/docxVariant";
 
 // Note: Order does matter for the order that filters that are hit
 const PREVIEW_VARIANTS: PreviewVariant[] = [
@@ -15,6 +16,7 @@ const PREVIEW_VARIANTS: PreviewVariant[] = [
   csvVariant,
   dataVariant,
   markdownVariant,
+  docxVariant,
 ];
 
 export function resolveVariant(
diff --git a/web/tests/e2e/chat/file_preview_modal.spec.ts b/web/tests/e2e/chat/file_preview_modal.spec.ts
index 9db6dce2bd3..f0d942fd9b5 100644
--- a/web/tests/e2e/chat/file_preview_modal.spec.ts
+++ b/web/tests/e2e/chat/file_preview_modal.spec.ts
@@ -1,5 +1,7 @@
 import { test, expect, Page } from "@playwright/test";
 import { loginAsRandomUser } from "../utils/auth";
+import * as fs from "fs";
+import * as path from "path";
 
 /**
  * Builds a newline-delimited JSON stream body matching the packet
@@ -234,4 +236,96 @@ test.describe("File preview modal from chat file links", () => {
 
     expect(download.suggestedFilename()).toContain("data.csv");
   });
+
+  test("clicking a .docx file link opens the preview modal and renders content", async ({
+    page,
+  }) => {
+    const mockContent = `Here is your document: [report.docx](/api/chat/file/${MOCK_FILE_ID})`;
+
+    // Serve a real .docx fixture so docx-preview can parse it
+    const docxBuffer = fs.readFileSync(
+      path.join(__dirname, "../fixtures/three_images.docx")
+    );
+
+    await page.route(`**/api/chat/file/${MOCK_FILE_ID}`, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType:
+          "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        body: docxBuffer,
+      });
+    });
+
+    await sendMessageWithMockResponse(
+      page,
+      "Give me the document",
+      mockContent
+    );
+
+    const aiMessage = page.getByTestId("onyx-ai-message").last();
+    const fileLink = aiMessage.locator("a").filter({ hasText: "report.docx" });
+    await expect(fileLink).toBeVisible({ timeout: 5000 });
+    await fileLink.click();
+
+    const modal = page.getByRole("dialog");
+    await expect(modal).toBeVisible({ timeout: 5000 });
+
+    // Verify the file name is shown in the header
+    await expect(modal.getByText("report.docx")).toBeVisible();
+
+    // Verify the header describes it as a Word Document
+    await expect(
+      modal
+        .locator("div")
+        .filter({ hasText: /Word Document/ })
+        .first()
+    ).toBeVisible();
+
+    // Verify docx-preview rendered content into the body container
+    await expect(modal.locator(".docx-host")).toBeVisible({ timeout: 10000 });
+
+    // Verify the download button exists
+    await expect(modal.locator("a[download]")).toBeVisible();
+  });
+
+  test("clicking a legacy .doc file link shows unsupported message", async ({
+    page,
+  }) => {
+    const mockContent = `Here is your document: [old_report.doc](/api/chat/file/${MOCK_FILE_ID})`;
+
+    await page.route(`**/api/chat/file/${MOCK_FILE_ID}`, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/msword",
+        body: "fake binary content",
+      });
+    });
+
+    await sendMessageWithMockResponse(
+      page,
+      "Give me the old document",
+      mockContent
+    );
+
+    const aiMessage = page.getByTestId("onyx-ai-message").last();
+    const fileLink = aiMessage
+      .locator("a")
+      .filter({ hasText: "old_report.doc" });
+    await expect(fileLink).toBeVisible({ timeout: 5000 });
+    await fileLink.click();
+
+    const modal = page.getByRole("dialog");
+    await expect(modal).toBeVisible({ timeout: 5000 });
+
+    // Verify the file name is shown
+    await expect(modal.getByText("old_report.doc")).toBeVisible();
+
+    // Verify the legacy .doc message is shown
+    await expect(
+      modal.getByText(/Legacy .doc format cannot be previewed/)
+    ).toBeVisible();
+
+    // Verify download button is still available
+    await expect(modal.locator("a[download]")).toBeVisible();
+  });
 });
diff --git a/web/tests/e2e/fixtures/three_images.docx b/web/tests/e2e/fixtures/three_images.docx
new file mode 100644
index 0000000000000000000000000000000000000000..4f5f37f9f7aaaa527867dd9a926139dcd72f849d
GIT binary patch
literal 48578
zcmagFWmp~Awl<2p21|e-!QI{6-66Q^!kvY?27+sV;O_1cf(3`*PH<bed@J3%_wL^3
zoO}Ni4|9(3${1BOCsl>A95f6z1Ox;E#Bs@!?o)Bqk4#7ih$lD*2rTfZo*2Nv)!f0=
zP~FSX+(n<!)84KzSxIS|8DsFwH;OuyP<g8kK15T2hu-mH0<}qX6`M8c3)Lj{L9->H
zRmfrujb4j*l;xUFcP);k_k)?j4FqPRhnthSLKI5YWvu&XTT8m(XDW#>a(%K`4`n=p
zo-J2*=4=3z(U3{FTh|99p-|yQD7xB9NJ1@L;!1L0tQ=-xTdEv}5M`3-mku&Vb=Avn
zmNRTtyFZoPUj|0sO9SzY(k;6U@YOW4Z8K5Yg5J);aM8;g^+zGVt;?7pNYcrC#6z$0
z;*z`Pl^XnB1+T@sLCWQukU&ce-*L$3^;+OS(w_JUC^xDvTKTEt*);YC%nj{BfYe;~
zDx9O=vJGskmhEU_8J7YOLq=>;aG<A+QQPtR+EN1N*T5o_+)+)zzWx5@{m-*}l!6b7
z5kwyAPDup&w8A?|BN=7Y+NG=1Qlld-t<0}14{xOb0!W+l?vS4}4AH0b;zda?oQQz}
z{qtUgft+w%(0Ny@EH9cfhaL7JQ;g)eqlJ|(({V+Z>zn77E3bXO>?FyEjh&wDi=T#k
zkw3KME*!s8{zospDCLCjz&%`pf`C8<|1@+qw{u}){C%uU9G8V=!3a1Ll=wzb?9ikk
zUbti+exOh&*poJPTI2wfF8bNksUohgjoVAKf3|IEF`rpLut-;A7p!HXGZ*w_p;vpI
z=Axn9a0MX+u_KVwQ++E$$1WopM2048PI=2|p-Cc0w}v&SM^k?~B~m3SZb)k{jaCv;
znuK|c>`JZW=EpDtfCEU%H*rK2SGMlhc|_d_HMvR~1qdG|IAW@$E1I$3aTlV=IAL9j
z$?Q+Yl_j)h;kG@rD_iN6Uoaj7iz%rYc#>bkjd#2m;I?ewFP>`ImfB+=CmYxDp0IFR
z3s&)WoFqDCu1!7DZH!;^Ll~LT<2?Ikfg-|?)vUoM`xLl9nBW4L0Zf&h0gf(ArT}O2
z-=}(Z;;3RjGls;iuf(i^X5<wHf`kk$<YAPoG<M)(>kT`Hg578i=lJ?|p}lS%ojcJw
z-|&^A;3`*RGqh=FVkmL=r?Wt_C}bU+mt_;&mB$<jTAs?}kiN5?hnY)COJ39OJ<%%o
zC`dIq&@!1U`ttJ;ykrA)9PG1U6QtQKszqN8MAa}AmclfJ6RF$CP)T;NX?_I;5=ADF
zCDvn>HWv{=WMP(kfs9NUFqWS%fSFk=M+|n}w1aWSuhLc8I#|<V!C!7dU3RT$doaCZ
z@dv)wMGZNY8Z=Vf%QB~~fny~+aleN}L5E}$R!LX&XwhWdh&pj`c3Piwht@AgX%0t0
zOL_NY>ZGJXIOq$)ik|x#VBl-*@a*i?3WEzpfRL+M3tJ7=bJHj{RjM&CYxN7-u!n$U
zIAZqa+v^K!mdwvG*u^4QFfwh@)AU{A`3Lp>uTn4X776L@xGrGc9$KOq(9C#<y*%|@
z68y6-*UQUzN8rBL!9YM@{Jk&6j*fq{MSav^nHi(wkq$=RHOd-ZMCEN_(7ec$*eZTa
zVpj9)_Ybn4U|LzWfPVK8I6PrYph&)YzQ=~|j|(Ce@C}Mq8aSi(`QMbCR*@R3qlWjE
z$M-+Dz?8w3;%E+H>N^=uey^N^V?cCG*HW(f?(?DEWbA?n-qA&gZqoH9n($hKPf@#~
zqwkL=b76^N_u9LG^JL}5#kDjQW~Hcd=;vyya<7s}0S>8c(4kIBGAf!Rl<_kg%&1qn
zHT6=2B%T5Z0gF-R`Ir@q4YH3bsLt#cW}c<J9v=S;neY)2z2oH!%H06c4xVY@hA{94
zNYb%9`;>Ya0xzoJsGdZvu2d`HGWH~)TU%r}kB0;LS&TYnWST75#u(6hjhU+*xZ;%1
za#LT*mw+aBg9h`!C%X8AD^B}U3|{wrLQ+#YmVfPcz|}DqH%e0FCA2nV)aB0OUUm)E
zXJKo?r8Z1*zlkY9iQ3Vca@j4$3Q~cpAu95e_m3vT1azh}r&{~_Vhg(Zih8j)xg7YI
z?i8D$z*fjz02S<KTY<OAQtrB2#J5)X&lrps_AL7w_ih5nhaPa;z?OPMqSO;ayXTRZ
zQKG;WyY<v$!Evp1a=!2^JPjW^rBA5?%Q8Y=m83d5GMS#3h|Uo+@2?16=Rn8A|2#3O
zM8oQupdlav!Dq$q3)TbRY{mq>YTfL?OVsZ(<3w8@uuOvOw_Ys_98ojn8>yQwV^cVp
z*7#XuwUk2@R2v%w33>msdL7n(z`mK<_O{`a;^T%h_lggCU#o9>IrmRx`!wudBt(+X
z;;^6IVM*}b-M9hW1%-!9J{dE@D!}{LzyU0)8JlG&N80lHJ_ut_F3~2!eQl&g6cdxx
zHD;@LJ2m}n1ue2dG<`qjha;UEZd^Y1Wy*A-vZ+x!9X;nF4C+S;C9!g5>v0wAY_Z%(
zv~3o$(vpCYkB3Nl2ZvCa2kni#(DI=SdMp#iYsLzEX$trijneor^>N{PNf3c%Y8Uf5
zL|2uOoC@utxuSIj&Z{9SGsqmf!rDk`tZos@YEwpab|P^^Egp-NQB;$14~;{5R%ijm
zKPC?)aH`XZrD6)OShq;paEg^%x-CZw4Sko3LyL%4w!CUPr<^O%td6~`nzyR@gQ7Q-
zYBC5x@fJB!7CI)dP-W82dI+T#QP5-&+|D@f#x~q_N9@jYcl~jHa>=#tW7{X8?pdD)
zns|&3ig351@Dab7S{lkJ(6m)Lio|9%u1PKAysz?bD8rObX6{YT8>hLzvS~FGiOP2M
z7Z486aIdu9xc`yu#>Kw$wRZ<ZkQNUmeq+s?6T|qC>e|3DiHY4r2Y&$aO-qnAqYXAT
z7vs*=o}{S;E9=6>hDm5rKG&s6B42Pw2W>6&0bc=iE!rgf?cGC;S1g01?Q@Iz>&}W%
z>*8G4Vvov-dlfW&MzG|G2;#h^?1ezmpmJ{`CK3NCuhc8%SQHzFWftGoge32mxhSZL
zu5m^}7{!>m*~IB|o)%!BBX`A`xF_*<P)r$g{ixfnt}^6LuR5RGqd?NHQdjSYQt0fD
zQIm0;;S!+HM11nR%WI-FJelC1f!RH6b$-ttu&;a)i%Wc;Z6zg!Zc7lEgCGhR>M6dr
zs@ud<&s*FD6>@k}S5C=&!tK2|lctM%u^qLJ7RKNG={g+*u`nG(#T!v!wink$?-WZM
zW&2beJ*s_2NJr!NBKI@u)pm3uMPD5&#MlQ(w@#HU$hQO2IHLzS5%Jmpo3Ja&pMe!R
zhSZqZLi+|*6l1))2yff#2O2{IK}^w<tM42dqu*}tfhTKh@e5{o)Gm5jC{v;*dxrQ#
zJ<KEMzAy!X+qchwm~OM5CTEs01Lte`=G8Y3t!Z7I_eDJ8KJ^qGK{Pdig)I(@Ur*ek
z8$qiUd>>i^RSKBDG{zIdy<f9R;jxPV1&O2!+Z3x@)m0U2jz4G+5xwxIJ;VI-A_vw)
zq-%oj{yN|-DB)ih`Ja22zhCNq>|;9TM3nlN-@<LQcbhDkQ!Suk|6pz@LDU*NXmmAf
z9%|J8iJt5az%e5e-u`m2=<(}TP$$!#_w}>FHQEqTWfZwmJvr2%D~-Aa`Q&K$sLUIk
z!m`3xO=WU|nh{@j7Qc|N{AE+ysh{6aRhlAf2X0a@Mr{&ii`rm!a~$o-C7RiBtZ94-
za1umPVk3S{Mp(kL6-ej|Sg4?FTeVtmGSzeJ2lZxK*dih+sbfTE!c}BSE5K?GEV~`<
z4eYo+&!v0Qq)lnM$fu{Y@0|@@j11ugf&}(^&PzIOzwNi6J>Wx3Wdqjh<a|R^r2F72
za^kQ%f55*B4{@w?l+i+Ujq%$NlNbH)<KzSqn6k`#`|dIUuBoYHx7>D_Z@NJ)QaHh2
zoTN~)au+G49WmR2_#T6c6jQWKNdrDX8L18Rs==+nWjOH}-DE=orju|Vv)>Sg=Z<Ww
z3*w*sfS;{ScVU8nc%uOef&N!NTwJ~E%w7Jt<?8DvZAsSob$90%7(VUTCxk!@PdGp%
zx)U1vbmr8au_>_49RK)%XBB^9=ubf^Ost`*p($IISjX3wgR4xltCgLkZvOn7>)&B_
z1~ep&%X~gv<?8Q7?P}FK(|jx*KfP)P0H5Fb^4;&9dg`9$q%1!>JfCI?Eer!*?&DwY
z9~aKziiMhww)OAsS1;OA=h`3lXMTa&!^5`^y`Jm%U+iDo)<T(pKZy-eiq9we_rp_n
zH%FI`n#-R@k1iX$R_wTng@`M9dpecEcp_rzUazg|b$uS^mPfrkqJ&-@wE_K@x9!_k
zdmztuC*|L)3~$4W7y5yXf<*n6z@?mF9~}qx1>-P9<Gj@I!y2Jeq3jo2L3wAX3+2t>
z@ZdW`rsYSlD35jjwG;Hw;gg3|KkgsTLZagWCt7RZZJ@mmucSW_P>|f8(tq$3`KEp5
z;`GR4blax>{;e!3yysGgX=m<9T;}6>GU(DX<2~2tbu`eK!TXuVo9rs7e4ED2tIO->
zijcTyyniUuOV>(QdvnET@*s=9efx@E*GIjxu4j<ggN14;QNPprDiiuTFinEkS32i}
z^mU;6zT2d?dUTF5rT)oPHyntWL4ohuj@Ws=hTonl1oVnlZ};Up!6L1WOt`K=hy5CU
z`i6HhydFKgx=QG|#?Vhk$d5aesiQsKJQUCW`DMS~!XM%JdiB{g<Kt5eaH(URU!c<C
z>@+-;>okW;>FCwZ;0!2GmFuwZiZ#%c64Uat`$TbnIUcZexAR)7+bx+x(AB0V$$3xn
z(8K9{%R)i*a<{za&b5!sQ+hG@+8#kjd1E5uWx!PMwwpi`DPs$vE^S*D)wmpevjm+*
zmAFrX*rY;mK-@2a#y4UH=;q#aJ$zz4NQGpeejgb$qYlj9AWP1rZV}(5LLyQI5B1Us
zsnh_#zwOaK57@kW)xR5)UW6BPP+WF1hr*{VY9l{cf9~L?7a~rnp7fYn(M?cg?F(-n
zPFk!)n{xp5|EgK{tHL(bu`zi{UD)4sa;d;AEP05>Ja2tmFuqc!u^C9WybFHq(65@G
zd_0+XaJ+ST9+tVe5;{2(%u<nT)SsI@@87$+`gPjxlEqFJ+DiCUEB3X2&$Emu>xx<<
z7<uW(?j42yIq`y0W^-z^4a|=STe_&4G6`;B%ukTwM8<`zT|Lk3Jr`sI(JQao=DvZC
zxg{|Gt$3zv>yCuxsL%y%UU$65lb7>f_H<c9L(`bPIHWfS(;~j_4XI^fzLIe#37%P$
zYkXS~e^Munmz7qLE_tK+nXNp8eixgLRE}Xm79mlwt-Hd1osj8H^LxiI_IyPLOJ)J2
zirqzS^K&VFnr;;R%j2qbCtuasK;cqU4GY`4%%ZmaRuV=bC$ubrY9<l|Oz*z96X{`6
zK?r@Lj;d(FPgfdJ1j{w-9z%qyq5$j=FEwGLpB*$L$o6X$*#*)Fs$_I;f*cc@14y!V
z^!egHVHD<cl!tCm03da^NA!d-6fbcxLXtXQzcGkj;wA(obifwo{hqV}PvZVH3A0HK
zfE4*xd{rYp1tScT7xK40nKh`tuus?%!KozRIGR6Fb-`$%VBCMC{z(N>N_A#K>iJ&;
zXDVdi5u`s<q;$ZVefb{}{{xlaeOZMYlnRdeyD)bGupU(muvhGc9R?C)hX0btK!QN!
zg^cir>e(cZMvRW%QU4w)bP;QqaBuIzGRWZ-*PSEjBGPp8JG+PU*YVdSo^Ma?kwuaS
zOr`pqP}0)m*|qN9ilw(`??Nc9J-g@BzBD{)_d*{dz^Iq<bT+v92y$!HcNp{$dFo#n
zbN^zs=y|1gH#C!5z3Ex~YfeyUe|K*rfAcPOT}ZzfBu*UXu*J9}ocuBFjN=pj>!Txz
z7=zcO5eEHA>3j0qH|RP}SX#AHrd8;$wUhg!wI##mCAa=(+8zz7$6X(*a;0?nnUdmH
z8{EBy*_Rj+8mYIPd_B0+;rF?y9y=9BhfObEM<4UqvDQrQ_K#lfPS>2MWKN|!_c1mL
zj`WI}_@qC(zN@Z@r+2S5!%KI04sMT*DLB?B3EQP@?VMY_Xz-8BCIf&zPhV1Uce{G1
zSxumgG=(0?)_KlA4by7iZk8I(X9hjL44fA!?T@mqxe`To$b8RKl^xC8cmhA%fu#|f
zKU0uFB4Vwd@!}IsmOGjE&k}#5MP4+!G{AN~H_}zHP%RXCNzCZ~gpu)bmjFr{1{FV(
z&IYhWc5WYXUM$}LiofXt@BDmlKD(zyjrWYcrr5#78SFT~P553mz2k24T}FBGd^y{C
z5-&%9HaMMjm+EDAAHOSL5kz?wfD3CL#e|8o_$6*zIzE^*nmoI=C3CqGeyL0YB9A_j
z!7ZZFfyx>9rVHZHs^e<=-Wn#!or)zN<`TdE(M!wuUDeKqmc(&43WAwrJ2Cx{!!SA;
z-pGEpH}EqugpgFNm<;xQL-TW%ocpg$n<8XY@UhGSR<o$+&es=tF{#>d@3Xo^FnYwc
zA$kEHtJYi6fZOi<0Lh0t1(_=AwdkRbO!%hWQ!NArJNTOt6C@AgK2tQagX7_X4*87Y
zE+}{zj`~(XzeJN9T7GB~<Ed_ZgofM4C%K#cd?cqPZ<yiUpGx^~_r`>`&$&TfCiyBE
zrJgdwLqzeGB<>Mqa3$P-y|~0waYSJFy_;;eTwC<Isz!gM`}xc^Cry!%L-)GG%QHu*
zNAB76ulU{P-PmZ5`{VZI)9EwaYvnSic;<d?)2Pq$*~y>x#PBXR9{KtSlBkaB%Fz#@
ztIGqx6n`XkDM4~u-rnLQsj|8sh98xYqL3nV!lWPlmdn+vbVcB+b1K|=o__i5Jr&UZ
zJ|AM+w&AWk;?g>>n%=MMU7PwL1*%;#{-P*r%^U|bmnK6hd$GQaBEd+O``H*`=;A&O
zkC#tYwTaP@XCbSR03pO)&cgi+X)y9uvt(>W(yoNR1oz!3zl_9s-H?qCoq~9B>IJe(
zmH<Zj?gyQAgwZaB=8>^-RLaSgIY&Z87+8IA4+kfzz;am!iiU`G!YW4ROu{OFiEAv8
zPRsr7o|U|%rUHFw#KvPyj`bjWbUoHw<ATjv#{wSn^qhIkbPTM>C}}SDt7$z0@FJ(9
zL@G%6e!hHzzF!5>mK&vFb7L<k2FL3qKLfK4IP8HXkQ6keX))|CUJ6*fx|AH}SSXi;
zm9SkxBPro>x+kMG5Fg!#pHu5T7Mr|P@*iS|xtb*CbaZg|2r98o?L-N$>u}~I@W!g{
zAZKo1MP8UC<GX_S__ZYLM&ksBcZ&wbW^aqPahXh`THRDY<UWzzPR;O>Q(al@#Dmfe
zqTF@ZF3Qsz5rsA7k2dZ;Wru?n6;jlO8k(jXhWl;HC@f~Pgkj$}!jD~2t*}O=?%cwW
zh($Cp{E^HjvI6c^2lb|Biu??g&O288;^I=;l;-ER6$_@=a9wPtIXj0en;E#$&}2!)
z$R-WO$S>-(s6IX9_;IJPU!Pw!pSX|TJhtyNTFg0q4cZjy>h9tghCP~wrb3xu;v_<~
z)6gC-3BtmOq|HD>Yoa}F)3{K35}?w<8nNX)FrJMe;+}E>)~+4Y6jcd;VAMA`3y>6D
z$;(POctbQ;s`PN89XrNPE45u?+?@Oxb@b1B+%dK1SaS_>GO*}UQwid6SsG_mi)6|}
zvADDv+28Y+*hFr=Z8HFVtU~j#cs``?{`#$;iddMm48@+A6G93p;*@u7nGc_;BKkHA
z{5W_H?)Lrm=mKenhxScRspoJ=Ei%s)+VVS%l~SyUDj6WZklWw_vWifAbN`-v*>=$7
ziL9u2H3X_HqyeJGWSi)k|CW}DjUN|ra{j6Hx{X@)aStEyaH7`FdmD`h%=-*_qEdQE
zhSJ!XNGQ3kq_+b?$GiC@4jw+NMK|i54CYW>(=p2G7U(7hTB#s@v}tdmaDptE9kT`1
z!~5jr?fdRnJI2oqTP3qmWaM;lZAOC+%@#60Cm0&Dqs{o5k(+G2ld=mbhQFo|lIb|F
zILU1RT$9+h3uj}n$k`OzjE3AfGi83d=-N!uBnlMk*A#~lbS=VIf67wHZ9d#R_NJCG
zp{K`ZIVo;)IoF)WTyb)7i=jsemD)(Cg*QW3f_Bzx@(|n=1SIX$eGFk)Ooq)Xv^EzZ
zKKd!a{%W*<_nBD122~(fT(qCsn(R9xm)T_4AT?j%V6q1BaoY_xcZm<uB7sjOVu2uE
z<91iuh2Zd&;oO%>_<s7uidhA9s+kxuP0w)kbFQ+9G10w~j7;H6zfT%h-!NKjxZcSp
zniFZb2u7&v`o)wNiwarphR`*_3bT2%fqeJwW=>Gcyz5B4dBa-$382`+EO3LTdN!^0
z>IB(RTjy4zs;f=#?9D?<gRnI~wOo%Rv>b=f6Kk$%hZt2Ak_0-j^o;?{A76Z&tXXrk
zMA{&E<lvW14&IO#=G;&W?vc%~Gh!ZCIH}3HQt(RUl_VV`-$g(c$xg>IaVrUxJsH3j
zd=30)8FT+~-XNIO9UaGKs-8D4f@Hteluqf#CY*~i*m|sF$m<Xw*s&CvqTQ|acn7G7
z7s8$eIA<oBkPK2mQxwNAr{otZiUfrv=|$!`_5E_xnW4A??d_UaJRbJDWx2Wz$?v8<
zFWfudUK?L6XbAP&`VO5TgztAlll4&%T2|iSYWZ%r59Cq84UMY{5mymEH1H5AeQ`QV
zuks{aT{6&x=r&6ZOC;cH@1bq2E1ScbR_k%7uN)U}rg^2MO&xVv@E_Ip|8}swng2Ds
zft1H$m2sqOwcduXVpD%rYf*SsEFsJrW#;9)8MN8qT-)~~Z@PKJ(QtO<)~9d3Fe*m0
z7UB>5X=j>`_iRu}G=NuMZ{~XP(WjM&gxsM~Tj1<AyxY5)h?@P;J>|2DEa}f(WsaLb
zsti*O;dmCdsf?Zli-cJQRXFm2qSY0~4OFZ8_5gZOdovwThaq9C$s4HkNs*+dtR>6i
zurd;f>!F`e!@_{$Y{!g(=2Fx4rvAsO60rk?4LKHRsA|HLADMA39RXZ<;}=kM2%VqI
z5j)>OD?X8gP&F^HpeojBJw~l5;}k}$Y4d^J9mIAT8@gO`x)-N(8c~t7%N^MB=1xkf
ztpx{RdG6MPthr`w!*)R0$KfSN9K_Pg9gGt?Zas8ynFL|+ximH(psI;P9aMS_abk7W
zqOZ&ocE&<k^5)cH{iq~gfV}2>*D^7-B|yy`sD&nXpfJp1&_nQJ&l6H7WbIpB$XW~}
zmBEI>6Czd?cY3*>1fT>-RUAOZa?Qz#*}2po$(CJ@^#hgP1EQ1XYRP2tk_bDihc2Ar
zx@en_X#>@>yr9e+)0=GcjW-*7mi7z%H^vRxiS$lMK-zDZs<+-Q3gUpS6GphKpUVtP
zZV;WY+oea2td+=08_E4|yl0%^@Xp~HcnpMbzi`#jf8jFik=eM9OI=q^&t-dz0hfq8
zc8wceNb+HW=#?63hE}O%=&ZbeuPpKBQZ;}rVH!?o)~L{FBbAIs<SA+4dfOSadu9BJ
zYat8AFj6SDIgng$?Oonshr|V~E^x9=1gJVyO%v<u7~Y7nKw<bOgT$0Lp3(FUp-=N#
zK5|k=-62ghO|$VVa7{r?SWu}_yDh@rMRUCA%>i56*8n^uPtjKP@PkcNP`-ZM`@|D<
zWv1!{d3;bG!8o(ZnTepIesOh)R-IwU+PH<Vff9pVTZH%TbfW{d!#~qI|CMg=SGtta
z@APYoLyeRAFCIxm2@7gRxs3U1SsL|~bPqA!G#jB%Im%4qq~0y+oh7Mu;bwd|v!h4$
zpCvobha^M1H6D`=R#y;qK(nl+(Is4#b9STgf&~Uho?il}X60NWh!{1P4k?yNmlR<^
zm)@dZRhT+RvA-D1buoH#g$7j~ebH2VFW$*hZlU+}`W;BM2N{<Ci$R9iwPR_<0x0ps
z(XKei+pDu-x&&`cI$F8fMu@O8(>kytN7vO26SP;6Vb3ySIV%Urgnb_3ZH+e7|MgI!
z(~OUNS*Bpk|2?M?VFN)o3~XyE&IF8esYv9vwALK|l7g2oURp>e9$_y8@FNly{GFDc
zc7l?$ejcxNPiHUZK->%}eDn7vF-uPM^4$ki3;7GV1zfB`t-Lv^sr#A53i;9!*tQnp
z=x%7%1_YB$?W!DN<uNf(hwTfgBt|Tf_8)Pj)f!u0PnG!bL$hdyzvd*`FU#k5wY?SZ
zUT~VpcAQzr_~ocbWDMmtGe1dxS?}=h&Ze>|f8FL97X&O<?<fG;Ca8!=@NYU%n0|if
zS4HgKIoQL!azz9*>Plu;a+MZJjfc??)?Ecx4YJUls+@DYLzz|8qg$52Hs)VO_I>4b
zzOf3p)=(Jr+aah_6^Qk#>Y66L&!QC6lEO?_01E2Egf!<Ce=zFZn+0kbsVieDdwv|D
z{_1|Oe$C9&)+!;a-=|l3sA5UwOba!=gp7^0bT6{-0UrmF<}L#Tj@MZHH<j5_PrZQq
z?bxw~LUh2tc|MT*#p8jm)P{f{6dN8D0Gp}C1q=jR5(Zl;_^gPYpC3LlHO>Ha_-4&U
zBc2!C;>(9T6HMh{&pgMx4|!p?>+vJf^&2xy2+~bS4cYP{Lm)qZ>w6v_N3(~rA_?Kk
zSk2O$Awexe%miOWtlaVfgl~LV%wSi<iqaB2LF2z1Km3OcO|9^sY?Gx0|6gq4B16a>
zkwUF;Sprggei}1iN0R00N~XEx)d<pp#gUV9Dlj|Qb6Jc~eUmmtAB>!kxwGfA1!ya%
z@(x<+GH-s_S<`yIC0u>V3CIX(Ho<DZk3aePA<srh7<D_aFEA<qf6ZTrl59LkY54=m
zlH#;GE9|?`T-YT=yXL?dEe-~#L_mWqi2bG&-v=sj^4F$|8#bhV;D?Rfb5mNV57>~u
z4s8ByPW_<7o)*fz<G|R#)g?NhEu>j@PK=tr6k$>E|E#9C2<5r&Fu_MDMLe^WvHzuc
z;VLjsPR|WqKKJJxzDQ>^p6uuMyX`w}p)P?;KGmg99(4C;`Rg5x^-{sPYCZfA3-e#i
z17uI8RY{UPtVwG?!HFg%TU1(`(pTByzwn@8FO&>G@uPF8li|;L2nDA{`qUy9i&p%X
zQ3NAy%w6~cLOi~1T}(P8bMjNwUnD$t)*jlLolj6}QQ+Q}l_7l~?1>h+9!1%>ZnU8G
z5|b&9w8Sk6ar0!&`b<8GRW>qW{t2oUTRep|XA%zi)Hqoi3tk+_>@eUPq&yJ@3rW)l
zrieRPtve(M3%*Y}crf4IBWDRPw@r?P60Sl>QNhjJEuFPFy&YHVSV$biMmN~6eS3Ft
zG+=_X<cJxwZ>m_Jk8F<=C=HqI3VsX2^MFDE=N{7DKw`q8Z_I+7ej;w+7dkf98n%SR
z^f+enZ3@-V)r94NC~ZX<YUcQx0fUbG#f~;nbYL#A9DPv&>i&%h%cd(*!&DJQ1ok&<
zs87&oq9i85^pXY`wP{r~Z==TCKh!f~B=Dut_?T(s>Y(tnLB=W4ORi%PXPU5hXY-U$
zMAH!Y4V$u@L!U<sV%Kf5r;Y7pWyA$@h6)!3pk={)3(OKm#DF$oxeSUJbPXL;HfzF4
zcMA+y8F{nBCiU<)jXHC)QLLS43e#ZUlc$?t--v<(CQ(PWRMCO^HT9bafB0sQh5Hsr
zFAEnDcoO{ySDe0xjy~)|efGBsdqeQ&7Vb^f-hWfc#+C6~<wM?Ym4ZEBm1GEDm3$Kl
z`@t+!1Z`Go2;xX3%f!NHh0nyoD93N1twjb*+WJhWS(hWn+JuFxnk}1-Z2yK>w5dSB
z-1$?}cF=^@1JuuT#rI6Xurd?H*o@A9Obxn*Nr{CTg(CVC2Dea{w?o;A$eU_il5M}H
zz#8|-TT9`tw!dgnVs7brFt1O{LO}wgVVuqO&bgt<oUTZ}EnmBIJL7sLgewv#S10<A
zj1W*&Fq!9qv3ly!9Ji4;9m$m)i02&j=&eC$3rA(Oz}bpzA7Ed~)kE1NW0$mOv7nkb
zW<qzBfq}I?z$$p5uq_`(R6W3LtHR)<xRtdE_ilg(G}FntU-4q1)~V0)dvJiKJtdKx
z(iU1z5^Eov<fQm#63_okvSS34a-~vD$YdpPTY{+u%<PSV0b5zxLsS#iStCETlesM!
z$|%6|^~)r|+{M5)t-Y*dDM;-@DM*Zc^55gOG%_Z2oHg(HoD}J|vG&;~%nmMOv+8l@
z-hk(q>=Q(?)Pz>)TqeE;6VQW#2_jtn7;pScULQHqv3EbfQyZg{HN&0sWth%sLRVex
zw~}TNI48wt*Xl7Iy7;A<+4v=re=9^eVLmH?-paE2Q(?{jRG7M-C1e-(WYIVkjf83=
zHJ%`sBDTw$K!uj<Ad=%wF`h;<SwKsK<c^@(Sj79y1Z$f(==sz&=IQj06?*dZ^u_#s
z{dx15KBiB4i#J5Ne%m4)IHgo2Q7t3|FatWf@qcBU<WeFqXV**e3*-?PzbTvAW_Bzx
zjdvr)Rdilpuo>e?sJ!Ks;<I;Pi2%AVU;BptvTe-fSQv_hVv*7)cw)OzK1)<0fx!#e
z;XR>5Pqt}9Mn3&+j2Q72O+18t#h!ZF;`sVq+}jclcImApgN?_rvLc5(7?9?i5n^+y
zGj2)`0Sy*?Zzx5pMNGPO!v?7V4}I^Oe&fi5&~{Y0pE22j{coT_ad2`^Bv~g*nX>g-
z%i$Cy&1G<MEhn7yH85+oNk)i_^dq37?*sX$=oet>l(%Sdzp1tVpiTi(^K1XH`<?(b
zIn=;h{XtEp2c}-G#r%Uhg)v>*_5Y&2rBDQKx1TQeMg<OG<&*&$s40$_H)h6&9j55L
zZ+03fmh@lKwF!I0I-IqGD8l;RkRp2!q%^$a^9!SZJA99x^2aWFyk)h(;xF=QF)(>1
zFUB9_v0uRCoByY8s7a5Gr@fSak>kM0eNS!c(`spp%}>BBN)i;#{T}Q4>-qBG6m{&R
zw>W!B<KXyiK|)LOP33Sm?(i`O1vka2Wv{ccJis^lEBk3b9IEQnL~RDqv+d!Doko0j
zJx911j~XZk?njhOwYm3UNjt$>SJ{c*UE*9wRVmfniA*SgF(0V*xQSMta>zCiMZN?t
z=<6DCAhixWb$XA5#l22-<@;%pnwc{LOgI%boht(L%tLa^L?@+dc`|QGBR(~bb#9TQ
zoHE|S%P_Tuo5w^e#py#Wj45^uh4Q;T`A#mBsRpzk?16h|moA2S@5zMoiq|_`Q1Y$o
z_PB_6=VWHcw{xsAB-s^u+>30woH8f{G~8x)QH!llZmp-Yisq_G@~ufSG}q`xRnL+o
z*ejvg74nv1pH>z$;ooB%{PJL83AW0pxQ`82bem=$X`#v}!c@Sj$u7+RWEIIMX}ovy
znz7bB@;h=Zwr-@0u)>chO1?#FnDv2wqi_VFfMxYUA#~d~r-B0G{jjPxMUp{j3*7#q
zmd&ofdKy_|Ej|NdXIZvKP;5P|rXi)j=9n=LBvu-?)_q3$kO7x(z1ykI05T{OpWzjr
zfyp3+!hLF<HO6e3DOl*VK>f>O8<zs(-@r20Gb#Cgn^Y*auDs=#&n}v)`j<()pQ>jJ
z3V)j9srYSjSm(FNGyDHPll|7ZkA7<$#nvFO$qZ(N-*3qVPR`$Umi$<BT0x;>i`?c8
zK1fwqVZ@ts5JK<S6|{br$5dAMRk*BYTGW}R!hofFj&4Y~i7L}l<KYD<X>|BXEjaEw
z=3AtRsIas(lZhqKx5CPc{glB6T0i=S7>GK8Jqv`XmFKSSQ4nV{1+h4(VV*n%3FuoG
z$ZLN<iX*`g3-3T+K#8LukoCaI<imK02=pS_R8sN9U>gyMX$Sr?ufO0wALy)5XbA8w
zxA6>I_G6F6+gO!CWWx4IhuywUtCv|b2@@zW#TN!IlT_ekGMz{m1%U~Swgvke4cSKE
z2X71>7|k=Vp390er?t;up3*?LQ-h<U$38f95c!<bGXxLGSg08<8qu=3XdJ}{!5~07
za051i5W*lJ0&)|!g+!)<gsFtdQ>65rQuqbbm?;8NP4~$qKcETYrjGLh>aenG6V^ef
zh~6OJ*7QS%vRxmZyoC#zf@7L7x(x_E0m?=VIRW|?6nLA_hwLbl=qX~LtaKivs}+H^
z4VyNMVPNFF#Gi)FQ%<4tH*qM5U~xkvA$U=SVv4xXlg8oC5$|sDK*$g@zYjbK-~&qy
z2-!%a?g+0C76i*gZLf67Y!KjuvI%>WAMlCma%tVWwxePWgq+q~7KYctH(T!s*(H{J
zF6z|1>?-)yrEkqVOu$O(y)crM6t^&%SwF>p74LE9ui~AUUk%y~<%ImD@T~#0;XZ=l
z8n-nZkur29FQmetn8**g-2{vhRUT@HRP{JSDAJ$;*$;6x`$y0nR=&$$RgnV5-*yo^
zBMELh(h4+c7?E^P;fl-SN?IH`1!rs8m8_Kydy>@zTxe|H;@R$0CFmp32)tk_{Ay}Q
z=dCB@D_B!C+nNuO4=4zFU*O=^yzU4uy&uxlu6MY+8oBNku+GzK#=U=956j9QC?ay=
zRTdt4y<JL#Gan%3`f(|aPh<Ng<fyU6tqZkjA6B!+AVJDE{*LHEz&=LU7k!X%ZH3rL
z6Z_ZD-A_RImx+6I6(rA(HNmshZZqkIgLvMDv2qdjZUOfUa0P+=k;=&5pJ3o%IaEuD
zaHqMxdaG+^Voy1lx96+JE@SO2h+=)lO*3S^5Lm|o%9;S-0`yFP`s`3FLWJ$wYb%-2
z#UR{t!$;J_+4NjmS;%-~Ce+!g-#lK(v~r!WI4s?0%-z3y1&N(*>Xw!FsF<ls1|>i>
z330e{1%3G15pi_O)%i9nUCiBk%Q}s{Pm-j!rdr%ON-|@UFphF#)xnY^d*LRjCE)?X
zjBYG5-qB;#&zc^GV@fz*1BOGHpsMtbirBg@ErL?K*+fi$?~Q;-fk%bznHC>r16hRv
zMM%e#jI<%Hu-@VfJcSG=n*o!-rMqwZkyeAcXL&EuQ{`BflbDtZxsj4)h!-n7h8}(&
z+tFhQ?PH+}_;la6-k_d+Uz(47-eLq_YWN3LQ%#Dup7tM96TVH_EyoD&MbdM7^78zE
zbN!+>_Zsm?%llNkRmXzeWloQMPZ<D~<q1I{t~4Ye3Kk*g9tM_fM*P4u;wb%&^fUM-
zPhEgZuHn&1G3L!Z&2OS}KVYNns_UNC+Qzaf;9Oy>8hVWBt&)B?))&Ul_lPJ+HrxgR
z^o8A?ppqK*t^Dop?&#I{%~WI6p%$C=zWe*|XvHuS-v8Aq&zD)#)V4J1PKmvR7ZIqx
z>c=O2qRW+hpL})}3^>Z<6uXYeSJ2s}Jk73WjNpw#Mafq(5fh{Sy!fpKhJvlhF7eH~
zb}HAh(0)u#9_9v`aH;%xRdN!_u#VlgZ?5=fBdD=Z=$+5`-a{T_=_)N~xshd@egl=;
zVpcu??HP5qq{@uvFs>vg{2v~KHT+-}ym@hTFckDP6n-%tu=;JOxP7RMYapGp$?h$P
zsl=fdy>>K`P&#NJ(tB<oqP<WF%6nrtEazL96<L5h%_VeD`YoLK>%L;nw;_n+`)d$T
zt*B#-TL|Ytp5gk-zOY|sfUIB1P?1S)=}deXfwg<ayL-(eyDpzyL3Ls+y1QiJX^V2=
zX-QZiSxoiwBhTLI<bofry^nkF0ys|?l%SPBv8A_pLAhOPfbX9d2=<GEa!X-_t_e%3
z@sxYf=N8q^+1wsfPJ0R$NK<z7D(ml0ah{a@K2~mM)p}?>+bPoCsYK-k87?3L?Xv<(
zk=K3;-Uw$d-JeJw9fH7l`j6lzd4{_`1tS5$g26m9@y@H-)%DRM&AOIXt8{l?9$IvJ
ztDmGT^q!?H{slaY46G#dt@sOg`YV}BhZQGW$wqPYZ6@n3Xz0Fl!_uY~T>$>@2v+@E
zjDr*BNj@8>zA9Z$cJvQm0J-LQdsd7htPt&;b=rrLjbYEuqy5#RpxbeDZ`wQK2A0tr
z+U!_J+Phyz&qeZHolZd7yL8=ivB|&(Z%DA~SOr)iwPNC3A|M%Hr~YV&{!|#Y8|^_8
z?7c*=O7q-h5DCbL^8}U#0GEV#8w7_84BY3-0x)Y2XRGxpRp%845%(1m#S~Zd?+Jk;
z*>C=8=KofkI)ZULwh2)cTn})4;r+^wV1?9)Q)%wJM*CBVIfvE0e8=l_#OsElKaPbT
z$G%Bi()OYR)Nn5LLQRsqjPRV_Cs^;wqT%nf8PLl`ij8G0vhTcM54H=1<fSM(RPFKf
z7G8bRSzPVsX&_iBf<YnXb%Y4rMCpWD_LXPva!*=KNu8*q%;+i@+6a}JOFcf$q3n%t
z=tHF}!j@u}A@Sv>+ue4MoD~)f6+)boBx9f>)TTbnW{N31qt7SE-g8c)mXo+38lOx&
z$O~MkLP(!$_$aQgV+H|EAI)idF19|+!E&PsR%L8>=5Dl{Bf7&3BgT1P#<i#HYI9OS
zAjCC0<^+MC_>(zc1Z@v37YI3a(3syq#ck87LB`>sf2QwoIyX*)8GeKr4xLOT<yLg;
zh<04LSp72SPzR`Y=Iy=6KxG9#>t}F|LGHb%TKq47cpq9YfQr(e0PWpagjC#X65I~(
zH;w}@Lo>#^u0h)z1ZLRWGZ*qJBrwCV%~Jjwo@(EZVF`ydil7LYh=!B{wl{*`BE;Py
z#v$KYQ2a{)ehlSl8Wsf1u%0%bU>5gGYl{d%904HyrRSpP^Aa+5T)8|fw}D;qM{qXh
z$e;9l#h8E63%=*uhGYVp=RzO$Th>Qe<X|fLAL;M7iH6ULn>{y}A+dkl?Sk4z3G%d`
zg5-63ws?dS3oF<^SR;ngx%p3?B+KW}HtN*TcV59&Dr@lAz@qE2&IJ$C+lNI>-(}9A
zXjmVI2N}91mft&Ej}{{QvfUr5>@T&xR-mw0J`v0TP1WmbKYNqH#4R}(v|2$Kg?tZ3
z=lH>A&zn5YaTF46F{?+sp_+@rh{xt_-^xPN(-PxCAm40{45G58M*ZNmg_C(F<%sVZ
zxG(e>gE}&Kc&d6M7V1#8-7SQ!Wr6`=Bb3~)QX~;-bIZM942uaglrqpGZ)DUO_c>hz
zhdZsO1_GConf8J?+ba!E8`8(0j)ld<<h{Ace4kFtQZ{cybg6S~ma~gm->!3~T?HgG
z7V*pozEzB!pbow7Cm;LVr17Dvo~uwmvUWN@9UUj<ZY`^)znY0TWeqEMy{wSO4b6|0
zt&lg>#Fh7*+;{6`uy8jqANbDO^L@zF*0^?|hxw7}4PBCSHP7xI)RA+mf#!TbU}W+y
zGgNlXz4*N(9-jhITT#2DWUpR3ep9ACi&ffMRxeG>W5B4X`8j9v!1n|lohlCv3n=Hj
z3i^dyPPUS9*-oo|DDCu~l7a887Ul&BskKM;OJPCTrshz!aupQ?6?QxEQk;*z!WIMy
zCgyK`aTKqte0FU8$V6w`(*w?_gTtr0`naAG?Yd~6o6NvJnHjlm!$YTL$vl|S!w(02
zh9Zvwm)?u8;o${G22n|ZB8gl3B~}(i(h|<}_bx!eJeA)yuJ;?Ow+ZvAG4n)UPJ2hy
zFYbi0ZWPMDsDiD*R7St4f_3O|q2v9!-u<@OI~IKZ!xT$wzH<6j_Oha4@m<F7_YKti
z$Yj#`x{nLZV=z0SV88V)7C$iQK>4W1OTiif;EKfRq@Te$^yGxpRdVwUe}^$i)z*>H
zN#}64G<BCqSqezeP8atcr{UtF_{g}>0bdS;#-al^($lBr<K)#+W}*(3Nx4sr<k~mO
zB>nkHa6>H32jMpPHQ~;%6f02DlMx-?cxh5X;QgbccY)jWRAa|nR^ZCkX&{-HuNs@X
zc<i7p{)k=*Py0LL=y!Z(=33V5iol`oL9P2^OW7>iSSFbj^l3~MSuWE$&EQicBw2!r
z^`cb!iS{#4-`ySS`S2Q2A(rd8%595Aplieiwo}2+$D+O%YcFMOFyEpgtNjbg7R@nl
z_gd@+=RMkP-gypEa{7p|4^hJG;0L}!mdo^TQ`JUAbr<MOpLBY#Un15@^xX@T<&{@^
zxcySdI(%3HLx2GxdwkPx<Vn(mnFEc28YBdkk-6VPx<Vs?x4p1p7kZUgw4Yt)<i%h;
z<rIRDIs=dx8f3^zgp~vHphRHrp$&pD=xe$Yjdsg8zla)nxd0e}<!+*(iJAcG5{R=a
zN#!rZ%3to+^!<X7j0f(pBK>k3#X?t5&GST!ZCOQNgOJ*UVHa*YKRH&}VA0;y8y(cX
zdwZpM6oNz{kUXsnxuzVMCn}UDdZpm}0EaX5;<_o#-dg^icE^Dl8VAYmEg~(3`VSad
z&p@ut<IkqMWtw05z9Dlz(xf%(QmIp0Uw;ZiI%gz?!2z$Vx(6#ixJodzO?`R<zlOAm
zcDa`%w12r&AcVm|pgn-XsfegR-Y?T!pdIrSsu=_{DwZhMJ@TXCZ0JoQ(q2Q+Hq>Od
z0F-;(Dc553xy+lmOaD@#?}_lI3YeTTN8Q*uXN_`O9De`r)*IhDG+ay0tNZsN(J{BQ
zzI^MUG*h1cT-0?+gYKoW8bVI%6D}N3Xy=S&`04E{!WxGWR@(|T6CSm<pwlxdPY5wb
zvEo_*Wr8)M(8cUprf9B|gzXdaJMr$I7x;s(0dQ~_0Bj`KGA=R6Gu3qznZ<w_k?cib
z`*vlY1Eb%!C-<a`iLKy=Tph9yqxJ$L+O0JG9t2c=dVJZm*nQG>csG5VPT;>$X+MM}
zb|zRCLaZapNCzf}W=o6MH!J%{_Y#j&UDclZc|g(3zK-FOhJxRXa}waPG*{urV&i*i
zcbFCgFL@3b7>!@{aen$2P~{&$NdE?^2LpY1F+Bx|A%TSIC8dpz6&dt)jN1eLK-kt1
z0N-1Dj5DPnL7F(9L`M|Av8x80g^(8tOMlTU%xlmp5hzrCb((%44gKw-kQpiKS6U}Q
z=+btdRpF1G{;l`#v>$&RcoXeZMPSQviWYr>@+BiDg%w3|`vBWmDS86Vi|3w0|I-1i
z54Tg%arIzYrb>(?61Wm;yrDmpj_0l%jU@_|>(E(au{Rz`5NR+}OR#84POxpjdH%;a
zK(GVLc?6ofruKwij>hb&RvX5c=p7Z0*fIj>9UY{hqup_@cmDtRKK}&#FS|xwK{GrY
z5D+faa1i+a{61gH+SN+J!ou9t_0LcB{q$1{B<oHd?{OLr2bFSCAV^0>{U+W(4H=AX
zU!>pM36_`7>St6X9?H@-gTK}n&JB3;EnfOt$O$lwM)+MqE1SzOTEyLp|BI(r*P~zS
zY9;5<?K;XU=iQz|D{zs&YCd<}|LV+e8$h+ba&i+5+TQZ2H|ToZo7_Fke7!$=eRw(Y
zXn)R~99`AFd<31gS68E-o#ozuKjB~NTo&MGFvM-|?yMkc%3R%>c>$njrg~&5<!Yjj
zdKhvo4|_})adSU)FP!Wdw=Po*?L~vmqF0|wTT@XDZJDCOuU_5Yf@LmmZTzgaZ{j$s
zN8Ow+XDlA;7ODIlgs8d~fnGk(oYq%vwT6Bl1*&iSi|p@HEr9<1uTA>?9yZ&{qke_m
z_l&K9XFz{1LBo#Hwj0la;#ZzmlTnwX;oOkS@aEKAZ~vA~kL6t#=l)F4sWr&^gllO&
zF-d7(l9rhJs>aYTJm+U#`10Vwj(-*E<;u(Ug%s1|FkiKU6Zgj3PYscyOr8#;fGb}r
zopZnBqYS%!pyttXH-HOJy)dt7Q~BKT;%rT)11J8IH&*3l%H4+RYSa26Lq0Dx{0#Wi
zv1W%yoSVca>;1$ivGeTzy0EHW$1mVO)VEtaxO@dnCE_7meyJ09&qu^d%>U~4#J5&)
z+umNi&ftz-K36^ROi|fg@kUH&Y`%TY&)K4N@x-!y?t>32?|ZpPp|5zX{`WP@mT2(h
z!*kE=S)f(J5shx9ob`3SiSg3=s_UIAljnP1=hl~-b>h0)be?M#mirfA?ek6l@z1{7
zGuBnd2eJi~$UrU4^-kOehubz!?e`957uMbK^G#-VYUPvV*z6OFLa!Iq&8}m(fJcQF
zMuU2fPh9ClG$@Cgt+yi|ZZ=!+DDdcoz;7|{>U^JSloUI<g|wB>ULJ=Ho65&Ibyn8b
zm5PgliBp)$i8bTnM?sH|oA-U7nM0@h*PN6i|Fe|%h3!`Y;=R|>!SL~AZ-3uBIe39H
zq5>hJl<HskSs&{R3j3d29?JKxsoG;|#Rvf9M-1=LvE_-;US8{0H(Lw7%L_2z{i^cg
zs%Ye-XxL*Wzyl0Z*bI}|Sc=caDa}r#m1HBT@Tm>D-(-f9sn*-KsO99Y3dfyUav^L#
zE}`b#0o{X%yK+~1Lcv1^8{nb0;32jfkdTiy;Y-*3rZfsich$}0=ueQnbZu77O?tZ_
z?(*RN$rk7r<1Q>$(P75@`Hj=0$BbA|=1a}GgX)c*>8KNeodi?0QuL~g79iGy8>pbO
zwz}S2KCJ6gkoa6V)W<X#9lkrWckk5N`RH~(Y*6+om&=1Vj<5vSgXq0mJhxx`tlt+-
z>_z`T0o`l9Q#|Kj2>7z|rG?%RwaO4`6(9LkTd-=)U_xN9_mgjGUz{3XSgke*4QaAJ
z=5wqge`K`@`Fr0Ss&{k*o1Tf0b(qa-5i7Jfj7^4jdt2HLO_N-cnJ2}~mZuu#^j!N)
z?sr6z4nGZJ94i@2TX}NzLe4DE(IdsaLz~adY4?0StfM!Ivhc%YmabPueoL-h3tKV5
zu==X|()BYNvH7m$jJ2cr26r_P4bz16^|5JbA;~OUwC&ER)3C~8lus~;5!Pq?q!21t
zspcz^Hrb*cYz3xW9n?IwhaON)e7Pz>B<NYI2ftU6-YC{lYH!0&osTt~rtE!sKlVx7
zm~n!;l*3T?n;OXtc|>ip6)5fsOb5vEI~}O`h^7E<xdA<haFITSfPVZ<+#cgtN92w3
z@1;!;Xlm-<37Vha36c}=L;`rCMzRIg@!t@H^9aol&lv>W6kET8{>uIx<T-8+Nmx|!
z8>Qhl{2wTP5BNLE|E}UKM>DKrTK-QcZuuz(NJ2R4W(c(45HJ|WKeYZ!(od*E2221r
z3=te=`>(JbfCKUdvqa->oK+}pl<D6%e-HSZ=Nicd*jc>~Yv8aq;IQA;&}^N{WggIO
zt}f#qLw8Ac^(ddJWs*7|fWEW-3_=Xeqaf(vBL-~E$w^wHlr7Y2qxyU2;aiyiy&yss
zpYr(0^6|~DB|-p{7~6HD*Zrr{@ZH_)?|rveF$6L~o}<7ucW(EGQ{GnJ*L~aRL)#mU
z%HeG;<YJFebi9{4&wGRuXP;lsE7@H*{MqemkG~kJ;G5dbqH?N;P_|ly+_sNUiDG8g
zmv#*l1(?m&$3X;5<<IfaW)&~3jGddH%Xq(EBl~j?qxU;Y*H6~9;~$;hM_h%fwVrZk
zP55G_KY`3!eV=(+yFEfpg(~Mq^=~#n{Uh<CN}2Z4err1c6Ehy4Q#no@L3{SOK=J#T
zv&mGx))moHvhOPkmFuZ~%WZc`gUyw{My3IJF5Ml#<qV<;|K*H0)6;mb(+lG1=Zz=&
zDxs)ico^cJe8)IvXL#WXTi)EOZ)bSk?Z=o2=4N9nnhEA)oB15giXj=fm-QZ7!PJw%
z>^(hLLVQ!og?9<^T_jELxiEVhVot&o*kFieor^o|z)`3lo8bNkV_ghLC<-jrLRC^C
z;};<HG?1~jBsuztx}<T6&bGl{7Iq~~mL=sEUT-Ow<x=Cy&m|Z&LwM{-I0H3T4Odo;
zSpr-S<Ygr;S+TV(Cn3@b_N>4h*zO8mJj00S6nUsd*z%i>)k1h}lf4p$9YDxYC-cn5
z>`m$-^RyETnhOmR*%X(wdiz7vOBZ#wRFYch5p6f}UU|Olt*ykf7*y4u7%Li1V7gjd
z>1gpyIEvcXy>en~8B&Ls)48V5l%PVd`UQJ9wgRZOsJ-89?n=>p>qJO!KQHs?d7C%e
z%TTGeYdeYmrS==DoAZ+I{nJytgka__@Jjc2X8U{HQ-hEJC!u^9<5SDh85a{Fg9AF?
zW|loYPUE6WY1nh473g!{vXW!+>8n$}m_tfpEkC8h7b3~@%ANgjo_)=w%ACoo3A{$w
zCrac);|3)j<<3#!W*%j>qne(r%kw5VN4E$}JSk?pOEdQg^!<n<ePb^A<EF9yN7!2c
z$FXEx!eX+RnVFd_W@s@pGlNAIGc(I#w3wNh87yX&#j<3<w%?nXo%j8_`$vbWLlNEQ
zo^!G~>t<GE-r@>pZvtnBDvlhRX?s&Q7!_nTz-M!O=Sl9*!*ah-goT4!A7GruQ1-w`
zmSB`zCt_<<SfC#~WP$|UEnAmy@XWXGRMzthf=2ikIusiQelFnOm3|q2m+30%*iZe|
zo$P`=ZPIf$z4FD=o8ET^(F3O+7X5s&&Qpg!*CXb}UKeqAz^VT8maFcI7+`bR<FvJt
z)Ymzo1&e;`B0DXYyZF=5=v=d*KB&Gx-HH169)DGa%yMNC0VIkyLH9w7Iq8wJ`hc~M
zeTT1b$z3|CL!+X!@x!FY&-2xkjHoHS8%qN=L(nhWv;n32Dg6sKja5!OtEz#i_QfW0
zLBRE14XbWYz~{dimSU@MBr+UnOi2z6PVGr{yiDnq&WNc>G7VmCCh}^9mu^`zy5TtE
z{0LF!**a)GdrxZ2Y>Te(xY~CKVE5nsFzaTrXfWc2eRiwQAMlFHG5<RL*}_d>o<T7!
zfB$Or7Ev_-Fot)wLWSumne*U}|1+NpJU0r@?Zvl%B%fm&$t_17sTOxvPOx7_AG=4O
zag=VqlIp;Np|c7yQkbB+<Fr<{0Pig6<hDzli~ZiCGU4>s^{Qb{YD2QKbAg!jNnfTJ
z<<-q$d+E@Ni}vWl^%rnCip!M5sv}jgqFqK80>N*Ht?jlKjmu^fHplrBVyROl9k$%*
zjms8&>vwnc#?D(gjLhGk?A>AyM&r`9(>@VQxmql3eAYMGK(9VkDm^5u%KTAE$YB?{
za$mNt9ry0zVOCrqs(_`rlv9}6(O^AJRAcEo&Zn}SlZuv;N%)|1HCI97cQ!X%+Nm8E
zt8+f*Ie%~crj829<9d3C+R)xO?q)jw5bCke)=_cv_Kdr4-mO^5Su}0V*JOQWz`N8q
z#<W-tJ-#he^KNoeyO|ud#dLa#3cGi!LJ+7VZ*YZ0^rg*>oyYOr=|{jRTerRYShL`?
ztxAdpV%VCa%R}+L?P&Y0@(6)PXBwbhRNu4wJjR1)Le@jYSEubUM@p4zisG?Zj{vex
zwDHo5yaq{67wl`zvj&W_rz)%P*VbTe5T_i;M6V5m9eG0dM{VcIyOE3AeVX@&^xqVb
zq61Bz;tLb4Xa$isZua_i1s}s$+k5>kV{Vo527H_pZC<+gHnS%b`!7!KfKOjPd$;L7
zfF<!vydV!|uCNLmy)%<GgcI{hJe*)B6q+m|xw2>O3psAQy*NFMjcooLX~j!=5<y1W
z_mYbqV_|`!%#<Y~feDxXOiX#;pMDRH9BO8UEH>Ooh@;|cD)&18-a84umf-4nFa9|*
zCN*q9nzS_Qrv7Ic6qZ-LyRMmP9a0yLW~DQ0vPOc@v*eKIP+VlqHrPc=R(;Kl!m+6a
zY$#i9jB;57H3dP<Dqb2K$mDx#HpK->3KK=!J>n4Lo+?wGNIIVe`Yh$FnM1yMsf*6b
z{o=x}QyM<Acs822H@QvGkXTXo#C?PD?-{#^V+c}bbuuFX&Pl;|Iq2s(ETT!jTQ5Ad
zy5cdvcg|Lo4q%$Tj2Sw6b=1e6m5)P+H)=fH%4^~E+sPh!D}N98T9u^|a&fNa`t@r5
z;hAyGHW%&8U@QNw&vGZl)$%>*tfk*q3hp{{tDC`GY<2TT8||~AsxM=WMfQ9<0K-#?
z)hriAa@fwnbi7@YBV|JH_}EKj(svTGi1t!Sf|W_huQP`}v*nbrbj|nBi|aJ;=K4qJ
zX+oo=o^)DCDU$f*xHo$iWnIO#1emb(%d1OR=)nRFRMzFbvyKPWSv;U_cnZgKBim;$
zi%eL6Qb*M$c;&Fd>L|NJsVZfO7w5+zlGx>I$^10US5u>l?w@A9lk4SvWi8&cBU+E&
zEJ_w@U%+-g{c_91^nV>5ehZv<-jN6UHW{nl+>4KY<7d|m1srLHEg7Uu6JVyL4}?Ul
z{rKcYua%StJ9P5{X@s<B(W}SY2@#>kmZ{1|+wRM62#Kc*#8J7#es-QHqvwk?AD0ql
zo5;HoAy^0L-HttWK7Jj<Y^0E*M<g!8CAgKWsxMt$-8?l2vyh$1TS7)u3_S-eiL!{j
zwC<NTJ4~JzIkW1Jy~mK((63ElJp*9r{Ij1y=?4|JTj%0n!Li?)H?Dq4E9ycwrusYT
zvVLQvzuxt1Tg7bixjimjx)a`!{?LmjAVNG^)AG8YCh2f88cFG0H$wJZwf*QPJ^{`t
zZ6B_$N%vJh8C}Jusi*8;g|d-l)O6il!CT~Md3|8Om<|*N$cn;g*%c{YAkr76INJF4
zHM791l&n<px(;wh!d149F70e+^20-1$y@oNg?g(b92MbRO)a{7U7_<{FYLKOIM!jF
z?_mC^!|CX-v!y7ij@N|V0X|Viv4Lk;YX{%ob;?l_3*6$#KuarC<2bIrtIic0W+Q7}
zE(rdqgml-CYa^>p&~1aqo6FJrVoNTF7+ZegMSQbs*OurCVFS;3)VeU$_=_P<Q?NHU
zd~=L&E7#l6k}rA)8D)*Ti{$Q>CNGd%4Ast-DO;TTd>78pmMg!>PpFkVz{f_`SnrcL
zK&z*$gDd-Tpew*z6j94=@h_>Vjt+lGeJWY$<c%JXW;eREX8MAD6;nJQw6hfrv5{rV
zxd3SAx^mo;2Y<A8bW{9&yyeknEAaIH&kn#Ib(i~P!<nO%3lj-Ez<d8wE7uyFQjV(w
z=}In=Oaa%5e1YGUJpZ>B{V_%@dQ!TEPcF?!Pf%9~Jf=-bvUPm5(c1l8pit|>#2Z=q
zcW2zuowez;-+?W$1#AiBt0{%=o89B3JlPsgCiPa!(bB){ThjV+<J$NeI{VtbIh3-a
zN<S@ew5Jg64fqWyy|;S&y7lbvlx@!O<_z1}2y9Ke1N%{L#hlVI^NkN7E~_PO<@D-%
z6@}M|@FrdUauc$BD2cs<3C(c8SNT;ccMlL49T1XBuN%`!Kuw{X27&>-x7Pkx(Gb-)
zlJW{ODneGH0V<n$D!Ltp+%7bIEj0ZMpHxc%o;<v1R{5@ze!hlzz5#q@SH#B4Vo+=b
zaM2~5?{d9456jf`4r$&tcZR_6E;`Ef@`;N{l!BlrtHT7~Gx=j^%W_eRdasTE4oznh
zWhcjT(F(7!Hdi)#me*WJi+OQND39R@zU8_OII}iXXhn;9h64Y2l@d8xSW9YG<&En0
z-oi}0*j~K~lIQqt6~}26#&zmU6`VsAtb@EjSW7JYCc-gDslMxOmDXvM5h6A(^pD47
zkm%Ha{Ie>x63H1a8}zoh-6}IC8-ACzU-xX}OzjtoqCea`Y~;OcAUh9LhWd4E`gM{N
zq^rqxJqBo|%CYo3Y}CDM(!oQg1Dd-yKnl$a%e-t-*0vh9aK$UWc-X8>;3^C<-jLSg
zSZ$e=64s9n=-AwMH1TiUW;g&T?pBRiXs#p(cJ0DnE=DnSa?o{gOoECY3$1VA`p>a4
zt9CVwA3SI|#E`mt?rgd+i#blg%JmI3txC)Bl8QufsFHT5@^A4WH2_ldu(^fZcPk2V
z;NInbDEQ<sCF6kL(mTsD+uQ<W*a#0#<8b+NeaR#x&7HgED%%V#sh3BT_dRvth6tBQ
z^>}vS)d4p%OxEg~Y+DT1`5U91_fxI*TPEVx@84-dew^z>=CH`~!)dU3*_Y~37h@-`
z^q)VH^+#V12kdis@GA*5hDfY7jLwvOPx9Ab3$&szBx&*=lT>x`IqvQD3dSLisw7f|
zVo${?ZdPwbS6?o5gijtw(Bn=CiLZkDrS61Zej3y02+?~_t`=nX>UF4=2!AsMtt9}#
z>!sZ8FHZ6Kb_O_gOJ2$$zO-Nxb)yok;H&F&(1U_VLtHE!XYh%CwtITGq+wR3eaKQV
z68mnu3IN52d1n9^p(_r+hu$Nd61nycHx;RnfPjdyF%P0I%p&Ylx37+`R80|H0+>Ny
z7DZfe51G~dJEwX<gzN=J-NImKWh2c+A<!wrQAkJiLlX-^lhMtdPut;P7zwE(Gj)C;
zlh*2?)s|N1S%vpz*Sl*&4!c({l8Vjlp-U|3PZ|cpAd`X+)H*Sos)mE~&ceg9Jg`TK
za+zYejuBk~!v8xYGU&fUp08Q}L%Lo36_WQcbg|CjUm>%hkV%EYdlBV(zbTIwlYqHc
z)7W5OuhTrlAPYySq%(;b&Y%y&+Z#cVi5cFI1tG3>q`K0Iff!msh30vkNh)yz)mD_+
zUs-+;fe^~W%v_)js{=c*3xxr3{w-Y1C$@7F3RC~`Sp;G@80J@0*Tke_!m`;>i_~w_
z2Av|$a^!$k(7vId1rQMk7?jm~SjQRcO*-|<Of_6mWVU>lwRu|R+ZsC<6jxKYyAYU*
zjQ;dKhCd$A`<l*zdaon`LSR7Pr+Sf96b87n#gd|`D!tAQW8JC5Kp?F1d19Qg>4dh-
z!$F8!hz{CCA;`9n`(Q}G&_p5hnX_hOt<~e;d;`U3Spt@eQ6pd*nUW;r@;uwLA^M@j
z8j^2tgu+2c!1&lfuW$;zhbr_M#%)kwGG^OstuU~kS2%-Vcv(YuY)~}WLRf-y()(ag
zG+#&az#pqAa^O%vurmWl%D(Z=(N9yE_GFF&&xZeQnk8)rkhTZn6#~+0Pf-W~5eUjq
zn7y0DCz;tptXGH|9LD+f$yZD(17r6nb|wr`WG>=X4@cbp$wx*M!kE&PQAZn6;=Kuh
zBrsOas2e%pvkEp_YY0v>a==g=Jg?zT?fG(KQ2%@!Y~wR4d<lK-);|sA`+sgQ00HT*
zkz1#S$6MgMZ~De7Fe~8JclpwOazz?I2LWB50*{QJ_v~vJ|4z4O-SbMO;``Q`3hC5m
z6dw*Xj+X?7FrJkZfi|v_^!rh0oUk9{C<K(2|K~u!fPZcu3eh_q;_s26fwY<RDV_eX
zyVP~>1_ftc_RdE3?pF4$PO0&*5LuYAyPa!;0A8Y>1{q{{7^uu@$s^GhuhEM%qb;Nn
z3wSB23~gy`&%|#dx<~aR(HMPltF+puq9QTHIb&5vgSq;T`>sbbHLrc&x#qtUK{xbu
z7C9F~_2`dfPpa3LDjI*+sHZyIoX`&TL;C1O`Ox>3VecMotes@<nZ*{}>hxfRua1jH
zNa$N|7+x6JxR}}q9@%amA!;|m7pM57|48lQd*_9s@AqRMHhm@cO$tfBheiK`pAdRK
z(O4C52u0C!N|%wecAEk(WBW_yv8dBmE9&}X_knBgVL~Bd7%KxaHRA{i*W_f~hZ)zy
zwq{$&!utA!r_*<GYHL#7<E_g3O)1->5-=8+_8G2byHh`SCHJwG?&!hdv%AOJu*X{f
zU#^18nQUtcUh-l|jVZu<LW7mMZkKK?>Gs8pq5nK=WjlO@Nst29z*Jk)Jk!83I^SV|
z7)C<lm|AvQ*R2GqCU@ZcZ(%Fj-77zVzhGLe>w3xEhpZJK(*?rE!Or(eS;U%c>>58@
z1#{sD`b#x?MdhsSM4k)=gR#89&>B;P@$<AMm>ME|KQjHE*JMkd1S_KqE8l#U&~6M`
z++$g*fpdrc|3qnDAsXH#&rGKGSS!4KnK~EucpG6A5z+rBK11&GP3nBVF%^LM{0PNS
zv5{BA`IW*&ndqS$JNdatVd&e&m$yXB-3K7v;CWguY77%A13lXm6Z`ONi%3GhkDHvw
z8_>1%tgei#>zDPXm#P|1yZ&Y)KP9uMuJ^?GE;D^WaZm$~x3vjNxL<&vzE;zqTRJZ4
za(RQXY}K!b7(uLuys8&t7@(<*{}(-Hh=-r_`~IoN!4F54tQq0_oLu|l;m+))P--jf
zVQ=@~6VLNNJpzq_hV>WaY4;uB{vh%P;<g)aQ2{MkYS8{qAQf6wO5jx};m5>2zxS7Y
zX#A6dIu13m$)selvN1O>(6FSJr9d@e7<~yqR0)i|1g8_X{7QfGWfy(WE}vgyEPm20
z>9LY;W`1v5o>=V51I4y%)ZcY^YvNW<k!$?=4FsJ!Pe`5st-|qCQN1--H?<4i8Rvj?
z)a*@ncL>`sP6k$lxdE#Ld6GDNt?ktfL^&tk@jjMajLl_`BHa7|1Uw_u5(*ugBGai`
zTSAK%vq0;SHQXF|ia7JZB?QaF|8vD4?A)Y&x(IuarTOvg3aFHuNdFw)Jo3~eN*ZzI
z5;(jmZUK&>VY210hQV5XWexlsy*G{++aHXVw*DxVUP6re5KD6=Ig(6a_6C>dbC4ol
zlHC&mt8nw9a9QN3Gf*g2ggJO>W*PQ<I)y96RH`sbpooIMF#aXtOh}adj|d>E|F?*k
zL9qteF8#j+u;jtc!P9jTny(kKo*_?NgwXt<<<96w;IB$Wj^9OwFgJ<s1k5o$_X?Ge
zWP(CUM3{G{Te{PH0rL41ABvqM(<o%6NFutld*qSg6>O3uGhz?D00-x9G0y*2F_s$a
zzpa|S(`01m3oBEy{npmzJJTer=efqJ(9Z46rL)Na@0!xq!TG`S;%~xA(}bv3Etf{e
zxVi4pu=R7Er_Nim%2&SQ{_SmIPcZ8esln7q+QBM=`D4w#Y4lq(U}XMI;WT8@K;Ysr
zW1#QMX(=+d48eR5k3rN(*|{#Xj*B3y(!vpUD+t4TtwKo^-QadzRP>5RNC+NGnn;`Y
zyXQ;IP747MjrYaMlGn%kR?O5Fv8K=QV7Z61kbVbE$!<Hsj-RkHB^*DwaVvavR0&t{
z>f5s=BF7?cLCFg^qGiRu@@=*y7j^>;mN>CL33Wne0oQLv)sKlQ0(gG^)OJL}B#xn>
zxYZw0qO>J~QMFOOhpebS{V41y?1=}8OI<^{uzO`OA%U8VC1e?VE8*0SytX!YD|wmU
ziAyA%bE}?aG@+s&iEEqJ8S+WKurmY~yUlEfBCj+1GUzt&mJ^I!QD3}dU~?ulhMbzo
ze-{4mp^zG%<vHJm?r`Zz>MXgXJzVD7t+J{j=ployCGH`EY3(!v9U<u9p)FA|R`MSe
zx3sJTf2;5W4K~-e4IhwJeSN=uRdiSWmkyP@W1x<Amw)ScAKR#BCH;Spa4XQt_8WS5
zQA}0V|N55|Xz72fcvSv3#A6xI3bg-+6~jgcAwvgH$6@tJx7I%7p5qfYYq&!z*4;+%
zEuVcs+^gc>=(DV6GbgQiWTG4G?AjnYdZssjq8m)Ey>V>U0XU_O)DkUuzv1#bfLdDv
zjNUwVaH?g3Y?VxV2a!$ea8KQpKk!&*Y$Rg{)!(pPLM7Km<Ie#<!>sgq4@T$w*3X*{
z#K@JTSYV3RPHEH-FVQ@yoPO_tBq~p!yJEjjW+0j!$-%H8n@iQZM>gP#ItPv?S{LDm
z2n|HcDhEi=x8-9b*Po-tti}r$1xOV_YQAB+HJIV1EH<W}6$c^ahu*YTa;*9AF)TGQ
z!z0^p6E7xe4&2?sn@wAUb0FJD-O5L~5Qx@mO(fcoPlRgzL9LUZXQ;twtUovYgIXD&
z`7hKV+?1lTzfkK!6Z+;e`R{WuZM3nW!a4Aft)(k>%hY!i)#>~-!Rtbclmod}Sc(vX
z=-VVRpu;(`VHhxM22sa#gy}jMm%|Zo264kVwEdUjl(=*%m1v*?%k_CrkZrJO12`~L
z+ZmSG1^>fU$zmkGvH`pf${0a9hRCVfL<*8b%Q*&294H1wn|3)oMWilJ-CeH|1&{TQ
zqDGMKM1}UvnuW@va4KD{vn0#R-92?Bj~b;znV6xV#t6{C+Nd_%w1Yg!7<<IaLX{-t
z0IHj@7M!M^rehp3=fah{VwRrMxcQ{|>a*k3Q5?piP{80Zn1&A~i&L03sxr*R6={gP
zgSeqGhVo0}_E8*DNZ^CGh%im$%Z`hjZqzneB0$qbl{M6|&#{%8)KYZ|sp$uC0l}$}
z9L9%KRe33TST=*9@Wu#(xD35#BV}0(%Vp?D!>UXKuHhWf`Yk0}&i|V%F1pQox87%U
zjR2V%Vw!h$d%djF?1Ei{c|TjVW1nm8FG1YU%;ko$oh;>PDhE?zgP4a^80xp77jMhK
zT>=%Kk)E3*UG#?fD;TRdztZ1t_>8EhB)h_D6}F4TkUU=`u6c<2yqbqrITa=fAU+*r
z!q59<C)sR#Yngoqr>PaH&dihKl+r>&Z)Enyfn~t|lk7FBqVuq*vQmj605h<7Q3`M6
z`}p1hV&UW_n8>o8Z)j4+P=co9N=C5(l(^Dp7W>4A&s6CMVoLjD<tjsGk*1y%Qc4N%
zsx00(@&q*=_|dY?M7&E;d8&Hw7%s{w-Ky~8$<|7BRN@%0^l-}JT2XnCFW;s8Y0a-i
zB``3Ku*(V(R9T`e_A_Qa_u1w}{^`GH)mKEvRKz2_sPiJ%CZx)Ycczb%5+`NtA4sW1
zF;XVS6vZimP*s)2zM-p;*HTMim@x#>p3RscRHXMI;i##mo8(1GC=YpJhc@s$K{N!=
z0(%0t3eB9D&k7hc^>snC=1he&+*p4ywVn$#ra)y#UDZkHlp+-tY84f!p?{(l!TuAK
z7%`NBXt9<u9YOV97U<RjElBu;`Nx8(j>x2E;``O8oiZ<!WG@Y+q3p$uNLnbfEj86T
zs;BCLcJa9{7!-f;-G}^xyx9?X>jJMjCso0X7g8Ah77A?>xF&?bA&|(cRyi$}RvL+(
zaUz7#kT!SVkOdXwG)8)&0i+C^3!aoV^8iv#Dv<milu5z<Ntru+#@tqaDASNrQ9LG&
zTmgeez#{)wq}e<#n^>%|2@j(rQFbOKRpYDOM6JgAGDR7!-@bCEYNMwx>i7~rwgt5F
zr4)m;bF|U{<lF&~g#$wA*@1A(XRg(dy`ps`9U*&6dvYc9-i(4MBg|P`sf`VTqU+WW
zEM#=9VVmmrJsSVguh)}EA2-gR8U(VVZt4gVGGJF|7r80ux^p0)#CSx4vdXk{C#<g-
zr}*QOuE^HJi^)`rF;oM2?B2;0s$}!+s?KHsk7o5WpV*nw1hiKDExSzxz>)2E6W*q!
z)+nQM(%<T!g7ILuUifKYxI~1`>wY5aLhU5fpc9A{CUQ;MrPyDL3ChrJIVL%IK8NQ1
z{0`m_qI3}xJa89@U^c8N#U1ZBewU6Y0bXOO<OCNjOuAGhbgrCX2l*pS+LUg#Q+G?-
z2)w|``WarR|5Qv}8;v5{12sfxbkiW-k$6`(bjxuB9~Chk47T*=j#ED|{I6$!NYvQR
zo_*33`1Y)fOuN^2U%~9^p8txOFt(XLd4LEDjSBFb9|aCHC}{3Cz)a#t>1b!$RdJR6
zC=G=JDkWD1Dg`JCfX6%XCNOMC!CIgz$ZTmFKVXsLOL3>=b8WDM1%np>De-vB)5nqU
ziS-?TV@h#9E}j#oIJS<pb_Ng3Ji&IK+xVh;lkGaHYC2KVRSNY71go6wD?oLpNkgXS
zsCI&xAg4KsX{RMPiv387cNEJ^OLQDWfRW+Oh9cf|Er^UtK#fHkV&TIcJY)Lf6r-p^
zs|k?4R6y{8%e7b`bL{Fj)+8iN;@wph$tczSUCRAiR7AmT4QTUEg{ye5VTHFDqFT@J
zsEFj*x280ICUV!J#>;xK$(?s$8W~eQN#=dc(B%f3nmFu7;Uv!d6gC4wo()jdU{mUk
z=wFR1-FSlpnl){9g79UMWEX@c-q8#3n<FN0%kvp%`gq5SatG<GPhn}%6SCZ|KDoqL
zfV;oLl9r2VC7}NmmN#R+{AUV1t#1H}RI)OLrCx<|h0t%-5M{{BwC_>0wnB~Yw7H;C
z+&N`l)&;?6l64xW#isvXpZPrcEph8b(d7gT1A<KyHm#Il!?OMr7bJZu&iI%DKNg=G
zz1*QBW8spTb8~^`_Jn7OpVG&)2~qfyvR7Ch0?w4^Z19FMotc<x-60p)TOl1stA?4b
z=a6(Eq*CGLAyr1HJiS#@ROWs{##~pmv=<hyx~3bcrXzd<+cHFXl?z)c^0A$Q7B5|T
zUFf7H+}!*!&HA8g1qknMzhU5QvA4k~jTEG*n%(tTIOlh?{6tdQxM#oPF^JFpR6+Md
zr44p@h)Ak<vDRJY@TF@%%+o~tckg3Q;>l(meI@T->Pblv!?}s~{KG|CND=e#hAGNd
zQCvXyL?`=%tkufab8;KPd5O<v_0r&6FrC6MDOLUU5MQ2BzxAUhK+7^mu7XpCxWmj0
z3*+B*Y=#Sftb_}sv-B+PBgG26?kW%B+&~W!A^YXA2mT5Iy$Pd6+>C!CA^2X#zlXGA
z5iZy$SA7KBPRr!?Hlko$#e6uk1&Uv9c9X?4>AU~0AOvplSI`^i1(wKPz$ot<t2e-h
z-qU`Xwrz$B0s{&D9f&_7b@~R{R96J}*)YCAqIO)r>q6>D4LxqA#pijFa6$iEl6OOh
zwoE8tW@C#G3Mr7NU*LO4=?(5vT7S6Jf|iC062BYrN}%|G6weZgd>U{ZX4D;Y?g0K@
zjpD~_;#)pK#2@fWl#|>4&o}>kdbaqND0WzqWxsCO=V6hUU*NxR_K+Boz5{QA$VB>i
zzVcVdko9K+>ANg{<M}Hd=MMTGFXTq3_mJ|?e~{o0_A%o-0zLaLDP#e^24MbnOz1WL
z`wcWz=FoGp$8iYnhZ@A+j$sQ|cN%i$HV85j+}xGX#=y8>-at=kc^}dLA-3wT@<$Rg
zK_O7K@=47HGn^y}U-0lhwfF@53X1!WlDS`^z)3IZJnormpkP7K*FG3$jJQ8TxSp@R
zglfeoMt@p^$7be_oEvC7M__C0A(fZ_<tW0vAtN3&Br14l+H>t8^>XYXnNKnS0b5sn
zpRJnK8-fr|*E$BQ4!H+B;(0a!*(3_72bLPKt~i(-{vO#`W<djfAzIA_?{zZ>CFUuu
z6p7Qk22C089G8?OiT7T%Wo-$Ny_UqR!DN(B_%;L$kt{QWzpooTbm!x>Q?JcN?`sIe
z?JOIR;6Opqv41FkvPRftesosK6ABc7EDcZt9Vj!X?Pa#cmeA_?b+5ctJ1i*B6aU4H
zVTXD^sd-T8ac_*-P@^*RJG=%?bv?af<z^VcOw89u?=;6$oc&cRi?s*Io8%k_h%4ur
zjYG~_kgzscaM-l9Zvm>VnFN5+wSWcSPl~hDQve%*zj@)pGz<;EmTk^G^>sDk>&Oj$
zi>bK(!Uj{R=UH3#`ArZgz~xKM5fG;I4@~LbFnWN}XXOckKi|{IKC(iFD5P=OYFpb4
z214TiT!`F_nQp@nJNoM;enjlDe_6F6{H-#QbN7D+`wS@MIiKsd3SF=bS(sE&#QGPV
zwTR7Cg4orcKAx31*Z`NXoFk<R`4Ki>=3c9->V*v`%pLYGR>ZsP>um9n02k@}JG|12
zyiuM%QV{$WCY2x&{{xiMXSo+As}8|E_2!(pxjUEz^=b$dsaM*DKo3Nl7wWfawjjpH
zIZ8as<^r$@n*q3|95b`rGCgI|dV$2?OWT<EZd`%u$IR%!vX6XurV`F)pf5C`(BK_2
zJI>i#0wB4k^l+uPryk*p$`*Vyp#{4L<S0JTtXl{exPIxD*)*9h+2))!VZ1(G(05Xa
zA5}HTfCStmE`~H}l>(>_ri|q_eD2JuTwGaP=2cqs`(T&wYATB)m17^=+eo>bwN2pi
z0%-@dSKsc57Jg0>@-4&R14tHUnIs--{rl1R1B-p2=A}3a)anm|P3=4;3Wun)gqz0g
z;5oT+D&pv6J!lZCj6^M<wl%hQXP|KkGuW);E(zc|SsDp?rxs&|GDWOje?0CA0`w1m
ziy@ISdc*ioXTI<I5W^MwcFEB&J-r?}JKZuee^mL{y{e;&C!CENi#r9^_hPFi_J@2{
zk%oKdcCJ!6At$|*rKTXA5~VxMP)8jGOaiE&nt~nFMHvFLjdQj4CcB=~bLOzTBCHVU
zw-L3l=lccx1U3qc=b?`BGDd}~a}=hvLBj2q$kQi}QD)fI3bQ7GowUS89K_)u{9#d1
zr*4L`h>{uNxb$xSHySF^stIbUKOw1rA$d;IoKY1Dm}$RTcyz#u@B}!69g4v_nA1}2
z*Rg$B{fWS4Ln6%6md&ZgLj!MR)Wt(&uf$^o?xF}dAYK`NoQD!}rK6goPKUUF5Tg$@
z3vxysZn%kl^Q1mc$jeU8&rV*%rdI(_%OHsG(CAubJ1bMO#gifE+k2)d0pL<ToU1xQ
zmd%pU5*{glhok)LdpRDQp`>sEfzg$r0B6$5Y)2-UM@1cKDm^8D#GJ<g=5|XpbvWeV
zf%6a5!y@LQkgxAPt>TA82$RA*2|>DikkEguI3&L(<Ju|bw~TXUMFRHmA5x^_urU&f
z%F1<eWO-$kFfn<K`A)b2;du1bDB;w|thfQdn=rt`-7Jh(2@1CoenZIZYe(`dOfU!7
zmG~GTDs)U99c}>E7x11+j~Yr|#F(AeS#9>f{&>vC=eu1@jzCUk=oleH=PFw!I}ouJ
z3Fh1xXd{*^NuGgvVKSIKL+tuu{AIG;OE|WzYU=XuS|!<v$t%Im%B{29hee9oWRkeA
z8@G%pb7TgWtSc{Nz;sap379Ujdcm+G9TpjkOQR3_PHwH-HRa`H!_ZM}L?wP+#2lB_
zNJg``m>Ir+!D)cOPfnV!Qb|er7bi|OuSS0!YAWY=8>&LdPat#O<_3@k!gJVShH7mU
z0p^8{=yi~c%VfelETTL#G}YQbN{gBye^U|@!$;Nth`Hk69Eufvg#{iwsj1$S0ejSs
zq?{UKJrTgOM3ZM%KlviRSrO1)kPY!ZN>mH`xdD~<pDZv_l7P+}iv7nKXH@8XtXh}+
zdhAq$acTTX3$|wGelK!rDmxk~!7BIPxNQfH5$$4$^4V|^!Rn*|6V}q@DkiI9DIL77
z@Havw34AVVS)bXyuK3u0`=aF$ihtNGU7+Cua@lQus(81Y&@9Zn<3#HzPO01yxK&23
z7BZvs4EP1SMbehjs!BoU=F8#xEAA;k_Z?c<C_g&{enFPzJ9c0yCL;vHrHL93vdZ5t
zJqcks4&*<#FcXs#nw1xr!zFIwKN2!2O5K_Y>JO3&6wybmc17YB1Te2ac_9CKEt#Po
zsDksv>;-?THvl!XqvniXScMH@-tj9kAG6ZqiKXW$E*k=M)^0^UXpCz@5dw%yuxeoy
zL<mh&qm5bZ;y54NQ@Y@d(u|fTD#fc194y8aI1YB@uL=PQwfN!Jz!2~LBH+2xaF9$2
z%l|I|l!s6}7&v22>^a_G;tF!)r6Crh2@6^CqQs@dr7{x20Jq?WeMjX)>9D4JO<{nf
zk#3@x|FhIo;zGM>hnBNUf(6z=qa(?v717<d!0gC29Fs51Cb8sq6Bd7ws<=b)&koF{
z#ew8m5(ea`S{`gE+7g%U(nlJn{cXq^{2x9kK!m>xDM<wf@{wN23TAWXkI9%_6?4`G
zwi8d6G##QdoO6XK&?U*+G3HwtnVdRKbi7fkTd9S_K-Wo0Yya%`uN_{MB*kH}i*03}
z7&Cj~<D=>+Gp{zLso+U3o!>gsCg<ir*i!TPUWu3pfPJlPq+IwSy)u7B?t`AC_PqYp
zH`-`5ErlFvKcQYs_z4ahM}<>BJ1<Vr2e$>RxUcf2n9@3U`K;J<5#Y2qSvsc|?-N!a
z*JB8m4ApFH4i8k)GrzIL9Ml)~R<tU!xIa${^Rpqm)}?gMPZ9q$L(;&s)=R=6fC?H_
zInkYLmVmyN)=LV+5Pu92m$7KC%@LO<G(?SVBf_Vjj|ViSiUU5cd|8Xm%BcE2Lth^Q
z#33E<;QUtCLufXIfu~tCEJ<pZ;AWLrPoGFCkE&_9D^fe!T`P5(jNaTZIvcm)|7J{g
z-q%Np0Nj0C>tHpPmr=nWK)iWgqh0HOAASJmL$@wK95@XEhN+b{Lp?!CbBhxo4m_Kq
zE)b%UrwEMrqOxa>gAz4*w2%-nt)!^5CrBlM)8Gv%@XSdKj~U|4b3i0hWaxp!84FF9
zAt=o9n*<n5Q@y=>`luo)eh5shR%H5mCVFMwv7k$O*6V><@+|!S5Gvx!_E353Ae+<$
z`D&hEcc1e3L@K#UZJg#|_+RR90{^HJMgHIFY~g|GxM8~d-_9`p17>>g;*#K6`Zth0
zCJyx7TC{xIze%yu-`@Hq<-C6US3#6N3$6+UB@BANK|qdS|Emg>i<zsdmA%DZ>#Um8
zH=TcQqjztY8n*75!!|p~?bDo+*KWyE+5$Hp0IB~9Vt3D#2%oR8O|~96mTI1Ud4X~J
zJl)gnGB~2Zl#Sq?hmc|{0LK(K2O>s8N6UFPw^C~RYQ)Z*8Xn0^V<^DukMp(t{c>M`
z!;rx`1Jnzd^6=27wMo4=DT1b@H=->b4kFN|oTu(rITsq>-lb}|_#jeKTT$ZD2o+M8
z^<rc6xptZKQa751p^4quE=QVn#YS7?X`kVq$4MutnBE4lpA&@&7yF1fWKG$ulk44}
zi=_1d;QkY%Zh!Lpa$qOg`AJ!$2J^V+7(O|b0y_w6Fhe0eQo!*wsBmQ!3%i4^&MD-`
zXg2$05`m8@0n;llg!08P8<J_EBPKo*9sWpk(%d5^`h}8$=wg9D_!ts9ONlR=8zd^>
zd;|3p3?5`Oj~AjW6hzMDLJTE-#vui8qXHXcw%=lr8#0HR(*=1U6AW`jjd?EOGWX5#
z{nlfh`V=3j?g8{mtAoq^@dW(Vt4gba^YhEN+L8z<o8_GGZ#P1S_05t}Td}abn87A>
z4rM)w7_DH|@-sbg`3k7(j{xEbl`1Pph3c`k&&;E>!`Z$;cuJcq!^-!o@V!i?*ZN?@
zx(72-QKdnF@Zskf&$)pdSg9-(>Z&&7KgB|lp1=1|j;ut{)w8}|i_4s=1?_Ntn<^ow
z!~a3n#}4Q}AWwuCb9I7)WeU>r@rH}2PCQ+@MQ4pkyf`z3;^Nx99gxn-wdiU^NF)~s
zF^xK~&UEWK<?UB#`Ayg)$difSVN*xkIhzcxZqEnEmdMX_D8KdqZDrcQ9y{+3+IRYd
z4Zxmo)cuUycpHh^6zt|=PFKLywG9x>P2RI^^?OhwRS^0pH>=Wit%<Nc-B;`9zM?O$
zMN0N=E05aHf!%PFRAi`_;oH0~cbE}qlIk&sCz2Z2l)xJNWpfn{J-CV|I_C2W31?f-
z-PMBkOJxX#QiYjM9qh5F1eXpTFI$uWM)&tA$+`$$dh6P<p-d#@c4MUuzWe&oiP-xR
zea=g>y0oFLi}?vgZ>>GEh$K6wSB~lni)>Lp*V`sjxvTt_?<0Q5ZW9~wPx5xf24kC0
zoR{WXsE`xx+hjy$bSH!$Y^%lB#&uH|0#x9ImP2Eo^sSMnvhM&{9NxcUst2;`z0UJV
zQ-8f(54UDS_#N(T0p}_F?!cK|jt>hMqLhN7<aT9EiywihCFZcEt7lkYSg8czkT5Ew
z^e?y;;VbU7UgbG`CtQe4|Cb)im2J>}F0VY%K2!k#mZNG0{{5+w`d7`lFJ{In|Mi29
zneDS4V1@^o_3rLJNL1N3jb;%^WW^@vNEU8Ja>S=#X#y^WntFL+)8fSLxThpJB`M$X
z!<}N>k<PcPXJulAQs2wFSTrU28MbLMObx>a6N8y~0hfHaUZh_E`GP1C9y3U4T+UiA
zeT=L-#50Byorh1bs);{`hhlt2Wgje<vk540A}!Om!l-_&rY4+^xoM&1j+N<W8*c!`
zTlTyXmPBEg8lQ`6-Y8%=fj(9OQ|cT!ahQQI^UJt>Co)aGm*NiPCv325RCem5UmiV4
z#?k5mV0N8wuv-Psa~je6Dq6-&tlxw<Jo`(+=d|{sxj7*qKo^r>+PojH+ucI`)3M(?
zc`hcvlA6EafJLMJ?U*^Rj;yMYvF%@VH8)fH?0+!h5C8lMEFqgMW1G~3jzT*e+BkuT
z=M92}UyHe(a4FO_|9hIxHjeqSR=VTfF5c^sZju}{5C+FpR0^Dg=VRvC_~ZVKK)dA&
zeLbZZEp6-1UR+1|esGo|p94Okm#&FW6PlQ3WXV9Z?F^K|jb<k81#{|F_0+bU@06c>
zyer){T=g)bVFxNGjr(J;;l^q?)0_`j=>;io%!oCkIS6LM&oZJwTI*f#Jj0`4L~-La
zNTslMdAqh#$XR0pzq7<FjoW#Jud9w4(TfWuv+9^D9gQ#_+TfjBVzb~%<%^Zsn6o`c
zD$}{}L7aw*HxC6KWuai9B9ZQ`50Ba#XsS<7XL9nGm%RH9Ly^i9t46b6MG6%vI3BF$
z9hh{Suk~Teir;&2(pr+3vu9S3XIm;En^Xkd$YdExr+ueCiHwcTECXGw?3<>YZP|5)
zyqqj|&<I>Ct<wt#;W-V`u^%phSIK29sBAH{?m~mVd+UsU)(_zI0Oh|EH9t_h1}oip
z_;CT_=GBEzQ(dmh#osz`UJ|L{1<RIe;_1eMmoBdEq<uTa&ET1T=Ll9dI;NxE>2}zw
zYnE;QZRqrLcYR?1>HOxdbcD&^LkWxXaUs#lgNqicoe6C|cgPfJAbu;s$jzi5L1-3a
z#ViK)0|NPT3rh!g0i~6i@Og1e`21)Nm1QlxWsbe{ETZLT58MyqcNdnArq&*V$(~#R
zdpY=s*O^;NROyJyaXe;EzW7b6+f>13{T)?9$AiAqJAqV{k;>XV2S_lcsk)zsUn8d7
zUemfM&r7}Jt0gMF-uzcZ(La~$WMR_QVPHME4q6ZpjDMe!u9jwYW=ww_S^lbIrY-NV
z&WYXqq=DRiu=uj>7TGR-v3j{&f`Hm08rLYMV@s_>d`jMpaOu?RZ?suE0C&+mP+KMR
z>0<sZ)1IIi@x%a|W-XFh$@yqV{s#s02<bDwPmh7}_0oA5A?WXLC%Lyr?L%cx1mf)y
z#K)1#Chws4p=I11uopz~Maj!1nmwD98ogGy8W=237^&8on%?F^I22u)lvai?k{&Ve
zgNZg2GeY#+gcw=GAn3$pvSRDD4SG-H-<a3=VLz5P=U~=h;L(fSF2O)t-U$<kx_7MU
z@ta`Rn+9@{r06n{G`PJ}o>hKLmUhZwuZ9)bjlB_gF$;zDgF!fxQ2kKnd2Ntkk(4G&
zKo_GgkehuN5X@l|MwZcBI$ia^zEgX7c$mntvZ}~rhrHIWS-Di3@1WY9Z7vq4dqxLt
zfjuuR9S=6d4w>jW5#zimm6TGFs?e}?>WX_#nW-IG@=alZmg^i(4Nd;D=mK@EyhY)<
zU8W^2PNunl{Ku_VgME<|rKN7*TbB<iM$@U#0x>Fc!GSr8tZaRw@?1^fqExoK6KQN2
z6Q*eaG?DUh+Iiz9Ecz<6F>W48BSrNmSVC4Ga^Y6EzQM%B?5VrsWKI8dc<2JVulPb*
z#<9!YU!V8a(`Nd<OET$yemPv)AE_aH(}n1PeRD#6Kl;t|?)yUX>-_nP!#AHMkkO>x
zZNHa`7K0vLe`M*w^P1eZo4vJj2Z4{fFe>p@1gJ3S4G{0}Aifij3q=K5gGLJ6dWw8-
ztUYqq0V0<ZQAozXhv4shS8^l);{J&91dh35#ya7xES_aFP3QFyQX{FMt%qK?#!<@i
z`IW06Ey>u@>+-KRU~Q}9u&V)%J&Kj~w836ULPxla8%5`&@+o$tg>bP6aS)0wu1NW$
zui()fAGStWN&rbP{@y%rr#cd759-O2tktC0Z<ynZqB0F9%U@^niyQ~!8*4;O+eMUH
zVM#Nw?0X~p_3PAU$)rc^s5eB!-AgBz@kc`7OIS$J@9_scNq#YAS<`MNHaQ8K+9i~i
zil+B^hs3YP&y$-bUAgI<Kn{5sZOaD=?0K`Q5U-XLXbMyu*LtPKhP>~Ex5p)D){ATo
zn5^JOTbuX8xnL-Dh02Y=6b!mokeGXAoqbsqRPVVn?T}r!O?d+}C#-A>y!G;KhBg`*
z)tCNW7ZGaz?ndKs9X7YfxjVQm!5T2*{lim%@28bTSt&!M%=e$BUMrDTes>+4b8a&_
zuIqS4BJM-UdF#3k{<@jNrxR<1bC&!EQA`B^bUoHTlA|>v@Y%2t!6b&LG+R3u;fv%j
z=$Z!7ZR!ULiSu-~av8qT8kF6)pS+=`rXpf-+&@Y35~1rXMl3IlABE%>+<jHqOHJ-<
zqg`BFrYe@WytOJ<iojNoij&z-_d57>X>f`XQ`9e)^Ky`(kSawZ-+*gH)qsk6P{u3|
z`OKd^;~cHwoK1+*J}W$;l~(Ip?A}~h#$28@`_x!a)k*!MKhU9UGjf>=({(Q>sJUsY
zjFaAQAkQx5fI!ms0j!NkqY5RlZoApGZ+_1D0&?Uj!Tz_KOF=1km92KF&0}^o+B{Tr
zl>F#sIJa&}Gvf_HNd@QGIK}rSHLE4<MeUR)wWyOZ<Xua4k!EHIPh;99H+B=+4p&m-
zb+;UFW^%M<@M5<!C0^e232-g9_g>S0@)=e&rt2fHRNtQtWiGoSQearqZ~(fVEiu=%
z=<q`Y@4md-ImdB{@AZ0@1V0!{>$BId?(Mj~6O2l7P?^B!=mW4JD!3aN#)D<eIzH*z
zK4o++q^l;YgVd+ffP;v<T?>l-E+6JequQIXl|4|CyVzkd)Z{eUWesi~n%w%ZUy)hz
z$b<Q`YMUe%GWkP9i<&vzBK#2rr_6Xu)xO@J&jGO3{(aX4jFY2sWqG&tqo)gXdHb+j
zQ6=9uF>J?cPL0+HSx1n;PGN5{SFy-Tu0;(GQv9li@Cck*H&5We6OJv5n69v!w+87X
zc9IX-K+V6B5=*CHo)8JKI7VBmYH`at>ggw`wc_weLBn$@DT)ox)3$A8PB1B5cvC3J
zBK-5$PAL_W5?>U3K-b`e6i58CSvoH$0+9?X*BlH$YVX*XKVCHA+hCBLx(q*3IopyX
zOq`dNbF>Ab)!?=;nSYL`C}~lF(c?n-#i8l3RQ>8Ki;W%6GEUg85DuG0nn|pdYsO(Y
ztvTX0Ig=q3R0dhBDK$AfVUD;lQ)sh6n?hRS99V9u#?b<W$#t*~En?cW)y2^DYwnnS
z@qWHxE#Jp(20g5E9QRv|-Y@8X=3?Lcc~?q-7d$9n_KF64H*s@ub+FU4vt_b!HM9Hc
zvR4&d2iMPx4)WwHK9)FE!W)jhpo~m~k`Grc{qh4Uu`{vA_+u-)XUF4<<H(Vn{5u#C
zJ1?L`T-wDE&ihgVK=gEXBy@)yavmZKon4J=sbV3i<<{x}NumIbMLRZzzOT!Ixd@>i
z3})e2j&M>H4*NFhh}{^7RxuP9Wvh|uP1(ebE6H?ZMbWe7r%r&ai1NZ%4aIGAS;g>e
zlOm+16)wxvIe2O9f9MhzKV0ep>Y)PaBK(K0zbnQ5N8Mj#Vq<3NfcZHx)J~TINuy<j
znFV#e<|8WDnusIG_xPFS@M5%fS*fk=0u^u^)-8gMCl@<Er0=c5lyP%qB^4?DCyw_{
zoM#rRe)cKE%}$MU63l0yMK4!{pZl!aOf7FB#Dqz4+L%ins>T?Q>DAJSQzwFXG#O34
zxz%48Tg+y)zt2DSkaSR~;7gF*8QB(L6T)uQIc0VR5wzR*k229VcA%PYhdrd%u}AhD
z;jBu{Ait~2tI3sjs0+TWyn+3*L7O_{<adFBje)|k{~`R3<iE<-|JABF@pbk=%;@4@
zy8CbU##r(oEYZWIKxk~1Wb_C;{3&e7*2Q8f-o52{IZQ^rRJ&d+@!<;|2HP7}&eBrN
zQIf-`e&@>%&F<{sU?&^pt>zW5g5+rnq8K6Nc6Hx&8mU@<VnigrB|OZSx;feCw3uur
zld|XXf;t?~#~aHLoa%Mmj>4qfWJFCial)po)a#V>9fc+Pi3wa)>inw4<&<frBy#RD
zKg+sybt0Rt&ThA-r<JRq)Wp!^ghJd1c)9cm*{VK>sM;C||3K`FJSV?5{Kdb;;>})P
zIu8BoE|v7x{}`pk&xS?V0Ow>PfZ5%D#vJx;cE)DTz*(6;+1-@pru`l_cGq^PP=bVR
zQ$!Lw1bbtFkh)%s1X<G^2qkvyS?(wc^Tw6zrO6asWsYE3B%2(n`$P<y-!{*?58xH@
z*Xwmq;uc~Ax(nx3kWT5gDE*P_<nsReQ`!mT#gj7Z8Y=4aY^$G;)yM98+{|y3^?68C
z+L}^oP2L|=H>*FSGNNtyVz|Ql?^E|Quaj#I>?X^nH0bcjyk~~y-3fL~H6nIcWK@RO
zLTsT`zULLbvU0-h-_E;bD{h*oJ9XBCQ-zoBM1F!RZpW|*L9SUpkZ__@+=HalBxKi6
zoVyraR<Bj+b5dE#XCYJTwUm_3m^^pB6N$<f3zv<YBw-_TpfP5po52h(3*?dI;^sM9
zPL_w{qL97}Rp9JU@ZX-k&+zx=z=vg`@yiIJ9;2(VfS87iwTy&wl7@9yp{L{d`s;D3
zhzH}#CSY9<a+^|;b0hXLqDx)30__!1V|VU!dER}9-@&i|5jjRu!Dbjz7g;SqxwAA^
z>Ri8xs#U7kzwWiYxQpwH!bIJnDGmLQEXKMpYjeQ`Te^00>?}jVuTMWnZk?qRGYYXN
zsk5dR$mOMQvb}mU6uxrB#pfUzawJEUQ_`Adz~9m@iI8c_Gb%;XkYn_HdQln@2w1m%
zuK}*WwWPQ^J;)k`Q~pgq%qm%BRDK>zHza(*&ATmNZd^h!D<-bFX-BMc{_fx@obl~u
zeeHJ5qu`in2#T`KB4+5@ZveNe?uTg9<?klrbH^v+4$8XYn4wt006h3EX-Q+MnOmWX
zl%5^cwCZkYkCpp=Sevfd-K(x^IeoF1u4|EP=srCSz2SopZ*e9l`y343A6;nOeG$m)
z?qKk}rf2fnjd??<$mBD$Z+Aca-ail<i6V@{xs%G(Ib!NwFmHVFJ^@%y#H?P-!Pv@k
z>o8O!f!S_|(-+G9jibxSEQNwKpC2(!KNV(8Fh6fk@!mG+as7trhN3j+I;wJlI#Oak
zKM~6G`MizOanqz`@d{IoC|4aCqnE>z)cbYv_bP^ghlbBK!B^hnidgrL?oaX(@OXH;
zh|r*l`npdZdN;03x4VM8dh~2bIq&vf`?hU0wRt8MhSfNji@p487u8UYS0j%oM=QNo
zleNMK^vnaDxU0SJE;fewI8fGxqHL2qA!}40`CA{K{@G)V(-9m+1Ft<*IR7>FvNJQa
zGGel_GqNyaVRW>&xYYd0pS-p%`1F~JtuWoYOr4f(RL2Wv?h_8B7?a6r<2s*=k(4H?
z@kWxC5=lpLOYJ(^8irR3Y?4%@<;Y%XN(5?2XL5w4$8_W4-K%fz@!jj)YuCr-arU|H
z%2WHaTlKm3l^EBzhW5-@To9qJ6XqkAAo1xSc^%Xhj+At-rpzFp2Aa9;H&7Dps?QC|
zXSmLNKHM?}MzTT!I&HgVMI)lTZC`J{cAHb;h879b75M#n&iK5<qI*qqmBpt5rvu?%
zoEtZGETo6@zzu@@0|rir0TSB(RIFFa1s$9?08!p~8jSiYav_L6-YeP5&jQN%>&R;5
z0Nzon*n*`IRk;dB^@pi+SA;mhk3!XuRz}iN&%!d9{f0TDhY<_qx%c5OyBKV_k|y=h
z0H;lWGR>WU^|?G>S!1$T_2@Z8#(k)U1NFOaN41S8sGyD4OAHl(ozZxu^BGI@7b$2v
ztsQ_)Zs`WbWe+F2%#vM>?PflFU{Y_XBct=$B$cAAsiVGOZn0OlgibHnCoyg+GQtb*
zc^TRO?r6b~w|dU|>a(^1mK)HF;MUl45OtTeXIzQNom>YD!a8br2#0Z3f>m8Ww{HL;
zcQ(#Y#IAEu*kil<^L4xMZIjjSC`UU!-K_EOJy$0lxf-JdLA>Xvp=CSo8X?nEV_CUz
z_tNK_0%ftNwbM0qENQejswJ=~lwDDn!@E9Vaz_r*$!&dXb0rTspW@b9vtrDvw7$|>
z*B#C>kz{*sy7h`g^uzDSYa++dZHU3pVtcR&dEHpvna(fq<E%)(HNyw<h2qG92t7oQ
zlpR{fzk2M8tuqcQ2un<2(!qWc>=8;Ut_Vr%Kq!HH*en9BX5U9b%A+3BCAfJa6!Rjf
zU`x}(5a`6&TiImO*CnHz5DSz|>$9_Ix~AK6fP;+^Avtc;4GJMf4kKrS)9elTAqc0S
zjXv!3%kI3WTy=c($tQCCl+;;^A(UbLeem9l%%J8X(8pekAXJ=P)0iMmM;dLM<LOwO
z2@m>S0`<_v{c~@vo?EJ>m>ykuAyoBce8waD?SmE<e|%R4#OQQ1G-SIm5?P6kQt7#m
z!IlQJ?T_eUbOzl>S;tEiaZ|JR3u?d@zjPX>vmWBobRio`B!)Wa6Rk|7$P(yI8-!E5
z!Y?nh@um9InJOj`ZiIwl&bZ8SrDn7DYGi(=Q_xC9*_7})ehCUzcJ>titF3bYl4RSr
ze%m&uZQHhc+O|Dy+nTn`Y1_7K+uhT)zP{((_s%`@-K>bpsEk~{tlSY*xpU`U>u(*5
z_@k9V%>>m#CQ-KxNHa1egSq)GCs7G*Lj7Y2^l>OPuHs<CzWj|j5vg6?pRYD10LhHj
zd|Ug>#mg{F&I`30FKz9|7Lo^4ZoS};lZJ7TSCnTy^QGiAJkt-c4w598$7j6YS1?pA
z!Pnk;o2_b4OKOCDbUa)ou)TKwAc(#AP7f>8RSB968KTY!e12ppZ8PwtO3FD33eRau
z$2d;r+cL5i>L5vTb;_PhPq5hZC=8PcEanT_{d9~#B~`~yM;P~Ozq1?~YQm=Rnci2+
zS7@I`@^<D2@mzMM1~Vjo*s?m50~29D*71q``{3{)&pFgw=b9?eYap{m%Z3-ZbSOuT
zKKcV{S6cM)<z(gHR(N=~hwNMhwG@!Y5R)lEz6#xm_&Vqa4NKJc7R6h#++v3_8WB$U
zYm#3nruP#cFMh^c0ftiU#UhPYF}T$8_gESd1~6@F$<9{acNQ|hMBHXkypRTsi5vOp
zj=ZTPEWi+tnwy69m8|(VQ2Q}VBYS{vk!~m^<u5yaUig#)ovoqzTLk5`xSQUq=NFy7
zh(lZO3x=~T(ef>ZLYlQ~%E&^hz7ApwjV&-kPMIl7-yi(0ao&)E>*+Z<OC=~%(IAI#
zI6elxT~cUB(1(WHI74WMK2m^A1&z?e?z0#Ymj%~Pz?$8iG$jW9$}D&_WTiZ;y3K@b
zp48&1I-u`mYgSq91(X~kq|sWt2;=%)$*?0CKTX1H?aFRrxz0kE)=SUls(tt|YnrC_
zRmr{1qh4xrm`~5k4(VDa3ZKdgFGPvsH&y4NOS$I@eZ2!Tm`w8))T;Vr`))D9!VX^7
z?UeW=Lg-ivj{k1f8!sith@EEn(N!TvC6hjwRN9^S<VfV@?BY43_bVf*=T;A0slGxc
ztB<uoqtTDupMAE2Y`5vAo;v+JQ_^6ab`pKYL`$bN4MF!=aOvwoq;xl@bBV0Jh>BK9
z)lW|D_BTMUn|GOoiP4y>bJ((u@NSy<=JdwRaSVQ|Jwv)4DEF3PlFl!eC;FE@DJ(Jc
z{3b2k9lt#6%`^n<EwnDXc$Jnq^wQ{<y%2&g{7KviuY!z2$a&^xUxu^s*woH~=x5u3
z5w$60%{r8eH{eGq)?MWpmoB*ZrQfuOkm4?DChl>23^O2y!$z8rPx|daXkLF5e8NO?
z`^QHBEtpSb9q1@SHJCH_VX_z}2$F3YqA<AGMhPvebvM@8t-}pDSnR@FFi@Q980+}W
zBqYR?ojP)I#=*rv6v+%Ng4lsLv*jm03Y{}lkw9=Rk@V6)ixFz+8=TJ=%=ardh9QxM
z&MClMGZLMy3*b8TV@NJE45m^@wK0vGYBeRs12iK|WiI$O$BN%}EuuTT-V@T@9TLHu
zT~b?(V#d;rQB5<=?j;x`pb5FGeltI{rxQatlcOcn4RTs38S)=lQJ2zT;80<Cz|OLT
zVLGEiY>6w37JknARcPrLfmVJ#^nIMpl5k5M?`+DEmdKMbJK|UUubJHW1B%UIC>c_+
zgt0|gi;r*BVieFChf$ky)z1RPFgoA6T#t}ydTb_9qzUptR{PH?ODYRfvJvpRFxDg|
zj*n$%0Xt_55`KtmQ_ee-C3#LQXQ}ZI+%`SLtRA~(07ULK8lkvl`5s~CEho+)3r7+a
ziogoEunR{_+<(pv)K6qfiD|llH0KQ1amfk1MX~oc3a`E>Ud_b_aZBV>bOG?`Q#X-J
zf7@}-;E(jjUSn(u>&D`YuPaK*P^^+SZy@VlDs1oY8<{<x{VKeZ(Gmo3$Wwp>aiU5&
zS^x8}8keFc7$U7N;*cMw=hn0&%ux)m&pMHdR#~X#UIMw_h;Y)8fS+K}Y$hjPs-%v&
zm{zfyqh~{WTxi-YxbgY*zGi|w9+<{a5Sr~HX*Gdhds%=2nv&KyiV&(b%k_~On-E7Y
z@%k%P58WW4_8iiH6LG33V_^Fpwf(JFn!<(;V4pd2rq;qUbIshh92U2L6)k>XD=$T2
z!goZ?AyO18UZ{CLFn?mep&we_N)@>UQ{Re|%#v}you?qALwVmQgF<IelgyE35$P;P
zO)S1-WQ7cBRTE<@0mp|~?~$?>m5`n22dZX3lRM6?Y&3kU%OmG5d&Y#L%l(ahz?%HV
zSH+X++7trT08WeNL82&^9z^nvuqH{@l4bt#u$%!ea}7kN_?%_Cq*E_mdb=o%6dKk|
zQsjkX#Ll{Q`8U)l=_ikx)MWsHeBG!tw~CmONMayigx16~MYb?jgM`>yq{`$}X(wX0
zB>q}0?{YT$FDD+!6T%qbhSc_+6Cn9}x}%C$HI&MkPP0++M^~NnMaGLlFQNVK42b;C
zlu6$?wNXIg1D{ZHQG|9^1>B8gvFxH7gNq{cVx<n+rNm?xT-<C02ujkQej6@Dt&R-E
zs(2W-59?;3C0r)6)Ll2*kB02=g<qAM$>M(o9t_N)IX(W)M~p|w;MWBSZg8mc|GhjD
z=r^;MYeoOGnwvc^p3V@v;D)U-weF@Cd$htt=WHH!yJ=vWWb=(snAgj>(PGm3L8yBh
ze9i;VFtxVo;zk@I8MwDX$W|#*MqOl(b<9r}ho4iY(;Dlgp{--vwFt(1hJU(w#^WZ2
z@IcF@r&;~AFojj<f(f9;O`(C|bZ}npwgFHibDd745=v?-cx(Z(SmmUBDo9gV|NCpl
zlH*(Y`JsE;p5gDIHHl~1I<kRYOhccfK`CCH#t7>ms^s(4$ObvUop(8$cn4nXUQ5YC
zxXB04)oz!>Vdx>)oMe(1vS=&m@}C@CjRtC0&qGRsN)XtNy~x{M`)#T?$=o$G1QE79
zrD@B~^JMg+K!Z}E0}UdD)Cy;cmZ-KE@=2z77SHA!&$&BY+1R;G$~7+<3z3HHFpwrh
zW>-#2=Nl{9V`~z#JmjQNWyL%kd^?WR09X~aY?s`qE!m>$AJF<TLi65cWcY>;UU?d<
zi%RB(jvFL3I@M0~+#(O>;|I&i8>ZJ1d+HI!YYWgJu2ZJ&`Q0*VoSQ`*7`O6T&o8+1
zwP=Fhr<~p=c-ju4w0V3ilp#|cfL`{Pw-r{I9f6`BdSgXn?Tui?u(v~xuu)Jkyu~mf
zNx{v|PjTih($q?(wKWN-mO$;7y@wN#c|TSx%R)evWrQqu8Y@fRp-_Zt{2M2wyG|O@
zD=V45se8DbvXNJgfKVn*kwsH3pJk8sB%=71cWr6fm6ud)n0ex@j|QV*M?Vd_=WSyj
zDnZ|T`b>uPOh3)H$=zScELb1rlEST$T0Zkg8e7ewlWdRxfvlfjxZgj>j9$HGk{_x5
zB0aVk@7$ST3v=8Cyr*mOw!NP#c4pxmerHYwGLYF%pU<m`<)@{NRVJ01zh~&h90>hg
zT&#TjD@7`FKy03{k5_ghThiWJz_21PjAvE}Q{U5aXTnca%IJ2|CL`z)m0O;eu`rbD
z1K4dn<UR_Q#HCml=MhdBhaE_+b*LP1z17CU=l%0RUb+$8Vr)JYhc3yQui<`2dmNjP
zRL1Kx(>_8Qa<##vPqEvl%htNO!ipAJC-O-(7O*uLvv^Z(T<*KhT35c)bS7mkpjvC~
z*7`4ac-@Q`d+R2$Sja$ZqL5louYfCl*@CIK_(NSJ#wUYi?(`FJBCl=ODaOjLD(qRv
zt{5saJneNF$`(FH&us}Z2HA{l$jR>dMpPh|I<A%JD@<-)<Az2CA73@~s`S&_Y`Mbg
zjOK*)ut|;gvO(GO_4EYN$A|`j(mYMRfuCo`X=_C0u%=1-Gfu0epv2FA-D-8rw1%L}
zJQ{((dXO+Id!HRswT-TMSS`)<6DV6iv+o=AtV%)if}Ce(Skzm-cBD%$ix@aCLSePL
zRIoE-_iU<WayiTc7?78-EQ8J)GyIqf=%Z6iM&7CJ!8F-wqgpanoAzO|AQS6`iB%J&
z{dAjXJP)UC6Y^iwEvwUx{!P<}peZ=G=yK@@#REvj+v`PDOZ7WT8|Klv$&yTjpH&Ih
z{FdoeLHj*+@ynqTuG&)$08>`9%f2FRW0mF961<EtKx!ckuUj7$hh2=*e!pEgE0t5(
z*La_*1H`HC(4gskt$DUl+L(`?9%M-m6;hxn6XB9gv5>j)`OIO43s?1<7WJ1yC!hO~
zo7_)T95=UptUeZqIOr`j)97P_I@}BKuX*>&g272%@CZLI^M2XFQzb~yJnUE_n2ZVx
zsQ`hfFX%T_;eqyzR%)k6;Q-^p>24cXFY)ky%g|O$8PedeQFR8y-wJ*cjN)}gtnbMx
zA6j$mHaQMV0Kz^R>Y)#Vf3S0uua*T|)eB(KXuGm)D^{oMJ=sbNN*i^i-kE4LjOLhn
zCY#F5@f_yce24*4!-B!SQJGi?gl+QmU<BP}jHHznLrsGr8GDLw=H9j$Z=%v8cMDAq
zB}5^fE?8eN=w_hPYh0EzQ*gDFZVYEfZP<5+(Y<3=u;CN~p6gm`qL{BP@a^&24>Z-w
zraLCEUNi`gz@eyE%j=Q#{Hm6v3Y(Zt#UIA&X+Qm)V-lfQsK`W*F6xvZ(G+msRBV*@
zmosdEj3o|*PkdvHzWA#5aF>fGx0kP{?8rOPl^DCw$c;bx><n8Pj4aX{b5OS31La$N
zUVaF&`7>{fLRJBU>QdYWD>+4>ILyd0x@3v%<p73=jo^XL^!;cYY4<k>b9KT_XpJtY
zj?M$|7E`O&ppus}!=v0v+nh?R@ap=c^;#?e8n*EMvYg6F7k>-6Ah@T-yfd?DRn^<`
zQYfBz9K(5_+#4+M7(DdWj3dQmgj}lqVcx`*Ys|bP4vN<pNi$)C+rA<N+Vm^m#}T@*
zXLp}dkWl~M_awXDUmE+N**APvpIdcbAnZ7=mfG9}2q!EljIPnGw9lcjs6}ea<^%GF
zG0L}I`K)y8EE{mx1(4VhFfWS^WN)GBNOJWBWO(Jga9Q_Y4yeW>&g8xAL8QAM5PbTE
zJN2Xlud*{?)sed)UwrVHc$bGWMR7zKE~t4A>`6V5`Zi4qRFM^g6nG6p*&&S)q`{e+
zaF%{9HUZ-4|Ikv-aEz`hvAwE#w7S%&WtV$at3|(Naq2N%MxC>b_@+);boxy~T16JL
zyM%b=5ED@yr{vtv0~gMC!N#WbLdjO55OI{WVdkR?$WnaV8YHD@z9ilpR#MOJFcFgr
z&59$v&johxgB?g3|8?>jTGFf^3xsU9J<6(Ekq53?&iiRN?xpYAXu*9<7#1kNk^h%@
z=juRuJIVJn{W}=H7GM?cw(*gWi~7P}M8KoN_!)ENBPEkm!kS<jgh?6!0?QG}xVIc_
zp3o2Mimnq3F!jARh9zA_Cr}dux~=wchqLhoZ!+Xbw%yLM=K$|9?&c1SxYJD_@zeaG
zekDof@KBx1em>sNpF}S|k3UIP(IXZevFcd8Z~`>DlVrGukUXm5KVknleCIao<V=SK
z0Pt0e?(eA+|1o^W_&>vU=G+NqTV20Bf?H@<0;p*)+AORJ^QaABCE}n)bP`6*YOvX4
z$nqe4Vg>i+W0MraB`J!?2}LOsW|j#@kQipJwB|~VZrfcqd2F-LkD{gyTy(w99$(%&
z`6w!B&yFN$<3Iq$9UQBjfPMKv0q(o|bN8);k$`<k(s8US*7I*V9j)3oE%E%iuIg5&
z&xM)4z4yKSP6G&Nl?_?msgy4?DaN<~A+wxwY09Yr+n`F3fsk51xnCT+mu=hoCXUCw
zW*ZKmM+K1`=bx5cIs@1Z`<)OVWw2}L^HD6?C*p^pQ6hWiWXr&lLa$W>qH*jGLkhVr
zEBRnfn?{OSNx&uJA+{>f>G&E@34hdG2E2UnYyVDtk?jsrKlOwGqqNE9uptavtLGp4
ztC2Zxua?#Cuz);nm3*9}HUyV%&m)F8L@&hZLlJd&B$W%*gV5s^5)%b#oMOL&FQv9<
z7<=NvcCTNfkfp2A(bOkk2*PMD!p+p*se13k)K~c@n&sS64(v#y^3gaC`Jx~wl!WjD
zl74tV%01UI7p4hO$19yHPiIjo)b+F+_9oWI%)hFOU)S&l)oake3t7k_)P`S6^G+ZZ
zgEv)n(l0G#3+}89Jt)Z`6akN<+}%n--IvRQvK6!H!a=J@r>y-}BFV_Q&|UJSX-4K`
zXH^`?z=bT+D6@4M;gUEPR9Zj4h7ki@N~QzR(}<W{xzT4FDZgpK9b|94DfX#V>Z^NZ
zJZ*eZPFx+2W)Oafeb6r?(^szBYAEe>C<C^|va!O9TQuVC;2wP<rh5++*YY594}f=6
z9OvRIdJEaFXWfu<5US3@P5Ri4@0JgJHB9h(T#~T2Mg4wRK3%$(Eso5M8m>SzE`4Q?
zwJ!slCw4M_@KaUf&^j_k*yz}5cA$2OcJO6t+CTGL@x2okIgsy{qh~)F)yga}fLs)o
zlq%v}>lWzKZQPr?4arg~pL(-ENp6T)`UW00i)3P@a_-Z?P}z^d#+c_Z`?qhXa^F&T
z&wtUodzy{=tShY|9?cT<o+H<nzvtCED&3dG*%+V{K19wc5<9IKwHgN=fJb!!iF_z+
z5h4z#-VBZzL=8TG+1T5qaf@y->$<g!UAbVaEMwx#!?}ScT1s{($9zA?a{CO)dqNa=
z2!KW0T+|j?HBJV3UfLQW|ER$hx%Ky|>GSE(kNbgZU8)ahE#<BvobnLMWgl>ZI3?>t
zC~+Iwe^VqW2|-P&jV$1U^O58wn(6A?L%0A8UzpQvk~w{OO&J$#&B*5ckxUU%nC(&a
z+K63wNHBcf--c}+4!wjrY-;j=w|6+zlrXD}=MoHwgugn<7Sqr%#8U|?F*cmD)0as^
zUv8h5U}H^E*!&HRo#%FgJWU?GCRZ`SG3Ov-ttS+e${?)nb*NQ?s@a~yTO6<dcEh8s
zRD6Bl<)=IwS-^0bF&htAvk&jWjkGQuo#Y%aRAQ$v*nL-=^x%Me-cV!DxfX7UB<=0f
zb1Y1g2hiYArgzw(l1=o>#%3nCm@1zZRN`RkSP6zJ)4;e2;jo<?X+`BPWq`c;W7p-d
z?17yvjYY-x>zFMDUzoo0gO-lql`%G{BG+a)ZiApnm+Q&fbyP=lMkQ(ju1((WQt6Ux
z*;P{ylb#BmK{A6!0%B-Nln)v;&0IQ5g3F2At9Xg*9R;3-DRbaaX$5<{*MbLacn}0`
z0I6>ug)&$B&%^7hpcYd3Ue!-j<2?)?`T6V5^!wJ=sI%Gk_t~KISe6zC_MWkbk-hq*
zb>%ixCH}b8hqiER$0A4jVJLFnENPb+4SzcqdU#GT*Itr_VJM`VRf6?3@E+C9tXmJb
z*fmNe9WK@CCWQJ%c1ou$MSR`##NwxPrif;qji<@v7g(GJL9!)87VhDyt`>Ios&@XW
zNOq%a7EiPU-ScE4RzBW3c94$*tdq?4>r!_@PLKsA-aXw+oEtMPxBgumlUvL=t*9)b
z1}V9uw!c*Zq<16zO5bI)k_Mf0CVkt7YR{-0UFEWxHjUx}&{aK^#_aVAd+~5nC7_du
zVS9*)2EOuh5wYfYqci2L8w%P~N^3MVT9uOTDYZ8zLauRDG!x~n=`s>{Q@|*4=bmP<
zR8Oa{XP}F=4TIS6_ZuT>g9q02?;t>_GxDzxVAI2<o8aVZ8ltjFOV^1Y*zyJdDsrXD
zk=6M-s{y$l<9xg%O<%6ZP=y0@I<|yg$6twNU6E5gI?1<HY|fEZ8CYj8tr?Q+OBw8k
zG?EXqxz_Ny+)zI;Bla4d>e(TSVUe6|zpXGX1QnQy>%mNYT1oKfbiF9ZVsWKvdXt34
zqblBuLA3-)C&uSLUCbfocHB1iim__;a8_Silgo*wCr>+8-B$Xr`IQog<rbl7=h5=8
z65dPes8>ClEP9A&^x#oKwdtQ#lo277_*g&5xi9XcmzXk+Vil~GStpegs(=Tm;H)#H
z>^Q^mmTN&$chpq8YGi9$LZMv{{hEJl)Az}+Wn>&ay$EIT+L}$Fzr{MO9TI5!(c8Od
zLAJ=!5rY$?-Lt?NSuRwDy9{4i8T}MD8IMrkq?r_KE0;r|mG;VjYVwTldLG)Cdht^4
zJ?0IYU)A*L!3*hSN-65F>DR(4<y^?bn-Kv#MMO1_2U?7@pK!ZWp|#v8DM-)QWGY+g
z<exKEbwLl1(V-88Y3E;g37PR;!+&3Y;@Z<WN^y&Yqz!98ooASzxOQg&smO6q+X?u%
z=@P=hQJoDe0b%iR_M*Lp2Tpt4(bnOR`w}vOk|zHoF$P&qFC2qR;6Y-$v477lOj4IR
z+CuiwB7R9S))>Q~l;X77x=>8RU=Nru$0^N6w@G+*1a6IK&BDbbX`0fZS^mO4&7~st
z9tVd;ktIl&Z-9g{nOZGl<(x3OXKI^QKOtQyOp-1^V*2pt<GW2tXcqNbMwG`G^7(qE
zY>~AiNZ0K~OP##KWz0}LwX$5&wm;aYt}H*KUo6`a@30wPA?VQ1!i3aA%-Ltn;UT|u
zeCgyN{V^e8j+kEZ_**{ckBTZ?+=Y&|k)j2!`GhA&^zcQcKy)xT4Q)>s37Yv8L|qtU
zOQG*>2SargBVB<mP-CY3{7H=>*YW<P+xL{s!gZ}ULCCE{3-xC+lUyPes}^_I!sY6g
z&?^zy61R0CVZi5O1zk~x1P_2l<?7z!l=qY6@Ho-PEW*3|v*cnm;!(Un*(*aR_R`&i
zj=iAZ*au2vIBMN*F@b`&4Z})(v{V6;nW<jj<~Upl7(ff!zKV|c#zK%f3DS+1K~}(U
zm@kr-0S0!#ov@<c4a?Yn7salOI#B0;d)zl+DP%;mWWhSLHKoU73hr2mgbl0!d5)r4
zs))(E46#=RaWd=^^H-XwT_xh{*9`QiU@C)Q3$@Q5KW!S>x4iSU?pum?SS&tiLPGK7
zrC%wlL~V-qV~h>OXpf*wvL>i`EBJ2J4rs9;+;uqNXlsCZfdXzR3zhn*vLP`nxfzOQ
z<HNPUI-zdSzH91tSRSo?96^VUq&covr_;mWR>b7Us{?V9ruMoBgtgNCxO3Hv%ni)}
zs5bg_Hz87538qQ@_I#D@g`;g2@tt+In>H249!F@Ngd9MA4#3{B5Fwj89)uOS=57v%
zn=nXF#$N$*!2}wUS?U$Ns@wx6EU}9?4YY!7K8AF$u3LAR4)#S<Fe5b`q@EsX%M}K3
zv}6YU%^>dy%~Yz3L_~@6t_to&9#u8<81~k#sNUD39$eo@Kq@j6bnZRm@KKP`F#a*<
z*sv6S(GaDJCBkiZH#tmo=K=+gm(*2m8LlwA#}es&*<K4Z!EE;Uq%@(g&d3PZsNqC8
zEVq-~C>tiRtv)QQ7IHm^oS`&#BehDC>t|JD&ex#a9Oi+TABkOzjWra1fJ`br%Bd{v
z#1U;3>YgElBo{k{rVgI$oqWh1N!8C~3j;s{pJH>??Kv9A*lXAZB#sY=ep&z&wHkO*
zE@F4Sq<j;5rAk&DnwlbBJ#a*9uicY=b@{U4re1-R6OJ$vuY=)$E#eLR6CNg|WOUl!
z+Yntz#kr)gh9Ez;bj3X2e^kpn6r688gKjhI>$}0ST}fZ^^?w`gP5fDTS2i3RJY58X
zBJ}!6^Fd2^b6NH}ydzR9%aV2J=C)LDs|2$S>bhrw+uP7A7O@hYzrLT#u_2%3zCS|2
zG8TJ3x{_I){eVFrzQNydKi||CHxnYm6k0~<U&L3+&Z@P|ZbSW6q;79T+!`M_R9|<9
zY%^iL&c3m&#Id$H*RvNyMQrAr)oPe`Lk?BzRp3P%@W|2Kymh?Bwi-|p<DiJ15+BC@
z^^8x}1O5csFzuVtJ+#2^ci$8gSrB1w^ERI9TOt%3@UWkwT*a5@e3;%IMCSw2AM-)3
z4`4!|AT(2GyTJ0CNKXcbe2VDfE0%UoLsG>J%5c;#8uTLD{3d%YC0%!31z7{nf$(&$
zkA^foniIO}sPN6xcpa3sU6=KC9nVMlJKZJUT9~mj#<oJj-px73z53e0u~jr4*@l{=
zxR6Lw1?WfBhIt+qg0}WLU{X%mQ5&ybX%-NX-f<E0UoXYIG}BJ!m<K^F*|zlr)C;~J
zM+_`5LG&RB{A7%#+ZV2G!U!iK--($d?BrdWmH$-j`JjlibU12DOHtQ6K}1r0`pG*r
z4+kGB0|~|Z)5T_qpl%nqT~U8V`T+Ws&)d+ymW~6p)3+@B$c@M;yjykVqcCh6Q88;y
zZ_FEQvr|IX$0Cvg@hWUdJ_?oeZ4;WP(owsN{5|dpmD103O!LZadna-&sA-0tONlcD
z&v-M(6FUNZ@aQ7jgEfG;44=HuX?Lp8m%;&qrk_#Oz@b#mLhKD#`6`HzGG{7qDMoUN
zZ-MG@?UwLCTy;SB*U&V50%~?hZ4B>c#}I0%XiB17aFm|>V-R?8L3ek4_k`u%p7)*C
zFdJDQ>R`CVVE|GII$<HN)-NR60617d9}>`b^}f-P&XP-8frzb~0mG~*&Ft>=UKxbv
zF6yD(;P&gVlkTKd4P#&i@4m6C7`g8T$j<Bl-Jhn<+GWi9l3hQOZ<2{Jh{zGQo`1-y
zIk`l0@Z9DGgG~0w#A@Doc^(V~wz%Mefq3$I=Dtt`bx#2Z^ljh1;A{1NC(ldDz$5Sg
ziLddpHK}jaWSTuCi#E|yIFJ$E4PVdW$=qv?#@=h`35zT*T<%as<a>yunE3PnjcYcU
zHAdyKF&`?OXnCK}eZ_%CDS2oGH*$AL26vgV>?3!|kg5!G-+S*dr7^h_zPy@oy30{T
zV8}bK4ND8lucfXDtFG%=3piGl>$l$AaW6AAD7O?Y-Mvfy!GdK<1e0|d-B#1DHzp(9
z?p!V_^a>&qPh#%b;xc|ImF^!7Q7*<KSD-tb)9T<{8E$y^goC=hW2<(XydKt$`AtcU
zbAgWH>tW^~FiejG`gVVu(SEY8K0ExT#PE_pjSi$1l$7llxdSsg8(FES3ZO-!0JG^m
zU)9$o`O{#r^ZWISkXtDBdMV4AGlC7%c-)}3Q(Hev1voeMcn4MN)DN_P4W__Fv+y+X
zc)BtdME!$1*TD2h;yMWvXDwtoS-)6#q|A;2Suu1i_Y;q6f{DPoL)I~gsz%NT5)&#Z
zT(4Dg`Ldm}_s5zSY4uOqAp%iDvMP=M^deQ)Y1+bqr#60#%W<)(@9E`Di7BG-+xNgi
z1q+ia^p3cSf|Tk}lQoOCNd>c4<xK}w>)gj&VJX)vkGn<`rzA}<_u1y!Xn}dgKf{EP
z$ucIdTX#yjrpGnTD_)^ib#8%?ZsbAl%`8!q_Lx+A^vGug8|CiAywgfk5QQ_GWnhA&
z6poJL*QUDEP&Asw=in;16g(wSrp~jo7+OEhrF;(cZr)x8NDgY|b{Z)vA&f|EwfK(C
zSNr46y}oPTng%v3-zy+xkol0gy0ZjqTRsQFu+2_=uEM@pgQ?@mK%o1u^0%5{s7Stl
z3;wY)BfNynqmXZRXk)b+_3=%EOseh}e0i*e3UR)f)1^%8lU?EA2?4ihts7bMWr9On
zNHU~2vDs1?XN~Hxj6%pMp5;WixuaKaMd?IAAdlL})R_p>ocEM@RloGzcoR1B7G!zq
z305bhLj=FRu2Bj&nmxG}$$@7lyxO>Ag5>nWP&fP6rsgl4S%v9kI>k1v`N8CtCUWmG
zS8>qCqLeDQPyG45dHt$ZRKE1<#)A5Z^d~L6PE#YBQn-)(5xRV(zGPGbVMFY2f)(S)
zkFv~SSHeb2<%;FTlF-rnmWuVg^U0d&V7p=Z=4Ex%U8^AQGY(D8C|(fj7IxM3WDCgW
zF*pz8>~p4pb%a9?g3*-<#N@NO1`mQ9mwwo-cixD;;470)^pYjO{$kMpAM0XGekg@}
z+0aueaH;Kx91hJNNYpPUG1jTvwk|t-SilI#IU7cq1y^S-*8zkkwJ!z@BfLzrJzGTF
zwoSy8fw24d#PAxY{pK{#S`TbB!y__zWZet1us5}aYJ^Ow<1=p)=PKym(`mL(^&)cw
zG!`>5Hv)~+MhG;^t-LZqhu`zROe08MxbxfiyFS#d)xmf1pM~<_4j_6dFJ%;`tTgy=
zV6sG)`glrp13D}He&XtsxN&O~9LhG}i23X_&DSi%szAiutkkU~L3G;ik|A8HO@$VV
zQI2;@atLt^Cr{BvlC^1|A857R3#a|=>dG$?h<k|wE&@v;k!*NUo&fj!b}gDU$CMj^
zyPo0&3+2xdgE5S)q2gr>%Ru;qvjHP0$gk`<;D$Wb5wPZJ+ZA?Y*9v6Lqb0M71Y9~K
z0fJbo?J%dS{kx*h$b$BO_DL2KOMb0z85f_t>tK?bn6@xP9zD^|7D9Pv(SkhCp4b`3
z*lQjB_Mc{p7(&8jBI1?<Sw>>#1beBTw+0ZeqBK)sFRFolb9ogzStg~DP^ri;O<_Rg
z^2O=&G4KORV=RhI5;5;+-NpuObu!|?0L$Px$2&Z^wW+Bd)g><WELWsjNWXo?3obTT
zLJI_N9LqCQe`y!=;$jHKyt)KL`S;PMVj<D`VNy282bY-Wp*hc1<|f=xqb)v=d}=_g
z$RU$Z8ejI*+ZzJF0u`*R6jffM`q{!^Vzv_r4DRh%B`JEeKQs8j_b3U<(bhx&x!J8+
zV{<~@&vR5ysPs~Qu*1f%DQSWakx!SwJ$GxU-xpF~Qc5W-t5e5?O5B!M(9yIZsIu-W
zW(&sAS*%`0(d(R%mI3)QKxK{EyABb~m`_^;&t~NV=e(itJ3de5dB|EGBqR&UZ3@8|
zqFT*aCT5|xtO|qbgxsZTJZg;0FueEVDwEpOj`D-Kb6x611t{W=#7?-_al=><m}<}A
zR|&8-xwL<fhUdW)ZAZrV6qWbf_I})U+KoTcyMjX2zb57|Yd|F>rn=6dNiObnt9exf
zBo{$q%;yG(Xut`_L7?2-Ggz&pi!<%l1iL;Mt|8C^UT6JwCNvgc_y63V;S<)R0N_dZ
z9LfFU`S5sqeCql(H6B|YfSbe|2ei~}3XF51WmTp5O7f2W&k^P*EJ?<buj%Zru>XC8
zndx66%x5rH4o3%Zy9RoC+xK^NkY8&RJw3hfZ9U-daY{={fbcbsR`y_}aW{`wz2f@(
zP)j`@{NyEln}zKt9FJb7!v_fMc4Mz*!j20)!JC@PwJKhh=W71#@6*cf7hQNhs3v-L
zu2;{{)8*i3)HpCO$RK`2T+J*1pv0J|7#IqopkjZ$LISp#kTrwBG0%#8K6-l}E6X>B
zvi&Y$=+cs2VPUwNnhsPLo{uV68jL-2Y-F{Up0rIWuiCs@Ys14jJe%Gboxp<M;g{7g
zFl6l@=;_JHx#;Pc@AkP|_t#nLtd+LBtrxk$g83p*T6<=bvwIAd7A<wvFl5j5jEwZ?
z4gA-h)HHGkt{+%+Kk+~>A5AaYsV>j8A3H~9x3YT#K}Iw_VPW9i6RkN@O}PbJXn;%o
z0zs0yj1o9-6171cGg;!M@EpP!tYW}GBazuHu!`uJZ*1Ld_;x(rBi7bjoqUp(3hL<J
zOu;!pOlI2y!|<}I+0K2QvfXsLm{;JiP;pRk1pQ4J%P^vC0nlK;3#LehrZ_sM^12%3
ze+y0E7BC)ubaISMz=QaNc9MK}=JP6H`fSw|S9QHsb(O;~lRN`MKjPoa|Jwew%@4WC
z#H>~SoG?Adg_z=p!L9wSwa7uj4ERUZLf-JAX$L3(Kp;K<0Q#5R!N}I|FOS2QZS!k#
zzm2}R6|IGxvFU}1r5&;|3U8YS8-?`*0yzx|cyAkHcL9wc6%ecWYEc4f0ZrA9V2OAc
z<TO%!m$@X_%-9!z`w(u=&l(gZ$BZBHGya?kBK%_D2+$}PgM=2>EZiu%z}M>=1(5QA
zvAUCAvk=}pGj2B=rZ_x~Z1RTkbo-`nkUSviVStTY1@7uQ$7~uZ?bypC&rw+&0gjtm
zdUpUUfy`h=^XldeG+M1%B(|WbBmJ3&gPD^xq0l*SP<;a|c3OX&K+vPW%i*nmRuN5n
zSttNVLEVOlTCiiA0ImRC)Di$4O{aCHsY7DVE`_rQ4E%>D5|+x^Q*JmD>6DpSWU1`a
zB6=<y++vytvQ?6es^oSp;6{hZQT_doUDD0ya14ge;2|VVHv7FI@);1qs@T9T9ZPcE
z0S(|PHpr4V4BPuIYL$tyLp^=e8s%S&_W4AxEFxm$K=nf02I4f7r#9D4%hdh3kz0o7
z)+`Mk7WK4^6FHMFtRQIY2AN+s;!r)n_F}VdARnMu@Zh)wYoZ>YpD}a`sL`^ilG949
zuh}bjEeo+ikX2hpafj<-tB{2zDOpS_6(JHh7oOHPtItCZy6?e(6HzUs4G@S6MF(hK
zEk@^CjFKYhzGq4$dAyT6q;%5Y$UhJsiZ+HLnp#UcOp~liF0k+WBa}xC?2EZ;4b(R=
z#Y_bZL_&i=2;lN=AOw!-0g)y6gEGJny0>qK0BC^RL781Mx$pz8f-P~NM2#YcyBj<6
zWk!|3RDM@w$DRumM`MWhY(I*DVoXMf5u}fO-sfffiIU$CGme>ZCa#fP>Ew(*Ng1lA
zRH_M+biWdt(eHk-3)S`79e-4rhTBSON{}UI56<5U*Pl2Sf3~&s@G&eL`EAzebLY;>
zTHdMd<Hq#KyAwRS<836+pRXsozYIN`zR5T4JJF^$2|NWwz&=*%by82z6z_acoTF;R
zF>K|Otg9JWU_)XuWv-V-uLZBg$I80lrq!m!$8{Pl{3?kJa#O&o@7l=4E-yH8Q~KE<
z@BV|mt=%O_M;Z3zPd}HcdF-krcd)Yt0Kk9&`c?WKc`FRd6r*3_{Y*xf_OQmm6vvo6
zSDSH5Qk4VnV^^4$r`wh#tr~YPx#}hS3Y<8B3rpvp%T|oR`$(@WZH>Oa51Iu{=TOhW
zy9?4wspbz(M=5?D6{q`m3VN<qt~&k3R>CJPi95@vJm+jxJvk>GAoIhAreWkUtH`~w
zn9;qAmvJ+>wNga%E(M9_InH93*oOj<4wqsK^Cu3K@izsVzRYnK)^()ZVk5of?<J)J
zNqL3NQU^zFJV5kaBJnLxh17)03M0}1IZiu>4wb24%GU1$h-rUzJFRkr&XOt4n~8AM
zIbj3R+C+%@*uad^+4R4b13HHje&ug$c<KOvMxRy0Q}Cr<>7HA0oiY@Kzd|AfhqoJ5
z_igaTXYeq#x~N^YMO}eot<=jp-rmhnE|@{qEByRsV>ylAgdGs}8_W<Yg2Fx$QH`h%
zGxhizMnua^DgKAPv0C&Mr`KrAJTuBU1{8JQ59%G)EIspa;A3!u{g9|Jnps%g{n?+o
ziLp&4eTNB<Nf#SL86lH0<5kFOAq6HTQ8<Y_<~Io$ZAFvq9*gJxy&mNQjd8P#9&S!D
z7rP`+?i=5FG%s(f686Ov9mY-<L%w<M&orEU^YGj&D$epgTsg|}$#oc8OxE!>UMs8W
zcwSuN+H`BOJgWT3yLmgZ>GjI@em>Txdym86UjFF1bz(c|`MUA=ZtBDCv$I>(rTy~$
z<v7T5V(5lV;5E};1_>q!By!h4?_*W;i@n;jcj^mAJJBu+{yC)?AE&=k?dI_q1Nl7Z
zKy=zKRFaBp`XIw8C#6W)*3i59sb~xwL~_arcY<TXPGlPRY<D0D=U5G2<PU~rmgDzd
z-#(c_AA0%Zr2v6Yfd7@P0ReFSW!8TyuAEN)>JPkq8TS9>S^VF{_iGyffTqw_l7z91
zqpp&how0-VzpPz<0^CTY_@BOZ-TVrnfc{_g*V-3w{0s3v2Eo64fqx1^gP|48zjm4V
z5+eRX_~ohp``Tk@YyVe_#h>!KwKep!FS!*6006>2<UwCs{_oPIZ)f-4zICNwaBbt4
zh0X6v`p<)BeKo{iu_IpyC+n|s|8H{d>d;h`uY;?9?fmtq{{I$Vz<{qDj=$vpbLRgE
z`LC@2K3|pUK=<XNQw9Zq|3A*ZnhzP~-y{b|H!I`6vX1_<4gOm-`v2AY0@iW;L;Oc=
z`ad~;hAjQfA^!2doc~B*`BVO9YRlhpB&UDN|HyFplkjJX$=?KF=YJFak!kX${?EvX
zzx7M5|JMH*K=CKyPxJ2Ih-shyYUTYC@TW`mZ@@3#{{;Lu&+MP9KaHn<vvU3Zll4y<
z>YtQ9eVTt$n*IOXD*te8{;B`dO!l{4G5Fv5|CpQdm$mFq#Geyd{zf3B{r`x+rnmfw
z`16kCZ-is@|Bv|V{^d`^pB>x35izy@@n7-JZmzr(=-03NUpYi50F+<7V*loUefobW
C_kpSa

literal 0
HcmV?d00001


From 127b2dcc80667b85cd487a9f28356adf3563b382 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Fri, 6 Mar 2026 01:15:39 -0800
Subject: [PATCH 145/267] refactor: split `Interactive` into
 `Stateless`/`Stateful`, add `SelectButton`, kebab-case dirs (#9134)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 web/lib/opal/README.md                        |  12 +-
 web/lib/opal/src/components/README.md         |  24 +-
 .../src/components/buttons/Button/README.md   | 102 ----
 .../src/components/buttons/Button/styles.css  |  69 ---
 .../components/buttons/OpenButton/README.md   |  79 ---
 .../buttons/OpenButton/components.tsx         |  61 ---
 .../components/buttons/OpenButton/styles.css  |   7 -
 .../src/components/buttons/button/README.md   |  58 ++
 .../components/buttons/button/components.tsx  | 124 +++++
 .../src/components/buttons/button/styles.css  |   9 +
 .../src/components/buttons/icon-wrapper.tsx   |  36 ++
 .../components/buttons/open-button/README.md  |  73 +++
 .../buttons/open-button/components.tsx        | 128 +++++
 .../components/buttons/open-button/styles.css |   8 +
 .../buttons/select-button/README.md           |  77 +++
 .../{Button => select-button}/components.tsx  | 103 +---
 .../buttons/select-button/styles.css          |   9 +
 web/lib/opal/src/components/index.ts          |  12 +-
 .../src/components/{Tag => tag}/README.md     |   0
 .../components/{Tag => tag}/components.tsx    |   2 +-
 .../src/components/{Tag => tag}/styles.css    |   0
 web/lib/opal/src/core/README.md               |   5 +-
 web/lib/opal/src/core/animations/README.md    |  41 ++
 .../{hoverable => animations}/components.tsx  |   2 +-
 .../core/{hoverable => animations}/styles.css |   0
 web/lib/opal/src/core/index.ts                |  50 +-
 web/lib/opal/src/core/interactive/README.md   | 172 +++---
 .../opal/src/core/interactive/components.tsx  | 502 ------------------
 .../src/core/interactive/container/README.md  |  25 +
 .../core/interactive/container/components.tsx | 168 ++++++
 .../src/core/interactive/foldable/README.md   |  38 ++
 .../core/interactive/foldable/components.tsx  |  51 ++
 .../src/core/interactive/foldable/styles.css  |  54 ++
 web/lib/opal/src/core/interactive/shared.css  |  48 ++
 .../src/core/interactive/stateful/README.md   |  35 ++
 .../core/interactive/stateful/components.tsx  | 150 ++++++
 .../src/core/interactive/stateful/styles.css  | 265 +++++++++
 .../src/core/interactive/stateless/README.md  |  33 ++
 .../core/interactive/stateless/components.tsx | 145 +++++
 .../src/core/interactive/stateless/styles.css | 387 ++++++++++++++
 web/lib/opal/src/core/interactive/styles.css  | 441 ---------------
 web/lib/opal/src/layouts/README.md            |  16 +-
 .../README.md                                 |   4 +-
 .../components.tsx                            |   2 +-
 .../{Content => content}/BodyLayout.tsx       |   0
 .../{Content => content}/ContentLg.tsx        |   2 +-
 .../{Content => content}/ContentMd.tsx        |   4 +-
 .../{Content => content}/ContentSm.tsx        |   0
 .../{Content => content}/ContentXl.tsx        |   2 +-
 .../{Content => content}/HeadingLayout.tsx    |   2 +-
 .../{Content => content}/LabelLayout.tsx      |   4 +-
 .../layouts/{Content => content}/README.md    |   0
 .../{Content => content}/components.tsx       |  12 +-
 .../layouts/{Content => content}/styles.css   |   0
 .../README.md                                 |   0
 .../components.tsx                            |   0
 web/lib/opal/src/layouts/index.ts             |   6 +-
 .../admin/indexing/status/FilterComponent.tsx |   6 +-
 web/src/app/admin/scim/ScimModal.tsx          |   4 +-
 .../messageComponents/MessageToolbar.tsx      |  12 +-
 web/src/components/modals/UserFilesModal.tsx  |   2 +-
 web/src/ee/sections/SearchCard.tsx            |   4 +-
 web/src/layouts/app-layouts.tsx               |   2 +-
 web/src/refresh-components/Pagination.tsx     |   2 +-
 .../refresh-components/SimpleCollapsible.tsx  |   2 +-
 .../refresh-components/buttons/SidebarTab.tsx |   6 +-
 .../popovers/ActionsPopover/index.tsx         |   2 +-
 .../popovers/LLMPopover.tsx                   |   1 -
 .../table/ColumnVisibilityPopover.tsx         |   2 +-
 .../refresh-components/table/Pagination.tsx   |   2 +-
 .../table/SortingPopover.tsx                  |   2 +-
 .../refresh-components/tiles/ButtonTile.tsx   |   4 +-
 web/src/refresh-pages/SettingsPage.tsx        |   4 +-
 web/src/sections/Suggestions.tsx              |   4 +-
 web/src/sections/actions/ToolsList.tsx        |   2 +-
 web/src/sections/cards/AgentCard.tsx          |   4 +-
 web/src/sections/cards/DocumentSetCard.tsx    |   4 +-
 web/src/sections/input/AppInputBar.tsx        |  28 +-
 web/src/sections/input/SharedAppInputBar.tsx  |   6 +-
 web/src/sections/modals/AgentViewerModal.tsx  |   4 +-
 80 files changed, 2205 insertions(+), 1563 deletions(-)
 delete mode 100644 web/lib/opal/src/components/buttons/Button/README.md
 delete mode 100644 web/lib/opal/src/components/buttons/Button/styles.css
 delete mode 100644 web/lib/opal/src/components/buttons/OpenButton/README.md
 delete mode 100644 web/lib/opal/src/components/buttons/OpenButton/components.tsx
 delete mode 100644 web/lib/opal/src/components/buttons/OpenButton/styles.css
 create mode 100644 web/lib/opal/src/components/buttons/button/README.md
 create mode 100644 web/lib/opal/src/components/buttons/button/components.tsx
 create mode 100644 web/lib/opal/src/components/buttons/button/styles.css
 create mode 100644 web/lib/opal/src/components/buttons/icon-wrapper.tsx
 create mode 100644 web/lib/opal/src/components/buttons/open-button/README.md
 create mode 100644 web/lib/opal/src/components/buttons/open-button/components.tsx
 create mode 100644 web/lib/opal/src/components/buttons/open-button/styles.css
 create mode 100644 web/lib/opal/src/components/buttons/select-button/README.md
 rename web/lib/opal/src/components/buttons/{Button => select-button}/components.tsx (54%)
 create mode 100644 web/lib/opal/src/components/buttons/select-button/styles.css
 rename web/lib/opal/src/components/{Tag => tag}/README.md (100%)
 rename web/lib/opal/src/components/{Tag => tag}/components.tsx (97%)
 rename web/lib/opal/src/components/{Tag => tag}/styles.css (100%)
 create mode 100644 web/lib/opal/src/core/animations/README.md
 rename web/lib/opal/src/core/{hoverable => animations}/components.tsx (99%)
 rename web/lib/opal/src/core/{hoverable => animations}/styles.css (100%)
 delete mode 100644 web/lib/opal/src/core/interactive/components.tsx
 create mode 100644 web/lib/opal/src/core/interactive/container/README.md
 create mode 100644 web/lib/opal/src/core/interactive/container/components.tsx
 create mode 100644 web/lib/opal/src/core/interactive/foldable/README.md
 create mode 100644 web/lib/opal/src/core/interactive/foldable/components.tsx
 create mode 100644 web/lib/opal/src/core/interactive/foldable/styles.css
 create mode 100644 web/lib/opal/src/core/interactive/shared.css
 create mode 100644 web/lib/opal/src/core/interactive/stateful/README.md
 create mode 100644 web/lib/opal/src/core/interactive/stateful/components.tsx
 create mode 100644 web/lib/opal/src/core/interactive/stateful/styles.css
 create mode 100644 web/lib/opal/src/core/interactive/stateless/README.md
 create mode 100644 web/lib/opal/src/core/interactive/stateless/components.tsx
 create mode 100644 web/lib/opal/src/core/interactive/stateless/styles.css
 delete mode 100644 web/lib/opal/src/core/interactive/styles.css
 rename web/lib/opal/src/layouts/{ContentAction => content-action}/README.md (95%)
 rename web/lib/opal/src/layouts/{ContentAction => content-action}/components.tsx (97%)
 rename web/lib/opal/src/layouts/{Content => content}/BodyLayout.tsx (100%)
 rename web/lib/opal/src/layouts/{Content => content}/ContentLg.tsx (98%)
 rename web/lib/opal/src/layouts/{Content => content}/ContentMd.tsx (98%)
 rename web/lib/opal/src/layouts/{Content => content}/ContentSm.tsx (100%)
 rename web/lib/opal/src/layouts/{Content => content}/ContentXl.tsx (99%)
 rename web/lib/opal/src/layouts/{Content => content}/HeadingLayout.tsx (98%)
 rename web/lib/opal/src/layouts/{Content => content}/LabelLayout.tsx (98%)
 rename web/lib/opal/src/layouts/{Content => content}/README.md (100%)
 rename web/lib/opal/src/layouts/{Content => content}/components.tsx (95%)
 rename web/lib/opal/src/layouts/{Content => content}/styles.css (100%)
 rename web/lib/opal/src/layouts/{IllustrationContent => illustration-content}/README.md (100%)
 rename web/lib/opal/src/layouts/{IllustrationContent => illustration-content}/components.tsx (100%)

diff --git a/web/lib/opal/README.md b/web/lib/opal/README.md
index a5089cec1c3..5f60f9d59a6 100644
--- a/web/lib/opal/README.md
+++ b/web/lib/opal/README.md
@@ -33,9 +33,17 @@ Those dependencies will then install inside of `/web/node_modules` and be availa
 ```
 /web/lib/opal/
 ├── src/
-│   ├── components/    # React components
-│   └── index.ts       # Main export file
+│   ├── core/           # Low-level primitives (Interactive, Hoverable)
+│   ├── components/     # High-level React components (Button, SelectButton, OpenButton, Tag)
+│   ├── layouts/        # Layout primitives (Content, ContentAction, IllustrationContent)
+│   └── index.ts        # Main export file
 ├── package.json
 ├── tsconfig.json
 └── README.md
 ```
+
+## Conventions
+
+- **Directory names** are kebab-case (e.g. `select-button/`, `open-button/`, `content-action/`)
+- **Each component directory** contains `components.tsx`, `styles.css` (if needed), and `README.md`
+- **Imports** use `@opal/` path aliases (e.g. `@opal/components`, `@opal/core`)
diff --git a/web/lib/opal/src/components/README.md b/web/lib/opal/src/components/README.md
index 8c9c2d11153..7c323fb64bf 100644
--- a/web/lib/opal/src/components/README.md
+++ b/web/lib/opal/src/components/README.md
@@ -1,13 +1,13 @@
 # Opal Components
 
-High-level UI components built on the [`@opal/core`](../core/) primitives. Every component in this directory delegates state styling (hover, active, disabled, transient) to `Interactive.Base` via CSS data-attributes and the `--interactive-foreground` custom property — no duplicated Tailwind class maps.
+High-level UI components built on the [`@opal/core`](../core/) primitives. Every component in this directory delegates state styling (hover, active, disabled) to `Interactive.Stateless` or `Interactive.Stateful` via CSS data-attributes and the `--interactive-foreground` / `--interactive-foreground-icon` custom properties — no duplicated Tailwind class maps.
 
 ## Package export
 
-Components are exposed from the `@onyx/opal` package via:
+Components are exposed via:
 
 ```ts
-import { Button } from "@opal/components";
+import { Button, SelectButton, OpenButton, Tag } from "@opal/components";
 ```
 
 The barrel file at `index.ts` re-exports each component and its prop types. Each component imports its own `styles.css` internally.
@@ -16,17 +16,19 @@ The barrel file at `index.ts` re-exports each component and its prop types. Each
 
 | Component | Description | Docs |
 |-----------|-------------|------|
-| [Button](./buttons/Button/) | Label and/or icon-only button | [README](./buttons/Button/README.md) |
-| [OpenButton](./buttons/OpenButton/) | Trigger button with rotating chevron | [README](./buttons/OpenButton/README.md) |
+| [Button](./buttons/button/) | Label and/or icon-only stateless button | [README](./buttons/button/README.md) |
+| [SelectButton](./buttons/select-button/) | Stateful toggle button with optional foldable content | [README](./buttons/select-button/README.md) |
+| [OpenButton](./buttons/open-button/) | Trigger button with rotating chevron for popovers | [README](./buttons/open-button/README.md) |
+| [Tag](./tag/) | Small colored label for status/category metadata | [README](./tag/README.md) |
 
 ## Adding new components
 
-1. Create a directory under `components/` (e.g. `components/inputs/TextInput/`)
-2. Add a `styles.css` for layout-only CSS (colors come from Interactive.Base or other core primitives)
+1. Create a directory under `components/` in kebab-case (e.g. `components/inputs/text-input/`)
+2. Add a `styles.css` for layout-only CSS (colors come from Interactive primitives)
 3. Add a `components.tsx` with the component and its exported props type
-4. Import `styles.css` at the top of your `components.tsx` (each component owns its own styles)
-5. In `components/index.ts`, re-export the component:
+4. Import `styles.css` at the top of your `components.tsx`
+5. Add a `README.md` inside the component directory with architecture, props, and usage examples
+6. In `components/index.ts`, re-export the component:
    ```ts
-   export { TextInput, type TextInputProps } from "@opal/components/inputs/TextInput/components";
+   export { TextInput, type TextInputProps } from "@opal/components/inputs/text-input/components";
    ```
-6. Add a `README.md` inside the component directory with architecture, props, and usage examples
diff --git a/web/lib/opal/src/components/buttons/Button/README.md b/web/lib/opal/src/components/buttons/Button/README.md
deleted file mode 100644
index 58701081aff..00000000000
--- a/web/lib/opal/src/components/buttons/Button/README.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Button
-
-**Import:** `import { Button, type ButtonProps } from "@opal/components";`
-
-A single component that handles both labeled buttons and icon-only buttons. It replaces the legacy `refresh-components/buttons/Button` and `refresh-components/buttons/IconButton` with a unified API built on `Interactive.Base` > `Interactive.Container`.
-
-## Architecture
-
-```
-Interactive.Base            <- variant/prominence, transient, disabled, href, onClick
-  └─ Interactive.Container  <- height, rounding, padding (derived from `size`), border (auto for secondary)
-       └─ div.opal-button.interactive-foreground  <- flexbox row layout
-            ├─ div.p-0.5 > Icon?      (compact: 12px, default: 16px, shrink-0)
-            ├─ <span>?                 .opal-button-label  (whitespace-nowrap, font)
-            └─ div.p-0.5 > RightIcon?  (compact: 12px, default: 16px, shrink-0)
-```
-
-- **Colors are not in the Button.** `Interactive.Base` sets `background-color` and `--interactive-foreground` per variant/prominence/state. The `.interactive-foreground` utility class on the content div sets `color: var(--interactive-foreground)`, which both the `<span>` text and `stroke="currentColor"` SVG icons inherit automatically.
-- **Layout is in `styles.css`.** The CSS classes (`.opal-button`, `.opal-button-label`) handle flexbox alignment, gap, and text styling. Default labels use `font-main-ui-action` (14px/600); compact labels use `font-secondary-action` (12px/600) via a `[data-size="compact"]` selector.
-- **Sizing is delegated to `Interactive.Container` presets.** The `size` prop maps to Container height/rounding/padding presets:
-  - `"default"` -> height 2.25rem, rounding 12px, padding 8px
-  - `"compact"` -> height 1.75rem, rounding 8px, padding 4px
-- **Icon-only buttons render as squares** because `Interactive.Container` enforces `min-width >= height` for every height preset.
-- **Border is automatic for `prominence="secondary"`.** The Container receives `border={prominence === "secondary"}` internally — there is no external `border` prop.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `"default" \| "action" \| "danger" \| "none" \| "select"` | `"default"` | Top-level color variant (maps to `Interactive.Base`) |
-| `prominence` | Depends on `variant` | `"primary"` | Color prominence -- e.g. `"primary"`, `"secondary"`, `"tertiary"`, `"internal"` for default/action/danger. `"secondary"` automatically renders a border. |
-| `icon` | `IconFunctionComponent` | -- | Left icon component |
-| `children` | `string` | -- | Button label text. Omit for icon-only buttons |
-| `rightIcon` | `IconFunctionComponent` | -- | Right icon component |
-| `size` | `SizeVariant` | `"default"` | Size preset controlling height, rounding, padding, icon size, and font style |
-| `tooltip` | `string` | -- | Tooltip text shown on hover |
-| `tooltipSide` | `TooltipSide` | `"top"` | Which side the tooltip appears on |
-| `selected` | `boolean` | `false` | Switches foreground to action-link colours (only available with `variant="select"`) |
-| `transient` | `boolean` | `false` | Forces the transient (hover) visual state (data-transient) |
-| `disabled` | `boolean` | `false` | Disables the button (data-disabled, aria-disabled) |
-| `href` | `string` | -- | URL; renders an `<a>` wrapper instead of Radix Slot |
-| `onClick` | `MouseEventHandler<HTMLElement>` | -- | Click handler |
-| _...and all other `InteractiveBaseProps`_ | | | `group`, `ref`, etc. |
-
-## Usage examples
-
-```tsx
-import { Button } from "@opal/components";
-import { SvgPlus, SvgArrowRight } from "@opal/icons";
-
-// Primary button with label
-<Button variant="default" onClick={handleClick}>
-  Save changes
-</Button>
-
-// Icon-only button (renders as a square)
-<Button icon={SvgPlus} prominence="tertiary" size="compact" />
-
-// Labeled button with left icon
-<Button icon={SvgPlus} variant="action">
-  Add item
-</Button>
-
-// Secondary button (automatically renders a border)
-<Button rightIcon={SvgArrowRight} variant="default" prominence="secondary">
-  Continue
-</Button>
-
-// Compact danger button, disabled
-<Button variant="danger" size="compact" disabled>
-  Delete
-</Button>
-
-// As a link
-<Button href="/settings" variant="default" prominence="tertiary">
-  Settings
-</Button>
-
-// Transient state (e.g. inside a popover trigger)
-<Button icon={SvgFilter} prominence="tertiary" transient={isOpen} />
-
-// With tooltip
-<Button icon={SvgPlus} prominence="tertiary" tooltip="Add item" />
-```
-
-## Migration from legacy buttons
-
-| Legacy prop | Opal equivalent |
-|-------------|-----------------|
-| `main` | `variant="default"` (default, can be omitted) |
-| `action` | `variant="action"` |
-| `danger` | `variant="danger"` |
-| `primary` | `prominence="primary"` (default, can be omitted) |
-| `secondary` | `prominence="secondary"` |
-| `tertiary` | `prominence="tertiary"` |
-| `internal` | `prominence="internal"` |
-| `transient={x}` | `transient={x}` |
-| `size="md"` | `size="compact"` |
-| `size="lg"` | `size="default"` (default, can be omitted) |
-| `leftIcon={X}` | `icon={X}` |
-| `IconButton icon={X}` | `<Button icon={X} />` (no children = icon-only) |
-| `tooltip="..."` | `tooltip="..."` |
diff --git a/web/lib/opal/src/components/buttons/Button/styles.css b/web/lib/opal/src/components/buttons/Button/styles.css
deleted file mode 100644
index db5192c2e4c..00000000000
--- a/web/lib/opal/src/components/buttons/Button/styles.css
+++ /dev/null
@@ -1,69 +0,0 @@
-/* Button — layout only; colors handled by Interactive.Base */
-
-.opal-button {
-  @apply flex flex-row items-center gap-1;
-}
-
-.opal-button-label {
-  @apply whitespace-nowrap;
-}
-
-/* ---------------------------------------------------------------------------
-   Foldable content — collapses label + right-icon via CSS grid animation.
-
-   Structure (two divs are required):
-     .opal-button-foldable        — grid container, animates column 0fr ↔ 1fr
-       .opal-button-foldable-inner — single grid item, flex layout + overflow clip
-
-   The parent gap also transitions so the spacing between the icon and the
-   foldable wrapper collapses/expands in sync.
-
-   Expand triggers piggy-back on Interactive.Base's existing `:hover` and
-   `[data-transient]` data-attributes — no JS hover state required.
-   --------------------------------------------------------------------------- */
-
-/* Parent gap: 0 when foldable, transitions to gap-1 on expand */
-.opal-button--foldable {
-  gap: 0;
-  transition: gap 200ms ease-in-out;
-}
-
-.interactive:hover:not([data-disabled]) .opal-button--foldable,
-.interactive[data-transient="true"]:not([data-disabled])
-  .opal-button--foldable {
-  gap: 0.25rem;
-}
-
-/* Grid container — collapse animation */
-.opal-button-foldable {
-  display: grid;
-  grid-template-columns: 1fr;
-  transition:
-    grid-template-columns 200ms ease-in-out,
-    opacity 200ms ease-in-out;
-  opacity: 1;
-}
-
-/* Single grid item — content layout + overflow clipping */
-.opal-button-foldable-inner {
-  @apply flex items-center gap-1;
-  overflow: hidden;
-  min-width: 0;
-}
-
-/* Collapsed: foldable and not hovered / transient */
-.opal-button--foldable .opal-button-foldable {
-  grid-template-columns: 0fr;
-  opacity: 0;
-}
-
-/* Expanded: hovered or transient (mirrors Interactive.Base's hover selectors) */
-.interactive:hover:not([data-disabled])
-  .opal-button--foldable
-  .opal-button-foldable,
-.interactive[data-transient="true"]:not([data-disabled])
-  .opal-button--foldable
-  .opal-button-foldable {
-  grid-template-columns: 1fr;
-  opacity: 1;
-}
diff --git a/web/lib/opal/src/components/buttons/OpenButton/README.md b/web/lib/opal/src/components/buttons/OpenButton/README.md
deleted file mode 100644
index 53e5eb5d02e..00000000000
--- a/web/lib/opal/src/components/buttons/OpenButton/README.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# OpenButton
-
-**Import:** `import { OpenButton, type OpenButtonProps } from "@opal/components";`
-
-A trigger button with a built-in chevron that rotates when open. Hardcodes `variant="select"` and delegates to `Button`, adding automatic open-state detection from Radix `data-state`. Designed to work automatically with Radix primitives while also supporting explicit control via the `transient` prop.
-
-## Architecture
-
-```
-OpenButton
-  └─ Button (variant="select", rightIcon=ChevronIcon)
-       └─ Interactive.Base                 <- select variant, transient, selected, disabled, href, onClick
-            └─ Interactive.Container       <- height, rounding, padding, border (auto for secondary)
-                 └─ div.opal-button.interactive-foreground
-                      ├─ div.p-0.5 > Icon?
-                      ├─ <span>?                   .opal-button-label
-                      └─ div.p-0.5 > ChevronIcon   .opal-open-button-chevron
-```
-
-- **Always uses `variant="select"`.** OpenButton omits `variant` and `prominence` from its own props; it hardcodes `variant="select"` and only exposes `InteractiveBaseSelectVariantProps` (`prominence?: "light" | "heavy"`, `selected?: boolean`).
-- **`transient` controls both the chevron and the hover visual state.** When `transient` is true (explicitly or via Radix `data-state="open"`), the chevron rotates 180° and the `Interactive.Base` hover background activates. There is no separate `open` prop.
-- **Open-state detection** is dual-resolution: the explicit `transient` prop takes priority; otherwise the component reads `data-state="open"` injected by Radix triggers (e.g. `Popover.Trigger`).
-- **Chevron rotation** is CSS-driven via `.interactive[data-transient="true"] .opal-open-button-chevron { rotate: -180deg }`. The `ChevronIcon` is a stable named component (not an inline function) to preserve React element identity across renders, ensuring CSS transitions fire correctly.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `prominence` | `"light" \| "heavy"` | `"light"` | Select prominence. `"heavy"` shows a tinted background when selected. |
-| `selected` | `boolean` | `false` | Switches foreground to action-link colours |
-| `transient` | `boolean` | -- | Forces transient (hover) visual state and chevron rotation. Falls back to Radix `data-state="open"` when omitted. |
-| `icon` | `IconFunctionComponent` | -- | Left icon component |
-| `children` | `string` | -- | Content between icon and chevron |
-| `size` | `SizeVariant` | `"default"` | Size preset controlling height, rounding, and padding |
-| `tooltip` | `string` | -- | Tooltip text shown on hover |
-| `tooltipSide` | `TooltipSide` | `"top"` | Which side the tooltip appears on |
-| `disabled` | `boolean` | `false` | Disables the button |
-| `href` | `string` | -- | URL; renders an `<a>` wrapper |
-| `onClick` | `MouseEventHandler<HTMLElement>` | -- | Click handler |
-| _...and all other `ButtonProps` (minus variant props) / `InteractiveBaseProps`_ | | | `group`, `ref`, etc. |
-
-## Usage examples
-
-```tsx
-import { OpenButton } from "@opal/components";
-import { SvgFilter } from "@opal/icons";
-
-// Basic usage with Radix Popover (auto-detects open state from data-state)
-<Popover.Trigger asChild>
-  <OpenButton>
-    Select option
-  </OpenButton>
-</Popover.Trigger>
-
-// Explicit transient control (chevron rotates AND button shows hover state)
-<OpenButton transient={isExpanded} onClick={toggle}>
-  Advanced settings
-</OpenButton>
-
-// With selected state (action-link foreground)
-<OpenButton selected={isActive} transient={isExpanded} onClick={toggle}>
-  Active filter
-</OpenButton>
-
-// With left icon and heavy prominence (tinted background when selected)
-<OpenButton icon={SvgFilter} prominence="heavy" selected={isActive}>
-  Filters
-</OpenButton>
-
-// Compact sizing
-<OpenButton size="compact">
-  More
-</OpenButton>
-
-// With tooltip
-<OpenButton tooltip="Expand filters" icon={SvgFilter}>
-  Filters
-</OpenButton>
-```
diff --git a/web/lib/opal/src/components/buttons/OpenButton/components.tsx b/web/lib/opal/src/components/buttons/OpenButton/components.tsx
deleted file mode 100644
index 1857538ea4a..00000000000
--- a/web/lib/opal/src/components/buttons/OpenButton/components.tsx
+++ /dev/null
@@ -1,61 +0,0 @@
-import "@opal/components/buttons/OpenButton/styles.css";
-import { Button } from "@opal/components/buttons/Button/components";
-import type { ButtonProps } from "@opal/components";
-import { SvgChevronDownSmall } from "@opal/icons";
-import { cn } from "@opal/utils";
-import type { InteractiveBaseVariantProps } from "@opal/core";
-import type { InteractiveBaseSelectVariantProps } from "@opal/core/interactive/components";
-import type { IconProps } from "@opal/types";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Omit that distributes over unions, preserving discriminated-union branches. */
-type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
-  ? Omit<T, K>
-  : never;
-
-type OpenButtonProps = DistributiveOmit<
-  ButtonProps,
-  keyof InteractiveBaseVariantProps
-> &
-  InteractiveBaseSelectVariantProps;
-
-// ---------------------------------------------------------------------------
-// Chevron (stable identity — never causes React to remount the SVG)
-// ---------------------------------------------------------------------------
-
-function ChevronIcon({ className, ...props }: IconProps) {
-  return (
-    <SvgChevronDownSmall
-      className={cn(className, "opal-open-button-chevron")}
-      {...props}
-    />
-  );
-}
-
-// ---------------------------------------------------------------------------
-// OpenButton
-// ---------------------------------------------------------------------------
-
-function OpenButton({ transient, ...baseProps }: OpenButtonProps) {
-  // Derive open state: explicit prop → Radix data-state (injected via Slot chain)
-  const dataState = (baseProps as Record<string, unknown>)["data-state"] as
-    | string
-    | undefined;
-  const transient_ = transient ?? dataState === "open";
-
-  // Assertion is safe: OpenButton is a controlled wrapper that always supplies
-  // rightIcon (ChevronIcon) and variant="select", satisfying Button's union.
-  const buttonProps = {
-    ...baseProps,
-    variant: "select" as const,
-    transient: transient_,
-    rightIcon: ChevronIcon,
-  } as ButtonProps;
-
-  return <Button {...buttonProps} />;
-}
-
-export { OpenButton, type OpenButtonProps };
diff --git a/web/lib/opal/src/components/buttons/OpenButton/styles.css b/web/lib/opal/src/components/buttons/OpenButton/styles.css
deleted file mode 100644
index 5c2d20e61e0..00000000000
--- a/web/lib/opal/src/components/buttons/OpenButton/styles.css
+++ /dev/null
@@ -1,7 +0,0 @@
-.opal-open-button-chevron {
-  transition: rotate 200ms ease;
-}
-
-.interactive[data-transient="true"] .opal-open-button-chevron {
-  rotate: -180deg;
-}
diff --git a/web/lib/opal/src/components/buttons/button/README.md b/web/lib/opal/src/components/buttons/button/README.md
new file mode 100644
index 00000000000..7599c501128
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/button/README.md
@@ -0,0 +1,58 @@
+# Button
+
+**Import:** `import { Button, type ButtonProps } from "@opal/components";`
+
+A single component that handles both labeled buttons and icon-only buttons. Built on `Interactive.Stateless` > `Interactive.Container`.
+
+## Architecture
+
+```
+Interactive.Stateless          <- variant, prominence, interaction, disabled, href, onClick
+  └─ Interactive.Container     <- height, rounding, padding (from `size`), border (auto for secondary)
+       └─ div.opal-button.interactive-foreground
+            ├─ div > Icon?       (interactive-foreground-icon)
+            ├─ <span>?           .opal-button-label
+            └─ div > RightIcon?  (interactive-foreground-icon)
+```
+
+- **Colors are not in the Button.** `Interactive.Stateless` sets `background-color`, `--interactive-foreground`, and `--interactive-foreground-icon` per variant/prominence/state. Descendants opt in via the `.interactive-foreground` and `.interactive-foreground-icon` utility classes.
+- **Icon-only buttons render as squares** because `Interactive.Container` enforces `min-width >= height`.
+- **Border is automatic for `prominence="secondary"`.** The Container receives `border={prominence === "secondary"}` internally.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "action" \| "danger" \| "none"` | `"default"` | Color variant |
+| `prominence` | `"primary" \| "secondary" \| "tertiary" \| "internal"` | `"primary"` | Color prominence |
+| `interaction` | `"rest" \| "hover" \| "active"` | `"rest"` | JS-controlled interaction override |
+| `icon` | `IconFunctionComponent` | — | Left icon |
+| `children` | `string` | — | Label text. Omit for icon-only buttons |
+| `rightIcon` | `IconFunctionComponent` | — | Right icon |
+| `responsiveHideText` | `boolean` | `false` | Hides label on small screens |
+| `size` | `SizeVariant` | `"lg"` | Size preset |
+| `type` | `"submit" \| "button" \| "reset"` | `"button"` | HTML button type |
+| `width` | `WidthVariant` | — | Width preset |
+| `tooltip` | `string` | — | Tooltip text |
+| `tooltipSide` | `TooltipSide` | `"top"` | Tooltip placement |
+| `disabled` | `boolean` | `false` | Disables the button |
+| `href` | `string` | — | URL; renders as a link |
+
+## Usage
+
+```tsx
+import { Button } from "@opal/components";
+import { SvgPlus, SvgArrowRight } from "@opal/icons";
+
+// Primary button with label
+<Button variant="default" onClick={handleClick}>Save changes</Button>
+
+// Icon-only button (renders as a square)
+<Button icon={SvgPlus} prominence="tertiary" size="sm" />
+
+// Secondary button (auto border)
+<Button rightIcon={SvgArrowRight} prominence="secondary">Continue</Button>
+
+// Interaction override (e.g. inside a popover trigger)
+<Button icon={SvgFilter} prominence="tertiary" interaction={isOpen ? "hover" : "rest"} />
+```
diff --git a/web/lib/opal/src/components/buttons/button/components.tsx b/web/lib/opal/src/components/buttons/button/components.tsx
new file mode 100644
index 00000000000..e9786ce1f69
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/button/components.tsx
@@ -0,0 +1,124 @@
+import "@opal/components/buttons/button/styles.css";
+import "@opal/components/tooltip.css";
+import { Interactive, type InteractiveStatelessProps } from "@opal/core";
+import type { SizeVariant, WidthVariant } from "@opal/shared";
+import type { TooltipSide } from "@opal/components";
+import type { IconFunctionComponent } from "@opal/types";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import { cn } from "@opal/utils";
+import { iconWrapper } from "@opal/components/buttons/icon-wrapper";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ButtonContentProps =
+  | {
+      icon?: IconFunctionComponent;
+      children: string;
+      rightIcon?: IconFunctionComponent;
+      responsiveHideText?: never;
+    }
+  | {
+      icon: IconFunctionComponent;
+      children?: string;
+      rightIcon?: IconFunctionComponent;
+      responsiveHideText?: boolean;
+    };
+
+type ButtonProps = InteractiveStatelessProps &
+  ButtonContentProps & {
+    /**
+     * Size preset — controls gap, text size, and Container height/rounding.
+     */
+    size?: SizeVariant;
+
+    /** HTML button type. When provided, Container renders a `<button>` element. */
+    type?: "submit" | "button" | "reset";
+
+    /** Tooltip text shown on hover. */
+    tooltip?: string;
+
+    /** Width preset. `"auto"` shrink-wraps, `"full"` stretches to parent width. */
+    width?: WidthVariant;
+
+    /** Which side the tooltip appears on. */
+    tooltipSide?: TooltipSide;
+  };
+
+// ---------------------------------------------------------------------------
+// Button
+// ---------------------------------------------------------------------------
+
+function Button({
+  icon: Icon,
+  children,
+  rightIcon: RightIcon,
+  size = "lg",
+  type = "button",
+  width,
+  tooltip,
+  tooltipSide = "top",
+  responsiveHideText = false,
+  ...interactiveProps
+}: ButtonProps) {
+  const isLarge = size === "lg";
+
+  const labelEl = children ? (
+    <span
+      className={cn(
+        "opal-button-label",
+        isLarge ? "font-main-ui-body " : "font-secondary-body",
+        responsiveHideText && "hidden md:inline"
+      )}
+    >
+      {children}
+    </span>
+  ) : null;
+
+  const button = (
+    <Interactive.Stateless {...interactiveProps}>
+      <Interactive.Container
+        type={type}
+        border={interactiveProps.prominence === "secondary"}
+        heightVariant={size}
+        widthVariant={width}
+        roundingVariant={
+          isLarge ? "default" : size === "2xs" ? "mini" : "compact"
+        }
+      >
+        <div className={cn("opal-button interactive-foreground")}>
+          {iconWrapper(Icon, size, !!children)}
+
+          {labelEl}
+          {responsiveHideText ? (
+            <span className="hidden md:inline-flex">
+              {iconWrapper(RightIcon, size, !!children)}
+            </span>
+          ) : (
+            iconWrapper(RightIcon, size, !!children)
+          )}
+        </div>
+      </Interactive.Container>
+    </Interactive.Stateless>
+  );
+
+  if (!tooltip) return button;
+
+  return (
+    <TooltipPrimitive.Root>
+      <TooltipPrimitive.Trigger asChild>{button}</TooltipPrimitive.Trigger>
+      <TooltipPrimitive.Portal>
+        <TooltipPrimitive.Content
+          className="opal-tooltip"
+          side={tooltipSide}
+          sideOffset={4}
+        >
+          {tooltip}
+        </TooltipPrimitive.Content>
+      </TooltipPrimitive.Portal>
+    </TooltipPrimitive.Root>
+  );
+}
+
+export { Button, type ButtonProps };
diff --git a/web/lib/opal/src/components/buttons/button/styles.css b/web/lib/opal/src/components/buttons/button/styles.css
new file mode 100644
index 00000000000..ff65be418bd
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/button/styles.css
@@ -0,0 +1,9 @@
+/* Button — layout only; colors handled by Interactive.Stateless */
+
+.opal-button {
+  @apply flex flex-row items-center gap-1;
+}
+
+.opal-button-label {
+  @apply whitespace-nowrap;
+}
diff --git a/web/lib/opal/src/components/buttons/icon-wrapper.tsx b/web/lib/opal/src/components/buttons/icon-wrapper.tsx
new file mode 100644
index 00000000000..17896d3f15d
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/icon-wrapper.tsx
@@ -0,0 +1,36 @@
+import type { SizeVariant } from "@opal/shared";
+import type { IconFunctionComponent } from "@opal/types";
+import { cn } from "@opal/utils";
+
+const iconVariants = {
+  lg: { padding: "p-0.5", size: 1 },
+  md: { padding: "p-0.5", size: 1 },
+  sm: { padding: "p-0", size: 1 },
+  xs: { padding: "p-0.5", size: 0.75 },
+  "2xs": { padding: "p-0", size: 0.75 },
+  fit: { padding: "p-0.5", size: 1 },
+} as const;
+
+function iconWrapper(
+  Icon: IconFunctionComponent | undefined,
+  size: SizeVariant,
+  includeSpacer: boolean
+) {
+  const { padding: p, size: s } = iconVariants[size];
+
+  return Icon ? (
+    <div className={cn("interactive-foreground-icon", p)}>
+      <Icon
+        className="shrink-0"
+        style={{
+          height: `${s}rem`,
+          width: `${s}rem`,
+        }}
+      />
+    </div>
+  ) : includeSpacer ? (
+    <div />
+  ) : null;
+}
+
+export { iconWrapper, iconVariants };
diff --git a/web/lib/opal/src/components/buttons/open-button/README.md b/web/lib/opal/src/components/buttons/open-button/README.md
new file mode 100644
index 00000000000..bfa0be165b5
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/open-button/README.md
@@ -0,0 +1,73 @@
+# OpenButton
+
+**Import:** `import { OpenButton, type OpenButtonProps } from "@opal/components";`
+
+A trigger button with a built-in chevron that rotates when open. Hardcodes `variant="select-heavy"` and delegates to `Interactive.Stateful`, adding automatic open-state detection from Radix `data-state`. Designed to work automatically with Radix primitives while also supporting explicit control via the `interaction` prop.
+
+## Relationship to SelectButton
+
+OpenButton is structurally near-identical to `SelectButton` — both share the same call stack:
+
+```
+Interactive.Stateful → Interactive.Container → content row (icon + label + trailing icon)
+```
+
+OpenButton is a **tighter, specialized use-case** of SelectButton:
+
+- It hardcodes `variant="select-heavy"` (SelectButton exposes `variant`)
+- It adds a built-in chevron with CSS-driven rotation (SelectButton has no chevron)
+- It auto-detects Radix `data-state="open"` to derive `interaction` (SelectButton has no Radix awareness)
+- It does not support `foldable` or `rightIcon` (SelectButton does)
+
+If you need a general-purpose stateful toggle, use `SelectButton`. If you need a popover/dropdown trigger with a chevron, use `OpenButton`.
+
+## Architecture
+
+```
+Interactive.Stateful           <- variant="select-heavy", interaction, state, disabled, onClick
+  └─ Interactive.Container     <- height, rounding, padding (from `size`)
+       └─ div.opal-button.interactive-foreground
+            ├─ div > Icon?                 (interactive-foreground-icon)
+            ├─ <span>?                     .opal-button-label
+            └─ div > ChevronIcon           .opal-open-button-chevron (interactive-foreground-icon)
+```
+
+- **`interaction` controls both the chevron and the hover visual state.** When `interaction` is `"hover"` (explicitly or via Radix `data-state="open"`), the chevron rotates 180° and the hover background activates.
+- **Open-state detection** is dual-resolution: the explicit `interaction` prop takes priority; otherwise the component reads `data-state="open"` injected by Radix triggers (e.g. `Popover.Trigger`).
+- **Chevron rotation** is CSS-driven via `.interactive[data-interaction="hover"] .opal-open-button-chevron { rotate: -180deg }`. The `ChevronIcon` is a stable named component (not an inline function) to preserve React element identity across renders.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `state` | `"empty" \| "filled" \| "selected"` | `"empty"` | Current value state |
+| `interaction` | `"rest" \| "hover" \| "active"` | auto | JS-controlled interaction override. Falls back to Radix `data-state="open"` when omitted. |
+| `icon` | `IconFunctionComponent` | — | Left icon component |
+| `children` | `string` | — | Content between icon and chevron |
+| `size` | `SizeVariant` | `"lg"` | Size preset controlling height, rounding, and padding |
+| `width` | `WidthVariant` | — | Width preset |
+| `tooltip` | `string` | — | Tooltip text shown on hover |
+| `tooltipSide` | `TooltipSide` | `"top"` | Which side the tooltip appears on |
+| `disabled` | `boolean` | `false` | Disables the button |
+
+## Usage
+
+```tsx
+import { OpenButton } from "@opal/components";
+import { SvgFilter } from "@opal/icons";
+
+// Basic usage with Radix Popover (auto-detects open state)
+<Popover.Trigger asChild>
+  <OpenButton>Select option</OpenButton>
+</Popover.Trigger>
+
+// Explicit interaction control
+<OpenButton interaction={isExpanded ? "hover" : "rest"} onClick={toggle}>
+  Advanced settings
+</OpenButton>
+
+// With left icon
+<OpenButton icon={SvgFilter} state="filled">
+  Filters
+</OpenButton>
+```
diff --git a/web/lib/opal/src/components/buttons/open-button/components.tsx b/web/lib/opal/src/components/buttons/open-button/components.tsx
new file mode 100644
index 00000000000..40f31ae69e0
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/open-button/components.tsx
@@ -0,0 +1,128 @@
+import "@opal/components/buttons/open-button/styles.css";
+import "@opal/components/tooltip.css";
+import {
+  Interactive,
+  type InteractiveStatefulProps,
+  type InteractiveStatefulInteraction,
+} from "@opal/core";
+import type { SizeVariant, WidthVariant } from "@opal/shared";
+import type { TooltipSide } from "@opal/components";
+import type { IconFunctionComponent, IconProps } from "@opal/types";
+import { SvgChevronDownSmall } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import { cn } from "@opal/utils";
+import { iconWrapper } from "@opal/components/buttons/icon-wrapper";
+
+// ---------------------------------------------------------------------------
+// Chevron (stable identity — never causes React to remount the SVG)
+// ---------------------------------------------------------------------------
+
+function ChevronIcon({ className, ...props }: IconProps) {
+  return (
+    <SvgChevronDownSmall
+      className={cn(className, "opal-open-button-chevron")}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type OpenButtonProps = Omit<InteractiveStatefulProps, "variant"> & {
+  /** Left icon. */
+  icon?: IconFunctionComponent;
+
+  /** Button label text. */
+  children?: string;
+
+  /**
+   * Size preset — controls gap, text size, and Container height/rounding.
+   */
+  size?: SizeVariant;
+
+  /** Width preset. */
+  width?: WidthVariant;
+
+  /** Tooltip text shown on hover. */
+  tooltip?: string;
+
+  /** Which side the tooltip appears on. */
+  tooltipSide?: TooltipSide;
+};
+
+// ---------------------------------------------------------------------------
+// OpenButton
+// ---------------------------------------------------------------------------
+
+function OpenButton({
+  icon: Icon,
+  children,
+  size = "lg",
+  width,
+  tooltip,
+  tooltipSide = "top",
+  interaction,
+  ...statefulProps
+}: OpenButtonProps) {
+  // Derive open state: explicit prop → Radix data-state (injected via Slot chain)
+  const dataState = (statefulProps as Record<string, unknown>)["data-state"] as
+    | string
+    | undefined;
+  const resolvedInteraction: InteractiveStatefulInteraction =
+    interaction ?? (dataState === "open" ? "hover" : "rest");
+
+  const isLarge = size === "lg";
+
+  const button = (
+    <Interactive.Stateful
+      variant="select-heavy"
+      interaction={resolvedInteraction}
+      {...statefulProps}
+    >
+      <Interactive.Container
+        type="button"
+        heightVariant={size}
+        widthVariant={width}
+        roundingVariant={
+          isLarge ? "default" : size === "2xs" ? "mini" : "compact"
+        }
+      >
+        <div className="opal-button interactive-foreground flex flex-row items-center gap-1">
+          {iconWrapper(Icon, size, false)}
+          {children && (
+            <span
+              className={cn(
+                "opal-button-label whitespace-nowrap",
+                isLarge ? "font-main-ui-body" : "font-secondary-body"
+              )}
+            >
+              {children}
+            </span>
+          )}
+          {iconWrapper(ChevronIcon, size, false)}
+        </div>
+      </Interactive.Container>
+    </Interactive.Stateful>
+  );
+
+  if (!tooltip) return button;
+
+  return (
+    <TooltipPrimitive.Root>
+      <TooltipPrimitive.Trigger asChild>{button}</TooltipPrimitive.Trigger>
+      <TooltipPrimitive.Portal>
+        <TooltipPrimitive.Content
+          className="opal-tooltip"
+          side={tooltipSide}
+          sideOffset={4}
+        >
+          {tooltip}
+        </TooltipPrimitive.Content>
+      </TooltipPrimitive.Portal>
+    </TooltipPrimitive.Root>
+  );
+}
+
+export { OpenButton, type OpenButtonProps };
diff --git a/web/lib/opal/src/components/buttons/open-button/styles.css b/web/lib/opal/src/components/buttons/open-button/styles.css
new file mode 100644
index 00000000000..e27d654ba98
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/open-button/styles.css
@@ -0,0 +1,8 @@
+.opal-open-button-chevron {
+  transition: rotate 200ms ease;
+}
+
+.interactive[data-interaction="hover"] .opal-open-button-chevron,
+.interactive[data-interaction="active"] .opal-open-button-chevron {
+  rotate: -180deg;
+}
diff --git a/web/lib/opal/src/components/buttons/select-button/README.md b/web/lib/opal/src/components/buttons/select-button/README.md
new file mode 100644
index 00000000000..5334e0364d9
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/select-button/README.md
@@ -0,0 +1,77 @@
+# SelectButton
+
+**Import:** `import { SelectButton, type SelectButtonProps } from "@opal/components";`
+
+A stateful button for togglable selections — the stateful counterpart to `Button`. Built on `Interactive.Stateful` > `Interactive.Container`.
+
+## Relationship to OpenButton
+
+SelectButton and `OpenButton` are structurally near-identical — both share the same call stack:
+
+```
+Interactive.Stateful → Interactive.Container → content row (icon + label + trailing icon)
+```
+
+`OpenButton` is a **tighter, specialized use-case** of SelectButton:
+
+- OpenButton hardcodes `variant="select-heavy"` (SelectButton exposes `variant`)
+- OpenButton adds a built-in chevron with CSS-driven rotation (SelectButton has no chevron)
+- OpenButton auto-detects Radix `data-state="open"` to derive `interaction` (SelectButton has no Radix awareness)
+- OpenButton does not support `foldable` or `rightIcon` (SelectButton does)
+
+Use SelectButton for general-purpose stateful toggles. Use `OpenButton` for popover/dropdown triggers with a chevron.
+
+## Architecture
+
+```
+Interactive.Stateful           <- variant, state, interaction, disabled, onClick
+  └─ Interactive.Container     <- height, rounding, padding (from `size`)
+       └─ div.opal-select-button.interactive-foreground
+            ├─ Icon?           (interactive-foreground-icon)
+            ├─ [Foldable]?     (wraps label + rightIcon when foldable)
+            │    ├─ <span>     .opal-select-button-label
+            │    └─ RightIcon?
+            └─ <span>? / RightIcon?  (non-foldable)
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"select-light" \| "select-heavy" \| "sidebar"` | `"select-heavy"` | Stateful color variant |
+| `state` | `"empty" \| "filled" \| "selected"` | `"empty"` | Current value state |
+| `interaction` | `"rest" \| "hover" \| "active"` | `"rest"` | JS-controlled interaction override |
+| `icon` | `IconFunctionComponent` | — | Left icon |
+| `children` | `string` | — | Label text |
+| `rightIcon` | `IconFunctionComponent` | — | Right icon |
+| `foldable` | `boolean` | `false` | When `true`, label + rightIcon collapse when not hovered |
+| `size` | `SizeVariant` | `"lg"` | Size preset |
+| `width` | `WidthVariant` | — | Width preset |
+| `tooltip` | `string` | — | Tooltip text |
+| `tooltipSide` | `TooltipSide` | `"top"` | Tooltip placement |
+| `disabled` | `boolean` | `false` | Disables the button |
+
+## Usage
+
+```tsx
+import { SelectButton } from "@opal/components";
+import { SvgStar } from "@opal/icons";
+
+// Basic toggle
+<SelectButton
+  icon={SvgStar}
+  state={isFavorite ? "selected" : "empty"}
+  onClick={toggleFavorite}
+>
+  Favorite
+</SelectButton>
+
+// Foldable — icon stays visible, label folds away
+<SelectButton
+  foldable
+  icon={SvgStar}
+  state="empty"
+>
+  Favorite
+</SelectButton>
+```
diff --git a/web/lib/opal/src/components/buttons/Button/components.tsx b/web/lib/opal/src/components/buttons/select-button/components.tsx
similarity index 54%
rename from web/lib/opal/src/components/buttons/Button/components.tsx
rename to web/lib/opal/src/components/buttons/select-button/components.tsx
index 50dfa9e1d3b..f18f3f3f76b 100644
--- a/web/lib/opal/src/components/buttons/Button/components.tsx
+++ b/web/lib/opal/src/components/buttons/select-button/components.tsx
@@ -1,42 +1,12 @@
-import "@opal/components/buttons/Button/styles.css";
+import "@opal/components/buttons/select-button/styles.css";
 import "@opal/components/tooltip.css";
-import { Interactive, type InteractiveBaseProps } from "@opal/core";
+import { Interactive, type InteractiveStatefulProps } from "@opal/core";
 import type { SizeVariant, WidthVariant } from "@opal/shared";
 import type { TooltipSide } from "@opal/components";
 import type { IconFunctionComponent } from "@opal/types";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import { cn } from "@opal/utils";
-
-const iconVariants = {
-  lg: { padding: "p-0.5", size: 1 },
-  md: { padding: "p-0.5", size: 1 },
-  sm: { padding: "p-0", size: 1 },
-  xs: { padding: "p-0.5", size: 0.75 },
-  "2xs": { padding: "p-0", size: 0.75 },
-  fit: { padding: "p-0.5", size: 1 },
-} as const;
-
-function iconWrapper(
-  Icon: IconFunctionComponent | undefined,
-  size: SizeVariant,
-  includeSpacer: boolean
-) {
-  const { padding: p, size: s } = iconVariants[size];
-
-  return Icon ? (
-    <div className={cn("interactive-foreground-icon", p)}>
-      <Icon
-        className="shrink-0"
-        style={{
-          height: `${s}rem`,
-          width: `${s}rem`,
-        }}
-      />
-    </div>
-  ) : includeSpacer ? (
-    <div />
-  ) : null;
-}
+import { iconWrapper } from "@opal/components/buttons/icon-wrapper";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -49,38 +19,34 @@ function iconWrapper(
  *                        label + rightIcon fold away)
  * - `foldable?: false` → at least one of `icon` or `children` must be provided
  */
-type ButtonContentProps =
+type SelectButtonContentProps =
   | {
       foldable: true;
       icon: IconFunctionComponent;
       children: string;
       rightIcon?: IconFunctionComponent;
-      responsiveHideText?: never;
     }
   | {
       foldable?: false;
       icon?: IconFunctionComponent;
       children: string;
       rightIcon?: IconFunctionComponent;
-      responsiveHideText?: never;
     }
   | {
       foldable?: false;
       icon: IconFunctionComponent;
       children?: string;
       rightIcon?: IconFunctionComponent;
-      responsiveHideText?: boolean;
     };
 
-type ButtonProps = InteractiveBaseProps &
-  ButtonContentProps & {
+type SelectButtonProps = InteractiveStatefulProps &
+  SelectButtonContentProps & {
     /**
      * Size preset — controls gap, text size, and Container height/rounding.
-     * Uses the shared `SizeVariant` scale from `@opal/shared`.
      */
     size?: SizeVariant;
 
-    /** HTML button type. When provided, Container renders a `<button>` element. */
+    /** HTML button type. Container renders a `<button>` element. */
     type?: "submit" | "button" | "reset";
 
     /** Tooltip text shown on hover. */
@@ -94,30 +60,28 @@ type ButtonProps = InteractiveBaseProps &
   };
 
 // ---------------------------------------------------------------------------
-// Button
+// SelectButton
 // ---------------------------------------------------------------------------
 
-function Button({
+function SelectButton({
   icon: Icon,
   children,
   rightIcon: RightIcon,
   size = "lg",
-  foldable,
   type = "button",
+  foldable,
   width,
   tooltip,
   tooltipSide = "top",
-  responsiveHideText = false,
-  ...interactiveBaseProps
-}: ButtonProps) {
+  ...statefulProps
+}: SelectButtonProps) {
   const isLarge = size === "lg";
 
   const labelEl = children ? (
     <span
       className={cn(
-        "opal-button-label",
-        isLarge ? "font-main-ui-body " : "font-secondary-body",
-        responsiveHideText && "hidden md:inline"
+        "opal-select-button-label",
+        isLarge ? "font-main-ui-body" : "font-secondary-body"
       )}
     >
       {children}
@@ -125,10 +89,9 @@ function Button({
   ) : null;
 
   const button = (
-    <Interactive.Base {...interactiveBaseProps}>
+    <Interactive.Stateful {...statefulProps}>
       <Interactive.Container
         type={type}
-        border={interactiveBaseProps.prominence === "secondary"}
         heightVariant={size}
         widthVariant={width}
         roundingVariant={
@@ -137,47 +100,31 @@ function Button({
       >
         <div
           className={cn(
-            "opal-button interactive-foreground",
-            foldable && "opal-button--foldable"
+            "opal-select-button interactive-foreground",
+            foldable && "interactive-foldable-host"
           )}
         >
           {iconWrapper(Icon, size, !foldable && !!children)}
 
           {foldable ? (
-            <div className="opal-button-foldable">
-              <div className="opal-button-foldable-inner">
-                {labelEl}
-                {responsiveHideText ? (
-                  <span className="hidden md:inline-flex">
-                    {iconWrapper(RightIcon, size, !!children)}
-                  </span>
-                ) : (
-                  iconWrapper(RightIcon, size, !!children)
-                )}
-              </div>
-            </div>
+            <Interactive.Foldable>
+              {labelEl}
+              {iconWrapper(RightIcon, size, !!children)}
+            </Interactive.Foldable>
           ) : (
             <>
               {labelEl}
-              {responsiveHideText ? (
-                <span className="hidden md:inline-flex">
-                  {iconWrapper(RightIcon, size, !!children)}
-                </span>
-              ) : (
-                iconWrapper(RightIcon, size, !!children)
-              )}
+              {iconWrapper(RightIcon, size, !!children)}
             </>
           )}
         </div>
       </Interactive.Container>
-    </Interactive.Base>
+    </Interactive.Stateful>
   );
 
   const resolvedTooltip =
     tooltip ??
-    (foldable && interactiveBaseProps.disabled && children
-      ? children
-      : undefined);
+    (foldable && statefulProps.disabled && children ? children : undefined);
 
   if (!resolvedTooltip) return button;
 
@@ -197,4 +144,4 @@ function Button({
   );
 }
 
-export { Button, type ButtonProps };
+export { SelectButton, type SelectButtonProps };
diff --git a/web/lib/opal/src/components/buttons/select-button/styles.css b/web/lib/opal/src/components/buttons/select-button/styles.css
new file mode 100644
index 00000000000..3519f6c4030
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/select-button/styles.css
@@ -0,0 +1,9 @@
+/* SelectButton — layout only; colors handled by Interactive.Stateful */
+
+.opal-select-button {
+  @apply flex flex-row items-center gap-1;
+}
+
+.opal-select-button-label {
+  @apply whitespace-nowrap;
+}
diff --git a/web/lib/opal/src/components/index.ts b/web/lib/opal/src/components/index.ts
index a5a5dfcf5df..a9867f8b7cf 100644
--- a/web/lib/opal/src/components/index.ts
+++ b/web/lib/opal/src/components/index.ts
@@ -5,17 +5,23 @@ export type TooltipSide = "top" | "bottom" | "left" | "right";
 export {
   Button,
   type ButtonProps,
-} from "@opal/components/buttons/Button/components";
+} from "@opal/components/buttons/button/components";
+
+/* SelectButton */
+export {
+  SelectButton,
+  type SelectButtonProps,
+} from "@opal/components/buttons/select-button/components";
 
 /* OpenButton */
 export {
   OpenButton,
   type OpenButtonProps,
-} from "@opal/components/buttons/OpenButton/components";
+} from "@opal/components/buttons/open-button/components";
 
 /* Tag */
 export {
   Tag,
   type TagProps,
   type TagColor,
-} from "@opal/components/Tag/components";
+} from "@opal/components/tag/components";
diff --git a/web/lib/opal/src/components/Tag/README.md b/web/lib/opal/src/components/tag/README.md
similarity index 100%
rename from web/lib/opal/src/components/Tag/README.md
rename to web/lib/opal/src/components/tag/README.md
diff --git a/web/lib/opal/src/components/Tag/components.tsx b/web/lib/opal/src/components/tag/components.tsx
similarity index 97%
rename from web/lib/opal/src/components/Tag/components.tsx
rename to web/lib/opal/src/components/tag/components.tsx
index a4bc09e92ca..34637514be3 100644
--- a/web/lib/opal/src/components/Tag/components.tsx
+++ b/web/lib/opal/src/components/tag/components.tsx
@@ -1,4 +1,4 @@
-import "@opal/components/Tag/styles.css";
+import "@opal/components/tag/styles.css";
 
 import type { IconFunctionComponent } from "@opal/types";
 import { cn } from "@opal/utils";
diff --git a/web/lib/opal/src/components/Tag/styles.css b/web/lib/opal/src/components/tag/styles.css
similarity index 100%
rename from web/lib/opal/src/components/Tag/styles.css
rename to web/lib/opal/src/components/tag/styles.css
diff --git a/web/lib/opal/src/core/README.md b/web/lib/opal/src/core/README.md
index 3ae3f133dcd..bdf5a324267 100644
--- a/web/lib/opal/src/core/README.md
+++ b/web/lib/opal/src/core/README.md
@@ -2,10 +2,11 @@
 
 The lowest-level primitives of the Opal design system. Think of `core` like Rust's `core` crate — compiler intrinsics and foundational types — while higher-level modules (like Rust's `std`) provide the public-facing components that most consumers should reach for first.
 
-End-users *can* use these components directly when needed, but in most cases they should prefer the higher-level components (such as `Button`, `OpenButton`, etc.) that are built on top of `core`.
+End-users *can* use these components directly when needed, but in most cases they should prefer the higher-level components (such as `Button`, `OpenButton`, `SelectButton`, etc.) that are built on top of `core`.
 
 ## Contents
 
 | Primitive | Description | Docs |
 |-----------|-------------|------|
-| [Interactive](./interactive/) | Foundational hover/active/disabled/transient state styling | [README](./interactive/README.md) |
+| [Interactive](./interactive/) | Foundational interactive surface styling (`Stateless`, `Stateful`, `Container`, `Foldable`) | [README](./interactive/README.md) |
+| [Animations](./animations/) | Coordinated hover-state animations across grouped elements (`Hoverable`) | [README](./animations/README.md) |
diff --git a/web/lib/opal/src/core/animations/README.md b/web/lib/opal/src/core/animations/README.md
new file mode 100644
index 00000000000..edf91eb2054
--- /dev/null
+++ b/web/lib/opal/src/core/animations/README.md
@@ -0,0 +1,41 @@
+# Animations (Hoverable)
+
+**Import:** `import { Hoverable } from "@opal/core";`
+
+Provides coordinated hover-state animations across a group of elements. A `Hoverable.Root` tracks hover state and broadcasts it to `Hoverable.Item` descendants via a per-group React context.
+
+## Sub-components
+
+| Sub-component | Role |
+|---|---|
+| `Hoverable.Root` | Wraps a group of items. Tracks mouse enter/leave and provides hover state via context. |
+| `Hoverable.Item` | Reads hover state from its group's context. Applies a CSS class (`opal-hoverable-item`) with variant-specific transitions (e.g. opacity, scale). |
+
+## Props
+
+### Hoverable.Root
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `group` | `string` | `"default"` | Named group for independent hover tracking |
+
+### Hoverable.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `group` | `string` | `"default"` | Which group to listen to |
+| `variant` | `HoverableItemVariant` | `"fade"` | Animation variant |
+
+## Usage
+
+```tsx
+import { Hoverable } from "@opal/core";
+
+<Hoverable.Root group="card">
+  <div>
+    <Hoverable.Item group="card" variant="fade">
+      <span>Appears on hover</span>
+    </Hoverable.Item>
+  </div>
+</Hoverable.Root>
+```
diff --git a/web/lib/opal/src/core/hoverable/components.tsx b/web/lib/opal/src/core/animations/components.tsx
similarity index 99%
rename from web/lib/opal/src/core/hoverable/components.tsx
rename to web/lib/opal/src/core/animations/components.tsx
index 6b66da255cb..762d164b7c5 100644
--- a/web/lib/opal/src/core/hoverable/components.tsx
+++ b/web/lib/opal/src/core/animations/components.tsx
@@ -1,4 +1,4 @@
-import "@opal/core/hoverable/styles.css";
+import "@opal/core/animations/styles.css";
 import React, { createContext, useContext, useState, useCallback } from "react";
 import { cn } from "@opal/utils";
 import type { WithoutStyles } from "@opal/types";
diff --git a/web/lib/opal/src/core/hoverable/styles.css b/web/lib/opal/src/core/animations/styles.css
similarity index 100%
rename from web/lib/opal/src/core/hoverable/styles.css
rename to web/lib/opal/src/core/animations/styles.css
diff --git a/web/lib/opal/src/core/index.ts b/web/lib/opal/src/core/index.ts
index ed3d7f644db..2753d741c3b 100644
--- a/web/lib/opal/src/core/index.ts
+++ b/web/lib/opal/src/core/index.ts
@@ -1,18 +1,44 @@
-/* Hoverable */
+/* Animations (formerly Hoverable) */
 export {
   Hoverable,
   type HoverableRootProps,
   type HoverableItemProps,
   type HoverableItemVariant,
-} from "@opal/core/hoverable/components";
+} from "@opal/core/animations/components";
 
-/* Interactive */
-export {
-  Interactive,
-  type InteractiveBaseProps,
-  type InteractiveBaseVariantProps,
-  type InteractiveBaseSidebarVariantProps,
-  type InteractiveBaseSidebarProminenceTypes,
-  type InteractiveContainerProps,
-  type InteractiveContainerRoundingVariant,
-} from "@opal/core/interactive/components";
+/* Interactive — compound component */
+import { InteractiveStateless } from "@opal/core/interactive/stateless/components";
+import { InteractiveStateful } from "@opal/core/interactive/stateful/components";
+import { InteractiveContainer } from "@opal/core/interactive/container/components";
+import { Foldable } from "@opal/core/interactive/foldable/components";
+
+const Interactive = {
+  Stateless: InteractiveStateless,
+  Stateful: InteractiveStateful,
+  Container: InteractiveContainer,
+  Foldable,
+};
+
+export { Interactive };
+
+/* Interactive — types */
+export type {
+  InteractiveStatelessProps,
+  InteractiveStatelessVariant,
+  InteractiveStatelessProminence,
+  InteractiveStatelessInteraction,
+} from "@opal/core/interactive/stateless/components";
+
+export type {
+  InteractiveStatefulProps,
+  InteractiveStatefulVariant,
+  InteractiveStatefulState,
+  InteractiveStatefulInteraction,
+} from "@opal/core/interactive/stateful/components";
+
+export type {
+  InteractiveContainerProps,
+  InteractiveContainerRoundingVariant,
+} from "@opal/core/interactive/container/components";
+
+export type { FoldableProps } from "@opal/core/interactive/foldable/components";
diff --git a/web/lib/opal/src/core/interactive/README.md b/web/lib/opal/src/core/interactive/README.md
index 6445cfe61c6..3bc3d3d1d6a 100644
--- a/web/lib/opal/src/core/interactive/README.md
+++ b/web/lib/opal/src/core/interactive/README.md
@@ -1,185 +1,137 @@
 # Interactive
 
-The foundational layer for all clickable surfaces in the design system. Defines hover, active, disabled, and transient state styling in a single place. Higher-level components (Button, OpenButton, etc.) compose on top of it.
+The foundational layer for all clickable surfaces in the design system. Defines hover, active, disabled, and interaction-override state styling in a single place. Higher-level components (Button, SelectButton, OpenButton, etc.) compose on top of it.
+
+## Sub-components
+
+| Sub-component | Role | Docs |
+|---|---|---|
+| `Interactive.Stateless` | Stateless surfaces (buttons, links, cards). Variant × prominence color matrix. | [README](./stateless/README.md) |
+| `Interactive.Stateful` | Stateful surfaces (toggles, sidebar items). Variant × state color matrix. | [README](./stateful/README.md) |
+| `Interactive.Container` | Structural box with height, rounding, padding, and optional border. Shared by both. | [README](./container/README.md) |
+| `Interactive.Foldable` | Zero-width collapsible wrapper with CSS grid animation. | [README](./foldable/README.md) |
+
+## Foreground colour system
+
+Each variant/prominence/state combination sets two CSS custom properties:
+- `--interactive-foreground` — text color
+- `--interactive-foreground-icon` — icon color
+
+Both are registered via `@property` as `<color>` in `shared.css`, enabling the browser to interpolate them directly on the parent `.interactive` element. Children read the variables with no independent transitions, guaranteeing perfect sync.
+
+**Opt-in classes:**
+- `.interactive-foreground` — sets `color: var(--interactive-foreground)`
+- `.interactive-foreground-icon` — sets `color: var(--interactive-foreground-icon)`
+
+## Interaction override
+
+Both `Stateless` and `Stateful` support `interaction?: "rest" | "hover" | "active"` for JS-controlled visual state overrides via `data-interaction`.
 
 ## Colour tables
 
-### Default
+### Stateless: Default
 
 **Background**
 
 | | Primary | Secondary | Tertiary | Internal |
 |---|---|---|---|---|
 | **Rest** | `theme-primary-05` | `background-tint-01` | `transparent` | `transparent` |
-| **Hover / Transient** | `theme-primary-04` | `background-tint-02` | `background-tint-02` | `background-tint-00` |
+| **Hover** | `theme-primary-04` | `background-tint-02` | `background-tint-02` | `background-tint-00` |
 | **Active** | `theme-primary-06` | `background-tint-00` | `background-tint-00` | `background-tint-00` |
-| **Disabled** | `background-neutral-04` | `background-neutral-03` | `transparent` + `opacity-50` | `transparent` + `opacity-50` |
+| **Disabled** | `background-neutral-04` | `background-neutral-03` | `transparent` | `transparent` |
 
 **Foreground**
 
 | | Primary | Secondary | Tertiary | Internal |
 |---|---|---|---|---|
 | **Rest** | `text-inverted-05` | `text-03` | `text-03` | `text-03` |
-| **Hover / Transient** | `text-inverted-05` | `text-04` | `text-04` | `text-04` |
+| **Hover** | `text-inverted-05` | `text-04` | `text-04` | `text-04` |
 | **Active** | `text-inverted-05` | `text-05` | `text-05` | `text-05` |
 | **Disabled** | `text-inverted-04` | `text-01` | `text-01` | `text-01` |
 
-### Action
+### Stateless: Action
 
 **Background**
 
 | | Primary | Secondary | Tertiary | Internal |
 |---|---|---|---|---|
 | **Rest** | `action-link-05` | `background-tint-01` | `transparent` | `transparent` |
-| **Hover / Transient** | `action-link-04` | `background-tint-02` | `background-tint-02` | `background-tint-00` |
+| **Hover** | `action-link-04` | `background-tint-02` | `background-tint-02` | `background-tint-00` |
 | **Active** | `action-link-06` | `background-tint-00` | `background-tint-00` | `background-tint-00` |
-| **Disabled** | `action-link-02` | `background-neutral-02` | `transparent` + `opacity-50` | `transparent` + `opacity-50` |
+| **Disabled** | `action-link-02` | `background-neutral-02` | `transparent` | `transparent` |
 
 **Foreground**
 
 | | Primary | Secondary | Tertiary | Internal |
 |---|---|---|---|---|
 | **Rest** | `text-light-05` | `action-text-link-05` | `action-text-link-05` | `action-text-link-05` |
-| **Hover / Transient** | `text-light-05` | `action-text-link-05` | `action-text-link-05` | `action-text-link-05` |
+| **Hover** | `text-light-05` | `action-text-link-05` | `action-text-link-05` | `action-text-link-05` |
 | **Active** | `text-light-05` | `action-text-link-05` | `action-text-link-05` | `action-text-link-05` |
 | **Disabled** | `text-01` | `action-link-03` | `action-link-03` | `action-link-03` |
 
-### Danger
+### Stateless: Danger
 
 **Background**
 
 | | Primary | Secondary | Tertiary | Internal |
 |---|---|---|---|---|
 | **Rest** | `action-danger-05` | `background-tint-01` | `transparent` | `transparent` |
-| **Hover / Transient** | `action-danger-04` | `background-tint-02` | `background-tint-02` | `background-tint-00` |
+| **Hover** | `action-danger-04` | `background-tint-02` | `background-tint-02` | `background-tint-00` |
 | **Active** | `action-danger-06` | `background-tint-00` | `background-tint-00` | `background-tint-00` |
-| **Disabled** | `action-danger-02` | `background-neutral-02` | `transparent` + `opacity-50` | `transparent` + `opacity-50` |
+| **Disabled** | `action-danger-02` | `background-neutral-02` | `transparent` | `transparent` |
 
 **Foreground**
 
 | | Primary | Secondary | Tertiary | Internal |
 |---|---|---|---|---|
 | **Rest** | `text-light-05` | `action-text-danger-05` | `action-text-danger-05` | `action-text-danger-05` |
-| **Hover / Transient** | `text-light-05` | `action-text-danger-05` | `action-text-danger-05` | `action-text-danger-05` |
+| **Hover** | `text-light-05` | `action-text-danger-05` | `action-text-danger-05` | `action-text-danger-05` |
 | **Active** | `text-light-05` | `action-text-danger-05` | `action-text-danger-05` | `action-text-danger-05` |
 | **Disabled** | `text-01` | `action-danger-03` | `action-danger-03` | `action-danger-03` |
 
-### Select (unselected)
+### Stateful: Select-Heavy / Select-Light
 
-**Background**
+**Background (empty/filled)**
 
-| | Light | Heavy |
+| | Select-Heavy | Select-Light |
 |---|---|---|
 | **Rest** | `transparent` | `transparent` |
-| **Hover / Transient** | `background-tint-02` | `background-tint-02` |
+| **Hover** | `background-tint-02` | `background-tint-02` |
 | **Active** | `background-neutral-00` | `background-neutral-00` |
 | **Disabled** | `transparent` | `transparent` |
 
-**Foreground**
+**Background (selected)**
 
-| | Light | Heavy |
+| | Select-Heavy | Select-Light |
 |---|---|---|
-| **Rest** | `text-04` (icon: `text-03`) | `text-04` (icon: `text-03`) |
-| **Hover / Transient** | `text-04` | `text-04` |
-| **Active** | `text-05` | `text-05` |
-| **Disabled** | `text-02` | `text-02` |
-
-### Select (selected)
+| **Rest** | `action-link-01` | `transparent` |
+| **Hover** | `background-tint-02` | `background-tint-02` |
+| **Active** | `background-tint-00` | `background-tint-00` |
+| **Disabled** | `transparent` | `transparent` |
 
-**Background**
+**Foreground (empty)**
 
-| | Light | Heavy |
+| | Text | Icon |
 |---|---|---|
-| **Rest** | `transparent` | `action-link-01` |
-| **Hover / Transient** | `background-tint-02` | `background-tint-02` |
-| **Active** | `background-neutral-00` | `background-tint-00` |
-| **Disabled** | `transparent` | `transparent` |
+| **Rest** | `text-04` | `text-03` |
+| **Hover** | `text-04` | `text-04` |
+| **Active** | `text-05` | `text-05` |
+| **Disabled** | `text-01` | `text-01` |
 
-**Foreground**
+**Foreground (selected)**
 
-| | Light | Heavy |
+| | Text | Icon |
 |---|---|---|
 | **Rest** | `action-link-05` | `action-link-05` |
-| **Hover / Transient** | `action-link-05` | `action-link-05` |
+| **Hover** | `action-link-05` | `action-link-05` |
 | **Active** | `action-link-05` | `action-link-05` |
 | **Disabled** | `action-link-03` | `action-link-03` |
 
-### Sidebar (unselected)
-
-> No CSS `:active` state — only hover/transient and selected.
-
-**Background**
-
-| | Light |
-|---|---|
-| **Rest** | `transparent` |
-| **Hover / Transient** | `background-tint-03` |
-| **Disabled** | `transparent` |
-
-**Foreground**
-
-| | Light |
-|---|---|
-| **Rest** | `text-03` |
-| **Hover / Transient** | `text-04` |
-| **Disabled** | `text-01` |
-
-### Sidebar (selected)
-
-> Completely static — hover and transient have no effect.
+### Stateful: Sidebar
 
 **Background**
 
-| | Light |
-|---|---|
-| **All states** | `background-tint-00` |
-| **Disabled** | `transparent` |
-
-**Foreground**
-
-| | Light |
-|---|---|
-| **All states** | `text-03` (icon: `text-02`) |
-| **Disabled** | `text-01` |
-
-## Sub-components
-
-| Sub-component | Role |
-|---|---|
-| `Interactive.Base` | Applies the `.interactive` CSS class and data-attributes for variant and transient states via Radix Slot. |
-| `Interactive.Container` | Structural `<div>` with flex layout, border, padding, rounding, and height variant presets. |
-
-## Foreground colour (`--interactive-foreground`)
-
-Each variant+prominence combination sets a `--interactive-foreground` CSS custom property that cascades to all descendants. The variable updates automatically across hover, active, and disabled states.
-
-**Buy-in:** Descendants opt in to parent-controlled text colour by referencing the variable. Elements that don't reference it are unaffected — the variable is inert unless consumed.
-
-```css
-/* Utility class for plain elements */
-.interactive-foreground {
-  color: var(--interactive-foreground);
-}
-```
-
-```tsx
-// Future Text component — `interactive` prop triggers buy-in
-<Interactive.Base variant="action" prominence="tertiary" onClick={handleClick}>
-  <Interactive.Container>
-    <Text interactive>Reacts to hover/active/disabled</Text>
-    <Text color="text03">Stays static</Text>
-  </Interactive.Container>
-</Interactive.Base>
-```
-
-This is selective — component authors decide per-instance which text responds to interactivity. For example, a `LineItem` might opt in its title but not its description.
-
-## Style invariants
-
-The following invariants hold across all variant+prominence combinations:
-
-1. For each variant, **secondary and tertiary rows are identical** (e.g. `default+secondary` = `default+tertiary` across all states).
-2. **Hover and transient (`data-transient`) columns are always equal** (both background and foreground) for non-select variants. CSS `:active` is also equal to hover/transient for all rows *except* `default+secondary` and `default+tertiary`, where foreground progressively darkens (`text-03` -> `text-04` -> `text-05`) and `:active` uses a distinct background (`tint-00` instead of `tint-02`). For the `select` variant, `data-transient` forces hover background while `data-selected` independently controls the action-link foreground colours.
-3. **`action+primary` and `danger+primary` are row-wise identical** (both use `--text-light-05` / `--text-01`).
-4. **`action+secondary`/`tertiary` and `danger+secondary`/`tertiary` are structurally identical** — only the colour family differs (`link` [blue] vs `danger` [red]).
-5. **`internal` is similar to `tertiary`** but uses a subtler hover background (`tint-00` instead of `tint-02`).
+| | Empty/Filled | Selected |
+|---|---|---|
+| **Rest** | `transparent` | `background-tint-00` |
+| **Hover** | `background-tint-03` | `background-tint-03` |
diff --git a/web/lib/opal/src/core/interactive/components.tsx b/web/lib/opal/src/core/interactive/components.tsx
deleted file mode 100644
index 7c2fa2e44a4..00000000000
--- a/web/lib/opal/src/core/interactive/components.tsx
+++ /dev/null
@@ -1,502 +0,0 @@
-import Link from "next/link";
-import type { Route } from "next";
-import "@opal/core/interactive/styles.css";
-import React from "react";
-import { Slot } from "@radix-ui/react-slot";
-import { cn } from "@opal/utils";
-import type { WithoutStyles } from "@opal/types";
-import {
-  sizeVariants,
-  type SizeVariant,
-  widthVariants,
-  type WidthVariant,
-} from "@opal/shared";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type InteractiveBaseVariantTypes = "default" | "action" | "danger";
-type InteractiveBaseProminenceTypes =
-  | "primary"
-  | "secondary"
-  | "tertiary"
-  | "internal";
-type InteractiveBaseSelectVariantProps = {
-  variant?: "select";
-  prominence?: "light" | "heavy";
-  selected?: boolean;
-};
-
-type InteractiveBaseSidebarProminenceTypes = "light";
-type InteractiveBaseSidebarVariantProps = {
-  variant: "sidebar";
-  prominence?: InteractiveBaseSidebarProminenceTypes;
-  selected?: boolean;
-};
-
-/**
- * Discriminated union tying `variant` to `prominence`.
- *
- * - `"none"` accepts no prominence (`prominence` must not be provided)
- * - `"select"` accepts an optional prominence (defaults to `"light"`) and
- *   an optional `selected` boolean that switches foreground to action-link colours
- * - `"sidebar"` accepts an optional prominence (defaults to `"light"`) and
- *   an optional `selected` boolean for the focused/active-item state
- * - `"default"`, `"action"`, and `"danger"` accept an optional prominence
- *   (defaults to `"primary"`)
- */
-type InteractiveBaseVariantProps =
-  | { variant?: "none"; prominence?: never; selected?: never }
-  | InteractiveBaseSelectVariantProps
-  | InteractiveBaseSidebarVariantProps
-  | {
-      variant?: InteractiveBaseVariantTypes;
-      prominence?: InteractiveBaseProminenceTypes;
-      selected?: never;
-    };
-
-/**
- * Border-radius presets for `Interactive.Container`.
- *
- * - `"default"` — Default radius of 0.75rem (12px), matching card rounding
- * - `"compact"` — Smaller radius of 0.5rem (8px), for tighter/inline elements
- */
-type InteractiveContainerRoundingVariant =
-  keyof typeof interactiveContainerRoundingVariants;
-const interactiveContainerRoundingVariants = {
-  default: "rounded-12",
-  compact: "rounded-08",
-  mini: "rounded-04",
-} as const;
-
-// ---------------------------------------------------------------------------
-// InteractiveBase
-// ---------------------------------------------------------------------------
-
-/**
- * Base props for {@link InteractiveBase} (without variant/prominence).
- *
- * Extends standard HTML element attributes (minus `className` and `style`,
- * which are controlled by the design system).
- */
-interface InteractiveBasePropsBase
-  extends WithoutStyles<React.HTMLAttributes<HTMLElement>> {
-  /**
-   * Ref forwarded to the underlying element (the single child).
-   * Since `Interactive.Base` uses Radix Slot, the ref attaches to whatever
-   * element the child renders.
-   */
-  ref?: React.Ref<HTMLElement>;
-
-  /**
-   * Tailwind group class to apply (e.g. `"group/AgentCard"`).
-   *
-   * When set, this class is added to the element, enabling `group-hover:*`
-   * utilities on descendant elements. Useful for showing/hiding child elements
-   * (like action buttons) when the interactive surface is hovered.
-   *
-   * @example
-   * ```tsx
-   * <Interactive.Base group="group/Card">
-   *   <Card>
-   *     <IconButton className="hidden group-hover/Card:flex" />
-   *   </Card>
-   * </Interactive.Base>
-   * ```
-   */
-  group?: string;
-
-  /**
-   * When `true`, forces the transient (hover) visual state regardless of
-   * actual pointer state.
-   *
-   * This sets `data-transient="true"` on the element, which the CSS uses to
-   * apply the hover-state background and foreground. Useful for popover
-   * triggers, toggle buttons, or any UI where you want to programmatically
-   * indicate that the element is currently active.
-   *
-   * @default false
-   */
-  transient?: boolean;
-
-  /**
-   * When `true`, disables the interactive element.
-   *
-   * Sets `data-disabled` and `aria-disabled` attributes. CSS uses `data-disabled`
-   * to apply disabled styles (muted colors, `cursor-not-allowed`). Click handlers
-   * and `href` navigation are blocked in JS, but hover events still fire to
-   * support tooltips explaining why the element is disabled.
-   *
-   * @default false
-   */
-  disabled?: boolean;
-
-  /**
-   * URL to navigate to when clicked.
-   *
-   * Passed through Slot to the child element (typically `Interactive.Container`),
-   * which renders an `<a>` tag when `href` is present. This keeps all styling
-   * (backgrounds, rounding, overflow) on a single element.
-   *
-   * @example
-   * ```tsx
-   * <Interactive.Base href="/settings">
-   *   <Interactive.Container border>
-   *     <span>Go to Settings</span>
-   *   </Interactive.Container>
-   * </Interactive.Base>
-   * ```
-   */
-  href?: string;
-
-  /**
-   * Link target (e.g. `"_blank"`). Only used when `href` is provided.
-   */
-  target?: string;
-}
-
-/**
- * Props for {@link InteractiveBase}.
- *
- * Intersects the base props with the {@link InteractiveBaseVariantProps}
- * discriminated union so that `variant` and `prominence` are correlated:
- *
- * - `"none"` — `prominence` must not be provided
- * - `"select"` — `prominence` is optional (defaults to `"light"`); `selected` switches foreground to action-link colours
- * - `"default"` / `"action"` / `"danger"` — `prominence` is optional (defaults to `"primary"`)
- */
-type InteractiveBaseProps = InteractiveBasePropsBase &
-  InteractiveBaseVariantProps;
-
-/**
- * The foundational interactive surface primitive.
- *
- * `Interactive.Base` is the lowest-level building block for any clickable
- * element in the design system. It applies:
- *
- * 1. The `.interactive` CSS class (flex layout, pointer cursor, color transitions)
- * 2. `data-interactive-base-variant` and `data-interactive-base-prominence`
- *    attributes for variant-specific background colors (both omitted for `"none"`;
- *    prominence omitted when not provided)
- * 3. `data-transient` attribute for forced transient (hover) state
- * 4. `data-disabled` attribute for disabled styling
- *
- * All props are merged onto the single child element via Radix `Slot`, meaning
- * the child element *becomes* the interactive surface (no wrapper div).
- *
- * @example
- * ```tsx
- * // Basic usage with a container
- * <Interactive.Base variant="default" prominence="primary">
- *   <Interactive.Container border>
- *     <span>Click me</span>
- *   </Interactive.Container>
- * </Interactive.Base>
- *
- * // Wrapping a component that controls its own background
- * <Interactive.Base variant="none" onClick={handleClick}>
- *   <Card>Card controls its own background</Card>
- * </Interactive.Base>
- *
- * // With group hover for child visibility
- * <Interactive.Base group="group/Item" onClick={handleClick}>
- *   <div>
- *     <span>Item</span>
- *     <button className="hidden group-hover/Item:block">Delete</button>
- *   </div>
- * </Interactive.Base>
- *
- * // As a link
- * <Interactive.Base href="/settings">
- *   <Interactive.Container border>
- *     <span>Go to Settings</span>
- *   </Interactive.Container>
- * </Interactive.Base>
- * ```
- *
- * @see InteractiveBaseProps for detailed prop documentation
- */
-function InteractiveBase({
-  ref,
-  variant = "default",
-  prominence,
-  selected,
-  group,
-  transient,
-  disabled,
-  href,
-  target,
-  ...props
-}: InteractiveBaseProps) {
-  const effectiveProminence =
-    prominence ??
-    (variant === "select" || variant === "sidebar" ? "light" : "primary");
-  const classes = cn(
-    "interactive",
-    !props.onClick && !href && "!cursor-default !select-auto",
-    group
-  );
-
-  const dataAttrs = {
-    "data-interactive-base-variant": variant !== "none" ? variant : undefined,
-    "data-interactive-base-prominence":
-      variant !== "none" ? effectiveProminence : undefined,
-    "data-transient": transient ? "true" : undefined,
-    "data-selected": selected ? "true" : undefined,
-    "data-disabled": disabled ? "true" : undefined,
-    "aria-disabled": disabled || undefined,
-  };
-
-  const { onClick, ...slotProps } = props;
-
-  // href, target, and rel are passed through Slot to the child element
-  // (typically Interactive.Container), which renders an <a> when href is present.
-  const linkAttrs = href
-    ? {
-        href: disabled ? undefined : href,
-        target,
-        rel: target === "_blank" ? "noopener noreferrer" : undefined,
-      }
-    : {};
-
-  return (
-    <Slot
-      ref={ref}
-      className={classes}
-      {...dataAttrs}
-      {...linkAttrs}
-      {...slotProps}
-      onClick={
-        disabled && href
-          ? (e: React.MouseEvent) => e.preventDefault()
-          : disabled
-            ? undefined
-            : onClick
-      }
-    />
-  );
-}
-
-// ---------------------------------------------------------------------------
-// InteractiveContainer
-// ---------------------------------------------------------------------------
-
-/**
- * Props for {@link InteractiveContainer}.
- *
- * Extends standard `<div>` attributes (minus `className` and `style`).
- */
-interface InteractiveContainerProps
-  extends WithoutStyles<React.HTMLAttributes<HTMLDivElement>> {
-  /**
-   * Ref forwarded to the underlying element.
-   */
-  ref?: React.Ref<HTMLElement>;
-
-  /**
-   * HTML button type (e.g. `"submit"`, `"button"`, `"reset"`).
-   *
-   * When provided, renders a `<button>` element instead of a `<div>`.
-   * This keeps all styling (background, rounding, height) on a single
-   * element — unlike a wrapper approach which would split them.
-   *
-   * Mutually exclusive with `href`.
-   *
-   * @example
-   * ```tsx
-   * <Interactive.Base>
-   *   <Interactive.Container type="submit">
-   *     <span>Submit</span>
-   *   </Interactive.Container>
-   * </Interactive.Base>
-   * ```
-   */
-  type?: "submit" | "button" | "reset";
-
-  /**
-   * When `true`, applies a 1px border using the theme's border color.
-   *
-   * The border uses the default `border` utility class, which references
-   * the `--border` CSS variable for consistent theming.
-   *
-   * @default false
-   */
-  border?: boolean;
-
-  /**
-   * Border-radius preset controlling corner rounding.
-   *
-   * - `"default"` — 0.75rem (12px), matching card-level rounding
-   * - `"compact"` — 0.5rem (8px), for smaller/inline elements
-   *
-   * @default "default"
-   */
-  roundingVariant?: InteractiveContainerRoundingVariant;
-
-  /**
-   * Size preset controlling the container's height, min-width, and padding.
-   * Uses the shared `SizeVariant` scale from `@opal/shared`.
-   *
-   * @default "lg"
-   * @see {@link SizeVariant} for the full list of presets.
-   */
-  heightVariant?: SizeVariant;
-
-  /**
-   * Width preset controlling the container's horizontal size.
-   *
-   * - `"auto"` — Shrink-wraps to content width
-   * - `"full"` — Stretches to fill the parent's width (`w-full`)
-   *
-   * @default "auto"
-   */
-  widthVariant?: WidthVariant;
-}
-
-/**
- * Structural container for use inside `Interactive.Base`.
- *
- * Provides a `<div>` with design-system-controlled border, padding, rounding,
- * and height. Use this when you need a consistent container shape for
- * interactive content.
- *
- * When nested directly under `Interactive.Base`, Radix Slot merges the parent's
- * `className` and `style` onto this component at runtime. This component
- * correctly extracts and merges those injected values so they aren't lost.
- *
- * @example
- * ```tsx
- * // Standard card-like container
- * <Interactive.Base>
- *   <Interactive.Container border>
- *     <Content icon={SvgIcon} title="Option" />
- *   </Interactive.Container>
- * </Interactive.Base>
- *
- * // Compact, borderless container with no padding
- * <Interactive.Base variant="default" prominence="tertiary">
- *   <Interactive.Container heightVariant="md" roundingVariant="compact">
- *     <span>Inline item</span>
- *   </Interactive.Container>
- * </Interactive.Base>
- * ```
- *
- * @see InteractiveContainerProps for detailed prop documentation
- */
-function InteractiveContainer({
-  ref,
-  type,
-  border,
-  roundingVariant = "default",
-  heightVariant = "lg",
-  widthVariant = "auto",
-  ...props
-}: InteractiveContainerProps) {
-  // Radix Slot injects className, style, href, target, rel, and other
-  // attributes at runtime (bypassing WithoutStyles), so we extract and
-  // merge them to preserve the Slot-injected values.
-  const {
-    className: slotClassName,
-    style: slotStyle,
-    href,
-    target,
-    rel,
-    ...rest
-  } = props as typeof props & {
-    className?: string;
-    style?: React.CSSProperties;
-    href?: string;
-    target?: string;
-    rel?: string;
-  };
-  const { height, minWidth, padding } = sizeVariants[heightVariant];
-  const sharedProps = {
-    ...rest,
-    className: cn(
-      "interactive-container",
-      interactiveContainerRoundingVariants[roundingVariant],
-      height,
-      minWidth,
-      padding,
-      widthVariants[widthVariant],
-      slotClassName
-    ),
-    "data-border": border ? ("true" as const) : undefined,
-    style: slotStyle,
-  };
-
-  // When href is provided (via Slot from Interactive.Base), render an <a>
-  // so all styling (backgrounds, rounding, overflow) lives on one element.
-  if (href) {
-    return (
-      <Link
-        ref={ref as React.Ref<HTMLAnchorElement>}
-        href={href as Route}
-        target={target}
-        rel={rel}
-        {...(sharedProps as React.HTMLAttributes<HTMLAnchorElement>)}
-      />
-    );
-  }
-
-  if (type) {
-    // When Interactive.Base is disabled it injects aria-disabled via Slot.
-    // Map that to the native disabled attribute so a <button type="submit">
-    // cannot trigger form submission in the disabled state.
-    const ariaDisabled = (rest as Record<string, unknown>)["aria-disabled"];
-    const nativeDisabled =
-      ariaDisabled === true || ariaDisabled === "true" || undefined;
-    return (
-      <button
-        ref={ref as React.Ref<HTMLButtonElement>}
-        type={type}
-        disabled={nativeDisabled}
-        {...(sharedProps as React.HTMLAttributes<HTMLButtonElement>)}
-      />
-    );
-  }
-  return <div ref={ref as React.Ref<HTMLDivElement>} {...sharedProps} />;
-}
-
-// ---------------------------------------------------------------------------
-// Compound export
-// ---------------------------------------------------------------------------
-
-/**
- * Interactive compound component for building clickable surfaces.
- *
- * Provides two sub-components:
- *
- * - `Interactive.Base` — The foundational layer that applies hover/active/transient
- *   state styling via CSS data-attributes. Uses Radix Slot to merge onto child.
- *
- * - `Interactive.Container` — A structural `<div>` with design-system presets
- *   for border, padding, rounding, and height.
- *
- * @example
- * ```tsx
- * import { Interactive } from "@opal/core";
- *
- * <Interactive.Base variant="default" prominence="tertiary" onClick={handleClick}>
- *   <Interactive.Container border>
- *     <span>Clickable card</span>
- *   </Interactive.Container>
- * </Interactive.Base>
- * ```
- */
-const Interactive = {
-  Base: InteractiveBase,
-  Container: InteractiveContainer,
-};
-
-export {
-  Interactive,
-  type InteractiveBaseProps,
-  type InteractiveBaseVariantProps,
-  type InteractiveBaseSelectVariantProps,
-  type InteractiveBaseSidebarVariantProps,
-  type InteractiveBaseSidebarProminenceTypes,
-  type InteractiveContainerProps,
-  type InteractiveContainerRoundingVariant,
-};
diff --git a/web/lib/opal/src/core/interactive/container/README.md b/web/lib/opal/src/core/interactive/container/README.md
new file mode 100644
index 00000000000..20d9a116beb
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/container/README.md
@@ -0,0 +1,25 @@
+# Interactive.Container
+
+**Import:** `import { Interactive } from "@opal/core";` — use as `Interactive.Container`.
+
+Structural container shared by both `Interactive.Stateless` and `Interactive.Stateful`. Provides consistent height, rounding, padding, and optional border. Renders a `<div>` by default, or a `<button>` when `type` is provided.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `heightVariant` | `SizeVariant` | `"lg"` | Height preset (`2xs`–`lg`, `fit`) |
+| `roundingVariant` | `"default" \| "compact" \| "mini"` | `"default"` | Border-radius preset |
+| `widthVariant` | `WidthVariant` | — | Width preset (`auto`, `full`) |
+| `border` | `boolean` | `false` | Renders a 1px border |
+| `type` | `"submit" \| "button" \| "reset"` | — | When set, renders a `<button>` element |
+
+## Usage
+
+```tsx
+<Interactive.Stateless variant="default" prominence="primary">
+  <Interactive.Container heightVariant="sm" roundingVariant="compact" border>
+    <span>Content</span>
+  </Interactive.Container>
+</Interactive.Stateless>
+```
diff --git a/web/lib/opal/src/core/interactive/container/components.tsx b/web/lib/opal/src/core/interactive/container/components.tsx
new file mode 100644
index 00000000000..3f52a430193
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/container/components.tsx
@@ -0,0 +1,168 @@
+import Link from "next/link";
+import type { Route } from "next";
+import "@opal/core/interactive/shared.css";
+import React from "react";
+import { cn } from "@opal/utils";
+import type { WithoutStyles } from "@opal/types";
+import {
+  sizeVariants,
+  type SizeVariant,
+  widthVariants,
+  type WidthVariant,
+} from "@opal/shared";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Border-radius presets for `Interactive.Container`.
+ *
+ * - `"default"` — Default radius of 0.75rem (12px), matching card rounding
+ * - `"compact"` — Smaller radius of 0.5rem (8px), for tighter/inline elements
+ * - `"mini"` — Smallest radius of 0.25rem (4px)
+ */
+type InteractiveContainerRoundingVariant =
+  keyof typeof interactiveContainerRoundingVariants;
+const interactiveContainerRoundingVariants = {
+  default: "rounded-12",
+  compact: "rounded-08",
+  mini: "rounded-04",
+} as const;
+
+/**
+ * Props for {@link InteractiveContainer}.
+ *
+ * Extends standard `<div>` attributes (minus `className` and `style`).
+ */
+interface InteractiveContainerProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLDivElement>> {
+  /**
+   * Ref forwarded to the underlying element.
+   */
+  ref?: React.Ref<HTMLElement>;
+
+  /**
+   * HTML button type (e.g. `"submit"`, `"button"`, `"reset"`).
+   *
+   * When provided, renders a `<button>` element instead of a `<div>`.
+   * This keeps all styling (background, rounding, height) on a single
+   * element — unlike a wrapper approach which would split them.
+   *
+   * Mutually exclusive with `href`.
+   */
+  type?: "submit" | "button" | "reset";
+
+  /**
+   * When `true`, applies a 1px border using the theme's border color.
+   *
+   * @default false
+   */
+  border?: boolean;
+
+  /**
+   * Border-radius preset controlling corner rounding.
+   *
+   * @default "default"
+   */
+  roundingVariant?: InteractiveContainerRoundingVariant;
+
+  /**
+   * Size preset controlling the container's height, min-width, and padding.
+   *
+   * @default "lg"
+   */
+  heightVariant?: SizeVariant;
+
+  /**
+   * Width preset controlling the container's horizontal size.
+   *
+   * @default "auto"
+   */
+  widthVariant?: WidthVariant;
+}
+
+// ---------------------------------------------------------------------------
+// InteractiveContainer
+// ---------------------------------------------------------------------------
+
+/**
+ * Structural container for use inside `Interactive.Stateless` or
+ * `Interactive.Stateful`.
+ *
+ * Provides a `<div>` with design-system-controlled border, padding, rounding,
+ * and height. When nested under a Radix Slot-based parent, correctly extracts
+ * and merges injected `className` and `style` values.
+ */
+function InteractiveContainer({
+  ref,
+  type,
+  border,
+  roundingVariant = "default",
+  heightVariant = "lg",
+  widthVariant = "auto",
+  ...props
+}: InteractiveContainerProps) {
+  const {
+    className: slotClassName,
+    style: slotStyle,
+    href,
+    target,
+    rel,
+    ...rest
+  } = props as typeof props & {
+    className?: string;
+    style?: React.CSSProperties;
+    href?: string;
+    target?: string;
+    rel?: string;
+  };
+  const { height, minWidth, padding } = sizeVariants[heightVariant];
+  const sharedProps = {
+    ...rest,
+    className: cn(
+      "interactive-container",
+      interactiveContainerRoundingVariants[roundingVariant],
+      height,
+      minWidth,
+      padding,
+      widthVariants[widthVariant],
+      slotClassName
+    ),
+    "data-border": border ? ("true" as const) : undefined,
+    style: slotStyle,
+  };
+
+  if (href) {
+    return (
+      <Link
+        ref={ref as React.Ref<HTMLAnchorElement>}
+        href={href as Route}
+        target={target}
+        rel={rel}
+        {...(sharedProps as React.HTMLAttributes<HTMLAnchorElement>)}
+      />
+    );
+  }
+
+  if (type) {
+    const ariaDisabled = (rest as Record<string, unknown>)["aria-disabled"];
+    const nativeDisabled =
+      ariaDisabled === true || ariaDisabled === "true" || undefined;
+    return (
+      <button
+        ref={ref as React.Ref<HTMLButtonElement>}
+        type={type}
+        disabled={nativeDisabled}
+        {...(sharedProps as React.HTMLAttributes<HTMLButtonElement>)}
+      />
+    );
+  }
+  return <div ref={ref as React.Ref<HTMLDivElement>} {...sharedProps} />;
+}
+
+export {
+  InteractiveContainer,
+  type InteractiveContainerProps,
+  type InteractiveContainerRoundingVariant,
+};
diff --git a/web/lib/opal/src/core/interactive/foldable/README.md b/web/lib/opal/src/core/interactive/foldable/README.md
new file mode 100644
index 00000000000..ab9cc5ab308
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/foldable/README.md
@@ -0,0 +1,38 @@
+# Interactive.Foldable
+
+**Import:** `import { Interactive } from "@opal/core";` — use as `Interactive.Foldable`.
+
+A zero-width collapsible wrapper that expands when its ancestor `.interactive` element is hovered or has an interaction override. Uses a CSS grid `0fr → 1fr` animation for smooth expand/collapse.
+
+## Requirements
+
+- Must be placed inside an `Interactive.Stateless` or `Interactive.Stateful` tree.
+- The direct parent element should add the `interactive-foldable-host` class for synchronized gap transitions.
+
+## Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Content that folds/unfolds |
+
+## CSS triggers
+
+The foldable expands when any of these conditions are met on an ancestor `.interactive`:
+- `:hover` pseudo-class
+- `data-interaction="hover"`
+- `data-interaction="active"`
+
+## Usage
+
+```tsx
+<Interactive.Stateful variant="select-heavy" state="empty">
+  <Interactive.Container>
+    <div className="interactive-foldable-host flex items-center">
+      <Icon />
+      <Interactive.Foldable>
+        <span>Label text</span>
+      </Interactive.Foldable>
+    </div>
+  </Interactive.Container>
+</Interactive.Stateful>
+```
diff --git a/web/lib/opal/src/core/interactive/foldable/components.tsx b/web/lib/opal/src/core/interactive/foldable/components.tsx
new file mode 100644
index 00000000000..83ad3e1ca0e
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/foldable/components.tsx
@@ -0,0 +1,51 @@
+import "@opal/core/interactive/foldable/styles.css";
+import React from "react";
+import type { WithoutStyles } from "@opal/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface FoldableProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLDivElement>> {
+  children: React.ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// Foldable
+// ---------------------------------------------------------------------------
+
+/**
+ * A zero-width collapsible wrapper that expands when its ancestor
+ * `.interactive` element is hovered or has an interaction override.
+ *
+ * Uses a CSS grid `0fr ↔ 1fr` animation for smooth expand/collapse.
+ * Must be placed inside an `Interactive.Stateless` or `Interactive.Stateful`
+ * tree for the CSS triggers to work.
+ *
+ * The parent element should add the `interactive-foldable-host` class to
+ * get synchronized gap transitions.
+ *
+ * @example
+ * ```tsx
+ * <Interactive.Stateful variant="select-heavy" state="empty">
+ *   <Interactive.Container>
+ *     <div className="interactive-foldable-host flex items-center">
+ *       <Icon />
+ *       <Foldable>
+ *         <span>Label text</span>
+ *       </Foldable>
+ *     </div>
+ *   </Interactive.Container>
+ * </Interactive.Stateful>
+ * ```
+ */
+function Foldable({ children, ...props }: FoldableProps) {
+  return (
+    <div {...props} className="interactive-foldable">
+      <div className="interactive-foldable-inner">{children}</div>
+    </div>
+  );
+}
+
+export { Foldable, type FoldableProps };
diff --git a/web/lib/opal/src/core/interactive/foldable/styles.css b/web/lib/opal/src/core/interactive/foldable/styles.css
new file mode 100644
index 00000000000..95fd6ed2530
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/foldable/styles.css
@@ -0,0 +1,54 @@
+/* ---------------------------------------------------------------------------
+   Foldable — CSS grid collapse/expand animation.
+
+   Expands when an ancestor `.interactive` element is hovered or has
+   `data-interaction="hover"` / `data-interaction="active"`.
+
+   Structure:
+     .interactive-foldable-host   — flex parent, gap transitions 0 → 0.25rem
+       [always-visible content]
+       .interactive-foldable      — grid container, column 0fr ↔ 1fr
+         .interactive-foldable-inner — single grid item, flex + overflow clip
+           [foldable content]
+   --------------------------------------------------------------------------- */
+
+/* Host: the flex parent that includes both persistent + foldable content */
+.interactive-foldable-host {
+  gap: 0;
+  transition: gap 200ms ease-in-out;
+}
+
+.interactive:hover:not([data-disabled]) .interactive-foldable-host,
+.interactive[data-interaction="hover"]:not([data-disabled])
+  .interactive-foldable-host,
+.interactive[data-interaction="active"]:not([data-disabled])
+  .interactive-foldable-host {
+  gap: 0.25rem;
+}
+
+/* Grid container — collapse animation */
+.interactive-foldable {
+  display: grid;
+  grid-template-columns: 0fr;
+  opacity: 0;
+  transition:
+    grid-template-columns 200ms ease-in-out,
+    opacity 200ms ease-in-out;
+}
+
+/* Single grid item — content layout + overflow clipping */
+.interactive-foldable-inner {
+  @apply flex items-center gap-1;
+  overflow: hidden;
+  min-width: 0;
+}
+
+/* Expanded: hovered or interaction override */
+.interactive:hover:not([data-disabled]) .interactive-foldable,
+.interactive[data-interaction="hover"]:not([data-disabled])
+  .interactive-foldable,
+.interactive[data-interaction="active"]:not([data-disabled])
+  .interactive-foldable {
+  grid-template-columns: 1fr;
+  opacity: 1;
+}
diff --git a/web/lib/opal/src/core/interactive/shared.css b/web/lib/opal/src/core/interactive/shared.css
new file mode 100644
index 00000000000..8f9dda51683
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/shared.css
@@ -0,0 +1,48 @@
+/* Interactive — shared base classes for stateless + stateful primitives */
+
+/* Register --interactive-foreground as a <color> so the browser can
+   interpolate it directly on the parent. Children just read the variable
+   with no independent transitions — guaranteeing perfect sync. */
+@property --interactive-foreground {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: transparent;
+}
+
+@property --interactive-foreground-icon {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: transparent;
+}
+
+/* Base interactive surface */
+.interactive {
+  @apply cursor-pointer select-none;
+  transition:
+    background-color 150ms ease-in-out,
+    --interactive-foreground 150ms ease-in-out,
+    --interactive-foreground-icon 150ms ease-in-out;
+}
+.interactive[data-disabled] {
+  @apply cursor-not-allowed;
+}
+
+/* Container — structural box */
+.interactive-container {
+  @apply flex items-center justify-center overflow-clip;
+}
+.interactive-container[data-border="true"] {
+  @apply border;
+}
+
+/* Utility classes — descendants opt in to parent-controlled foreground color.
+   No transition here — the parent interpolates the variables directly. */
+.interactive-foreground {
+  color: var(--interactive-foreground);
+}
+
+/* Icon foreground — reads from --interactive-foreground-icon, which defaults
+   to --interactive-foreground via the variant CSS rules. */
+.interactive-foreground-icon {
+  color: var(--interactive-foreground-icon);
+}
diff --git a/web/lib/opal/src/core/interactive/stateful/README.md b/web/lib/opal/src/core/interactive/stateful/README.md
new file mode 100644
index 00000000000..ffe06515456
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/stateful/README.md
@@ -0,0 +1,35 @@
+# Interactive.Stateful
+
+**Import:** `import { Interactive } from "@opal/core";` — use as `Interactive.Stateful`.
+
+Stateful interactive surface primitive for elements that maintain a value state (empty/filled/selected). Used for toggles, sidebar items, and selectable list rows. Applies variant/state color styling via CSS data-attributes and merges onto a single child element via Radix `Slot`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"select-light" \| "select-heavy" \| "sidebar"` | `"select-heavy"` | Color variant |
+| `state` | `"empty" \| "filled" \| "selected"` | `"empty"` | Current value state |
+| `interaction` | `"rest" \| "hover" \| "active"` | `"rest"` | JS-controlled interaction override |
+| `group` | `string` | — | Tailwind group class for `group-hover:*` |
+| `disabled` | `boolean` | `false` | Disables the element |
+| `href` | `string` | — | URL for link behavior |
+| `target` | `string` | — | Link target (e.g. `"_blank"`) |
+
+## State attribute
+
+Uses `data-interactive-state` (not `data-state`) to avoid conflicts with Radix UI, which injects its own `data-state` on trigger elements.
+
+## CSS custom properties
+
+Sets `--interactive-foreground` and `--interactive-foreground-icon` per variant/state. In the `empty` state, icon color (`--text-03`) is intentionally lighter than text color (`--text-04`).
+
+## Usage
+
+```tsx
+<Interactive.Stateful variant="select-heavy" state="selected" onClick={toggle}>
+  <Interactive.Container>
+    <span className="interactive-foreground">Selected item</span>
+  </Interactive.Container>
+</Interactive.Stateful>
+```
diff --git a/web/lib/opal/src/core/interactive/stateful/components.tsx b/web/lib/opal/src/core/interactive/stateful/components.tsx
new file mode 100644
index 00000000000..395ff904738
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/stateful/components.tsx
@@ -0,0 +1,150 @@
+import "@opal/core/interactive/shared.css";
+import "@opal/core/interactive/stateful/styles.css";
+import React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "@opal/utils";
+import type { WithoutStyles } from "@opal/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type InteractiveStatefulVariant = "select-light" | "select-heavy" | "sidebar";
+type InteractiveStatefulState = "empty" | "filled" | "selected";
+type InteractiveStatefulInteraction = "rest" | "hover" | "active";
+
+/**
+ * Props for {@link InteractiveStateful}.
+ */
+interface InteractiveStatefulProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLElement>> {
+  ref?: React.Ref<HTMLElement>;
+
+  /**
+   * Visual variant controlling the color palette and behavior.
+   *
+   * - `"select-light"` — transparent selected background (for inline toggles)
+   * - `"select-heavy"` — tinted selected background (for list rows, model pickers)
+   * - `"sidebar"` — for sidebar navigation items
+   *
+   * @default "select-heavy"
+   */
+  variant?: InteractiveStatefulVariant;
+
+  /**
+   * The current value state of this element.
+   *
+   * - `"empty"` — no value / unset
+   * - `"filled"` — has a value but not actively selected
+   * - `"selected"` — actively chosen / focused
+   *
+   * @default "empty"
+   */
+  state?: InteractiveStatefulState;
+
+  /**
+   * JS-controllable interaction state override.
+   *
+   * - `"rest"` — default appearance (no override)
+   * - `"hover"` — forces hover visual state
+   * - `"active"` — forces active/pressed visual state
+   *
+   * @default "rest"
+   */
+  interaction?: InteractiveStatefulInteraction;
+
+  /**
+   * Tailwind group class (e.g. `"group/Card"`) for `group-hover:*` utilities.
+   */
+  group?: string;
+
+  /**
+   * When `true`, disables the interactive element.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * URL to navigate to when clicked. Passed through Slot to the child.
+   */
+  href?: string;
+
+  /**
+   * Link target (e.g. `"_blank"`). Only used when `href` is provided.
+   */
+  target?: string;
+}
+
+// ---------------------------------------------------------------------------
+// InteractiveStateful
+// ---------------------------------------------------------------------------
+
+/**
+ * Stateful interactive surface primitive.
+ *
+ * The foundational building block for elements that maintain a value state
+ * (empty/filled/selected). Applies variant/state color styling via CSS
+ * data-attributes and merges onto a single child element via Radix `Slot`.
+ */
+function InteractiveStateful({
+  ref,
+  variant = "select-heavy",
+  state = "empty",
+  interaction = "rest",
+  group,
+  disabled,
+  href,
+  target,
+  ...props
+}: InteractiveStatefulProps) {
+  // onClick/href are always passed directly — Stateful is the outermost Slot,
+  // so Radix Slot-injected handlers don't bypass this guard.
+  const classes = cn(
+    "interactive",
+    !props.onClick && !href && "!cursor-default !select-auto",
+    group
+  );
+
+  const dataAttrs = {
+    "data-interactive-variant": variant,
+    "data-interactive-state": state,
+    "data-interaction": interaction !== "rest" ? interaction : undefined,
+    "data-disabled": disabled ? "true" : undefined,
+    "aria-disabled": disabled || undefined,
+  };
+
+  const { onClick, ...slotProps } = props;
+
+  const linkAttrs = href
+    ? {
+        href: disabled ? undefined : href,
+        target,
+        rel: target === "_blank" ? "noopener noreferrer" : undefined,
+      }
+    : {};
+
+  return (
+    <Slot
+      ref={ref}
+      className={classes}
+      {...dataAttrs}
+      {...linkAttrs}
+      {...slotProps}
+      onClick={
+        disabled && href
+          ? (e: React.MouseEvent) => e.preventDefault()
+          : disabled
+            ? undefined
+            : onClick
+      }
+    />
+  );
+}
+
+export {
+  InteractiveStateful,
+  type InteractiveStatefulProps,
+  type InteractiveStatefulVariant,
+  type InteractiveStatefulState,
+  type InteractiveStatefulInteraction,
+};
diff --git a/web/lib/opal/src/core/interactive/stateful/styles.css b/web/lib/opal/src/core/interactive/stateful/styles.css
new file mode 100644
index 00000000000..1dbe23778cd
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/stateful/styles.css
@@ -0,0 +1,265 @@
+/* ============================================================================
+   Stateful — variant x state color matrix
+
+   Each combination sets:
+     - background-color (via @apply)
+     - --interactive-foreground (CSS custom property for descendant text color)
+     - --interactive-foreground-icon (CSS custom property for descendant icon color)
+
+   Both foreground variables are registered as <color> via @property in
+   shared.css, so the browser interpolates them on the parent element.
+   Children read the variables with no independent transitions.
+
+   State dimension: `data-interactive-state` = "empty" | "filled" | "selected"
+   Variant dimension: `data-interactive-variant` = "select-light" | "select-heavy" | "sidebar"
+
+   Interaction override: `data-interaction="hover"` and `data-interaction="active"`
+   allow JS-controlled visual state overrides.
+============================================================================ */
+
+/* ===========================================================================
+   Select-Heavy
+   =========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Select-Heavy — Empty
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="empty"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-03);
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="empty"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="empty"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="empty"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="empty"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-neutral-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="empty"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Select-Heavy — Filled
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-neutral-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Select-Heavy — Selected
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="selected"] {
+  @apply bg-[var(--action-link-01)];
+  --interactive-foreground: var(--action-link-05);
+  --interactive-foreground-icon: var(--action-link-05);
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="selected"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="selected"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="selected"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="selected"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="select-heavy"][data-interactive-state="selected"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-link-03);
+  --interactive-foreground-icon: var(--action-link-03);
+}
+
+/* ===========================================================================
+   Select-Light — identical to Select-Heavy except selected bg is transparent
+   =========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Select-Light — Empty
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-light"][data-interactive-state="empty"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-03);
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="empty"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-light"][data-interactive-state="empty"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="empty"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-light"][data-interactive-state="empty"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-neutral-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="empty"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Select-Light — Filled
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-light"][data-interactive-state="filled"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="filled"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-light"][data-interactive-state="filled"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="filled"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-light"][data-interactive-state="filled"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-neutral-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="filled"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Select-Light — Selected (transparent background, unlike select-heavy)
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-light"][data-interactive-state="selected"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-link-05);
+  --interactive-foreground-icon: var(--action-link-05);
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="selected"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-light"][data-interactive-state="selected"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="selected"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-light"][data-interactive-state="selected"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="select-light"][data-interactive-state="selected"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-link-03);
+  --interactive-foreground-icon: var(--action-link-03);
+}
+
+/* ===========================================================================
+   Sidebar
+   =========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Sidebar — Empty
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="empty"] {
+  @apply bg-transparent;
+}
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="empty"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="empty"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-03;
+}
+
+/* ---------------------------------------------------------------------------
+   Sidebar — Filled
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="filled"] {
+  @apply bg-transparent;
+}
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="filled"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="filled"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-03;
+}
+
+/* ---------------------------------------------------------------------------
+   Sidebar — Selected
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="selected"] {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="selected"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="sidebar"][data-interactive-state="selected"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-03;
+}
diff --git a/web/lib/opal/src/core/interactive/stateless/README.md b/web/lib/opal/src/core/interactive/stateless/README.md
new file mode 100644
index 00000000000..7e314d26c35
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/stateless/README.md
@@ -0,0 +1,33 @@
+# Interactive.Stateless
+
+**Import:** `import { Interactive } from "@opal/core";` — use as `Interactive.Stateless`.
+
+Stateless interactive surface primitive for buttons, links, and cards. Applies variant/prominence color styling via CSS data-attributes and merges onto a single child element via Radix `Slot`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"none" \| "default" \| "action" \| "danger"` | `"default"` | Color variant |
+| `prominence` | `"primary" \| "secondary" \| "tertiary" \| "internal"` | `"primary"` | Color prominence within the variant |
+| `interaction` | `"rest" \| "hover" \| "active"` | `"rest"` | JS-controlled interaction override |
+| `group` | `string` | — | Tailwind group class for `group-hover:*` |
+| `disabled` | `boolean` | `false` | Disables the element |
+| `href` | `string` | — | URL for link behavior |
+| `target` | `string` | — | Link target (e.g. `"_blank"`) |
+
+## CSS custom properties
+
+Sets `--interactive-foreground` and `--interactive-foreground-icon` per variant/prominence/state. Descendants opt in via:
+- `.interactive-foreground` — text color
+- `.interactive-foreground-icon` — icon color
+
+## Usage
+
+```tsx
+<Interactive.Stateless variant="default" prominence="primary" onClick={handleClick}>
+  <Interactive.Container border>
+    <span className="interactive-foreground">Click me</span>
+  </Interactive.Container>
+</Interactive.Stateless>
+```
diff --git a/web/lib/opal/src/core/interactive/stateless/components.tsx b/web/lib/opal/src/core/interactive/stateless/components.tsx
new file mode 100644
index 00000000000..0fb8d0c96d9
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/stateless/components.tsx
@@ -0,0 +1,145 @@
+import "@opal/core/interactive/shared.css";
+import "@opal/core/interactive/stateless/styles.css";
+import React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "@opal/utils";
+import type { WithoutStyles } from "@opal/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type InteractiveStatelessVariant = "none" | "default" | "action" | "danger";
+type InteractiveStatelessProminence =
+  | "primary"
+  | "secondary"
+  | "tertiary"
+  | "internal";
+type InteractiveStatelessInteraction = "rest" | "hover" | "active";
+
+/**
+ * Props for {@link InteractiveStateless}.
+ */
+interface InteractiveStatelessProps
+  extends WithoutStyles<React.HTMLAttributes<HTMLElement>> {
+  ref?: React.Ref<HTMLElement>;
+
+  /**
+   * Visual variant controlling the color palette.
+   * @default "default"
+   */
+  variant?: InteractiveStatelessVariant;
+
+  /**
+   * Prominence level controlling background intensity.
+   * @default "primary"
+   */
+  prominence?: InteractiveStatelessProminence;
+
+  /**
+   * JS-controllable interaction state override.
+   *
+   * - `"rest"` — default appearance (no override)
+   * - `"hover"` — forces hover visual state
+   * - `"active"` — forces active/pressed visual state
+   *
+   * @default "rest"
+   */
+  interaction?: InteractiveStatelessInteraction;
+
+  /**
+   * Tailwind group class (e.g. `"group/Card"`) for `group-hover:*` utilities.
+   */
+  group?: string;
+
+  /**
+   * When `true`, disables the interactive element.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * URL to navigate to when clicked. Passed through Slot to the child.
+   */
+  href?: string;
+
+  /**
+   * Link target (e.g. `"_blank"`). Only used when `href` is provided.
+   */
+  target?: string;
+}
+
+// ---------------------------------------------------------------------------
+// InteractiveStateless
+// ---------------------------------------------------------------------------
+
+/**
+ * Stateless interactive surface primitive.
+ *
+ * The foundational building block for buttons, links, and any clickable
+ * element that does not maintain selection state. Applies variant/prominence
+ * color styling via CSS data-attributes and merges onto a single child
+ * element via Radix `Slot`.
+ */
+function InteractiveStateless({
+  ref,
+  variant = "default",
+  prominence = "primary",
+  interaction = "rest",
+  group,
+  disabled,
+  href,
+  target,
+  ...props
+}: InteractiveStatelessProps) {
+  // onClick/href are always passed directly — Stateless is the outermost Slot,
+  // so Radix Slot-injected handlers don't bypass this guard.
+  const classes = cn(
+    "interactive",
+    !props.onClick && !href && "!cursor-default !select-auto",
+    group
+  );
+
+  const dataAttrs = {
+    "data-interactive-variant": variant !== "none" ? variant : undefined,
+    "data-interactive-prominence": variant !== "none" ? prominence : undefined,
+    "data-interaction": interaction !== "rest" ? interaction : undefined,
+    "data-disabled": disabled ? "true" : undefined,
+    "aria-disabled": disabled || undefined,
+  };
+
+  const { onClick, ...slotProps } = props;
+
+  const linkAttrs = href
+    ? {
+        href: disabled ? undefined : href,
+        target,
+        rel: target === "_blank" ? "noopener noreferrer" : undefined,
+      }
+    : {};
+
+  return (
+    <Slot
+      ref={ref}
+      className={classes}
+      {...dataAttrs}
+      {...linkAttrs}
+      {...slotProps}
+      onClick={
+        disabled && href
+          ? (e: React.MouseEvent) => e.preventDefault()
+          : disabled
+            ? undefined
+            : onClick
+      }
+    />
+  );
+}
+
+export {
+  InteractiveStateless,
+  type InteractiveStatelessProps,
+  type InteractiveStatelessVariant,
+  type InteractiveStatelessProminence,
+  type InteractiveStatelessInteraction,
+};
diff --git a/web/lib/opal/src/core/interactive/stateless/styles.css b/web/lib/opal/src/core/interactive/stateless/styles.css
new file mode 100644
index 00000000000..09b630bca2f
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/stateless/styles.css
@@ -0,0 +1,387 @@
+/* ============================================================================
+   Stateless — variant x prominence color matrix
+
+   Each combination sets:
+     - background-color (via @apply)
+     - --interactive-foreground (CSS custom property for descendant text color)
+     - --interactive-foreground-icon (CSS custom property for descendant icon color)
+
+   Both foreground variables are registered as <color> via @property in
+   shared.css, so the browser interpolates them on the parent element.
+   Children read the variables with no independent transitions.
+
+   Interaction override: `data-interaction="hover"` and `data-interaction="active"`
+   allow JS-controlled visual state overrides without actual pointer events.
+============================================================================ */
+
+/* ---------------------------------------------------------------------------
+   Default + Primary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="default"][data-interactive-prominence="primary"] {
+  @apply bg-[var(--theme-primary-05)];
+  --interactive-foreground: var(--text-inverted-05);
+  --interactive-foreground-icon: var(--text-inverted-05);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="primary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="primary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-[var(--theme-primary-04)];
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="primary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="primary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-[var(--theme-primary-06)];
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="primary"][data-disabled] {
+  @apply bg-background-neutral-04;
+  --interactive-foreground: var(--text-inverted-04);
+  --interactive-foreground-icon: var(--text-inverted-04);
+}
+
+/* ---------------------------------------------------------------------------
+   Default + Secondary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="default"][data-interactive-prominence="secondary"] {
+  @apply bg-background-tint-01;
+  --interactive-foreground: var(--text-03);
+  --interactive-foreground-icon: var(--text-03);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="secondary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="secondary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="secondary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="secondary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="secondary"][data-disabled] {
+  @apply bg-background-neutral-03;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Default + Tertiary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-03);
+  --interactive-foreground-icon: var(--text-03);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"][data-disabled] {
+  @apply bg-transparent opacity-50;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Default + Internal
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="default"][data-interactive-prominence="internal"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-03);
+  --interactive-foreground-icon: var(--text-03);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="internal"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="internal"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="internal"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="default"][data-interactive-prominence="internal"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="default"][data-interactive-prominence="internal"][data-disabled] {
+  @apply bg-transparent opacity-50;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Action + Primary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="action"][data-interactive-prominence="primary"] {
+  @apply bg-[var(--action-link-05)];
+  --interactive-foreground: var(--text-light-05);
+  --interactive-foreground-icon: var(--text-light-05);
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="primary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="primary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-[var(--action-link-04)];
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="primary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="primary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-[var(--action-link-06)];
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="primary"][data-disabled] {
+  @apply bg-[var(--action-link-02)];
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Action + Secondary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="action"][data-interactive-prominence="secondary"] {
+  @apply bg-background-tint-01;
+  --interactive-foreground: var(--action-text-link-05);
+  --interactive-foreground-icon: var(--action-text-link-05);
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="secondary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="secondary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="secondary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="secondary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="secondary"][data-disabled] {
+  @apply bg-background-neutral-02;
+  --interactive-foreground: var(--action-link-03);
+  --interactive-foreground-icon: var(--action-link-03);
+}
+
+/* ---------------------------------------------------------------------------
+   Action + Tertiary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-text-link-05);
+  --interactive-foreground-icon: var(--action-text-link-05);
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"][data-disabled] {
+  @apply bg-transparent opacity-50;
+  --interactive-foreground: var(--action-link-03);
+  --interactive-foreground-icon: var(--action-link-03);
+}
+
+/* ---------------------------------------------------------------------------
+   Action + Internal
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="action"][data-interactive-prominence="internal"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-text-link-05);
+  --interactive-foreground-icon: var(--action-text-link-05);
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="internal"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="internal"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="internal"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="action"][data-interactive-prominence="internal"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="action"][data-interactive-prominence="internal"][data-disabled] {
+  @apply bg-transparent opacity-50;
+  --interactive-foreground: var(--action-link-03);
+  --interactive-foreground-icon: var(--action-link-03);
+}
+
+/* ---------------------------------------------------------------------------
+   Danger + Primary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="primary"] {
+  @apply bg-[var(--action-danger-05)];
+  --interactive-foreground: var(--text-light-05);
+  --interactive-foreground-icon: var(--text-light-05);
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="primary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="primary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-[var(--action-danger-04)];
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="primary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="primary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-[var(--action-danger-06)];
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="primary"][data-disabled] {
+  @apply bg-[var(--action-danger-02)];
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Danger + Secondary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="secondary"] {
+  @apply bg-background-tint-01;
+  --interactive-foreground: var(--action-text-danger-05);
+  --interactive-foreground-icon: var(--action-text-danger-05);
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="secondary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="secondary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="secondary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="secondary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="secondary"][data-disabled] {
+  @apply bg-background-neutral-02;
+  --interactive-foreground: var(--action-danger-03);
+  --interactive-foreground-icon: var(--action-danger-03);
+}
+
+/* ---------------------------------------------------------------------------
+   Danger + Tertiary
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-text-danger-05);
+  --interactive-foreground-icon: var(--action-text-danger-05);
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"][data-disabled] {
+  @apply bg-transparent opacity-50;
+  --interactive-foreground: var(--action-danger-03);
+  --interactive-foreground-icon: var(--action-danger-03);
+}
+
+/* ---------------------------------------------------------------------------
+   Danger + Internal
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-text-danger-05);
+  --interactive-foreground-icon: var(--action-text-danger-05);
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"][data-disabled] {
+  @apply bg-transparent opacity-50;
+  --interactive-foreground: var(--action-danger-03);
+  --interactive-foreground-icon: var(--action-danger-03);
+}
diff --git a/web/lib/opal/src/core/interactive/styles.css b/web/lib/opal/src/core/interactive/styles.css
deleted file mode 100644
index a10f279b275..00000000000
--- a/web/lib/opal/src/core/interactive/styles.css
+++ /dev/null
@@ -1,441 +0,0 @@
-/* Interactive — base (structural only, no color changes) */
-.interactive {
-  @apply cursor-pointer select-none transition-all;
-}
-.interactive[data-disabled] {
-  @apply cursor-not-allowed;
-}
-
-/* Interactive — container */
-.interactive-container {
-  @apply flex items-center justify-center overflow-clip;
-}
-.interactive-container[data-border="true"] {
-  @apply border;
-}
-
-/* Utility class — descendants opt in to parent-controlled foreground color */
-.interactive-foreground {
-  @apply transition-all duration-150 ease-in-out;
-  color: var(--interactive-foreground);
-}
-
-/* Icon foreground — falls back to --interactive-foreground when the icon
-   variable is unset (or reset to `initial`).  Variants that need a distinct
-   icon color at rest (e.g. select) set --interactive-foreground-icon; all
-   other states leave it unset so icons track the text color automatically. */
-.interactive-foreground-icon {
-  @apply transition-all duration-150 ease-in-out;
-  color: var(--interactive-foreground-icon, var(--interactive-foreground));
-}
-
-/* ============================================================================
-   Variant + Prominence combinations (12 + select)
-
-   Each combination sets:
-     - background-color (via @apply)
-     - --interactive-foreground (CSS custom property for descendant text color)
-
-   Descendants opt in to text color via: color: var(--interactive-foreground);
-
-============================================================================ */
-
-/* ---------------------------------------------------------------------------
-   Default + Primary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="primary"] {
-  @apply bg-[var(--theme-primary-05)];
-  --interactive-foreground: var(--text-inverted-05);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="primary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="primary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--theme-primary-04)];
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="primary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--theme-primary-06)];
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="primary"][data-disabled] {
-  @apply bg-background-neutral-04;
-  --interactive-foreground: var(--text-inverted-04);
-}
-
-/* ---------------------------------------------------------------------------
-   Default + Secondary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="secondary"] {
-  @apply bg-background-tint-01;
-  --interactive-foreground: var(--text-03);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="secondary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="secondary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-  --interactive-foreground: var(--text-04);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="secondary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-  --interactive-foreground: var(--text-05);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="secondary"][data-disabled] {
-  @apply bg-background-neutral-03;
-  --interactive-foreground: var(--text-01);
-}
-
-/* ---------------------------------------------------------------------------
-   Default + Tertiary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="tertiary"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--text-03);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="tertiary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="tertiary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-  --interactive-foreground: var(--text-04);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="tertiary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-  --interactive-foreground: var(--text-05);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="tertiary"][data-disabled] {
-  @apply bg-transparent opacity-50;
-  --interactive-foreground: var(--text-01);
-}
-
-/* ---------------------------------------------------------------------------
-   Default + Internal
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="internal"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--text-03);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="internal"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="internal"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-  --interactive-foreground: var(--text-04);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="internal"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-  --interactive-foreground: var(--text-05);
-}
-.interactive[data-interactive-base-variant="default"][data-interactive-base-prominence="internal"][data-disabled] {
-  @apply bg-transparent opacity-50;
-  --interactive-foreground: var(--text-01);
-}
-
-/* ---------------------------------------------------------------------------
-   Action + Primary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="primary"] {
-  @apply bg-[var(--action-link-05)];
-  --interactive-foreground: var(--text-light-05);
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="primary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="primary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--action-link-04)];
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="primary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--action-link-06)];
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="primary"][data-disabled] {
-  @apply bg-[var(--action-link-02)];
-  --interactive-foreground: var(--text-01);
-}
-
-/* ---------------------------------------------------------------------------
-   Action + Secondary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="secondary"] {
-  @apply bg-background-tint-01;
-  --interactive-foreground: var(--action-text-link-05);
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="secondary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="secondary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="secondary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="secondary"][data-disabled] {
-  @apply bg-background-neutral-02;
-  --interactive-foreground: var(--action-link-03);
-}
-
-/* ---------------------------------------------------------------------------
-   Action + Tertiary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="tertiary"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--action-text-link-05);
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="tertiary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="tertiary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="tertiary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="tertiary"][data-disabled] {
-  @apply bg-transparent opacity-50;
-  --interactive-foreground: var(--action-link-03);
-}
-
-/* ---------------------------------------------------------------------------
-   Action + Internal
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="internal"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--action-text-link-05);
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="internal"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="internal"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="internal"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="action"][data-interactive-base-prominence="internal"][data-disabled] {
-  @apply bg-transparent opacity-50;
-  --interactive-foreground: var(--action-link-03);
-}
-
-/* ---------------------------------------------------------------------------
-   Danger + Primary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="primary"] {
-  @apply bg-[var(--action-danger-05)];
-  --interactive-foreground: var(--text-light-05);
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="primary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="primary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--action-danger-04)];
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="primary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--action-danger-06)];
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="primary"][data-disabled] {
-  @apply bg-[var(--action-danger-02)];
-  --interactive-foreground: var(--text-01);
-}
-
-/* ---------------------------------------------------------------------------
-   Danger + Secondary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="secondary"] {
-  @apply bg-background-tint-01;
-  --interactive-foreground: var(--action-text-danger-05);
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="secondary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="secondary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="secondary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="secondary"][data-disabled] {
-  @apply bg-background-neutral-02;
-  --interactive-foreground: var(--action-danger-03);
-}
-
-/* ---------------------------------------------------------------------------
-   Danger + Tertiary
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="tertiary"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--action-text-danger-05);
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="tertiary"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="tertiary"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="tertiary"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="tertiary"][data-disabled] {
-  @apply bg-transparent opacity-50;
-  --interactive-foreground: var(--action-danger-03);
-}
-
-/* ---------------------------------------------------------------------------
-   Danger + Internal
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="internal"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--action-text-danger-05);
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="internal"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="internal"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="internal"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-.interactive[data-interactive-base-variant="danger"][data-interactive-base-prominence="internal"][data-disabled] {
-  @apply bg-transparent opacity-50;
-  --interactive-foreground: var(--action-danger-03);
-}
-
-/* ---------------------------------------------------------------------------
-   Select (optional "heavy" prominence)
-
-   Foreground is a 2D state machine: interaction × selected.
-   When not selected, text darkens on :active. When selected, foreground
-   switches to the action-link colour family and stays constant.
-
-   `data-transient` forces the hover background (same as all other variants).
-   `data-selected` switches the foreground to action-link colours.
-
-   The "heavy" prominence overrides the selected background to action-link-01
-   (instead of transparent). All other states are identical.
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="select"] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--text-04);
-}
-/* Icon color at rest (not hovered/transient/active/selected/disabled).
-   Uses a single negated selector so no other state rules need updating. */
-.interactive[data-interactive-base-variant="select"]:not(:hover):not(
-    [data-transient="true"]
-  ):not(:active):not([data-selected="true"]):not([data-disabled]) {
-  --interactive-foreground-icon: var(--text-03);
-}
-.interactive[data-interactive-base-variant="select"]:hover:not([data-disabled]),
-.interactive[data-interactive-base-variant="select"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-}
-.interactive[data-interactive-base-variant="select"][data-selected="true"]:not(
-    [data-disabled]
-  ) {
-  --interactive-foreground: var(--action-link-05);
-}
-.interactive[data-interactive-base-variant="select"]:active:not(
-    [data-disabled]
-  ):not([data-selected="true"]) {
-  @apply bg-background-neutral-00;
-  --interactive-foreground: var(--text-05);
-}
-.interactive[data-interactive-base-variant="select"][data-selected="true"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-neutral-00;
-}
-.interactive[data-interactive-base-variant="select"][data-disabled] {
-  @apply bg-transparent;
-  --interactive-foreground: var(--text-01);
-}
-.interactive[data-interactive-base-variant="select"][data-selected="true"][data-disabled] {
-  --interactive-foreground: var(--action-link-03);
-}
-
-/* Heavy — selected background overrides */
-.interactive[data-interactive-base-variant="select"][data-interactive-base-prominence="heavy"][data-selected="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-[var(--action-link-01)];
-}
-.interactive[data-interactive-base-variant="select"][data-interactive-base-prominence="heavy"][data-selected="true"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="select"][data-interactive-base-prominence="heavy"][data-selected="true"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-02;
-}
-.interactive[data-interactive-base-variant="select"][data-interactive-base-prominence="heavy"][data-selected="true"]:active:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
-
-/* ---------------------------------------------------------------------------
-   Sidebar + Light
-   --------------------------------------------------------------------------- */
-.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"] {
-  @apply bg-transparent;
-}
-.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"]:hover:not(
-    [data-disabled]
-  ),
-.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"][data-transient="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-03;
-}
-.interactive[data-interactive-base-variant="sidebar"][data-interactive-base-prominence="light"][data-selected="true"]:not(
-    [data-disabled]
-  ) {
-  @apply bg-background-tint-00;
-}
diff --git a/web/lib/opal/src/layouts/README.md b/web/lib/opal/src/layouts/README.md
index 31b3461db0e..ec3791b3778 100644
--- a/web/lib/opal/src/layouts/README.md
+++ b/web/lib/opal/src/layouts/README.md
@@ -8,9 +8,9 @@ Layout primitives for composing content blocks. These components handle sizing,
 
 | Component | Description | Docs |
 |---|---|---|
-| [`Content`](./Content/README.md) | Icon + title + description row. Routes to an internal layout (`ContentXl`, `ContentLg`, `ContentMd`, or `ContentSm`) based on `sizePreset` and `variant`. | [Content README](./Content/README.md) |
-| [`ContentAction`](./ContentAction/README.md) | Wraps `Content` in a flex-row with an optional `rightChildren` slot for action buttons. Adds padding alignment via the shared `SizeVariant` scale. | [ContentAction README](./ContentAction/README.md) |
-| [`IllustrationContent`](./IllustrationContent/README.md) | Center-aligned illustration + title + description stack for empty states, error pages, and placeholders. | [IllustrationContent README](./IllustrationContent/README.md) |
+| [`Content`](./content/README.md) | Icon + title + description row. Routes to an internal layout (`ContentXl`, `ContentLg`, `ContentMd`, or `ContentSm`) based on `sizePreset` and `variant`. | [Content README](./content/README.md) |
+| [`ContentAction`](./content-action/README.md) | Wraps `Content` in a flex-row with an optional `rightChildren` slot for action buttons. Adds padding alignment via the shared `SizeVariant` scale. | [ContentAction README](./content-action/README.md) |
+| [`IllustrationContent`](./illustration-content/README.md) | Center-aligned illustration + title + description stack for empty states, error pages, and placeholders. | [IllustrationContent README](./illustration-content/README.md) |
 
 ## Quick Start
 
@@ -69,7 +69,7 @@ import SvgNoResult from "@opal/illustrations/no-result";
 - **`sizePreset`** — controls sizing tokens (icon size, padding, gap, font, line-height).
 - **`variant`** — controls structural layout (icon placement, description rendering).
 
-Valid preset/variant combinations are enforced at the type level via a discriminated union. See the [Content README](./Content/README.md) for the full matrix.
+Valid preset/variant combinations are enforced at the type level via a discriminated union. See the [Content README](./content/README.md) for the full matrix.
 
 ### Shared size scale (`ContentAction`)
 
@@ -99,7 +99,7 @@ These are not exported — `Content` routes to them automatically:
 
 | Layout | Used when | File |
 |---|---|---|
-| `ContentXl` | `sizePreset` is `headline` or `section` with `variant="heading"` | `Content/ContentXl.tsx` |
-| `ContentLg` | `sizePreset` is `headline` or `section` with `variant="section"` | `Content/ContentLg.tsx` |
-| `ContentMd` | `sizePreset` is `main-content`, `main-ui`, or `secondary` with `variant="section"` | `Content/ContentMd.tsx` |
-| `ContentSm` | `variant="body"` | `Content/ContentSm.tsx` |
+| `ContentXl` | `sizePreset` is `headline` or `section` with `variant="heading"` | `content/ContentXl.tsx` |
+| `ContentLg` | `sizePreset` is `headline` or `section` with `variant="section"` | `content/ContentLg.tsx` |
+| `ContentMd` | `sizePreset` is `main-content`, `main-ui`, or `secondary` with `variant="section"` | `content/ContentMd.tsx` |
+| `ContentSm` | `variant="body"` | `content/ContentSm.tsx` |
diff --git a/web/lib/opal/src/layouts/ContentAction/README.md b/web/lib/opal/src/layouts/content-action/README.md
similarity index 95%
rename from web/lib/opal/src/layouts/ContentAction/README.md
rename to web/lib/opal/src/layouts/content-action/README.md
index 71cdf0ae226..7e9c272a1f7 100644
--- a/web/lib/opal/src/layouts/ContentAction/README.md
+++ b/web/lib/opal/src/layouts/content-action/README.md
@@ -2,7 +2,7 @@
 
 **Import:** `import { ContentAction, type ContentActionProps } from "@opal/layouts";`
 
-A row layout that pairs a [`Content`](../Content/README.md) block with optional right-side action children (buttons, badges, icons, etc.).
+A row layout that pairs a [`Content`](../content/README.md) block with optional right-side action children (buttons, badges, icons, etc.).
 
 ## Why ContentAction?
 
@@ -10,7 +10,7 @@ A row layout that pairs a [`Content`](../Content/README.md) block with optional
 
 ## Props
 
-Inherits **all** props from [`Content`](../Content/README.md) (same discriminated-union API) plus:
+Inherits **all** props from [`Content`](../content/README.md) (same discriminated-union API) plus:
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
diff --git a/web/lib/opal/src/layouts/ContentAction/components.tsx b/web/lib/opal/src/layouts/content-action/components.tsx
similarity index 97%
rename from web/lib/opal/src/layouts/ContentAction/components.tsx
rename to web/lib/opal/src/layouts/content-action/components.tsx
index 193f609bf99..93f6feb8198 100644
--- a/web/lib/opal/src/layouts/ContentAction/components.tsx
+++ b/web/lib/opal/src/layouts/content-action/components.tsx
@@ -1,4 +1,4 @@
-import { Content, type ContentProps } from "@opal/layouts/Content/components";
+import { Content, type ContentProps } from "@opal/layouts/content/components";
 import { sizeVariants, type SizeVariant } from "@opal/shared";
 import { cn } from "@opal/utils";
 
diff --git a/web/lib/opal/src/layouts/Content/BodyLayout.tsx b/web/lib/opal/src/layouts/content/BodyLayout.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/Content/BodyLayout.tsx
rename to web/lib/opal/src/layouts/content/BodyLayout.tsx
diff --git a/web/lib/opal/src/layouts/Content/ContentLg.tsx b/web/lib/opal/src/layouts/content/ContentLg.tsx
similarity index 98%
rename from web/lib/opal/src/layouts/Content/ContentLg.tsx
rename to web/lib/opal/src/layouts/content/ContentLg.tsx
index 8d26674e2b8..530afe5d4ad 100644
--- a/web/lib/opal/src/layouts/Content/ContentLg.tsx
+++ b/web/lib/opal/src/layouts/content/ContentLg.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Button } from "@opal/components/buttons/Button/components";
+import { Button } from "@opal/components/buttons/button/components";
 import type { SizeVariant } from "@opal/shared";
 import SvgEdit from "@opal/icons/edit";
 import type { IconFunctionComponent } from "@opal/types";
diff --git a/web/lib/opal/src/layouts/Content/ContentMd.tsx b/web/lib/opal/src/layouts/content/ContentMd.tsx
similarity index 98%
rename from web/lib/opal/src/layouts/Content/ContentMd.tsx
rename to web/lib/opal/src/layouts/content/ContentMd.tsx
index 44b55b3e44a..fc3b08418d0 100644
--- a/web/lib/opal/src/layouts/Content/ContentMd.tsx
+++ b/web/lib/opal/src/layouts/content/ContentMd.tsx
@@ -1,7 +1,7 @@
 "use client";
 
-import { Button } from "@opal/components/buttons/Button/components";
-import { Tag, type TagProps } from "@opal/components/Tag/components";
+import { Button } from "@opal/components/buttons/button/components";
+import { Tag, type TagProps } from "@opal/components/tag/components";
 import type { SizeVariant } from "@opal/shared";
 import SvgAlertCircle from "@opal/icons/alert-circle";
 import SvgAlertTriangle from "@opal/icons/alert-triangle";
diff --git a/web/lib/opal/src/layouts/Content/ContentSm.tsx b/web/lib/opal/src/layouts/content/ContentSm.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/Content/ContentSm.tsx
rename to web/lib/opal/src/layouts/content/ContentSm.tsx
diff --git a/web/lib/opal/src/layouts/Content/ContentXl.tsx b/web/lib/opal/src/layouts/content/ContentXl.tsx
similarity index 99%
rename from web/lib/opal/src/layouts/Content/ContentXl.tsx
rename to web/lib/opal/src/layouts/content/ContentXl.tsx
index 08b36fd56d3..e086abf1859 100644
--- a/web/lib/opal/src/layouts/Content/ContentXl.tsx
+++ b/web/lib/opal/src/layouts/content/ContentXl.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Button } from "@opal/components/buttons/Button/components";
+import { Button } from "@opal/components/buttons/button/components";
 import type { SizeVariant } from "@opal/shared";
 import SvgEdit from "@opal/icons/edit";
 import type { IconFunctionComponent } from "@opal/types";
diff --git a/web/lib/opal/src/layouts/Content/HeadingLayout.tsx b/web/lib/opal/src/layouts/content/HeadingLayout.tsx
similarity index 98%
rename from web/lib/opal/src/layouts/Content/HeadingLayout.tsx
rename to web/lib/opal/src/layouts/content/HeadingLayout.tsx
index 8fe2d067c87..02eeaf0ddf7 100644
--- a/web/lib/opal/src/layouts/Content/HeadingLayout.tsx
+++ b/web/lib/opal/src/layouts/content/HeadingLayout.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Button } from "@opal/components/buttons/Button/components";
+import { Button } from "@opal/components/buttons/button/components";
 import type { SizeVariant } from "@opal/shared";
 import SvgEdit from "@opal/icons/edit";
 import type { IconFunctionComponent } from "@opal/types";
diff --git a/web/lib/opal/src/layouts/Content/LabelLayout.tsx b/web/lib/opal/src/layouts/content/LabelLayout.tsx
similarity index 98%
rename from web/lib/opal/src/layouts/Content/LabelLayout.tsx
rename to web/lib/opal/src/layouts/content/LabelLayout.tsx
index 9653490e088..6bfb5c9b680 100644
--- a/web/lib/opal/src/layouts/Content/LabelLayout.tsx
+++ b/web/lib/opal/src/layouts/content/LabelLayout.tsx
@@ -1,7 +1,7 @@
 "use client";
 
-import { Button } from "@opal/components/buttons/Button/components";
-import { Tag, type TagProps } from "@opal/components/Tag/components";
+import { Button } from "@opal/components/buttons/button/components";
+import { Tag, type TagProps } from "@opal/components/tag/components";
 import type { SizeVariant } from "@opal/shared";
 import SvgAlertCircle from "@opal/icons/alert-circle";
 import SvgAlertTriangle from "@opal/icons/alert-triangle";
diff --git a/web/lib/opal/src/layouts/Content/README.md b/web/lib/opal/src/layouts/content/README.md
similarity index 100%
rename from web/lib/opal/src/layouts/Content/README.md
rename to web/lib/opal/src/layouts/content/README.md
diff --git a/web/lib/opal/src/layouts/Content/components.tsx b/web/lib/opal/src/layouts/content/components.tsx
similarity index 95%
rename from web/lib/opal/src/layouts/Content/components.tsx
rename to web/lib/opal/src/layouts/content/components.tsx
index b0a3660cd9b..3ce97bb01d8 100644
--- a/web/lib/opal/src/layouts/Content/components.tsx
+++ b/web/lib/opal/src/layouts/content/components.tsx
@@ -1,22 +1,22 @@
-import "@opal/layouts/Content/styles.css";
+import "@opal/layouts/content/styles.css";
 import {
   ContentSm,
   type ContentSmOrientation,
   type ContentSmProminence,
-} from "@opal/layouts/Content/ContentSm";
+} from "@opal/layouts/content/ContentSm";
 import {
   ContentXl,
   type ContentXlProps,
-} from "@opal/layouts/Content/ContentXl";
+} from "@opal/layouts/content/ContentXl";
 import {
   ContentLg,
   type ContentLgProps,
-} from "@opal/layouts/Content/ContentLg";
+} from "@opal/layouts/content/ContentLg";
 import {
   ContentMd,
   type ContentMdProps,
-} from "@opal/layouts/Content/ContentMd";
-import type { TagProps } from "@opal/components/Tag/components";
+} from "@opal/layouts/content/ContentMd";
+import type { TagProps } from "@opal/components/tag/components";
 import type { IconFunctionComponent } from "@opal/types";
 import { widthVariants, type WidthVariant } from "@opal/shared";
 
diff --git a/web/lib/opal/src/layouts/Content/styles.css b/web/lib/opal/src/layouts/content/styles.css
similarity index 100%
rename from web/lib/opal/src/layouts/Content/styles.css
rename to web/lib/opal/src/layouts/content/styles.css
diff --git a/web/lib/opal/src/layouts/IllustrationContent/README.md b/web/lib/opal/src/layouts/illustration-content/README.md
similarity index 100%
rename from web/lib/opal/src/layouts/IllustrationContent/README.md
rename to web/lib/opal/src/layouts/illustration-content/README.md
diff --git a/web/lib/opal/src/layouts/IllustrationContent/components.tsx b/web/lib/opal/src/layouts/illustration-content/components.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/IllustrationContent/components.tsx
rename to web/lib/opal/src/layouts/illustration-content/components.tsx
diff --git a/web/lib/opal/src/layouts/index.ts b/web/lib/opal/src/layouts/index.ts
index 6b703e1e8f9..6077b4d0386 100644
--- a/web/lib/opal/src/layouts/index.ts
+++ b/web/lib/opal/src/layouts/index.ts
@@ -4,16 +4,16 @@ export {
   type ContentProps,
   type SizePreset,
   type ContentVariant,
-} from "@opal/layouts/Content/components";
+} from "@opal/layouts/content/components";
 
 /* ContentAction */
 export {
   ContentAction,
   type ContentActionProps,
-} from "@opal/layouts/ContentAction/components";
+} from "@opal/layouts/content-action/components";
 
 /* IllustrationContent */
 export {
   IllustrationContent,
   type IllustrationContentProps,
-} from "@opal/layouts/IllustrationContent/components";
+} from "@opal/layouts/illustration-content/components";
diff --git a/web/src/app/admin/indexing/status/FilterComponent.tsx b/web/src/app/admin/indexing/status/FilterComponent.tsx
index 65156c10bb0..e22341eec46 100644
--- a/web/src/app/admin/indexing/status/FilterComponent.tsx
+++ b/web/src/app/admin/indexing/status/FilterComponent.tsx
@@ -127,7 +127,11 @@ export const FilterComponent = forwardRef<
     <div className="relative">
       <DropdownMenu open={isOpen} onOpenChange={handleOpenChange}>
         <DropdownMenuTrigger asChild>
-          <Button icon={SvgFilter} prominence="secondary" transient={isOpen} />
+          <Button
+            icon={SvgFilter}
+            prominence="secondary"
+            interaction={isOpen ? "hover" : "rest"}
+          />
         </DropdownMenuTrigger>
         <DropdownMenuContent
           align="end"
diff --git a/web/src/app/admin/scim/ScimModal.tsx b/web/src/app/admin/scim/ScimModal.tsx
index a0029b1e099..891f7e1fabc 100644
--- a/web/src/app/admin/scim/ScimModal.tsx
+++ b/web/src/app/admin/scim/ScimModal.tsx
@@ -84,7 +84,7 @@ export default function ScimModal({
               onClose={onClose}
             />
             <Modal.Body>
-              <Interactive.Base
+              <Interactive.Stateless
                 group="group/token"
                 onClick={() => copyToClipboard(view.rawToken)}
               >
@@ -104,7 +104,7 @@ export default function ScimModal({
                     </div>
                   }
                 />
-              </Interactive.Base>
+              </Interactive.Stateless>
             </Modal.Body>
             <Modal.Footer>
               <BasicModalFooter
diff --git a/web/src/app/app/message/messageComponents/MessageToolbar.tsx b/web/src/app/app/message/messageComponents/MessageToolbar.tsx
index f2675fb5098..61070fd1e44 100644
--- a/web/src/app/app/message/messageComponents/MessageToolbar.tsx
+++ b/web/src/app/app/message/messageComponents/MessageToolbar.tsx
@@ -28,7 +28,7 @@ import { useCreateModal } from "@/refresh-components/contexts/ModalContext";
 import FeedbackModal, {
   FeedbackModalProps,
 } from "@/sections/modals/FeedbackModal";
-import { Button } from "@opal/components";
+import { Button, SelectButton } from "@opal/components";
 
 // Wrapper component for SourceTag in toolbar to handle memoization
 const SourcesTagWrapper = React.memo(function SourcesTagWrapper({
@@ -246,21 +246,19 @@ export default function MessageToolbar({
               getHtmlContent={() => finalAnswerRef.current?.innerHTML || ""}
               data-testid="AgentMessage/copy-button"
             />
-            <Button
+            <SelectButton
               icon={SvgThumbsUp}
               onClick={() => handleFeedbackClick("like")}
-              variant="select"
-              selected={isFeedbackTransient("like")}
+              state={isFeedbackTransient("like") ? "selected" : "empty"}
               tooltip={
                 currentFeedback === "like" ? "Remove Like" : "Good Response"
               }
               data-testid="AgentMessage/like-button"
             />
-            <Button
+            <SelectButton
               icon={SvgThumbsDown}
               onClick={() => handleFeedbackClick("dislike")}
-              variant="select"
-              selected={isFeedbackTransient("dislike")}
+              state={isFeedbackTransient("dislike") ? "selected" : "empty"}
               tooltip={
                 currentFeedback === "dislike"
                   ? "Remove Dislike"
diff --git a/web/src/components/modals/UserFilesModal.tsx b/web/src/components/modals/UserFilesModal.tsx
index ddd53c746c0..527ebb3df33 100644
--- a/web/src/components/modals/UserFilesModal.tsx
+++ b/web/src/components/modals/UserFilesModal.tsx
@@ -273,7 +273,7 @@ export default function UserFilesModal({
                   prominence="tertiary"
                   size="sm"
                   onClick={() => setShowOnlySelected(!showOnlySelected)}
-                  transient={showOnlySelected}
+                  interaction={showOnlySelected ? "hover" : "rest"}
                 />
                 <Button
                   icon={SvgXCircle}
diff --git a/web/src/ee/sections/SearchCard.tsx b/web/src/ee/sections/SearchCard.tsx
index 1f01b019a82..0aae1dfbf5d 100644
--- a/web/src/ee/sections/SearchCard.tsx
+++ b/web/src/ee/sections/SearchCard.tsx
@@ -55,7 +55,7 @@ export default function SearchCard({
   );
 
   return (
-    <Interactive.Base onClick={handleClick} prominence="secondary">
+    <Interactive.Stateless onClick={handleClick} prominence="secondary">
       <Interactive.Container heightVariant="fit">
         <Section alignItems="start" gap={0} padding={0.25}>
           {/* Title Row */}
@@ -107,6 +107,6 @@ export default function SearchCard({
           </div>
         </Section>
       </Interactive.Container>
-    </Interactive.Base>
+    </Interactive.Stateless>
   );
 }
diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index 266a791a2e5..3ec6c9eb364 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -394,7 +394,7 @@ function Header() {
               <Button
                 icon={SvgShare}
                 prominence="tertiary"
-                transient={showShareModal}
+                interaction={showShareModal ? "hover" : "rest"}
                 responsiveHideText
                 onClick={() => setShowShareModal(true)}
                 aria-label="share-chat-button"
diff --git a/web/src/refresh-components/Pagination.tsx b/web/src/refresh-components/Pagination.tsx
index b3d92e229f3..1b87db52859 100644
--- a/web/src/refresh-components/Pagination.tsx
+++ b/web/src/refresh-components/Pagination.tsx
@@ -93,7 +93,7 @@ export default function Pagination({
               key={pageNum}
               onClick={() => onPageChange(pageNum)}
               prominence="tertiary"
-              transient={isActive}
+              interaction={isActive ? "hover" : "rest"}
               icon={({ className }) => (
                 <div className={cn(className, "flex flex-col justify-center")}>
                   <Text>{pageNum}</Text>
diff --git a/web/src/refresh-components/SimpleCollapsible.tsx b/web/src/refresh-components/SimpleCollapsible.tsx
index 284feaf08c4..392c4f8f706 100644
--- a/web/src/refresh-components/SimpleCollapsible.tsx
+++ b/web/src/refresh-components/SimpleCollapsible.tsx
@@ -210,7 +210,7 @@ const Header = React.forwardRef<HTMLDivElement, SimpleCollapsibleHeaderProps>(
             icon={open ? SvgFold : SvgExpand}
             prominence="tertiary"
             size="sm"
-            transient={inside}
+            interaction={inside ? "hover" : "rest"}
             tooltip={open ? "Fold" : "Expand"}
           />
         </div>
diff --git a/web/src/refresh-components/buttons/SidebarTab.tsx b/web/src/refresh-components/buttons/SidebarTab.tsx
index a2f9d119371..95adc27796a 100644
--- a/web/src/refresh-components/buttons/SidebarTab.tsx
+++ b/web/src/refresh-components/buttons/SidebarTab.tsx
@@ -54,9 +54,9 @@ export default function SidebarTab({
 
   const content = (
     <div className="relative">
-      <Interactive.Base
+      <Interactive.Stateful
         variant="sidebar"
-        selected={selected}
+        state={selected ? "selected" : "empty"}
         onClick={onClick}
         group="group/SidebarTab"
       >
@@ -110,7 +110,7 @@ export default function SidebarTab({
             </div>
           )}
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateful>
     </div>
   );
 
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index 57da4db2f2b..105ddfe399e 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -1029,7 +1029,7 @@ export default function ActionsPopover({
           <div data-testid="action-management-toggle">
             <Button
               icon={SvgSliders}
-              transient={open}
+              interaction={open ? "hover" : "rest"}
               prominence="tertiary"
               tooltip="Manage Actions"
               disabled={disabled}
diff --git a/web/src/refresh-components/popovers/LLMPopover.tsx b/web/src/refresh-components/popovers/LLMPopover.tsx
index 44275c41594..f8e86646be7 100644
--- a/web/src/refresh-components/popovers/LLMPopover.tsx
+++ b/web/src/refresh-components/popovers/LLMPopover.tsx
@@ -364,7 +364,6 @@ export default function LLMPopover({
                     llmManager.currentLlm.modelName
                   )
             }
-            foldable={folded}
             disabled={disabled}
           >
             {currentLlmDisplayName}
diff --git a/web/src/refresh-components/table/ColumnVisibilityPopover.tsx b/web/src/refresh-components/table/ColumnVisibilityPopover.tsx
index 2436d1947d1..1450f081d6d 100644
--- a/web/src/refresh-components/table/ColumnVisibilityPopover.tsx
+++ b/web/src/refresh-components/table/ColumnVisibilityPopover.tsx
@@ -38,7 +38,7 @@ function ColumnVisibilityPopover<TData extends RowData>({
       <Popover.Trigger asChild>
         <Button
           icon={SvgColumn}
-          transient={open}
+          interaction={open ? "hover" : "rest"}
           size={size === "small" ? "sm" : "md"}
           prominence="internal"
           tooltip="Columns"
diff --git a/web/src/refresh-components/table/Pagination.tsx b/web/src/refresh-components/table/Pagination.tsx
index f1ec24289a3..d70f2cb8f98 100644
--- a/web/src/refresh-components/table/Pagination.tsx
+++ b/web/src/refresh-components/table/Pagination.tsx
@@ -373,7 +373,7 @@ function ListPaginationInner({
                   onClick={() => onPageChange(pageNum)}
                   size={size}
                   prominence="tertiary"
-                  transient={isActive}
+                  interaction={isActive ? "hover" : "rest"}
                   icon={({ className: iconClassName }) => (
                     <PageNumberIcon
                       className={iconClassName}
diff --git a/web/src/refresh-components/table/SortingPopover.tsx b/web/src/refresh-components/table/SortingPopover.tsx
index 82d94da438c..d5e70d74954 100644
--- a/web/src/refresh-components/table/SortingPopover.tsx
+++ b/web/src/refresh-components/table/SortingPopover.tsx
@@ -47,7 +47,7 @@ function SortingPopover<TData extends RowData>({
       <Popover.Trigger asChild>
         <Button
           icon={currentSort === null ? SvgArrowUpDown : SvgSortOrder}
-          transient={open}
+          interaction={open ? "hover" : "rest"}
           size={size === "small" ? "sm" : "md"}
           prominence="internal"
           tooltip="Sort"
diff --git a/web/src/refresh-components/tiles/ButtonTile.tsx b/web/src/refresh-components/tiles/ButtonTile.tsx
index 72461595887..a6f1a12f93e 100644
--- a/web/src/refresh-components/tiles/ButtonTile.tsx
+++ b/web/src/refresh-components/tiles/ButtonTile.tsx
@@ -31,7 +31,7 @@ export default function ButtonTile({
   const Icon = icon;
 
   return (
-    <Interactive.Base
+    <Interactive.Stateless
       variant="default"
       prominence="secondary"
       group="group/Tile"
@@ -72,6 +72,6 @@ export default function ButtonTile({
           </div>
         )}
       </div>
-    </Interactive.Base>
+    </Interactive.Stateless>
   );
 }
diff --git a/web/src/refresh-pages/SettingsPage.tsx b/web/src/refresh-pages/SettingsPage.tsx
index 0abefd0c975..8c525716578 100644
--- a/web/src/refresh-pages/SettingsPage.tsx
+++ b/web/src/refresh-pages/SettingsPage.tsx
@@ -447,7 +447,7 @@ function GeneralSettings() {
                 prominence="secondary"
                 onClick={() => setShowDeleteConfirmation(true)}
                 icon={SvgTrash}
-                transient={showDeleteConfirmation}
+                interaction={showDeleteConfirmation ? "hover" : "rest"}
               >
                 Delete All Chats
               </Button>
@@ -1270,7 +1270,7 @@ function AccountsAccessSettings() {
                   prominence="secondary"
                   icon={SvgLock}
                   onClick={() => setShowPasswordModal(true)}
-                  transient={showPasswordModal}
+                  interaction={showPasswordModal ? "hover" : "rest"}
                 >
                   Change Password
                 </Button>
diff --git a/web/src/sections/Suggestions.tsx b/web/src/sections/Suggestions.tsx
index b907f1f5dad..3adb7257c5f 100644
--- a/web/src/sections/Suggestions.tsx
+++ b/web/src/sections/Suggestions.tsx
@@ -30,7 +30,7 @@ export default function Suggestions({ onSubmit }: SuggestionsProps) {
   return (
     <div className="max-w-[var(--app-page-main-content-width)] flex flex-col w-full p-1">
       {currentAgent.starter_messages.map(({ message }, index) => (
-        <Interactive.Base
+        <Interactive.Stateless
           key={index}
           variant="default"
           prominence="tertiary"
@@ -49,7 +49,7 @@ export default function Suggestions({ onSubmit }: SuggestionsProps) {
               prominence="muted"
             />
           </Interactive.Container>
-        </Interactive.Base>
+        </Interactive.Stateless>
       ))}
     </div>
   );
diff --git a/web/src/sections/actions/ToolsList.tsx b/web/src/sections/actions/ToolsList.tsx
index 74f7a3ddf18..b34205064aa 100644
--- a/web/src/sections/actions/ToolsList.tsx
+++ b/web/src/sections/actions/ToolsList.tsx
@@ -100,7 +100,7 @@ const ToolsList: React.FC<ToolsListProps> = ({
                   prominence="tertiary"
                   size="sm"
                   onClick={onToggleShowOnlyEnabled}
-                  transient={showOnlyEnabled}
+                  interaction={showOnlyEnabled ? "hover" : "rest"}
                   tooltip={
                     showOnlyEnabled ? "Show all tools" : "Show only enabled"
                   }
diff --git a/web/src/sections/cards/AgentCard.tsx b/web/src/sections/cards/AgentCard.tsx
index 502f7470345..931f9664672 100644
--- a/web/src/sections/cards/AgentCard.tsx
+++ b/web/src/sections/cards/AgentCard.tsx
@@ -127,7 +127,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
         {fullAgent && <AgentViewerModal agent={fullAgent} />}
       </agentViewerModal.Provider>
 
-      <Interactive.Base
+      <Interactive.Stateless
         onClick={() => agentViewerModal.toggle(true)}
         group="group/AgentCard"
         variant="none"
@@ -232,7 +232,7 @@ export default function AgentCard({ agent }: AgentCardProps) {
             </div>
           </div>
         </Card>
-      </Interactive.Base>
+      </Interactive.Stateless>
     </>
   );
 }
diff --git a/web/src/sections/cards/DocumentSetCard.tsx b/web/src/sections/cards/DocumentSetCard.tsx
index bd74b6dcdd4..2c642a2e199 100644
--- a/web/src/sections/cards/DocumentSetCard.tsx
+++ b/web/src/sections/cards/DocumentSetCard.tsx
@@ -29,7 +29,7 @@ export default function DocumentSetCard({
       disabled={!disabled || !disabledTooltip}
     >
       <div className="max-w-[12rem]">
-        <Interactive.Base
+        <Interactive.Stateless
           onClick={
             disabled || isSelected === undefined
               ? undefined
@@ -64,7 +64,7 @@ export default function DocumentSetCard({
             />
             <Spacer horizontal rem={0.5} />
           </Interactive.Container>
-        </Interactive.Base>
+        </Interactive.Stateless>
       </div>
     </SimpleTooltip>
   );
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index 7e3d59c7349..bd08bf70b46 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -50,7 +50,7 @@ import {
   SvgStop,
   SvgX,
 } from "@opal/icons";
-import { Button } from "@opal/components";
+import { Button, SelectButton } from "@opal/components";
 import Popover from "@/refresh-components/Popover";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import { useQueryController } from "@/providers/QueryControllerProvider";
@@ -442,7 +442,7 @@ const AppInputBar = React.memo(
               <Button
                 icon={SvgPlusCircle}
                 tooltip="Attach Files"
-                transient={open}
+                interaction={open ? "hover" : "rest"}
                 disabled={disabled}
                 prominence="tertiary"
               />
@@ -467,12 +467,10 @@ const AppInputBar = React.memo(
               />
             )}
             {onToggleTabReading ? (
-              <Button
+              <SelectButton
                 icon={SvgGlobe}
                 onClick={onToggleTabReading}
-                variant="select"
-                selected={tabReadingEnabled}
-                foldable={!tabReadingEnabled}
+                state={tabReadingEnabled ? "selected" : "empty"}
                 disabled={disabled}
               >
                 {tabReadingEnabled
@@ -486,19 +484,19 @@ const AppInputBar = React.memo(
                       })()
                     : "Reading tab..."
                   : "Read this tab"}
-              </Button>
+              </SelectButton>
             ) : (
               showDeepResearch && (
-                <Button
+                <SelectButton
+                  variant="select-light"
                   icon={SvgHourglass}
                   onClick={toggleDeepResearch}
-                  variant="select"
-                  selected={deepResearchEnabled}
+                  state={deepResearchEnabled ? "selected" : "empty"}
                   foldable={!deepResearchEnabled}
                   disabled={disabled}
                 >
                   Deep Research
-                </Button>
+                </SelectButton>
               )
             )}
 
@@ -512,7 +510,8 @@ const AppInputBar = React.memo(
                   return null;
                 }
                 return (
-                  <Button
+                  <SelectButton
+                    variant="select-light"
                     key={toolId}
                     icon={getIconForAction(tool)}
                     onClick={() => {
@@ -520,12 +519,11 @@ const AppInputBar = React.memo(
                         forcedToolIds.filter((id) => id !== toolId)
                       );
                     }}
-                    variant="select"
-                    selected
+                    state="selected"
                     disabled={disabled}
                   >
                     {tool.display_name}
-                  </Button>
+                  </SelectButton>
                 );
               })}
           </div>
diff --git a/web/src/sections/input/SharedAppInputBar.tsx b/web/src/sections/input/SharedAppInputBar.tsx
index e0ecc8b70a3..e5525911ecf 100644
--- a/web/src/sections/input/SharedAppInputBar.tsx
+++ b/web/src/sections/input/SharedAppInputBar.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import Text from "@/refresh-components/texts/Text";
-import { Button, OpenButton } from "@opal/components";
+import { Button, OpenButton, SelectButton } from "@opal/components";
 import { OpenAISVG } from "@/components/icons/icons";
 import {
   SvgPlusCircle,
@@ -28,12 +28,12 @@ export default function SharedAppInputBar() {
           <div className="flex flex-row items-center">
             <Button icon={SvgPlusCircle} prominence="tertiary" disabled />
             <Button icon={SvgSliders} prominence="tertiary" disabled />
-            <Button icon={SvgHourglass} variant="select" disabled />
+            <SelectButton icon={SvgHourglass} disabled />
           </div>
 
           {/* Right side controls */}
           <div className="flex flex-row items-center gap-1">
-            <OpenButton icon={OpenAISVG} foldable disabled>
+            <OpenButton icon={OpenAISVG} disabled>
               GPT-4o
             </OpenButton>
             <Button icon={SvgArrowUp} disabled />
diff --git a/web/src/sections/modals/AgentViewerModal.tsx b/web/src/sections/modals/AgentViewerModal.tsx
index ca7393c4028..a49f9939587 100644
--- a/web/src/sections/modals/AgentViewerModal.tsx
+++ b/web/src/sections/modals/AgentViewerModal.tsx
@@ -404,7 +404,7 @@ export default function AgentViewerModal({ agent }: AgentViewerModalProps) {
               />
               <div className="grid grid-cols-2 gap-1 w-full">
                 {agent.starter_messages.map((starter, index) => (
-                  <Interactive.Base
+                  <Interactive.Stateless
                     key={index}
                     onClick={() => handleStartChat(starter.message)}
                     prominence="tertiary"
@@ -419,7 +419,7 @@ export default function AgentViewerModal({ agent }: AgentViewerModalProps) {
                         widthVariant="full"
                       />
                     </Interactive.Container>
-                  </Interactive.Base>
+                  </Interactive.Stateless>
                 ))}
               </div>
             </>

From 19016dd35a343647c6db94f6183265619d465632 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Fri, 6 Mar 2026 03:48:22 -0800
Subject: [PATCH 146/267] refactor: add `Disabled` primitive to `@opal/core`
 (#9136)

---
 .../buttons/select-button/components.tsx      |  10 +-
 web/lib/opal/src/core/disabled/components.tsx |  94 ++++++++++
 web/lib/opal/src/core/disabled/styles.css     |  30 +++
 web/lib/opal/src/core/index.ts                |   8 +
 .../core/interactive/container/components.tsx |   5 +-
 .../core/interactive/stateful/components.tsx  |  29 ++-
 .../core/interactive/stateless/components.tsx |  29 ++-
 .../src/core/interactive/stateless/styles.css |  12 +-
 web/src/app/admin/api-key/OnyxApiKeyForm.tsx  |   9 +-
 .../app/admin/billing/BillingDetailsView.tsx  |  56 +++---
 web/src/app/admin/billing/CheckoutView.tsx    |   9 +-
 .../admin/billing/LicenseActivationCard.tsx   |  32 ++--
 web/src/app/admin/bots/SlackTokensForm.tsx    |   8 +-
 .../llm/ModelConfigurationField.tsx           |  24 ++-
 .../web-search/WebProviderSetupModal.tsx      |  13 +-
 .../admin/configuration/web-search/page.tsx   |  67 ++++---
 .../[ccPairId]/InlineFileManagement.tsx       |  68 ++++---
 .../connector/[ccPairId]/ReIndexModal.tsx     |  15 +-
 .../[connector]/AddConnectorPage.tsx          |  26 +--
 .../connectors/[connector]/NavigationRow.tsx  |  47 ++---
 .../[connector]/oauth/finalize/page.tsx       |   9 +-
 .../[connector]/pages/gdrive/Credential.tsx   |  62 +++---
 .../[connector]/pages/gmail/Credential.tsx    |  62 +++---
 .../app/admin/discord-bot/BotConfigCard.tsx   |  27 +--
 .../admin/discord-bot/DiscordGuildsTable.tsx  |  20 +-
 .../app/admin/discord-bot/[guild-id]/page.tsx |  31 ++-
 .../modals/ProviderCreationModal.tsx          |  26 +--
 .../embeddings/pages/EmbeddingFormPage.tsx    |  20 +-
 web/src/app/admin/kg/page.tsx                 |   7 +-
 web/src/app/admin/scim/ScimModal.tsx          |  13 +-
 web/src/app/admin/scim/ScimSyncCard.tsx       |  13 +-
 .../CreateRateLimitModal.tsx                  |   7 +-
 web/src/app/admin/users/page.tsx              |  16 +-
 web/src/app/app/message/MessageSwitcher.tsx   |  31 +--
 web/src/app/auth/forgot-password/page.tsx     |   9 +-
 web/src/app/auth/impersonate/page.tsx         |   9 +-
 web/src/app/auth/login/EmailPasswordForm.tsx  |  18 +-
 web/src/app/auth/reset-password/page.tsx      |   9 +-
 web/src/app/craft/components/InputBar.tsx     |  40 ++--
 web/src/app/craft/components/SideBar.tsx      |  26 +--
 .../craft/components/output-panel/UrlBar.tsx  |  20 +-
 .../components/OnboardingLlmSetup.tsx         |   2 +-
 .../components/OnboardingUserInfo.tsx         |   2 +-
 .../components/ConnectorConfigStep.tsx        |  21 ++-
 .../components/CreateCredentialInline.tsx     |  30 +--
 .../configure/components/CredentialStep.tsx   |  45 ++---
 .../configure/components/UserLibraryModal.tsx |  27 ++-
 web/src/app/craft/v1/configure/page.tsx       |  22 +--
 .../admin/groups/[groupId]/GroupDisplay.tsx   |  43 +++--
 .../admin/performance/usage/UsageReports.tsx  |  18 +-
 .../admin/theme/AppearanceThemeSettings.tsx   |  18 +-
 web/src/app/ee/admin/theme/page.tsx           |  32 ++--
 web/src/components/DeleteButton.tsx           |  18 +-
 web/src/components/GenericMultiSelect.tsx     |   2 +-
 .../admin/users/buttons/InviteUserButton.tsx  |   9 +-
 web/src/components/chat/MCPApiKeyModal.tsx    |  30 +--
 .../credentials/actions/CreateCredential.tsx  |  13 +-
 .../credentials/actions/EditCredential.tsx    |   9 +-
 .../credentials/actions/ModifyCredential.tsx  |  53 +++---
 .../embedding/FailedReIndexAttempts.tsx       |  71 +++----
 .../errorPages/AccessRestrictedPage.tsx       |   9 +-
 .../components/modals/CreateProjectModal.tsx  |   7 +-
 .../components/modals/EditPropertyModal.tsx   |  10 +-
 web/src/components/modals/NewTeamModal.tsx    |  22 ++-
 web/src/components/modals/ProviderModal.tsx   |  18 +-
 web/src/components/modals/UserFilesModal.tsx  |  16 +-
 web/src/layouts/general-layouts.tsx           |  16 +-
 web/src/refresh-components/Disabled.tsx       | 107 -----------
 web/src/refresh-components/Pagination.tsx     |  27 +--
 web/src/refresh-components/Tabs.tsx           |  35 ++--
 .../source-tag/SourceTagDetailsCard.tsx       |  31 +--
 web/src/refresh-components/cards/Select.tsx   |  97 +++++-----
 .../form/InputTypeInElementField.tsx          |  16 +-
 .../inputs/InputComboBox/InputComboBox.tsx    |  22 ++-
 .../inputs/InputDatePicker.tsx                |   9 +-
 .../refresh-components/inputs/InputFile.tsx   |  20 +-
 .../inputs/InputKeyValue.tsx                  |  43 +++--
 .../refresh-components/inputs/InputNumber.tsx |  14 +-
 .../inputs/PasswordInputTypeIn.tsx            |  26 +--
 .../modals/MemoriesModal.tsx                  |  45 ++---
 .../popovers/ActionsPopover/index.tsx         |  16 +-
 .../popovers/LLMPopover.tsx                   |  28 +--
 .../refresh-components/table/Pagination.tsx   |  35 ++--
 .../refresh-components/tiles/ButtonTile.tsx   |  85 ++++-----
 web/src/refresh-pages/AgentEditorPage.tsx     |  10 +-
 web/src/refresh-pages/SettingsPage.tsx        | 111 +++++------
 .../admin/ChatPreferencesPage.tsx             |   2 +-
 .../admin/CodeInterpreterPage.tsx             |  35 ++--
 web/src/sections/actions/Actions.tsx          |  20 +-
 .../actions/modals/AddMCPServerModal.tsx      |  41 ++--
 .../actions/modals/AddOpenAPIActionModal.tsx  |  37 ++--
 .../actions/modals/DisconnectEntityModal.tsx  |  41 ++--
 .../actions/modals/MCPAuthenticationModal.tsx |  13 +-
 .../modals/OpenAPIAuthenticationModal.tsx     |  10 +-
 web/src/sections/input/AppInputBar.tsx        | 176 +++++++++---------
 web/src/sections/input/SharedAppInputBar.tsx  |  23 ++-
 .../sections/knowledge/AgentKnowledgePane.tsx |   2 +-
 web/src/sections/modals/FeedbackModal.tsx     |  10 +-
 web/src/sections/modals/NewTenantModal.tsx    |  42 ++---
 web/src/sections/modals/ShareAgentModal.tsx   |  22 +--
 .../sections/modals/ShareChatSessionModal.tsx |  20 +-
 .../components/FetchModelsButton.tsx          |  13 +-
 .../onboarding/components/LLMProviderCard.tsx |   2 +-
 .../onboarding/components/NonAdminStep.tsx    |   7 +-
 .../components/OnboardingHeader.tsx           |  10 +-
 .../forms/BedrockOnboardingForm.tsx           |  56 +++---
 .../onboarding/forms/OllamaOnboardingForm.tsx |  75 ++++----
 .../forms/OpenRouterOnboardingForm.tsx        |  38 ++--
 web/src/sections/onboarding/steps/LLMStep.tsx |  19 +-
 109 files changed, 1665 insertions(+), 1455 deletions(-)
 create mode 100644 web/lib/opal/src/core/disabled/components.tsx
 create mode 100644 web/lib/opal/src/core/disabled/styles.css
 delete mode 100644 web/src/refresh-components/Disabled.tsx

diff --git a/web/lib/opal/src/components/buttons/select-button/components.tsx b/web/lib/opal/src/components/buttons/select-button/components.tsx
index f18f3f3f76b..0fd0d01bd7a 100644
--- a/web/lib/opal/src/components/buttons/select-button/components.tsx
+++ b/web/lib/opal/src/components/buttons/select-button/components.tsx
@@ -1,6 +1,10 @@
 import "@opal/components/buttons/select-button/styles.css";
 import "@opal/components/tooltip.css";
-import { Interactive, type InteractiveStatefulProps } from "@opal/core";
+import {
+  Interactive,
+  useDisabled,
+  type InteractiveStatefulProps,
+} from "@opal/core";
 import type { SizeVariant, WidthVariant } from "@opal/shared";
 import type { TooltipSide } from "@opal/components";
 import type { IconFunctionComponent } from "@opal/types";
@@ -75,6 +79,7 @@ function SelectButton({
   tooltipSide = "top",
   ...statefulProps
 }: SelectButtonProps) {
+  const { isDisabled } = useDisabled();
   const isLarge = size === "lg";
 
   const labelEl = children ? (
@@ -123,8 +128,7 @@ function SelectButton({
   );
 
   const resolvedTooltip =
-    tooltip ??
-    (foldable && statefulProps.disabled && children ? children : undefined);
+    tooltip ?? (foldable && isDisabled && children ? children : undefined);
 
   if (!resolvedTooltip) return button;
 
diff --git a/web/lib/opal/src/core/disabled/components.tsx b/web/lib/opal/src/core/disabled/components.tsx
new file mode 100644
index 00000000000..d038420b442
--- /dev/null
+++ b/web/lib/opal/src/core/disabled/components.tsx
@@ -0,0 +1,94 @@
+import "@opal/core/disabled/styles.css";
+import React, { createContext, useContext } from "react";
+import { Slot } from "@radix-ui/react-slot";
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+interface DisabledContextValue {
+  isDisabled: boolean;
+  allowClick: boolean;
+}
+
+const DisabledContext = createContext<DisabledContextValue>({
+  isDisabled: false,
+  allowClick: false,
+});
+
+/**
+ * Returns the current disabled state from the nearest `<Disabled>` ancestor.
+ *
+ * Used internally by `Interactive.Stateless` and `Interactive.Stateful` to
+ * derive `data-disabled` and `aria-disabled` attributes automatically.
+ */
+function useDisabled(): DisabledContextValue {
+  return useContext(DisabledContext);
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface DisabledProps extends React.HTMLAttributes<HTMLElement> {
+  ref?: React.Ref<HTMLElement>;
+
+  /**
+   * When truthy, applies disabled styling to child elements.
+   */
+  disabled?: boolean;
+
+  /**
+   * When `true`, re-enables pointer events while keeping the disabled
+   * visual treatment. Useful for elements that need to show tooltips or
+   * error messages on click.
+   * @default false
+   */
+  allowClick?: boolean;
+
+  children: React.ReactElement;
+}
+
+// ---------------------------------------------------------------------------
+// Disabled
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrapper component that propagates disabled state via context and applies
+ * baseline disabled CSS (opacity, cursor, pointer-events) to its child.
+ *
+ * Uses Radix `Slot` — merges props onto the single child element without
+ * adding any DOM node. Works correctly inside Radix `asChild` chains.
+ *
+ * @example
+ * ```tsx
+ * <Disabled disabled={!canSubmit}>
+ *   <Button onClick={handleSubmit}>Save</Button>
+ * </Disabled>
+ * ```
+ */
+function Disabled({
+  disabled,
+  allowClick,
+  children,
+  ref,
+  ...rest
+}: DisabledProps) {
+  return (
+    <DisabledContext.Provider
+      value={{ isDisabled: !!disabled, allowClick: !!allowClick }}
+    >
+      <Slot
+        ref={ref}
+        {...rest}
+        aria-disabled={disabled || undefined}
+        data-opal-disabled={disabled || undefined}
+        data-allow-click={disabled && allowClick ? "" : undefined}
+      >
+        {children}
+      </Slot>
+    </DisabledContext.Provider>
+  );
+}
+
+export { Disabled, useDisabled, type DisabledProps, type DisabledContextValue };
diff --git a/web/lib/opal/src/core/disabled/styles.css b/web/lib/opal/src/core/disabled/styles.css
new file mode 100644
index 00000000000..77c250b416f
--- /dev/null
+++ b/web/lib/opal/src/core/disabled/styles.css
@@ -0,0 +1,30 @@
+/* Disabled — baseline disabled visuals via Radix Slot (no extra DOM node).
+ *
+ * [data-opal-disabled]                   → cursor + pointer-events for all
+ * [data-opal-disabled]:not(.interactive) → opacity for non-Interactive elements
+ * [data-opal-disabled][data-allow-click] → re-enables clicks
+ *
+ * Interactive elements (.interactive) handle their own disabled colors via
+ * variant CSS — no blanket opacity is applied to them. Pointer-events are
+ * re-enabled so the JS layer can suppress onClick.
+ */
+
+[data-opal-disabled] {
+  @apply cursor-not-allowed select-none;
+  pointer-events: none;
+}
+
+/* Only apply blanket opacity to non-Interactive elements.
+   Interactive variants define their own disabled backgrounds/foregrounds. */
+[data-opal-disabled]:not(.interactive) {
+  @apply opacity-50;
+}
+
+/* Re-enable pointer-events so the Interactive JS layer can suppress onClick. */
+[data-opal-disabled].interactive {
+  pointer-events: auto;
+}
+
+[data-opal-disabled][data-allow-click] {
+  pointer-events: auto;
+}
diff --git a/web/lib/opal/src/core/index.ts b/web/lib/opal/src/core/index.ts
index 2753d741c3b..e01eb2de571 100644
--- a/web/lib/opal/src/core/index.ts
+++ b/web/lib/opal/src/core/index.ts
@@ -1,3 +1,11 @@
+/* Disabled */
+export {
+  Disabled,
+  useDisabled,
+  type DisabledProps,
+  type DisabledContextValue,
+} from "@opal/core/disabled/components";
+
 /* Animations (formerly Hoverable) */
 export {
   Hoverable,
diff --git a/web/lib/opal/src/core/interactive/container/components.tsx b/web/lib/opal/src/core/interactive/container/components.tsx
index 3f52a430193..d232b03057b 100644
--- a/web/lib/opal/src/core/interactive/container/components.tsx
+++ b/web/lib/opal/src/core/interactive/container/components.tsx
@@ -10,6 +10,7 @@ import {
   widthVariants,
   type WidthVariant,
 } from "@opal/shared";
+import { useDisabled } from "@opal/core/disabled/components";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -103,6 +104,7 @@ function InteractiveContainer({
   widthVariant = "auto",
   ...props
 }: InteractiveContainerProps) {
+  const { allowClick } = useDisabled();
   const {
     className: slotClassName,
     style: slotStyle,
@@ -148,7 +150,8 @@ function InteractiveContainer({
   if (type) {
     const ariaDisabled = (rest as Record<string, unknown>)["aria-disabled"];
     const nativeDisabled =
-      ariaDisabled === true || ariaDisabled === "true" || undefined;
+      (type === "submit" || !allowClick) &&
+      (ariaDisabled === true || ariaDisabled === "true" || undefined);
     return (
       <button
         ref={ref as React.Ref<HTMLButtonElement>}
diff --git a/web/lib/opal/src/core/interactive/stateful/components.tsx b/web/lib/opal/src/core/interactive/stateful/components.tsx
index 395ff904738..5a7d3f11a85 100644
--- a/web/lib/opal/src/core/interactive/stateful/components.tsx
+++ b/web/lib/opal/src/core/interactive/stateful/components.tsx
@@ -3,6 +3,7 @@ import "@opal/core/interactive/stateful/styles.css";
 import React from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { cn } from "@opal/utils";
+import { useDisabled } from "@opal/core/disabled/components";
 import type { WithoutStyles } from "@opal/types";
 
 // ---------------------------------------------------------------------------
@@ -58,12 +59,6 @@ interface InteractiveStatefulProps
    */
   group?: string;
 
-  /**
-   * When `true`, disables the interactive element.
-   * @default false
-   */
-  disabled?: boolean;
-
   /**
    * URL to navigate to when clicked. Passed through Slot to the child.
    */
@@ -85,6 +80,9 @@ interface InteractiveStatefulProps
  * The foundational building block for elements that maintain a value state
  * (empty/filled/selected). Applies variant/state color styling via CSS
  * data-attributes and merges onto a single child element via Radix `Slot`.
+ *
+ * Disabled state is consumed from the nearest `<Disabled>` ancestor via
+ * context — there is no `disabled` prop on this component.
  */
 function InteractiveStateful({
   ref,
@@ -92,11 +90,12 @@ function InteractiveStateful({
   state = "empty",
   interaction = "rest",
   group,
-  disabled,
   href,
   target,
   ...props
 }: InteractiveStatefulProps) {
+  const { isDisabled, allowClick } = useDisabled();
+
   // onClick/href are always passed directly — Stateful is the outermost Slot,
   // so Radix Slot-injected handlers don't bypass this guard.
   const classes = cn(
@@ -109,15 +108,15 @@ function InteractiveStateful({
     "data-interactive-variant": variant,
     "data-interactive-state": state,
     "data-interaction": interaction !== "rest" ? interaction : undefined,
-    "data-disabled": disabled ? "true" : undefined,
-    "aria-disabled": disabled || undefined,
+    "data-disabled": isDisabled ? "true" : undefined,
+    "aria-disabled": isDisabled || undefined,
   };
 
   const { onClick, ...slotProps } = props;
 
   const linkAttrs = href
     ? {
-        href: disabled ? undefined : href,
+        href: isDisabled ? undefined : href,
         target,
         rel: target === "_blank" ? "noopener noreferrer" : undefined,
       }
@@ -131,11 +130,11 @@ function InteractiveStateful({
       {...linkAttrs}
       {...slotProps}
       onClick={
-        disabled && href
-          ? (e: React.MouseEvent) => e.preventDefault()
-          : disabled
-            ? undefined
-            : onClick
+        isDisabled && !allowClick
+          ? href
+            ? (e: React.MouseEvent) => e.preventDefault()
+            : undefined
+          : onClick
       }
     />
   );
diff --git a/web/lib/opal/src/core/interactive/stateless/components.tsx b/web/lib/opal/src/core/interactive/stateless/components.tsx
index 0fb8d0c96d9..cac1273001d 100644
--- a/web/lib/opal/src/core/interactive/stateless/components.tsx
+++ b/web/lib/opal/src/core/interactive/stateless/components.tsx
@@ -3,6 +3,7 @@ import "@opal/core/interactive/stateless/styles.css";
 import React from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { cn } from "@opal/utils";
+import { useDisabled } from "@opal/core/disabled/components";
 import type { WithoutStyles } from "@opal/types";
 
 // ---------------------------------------------------------------------------
@@ -52,12 +53,6 @@ interface InteractiveStatelessProps
    */
   group?: string;
 
-  /**
-   * When `true`, disables the interactive element.
-   * @default false
-   */
-  disabled?: boolean;
-
   /**
    * URL to navigate to when clicked. Passed through Slot to the child.
    */
@@ -80,6 +75,9 @@ interface InteractiveStatelessProps
  * element that does not maintain selection state. Applies variant/prominence
  * color styling via CSS data-attributes and merges onto a single child
  * element via Radix `Slot`.
+ *
+ * Disabled state is consumed from the nearest `<Disabled>` ancestor via
+ * context — there is no `disabled` prop on this component.
  */
 function InteractiveStateless({
   ref,
@@ -87,11 +85,12 @@ function InteractiveStateless({
   prominence = "primary",
   interaction = "rest",
   group,
-  disabled,
   href,
   target,
   ...props
 }: InteractiveStatelessProps) {
+  const { isDisabled, allowClick } = useDisabled();
+
   // onClick/href are always passed directly — Stateless is the outermost Slot,
   // so Radix Slot-injected handlers don't bypass this guard.
   const classes = cn(
@@ -104,15 +103,15 @@ function InteractiveStateless({
     "data-interactive-variant": variant !== "none" ? variant : undefined,
     "data-interactive-prominence": variant !== "none" ? prominence : undefined,
     "data-interaction": interaction !== "rest" ? interaction : undefined,
-    "data-disabled": disabled ? "true" : undefined,
-    "aria-disabled": disabled || undefined,
+    "data-disabled": isDisabled ? "true" : undefined,
+    "aria-disabled": isDisabled || undefined,
   };
 
   const { onClick, ...slotProps } = props;
 
   const linkAttrs = href
     ? {
-        href: disabled ? undefined : href,
+        href: isDisabled ? undefined : href,
         target,
         rel: target === "_blank" ? "noopener noreferrer" : undefined,
       }
@@ -126,11 +125,11 @@ function InteractiveStateless({
       {...linkAttrs}
       {...slotProps}
       onClick={
-        disabled && href
-          ? (e: React.MouseEvent) => e.preventDefault()
-          : disabled
-            ? undefined
-            : onClick
+        isDisabled && !allowClick
+          ? href
+            ? (e: React.MouseEvent) => e.preventDefault()
+            : undefined
+          : onClick
       }
     />
   );
diff --git a/web/lib/opal/src/core/interactive/stateless/styles.css b/web/lib/opal/src/core/interactive/stateless/styles.css
index 09b630bca2f..740a9192024 100644
--- a/web/lib/opal/src/core/interactive/stateless/styles.css
+++ b/web/lib/opal/src/core/interactive/stateless/styles.css
@@ -107,7 +107,7 @@
   --interactive-foreground-icon: var(--text-05);
 }
 .interactive[data-interactive-variant="default"][data-interactive-prominence="tertiary"][data-disabled] {
-  @apply bg-transparent opacity-50;
+  @apply bg-transparent;
   --interactive-foreground: var(--text-01);
   --interactive-foreground-icon: var(--text-01);
 }
@@ -141,7 +141,7 @@
   --interactive-foreground-icon: var(--text-05);
 }
 .interactive[data-interactive-variant="default"][data-interactive-prominence="internal"][data-disabled] {
-  @apply bg-transparent opacity-50;
+  @apply bg-transparent;
   --interactive-foreground: var(--text-01);
   --interactive-foreground-icon: var(--text-01);
 }
@@ -231,7 +231,7 @@
   @apply bg-background-tint-00;
 }
 .interactive[data-interactive-variant="action"][data-interactive-prominence="tertiary"][data-disabled] {
-  @apply bg-transparent opacity-50;
+  @apply bg-transparent;
   --interactive-foreground: var(--action-link-03);
   --interactive-foreground-icon: var(--action-link-03);
 }
@@ -261,7 +261,7 @@
   @apply bg-background-tint-00;
 }
 .interactive[data-interactive-variant="action"][data-interactive-prominence="internal"][data-disabled] {
-  @apply bg-transparent opacity-50;
+  @apply bg-transparent;
   --interactive-foreground: var(--action-link-03);
   --interactive-foreground-icon: var(--action-link-03);
 }
@@ -351,7 +351,7 @@
   @apply bg-background-tint-00;
 }
 .interactive[data-interactive-variant="danger"][data-interactive-prominence="tertiary"][data-disabled] {
-  @apply bg-transparent opacity-50;
+  @apply bg-transparent;
   --interactive-foreground: var(--action-danger-03);
   --interactive-foreground-icon: var(--action-danger-03);
 }
@@ -381,7 +381,7 @@
   @apply bg-background-tint-00;
 }
 .interactive[data-interactive-variant="danger"][data-interactive-prominence="internal"][data-disabled] {
-  @apply bg-transparent opacity-50;
+  @apply bg-transparent;
   --interactive-foreground: var(--action-danger-03);
   --interactive-foreground-icon: var(--action-danger-03);
 }
diff --git a/web/src/app/admin/api-key/OnyxApiKeyForm.tsx b/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
index 07a80d3df94..f11c15a7f92 100644
--- a/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
+++ b/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
@@ -3,6 +3,7 @@ import { toast } from "@/hooks/useToast";
 import { createApiKey, updateApiKey } from "./lib";
 import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import InputComboBox from "@/refresh-components/inputs/InputComboBox";
@@ -138,9 +139,11 @@ export default function OnyxApiKeyForm({
               </Modal.Body>
 
               <Modal.Footer>
-                <Button type="submit" disabled={isSubmitting}>
-                  {isUpdate ? "Update" : "Create"}
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button type="submit">
+                    {isUpdate ? "Update" : "Create"}
+                  </Button>
+                </Disabled>
               </Modal.Footer>
             </Form>
           )}
diff --git a/web/src/app/admin/billing/BillingDetailsView.tsx b/web/src/app/admin/billing/BillingDetailsView.tsx
index 76a68e4f419..76795bd5928 100644
--- a/web/src/app/admin/billing/BillingDetailsView.tsx
+++ b/web/src/app/admin/billing/BillingDetailsView.tsx
@@ -8,6 +8,7 @@ import * as InputLayouts from "@/layouts/input-layouts";
 import Card from "@/refresh-components/cards/Card";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import Message from "@/refresh-components/messages/Message";
 import InfoBlock from "@/refresh-components/messages/InfoBlock";
@@ -245,14 +246,15 @@ function SubscriptionCard({
               to make changes.
             </Text>
           ) : disabled ? (
-            <OpalButton
-              prominence="secondary"
-              onClick={handleReconnect}
-              rightIcon={SvgArrowRight}
-              disabled={isReconnecting}
-            >
-              {isReconnecting ? "Connecting..." : "Connect to Stripe"}
-            </OpalButton>
+            <Disabled disabled={isReconnecting}>
+              <OpalButton
+                prominence="secondary"
+                onClick={handleReconnect}
+                rightIcon={SvgArrowRight}
+              >
+                {isReconnecting ? "Connecting..." : "Connect to Stripe"}
+              </OpalButton>
+            </Disabled>
           ) : (
             <OpalButton onClick={handleManagePlan} rightIcon={SvgExternalLink}>
               Manage Plan
@@ -375,13 +377,11 @@ function SeatsCard({
             sizePreset="main-content"
             variant="section"
           />
-          <OpalButton
-            prominence="secondary"
-            onClick={handleCancel}
-            disabled={isSubmitting}
-          >
-            Cancel
-          </OpalButton>
+          <Disabled disabled={isSubmitting}>
+            <OpalButton prominence="secondary" onClick={handleCancel}>
+              Cancel
+            </OpalButton>
+          </Disabled>
         </Section>
 
         <div className="billing-content-area">
@@ -463,14 +463,15 @@ function SeatsCard({
               No changes to your billing.
             </Text>
           )}
-          <OpalButton
-            onClick={handleConfirm}
+          <Disabled
             disabled={
               isSubmitting || newSeatCount === totalSeats || isBelowMinimum
             }
           >
-            {isSubmitting ? "Saving..." : "Confirm Change"}
-          </OpalButton>
+            <OpalButton onClick={handleConfirm}>
+              {isSubmitting ? "Saving..." : "Confirm Change"}
+            </OpalButton>
+          </Disabled>
         </Section>
       </Card>
     );
@@ -508,14 +509,15 @@ function SeatsCard({
             View Users
           </OpalButton>
           {!hideUpdateSeats && (
-            <OpalButton
-              prominence="secondary"
-              onClick={handleStartEdit}
-              icon={SvgPlus}
-              disabled={isLoadingUsers || disabled || !billing}
-            >
-              Update Seats
-            </OpalButton>
+            <Disabled disabled={isLoadingUsers || disabled || !billing}>
+              <OpalButton
+                prominence="secondary"
+                onClick={handleStartEdit}
+                icon={SvgPlus}
+              >
+                Update Seats
+              </OpalButton>
+            </Disabled>
           )}
         </Section>
       </Section>
diff --git a/web/src/app/admin/billing/CheckoutView.tsx b/web/src/app/admin/billing/CheckoutView.tsx
index 9b22cc01374..35e8754642e 100644
--- a/web/src/app/admin/billing/CheckoutView.tsx
+++ b/web/src/app/admin/billing/CheckoutView.tsx
@@ -4,6 +4,7 @@ import { useState, useMemo, useEffect } from "react";
 import { Section } from "@/layouts/general-layouts";
 import * as InputLayouts from "@/layouts/input-layouts";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import Card from "@/refresh-components/cards/Card";
 import Separator from "@/refresh-components/Separator";
@@ -262,9 +263,11 @@ export default function CheckoutView({ onAdjustPlan }: CheckoutViewProps) {
           // Empty div to maintain space-between alignment
           <div></div>
         )}
-        <Button onClick={handleSubmit} disabled={isSubmitting}>
-          {isSubmitting ? "Loading..." : "Continue to Payment"}
-        </Button>
+        <Disabled disabled={isSubmitting}>
+          <Button onClick={handleSubmit}>
+            {isSubmitting ? "Loading..." : "Continue to Payment"}
+          </Button>
+        </Disabled>
       </Section>
     </Card>
   );
diff --git a/web/src/app/admin/billing/LicenseActivationCard.tsx b/web/src/app/admin/billing/LicenseActivationCard.tsx
index 5c63469506d..dc5521fdd0f 100644
--- a/web/src/app/admin/billing/LicenseActivationCard.tsx
+++ b/web/src/app/admin/billing/LicenseActivationCard.tsx
@@ -3,6 +3,7 @@
 import { useState } from "react";
 import Card from "@/refresh-components/cards/Card";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import InputFile from "@/refresh-components/inputs/InputFile";
 import { Section } from "@/layouts/general-layouts";
@@ -146,13 +147,11 @@ export default function LicenseActivationCard({
           <Text headingH3>
             {hasLicense ? "Update License Key" : "Activate License Key"}
           </Text>
-          <Button
-            prominence="secondary"
-            onClick={handleClose}
-            disabled={isActivating}
-          >
-            Cancel
-          </Button>
+          <Disabled disabled={isActivating}>
+            <Button prominence="secondary" onClick={handleClose}>
+              Cancel
+            </Button>
+          </Disabled>
         </Section>
         <Text secondaryBody text03>
           Manually add and activate a license for this Onyx instance.
@@ -222,16 +221,15 @@ export default function LicenseActivationCard({
 
       {/* Footer */}
       <Section flexDirection="row" justifyContent="end" padding={1}>
-        <Button
-          onClick={handleActivate}
-          disabled={isActivating || !licenseKey.trim() || success}
-        >
-          {isActivating
-            ? "Activating..."
-            : hasLicense
-              ? "Update License"
-              : "Activate License"}
-        </Button>
+        <Disabled disabled={isActivating || !licenseKey.trim() || success}>
+          <Button onClick={handleActivate}>
+            {isActivating
+              ? "Activating..."
+              : hasLicense
+                ? "Update License"
+                : "Activate License"}
+          </Button>
+        </Disabled>
       </Section>
     </Card>
   );
diff --git a/web/src/app/admin/bots/SlackTokensForm.tsx b/web/src/app/admin/bots/SlackTokensForm.tsx
index b831e0fb316..3333cdb3c0f 100644
--- a/web/src/app/admin/bots/SlackTokensForm.tsx
+++ b/web/src/app/admin/bots/SlackTokensForm.tsx
@@ -5,6 +5,7 @@ import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { createSlackBot, updateSlackBot } from "./new/lib";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Separator from "@/refresh-components/Separator";
 import { useEffect } from "react";
 import { DOCS_ADMINS_PATH } from "@/lib/constants";
@@ -126,8 +127,7 @@ export const SlackTokensForm = ({
             subtext="Optional: User OAuth token for enhanced private channel access"
           />
           <div className="flex justify-end w-full mt-4">
-            <Button
-              type="submit"
+            <Disabled
               disabled={
                 isSubmitting ||
                 !values.bot_token ||
@@ -135,8 +135,8 @@ export const SlackTokensForm = ({
                 !values.name
               }
             >
-              {isUpdate ? "Update" : "Create"}
-            </Button>
+              <Button type="submit">{isUpdate ? "Update" : "Create"}</Button>
+            </Disabled>
           </div>
         </Form>
       )}
diff --git a/web/src/app/admin/configuration/llm/ModelConfigurationField.tsx b/web/src/app/admin/configuration/llm/ModelConfigurationField.tsx
index 844b2d952ad..a9dcd8613fd 100644
--- a/web/src/app/admin/configuration/llm/ModelConfigurationField.tsx
+++ b/web/src/app/admin/configuration/llm/ModelConfigurationField.tsx
@@ -6,6 +6,7 @@ import { ManualErrorMessage, TextFormField } from "@/components/Field";
 import { useEffect, useState } from "react";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { SvgX } from "@opal/icons";
 import Text from "@/refresh-components/texts/Text";
 
@@ -55,17 +56,20 @@ function ModelConfigurationRow({
         />
       </div>
       <div className="flex flex-col justify-center">
-        <Button
+        <Disabled
           disabled={formikProps.values.model_configurations.length <= 1}
-          onClick={() => {
-            if (formikProps.values.model_configurations.length > 1) {
-              setError(null);
-              arrayHelpers.remove(index);
-            }
-          }}
-          icon={SvgX}
-          prominence="secondary"
-        />
+        >
+          <Button
+            onClick={() => {
+              if (formikProps.values.model_configurations.length > 1) {
+                setError(null);
+                arrayHelpers.remove(index);
+              }
+            }}
+            icon={SvgX}
+            prominence="secondary"
+          />
+        </Disabled>
       </div>
     </div>
   );
diff --git a/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx b/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx
index 0ba6e8e7401..9af36933d3e 100644
--- a/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx
+++ b/web/src/app/admin/configuration/web-search/WebProviderSetupModal.tsx
@@ -7,6 +7,7 @@ import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
 import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 
 import { SvgArrowExchange, SvgOnyxLogo } from "@opal/icons";
 import type { IconProps } from "@opal/types";
@@ -247,13 +248,11 @@ export const WebProviderSetupModal = memo(
             <Button prominence="secondary" type="button" onClick={onClose}>
               Cancel
             </Button>
-            <Button
-              type="button"
-              disabled={!canConnect || isProcessing}
-              onClick={onConnect}
-            >
-              {isProcessing ? "Connecting..." : "Connect"}
-            </Button>
+            <Disabled disabled={!canConnect || isProcessing}>
+              <Button type="button" onClick={onConnect}>
+                {isProcessing ? "Connecting..." : "Connect"}
+              </Button>
+            </Disabled>
           </Modal.Footer>
         </Modal.Content>
       </Modal>
diff --git a/web/src/app/admin/configuration/web-search/page.tsx b/web/src/app/admin/configuration/web-search/page.tsx
index 12d6712940b..0956ed6a041 100644
--- a/web/src/app/admin/configuration/web-search/page.tsx
+++ b/web/src/app/admin/configuration/web-search/page.tsx
@@ -12,6 +12,7 @@ import { ThreeDotsLoader } from "@/components/Loading";
 import { Callout } from "@/components/ui/callout";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { cn } from "@/lib/utils";
 import {
   SvgArrowExchange,
@@ -1011,25 +1012,28 @@ export default function Page() {
                             {buttonState.label}
                           </HoverIconButton>
                         ) : (
-                          <OpalButton
-                            prominence="tertiary"
+                          <Disabled
                             disabled={
                               buttonState.disabled || !buttonState.onClick
                             }
-                            onClick={(e) => {
-                              e.stopPropagation();
-                              buttonState.onClick?.();
-                            }}
-                            rightIcon={
-                              buttonState.icon === "arrow"
-                                ? SvgArrowExchange
-                                : buttonState.icon === "arrow-circle"
-                                  ? SvgArrowRightCircle
-                                  : undefined
-                            }
                           >
-                            {buttonState.label}
-                          </OpalButton>
+                            <OpalButton
+                              prominence="tertiary"
+                              onClick={(e) => {
+                                e.stopPropagation();
+                                buttonState.onClick?.();
+                              }}
+                              rightIcon={
+                                buttonState.icon === "arrow"
+                                  ? SvgArrowExchange
+                                  : buttonState.icon === "arrow-circle"
+                                    ? SvgArrowRightCircle
+                                    : undefined
+                              }
+                            >
+                              {buttonState.label}
+                            </OpalButton>
+                          </Disabled>
                         )}
                       </div>
                     </div>
@@ -1202,25 +1206,28 @@ export default function Page() {
                           {buttonState.label}
                         </HoverIconButton>
                       ) : (
-                        <OpalButton
-                          prominence="tertiary"
+                        <Disabled
                           disabled={
                             buttonState.disabled || !buttonState.onClick
                           }
-                          onClick={(e) => {
-                            e.stopPropagation();
-                            buttonState.onClick?.();
-                          }}
-                          rightIcon={
-                            buttonState.icon === "arrow"
-                              ? SvgArrowExchange
-                              : buttonState.icon === "arrow-circle"
-                                ? SvgArrowRightCircle
-                                : undefined
-                          }
                         >
-                          {buttonState.label}
-                        </OpalButton>
+                          <OpalButton
+                            prominence="tertiary"
+                            onClick={(e) => {
+                              e.stopPropagation();
+                              buttonState.onClick?.();
+                            }}
+                            rightIcon={
+                              buttonState.icon === "arrow"
+                                ? SvgArrowExchange
+                                : buttonState.icon === "arrow-circle"
+                                  ? SvgArrowRightCircle
+                                  : undefined
+                            }
+                          >
+                            {buttonState.label}
+                          </OpalButton>
+                        </Disabled>
                       )}
                     </div>
                   </div>
diff --git a/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx b/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx
index 5550b3df3d4..d97cfb1fd17 100644
--- a/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useRef } from "react";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   Table,
   TableBody,
@@ -183,24 +184,25 @@ export default function InlineFileManagement({
             </Button>
           ) : (
             <>
-              <Button
-                prominence="secondary"
-                onClick={handleCancel}
-                icon={SvgX}
-                disabled={isSaving}
-              >
-                Cancel
-              </Button>
-              <Button
-                onClick={handleSaveClick}
-                icon={SvgCheck}
+              <Disabled disabled={isSaving}>
+                <Button
+                  prominence="secondary"
+                  onClick={handleCancel}
+                  icon={SvgX}
+                >
+                  Cancel
+                </Button>
+              </Disabled>
+              <Disabled
                 disabled={
                   isSaving ||
                   (selectedFilesToRemove.size === 0 && filesToAdd.length === 0)
                 }
               >
-                {isSaving ? "Saving..." : "Save Changes"}
-              </Button>
+                <Button onClick={handleSaveClick} icon={SvgCheck}>
+                  {isSaving ? "Saving..." : "Save Changes"}
+                </Button>
+              </Disabled>
             </>
           )}
         </div>
@@ -332,14 +334,15 @@ export default function InlineFileManagement({
             className="hidden"
             id={`file-upload-${connectorId}`}
           />
-          <Button
-            prominence="secondary"
-            onClick={() => fileInputRef.current?.click()}
-            icon={SvgPlusCircle}
-            disabled={isSaving}
-          >
-            Add Files
-          </Button>
+          <Disabled disabled={isSaving}>
+            <Button
+              prominence="secondary"
+              onClick={() => fileInputRef.current?.click()}
+              icon={SvgPlusCircle}
+            >
+              Add Files
+            </Button>
+          </Disabled>
         </div>
       )}
 
@@ -395,16 +398,19 @@ export default function InlineFileManagement({
           </Modal.Body>
 
           <Modal.Footer>
-            <Button
-              prominence="secondary"
-              onClick={() => setShowSaveConfirm(false)}
-              disabled={isSaving}
-            >
-              Cancel
-            </Button>
-            <Button onClick={handleConfirmSave} disabled={isSaving}>
-              {isSaving ? "Saving..." : "Confirm & Save"}
-            </Button>
+            <Disabled disabled={isSaving}>
+              <Button
+                prominence="secondary"
+                onClick={() => setShowSaveConfirm(false)}
+              >
+                Cancel
+              </Button>
+            </Disabled>
+            <Disabled disabled={isSaving}>
+              <Button onClick={handleConfirmSave}>
+                {isSaving ? "Saving..." : "Confirm & Save"}
+              </Button>
+            </Disabled>
           </Modal.Footer>
         </Modal.Content>
       </Modal>
diff --git a/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx b/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx
index 5987e28447e..5a840930813 100644
--- a/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx
+++ b/web/src/app/admin/connector/[ccPairId]/ReIndexModal.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { useState } from "react";
 import { toast } from "@/hooks/useToast";
 import { triggerIndexing } from "@/app/admin/connector/[ccPairId]/lib";
@@ -115,9 +116,9 @@ export default function ReIndexModal({ hide, onRunIndex }: ReIndexModalProps) {
             This will pull in and index all documents that have changed and/or
             have been added since the last successful indexing run.
           </Text>
-          <Button onClick={() => handleRunIndex(false)} disabled={isProcessing}>
-            Run Update
-          </Button>
+          <Disabled disabled={isProcessing}>
+            <Button onClick={() => handleRunIndex(false)}>Run Update</Button>
+          </Disabled>
 
           <Separator />
 
@@ -130,9 +131,11 @@ export default function ReIndexModal({ hide, onRunIndex }: ReIndexModalProps) {
             in the source, this may take a long time.
           </Text>
 
-          <Button onClick={() => handleRunIndex(true)} disabled={isProcessing}>
-            Run Complete Re-Indexing
-          </Button>
+          <Disabled disabled={isProcessing}>
+            <Button onClick={() => handleRunIndex(true)}>
+              Run Complete Re-Indexing
+            </Button>
+          </Disabled>
         </Modal.Body>
       </Modal.Content>
     </Modal>
diff --git a/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx b/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
index 28190b7ef3f..efe6fcf0ab8 100644
--- a/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
+++ b/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
@@ -56,6 +56,7 @@ import {
 import { CreateStdOAuthCredential } from "@/components/credentials/actions/CreateStdOAuthCredential";
 import { Spinner } from "@/components/Spinner";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { deleteConnector } from "@/lib/connector";
 import ConnectorDocsLink from "@/components/admin/connectors/ConnectorDocsLink";
 import Text from "@/refresh-components/texts/Text";
@@ -579,18 +580,19 @@ export default function AddConnector({
                       {/* Button to sign in via OAuth */}
                       {oauthSupportedSources.includes(connector) &&
                         (NEXT_PUBLIC_CLOUD_ENABLED || NEXT_PUBLIC_TEST_ENV) && (
-                          <Button
-                            variant="action"
-                            onClick={handleAuthorize}
-                            disabled={isAuthorizing}
-                            hidden={!isAuthorizeVisible}
-                          >
-                            {isAuthorizing
-                              ? "Authorizing..."
-                              : `Authorize with ${getSourceDisplayName(
-                                  connector
-                                )}`}
-                          </Button>
+                          <Disabled disabled={isAuthorizing}>
+                            <Button
+                              variant="action"
+                              onClick={handleAuthorize}
+                              hidden={!isAuthorizeVisible}
+                            >
+                              {isAuthorizing
+                                ? "Authorizing..."
+                                : `Authorize with ${getSourceDisplayName(
+                                    connector
+                                  )}`}
+                            </Button>
+                          </Disabled>
                         )}
                     </div>
                   )}
diff --git a/web/src/app/admin/connectors/[connector]/NavigationRow.tsx b/web/src/app/admin/connectors/[connector]/NavigationRow.tsx
index 3e612a231e5..0c25a64a146 100644
--- a/web/src/app/admin/connectors/[connector]/NavigationRow.tsx
+++ b/web/src/app/admin/connectors/[connector]/NavigationRow.tsx
@@ -1,5 +1,6 @@
 import { useFormContext } from "@/components/context/FormContext";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { SvgArrowLeft, SvgArrowRight, SvgPlusCircle } from "@opal/icons";
 
 const NavigationRow = ({
@@ -33,35 +34,35 @@ const NavigationRow = ({
       </div>
       <div className="flex justify-center">
         {(formStep > 0 || noCredentials) && (
-          <Button
-            disabled={!isValid}
-            rightIcon={SvgPlusCircle}
-            onClick={onSubmit}
-          >
-            Create Connector
-          </Button>
+          <Disabled disabled={!isValid}>
+            <Button rightIcon={SvgPlusCircle} onClick={onSubmit}>
+              Create Connector
+            </Button>
+          </Disabled>
         )}
       </div>
       <div className="flex justify-end">
         {formStep === 0 && (
-          <Button
-            variant="action"
-            disabled={!activatedCredential}
-            rightIcon={SvgArrowRight}
-            onClick={() => nextFormStep()}
-          >
-            Continue
-          </Button>
+          <Disabled disabled={!activatedCredential}>
+            <Button
+              variant="action"
+              rightIcon={SvgArrowRight}
+              onClick={() => nextFormStep()}
+            >
+              Continue
+            </Button>
+          </Disabled>
         )}
         {!noAdvanced && formStep === 1 && (
-          <Button
-            prominence="secondary"
-            disabled={!isValid}
-            rightIcon={SvgArrowRight}
-            onClick={() => nextFormStep()}
-          >
-            Advanced
-          </Button>
+          <Disabled disabled={!isValid}>
+            <Button
+              prominence="secondary"
+              rightIcon={SvgArrowRight}
+              onClick={() => nextFormStep()}
+            >
+              Advanced
+            </Button>
+          </Disabled>
         )}
       </div>
     </div>
diff --git a/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx b/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx
index fc86523b72e..f5e0961ceb4 100644
--- a/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx
+++ b/web/src/app/admin/connectors/[connector]/oauth/finalize/page.tsx
@@ -4,6 +4,7 @@ import { useEffect, useState } from "react";
 import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import { AdminPageTitle } from "@/components/admin/Title";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { getSourceMetadata, isValidSource } from "@/lib/sources";
 import { ConfluenceAccessibleResource, ValidSources } from "@/lib/types";
 import CardSection from "@/components/admin/CardSection";
@@ -259,9 +260,11 @@ export default function OAuthFinalizePage() {
                 )}
                 <br />
                 {!redirectUrl && (
-                  <Button type="submit" disabled={!isValid || isSubmitting}>
-                    {isSubmitting ? "Submitting..." : "Submit"}
-                  </Button>
+                  <Disabled disabled={!isValid || isSubmitting}>
+                    <Button type="submit">
+                      {isSubmitting ? "Submitting..." : "Submit"}
+                    </Button>
+                  </Disabled>
                 )}
               </Form>
             )}
diff --git a/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx b/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
index 09d7d9a0b11..2d61405d016 100644
--- a/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx
@@ -11,6 +11,7 @@ import { TextFormField, SectionHeader } from "@/components/Field";
 import { Form, Formik } from "formik";
 import { User } from "@/lib/types";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   Credential,
   GoogleDriveCredentialJson,
@@ -561,9 +562,11 @@ export const DriveAuthSection = ({
                   subtext="Enter the email of an admin/owner of the Google Organization that owns the Google Drive(s) you want to index."
                 />
                 <div className="flex">
-                  <Button type="submit" disabled={isSubmitting}>
-                    {isSubmitting ? "Creating..." : "Create Credential"}
-                  </Button>
+                  <Disabled disabled={isSubmitting}>
+                    <Button type="submit">
+                      {isSubmitting ? "Creating..." : "Create Credential"}
+                    </Button>
+                  </Disabled>
                 </div>
               </Form>
             )}
@@ -583,34 +586,35 @@ export const DriveAuthSection = ({
             Google Drive account.
           </p>
         </div>
-        <Button
-          disabled={isAuthenticating}
-          onClick={async () => {
-            setIsAuthenticating(true);
-            try {
-              const [authUrl, errorMsg] = await setupGoogleDriveOAuth({
-                isAdmin: true,
-                name: "OAuth (uploaded)",
-              });
-
-              if (authUrl) {
-                router.push(authUrl as Route);
-              } else {
-                toast.error(errorMsg);
+        <Disabled disabled={isAuthenticating}>
+          <Button
+            onClick={async () => {
+              setIsAuthenticating(true);
+              try {
+                const [authUrl, errorMsg] = await setupGoogleDriveOAuth({
+                  isAdmin: true,
+                  name: "OAuth (uploaded)",
+                });
+
+                if (authUrl) {
+                  router.push(authUrl as Route);
+                } else {
+                  toast.error(errorMsg);
+                  setIsAuthenticating(false);
+                }
+              } catch (error) {
+                toast.error(
+                  `Failed to authenticate with Google Drive - ${error}`
+                );
                 setIsAuthenticating(false);
               }
-            } catch (error) {
-              toast.error(
-                `Failed to authenticate with Google Drive - ${error}`
-              );
-              setIsAuthenticating(false);
-            }
-          }}
-        >
-          {isAuthenticating
-            ? "Authenticating..."
-            : "Authenticate with Google Drive"}
-        </Button>
+            }}
+          >
+            {isAuthenticating
+              ? "Authenticating..."
+              : "Authenticate with Google Drive"}
+          </Button>
+        </Disabled>
       </div>
     );
   }
diff --git a/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx b/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
index cb544076fb7..f3557133978 100644
--- a/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
+++ b/web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx
@@ -1,4 +1,5 @@
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { toast } from "@/hooks/useToast";
 import React, { useState, useEffect } from "react";
 import { useSWRConfig } from "swr";
@@ -570,9 +571,11 @@ export const GmailAuthSection = ({
                   subtext="Enter the email of an admin/owner of the Google Organization that owns the Gmail account(s) you want to index."
                 />
                 <div className="flex">
-                  <Button type="submit" disabled={isSubmitting}>
-                    {isSubmitting ? "Creating..." : "Create Credential"}
-                  </Button>
+                  <Disabled disabled={isSubmitting}>
+                    <Button type="submit">
+                      {isSubmitting ? "Creating..." : "Create Credential"}
+                    </Button>
+                  </Disabled>
                 </div>
               </Form>
             )}
@@ -591,35 +594,36 @@ export const GmailAuthSection = ({
             read access to the emails you have access to in your Gmail account.
           </p>
         </div>
-        <Button
-          disabled={isAuthenticating}
-          onClick={async () => {
-            setIsAuthenticating(true);
-            try {
-              if (buildMode) {
-                Cookies.set(CRAFT_OAUTH_COOKIE_NAME, "true", {
-                  path: "/",
+        <Disabled disabled={isAuthenticating}>
+          <Button
+            onClick={async () => {
+              setIsAuthenticating(true);
+              try {
+                if (buildMode) {
+                  Cookies.set(CRAFT_OAUTH_COOKIE_NAME, "true", {
+                    path: "/",
+                  });
+                }
+                const [authUrl, errorMsg] = await setupGmailOAuth({
+                  isAdmin: true,
                 });
-              }
-              const [authUrl, errorMsg] = await setupGmailOAuth({
-                isAdmin: true,
-              });
-
-              if (authUrl) {
-                onOAuthRedirect?.();
-                router.push(authUrl as Route);
-              } else {
-                toast.error(errorMsg);
+
+                if (authUrl) {
+                  onOAuthRedirect?.();
+                  router.push(authUrl as Route);
+                } else {
+                  toast.error(errorMsg);
+                  setIsAuthenticating(false);
+                }
+              } catch (error) {
+                toast.error(`Failed to authenticate with Gmail - ${error}`);
                 setIsAuthenticating(false);
               }
-            } catch (error) {
-              toast.error(`Failed to authenticate with Gmail - ${error}`);
-              setIsAuthenticating(false);
-            }
-          }}
-        >
-          {isAuthenticating ? "Authenticating..." : "Authenticate with Gmail"}
-        </Button>
+            }}
+          >
+            {isAuthenticating ? "Authenticating..." : "Authenticate with Gmail"}
+          </Button>
+        </Disabled>
       </div>
     );
   }
diff --git a/web/src/app/admin/discord-bot/BotConfigCard.tsx b/web/src/app/admin/discord-bot/BotConfigCard.tsx
index 3e6622b11d8..5f6317a55ec 100644
--- a/web/src/app/admin/discord-bot/BotConfigCard.tsx
+++ b/web/src/app/admin/discord-bot/BotConfigCard.tsx
@@ -5,6 +5,7 @@ import { Section } from "@/layouts/general-layouts";
 import Text from "@/refresh-components/texts/Text";
 import Card from "@/refresh-components/cards/Card";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { Badge } from "@/components/ui/badge";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
 import { ThreeDotsLoader } from "@/components/Loading";
@@ -125,13 +126,14 @@ export function BotConfigCard() {
               }
               disabled={!hasServerConfigs}
             >
-              <Button
-                variant="danger"
-                onClick={() => setShowDeleteConfirm(true)}
-                disabled={isSubmitting || hasServerConfigs}
-              >
-                Delete Discord Token
-              </Button>
+              <Disabled disabled={isSubmitting || hasServerConfigs}>
+                <Button
+                  variant="danger"
+                  onClick={() => setShowDeleteConfirm(true)}
+                >
+                  Delete Discord Token
+                </Button>
+              </Disabled>
             </SimpleTooltip>
           )}
         </Section>
@@ -165,12 +167,11 @@ export function BotConfigCard() {
                 disabled={isSubmitting}
                 className="flex-1"
               />
-              <Button
-                onClick={handleSaveToken}
-                disabled={isSubmitting || !botToken.trim()}
-              >
-                {isSubmitting ? "Saving..." : "Save Token"}
-              </Button>
+              <Disabled disabled={isSubmitting || !botToken.trim()}>
+                <Button onClick={handleSaveToken}>
+                  {isSubmitting ? "Saving..." : "Save Token"}
+                </Button>
+              </Disabled>
             </Section>
           </Section>
         )}
diff --git a/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx b/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx
index a8a932c9bf4..0f8620471ac 100644
--- a/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx
+++ b/web/src/app/admin/discord-bot/DiscordGuildsTable.tsx
@@ -13,6 +13,7 @@ import {
 import { Badge } from "@/components/ui/badge";
 import { DeleteButton } from "@/components/DeleteButton";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Switch from "@/refresh-components/inputs/Switch";
 import { SvgEdit, SvgServer } from "@opal/icons";
 import EmptyMessage from "@/refresh-components/EmptyMessage";
@@ -115,14 +116,17 @@ export function DiscordGuildsTable({ guilds, onRefresh }: Props) {
           {guilds.map((guild) => (
             <TableRow key={guild.id}>
               <TableCell>
-                <Button
-                  prominence="internal"
-                  disabled={!guild.guild_id}
-                  onClick={() => router.push(`/admin/discord-bot/${guild.id}`)}
-                  icon={SvgEdit}
-                >
-                  {guild.guild_name || `Server #${guild.id}`}
-                </Button>
+                <Disabled disabled={!guild.guild_id}>
+                  <Button
+                    prominence="internal"
+                    onClick={() =>
+                      router.push(`/admin/discord-bot/${guild.id}`)
+                    }
+                    icon={SvgEdit}
+                  >
+                    {guild.guild_name || `Server #${guild.id}`}
+                  </Button>
+                </Disabled>
               </TableCell>
               <TableCell>
                 {guild.guild_id ? (
diff --git a/web/src/app/admin/discord-bot/[guild-id]/page.tsx b/web/src/app/admin/discord-bot/[guild-id]/page.tsx
index 44ce90ce4ad..d1ea7e5d340 100644
--- a/web/src/app/admin/discord-bot/[guild-id]/page.tsx
+++ b/web/src/app/admin/discord-bot/[guild-id]/page.tsx
@@ -13,6 +13,7 @@ import Card from "@/refresh-components/cards/Card";
 import { Callout } from "@/components/ui/callout";
 import Message from "@/refresh-components/messages/Message";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { SvgServer } from "@opal/icons";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import {
@@ -104,20 +105,16 @@ function GuildDetailContent({
                 width="fit"
                 gap={0.5}
               >
-                <Button
-                  prominence="secondary"
-                  onClick={handleEnableAll}
-                  disabled={disabled}
-                >
-                  Enable All
-                </Button>
-                <Button
-                  prominence="secondary"
-                  onClick={handleDisableAll}
-                  disabled={disabled}
-                >
-                  Disable All
-                </Button>
+                <Disabled disabled={disabled}>
+                  <Button prominence="secondary" onClick={handleEnableAll}>
+                    Enable All
+                  </Button>
+                </Disabled>
+                <Disabled disabled={disabled}>
+                  <Button prominence="secondary" onClick={handleDisableAll}>
+                    Disable All
+                  </Button>
+                </Disabled>
               </Section>
             ) : undefined
           }
@@ -338,9 +335,9 @@ export default function Page({ params }: Props) {
         description={registeredText}
         backButton
         rightChildren={
-          <Button onClick={handleSaveChanges} disabled={isUpdateDisabled}>
-            Update Configuration
-          </Button>
+          <Disabled disabled={isUpdateDisabled}>
+            <Button onClick={handleSaveChanges}>Update Configuration</Button>
+          </Disabled>
         }
       />
       <SettingsLayouts.Body>
diff --git a/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx b/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx
index dc2b9f8962b..d7916feceda 100644
--- a/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx
+++ b/web/src/app/admin/embeddings/modals/ProviderCreationModal.tsx
@@ -2,6 +2,7 @@ import React, { useRef, useState } from "react";
 import Text from "@/refresh-components/texts/Text";
 import { Callout } from "@/components/ui/callout";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { Formik, Form } from "formik";
 import * as Yup from "yup";
 import { Label, TextFormField } from "@/components/Field";
@@ -296,18 +297,19 @@ export default function ProviderCreationModal({
                   </Callout>
                 )}
 
-                <Button
-                  type="submit"
-                  width="full"
-                  disabled={isSubmitting}
-                  icon={isSubmitting ? SimpleLoader : undefined}
-                >
-                  {isSubmitting
-                    ? "Submitting"
-                    : existingProvider
-                      ? "Update"
-                      : "Create"}
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button
+                    type="submit"
+                    width="full"
+                    icon={isSubmitting ? SimpleLoader : undefined}
+                  >
+                    {isSubmitting
+                      ? "Submitting"
+                      : existingProvider
+                        ? "Update"
+                        : "Create"}
+                  </Button>
+                </Disabled>
               </Form>
             )}
           </Formik>
diff --git a/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx b/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
index 78469cb9c45..d2a520b508b 100644
--- a/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
+++ b/web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx
@@ -7,6 +7,7 @@ import { useCallback, useEffect, useMemo, useState, useRef } from "react";
 import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { WarningCircle, Warning, CaretDownIcon } from "@phosphor-icons/react";
 import {
   CloudEmbeddingModel,
@@ -376,15 +377,16 @@ export default function EmbeddingForm() {
         </div>
       ) : (
         <div className="flex mx-auto gap-x-1 ml-auto items-center">
-          <OpalButton
-            onClick={() => {
-              updateSearch();
-              navigateToEmbeddingPage("search settings");
-            }}
-            disabled={!isOverallFormValid}
-          >
-            Update Search
-          </OpalButton>
+          <Disabled disabled={!isOverallFormValid}>
+            <OpalButton
+              onClick={() => {
+                updateSearch();
+                navigateToEmbeddingPage("search settings");
+              }}
+            >
+              Update Search
+            </OpalButton>
+          </Disabled>
           {!isOverallFormValid &&
             Object.keys(combinedFormErrors).length > 0 && (
               <div className="relative group">
diff --git a/web/src/app/admin/kg/page.tsx b/web/src/app/admin/kg/page.tsx
index bea909aa178..3e381f8cb2f 100644
--- a/web/src/app/admin/kg/page.tsx
+++ b/web/src/app/admin/kg/page.tsx
@@ -10,6 +10,7 @@ import {
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import SwitchField from "@/refresh-components/form/SwitchField";
 import { Form, Formik, FormikState, useFormikContext } from "formik";
 import { useState } from "react";
@@ -199,9 +200,9 @@ function KGConfiguration({
                 disabled={!props.values.enabled}
               />
             </div>
-            <Button type="submit" disabled={!props.dirty}>
-              Submit
-            </Button>
+            <Disabled disabled={!props.dirty}>
+              <Button type="submit">Submit</Button>
+            </Disabled>
           </div>
         </Form>
       )}
diff --git a/web/src/app/admin/scim/ScimModal.tsx b/web/src/app/admin/scim/ScimModal.tsx
index 891f7e1fabc..4358506e5f7 100644
--- a/web/src/app/admin/scim/ScimModal.tsx
+++ b/web/src/app/admin/scim/ScimModal.tsx
@@ -2,6 +2,7 @@ import { SvgDownload, SvgKey, SvgRefreshCw } from "@opal/icons";
 import { Interactive } from "@opal/core";
 import { Section } from "@/layouts/general-layouts";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
@@ -54,13 +55,11 @@ export default function ScimModal({
           title="Regenerate SCIM Token"
           onClose={onClose}
           submit={
-            <Button
-              variant="danger"
-              onClick={onRegenerate}
-              disabled={isSubmitting}
-            >
-              Regenerate Token
-            </Button>
+            <Disabled disabled={isSubmitting}>
+              <Button variant="danger" onClick={onRegenerate}>
+                Regenerate Token
+              </Button>
+            </Disabled>
           }
         >
           <Section alignItems="start" gap={0.5}>
diff --git a/web/src/app/admin/scim/ScimSyncCard.tsx b/web/src/app/admin/scim/ScimSyncCard.tsx
index 9bd562c2ad5..9d9d630f47c 100644
--- a/web/src/app/admin/scim/ScimSyncCard.tsx
+++ b/web/src/app/admin/scim/ScimSyncCard.tsx
@@ -3,6 +3,7 @@ import { ContentAction } from "@opal/layouts";
 import { Section } from "@/layouts/general-layouts";
 import Card from "@/refresh-components/cards/Card";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import Separator from "@/refresh-components/Separator";
 import { timeAgo } from "@/lib/time";
@@ -53,13 +54,11 @@ export default function ScimSyncCard({
               Regenerate Token
             </Button>
           ) : (
-            <Button
-              rightIcon={SvgKey}
-              onClick={onGenerate}
-              disabled={isSubmitting}
-            >
-              Generate SCIM Token
-            </Button>
+            <Disabled disabled={isSubmitting}>
+              <Button rightIcon={SvgKey} onClick={onGenerate}>
+                Generate SCIM Token
+              </Button>
+            </Disabled>
           )
         }
       />
diff --git a/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx b/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx
index bb7bffcc49e..34e6582c5d6 100644
--- a/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx
+++ b/web/src/app/admin/token-rate-limits/CreateRateLimitModal.tsx
@@ -2,6 +2,7 @@
 
 import * as Yup from "yup";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { useEffect, useState } from "react";
 import Modal from "@/refresh-components/Modal";
 import { Form, Formik } from "formik";
@@ -147,9 +148,9 @@ export default function CreateRateLimitModal({
                   type="number"
                   placeholder=""
                 />
-                <Button type="submit" disabled={isSubmitting}>
-                  Create
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button type="submit">Create</Button>
+                </Disabled>
               </Form>
             )}
           </Formik>
diff --git a/web/src/app/admin/users/page.tsx b/web/src/app/admin/users/page.tsx
index de548157c58..5902b120325 100644
--- a/web/src/app/admin/users/page.tsx
+++ b/web/src/app/admin/users/page.tsx
@@ -19,6 +19,7 @@ import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
 import PendingUsersTable from "@/components/admin/users/PendingUsersTable";
 import CreateButton from "@/refresh-components/buttons/CreateButton";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { Spinner } from "@/components/Spinner";
 import { SvgDownloadCloud, SvgUserPlus } from "@opal/icons";
@@ -149,13 +150,14 @@ function UsersTables({
           <CardHeader>
             <div className="flex justify-between items-center gap-1">
               <CardTitle>Current Users</CardTitle>
-              <Button
-                icon={SvgDownloadCloud}
-                disabled={isDownloadingUsers}
-                onClick={() => downloadAllUsers()}
-              >
-                {isDownloadingUsers ? "Downloading..." : "Download CSV"}
-              </Button>
+              <Disabled disabled={isDownloadingUsers}>
+                <Button
+                  icon={SvgDownloadCloud}
+                  onClick={() => downloadAllUsers()}
+                >
+                  {isDownloadingUsers ? "Downloading..." : "Download CSV"}
+                </Button>
+              </Disabled>
             </div>
           </CardHeader>
           <CardContent>
diff --git a/web/src/app/app/message/MessageSwitcher.tsx b/web/src/app/app/message/MessageSwitcher.tsx
index d31a40b56b6..1664339a922 100644
--- a/web/src/app/app/message/MessageSwitcher.tsx
+++ b/web/src/app/app/message/MessageSwitcher.tsx
@@ -1,4 +1,5 @@
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
 const DISABLED_MESSAGE = "Wait for agent message to complete";
@@ -32,13 +33,14 @@ export default function MessageSwitcher({
       className="flex flex-row items-center gap-1"
       data-testid="MessageSwitcher/container"
     >
-      <Button
-        icon={SvgChevronLeft}
-        onClick={previous}
-        prominence="tertiary"
-        disabled={disableForStreaming}
-        tooltip={disableForStreaming ? DISABLED_MESSAGE : "Previous"}
-      />
+      <Disabled disabled={disableForStreaming}>
+        <Button
+          icon={SvgChevronLeft}
+          onClick={previous}
+          prominence="tertiary"
+          tooltip={disableForStreaming ? DISABLED_MESSAGE : "Previous"}
+        />
+      </Disabled>
 
       <div className="flex flex-row items-center justify-center">
         <Text as="p" text03 mainUiAction>
@@ -52,13 +54,14 @@ export default function MessageSwitcher({
         </Text>
       </div>
 
-      <Button
-        icon={SvgChevronRight}
-        onClick={next}
-        prominence="tertiary"
-        disabled={disableForStreaming}
-        tooltip={disableForStreaming ? DISABLED_MESSAGE : "Next"}
-      />
+      <Disabled disabled={disableForStreaming}>
+        <Button
+          icon={SvgChevronRight}
+          onClick={next}
+          prominence="tertiary"
+          tooltip={disableForStreaming ? DISABLED_MESSAGE : "Next"}
+        />
+      </Disabled>
     </div>
   );
 }
diff --git a/web/src/app/auth/forgot-password/page.tsx b/web/src/app/auth/forgot-password/page.tsx
index 452c0672b39..a8e83362f4f 100644
--- a/web/src/app/auth/forgot-password/page.tsx
+++ b/web/src/app/auth/forgot-password/page.tsx
@@ -6,6 +6,7 @@ import Title from "@/components/ui/title";
 import Text from "@/components/ui/text";
 import Link from "next/link";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { TextFormField } from "@/components/Field";
@@ -63,9 +64,11 @@ const ForgotPasswordPage: React.FC = () => {
               />
 
               <div className="flex">
-                <Button type="submit" disabled={isSubmitting} width="full">
-                  Reset Password
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button type="submit" width="full">
+                    Reset Password
+                  </Button>
+                </Disabled>
               </div>
             </Form>
           )}
diff --git a/web/src/app/auth/impersonate/page.tsx b/web/src/app/auth/impersonate/page.tsx
index a6c38da2f46..5b3d2c5f0cf 100644
--- a/web/src/app/auth/impersonate/page.tsx
+++ b/web/src/app/auth/impersonate/page.tsx
@@ -10,6 +10,7 @@ import * as Yup from "yup";
 import { toast } from "@/hooks/useToast";
 import { TextFormField } from "@/components/Field";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 
 const ImpersonateSchema = Yup.object().shape({
@@ -89,9 +90,11 @@ export default function ImpersonatePage() {
                 placeholder="Enter API Key"
               />
 
-              <Button type="submit" width="full" disabled={isSubmitting}>
-                Impersonate User
-              </Button>
+              <Disabled disabled={isSubmitting}>
+                <Button type="submit" width="full">
+                  Impersonate User
+                </Button>
+              </Disabled>
             </Form>
           )}
         </Formik>
diff --git a/web/src/app/auth/login/EmailPasswordForm.tsx b/web/src/app/auth/login/EmailPasswordForm.tsx
index fe30b4cc4b8..d37d788c7a2 100644
--- a/web/src/app/auth/login/EmailPasswordForm.tsx
+++ b/web/src/app/auth/login/EmailPasswordForm.tsx
@@ -3,6 +3,7 @@
 import { toast } from "@/hooks/useToast";
 import { basicLogin, basicSignup } from "@/lib/user";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { requestEmailVerification } from "../lib";
@@ -241,14 +242,15 @@ export default function EmailPasswordForm({
               />
 
               <Spacer rem={0.25} />
-              <Button
-                type="submit"
-                width="full"
-                disabled={isSubmitting || !isValid || !dirty}
-                rightIcon={SvgArrowRightCircle}
-              >
-                {isJoin ? "Join" : isSignup ? "Create Account" : "Sign In"}
-              </Button>
+              <Disabled disabled={isSubmitting || !isValid || !dirty}>
+                <Button
+                  type="submit"
+                  width="full"
+                  rightIcon={SvgArrowRightCircle}
+                >
+                  {isJoin ? "Join" : isSignup ? "Create Account" : "Sign In"}
+                </Button>
+              </Disabled>
               {user?.is_anonymous_user && (
                 <Link
                   href="/app"
diff --git a/web/src/app/auth/reset-password/page.tsx b/web/src/app/auth/reset-password/page.tsx
index 9feb9ca5d98..dac4ccc2676 100644
--- a/web/src/app/auth/reset-password/page.tsx
+++ b/web/src/app/auth/reset-password/page.tsx
@@ -6,6 +6,7 @@ import Title from "@/components/ui/title";
 import Text from "@/components/ui/text";
 import Link from "next/link";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { Form, Formik } from "formik";
 import * as Yup from "yup";
 import { TextFormField } from "@/components/Field";
@@ -99,9 +100,11 @@ const ResetPasswordPage: React.FC = () => {
               />
 
               <div className="flex">
-                <Button type="submit" disabled={isSubmitting} width="full">
-                  Reset Password
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button type="submit" width="full">
+                    Reset Password
+                  </Button>
+                </Disabled>
               </div>
             </Form>
           )}
diff --git a/web/src/app/craft/components/InputBar.tsx b/web/src/app/craft/components/InputBar.tsx
index 7011687f969..d6c190aa905 100644
--- a/web/src/app/craft/components/InputBar.tsx
+++ b/web/src/app/craft/components/InputBar.tsx
@@ -14,7 +14,7 @@ import {
 } from "react";
 import { useRouter } from "next/navigation";
 import { cn, isImageFile } from "@/lib/utils";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import {
   useUploadFilesContext,
   BuildFile,
@@ -373,13 +373,14 @@ const InputBar = memo(
               {/* Bottom left controls */}
               <div className="flex flex-row items-center gap-1">
                 {/* (+) button for file upload */}
-                <Button
-                  icon={SvgPaperclip}
-                  tooltip="Attach Files"
-                  prominence="tertiary"
-                  disabled={disabled}
-                  onClick={() => fileInputRef.current?.click()}
-                />
+                <Disabled disabled={disabled}>
+                  <Button
+                    icon={SvgPaperclip}
+                    tooltip="Attach Files"
+                    prominence="tertiary"
+                    onClick={() => fileInputRef.current?.click()}
+                  />
+                </Disabled>
                 {/* Demo Data indicator pill - only show on welcome page (no session) when demo data is enabled */}
                 {demoDataEnabled && isWelcomePage && (
                   <SimpleTooltip
@@ -387,17 +388,18 @@ const InputBar = memo(
                     side="top"
                   >
                     <span>
-                      <SelectButton
-                        leftIcon={SvgOrganization}
-                        engaged={demoDataEnabled}
-                        action
-                        folded
-                        disabled={disabled}
-                        onClick={() => router.push(CRAFT_CONFIGURE_PATH)}
-                        className="bg-action-link-01"
-                      >
-                        Demo Data Active
-                      </SelectButton>
+                      <Disabled disabled={disabled}>
+                        <SelectButton
+                          leftIcon={SvgOrganization}
+                          engaged={demoDataEnabled}
+                          action
+                          folded
+                          onClick={() => router.push(CRAFT_CONFIGURE_PATH)}
+                          className="bg-action-link-01"
+                        >
+                          Demo Data Active
+                        </SelectButton>
+                      </Disabled>
                     </span>
                   </SimpleTooltip>
                 )}
diff --git a/web/src/app/craft/components/SideBar.tsx b/web/src/app/craft/components/SideBar.tsx
index 559ae1eb532..13e7515f4ad 100644
--- a/web/src/app/craft/components/SideBar.tsx
+++ b/web/src/app/craft/components/SideBar.tsx
@@ -34,6 +34,7 @@ import {
 } from "@opal/icons";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import TypewriterText from "@/app/craft/components/TypewriterText";
 import {
@@ -271,22 +272,25 @@ function BuildSessionButton({
           twoTone={!isDeleting && !deleteSuccess && !deleteError}
           submit={
             deleteSuccess ? (
-              <Button variant="action" disabled icon={SvgCheckCircle}>
-                Done
-              </Button>
+              <Disabled disabled>
+                <Button variant="action" icon={SvgCheckCircle}>
+                  Done
+                </Button>
+              </Disabled>
             ) : deleteError ? (
               <Button variant="danger" onClick={closeModal}>
                 Close
               </Button>
             ) : (
-              <Button
-                variant="danger"
-                onClick={handleConfirmDelete}
-                disabled={isDeleting}
-                icon={isDeleting ? SimpleLoader : undefined}
-              >
-                {isDeleting ? "Deleting..." : "Delete"}
-              </Button>
+              <Disabled disabled={isDeleting}>
+                <Button
+                  variant="danger"
+                  onClick={handleConfirmDelete}
+                  icon={isDeleting ? SimpleLoader : undefined}
+                >
+                  {isDeleting ? "Deleting..." : "Delete"}
+                </Button>
+              </Disabled>
             )
           }
         >
diff --git a/web/src/app/craft/components/output-panel/UrlBar.tsx b/web/src/app/craft/components/output-panel/UrlBar.tsx
index 302ced200c8..c9131de83d6 100644
--- a/web/src/app/craft/components/output-panel/UrlBar.tsx
+++ b/web/src/app/craft/components/output-panel/UrlBar.tsx
@@ -4,6 +4,7 @@ import React from "react";
 import { cn } from "@/lib/utils";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   SvgDownloadCloud,
   SvgLoader,
@@ -153,15 +154,16 @@ export default function UrlBar({
         </div>
         {/* Export button — shown for downloadable file previews (e.g. markdown → docx) */}
         {onDownload && (
-          <Button
-            variant="action"
-            prominence="tertiary"
-            icon={isDownloading ? SpinningLoader : SvgExternalLink}
-            disabled={isDownloading}
-            onClick={onDownload}
-          >
-            {isDownloading ? "Exporting..." : "Export to .docx"}
-          </Button>
+          <Disabled disabled={isDownloading}>
+            <Button
+              variant="action"
+              prominence="tertiary"
+              icon={isDownloading ? SpinningLoader : SvgExternalLink}
+              onClick={onDownload}
+            >
+              {isDownloading ? "Exporting..." : "Export to .docx"}
+            </Button>
+          </Disabled>
         )}
         {/* Share button — shown when webapp preview is active */}
         {previewUrl && sessionId && (
diff --git a/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx b/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx
index 9128094c88a..0ef46382ad9 100644
--- a/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx
+++ b/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx
@@ -2,7 +2,7 @@
 
 import { SvgCheckCircle } from "@opal/icons";
 import { cn } from "@/lib/utils";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import SimpleTooltip from "@/refresh-components/SimpleTooltip";
 import { LLMProviderName, LLMProviderDescriptor } from "@/interfaces/llm";
diff --git a/web/src/app/craft/onboarding/components/OnboardingUserInfo.tsx b/web/src/app/craft/onboarding/components/OnboardingUserInfo.tsx
index 536880f64d2..b04264cad2e 100644
--- a/web/src/app/craft/onboarding/components/OnboardingUserInfo.tsx
+++ b/web/src/app/craft/onboarding/components/OnboardingUserInfo.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { cn } from "@/lib/utils";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import {
   WorkArea,
diff --git a/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx b/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx
index 2a551bb9a26..5d681002f71 100644
--- a/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx
+++ b/web/src/app/craft/v1/configure/components/ConnectorConfigStep.tsx
@@ -4,6 +4,7 @@ import { useState } from "react";
 import { Formik, Form, useFormikContext } from "formik";
 import { Section } from "@/layouts/general-layouts";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { toast } from "@/hooks/useToast";
 import { ValidSources } from "@/lib/types";
 import { Credential } from "@/lib/connectors/credentials";
@@ -95,16 +96,16 @@ function ConnectorConfigForm({
             />
           ))}
         <Section flexDirection="row" justifyContent="between" height="fit">
-          <Button
-            prominence="secondary"
-            onClick={onBack}
-            disabled={isSubmitting}
-          >
-            Back
-          </Button>
-          <Button type="button" onClick={handleSubmit} disabled={isSubmitting}>
-            {isSubmitting ? "Creating..." : "Create Connector"}
-          </Button>
+          <Disabled disabled={isSubmitting}>
+            <Button prominence="secondary" onClick={onBack}>
+              Back
+            </Button>
+          </Disabled>
+          <Disabled disabled={isSubmitting}>
+            <Button type="button" onClick={handleSubmit}>
+              {isSubmitting ? "Creating..." : "Create Connector"}
+            </Button>
+          </Disabled>
         </Section>
       </CardSection>
     </Form>
diff --git a/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx b/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx
index 4f6ddd46647..bff3ccbdb0e 100644
--- a/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx
+++ b/web/src/app/craft/v1/configure/components/CreateCredentialInline.tsx
@@ -6,6 +6,7 @@ import * as Yup from "yup";
 import { Section } from "@/layouts/general-layouts";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { TextFormField } from "@/components/Field";
 import { ValidSources } from "@/lib/types";
 import {
@@ -149,21 +150,20 @@ export default function CreateCredentialInline({
               gap={0.5}
               height="fit"
             >
-              <Button
-                variant="action"
-                prominence="secondary"
-                onClick={onCancel}
-                disabled={isSubmitting}
-              >
-                Cancel
-              </Button>
-              <Button
-                variant="action"
-                type="submit"
-                disabled={!isValid || !dirty || isSubmitting}
-              >
-                {isSubmitting ? "Creating..." : "Create Credential"}
-              </Button>
+              <Disabled disabled={isSubmitting}>
+                <Button
+                  variant="action"
+                  prominence="secondary"
+                  onClick={onCancel}
+                >
+                  Cancel
+                </Button>
+              </Disabled>
+              <Disabled disabled={!isValid || !dirty || isSubmitting}>
+                <Button variant="action" type="submit">
+                  {isSubmitting ? "Creating..." : "Create Credential"}
+                </Button>
+              </Disabled>
             </Section>
           </Section>
         </Form>
diff --git a/web/src/app/craft/v1/configure/components/CredentialStep.tsx b/web/src/app/craft/v1/configure/components/CredentialStep.tsx
index b3dccf52ae8..f9861c34dbd 100644
--- a/web/src/app/craft/v1/configure/components/CredentialStep.tsx
+++ b/web/src/app/craft/v1/configure/components/CredentialStep.tsx
@@ -3,6 +3,7 @@
 import { useState } from "react";
 import { Section } from "@/layouts/general-layouts";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Modal from "@/refresh-components/Modal";
 import { SvgKey } from "@opal/icons";
 import {
@@ -228,31 +229,31 @@ export default function CredentialStep({
                     connectorType as ConfigurableSources
                   ) &&
                     (NEXT_PUBLIC_CLOUD_ENABLED || NEXT_PUBLIC_TEST_ENV) && (
-                      <Button
-                        variant="action"
-                        onClick={handleAuthorize}
-                        disabled={isAuthorizing}
-                        hidden={!isAuthorizeVisible}
-                      >
-                        {isAuthorizing
-                          ? "Authorizing..."
-                          : `Authorize with ${getSourceDisplayName(
-                              connectorType
-                            )}`}
-                      </Button>
+                      <Disabled disabled={isAuthorizing}>
+                        <Button
+                          variant="action"
+                          onClick={handleAuthorize}
+                          hidden={!isAuthorizeVisible}
+                        >
+                          {isAuthorizing
+                            ? "Authorizing..."
+                            : `Authorize with ${getSourceDisplayName(
+                                connectorType
+                              )}`}
+                        </Button>
+                      </Disabled>
                     )}
                 </div>
                 {hasCredentials && (
-                  <Button
-                    onClick={isSingleStep ? handleConnect : onContinue}
-                    disabled={!selectedCredential || isConnecting}
-                  >
-                    {isSingleStep
-                      ? isConnecting
-                        ? "Connecting..."
-                        : "Connect"
-                      : "Continue"}
-                  </Button>
+                  <Disabled disabled={!selectedCredential || isConnecting}>
+                    <Button onClick={isSingleStep ? handleConnect : onContinue}>
+                      {isSingleStep
+                        ? isConnecting
+                          ? "Connecting..."
+                          : "Connect"
+                        : "Continue"}
+                    </Button>
+                  </Disabled>
                 )}
               </div>
             )}
diff --git a/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx b/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx
index 4009ded1f2c..72db7953b99 100644
--- a/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx
+++ b/web/src/app/craft/v1/configure/components/UserLibraryModal.tsx
@@ -13,6 +13,7 @@ import {
 import { LibraryEntry } from "@/app/craft/types/user-library";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Modal from "@/refresh-components/Modal";
 import ShadowDiv from "@/refresh-components/ShadowDiv";
 import { Section } from "@/layouts/general-layouts";
@@ -260,14 +261,15 @@ export default function UserLibraryModal({
                     disabled={isUploading}
                     accept=".xlsx,.xls,.docx,.doc,.pptx,.ppt,.csv,.json,.txt,.pdf,.zip"
                   />
-                  <Button
-                    prominence="secondary"
-                    icon={SvgUploadCloud}
-                    onClick={() => handleUploadToFolder("/")}
-                    disabled={isUploading}
-                    tooltip={isUploading ? "Uploading..." : "Upload"}
-                    aria-label={isUploading ? "Uploading..." : "Upload"}
-                  />
+                  <Disabled disabled={isUploading}>
+                    <Button
+                      prominence="secondary"
+                      icon={SvgUploadCloud}
+                      onClick={() => handleUploadToFolder("/")}
+                      tooltip={isUploading ? "Uploading..." : "Upload"}
+                      aria-label={isUploading ? "Uploading..." : "Upload"}
+                    />
+                  </Disabled>
                 </Section>
 
                 {isLoading ? (
@@ -381,12 +383,9 @@ export default function UserLibraryModal({
             >
               Cancel
             </Button>
-            <Button
-              onClick={handleCreateDirectory}
-              disabled={!newFolderName.trim()}
-            >
-              Create
-            </Button>
+            <Disabled disabled={!newFolderName.trim()}>
+              <Button onClick={handleCreateDirectory}>Create</Button>
+            </Disabled>
           </Modal.Footer>
         </Modal.Content>
       </Modal>
diff --git a/web/src/app/craft/v1/configure/page.tsx b/web/src/app/craft/v1/configure/page.tsx
index c3e399e8cc4..f33173cd3d3 100644
--- a/web/src/app/craft/v1/configure/page.tsx
+++ b/web/src/app/craft/v1/configure/page.tsx
@@ -36,6 +36,7 @@ import { ConfirmEntityModal } from "@/components/modals/ConfirmEntityModal";
 import { getSourceMetadata } from "@/lib/sources";
 import { deleteConnector } from "@/app/craft/services/apiServices";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   OAUTH_STATE_KEY,
   getDemoDataEnabled,
@@ -376,19 +377,18 @@ export default function BuildConfigPage() {
           description="Select data sources and your default LLM"
           rightChildren={
             <div className="flex items-center gap-2">
-              <Button
-                prominence="secondary"
-                onClick={handleRestoreChanges}
-                disabled={!hasChanges || isUpdating}
-              >
-                Restore Changes
-              </Button>
-              <Button
-                onClick={handleUpdate}
+              <Disabled disabled={!hasChanges || isUpdating}>
+                <Button prominence="secondary" onClick={handleRestoreChanges}>
+                  Restore Changes
+                </Button>
+              </Disabled>
+              <Disabled
                 disabled={!hasChanges || isUpdating || isPreProvisioning}
               >
-                {isUpdating || isPreProvisioning ? "Updating..." : "Update"}
-              </Button>
+                <Button onClick={handleUpdate}>
+                  {isUpdating || isPreProvisioning ? "Updating..." : "Update"}
+                </Button>
+              </Disabled>
             </div>
           }
         />
diff --git a/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx b/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx
index f1dc014dc93..75659532051 100644
--- a/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx
+++ b/web/src/app/ee/admin/groups/[groupId]/GroupDisplay.tsx
@@ -27,6 +27,7 @@ import {
 } from "@/components/ui/table";
 import SimpleTooltip from "@/refresh-components/SimpleTooltip";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { DeleteButton } from "@/components/DeleteButton";
 import { Bubble } from "@/components/Bubble";
 import { BookmarkIcon, RobotIcon } from "@/components/icons/icons";
@@ -278,16 +279,17 @@ export const GroupDisplay = ({
         tooltip="Cannot update group while sync is occurring"
         disabled={userGroup.is_up_to_date}
       >
-        <Button
-          disabled={!userGroup.is_up_to_date}
-          onClick={() => {
-            if (userGroup.is_up_to_date) {
-              setAddMemberFormVisible(true);
-            }
-          }}
-        >
-          Add Users
-        </Button>
+        <Disabled disabled={!userGroup.is_up_to_date}>
+          <Button
+            onClick={() => {
+              if (userGroup.is_up_to_date) {
+                setAddMemberFormVisible(true);
+              }
+            }}
+          >
+            Add Users
+          </Button>
+        </Disabled>
       </SimpleTooltip>
       {addMemberFormVisible && (
         <AddMemberForm
@@ -378,16 +380,17 @@ export const GroupDisplay = ({
         tooltip="Cannot update group while sync is occurring"
         disabled={userGroup.is_up_to_date}
       >
-        <Button
-          disabled={!userGroup.is_up_to_date}
-          onClick={() => {
-            if (userGroup.is_up_to_date) {
-              setAddConnectorFormVisible(true);
-            }
-          }}
-        >
-          Add Connectors
-        </Button>
+        <Disabled disabled={!userGroup.is_up_to_date}>
+          <Button
+            onClick={() => {
+              if (userGroup.is_up_to_date) {
+                setAddConnectorFormVisible(true);
+              }
+            }}
+          >
+            Add Connectors
+          </Button>
+        </Disabled>
       </SimpleTooltip>
 
       {addConnectorFormVisible && (
diff --git a/web/src/app/ee/admin/performance/usage/UsageReports.tsx b/web/src/app/ee/admin/performance/usage/UsageReports.tsx
index d7db896dc13..7b6c0604387 100644
--- a/web/src/app/ee/admin/performance/usage/UsageReports.tsx
+++ b/web/src/app/ee/admin/performance/usage/UsageReports.tsx
@@ -16,6 +16,7 @@ import Text from "@/components/ui/text";
 import Title from "@/components/ui/title";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import useSWR from "swr";
 import React, { useState } from "react";
 import { UsageReport } from "./types";
@@ -200,14 +201,15 @@ function GenerateReportInput({
           </Popover.Content>
         </Popover>
       </div>
-      <OpalButton
-        color={"blue"}
-        icon={SvgDownloadCloud}
-        disabled={isLoading || isWaitingForReport}
-        onClick={() => requestReport()}
-      >
-        {isWaitingForReport ? "Generating..." : "Generate Report"}
-      </OpalButton>
+      <Disabled disabled={isLoading || isWaitingForReport}>
+        <OpalButton
+          color={"blue"}
+          icon={SvgDownloadCloud}
+          onClick={() => requestReport()}
+        >
+          {isWaitingForReport ? "Generating..." : "Generate Report"}
+        </OpalButton>
+      </Disabled>
       <p className="mt-1 text-xs">
         {isWaitingForReport
           ? "A report is currently being generated. Please wait..."
diff --git a/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx b/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
index 5734f3cc151..b337dd1a905 100644
--- a/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
+++ b/web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
@@ -10,6 +10,7 @@ import Switch from "@/refresh-components/inputs/Switch";
 import CharacterCount from "@/refresh-components/CharacterCount";
 import InputImage from "@/refresh-components/inputs/InputImage";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { useFormikContext } from "formik";
 import {
   forwardRef,
@@ -312,14 +313,15 @@ export const AppearanceThemeSettings = forwardRef<
             />
           </FormField.Control>
           <div className="mt-2 w-full justify-center items-center flex">
-            <Button
-              prominence="secondary"
-              disabled={!hasLogo}
-              onClick={handleLogoEdit}
-              icon={SvgEdit}
-            >
-              Update
-            </Button>
+            <Disabled disabled={!hasLogo}>
+              <Button
+                prominence="secondary"
+                onClick={handleLogoEdit}
+                icon={SvgEdit}
+              >
+                Update
+              </Button>
+            </Disabled>
           </div>
         </FormField>
       </div>
diff --git a/web/src/app/ee/admin/theme/page.tsx b/web/src/app/ee/admin/theme/page.tsx
index 89264a89068..7b30aeaf99a 100644
--- a/web/src/app/ee/admin/theme/page.tsx
+++ b/web/src/app/ee/admin/theme/page.tsx
@@ -3,6 +3,7 @@
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   AppearanceThemeSettings,
   AppearanceThemeSettingsRef,
@@ -217,21 +218,26 @@ export default function ThemePage() {
                 description="Customize how the application appears to users across your organization."
                 icon={route.icon}
                 rightChildren={
-                  <Button
-                    type="button"
+                  <Disabled
                     disabled={isSubmitting || (!dirty && !hasLogoChange)}
-                    onClick={async () => {
-                      const errors = await validateForm();
-                      if (Object.keys(errors).length > 0) {
-                        setErrors(errors);
-                        appearanceSettingsRef.current?.focusFirstError(errors);
-                        return;
-                      }
-                      await submitForm();
-                    }}
                   >
-                    {isSubmitting ? "Applying..." : "Apply Changes"}
-                  </Button>
+                    <Button
+                      type="button"
+                      onClick={async () => {
+                        const errors = await validateForm();
+                        if (Object.keys(errors).length > 0) {
+                          setErrors(errors);
+                          appearanceSettingsRef.current?.focusFirstError(
+                            errors
+                          );
+                          return;
+                        }
+                        await submitForm();
+                      }}
+                    >
+                      {isSubmitting ? "Applying..." : "Apply Changes"}
+                    </Button>
+                  </Disabled>
                 }
               />
               <SettingsLayouts.Body>
diff --git a/web/src/components/DeleteButton.tsx b/web/src/components/DeleteButton.tsx
index c77760fe789..f2dd83e429e 100644
--- a/web/src/components/DeleteButton.tsx
+++ b/web/src/components/DeleteButton.tsx
@@ -1,5 +1,6 @@
 import { SvgTrash } from "@opal/icons";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 
 export interface DeleteButtonProps {
   onClick?: (event: React.MouseEvent<HTMLElement>) => void | Promise<void>;
@@ -8,13 +9,14 @@ export interface DeleteButtonProps {
 
 export function DeleteButton({ onClick, disabled }: DeleteButtonProps) {
   return (
-    <Button
-      onClick={onClick}
-      icon={SvgTrash}
-      tooltip="Delete"
-      disabled={disabled}
-      prominence="tertiary"
-      size="sm"
-    />
+    <Disabled disabled={disabled}>
+      <Button
+        onClick={onClick}
+        icon={SvgTrash}
+        tooltip="Delete"
+        prominence="tertiary"
+        size="sm"
+      />
+    </Disabled>
   );
 }
diff --git a/web/src/components/GenericMultiSelect.tsx b/web/src/components/GenericMultiSelect.tsx
index cc3731ba099..73650b02525 100644
--- a/web/src/components/GenericMultiSelect.tsx
+++ b/web/src/components/GenericMultiSelect.tsx
@@ -2,7 +2,7 @@ import { FormikProps, ErrorMessage } from "formik";
 import Text from "@/refresh-components/texts/Text";
 import Button from "@/refresh-components/buttons/Button";
 import InputComboBox from "@/refresh-components/inputs/InputComboBox/InputComboBox";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import { SvgX } from "@opal/icons";
 export type GenericMultiSelectFormType<T extends string> = {
   [K in T]: number[];
diff --git a/web/src/components/admin/users/buttons/InviteUserButton.tsx b/web/src/components/admin/users/buttons/InviteUserButton.tsx
index 4e9ee594d41..62865f7d71f 100644
--- a/web/src/components/admin/users/buttons/InviteUserButton.tsx
+++ b/web/src/components/admin/users/buttons/InviteUserButton.tsx
@@ -6,6 +6,7 @@ import {
 import { toast } from "@/hooks/useToast";
 import useSWRMutation from "swr/mutation";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import GenericConfirmModal from "@/components/modals/GenericConfirmModal";
 import { useState } from "react";
 
@@ -108,9 +109,11 @@ export const InviteUserButton = ({
         />
       )}
 
-      <Button onClick={() => setShowInviteModal(true)} disabled={isMutating}>
-        {invited ? "Uninvite" : "Invite"}
-      </Button>
+      <Disabled disabled={isMutating}>
+        <Button onClick={() => setShowInviteModal(true)}>
+          {invited ? "Uninvite" : "Invite"}
+        </Button>
+      </Disabled>
     </>
   );
 };
diff --git a/web/src/components/chat/MCPApiKeyModal.tsx b/web/src/components/chat/MCPApiKeyModal.tsx
index a17d90489a9..156836d38fb 100644
--- a/web/src/components/chat/MCPApiKeyModal.tsx
+++ b/web/src/components/chat/MCPApiKeyModal.tsx
@@ -7,6 +7,7 @@ import { Input } from "@/components/ui/input";
 import Label from "@/refresh-components/form/Label";
 import Text from "@/refresh-components/texts/Text";
 import { SvgAlertCircle, SvgEye, SvgEyeClosed, SvgKey } from "@opal/icons";
+import { Disabled } from "@opal/core";
 interface MCPAuthTemplate {
   headers: Array<{ name: string; value: string }>;
   request_body_params: Array<{ path: string; value: string }>;
@@ -250,15 +251,12 @@ export default function MCPApiKeyModal({
             )}
 
             <div className="flex justify-end space-x-2 pt-4">
-              <Button
-                prominence="secondary"
-                onClick={handleClose}
-                disabled={isSubmitting}
-              >
-                Cancel
-              </Button>
-              <Button
-                type="submit"
+              <Disabled disabled={isSubmitting}>
+                <Button prominence="secondary" onClick={handleClose}>
+                  Cancel
+                </Button>
+              </Disabled>
+              <Disabled
                 disabled={
                   isSubmitting ||
                   (isTemplateMode
@@ -268,12 +266,14 @@ export default function MCPApiKeyModal({
                     : !apiKey.trim())
                 }
               >
-                {isSubmitting
-                  ? "Saving..."
-                  : isAuthenticated
-                    ? `Update ${credsType}`
-                    : `Save ${credsType}`}
-              </Button>
+                <Button type="submit">
+                  {isSubmitting
+                    ? "Saving..."
+                    : isAuthenticated
+                      ? `Update ${credsType}`
+                      : `Save ${credsType}`}
+                </Button>
+              </Disabled>
             </div>
           </form>
         </Modal.Body>
diff --git a/web/src/components/credentials/actions/CreateCredential.tsx b/web/src/components/credentials/actions/CreateCredential.tsx
index 3235bb70d1b..585d07566ad 100644
--- a/web/src/components/credentials/actions/CreateCredential.tsx
+++ b/web/src/components/credentials/actions/CreateCredential.tsx
@@ -25,6 +25,7 @@ import { CredentialFieldsRenderer } from "./CredentialFieldsRenderer";
 import { TypedFile } from "@/lib/connectors/fileTypes";
 import ConnectorDocsLink from "@/components/admin/connectors/ConnectorDocsLink";
 import { SvgPlusCircle } from "@opal/icons";
+import { Disabled } from "@opal/core";
 const CreateButton = ({
   onClick,
   isSubmitting,
@@ -36,13 +37,11 @@ const CreateButton = ({
   isAdmin: boolean;
   groups: number[];
 }) => (
-  <OpalButton
-    onClick={onClick}
-    disabled={isSubmitting || (!isAdmin && groups.length === 0)}
-    icon={SvgPlusCircle}
-  >
-    Create
-  </OpalButton>
+  <Disabled disabled={isSubmitting || (!isAdmin && groups.length === 0)}>
+    <OpalButton onClick={onClick} icon={SvgPlusCircle}>
+      Create
+    </OpalButton>
+  </Disabled>
 );
 
 type formType = IsPublicGroupSelectorFormType & {
diff --git a/web/src/components/credentials/actions/EditCredential.tsx b/web/src/components/credentials/actions/EditCredential.tsx
index 28d66f14157..3eae2f2cd88 100644
--- a/web/src/components/credentials/actions/EditCredential.tsx
+++ b/web/src/components/credentials/actions/EditCredential.tsx
@@ -1,4 +1,5 @@
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/components/ui/text";
 
 import { FaNewspaper, FaTrash } from "react-icons/fa";
@@ -96,9 +97,11 @@ export default function EditCredential({
               <Button onClick={() => resetForm()} icon={SvgTrash}>
                 Reset Changes
               </Button>
-              <Button type="submit" disabled={isSubmitting} icon={FaNewspaper}>
-                Update
-              </Button>
+              <Disabled disabled={isSubmitting}>
+                <Button type="submit" icon={FaNewspaper}>
+                  Update
+                </Button>
+              </Disabled>
             </div>
           </Form>
         )}
diff --git a/web/src/components/credentials/actions/ModifyCredential.tsx b/web/src/components/credentials/actions/ModifyCredential.tsx
index 12d30e07868..136f3295cef 100644
--- a/web/src/components/credentials/actions/ModifyCredential.tsx
+++ b/web/src/components/credentials/actions/ModifyCredential.tsx
@@ -16,6 +16,7 @@ import {
   SvgTrash,
 } from "@opal/icons";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 interface CredentialSelectionTableProps {
   credentials: Credential<any>[];
   editableCredentials: Credential<any>[];
@@ -119,13 +120,14 @@ function CredentialSelectionTable({
                     {new Date(credential.time_updated).toLocaleString()}
                   </td>
                   <td className="p-2 flex gap-x-2 content-center mt-auto">
-                    <Button
-                      onClick={async () => {
-                        onDeleteCredential(credential);
-                      }}
-                      disabled={selected || !editable}
-                      icon={SvgTrash}
-                    />
+                    <Disabled disabled={selected || !editable}>
+                      <Button
+                        onClick={async () => {
+                          onDeleteCredential(credential);
+                        }}
+                        icon={SvgTrash}
+                      />
+                    </Disabled>
                     {onEditCredential && (
                       <button
                         disabled={!editable}
@@ -266,23 +268,28 @@ export default function ModifyCredential({
               <div />
             )}
 
-            <Button
-              disabled={selectedCredential == null}
-              onClick={() => {
-                if (onSwap && attachedConnector) {
-                  onSwap(selectedCredential!, attachedConnector.id, accessType);
-                  if (close) {
-                    close();
+            <Disabled disabled={selectedCredential == null}>
+              <Button
+                onClick={() => {
+                  if (onSwap && attachedConnector) {
+                    onSwap(
+                      selectedCredential!,
+                      attachedConnector.id,
+                      accessType
+                    );
+                    if (close) {
+                      close();
+                    }
+                  }
+                  if (onSwitch) {
+                    onSwitch(selectedCredential!);
                   }
-                }
-                if (onSwitch) {
-                  onSwitch(selectedCredential!);
-                }
-              }}
-              icon={SvgArrowExchange}
-            >
-              Select
-            </Button>
+                }}
+                icon={SvgArrowExchange}
+              >
+                Select
+              </Button>
+            </Disabled>
           </div>
         )}
       </div>
diff --git a/web/src/components/embedding/FailedReIndexAttempts.tsx b/web/src/components/embedding/FailedReIndexAttempts.tsx
index f86d1175c98..0e878cd0df8 100644
--- a/web/src/components/embedding/FailedReIndexAttempts.tsx
+++ b/web/src/components/embedding/FailedReIndexAttempts.tsx
@@ -20,6 +20,7 @@ import { FiLink, FiMaximize2, FiTrash } from "react-icons/fi";
 import { mutate } from "swr";
 import { toast } from "@/hooks/useToast";
 import { SvgTrash } from "@opal/icons";
+import { Disabled } from "@opal/core";
 export function FailedReIndexAttempts({
   failedIndexingStatuses,
 }: {
@@ -128,42 +129,44 @@ export function FailedReIndexAttempts({
                       </Link>
                     </TableCell>
                     <TableCell>
-                      <Button
-                        variant="danger"
-                        onClick={async () => {
-                          if (shouldConfirmConnectorDeletion) {
-                            setPendingConnectorDeletion({
-                              connectorId: reindexingProgress.connector_id,
-                              credentialId: reindexingProgress.credential_id,
-                              ccPairId: reindexingProgress.cc_pair_id,
-                              name: reindexingProgress.name ?? "this connector",
-                            });
-                            return;
-                          }
+                      <Disabled disabled={!reindexingProgress.is_deletable}>
+                        <Button
+                          variant="danger"
+                          onClick={async () => {
+                            if (shouldConfirmConnectorDeletion) {
+                              setPendingConnectorDeletion({
+                                connectorId: reindexingProgress.connector_id,
+                                credentialId: reindexingProgress.credential_id,
+                                ccPairId: reindexingProgress.cc_pair_id,
+                                name:
+                                  reindexingProgress.name ?? "this connector",
+                              });
+                              return;
+                            }
 
-                          try {
-                            await deleteCCPair(
-                              reindexingProgress.connector_id,
-                              reindexingProgress.credential_id,
-                              () =>
-                                mutate(
-                                  buildCCPairInfoUrl(
-                                    reindexingProgress.cc_pair_id
+                            try {
+                              await deleteCCPair(
+                                reindexingProgress.connector_id,
+                                reindexingProgress.credential_id,
+                                () =>
+                                  mutate(
+                                    buildCCPairInfoUrl(
+                                      reindexingProgress.cc_pair_id
+                                    )
                                   )
-                                )
-                            );
-                          } catch (error) {
-                            console.error("Error deleting connector:", error);
-                            toast.error(
-                              "Failed to delete connector. Please try again."
-                            );
-                          }
-                        }}
-                        icon={SvgTrash}
-                        disabled={!reindexingProgress.is_deletable}
-                      >
-                        Delete
-                      </Button>
+                              );
+                            } catch (error) {
+                              console.error("Error deleting connector:", error);
+                              toast.error(
+                                "Failed to delete connector. Please try again."
+                              );
+                            }
+                          }}
+                          icon={SvgTrash}
+                        >
+                          Delete
+                        </Button>
+                      </Disabled>
                     </TableCell>
                   </TableRow>
                 );
diff --git a/web/src/components/errorPages/AccessRestrictedPage.tsx b/web/src/components/errorPages/AccessRestrictedPage.tsx
index d6b3129b0c8..fba263ff4e5 100644
--- a/web/src/components/errorPages/AccessRestrictedPage.tsx
+++ b/web/src/components/errorPages/AccessRestrictedPage.tsx
@@ -4,6 +4,7 @@ import { useState } from "react";
 import Link from "next/link";
 import ErrorPageLayout from "@/components/errorPages/ErrorPageLayout";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import InlineExternalLink from "@/refresh-components/InlineExternalLink";
 import { logout } from "@/lib/user";
 import { loadStripe } from "@stripe/stripe-js";
@@ -136,9 +137,11 @@ export default function AccessRestricted() {
           </Text>
 
           <div className="flex flex-row gap-2">
-            <Button onClick={handleResubscribe} disabled={isLoading}>
-              {isLoading ? "Loading..." : "Resubscribe"}
-            </Button>
+            <Disabled disabled={isLoading}>
+              <Button onClick={handleResubscribe}>
+                {isLoading ? "Loading..." : "Resubscribe"}
+              </Button>
+            </Disabled>
             <Button
               prominence="secondary"
               onClick={async () => {
diff --git a/web/src/components/modals/CreateProjectModal.tsx b/web/src/components/modals/CreateProjectModal.tsx
index 9b9d4caef37..dc9980eb3a6 100644
--- a/web/src/components/modals/CreateProjectModal.tsx
+++ b/web/src/components/modals/CreateProjectModal.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useEffect } from "react";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { useProjectsContext } from "@/providers/ProjectsContext";
 import { useKeyPress } from "@/hooks/useKeyPress";
 import * as InputLayouts from "@/layouts/input-layouts";
@@ -68,9 +69,9 @@ export default function CreateProjectModal({
             <Button prominence="secondary" onClick={() => modal.toggle(false)}>
               Cancel
             </Button>
-            <Button disabled={!projectName.trim()} onClick={handleSubmit}>
-              Create Project
-            </Button>
+            <Disabled disabled={!projectName.trim()}>
+              <Button onClick={handleSubmit}>Create Project</Button>
+            </Disabled>
           </Modal.Footer>
         </Modal.Content>
       </Modal>
diff --git a/web/src/components/modals/EditPropertyModal.tsx b/web/src/components/modals/EditPropertyModal.tsx
index dd93300c51a..4d293be65d7 100644
--- a/web/src/components/modals/EditPropertyModal.tsx
+++ b/web/src/components/modals/EditPropertyModal.tsx
@@ -3,6 +3,7 @@ import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
 import { TextFormField } from "@/components/Field";
 import { SvgEdit } from "@opal/icons";
+import { Disabled } from "@opal/core";
 export interface EditPropertyModalProps {
   propertyTitle: string;
   propertyDetails?: string;
@@ -52,16 +53,17 @@ export default function EditPropertyModal({
                 />
 
                 <Modal.Footer>
-                  <Button
-                    type="submit"
+                  <Disabled
                     disabled={
                       isSubmitting ||
                       !isValid ||
                       values.propertyValue === propertyValue
                     }
                   >
-                    {isSubmitting ? "Updating..." : "Update property"}
-                  </Button>
+                    <Button type="submit">
+                      {isSubmitting ? "Updating..." : "Update property"}
+                    </Button>
+                  </Disabled>
                 </Modal.Footer>
               </Form>
             )}
diff --git a/web/src/components/modals/NewTeamModal.tsx b/web/src/components/modals/NewTeamModal.tsx
index 3b2a818ce0b..908051d7e40 100644
--- a/web/src/components/modals/NewTeamModal.tsx
+++ b/web/src/components/modals/NewTeamModal.tsx
@@ -5,6 +5,7 @@ import { useRouter, useSearchParams } from "next/navigation";
 import type { Route } from "next";
 import { Dialog } from "@headlessui/react";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { toast } from "@/hooks/useToast";
 import { useUser } from "@/providers/UserProvider";
 import { useModalContext } from "../context/ModalContext";
@@ -190,16 +191,17 @@ export default function NewTeamModal() {
                 Your join request can be approved by any admin of {appDomain}.
               </p>
               <div className="flex flex-col items-center justify-center gap-4 mt-4">
-                <Button
-                  onClick={handleRequestInvite}
-                  width="full"
-                  disabled={isSubmitting}
-                  icon={isSubmitting ? SimpleLoader : SvgArrowUp}
-                >
-                  {isSubmitting
-                    ? "Sending request..."
-                    : "Request to join your team"}
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button
+                    onClick={handleRequestInvite}
+                    width="full"
+                    icon={isSubmitting ? SimpleLoader : SvgArrowUp}
+                  >
+                    {isSubmitting
+                      ? "Sending request..."
+                      : "Request to join your team"}
+                  </Button>
+                </Disabled>
               </div>
               <Button
                 onClick={handleContinueToNewOrg}
diff --git a/web/src/components/modals/ProviderModal.tsx b/web/src/components/modals/ProviderModal.tsx
index 90ea974fce8..3faaf5d93e5 100644
--- a/web/src/components/modals/ProviderModal.tsx
+++ b/web/src/components/modals/ProviderModal.tsx
@@ -3,6 +3,7 @@ import { Button } from "@opal/components";
 import type { IconProps } from "@opal/types";
 import Modal from "@/refresh-components/Modal";
 import { SvgLoader } from "@opal/icons";
+import { Disabled } from "@opal/core";
 export interface ProviderModalProps {
   // Modal configurations
   clickOutsideToClose?: boolean;
@@ -83,14 +84,15 @@ export default function ProviderModal({
             >
               {cancelLabel}
             </Button>
-            <Button
-              type="button"
-              onClick={onSubmit}
-              disabled={submitDisabled || isSubmitting}
-              icon={isSubmitting ? SpinningLoader : undefined}
-            >
-              {submitLabel}
-            </Button>
+            <Disabled disabled={submitDisabled || isSubmitting}>
+              <Button
+                type="button"
+                onClick={onSubmit}
+                icon={isSubmitting ? SpinningLoader : undefined}
+              >
+                {submitLabel}
+              </Button>
+            </Disabled>
           </Modal.Footer>
         )}
       </Modal.Content>
diff --git a/web/src/components/modals/UserFilesModal.tsx b/web/src/components/modals/UserFilesModal.tsx
index 527ebb3df33..c718c98d606 100644
--- a/web/src/components/modals/UserFilesModal.tsx
+++ b/web/src/components/modals/UserFilesModal.tsx
@@ -25,6 +25,7 @@ import {
 import { Section } from "@/layouts/general-layouts";
 import useFilter from "@/hooks/useFilter";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import ScrollIndicatorDiv from "@/refresh-components/ScrollIndicatorDiv";
 
 function getIcon(
@@ -275,13 +276,14 @@ export default function UserFilesModal({
                   onClick={() => setShowOnlySelected(!showOnlySelected)}
                   interaction={showOnlySelected ? "hover" : "rest"}
                 />
-                <Button
-                  icon={SvgXCircle}
-                  prominence="tertiary"
-                  size="sm"
-                  onClick={handleDeselectAll}
-                  disabled={selectedCount === 0}
-                />
+                <Disabled disabled={selectedCount === 0}>
+                  <Button
+                    icon={SvgXCircle}
+                    prominence="tertiary"
+                    size="sm"
+                    onClick={handleDeselectAll}
+                  />
+                </Disabled>
               </Section>
             )}
 
diff --git a/web/src/layouts/general-layouts.tsx b/web/src/layouts/general-layouts.tsx
index 7d399abba3b..ac7c2ffccc1 100644
--- a/web/src/layouts/general-layouts.tsx
+++ b/web/src/layouts/general-layouts.tsx
@@ -112,20 +112,8 @@ export interface SectionProps
 }
 
 /**
- * WARNING: Do NOT wrap Section with the `<Disabled>` component.
- *
- * The `<Disabled>` component uses Radix Slot which injects a `className` prop.
- * Since `Section` spreads `...rest` after setting its own `className`, the injected
- * className will overwrite all layout classes (flex, flex-col, etc.), breaking the layout.
- *
- * To disable content within a Section, wrap the individual children instead:
- * ```tsx
- * <Section>
- *   <Disabled disabled={!isEnabled}>
- *     <Button>...</Button>
- *   </Disabled>
- * </Section>
- * ```
+ * `<Disabled>` from `@opal/core` uses `display: contents` — it can safely
+ * wrap a `Section` without affecting layout.
  */
 function Section({
   flexDirection = "column",
diff --git a/web/src/refresh-components/Disabled.tsx b/web/src/refresh-components/Disabled.tsx
deleted file mode 100644
index 193a5c2b85c..00000000000
--- a/web/src/refresh-components/Disabled.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import React from "react";
-import { Slot } from "@radix-ui/react-slot";
-import { cn } from "@/lib/utils";
-
-/**
- * Standard disabled styles used across the application.
- * - opacity-50: Visual feedback that the element is inactive
- * - cursor-not-allowed: Indicates the element cannot be interacted with
- * - pointer-events-none: Prevents all mouse/touch interactions
- * - select-none: Prevents text selection
- */
-const DISABLED_STYLES =
-  "opacity-50 cursor-not-allowed pointer-events-none select-none";
-
-/**
- * Disabled styles that still allow click interactions.
- * Use this for elements that need to show tooltips, error messages,
- * or other feedback when clicked while in a disabled state.
- * - opacity-50: Visual feedback that the element is inactive
- * - cursor-not-allowed: Indicates the element cannot be interacted with
- */
-const DISABLED_ALLOW_CLICK_STYLES = "opacity-50 cursor-not-allowed";
-
-export interface DisabledProps {
-  /**
-   * When true, applies disabled styling to the child element.
-   * When false or undefined, renders the child unchanged.
-   */
-  disabled?: boolean;
-  /**
-   * When true, allows click interactions while still appearing disabled.
-   * Useful for elements that need to show tooltips or error messages.
-   * @default false
-   */
-  allowClick?: boolean;
-  /**
-   * The child element to apply disabled styling to.
-   * Must be a single React element.
-   */
-  children: React.ReactElement;
-}
-
-/**
- * Disabled Component
- *
- * A pure wrapper component that standardizes disabled styling across the application.
- * Uses Radix Slot to merge props directly onto its child element without adding
- * an extra wrapper div.
- *
- * @example
- * ```tsx
- * // Basic usage - blocks all interactions
- * <Disabled disabled={!isEnabled}>
- *   <Card>
- *     <Text>This content is fully disabled</Text>
- *   </Card>
- * </Disabled>
- *
- * // Allow clicks for tooltips/feedback
- * <Disabled disabled={isDisabled} allowClick>
- *   <Button onClick={showTooltip}>Hover for info</Button>
- * </Disabled>
- * ```
- *
- * @remarks
- * - By default, applies: opacity-50, cursor-not-allowed, pointer-events-none, select-none
- * - With allowClick: applies only opacity-50, cursor-not-allowed (clicks still work)
- * - Sets aria-disabled attribute for accessibility
- * - Uses Radix Slot to avoid extra DOM nodes
- * - When disabled is false/undefined, renders child unchanged
- * - Forwards refs so it can be used as a tooltip trigger
- */
-const Disabled = React.forwardRef<
-  HTMLElement,
-  DisabledProps & React.HTMLAttributes<HTMLElement>
->(function Disabled({ disabled, allowClick = false, children, ...rest }, ref) {
-  // When not disabled, render child unchanged (still forward ref + props
-  // so parent Slots like TooltipTrigger asChild work correctly)
-  if (!disabled) {
-    return (
-      <Slot ref={ref} {...rest}>
-        {children}
-      </Slot>
-    );
-  }
-
-  const styles = allowClick ? DISABLED_ALLOW_CLICK_STYLES : DISABLED_STYLES;
-
-  return (
-    <Slot
-      ref={ref}
-      {...rest}
-      className={cn(
-        // Get existing className from child if present
-        (children.props as { className?: string }).className,
-        rest.className,
-        styles
-      )}
-      aria-disabled="true"
-    >
-      {children}
-    </Slot>
-  );
-});
-
-export { Disabled };
-export default Disabled;
diff --git a/web/src/refresh-components/Pagination.tsx b/web/src/refresh-components/Pagination.tsx
index 1b87db52859..a17092fbece 100644
--- a/web/src/refresh-components/Pagination.tsx
+++ b/web/src/refresh-components/Pagination.tsx
@@ -1,4 +1,5 @@
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
@@ -67,12 +68,13 @@ export default function Pagination({
   return (
     <Section flexDirection="row" gap={0.25}>
       {/* Previous button */}
-      <Button
-        onClick={() => onPageChange(currentPage - 1)}
-        disabled={currentPage === 1}
-        prominence="tertiary"
-        icon={SvgChevronLeft}
-      />
+      <Disabled disabled={currentPage === 1}>
+        <Button
+          onClick={() => onPageChange(currentPage - 1)}
+          prominence="tertiary"
+          icon={SvgChevronLeft}
+        />
+      </Disabled>
 
       {/* Page numbers */}
       <Section flexDirection="row" gap={0} width="fit">
@@ -105,12 +107,13 @@ export default function Pagination({
       </Section>
 
       {/* Next button */}
-      <Button
-        onClick={() => onPageChange(currentPage + 1)}
-        disabled={currentPage === totalPages}
-        prominence="tertiary"
-        icon={SvgChevronRight}
-      />
+      <Disabled disabled={currentPage === totalPages}>
+        <Button
+          onClick={() => onPageChange(currentPage + 1)}
+          prominence="tertiary"
+          icon={SvgChevronRight}
+        />
+      </Disabled>
     </Section>
   );
 }
diff --git a/web/src/refresh-components/Tabs.tsx b/web/src/refresh-components/Tabs.tsx
index a9a323caf28..bebc5c9045c 100644
--- a/web/src/refresh-components/Tabs.tsx
+++ b/web/src/refresh-components/Tabs.tsx
@@ -16,6 +16,7 @@ import { IconProps } from "@opal/types";
 import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
 import Text from "./texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 
 /* =============================================================================
    CONTEXT
@@ -503,22 +504,24 @@ const TabsList = React.forwardRef<
               ref={scrollArrowsRef}
               className="flex items-center gap-1 pl-2 flex-shrink-0"
             >
-              <Button
-                prominence="tertiary"
-                size="sm"
-                icon={SvgChevronLeft}
-                onClick={handleScrollLeft}
-                disabled={!canScrollLeft}
-                tooltip="Scroll tabs left"
-              />
-              <Button
-                prominence="tertiary"
-                size="sm"
-                icon={SvgChevronRight}
-                onClick={handleScrollRight}
-                disabled={!canScrollRight}
-                tooltip="Scroll tabs right"
-              />
+              <Disabled disabled={!canScrollLeft}>
+                <Button
+                  prominence="tertiary"
+                  size="sm"
+                  icon={SvgChevronLeft}
+                  onClick={handleScrollLeft}
+                  tooltip="Scroll tabs left"
+                />
+              </Disabled>
+              <Disabled disabled={!canScrollRight}>
+                <Button
+                  prominence="tertiary"
+                  size="sm"
+                  icon={SvgChevronRight}
+                  onClick={handleScrollRight}
+                  tooltip="Scroll tabs right"
+                />
+              </Disabled>
             </div>
           )}
 
diff --git a/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx b/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx
index 45d3eee5c82..321ffa332ab 100644
--- a/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx
+++ b/web/src/refresh-components/buttons/source-tag/SourceTagDetailsCard.tsx
@@ -3,6 +3,7 @@
 import React, { memo } from "react";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   SvgArrowLeft,
   SvgArrowRight,
@@ -90,20 +91,22 @@ const SourceTagDetailsCardInner = ({
       {showNavigation && (
         <div className="flex items-center justify-between p-2 bg-background-tint-01 border-b border-border-01">
           <div className="flex items-center gap-1">
-            <Button
-              prominence="internal"
-              icon={SvgArrowLeft}
-              onClick={onPrev}
-              disabled={isFirst}
-              size="sm"
-            />
-            <Button
-              prominence="internal"
-              icon={SvgArrowRight}
-              onClick={onNext}
-              disabled={isLast}
-              size="sm"
-            />
+            <Disabled disabled={isFirst}>
+              <Button
+                prominence="internal"
+                icon={SvgArrowLeft}
+                onClick={onPrev}
+                size="sm"
+              />
+            </Disabled>
+            <Disabled disabled={isLast}>
+              <Button
+                prominence="internal"
+                icon={SvgArrowRight}
+                onClick={onNext}
+                size="sm"
+              />
+            </Disabled>
           </div>
           <Text secondaryBody text03 className="px-1">
             {currentIndex + 1}/{sources.length}
diff --git a/web/src/refresh-components/cards/Select.tsx b/web/src/refresh-components/cards/Select.tsx
index 11a32bcc186..7d5854bbf0f 100644
--- a/web/src/refresh-components/cards/Select.tsx
+++ b/web/src/refresh-components/cards/Select.tsx
@@ -3,7 +3,7 @@
 import React, { useState } from "react";
 import type { IconProps } from "@opal/types";
 import { cn, noProp } from "@/lib/utils";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
 import SelectButton from "@/refresh-components/buttons/SelectButton";
@@ -124,39 +124,42 @@ export default function Select({
         <div className="flex items-center justify-end gap-1">
           {/* Disconnected: Show Connect button */}
           {isDisconnected && (
-            <Button
-              prominence="tertiary"
-              disabled={disabled || !onConnect}
-              onClick={noProp(onConnect)}
-              rightIcon={SvgArrowExchange}
-            >
-              {connectLabel}
-            </Button>
+            <Disabled disabled={disabled || !onConnect}>
+              <Button
+                prominence="tertiary"
+                onClick={noProp(onConnect)}
+                rightIcon={SvgArrowExchange}
+              >
+                {connectLabel}
+              </Button>
+            </Disabled>
           )}
 
           {/* Connected: Show select icon + settings icon */}
           {isConnected && (
             <>
-              <SelectButton
-                action
-                folded
-                transient={isHovered}
-                disabled={disabled || !onSelect}
-                onClick={onSelect}
-                rightIcon={SvgArrowRightCircle}
-              >
-                {selectLabel}
-              </SelectButton>
+              <Disabled disabled={disabled || !onSelect}>
+                <SelectButton
+                  action
+                  folded
+                  transient={isHovered}
+                  onClick={onSelect}
+                  rightIcon={SvgArrowRightCircle}
+                >
+                  {selectLabel}
+                </SelectButton>
+              </Disabled>
               {onEdit && (
-                <Button
-                  icon={SvgSettings}
-                  tooltip="Edit"
-                  prominence="tertiary"
-                  size="sm"
-                  disabled={disabled}
-                  onClick={noProp(onEdit)}
-                  aria-label={`Edit ${title}`}
-                />
+                <Disabled disabled={disabled}>
+                  <Button
+                    icon={SvgSettings}
+                    tooltip="Edit"
+                    prominence="tertiary"
+                    size="sm"
+                    onClick={noProp(onEdit)}
+                    aria-label={`Edit ${title}`}
+                  />
+                </Disabled>
               )}
             </>
           )}
@@ -164,25 +167,27 @@ export default function Select({
           {/* Selected: Show "Current Default" label + settings icon */}
           {isSelected && (
             <>
-              <SelectButton
-                action
-                engaged
-                disabled={disabled}
-                onClick={onDeselect}
-                leftIcon={SvgCheckSquare}
-              >
-                {selectedLabel}
-              </SelectButton>
+              <Disabled disabled={disabled}>
+                <SelectButton
+                  action
+                  engaged
+                  onClick={onDeselect}
+                  leftIcon={SvgCheckSquare}
+                >
+                  {selectedLabel}
+                </SelectButton>
+              </Disabled>
               {onEdit && (
-                <Button
-                  icon={SvgSettings}
-                  tooltip="Edit"
-                  prominence="tertiary"
-                  size="sm"
-                  disabled={disabled}
-                  onClick={noProp(onEdit)}
-                  aria-label={`Edit ${title}`}
-                />
+                <Disabled disabled={disabled}>
+                  <Button
+                    icon={SvgSettings}
+                    tooltip="Edit"
+                    prominence="tertiary"
+                    size="sm"
+                    onClick={noProp(onEdit)}
+                    aria-label={`Edit ${title}`}
+                  />
+                </Disabled>
               )}
             </>
           )}
diff --git a/web/src/refresh-components/form/InputTypeInElementField.tsx b/web/src/refresh-components/form/InputTypeInElementField.tsx
index a034ca7e2b0..24c164a1ea7 100644
--- a/web/src/refresh-components/form/InputTypeInElementField.tsx
+++ b/web/src/refresh-components/form/InputTypeInElementField.tsx
@@ -5,6 +5,7 @@ import InputTypeIn, {
   InputTypeInProps,
 } from "@/refresh-components/inputs/InputTypeIn";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { SvgMinusCircle } from "@opal/icons";
 import { useOnChangeEvent, useOnBlurEvent } from "@/hooks/formHooks";
 import { Section } from "@/layouts/general-layouts";
@@ -50,13 +51,14 @@ export default function InputTypeInElementField({
         }
         showClearButton={false}
       />
-      <Button
-        icon={SvgMinusCircle}
-        prominence="tertiary"
-        disabled={!onRemove || isEmpty}
-        onClick={onRemove}
-        tooltip="Remove"
-      />
+      <Disabled disabled={!onRemove || isEmpty}>
+        <Button
+          icon={SvgMinusCircle}
+          prominence="tertiary"
+          onClick={onRemove}
+          tooltip="Remove"
+        />
+      </Disabled>
     </Section>
   );
 }
diff --git a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
index 3f2c5e8b91d..bc7828baa94 100644
--- a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
+++ b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
@@ -95,6 +95,7 @@ import { cn, noProp } from "@/lib/utils";
 import InputTypeIn from "../InputTypeIn";
 import { FieldContext } from "../../form/FieldContext";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { FieldMessage } from "../../messages/FieldMessage";
 
 // Hooks
@@ -394,16 +395,17 @@ const InputComboBox = ({
                 </div>
               )}
               {hasOptions && (
-                <Button
-                  prominence="tertiary"
-                  size="sm"
-                  onClick={noProp(toggleDropdown)}
-                  disabled={disabled}
-                  icon={isOpen ? SvgChevronUp : SvgChevronDown}
-                  aria-label={isOpen ? "Close dropdown" : "Open dropdown"}
-                  tabIndex={-1}
-                  type="button"
-                />
+                <Disabled disabled={disabled}>
+                  <Button
+                    prominence="tertiary"
+                    size="sm"
+                    onClick={noProp(toggleDropdown)}
+                    icon={isOpen ? SvgChevronUp : SvgChevronDown}
+                    aria-label={isOpen ? "Close dropdown" : "Open dropdown"}
+                    tabIndex={-1}
+                    type="button"
+                  />
+                </Disabled>
               )}
             </>
           }
diff --git a/web/src/refresh-components/inputs/InputDatePicker.tsx b/web/src/refresh-components/inputs/InputDatePicker.tsx
index 7c57d835358..2aee1b380df 100644
--- a/web/src/refresh-components/inputs/InputDatePicker.tsx
+++ b/web/src/refresh-components/inputs/InputDatePicker.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Calendar from "@/refresh-components/Calendar";
 import Popover from "@/refresh-components/Popover";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
@@ -40,9 +41,11 @@ export default function InputDatePicker({
   return (
     <Popover open={open} onOpenChange={setOpen}>
       <Popover.Trigger asChild id={name} name={name}>
-        <Button prominence="secondary" icon={SvgCalendar} disabled={disabled}>
-          {selectedDate ? selectedDate.toLocaleDateString() : "Select Date"}
-        </Button>
+        <Disabled disabled={disabled}>
+          <Button prominence="secondary" icon={SvgCalendar}>
+            {selectedDate ? selectedDate.toLocaleDateString() : "Select Date"}
+          </Button>
+        </Disabled>
       </Popover.Trigger>
       <Popover.Content>
         <Section padding={0.25}>
diff --git a/web/src/refresh-components/inputs/InputFile.tsx b/web/src/refresh-components/inputs/InputFile.tsx
index 6a909719ea2..e7c167b70b6 100644
--- a/web/src/refresh-components/inputs/InputFile.tsx
+++ b/web/src/refresh-components/inputs/InputFile.tsx
@@ -5,6 +5,7 @@ import InputTypeIn, {
   InputTypeInProps,
 } from "@/refresh-components/inputs/InputTypeIn";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { noProp } from "@/lib/utils";
 import { SvgPaperclip } from "@opal/icons";
 
@@ -127,15 +128,16 @@ export default function InputFile({
   }
 
   const rightSection = (
-    <Button
-      icon={SvgPaperclip}
-      disabled={isNonEditable}
-      onClick={noProp(openFilePicker)}
-      type="button"
-      prominence="tertiary"
-      size="sm"
-      aria-label="Attach file"
-    />
+    <Disabled disabled={isNonEditable}>
+      <Button
+        icon={SvgPaperclip}
+        onClick={noProp(openFilePicker)}
+        type="button"
+        prominence="tertiary"
+        size="sm"
+        aria-label="Attach file"
+      />
+    </Disabled>
   );
 
   return (
diff --git a/web/src/refresh-components/inputs/InputKeyValue.tsx b/web/src/refresh-components/inputs/InputKeyValue.tsx
index e326a56c88b..bdb46e5b797 100644
--- a/web/src/refresh-components/inputs/InputKeyValue.tsx
+++ b/web/src/refresh-components/inputs/InputKeyValue.tsx
@@ -79,6 +79,7 @@ import React, {
 import { cn } from "@/lib/utils";
 import InputTypeIn from "./InputTypeIn";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import { FieldContext } from "../form/FieldContext";
 import { FieldMessage } from "../messages/FieldMessage";
@@ -177,16 +178,17 @@ const KeyValueInputItem = ({
         </div>
       </div>
       <div className="flex items-start pt-[2px]">
-        <Button
-          prominence="tertiary"
-          size="sm"
-          icon={SvgMinusCircle}
-          onClick={onRemove}
-          disabled={disabled || !canRemove}
-          aria-label={`Remove ${keyPlaceholder || "key-value"} pair ${
-            index + 1
-          }`}
-        />
+        <Disabled disabled={disabled || !canRemove}>
+          <Button
+            prominence="tertiary"
+            size="sm"
+            icon={SvgMinusCircle}
+            onClick={onRemove}
+            aria-label={`Remove ${keyPlaceholder || "key-value"} pair ${
+              index + 1
+            }`}
+          />
+        </Disabled>
       </div>
     </div>
   );
@@ -487,16 +489,17 @@ const KeyValueInput = ({
       )}
 
       <div>
-        <Button
-          prominence="secondary"
-          onClick={handleAdd}
-          disabled={disabled}
-          icon={SvgPlusCircle}
-          aria-label={`Add ${keyTitle} and ${valueTitle} pair`}
-          type="button"
-        >
-          {addButtonLabel}
-        </Button>
+        <Disabled disabled={disabled}>
+          <Button
+            prominence="secondary"
+            onClick={handleAdd}
+            icon={SvgPlusCircle}
+            aria-label={`Add ${keyTitle} and ${valueTitle} pair`}
+            type="button"
+          >
+            {addButtonLabel}
+          </Button>
+        </Disabled>
       </div>
     </div>
   );
diff --git a/web/src/refresh-components/inputs/InputNumber.tsx b/web/src/refresh-components/inputs/InputNumber.tsx
index 204888bc128..bceff7472b3 100644
--- a/web/src/refresh-components/inputs/InputNumber.tsx
+++ b/web/src/refresh-components/inputs/InputNumber.tsx
@@ -3,6 +3,7 @@
 import * as React from "react";
 import { cn } from "@/lib/utils";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   Variants,
   wrapperClasses,
@@ -162,12 +163,13 @@ export default function InputNumber({
 
       <div className="flex flex-row items-center gap-1">
         {showReset && (
-          <Button
-            icon={SvgRevert}
-            onClick={handleReset}
-            disabled={!canReset || isDisabled}
-            prominence="tertiary"
-          />
+          <Disabled disabled={!canReset || isDisabled}>
+            <Button
+              icon={SvgRevert}
+              onClick={handleReset}
+              prominence="tertiary"
+            />
+          </Disabled>
         )}
         <div className="flex flex-col">
           <button
diff --git a/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx b/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx
index f43a8369a30..d2f7849b596 100644
--- a/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx
+++ b/web/src/refresh-components/inputs/PasswordInputTypeIn.tsx
@@ -5,6 +5,7 @@ import InputTypeIn, {
   InputTypeInProps,
 } from "@/refresh-components/inputs/InputTypeIn";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { noProp } from "@/lib/utils";
 import { SvgEye, SvgEyeClosed } from "@opal/icons";
 
@@ -305,18 +306,19 @@ export default function PasswordInputTypeIn({
         data-ph-no-capture
         rightSection={
           showToggleButton ? (
-            <Button
-              icon={isRevealed ? SvgEye : SvgEyeClosed}
-              disabled={disabled || effectiveNonRevealable}
-              onClick={noProp(() => setIsPasswordVisible((v) => !v))}
-              type="button"
-              variant={isRevealed ? "action" : undefined}
-              prominence="tertiary"
-              size="sm"
-              tooltipSide="left"
-              tooltip={toggleLabel}
-              aria-label={toggleLabel}
-            />
+            <Disabled disabled={disabled || effectiveNonRevealable}>
+              <Button
+                icon={isRevealed ? SvgEye : SvgEyeClosed}
+                onClick={noProp(() => setIsPasswordVisible((v) => !v))}
+                type="button"
+                variant={isRevealed ? "action" : undefined}
+                prominence="tertiary"
+                size="sm"
+                tooltipSide="left"
+                tooltip={toggleLabel}
+                aria-label={toggleLabel}
+              />
+            </Disabled>
           ) : undefined
         }
         {...props}
diff --git a/web/src/refresh-components/modals/MemoriesModal.tsx b/web/src/refresh-components/modals/MemoriesModal.tsx
index 26bf1f418bc..95a89c5a655 100644
--- a/web/src/refresh-components/modals/MemoriesModal.tsx
+++ b/web/src/refresh-components/modals/MemoriesModal.tsx
@@ -7,6 +7,7 @@ import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import InputTextArea from "@/refresh-components/inputs/InputTextArea";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import CharacterCount from "@/refresh-components/CharacterCount";
 import Separator from "@/refresh-components/Separator";
 import TextSeparator from "@/refresh-components/TextSeparator";
@@ -101,14 +102,15 @@ function MemoryItem({
             resizable={false}
             className={cn(!isFocused && "bg-transparent")}
           />
-          <Button
-            prominence="tertiary"
-            icon={SvgMinusCircle}
-            onClick={() => void onRemove(originalIndex)}
-            disabled={!memory.content.trim() && memory.isNew}
-            aria-label="Remove Line"
-            tooltip="Remove Line"
-          />
+          <Disabled disabled={!memory.content.trim() && memory.isNew}>
+            <Button
+              prominence="tertiary"
+              icon={SvgMinusCircle}
+              onClick={() => void onRemove(originalIndex)}
+              aria-label="Remove Line"
+              tooltip="Remove Line"
+            />
+          </Disabled>
         </Section>
         {isFocused && (
           <CharacterCount value={memory.content} limit={MAX_MEMORY_LENGTH} />
@@ -240,19 +242,20 @@ export default function MemoriesModal({
               showClearButton={false}
               className="w-full !bg-transparent !border-transparent [&:is(:hover,:active,:focus,:focus-within)]:!bg-background-neutral-00 [&:is(:hover)]:!border-border-01 [&:is(:focus,:focus-within)]:!shadow-none"
             />
-            <Button
-              prominence="tertiary"
-              onClick={onAddLine}
-              rightIcon={SvgPlusCircle}
-              disabled={!canAddMemory}
-              title={
-                !canAddMemory
-                  ? `Maximum of ${MAX_MEMORY_COUNT} memories reached`
-                  : undefined
-              }
-            >
-              Add Line
-            </Button>
+            <Disabled disabled={!canAddMemory}>
+              <Button
+                prominence="tertiary"
+                onClick={onAddLine}
+                rightIcon={SvgPlusCircle}
+                title={
+                  !canAddMemory
+                    ? `Maximum of ${MAX_MEMORY_COUNT} memories reached`
+                    : undefined
+                }
+              >
+                Add Line
+              </Button>
+            </Disabled>
           </Section>
         </Modal.Header>
 
diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index 105ddfe399e..5895f2e711c 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -41,6 +41,7 @@ import MCPLineItem, {
 import { useProjectsContext } from "@/providers/ProjectsContext";
 import { SvgActions, SvgChevronRight, SvgKey, SvgSliders } from "@opal/icons";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 
 function buildTooltipMessage(
   actionDescription: string,
@@ -1027,13 +1028,14 @@ export default function ActionsPopover({
       <Popover open={open} onOpenChange={handleOpenChange}>
         <Popover.Trigger asChild>
           <div data-testid="action-management-toggle">
-            <Button
-              icon={SvgSliders}
-              interaction={open ? "hover" : "rest"}
-              prominence="tertiary"
-              tooltip="Manage Actions"
-              disabled={disabled}
-            />
+            <Disabled disabled={disabled}>
+              <Button
+                icon={SvgSliders}
+                interaction={open ? "hover" : "rest"}
+                prominence="tertiary"
+                tooltip="Manage Actions"
+              />
+            </Disabled>
           </div>
         </Popover.Trigger>
         <Popover.Content side="bottom" align="start" width="lg">
diff --git a/web/src/refresh-components/popovers/LLMPopover.tsx b/web/src/refresh-components/popovers/LLMPopover.tsx
index f8e86646be7..a1dee7fa639 100644
--- a/web/src/refresh-components/popovers/LLMPopover.tsx
+++ b/web/src/refresh-components/popovers/LLMPopover.tsx
@@ -29,6 +29,7 @@ import {
 } from "@opal/icons";
 import { Section } from "@/layouts/general-layouts";
 import { OpenButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { LLMOption, LLMOptionGroup } from "./interfaces";
 
 export interface LLMPopoverProps {
@@ -355,19 +356,20 @@ export default function LLMPopover({
     <Popover open={open} onOpenChange={setOpen}>
       <div data-testid="llm-popover-trigger">
         <Popover.Trigger asChild disabled={disabled}>
-          <OpenButton
-            icon={
-              folded
-                ? SvgRefreshCw
-                : getProviderIcon(
-                    llmManager.currentLlm.provider,
-                    llmManager.currentLlm.modelName
-                  )
-            }
-            disabled={disabled}
-          >
-            {currentLlmDisplayName}
-          </OpenButton>
+          <Disabled disabled={disabled}>
+            <OpenButton
+              icon={
+                folded
+                  ? SvgRefreshCw
+                  : getProviderIcon(
+                      llmManager.currentLlm.provider,
+                      llmManager.currentLlm.modelName
+                    )
+              }
+            >
+              {currentLlmDisplayName}
+            </OpenButton>
+          </Disabled>
         </Popover.Trigger>
       </div>
 
diff --git a/web/src/refresh-components/table/Pagination.tsx b/web/src/refresh-components/table/Pagination.tsx
index d70f2cb8f98..966049518fc 100644
--- a/web/src/refresh-components/table/Pagination.tsx
+++ b/web/src/refresh-components/table/Pagination.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
@@ -156,23 +157,25 @@ function NavButtons({
 }: NavButtonsProps) {
   return (
     <>
-      <Button
-        icon={SvgChevronLeft}
-        onClick={() => onPageChange(currentPage - 1)}
-        disabled={currentPage <= 1}
-        size={size}
-        prominence="tertiary"
-        tooltip="Previous page"
-      />
+      <Disabled disabled={currentPage <= 1}>
+        <Button
+          icon={SvgChevronLeft}
+          onClick={() => onPageChange(currentPage - 1)}
+          size={size}
+          prominence="tertiary"
+          tooltip="Previous page"
+        />
+      </Disabled>
       {children}
-      <Button
-        icon={SvgChevronRight}
-        onClick={() => onPageChange(currentPage + 1)}
-        disabled={currentPage >= totalPages}
-        size={size}
-        prominence="tertiary"
-        tooltip="Next page"
-      />
+      <Disabled disabled={currentPage >= totalPages}>
+        <Button
+          icon={SvgChevronRight}
+          onClick={() => onPageChange(currentPage + 1)}
+          size={size}
+          prominence="tertiary"
+          tooltip="Next page"
+        />
+      </Disabled>
     </>
   );
 }
diff --git a/web/src/refresh-components/tiles/ButtonTile.tsx b/web/src/refresh-components/tiles/ButtonTile.tsx
index a6f1a12f93e..f0dfa8b49e5 100644
--- a/web/src/refresh-components/tiles/ButtonTile.tsx
+++ b/web/src/refresh-components/tiles/ButtonTile.tsx
@@ -2,7 +2,7 @@ import type { FunctionComponent } from "react";
 
 import { cn } from "@/lib/utils";
 import Text from "@/refresh-components/texts/Text";
-import { Interactive } from "@opal/core";
+import { Disabled, Interactive } from "@opal/core";
 import type { IconProps } from "@opal/types";
 
 // ---------------------------------------------------------------------------
@@ -31,47 +31,48 @@ export default function ButtonTile({
   const Icon = icon;
 
   return (
-    <Interactive.Stateless
-      variant="default"
-      prominence="secondary"
-      group="group/Tile"
-      onClick={onClick}
-      disabled={disabled}
-    >
-      <div className={cn("rounded-08 p-1.5", "flex flex-row gap-2")}>
-        {(title || description) && (
-          <div className="min-w-0 flex flex-col px-0.5">
-            {title && (
-              <Text
-                secondaryAction
-                text02={disabled}
-                text04={!disabled}
-                className="truncate"
-              >
-                {title}
-              </Text>
-            )}
-            {description && (
-              <Text secondaryBody text02={disabled} text03={!disabled}>
-                {description}
-              </Text>
-            )}
-          </div>
-        )}
-
-        {Icon && (
-          <div className="flex items-start justify-center">
-            <Icon
-              size={16}
-              className={cn(
-                disabled
-                  ? "stroke-text-01"
-                  : "stroke-text-03 group-hover/Tile:stroke-text-04"
+    <Disabled disabled={disabled}>
+      <Interactive.Stateless
+        variant="default"
+        prominence="secondary"
+        group="group/Tile"
+        onClick={onClick}
+      >
+        <div className={cn("rounded-08 p-1.5", "flex flex-row gap-2")}>
+          {(title || description) && (
+            <div className="min-w-0 flex flex-col px-0.5">
+              {title && (
+                <Text
+                  secondaryAction
+                  text02={disabled}
+                  text04={!disabled}
+                  className="truncate"
+                >
+                  {title}
+                </Text>
+              )}
+              {description && (
+                <Text secondaryBody text02={disabled} text03={!disabled}>
+                  {description}
+                </Text>
               )}
-            />
-          </div>
-        )}
-      </div>
-    </Interactive.Stateless>
+            </div>
+          )}
+
+          {Icon && (
+            <div className="flex items-start justify-center">
+              <Icon
+                size={16}
+                className={cn(
+                  disabled
+                    ? "stroke-text-01"
+                    : "stroke-text-03 group-hover/Tile:stroke-text-04"
+                )}
+              />
+            </div>
+          )}
+        </div>
+      </Interactive.Stateless>
+    </Disabled>
   );
 }
diff --git a/web/src/refresh-pages/AgentEditorPage.tsx b/web/src/refresh-pages/AgentEditorPage.tsx
index 8b6784ee77a..8eff4e3bdeb 100644
--- a/web/src/refresh-pages/AgentEditorPage.tsx
+++ b/web/src/refresh-pages/AgentEditorPage.tsx
@@ -6,6 +6,7 @@ import * as SettingsLayouts from "@/layouts/settings-layouts";
 import * as GeneralLayouts from "@/layouts/general-layouts";
 import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { FullPersona } from "@/app/admin/agents/interfaces";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
 import { Formik, Form, FieldArray } from "formik";
@@ -1200,8 +1201,7 @@ export default function AgentEditorPage({
                           >
                             Cancel
                           </OpalButton>
-                          <OpalButton
-                            type="submit"
+                          <Disabled
                             disabled={
                               isSubmitting ||
                               !isValid ||
@@ -1209,8 +1209,10 @@ export default function AgentEditorPage({
                               hasUploadingFiles
                             }
                           >
-                            {existingAgent ? "Save" : "Create"}
-                          </OpalButton>
+                            <OpalButton type="submit">
+                              {existingAgent ? "Save" : "Create"}
+                            </OpalButton>
+                          </Disabled>
                         </div>
                       }
                       backButton
diff --git a/web/src/refresh-pages/SettingsPage.tsx b/web/src/refresh-pages/SettingsPage.tsx
index 8c525716578..72de465fb3a 100644
--- a/web/src/refresh-pages/SettingsPage.tsx
+++ b/web/src/refresh-pages/SettingsPage.tsx
@@ -57,7 +57,7 @@ import {
 } from "@/lib/constants/chatBackgrounds";
 import { SvgCheck } from "@opal/icons";
 import { cn } from "@/lib/utils";
-import { Interactive } from "@opal/core";
+import { Disabled, Interactive } from "@opal/core";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import { useSettingsContext } from "@/providers/SettingsProvider";
 import SimpleTooltip from "@/refresh-components/SimpleTooltip";
@@ -109,12 +109,11 @@ function PATModal({
         !!createdToken?.token ? (
           <Button onClick={onClose}>Done</Button>
         ) : (
-          <Button
-            onClick={onCreate}
-            disabled={isCreating || !newTokenName.trim()}
-          >
-            {isCreating ? "Creating Token..." : "Create Token"}
-          </Button>
+          <Disabled disabled={isCreating || !newTokenName.trim()}>
+            <Button onClick={onCreate}>
+              {isCreating ? "Creating Token..." : "Create Token"}
+            </Button>
+          </Disabled>
         )
       }
       hideCancel={!!createdToken}
@@ -236,15 +235,16 @@ function GeneralSettings() {
           title="Delete All Chats"
           onClose={() => setShowDeleteConfirmation(false)}
           submit={
-            <Button
-              variant="danger"
-              onClick={() => {
-                void handleDeleteAllChats();
-              }}
-              disabled={isDeleting}
-            >
-              {isDeleting ? "Deleting..." : "Delete"}
-            </Button>
+            <Disabled disabled={isDeleting}>
+              <Button
+                variant="danger"
+                onClick={() => {
+                  void handleDeleteAllChats();
+                }}
+              >
+                {isDeleting ? "Deleting..." : "Delete"}
+              </Button>
+            </Disabled>
           }
         >
           <Section gap={0.5} alignItems="start">
@@ -697,18 +697,21 @@ function PromptShortcuts() {
                   }
                 />
                 <Section>
-                  <Button
-                    icon={SvgMinusCircle}
-                    onClick={() => void handleRemoveShortcut(index)}
-                    prominence="tertiary"
+                  <Disabled
                     disabled={(shortcut.isNew && isEmpty) || shortcut.is_public}
-                    aria-label="Remove shortcut"
-                    tooltip={
-                      shortcut.is_public
-                        ? "Cannot delete public prompt-shortcuts."
-                        : undefined
-                    }
-                  />
+                  >
+                    <Button
+                      icon={SvgMinusCircle}
+                      onClick={() => void handleRemoveShortcut(index)}
+                      prominence="tertiary"
+                      aria-label="Remove shortcut"
+                      tooltip={
+                        shortcut.is_public
+                          ? "Cannot delete public prompt-shortcuts."
+                          : undefined
+                      }
+                    />
+                  </Disabled>
                 </Section>
                 <InputTextArea
                   placeholder="Provide a concise 1–2 sentence summary of the following:"
@@ -1170,19 +1173,20 @@ function AccountsAccessSettings() {
                 icon={SvgLock}
                 title="Change Password"
                 submit={
-                  <Button
-                    disabled={isSubmitting || !dirty || !isValid}
-                    onClick={async () => {
-                      setSubmitting(true);
-                      try {
-                        await handleChangePassword(values);
-                      } finally {
-                        setSubmitting(false);
-                      }
-                    }}
-                  >
-                    {isSubmitting ? "Updating..." : "Update"}
-                  </Button>
+                  <Disabled disabled={isSubmitting || !dirty || !isValid}>
+                    <Button
+                      onClick={async () => {
+                        setSubmitting(true);
+                        try {
+                          await handleChangePassword(values);
+                        } finally {
+                          setSubmitting(false);
+                        }
+                      }}
+                    >
+                      {isSubmitting ? "Updating..." : "Update"}
+                    </Button>
+                  </Disabled>
                 }
                 onClose={() => {
                   setShowPasswordModal(false);
@@ -1457,13 +1461,11 @@ function FederatedConnectorCard({
           title={`Disconnect ${sourceMetadata.displayName}`}
           onClose={() => setShowDisconnectConfirmation(false)}
           submit={
-            <Button
-              variant="danger"
-              onClick={() => void handleDisconnect()}
-              disabled={isDisconnecting}
-            >
-              {isDisconnecting ? "Disconnecting..." : "Disconnect"}
-            </Button>
+            <Disabled disabled={isDisconnecting}>
+              <Button variant="danger" onClick={() => void handleDisconnect()}>
+                {isDisconnecting ? "Disconnecting..." : "Disconnect"}
+              </Button>
+            </Disabled>
           }
         >
           <Section gap={0.5} alignItems="start">
@@ -1492,13 +1494,14 @@ function FederatedConnectorCard({
           paddingVariant="sm"
           rightChildren={
             connector.has_oauth_token ? (
-              <Button
-                icon={SvgUnplug}
-                prominence="tertiary"
-                size="sm"
-                onClick={() => setShowDisconnectConfirmation(true)}
-                disabled={isDisconnecting}
-              />
+              <Disabled disabled={isDisconnecting}>
+                <Button
+                  icon={SvgUnplug}
+                  prominence="tertiary"
+                  size="sm"
+                  onClick={() => setShowDisconnectConfirmation(true)}
+                />
+              </Disabled>
             ) : connector.authorize_url ? (
               <Button
                 prominence="internal"
diff --git a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
index 46d4fc62ff9..07a9731ed57 100644
--- a/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
+++ b/web/src/refresh-pages/admin/ChatPreferencesPage.tsx
@@ -52,7 +52,7 @@ import useOpenApiTools from "@/hooks/useOpenApiTools";
 import * as ExpandableCard from "@/layouts/expandable-card-layouts";
 import * as ActionsLayouts from "@/layouts/actions-layouts";
 import { getActionIcon } from "@/lib/tools/mcpUtils";
-import Disabled from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useFilter from "@/hooks/useFilter";
 import { MCPServer } from "@/lib/tools/interfaces";
diff --git a/web/src/refresh-pages/admin/CodeInterpreterPage.tsx b/web/src/refresh-pages/admin/CodeInterpreterPage.tsx
index f6875714795..33390e87ab8 100644
--- a/web/src/refresh-pages/admin/CodeInterpreterPage.tsx
+++ b/web/src/refresh-pages/admin/CodeInterpreterPage.tsx
@@ -14,6 +14,7 @@ import {
 import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
 import { Section } from "@/layouts/general-layouts";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
@@ -120,22 +121,24 @@ function ActionButtons({
       gap={0.25}
       padding={0.25}
     >
-      <Button
-        prominence="tertiary"
-        size="sm"
-        icon={SvgUnplug}
-        onClick={onDisconnect}
-        tooltip="Disconnect"
-        disabled={disabled}
-      />
-      <Button
-        prominence="tertiary"
-        size="sm"
-        icon={SvgRefreshCw}
-        onClick={onRefresh}
-        tooltip="Refresh"
-        disabled={disabled}
-      />
+      <Disabled disabled={disabled}>
+        <Button
+          prominence="tertiary"
+          size="sm"
+          icon={SvgUnplug}
+          onClick={onDisconnect}
+          tooltip="Disconnect"
+        />
+      </Disabled>
+      <Disabled disabled={disabled}>
+        <Button
+          prominence="tertiary"
+          size="sm"
+          icon={SvgRefreshCw}
+          onClick={onRefresh}
+          tooltip="Refresh"
+        />
+      </Disabled>
     </Section>
   );
 }
diff --git a/web/src/sections/actions/Actions.tsx b/web/src/sections/actions/Actions.tsx
index bca3da21433..8c1759aa98d 100644
--- a/web/src/sections/actions/Actions.tsx
+++ b/web/src/sections/actions/Actions.tsx
@@ -2,6 +2,7 @@
 import { ActionStatus } from "@/lib/tools/interfaces";
 import React from "react";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import {
   SvgArrowExchange,
   SvgChevronDown,
@@ -166,15 +167,16 @@ const Actions = React.memo(
           )}
         </div>
         {showViewToolsButton && (
-          <Button
-            prominence="tertiary"
-            onClick={onToggleTools}
-            rightIcon={SvgChevronDown}
-            aria-label={`View tools for ${serverName}`}
-            disabled
-          >
-            {`View ${toolCount ?? 0} tool${toolCount !== 1 ? "s" : ""}`}
-          </Button>
+          <Disabled disabled>
+            <Button
+              prominence="tertiary"
+              onClick={onToggleTools}
+              rightIcon={SvgChevronDown}
+              aria-label={`View tools for ${serverName}`}
+            >
+              {`View ${toolCount ?? 0} tool${toolCount !== 1 ? "s" : ""}`}
+            </Button>
+          </Disabled>
         )}
       </div>
     );
diff --git a/web/src/sections/actions/modals/AddMCPServerModal.tsx b/web/src/sections/actions/modals/AddMCPServerModal.tsx
index f9722cfd9fa..7e413928a5e 100644
--- a/web/src/sections/actions/modals/AddMCPServerModal.tsx
+++ b/web/src/sections/actions/modals/AddMCPServerModal.tsx
@@ -16,6 +16,7 @@ import {
 import { useModal } from "@/refresh-components/contexts/ModalContext";
 import Separator from "@/refresh-components/Separator";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { toast } from "@/hooks/useToast";
 import { ModalCreationInterface } from "@/refresh-components/contexts/ModalContext";
 import { SvgCheckCircle, SvgServer, SvgUnplug } from "@opal/icons";
@@ -237,26 +238,26 @@ export default function AddMCPServerModal({
               </Modal.Body>
 
               <Modal.Footer>
-                <Button
-                  prominence="secondary"
-                  type="button"
-                  onClick={() => handleModalClose(false)}
-                  disabled={isSubmitting}
-                >
-                  Cancel
-                </Button>
-                <Button
-                  type="submit"
-                  disabled={isSubmitting || !isValid || !dirty}
-                >
-                  {isSubmitting
-                    ? isEditMode
-                      ? "Saving..."
-                      : "Adding..."
-                    : isEditMode
-                      ? "Save Changes"
-                      : "Add Server"}
-                </Button>
+                <Disabled disabled={isSubmitting}>
+                  <Button
+                    prominence="secondary"
+                    type="button"
+                    onClick={() => handleModalClose(false)}
+                  >
+                    Cancel
+                  </Button>
+                </Disabled>
+                <Disabled disabled={isSubmitting || !isValid || !dirty}>
+                  <Button type="submit">
+                    {isSubmitting
+                      ? isEditMode
+                        ? "Saving..."
+                        : "Adding..."
+                      : isEditMode
+                        ? "Save Changes"
+                        : "Add Server"}
+                  </Button>
+                </Disabled>
               </Modal.Footer>
             </Form>
           )}
diff --git a/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx b/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
index 8c9ae477ffa..633308bd649 100644
--- a/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
+++ b/web/src/sections/actions/modals/AddOpenAPIActionModal.tsx
@@ -10,6 +10,7 @@ import Separator from "@/refresh-components/Separator";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { MethodSpec, ToolSnapshot } from "@/lib/tools/interfaces";
 import {
   validateToolDefinition,
@@ -374,31 +375,29 @@ function FormContent({
                   onDisconnectTool(existingTool);
                 }}
               />
-              <Button
-                prominence="secondary"
-                type="button"
-                onClick={handleEditAuthenticationClick}
-                disabled={!onEditAuthentication}
-              >
-                Edit Configs
-              </Button>
+              <Disabled disabled={!onEditAuthentication}>
+                <Button
+                  prominence="secondary"
+                  type="button"
+                  onClick={handleEditAuthenticationClick}
+                >
+                  Edit Configs
+                </Button>
+              </Disabled>
             </Section>
           </Section>
         )}
       </Modal.Body>
 
       <Modal.Footer>
-        <Button
-          prominence="secondary"
-          type="button"
-          onClick={handleClose}
-          disabled={isSubmitting}
-        >
-          Cancel
-        </Button>
-        <Button type="submit" disabled={isSubmitting || !dirty}>
-          {primaryButtonLabel}
-        </Button>
+        <Disabled disabled={isSubmitting}>
+          <Button prominence="secondary" type="button" onClick={handleClose}>
+            Cancel
+          </Button>
+        </Disabled>
+        <Disabled disabled={isSubmitting || !dirty}>
+          <Button type="submit">{primaryButtonLabel}</Button>
+        </Disabled>
       </Modal.Footer>
     </Form>
   );
diff --git a/web/src/sections/actions/modals/DisconnectEntityModal.tsx b/web/src/sections/actions/modals/DisconnectEntityModal.tsx
index fb22defde38..330dfdc9f2e 100644
--- a/web/src/sections/actions/modals/DisconnectEntityModal.tsx
+++ b/web/src/sections/actions/modals/DisconnectEntityModal.tsx
@@ -3,6 +3,7 @@
 import { useRef } from "react";
 import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import { cn } from "@/lib/utils";
 import { SvgUnplug } from "@opal/icons";
@@ -66,31 +67,31 @@ export default function DisconnectEntityModal({
         </Modal.Body>
 
         <Modal.Footer>
-          <Button
-            prominence="secondary"
-            onClick={onClose}
-            disabled={isDisconnecting}
-          >
-            Cancel
-          </Button>
+          <Disabled disabled={isDisconnecting}>
+            <Button prominence="secondary" onClick={onClose}>
+              Cancel
+            </Button>
+          </Disabled>
           {onConfirmDisconnectAndDelete && (
+            <Disabled disabled={isDisconnecting}>
+              <Button
+                variant="danger"
+                prominence="secondary"
+                onClick={onConfirmDisconnectAndDelete}
+              >
+                Disconnect &amp; Delete
+              </Button>
+            </Disabled>
+          )}
+          <Disabled disabled={isDisconnecting}>
             <Button
               variant="danger"
-              prominence="secondary"
-              onClick={onConfirmDisconnectAndDelete}
-              disabled={isDisconnecting}
+              onClick={onConfirmDisconnect}
+              ref={disconnectButtonRef}
             >
-              Disconnect &amp; Delete
+              {isDisconnecting ? "Disconnecting..." : "Disconnect"}
             </Button>
-          )}
-          <Button
-            variant="danger"
-            onClick={onConfirmDisconnect}
-            disabled={isDisconnecting}
-            ref={disconnectButtonRef}
-          >
-            {isDisconnecting ? "Disconnecting..." : "Disconnect"}
-          </Button>
+          </Disabled>
         </Modal.Footer>
       </Modal.Content>
     </Modal>
diff --git a/web/src/sections/actions/modals/MCPAuthenticationModal.tsx b/web/src/sections/actions/modals/MCPAuthenticationModal.tsx
index f778b320834..1e97bb044e6 100644
--- a/web/src/sections/actions/modals/MCPAuthenticationModal.tsx
+++ b/web/src/sections/actions/modals/MCPAuthenticationModal.tsx
@@ -9,6 +9,7 @@ import InputSelect from "@/refresh-components/inputs/InputSelect";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import Text from "@/refresh-components/texts/Text";
 import { Formik, Form } from "formik";
@@ -639,13 +640,11 @@ export default function MCPAuthenticationModal({
                   >
                     Cancel
                   </Button>
-                  <Button
-                    type="submit"
-                    disabled={!isValid || isSubmitting}
-                    data-testid="mcp-auth-connect-button"
-                  >
-                    {isSubmitting ? "Connecting..." : "Connect"}
-                  </Button>
+                  <Disabled disabled={!isValid || isSubmitting}>
+                    <Button type="submit" data-testid="mcp-auth-connect-button">
+                      {isSubmitting ? "Connecting..." : "Connect"}
+                    </Button>
+                  </Disabled>
                 </Modal.Footer>
               </Form>
             );
diff --git a/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx b/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx
index d14a3ebe1b4..b5b68f7c8ba 100644
--- a/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx
+++ b/web/src/sections/actions/modals/OpenAPIAuthenticationModal.tsx
@@ -5,6 +5,7 @@ import { Formik, Form, FormikHelpers } from "formik";
 import * as Yup from "yup";
 import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import InputSelect from "@/refresh-components/inputs/InputSelect";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
@@ -670,14 +671,15 @@ export default function OpenAPIAuthenticationModal({
                 >
                   Cancel
                 </Button>
-                <Button
-                  type="submit"
+                <Disabled
                   disabled={
                     !isValid || isSubmitting || shouldDisableForm || !dirty
                   }
                 >
-                  {isSubmitting ? "Connecting..." : "Connect"}
-                </Button>
+                  <Button type="submit">
+                    {isSubmitting ? "Connecting..." : "Connect"}
+                  </Button>
+                </Disabled>
               </Modal.Footer>
             </Form>
           )}
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index bd08bf70b46..ec41d413d46 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -22,7 +22,7 @@ import { useForcedTools } from "@/lib/hooks/useForcedTools";
 import { useAppMode } from "@/providers/AppModeProvider";
 import useAppFocus from "@/hooks/useAppFocus";
 import { cn, isImageFile } from "@/lib/utils";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import { useUser } from "@/providers/UserProvider";
 import {
   SettingsContext,
@@ -439,13 +439,14 @@ const AppInputBar = React.memo(
             }}
             handleUploadChange={handleUploadChange}
             trigger={(open) => (
-              <Button
-                icon={SvgPlusCircle}
-                tooltip="Attach Files"
-                interaction={open ? "hover" : "rest"}
-                disabled={disabled}
-                prominence="tertiary"
-              />
+              <Disabled disabled={disabled}>
+                <Button
+                  icon={SvgPlusCircle}
+                  tooltip="Attach Files"
+                  interaction={open ? "hover" : "rest"}
+                  prominence="tertiary"
+                />
+              </Disabled>
             )}
             selectedFileIds={currentMessageFiles.map((f) => f.id)}
           />
@@ -467,36 +468,38 @@ const AppInputBar = React.memo(
               />
             )}
             {onToggleTabReading ? (
-              <SelectButton
-                icon={SvgGlobe}
-                onClick={onToggleTabReading}
-                state={tabReadingEnabled ? "selected" : "empty"}
-                disabled={disabled}
-              >
-                {tabReadingEnabled
-                  ? currentTabUrl
-                    ? (() => {
-                        try {
-                          return new URL(currentTabUrl).hostname;
-                        } catch {
-                          return currentTabUrl;
-                        }
-                      })()
-                    : "Reading tab..."
-                  : "Read this tab"}
-              </SelectButton>
-            ) : (
-              showDeepResearch && (
+              <Disabled disabled={disabled}>
                 <SelectButton
-                  variant="select-light"
-                  icon={SvgHourglass}
-                  onClick={toggleDeepResearch}
-                  state={deepResearchEnabled ? "selected" : "empty"}
-                  foldable={!deepResearchEnabled}
-                  disabled={disabled}
+                  icon={SvgGlobe}
+                  onClick={onToggleTabReading}
+                  state={tabReadingEnabled ? "selected" : "empty"}
                 >
-                  Deep Research
+                  {tabReadingEnabled
+                    ? currentTabUrl
+                      ? (() => {
+                          try {
+                            return new URL(currentTabUrl).hostname;
+                          } catch {
+                            return currentTabUrl;
+                          }
+                        })()
+                      : "Reading tab..."
+                    : "Read this tab"}
                 </SelectButton>
+              </Disabled>
+            ) : (
+              showDeepResearch && (
+                <Disabled disabled={disabled}>
+                  <SelectButton
+                    variant="select-light"
+                    icon={SvgHourglass}
+                    onClick={toggleDeepResearch}
+                    state={deepResearchEnabled ? "selected" : "empty"}
+                    foldable={!deepResearchEnabled}
+                  >
+                    Deep Research
+                  </SelectButton>
+                </Disabled>
               )
             )}
 
@@ -510,20 +513,20 @@ const AppInputBar = React.memo(
                   return null;
                 }
                 return (
-                  <SelectButton
-                    variant="select-light"
-                    key={toolId}
-                    icon={getIconForAction(tool)}
-                    onClick={() => {
-                      setForcedToolIds(
-                        forcedToolIds.filter((id) => id !== toolId)
-                      );
-                    }}
-                    state="selected"
-                    disabled={disabled}
-                  >
-                    {tool.display_name}
-                  </SelectButton>
+                  <Disabled disabled={disabled} key={toolId}>
+                    <SelectButton
+                      variant="select-light"
+                      icon={getIconForAction(tool)}
+                      onClick={() => {
+                        setForcedToolIds(
+                          forcedToolIds.filter((id) => id !== toolId)
+                        );
+                      }}
+                      state="selected"
+                    >
+                      {tool.display_name}
+                    </SelectButton>
+                  </Disabled>
                 );
               })}
           </div>
@@ -541,28 +544,31 @@ const AppInputBar = React.memo(
               disabled={disabled}
             />
           </div>
-          <Button
-            id="onyx-chat-input-send-button"
-            icon={
-              isClassifying
-                ? SimpleLoader
-                : chatState === "input"
-                  ? SvgArrowUp
-                  : SvgStop
-            }
+          <Disabled
             disabled={
               (chatState === "input" && !message) ||
               hasUploadingFiles ||
               isClassifying
             }
-            onClick={() => {
-              if (chatState == "streaming") {
-                stopGenerating();
-              } else if (message) {
-                onSubmit(message);
+          >
+            <Button
+              id="onyx-chat-input-send-button"
+              icon={
+                isClassifying
+                  ? SimpleLoader
+                  : chatState === "input"
+                    ? SvgArrowUp
+                    : SvgStop
               }
-            }}
-          />
+              onClick={() => {
+                if (chatState == "streaming") {
+                  stopGenerating();
+                } else if (message) {
+                  onSubmit(message);
+                }
+              }}
+            />
+          </Disabled>
         </div>
       </div>
     );
@@ -706,25 +712,29 @@ const AppInputBar = React.memo(
 
             {isSearchMode && (
               <Section flexDirection="row" width="fit" gap={0}>
-                <Button
-                  icon={SvgX}
-                  disabled={!message || isClassifying}
-                  onClick={() => setMessage("")}
-                  prominence="tertiary"
-                />
-                <Button
-                  id="onyx-chat-input-send-button"
-                  icon={isClassifying ? SimpleLoader : SvgSearch}
+                <Disabled disabled={!message || isClassifying}>
+                  <Button
+                    icon={SvgX}
+                    onClick={() => setMessage("")}
+                    prominence="tertiary"
+                  />
+                </Disabled>
+                <Disabled
                   disabled={!message || isClassifying || hasUploadingFiles}
-                  onClick={() => {
-                    if (chatState == "streaming") {
-                      stopGenerating();
-                    } else if (message) {
-                      onSubmit(message);
-                    }
-                  }}
-                  prominence="tertiary"
-                />
+                >
+                  <Button
+                    id="onyx-chat-input-send-button"
+                    icon={isClassifying ? SimpleLoader : SvgSearch}
+                    onClick={() => {
+                      if (chatState == "streaming") {
+                        stopGenerating();
+                      } else if (message) {
+                        onSubmit(message);
+                      }
+                    }}
+                    prominence="tertiary"
+                  />
+                </Disabled>
                 <Spacer horizontal rem={0.25} />
               </Section>
             )}
diff --git a/web/src/sections/input/SharedAppInputBar.tsx b/web/src/sections/input/SharedAppInputBar.tsx
index e5525911ecf..49a73f8423f 100644
--- a/web/src/sections/input/SharedAppInputBar.tsx
+++ b/web/src/sections/input/SharedAppInputBar.tsx
@@ -2,6 +2,7 @@
 
 import Text from "@/refresh-components/texts/Text";
 import { Button, OpenButton, SelectButton } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { OpenAISVG } from "@/components/icons/icons";
 import {
   SvgPlusCircle,
@@ -26,17 +27,25 @@ export default function SharedAppInputBar() {
         <div className="flex justify-between items-center w-full p-1 min-h-[40px]">
           {/* Left side controls */}
           <div className="flex flex-row items-center">
-            <Button icon={SvgPlusCircle} prominence="tertiary" disabled />
-            <Button icon={SvgSliders} prominence="tertiary" disabled />
-            <SelectButton icon={SvgHourglass} disabled />
+            <Disabled disabled>
+              <Button icon={SvgPlusCircle} prominence="tertiary" />
+            </Disabled>
+            <Disabled disabled>
+              <Button icon={SvgSliders} prominence="tertiary" />
+            </Disabled>
+            <Disabled disabled>
+              <SelectButton icon={SvgHourglass} />
+            </Disabled>
           </div>
 
           {/* Right side controls */}
           <div className="flex flex-row items-center gap-1">
-            <OpenButton icon={OpenAISVG} disabled>
-              GPT-4o
-            </OpenButton>
-            <Button icon={SvgArrowUp} disabled />
+            <Disabled disabled>
+              <OpenButton icon={OpenAISVG}>GPT-4o</OpenButton>
+            </Disabled>
+            <Disabled disabled>
+              <Button icon={SvgArrowUp} />
+            </Disabled>
           </div>
         </div>
       </div>
diff --git a/web/src/sections/knowledge/AgentKnowledgePane.tsx b/web/src/sections/knowledge/AgentKnowledgePane.tsx
index 900c73b90a1..d0d2065ca7a 100644
--- a/web/src/sections/knowledge/AgentKnowledgePane.tsx
+++ b/web/src/sections/knowledge/AgentKnowledgePane.tsx
@@ -38,7 +38,7 @@ import {
 } from "@/app/admin/agents/interfaces";
 import { timeAgo } from "@/lib/time";
 import Spacer from "@/refresh-components/Spacer";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import SourceHierarchyBrowser from "./SourceHierarchyBrowser";
 
 // Knowledge pane view states
diff --git a/web/src/sections/modals/FeedbackModal.tsx b/web/src/sections/modals/FeedbackModal.tsx
index ac8e3bcfa9c..7dc02e78ff8 100644
--- a/web/src/sections/modals/FeedbackModal.tsx
+++ b/web/src/sections/modals/FeedbackModal.tsx
@@ -2,6 +2,7 @@
 
 import { FeedbackType } from "@/app/app/interfaces";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import useFeedbackController from "@/hooks/useFeedbackController";
 import { useModal } from "@/refresh-components/contexts/ModalContext";
 import { SvgThumbsDown, SvgThumbsUp } from "@opal/icons";
@@ -96,15 +97,16 @@ export default function FeedbackModal({
                   >
                     Cancel
                   </Button>
-                  <Button
-                    onClick={() => formikHandleSubmit()}
+                  <Disabled
                     disabled={
                       isSubmitting ||
                       (feedbackType === "dislike" && (!dirty || !isValid))
                     }
                   >
-                    {isSubmitting ? "Submitting..." : "Submit"}
-                  </Button>
+                    <Button onClick={() => formikHandleSubmit()}>
+                      {isSubmitting ? "Submitting..." : "Submit"}
+                    </Button>
+                  </Disabled>
                 </Modal.Footer>
               </>
             )}
diff --git a/web/src/sections/modals/NewTenantModal.tsx b/web/src/sections/modals/NewTenantModal.tsx
index ac1dbde615b..f1ee0a4755e 100644
--- a/web/src/sections/modals/NewTenantModal.tsx
+++ b/web/src/sections/modals/NewTenantModal.tsx
@@ -3,6 +3,7 @@
 import { useState } from "react";
 import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { toast } from "@/hooks/useToast";
 import { SvgArrowRight, SvgUsers, SvgX } from "@opal/icons";
 import { logout } from "@/lib/user";
@@ -136,30 +137,29 @@ export default function NewTenantModal({
           <BasicModalFooter
             cancel={
               isInvite ? (
-                <Button
-                  prominence="secondary"
-                  onClick={handleRejectInvite}
-                  disabled={isLoading}
-                  icon={SvgX}
-                >
-                  Decline
-                </Button>
+                <Disabled disabled={isLoading}>
+                  <Button
+                    prominence="secondary"
+                    onClick={handleRejectInvite}
+                    icon={SvgX}
+                  >
+                    Decline
+                  </Button>
+                </Disabled>
               ) : undefined
             }
             submit={
-              <Button
-                onClick={handleJoinTenant}
-                disabled={isLoading}
-                rightIcon={SvgArrowRight}
-              >
-                {isLoading
-                  ? isInvite
-                    ? "Accepting..."
-                    : "Joining..."
-                  : isInvite
-                    ? "Accept Invitation"
-                    : "Reauthenticate"}
-              </Button>
+              <Disabled disabled={isLoading}>
+                <Button onClick={handleJoinTenant} rightIcon={SvgArrowRight}>
+                  {isLoading
+                    ? isInvite
+                      ? "Accepting..."
+                      : "Joining..."
+                    : isInvite
+                      ? "Accept Invitation"
+                      : "Reauthenticate"}
+                </Button>
+              </Disabled>
             }
           />
         </Modal.Footer>
diff --git a/web/src/sections/modals/ShareAgentModal.tsx b/web/src/sections/modals/ShareAgentModal.tsx
index b75e4e95a04..a18f8cd7550 100644
--- a/web/src/sections/modals/ShareAgentModal.tsx
+++ b/web/src/sections/modals/ShareAgentModal.tsx
@@ -28,6 +28,7 @@ import { useUser } from "@/providers/UserProvider";
 import { Formik, useFormikContext } from "formik";
 import { useAgent } from "@/hooks/useAgents";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { useLabels } from "@/lib/hooks";
 import { PersonaLabel } from "@/app/admin/agents/interfaces";
 
@@ -352,21 +353,16 @@ function ShareAgentFormContent({ agentId }: ShareAgentFormContentProps) {
             ) : undefined
           }
           cancel={
-            <Button
-              prominence="secondary"
-              onClick={handleClose}
-              disabled={isSubmitting}
-            >
-              Cancel
-            </Button>
+            <Disabled disabled={isSubmitting}>
+              <Button prominence="secondary" onClick={handleClose}>
+                Cancel
+              </Button>
+            </Disabled>
           }
           submit={
-            <Button
-              onClick={() => handleSubmit()}
-              disabled={!dirty || isSubmitting}
-            >
-              Save
-            </Button>
+            <Disabled disabled={!dirty || isSubmitting}>
+              <Button onClick={() => handleSubmit()}>Save</Button>
+            </Disabled>
           }
         />
       </Modal.Footer>
diff --git a/web/src/sections/modals/ShareChatSessionModal.tsx b/web/src/sections/modals/ShareChatSessionModal.tsx
index 5aa7c7ecca4..cc880a9129c 100644
--- a/web/src/sections/modals/ShareChatSessionModal.tsx
+++ b/web/src/sections/modals/ShareChatSessionModal.tsx
@@ -9,6 +9,7 @@ import { copyAll } from "@/app/app/message/copyingUtils";
 import { Section } from "@/layouts/general-layouts";
 import Modal from "@/refresh-components/Modal";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import Text from "@/refresh-components/texts/Text";
@@ -235,15 +236,16 @@ export default function ShareChatSessionModal({
               Cancel
             </Button>
           )}
-          <Button
-            onClick={handleSubmit}
-            disabled={isLoading}
-            icon={isShared ? SvgLink : undefined}
-            width={isShared ? "full" : undefined}
-            aria-label="share-modal-submit"
-          >
-            {submitButtonText}
-          </Button>
+          <Disabled disabled={isLoading}>
+            <Button
+              onClick={handleSubmit}
+              icon={isShared ? SvgLink : undefined}
+              width={isShared ? "full" : undefined}
+              aria-label="share-modal-submit"
+            >
+              {submitButtonText}
+            </Button>
+          </Disabled>
         </Modal.Footer>
       </Modal.Content>
     </Modal>
diff --git a/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx b/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx
index 6bc960a1f7d..7c2faac0512 100644
--- a/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx
+++ b/web/src/sections/modals/llmConfig/components/FetchModelsButton.tsx
@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import SimpleTooltip from "@/refresh-components/SimpleTooltip";
 import { ModelConfiguration } from "@/interfaces/llm";
@@ -59,13 +60,11 @@ export function FetchModelsButton({
     <div className="flex flex-col gap-y-1">
       <SimpleTooltip tooltip={isDisabled ? disabledHint : undefined} side="top">
         <div className="w-fit">
-          <Button
-            type="button"
-            onClick={handleFetchModels}
-            disabled={isFetchingModels || isDisabled}
-          >
-            Fetch Available Models
-          </Button>
+          <Disabled disabled={isFetchingModels || isDisabled}>
+            <Button type="button" onClick={handleFetchModels}>
+              Fetch Available Models
+            </Button>
+          </Disabled>
         </div>
       </SimpleTooltip>
       {fetchModelsError && (
diff --git a/web/src/sections/onboarding/components/LLMProviderCard.tsx b/web/src/sections/onboarding/components/LLMProviderCard.tsx
index 9d798013018..dbd7cbecaf1 100644
--- a/web/src/sections/onboarding/components/LLMProviderCard.tsx
+++ b/web/src/sections/onboarding/components/LLMProviderCard.tsx
@@ -5,7 +5,7 @@ import Text from "@/refresh-components/texts/Text";
 import Truncated from "@/refresh-components/texts/Truncated";
 import IconButton from "@/refresh-components/buttons/IconButton";
 import { cn, noProp } from "@/lib/utils";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import {
   SvgArrowExchange,
   SvgCheckCircle,
diff --git a/web/src/sections/onboarding/components/NonAdminStep.tsx b/web/src/sections/onboarding/components/NonAdminStep.tsx
index 5a8564ec295..b7accd55980 100644
--- a/web/src/sections/onboarding/components/NonAdminStep.tsx
+++ b/web/src/sections/onboarding/components/NonAdminStep.tsx
@@ -8,6 +8,7 @@ import { useUser } from "@/providers/UserProvider";
 import { toast } from "@/hooks/useToast";
 import IconButton from "@/refresh-components/buttons/IconButton";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import InputAvatar from "@/refresh-components/inputs/InputAvatar";
 import { cn } from "@/lib/utils";
 import { SvgCheckCircle, SvgEdit, SvgUser, SvgX } from "@opal/icons";
@@ -116,9 +117,9 @@ export default function NonAdminStep() {
                   }}
                   className="w-[26%] min-w-40"
                 />
-                <Button disabled={name === ""} onClick={handleSave}>
-                  Save
-                </Button>
+                <Disabled disabled={name === ""}>
+                  <Button onClick={handleSave}>Save</Button>
+                </Disabled>
               </div>
             }
           />
diff --git a/web/src/sections/onboarding/components/OnboardingHeader.tsx b/web/src/sections/onboarding/components/OnboardingHeader.tsx
index 9017962bce2..47fad978af8 100644
--- a/web/src/sections/onboarding/components/OnboardingHeader.tsx
+++ b/web/src/sections/onboarding/components/OnboardingHeader.tsx
@@ -7,6 +7,7 @@ import {
 } from "@/interfaces/onboarding";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { SvgProgressCircle, SvgX } from "@opal/icons";
 import { Card } from "@/refresh-components/cards";
 import { Section } from "@/layouts/general-layouts";
@@ -58,12 +59,9 @@ const OnboardingHeader = React.memo(
                     {onboardingState.totalSteps}
                   </Text>
                 )}
-                <Button
-                  onClick={handleButtonClick}
-                  disabled={!onboardingState.isButtonActive}
-                >
-                  {stepButtonText}
-                </Button>
+                <Disabled disabled={!onboardingState.isButtonActive}>
+                  <Button onClick={handleButtonClick}>{stepButtonText}</Button>
+                </Disabled>
               </Section>
             ) : (
               <Button
diff --git a/web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx b/web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx
index 3b3653058cb..662a1fa69d1 100644
--- a/web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/BedrockOnboardingForm.tsx
@@ -11,6 +11,7 @@ import InputSelect from "@/refresh-components/inputs/InputSelect";
 import Separator from "@/refresh-components/Separator";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { cn, noProp } from "@/lib/utils";
 import { SvgAlertCircle, SvgRefreshCw } from "@opal/icons";
 import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
@@ -348,33 +349,36 @@ function BedrockFormFields(props: OnboardingFormChildProps<BedrockFormValues>) {
                   disabled || isFetchingModels || modelOptions.length === 0
                 }
                 rightSection={
-                  <Button
-                    prominence="tertiary"
-                    size="sm"
-                    icon={({ className }) => (
-                      <SvgRefreshCw
-                        className={cn(
-                          className,
-                          isFetchingModels && "animate-spin"
-                        )}
-                      />
-                    )}
-                    onClick={noProp((e) => {
-                      e.preventDefault();
-                      if (!isFetchDisabled) {
-                        handleFetchModels();
-                      }
-                    })}
-                    tooltip={
-                      isFetchDisabled
-                        ? !formikProps.values.custom_config?.AWS_REGION_NAME
-                          ? "Select an AWS region first"
-                          : "Complete authentication first"
-                        : "Fetch available models"
-                    }
-                    aria-label="Fetch available models"
+                  <Disabled
                     disabled={disabled || isFetchingModels || isFetchDisabled}
-                  />
+                  >
+                    <Button
+                      prominence="tertiary"
+                      size="sm"
+                      icon={({ className }) => (
+                        <SvgRefreshCw
+                          className={cn(
+                            className,
+                            isFetchingModels && "animate-spin"
+                          )}
+                        />
+                      )}
+                      onClick={noProp((e) => {
+                        e.preventDefault();
+                        if (!isFetchDisabled) {
+                          handleFetchModels();
+                        }
+                      })}
+                      tooltip={
+                        isFetchDisabled
+                          ? !formikProps.values.custom_config?.AWS_REGION_NAME
+                            ? "Select an AWS region first"
+                            : "Complete authentication first"
+                          : "Fetch available models"
+                      }
+                      aria-label="Fetch available models"
+                    />
+                  </Disabled>
                 }
                 onBlur={field.onBlur}
                 placeholder="Select a model"
diff --git a/web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx b/web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx
index 5f5c14cc656..4015f8363d8 100644
--- a/web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/OllamaOnboardingForm.tsx
@@ -9,6 +9,7 @@ import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn
 import InputComboBox from "@/refresh-components/inputs/InputComboBox";
 import Separator from "@/refresh-components/Separator";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import Tabs from "@/refresh-components/Tabs";
 import { cn, noProp } from "@/lib/utils";
 import { SvgRefreshCw } from "@opal/icons";
@@ -190,24 +191,25 @@ function OllamaFormFields({
                     options={modelOptions}
                     disabled={disabled || isFetchingModels}
                     rightSection={
-                      <Button
-                        prominence="tertiary"
-                        size="sm"
-                        icon={({ className }) => (
-                          <SvgRefreshCw
-                            className={cn(
-                              className,
-                              isFetchingModels && "animate-spin"
-                            )}
-                          />
-                        )}
-                        onClick={noProp((e) => {
-                          e.preventDefault();
-                          handleFetchModels();
-                        })}
-                        tooltip="Fetch available models"
-                        disabled={disabled || isFetchingModels}
-                      />
+                      <Disabled disabled={disabled || isFetchingModels}>
+                        <Button
+                          prominence="tertiary"
+                          size="sm"
+                          icon={({ className }) => (
+                            <SvgRefreshCw
+                              className={cn(
+                                className,
+                                isFetchingModels && "animate-spin"
+                              )}
+                            />
+                          )}
+                          onClick={noProp((e) => {
+                            e.preventDefault();
+                            handleFetchModels();
+                          })}
+                          tooltip="Fetch available models"
+                        />
+                      </Disabled>
                     }
                     onBlur={field.onBlur}
                     placeholder="Select a model"
@@ -312,24 +314,25 @@ function OllamaFormFields({
                     options={modelOptions}
                     disabled={disabled || isFetchingModels}
                     rightSection={
-                      <Button
-                        prominence="tertiary"
-                        size="sm"
-                        icon={({ className }) => (
-                          <SvgRefreshCw
-                            className={cn(
-                              className,
-                              isFetchingModels && "animate-spin"
-                            )}
-                          />
-                        )}
-                        onClick={noProp((e) => {
-                          e.preventDefault();
-                          handleFetchModels();
-                        })}
-                        tooltip="Fetch available models"
-                        disabled={disabled || isFetchingModels}
-                      />
+                      <Disabled disabled={disabled || isFetchingModels}>
+                        <Button
+                          prominence="tertiary"
+                          size="sm"
+                          icon={({ className }) => (
+                            <SvgRefreshCw
+                              className={cn(
+                                className,
+                                isFetchingModels && "animate-spin"
+                              )}
+                            />
+                          )}
+                          onClick={noProp((e) => {
+                            e.preventDefault();
+                            handleFetchModels();
+                          })}
+                          tooltip="Fetch available models"
+                        />
+                      </Disabled>
                     }
                     onBlur={field.onBlur}
                     placeholder="Select a model"
diff --git a/web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx b/web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx
index db17b94c968..6c02eddbec6 100644
--- a/web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/OpenRouterOnboardingForm.tsx
@@ -8,6 +8,7 @@ import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn
 import InputComboBox from "@/refresh-components/inputs/InputComboBox";
 import Separator from "@/refresh-components/Separator";
 import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
 import { cn, noProp } from "@/lib/utils";
 import { SvgRefreshCw } from "@opal/icons";
 import { WellKnownLLMProviderDescriptor } from "@/interfaces/llm";
@@ -139,24 +140,25 @@ function OpenRouterFormFields(
                   disabled || isFetchingModels || modelOptions.length === 0
                 }
                 rightSection={
-                  <Button
-                    prominence="tertiary"
-                    size="sm"
-                    icon={({ className }) => (
-                      <SvgRefreshCw
-                        className={cn(
-                          className,
-                          isFetchingModels && "animate-spin"
-                        )}
-                      />
-                    )}
-                    onClick={noProp((e) => {
-                      e.preventDefault();
-                      handleFetchModels();
-                    })}
-                    tooltip="Fetch available models"
-                    disabled={disabled || isFetchingModels}
-                  />
+                  <Disabled disabled={disabled || isFetchingModels}>
+                    <Button
+                      prominence="tertiary"
+                      size="sm"
+                      icon={({ className }) => (
+                        <SvgRefreshCw
+                          className={cn(
+                            className,
+                            isFetchingModels && "animate-spin"
+                          )}
+                        />
+                      )}
+                      onClick={noProp((e) => {
+                        e.preventDefault();
+                        handleFetchModels();
+                      })}
+                      tooltip="Fetch available models"
+                    />
+                  </Disabled>
                 }
                 onBlur={field.onBlur}
                 placeholder="Select a model"
diff --git a/web/src/sections/onboarding/steps/LLMStep.tsx b/web/src/sections/onboarding/steps/LLMStep.tsx
index 3d26757d04f..6875227e829 100644
--- a/web/src/sections/onboarding/steps/LLMStep.tsx
+++ b/web/src/sections/onboarding/steps/LLMStep.tsx
@@ -15,7 +15,7 @@ import {
   getOnboardingForm,
   getProviderDisplayInfo,
 } from "../forms/getOnboardingForm";
-import { Disabled } from "@/refresh-components/Disabled";
+import { Disabled } from "@opal/core";
 import { ProviderIcon } from "@/app/admin/configuration/llm/ProviderIcon";
 import { SvgCheckCircle, SvgCpu, SvgExternalLink } from "@opal/icons";
 import { ContentAction } from "@opal/layouts";
@@ -137,14 +137,15 @@ const LLMStepInner = ({
             variant="section"
             paddingVariant="lg"
             rightChildren={
-              <Button
-                prominence="tertiary"
-                rightIcon={SvgExternalLink}
-                disabled={disabled}
-                href="/admin/configuration/llm"
-              >
-                View in Admin Panel
-              </Button>
+              <Disabled disabled={disabled}>
+                <Button
+                  prominence="tertiary"
+                  rightIcon={SvgExternalLink}
+                  href="/admin/configuration/llm"
+                >
+                  View in Admin Panel
+                </Button>
+              </Disabled>
             }
           />
           <Separator />

From 661dc831dce855fc7e77037951e9f54ada093df7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 6 Mar 2026 16:22:41 +0000
Subject: [PATCH 147/267] chore(deps): bump golang.org/x/net from 0.27.0 to
 0.38.0 in /cli (#9133)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 cli/go.mod |  6 +++---
 cli/go.sum | 12 ++++++------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/cli/go.mod b/cli/go.mod
index 408147be0c0..9f862ef21e5 100644
--- a/cli/go.mod
+++ b/cli/go.mod
@@ -8,7 +8,7 @@ require (
 	github.com/charmbracelet/glamour v0.8.0
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/spf13/cobra v1.9.1
-	golang.org/x/term v0.22.0
+	golang.org/x/term v0.30.0
 	golang.org/x/text v0.34.0
 )
 
@@ -39,7 +39,7 @@ require (
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yuin/goldmark v1.7.4 // indirect
 	github.com/yuin/goldmark-emoji v1.0.3 // indirect
-	golang.org/x/net v0.27.0 // indirect
+	golang.org/x/net v0.38.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.30.0 // indirect
+	golang.org/x/sys v0.31.0 // indirect
 )
diff --git a/cli/go.sum b/cli/go.sum
index 4ba0b3b2c0c..5e756771906 100644
--- a/cli/go.sum
+++ b/cli/go.sum
@@ -78,16 +78,16 @@ github.com/yuin/goldmark-emoji v1.0.3 h1:aLRkLHOuBR2czCY4R8olwMjID+tENfhyFDMCRhb
 github.com/yuin/goldmark-emoji v1.0.3/go.mod h1:tTkZEbwu5wkPmgTcitqddVxY9osFZiavD+r4AzQrh1U=
 golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561 h1:MDc5xs78ZrZr3HMQugiXOAkSZtfTpbJLDr/lwfgO53E=
 golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561/go.mod h1:cyybsKvd6eL0RnXn6p/Grxp8F5bW7iYuBgsNCOHpMYE=
-golang.org/x/net v0.27.0 h1:5K3Njcw06/l2y9vpGCSdcxWOYHOUk3dVNGDXN+FvAys=
-golang.org/x/net v0.27.0/go.mod h1:dDi0PyhWNoiUOrAS8uXv/vnScO4wnHQO4mj9fn/RytE=
+golang.org/x/net v0.38.0 h1:vRMAPTMaeGqVhG5QyLJHqNDwecKTomGeqbnfZyKlBI8=
+golang.org/x/net v0.38.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
 golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
-golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/term v0.22.0 h1:BbsgPEJULsl2fV/AT3v15Mjva5yXKQDyKf+TbDz7QJk=
-golang.org/x/term v0.22.0/go.mod h1:F3qCibpT5AMpCRfhfT53vVJwhLtIVHhB9XDjfFvnMI4=
+golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
+golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/term v0.30.0 h1:PQ39fJZ+mfadBm0y5WlL4vlM7Sx1Hgf13sMIY2+QS9Y=
+golang.org/x/term v0.30.0/go.mod h1:NYYFdzHoI5wRh/h5tDMdMqCqPJZEuNqVR5xJLd/n67g=
 golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
 golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

From e41bad910347e9d61afe6b2b76e3bcaa2f328d3f Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 10:26:08 -0800
Subject: [PATCH 148/267] chore(zizmor): fix issues (#9139)

---
 .github/workflows/nightly-llm-provider-chat.yml          | 3 ++-
 .github/workflows/post-merge-beta-cherry-pick.yml        | 6 ++++--
 .github/workflows/pr-jest-tests.yml                      | 2 +-
 .github/workflows/reusable-nightly-llm-provider-chat.yml | 4 ++++
 4 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/nightly-llm-provider-chat.yml b/.github/workflows/nightly-llm-provider-chat.yml
index 15fc1f83a7b..a27c1aab798 100644
--- a/.github/workflows/nightly-llm-provider-chat.yml
+++ b/.github/workflows/nightly-llm-provider-chat.yml
@@ -15,7 +15,8 @@ permissions:
 jobs:
   provider-chat-test:
     uses: ./.github/workflows/reusable-nightly-llm-provider-chat.yml
-    secrets: inherit
+    secrets:
+      AWS_OIDC_ROLE_ARN: ${{ secrets.AWS_OIDC_ROLE_ARN }}
     permissions:
       contents: read
       id-token: write
diff --git a/.github/workflows/post-merge-beta-cherry-pick.yml b/.github/workflows/post-merge-beta-cherry-pick.yml
index 06993fa5a53..a68a9d616bf 100644
--- a/.github/workflows/post-merge-beta-cherry-pick.yml
+++ b/.github/workflows/post-merge-beta-cherry-pick.yml
@@ -6,11 +6,13 @@ on:
       - main
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
 
 jobs:
   cherry-pick-to-latest-release:
+    permissions:
+      contents: write
+      pull-requests: write
     outputs:
       should_cherrypick: ${{ steps.gate.outputs.should_cherrypick }}
       pr_number: ${{ steps.gate.outputs.pr_number }}
diff --git a/.github/workflows/pr-jest-tests.yml b/.github/workflows/pr-jest-tests.yml
index e7fa59d117b..d2eb465b988 100644
--- a/.github/workflows/pr-jest-tests.yml
+++ b/.github/workflows/pr-jest-tests.yml
@@ -31,7 +31,7 @@ jobs:
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # ratchet:actions/setup-node@v4
         with:
           node-version: 22
-          cache: "npm"
+          cache: "npm" # zizmor: ignore[cache-poisoning] test-only workflow; no deploy artifacts
           cache-dependency-path: ./web/package-lock.json
 
       - name: Install node dependencies
diff --git a/.github/workflows/reusable-nightly-llm-provider-chat.yml b/.github/workflows/reusable-nightly-llm-provider-chat.yml
index ed4edb14b1e..51213434e3e 100644
--- a/.github/workflows/reusable-nightly-llm-provider-chat.yml
+++ b/.github/workflows/reusable-nightly-llm-provider-chat.yml
@@ -48,6 +48,10 @@ on:
         required: false
         default: true
         type: boolean
+    secrets:
+      AWS_OIDC_ROLE_ARN:
+        description: "AWS role ARN for OIDC auth"
+        required: true
 
 permissions:
   contents: read

From d1409ccafaff3dcf0c8a107616fbfa2dc781a4e9 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 10:53:56 -0800
Subject: [PATCH 149/267] chore(fe): rm redundant `alignBubble` (#9072)

---
 web/src/app/app/message/FileDisplay.tsx  | 80 ++++++++++--------------
 web/src/app/app/message/HumanMessage.tsx |  2 +-
 2 files changed, 34 insertions(+), 48 deletions(-)

diff --git a/web/src/app/app/message/FileDisplay.tsx b/web/src/app/app/message/FileDisplay.tsx
index 7c170611fb0..eff28c2da94 100644
--- a/web/src/app/app/message/FileDisplay.tsx
+++ b/web/src/app/app/message/FileDisplay.tsx
@@ -7,15 +7,13 @@ import { InMessageImage } from "@/app/app/components/files/images/InMessageImage
 import CsvContent from "@/components/tools/CSVContent";
 import TextViewModal from "@/sections/modals/TextViewModal";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
-import { cn } from "@/lib/utils";
 import ExpandableContentWrapper from "@/components/tools/ExpandableContentWrapper";
 
 interface FileDisplayProps {
   files: FileDescriptor[];
-  alignBubble?: boolean;
 }
 
-export default function FileDisplay({ files, alignBubble }: FileDisplayProps) {
+export default function FileDisplay({ files }: FileDisplayProps) {
   const [close, setClose] = useState(true);
   const [previewingFile, setPreviewingFile] = useState<FileDescriptor | null>(
     null
@@ -43,59 +41,47 @@ export default function FileDisplay({ files, alignBubble }: FileDisplayProps) {
       )}
 
       {textFiles.length > 0 && (
-        <div
-          id="onyx-file"
-          className={cn("m-2 auto", alignBubble && "ml-auto")}
-        >
-          <div className="flex flex-col items-end gap-2">
-            {textFiles.map((file) => (
-              <Attachment
-                key={file.id}
-                fileName={file.name || file.id}
-                open={() => setPreviewingFile(file)}
-              />
-            ))}
-          </div>
+        <div id="onyx-file" className="flex flex-col items-end gap-2 py-2">
+          {textFiles.map((file) => (
+            <Attachment
+              key={file.id}
+              fileName={file.name || file.id}
+              open={() => setPreviewingFile(file)}
+            />
+          ))}
         </div>
       )}
 
       {imageFiles.length > 0 && (
-        <div
-          id="onyx-image"
-          className={cn("m-2 auto", alignBubble && "ml-auto")}
-        >
-          <div className="flex flex-col items-end gap-2">
-            {imageFiles.map((file) => (
-              <InMessageImage key={file.id} fileId={file.id} />
-            ))}
-          </div>
+        <div id="onyx-image" className="flex flex-col items-end gap-2 py-2">
+          {imageFiles.map((file) => (
+            <InMessageImage key={file.id} fileId={file.id} />
+          ))}
         </div>
       )}
 
       {csvFiles.length > 0 && (
-        <div className={cn("m-2 auto", alignBubble && "ml-auto")}>
-          <div className="flex flex-col items-end gap-2">
-            {csvFiles.map((file) => {
-              return (
-                <div key={file.id} className="w-fit">
-                  {close ? (
-                    <>
-                      <ExpandableContentWrapper
-                        fileDescriptor={file}
-                        close={() => setClose(false)}
-                        ContentComponent={CsvContent}
-                      />
-                    </>
-                  ) : (
-                    <Attachment
-                      open={() => setClose(true)}
-                      fileName={file.name || file.id}
+        <div className="flex flex-col items-end gap-2 py-2">
+          {csvFiles.map((file) => {
+            return (
+              <div key={file.id} className="w-fit">
+                {close ? (
+                  <>
+                    <ExpandableContentWrapper
+                      fileDescriptor={file}
+                      close={() => setClose(false)}
+                      ContentComponent={CsvContent}
                     />
-                  )}
-                </div>
-              );
-            })}
-          </div>
+                  </>
+                ) : (
+                  <Attachment
+                    open={() => setClose(true)}
+                    fileName={file.name || file.id}
+                  />
+                )}
+              </div>
+            );
+          })}
         </div>
       )}
     </>
diff --git a/web/src/app/app/message/HumanMessage.tsx b/web/src/app/app/message/HumanMessage.tsx
index 3a5ab0447ac..7f65255bdfa 100644
--- a/web/src/app/app/message/HumanMessage.tsx
+++ b/web/src/app/app/message/HumanMessage.tsx
@@ -195,7 +195,7 @@ const HumanMessage = React.memo(function HumanMessage({
       id="onyx-human-message"
       className="group flex flex-col justify-end w-full relative"
     >
-      <FileDisplay alignBubble files={files || []} />
+      <FileDisplay files={files || []} />
       {isEditing ? (
         <MessageEditing
           content={content}

From 29d8b310b5c48e4f143bd187b162cf892d2f9aa2 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 11:04:23 -0800
Subject: [PATCH 150/267] chore(deps): upgrade desktop deps (#9140)

---
 desktop/package-lock.json    |  104 +--
 desktop/package.json         |    8 +-
 desktop/src-tauri/Cargo.lock | 1168 +++++++++++++++++-----------------
 desktop/src-tauri/Cargo.toml |   10 +-
 4 files changed, 636 insertions(+), 654 deletions(-)

diff --git a/desktop/package-lock.json b/desktop/package-lock.json
index 35765ca709a..f4f61e2cfb2 100644
--- a/desktop/package-lock.json
+++ b/desktop/package-lock.json
@@ -8,16 +8,16 @@
       "name": "onyx-desktop",
       "version": "0.0.0-dev",
       "dependencies": {
-        "@tauri-apps/api": "^2.0.0"
+        "@tauri-apps/api": "^2.10.1"
       },
       "devDependencies": {
-        "@tauri-apps/cli": "^2.0.0"
+        "@tauri-apps/cli": "^2.10.1"
       }
     },
     "node_modules/@tauri-apps/api": {
-      "version": "2.9.1",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.9.1.tgz",
-      "integrity": "sha512-IGlhP6EivjXHepbBic618GOmiWe4URJiIeZFlB7x3czM0yDHHYviH1Xvoiv4FefdkQtn6v7TuwWCRfOGdnVUGw==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.10.1.tgz",
+      "integrity": "sha512-hKL/jWf293UDSUN09rR69hrToyIXBb8CjGaWC7gfinvnQrBVvnLr08FeFi38gxtugAVyVcTa5/FD/Xnkb1siBw==",
       "license": "Apache-2.0 OR MIT",
       "funding": {
         "type": "opencollective",
@@ -25,9 +25,9 @@
       }
     },
     "node_modules/@tauri-apps/cli": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli/-/cli-2.9.6.tgz",
-      "integrity": "sha512-3xDdXL5omQ3sPfBfdC8fCtDKcnyV7OqyzQgfyT5P3+zY6lcPqIYKQBvUasNvppi21RSdfhy44ttvJmftb0PCDw==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli/-/cli-2.10.1.tgz",
+      "integrity": "sha512-jQNGF/5quwORdZSSLtTluyKQ+o6SMa/AUICfhf4egCGFdMHqWssApVgYSbg+jmrZoc8e1DscNvjTnXtlHLS11g==",
       "dev": true,
       "license": "Apache-2.0 OR MIT",
       "bin": {
@@ -41,23 +41,23 @@
         "url": "https://opencollective.com/tauri"
       },
       "optionalDependencies": {
-        "@tauri-apps/cli-darwin-arm64": "2.9.6",
-        "@tauri-apps/cli-darwin-x64": "2.9.6",
-        "@tauri-apps/cli-linux-arm-gnueabihf": "2.9.6",
-        "@tauri-apps/cli-linux-arm64-gnu": "2.9.6",
-        "@tauri-apps/cli-linux-arm64-musl": "2.9.6",
-        "@tauri-apps/cli-linux-riscv64-gnu": "2.9.6",
-        "@tauri-apps/cli-linux-x64-gnu": "2.9.6",
-        "@tauri-apps/cli-linux-x64-musl": "2.9.6",
-        "@tauri-apps/cli-win32-arm64-msvc": "2.9.6",
-        "@tauri-apps/cli-win32-ia32-msvc": "2.9.6",
-        "@tauri-apps/cli-win32-x64-msvc": "2.9.6"
+        "@tauri-apps/cli-darwin-arm64": "2.10.1",
+        "@tauri-apps/cli-darwin-x64": "2.10.1",
+        "@tauri-apps/cli-linux-arm-gnueabihf": "2.10.1",
+        "@tauri-apps/cli-linux-arm64-gnu": "2.10.1",
+        "@tauri-apps/cli-linux-arm64-musl": "2.10.1",
+        "@tauri-apps/cli-linux-riscv64-gnu": "2.10.1",
+        "@tauri-apps/cli-linux-x64-gnu": "2.10.1",
+        "@tauri-apps/cli-linux-x64-musl": "2.10.1",
+        "@tauri-apps/cli-win32-arm64-msvc": "2.10.1",
+        "@tauri-apps/cli-win32-ia32-msvc": "2.10.1",
+        "@tauri-apps/cli-win32-x64-msvc": "2.10.1"
       }
     },
     "node_modules/@tauri-apps/cli-darwin-arm64": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-arm64/-/cli-darwin-arm64-2.9.6.tgz",
-      "integrity": "sha512-gf5no6N9FCk1qMrti4lfwP77JHP5haASZgVbBgpZG7BUepB3fhiLCXGUK8LvuOjP36HivXewjg72LTnPDScnQQ==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-arm64/-/cli-darwin-arm64-2.10.1.tgz",
+      "integrity": "sha512-Z2OjCXiZ+fbYZy7PmP3WRnOpM9+Fy+oonKDEmUE6MwN4IGaYqgceTjwHucc/kEEYZos5GICve35f7ZiizgqEnQ==",
       "cpu": [
         "arm64"
       ],
@@ -72,9 +72,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-darwin-x64": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.9.6.tgz",
-      "integrity": "sha512-oWh74WmqbERwwrwcueJyY6HYhgCksUc6NT7WKeXyrlY/FPmNgdyQAgcLuTSkhRFuQ6zh4Np1HZpOqCTpeZBDcw==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.10.1.tgz",
+      "integrity": "sha512-V/irQVvjPMGOTQqNj55PnQPVuH4VJP8vZCN7ajnj+ZS8Kom1tEM2hR3qbbIRoS3dBKs5mbG8yg1WC+97dq17Pw==",
       "cpu": [
         "x64"
       ],
@@ -89,9 +89,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-arm-gnueabihf": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.9.6.tgz",
-      "integrity": "sha512-/zde3bFroFsNXOHN204DC2qUxAcAanUjVXXSdEGmhwMUZeAQalNj5cz2Qli2elsRjKN/hVbZOJj0gQ5zaYUjSg==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.10.1.tgz",
+      "integrity": "sha512-Hyzwsb4VnCWKGfTw+wSt15Z2pLw2f0JdFBfq2vHBOBhvg7oi6uhKiF87hmbXOBXUZaGkyRDkCHsdzJcIfoJC2w==",
       "cpu": [
         "arm"
       ],
@@ -106,9 +106,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-arm64-gnu": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.9.6.tgz",
-      "integrity": "sha512-pvbljdhp9VOo4RnID5ywSxgBs7qiylTPlK56cTk7InR3kYSTJKYMqv/4Q/4rGo/mG8cVppesKIeBMH42fw6wjg==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.10.1.tgz",
+      "integrity": "sha512-OyOYs2t5GkBIvyWjA1+h4CZxTcdz1OZPCWAPz5DYEfB0cnWHERTnQ/SLayQzncrT0kwRoSfSz9KxenkyJoTelA==",
       "cpu": [
         "arm64"
       ],
@@ -123,9 +123,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-arm64-musl": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.9.6.tgz",
-      "integrity": "sha512-02TKUndpodXBCR0oP//6dZWGYcc22Upf2eP27NvC6z0DIqvkBBFziQUcvi2n6SrwTRL0yGgQjkm9K5NIn8s6jw==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.10.1.tgz",
+      "integrity": "sha512-MIj78PDDGjkg3NqGptDOGgfXks7SYJwhiMh8SBoZS+vfdz7yP5jN18bNaLnDhsVIPARcAhE1TlsZe/8Yxo2zqg==",
       "cpu": [
         "arm64"
       ],
@@ -140,9 +140,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-riscv64-gnu": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.9.6.tgz",
-      "integrity": "sha512-fmp1hnulbqzl1GkXl4aTX9fV+ubHw2LqlLH1PE3BxZ11EQk+l/TmiEongjnxF0ie4kV8DQfDNJ1KGiIdWe1GvQ==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.10.1.tgz",
+      "integrity": "sha512-X0lvOVUg8PCVaoEtEAnpxmnkwlE1gcMDTqfhbefICKDnOTJ5Est3qL0SrWxizDackIOKBcvtpejrSiVpuJI1kw==",
       "cpu": [
         "riscv64"
       ],
@@ -157,9 +157,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-x64-gnu": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.9.6.tgz",
-      "integrity": "sha512-vY0le8ad2KaV1PJr+jCd8fUF9VOjwwQP/uBuTJvhvKTloEwxYA/kAjKK9OpIslGA9m/zcnSo74czI6bBrm2sYA==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.10.1.tgz",
+      "integrity": "sha512-2/12bEzsJS9fAKybxgicCDFxYD1WEI9kO+tlDwX5znWG2GwMBaiWcmhGlZ8fi+DMe9CXlcVarMTYc0L3REIRxw==",
       "cpu": [
         "x64"
       ],
@@ -174,9 +174,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-x64-musl": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.9.6.tgz",
-      "integrity": "sha512-TOEuB8YCFZTWVDzsO2yW0+zGcoMiPPwcUgdnW1ODnmgfwccpnihDRoks+ABT1e3fHb1ol8QQWsHSCovb3o2ENQ==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.10.1.tgz",
+      "integrity": "sha512-Y8J0ZzswPz50UcGOFuXGEMrxbjwKSPgXftx5qnkuMs2rmwQB5ssvLb6tn54wDSYxe7S6vlLob9vt0VKuNOaCIQ==",
       "cpu": [
         "x64"
       ],
@@ -191,9 +191,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-win32-arm64-msvc": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.9.6.tgz",
-      "integrity": "sha512-ujmDGMRc4qRLAnj8nNG26Rlz9klJ0I0jmZs2BPpmNNf0gM/rcVHhqbEkAaHPTBVIrtUdf7bGvQAD2pyIiUrBHQ==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.10.1.tgz",
+      "integrity": "sha512-iSt5B86jHYAPJa/IlYw++SXtFPGnWtFJriHn7X0NFBVunF6zu9+/zOn8OgqIWSl8RgzhLGXQEEtGBdR4wzpVgg==",
       "cpu": [
         "arm64"
       ],
@@ -208,9 +208,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-win32-ia32-msvc": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.9.6.tgz",
-      "integrity": "sha512-S4pT0yAJgFX8QRCyKA1iKjZ9Q/oPjCZf66A/VlG5Yw54Nnr88J1uBpmenINbXxzyhduWrIXBaUbEY1K80ZbpMg==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.10.1.tgz",
+      "integrity": "sha512-gXyxgEzsFegmnWywYU5pEBURkcFN/Oo45EAwvZrHMh+zUSEAvO5E8TXsgPADYm31d1u7OQU3O3HsYfVBf2moHw==",
       "cpu": [
         "ia32"
       ],
@@ -225,9 +225,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-win32-x64-msvc": {
-      "version": "2.9.6",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.9.6.tgz",
-      "integrity": "sha512-ldWuWSSkWbKOPjQMJoYVj9wLHcOniv7diyI5UAJ4XsBdtaFB0pKHQsqw/ItUma0VXGC7vB4E9fZjivmxur60aw==",
+      "version": "2.10.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.10.1.tgz",
+      "integrity": "sha512-6Cn7YpPFwzChy0ERz6djKEmUehWrYlM+xTaNzGPgZocw3BD7OfwfWHKVWxXzdjEW2KfKkHddfdxK1XXTYqBRLg==",
       "cpu": [
         "x64"
       ],
diff --git a/desktop/package.json b/desktop/package.json
index 2b8b6056340..ed98dc27233 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -9,10 +9,10 @@
     "build:dmg": "tauri build --target universal-apple-darwin",
     "build:linux": "tauri build --bundles deb,rpm"
   },
-  "devDependencies": {
-    "@tauri-apps/cli": "^2.0.0"
-  },
   "dependencies": {
-    "@tauri-apps/api": "^2.0.0"
+    "@tauri-apps/api": "^2.10.1"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.10.1"
   }
 }
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index ee9ddbdddcc..ab46e1c5c73 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -43,9 +43,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.100"
+version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"
+checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
 [[package]]
 name = "atk"
@@ -102,9 +102,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
 [[package]]
 name = "bitflags"
-version = "2.10.0"
+version = "2.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
 dependencies = [
  "serde_core",
 ]
@@ -118,22 +118,13 @@ dependencies = [
  "generic-array",
 ]
 
-[[package]]
-name = "block2"
-version = "0.5.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2c132eebf10f5cad5289222520a4a058514204aed6d791f1cf4fe8088b82d15f"
-dependencies = [
- "objc2 0.5.2",
-]
-
 [[package]]
 name = "block2"
 version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cdeb9d870516001442e364c5220d3574d2da8dc765554b4a617230d33fa58ef5"
 dependencies = [
- "objc2 0.6.3",
+ "objc2",
 ]
 
 [[package]]
@@ -159,15 +150,15 @@ dependencies = [
 
 [[package]]
 name = "bumpalo"
-version = "3.19.0"
+version = "3.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "46c5e41b57b8bba42a04676d81cb89e9ee8e859a1a66f80a5a72e1cb76b34d43"
+checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
 
 [[package]]
 name = "bytemuck"
-version = "1.24.0"
+version = "1.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1fbdf580320f38b612e485521afda1ee26d10cc9884efaaa750d383e13e3c5f4"
+checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
 
 [[package]]
 name = "byteorder"
@@ -196,7 +187,7 @@ version = "0.18.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ca26ef0159422fb77631dc9d17b102f253b876fe1586b03b803e63a309b4ee2"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "cairo-sys-rs",
  "glib",
  "libc",
@@ -217,9 +208,9 @@ dependencies = [
 
 [[package]]
 name = "camino"
-version = "1.2.1"
+version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "276a59bf2b2c967788139340c9f0c5b12d7fd6630315c15c217e559de85d2609"
+checksum = "e629a66d692cb9ff1a1c664e41771b3dcaf961985a9774c0eb0bd1b51cf60a48"
 dependencies = [
  "serde_core",
 ]
@@ -244,7 +235,7 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
 ]
 
 [[package]]
@@ -254,14 +245,14 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "374b7c592d9c00c1f4972ea58390ac6b18cbb6ab79011f3bdc90a0b82ca06b77"
 dependencies = [
  "serde",
- "toml 0.9.8",
+ "toml 0.9.12+spec-1.1.0",
 ]
 
 [[package]]
 name = "cc"
-version = "1.2.49"
+version = "1.2.56"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90583009037521a116abf44494efecd645ba48b6622457080f080b85544e2215"
+checksum = "aebf35691d1bfb0ac386a69bac2fde4dd276fb618cf8bf4f5318fe285e821bb2"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -300,17 +291,11 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
-[[package]]
-name = "cfg_aliases"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
-
 [[package]]
 name = "chrono"
-version = "0.4.42"
+version = "0.4.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "145052bdd345b87320e369255277e3fb5152762ad123a901ef5c262dd38fe8d2"
+checksum = "c673075a2e0e5f4a1dde27ce9dee1ea4558c7ffe648f576438a20ca1d2acc4b0"
 dependencies = [
  "iana-time-zone",
  "num-traits",
@@ -362,11 +347,11 @@ checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
 [[package]]
 name = "core-graphics"
-version = "0.24.0"
+version = "0.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fa95a34622365fa5bbf40b20b75dba8dfa8c94c734aea8ac9a5ca38af14316f1"
+checksum = "064badf302c3194842cf2c5d61f56cc88e54a759313879cdf03abdd27d0c3b97"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "core-foundation",
  "core-graphics-types",
  "foreign-types",
@@ -379,7 +364,7 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "core-foundation",
  "libc",
 ]
@@ -451,7 +436,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13b588ba4ac1a99f7f2964d24b3d896ddc6bf847ee3855dbd4366f058cfcd331"
 dependencies = [
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -461,7 +446,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a2785755761f3ddc1492979ce1e48d2c00d09311c39e4466429188f3dd6501"
 dependencies = [
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -485,7 +470,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "strsim",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -496,14 +481,14 @@ checksum = "d38308df82d1080de0afee5d069fa14b0326a88c14f15c5ccda35b4a6c414c81"
 dependencies = [
  "darling_core",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "deranged"
-version = "0.5.5"
+version = "0.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ececcb659e7ba858fb4f10388c250a7252eb0a27373f1a72b8748afdd248e587"
+checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 dependencies = [
  "powerfmt",
  "serde_core",
@@ -519,7 +504,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "rustc_version",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -574,20 +559,16 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "dispatch"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd0c93bb4b0c6d9b77f4435b0ae98c24d17f1c45b2ff844c6151a07256ca923b"
-
 [[package]]
 name = "dispatch2"
-version = "0.3.0"
+version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89a09f22a6c6069a18470eb92d2298acf25463f14256d24778e1230d789a2aec"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
 dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
+ "bitflags 2.11.0",
+ "block2",
+ "libc",
+ "objc2",
 ]
 
 [[package]]
@@ -598,7 +579,7 @@ checksum = "97369cbbc041bc366949bc74d34658d6cda5621039731c6310521892a3a20ae0"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -621,7 +602,7 @@ checksum = "0fbbb781877580993a8707ec48672673ec7b81eeba04cfd2310bd28c08e47c8f"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -635,9 +616,9 @@ dependencies = [
 
 [[package]]
 name = "dtoa"
-version = "1.0.10"
+version = "1.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d6add3b8cff394282be81f3fc1a0605db594ed69890078ca6e2cab1c408bcf04"
+checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590"
 
 [[package]]
 name = "dtoa-short"
@@ -669,7 +650,7 @@ dependencies = [
  "cc",
  "memchr",
  "rustc_version",
- "toml 0.9.8",
+ "toml 0.9.12+spec-1.1.0",
  "vswhom",
  "winreg",
 ]
@@ -697,15 +678,25 @@ checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
 [[package]]
 name = "erased-serde"
-version = "0.4.9"
+version = "0.4.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89e8918065695684b2b0702da20382d5ae6065cf3327bc2d6436bd49a71ce9f3"
+checksum = "d2add8a07dd6a8d93ff627029c51de145e12686fbc36ecb298ac22e74cf02dec"
 dependencies = [
  "serde",
  "serde_core",
  "typeid",
 ]
 
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "fdeflate"
 version = "0.3.7"
@@ -727,15 +718,15 @@ dependencies = [
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.5"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a3076410a55c90011c298b04d0cfa770b00fa04e1e3c97d3f6c9de105a03844"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
 [[package]]
 name = "flate2"
-version = "1.1.5"
+version = "1.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bfe33edd8e85a12a67454e37f8c75e730830d83e313556ab9ebf9ee7fbeb3bfb"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
 dependencies = [
  "crc32fast",
  "miniz_oxide",
@@ -747,6 +738,12 @@ version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
 [[package]]
 name = "foreign-types"
 version = "0.5.0"
@@ -765,7 +762,7 @@ checksum = "1a5c6c585bc94aaf2c7b51dd4c2ba22680844aba4c687be581871a6f518c5742"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -795,24 +792,24 @@ dependencies = [
 
 [[package]]
 name = "futures-channel"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2dff15bf788c671c1934e366d07e30c1814a8ef514e1af724a602e8a2fbe1b10"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
 dependencies = [
  "futures-core",
 ]
 
 [[package]]
 name = "futures-core"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "05f29059c0c2090612e8d742178b0580d2dc940c837851ad723096f87af6663e"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
 
 [[package]]
 name = "futures-executor"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e28d1d997f585e54aebc3f97d39e72338912123a67330d723fdbb564d646c9f"
+checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
 dependencies = [
  "futures-core",
  "futures-task",
@@ -821,38 +818,38 @@ dependencies = [
 
 [[package]]
 name = "futures-io"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e5c1b78ca4aae1ac06c48a526a655760685149f0d465d21f37abfe57ce075c6"
+checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
 
 [[package]]
 name = "futures-macro"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "162ee34ebcb7c64a8abebc059ce0fee27c2262618d7b60ed8faf72fef13c3650"
+checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "futures-sink"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e575fab7d1e0dcb8d0c7bcf9a63ee213816ab51902e6d244a95819acacf1d4f7"
+checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
 
 [[package]]
 name = "futures-task"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f90f7dce0722e95104fcb095585910c0977252f286e354b5e3bd38902cd99988"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
 
 [[package]]
 name = "futures-util"
-version = "0.3.31"
+version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9fa08315bb612088cc391249efdc3bc77536f16c91f6cf495e6fbe85b20a4a81"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
 dependencies = [
  "futures-core",
  "futures-io",
@@ -861,7 +858,6 @@ dependencies = [
  "futures-task",
  "memchr",
  "pin-project-lite",
- "pin-utils",
  "slab",
 ]
 
@@ -996,9 +992,9 @@ dependencies = [
 
 [[package]]
 name = "getrandom"
-version = "0.2.16"
+version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
 dependencies = [
  "cfg-if",
  "libc",
@@ -1013,8 +1009,21 @@ checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
  "cfg-if",
  "libc",
- "r-efi",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 6.0.0",
  "wasip2",
+ "wasip3",
 ]
 
 [[package]]
@@ -1055,7 +1064,7 @@ version = "0.18.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "233daaf6e83ae6a12a52055f568f9d7cf4671dabb78ff9560ab6da230ce00ee5"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "futures-channel",
  "futures-core",
  "futures-executor",
@@ -1083,7 +1092,7 @@ dependencies = [
  "proc-macro-error",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -1162,7 +1171,7 @@ dependencies = [
  "proc-macro-error",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -1171,6 +1180,15 @@ version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
 
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.1"
@@ -1269,14 +1287,13 @@ dependencies = [
 
 [[package]]
 name = "hyper-util"
-version = "0.1.19"
+version = "0.1.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "727805d60e7938b76b826a6ef209eb70eaa1812794f9424d4a4e2d740662df5f"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
 dependencies = [
  "base64 0.22.1",
  "bytes",
  "futures-channel",
- "futures-core",
  "futures-util",
  "http",
  "http-body",
@@ -1293,9 +1310,9 @@ dependencies = [
 
 [[package]]
 name = "iana-time-zone"
-version = "0.1.64"
+version = "0.1.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33e57f83510bb73707521ebaffa789ec8caf86f9657cad665b092b581d40e9fb"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
 dependencies = [
  "android_system_properties",
  "core-foundation-sys",
@@ -1317,9 +1334,9 @@ dependencies = [
 
 [[package]]
 name = "ico"
-version = "0.4.0"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc50b891e4acf8fe0e71ef88ec43ad82ee07b3810ad09de10f1d01f072ed4b98"
+checksum = "3e795dff5605e0f04bff85ca41b51a96b83e80b281e96231bcaaf1ac35103371"
 dependencies = [
  "byteorder",
  "png 0.17.16",
@@ -1406,6 +1423,12 @@ dependencies = [
  "zerovec",
 ]
 
+[[package]]
+name = "id-arena"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
+
 [[package]]
 name = "ident_case"
 version = "1.0.1"
@@ -1443,7 +1466,7 @@ dependencies = [
  "byteorder-lite",
  "moxcms",
  "num-traits",
- "png 0.18.0",
+ "png 0.18.1",
 ]
 
 [[package]]
@@ -1459,9 +1482,9 @@ dependencies = [
 
 [[package]]
 name = "indexmap"
-version = "2.12.1"
+version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ad4bb2b565bca0645f4d68c5c9af97fba094e9791da685bf83cb5f3ce74acf2"
+checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
 dependencies = [
  "equivalent",
  "hashbrown 0.16.1",
@@ -1480,15 +1503,15 @@ dependencies = [
 
 [[package]]
 name = "ipnet"
-version = "2.11.0"
+version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "469fb0b9cefa57e3ef31275ee7cacb78f2fdca44e4765491884a2b119d4eb130"
+checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
 [[package]]
 name = "iri-string"
-version = "0.7.9"
+version = "0.7.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f867b9d1d896b67beb18518eda36fdb77a32ea590de864f1325b294a6d14397"
+checksum = "c91338f0783edbd6195decb37bae672fd3b165faffb89bf7b9e6942f8b1a731a"
 dependencies = [
  "memchr",
  "serde",
@@ -1515,9 +1538,9 @@ dependencies = [
 
 [[package]]
 name = "itoa"
-version = "1.0.15"
+version = "1.0.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
 
 [[package]]
 name = "javascriptcore-rs"
@@ -1566,9 +1589,9 @@ checksum = "8eaf4bc02d17cbdd7ff4c7438cafcdf7fb9a4613313ad11b4f8fefe7d3fa0130"
 
 [[package]]
 name = "js-sys"
-version = "0.3.83"
+version = "0.3.91"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "464a3709c7f55f1f721e5389aa6ea4e3bc6aba669353300af094b29ffbdde1d8"
+checksum = "b49715b7073f385ba4bc528e5747d02e66cb39c6146efb66b781f131f0fb399c"
 dependencies = [
  "once_cell",
  "wasm-bindgen",
@@ -1602,7 +1625,7 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b750dcadc39a09dbadd74e118f6dd6598df77fa01df0cfcdc52c28dece74528a"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "serde",
  "unicode-segmentation",
 ]
@@ -1615,15 +1638,15 @@ checksum = "02cb977175687f33fa4afa0c95c112b987ea1443e5a51c8f8ff27dc618270cc2"
 dependencies = [
  "cssparser",
  "html5ever",
- "indexmap 2.12.1",
+ "indexmap 2.13.0",
  "selectors",
 ]
 
 [[package]]
-name = "lazy_static"
-version = "1.5.0"
+name = "leb128fmt"
+version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libappindicator"
@@ -1651,9 +1674,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.178"
+version = "0.2.182"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37c93d8daa9d8a012fd8ab92f088405fb202ea0b6ab73ee2482ae66af4f42091"
+checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
 
 [[package]]
 name = "libloading"
@@ -1667,11 +1690,10 @@ dependencies = [
 
 [[package]]
 name = "libredox"
-version = "0.1.10"
+version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "416f7e718bdb06000964960ffa43b4335ad4012ae8b99060261aa4a8088d5ccb"
+checksum = "1744e39d1d6a9948f4f388969627434e31128196de472883b39f148769bfe30a"
 dependencies = [
- "bitflags 2.10.0",
  "libc",
 ]
 
@@ -1724,7 +1746,7 @@ checksum = "88a9689d8d44bf9964484516275f5cd4c9b59457a6940c1d5d0ecbb94510a36b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -1735,9 +1757,9 @@ checksum = "2532096657941c2fea9c289d370a250971c689d4f143798ff67113ec042024a5"
 
 [[package]]
 name = "memchr"
-version = "2.7.6"
+version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "memoffset"
@@ -1777,9 +1799,9 @@ dependencies = [
 
 [[package]]
 name = "moxcms"
-version = "0.7.10"
+version = "0.7.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "80986bbbcf925ebd3be54c26613d861255284584501595cf418320c078945608"
+checksum = "ac9557c559cd6fc9867e122e20d2cbefc9ca29d80d027a8e39310920ed2f0a97"
 dependencies = [
  "num-traits",
  "pxfm",
@@ -1795,14 +1817,14 @@ dependencies = [
  "dpi",
  "gtk",
  "keyboard-types",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
+ "objc2",
+ "objc2-app-kit",
  "objc2-core-foundation",
- "objc2-foundation 0.3.2",
+ "objc2-foundation",
  "once_cell",
  "png 0.17.16",
  "serde",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "windows-sys 0.60.2",
 ]
 
@@ -1812,7 +1834,7 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "jni-sys",
  "log",
  "ndk-sys",
@@ -1879,107 +1901,33 @@ version = "0.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ff32365de1b6743cb203b710788263c44a03de03802daf96092f2da4fe6ba4d7"
 dependencies = [
- "proc-macro-crate 3.4.0",
+ "proc-macro-crate 3.5.0",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
-]
-
-[[package]]
-name = "objc-sys"
-version = "0.3.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cdb91bdd390c7ce1a8607f35f3ca7151b65afc0ff5ff3b34fa350f7d7c7e4310"
-
-[[package]]
-name = "objc2"
-version = "0.5.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "46a785d4eeff09c14c487497c162e92766fbb3e4059a71840cecc03d9a50b804"
-dependencies = [
- "objc-sys",
- "objc2-encode",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "objc2"
-version = "0.6.3"
+version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7c2599ce0ec54857b29ce62166b0ed9b4f6f1a70ccc9a71165b6154caca8c05"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
 dependencies = [
  "objc2-encode",
  "objc2-exception-helper",
 ]
 
-[[package]]
-name = "objc2-app-kit"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e4e89ad9e3d7d297152b17d39ed92cd50ca8063a89a9fa569046d41568891eff"
-dependencies = [
- "bitflags 2.10.0",
- "block2 0.5.1",
- "libc",
- "objc2 0.5.2",
- "objc2-core-data 0.2.2",
- "objc2-core-image 0.2.2",
- "objc2-foundation 0.2.2",
- "objc2-quartz-core 0.2.2",
-]
-
 [[package]]
 name = "objc2-app-kit"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
 dependencies = [
- "bitflags 2.10.0",
- "block2 0.6.2",
- "libc",
- "objc2 0.6.3",
- "objc2-cloud-kit",
- "objc2-core-data 0.3.2",
+ "bitflags 2.11.0",
+ "block2",
+ "objc2",
  "objc2-core-foundation",
- "objc2-core-graphics",
- "objc2-core-image 0.3.2",
- "objc2-core-text",
- "objc2-core-video",
- "objc2-foundation 0.3.2",
- "objc2-quartz-core 0.3.2",
-]
-
-[[package]]
-name = "objc2-cloud-kit"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c"
-dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
- "objc2-foundation 0.3.2",
-]
-
-[[package]]
-name = "objc2-core-data"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "617fbf49e071c178c0b24c080767db52958f716d9eabdf0890523aeae54773ef"
-dependencies = [
- "bitflags 2.10.0",
- "block2 0.5.1",
- "objc2 0.5.2",
- "objc2-foundation 0.2.2",
-]
-
-[[package]]
-name = "objc2-core-data"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
-dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
- "objc2-foundation 0.3.2",
+ "objc2-foundation",
 ]
 
 [[package]]
@@ -1988,9 +1936,9 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "dispatch2",
- "objc2 0.6.3",
+ "objc2",
 ]
 
 [[package]]
@@ -1999,57 +1947,10 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "dispatch2",
- "objc2 0.6.3",
- "objc2-core-foundation",
- "objc2-io-surface",
-]
-
-[[package]]
-name = "objc2-core-image"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "55260963a527c99f1819c4f8e3b47fe04f9650694ef348ffd2227e8196d34c80"
-dependencies = [
- "block2 0.5.1",
- "objc2 0.5.2",
- "objc2-foundation 0.2.2",
- "objc2-metal",
-]
-
-[[package]]
-name = "objc2-core-image"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e5d563b38d2b97209f8e861173de434bd0214cf020e3423a52624cd1d989f006"
-dependencies = [
- "objc2 0.6.3",
- "objc2-foundation 0.3.2",
-]
-
-[[package]]
-name = "objc2-core-text"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d"
-dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
- "objc2-core-foundation",
- "objc2-core-graphics",
-]
-
-[[package]]
-name = "objc2-core-video"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
-dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
+ "objc2",
  "objc2-core-foundation",
- "objc2-core-graphics",
  "objc2-io-surface",
 ]
 
@@ -2068,28 +1969,15 @@ dependencies = [
  "cc",
 ]
 
-[[package]]
-name = "objc2-foundation"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ee638a5da3799329310ad4cfa62fbf045d5f56e3ef5ba4149e7452dcf89d5a8"
-dependencies = [
- "bitflags 2.10.0",
- "block2 0.5.1",
- "libc",
- "objc2 0.5.2",
-]
-
 [[package]]
 name = "objc2-foundation"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
 dependencies = [
- "bitflags 2.10.0",
- "block2 0.6.2",
- "libc",
- "objc2 0.6.3",
+ "bitflags 2.11.0",
+ "block2",
+ "objc2",
  "objc2-core-foundation",
 ]
 
@@ -2099,66 +1987,21 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
 dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
+ "bitflags 2.11.0",
+ "objc2",
  "objc2-core-foundation",
 ]
 
-[[package]]
-name = "objc2-javascript-core"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a1e6550c4caed348956ce3370c9ffeca70bb1dbed4fa96112e7c6170e074586"
-dependencies = [
- "objc2 0.6.3",
- "objc2-core-foundation",
-]
-
-[[package]]
-name = "objc2-metal"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd0cba1276f6023976a406a14ffa85e1fdd19df6b0f737b063b95f6c8c7aadd6"
-dependencies = [
- "bitflags 2.10.0",
- "block2 0.5.1",
- "objc2 0.5.2",
- "objc2-foundation 0.2.2",
-]
-
-[[package]]
-name = "objc2-quartz-core"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e42bee7bff906b14b167da2bac5efe6b6a07e6f7c0a21a7308d40c960242dc7a"
-dependencies = [
- "bitflags 2.10.0",
- "block2 0.5.1",
- "objc2 0.5.2",
- "objc2-foundation 0.2.2",
- "objc2-metal",
-]
-
 [[package]]
 name = "objc2-quartz-core"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "96c1358452b371bf9f104e21ec536d37a650eb10f7ee379fff67d2e08d537f1f"
 dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
- "objc2-foundation 0.3.2",
-]
-
-[[package]]
-name = "objc2-security"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "709fe137109bd1e8b5a99390f77a7d8b2961dafc1a1c5db8f2e60329ad6d895a"
-dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
+ "bitflags 2.11.0",
+ "objc2",
  "objc2-core-foundation",
+ "objc2-foundation",
 ]
 
 [[package]]
@@ -2167,10 +2010,10 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d87d638e33c06f577498cbcc50491496a3ed4246998a7fbba7ccb98b1e7eab22"
 dependencies = [
- "bitflags 2.10.0",
- "objc2 0.6.3",
+ "bitflags 2.11.0",
+ "objc2",
  "objc2-core-foundation",
- "objc2-foundation 0.3.2",
+ "objc2-foundation",
 ]
 
 [[package]]
@@ -2179,14 +2022,12 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b2e5aaab980c433cf470df9d7af96a7b46a9d892d521a2cbbb2f8a4c16751e7f"
 dependencies = [
- "bitflags 2.10.0",
- "block2 0.6.2",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
+ "bitflags 2.11.0",
+ "block2",
+ "objc2",
+ "objc2-app-kit",
  "objc2-core-foundation",
- "objc2-foundation 0.3.2",
- "objc2-javascript-core",
- "objc2-security",
+ "objc2-foundation",
 ]
 
 [[package]]
@@ -2209,7 +2050,7 @@ dependencies = [
  "tokio",
  "url",
  "uuid",
- "window-vibrancy 0.5.3",
+ "window-vibrancy 0.7.1",
 ]
 
 [[package]]
@@ -2404,7 +2245,7 @@ dependencies = [
  "phf_shared 0.11.3",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -2431,14 +2272,14 @@ version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
 dependencies = [
- "siphasher 1.0.1",
+ "siphasher 1.0.2",
 ]
 
 [[package]]
 name = "pin-project-lite"
-version = "0.2.16"
+version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b3cff922bd51709b605d9ead9aa71031d81447142d828eb4a6eba76fe619f9b"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
 [[package]]
 name = "pin-utils"
@@ -2459,7 +2300,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "740ebea15c5d1428f910cd1a5f52cebf8d25006245ed8ade92702f4943d91e07"
 dependencies = [
  "base64 0.22.1",
- "indexmap 2.12.1",
+ "indexmap 2.13.0",
  "quick-xml",
  "serde",
  "time",
@@ -2480,11 +2321,11 @@ dependencies = [
 
 [[package]]
 name = "png"
-version = "0.18.0"
+version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97baced388464909d42d89643fe4361939af9b7ce7a31ee32a168f832a70f2a0"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "crc32fast",
  "fdeflate",
  "flate2",
@@ -2521,6 +2362,16 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"
 
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "proc-macro-crate"
 version = "1.3.1"
@@ -2543,11 +2394,11 @@ dependencies = [
 
 [[package]]
 name = "proc-macro-crate"
-version = "3.4.0"
+version = "3.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "219cb19e96be00ab2e37d6e299658a0cfa83e52429179969b0f0121b4ac46983"
+checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
 dependencies = [
- "toml_edit 0.23.9",
+ "toml_edit 0.25.4+spec-1.1.0",
 ]
 
 [[package]]
@@ -2582,21 +2433,18 @@ checksum = "dc375e1527247fe1a97d8b7156678dfe7c1af2fc075c9a4db3690ecd2a148068"
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.103"
+version = "1.0.106"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ee95bc4ef87b8d5ba32e8b7714ccc834865276eab0aed5c9958d00ec45f49e8"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
 dependencies = [
  "unicode-ident",
 ]
 
 [[package]]
 name = "pxfm"
-version = "0.1.27"
+version = "0.1.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7186d3822593aa4393561d186d1393b3923e9d6163d3fbfd6e825e3e6cf3e6a8"
-dependencies = [
- "num-traits",
-]
+checksum = "b5a041e753da8b807c9255f28de81879c78c876392ff2469cde94799b2896b9d"
 
 [[package]]
 name = "quick-xml"
@@ -2609,9 +2457,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.42"
+version = "1.0.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
 dependencies = [
  "proc-macro2",
 ]
@@ -2622,6 +2470,12 @@ version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
 [[package]]
 name = "rand"
 version = "0.7.3"
@@ -2682,7 +2536,7 @@ version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
 dependencies = [
- "getrandom 0.2.16",
+ "getrandom 0.2.17",
 ]
 
 [[package]]
@@ -2715,7 +2569,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
 ]
 
 [[package]]
@@ -2724,7 +2578,7 @@ version = "0.4.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43"
 dependencies = [
- "getrandom 0.2.16",
+ "getrandom 0.2.17",
  "libredox",
  "thiserror 1.0.69",
 ]
@@ -2735,9 +2589,9 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
 dependencies = [
- "getrandom 0.2.16",
+ "getrandom 0.2.17",
  "libredox",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
 ]
 
 [[package]]
@@ -2757,14 +2611,14 @@ checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "regex"
-version = "1.12.2"
+version = "1.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "843bc0191f75f3e22651ae5f1e72939ab2f72a4bc30fa80a066bd66edefc24d4"
+checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2774,9 +2628,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.13"
+version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5276caf25ac86c8d810222b3dbb938e512c55c6831a10f3e6ed1c93b84041f1c"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2785,15 +2639,15 @@ dependencies = [
 
 [[package]]
 name = "regex-syntax"
-version = "0.8.8"
+version = "0.8.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7a2d987857b319362043e95f5353c0535c1f58eec5336fdfcf626430af7def58"
+checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
 [[package]]
 name = "reqwest"
-version = "0.12.25"
+version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6eff9328d40131d43bd911d42d79eb6a47312002a4daefc9e37f17e74a7701a"
+checksum = "ab3f43e3283ab1488b624b44b0e988d0acea0b3214e694730a055cb6b2efa801"
 dependencies = [
  "base64 0.22.1",
  "bytes",
@@ -2810,7 +2664,6 @@ dependencies = [
  "pin-project-lite",
  "serde",
  "serde_json",
- "serde_urlencoded",
  "sync_wrapper",
  "tokio",
  "tokio-util",
@@ -2839,12 +2692,6 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
-[[package]]
-name = "ryu"
-version = "1.0.20"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f"
-
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -2883,9 +2730,9 @@ dependencies = [
 
 [[package]]
 name = "schemars"
-version = "1.1.0"
+version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9558e172d4e8533736ba97870c4b2cd63f84b382a3d6eb063da41b91cce17289"
+checksum = "a2b42f36aa1cd011945615b92222f6bf73c599a102a300334cd7f8dbeec726cc"
 dependencies = [
  "dyn-clone",
  "ref-cast",
@@ -2902,7 +2749,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "serde_derive_internals",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -2978,7 +2825,7 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -2989,20 +2836,20 @@ checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.145"
+version = "1.0.149"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "402a6f66d8c709116cf22f558eab210f5a50187f702eb4d7e5ef38d9a7f1c79c"
+checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
 dependencies = [
  "itoa",
  "memchr",
- "ryu",
  "serde",
  "serde_core",
+ "zmij",
 ]
 
 [[package]]
@@ -3013,7 +2860,7 @@ checksum = "175ee3e80ae9982737ca543e96133087cbd9a485eecc3bc4de9c1a37b47ea59c"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -3027,38 +2874,26 @@ dependencies = [
 
 [[package]]
 name = "serde_spanned"
-version = "1.0.3"
+version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e24345aa0fe688594e73770a5f6d1b216508b4f93484c0026d521acd30134392"
+checksum = "f8bbf91e5a4d6315eee45e704372590b30e260ee83af6639d64557f51b067776"
 dependencies = [
  "serde_core",
 ]
 
-[[package]]
-name = "serde_urlencoded"
-version = "0.7.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
-dependencies = [
- "form_urlencoded",
- "itoa",
- "ryu",
- "serde",
-]
-
 [[package]]
 name = "serde_with"
-version = "3.16.1"
+version = "3.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fa237f2807440d238e0364a218270b98f767a00d3dada77b1c53ae88940e2e7"
+checksum = "381b283ce7bc6b476d903296fb59d0d36633652b633b27f64db4fb46dcbfc3b9"
 dependencies = [
  "base64 0.22.1",
  "chrono",
  "hex",
  "indexmap 1.9.3",
- "indexmap 2.12.1",
+ "indexmap 2.13.0",
  "schemars 0.9.0",
- "schemars 1.1.0",
+ "schemars 1.2.1",
  "serde_core",
  "serde_json",
  "serde_with_macros",
@@ -3067,14 +2902,14 @@ dependencies = [
 
 [[package]]
 name = "serde_with_macros"
-version = "3.16.1"
+version = "3.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52a8e3ca0ca629121f70ab50f95249e5a6f925cc0f6ffe8256c45b728875706c"
+checksum = "a6d4e30573c8cb306ed6ab1dca8423eec9a463ea0e155f45399455e0368b27e0"
 dependencies = [
  "darling",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -3096,7 +2931,7 @@ checksum = "772ee033c0916d670af7860b6e1ef7d658a4629a6d0b4c8c3e67f09b3765b75d"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -3160,10 +2995,11 @@ dependencies = [
 
 [[package]]
 name = "signal-hook-registry"
-version = "1.4.7"
+version = "1.4.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7664a098b8e616bdfcc2dc0e9ac44eb231eedf41db4e9fe95d8d32ec728dedad"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
 dependencies = [
+ "errno",
  "libc",
 ]
 
@@ -3181,15 +3017,15 @@ checksum = "38b58827f4464d87d377d175e90bf58eb00fd8716ff0a62f80356b5e61555d0d"
 
 [[package]]
 name = "siphasher"
-version = "1.0.1"
+version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "56199f7ddabf13fe5074ce809e7d3f42b42ae711800501b5b16ea82ad029c39d"
+checksum = "b2aa850e253778c88a04c3d7323b043aeda9d3e30d5971937c1855769763678e"
 
 [[package]]
 name = "slab"
-version = "0.4.11"
+version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7a2ae44ef20feb57a68b23d846850f861394c2e02dc425a50098ae8c90267589"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
@@ -3199,34 +3035,34 @@ checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
 [[package]]
 name = "socket2"
-version = "0.6.1"
+version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "17129e116933cf371d018bb80ae557e889637989d8638274fb25622827b03881"
+checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e"
 dependencies = [
  "libc",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "softbuffer"
-version = "0.4.6"
+version = "0.4.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "18051cdd562e792cad055119e0cdb2cfc137e44e3987532e0f9659a77931bb08"
+checksum = "aac18da81ebbf05109ab275b157c22a653bb3c12cf884450179942f81bcbf6c3"
 dependencies = [
  "bytemuck",
- "cfg_aliases",
- "core-graphics",
- "foreign-types",
  "js-sys",
- "log",
- "objc2 0.5.2",
- "objc2-foundation 0.2.2",
- "objc2-quartz-core 0.2.2",
+ "ndk",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-foundation",
+ "objc2-quartz-core",
  "raw-window-handle",
  "redox_syscall",
+ "tracing",
  "wasm-bindgen",
  "web-sys",
- "windows-sys 0.59.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3316,9 +3152,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.111"
+version = "2.0.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "390cc9a294ab71bdb1aa2e99d13be9c753cd2d7bd6560c77118597410c4d2e87"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3342,7 +3178,7 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -3360,35 +3196,33 @@ dependencies = [
 
 [[package]]
 name = "tao"
-version = "0.34.5"
+version = "0.34.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f3a753bdc39c07b192151523a3f77cd0394aa75413802c883a0f6f6a0e5ee2e7"
+checksum = "6e06d52c379e63da659a483a958110bbde891695a0ecb53e48cc7786d5eda7bb"
 dependencies = [
- "bitflags 2.10.0",
- "block2 0.6.2",
+ "bitflags 2.11.0",
+ "block2",
  "core-foundation",
  "core-graphics",
  "crossbeam-channel",
- "dispatch",
+ "dispatch2",
  "dlopen2",
  "dpi",
  "gdkwayland-sys",
  "gdkx11-sys",
  "gtk",
  "jni",
- "lazy_static",
  "libc",
  "log",
  "ndk",
  "ndk-context",
  "ndk-sys",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
- "objc2-foundation 0.3.2",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
  "once_cell",
  "parking_lot",
  "raw-window-handle",
- "scopeguard",
  "tao-macros",
  "unicode-segmentation",
  "url",
@@ -3406,7 +3240,7 @@ checksum = "f4e16beb8b2ac17db28eab8bca40e62dbfbb34c0fcdc6d9826b11b7b5d047dfd"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -3417,9 +3251,9 @@ checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
 
 [[package]]
 name = "tauri"
-version = "2.9.5"
+version = "2.10.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a3868da5508446a7cd08956d523ac3edf0a8bc20bf7e4038f9a95c2800d2033"
+checksum = "da77cc00fb9028caf5b5d4650f75e31f1ef3693459dfca7f7e506d1ecef0ba2d"
 dependencies = [
  "anyhow",
  "bytes",
@@ -3438,9 +3272,9 @@ dependencies = [
  "log",
  "mime",
  "muda",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
- "objc2-foundation 0.3.2",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
  "objc2-ui-kit",
  "objc2-web-kit",
  "percent-encoding",
@@ -3457,7 +3291,7 @@ dependencies = [
  "tauri-runtime",
  "tauri-runtime-wry",
  "tauri-utils",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "tokio",
  "tray-icon",
  "url",
@@ -3469,9 +3303,9 @@ dependencies = [
 
 [[package]]
 name = "tauri-build"
-version = "2.5.3"
+version = "2.5.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "17fcb8819fd16463512a12f531d44826ce566f486d7ccd211c9c8cebdaec4e08"
+checksum = "4bbc990d1dbf57a8e1c7fa2327f2a614d8b757805603c1b9ba5c81bade09fd4d"
 dependencies = [
  "anyhow",
  "cargo_toml",
@@ -3485,15 +3319,15 @@ dependencies = [
  "serde_json",
  "tauri-utils",
  "tauri-winres",
- "toml 0.9.8",
+ "toml 0.9.12+spec-1.1.0",
  "walkdir",
 ]
 
 [[package]]
 name = "tauri-codegen"
-version = "2.5.2"
+version = "2.5.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9fa9844cefcf99554a16e0a278156ae73b0d8680bbc0e2ad1e4287aadd8489cf"
+checksum = "d4a24476afd977c5d5d169f72425868613d82747916dd29e0a357c84c4bd6d29"
 dependencies = [
  "base64 0.22.1",
  "brotli",
@@ -3507,9 +3341,9 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2",
- "syn 2.0.111",
+ "syn 2.0.117",
  "tauri-utils",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "time",
  "url",
  "uuid",
@@ -3518,23 +3352,23 @@ dependencies = [
 
 [[package]]
 name = "tauri-macros"
-version = "2.5.2"
+version = "2.5.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3764a12f886d8245e66b7ee9b43ccc47883399be2019a61d80cf0f4117446fde"
+checksum = "d39b349a98dadaffebb73f0a40dcd1f23c999211e5a2e744403db384d0c33de7"
 dependencies = [
  "heck 0.5.0",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
  "tauri-codegen",
  "tauri-utils",
 ]
 
 [[package]]
 name = "tauri-plugin"
-version = "2.5.2"
+version = "2.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0e1d0a4860b7ff570c891e1d2a586bf1ede205ff858fbc305e0b5ae5d14c1377"
+checksum = "ddde7d51c907b940fb573006cdda9a642d6a7c8153657e88f8a5c3c9290cd4aa"
 dependencies = [
  "anyhow",
  "glob",
@@ -3543,15 +3377,15 @@ dependencies = [
  "serde",
  "serde_json",
  "tauri-utils",
- "toml 0.9.8",
+ "toml 0.9.12+spec-1.1.0",
  "walkdir",
 ]
 
 [[package]]
 name = "tauri-plugin-shell"
-version = "2.3.3"
+version = "2.3.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c374b6db45f2a8a304f0273a15080d98c70cde86178855fc24653ba657a1144c"
+checksum = "8457dbf9e2bab1edd8df22bb2c20857a59a9868e79cb3eac5ed639eec4d0c73b"
 dependencies = [
  "encoding_rs",
  "log",
@@ -3564,7 +3398,7 @@ dependencies = [
  "shared_child",
  "tauri",
  "tauri-plugin",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "tokio",
 ]
 
@@ -3574,34 +3408,34 @@ version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73736611e14142408d15353e21e3cca2f12a3cfb523ad0ce85999b6d2ef1a704"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "log",
  "serde",
  "serde_json",
  "tauri",
  "tauri-plugin",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
 ]
 
 [[package]]
 name = "tauri-runtime"
-version = "2.9.2"
+version = "2.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "87f766fe9f3d1efc4b59b17e7a891ad5ed195fa8d23582abb02e6c9a01137892"
+checksum = "2826d79a3297ed08cd6ea7f412644ef58e32969504bc4fbd8d7dbeabc4445ea2"
 dependencies = [
  "cookie",
  "dpi",
  "gtk",
  "http",
  "jni",
- "objc2 0.6.3",
+ "objc2",
  "objc2-ui-kit",
  "objc2-web-kit",
  "raw-window-handle",
  "serde",
  "serde_json",
  "tauri-utils",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "url",
  "webkit2gtk",
  "webview2-com",
@@ -3610,17 +3444,16 @@ dependencies = [
 
 [[package]]
 name = "tauri-runtime-wry"
-version = "2.9.3"
+version = "2.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "187a3f26f681bdf028f796ccf57cf478c1ee422c50128e5a0a6ebeb3f5910065"
+checksum = "e11ea2e6f801d275fdd890d6c9603736012742a1c33b96d0db788c9cdebf7f9e"
 dependencies = [
  "gtk",
  "http",
  "jni",
  "log",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
- "objc2-foundation 0.3.2",
+ "objc2",
+ "objc2-app-kit",
  "once_cell",
  "percent-encoding",
  "raw-window-handle",
@@ -3637,9 +3470,9 @@ dependencies = [
 
 [[package]]
 name = "tauri-utils"
-version = "2.8.1"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76a423c51176eb3616ee9b516a9fa67fed5f0e78baaba680e44eb5dd2cc37490"
+checksum = "219a1f983a2af3653f75b5747f76733b0da7ff03069c7a41901a5eb3ace4557d"
 dependencies = [
  "anyhow",
  "brotli",
@@ -3665,8 +3498,8 @@ dependencies = [
  "serde_json",
  "serde_with",
  "swift-rs",
- "thiserror 2.0.17",
- "toml 0.9.8",
+ "thiserror 2.0.18",
+ "toml 0.9.12+spec-1.1.0",
  "url",
  "urlpattern",
  "uuid",
@@ -3681,7 +3514,7 @@ checksum = "1087b111fe2b005e42dbdc1990fc18593234238d47453b0c99b7de1c9ab2c1e0"
 dependencies = [
  "dunce",
  "embed-resource",
- "toml 0.9.8",
+ "toml 0.9.12+spec-1.1.0",
 ]
 
 [[package]]
@@ -3706,11 +3539,11 @@ dependencies = [
 
 [[package]]
 name = "thiserror"
-version = "2.0.17"
+version = "2.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f63587ca0f12b72a0600bcba1d40081f830876000bb46dd2337a3051618f4fc8"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
 dependencies = [
- "thiserror-impl 2.0.17",
+ "thiserror-impl 2.0.18",
 ]
 
 [[package]]
@@ -3721,18 +3554,18 @@ checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "2.0.17"
+version = "2.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3ff15c8ecd7de3849db632e14d18d2571fa09dfc5ed93479bc4485c7a517c913"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -3778,9 +3611,9 @@ dependencies = [
 
 [[package]]
 name = "tokio"
-version = "1.48.0"
+version = "1.50.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ff360e02eab121e0bc37a2d3b4d4dc622e6eda3a8e5253d5435ecf5bd4c68408"
+checksum = "27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d"
 dependencies = [
  "bytes",
  "libc",
@@ -3792,9 +3625,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-util"
-version = "0.7.17"
+version = "0.7.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2efa149fe76073d6e8fd97ef4f4eca7b67f599660115591483572e406e165594"
+checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
 dependencies = [
  "bytes",
  "futures-core",
@@ -3817,17 +3650,17 @@ dependencies = [
 
 [[package]]
 name = "toml"
-version = "0.9.8"
+version = "0.9.12+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f0dc8b1fb61449e27716ec0e1bdf0f6b8f3e8f6b05391e8497b8b6d7804ea6d8"
+checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863"
 dependencies = [
- "indexmap 2.12.1",
+ "indexmap 2.13.0",
  "serde_core",
- "serde_spanned 1.0.3",
- "toml_datetime 0.7.3",
+ "serde_spanned 1.0.4",
+ "toml_datetime 0.7.5+spec-1.1.0",
  "toml_parser",
  "toml_writer",
- "winnow 0.7.14",
+ "winnow 0.7.15",
 ]
 
 [[package]]
@@ -3841,9 +3674,18 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "0.7.3"
+version = "0.7.5+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2cdb639ebbc97961c51720f858597f7f24c4fc295327923af55b74c3c724533"
+checksum = "92e1cfed4a3038bc5a127e35a2d360f145e1f4b971b551a2ba5fd7aedf7e1347"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "1.0.0+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32c2555c699578a4f59f0cc68e5116c8d7cabbd45e1409b989d4be085b53f13e"
 dependencies = [
  "serde_core",
 ]
@@ -3854,7 +3696,7 @@ version = "0.19.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1b5bb770da30e5cbfde35a2d7b9b8a2c4b8ef89548a7a6aeab5c9a576e3e7421"
 dependencies = [
- "indexmap 2.12.1",
+ "indexmap 2.13.0",
  "toml_datetime 0.6.3",
  "winnow 0.5.40",
 ]
@@ -3865,7 +3707,7 @@ version = "0.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "396e4d48bbb2b7554c944bde63101b5ae446cff6ec4a24227428f15eb72ef338"
 dependencies = [
- "indexmap 2.12.1",
+ "indexmap 2.13.0",
  "serde",
  "serde_spanned 0.6.9",
  "toml_datetime 0.6.3",
@@ -3874,36 +3716,36 @@ dependencies = [
 
 [[package]]
 name = "toml_edit"
-version = "0.23.9"
+version = "0.25.4+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d7cbc3b4b49633d57a0509303158ca50de80ae32c265093b24c414705807832"
+checksum = "7193cbd0ce53dc966037f54351dbbcf0d5a642c7f0038c382ef9e677ce8c13f2"
 dependencies = [
- "indexmap 2.12.1",
- "toml_datetime 0.7.3",
+ "indexmap 2.13.0",
+ "toml_datetime 1.0.0+spec-1.1.0",
  "toml_parser",
- "winnow 0.7.14",
+ "winnow 0.7.15",
 ]
 
 [[package]]
 name = "toml_parser"
-version = "1.0.4"
+version = "1.0.9+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c0cbe268d35bdb4bb5a56a2de88d0ad0eb70af5384a99d648cd4b3d04039800e"
+checksum = "702d4415e08923e7e1ef96cd5727c0dfed80b4d2fa25db9647fe5eb6f7c5a4c4"
 dependencies = [
- "winnow 0.7.14",
+ "winnow 0.7.15",
 ]
 
 [[package]]
 name = "toml_writer"
-version = "1.0.4"
+version = "1.0.6+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df8b2b54733674ad286d16267dcfc7a71ed5c776e4ac7aa3c3e2561f7c637bf2"
+checksum = "ab16f14aed21ee8bfd8ec22513f7287cd4a91aa92e44edfe2c17ddd004e92607"
 
 [[package]]
 name = "tower"
-version = "0.5.2"
+version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d039ad9159c98b70ecfd540b2573b97f7f52c3e8d9f8ad57a24b916a536975f9"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
 dependencies = [
  "futures-core",
  "futures-util",
@@ -3920,7 +3762,7 @@ version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
 dependencies = [
- "bitflags 2.10.0",
+ "bitflags 2.11.0",
  "bytes",
  "futures-util",
  "http",
@@ -3946,9 +3788,9 @@ checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
 
 [[package]]
 name = "tracing"
-version = "0.1.43"
+version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d15d90a0b5c19378952d479dc858407149d7bb45a14de0142f6c534b16fc647"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
  "pin-project-lite",
  "tracing-core",
@@ -3956,32 +3798,32 @@ dependencies = [
 
 [[package]]
 name = "tracing-core"
-version = "0.1.35"
+version = "0.1.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7a04e24fab5c89c6a36eb8558c9656f30d81de51dfa4d3b45f26b21d61fa0a6c"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
  "once_cell",
 ]
 
 [[package]]
 name = "tray-icon"
-version = "0.21.2"
+version = "0.21.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3d5572781bee8e3f994d7467084e1b1fd7a93ce66bd480f8156ba89dee55a2b"
+checksum = "a5e85aa143ceb072062fc4d6356c1b520a51d636e7bc8e77ec94be3608e5e80c"
 dependencies = [
  "crossbeam-channel",
  "dirs",
  "libappindicator",
  "muda",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
+ "objc2",
+ "objc2-app-kit",
  "objc2-core-foundation",
  "objc2-core-graphics",
- "objc2-foundation 0.3.2",
+ "objc2-foundation",
  "once_cell",
  "png 0.17.16",
  "serde",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "windows-sys 0.60.2",
 ]
 
@@ -4046,9 +3888,9 @@ dependencies = [
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.22"
+version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
 [[package]]
 name = "unicode-segmentation"
@@ -4056,16 +3898,23 @@ version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
 
+[[package]]
+name = "unicode-xid"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+
 [[package]]
 name = "url"
-version = "2.5.7"
+version = "2.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08bc136a29a3d1758e07a9cca267be308aeebf5cfd5a10f3f67ab2097683ef5b"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
 dependencies = [
  "form_urlencoded",
  "idna",
  "percent-encoding",
  "serde",
+ "serde_derive",
 ]
 
 [[package]]
@@ -4094,11 +3943,11 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
 name = "uuid"
-version = "1.19.0"
+version = "1.22.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2e054861b4bd027cd373e18e8d8d8e6548085000e41290d95ce0c373a654b4a"
+checksum = "a68d3c8f01c0cfa54a75291d83601161799e4a89a39e0929f4b0354d88757a37"
 dependencies = [
- "getrandom 0.3.4",
+ "getrandom 0.4.2",
  "js-sys",
  "serde_core",
  "wasm-bindgen",
@@ -4169,18 +4018,27 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "wasip2"
-version = "1.0.1+wasi-0.2.4"
+version = "1.0.2+wasi-0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasip3"
+version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0562428422c63773dad2c345a1882263bbf4d65cf3f42e90921f787ef5ad58e7"
+checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
 dependencies = [
  "wit-bindgen",
 ]
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.106"
+version = "0.2.114"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d759f433fa64a2d763d1340820e46e111a7a5ab75f993d1852d70b03dbb80fd"
+checksum = "6532f9a5c1ece3798cb1c2cfdba640b9b3ba884f5db45973a6f442510a87d38e"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -4191,11 +4049,12 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.56"
+version = "0.4.64"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "836d9622d604feee9e5de25ac10e3ea5f2d65b41eac0d9ce72eb5deae707ce7c"
+checksum = "e9c5522b3a28661442748e09d40924dfb9ca614b21c00d3fd135720e48b67db8"
 dependencies = [
  "cfg-if",
+ "futures-util",
  "js-sys",
  "once_cell",
  "wasm-bindgen",
@@ -4204,9 +4063,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.106"
+version = "0.2.114"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48cb0d2638f8baedbc542ed444afc0644a29166f1595371af4fecf8ce1e7eeb3"
+checksum = "18a2d50fcf105fb33bb15f00e7a77b772945a2ee45dcf454961fd843e74c18e6"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -4214,31 +4073,53 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.106"
+version = "0.2.114"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cefb59d5cd5f92d9dcf80e4683949f15ca4b511f4ac0a6e14d4e1ac60c6ecd40"
+checksum = "03ce4caeaac547cdf713d280eda22a730824dd11e6b8c3ca9e42247b25c631e3"
 dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
  "wasm-bindgen-shared",
 ]
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.106"
+version = "0.2.114"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cbc538057e648b67f72a982e708d485b2efa771e1ac05fec311f9f63e5800db4"
+checksum = "75a326b8c223ee17883a4251907455a2431acc2791c98c26279376490c378c16"
 dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "wasm-encoder"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
+dependencies = [
+ "leb128fmt",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasm-metadata"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
+dependencies = [
+ "anyhow",
+ "indexmap 2.13.0",
+ "wasm-encoder",
+ "wasmparser",
+]
+
 [[package]]
 name = "wasm-streams"
-version = "0.4.2"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb"
 dependencies = [
  "futures-util",
  "js-sys",
@@ -4247,11 +4128,23 @@ dependencies = [
  "web-sys",
 ]
 
+[[package]]
+name = "wasmparser"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
+dependencies = [
+ "bitflags 2.11.0",
+ "hashbrown 0.15.5",
+ "indexmap 2.13.0",
+ "semver",
+]
+
 [[package]]
 name = "web-sys"
-version = "0.3.83"
+version = "0.3.91"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9b32828d774c412041098d182a8b38b16ea816958e07cf40eec2bc080ae137ac"
+checksum = "854ba17bb104abfb26ba36da9729addc7ce7f06f5c0f90f3c391f8461cca21f9"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -4259,9 +4152,9 @@ dependencies = [
 
 [[package]]
 name = "webkit2gtk"
-version = "2.0.1"
+version = "2.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76b1bc1e54c581da1e9f179d0b38512ba358fb1af2d634a1affe42e37172361a"
+checksum = "a1027150013530fb2eaf806408df88461ae4815a45c541c8975e61d6f2fc4793"
 dependencies = [
  "bitflags 1.3.2",
  "cairo-rs",
@@ -4283,9 +4176,9 @@ dependencies = [
 
 [[package]]
 name = "webkit2gtk-sys"
-version = "2.0.1"
+version = "2.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "62daa38afc514d1f8f12b8693d30d5993ff77ced33ce30cd04deebc267a6d57c"
+checksum = "916a5f65c2ef0dfe12fff695960a2ec3d4565359fdbb2e9943c974e06c734ea5"
 dependencies = [
  "bitflags 1.3.2",
  "cairo-sys-rs",
@@ -4303,9 +4196,9 @@ dependencies = [
 
 [[package]]
 name = "webview2-com"
-version = "0.38.0"
+version = "0.38.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4ba622a989277ef3886dd5afb3e280e3dd6d974b766118950a08f8f678ad6a4"
+checksum = "7130243a7a5b33c54a444e54842e6a9e133de08b5ad7b5861cd8ed9a6a5bc96a"
 dependencies = [
  "webview2-com-macros",
  "webview2-com-sys",
@@ -4317,22 +4210,22 @@ dependencies = [
 
 [[package]]
 name = "webview2-com-macros"
-version = "0.8.0"
+version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d228f15bba3b9d56dde8bddbee66fa24545bd17b48d5128ccf4a8742b18e431"
+checksum = "67a921c1b6914c367b2b823cd4cde6f96beec77d30a939c8199bb377cf9b9b54"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
 name = "webview2-com-sys"
-version = "0.38.0"
+version = "0.38.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "36695906a1b53a3bf5c4289621efedac12b73eeb0b89e7e1a89b517302d5d75c"
+checksum = "381336cfffd772377d291702245447a5251a2ffa5bad679c99e61bc48bacbf9c"
 dependencies = [
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "windows",
  "windows-core 0.61.2",
 ]
@@ -4370,13 +4263,14 @@ checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
 [[package]]
 name = "window-vibrancy"
-version = "0.5.3"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "831ad7678290beae36be6f9fad9234139c7f00f3b536347de7745621716be82d"
+checksum = "d9bec5a31f3f9362f2258fd0e9c9dd61a9ca432e7306cc78c444258f0dce9a9c"
 dependencies = [
- "objc2 0.5.2",
- "objc2-app-kit 0.2.2",
- "objc2-foundation 0.2.2",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
  "raw-window-handle",
  "windows-sys 0.59.0",
  "windows-version",
@@ -4384,16 +4278,16 @@ dependencies = [
 
 [[package]]
 name = "window-vibrancy"
-version = "0.6.0"
+version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9bec5a31f3f9362f2258fd0e9c9dd61a9ca432e7306cc78c444258f0dce9a9c"
+checksum = "010797bd7c40396fbc59d3105089fed0885fe267a0ef4a0a4646df54e28647f6"
 dependencies = [
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
+ "objc2",
+ "objc2-app-kit",
  "objc2-core-foundation",
- "objc2-foundation 0.3.2",
+ "objc2-foundation",
  "raw-window-handle",
- "windows-sys 0.59.0",
+ "windows-sys 0.60.2",
  "windows-version",
 ]
 
@@ -4464,7 +4358,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -4475,7 +4369,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -4853,9 +4747,9 @@ dependencies = [
 
 [[package]]
 name = "winnow"
-version = "0.7.14"
+version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a5364e9d77fcdeeaa6062ced926ee3381faa2ee02d3eb83a5c27a8825540829"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 dependencies = [
  "memchr",
 ]
@@ -4872,9 +4766,91 @@ dependencies = [
 
 [[package]]
 name = "wit-bindgen"
-version = "0.46.0"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
+dependencies = [
+ "wit-bindgen-rust-macro",
+]
+
+[[package]]
+name = "wit-bindgen-core"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
+dependencies = [
+ "anyhow",
+ "heck 0.5.0",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-bindgen-rust"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
+dependencies = [
+ "anyhow",
+ "heck 0.5.0",
+ "indexmap 2.13.0",
+ "prettyplease",
+ "syn 2.0.117",
+ "wasm-metadata",
+ "wit-bindgen-core",
+ "wit-component",
+]
+
+[[package]]
+name = "wit-bindgen-rust-macro"
+version = "0.51.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
+checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a"
+dependencies = [
+ "anyhow",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+ "wit-bindgen-core",
+ "wit-bindgen-rust",
+]
+
+[[package]]
+name = "wit-component"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
+dependencies = [
+ "anyhow",
+ "bitflags 2.11.0",
+ "indexmap 2.13.0",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "wasm-encoder",
+ "wasm-metadata",
+ "wasmparser",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-parser"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
+dependencies = [
+ "anyhow",
+ "id-arena",
+ "indexmap 2.13.0",
+ "log",
+ "semver",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "unicode-xid",
+ "wasmparser",
+]
 
 [[package]]
 name = "writeable"
@@ -4884,12 +4860,12 @@ checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
 
 [[package]]
 name = "wry"
-version = "0.53.5"
+version = "0.54.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "728b7d4c8ec8d81cab295e0b5b8a4c263c0d41a785fb8f8c4df284e5411140a2"
+checksum = "bb26159b420aa77684589a744ae9a9461a95395b848764ad12290a14d960a11a"
 dependencies = [
  "base64 0.22.1",
- "block2 0.6.2",
+ "block2",
  "cookie",
  "crossbeam-channel",
  "dirs",
@@ -4904,10 +4880,10 @@ dependencies = [
  "kuchikiki",
  "libc",
  "ndk",
- "objc2 0.6.3",
- "objc2-app-kit 0.3.2",
+ "objc2",
+ "objc2-app-kit",
  "objc2-core-foundation",
- "objc2-foundation 0.3.2",
+ "objc2-foundation",
  "objc2-ui-kit",
  "objc2-web-kit",
  "once_cell",
@@ -4916,7 +4892,7 @@ dependencies = [
  "sha2",
  "soup3",
  "tao-macros",
- "thiserror 2.0.17",
+ "thiserror 2.0.18",
  "url",
  "webkit2gtk",
  "webkit2gtk-sys",
@@ -4967,28 +4943,28 @@ checksum = "b659052874eb698efe5b9e8cf382204678a0086ebf46982b79d6ca3182927e5d"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
  "synstructure",
 ]
 
 [[package]]
 name = "zerocopy"
-version = "0.8.31"
+version = "0.8.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fd74ec98b9250adb3ca554bdde269adf631549f51d8a8f8f0a10b50f1cb298c3"
+checksum = "a789c6e490b576db9f7e6b6d661bcc9799f7c0ac8352f56ea20193b2681532e5"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.31"
+version = "0.8.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d8a8d209fdf45cf5138cbb5a506f6b52522a25afccc534d1475dad8e31105c6a"
+checksum = "f65c489a7071a749c849713807783f70672b28094011623e200cb86dcb835953"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -5008,7 +4984,7 @@ checksum = "d71e5d6e06ab090c67b5e44993ec16b72dcbaabc526db883a360057678b48502"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
  "synstructure",
 ]
 
@@ -5042,5 +5018,11 @@ checksum = "eadce39539ca5cb3985590102671f2567e659fca9666581ad3411d59207951f3"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.111",
+ "syn 2.0.117",
 ]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index fe84604ca33..37de2156aab 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -6,18 +6,18 @@ authors = ["you"]
 edition = "2021"
 
 [build-dependencies]
-tauri-build = { version = "2.0", features = [] }
+tauri-build = { version = "2.5", features = [] }
 
 [dependencies]
-tauri = { version = "2.0", features = ["macos-private-api", "tray-icon", "image-png"] }
-tauri-plugin-shell = "2.0"
-tauri-plugin-window-state = "2.0"
+tauri = { version = "2.10", features = ["macos-private-api", "tray-icon", "image-png"] }
+tauri-plugin-shell = "2.3.5"
+tauri-plugin-window-state = "2.4.1"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 uuid = { version = "1.0", features = ["v4"] }
 directories = "5.0"
 tokio = { version = "1", features = ["time"] }
-window-vibrancy = "0.5"
+window-vibrancy = "0.7.1"
 url = "2.5"
 
 [features]

From a615a920cb8622ccdb72a59a7e7cfdd7bd963e95 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 6 Mar 2026 11:13:21 -0800
Subject: [PATCH 151/267] chore(deps): bump express-rate-limit from 8.2.1 to
 8.3.0 in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#9143)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../docker/templates/outputs/web/package-lock.json | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index adb3fd12c99..f5830244ef5 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -6758,12 +6758,12 @@
       }
     },
     "node_modules/express-rate-limit": {
-      "version": "8.2.1",
-      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.2.1.tgz",
-      "integrity": "sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==",
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.0.tgz",
+      "integrity": "sha512-KJzBawY6fB9FiZGdE/0aftepZ91YlaGIrV8vgblRM3J8X+dHx/aiowJWwkx6LIGyuqGiANsjSwwrbb8mifOJ4Q==",
       "license": "MIT",
       "dependencies": {
-        "ip-address": "10.0.1"
+        "ip-address": "10.1.0"
       },
       "engines": {
         "node": ">= 16"
@@ -7556,9 +7556,9 @@
       }
     },
     "node_modules/ip-address": {
-      "version": "10.0.1",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.0.1.tgz",
-      "integrity": "sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==",
+      "version": "10.1.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
+      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"

From 1a7ca93b93a73bbbbdaa7adefa576a87d693f5db Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 6 Mar 2026 11:14:33 -0800
Subject: [PATCH 152/267] chore(deps): bump @tootallnate/once and
 jest-environment-jsdom in /web (#9050)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 web/package-lock.json                         | 928 +++++++++++++-----
 web/package.json                              |   2 +-
 .../app/auth/login/EmailPasswordForm.test.tsx |  10 +-
 3 files changed, 704 insertions(+), 236 deletions(-)

diff --git a/web/package-lock.json b/web/package-lock.json
index 30b3b0abf3b..893bb21683d 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -116,7 +116,7 @@
         "eslint-plugin-unused-imports": "^4.1.4",
         "identity-obj-proxy": "^3.0.0",
         "jest": "^29.7.0",
-        "jest-environment-jsdom": "^29.7.0",
+        "jest-environment-jsdom": "^30.2.0",
         "prettier": "3.1.0",
         "stats.js": "^0.17.0",
         "tailwindcss": "^3.4.17",
@@ -162,6 +162,27 @@
         "module-details-from-path": "^1.0.4"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-3.2.0.tgz",
+      "integrity": "sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/css-calc": "^2.1.3",
+        "@csstools/css-color-parser": "^3.0.9",
+        "@csstools/css-parser-algorithms": "^3.0.4",
+        "@csstools/css-tokenizer": "^3.0.3",
+        "lru-cache": "^10.4.3"
+      }
+    },
+    "node_modules/@asamuzakjp/css-color/node_modules/lru-cache": {
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.27.1",
       "license": "MIT",
@@ -593,6 +614,121 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@csstools/color-helpers": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-5.1.0.tgz",
+      "integrity": "sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-2.1.4.tgz",
+      "integrity": "sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-3.1.0.tgz",
+      "integrity": "sha512-nbtKwh3a6xNVIp/VRuXV64yTKnb1IjTAEEh3irzS+HkKjAOYLTGNb9pmVNntZ8iVBHcWDA2Dof0QtPgFI1BaTA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^5.1.0",
+        "@csstools/css-calc": "^2.1.4"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "3.0.5",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz",
+      "integrity": "sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz",
+      "integrity": "sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@date-fns/tz": {
       "version": "1.4.1",
       "license": "MIT"
@@ -1774,6 +1910,202 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/@jest/environment-jsdom-abstract": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/environment-jsdom-abstract/-/environment-jsdom-abstract-30.2.0.tgz",
+      "integrity": "sha512-kazxw2L9IPuZpQ0mEt9lu9Z98SqR74xcagANmMBU16X0lS23yPc0+S6hGLUz8kVRlomZEs/5S/Zlpqwf5yu6OQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/environment": "30.2.0",
+        "@jest/fake-timers": "30.2.0",
+        "@jest/types": "30.2.0",
+        "@types/jsdom": "^21.1.7",
+        "@types/node": "*",
+        "jest-mock": "30.2.0",
+        "jest-util": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.0.0",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/@jest/environment": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/environment/-/environment-30.2.0.tgz",
+      "integrity": "sha512-/QPTL7OBJQ5ac09UDRa3EQes4gt1FTEG/8jZ/4v5IVzx+Cv7dLxlVIvfvSVRiiX2drWyXeBjkMSR8hvOWSog5g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/fake-timers": "30.2.0",
+        "@jest/types": "30.2.0",
+        "@types/node": "*",
+        "jest-mock": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/@jest/fake-timers": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/fake-timers/-/fake-timers-30.2.0.tgz",
+      "integrity": "sha512-HI3tRLjRxAbBy0VO8dqqm7Hb2mIa8d5bg/NJkyQcOk7V118ObQML8RC5luTF/Zsg4474a+gDvhce7eTnP4GhYw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/types": "30.2.0",
+        "@sinonjs/fake-timers": "^13.0.0",
+        "@types/node": "*",
+        "jest-message-util": "30.2.0",
+        "jest-mock": "30.2.0",
+        "jest-util": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/@jest/schemas": {
+      "version": "30.0.5",
+      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-30.0.5.tgz",
+      "integrity": "sha512-DmdYgtezMkh3cpU8/1uyXakv3tJRcmcXxBOcO0tbaozPwpmh4YMsnWrQm9ZmZMfa5ocbxzbFk6O4bDPEc/iAnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@sinclair/typebox": "^0.34.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/@jest/types": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/types/-/types-30.2.0.tgz",
+      "integrity": "sha512-H9xg1/sfVvyfU7o3zMfBEjQ1gcsdeTMgqHoYdN79tuLqfTtuu7WckRA1R5whDwOzxaZAeMKTYWqP+WCAi0CHsg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/pattern": "30.0.1",
+        "@jest/schemas": "30.0.5",
+        "@types/istanbul-lib-coverage": "^2.0.6",
+        "@types/istanbul-reports": "^3.0.4",
+        "@types/node": "*",
+        "@types/yargs": "^17.0.33",
+        "chalk": "^4.1.2"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/@sinclair/typebox": {
+      "version": "0.34.48",
+      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.48.tgz",
+      "integrity": "sha512-kKJTNuK3AQOrgjjotVxMrCn1sUJwM76wMszfq1kdU4uYVJjvEWuFQ6HgvLt4Xz3fSmZlTOxJ/Ie13KnIcWQXFA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/@sinonjs/fake-timers": {
+      "version": "13.0.5",
+      "resolved": "https://registry.npmjs.org/@sinonjs/fake-timers/-/fake-timers-13.0.5.tgz",
+      "integrity": "sha512-36/hTbH2uaWuGVERyC6da9YwGWnzUZXuPro/F2LfsdOsLnCojz/iSH8MxUt/FD2S5XBSVPhmArFUXcpCQ2Hkiw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@sinonjs/commons": "^3.0.1"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/ci-info": {
+      "version": "4.4.0",
+      "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-4.4.0.tgz",
+      "integrity": "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/sibiraj-s"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/jest-message-util": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-message-util/-/jest-message-util-30.2.0.tgz",
+      "integrity": "sha512-y4DKFLZ2y6DxTWD4cDe07RglV88ZiNEdlRfGtqahfbIjfsw1nMCPx49Uev4IA/hWn3sDKyAnSPwoYSsAEdcimw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.27.1",
+        "@jest/types": "30.2.0",
+        "@types/stack-utils": "^2.0.3",
+        "chalk": "^4.1.2",
+        "graceful-fs": "^4.2.11",
+        "micromatch": "^4.0.8",
+        "pretty-format": "30.2.0",
+        "slash": "^3.0.0",
+        "stack-utils": "^2.0.6"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/jest-mock": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-mock/-/jest-mock-30.2.0.tgz",
+      "integrity": "sha512-JNNNl2rj4b5ICpmAcq+WbLH83XswjPbjH4T7yvGzfAGCPh1rw+xVNbtk+FnRslvt9lkCcdn9i1oAoKUuFsOxRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/types": "30.2.0",
+        "@types/node": "*",
+        "jest-util": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/jest-util": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-util/-/jest-util-30.2.0.tgz",
+      "integrity": "sha512-QKNsM0o3Xe6ISQU869e+DhG+4CK/48aHYdJZGlFQVTjnbvgpcKyxpzk29fGiO7i/J8VENZ+d2iGnSsvmuHywlA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/types": "30.2.0",
+        "@types/node": "*",
+        "chalk": "^4.1.2",
+        "ci-info": "^4.2.0",
+        "graceful-fs": "^4.2.11",
+        "picomatch": "^4.0.2"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/environment-jsdom-abstract/node_modules/pretty-format": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-30.2.0.tgz",
+      "integrity": "sha512-9uBdv/B4EefsuAL+pWqueZyZS2Ba+LxfFeQ9DN14HU4bN8bhaxKdkpjpB6fs9+pSjIBu+FXQHImEg8j/Lw0+vA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/schemas": "30.0.5",
+        "ansi-styles": "^5.2.0",
+        "react-is": "^18.3.1"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
     "node_modules/@jest/expect": {
       "version": "29.7.0",
       "dev": true,
@@ -1827,6 +2159,30 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/@jest/pattern": {
+      "version": "30.0.1",
+      "resolved": "https://registry.npmjs.org/@jest/pattern/-/pattern-30.0.1.tgz",
+      "integrity": "sha512-gWp7NfQW27LaBQz3TITS8L7ZCQ0TLvtmI//4OwlQRx4rnWxcPNIYjxZpDcN4+UlGxgm3jS5QPz8IPTCkb59wZA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "jest-regex-util": "30.0.1"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@jest/pattern/node_modules/jest-regex-util": {
+      "version": "30.0.1",
+      "resolved": "https://registry.npmjs.org/jest-regex-util/-/jest-regex-util-30.0.1.tgz",
+      "integrity": "sha512-jHEQgBXAgc+Gh4g0p3bCevgRCVRkB4VB70zhoAE48gxeSr1hfUOsM/C2WoJgVL7Eyg//hudYENbm3Ne+/dRVVA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
     "node_modules/@jest/reporters": {
       "version": "29.7.0",
       "dev": true,
@@ -5197,14 +5553,6 @@
         "@testing-library/dom": ">=7.21.4"
       }
     },
-    "node_modules/@tootallnate/once": {
-      "version": "2.0.0",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 10"
-      }
-    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.1",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
@@ -5437,7 +5785,9 @@
       "license": "MIT"
     },
     "node_modules/@types/jsdom": {
-      "version": "20.0.1",
+      "version": "21.1.7",
+      "resolved": "https://registry.npmjs.org/@types/jsdom/-/jsdom-21.1.7.tgz",
+      "integrity": "sha512-yOriVnggzrnQ3a9OKOCxaVuSug3w3/SbOj5i7VwXWZEyUNl3bLF9V3MfxGbZKuwqJOQyRfqXyROBB1CoZLFWzA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -5571,6 +5921,8 @@
     },
     "node_modules/@types/tough-cookie": {
       "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/@types/tough-cookie/-/tough-cookie-4.0.5.tgz",
+      "integrity": "sha512-/Ad8+nIOV7Rl++6f1BdKxFSMgmoqEoYbHRpPcx3JEfv8VRsQe9Z4mCXeJBzxs7mbHY/XOZZuXlRNfhpVPbs6ZA==",
       "dev": true,
       "license": "MIT"
     },
@@ -6374,11 +6726,6 @@
       "license": "Apache-2.0",
       "peer": true
     },
-    "node_modules/abab": {
-      "version": "2.0.6",
-      "dev": true,
-      "license": "BSD-3-Clause"
-    },
     "node_modules/acorn": {
       "version": "8.15.0",
       "license": "MIT",
@@ -6389,15 +6736,6 @@
         "node": ">=0.4.0"
       }
     },
-    "node_modules/acorn-globals": {
-      "version": "7.0.1",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "acorn": "^8.1.0",
-        "acorn-walk": "^8.0.2"
-      }
-    },
     "node_modules/acorn-import-attributes": {
       "version": "1.9.5",
       "resolved": "https://registry.npmjs.org/acorn-import-attributes/-/acorn-import-attributes-1.9.5.tgz",
@@ -6426,17 +6764,6 @@
         "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
       }
     },
-    "node_modules/acorn-walk": {
-      "version": "8.3.4",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "acorn": "^8.11.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
     "node_modules/agent-base": {
       "version": "6.0.2",
       "license": "MIT",
@@ -6743,11 +7070,6 @@
         "node": ">= 0.4"
       }
     },
-    "node_modules/asynckit": {
-      "version": "0.4.0",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/attr-accept": {
       "version": "2.2.5",
       "license": "MIT",
@@ -7435,17 +7757,6 @@
         "simple-swizzle": "^0.2.2"
       }
     },
-    "node_modules/combined-stream": {
-      "version": "1.0.8",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "delayed-stream": "~1.0.0"
-      },
-      "engines": {
-        "node": ">= 0.8"
-      }
-    },
     "node_modules/comma-separated-tokens": {
       "version": "2.0.3",
       "license": "MIT",
@@ -7591,27 +7902,20 @@
         "node": ">=4"
       }
     },
-    "node_modules/cssom": {
-      "version": "0.5.0",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/cssstyle": {
-      "version": "2.3.0",
+      "version": "4.6.0",
+      "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-4.6.0.tgz",
+      "integrity": "sha512-2z+rWdzbbSZv6/rhtvzvqeZQHrBaqgogqt85sqFNbabZOuFbCVFb8kPeEtZjiKkbrm395irpNKiYeFeLiQnFPg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "cssom": "~0.3.6"
+        "@asamuzakjp/css-color": "^3.2.0",
+        "rrweb-cssom": "^0.8.0"
       },
       "engines": {
-        "node": ">=8"
+        "node": ">=18"
       }
     },
-    "node_modules/cssstyle/node_modules/cssom": {
-      "version": "0.3.8",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/csstype": {
       "version": "3.1.3",
       "license": "MIT"
@@ -7721,16 +8025,17 @@
       "license": "BSD-2-Clause"
     },
     "node_modules/data-urls": {
-      "version": "3.0.2",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-5.0.0.tgz",
+      "integrity": "sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "abab": "^2.0.6",
-        "whatwg-mimetype": "^3.0.0",
-        "whatwg-url": "^11.0.0"
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^14.0.0"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/data-view-buffer": {
@@ -7812,6 +8117,8 @@
     },
     "node_modules/decimal.js": {
       "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
       "dev": true,
       "license": "MIT"
     },
@@ -7887,14 +8194,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/delayed-stream": {
-      "version": "1.0.0",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
     "node_modules/dequal": {
       "version": "2.0.3",
       "license": "MIT",
@@ -7981,17 +8280,6 @@
         "csstype": "^3.0.2"
       }
     },
-    "node_modules/domexception": {
-      "version": "4.0.0",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "webidl-conversions": "^7.0.0"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
     "node_modules/dotenv": {
       "version": "16.6.1",
       "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
@@ -8251,26 +8539,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/escodegen": {
-      "version": "2.1.0",
-      "dev": true,
-      "license": "BSD-2-Clause",
-      "dependencies": {
-        "esprima": "^4.0.1",
-        "estraverse": "^5.2.0",
-        "esutils": "^2.0.2"
-      },
-      "bin": {
-        "escodegen": "bin/escodegen.js",
-        "esgenerate": "bin/esgenerate.js"
-      },
-      "engines": {
-        "node": ">=6.0"
-      },
-      "optionalDependencies": {
-        "source-map": "~0.6.1"
-      }
-    },
     "node_modules/eslint": {
       "version": "9.39.1",
       "dev": true,
@@ -8999,21 +9267,6 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/form-data": {
-      "version": "4.0.4",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "asynckit": "^0.4.0",
-        "combined-stream": "^1.0.8",
-        "es-set-tostringtag": "^2.1.0",
-        "hasown": "^2.0.2",
-        "mime-types": "^2.1.12"
-      },
-      "engines": {
-        "node": ">= 6"
-      }
-    },
     "node_modules/formik": {
       "version": "2.4.6",
       "funding": [
@@ -9671,14 +9924,16 @@
       }
     },
     "node_modules/html-encoding-sniffer": {
-      "version": "3.0.0",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz",
+      "integrity": "sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "whatwg-encoding": "^2.0.0"
+        "whatwg-encoding": "^3.1.1"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/html-escaper": {
@@ -9703,16 +9958,27 @@
       }
     },
     "node_modules/http-proxy-agent": {
-      "version": "5.0.0",
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
+      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@tootallnate/once": "2",
-        "agent-base": "6",
-        "debug": "4"
+        "agent-base": "^7.1.0",
+        "debug": "^4.3.4"
       },
       "engines": {
-        "node": ">= 6"
+        "node": ">= 14"
+      }
+    },
+    "node_modules/http-proxy-agent/node_modules/agent-base": {
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
       }
     },
     "node_modules/https": {
@@ -9742,6 +10008,8 @@
     },
     "node_modules/iconv-lite": {
       "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -10190,6 +10458,8 @@
     },
     "node_modules/is-potential-custom-element-name": {
       "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
       "dev": true,
       "license": "MIT"
     },
@@ -10649,24 +10919,23 @@
       }
     },
     "node_modules/jest-environment-jsdom": {
-      "version": "29.7.0",
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-environment-jsdom/-/jest-environment-jsdom-30.2.0.tgz",
+      "integrity": "sha512-zbBTiqr2Vl78pKp/laGBREYzbZx9ZtqPjOK4++lL4BNDhxRnahg51HtoDrk9/VjIy9IthNEWdKVd7H5bqBhiWQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@jest/environment": "^29.7.0",
-        "@jest/fake-timers": "^29.7.0",
-        "@jest/types": "^29.6.3",
-        "@types/jsdom": "^20.0.0",
+        "@jest/environment": "30.2.0",
+        "@jest/environment-jsdom-abstract": "30.2.0",
+        "@types/jsdom": "^21.1.7",
         "@types/node": "*",
-        "jest-mock": "^29.7.0",
-        "jest-util": "^29.7.0",
-        "jsdom": "^20.0.0"
+        "jsdom": "^26.1.0"
       },
       "engines": {
-        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
       },
       "peerDependencies": {
-        "canvas": "^2.5.0"
+        "canvas": "^3.0.0"
       },
       "peerDependenciesMeta": {
         "canvas": {
@@ -10674,6 +10943,174 @@
         }
       }
     },
+    "node_modules/jest-environment-jsdom/node_modules/@jest/environment": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/environment/-/environment-30.2.0.tgz",
+      "integrity": "sha512-/QPTL7OBJQ5ac09UDRa3EQes4gt1FTEG/8jZ/4v5IVzx+Cv7dLxlVIvfvSVRiiX2drWyXeBjkMSR8hvOWSog5g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/fake-timers": "30.2.0",
+        "@jest/types": "30.2.0",
+        "@types/node": "*",
+        "jest-mock": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/@jest/fake-timers": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/fake-timers/-/fake-timers-30.2.0.tgz",
+      "integrity": "sha512-HI3tRLjRxAbBy0VO8dqqm7Hb2mIa8d5bg/NJkyQcOk7V118ObQML8RC5luTF/Zsg4474a+gDvhce7eTnP4GhYw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/types": "30.2.0",
+        "@sinonjs/fake-timers": "^13.0.0",
+        "@types/node": "*",
+        "jest-message-util": "30.2.0",
+        "jest-mock": "30.2.0",
+        "jest-util": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/@jest/schemas": {
+      "version": "30.0.5",
+      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-30.0.5.tgz",
+      "integrity": "sha512-DmdYgtezMkh3cpU8/1uyXakv3tJRcmcXxBOcO0tbaozPwpmh4YMsnWrQm9ZmZMfa5ocbxzbFk6O4bDPEc/iAnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@sinclair/typebox": "^0.34.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/@jest/types": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/@jest/types/-/types-30.2.0.tgz",
+      "integrity": "sha512-H9xg1/sfVvyfU7o3zMfBEjQ1gcsdeTMgqHoYdN79tuLqfTtuu7WckRA1R5whDwOzxaZAeMKTYWqP+WCAi0CHsg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/pattern": "30.0.1",
+        "@jest/schemas": "30.0.5",
+        "@types/istanbul-lib-coverage": "^2.0.6",
+        "@types/istanbul-reports": "^3.0.4",
+        "@types/node": "*",
+        "@types/yargs": "^17.0.33",
+        "chalk": "^4.1.2"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/@sinclair/typebox": {
+      "version": "0.34.48",
+      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.48.tgz",
+      "integrity": "sha512-kKJTNuK3AQOrgjjotVxMrCn1sUJwM76wMszfq1kdU4uYVJjvEWuFQ6HgvLt4Xz3fSmZlTOxJ/Ie13KnIcWQXFA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/jest-environment-jsdom/node_modules/@sinonjs/fake-timers": {
+      "version": "13.0.5",
+      "resolved": "https://registry.npmjs.org/@sinonjs/fake-timers/-/fake-timers-13.0.5.tgz",
+      "integrity": "sha512-36/hTbH2uaWuGVERyC6da9YwGWnzUZXuPro/F2LfsdOsLnCojz/iSH8MxUt/FD2S5XBSVPhmArFUXcpCQ2Hkiw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@sinonjs/commons": "^3.0.1"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/ci-info": {
+      "version": "4.4.0",
+      "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-4.4.0.tgz",
+      "integrity": "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/sibiraj-s"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/jest-message-util": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-message-util/-/jest-message-util-30.2.0.tgz",
+      "integrity": "sha512-y4DKFLZ2y6DxTWD4cDe07RglV88ZiNEdlRfGtqahfbIjfsw1nMCPx49Uev4IA/hWn3sDKyAnSPwoYSsAEdcimw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.27.1",
+        "@jest/types": "30.2.0",
+        "@types/stack-utils": "^2.0.3",
+        "chalk": "^4.1.2",
+        "graceful-fs": "^4.2.11",
+        "micromatch": "^4.0.8",
+        "pretty-format": "30.2.0",
+        "slash": "^3.0.0",
+        "stack-utils": "^2.0.6"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/jest-mock": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-mock/-/jest-mock-30.2.0.tgz",
+      "integrity": "sha512-JNNNl2rj4b5ICpmAcq+WbLH83XswjPbjH4T7yvGzfAGCPh1rw+xVNbtk+FnRslvt9lkCcdn9i1oAoKUuFsOxRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/types": "30.2.0",
+        "@types/node": "*",
+        "jest-util": "30.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/jest-util": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/jest-util/-/jest-util-30.2.0.tgz",
+      "integrity": "sha512-QKNsM0o3Xe6ISQU869e+DhG+4CK/48aHYdJZGlFQVTjnbvgpcKyxpzk29fGiO7i/J8VENZ+d2iGnSsvmuHywlA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/types": "30.2.0",
+        "@types/node": "*",
+        "chalk": "^4.1.2",
+        "ci-info": "^4.2.0",
+        "graceful-fs": "^4.2.11",
+        "picomatch": "^4.0.2"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/jest-environment-jsdom/node_modules/pretty-format": {
+      "version": "30.2.0",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-30.2.0.tgz",
+      "integrity": "sha512-9uBdv/B4EefsuAL+pWqueZyZS2Ba+LxfFeQ9DN14HU4bN8bhaxKdkpjpB6fs9+pSjIBu+FXQHImEg8j/Lw0+vA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/schemas": "30.0.5",
+        "ansi-styles": "^5.2.0",
+        "react-is": "^18.3.1"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
     "node_modules/jest-environment-node": {
       "version": "29.7.0",
       "dev": true,
@@ -11107,42 +11544,38 @@
       }
     },
     "node_modules/jsdom": {
-      "version": "20.0.3",
+      "version": "26.1.0",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-26.1.0.tgz",
+      "integrity": "sha512-Cvc9WUhxSMEo4McES3P7oK3QaXldCfNWp7pl2NNeiIFlCoLr3kfq9kb1fxftiwk1FLV7CvpvDfonxtzUDeSOPg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "abab": "^2.0.6",
-        "acorn": "^8.8.1",
-        "acorn-globals": "^7.0.0",
-        "cssom": "^0.5.0",
-        "cssstyle": "^2.3.0",
-        "data-urls": "^3.0.2",
-        "decimal.js": "^10.4.2",
-        "domexception": "^4.0.0",
-        "escodegen": "^2.0.0",
-        "form-data": "^4.0.0",
-        "html-encoding-sniffer": "^3.0.0",
-        "http-proxy-agent": "^5.0.0",
-        "https-proxy-agent": "^5.0.1",
+        "cssstyle": "^4.2.1",
+        "data-urls": "^5.0.0",
+        "decimal.js": "^10.5.0",
+        "html-encoding-sniffer": "^4.0.0",
+        "http-proxy-agent": "^7.0.2",
+        "https-proxy-agent": "^7.0.6",
         "is-potential-custom-element-name": "^1.0.1",
-        "nwsapi": "^2.2.2",
-        "parse5": "^7.1.1",
+        "nwsapi": "^2.2.16",
+        "parse5": "^7.2.1",
+        "rrweb-cssom": "^0.8.0",
         "saxes": "^6.0.0",
         "symbol-tree": "^3.2.4",
-        "tough-cookie": "^4.1.2",
-        "w3c-xmlserializer": "^4.0.0",
+        "tough-cookie": "^5.1.1",
+        "w3c-xmlserializer": "^5.0.0",
         "webidl-conversions": "^7.0.0",
-        "whatwg-encoding": "^2.0.0",
-        "whatwg-mimetype": "^3.0.0",
-        "whatwg-url": "^11.0.0",
-        "ws": "^8.11.0",
-        "xml-name-validator": "^4.0.0"
+        "whatwg-encoding": "^3.1.1",
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^14.1.1",
+        "ws": "^8.18.0",
+        "xml-name-validator": "^5.0.0"
       },
       "engines": {
-        "node": ">=14"
+        "node": ">=18"
       },
       "peerDependencies": {
-        "canvas": "^2.5.0"
+        "canvas": "^3.0.0"
       },
       "peerDependenciesMeta": {
         "canvas": {
@@ -11150,6 +11583,30 @@
         }
       }
     },
+    "node_modules/jsdom/node_modules/agent-base": {
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/jsdom/node_modules/https-proxy-agent": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^7.1.2",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "node_modules/jsesc": {
       "version": "3.1.0",
       "license": "MIT",
@@ -12292,6 +12749,7 @@
     "node_modules/mime-db": {
       "version": "1.52.0",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 0.6"
       }
@@ -12299,6 +12757,7 @@
     "node_modules/mime-types": {
       "version": "2.1.35",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "mime-db": "1.52.0"
       },
@@ -13005,7 +13464,9 @@
       }
     },
     "node_modules/nwsapi": {
-      "version": "2.2.22",
+      "version": "2.2.23",
+      "resolved": "https://registry.npmjs.org/nwsapi/-/nwsapi-2.2.23.tgz",
+      "integrity": "sha512-7wfH4sLbt4M0gCDzGE6vzQBo0bfTKjU7Sfpqy/7gs1qBfYz2vEJH6vXcBKpO3+6Yu1telwd0t9HpyOoLEQQbIQ==",
       "dev": true,
       "license": "MIT"
     },
@@ -13823,17 +14284,6 @@
       "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
       "license": "MIT"
     },
-    "node_modules/psl": {
-      "version": "1.15.0",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "punycode": "^2.3.1"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/lupomontero"
-      }
-    },
     "node_modules/punycode": {
       "version": "2.3.1",
       "dev": true,
@@ -13872,11 +14322,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/querystringify": {
-      "version": "2.2.0",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/queue": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz",
@@ -14451,11 +14896,6 @@
         "node": ">=9.3.0 || >=8.10.0 <9.0.0"
       }
     },
-    "node_modules/requires-port": {
-      "version": "1.0.0",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/resolve-cwd": {
       "version": "3.0.0",
       "dev": true,
@@ -14561,6 +15001,13 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/rrweb-cssom": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.8.0.tgz",
+      "integrity": "sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/run-parallel": {
       "version": "1.2.0",
       "funding": [
@@ -14633,11 +15080,15 @@
     },
     "node_modules/safer-buffer": {
       "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "dev": true,
       "license": "MIT"
     },
     "node_modules/saxes": {
       "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -15370,6 +15821,8 @@
     },
     "node_modules/symbol-tree": {
       "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
       "dev": true,
       "license": "MIT"
     },
@@ -15640,6 +16093,26 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tldts": {
+      "version": "6.1.86",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-6.1.86.tgz",
+      "integrity": "sha512-WMi/OQ2axVTf/ykqCQgXiIct+mSQDFdH2fkwhPwgEwvJ1kSzZRiinb0zF2Xb8u4+OqPChmyI6MEu4EezNJz+FQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^6.1.86"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "6.1.86",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-6.1.86.tgz",
+      "integrity": "sha512-Je6p7pkk+KMzMv2XXKmAE3McmolOQFdxkKw0R8EYNr7sELW46JqnNeTX8ybPiQgvg1ymCoF8LXs5fzFaZvJPTA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tmpl": {
       "version": "1.0.5",
       "dev": true,
@@ -15660,28 +16133,29 @@
       "license": "MIT"
     },
     "node_modules/tough-cookie": {
-      "version": "4.1.4",
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-5.1.2.tgz",
+      "integrity": "sha512-FVDYdxtnj0G6Qm/DhNPSb8Ju59ULcup3tuJxkFb5K8Bv2pUXILbf0xZWU8PX8Ov19OXljbUyveOFwRMwkXzO+A==",
       "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
-        "psl": "^1.1.33",
-        "punycode": "^2.1.1",
-        "universalify": "^0.2.0",
-        "url-parse": "^1.5.3"
+        "tldts": "^6.1.32"
       },
       "engines": {
-        "node": ">=6"
+        "node": ">=16"
       }
     },
     "node_modules/tr46": {
-      "version": "3.0.0",
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-5.1.1.tgz",
+      "integrity": "sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "punycode": "^2.1.1"
+        "punycode": "^2.3.1"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/trim-lines": {
@@ -16083,14 +16557,6 @@
         "url": "https://opencollective.com/unified"
       }
     },
-    "node_modules/universalify": {
-      "version": "0.2.0",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 4.0.0"
-      }
-    },
     "node_modules/unplugin": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/unplugin/-/unplugin-1.0.1.tgz",
@@ -16180,15 +16646,6 @@
         "punycode": "^2.1.0"
       }
     },
-    "node_modules/url-parse": {
-      "version": "1.5.10",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "querystringify": "^2.1.1",
-        "requires-port": "^1.0.0"
-      }
-    },
     "node_modules/use-callback-ref": {
       "version": "1.3.3",
       "license": "MIT",
@@ -16343,14 +16800,16 @@
       }
     },
     "node_modules/w3c-xmlserializer": {
-      "version": "4.0.0",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "xml-name-validator": "^4.0.0"
+        "xml-name-validator": "^5.0.0"
       },
       "engines": {
-        "node": ">=14"
+        "node": ">=18"
       }
     },
     "node_modules/walker": {
@@ -16389,6 +16848,8 @@
     },
     "node_modules/webidl-conversions": {
       "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-7.0.0.tgz",
+      "integrity": "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==",
       "dev": true,
       "license": "BSD-2-Clause",
       "engines": {
@@ -16479,14 +16940,17 @@
       }
     },
     "node_modules/whatwg-encoding": {
-      "version": "2.0.0",
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz",
+      "integrity": "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==",
+      "deprecated": "Use @exodus/bytes instead for a more spec-conformant and faster implementation",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "iconv-lite": "0.6.3"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/whatwg-fetch": {
@@ -16495,23 +16959,27 @@
       "license": "MIT"
     },
     "node_modules/whatwg-mimetype": {
-      "version": "3.0.0",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz",
+      "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==",
       "dev": true,
       "license": "MIT",
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/whatwg-url": {
-      "version": "11.0.0",
+      "version": "14.2.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-14.2.0.tgz",
+      "integrity": "sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "tr46": "^3.0.0",
+        "tr46": "^5.1.0",
         "webidl-conversions": "^7.0.0"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/which": {
@@ -16698,7 +17166,9 @@
       }
     },
     "node_modules/ws": {
-      "version": "8.18.3",
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
+      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -16718,15 +17188,19 @@
       }
     },
     "node_modules/xml-name-validator": {
-      "version": "4.0.0",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
       "dev": true,
       "license": "Apache-2.0",
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/xmlchars": {
       "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
       "dev": true,
       "license": "MIT"
     },
diff --git a/web/package.json b/web/package.json
index 12a26f67f50..b564937a234 100644
--- a/web/package.json
+++ b/web/package.json
@@ -132,7 +132,7 @@
     "eslint-plugin-unused-imports": "^4.1.4",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
+    "jest-environment-jsdom": "^30.2.0",
     "prettier": "3.1.0",
     "stats.js": "^0.17.0",
     "tailwindcss": "^3.4.17",
diff --git a/web/src/app/auth/login/EmailPasswordForm.test.tsx b/web/src/app/auth/login/EmailPasswordForm.test.tsx
index 2611d78ef50..c49c207aee2 100644
--- a/web/src/app/auth/login/EmailPasswordForm.test.tsx
+++ b/web/src/app/auth/login/EmailPasswordForm.test.tsx
@@ -22,9 +22,6 @@ describe("Email/Password Login Workflow", () => {
   beforeEach(() => {
     jest.clearAllMocks();
     fetchSpy = jest.spyOn(global, "fetch");
-    // Mock window.location.href for redirect testing
-    delete (window as any).location;
-    window.location = { href: "" } as any;
   });
 
   afterEach(() => {
@@ -53,9 +50,9 @@ describe("Email/Password Login Workflow", () => {
     const loginButton = screen.getByRole("button", { name: /sign in/i });
     await user.click(loginButton);
 
-    // After successful login, user should be redirected to /chat
+    // Verify success message is shown after login
     await waitFor(() => {
-      expect(window.location.href).toBe("/app");
+      expect(screen.getByText(/signed in successfully\./i)).toBeInTheDocument();
     });
 
     // Verify API was called with correct credentials
@@ -114,9 +111,6 @@ describe("Email/Password Signup Workflow", () => {
   beforeEach(() => {
     jest.clearAllMocks();
     fetchSpy = jest.spyOn(global, "fetch");
-    // Mock window.location.href
-    delete (window as any).location;
-    window.location = { href: "" } as any;
   });
 
   afterEach(() => {

From 910718deaa9c6b929086845e53dc94f8eab9925b Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 11:40:43 -0800
Subject: [PATCH 153/267] chore(playwright): hide flaky
 AppInputBar/llm-popover-trigger (#9144)

---
 web/tests/e2e/agents/create_and_edit_agent.spec.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/web/tests/e2e/agents/create_and_edit_agent.spec.ts b/web/tests/e2e/agents/create_and_edit_agent.spec.ts
index 068b5e9e6b1..575d1cbcfee 100644
--- a/web/tests/e2e/agents/create_and_edit_agent.spec.ts
+++ b/web/tests/e2e/agents/create_and_edit_agent.spec.ts
@@ -292,7 +292,10 @@ test.describe("Assistant Creation and Edit Verification", () => {
       expect(agentIdMatch).toBeTruthy();
       const agentId = agentIdMatch ? agentIdMatch[1] : null;
       expect(agentId).not.toBeNull();
-      await expectScreenshot(page, { name: "welcome-page-with-assistant" });
+      await expectScreenshot(page, {
+        name: "welcome-page-with-assistant",
+        hide: ["[data-testid='AppInputBar/llm-popover-trigger']"],
+      });
 
       // Store assistant ID for cleanup
       knowledgeAssistantId = Number(agentId);

From f4dcd130badad20727e1b7104e9f924c236830c4 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Fri, 6 Mar 2026 11:42:46 -0800
Subject: [PATCH 154/267] feat(cli): add PyPI wheel packaging for onyx-cli
 (#8992)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
---
 .github/workflows/release-cli.yml | 40 ++++++++++++++++++++++++++++
 cli/README.md                     | 44 +++++++++++++++++++++++++++++--
 cli/hatch_build.py                | 43 ++++++++++++++++++++++++++++++
 cli/internal/_version.py          | 11 ++++++++
 cli/pyproject.toml                | 39 +++++++++++++++++++++++++++
 5 files changed, 175 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/release-cli.yml
 create mode 100644 cli/hatch_build.py
 create mode 100644 cli/internal/_version.py
 create mode 100644 cli/pyproject.toml

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
new file mode 100644
index 00000000000..c33a18bee4e
--- /dev/null
+++ b/.github/workflows/release-cli.yml
@@ -0,0 +1,40 @@
+name: Release CLI
+
+on:
+  push:
+    tags:
+      - "cli/v*.*.*"
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: release-cli
+    permissions:
+      id-token: write
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        os-arch:
+          - { goos: "linux", goarch: "amd64" }
+          - { goos: "linux", goarch: "arm64" }
+          - { goos: "windows", goarch: "amd64" }
+          - { goos: "windows", goarch: "arm64" }
+          - { goos: "darwin", goarch: "amd64" }
+          - { goos: "darwin", goarch: "arm64" }
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+        with:
+          enable-cache: false
+          version: "0.9.9"
+      - run: |
+          GOOS="${{ matrix.os-arch.goos }}" \
+          GOARCH="${{ matrix.os-arch.goarch }}" \
+          uv build --wheel
+        working-directory: cli
+      - run: uv publish
+        working-directory: cli
diff --git a/cli/README.md b/cli/README.md
index f86ad7476f9..aa5faeb13bd 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -68,17 +68,17 @@ onyx-cli agents --json
 | `ask` | Ask a one-shot question (non-interactive) |
 | `agents` | List available agents |
 | `configure` | Configure server URL and API key |
+| `validate-config` | Validate configuration and test connection |
 
 ## Slash Commands (in TUI)
 
 | Command | Description |
 |---------|-------------|
 | `/help` | Show help message |
-| `/new` | Start a new chat session |
+| `/clear` | Clear chat and start a new session |
 | `/agent` | List and switch agents |
 | `/attach <path>` | Attach a file to next message |
 | `/sessions` | List recent chat sessions |
-| `/clear` | Clear the chat display |
 | `/configure` | Re-run connection setup |
 | `/connectors` | Open connectors in browser |
 | `/settings` | Open settings in browser |
@@ -116,3 +116,43 @@ go build -o onyx-cli .
 # Lint
 staticcheck ./...
 ```
+
+## Publishing to PyPI
+
+The CLI is distributed as a Python package via [PyPI](https://pypi.org/project/onyx-cli/). The build system uses [hatchling](https://hatch.pypa.io/) with [manygo](https://github.com/nicholasgasior/manygo) to cross-compile Go binaries into platform-specific wheels.
+
+### CI release (recommended)
+
+Tag a release and push — the `release-cli.yml` workflow builds wheels for all platforms and publishes to PyPI automatically:
+
+```shell
+tag --prefix cli
+```
+
+To do this manually:
+
+```shell
+git tag cli/v0.1.0
+git push origin cli/v0.1.0
+```
+
+The workflow builds wheels for: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64.
+
+### Manual release
+
+Build a wheel locally with `uv`. Set `GOOS` and `GOARCH` to cross-compile for other platforms (Go handles this natively — no cross-compiler needed):
+
+```shell
+# Build for current platform
+uv build --wheel
+
+# Cross-compile for a different platform
+GOOS=linux GOARCH=amd64 uv build --wheel
+
+# Upload to PyPI
+uv publish
+```
+
+### Versioning
+
+Versions are derived from git tags with the `cli/` prefix (e.g. `cli/v0.1.0`). The tag is parsed by `internal/_version.py` and injected into the Go binary via `-ldflags` at build time.
diff --git a/cli/hatch_build.py b/cli/hatch_build.py
new file mode 100644
index 00000000000..7fdccf55892
--- /dev/null
+++ b/cli/hatch_build.py
@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import Any
+
+import manygo
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    """Build hook to compile the Go binary and include it in the wheel."""
+
+    def initialize(self, version: Any, build_data: Any) -> None:  # noqa: ARG002
+        """Build the Go binary before packaging."""
+        build_data["pure_python"] = False
+
+        # Set platform tag for cross-compilation
+        goos = os.getenv("GOOS")
+        goarch = os.getenv("GOARCH")
+        if manygo.is_goos(goos) and manygo.is_goarch(goarch):
+            build_data["tag"] = "py3-none-" + manygo.get_platform_tag(
+                goos=goos,
+                goarch=goarch,
+            )
+
+        # Get config and environment
+        binary_name = self.config["binary_name"]
+        tag_prefix = self.config.get("tag_prefix", binary_name)
+        tag = os.getenv("GITHUB_REF_NAME", "dev").removeprefix(f"{tag_prefix}/")
+        commit = os.getenv("GITHUB_SHA", "none")
+
+        # Build the Go binary if it doesn't exist
+        # Build the Go binary (always rebuild to ensure correct version injection)
+        if not os.path.exists(binary_name):
+            print(f"Building Go binary '{binary_name}'...")
+            pkg = "github.com/onyx-dot-app/onyx/cli/cmd"
+            ldflags = f"-X {pkg}.version={tag}" f" -X {pkg}.commit={commit}" " -s -w"
+            subprocess.check_call(  # noqa: S603
+                ["go", "build", f"-ldflags={ldflags}", "-o", binary_name],
+            )
+
+        build_data["shared_scripts"] = {binary_name: binary_name}
diff --git a/cli/internal/_version.py b/cli/internal/_version.py
new file mode 100644
index 00000000000..8819d43b7f6
--- /dev/null
+++ b/cli/internal/_version.py
@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import os
+import re
+
+# Must match tag_prefix in pyproject.toml [tool.hatch.build.targets.wheel.hooks.custom]
+TAG_PREFIX = "cli"
+
+_tag = os.environ.get("GITHUB_REF_NAME", "v0.0.0-dev").removeprefix(f"{TAG_PREFIX}/")
+_match = re.search(r"v?(\d+\.\d+\.\d+)", _tag)
+__version__ = _match.group(1) if _match else "0.0.0"
diff --git a/cli/pyproject.toml b/cli/pyproject.toml
new file mode 100644
index 00000000000..3640d8779d0
--- /dev/null
+++ b/cli/pyproject.toml
@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling", "go-bin~=1.24.11", "manygo"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onyx-cli"
+readme = "README.md"
+description = "Terminal interface for chatting with your Onyx agent"
+authors = [{ name = "Onyx AI", email = "founders@onyx.app" }]
+requires-python = ">=3.9"
+keywords = [
+  "onyx", "cli", "chat", "ai", "enterprise-search",
+]
+classifiers = [
+    "Programming Language :: Go",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+dynamic = ["version"]
+
+[project.urls]
+Repository = "https://github.com/onyx-dot-app/onyx"
+
+[tool.hatch.build]
+include = ["go.mod", "go.sum", "main.go", "**/*.go", "**/*.py", "README.md"]
+
+[tool.hatch.version]
+source = "code"
+path = "internal/_version.py"
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+binary_name = "onyx-cli"
+tag_prefix = "cli"
+
+[tool.uv]
+managed = false

From e618bf8385aad0005c0ab511226f7560cb5652e2 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Fri, 6 Mar 2026 11:53:53 -0800
Subject: [PATCH 155/267] fix(ui): LLM Model selection Cache 1/2 (#9141)

---
 web/src/lib/llmConfig/cache.ts                | 21 +++++++++++++++++++
 web/src/lib/llmConfig/constants.ts            |  1 +
 .../admin/LLMConfigurationPage.tsx            |  6 +++---
 .../modals/llmConfig/BedrockModal.tsx         |  3 ++-
 .../modals/llmConfig/CustomModal.test.tsx     | 12 +++++++++++
 .../modals/llmConfig/LMStudioForm.tsx         |  3 ++-
 .../sections/modals/llmConfig/OllamaModal.tsx |  3 ++-
 .../components/FormActionButtons.tsx          |  7 ++++---
 .../llmConfig/components/FormWrapper.tsx      |  8 +++----
 .../sections/modals/llmConfig/formUtils.ts    |  6 ++++--
 10 files changed, 55 insertions(+), 15 deletions(-)
 create mode 100644 web/src/lib/llmConfig/cache.ts

diff --git a/web/src/lib/llmConfig/cache.ts b/web/src/lib/llmConfig/cache.ts
new file mode 100644
index 00000000000..465af204fa9
--- /dev/null
+++ b/web/src/lib/llmConfig/cache.ts
@@ -0,0 +1,21 @@
+import { ScopedMutator } from "swr";
+import {
+  LLM_CHAT_PROVIDERS_URL,
+  LLM_PROVIDERS_ADMIN_URL,
+} from "@/lib/llmConfig/constants";
+
+const PERSONA_PROVIDER_ENDPOINT_PATTERN =
+  /^\/api\/llm\/persona\/\d+\/providers$/;
+
+export async function refreshLlmProviderCaches(
+  mutate: ScopedMutator
+): Promise<void> {
+  await Promise.all([
+    mutate(LLM_PROVIDERS_ADMIN_URL),
+    mutate(LLM_CHAT_PROVIDERS_URL),
+    mutate(
+      (key) =>
+        typeof key === "string" && PERSONA_PROVIDER_ENDPOINT_PATTERN.test(key)
+    ),
+  ]);
+}
diff --git a/web/src/lib/llmConfig/constants.ts b/web/src/lib/llmConfig/constants.ts
index bcc2e710910..150b42f52fe 100644
--- a/web/src/lib/llmConfig/constants.ts
+++ b/web/src/lib/llmConfig/constants.ts
@@ -1,5 +1,6 @@
 export const LLM_ADMIN_URL = "/api/admin/llm";
 export const LLM_PROVIDERS_ADMIN_URL = `${LLM_ADMIN_URL}/provider`;
+export const LLM_CHAT_PROVIDERS_URL = "/api/llm/provider";
 
 export const LLM_CONTEXTUAL_COST_ADMIN_URL =
   "/api/admin/llm/provider-contextual-cost";
diff --git a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
index 1b557ea0917..3be9e80f779 100644
--- a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
+++ b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
@@ -20,6 +20,7 @@ import {
   getProviderIcon,
   getProviderProductName,
 } from "@/lib/llmConfig/providers";
+import { refreshLlmProviderCaches } from "@/lib/llmConfig/cache";
 import { deleteLlmProvider, setDefaultLlmModel } from "@/lib/llmConfig/svc";
 import Text from "@/refresh-components/texts/Text";
 import { Horizontal as HorizontalInput } from "@/layouts/input-layouts";
@@ -33,7 +34,6 @@ import {
   LLMProviderView,
   WellKnownLLMProviderDescriptor,
 } from "@/interfaces/llm";
-import { LLM_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
 import { getModalForExistingProvider } from "@/sections/modals/llmConfig/getModal";
 import { OpenAIModal } from "@/sections/modals/llmConfig/OpenAIModal";
 import { AnthropicModal } from "@/sections/modals/llmConfig/AnthropicModal";
@@ -140,7 +140,7 @@ function ExistingProviderCard({
   const handleDelete = async () => {
     try {
       await deleteLlmProvider(provider.id);
-      mutate(LLM_PROVIDERS_ADMIN_URL);
+      await refreshLlmProviderCaches(mutate);
       deleteModal.toggle(false);
       toast.success("Provider deleted successfully!");
     } catch (e) {
@@ -345,7 +345,7 @@ export default function LLMConfigurationPage() {
 
     try {
       await setDefaultLlmModel(providerId, modelName);
-      mutate(LLM_PROVIDERS_ADMIN_URL);
+      await refreshLlmProviderCaches(mutate);
       toast.success("Default model updated successfully!");
     } catch (e) {
       const message = e instanceof Error ? e.message : "Unknown error";
diff --git a/web/src/sections/modals/llmConfig/BedrockModal.tsx b/web/src/sections/modals/llmConfig/BedrockModal.tsx
index 3f82670bc5e..253045f2b87 100644
--- a/web/src/sections/modals/llmConfig/BedrockModal.tsx
+++ b/web/src/sections/modals/llmConfig/BedrockModal.tsx
@@ -32,6 +32,7 @@ import Separator from "@/refresh-components/Separator";
 import Text from "@/refresh-components/texts/Text";
 import Tabs from "@/refresh-components/Tabs";
 import { cn } from "@/lib/utils";
+import { ScopedMutator } from "swr";
 
 export const BEDROCK_PROVIDER_NAME = "bedrock";
 const BEDROCK_DISPLAY_NAME = "AWS Bedrock";
@@ -83,7 +84,7 @@ interface BedrockModalInternalsProps {
   modelConfigurations: ModelConfiguration[];
   isTesting: boolean;
   testError: string;
-  mutate: (key: string) => void;
+  mutate: ScopedMutator;
   onClose: () => void;
 }
 
diff --git a/web/src/sections/modals/llmConfig/CustomModal.test.tsx b/web/src/sections/modals/llmConfig/CustomModal.test.tsx
index d32f7112c72..38c0f94bde7 100644
--- a/web/src/sections/modals/llmConfig/CustomModal.test.tsx
+++ b/web/src/sections/modals/llmConfig/CustomModal.test.tsx
@@ -164,6 +164,18 @@ describe("Custom LLM Provider Configuration Workflow", () => {
 
     // Verify SWR cache was invalidated
     expect(mockMutate).toHaveBeenCalledWith("/api/admin/llm/provider");
+    expect(mockMutate).toHaveBeenCalledWith("/api/llm/provider");
+
+    const personaProvidersMutateCall = mockMutate.mock.calls.find(
+      ([key]) => typeof key === "function"
+    );
+    expect(personaProvidersMutateCall).toBeDefined();
+
+    const personaProviderFilter = personaProvidersMutateCall?.[0] as (
+      key: unknown
+    ) => boolean;
+    expect(personaProviderFilter("/api/llm/persona/42/providers")).toBe(true);
+    expect(personaProviderFilter("/api/llm/provider")).toBe(false);
   });
 
   test("shows error when test configuration fails", async () => {
diff --git a/web/src/sections/modals/llmConfig/LMStudioForm.tsx b/web/src/sections/modals/llmConfig/LMStudioForm.tsx
index d96784ee468..7f4205cced3 100644
--- a/web/src/sections/modals/llmConfig/LMStudioForm.tsx
+++ b/web/src/sections/modals/llmConfig/LMStudioForm.tsx
@@ -27,6 +27,7 @@ import { DisplayModels } from "./components/DisplayModels";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { fetchModels } from "@/app/admin/configuration/llm/utils";
 import debounce from "lodash/debounce";
+import { ScopedMutator } from "swr";
 
 const DEFAULT_API_BASE = "http://localhost:1234";
 
@@ -46,7 +47,7 @@ interface LMStudioFormContentProps {
   setHasFetched: (value: boolean) => void;
   isTesting: boolean;
   testError: string;
-  mutate: () => void;
+  mutate: ScopedMutator;
   onClose: () => void;
   isFormValid: boolean;
 }
diff --git a/web/src/sections/modals/llmConfig/OllamaModal.tsx b/web/src/sections/modals/llmConfig/OllamaModal.tsx
index 69d3c69c3e6..8f178bae826 100644
--- a/web/src/sections/modals/llmConfig/OllamaModal.tsx
+++ b/web/src/sections/modals/llmConfig/OllamaModal.tsx
@@ -26,6 +26,7 @@ import { DisplayModels } from "./components/DisplayModels";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { fetchOllamaModels } from "@/app/admin/configuration/llm/utils";
 import debounce from "lodash/debounce";
+import { ScopedMutator } from "swr";
 
 export const OLLAMA_PROVIDER_NAME = "ollama_chat";
 const DEFAULT_API_BASE = "http://127.0.0.1:11434";
@@ -44,7 +45,7 @@ interface OllamaModalContentProps {
   setFetchedModels: (models: ModelConfiguration[]) => void;
   isTesting: boolean;
   testError: string;
-  mutate: () => void;
+  mutate: ScopedMutator;
   onClose: () => void;
   isFormValid: boolean;
 }
diff --git a/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx b/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
index 7c36f12ae92..8da3f9fce5f 100644
--- a/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
+++ b/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
@@ -4,14 +4,15 @@ import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
 import { SvgTrash } from "@opal/icons";
 import { LLMProviderView } from "@/interfaces/llm";
-import { LLM_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
+import { refreshLlmProviderCaches } from "@/lib/llmConfig/cache";
 import { deleteLlmProvider } from "@/lib/llmConfig/svc";
+import { ScopedMutator } from "swr";
 
 interface FormActionButtonsProps {
   isTesting: boolean;
   testError: string;
   existingLlmProvider?: LLMProviderView;
-  mutate: (key: string) => void;
+  mutate: ScopedMutator;
   onClose: () => void;
   isFormValid: boolean;
 }
@@ -29,7 +30,7 @@ export function FormActionButtons({
 
     try {
       await deleteLlmProvider(existingLlmProvider.id);
-      mutate(LLM_PROVIDERS_ADMIN_URL);
+      await refreshLlmProviderCaches(mutate);
       onClose();
     } catch (e) {
       const message = e instanceof Error ? e.message : "Unknown error";
diff --git a/web/src/sections/modals/llmConfig/components/FormWrapper.tsx b/web/src/sections/modals/llmConfig/components/FormWrapper.tsx
index f7e6deb2122..593bd96cfa9 100644
--- a/web/src/sections/modals/llmConfig/components/FormWrapper.tsx
+++ b/web/src/sections/modals/llmConfig/components/FormWrapper.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState, ReactNode } from "react";
-import useSWR, { useSWRConfig, KeyedMutator } from "swr";
+import useSWR, { useSWRConfig, ScopedMutator } from "swr";
 import { toast } from "@/hooks/useToast";
 import {
   LLMProviderView,
@@ -14,12 +14,12 @@ import { Button } from "@opal/components";
 import { SvgSettings } from "@opal/icons";
 import { Badge } from "@/components/ui/badge";
 import { cn } from "@/lib/utils";
-import { LLM_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
+import { refreshLlmProviderCaches } from "@/lib/llmConfig/cache";
 import { setDefaultLlmModel } from "@/lib/llmConfig/svc";
 
 export interface ProviderFormContext {
   onClose: () => void;
-  mutate: KeyedMutator<any>;
+  mutate: ScopedMutator;
   isTesting: boolean;
   setIsTesting: (testing: boolean) => void;
   testError: string;
@@ -95,7 +95,7 @@ export function ProviderFormEntrypointWrapper({
 
     try {
       await setDefaultLlmModel(existingLlmProvider.id, firstVisibleModel.name);
-      await mutate(LLM_PROVIDERS_ADMIN_URL);
+      await refreshLlmProviderCaches(mutate);
       toast.success("Provider set as default successfully!");
     } catch (e) {
       const message = e instanceof Error ? e.message : "Unknown error";
diff --git a/web/src/sections/modals/llmConfig/formUtils.ts b/web/src/sections/modals/llmConfig/formUtils.ts
index 730d074cace..748bb36abbd 100644
--- a/web/src/sections/modals/llmConfig/formUtils.ts
+++ b/web/src/sections/modals/llmConfig/formUtils.ts
@@ -7,9 +7,11 @@ import {
   LLM_ADMIN_URL,
   LLM_PROVIDERS_ADMIN_URL,
 } from "@/lib/llmConfig/constants";
+import { refreshLlmProviderCaches } from "@/lib/llmConfig/cache";
 import { toast } from "@/hooks/useToast";
 import * as Yup from "yup";
 import isEqual from "lodash/isEqual";
+import { ScopedMutator } from "swr";
 
 // Common class names for the Form component across all LLM provider forms
 export const LLM_FORM_CLASS_NAME = "flex flex-col gap-y-4 items-stretch mt-6";
@@ -105,7 +107,7 @@ export interface SubmitLLMProviderParams<
   hideSuccess?: boolean;
   setIsTesting: (testing: boolean) => void;
   setTestError: (error: string) => void;
-  mutate: (key: string) => void;
+  mutate: ScopedMutator;
   onClose: () => void;
   setSubmitting: (submitting: boolean) => void;
 }
@@ -287,7 +289,7 @@ export const submitLLMProvider = async <T extends BaseLLMFormValues>({
     }
   }
 
-  mutate(LLM_PROVIDERS_ADMIN_URL);
+  await refreshLlmProviderCaches(mutate);
   onClose();
 
   if (!hideSuccess) {

From 99e95f820581f41f24c7b30566fdeab6fe125af3 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Fri, 6 Mar 2026 12:02:38 -0800
Subject: [PATCH 156/267] chore: rm dead llm provider code and bump claude recs
 (#9145)

---
 .../onyx/llm/model_metadata_enrichments.json  |  8 ++
 .../llm/well_known_providers/constants.py     | 43 -----------
 .../recommended-models.json                   |  4 +
 .../craft/components/ToggleWarningModal.tsx   |  2 +-
 .../components/OnboardingLlmSetup.tsx         |  4 +-
 web/src/app/craft/onboarding/constants.ts     | 14 ++--
 .../AnthropicOnboardingForm.test.tsx          | 68 -----------------
 .../__tests__/OpenAIOnboardingForm.test.tsx   | 74 -------------------
 .../__tests__/VertexAIOnboardingForm.test.tsx | 68 -----------------
 .../forms/__tests__/testHelpers.tsx           | 16 ----
 10 files changed, 22 insertions(+), 279 deletions(-)

diff --git a/backend/onyx/llm/model_metadata_enrichments.json b/backend/onyx/llm/model_metadata_enrichments.json
index 654ee3ed9ab..bf017061e20 100644
--- a/backend/onyx/llm/model_metadata_enrichments.json
+++ b/backend/onyx/llm/model_metadata_enrichments.json
@@ -1512,6 +1512,10 @@
     "display_name": "Claude Opus 4.5",
     "model_vendor": "anthropic"
   },
+  "claude-opus-4-6": {
+    "display_name": "Claude Opus 4.6",
+    "model_vendor": "anthropic"
+  },
   "claude-opus-4-5-20251101": {
     "display_name": "Claude Opus 4.5",
     "model_vendor": "anthropic",
@@ -1526,6 +1530,10 @@
     "display_name": "Claude Sonnet 4.5",
     "model_vendor": "anthropic"
   },
+  "claude-sonnet-4-6": {
+    "display_name": "Claude Sonnet 4.6",
+    "model_vendor": "anthropic"
+  },
   "claude-sonnet-4-5-20250929": {
     "display_name": "Claude Sonnet 4.5",
     "model_vendor": "anthropic",
diff --git a/backend/onyx/llm/well_known_providers/constants.py b/backend/onyx/llm/well_known_providers/constants.py
index ae023c72dbd..1a5a2f47b89 100644
--- a/backend/onyx/llm/well_known_providers/constants.py
+++ b/backend/onyx/llm/well_known_providers/constants.py
@@ -1,37 +1,8 @@
 from onyx.llm.constants import LlmProviderNames
 
 OPENAI_PROVIDER_NAME = "openai"
-# Curated list of OpenAI models to show by default in the UI
-OPENAI_VISIBLE_MODEL_NAMES = {
-    "gpt-5",
-    "gpt-5-mini",
-    "o1",
-    "o3-mini",
-    "gpt-4o",
-    "gpt-4o-mini",
-}
 
 BEDROCK_PROVIDER_NAME = "bedrock"
-BEDROCK_DEFAULT_MODEL = "anthropic.claude-3-5-sonnet-20241022-v2:0"
-
-
-def _fallback_bedrock_regions() -> list[str]:
-    # Fall back to a conservative set of well-known Bedrock regions if boto3 data isn't available.
-    return [
-        "us-east-1",
-        "us-east-2",
-        "us-gov-east-1",
-        "us-gov-west-1",
-        "us-west-2",
-        "ap-northeast-1",
-        "ap-south-1",
-        "ap-southeast-1",
-        "ap-southeast-2",
-        "ap-east-1",
-        "ca-central-1",
-        "eu-central-1",
-        "eu-west-2",
-    ]
 
 
 OLLAMA_PROVIDER_NAME = "ollama_chat"
@@ -51,13 +22,6 @@ def _fallback_bedrock_regions() -> list[str]:
 
 ANTHROPIC_PROVIDER_NAME = "anthropic"
 
-# Curated list of Anthropic models to show by default in the UI
-ANTHROPIC_VISIBLE_MODEL_NAMES = {
-    "claude-opus-4-5",
-    "claude-sonnet-4-5",
-    "claude-haiku-4-5",
-}
-
 AZURE_PROVIDER_NAME = "azure"
 
 
@@ -65,13 +29,6 @@ def _fallback_bedrock_regions() -> list[str]:
 VERTEX_CREDENTIALS_FILE_KWARG = "vertex_credentials"
 VERTEX_CREDENTIALS_FILE_KWARG_ENV_VAR_FORMAT = "CREDENTIALS_FILE"
 VERTEX_LOCATION_KWARG = "vertex_location"
-VERTEXAI_DEFAULT_MODEL = "gemini-2.5-flash"
-# Curated list of Vertex AI models to show by default in the UI
-VERTEXAI_VISIBLE_MODEL_NAMES = {
-    "gemini-2.5-flash",
-    "gemini-2.5-flash-lite",
-    "gemini-2.5-pro",
-}
 
 AWS_REGION_NAME_KWARG = "aws_region_name"
 AWS_REGION_NAME_KWARG_ENV_VAR_FORMAT = "AWS_REGION_NAME"
diff --git a/backend/onyx/llm/well_known_providers/recommended-models.json b/backend/onyx/llm/well_known_providers/recommended-models.json
index 17abd40804f..ec32ab598fa 100644
--- a/backend/onyx/llm/well_known_providers/recommended-models.json
+++ b/backend/onyx/llm/well_known_providers/recommended-models.json
@@ -16,6 +16,10 @@
           "name": "claude-opus-4-6",
           "display_name": "Claude Opus 4.6"
         },
+        {
+          "name": "claude-sonnet-4-6",
+          "display_name": "Claude Sonnet 4.6"
+        },
         {
           "name": "claude-opus-4-5",
           "display_name": "Claude Opus 4.5"
diff --git a/web/src/app/craft/components/ToggleWarningModal.tsx b/web/src/app/craft/components/ToggleWarningModal.tsx
index b2ade32baaa..88b36fdfb64 100644
--- a/web/src/app/craft/components/ToggleWarningModal.tsx
+++ b/web/src/app/craft/components/ToggleWarningModal.tsx
@@ -39,7 +39,7 @@ export function ToggleWarningModal({
           {/* Message */}
           <div className="flex justify-center">
             <Text mainUiBody text04 className="text-center">
-              We recommend using <strong>Claude Opus 4.5</strong> for Crafting.
+              We recommend using <strong>Claude Opus 4.6</strong> for Crafting.
               <br />
               Other models may have reduced capabilities for code creation,
               <br />
diff --git a/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx b/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx
index 0ef46382ad9..a61971d24a7 100644
--- a/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx
+++ b/web/src/app/craft/onboarding/components/OnboardingLlmSetup.tsx
@@ -34,8 +34,8 @@ export const PROVIDERS: ProviderConfig[] = [
     providerName: LLMProviderName.ANTHROPIC,
     recommended: true,
     models: [
-      { name: "claude-opus-4-5", label: "Claude Opus 4.5", recommended: true },
-      { name: "claude-sonnet-4-5", label: "Claude Sonnet 4.5" },
+      { name: "claude-opus-4-6", label: "Claude Opus 4.6", recommended: true },
+      { name: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
     ],
     apiKeyPlaceholder: "sk-ant-...",
     apiKeyUrl: "https://console.anthropic.com/dashboard",
diff --git a/web/src/app/craft/onboarding/constants.ts b/web/src/app/craft/onboarding/constants.ts
index e0d6ee80e0f..510f9323695 100644
--- a/web/src/app/craft/onboarding/constants.ts
+++ b/web/src/app/craft/onboarding/constants.ts
@@ -5,12 +5,12 @@
 export interface BuildLlmSelection {
   providerName: string; // e.g., "build-mode-anthropic" (LLMProviderDescriptor.name)
   provider: string; // e.g., "anthropic"
-  modelName: string; // e.g., "claude-opus-4-5"
+  modelName: string; // e.g., "claude-opus-4-6"
 }
 
 // Priority order for smart default LLM selection
 const LLM_SELECTION_PRIORITY = [
-  { provider: "anthropic", modelName: "claude-opus-4-5" },
+  { provider: "anthropic", modelName: "claude-opus-4-6" },
   { provider: "openai", modelName: "gpt-5.2" },
   { provider: "openrouter", modelName: "minimax/minimax-m2.1" },
 ] as const;
@@ -63,11 +63,11 @@ export function getDefaultLlmSelection(
 export const RECOMMENDED_BUILD_MODELS = {
   preferred: {
     provider: "anthropic",
-    modelName: "claude-opus-4-5",
-    displayName: "Claude Opus 4.5",
+    modelName: "claude-opus-4-6",
+    displayName: "Claude Opus 4.6",
   },
   alternatives: [
-    { provider: "anthropic", modelName: "claude-sonnet-4-5" },
+    { provider: "anthropic", modelName: "claude-sonnet-4-6" },
     { provider: "openai", modelName: "gpt-5.2" },
     { provider: "openai", modelName: "gpt-5.1-codex" },
     { provider: "openrouter", modelName: "minimax/minimax-m2.1" },
@@ -148,8 +148,8 @@ export const BUILD_MODE_PROVIDERS: BuildModeProvider[] = [
     providerName: "anthropic",
     recommended: true,
     models: [
-      { name: "claude-opus-4-5", label: "Claude Opus 4.5", recommended: true },
-      { name: "claude-sonnet-4-5", label: "Claude Sonnet 4.5" },
+      { name: "claude-opus-4-6", label: "Claude Opus 4.6", recommended: true },
+      { name: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
     ],
     apiKeyPlaceholder: "sk-ant-...",
     apiKeyUrl: "https://console.anthropic.com/dashboard",
diff --git a/web/src/sections/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx
index 845baa9d348..8c47fd6ad63 100644
--- a/web/src/sections/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx
+++ b/web/src/sections/onboarding/forms/__tests__/AnthropicOnboardingForm.test.tsx
@@ -10,7 +10,6 @@ import {
   createMockOnboardingActions,
   createMockFetchResponses,
   MOCK_PROVIDERS,
-  ANTHROPIC_DEFAULT_VISIBLE_MODELS,
 } from "./testHelpers";
 
 // Mock fetch
@@ -51,8 +50,6 @@ jest.mock("@/components/modals/ProviderModal", () => ({
   },
 }));
 
-// Mock fetchModels utility - returns the curated Anthropic visible models
-// that match ANTHROPIC_VISIBLE_MODEL_NAMES from backend
 const mockFetchModels = jest.fn().mockResolvedValue({
   models: [
     {
@@ -152,71 +149,6 @@ describe("AnthropicOnboardingForm", () => {
     });
   });
 
-  describe("Default Available Models", () => {
-    /**
-     * This test verifies that the exact curated list of Anthropic visible models
-     * matches what's returned from /api/admin/llm/built-in/options.
-     * The expected models are defined in ANTHROPIC_VISIBLE_MODEL_NAMES in
-     * backend/onyx/llm/llm_provider_options.py
-     */
-    test("llmDescriptor contains the correct default visible models from built-in options", () => {
-      const expectedModelNames = [
-        "claude-opus-4-5",
-        "claude-sonnet-4-5",
-        "claude-haiku-4-5",
-      ];
-
-      // Verify MOCK_PROVIDERS.anthropic has the correct model configurations
-      const actualModelNames = MOCK_PROVIDERS.anthropic.known_models.map(
-        (config) => config.name
-      );
-
-      // Check that all expected models are present
-      expect(actualModelNames).toEqual(
-        expect.arrayContaining(expectedModelNames)
-      );
-
-      // Check that only the expected models are present (no extras)
-      expect(actualModelNames).toHaveLength(expectedModelNames.length);
-
-      // Verify each model has is_visible set to true
-      MOCK_PROVIDERS.anthropic.known_models.forEach((config) => {
-        expect(config.is_visible).toBe(true);
-      });
-    });
-
-    test("ANTHROPIC_DEFAULT_VISIBLE_MODELS matches backend ANTHROPIC_VISIBLE_MODEL_NAMES", () => {
-      // These are the exact model names from backend/onyx/llm/llm_provider_options.py
-      // ANTHROPIC_VISIBLE_MODEL_NAMES = {"claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"}
-      const backendVisibleModelNames = new Set([
-        "claude-opus-4-5",
-        "claude-sonnet-4-5",
-        "claude-haiku-4-5",
-      ]);
-
-      const testHelperModelNames = new Set(
-        ANTHROPIC_DEFAULT_VISIBLE_MODELS.map((m) => m.name)
-      );
-
-      expect(testHelperModelNames).toEqual(backendVisibleModelNames);
-    });
-
-    test("all default models are marked as visible", () => {
-      ANTHROPIC_DEFAULT_VISIBLE_MODELS.forEach((model) => {
-        expect(model.is_visible).toBe(true);
-      });
-    });
-
-    test("default model claude-sonnet-4-5 is set correctly in component", () => {
-      // The AnthropicOnboardingForm sets DEFAULT_DEFAULT_MODEL_NAME = "claude-sonnet-4-5"
-      // Verify this model exists in the default visible models
-      const defaultModelExists = ANTHROPIC_DEFAULT_VISIBLE_MODELS.some(
-        (m) => m.name === "claude-sonnet-4-5"
-      );
-      expect(defaultModelExists).toBe(true);
-    });
-  });
-
   describe("Form Validation", () => {
     test("submit button is disabled when form is empty", () => {
       render(<AnthropicOnboardingForm {...defaultProps} />);
diff --git a/web/src/sections/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx
index 2d931a12bf9..20abf9be656 100644
--- a/web/src/sections/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx
+++ b/web/src/sections/onboarding/forms/__tests__/OpenAIOnboardingForm.test.tsx
@@ -10,7 +10,6 @@ import {
   createMockOnboardingActions,
   createMockFetchResponses,
   MOCK_PROVIDERS,
-  OPENAI_DEFAULT_VISIBLE_MODELS,
 } from "./testHelpers";
 
 // Mock fetch
@@ -54,8 +53,6 @@ jest.mock("@/components/modals/ProviderModal", () => ({
   },
 }));
 
-// Mock fetchModels utility - returns the curated OpenAI visible models
-// that match OPENAI_VISIBLE_MODEL_NAMES from backend
 const mockFetchModels = jest.fn().mockResolvedValue({
   models: [
     {
@@ -173,77 +170,6 @@ describe("OpenAIOnboardingForm", () => {
     });
   });
 
-  describe("Default Available Models", () => {
-    /**
-     * This test verifies that the exact curated list of OpenAI visible models
-     * matches what's returned from /api/admin/llm/built-in/options.
-     * The expected models are defined in OPENAI_VISIBLE_MODEL_NAMES in
-     * backend/onyx/llm/llm_provider_options.py
-     */
-    test("llmDescriptor contains the correct default visible models from built-in options", () => {
-      const expectedModelNames = [
-        "gpt-5.2",
-        "gpt-5-mini",
-        "o1",
-        "o3-mini",
-        "gpt-4o",
-        "gpt-4o-mini",
-      ];
-
-      // Verify MOCK_PROVIDERS.openai has the correct model configurations
-      const actualModelNames = MOCK_PROVIDERS.openai.known_models.map(
-        (config) => config.name
-      );
-
-      // Check that all expected models are present
-      expect(actualModelNames).toEqual(
-        expect.arrayContaining(expectedModelNames)
-      );
-
-      // Check that only the expected models are present (no extras)
-      expect(actualModelNames).toHaveLength(expectedModelNames.length);
-
-      // Verify each model has is_visible set to true
-      MOCK_PROVIDERS.openai.known_models.forEach((config) => {
-        expect(config.is_visible).toBe(true);
-      });
-    });
-
-    test("OPENAI_DEFAULT_VISIBLE_MODELS matches backend OPENAI_VISIBLE_MODEL_NAMES", () => {
-      // These are the exact model names from backend/onyx/llm/llm_provider_options.py
-      // OPENAI_VISIBLE_MODEL_NAMES = {"gpt-5.2", "gpt-5-mini", "o1", "o3-mini", "gpt-4o", "gpt-4o-mini"}
-      const backendVisibleModelNames = new Set([
-        "gpt-5.2",
-        "gpt-5-mini",
-        "o1",
-        "o3-mini",
-        "gpt-4o",
-        "gpt-4o-mini",
-      ]);
-
-      const testHelperModelNames = new Set(
-        OPENAI_DEFAULT_VISIBLE_MODELS.map((m) => m.name)
-      );
-
-      expect(testHelperModelNames).toEqual(backendVisibleModelNames);
-    });
-
-    test("all default models are marked as visible", () => {
-      OPENAI_DEFAULT_VISIBLE_MODELS.forEach((model) => {
-        expect(model.is_visible).toBe(true);
-      });
-    });
-
-    test("default model gpt-5.2 is set correctly in component", () => {
-      // The OpenAIOnboardingForm sets DEFAULT_DEFAULT_MODEL_NAME = "gpt-5.2"
-      // Verify this model exists in the default visible models
-      const defaultModelExists = OPENAI_DEFAULT_VISIBLE_MODELS.some(
-        (m) => m.name === "gpt-5.2"
-      );
-      expect(defaultModelExists).toBe(true);
-    });
-  });
-
   describe("Form Validation", () => {
     test("submit button is disabled when form is empty", () => {
       render(<OpenAIOnboardingForm {...defaultProps} />);
diff --git a/web/src/sections/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx b/web/src/sections/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx
index 649d6cdf24b..fcb0751d84a 100644
--- a/web/src/sections/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx
+++ b/web/src/sections/onboarding/forms/__tests__/VertexAIOnboardingForm.test.tsx
@@ -10,7 +10,6 @@ import {
   createMockOnboardingActions,
   createMockFetchResponses,
   MOCK_PROVIDERS,
-  VERTEXAI_DEFAULT_VISIBLE_MODELS,
 } from "./testHelpers";
 
 // Mock fetch
@@ -51,8 +50,6 @@ jest.mock("@/components/modals/ProviderModal", () => ({
   },
 }));
 
-// Mock fetchModels utility - returns the curated Vertex AI visible models
-// that match VERTEXAI_VISIBLE_MODEL_NAMES from backend
 jest.mock("@/app/admin/configuration/llm/utils", () => ({
   canProviderFetchModels: jest.fn().mockReturnValue(true),
   fetchModels: jest.fn().mockResolvedValue({
@@ -154,71 +151,6 @@ describe("VertexAIOnboardingForm", () => {
     });
   });
 
-  describe("Default Available Models", () => {
-    /**
-     * This test verifies that the exact curated list of Vertex AI visible models
-     * matches what's returned from /api/admin/llm/built-in/options.
-     * The expected models are defined in VERTEXAI_VISIBLE_MODEL_NAMES in
-     * backend/onyx/llm/llm_provider_options.py
-     */
-    test("llmDescriptor contains the correct default visible models from built-in options", () => {
-      const expectedModelNames = [
-        "gemini-2.5-flash",
-        "gemini-2.5-flash-lite",
-        "gemini-2.5-pro",
-      ];
-
-      // Verify MOCK_PROVIDERS.vertexAi has the correct model configurations
-      const actualModelNames = MOCK_PROVIDERS.vertexAi.known_models.map(
-        (config) => config.name
-      );
-
-      // Check that all expected models are present
-      expect(actualModelNames).toEqual(
-        expect.arrayContaining(expectedModelNames)
-      );
-
-      // Check that only the expected models are present (no extras)
-      expect(actualModelNames).toHaveLength(expectedModelNames.length);
-
-      // Verify each model has is_visible set to true
-      MOCK_PROVIDERS.vertexAi.known_models.forEach((config) => {
-        expect(config.is_visible).toBe(true);
-      });
-    });
-
-    test("VERTEXAI_DEFAULT_VISIBLE_MODELS matches backend VERTEXAI_VISIBLE_MODEL_NAMES", () => {
-      // These are the exact model names from backend/onyx/llm/llm_provider_options.py
-      // VERTEXAI_VISIBLE_MODEL_NAMES = {"gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.5-pro"}
-      const backendVisibleModelNames = new Set([
-        "gemini-2.5-flash",
-        "gemini-2.5-flash-lite",
-        "gemini-2.5-pro",
-      ]);
-
-      const testHelperModelNames = new Set(
-        VERTEXAI_DEFAULT_VISIBLE_MODELS.map((m) => m.name)
-      );
-
-      expect(testHelperModelNames).toEqual(backendVisibleModelNames);
-    });
-
-    test("all default models are marked as visible", () => {
-      VERTEXAI_DEFAULT_VISIBLE_MODELS.forEach((model) => {
-        expect(model.is_visible).toBe(true);
-      });
-    });
-
-    test("default model gemini-2.5-pro is set correctly in component", () => {
-      // The VertexAIOnboardingForm sets DEFAULT_DEFAULT_MODEL_NAME = "gemini-2.5-pro"
-      // Verify this model exists in the default visible models
-      const defaultModelExists = VERTEXAI_DEFAULT_VISIBLE_MODELS.some(
-        (m) => m.name === "gemini-2.5-pro"
-      );
-      expect(defaultModelExists).toBe(true);
-    });
-  });
-
   describe("Form Validation", () => {
     test("submit button is disabled when form is empty", () => {
       render(<VertexAIOnboardingForm {...defaultProps} />);
diff --git a/web/src/sections/onboarding/forms/__tests__/testHelpers.tsx b/web/src/sections/onboarding/forms/__tests__/testHelpers.tsx
index 5f146728e3d..e461e43ff4e 100644
--- a/web/src/sections/onboarding/forms/__tests__/testHelpers.tsx
+++ b/web/src/sections/onboarding/forms/__tests__/testHelpers.tsx
@@ -1,7 +1,6 @@
 /**
  * Shared test helpers and mocks for onboarding form tests
  */
-import React from "react";
 
 // Mock Element.prototype.scrollIntoView for JSDOM (not implemented in jsdom)
 Element.prototype.scrollIntoView = jest.fn();
@@ -161,11 +160,6 @@ export async function waitForModalOpen(screen: any, waitFor: any) {
 /**
  * Common provider descriptors for testing
  */
-/**
- * The curated list of OpenAI visible models that are returned by
- * /api/admin/llm/built-in/options. This must match OPENAI_VISIBLE_MODEL_NAMES
- * in backend/onyx/llm/llm_provider_options.py
- */
 export const OPENAI_DEFAULT_VISIBLE_MODELS = [
   {
     name: "gpt-5.2",
@@ -211,11 +205,6 @@ export const OPENAI_DEFAULT_VISIBLE_MODELS = [
   },
 ];
 
-/**
- * The curated list of Anthropic visible models that are returned by
- * /api/admin/llm/built-in/options. This must match ANTHROPIC_VISIBLE_MODEL_NAMES
- * in backend/onyx/llm/llm_provider_options.py
- */
 export const ANTHROPIC_DEFAULT_VISIBLE_MODELS = [
   {
     name: "claude-opus-4-5",
@@ -240,11 +229,6 @@ export const ANTHROPIC_DEFAULT_VISIBLE_MODELS = [
   },
 ];
 
-/**
- * The curated list of Vertex AI visible models that are returned by
- * /api/admin/llm/built-in/options. This must match VERTEXAI_VISIBLE_MODEL_NAMES
- * in backend/onyx/llm/llm_provider_options.py
- */
 export const VERTEXAI_DEFAULT_VISIBLE_MODELS = [
   {
     name: "gemini-2.5-flash",

From 472d1788a722ed15f1923a4e675ab19373ce459c Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 12:46:56 -0800
Subject: [PATCH 157/267] fix(fe): add horizontal padding to chat page (#9147)

---
 web/src/refresh-pages/AppPage.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index b426d930495..e2d9ea1efb4 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -709,7 +709,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
             >
               {/* Main content grid — 3 rows, animated */}
               <div
-                className="flex-1 w-full grid min-h-0 transition-[grid-template-rows] duration-150 ease-in-out"
+                className="flex-1 w-full grid min-h-0 px-4 transition-[grid-template-rows] duration-150 ease-in-out"
                 style={gridStyle}
               >
                 {/* ── Top row: ChatUI / WelcomeMessage / ProjectUI ── */}

From c527f755571919a342a1fd9f3d037b6667ed203f Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Fri, 6 Mar 2026 13:00:36 -0800
Subject: [PATCH 158/267] fix(ci): release workflow and ods build file
 improvements (#9149)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 .github/workflows/release-cli.yml      |  1 -
 .github/workflows/release-devtools.yml |  2 --
 tools/ods/hatch_build.py               | 12 ++++--------
 tools/ods/internal/_version.py         |  5 ++++-
 tools/ods/pyproject.toml               |  7 +++++--
 5 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index c33a18bee4e..82cbeefa2a9 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -26,7 +26,6 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           persist-credentials: false
-          fetch-depth: 0
       - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
diff --git a/.github/workflows/release-devtools.yml b/.github/workflows/release-devtools.yml
index d883d2d206d..0fde4304eae 100644
--- a/.github/workflows/release-devtools.yml
+++ b/.github/workflows/release-devtools.yml
@@ -22,12 +22,10 @@ jobs:
           - { goos: "windows", goarch: "arm64" }
           - { goos: "darwin", goarch: "amd64" }
           - { goos: "darwin", goarch: "arm64" }
-          - { goos: "", goarch: "" }
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           persist-credentials: false
-          fetch-depth: 0
       - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
diff --git a/tools/ods/hatch_build.py b/tools/ods/hatch_build.py
index 71701b4b621..536503b9794 100644
--- a/tools/ods/hatch_build.py
+++ b/tools/ods/hatch_build.py
@@ -26,20 +26,16 @@ def initialize(self, version: Any, build_data: Any) -> None:  # noqa: ARG002
 
         # Get config and environment
         binary_name = self.config["binary_name"]
-        tag = os.getenv("GITHUB_REF_NAME", "dev").removeprefix(f"{binary_name}/")
+        tag_prefix = self.config.get("tag_prefix", binary_name)
+        tag = os.getenv("GITHUB_REF_NAME", "dev").removeprefix(f"{tag_prefix}/")
         commit = os.getenv("GITHUB_SHA", "none")
 
         # Build the Go binary if it doesn't exist
         if not os.path.exists(binary_name):
             print(f"Building Go binary '{binary_name}'...")
+            ldflags = f"-X main.version={tag} -X main.commit={commit} -s -w"
             subprocess.check_call(  # noqa: S603
-                [
-                    "go",
-                    "build",
-                    f"-ldflags=-X main.version={tag} -X main.commit={commit} -s -w",
-                    "-o",
-                    binary_name,
-                ],
+                ["go", "build", f"-ldflags={ldflags}", "-o", binary_name],
             )
 
         build_data["shared_scripts"] = {binary_name: binary_name}
diff --git a/tools/ods/internal/_version.py b/tools/ods/internal/_version.py
index 72a06f121d7..3a0714e4e1d 100644
--- a/tools/ods/internal/_version.py
+++ b/tools/ods/internal/_version.py
@@ -3,6 +3,9 @@
 import os
 import re
 
-_tag = os.environ.get("GITHUB_REF_NAME", "v0.0.0-dev").removeprefix("ods/")
+# Must match tag_prefix in pyproject.toml [tool.hatch.build.targets.wheel.hooks.custom]
+TAG_PREFIX: str = "ods"
+
+_tag = os.environ.get("GITHUB_REF_NAME", "v0.0.0-dev").removeprefix(f"{TAG_PREFIX}/")
 _match = re.search(r"v?(\d+\.\d+\.\d+)", _tag)
 __version__ = _match.group(1) if _match else "0.0.0"
diff --git a/tools/ods/pyproject.toml b/tools/ods/pyproject.toml
index 6518359fa4f..7c178f84e74 100644
--- a/tools/ods/pyproject.toml
+++ b/tools/ods/pyproject.toml
@@ -14,7 +14,9 @@ keywords = [
 classifiers = [
     "Programming Language :: Go",
     "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
 ]
 dynamic = ["version"]
 dependencies = [
@@ -27,7 +29,7 @@ dependencies = [
 Repository = "https://github.com/onyx-dot-app/onyx"
 
 [tool.hatch.build]
-include = ["go.mod", "go.sum", "main.go", "**/*.go", "**/*.py"]
+include = ["go.mod", "go.sum", "main.go", "**/*.go", "**/*.py", "README.md"]
 
 [tool.hatch.version]
 source = "code"
@@ -36,6 +38,7 @@ path = "internal/_version.py"
 [tool.hatch.build.targets.wheel.hooks.custom]
 path = "hatch_build.py"
 binary_name = "ods"
+tag_prefix = "ods"
 
 [tool.uv]
 managed = false

From 6590f1d7ba8fefe86b3474dbe66376424385ca52 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Fri, 6 Mar 2026 13:01:42 -0800
Subject: [PATCH 159/267] feat(cli): add PyPI and release workflow badges to
 README (#9148)

---
 cli/README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/cli/README.md b/cli/README.md
index aa5faeb13bd..1cd81cf1841 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -1,5 +1,8 @@
 # Onyx CLI
 
+[![Release CLI](https://github.com/onyx-dot-app/onyx/actions/workflows/release-cli.yml/badge.svg)](https://github.com/onyx-dot-app/onyx/actions/workflows/release-cli.yml)
+[![PyPI](https://img.shields.io/pypi/v/onyx-cli.svg)](https://pypi.org/project/onyx-cli/)
+
 A terminal interface for chatting with your [Onyx](https://github.com/onyx-dot-app/onyx) agent. Built with Go using [Bubble Tea](https://github.com/charmbracelet/bubbletea) for the TUI framework.
 
 ## Installation

From 8816d52b2771937ed7cba9e9ee60164e87b7773b Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Fri, 6 Mar 2026 13:08:07 -0800
Subject: [PATCH 160/267] fix: vespa filter restrictions (#9138)

---
 .../onyx/document_index/FILTER_SEMANTICS.md   | 103 ++++++++++++++
 .../onyx/document_index/opensearch/search.py  | 103 ++++++--------
 .../shared_utils/vespa_request_builders.py    | 128 +++++++++---------
 .../tests/unit/onyx/utils/test_vespa_query.py |  67 +++++++--
 4 files changed, 265 insertions(+), 136 deletions(-)
 create mode 100644 backend/onyx/document_index/FILTER_SEMANTICS.md

diff --git a/backend/onyx/document_index/FILTER_SEMANTICS.md b/backend/onyx/document_index/FILTER_SEMANTICS.md
new file mode 100644
index 00000000000..5b0cc763e8f
--- /dev/null
+++ b/backend/onyx/document_index/FILTER_SEMANTICS.md
@@ -0,0 +1,103 @@
+# Vector DB Filter Semantics
+
+How `IndexFilters` fields combine into the final query filter. Applies to both Vespa and OpenSearch.
+
+## Filter categories
+
+| Category | Fields | Join logic |
+|---|---|---|
+| **Visibility** | `hidden` | Always applied (unless `include_hidden`) |
+| **Tenant** | `tenant_id` | AND (multi-tenant only) |
+| **ACL** | `access_control_list` | OR within, AND with rest |
+| **Narrowing** | `source_type`, `tags`, `time_cutoff` | Each OR within, AND with rest |
+| **Knowledge scope** | `document_set`, `user_file_ids`, `attached_document_ids`, `hierarchy_node_ids` | OR within group, AND with rest |
+| **Additive scope** | `project_id`, `persona_id` | OR'd into knowledge scope **only when** a knowledge scope filter already exists |
+
+## How filters combine
+
+All categories are AND'd together. Within the knowledge scope category, individual filters are OR'd.
+
+```
+NOT hidden
+AND tenant = T                          -- if multi-tenant
+AND (acl contains A1 OR acl contains A2)
+AND (source_type = S1 OR ...)           -- if set
+AND (tag = T1 OR ...)                   -- if set
+AND <knowledge scope>                   -- see below
+AND time >= cutoff                      -- if set
+```
+
+## Knowledge scope rules
+
+The knowledge scope filter controls **what knowledge an assistant can access**.
+
+### No explicit knowledge attached
+
+When `document_set`, `user_file_ids`, `attached_document_ids`, and `hierarchy_node_ids` are all empty/None:
+
+- **No knowledge scope filter is applied.** The assistant can see everything (subject to ACL).
+- `project_id` and `persona_id` are ignored — they never restrict on their own.
+
+### One explicit knowledge type
+
+```
+-- Only document sets
+AND (document_sets contains "Engineering" OR document_sets contains "Legal")
+
+-- Only user files
+AND (document_id = "uuid-1" OR document_id = "uuid-2")
+```
+
+### Multiple explicit knowledge types (OR'd)
+
+```
+-- Document sets + user files
+AND (
+    document_sets contains "Engineering"
+    OR document_id = "uuid-1"
+)
+```
+
+### Explicit knowledge + overflowing user files
+
+When an explicit knowledge restriction is in effect **and** `project_id` or `persona_id` is set (user files overflowed the LLM context window), the additive scopes widen the filter:
+
+```
+-- Document sets + persona user files overflowed
+AND (
+    document_sets contains "Engineering"
+    OR personas contains 42
+)
+
+-- User files + project files overflowed
+AND (
+    document_id = "uuid-1"
+    OR user_project contains 7
+)
+```
+
+### Only project_id or persona_id (no explicit knowledge)
+
+No knowledge scope filter. The assistant searches everything.
+
+```
+-- Just ACL, no restriction
+NOT hidden
+AND (acl contains ...)
+```
+
+## Field reference
+
+| Filter field | Vespa field | Vespa type | Purpose |
+|---|---|---|---|
+| `document_set` | `document_sets` | `weightedset<string>` | Connector doc sets attached to assistant |
+| `user_file_ids` | `document_id` | `string` | User files uploaded to assistant |
+| `attached_document_ids` | `document_id` | `string` | Documents explicitly attached (OpenSearch only) |
+| `hierarchy_node_ids` | `ancestor_hierarchy_node_ids` | `array<int>` | Folder/space nodes (OpenSearch only) |
+| `project_id` | `user_project` | `array<int>` | Project tag for overflowing user files |
+| `persona_id` | `personas` | `array<int>` | Persona tag for overflowing user files |
+| `access_control_list` | `access_control_list` | `weightedset<string>` | ACL entries for the requesting user |
+| `source_type` | `source_type` | `string` | Connector source type (e.g. `web`, `jira`) |
+| `tags` | `metadata_list` | `array<string>` | Document metadata tags |
+| `time_cutoff` | `doc_updated_at` | `long` | Minimum document update timestamp |
+| `tenant_id` | `tenant_id` | `string` | Tenant isolation (multi-tenant) |
diff --git a/backend/onyx/document_index/opensearch/search.py b/backend/onyx/document_index/opensearch/search.py
index 7ff7a5002f7..3a699069194 100644
--- a/backend/onyx/document_index/opensearch/search.py
+++ b/backend/onyx/document_index/opensearch/search.py
@@ -698,41 +698,6 @@ def _get_hierarchy_node_filter(
             """
             return {"terms": {ANCESTOR_HIERARCHY_NODE_IDS_FIELD_NAME: node_ids}}
 
-        def _get_assistant_knowledge_filter(
-            attached_doc_ids: list[str] | None,
-            node_ids: list[int] | None,
-            file_ids: list[UUID] | None,
-            document_sets: list[str] | None,
-        ) -> dict[str, Any]:
-            """Combined filter for assistant knowledge.
-
-            When an assistant has attached knowledge, search should be scoped to:
-            - Documents explicitly attached (by document ID), OR
-            - Documents under attached hierarchy nodes (by ancestor node IDs), OR
-            - User-uploaded files attached to the assistant, OR
-            - Documents in the assistant's document sets (if any)
-            """
-            knowledge_filter: dict[str, Any] = {
-                "bool": {"should": [], "minimum_should_match": 1}
-            }
-            if attached_doc_ids:
-                knowledge_filter["bool"]["should"].append(
-                    _get_attached_document_id_filter(attached_doc_ids)
-                )
-            if node_ids:
-                knowledge_filter["bool"]["should"].append(
-                    _get_hierarchy_node_filter(node_ids)
-                )
-            if file_ids:
-                knowledge_filter["bool"]["should"].append(
-                    _get_user_file_id_filter(file_ids)
-                )
-            if document_sets:
-                knowledge_filter["bool"]["should"].append(
-                    _get_document_set_filter(document_sets)
-                )
-            return knowledge_filter
-
         filter_clauses: list[dict[str, Any]] = []
 
         if not include_hidden:
@@ -758,41 +723,53 @@ def _get_assistant_knowledge_filter(
             # document's metadata list.
             filter_clauses.append(_get_tag_filter(tags))
 
-        # Check if this is an assistant knowledge search (has any assistant-scoped knowledge)
-        has_assistant_knowledge = (
+        # Knowledge scope: explicit knowledge attachments restrict what
+        # an assistant can see.  When none are set the assistant
+        # searches everything.
+        #
+        # project_id / persona_id are additive: they make overflowing
+        # user files findable but must NOT trigger the restriction on
+        # their own (an agent with no explicit knowledge should search
+        # everything).
+        has_knowledge_scope = (
             attached_document_ids
             or hierarchy_node_ids
             or user_file_ids
             or document_sets
         )
 
-        if has_assistant_knowledge:
-            # If assistant has attached knowledge, scope search to that knowledge.
-            # Document sets are included in the OR filter so directly attached
-            # docs are always findable even if not in the document sets.
-            filter_clauses.append(
-                _get_assistant_knowledge_filter(
-                    attached_document_ids,
-                    hierarchy_node_ids,
-                    user_file_ids,
-                    document_sets,
+        if has_knowledge_scope:
+            knowledge_filter: dict[str, Any] = {
+                "bool": {"should": [], "minimum_should_match": 1}
+            }
+            if attached_document_ids:
+                knowledge_filter["bool"]["should"].append(
+                    _get_attached_document_id_filter(attached_document_ids)
                 )
-            )
-        elif user_file_ids:
-            # Fallback for non-assistant user file searches (e.g., project searches)
-            # If at least one user file ID is provided, the caller will only
-            # retrieve documents where the document ID is in this input list of
-            # file IDs.
-            filter_clauses.append(_get_user_file_id_filter(user_file_ids))
-
-        if project_id is not None:
-            # If a project ID is provided, the caller will only retrieve
-            # documents where the project ID provided here is present in the
-            # document's user projects list.
-            filter_clauses.append(_get_user_project_filter(project_id))
-
-        if persona_id is not None:
-            filter_clauses.append(_get_persona_filter(persona_id))
+            if hierarchy_node_ids:
+                knowledge_filter["bool"]["should"].append(
+                    _get_hierarchy_node_filter(hierarchy_node_ids)
+                )
+            if user_file_ids:
+                knowledge_filter["bool"]["should"].append(
+                    _get_user_file_id_filter(user_file_ids)
+                )
+            if document_sets:
+                knowledge_filter["bool"]["should"].append(
+                    _get_document_set_filter(document_sets)
+                )
+            # Additive: widen scope to also cover overflowing user
+            # files, but only when an explicit restriction is already
+            # in effect.
+            if project_id is not None:
+                knowledge_filter["bool"]["should"].append(
+                    _get_user_project_filter(project_id)
+                )
+            if persona_id is not None:
+                knowledge_filter["bool"]["should"].append(
+                    _get_persona_filter(persona_id)
+                )
+            filter_clauses.append(knowledge_filter)
 
         if time_cutoff is not None:
             # If a time cutoff is provided, the caller will only retrieve
diff --git a/backend/onyx/document_index/vespa/shared_utils/vespa_request_builders.py b/backend/onyx/document_index/vespa/shared_utils/vespa_request_builders.py
index 276f32b9aae..28653d6c29b 100644
--- a/backend/onyx/document_index/vespa/shared_utils/vespa_request_builders.py
+++ b/backend/onyx/document_index/vespa/shared_utils/vespa_request_builders.py
@@ -23,11 +23,8 @@
 logger = setup_logger()
 
 
-def build_tenant_id_filter(tenant_id: str, include_trailing_and: bool = False) -> str:
-    filter_str = f'({TENANT_ID} contains "{tenant_id}")'
-    if include_trailing_and:
-        filter_str += " and "
-    return filter_str
+def build_tenant_id_filter(tenant_id: str) -> str:
+    return f'({TENANT_ID} contains "{tenant_id}")'
 
 
 def build_vespa_filters(
@@ -37,30 +34,22 @@ def build_vespa_filters(
     remove_trailing_and: bool = False,  # Set to True when using as a complete Vespa query
 ) -> str:
     def _build_or_filters(key: str, vals: list[str] | None) -> str:
-        """For string-based 'contains' filters, e.g. WSET fields or array<string> fields."""
+        """For string-based 'contains' filters, e.g. WSET fields or array<string> fields.
+        Returns a bare clause like '(key contains "v1" or key contains "v2")' or ""."""
         if not key or not vals:
             return ""
         eq_elems = [f'{key} contains "{val}"' for val in vals if val]
         if not eq_elems:
             return ""
-        or_clause = " or ".join(eq_elems)
-        return f"({or_clause}) and "
+        return f"({' or '.join(eq_elems)})"
 
     def _build_int_or_filters(key: str, vals: list[int] | None) -> str:
-        """
-        For an integer field filter.
-        If vals is not None, we want *only* docs whose key matches one of vals.
-        """
-        # If `vals` is None => skip the filter entirely
+        """For an integer field filter.
+        Returns a bare clause or ""."""
         if vals is None or not vals:
             return ""
-
-        # Otherwise build the OR filter
         eq_elems = [f"{key} = {val}" for val in vals]
-        or_clause = " or ".join(eq_elems)
-        result = f"({or_clause}) and "
-
-        return result
+        return f"({' or '.join(eq_elems)})"
 
     def _build_kg_filter(
         kg_entities: list[str] | None,
@@ -73,16 +62,12 @@ def _build_kg_filter(
         combined_filter_parts = []
 
         def _build_kge(entity: str) -> str:
-            # TYPE-SUBTYPE::ID -> "TYPE-SUBTYPE::ID"
-            # TYPE-SUBTYPE::*  -> ({prefix: true}"TYPE-SUBTYPE")
-            # TYPE::*          -> ({prefix: true}"TYPE")
             GENERAL = "::*"
             if entity.endswith(GENERAL):
                 return f'({{prefix: true}}"{entity.split(GENERAL, 1)[0]}")'
             else:
                 return f'"{entity}"'
 
-        # OR the entities (give new design)
         if kg_entities:
             filter_parts = []
             for kg_entity in kg_entities:
@@ -104,8 +89,7 @@ def _build_kge(entity: str) -> str:
 
         # TODO: remove kg terms entirely from prompts and codebase
 
-        # AND the combined filter parts
-        return f"({' and '.join(combined_filter_parts)}) and "
+        return f"({' and '.join(combined_filter_parts)})"
 
     def _build_kg_source_filters(
         kg_sources: list[str] | None,
@@ -114,16 +98,14 @@ def _build_kg_source_filters(
             return ""
 
         source_phrases = [f'{DOCUMENT_ID} contains "{source}"' for source in kg_sources]
-
-        return f"({' or '.join(source_phrases)}) and "
+        return f"({' or '.join(source_phrases)})"
 
     def _build_kg_chunk_id_zero_only_filter(
         kg_chunk_id_zero_only: bool,
     ) -> str:
         if not kg_chunk_id_zero_only:
             return ""
-
-        return "(chunk_id = 0 ) and "
+        return "(chunk_id = 0)"
 
     def _build_time_filter(
         cutoff: datetime | None,
@@ -135,8 +117,8 @@ def _build_time_filter(
         cutoff_secs = int(cutoff.timestamp())
 
         if include_untimed:
-            return f"!({DOC_UPDATED_AT} < {cutoff_secs}) and "
-        return f"({DOC_UPDATED_AT} >= {cutoff_secs}) and "
+            return f"!({DOC_UPDATED_AT} < {cutoff_secs})"
+        return f"({DOC_UPDATED_AT} >= {cutoff_secs})"
 
     def _build_user_project_filter(
         project_id: int | None,
@@ -147,8 +129,7 @@ def _build_user_project_filter(
             pid = int(project_id)
         except Exception:
             return ""
-        # Vespa YQL 'contains' expects a string literal; quote the integer
-        return f'({USER_PROJECT} contains "{pid}") and '
+        return f'({USER_PROJECT} contains "{pid}")'
 
     def _build_persona_filter(
         persona_id: int | None,
@@ -160,73 +141,94 @@ def _build_persona_filter(
         except Exception:
             logger.warning(f"Invalid persona ID: {persona_id}")
             return ""
-        return f'({PERSONAS} contains "{pid}") and '
+        return f'({PERSONAS} contains "{pid}")'
+
+    def _append(parts: list[str], clause: str) -> None:
+        if clause:
+            parts.append(clause)
 
-    # Start building the filter string
-    filter_str = f"!({HIDDEN}=true) and " if not include_hidden else ""
+    # Collect all top-level filter clauses, then join with " and " at the end.
+    filter_parts: list[str] = []
+
+    if not include_hidden:
+        filter_parts.append(f"!({HIDDEN}=true)")
 
     # TODO: add error condition if MULTI_TENANT and no tenant_id filter is set
-    # If running in multi-tenant mode
     if filters.tenant_id and MULTI_TENANT:
-        filter_str += build_tenant_id_filter(
-            filters.tenant_id, include_trailing_and=True
-        )
+        filter_parts.append(build_tenant_id_filter(filters.tenant_id))
 
     # ACL filters
     if filters.access_control_list is not None:
-        filter_str += _build_or_filters(
-            ACCESS_CONTROL_LIST, filters.access_control_list
+        _append(
+            filter_parts,
+            _build_or_filters(ACCESS_CONTROL_LIST, filters.access_control_list),
         )
 
     # Source type filters
     source_strs = (
         [s.value for s in filters.source_type] if filters.source_type else None
     )
-    filter_str += _build_or_filters(SOURCE_TYPE, source_strs)
+    _append(filter_parts, _build_or_filters(SOURCE_TYPE, source_strs))
 
     # Tag filters
     tag_attributes = None
     if filters.tags:
-        # build e.g. "tag_key|tag_value"
         tag_attributes = [
             f"{tag.tag_key}{INDEX_SEPARATOR}{tag.tag_value}" for tag in filters.tags
         ]
-    filter_str += _build_or_filters(METADATA_LIST, tag_attributes)
-
-    # Document sets
-    filter_str += _build_or_filters(DOCUMENT_SETS, filters.document_set)
+    _append(filter_parts, _build_or_filters(METADATA_LIST, tag_attributes))
+
+    # Knowledge scope: explicit knowledge attachments (document_sets,
+    # user_file_ids) restrict what an assistant can see.  When none are
+    # set, the assistant can see everything.
+    #
+    # project_id / persona_id are additive: they make overflowing user
+    # files findable in Vespa but must NOT trigger the restriction on
+    # their own (an agent with no explicit knowledge should search
+    # everything).
+    knowledge_scope_parts: list[str] = []
+
+    _append(
+        knowledge_scope_parts, _build_or_filters(DOCUMENT_SETS, filters.document_set)
+    )
 
-    # Convert UUIDs to strings for user_file_ids
     user_file_ids_str = (
         [str(uuid) for uuid in filters.user_file_ids] if filters.user_file_ids else None
     )
-    filter_str += _build_or_filters(DOCUMENT_ID, user_file_ids_str)
+    _append(knowledge_scope_parts, _build_or_filters(DOCUMENT_ID, user_file_ids_str))
 
-    # User project filter (array<int> attribute membership)
-    filter_str += _build_user_project_filter(filters.project_id)
+    # Only include project/persona scopes when an explicit knowledge
+    # restriction is already in effect — they widen the scope to also
+    # cover overflowing user files but never restrict on their own.
+    if knowledge_scope_parts:
+        _append(knowledge_scope_parts, _build_user_project_filter(filters.project_id))
+        _append(knowledge_scope_parts, _build_persona_filter(filters.persona_id))
 
-    # Persona filter (array<int> attribute membership)
-    filter_str += _build_persona_filter(filters.persona_id)
+    if len(knowledge_scope_parts) > 1:
+        filter_parts.append("(" + " or ".join(knowledge_scope_parts) + ")")
+    elif len(knowledge_scope_parts) == 1:
+        filter_parts.append(knowledge_scope_parts[0])
 
     # Time filter
-    filter_str += _build_time_filter(filters.time_cutoff)
+    _append(filter_parts, _build_time_filter(filters.time_cutoff))
 
     # # Knowledge Graph Filters
-    # filter_str += _build_kg_filter(
+    # _append(filter_parts, _build_kg_filter(
     #     kg_entities=filters.kg_entities,
     #     kg_relationships=filters.kg_relationships,
     #     kg_terms=filters.kg_terms,
-    # )
+    # ))
 
-    # filter_str += _build_kg_source_filters(filters.kg_sources)
+    # _append(filter_parts, _build_kg_source_filters(filters.kg_sources))
 
-    # filter_str += _build_kg_chunk_id_zero_only_filter(
+    # _append(filter_parts, _build_kg_chunk_id_zero_only_filter(
     #     filters.kg_chunk_id_zero_only or False
-    # )
+    # ))
+
+    filter_str = " and ".join(filter_parts)
 
-    # Trim trailing " and "
-    if remove_trailing_and and filter_str.endswith(" and "):
-        filter_str = filter_str[:-5]
+    if filter_str and not remove_trailing_and:
+        filter_str += " and "
 
     return filter_str
 
diff --git a/backend/tests/unit/onyx/utils/test_vespa_query.py b/backend/tests/unit/onyx/utils/test_vespa_query.py
index 8c63f46c1e2..6caade14500 100644
--- a/backend/tests/unit/onyx/utils/test_vespa_query.py
+++ b/backend/tests/unit/onyx/utils/test_vespa_query.py
@@ -20,8 +20,6 @@
 from onyx.document_index.vespa_constants import USER_PROJECT
 from shared_configs.configs import MULTI_TENANT
 
-# Import the function under test
-
 
 class TestBuildVespaFilters:
     def test_empty_filters(self) -> None:
@@ -179,11 +177,27 @@ def test_user_file_ids_filter(self) -> None:
         assert f"!({HIDDEN}=true) and " == result
 
     def test_user_project_filter(self) -> None:
-        """Test user project filtering (replacement for user folder IDs)."""
-        # Single project id
+        """Test user project filtering.
+
+        project_id alone does NOT trigger a knowledge scope restriction
+        (an agent with no explicit knowledge should search everything).
+        It only participates when explicit knowledge filters are present.
+        """
+        # project_id alone → no restriction
         filters = IndexFilters(access_control_list=[], project_id=789)
         result = build_vespa_filters(filters)
-        assert f'!({HIDDEN}=true) and ({USER_PROJECT} contains "789") and ' == result
+        assert f"!({HIDDEN}=true) and " == result
+
+        # project_id with user_file_ids → both OR'd
+        id1 = UUID("00000000-0000-0000-0000-000000000123")
+        filters = IndexFilters(
+            access_control_list=[], project_id=789, user_file_ids=[id1]
+        )
+        result = build_vespa_filters(filters)
+        assert (
+            f'!({HIDDEN}=true) and (({DOCUMENT_ID} contains "{str(id1)}") or ({USER_PROJECT} contains "789")) and '
+            == result
+        )
 
         # No project id
         filters = IndexFilters(access_control_list=[], project_id=None)
@@ -217,7 +231,11 @@ def test_time_cutoff_filter(self) -> None:
         )
 
     def test_combined_filters(self) -> None:
-        """Test combining multiple filter types."""
+        """Test combining multiple filter types.
+
+        Knowledge-scope filters (document_set, user_file_ids, project_id,
+        persona_id) are OR'd together, while all other filters are AND'd.
+        """
         id1 = UUID("00000000-0000-0000-0000-000000000123")
         filters = IndexFilters(
             access_control_list=["user1", "group1"],
@@ -231,7 +249,6 @@ def test_combined_filters(self) -> None:
 
         result = build_vespa_filters(filters)
 
-        # Build expected result piece by piece for readability
         expected = f"!({HIDDEN}=true) and "
         expected += (
             '(access_control_list contains "user1" or '
@@ -239,9 +256,13 @@ def test_combined_filters(self) -> None:
         )
         expected += f'({SOURCE_TYPE} contains "web") and '
         expected += f'({METADATA_LIST} contains "color{INDEX_SEPARATOR}red") and '
-        expected += f'({DOCUMENT_SETS} contains "set1") and '
-        expected += f'({DOCUMENT_ID} contains "{str(id1)}") and '
-        expected += f'({USER_PROJECT} contains "789") and '
+        # Knowledge scope filters are OR'd together
+        expected += (
+            f'(({DOCUMENT_SETS} contains "set1")'
+            f' or ({DOCUMENT_ID} contains "{str(id1)}")'
+            f' or ({USER_PROJECT} contains "789")'
+            f") and "
+        )
         cutoff_secs = int(datetime(2023, 1, 1, tzinfo=timezone.utc).timestamp())
         expected += f"!({DOC_UPDATED_AT} < {cutoff_secs}) and "
 
@@ -251,6 +272,32 @@ def test_combined_filters(self) -> None:
         result_no_trailing = build_vespa_filters(filters, remove_trailing_and=True)
         assert expected[:-5] == result_no_trailing  # Remove trailing " and "
 
+    def test_knowledge_scope_single_filter_not_wrapped(self) -> None:
+        """When only one knowledge-scope filter is present it should not
+        be wrapped in an extra OR group."""
+        filters = IndexFilters(access_control_list=[], document_set=["set1"])
+        result = build_vespa_filters(filters)
+        assert f'!({HIDDEN}=true) and ({DOCUMENT_SETS} contains "set1") and ' == result
+
+    def test_knowledge_scope_document_set_and_user_files_ored(self) -> None:
+        """Document set filter and user file IDs must be OR'd so that
+        connector documents (in the set) and user files (with specific
+        IDs) can both be found."""
+        id1 = UUID("00000000-0000-0000-0000-000000000123")
+        filters = IndexFilters(
+            access_control_list=[],
+            document_set=["engineering"],
+            user_file_ids=[id1],
+        )
+        result = build_vespa_filters(filters)
+        expected = (
+            f"!({HIDDEN}=true) and "
+            f'(({DOCUMENT_SETS} contains "engineering")'
+            f' or ({DOCUMENT_ID} contains "{str(id1)}")'
+            f") and "
+        )
+        assert expected == result
+
     def test_empty_or_none_values(self) -> None:
         """Test with empty or None values in filter lists."""
         # Empty strings in document set

From bdc2bfdcee34dd9babf3373c3262df1cb59dcc61 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Fri, 6 Mar 2026 13:30:25 -0800
Subject: [PATCH 161/267] fix(fe): account for wrapper padding in textarea
 auto-resize (#9151)

---
 web/src/sections/input/AppInputBar.tsx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index ec41d413d46..ce527942717 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -200,9 +200,17 @@ const AppInputBar = React.memo(
       const textarea = textAreaRef.current;
       if (!wrapper || !textarea) return;
 
+      // Reset so scrollHeight reflects actual content size
       wrapper.style.height = `${MIN_INPUT_HEIGHT}px`;
+
+      // scrollHeight doesn't include the wrapper's padding, so add it back
+      const wrapperStyle = getComputedStyle(wrapper);
+      const paddingTop = parseFloat(wrapperStyle.paddingTop);
+      const paddingBottom = parseFloat(wrapperStyle.paddingBottom);
+      const contentHeight = textarea.scrollHeight + paddingTop + paddingBottom;
+
       wrapper.style.height = `${Math.min(
-        Math.max(textarea.scrollHeight, MIN_INPUT_HEIGHT),
+        Math.max(contentHeight, MIN_INPUT_HEIGHT),
         MAX_INPUT_HEIGHT
       )}px`;
     }, [message, isSearchMode]);

From 41fb1480bbf28a3fa33bea71ed4941ce781ddd77 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Fri, 6 Mar 2026 13:47:18 -0800
Subject: [PATCH 162/267] docs(cli): improve onyx-cli SKILL.md and fix README
 default server URL (#9152)

---
 .cursor/skills/onyx-cli/SKILL.md | 27 ++++++++++++++++++++++++++-
 cli/README.md                    |  2 +-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/.cursor/skills/onyx-cli/SKILL.md b/.cursor/skills/onyx-cli/SKILL.md
index bd5606284d4..da7132d3206 100644
--- a/.cursor/skills/onyx-cli/SKILL.md
+++ b/.cursor/skills/onyx-cli/SKILL.md
@@ -106,13 +106,34 @@ onyx-cli ask --json "What authentication methods do we support?"
 
 Outputs JSON-encoded parsed stream events (one object per line). Key event objects include message deltas, stop, errors, search-start, and citation payloads.
 
+Each line is a JSON object with this envelope:
+
+```json
+{"type": "<event_type>", "event": { ... }}
+```
+
 | Event Type | Description |
 |------------|-------------|
 | `message_delta` | Content token — concatenate all `content` fields for the full answer |
 | `stop` | Stream complete |
 | `error` | Error with `error` message field |
 | `search_tool_start` | Onyx started searching documents |
-| `citation_info` | Source citation with `citation_number` and `document_id` |
+| `citation_info` | Source citation — see shape below |
+
+`citation_info` event shape:
+
+```json
+{
+  "type": "citation_info",
+  "event": {
+    "citation_number": 1,
+    "document_id": "abc123def456",
+    "placement": {"turn_index": 0, "tab_index": 0, "sub_turn_index": null}
+  }
+}
+```
+
+`placement` is metadata about where in the conversation the citation appeared and can be ignored for most use cases.
 
 ### Specify an agent
 
@@ -129,6 +150,10 @@ Uses a specific Onyx agent/persona instead of the default.
 | `--agent-id` | int | Agent ID to use (overrides default) |
 | `--json` | bool | Output raw NDJSON events instead of plain text |
 
+## Statelessness
+
+Each `onyx-cli ask` call creates an independent chat session. There is no built-in way to chain context across multiple `ask` invocations — every call starts fresh. If you need multi-turn conversation with memory, use the interactive TUI (`onyx-cli` or `onyx-cli chat`) instead.
+
 ## When to Use
 
 Use `onyx-cli ask` when:
diff --git a/cli/README.md b/cli/README.md
index 1cd81cf1841..6601b284563 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -31,7 +31,7 @@ Environment variables override config file values:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `ONYX_SERVER_URL` | No | Server base URL (default: `http://localhost:3000`) |
+| `ONYX_SERVER_URL` | No | Server base URL (default: `https://cloud.onyx.app`) |
 | `ONYX_API_KEY` | Yes | API key for authentication |
 | `ONYX_PERSONA_ID` | No | Default agent/persona ID |
 

From e7cf027f8ac9fc7cd8148cdf5637ac5fb25c011d Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 13:53:57 -0800
Subject: [PATCH 163/267] chore(zizmor): fix rust-toolchain commit (#9153)

---
 .github/workflows/pr-desktop-build.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pr-desktop-build.yml b/.github/workflows/pr-desktop-build.yml
index 9bf0b3f3b96..64918081aef 100644
--- a/.github/workflows/pr-desktop-build.yml
+++ b/.github/workflows/pr-desktop-build.yml
@@ -57,7 +57,7 @@ jobs:
           cache-dependency-path: ./desktop/package-lock.json
 
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7
+        uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9
         with:
           toolchain: stable
           targets: ${{ matrix.target }}

From 6917953b86a7d5fe5fc9d6d50642517916b34a59 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Fri, 6 Mar 2026 14:08:14 -0800
Subject: [PATCH 164/267] chore(projects): Turn off DR in Projects (#9150)

---
 web/src/refresh-pages/AppPage.tsx      | 29 ++++++++++++++++++--------
 web/src/sections/input/AppInputBar.tsx |  8 ++++++-
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index e2d9ea1efb4..fecda858b29 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -193,7 +193,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       onSubmit({
         message,
         currentMessageFiles,
-        deepResearch: deepResearchEnabled,
+        deepResearch: deepResearchEnabledForCurrentWorkflow,
       });
     }
   }
@@ -218,6 +218,8 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     chatSessionId: currentChatSessionId,
     agentId: selectedAgent?.id,
   });
+  const deepResearchEnabledForCurrentWorkflow =
+    currentProjectId === null && deepResearchEnabled;
 
   const [presentingDocument, setPresentingDocument] =
     useState<MinimalOnyxDocument | null>(null);
@@ -435,10 +437,15 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     onSubmit({
       message: lastUserMsg.message,
       currentMessageFiles: currentMessageFiles,
-      deepResearch: deepResearchEnabled,
+      deepResearch: deepResearchEnabledForCurrentWorkflow,
       messageIdToResend: lastUserMsg.messageId,
     });
-  }, [messageHistory, onSubmit, currentMessageFiles, deepResearchEnabled]);
+  }, [
+    messageHistory,
+    onSubmit,
+    currentMessageFiles,
+    deepResearchEnabledForCurrentWorkflow,
+  ]);
 
   const toggleDocumentSidebar = useCallback(() => {
     if (!documentSidebarVisible) {
@@ -458,7 +465,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       onSubmit({
         message,
         currentMessageFiles,
-        deepResearch: deepResearchEnabled,
+        deepResearch: deepResearchEnabledForCurrentWorkflow,
       });
       if (showOnboarding || !onboardingDismissed) {
         finishOnboarding();
@@ -468,7 +475,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       resetInputBar,
       onSubmit,
       currentMessageFiles,
-      deepResearchEnabled,
+      deepResearchEnabledForCurrentWorkflow,
       showOnboarding,
       onboardingDismissed,
       finishOnboarding,
@@ -503,7 +510,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
         onSubmit({
           message,
           currentMessageFiles,
-          deepResearch: deepResearchEnabled,
+          deepResearch: deepResearchEnabledForCurrentWorkflow,
         });
         if (showOnboarding || !onboardingDismissed) {
           finishOnboarding();
@@ -524,7 +531,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       resetInputBar,
       onSubmit,
       currentMessageFiles,
-      deepResearchEnabled,
+      deepResearchEnabledForCurrentWorkflow,
       showOnboarding,
       onboardingDismissed,
       finishOnboarding,
@@ -732,7 +739,9 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                       <ChatUI
                         liveAgent={liveAgent!}
                         llmManager={llmManager}
-                        deepResearchEnabled={deepResearchEnabled}
+                        deepResearchEnabled={
+                          deepResearchEnabledForCurrentWorkflow
+                        }
                         currentMessageFiles={currentMessageFiles}
                         setPresentingDocument={setPresentingDocument}
                         onSubmit={onSubmit}
@@ -828,7 +837,9 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                       />
                       <AppInputBar
                         ref={chatInputBarRef}
-                        deepResearchEnabled={deepResearchEnabled}
+                        deepResearchEnabled={
+                          deepResearchEnabledForCurrentWorkflow
+                        }
                         toggleDeepResearch={toggleDeepResearch}
                         filterManager={filterManager}
                         llmManager={llmManager}
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index ce527942717..ec63ebedbe2 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -148,7 +148,7 @@ const AppInputBar = React.memo(
       classification === "search";
 
     const { forcedToolIds, setForcedToolIds } = useForcedTools();
-    const { currentMessageFiles, setCurrentMessageFiles } =
+    const { currentMessageFiles, setCurrentMessageFiles, currentProjectId } =
       useProjectsContext();
 
     const currentIndexingFiles = useMemo(() => {
@@ -366,13 +366,19 @@ const AppInputBar = React.memo(
     const showDeepResearch = useMemo(() => {
       const deepResearchGloballyEnabled =
         combinedSettings?.settings?.deep_research_enabled ?? true;
+      const isProjectWorkflow = currentProjectId !== null;
+
+      // TODO(@yuhong): Re-enable Deep Research in Projects workflow once it is fully supported.
+      // https://linear.app/onyx-app/issue/ENG-3818/re-enable-deep-research-in-projects
       return (
+        !isProjectWorkflow &&
         deepResearchGloballyEnabled &&
         hasSearchToolsAvailable(selectedAgent?.tools || [])
       );
     }, [
       selectedAgent?.tools,
       combinedSettings?.settings?.deep_research_enabled,
+      currentProjectId,
     ]);
 
     function handleKeyDownForPromptShortcuts(

From 48802618db6aa0ece2d1a9d82ebd0dace3b7c176 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 14:13:52 -0800
Subject: [PATCH 165/267] fix(fe): fix API Key Role dropdown options (#9154)

---
 web/src/app/admin/api-key/OnyxApiKeyForm.tsx | 37 ++++++++++----------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/web/src/app/admin/api-key/OnyxApiKeyForm.tsx b/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
index f11c15a7f92..427bca01887 100644
--- a/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
+++ b/web/src/app/admin/api-key/OnyxApiKeyForm.tsx
@@ -6,7 +6,7 @@ import { Button } from "@opal/components";
 import { Disabled } from "@opal/core";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
-import InputComboBox from "@/refresh-components/inputs/InputComboBox";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
 import { FormikField } from "@/refresh-components/form/FormikField";
 import { FormField } from "@/refresh-components/form/FormField";
 import { USER_ROLE_LABELS, UserRole } from "@/lib/types";
@@ -107,26 +107,25 @@ export default function OnyxApiKeyForm({
                     <FormField name="role" state={state} className="w-full">
                       <FormField.Label>Role:</FormField.Label>
                       <FormField.Control>
-                        <InputComboBox
+                        <InputSelect
                           value={field.value}
                           onValueChange={(value) => helper.setValue(value)}
-                          options={[
-                            {
-                              label: USER_ROLE_LABELS[UserRole.LIMITED],
-                              value: UserRole.LIMITED.toString(),
-                            },
-                            {
-                              label: USER_ROLE_LABELS[UserRole.BASIC],
-                              value: UserRole.BASIC.toString(),
-                            },
-                            {
-                              label: USER_ROLE_LABELS[UserRole.ADMIN],
-                              value: UserRole.ADMIN.toString(),
-                            },
-                          ]}
-                          placeholder="Select a role"
-                          strict
-                        />
+                        >
+                          <InputSelect.Trigger placeholder="Select a role" />
+                          <InputSelect.Content>
+                            <InputSelect.Item
+                              value={UserRole.LIMITED.toString()}
+                            >
+                              {USER_ROLE_LABELS[UserRole.LIMITED]}
+                            </InputSelect.Item>
+                            <InputSelect.Item value={UserRole.BASIC.toString()}>
+                              {USER_ROLE_LABELS[UserRole.BASIC]}
+                            </InputSelect.Item>
+                            <InputSelect.Item value={UserRole.ADMIN.toString()}>
+                              {USER_ROLE_LABELS[UserRole.ADMIN]}
+                            </InputSelect.Item>
+                          </InputSelect.Content>
+                        </InputSelect>
                       </FormField.Control>
                       <FormField.Description>
                         Select the role for this API key. Limited has access to

From cc008699e5315654037c03ff68b2c749528c4637 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 16:06:36 -0800
Subject: [PATCH 166/267] fix(a11y): InputSelect supports keyboard navigation
 (#9160)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 .../refresh-components/buttons/LineItem.tsx   | 21 +++++++++++++++++--
 .../refresh-components/inputs/InputSelect.tsx |  4 ++--
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/web/src/refresh-components/buttons/LineItem.tsx b/web/src/refresh-components/buttons/LineItem.tsx
index 30e38ed0eef..bfaa78c1d00 100644
--- a/web/src/refresh-components/buttons/LineItem.tsx
+++ b/web/src/refresh-components/buttons/LineItem.tsx
@@ -57,6 +57,12 @@ export interface LineItemProps
     WithoutStyles<React.HTMLAttributes<HTMLDivElement>>,
     "children"
   > {
+  /**
+   * Whether the row should behave like a standalone interactive button.
+   * Set to false when nested inside another interactive primitive
+   * (e.g. Radix Select.Item) to avoid nested focus targets.
+   */
+  interactive?: boolean;
   // line-item variants
   strikethrough?: boolean;
   danger?: boolean;
@@ -131,6 +137,7 @@ export interface LineItemProps
  * - The component automatically adds a `data-selected="true"` attribute for custom styling
  */
 export default function LineItem({
+  interactive = true,
   selected,
   strikethrough,
   danger,
@@ -164,6 +171,11 @@ export default function LineItem({
   const emphasisKey = emphasized ? "emphasized" : "normal";
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    if (!interactive) {
+      props.onKeyDown?.(e);
+      return;
+    }
+
     if (e.key === "Enter") {
       e.preventDefault();
       (e.currentTarget as HTMLDivElement).click();
@@ -174,6 +186,11 @@ export default function LineItem({
   };
 
   const handleKeyUp = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    if (!interactive) {
+      props.onKeyUp?.(e);
+      return;
+    }
+
     if (e.key === " ") {
       e.preventDefault();
       (e.currentTarget as HTMLDivElement).click();
@@ -184,8 +201,8 @@ export default function LineItem({
   const content = (
     <div
       ref={ref}
-      role="button"
-      tabIndex={0}
+      role={interactive ? "button" : undefined}
+      tabIndex={interactive ? 0 : undefined}
       className={cn(
         "flex flex-row w-full items-start p-2 rounded-08 group/LineItem gap-2",
         !!(children && description) ? "items-start" : "items-center",
diff --git a/web/src/refresh-components/inputs/InputSelect.tsx b/web/src/refresh-components/inputs/InputSelect.tsx
index abd245ac254..6c085b13e78 100644
--- a/web/src/refresh-components/inputs/InputSelect.tsx
+++ b/web/src/refresh-components/inputs/InputSelect.tsx
@@ -369,7 +369,7 @@ function InputSelectItem({
     <SelectPrimitive.Item
       ref={ref}
       value={value}
-      className="outline-none focus:outline-none"
+      className="outline-none focus:outline-none rounded-08 data-[highlighted]:bg-background-tint-02"
       onSelect={onClick}
     >
       {/* Hidden ItemText for Radix to track selection */}
@@ -383,7 +383,7 @@ function InputSelectItem({
         selected={isSelected}
         emphasized
         description={description}
-        onClick={noProp((event) => event.preventDefault())}
+        interactive={false}
       >
         {children}
       </LineItem>

From c2a71091dc6bda9650a1471141897fb04e71827b Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Fri, 6 Mar 2026 16:23:24 -0800
Subject: [PATCH 167/267] feat: jsonriver implementation w/ delta (#9161)

---
 backend/onyx/utils/jsonriver/__init__.py      |  17 +
 backend/onyx/utils/jsonriver/parse.py         | 427 +++++++++++++++
 backend/onyx/utils/jsonriver/tokenize.py      | 514 ++++++++++++++++++
 .../tests/unit/onyx/utils/test_json_river.py  | 394 ++++++++++++++
 4 files changed, 1352 insertions(+)
 create mode 100644 backend/onyx/utils/jsonriver/__init__.py
 create mode 100644 backend/onyx/utils/jsonriver/parse.py
 create mode 100644 backend/onyx/utils/jsonriver/tokenize.py
 create mode 100644 backend/tests/unit/onyx/utils/test_json_river.py

diff --git a/backend/onyx/utils/jsonriver/__init__.py b/backend/onyx/utils/jsonriver/__init__.py
new file mode 100644
index 00000000000..02acb52816f
--- /dev/null
+++ b/backend/onyx/utils/jsonriver/__init__.py
@@ -0,0 +1,17 @@
+"""
+jsonriver - A streaming JSON parser for Python
+
+Parse JSON incrementally as it streams in, e.g. from a network request or a language model.
+Gives you a sequence of increasingly complete values.
+
+Copyright (c) 2023 Google LLC (original TypeScript implementation)
+Copyright (c) 2024 jsonriver-python contributors (Python port)
+SPDX-License-Identifier: BSD-3-Clause
+"""
+
+from .parse import _Parser as Parser
+from .parse import JsonObject
+from .parse import JsonValue
+
+__all__ = ["Parser", "JsonValue", "JsonObject"]
+__version__ = "0.0.1"
diff --git a/backend/onyx/utils/jsonriver/parse.py b/backend/onyx/utils/jsonriver/parse.py
new file mode 100644
index 00000000000..ee65e79c69a
--- /dev/null
+++ b/backend/onyx/utils/jsonriver/parse.py
@@ -0,0 +1,427 @@
+"""
+JSON parser for streaming incremental parsing
+
+Copyright (c) 2023 Google LLC (original TypeScript implementation)
+Copyright (c) 2024 jsonriver-python contributors (Python port)
+SPDX-License-Identifier: BSD-3-Clause
+"""
+
+from __future__ import annotations
+
+import copy
+from enum import IntEnum
+from typing import cast
+from typing import Union
+
+from .tokenize import _Input
+from .tokenize import json_token_type_to_string
+from .tokenize import JsonTokenType
+from .tokenize import Tokenizer
+
+
+# Type definitions for JSON values
+JsonValue = Union[None, bool, float, str, list["JsonValue"], dict[str, "JsonValue"]]
+JsonObject = dict[str, JsonValue]
+
+
+class _StateEnum(IntEnum):
+    """Parser state machine states"""
+
+    Initial = 0
+    InString = 1
+    InArray = 2
+    InObjectExpectingKey = 3
+    InObjectExpectingValue = 4
+
+
+class _State:
+    """Base class for parser states"""
+
+    type: _StateEnum
+    value: JsonValue | tuple[str, JsonObject] | None
+
+
+class _InitialState(_State):
+    """Initial state before any parsing"""
+
+    def __init__(self) -> None:
+        self.type = _StateEnum.Initial
+        self.value = None
+
+
+class _InStringState(_State):
+    """State while parsing a string"""
+
+    def __init__(self) -> None:
+        self.type = _StateEnum.InString
+        self.value = ""
+
+
+class _InArrayState(_State):
+    """State while parsing an array"""
+
+    def __init__(self) -> None:
+        self.type = _StateEnum.InArray
+        self.value: list[JsonValue] = []
+
+
+class _InObjectExpectingKeyState(_State):
+    """State while parsing an object, expecting a key"""
+
+    def __init__(self) -> None:
+        self.type = _StateEnum.InObjectExpectingKey
+        self.value: JsonObject = {}
+
+
+class _InObjectExpectingValueState(_State):
+    """State while parsing an object, expecting a value"""
+
+    def __init__(self, key: str, obj: JsonObject) -> None:
+        self.type = _StateEnum.InObjectExpectingValue
+        self.value = (key, obj)
+
+
+# Sentinel value to distinguish "not set" from "set to None/null"
+class _Unset:
+    pass
+
+
+_UNSET = _Unset()
+
+
+class _Parser:
+    """
+    Incremental JSON parser
+
+    Feed chunks of JSON text via feed() and get back progressively
+    more complete JSON values.
+    """
+
+    def __init__(self) -> None:
+        self._state_stack: list[_State] = [_InitialState()]
+        self._toplevel_value: JsonValue | _Unset = _UNSET
+        self._input = _Input()
+        self.tokenizer = Tokenizer(self._input, self)
+        self._finished = False
+        self._progressed = False
+        self._prev_snapshot: JsonValue | _Unset = _UNSET
+
+    def feed(self, chunk: str) -> list[JsonValue]:
+        """
+        Feed a chunk of JSON text and return deltas from the previous state.
+
+        Each element in the returned list represents what changed since the
+        last yielded value. For dicts, only changed/new keys are included,
+        with string values containing only the newly appended characters.
+        """
+        if self._finished:
+            return []
+
+        self._input.feed(chunk)
+        return self._collect_deltas()
+
+    @staticmethod
+    def _compute_delta(prev: JsonValue | None, current: JsonValue) -> JsonValue | None:
+        if prev is None:
+            return current
+
+        if isinstance(current, dict) and isinstance(prev, dict):
+            result: JsonObject = {}
+            for key in current:
+                cur_val = current[key]
+                prev_val = prev.get(key)
+                if key not in prev:
+                    result[key] = cur_val
+                elif isinstance(cur_val, str) and isinstance(prev_val, str):
+                    if cur_val != prev_val:
+                        result[key] = cur_val[len(prev_val) :]
+                elif isinstance(cur_val, list) and isinstance(prev_val, list):
+                    if cur_val != prev_val:
+                        new_items = cur_val[len(prev_val) :]
+                        # check if the last existing element was updated
+                        if (
+                            prev_val
+                            and len(cur_val) >= len(prev_val)
+                            and cur_val[len(prev_val) - 1] != prev_val[-1]
+                        ):
+                            result[key] = [cur_val[len(prev_val) - 1]] + new_items
+                        elif new_items:
+                            result[key] = new_items
+                elif cur_val != prev_val:
+                    result[key] = cur_val
+            return result if result else None
+
+        if isinstance(current, str) and isinstance(prev, str):
+            delta = current[len(prev) :]
+            return delta if delta else None
+
+        if isinstance(current, list) and isinstance(prev, list):
+            if current != prev:
+                new_items = current[len(prev) :]
+                if (
+                    prev
+                    and len(current) >= len(prev)
+                    and current[len(prev) - 1] != prev[-1]
+                ):
+                    return [current[len(prev) - 1]] + new_items
+                return new_items if new_items else None
+            return None
+
+        if current != prev:
+            return current
+        return None
+
+    def finish(self) -> list[JsonValue]:
+        """Signal that no more chunks will be fed. Validates trailing content.
+
+        Returns any final deltas produced by flushing pending tokens (e.g.
+        numbers, which have no terminator and wait for more input).
+        """
+        self._input.mark_complete()
+        # Pump once more so the tokenizer can emit tokens that were waiting
+        # for more input (e.g. numbers need buffer_complete to finalize).
+        results = self._collect_deltas()
+        self._input.expect_end_of_content()
+        return results
+
+    def _collect_deltas(self) -> list[JsonValue]:
+        """Run one pump cycle and return any deltas produced."""
+        results: list[JsonValue] = []
+        while True:
+            self._progressed = False
+            self.tokenizer.pump()
+
+            if self._progressed:
+                if self._toplevel_value is _UNSET:
+                    raise RuntimeError(
+                        "Internal error: toplevel_value should not be unset "
+                        "after progressing"
+                    )
+                current = copy.deepcopy(cast(JsonValue, self._toplevel_value))
+                if isinstance(self._prev_snapshot, _Unset):
+                    results.append(current)
+                else:
+                    delta = self._compute_delta(self._prev_snapshot, current)
+                    if delta is not None:
+                        results.append(delta)
+                self._prev_snapshot = current
+            else:
+                if not self._state_stack:
+                    self._finished = True
+                break
+        return results
+
+    # TokenHandler protocol implementation
+
+    def handle_null(self) -> None:
+        """Handle null token"""
+        self._handle_value_token(JsonTokenType.Null, None)
+
+    def handle_boolean(self, value: bool) -> None:
+        """Handle boolean token"""
+        self._handle_value_token(JsonTokenType.Boolean, value)
+
+    def handle_number(self, value: float) -> None:
+        """Handle number token"""
+        self._handle_value_token(JsonTokenType.Number, value)
+
+    def handle_string_start(self) -> None:
+        """Handle string start token"""
+        state = self._current_state()
+        if not self._progressed and state.type != _StateEnum.InObjectExpectingKey:
+            self._progressed = True
+
+        if state.type == _StateEnum.Initial:
+            self._state_stack.pop()
+            self._toplevel_value = self._progress_value(JsonTokenType.StringStart, None)
+
+        elif state.type == _StateEnum.InArray:
+            v = self._progress_value(JsonTokenType.StringStart, None)
+            arr = cast(list[JsonValue], state.value)
+            arr.append(v)
+
+        elif state.type == _StateEnum.InObjectExpectingKey:
+            self._state_stack.append(_InStringState())
+
+        elif state.type == _StateEnum.InObjectExpectingValue:
+            key, obj = cast(tuple[str, JsonObject], state.value)
+            sv = self._progress_value(JsonTokenType.StringStart, None)
+            obj[key] = sv
+
+        elif state.type == _StateEnum.InString:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(JsonTokenType.StringStart)} "
+                f"token in the middle of string"
+            )
+
+    def handle_string_middle(self, value: str) -> None:
+        """Handle string middle token"""
+        state = self._current_state()
+
+        if not self._progressed:
+            if len(self._state_stack) >= 2:
+                prev = self._state_stack[-2]
+                if prev.type != _StateEnum.InObjectExpectingKey:
+                    self._progressed = True
+            else:
+                self._progressed = True
+
+        if state.type != _StateEnum.InString:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(JsonTokenType.StringMiddle)} "
+                f"token when not in string"
+            )
+
+        assert isinstance(state.value, str)
+        state.value += value
+
+        parent_state = self._state_stack[-2] if len(self._state_stack) >= 2 else None
+        self._update_string_parent(state.value, parent_state)
+
+    def handle_string_end(self) -> None:
+        """Handle string end token"""
+        state = self._current_state()
+
+        if state.type != _StateEnum.InString:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(JsonTokenType.StringEnd)} "
+                f"token when not in string"
+            )
+
+        self._state_stack.pop()
+        parent_state = self._state_stack[-1] if self._state_stack else None
+        assert isinstance(state.value, str)
+        self._update_string_parent(state.value, parent_state)
+
+    def handle_array_start(self) -> None:
+        """Handle array start token"""
+        self._handle_value_token(JsonTokenType.ArrayStart, None)
+
+    def handle_array_end(self) -> None:
+        """Handle array end token"""
+        state = self._current_state()
+        if state.type != _StateEnum.InArray:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(JsonTokenType.ArrayEnd)} token"
+            )
+        self._state_stack.pop()
+
+    def handle_object_start(self) -> None:
+        """Handle object start token"""
+        self._handle_value_token(JsonTokenType.ObjectStart, None)
+
+    def handle_object_end(self) -> None:
+        """Handle object end token"""
+        state = self._current_state()
+
+        if state.type in (
+            _StateEnum.InObjectExpectingKey,
+            _StateEnum.InObjectExpectingValue,
+        ):
+            self._state_stack.pop()
+        else:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(JsonTokenType.ObjectEnd)} token"
+            )
+
+    # Private helper methods
+
+    def _current_state(self) -> _State:
+        """Get current parser state"""
+        if not self._state_stack:
+            raise ValueError("Unexpected trailing input")
+        return self._state_stack[-1]
+
+    def _handle_value_token(self, token_type: JsonTokenType, value: JsonValue) -> None:
+        """Handle a complete value token"""
+        state = self._current_state()
+
+        if not self._progressed:
+            self._progressed = True
+
+        if state.type == _StateEnum.Initial:
+            self._state_stack.pop()
+            self._toplevel_value = self._progress_value(token_type, value)
+
+        elif state.type == _StateEnum.InArray:
+            v = self._progress_value(token_type, value)
+            arr = cast(list[JsonValue], state.value)
+            arr.append(v)
+
+        elif state.type == _StateEnum.InObjectExpectingValue:
+            key, obj = cast(tuple[str, JsonObject], state.value)
+            if token_type != JsonTokenType.StringStart:
+                self._state_stack.pop()
+                new_state = _InObjectExpectingKeyState()
+                new_state.value = obj
+                self._state_stack.append(new_state)
+
+            v = self._progress_value(token_type, value)
+            obj[key] = v
+
+        elif state.type == _StateEnum.InString:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(token_type)} "
+                f"token in the middle of string"
+            )
+
+        elif state.type == _StateEnum.InObjectExpectingKey:
+            raise ValueError(
+                f"Unexpected {json_token_type_to_string(token_type)} "
+                f"token in the middle of object expecting key"
+            )
+
+    def _update_string_parent(self, updated: str, parent_state: _State | None) -> None:
+        """Update parent container with updated string value"""
+        if parent_state is None:
+            self._toplevel_value = updated
+
+        elif parent_state.type == _StateEnum.InArray:
+            arr = cast(list[JsonValue], parent_state.value)
+            arr[-1] = updated
+
+        elif parent_state.type == _StateEnum.InObjectExpectingValue:
+            key, obj = cast(tuple[str, JsonObject], parent_state.value)
+            obj[key] = updated
+            if self._state_stack and self._state_stack[-1] == parent_state:
+                self._state_stack.pop()
+                new_state = _InObjectExpectingKeyState()
+                new_state.value = obj
+                self._state_stack.append(new_state)
+
+        elif parent_state.type == _StateEnum.InObjectExpectingKey:
+            if self._state_stack and self._state_stack[-1] == parent_state:
+                self._state_stack.pop()
+                obj = cast(JsonObject, parent_state.value)
+                self._state_stack.append(_InObjectExpectingValueState(updated, obj))
+
+    def _progress_value(self, token_type: JsonTokenType, value: JsonValue) -> JsonValue:
+        """Create initial value for a token and push appropriate state"""
+        if token_type == JsonTokenType.Null:
+            return None
+
+        elif token_type == JsonTokenType.Boolean:
+            return value
+
+        elif token_type == JsonTokenType.Number:
+            return value
+
+        elif token_type == JsonTokenType.StringStart:
+            string_state = _InStringState()
+            self._state_stack.append(string_state)
+            return ""
+
+        elif token_type == JsonTokenType.ArrayStart:
+            array_state = _InArrayState()
+            self._state_stack.append(array_state)
+            return array_state.value
+
+        elif token_type == JsonTokenType.ObjectStart:
+            object_state = _InObjectExpectingKeyState()
+            self._state_stack.append(object_state)
+            return object_state.value
+
+        else:
+            raise ValueError(
+                f"Unexpected token type: {json_token_type_to_string(token_type)}"
+            )
diff --git a/backend/onyx/utils/jsonriver/tokenize.py b/backend/onyx/utils/jsonriver/tokenize.py
new file mode 100644
index 00000000000..fec2fe7ddde
--- /dev/null
+++ b/backend/onyx/utils/jsonriver/tokenize.py
@@ -0,0 +1,514 @@
+"""
+JSON tokenizer for streaming incremental parsing
+
+Copyright (c) 2023 Google LLC (original TypeScript implementation)
+Copyright (c) 2024 jsonriver-python contributors (Python port)
+SPDX-License-Identifier: BSD-3-Clause
+"""
+
+from __future__ import annotations
+
+import re
+from enum import IntEnum
+from typing import Protocol
+
+
+class TokenHandler(Protocol):
+    """Protocol for handling JSON tokens"""
+
+    def handle_null(self) -> None: ...
+    def handle_boolean(self, value: bool) -> None: ...
+    def handle_number(self, value: float) -> None: ...
+    def handle_string_start(self) -> None: ...
+    def handle_string_middle(self, value: str) -> None: ...
+    def handle_string_end(self) -> None: ...
+    def handle_array_start(self) -> None: ...
+    def handle_array_end(self) -> None: ...
+    def handle_object_start(self) -> None: ...
+    def handle_object_end(self) -> None: ...
+
+
+class JsonTokenType(IntEnum):
+    """Types of JSON tokens"""
+
+    Null = 0
+    Boolean = 1
+    Number = 2
+    StringStart = 3
+    StringMiddle = 4
+    StringEnd = 5
+    ArrayStart = 6
+    ArrayEnd = 7
+    ObjectStart = 8
+    ObjectEnd = 9
+
+
+def json_token_type_to_string(token_type: JsonTokenType) -> str:
+    """Convert token type to readable string"""
+    names = {
+        JsonTokenType.Null: "null",
+        JsonTokenType.Boolean: "boolean",
+        JsonTokenType.Number: "number",
+        JsonTokenType.StringStart: "string start",
+        JsonTokenType.StringMiddle: "string middle",
+        JsonTokenType.StringEnd: "string end",
+        JsonTokenType.ArrayStart: "array start",
+        JsonTokenType.ArrayEnd: "array end",
+        JsonTokenType.ObjectStart: "object start",
+        JsonTokenType.ObjectEnd: "object end",
+    }
+    return names[token_type]
+
+
+class _State(IntEnum):
+    """Internal tokenizer states"""
+
+    ExpectingValue = 0
+    InString = 1
+    StartArray = 2
+    AfterArrayValue = 3
+    StartObject = 4
+    AfterObjectKey = 5
+    AfterObjectValue = 6
+    BeforeObjectKey = 7
+
+
+# Regex for validating JSON numbers
+_JSON_NUMBER_PATTERN = re.compile(r"^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$")
+
+
+def _parse_json_number(s: str) -> float:
+    """Parse a JSON number string, validating format"""
+    if not _JSON_NUMBER_PATTERN.match(s):
+        raise ValueError("Invalid number")
+    return float(s)
+
+
+class _Input:
+    """
+    Input buffer for chunk-based JSON parsing
+
+    Manages buffering of input chunks and provides methods for
+    consuming and inspecting the buffer.
+    """
+
+    def __init__(self) -> None:
+        self._buffer = ""
+        self._start_index = 0
+        self.buffer_complete = False
+
+    def feed(self, chunk: str) -> None:
+        """Add a chunk of data to the buffer"""
+        self._buffer += chunk
+
+    def mark_complete(self) -> None:
+        """Signal that no more chunks will be fed"""
+        self.buffer_complete = True
+
+    @property
+    def length(self) -> int:
+        """Number of characters remaining in buffer"""
+        return len(self._buffer) - self._start_index
+
+    def advance(self, length: int) -> None:
+        """Advance the start position by length characters"""
+        self._start_index += length
+
+    def peek(self, offset: int) -> str | None:
+        """Peek at character at offset, or None if not available"""
+        idx = self._start_index + offset
+        if idx < len(self._buffer):
+            return self._buffer[idx]
+        return None
+
+    def peek_char_code(self, offset: int) -> int:
+        """Get character code at offset"""
+        return ord(self._buffer[self._start_index + offset])
+
+    def slice(self, start: int, end: int) -> str:
+        """Slice buffer from start to end (relative to current position)"""
+        return self._buffer[self._start_index + start : self._start_index + end]
+
+    def commit(self) -> None:
+        """Commit consumed content, removing it from buffer"""
+        if self._start_index > 0:
+            self._buffer = self._buffer[self._start_index :]
+            self._start_index = 0
+
+    def remaining(self) -> str:
+        """Get all remaining content in buffer"""
+        return self._buffer[self._start_index :]
+
+    def expect_end_of_content(self) -> None:
+        """Verify no non-whitespace content remains"""
+        self.commit()
+        self.skip_past_whitespace()
+        if self.length != 0:
+            raise ValueError(f"Unexpected trailing content {self.remaining()!r}")
+
+    def skip_past_whitespace(self) -> None:
+        """Skip whitespace characters"""
+        i = self._start_index
+        while i < len(self._buffer):
+            c = ord(self._buffer[i])
+            if c in (32, 9, 10, 13):  # space, tab, \n, \r
+                i += 1
+            else:
+                break
+        self._start_index = i
+
+    def try_to_take_prefix(self, prefix: str) -> bool:
+        """Try to consume prefix from buffer, return True if successful"""
+        if self._buffer.startswith(prefix, self._start_index):
+            self._start_index += len(prefix)
+            return True
+        return False
+
+    def try_to_take(self, length: int) -> str | None:
+        """Try to take length characters, or None if not enough available"""
+        if self.length < length:
+            return None
+        result = self._buffer[self._start_index : self._start_index + length]
+        self._start_index += length
+        return result
+
+    def try_to_take_char_code(self) -> int | None:
+        """Try to take a single character as char code, or None if buffer empty"""
+        if self.length == 0:
+            return None
+        code = ord(self._buffer[self._start_index])
+        self._start_index += 1
+        return code
+
+    def take_until_quote_or_backslash(self) -> tuple[str, bool]:
+        """
+        Consume input up to first quote or backslash
+
+        Returns tuple of (consumed_content, pattern_found)
+        """
+        buf = self._buffer
+        i = self._start_index
+        while i < len(buf):
+            c = ord(buf[i])
+            if c <= 0x1F:
+                raise ValueError("Unescaped control character in string")
+            if c == 34 or c == 92:  # " or \
+                result = buf[self._start_index : i]
+                self._start_index = i
+                return (result, True)
+            i += 1
+
+        result = buf[self._start_index :]
+        self._start_index = len(buf)
+        return (result, False)
+
+
+class Tokenizer:
+    """
+    Tokenizer for chunk-based JSON parsing
+
+    Processes chunks fed into its input buffer and calls handler methods
+    as JSON tokens are recognized.
+    """
+
+    def __init__(self, input: _Input, handler: TokenHandler) -> None:
+        self.input = input
+        self._handler = handler
+        self._stack: list[_State] = [_State.ExpectingValue]
+        self._emitted_tokens = 0
+
+    def is_done(self) -> bool:
+        """Check if tokenization is complete"""
+        return len(self._stack) == 0 and self.input.length == 0
+
+    def pump(self) -> None:
+        """Process all available tokens in the buffer"""
+        while True:
+            before = self._emitted_tokens
+            self._tokenize_more()
+            if self._emitted_tokens == before:
+                self.input.commit()
+                return
+
+    def _tokenize_more(self) -> None:
+        """Process one step of tokenization based on current state"""
+        if not self._stack:
+            return
+
+        state = self._stack[-1]
+
+        if state == _State.ExpectingValue:
+            self._tokenize_value()
+        elif state == _State.InString:
+            self._tokenize_string()
+        elif state == _State.StartArray:
+            self._tokenize_array_start()
+        elif state == _State.AfterArrayValue:
+            self._tokenize_after_array_value()
+        elif state == _State.StartObject:
+            self._tokenize_object_start()
+        elif state == _State.AfterObjectKey:
+            self._tokenize_after_object_key()
+        elif state == _State.AfterObjectValue:
+            self._tokenize_after_object_value()
+        elif state == _State.BeforeObjectKey:
+            self._tokenize_before_object_key()
+
+    def _tokenize_value(self) -> None:
+        """Tokenize a JSON value"""
+        self.input.skip_past_whitespace()
+
+        if self.input.try_to_take_prefix("null"):
+            self._handler.handle_null()
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+
+        if self.input.try_to_take_prefix("true"):
+            self._handler.handle_boolean(True)
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+
+        if self.input.try_to_take_prefix("false"):
+            self._handler.handle_boolean(False)
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+
+        if self.input.length > 0:
+            ch = self.input.peek_char_code(0)
+            if (48 <= ch <= 57) or ch == 45:  # 0-9 or -
+                # Scan for end of number
+                i = 0
+                while i < self.input.length:
+                    c = self.input.peek_char_code(i)
+                    if (48 <= c <= 57) or c in (45, 43, 46, 101, 69):  # 0-9 - + . e E
+                        i += 1
+                    else:
+                        break
+
+                if i == self.input.length and not self.input.buffer_complete:
+                    # Need more input (numbers have no terminator)
+                    return
+
+                number_chars = self.input.slice(0, i)
+                self.input.advance(i)
+                number = _parse_json_number(number_chars)
+                self._handler.handle_number(number)
+                self._emitted_tokens += 1
+                self._stack.pop()
+                return
+
+        if self.input.try_to_take_prefix('"'):
+            self._stack.pop()
+            self._stack.append(_State.InString)
+            self._handler.handle_string_start()
+            self._emitted_tokens += 1
+            self._tokenize_string()
+            return
+
+        if self.input.try_to_take_prefix("["):
+            self._stack.pop()
+            self._stack.append(_State.StartArray)
+            self._handler.handle_array_start()
+            self._emitted_tokens += 1
+            self._tokenize_array_start()
+            return
+
+        if self.input.try_to_take_prefix("{"):
+            self._stack.pop()
+            self._stack.append(_State.StartObject)
+            self._handler.handle_object_start()
+            self._emitted_tokens += 1
+            self._tokenize_object_start()
+            return
+
+    def _tokenize_string(self) -> None:
+        """Tokenize string content"""
+        while True:
+            chunk, interrupted = self.input.take_until_quote_or_backslash()
+            if chunk:
+                self._handler.handle_string_middle(chunk)
+                self._emitted_tokens += 1
+            elif not interrupted:
+                return
+
+            if interrupted:
+                if self.input.length == 0:
+                    return
+
+                next_char = self.input.peek(0)
+                if next_char == '"':
+                    self.input.advance(1)
+                    self._handler.handle_string_end()
+                    self._emitted_tokens += 1
+                    self._stack.pop()
+                    return
+
+                # Handle escape sequences
+                next_char2 = self.input.peek(1)
+                if next_char2 is None:
+                    return
+
+                value: str
+                if next_char2 == "u":
+                    # Unicode escape: need 4 hex digits
+                    if self.input.length < 6:
+                        return
+
+                    code = 0
+                    for j in range(2, 6):
+                        c = self.input.peek_char_code(j)
+                        if 48 <= c <= 57:  # 0-9
+                            digit = c - 48
+                        elif 65 <= c <= 70:  # A-F
+                            digit = c - 55
+                        elif 97 <= c <= 102:  # a-f
+                            digit = c - 87
+                        else:
+                            raise ValueError("Bad Unicode escape in JSON")
+                        code = (code << 4) | digit
+
+                    self.input.advance(6)
+                    self._handler.handle_string_middle(chr(code))
+                    self._emitted_tokens += 1
+                    continue
+
+                elif next_char2 == "n":
+                    value = "\n"
+                elif next_char2 == "r":
+                    value = "\r"
+                elif next_char2 == "t":
+                    value = "\t"
+                elif next_char2 == "b":
+                    value = "\b"
+                elif next_char2 == "f":
+                    value = "\f"
+                elif next_char2 == "\\":
+                    value = "\\"
+                elif next_char2 == "/":
+                    value = "/"
+                elif next_char2 == '"':
+                    value = '"'
+                else:
+                    raise ValueError("Bad escape in string")
+
+                self.input.advance(2)
+                self._handler.handle_string_middle(value)
+                self._emitted_tokens += 1
+
+    def _tokenize_array_start(self) -> None:
+        """Tokenize start of array (check for empty or first element)"""
+        self.input.skip_past_whitespace()
+        if self.input.length == 0:
+            return
+
+        if self.input.try_to_take_prefix("]"):
+            self._handler.handle_array_end()
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+
+        self._stack.pop()
+        self._stack.append(_State.AfterArrayValue)
+        self._stack.append(_State.ExpectingValue)
+        self._tokenize_value()
+
+    def _tokenize_after_array_value(self) -> None:
+        """Tokenize after an array value (expect , or ])"""
+        self.input.skip_past_whitespace()
+        next_char = self.input.try_to_take_char_code()
+
+        if next_char is None:
+            return
+        elif next_char == 0x5D:  # ]
+            self._handler.handle_array_end()
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+        elif next_char == 0x2C:  # ,
+            self._stack.append(_State.ExpectingValue)
+            self._tokenize_value()
+            return
+        else:
+            raise ValueError(f"Expected , or ], got {chr(next_char)!r}")
+
+    def _tokenize_object_start(self) -> None:
+        """Tokenize start of object (check for empty or first key)"""
+        self.input.skip_past_whitespace()
+        next_char = self.input.try_to_take_char_code()
+
+        if next_char is None:
+            return
+        elif next_char == 0x7D:  # }
+            self._handler.handle_object_end()
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+        elif next_char == 0x22:  # "
+            self._stack.pop()
+            self._stack.append(_State.AfterObjectKey)
+            self._stack.append(_State.InString)
+            self._handler.handle_string_start()
+            self._emitted_tokens += 1
+            self._tokenize_string()
+            return
+        else:
+            raise ValueError(f"Expected start of object key, got {chr(next_char)!r}")
+
+    def _tokenize_after_object_key(self) -> None:
+        """Tokenize after object key (expect :)"""
+        self.input.skip_past_whitespace()
+        next_char = self.input.try_to_take_char_code()
+
+        if next_char is None:
+            return
+        elif next_char == 0x3A:  # :
+            self._stack.pop()
+            self._stack.append(_State.AfterObjectValue)
+            self._stack.append(_State.ExpectingValue)
+            self._tokenize_value()
+            return
+        else:
+            raise ValueError(f"Expected colon after object key, got {chr(next_char)!r}")
+
+    def _tokenize_after_object_value(self) -> None:
+        """Tokenize after object value (expect , or })"""
+        self.input.skip_past_whitespace()
+        next_char = self.input.try_to_take_char_code()
+
+        if next_char is None:
+            return
+        elif next_char == 0x7D:  # }
+            self._handler.handle_object_end()
+            self._emitted_tokens += 1
+            self._stack.pop()
+            return
+        elif next_char == 0x2C:  # ,
+            self._stack.pop()
+            self._stack.append(_State.BeforeObjectKey)
+            self._tokenize_before_object_key()
+            return
+        else:
+            raise ValueError(
+                f"Expected , or }} after object value, got {chr(next_char)!r}"
+            )
+
+    def _tokenize_before_object_key(self) -> None:
+        """Tokenize before object key (after comma)"""
+        self.input.skip_past_whitespace()
+        next_char = self.input.try_to_take_char_code()
+
+        if next_char is None:
+            return
+        elif next_char == 0x22:  # "
+            self._stack.pop()
+            self._stack.append(_State.AfterObjectKey)
+            self._stack.append(_State.InString)
+            self._handler.handle_string_start()
+            self._emitted_tokens += 1
+            self._tokenize_string()
+            return
+        else:
+            raise ValueError(f"Expected start of object key, got {chr(next_char)!r}")
diff --git a/backend/tests/unit/onyx/utils/test_json_river.py b/backend/tests/unit/onyx/utils/test_json_river.py
new file mode 100644
index 00000000000..d4db746a461
--- /dev/null
+++ b/backend/tests/unit/onyx/utils/test_json_river.py
@@ -0,0 +1,394 @@
+"""Tests for the jsonriver incremental JSON parser."""
+
+import json
+
+import pytest
+
+from onyx.utils.jsonriver import JsonValue
+from onyx.utils.jsonriver import Parser
+
+
+def _all_deltas(chunks: list[str]) -> list[JsonValue]:
+    """Feed chunks one at a time and collect all emitted deltas."""
+    parser = Parser()
+    deltas: list[JsonValue] = []
+    for chunk in chunks:
+        deltas.extend(parser.feed(chunk))
+    deltas.extend(parser.finish())
+    return deltas
+
+
+class TestParseComplete:
+    """Parsing complete JSON in a single chunk."""
+
+    def test_simple_object(self) -> None:
+        deltas = _all_deltas(['{"a": 1}'])
+        assert any(r == {"a": 1.0} or r == {"a": 1} for r in deltas)
+
+    def test_simple_array(self) -> None:
+        deltas = _all_deltas(["[1, 2, 3]"])
+        assert any(isinstance(r, list) for r in deltas)
+
+    def test_simple_string(self) -> None:
+        deltas = _all_deltas(['"hello"'])
+        assert "hello" in deltas or any("hello" in str(r) for r in deltas)
+
+    def test_null(self) -> None:
+        deltas = _all_deltas(["null"])
+        assert None in deltas
+
+    def test_boolean_true(self) -> None:
+        deltas = _all_deltas(["true"])
+        assert True in deltas
+
+    def test_boolean_false(self) -> None:
+        deltas = _all_deltas(["false"])
+        assert any(r is False for r in deltas)
+
+    def test_number(self) -> None:
+        deltas = _all_deltas(["42"])
+        assert 42.0 in deltas
+
+    def test_negative_number(self) -> None:
+        deltas = _all_deltas(["-3.14"])
+        assert any(abs(r - (-3.14)) < 1e-10 for r in deltas if isinstance(r, float))
+
+    def test_empty_object(self) -> None:
+        deltas = _all_deltas(["{}"])
+        assert {} in deltas
+
+    def test_empty_array(self) -> None:
+        deltas = _all_deltas(["[]"])
+        assert [] in deltas
+
+
+class TestStreamingDeltas:
+    """Incremental feeding produces correct deltas."""
+
+    def test_object_string_value_streamed_char_by_char(self) -> None:
+        chunks = list('{"code": "abc"}')
+        deltas = _all_deltas(chunks)
+        str_parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "code" in d:
+                val = d["code"]
+                if isinstance(val, str):
+                    str_parts.append(val)
+        assert "".join(str_parts) == "abc"
+
+    def test_object_streamed_in_two_halves(self) -> None:
+        deltas = _all_deltas(['{"name": "Al', 'ice"}'])
+        str_parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "name" in d:
+                val = d["name"]
+                if isinstance(val, str):
+                    str_parts.append(val)
+        assert "".join(str_parts) == "Alice"
+
+    def test_multiple_keys_streamed(self) -> None:
+        deltas = _all_deltas(['{"a": "x', '", "b": "y"}'])
+        a_parts: list[str] = []
+        b_parts: list[str] = []
+        for d in deltas:
+            if isinstance(d, dict):
+                if "a" in d and isinstance(d["a"], str):
+                    a_parts.append(d["a"])
+                if "b" in d and isinstance(d["b"], str):
+                    b_parts.append(d["b"])
+        assert "".join(a_parts) == "x"
+        assert "".join(b_parts) == "y"
+
+    def test_deltas_only_contain_new_string_content(self) -> None:
+        parser = Parser()
+        d1 = parser.feed('{"msg": "hel')
+        d2 = parser.feed('lo"}')
+        parser.finish()
+
+        msg_parts = []
+        for d in d1 + d2:
+            if isinstance(d, dict) and "msg" in d:
+                val = d["msg"]
+                if isinstance(val, str):
+                    msg_parts.append(val)
+        assert "".join(msg_parts) == "hello"
+
+        # Each delta should only contain new chars, not repeat previous ones
+        if len(msg_parts) == 2:
+            assert msg_parts[0] == "hel"
+            assert msg_parts[1] == "lo"
+
+
+class TestEscapeSequences:
+    """JSON escape sequences are decoded correctly, even across chunk boundaries."""
+
+    def test_newline_escape(self) -> None:
+        deltas = _all_deltas(['{"text": "line1\\nline2"}'])
+        text_parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "text" in d and isinstance(d["text"], str):
+                text_parts.append(d["text"])
+        assert "".join(text_parts) == "line1\nline2"
+
+    def test_tab_escape(self) -> None:
+        deltas = _all_deltas(['{"t": "a\\tb"}'])
+        parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "t" in d and isinstance(d["t"], str):
+                parts.append(d["t"])
+        assert "".join(parts) == "a\tb"
+
+    def test_escaped_quote(self) -> None:
+        deltas = _all_deltas(['{"q": "say \\"hi\\""}'])
+        parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "q" in d and isinstance(d["q"], str):
+                parts.append(d["q"])
+        assert "".join(parts) == 'say "hi"'
+
+    def test_unicode_escape(self) -> None:
+        deltas = _all_deltas(['{"u": "\\u0041\\u0042"}'])
+        parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "u" in d and isinstance(d["u"], str):
+                parts.append(d["u"])
+        assert "".join(parts) == "AB"
+
+    def test_escape_split_across_chunks(self) -> None:
+        deltas = _all_deltas(['{"x": "a\\', 'nb"}'])
+        parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "x" in d and isinstance(d["x"], str):
+                parts.append(d["x"])
+        assert "".join(parts) == "a\nb"
+
+    def test_unicode_escape_split_across_chunks(self) -> None:
+        deltas = _all_deltas(['{"u": "\\u00', '41"}'])
+        parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "u" in d and isinstance(d["u"], str):
+                parts.append(d["u"])
+        assert "".join(parts) == "A"
+
+    def test_backslash_escape(self) -> None:
+        deltas = _all_deltas(['{"p": "c:\\\\dir"}'])
+        parts = []
+        for d in deltas:
+            if isinstance(d, dict) and "p" in d and isinstance(d["p"], str):
+                parts.append(d["p"])
+        assert "".join(parts) == "c:\\dir"
+
+
+class TestNestedStructures:
+    """Nested objects and arrays produce correct deltas."""
+
+    def test_nested_object(self) -> None:
+        deltas = _all_deltas(['{"outer": {"inner": "val"}}'])
+        found = False
+        for d in deltas:
+            if isinstance(d, dict) and "outer" in d:
+                outer = d["outer"]
+                if isinstance(outer, dict) and "inner" in outer:
+                    found = True
+        assert found
+
+    def test_array_of_strings(self) -> None:
+        deltas = _all_deltas(['["a', '", "b"]'])
+        all_items: list[str] = []
+        for d in deltas:
+            if isinstance(d, list):
+                for item in d:
+                    if isinstance(item, str):
+                        all_items.append(item)
+            elif isinstance(d, str):
+                all_items.append(d)
+        joined = "".join(all_items)
+        assert "a" in joined
+        assert "b" in joined
+
+    def test_object_with_number_and_bool(self) -> None:
+        deltas = _all_deltas(['{"count": 42, "active": true}'])
+        has_count = False
+        has_active = False
+        for d in deltas:
+            if isinstance(d, dict):
+                if "count" in d and d["count"] == 42.0:
+                    has_count = True
+                if "active" in d and d["active"] is True:
+                    has_active = True
+        assert has_count
+        assert has_active
+
+    def test_object_with_null_value(self) -> None:
+        deltas = _all_deltas(['{"key": null}'])
+        found = False
+        for d in deltas:
+            if isinstance(d, dict) and "key" in d and d["key"] is None:
+                found = True
+        assert found
+
+
+class TestComputeDelta:
+    """Direct tests for the _compute_delta static method."""
+
+    def test_none_prev_returns_current(self) -> None:
+        assert Parser._compute_delta(None, {"a": "b"}) == {"a": "b"}
+
+    def test_string_delta(self) -> None:
+        assert Parser._compute_delta("hel", "hello") == "lo"
+
+    def test_string_no_change(self) -> None:
+        assert Parser._compute_delta("same", "same") is None
+
+    def test_dict_new_key(self) -> None:
+        assert Parser._compute_delta({"a": "x"}, {"a": "x", "b": "y"}) == {"b": "y"}
+
+    def test_dict_string_append(self) -> None:
+        assert Parser._compute_delta({"code": "def"}, {"code": "def hello()"}) == {
+            "code": " hello()"
+        }
+
+    def test_dict_no_change(self) -> None:
+        assert Parser._compute_delta({"a": 1}, {"a": 1}) is None
+
+    def test_list_new_items(self) -> None:
+        assert Parser._compute_delta([1, 2], [1, 2, 3]) == [3]
+
+    def test_list_last_item_updated(self) -> None:
+        assert Parser._compute_delta(["a"], ["ab"]) == ["ab"]
+
+    def test_list_no_change(self) -> None:
+        assert Parser._compute_delta([1, 2], [1, 2]) is None
+
+    def test_primitive_change(self) -> None:
+        assert Parser._compute_delta(1, 2) == 2
+
+    def test_primitive_no_change(self) -> None:
+        assert Parser._compute_delta(42, 42) is None
+
+
+class TestParserLifecycle:
+    """Edge cases around parser state and lifecycle."""
+
+    def test_feed_after_finish_returns_empty(self) -> None:
+        parser = Parser()
+        parser.feed('{"a": 1}')
+        parser.finish()
+        assert parser.feed("more") == []
+
+    def test_empty_feed_returns_empty(self) -> None:
+        parser = Parser()
+        assert parser.feed("") == []
+
+    def test_whitespace_only_returns_empty(self) -> None:
+        parser = Parser()
+        assert parser.feed("   ") == []
+
+    def test_finish_with_trailing_whitespace(self) -> None:
+        parser = Parser()
+        # Trailing whitespace terminates the number, so feed() emits it
+        deltas = parser.feed("42  ")
+        assert 42.0 in deltas
+        parser.finish()  # Should not raise
+
+    def test_finish_with_trailing_content_raises(self) -> None:
+        parser = Parser()
+        # Feed a complete JSON value followed by non-whitespace in one chunk
+        parser.feed('{"a": 1} extra')
+        with pytest.raises(ValueError, match="Unexpected trailing"):
+            parser.finish()
+
+    def test_finish_flushes_pending_number(self) -> None:
+        parser = Parser()
+        deltas = parser.feed("42")
+        # Number has no terminator, so feed() can't emit it yet
+        assert deltas == []
+        final = parser.finish()
+        assert 42.0 in final
+
+
+class TestToolCallSimulation:
+    """Simulate the LLM tool-call streaming use case."""
+
+    def test_python_tool_call_streaming(self) -> None:
+        full_json = json.dumps({"code": "print('hello world')"})
+        chunk_size = 5
+        chunks = [
+            full_json[i : i + chunk_size] for i in range(0, len(full_json), chunk_size)
+        ]
+
+        parser = Parser()
+        code_parts: list[str] = []
+        for chunk in chunks:
+            for delta in parser.feed(chunk):
+                if isinstance(delta, dict) and "code" in delta:
+                    val = delta["code"]
+                    if isinstance(val, str):
+                        code_parts.append(val)
+        for delta in parser.finish():
+            if isinstance(delta, dict) and "code" in delta:
+                val = delta["code"]
+                if isinstance(val, str):
+                    code_parts.append(val)
+        assert "".join(code_parts) == "print('hello world')"
+
+    def test_multi_arg_tool_call(self) -> None:
+        full = '{"query": "search term", "num_results": 5}'
+        chunks = [full[:15], full[15:30], full[30:]]
+
+        parser = Parser()
+        query_parts: list[str] = []
+        has_num_results = False
+        for chunk in chunks:
+            for delta in parser.feed(chunk):
+                if isinstance(delta, dict):
+                    if "query" in delta and isinstance(delta["query"], str):
+                        query_parts.append(delta["query"])
+                    if "num_results" in delta:
+                        has_num_results = True
+        for delta in parser.finish():
+            if isinstance(delta, dict):
+                if "query" in delta and isinstance(delta["query"], str):
+                    query_parts.append(delta["query"])
+                if "num_results" in delta:
+                    has_num_results = True
+        assert "".join(query_parts) == "search term"
+        assert has_num_results
+
+    def test_code_with_newlines_and_escapes(self) -> None:
+        code = 'def greet(name):\n    print(f"Hello, {name}!")\n    return True'
+        full = json.dumps({"code": code})
+        chunk_size = 8
+        chunks = [full[i : i + chunk_size] for i in range(0, len(full), chunk_size)]
+
+        parser = Parser()
+        code_parts: list[str] = []
+        for chunk in chunks:
+            for delta in parser.feed(chunk):
+                if isinstance(delta, dict) and "code" in delta:
+                    val = delta["code"]
+                    if isinstance(val, str):
+                        code_parts.append(val)
+        for delta in parser.finish():
+            if isinstance(delta, dict) and "code" in delta:
+                val = delta["code"]
+                if isinstance(val, str):
+                    code_parts.append(val)
+        assert "".join(code_parts) == code
+
+    def test_single_char_streaming(self) -> None:
+        full = '{"key": "value"}'
+        parser = Parser()
+        key_parts: list[str] = []
+        for ch in full:
+            for delta in parser.feed(ch):
+                if isinstance(delta, dict) and "key" in delta:
+                    val = delta["key"]
+                    if isinstance(val, str):
+                        key_parts.append(val)
+        for delta in parser.finish():
+            if isinstance(delta, dict) and "key" in delta:
+                val = delta["key"]
+                if isinstance(val, str):
+                    key_parts.append(val)
+        assert "".join(key_parts) == "value"

From 1611604269e56917b76804f0fff1515c5bfa489c Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Fri, 6 Mar 2026 17:55:38 -0800
Subject: [PATCH 168/267] chore(tests): add shared enable_ee fixture and test
 README (#9165)

---
 AGENTS.md                                     |  2 +
 backend/onyx/utils/variable_functionality.py  |  3 +
 backend/tests/README.md                       | 71 +++++++++++++++++++
 backend/tests/conftest.py                     | 24 +++++++
 .../test_confluence_permissions_basic.py      |  4 +-
 backend/tests/daily/connectors/conftest.py    | 13 ----
 .../google_drive/test_drive_perm_sync.py      |  2 +-
 .../connectors/slack/test_slack_perm_sync.py  | 13 +---
 .../connectors/teams/test_teams_connector.py  | 13 +---
 .../connectors/jira/test_jira_doc_sync.py     | 10 +--
 .../connectors/jira/test_jira_group_sync.py   |  3 +
 backend/tests/unit/ee/conftest.py             |  8 +++
 .../jira/test_jira_permission_sync.py         |  2 +
 13 files changed, 121 insertions(+), 47 deletions(-)
 create mode 100644 backend/tests/README.md
 create mode 100644 backend/tests/conftest.py
 create mode 100644 backend/tests/unit/ee/conftest.py

diff --git a/AGENTS.md b/AGENTS.md
index bfabe9c991f..633e9615a3b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -544,6 +544,8 @@ To run them:
 npx playwright test <TEST_NAME>
 ```
 
+For shared fixtures, best practices, and detailed guidance, see `backend/tests/README.md`.
+
 ## Logs
 
 When (1) writing integration tests or (2) doing live tests (e.g. curl / playwright) you can get access
diff --git a/backend/onyx/utils/variable_functionality.py b/backend/onyx/utils/variable_functionality.py
index c1d2ff7497b..f67210b363d 100644
--- a/backend/onyx/utils/variable_functionality.py
+++ b/backend/onyx/utils/variable_functionality.py
@@ -24,6 +24,9 @@ def __init__(self) -> None:
     def set_ee(self) -> None:
         self._is_ee = True
 
+    def unset_ee(self) -> None:
+        self._is_ee = False
+
     def is_ee_version(self) -> bool:
         return self._is_ee
 
diff --git a/backend/tests/README.md b/backend/tests/README.md
new file mode 100644
index 00000000000..80fbe8f2a37
--- /dev/null
+++ b/backend/tests/README.md
@@ -0,0 +1,71 @@
+# Backend Tests
+
+## Test Types
+
+There are four test categories, ordered by increasing scope:
+
+### Unit Tests (`tests/unit/`)
+
+No external services. Mock all I/O with `unittest.mock`. Use for complex, isolated
+logic (e.g. citation processing, encryption).
+
+```bash
+pytest -xv backend/tests/unit
+```
+
+### External Dependency Unit Tests (`tests/external_dependency_unit/`)
+
+External services (Postgres, Redis, Vespa, OpenAI, etc.) are running, but Onyx
+application containers are not. Tests call functions directly and can mock selectively.
+
+Use when you need a real database or real API calls but want control over setup.
+
+```bash
+python -m dotenv -f .vscode/.env run -- pytest backend/tests/external_dependency_unit
+```
+
+### Integration Tests (`tests/integration/`)
+
+Full Onyx deployment running. No mocking. Prefer this over other test types when possible.
+
+```bash
+python -m dotenv -f .vscode/.env run -- pytest backend/tests/integration
+```
+
+### Playwright / E2E Tests (`web/tests/e2e/`)
+
+Full stack including web server. Use for frontend-backend coordination.
+
+```bash
+npx playwright test <TEST_NAME>
+```
+
+## Shared Fixtures
+
+Shared fixtures live in `backend/tests/conftest.py`. Test subdirectories can define
+their own `conftest.py` for directory-scoped fixtures.
+
+## Best Practices
+
+### Use `enable_ee` fixture instead of inlining
+
+Enables EE mode for a test, with proper teardown and cache clearing.
+
+```python
+# Whole file (in a test module, NOT in conftest.py)
+pytestmark = pytest.mark.usefixtures("enable_ee")
+
+# Whole directory — add an autouse wrapper to the directory's conftest.py
+@pytest.fixture(autouse=True)
+def _enable_ee_for_directory(enable_ee: None) -> None:  # noqa: ARG001
+    """Wraps the shared enable_ee fixture with autouse for this directory."""
+
+# Single test
+def test_something(enable_ee: None) -> None: ...
+```
+
+**Note:** `pytestmark` in a `conftest.py` does NOT apply markers to tests in that
+directory — it only affects tests defined in the conftest itself (which is none).
+Use the autouse fixture wrapper pattern shown above instead.
+
+Do NOT inline `global_version.set_ee()` — always use the fixture.
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
new file mode 100644
index 00000000000..1bcb468eb45
--- /dev/null
+++ b/backend/tests/conftest.py
@@ -0,0 +1,24 @@
+"""Root conftest — shared fixtures available to all test directories."""
+
+from collections.abc import Generator
+
+import pytest
+
+from onyx.utils.variable_functionality import fetch_versioned_implementation
+from onyx.utils.variable_functionality import global_version
+
+
+@pytest.fixture()
+def enable_ee() -> Generator[None, None, None]:
+    """Temporarily enable EE mode for a single test.
+
+    Restores the previous EE state and clears the versioned-implementation
+    cache on teardown so state doesn't leak between tests.
+    """
+    was_ee = global_version.is_ee_version()
+    global_version.set_ee()
+    fetch_versioned_implementation.cache_clear()
+    yield
+    if not was_ee:
+        global_version.unset_ee()
+    fetch_versioned_implementation.cache_clear()
diff --git a/backend/tests/daily/connectors/confluence/test_confluence_permissions_basic.py b/backend/tests/daily/connectors/confluence/test_confluence_permissions_basic.py
index d47a98efd90..40edb036b24 100644
--- a/backend/tests/daily/connectors/confluence/test_confluence_permissions_basic.py
+++ b/backend/tests/daily/connectors/confluence/test_confluence_permissions_basic.py
@@ -45,7 +45,7 @@ def confluence_connector() -> ConfluenceConnector:
 def test_confluence_connector_permissions(
     mock_get_api_key: MagicMock,  # noqa: ARG001
     confluence_connector: ConfluenceConnector,
-    set_ee_on: None,  # noqa: ARG001
+    enable_ee: None,  # noqa: ARG001
 ) -> None:
     # Get all doc IDs from the full connector
     all_full_doc_ids = set()
@@ -93,7 +93,7 @@ def test_confluence_connector_permissions(
 def test_confluence_connector_restriction_handling(
     mock_get_api_key: MagicMock,  # noqa: ARG001
     mock_db_provider_class: MagicMock,
-    set_ee_on: None,  # noqa: ARG001
+    enable_ee: None,  # noqa: ARG001
 ) -> None:
     # Test space key
     test_space_key = "DailyPermS"
diff --git a/backend/tests/daily/connectors/conftest.py b/backend/tests/daily/connectors/conftest.py
index ad702e4cfcd..88a00b57af1 100644
--- a/backend/tests/daily/connectors/conftest.py
+++ b/backend/tests/daily/connectors/conftest.py
@@ -4,8 +4,6 @@
 
 import pytest
 
-from onyx.utils.variable_functionality import global_version
-
 
 @pytest.fixture
 def mock_get_unstructured_api_key() -> Generator[MagicMock, None, None]:
@@ -14,14 +12,3 @@ def mock_get_unstructured_api_key() -> Generator[MagicMock, None, None]:
         return_value=None,
     ) as mock:
         yield mock
-
-
-@pytest.fixture
-def set_ee_on() -> Generator[None, None, None]:
-    """Need EE to be enabled for these tests to work since
-    perm syncing is a an EE-only feature."""
-    global_version.set_ee()
-
-    yield
-
-    global_version._is_ee = False
diff --git a/backend/tests/daily/connectors/google_drive/test_drive_perm_sync.py b/backend/tests/daily/connectors/google_drive/test_drive_perm_sync.py
index 5a8e9d6b2fe..0f5777e372c 100644
--- a/backend/tests/daily/connectors/google_drive/test_drive_perm_sync.py
+++ b/backend/tests/daily/connectors/google_drive/test_drive_perm_sync.py
@@ -98,7 +98,7 @@ def _build_connector(
 
 def test_gdrive_perm_sync_with_real_data(
     google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
-    set_ee_on: None,  # noqa: ARG001
+    enable_ee: None,  # noqa: ARG001
 ) -> None:
     """
     Test gdrive_doc_sync and gdrive_group_sync with real data from the test drive.
diff --git a/backend/tests/daily/connectors/slack/test_slack_perm_sync.py b/backend/tests/daily/connectors/slack/test_slack_perm_sync.py
index 619482ba964..d53404414ad 100644
--- a/backend/tests/daily/connectors/slack/test_slack_perm_sync.py
+++ b/backend/tests/daily/connectors/slack/test_slack_perm_sync.py
@@ -1,12 +1,10 @@
 import time
-from collections.abc import Generator
 
 import pytest
 
 from onyx.connectors.models import HierarchyNode
 from onyx.connectors.models import SlimDocument
 from onyx.connectors.slack.connector import SlackConnector
-from onyx.utils.variable_functionality import global_version
 from tests.daily.connectors.utils import load_all_from_connector
 
 
@@ -19,16 +17,7 @@
     "test_user_2@onyx-test.com",
 ]
 
-
-@pytest.fixture(autouse=True)
-def set_ee_on() -> Generator[None, None, None]:
-    """Need EE to be enabled for these tests to work since
-    perm syncing is a an EE-only feature."""
-    global_version.set_ee()
-
-    yield
-
-    global_version._is_ee = False
+pytestmark = pytest.mark.usefixtures("enable_ee")
 
 
 @pytest.mark.parametrize(
diff --git a/backend/tests/daily/connectors/teams/test_teams_connector.py b/backend/tests/daily/connectors/teams/test_teams_connector.py
index 2b5c1e62cbd..39d8f52fd84 100644
--- a/backend/tests/daily/connectors/teams/test_teams_connector.py
+++ b/backend/tests/daily/connectors/teams/test_teams_connector.py
@@ -1,13 +1,11 @@
 import os
 import time
-from collections.abc import Generator
 
 import pytest
 
 from onyx.access.models import ExternalAccess
 from onyx.connectors.models import HierarchyNode
 from onyx.connectors.teams.connector import TeamsConnector
-from onyx.utils.variable_functionality import global_version
 from tests.daily.connectors.teams.models import TeamsThread
 from tests.daily.connectors.utils import load_all_from_connector
 
@@ -168,18 +166,9 @@ def test_slim_docs_retrieval_from_teams_connector(
         _assert_is_valid_external_access(external_access=slim_doc.external_access)
 
 
-@pytest.fixture(autouse=False)
-def set_ee_on() -> Generator[None, None, None]:
-    """Need EE to be enabled for perm sync tests to work since
-    perm syncing is an EE-only feature."""
-    global_version.set_ee()
-    yield
-    global_version._is_ee = False
-
-
 def test_load_from_checkpoint_with_perm_sync(
     teams_connector: TeamsConnector,
-    set_ee_on: None,  # noqa: ARG001
+    enable_ee: None,  # noqa: ARG001
 ) -> None:
     """Test that load_from_checkpoint_with_perm_sync returns documents with external_access.
 
diff --git a/backend/tests/external_dependency_unit/connectors/jira/test_jira_doc_sync.py b/backend/tests/external_dependency_unit/connectors/jira/test_jira_doc_sync.py
index a089ec439de..d6dfa9c9bf6 100644
--- a/backend/tests/external_dependency_unit/connectors/jira/test_jira_doc_sync.py
+++ b/backend/tests/external_dependency_unit/connectors/jira/test_jira_doc_sync.py
@@ -1,5 +1,6 @@
 from typing import Any
 
+import pytest
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
@@ -14,13 +15,14 @@
 from onyx.db.models import Credential
 from onyx.db.utils import DocumentRow
 from onyx.db.utils import SortOrder
-from onyx.utils.variable_functionality import global_version
 
 
 # In order to get these tests to run, use the credentials from Bitwarden.
 # Search up "ENV vars for local and Github tests", and find the Jira relevant key-value pairs.
 # Required env vars: JIRA_USER_EMAIL, JIRA_API_TOKEN
 
+pytestmark = pytest.mark.usefixtures("enable_ee")
+
 
 class DocExternalAccessSet(BaseModel):
     """A version of DocExternalAccess that uses sets for comparison."""
@@ -52,9 +54,6 @@ def test_jira_doc_sync(
     This test uses the AS project which has applicationRole permission,
     meaning all documents should be marked as public.
     """
-    # NOTE: must set EE on or else the connector will skip the perm syncing
-    global_version.set_ee()
-
     try:
         # Use AS project specifically for this test
         connector_config = {
@@ -150,9 +149,6 @@ def test_jira_doc_sync_with_specific_permissions(
     This test uses a project that has specific user permissions to verify
     that specific users are correctly extracted.
     """
-    # NOTE: must set EE on or else the connector will skip the perm syncing
-    global_version.set_ee()
-
     try:
         # Use SUP project which has specific user permissions
         connector_config = {
diff --git a/backend/tests/external_dependency_unit/connectors/jira/test_jira_group_sync.py b/backend/tests/external_dependency_unit/connectors/jira/test_jira_group_sync.py
index 052fb53ec1a..b82e95bddd1 100644
--- a/backend/tests/external_dependency_unit/connectors/jira/test_jira_group_sync.py
+++ b/backend/tests/external_dependency_unit/connectors/jira/test_jira_group_sync.py
@@ -1,5 +1,6 @@
 from typing import Any
 
+import pytest
 from sqlalchemy.orm import Session
 
 from ee.onyx.external_permissions.jira.group_sync import jira_group_sync
@@ -18,6 +19,8 @@
 # Search up "ENV vars for local and Github tests", and find the Jira relevant key-value pairs.
 # Required env vars: JIRA_USER_EMAIL, JIRA_API_TOKEN
 
+pytestmark = pytest.mark.usefixtures("enable_ee")
+
 # Expected groups from the danswerai.atlassian.net Jira instance
 # Note: These groups are shared with Confluence since they're both Atlassian products
 # App accounts (bots, integrations) are filtered out
diff --git a/backend/tests/unit/ee/conftest.py b/backend/tests/unit/ee/conftest.py
new file mode 100644
index 00000000000..ebdffebc9cc
--- /dev/null
+++ b/backend/tests/unit/ee/conftest.py
@@ -0,0 +1,8 @@
+"""Auto-enable EE mode for all tests under tests/unit/ee/."""
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _enable_ee_for_directory(enable_ee: None) -> None:  # noqa: ARG001
+    """Wraps the shared enable_ee fixture with autouse for this directory."""
diff --git a/backend/tests/unit/onyx/connectors/jira/test_jira_permission_sync.py b/backend/tests/unit/onyx/connectors/jira/test_jira_permission_sync.py
index 64b41e9e88d..a07ee71bac5 100644
--- a/backend/tests/unit/onyx/connectors/jira/test_jira_permission_sync.py
+++ b/backend/tests/unit/onyx/connectors/jira/test_jira_permission_sync.py
@@ -9,6 +9,8 @@
 from onyx.db.models import ConnectorCredentialPair
 from onyx.utils.sensitive import make_mock_sensitive_value
 
+pytestmark = pytest.mark.usefixtures("enable_ee")
+
 
 @pytest.fixture
 def mock_jira_cc_pair(

From f1df36e3067d1d42d5c011e14e450da5a6fa57a2 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Fri, 6 Mar 2026 19:18:47 -0800
Subject: [PATCH 169/267] feat(cli): package as docker image (#9167)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 .github/workflows/release-cli.yml | 177 +++++++++++++++++++++++++++++-
 cli/Dockerfile                    |  22 ++++
 docker-bake.hcl                   |  14 +++
 3 files changed, 212 insertions(+), 1 deletion(-)
 create mode 100644 cli/Dockerfile

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index 82cbeefa2a9..24d4b649735 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -26,7 +26,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
           version: "0.9.9"
@@ -37,3 +37,178 @@ jobs:
         working-directory: cli
       - run: uv publish
         working-directory: cli
+
+  docker-amd64:
+    runs-on:
+      - runs-on
+      - runner=2cpu-linux-x64
+      - run-id=${{ github.run_id }}-cli-amd64
+      - extras=ecr-cache
+    environment: deploy
+    permissions:
+      id-token: write
+    timeout-minutes: 30
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    env:
+      REGISTRY_IMAGE: onyxdotapp/onyx-cli
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # ratchet:aws-actions/configure-aws-credentials@v6.0.0
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802 # ratchet:aws-actions/aws-secretsmanager-get-secrets@v2.0.10
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # ratchet:docker/login-action@v4
+        with:
+          username: ${{ env.DOCKER_USERNAME }}
+          password: ${{ env.DOCKER_TOKEN }}
+
+      - name: Build and push AMD64
+        id: build
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # ratchet:docker/build-push-action@v7
+        with:
+          context: ./cli
+          file: ./cli/Dockerfile
+          platforms: linux/amd64
+          cache-from: type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
+          cache-to: type=inline
+          outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true
+
+  docker-arm64:
+    runs-on:
+      - runs-on
+      - runner=2cpu-linux-arm64
+      - run-id=${{ github.run_id }}-cli-arm64
+      - extras=ecr-cache
+    environment: deploy
+    permissions:
+      id-token: write
+    timeout-minutes: 30
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    env:
+      REGISTRY_IMAGE: onyxdotapp/onyx-cli
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # ratchet:aws-actions/configure-aws-credentials@v6.0.0
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802 # ratchet:aws-actions/aws-secretsmanager-get-secrets@v2.0.10
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # ratchet:docker/login-action@v4
+        with:
+          username: ${{ env.DOCKER_USERNAME }}
+          password: ${{ env.DOCKER_TOKEN }}
+
+      - name: Build and push ARM64
+        id: build
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # ratchet:docker/build-push-action@v7
+        with:
+          context: ./cli
+          file: ./cli/Dockerfile
+          platforms: linux/arm64
+          cache-from: type=registry,ref=${{ env.REGISTRY_IMAGE }}:latest
+          cache-to: type=inline
+          outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true
+
+  merge-docker:
+    needs:
+      - docker-amd64
+      - docker-arm64
+    runs-on:
+      - runs-on
+      - runner=2cpu-linux-x64
+      - run-id=${{ github.run_id }}-cli-merge
+    environment: deploy
+    permissions:
+      id-token: write
+    timeout-minutes: 10
+    env:
+      REGISTRY_IMAGE: onyxdotapp/onyx-cli
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # ratchet:aws-actions/configure-aws-credentials@v6.0.0
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802 # ratchet:aws-actions/aws-secretsmanager-get-secrets@v2.0.10
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # ratchet:docker/login-action@v4
+        with:
+          username: ${{ env.DOCKER_USERNAME }}
+          password: ${{ env.DOCKER_TOKEN }}
+
+      - name: Create and push manifest
+        env:
+          AMD64_DIGEST: ${{ needs.docker-amd64.outputs.digest }}
+          ARM64_DIGEST: ${{ needs.docker-arm64.outputs.digest }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          SANITIZED_TAG="${TAG#cli/}"
+          IMAGES=(
+            "${REGISTRY_IMAGE}@${AMD64_DIGEST}"
+            "${REGISTRY_IMAGE}@${ARM64_DIGEST}"
+          )
+
+          if [[ "$TAG" =~ ^cli/v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            docker buildx imagetools create \
+              -t "${REGISTRY_IMAGE}:${SANITIZED_TAG}" \
+              -t "${REGISTRY_IMAGE}:latest" \
+              "${IMAGES[@]}"
+          else
+            docker buildx imagetools create \
+              -t "${REGISTRY_IMAGE}:${SANITIZED_TAG}" \
+              "${IMAGES[@]}"
+          fi
diff --git a/cli/Dockerfile b/cli/Dockerfile
new file mode 100644
index 00000000000..8246d21b3ed
--- /dev/null
+++ b/cli/Dockerfile
@@ -0,0 +1,22 @@
+FROM golang:1.26-alpine@sha256:2389ebfa5b7f43eeafbd6be0c3700cc46690ef842ad962f6c5bd6be49ed82039 AS builder
+
+WORKDIR /app
+COPY ./ .
+
+ARG TARGETARCH
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH} go build -ldflags="-s -w" -o onyx-cli .
+RUN mkdir -p /home/onyx/.config
+
+FROM scratch
+
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=builder --chown=65534:65534 /home/onyx /home/onyx
+
+COPY --from=builder /app/onyx-cli /onyx-cli
+
+ENV HOME=/home/onyx
+ENV XDG_CONFIG_HOME=/home/onyx/.config
+
+USER 65534:65534
+
+ENTRYPOINT ["/onyx-cli"]
diff --git a/docker-bake.hcl b/docker-bake.hcl
index b86563199db..64d25e8c65f 100644
--- a/docker-bake.hcl
+++ b/docker-bake.hcl
@@ -18,6 +18,10 @@ variable "INTEGRATION_REPOSITORY" {
   default = "onyxdotapp/onyx-integration"
 }
 
+variable "CLI_REPOSITORY" {
+  default = "onyxdotapp/onyx-cli"
+}
+
 variable "TAG" {
   default = "latest"
 }
@@ -64,3 +68,13 @@ target "integration" {
 
   tags      = ["${INTEGRATION_REPOSITORY}:${TAG}"]
 }
+
+target "cli" {
+  context    = "cli"
+  dockerfile = "Dockerfile"
+
+  cache-from = ["type=registry,ref=${CLI_REPOSITORY}:latest"]
+  cache-to   = ["type=inline"]
+
+  tags      = ["${CLI_REPOSITORY}:${TAG}"]
+}

From 29d9ebf7b3cfb5326e30ac3f7c1230c06261c011 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Fri, 6 Mar 2026 22:17:21 -0800
Subject: [PATCH 170/267] feat: rotate encryption key utility (#9162)

---
 backend/Dockerfile                            |   1 +
 backend/ee/onyx/utils/encryption.py           |  86 +++--
 backend/onyx/db/rotate_encryption_key.py      | 161 +++++++++
 backend/onyx/utils/encryption.py              |  20 +-
 backend/scripts/reencrypt_secrets.py          | 107 ++++++
 .../db/test_rotate_encryption_key.py          | 305 ++++++++++++++++++
 .../unit/ee/onyx/utils/test_encryption.py     | 165 ++++++++++
 7 files changed, 806 insertions(+), 39 deletions(-)
 create mode 100644 backend/onyx/db/rotate_encryption_key.py
 create mode 100644 backend/scripts/reencrypt_secrets.py
 create mode 100644 backend/tests/external_dependency_unit/db/test_rotate_encryption_key.py
 create mode 100644 backend/tests/unit/ee/onyx/utils/test_encryption.py

diff --git a/backend/Dockerfile b/backend/Dockerfile
index f6b298707d0..b6d284ffbc1 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -141,6 +141,7 @@ COPY --chown=onyx:onyx ./scripts/debugging /app/scripts/debugging
 COPY --chown=onyx:onyx ./scripts/force_delete_connector_by_id.py /app/scripts/force_delete_connector_by_id.py
 COPY --chown=onyx:onyx ./scripts/supervisord_entrypoint.sh /app/scripts/supervisord_entrypoint.sh
 COPY --chown=onyx:onyx ./scripts/setup_craft_templates.sh /app/scripts/setup_craft_templates.sh
+COPY --chown=onyx:onyx ./scripts/reencrypt_secrets.py /app/scripts/reencrypt_secrets.py
 RUN chmod +x /app/scripts/supervisord_entrypoint.sh /app/scripts/setup_craft_templates.sh
 
 # Run Craft template setup at build time when ENABLE_CRAFT=true
diff --git a/backend/ee/onyx/utils/encryption.py b/backend/ee/onyx/utils/encryption.py
index 85be05df31b..79b75f7441b 100644
--- a/backend/ee/onyx/utils/encryption.py
+++ b/backend/ee/onyx/utils/encryption.py
@@ -14,67 +14,91 @@
 logger = setup_logger()
 
 
-@lru_cache(maxsize=1)
+@lru_cache(maxsize=2)
 def _get_trimmed_key(key: str) -> bytes:
     encoded_key = key.encode()
     key_length = len(encoded_key)
     if key_length < 16:
         raise RuntimeError("Invalid ENCRYPTION_KEY_SECRET - too short")
-    elif key_length > 32:
-        key = key[:32]
-    elif key_length not in (16, 24, 32):
-        valid_lengths = [16, 24, 32]
-        key = key[: min(valid_lengths, key=lambda x: abs(x - key_length))]
 
-    return encoded_key
+    # Trim to the largest valid AES key size that fits
+    valid_lengths = [32, 24, 16]
+    for size in valid_lengths:
+        if key_length >= size:
+            return encoded_key[:size]
 
+    raise AssertionError("unreachable")
 
-def _encrypt_string(input_str: str) -> bytes:
-    if not ENCRYPTION_KEY_SECRET:
+
+def _encrypt_string(input_str: str, key: str | None = None) -> bytes:
+    effective_key = key if key is not None else ENCRYPTION_KEY_SECRET
+    if not effective_key:
         return input_str.encode()
 
-    key = _get_trimmed_key(ENCRYPTION_KEY_SECRET)
+    trimmed = _get_trimmed_key(effective_key)
     iv = urandom(16)
     padder = padding.PKCS7(algorithms.AES.block_size).padder()
     padded_data = padder.update(input_str.encode()) + padder.finalize()
 
-    cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=default_backend())
+    cipher = Cipher(algorithms.AES(trimmed), modes.CBC(iv), backend=default_backend())
     encryptor = cipher.encryptor()
     encrypted_data = encryptor.update(padded_data) + encryptor.finalize()
 
     return iv + encrypted_data
 
 
-def _decrypt_bytes(input_bytes: bytes) -> str:
-    if not ENCRYPTION_KEY_SECRET:
+def _decrypt_bytes(input_bytes: bytes, key: str | None = None) -> str:
+    effective_key = key if key is not None else ENCRYPTION_KEY_SECRET
+    if not effective_key:
         return input_bytes.decode()
 
-    key = _get_trimmed_key(ENCRYPTION_KEY_SECRET)
-    iv = input_bytes[:16]
-    encrypted_data = input_bytes[16:]
-
-    cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=default_backend())
-    decryptor = cipher.decryptor()
-    decrypted_padded_data = decryptor.update(encrypted_data) + decryptor.finalize()
-
-    unpadder = padding.PKCS7(algorithms.AES.block_size).unpadder()
-    decrypted_data = unpadder.update(decrypted_padded_data) + unpadder.finalize()
-
-    return decrypted_data.decode()
-
-
-def encrypt_string_to_bytes(input_str: str) -> bytes:
+    trimmed = _get_trimmed_key(effective_key)
+    try:
+        iv = input_bytes[:16]
+        encrypted_data = input_bytes[16:]
+
+        cipher = Cipher(
+            algorithms.AES(trimmed), modes.CBC(iv), backend=default_backend()
+        )
+        decryptor = cipher.decryptor()
+        decrypted_padded_data = decryptor.update(encrypted_data) + decryptor.finalize()
+
+        unpadder = padding.PKCS7(algorithms.AES.block_size).unpadder()
+        decrypted_data = unpadder.update(decrypted_padded_data) + unpadder.finalize()
+
+        return decrypted_data.decode()
+    except (ValueError, UnicodeDecodeError):
+        if key is not None:
+            # Explicit key was provided — don't fall back silently
+            raise
+        # Read path: attempt raw UTF-8 decode as a fallback for legacy data.
+        # Does NOT handle data encrypted with a different key — that
+        # ciphertext is not valid UTF-8 and will raise below.
+        logger.warning(
+            "AES decryption failed — falling back to raw decode. "
+            "Run the re-encrypt secrets script to rotate to the current key."
+        )
+        try:
+            return input_bytes.decode()
+        except UnicodeDecodeError:
+            raise ValueError(
+                "Data is not valid UTF-8 — likely encrypted with a different key. "
+                "Run the re-encrypt secrets script to rotate to the current key."
+            ) from None
+
+
+def encrypt_string_to_bytes(input_str: str, key: str | None = None) -> bytes:
     versioned_encryption_fn = fetch_versioned_implementation(
         "onyx.utils.encryption", "_encrypt_string"
     )
-    return versioned_encryption_fn(input_str)
+    return versioned_encryption_fn(input_str, key=key)
 
 
-def decrypt_bytes_to_string(input_bytes: bytes) -> str:
+def decrypt_bytes_to_string(input_bytes: bytes, key: str | None = None) -> str:
     versioned_decryption_fn = fetch_versioned_implementation(
         "onyx.utils.encryption", "_decrypt_bytes"
     )
-    return versioned_decryption_fn(input_bytes)
+    return versioned_decryption_fn(input_bytes, key=key)
 
 
 def test_encryption() -> None:
diff --git a/backend/onyx/db/rotate_encryption_key.py b/backend/onyx/db/rotate_encryption_key.py
new file mode 100644
index 00000000000..ddb99fc9c43
--- /dev/null
+++ b/backend/onyx/db/rotate_encryption_key.py
@@ -0,0 +1,161 @@
+"""Rotate encryption key for all encrypted columns.
+
+Dynamically discovers all columns using EncryptedString / EncryptedJson,
+decrypts each value with the old key, and re-encrypts with the current
+ENCRYPTION_KEY_SECRET.
+
+The operation is idempotent: rows already encrypted with the current key
+are skipped. Commits are made in batches so a crash mid-rotation can be
+safely resumed by re-running.
+"""
+
+import json
+from typing import Any
+
+from sqlalchemy import LargeBinary
+from sqlalchemy import select
+from sqlalchemy import update
+from sqlalchemy.orm import Session
+
+from onyx.configs.app_configs import ENCRYPTION_KEY_SECRET
+from onyx.db.models import Base
+from onyx.db.models import EncryptedJson
+from onyx.db.models import EncryptedString
+from onyx.utils.encryption import decrypt_bytes_to_string
+from onyx.utils.logger import setup_logger
+from onyx.utils.variable_functionality import global_version
+
+logger = setup_logger()
+
+_BATCH_SIZE = 500
+
+
+def _can_decrypt_with_current_key(data: bytes) -> bool:
+    """Check if data is already encrypted with the current key.
+
+    Passes the key explicitly so the fallback-to-raw-decode path in
+    _decrypt_bytes is NOT triggered — a clean success/failure signal.
+    """
+    try:
+        decrypt_bytes_to_string(data, key=ENCRYPTION_KEY_SECRET)
+        return True
+    except Exception:
+        return False
+
+
+def _discover_encrypted_columns() -> list[tuple[type, str, list[str], bool]]:
+    """Walk all ORM models and find columns using EncryptedString/EncryptedJson.
+
+    Returns list of (ModelClass, column_attr_name, [pk_attr_names], is_json).
+    """
+    results: list[tuple[type, str, list[str], bool]] = []
+
+    for mapper in Base.registry.mappers:
+        model_cls = mapper.class_
+        pk_names = [col.key for col in mapper.primary_key]
+
+        for prop in mapper.column_attrs:
+            for col in prop.columns:
+                if isinstance(col.type, EncryptedJson):
+                    results.append((model_cls, prop.key, pk_names, True))
+                elif isinstance(col.type, EncryptedString):
+                    results.append((model_cls, prop.key, pk_names, False))
+
+    return results
+
+
+def rotate_encryption_key(
+    db_session: Session,
+    old_key: str | None,
+    dry_run: bool = False,
+) -> dict[str, int]:
+    """Decrypt all encrypted columns with old_key and re-encrypt with the current key.
+
+    Args:
+        db_session: Active database session.
+        old_key: The previous encryption key. Pass None or "" if values were
+                 not previously encrypted with a key.
+        dry_run: If True, count rows that need rotation without modifying data.
+
+    Returns:
+        Dict of "table.column" -> number of rows re-encrypted (or would be).
+
+    Commits every _BATCH_SIZE rows so that locks are held briefly and progress
+    is preserved on crash. Already-rotated rows are detected and skipped,
+    making the operation safe to re-run.
+    """
+    if not global_version.is_ee_version():
+        raise RuntimeError("EE mode is not enabled — rotation requires EE encryption.")
+
+    if not ENCRYPTION_KEY_SECRET:
+        raise RuntimeError(
+            "ENCRYPTION_KEY_SECRET is not set — cannot rotate. "
+            "Set the target encryption key in the environment before running."
+        )
+
+    encrypted_columns = _discover_encrypted_columns()
+    totals: dict[str, int] = {}
+
+    for model_cls, col_name, pk_names, is_json in encrypted_columns:
+        table_name: str = model_cls.__tablename__  # type: ignore[attr-defined]
+        col_attr = getattr(model_cls, col_name)
+        pk_attrs = [getattr(model_cls, pk) for pk in pk_names]
+
+        # Read raw bytes directly, bypassing the TypeDecorator
+        raw_col = col_attr.property.columns[0]
+
+        stmt = select(*pk_attrs, raw_col.cast(LargeBinary)).where(col_attr.is_not(None))
+        rows = db_session.execute(stmt).all()
+
+        reencrypted = 0
+        batch_pending = 0
+        for row in rows:
+            raw_bytes: bytes | None = row[-1]
+            if raw_bytes is None:
+                continue
+
+            if _can_decrypt_with_current_key(raw_bytes):
+                continue
+
+            try:
+                if not old_key:
+                    decrypted_str = raw_bytes.decode("utf-8")
+                else:
+                    decrypted_str = decrypt_bytes_to_string(raw_bytes, key=old_key)
+
+                # For EncryptedJson, parse back to dict so the TypeDecorator
+                # can json.dumps() it cleanly (avoids double-encoding).
+                value: Any = json.loads(decrypted_str) if is_json else decrypted_str
+            except (ValueError, UnicodeDecodeError) as e:
+                pk_vals = [row[i] for i in range(len(pk_names))]
+                logger.warning(
+                    f"Could not decrypt/parse {table_name}.{col_name} "
+                    f"row {pk_vals} — skipping: {e}"
+                )
+                continue
+
+            if not dry_run:
+                pk_filters = [pk_attr == row[i] for i, pk_attr in enumerate(pk_attrs)]
+                update_stmt = (
+                    update(model_cls).where(*pk_filters).values({col_name: value})
+                )
+                db_session.execute(update_stmt)
+                batch_pending += 1
+
+                if batch_pending >= _BATCH_SIZE:
+                    db_session.commit()
+                    batch_pending = 0
+            reencrypted += 1
+
+        # Flush remaining rows in this column
+        if batch_pending > 0:
+            db_session.commit()
+
+        if reencrypted > 0:
+            totals[f"{table_name}.{col_name}"] = reencrypted
+            logger.info(
+                f"{'[DRY RUN] Would re-encrypt' if dry_run else 'Re-encrypted'} "
+                f"{reencrypted} value(s) in {table_name}.{col_name}"
+            )
+
+    return totals
diff --git a/backend/onyx/utils/encryption.py b/backend/onyx/utils/encryption.py
index 299b2326b82..d7385528207 100644
--- a/backend/onyx/utils/encryption.py
+++ b/backend/onyx/utils/encryption.py
@@ -11,16 +11,20 @@
 
 
 # IMPORTANT DO NOT DELETE, THIS IS USED BY fetch_versioned_implementation
-def _encrypt_string(input_str: str) -> bytes:
+def _encrypt_string(input_str: str, key: str | None = None) -> bytes:  # noqa: ARG001
     if ENCRYPTION_KEY_SECRET:
         logger.warning("MIT version of Onyx does not support encryption of secrets.")
+    elif key is not None:
+        logger.debug("MIT encrypt called with explicit key — key ignored.")
     return input_str.encode()
 
 
 # IMPORTANT DO NOT DELETE, THIS IS USED BY fetch_versioned_implementation
-def _decrypt_bytes(input_bytes: bytes) -> str:
-    # No need to double warn. If you wish to learn more about encryption features
-    # refer to the Onyx EE code
+def _decrypt_bytes(input_bytes: bytes, key: str | None = None) -> str:  # noqa: ARG001
+    if ENCRYPTION_KEY_SECRET:
+        logger.warning("MIT version of Onyx does not support decryption of secrets.")
+    elif key is not None:
+        logger.debug("MIT decrypt called with explicit key — key ignored.")
     return input_bytes.decode()
 
 
@@ -86,15 +90,15 @@ def _mask_list(items: list[Any]) -> list[Any]:
     return masked
 
 
-def encrypt_string_to_bytes(intput_str: str) -> bytes:
+def encrypt_string_to_bytes(intput_str: str, key: str | None = None) -> bytes:
     versioned_encryption_fn = fetch_versioned_implementation(
         "onyx.utils.encryption", "_encrypt_string"
     )
-    return versioned_encryption_fn(intput_str)
+    return versioned_encryption_fn(intput_str, key=key)
 
 
-def decrypt_bytes_to_string(intput_bytes: bytes) -> str:
+def decrypt_bytes_to_string(intput_bytes: bytes, key: str | None = None) -> str:
     versioned_decryption_fn = fetch_versioned_implementation(
         "onyx.utils.encryption", "_decrypt_bytes"
     )
-    return versioned_decryption_fn(intput_bytes)
+    return versioned_decryption_fn(intput_bytes, key=key)
diff --git a/backend/scripts/reencrypt_secrets.py b/backend/scripts/reencrypt_secrets.py
new file mode 100644
index 00000000000..0458cbe1f6e
--- /dev/null
+++ b/backend/scripts/reencrypt_secrets.py
@@ -0,0 +1,107 @@
+"""Re-encrypt secrets under the current ENCRYPTION_KEY_SECRET.
+
+Decrypts all encrypted columns using the old key (or raw decode if the old key
+is empty), then re-encrypts them with the current ENCRYPTION_KEY_SECRET.
+
+Usage (docker):
+    docker exec -it onyx-api_server-1 \
+        python -m scripts.reencrypt_secrets --old-key "previous-key"
+
+Usage (kubernetes):
+    kubectl exec -it <pod> -- \
+        python -m scripts.reencrypt_secrets --old-key "previous-key"
+
+Omit --old-key (or pass "") if secrets were not previously encrypted.
+
+For multi-tenant deployments, pass --tenant-id to target a specific tenant,
+or --all-tenants to iterate every tenant.
+"""
+
+import argparse
+import os
+import sys
+
+parent_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(parent_dir)
+
+from onyx.db.rotate_encryption_key import rotate_encryption_key  # noqa: E402
+from onyx.db.engine.sql_engine import get_session_with_tenant  # noqa: E402
+from onyx.db.engine.sql_engine import SqlEngine  # noqa: E402
+from onyx.db.engine.tenant_utils import get_all_tenant_ids  # noqa: E402
+from onyx.utils.variable_functionality import global_version  # noqa: E402
+from shared_configs.configs import POSTGRES_DEFAULT_SCHEMA  # noqa: E402
+
+
+def _run_for_tenant(tenant_id: str, old_key: str | None, dry_run: bool = False) -> None:
+    print(f"Re-encrypting secrets for tenant: {tenant_id}")
+    with get_session_with_tenant(tenant_id=tenant_id) as db_session:
+        results = rotate_encryption_key(db_session, old_key=old_key, dry_run=dry_run)
+
+    if results:
+        for col, count in results.items():
+            print(
+                f"  {col}: {count} row(s) {'would be ' if dry_run else ''}re-encrypted"
+            )
+    else:
+        print("No rows needed re-encryption.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Re-encrypt secrets under the current encryption key."
+    )
+    parser.add_argument(
+        "--old-key",
+        default=None,
+        help="Previous encryption key. Omit or pass empty string if not applicable.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be re-encrypted without making changes.",
+    )
+
+    tenant_group = parser.add_mutually_exclusive_group()
+    tenant_group.add_argument(
+        "--tenant-id",
+        default=None,
+        help="Target a specific tenant schema.",
+    )
+    tenant_group.add_argument(
+        "--all-tenants",
+        action="store_true",
+        help="Iterate all tenants.",
+    )
+
+    args = parser.parse_args()
+
+    old_key = args.old_key if args.old_key else None
+
+    global_version.set_ee()
+    SqlEngine.init_engine(pool_size=5, max_overflow=2)
+
+    if args.dry_run:
+        print("DRY RUN — no changes will be made")
+
+    if args.all_tenants:
+        tenant_ids = get_all_tenant_ids()
+        print(f"Found {len(tenant_ids)} tenant(s)")
+        failed_tenants: list[str] = []
+        for tid in tenant_ids:
+            try:
+                _run_for_tenant(tid, old_key, dry_run=args.dry_run)
+            except Exception as e:
+                print(f"  ERROR for tenant {tid}: {e}")
+                failed_tenants.append(tid)
+        if failed_tenants:
+            print(f"FAILED tenants ({len(failed_tenants)}): {failed_tenants}")
+            sys.exit(1)
+    else:
+        tenant_id = args.tenant_id or POSTGRES_DEFAULT_SCHEMA
+        _run_for_tenant(tenant_id, old_key, dry_run=args.dry_run)
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/backend/tests/external_dependency_unit/db/test_rotate_encryption_key.py b/backend/tests/external_dependency_unit/db/test_rotate_encryption_key.py
new file mode 100644
index 00000000000..cded9f8b54a
--- /dev/null
+++ b/backend/tests/external_dependency_unit/db/test_rotate_encryption_key.py
@@ -0,0 +1,305 @@
+"""Tests for rotate_encryption_key against real Postgres.
+
+Uses real ORM models (Credential, InternetSearchProvider) and the actual
+Postgres database. Discovery is mocked in rotation tests to scope mutations
+to only the test rows — the real _discover_encrypted_columns walk is tested
+separately in TestDiscoverEncryptedColumns.
+
+Requires a running Postgres instance. Run with::
+
+    python -m dotenv -f .vscode/.env run -- pytest tests/external_dependency_unit/db/test_rotate_encryption_key.py
+"""
+
+import json
+from collections.abc import Generator
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy import LargeBinary
+from sqlalchemy import select
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from ee.onyx.utils.encryption import _decrypt_bytes
+from ee.onyx.utils.encryption import _encrypt_string
+from ee.onyx.utils.encryption import _get_trimmed_key
+from onyx.configs.constants import DocumentSource
+from onyx.db.models import Credential
+from onyx.db.models import EncryptedJson
+from onyx.db.models import EncryptedString
+from onyx.db.models import InternetSearchProvider
+from onyx.db.rotate_encryption_key import _discover_encrypted_columns
+from onyx.db.rotate_encryption_key import rotate_encryption_key
+from onyx.utils.variable_functionality import fetch_versioned_implementation
+from onyx.utils.variable_functionality import global_version
+
+EE_MODULE = "ee.onyx.utils.encryption"
+ROTATE_MODULE = "onyx.db.rotate_encryption_key"
+
+OLD_KEY = "o" * 16
+NEW_KEY = "n" * 16
+
+
+@pytest.fixture(autouse=True)
+def _enable_ee() -> Generator[None, None, None]:
+    prev = global_version._is_ee
+    global_version.set_ee()
+    fetch_versioned_implementation.cache_clear()
+    yield
+    global_version._is_ee = prev
+    fetch_versioned_implementation.cache_clear()
+
+
+@pytest.fixture(autouse=True)
+def _clear_key_cache() -> None:
+    _get_trimmed_key.cache_clear()
+
+
+def _raw_credential_bytes(db_session: Session, credential_id: int) -> bytes | None:
+    """Read raw bytes from credential_json, bypassing the TypeDecorator."""
+    col = Credential.__table__.c.credential_json
+    stmt = select(col.cast(LargeBinary)).where(
+        Credential.__table__.c.id == credential_id
+    )
+    return db_session.execute(stmt).scalar()
+
+
+def _raw_isp_bytes(db_session: Session, isp_id: int) -> bytes | None:
+    """Read raw bytes from InternetSearchProvider.api_key."""
+    col = InternetSearchProvider.__table__.c.api_key
+    stmt = select(col.cast(LargeBinary)).where(
+        InternetSearchProvider.__table__.c.id == isp_id
+    )
+    return db_session.execute(stmt).scalar()
+
+
+class TestDiscoverEncryptedColumns:
+    """Verify _discover_encrypted_columns finds real production models."""
+
+    def test_discovers_credential_json(self) -> None:
+        results = _discover_encrypted_columns()
+        found = {
+            (model_cls.__tablename__, col_name, is_json)  # type: ignore[attr-defined]
+            for model_cls, col_name, _, is_json in results
+        }
+        assert ("credential", "credential_json", True) in found
+
+    def test_discovers_internet_search_provider_api_key(self) -> None:
+        results = _discover_encrypted_columns()
+        found = {
+            (model_cls.__tablename__, col_name, is_json)  # type: ignore[attr-defined]
+            for model_cls, col_name, _, is_json in results
+        }
+        assert ("internet_search_provider", "api_key", False) in found
+
+    def test_all_encrypted_string_columns_are_not_json(self) -> None:
+        results = _discover_encrypted_columns()
+        for model_cls, col_name, _, is_json in results:
+            col = getattr(model_cls, col_name).property.columns[0]
+            if isinstance(col.type, EncryptedString):
+                assert not is_json, (
+                    f"{model_cls.__tablename__}.{col_name} is EncryptedString "  # type: ignore[attr-defined]
+                    f"but is_json={is_json}"
+                )
+
+    def test_all_encrypted_json_columns_are_json(self) -> None:
+        results = _discover_encrypted_columns()
+        for model_cls, col_name, _, is_json in results:
+            col = getattr(model_cls, col_name).property.columns[0]
+            if isinstance(col.type, EncryptedJson):
+                assert is_json, (
+                    f"{model_cls.__tablename__}.{col_name} is EncryptedJson "  # type: ignore[attr-defined]
+                    f"but is_json={is_json}"
+                )
+
+
+class TestRotateCredential:
+    """Test rotation against the real Credential table (EncryptedJson).
+
+    Discovery is scoped to only the Credential model to avoid mutating
+    other tables in the test database.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _limit_discovery(self) -> Generator[None, None, None]:
+        with patch(
+            f"{ROTATE_MODULE}._discover_encrypted_columns",
+            return_value=[(Credential, "credential_json", ["id"], True)],
+        ):
+            yield
+
+    @pytest.fixture()
+    def credential_id(
+        self, db_session: Session, tenant_context: None  # noqa: ARG002
+    ) -> Generator[int, None, None]:
+        """Insert a Credential row with raw encrypted bytes, clean up after."""
+        config = {"api_key": "sk-test-1234", "endpoint": "https://example.com"}
+        encrypted = _encrypt_string(json.dumps(config), key=OLD_KEY)
+
+        result = db_session.execute(
+            text(
+                "INSERT INTO credential "
+                "(source, credential_json, admin_public, curator_public) "
+                "VALUES (:source, :cred_json, true, false) "
+                "RETURNING id"
+            ),
+            {"source": DocumentSource.INGESTION_API.value, "cred_json": encrypted},
+        )
+        cred_id = result.scalar_one()
+        db_session.commit()
+
+        yield cred_id
+
+        db_session.execute(
+            text("DELETE FROM credential WHERE id = :id"), {"id": cred_id}
+        )
+        db_session.commit()
+
+    def test_rotates_credential_json(
+        self, db_session: Session, credential_id: int
+    ) -> None:
+        with (
+            patch(f"{ROTATE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+            patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+        ):
+            totals = rotate_encryption_key(db_session, old_key=OLD_KEY)
+
+        assert totals.get("credential.credential_json", 0) >= 1
+
+        raw = _raw_credential_bytes(db_session, credential_id)
+        assert raw is not None
+        decrypted = json.loads(_decrypt_bytes(raw, key=NEW_KEY))
+        assert decrypted["api_key"] == "sk-test-1234"
+        assert decrypted["endpoint"] == "https://example.com"
+
+    def test_skips_already_rotated(
+        self, db_session: Session, credential_id: int
+    ) -> None:
+        with (
+            patch(f"{ROTATE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+            patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+        ):
+            rotate_encryption_key(db_session, old_key=OLD_KEY)
+            _ = rotate_encryption_key(db_session, old_key=OLD_KEY)
+
+        raw = _raw_credential_bytes(db_session, credential_id)
+        assert raw is not None
+        decrypted = json.loads(_decrypt_bytes(raw, key=NEW_KEY))
+        assert decrypted["api_key"] == "sk-test-1234"
+
+    def test_dry_run_does_not_modify(
+        self, db_session: Session, credential_id: int
+    ) -> None:
+        original = _raw_credential_bytes(db_session, credential_id)
+
+        with (
+            patch(f"{ROTATE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+            patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+        ):
+            totals = rotate_encryption_key(db_session, old_key=OLD_KEY, dry_run=True)
+
+        assert totals.get("credential.credential_json", 0) >= 1
+
+        raw_after = _raw_credential_bytes(db_session, credential_id)
+        assert raw_after == original
+
+
+class TestRotateInternetSearchProvider:
+    """Test rotation against the real InternetSearchProvider table (EncryptedString).
+
+    Discovery is scoped to only the InternetSearchProvider model to avoid
+    mutating other tables in the test database.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _limit_discovery(self) -> Generator[None, None, None]:
+        with patch(
+            f"{ROTATE_MODULE}._discover_encrypted_columns",
+            return_value=[
+                (InternetSearchProvider, "api_key", ["id"], False),
+            ],
+        ):
+            yield
+
+    @pytest.fixture()
+    def isp_id(
+        self, db_session: Session, tenant_context: None  # noqa: ARG002
+    ) -> Generator[int, None, None]:
+        """Insert an InternetSearchProvider row with raw encrypted bytes."""
+        encrypted = _encrypt_string("sk-secret-api-key", key=OLD_KEY)
+
+        result = db_session.execute(
+            text(
+                "INSERT INTO internet_search_provider "
+                "(name, provider_type, api_key, is_active) "
+                "VALUES (:name, :ptype, :api_key, false) "
+                "RETURNING id"
+            ),
+            {
+                "name": f"test-rotation-{id(self)}",
+                "ptype": "test",
+                "api_key": encrypted,
+            },
+        )
+        isp_id = result.scalar_one()
+        db_session.commit()
+
+        yield isp_id
+
+        db_session.execute(
+            text("DELETE FROM internet_search_provider WHERE id = :id"),
+            {"id": isp_id},
+        )
+        db_session.commit()
+
+    def test_rotates_api_key(self, db_session: Session, isp_id: int) -> None:
+        with (
+            patch(f"{ROTATE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+            patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+        ):
+            totals = rotate_encryption_key(db_session, old_key=OLD_KEY)
+
+        assert totals.get("internet_search_provider.api_key", 0) >= 1
+
+        raw = _raw_isp_bytes(db_session, isp_id)
+        assert raw is not None
+        assert _decrypt_bytes(raw, key=NEW_KEY) == "sk-secret-api-key"
+
+    def test_rotates_from_unencrypted(
+        self, db_session: Session, tenant_context: None  # noqa: ARG002
+    ) -> None:
+        """Test rotating data that was stored without any encryption key."""
+        result = db_session.execute(
+            text(
+                "INSERT INTO internet_search_provider "
+                "(name, provider_type, api_key, is_active) "
+                "VALUES (:name, :ptype, :api_key, false) "
+                "RETURNING id"
+            ),
+            {
+                "name": f"test-raw-{id(self)}",
+                "ptype": "test",
+                "api_key": b"raw-api-key",
+            },
+        )
+        isp_id = result.scalar_one()
+        db_session.commit()
+
+        try:
+            with (
+                patch(f"{ROTATE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+                patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", NEW_KEY),
+            ):
+                totals = rotate_encryption_key(db_session, old_key=None)
+
+            assert totals.get("internet_search_provider.api_key", 0) >= 1
+
+            raw = _raw_isp_bytes(db_session, isp_id)
+            assert raw is not None
+            assert _decrypt_bytes(raw, key=NEW_KEY) == "raw-api-key"
+        finally:
+            db_session.execute(
+                text("DELETE FROM internet_search_provider WHERE id = :id"),
+                {"id": isp_id},
+            )
+            db_session.commit()
diff --git a/backend/tests/unit/ee/onyx/utils/test_encryption.py b/backend/tests/unit/ee/onyx/utils/test_encryption.py
new file mode 100644
index 00000000000..1e087907df8
--- /dev/null
+++ b/backend/tests/unit/ee/onyx/utils/test_encryption.py
@@ -0,0 +1,165 @@
+"""Tests for EE AES-CBC encryption/decryption with explicit key support.
+
+With EE mode enabled (via conftest), fetch_versioned_implementation resolves
+to the EE implementations, so no patching of the MIT layer is needed.
+"""
+
+from unittest.mock import patch
+
+import pytest
+
+from ee.onyx.utils.encryption import _decrypt_bytes
+from ee.onyx.utils.encryption import _encrypt_string
+from ee.onyx.utils.encryption import _get_trimmed_key
+from ee.onyx.utils.encryption import decrypt_bytes_to_string
+from ee.onyx.utils.encryption import encrypt_string_to_bytes
+
+EE_MODULE = "ee.onyx.utils.encryption"
+
+# Keys must be exactly 16, 24, or 32 bytes for AES
+KEY_16 = "a" * 16
+KEY_16_ALT = "b" * 16
+KEY_24 = "d" * 24
+KEY_32 = "c" * 32
+
+
+@pytest.fixture(autouse=True)
+def _clear_key_cache() -> None:
+    _get_trimmed_key.cache_clear()
+
+
+class TestEncryptDecryptRoundTrip:
+    def test_roundtrip_with_env_key(self) -> None:
+        with patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", KEY_16):
+            encrypted = _encrypt_string("hello world")
+            assert encrypted != b"hello world"
+            assert _decrypt_bytes(encrypted) == "hello world"
+
+    def test_roundtrip_with_explicit_key(self) -> None:
+        encrypted = _encrypt_string("secret data", key=KEY_32)
+        assert encrypted != b"secret data"
+        assert _decrypt_bytes(encrypted, key=KEY_32) == "secret data"
+
+    def test_roundtrip_no_key(self) -> None:
+        """Without any key, data is raw-encoded (no encryption)."""
+        with patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", ""):
+            encrypted = _encrypt_string("plain text")
+            assert encrypted == b"plain text"
+            assert _decrypt_bytes(encrypted) == "plain text"
+
+    def test_explicit_key_overrides_env(self) -> None:
+        with patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", KEY_16):
+            encrypted = _encrypt_string("data", key=KEY_16_ALT)
+            with pytest.raises(ValueError):
+                _decrypt_bytes(encrypted, key=KEY_16)
+            assert _decrypt_bytes(encrypted, key=KEY_16_ALT) == "data"
+
+    def test_different_encryptions_produce_different_bytes(self) -> None:
+        """Each encryption uses a random IV, so results differ."""
+        a = _encrypt_string("same", key=KEY_16)
+        b = _encrypt_string("same", key=KEY_16)
+        assert a != b
+
+    def test_roundtrip_empty_string(self) -> None:
+        encrypted = _encrypt_string("", key=KEY_16)
+        assert encrypted != b""
+        assert _decrypt_bytes(encrypted, key=KEY_16) == ""
+
+    def test_roundtrip_unicode(self) -> None:
+        text = "日本語テスト 🔐 émojis"
+        encrypted = _encrypt_string(text, key=KEY_16)
+        assert _decrypt_bytes(encrypted, key=KEY_16) == text
+
+
+class TestDecryptFallbackBehavior:
+    def test_wrong_env_key_falls_back_to_raw_decode(self) -> None:
+        """Default key path: AES fails on non-AES data → fallback to raw decode."""
+        raw = "readable text".encode()
+        with patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", KEY_16):
+            assert _decrypt_bytes(raw) == "readable text"
+
+    def test_explicit_wrong_key_raises(self) -> None:
+        """Explicit key path: AES fails → raises, no fallback."""
+        encrypted = _encrypt_string("secret", key=KEY_16)
+        with pytest.raises(ValueError):
+            _decrypt_bytes(encrypted, key=KEY_16_ALT)
+
+    def test_explicit_none_key_with_no_env(self) -> None:
+        """key=None with empty env → raw decode."""
+        with patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", ""):
+            assert _decrypt_bytes(b"hello", key=None) == "hello"
+
+    def test_explicit_empty_string_key(self) -> None:
+        """key='' means no encryption."""
+        encrypted = _encrypt_string("test", key="")
+        assert encrypted == b"test"
+        assert _decrypt_bytes(encrypted, key="") == "test"
+
+
+class TestKeyValidation:
+    def test_key_too_short_raises(self) -> None:
+        with pytest.raises(RuntimeError, match="too short"):
+            _encrypt_string("data", key="short")
+
+    def test_16_byte_key(self) -> None:
+        encrypted = _encrypt_string("data", key=KEY_16)
+        assert _decrypt_bytes(encrypted, key=KEY_16) == "data"
+
+    def test_24_byte_key(self) -> None:
+        encrypted = _encrypt_string("data", key=KEY_24)
+        assert _decrypt_bytes(encrypted, key=KEY_24) == "data"
+
+    def test_32_byte_key(self) -> None:
+        encrypted = _encrypt_string("data", key=KEY_32)
+        assert _decrypt_bytes(encrypted, key=KEY_32) == "data"
+
+    def test_long_key_truncated_to_32(self) -> None:
+        """Keys longer than 32 bytes are truncated to 32."""
+        long_key = "e" * 64
+        encrypted = _encrypt_string("data", key=long_key)
+        assert _decrypt_bytes(encrypted, key=long_key) == "data"
+
+    def test_20_byte_key_trimmed_to_16(self) -> None:
+        """A 20-byte key is trimmed to the largest valid AES size that fits (16)."""
+        key_20 = "f" * 20
+        encrypted = _encrypt_string("data", key=key_20)
+        assert _decrypt_bytes(encrypted, key=key_20) == "data"
+
+        # Verify it was trimmed to 16 by checking that the first 16 bytes
+        # of the key can also decrypt it
+        key_16_same_prefix = "f" * 16
+        assert _decrypt_bytes(encrypted, key=key_16_same_prefix) == "data"
+
+    def test_25_byte_key_trimmed_to_24(self) -> None:
+        """A 25-byte key is trimmed to the largest valid AES size that fits (24)."""
+        key_25 = "g" * 25
+        encrypted = _encrypt_string("data", key=key_25)
+        assert _decrypt_bytes(encrypted, key=key_25) == "data"
+
+        key_24_same_prefix = "g" * 24
+        assert _decrypt_bytes(encrypted, key=key_24_same_prefix) == "data"
+
+    def test_30_byte_key_trimmed_to_24(self) -> None:
+        """A 30-byte key is trimmed to the largest valid AES size that fits (24)."""
+        key_30 = "h" * 30
+        encrypted = _encrypt_string("data", key=key_30)
+        assert _decrypt_bytes(encrypted, key=key_30) == "data"
+
+        key_24_same_prefix = "h" * 24
+        assert _decrypt_bytes(encrypted, key=key_24_same_prefix) == "data"
+
+
+class TestWrapperFunctions:
+    """Test encrypt_string_to_bytes / decrypt_bytes_to_string pass key through.
+
+    With EE mode enabled, the wrappers resolve to EE implementations automatically.
+    """
+
+    def test_wrapper_passes_key(self) -> None:
+        encrypted = encrypt_string_to_bytes("payload", key=KEY_16)
+        assert decrypt_bytes_to_string(encrypted, key=KEY_16) == "payload"
+
+    def test_wrapper_no_key_uses_env(self) -> None:
+        with patch(f"{EE_MODULE}.ENCRYPTION_KEY_SECRET", KEY_32):
+            encrypted = encrypt_string_to_bytes("payload")
+            assert decrypt_bytes_to_string(encrypted) == "payload"

From 9aad4077f10ecc3fd0b5e4a0e980bfd48143ad91 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Sat, 7 Mar 2026 01:02:39 -0800
Subject: [PATCH 171/267] feat: Tool call arg streaming (#9095)

---
 backend/onyx/chat/llm_step.py                 |  10 +
 backend/onyx/chat/tool_call_args_streaming.py |  77 +++
 .../server/query_and_chat/streaming_models.py |  11 +
 backend/onyx/tools/built_in_tools.py          |  20 +
 backend/onyx/tools/interface.py               |   4 +
 .../python/python_tool.py                     |   5 +
 .../tools/test_python_tool.py                 |  12 +-
 .../chat/test_argument_delta_streaming.py     | 630 ++++++++++++++++++
 .../renderMessageComponent.tsx                |  11 +-
 .../timeline/hooks/packetProcessor.ts         |  16 +-
 .../timeline/packetHelpers.ts                 |  37 +-
 .../renderers/code/PythonToolRenderer.tsx     |  42 +-
 web/src/app/app/services/packetUtils.ts       |   1 +
 web/src/app/app/services/streamingModels.ts   |  15 +
 14 files changed, 871 insertions(+), 20 deletions(-)
 create mode 100644 backend/onyx/chat/tool_call_args_streaming.py
 create mode 100644 backend/tests/unit/onyx/chat/test_argument_delta_streaming.py

diff --git a/backend/onyx/chat/llm_step.py b/backend/onyx/chat/llm_step.py
index 6b48fabc8f3..ab151b66da3 100644
--- a/backend/onyx/chat/llm_step.py
+++ b/backend/onyx/chat/llm_step.py
@@ -15,6 +15,7 @@
 from onyx.chat.emitter import Emitter
 from onyx.chat.models import ChatMessageSimple
 from onyx.chat.models import LlmStepResult
+from onyx.chat.tool_call_args_streaming import maybe_emit_argument_delta
 from onyx.configs.app_configs import LOG_ONYX_MODEL_INTERACTIONS
 from onyx.configs.app_configs import PROMPT_CACHE_CHAT_HISTORY
 from onyx.configs.constants import MessageType
@@ -54,6 +55,7 @@
 from onyx.tools.models import ToolCallKickoff
 from onyx.tracing.framework.create import generation_span
 from onyx.utils.b64 import get_image_type_from_bytes
+from onyx.utils.jsonriver import Parser
 from onyx.utils.logger import setup_logger
 from onyx.utils.postgres_sanitization import sanitize_string
 from onyx.utils.text_processing import find_all_json_objects
@@ -1009,6 +1011,7 @@ def _current_placement() -> Placement:
         )
 
     id_to_tool_call_map: dict[int, dict[str, Any]] = {}
+    arg_parsers: dict[int, Parser] = {}
     reasoning_start = False
     answer_start = False
     accumulated_reasoning = ""
@@ -1215,7 +1218,14 @@ def _emit_content_chunk(content_chunk: str) -> Generator[Packet, None, None]:
                 yield from _close_reasoning_if_active()
 
                 for tool_call_delta in delta.tool_calls:
+                    # maybe_emit depends and update being called first and attaching the delta
                     _update_tool_call_with_delta(id_to_tool_call_map, tool_call_delta)
+                    yield from maybe_emit_argument_delta(
+                        tool_calls_in_progress=id_to_tool_call_map,
+                        tool_call_delta=tool_call_delta,
+                        placement=_current_placement(),
+                        parsers=arg_parsers,
+                    )
 
         # Flush any tail text buffered while checking for split "<function_calls" markers.
         filtered_content_tail = xml_tool_call_content_filter.flush()
diff --git a/backend/onyx/chat/tool_call_args_streaming.py b/backend/onyx/chat/tool_call_args_streaming.py
new file mode 100644
index 00000000000..2520042bed7
--- /dev/null
+++ b/backend/onyx/chat/tool_call_args_streaming.py
@@ -0,0 +1,77 @@
+from collections.abc import Generator
+from collections.abc import Mapping
+from typing import Any
+from typing import Type
+
+from onyx.llm.model_response import ChatCompletionDeltaToolCall
+from onyx.server.query_and_chat.placement import Placement
+from onyx.server.query_and_chat.streaming_models import Packet
+from onyx.server.query_and_chat.streaming_models import ToolCallArgumentDelta
+from onyx.tools.built_in_tools import TOOL_NAME_TO_CLASS
+from onyx.tools.interface import Tool
+from onyx.utils.jsonriver import Parser
+
+
+def _get_tool_class(
+    tool_calls_in_progress: Mapping[int, Mapping[str, Any]],
+    tool_call_delta: ChatCompletionDeltaToolCall,
+) -> Type[Tool] | None:
+    """Look up the Tool subclass for a streaming tool call delta."""
+    tool_name = tool_calls_in_progress.get(tool_call_delta.index, {}).get("name")
+    if not tool_name:
+        return None
+    return TOOL_NAME_TO_CLASS.get(tool_name)
+
+
+def maybe_emit_argument_delta(
+    tool_calls_in_progress: Mapping[int, Mapping[str, Any]],
+    tool_call_delta: ChatCompletionDeltaToolCall,
+    placement: Placement,
+    parsers: dict[int, Parser],
+) -> Generator[Packet, None, None]:
+    """Emit decoded tool-call argument deltas to the frontend.
+
+    Uses a ``jsonriver.Parser`` per tool-call index to incrementally parse
+    the JSON argument string and extract only the newly-appended content
+    for each string-valued argument.
+
+    NOTE: Non-string arguments (numbers, booleans, null, arrays, objects)
+    are skipped — they are available in the final tool-call kickoff packet.
+
+    ``parsers`` is a mutable dict keyed by tool-call index. A new
+    ``Parser`` is created automatically for each new index.
+    """
+    tool_cls = _get_tool_class(tool_calls_in_progress, tool_call_delta)
+    if not tool_cls or not tool_cls.should_emit_argument_deltas():
+        return
+
+    fn = tool_call_delta.function
+    delta_fragment = fn.arguments if fn else None
+    if not delta_fragment:
+        return
+
+    idx = tool_call_delta.index
+    if idx not in parsers:
+        parsers[idx] = Parser()
+    parser = parsers[idx]
+
+    deltas = parser.feed(delta_fragment)
+
+    argument_deltas: dict[str, str] = {}
+    for delta in deltas:
+        if isinstance(delta, dict):
+            for key, value in delta.items():
+                if isinstance(value, str):
+                    argument_deltas[key] = argument_deltas.get(key, "") + value
+
+    if not argument_deltas:
+        return
+
+    tc_data = tool_calls_in_progress[tool_call_delta.index]
+    yield Packet(
+        placement=placement,
+        obj=ToolCallArgumentDelta(
+            tool_type=tc_data.get("name", ""),
+            argument_deltas=argument_deltas,
+        ),
+    )
diff --git a/backend/onyx/server/query_and_chat/streaming_models.py b/backend/onyx/server/query_and_chat/streaming_models.py
index 4ab5f2eda5a..a1c3b606b5c 100644
--- a/backend/onyx/server/query_and_chat/streaming_models.py
+++ b/backend/onyx/server/query_and_chat/streaming_models.py
@@ -41,6 +41,7 @@ class StreamingType(Enum):
     REASONING_DONE = "reasoning_done"
     CITATION_INFO = "citation_info"
     TOOL_CALL_DEBUG = "tool_call_debug"
+    TOOL_CALL_ARGUMENT_DELTA = "tool_call_argument_delta"
 
     MEMORY_TOOL_START = "memory_tool_start"
     MEMORY_TOOL_DELTA = "memory_tool_delta"
@@ -259,6 +260,15 @@ class CustomToolDelta(BaseObj):
     file_ids: list[str] | None = None
 
 
+class ToolCallArgumentDelta(BaseObj):
+    type: Literal["tool_call_argument_delta"] = (
+        StreamingType.TOOL_CALL_ARGUMENT_DELTA.value
+    )
+
+    tool_type: str
+    argument_deltas: dict[str, Any]
+
+
 ################################################
 # File Reader Packets
 ################################################
@@ -379,6 +389,7 @@ class IntermediateReportCitedDocs(BaseObj):
     # Citation Packets
     CitationInfo,
     ToolCallDebug,
+    ToolCallArgumentDelta,
     # Deep Research Packets
     DeepResearchPlanStart,
     DeepResearchPlanDelta,
diff --git a/backend/onyx/tools/built_in_tools.py b/backend/onyx/tools/built_in_tools.py
index ca7bcbfa669..bf1ba9725a1 100644
--- a/backend/onyx/tools/built_in_tools.py
+++ b/backend/onyx/tools/built_in_tools.py
@@ -56,3 +56,23 @@ def get_built_in_tool_ids() -> list[str]:
 
 def get_built_in_tool_by_id(in_code_tool_id: str) -> Type[BUILT_IN_TOOL_TYPES]:
     return BUILT_IN_TOOL_MAP[in_code_tool_id]
+
+
+def _build_tool_name_to_class() -> dict[str, Type[BUILT_IN_TOOL_TYPES]]:
+    """Build a mapping from LLM-facing tool name to tool class."""
+    result: dict[str, Type[BUILT_IN_TOOL_TYPES]] = {}
+    for cls in BUILT_IN_TOOL_MAP.values():
+        name_attr = cls.__dict__.get("name")
+        if isinstance(name_attr, property) and name_attr.fget is not None:
+            tool_name = name_attr.fget(cls)
+        elif isinstance(name_attr, str):
+            tool_name = name_attr
+        else:
+            raise ValueError(
+                f"Built-in tool {cls.__name__} must define a valid LLM-facing tool name"
+            )
+        result[tool_name] = cls
+    return result
+
+
+TOOL_NAME_TO_CLASS: dict[str, Type[BUILT_IN_TOOL_TYPES]] = _build_tool_name_to_class()
diff --git a/backend/onyx/tools/interface.py b/backend/onyx/tools/interface.py
index 924833e65ce..05bcb005e90 100644
--- a/backend/onyx/tools/interface.py
+++ b/backend/onyx/tools/interface.py
@@ -92,3 +92,7 @@ def run(
         **llm_kwargs: Any,
     ) -> ToolResponse:
         raise NotImplementedError
+
+    @classmethod
+    def should_emit_argument_deltas(cls) -> bool:
+        return False
diff --git a/backend/onyx/tools/tool_implementations/python/python_tool.py b/backend/onyx/tools/tool_implementations/python/python_tool.py
index 21268975fb9..8be2fc1817f 100644
--- a/backend/onyx/tools/tool_implementations/python/python_tool.py
+++ b/backend/onyx/tools/tool_implementations/python/python_tool.py
@@ -376,3 +376,8 @@ def run(
                     rich_response=None,
                     llm_facing_response=llm_response,
                 )
+
+    @classmethod
+    @override
+    def should_emit_argument_deltas(cls) -> bool:
+        return True
diff --git a/backend/tests/external_dependency_unit/tools/test_python_tool.py b/backend/tests/external_dependency_unit/tools/test_python_tool.py
index 35119a7469f..0f03c07e358 100644
--- a/backend/tests/external_dependency_unit/tools/test_python_tool.py
+++ b/backend/tests/external_dependency_unit/tools/test_python_tool.py
@@ -950,6 +950,7 @@
 from onyx.server.query_and_chat.streaming_models import PythonToolDelta
 from onyx.server.query_and_chat.streaming_models import PythonToolStart
 from onyx.server.query_and_chat.streaming_models import SectionEnd
+from onyx.server.query_and_chat.streaming_models import ToolCallArgumentDelta
 from onyx.tools.tool_implementations.python.python_tool import PythonTool
 from tests.external_dependency_unit.answer.stream_test_builder import StreamTestBuilder
 from tests.external_dependency_unit.answer.stream_test_utils import create_chat_session
@@ -1294,9 +1295,18 @@ def test_code_interpreter_replay_packets_include_code_and_output(
             ).expect(
                 Packet(
                     placement=create_placement(0),
-                    obj=PythonToolStart(code=code),
+                    obj=ToolCallArgumentDelta(
+                        tool_type="python",
+                        argument_deltas={"code": code},
+                    ),
                 ),
                 forward=2,
+            ).expect(
+                Packet(
+                    placement=create_placement(0),
+                    obj=PythonToolStart(code=code),
+                ),
+                forward=False,
             ).expect(
                 Packet(
                     placement=create_placement(0),
diff --git a/backend/tests/unit/onyx/chat/test_argument_delta_streaming.py b/backend/tests/unit/onyx/chat/test_argument_delta_streaming.py
new file mode 100644
index 00000000000..e9233f350c1
--- /dev/null
+++ b/backend/tests/unit/onyx/chat/test_argument_delta_streaming.py
@@ -0,0 +1,630 @@
+from typing import Any
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+from onyx.chat.tool_call_args_streaming import maybe_emit_argument_delta
+from onyx.server.query_and_chat.placement import Placement
+from onyx.server.query_and_chat.streaming_models import ToolCallArgumentDelta
+from onyx.utils.jsonriver import Parser
+
+
+def _make_tool_call_delta(
+    index: int = 0,
+    name: str | None = None,
+    arguments: str | None = None,
+    function_is_none: bool = False,
+) -> MagicMock:
+    """Create a mock tool_call_delta matching the LiteLLM streaming shape."""
+    delta = MagicMock()
+    delta.index = index
+    if function_is_none:
+        delta.function = None
+    else:
+        delta.function = MagicMock()
+        delta.function.name = name
+        delta.function.arguments = arguments
+    return delta
+
+
+def _make_placement() -> Placement:
+    return Placement(turn_index=0, tab_index=0)
+
+
+def _mock_tool_class(emit: bool = True) -> MagicMock:
+    cls = MagicMock()
+    cls.should_emit_argument_deltas.return_value = emit
+    return cls
+
+
+def _collect(
+    tc_map: dict[int, dict[str, Any]],
+    delta: MagicMock,
+    placement: Placement | None = None,
+    parsers: dict[int, Parser] | None = None,
+) -> list[Any]:
+    """Run maybe_emit_argument_delta and return the yielded packets."""
+    return list(
+        maybe_emit_argument_delta(
+            tc_map,
+            delta,
+            placement or _make_placement(),
+            parsers if parsers is not None else {},
+        )
+    )
+
+
+def _stream_fragments(
+    fragments: list[str],
+    tc_map: dict[int, dict[str, Any]],
+    placement: Placement | None = None,
+) -> list[str]:
+    """Feed fragments into maybe_emit_argument_delta one by one, returning
+    all emitted content values concatenated per-key as a flat list."""
+    pl = placement or _make_placement()
+    parsers: dict[int, Parser] = {}
+    emitted: list[str] = []
+    for frag in fragments:
+        tc_map[0]["arguments"] += frag
+        delta = _make_tool_call_delta(arguments=frag)
+        for packet in maybe_emit_argument_delta(tc_map, delta, pl, parsers=parsers):
+            obj = packet.obj
+            assert isinstance(obj, ToolCallArgumentDelta)
+            for value in obj.argument_deltas.values():
+                emitted.append(value)
+    return emitted
+
+
+class TestMaybeEmitArgumentDeltaGuards:
+    """Tests for conditions that cause no packet to be emitted."""
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_no_emission_when_tool_does_not_opt_in(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        """Tools that return False from should_emit_argument_deltas emit nothing."""
+        mock_get_tool.return_value = _mock_tool_class(emit=False)
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": '{"code": "x'}
+        }
+        assert _collect(tc_map, _make_tool_call_delta(arguments="x")) == []
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_no_emission_when_tool_class_unknown(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        mock_get_tool.return_value = None
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "unknown", "arguments": '{"code": "x'}
+        }
+        assert _collect(tc_map, _make_tool_call_delta(arguments="x")) == []
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_no_emission_when_no_argument_fragment(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": '{"code": "x'}
+        }
+        assert _collect(tc_map, _make_tool_call_delta(arguments=None)) == []
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_no_emission_when_key_value_not_started(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        """Key exists in JSON but its string value hasn't begun yet."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": '{"code":'}
+        }
+        assert _collect(tc_map, _make_tool_call_delta(arguments=":")) == []
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_no_emission_before_any_key(self, mock_get_tool: MagicMock) -> None:
+        """Only the opening brace has arrived — no key to stream yet."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": "{"}
+        }
+        assert _collect(tc_map, _make_tool_call_delta(arguments="{")) == []
+
+
+class TestMaybeEmitArgumentDeltaBasic:
+    """Tests for correct packet content and incremental emission."""
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_emits_packet_with_correct_fields(self, mock_get_tool: MagicMock) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "', "print(1)", '"}']
+
+        pl = _make_placement()
+        parsers: dict[int, Parser] = {}
+        all_packets = []
+        for frag in fragments:
+            tc_map[0]["arguments"] += frag
+            packets = _collect(
+                tc_map, _make_tool_call_delta(arguments=frag), pl, parsers
+            )
+            all_packets.extend(packets)
+
+        assert len(all_packets) >= 1
+        # Verify packet structure
+        obj = all_packets[0].obj
+        assert isinstance(obj, ToolCallArgumentDelta)
+        assert obj.tool_type == "python"
+        # All emitted content should reconstruct the value
+        full_code = ""
+        for p in all_packets:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            if "code" in p.obj.argument_deltas:
+                full_code += p.obj.argument_deltas["code"]
+        assert full_code == "print(1)"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_emits_only_new_content_on_subsequent_call(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        """After a first emission, subsequent calls emit only the diff."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        parsers: dict[int, Parser] = {}
+        pl = _make_placement()
+
+        # First fragment opens the string
+        tc_map[0]["arguments"] = '{"code": "abc'
+        packets_1 = _collect(
+            tc_map, _make_tool_call_delta(arguments='{"code": "abc'), pl, parsers
+        )
+        code_1 = ""
+        for p in packets_1:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            code_1 += p.obj.argument_deltas.get("code", "")
+        assert code_1 == "abc"
+
+        # Second fragment appends more
+        tc_map[0]["arguments"] = '{"code": "abcdef'
+        packets_2 = _collect(
+            tc_map, _make_tool_call_delta(arguments="def"), pl, parsers
+        )
+        code_2 = ""
+        for p in packets_2:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            code_2 += p.obj.argument_deltas.get("code", "")
+        assert code_2 == "def"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_handles_multiple_keys_sequentially(self, mock_get_tool: MagicMock) -> None:
+        """When a second key starts, emissions switch to that key."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "x',
+            '", "output": "hello',
+            '"}',
+        ]
+
+        emitted = _stream_fragments(fragments, tc_map)
+        full = "".join(emitted)
+        assert "x" in full
+        assert "hello" in full
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_delta_spans_key_boundary(self, mock_get_tool: MagicMock) -> None:
+        """A single delta contains the end of one value and the start of the next key."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "x',
+            'y", "lang": "py',
+            '"}',
+        ]
+
+        emitted = _stream_fragments(fragments, tc_map)
+        full = "".join(emitted)
+        assert "xy" in full
+        assert "py" in full
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_empty_value_emits_nothing(self, mock_get_tool: MagicMock) -> None:
+        """An empty string value has nothing to emit."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        # Opening quote just arrived, value is empty
+        tc_map[0]["arguments"] = '{"code": "'
+        packets = _collect(tc_map, _make_tool_call_delta(arguments='{"code": "'))
+        # No string content yet, so either no packet or empty deltas
+        for p in packets:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            assert p.obj.argument_deltas.get("code", "") == ""
+
+
+class TestMaybeEmitArgumentDeltaDecoding:
+    """Tests verifying that JSON escape sequences are properly decoded."""
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_decodes_newlines(self, mock_get_tool: MagicMock) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "line1\\nline2"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == "line1\nline2"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_decodes_tabs(self, mock_get_tool: MagicMock) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "\\tindented"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == "\tindented"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_decodes_escaped_quotes(self, mock_get_tool: MagicMock) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "say \\"hi\\""}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == 'say "hi"'
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_decodes_escaped_backslashes(self, mock_get_tool: MagicMock) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "path\\\\dir"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == "path\\dir"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_decodes_unicode_escape(self, mock_get_tool: MagicMock) -> None:
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "\\u0041"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == "A"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_incomplete_escape_at_end_decoded_on_next_chunk(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        """A trailing backslash (incomplete escape) is completed in the next chunk."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "hello\\', 'n"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == "hello\n"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_incomplete_unicode_escape_completed_on_next_chunk(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        """A partial \\uXX sequence is completed in the next chunk."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"code": "hello\\u00', '41"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        assert "".join(emitted) == "helloA"
+
+
+class TestArgumentDeltaStreamingE2E:
+    """Simulates realistic sequences of LLM argument deltas to verify
+    the full pipeline produces correct decoded output."""
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_realistic_python_code_streaming(self, mock_get_tool: MagicMock) -> None:
+        """Streams: {"code": "print('hello')\\nprint('world')"}"""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"',
+            "code",
+            '": "',
+            "print(",
+            "'hello')",
+            "\\n",
+            "print(",
+            "'world')",
+            '"}',
+        ]
+
+        full = "".join(_stream_fragments(fragments, tc_map))
+        assert full == "print('hello')\nprint('world')"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_streaming_with_tabs_and_newlines(self, mock_get_tool: MagicMock) -> None:
+        """Streams code with tabs and newlines."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "',
+            "if True:",
+            "\\n",
+            "\\t",
+            "pass",
+            '"}',
+        ]
+
+        full = "".join(_stream_fragments(fragments, tc_map))
+        assert full == "if True:\n\tpass"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_split_escape_sequence(self, mock_get_tool: MagicMock) -> None:
+        """An escape sequence split across two fragments (backslash in one,
+        'n' in the next) should still decode correctly."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "hello',
+            "\\",
+            "n",
+            'world"}',
+        ]
+
+        full = "".join(_stream_fragments(fragments, tc_map))
+        assert full == "hello\nworld"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_multiple_newlines_and_indentation(self, mock_get_tool: MagicMock) -> None:
+        """Streams a multi-line function with multiple escape sequences."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "',
+            "def foo():",
+            "\\n",
+            "\\t",
+            "x = 1",
+            "\\n",
+            "\\t",
+            "return x",
+            '"}',
+        ]
+
+        full = "".join(_stream_fragments(fragments, tc_map))
+        assert full == "def foo():\n\tx = 1\n\treturn x"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_two_keys_streamed_sequentially(self, mock_get_tool: MagicMock) -> None:
+        """Streams code first, then a second key (language) — both decoded."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "',
+            "x = 1",
+            '", "language": "',
+            "python",
+            '"}',
+        ]
+
+        emitted = _stream_fragments(fragments, tc_map)
+        # Should have emissions for both keys
+        full = "".join(emitted)
+        assert "x = 1" in full
+        assert "python" in full
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_code_containing_dict_literal(self, mock_get_tool: MagicMock) -> None:
+        """Python code like `x = {"key": "val"}` contains JSON-like patterns.
+        The escaped quotes inside the *outer* JSON value should prevent the
+        inner `"key":` from being mistaken for a top-level JSON key."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        # The LLM sends: {"code": "x = {\"key\": \"val\"}"}
+        # The inner quotes are escaped as \" in the JSON value.
+        fragments = [
+            '{"code": "',
+            "x = {",
+            '\\"key\\"',
+            ": ",
+            '\\"val\\"',
+            "}",
+            '"}',
+        ]
+
+        full = "".join(_stream_fragments(fragments, tc_map))
+        assert full == 'x = {"key": "val"}'
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_code_with_colon_in_value(self, mock_get_tool: MagicMock) -> None:
+        """Colons inside the string value should not confuse key detection."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = [
+            '{"code": "',
+            "url = ",
+            '\\"https://example.com\\"',
+            '"}',
+        ]
+
+        full = "".join(_stream_fragments(fragments, tc_map))
+        assert full == 'url = "https://example.com"'
+
+
+class TestMaybeEmitArgumentDeltaEdgeCases:
+    """Edge cases not covered by the standard test classes."""
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_no_emission_when_function_is_none(self, mock_get_tool: MagicMock) -> None:
+        """Some delta chunks have function=None (e.g. role-only deltas)."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": '{"code": "x'}
+        }
+        delta = _make_tool_call_delta(arguments=None, function_is_none=True)
+        assert _collect(tc_map, delta) == []
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_multiple_concurrent_tool_calls(self, mock_get_tool: MagicMock) -> None:
+        """Two tool calls streaming at different indices in parallel."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""},
+            1: {"id": "tc_2", "name": "python", "arguments": ""},
+        }
+
+        parsers: dict[int, Parser] = {}
+        pl = _make_placement()
+
+        # Feed full JSON to index 0
+        tc_map[0]["arguments"] = '{"code": "aaa"}'
+        packets_0 = _collect(
+            tc_map,
+            _make_tool_call_delta(index=0, arguments='{"code": "aaa"}'),
+            pl,
+            parsers,
+        )
+        code_0 = ""
+        for p in packets_0:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            code_0 += p.obj.argument_deltas.get("code", "")
+        assert code_0 == "aaa"
+
+        # Feed full JSON to index 1
+        tc_map[1]["arguments"] = '{"code": "bbb"}'
+        packets_1 = _collect(
+            tc_map,
+            _make_tool_call_delta(index=1, arguments='{"code": "bbb"}'),
+            pl,
+            parsers,
+        )
+        code_1 = ""
+        for p in packets_1:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            code_1 += p.obj.argument_deltas.get("code", "")
+        assert code_1 == "bbb"
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_delta_with_four_arguments(self, mock_get_tool: MagicMock) -> None:
+        """A single delta contains four complete key-value pairs."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        full = '{"a": "one", "b": "two", "c": "three", "d": "four"}'
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        tc_map[0]["arguments"] = full
+        parsers: dict[int, Parser] = {}
+        packets = _collect(
+            tc_map, _make_tool_call_delta(arguments=full), parsers=parsers
+        )
+
+        # Collect all argument deltas across packets
+        all_deltas: dict[str, str] = {}
+        for p in packets:
+            assert isinstance(p.obj, ToolCallArgumentDelta)
+            for k, v in p.obj.argument_deltas.items():
+                all_deltas[k] = all_deltas.get(k, "") + v
+
+        assert all_deltas == {
+            "a": "one",
+            "b": "two",
+            "c": "three",
+            "d": "four",
+        }
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_delta_on_second_arg_after_first_complete(
+        self, mock_get_tool: MagicMock
+    ) -> None:
+        """First argument is fully complete; delta only adds to the second."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+
+        fragments = [
+            '{"code": "print(1)", "lang": "py',
+            '"}',
+        ]
+
+        emitted = _stream_fragments(fragments, tc_map)
+        full = "".join(emitted)
+        assert "print(1)" in full
+        assert "py" in full
+
+    @patch("onyx.chat.tool_call_args_streaming._get_tool_class")
+    def test_non_string_values_skipped(self, mock_get_tool: MagicMock) -> None:
+        """Non-string values (numbers, booleans, null) are skipped — they are
+        available in the final tool-call kickoff packet. String arguments
+        following them are still emitted."""
+        mock_get_tool.return_value = _mock_tool_class()
+
+        tc_map: dict[int, dict[str, Any]] = {
+            0: {"id": "tc_1", "name": "python", "arguments": ""}
+        }
+        fragments = ['{"timeout": 30, "code": "hello"}']
+
+        emitted = _stream_fragments(fragments, tc_map)
+        full = "".join(emitted)
+        assert full == "hello"
diff --git a/web/src/app/app/message/messageComponents/renderMessageComponent.tsx b/web/src/app/app/message/messageComponents/renderMessageComponent.tsx
index b41576c6efd..8a9cdf6d454 100644
--- a/web/src/app/app/message/messageComponents/renderMessageComponent.tsx
+++ b/web/src/app/app/message/messageComponents/renderMessageComponent.tsx
@@ -1,11 +1,14 @@
 import React, { JSX, memo } from "react";
 import {
   ChatPacket,
+  CODE_INTERPRETER_TOOL_TYPES,
   ImageGenerationToolPacket,
   Packet,
   PacketType,
   ReasoningPacket,
+  SearchToolStart,
   StopReason,
+  ToolCallArgumentDelta,
 } from "../../services/streamingModels";
 import {
   FullChatState,
@@ -26,7 +29,6 @@ import { DeepResearchPlanRenderer } from "./timeline/renderers/deepresearch/Deep
 import { ResearchAgentRenderer } from "./timeline/renderers/deepresearch/ResearchAgentRenderer";
 import { WebSearchToolRenderer } from "./timeline/renderers/search/WebSearchToolRenderer";
 import { InternalSearchToolRenderer } from "./timeline/renderers/search/InternalSearchToolRenderer";
-import { SearchToolStart } from "../../services/streamingModels";
 
 // Different types of chat packets using discriminated unions
 interface GroupedPackets {
@@ -56,7 +58,12 @@ function isImageToolPacket(packet: Packet) {
 }
 
 function isPythonToolPacket(packet: Packet) {
-  return packet.obj.type === PacketType.PYTHON_TOOL_START;
+  return (
+    packet.obj.type === PacketType.PYTHON_TOOL_START ||
+    (packet.obj.type === PacketType.TOOL_CALL_ARGUMENT_DELTA &&
+      (packet.obj as ToolCallArgumentDelta).tool_type ===
+        CODE_INTERPRETER_TOOL_TYPES.PYTHON)
+  );
 }
 
 function isCustomToolPacket(packet: Packet) {
diff --git a/web/src/app/app/message/messageComponents/timeline/hooks/packetProcessor.ts b/web/src/app/app/message/messageComponents/timeline/hooks/packetProcessor.ts
index 72983a723ab..6e7e6684e42 100644
--- a/web/src/app/app/message/messageComponents/timeline/hooks/packetProcessor.ts
+++ b/web/src/app/app/message/messageComponents/timeline/hooks/packetProcessor.ts
@@ -10,6 +10,8 @@ import {
   Stop,
   ImageGenerationToolDelta,
   MessageStart,
+  ToolCallArgumentDelta,
+  CODE_INTERPRETER_TOOL_TYPES,
 } from "@/app/app/services/streamingModels";
 import { CitationMap } from "@/app/app/interfaces";
 import { OnyxDocument } from "@/lib/search/interfaces";
@@ -138,6 +140,7 @@ const CONTENT_PACKET_TYPES_SET = new Set<PacketType>([
   PacketType.SEARCH_TOOL_START,
   PacketType.IMAGE_GENERATION_TOOL_START,
   PacketType.PYTHON_TOOL_START,
+  PacketType.TOOL_CALL_ARGUMENT_DELTA,
   PacketType.CUSTOM_TOOL_START,
   PacketType.FILE_READER_START,
   PacketType.FETCH_TOOL_START,
@@ -149,9 +152,16 @@ const CONTENT_PACKET_TYPES_SET = new Set<PacketType>([
 ]);
 
 function hasContentPackets(packets: Packet[]): boolean {
-  return packets.some((packet) =>
-    CONTENT_PACKET_TYPES_SET.has(packet.obj.type as PacketType)
-  );
+  return packets.some((packet) => {
+    const type = packet.obj.type as PacketType;
+    if (type === PacketType.TOOL_CALL_ARGUMENT_DELTA) {
+      return (
+        (packet.obj as ToolCallArgumentDelta).tool_type ===
+        CODE_INTERPRETER_TOOL_TYPES.PYTHON
+      );
+    }
+    return CONTENT_PACKET_TYPES_SET.has(type);
+  });
 }
 
 /**
diff --git a/web/src/app/app/message/messageComponents/timeline/packetHelpers.ts b/web/src/app/app/message/messageComponents/timeline/packetHelpers.ts
index 96e7d43631c..563487d6369 100644
--- a/web/src/app/app/message/messageComponents/timeline/packetHelpers.ts
+++ b/web/src/app/app/message/messageComponents/timeline/packetHelpers.ts
@@ -1,6 +1,13 @@
-import { Packet, PacketType } from "@/app/app/services/streamingModels";
-
-// Packet types with renderers supporting collapsed streaming mode
+import {
+  CODE_INTERPRETER_TOOL_TYPES,
+  Packet,
+  PacketType,
+  ToolCallArgumentDelta,
+} from "@/app/app/services/streamingModels";
+
+// Packet types with renderers supporting collapsed streaming mode.
+// TOOL_CALL_ARGUMENT_DELTA is intentionally excluded here because it requires
+// a tool_type check — it's handled separately in stepSupportsCollapsedStreaming.
 export const COLLAPSED_STREAMING_PACKET_TYPES = new Set<PacketType>([
   PacketType.SEARCH_TOOL_START,
   PacketType.FETCH_TOOL_START,
@@ -21,7 +28,13 @@ export const isSearchToolPackets = (packets: Packet[]): boolean =>
 
 // Check if packets belong to a python tool
 export const isPythonToolPackets = (packets: Packet[]): boolean =>
-  packets.some((p) => p.obj.type === PacketType.PYTHON_TOOL_START);
+  packets.some(
+    (p) =>
+      p.obj.type === PacketType.PYTHON_TOOL_START ||
+      (p.obj.type === PacketType.TOOL_CALL_ARGUMENT_DELTA &&
+        (p.obj as ToolCallArgumentDelta).tool_type ===
+          CODE_INTERPRETER_TOOL_TYPES.PYTHON)
+  );
 
 // Check if packets belong to reasoning
 export const isReasoningPackets = (packets: Packet[]): boolean =>
@@ -29,8 +42,12 @@ export const isReasoningPackets = (packets: Packet[]): boolean =>
 
 // Check if step supports collapsed streaming rendering mode
 export const stepSupportsCollapsedStreaming = (packets: Packet[]): boolean =>
-  packets.some((p) =>
-    COLLAPSED_STREAMING_PACKET_TYPES.has(p.obj.type as PacketType)
+  packets.some(
+    (p) =>
+      COLLAPSED_STREAMING_PACKET_TYPES.has(p.obj.type as PacketType) ||
+      (p.obj.type === PacketType.TOOL_CALL_ARGUMENT_DELTA &&
+        (p.obj as ToolCallArgumentDelta).tool_type ===
+          CODE_INTERPRETER_TOOL_TYPES.PYTHON)
   );
 
 // Check if packets have content worth rendering in collapsed streaming mode.
@@ -67,7 +84,13 @@ export const stepHasCollapsedStreamingContent = (
   // Python tool renders code/output from the start packet onward
   if (
     packetTypes.has(PacketType.PYTHON_TOOL_START) ||
-    packetTypes.has(PacketType.PYTHON_TOOL_DELTA)
+    packetTypes.has(PacketType.PYTHON_TOOL_DELTA) ||
+    packets.some(
+      (p) =>
+        p.obj.type === PacketType.TOOL_CALL_ARGUMENT_DELTA &&
+        (p.obj as ToolCallArgumentDelta).tool_type ===
+          CODE_INTERPRETER_TOOL_TYPES.PYTHON
+    )
   ) {
     return true;
   }
diff --git a/web/src/app/app/message/messageComponents/timeline/renderers/code/PythonToolRenderer.tsx b/web/src/app/app/message/messageComponents/timeline/renderers/code/PythonToolRenderer.tsx
index 286086092e0..d0359994643 100644
--- a/web/src/app/app/message/messageComponents/timeline/renderers/code/PythonToolRenderer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/renderers/code/PythonToolRenderer.tsx
@@ -4,7 +4,9 @@ import {
   PythonToolPacket,
   PythonToolStart,
   PythonToolDelta,
+  ToolCallArgumentDelta,
   SectionEnd,
+  CODE_INTERPRETER_TOOL_TYPES,
 } from "@/app/app/services/streamingModels";
 import {
   MessageRenderer,
@@ -39,6 +41,18 @@ function HighlightedPythonCode({ code }: { code: string }) {
 
 // Helper function to construct current Python execution state
 function constructCurrentPythonState(packets: PythonToolPacket[]) {
+  // Accumulate streaming code from argument deltas (arrives before PythonToolStart)
+  const streamingCode = packets
+    .filter(
+      (packet) =>
+        packet.obj.type === PacketType.TOOL_CALL_ARGUMENT_DELTA &&
+        (packet.obj as ToolCallArgumentDelta).tool_type ===
+          CODE_INTERPRETER_TOOL_TYPES.PYTHON
+    )
+    .map((packet) =>
+      String((packet.obj as ToolCallArgumentDelta).argument_deltas.code ?? "")
+    )
+    .join("");
   const pythonStart = packets.find(
     (packet) => packet.obj.type === PacketType.PYTHON_TOOL_START
   )?.obj as PythonToolStart | null;
@@ -51,7 +65,8 @@ function constructCurrentPythonState(packets: PythonToolPacket[]) {
       packet.obj.type === PacketType.ERROR
   )?.obj as SectionEnd | null;
 
-  const code = pythonStart?.code || "";
+  // Use complete code from PythonToolStart if available, else use streamed code.
+  const code = pythonStart?.code || streamingCode;
   const stdout = pythonDeltas
     .map((delta) => delta?.stdout || "")
     .filter((s) => s)
@@ -61,6 +76,7 @@ function constructCurrentPythonState(packets: PythonToolPacket[]) {
     .filter((s) => s)
     .join("");
   const fileIds = pythonDeltas.flatMap((delta) => delta?.file_ids || []);
+  const isStreaming = !pythonStart && streamingCode.length > 0;
   const isExecuting = pythonStart && !pythonEnd;
   const isComplete = pythonStart && pythonEnd;
   const hasError = stderr.length > 0;
@@ -70,6 +86,7 @@ function constructCurrentPythonState(packets: PythonToolPacket[]) {
     stdout,
     stderr,
     fileIds,
+    isStreaming,
     isExecuting,
     isComplete,
     hasError,
@@ -82,8 +99,16 @@ export const PythonToolRenderer: MessageRenderer<PythonToolPacket, {}> = ({
   renderType,
   children,
 }) => {
-  const { code, stdout, stderr, fileIds, isExecuting, isComplete, hasError } =
-    constructCurrentPythonState(packets);
+  const {
+    code,
+    stdout,
+    stderr,
+    fileIds,
+    isStreaming,
+    isExecuting,
+    isComplete,
+    hasError,
+  } = constructCurrentPythonState(packets);
 
   useEffect(() => {
     if (isComplete) {
@@ -92,6 +117,9 @@ export const PythonToolRenderer: MessageRenderer<PythonToolPacket, {}> = ({
   }, [isComplete, onComplete]);
 
   const status = useMemo(() => {
+    if (isStreaming) {
+      return "Writing code...";
+    }
     if (isExecuting) {
       return "Executing Python code...";
     }
@@ -102,13 +130,13 @@ export const PythonToolRenderer: MessageRenderer<PythonToolPacket, {}> = ({
       return "Python execution completed";
     }
     return "Python execution";
-  }, [isComplete, isExecuting, hasError]);
+  }, [isStreaming, isComplete, isExecuting, hasError]);
 
   // Shared content for all states - used by both FULL and compact modes
   const content = (
     <div className="flex flex-col mb-1 space-y-2">
-      {/* Loading indicator when executing */}
-      {isExecuting && (
+      {/* Loading indicator when streaming or executing */}
+      {(isStreaming || isExecuting) && (
         <div className="flex items-center gap-2 text-sm text-muted-foreground">
           <div className="flex gap-0.5">
             <div className="w-1 h-1 bg-current rounded-full animate-pulse"></div>
@@ -121,7 +149,7 @@ export const PythonToolRenderer: MessageRenderer<PythonToolPacket, {}> = ({
               style={{ animationDelay: "0.2s" }}
             ></div>
           </div>
-          <span>Running code...</span>
+          <span>{isStreaming ? "Writing code..." : "Running code..."}</span>
         </div>
       )}
 
diff --git a/web/src/app/app/services/packetUtils.ts b/web/src/app/app/services/packetUtils.ts
index dc8d69c7b26..f359b3012d1 100644
--- a/web/src/app/app/services/packetUtils.ts
+++ b/web/src/app/app/services/packetUtils.ts
@@ -16,6 +16,7 @@ export function isToolPacket(
     PacketType.SEARCH_TOOL_DOCUMENTS_DELTA,
     PacketType.PYTHON_TOOL_START,
     PacketType.PYTHON_TOOL_DELTA,
+    PacketType.TOOL_CALL_ARGUMENT_DELTA,
     PacketType.CUSTOM_TOOL_START,
     PacketType.CUSTOM_TOOL_DELTA,
     PacketType.FILE_READER_START,
diff --git a/web/src/app/app/services/streamingModels.ts b/web/src/app/app/services/streamingModels.ts
index a9a9f1357dd..62e023bf67b 100644
--- a/web/src/app/app/services/streamingModels.ts
+++ b/web/src/app/app/services/streamingModels.ts
@@ -27,6 +27,9 @@ export enum PacketType {
   FETCH_TOOL_URLS = "open_url_urls",
   FETCH_TOOL_DOCUMENTS = "open_url_documents",
 
+  // Tool call argument delta (streams tool args before tool executes)
+  TOOL_CALL_ARGUMENT_DELTA = "tool_call_argument_delta",
+
   // Custom tool packets
   CUSTOM_TOOL_START = "custom_tool_start",
   CUSTOM_TOOL_DELTA = "custom_tool_delta",
@@ -59,6 +62,10 @@ export enum PacketType {
   INTERMEDIATE_REPORT_CITED_DOCS = "intermediate_report_cited_docs",
 }
 
+export const CODE_INTERPRETER_TOOL_TYPES = {
+  PYTHON: "python",
+} as const;
+
 // Basic Message Packets
 export interface MessageStart extends BaseObj {
   id: string;
@@ -149,6 +156,13 @@ export interface PythonToolDelta extends BaseObj {
   file_ids: string[];
 }
 
+export interface ToolCallArgumentDelta extends BaseObj {
+  type: "tool_call_argument_delta";
+  tool_type: string;
+  tool_id: string;
+  argument_deltas: Record<string, unknown>;
+}
+
 export interface FetchToolStart extends BaseObj {
   type: "open_url_start";
 }
@@ -294,6 +308,7 @@ export type ImageGenerationToolObj =
 export type PythonToolObj =
   | PythonToolStart
   | PythonToolDelta
+  | ToolCallArgumentDelta
   | SectionEnd
   | PacketError;
 export type FetchToolObj =

From dfa0efc093a0720d807207fd2244c59b4a491d68 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Sun, 8 Mar 2026 10:01:55 -0700
Subject: [PATCH 172/267] fix(user files): Add configurable user file max
 upload size setting 1/3 (#9157)

---
 backend/onyx/configs/app_configs.py           |  4 +++
 backend/onyx/server/settings/models.py        |  1 +
 backend/onyx/server/settings/store.py         |  2 ++
 .../unit/onyx/server/test_settings_store.py   | 32 +++++++++++++++++++
 deployment/helm/charts/onyx/values.yaml       |  2 ++
 web/src/interfaces/settings.ts                |  1 +
 6 files changed, 42 insertions(+)
 create mode 100644 backend/tests/unit/onyx/server/test_settings_store.py

diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 32f2c77c099..2883dead666 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -68,6 +68,10 @@
     os.environ.get("FILE_TOKEN_COUNT_THRESHOLD", str(_DEFAULT_FILE_TOKEN_LIMIT))
 )
 
+# Maximum upload size for a single user file (chat/projects) in MB.
+USER_FILE_MAX_UPLOAD_SIZE_MB = int(os.environ.get("USER_FILE_MAX_UPLOAD_SIZE_MB") or 50)
+USER_FILE_MAX_UPLOAD_SIZE_BYTES = USER_FILE_MAX_UPLOAD_SIZE_MB * 1024 * 1024
+
 # If set to true, will show extra/uncommon connectors in the "Other" category
 SHOW_EXTRA_CONNECTORS = os.environ.get("SHOW_EXTRA_CONNECTORS", "").lower() == "true"
 
diff --git a/backend/onyx/server/settings/models.py b/backend/onyx/server/settings/models.py
index 63c814ec783..32870c030b4 100644
--- a/backend/onyx/server/settings/models.py
+++ b/backend/onyx/server/settings/models.py
@@ -78,6 +78,7 @@ class Settings(BaseModel):
 
     # User Knowledge settings
     user_knowledge_enabled: bool | None = True
+    user_file_max_upload_size_mb: int | None = None
 
     # Connector settings
     show_extra_connectors: bool | None = True
diff --git a/backend/onyx/server/settings/store.py b/backend/onyx/server/settings/store.py
index de9e8ad4099..5b058b32172 100644
--- a/backend/onyx/server/settings/store.py
+++ b/backend/onyx/server/settings/store.py
@@ -3,6 +3,7 @@
 from onyx.configs.app_configs import ENABLE_OPENSEARCH_INDEXING_FOR_ONYX
 from onyx.configs.app_configs import ONYX_QUERY_HISTORY_TYPE
 from onyx.configs.app_configs import SHOW_EXTRA_CONNECTORS
+from onyx.configs.app_configs import USER_FILE_MAX_UPLOAD_SIZE_MB
 from onyx.configs.constants import KV_SETTINGS_KEY
 from onyx.configs.constants import OnyxRedisLocks
 from onyx.key_value_store.factory import get_kv_store
@@ -50,6 +51,7 @@ def load_settings() -> Settings:
     if DISABLE_USER_KNOWLEDGE:
         settings.user_knowledge_enabled = False
 
+    settings.user_file_max_upload_size_mb = USER_FILE_MAX_UPLOAD_SIZE_MB
     settings.show_extra_connectors = SHOW_EXTRA_CONNECTORS
     settings.opensearch_indexing_enabled = ENABLE_OPENSEARCH_INDEXING_FOR_ONYX
     return settings
diff --git a/backend/tests/unit/onyx/server/test_settings_store.py b/backend/tests/unit/onyx/server/test_settings_store.py
new file mode 100644
index 00000000000..424e191291d
--- /dev/null
+++ b/backend/tests/unit/onyx/server/test_settings_store.py
@@ -0,0 +1,32 @@
+import pytest
+
+from onyx.key_value_store.interface import KvKeyNotFoundError
+from onyx.server.settings import store as settings_store
+
+
+class _FakeKvStore:
+    def load(self, _key: str) -> dict:
+        raise KvKeyNotFoundError()
+
+
+class _FakeCache:
+    def __init__(self) -> None:
+        self._vals: dict[str, bytes] = {}
+
+    def get(self, key: str) -> bytes | None:
+        return self._vals.get(key)
+
+    def set(self, key: str, value: str, ex: int | None = None) -> None:  # noqa: ARG002
+        self._vals[key] = value.encode("utf-8")
+
+
+def test_load_settings_includes_user_file_max_upload_size_mb(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(settings_store, "get_kv_store", lambda: _FakeKvStore())
+    monkeypatch.setattr(settings_store, "get_cache_backend", lambda: _FakeCache())
+    monkeypatch.setattr(settings_store, "USER_FILE_MAX_UPLOAD_SIZE_MB", 77)
+
+    settings = settings_store.load_settings()
+
+    assert settings.user_file_max_upload_size_mb == 77
diff --git a/deployment/helm/charts/onyx/values.yaml b/deployment/helm/charts/onyx/values.yaml
index e4c602a3d05..29480549787 100644
--- a/deployment/helm/charts/onyx/values.yaml
+++ b/deployment/helm/charts/onyx/values.yaml
@@ -1261,3 +1261,5 @@ configMap:
   SKIP_USERFILE_THRESHOLD: ""
   # For multi-tenant: comma-separated list of tenant IDs to skip threshold
   SKIP_USERFILE_THRESHOLD_TENANT_IDS: ""
+  # Maximum user upload file size in MB for chat/projects uploads
+  USER_FILE_MAX_UPLOAD_SIZE_MB: ""
diff --git a/web/src/interfaces/settings.ts b/web/src/interfaces/settings.ts
index a0e0a1cf62e..3c547e3a849 100644
--- a/web/src/interfaces/settings.ts
+++ b/web/src/interfaces/settings.ts
@@ -36,6 +36,7 @@ export interface Settings {
 
   // User Knowledge settings
   user_knowledge_enabled?: boolean;
+  user_file_max_upload_size_mb?: number | null;
 
   // Connector settings
   show_extra_connectors?: boolean;

From d3ee5c9b59d30bd0502274c1a94291e8cd1c1634 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Sun, 8 Mar 2026 10:42:44 -0700
Subject: [PATCH 173/267] fix(user files): Enforce user upload file size limit
 in projects/chat upload path 2/3 (#9158)

---
 .../features/projects/projects_file_utils.py  |  46 +++++
 .../onyx/server/test_projects_file_utils.py   | 188 ++++++++++++++++++
 2 files changed, 234 insertions(+)
 create mode 100644 backend/tests/unit/onyx/server/test_projects_file_utils.py

diff --git a/backend/onyx/server/features/projects/projects_file_utils.py b/backend/onyx/server/features/projects/projects_file_utils.py
index 5b882c76974..d3136e3d4b7 100644
--- a/backend/onyx/server/features/projects/projects_file_utils.py
+++ b/backend/onyx/server/features/projects/projects_file_utils.py
@@ -10,6 +10,8 @@
 from sqlalchemy.orm import Session
 
 from onyx.configs.app_configs import FILE_TOKEN_COUNT_THRESHOLD
+from onyx.configs.app_configs import USER_FILE_MAX_UPLOAD_SIZE_BYTES
+from onyx.configs.app_configs import USER_FILE_MAX_UPLOAD_SIZE_MB
 from onyx.db.llm import fetch_default_llm_model
 from onyx.file_processing.extract_file_text import extract_file_text
 from onyx.file_processing.extract_file_text import get_file_ext
@@ -35,6 +37,38 @@ def get_safe_filename(upload: UploadFile) -> str:
     return upload.filename
 
 
+def get_upload_size_bytes(upload: UploadFile) -> int | None:
+    """Best-effort file size in bytes without consuming the stream."""
+    if upload.size is not None:
+        return upload.size
+
+    try:
+        current_pos = upload.file.tell()
+        upload.file.seek(0, 2)
+        size = upload.file.tell()
+        upload.file.seek(current_pos)
+        return size
+    except Exception as e:
+        logger.warning(
+            "Could not determine upload size via stream seek "
+            f"(filename='{get_safe_filename(upload)}', "
+            f"error_type={type(e).__name__}, error={e})"
+        )
+        return None
+
+
+def is_upload_too_large(upload: UploadFile, max_bytes: int) -> bool:
+    """Return True when upload size is known and exceeds max_bytes."""
+    size_bytes = get_upload_size_bytes(upload)
+    if size_bytes is None:
+        logger.warning(
+            "Could not determine upload size; skipping size-limit check for "
+            f"'{get_safe_filename(upload)}'"
+        )
+        return False
+    return size_bytes > max_bytes
+
+
 # Guard against extremely large images
 Image.MAX_IMAGE_PIXELS = 12000 * 12000
 
@@ -159,6 +193,18 @@ def categorize_uploaded_files(
     for upload in files:
         try:
             filename = get_safe_filename(upload)
+
+            # Size limit is a hard safety cap and is enforced even when token
+            # threshold checks are skipped via SKIP_USERFILE_THRESHOLD settings.
+            if is_upload_too_large(upload, USER_FILE_MAX_UPLOAD_SIZE_BYTES):
+                results.rejected.append(
+                    RejectedFile(
+                        filename=filename,
+                        reason=f"Exceeds {USER_FILE_MAX_UPLOAD_SIZE_MB} MB file size limit",
+                    )
+                )
+                continue
+
             extension = get_file_ext(filename)
 
             # If image, estimate tokens via dedicated method first
diff --git a/backend/tests/unit/onyx/server/test_projects_file_utils.py b/backend/tests/unit/onyx/server/test_projects_file_utils.py
new file mode 100644
index 00000000000..35ec07ba5ee
--- /dev/null
+++ b/backend/tests/unit/onyx/server/test_projects_file_utils.py
@@ -0,0 +1,188 @@
+from io import BytesIO
+from unittest.mock import MagicMock
+
+import pytest
+from fastapi import UploadFile
+
+from onyx.server.features.projects import projects_file_utils as utils
+
+
+class _Tokenizer:
+    def encode(self, text: str) -> list[int]:
+        return [1] * len(text)
+
+
+class _NonSeekableFile(BytesIO):
+    def tell(self) -> int:
+        raise OSError("tell not supported")
+
+    def seek(self, *_args: object, **_kwargs: object) -> int:
+        raise OSError("seek not supported")
+
+
+def _make_upload(filename: str, size: int, content: bytes | None = None) -> UploadFile:
+    payload = content if content is not None else (b"x" * size)
+    return UploadFile(filename=filename, file=BytesIO(payload), size=size)
+
+
+def _make_upload_no_size(filename: str, content: bytes) -> UploadFile:
+    return UploadFile(filename=filename, file=BytesIO(content), size=None)
+
+
+def _patch_common_dependencies(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(utils, "fetch_default_llm_model", lambda _db: None)
+    monkeypatch.setattr(utils, "get_tokenizer", lambda **_kwargs: _Tokenizer())
+    monkeypatch.setattr(utils, "is_file_password_protected", lambda **_kwargs: False)
+
+
+def test_get_upload_size_bytes_falls_back_to_stream_size() -> None:
+    upload = UploadFile(filename="example.txt", file=BytesIO(b"abcdef"), size=None)
+    upload.file.seek(2)
+
+    size = utils.get_upload_size_bytes(upload)
+
+    assert size == 6
+    assert upload.file.tell() == 2
+
+
+def test_get_upload_size_bytes_logs_warning_when_stream_size_unavailable(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    upload = UploadFile(filename="non_seekable.txt", file=_NonSeekableFile(), size=None)
+
+    caplog.set_level("WARNING")
+    size = utils.get_upload_size_bytes(upload)
+
+    assert size is None
+    assert "Could not determine upload size via stream seek" in caplog.text
+    assert "non_seekable.txt" in caplog.text
+
+
+def test_is_upload_too_large_logs_warning_when_size_unknown(
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    upload = _make_upload("size_unknown.txt", size=1)
+    monkeypatch.setattr(utils, "get_upload_size_bytes", lambda _upload: None)
+
+    caplog.set_level("WARNING")
+    is_too_large = utils.is_upload_too_large(upload, max_bytes=100)
+
+    assert is_too_large is False
+    assert "Could not determine upload size; skipping size-limit check" in caplog.text
+    assert "size_unknown.txt" in caplog.text
+
+
+def test_categorize_uploaded_files_accepts_size_under_limit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+    monkeypatch.setattr(utils, "estimate_image_tokens_for_upload", lambda _upload: 10)
+
+    upload = _make_upload("small.png", size=99)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 1
+    assert len(result.rejected) == 0
+
+
+def test_categorize_uploaded_files_uses_seek_fallback_when_upload_size_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+    monkeypatch.setattr(utils, "estimate_image_tokens_for_upload", lambda _upload: 10)
+
+    upload = _make_upload_no_size("small.png", content=b"x" * 99)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 1
+    assert len(result.rejected) == 0
+
+
+def test_categorize_uploaded_files_accepts_size_at_limit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+    monkeypatch.setattr(utils, "estimate_image_tokens_for_upload", lambda _upload: 10)
+
+    upload = _make_upload("edge.png", size=100)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 1
+    assert len(result.rejected) == 0
+
+
+def test_categorize_uploaded_files_rejects_size_over_limit_with_reason(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+    monkeypatch.setattr(utils, "estimate_image_tokens_for_upload", lambda _upload: 10)
+
+    upload = _make_upload("large.png", size=101)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 0
+    assert len(result.rejected) == 1
+    assert result.rejected[0].reason == "Exceeds 1 MB file size limit"
+
+
+def test_categorize_uploaded_files_mixed_batch_keeps_valid_and_rejects_oversized(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+    monkeypatch.setattr(utils, "estimate_image_tokens_for_upload", lambda _upload: 10)
+
+    small = _make_upload("small.png", size=50)
+    large = _make_upload("large.png", size=101)
+
+    result = utils.categorize_uploaded_files([small, large], MagicMock())
+
+    assert [file.filename for file in result.acceptable] == ["small.png"]
+    assert len(result.rejected) == 1
+    assert result.rejected[0].filename == "large.png"
+    assert result.rejected[0].reason == "Exceeds 1 MB file size limit"
+
+
+def test_categorize_uploaded_files_enforces_size_limit_even_when_threshold_is_skipped(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "SKIP_USERFILE_THRESHOLD", True)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+
+    upload = _make_upload("oversized.pdf", size=101)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 0
+    assert len(result.rejected) == 1
+    assert result.rejected[0].reason == "Exceeds 1 MB file size limit"
+
+
+def test_categorize_uploaded_files_checks_size_before_text_extraction(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 100)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+
+    extract_mock = MagicMock(return_value="this should not run")
+    monkeypatch.setattr(utils, "extract_file_text", extract_mock)
+
+    oversized_doc = _make_upload("oversized.pdf", size=101)
+    result = utils.categorize_uploaded_files([oversized_doc], MagicMock())
+
+    extract_mock.assert_not_called()
+    assert len(result.acceptable) == 0
+    assert len(result.rejected) == 1
+    assert result.rejected[0].reason == "Exceeds 1 MB file size limit"

From cc2e6ffa8a2425aa17a3d7ddb7901895cce69230 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Sun, 8 Mar 2026 11:47:25 -0700
Subject: [PATCH 174/267] fix(user files): Add frontend precheck for oversized
 user uploads 3/3 (#9159)

---
 web/jest.config.js                            |   1 +
 web/src/providers/ProjectsContext.tsx         |  35 +++-
 .../__tests__/ProjectsContext.test.tsx        | 166 ++++++++++++++++++
 3 files changed, 199 insertions(+), 3 deletions(-)
 create mode 100644 web/src/providers/__tests__/ProjectsContext.test.tsx

diff --git a/web/jest.config.js b/web/jest.config.js
index 83c97d69ea3..7ba48ecf563 100644
--- a/web/jest.config.js
+++ b/web/jest.config.js
@@ -156,6 +156,7 @@ module.exports = {
         "**/src/app/**/*.test.tsx",
         "**/src/components/**/*.test.tsx",
         "**/src/lib/**/*.test.tsx",
+        "**/src/providers/**/*.test.tsx",
         "**/src/refresh-components/**/*.test.tsx",
         "**/src/hooks/**/*.test.tsx",
         "**/src/sections/**/*.test.tsx",
diff --git a/web/src/providers/ProjectsContext.tsx b/web/src/providers/ProjectsContext.tsx
index 4a3ecba8ab9..90d7ca8764f 100644
--- a/web/src/providers/ProjectsContext.tsx
+++ b/web/src/providers/ProjectsContext.tsx
@@ -43,6 +43,7 @@ import { useAppRouter } from "@/hooks/appNavigation";
 import { ChatFileType } from "@/app/app/interfaces";
 import { toast } from "@/hooks/useToast";
 import { useProjects } from "@/lib/hooks/useProjects";
+import { SettingsContext } from "@/providers/SettingsProvider";
 
 export type { Project, ProjectFile } from "@/app/app/projects/projectsService";
 
@@ -84,6 +85,8 @@ function buildFileKey(file: File): string {
   return `${file.size}|${namePrefix}`;
 }
 
+const DEFAULT_USER_FILE_MAX_UPLOAD_SIZE_MB = 50;
+
 interface ProjectsContextType {
   projects: Project[];
   recentFiles: ProjectFile[];
@@ -157,6 +160,7 @@ export function ProjectsProvider({ children }: ProjectsProviderProps) {
     new Map()
   );
   const route = useAppRouter();
+  const settingsContext = useContext(SettingsContext);
 
   // Use SWR's mutate to refresh projects - returns the new data
   const fetchProjects = useCallback(async (): Promise<Project[]> => {
@@ -336,16 +340,40 @@ export function ProjectsProvider({ children }: ProjectsProviderProps) {
       onSuccess?: (uploaded: CategorizedFiles) => void,
       onFailure?: (failedTempIds: string[]) => void
     ): Promise<ProjectFile[]> => {
-      const optimisticFiles = files.map((f) =>
+      const rawMax = settingsContext?.settings?.user_file_max_upload_size_mb;
+      const maxUploadSizeMb =
+        rawMax && rawMax > 0 ? rawMax : DEFAULT_USER_FILE_MAX_UPLOAD_SIZE_MB;
+      const maxUploadSizeBytes = maxUploadSizeMb * 1024 * 1024;
+
+      const oversizedFiles = files.filter(
+        (file) => file.size > maxUploadSizeBytes
+      );
+      const validFiles = files.filter(
+        (file) => file.size <= maxUploadSizeBytes
+      );
+
+      if (oversizedFiles.length > 0) {
+        const skippedNames = oversizedFiles.map((file) => file.name).join(", ");
+        toast.warning(
+          `Skipped ${oversizedFiles.length} oversized file(s) (>${maxUploadSizeMb} MB): ${skippedNames}`
+        );
+      }
+
+      if (validFiles.length === 0) {
+        onFailure?.([]);
+        return [];
+      }
+
+      const optimisticFiles = validFiles.map((f) =>
         createOptimisticFile(f, projectId)
       );
-      const tempIdMap = getTempIdMap(files, optimisticFiles);
+      const tempIdMap = getTempIdMap(validFiles, optimisticFiles);
       setAllRecentFiles((prev) => [...optimisticFiles, ...prev]);
       if (projectId) {
         setAllCurrentProjectFiles((prev) => [...optimisticFiles, ...prev]);
         projectToUploadFilesMapRef.current.set(projectId, optimisticFiles);
       }
-      svcUploadFiles(files, projectId, tempIdMap)
+      svcUploadFiles(validFiles, projectId, tempIdMap)
         .then((uploaded) => {
           const uploadedFiles = uploaded.user_files || [];
           const tempIdToUploadedFileMap = new Map(
@@ -445,6 +473,7 @@ export function ProjectsProvider({ children }: ProjectsProviderProps) {
       refreshCurrentProjectDetails,
       refreshRecentFiles,
       removeOptimisticFilesByTempIds,
+      settingsContext,
     ]
   );
 
diff --git a/web/src/providers/__tests__/ProjectsContext.test.tsx b/web/src/providers/__tests__/ProjectsContext.test.tsx
new file mode 100644
index 00000000000..cdb1b90671f
--- /dev/null
+++ b/web/src/providers/__tests__/ProjectsContext.test.tsx
@@ -0,0 +1,166 @@
+import React, { PropsWithChildren } from "react";
+import { act, renderHook } from "@testing-library/react";
+import {
+  ProjectsProvider,
+  useProjectsContext,
+} from "@/providers/ProjectsContext";
+import { SettingsContext } from "@/providers/SettingsProvider";
+import { CombinedSettings } from "@/interfaces/settings";
+import type { ProjectFile } from "@/app/app/projects/projectsService";
+
+const mockUploadFiles = jest.fn();
+const mockGetRecentFiles = jest.fn();
+const mockToastWarning = jest.fn();
+
+jest.mock("next/navigation", () => ({
+  useSearchParams: () => ({
+    get: () => null,
+  }),
+}));
+
+jest.mock("@/hooks/appNavigation", () => ({
+  useAppRouter: () => jest.fn(),
+}));
+
+jest.mock("@/lib/hooks/useProjects", () => ({
+  useProjects: () => ({
+    projects: [],
+    refreshProjects: jest.fn().mockResolvedValue([]),
+  }),
+}));
+
+jest.mock("@/hooks/useToast", () => ({
+  toast: {
+    warning: (...args: unknown[]) => mockToastWarning(...args),
+    error: jest.fn(),
+    success: jest.fn(),
+  },
+}));
+
+jest.mock("@/app/app/projects/projectsService", () => {
+  const actual = jest.requireActual("@/app/app/projects/projectsService");
+  return {
+    ...actual,
+    fetchProjects: jest.fn().mockResolvedValue([]),
+    createProject: jest.fn(),
+    uploadFiles: (...args: unknown[]) => mockUploadFiles(...args),
+    getRecentFiles: (...args: unknown[]) => mockGetRecentFiles(...args),
+    getFilesInProject: jest.fn().mockResolvedValue([]),
+    getProject: jest.fn(),
+    getProjectInstructions: jest.fn(),
+    upsertProjectInstructions: jest.fn(),
+    getProjectDetails: jest.fn(),
+    renameProject: jest.fn(),
+    deleteProject: jest.fn(),
+    deleteUserFile: jest.fn(),
+    getUserFileStatuses: jest.fn().mockResolvedValue([]),
+    unlinkFileFromProject: jest.fn(),
+    linkFileToProject: jest.fn(),
+  };
+});
+
+const settingsValue: CombinedSettings = {
+  settings: {
+    user_file_max_upload_size_mb: 1,
+  } as CombinedSettings["settings"],
+  enterpriseSettings: null,
+  customAnalyticsScript: null,
+  webVersion: null,
+  webDomain: null,
+  isSearchModeAvailable: true,
+};
+
+const wrapper = ({ children }: PropsWithChildren) => (
+  <SettingsContext.Provider value={settingsValue}>
+    <ProjectsProvider>{children}</ProjectsProvider>
+  </SettingsContext.Provider>
+);
+
+describe("ProjectsContext beginUpload size precheck", () => {
+  beforeEach(() => {
+    mockUploadFiles.mockReset();
+    mockGetRecentFiles.mockReset();
+    mockToastWarning.mockReset();
+
+    mockUploadFiles.mockResolvedValue({
+      user_files: [],
+      rejected_files: [],
+    });
+    mockGetRecentFiles.mockResolvedValue([]);
+  });
+
+  it("only sends valid files to the upload API when oversized files are present", async () => {
+    const { result } = renderHook(() => useProjectsContext(), { wrapper });
+
+    const valid = new File(["small"], "small.txt", { type: "text/plain" });
+    const oversized = new File([new Uint8Array(2 * 1024 * 1024)], "big.txt", {
+      type: "text/plain",
+    });
+
+    let optimisticFiles: ProjectFile[] = [];
+    await act(async () => {
+      optimisticFiles = await result.current.beginUpload(
+        [valid, oversized],
+        null
+      );
+    });
+
+    expect(mockUploadFiles).toHaveBeenCalledTimes(1);
+    const [uploadedFiles] = mockUploadFiles.mock.calls[0];
+    expect((uploadedFiles as File[]).map((f) => f.name)).toEqual(["small.txt"]);
+    expect(optimisticFiles.map((f) => f.name)).toEqual(["small.txt"]);
+    expect(mockToastWarning).toHaveBeenCalledTimes(1);
+  });
+
+  it("uploads all files when none are oversized", async () => {
+    const { result } = renderHook(() => useProjectsContext(), { wrapper });
+
+    const first = new File(["small"], "first.txt", { type: "text/plain" });
+    const second = new File(["small"], "second.txt", { type: "text/plain" });
+
+    let optimisticFiles: ProjectFile[] = [];
+    await act(async () => {
+      optimisticFiles = await result.current.beginUpload([first, second], null);
+    });
+
+    expect(mockUploadFiles).toHaveBeenCalledTimes(1);
+    const [uploadedFiles] = mockUploadFiles.mock.calls[0];
+    expect((uploadedFiles as File[]).map((f) => f.name)).toEqual([
+      "first.txt",
+      "second.txt",
+    ]);
+    expect(mockToastWarning).not.toHaveBeenCalled();
+    expect(optimisticFiles.map((f) => f.name)).toEqual([
+      "first.txt",
+      "second.txt",
+    ]);
+  });
+
+  it("does not call upload API when all files are oversized", async () => {
+    const { result } = renderHook(() => useProjectsContext(), { wrapper });
+
+    const oversized = new File(
+      [new Uint8Array(2 * 1024 * 1024)],
+      "too-big.txt",
+      { type: "text/plain" }
+    );
+    const onSuccess = jest.fn();
+    const onFailure = jest.fn();
+
+    let optimisticFiles: ProjectFile[] = [];
+    await act(async () => {
+      optimisticFiles = await result.current.beginUpload(
+        [oversized],
+        null,
+        onSuccess,
+        onFailure
+      );
+    });
+
+    expect(mockUploadFiles).not.toHaveBeenCalled();
+    expect(optimisticFiles).toEqual([]);
+    expect(mockToastWarning).toHaveBeenCalledTimes(1);
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(onFailure).toHaveBeenCalledWith([]);
+  });
+});

From e07764285dc650260e48df9c9009b7a2b221b933 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Sun, 8 Mar 2026 12:07:11 -0700
Subject: [PATCH 175/267] chore(llm): Adding Integration test for Model state
 cache 2/2 (#9142)

---
 .../e2e/admin/llm_provider_setup.spec.ts      | 259 +++++++++++++++++-
 1 file changed, 258 insertions(+), 1 deletion(-)

diff --git a/web/tests/e2e/admin/llm_provider_setup.spec.ts b/web/tests/e2e/admin/llm_provider_setup.spec.ts
index 3e84409863f..3a3ae5bd267 100644
--- a/web/tests/e2e/admin/llm_provider_setup.spec.ts
+++ b/web/tests/e2e/admin/llm_provider_setup.spec.ts
@@ -21,10 +21,47 @@ type DefaultModelInfo = {
   model_name: string;
 } | null;
 
+type ProviderModelConfig = {
+  name: string;
+  is_visible: boolean;
+};
+
 function uniqueName(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
+function normalizeAlphaNum(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function modelTokenVariants(modelName: string): string[][] {
+  return modelName
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length > 0)
+    .map((token) => {
+      // Display names may shorten long numeric segments to suffixes.
+      if (/^\d+$/.test(token) && token.length > 5) {
+        return [token, token.slice(-5)];
+      }
+      return [token];
+    });
+}
+
+function textMatchesModel(modelName: string, candidateText: string): boolean {
+  const normalizedCandidate = normalizeAlphaNum(candidateText);
+  if (!normalizedCandidate) {
+    return false;
+  }
+
+  const tokenVariants = modelTokenVariants(modelName);
+  return tokenVariants.every((variants) =>
+    variants.some((variant) =>
+      normalizedCandidate.includes(normalizeAlphaNum(variant))
+    )
+  );
+}
+
 async function getAdminLLMProviderResponse(page: Page) {
   const response = await page.request.get(`${BASE_URL}/api/admin/llm/provider`);
   expect(response.ok()).toBeTruthy();
@@ -50,6 +87,18 @@ async function createPublicProvider(
   providerName: string,
   modelName: string = "gpt-4o"
 ): Promise<number> {
+  return createPublicProviderWithModels(page, providerName, [
+    { name: modelName, is_visible: true },
+  ]);
+}
+
+async function createPublicProviderWithModels(
+  page: Page,
+  providerName: string,
+  modelConfigurations: ProviderModelConfig[]
+): Promise<number> {
+  expect(modelConfigurations.length).toBeGreaterThan(0);
+
   const response = await page.request.put(
     `${BASE_URL}/api/admin/llm/provider?is_creation=true`,
     {
@@ -60,7 +109,7 @@ async function createPublicProvider(
         is_public: true,
         groups: [],
         personas: [],
-        model_configurations: [{ name: modelName, is_visible: true }],
+        model_configurations: modelConfigurations,
       },
     }
   );
@@ -69,6 +118,86 @@ async function createPublicProvider(
   return data.id;
 }
 
+async function navigateToAdminLlmPageFromChat(page: Page): Promise<void> {
+  await page.goto(LLM_SETUP_URL);
+  await page.waitForURL("**/admin/configuration/llm**");
+  await expect(page.getByLabel("admin-page-title")).toHaveText(
+    /^Language Models/
+  );
+}
+
+async function exitAdminToChat(page: Page): Promise<void> {
+  await page.goto("/app");
+  await page.waitForURL("**/app**");
+  await page
+    .locator("#onyx-chat-input-textarea")
+    .waitFor({ state: "visible", timeout: 15000 });
+}
+
+async function isModelVisibleInChatProviders(
+  page: Page,
+  modelName: string
+): Promise<boolean> {
+  const response = await page.request.get(`${BASE_URL}/api/llm/provider`);
+  expect(response.ok()).toBeTruthy();
+
+  const data = (await response.json()) as {
+    providers: {
+      model_configurations: { name: string; is_visible: boolean }[];
+    }[];
+  };
+
+  return data.providers.some((provider) =>
+    provider.model_configurations.some(
+      (model) => model.name === modelName && model.is_visible
+    )
+  );
+}
+
+async function expectModelVisibilityInChatProviders(
+  page: Page,
+  modelName: string,
+  expectedVisible: boolean
+): Promise<void> {
+  await expect
+    .poll(() => isModelVisibleInChatProviders(page, modelName), {
+      timeout: 30000,
+    })
+    .toBe(expectedVisible);
+}
+
+async function getModelCountInChatSelector(
+  page: Page,
+  modelName: string
+): Promise<number> {
+  const dialog = page.locator('[role="dialog"]').first();
+
+  // When used in expect.poll retries, a previous attempt may leave the
+  // popover open. Ensure a clean state before toggling it.
+  if (await dialog.isVisible()) {
+    await page.keyboard.press("Escape");
+    await dialog.waitFor({ state: "hidden", timeout: 5000 });
+  }
+
+  await page.getByTestId("AppInputBar/llm-popover-trigger").click();
+  await dialog.waitFor({ state: "visible", timeout: 10000 });
+
+  await dialog.getByPlaceholder("Search models...").fill(modelName);
+  const optionButtons = dialog.getByRole("button");
+  const optionTexts = await optionButtons.allTextContents();
+  const uniqueOptionTexts = Array.from(
+    new Set(optionTexts.map((text) => text.trim()))
+  );
+  const count = uniqueOptionTexts.filter((text) =>
+    textMatchesModel(modelName, text)
+  ).length;
+
+  await page.keyboard.press("Escape");
+  await dialog.waitFor({ state: "hidden", timeout: 10000 });
+
+  return count;
+}
+
 async function getProviderByName(
   page: Page,
   providerName: string
@@ -272,4 +401,132 @@ test.describe("LLM Provider Setup @exclusive", () => {
       }
     }
   });
+
+  test("adding a hidden model on an existing provider shows it in chat after one save", async ({
+    page,
+  }) => {
+    await page.route("**/api/admin/llm/test", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true }),
+      });
+    });
+
+    const providerName = uniqueName("PW Provider Add Model");
+    const ts = Date.now();
+    const alwaysVisibleModel = `pw-visible-${ts}-base`;
+    const modelToEnable = `pw-hidden-${ts}-to-enable`;
+
+    const providerId = await createPublicProviderWithModels(
+      page,
+      providerName,
+      [
+        { name: alwaysVisibleModel, is_visible: true },
+        { name: modelToEnable, is_visible: false },
+      ]
+    );
+    providersToCleanup.push(providerId);
+    await expectModelVisibilityInChatProviders(page, modelToEnable, false);
+
+    await page.goto("/app");
+    await page.waitForLoadState("networkidle");
+    await page
+      .locator("#onyx-chat-input-textarea")
+      .waitFor({ state: "visible", timeout: 15000 });
+
+    await expect
+      .poll(() => getModelCountInChatSelector(page, modelToEnable), {
+        timeout: 15000,
+      })
+      .toBe(0);
+
+    await navigateToAdminLlmPageFromChat(page);
+
+    const editModal = await openProviderEditModal(page, providerName);
+    await editModal.getByText(modelToEnable, { exact: true }).click();
+
+    const updateButton = editModal.getByRole("button", { name: "Update" });
+    const providerUpdateResponsePromise = page.waitForResponse(
+      (response) =>
+        response.url().includes("/api/admin/llm/provider") &&
+        response.request().method() === "PUT"
+    );
+    await expect(updateButton).toBeEnabled({ timeout: 10000 });
+    await updateButton.click();
+    await providerUpdateResponsePromise;
+    await expect(editModal).not.toBeVisible({ timeout: 30000 });
+    await expectModelVisibilityInChatProviders(page, modelToEnable, true);
+
+    await exitAdminToChat(page);
+    await expect
+      .poll(() => getModelCountInChatSelector(page, modelToEnable), {
+        timeout: 15000,
+      })
+      .toBe(1);
+  });
+
+  test("removing a visible model on an existing provider hides it in chat after one save", async ({
+    page,
+  }) => {
+    await page.route("**/api/admin/llm/test", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true }),
+      });
+    });
+
+    const providerName = uniqueName("PW Provider Remove Model");
+    const ts = Date.now();
+    const alwaysVisibleModel = `pw-visible-${ts}-base`;
+    const modelToDisable = `pw-visible-${ts}-to-disable`;
+
+    const providerId = await createPublicProviderWithModels(
+      page,
+      providerName,
+      [
+        { name: alwaysVisibleModel, is_visible: true },
+        { name: modelToDisable, is_visible: true },
+      ]
+    );
+    providersToCleanup.push(providerId);
+    await expectModelVisibilityInChatProviders(page, modelToDisable, true);
+
+    await page.goto("/app");
+    await page.waitForLoadState("networkidle");
+    await page
+      .locator("#onyx-chat-input-textarea")
+      .waitFor({ state: "visible", timeout: 15000 });
+
+    await expect
+      .poll(() => getModelCountInChatSelector(page, modelToDisable), {
+        timeout: 15000,
+      })
+      .toBe(1);
+
+    await navigateToAdminLlmPageFromChat(page);
+
+    const editModal = await openProviderEditModal(page, providerName);
+    await editModal.getByText(modelToDisable, { exact: true }).click();
+
+    const updateButton = editModal.getByRole("button", { name: "Update" });
+    const providerUpdateResponsePromise = page.waitForResponse(
+      (response) =>
+        response.url().includes("/api/admin/llm/provider") &&
+        response.request().method() === "PUT"
+    );
+    await expect(updateButton).toBeEnabled({ timeout: 10000 });
+    await updateButton.click();
+    await providerUpdateResponsePromise;
+    await expect(editModal).not.toBeVisible({ timeout: 30000 });
+    await expectModelVisibilityInChatProviders(page, modelToDisable, false);
+
+    await exitAdminToChat(page);
+    await expect
+      .poll(() => getModelCountInChatSelector(page, modelToDisable), {
+        timeout: 15000,
+      })
+      .toBe(0);
+  });
 });

From 64ee7fc23fce4f23257ce113239125bcf3c2d434 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Sun, 8 Mar 2026 13:11:17 -0700
Subject: [PATCH 176/267] fix(fe): fix broken slack bot admin pages (#9168)

---
 .../app/admin/bots/SlackBotCreationForm.tsx   |  11 +-
 web/src/app/admin/bots/SlackBotUpdateForm.tsx |   9 +-
 .../bots/[bot-id]/channels/[id]/page.tsx      | 172 ++++++++++--------
 .../admin/bots/[bot-id]/channels/new/page.tsx | 125 +++++++++----
 web/src/app/admin/bots/[bot-id]/page.tsx      |  64 +++----
 web/src/app/admin/bots/new/page.tsx           |  13 +-
 web/src/lib/error.ts                          |  10 +
 7 files changed, 236 insertions(+), 168 deletions(-)
 create mode 100644 web/src/lib/error.ts

diff --git a/web/src/app/admin/bots/SlackBotCreationForm.tsx b/web/src/app/admin/bots/SlackBotCreationForm.tsx
index 17a7f1bb81b..7398e247903 100644
--- a/web/src/app/admin/bots/SlackBotCreationForm.tsx
+++ b/web/src/app/admin/bots/SlackBotCreationForm.tsx
@@ -7,7 +7,7 @@ import { SlackTokensForm } from "./SlackTokensForm";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { SvgSlack } from "@opal/icons";
 
-export const NewSlackBotForm = () => {
+export function NewSlackBotForm() {
   const [formValues] = useState({
     name: "",
     enabled: true,
@@ -19,7 +19,12 @@ export const NewSlackBotForm = () => {
 
   return (
     <SettingsLayouts.Root>
-      <SettingsLayouts.Header icon={SvgSlack} title="New Slack Bot" separator />
+      <SettingsLayouts.Header
+        icon={SvgSlack}
+        title="New Slack Bot"
+        separator
+        backButton
+      />
       <SettingsLayouts.Body>
         <CardSection>
           <div className="p-4">
@@ -33,4 +38,4 @@ export const NewSlackBotForm = () => {
       </SettingsLayouts.Body>
     </SettingsLayouts.Root>
   );
-};
+}
diff --git a/web/src/app/admin/bots/SlackBotUpdateForm.tsx b/web/src/app/admin/bots/SlackBotUpdateForm.tsx
index 818bee61dd2..99a50a2393a 100644
--- a/web/src/app/admin/bots/SlackBotUpdateForm.tsx
+++ b/web/src/app/admin/bots/SlackBotUpdateForm.tsx
@@ -1,12 +1,12 @@
 "use client";
 
 import { toast } from "@/hooks/useToast";
-import { SlackBot, ValidSources } from "@/lib/types";
+import { SlackBot } from "@/lib/types";
 import { useRouter } from "next/navigation";
 import { useState, useEffect, useRef } from "react";
 import { updateSlackBotField } from "@/lib/updateSlackBotField";
 import { SlackTokensForm } from "./SlackTokensForm";
-import { SourceIcon } from "@/components/SourceIcon";
+
 import { EditableStringFieldDisplay } from "@/components/EditableStringFieldDisplay";
 import { deleteSlackBot } from "./new/lib";
 import GenericConfirmModal from "@/components/modals/GenericConfirmModal";
@@ -90,10 +90,7 @@ export const ExistingSlackBotForm = ({
     <div>
       <div className="flex items-center justify-between h-14">
         <div className="flex items-center gap-2">
-          <div className="my-auto">
-            <SourceIcon iconSize={32} sourceType={ValidSources.Slack} />
-          </div>
-          <div className="ml-1">
+          <div>
             <EditableStringFieldDisplay
               value={formValues.name}
               isEditable={true}
diff --git a/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx b/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
index de4af1a36d3..98126a0f086 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/[id]/page.tsx
@@ -1,100 +1,122 @@
-import { SlackChannelConfigCreationForm } from "../SlackChannelConfigCreationForm";
-import { fetchSS } from "@/lib/utilsSS";
+"use client";
+
+import { use } from "react";
+import { SlackChannelConfigCreationForm } from "@/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import { DocumentSetSummary, SlackChannelConfig } from "@/lib/types";
-import { InstantSSRAutoRefresh } from "@/components/SSRAutoRefresh";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { SvgSlack } from "@opal/icons";
-import { FetchAgentsResponse, fetchAgentsSS } from "@/lib/agentsSS";
-import { getStandardAnswerCategoriesIfEE } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
+import { useSlackChannelConfigs } from "@/app/admin/bots/[bot-id]/hooks";
+import { useDocumentSets } from "@/app/admin/documents/sets/hooks";
+import { useAgents } from "@/hooks/useAgents";
+import { useStandardAnswerCategories } from "@/app/ee/admin/standard-answer/hooks";
+import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
+import type { StandardAnswerCategoryResponse } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
 
-async function EditslackChannelConfigPage(props: {
-  params: Promise<{ id: number }>;
-}) {
-  const params = await props.params;
-  const tasks = [
-    fetchSS("/manage/admin/slack-app/channel"),
-    fetchSS("/manage/document-set"),
-    fetchAgentsSS(),
-  ];
+function EditSlackChannelConfigContent({ id }: { id: string }) {
+  const isPaidEnterprise = usePaidEnterpriseFeaturesEnabled();
 
-  const [
-    slackChannelsResponse,
-    documentSetsResponse,
-    [assistants, agentsFetchError],
-  ] = (await Promise.all(tasks)) as [Response, Response, FetchAgentsResponse];
+  const {
+    data: slackChannelConfigs,
+    isLoading: isChannelsLoading,
+    error: channelsError,
+  } = useSlackChannelConfigs();
 
-  const eeStandardAnswerCategoryResponse =
-    await getStandardAnswerCategoriesIfEE();
+  const {
+    data: documentSets,
+    isLoading: isDocSetsLoading,
+    error: docSetsError,
+  } = useDocumentSets();
 
-  if (!slackChannelsResponse.ok) {
-    return (
-      <ErrorCallout
-        errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch Slack Channels - ${await slackChannelsResponse.text()}`}
-      />
-    );
-  }
-  const allslackChannelConfigs =
-    (await slackChannelsResponse.json()) as SlackChannelConfig[];
+  const {
+    agents,
+    isLoading: isAgentsLoading,
+    error: agentsError,
+  } = useAgents();
 
-  const slackChannelConfig = allslackChannelConfigs.find(
-    (config) => config.id === Number(params.id)
-  );
+  const {
+    data: standardAnswerCategories,
+    isLoading: isStdAnswerLoading,
+    error: stdAnswerError,
+  } = useStandardAnswerCategories();
 
-  if (!slackChannelConfig) {
-    return (
-      <ErrorCallout
-        errorTitle="Something went wrong :("
-        errorMsg={`Did not find Slack Channel config with ID: ${params.id}`}
-      />
-    );
-  }
+  const isLoading =
+    isChannelsLoading ||
+    isDocSetsLoading ||
+    isAgentsLoading ||
+    (isPaidEnterprise && isStdAnswerLoading);
 
-  if (!documentSetsResponse.ok) {
-    return (
-      <ErrorCallout
-        errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch document sets - ${await documentSetsResponse.text()}`}
-      />
-    );
-  }
-  const response = await documentSetsResponse.json();
-  const documentSets = response as DocumentSetSummary[];
+  const slackChannelConfig = slackChannelConfigs?.find(
+    (config) => config.id === Number(id)
+  );
 
-  if (agentsFetchError) {
-    return (
-      <ErrorCallout
-        errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch personas - ${agentsFetchError}`}
-      />
-    );
-  }
+  const title = slackChannelConfig?.is_default
+    ? "Edit Default Slack Config"
+    : "Edit Slack Channel Config";
 
   return (
     <SettingsLayouts.Root>
-      <InstantSSRAutoRefresh />
       <SettingsLayouts.Header
         icon={SvgSlack}
-        title={
-          slackChannelConfig.is_default
-            ? "Edit Default Slack Config"
-            : "Edit Slack Channel Config"
-        }
+        title={title}
         separator
         backButton
       />
       <SettingsLayouts.Body>
-        <SlackChannelConfigCreationForm
-          slack_bot_id={slackChannelConfig.slack_bot_id}
-          documentSets={documentSets}
-          personas={assistants}
-          standardAnswerCategoryResponse={eeStandardAnswerCategoryResponse}
-          existingSlackChannelConfig={slackChannelConfig}
-        />
+        {isLoading ? (
+          <SimpleLoader />
+        ) : channelsError || !slackChannelConfigs ? (
+          <ErrorCallout
+            errorTitle="Something went wrong :("
+            errorMsg={`Failed to fetch Slack Channels - ${
+              channelsError?.message ?? "unknown error"
+            }`}
+          />
+        ) : !slackChannelConfig ? (
+          <ErrorCallout
+            errorTitle="Something went wrong :("
+            errorMsg={`Did not find Slack Channel config with ID: ${id}`}
+          />
+        ) : docSetsError || !documentSets ? (
+          <ErrorCallout
+            errorTitle="Something went wrong :("
+            errorMsg={`Failed to fetch document sets - ${
+              docSetsError?.message ?? "unknown error"
+            }`}
+          />
+        ) : agentsError ? (
+          <ErrorCallout
+            errorTitle="Something went wrong :("
+            errorMsg={`Failed to fetch agents - ${
+              agentsError?.message ?? "unknown error"
+            }`}
+          />
+        ) : (
+          <SlackChannelConfigCreationForm
+            slack_bot_id={slackChannelConfig.slack_bot_id}
+            documentSets={documentSets}
+            personas={agents}
+            standardAnswerCategoryResponse={
+              isPaidEnterprise
+                ? {
+                    paidEnterpriseFeaturesEnabled: true,
+                    categories: standardAnswerCategories ?? [],
+                    ...(stdAnswerError
+                      ? { error: { message: String(stdAnswerError) } }
+                      : {}),
+                  }
+                : { paidEnterpriseFeaturesEnabled: false }
+            }
+            existingSlackChannelConfig={slackChannelConfig}
+          />
+        )}
       </SettingsLayouts.Body>
     </SettingsLayouts.Root>
   );
 }
 
-export default EditslackChannelConfigPage;
+export default function Page(props: { params: Promise<{ id: string }> }) {
+  const params = use(props.params);
+
+  return <EditSlackChannelConfigContent id={params.id} />;
+}
diff --git a/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx b/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
index 8ef6cf32a28..99d6447765f 100644
--- a/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/channels/new/page.tsx
@@ -1,53 +1,109 @@
-import { SlackChannelConfigCreationForm } from "../SlackChannelConfigCreationForm";
-import { fetchSS } from "@/lib/utilsSS";
+"use client";
+
+import { use, useEffect } from "react";
+import { SlackChannelConfigCreationForm } from "@/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import { DocumentSetSummary } from "@/lib/types";
-import { fetchAgentsSS } from "@/lib/agentsSS";
-import { getStandardAnswerCategoriesIfEE } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
-import { redirect } from "next/navigation";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { SvgSlack } from "@opal/icons";
+import { useDocumentSets } from "@/app/admin/documents/sets/hooks";
+import { useAgents } from "@/hooks/useAgents";
+import { useStandardAnswerCategories } from "@/app/ee/admin/standard-answer/hooks";
+import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
+import type { StandardAnswerCategoryResponse } from "@/components/standardAnswers/getStandardAnswerCategoriesIfEE";
+import { useRouter } from "next/navigation";
 
-async function NewChannelConfigPage(props: {
-  params: Promise<{ "bot-id": string }>;
-}) {
-  const unwrappedParams = await props.params;
-  const slack_bot_id_raw = unwrappedParams?.["bot-id"] || null;
-  const slack_bot_id = slack_bot_id_raw
-    ? parseInt(slack_bot_id_raw as string, 10)
-    : null;
-  if (!slack_bot_id || isNaN(slack_bot_id)) {
-    redirect("/admin/bots");
-    return null;
-  }
+function NewChannelConfigContent({ slackBotId }: { slackBotId: number }) {
+  const isPaidEnterprise = usePaidEnterpriseFeaturesEnabled();
 
-  const [documentSetsResponse, agentsResponse, standardAnswerCategoryResponse] =
-    await Promise.all([
-      fetchSS("/manage/document-set") as Promise<Response>,
-      fetchAgentsSS(),
-      getStandardAnswerCategoriesIfEE(),
-    ]);
+  const {
+    data: documentSets,
+    isLoading: isDocSetsLoading,
+    error: docSetsError,
+  } = useDocumentSets();
 
-  if (!documentSetsResponse.ok) {
+  const {
+    agents,
+    isLoading: isAgentsLoading,
+    error: agentsError,
+  } = useAgents();
+
+  const {
+    data: standardAnswerCategories,
+    isLoading: isStdAnswerLoading,
+    error: stdAnswerError,
+  } = useStandardAnswerCategories();
+
+  if (
+    isDocSetsLoading ||
+    isAgentsLoading ||
+    (isPaidEnterprise && isStdAnswerLoading)
+  ) {
+    return <SimpleLoader />;
+  }
+
+  if (docSetsError || !documentSets) {
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch document sets - ${await documentSetsResponse.text()}`}
+        errorMsg={`Failed to fetch document sets - ${
+          docSetsError?.message ?? "unknown error"
+        }`}
       />
     );
   }
-  const documentSets =
-    (await documentSetsResponse.json()) as DocumentSetSummary[];
 
-  if (agentsResponse[1]) {
+  if (agentsError) {
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch agents - ${agentsResponse[1]}`}
+        errorMsg={`Failed to fetch agents - ${
+          agentsError?.message ?? "unknown error"
+        }`}
       />
     );
   }
 
+  const standardAnswerCategoryResponse: StandardAnswerCategoryResponse =
+    isPaidEnterprise
+      ? {
+          paidEnterpriseFeaturesEnabled: true,
+          categories: standardAnswerCategories ?? [],
+          ...(stdAnswerError
+            ? { error: { message: String(stdAnswerError) } }
+            : {}),
+        }
+      : { paidEnterpriseFeaturesEnabled: false };
+
+  return (
+    <SlackChannelConfigCreationForm
+      slack_bot_id={slackBotId}
+      documentSets={documentSets}
+      personas={agents}
+      standardAnswerCategoryResponse={standardAnswerCategoryResponse}
+    />
+  );
+}
+
+export default function Page(props: { params: Promise<{ "bot-id": string }> }) {
+  const unwrappedParams = use(props.params);
+  const router = useRouter();
+
+  const slack_bot_id_raw = unwrappedParams?.["bot-id"] || null;
+  const slack_bot_id = slack_bot_id_raw
+    ? parseInt(slack_bot_id_raw as string, 10)
+    : null;
+
+  useEffect(() => {
+    if (!slack_bot_id || isNaN(slack_bot_id)) {
+      router.replace("/admin/bots");
+    }
+  }, [slack_bot_id, router]);
+
+  if (!slack_bot_id || isNaN(slack_bot_id)) {
+    return null;
+  }
+
   return (
     <SettingsLayouts.Root>
       <SettingsLayouts.Header
@@ -57,15 +113,8 @@ async function NewChannelConfigPage(props: {
         backButton
       />
       <SettingsLayouts.Body>
-        <SlackChannelConfigCreationForm
-          slack_bot_id={slack_bot_id}
-          documentSets={documentSets}
-          personas={agentsResponse[0]}
-          standardAnswerCategoryResponse={standardAnswerCategoryResponse}
-        />
+        <NewChannelConfigContent slackBotId={slack_bot_id} />
       </SettingsLayouts.Body>
     </SettingsLayouts.Root>
   );
 }
-
-export default NewChannelConfigPage;
diff --git a/web/src/app/admin/bots/[bot-id]/page.tsx b/web/src/app/admin/bots/[bot-id]/page.tsx
index 8657082837a..a5eabe80b58 100644
--- a/web/src/app/admin/bots/[bot-id]/page.tsx
+++ b/web/src/app/admin/bots/[bot-id]/page.tsx
@@ -1,82 +1,62 @@
 "use client";
 
 import { use } from "react";
-import BackButton from "@/refresh-components/buttons/BackButton";
 import { ErrorCallout } from "@/components/ErrorCallout";
-import { ThreeDotsLoader } from "@/components/Loading";
-import { InstantSSRAutoRefresh } from "@/components/SSRAutoRefresh";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import SlackChannelConfigsTable from "./SlackChannelConfigsTable";
 import { useSlackBot, useSlackChannelConfigsByBot } from "./hooks";
 import { ExistingSlackBotForm } from "../SlackBotUpdateForm";
-import Separator from "@/refresh-components/Separator";
-
-function SlackBotEditPage({
-  params,
-}: {
-  params: Promise<{ "bot-id": string }>;
-}) {
-  // Unwrap the params promise
-  const unwrappedParams = use(params);
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { SvgSlack } from "@opal/icons";
+import { getErrorMsg } from "@/lib/error";
 
+function SlackBotEditContent({ botId }: { botId: string }) {
   const {
     data: slackBot,
     isLoading: isSlackBotLoading,
     error: slackBotError,
     refreshSlackBot,
-  } = useSlackBot(Number(unwrappedParams["bot-id"]));
+  } = useSlackBot(Number(botId));
 
   const {
     data: slackChannelConfigs,
     isLoading: isSlackChannelConfigsLoading,
     error: slackChannelConfigsError,
     refreshSlackChannelConfigs,
-  } = useSlackChannelConfigsByBot(Number(unwrappedParams["bot-id"]));
+  } = useSlackChannelConfigsByBot(Number(botId));
 
   if (isSlackBotLoading || isSlackChannelConfigsLoading) {
-    return (
-      <div className="flex justify-center items-center h-screen">
-        <ThreeDotsLoader />
-      </div>
-    );
+    return <SimpleLoader />;
   }
 
   if (slackBotError || !slackBot) {
-    const errorMsg =
-      slackBotError?.info?.message ||
-      slackBotError?.info?.detail ||
-      "An unknown error occurred";
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch Slack Bot ${unwrappedParams["bot-id"]}: ${errorMsg}`}
+        errorMsg={`Failed to fetch Slack Bot ${botId}: ${getErrorMsg(
+          slackBotError
+        )}`}
       />
     );
   }
 
   if (slackChannelConfigsError || !slackChannelConfigs) {
-    const errorMsg =
-      slackChannelConfigsError?.info?.message ||
-      slackChannelConfigsError?.info?.detail ||
-      "An unknown error occurred";
     return (
       <ErrorCallout
         errorTitle="Something went wrong :("
-        errorMsg={`Failed to fetch Slack Bot ${unwrappedParams["bot-id"]}: ${errorMsg}`}
+        errorMsg={`Failed to fetch Slack Bot ${botId}: ${getErrorMsg(
+          slackChannelConfigsError
+        )}`}
       />
     );
   }
 
   return (
     <>
-      <InstantSSRAutoRefresh />
-
-      <BackButton routerOverride="/admin/bots" />
-
       <ExistingSlackBotForm
         existingSlackBot={slackBot}
         refreshSlackBot={refreshSlackBot}
       />
-      <Separator />
 
       <div className="mt-8">
         <SlackChannelConfigsTable
@@ -94,9 +74,19 @@ export default function Page({
 }: {
   params: Promise<{ "bot-id": string }>;
 }) {
+  const unwrappedParams = use(params);
+
   return (
-    <>
-      <SlackBotEditPage params={params} />
-    </>
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header
+        icon={SvgSlack}
+        title="Edit Slack Bot"
+        backButton
+        separator
+      />
+      <SettingsLayouts.Body>
+        <SlackBotEditContent botId={unwrappedParams["bot-id"]} />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/app/admin/bots/new/page.tsx b/web/src/app/admin/bots/new/page.tsx
index a0daa222a98..18b1a460ca3 100644
--- a/web/src/app/admin/bots/new/page.tsx
+++ b/web/src/app/admin/bots/new/page.tsx
@@ -1,12 +1,7 @@
-import BackButton from "@/refresh-components/buttons/BackButton";
-import { NewSlackBotForm } from "../SlackBotCreationForm";
+"use client";
 
-export default async function NewSlackBotPage() {
-  return (
-    <>
-      <BackButton routerOverride="/admin/bots" />
+import { NewSlackBotForm } from "../SlackBotCreationForm";
 
-      <NewSlackBotForm />
-    </>
-  );
+export default function Page() {
+  return <NewSlackBotForm />;
 }
diff --git a/web/src/lib/error.ts b/web/src/lib/error.ts
new file mode 100644
index 00000000000..2acab0ecb99
--- /dev/null
+++ b/web/src/lib/error.ts
@@ -0,0 +1,10 @@
+/**
+ * Extract a human-readable error message from an SWR error object.
+ * SWR errors from `errorHandlingFetcher` attach `info.message` or `info.detail`.
+ */
+export function getErrorMsg(
+  error: { info?: { message?: string; detail?: string } } | null | undefined,
+  fallback = "An unknown error occurred"
+): string {
+  return error?.info?.message || error?.info?.detail || fallback;
+}

From 2899be4c5e5bdaf4b2efd9596afbf30fa89aedc0 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Sun, 8 Mar 2026 13:53:11 -0700
Subject: [PATCH 177/267] fix: remove unnecessary multitenant check in
 migration (#9172)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 .../3b9f09038764_add_read_only_kg_user.py     | 88 +++++++++----------
 1 file changed, 40 insertions(+), 48 deletions(-)

diff --git a/backend/alembic_tenants/versions/3b9f09038764_add_read_only_kg_user.py b/backend/alembic_tenants/versions/3b9f09038764_add_read_only_kg_user.py
index d46c95c9d37..a91e0f8a589 100644
--- a/backend/alembic_tenants/versions/3b9f09038764_add_read_only_kg_user.py
+++ b/backend/alembic_tenants/versions/3b9f09038764_add_read_only_kg_user.py
@@ -11,7 +11,6 @@
 from alembic import op
 from onyx.configs.app_configs import DB_READONLY_PASSWORD
 from onyx.configs.app_configs import DB_READONLY_USER
-from shared_configs.configs import MULTI_TENANT
 
 
 # revision identifiers, used by Alembic.
@@ -22,59 +21,52 @@
 
 
 def upgrade() -> None:
-    if MULTI_TENANT:
+    # Enable pg_trgm extension if not already enabled
+    op.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm")
 
-        # Enable pg_trgm extension if not already enabled
-        op.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm")
+    # Create the read-only db user if it does not already exist.
+    if not (DB_READONLY_USER and DB_READONLY_PASSWORD):
+        raise Exception("DB_READONLY_USER or DB_READONLY_PASSWORD is not set")
 
-        # Create read-only db user here only in multi-tenant mode. For single-tenant mode,
-        # the user is created in the standard migration.
-        if not (DB_READONLY_USER and DB_READONLY_PASSWORD):
-            raise Exception("DB_READONLY_USER or DB_READONLY_PASSWORD is not set")
-
-        op.execute(
-            text(
-                f"""
-                DO $$
-                BEGIN
-                    -- Check if the read-only user already exists
-                    IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '{DB_READONLY_USER}') THEN
-                        -- Create the read-only user with the specified password
-                        EXECUTE format('CREATE USER %I WITH PASSWORD %L', '{DB_READONLY_USER}', '{DB_READONLY_PASSWORD}');
-                        -- First revoke all privileges to ensure a clean slate
-                        EXECUTE format('REVOKE ALL ON DATABASE %I FROM %I', current_database(), '{DB_READONLY_USER}');
-                        -- Grant only the CONNECT privilege to allow the user to connect to the database
-                        -- but not perform any operations without additional specific grants
-                        EXECUTE format('GRANT CONNECT ON DATABASE %I TO %I', current_database(), '{DB_READONLY_USER}');
-                    END IF;
-                END
-                $$;
-                """
-            )
-        )
-
-
-def downgrade() -> None:
-    if MULTI_TENANT:
-        # Drop read-only db user here only in single tenant mode. For multi-tenant mode,
-        # the user is dropped in the alembic_tenants migration.
-
-        op.execute(
-            text(
-                f"""
+    op.execute(
+        text(
+            f"""
             DO $$
             BEGIN
-                IF EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '{DB_READONLY_USER}') THEN
-                    -- First revoke all privileges from the database
+                -- Check if the read-only user already exists
+                IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '{DB_READONLY_USER}') THEN
+                    -- Create the read-only user with the specified password
+                    EXECUTE format('CREATE USER %I WITH PASSWORD %L', '{DB_READONLY_USER}', '{DB_READONLY_PASSWORD}');
+                    -- First revoke all privileges to ensure a clean slate
                     EXECUTE format('REVOKE ALL ON DATABASE %I FROM %I', current_database(), '{DB_READONLY_USER}');
-                    -- Then revoke all privileges from the public schema
-                    EXECUTE format('REVOKE ALL ON SCHEMA public FROM %I', '{DB_READONLY_USER}');
-                    -- Then drop the user
-                    EXECUTE format('DROP USER %I', '{DB_READONLY_USER}');
+                    -- Grant only the CONNECT privilege to allow the user to connect to the database
+                    -- but not perform any operations without additional specific grants
+                    EXECUTE format('GRANT CONNECT ON DATABASE %I TO %I', current_database(), '{DB_READONLY_USER}');
                 END IF;
             END
             $$;
-        """
-            )
+            """
+        )
+    )
+
+
+def downgrade() -> None:
+    op.execute(
+        text(
+            f"""
+        DO $$
+        BEGIN
+            IF EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '{DB_READONLY_USER}') THEN
+                -- First revoke all privileges from the database
+                EXECUTE format('REVOKE ALL ON DATABASE %I FROM %I', current_database(), '{DB_READONLY_USER}');
+                -- Then revoke all privileges from the public schema
+                EXECUTE format('REVOKE ALL ON SCHEMA public FROM %I', '{DB_READONLY_USER}');
+                -- Then drop the user
+                EXECUTE format('DROP USER %I', '{DB_READONLY_USER}');
+            END IF;
+        END
+        $$;
+    """
         )
-        op.execute(text("DROP EXTENSION IF EXISTS pg_trgm"))
+    )
+    op.execute(text("DROP EXTENSION IF EXISTS pg_trgm"))

From 9d7dc3da21309bb84e85906de8165e0ba5532039 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Sun, 8 Mar 2026 16:35:59 -0700
Subject: [PATCH 178/267] fix: ph ssl upgrade on redirect for local development
 (#9175)

---
 web/next.config.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/web/next.config.js b/web/next.config.js
index 75e16a3bbfb..20ac633390a 100644
--- a/web/next.config.js
+++ b/web/next.config.js
@@ -8,7 +8,8 @@ const cspHeader = `
     base-uri 'self';
     form-action 'self';
     ${
-      process.env.NEXT_PUBLIC_CLOUD_ENABLED === "true"
+      process.env.NEXT_PUBLIC_CLOUD_ENABLED === "true" &&
+      process.env.NODE_ENV !== "development"
         ? "upgrade-insecure-requests;"
         : ""
     }

From 5fe7a474db480c92ef8edb2358416a6a4cf5d77e Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 09:32:14 -0700
Subject: [PATCH 179/267] chore: update decryption utility (#9176)

---
 backend/scripts/decrypt.py | 105 ++++++++++++++++++++++++++-----------
 1 file changed, 75 insertions(+), 30 deletions(-)

diff --git a/backend/scripts/decrypt.py b/backend/scripts/decrypt.py
index 40e6413564e..4aebbd4d885 100644
--- a/backend/scripts/decrypt.py
+++ b/backend/scripts/decrypt.py
@@ -1,48 +1,93 @@
+"""Decrypt a raw hex-encoded credential value.
+
+Usage:
+    python -m scripts.decrypt <hex_value>
+    python -m scripts.decrypt <hex_value> --key "my-encryption-key"
+    python -m scripts.decrypt <hex_value> --key ""
+
+Pass --key "" to skip decryption and just decode the raw bytes as UTF-8.
+Omit --key to use the current ENCRYPTION_KEY_SECRET from the environment.
+"""
+
+import argparse
 import binascii
 import json
+import os
 import sys
 
-from onyx.utils.encryption import decrypt_bytes_to_string
+parent_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(parent_dir)
 
+from onyx.utils.encryption import decrypt_bytes_to_string  # noqa: E402
+from onyx.utils.variable_functionality import global_version  # noqa: E402
 
-def decrypt_raw_credential(encrypted_value: str) -> None:
-    """Decrypt and display a raw encrypted credential value
+
+def decrypt_raw_credential(encrypted_value: str, key: str | None = None) -> None:
+    """Decrypt and display a raw encrypted credential value.
 
     Args:
-        encrypted_value: The hex encoded encrypted credential value
+        encrypted_value: The hex-encoded encrypted credential value.
+        key: Encryption key to use. None means use ENCRYPTION_KEY_SECRET,
+             empty string means just decode as UTF-8.
     """
-    try:
-        # If string starts with 'x', remove it as it's just a prefix indicating hex
-        if encrypted_value.startswith("x"):
-            encrypted_value = encrypted_value[1:]
-        elif encrypted_value.startswith("\\x"):
-            encrypted_value = encrypted_value[2:]
+    # Strip common hex prefixes
+    if encrypted_value.startswith("\\x"):
+        encrypted_value = encrypted_value[2:]
+    elif encrypted_value.startswith("x"):
+        encrypted_value = encrypted_value[1:]
+    print(encrypted_value)
 
-        # Convert hex string to bytes
-        encrypted_bytes = binascii.unhexlify(encrypted_value)
+    try:
+        raw_bytes = binascii.unhexlify(encrypted_value)
+    except binascii.Error:
+        print("Error: Invalid hex-encoded string")
+        sys.exit(1)
 
-        # Decrypt the bytes
-        decrypted_str = decrypt_bytes_to_string(encrypted_bytes)
+    if key == "":
+        # Empty key → just decode as UTF-8, no decryption
+        try:
+            decrypted_str = raw_bytes.decode("utf-8")
+        except UnicodeDecodeError as e:
+            print(f"Error decoding bytes as UTF-8: {e}")
+            sys.exit(1)
+    else:
+        print(key)
+        try:
+            decrypted_str = decrypt_bytes_to_string(raw_bytes, key=key)
+        except Exception as e:
+            print(f"Error decrypting value: {e}")
+            sys.exit(1)
 
-        # Parse and pretty print the decrypted JSON
-        decrypted_json = json.loads(decrypted_str)
-        print("Decrypted credential value:")
-        print(json.dumps(decrypted_json, indent=2))
+    # Try to pretty-print as JSON, otherwise print raw
+    try:
+        parsed = json.loads(decrypted_str)
+        print(json.dumps(parsed, indent=2))
+    except json.JSONDecodeError:
+        print(decrypted_str)
 
-    except binascii.Error:
-        print("Error: Invalid hex encoded string")
 
-    except json.JSONDecodeError as e:
-        print(f"Decrypted raw value (not JSON): {e}")
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Decrypt a hex-encoded credential value."
+    )
+    parser.add_argument(
+        "value",
+        help="Hex-encoded encrypted value to decrypt.",
+    )
+    parser.add_argument(
+        "--key",
+        default=None,
+        help=(
+            "Encryption key. Omit to use ENCRYPTION_KEY_SECRET from env. "
+            'Pass "" (empty) to just decode as UTF-8 without decryption.'
+        ),
+    )
+    args = parser.parse_args()
 
-    except Exception as e:
-        print(f"Error decrypting value: {e}")
+    global_version.set_ee()
+    decrypt_raw_credential(args.value, key=args.key)
+    global_version.unset_ee()
 
 
 if __name__ == "__main__":
-    if len(sys.argv) != 2:
-        print("Usage: python decrypt.py <hex_encoded_encrypted_value>")
-        sys.exit(1)
-
-    encrypted_value = sys.argv[1]
-    decrypt_raw_credential(encrypted_value)
+    main()

From 2ebccea6d6da4e5cdfa943d0e3a3fe151ac96d27 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 09:32:28 -0700
Subject: [PATCH 180/267] fix: move available context tokens to
 useChatController and remove arbitrary 50% cap (#9174)

---
 web/src/app/app/projects/projectsService.ts |  6 +-
 web/src/app/app/services/lib.tsx            |  6 +-
 web/src/hooks/useChatController.ts          | 70 +++++++++++++++----
 web/src/refresh-pages/AppPage.tsx           | 76 +++++----------------
 4 files changed, 79 insertions(+), 79 deletions(-)

diff --git a/web/src/app/app/projects/projectsService.ts b/web/src/app/app/projects/projectsService.ts
index cd5ee0be39f..ce1544d88dc 100644
--- a/web/src/app/app/projects/projectsService.ts
+++ b/web/src/app/app/projects/projectsService.ts
@@ -308,15 +308,15 @@ export async function getProjectTokenCount(projectId: number): Promise<number> {
 
 export async function getMaxSelectedDocumentTokens(
   personaId: number
-): Promise<number> {
+): Promise<number | null> {
   const response = await fetch(
     `/api/chat/max-selected-document-tokens?persona_id=${personaId}`
   );
   if (!response.ok) {
-    return 128_000;
+    return null;
   }
   const json = await response.json();
-  return (json?.max_tokens as number) ?? 128_000;
+  return (json?.max_tokens as number) ?? null;
 }
 
 export async function moveChatSession(
diff --git a/web/src/app/app/services/lib.tsx b/web/src/app/app/services/lib.tsx
index b89a29741e3..0d4dda79b63 100644
--- a/web/src/app/app/services/lib.tsx
+++ b/web/src/app/app/services/lib.tsx
@@ -288,15 +288,15 @@ export async function deleteAllChatSessions() {
 
 export async function getAvailableContextTokens(
   chatSessionId: string
-): Promise<number> {
+): Promise<number | null> {
   const response = await fetch(
     `/api/chat/available-context-tokens/${chatSessionId}`
   );
   if (!response.ok) {
-    return 0;
+    return null;
   }
   const data = (await response.json()) as { available_tokens: number };
-  return data?.available_tokens ?? 0;
+  return data?.available_tokens ?? null;
 }
 
 export function processRawChatHistory(
diff --git a/web/src/hooks/useChatController.ts b/web/src/hooks/useChatController.ts
index 633a6d95a2b..a8da94afcd1 100644
--- a/web/src/hooks/useChatController.ts
+++ b/web/src/hooks/useChatController.ts
@@ -2,9 +2,12 @@
 
 import {
   buildChatUrl,
+  getAvailableContextTokens,
   nameChatSession,
   updateLlmOverrideForChatSession,
 } from "@/app/app/services/lib";
+import { getMaxSelectedDocumentTokens } from "@/app/app/projects/projectsService";
+import { DEFAULT_CONTEXT_TOKENS } from "@/lib/constants";
 import { StreamStopInfo } from "@/lib/search/interfaces";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { Route } from "next";
@@ -194,9 +197,6 @@ export default function useChatController({
 
   const navigatingAway = useRef(false);
 
-  // Local state that doesn't need to be in the store
-  const [_maxTokens, setMaxTokens] = useState<number>(4096);
-
   // Sync store state changes
   useEffect(() => {
     if (currentSessionId) {
@@ -1067,21 +1067,59 @@ export default function useChatController({
     handleSlackChatRedirect();
   }, [searchParams, router]);
 
-  // fetch # of allowed document tokens for the selected Persona
+  // Available context tokens: if a chat session exists, fetch from the session
+  // API (dynamic per session/model). Otherwise derive from the persona's max
+  // document tokens. The backend already accounts for system prompt, tools,
+  // and user-message reservations.
+  const [availableContextTokens, setAvailableContextTokens] = useState<number>(
+    DEFAULT_CONTEXT_TOKENS
+  );
+
   useEffect(() => {
-    if (!liveAgent?.id) return; // avoid calling with undefined persona id
+    if (!llmManager.hasAnyProvider) return;
 
-    async function fetchMaxTokens() {
-      const response = await fetch(
-        `/api/chat/max-selected-document-tokens?persona_id=${liveAgent?.id}`
-      );
-      if (response.ok) {
-        const maxTokens = (await response.json()).max_tokens as number;
-        setMaxTokens(maxTokens);
+    let cancelled = false;
+
+    const setIfActive = (tokens: number) => {
+      if (!cancelled) setAvailableContextTokens(tokens);
+    };
+
+    // Prefer the Zustand session ID, but fall back to the URL-derived prop
+    // so we don't incorrectly take the persona path while the store is
+    // still initialising on navigation to an existing chat.
+    const sessionId = currentSessionId || existingChatSessionId;
+
+    (async () => {
+      try {
+        if (sessionId) {
+          const available = await getAvailableContextTokens(sessionId);
+          setIfActive(available ?? DEFAULT_CONTEXT_TOKENS);
+          return;
+        }
+
+        const personaId = liveAgent?.id;
+        if (personaId == null) {
+          setIfActive(DEFAULT_CONTEXT_TOKENS);
+          return;
+        }
+
+        const maxTokens = await getMaxSelectedDocumentTokens(personaId);
+        setIfActive(maxTokens ?? DEFAULT_CONTEXT_TOKENS);
+      } catch (e) {
+        console.error("Failed to fetch available context tokens:", e);
+        setIfActive(DEFAULT_CONTEXT_TOKENS);
       }
-    }
-    fetchMaxTokens();
-  }, [liveAgent]);
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    currentSessionId,
+    existingChatSessionId,
+    liveAgent?.id,
+    llmManager.hasAnyProvider,
+  ]);
 
   // check if there's an image file in the message history so that we know
   // which LLMs are available to use
@@ -1110,5 +1148,7 @@ export default function useChatController({
     onSubmit,
     stopGenerating,
     handleMessageSpecificFileUpload,
+    // data
+    availableContextTokens,
   };
 }
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index fecda858b29..cf62181a55e 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -1,10 +1,7 @@
 "use client";
 
 import { redirect, useRouter, useSearchParams } from "next/navigation";
-import {
-  personaIncludesRetrieval,
-  getAvailableContextTokens,
-} from "@/app/app/services/lib";
+import { personaIncludesRetrieval } from "@/app/app/services/lib";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "@/hooks/useToast";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
@@ -56,10 +53,7 @@ import ChatScrollContainer, {
 } from "@/sections/chat/ChatScrollContainer";
 import ProjectContextPanel from "@/app/app/components/projects/ProjectContextPanel";
 import { useProjectsContext } from "@/providers/ProjectsContext";
-import {
-  getProjectTokenCount,
-  getMaxSelectedDocumentTokens,
-} from "@/app/app/projects/projectsService";
+import { getProjectTokenCount } from "@/app/app/projects/projectsService";
 import ProjectChatSessionList from "@/app/app/components/projects/ProjectChatSessionList";
 import { cn } from "@/lib/utils";
 import Suggestions from "@/sections/Suggestions";
@@ -70,7 +64,6 @@ import * as AppLayouts from "@/layouts/app-layouts";
 import { SvgChevronDown, SvgFileText } from "@opal/icons";
 import { Button } from "@opal/components";
 import Spacer from "@/refresh-components/Spacer";
-import { DEFAULT_CONTEXT_TOKENS } from "@/lib/constants";
 import useAppFocus from "@/hooks/useAppFocus";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import WelcomeMessage from "@/app/app/components/WelcomeMessage";
@@ -367,18 +360,22 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
   const autoScrollEnabled = user?.preferences?.auto_scroll !== false;
   const isStreaming = currentChatState === "streaming";
 
-  const { onSubmit, stopGenerating, handleMessageSpecificFileUpload } =
-    useChatController({
-      filterManager,
-      llmManager,
-      availableAgents: agents,
-      liveAgent,
-      existingChatSessionId: currentChatSessionId,
-      selectedDocuments,
-      searchParams,
-      resetInputBar,
-      setSelectedAgentFromId,
-    });
+  const {
+    onSubmit,
+    stopGenerating,
+    handleMessageSpecificFileUpload,
+    availableContextTokens,
+  } = useChatController({
+    filterManager,
+    llmManager,
+    availableAgents: agents,
+    liveAgent,
+    existingChatSessionId: currentChatSessionId,
+    selectedDocuments,
+    searchParams,
+    resetInputBar,
+    setSelectedAgentFromId,
+  });
 
   const { onMessageSelection, currentSessionFileTokenCount } =
     useChatSessionController({
@@ -595,43 +592,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
     };
   }, [currentChatSessionId, currentProjectId, currentProjectDetails?.files]);
 
-  // Available context tokens source of truth:
-  // - If a chat session exists, fetch from session API (dynamic per session/model)
-  // - If no session, derive from the default/current persona's max document tokens
-  const [availableContextTokens, setAvailableContextTokens] = useState<number>(
-    DEFAULT_CONTEXT_TOKENS * 0.5
-  );
-  useEffect(() => {
-    let cancelled = false;
-    async function run() {
-      try {
-        if (currentChatSessionId) {
-          const available =
-            await getAvailableContextTokens(currentChatSessionId);
-          const capped_context_tokens =
-            (available ?? DEFAULT_CONTEXT_TOKENS) * 0.5;
-          if (!cancelled) setAvailableContextTokens(capped_context_tokens);
-        } else {
-          const personaId = (selectedAgent || liveAgent)?.id;
-          if (personaId !== undefined && personaId !== null) {
-            const maxTokens = await getMaxSelectedDocumentTokens(personaId);
-            const capped_context_tokens =
-              (maxTokens ?? DEFAULT_CONTEXT_TOKENS) * 0.5;
-            if (!cancelled) setAvailableContextTokens(capped_context_tokens);
-          } else if (!cancelled) {
-            setAvailableContextTokens(DEFAULT_CONTEXT_TOKENS * 0.5);
-          }
-        }
-      } catch (e) {
-        if (!cancelled) setAvailableContextTokens(DEFAULT_CONTEXT_TOKENS * 0.5);
-      }
-    }
-    run();
-    return () => {
-      cancelled = true;
-    };
-  }, [currentChatSessionId, selectedAgent?.id, liveAgent?.id]);
-
   // handle error case where no assistants are available
   // Only show this after agents have loaded to prevent flash during initial load
   if (noAgents && !isLoadingAgents) {

From 959cf444f8eab4224226ef3794c52581db838e8d Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 10:37:33 -0700
Subject: [PATCH 181/267] fix: set event hook for wrapping values into
 SensitiveValue (#9177)

---
 backend/onyx/db/models.py                     | 105 +++++++++++++-----
 backend/onyx/utils/sensitive.py               |  24 ++--
 .../db/test_credential_sensitive_value.py     |  90 +++++++++++++++
 .../slack_bot/__init__.py                     |   0
 .../slack_bot/test_slack_bot_crud.py          |  85 ++++++++++++++
 .../tools/test_oauth_config_crud.py           |  57 +++++++---
 .../tools/test_oauth_token_manager.py         |  10 +-
 .../tests/discord_bot/test_discord_bot_db.py  |   3 +-
 .../tests/unit/onyx/utils/test_sensitive.py   |  11 +-
 9 files changed, 329 insertions(+), 56 deletions(-)
 create mode 100644 backend/tests/external_dependency_unit/db/test_credential_sensitive_value.py
 create mode 100644 backend/tests/external_dependency_unit/slack_bot/__init__.py
 create mode 100644 backend/tests/external_dependency_unit/slack_bot/test_slack_bot_crud.py

diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index 3d3f734d4de..35f8db0bf4a 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -36,9 +36,11 @@
 from sqlalchemy import text
 from sqlalchemy import UniqueConstraint
 from sqlalchemy.dialects import postgresql
+from sqlalchemy import event
 from sqlalchemy.engine.interfaces import Dialect
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm import Mapped
+from sqlalchemy.orm import Mapper
 from sqlalchemy.orm import mapped_column
 from sqlalchemy.orm import relationship
 from sqlalchemy.types import LargeBinary
@@ -117,10 +119,50 @@ class Base(DeclarativeBase):
     __abstract__ = True
 
 
-class EncryptedString(TypeDecorator):
+class _EncryptedBase(TypeDecorator):
+    """Base for encrypted column types that wrap values in SensitiveValue."""
+
     impl = LargeBinary
-    # This type's behavior is fully deterministic and doesn't depend on any external factors.
     cache_ok = True
+    _is_json: bool = False
+
+    def wrap_raw(self, value: Any) -> SensitiveValue:
+        """Encrypt a raw value and wrap it in SensitiveValue.
+
+        Called by the attribute set event so the Python-side type is always
+        SensitiveValue, regardless of whether the value was loaded from the DB
+        or assigned in application code.
+        """
+        if self._is_json:
+            if not isinstance(value, dict):
+                raise TypeError(
+                    f"EncryptedJson column expected dict, got {type(value).__name__}"
+                )
+            raw_str = json.dumps(value)
+        else:
+            if not isinstance(value, str):
+                raise TypeError(
+                    f"EncryptedString column expected str, got {type(value).__name__}"
+                )
+            raw_str = value
+        return SensitiveValue(
+            encrypted_bytes=encrypt_string_to_bytes(raw_str),
+            decrypt_fn=decrypt_bytes_to_string,
+            is_json=self._is_json,
+        )
+
+    def compare_values(self, x: Any, y: Any) -> bool:
+        if x is None or y is None:
+            return x == y
+        if isinstance(x, SensitiveValue):
+            x = x.get_value(apply_mask=False)
+        if isinstance(y, SensitiveValue):
+            y = y.get_value(apply_mask=False)
+        return x == y
+
+
+class EncryptedString(_EncryptedBase):
+    _is_json: bool = False
 
     def process_bind_param(
         self, value: str | SensitiveValue[str] | None, dialect: Dialect  # noqa: ARG002
@@ -144,20 +186,9 @@ def process_result_value(
             )
         return None
 
-    def compare_values(self, x: Any, y: Any) -> bool:
-        if x is None or y is None:
-            return x == y
-        if isinstance(x, SensitiveValue):
-            x = x.get_value(apply_mask=False)
-        if isinstance(y, SensitiveValue):
-            y = y.get_value(apply_mask=False)
-        return x == y
-
 
-class EncryptedJson(TypeDecorator):
-    impl = LargeBinary
-    # This type's behavior is fully deterministic and doesn't depend on any external factors.
-    cache_ok = True
+class EncryptedJson(_EncryptedBase):
+    _is_json: bool = True
 
     def process_bind_param(
         self,
@@ -165,9 +196,7 @@ def process_bind_param(
         dialect: Dialect,  # noqa: ARG002
     ) -> bytes | None:
         if value is not None:
-            # Handle both raw dicts and SensitiveValue wrappers
             if isinstance(value, SensitiveValue):
-                # Get raw value for storage
                 value = value.get_value(apply_mask=False)
             json_str = json.dumps(value)
             return encrypt_string_to_bytes(json_str)
@@ -184,14 +213,40 @@ def process_result_value(
             )
         return None
 
-    def compare_values(self, x: Any, y: Any) -> bool:
-        if x is None or y is None:
-            return x == y
-        if isinstance(x, SensitiveValue):
-            x = x.get_value(apply_mask=False)
-        if isinstance(y, SensitiveValue):
-            y = y.get_value(apply_mask=False)
-        return x == y
+
+_REGISTERED_ATTRS: set[str] = set()
+
+
+@event.listens_for(Mapper, "mapper_configured")
+def _register_sensitive_value_set_events(
+    mapper: Mapper,
+    class_: type,
+) -> None:
+    """Auto-wrap raw values in SensitiveValue when assigned to encrypted columns."""
+    for prop in mapper.column_attrs:
+        for col in prop.columns:
+            if isinstance(col.type, _EncryptedBase):
+                col_type = col.type
+                attr = getattr(class_, prop.key)
+
+                # Guard against double-registration (e.g. if mapper is
+                # re-configured in test setups)
+                attr_key = f"{class_.__qualname__}.{prop.key}"
+                if attr_key in _REGISTERED_ATTRS:
+                    continue
+                _REGISTERED_ATTRS.add(attr_key)
+
+                @event.listens_for(attr, "set", retval=True)
+                def _wrap_value(
+                    target: Any,  # noqa: ARG001
+                    value: Any,
+                    oldvalue: Any,  # noqa: ARG001
+                    initiator: Any,  # noqa: ARG001
+                    _col_type: _EncryptedBase = col_type,
+                ) -> Any:
+                    if value is not None and not isinstance(value, SensitiveValue):
+                        return _col_type.wrap_raw(value)
+                    return value
 
 
 class NullFilteredString(TypeDecorator):
diff --git a/backend/onyx/utils/sensitive.py b/backend/onyx/utils/sensitive.py
index 8d2fe1ec5a1..a6100bc872d 100644
--- a/backend/onyx/utils/sensitive.py
+++ b/backend/onyx/utils/sensitive.py
@@ -128,6 +128,8 @@ def get_value(
         value = self._decrypt()
 
         if not apply_mask:
+            # Callers must not mutate the returned dict — doing so would
+            # desync the cache from the encrypted bytes and the DB.
             return value
 
         # Apply masking
@@ -174,18 +176,20 @@ def __getitem__(self, key: Any) -> NoReturn:
         )
 
     def __eq__(self, other: Any) -> bool:
-        """Prevent direct comparison which might expose value."""
-        if isinstance(other, SensitiveValue):
-            # Compare encrypted bytes for equality check
-            return self._encrypted_bytes == other._encrypted_bytes
-        raise SensitiveAccessError(
-            "Cannot compare SensitiveValue with non-SensitiveValue. "
-            "Use .get_value(apply_mask=True/False) to access the value for comparison."
-        )
+        """Compare SensitiveValues by their decrypted content."""
+        # NOTE: if you attempt to compare a string/dict to a SensitiveValue,
+        # this comparison will return NotImplemented, which then evaluates to False.
+        # This is the convention and required for SQLAlchemy's attribute tracking.
+        if not isinstance(other, SensitiveValue):
+            return NotImplemented
+        return self._decrypt() == other._decrypt()
 
     def __hash__(self) -> int:
-        """Allow hashing based on encrypted bytes."""
-        return hash(self._encrypted_bytes)
+        """Hash based on decrypted content."""
+        value = self._decrypt()
+        if isinstance(value, dict):
+            return hash(json.dumps(value, sort_keys=True))
+        return hash(value)
 
     # Prevent JSON serialization
     def __json__(self) -> Any:
diff --git a/backend/tests/external_dependency_unit/db/test_credential_sensitive_value.py b/backend/tests/external_dependency_unit/db/test_credential_sensitive_value.py
new file mode 100644
index 00000000000..6337faa2249
--- /dev/null
+++ b/backend/tests/external_dependency_unit/db/test_credential_sensitive_value.py
@@ -0,0 +1,90 @@
+"""Test that Credential with nested JSON round-trips through SensitiveValue correctly.
+
+Exercises the full encrypt → store → read → decrypt → SensitiveValue path
+with realistic nested OAuth credential data, and verifies SQLAlchemy dirty
+tracking works with nested dict comparison.
+
+Requires a running Postgres instance.
+"""
+
+from sqlalchemy.orm import Session
+
+from onyx.configs.constants import DocumentSource
+from onyx.db.models import Credential
+from onyx.utils.sensitive import SensitiveValue
+
+# NOTE: this is not the real shape of a Drive credential,
+# but it is intended to test nested JSON credential handling
+
+_NESTED_CRED_JSON = {
+    "oauth_tokens": {
+        "access_token": "ya29.abc123",
+        "refresh_token": "1//xEg-def456",
+    },
+    "scopes": ["read", "write", "admin"],
+    "client_config": {
+        "client_id": "123.apps.googleusercontent.com",
+        "client_secret": "GOCSPX-secret",
+    },
+}
+
+
+def test_nested_credential_json_round_trip(db_session: Session) -> None:
+    """Nested OAuth credential survives encrypt → store → read → decrypt."""
+    credential = Credential(
+        source=DocumentSource.GOOGLE_DRIVE,
+        credential_json=_NESTED_CRED_JSON,
+    )
+    db_session.add(credential)
+    db_session.flush()
+
+    # Immediate read (no DB round-trip) — tests the set event wrapping
+    assert isinstance(credential.credential_json, SensitiveValue)
+    assert credential.credential_json.get_value(apply_mask=False) == _NESTED_CRED_JSON
+
+    # DB round-trip — tests process_result_value
+    db_session.expire(credential)
+    reloaded = credential.credential_json
+    assert isinstance(reloaded, SensitiveValue)
+    assert reloaded.get_value(apply_mask=False) == _NESTED_CRED_JSON
+
+    db_session.rollback()
+
+
+def test_reassign_same_nested_json_not_dirty(db_session: Session) -> None:
+    """Re-assigning the same nested dict should not mark the session dirty."""
+    credential = Credential(
+        source=DocumentSource.GOOGLE_DRIVE,
+        credential_json=_NESTED_CRED_JSON,
+    )
+    db_session.add(credential)
+    db_session.flush()
+
+    # Clear dirty state from the insert
+    db_session.expire(credential)
+    _ = credential.credential_json  # force reload
+
+    # Re-assign identical value
+    credential.credential_json = _NESTED_CRED_JSON  # type: ignore[assignment]
+    assert not db_session.is_modified(credential)
+
+    db_session.rollback()
+
+
+def test_assign_different_nested_json_is_dirty(db_session: Session) -> None:
+    """Assigning a different nested dict should mark the session dirty."""
+    credential = Credential(
+        source=DocumentSource.GOOGLE_DRIVE,
+        credential_json=_NESTED_CRED_JSON,
+    )
+    db_session.add(credential)
+    db_session.flush()
+
+    db_session.expire(credential)
+    _ = credential.credential_json  # force reload
+
+    modified_cred = {**_NESTED_CRED_JSON, "scopes": ["read"]}
+    credential.credential_json = modified_cred  # type: ignore[assignment]
+    assert db_session.is_modified(credential)
+
+    db_session.rollback()
diff --git a/backend/tests/external_dependency_unit/slack_bot/__init__.py b/backend/tests/external_dependency_unit/slack_bot/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/backend/tests/external_dependency_unit/slack_bot/test_slack_bot_crud.py b/backend/tests/external_dependency_unit/slack_bot/test_slack_bot_crud.py
new file mode 100644
index 00000000000..89d6215eedc
--- /dev/null
+++ b/backend/tests/external_dependency_unit/slack_bot/test_slack_bot_crud.py
@@ -0,0 +1,85 @@
+"""Tests that SlackBot CRUD operations return properly typed SensitiveValue fields.
+
+Regression test for the bug where insert_slack_bot/update_slack_bot returned
+objects with raw string tokens instead of SensitiveValue wrappers, causing
+'str object has no attribute get_value' errors in SlackBot.from_model().
+"""
+
+from uuid import uuid4
+
+from sqlalchemy.orm import Session
+
+from onyx.db.slack_bot import insert_slack_bot
+from onyx.db.slack_bot import update_slack_bot
+from onyx.server.manage.models import SlackBot
+from onyx.utils.sensitive import SensitiveValue
+
+
+def _unique(prefix: str) -> str:
+    return f"{prefix}-{uuid4().hex[:8]}"
+
+
+def test_insert_slack_bot_returns_sensitive_values(db_session: Session) -> None:
+    bot_token = _unique("xoxb-insert")
+    app_token = _unique("xapp-insert")
+    user_token = _unique("xoxp-insert")
+
+    slack_bot = insert_slack_bot(
+        db_session=db_session,
+        name=_unique("test-bot-insert"),
+        enabled=True,
+        bot_token=bot_token,
+        app_token=app_token,
+        user_token=user_token,
+    )
+
+    assert isinstance(slack_bot.bot_token, SensitiveValue)
+    assert isinstance(slack_bot.app_token, SensitiveValue)
+    assert isinstance(slack_bot.user_token, SensitiveValue)
+
+    assert slack_bot.bot_token.get_value(apply_mask=False) == bot_token
+    assert slack_bot.app_token.get_value(apply_mask=False) == app_token
+    assert slack_bot.user_token.get_value(apply_mask=False) == user_token
+
+    # Verify from_model works without error
+    pydantic_bot = SlackBot.from_model(slack_bot)
+    assert pydantic_bot.bot_token  # masked, but not empty
+    assert pydantic_bot.app_token
+
+
+def test_update_slack_bot_returns_sensitive_values(db_session: Session) -> None:
+    slack_bot = insert_slack_bot(
+        db_session=db_session,
+        name=_unique("test-bot-update"),
+        enabled=True,
+        bot_token=_unique("xoxb-update"),
+        app_token=_unique("xapp-update"),
+    )
+
+    new_bot_token = _unique("xoxb-update-new")
+    new_app_token = _unique("xapp-update-new")
+    new_user_token = _unique("xoxp-update-new")
+
+    updated = update_slack_bot(
+        db_session=db_session,
+        slack_bot_id=slack_bot.id,
+        name=_unique("test-bot-updated"),
+        enabled=False,
+        bot_token=new_bot_token,
+        app_token=new_app_token,
+        user_token=new_user_token,
+    )
+
+    assert isinstance(updated.bot_token, SensitiveValue)
+    assert isinstance(updated.app_token, SensitiveValue)
+    assert isinstance(updated.user_token, SensitiveValue)
+
+    assert updated.bot_token.get_value(apply_mask=False) == new_bot_token
+    assert updated.app_token.get_value(apply_mask=False) == new_app_token
+    assert updated.user_token.get_value(apply_mask=False) == new_user_token
+
+    # Verify from_model works without error
+    pydantic_bot = SlackBot.from_model(updated)
+    assert pydantic_bot.bot_token
+    assert pydantic_bot.app_token
+    assert pydantic_bot.user_token is not None
diff --git a/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py b/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py
index 094f13d45bb..4033577e047 100644
--- a/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py
+++ b/backend/tests/external_dependency_unit/tools/test_oauth_config_crud.py
@@ -148,8 +148,16 @@ def test_update_oauth_config_preserves_secrets(self, db_session: Session) -> Non
         )
 
         # Secrets should be preserved
-        assert updated_config.client_id == original_client_id
-        assert updated_config.client_secret == original_client_secret
+        assert updated_config.client_id is not None
+        assert original_client_id is not None
+        assert updated_config.client_id.get_value(
+            apply_mask=False
+        ) == original_client_id.get_value(apply_mask=False)
+        assert updated_config.client_secret is not None
+        assert original_client_secret is not None
+        assert updated_config.client_secret.get_value(
+            apply_mask=False
+        ) == original_client_secret.get_value(apply_mask=False)
         # But name should be updated
         assert updated_config.name == new_name
 
@@ -173,9 +181,14 @@ def test_update_oauth_config_clear_client_id(self, db_session: Session) -> None:
         )
 
         # client_id should be cleared (empty string)
-        assert updated_config.client_id == ""
+        assert updated_config.client_id is not None
+        assert updated_config.client_id.get_value(apply_mask=False) == ""
         # client_secret should be preserved
-        assert updated_config.client_secret == original_client_secret
+        assert updated_config.client_secret is not None
+        assert original_client_secret is not None
+        assert updated_config.client_secret.get_value(
+            apply_mask=False
+        ) == original_client_secret.get_value(apply_mask=False)
 
     def test_update_oauth_config_clear_client_secret(self, db_session: Session) -> None:
         """Test clearing client_secret while preserving client_id"""
@@ -190,9 +203,14 @@ def test_update_oauth_config_clear_client_secret(self, db_session: Session) -> N
         )
 
         # client_secret should be cleared (empty string)
-        assert updated_config.client_secret == ""
+        assert updated_config.client_secret is not None
+        assert updated_config.client_secret.get_value(apply_mask=False) == ""
         # client_id should be preserved
-        assert updated_config.client_id == original_client_id
+        assert updated_config.client_id is not None
+        assert original_client_id is not None
+        assert updated_config.client_id.get_value(
+            apply_mask=False
+        ) == original_client_id.get_value(apply_mask=False)
 
     def test_update_oauth_config_clear_both_secrets(self, db_session: Session) -> None:
         """Test clearing both client_id and client_secret"""
@@ -207,8 +225,10 @@ def test_update_oauth_config_clear_both_secrets(self, db_session: Session) -> No
         )
 
         # Both should be cleared (empty strings)
-        assert updated_config.client_id == ""
-        assert updated_config.client_secret == ""
+        assert updated_config.client_id is not None
+        assert updated_config.client_id.get_value(apply_mask=False) == ""
+        assert updated_config.client_secret is not None
+        assert updated_config.client_secret.get_value(apply_mask=False) == ""
 
     def test_update_oauth_config_authorization_url(self, db_session: Session) -> None:
         """Test updating authorization_url"""
@@ -275,7 +295,8 @@ def test_update_oauth_config_multiple_fields(self, db_session: Session) -> None:
         assert updated_config.token_url == new_token_url
         assert updated_config.scopes == new_scopes
         assert updated_config.additional_params == new_params
-        assert updated_config.client_id == new_client_id
+        assert updated_config.client_id is not None
+        assert updated_config.client_id.get_value(apply_mask=False) == new_client_id
 
     def test_delete_oauth_config(self, db_session: Session) -> None:
         """Test deleting an OAuth configuration"""
@@ -416,7 +437,8 @@ def test_upsert_user_oauth_token_create(self, db_session: Session) -> None:
         assert user_token.id is not None
         assert user_token.oauth_config_id == oauth_config.id
         assert user_token.user_id == user.id
-        assert user_token.token_data == token_data
+        assert user_token.token_data is not None
+        assert user_token.token_data.get_value(apply_mask=False) == token_data
         assert user_token.created_at is not None
         assert user_token.updated_at is not None
 
@@ -446,8 +468,13 @@ def test_upsert_user_oauth_token_update(self, db_session: Session) -> None:
 
         # Should be the same token record (updated, not inserted)
         assert updated_token.id == initial_token_id
-        assert updated_token.token_data == updated_token_data
-        assert updated_token.token_data != initial_token_data
+        assert updated_token.token_data is not None
+        assert (
+            updated_token.token_data.get_value(apply_mask=False) == updated_token_data
+        )
+        assert (
+            updated_token.token_data.get_value(apply_mask=False) != initial_token_data
+        )
 
     def test_get_user_oauth_token(self, db_session: Session) -> None:
         """Test retrieving a user's OAuth token"""
@@ -463,7 +490,8 @@ def test_get_user_oauth_token(self, db_session: Session) -> None:
 
         assert retrieved_token is not None
         assert retrieved_token.id == created_token.id
-        assert retrieved_token.token_data == token_data
+        assert retrieved_token.token_data is not None
+        assert retrieved_token.token_data.get_value(apply_mask=False) == token_data
 
     def test_get_user_oauth_token_not_found(self, db_session: Session) -> None:
         """Test retrieving a non-existent user token returns None"""
@@ -519,7 +547,8 @@ def test_unique_constraint_on_user_config(self, db_session: Session) -> None:
         retrieved_token = get_user_oauth_token(oauth_config.id, user.id, db_session)
         assert retrieved_token is not None
         assert retrieved_token.id == updated_token.id
-        assert retrieved_token.token_data == token_data2
+        assert retrieved_token.token_data is not None
+        assert retrieved_token.token_data.get_value(apply_mask=False) == token_data2
 
     def test_cascade_delete_user_tokens_on_config_deletion(
         self, db_session: Session
diff --git a/backend/tests/external_dependency_unit/tools/test_oauth_token_manager.py b/backend/tests/external_dependency_unit/tools/test_oauth_token_manager.py
index 77502737068..b4ee624fbcf 100644
--- a/backend/tests/external_dependency_unit/tools/test_oauth_token_manager.py
+++ b/backend/tests/external_dependency_unit/tools/test_oauth_token_manager.py
@@ -374,8 +374,14 @@ def test_exchange_code_for_token_success(
         assert call_args[0][0] == oauth_config.token_url
         assert call_args[1]["data"]["grant_type"] == "authorization_code"
         assert call_args[1]["data"]["code"] == "auth_code_123"
-        assert call_args[1]["data"]["client_id"] == oauth_config.client_id
-        assert call_args[1]["data"]["client_secret"] == oauth_config.client_secret
+        assert oauth_config.client_id is not None
+        assert oauth_config.client_secret is not None
+        assert call_args[1]["data"]["client_id"] == oauth_config.client_id.get_value(
+            apply_mask=False
+        )
+        assert call_args[1]["data"][
+            "client_secret"
+        ] == oauth_config.client_secret.get_value(apply_mask=False)
         assert call_args[1]["data"]["redirect_uri"] == "https://example.com/callback"
 
     @patch("onyx.auth.oauth_token_manager.requests.post")
diff --git a/backend/tests/integration/tests/discord_bot/test_discord_bot_db.py b/backend/tests/integration/tests/discord_bot/test_discord_bot_db.py
index 2a9abf7083a..c4cb95e9d32 100644
--- a/backend/tests/integration/tests/discord_bot/test_discord_bot_db.py
+++ b/backend/tests/integration/tests/discord_bot/test_discord_bot_db.py
@@ -64,7 +64,8 @@ def test_create_bot_config(self, db_session: Session) -> None:
         db_session.commit()
 
         assert config is not None
-        assert config.bot_token == "test_token_123"
+        assert config.bot_token is not None
+        assert config.bot_token.get_value(apply_mask=False) == "test_token_123"
 
         # Cleanup
         delete_discord_bot_config(db_session)
diff --git a/backend/tests/unit/onyx/utils/test_sensitive.py b/backend/tests/unit/onyx/utils/test_sensitive.py
index 862fe372211..40aec04b11f 100644
--- a/backend/tests/unit/onyx/utils/test_sensitive.py
+++ b/backend/tests/unit/onyx/utils/test_sensitive.py
@@ -147,15 +147,18 @@ def test_equality_with_different_value(self) -> None:
         )
         assert sensitive1 != sensitive2
 
-    def test_equality_with_non_sensitive_raises(self) -> None:
-        """Test that comparing with non-SensitiveValue raises error."""
+    def test_equality_with_non_sensitive_returns_not_equal(self) -> None:
+        """Test that comparing with non-SensitiveValue is always not-equal.
+
+        Returns NotImplemented so Python falls back to identity comparison.
+        This is required for compatibility with SQLAlchemy's attribute tracking.
+        """
         sensitive = SensitiveValue(
             encrypted_bytes=_encrypt_string("secret"),
             decrypt_fn=_decrypt_string,
             is_json=False,
         )
-        with pytest.raises(SensitiveAccessError):
-            _ = sensitive == "secret"
+        assert not (sensitive == "secret")
 
 
 class TestSensitiveValueJson:

From 6b5ab54b85a6aef6d14472c5170392a7529cef5b Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 9 Mar 2026 10:49:37 -0700
Subject: [PATCH 182/267] feat: add `LineItemButton` component (#9137)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../buttons/line-item-button/README.md        |  83 +++++++++++
 .../buttons/line-item-button/components.tsx   | 137 ++++++++++++++++++
 web/lib/opal/src/components/index.ts          |   6 +
 .../opal/src/core/animations/components.tsx   |  21 ++-
 .../src/core/interactive/stateful/styles.css  |  16 +-
 .../opal/src/layouts/content/BodyLayout.tsx   |   5 +
 .../opal/src/layouts/content/ContentLg.tsx    |  15 +-
 .../opal/src/layouts/content/ContentMd.tsx    |  15 +-
 .../opal/src/layouts/content/ContentSm.tsx    |  10 ++
 .../opal/src/layouts/content/ContentXl.tsx    |  14 +-
 .../src/layouts/content/HeadingLayout.tsx     |   5 +
 .../opal/src/layouts/content/LabelLayout.tsx  |   6 +-
 .../opal/src/layouts/content/components.tsx   |  16 ++
 web/lib/opal/src/layouts/content/styles.css   |  54 ++++++-
 web/lib/opal/src/types.ts                     |   5 +
 15 files changed, 389 insertions(+), 19 deletions(-)
 create mode 100644 web/lib/opal/src/components/buttons/line-item-button/README.md
 create mode 100644 web/lib/opal/src/components/buttons/line-item-button/components.tsx

diff --git a/web/lib/opal/src/components/buttons/line-item-button/README.md b/web/lib/opal/src/components/buttons/line-item-button/README.md
new file mode 100644
index 00000000000..488ea5f98fd
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/line-item-button/README.md
@@ -0,0 +1,83 @@
+# LineItemButton
+
+**Import:** `import { LineItemButton, type LineItemButtonProps } from "@opal/components";`
+
+A composite component that wraps `Interactive.Stateful > Interactive.Container > ContentAction` into a single API. Use it for selectable list rows such as model pickers, menu items, or any row that acts like a button.
+
+## Architecture
+
+```
+Interactive.Stateful         <- selectVariant, state, interaction, onClick, href, ref
+  └─ Interactive.Container   <- type, width, roundingVariant
+       └─ ContentAction      <- withInteractive, paddingVariant="lg"
+            ├─ Content       <- icon, title, description, sizePreset, variant, ...
+            └─ rightChildren
+```
+
+`paddingVariant` is hardcoded to `"lg"` and `withInteractive` is always `true`. These are not exposed as props.
+
+## Props
+
+### Interactive surface
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectVariant` | `"select-light" \| "select-heavy"` | `"select-light"` | Interactive select variant |
+| `state` | `InteractiveStatefulState` | `"empty"` | Value state (`"empty"`, `"filled"`, `"selected"`) |
+| `interaction` | `InteractiveStatefulInteraction` | `"rest"` | JS-controlled interaction state override |
+| `onClick` | `MouseEventHandler<HTMLElement>` | — | Click handler |
+| `href` | `string` | — | Renders an anchor instead of a div |
+| `target` | `string` | — | Anchor target (e.g. `"_blank"`) |
+| `group` | `string` | — | Interactive group key |
+| `ref` | `React.Ref<HTMLElement>` | — | Forwarded ref |
+
+### Sizing
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `roundingVariant` | `InteractiveContainerRoundingVariant` | `"default"` | Corner rounding preset (height is content-driven) |
+| `width` | `WidthVariant` | `"full"` | Container width |
+| `type` | `"submit" \| "button" \| "reset"` | `"button"` | HTML button type |
+| `tooltip` | `string` | — | Tooltip text shown on hover |
+| `tooltipSide` | `TooltipSide` | `"top"` | Tooltip side |
+
+### Content (pass-through to ContentAction)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | **(required)** | Row label |
+| `icon` | `IconFunctionComponent` | — | Left icon |
+| `description` | `string` | — | Description below the title |
+| `sizePreset` | `SizePreset` | `"headline"` | Content size preset |
+| `variant` | `ContentVariant` | `"heading"` | Content layout variant |
+| `rightChildren` | `ReactNode` | — | Content after the label (e.g. action button) |
+
+All other `ContentAction` / `Content` props (`editable`, `onTitleChange`, `optional`, `auxIcon`, `tag`, etc.) are also passed through. Note: `withInteractive` is always `true` inside `LineItemButton` and cannot be overridden.
+
+## Usage
+
+```tsx
+import { LineItemButton } from "@opal/components";
+
+// Simple selectable row
+<LineItemButton
+  selectVariant="select-heavy"
+  state={isSelected ? "selected" : "empty"}
+  roundingVariant="compact"
+  onClick={handleClick}
+  title="gpt-4o"
+  sizePreset="main-ui"
+  variant="section"
+/>
+
+// With right-side action
+<LineItemButton
+  selectVariant="select-heavy"
+  state={isSelected ? "selected" : "empty"}
+  onClick={handleClick}
+  title="claude-opus-4"
+  sizePreset="main-ui"
+  variant="section"
+  rightChildren={<Tag title="Default" color="blue" />}
+/>
+```
diff --git a/web/lib/opal/src/components/buttons/line-item-button/components.tsx b/web/lib/opal/src/components/buttons/line-item-button/components.tsx
new file mode 100644
index 00000000000..777c26e2c57
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/line-item-button/components.tsx
@@ -0,0 +1,137 @@
+import "@opal/components/tooltip.css";
+import {
+  Interactive,
+  type InteractiveStatefulState,
+  type InteractiveStatefulInteraction,
+  type InteractiveStatefulProps,
+  InteractiveContainerRoundingVariant,
+} from "@opal/core";
+import { type WidthVariant } from "@opal/shared";
+import type { TooltipSide } from "@opal/components";
+import type { DistributiveOmit } from "@opal/types";
+import type { ContentActionProps } from "@opal/layouts/content-action/components";
+import { ContentAction } from "@opal/layouts";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ContentPassthroughProps = DistributiveOmit<
+  ContentActionProps,
+  "paddingVariant" | "widthVariant" | "ref" | "withInteractive"
+>;
+
+type LineItemButtonOwnProps = {
+  /** Interactive select variant. @default "select-light" */
+  selectVariant?: "select-light" | "select-heavy";
+
+  /** Value state. @default "empty" */
+  state?: InteractiveStatefulState;
+
+  /** JS-controllable interaction state override. @default "rest" */
+  interaction?: InteractiveStatefulInteraction;
+
+  /** Click handler. */
+  onClick?: InteractiveStatefulProps["onClick"];
+
+  /** When provided, renders an anchor instead of a div. */
+  href?: string;
+
+  /** Anchor target (e.g. "_blank"). */
+  target?: string;
+
+  /** Interactive group key. */
+  group?: string;
+
+  /** Forwarded ref. */
+  ref?: React.Ref<HTMLElement>;
+
+  /** Corner rounding preset (height is always content-driven). @default "default" */
+  roundingVariant?: InteractiveContainerRoundingVariant;
+
+  /** Container width. @default "full" */
+  width?: WidthVariant;
+
+  /** HTML button type. @default "button" */
+  type?: "submit" | "button" | "reset";
+
+  /** Tooltip text shown on hover. */
+  tooltip?: string;
+
+  /** Which side the tooltip appears on. @default "top" */
+  tooltipSide?: TooltipSide;
+};
+
+type LineItemButtonProps = ContentPassthroughProps & LineItemButtonOwnProps;
+
+// ---------------------------------------------------------------------------
+// LineItemButton
+// ---------------------------------------------------------------------------
+
+function LineItemButton({
+  // Interactive surface
+  selectVariant = "select-light",
+  state,
+  interaction,
+  onClick,
+  href,
+  target,
+  group,
+  ref,
+
+  // Sizing
+  roundingVariant = "default",
+  width = "full",
+  type = "button",
+  tooltip,
+  tooltipSide = "top",
+
+  // ContentAction pass-through
+  ...contentActionProps
+}: LineItemButtonProps) {
+  const item = (
+    <Interactive.Stateful
+      variant={selectVariant}
+      state={state}
+      interaction={interaction}
+      onClick={onClick}
+      href={href}
+      target={target}
+      group={group}
+      ref={ref}
+    >
+      <Interactive.Container
+        type={type}
+        widthVariant={width}
+        heightVariant="lg"
+        roundingVariant={roundingVariant}
+      >
+        <ContentAction
+          {...(contentActionProps as ContentActionProps)}
+          withInteractive
+          paddingVariant="fit"
+        />
+      </Interactive.Container>
+    </Interactive.Stateful>
+  );
+
+  if (!tooltip) return item;
+
+  return (
+    <TooltipPrimitive.Root>
+      <TooltipPrimitive.Trigger asChild>{item}</TooltipPrimitive.Trigger>
+      <TooltipPrimitive.Portal>
+        <TooltipPrimitive.Content
+          className="opal-tooltip"
+          side={tooltipSide}
+          sideOffset={4}
+        >
+          {tooltip}
+        </TooltipPrimitive.Content>
+      </TooltipPrimitive.Portal>
+    </TooltipPrimitive.Root>
+  );
+}
+
+export { LineItemButton, type LineItemButtonProps };
diff --git a/web/lib/opal/src/components/index.ts b/web/lib/opal/src/components/index.ts
index a9867f8b7cf..ea3d58dee2c 100644
--- a/web/lib/opal/src/components/index.ts
+++ b/web/lib/opal/src/components/index.ts
@@ -19,6 +19,12 @@ export {
   type OpenButtonProps,
 } from "@opal/components/buttons/open-button/components";
 
+/* LineItemButton */
+export {
+  LineItemButton,
+  type LineItemButtonProps,
+} from "@opal/components/buttons/line-item-button/components";
+
 /* Tag */
 export {
   Tag,
diff --git a/web/lib/opal/src/core/animations/components.tsx b/web/lib/opal/src/core/animations/components.tsx
index 762d164b7c5..da61b3176e8 100644
--- a/web/lib/opal/src/core/animations/components.tsx
+++ b/web/lib/opal/src/core/animations/components.tsx
@@ -2,6 +2,7 @@ import "@opal/core/animations/styles.css";
 import React, { createContext, useContext, useState, useCallback } from "react";
 import { cn } from "@opal/utils";
 import type { WithoutStyles } from "@opal/types";
+import { widthVariants, type WidthVariant } from "@opal/shared";
 
 // ---------------------------------------------------------------------------
 // Context-per-group registry
@@ -38,6 +39,10 @@ interface HoverableRootProps
   extends WithoutStyles<React.HTMLAttributes<HTMLDivElement>> {
   children: React.ReactNode;
   group: string;
+  /** Width preset. @default "auto" */
+  widthVariant?: WidthVariant;
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 type HoverableItemVariant = "opacity-on-hover";
@@ -47,6 +52,8 @@ interface HoverableItemProps
   children: React.ReactNode;
   group?: string;
   variant?: HoverableItemVariant;
+  /** Ref forwarded to the item `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -77,6 +84,8 @@ interface HoverableItemProps
 function HoverableRoot({
   group,
   children,
+  widthVariant = "auto",
+  ref,
   onMouseEnter: consumerMouseEnter,
   onMouseLeave: consumerMouseLeave,
   ...props
@@ -103,7 +112,15 @@ function HoverableRoot({
 
   return (
     <GroupContext.Provider value={hovered}>
-      <div {...props} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+      <div
+        {...props}
+        ref={ref}
+        className={
+          widthVariant !== "auto" ? cn(widthVariants[widthVariant]) : undefined
+        }
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+      >
         {children}
       </div>
     </GroupContext.Provider>
@@ -147,6 +164,7 @@ function HoverableItem({
   group,
   variant = "opacity-on-hover",
   children,
+  ref,
   ...props
 }: HoverableItemProps) {
   const contextValue = useContext(
@@ -165,6 +183,7 @@ function HoverableItem({
   return (
     <div
       {...props}
+      ref={ref}
       className={cn("hoverable-item")}
       data-hoverable-variant={variant}
       data-hoverable-active={
diff --git a/web/lib/opal/src/core/interactive/stateful/styles.css b/web/lib/opal/src/core/interactive/stateful/styles.css
index 1dbe23778cd..59232abda93 100644
--- a/web/lib/opal/src/core/interactive/stateful/styles.css
+++ b/web/lib/opal/src/core/interactive/stateful/styles.css
@@ -59,8 +59,8 @@
    --------------------------------------------------------------------------- */
 .interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"] {
   @apply bg-transparent;
-  --interactive-foreground: var(--text-04);
-  --interactive-foreground-icon: var(--text-04);
+  --interactive-foreground: var(--action-link-05);
+  --interactive-foreground-icon: var(--action-link-05);
 }
 .interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"]:hover:not(
     [data-disabled]
@@ -76,9 +76,7 @@
 .interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"][data-interaction="active"]:not(
     [data-disabled]
   ) {
-  @apply bg-background-neutral-00;
-  --interactive-foreground: var(--text-05);
-  --interactive-foreground-icon: var(--text-05);
+  @apply bg-background-tint-00;
 }
 .interactive[data-interactive-variant="select-heavy"][data-interactive-state="filled"][data-disabled] {
   @apply bg-transparent;
@@ -158,8 +156,8 @@
    --------------------------------------------------------------------------- */
 .interactive[data-interactive-variant="select-light"][data-interactive-state="filled"] {
   @apply bg-transparent;
-  --interactive-foreground: var(--text-04);
-  --interactive-foreground-icon: var(--text-04);
+  --interactive-foreground: var(--action-link-05);
+  --interactive-foreground-icon: var(--action-link-05);
 }
 .interactive[data-interactive-variant="select-light"][data-interactive-state="filled"]:hover:not(
     [data-disabled]
@@ -175,9 +173,7 @@
 .interactive[data-interactive-variant="select-light"][data-interactive-state="filled"][data-interaction="active"]:not(
     [data-disabled]
   ) {
-  @apply bg-background-neutral-00;
-  --interactive-foreground: var(--text-05);
-  --interactive-foreground-icon: var(--text-05);
+  @apply bg-background-tint-00;
 }
 .interactive[data-interactive-variant="select-light"][data-interactive-state="filled"][data-disabled] {
   @apply bg-transparent;
diff --git a/web/lib/opal/src/layouts/content/BodyLayout.tsx b/web/lib/opal/src/layouts/content/BodyLayout.tsx
index d4d6e23b4c1..569d407df54 100644
--- a/web/lib/opal/src/layouts/content/BodyLayout.tsx
+++ b/web/lib/opal/src/layouts/content/BodyLayout.tsx
@@ -40,6 +40,9 @@ interface BodyLayoutProps {
 
   /** Title prominence. Default: `"default"`. */
   prominence?: BodyProminence;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -80,6 +83,7 @@ function BodyLayout({
   sizePreset = "main-ui",
   orientation = "inline",
   prominence = "default",
+  ref,
 }: BodyLayoutProps) {
   const config = BODY_PRESETS[sizePreset];
   const titleColorClass =
@@ -87,6 +91,7 @@ function BodyLayout({
 
   return (
     <div
+      ref={ref}
       className="opal-content-body"
       data-orientation={orientation}
       style={{ gap: config.gap }}
diff --git a/web/lib/opal/src/layouts/content/ContentLg.tsx b/web/lib/opal/src/layouts/content/ContentLg.tsx
index 530afe5d4ad..d70a09dca1f 100644
--- a/web/lib/opal/src/layouts/content/ContentLg.tsx
+++ b/web/lib/opal/src/layouts/content/ContentLg.tsx
@@ -48,6 +48,12 @@ interface ContentLgProps {
 
   /** Size preset. Default: `"headline"`. */
   sizePreset?: ContentLgSizePreset;
+
+  /** When `true`, the title color hooks into `Interactive`'s `--interactive-foreground` variable. */
+  withInteractive?: boolean;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -86,6 +92,8 @@ function ContentLg({
   description,
   editable,
   onTitleChange,
+  withInteractive,
+  ref,
 }: ContentLgProps) {
   const [editing, setEditing] = useState(false);
   const [editValue, setEditValue] = useState(title);
@@ -104,7 +112,12 @@ function ContentLg({
   }
 
   return (
-    <div className="opal-content-lg" style={{ gap: config.gap }}>
+    <div
+      ref={ref}
+      className="opal-content-lg"
+      data-interactive={withInteractive || undefined}
+      style={{ gap: config.gap }}
+    >
       {Icon && (
         <div
           className={cn(
diff --git a/web/lib/opal/src/layouts/content/ContentMd.tsx b/web/lib/opal/src/layouts/content/ContentMd.tsx
index fc3b08418d0..a1fadb7b3a2 100644
--- a/web/lib/opal/src/layouts/content/ContentMd.tsx
+++ b/web/lib/opal/src/layouts/content/ContentMd.tsx
@@ -61,6 +61,12 @@ interface ContentMdProps {
 
   /** Size preset. Default: `"main-ui"`. */
   sizePreset?: ContentMdSizePreset;
+
+  /** When `true`, the title color hooks into `Interactive`'s `--interactive-foreground` variable. */
+  withInteractive?: boolean;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -130,6 +136,8 @@ function ContentMd({
   auxIcon,
   tag,
   sizePreset = "main-ui",
+  withInteractive,
+  ref,
 }: ContentMdProps) {
   const [editing, setEditing] = useState(false);
   const [editValue, setEditValue] = useState(title);
@@ -149,7 +157,12 @@ function ContentMd({
   }
 
   return (
-    <div className="opal-content-md" style={{ gap: config.gap }}>
+    <div
+      ref={ref}
+      className="opal-content-md"
+      data-interactive={withInteractive || undefined}
+      style={{ gap: config.gap }}
+    >
       {Icon && (
         <div
           className={cn(
diff --git a/web/lib/opal/src/layouts/content/ContentSm.tsx b/web/lib/opal/src/layouts/content/ContentSm.tsx
index fe967366761..1206cba08ed 100644
--- a/web/lib/opal/src/layouts/content/ContentSm.tsx
+++ b/web/lib/opal/src/layouts/content/ContentSm.tsx
@@ -40,6 +40,12 @@ interface ContentSmProps {
 
   /** Title prominence. Default: `"default"`. */
   prominence?: ContentSmProminence;
+
+  /** When `true`, the title color hooks into `Interactive`'s `--interactive-foreground` variable. */
+  withInteractive?: boolean;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -80,14 +86,18 @@ function ContentSm({
   sizePreset = "main-ui",
   orientation = "inline",
   prominence = "default",
+  withInteractive,
+  ref,
 }: ContentSmProps) {
   const config = CONTENT_SM_PRESETS[sizePreset];
 
   return (
     <div
+      ref={ref}
       className="opal-content-sm"
       data-orientation={orientation}
       data-prominence={prominence}
+      data-interactive={withInteractive || undefined}
       style={{ gap: config.gap }}
     >
       {Icon && (
diff --git a/web/lib/opal/src/layouts/content/ContentXl.tsx b/web/lib/opal/src/layouts/content/ContentXl.tsx
index e086abf1859..2671b73fd57 100644
--- a/web/lib/opal/src/layouts/content/ContentXl.tsx
+++ b/web/lib/opal/src/layouts/content/ContentXl.tsx
@@ -60,6 +60,12 @@ interface ContentXlProps {
 
   /** Optional tertiary icon rendered in the icon row. */
   moreIcon2?: IconFunctionComponent;
+
+  /** When `true`, the title color hooks into `Interactive`'s `--interactive-foreground` variable. */
+  withInteractive?: boolean;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -106,6 +112,8 @@ function ContentXl({
   onTitleChange,
   moreIcon1: MoreIcon1,
   moreIcon2: MoreIcon2,
+  withInteractive,
+  ref,
 }: ContentXlProps) {
   const [editing, setEditing] = useState(false);
   const [editValue, setEditValue] = useState(title);
@@ -124,7 +132,11 @@ function ContentXl({
   }
 
   return (
-    <div className="opal-content-xl">
+    <div
+      ref={ref}
+      className="opal-content-xl"
+      data-interactive={withInteractive || undefined}
+    >
       {(Icon || MoreIcon1 || MoreIcon2) && (
         <div className="opal-content-xl-icon-row">
           {Icon && (
diff --git a/web/lib/opal/src/layouts/content/HeadingLayout.tsx b/web/lib/opal/src/layouts/content/HeadingLayout.tsx
index 02eeaf0ddf7..7047011fcca 100644
--- a/web/lib/opal/src/layouts/content/HeadingLayout.tsx
+++ b/web/lib/opal/src/layouts/content/HeadingLayout.tsx
@@ -52,6 +52,9 @@ interface HeadingLayoutProps {
 
   /** Variant controls icon placement. `"heading"` = top, `"section"` = inline. Default: `"heading"`. */
   variant?: HeadingVariant;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -91,6 +94,7 @@ function HeadingLayout({
   description,
   editable,
   onTitleChange,
+  ref,
 }: HeadingLayoutProps) {
   const [editing, setEditing] = useState(false);
   const [editValue, setEditValue] = useState(title);
@@ -112,6 +116,7 @@ function HeadingLayout({
 
   return (
     <div
+      ref={ref}
       className="opal-content-heading"
       data-icon-placement={iconPlacement}
       style={{ gap: iconPlacement === "left" ? config.gap : undefined }}
diff --git a/web/lib/opal/src/layouts/content/LabelLayout.tsx b/web/lib/opal/src/layouts/content/LabelLayout.tsx
index 6bfb5c9b680..016b43f5cfa 100644
--- a/web/lib/opal/src/layouts/content/LabelLayout.tsx
+++ b/web/lib/opal/src/layouts/content/LabelLayout.tsx
@@ -61,6 +61,9 @@ interface LabelLayoutProps {
 
   /** Size preset. Default: `"main-ui"`. */
   sizePreset?: LabelSizePreset;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -130,6 +133,7 @@ function LabelLayout({
   auxIcon,
   tag,
   sizePreset = "main-ui",
+  ref,
 }: LabelLayoutProps) {
   const [editing, setEditing] = useState(false);
   const [editValue, setEditValue] = useState(title);
@@ -149,7 +153,7 @@ function LabelLayout({
   }
 
   return (
-    <div className="opal-content-label" style={{ gap: config.gap }}>
+    <div ref={ref} className="opal-content-label" style={{ gap: config.gap }}>
       {Icon && (
         <div
           className={cn(
diff --git a/web/lib/opal/src/layouts/content/components.tsx b/web/lib/opal/src/layouts/content/components.tsx
index 3ce97bb01d8..cda24ce02d4 100644
--- a/web/lib/opal/src/layouts/content/components.tsx
+++ b/web/lib/opal/src/layouts/content/components.tsx
@@ -59,6 +59,12 @@ interface ContentBaseProps {
    * @default "auto"
    */
   widthVariant?: WidthVariant;
+
+  /** When `true`, the title color hooks into `Interactive.Stateful`/`Interactive.Stateless`'s `--interactive-foreground` variable. */
+  withInteractive?: boolean;
+
+  /** Ref forwarded to the root `<div>` of the resolved layout. */
+  ref?: React.Ref<HTMLDivElement>;
 }
 
 // ---------------------------------------------------------------------------
@@ -122,6 +128,8 @@ function Content(props: ContentProps) {
     sizePreset = "headline",
     variant = "heading",
     widthVariant = "auto",
+    withInteractive,
+    ref,
     ...rest
   } = props;
 
@@ -135,6 +143,8 @@ function Content(props: ContentProps) {
       layout = (
         <ContentXl
           sizePreset={sizePreset}
+          withInteractive={withInteractive}
+          ref={ref}
           {...(rest as Omit<ContentXlProps, "sizePreset">)}
         />
       );
@@ -142,6 +152,8 @@ function Content(props: ContentProps) {
       layout = (
         <ContentLg
           sizePreset={sizePreset}
+          withInteractive={withInteractive}
+          ref={ref}
           {...(rest as Omit<ContentLgProps, "sizePreset">)}
         />
       );
@@ -154,6 +166,8 @@ function Content(props: ContentProps) {
     layout = (
       <ContentMd
         sizePreset={sizePreset}
+        withInteractive={withInteractive}
+        ref={ref}
         {...(rest as Omit<ContentMdProps, "sizePreset">)}
       />
     );
@@ -164,6 +178,8 @@ function Content(props: ContentProps) {
     layout = (
       <ContentSm
         sizePreset={sizePreset}
+        withInteractive={withInteractive}
+        ref={ref}
         {...(rest as Omit<
           React.ComponentProps<typeof ContentSm>,
           "sizePreset"
diff --git a/web/lib/opal/src/layouts/content/styles.css b/web/lib/opal/src/layouts/content/styles.css
index ae232231bb4..07b542400fb 100644
--- a/web/lib/opal/src/layouts/content/styles.css
+++ b/web/lib/opal/src/layouts/content/styles.css
@@ -22,6 +22,7 @@
 
 .opal-content-xl-icon-row {
   @apply flex flex-row items-center;
+  gap: 0.25rem;
 }
 
 /* ---------------------------------------------------------------------------
@@ -63,7 +64,7 @@
 }
 
 .opal-content-xl-title {
-  @apply text-left overflow-hidden;
+  @apply text-left overflow-hidden text-text-04;
   display: -webkit-box;
   -webkit-box-orient: vertical;
   -webkit-line-clamp: 1;
@@ -162,7 +163,7 @@
 }
 
 .opal-content-lg-title {
-  @apply text-left overflow-hidden;
+  @apply text-left overflow-hidden text-text-04;
   display: -webkit-box;
   -webkit-box-orient: vertical;
   -webkit-line-clamp: 1;
@@ -255,7 +256,7 @@
 }
 
 .opal-content-md-title {
-  @apply text-left overflow-hidden;
+  @apply text-left overflow-hidden text-text-04;
   display: -webkit-box;
   -webkit-box-orient: vertical;
   -webkit-line-clamp: 1;
@@ -361,8 +362,12 @@
   @apply text-text-03;
 }
 
+.opal-content-sm[data-prominence="muted"] .opal-content-sm-icon {
+  @apply text-text-02;
+}
+
 .opal-content-sm[data-prominence="muted-2x"] .opal-content-sm-icon {
-  @apply text-text-02 stroke-text-02;
+  @apply text-text-02;
 }
 
 /* ---------------------------------------------------------------------------
@@ -385,3 +390,44 @@
 .opal-content-sm[data-prominence="muted-2x"] .opal-content-sm-title {
   @apply text-text-02;
 }
+
+/* ===========================================================================
+   Interactive-foreground opt-in
+
+   When a Content variant is nested inside an Interactive and
+   `withInteractive` is set, the title and icon delegate their color to the
+   `--interactive-foreground` / `--interactive-foreground-icon` CSS variables
+   controlled by the ancestor Interactive variant.
+   =========================================================================== */
+
+.opal-content-xl[data-interactive] .opal-content-xl-title {
+  color: var(--interactive-foreground);
+}
+
+.opal-content-xl[data-interactive] .opal-content-xl-icon {
+  color: var(--interactive-foreground-icon);
+}
+
+.opal-content-lg[data-interactive] .opal-content-lg-title {
+  color: var(--interactive-foreground);
+}
+
+.opal-content-lg[data-interactive] .opal-content-lg-icon {
+  color: var(--interactive-foreground-icon);
+}
+
+.opal-content-md[data-interactive] .opal-content-md-title {
+  color: var(--interactive-foreground);
+}
+
+.opal-content-md[data-interactive] .opal-content-md-icon {
+  color: var(--interactive-foreground-icon);
+}
+
+.opal-content-sm[data-interactive] .opal-content-sm-title {
+  color: var(--interactive-foreground);
+}
+
+.opal-content-sm[data-interactive] .opal-content-sm-icon {
+  color: var(--interactive-foreground-icon);
+}
diff --git a/web/lib/opal/src/types.ts b/web/lib/opal/src/types.ts
index 8d0b6374ce9..068bf35da23 100644
--- a/web/lib/opal/src/types.ts
+++ b/web/lib/opal/src/types.ts
@@ -30,6 +30,11 @@ export interface IconProps extends SVGProps<SVGSVGElement> {
 /** Strips `className` and `style` from a props type to enforce design-system styling. */
 export type WithoutStyles<T> = Omit<T, "className" | "style">;
 
+/** Like `Omit` but distributes over union types, preserving discriminated unions. */
+export type DistributiveOmit<T, K extends keyof any> = T extends any
+  ? Omit<T, K>
+  : never;
+
 /**
  * A React function component that accepts {@link IconProps}.
  *

From 4761e4b132c3028e67f285351caef2180b341f14 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 10:58:14 -0700
Subject: [PATCH 183/267] fix: fallback doc access when drive item is
 externally owned (#9053)

---
 .../google_drive/doc_sync.py                  | 26 +++++++++++++++++++
 .../onyx/connectors/google_drive/connector.py |  1 +
 .../connectors/google_drive/doc_conversion.py |  8 ++++++
 3 files changed, 35 insertions(+)

diff --git a/backend/ee/onyx/external_permissions/google_drive/doc_sync.py b/backend/ee/onyx/external_permissions/google_drive/doc_sync.py
index c5318548a44..bbec6bfbcc7 100644
--- a/backend/ee/onyx/external_permissions/google_drive/doc_sync.py
+++ b/backend/ee/onyx/external_permissions/google_drive/doc_sync.py
@@ -68,6 +68,7 @@ def get_external_access_for_raw_gdrive_file(
     company_domain: str,
     retriever_drive_service: GoogleDriveService | None,
     admin_drive_service: GoogleDriveService,
+    fallback_user_email: str,
     add_prefix: bool = False,
 ) -> ExternalAccess:
     """
@@ -79,6 +80,11 @@ def get_external_access_for_raw_gdrive_file(
                 set add_prefix to True so group IDs are prefixed with the source type.
                 When invoked from doc_sync (permission sync), use the default (False)
                 since upsert_document_external_perms handles prefixing.
+    fallback_user_email: When we cannot retrieve any permission info for a file
+                (e.g. externally-owned files where the API returns no permissions
+                and permissions.list returns 403), fall back to granting access
+                to this user. This is typically the impersonated org user whose
+                drive contained the file.
     """
     doc_id = file.get("id")
     if not doc_id:
@@ -117,6 +123,26 @@ def _get_permissions(
                 [permissions_list, backup_permissions_list]
             )
 
+    # For externally-owned files, the Drive API may return no permissions
+    # and permissions.list may return 403. In this case, fall back to
+    # granting access to the user who found the file in their drive.
+    # Note, even if other users also have access to this file,
+    # they will not be granted access in Onyx.
+    # We check permissions_list (the final result after all fetch attempts)
+    # rather than the raw fields, because permission_ids may be present
+    # but the actual fetch can still return empty due to a 403.
+    if not permissions_list:
+        logger.info(
+            f"No permission info available for file {doc_id} "
+            f"(likely owned by a user outside of your organization). "
+            f"Falling back to granting access to retriever user: {fallback_user_email}"
+        )
+        return ExternalAccess(
+            external_user_emails={fallback_user_email},
+            external_user_group_ids=set(),
+            is_public=False,
+        )
+
     folder_ids_to_inherit_permissions_from: set[str] = set()
     user_emails: set[str] = set()
     group_emails: set[str] = set()
diff --git a/backend/onyx/connectors/google_drive/connector.py b/backend/onyx/connectors/google_drive/connector.py
index f28c7e78bca..944def29a5e 100644
--- a/backend/onyx/connectors/google_drive/connector.py
+++ b/backend/onyx/connectors/google_drive/connector.py
@@ -1722,6 +1722,7 @@ def _yield_slim_batch() -> list[SlimDocument | HierarchyNode]:
                         primary_admin_email=self.primary_admin_email,
                         google_domain=self.google_domain,
                     ),
+                    retriever_email=file.user_email,
                 ):
                     slim_batch.append(doc)
 
diff --git a/backend/onyx/connectors/google_drive/doc_conversion.py b/backend/onyx/connectors/google_drive/doc_conversion.py
index 4aa731a2a8a..fdbe3a78a1f 100644
--- a/backend/onyx/connectors/google_drive/doc_conversion.py
+++ b/backend/onyx/connectors/google_drive/doc_conversion.py
@@ -476,6 +476,7 @@ def _get_external_access_for_raw_gdrive_file(
     company_domain: str,
     retriever_drive_service: GoogleDriveService | None,
     admin_drive_service: GoogleDriveService,
+    fallback_user_email: str,
     add_prefix: bool = False,
 ) -> ExternalAccess:
     """
@@ -484,6 +485,8 @@ def _get_external_access_for_raw_gdrive_file(
     add_prefix: When True, prefix group IDs with source type (for indexing path).
                When False (default), leave unprefixed (for permission sync path
                where upsert_document_external_perms handles prefixing).
+    fallback_user_email: When permission info can't be retrieved (e.g. externally-owned
+               files), fall back to granting access to this user.
     """
     external_access_fn = cast(
         Callable[
@@ -492,6 +495,7 @@ def _get_external_access_for_raw_gdrive_file(
                 str,
                 GoogleDriveService | None,
                 GoogleDriveService,
+                str,
                 bool,
             ],
             ExternalAccess,
@@ -507,6 +511,7 @@ def _get_external_access_for_raw_gdrive_file(
         company_domain,
         retriever_drive_service,
         admin_drive_service,
+        fallback_user_email,
         add_prefix,
     )
 
@@ -672,6 +677,7 @@ def _get_docs_service() -> GoogleDocsService:
                     creds, user_email=permission_sync_context.primary_admin_email
                 ),
                 add_prefix=True,  # Indexing path - prefix here
+                fallback_user_email=retriever_email,
             )
             if permission_sync_context
             else None
@@ -753,6 +759,7 @@ def build_slim_document(
     # if not specified, we will not sync permissions
     # will also be a no-op if EE is not enabled
     permission_sync_context: PermissionSyncContext | None,
+    retriever_email: str,
 ) -> SlimDocument | None:
     if file.get("mimeType") in [DRIVE_FOLDER_TYPE, DRIVE_SHORTCUT_TYPE]:
         return None
@@ -774,6 +781,7 @@ def build_slim_document(
                 creds,
                 user_email=permission_sync_context.primary_admin_email,
             ),
+            fallback_user_email=retriever_email,
         )
         if permission_sync_context
         else None

From e495f7a13e665730fe55df71c26f5e48dd054f6b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 Mar 2026 12:40:58 -0700
Subject: [PATCH 184/267] chore(deps): bump astral-sh/setup-uv from 7.2.0 to
 7.3.1 (#9200)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/deployment.yml                  | 2 +-
 .github/workflows/post-merge-beta-cherry-pick.yml | 2 +-
 .github/workflows/pr-playwright-tests.yml         | 2 +-
 .github/workflows/release-devtools.yml            | 2 +-
 .github/workflows/zizmor.yml                      | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
index 66105c0257e..1f689dd37fa 100644
--- a/.github/workflows/deployment.yml
+++ b/.github/workflows/deployment.yml
@@ -151,7 +151,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           version: "0.9.9"
           # NOTE: This isn't caching much and zizmor suggests this could be poisoned, so disable.
diff --git a/.github/workflows/post-merge-beta-cherry-pick.yml b/.github/workflows/post-merge-beta-cherry-pick.yml
index a68a9d616bf..600e4ee6f29 100644
--- a/.github/workflows/post-merge-beta-cherry-pick.yml
+++ b/.github/workflows/post-merge-beta-cherry-pick.yml
@@ -70,7 +70,7 @@ jobs:
 
       - name: Install the latest version of uv
         if: steps.gate.outputs.should_cherrypick == 'true'
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
           version: "0.9.9"
diff --git a/.github/workflows/pr-playwright-tests.yml b/.github/workflows/pr-playwright-tests.yml
index 8943f80a663..c0db3ee18fe 100644
--- a/.github/workflows/pr-playwright-tests.yml
+++ b/.github/workflows/pr-playwright-tests.yml
@@ -468,7 +468,7 @@ jobs:
 
       - name: Install the latest version of uv
         if: always()
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
           version: "0.9.9"
diff --git a/.github/workflows/release-devtools.yml b/.github/workflows/release-devtools.yml
index 0fde4304eae..d1ebc35e4b5 100644
--- a/.github/workflows/release-devtools.yml
+++ b/.github/workflows/release-devtools.yml
@@ -26,7 +26,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
           version: "0.9.9"
diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml
index 32f550fbb87..86dbb4494c7 100644
--- a/.github/workflows/zizmor.yml
+++ b/.github/workflows/zizmor.yml
@@ -24,7 +24,7 @@ jobs:
           persist-credentials: false
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # ratchet:astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
           version: "0.9.9"

From dc40e86dac75c8d833dd74bc1fdad0f046f2b3cb Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 Mar 2026 12:41:21 -0700
Subject: [PATCH 185/267] chore(deps): bump actions/download-artifact from
 7.0.0 to 8.0.0 (#9199)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pr-playwright-tests.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pr-playwright-tests.yml b/.github/workflows/pr-playwright-tests.yml
index c0db3ee18fe..d09756a5e1c 100644
--- a/.github/workflows/pr-playwright-tests.yml
+++ b/.github/workflows/pr-playwright-tests.yml
@@ -707,7 +707,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Download visual diff summaries
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3
         with:
           pattern: screenshot-diff-summary-*
           path: summaries/

From d4d98a6cd083b445c4874adc57ca865f586c8dfc Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 Mar 2026 12:42:30 -0700
Subject: [PATCH 186/267] chore(deps): bump hashicorp/setup-terraform from
 3.1.2 to 4.0.0 (#9198)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pr-quality-checks.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pr-quality-checks.yml b/.github/workflows/pr-quality-checks.yml
index 8e6d57b9d83..6bdaad1fb5b 100644
--- a/.github/workflows/pr-quality-checks.yml
+++ b/.github/workflows/pr-quality-checks.yml
@@ -28,7 +28,7 @@ jobs:
         with:
           python-version: "3.11"
       - name: Setup Terraform
-        uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # ratchet:hashicorp/setup-terraform@v3
+        uses: hashicorp/setup-terraform@5e8dbf3c6d9deaf4193ca7a8fb23f2ac83bb6c85 # ratchet:hashicorp/setup-terraform@v4.0.0
       - name: Setup node
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # ratchet:actions/setup-node@v6
         with: # zizmor: ignore[cache-poisoning]

From ec978d9a3fef0aa96feb4950fc1a05b36d41e1a7 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 12:44:08 -0700
Subject: [PATCH 187/267] fix(mcp): use CE-compatible chat endpoint for
 search_indexed_documents (#9193)

Co-authored-by: Fizza-Mukhtar <fizzamukhtar01@gmail.com>
---
 backend/onyx/mcp_server/tools/search.py | 83 +++++++++++++++++--------
 1 file changed, 58 insertions(+), 25 deletions(-)

diff --git a/backend/onyx/mcp_server/tools/search.py b/backend/onyx/mcp_server/tools/search.py
index b3c0a427c79..c509b8d0aff 100644
--- a/backend/onyx/mcp_server/tools/search.py
+++ b/backend/onyx/mcp_server/tools/search.py
@@ -10,6 +10,7 @@
 from onyx.mcp_server.utils import require_access_token
 from onyx.utils.logger import setup_logger
 from onyx.utils.variable_functionality import build_api_server_url_for_http_requests
+from onyx.utils.variable_functionality import global_version
 
 logger = setup_logger()
 
@@ -26,6 +27,14 @@ async def search_indexed_documents(
     Use this tool for information that is not public knowledge and specific to the user,
     their team, their work, or their organization/company.
 
+    Note: In CE mode, this tool uses the chat endpoint internally which invokes an LLM
+    on every call, consuming tokens and adding latency.
+    Additionally, CE callers receive a truncated snippet (blurb) instead of a full document chunk,
+    but this should still be sufficient for most use cases. CE mode functionality should be swapped
+    when a dedicated CE search endpoint is implemented.
+
+    In EE mode, the dedicated search endpoint is used instead.
+
     To find a list of available sources, use the `indexed_sources` resource.
     Returns chunks of text as search results with snippets, scores, and metadata.
 
@@ -111,48 +120,73 @@ async def search_indexed_documents(
         if time_cutoff_dt:
             filters["time_cutoff"] = time_cutoff_dt.isoformat()
 
-    # Build the search request using the new SendSearchQueryRequest format
-    search_request = {
-        "search_query": query,
-        "filters": filters,
-        "num_docs_fed_to_llm_selection": limit,
-        "run_query_expansion": False,
-        "include_content": True,
-        "stream": False,
-    }
+    is_ee = global_version.is_ee_version()
+    base_url = build_api_server_url_for_http_requests(respect_env_override_if_set=True)
+    auth_headers = {"Authorization": f"Bearer {access_token.token}"}
+
+    search_request: dict[str, Any]
+    if is_ee:
+        # EE: use the dedicated search endpoint (no LLM invocation)
+        search_request = {
+            "search_query": query,
+            "filters": filters,
+            "num_docs_fed_to_llm_selection": limit,
+            "run_query_expansion": False,
+            "include_content": True,
+            "stream": False,
+        }
+        endpoint = f"{base_url}/search/send-search-message"
+        error_key = "error"
+        docs_key = "search_docs"
+        content_field = "content"
+    else:
+        # CE: fall back to the chat endpoint (invokes LLM, consumes tokens)
+        search_request = {
+            "message": query,
+            "stream": False,
+            "chat_session_info": {},
+        }
+        if filters:
+            search_request["internal_search_filters"] = filters
+        endpoint = f"{base_url}/chat/send-chat-message"
+        error_key = "error_msg"
+        docs_key = "top_documents"
+        content_field = "blurb"
 
-    # Call the API server using the new send-search-message route
     try:
         response = await get_http_client().post(
-            f"{build_api_server_url_for_http_requests(respect_env_override_if_set=True)}/search/send-search-message",
+            endpoint,
             json=search_request,
-            headers={"Authorization": f"Bearer {access_token.token}"},
+            headers=auth_headers,
         )
         response.raise_for_status()
         result = response.json()
 
         # Check for error in response
-        if result.get("error"):
+        if result.get(error_key):
             return {
                 "documents": [],
                 "total_results": 0,
                 "query": query,
-                "error": result.get("error"),
+                "error": result.get(error_key),
             }
 
-        # Return simplified format for MCP clients
-        fields_to_return = [
-            "semantic_identifier",
-            "content",
-            "source_type",
-            "link",
-            "score",
-        ]
         documents = [
-            {key: doc.get(key) for key in fields_to_return}
-            for doc in result.get("search_docs", [])
+            {
+                "semantic_identifier": doc.get("semantic_identifier"),
+                "content": doc.get(content_field),
+                "source_type": doc.get("source_type"),
+                "link": doc.get("link"),
+                "score": doc.get("score"),
+            }
+            for doc in result.get(docs_key, [])
         ]
 
+        # NOTE: search depth is controlled by the backend persona defaults, not `limit`.
+        # `limit` only caps the returned list; fewer results may be returned if the
+        # backend retrieves fewer documents than requested.
+        documents = documents[:limit]
+
         logger.info(
             f"Onyx MCP Server: Internal search returned {len(documents)} results"
         )
@@ -160,7 +194,6 @@ async def search_indexed_documents(
             "documents": documents,
             "total_results": len(documents),
             "query": query,
-            "executed_queries": result.get("all_executed_queries", [query]),
         }
     except Exception as e:
         logger.error(f"Onyx MCP Server: Document search error: {e}", exc_info=True)

From 63d3efd3801f5ee2c2dd78e8eb80483e98c1df7b Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Mon, 9 Mar 2026 12:58:16 -0700
Subject: [PATCH 188/267] =?UTF-8?q?refactor:=20default=20width=20from=20`w?=
 =?UTF-8?q?-auto`=20=E2=86=92=20`w-fit`=20(#9146)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../opal/src/components/buttons/button/components.tsx |  2 +-
 .../components/buttons/select-button/components.tsx   |  2 +-
 web/lib/opal/src/core/animations/components.tsx       |  4 +---
 web/lib/opal/src/core/interactive/container/README.md |  2 +-
 .../src/core/interactive/container/components.tsx     |  4 ++--
 web/lib/opal/src/layouts/content/components.tsx       | 11 +++--------
 web/lib/opal/src/shared.ts                            |  2 ++
 7 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/web/lib/opal/src/components/buttons/button/components.tsx b/web/lib/opal/src/components/buttons/button/components.tsx
index e9786ce1f69..907a8a84b51 100644
--- a/web/lib/opal/src/components/buttons/button/components.tsx
+++ b/web/lib/opal/src/components/buttons/button/components.tsx
@@ -39,7 +39,7 @@ type ButtonProps = InteractiveStatelessProps &
     /** Tooltip text shown on hover. */
     tooltip?: string;
 
-    /** Width preset. `"auto"` shrink-wraps, `"full"` stretches to parent width. */
+    /** Width preset. `"fit"` shrink-wraps, `"full"` stretches to parent width. */
     width?: WidthVariant;
 
     /** Which side the tooltip appears on. */
diff --git a/web/lib/opal/src/components/buttons/select-button/components.tsx b/web/lib/opal/src/components/buttons/select-button/components.tsx
index 0fd0d01bd7a..0d523b55208 100644
--- a/web/lib/opal/src/components/buttons/select-button/components.tsx
+++ b/web/lib/opal/src/components/buttons/select-button/components.tsx
@@ -56,7 +56,7 @@ type SelectButtonProps = InteractiveStatefulProps &
     /** Tooltip text shown on hover. */
     tooltip?: string;
 
-    /** Width preset. `"auto"` shrink-wraps, `"full"` stretches to parent width. */
+    /** Width preset. `"fit"` shrink-wraps, `"full"` stretches to parent width. */
     width?: WidthVariant;
 
     /** Which side the tooltip appears on. */
diff --git a/web/lib/opal/src/core/animations/components.tsx b/web/lib/opal/src/core/animations/components.tsx
index da61b3176e8..ec2e857a7ae 100644
--- a/web/lib/opal/src/core/animations/components.tsx
+++ b/web/lib/opal/src/core/animations/components.tsx
@@ -115,9 +115,7 @@ function HoverableRoot({
       <div
         {...props}
         ref={ref}
-        className={
-          widthVariant !== "auto" ? cn(widthVariants[widthVariant]) : undefined
-        }
+        className={cn(widthVariants[widthVariant])}
         onMouseEnter={onMouseEnter}
         onMouseLeave={onMouseLeave}
       >
diff --git a/web/lib/opal/src/core/interactive/container/README.md b/web/lib/opal/src/core/interactive/container/README.md
index 20d9a116beb..71689466fd8 100644
--- a/web/lib/opal/src/core/interactive/container/README.md
+++ b/web/lib/opal/src/core/interactive/container/README.md
@@ -10,7 +10,7 @@ Structural container shared by both `Interactive.Stateless` and `Interactive.Sta
 |------|------|---------|-------------|
 | `heightVariant` | `SizeVariant` | `"lg"` | Height preset (`2xs`–`lg`, `fit`) |
 | `roundingVariant` | `"default" \| "compact" \| "mini"` | `"default"` | Border-radius preset |
-| `widthVariant` | `WidthVariant` | — | Width preset (`auto`, `full`) |
+| `widthVariant` | `WidthVariant` | — | Width preset (`"auto"`, `"fit"`, `"full"`) |
 | `border` | `boolean` | `false` | Renders a 1px border |
 | `type` | `"submit" \| "button" \| "reset"` | — | When set, renders a `<button>` element |
 
diff --git a/web/lib/opal/src/core/interactive/container/components.tsx b/web/lib/opal/src/core/interactive/container/components.tsx
index d232b03057b..499804c4944 100644
--- a/web/lib/opal/src/core/interactive/container/components.tsx
+++ b/web/lib/opal/src/core/interactive/container/components.tsx
@@ -78,7 +78,7 @@ interface InteractiveContainerProps
   /**
    * Width preset controlling the container's horizontal size.
    *
-   * @default "auto"
+   * @default "fit"
    */
   widthVariant?: WidthVariant;
 }
@@ -101,7 +101,7 @@ function InteractiveContainer({
   border,
   roundingVariant = "default",
   heightVariant = "lg",
-  widthVariant = "auto",
+  widthVariant = "fit",
   ...props
 }: InteractiveContainerProps) {
   const { allowClick } = useDisabled();
diff --git a/web/lib/opal/src/layouts/content/components.tsx b/web/lib/opal/src/layouts/content/components.tsx
index cda24ce02d4..d6d1cad7c95 100644
--- a/web/lib/opal/src/layouts/content/components.tsx
+++ b/web/lib/opal/src/layouts/content/components.tsx
@@ -54,9 +54,10 @@ interface ContentBaseProps {
    * Uses the shared `WidthVariant` scale from `@opal/shared`.
    *
    * - `"auto"` — Shrink-wraps to content width
+   * - `"fit"` — Shrink-wraps to content width
    * - `"full"` — Stretches to fill the parent's width
    *
-   * @default "auto"
+   * @default "fit"
    */
   widthVariant?: WidthVariant;
 
@@ -133,8 +134,6 @@ function Content(props: ContentProps) {
     ...rest
   } = props;
 
-  const widthClass = widthVariants[widthVariant];
-
   let layout: React.ReactNode = null;
 
   // ContentXl / ContentLg: headline/section presets
@@ -194,11 +193,7 @@ function Content(props: ContentProps) {
       `Content: no layout matched for sizePreset="${sizePreset}" variant="${variant}"`
     );
 
-  // "auto" → return layout directly (a block div with w-auto still
-  // stretches to its parent, defeating shrink-to-content).
-  if (widthVariant === "auto") return layout;
-
-  return <div className={widthClass}>{layout}</div>;
+  return <div className={widthVariants[widthVariant]}>{layout}</div>;
 }
 
 // ---------------------------------------------------------------------------
diff --git a/web/lib/opal/src/shared.ts b/web/lib/opal/src/shared.ts
index 0559d17c0e2..f365842e3c1 100644
--- a/web/lib/opal/src/shared.ts
+++ b/web/lib/opal/src/shared.ts
@@ -67,10 +67,12 @@ type SizeVariant = keyof typeof sizeVariants;
  * | Key    | Tailwind class |
  * |--------|----------------|
  * | `auto` | `w-auto`       |
+ * | `fit`  | `w-fit`        |
  * | `full` | `w-full`       |
  */
 const widthVariants = {
   auto: "w-auto",
+  fit: "w-fit",
   full: "w-full",
 } as const;
 

From 5118193d161cc0830b9a2c0b9dea47fcfe52729a Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 9 Mar 2026 13:38:47 -0700
Subject: [PATCH 189/267] fix(fe): move app padding inside overflow container
 (#9206)

---
 web/src/refresh-pages/AppPage.tsx | 6 +++---
 web/src/sections/chat/ChatUI.tsx  | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index cf62181a55e..2a55a2ad9ed 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -676,7 +676,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
             >
               {/* Main content grid — 3 rows, animated */}
               <div
-                className="flex-1 w-full grid min-h-0 px-4 transition-[grid-template-rows] duration-150 ease-in-out"
+                className="flex-1 w-full grid min-h-0 transition-[grid-template-rows] duration-150 ease-in-out"
                 style={gridStyle}
               >
                 {/* ── Top row: ChatUI / WelcomeMessage / ProjectUI ── */}
@@ -741,7 +741,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                 </div>
 
                 {/* ── Middle-center: AppInputBar ── */}
-                <div className="row-start-2 flex flex-col items-center">
+                <div className="row-start-2 flex flex-col items-center px-4">
                   <div className="relative w-full max-w-[var(--app-page-main-content-width)] flex flex-col">
                     {/* Scroll to bottom button - positioned absolutely above AppInputBar */}
                     {appFocus.isChat() && showScrollButton && (
@@ -841,7 +841,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                 </div>
 
                 {/* ── Bottom: SearchResults + SourceFilter / Suggestions / ProjectChatList ── */}
-                <div className="row-start-3 min-h-0 overflow-hidden flex flex-col items-center w-full">
+                <div className="row-start-3 min-h-0 overflow-hidden flex flex-col items-center w-full px-4">
                   {/* Agent description below input */}
                   {(appFocus.isNewSession() || appFocus.isAgent()) &&
                     !isDefaultAgent && (
diff --git a/web/src/sections/chat/ChatUI.tsx b/web/src/sections/chat/ChatUI.tsx
index fd206cba8d2..40d004062eb 100644
--- a/web/src/sections/chat/ChatUI.tsx
+++ b/web/src/sections/chat/ChatUI.tsx
@@ -115,7 +115,7 @@ const ChatUI = React.memo(
 
     return (
       <>
-        <div className="flex flex-col w-full max-w-[var(--app-page-main-content-width)] h-full pt-4 pb-8 pr-1 gap-12">
+        <div className="flex flex-col w-full max-w-[var(--app-page-main-content-width)] h-full p-4 pb-8 pr-5 gap-12">
           {messages.map((message, i) => {
             const messageReactComponentKey = `message-${message.nodeId}`;
             const parentMessage = message.parentNodeId

From edbe569edd87cf12787ae6443d1f0a75e893534e Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 13:45:55 -0700
Subject: [PATCH 190/267] fix: don't fetch mcp tools when no llms are
 configured (#9173)

---
 .../popovers/ActionsPopover/index.tsx                  | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/web/src/refresh-components/popovers/ActionsPopover/index.tsx b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
index 5895f2e711c..94bc729271e 100644
--- a/web/src/refresh-components/popovers/ActionsPopover/index.tsx
+++ b/web/src/refresh-components/popovers/ActionsPopover/index.tsx
@@ -29,6 +29,7 @@ import { SourceMetadata } from "@/lib/search/interfaces";
 import { SourceIcon } from "@/components/SourceIcon";
 import { useAvailableTools } from "@/hooks/useAvailableTools";
 import useCCPairs from "@/hooks/useCCPairs";
+import { useLLMProviders } from "@/hooks/useLLMProviders";
 import { useVectorDbEnabled } from "@/providers/SettingsProvider";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import { useToolOAuthStatus } from "@/lib/hooks/useToolOAuthStatus";
@@ -178,6 +179,10 @@ export default function ActionsPopover({
   // const [showTopShadow, setShowTopShadow] = useState(false);
   const { selectedSources, setSelectedSources } = filterManager;
   const [mcpServers, setMcpServers] = useState<MCPServer[]>([]);
+  const { llmProviders, isLoading: isLLMLoading } = useLLMProviders(
+    selectedAgent.id
+  );
+  const hasAnyProvider = !isLLMLoading && (llmProviders?.length ?? 0) > 0;
 
   // Use the OAuth hook
   const { getToolAuthStatus, authenticateTool } = useToolOAuthStatus(
@@ -493,7 +498,8 @@ export default function ActionsPopover({
 
   // Fetch MCP servers for the agent on mount
   useEffect(() => {
-    if (selectedAgent == null || selectedAgent.id == null) return;
+    if (selectedAgent == null || selectedAgent.id == null || !hasAnyProvider)
+      return;
 
     const abortController = new AbortController();
 
@@ -534,7 +540,7 @@ export default function ActionsPopover({
     return () => {
       abortController.abort();
     };
-  }, [selectedAgent?.id]);
+  }, [selectedAgent?.id, hasAnyProvider]);
 
   // No separate MCP tool loading; tools already exist in selectedAgent.tools
 

From 27df690a8de31c2f7ab768c70819cd8a76fcfe86 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 13:46:58 -0700
Subject: [PATCH 191/267] fix: discord connector async resource cleanup (#9203)

---
 backend/onyx/connectors/discord/connector.py | 22 +++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/backend/onyx/connectors/discord/connector.py b/backend/onyx/connectors/discord/connector.py
index 2ff37fe8e2d..8cfc9f459b3 100644
--- a/backend/onyx/connectors/discord/connector.py
+++ b/backend/onyx/connectors/discord/connector.py
@@ -1,4 +1,5 @@
 import asyncio
+from collections.abc import AsyncGenerator
 from collections.abc import AsyncIterable
 from collections.abc import Iterable
 from datetime import datetime
@@ -204,7 +205,7 @@ def _manage_async_retrieval(
 
     end_time: datetime | None = end
 
-    async def _async_fetch() -> AsyncIterable[Document]:
+    async def _async_fetch() -> AsyncGenerator[Document, None]:
         intents = Intents.default()
         intents.message_content = True
         async with Client(intents=intents) as discord_client:
@@ -227,22 +228,23 @@ async def _async_fetch() -> AsyncIterable[Document]:
 
     def run_and_yield() -> Iterable[Document]:
         loop = asyncio.new_event_loop()
+        async_gen = _async_fetch()
         try:
-            # Get the async generator
-            async_gen = _async_fetch()
-            # Convert to AsyncIterator
-            async_iter = async_gen.__aiter__()
             while True:
                 try:
-                    # Create a coroutine by calling anext with the async iterator
-                    next_coro = anext(async_iter)
-                    # Run the coroutine to get the next document
-                    doc = loop.run_until_complete(next_coro)
+                    doc = loop.run_until_complete(anext(async_gen))
                     yield doc
                 except StopAsyncIteration:
                     break
         finally:
-            loop.close()
+            # Must close the async generator before the loop so the Discord
+            # client's `async with` block can await its shutdown coroutine.
+            # The nested try/finally ensures the loop always closes even if
+            # aclose() raises (same pattern as cursor.close() before conn.close()).
+            try:
+                loop.run_until_complete(async_gen.aclose())
+            finally:
+                loop.close()
 
     return run_and_yield()
 

From fe593a15da2f79096ffa48723d436fc686c22427 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 9 Mar 2026 14:04:20 -0700
Subject: [PATCH 192/267] fix(safari): Search results dont shrink (#9126)

---
 web/src/ee/sections/SearchUI.tsx          | 69 ++++++++++++-----------
 web/src/refresh-components/Pagination.tsx |  4 +-
 2 files changed, 37 insertions(+), 36 deletions(-)

diff --git a/web/src/ee/sections/SearchUI.tsx b/web/src/ee/sections/SearchUI.tsx
index 47d88e604b6..6a7e478ec55 100644
--- a/web/src/ee/sections/SearchUI.tsx
+++ b/web/src/ee/sections/SearchUI.tsx
@@ -198,16 +198,15 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
   const showEmpty = !error && results.length === 0;
 
   return (
-    <>
-      <div
-        className="flex-1 min-h-0 w-full grid gap-x-4"
-        style={{
-          gridTemplateColumns: showEmpty ? "1fr" : "3fr 1fr",
-          gridTemplateRows: "auto 1fr auto",
-        }}
-      >
-        {/* Top-left: Search filters */}
-        <div className="row-start-1 col-start-1 flex flex-col justify-end gap-3">
+    <div className="flex-1 min-h-0 w-full flex flex-col gap-3">
+      {/* ── Top row: Filters + Result count ── */}
+      <div className="flex-shrink-0 flex flex-row gap-x-4">
+        <div
+          className={cn(
+            "flex flex-col justify-end gap-3",
+            showEmpty ? "flex-1" : "flex-[3]"
+          )}
+        >
           <div className="flex flex-row gap-2">
             {/* Time filter */}
             <Popover open={timeFilterOpen} onOpenChange={setTimeFilterOpen}>
@@ -307,9 +306,8 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
           <Separator noPadding />
         </div>
 
-        {/* Top-right: Number of results */}
         {!showEmpty && (
-          <div className="row-start-1 col-start-2 flex flex-col justify-end gap-3">
+          <div className="flex-1 flex flex-col justify-end gap-3">
             <Section alignItems="start">
               <Text text03 mainUiMuted>
                 {results.length} Results
@@ -319,12 +317,14 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
             <Separator noPadding />
           </div>
         )}
+      </div>
 
-        {/* Bottom-left: Search results */}
+      {/* ── Middle row: Results + Source filter ── */}
+      <div className="flex-1 min-h-0 flex flex-row gap-x-4">
         <div
           className={cn(
-            "row-start-2 col-start-1 min-h-0 overflow-y-scroll py-3 flex flex-col gap-2",
-            showEmpty && "justify-center"
+            "min-h-0 overflow-y-scroll flex flex-col gap-2",
+            showEmpty ? "flex-1 justify-center" : "flex-[3]"
           )}
         >
           {error ? (
@@ -332,12 +332,16 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
           ) : paginatedResults.length > 0 ? (
             <>
               {paginatedResults.map((doc) => (
-                <SearchCard
+                <div
                   key={`${doc.document_id}-${doc.chunk_ind}`}
-                  document={doc}
-                  isLlmSelected={llmSelectedSet.has(doc.document_id)}
-                  onDocumentClick={onDocumentClick}
-                />
+                  className="flex-shrink-0"
+                >
+                  <SearchCard
+                    document={doc}
+                    isLlmSelected={llmSelectedSet.has(doc.document_id)}
+                    onDocumentClick={onDocumentClick}
+                  />
+                </div>
               ))}
             </>
           ) : (
@@ -349,20 +353,8 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
           )}
         </div>
 
-        {/* Pagination */}
         {!showEmpty && (
-          <div className="row-start-3 col-start-1 col-span-2 pt-3">
-            <Pagination
-              currentPage={currentPage}
-              totalPages={totalPages}
-              onPageChange={setCurrentPage}
-            />
-          </div>
-        )}
-
-        {/* Bottom-right: Source filter */}
-        {!showEmpty && (
-          <div className="row-start-2 col-start-2 min-h-0 overflow-y-auto flex flex-col gap-4 px-1 py-3">
+          <div className="flex-1 min-h-0 overflow-y-auto flex flex-col gap-4 px-1">
             <Section gap={0.25} height="fit">
               {sourcesWithMeta.map(({ source, meta, count }) => (
                 <LineItem
@@ -386,6 +378,15 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
           </div>
         )}
       </div>
-    </>
+
+      {/* ── Bottom row: Pagination ── */}
+      {!showEmpty && (
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          onPageChange={setCurrentPage}
+        />
+      )}
+    </div>
   );
 }
diff --git a/web/src/refresh-components/Pagination.tsx b/web/src/refresh-components/Pagination.tsx
index a17092fbece..c263c157e45 100644
--- a/web/src/refresh-components/Pagination.tsx
+++ b/web/src/refresh-components/Pagination.tsx
@@ -66,7 +66,7 @@ export default function Pagination({
   const pageNumbers = getPageNumbers();
 
   return (
-    <Section flexDirection="row" gap={0.25}>
+    <Section flexDirection="row" height="auto" gap={0.25}>
       {/* Previous button */}
       <Disabled disabled={currentPage === 1}>
         <Button
@@ -77,7 +77,7 @@ export default function Pagination({
       </Disabled>
 
       {/* Page numbers */}
-      <Section flexDirection="row" gap={0} width="fit">
+      <Section flexDirection="row" height="auto" gap={0} width="fit">
         {pageNumbers.map((page, index) => {
           if (page === "...") {
             return (

From e74c36001a04a83aaeb7f2e2506ffd140cc9c2a2 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 9 Mar 2026 15:55:05 -0700
Subject: [PATCH 193/267] feat(storybook): add Storybook infrastructure - 1/3
 (#9195)

---
 web/.gitignore                                |    3 +
 web/.storybook/README.md                      |   80 +
 web/.storybook/main.ts                        |   42 +
 web/.storybook/mocks/next-image.tsx           |   28 +
 web/.storybook/mocks/next-link.tsx            |   28 +
 web/.storybook/mocks/next-navigation.tsx      |   30 +
 web/.storybook/preview-head.html              |   11 +
 web/.storybook/preview.ts                     |   27 +
 .../opal/src/components/tag/Tag.stories.tsx   |   47 +
 web/package-lock.json                         | 3203 ++++++++++++-----
 web/package.json                              |   10 +-
 11 files changed, 2600 insertions(+), 909 deletions(-)
 create mode 100644 web/.storybook/README.md
 create mode 100644 web/.storybook/main.ts
 create mode 100644 web/.storybook/mocks/next-image.tsx
 create mode 100644 web/.storybook/mocks/next-link.tsx
 create mode 100644 web/.storybook/mocks/next-navigation.tsx
 create mode 100644 web/.storybook/preview-head.html
 create mode 100644 web/.storybook/preview.ts
 create mode 100644 web/lib/opal/src/components/tag/Tag.stories.tsx

diff --git a/web/.gitignore b/web/.gitignore
index f5f923cc062..3e21252dfea 100644
--- a/web/.gitignore
+++ b/web/.gitignore
@@ -47,3 +47,6 @@ next-env.d.ts
 # generated clients ... in particular, the API to the Onyx backend itself!
 /src/lib/generated
 .jest-cache
+
+# storybook
+storybook-static
diff --git a/web/.storybook/README.md b/web/.storybook/README.md
new file mode 100644
index 00000000000..b86ed6df344
--- /dev/null
+++ b/web/.storybook/README.md
@@ -0,0 +1,80 @@
+# Onyx Storybook
+
+Storybook is an isolated development environment for UI components. It renders each component in a standalone "story" outside of the main app, so you can visually verify appearance, interact with props, and catch regressions without navigating through the full application.
+
+The Onyx Storybook covers the full component library — from low-level `@opal/core` primitives up through `refresh-components` — giving designers and engineers a shared reference for every visual state.
+
+**Production:** [onyx-storybook.vercel.app](https://onyx-storybook.vercel.app)
+
+## Running Locally
+
+```bash
+cd web
+npm run storybook        # dev server on http://localhost:6006
+npm run storybook:build  # static build to storybook-static/
+```
+
+The dev server hot-reloads when you edit a component or story file.
+
+## Writing Stories
+
+Stories are **co-located** next to their component source:
+
+```
+lib/opal/src/core/interactive/
+├── components.tsx              ← the component
+├── Interactive.stories.tsx     ← the story
+└── styles.css
+
+src/refresh-components/buttons/
+├── Button.tsx
+└── Button.stories.tsx
+```
+
+### Minimal Template
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { MyComponent } from "./MyComponent";
+
+const meta: Meta<typeof MyComponent> = {
+  title: "Category/MyComponent",   // sidebar path
+  component: MyComponent,
+  tags: ["autodocs"],               // generates a docs page from props
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const Default: Story = {
+  args: { label: "Hello" },
+};
+```
+
+### Conventions
+
+- **Title format:** `Core/Name`, `Components/Name`, `Layouts/Name`, or `refresh-components/category/Name`
+- **Tags:** Add `tags: ["autodocs"]` to auto-generate a props docs page
+- **Decorators:** Components that use Radix tooltips need a `TooltipPrimitive.Provider` decorator
+- **Layout:** Use `parameters: { layout: "fullscreen" }` for modals/popovers that use portals
+
+## Dark Mode
+
+Use the theme toggle (paint roller icon) in the Storybook toolbar to switch between light and dark modes. This adds/removes the `dark` class on the preview body, matching the app's `darkMode: "class"` Tailwind config. All color tokens from `colors.css` adapt automatically.
+
+## Deployment
+
+The production Storybook is deployed as a static site on Vercel. The build runs `npm run storybook:build` which outputs to `storybook-static/`, and Vercel serves that directory.
+
+Deploys are triggered on merges to `main` when files in `web/lib/opal/`, `web/src/refresh-components/`, or `web/.storybook/` change.
+
+## Component Layers
+
+The sidebar organizes components by their layer in the design system:
+
+| Layer | Path | Examples |
+|-------|------|----------|
+| **Core** | `lib/opal/src/core/` | Interactive, Hoverable |
+| **Components** | `lib/opal/src/components/` | Button, OpenButton, Tag |
+| **Layouts** | `lib/opal/src/layouts/` | Content, ContentAction, IllustrationContent |
+| **refresh-components** | `src/refresh-components/` | Inputs, tables, modals, text, cards, tiles, etc. |
diff --git a/web/.storybook/main.ts b/web/.storybook/main.ts
new file mode 100644
index 00000000000..78eb510d0c5
--- /dev/null
+++ b/web/.storybook/main.ts
@@ -0,0 +1,42 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+import path from "path";
+
+const config: StorybookConfig = {
+  stories: [
+    "../lib/opal/src/**/*.stories.@(ts|tsx)",
+    "../src/refresh-components/**/*.stories.@(ts|tsx)",
+  ],
+  addons: ["@storybook/addon-essentials", "@storybook/addon-themes"],
+  framework: {
+    name: "@storybook/react-vite",
+    options: {},
+  },
+  staticDirs: ["../public"],
+  docs: {
+    autodocs: "tag",
+  },
+  typescript: {
+    reactDocgen: "react-docgen-typescript",
+  },
+  viteFinal: async (config) => {
+    config.resolve = config.resolve ?? {};
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      "@": path.resolve(__dirname, "../src"),
+      "@opal": path.resolve(__dirname, "../lib/opal/src"),
+      "@public": path.resolve(__dirname, "../public"),
+      // Next.js module stubs for Vite
+      "next/link": path.resolve(__dirname, "mocks/next-link.tsx"),
+      "next/navigation": path.resolve(__dirname, "mocks/next-navigation.tsx"),
+      "next/image": path.resolve(__dirname, "mocks/next-image.tsx"),
+    };
+
+    // Process CSS with Tailwind via PostCSS
+    config.css = config.css ?? {};
+    config.css.postcss = path.resolve(__dirname, "..");
+
+    return config;
+  },
+};
+
+export default config;
diff --git a/web/.storybook/mocks/next-image.tsx b/web/.storybook/mocks/next-image.tsx
new file mode 100644
index 00000000000..46cb2a9a327
--- /dev/null
+++ b/web/.storybook/mocks/next-image.tsx
@@ -0,0 +1,28 @@
+import React from "react";
+
+interface ImageProps {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+  fill?: boolean;
+  [key: string]: unknown;
+}
+
+function Image({ src, alt, width, height, fill, ...props }: ImageProps) {
+  const fillStyle: React.CSSProperties = fill
+    ? { position: "absolute", inset: 0, width: "100%", height: "100%" }
+    : {};
+  return (
+    <img
+      {...(props as React.ImgHTMLAttributes<HTMLImageElement>)}
+      src={src}
+      alt={alt}
+      width={fill ? undefined : width}
+      height={fill ? undefined : height}
+      style={{ ...(props.style as React.CSSProperties), ...fillStyle }}
+    />
+  );
+}
+
+export default Image;
diff --git a/web/.storybook/mocks/next-link.tsx b/web/.storybook/mocks/next-link.tsx
new file mode 100644
index 00000000000..d9bfc900cdd
--- /dev/null
+++ b/web/.storybook/mocks/next-link.tsx
@@ -0,0 +1,28 @@
+import React from "react";
+
+interface LinkProps {
+  href: string;
+  children: React.ReactNode;
+  [key: string]: unknown;
+}
+
+function Link({
+  href,
+  children,
+  prefetch: _prefetch,
+  scroll: _scroll,
+  shallow: _shallow,
+  replace: _replace,
+  passHref: _passHref,
+  locale: _locale,
+  legacyBehavior: _legacyBehavior,
+  ...props
+}: LinkProps) {
+  return (
+    <a href={href} {...props}>
+      {children}
+    </a>
+  );
+}
+
+export default Link;
diff --git a/web/.storybook/mocks/next-navigation.tsx b/web/.storybook/mocks/next-navigation.tsx
new file mode 100644
index 00000000000..b1a0a719f50
--- /dev/null
+++ b/web/.storybook/mocks/next-navigation.tsx
@@ -0,0 +1,30 @@
+export function useRouter() {
+  return {
+    push: (_url: string) => {},
+    replace: (_url: string) => {},
+    back: () => {},
+    forward: () => {},
+    refresh: () => {},
+    prefetch: (_url: string) => Promise.resolve(),
+  };
+}
+
+export function usePathname() {
+  return "/";
+}
+
+export function useSearchParams() {
+  return new URLSearchParams() as ReadonlyURLSearchParams;
+}
+
+export function useParams() {
+  return {};
+}
+
+export function redirect(_url: string): never {
+  throw new Error("redirect() called in Storybook");
+}
+
+export function notFound(): never {
+  throw new Error("notFound() called in Storybook");
+}
diff --git a/web/.storybook/preview-head.html b/web/.storybook/preview-head.html
new file mode 100644
index 00000000000..0e65b15b823
--- /dev/null
+++ b/web/.storybook/preview-head.html
@@ -0,0 +1,11 @@
+<!-- Preconnect for fonts loaded via globals.css @import -->
+<link
+  rel="preconnect"
+  href="https://fonts.googleapis.com"
+  crossorigin="anonymous"
+/>
+<link
+  rel="preconnect"
+  href="https://fonts.gstatic.com"
+  crossorigin="anonymous"
+/>
diff --git a/web/.storybook/preview.ts b/web/.storybook/preview.ts
new file mode 100644
index 00000000000..af3bccd8a48
--- /dev/null
+++ b/web/.storybook/preview.ts
@@ -0,0 +1,27 @@
+import type { Preview } from "@storybook/react";
+import { withThemeByClassName } from "@storybook/addon-themes";
+import "../src/app/globals.css";
+
+const preview: Preview = {
+  parameters: {
+    layout: "centered",
+    backgrounds: { disable: true },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+  decorators: [
+    withThemeByClassName({
+      themes: {
+        light: "",
+        dark: "dark",
+      },
+      defaultTheme: "light",
+    }),
+  ],
+};
+
+export default preview;
diff --git a/web/lib/opal/src/components/tag/Tag.stories.tsx b/web/lib/opal/src/components/tag/Tag.stories.tsx
new file mode 100644
index 00000000000..e80bf36fa9c
--- /dev/null
+++ b/web/lib/opal/src/components/tag/Tag.stories.tsx
@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tag } from "@opal/components";
+import { SvgAlertCircle } from "@opal/icons";
+
+const TAG_COLORS = ["green", "purple", "blue", "gray", "amber"] as const;
+
+const meta: Meta<typeof Tag> = {
+  title: "opal/components/Tag",
+  component: Tag,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Tag>;
+
+export const Default: Story = {
+  args: {
+    title: "Label",
+  },
+};
+
+export const AllColors: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      {TAG_COLORS.map((color) => (
+        <Tag key={color} title={color} color={color} />
+      ))}
+    </div>
+  ),
+};
+
+export const WithIcon: Story = {
+  args: {
+    title: "Alert",
+    icon: SvgAlertCircle,
+  },
+};
+
+export const AllColorsWithIcon: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      {TAG_COLORS.map((color) => (
+        <Tag key={color} title={color} color={color} icon={SvgAlertCircle} />
+      ))}
+    </div>
+  ),
+};
diff --git a/web/package-lock.json b/web/package-lock.json
index 893bb21683d..2031b70bc81 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -94,6 +94,11 @@
       },
       "devDependencies": {
         "@playwright/test": "^1.39.0",
+        "@storybook/addon-essentials": "^8.6.18",
+        "@storybook/addon-themes": "^8.6.18",
+        "@storybook/blocks": "^8.6.18",
+        "@storybook/react": "^8.6.18",
+        "@storybook/react-vite": "^8.6.18",
         "@tailwindcss/typography": "^0.5.19",
         "@testing-library/jest-dom": "^6.9.1",
         "@testing-library/react": "^16.3.0",
@@ -119,6 +124,7 @@
         "jest-environment-jsdom": "^30.2.0",
         "prettier": "3.1.0",
         "stats.js": "^0.17.0",
+        "storybook": "^8.6.18",
         "tailwindcss": "^3.4.17",
         "ts-jest": "^29.2.5",
         "ts-unused-exports": "^11.0.1",
@@ -953,462 +959,904 @@
       "version": "0.4.0",
       "license": "MIT"
     },
-    "node_modules/@eslint-community/eslint-utils": {
-      "version": "4.9.0",
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
+      "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
+      "cpu": [
+        "ppc64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "eslint-visitor-keys": "^3.4.3"
-      },
+      "optional": true,
+      "os": [
+        "aix"
+      ],
       "engines": {
-        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/eslint"
-      },
-      "peerDependencies": {
-        "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint-community/eslint-utils/node_modules/eslint-visitor-keys": {
-      "version": "3.4.3",
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz",
+      "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==",
+      "cpu": [
+        "arm"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
       "engines": {
-        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/eslint"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint-community/regexpp": {
-      "version": "4.12.2",
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz",
+      "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
       "engines": {
-        "node": "^12.0.0 || ^14.0.0 || >=16.0.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/config-array": {
-      "version": "0.21.1",
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz",
+      "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@eslint/object-schema": "^2.1.7",
-        "debug": "^4.3.1",
-        "minimatch": "^3.1.2"
-      },
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/config-helpers": {
-      "version": "0.4.2",
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz",
+      "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@eslint/core": "^0.17.0"
-      },
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/core": {
-      "version": "0.17.0",
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz",
+      "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@types/json-schema": "^7.0.15"
-      },
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/eslintrc": {
-      "version": "3.3.1",
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "ajv": "^6.12.4",
-        "debug": "^4.3.2",
-        "espree": "^10.0.1",
-        "globals": "^14.0.0",
-        "ignore": "^5.2.0",
-        "import-fresh": "^3.2.1",
-        "js-yaml": "^4.1.0",
-        "minimatch": "^3.1.2",
-        "strip-json-comments": "^3.1.1"
-      },
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/eslint"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/eslintrc/node_modules/ajv": {
-      "version": "6.14.0",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
-      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz",
+      "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "fast-deep-equal": "^3.1.1",
-        "fast-json-stable-stringify": "^2.0.0",
-        "json-schema-traverse": "^0.4.1",
-        "uri-js": "^4.2.2"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/epoberezkin"
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/eslintrc/node_modules/globals": {
-      "version": "14.0.0",
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz",
+      "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==",
+      "cpu": [
+        "arm"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/@eslint/eslintrc/node_modules/json-schema-traverse": {
-      "version": "0.4.1",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/@eslint/js": {
-      "version": "9.39.1",
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz",
+      "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "url": "https://eslint.org/donate"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/object-schema": {
-      "version": "2.1.7",
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz",
+      "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==",
+      "cpu": [
+        "ia32"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@eslint/plugin-kit": {
-      "version": "0.4.1",
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz",
+      "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==",
+      "cpu": [
+        "loong64"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@eslint/core": "^0.17.0",
-        "levn": "^0.4.1"
-      },
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+        "node": ">=18"
       }
     },
-    "node_modules/@floating-ui/core": {
-      "version": "1.7.3",
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz",
+      "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@floating-ui/utils": "^0.2.10"
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@floating-ui/dom": {
-      "version": "1.7.4",
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz",
+      "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@floating-ui/core": "^1.7.3",
-        "@floating-ui/utils": "^0.2.10"
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@floating-ui/react": {
-      "version": "0.26.28",
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz",
+      "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@floating-ui/react-dom": "^2.1.2",
-        "@floating-ui/utils": "^0.2.8",
-        "tabbable": "^6.0.0"
-      },
-      "peerDependencies": {
-        "react": ">=16.8.0",
-        "react-dom": ">=16.8.0"
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@floating-ui/react-dom": {
-      "version": "2.1.6",
-      "license": "MIT",
-      "dependencies": {
-        "@floating-ui/dom": "^1.7.4"
-      },
-      "peerDependencies": {
-        "react": ">=16.8.0",
-        "react-dom": ">=16.8.0"
-      }
-    },
-    "node_modules/@floating-ui/utils": {
-      "version": "0.2.10",
-      "license": "MIT"
-    },
-    "node_modules/@headlessui/react": {
-      "version": "2.2.9",
-      "license": "MIT",
-      "dependencies": {
-        "@floating-ui/react": "^0.26.16",
-        "@react-aria/focus": "^3.20.2",
-        "@react-aria/interactions": "^3.25.0",
-        "@tanstack/react-virtual": "^3.13.9",
-        "use-sync-external-store": "^1.5.0"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "peerDependencies": {
-        "react": "^18 || ^19 || ^19.0.0-rc",
-        "react-dom": "^18 || ^19 || ^19.0.0-rc"
-      }
-    },
-    "node_modules/@headlessui/tailwindcss": {
-      "version": "0.2.2",
-      "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      },
-      "peerDependencies": {
-        "tailwindcss": "^3.0 || ^4.0"
-      }
-    },
-    "node_modules/@humanfs/core": {
-      "version": "0.19.1",
-      "dev": true,
-      "license": "Apache-2.0",
-      "engines": {
-        "node": ">=18.18.0"
-      }
-    },
-    "node_modules/@humanfs/node": {
-      "version": "0.16.7",
-      "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@humanfs/core": "^0.19.1",
-        "@humanwhocodes/retry": "^0.4.0"
-      },
-      "engines": {
-        "node": ">=18.18.0"
-      }
-    },
-    "node_modules/@humanwhocodes/module-importer": {
-      "version": "1.0.1",
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz",
+      "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==",
+      "cpu": [
+        "s390x"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": ">=12.22"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/nzakas"
+        "node": ">=18"
       }
     },
-    "node_modules/@humanwhocodes/retry": {
-      "version": "0.4.3",
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz",
+      "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
-      "license": "Apache-2.0",
-      "engines": {
-        "node": ">=18.18"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/nzakas"
-      }
-    },
-    "node_modules/@img/colour": {
-      "version": "1.0.0",
       "license": "MIT",
       "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
         "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-darwin-arm64": {
-      "version": "0.33.5",
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==",
       "cpu": [
         "arm64"
       ],
-      "license": "Apache-2.0",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "darwin"
+        "netbsd"
       ],
       "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-darwin-arm64": "1.0.4"
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-darwin-x64": {
-      "version": "0.33.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.33.5.tgz",
-      "integrity": "sha512-fyHac4jIc1ANYGRDxtiqelIbdWkIuQaI84Mv45KvGRRxSAa7o7d1ZKAOBaYbnepLC1WqxfpimdeWfvqqSGwR2Q==",
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==",
       "cpu": [
         "x64"
       ],
-      "license": "Apache-2.0",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "darwin"
+        "netbsd"
       ],
       "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-darwin-x64": "1.0.4"
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-darwin-arm64": {
-      "version": "1.0.4",
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==",
       "cpu": [
         "arm64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "darwin"
+        "openbsd"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-darwin-x64": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.0.4.tgz",
-      "integrity": "sha512-xnGR8YuZYfJGmWPvmlunFaWJsb9T/AO2ykoP3Fz/0X5XV2aoYBPkX6xqCQvUTKKiLddarLaxpzNe+b1hjeWHAQ==",
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==",
       "cpu": [
         "x64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "darwin"
+        "openbsd"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-linux-arm": {
-      "version": "1.0.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.0.5.tgz",
-      "integrity": "sha512-gvcC4ACAOPRNATg/ov8/MnbxFDJqf/pDePbBnuBDcjsI8PssmjoKMAz4LtLaVi+OnSb5FK/yIOamqDwGmXW32g==",
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz",
+      "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==",
       "cpu": [
-        "arm"
+        "arm64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "openharmony"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-linux-arm64": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.0.4.tgz",
-      "integrity": "sha512-9B+taZ8DlyyqzZQnoeIvDVR/2F4EbMepXMc/NdVbkzsJbzkUjhXv/70GQJ7tdLA4YJgNP25zukcxpX2/SueNrA==",
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz",
+      "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==",
       "cpu": [
-        "arm64"
+        "x64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "sunos"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-linux-ppc64": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.3.tgz",
-      "integrity": "sha512-Y2T7IsQvJLMCBM+pmPbM3bKT/yYJvVtLJGfCs4Sp95SjvnFIjynbjzsa7dY1fRJX45FTSfDksbTp6AGWudiyCg==",
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz",
+      "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==",
       "cpu": [
-        "ppc64"
+        "arm64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "win32"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-linux-s390x": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.0.4.tgz",
-      "integrity": "sha512-u7Wz6ntiSSgGSGcjZ55im6uvTrOxSIS8/dgoVMoiGE9I6JAfU50yH5BoDlYA1tcuGS7g/QNtetJnxA6QEsCVTA==",
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz",
+      "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==",
       "cpu": [
-        "s390x"
+        "ia32"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "win32"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-linux-x64": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.0.4.tgz",
-      "integrity": "sha512-MmWmQ3iPFZr0Iev+BAgVMb3ZyC4KeFc3jFxnNbEPas60e1cIfevbtuyf9nDGIzOaW9PdnDciJm+wFFaTlj5xYw==",
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz",
+      "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==",
       "cpu": [
         "x64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "dev": true,
+      "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "win32"
       ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
+      "engines": {
+        "node": ">=18"
       }
     },
-    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.0.4.tgz",
-      "integrity": "sha512-9Ti+BbTYDcsbp4wfYib8Ctm1ilkugkA/uscUn6UXK1ldpC1JjiXbLfFZtRlBhjPZ5o1NCLiDbg8fhUPKStHoTA==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "LGPL-3.0-or-later",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
+    "node_modules/@eslint-community/eslint-utils": {
+      "version": "4.9.0",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eslint-visitor-keys": "^3.4.3"
+      },
+      "engines": {
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+      },
       "funding": {
-        "url": "https://opencollective.com/libvips"
+        "url": "https://opencollective.com/eslint"
+      },
+      "peerDependencies": {
+        "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0"
       }
     },
-    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.0.4.tgz",
-      "integrity": "sha512-viYN1KX9m+/hGkJtvYYp+CCLgnJXwiQB39damAO7WMdKWlIhmYTfHjwSbQeUK/20vY154mwezd9HflVFM1wVSw==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "LGPL-3.0-or-later",
+    "node_modules/@eslint-community/eslint-utils/node_modules/eslint-visitor-keys": {
+      "version": "3.4.3",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/@eslint-community/regexpp": {
+      "version": "4.12.2",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.0.0 || ^14.0.0 || >=16.0.0"
+      }
+    },
+    "node_modules/@eslint/config-array": {
+      "version": "0.21.1",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/object-schema": "^2.1.7",
+        "debug": "^4.3.1",
+        "minimatch": "^3.1.2"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/config-helpers": {
+      "version": "0.4.2",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/core": "^0.17.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/core": {
+      "version": "0.17.0",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@types/json-schema": "^7.0.15"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/eslintrc": {
+      "version": "3.3.1",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^6.12.4",
+        "debug": "^4.3.2",
+        "espree": "^10.0.1",
+        "globals": "^14.0.0",
+        "ignore": "^5.2.0",
+        "import-fresh": "^3.2.1",
+        "js-yaml": "^4.1.0",
+        "minimatch": "^3.1.2",
+        "strip-json-comments": "^3.1.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/@eslint/eslintrc/node_modules/ajv": {
+      "version": "6.14.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
+      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.1",
+        "fast-json-stable-stringify": "^2.0.0",
+        "json-schema-traverse": "^0.4.1",
+        "uri-js": "^4.2.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/@eslint/eslintrc/node_modules/globals": {
+      "version": "14.0.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/@eslint/eslintrc/node_modules/json-schema-traverse": {
+      "version": "0.4.1",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@eslint/js": {
+      "version": "9.39.1",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
+      }
+    },
+    "node_modules/@eslint/object-schema": {
+      "version": "2.1.7",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/plugin-kit": {
+      "version": "0.4.1",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/core": "^0.17.0",
+        "levn": "^0.4.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@floating-ui/core": {
+      "version": "1.7.3",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/utils": "^0.2.10"
+      }
+    },
+    "node_modules/@floating-ui/dom": {
+      "version": "1.7.4",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/core": "^1.7.3",
+        "@floating-ui/utils": "^0.2.10"
+      }
+    },
+    "node_modules/@floating-ui/react": {
+      "version": "0.26.28",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/react-dom": "^2.1.2",
+        "@floating-ui/utils": "^0.2.8",
+        "tabbable": "^6.0.0"
+      },
+      "peerDependencies": {
+        "react": ">=16.8.0",
+        "react-dom": ">=16.8.0"
+      }
+    },
+    "node_modules/@floating-ui/react-dom": {
+      "version": "2.1.6",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/dom": "^1.7.4"
+      },
+      "peerDependencies": {
+        "react": ">=16.8.0",
+        "react-dom": ">=16.8.0"
+      }
+    },
+    "node_modules/@floating-ui/utils": {
+      "version": "0.2.10",
+      "license": "MIT"
+    },
+    "node_modules/@headlessui/react": {
+      "version": "2.2.9",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/react": "^0.26.16",
+        "@react-aria/focus": "^3.20.2",
+        "@react-aria/interactions": "^3.25.0",
+        "@tanstack/react-virtual": "^3.13.9",
+        "use-sync-external-store": "^1.5.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "react": "^18 || ^19 || ^19.0.0-rc",
+        "react-dom": "^18 || ^19 || ^19.0.0-rc"
+      }
+    },
+    "node_modules/@headlessui/tailwindcss": {
+      "version": "0.2.2",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "tailwindcss": "^3.0 || ^4.0"
+      }
+    },
+    "node_modules/@humanfs/core": {
+      "version": "0.19.1",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanfs/node": {
+      "version": "0.16.7",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@humanfs/core": "^0.19.1",
+        "@humanwhocodes/retry": "^0.4.0"
+      },
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanwhocodes/module-importer": {
+      "version": "1.0.1",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.22"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/nzakas"
+      }
+    },
+    "node_modules/@humanwhocodes/retry": {
+      "version": "0.4.3",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.18"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/nzakas"
+      }
+    },
+    "node_modules/@img/colour": {
+      "version": "1.0.0",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.33.5",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.33.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.33.5.tgz",
+      "integrity": "sha512-fyHac4jIc1ANYGRDxtiqelIbdWkIuQaI84Mv45KvGRRxSAa7o7d1ZKAOBaYbnepLC1WqxfpimdeWfvqqSGwR2Q==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.0.4"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.0.4",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.0.4.tgz",
+      "integrity": "sha512-xnGR8YuZYfJGmWPvmlunFaWJsb9T/AO2ykoP3Fz/0X5XV2aoYBPkX6xqCQvUTKKiLddarLaxpzNe+b1hjeWHAQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.0.5.tgz",
+      "integrity": "sha512-gvcC4ACAOPRNATg/ov8/MnbxFDJqf/pDePbBnuBDcjsI8PssmjoKMAz4LtLaVi+OnSb5FK/yIOamqDwGmXW32g==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.0.4.tgz",
+      "integrity": "sha512-9B+taZ8DlyyqzZQnoeIvDVR/2F4EbMepXMc/NdVbkzsJbzkUjhXv/70GQJ7tdLA4YJgNP25zukcxpX2/SueNrA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-ppc64": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.3.tgz",
+      "integrity": "sha512-Y2T7IsQvJLMCBM+pmPbM3bKT/yYJvVtLJGfCs4Sp95SjvnFIjynbjzsa7dY1fRJX45FTSfDksbTp6AGWudiyCg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.0.4.tgz",
+      "integrity": "sha512-u7Wz6ntiSSgGSGcjZ55im6uvTrOxSIS8/dgoVMoiGE9I6JAfU50yH5BoDlYA1tcuGS7g/QNtetJnxA6QEsCVTA==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.0.4.tgz",
+      "integrity": "sha512-MmWmQ3iPFZr0Iev+BAgVMb3ZyC4KeFc3jFxnNbEPas60e1cIfevbtuyf9nDGIzOaW9PdnDciJm+wFFaTlj5xYw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.0.4.tgz",
+      "integrity": "sha512-9Ti+BbTYDcsbp4wfYib8Ctm1ilkugkA/uscUn6UXK1ldpC1JjiXbLfFZtRlBhjPZ5o1NCLiDbg8fhUPKStHoTA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.0.4.tgz",
+      "integrity": "sha512-viYN1KX9m+/hGkJtvYYp+CCLgnJXwiQB39damAO7WMdKWlIhmYTfHjwSbQeUK/20vY154mwezd9HflVFM1wVSw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
         "linux"
@@ -2337,6 +2785,40 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/@joshwooding/vite-plugin-react-docgen-typescript": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/@joshwooding/vite-plugin-react-docgen-typescript/-/vite-plugin-react-docgen-typescript-0.5.0.tgz",
+      "integrity": "sha512-qYDdL7fPwLRI+bJNurVcis+tNgJmvWjH4YTBGXTA8xMuxFrnAz6E5o35iyzyKbq5J5Lr8mJGfrR5GXl+WGwhgQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "glob": "^10.0.0",
+        "magic-string": "^0.27.0",
+        "react-docgen-typescript": "^2.2.2"
+      },
+      "peerDependencies": {
+        "typescript": ">= 4.3.x",
+        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@joshwooding/vite-plugin-react-docgen-typescript/node_modules/magic-string": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.27.0.tgz",
+      "integrity": "sha512-8UnnX2PeRAPZuN12svgR9j7M1uWMovg/CEnIwIG0LFkXSJJe4PdfUGiTGl8V9bsBHFUtfVINcSyYxd7q+kx9fA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.4.13"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "license": "MIT",
@@ -2381,6 +2863,24 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@mdx-js/react": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.1.tgz",
+      "integrity": "sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdx": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      },
+      "peerDependencies": {
+        "@types/react": ">=16",
+        "react": ">=16"
+      }
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "0.2.12",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-0.2.12.tgz",
@@ -4558,15 +5058,132 @@
       "license": "MIT",
       "optional": true,
       "os": [
-        "freebsd"
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.59.0.tgz",
+      "integrity": "sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.59.0.tgz",
+      "integrity": "sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.59.0.tgz",
+      "integrity": "sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.59.0.tgz",
+      "integrity": "sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.59.0.tgz",
+      "integrity": "sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.59.0.tgz",
+      "integrity": "sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.59.0.tgz",
+      "integrity": "sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.59.0.tgz",
+      "integrity": "sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.59.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.59.0.tgz",
+      "integrity": "sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
       ]
     },
-    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.59.0.tgz",
-      "integrity": "sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.59.0.tgz",
+      "integrity": "sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==",
       "cpu": [
-        "arm"
+        "riscv64"
       ],
       "license": "MIT",
       "optional": true,
@@ -4574,12 +5191,12 @@
         "linux"
       ]
     },
-    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.59.0.tgz",
-      "integrity": "sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.59.0.tgz",
+      "integrity": "sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==",
       "cpu": [
-        "arm"
+        "s390x"
       ],
       "license": "MIT",
       "optional": true,
@@ -4587,12 +5204,12 @@
         "linux"
       ]
     },
-    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.59.0.tgz",
-      "integrity": "sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.59.0.tgz",
+      "integrity": "sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==",
       "cpu": [
-        "arm64"
+        "x64"
       ],
       "license": "MIT",
       "optional": true,
@@ -4600,12 +5217,12 @@
         "linux"
       ]
     },
-    "node_modules/@rollup/rollup-linux-arm64-musl": {
+    "node_modules/@rollup/rollup-linux-x64-musl": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.59.0.tgz",
-      "integrity": "sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.59.0.tgz",
+      "integrity": "sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==",
       "cpu": [
-        "arm64"
+        "x64"
       ],
       "license": "MIT",
       "optional": true,
@@ -4613,754 +5230,1139 @@
         "linux"
       ]
     },
-    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+    "node_modules/@rollup/rollup-openbsd-x64": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.59.0.tgz",
-      "integrity": "sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.59.0.tgz",
+      "integrity": "sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==",
       "cpu": [
-        "loong64"
+        "x64"
       ],
       "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "openbsd"
       ]
     },
-    "node_modules/@rollup/rollup-linux-loong64-musl": {
+    "node_modules/@rollup/rollup-openharmony-arm64": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.59.0.tgz",
-      "integrity": "sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.59.0.tgz",
+      "integrity": "sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==",
       "cpu": [
-        "loong64"
+        "arm64"
       ],
       "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "openharmony"
       ]
     },
-    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.59.0.tgz",
-      "integrity": "sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.59.0.tgz",
+      "integrity": "sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==",
       "cpu": [
-        "ppc64"
+        "arm64"
       ],
       "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "win32"
       ]
     },
-    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.59.0.tgz",
-      "integrity": "sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.59.0.tgz",
+      "integrity": "sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==",
       "cpu": [
-        "ppc64"
+        "ia32"
       ],
       "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "win32"
       ]
     },
-    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.59.0.tgz",
-      "integrity": "sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.59.0.tgz",
+      "integrity": "sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==",
       "cpu": [
-        "riscv64"
+        "x64"
       ],
       "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
+        "win32"
       ]
     },
-    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
       "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.59.0.tgz",
-      "integrity": "sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.59.0.tgz",
+      "integrity": "sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==",
       "cpu": [
-        "riscv64"
+        "x64"
       ],
       "license": "MIT",
       "optional": true,
       "os": [
-        "linux"
-      ]
+        "win32"
+      ]
+    },
+    "node_modules/@rtsao/scc": {
+      "version": "1.1.0",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@sentry-internal/browser-utils": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/browser-utils/-/browser-utils-10.38.0.tgz",
+      "integrity": "sha512-UOJtYmdcxHCcV0NPfXFff/a95iXl/E0EhuQ1y0uE0BuZDMupWSF5t2BgC4HaE5Aw3RTjDF3XkSHWoIF6ohy7eA==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry/core": "10.38.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/feedback": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/feedback/-/feedback-10.38.0.tgz",
+      "integrity": "sha512-JXneg9zRftyfy1Fyfc39bBlF/Qd8g4UDublFFkVvdc1S6JQPlK+P6q22DKz3Pc8w3ySby+xlIq/eTu9Pzqi4KA==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry/core": "10.38.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/replay": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/replay/-/replay-10.38.0.tgz",
+      "integrity": "sha512-YWIkL6/dnaiQyFiZXJ/nN+NXGv/15z45ia86bE/TMq01CubX/DUOilgsFz0pk2v/pg3tp/U2MskLO9Hz0cnqeg==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry-internal/browser-utils": "10.38.0",
+        "@sentry/core": "10.38.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/replay-canvas": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/replay-canvas/-/replay-canvas-10.38.0.tgz",
+      "integrity": "sha512-OXWM9jEqNYh4VTvrMu7v+z1anz+QKQ/fZXIZdsO7JTT2lGNZe58UUMeoq386M+Saxen8F9SUH7yTORy/8KI5qw==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry-internal/replay": "10.38.0",
+        "@sentry/core": "10.38.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/tracing": {
+      "version": "7.120.4",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry/core": "7.120.4",
+        "@sentry/types": "7.120.4",
+        "@sentry/utils": "7.120.4"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@sentry-internal/tracing/node_modules/@sentry/core": {
+      "version": "7.120.4",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry/types": "7.120.4",
+        "@sentry/utils": "7.120.4"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@sentry/babel-plugin-component-annotate": {
+      "version": "4.8.0",
+      "resolved": "https://registry.npmjs.org/@sentry/babel-plugin-component-annotate/-/babel-plugin-component-annotate-4.8.0.tgz",
+      "integrity": "sha512-cy/9Eipkv23MsEJ4IuB4dNlVwS9UqOzI3Eu+QPake5BVFgPYCX0uP0Tr3Z43Ime6Rb+BiDnWC51AJK9i9afHYw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@sentry/browser": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry/browser/-/browser-10.38.0.tgz",
+      "integrity": "sha512-3phzp1YX4wcQr9mocGWKbjv0jwtuoDBv7+Y6Yfrys/kwyaL84mDLjjQhRf4gL5SX7JdYkhBp4WaiNlR0UC4kTA==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry-internal/browser-utils": "10.38.0",
+        "@sentry-internal/feedback": "10.38.0",
+        "@sentry-internal/replay": "10.38.0",
+        "@sentry-internal/replay-canvas": "10.38.0",
+        "@sentry/core": "10.38.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry/bundler-plugin-core": {
+      "version": "4.8.0",
+      "resolved": "https://registry.npmjs.org/@sentry/bundler-plugin-core/-/bundler-plugin-core-4.8.0.tgz",
+      "integrity": "sha512-QaXd/NzaZ2vmiA2FNu2nBkgQU+17N3fE+zVOTzG0YK54QDSJMd4n3AeJIEyPhSzkOob+GqtO22nbYf6AATFMAw==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.18.5",
+        "@sentry/babel-plugin-component-annotate": "4.8.0",
+        "@sentry/cli": "^2.57.0",
+        "dotenv": "^16.3.1",
+        "find-up": "^5.0.0",
+        "glob": "^10.5.0",
+        "magic-string": "0.30.8",
+        "unplugin": "1.0.1"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@sentry/bundler-plugin-core/node_modules/magic-string": {
+      "version": "0.30.8",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.8.tgz",
+      "integrity": "sha512-ISQTe55T2ao7XtlAStud6qwYPZjE4GK1S/BeVPus4jrq6JuOnQ00YKQC581RWhR122W7msZV263KzVeLoqidyQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.4.15"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@sentry/cli": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli/-/cli-2.58.4.tgz",
+      "integrity": "sha512-ArDrpuS8JtDYEvwGleVE+FgR+qHaOp77IgdGSacz6SZy6Lv90uX0Nu4UrHCQJz8/xwIcNxSqnN22lq0dH4IqTg==",
+      "hasInstallScript": true,
+      "license": "FSL-1.1-MIT",
+      "dependencies": {
+        "https-proxy-agent": "^5.0.0",
+        "node-fetch": "^2.6.7",
+        "progress": "^2.0.3",
+        "proxy-from-env": "^1.1.0",
+        "which": "^2.0.2"
+      },
+      "bin": {
+        "sentry-cli": "bin/sentry-cli"
+      },
+      "engines": {
+        "node": ">= 10"
+      },
+      "optionalDependencies": {
+        "@sentry/cli-darwin": "2.58.4",
+        "@sentry/cli-linux-arm": "2.58.4",
+        "@sentry/cli-linux-arm64": "2.58.4",
+        "@sentry/cli-linux-i686": "2.58.4",
+        "@sentry/cli-linux-x64": "2.58.4",
+        "@sentry/cli-win32-arm64": "2.58.4",
+        "@sentry/cli-win32-i686": "2.58.4",
+        "@sentry/cli-win32-x64": "2.58.4"
+      }
+    },
+    "node_modules/@sentry/cli-darwin": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-darwin/-/cli-darwin-2.58.4.tgz",
+      "integrity": "sha512-kbTD+P4X8O+nsNwPxCywtj3q22ecyRHWff98rdcmtRrvwz8CKi/T4Jxn/fnn2i4VEchy08OWBuZAqaA5Kh2hRQ==",
+      "license": "FSL-1.1-MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-linux-s390x-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.59.0.tgz",
-      "integrity": "sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==",
+    "node_modules/@sentry/cli-linux-arm": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-arm/-/cli-linux-arm-2.58.4.tgz",
+      "integrity": "sha512-rdQ8beTwnN48hv7iV7e7ZKucPec5NJkRdrrycMJMZlzGBPi56LqnclgsHySJ6Kfq506A2MNuQnKGaf/sBC9REA==",
       "cpu": [
-        "s390x"
+        "arm"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
-        "linux"
-      ]
+        "linux",
+        "freebsd",
+        "android"
+      ],
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-linux-x64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.59.0.tgz",
-      "integrity": "sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==",
+    "node_modules/@sentry/cli-linux-arm64": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-arm64/-/cli-linux-arm64-2.58.4.tgz",
+      "integrity": "sha512-0g0KwsOozkLtzN8/0+oMZoOuQ0o7W6O+hx+ydVU1bktaMGKEJLMAWxOQNjsh1TcBbNIXVOKM/I8l0ROhaAb8Ig==",
       "cpu": [
-        "x64"
+        "arm64"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
-        "linux"
-      ]
+        "linux",
+        "freebsd",
+        "android"
+      ],
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-linux-x64-musl": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.59.0.tgz",
-      "integrity": "sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==",
+    "node_modules/@sentry/cli-linux-i686": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-i686/-/cli-linux-i686-2.58.4.tgz",
+      "integrity": "sha512-NseoIQAFtkziHyjZNPTu1Gm1opeQHt7Wm1LbLrGWVIRvUOzlslO9/8i6wETUZ6TjlQxBVRgd3Q0lRBG2A8rFYA==",
       "cpu": [
-        "x64"
+        "x86",
+        "ia32"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
-        "linux"
-      ]
+        "linux",
+        "freebsd",
+        "android"
+      ],
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-openbsd-x64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.59.0.tgz",
-      "integrity": "sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==",
+    "node_modules/@sentry/cli-linux-x64": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-x64/-/cli-linux-x64-2.58.4.tgz",
+      "integrity": "sha512-d3Arz+OO/wJYTqCYlSN3Ktm+W8rynQ/IMtSZLK8nu0ryh5mJOh+9XlXY6oDXw4YlsM8qCRrNquR8iEI1Y/IH+Q==",
       "cpu": [
         "x64"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
-        "openbsd"
-      ]
-    },
-    "node_modules/@rollup/rollup-openharmony-arm64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.59.0.tgz",
-      "integrity": "sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==",
-      "cpu": [
-        "arm64"
+        "linux",
+        "freebsd",
+        "android"
       ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openharmony"
-      ]
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-win32-arm64-msvc": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.59.0.tgz",
-      "integrity": "sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==",
+    "node_modules/@sentry/cli-win32-arm64": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-win32-arm64/-/cli-win32-arm64-2.58.4.tgz",
+      "integrity": "sha512-bqYrF43+jXdDBh0f8HIJU3tbvlOFtGyRjHB8AoRuMQv9TEDUfENZyCelhdjA+KwDKYl48R1Yasb4EHNzsoO83w==",
       "cpu": [
         "arm64"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
         "win32"
-      ]
+      ],
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-win32-ia32-msvc": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.59.0.tgz",
-      "integrity": "sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==",
+    "node_modules/@sentry/cli-win32-i686": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-win32-i686/-/cli-win32-i686-2.58.4.tgz",
+      "integrity": "sha512-3triFD6jyvhVcXOmGyttf+deKZcC1tURdhnmDUIBkiDPJKGT/N5xa4qAtHJlAB/h8L9jgYih9bvJnvvFVM7yug==",
       "cpu": [
+        "x86",
         "ia32"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
         "win32"
-      ]
+      ],
+      "engines": {
+        "node": ">=10"
+      }
     },
-    "node_modules/@rollup/rollup-win32-x64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.59.0.tgz",
-      "integrity": "sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==",
+    "node_modules/@sentry/cli-win32-x64": {
+      "version": "2.58.4",
+      "resolved": "https://registry.npmjs.org/@sentry/cli-win32-x64/-/cli-win32-x64-2.58.4.tgz",
+      "integrity": "sha512-cSzN4PjM1RsCZ4pxMjI0VI7yNCkxiJ5jmWncyiwHXGiXrV1eXYdQ3n1LhUYLZ91CafyprR0OhDcE+RVZ26Qb5w==",
       "cpu": [
         "x64"
       ],
-      "license": "MIT",
+      "license": "FSL-1.1-MIT",
       "optional": true,
       "os": [
         "win32"
-      ]
-    },
-    "node_modules/@rollup/rollup-win32-x64-msvc": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.59.0.tgz",
-      "integrity": "sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==",
-      "cpu": [
-        "x64"
       ],
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/@sentry/core": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry/core/-/core-10.38.0.tgz",
+      "integrity": "sha512-1pubWDZE5y5HZEPMAZERP4fVl2NH3Ihp1A+vMoVkb3Qc66Diqj1WierAnStlZP7tCx0TBa0dK85GTW/ZFYyB9g==",
       "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ]
+      "engines": {
+        "node": ">=18"
+      }
     },
-    "node_modules/@rtsao/scc": {
-      "version": "1.1.0",
-      "dev": true,
-      "license": "MIT"
+    "node_modules/@sentry/nextjs": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry/nextjs/-/nextjs-10.38.0.tgz",
+      "integrity": "sha512-MW2f6mK54jFyS/lmJxT7GWr5d12E+3qvIhR5EdjdyzMX8udSOCGyFJaFIwUfMyEMuggPEvNQVFFpjIrvWXCSGA==",
+      "license": "MIT",
+      "dependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/semantic-conventions": "^1.37.0",
+        "@rollup/plugin-commonjs": "28.0.1",
+        "@sentry-internal/browser-utils": "10.38.0",
+        "@sentry/bundler-plugin-core": "^4.8.0",
+        "@sentry/core": "10.38.0",
+        "@sentry/node": "10.38.0",
+        "@sentry/opentelemetry": "10.38.0",
+        "@sentry/react": "10.38.0",
+        "@sentry/vercel-edge": "10.38.0",
+        "@sentry/webpack-plugin": "^4.8.0",
+        "rollup": "^4.35.0",
+        "stacktrace-parser": "^0.1.10"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "next": "^13.2.0 || ^14.0 || ^15.0.0-rc.0 || ^16.0.0-0"
+      }
     },
-    "node_modules/@sentry-internal/browser-utils": {
+    "node_modules/@sentry/node": {
       "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry-internal/browser-utils/-/browser-utils-10.38.0.tgz",
-      "integrity": "sha512-UOJtYmdcxHCcV0NPfXFff/a95iXl/E0EhuQ1y0uE0BuZDMupWSF5t2BgC4HaE5Aw3RTjDF3XkSHWoIF6ohy7eA==",
+      "resolved": "https://registry.npmjs.org/@sentry/node/-/node-10.38.0.tgz",
+      "integrity": "sha512-wriyDtWDAoatn8EhOj0U4PJR1WufiijTsCGALqakOHbFiadtBJANLe6aSkXoXT4tegw59cz1wY4NlzHjYksaPw==",
+      "license": "MIT",
+      "dependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/context-async-hooks": "^2.5.0",
+        "@opentelemetry/core": "^2.5.0",
+        "@opentelemetry/instrumentation": "^0.211.0",
+        "@opentelemetry/instrumentation-amqplib": "0.58.0",
+        "@opentelemetry/instrumentation-connect": "0.54.0",
+        "@opentelemetry/instrumentation-dataloader": "0.28.0",
+        "@opentelemetry/instrumentation-express": "0.59.0",
+        "@opentelemetry/instrumentation-fs": "0.30.0",
+        "@opentelemetry/instrumentation-generic-pool": "0.54.0",
+        "@opentelemetry/instrumentation-graphql": "0.58.0",
+        "@opentelemetry/instrumentation-hapi": "0.57.0",
+        "@opentelemetry/instrumentation-http": "0.211.0",
+        "@opentelemetry/instrumentation-ioredis": "0.59.0",
+        "@opentelemetry/instrumentation-kafkajs": "0.20.0",
+        "@opentelemetry/instrumentation-knex": "0.55.0",
+        "@opentelemetry/instrumentation-koa": "0.59.0",
+        "@opentelemetry/instrumentation-lru-memoizer": "0.55.0",
+        "@opentelemetry/instrumentation-mongodb": "0.64.0",
+        "@opentelemetry/instrumentation-mongoose": "0.57.0",
+        "@opentelemetry/instrumentation-mysql": "0.57.0",
+        "@opentelemetry/instrumentation-mysql2": "0.57.0",
+        "@opentelemetry/instrumentation-pg": "0.63.0",
+        "@opentelemetry/instrumentation-redis": "0.59.0",
+        "@opentelemetry/instrumentation-tedious": "0.30.0",
+        "@opentelemetry/instrumentation-undici": "0.21.0",
+        "@opentelemetry/resources": "^2.5.0",
+        "@opentelemetry/sdk-trace-base": "^2.5.0",
+        "@opentelemetry/semantic-conventions": "^1.39.0",
+        "@prisma/instrumentation": "7.2.0",
+        "@sentry/core": "10.38.0",
+        "@sentry/node-core": "10.38.0",
+        "@sentry/opentelemetry": "10.38.0",
+        "import-in-the-middle": "^2.0.6",
+        "minimatch": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry/node-core": {
+      "version": "10.38.0",
+      "resolved": "https://registry.npmjs.org/@sentry/node-core/-/node-core-10.38.0.tgz",
+      "integrity": "sha512-ErXtpedrY1HghgwM6AliilZPcUCoNNP1NThdO4YpeMq04wMX9/GMmFCu46TnCcg6b7IFIOSr2S4yD086PxLlHQ==",
       "license": "MIT",
       "dependencies": {
-        "@sentry/core": "10.38.0"
+        "@apm-js-collab/tracing-hooks": "^0.3.1",
+        "@sentry/core": "10.38.0",
+        "@sentry/opentelemetry": "10.38.0",
+        "import-in-the-middle": "^2.0.6"
       },
       "engines": {
         "node": ">=18"
+      },
+      "peerDependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/context-async-hooks": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/core": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/instrumentation": ">=0.57.1 <1",
+        "@opentelemetry/resources": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/semantic-conventions": "^1.39.0"
       }
     },
-    "node_modules/@sentry-internal/feedback": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry-internal/feedback/-/feedback-10.38.0.tgz",
-      "integrity": "sha512-JXneg9zRftyfy1Fyfc39bBlF/Qd8g4UDublFFkVvdc1S6JQPlK+P6q22DKz3Pc8w3ySby+xlIq/eTu9Pzqi4KA==",
+    "node_modules/@sentry/node/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/@sentry/node/node_modules/brace-expansion": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.3.tgz",
+      "integrity": "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==",
       "license": "MIT",
       "dependencies": {
-        "@sentry/core": "10.38.0"
+        "balanced-match": "^4.0.2"
       },
       "engines": {
-        "node": ">=18"
+        "node": "18 || 20 || >=22"
       }
     },
-    "node_modules/@sentry-internal/replay": {
+    "node_modules/@sentry/node/node_modules/minimatch": {
+      "version": "9.0.8",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.8.tgz",
+      "integrity": "sha512-reYkDYtj/b19TeqbNZCV4q9t+Yxylf/rYBsLb42SXJatTv4/ylq5lEiAmhA/IToxO7NI2UzNMghHoHuaqDkAjw==",
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^5.0.2"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/@sentry/opentelemetry": {
       "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry-internal/replay/-/replay-10.38.0.tgz",
-      "integrity": "sha512-YWIkL6/dnaiQyFiZXJ/nN+NXGv/15z45ia86bE/TMq01CubX/DUOilgsFz0pk2v/pg3tp/U2MskLO9Hz0cnqeg==",
+      "resolved": "https://registry.npmjs.org/@sentry/opentelemetry/-/opentelemetry-10.38.0.tgz",
+      "integrity": "sha512-YPVhWfYmC7nD3EJqEHGtjp4fp5LwtAbE5rt9egQ4hqJlYFvr8YEz9sdoqSZxO0cZzgs2v97HFl/nmWAXe52G2Q==",
       "license": "MIT",
       "dependencies": {
-        "@sentry-internal/browser-utils": "10.38.0",
         "@sentry/core": "10.38.0"
       },
       "engines": {
         "node": ">=18"
+      },
+      "peerDependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/context-async-hooks": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/core": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0",
+        "@opentelemetry/semantic-conventions": "^1.39.0"
       }
     },
-    "node_modules/@sentry-internal/replay-canvas": {
+    "node_modules/@sentry/react": {
       "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry-internal/replay-canvas/-/replay-canvas-10.38.0.tgz",
-      "integrity": "sha512-OXWM9jEqNYh4VTvrMu7v+z1anz+QKQ/fZXIZdsO7JTT2lGNZe58UUMeoq386M+Saxen8F9SUH7yTORy/8KI5qw==",
+      "resolved": "https://registry.npmjs.org/@sentry/react/-/react-10.38.0.tgz",
+      "integrity": "sha512-3UiKo6QsqTyPGUt0XWRY9KLaxc/cs6Kz4vlldBSOXEL6qPDL/EfpwNJT61osRo81VFWu8pKu7ZY2bvLPryrnBQ==",
       "license": "MIT",
       "dependencies": {
-        "@sentry-internal/replay": "10.38.0",
+        "@sentry/browser": "10.38.0",
         "@sentry/core": "10.38.0"
       },
       "engines": {
         "node": ">=18"
+      },
+      "peerDependencies": {
+        "react": "^16.14.0 || 17.x || 18.x || 19.x"
       }
     },
-    "node_modules/@sentry-internal/tracing": {
+    "node_modules/@sentry/tracing": {
       "version": "7.120.4",
       "license": "MIT",
       "dependencies": {
-        "@sentry/core": "7.120.4",
-        "@sentry/types": "7.120.4",
-        "@sentry/utils": "7.120.4"
+        "@sentry-internal/tracing": "7.120.4"
       },
       "engines": {
         "node": ">=8"
       }
     },
-    "node_modules/@sentry-internal/tracing/node_modules/@sentry/core": {
+    "node_modules/@sentry/types": {
       "version": "7.120.4",
       "license": "MIT",
-      "dependencies": {
-        "@sentry/types": "7.120.4",
-        "@sentry/utils": "7.120.4"
-      },
       "engines": {
         "node": ">=8"
       }
     },
-    "node_modules/@sentry/babel-plugin-component-annotate": {
-      "version": "4.8.0",
-      "resolved": "https://registry.npmjs.org/@sentry/babel-plugin-component-annotate/-/babel-plugin-component-annotate-4.8.0.tgz",
-      "integrity": "sha512-cy/9Eipkv23MsEJ4IuB4dNlVwS9UqOzI3Eu+QPake5BVFgPYCX0uP0Tr3Z43Ime6Rb+BiDnWC51AJK9i9afHYw==",
+    "node_modules/@sentry/utils": {
+      "version": "7.120.4",
       "license": "MIT",
+      "dependencies": {
+        "@sentry/types": "7.120.4"
+      },
       "engines": {
-        "node": ">= 14"
+        "node": ">=8"
       }
     },
-    "node_modules/@sentry/browser": {
+    "node_modules/@sentry/vercel-edge": {
       "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/browser/-/browser-10.38.0.tgz",
-      "integrity": "sha512-3phzp1YX4wcQr9mocGWKbjv0jwtuoDBv7+Y6Yfrys/kwyaL84mDLjjQhRf4gL5SX7JdYkhBp4WaiNlR0UC4kTA==",
+      "resolved": "https://registry.npmjs.org/@sentry/vercel-edge/-/vercel-edge-10.38.0.tgz",
+      "integrity": "sha512-lElDFktj/PyRC/LDHejPFhQmHVMCB9Celj+IHi36aw96a/LekqF6/7vmp26hDtH58QtuiPO3h5voqEAMUOkSlw==",
       "license": "MIT",
       "dependencies": {
-        "@sentry-internal/browser-utils": "10.38.0",
-        "@sentry-internal/feedback": "10.38.0",
-        "@sentry-internal/replay": "10.38.0",
-        "@sentry-internal/replay-canvas": "10.38.0",
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/resources": "^2.5.0",
         "@sentry/core": "10.38.0"
       },
       "engines": {
         "node": ">=18"
       }
     },
-    "node_modules/@sentry/bundler-plugin-core": {
+    "node_modules/@sentry/webpack-plugin": {
       "version": "4.8.0",
-      "resolved": "https://registry.npmjs.org/@sentry/bundler-plugin-core/-/bundler-plugin-core-4.8.0.tgz",
-      "integrity": "sha512-QaXd/NzaZ2vmiA2FNu2nBkgQU+17N3fE+zVOTzG0YK54QDSJMd4n3AeJIEyPhSzkOob+GqtO22nbYf6AATFMAw==",
+      "resolved": "https://registry.npmjs.org/@sentry/webpack-plugin/-/webpack-plugin-4.8.0.tgz",
+      "integrity": "sha512-x4gayRA/J8CEcowrXWA2scaPZx+hd18squORJElHZKC46PGYRKvQfAWQ7qRCX6gtJ2v53x9264n9D8f3b9rp9g==",
       "license": "MIT",
       "dependencies": {
-        "@babel/core": "^7.18.5",
-        "@sentry/babel-plugin-component-annotate": "4.8.0",
-        "@sentry/cli": "^2.57.0",
-        "dotenv": "^16.3.1",
-        "find-up": "^5.0.0",
-        "glob": "^10.5.0",
-        "magic-string": "0.30.8",
-        "unplugin": "1.0.1"
+        "@sentry/bundler-plugin-core": "4.8.0",
+        "unplugin": "1.0.1",
+        "uuid": "^9.0.0"
       },
       "engines": {
         "node": ">= 14"
-      }
-    },
-    "node_modules/@sentry/bundler-plugin-core/node_modules/magic-string": {
-      "version": "0.30.8",
-      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.8.tgz",
-      "integrity": "sha512-ISQTe55T2ao7XtlAStud6qwYPZjE4GK1S/BeVPus4jrq6JuOnQ00YKQC581RWhR122W7msZV263KzVeLoqidyQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@jridgewell/sourcemap-codec": "^1.4.15"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
-    "node_modules/@sentry/cli": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli/-/cli-2.58.4.tgz",
-      "integrity": "sha512-ArDrpuS8JtDYEvwGleVE+FgR+qHaOp77IgdGSacz6SZy6Lv90uX0Nu4UrHCQJz8/xwIcNxSqnN22lq0dH4IqTg==",
-      "hasInstallScript": true,
-      "license": "FSL-1.1-MIT",
-      "dependencies": {
-        "https-proxy-agent": "^5.0.0",
-        "node-fetch": "^2.6.7",
-        "progress": "^2.0.3",
-        "proxy-from-env": "^1.1.0",
-        "which": "^2.0.2"
-      },
-      "bin": {
-        "sentry-cli": "bin/sentry-cli"
-      },
-      "engines": {
-        "node": ">= 10"
       },
-      "optionalDependencies": {
-        "@sentry/cli-darwin": "2.58.4",
-        "@sentry/cli-linux-arm": "2.58.4",
-        "@sentry/cli-linux-arm64": "2.58.4",
-        "@sentry/cli-linux-i686": "2.58.4",
-        "@sentry/cli-linux-x64": "2.58.4",
-        "@sentry/cli-win32-arm64": "2.58.4",
-        "@sentry/cli-win32-i686": "2.58.4",
-        "@sentry/cli-win32-x64": "2.58.4"
+      "peerDependencies": {
+        "webpack": ">=4.40.0"
       }
     },
-    "node_modules/@sentry/cli-darwin": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-darwin/-/cli-darwin-2.58.4.tgz",
-      "integrity": "sha512-kbTD+P4X8O+nsNwPxCywtj3q22ecyRHWff98rdcmtRrvwz8CKi/T4Jxn/fnn2i4VEchy08OWBuZAqaA5Kh2hRQ==",
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=10"
-      }
+    "node_modules/@sinclair/typebox": {
+      "version": "0.27.8",
+      "dev": true,
+      "license": "MIT"
     },
-    "node_modules/@sentry/cli-linux-arm": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-arm/-/cli-linux-arm-2.58.4.tgz",
-      "integrity": "sha512-rdQ8beTwnN48hv7iV7e7ZKucPec5NJkRdrrycMJMZlzGBPi56LqnclgsHySJ6Kfq506A2MNuQnKGaf/sBC9REA==",
-      "cpu": [
-        "arm"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "linux",
-        "freebsd",
-        "android"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@sinonjs/commons": {
+      "version": "3.0.1",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "type-detect": "4.0.8"
       }
     },
-    "node_modules/@sentry/cli-linux-arm64": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-arm64/-/cli-linux-arm64-2.58.4.tgz",
-      "integrity": "sha512-0g0KwsOozkLtzN8/0+oMZoOuQ0o7W6O+hx+ydVU1bktaMGKEJLMAWxOQNjsh1TcBbNIXVOKM/I8l0ROhaAb8Ig==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "linux",
-        "freebsd",
-        "android"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@sinonjs/fake-timers": {
+      "version": "10.3.0",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@sinonjs/commons": "^3.0.0"
       }
     },
-    "node_modules/@sentry/cli-linux-i686": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-i686/-/cli-linux-i686-2.58.4.tgz",
-      "integrity": "sha512-NseoIQAFtkziHyjZNPTu1Gm1opeQHt7Wm1LbLrGWVIRvUOzlslO9/8i6wETUZ6TjlQxBVRgd3Q0lRBG2A8rFYA==",
-      "cpu": [
-        "x86",
-        "ia32"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "linux",
-        "freebsd",
-        "android"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@storybook/addon-actions": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-actions/-/addon-actions-8.6.18.tgz",
+      "integrity": "sha512-GcYhtE91GjIQTuZlwpTJ8jfMp6NC79nkpe1DGe0eetTpyQqLq1WUt+ACkk0Z5lqq2u8HBc09zCCGw+D8iCLpYQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/global": "^5.0.0",
+        "@types/uuid": "^9.0.1",
+        "dequal": "^2.0.2",
+        "polished": "^4.2.2",
+        "uuid": "^9.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/cli-linux-x64": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-linux-x64/-/cli-linux-x64-2.58.4.tgz",
-      "integrity": "sha512-d3Arz+OO/wJYTqCYlSN3Ktm+W8rynQ/IMtSZLK8nu0ryh5mJOh+9XlXY6oDXw4YlsM8qCRrNquR8iEI1Y/IH+Q==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "linux",
-        "freebsd",
-        "android"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@storybook/addon-backgrounds": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-backgrounds/-/addon-backgrounds-8.6.18.tgz",
+      "integrity": "sha512-froND3WwvSCYzjEBO8QODStaWNL+aGXqxBEbrMnGYejDFST4qEFkvM2IYWMnLBkRgrgJ0yIqTeDQoyH9b9/8uQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/global": "^5.0.0",
+        "memoizerific": "^1.11.3",
+        "ts-dedent": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/cli-win32-arm64": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-win32-arm64/-/cli-win32-arm64-2.58.4.tgz",
-      "integrity": "sha512-bqYrF43+jXdDBh0f8HIJU3tbvlOFtGyRjHB8AoRuMQv9TEDUfENZyCelhdjA+KwDKYl48R1Yasb4EHNzsoO83w==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@storybook/addon-controls": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-controls/-/addon-controls-8.6.18.tgz",
+      "integrity": "sha512-K09dHDCfGW3cudsfuyfu0Yi49aZ2h7VYK4IXDGo1sfmtzVh4xd3HrZQQMVUeKLcfDP/NnJowT+fLVwg04CLrxQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/global": "^5.0.0",
+        "dequal": "^2.0.2",
+        "ts-dedent": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/cli-win32-i686": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-win32-i686/-/cli-win32-i686-2.58.4.tgz",
-      "integrity": "sha512-3triFD6jyvhVcXOmGyttf+deKZcC1tURdhnmDUIBkiDPJKGT/N5xa4qAtHJlAB/h8L9jgYih9bvJnvvFVM7yug==",
-      "cpu": [
-        "x86",
-        "ia32"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@storybook/addon-docs": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-docs/-/addon-docs-8.6.18.tgz",
+      "integrity": "sha512-55ADer0yNmmeR928Y3UAv3r4i7bJSd9LwywsQ+lRol/FNe0ZcwLEz31xL+jVsqQFNnDh/imsDIp8aYapGMtfEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@mdx-js/react": "^3.0.0",
+        "@storybook/blocks": "8.6.18",
+        "@storybook/csf-plugin": "8.6.18",
+        "@storybook/react-dom-shim": "8.6.18",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "ts-dedent": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/cli-win32-x64": {
-      "version": "2.58.4",
-      "resolved": "https://registry.npmjs.org/@sentry/cli-win32-x64/-/cli-win32-x64-2.58.4.tgz",
-      "integrity": "sha512-cSzN4PjM1RsCZ4pxMjI0VI7yNCkxiJ5jmWncyiwHXGiXrV1eXYdQ3n1LhUYLZ91CafyprR0OhDcE+RVZ26Qb5w==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "FSL-1.1-MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=10"
+    "node_modules/@storybook/addon-essentials": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-essentials/-/addon-essentials-8.6.18.tgz",
+      "integrity": "sha512-MmH7gFb8pyfRoAth0w2RW8j7mBaEJbEWGP3juIoH03ZqTGmbMUbJXElCuRgxQhve7pyz39zLsgtE78D7G+76ew==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/addon-actions": "8.6.18",
+        "@storybook/addon-backgrounds": "8.6.18",
+        "@storybook/addon-controls": "8.6.18",
+        "@storybook/addon-docs": "8.6.18",
+        "@storybook/addon-highlight": "8.6.18",
+        "@storybook/addon-measure": "8.6.18",
+        "@storybook/addon-outline": "8.6.18",
+        "@storybook/addon-toolbars": "8.6.18",
+        "@storybook/addon-viewport": "8.6.18",
+        "ts-dedent": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/core": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/core/-/core-10.38.0.tgz",
-      "integrity": "sha512-1pubWDZE5y5HZEPMAZERP4fVl2NH3Ihp1A+vMoVkb3Qc66Diqj1WierAnStlZP7tCx0TBa0dK85GTW/ZFYyB9g==",
+    "node_modules/@storybook/addon-highlight": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-highlight/-/addon-highlight-8.6.18.tgz",
+      "integrity": "sha512-wTFJ1DPM0C8gK6nGTJxH75byayQj7BPAz02fME4AOmT6clrBpVl1zSTFTkXaSr+k4xOfeMR/xNUfVskaXz6T9w==",
+      "dev": true,
       "license": "MIT",
-      "engines": {
-        "node": ">=18"
+      "dependencies": {
+        "@storybook/global": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/nextjs": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/nextjs/-/nextjs-10.38.0.tgz",
-      "integrity": "sha512-MW2f6mK54jFyS/lmJxT7GWr5d12E+3qvIhR5EdjdyzMX8udSOCGyFJaFIwUfMyEMuggPEvNQVFFpjIrvWXCSGA==",
+    "node_modules/@storybook/addon-measure": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-measure/-/addon-measure-8.6.18.tgz",
+      "integrity": "sha512-fMEOJXgPrTm6qHlWoRM+WTLE7Mr1QBIf2ei+pujBQFcWkD6Gjc2pV8zKzvh93d+EA13wD8AmwOq1DEw9J+XH+g==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/semantic-conventions": "^1.37.0",
-        "@rollup/plugin-commonjs": "28.0.1",
-        "@sentry-internal/browser-utils": "10.38.0",
-        "@sentry/bundler-plugin-core": "^4.8.0",
-        "@sentry/core": "10.38.0",
-        "@sentry/node": "10.38.0",
-        "@sentry/opentelemetry": "10.38.0",
-        "@sentry/react": "10.38.0",
-        "@sentry/vercel-edge": "10.38.0",
-        "@sentry/webpack-plugin": "^4.8.0",
-        "rollup": "^4.35.0",
-        "stacktrace-parser": "^0.1.10"
+        "@storybook/global": "^5.0.0",
+        "tiny-invariant": "^1.3.1"
       },
-      "engines": {
-        "node": ">=18"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
       "peerDependencies": {
-        "next": "^13.2.0 || ^14.0 || ^15.0.0-rc.0 || ^16.0.0-0"
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/node": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/node/-/node-10.38.0.tgz",
-      "integrity": "sha512-wriyDtWDAoatn8EhOj0U4PJR1WufiijTsCGALqakOHbFiadtBJANLe6aSkXoXT4tegw59cz1wY4NlzHjYksaPw==",
+    "node_modules/@storybook/addon-outline": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-outline/-/addon-outline-8.6.18.tgz",
+      "integrity": "sha512-TErFqfCtlV2xt9B6/kskROt69TPjr6AXdHpMselaRrN1X4WEjcMk9GT9PcNP7FXqL88/VYqUb3uNMiAmpDmS/g==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/context-async-hooks": "^2.5.0",
-        "@opentelemetry/core": "^2.5.0",
-        "@opentelemetry/instrumentation": "^0.211.0",
-        "@opentelemetry/instrumentation-amqplib": "0.58.0",
-        "@opentelemetry/instrumentation-connect": "0.54.0",
-        "@opentelemetry/instrumentation-dataloader": "0.28.0",
-        "@opentelemetry/instrumentation-express": "0.59.0",
-        "@opentelemetry/instrumentation-fs": "0.30.0",
-        "@opentelemetry/instrumentation-generic-pool": "0.54.0",
-        "@opentelemetry/instrumentation-graphql": "0.58.0",
-        "@opentelemetry/instrumentation-hapi": "0.57.0",
-        "@opentelemetry/instrumentation-http": "0.211.0",
-        "@opentelemetry/instrumentation-ioredis": "0.59.0",
-        "@opentelemetry/instrumentation-kafkajs": "0.20.0",
-        "@opentelemetry/instrumentation-knex": "0.55.0",
-        "@opentelemetry/instrumentation-koa": "0.59.0",
-        "@opentelemetry/instrumentation-lru-memoizer": "0.55.0",
-        "@opentelemetry/instrumentation-mongodb": "0.64.0",
-        "@opentelemetry/instrumentation-mongoose": "0.57.0",
-        "@opentelemetry/instrumentation-mysql": "0.57.0",
-        "@opentelemetry/instrumentation-mysql2": "0.57.0",
-        "@opentelemetry/instrumentation-pg": "0.63.0",
-        "@opentelemetry/instrumentation-redis": "0.59.0",
-        "@opentelemetry/instrumentation-tedious": "0.30.0",
-        "@opentelemetry/instrumentation-undici": "0.21.0",
-        "@opentelemetry/resources": "^2.5.0",
-        "@opentelemetry/sdk-trace-base": "^2.5.0",
-        "@opentelemetry/semantic-conventions": "^1.39.0",
-        "@prisma/instrumentation": "7.2.0",
-        "@sentry/core": "10.38.0",
-        "@sentry/node-core": "10.38.0",
-        "@sentry/opentelemetry": "10.38.0",
-        "import-in-the-middle": "^2.0.6",
-        "minimatch": "^9.0.0"
+        "@storybook/global": "^5.0.0",
+        "ts-dedent": "^2.0.0"
       },
-      "engines": {
-        "node": ">=18"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/node-core": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/node-core/-/node-core-10.38.0.tgz",
-      "integrity": "sha512-ErXtpedrY1HghgwM6AliilZPcUCoNNP1NThdO4YpeMq04wMX9/GMmFCu46TnCcg6b7IFIOSr2S4yD086PxLlHQ==",
+    "node_modules/@storybook/addon-themes": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-themes/-/addon-themes-8.6.18.tgz",
+      "integrity": "sha512-v+Xcxo/XB2ayw9E/RygGOqUIaPOXp9XEFv6EF7DRt41/RQkQ846yJBARTC2cH8kCb+7FYcvDLD3GN/ms7i8wNg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@apm-js-collab/tracing-hooks": "^0.3.1",
-        "@sentry/core": "10.38.0",
-        "@sentry/opentelemetry": "10.38.0",
-        "import-in-the-middle": "^2.0.6"
+        "ts-dedent": "^2.0.0"
       },
-      "engines": {
-        "node": ">=18"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
       "peerDependencies": {
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/context-async-hooks": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/core": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/instrumentation": ">=0.57.1 <1",
-        "@opentelemetry/resources": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/semantic-conventions": "^1.39.0"
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/node/node_modules/balanced-match": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
-      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+    "node_modules/@storybook/addon-toolbars": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-toolbars/-/addon-toolbars-8.6.18.tgz",
+      "integrity": "sha512-x037KXCEcNfPISGX485DtiP+8Bw/cOT45plcQa8eiAQVrVcUwYaDoLubE9YV5b5CsSAjX8sDviGTme6ALfq7+w==",
+      "dev": true,
       "license": "MIT",
-      "engines": {
-        "node": "18 || 20 || >=22"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/node/node_modules/brace-expansion": {
-      "version": "5.0.3",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.3.tgz",
-      "integrity": "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==",
+    "node_modules/@storybook/addon-viewport": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-viewport/-/addon-viewport-8.6.18.tgz",
+      "integrity": "sha512-z9sDJSkuWQb4BP+Z1+H+y/Q0rFbPSDcw+OBBEhMfRcJPPXavdC2pNQ0GdQNVw+tDwhAXj+U7jehKnMDKaP7TyA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "balanced-match": "^4.0.2"
+        "memoizerific": "^1.11.3"
       },
-      "engines": {
-        "node": "18 || 20 || >=22"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/node/node_modules/minimatch": {
-      "version": "9.0.8",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.8.tgz",
-      "integrity": "sha512-reYkDYtj/b19TeqbNZCV4q9t+Yxylf/rYBsLb42SXJatTv4/ylq5lEiAmhA/IToxO7NI2UzNMghHoHuaqDkAjw==",
-      "license": "ISC",
+    "node_modules/@storybook/blocks": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/blocks/-/blocks-8.6.18.tgz",
+      "integrity": "sha512-esZv4msPQ9LxgTb8YUIZhhxVMuI6BPi5bkXtk8c7w7sWuAsqsCe/RnVInn7ooUry2gjnD4hd9+8Eqj0b8oTVoA==",
+      "dev": true,
+      "license": "MIT",
       "dependencies": {
-        "brace-expansion": "^5.0.2"
+        "@storybook/icons": "^1.2.12",
+        "ts-dedent": "^2.0.0"
       },
-      "engines": {
-        "node": ">=16 || 14 >=14.17"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "storybook": "^8.6.18"
+      },
+      "peerDependenciesMeta": {
+        "react": {
+          "optional": true
+        },
+        "react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@storybook/builder-vite": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/builder-vite/-/builder-vite-8.6.18.tgz",
+      "integrity": "sha512-XLqnOv4C36jlTd4uC8xpWBxv+7GV4/05zWJ0wAcU4qflorropUTirt4UQPGkwIzi+BVAhs9pJj+m4k0IWJtpHg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/csf-plugin": "8.6.18",
+        "browser-assert": "^1.2.1",
+        "ts-dedent": "^2.0.0"
       },
       "funding": {
-        "url": "https://github.com/sponsors/isaacs"
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.6.18",
+        "vite": "^4.0.0 || ^5.0.0 || ^6.0.0"
+      }
+    },
+    "node_modules/@storybook/components": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/components/-/components-8.6.18.tgz",
+      "integrity": "sha512-55yViiZzPS/cPBuOeW4QGxGqrusjXVyxuknmbYCIwDtFyyvI/CgbjXRHdxNBaIjz+IlftxvBmmSaOqFG5+/dkA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.2.0 || ^8.3.0-0 || ^8.4.0-0 || ^8.5.0-0 || ^8.6.0-0"
       }
     },
-    "node_modules/@sentry/opentelemetry": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/opentelemetry/-/opentelemetry-10.38.0.tgz",
-      "integrity": "sha512-YPVhWfYmC7nD3EJqEHGtjp4fp5LwtAbE5rt9egQ4hqJlYFvr8YEz9sdoqSZxO0cZzgs2v97HFl/nmWAXe52G2Q==",
+    "node_modules/@storybook/core": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/core/-/core-8.6.18.tgz",
+      "integrity": "sha512-dRBP2TnX6fGdS0T2mXBHjkS/3Nlu1ra1huovZVFuM67CYMzrhM/3hX/zru1vWSC5rqY93ZaAhjMciPW4pK5mMQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@sentry/core": "10.38.0"
+        "@storybook/theming": "8.6.18",
+        "better-opn": "^3.0.2",
+        "browser-assert": "^1.2.1",
+        "esbuild": "^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0",
+        "esbuild-register": "^3.5.0",
+        "jsdoc-type-pratt-parser": "^4.0.0",
+        "process": "^0.11.10",
+        "recast": "^0.23.5",
+        "semver": "^7.6.2",
+        "util": "^0.12.5",
+        "ws": "^8.2.3"
       },
-      "engines": {
-        "node": ">=18"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
       "peerDependencies": {
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/context-async-hooks": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/core": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0",
-        "@opentelemetry/semantic-conventions": "^1.39.0"
+        "prettier": "^2 || ^3"
+      },
+      "peerDependenciesMeta": {
+        "prettier": {
+          "optional": true
+        }
       }
     },
-    "node_modules/@sentry/react": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/react/-/react-10.38.0.tgz",
-      "integrity": "sha512-3UiKo6QsqTyPGUt0XWRY9KLaxc/cs6Kz4vlldBSOXEL6qPDL/EfpwNJT61osRo81VFWu8pKu7ZY2bvLPryrnBQ==",
+    "node_modules/@storybook/csf-plugin": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/csf-plugin/-/csf-plugin-8.6.18.tgz",
+      "integrity": "sha512-x1ioz/L0CwaelCkHci3P31YtvwayN3FBftvwQOPbvRh9qeb4Cpz5IdVDmyvSxxYwXN66uAORNoqgjTi7B4/y5Q==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@sentry/browser": "10.38.0",
-        "@sentry/core": "10.38.0"
+        "unplugin": "^1.3.1"
       },
-      "engines": {
-        "node": ">=18"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
       "peerDependencies": {
-        "react": "^16.14.0 || 17.x || 18.x || 19.x"
+        "storybook": "^8.6.18"
       }
     },
-    "node_modules/@sentry/tracing": {
-      "version": "7.120.4",
+    "node_modules/@storybook/csf-plugin/node_modules/unplugin": {
+      "version": "1.16.1",
+      "resolved": "https://registry.npmjs.org/unplugin/-/unplugin-1.16.1.tgz",
+      "integrity": "sha512-4/u/j4FrCKdi17jaxuJA0jClGxB1AvU2hw/IuayPc4ay1XGaJs/rbb4v5WKwAjNifjmXK9PIFyuPiaK8azyR9w==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@sentry-internal/tracing": "7.120.4"
+        "acorn": "^8.14.0",
+        "webpack-virtual-modules": "^0.6.2"
       },
       "engines": {
-        "node": ">=8"
+        "node": ">=14.0.0"
       }
     },
-    "node_modules/@sentry/types": {
-      "version": "7.120.4",
+    "node_modules/@storybook/global": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@storybook/global/-/global-5.0.0.tgz",
+      "integrity": "sha512-FcOqPAXACP0I3oJ/ws6/rrPT9WGhu915Cg8D02a9YxLo0DE9zI+a9A5gRGvmQ09fiWPukqI8ZAEoQEdWUKMQdQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@storybook/icons": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/@storybook/icons/-/icons-1.6.0.tgz",
+      "integrity": "sha512-hcFZIjW8yQz8O8//2WTIXylm5Xsgc+lW9ISLgUk1xGmptIJQRdlhVIXCpSyLrQaaRiyhQRaVg7l3BD9S216BHw==",
+      "dev": true,
       "license": "MIT",
       "engines": {
-        "node": ">=8"
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta"
       }
     },
-    "node_modules/@sentry/utils": {
-      "version": "7.120.4",
+    "node_modules/@storybook/manager-api": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/manager-api/-/manager-api-8.6.18.tgz",
+      "integrity": "sha512-BjIp12gEMgzFkEsgKpDIbZdnSWTZpm2dlws8WiPJCpgJtG+HWSxZ0/Ms30Au9yfwzQEKRSbV/5zpsKMGc2SIJw==",
+      "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@sentry/types": "7.120.4"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
-      "engines": {
-        "node": ">=8"
+      "peerDependencies": {
+        "storybook": "^8.2.0 || ^8.3.0-0 || ^8.4.0-0 || ^8.5.0-0 || ^8.6.0-0"
       }
     },
-    "node_modules/@sentry/vercel-edge": {
-      "version": "10.38.0",
-      "resolved": "https://registry.npmjs.org/@sentry/vercel-edge/-/vercel-edge-10.38.0.tgz",
-      "integrity": "sha512-lElDFktj/PyRC/LDHejPFhQmHVMCB9Celj+IHi36aw96a/LekqF6/7vmp26hDtH58QtuiPO3h5voqEAMUOkSlw==",
+    "node_modules/@storybook/preview-api": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/preview-api/-/preview-api-8.6.18.tgz",
+      "integrity": "sha512-joXRXh3GdVvzhbfIgmix1xs90p8Q/nja7AhEAC2egn5Pl7SKsIYZUCYI6UdrQANb2myg9P552LKXfPect8llKg==",
+      "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/resources": "^2.5.0",
-        "@sentry/core": "10.38.0"
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
-      "engines": {
-        "node": ">=18"
+      "peerDependencies": {
+        "storybook": "^8.2.0 || ^8.3.0-0 || ^8.4.0-0 || ^8.5.0-0 || ^8.6.0-0"
       }
     },
-    "node_modules/@sentry/webpack-plugin": {
-      "version": "4.8.0",
-      "resolved": "https://registry.npmjs.org/@sentry/webpack-plugin/-/webpack-plugin-4.8.0.tgz",
-      "integrity": "sha512-x4gayRA/J8CEcowrXWA2scaPZx+hd18squORJElHZKC46PGYRKvQfAWQ7qRCX6gtJ2v53x9264n9D8f3b9rp9g==",
+    "node_modules/@storybook/react": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/react/-/react-8.6.18.tgz",
+      "integrity": "sha512-BuLpzMkKtF+UCQCbi+lYVX9cdcAMG86Lu2dDn7UFkPi5HRNFq/zHPSvlz1XDgL0OYMtcqB1aoVzFzcyzUBhhjw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@sentry/bundler-plugin-core": "4.8.0",
-        "unplugin": "1.0.1",
-        "uuid": "^9.0.0"
+        "@storybook/components": "8.6.18",
+        "@storybook/global": "^5.0.0",
+        "@storybook/manager-api": "8.6.18",
+        "@storybook/preview-api": "8.6.18",
+        "@storybook/react-dom-shim": "8.6.18",
+        "@storybook/theming": "8.6.18"
       },
       "engines": {
-        "node": ">= 14"
+        "node": ">=18.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
       },
       "peerDependencies": {
-        "webpack": ">=4.40.0"
+        "@storybook/test": "8.6.18",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "storybook": "^8.6.18",
+        "typescript": ">= 4.2.x"
+      },
+      "peerDependenciesMeta": {
+        "@storybook/test": {
+          "optional": true
+        },
+        "typescript": {
+          "optional": true
+        }
       }
     },
-    "node_modules/@sinclair/typebox": {
-      "version": "0.27.8",
+    "node_modules/@storybook/react-dom-shim": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/react-dom-shim/-/react-dom-shim-8.6.18.tgz",
+      "integrity": "sha512-N4xULcAWZQTUv4jy1/d346Tyb4gufuC3UaLCuU/iVSZ1brYF4OW3ANr+096btbMxY8pR/65lmtoqr5CTGwnBvA==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "storybook": "^8.6.18"
+      }
     },
-    "node_modules/@sinonjs/commons": {
-      "version": "3.0.1",
+    "node_modules/@storybook/react-vite": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/react-vite/-/react-vite-8.6.18.tgz",
+      "integrity": "sha512-qpSYyH2IizlEsI95MJTdIL6xpLSgiNCMoJpHu+IEqLnyvmecRR/YEZvcHalgdtawuXlimH0bAYuwIu3l8Vo6FQ==",
       "dev": true,
-      "license": "BSD-3-Clause",
+      "license": "MIT",
       "dependencies": {
-        "type-detect": "4.0.8"
+        "@joshwooding/vite-plugin-react-docgen-typescript": "0.5.0",
+        "@rollup/pluginutils": "^5.0.2",
+        "@storybook/builder-vite": "8.6.18",
+        "@storybook/react": "8.6.18",
+        "find-up": "^5.0.0",
+        "magic-string": "^0.30.0",
+        "react-docgen": "^7.0.0",
+        "resolve": "^1.22.8",
+        "tsconfig-paths": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "@storybook/test": "8.6.18",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta",
+        "storybook": "^8.6.18",
+        "vite": "^4.0.0 || ^5.0.0 || ^6.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@storybook/test": {
+          "optional": true
+        }
       }
     },
-    "node_modules/@sinonjs/fake-timers": {
-      "version": "10.3.0",
+    "node_modules/@storybook/react-vite/node_modules/tsconfig-paths": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/tsconfig-paths/-/tsconfig-paths-4.2.0.tgz",
+      "integrity": "sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg==",
       "dev": true,
-      "license": "BSD-3-Clause",
+      "license": "MIT",
       "dependencies": {
-        "@sinonjs/commons": "^3.0.0"
+        "json5": "^2.2.2",
+        "minimist": "^1.2.6",
+        "strip-bom": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/@storybook/theming": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/@storybook/theming/-/theming-8.6.18.tgz",
+      "integrity": "sha512-n6OEjEtHupa2PdTwWzRepr7cO8NkDd4rgF6BKLitRbujOspLxzMBEqdphs+QLcuiCIgf33SqmEA64QWnbSMhPw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^8.2.0 || ^8.3.0-0 || ^8.4.0-0 || ^8.5.0-0 || ^8.6.0-0"
       }
     },
     "node_modules/@stripe/stripe-js": {
@@ -5677,6 +6679,13 @@
         "@types/ms": "*"
       }
     },
+    "node_modules/@types/doctrine": {
+      "version": "0.0.9",
+      "resolved": "https://registry.npmjs.org/@types/doctrine/-/doctrine-0.0.9.tgz",
+      "integrity": "sha512-eOIHzCUSH7SMfonMG1LsC2f8vxBFtho6NGBznK41R84YzPuvSBzrhEps33IsQiOW9+VL6NQ9DbjQJznk/S4uRA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/eslint": {
       "version": "9.6.1",
       "license": "MIT",
@@ -5821,6 +6830,13 @@
         "@types/unist": "*"
       }
     },
+    "node_modules/@types/mdx": {
+      "version": "2.0.13",
+      "resolved": "https://registry.npmjs.org/@types/mdx/-/mdx-2.0.13.tgz",
+      "integrity": "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/ms": {
       "version": "2.1.0",
       "license": "MIT"
@@ -5894,6 +6910,13 @@
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
       "license": "MIT"
     },
+    "node_modules/@types/resolve": {
+      "version": "1.20.6",
+      "resolved": "https://registry.npmjs.org/@types/resolve/-/resolve-1.20.6.tgz",
+      "integrity": "sha512-A4STmOXPhMUtHH+S6ymgE2GiBSMqf4oTvcQZMcHzokuTLVYzXTB8ttjcgxOVaAp2lGwEdzZ0J+cRbbeevQj1UQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/stack-utils": {
       "version": "2.0.3",
       "dev": true,
@@ -7057,6 +8080,19 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/ast-types": {
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.16.1.tgz",
+      "integrity": "sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/ast-types-flow": {
       "version": "0.0.8",
       "dev": true,
@@ -7227,24 +8263,6 @@
         "npm": ">=6"
       }
     },
-    "node_modules/babel-plugin-macros/node_modules/resolve": {
-      "version": "1.22.11",
-      "license": "MIT",
-      "dependencies": {
-        "is-core-module": "^2.16.1",
-        "path-parse": "^1.0.7",
-        "supports-preserve-symlinks-flag": "^1.0.0"
-      },
-      "bin": {
-        "resolve": "bin/resolve"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
     "node_modules/babel-plugin-react-compiler": {
       "version": "1.0.0",
       "devOptional": true,
@@ -7315,6 +8333,19 @@
         "baseline-browser-mapping": "dist/cli.js"
       }
     },
+    "node_modules/better-opn": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/better-opn/-/better-opn-3.0.2.tgz",
+      "integrity": "sha512-aVNobHnJqLiUelTaHat9DZ1qM2w0C0Eym4LPI/3JxOnSokGVdsl1T1kN7TFvsEAD8G47A6VKQ0TVHqbBnYMJlQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "open": "^8.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/binary-extensions": {
       "version": "2.3.0",
       "license": "MIT",
@@ -7344,6 +8375,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/browser-assert": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/browser-assert/-/browser-assert-1.2.1.tgz",
+      "integrity": "sha512-nfulgvOR6S4gt9UKCeGJOuSGBPGiFT6oQ/2UBnvTY/5aQ1PnksW72fhZkM30DzoRRv2WpwZf1vHHEr3mtuXIWQ==",
+      "dev": true
+    },
     "node_modules/browserslist": {
       "version": "4.28.1",
       "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.1.tgz",
@@ -8178,6 +9215,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/define-lazy-prop": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz",
+      "integrity": "sha512-Ds09qNh8yw3khSjiJjiUInaGX9xlqZDY7JVryGxdxV7NPeuqQfplOpQ66yJFZut3jLa5zOwkXw1g9EI2uKh4Og==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/define-properties": {
       "version": "1.2.1",
       "dev": true,
@@ -8522,6 +9569,61 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/esbuild": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
+      "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.12",
+        "@esbuild/android-arm": "0.25.12",
+        "@esbuild/android-arm64": "0.25.12",
+        "@esbuild/android-x64": "0.25.12",
+        "@esbuild/darwin-arm64": "0.25.12",
+        "@esbuild/darwin-x64": "0.25.12",
+        "@esbuild/freebsd-arm64": "0.25.12",
+        "@esbuild/freebsd-x64": "0.25.12",
+        "@esbuild/linux-arm": "0.25.12",
+        "@esbuild/linux-arm64": "0.25.12",
+        "@esbuild/linux-ia32": "0.25.12",
+        "@esbuild/linux-loong64": "0.25.12",
+        "@esbuild/linux-mips64el": "0.25.12",
+        "@esbuild/linux-ppc64": "0.25.12",
+        "@esbuild/linux-riscv64": "0.25.12",
+        "@esbuild/linux-s390x": "0.25.12",
+        "@esbuild/linux-x64": "0.25.12",
+        "@esbuild/netbsd-arm64": "0.25.12",
+        "@esbuild/netbsd-x64": "0.25.12",
+        "@esbuild/openbsd-arm64": "0.25.12",
+        "@esbuild/openbsd-x64": "0.25.12",
+        "@esbuild/openharmony-arm64": "0.25.12",
+        "@esbuild/sunos-x64": "0.25.12",
+        "@esbuild/win32-arm64": "0.25.12",
+        "@esbuild/win32-ia32": "0.25.12",
+        "@esbuild/win32-x64": "0.25.12"
+      }
+    },
+    "node_modules/esbuild-register": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/esbuild-register/-/esbuild-register-3.6.0.tgz",
+      "integrity": "sha512-H2/S7Pm8a9CL1uhp9OvjwrBh5Pvx0H8qVOxNu8Wed9Y7qv56MPtq+GGM8RJpq6glYJn9Wspr8uw7l55uyinNeg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.3.4"
+      },
+      "peerDependencies": {
+        "esbuild": ">=0.12 <1"
+      }
+    },
     "node_modules/escalade": {
       "version": "3.2.0",
       "license": "MIT",
@@ -8642,25 +9744,6 @@
         "ms": "^2.1.1"
       }
     },
-    "node_modules/eslint-import-resolver-node/node_modules/resolve": {
-      "version": "1.22.11",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "is-core-module": "^2.16.1",
-        "path-parse": "^1.0.7",
-        "supports-preserve-symlinks-flag": "^1.0.0"
-      },
-      "bin": {
-        "resolve": "bin/resolve"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
     "node_modules/eslint-import-resolver-typescript": {
       "version": "3.10.1",
       "dev": true,
@@ -10182,6 +11265,23 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/is-arguments": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/is-arguments/-/is-arguments-1.2.0.tgz",
+      "integrity": "sha512-7bVbi0huj/wrIAOzb8U1aszg9kdi3KN/CyU19CTI7tAoZYEZoL9yCDXpbXN+uPsuWnP02cyug1gleqq+TU+YCA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "call-bound": "^1.0.2",
+        "has-tostringtag": "^1.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/is-array-buffer": {
       "version": "3.0.5",
       "dev": true,
@@ -10326,8 +11426,24 @@
       "version": "2.0.1",
       "license": "MIT",
       "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/wooorm"
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-docker": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-2.2.1.tgz",
+      "integrity": "sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
     "node_modules/is-extglob": {
@@ -10608,6 +11724,19 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/is-wsl": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-2.2.0.tgz",
+      "integrity": "sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/isarray": {
       "version": "2.0.5",
       "dev": true,
@@ -11284,25 +12413,6 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
-    "node_modules/jest-resolve/node_modules/resolve": {
-      "version": "1.22.11",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "is-core-module": "^2.16.1",
-        "path-parse": "^1.0.7",
-        "supports-preserve-symlinks-flag": "^1.0.0"
-      },
-      "bin": {
-        "resolve": "bin/resolve"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
     "node_modules/jest-runner": {
       "version": "29.7.0",
       "dev": true,
@@ -11543,6 +12653,16 @@
         "js-yaml": "bin/js-yaml.js"
       }
     },
+    "node_modules/jsdoc-type-pratt-parser": {
+      "version": "4.8.0",
+      "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.8.0.tgz",
+      "integrity": "sha512-iZ8Bdb84lWRuGHamRXFyML07r21pcwBrLkHEuHgEY5UbCouBwv7ECknDRKzsQIXMiqpPymqtIf8TC/shYKB5rw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/jsdom": {
       "version": "26.1.0",
       "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-26.1.0.tgz",
@@ -11902,6 +13022,13 @@
         "tmpl": "1.0.5"
       }
     },
+    "node_modules/map-or-similar": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/map-or-similar/-/map-or-similar-1.5.0.tgz",
+      "integrity": "sha512-0aF7ZmVon1igznGI4VS30yugpduQW3y3GkcgGJOp7d8x8QrizhigUxjI/m2UojsXXto+jLAH3KSz+xOJTiORjg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/markdown-table": {
       "version": "3.0.4",
       "license": "MIT",
@@ -12190,6 +13317,16 @@
       "version": "6.0.0",
       "license": "MIT"
     },
+    "node_modules/memoizerific": {
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/memoizerific/-/memoizerific-1.11.3.tgz",
+      "integrity": "sha512-/EuHYwAPdLtXwAwSZkh/Gutery6pD2KYd44oQLhAvQp/50mpyduZh8Q7PYHXTCJ+wuXxt7oij2LXyIJOOYFPog==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "map-or-similar": "^1.5.0"
+      }
+    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "license": "MIT"
@@ -13604,6 +14741,24 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/open": {
+      "version": "8.4.2",
+      "resolved": "https://registry.npmjs.org/open/-/open-8.4.2.tgz",
+      "integrity": "sha512-7x81NCL719oNbsq/3mh+hVrAWmFuEYUqrq/Iw3kUzH8ReypT9QQ0BLoJS7/G9k6N81XjW4qHWtjWwe/9eLy1EQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "define-lazy-prop": "^2.0.0",
+        "is-docker": "^2.1.1",
+        "is-wsl": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/optionator": {
       "version": "0.9.4",
       "dev": true,
@@ -13934,6 +15089,19 @@
         "node": ">=18"
       }
     },
+    "node_modules/polished": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/polished/-/polished-4.3.1.tgz",
+      "integrity": "sha512-OBatVyC/N7SCW/FaDHrSd+vn0o5cS855TOmYi4OkdWUMSJCET/xip//ch8xGUvtr3i44X9LVyWwQlRMTN3pwSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.17.8"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/possible-typed-array-names": {
       "version": "1.1.0",
       "dev": true,
@@ -13983,24 +15151,6 @@
         "postcss": "^8.0.0"
       }
     },
-    "node_modules/postcss-import/node_modules/resolve": {
-      "version": "1.22.11",
-      "license": "MIT",
-      "dependencies": {
-        "is-core-module": "^2.16.1",
-        "path-parse": "^1.0.7",
-        "supports-preserve-symlinks-flag": "^1.0.0"
-      },
-      "bin": {
-        "resolve": "bin/resolve"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
     "node_modules/postcss-js": {
       "version": "4.1.0",
       "funding": [
@@ -14230,6 +15380,16 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/process": {
+      "version": "0.11.10",
+      "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz",
+      "integrity": "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6.0"
+      }
+    },
     "node_modules/process-nextick-args": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
@@ -14413,6 +15573,64 @@
         "url": "https://github.com/sponsors/kossnocorp"
       }
     },
+    "node_modules/react-docgen": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/react-docgen/-/react-docgen-7.1.1.tgz",
+      "integrity": "sha512-hlSJDQ2synMPKFZOsKo9Hi8WWZTC7POR8EmWvTSjow+VDgKzkmjQvFm2fk0tmRw+f0vTOIYKlarR0iL4996pdg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.18.9",
+        "@babel/traverse": "^7.18.9",
+        "@babel/types": "^7.18.9",
+        "@types/babel__core": "^7.18.0",
+        "@types/babel__traverse": "^7.18.0",
+        "@types/doctrine": "^0.0.9",
+        "@types/resolve": "^1.20.2",
+        "doctrine": "^3.0.0",
+        "resolve": "^1.22.1",
+        "strip-indent": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=16.14.0"
+      }
+    },
+    "node_modules/react-docgen-typescript": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/react-docgen-typescript/-/react-docgen-typescript-2.4.0.tgz",
+      "integrity": "sha512-ZtAp5XTO5HRzQctjPU0ybY0RRCQO19X/8fxn3w7y2VVTUbGHDKULPTL4ky3vB05euSgG5NpALhEhDPvQ56wvXg==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "typescript": ">= 4.3.x"
+      }
+    },
+    "node_modules/react-docgen/node_modules/doctrine": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz",
+      "integrity": "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "esutils": "^2.0.2"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/react-docgen/node_modules/strip-indent": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-4.1.1.tgz",
+      "integrity": "sha512-SlyRoSkdh1dYP0PzclLE7r0M9sgbFKKMFXpFRUMNuKhQSbC6VQIGzq3E0qsfvGJaUFJPGv6Ws1NZ/haTAjfbMA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/react-dom": {
       "version": "19.2.4",
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
@@ -14658,6 +15876,23 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/recast": {
+      "version": "0.23.11",
+      "resolved": "https://registry.npmjs.org/recast/-/recast-0.23.11.tgz",
+      "integrity": "sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ast-types": "^0.16.1",
+        "esprima": "~4.0.0",
+        "source-map": "~0.6.1",
+        "tiny-invariant": "^1.3.3",
+        "tslib": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 4"
+      }
+    },
     "node_modules/recharts": {
       "version": "2.15.4",
       "license": "MIT",
@@ -14896,6 +16131,26 @@
         "node": ">=9.3.0 || >=8.10.0 <9.0.0"
       }
     },
+    "node_modules/resolve": {
+      "version": "1.22.11",
+      "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.11.tgz",
+      "integrity": "sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "is-core-module": "^2.16.1",
+        "path-parse": "^1.0.7",
+        "supports-preserve-symlinks-flag": "^1.0.0"
+      },
+      "bin": {
+        "resolve": "bin/resolve"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/resolve-cwd": {
       "version": "3.0.0",
       "dev": true,
@@ -15422,6 +16677,33 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/storybook": {
+      "version": "8.6.18",
+      "resolved": "https://registry.npmjs.org/storybook/-/storybook-8.6.18.tgz",
+      "integrity": "sha512-p8seiSI6FiVY6P3V0pG+5v7c8pDMehMAFRWEhG5XqIBSQszzOjDnW2rNvm3odoLKfo3V3P6Cs6Hv9ILzymULyQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/core": "8.6.18"
+      },
+      "bin": {
+        "getstorybook": "bin/index.cjs",
+        "sb": "bin/index.cjs",
+        "storybook": "bin/index.cjs"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "prettier": "^2 || ^3"
+      },
+      "peerDependenciesMeta": {
+        "prettier": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/string_decoder": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
@@ -15891,24 +17173,6 @@
         "node": ">=4"
       }
     },
-    "node_modules/tailwindcss/node_modules/resolve": {
-      "version": "1.22.11",
-      "license": "MIT",
-      "dependencies": {
-        "is-core-module": "^2.16.1",
-        "path-parse": "^1.0.7",
-        "supports-preserve-symlinks-flag": "^1.0.0"
-      },
-      "bin": {
-        "resolve": "bin/resolve"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
     "node_modules/tapable": {
       "version": "2.3.0",
       "license": "MIT",
@@ -16185,6 +17449,16 @@
         "typescript": ">=4.8.4"
       }
     },
+    "node_modules/ts-dedent": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz",
+      "integrity": "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.10"
+      }
+    },
     "node_modules/ts-interface-checker": {
       "version": "0.1.13",
       "license": "Apache-2.0"
@@ -16704,6 +17978,20 @@
         "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/util": {
+      "version": "0.12.5",
+      "resolved": "https://registry.npmjs.org/util/-/util-0.12.5.tgz",
+      "integrity": "sha512-kZf/K6hEIrWHI6XqOFUiiMa+79wE/D8Q+NCNAWclkyg3b4d2k7s0QGepNjiABc+aR3N1PAyHL7p6UcLY6LmrnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "inherits": "^2.0.3",
+        "is-arguments": "^1.0.4",
+        "is-generator-function": "^1.0.7",
+        "is-typed-array": "^1.1.3",
+        "which-typed-array": "^1.1.2"
+      }
+    },
     "node_modules/util-deprecate": {
       "version": "1.0.2",
       "license": "MIT"
@@ -16799,6 +18087,98 @@
         "d3-timer": "^3.0.1"
       }
     },
+    "node_modules/vite": {
+      "version": "6.4.1",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.1.tgz",
+      "integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "esbuild": "^0.25.0",
+        "fdir": "^6.4.4",
+        "picomatch": "^4.0.2",
+        "postcss": "^8.5.3",
+        "rollup": "^4.34.9",
+        "tinyglobby": "^0.2.13"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+        "jiti": ">=1.21.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vite/node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "peer": true,
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/w3c-xmlserializer": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
@@ -16912,6 +18292,13 @@
         "node": ">=10.13.0"
       }
     },
+    "node_modules/webpack-virtual-modules": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/webpack-virtual-modules/-/webpack-virtual-modules-0.6.2.tgz",
+      "integrity": "sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/webpack/node_modules/es-module-lexer": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.0.0.tgz",
diff --git a/web/package.json b/web/package.json
index b564937a234..3ade8c50d5b 100644
--- a/web/package.json
+++ b/web/package.json
@@ -24,7 +24,9 @@
     "test:ci": "jest --ci --maxWorkers=2 --silent --bail",
     "test:changed": "jest --onlyChanged",
     "test:diff": "jest --changedSince=main",
-    "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand"
+    "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand",
+    "storybook": "storybook dev -p 6006",
+    "storybook:build": "storybook build -o storybook-static"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.1.0",
@@ -110,6 +112,11 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.39.0",
+    "@storybook/addon-essentials": "^8.6.18",
+    "@storybook/addon-themes": "^8.6.18",
+    "@storybook/blocks": "^8.6.18",
+    "@storybook/react": "^8.6.18",
+    "@storybook/react-vite": "^8.6.18",
     "@tailwindcss/typography": "^0.5.19",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
@@ -135,6 +142,7 @@
     "jest-environment-jsdom": "^30.2.0",
     "prettier": "3.1.0",
     "stats.js": "^0.17.0",
+    "storybook": "^8.6.18",
     "tailwindcss": "^3.4.17",
     "ts-jest": "^29.2.5",
     "ts-unused-exports": "^11.0.1",

From bbd68e279547c8ca7b14a02908d5c77b19887a70 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Mon, 9 Mar 2026 16:48:44 -0700
Subject: [PATCH 194/267] fix: impropoer kv store strings (#9213)

---
 backend/onyx/connectors/google_utils/google_kv.py |  7 +++++--
 backend/onyx/key_value_store/interface.py         | 14 ++++++++++++++
 backend/onyx/utils/telemetry.py                   | 13 ++++++++-----
 3 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/backend/onyx/connectors/google_utils/google_kv.py b/backend/onyx/connectors/google_utils/google_kv.py
index 17d9d0c1e35..6974aea271c 100644
--- a/backend/onyx/connectors/google_utils/google_kv.py
+++ b/backend/onyx/connectors/google_utils/google_kv.py
@@ -44,6 +44,7 @@
 from onyx.db.credentials import update_credential_json
 from onyx.db.models import User
 from onyx.key_value_store.factory import get_kv_store
+from onyx.key_value_store.interface import unwrap_str
 from onyx.server.documents.models import CredentialBase
 from onyx.server.documents.models import GoogleAppCredentials
 from onyx.server.documents.models import GoogleServiceAccountKey
@@ -89,7 +90,7 @@ def _get_current_oauth_user(creds: OAuthCredentials, source: DocumentSource) ->
 
 
 def verify_csrf(credential_id: int, state: str) -> None:
-    csrf = get_kv_store().load(KV_CRED_KEY.format(str(credential_id)))
+    csrf = unwrap_str(get_kv_store().load(KV_CRED_KEY.format(str(credential_id))))
     if csrf != state:
         raise PermissionError(
             "State from Google Drive Connector callback does not match expected"
@@ -178,7 +179,9 @@ def get_auth_url(credential_id: int, source: DocumentSource) -> str:
     params = parse_qs(parsed_url.query)
 
     get_kv_store().store(
-        KV_CRED_KEY.format(credential_id), params.get("state", [None])[0], encrypt=True
+        KV_CRED_KEY.format(credential_id),
+        {"value": params.get("state", [None])[0]},
+        encrypt=True,
     )
     return str(auth_url)
 
diff --git a/backend/onyx/key_value_store/interface.py b/backend/onyx/key_value_store/interface.py
index 9d6348076c0..7766513a85d 100644
--- a/backend/onyx/key_value_store/interface.py
+++ b/backend/onyx/key_value_store/interface.py
@@ -1,4 +1,5 @@
 import abc
+from typing import cast
 
 from onyx.utils.special_types import JSON_ro
 
@@ -7,6 +8,19 @@ class KvKeyNotFoundError(Exception):
     pass
 
 
+def unwrap_str(val: JSON_ro) -> str:
+    """Unwrap a string stored as {"value": str} in the encrypted KV store.
+    Also handles legacy plain-string values cached in Redis."""
+    if isinstance(val, dict):
+        try:
+            return cast(str, val["value"])
+        except KeyError:
+            raise ValueError(
+                f"Expected dict with 'value' key, got keys: {list(val.keys())}"
+            )
+    return cast(str, val)
+
+
 class KeyValueStore:
     # In the Multi Tenant case, the tenant context is picked up automatically, it does not need to be passed in
     # It's read from the global thread level variable
diff --git a/backend/onyx/utils/telemetry.py b/backend/onyx/utils/telemetry.py
index 3bb5d2ec876..d437095065e 100644
--- a/backend/onyx/utils/telemetry.py
+++ b/backend/onyx/utils/telemetry.py
@@ -2,7 +2,6 @@
 import threading
 import uuid
 from enum import Enum
-from typing import cast
 
 import requests
 
@@ -15,6 +14,7 @@
 from onyx.db.models import User
 from onyx.key_value_store.factory import get_kv_store
 from onyx.key_value_store.interface import KvKeyNotFoundError
+from onyx.key_value_store.interface import unwrap_str
 from onyx.utils.logger import setup_logger
 from onyx.utils.variable_functionality import (
     fetch_versioned_implementation_with_fallback,
@@ -25,6 +25,7 @@
 
 logger = setup_logger()
 
+
 _DANSWER_TELEMETRY_ENDPOINT = "https://telemetry.onyx.app/anonymous_telemetry"
 _CACHED_UUID: str | None = None
 _CACHED_INSTANCE_DOMAIN: str | None = None
@@ -62,10 +63,10 @@ def get_or_generate_uuid() -> str:
     kv_store = get_kv_store()
 
     try:
-        _CACHED_UUID = cast(str, kv_store.load(KV_CUSTOMER_UUID_KEY))
+        _CACHED_UUID = unwrap_str(kv_store.load(KV_CUSTOMER_UUID_KEY))
     except KvKeyNotFoundError:
         _CACHED_UUID = str(uuid.uuid4())
-        kv_store.store(KV_CUSTOMER_UUID_KEY, _CACHED_UUID, encrypt=True)
+        kv_store.store(KV_CUSTOMER_UUID_KEY, {"value": _CACHED_UUID}, encrypt=True)
 
     return _CACHED_UUID
 
@@ -79,14 +80,16 @@ def _get_or_generate_instance_domain() -> str | None:  #
     kv_store = get_kv_store()
 
     try:
-        _CACHED_INSTANCE_DOMAIN = cast(str, kv_store.load(KV_INSTANCE_DOMAIN_KEY))
+        _CACHED_INSTANCE_DOMAIN = unwrap_str(kv_store.load(KV_INSTANCE_DOMAIN_KEY))
     except KvKeyNotFoundError:
         with get_session_with_current_tenant() as db_session:
             first_user = db_session.query(User).first()
             if first_user:
                 _CACHED_INSTANCE_DOMAIN = first_user.email.split("@")[-1]
                 kv_store.store(
-                    KV_INSTANCE_DOMAIN_KEY, _CACHED_INSTANCE_DOMAIN, encrypt=True
+                    KV_INSTANCE_DOMAIN_KEY,
+                    {"value": _CACHED_INSTANCE_DOMAIN},
+                    encrypt=True,
                 )
 
     return _CACHED_INSTANCE_DOMAIN

From 2ec752677227b0e004809d2c11c0d3a68331539d Mon Sep 17 00:00:00 2001
From: Bo-Onyx <bo@onyx.app>
Date: Mon, 9 Mar 2026 17:02:31 -0700
Subject: [PATCH 195/267] fix(api memory): replace glibc with jemalloc for
 memory allocating (#9196)

---
 backend/Dockerfile | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/backend/Dockerfile b/backend/Dockerfile
index b6d284ffbc1..af48b7b761c 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -46,7 +46,9 @@ RUN apt-get update && \
         pkg-config \
         gcc \
         nano \
-        vim && \
+        vim \
+        libjemalloc2 \
+        && \
     rm -rf /var/lib/apt/lists/* && \
     apt-get clean
 
@@ -165,6 +167,13 @@ ENV PYTHONPATH=/app
 ARG ONYX_VERSION=0.0.0-dev
 ENV ONYX_VERSION=${ONYX_VERSION}
 
+# Use jemalloc instead of glibc malloc to reduce memory fragmentation
+# in long-running Python processes (API server, Celery workers).
+# The soname is architecture-independent; the dynamic linker resolves
+# the correct path from standard library directories.
+# Placed after all RUN steps so build-time processes are unaffected.
+ENV LD_PRELOAD=libjemalloc.so.2
+
 # Default command which does nothing
 # This container is used by api server and background which specify their own CMD
 CMD ["tail", "-f", "/dev/null"]

From 87f0849330bb5d67a66ae3ca9bab9890d5228d47 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Mon, 9 Mar 2026 17:30:32 -0700
Subject: [PATCH 196/267] feat(opensearch): Enable by default (#9211)

---
 .github/workflows/pr-integration-tests.yml    |  4 ++
 backend/onyx/configs/app_configs.py           |  3 +-
 .../docker-compose.multitenant-dev.yml        | 52 +++++++++++++++++++
 .../docker-compose.prod-cloud.yml             | 52 +++++++++++++++++++
 .../docker-compose.prod-no-letsencrypt.yml    | 52 +++++++++++++++++++
 .../docker_compose/docker-compose.prod.yml    | 52 +++++++++++++++++++
 deployment/docker_compose/docker-compose.yml  | 36 +++++++++----
 deployment/docker_compose/env.template        |  6 +--
 deployment/helm/charts/onyx/Chart.yaml        |  2 +-
 deployment/helm/charts/onyx/values.yaml       | 11 ++--
 10 files changed, 251 insertions(+), 19 deletions(-)

diff --git a/.github/workflows/pr-integration-tests.yml b/.github/workflows/pr-integration-tests.yml
index 18357102459..e9b8006c2c7 100644
--- a/.github/workflows/pr-integration-tests.yml
+++ b/.github/workflows/pr-integration-tests.yml
@@ -316,6 +316,7 @@ jobs:
           # Base config shared by both editions
           cat <<EOF > deployment/docker_compose/.env
           COMPOSE_PROFILES=s3-filestore
+          OPENSEARCH_FOR_ONYX_ENABLED=false
           AUTH_TYPE=basic
           POSTGRES_POOL_PRE_PING=true
           POSTGRES_USE_NULL_POOL=true
@@ -418,6 +419,7 @@ jobs:
               -e POSTGRES_POOL_PRE_PING=true \
               -e POSTGRES_USE_NULL_POOL=true \
               -e VESPA_HOST=index \
+              -e ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=false \
               -e REDIS_HOST=cache \
               -e API_SERVER_HOST=api_server \
               -e OPENAI_API_KEY=${OPENAI_API_KEY} \
@@ -637,6 +639,7 @@ jobs:
           ONYX_BACKEND_IMAGE=${ECR_CACHE}:integration-test-backend-test-${RUN_ID} \
           ONYX_MODEL_SERVER_IMAGE=${ECR_CACHE}:integration-test-model-server-test-${RUN_ID} \
           DEV_MODE=true \
+          OPENSEARCH_FOR_ONYX_ENABLED=false \
           docker compose -f docker-compose.multitenant-dev.yml up \
             relational_db \
             index \
@@ -691,6 +694,7 @@ jobs:
             -e POSTGRES_DB=postgres \
             -e POSTGRES_USE_NULL_POOL=true \
             -e VESPA_HOST=index \
+            -e ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=false \
             -e REDIS_HOST=cache \
             -e API_SERVER_HOST=api_server \
             -e OPENAI_API_KEY=${OPENAI_API_KEY} \
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 2883dead666..554f51ef79c 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -292,8 +292,9 @@
 # environments we always want to be dual indexing into both OpenSearch and Vespa
 # to stress test the new codepaths. Only enable this if there is some instance
 # of OpenSearch running for the relevant Onyx instance.
+# NOTE: Now enabled on by default, unless the env indicates otherwise.
 ENABLE_OPENSEARCH_INDEXING_FOR_ONYX = (
-    os.environ.get("ENABLE_OPENSEARCH_INDEXING_FOR_ONYX", "").lower() == "true"
+    os.environ.get("ENABLE_OPENSEARCH_INDEXING_FOR_ONYX", "true").lower() == "true"
 )
 # NOTE: This effectively does nothing anymore, admins can now toggle whether
 # retrieval is through OpenSearch. This value is only used as a final fallback
diff --git a/deployment/docker_compose/docker-compose.multitenant-dev.yml b/deployment/docker_compose/docker-compose.multitenant-dev.yml
index c1366bc7e91..9753df2e975 100644
--- a/deployment/docker_compose/docker-compose.multitenant-dev.yml
+++ b/deployment/docker_compose/docker-compose.multitenant-dev.yml
@@ -61,6 +61,9 @@ services:
       - POSTGRES_HOST=relational_db
       - POSTGRES_DEFAULT_SCHEMA=${POSTGRES_DEFAULT_SCHEMA:-}
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - WEB_DOMAIN=${WEB_DOMAIN:-}
       # MinIO configuration
@@ -168,6 +171,9 @@ services:
       - POSTGRES_DB=${POSTGRES_DB:-}
       - POSTGRES_DEFAULT_SCHEMA=${POSTGRES_DEFAULT_SCHEMA:-}
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - WEB_DOMAIN=${WEB_DOMAIN:-}
       # MinIO configuration
@@ -424,6 +430,50 @@ services:
         max-size: "50m"
         max-file: "6"
 
+  opensearch:
+    image: opensearchproject/opensearch:3.4.0
+    restart: unless-stopped
+    # Controls whether this service runs. In order to enable it, add
+    # opensearch-enabled to COMPOSE_PROFILES in the environment for this
+    # docker-compose.
+    # NOTE: Now enabled on by default. To explicitly disable this service,
+    # uncomment this profile and ensure COMPOSE_PROFILES in your env does not
+    # list the profile, or when running docker compose, include all desired
+    # service names but this one. Additionally set
+    # OPENSEARCH_FOR_ONYX_ENABLED=false in your env.
+    # profiles: ["opensearch-enabled"]
+    environment:
+      # We need discovery.type=single-node so that OpenSearch doesn't try
+      # forming a cluster and waiting for other nodes to become live.
+      - discovery.type=single-node
+      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      # This and the JVM config below come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+      # We do this to avoid unstable performance from page swaps.
+      - bootstrap.memory_lock=true # Disable JVM heap memory swapping.
+      # Java heap should be ~50% of memory limit. For now we assume a limit of
+      # 4g although in practice the container can request more than this.
+      # See https://opster.com/guides/opensearch/opensearch-basics/opensearch-heap-size-usage-and-jvm-garbage-collection/
+      # Xms is the starting size, Xmx is the maximum size. These should be the
+      # same.
+      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
+    volumes:
+      - opensearch-data:/usr/share/opensearch/data
+    # These come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+    ulimits:
+      # Similarly to bootstrap.memory_lock, we don't want to impose limits on
+      # how much memory a process can lock from being swapped.
+      memlock:
+        soft: -1 # Set memlock to unlimited (no soft or hard limit).
+        hard: -1
+      nofile:
+        soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536.
+        hard: 65536
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "6"
+
   nginx:
     image: nginx:1.25.5-alpine
     restart: unless-stopped
@@ -508,3 +558,5 @@ volumes:
   model_cache_huggingface:
   indexing_huggingface_model_cache:
   # mcp_server_logs:
+  # Persistent data for OpenSearch.
+  opensearch-data:
diff --git a/deployment/docker_compose/docker-compose.prod-cloud.yml b/deployment/docker_compose/docker-compose.prod-cloud.yml
index 3153440fcf3..d86bcc453c6 100644
--- a/deployment/docker_compose/docker-compose.prod-cloud.yml
+++ b/deployment/docker_compose/docker-compose.prod-cloud.yml
@@ -21,6 +21,9 @@ services:
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       # MinIO configuration
@@ -55,6 +58,9 @@ services:
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - INDEXING_MODEL_SERVER_HOST=${INDEXING_MODEL_SERVER_HOST:-indexing_model_server}
@@ -228,6 +234,50 @@ services:
         max-size: "50m"
         max-file: "6"
 
+  opensearch:
+    image: opensearchproject/opensearch:3.4.0
+    restart: unless-stopped
+    # Controls whether this service runs. In order to enable it, add
+    # opensearch-enabled to COMPOSE_PROFILES in the environment for this
+    # docker-compose.
+    # NOTE: Now enabled on by default. To explicitly disable this service,
+    # uncomment this profile and ensure COMPOSE_PROFILES in your env does not
+    # list the profile, or when running docker compose, include all desired
+    # service names but this one. Additionally set
+    # OPENSEARCH_FOR_ONYX_ENABLED=false in your env.
+    # profiles: ["opensearch-enabled"]
+    environment:
+      # We need discovery.type=single-node so that OpenSearch doesn't try
+      # forming a cluster and waiting for other nodes to become live.
+      - discovery.type=single-node
+      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      # This and the JVM config below come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+      # We do this to avoid unstable performance from page swaps.
+      - bootstrap.memory_lock=true # Disable JVM heap memory swapping.
+      # Java heap should be ~50% of memory limit. For now we assume a limit of
+      # 4g although in practice the container can request more than this.
+      # See https://opster.com/guides/opensearch/opensearch-basics/opensearch-heap-size-usage-and-jvm-garbage-collection/
+      # Xms is the starting size, Xmx is the maximum size. These should be the
+      # same.
+      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
+    volumes:
+      - opensearch-data:/usr/share/opensearch/data
+    # These come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+    ulimits:
+      # Similarly to bootstrap.memory_lock, we don't want to impose limits on
+      # how much memory a process can lock from being swapped.
+      memlock:
+        soft: -1 # Set memlock to unlimited (no soft or hard limit).
+        hard: -1
+      nofile:
+        soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536.
+        hard: 65536
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "6"
+
   nginx:
     image: nginx:1.25.5-alpine
     restart: unless-stopped
@@ -315,3 +365,5 @@ volumes:
   model_cache_huggingface:
   indexing_huggingface_model_cache:
   # mcp_server_logs:
+  # Persistent data for OpenSearch.
+  opensearch-data:
diff --git a/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml b/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
index e1a2cfa4ef5..772b725c3be 100644
--- a/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
+++ b/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
@@ -21,6 +21,9 @@ services:
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - USE_IAM_AUTH=${USE_IAM_AUTH}
@@ -68,6 +71,9 @@ services:
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - INDEXING_MODEL_SERVER_HOST=${INDEXING_MODEL_SERVER_HOST:-indexing_model_server}
@@ -251,6 +257,50 @@ services:
         max-size: "50m"
         max-file: "6"
 
+  opensearch:
+    image: opensearchproject/opensearch:3.4.0
+    restart: unless-stopped
+    # Controls whether this service runs. In order to enable it, add
+    # opensearch-enabled to COMPOSE_PROFILES in the environment for this
+    # docker-compose.
+    # NOTE: Now enabled on by default. To explicitly disable this service,
+    # uncomment this profile and ensure COMPOSE_PROFILES in your env does not
+    # list the profile, or when running docker compose, include all desired
+    # service names but this one. Additionally set
+    # OPENSEARCH_FOR_ONYX_ENABLED=false in your env.
+    # profiles: ["opensearch-enabled"]
+    environment:
+      # We need discovery.type=single-node so that OpenSearch doesn't try
+      # forming a cluster and waiting for other nodes to become live.
+      - discovery.type=single-node
+      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      # This and the JVM config below come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+      # We do this to avoid unstable performance from page swaps.
+      - bootstrap.memory_lock=true # Disable JVM heap memory swapping.
+      # Java heap should be ~50% of memory limit. For now we assume a limit of
+      # 4g although in practice the container can request more than this.
+      # See https://opster.com/guides/opensearch/opensearch-basics/opensearch-heap-size-usage-and-jvm-garbage-collection/
+      # Xms is the starting size, Xmx is the maximum size. These should be the
+      # same.
+      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
+    volumes:
+      - opensearch-data:/usr/share/opensearch/data
+    # These come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+    ulimits:
+      # Similarly to bootstrap.memory_lock, we don't want to impose limits on
+      # how much memory a process can lock from being swapped.
+      memlock:
+        soft: -1 # Set memlock to unlimited (no soft or hard limit).
+        hard: -1
+      nofile:
+        soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536.
+        hard: 65536
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "6"
+
   nginx:
     image: nginx:1.25.5-alpine
     restart: unless-stopped
@@ -343,3 +393,5 @@ volumes:
   # mcp_server_logs:
   # Shared volume for persistent document storage (Craft file-system mode)
   file-system:
+  # Persistent data for OpenSearch.
+  opensearch-data:
diff --git a/deployment/docker_compose/docker-compose.prod.yml b/deployment/docker_compose/docker-compose.prod.yml
index fbb4bcc5c43..cc7d75c66cf 100644
--- a/deployment/docker_compose/docker-compose.prod.yml
+++ b/deployment/docker_compose/docker-compose.prod.yml
@@ -22,6 +22,9 @@ services:
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - USE_IAM_AUTH=${USE_IAM_AUTH}
@@ -73,6 +76,9 @@ services:
       - AUTH_TYPE=${AUTH_TYPE:-oidc}
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
+      - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - INDEXING_MODEL_SERVER_HOST=${INDEXING_MODEL_SERVER_HOST:-indexing_model_server}
@@ -270,6 +276,50 @@ services:
         max-size: "50m"
         max-file: "6"
 
+  opensearch:
+    image: opensearchproject/opensearch:3.4.0
+    restart: unless-stopped
+    # Controls whether this service runs. In order to enable it, add
+    # opensearch-enabled to COMPOSE_PROFILES in the environment for this
+    # docker-compose.
+    # NOTE: Now enabled on by default. To explicitly disable this service,
+    # uncomment this profile and ensure COMPOSE_PROFILES in your env does not
+    # list the profile, or when running docker compose, include all desired
+    # service names but this one. Additionally set
+    # OPENSEARCH_FOR_ONYX_ENABLED=false in your env.
+    # profiles: ["opensearch-enabled"]
+    environment:
+      # We need discovery.type=single-node so that OpenSearch doesn't try
+      # forming a cluster and waiting for other nodes to become live.
+      - discovery.type=single-node
+      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
+      # This and the JVM config below come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+      # We do this to avoid unstable performance from page swaps.
+      - bootstrap.memory_lock=true # Disable JVM heap memory swapping.
+      # Java heap should be ~50% of memory limit. For now we assume a limit of
+      # 4g although in practice the container can request more than this.
+      # See https://opster.com/guides/opensearch/opensearch-basics/opensearch-heap-size-usage-and-jvm-garbage-collection/
+      # Xms is the starting size, Xmx is the maximum size. These should be the
+      # same.
+      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
+    volumes:
+      - opensearch-data:/usr/share/opensearch/data
+    # These come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
+    ulimits:
+      # Similarly to bootstrap.memory_lock, we don't want to impose limits on
+      # how much memory a process can lock from being swapped.
+      memlock:
+        soft: -1 # Set memlock to unlimited (no soft or hard limit).
+        hard: -1
+      nofile:
+        soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536.
+        hard: 65536
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "6"
+
   nginx:
     image: nginx:1.25.5-alpine
     restart: unless-stopped
@@ -380,3 +430,5 @@ volumes:
   # mcp_server_logs:
   # Shared volume for persistent document storage (Craft file-system mode)
   file-system:
+  # Persistent data for OpenSearch.
+  opensearch-data:
diff --git a/deployment/docker_compose/docker-compose.yml b/deployment/docker_compose/docker-compose.yml
index d82cd1cb3cd..32154352993 100644
--- a/deployment/docker_compose/docker-compose.yml
+++ b/deployment/docker_compose/docker-compose.yml
@@ -57,6 +57,9 @@ services:
         condition: service_started
       index:
         condition: service_started
+      opensearch:
+        condition: service_started
+        required: false
       cache:
         condition: service_started
       inference_model_server:
@@ -78,7 +81,7 @@ services:
       - VESPA_HOST=${VESPA_HOST:-index}
       - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
       - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
-      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-false}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=${REDIS_HOST:-cache}
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - S3_ENDPOINT_URL=${S3_ENDPOINT_URL:-http://minio:9000}
@@ -139,11 +142,19 @@ services:
       - path: .env
         required: false
     depends_on:
-      - relational_db
-      - index
-      - cache
-      - inference_model_server
-      - indexing_model_server
+      relational_db:
+        condition: service_started
+      index:
+        condition: service_started
+      opensearch:
+        condition: service_started
+        required: false
+      cache:
+        condition: service_started
+      inference_model_server:
+        condition: service_started
+      indexing_model_server:
+        condition: service_started
     restart: unless-stopped
     environment:
       - FILE_STORE_BACKEND=${FILE_STORE_BACKEND:-s3}
@@ -151,7 +162,7 @@ services:
       - VESPA_HOST=${VESPA_HOST:-index}
       - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
       - OPENSEARCH_ADMIN_PASSWORD=${OPENSEARCH_ADMIN_PASSWORD:-StrongPassword123!}
-      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-false}
+      - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=${REDIS_HOST:-cache}
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - INDEXING_MODEL_SERVER_HOST=${INDEXING_MODEL_SERVER_HOST:-indexing_model_server}
@@ -406,7 +417,12 @@ services:
     # Controls whether this service runs. In order to enable it, add
     # opensearch-enabled to COMPOSE_PROFILES in the environment for this
     # docker-compose.
-    profiles: ["opensearch-enabled"]
+    # NOTE: Now enabled on by default. To explicitly disable this service,
+    # uncomment this profile and ensure COMPOSE_PROFILES in your env does not
+    # list the profile, or when running docker compose, include all desired
+    # service names but this one. Additionally set
+    # OPENSEARCH_FOR_ONYX_ENABLED=false in your env.
+    # profiles: ["opensearch-enabled"]
     environment:
       # We need discovery.type=single-node so that OpenSearch doesn't try
       # forming a cluster and waiting for other nodes to become live.
@@ -416,11 +432,11 @@ services:
       # We do this to avoid unstable performance from page swaps.
       - bootstrap.memory_lock=true # Disable JVM heap memory swapping.
       # Java heap should be ~50% of memory limit. For now we assume a limit of
-      # 2g although in practice the container can request more than this.
+      # 4g although in practice the container can request more than this.
       # See https://opster.com/guides/opensearch/opensearch-basics/opensearch-heap-size-usage-and-jvm-garbage-collection/
       # Xms is the starting size, Xmx is the maximum size. These should be the
       # same.
-      - "OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g"
+      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
     volumes:
       - opensearch-data:/usr/share/opensearch/data
     # These come from the example in https://docs.opensearch.org/latest/install-and-configure/install-opensearch/docker/
diff --git a/deployment/docker_compose/env.template b/deployment/docker_compose/env.template
index 4d464a8f58c..7b66925ba3d 100644
--- a/deployment/docker_compose/env.template
+++ b/deployment/docker_compose/env.template
@@ -67,10 +67,8 @@ POSTGRES_PASSWORD=password
 ## remove s3-filestore from COMPOSE_PROFILES and set FILE_STORE_BACKEND=postgres.
 COMPOSE_PROFILES=s3-filestore
 FILE_STORE_BACKEND=s3
-## Settings for enabling OpenSearch. Uncomment these and comment out
-## COMPOSE_PROFILES above.
-# COMPOSE_PROFILES=s3-filestore,opensearch-enabled
-# OPENSEARCH_FOR_ONYX_ENABLED=true
+## Setting for enabling OpenSearch.
+OPENSEARCH_FOR_ONYX_ENABLED=true
 
 ## MinIO/S3 Configuration (only needed when FILE_STORE_BACKEND=s3)
 S3_ENDPOINT_URL=http://minio:9000
diff --git a/deployment/helm/charts/onyx/Chart.yaml b/deployment/helm/charts/onyx/Chart.yaml
index 8e3459577a6..23851be6b29 100644
--- a/deployment/helm/charts/onyx/Chart.yaml
+++ b/deployment/helm/charts/onyx/Chart.yaml
@@ -5,7 +5,7 @@ home: https://www.onyx.app/
 sources:
   - "https://github.com/onyx-dot-app/onyx"
 type: application
-version: 0.4.32
+version: 0.4.33
 appVersion: latest
 annotations:
   category: Productivity
diff --git a/deployment/helm/charts/onyx/values.yaml b/deployment/helm/charts/onyx/values.yaml
index 29480549787..d70f93dbcad 100644
--- a/deployment/helm/charts/onyx/values.yaml
+++ b/deployment/helm/charts/onyx/values.yaml
@@ -76,7 +76,10 @@ vespa:
       memory: 32000Mi
 
 opensearch:
-  enabled: false
+  # Enabled by default. Override to false and set the appropriate env vars in
+  # the instance-specific values yaml if using AWS-managed OpenSearch, or simply
+  # override to false to entirely disable.
+  enabled: true
   # These values are passed to the opensearch subchart.
   # See https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/values.yaml
 
@@ -1158,8 +1161,10 @@ auth:
   opensearch:
     # Enable or disable this secret entirely. Will remove from env var
     # configurations and remove any created secrets.
-    # Set to true when opensearch.enabled is true.
-    enabled: false
+    # Enabled by default. Override to false and set the appropriate env vars in
+    # the instance-specific values yaml if using AWS-managed OpenSearch, or
+    # simply override to false to entirely disable.
+    enabled: true
     # Overwrite the default secret name, ignored if existingSecret is defined.
     secretName: 'onyx-opensearch'
     # Use a secret specified elsewhere.

From d2b37724d194fc43ac27d740bd6152df0f2faa36 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 9 Mar 2026 17:48:53 -0700
Subject: [PATCH 197/267] fix(fe): fix chat content padding (#9216)

---
 web/src/sections/chat/ChatScrollContainer.tsx | 2 +-
 web/src/sections/chat/ChatUI.tsx              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/src/sections/chat/ChatScrollContainer.tsx b/web/src/sections/chat/ChatScrollContainer.tsx
index 2548f116848..0c8a947fb4c 100644
--- a/web/src/sections/chat/ChatScrollContainer.tsx
+++ b/web/src/sections/chat/ChatScrollContainer.tsx
@@ -366,7 +366,7 @@ const ChatScrollContainer = React.memo(
           >
             <div
               ref={contentWrapperRef}
-              className="w-full flex-1 flex flex-col items-center"
+              className="w-full flex-1 flex flex-col items-center px-4"
               data-scroll-ready={isScrollReady}
               style={{
                 visibility: isScrollReady ? "visible" : "hidden",
diff --git a/web/src/sections/chat/ChatUI.tsx b/web/src/sections/chat/ChatUI.tsx
index 40d004062eb..fd206cba8d2 100644
--- a/web/src/sections/chat/ChatUI.tsx
+++ b/web/src/sections/chat/ChatUI.tsx
@@ -115,7 +115,7 @@ const ChatUI = React.memo(
 
     return (
       <>
-        <div className="flex flex-col w-full max-w-[var(--app-page-main-content-width)] h-full p-4 pb-8 pr-5 gap-12">
+        <div className="flex flex-col w-full max-w-[var(--app-page-main-content-width)] h-full pt-4 pb-8 pr-1 gap-12">
           {messages.map((message, i) => {
             const messageReactComponentKey = `message-${message.nodeId}`;
             const parentMessage = message.parentNodeId

From 91e24ae63a6152caed67b63e4553618d249eba22 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 9 Mar 2026 17:50:10 -0700
Subject: [PATCH 198/267] =?UTF-8?q?fix(code-interpreter):=20set=20default?=
 =?UTF-8?q?=20CODE=5FINTERPRETER=5FBASE=5FURL=20w/=20docke=E2=80=A6=20(#92?=
 =?UTF-8?q?15)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 deployment/docker_compose/docker-compose.multitenant-dev.yml     | 1 +
 deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml | 1 +
 deployment/docker_compose/docker-compose.prod.yml                | 1 +
 deployment/docker_compose/docker-compose.yml                     | 1 +
 4 files changed, 4 insertions(+)

diff --git a/deployment/docker_compose/docker-compose.multitenant-dev.yml b/deployment/docker_compose/docker-compose.multitenant-dev.yml
index 9753df2e975..1f69d96ec71 100644
--- a/deployment/docker_compose/docker-compose.multitenant-dev.yml
+++ b/deployment/docker_compose/docker-compose.multitenant-dev.yml
@@ -80,6 +80,7 @@ services:
       - DISABLE_RERANK_FOR_STREAMING=${DISABLE_RERANK_FOR_STREAMING:-}
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
       - MODEL_SERVER_PORT=${MODEL_SERVER_PORT:-}
+      - CODE_INTERPRETER_BASE_URL=${CODE_INTERPRETER_BASE_URL:-http://code-interpreter:8000}
       - LOG_ONYX_MODEL_INTERACTIONS=${LOG_ONYX_MODEL_INTERACTIONS:-}
       - LOG_VESPA_TIMING_INFORMATION=${LOG_VESPA_TIMING_INFORMATION:-}
       - LOG_ENDPOINT_LATENCY=${LOG_ENDPOINT_LATENCY:-}
diff --git a/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml b/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
index 772b725c3be..6167b2f53bc 100644
--- a/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
+++ b/deployment/docker_compose/docker-compose.prod-no-letsencrypt.yml
@@ -26,6 +26,7 @@ services:
       - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
+      - CODE_INTERPRETER_BASE_URL=${CODE_INTERPRETER_BASE_URL:-http://code-interpreter:8000}
       - USE_IAM_AUTH=${USE_IAM_AUTH}
       - AWS_REGION_NAME=${AWS_REGION_NAME-}
       - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID-}
diff --git a/deployment/docker_compose/docker-compose.prod.yml b/deployment/docker_compose/docker-compose.prod.yml
index cc7d75c66cf..7f576975e25 100644
--- a/deployment/docker_compose/docker-compose.prod.yml
+++ b/deployment/docker_compose/docker-compose.prod.yml
@@ -27,6 +27,7 @@ services:
       - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=cache
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
+      - CODE_INTERPRETER_BASE_URL=${CODE_INTERPRETER_BASE_URL:-http://code-interpreter:8000}
       - USE_IAM_AUTH=${USE_IAM_AUTH}
       - AWS_REGION_NAME=${AWS_REGION_NAME-}
       - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID-}
diff --git a/deployment/docker_compose/docker-compose.yml b/deployment/docker_compose/docker-compose.yml
index 32154352993..a734438d3d6 100644
--- a/deployment/docker_compose/docker-compose.yml
+++ b/deployment/docker_compose/docker-compose.yml
@@ -84,6 +84,7 @@ services:
       - ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=${OPENSEARCH_FOR_ONYX_ENABLED:-true}
       - REDIS_HOST=${REDIS_HOST:-cache}
       - MODEL_SERVER_HOST=${MODEL_SERVER_HOST:-inference_model_server}
+      - CODE_INTERPRETER_BASE_URL=${CODE_INTERPRETER_BASE_URL:-http://code-interpreter:8000}
       - S3_ENDPOINT_URL=${S3_ENDPOINT_URL:-http://minio:9000}
       - S3_AWS_ACCESS_KEY_ID=${S3_AWS_ACCESS_KEY_ID:-minioadmin}
       - S3_AWS_SECRET_ACCESS_KEY=${S3_AWS_SECRET_ACCESS_KEY:-minioadmin}

From 89593b353f9729b517894edafee9bacdf0e68457 Mon Sep 17 00:00:00 2001
From: Jessica Singh <86633231+jessicasingh7@users.noreply.github.com>
Date: Mon, 9 Mar 2026 18:05:29 -0700
Subject: [PATCH 199/267] chore(auth): backend cleanup (#8558)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
---
 backend/ee/onyx/auth/users.py                 |  9 +++-
 backend/ee/onyx/db/hierarchy.py               |  4 +-
 backend/onyx/auth/users.py                    | 17 +++++-
 backend/onyx/configs/app_configs.py           | 17 ++----
 backend/onyx/db/hierarchy.py                  |  4 +-
 backend/onyx/server/documents/connector.py    |  4 +-
 .../server/features/build/api/messages_api.py |  3 --
 backend/onyx/server/features/hierarchy/api.py | 10 ++--
 backend/onyx/server/features/mcp/api.py       |  2 +-
 .../hierarchy/test_hierarchy_access_filter.py |  4 +-
 .../onyx/auth/test_verify_auth_setting.py     | 54 +++++++++++++++++++
 .../hierarchy/test_user_access_info.py        | 43 +++++++++++++++
 web/src/app/auth/login/LoginPage.tsx          | 17 ------
 web/src/app/auth/login/page.tsx               | 10 +---
 14 files changed, 138 insertions(+), 60 deletions(-)
 create mode 100644 backend/tests/unit/onyx/auth/test_verify_auth_setting.py
 create mode 100644 backend/tests/unit/onyx/server/features/hierarchy/test_user_access_info.py

diff --git a/backend/ee/onyx/auth/users.py b/backend/ee/onyx/auth/users.py
index 7588ed8716e..0b2cda57991 100644
--- a/backend/ee/onyx/auth/users.py
+++ b/backend/ee/onyx/auth/users.py
@@ -1,3 +1,4 @@
+import os
 from datetime import datetime
 
 import jwt
@@ -20,7 +21,13 @@
 
 
 def verify_auth_setting() -> None:
-    # All the Auth flows are valid for EE version
+    # All the Auth flows are valid for EE version, but warn about deprecated 'disabled'
+    raw_auth_type = (os.environ.get("AUTH_TYPE") or "").lower()
+    if raw_auth_type == "disabled":
+        logger.warning(
+            "AUTH_TYPE='disabled' is no longer supported. "
+            "Using 'basic' instead. Please update your configuration."
+        )
     logger.notice(f"Using Auth Type: {AUTH_TYPE.value}")
 
 
diff --git a/backend/ee/onyx/db/hierarchy.py b/backend/ee/onyx/db/hierarchy.py
index 232f19581b0..f18745cd9d3 100644
--- a/backend/ee/onyx/db/hierarchy.py
+++ b/backend/ee/onyx/db/hierarchy.py
@@ -18,7 +18,7 @@
 
 
 def _build_hierarchy_access_filter(
-    user_email: str | None,
+    user_email: str,
     external_group_ids: list[str],
 ) -> ColumnElement[bool]:
     """Build SQLAlchemy filter for hierarchy node access.
@@ -43,7 +43,7 @@ def _build_hierarchy_access_filter(
 def _get_accessible_hierarchy_nodes_for_source(
     db_session: Session,
     source: DocumentSource,
-    user_email: str | None,
+    user_email: str,
     external_group_ids: list[str],
 ) -> list[HierarchyNode]:
     """
diff --git a/backend/onyx/auth/users.py b/backend/onyx/auth/users.py
index bcb3f891d2c..6f9c8d5b036 100644
--- a/backend/onyx/auth/users.py
+++ b/backend/onyx/auth/users.py
@@ -1,4 +1,5 @@
 import json
+import os
 import random
 import secrets
 import string
@@ -145,10 +146,22 @@ def is_user_admin(user: User) -> bool:
 
 
 def verify_auth_setting() -> None:
-    if AUTH_TYPE == AuthType.CLOUD:
+    """Log warnings for AUTH_TYPE issues.
+
+    This only runs on app startup not during migrations/scripts.
+    """
+    raw_auth_type = (os.environ.get("AUTH_TYPE") or "").lower()
+
+    if raw_auth_type == "cloud":
         raise ValueError(
-            f"{AUTH_TYPE.value} is not a valid auth type for self-hosted deployments."
+            "'cloud' is not a valid auth type for self-hosted deployments."
         )
+    if raw_auth_type == "disabled":
+        logger.warning(
+            "AUTH_TYPE='disabled' is no longer supported. "
+            "Using 'basic' instead. Please update your configuration."
+        )
+
     logger.notice(f"Using Auth Type: {AUTH_TYPE.value}")
 
 
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 554f51ef79c..bf29587a636 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -96,19 +96,12 @@
 #####
 # Auth Configs
 #####
-# Upgrades users from disabled auth to basic auth and shows warning.
-_auth_type_str = (os.environ.get("AUTH_TYPE") or "basic").lower()
-if _auth_type_str == "disabled":
-    logger.warning(
-        "AUTH_TYPE='disabled' is no longer supported. "
-        "Defaulting to 'basic'. Please update your configuration. "
-        "Your existing data will be migrated automatically."
-    )
-    _auth_type_str = AuthType.BASIC.value
-try:
+# Silently default to basic - warnings/errors logged in verify_auth_setting()
+# which only runs on app startup, not during migrations/scripts
+_auth_type_str = (os.environ.get("AUTH_TYPE") or "").lower()
+if _auth_type_str in [auth_type.value for auth_type in AuthType]:
     AUTH_TYPE = AuthType(_auth_type_str)
-except ValueError:
-    logger.error(f"Invalid AUTH_TYPE: {_auth_type_str}. Defaulting to 'basic'.")
+else:
     AUTH_TYPE = AuthType.BASIC
 
 PASSWORD_MIN_LENGTH = int(os.getenv("PASSWORD_MIN_LENGTH", 8))
diff --git a/backend/onyx/db/hierarchy.py b/backend/onyx/db/hierarchy.py
index bf2bf996477..7c403bc37d9 100644
--- a/backend/onyx/db/hierarchy.py
+++ b/backend/onyx/db/hierarchy.py
@@ -458,7 +458,7 @@ def get_all_hierarchy_nodes_for_source(
 def _get_accessible_hierarchy_nodes_for_source(
     db_session: Session,
     source: DocumentSource,
-    user_email: str | None,  # noqa: ARG001
+    user_email: str,  # noqa: ARG001
     external_group_ids: list[str],  # noqa: ARG001
 ) -> list[HierarchyNode]:
     """
@@ -485,7 +485,7 @@ def _get_accessible_hierarchy_nodes_for_source(
 def get_accessible_hierarchy_nodes_for_source(
     db_session: Session,
     source: DocumentSource,
-    user_email: str | None,
+    user_email: str,
     external_group_ids: list[str],
 ) -> list[HierarchyNode]:
     """
diff --git a/backend/onyx/server/documents/connector.py b/backend/onyx/server/documents/connector.py
index 41d6f68fb82..fc321285bbb 100644
--- a/backend/onyx/server/documents/connector.py
+++ b/backend/onyx/server/documents/connector.py
@@ -1905,7 +1905,7 @@ def get_connector_by_id(
 @router.post("/connector-request")
 def submit_connector_request(
     request_data: ConnectorRequestSubmission,
-    user: User | None = Depends(current_user),
+    user: User = Depends(current_user),
 ) -> StatusResponse:
     """
     Submit a connector request for Cloud deployments.
@@ -1918,7 +1918,7 @@ def submit_connector_request(
         raise HTTPException(status_code=400, detail="Connector name cannot be empty")
 
     # Get user identifier for telemetry
-    user_email = user.email if user else None
+    user_email = user.email
     distinct_id = user_email or tenant_id
 
     # Track connector request via PostHog telemetry (Cloud only)
diff --git a/backend/onyx/server/features/build/api/messages_api.py b/backend/onyx/server/features/build/api/messages_api.py
index 50164d109ca..ac4b194bd17 100644
--- a/backend/onyx/server/features/build/api/messages_api.py
+++ b/backend/onyx/server/features/build/api/messages_api.py
@@ -57,9 +57,6 @@ def list_messages(
     db_session: Session = Depends(get_session),
 ) -> MessageListResponse:
     """Get all messages for a build session."""
-    if user is None:
-        raise HTTPException(status_code=401, detail="Authentication required")
-
     session_manager = SessionManager(db_session)
 
     messages = session_manager.list_messages(session_id, user.id)
diff --git a/backend/onyx/server/features/hierarchy/api.py b/backend/onyx/server/features/hierarchy/api.py
index 4163810e732..12382b0070b 100644
--- a/backend/onyx/server/features/hierarchy/api.py
+++ b/backend/onyx/server/features/hierarchy/api.py
@@ -54,18 +54,14 @@ def _require_opensearch(db_session: Session) -> None:
         )
 
 
-def _get_user_access_info(
-    user: User | None, db_session: Session
-) -> tuple[str | None, list[str]]:
-    if not user:
-        return None, []
+def _get_user_access_info(user: User, db_session: Session) -> tuple[str, list[str]]:
     return user.email, get_user_external_group_ids(db_session, user)
 
 
 @router.get(HIERARCHY_NODES_LIST_PATH)
 def list_accessible_hierarchy_nodes(
     source: DocumentSource,
-    user: User | None = Depends(current_user),
+    user: User = Depends(current_user),
     db_session: Session = Depends(get_session),
 ) -> HierarchyNodesResponse:
     _require_opensearch(db_session)
@@ -92,7 +88,7 @@ def list_accessible_hierarchy_nodes(
 @router.post(HIERARCHY_NODE_DOCUMENTS_PATH)
 def list_accessible_hierarchy_node_documents(
     documents_request: HierarchyNodeDocumentsRequest,
-    user: User | None = Depends(current_user),
+    user: User = Depends(current_user),
     db_session: Session = Depends(get_session),
 ) -> HierarchyNodeDocumentsResponse:
     _require_opensearch(db_session)
diff --git a/backend/onyx/server/features/mcp/api.py b/backend/onyx/server/features/mcp/api.py
index cc92cfb1dde..7c6db29d05f 100644
--- a/backend/onyx/server/features/mcp/api.py
+++ b/backend/onyx/server/features/mcp/api.py
@@ -1013,7 +1013,7 @@ def get_mcp_servers_for_assistant(
 @router.get("/servers", response_model=MCPServersResponse)
 def get_mcp_servers_for_user(
     db: Session = Depends(get_session),
-    user: User | None = Depends(current_user),
+    user: User = Depends(current_user),
 ) -> MCPServersResponse:
     """List all MCP servers for use in agent configuration and chat UI.
 
diff --git a/backend/tests/external_dependency_unit/hierarchy/test_hierarchy_access_filter.py b/backend/tests/external_dependency_unit/hierarchy/test_hierarchy_access_filter.py
index d256fca689b..364cec642a5 100644
--- a/backend/tests/external_dependency_unit/hierarchy/test_hierarchy_access_filter.py
+++ b/backend/tests/external_dependency_unit/hierarchy/test_hierarchy_access_filter.py
@@ -85,7 +85,7 @@ def test_group_overlap_filter(
     results = _get_accessible_hierarchy_nodes_for_source(
         db_session,
         source=DocumentSource.GOOGLE_DRIVE,
-        user_email=None,
+        user_email="",
         external_group_ids=["group_engineering"],
     )
     result_ids = {n.raw_node_id for n in results}
@@ -124,7 +124,7 @@ def test_no_credentials_returns_only_public(
     results = _get_accessible_hierarchy_nodes_for_source(
         db_session,
         source=DocumentSource.GOOGLE_DRIVE,
-        user_email=None,
+        user_email="",
         external_group_ids=[],
     )
     result_ids = {n.raw_node_id for n in results}
diff --git a/backend/tests/unit/onyx/auth/test_verify_auth_setting.py b/backend/tests/unit/onyx/auth/test_verify_auth_setting.py
new file mode 100644
index 00000000000..a5eaead6da5
--- /dev/null
+++ b/backend/tests/unit/onyx/auth/test_verify_auth_setting.py
@@ -0,0 +1,54 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+import onyx.auth.users as users
+from onyx.auth.users import verify_auth_setting
+from onyx.configs.constants import AuthType
+
+
+def test_verify_auth_setting_raises_for_cloud(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Cloud auth type is not valid for self-hosted deployments."""
+    monkeypatch.setenv("AUTH_TYPE", "cloud")
+
+    with pytest.raises(ValueError, match="'cloud' is not a valid auth type"):
+        verify_auth_setting()
+
+
+def test_verify_auth_setting_warns_for_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Disabled auth type logs a deprecation warning."""
+    monkeypatch.setenv("AUTH_TYPE", "disabled")
+
+    mock_logger = MagicMock()
+    monkeypatch.setattr(users, "logger", mock_logger)
+    monkeypatch.setattr(users, "AUTH_TYPE", AuthType.BASIC)
+
+    verify_auth_setting()
+
+    mock_logger.warning.assert_called_once()
+    assert "no longer supported" in mock_logger.warning.call_args[0][0]
+
+
+@pytest.mark.parametrize(
+    "auth_type",
+    [AuthType.BASIC, AuthType.GOOGLE_OAUTH, AuthType.OIDC, AuthType.SAML],
+)
+def test_verify_auth_setting_valid_auth_types(
+    monkeypatch: pytest.MonkeyPatch,
+    auth_type: AuthType,
+) -> None:
+    """Valid auth types work without errors or warnings."""
+    monkeypatch.setenv("AUTH_TYPE", auth_type.value)
+
+    mock_logger = MagicMock()
+    monkeypatch.setattr(users, "logger", mock_logger)
+    monkeypatch.setattr(users, "AUTH_TYPE", auth_type)
+
+    verify_auth_setting()
+
+    mock_logger.warning.assert_not_called()
+    mock_logger.notice.assert_called_once_with(f"Using Auth Type: {auth_type.value}")
diff --git a/backend/tests/unit/onyx/server/features/hierarchy/test_user_access_info.py b/backend/tests/unit/onyx/server/features/hierarchy/test_user_access_info.py
new file mode 100644
index 00000000000..6c1055cacd6
--- /dev/null
+++ b/backend/tests/unit/onyx/server/features/hierarchy/test_user_access_info.py
@@ -0,0 +1,43 @@
+"""Unit tests for _get_user_access_info helper function.
+
+These tests mock all database operations and don't require a real database.
+"""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+from sqlalchemy.orm import Session
+
+from onyx.server.features.hierarchy.api import _get_user_access_info
+
+
+def test_get_user_access_info_returns_email_and_groups() -> None:
+    """_get_user_access_info returns the user's email and external group IDs."""
+    mock_user = MagicMock()
+    mock_user.email = "test@example.com"
+    mock_db_session = MagicMock(spec=Session)
+
+    with patch(
+        "onyx.server.features.hierarchy.api.get_user_external_group_ids",
+        return_value=["group1", "group2"],
+    ):
+        email, groups = _get_user_access_info(mock_user, mock_db_session)
+
+    assert email == "test@example.com"
+    assert groups == ["group1", "group2"]
+
+
+def test_get_user_access_info_with_no_groups() -> None:
+    """User with no external groups returns empty list."""
+    mock_user = MagicMock()
+    mock_user.email = "solo@example.com"
+    mock_db_session = MagicMock(spec=Session)
+
+    with patch(
+        "onyx.server.features.hierarchy.api.get_user_external_group_ids",
+        return_value=[],
+    ):
+        email, groups = _get_user_access_info(mock_user, mock_db_session)
+
+    assert email == "solo@example.com"
+    assert groups == []
diff --git a/web/src/app/auth/login/LoginPage.tsx b/web/src/app/auth/login/LoginPage.tsx
index 6a54ff43ac8..3783b47fe75 100644
--- a/web/src/app/auth/login/LoginPage.tsx
+++ b/web/src/app/auth/login/LoginPage.tsx
@@ -85,23 +85,6 @@ export default function LoginPage({
       {authTypeMetadata?.authType === AuthType.BASIC && (
         <div className="flex flex-col w-full gap-6">
           <LoginText />
-
-          {authTypeMetadata?.oauthEnabled && authUrl && (
-            <>
-              <SignInButton
-                authorizeUrl={authUrl}
-                authType={AuthType.GOOGLE_OAUTH}
-              />
-              <div className="flex flex-row items-center w-full gap-2">
-                <div className="flex-1 border-t border-text-01" />
-                <Text as="p" text03 mainUiMuted>
-                  or
-                </Text>
-                <div className="flex-1 border-t border-text-01" />
-              </div>
-            </>
-          )}
-
           <EmailPasswordForm nextUrl={effectiveNextUrl} />
         </div>
       )}
diff --git a/web/src/app/auth/login/page.tsx b/web/src/app/auth/login/page.tsx
index 7b0c9d489dc..a89e67755e2 100644
--- a/web/src/app/auth/login/page.tsx
+++ b/web/src/app/auth/login/page.tsx
@@ -72,15 +72,7 @@ export default async function Page(props: PageProps) {
   let authUrl: string | null = null;
   if (authTypeMetadata) {
     try {
-      // For BASIC auth with OAuth enabled, fetch the OAuth URL
-      if (
-        authTypeMetadata.authType === AuthType.BASIC &&
-        authTypeMetadata.oauthEnabled
-      ) {
-        authUrl = await getAuthUrlSS(AuthType.GOOGLE_OAUTH, nextUrl);
-      } else {
-        authUrl = await getAuthUrlSS(authTypeMetadata.authType, nextUrl);
-      }
+      authUrl = await getAuthUrlSS(authTypeMetadata.authType, nextUrl);
     } catch (e) {
       console.log(`Some fetch failed for the login page - ${e}`);
     }

From f71fab580c5dd598af712f699ae045044981b2d7 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 9 Mar 2026 19:03:54 -0700
Subject: [PATCH 200/267] fix: use `detail` instead of `message` in OnyxError
 response shape (#9214)

---
 AGENTS.md                                      |  2 +-
 backend/onyx/error_handling/error_codes.py     |  6 +++---
 backend/onyx/error_handling/exceptions.py      | 18 +++++++++---------
 .../llm/test_llm_provider.py                   |  6 +++---
 .../llm/test_llm_provider_api_base.py          |  8 ++++----
 .../tests/llm_provider/test_llm_provider.py    |  6 +++---
 .../test_llm_provider_persona_access.py        |  4 ++--
 .../ee/onyx/server/billing/test_billing_api.py | 10 +++++-----
 .../server/billing/test_billing_service.py     |  4 ++--
 .../ee/onyx/server/tenants/test_billing_api.py |  8 ++++----
 .../onyx/error_handling/test_exceptions.py     | 10 +++++-----
 web/src/app/admin/configuration/llm/utils.ts   |  8 ++++----
 .../[connector]/AddConnectorPage.tsx           |  4 ++--
 web/src/app/ee/admin/standard-answer/page.tsx  |  8 ++++----
 web/src/components/modals/NewTeamModal.tsx     |  4 +++-
 web/src/sections/modals/NewTenantModal.tsx     | 12 ++++++++++--
 .../sections/modals/llmConfig/CustomModal.tsx  |  4 ++--
 .../llmConfig/components/FormActionButtons.tsx |  2 +-
 18 files changed, 67 insertions(+), 57 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 633e9615a3b..54b939eb08b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -598,7 +598,7 @@ Before writing your plan, make sure to do research. Explore the relevant section
 Never hardcode status codes or use `starlette.status` / `fastapi.status` constants directly.**
 
 A global FastAPI exception handler converts `OnyxError` into a JSON response with the standard
-`{"error_code": "...", "message": "..."}` shape. This eliminates boilerplate and keeps error
+`{"error_code": "...", "detail": "..."}` shape. This eliminates boilerplate and keeps error
 handling consistent across the entire backend.
 
 ```python
diff --git a/backend/onyx/error_handling/error_codes.py b/backend/onyx/error_handling/error_codes.py
index 035797722e2..42a4c5d60a8 100644
--- a/backend/onyx/error_handling/error_codes.py
+++ b/backend/onyx/error_handling/error_codes.py
@@ -91,11 +91,11 @@ def detail(self, message: str | None = None) -> dict[str, str]:
         """Build a structured error detail dict.
 
         Returns a dict like:
-            {"error_code": "UNAUTHENTICATED", "message": "Token expired"}
+            {"error_code": "UNAUTHENTICATED", "detail": "Token expired"}
 
-        If no message is supplied, the error code itself is used as the message.
+        If no message is supplied, the error code itself is used as the detail.
         """
         return {
             "error_code": self.code,
-            "message": message or self.code,
+            "detail": message or self.code,
         }
diff --git a/backend/onyx/error_handling/exceptions.py b/backend/onyx/error_handling/exceptions.py
index 61c895791d7..7ba448ecc70 100644
--- a/backend/onyx/error_handling/exceptions.py
+++ b/backend/onyx/error_handling/exceptions.py
@@ -3,7 +3,7 @@
 Raise ``OnyxError`` instead of ``HTTPException`` in business code.  A global
 FastAPI exception handler (registered via ``register_onyx_exception_handlers``)
 converts it into a JSON response with the standard
-``{"error_code": "...", "message": "..."}`` shape.
+``{"error_code": "...", "detail": "..."}`` shape.
 
 Usage::
 
@@ -37,21 +37,21 @@ class OnyxError(Exception):
 
     Attributes:
         error_code: The ``OnyxErrorCode`` enum member.
-        message: Human-readable message (defaults to the error code string).
+        detail: Human-readable detail (defaults to the error code string).
         status_code: HTTP status — either overridden or from the error code.
     """
 
     def __init__(
         self,
         error_code: OnyxErrorCode,
-        message: str | None = None,
+        detail: str | None = None,
         *,
         status_code_override: int | None = None,
     ) -> None:
-        resolved_message = message or error_code.code
-        super().__init__(resolved_message)
+        resolved_detail = detail or error_code.code
+        super().__init__(resolved_detail)
         self.error_code = error_code
-        self.message = resolved_message
+        self.detail = resolved_detail
         self._status_code_override = status_code_override
 
     @property
@@ -73,11 +73,11 @@ async def _handle_onyx_error(
     ) -> JSONResponse:
         status_code = exc.status_code
         if status_code >= 500:
-            logger.error(f"OnyxError {exc.error_code.code}: {exc.message}")
+            logger.error(f"OnyxError {exc.error_code.code}: {exc.detail}")
         elif status_code >= 400:
-            logger.warning(f"OnyxError {exc.error_code.code}: {exc.message}")
+            logger.warning(f"OnyxError {exc.error_code.code}: {exc.detail}")
 
         return JSONResponse(
             status_code=status_code,
-            content=exc.error_code.detail(exc.message),
+            content=exc.error_code.detail(exc.detail),
         )
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider.py b/backend/tests/external_dependency_unit/llm/test_llm_provider.py
index 82ab4d07d32..3eb8ccddb4d 100644
--- a/backend/tests/external_dependency_unit/llm/test_llm_provider.py
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider.py
@@ -158,7 +158,7 @@ def mock_test_llm_failure(llm: LLM) -> str | None:  # noqa: ARG001
                     )
 
                 assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
-                assert exc_info.value.message == error_message
+                assert exc_info.value.detail == error_message
 
         finally:
             db_session.rollback()
@@ -540,7 +540,7 @@ def test_no_default_provider_raises_exception(
                 run_test_default_provider(_=_create_mock_admin())
 
             assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
-            assert "No LLM Provider setup" in exc_info.value.message
+            assert "No LLM Provider setup" in exc_info.value.detail
 
         finally:
             db_session.rollback()
@@ -585,7 +585,7 @@ def mock_test_llm_failure(llm: LLM) -> str | None:  # noqa: ARG001
                     run_test_default_provider(_=_create_mock_admin())
 
                 assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
-                assert exc_info.value.message == error_message
+                assert exc_info.value.detail == error_message
 
         finally:
             db_session.rollback()
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py b/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py
index cc656440d3d..3b53d965bd8 100644
--- a/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py
@@ -111,7 +111,7 @@ def test_blocks_api_base_change_without_key_change__multi_tenant(
 
                 assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.message
+                    exc_info.value.detail
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
@@ -247,7 +247,7 @@ def test_blocks_clearing_api_base__multi_tenant(
 
                 assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.message
+                    exc_info.value.detail
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
@@ -350,7 +350,7 @@ def test_blocks_custom_config_change_without_key_change__multi_tenant(
 
                 assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.message
+                    exc_info.value.detail
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
@@ -386,7 +386,7 @@ def test_blocks_adding_custom_config_without_key_change__multi_tenant(
 
                 assert exc_info.value.error_code == OnyxErrorCode.VALIDATION_ERROR
                 assert "cannot be changed without changing the API key" in str(
-                    exc_info.value.message
+                    exc_info.value.detail
                 )
         finally:
             _cleanup_provider(db_session, provider_name)
diff --git a/backend/tests/integration/tests/llm_provider/test_llm_provider.py b/backend/tests/integration/tests/llm_provider/test_llm_provider.py
index c3893fc209c..f5690fccc03 100644
--- a/backend/tests/integration/tests/llm_provider/test_llm_provider.py
+++ b/backend/tests/integration/tests/llm_provider/test_llm_provider.py
@@ -427,7 +427,7 @@ def test_delete_default_llm_provider_rejected(reset: None) -> None:  # noqa: ARG
         headers=admin_user.headers,
     )
     assert delete_response.status_code == 400
-    assert "Cannot delete the default LLM provider" in delete_response.json()["message"]
+    assert "Cannot delete the default LLM provider" in delete_response.json()["detail"]
 
     # Verify provider still exists
     provider_data = _get_provider_by_id(admin_user, created_provider["id"])
@@ -674,7 +674,7 @@ def test_duplicate_provider_name_rejected(reset: None) -> None:  # noqa: ARG001
         json=base_payload,
     )
     assert response.status_code == 409
-    assert "already exists" in response.json()["message"]
+    assert "already exists" in response.json()["detail"]
 
 
 def test_rename_provider_rejected(reset: None) -> None:  # noqa: ARG001
@@ -711,7 +711,7 @@ def test_rename_provider_rejected(reset: None) -> None:  # noqa: ARG001
         json=update_payload,
     )
     assert response.status_code == 400
-    assert "not currently supported" in response.json()["message"]
+    assert "not currently supported" in response.json()["detail"]
 
     # Verify no duplicate was created — only the original provider should exist
     provider = _get_provider_by_id(admin_user, provider_id)
diff --git a/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py b/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py
index 6a1be7b157f..77924ae4e1a 100644
--- a/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py
+++ b/backend/tests/integration/tests/llm_provider/test_llm_provider_persona_access.py
@@ -69,7 +69,7 @@ def test_unauthorized_persona_access_returns_403(
 
     # Should return 403 Forbidden
     assert response.status_code == 403
-    assert "don't have access to this assistant" in response.json()["message"]
+    assert "don't have access to this assistant" in response.json()["detail"]
 
 
 def test_authorized_persona_access_returns_filtered_providers(
@@ -245,4 +245,4 @@ def test_nonexistent_persona_returns_404(
 
     # Should return 404
     assert response.status_code == 404
-    assert "Persona not found" in response.json()["message"]
+    assert "Persona not found" in response.json()["detail"]
diff --git a/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py b/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
index cda9fa9dd83..d0976589842 100644
--- a/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
+++ b/backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
@@ -107,7 +107,7 @@ async def test_raises_on_service_error(
 
         assert exc_info.value.status_code == 502
         assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
-        assert exc_info.value.message == "Stripe error"
+        assert exc_info.value.detail == "Stripe error"
 
 
 class TestCreateCustomerPortalSession:
@@ -137,7 +137,7 @@ async def test_requires_license_for_self_hosted(
 
         assert exc_info.value.status_code == 400
         assert exc_info.value.error_code is OnyxErrorCode.VALIDATION_ERROR
-        assert exc_info.value.message == "No license found"
+        assert exc_info.value.detail == "No license found"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.api.create_portal_service")
@@ -243,7 +243,7 @@ async def test_requires_license_for_self_hosted(
 
         assert exc_info.value.status_code == 400
         assert exc_info.value.error_code is OnyxErrorCode.VALIDATION_ERROR
-        assert exc_info.value.message == "No license found"
+        assert exc_info.value.detail == "No license found"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.api.get_used_seats")
@@ -317,7 +317,7 @@ async def test_handles_billing_service_error(
 
         assert exc_info.value.status_code == 400
         assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
-        assert exc_info.value.message == "Cannot reduce below 10 seats"
+        assert exc_info.value.detail == "Cannot reduce below 10 seats"
 
 
 class TestCircuitBreaker:
@@ -346,7 +346,7 @@ async def test_returns_503_when_circuit_open(
 
         assert exc_info.value.status_code == 503
         assert exc_info.value.error_code is OnyxErrorCode.SERVICE_UNAVAILABLE
-        assert "Connect to Stripe" in exc_info.value.message
+        assert "Connect to Stripe" in exc_info.value.detail
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.api.MULTI_TENANT", False)
diff --git a/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py b/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
index 1376839b205..1f194da22c5 100644
--- a/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
+++ b/backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
@@ -101,7 +101,7 @@ async def test_raises_on_http_error(
 
         assert exc_info.value.status_code == 400
         assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
-        assert "Bad request" in exc_info.value.message
+        assert "Bad request" in exc_info.value.detail
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.billing.service._get_headers")
@@ -152,7 +152,7 @@ async def test_raises_on_connection_error(
 
         assert exc_info.value.status_code == 502
         assert exc_info.value.error_code is OnyxErrorCode.BAD_GATEWAY
-        assert "Failed to connect" in exc_info.value.message
+        assert "Failed to connect" in exc_info.value.detail
 
 
 class TestCreateCheckoutSession:
diff --git a/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py b/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
index ddb60b69d7c..5ed9f209867 100644
--- a/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
+++ b/backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
@@ -72,7 +72,7 @@ async def test_rejects_invalid_env_var_key_format(self) -> None:
 
         assert exc_info.value.status_code == 500
         assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
-        assert exc_info.value.message == "Invalid Stripe publishable key format"
+        assert exc_info.value.detail == "Invalid Stripe publishable key format"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_OVERRIDE", None)
@@ -97,7 +97,7 @@ async def test_rejects_invalid_s3_key_format(self) -> None:
 
         assert exc_info.value.status_code == 500
         assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
-        assert exc_info.value.message == "Invalid Stripe publishable key format"
+        assert exc_info.value.detail == "Invalid Stripe publishable key format"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_OVERRIDE", None)
@@ -118,7 +118,7 @@ async def test_handles_s3_fetch_error(self) -> None:
 
         assert exc_info.value.status_code == 500
         assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
-        assert exc_info.value.message == "Failed to fetch Stripe publishable key"
+        assert exc_info.value.detail == "Failed to fetch Stripe publishable key"
 
     @pytest.mark.asyncio
     @patch("ee.onyx.server.tenants.billing_api.STRIPE_PUBLISHABLE_KEY_OVERRIDE", None)
@@ -132,7 +132,7 @@ async def test_error_when_no_config(self) -> None:
 
         assert exc_info.value.status_code == 500
         assert exc_info.value.error_code is OnyxErrorCode.INTERNAL_ERROR
-        assert "not configured" in exc_info.value.message
+        assert "not configured" in exc_info.value.detail
 
     @pytest.mark.asyncio
     @patch(
diff --git a/backend/tests/unit/onyx/error_handling/test_exceptions.py b/backend/tests/unit/onyx/error_handling/test_exceptions.py
index f09224e8d71..45e1b196017 100644
--- a/backend/tests/unit/onyx/error_handling/test_exceptions.py
+++ b/backend/tests/unit/onyx/error_handling/test_exceptions.py
@@ -15,12 +15,12 @@ class TestOnyxError:
     def test_basic_construction(self) -> None:
         err = OnyxError(OnyxErrorCode.NOT_FOUND, "Session not found")
         assert err.error_code is OnyxErrorCode.NOT_FOUND
-        assert err.message == "Session not found"
+        assert err.detail == "Session not found"
         assert err.status_code == 404
 
     def test_message_defaults_to_code(self) -> None:
         err = OnyxError(OnyxErrorCode.UNAUTHENTICATED)
-        assert err.message == "UNAUTHENTICATED"
+        assert err.detail == "UNAUTHENTICATED"
         assert str(err) == "UNAUTHENTICATED"
 
     def test_status_code_override(self) -> None:
@@ -73,18 +73,18 @@ def test_returns_correct_status_and_body(self, client: TestClient) -> None:
         assert resp.status_code == 404
         body = resp.json()
         assert body["error_code"] == "NOT_FOUND"
-        assert body["message"] == "Thing not found"
+        assert body["detail"] == "Thing not found"
 
     def test_status_code_override_in_response(self, client: TestClient) -> None:
         resp = client.get("/boom-override")
         assert resp.status_code == 503
         body = resp.json()
         assert body["error_code"] == "BAD_GATEWAY"
-        assert body["message"] == "upstream 503"
+        assert body["detail"] == "upstream 503"
 
     def test_default_message(self, client: TestClient) -> None:
         resp = client.get("/boom-default-msg")
         assert resp.status_code == 401
         body = resp.json()
         assert body["error_code"] == "UNAUTHENTICATED"
-        assert body["message"] == "UNAUTHENTICATED"
+        assert body["detail"] == "UNAUTHENTICATED"
diff --git a/web/src/app/admin/configuration/llm/utils.ts b/web/src/app/admin/configuration/llm/utils.ts
index eba24b779e4..95629899dad 100644
--- a/web/src/app/admin/configuration/llm/utils.ts
+++ b/web/src/app/admin/configuration/llm/utils.ts
@@ -145,7 +145,7 @@ export const fetchBedrockModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.message || errorMessage;
+        errorMessage = errorData.detail || errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
@@ -199,7 +199,7 @@ export const fetchOllamaModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.message || errorMessage;
+        errorMessage = errorData.detail || errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
@@ -257,7 +257,7 @@ export const fetchOpenRouterModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.message || errorMessage;
+        errorMessage = errorData.detail || errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
@@ -313,7 +313,7 @@ export const fetchLMStudioModels = async (
       let errorMessage = "Failed to fetch models";
       try {
         const errorData = await response.json();
-        errorMessage = errorData.message || errorMessage;
+        errorMessage = errorData.detail || errorData.message || errorMessage;
       } catch {
         // ignore JSON parsing errors
       }
diff --git a/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx b/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
index efe6fcf0ab8..5ffc190b121 100644
--- a/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
+++ b/web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx
@@ -240,7 +240,7 @@ export default function AddConnector({
       toast.success("Credential deleted successfully!");
     } else {
       const errorData = await response.json();
-      toast.error(errorData.message);
+      toast.error(errorData.detail || errorData.message);
     }
   };
 
@@ -444,7 +444,7 @@ export default function AddConnector({
 
                 if (!timeoutErrorHappenedRef.current) {
                   // Only show error if timeout didn't happen
-                  toast.error(errorData.message || errorData.detail);
+                  toast.error(errorData.detail || errorData.message);
                 }
               }
             } else if (isSuccess) {
diff --git a/web/src/app/ee/admin/standard-answer/page.tsx b/web/src/app/ee/admin/standard-answer/page.tsx
index 19976d396b7..f6f9c3b2915 100644
--- a/web/src/app/ee/admin/standard-answer/page.tsx
+++ b/web/src/app/ee/admin/standard-answer/page.tsx
@@ -368,8 +368,8 @@ function Main() {
       <ErrorCallout
         errorTitle="Error loading standard answers"
         errorMsg={
-          standardAnswersError.info?.message ||
-          standardAnswersError.message.info?.detail
+          standardAnswersError.info?.detail ||
+          standardAnswersError.info?.message
         }
       />
     );
@@ -380,8 +380,8 @@ function Main() {
       <ErrorCallout
         errorTitle="Error loading standard answer categories"
         errorMsg={
-          standardAnswerCategoriesError.info?.message ||
-          standardAnswerCategoriesError.message.info?.detail
+          standardAnswerCategoriesError.info?.detail ||
+          standardAnswerCategoriesError.info?.message
         }
       />
     );
diff --git a/web/src/components/modals/NewTeamModal.tsx b/web/src/components/modals/NewTeamModal.tsx
index 908051d7e40..60649dc3521 100644
--- a/web/src/components/modals/NewTeamModal.tsx
+++ b/web/src/components/modals/NewTeamModal.tsx
@@ -96,7 +96,9 @@ export default function NewTeamModal() {
 
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
-        throw new Error(errorData.message || "Failed to request invite");
+        throw new Error(
+          errorData.detail || errorData.message || "Failed to request invite"
+        );
       }
 
       setHasRequestedInvite(true);
diff --git a/web/src/sections/modals/NewTenantModal.tsx b/web/src/sections/modals/NewTenantModal.tsx
index f1ee0a4755e..ac0eb01a2cc 100644
--- a/web/src/sections/modals/NewTenantModal.tsx
+++ b/web/src/sections/modals/NewTenantModal.tsx
@@ -49,7 +49,11 @@ export default function NewTenantModal({
 
         if (!response.ok) {
           const errorData = await response.json().catch(() => ({}));
-          throw new Error(errorData.message || "Failed to accept invitation");
+          throw new Error(
+            errorData.detail ||
+              errorData.message ||
+              "Failed to accept invitation"
+          );
         }
 
         toast.success("You have accepted the invitation.");
@@ -93,7 +97,11 @@ export default function NewTenantModal({
 
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
-        throw new Error(errorData.message || "Failed to decline invitation");
+        throw new Error(
+          errorData.detail ||
+            errorData.message ||
+            "Failed to decline invitation"
+        );
       }
 
       toast.info("You have declined the invitation.");
diff --git a/web/src/sections/modals/llmConfig/CustomModal.tsx b/web/src/sections/modals/llmConfig/CustomModal.tsx
index 0b5438c8ea1..8f57fde321d 100644
--- a/web/src/sections/modals/llmConfig/CustomModal.tsx
+++ b/web/src/sections/modals/llmConfig/CustomModal.tsx
@@ -261,7 +261,7 @@ export function CustomModal({
                                     <ErrorMessage
                                       name={`custom_config_list[${index}][0]`}
                                       component="div"
-                                      className="text-error text-sm mt-1"
+                                      className="text-status-text-error-05 text-sm mt-1"
                                     />
                                   </div>
                                   <div className="mt-3">
@@ -276,7 +276,7 @@ export function CustomModal({
                                     <ErrorMessage
                                       name={`custom_config_list[${index}][1]`}
                                       component="div"
-                                      className="text-error text-sm mt-1"
+                                      className="text-status-text-error-05 text-sm mt-1"
                                     />
                                   </div>
                                 </div>
diff --git a/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx b/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
index 8da3f9fce5f..03df9a6c99a 100644
--- a/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
+++ b/web/src/sections/modals/llmConfig/components/FormActionButtons.tsx
@@ -41,7 +41,7 @@ export function FormActionButtons({
   return (
     <>
       {testError && (
-        <Text as="p" className="text-error mt-2">
+        <Text as="p" className="text-status-text-error-05 mt-2">
           {testError}
         </Text>
       )}

From 28310b9138d8c4d38a7685922973f00799ab5cb0 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 9 Mar 2026 19:16:42 -0700
Subject: [PATCH 201/267] feat(storybook): add stories for all components - 2/3
 (#9194)

---
 web/.storybook/Introduction.mdx               | 115 ++++++
 web/.storybook/main.ts                        |   1 +
 .../buttons/Button/Button.stories.tsx         | 171 ++++++++
 .../buttons/OpenButton/OpenButton.stories.tsx |  80 ++++
 .../src/core/hoverable/Hoverable.stories.tsx  | 127 ++++++
 .../core/interactive/Interactive.stories.tsx  | 329 ++++++++++++++++
 .../layouts/Content/BodyLayout.stories.tsx    |  87 +++++
 .../src/layouts/Content/Content.stories.tsx   | 204 ++++++++++
 .../layouts/Content/HeadingLayout.stories.tsx |  98 +++++
 .../layouts/Content/LabelLayout.stories.tsx   | 154 ++++++++
 .../ContentAction/ContentAction.stories.tsx   |  69 ++++
 .../IllustrationContent.stories.tsx           |  42 ++
 .../refresh-components/Attachment.stories.tsx |  42 ++
 .../refresh-components/Calendar.stories.tsx   |  64 +++
 .../CharacterCount.stories.tsx                |  42 ++
 web/src/refresh-components/Chip.stories.tsx   |  40 ++
 web/src/refresh-components/Code.stories.tsx   |  43 +++
 .../Collapsible.stories.tsx                   |  99 +++++
 .../ColorSwatch.stories.tsx                   |  35 ++
 .../ConnectionProviderIcon.stories.tsx        |  33 ++
 .../refresh-components/Divider.stories.tsx    |  90 +++++
 .../EmptyMessage.stories.tsx                  |  42 ++
 .../EnabledCount.stories.tsx                  |  53 +++
 .../FadingEdgeContainer.stories.tsx           |  45 +++
 .../refresh-components/FrostedDiv.stories.tsx |  61 +++
 .../InlineExternalLink.stories.tsx            |  45 +++
 web/src/refresh-components/Modal.stories.tsx  | 179 +++++++++
 .../OverflowDiv.stories.tsx                   |  43 +++
 .../refresh-components/Pagination.stories.tsx |  57 +++
 .../refresh-components/Popover.stories.tsx    |  88 +++++
 .../PreviewImage.stories.tsx                  |  37 ++
 .../ScrollIndicatorDiv.stories.tsx            |  53 +++
 .../refresh-components/Separator.stories.tsx  |  53 +++
 .../refresh-components/ShadowDiv.stories.tsx  |  55 +++
 .../SimpleCollapsible.stories.tsx             |  58 +++
 .../SimplePopover.stories.tsx                 |  44 +++
 .../refresh-components/SimpleTabs.stories.tsx |  72 ++++
 .../SimpleTooltip.stories.tsx                 |  49 +++
 web/src/refresh-components/Spacer.stories.tsx |  54 +++
 web/src/refresh-components/Tabs.stories.tsx   | 151 ++++++++
 .../TextSeparator.stories.tsx                 |  39 ++
 .../avatars/CustomAgentAvatar.stories.tsx     |  91 +++++
 .../buttons/AttachmentButton.stories.tsx      | 112 ++++++
 .../buttons/BackButton.stories.tsx            |  29 ++
 .../buttons/Button.stories.tsx                |  76 ++++
 .../buttons/ButtonRenaming.stories.tsx        |  62 +++
 .../buttons/CopyIconButton.stories.tsx        |  32 ++
 .../buttons/CreateButton.stories.tsx          |  51 +++
 .../buttons/FilterButton.stories.tsx          |  74 ++++
 .../buttons/IconButton.stories.tsx            |  57 +++
 .../buttons/LineItem.stories.tsx              | 129 +++++++
 .../buttons/SelectButton.stories.tsx          | 135 +++++++
 .../buttons/SidebarTab.stories.tsx            |  89 +++++
 .../buttons/SquareButton.stories.tsx          |  52 +++
 .../buttons/Tag.stories.tsx                   |  93 +++++
 .../refresh-components/cards/Card.stories.tsx | 141 +++++++
 .../cards/Select.stories.tsx                  | 129 +++++++
 .../commandmenu/CommandMenu.stories.tsx       | 154 ++++++++
 .../form/FormField.stories.tsx                |  89 +++++
 .../form/FormikFields.stories.tsx             | 229 +++++++++++
 .../refresh-components/form/Label.stories.tsx |  34 ++
 .../inputs/Checkbox.stories.tsx               |  46 +++
 .../inputs/InputAvatar.stories.tsx            |  61 +++
 .../inputs/InputChipField.stories.tsx         | 110 ++++++
 .../InputComboBox/InputComboBox.stories.tsx   | 144 +++++++
 .../inputs/InputDatePicker.stories.tsx        |  59 +++
 .../inputs/InputFile.stories.tsx              |  75 ++++
 .../inputs/InputImage.stories.tsx             |  85 ++++
 .../inputs/InputKeyValue.stories.tsx          | 134 +++++++
 .../inputs/InputNumber.stories.tsx            |  46 +++
 .../inputs/InputSelect.stories.tsx            | 128 ++++++
 .../inputs/InputTextArea.stories.tsx          |  71 ++++
 .../inputs/InputTypeIn.stories.tsx            |  71 ++++
 .../inputs/ListFieldInput.stories.tsx         |  77 ++++
 .../inputs/PasswordInputTypeIn.stories.tsx    |  87 +++++
 .../inputs/Switch.stories.tsx                 |  35 ++
 .../ConfirmationModalLayout.stories.tsx       | 114 ++++++
 .../loaders/SimpleLoader.stories.tsx          |  27 ++
 .../messages/FieldMessage.stories.tsx         |  93 +++++
 .../messages/InfoBlock.stories.tsx            |  45 +++
 .../messages/Message.stories.tsx              | 136 +++++++
 .../skeletons/ChatSessionSkeleton.stories.tsx |  26 ++
 .../skeletons/SidebarTabSkeleton.stories.tsx  |  39 ++
 .../table/DataTable.stories.tsx               | 365 ++++++++++++++++++
 .../table/Footer.stories.tsx                  | 183 +++++++++
 .../table/Table.stories.tsx                   | 281 ++++++++++++++
 .../texts/ExpandableTextDisplay.stories.tsx   |  89 +++++
 .../refresh-components/texts/Text.stories.tsx |  59 +++
 .../texts/Truncated.stories.tsx               |  76 ++++
 .../tiles/ButtonTile.stories.tsx              |  99 +++++
 .../tiles/FileTile.stories.tsx                | 112 ++++++
 91 files changed, 8074 insertions(+)
 create mode 100644 web/.storybook/Introduction.mdx
 create mode 100644 web/lib/opal/src/components/buttons/Button/Button.stories.tsx
 create mode 100644 web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx
 create mode 100644 web/lib/opal/src/core/hoverable/Hoverable.stories.tsx
 create mode 100644 web/lib/opal/src/core/interactive/Interactive.stories.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/BodyLayout.stories.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/Content.stories.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/HeadingLayout.stories.tsx
 create mode 100644 web/lib/opal/src/layouts/Content/LabelLayout.stories.tsx
 create mode 100644 web/lib/opal/src/layouts/ContentAction/ContentAction.stories.tsx
 create mode 100644 web/lib/opal/src/layouts/IllustrationContent/IllustrationContent.stories.tsx
 create mode 100644 web/src/refresh-components/Attachment.stories.tsx
 create mode 100644 web/src/refresh-components/Calendar.stories.tsx
 create mode 100644 web/src/refresh-components/CharacterCount.stories.tsx
 create mode 100644 web/src/refresh-components/Chip.stories.tsx
 create mode 100644 web/src/refresh-components/Code.stories.tsx
 create mode 100644 web/src/refresh-components/Collapsible.stories.tsx
 create mode 100644 web/src/refresh-components/ColorSwatch.stories.tsx
 create mode 100644 web/src/refresh-components/ConnectionProviderIcon.stories.tsx
 create mode 100644 web/src/refresh-components/Divider.stories.tsx
 create mode 100644 web/src/refresh-components/EmptyMessage.stories.tsx
 create mode 100644 web/src/refresh-components/EnabledCount.stories.tsx
 create mode 100644 web/src/refresh-components/FadingEdgeContainer.stories.tsx
 create mode 100644 web/src/refresh-components/FrostedDiv.stories.tsx
 create mode 100644 web/src/refresh-components/InlineExternalLink.stories.tsx
 create mode 100644 web/src/refresh-components/Modal.stories.tsx
 create mode 100644 web/src/refresh-components/OverflowDiv.stories.tsx
 create mode 100644 web/src/refresh-components/Pagination.stories.tsx
 create mode 100644 web/src/refresh-components/Popover.stories.tsx
 create mode 100644 web/src/refresh-components/PreviewImage.stories.tsx
 create mode 100644 web/src/refresh-components/ScrollIndicatorDiv.stories.tsx
 create mode 100644 web/src/refresh-components/Separator.stories.tsx
 create mode 100644 web/src/refresh-components/ShadowDiv.stories.tsx
 create mode 100644 web/src/refresh-components/SimpleCollapsible.stories.tsx
 create mode 100644 web/src/refresh-components/SimplePopover.stories.tsx
 create mode 100644 web/src/refresh-components/SimpleTabs.stories.tsx
 create mode 100644 web/src/refresh-components/SimpleTooltip.stories.tsx
 create mode 100644 web/src/refresh-components/Spacer.stories.tsx
 create mode 100644 web/src/refresh-components/Tabs.stories.tsx
 create mode 100644 web/src/refresh-components/TextSeparator.stories.tsx
 create mode 100644 web/src/refresh-components/avatars/CustomAgentAvatar.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/AttachmentButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/BackButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/Button.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/ButtonRenaming.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/CopyIconButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/CreateButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/FilterButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/IconButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/LineItem.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/SelectButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/SidebarTab.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/SquareButton.stories.tsx
 create mode 100644 web/src/refresh-components/buttons/Tag.stories.tsx
 create mode 100644 web/src/refresh-components/cards/Card.stories.tsx
 create mode 100644 web/src/refresh-components/cards/Select.stories.tsx
 create mode 100644 web/src/refresh-components/commandmenu/CommandMenu.stories.tsx
 create mode 100644 web/src/refresh-components/form/FormField.stories.tsx
 create mode 100644 web/src/refresh-components/form/FormikFields.stories.tsx
 create mode 100644 web/src/refresh-components/form/Label.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/Checkbox.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputAvatar.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputChipField.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputComboBox/InputComboBox.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputDatePicker.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputFile.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputImage.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputKeyValue.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputNumber.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputSelect.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputTextArea.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/InputTypeIn.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/ListFieldInput.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/PasswordInputTypeIn.stories.tsx
 create mode 100644 web/src/refresh-components/inputs/Switch.stories.tsx
 create mode 100644 web/src/refresh-components/layouts/ConfirmationModalLayout.stories.tsx
 create mode 100644 web/src/refresh-components/loaders/SimpleLoader.stories.tsx
 create mode 100644 web/src/refresh-components/messages/FieldMessage.stories.tsx
 create mode 100644 web/src/refresh-components/messages/InfoBlock.stories.tsx
 create mode 100644 web/src/refresh-components/messages/Message.stories.tsx
 create mode 100644 web/src/refresh-components/skeletons/ChatSessionSkeleton.stories.tsx
 create mode 100644 web/src/refresh-components/skeletons/SidebarTabSkeleton.stories.tsx
 create mode 100644 web/src/refresh-components/table/DataTable.stories.tsx
 create mode 100644 web/src/refresh-components/table/Footer.stories.tsx
 create mode 100644 web/src/refresh-components/table/Table.stories.tsx
 create mode 100644 web/src/refresh-components/texts/ExpandableTextDisplay.stories.tsx
 create mode 100644 web/src/refresh-components/texts/Text.stories.tsx
 create mode 100644 web/src/refresh-components/texts/Truncated.stories.tsx
 create mode 100644 web/src/refresh-components/tiles/ButtonTile.stories.tsx
 create mode 100644 web/src/refresh-components/tiles/FileTile.stories.tsx

diff --git a/web/.storybook/Introduction.mdx b/web/.storybook/Introduction.mdx
new file mode 100644
index 00000000000..74e99abe422
--- /dev/null
+++ b/web/.storybook/Introduction.mdx
@@ -0,0 +1,115 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Getting Started" />
+
+# Onyx Storybook
+
+A living catalog for browsing, testing, and documenting Onyx UI components in isolation.
+
+---
+
+## What is this?
+
+This Storybook contains interactive examples of every reusable UI component in the Onyx frontend. Each component has a dedicated page with:
+
+- **Live demos** you can interact with directly
+- **Controls** to tweak props and see how the component responds
+- **Auto-generated docs** showing the full props API
+- **Dark mode toggle** in the toolbar to preview both themes
+
+---
+
+## Navigating Storybook
+
+### Sidebar
+
+The left sidebar organizes components by layer:
+
+- **opal/core** — Low-level primitives (`Interactive`, `Hoverable`)
+- **opal/components** — Design system atoms (`Button`, `OpenButton`, `Tag`)
+- **Layouts** — Structural layouts (`Content`, `ContentAction`, `IllustrationContent`)
+- **refresh-components** — App-level components (inputs, modals, tables, text, etc.)
+
+Click any component to see its stories. Click **Docs** to see the auto-generated props table.
+
+### Controls panel
+
+At the bottom of each story, the **Controls** panel lets you change props in real time. Toggle booleans, pick from enums, type in strings — the preview updates instantly.
+
+### Theme toggle
+
+Use the paint roller icon in the top toolbar to switch between **light** and **dark** mode. All components use CSS variables that automatically adapt.
+
+---
+
+## Running locally
+
+```bash
+cd web
+npm run storybook        # dev server on :6006
+npm run storybook:build  # static build to storybook-static/
+```
+
+---
+
+## Adding a new story
+
+Stories are **co-located** next to their component:
+
+```
+lib/opal/src/components/buttons/Button/
+├── components.tsx       ← the component
+├── Button.stories.tsx   ← the story
+├── styles.css
+└── README.md
+```
+
+### Minimal template
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { MyComponent } from "./MyComponent";
+
+const meta: Meta<typeof MyComponent> = {
+  title: "opal/components/MyComponent",  // sidebar path
+  component: MyComponent,
+  tags: ["autodocs"],                     // auto-generate docs page
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const Default: Story = {
+  args: {
+    title: "Hello",
+  },
+};
+
+export const WithCustomLayout: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <MyComponent title="One" />
+      <MyComponent title="Two" />
+    </div>
+  ),
+};
+```
+
+### Conventions
+
+- **Title format:** `opal/core/Name`, `opal/components/Name`, `Layouts/Name`, or `refresh-components/Name`
+- **Tags:** Add `tags: ["autodocs"]` to auto-generate a docs page from props
+- **Decorators:** If your component needs `TooltipPrimitive.Provider` (anything with tooltips), add it as a decorator
+- **Layout:** Use `parameters: { layout: "fullscreen" }` for modals/popovers that use portals
+
+---
+
+## Deployment
+
+Production builds deploy to [onyx-storybook.vercel.app](https://onyx-storybook.vercel.app) automatically when PRs touching component files merge to `main`.
+
+Monitored paths:
+
+- `web/lib/opal/**`
+- `web/src/refresh-components/**`
+- `web/.storybook/**`
diff --git a/web/.storybook/main.ts b/web/.storybook/main.ts
index 78eb510d0c5..1063f22dcd0 100644
--- a/web/.storybook/main.ts
+++ b/web/.storybook/main.ts
@@ -3,6 +3,7 @@ import path from "path";
 
 const config: StorybookConfig = {
   stories: [
+    "./*.mdx",
     "../lib/opal/src/**/*.stories.@(ts|tsx)",
     "../src/refresh-components/**/*.stories.@(ts|tsx)",
   ],
diff --git a/web/lib/opal/src/components/buttons/Button/Button.stories.tsx b/web/lib/opal/src/components/buttons/Button/Button.stories.tsx
new file mode 100644
index 00000000000..228f6f801e7
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/Button/Button.stories.tsx
@@ -0,0 +1,171 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "@opal/components";
+import { SvgPlus, SvgArrowRight, SvgSettings } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Button> = {
+  title: "opal/components/Button",
+  component: Button,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Default: Story = {
+  args: {
+    children: "Button",
+    variant: "default",
+    prominence: "primary",
+  },
+};
+
+const VARIANTS = ["default", "action", "danger"] as const;
+const PROMINENCES = ["primary", "secondary", "tertiary"] as const;
+
+export const VariantProminenceGrid: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns: "auto repeat(3, 1fr)",
+        gap: 12,
+        alignItems: "center",
+      }}
+    >
+      {/* Header row */}
+      <div />
+      {PROMINENCES.map((p) => (
+        <div
+          key={p}
+          style={{
+            fontWeight: 600,
+            textAlign: "center",
+            textTransform: "capitalize",
+          }}
+        >
+          {p}
+        </div>
+      ))}
+
+      {/* Variant rows */}
+      {VARIANTS.map((variant) => (
+        <React.Fragment key={variant}>
+          <div style={{ fontWeight: 600, textTransform: "capitalize" }}>
+            {variant}
+          </div>
+          {PROMINENCES.map((prominence) => (
+            <Button
+              key={`${variant}-${prominence}`}
+              variant={variant}
+              prominence={prominence}
+            >
+              {`${variant} ${prominence}`}
+            </Button>
+          ))}
+        </React.Fragment>
+      ))}
+    </div>
+  ),
+};
+
+export const WithLeftIcon: Story = {
+  args: {
+    icon: SvgPlus,
+    children: "Add item",
+  },
+};
+
+export const WithRightIcon: Story = {
+  args: {
+    rightIcon: SvgArrowRight,
+    children: "Continue",
+  },
+};
+
+export const IconOnly: Story = {
+  args: {
+    icon: SvgSettings,
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
+      {(["lg", "md", "sm", "xs", "2xs", "fit"] as const).map((size) => (
+        <Button key={size} size={size} icon={SvgPlus}>
+          {size}
+        </Button>
+      ))}
+    </div>
+  ),
+};
+
+export const Foldable: Story = {
+  args: {
+    foldable: true,
+    icon: SvgPlus,
+    children: "Add item",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    children: "Disabled",
+  },
+};
+
+export const WidthFull: Story = {
+  args: {
+    width: "full",
+    children: "Full width",
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 400 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const AsLink: Story = {
+  args: {
+    href: "https://example.com",
+    children: "Visit site",
+    rightIcon: SvgArrowRight,
+  },
+};
+
+export const WithTooltip: Story = {
+  args: {
+    icon: SvgSettings,
+    tooltip: "Open settings",
+    tooltipSide: "bottom",
+  },
+};
+
+export const ResponsiveHideText: Story = {
+  args: {
+    icon: SvgPlus,
+    children: "Create",
+    responsiveHideText: true,
+  },
+};
+
+export const InternalProminence: Story = {
+  args: {
+    variant: "default",
+    prominence: "internal",
+    children: "Internal",
+  },
+};
diff --git a/web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx b/web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx
new file mode 100644
index 00000000000..d31b8483776
--- /dev/null
+++ b/web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx
@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { OpenButton } from "@opal/components";
+import { SvgSettings } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof OpenButton> = {
+  title: "opal/components/OpenButton",
+  component: OpenButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof OpenButton>;
+
+export const Default: Story = {
+  args: {
+    children: "Select option",
+  },
+};
+
+export const WithIcon: Story = {
+  args: {
+    icon: SvgSettings,
+    children: "Settings",
+  },
+};
+
+export const Selected: Story = {
+  args: {
+    selected: true,
+    children: "Selected",
+  },
+};
+
+export const Open: Story = {
+  args: {
+    transient: true,
+    children: "Open state",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    children: "Disabled",
+  },
+};
+
+export const LightProminence: Story = {
+  args: {
+    prominence: "light",
+    children: "Light prominence",
+  },
+};
+
+export const HeavyProminence: Story = {
+  args: {
+    prominence: "heavy",
+    children: "Heavy prominence",
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
+      {(["lg", "md", "sm", "xs", "2xs"] as const).map((size) => (
+        <OpenButton key={size} size={size}>
+          {size}
+        </OpenButton>
+      ))}
+    </div>
+  ),
+};
diff --git a/web/lib/opal/src/core/hoverable/Hoverable.stories.tsx b/web/lib/opal/src/core/hoverable/Hoverable.stories.tsx
new file mode 100644
index 00000000000..bab9caa6f94
--- /dev/null
+++ b/web/lib/opal/src/core/hoverable/Hoverable.stories.tsx
@@ -0,0 +1,127 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Hoverable } from "@opal/core";
+import SvgX from "@opal/icons/x";
+
+// ---------------------------------------------------------------------------
+// Shared styles
+// ---------------------------------------------------------------------------
+
+const cardStyle: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: "1rem",
+  padding: "0.75rem 1rem",
+  borderRadius: "0.5rem",
+  border: "1px solid var(--border-02)",
+  background: "var(--background-neutral-01)",
+  minWidth: 220,
+};
+
+const labelStyle: React.CSSProperties = {
+  fontSize: "0.875rem",
+  fontWeight: 500,
+};
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: "Core/Hoverable",
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/**
+ * Local hover mode -- no `group` prop on the Item.
+ * The icon only appears when you hover directly over the Item element itself.
+ */
+export const LocalHover: StoryObj = {
+  render: () => (
+    <div style={cardStyle}>
+      <span style={labelStyle}>Hover this card area</span>
+
+      <Hoverable.Item variant="opacity-on-hover">
+        <SvgX width={16} height={16} />
+      </Hoverable.Item>
+    </div>
+  ),
+};
+
+/**
+ * Group hover mode -- hovering anywhere inside the Root reveals the Item.
+ */
+export const GroupHover: StoryObj = {
+  render: () => (
+    <Hoverable.Root group="card">
+      <div style={cardStyle}>
+        <span style={labelStyle}>Hover anywhere on this card</span>
+
+        <Hoverable.Item group="card" variant="opacity-on-hover">
+          <SvgX width={16} height={16} />
+        </Hoverable.Item>
+      </div>
+    </Hoverable.Root>
+  ),
+};
+
+/**
+ * Nested groups demonstrating isolation.
+ *
+ * - Hovering the outer card reveals only the outer icon.
+ * - Hovering the inner card reveals only the inner icon.
+ */
+export const NestedGroups: StoryObj = {
+  render: () => (
+    <Hoverable.Root group="outer">
+      <div
+        style={{
+          ...cardStyle,
+          flexDirection: "column",
+          alignItems: "stretch",
+          gap: "0.75rem",
+          padding: "1rem",
+          minWidth: 300,
+        }}
+      >
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+          }}
+        >
+          <span style={labelStyle}>Outer card</span>
+
+          <Hoverable.Item group="outer" variant="opacity-on-hover">
+            <SvgX width={16} height={16} />
+          </Hoverable.Item>
+        </div>
+
+        <Hoverable.Root group="inner">
+          <div
+            style={{
+              ...cardStyle,
+              background: "var(--background-neutral-02)",
+            }}
+          >
+            <span style={labelStyle}>Inner card</span>
+
+            <Hoverable.Item group="inner" variant="opacity-on-hover">
+              <SvgX width={16} height={16} />
+            </Hoverable.Item>
+          </div>
+        </Hoverable.Root>
+      </div>
+    </Hoverable.Root>
+  ),
+};
diff --git a/web/lib/opal/src/core/interactive/Interactive.stories.tsx b/web/lib/opal/src/core/interactive/Interactive.stories.tsx
new file mode 100644
index 00000000000..1cf6180e6fe
--- /dev/null
+++ b/web/lib/opal/src/core/interactive/Interactive.stories.tsx
@@ -0,0 +1,329 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Interactive } from "@opal/core";
+
+// ---------------------------------------------------------------------------
+// Variant / Prominence mappings for the matrix story
+// ---------------------------------------------------------------------------
+
+const VARIANT_PROMINENCE_MAP: Record<string, string[]> = {
+  default: ["primary", "secondary", "tertiary", "internal"],
+  action: ["primary", "secondary", "tertiary", "internal"],
+  danger: ["primary", "secondary", "tertiary", "internal"],
+  select: ["light", "heavy"],
+  sidebar: ["light"],
+  none: [],
+};
+
+const SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
+const ROUNDING_VARIANTS = ["default", "compact", "mini"] as const;
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: "Core/Interactive",
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Basic Interactive.Base + Container with text content. */
+export const Default: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem", alignItems: "center" }}>
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Secondary</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base
+        variant="default"
+        prominence="primary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Primary</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base
+        variant="default"
+        prominence="tertiary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Tertiary</span>
+        </Interactive.Container>
+      </Interactive.Base>
+    </div>
+  ),
+};
+
+/** All variant x prominence combinations displayed in a grid. */
+export const VariantMatrix: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1.5rem" }}>
+      {Object.entries(VARIANT_PROMINENCE_MAP).map(([variant, prominences]) => (
+        <div key={variant}>
+          <div
+            style={{
+              fontSize: "0.75rem",
+              fontWeight: 600,
+              textTransform: "uppercase",
+              letterSpacing: "0.05em",
+              paddingBottom: "0.5rem",
+            }}
+          >
+            {variant}
+          </div>
+
+          {prominences.length === 0 ? (
+            <Interactive.Base variant="none" onClick={() => {}}>
+              <Interactive.Container border>
+                <span>none (no prominence)</span>
+              </Interactive.Container>
+            </Interactive.Base>
+          ) : (
+            <div style={{ display: "flex", gap: "0.5rem", flexWrap: "wrap" }}>
+              {prominences.map((prominence) => (
+                <div
+                  key={prominence}
+                  style={{
+                    display: "flex",
+                    flexDirection: "column",
+                    alignItems: "center",
+                    gap: "0.25rem",
+                  }}
+                >
+                  <Interactive.Base
+                    // Cast required because the discriminated union can't be
+                    // resolved from dynamic strings at the type level.
+                    {...({ variant, prominence } as any)}
+                    onClick={() => {}}
+                  >
+                    <Interactive.Container border>
+                      <span>{prominence}</span>
+                    </Interactive.Container>
+                  </Interactive.Base>
+                  <span
+                    style={{
+                      fontSize: "0.625rem",
+                      opacity: 0.6,
+                    }}
+                  >
+                    {prominence}
+                  </span>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/** All heightVariant sizes (lg, md, sm, xs, 2xs, fit). */
+export const Sizes: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", alignItems: "center", gap: "0.75rem" }}>
+      {SIZE_VARIANTS.map((size) => (
+        <Interactive.Base
+          key={size}
+          variant="default"
+          prominence="secondary"
+          onClick={() => {}}
+        >
+          <Interactive.Container border heightVariant={size}>
+            <span>{size}</span>
+          </Interactive.Container>
+        </Interactive.Base>
+      ))}
+    </div>
+  ),
+};
+
+/** Container with widthVariant="full" stretching to fill its parent. */
+export const WidthFull: StoryObj = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border widthVariant="full">
+          <span>Full width container</span>
+        </Interactive.Container>
+      </Interactive.Base>
+    </div>
+  ),
+};
+
+/** All rounding variants side by side. */
+export const Rounding: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem" }}>
+      {ROUNDING_VARIANTS.map((rounding) => (
+        <Interactive.Base
+          key={rounding}
+          variant="default"
+          prominence="secondary"
+          onClick={() => {}}
+        >
+          <Interactive.Container border roundingVariant={rounding}>
+            <span>{rounding}</span>
+          </Interactive.Container>
+        </Interactive.Base>
+      ))}
+    </div>
+  ),
+};
+
+/** Disabled state prevents clicks and shows disabled styling. */
+export const Disabled: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem" }}>
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+        disabled
+      >
+        <Interactive.Container border>
+          <span>Disabled</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Enabled</span>
+        </Interactive.Container>
+      </Interactive.Base>
+    </div>
+  ),
+};
+
+/** Transient prop forces the hover/active visual state. */
+export const Transient: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem" }}>
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+        transient
+      >
+        <Interactive.Container border>
+          <span>Forced hover</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Normal</span>
+        </Interactive.Container>
+      </Interactive.Base>
+    </div>
+  ),
+};
+
+/** Container with border={true}. */
+export const WithBorder: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem" }}>
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>With border</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base
+        variant="default"
+        prominence="secondary"
+        onClick={() => {}}
+      >
+        <Interactive.Container>
+          <span>Without border</span>
+        </Interactive.Container>
+      </Interactive.Base>
+    </div>
+  ),
+};
+
+/** Using href to render as a link. */
+export const AsLink: StoryObj = {
+  render: () => (
+    <Interactive.Base variant="action" href="/settings">
+      <Interactive.Container border>
+        <span>Go to Settings</span>
+      </Interactive.Container>
+    </Interactive.Base>
+  ),
+};
+
+/** Select variant with selected and unselected states. */
+export const SelectVariant: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem" }}>
+      <Interactive.Base
+        variant="select"
+        prominence="light"
+        selected
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Selected (light)</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base variant="select" prominence="light" onClick={() => {}}>
+        <Interactive.Container border>
+          <span>Unselected (light)</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base
+        variant="select"
+        prominence="heavy"
+        selected
+        onClick={() => {}}
+      >
+        <Interactive.Container border>
+          <span>Selected (heavy)</span>
+        </Interactive.Container>
+      </Interactive.Base>
+
+      <Interactive.Base variant="select" prominence="heavy" onClick={() => {}}>
+        <Interactive.Container border>
+          <span>Unselected (heavy)</span>
+        </Interactive.Container>
+      </Interactive.Base>
+    </div>
+  ),
+};
diff --git a/web/lib/opal/src/layouts/Content/BodyLayout.stories.tsx b/web/lib/opal/src/layouts/Content/BodyLayout.stories.tsx
new file mode 100644
index 00000000000..4908a2b0ca0
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/BodyLayout.stories.tsx
@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { BodyLayout } from "./BodyLayout";
+import { SvgSettings, SvgStar, SvgRefreshCw } from "@opal/icons";
+
+const meta = {
+  title: "Layouts/BodyLayout",
+  component: BodyLayout,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof BodyLayout>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Size presets
+// ---------------------------------------------------------------------------
+
+export const MainContent: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Last synced 2 minutes ago",
+  },
+};
+
+export const MainUi: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Document count: 1,234",
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    sizePreset: "secondary",
+    title: "Updated 5 min ago",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// With icon
+// ---------------------------------------------------------------------------
+
+export const WithIcon: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Settings",
+    icon: SvgSettings,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Orientations
+// ---------------------------------------------------------------------------
+
+export const Vertical: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Stacked layout",
+    icon: SvgStar,
+    orientation: "vertical",
+  },
+};
+
+export const Reverse: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Reverse layout",
+    icon: SvgRefreshCw,
+    orientation: "reverse",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Prominence
+// ---------------------------------------------------------------------------
+
+export const Muted: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Muted body text",
+    prominence: "muted",
+  },
+};
diff --git a/web/lib/opal/src/layouts/Content/Content.stories.tsx b/web/lib/opal/src/layouts/Content/Content.stories.tsx
new file mode 100644
index 00000000000..8e29addf419
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/Content.stories.tsx
@@ -0,0 +1,204 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Content } from "@opal/layouts";
+import { SvgSettings, SvgStar, SvgRefreshCw } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta = {
+  title: "Layouts/Content",
+  component: Content,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+} satisfies Meta<typeof Content>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// XL stories (sizePreset: headline | section, variant: heading)
+// ---------------------------------------------------------------------------
+
+export const XlHeadline: Story = {
+  args: {
+    sizePreset: "headline",
+    variant: "heading",
+    title: "Welcome to Onyx",
+    description: "Your enterprise search and AI assistant platform.",
+  },
+};
+
+export const XlSection: Story = {
+  args: {
+    sizePreset: "section",
+    variant: "heading",
+    title: "Configuration",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// LG stories (sizePreset: headline | section, variant: section)
+// ---------------------------------------------------------------------------
+
+export const LgHeadline: Story = {
+  args: {
+    sizePreset: "headline",
+    variant: "section",
+    title: "Connectors Overview",
+  },
+};
+
+export const LgSection: Story = {
+  args: {
+    sizePreset: "section",
+    variant: "section",
+    title: "Data Sources",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// MD stories (sizePreset: main-content | main-ui | secondary, variant: section)
+// ---------------------------------------------------------------------------
+
+export const MdMainContent: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "General Settings",
+    description: "Manage your workspace preferences.",
+    icon: SvgSettings,
+  },
+};
+
+export const MdWithTag: Story = {
+  args: {
+    sizePreset: "main-ui",
+    variant: "section",
+    title: "Knowledge Graph",
+    tag: { title: "Beta", color: "blue" },
+  },
+};
+
+export const MdMuted: Story = {
+  args: {
+    sizePreset: "secondary",
+    variant: "section",
+    title: "Advanced Options",
+    description: "Fine-tune model behavior and parameters.",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// SM stories (sizePreset: main-content | main-ui | secondary, variant: body)
+// ---------------------------------------------------------------------------
+
+export const SmBody: Story = {
+  args: {
+    sizePreset: "secondary",
+    variant: "body",
+    title: "Last synced 2 minutes ago",
+  },
+};
+
+export const SmStacked: Story = {
+  args: {
+    sizePreset: "secondary",
+    variant: "body",
+    title: "Document count",
+    orientation: "stacked",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Editable
+// ---------------------------------------------------------------------------
+
+export const Editable: Story = {
+  args: {
+    sizePreset: "main-ui",
+    variant: "section",
+    title: "Editable Title",
+    editable: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// MD — optional prop
+// ---------------------------------------------------------------------------
+
+export const MdWithOptional: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "API Key",
+    optional: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// MD — auxIcon prop
+// ---------------------------------------------------------------------------
+
+export const MdWithAuxIcon: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "Connection Status",
+    auxIcon: "warning",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// XL — moreIcon1 / moreIcon2 props
+// ---------------------------------------------------------------------------
+
+export const XlWithMoreIcons: Story = {
+  args: {
+    sizePreset: "headline",
+    variant: "heading",
+    title: "Dashboard",
+    moreIcon1: SvgStar,
+    moreIcon2: SvgRefreshCw,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// SM — prominence: muted
+// ---------------------------------------------------------------------------
+
+export const SmMuted: Story = {
+  args: {
+    sizePreset: "secondary",
+    variant: "body",
+    title: "Updated 5 min ago",
+    prominence: "muted",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// widthVariant: full
+// ---------------------------------------------------------------------------
+
+export const WidthFull: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "Full Width Content",
+    widthVariant: "full",
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 600, border: "1px dashed gray" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
diff --git a/web/lib/opal/src/layouts/Content/HeadingLayout.stories.tsx b/web/lib/opal/src/layouts/Content/HeadingLayout.stories.tsx
new file mode 100644
index 00000000000..562bbfa7db3
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/HeadingLayout.stories.tsx
@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { HeadingLayout } from "./HeadingLayout";
+import { SvgSettings, SvgStar } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta = {
+  title: "Layouts/HeadingLayout",
+  component: HeadingLayout,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+} satisfies Meta<typeof HeadingLayout>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Size presets
+// ---------------------------------------------------------------------------
+
+export const Headline: Story = {
+  args: {
+    sizePreset: "headline",
+    title: "Welcome to Onyx",
+    description: "Your enterprise search and AI assistant platform.",
+  },
+};
+
+export const Section: Story = {
+  args: {
+    sizePreset: "section",
+    title: "Configuration",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// With icon
+// ---------------------------------------------------------------------------
+
+export const WithIcon: Story = {
+  args: {
+    sizePreset: "headline",
+    title: "Settings",
+    icon: SvgSettings,
+  },
+};
+
+export const SectionWithIcon: Story = {
+  args: {
+    sizePreset: "section",
+    variant: "section",
+    title: "Favorites",
+    icon: SvgStar,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Variants
+// ---------------------------------------------------------------------------
+
+export const SectionVariant: Story = {
+  args: {
+    sizePreset: "headline",
+    variant: "section",
+    title: "Inline Icon Heading",
+    icon: SvgSettings,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Editable
+// ---------------------------------------------------------------------------
+
+export const Editable: Story = {
+  args: {
+    sizePreset: "headline",
+    title: "Click to edit me",
+    editable: true,
+  },
+};
+
+export const EditableSection: Story = {
+  args: {
+    sizePreset: "section",
+    title: "Editable Section Title",
+    editable: true,
+    description: "This title can be edited inline.",
+  },
+};
diff --git a/web/lib/opal/src/layouts/Content/LabelLayout.stories.tsx b/web/lib/opal/src/layouts/Content/LabelLayout.stories.tsx
new file mode 100644
index 00000000000..0dd3bdff3df
--- /dev/null
+++ b/web/lib/opal/src/layouts/Content/LabelLayout.stories.tsx
@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { LabelLayout } from "./LabelLayout";
+import { SvgSettings, SvgStar } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta = {
+  title: "Layouts/LabelLayout",
+  component: LabelLayout,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+} satisfies Meta<typeof LabelLayout>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Size presets
+// ---------------------------------------------------------------------------
+
+export const MainContent: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Display Name",
+  },
+};
+
+export const MainUi: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Email Address",
+  },
+};
+
+export const SecondaryPreset: Story = {
+  args: {
+    sizePreset: "secondary",
+    title: "API Key",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// With description
+// ---------------------------------------------------------------------------
+
+export const WithDescription: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Workspace Name",
+    description: "The name displayed across your organization.",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// With icon
+// ---------------------------------------------------------------------------
+
+export const WithIcon: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Settings",
+    icon: SvgSettings,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Optional
+// ---------------------------------------------------------------------------
+
+export const Optional: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Phone Number",
+    optional: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Aux icons
+// ---------------------------------------------------------------------------
+
+export const AuxInfoGray: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Connection Status",
+    auxIcon: "info-gray",
+  },
+};
+
+export const AuxWarning: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Rate Limit",
+    auxIcon: "warning",
+  },
+};
+
+export const AuxError: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "API Key",
+    auxIcon: "error",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// With tag
+// ---------------------------------------------------------------------------
+
+export const WithTag: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Knowledge Graph",
+    tag: { title: "Beta", color: "blue" },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Editable
+// ---------------------------------------------------------------------------
+
+export const Editable: Story = {
+  args: {
+    sizePreset: "main-ui",
+    title: "Click to edit",
+    editable: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Combined
+// ---------------------------------------------------------------------------
+
+export const FullFeatured: Story = {
+  args: {
+    sizePreset: "main-content",
+    title: "Custom Field",
+    icon: SvgStar,
+    description: "A custom field with all extras enabled.",
+    optional: true,
+    auxIcon: "info-blue",
+    tag: { title: "New", color: "green" },
+    editable: true,
+  },
+};
diff --git a/web/lib/opal/src/layouts/ContentAction/ContentAction.stories.tsx b/web/lib/opal/src/layouts/ContentAction/ContentAction.stories.tsx
new file mode 100644
index 00000000000..96433c95475
--- /dev/null
+++ b/web/lib/opal/src/layouts/ContentAction/ContentAction.stories.tsx
@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ContentAction } from "@opal/layouts";
+import { Button } from "@opal/components";
+import { SvgSettings } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import type { Decorator } from "@storybook/react";
+
+const withTooltipProvider: Decorator = (Story) => (
+  <TooltipPrimitive.Provider>
+    <Story />
+  </TooltipPrimitive.Provider>
+);
+
+const meta = {
+  title: "Layouts/ContentAction",
+  component: ContentAction,
+  tags: ["autodocs"],
+  decorators: [withTooltipProvider],
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof ContentAction>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "OpenAI",
+    description: "GPT-4o language model provider.",
+    icon: SvgSettings,
+    rightChildren: <Button prominence="tertiary">Edit</Button>,
+  },
+};
+
+export const MultipleActions: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "Connector",
+    description: "Manage your data source connector.",
+    rightChildren: (
+      <div className="flex items-center gap-2">
+        <Button prominence="tertiary" icon={SvgSettings} />
+        <Button variant="danger" prominence="primary">
+          Delete
+        </Button>
+      </div>
+    ),
+  },
+};
+
+export const NoPadding: Story = {
+  args: {
+    sizePreset: "main-content",
+    variant: "section",
+    title: "Compact Row",
+    description: "No padding around content area.",
+    paddingVariant: "fit",
+    rightChildren: <Button prominence="tertiary">Action</Button>,
+  },
+};
diff --git a/web/lib/opal/src/layouts/IllustrationContent/IllustrationContent.stories.tsx b/web/lib/opal/src/layouts/IllustrationContent/IllustrationContent.stories.tsx
new file mode 100644
index 00000000000..8ce18eaadfe
--- /dev/null
+++ b/web/lib/opal/src/layouts/IllustrationContent/IllustrationContent.stories.tsx
@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { IllustrationContent } from "@opal/layouts";
+import { SvgEmpty } from "@opal/illustrations";
+
+const meta = {
+  title: "Layouts/IllustrationContent",
+  component: IllustrationContent,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+} satisfies Meta<typeof IllustrationContent>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  args: {
+    illustration: SvgEmpty,
+    title: "No results found",
+    description: "Try adjusting your search or filters to find what you need.",
+  },
+};
+
+export const TitleOnly: Story = {
+  args: {
+    title: "Nothing here yet",
+  },
+};
+
+export const NoIllustration: Story = {
+  args: {
+    title: "No documents available",
+    description:
+      "Connect a data source to start indexing documents into your workspace.",
+  },
+};
diff --git a/web/src/refresh-components/Attachment.stories.tsx b/web/src/refresh-components/Attachment.stories.tsx
new file mode 100644
index 00000000000..3d4775f1ff8
--- /dev/null
+++ b/web/src/refresh-components/Attachment.stories.tsx
@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Attachment from "./Attachment";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Attachment> = {
+  title: "refresh-components/Attachment",
+  component: Attachment,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Attachment>;
+
+export const Default: Story = {
+  args: {
+    fileName: "quarterly-report.pdf",
+  },
+};
+
+export const WithOpenAction: Story = {
+  args: {
+    fileName: "meeting-notes.docx",
+    open: () => alert("Opening document"),
+  },
+};
+
+export const LongFileName: Story = {
+  args: {
+    fileName:
+      "very-long-document-name-that-might-overflow-the-container-2024-Q4-final-draft.pdf",
+  },
+};
diff --git a/web/src/refresh-components/Calendar.stories.tsx b/web/src/refresh-components/Calendar.stories.tsx
new file mode 100644
index 00000000000..1280dbf5811
--- /dev/null
+++ b/web/src/refresh-components/Calendar.stories.tsx
@@ -0,0 +1,64 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Calendar from "./Calendar";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import type { DateRange } from "react-day-picker";
+
+const meta: Meta<typeof Calendar> = {
+  title: "refresh-components/Calendar",
+  component: Calendar,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+
+// ---------------------------------------------------------------------------
+// Single selection
+// ---------------------------------------------------------------------------
+
+function SingleSelectDemo() {
+  const [selected, setSelected] = React.useState<Date | undefined>(new Date());
+  return <Calendar mode="single" selected={selected} onSelect={setSelected} />;
+}
+
+export const SingleSelect: Story = {
+  render: () => <SingleSelectDemo />,
+};
+
+// ---------------------------------------------------------------------------
+// Range selection
+// ---------------------------------------------------------------------------
+
+function RangeSelectDemo() {
+  const [range, setRange] = React.useState<DateRange | undefined>({
+    from: new Date(2025, 2, 10),
+    to: new Date(2025, 2, 20),
+  });
+  return <Calendar mode="range" selected={range} onSelect={setRange} />;
+}
+
+export const RangeSelect: Story = {
+  render: () => <RangeSelectDemo />,
+};
+
+// ---------------------------------------------------------------------------
+// Without outside days
+// ---------------------------------------------------------------------------
+
+export const NoOutsideDays: Story = {
+  args: {
+    mode: "single",
+    showOutsideDays: false,
+  },
+};
diff --git a/web/src/refresh-components/CharacterCount.stories.tsx b/web/src/refresh-components/CharacterCount.stories.tsx
new file mode 100644
index 00000000000..58275abcc9d
--- /dev/null
+++ b/web/src/refresh-components/CharacterCount.stories.tsx
@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import CharacterCount from "./CharacterCount";
+
+const meta: Meta<typeof CharacterCount> = {
+  title: "refresh-components/CharacterCount",
+  component: CharacterCount,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CharacterCount>;
+
+export const UnderLimit: Story = {
+  args: {
+    value: "Hello world",
+    limit: 100,
+  },
+};
+
+export const NearLimit: Story = {
+  args: {
+    value: "A".repeat(95),
+    limit: 100,
+  },
+};
+
+export const AtLimit: Story = {
+  args: {
+    value: "A".repeat(100),
+    limit: 100,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    value: "",
+    limit: 256,
+  },
+};
diff --git a/web/src/refresh-components/Chip.stories.tsx b/web/src/refresh-components/Chip.stories.tsx
new file mode 100644
index 00000000000..3451e13839b
--- /dev/null
+++ b/web/src/refresh-components/Chip.stories.tsx
@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Chip from "./Chip";
+import { SvgUser } from "@opal/icons";
+
+const meta: Meta<typeof Chip> = {
+  title: "refresh-components/Chip",
+  component: Chip,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Chip>;
+
+export const Default: Story = {
+  args: {
+    children: "Tag Name",
+  },
+};
+
+export const WithIcon: Story = {
+  args: {
+    children: "John Doe",
+    icon: SvgUser,
+  },
+};
+
+export const Removable: Story = {
+  args: {
+    children: "Removable Tag",
+    onRemove: () => alert("Removed!"),
+  },
+};
+
+export const WithIconAndRemove: Story = {
+  args: {
+    children: "Jane Smith",
+    icon: SvgUser,
+    onRemove: () => alert("Removed!"),
+  },
+};
diff --git a/web/src/refresh-components/Code.stories.tsx b/web/src/refresh-components/Code.stories.tsx
new file mode 100644
index 00000000000..42c8b6159ea
--- /dev/null
+++ b/web/src/refresh-components/Code.stories.tsx
@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import Code from "./Code";
+
+const meta: Meta<typeof Code> = {
+  title: "refresh-components/Code",
+  component: Code,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Code>;
+
+export const Default: Story = {
+  args: {
+    children: `const greeting = "Hello, world!";\nconsole.log(greeting);`,
+  },
+};
+
+export const WithoutCopyButton: Story = {
+  args: {
+    children: `npm install @onyx/sdk`,
+    showCopyButton: false,
+  },
+};
+
+export const MultiLine: Story = {
+  args: {
+    children: `function fibonacci(n: number): number {
+  if (n <= 1) return n;
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+console.log(fibonacci(10));`,
+  },
+};
diff --git a/web/src/refresh-components/Collapsible.stories.tsx b/web/src/refresh-components/Collapsible.stories.tsx
new file mode 100644
index 00000000000..45bec229a41
--- /dev/null
+++ b/web/src/refresh-components/Collapsible.stories.tsx
@@ -0,0 +1,99 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from "./Collapsible";
+
+const meta: Meta<typeof Collapsible> = {
+  title: "refresh-components/Collapsible",
+  component: Collapsible,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Collapsible>;
+
+export const Default: Story = {
+  render: () => (
+    <Collapsible defaultOpen={false}>
+      <CollapsibleTrigger asChild>
+        <button className="p-2 bg-background-tint-03 rounded-08 font-main-ui-action w-full text-left">
+          Click to toggle
+        </button>
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <div className="p-4 border border-border-01 rounded-08 mt-2">
+          This content can be expanded and collapsed with a smooth animation.
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  ),
+};
+
+export const DefaultOpen: Story = {
+  render: () => (
+    <Collapsible defaultOpen>
+      <CollapsibleTrigger asChild>
+        <button className="p-2 bg-background-tint-03 rounded-08 font-main-ui-action w-full text-left">
+          Already open — click to close
+        </button>
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <div className="p-4 border border-border-01 rounded-08 mt-2">
+          This section starts open by default.
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  ),
+};
+
+function ControlledDemo() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ width: 320 }}>
+      <Collapsible open={open} onOpenChange={setOpen}>
+        <CollapsibleTrigger asChild>
+          <button className="p-2 bg-background-tint-03 rounded-08 font-main-ui-action w-full text-left">
+            {open ? "Close" : "Open"} (controlled)
+          </button>
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="p-4 border border-border-01 rounded-08 mt-2">
+            Controlled collapsible content. Current state:{" "}
+            {open ? "open" : "closed"}.
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  );
+}
+
+export const Controlled: Story = {
+  render: () => <ControlledDemo />,
+};
+
+export const MultipleCollapsibles: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2" style={{ width: 320 }}>
+      {["Section A", "Section B", "Section C"].map((title) => (
+        <Collapsible key={title}>
+          <CollapsibleTrigger asChild>
+            <button className="p-2 bg-background-tint-03 rounded-08 font-main-ui-action w-full text-left">
+              {title}
+            </button>
+          </CollapsibleTrigger>
+          <CollapsibleContent>
+            <div className="p-4 border border-border-01 rounded-08 mt-1">
+              Content for {title}
+            </div>
+          </CollapsibleContent>
+        </Collapsible>
+      ))}
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/ColorSwatch.stories.tsx b/web/src/refresh-components/ColorSwatch.stories.tsx
new file mode 100644
index 00000000000..a057212c8f1
--- /dev/null
+++ b/web/src/refresh-components/ColorSwatch.stories.tsx
@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ColorSwatch from "./ColorSwatch";
+
+const meta: Meta<typeof ColorSwatch> = {
+  title: "refresh-components/ColorSwatch",
+  component: ColorSwatch,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ColorSwatch>;
+
+export const Light: Story = {
+  args: {
+    light: true,
+  },
+};
+
+export const Dark: Story = {
+  args: {
+    dark: true,
+  },
+};
+
+export const SideBySide: Story = {
+  render: () => (
+    <div className="flex gap-4 items-center">
+      <ColorSwatch light />
+      <ColorSwatch dark />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/ConnectionProviderIcon.stories.tsx b/web/src/refresh-components/ConnectionProviderIcon.stories.tsx
new file mode 100644
index 00000000000..c6b738f8e7f
--- /dev/null
+++ b/web/src/refresh-components/ConnectionProviderIcon.stories.tsx
@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ConnectionProviderIcon from "./ConnectionProviderIcon";
+import { SvgSettings, SvgStar } from "@opal/icons";
+
+const meta: Meta<typeof ConnectionProviderIcon> = {
+  title: "refresh-components/ConnectionProviderIcon",
+  component: ConnectionProviderIcon,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ConnectionProviderIcon>;
+
+export const WithSettingsIcon: Story = {
+  args: {
+    icon: <SvgSettings className="w-5 h-5 stroke-text-04" />,
+  },
+};
+
+export const WithStarIcon: Story = {
+  args: {
+    icon: <SvgStar className="w-5 h-5 stroke-text-04" />,
+  },
+};
+
+export const WithCustomEmoji: Story = {
+  args: {
+    icon: <span className="text-lg">📄</span>,
+  },
+};
diff --git a/web/src/refresh-components/Divider.stories.tsx b/web/src/refresh-components/Divider.stories.tsx
new file mode 100644
index 00000000000..dd582933587
--- /dev/null
+++ b/web/src/refresh-components/Divider.stories.tsx
@@ -0,0 +1,90 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Divider from "./Divider";
+import { SvgSettings } from "@opal/icons";
+
+const meta: Meta<typeof Divider> = {
+  title: "refresh-components/Divider",
+  component: Divider,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Divider>;
+
+export const SimpleLine: Story = {
+  args: {},
+};
+
+export const WithTitle: Story = {
+  args: {
+    showTitle: true,
+    text: "Section Title",
+  },
+};
+
+export const WithTitleAndDescription: Story = {
+  args: {
+    showTitle: true,
+    text: "Advanced Settings",
+    description: "Configure additional options for this section.",
+    showDescription: true,
+  },
+};
+
+export const WithInfoText: Story = {
+  args: {
+    showTitle: true,
+    text: "Items",
+    infoText: "3 items",
+    showInfo: true,
+  },
+};
+
+function FoldableDividerDemo() {
+  const [expanded, setExpanded] = React.useState(false);
+  return (
+    <div style={{ width: 400 }}>
+      <Divider
+        showTitle
+        text="Click to toggle"
+        foldable
+        expanded={expanded}
+        onClick={() => setExpanded(!expanded)}
+      />
+      {expanded && (
+        <div style={{ padding: 12 }}>Expanded content goes here.</div>
+      )}
+    </div>
+  );
+}
+
+export const Foldable: Story = {
+  render: () => <FoldableDividerDemo />,
+};
+
+export const WithIcon: Story = {
+  args: {
+    showTitle: true,
+    text: "Settings",
+    icon: SvgSettings,
+  },
+};
+
+export const Highlighted: Story = {
+  args: {
+    showTitle: true,
+    text: "Active Section",
+    foldable: true,
+    expanded: false,
+    isHighlighted: true,
+  },
+};
+
+export const NoDividerLine: Story = {
+  args: {
+    showTitle: true,
+    text: "No Lines",
+    dividerLine: false,
+  },
+};
diff --git a/web/src/refresh-components/EmptyMessage.stories.tsx b/web/src/refresh-components/EmptyMessage.stories.tsx
new file mode 100644
index 00000000000..a080d774001
--- /dev/null
+++ b/web/src/refresh-components/EmptyMessage.stories.tsx
@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import EmptyMessage from "./EmptyMessage";
+import { SvgFileText, SvgUsers } from "@opal/icons";
+
+const meta: Meta<typeof EmptyMessage> = {
+  title: "refresh-components/messages/EmptyMessage",
+  component: EmptyMessage,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof EmptyMessage>;
+
+export const Default: Story = {
+  args: {
+    title: "No items found",
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    title: "No connectors configured",
+    description:
+      "Set up a connector to start indexing documents from your data sources.",
+  },
+};
+
+export const WithCustomIcon: Story = {
+  args: {
+    icon: SvgFileText,
+    title: "No documents available",
+    description: "Upload documents or connect a data source to get started.",
+  },
+};
+
+export const UsersEmpty: Story = {
+  args: {
+    icon: SvgUsers,
+    title: "No users in this group",
+    description: "Add users to this group to grant them access.",
+  },
+};
diff --git a/web/src/refresh-components/EnabledCount.stories.tsx b/web/src/refresh-components/EnabledCount.stories.tsx
new file mode 100644
index 00000000000..87965cdc178
--- /dev/null
+++ b/web/src/refresh-components/EnabledCount.stories.tsx
@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import EnabledCount from "./EnabledCount";
+
+const meta: Meta<typeof EnabledCount> = {
+  title: "refresh-components/EnabledCount",
+  component: EnabledCount,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof EnabledCount>;
+
+export const Default: Story = {
+  args: {
+    enabledCount: 5,
+    totalCount: 12,
+  },
+};
+
+export const WithName: Story = {
+  args: {
+    name: "connector",
+    enabledCount: 3,
+    totalCount: 10,
+  },
+};
+
+export const AllEnabled: Story = {
+  args: {
+    name: "source",
+    enabledCount: 8,
+    totalCount: 8,
+  },
+};
+
+export const NoneEnabled: Story = {
+  args: {
+    name: "item",
+    enabledCount: 0,
+    totalCount: 15,
+  },
+};
+
+export const SingleItem: Story = {
+  args: {
+    name: "document",
+    enabledCount: 1,
+    totalCount: 1,
+  },
+};
diff --git a/web/src/refresh-components/FadingEdgeContainer.stories.tsx b/web/src/refresh-components/FadingEdgeContainer.stories.tsx
new file mode 100644
index 00000000000..8a2e30b409e
--- /dev/null
+++ b/web/src/refresh-components/FadingEdgeContainer.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import FadingEdgeContainer from "./FadingEdgeContainer";
+
+const meta: Meta<typeof FadingEdgeContainer> = {
+  title: "refresh-components/FadingEdgeContainer",
+  component: FadingEdgeContainer,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FadingEdgeContainer>;
+
+const sampleItems = Array.from({ length: 20 }, (_, i) => (
+  <div key={i} className="p-2 border-b border-border-01">
+    Item {i + 1}
+  </div>
+));
+
+export const BottomFade: Story = {
+  args: {
+    direction: "bottom",
+    className: "max-h-[200px] overflow-y-auto",
+    children: sampleItems,
+  },
+};
+
+export const TopFade: Story = {
+  args: {
+    direction: "top",
+    className: "max-h-[200px] overflow-y-auto",
+    children: sampleItems,
+  },
+};
+
+export const CustomFadeHeight: Story = {
+  args: {
+    direction: "bottom",
+    className: "max-h-[200px] overflow-y-auto",
+    fadeClassName: "h-16",
+    children: sampleItems,
+  },
+};
diff --git a/web/src/refresh-components/FrostedDiv.stories.tsx b/web/src/refresh-components/FrostedDiv.stories.tsx
new file mode 100644
index 00000000000..41fb85731ee
--- /dev/null
+++ b/web/src/refresh-components/FrostedDiv.stories.tsx
@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import FrostedDiv from "./FrostedDiv";
+
+const meta: Meta<typeof FrostedDiv> = {
+  title: "refresh-components/FrostedDiv",
+  component: FrostedDiv,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <div
+        className="p-12"
+        style={{
+          background:
+            "linear-gradient(135deg, #667eea 0%, #764ba2 50%, #f093fb 100%)",
+        }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof FrostedDiv>;
+
+export const Default: Story = {
+  args: {
+    className: "p-4",
+    children: (
+      <span className="text-text-04 font-main-ui-action">
+        Frosted glass content
+      </span>
+    ),
+  },
+};
+
+export const CustomBlur: Story = {
+  args: {
+    blur: "30px",
+    backdropBlur: "10px",
+    className: "p-6",
+    children: (
+      <span className="text-text-04 font-main-ui-action">
+        Heavy blur effect
+      </span>
+    ),
+  },
+};
+
+export const CustomBorderRadius: Story = {
+  args: {
+    borderRadius: "0.5rem",
+    className: "p-4",
+    children: (
+      <span className="text-text-04 font-main-ui-action">Rounded corners</span>
+    ),
+  },
+};
diff --git a/web/src/refresh-components/InlineExternalLink.stories.tsx b/web/src/refresh-components/InlineExternalLink.stories.tsx
new file mode 100644
index 00000000000..491956c9342
--- /dev/null
+++ b/web/src/refresh-components/InlineExternalLink.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import InlineExternalLink from "./InlineExternalLink";
+
+const meta: Meta<typeof InlineExternalLink> = {
+  title: "refresh-components/InlineExternalLink",
+  component: InlineExternalLink,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof InlineExternalLink>;
+
+export const Default: Story = {
+  args: {
+    href: "https://docs.onyx.app",
+    children: "Onyx Documentation",
+  },
+};
+
+export const CustomClassName: Story = {
+  args: {
+    href: "https://github.com/onyx-dot-app/onyx",
+    children: "GitHub Repository",
+    className: "text-action-link-05 underline hover:opacity-80",
+  },
+};
+
+export const InContext: Story = {
+  render: () => (
+    <p className="font-main-content-body text-text-04">
+      For more information, visit the{" "}
+      <InlineExternalLink href="https://docs.onyx.app">
+        official documentation
+      </InlineExternalLink>{" "}
+      or check out the{" "}
+      <InlineExternalLink href="https://github.com/onyx-dot-app/onyx">
+        source code
+      </InlineExternalLink>
+      .
+    </p>
+  ),
+};
diff --git a/web/src/refresh-components/Modal.stories.tsx b/web/src/refresh-components/Modal.stories.tsx
new file mode 100644
index 00000000000..63bc37736d2
--- /dev/null
+++ b/web/src/refresh-components/Modal.stories.tsx
@@ -0,0 +1,179 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Modal from "./Modal";
+import { Button } from "@opal/components";
+import { SvgInfoSmall } from "@opal/icons";
+
+const meta: Meta<typeof Modal> = {
+  title: "refresh-components/Modal",
+  component: Modal,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Modal>;
+
+function ModalDemo() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ padding: 32 }}>
+      <Button onClick={() => setOpen(true)}>Open Modal</Button>
+      <Modal open={open} onOpenChange={setOpen}>
+        <Modal.Content width="sm" height="fit">
+          <Modal.Header
+            icon={SvgInfoSmall}
+            title="Example Modal"
+            description="This is a demo modal with header, body, and footer."
+            onClose={() => setOpen(false)}
+          />
+          <Modal.Body>
+            <div style={{ padding: 16 }}>
+              Some body content goes here. You can put forms, text, or anything
+              else inside the modal body.
+            </div>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button
+              variant="default"
+              prominence="secondary"
+              onClick={() => setOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant="action"
+              prominence="primary"
+              onClick={() => setOpen(false)}
+            >
+              Confirm
+            </Button>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <ModalDemo />,
+};
+
+function LargeModalDemo() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ padding: 32 }}>
+      <Button onClick={() => setOpen(true)}>Open Large Modal</Button>
+      <Modal open={open} onOpenChange={setOpen}>
+        <Modal.Content width="lg" height="full">
+          <Modal.Header
+            icon={SvgInfoSmall}
+            title="Large Modal"
+            description="A large modal with full height."
+            onClose={() => setOpen(false)}
+          />
+          <Modal.Body>
+            <div style={{ padding: 16 }}>
+              {Array.from({ length: 20 }, (_, i) => (
+                <p key={i} style={{ marginBottom: 12 }}>
+                  Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur
+                  adipiscing elit. Sed do eiusmod tempor incididunt ut labore et
+                  dolore magna aliqua.
+                </p>
+              ))}
+            </div>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button
+              variant="default"
+              prominence="secondary"
+              onClick={() => setOpen(false)}
+            >
+              Close
+            </Button>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal>
+    </div>
+  );
+}
+
+export const Large: Story = {
+  render: () => <LargeModalDemo />,
+};
+
+function GrayBackgroundDemo() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ padding: 32 }}>
+      <Button onClick={() => setOpen(true)}>Open Gray Modal</Button>
+      <Modal open={open} onOpenChange={setOpen}>
+        <Modal.Content width="sm" height="fit" background="gray">
+          <Modal.Header
+            icon={SvgInfoSmall}
+            title="Gray Background"
+            description="This modal uses background='gray' for a tinted card."
+            onClose={() => setOpen(false)}
+          />
+          <Modal.Body>
+            <div style={{ padding: 16 }}>
+              The modal card background uses the tinted color variant.
+            </div>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button
+              variant="default"
+              prominence="secondary"
+              onClick={() => setOpen(false)}
+            >
+              Close
+            </Button>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal>
+    </div>
+  );
+}
+
+export const GrayBackground: Story = {
+  render: () => <GrayBackgroundDemo />,
+};
+
+function NoOverlayDemo() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ padding: 32 }}>
+      <Button onClick={() => setOpen(true)}>Open Without Overlay</Button>
+      <Modal open={open} onOpenChange={setOpen}>
+        <Modal.Content width="sm" height="fit" skipOverlay>
+          <Modal.Header
+            icon={SvgInfoSmall}
+            title="No Overlay"
+            description="This modal skips the backdrop overlay."
+            onClose={() => setOpen(false)}
+          />
+          <Modal.Body>
+            <div style={{ padding: 16 }}>
+              The page behind remains fully visible with no blur or mask.
+            </div>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button
+              variant="default"
+              prominence="secondary"
+              onClick={() => setOpen(false)}
+            >
+              Close
+            </Button>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal>
+    </div>
+  );
+}
+
+export const NoOverlay: Story = {
+  render: () => <NoOverlayDemo />,
+};
diff --git a/web/src/refresh-components/OverflowDiv.stories.tsx b/web/src/refresh-components/OverflowDiv.stories.tsx
new file mode 100644
index 00000000000..abc62ca7f73
--- /dev/null
+++ b/web/src/refresh-components/OverflowDiv.stories.tsx
@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import OverflowDiv from "./OverflowDiv";
+
+const meta: Meta<typeof OverflowDiv> = {
+  title: "refresh-components/OverflowDiv",
+  component: OverflowDiv,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof OverflowDiv>;
+
+const sampleItems = Array.from({ length: 25 }, (_, i) => (
+  <div key={i} className="p-2 border-b border-border-01">
+    Sidebar item {i + 1}
+  </div>
+));
+
+export const Default: Story = {
+  args: {
+    style: { width: 260, height: 300 },
+    children: sampleItems,
+  },
+};
+
+export const MaskDisabled: Story = {
+  args: {
+    disableMask: true,
+    style: { width: 260, height: 300 },
+    children: sampleItems,
+  },
+};
+
+export const CustomHeight: Story = {
+  args: {
+    height: "4rem",
+    style: { width: 260, height: 300 },
+    children: sampleItems,
+  },
+};
diff --git a/web/src/refresh-components/Pagination.stories.tsx b/web/src/refresh-components/Pagination.stories.tsx
new file mode 100644
index 00000000000..4d66685a1f8
--- /dev/null
+++ b/web/src/refresh-components/Pagination.stories.tsx
@@ -0,0 +1,57 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Pagination from "./Pagination";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Pagination> = {
+  title: "refresh-components/Pagination",
+  component: Pagination,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Pagination>;
+
+function PaginationDemo({
+  totalPages,
+  initialPage = 1,
+}: {
+  totalPages: number;
+  initialPage?: number;
+}) {
+  const [page, setPage] = React.useState(initialPage);
+  return (
+    <Pagination
+      currentPage={page}
+      totalPages={totalPages}
+      onPageChange={setPage}
+    />
+  );
+}
+
+export const Default: Story = {
+  render: () => <PaginationDemo totalPages={10} />,
+};
+
+export const FewPages: Story = {
+  render: () => <PaginationDemo totalPages={5} />,
+};
+
+export const ManyPages: Story = {
+  render: () => <PaginationDemo totalPages={50} initialPage={25} />,
+};
+
+export const FirstPage: Story = {
+  render: () => <PaginationDemo totalPages={20} initialPage={1} />,
+};
+
+export const LastPage: Story = {
+  render: () => <PaginationDemo totalPages={20} initialPage={20} />,
+};
diff --git a/web/src/refresh-components/Popover.stories.tsx b/web/src/refresh-components/Popover.stories.tsx
new file mode 100644
index 00000000000..3a629d48064
--- /dev/null
+++ b/web/src/refresh-components/Popover.stories.tsx
@@ -0,0 +1,88 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Popover from "./Popover";
+import { Button } from "@opal/components";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Popover> = {
+  title: "refresh-components/Popover",
+  component: Popover,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Popover>;
+
+export const Default: Story = {
+  render: () => (
+    <Popover>
+      <Popover.Trigger asChild>
+        <Button>Open Popover</Button>
+      </Popover.Trigger>
+      <Popover.Content>
+        <div style={{ padding: 8 }}>
+          <p>Popover content goes here.</p>
+        </div>
+      </Popover.Content>
+    </Popover>
+  ),
+};
+
+export const WidthVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 16 }}>
+      {(["fit", "md", "lg", "xl"] as const).map((width) => (
+        <Popover key={width}>
+          <Popover.Trigger asChild>
+            <Button prominence="secondary">{width}</Button>
+          </Popover.Trigger>
+          <Popover.Content width={width}>
+            <div style={{ padding: 8 }}>
+              <p>Width: {width}</p>
+            </div>
+          </Popover.Content>
+        </Popover>
+      ))}
+    </div>
+  ),
+};
+
+export const WithMenu: Story = {
+  render: () => (
+    <Popover>
+      <Popover.Trigger asChild>
+        <Button>Options</Button>
+      </Popover.Trigger>
+      <Popover.Content width="lg">
+        <Popover.Menu>
+          <Popover.Close asChild>
+            <Button prominence="tertiary" width="full">
+              Edit
+            </Button>
+          </Popover.Close>
+          <Popover.Close asChild>
+            <Button prominence="tertiary" width="full">
+              Duplicate
+            </Button>
+          </Popover.Close>
+          {null}
+          <Popover.Close asChild>
+            <Button variant="danger" prominence="tertiary" width="full">
+              Delete
+            </Button>
+          </Popover.Close>
+        </Popover.Menu>
+      </Popover.Content>
+    </Popover>
+  ),
+};
diff --git a/web/src/refresh-components/PreviewImage.stories.tsx b/web/src/refresh-components/PreviewImage.stories.tsx
new file mode 100644
index 00000000000..641448cf681
--- /dev/null
+++ b/web/src/refresh-components/PreviewImage.stories.tsx
@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import PreviewImage from "./PreviewImage";
+
+const meta: Meta<typeof PreviewImage> = {
+  title: "refresh-components/PreviewImage",
+  component: PreviewImage,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PreviewImage>;
+
+export const Default: Story = {
+  args: {
+    src: "https://placehold.co/400x300/EEE/31343C?text=Preview+Image",
+    alt: "Sample preview image",
+  },
+};
+
+export const WithCustomClass: Story = {
+  args: {
+    src: "https://placehold.co/200x200/EEE/31343C?text=Square",
+    alt: "Square preview",
+    className: "w-[200px] h-[200px] rounded-12",
+  },
+};
+
+export const Landscape: Story = {
+  args: {
+    src: "https://placehold.co/600x200/EEE/31343C?text=Landscape",
+    alt: "Landscape preview",
+    className: "max-w-[400px]",
+  },
+};
diff --git a/web/src/refresh-components/ScrollIndicatorDiv.stories.tsx b/web/src/refresh-components/ScrollIndicatorDiv.stories.tsx
new file mode 100644
index 00000000000..7139d86fc61
--- /dev/null
+++ b/web/src/refresh-components/ScrollIndicatorDiv.stories.tsx
@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ScrollIndicatorDiv from "./ScrollIndicatorDiv";
+
+const meta: Meta<typeof ScrollIndicatorDiv> = {
+  title: "refresh-components/ScrollIndicatorDiv",
+  component: ScrollIndicatorDiv,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ScrollIndicatorDiv>;
+
+const sampleItems = Array.from({ length: 30 }, (_, i) => (
+  <div key={i} className="p-2 border-b border-border-01">
+    Scrollable item {i + 1}
+  </div>
+));
+
+export const GradientVariant: Story = {
+  args: {
+    variant: "gradient",
+    style: { width: 300, height: 250 },
+    children: sampleItems,
+  },
+};
+
+export const ShadowVariant: Story = {
+  args: {
+    variant: "shadow",
+    style: { width: 300, height: 250 },
+    children: sampleItems,
+  },
+};
+
+export const DisabledIndicators: Story = {
+  args: {
+    disableIndicators: true,
+    style: { width: 300, height: 250 },
+    children: sampleItems,
+  },
+};
+
+export const WithBottomSpacing: Story = {
+  args: {
+    variant: "gradient",
+    bottomSpacing: "2rem",
+    style: { width: 300, height: 250 },
+    children: sampleItems,
+  },
+};
diff --git a/web/src/refresh-components/Separator.stories.tsx b/web/src/refresh-components/Separator.stories.tsx
new file mode 100644
index 00000000000..b97f151e39b
--- /dev/null
+++ b/web/src/refresh-components/Separator.stories.tsx
@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Separator from "./Separator";
+
+const meta: Meta<typeof Separator> = {
+  title: "refresh-components/Separator",
+  component: Separator,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Separator>;
+
+export const Horizontal: Story = {
+  decorators: [
+    (Story) => (
+      <div style={{ width: 400 }}>
+        <div>Content above</div>
+        <Story />
+        <div>Content below</div>
+      </div>
+    ),
+  ],
+};
+
+export const Vertical: Story = {
+  args: {
+    orientation: "vertical",
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ display: "flex", alignItems: "center", height: 60 }}>
+        <span>Left</span>
+        <Story />
+        <span>Right</span>
+      </div>
+    ),
+  ],
+};
+
+export const NoPadding: Story = {
+  args: {
+    noPadding: true,
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 400 }}>
+        <div>No padding above</div>
+        <Story />
+        <div>No padding below</div>
+      </div>
+    ),
+  ],
+};
diff --git a/web/src/refresh-components/ShadowDiv.stories.tsx b/web/src/refresh-components/ShadowDiv.stories.tsx
new file mode 100644
index 00000000000..8f4d7304a04
--- /dev/null
+++ b/web/src/refresh-components/ShadowDiv.stories.tsx
@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ShadowDiv from "./ShadowDiv";
+
+const meta: Meta<typeof ShadowDiv> = {
+  title: "refresh-components/ShadowDiv",
+  component: ShadowDiv,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ShadowDiv>;
+
+const sampleItems = Array.from({ length: 30 }, (_, i) => (
+  <div key={i} className="p-2 border-b border-border-01">
+    Scrollable item {i + 1}
+  </div>
+));
+
+export const Default: Story = {
+  args: {
+    className: "max-h-[250px]",
+    style: { width: 300 },
+    children: sampleItems,
+  },
+};
+
+export const BottomOnly: Story = {
+  args: {
+    bottomOnly: true,
+    className: "max-h-[250px]",
+    style: { width: 300 },
+    children: sampleItems,
+  },
+};
+
+export const TopOnly: Story = {
+  args: {
+    topOnly: true,
+    className: "max-h-[250px]",
+    style: { width: 300 },
+    children: sampleItems,
+  },
+};
+
+export const CustomShadowHeight: Story = {
+  args: {
+    shadowHeight: "3rem",
+    className: "max-h-[250px]",
+    style: { width: 300 },
+    children: sampleItems,
+  },
+};
diff --git a/web/src/refresh-components/SimpleCollapsible.stories.tsx b/web/src/refresh-components/SimpleCollapsible.stories.tsx
new file mode 100644
index 00000000000..ff5a16129b5
--- /dev/null
+++ b/web/src/refresh-components/SimpleCollapsible.stories.tsx
@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import SimpleCollapsible from "./SimpleCollapsible";
+
+const meta: Meta<typeof SimpleCollapsible> = {
+  title: "refresh-components/SimpleCollapsible",
+  component: SimpleCollapsible,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof SimpleCollapsible>;
+
+export const DefaultOpen: Story = {
+  render: () => (
+    <SimpleCollapsible>
+      <SimpleCollapsible.Header
+        title="Section Title"
+        description="This section is open by default."
+      />
+      <SimpleCollapsible.Content>
+        <div>Here is some collapsible content that starts expanded.</div>
+      </SimpleCollapsible.Content>
+    </SimpleCollapsible>
+  ),
+};
+
+export const DefaultClosed: Story = {
+  render: () => (
+    <SimpleCollapsible defaultOpen={false}>
+      <SimpleCollapsible.Header
+        title="Initially Closed"
+        description="Click the button to expand this section."
+      />
+      <SimpleCollapsible.Content>
+        <div>This content was hidden until you clicked expand.</div>
+      </SimpleCollapsible.Content>
+    </SimpleCollapsible>
+  ),
+};
+
+export const TitleOnly: Story = {
+  render: () => (
+    <SimpleCollapsible>
+      <SimpleCollapsible.Header title="No Description" />
+      <SimpleCollapsible.Content>
+        <div>Content with a header that has no description.</div>
+      </SimpleCollapsible.Content>
+    </SimpleCollapsible>
+  ),
+};
diff --git a/web/src/refresh-components/SimplePopover.stories.tsx b/web/src/refresh-components/SimplePopover.stories.tsx
new file mode 100644
index 00000000000..0ebe6fa3584
--- /dev/null
+++ b/web/src/refresh-components/SimplePopover.stories.tsx
@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SimplePopover from "./SimplePopover";
+import { Button } from "@opal/components";
+import Text from "@/refresh-components/texts/Text";
+
+const meta: Meta<typeof SimplePopover> = {
+  title: "refresh-components/modals/SimplePopover",
+  component: SimplePopover,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SimplePopover>;
+
+export const Default: Story = {
+  args: {
+    trigger: <Button>Open Popover</Button>,
+    children: (
+      <div style={{ padding: 16 }}>
+        <Text mainUiBody text04>
+          Popover content goes here.
+        </Text>
+      </div>
+    ),
+  },
+};
+
+export const WithRenderPropTrigger: Story = {
+  args: {
+    trigger: (open: boolean) => (
+      <Button>{`${open ? "Close" : "Open"} Popover`}</Button>
+    ),
+    children: (
+      <div style={{ padding: 16 }}>
+        <Text mainUiBody text04>
+          The trigger updates its label based on open state.
+        </Text>
+      </div>
+    ),
+  },
+};
diff --git a/web/src/refresh-components/SimpleTabs.stories.tsx b/web/src/refresh-components/SimpleTabs.stories.tsx
new file mode 100644
index 00000000000..e4fd90cc4e8
--- /dev/null
+++ b/web/src/refresh-components/SimpleTabs.stories.tsx
@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SimpleTabs from "./SimpleTabs";
+
+const meta: Meta<typeof SimpleTabs> = {
+  title: "refresh-components/SimpleTabs",
+  component: SimpleTabs,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof SimpleTabs>;
+
+export const Default: Story = {
+  args: {
+    tabs: {
+      overview: {
+        name: "Overview",
+        content: <div style={{ padding: 16 }}>Overview content goes here.</div>,
+      },
+      settings: {
+        name: "Settings",
+        content: <div style={{ padding: 16 }}>Settings content goes here.</div>,
+      },
+      activity: {
+        name: "Activity",
+        content: <div style={{ padding: 16 }}>Activity content goes here.</div>,
+      },
+    },
+    defaultValue: "overview",
+  },
+};
+
+export const TwoTabs: Story = {
+  args: {
+    tabs: {
+      users: {
+        name: "Users",
+        content: (
+          <div style={{ padding: 16 }}>User management panel content.</div>
+        ),
+      },
+      groups: {
+        name: "Groups",
+        content: (
+          <div style={{ padding: 16 }}>Group management panel content.</div>
+        ),
+      },
+    },
+    defaultValue: "users",
+  },
+};
+
+export const WithDisabledTab: Story = {
+  args: {
+    tabs: {
+      active: {
+        name: "Active",
+        content: <div style={{ padding: 16 }}>This tab is active.</div>,
+      },
+      disabled: {
+        name: "Disabled",
+        content: <div style={{ padding: 16 }}>You should not see this.</div>,
+        disabled: true,
+      },
+      another: {
+        name: "Another",
+        content: <div style={{ padding: 16 }}>Another tab content.</div>,
+      },
+    },
+    defaultValue: "active",
+  },
+};
diff --git a/web/src/refresh-components/SimpleTooltip.stories.tsx b/web/src/refresh-components/SimpleTooltip.stories.tsx
new file mode 100644
index 00000000000..219c6b16ee5
--- /dev/null
+++ b/web/src/refresh-components/SimpleTooltip.stories.tsx
@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SimpleTooltip from "./SimpleTooltip";
+
+const meta: Meta<typeof SimpleTooltip> = {
+  title: "refresh-components/SimpleTooltip",
+  component: SimpleTooltip,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SimpleTooltip>;
+
+export const Default: Story = {
+  args: {
+    tooltip: "This is a tooltip",
+    children: <button>Hover me</button>,
+  },
+};
+
+export const SideVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 24, padding: 48 }}>
+      {(["top", "right", "bottom", "left"] as const).map((side) => (
+        <SimpleTooltip key={side} tooltip={`Tooltip on ${side}`} side={side}>
+          <button>{side}</button>
+        </SimpleTooltip>
+      ))}
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    tooltip: "You won't see this",
+    disabled: true,
+    children: <button>Tooltip disabled</button>,
+  },
+};
+
+export const StringChild: Story = {
+  render: () => (
+    <SimpleTooltip>
+      <span>String child auto-tooltips itself</span>
+    </SimpleTooltip>
+  ),
+};
diff --git a/web/src/refresh-components/Spacer.stories.tsx b/web/src/refresh-components/Spacer.stories.tsx
new file mode 100644
index 00000000000..9fd07ac83a1
--- /dev/null
+++ b/web/src/refresh-components/Spacer.stories.tsx
@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Spacer from "./Spacer";
+
+const meta: Meta<typeof Spacer> = {
+  title: "refresh-components/Spacer",
+  component: Spacer,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Spacer>;
+
+export const VerticalDefault: Story = {
+  render: () => (
+    <div className="flex flex-col items-start">
+      <div className="p-2 bg-background-tint-03">Above</div>
+      <Spacer />
+      <div className="p-2 bg-background-tint-03">Below (1rem gap)</div>
+    </div>
+  ),
+};
+
+export const VerticalCustomRem: Story = {
+  render: () => (
+    <div className="flex flex-col items-start">
+      <div className="p-2 bg-background-tint-03">Above</div>
+      <Spacer vertical rem={3} />
+      <div className="p-2 bg-background-tint-03">Below (3rem gap)</div>
+    </div>
+  ),
+};
+
+export const Horizontal: Story = {
+  render: () => (
+    <div className="flex flex-row items-center">
+      <div className="p-2 bg-background-tint-03">Left</div>
+      <Spacer horizontal rem={2} />
+      <div className="p-2 bg-background-tint-03">Right (2rem gap)</div>
+    </div>
+  ),
+};
+
+export const PixelBased: Story = {
+  render: () => (
+    <div className="flex flex-col items-start">
+      <div className="p-2 bg-background-tint-03">Above</div>
+      <Spacer pixels={48} />
+      <div className="p-2 bg-background-tint-03">Below (48px gap)</div>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/Tabs.stories.tsx b/web/src/refresh-components/Tabs.stories.tsx
new file mode 100644
index 00000000000..92633d2a14d
--- /dev/null
+++ b/web/src/refresh-components/Tabs.stories.tsx
@@ -0,0 +1,151 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Tabs from "./Tabs";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import { SvgSettings, SvgStar, SvgRefreshCw } from "@opal/icons";
+
+const meta: Meta<typeof Tabs> = {
+  title: "refresh-components/Tabs",
+  component: Tabs,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Tabs>;
+
+// ---------------------------------------------------------------------------
+// Contained variant (default)
+// ---------------------------------------------------------------------------
+
+export const Contained: Story = {
+  render: () => (
+    <Tabs defaultValue="overview">
+      <Tabs.List variant="contained">
+        <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+        <Tabs.Trigger value="details">Details</Tabs.Trigger>
+        <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="overview">Overview tab content</Tabs.Content>
+      <Tabs.Content value="details">Details tab content</Tabs.Content>
+      <Tabs.Content value="settings">Settings tab content</Tabs.Content>
+    </Tabs>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Pill variant
+// ---------------------------------------------------------------------------
+
+export const Pill: Story = {
+  render: () => (
+    <Tabs defaultValue="all">
+      <Tabs.List variant="pill">
+        <Tabs.Trigger value="all">All</Tabs.Trigger>
+        <Tabs.Trigger value="active">Active</Tabs.Trigger>
+        <Tabs.Trigger value="archived">Archived</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="all">All items</Tabs.Content>
+      <Tabs.Content value="active">Active items</Tabs.Content>
+      <Tabs.Content value="archived">Archived items</Tabs.Content>
+    </Tabs>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// With icons
+// ---------------------------------------------------------------------------
+
+export const WithIcons: Story = {
+  render: () => (
+    <Tabs defaultValue="general">
+      <Tabs.List variant="contained">
+        <Tabs.Trigger value="general" icon={SvgSettings}>
+          General
+        </Tabs.Trigger>
+        <Tabs.Trigger value="favorites" icon={SvgStar}>
+          Favorites
+        </Tabs.Trigger>
+        <Tabs.Trigger value="sync" icon={SvgRefreshCw}>
+          Sync
+        </Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="general">General settings</Tabs.Content>
+      <Tabs.Content value="favorites">Your favorites</Tabs.Content>
+      <Tabs.Content value="sync">Sync configuration</Tabs.Content>
+    </Tabs>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Pill with right content
+// ---------------------------------------------------------------------------
+
+export const PillWithRightContent: Story = {
+  render: () => (
+    <Tabs defaultValue="users">
+      <Tabs.List
+        variant="pill"
+        rightContent={
+          <button className="px-3 py-1 text-sm bg-background-tint-03 rounded-08">
+            Add New
+          </button>
+        }
+      >
+        <Tabs.Trigger value="users">Users</Tabs.Trigger>
+        <Tabs.Trigger value="groups">Groups</Tabs.Trigger>
+        <Tabs.Trigger value="roles">Roles</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="users">Users list</Tabs.Content>
+      <Tabs.Content value="groups">Groups list</Tabs.Content>
+      <Tabs.Content value="roles">Roles list</Tabs.Content>
+    </Tabs>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// With disabled and tooltip
+// ---------------------------------------------------------------------------
+
+export const WithDisabledTab: Story = {
+  render: () => (
+    <Tabs defaultValue="active">
+      <Tabs.List variant="contained">
+        <Tabs.Trigger value="active">Active</Tabs.Trigger>
+        <Tabs.Trigger value="pending" disabled tooltip="Coming soon">
+          Pending
+        </Tabs.Trigger>
+        <Tabs.Trigger value="completed">Completed</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="active">Active tasks</Tabs.Content>
+      <Tabs.Content value="completed">Completed tasks</Tabs.Content>
+    </Tabs>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Loading state
+// ---------------------------------------------------------------------------
+
+export const LoadingTab: Story = {
+  render: () => (
+    <Tabs defaultValue="data">
+      <Tabs.List variant="pill">
+        <Tabs.Trigger value="data" isLoading>
+          Loading Data
+        </Tabs.Trigger>
+        <Tabs.Trigger value="ready">Ready</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="data">Data is loading...</Tabs.Content>
+      <Tabs.Content value="ready">Ready content</Tabs.Content>
+    </Tabs>
+  ),
+};
diff --git a/web/src/refresh-components/TextSeparator.stories.tsx b/web/src/refresh-components/TextSeparator.stories.tsx
new file mode 100644
index 00000000000..f2faeee7bf5
--- /dev/null
+++ b/web/src/refresh-components/TextSeparator.stories.tsx
@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import TextSeparator from "./TextSeparator";
+
+const meta: Meta<typeof TextSeparator> = {
+  title: "refresh-components/TextSeparator",
+  component: TextSeparator,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TextSeparator>;
+
+export const TextOnly: Story = {
+  args: {
+    text: "Older messages",
+  },
+};
+
+export const WithCount: Story = {
+  args: {
+    text: "results",
+    count: 42,
+  },
+};
+
+export const InContext: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2" style={{ width: 400 }}>
+      <div className="p-2 bg-background-tint-01 rounded-08">Message 1</div>
+      <div className="p-2 bg-background-tint-01 rounded-08">Message 2</div>
+      <TextSeparator text="older messages" count={15} />
+      <div className="p-2 bg-background-tint-01 rounded-08">Message 3</div>
+      <div className="p-2 bg-background-tint-01 rounded-08">Message 4</div>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/avatars/CustomAgentAvatar.stories.tsx b/web/src/refresh-components/avatars/CustomAgentAvatar.stories.tsx
new file mode 100644
index 00000000000..7885e8807a6
--- /dev/null
+++ b/web/src/refresh-components/avatars/CustomAgentAvatar.stories.tsx
@@ -0,0 +1,91 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import CustomAgentAvatar from "./CustomAgentAvatar";
+
+const meta: Meta<typeof CustomAgentAvatar> = {
+  title: "refresh-components/Avatars/CustomAgentAvatar",
+  component: CustomAgentAvatar,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CustomAgentAvatar>;
+
+// ---------------------------------------------------------------------------
+// Default — falls back to letter from name
+// ---------------------------------------------------------------------------
+
+export const WithName: Story = {
+  args: {
+    name: "Research Assistant",
+    size: 40,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Icon variants
+// ---------------------------------------------------------------------------
+
+export const WithIconSearch: Story = {
+  args: {
+    name: "Search Agent",
+    iconName: "Search",
+    size: 40,
+  },
+};
+
+export const WithIconTerminal: Story = {
+  args: {
+    name: "Code Agent",
+    iconName: "Terminal",
+    size: 40,
+  },
+};
+
+export const WithIconPen: Story = {
+  args: {
+    name: "Writer Agent",
+    iconName: "Pen",
+    size: 40,
+  },
+};
+
+export const WithIconBarChart: Story = {
+  args: {
+    name: "Analytics Agent",
+    iconName: "BarChart",
+    size: 40,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Fallback — no name, no icon
+// ---------------------------------------------------------------------------
+
+export const NoNameNoIcon: Story = {
+  args: {
+    size: 40,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Sizes
+// ---------------------------------------------------------------------------
+
+export const Small: Story = {
+  args: {
+    name: "Tiny",
+    iconName: "Info",
+    size: 24,
+  },
+};
+
+export const Large: Story = {
+  args: {
+    name: "Big Agent",
+    iconName: "BooksStack",
+    size: 64,
+  },
+};
diff --git a/web/src/refresh-components/buttons/AttachmentButton.stories.tsx b/web/src/refresh-components/buttons/AttachmentButton.stories.tsx
new file mode 100644
index 00000000000..b4808b00113
--- /dev/null
+++ b/web/src/refresh-components/buttons/AttachmentButton.stories.tsx
@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import AttachmentButton from "./AttachmentButton";
+import { SvgTextLines, SvgTrash, SvgFiles } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof AttachmentButton> = {
+  title: "refresh-components/buttons/AttachmentButton",
+  component: AttachmentButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 400 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof AttachmentButton>;
+
+export const Default: Story = {
+  args: {
+    icon: SvgTextLines,
+    children: "Project Proposal",
+    description: "document.pdf",
+    rightText: "2.4 MB",
+  },
+};
+
+export const Selected: Story = {
+  args: {
+    icon: SvgTextLines,
+    children: "Project Proposal",
+    description: "document.pdf",
+    rightText: "2.4 MB",
+    selected: true,
+  },
+};
+
+export const Processing: Story = {
+  args: {
+    icon: SvgTextLines,
+    children: "Project Proposal",
+    description: "Uploading...",
+    rightText: "45%",
+    processing: true,
+  },
+};
+
+export const WithViewButton: Story = {
+  args: {
+    icon: SvgTextLines,
+    children: "Project Proposal",
+    description: "document.pdf",
+    rightText: "2.4 MB",
+    onView: () => {},
+  },
+};
+
+export const WithActionButton: Story = {
+  args: {
+    icon: SvgTextLines,
+    children: "Project Proposal",
+    description: "document.pdf",
+    rightText: "2.4 MB",
+    actionIcon: SvgTrash,
+    onAction: () => {},
+  },
+};
+
+export const FileList: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
+      <AttachmentButton
+        icon={SvgTextLines}
+        description="proposal.pdf"
+        rightText="2.4 MB"
+        onView={() => {}}
+      >
+        Project Proposal
+      </AttachmentButton>
+      <AttachmentButton
+        icon={SvgFiles}
+        description="report.xlsx"
+        rightText="1.1 MB"
+        selected
+      >
+        Quarterly Report
+      </AttachmentButton>
+      <AttachmentButton
+        icon={SvgTextLines}
+        description="Uploading..."
+        rightText="72%"
+        processing
+      >
+        Meeting Notes
+      </AttachmentButton>
+      <AttachmentButton
+        icon={SvgFiles}
+        description="readme.md"
+        rightText="4 KB"
+        actionIcon={SvgTrash}
+        onAction={() => {}}
+      >
+        README
+      </AttachmentButton>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/BackButton.stories.tsx b/web/src/refresh-components/buttons/BackButton.stories.tsx
new file mode 100644
index 00000000000..9883da7f9d2
--- /dev/null
+++ b/web/src/refresh-components/buttons/BackButton.stories.tsx
@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import BackButton from "./BackButton";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof BackButton> = {
+  title: "refresh-components/buttons/BackButton",
+  component: BackButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof BackButton>;
+
+export const Default: Story = {};
+
+export const WithBehaviorOverride: Story = {
+  args: {
+    behaviorOverride: () => {
+      console.log("Custom back behavior");
+    },
+  },
+};
diff --git a/web/src/refresh-components/buttons/Button.stories.tsx b/web/src/refresh-components/buttons/Button.stories.tsx
new file mode 100644
index 00000000000..08463a4b1c8
--- /dev/null
+++ b/web/src/refresh-components/buttons/Button.stories.tsx
@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Button from "./Button";
+import { SvgPlus, SvgArrowRight } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Button> = {
+  title: "refresh-components/buttons/Button",
+  component: Button,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Default: Story = {
+  args: {
+    children: "Button",
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <Button main>Main</Button>
+      <Button action>Action</Button>
+      <Button danger>Danger</Button>
+    </div>
+  ),
+};
+
+export const Prominences: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <Button primary>Primary</Button>
+      <Button secondary>Secondary</Button>
+      <Button tertiary>Tertiary</Button>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <Button leftIcon={SvgPlus}>With Left Icon</Button>
+      <Button rightIcon={SvgArrowRight}>With Right Icon</Button>
+    </div>
+  ),
+};
+
+export const Small: Story = {
+  args: {
+    size: "md",
+    children: "Small Button",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    children: "Disabled",
+  },
+};
+
+export const AsLink: Story = {
+  args: {
+    href: "https://example.com",
+    children: "Link Button",
+  },
+};
diff --git a/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx b/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx
new file mode 100644
index 00000000000..e6107352e4a
--- /dev/null
+++ b/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx
@@ -0,0 +1,62 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import ButtonRenaming from "./ButtonRenaming";
+
+const meta: Meta<typeof ButtonRenaming> = {
+  title: "refresh-components/buttons/ButtonRenaming",
+  component: ButtonRenaming,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div
+        style={{
+          width: 260,
+          padding: 8,
+          background: "var(--background-neutral-01)",
+          borderRadius: 8,
+        }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ButtonRenaming>;
+
+export const Default: Story = {
+  args: {
+    initialName: "My Chat Session",
+    onRename: async (name: string) => {
+      console.log("Renamed to:", name);
+    },
+    onClose: () => {
+      console.log("Closed");
+    },
+  },
+};
+
+export const EmptyName: Story = {
+  args: {
+    initialName: null,
+    onRename: async (name: string) => {
+      console.log("Renamed to:", name);
+    },
+    onClose: () => {
+      console.log("Closed");
+    },
+  },
+};
+
+export const LongName: Story = {
+  args: {
+    initialName: "This is a very long chat session name that should overflow",
+    onRename: async (name: string) => {
+      console.log("Renamed to:", name);
+    },
+    onClose: () => {
+      console.log("Closed");
+    },
+  },
+};
diff --git a/web/src/refresh-components/buttons/CopyIconButton.stories.tsx b/web/src/refresh-components/buttons/CopyIconButton.stories.tsx
new file mode 100644
index 00000000000..e4fd111454e
--- /dev/null
+++ b/web/src/refresh-components/buttons/CopyIconButton.stories.tsx
@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import CopyIconButton from "./CopyIconButton";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof CopyIconButton> = {
+  title: "refresh-components/buttons/CopyIconButton",
+  component: CopyIconButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof CopyIconButton>;
+
+export const Default: Story = {
+  args: {
+    getCopyText: () => "Copied text!",
+  },
+};
+
+export const WithTooltip: Story = {
+  args: {
+    getCopyText: () => "Copied text!",
+    tooltip: "Copy to clipboard",
+  },
+};
diff --git a/web/src/refresh-components/buttons/CreateButton.stories.tsx b/web/src/refresh-components/buttons/CreateButton.stories.tsx
new file mode 100644
index 00000000000..6b726aad540
--- /dev/null
+++ b/web/src/refresh-components/buttons/CreateButton.stories.tsx
@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import CreateButton from "./CreateButton";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof CreateButton> = {
+  title: "refresh-components/buttons/CreateButton",
+  component: CreateButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof CreateButton>;
+
+export const Default: Story = {};
+
+export const CustomLabel: Story = {
+  args: {
+    children: "New Document",
+  },
+};
+
+export const RightIcon: Story = {
+  args: {
+    rightIcon: true,
+    children: "Add Item",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <CreateButton />
+      <CreateButton>New Document</CreateButton>
+      <CreateButton rightIcon>Add Item</CreateButton>
+      <CreateButton disabled />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/FilterButton.stories.tsx b/web/src/refresh-components/buttons/FilterButton.stories.tsx
new file mode 100644
index 00000000000..08a5442a08b
--- /dev/null
+++ b/web/src/refresh-components/buttons/FilterButton.stories.tsx
@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import FilterButton from "./FilterButton";
+import { SvgFilter, SvgCalendar, SvgUser } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof FilterButton> = {
+  title: "refresh-components/buttons/FilterButton",
+  component: FilterButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof FilterButton>;
+
+export const Default: Story = {
+  args: {
+    leftIcon: SvgFilter,
+    children: "Filter",
+  },
+};
+
+export const Active: Story = {
+  args: {
+    leftIcon: SvgFilter,
+    active: true,
+    children: "Source: Google Drive",
+    onClear: () => {},
+  },
+};
+
+export const Transient: Story = {
+  args: {
+    leftIcon: SvgCalendar,
+    transient: true,
+    children: "Date Range",
+  },
+};
+
+export const WithoutLabel: Story = {
+  args: {
+    leftIcon: SvgFilter,
+  },
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        gap: 12,
+        alignItems: "center",
+        flexWrap: "wrap",
+      }}
+    >
+      <FilterButton leftIcon={SvgFilter}>Inactive</FilterButton>
+      <FilterButton leftIcon={SvgFilter} transient>
+        Transient
+      </FilterButton>
+      <FilterButton leftIcon={SvgCalendar} active onClear={() => {}}>
+        Active Filter
+      </FilterButton>
+      <FilterButton leftIcon={SvgUser} active onClear={() => {}}>
+        Author: John Doe
+      </FilterButton>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/IconButton.stories.tsx b/web/src/refresh-components/buttons/IconButton.stories.tsx
new file mode 100644
index 00000000000..3f8b0eb28e8
--- /dev/null
+++ b/web/src/refresh-components/buttons/IconButton.stories.tsx
@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import IconButton from "./IconButton";
+import { SvgSettings, SvgPlus, SvgX } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof IconButton> = {
+  title: "refresh-components/buttons/IconButton",
+  component: IconButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof IconButton>;
+
+export const Default: Story = {
+  args: {
+    icon: SvgSettings,
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <IconButton main icon={SvgSettings} />
+      <IconButton action icon={SvgPlus} />
+      <IconButton danger icon={SvgX} />
+    </div>
+  ),
+};
+
+export const Small: Story = {
+  args: {
+    icon: SvgSettings,
+    small: true,
+  },
+};
+
+export const WithTooltip: Story = {
+  args: {
+    icon: SvgSettings,
+    tooltip: "Settings",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    icon: SvgSettings,
+    disabled: true,
+  },
+};
diff --git a/web/src/refresh-components/buttons/LineItem.stories.tsx b/web/src/refresh-components/buttons/LineItem.stories.tsx
new file mode 100644
index 00000000000..59a304c00db
--- /dev/null
+++ b/web/src/refresh-components/buttons/LineItem.stories.tsx
@@ -0,0 +1,129 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import LineItem from "./LineItem";
+import {
+  SvgUser,
+  SvgSettings,
+  SvgTrash,
+  SvgFolder,
+  SvgCheck,
+  SvgSearch,
+} from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import Text from "@/refresh-components/texts/Text";
+
+const meta: Meta<typeof LineItem> = {
+  title: "refresh-components/buttons/LineItem",
+  component: LineItem,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 300 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof LineItem>;
+
+export const Default: Story = {
+  args: {
+    icon: SvgUser,
+    children: "Profile Settings",
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    icon: SvgSettings,
+    children: "Settings",
+    description: "Manage your account settings",
+  },
+};
+
+export const Selected: Story = {
+  args: {
+    icon: SvgCheck,
+    children: "Active Item",
+    selected: true,
+  },
+};
+
+export const SelectedEmphasized: Story = {
+  args: {
+    icon: SvgFolder,
+    children: "Selected Folder",
+    selected: true,
+    emphasized: true,
+  },
+};
+
+export const Danger: Story = {
+  args: {
+    icon: SvgTrash,
+    children: "Delete Account",
+    danger: true,
+  },
+};
+
+export const Action: Story = {
+  args: {
+    icon: SvgSearch,
+    children: "Search Results",
+    action: true,
+  },
+};
+
+export const Muted: Story = {
+  args: {
+    icon: SvgFolder,
+    children: "Secondary Item",
+    muted: true,
+  },
+};
+
+export const Strikethrough: Story = {
+  args: {
+    icon: SvgFolder,
+    children: "Archived Feature",
+    strikethrough: true,
+  },
+};
+
+export const WithRightChildren: Story = {
+  args: {
+    icon: SvgSettings,
+    children: "Keyboard Shortcuts",
+    rightChildren: (
+      <Text as="p" secondaryBody text03>
+        Cmd+K
+      </Text>
+    ),
+  },
+};
+
+export const MenuExample: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <LineItem icon={SvgUser}>Profile</LineItem>
+      <LineItem icon={SvgSettings} description="Manage your preferences">
+        Settings
+      </LineItem>
+      <LineItem icon={SvgFolder} selected emphasized>
+        Documents
+      </LineItem>
+      <LineItem icon={SvgSearch} action>
+        Search
+      </LineItem>
+      <LineItem icon={SvgFolder} muted>
+        Archived
+      </LineItem>
+      <LineItem icon={SvgTrash} danger>
+        Delete
+      </LineItem>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/SelectButton.stories.tsx b/web/src/refresh-components/buttons/SelectButton.stories.tsx
new file mode 100644
index 00000000000..4ad88a265ff
--- /dev/null
+++ b/web/src/refresh-components/buttons/SelectButton.stories.tsx
@@ -0,0 +1,135 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SelectButton from "./SelectButton";
+import { SvgFilter, SvgSettings } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof SelectButton> = {
+  title: "refresh-components/buttons/SelectButton",
+  component: SelectButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof SelectButton>;
+
+export const Default: Story = {
+  args: {
+    children: "Select Option",
+  },
+};
+
+export const MainVariant: Story = {
+  args: {
+    main: true,
+    children: "Main Select",
+    leftIcon: SvgFilter,
+  },
+};
+
+export const ActionVariant: Story = {
+  args: {
+    action: true,
+    children: "Action Select",
+    leftIcon: SvgSettings,
+  },
+};
+
+export const Engaged: Story = {
+  args: {
+    action: true,
+    engaged: true,
+    children: "Engaged",
+    leftIcon: SvgSettings,
+  },
+};
+
+export const WithChevron: Story = {
+  args: {
+    main: true,
+    children: "Dropdown",
+    leftIcon: SvgFilter,
+    rightChevronIcon: true,
+  },
+};
+
+export const Transient: Story = {
+  args: {
+    main: true,
+    transient: true,
+    children: "Transient",
+    leftIcon: SvgFilter,
+    rightChevronIcon: true,
+  },
+};
+
+export const Folded: Story = {
+  args: {
+    main: true,
+    folded: true,
+    children: "Folded Label",
+    leftIcon: SvgFilter,
+  },
+};
+
+export const FoldedAction: Story = {
+  args: {
+    action: true,
+    folded: true,
+    children: "Set as Default",
+    rightIcon: SvgSettings,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    main: true,
+    disabled: true,
+    children: "Disabled",
+    leftIcon: SvgFilter,
+  },
+};
+
+export const ActionDisabled: Story = {
+  args: {
+    action: true,
+    disabled: true,
+    children: "Disabled Action",
+    leftIcon: SvgSettings,
+  },
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        gap: 16,
+        alignItems: "center",
+        flexWrap: "wrap",
+      }}
+    >
+      <SelectButton main leftIcon={SvgFilter}>
+        Main
+      </SelectButton>
+      <SelectButton action leftIcon={SvgSettings}>
+        Action
+      </SelectButton>
+      <SelectButton action engaged leftIcon={SvgSettings}>
+        Engaged
+      </SelectButton>
+      <SelectButton main transient leftIcon={SvgFilter} rightChevronIcon>
+        Transient
+      </SelectButton>
+      <SelectButton main disabled leftIcon={SvgFilter}>
+        Disabled
+      </SelectButton>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/SidebarTab.stories.tsx b/web/src/refresh-components/buttons/SidebarTab.stories.tsx
new file mode 100644
index 00000000000..613ad1d3697
--- /dev/null
+++ b/web/src/refresh-components/buttons/SidebarTab.stories.tsx
@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SidebarTab from "./SidebarTab";
+import {
+  SvgDashboard,
+  SvgSettings,
+  SvgUser,
+  SvgFolder,
+  SvgSearch,
+} from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof SidebarTab> = {
+  title: "refresh-components/buttons/SidebarTab",
+  component: SidebarTab,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div
+          style={{
+            width: 260,
+            background: "var(--background-neutral-01)",
+            padding: 8,
+            borderRadius: 12,
+          }}
+        >
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof SidebarTab>;
+
+export const Default: Story = {
+  args: {
+    icon: SvgDashboard,
+    children: "Home",
+  },
+};
+
+export const Selected: Story = {
+  args: {
+    icon: SvgDashboard,
+    children: "Home",
+    selected: true,
+  },
+};
+
+export const Lowlight: Story = {
+  args: {
+    icon: SvgFolder,
+    children: "Archived",
+    lowlight: true,
+  },
+};
+
+export const Nested: Story = {
+  args: {
+    children: "Sub-item",
+    nested: true,
+  },
+};
+
+export const Folded: Story = {
+  args: {
+    icon: SvgDashboard,
+    children: "Home",
+    folded: true,
+  },
+};
+
+export const SidebarNavigation: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <SidebarTab icon={SvgDashboard} selected>
+        Home
+      </SidebarTab>
+      <SidebarTab icon={SvgSearch}>Search</SidebarTab>
+      <SidebarTab icon={SvgFolder}>Documents</SidebarTab>
+      <SidebarTab icon={SvgUser}>Profile</SidebarTab>
+      <SidebarTab icon={SvgSettings}>Settings</SidebarTab>
+      <SidebarTab nested>Sub-item A</SidebarTab>
+      <SidebarTab nested>Sub-item B</SidebarTab>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/SquareButton.stories.tsx b/web/src/refresh-components/buttons/SquareButton.stories.tsx
new file mode 100644
index 00000000000..f2df5cc0a6d
--- /dev/null
+++ b/web/src/refresh-components/buttons/SquareButton.stories.tsx
@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SquareButton from "./SquareButton";
+import { SvgPlus, SvgSettings, SvgSearch, SvgX } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof SquareButton> = {
+  title: "refresh-components/buttons/SquareButton",
+  component: SquareButton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof SquareButton>;
+
+export const Default: Story = {
+  args: {
+    icon: SvgPlus,
+  },
+};
+
+export const Transient: Story = {
+  args: {
+    icon: SvgSettings,
+    transient: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    icon: SvgPlus,
+    disabled: true,
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
+      <SquareButton icon={SvgPlus} />
+      <SquareButton icon={SvgSettings} transient />
+      <SquareButton icon={SvgSearch} />
+      <SquareButton icon={SvgX} />
+      <SquareButton icon={SvgPlus} disabled />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/buttons/Tag.stories.tsx b/web/src/refresh-components/buttons/Tag.stories.tsx
new file mode 100644
index 00000000000..82c16e3b326
--- /dev/null
+++ b/web/src/refresh-components/buttons/Tag.stories.tsx
@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Tag from "./Tag";
+import { SvgFilter, SvgUser, SvgFolder } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Tag> = {
+  title: "refresh-components/buttons/Tag",
+  component: Tag,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Tag>;
+
+export const Default: Story = {
+  args: {
+    label: "Label",
+  },
+};
+
+export const DisplayVariant: Story = {
+  args: {
+    label: "Display Tag",
+    variant: "display",
+  },
+};
+
+export const EditableVariant: Story = {
+  args: {
+    label: "Editable Tag",
+    variant: "editable",
+  },
+};
+
+export const WithIcon: Story = {
+  args: {
+    label: "With Icon",
+    icon: SvgFilter,
+  },
+};
+
+export const Removable: Story = {
+  args: {
+    label: "Removable",
+    variant: "editable",
+    onRemove: () => {},
+  },
+};
+
+export const Clickable: Story = {
+  args: {
+    label: "Click Me",
+    onClick: () => {},
+  },
+};
+
+export const WithIconAndRemove: Story = {
+  args: {
+    label: "Filter: Active",
+    variant: "editable",
+    icon: SvgFilter,
+    onRemove: () => {},
+  },
+};
+
+export const TagGroup: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+      <Tag label="React" variant="display" />
+      <Tag label="TypeScript" variant="display" icon={SvgFolder} />
+      <Tag
+        label="Active Filter"
+        variant="editable"
+        icon={SvgFilter}
+        onRemove={() => {}}
+      />
+      <Tag
+        label="John Doe"
+        variant="editable"
+        icon={SvgUser}
+        onRemove={() => {}}
+      />
+      <Tag label="Clickable" onClick={() => {}} />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/cards/Card.stories.tsx b/web/src/refresh-components/cards/Card.stories.tsx
new file mode 100644
index 00000000000..0fe7eb9cf5d
--- /dev/null
+++ b/web/src/refresh-components/cards/Card.stories.tsx
@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Card from "./Card";
+import Text from "@/refresh-components/texts/Text";
+
+const meta: Meta<typeof Card> = {
+  title: "refresh-components/cards/Card",
+  component: Card,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Primary: Story = {
+  args: {
+    variant: "primary",
+    children: (
+      <>
+        <Text as="p" mainUiAction text05>
+          Card Title
+        </Text>
+        <Text as="p" secondaryBody text03>
+          This is a primary card with some content inside.
+        </Text>
+      </>
+    ),
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    variant: "secondary",
+    children: (
+      <>
+        <Text as="p" mainUiAction text05>
+          Secondary Card
+        </Text>
+        <Text as="p" secondaryBody text03>
+          Less prominent content or nested cards.
+        </Text>
+      </>
+    ),
+  },
+};
+
+export const Tertiary: Story = {
+  args: {
+    variant: "tertiary",
+    children: (
+      <Text as="p" secondaryBody text03>
+        Dashed border for placeholder or empty states.
+      </Text>
+    ),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    variant: "disabled",
+    children: (
+      <>
+        <Text as="p" mainUiAction text05>
+          Disabled Card
+        </Text>
+        <Text as="p" secondaryBody text03>
+          This content is unavailable.
+        </Text>
+      </>
+    ),
+  },
+};
+
+export const Borderless: Story = {
+  args: {
+    variant: "borderless",
+    children: (
+      <>
+        <Text as="p" mainUiAction text05>
+          Borderless Card
+        </Text>
+        <Text as="p" secondaryBody text03>
+          No border, solid background.
+        </Text>
+      </>
+    ),
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 16,
+        maxWidth: 400,
+      }}
+    >
+      <Card variant="primary">
+        <Text as="p" mainUiAction text05>
+          Primary
+        </Text>
+        <Text as="p" secondaryBody text03>
+          Default card style
+        </Text>
+      </Card>
+      <Card variant="secondary">
+        <Text as="p" mainUiAction text05>
+          Secondary
+        </Text>
+        <Text as="p" secondaryBody text03>
+          Transparent background
+        </Text>
+      </Card>
+      <Card variant="tertiary">
+        <Text as="p" mainUiAction text05>
+          Tertiary
+        </Text>
+        <Text as="p" secondaryBody text03>
+          Dashed border
+        </Text>
+      </Card>
+      <Card variant="disabled">
+        <Text as="p" mainUiAction text05>
+          Disabled
+        </Text>
+        <Text as="p" secondaryBody text03>
+          Dimmed / unavailable
+        </Text>
+      </Card>
+      <Card variant="borderless">
+        <Text as="p" mainUiAction text05>
+          Borderless
+        </Text>
+        <Text as="p" secondaryBody text03>
+          No border
+        </Text>
+      </Card>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/cards/Select.stories.tsx b/web/src/refresh-components/cards/Select.stories.tsx
new file mode 100644
index 00000000000..80ffbe325d1
--- /dev/null
+++ b/web/src/refresh-components/cards/Select.stories.tsx
@@ -0,0 +1,129 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Select from "./Select";
+import { SvgSettings, SvgFolder, SvgSearch } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Select> = {
+  title: "refresh-components/cards/Select",
+  component: Select,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ maxWidth: 500 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Select>;
+
+export const Disconnected: Story = {
+  args: {
+    icon: SvgFolder,
+    title: "Google Drive",
+    description: "Connect to sync your files",
+    status: "disconnected",
+    onConnect: () => {},
+  },
+};
+
+export const Connected: Story = {
+  args: {
+    icon: SvgFolder,
+    title: "Google Drive",
+    description: "Connected and syncing",
+    status: "connected",
+    onSelect: () => {},
+    onEdit: () => {},
+  },
+};
+
+export const Selected: Story = {
+  args: {
+    icon: SvgFolder,
+    title: "Google Drive",
+    description: "Currently the default source",
+    status: "selected",
+    onDeselect: () => {},
+    onEdit: () => {},
+  },
+};
+
+export const DisabledState: Story = {
+  args: {
+    icon: SvgFolder,
+    title: "Google Drive",
+    description: "Not available on this plan",
+    status: "disconnected",
+    disabled: true,
+    onConnect: () => {},
+  },
+};
+
+export const MediumSize: Story = {
+  args: {
+    icon: SvgSearch,
+    title: "Elastic Search",
+    description: "Search engine connector",
+    status: "connected",
+    medium: true,
+    onSelect: () => {},
+  },
+};
+
+export const CustomLabels: Story = {
+  args: {
+    icon: SvgSettings,
+    title: "Custom LLM",
+    description: "Your custom model endpoint",
+    status: "connected",
+    connectLabel: "Link",
+    selectLabel: "Make Primary",
+    selectedLabel: "Primary Model",
+    onSelect: () => {},
+    onEdit: () => {},
+  },
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <Select
+        icon={SvgFolder}
+        title="Google Drive"
+        description="Connect to sync your files"
+        status="disconnected"
+        onConnect={() => {}}
+      />
+      <Select
+        icon={SvgSearch}
+        title="Confluence"
+        description="Connected and syncing"
+        status="connected"
+        onSelect={() => {}}
+        onEdit={() => {}}
+      />
+      <Select
+        icon={SvgSettings}
+        title="Notion"
+        description="Currently the default source"
+        status="selected"
+        onDeselect={() => {}}
+        onEdit={() => {}}
+      />
+      <Select
+        icon={SvgFolder}
+        title="Sharepoint"
+        description="Not available"
+        status="disconnected"
+        disabled
+        onConnect={() => {}}
+      />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/commandmenu/CommandMenu.stories.tsx b/web/src/refresh-components/commandmenu/CommandMenu.stories.tsx
new file mode 100644
index 00000000000..0bd21a5d126
--- /dev/null
+++ b/web/src/refresh-components/commandmenu/CommandMenu.stories.tsx
@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import CommandMenu from "./CommandMenu";
+import {
+  SvgFileText,
+  SvgUsers,
+  SvgSettings,
+  SvgPlus,
+  SvgSearch,
+  SvgArrowRight,
+} from "@opal/icons";
+
+const meta: Meta<typeof CommandMenu> = {
+  title: "refresh-components/modals/CommandMenu",
+  component: CommandMenu,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CommandMenu>;
+
+export const Default: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    const [search, setSearch] = useState("");
+
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Command Menu</button>
+        <CommandMenu open={open} onOpenChange={setOpen}>
+          <CommandMenu.Content>
+            <CommandMenu.Header
+              placeholder="Type a command or search..."
+              value={search}
+              onValueChange={setSearch}
+              onClose={() => setOpen(false)}
+            />
+            <CommandMenu.List emptyMessage="No results found.">
+              <CommandMenu.Item
+                value="documents"
+                icon={SvgFileText}
+                onSelect={() => alert("Documents")}
+              >
+                Search Documents
+              </CommandMenu.Item>
+              <CommandMenu.Item
+                value="people"
+                icon={SvgUsers}
+                onSelect={() => alert("People")}
+              >
+                Find People
+              </CommandMenu.Item>
+              <CommandMenu.Item
+                value="settings"
+                icon={SvgSettings}
+                onSelect={() => alert("Settings")}
+              >
+                Open Settings
+              </CommandMenu.Item>
+              <CommandMenu.Action
+                value="new-chat"
+                icon={SvgPlus}
+                shortcut="⌘N"
+                onSelect={() => alert("New chat")}
+              >
+                New Chat
+              </CommandMenu.Action>
+            </CommandMenu.List>
+            <CommandMenu.Footer
+              leftActions={
+                <>
+                  <CommandMenu.FooterAction
+                    icon={SvgArrowRight}
+                    label="Select"
+                  />
+                  <CommandMenu.FooterAction icon={SvgSearch} label="Search" />
+                </>
+              }
+            />
+          </CommandMenu.Content>
+        </CommandMenu>
+      </>
+    );
+  },
+};
+
+export const WithFilters: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    const [search, setSearch] = useState("");
+
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Command Menu</button>
+        <CommandMenu open={open} onOpenChange={setOpen}>
+          <CommandMenu.Content>
+            <CommandMenu.Header
+              placeholder="Search within filter..."
+              value={search}
+              onValueChange={setSearch}
+              onClose={() => setOpen(false)}
+              filters={[{ id: "docs", label: "Documents", icon: SvgFileText }]}
+              onFilterRemove={(id) => alert(`Remove filter: ${id}`)}
+            />
+            <CommandMenu.List>
+              <CommandMenu.Filter
+                value="filter-docs"
+                icon={SvgFileText}
+                isApplied
+              >
+                Documents
+              </CommandMenu.Filter>
+              <CommandMenu.Item value="doc-1" onSelect={() => {}}>
+                Q3 Financial Report
+              </CommandMenu.Item>
+              <CommandMenu.Item value="doc-2" onSelect={() => {}}>
+                Engineering Roadmap 2025
+              </CommandMenu.Item>
+              <CommandMenu.Item value="doc-3" onSelect={() => {}}>
+                Onboarding Guide
+              </CommandMenu.Item>
+            </CommandMenu.List>
+          </CommandMenu.Content>
+        </CommandMenu>
+      </>
+    );
+  },
+};
+
+export const EmptyState: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Command Menu</button>
+        <CommandMenu open={open} onOpenChange={setOpen}>
+          <CommandMenu.Content>
+            <CommandMenu.Header
+              placeholder="Search..."
+              onClose={() => setOpen(false)}
+            />
+            <CommandMenu.List emptyMessage="No commands match your search.">
+              <div />
+            </CommandMenu.List>
+          </CommandMenu.Content>
+        </CommandMenu>
+      </>
+    );
+  },
+};
diff --git a/web/src/refresh-components/form/FormField.stories.tsx b/web/src/refresh-components/form/FormField.stories.tsx
new file mode 100644
index 00000000000..25eb3943257
--- /dev/null
+++ b/web/src/refresh-components/form/FormField.stories.tsx
@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { FormField } from "./FormField";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+
+const meta: Meta<typeof FormField> = {
+  title: "refresh-components/form/FormField",
+  component: FormField,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof FormField>;
+
+export const Default: Story = {
+  render: () => (
+    <FormField state="idle" name="email">
+      <FormField.Label>Email Address</FormField.Label>
+      <FormField.Description>
+        We will never share your email with anyone.
+      </FormField.Description>
+      <FormField.Control>
+        <InputTypeIn placeholder="you@example.com" />
+      </FormField.Control>
+    </FormField>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <FormField state="idle" name="name" required>
+      <FormField.Label required>Full Name</FormField.Label>
+      <FormField.Control>
+        <InputTypeIn placeholder="Jane Doe" />
+      </FormField.Control>
+    </FormField>
+  ),
+};
+
+export const Optional: Story = {
+  render: () => (
+    <FormField state="idle" name="nickname">
+      <FormField.Label optional>Nickname</FormField.Label>
+      <FormField.Control>
+        <InputTypeIn placeholder="Optional nickname" />
+      </FormField.Control>
+    </FormField>
+  ),
+};
+
+export const ErrorState: Story = {
+  render: () => (
+    <FormField state="error" name="username">
+      <FormField.Label>Username</FormField.Label>
+      <FormField.Control>
+        <InputTypeIn placeholder="Choose a username" variant="error" />
+      </FormField.Control>
+      <FormField.Message
+        messages={{ error: "This username is already taken." }}
+      />
+    </FormField>
+  ),
+};
+
+export const SuccessState: Story = {
+  render: () => (
+    <FormField state="success" name="username">
+      <FormField.Label>Username</FormField.Label>
+      <FormField.Control>
+        <InputTypeIn placeholder="Choose a username" />
+      </FormField.Control>
+      <FormField.Message messages={{ success: "Username is available!" }} />
+    </FormField>
+  ),
+};
+
+export const WithAPIMessage: Story = {
+  render: () => (
+    <FormField state="idle" name="domain">
+      <FormField.Label>Custom Domain</FormField.Label>
+      <FormField.Control>
+        <InputTypeIn placeholder="your-domain.com" />
+      </FormField.Control>
+      <FormField.APIMessage
+        state="loading"
+        messages={{ loading: "Verifying DNS records..." }}
+      />
+    </FormField>
+  ),
+};
diff --git a/web/src/refresh-components/form/FormikFields.stories.tsx b/web/src/refresh-components/form/FormikFields.stories.tsx
new file mode 100644
index 00000000000..fba570d9928
--- /dev/null
+++ b/web/src/refresh-components/form/FormikFields.stories.tsx
@@ -0,0 +1,229 @@
+/**
+ * Stories for Formik-connected form field components.
+ *
+ * All these components call `useField` from Formik internally, so every story
+ * wraps the component in a minimal `<Formik>` provider. The forms are
+ * non-submitting; they exist purely to demonstrate the field UI.
+ *
+ * Components covered:
+ * - CheckboxField (unlabeled, from CheckboxField.tsx)
+ * - LabeledCheckboxField (from LabeledCheckboxField.tsx)
+ * - SwitchField
+ * - InputTypeInField
+ * - InputTextAreaField
+ * - InputSelectField
+ * - InputDatePickerField
+ * - PasswordInputTypeInField
+ */
+
+import type { Meta, StoryObj } from "@storybook/react";
+import { Formik, Form } from "formik";
+import React from "react";
+
+import UnlabeledCheckboxField from "./CheckboxField";
+import { CheckboxField as LabeledCheckboxField } from "./LabeledCheckboxField";
+import SwitchField from "./SwitchField";
+import InputTypeInField from "./InputTypeInField";
+import InputTextAreaField from "./InputTextAreaField";
+import InputSelectField from "./InputSelectField";
+import InputDatePickerField from "./InputDatePickerField";
+import PasswordInputTypeInField from "./PasswordInputTypeInField";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Minimal Formik wrapper that never submits. */
+function FormikWrapper({
+  initialValues,
+  children,
+}: {
+  initialValues: Record<string, unknown>;
+  children: React.ReactNode;
+}) {
+  return (
+    <Formik initialValues={initialValues} onSubmit={() => {}}>
+      <Form
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: 16,
+          maxWidth: 400,
+        }}
+      >
+        {children}
+      </Form>
+    </Formik>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta (we use a dummy component since this file covers multiple components)
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: "refresh-components/form/FormikFields",
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ---------------------------------------------------------------------------
+// CheckboxField (unlabeled)
+// ---------------------------------------------------------------------------
+
+export const Checkbox: Story = {
+  name: "CheckboxField (unlabeled)",
+  render: () => (
+    <FormikWrapper initialValues={{ agree: false }}>
+      <UnlabeledCheckboxField name="agree" />
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// LabeledCheckboxField
+// ---------------------------------------------------------------------------
+
+export const LabeledCheckbox: Story = {
+  name: "LabeledCheckboxField",
+  render: () => (
+    <FormikWrapper initialValues={{ terms: false }}>
+      <LabeledCheckboxField
+        name="terms"
+        label="I agree to the terms and conditions"
+        sublabel="You must accept before continuing."
+      />
+    </FormikWrapper>
+  ),
+};
+
+export const LabeledCheckboxWithTooltip: Story = {
+  name: "LabeledCheckboxField with tooltip",
+  render: () => (
+    <FormikWrapper initialValues={{ newsletter: true }}>
+      <LabeledCheckboxField
+        name="newsletter"
+        label="Subscribe to newsletter"
+        tooltip="We send at most one email per week."
+      />
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// SwitchField
+// ---------------------------------------------------------------------------
+
+export const Switch: Story = {
+  name: "SwitchField",
+  render: () => (
+    <FormikWrapper initialValues={{ notifications: true }}>
+      <label htmlFor="notifications" style={{ fontWeight: 500 }}>
+        Enable notifications
+      </label>
+      <SwitchField name="notifications" />
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// InputTypeInField
+// ---------------------------------------------------------------------------
+
+export const TextInput: Story = {
+  name: "InputTypeInField",
+  render: () => (
+    <FormikWrapper initialValues={{ username: "" }}>
+      <InputTypeInField name="username" placeholder="Enter your username" />
+    </FormikWrapper>
+  ),
+};
+
+export const TextInputDisabled: Story = {
+  name: "InputTypeInField (disabled)",
+  render: () => (
+    <FormikWrapper initialValues={{ locked: "read-only value" }}>
+      <InputTypeInField
+        name="locked"
+        placeholder="Disabled"
+        variant="disabled"
+      />
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// InputTextAreaField
+// ---------------------------------------------------------------------------
+
+export const TextArea: Story = {
+  name: "InputTextAreaField",
+  render: () => (
+    <FormikWrapper initialValues={{ bio: "" }}>
+      <InputTextAreaField name="bio" placeholder="Tell us about yourself..." />
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// InputSelectField
+// ---------------------------------------------------------------------------
+
+export const Select: Story = {
+  name: "InputSelectField",
+  render: () => (
+    <FormikWrapper initialValues={{ role: "" }}>
+      <InputSelectField name="role">
+        <InputSelect.Trigger placeholder="Select a role" />
+        <InputSelect.Content>
+          <InputSelect.Item value="admin">Admin</InputSelect.Item>
+          <InputSelect.Item value="editor">Editor</InputSelect.Item>
+          <InputSelect.Item value="viewer">Viewer</InputSelect.Item>
+        </InputSelect.Content>
+      </InputSelectField>
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// InputDatePickerField
+// ---------------------------------------------------------------------------
+
+export const DatePicker: Story = {
+  name: "InputDatePickerField",
+  render: () => (
+    <FormikWrapper initialValues={{ startDate: null }}>
+      <InputDatePickerField name="startDate" />
+    </FormikWrapper>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// PasswordInputTypeInField
+// ---------------------------------------------------------------------------
+
+export const PasswordInput: Story = {
+  name: "PasswordInputTypeInField",
+  render: () => (
+    <FormikWrapper initialValues={{ apiKey: "" }}>
+      <PasswordInputTypeInField
+        name="apiKey"
+        label="API Key"
+        subtext="Your key is stored encrypted."
+        placeholder="sk-..."
+      />
+    </FormikWrapper>
+  ),
+};
+
+export const PasswordInputNoLabel: Story = {
+  name: "PasswordInputTypeInField (no label)",
+  render: () => (
+    <FormikWrapper initialValues={{ secret: "" }}>
+      <PasswordInputTypeInField name="secret" placeholder="Enter secret" />
+    </FormikWrapper>
+  ),
+};
diff --git a/web/src/refresh-components/form/Label.stories.tsx b/web/src/refresh-components/form/Label.stories.tsx
new file mode 100644
index 00000000000..36fdc1ec119
--- /dev/null
+++ b/web/src/refresh-components/form/Label.stories.tsx
@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Label from "./Label";
+
+const meta: Meta<typeof Label> = {
+  title: "refresh-components/form/Label",
+  component: Label,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Label>;
+
+export const Default: Story = {
+  args: {
+    children: "Email Address",
+    name: "email",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    children: "Disabled Label",
+    name: "disabled-input",
+    disabled: true,
+  },
+};
+
+export const NonInteractive: Story = {
+  args: {
+    children: "Non-Interactive Label",
+    name: "readonly-input",
+    nonInteractive: true,
+  },
+};
diff --git a/web/src/refresh-components/inputs/Checkbox.stories.tsx b/web/src/refresh-components/inputs/Checkbox.stories.tsx
new file mode 100644
index 00000000000..467cd2d1bcd
--- /dev/null
+++ b/web/src/refresh-components/inputs/Checkbox.stories.tsx
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Checkbox from "./Checkbox";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Checkbox> = {
+  title: "refresh-components/inputs/Checkbox",
+  component: Checkbox,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const Checked: Story = {
+  args: {
+    checked: true,
+  },
+};
+
+export const Indeterminate: Story = {
+  args: {
+    indeterminate: true,
+  },
+};
+
+export const WithLabel: Story = {
+  render: () => (
+    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+      <Checkbox id="terms" />
+      <label htmlFor="terms" style={{ cursor: "pointer" }}>
+        Accept terms and conditions
+      </label>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/inputs/InputAvatar.stories.tsx b/web/src/refresh-components/inputs/InputAvatar.stories.tsx
new file mode 100644
index 00000000000..d7416cd9b3a
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputAvatar.stories.tsx
@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import InputAvatar from "./InputAvatar";
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+
+const meta: Meta<typeof InputAvatar> = {
+  title: "refresh-components/inputs/InputAvatar",
+  component: InputAvatar,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div
+        style={{
+          width: 320,
+          display: "flex",
+          justifyContent: "center",
+          padding: 24,
+        }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputAvatar>;
+
+export const WithImage: Story = {
+  render: () => (
+    <InputAvatar>
+      <AvatarPrimitive.Image
+        src="https://picsum.photos/80"
+        alt="User avatar"
+        className="h-full w-full object-cover"
+      />
+      <AvatarPrimitive.Fallback className="flex h-full w-full items-center justify-center bg-background-tint-02 text-text-03 text-sm font-medium">
+        AB
+      </AvatarPrimitive.Fallback>
+    </InputAvatar>
+  ),
+};
+
+export const WithFallback: Story = {
+  render: () => (
+    <InputAvatar>
+      <AvatarPrimitive.Fallback className="flex h-full w-full items-center justify-center bg-background-tint-02 text-text-03 text-sm font-medium">
+        JD
+      </AvatarPrimitive.Fallback>
+    </InputAvatar>
+  ),
+};
+
+export const Empty: Story = {
+  render: () => (
+    <InputAvatar>
+      <AvatarPrimitive.Fallback className="flex h-full w-full items-center justify-center bg-background-tint-02 text-text-04 text-xs">
+        ?
+      </AvatarPrimitive.Fallback>
+    </InputAvatar>
+  ),
+};
diff --git a/web/src/refresh-components/inputs/InputChipField.stories.tsx b/web/src/refresh-components/inputs/InputChipField.stories.tsx
new file mode 100644
index 00000000000..51d1b01f8e7
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputChipField.stories.tsx
@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import InputChipField from "./InputChipField";
+import type { ChipItem } from "./InputChipField";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputChipField> = {
+  title: "refresh-components/inputs/InputChipField",
+  component: InputChipField,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 400 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputChipField>;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [chips, setChips] = React.useState<ChipItem[]>([]);
+    const [value, setValue] = React.useState("");
+
+    return (
+      <InputChipField
+        chips={chips}
+        onRemoveChip={(id) => setChips((c) => c.filter((ch) => ch.id !== id))}
+        onAdd={(label) => {
+          setChips((c) => [...c, { id: crypto.randomUUID(), label }]);
+          setValue("");
+        }}
+        value={value}
+        onChange={setValue}
+        placeholder="Type and press Enter..."
+      />
+    );
+  },
+};
+
+export const WithChips: Story = {
+  render: function WithChipsStory() {
+    const [chips, setChips] = React.useState<ChipItem[]>([
+      { id: "1", label: "React" },
+      { id: "2", label: "TypeScript" },
+      { id: "3", label: "Tailwind" },
+    ]);
+    const [value, setValue] = React.useState("");
+
+    return (
+      <InputChipField
+        chips={chips}
+        onRemoveChip={(id) => setChips((c) => c.filter((ch) => ch.id !== id))}
+        onAdd={(label) => {
+          setChips((c) => [...c, { id: crypto.randomUUID(), label }]);
+          setValue("");
+        }}
+        value={value}
+        onChange={setValue}
+        placeholder="Add tags..."
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <InputChipField
+      chips={[
+        { id: "1", label: "Locked" },
+        { id: "2", label: "Tag" },
+      ]}
+      onRemoveChip={() => {}}
+      onAdd={() => {}}
+      value=""
+      onChange={() => {}}
+      placeholder="Disabled"
+      disabled
+    />
+  ),
+};
+
+export const ErrorVariant: Story = {
+  render: function ErrorStory() {
+    const [chips, setChips] = React.useState<ChipItem[]>([
+      { id: "1", label: "Invalid" },
+    ]);
+    const [value, setValue] = React.useState("");
+
+    return (
+      <InputChipField
+        chips={chips}
+        onRemoveChip={(id) => setChips((c) => c.filter((ch) => ch.id !== id))}
+        onAdd={(label) => {
+          setChips((c) => [...c, { id: crypto.randomUUID(), label }]);
+          setValue("");
+        }}
+        value={value}
+        onChange={setValue}
+        placeholder="Add labels..."
+        variant="error"
+      />
+    );
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.stories.tsx b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.stories.tsx
new file mode 100644
index 00000000000..1e237cdc215
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.stories.tsx
@@ -0,0 +1,144 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import InputComboBox from "./InputComboBox";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputComboBox> = {
+  title: "refresh-components/inputs/InputComboBox",
+  component: InputComboBox,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 320 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputComboBox>;
+
+const fruitOptions = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "cherry", label: "Cherry" },
+  { value: "dragonfruit", label: "Dragonfruit" },
+  { value: "elderberry", label: "Elderberry" },
+];
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [value, setValue] = React.useState("");
+    return (
+      <InputComboBox
+        placeholder="Type or select..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        options={fruitOptions}
+      />
+    );
+  },
+};
+
+export const InputModeNoOptions: Story = {
+  render: function InputModeStory() {
+    const [value, setValue] = React.useState("");
+    return (
+      <InputComboBox
+        placeholder="Type anything..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+    );
+  },
+};
+
+export const StrictMode: Story = {
+  render: function StrictStory() {
+    const [value, setValue] = React.useState("");
+    return (
+      <InputComboBox
+        placeholder="Select a fruit (strict)"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        options={fruitOptions}
+        strict
+      />
+    );
+  },
+};
+
+export const WithPreselectedValue: Story = {
+  render: function PreselectedStory() {
+    const [value, setValue] = React.useState("cherry");
+    return (
+      <InputComboBox
+        placeholder="Select a fruit"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onValueChange={setValue}
+        options={fruitOptions}
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <InputComboBox
+      placeholder="Cannot interact"
+      value="banana"
+      options={fruitOptions}
+      disabled
+    />
+  ),
+};
+
+export const WithSearchIcon: Story = {
+  render: function SearchIconStory() {
+    const [value, setValue] = React.useState("");
+    return (
+      <InputComboBox
+        placeholder="Search fruits..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        options={fruitOptions}
+        leftSearchIcon
+      />
+    );
+  },
+};
+
+export const ErrorState: Story = {
+  render: function ErrorStory() {
+    const [value, setValue] = React.useState("invalid-value");
+    return (
+      <InputComboBox
+        placeholder="Select a fruit"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        options={fruitOptions}
+        isError
+      />
+    );
+  },
+};
+
+export const WithOtherOptions: Story = {
+  render: function OtherOptionsStory() {
+    const [value, setValue] = React.useState("");
+    return (
+      <InputComboBox
+        placeholder="Search or select..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        options={fruitOptions}
+        showOtherOptions
+        separatorLabel="Other fruits"
+      />
+    );
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputDatePicker.stories.tsx b/web/src/refresh-components/inputs/InputDatePicker.stories.tsx
new file mode 100644
index 00000000000..26c84556cbb
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputDatePicker.stories.tsx
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import InputDatePicker from "./InputDatePicker";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputDatePicker> = {
+  title: "refresh-components/inputs/InputDatePicker",
+  component: InputDatePicker,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 320 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputDatePicker>;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [date, setDate] = React.useState<Date | null>(null);
+    return <InputDatePicker selectedDate={date} setSelectedDate={setDate} />;
+  },
+};
+
+export const WithSelectedDate: Story = {
+  render: function SelectedDateStory() {
+    const [date, setDate] = React.useState<Date | null>(new Date(2025, 0, 15));
+    return <InputDatePicker selectedDate={date} setSelectedDate={setDate} />;
+  },
+};
+
+export const CustomStartYear: Story = {
+  render: function CustomStartYearStory() {
+    const [date, setDate] = React.useState<Date | null>(null);
+    return (
+      <InputDatePicker
+        selectedDate={date}
+        setSelectedDate={setDate}
+        startYear={2020}
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <InputDatePicker
+      selectedDate={new Date()}
+      setSelectedDate={() => {}}
+      disabled
+    />
+  ),
+};
diff --git a/web/src/refresh-components/inputs/InputFile.stories.tsx b/web/src/refresh-components/inputs/InputFile.stories.tsx
new file mode 100644
index 00000000000..76b632ee686
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputFile.stories.tsx
@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import InputFile from "./InputFile";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputFile> = {
+  title: "refresh-components/inputs/InputFile",
+  component: InputFile,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 400 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputFile>;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [, setValue] = React.useState("");
+    return (
+      <InputFile placeholder="Paste or attach a file..." setValue={setValue} />
+    );
+  },
+};
+
+export const WithAcceptFilter: Story = {
+  render: function AcceptFilterStory() {
+    const [, setValue] = React.useState("");
+    return (
+      <InputFile
+        placeholder="JSON files only..."
+        setValue={setValue}
+        accept="application/json,.json"
+      />
+    );
+  },
+};
+
+export const WithMaxSize: Story = {
+  render: function MaxSizeStory() {
+    const [, setValue] = React.useState("");
+    return (
+      <InputFile
+        placeholder="Max 100KB..."
+        setValue={setValue}
+        maxSizeKb={100}
+        onFileSizeExceeded={({ file, maxSizeKb }) =>
+          alert(`${file.name} exceeds ${maxSizeKb}KB limit`)
+        }
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <InputFile placeholder="Cannot upload" setValue={() => {}} disabled />
+  ),
+};
+
+export const ErrorState: Story = {
+  render: function ErrorStory() {
+    const [, setValue] = React.useState("");
+    return (
+      <InputFile placeholder="Required file..." setValue={setValue} error />
+    );
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputImage.stories.tsx b/web/src/refresh-components/inputs/InputImage.stories.tsx
new file mode 100644
index 00000000000..420d758ce14
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputImage.stories.tsx
@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import InputImage from "./InputImage";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputImage> = {
+  title: "refresh-components/inputs/InputImage",
+  component: InputImage,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div
+          style={{
+            width: 320,
+            display: "flex",
+            justifyContent: "center",
+            padding: 24,
+          }}
+        >
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputImage>;
+
+export const Empty: Story = {
+  args: {
+    onDrop: () => {},
+  },
+};
+
+export const WithImage: Story = {
+  args: {
+    src: "https://picsum.photos/200",
+    alt: "Sample image",
+    onEdit: () => {},
+    onRemove: () => {},
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    onDrop: () => {},
+  },
+};
+
+export const DisabledWithImage: Story = {
+  args: {
+    src: "https://picsum.photos/200",
+    alt: "Cannot edit",
+    disabled: true,
+  },
+};
+
+export const CustomSize: Story = {
+  args: {
+    size: 80,
+    onDrop: () => {},
+  },
+};
+
+export const LargeSize: Story = {
+  args: {
+    src: "https://picsum.photos/300",
+    alt: "Large avatar",
+    size: 160,
+    onEdit: () => {},
+    onRemove: () => {},
+  },
+};
+
+export const NoEditOverlay: Story = {
+  args: {
+    src: "https://picsum.photos/200",
+    alt: "No overlay",
+    showEditOverlay: false,
+    onEdit: () => {},
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputKeyValue.stories.tsx b/web/src/refresh-components/inputs/InputKeyValue.stories.tsx
new file mode 100644
index 00000000000..7b56c9b79a9
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputKeyValue.stories.tsx
@@ -0,0 +1,134 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import KeyValueInput from "./InputKeyValue";
+import type { KeyValue } from "./InputKeyValue";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof KeyValueInput> = {
+  title: "refresh-components/inputs/InputKeyValue",
+  component: KeyValueInput,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 400 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof KeyValueInput>;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [items, setItems] = React.useState<KeyValue[]>([
+      { key: "", value: "" },
+    ]);
+    return (
+      <KeyValueInput
+        keyTitle="Key"
+        valueTitle="Value"
+        items={items}
+        onChange={setItems}
+      />
+    );
+  },
+};
+
+export const WithValues: Story = {
+  render: function WithValuesStory() {
+    const [items, setItems] = React.useState<KeyValue[]>([
+      { key: "API_KEY", value: "sk-abc123" },
+      { key: "BASE_URL", value: "https://api.example.com" },
+    ]);
+    return (
+      <KeyValueInput
+        keyTitle="Variable Name"
+        valueTitle="Value"
+        items={items}
+        onChange={setItems}
+      />
+    );
+  },
+};
+
+export const FixedLineMode: Story = {
+  render: function FixedLineStory() {
+    const [items, setItems] = React.useState<KeyValue[]>([
+      { key: "Content-Type", value: "application/json" },
+    ]);
+    return (
+      <KeyValueInput
+        keyTitle="Header"
+        valueTitle="Value"
+        items={items}
+        onChange={setItems}
+        mode="fixed-line"
+      />
+    );
+  },
+};
+
+export const KeyWideLayout: Story = {
+  render: function KeyWideStory() {
+    const [items, setItems] = React.useState<KeyValue[]>([
+      { key: "Authorization", value: "Bearer token" },
+    ]);
+    return (
+      <KeyValueInput
+        keyTitle="Header"
+        valueTitle="Value"
+        items={items}
+        onChange={setItems}
+        layout="key-wide"
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <KeyValueInput
+      keyTitle="Key"
+      valueTitle="Value"
+      items={[{ key: "LOCKED", value: "cannot-edit" }]}
+      onChange={() => {}}
+      disabled
+    />
+  ),
+};
+
+export const EmptyLineMode: Story = {
+  render: function EmptyStory() {
+    const [items, setItems] = React.useState<KeyValue[]>([]);
+    return (
+      <KeyValueInput
+        keyTitle="Key"
+        valueTitle="Value"
+        items={items}
+        onChange={setItems}
+        mode="line"
+      />
+    );
+  },
+};
+
+export const CustomAddLabel: Story = {
+  render: function CustomLabelStory() {
+    const [items, setItems] = React.useState<KeyValue[]>([
+      { key: "", value: "" },
+    ]);
+    return (
+      <KeyValueInput
+        keyTitle="Name"
+        valueTitle="Endpoint"
+        items={items}
+        onChange={setItems}
+        addButtonLabel="Add Endpoint"
+      />
+    );
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputNumber.stories.tsx b/web/src/refresh-components/inputs/InputNumber.stories.tsx
new file mode 100644
index 00000000000..6361ae5fe30
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputNumber.stories.tsx
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import InputNumber from "./InputNumber";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputNumber> = {
+  title: "refresh-components/inputs/InputNumber",
+  component: InputNumber,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 200 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputNumber>;
+
+export const Default: Story = {
+  args: {
+    value: 5,
+    onChange: () => {},
+  },
+};
+
+export const WithMinMax: Story = {
+  args: {
+    value: 50,
+    onChange: () => {},
+    min: 0,
+    max: 100,
+  },
+};
+
+export const WithReset: Story = {
+  args: {
+    value: 42,
+    onChange: () => {},
+    showReset: true,
+    defaultValue: 10,
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputSelect.stories.tsx b/web/src/refresh-components/inputs/InputSelect.stories.tsx
new file mode 100644
index 00000000000..6adb6380188
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputSelect.stories.tsx
@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import InputSelect from "./InputSelect";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputSelect> = {
+  title: "refresh-components/inputs/InputSelect",
+  component: InputSelect,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 320 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputSelect>;
+
+export const Default: Story = {
+  render: () => (
+    <InputSelect defaultValue="option1">
+      <InputSelect.Trigger placeholder="Select an option" />
+      <InputSelect.Content>
+        <InputSelect.Item value="option1">Option 1</InputSelect.Item>
+        <InputSelect.Item value="option2">Option 2</InputSelect.Item>
+        <InputSelect.Item value="option3">Option 3</InputSelect.Item>
+      </InputSelect.Content>
+    </InputSelect>
+  ),
+};
+
+export const WithPlaceholder: Story = {
+  render: () => (
+    <InputSelect>
+      <InputSelect.Trigger placeholder="Choose a fruit..." />
+      <InputSelect.Content>
+        <InputSelect.Item value="apple">Apple</InputSelect.Item>
+        <InputSelect.Item value="banana">Banana</InputSelect.Item>
+        <InputSelect.Item value="cherry">Cherry</InputSelect.Item>
+      </InputSelect.Content>
+    </InputSelect>
+  ),
+};
+
+export const Controlled: Story = {
+  render: function ControlledStory() {
+    const [value, setValue] = React.useState("b");
+    return (
+      <InputSelect value={value} onValueChange={setValue}>
+        <InputSelect.Trigger placeholder="Select..." />
+        <InputSelect.Content>
+          <InputSelect.Item value="a">Alpha</InputSelect.Item>
+          <InputSelect.Item value="b">Bravo</InputSelect.Item>
+          <InputSelect.Item value="c">Charlie</InputSelect.Item>
+        </InputSelect.Content>
+      </InputSelect>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <InputSelect defaultValue="option1" disabled>
+      <InputSelect.Trigger placeholder="Select an option" />
+      <InputSelect.Content>
+        <InputSelect.Item value="option1">Option 1</InputSelect.Item>
+        <InputSelect.Item value="option2">Option 2</InputSelect.Item>
+      </InputSelect.Content>
+    </InputSelect>
+  ),
+};
+
+export const ErrorState: Story = {
+  render: () => (
+    <InputSelect error>
+      <InputSelect.Trigger placeholder="Required field" />
+      <InputSelect.Content>
+        <InputSelect.Item value="x">X</InputSelect.Item>
+        <InputSelect.Item value="y">Y</InputSelect.Item>
+      </InputSelect.Content>
+    </InputSelect>
+  ),
+};
+
+export const WithGroups: Story = {
+  render: () => (
+    <InputSelect defaultValue="gpt4o">
+      <InputSelect.Trigger placeholder="Choose a model..." />
+      <InputSelect.Content>
+        <InputSelect.Group>
+          <InputSelect.Label>OpenAI</InputSelect.Label>
+          <InputSelect.Item value="gpt4o">GPT-4o</InputSelect.Item>
+          <InputSelect.Item value="gpt4o-mini">GPT-4o Mini</InputSelect.Item>
+        </InputSelect.Group>
+        <InputSelect.Separator />
+        <InputSelect.Group>
+          <InputSelect.Label>Anthropic</InputSelect.Label>
+          <InputSelect.Item value="opus">Claude Opus</InputSelect.Item>
+          <InputSelect.Item value="sonnet">Claude Sonnet</InputSelect.Item>
+        </InputSelect.Group>
+      </InputSelect.Content>
+    </InputSelect>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <InputSelect>
+      <InputSelect.Trigger placeholder="Select a plan..." />
+      <InputSelect.Content>
+        <InputSelect.Item value="free" description="Up to 5 users">
+          Free
+        </InputSelect.Item>
+        <InputSelect.Item value="pro" description="Unlimited users">
+          Pro
+        </InputSelect.Item>
+        <InputSelect.Item value="enterprise" description="Custom limits">
+          Enterprise
+        </InputSelect.Item>
+      </InputSelect.Content>
+    </InputSelect>
+  ),
+};
diff --git a/web/src/refresh-components/inputs/InputTextArea.stories.tsx b/web/src/refresh-components/inputs/InputTextArea.stories.tsx
new file mode 100644
index 00000000000..39ca717669b
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputTextArea.stories.tsx
@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import InputTextArea from "./InputTextArea";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputTextArea> = {
+  title: "refresh-components/inputs/InputTextArea",
+  component: InputTextArea,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 400 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputTextArea>;
+
+export const Default: Story = {
+  args: {
+    placeholder: "Enter a description...",
+  },
+};
+
+export const AutoResize: Story = {
+  args: {
+    autoResize: true,
+    placeholder: "This textarea grows as you type...",
+  },
+};
+
+export const WithMaxRows: Story = {
+  args: {
+    autoResize: true,
+    maxRows: 5,
+    placeholder: "Grows up to 5 rows...",
+  },
+};
+
+export const Error: Story = {
+  args: {
+    variant: "error",
+    value: "Invalid content",
+    placeholder: "Enter a description...",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    variant: "disabled",
+    value: "Cannot edit this textarea",
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    variant: "readOnly",
+    value: "This content is read-only and cannot be modified.",
+  },
+};
+
+export const NonResizable: Story = {
+  args: {
+    resizable: false,
+    placeholder: "This textarea cannot be resized...",
+  },
+};
diff --git a/web/src/refresh-components/inputs/InputTypeIn.stories.tsx b/web/src/refresh-components/inputs/InputTypeIn.stories.tsx
new file mode 100644
index 00000000000..4e928074290
--- /dev/null
+++ b/web/src/refresh-components/inputs/InputTypeIn.stories.tsx
@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import InputTypeIn from "./InputTypeIn";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof InputTypeIn> = {
+  title: "refresh-components/inputs/InputTypeIn",
+  component: InputTypeIn,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 320 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof InputTypeIn>;
+
+export const Default: Story = {
+  args: {
+    placeholder: "Enter text...",
+  },
+};
+
+export const WithPrefix: Story = {
+  args: {
+    prefixText: "https://",
+    placeholder: "example.com",
+  },
+};
+
+export const WithSearchIcon: Story = {
+  args: {
+    leftSearchIcon: true,
+    placeholder: "Search...",
+  },
+};
+
+export const WithClearButton: Story = {
+  args: {
+    showClearButton: true,
+    value: "Some text to clear",
+    onChange: () => {},
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    variant: "disabled",
+    value: "Cannot edit",
+  },
+};
+
+export const Error: Story = {
+  args: {
+    variant: "error",
+    value: "Invalid input",
+    placeholder: "Enter text...",
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    variant: "readOnly",
+    value: "Read-only value",
+  },
+};
diff --git a/web/src/refresh-components/inputs/ListFieldInput.stories.tsx b/web/src/refresh-components/inputs/ListFieldInput.stories.tsx
new file mode 100644
index 00000000000..86bad1b41c8
--- /dev/null
+++ b/web/src/refresh-components/inputs/ListFieldInput.stories.tsx
@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import { ListFieldInput } from "./ListFieldInput";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof ListFieldInput> = {
+  title: "refresh-components/inputs/ListFieldInput",
+  component: ListFieldInput,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 400 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ListFieldInput>;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [values, setValues] = React.useState<string[]>([]);
+    return (
+      <ListFieldInput
+        values={values}
+        onChange={setValues}
+        placeholder="Type and press Enter..."
+      />
+    );
+  },
+};
+
+export const WithValues: Story = {
+  render: function WithValuesStory() {
+    const [values, setValues] = React.useState([
+      "admin@example.com",
+      "user@example.com",
+      "dev@example.com",
+    ]);
+    return (
+      <ListFieldInput
+        values={values}
+        onChange={setValues}
+        placeholder="Add email..."
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <ListFieldInput
+      values={["locked-item"]}
+      onChange={() => {}}
+      placeholder="Cannot edit"
+      disabled
+    />
+  ),
+};
+
+export const ErrorState: Story = {
+  render: function ErrorStory() {
+    const [values, setValues] = React.useState(["invalid"]);
+    return (
+      <ListFieldInput
+        values={values}
+        onChange={setValues}
+        placeholder="Add value..."
+        error
+      />
+    );
+  },
+};
diff --git a/web/src/refresh-components/inputs/PasswordInputTypeIn.stories.tsx b/web/src/refresh-components/inputs/PasswordInputTypeIn.stories.tsx
new file mode 100644
index 00000000000..01407524c09
--- /dev/null
+++ b/web/src/refresh-components/inputs/PasswordInputTypeIn.stories.tsx
@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React from "react";
+import PasswordInputTypeIn from "./PasswordInputTypeIn";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof PasswordInputTypeIn> = {
+  title: "refresh-components/inputs/PasswordInputTypeIn",
+  component: PasswordInputTypeIn,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ width: 320 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof PasswordInputTypeIn>;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [value, setValue] = React.useState("");
+    return (
+      <PasswordInputTypeIn
+        placeholder="Enter password..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+    );
+  },
+};
+
+export const WithValue: Story = {
+  render: function WithValueStory() {
+    const [value, setValue] = React.useState("supersecret123");
+    return (
+      <PasswordInputTypeIn
+        placeholder="Enter password..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+    );
+  },
+};
+
+export const NonRevealable: Story = {
+  render: function NonRevealableStory() {
+    const [value, setValue] = React.useState("stored-secret-value");
+    return (
+      <PasswordInputTypeIn
+        placeholder="Stored secret"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        isNonRevealable
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <PasswordInputTypeIn
+      placeholder="Cannot edit"
+      value="disabled-password"
+      onChange={() => {}}
+      disabled
+    />
+  ),
+};
+
+export const ErrorState: Story = {
+  render: function ErrorStory() {
+    const [value, setValue] = React.useState("bad");
+    return (
+      <PasswordInputTypeIn
+        placeholder="Enter password..."
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        error
+      />
+    );
+  },
+};
diff --git a/web/src/refresh-components/inputs/Switch.stories.tsx b/web/src/refresh-components/inputs/Switch.stories.tsx
new file mode 100644
index 00000000000..6131a3f43f8
--- /dev/null
+++ b/web/src/refresh-components/inputs/Switch.stories.tsx
@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Switch from "./Switch";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Switch> = {
+  title: "refresh-components/inputs/Switch",
+  component: Switch,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const Checked: Story = {
+  args: {
+    checked: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};
diff --git a/web/src/refresh-components/layouts/ConfirmationModalLayout.stories.tsx b/web/src/refresh-components/layouts/ConfirmationModalLayout.stories.tsx
new file mode 100644
index 00000000000..c3f9dbc3611
--- /dev/null
+++ b/web/src/refresh-components/layouts/ConfirmationModalLayout.stories.tsx
@@ -0,0 +1,114 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import ConfirmationModalLayout from "./ConfirmationModalLayout";
+import { SvgAlertTriangle, SvgTrash, SvgCheckCircle } from "@opal/icons";
+import { Button } from "@opal/components";
+
+const meta: Meta<typeof ConfirmationModalLayout> = {
+  title: "refresh-components/modals/ConfirmationModalLayout",
+  component: ConfirmationModalLayout,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ConfirmationModalLayout>;
+
+/**
+ * NOTE: ConfirmationModalLayout calls `useModalClose` internally, which reads
+ * from ModalContext. Outside of that context, it falls back to the `onClose`
+ * prop, so these stories work without wrapping in a ModalContext provider.
+ */
+
+export const DeleteConfirmation: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Modal</button>
+        {open && (
+          <ConfirmationModalLayout
+            icon={SvgTrash}
+            title="Delete Item"
+            description="Are you sure you want to delete this item? This action cannot be undone."
+            submit={
+              <Button variant="danger" onClick={() => setOpen(false)}>
+                Delete
+              </Button>
+            }
+            onClose={() => setOpen(false)}
+          />
+        )}
+      </>
+    );
+  },
+};
+
+export const WarningConfirmation: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Modal</button>
+        {open && (
+          <ConfirmationModalLayout
+            icon={SvgAlertTriangle}
+            title="Proceed with Caution"
+            description="This operation will affect all users in the organization."
+            submit={<Button onClick={() => setOpen(false)}>Confirm</Button>}
+            onClose={() => setOpen(false)}
+          />
+        )}
+      </>
+    );
+  },
+};
+
+export const WithChildren: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Modal</button>
+        {open && (
+          <ConfirmationModalLayout
+            icon={SvgCheckCircle}
+            title="Review Changes"
+            description="Please review the following changes before confirming."
+            submit={<Button onClick={() => setOpen(false)}>Approve</Button>}
+            onClose={() => setOpen(false)}
+          >
+            <ul style={{ listStyle: "disc", paddingLeft: 20 }}>
+              <li>Updated email notification settings</li>
+              <li>Changed default connector timeout to 30s</li>
+              <li>Enabled automatic document syncing</li>
+            </ul>
+          </ConfirmationModalLayout>
+        )}
+      </>
+    );
+  },
+};
+
+export const HiddenCancel: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    return (
+      <>
+        <button onClick={() => setOpen(true)}>Open Modal</button>
+        {open && (
+          <ConfirmationModalLayout
+            icon={SvgCheckCircle}
+            title="Welcome!"
+            description="Thanks for signing up. Let's get you started."
+            hideCancel
+            submit={<Button onClick={() => setOpen(false)}>Get Started</Button>}
+            onClose={() => setOpen(false)}
+          />
+        )}
+      </>
+    );
+  },
+};
diff --git a/web/src/refresh-components/loaders/SimpleLoader.stories.tsx b/web/src/refresh-components/loaders/SimpleLoader.stories.tsx
new file mode 100644
index 00000000000..81e3ed66f12
--- /dev/null
+++ b/web/src/refresh-components/loaders/SimpleLoader.stories.tsx
@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SimpleLoader from "./SimpleLoader";
+
+const meta: Meta<typeof SimpleLoader> = {
+  title: "refresh-components/loaders/SimpleLoader",
+  component: SimpleLoader,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof SimpleLoader>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const Large: Story = {
+  args: {
+    className: "h-8 w-8",
+  },
+};
+
+export const CustomColor: Story = {
+  args: {
+    className: "h-6 w-6 stroke-text-05",
+  },
+};
diff --git a/web/src/refresh-components/messages/FieldMessage.stories.tsx b/web/src/refresh-components/messages/FieldMessage.stories.tsx
new file mode 100644
index 00000000000..dcd1fa5fdf2
--- /dev/null
+++ b/web/src/refresh-components/messages/FieldMessage.stories.tsx
@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { FieldMessage } from "./FieldMessage";
+
+const meta: Meta<typeof FieldMessage> = {
+  title: "refresh-components/messages/FieldMessage",
+  component: FieldMessage,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof FieldMessage>;
+
+export const Error: Story = {
+  args: {
+    variant: "error",
+    children: (
+      <FieldMessage.Content>This field is required.</FieldMessage.Content>
+    ),
+  },
+};
+
+export const Success: Story = {
+  args: {
+    variant: "success",
+    children: (
+      <FieldMessage.Content>Username is available!</FieldMessage.Content>
+    ),
+  },
+};
+
+export const Warning: Story = {
+  args: {
+    variant: "warning",
+    children: (
+      <FieldMessage.Content>This action cannot be undone.</FieldMessage.Content>
+    ),
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    variant: "loading",
+    children: (
+      <FieldMessage.Content>Checking availability...</FieldMessage.Content>
+    ),
+  },
+};
+
+export const Info: Story = {
+  args: {
+    variant: "info",
+    children: (
+      <FieldMessage.Content>
+        Passwords must be at least 8 characters.
+      </FieldMessage.Content>
+    ),
+  },
+};
+
+export const Idle: Story = {
+  args: {
+    variant: "idle",
+    children: (
+      <FieldMessage.Content>Enter your email address.</FieldMessage.Content>
+    ),
+  },
+};
+
+export const AllVariants: Story = {
+  name: "All Variants",
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <FieldMessage variant="error">
+        <FieldMessage.Content>Error message</FieldMessage.Content>
+      </FieldMessage>
+      <FieldMessage variant="success">
+        <FieldMessage.Content>Success message</FieldMessage.Content>
+      </FieldMessage>
+      <FieldMessage variant="warning">
+        <FieldMessage.Content>Warning message</FieldMessage.Content>
+      </FieldMessage>
+      <FieldMessage variant="loading">
+        <FieldMessage.Content>Loading message</FieldMessage.Content>
+      </FieldMessage>
+      <FieldMessage variant="info">
+        <FieldMessage.Content>Info message</FieldMessage.Content>
+      </FieldMessage>
+      <FieldMessage variant="idle">
+        <FieldMessage.Content>Idle message</FieldMessage.Content>
+      </FieldMessage>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/messages/InfoBlock.stories.tsx b/web/src/refresh-components/messages/InfoBlock.stories.tsx
new file mode 100644
index 00000000000..b7d436a0bde
--- /dev/null
+++ b/web/src/refresh-components/messages/InfoBlock.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import InfoBlock from "./InfoBlock";
+import { SvgAlertCircle, SvgCheckCircle, SvgSettings } from "@opal/icons";
+
+const meta: Meta<typeof InfoBlock> = {
+  title: "refresh-components/messages/InfoBlock",
+  component: InfoBlock,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof InfoBlock>;
+
+export const Default: Story = {
+  args: {
+    icon: SvgAlertCircle,
+    title: "Important Notice",
+    description: "This is a description providing additional context.",
+  },
+};
+
+export const TitleOnly: Story = {
+  args: {
+    icon: SvgCheckCircle,
+    title: "All systems operational",
+  },
+};
+
+export const WithCustomIcon: Story = {
+  args: {
+    icon: SvgSettings,
+    title: "Configuration Required",
+    description: "Please update your settings before continuing.",
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    icon: SvgAlertCircle,
+    title:
+      "This is a very long title that should get truncated when it exceeds the available width",
+    description:
+      "And this is a very long description that provides detailed context about the situation at hand and should also truncate gracefully.",
+  },
+};
diff --git a/web/src/refresh-components/messages/Message.stories.tsx b/web/src/refresh-components/messages/Message.stories.tsx
new file mode 100644
index 00000000000..7480954bcbc
--- /dev/null
+++ b/web/src/refresh-components/messages/Message.stories.tsx
@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Message from "./Message";
+
+const meta: Meta<typeof Message> = {
+  title: "refresh-components/messages/Message",
+  component: Message,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Message>;
+
+export const Default: Story = {
+  args: {
+    text: "This is a default message.",
+  },
+};
+
+export const FlashInfo: Story = {
+  args: {
+    flash: true,
+    info: true,
+    text: "Your changes have been saved.",
+    description: "The settings will take effect immediately.",
+  },
+};
+
+export const FlashSuccess: Story = {
+  args: {
+    flash: true,
+    success: true,
+    text: "Operation completed successfully!",
+  },
+};
+
+export const FlashWarning: Story = {
+  args: {
+    flash: true,
+    warning: true,
+    text: "Your session is about to expire.",
+    description: "Please save your work before the session ends.",
+  },
+};
+
+export const FlashError: Story = {
+  args: {
+    flash: true,
+    error: true,
+    text: "Something went wrong.",
+    description: "Please try again or contact support.",
+  },
+};
+
+export const StaticInfo: Story = {
+  args: {
+    static: true,
+    info: true,
+    text: "This is informational.",
+    description: "Here is some extra context.",
+  },
+};
+
+export const StaticSuccess: Story = {
+  args: {
+    static: true,
+    success: true,
+    text: "All checks passed.",
+  },
+};
+
+export const StaticWarning: Story = {
+  args: {
+    static: true,
+    warning: true,
+    text: "Proceed with caution.",
+  },
+};
+
+export const StaticError: Story = {
+  args: {
+    static: true,
+    error: true,
+    text: "Failed to load resource.",
+  },
+};
+
+export const MediumSize: Story = {
+  args: {
+    flash: true,
+    info: true,
+    medium: true,
+    text: "Medium sized message.",
+    description: "Compact layout for tight spaces.",
+  },
+};
+
+export const WithAction: Story = {
+  args: {
+    flash: true,
+    warning: true,
+    text: "Unsaved changes detected.",
+    actions: "Undo",
+    onAction: () => alert("Action clicked"),
+  },
+};
+
+export const WithoutIcon: Story = {
+  args: {
+    flash: true,
+    info: true,
+    icon: false,
+    text: "Message without an icon.",
+  },
+};
+
+export const WithoutCloseButton: Story = {
+  args: {
+    flash: true,
+    success: true,
+    close: false,
+    text: "This message cannot be dismissed.",
+  },
+};
+
+export const AllLevels: Story = {
+  name: "All Levels (Flash / Large)",
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+      <Message flash default text="Default flash message" />
+      <Message flash info text="Info flash message" />
+      <Message flash success text="Success flash message" />
+      <Message flash warning text="Warning flash message" />
+      <Message flash error text="Error flash message" />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/skeletons/ChatSessionSkeleton.stories.tsx b/web/src/refresh-components/skeletons/ChatSessionSkeleton.stories.tsx
new file mode 100644
index 00000000000..332fc9d65fc
--- /dev/null
+++ b/web/src/refresh-components/skeletons/ChatSessionSkeleton.stories.tsx
@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ChatSessionSkeleton from "./ChatSessionSkeleton";
+
+const meta: Meta<typeof ChatSessionSkeleton> = {
+  title: "refresh-components/Skeletons/ChatSessionSkeleton",
+  component: ChatSessionSkeleton,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatSessionSkeleton>;
+
+export const Default: Story = {};
+
+export const Multiple: Story = {
+  render: () => (
+    <div className="flex flex-col gap-1" style={{ width: 300 }}>
+      <ChatSessionSkeleton />
+      <ChatSessionSkeleton />
+      <ChatSessionSkeleton />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/skeletons/SidebarTabSkeleton.stories.tsx b/web/src/refresh-components/skeletons/SidebarTabSkeleton.stories.tsx
new file mode 100644
index 00000000000..5568492b200
--- /dev/null
+++ b/web/src/refresh-components/skeletons/SidebarTabSkeleton.stories.tsx
@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SidebarTabSkeleton from "./SidebarTabSkeleton";
+
+const meta: Meta<typeof SidebarTabSkeleton> = {
+  title: "refresh-components/Skeletons/SidebarTabSkeleton",
+  component: SidebarTabSkeleton,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SidebarTabSkeleton>;
+
+export const Default: Story = {};
+
+export const NarrowText: Story = {
+  args: {
+    textWidth: "w-1/3",
+  },
+};
+
+export const WideText: Story = {
+  args: {
+    textWidth: "w-full",
+  },
+};
+
+export const Multiple: Story = {
+  render: () => (
+    <div className="flex flex-col gap-1" style={{ width: 260 }}>
+      <SidebarTabSkeleton textWidth="w-3/4" />
+      <SidebarTabSkeleton textWidth="w-1/2" />
+      <SidebarTabSkeleton textWidth="w-2/3" />
+      <SidebarTabSkeleton textWidth="w-1/3" />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/table/DataTable.stories.tsx b/web/src/refresh-components/table/DataTable.stories.tsx
new file mode 100644
index 00000000000..11115dea550
--- /dev/null
+++ b/web/src/refresh-components/table/DataTable.stories.tsx
@@ -0,0 +1,365 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import DataTable from "./DataTable";
+import { createTableColumns } from "./columns";
+import type { OnyxColumnDef } from "./types";
+import Text from "@/refresh-components/texts/Text";
+
+// ---------------------------------------------------------------------------
+// Mock data
+// ---------------------------------------------------------------------------
+
+interface TeamMember {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: "active" | "invited" | "deactivated";
+  lastActive: string;
+}
+
+const MOCK_MEMBERS: TeamMember[] = [
+  {
+    id: "1",
+    name: "Alice Johnson",
+    email: "alice@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "2 hours ago",
+  },
+  {
+    id: "2",
+    name: "Bob Martinez",
+    email: "bob@acme.com",
+    role: "Editor",
+    status: "active",
+    lastActive: "5 minutes ago",
+  },
+  {
+    id: "3",
+    name: "Charlie Kim",
+    email: "charlie@acme.com",
+    role: "Viewer",
+    status: "invited",
+    lastActive: "Never",
+  },
+  {
+    id: "4",
+    name: "Diana Patel",
+    email: "diana@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "1 day ago",
+  },
+  {
+    id: "5",
+    name: "Ethan Lee",
+    email: "ethan@acme.com",
+    role: "Editor",
+    status: "deactivated",
+    lastActive: "3 weeks ago",
+  },
+  {
+    id: "6",
+    name: "Fiona Chen",
+    email: "fiona@acme.com",
+    role: "Viewer",
+    status: "active",
+    lastActive: "10 minutes ago",
+  },
+  {
+    id: "7",
+    name: "George Wu",
+    email: "george@acme.com",
+    role: "Editor",
+    status: "active",
+    lastActive: "1 hour ago",
+  },
+  {
+    id: "8",
+    name: "Hannah Davis",
+    email: "hannah@acme.com",
+    role: "Viewer",
+    status: "invited",
+    lastActive: "Never",
+  },
+  {
+    id: "9",
+    name: "Ivan Torres",
+    email: "ivan@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "30 minutes ago",
+  },
+  {
+    id: "10",
+    name: "Julia Nguyen",
+    email: "julia@acme.com",
+    role: "Editor",
+    status: "active",
+    lastActive: "3 hours ago",
+  },
+  {
+    id: "11",
+    name: "Kevin Brown",
+    email: "kevin@acme.com",
+    role: "Viewer",
+    status: "active",
+    lastActive: "Yesterday",
+  },
+  {
+    id: "12",
+    name: "Laura Smith",
+    email: "laura@acme.com",
+    role: "Editor",
+    status: "deactivated",
+    lastActive: "2 months ago",
+  },
+  {
+    id: "13",
+    name: "Mike Wilson",
+    email: "mike@acme.com",
+    role: "Viewer",
+    status: "active",
+    lastActive: "4 hours ago",
+  },
+  {
+    id: "14",
+    name: "Nina Garcia",
+    email: "nina@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "Just now",
+  },
+  {
+    id: "15",
+    name: "Oscar Ramirez",
+    email: "oscar@acme.com",
+    role: "Editor",
+    status: "invited",
+    lastActive: "Never",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+function getInitials(member: TeamMember): string {
+  return member.name
+    .split(" ")
+    .map((n) => n[0])
+    .join("")
+    .toUpperCase();
+}
+
+const tc = createTableColumns<TeamMember>();
+
+const defaultColumns: OnyxColumnDef<TeamMember>[] = [
+  tc.qualifier({
+    content: "avatar-user",
+    getInitials,
+    selectable: true,
+  }),
+  tc.column("name", { header: "Name", weight: 22, minWidth: 120 }),
+  tc.column("email", { header: "Email", weight: 28, minWidth: 150 }),
+  tc.column("role", { header: "Role", weight: 15, minWidth: 80 }),
+  tc.column("status", {
+    header: "Status",
+    weight: 15,
+    minWidth: 80,
+    cell: (value) => {
+      const colors: Record<string, string> = {
+        active: "text-status-success-02",
+        invited: "text-status-warning-02",
+        deactivated: "text-status-error-02",
+      };
+      return (
+        <Text mainUiBody className={colors[value]}>
+          {value.charAt(0).toUpperCase() + value.slice(1)}
+        </Text>
+      );
+    },
+  }),
+  tc.column("lastActive", {
+    header: "Last Active",
+    weight: 20,
+    minWidth: 100,
+    enableSorting: false,
+  }),
+  tc.actions(),
+];
+
+const columnsWithoutActions: OnyxColumnDef<TeamMember>[] = defaultColumns.slice(
+  0,
+  -1
+);
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta<typeof DataTable> = {
+  title: "refresh-components/table/DataTable",
+  component: DataTable,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ maxWidth: 960, padding: 16 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DataTable>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Basic table with all default features: qualifier column, data columns, and actions. */
+export const Default: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 8)}
+      columns={defaultColumns}
+    />
+  ),
+};
+
+/** Table with summary-mode footer showing "Showing X~Y of Z" and list pagination. */
+export const WithSummaryFooter: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      pageSize={5}
+      footer={{ mode: "summary" }}
+    />
+  ),
+};
+
+/** Table with selection-mode footer showing selected count and count pagination. */
+export const WithSelectionFooter: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      pageSize={5}
+      footer={{ mode: "selection" }}
+    />
+  ),
+};
+
+/** Table with initial sorting applied to the "name" column. */
+export const WithInitialSorting: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      pageSize={5}
+      footer={{ mode: "summary" }}
+      initialSorting={[{ id: "name", desc: false }]}
+    />
+  ),
+};
+
+/** Table with some columns hidden by default via initialColumnVisibility. */
+export const WithHiddenColumns: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 8)}
+      columns={defaultColumns}
+      initialColumnVisibility={{ email: false, lastActive: false }}
+    />
+  ),
+};
+
+/** Empty table with no data rows. */
+export const EmptyState: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={[]}
+      columns={defaultColumns}
+      footer={{ mode: "summary" }}
+    />
+  ),
+};
+
+/** Small size variant with denser spacing. */
+export const SmallSize: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 6)}
+      columns={defaultColumns}
+      size="small"
+      footer={{ mode: "summary" }}
+      pageSize={5}
+    />
+  ),
+};
+
+/** Table without actions column (no sorting/visibility popovers). */
+export const WithoutActions: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 8)}
+      columns={columnsWithoutActions}
+    />
+  ),
+};
+
+/** Table with a fixed max height and sticky header for scrollable content. */
+export const ScrollableFixedHeight: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      height={300}
+      headerBackground="var(--background-neutral-00)"
+      pageSize={Infinity}
+    />
+  ),
+};
+
+/** Table with onRowClick handler instead of default selection toggle. */
+export const WithRowClick: Story = {
+  render: () => {
+    function Demo() {
+      const [clicked, setClicked] = React.useState<string | null>(null);
+      return (
+        <div>
+          <DataTable<TeamMember>
+            getRowId={(row) => row.id}
+            data={MOCK_MEMBERS.slice(0, 5)}
+            columns={defaultColumns}
+            onRowClick={(row) => setClicked(row.name)}
+          />
+          {clicked && (
+            <Text mainUiBody text03 className="p-4">
+              Clicked: {clicked}
+            </Text>
+          )}
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
diff --git a/web/src/refresh-components/table/Footer.stories.tsx b/web/src/refresh-components/table/Footer.stories.tsx
new file mode 100644
index 00000000000..37b7ae56567
--- /dev/null
+++ b/web/src/refresh-components/table/Footer.stories.tsx
@@ -0,0 +1,183 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import Footer from "./Footer";
+import { TableSizeProvider } from "./TableSizeContext";
+
+const meta: Meta<typeof Footer> = {
+  title: "refresh-components/table/Footer",
+  component: Footer,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <TableSizeProvider size="regular">
+          <div style={{ maxWidth: 800, padding: 16 }}>
+            <Story />
+          </div>
+        </TableSizeProvider>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Footer>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Summary mode footer showing "Showing X~Y of Z" with list pagination. */
+export const SummaryMode: Story = {
+  render: function SummaryModeStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={(page - 1) * 10 + 1}
+        rangeEnd={Math.min(page * 10, 47)}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Summary mode on the last page. */
+export const SummaryLastPage: Story = {
+  render: function SummaryLastPageStory() {
+    const [page, setPage] = React.useState(5);
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={(page - 1) * 10 + 1}
+        rangeEnd={Math.min(page * 10, 47)}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Selection mode with no items selected. */
+export const SelectionNone: Story = {
+  render: function SelectionNoneStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect
+        selectionState="none"
+        selectedCount={0}
+        onClear={() => {}}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Selection mode with some items selected. */
+export const SelectionPartial: Story = {
+  render: function SelectionPartialStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect
+        selectionState="partial"
+        selectedCount={3}
+        onView={() => alert("View selected")}
+        onClear={() => alert("Clear selection")}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Selection mode with all items selected. */
+export const SelectionAll: Story = {
+  render: function SelectionAllStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect
+        selectionState="all"
+        selectedCount={10}
+        onView={() => alert("View selected")}
+        onClear={() => alert("Clear selection")}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Single-select mode (no multi-select). */
+export const SingleSelect: Story = {
+  render: function SingleSelectStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect={false}
+        selectionState="partial"
+        selectedCount={1}
+        onClear={() => alert("Clear selection")}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Small size variant. */
+export const SmallSize: Story = {
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <TableSizeProvider size="small">
+          <div style={{ maxWidth: 800, padding: 16 }}>
+            <Story />
+          </div>
+        </TableSizeProvider>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  render: function SmallSizeStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={(page - 1) * 10 + 1}
+        rangeEnd={Math.min(page * 10, 47)}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
diff --git a/web/src/refresh-components/table/Table.stories.tsx b/web/src/refresh-components/table/Table.stories.tsx
new file mode 100644
index 00000000000..451638a1b14
--- /dev/null
+++ b/web/src/refresh-components/table/Table.stories.tsx
@@ -0,0 +1,281 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import Table from "./Table";
+import TableHeader from "./TableHeader";
+import TableBody from "./TableBody";
+import TableRow from "./TableRow";
+import TableHead from "./TableHead";
+import TableCell from "./TableCell";
+import { TableSizeProvider } from "./TableSizeContext";
+import Text from "@/refresh-components/texts/Text";
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta<typeof Table> = {
+  title: "refresh-components/table/Table",
+  component: Table,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <TableSizeProvider size="regular">
+          <div style={{ maxWidth: 800, padding: 16 }}>
+            <Story />
+          </div>
+        </TableSizeProvider>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Table>;
+
+// ---------------------------------------------------------------------------
+// Sample data
+// ---------------------------------------------------------------------------
+
+const connectors = [
+  {
+    name: "Google Drive",
+    type: "Cloud Storage",
+    docs: 1_240,
+    status: "Active",
+  },
+  { name: "Confluence", type: "Wiki", docs: 856, status: "Active" },
+  { name: "Slack", type: "Messaging", docs: 3_102, status: "Syncing" },
+  { name: "Notion", type: "Wiki", docs: 412, status: "Paused" },
+  { name: "GitHub", type: "Code", docs: 2_890, status: "Active" },
+];
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** All primitive table components composed together (Table, TableHeader, TableBody, TableRow, TableHead, TableCell). */
+export const ComposedPrimitives: Story = {
+  render: () => (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead width={200}>Connector</TableHead>
+          <TableHead width={150}>Type</TableHead>
+          <TableHead width={120} alignment="right">
+            Documents
+          </TableHead>
+          <TableHead width={120}>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {connectors.map((c) => (
+          <TableRow key={c.name}>
+            <TableCell>
+              <Text mainUiBody>{c.name}</Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMuted text03>
+                {c.type}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMono text03>
+                {c.docs.toLocaleString()}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiBody>{c.status}</Text>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ),
+};
+
+/** Table rows with the "table" variant (bottom border instead of rounded corners). */
+export const TableVariantRows: Story = {
+  render: () => (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead width={200}>Connector</TableHead>
+          <TableHead width={150}>Type</TableHead>
+          <TableHead width={120}>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {connectors.map((c) => (
+          <TableRow key={c.name} variant="table">
+            <TableCell>
+              <Text mainUiBody>{c.name}</Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMuted text03>
+                {c.type}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiBody>{c.status}</Text>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ),
+};
+
+/** Row with selected state highlighted. */
+export const SelectedRows: Story = {
+  render: () => (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead width={200}>Connector</TableHead>
+          <TableHead width={150}>Type</TableHead>
+          <TableHead width={120}>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {connectors.map((c, i) => (
+          <TableRow key={c.name} selected={i === 1 || i === 3}>
+            <TableCell>
+              <Text mainUiBody>{c.name}</Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMuted text03>
+                {c.type}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiBody>{c.status}</Text>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ),
+};
+
+/** Sortable table headers with sort indicators. */
+export const SortableHeaders: Story = {
+  render: () => (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead width={200} sorted="ascending" onSort={() => {}}>
+            Connector
+          </TableHead>
+          <TableHead width={150} sorted="none" onSort={() => {}}>
+            Type
+          </TableHead>
+          <TableHead width={120} sorted="descending" onSort={() => {}}>
+            Documents
+          </TableHead>
+          <TableHead width={120}>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {connectors.map((c) => (
+          <TableRow key={c.name}>
+            <TableCell>
+              <Text mainUiBody>{c.name}</Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMuted text03>
+                {c.type}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMono text03>
+                {c.docs.toLocaleString()}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiBody>{c.status}</Text>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ),
+};
+
+/** Small size variant with denser spacing. */
+export const SmallSize: Story = {
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <TableSizeProvider size="small">
+          <div style={{ maxWidth: 800, padding: 16 }}>
+            <Story />
+          </div>
+        </TableSizeProvider>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  render: () => (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead width={200}>Connector</TableHead>
+          <TableHead width={150}>Type</TableHead>
+          <TableHead width={120}>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {connectors.map((c) => (
+          <TableRow key={c.name}>
+            <TableCell>
+              <Text secondaryBody>{c.name}</Text>
+            </TableCell>
+            <TableCell>
+              <Text secondaryBody text03>
+                {c.type}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text secondaryBody>{c.status}</Text>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ),
+};
+
+/** Disabled rows styling. */
+export const DisabledRows: Story = {
+  render: () => (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead width={200}>Connector</TableHead>
+          <TableHead width={150}>Type</TableHead>
+          <TableHead width={120}>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {connectors.map((c, i) => (
+          <TableRow key={c.name} disabled={i === 2 || i === 4}>
+            <TableCell>
+              <Text mainUiBody>{c.name}</Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiMuted text03>
+                {c.type}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <Text mainUiBody>{c.status}</Text>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ),
+};
diff --git a/web/src/refresh-components/texts/ExpandableTextDisplay.stories.tsx b/web/src/refresh-components/texts/ExpandableTextDisplay.stories.tsx
new file mode 100644
index 00000000000..ca6a19cbf68
--- /dev/null
+++ b/web/src/refresh-components/texts/ExpandableTextDisplay.stories.tsx
@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import ExpandableTextDisplay from "./ExpandableTextDisplay";
+
+const meta: Meta<typeof ExpandableTextDisplay> = {
+  title: "refresh-components/texts/ExpandableTextDisplay",
+  component: ExpandableTextDisplay,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+  },
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ExpandableTextDisplay>;
+
+const shortContent =
+  "This is a short piece of content that fits within the default line clamp.";
+
+const longContent = Array.from(
+  { length: 30 },
+  (_, i) =>
+    `Line ${i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit.`
+).join("\n");
+
+export const ShortContent: Story = {
+  args: {
+    title: "Short Content",
+    content: shortContent,
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    title: "Log Output",
+    content: longContent,
+  },
+};
+
+export const CustomMaxLines: Story = {
+  args: {
+    title: "Compact View",
+    content: longContent,
+    maxLines: 3,
+  },
+};
+
+export const WithSubtitle: Story = {
+  args: {
+    title: "Build Log",
+    content: longContent,
+    subtitle: "2.4 KB - 30 lines",
+  },
+};
+
+export const StreamingMode: Story = {
+  args: {
+    title: "Live Output",
+    content: longContent,
+    isStreaming: true,
+    maxLines: 5,
+  },
+};
+
+export const WithCustomRenderer: Story = {
+  args: {
+    title: "Formatted Content",
+    content:
+      "# Hello World\n\nThis is **bold** and this is *italic*.\n\n- Item 1\n- Item 2\n- Item 3",
+    renderContent: (content: string) => (
+      <pre
+        style={{
+          whiteSpace: "pre-wrap",
+          fontFamily: "monospace",
+          fontSize: 13,
+        }}
+      >
+        {content}
+      </pre>
+    ),
+  },
+};
diff --git a/web/src/refresh-components/texts/Text.stories.tsx b/web/src/refresh-components/texts/Text.stories.tsx
new file mode 100644
index 00000000000..09dddd6c425
--- /dev/null
+++ b/web/src/refresh-components/texts/Text.stories.tsx
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Text from "./Text";
+
+const meta: Meta<typeof Text> = {
+  title: "refresh-components/texts/Text",
+  component: Text,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Text>;
+
+export const Default: Story = {
+  args: {
+    children: "Hello, this is some default text.",
+  },
+};
+
+export const Colors: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+      <Text text01 mainUiBody>
+        text01 — Primary text color
+      </Text>
+      <Text text02 mainUiBody>
+        text02 — Secondary text color
+      </Text>
+      <Text text03 mainUiBody>
+        text03 — Tertiary text color
+      </Text>
+      <Text text04 mainUiBody>
+        text04 — Quaternary text color
+      </Text>
+      <Text text05 mainUiBody>
+        text05 — Quinary text color
+      </Text>
+    </div>
+  ),
+};
+
+export const Typography: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <Text headingH2>Heading H2</Text>
+      <Text mainContentBody>Main Content Body</Text>
+      <Text mainUiBody>Main UI Body</Text>
+      <Text secondaryBody>Secondary Body</Text>
+    </div>
+  ),
+};
+
+export const Emphasis: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+      <Text mainContentEmphasis>Main Content Emphasis</Text>
+      <Text mainUiAction>Main UI Action</Text>
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/texts/Truncated.stories.tsx b/web/src/refresh-components/texts/Truncated.stories.tsx
new file mode 100644
index 00000000000..9bd4893c910
--- /dev/null
+++ b/web/src/refresh-components/texts/Truncated.stories.tsx
@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Truncated from "./Truncated";
+
+const meta: Meta<typeof Truncated> = {
+  title: "refresh-components/texts/Truncated",
+  component: Truncated,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Truncated>;
+
+export const ShortText: Story = {
+  args: {
+    children: "Short text that fits.",
+    mainUiBody: true,
+    text04: true,
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 300 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const LongText: Story = {
+  args: {
+    children:
+      "This is a very long piece of text that will definitely get truncated because it exceeds the width of the container and should show a tooltip on hover.",
+    mainUiBody: true,
+    text04: true,
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 200 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const TooltipDisabled: Story = {
+  args: {
+    children:
+      "Long text but tooltip is disabled so it won't appear even when truncated.",
+    mainUiBody: true,
+    text03: true,
+    disable: true,
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 200 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const CustomTooltipSide: Story = {
+  args: {
+    children:
+      "Hover to see the tooltip appear on the right side instead of the default top.",
+    mainUiBody: true,
+    text04: true,
+    side: "right",
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 200, paddingTop: 40 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
diff --git a/web/src/refresh-components/tiles/ButtonTile.stories.tsx b/web/src/refresh-components/tiles/ButtonTile.stories.tsx
new file mode 100644
index 00000000000..94ce63a6b06
--- /dev/null
+++ b/web/src/refresh-components/tiles/ButtonTile.stories.tsx
@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ButtonTile from "./ButtonTile";
+import { SvgArrowRight, SvgPlus, SvgSettings, SvgSearch } from "@opal/icons";
+
+const meta: Meta<typeof ButtonTile> = {
+  title: "refresh-components/tiles/ButtonTile",
+  component: ButtonTile,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div style={{ maxWidth: 300 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ButtonTile>;
+
+export const Default: Story = {
+  args: {
+    title: "Create New",
+    description: "Start from scratch",
+    icon: SvgArrowRight,
+    onClick: () => {},
+  },
+};
+
+export const TitleOnly: Story = {
+  args: {
+    title: "Quick Action",
+    icon: SvgPlus,
+    onClick: () => {},
+  },
+};
+
+export const DescriptionOnly: Story = {
+  args: {
+    description: "Click to configure settings",
+    icon: SvgSettings,
+    onClick: () => {},
+  },
+};
+
+export const NoIcon: Story = {
+  args: {
+    title: "Simple Tile",
+    description: "Without an icon",
+    onClick: () => {},
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    title: "Unavailable",
+    description: "This feature is not enabled",
+    icon: SvgSettings,
+    disabled: true,
+  },
+};
+
+export const TileGrid: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns: "1fr 1fr",
+        gap: 8,
+        maxWidth: 500,
+      }}
+    >
+      <ButtonTile
+        title="Search"
+        description="Find documents"
+        icon={SvgSearch}
+        onClick={() => {}}
+      />
+      <ButtonTile
+        title="Create"
+        description="New document"
+        icon={SvgPlus}
+        onClick={() => {}}
+      />
+      <ButtonTile
+        title="Settings"
+        description="Configure"
+        icon={SvgSettings}
+        onClick={() => {}}
+      />
+      <ButtonTile
+        title="Disabled"
+        description="Not available"
+        icon={SvgArrowRight}
+        disabled
+      />
+    </div>
+  ),
+};
diff --git a/web/src/refresh-components/tiles/FileTile.stories.tsx b/web/src/refresh-components/tiles/FileTile.stories.tsx
new file mode 100644
index 00000000000..f8f2a7b8a02
--- /dev/null
+++ b/web/src/refresh-components/tiles/FileTile.stories.tsx
@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import FileTile from "./FileTile";
+import { SvgTextLines, SvgFiles } from "@opal/icons";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof FileTile> = {
+  title: "refresh-components/tiles/FileTile",
+  component: FileTile,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ maxWidth: 300 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof FileTile>;
+
+export const Default: Story = {
+  args: {
+    title: "document.pdf",
+    description: "Project proposal document",
+    icon: SvgTextLines,
+  },
+};
+
+export const WithOpen: Story = {
+  args: {
+    title: "report.xlsx",
+    description: "Quarterly report",
+    icon: SvgFiles,
+    onOpen: () => {},
+  },
+};
+
+export const WithRemove: Story = {
+  args: {
+    title: "notes.md",
+    description: "Meeting notes",
+    icon: SvgTextLines,
+    onRemove: () => {},
+  },
+};
+
+export const Processing: Story = {
+  args: {
+    title: "uploading.pdf",
+    description: "Processing...",
+    icon: SvgTextLines,
+    state: "processing",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    title: "locked.pdf",
+    description: "Access denied",
+    icon: SvgFiles,
+    state: "disabled",
+  },
+};
+
+export const TitleOnly: Story = {
+  args: {
+    title: "image.png",
+    icon: SvgFiles,
+  },
+};
+
+export const DefaultIcon: Story = {
+  args: {
+    title: "unknown-file",
+    description: "Uses default text lines icon",
+  },
+};
+
+export const FileList: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+      <FileTile
+        title="proposal.pdf"
+        description="2.4 MB"
+        icon={SvgTextLines}
+        onOpen={() => {}}
+        onRemove={() => {}}
+      />
+      <FileTile
+        title="report.xlsx"
+        description="1.1 MB"
+        icon={SvgFiles}
+        onOpen={() => {}}
+      />
+      <FileTile
+        title="uploading.doc"
+        description="Processing..."
+        icon={SvgTextLines}
+        state="processing"
+      />
+      <FileTile
+        title="locked.pdf"
+        description="No access"
+        icon={SvgFiles}
+        state="disabled"
+      />
+    </div>
+  ),
+};

From 8d085a4ccf53b31ec6ee689638dbbc5f9abab6bc Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Mon, 9 Mar 2026 19:40:53 -0700
Subject: [PATCH 202/267] ci: add Storybook deploy workflow - 3/3 (#9205)

---
 .github/workflows/storybook-deploy.yml | 69 ++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 .github/workflows/storybook-deploy.yml

diff --git a/.github/workflows/storybook-deploy.yml b/.github/workflows/storybook-deploy.yml
new file mode 100644
index 00000000000..c1f65126ad8
--- /dev/null
+++ b/.github/workflows/storybook-deploy.yml
@@ -0,0 +1,69 @@
+name: Storybook Deploy
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: prj_sG49mVsA25UsxIPhN2pmBJlikJZM
+  VERCEL_CLI: vercel@50.14.1
+  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+
+concurrency:
+  group: storybook-deploy-production
+  cancel-in-progress: true
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "web/lib/opal/**"
+      - "web/src/refresh-components/**"
+      - "web/.storybook/**"
+      - "web/package.json"
+      - "web/package-lock.json"
+permissions:
+  contents: read
+jobs:
+  Deploy-Storybook:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # ratchet:actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "npm"
+          cache-dependency-path: ./web/package-lock.json
+
+      - name: Install dependencies
+        working-directory: web
+        run: npm ci
+
+      - name: Build Storybook
+        working-directory: web
+        run: npm run storybook:build
+
+      - name: Deploy to Vercel (Production)
+        working-directory: web
+        run: npx --yes "$VERCEL_CLI" deploy storybook-static/ --prod --yes
+
+  notify-slack-on-failure:
+    needs: Deploy-Storybook
+    if: always() && needs.Deploy-Storybook.result == 'failure'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v4
+        with:
+          persist-credentials: false
+          sparse-checkout: .github/actions/slack-notify
+
+      - name: Send Slack notification
+        uses: ./.github/actions/slack-notify
+        with:
+          webhook-url: ${{ secrets.MONITOR_DEPLOYMENTS_WEBHOOK }}
+          failed-jobs: "• Deploy-Storybook"
+          title: "🚨 Storybook Deploy Failed"

From fef1fd093e9e4030f3142407b75353774048d358 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 9 Mar 2026 20:05:32 -0700
Subject: [PATCH 203/267] feat(fe): increase preview file type support &
 replace `TextViewModal` with `PreviewModal` variant (#9212)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 backend/onyx/file_processing/file_types.py    |   4 +
 web/src/app/app/message/CodeBlock.tsx         |  35 +-
 web/src/app/app/message/FileDisplay.tsx       |   4 +-
 .../app/shared/[chatId]/SharedChatDisplay.tsx |   4 +-
 web/src/app/nrf/NRFPage.tsx                   |   4 +-
 web/src/components/chat/MinimalMarkdown.tsx   |  12 +-
 .../tools/ExpandableContentWrapper.tsx        |   4 +-
 .../modals/PreviewModal/PreviewModal.tsx      |  17 +-
 .../sections/modals/PreviewModal/mimeUtils.ts |  50 +++
 .../PreviewModal/variants/CodePreview.tsx     |  22 ++
 .../PreviewModal/variants/codeVariant.tsx     |  19 +-
 .../PreviewModal/variants/dataVariant.tsx     |  25 +-
 .../modals/PreviewModal/variants/index.ts     |   2 +
 .../PreviewModal/variants/markdownVariant.tsx |   1 -
 .../PreviewModal/variants/textVariant.tsx     |  54 +++
 web/src/sections/modals/TextViewModal.tsx     | 333 ------------------
 16 files changed, 183 insertions(+), 407 deletions(-)
 create mode 100644 web/src/sections/modals/PreviewModal/mimeUtils.ts
 create mode 100644 web/src/sections/modals/PreviewModal/variants/CodePreview.tsx
 create mode 100644 web/src/sections/modals/PreviewModal/variants/textVariant.tsx
 delete mode 100644 web/src/sections/modals/TextViewModal.tsx

diff --git a/backend/onyx/file_processing/file_types.py b/backend/onyx/file_processing/file_types.py
index 9f419fc222d..68f547b7c2b 100644
--- a/backend/onyx/file_processing/file_types.py
+++ b/backend/onyx/file_processing/file_types.py
@@ -19,12 +19,16 @@ class OnyxMimeTypes:
         PLAIN_TEXT_MIME_TYPE,
         "text/markdown",
         "text/x-markdown",
+        "text/x-log",
         "text/x-config",
         "text/tab-separated-values",
         "application/json",
         "application/xml",
         "text/xml",
         "application/x-yaml",
+        "application/yaml",
+        "text/yaml",
+        "text/x-yaml",
     }
     DOCUMENT_MIME_TYPES = {
         PDF_MIME_TYPE,
diff --git a/web/src/app/app/message/CodeBlock.tsx b/web/src/app/app/message/CodeBlock.tsx
index 0a24511a3d9..f311b773570 100644
--- a/web/src/app/app/message/CodeBlock.tsx
+++ b/web/src/app/app/message/CodeBlock.tsx
@@ -7,6 +7,7 @@ interface CodeBlockProps {
   className?: string;
   children?: ReactNode;
   codeText: string;
+  showHeader?: boolean;
 }
 
 const MemoizedCodeLine = memo(({ content }: { content: ReactNode }) => (
@@ -17,6 +18,7 @@ export const CodeBlock = memo(function CodeBlock({
   className = "",
   children,
   codeText,
+  showHeader = true,
 }: CodeBlockProps) {
   const [copied, setCopied] = useState(false);
 
@@ -111,22 +113,27 @@ export const CodeBlock = memo(function CodeBlock({
   };
 
   return (
-    <div className="bg-background-tint-00 px-1 pb-1 rounded-12 max-w-full min-w-0">
-      {language && (
-        <div className="flex items-center px-2 py-1 text-sm text-text-04 gap-x-2">
-          <SvgCode
-            height={12}
-            width={12}
-            stroke="currentColor"
-            className="my-auto"
-          />
-          <Text secondaryMono>{language}</Text>
-          {codeText && <CopyButton />}
+    <>
+      {showHeader ? (
+        <div className="bg-background-tint-00 px-1 pb-1 rounded-12 max-w-full min-w-0">
+          {language && (
+            <div className="flex items-center px-2 py-1 text-sm text-text-04 gap-x-2">
+              <SvgCode
+                height={12}
+                width={12}
+                stroke="currentColor"
+                className="my-auto"
+              />
+              <Text secondaryMono>{language}</Text>
+              {codeText && <CopyButton />}
+            </div>
+          )}
+          <CodeContent />
         </div>
+      ) : (
+        <CodeContent />
       )}
-
-      <CodeContent />
-    </div>
+    </>
   );
 });
 
diff --git a/web/src/app/app/message/FileDisplay.tsx b/web/src/app/app/message/FileDisplay.tsx
index eff28c2da94..0fa6b8939af 100644
--- a/web/src/app/app/message/FileDisplay.tsx
+++ b/web/src/app/app/message/FileDisplay.tsx
@@ -5,7 +5,7 @@ import { ChatFileType, FileDescriptor } from "@/app/app/interfaces";
 import Attachment from "@/refresh-components/Attachment";
 import { InMessageImage } from "@/app/app/components/files/images/InMessageImage";
 import CsvContent from "@/components/tools/CSVContent";
-import TextViewModal from "@/sections/modals/TextViewModal";
+import PreviewModal from "@/sections/modals/PreviewModal";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import ExpandableContentWrapper from "@/components/tools/ExpandableContentWrapper";
 
@@ -34,7 +34,7 @@ export default function FileDisplay({ files }: FileDisplayProps) {
   return (
     <>
       {previewingFile && (
-        <TextViewModal
+        <PreviewModal
           presentingDocument={presentingDocument}
           onClose={() => setPreviewingFile(null)}
         />
diff --git a/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx b/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx
index 9649727753f..ffa12d3c09c 100644
--- a/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx
+++ b/web/src/app/app/shared/[chatId]/SharedChatDisplay.tsx
@@ -11,7 +11,7 @@ import { Callout } from "@/components/ui/callout";
 import OnyxInitializingLoader from "@/components/OnyxInitializingLoader";
 import { Persona } from "@/app/admin/agents/interfaces";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
-import TextViewModal from "@/sections/modals/TextViewModal";
+import PreviewModal from "@/sections/modals/PreviewModal";
 import { UNNAMED_CHAT } from "@/lib/constants";
 import Text from "@/refresh-components/texts/Text";
 import useOnMount from "@/hooks/useOnMount";
@@ -64,7 +64,7 @@ export default function SharedChatDisplay({
   return (
     <>
       {presentingDocument && (
-        <TextViewModal
+        <PreviewModal
           presentingDocument={presentingDocument}
           onClose={() => setPresentingDocument(null)}
         />
diff --git a/web/src/app/nrf/NRFPage.tsx b/web/src/app/nrf/NRFPage.tsx
index ff93044c278..2678138f888 100644
--- a/web/src/app/nrf/NRFPage.tsx
+++ b/web/src/app/nrf/NRFPage.tsx
@@ -40,7 +40,7 @@ import { SvgUser, SvgMenu, SvgAlertTriangle } from "@opal/icons";
 import { useAppBackground } from "@/providers/AppBackgroundProvider";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import DocumentsSidebar from "@/sections/document-sidebar/DocumentsSidebar";
-import TextViewModal from "@/sections/modals/TextViewModal";
+import PreviewModal from "@/sections/modals/PreviewModal";
 import { personaIncludesRetrieval } from "@/app/app/services/lib";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import { eeGated } from "@/ce";
@@ -537,7 +537,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
 
       {/* Text/document preview modal */}
       {presentingDocument && (
-        <TextViewModal
+        <PreviewModal
           presentingDocument={presentingDocument}
           onClose={() => setPresentingDocument(null)}
         />
diff --git a/web/src/components/chat/MinimalMarkdown.tsx b/web/src/components/chat/MinimalMarkdown.tsx
index 473dd460655..ce68c0c3ec9 100644
--- a/web/src/components/chat/MinimalMarkdown.tsx
+++ b/web/src/components/chat/MinimalMarkdown.tsx
@@ -4,7 +4,7 @@ import {
   MemoizedLink,
   MemoizedParagraph,
 } from "@/app/app/message/MemoizedTextComponents";
-import React, { useMemo, CSSProperties } from "react";
+import { useMemo, CSSProperties } from "react";
 import ReactMarkdown, { type Components } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import rehypeHighlight from "rehype-highlight";
@@ -19,6 +19,7 @@ interface MinimalMarkdownProps {
   content: string;
   className?: string;
   style?: CSSProperties;
+  showHeader?: boolean;
   /**
    * Override specific markdown renderers.
    * Any renderer not provided will fall back to this component's defaults.
@@ -30,6 +31,7 @@ export default function MinimalMarkdown({
   content,
   className = "",
   style,
+  showHeader = true,
   components,
 }: MinimalMarkdownProps) {
   const markdownComponents = useMemo(() => {
@@ -43,7 +45,11 @@ export default function MinimalMarkdown({
       code: ({ node, inline, className, children, ...props }: any) => {
         const codeText = extractCodeText(node, content, children);
         return (
-          <CodeBlock className={className} codeText={codeText}>
+          <CodeBlock
+            className={className}
+            codeText={codeText}
+            showHeader={showHeader}
+          >
             {children}
           </CodeBlock>
         );
@@ -54,7 +60,7 @@ export default function MinimalMarkdown({
       ...defaults,
       ...(components ?? {}),
     } satisfies Components;
-  }, [content, components]);
+  }, [content, components, showHeader]);
 
   return (
     <div style={style || {}} className={`${className}`}>
diff --git a/web/src/components/tools/ExpandableContentWrapper.tsx b/web/src/components/tools/ExpandableContentWrapper.tsx
index d7c1896502f..270e66aea52 100644
--- a/web/src/components/tools/ExpandableContentWrapper.tsx
+++ b/web/src/components/tools/ExpandableContentWrapper.tsx
@@ -6,7 +6,7 @@ import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
 import { FileDescriptor } from "@/app/app/interfaces";
 import { cn } from "@/lib/utils";
-import TextViewModal from "@/sections/modals/TextViewModal";
+import PreviewModal from "@/sections/modals/PreviewModal";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 
 export interface ExpandableContentWrapperProps {
@@ -102,7 +102,7 @@ export default function ExpandableContentWrapper({
   return (
     <>
       {expanded && (
-        <TextViewModal
+        <PreviewModal
           presentingDocument={presentingDocument}
           onClose={() => setExpanded(false)}
         />
diff --git a/web/src/sections/modals/PreviewModal/PreviewModal.tsx b/web/src/sections/modals/PreviewModal/PreviewModal.tsx
index 9da788b5348..cb52ac91ecd 100644
--- a/web/src/sections/modals/PreviewModal/PreviewModal.tsx
+++ b/web/src/sections/modals/PreviewModal/PreviewModal.tsx
@@ -10,18 +10,12 @@ import { Section } from "@/layouts/general-layouts";
 import { getCodeLanguage, getDataLanguage } from "@/lib/languages";
 import { fetchChatFile } from "@/lib/chat/svc";
 import { PreviewContext } from "@/sections/modals/PreviewModal/interfaces";
+import {
+  getMimeLanguage,
+  resolveMimeType,
+} from "@/sections/modals/PreviewModal/mimeUtils";
 import { resolveVariant } from "@/sections/modals/PreviewModal/variants";
 
-function resolveMimeType(mimeType: string, fileName: string): string {
-  if (mimeType !== "application/octet-stream") return mimeType;
-  const lower = fileName.toLowerCase();
-  if (lower.endsWith(".md") || lower.endsWith(".markdown"))
-    return "text/markdown";
-  if (lower.endsWith(".txt")) return "text/plain";
-  if (lower.endsWith(".csv")) return "text/csv";
-  return mimeType;
-}
-
 interface PreviewModalProps {
   presentingDocument: MinimalOnyxDocument;
   onClose: () => void;
@@ -47,9 +41,10 @@ export default function PreviewModal({
   const language = useMemo(
     () =>
       getCodeLanguage(presentingDocument.semantic_identifier || "") ||
+      getMimeLanguage(mimeType) ||
       getDataLanguage(presentingDocument.semantic_identifier || "") ||
       "plaintext",
-    [presentingDocument.semantic_identifier]
+    [mimeType, presentingDocument.semantic_identifier]
   );
 
   const lineCount = useMemo(() => {
diff --git a/web/src/sections/modals/PreviewModal/mimeUtils.ts b/web/src/sections/modals/PreviewModal/mimeUtils.ts
new file mode 100644
index 00000000000..2c31c817c6e
--- /dev/null
+++ b/web/src/sections/modals/PreviewModal/mimeUtils.ts
@@ -0,0 +1,50 @@
+const MIME_LANGUAGE_PREFIXES: Array<[prefix: string, language: string]> = [
+  ["application/json", "json"],
+  ["application/xml", "xml"],
+  ["text/xml", "xml"],
+  ["application/x-yaml", "yaml"],
+  ["application/yaml", "yaml"],
+  ["text/yaml", "yaml"],
+  ["text/x-yaml", "yaml"],
+];
+
+const OCTET_STREAM_EXTENSION_TO_MIME: Record<string, string> = {
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".conf": "text/plain",
+  ".sql": "text/plain",
+  ".csv": "text/csv",
+  ".tsv": "text/tab-separated-values",
+  ".json": "application/json",
+  ".xml": "application/xml",
+  ".yml": "application/x-yaml",
+  ".yaml": "application/x-yaml",
+};
+
+export function getMimeLanguage(mimeType: string): string | null {
+  return (
+    MIME_LANGUAGE_PREFIXES.find(([prefix]) =>
+      mimeType.startsWith(prefix)
+    )?.[1] ?? null
+  );
+}
+
+export function resolveMimeType(mimeType: string, fileName: string): string {
+  if (mimeType !== "application/octet-stream") {
+    return mimeType;
+  }
+
+  const lowerFileName = fileName.toLowerCase();
+
+  for (const [extension, resolvedMime] of Object.entries(
+    OCTET_STREAM_EXTENSION_TO_MIME
+  )) {
+    if (lowerFileName.endsWith(extension)) {
+      return resolvedMime;
+    }
+  }
+
+  return mimeType;
+}
diff --git a/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx b/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx
new file mode 100644
index 00000000000..f8c4ac12e42
--- /dev/null
+++ b/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
+import "@/app/app/message/custom-code-styles.css";
+
+interface CodePreviewProps {
+  content: string;
+  language?: string | null;
+}
+
+export function CodePreview({ content, language }: CodePreviewProps) {
+  const normalizedContent = content.replace(/~~~/g, "\\~\\~\\~");
+  const fenceHeader = language ? `~~~${language}` : "~~~";
+
+  return (
+    <MinimalMarkdown
+      content={`${fenceHeader}\n${normalizedContent}\n\n~~~`}
+      className="w-full h-full"
+      showHeader={false}
+    />
+  );
+}
diff --git a/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx b/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx
index ff576c42703..1106a44b8ac 100644
--- a/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx
@@ -1,10 +1,8 @@
-import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
 import Text from "@/refresh-components/texts/Text";
 import { Section } from "@/layouts/general-layouts";
 import { getCodeLanguage } from "@/lib/languages";
-import { CodeBlock } from "@/app/app/message/CodeBlock";
-import { extractCodeText } from "@/app/app/message/codeUtils";
 import { PreviewVariant } from "@/sections/modals/PreviewModal/interfaces";
+import { CodePreview } from "@/sections/modals/PreviewModal/variants/CodePreview";
 import {
   CopyButton,
   DownloadButton,
@@ -24,20 +22,7 @@ export const codeVariant: PreviewVariant = {
       : "",
 
   renderContent: (ctx) => (
-    <MinimalMarkdown
-      content={`\`\`\`${ctx.language}\n${ctx.fileContent}\n\n\`\`\``}
-      className="w-full break-words h-full"
-      components={{
-        code: ({ node, children }: any) => {
-          const codeText = extractCodeText(node, ctx.fileContent, children);
-          return (
-            <CodeBlock className="" codeText={codeText}>
-              {children}
-            </CodeBlock>
-          );
-        },
-      }}
-    />
+    <CodePreview content={ctx.fileContent} language={ctx.language} />
   ),
 
   renderFooterLeft: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx b/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx
index cf164a0cf90..c5dada9e789 100644
--- a/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx
@@ -1,10 +1,9 @@
-import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
 import Text from "@/refresh-components/texts/Text";
 import { Section } from "@/layouts/general-layouts";
 import { getDataLanguage } from "@/lib/languages";
-import { CodeBlock } from "@/app/app/message/CodeBlock";
-import { extractCodeText } from "@/app/app/message/codeUtils";
 import { PreviewVariant } from "@/sections/modals/PreviewModal/interfaces";
+import { getMimeLanguage } from "@/sections/modals/PreviewModal/mimeUtils";
+import { CodePreview } from "@/sections/modals/PreviewModal/variants/CodePreview";
 import {
   CopyButton,
   DownloadButton,
@@ -22,7 +21,8 @@ function formatContent(language: string, content: string): string {
 }
 
 export const dataVariant: PreviewVariant = {
-  matches: (name) => !!getDataLanguage(name || ""),
+  matches: (name, mime) =>
+    !!getDataLanguage(name || "") || !!getMimeLanguage(mime),
   width: "md",
   height: "lg",
   needsTextContent: true,
@@ -36,22 +36,7 @@ export const dataVariant: PreviewVariant = {
 
   renderContent: (ctx) => {
     const formatted = formatContent(ctx.language, ctx.fileContent);
-    return (
-      <MinimalMarkdown
-        content={`\`\`\`${ctx.language}\n${formatted}\n\n\`\`\``}
-        className="w-full break-words h-full"
-        components={{
-          code: ({ node, children }: any) => {
-            const codeText = extractCodeText(node, formatted, children);
-            return (
-              <CodeBlock className="" codeText={codeText}>
-                {children}
-              </CodeBlock>
-            );
-          },
-        }}
-      />
-    );
+    return <CodePreview content={formatted} language={ctx.language} />;
   },
 
   renderFooterLeft: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/index.ts b/web/src/sections/modals/PreviewModal/variants/index.ts
index 877f00bf458..3f8010ff8b2 100644
--- a/web/src/sections/modals/PreviewModal/variants/index.ts
+++ b/web/src/sections/modals/PreviewModal/variants/index.ts
@@ -5,6 +5,7 @@ import { pdfVariant } from "@/sections/modals/PreviewModal/variants/pdfVariant";
 import { csvVariant } from "@/sections/modals/PreviewModal/variants/csvVariant";
 import { markdownVariant } from "@/sections/modals/PreviewModal/variants/markdownVariant";
 import { dataVariant } from "@/sections/modals/PreviewModal/variants/dataVariant";
+import { textVariant } from "@/sections/modals/PreviewModal/variants/textVariant";
 import { unsupportedVariant } from "@/sections/modals/PreviewModal/variants/unsupportedVariant";
 import { docxVariant } from "@/sections/modals/PreviewModal/variants/docxVariant";
 
@@ -15,6 +16,7 @@ const PREVIEW_VARIANTS: PreviewVariant[] = [
   pdfVariant,
   csvVariant,
   dataVariant,
+  textVariant,
   markdownVariant,
   docxVariant,
 ];
diff --git a/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx b/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
index 6fae1e50d9d..d406169ac13 100644
--- a/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
@@ -11,7 +11,6 @@ import {
 const MARKDOWN_MIMES = [
   "text/markdown",
   "text/x-markdown",
-  "text/plain",
   "text/x-rst",
   "text/x-org",
 ];
diff --git a/web/src/sections/modals/PreviewModal/variants/textVariant.tsx b/web/src/sections/modals/PreviewModal/variants/textVariant.tsx
new file mode 100644
index 00000000000..1cdd2fa447e
--- /dev/null
+++ b/web/src/sections/modals/PreviewModal/variants/textVariant.tsx
@@ -0,0 +1,54 @@
+import Text from "@/refresh-components/texts/Text";
+import { Section } from "@/layouts/general-layouts";
+import { PreviewVariant } from "@/sections/modals/PreviewModal/interfaces";
+import { CodePreview } from "@/sections/modals/PreviewModal/variants/CodePreview";
+import {
+  CopyButton,
+  DownloadButton,
+} from "@/sections/modals/PreviewModal/variants/shared";
+
+const TEXT_MIMES = [
+  "text/plain",
+  "text/x-log",
+  "text/x-config",
+  "text/tab-separated-values",
+];
+
+const TEXT_EXTENSIONS = [".txt", ".log", ".conf", ".tsv"];
+
+export const textVariant: PreviewVariant = {
+  matches: (name, mime) => {
+    if (TEXT_MIMES.some((supportedMime) => mime.startsWith(supportedMime))) {
+      return true;
+    }
+
+    const lowerName = (name || "").toLowerCase();
+    return TEXT_EXTENSIONS.some((extension) => lowerName.endsWith(extension));
+  },
+  width: "md",
+  height: "lg",
+  needsTextContent: true,
+  headerDescription: (ctx) =>
+    ctx.fileContent
+      ? `${ctx.lineCount} ${ctx.lineCount === 1 ? "line" : "lines"} · ${
+          ctx.fileSize
+        }`
+      : "",
+
+  renderContent: (ctx) => (
+    <CodePreview content={ctx.fileContent} language={ctx.language} />
+  ),
+
+  renderFooterLeft: (ctx) => (
+    <Text text03 mainUiBody className="select-none">
+      {ctx.lineCount} {ctx.lineCount === 1 ? "line" : "lines"}
+    </Text>
+  ),
+
+  renderFooterRight: (ctx) => (
+    <Section flexDirection="row" width="fit">
+      <CopyButton getText={() => ctx.fileContent} />
+      <DownloadButton fileUrl={ctx.fileUrl} fileName={ctx.fileName} />
+    </Section>
+  ),
+};
diff --git a/web/src/sections/modals/TextViewModal.tsx b/web/src/sections/modals/TextViewModal.tsx
deleted file mode 100644
index fa39b816d5f..00000000000
--- a/web/src/sections/modals/TextViewModal.tsx
+++ /dev/null
@@ -1,333 +0,0 @@
-"use client";
-
-import { useState, useEffect, useCallback, useMemo } from "react";
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from "@/components/ui/table";
-import { MinimalOnyxDocument } from "@/lib/search/interfaces";
-import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
-import { Button } from "@opal/components";
-import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
-import Text from "@/refresh-components/texts/Text";
-import {
-  SvgDownloadCloud,
-  SvgFileText,
-  SvgZoomIn,
-  SvgZoomOut,
-} from "@opal/icons";
-import PreviewImage from "@/refresh-components/PreviewImage";
-import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
-import ScrollIndicatorDiv from "@/refresh-components/ScrollIndicatorDiv";
-import { cn } from "@/lib/utils";
-import { Section } from "@/layouts/general-layouts";
-
-export interface TextViewProps {
-  presentingDocument: MinimalOnyxDocument;
-  onClose: () => void;
-}
-
-export default function TextViewModal({
-  presentingDocument,
-  onClose,
-}: TextViewProps) {
-  const [zoom, setZoom] = useState(100);
-  const [fileContent, setFileContent] = useState("");
-  const [fileUrl, setFileUrl] = useState("");
-  const [fileName, setFileName] = useState("");
-  const [isLoading, setIsLoading] = useState(true);
-  const [loadError, setLoadError] = useState<string | null>(null);
-  const [fileType, setFileType] = useState("application/octet-stream");
-  const csvData = useMemo(() => {
-    if (!fileType.startsWith("text/csv")) {
-      return null;
-    }
-
-    const lines = fileContent.split(/\r?\n/).filter((l) => l.length > 0);
-    const headers = lines.length > 0 ? lines[0]?.split(",") ?? [] : [];
-    const rows = lines.slice(1).map((line) => line.split(","));
-
-    return { headers, rows } as { headers: string[]; rows: string[][] };
-  }, [fileContent, fileType]);
-
-  // Detect if a given MIME type is one of the recognized markdown formats
-  const isMarkdownFormat = (mimeType: string): boolean => {
-    const markdownFormats = [
-      "text/markdown",
-      "text/x-markdown",
-      "text/plain",
-      "text/csv",
-      "text/x-rst",
-      "text/x-org",
-      "txt",
-    ];
-    return markdownFormats.some((format) => mimeType.startsWith(format));
-  };
-
-  const isImageFormat = (mimeType: string) => {
-    const imageFormats = [
-      "image/png",
-      "image/jpeg",
-      "image/gif",
-      "image/svg+xml",
-    ];
-    return imageFormats.some((format) => mimeType.startsWith(format));
-  };
-  // Detect if a given MIME type can be rendered in an <iframe>
-  const isSupportedIframeFormat = (mimeType: string): boolean => {
-    const supportedFormats = [
-      "application/pdf",
-      "image/png",
-      "image/jpeg",
-      "image/gif",
-      "image/svg+xml",
-    ];
-    return supportedFormats.some((format) => mimeType.startsWith(format));
-  };
-
-  const fetchFile = useCallback(
-    async (signal?: AbortSignal) => {
-      setIsLoading(true);
-      setLoadError(null);
-      setFileContent("");
-      const fileIdLocal =
-        presentingDocument.document_id.split("__")[1] ||
-        presentingDocument.document_id;
-
-      try {
-        const response = await fetch(
-          `/api/chat/file/${encodeURIComponent(fileIdLocal)}`,
-          {
-            method: "GET",
-            signal,
-            cache: "force-cache",
-          }
-        );
-
-        if (!response.ok) {
-          setLoadError("Failed to load document.");
-          return;
-        }
-
-        const blob = await response.blob();
-        const url = window.URL.createObjectURL(blob);
-        setFileUrl((prev) => {
-          if (prev) {
-            window.URL.revokeObjectURL(prev);
-          }
-          return url;
-        });
-
-        const originalFileName =
-          presentingDocument.semantic_identifier || "document";
-        setFileName(originalFileName);
-
-        let contentType =
-          response.headers.get("Content-Type") || "application/octet-stream";
-
-        // If it's octet-stream but file name suggests a text-based extension, override accordingly
-        if (contentType === "application/octet-stream") {
-          const lowerName = originalFileName.toLowerCase();
-          if (lowerName.endsWith(".md") || lowerName.endsWith(".markdown")) {
-            contentType = "text/markdown";
-          } else if (lowerName.endsWith(".txt")) {
-            contentType = "text/plain";
-          } else if (lowerName.endsWith(".csv")) {
-            contentType = "text/csv";
-          }
-        }
-        setFileType(contentType);
-
-        // If the final content type looks like markdown, read its text
-        if (isMarkdownFormat(contentType)) {
-          const text = await blob.text();
-          setFileContent(text);
-        }
-      } catch (error) {
-        // Abort is expected on unmount / doc change
-        if (signal?.aborted) {
-          return;
-        }
-        setLoadError("Failed to load document.");
-      } finally {
-        // Prevent stale/aborted requests from clobbering the loading state.
-        // This is especially important in React StrictMode where effects can run twice.
-        if (!signal?.aborted) {
-          setIsLoading(false);
-        }
-      }
-    },
-    [presentingDocument]
-  );
-
-  useEffect(() => {
-    const controller = new AbortController();
-    fetchFile(controller.signal);
-    return () => {
-      controller.abort();
-    };
-  }, [fetchFile]);
-
-  useEffect(() => {
-    return () => {
-      if (fileUrl) {
-        window.URL.revokeObjectURL(fileUrl);
-      }
-    };
-  }, [fileUrl]);
-
-  const handleDownload = () => {
-    const link = document.createElement("a");
-    link.href = fileUrl;
-    link.download = fileName || presentingDocument.document_id;
-    document.body.appendChild(link);
-    link.click();
-    document.body.removeChild(link);
-  };
-
-  const handleZoomIn = () => setZoom((prev) => Math.min(prev + 25, 200));
-  const handleZoomOut = () => setZoom((prev) => Math.max(prev - 25, 100));
-
-  return (
-    <Modal
-      open
-      onOpenChange={(open) => {
-        if (!open) {
-          onClose();
-        }
-      }}
-    >
-      <Modal.Content
-        width="lg"
-        height="full"
-        preventAccidentalClose={false}
-        onOpenAutoFocus={(e) => e.preventDefault()}
-      >
-        <Modal.Header
-          icon={SvgFileText}
-          title={fileName || "Document"}
-          onClose={onClose}
-        >
-          <Section flexDirection="row" justifyContent="start" gap={0.25}>
-            <Button
-              prominence="tertiary"
-              onClick={handleZoomOut}
-              icon={SvgZoomOut}
-              tooltip="Zoom Out"
-            />
-            <Text mainUiBody>{zoom}%</Text>
-            <Button
-              prominence="tertiary"
-              onClick={handleZoomIn}
-              icon={SvgZoomIn}
-              tooltip="Zoom In"
-            />
-            <Button
-              prominence="tertiary"
-              onClick={handleDownload}
-              icon={SvgDownloadCloud}
-              tooltip="Download"
-            />
-          </Section>
-        </Modal.Header>
-
-        <Modal.Body>
-          <Section>
-            {isLoading ? (
-              <SimpleLoader className="h-8 w-8" />
-            ) : loadError ? (
-              <Text text03 mainUiBody>
-                {loadError}
-              </Text>
-            ) : (
-              <div
-                className="flex flex-col flex-1 min-h-0 min-w-0 w-full transform origin-center transition-transform duration-300 ease-in-out"
-                style={{ transform: `scale(${zoom / 100})` }}
-              >
-                {isImageFormat(fileType) ? (
-                  <PreviewImage
-                    src={fileUrl}
-                    alt={fileName}
-                    className="w-full flex-1 min-h-0"
-                  />
-                ) : isSupportedIframeFormat(fileType) ? (
-                  <iframe
-                    src={`${fileUrl}#toolbar=0`}
-                    className="w-full h-full flex-1 min-h-0 border-none"
-                    title="File Viewer"
-                  />
-                ) : isMarkdownFormat(fileType) ? (
-                  <ScrollIndicatorDiv
-                    className="flex-1 min-h-0 p-4"
-                    variant="shadow"
-                  >
-                    {csvData ? (
-                      <Table>
-                        <TableHeader className="sticky top-0 z-sticky">
-                          <TableRow className="bg-background-tint-02">
-                            {csvData.headers.map((h, i) => (
-                              <TableHead key={i}>
-                                <Text
-                                  as="p"
-                                  className="line-clamp-2 font-medium"
-                                  text03
-                                  mainUiBody
-                                >
-                                  {h}
-                                </Text>
-                              </TableHead>
-                            ))}
-                          </TableRow>
-                        </TableHeader>
-                        <TableBody>
-                          {csvData.rows.map((row, rIdx) => (
-                            <TableRow key={rIdx}>
-                              {csvData.headers.map((_, cIdx) => (
-                                <TableCell
-                                  key={cIdx}
-                                  className={cn(
-                                    cIdx === 0 &&
-                                      "sticky left-0 bg-background-tint-01",
-                                    "py-0 px-4 whitespace-normal break-words"
-                                  )}
-                                >
-                                  {row?.[cIdx] ?? ""}
-                                </TableCell>
-                              ))}
-                            </TableRow>
-                          ))}
-                        </TableBody>
-                      </Table>
-                    ) : (
-                      <MinimalMarkdown
-                        content={fileContent}
-                        className="w-full pb-4 h-full text-lg break-words"
-                      />
-                    )}
-                  </ScrollIndicatorDiv>
-                ) : (
-                  <div className="flex flex-col items-center justify-center flex-1 min-h-0 p-6 gap-4">
-                    <Text as="p" text03 mainUiBody>
-                      This file format is not supported for preview.
-                    </Text>
-                    <Button onClick={handleDownload}>Download File</Button>
-                  </div>
-                )}
-              </div>
-            )}
-          </Section>
-        </Modal.Body>
-
-        <Modal.Footer>
-          <BasicModalFooter
-            submit={<Button onClick={handleDownload}>Download File</Button>}
-          />
-        </Modal.Footer>
-      </Modal.Content>
-    </Modal>
-  );
-}

From a887bc616cb92821cd5ad8640861514f099b32cd Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Mon, 9 Mar 2026 21:32:44 -0700
Subject: [PATCH 204/267] fix(fe): preview modal fade matches code bg color
 (#9221)

---
 web/src/app/app/message/custom-code-styles.css        | 4 ++--
 web/src/app/css/colors.css                            | 6 ++++++
 web/src/sections/modals/PreviewModal/PreviewModal.tsx | 2 +-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/web/src/app/app/message/custom-code-styles.css b/web/src/app/app/message/custom-code-styles.css
index 8b2d46c2d7c..602192e458f 100644
--- a/web/src/app/app/message/custom-code-styles.css
+++ b/web/src/app/app/message/custom-code-styles.css
@@ -1,7 +1,7 @@
 /* Light mode syntax highlighting (Atom One Light) */
 .hljs {
   color: #383a42 !important;
-  background: #fafafa !important;
+  background: var(--background-code-01) !important;
 }
 
 .hljs-comment,
@@ -77,7 +77,7 @@
 /* Dark mode syntax highlighting (Atom One Dark) */
 .dark .hljs {
   color: #e2e6eb !important;
-  background: #151617 !important;
+  background: var(--background-code-01) !important;
 }
 
 .dark .hljs-comment,
diff --git a/web/src/app/css/colors.css b/web/src/app/css/colors.css
index 68dc4ebdb39..852d8b78830 100644
--- a/web/src/app/css/colors.css
+++ b/web/src/app/css/colors.css
@@ -438,6 +438,9 @@
   --action-text-link-05: var(--blue-50);
   --action-text-danger-05: var(--red-50);
 
+  /* Background / Code */
+  --background-code-01: var(--grey-02);
+
   /* Code */
   --code-code: var(--alpha-grey-100-85);
   --code-comment: var(--alpha-grey-100-35);
@@ -639,6 +642,9 @@
   --action-text-link-05: var(--blue-45);
   --action-text-danger-05: var(--red-45);
 
+  /* Background / Code */
+  --background-code-01: #151617;
+
   /* Code */
   --code-code: var(--alpha-grey-00-85);
   --code-comment: var(--alpha-grey-00-45);
diff --git a/web/src/sections/modals/PreviewModal/PreviewModal.tsx b/web/src/sections/modals/PreviewModal/PreviewModal.tsx
index cb52ac91ecd..f446201fe9f 100644
--- a/web/src/sections/modals/PreviewModal/PreviewModal.tsx
+++ b/web/src/sections/modals/PreviewModal/PreviewModal.tsx
@@ -195,7 +195,7 @@ export default function PreviewModal({
             )}
             style={{
               background:
-                "linear-gradient(to top, var(--background-tint-01) 40%, transparent)",
+                "linear-gradient(to top, var(--background-code-01) 40%, transparent)",
             }}
           >
             {/* Left slot */}

From cf74afc65e18f1ea2f10200dd9f32f3bf9cee6a2 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Mon, 9 Mar 2026 22:02:31 -0700
Subject: [PATCH 205/267] fix: assistant file transfer (#9163)

---
 backend/ee/onyx/access/access.py              |  65 +++++++
 backend/ee/onyx/db/persona.py                 |   9 +
 backend/onyx/access/access.py                 |  66 +++++--
 .../tasks/user_file_processing/tasks.py       |  29 +++-
 backend/onyx/db/persona.py                    |  26 +++
 backend/onyx/db/user_file.py                  |  30 ++++
 .../connectors/gitlab/test_gitlab_basic.py    |   2 +-
 .../unit/onyx/access/test_user_file_access.py | 163 ++++++++++++++++++
 .../test_user_file_impl_redis_locking.py      |   8 +-
 .../test_user_file_processing_no_vectordb.py  |  20 ++-
 10 files changed, 389 insertions(+), 29 deletions(-)
 create mode 100644 backend/tests/unit/onyx/access/test_user_file_access.py

diff --git a/backend/ee/onyx/access/access.py b/backend/ee/onyx/access/access.py
index 5add4468e80..62c42e315bf 100644
--- a/backend/ee/onyx/access/access.py
+++ b/backend/ee/onyx/access/access.py
@@ -9,12 +9,15 @@
     _get_access_for_documents as get_access_for_documents_without_groups,
 )
 from onyx.access.access import _get_acl_for_user as get_acl_for_user_without_groups
+from onyx.access.access import collect_user_file_access
 from onyx.access.models import DocumentAccess
 from onyx.access.utils import prefix_external_group
 from onyx.access.utils import prefix_user_group
 from onyx.db.document import get_document_sources
 from onyx.db.document import get_documents_by_ids
 from onyx.db.models import User
+from onyx.db.models import UserFile
+from onyx.db.user_file import fetch_user_files_with_access_relationships
 from onyx.utils.logger import setup_logger
 
 
@@ -116,6 +119,68 @@ def _get_access_for_documents(
     return access_map
 
 
+def _collect_user_file_group_names(user_file: UserFile) -> set[str]:
+    """Extract user-group names from the already-loaded Persona.groups
+    relationships on a UserFile (skipping deleted personas)."""
+    groups: set[str] = set()
+    for persona in user_file.assistants:
+        if persona.deleted:
+            continue
+        for group in persona.groups:
+            groups.add(group.name)
+    return groups
+
+
+def get_access_for_user_files_impl(
+    user_file_ids: list[str],
+    db_session: Session,
+) -> dict[str, DocumentAccess]:
+    """EE version: extends the MIT user file ACL with user group names
+    from personas shared via user groups.
+
+    Uses a single DB query (via fetch_user_files_with_access_relationships)
+    that eagerly loads both the MIT-needed and EE-needed relationships.
+
+    NOTE: is imported in onyx.access.access by `fetch_versioned_implementation`
+    DO NOT REMOVE."""
+    user_files = fetch_user_files_with_access_relationships(
+        user_file_ids, db_session, eager_load_groups=True
+    )
+    return build_access_for_user_files_impl(user_files)
+
+
+def build_access_for_user_files_impl(
+    user_files: list[UserFile],
+) -> dict[str, DocumentAccess]:
+    """EE version: works on pre-loaded UserFile objects.
+    Expects Persona.groups to be eagerly loaded.
+
+    NOTE: is imported in onyx.access.access by `fetch_versioned_implementation`
+    DO NOT REMOVE."""
+    result: dict[str, DocumentAccess] = {}
+    for user_file in user_files:
+        if user_file.user is None:
+            result[str(user_file.id)] = DocumentAccess.build(
+                user_emails=[],
+                user_groups=[],
+                is_public=True,
+                external_user_emails=[],
+                external_user_group_ids=[],
+            )
+            continue
+
+        emails, is_public = collect_user_file_access(user_file)
+        group_names = _collect_user_file_group_names(user_file)
+        result[str(user_file.id)] = DocumentAccess.build(
+            user_emails=list(emails),
+            user_groups=list(group_names),
+            is_public=is_public,
+            external_user_emails=[],
+            external_user_group_ids=[],
+        )
+    return result
+
+
 def _get_acl_for_user(user: User, db_session: Session) -> set[str]:
     """Returns a list of ACL entries that the user has access to. This is meant to be
     used downstream to filter out documents that the user does not have access to. The
diff --git a/backend/ee/onyx/db/persona.py b/backend/ee/onyx/db/persona.py
index 98562e59ea6..0fcef8e89c4 100644
--- a/backend/ee/onyx/db/persona.py
+++ b/backend/ee/onyx/db/persona.py
@@ -7,6 +7,7 @@
 from onyx.db.models import Persona__User
 from onyx.db.models import Persona__UserGroup
 from onyx.db.notification import create_notification
+from onyx.db.persona import mark_persona_user_files_for_sync
 from onyx.server.features.persona.models import PersonaSharedNotificationData
 
 
@@ -26,7 +27,9 @@ def update_persona_access(
 
     NOTE: Callers are responsible for committing."""
 
+    needs_sync = False
     if is_public is not None:
+        needs_sync = True
         persona = db_session.query(Persona).filter(Persona.id == persona_id).first()
         if persona:
             persona.is_public = is_public
@@ -35,6 +38,7 @@ def update_persona_access(
     # and a non-empty list means "replace with these shares".
 
     if user_ids is not None:
+        needs_sync = True
         db_session.query(Persona__User).filter(
             Persona__User.persona_id == persona_id
         ).delete(synchronize_session="fetch")
@@ -54,6 +58,7 @@ def update_persona_access(
                 )
 
     if group_ids is not None:
+        needs_sync = True
         db_session.query(Persona__UserGroup).filter(
             Persona__UserGroup.persona_id == persona_id
         ).delete(synchronize_session="fetch")
@@ -63,3 +68,7 @@ def update_persona_access(
             db_session.add(
                 Persona__UserGroup(persona_id=persona_id, user_group_id=group_id)
             )
+
+    # When sharing changes, user file ACLs need to be updated in the vector DB
+    if needs_sync:
+        mark_persona_user_files_for_sync(persona_id, db_session)
diff --git a/backend/onyx/access/access.py b/backend/onyx/access/access.py
index 6871bfe8ae1..49d93ac6d19 100644
--- a/backend/onyx/access/access.py
+++ b/backend/onyx/access/access.py
@@ -1,7 +1,6 @@
 from collections.abc import Callable
 from typing import cast
 
-from sqlalchemy.orm import joinedload
 from sqlalchemy.orm import Session
 
 from onyx.access.models import DocumentAccess
@@ -12,6 +11,7 @@
 from onyx.db.document import get_access_info_for_documents
 from onyx.db.models import User
 from onyx.db.models import UserFile
+from onyx.db.user_file import fetch_user_files_with_access_relationships
 from onyx.utils.variable_functionality import fetch_ee_implementation_or_noop
 from onyx.utils.variable_functionality import fetch_versioned_implementation
 
@@ -132,19 +132,61 @@ def get_access_for_user_files(
     user_file_ids: list[str],
     db_session: Session,
 ) -> dict[str, DocumentAccess]:
-    user_files = (
-        db_session.query(UserFile)
-        .options(joinedload(UserFile.user))  # Eager load the user relationship
-        .filter(UserFile.id.in_(user_file_ids))
-        .all()
+    versioned_fn = fetch_versioned_implementation(
+        "onyx.access.access", "get_access_for_user_files_impl"
     )
-    return {
-        str(user_file.id): DocumentAccess.build(
-            user_emails=[user_file.user.email] if user_file.user else [],
+    return versioned_fn(user_file_ids, db_session)
+
+
+def get_access_for_user_files_impl(
+    user_file_ids: list[str],
+    db_session: Session,
+) -> dict[str, DocumentAccess]:
+    user_files = fetch_user_files_with_access_relationships(user_file_ids, db_session)
+    return build_access_for_user_files_impl(user_files)
+
+
+def build_access_for_user_files(
+    user_files: list[UserFile],
+) -> dict[str, DocumentAccess]:
+    """Compute access from pre-loaded UserFile objects (with relationships).
+    Callers must ensure UserFile.user, Persona.users, and Persona.user are
+    eagerly loaded (and Persona.groups for the EE path)."""
+    versioned_fn = fetch_versioned_implementation(
+        "onyx.access.access", "build_access_for_user_files_impl"
+    )
+    return versioned_fn(user_files)
+
+
+def build_access_for_user_files_impl(
+    user_files: list[UserFile],
+) -> dict[str, DocumentAccess]:
+    result: dict[str, DocumentAccess] = {}
+    for user_file in user_files:
+        emails, is_public = collect_user_file_access(user_file)
+        result[str(user_file.id)] = DocumentAccess.build(
+            user_emails=list(emails),
             user_groups=[],
-            is_public=True if user_file.user is None else False,
+            is_public=is_public,
             external_user_emails=[],
             external_user_group_ids=[],
         )
-        for user_file in user_files
-    }
+    return result
+
+
+def collect_user_file_access(user_file: UserFile) -> tuple[set[str], bool]:
+    """Collect all user emails that should have access to this user file.
+    Includes the owner plus any users who have access via shared personas.
+    Returns (emails, is_public)."""
+    emails: set[str] = {user_file.user.email}
+    is_public = False
+    for persona in user_file.assistants:
+        if persona.deleted:
+            continue
+        if persona.is_public:
+            is_public = True
+        if persona.user_id is not None and persona.user:
+            emails.add(persona.user.email)
+        for shared_user in persona.users:
+            emails.add(shared_user.email)
+    return emails, is_public
diff --git a/backend/onyx/background/celery/tasks/user_file_processing/tasks.py b/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
index 8f088c0f693..6208f884817 100644
--- a/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
+++ b/backend/onyx/background/celery/tasks/user_file_processing/tasks.py
@@ -12,9 +12,9 @@
 from redis.lock import Lock as RedisLock
 from retry import retry
 from sqlalchemy import select
-from sqlalchemy.orm import selectinload
 from sqlalchemy.orm import Session
 
+from onyx.access.access import build_access_for_user_files
 from onyx.background.celery.apps.app_base import task_logger
 from onyx.background.celery.celery_redis import celery_get_queue_length
 from onyx.background.celery.celery_utils import httpx_init_vespa_pool
@@ -43,7 +43,9 @@
 from onyx.db.models import UserFile
 from onyx.db.search_settings import get_active_search_settings
 from onyx.db.search_settings import get_active_search_settings_list
+from onyx.db.user_file import fetch_user_files_with_access_relationships
 from onyx.document_index.factory import get_all_document_indices
+from onyx.document_index.interfaces import VespaDocumentFields
 from onyx.document_index.interfaces import VespaDocumentUserFields
 from onyx.document_index.vespa_constants import DOCUMENT_ID_ENDPOINT
 from onyx.file_store.file_store import get_default_file_store
@@ -54,6 +56,7 @@
 from onyx.indexing.embedder import DefaultIndexingEmbedder
 from onyx.indexing.indexing_pipeline import run_indexing_pipeline
 from onyx.redis.redis_pool import get_redis_client
+from onyx.utils.variable_functionality import global_version
 
 
 def _as_uuid(value: str | UUID) -> UUID:
@@ -791,11 +794,12 @@ def project_sync_user_file_impl(
 
     try:
         with get_session_with_current_tenant() as db_session:
-            user_file = db_session.execute(
-                select(UserFile)
-                .where(UserFile.id == _as_uuid(user_file_id))
-                .options(selectinload(UserFile.assistants))
-            ).scalar_one_or_none()
+            user_files = fetch_user_files_with_access_relationships(
+                [user_file_id],
+                db_session,
+                eager_load_groups=global_version.is_ee_version(),
+            )
+            user_file = user_files[0] if user_files else None
             if not user_file:
                 task_logger.info(
                     f"project_sync_user_file_impl - User file not found id={user_file_id}"
@@ -823,12 +827,21 @@ def project_sync_user_file_impl(
 
                 project_ids = [project.id for project in user_file.projects]
                 persona_ids = [p.id for p in user_file.assistants if not p.deleted]
+
+                file_id_str = str(user_file.id)
+                access_map = build_access_for_user_files([user_file])
+                access = access_map.get(file_id_str)
+
                 for retry_document_index in retry_document_indices:
                     retry_document_index.update_single(
-                        doc_id=str(user_file.id),
+                        doc_id=file_id_str,
                         tenant_id=tenant_id,
                         chunk_count=user_file.chunk_count,
-                        fields=None,
+                        fields=(
+                            VespaDocumentFields(access=access)
+                            if access is not None
+                            else None
+                        ),
                         user_fields=VespaDocumentUserFields(
                             user_projects=project_ids,
                             personas=persona_ids,
diff --git a/backend/onyx/db/persona.py b/backend/onyx/db/persona.py
index a35c0c6d26f..3c396b563eb 100644
--- a/backend/onyx/db/persona.py
+++ b/backend/onyx/db/persona.py
@@ -205,7 +205,9 @@ def update_persona_access(
 
     NOTE: Callers are responsible for committing."""
 
+    needs_sync = False
     if is_public is not None:
+        needs_sync = True
         persona = db_session.query(Persona).filter(Persona.id == persona_id).first()
         if persona:
             persona.is_public = is_public
@@ -213,6 +215,7 @@ def update_persona_access(
     # NOTE: For user-ids and group-ids, `None` means "leave unchanged", `[]` means "clear all shares",
     # and a non-empty list means "replace with these shares".
     if user_ids is not None:
+        needs_sync = True
         db_session.query(Persona__User).filter(
             Persona__User.persona_id == persona_id
         ).delete(synchronize_session="fetch")
@@ -233,6 +236,7 @@ def update_persona_access(
     # MIT doesn't support group-based sharing, so we allow clearing (no-op since
     # there shouldn't be any) but raise an error if trying to add actual groups.
     if group_ids is not None:
+        needs_sync = True
         db_session.query(Persona__UserGroup).filter(
             Persona__UserGroup.persona_id == persona_id
         ).delete(synchronize_session="fetch")
@@ -240,6 +244,10 @@ def update_persona_access(
         if group_ids:
             raise NotImplementedError("Onyx MIT does not support group-based sharing")
 
+    # When sharing changes, user file ACLs need to be updated in the vector DB
+    if needs_sync:
+        mark_persona_user_files_for_sync(persona_id, db_session)
+
 
 def create_update_persona(
     persona_id: int | None,
@@ -851,6 +859,24 @@ def update_personas_display_priority(
         db_session.commit()
 
 
+def mark_persona_user_files_for_sync(
+    persona_id: int,
+    db_session: Session,
+) -> None:
+    """When persona sharing changes, mark all of its user files for sync
+    so that their ACLs get updated in the vector DB."""
+    persona = (
+        db_session.query(Persona)
+        .options(selectinload(Persona.user_files))
+        .filter(Persona.id == persona_id)
+        .first()
+    )
+    if not persona:
+        return
+    file_ids = [uf.id for uf in persona.user_files]
+    _mark_files_need_persona_sync(db_session, file_ids)
+
+
 def _mark_files_need_persona_sync(
     db_session: Session,
     user_file_ids: list[UUID],
diff --git a/backend/onyx/db/user_file.py b/backend/onyx/db/user_file.py
index 5e4800a2149..1de96ff917c 100644
--- a/backend/onyx/db/user_file.py
+++ b/backend/onyx/db/user_file.py
@@ -3,9 +3,11 @@
 
 from sqlalchemy import func
 from sqlalchemy import select
+from sqlalchemy.orm import joinedload
 from sqlalchemy.orm import selectinload
 from sqlalchemy.orm import Session
 
+from onyx.db.models import Persona
 from onyx.db.models import Project__UserFile
 from onyx.db.models import UserFile
 
@@ -118,3 +120,31 @@ def get_file_ids_by_user_file_ids(
 ) -> list[str]:
     user_files = db_session.query(UserFile).filter(UserFile.id.in_(user_file_ids)).all()
     return [user_file.file_id for user_file in user_files]
+
+
+def fetch_user_files_with_access_relationships(
+    user_file_ids: list[str],
+    db_session: Session,
+    eager_load_groups: bool = False,
+) -> list[UserFile]:
+    """Fetch user files with the owner and assistant relationships
+    eagerly loaded (needed for computing access control).
+
+    When eager_load_groups is True, Persona.groups is also loaded so that
+    callers can extract user-group names without a second DB round-trip."""
+    persona_sub_options = [
+        selectinload(Persona.users),
+        selectinload(Persona.user),
+    ]
+    if eager_load_groups:
+        persona_sub_options.append(selectinload(Persona.groups))
+
+    return (
+        db_session.query(UserFile)
+        .options(
+            joinedload(UserFile.user),
+            selectinload(UserFile.assistants).options(*persona_sub_options),
+        )
+        .filter(UserFile.id.in_(user_file_ids))
+        .all()
+    )
diff --git a/backend/tests/daily/connectors/gitlab/test_gitlab_basic.py b/backend/tests/daily/connectors/gitlab/test_gitlab_basic.py
index 6b1e515b169..781c396f4cb 100644
--- a/backend/tests/daily/connectors/gitlab/test_gitlab_basic.py
+++ b/backend/tests/daily/connectors/gitlab/test_gitlab_basic.py
@@ -48,7 +48,7 @@ def test_gitlab_connector_basic(gitlab_connector: GitlabConnector) -> None:
 
     # --- Specific Document Details to Validate ---
     target_mr_id = f"https://{gitlab_base_url}/{project_path}/-/merge_requests/1"
-    target_issue_id = f"https://{gitlab_base_url}/{project_path}/-/issues/2"
+    target_issue_id = f"https://{gitlab_base_url}/{project_path}/-/work_items/2"
     target_code_file_semantic_id = "README.md"
     # ---
 
diff --git a/backend/tests/unit/onyx/access/test_user_file_access.py b/backend/tests/unit/onyx/access/test_user_file_access.py
new file mode 100644
index 00000000000..b5fe6e61ffe
--- /dev/null
+++ b/backend/tests/unit/onyx/access/test_user_file_access.py
@@ -0,0 +1,163 @@
+"""Tests for user file ACL computation, including shared persona access."""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+from uuid import uuid4
+
+from onyx.access.access import collect_user_file_access
+from onyx.access.access import get_access_for_user_files_impl
+from onyx.access.utils import prefix_user_email
+from onyx.configs.constants import PUBLIC_DOC_PAT
+
+
+def _make_user(email: str) -> MagicMock:
+    user = MagicMock()
+    user.email = email
+    user.id = uuid4()
+    return user
+
+
+def _make_persona(
+    *,
+    owner: MagicMock | None = None,
+    shared_users: list[MagicMock] | None = None,
+    is_public: bool = False,
+    deleted: bool = False,
+) -> MagicMock:
+    persona = MagicMock()
+    persona.deleted = deleted
+    persona.is_public = is_public
+    persona.user_id = owner.id if owner else None
+    persona.user = owner
+    persona.users = shared_users or []
+    return persona
+
+
+def _make_user_file(
+    *,
+    owner: MagicMock,
+    assistants: list[MagicMock] | None = None,
+) -> MagicMock:
+    uf = MagicMock()
+    uf.id = uuid4()
+    uf.user = owner
+    uf.user_id = owner.id
+    uf.assistants = assistants or []
+    return uf
+
+
+class TestCollectUserFileAccess:
+    def test_owner_only(self) -> None:
+        owner = _make_user("owner@test.com")
+        uf = _make_user_file(owner=owner)
+
+        emails, is_public = collect_user_file_access(uf)
+
+        assert emails == {"owner@test.com"}
+        assert is_public is False
+
+    def test_shared_persona_adds_users(self) -> None:
+        owner = _make_user("owner@test.com")
+        shared = _make_user("shared@test.com")
+        persona = _make_persona(owner=owner, shared_users=[shared])
+        uf = _make_user_file(owner=owner, assistants=[persona])
+
+        emails, is_public = collect_user_file_access(uf)
+
+        assert emails == {"owner@test.com", "shared@test.com"}
+        assert is_public is False
+
+    def test_persona_owner_added(self) -> None:
+        """Persona owner (different from file owner) gets access too."""
+        file_owner = _make_user("file-owner@test.com")
+        persona_owner = _make_user("persona-owner@test.com")
+        persona = _make_persona(owner=persona_owner)
+        uf = _make_user_file(owner=file_owner, assistants=[persona])
+
+        emails, is_public = collect_user_file_access(uf)
+
+        assert "file-owner@test.com" in emails
+        assert "persona-owner@test.com" in emails
+
+    def test_public_persona_makes_file_public(self) -> None:
+        owner = _make_user("owner@test.com")
+        persona = _make_persona(owner=owner, is_public=True)
+        uf = _make_user_file(owner=owner, assistants=[persona])
+
+        emails, is_public = collect_user_file_access(uf)
+
+        assert is_public is True
+        assert "owner@test.com" in emails
+
+    def test_deleted_persona_ignored(self) -> None:
+        owner = _make_user("owner@test.com")
+        shared = _make_user("shared@test.com")
+        persona = _make_persona(owner=owner, shared_users=[shared], deleted=True)
+        uf = _make_user_file(owner=owner, assistants=[persona])
+
+        emails, is_public = collect_user_file_access(uf)
+
+        assert emails == {"owner@test.com"}
+        assert is_public is False
+
+    def test_multiple_personas_combine(self) -> None:
+        owner = _make_user("owner@test.com")
+        user_a = _make_user("a@test.com")
+        user_b = _make_user("b@test.com")
+        p1 = _make_persona(owner=owner, shared_users=[user_a])
+        p2 = _make_persona(owner=owner, shared_users=[user_b])
+        uf = _make_user_file(owner=owner, assistants=[p1, p2])
+
+        emails, is_public = collect_user_file_access(uf)
+
+        assert emails == {"owner@test.com", "a@test.com", "b@test.com"}
+
+    def test_deduplication(self) -> None:
+        owner = _make_user("owner@test.com")
+        shared = _make_user("shared@test.com")
+        p1 = _make_persona(owner=owner, shared_users=[shared])
+        p2 = _make_persona(owner=owner, shared_users=[shared])
+        uf = _make_user_file(owner=owner, assistants=[p1, p2])
+
+        emails, _ = collect_user_file_access(uf)
+
+        assert emails == {"owner@test.com", "shared@test.com"}
+
+
+class TestGetAccessForUserFiles:
+    def test_shared_user_in_acl(self) -> None:
+        """Shared persona users should appear in the ACL."""
+        owner = _make_user("owner@test.com")
+        shared = _make_user("shared@test.com")
+        persona = _make_persona(owner=owner, shared_users=[shared])
+        uf = _make_user_file(owner=owner, assistants=[persona])
+
+        db_session = MagicMock()
+        with patch(
+            "onyx.access.access.fetch_user_files_with_access_relationships",
+            return_value=[uf],
+        ):
+            result = get_access_for_user_files_impl([str(uf.id)], db_session)
+
+        access = result[str(uf.id)]
+        acl = access.to_acl()
+        assert prefix_user_email("owner@test.com") in acl
+        assert prefix_user_email("shared@test.com") in acl
+        assert access.is_public is False
+
+    def test_public_persona_sets_public_acl(self) -> None:
+        owner = _make_user("owner@test.com")
+        persona = _make_persona(owner=owner, is_public=True)
+        uf = _make_user_file(owner=owner, assistants=[persona])
+
+        db_session = MagicMock()
+        with patch(
+            "onyx.access.access.fetch_user_files_with_access_relationships",
+            return_value=[uf],
+        ):
+            result = get_access_for_user_files_impl([str(uf.id)], db_session)
+
+        access = result[str(uf.id)]
+        assert access.is_public is True
+        acl = access.to_acl()
+        assert PUBLIC_DOC_PAT in acl
diff --git a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py
index 4ae9f297b1f..b7506f3bd5b 100644
--- a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py
+++ b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_impl_redis_locking.py
@@ -27,7 +27,6 @@ def _mock_session_returning_none() -> MagicMock:
     """Return a mock session whose .get() returns None (file not found)."""
     session = MagicMock()
     session.get.return_value = None
-    session.execute.return_value.scalar_one_or_none.return_value = None
     return session
 
 
@@ -220,6 +219,10 @@ def test_redis_locking_false_skips_redis_entirely(
 # ------------------------------------------------------------------
 
 
+@patch(
+    f"{TASKS_MODULE}.fetch_user_files_with_access_relationships",
+    return_value=[],
+)
 class TestProjectSyncUserFileImpl:
     @patch(f"{TASKS_MODULE}.get_session_with_current_tenant")
     @patch(f"{TASKS_MODULE}.get_redis_client")
@@ -227,6 +230,7 @@ def test_redis_locking_true_acquires_and_releases_lock(
         self,
         mock_get_redis: MagicMock,
         mock_get_session: MagicMock,
+        _mock_fetch: MagicMock,
     ) -> None:
         redis_client = MagicMock()
         lock = MagicMock()
@@ -255,6 +259,7 @@ def test_redis_locking_true_skips_when_lock_held(
         self,
         mock_get_redis: MagicMock,
         mock_get_session: MagicMock,
+        _mock_fetch: MagicMock,
     ) -> None:
         redis_client = MagicMock()
         lock = MagicMock()
@@ -277,6 +282,7 @@ def test_redis_locking_false_skips_redis_entirely(
         self,
         mock_get_redis: MagicMock,
         mock_get_session: MagicMock,
+        _mock_fetch: MagicMock,
     ) -> None:
         session = _mock_session_returning_none()
         mock_get_session.return_value.__enter__.return_value = session
diff --git a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py
index 6171c4e4a5d..d3874debad7 100644
--- a/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py
+++ b/backend/tests/unit/onyx/background/celery/tasks/test_user_file_processing_no_vectordb.py
@@ -379,10 +379,13 @@ def test_skips_vector_db_update(
     ) -> None:
         uf = _make_user_file(status=UserFileStatus.COMPLETED)
         session = MagicMock()
-        session.execute.return_value.scalar_one_or_none.return_value = uf
         mock_get_session.return_value.__enter__.return_value = session
 
         with (
+            patch(
+                f"{TASKS_MODULE}.fetch_user_files_with_access_relationships",
+                return_value=[uf],
+            ),
             patch(f"{TASKS_MODULE}.get_all_document_indices") as mock_get_indices,
             patch(f"{TASKS_MODULE}.get_active_search_settings") as mock_get_ss,
             patch(f"{TASKS_MODULE}.httpx_init_vespa_pool") as mock_vespa_pool,
@@ -405,14 +408,17 @@ def test_still_clears_sync_flags(
     ) -> None:
         uf = _make_user_file(status=UserFileStatus.COMPLETED)
         session = MagicMock()
-        session.execute.return_value.scalar_one_or_none.return_value = uf
         mock_get_session.return_value.__enter__.return_value = session
 
-        project_sync_user_file_impl(
-            user_file_id=str(uf.id),
-            tenant_id="test-tenant",
-            redis_locking=False,
-        )
+        with patch(
+            f"{TASKS_MODULE}.fetch_user_files_with_access_relationships",
+            return_value=[uf],
+        ):
+            project_sync_user_file_impl(
+                user_file_id=str(uf.id),
+                tenant_id="test-tenant",
+                redis_locking=False,
+            )
 
         assert uf.needs_project_sync is False
         assert uf.needs_persona_sync is False

From 77f58fbad5f60f6d19b3f23e7d5fbb346aacd5af Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Mon, 9 Mar 2026 22:29:26 -0700
Subject: [PATCH 206/267] feat: prune hierarchynodes (#9066)

---
 ...e8f9a1_add_hierarchy_node_cc_pair_table.py |  51 +++
 .../onyx/background/celery/celery_utils.py    |   9 +-
 .../celery/tasks/hierarchyfetching/tasks.py   |   9 +
 .../background/celery/tasks/pruning/tasks.py  |  57 ++-
 .../background/indexing/run_docfetching.py    |   9 +
 backend/onyx/db/hierarchy.py                  | 155 ++++++++
 backend/onyx/db/models.py                     |  33 ++
 backend/onyx/redis/redis_hierarchy.py         |  25 ++
 .../celery/test_pruning_hierarchy_nodes.py    | 333 +++++++++++++++++-
 9 files changed, 660 insertions(+), 21 deletions(-)
 create mode 100644 backend/alembic/versions/b5c4d7e8f9a1_add_hierarchy_node_cc_pair_table.py

diff --git a/backend/alembic/versions/b5c4d7e8f9a1_add_hierarchy_node_cc_pair_table.py b/backend/alembic/versions/b5c4d7e8f9a1_add_hierarchy_node_cc_pair_table.py
new file mode 100644
index 00000000000..931d615603a
--- /dev/null
+++ b/backend/alembic/versions/b5c4d7e8f9a1_add_hierarchy_node_cc_pair_table.py
@@ -0,0 +1,51 @@
+"""add hierarchy_node_by_connector_credential_pair table
+
+Revision ID: b5c4d7e8f9a1
+Revises: a3b8d9e2f1c4
+Create Date: 2026-03-04
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "b5c4d7e8f9a1"
+down_revision = "a3b8d9e2f1c4"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "hierarchy_node_by_connector_credential_pair",
+        sa.Column("hierarchy_node_id", sa.Integer(), nullable=False),
+        sa.Column("connector_id", sa.Integer(), nullable=False),
+        sa.Column("credential_id", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["hierarchy_node_id"],
+            ["hierarchy_node.id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["connector_id", "credential_id"],
+            [
+                "connector_credential_pair.connector_id",
+                "connector_credential_pair.credential_id",
+            ],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("hierarchy_node_id", "connector_id", "credential_id"),
+    )
+    op.create_index(
+        "ix_hierarchy_node_cc_pair_connector_credential",
+        "hierarchy_node_by_connector_credential_pair",
+        ["connector_id", "credential_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_hierarchy_node_cc_pair_connector_credential",
+        table_name="hierarchy_node_by_connector_credential_pair",
+    )
+    op.drop_table("hierarchy_node_by_connector_credential_pair")
diff --git a/backend/onyx/background/celery/celery_utils.py b/backend/onyx/background/celery/celery_utils.py
index e4c236d560f..977a9f0daa0 100644
--- a/backend/onyx/background/celery/celery_utils.py
+++ b/backend/onyx/background/celery/celery_utils.py
@@ -115,8 +115,6 @@ def _extract_from_batch(
     for item in doc_list:
         if isinstance(item, HierarchyNode):
             hierarchy_nodes.append(item)
-            if item.raw_node_id not in ids:
-                ids[item.raw_node_id] = None
         elif isinstance(item, ConnectorFailure):
             failed_id = _get_failure_id(item)
             if failed_id:
@@ -125,8 +123,7 @@ def _extract_from_batch(
                 f"Failed to retrieve document {failed_id}: " f"{item.failure_message}"
             )
         else:
-            parent_raw = getattr(item, "parent_hierarchy_raw_node_id", None)
-            ids[item.id] = parent_raw
+            ids[item.id] = item.parent_hierarchy_raw_node_id
     return BatchResult(raw_id_to_parent=ids, hierarchy_nodes=hierarchy_nodes)
 
 
@@ -192,9 +189,7 @@ def extract_ids_from_runnable_connector(
         batch_ids = batch_result.raw_id_to_parent
         batch_nodes = batch_result.hierarchy_nodes
         doc_batch_processing_func(batch_ids)
-        for k, v in batch_ids.items():
-            if v is not None or k not in all_raw_id_to_parent:
-                all_raw_id_to_parent[k] = v
+        all_raw_id_to_parent.update(batch_ids)
         all_hierarchy_nodes.extend(batch_nodes)
 
         if callback:
diff --git a/backend/onyx/background/celery/tasks/hierarchyfetching/tasks.py b/backend/onyx/background/celery/tasks/hierarchyfetching/tasks.py
index c445cc1a917..50b57560310 100644
--- a/backend/onyx/background/celery/tasks/hierarchyfetching/tasks.py
+++ b/backend/onyx/background/celery/tasks/hierarchyfetching/tasks.py
@@ -40,6 +40,7 @@
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.enums import AccessType
 from onyx.db.enums import ConnectorCredentialPairStatus
+from onyx.db.hierarchy import upsert_hierarchy_node_cc_pair_entries
 from onyx.db.hierarchy import upsert_hierarchy_nodes_batch
 from onyx.db.models import ConnectorCredentialPair
 from onyx.redis.redis_hierarchy import cache_hierarchy_nodes_batch
@@ -289,6 +290,14 @@ def _process_batch() -> int:
             is_connector_public=is_connector_public,
         )
 
+        upsert_hierarchy_node_cc_pair_entries(
+            db_session=db_session,
+            hierarchy_node_ids=[n.id for n in upserted_nodes],
+            connector_id=cc_pair.connector_id,
+            credential_id=cc_pair.credential_id,
+            commit=True,
+        )
+
         # Cache in Redis for fast ancestor resolution
         cache_entries = [
             HierarchyNodeCacheEntry.from_db_model(node) for node in upserted_nodes
diff --git a/backend/onyx/background/celery/tasks/pruning/tasks.py b/backend/onyx/background/celery/tasks/pruning/tasks.py
index 4c8add72703..baa0627754d 100644
--- a/backend/onyx/background/celery/tasks/pruning/tasks.py
+++ b/backend/onyx/background/celery/tasks/pruning/tasks.py
@@ -48,10 +48,15 @@
 from onyx.db.enums import ConnectorCredentialPairStatus
 from onyx.db.enums import SyncStatus
 from onyx.db.enums import SyncType
+from onyx.db.hierarchy import delete_orphaned_hierarchy_nodes
 from onyx.db.hierarchy import link_hierarchy_nodes_to_documents
+from onyx.db.hierarchy import remove_stale_hierarchy_node_cc_pair_entries
+from onyx.db.hierarchy import reparent_orphaned_hierarchy_nodes
 from onyx.db.hierarchy import update_document_parent_hierarchy_nodes
+from onyx.db.hierarchy import upsert_hierarchy_node_cc_pair_entries
 from onyx.db.hierarchy import upsert_hierarchy_nodes_batch
 from onyx.db.models import ConnectorCredentialPair
+from onyx.db.models import HierarchyNode as DBHierarchyNode
 from onyx.db.sync_record import insert_sync_record
 from onyx.db.sync_record import update_sync_record_status
 from onyx.db.tag import delete_orphan_tags__no_commit
@@ -60,6 +65,7 @@
 from onyx.redis.redis_connector_prune import RedisConnectorPrunePayload
 from onyx.redis.redis_hierarchy import cache_hierarchy_nodes_batch
 from onyx.redis.redis_hierarchy import ensure_source_node_exists
+from onyx.redis.redis_hierarchy import evict_hierarchy_nodes_from_cache
 from onyx.redis.redis_hierarchy import get_node_id_from_raw_id
 from onyx.redis.redis_hierarchy import get_source_node_id_from_cache
 from onyx.redis.redis_hierarchy import HierarchyNodeCacheEntry
@@ -579,11 +585,12 @@ def connector_pruning_generator_task(
             source = cc_pair.connector.source
             redis_client = get_redis_client(tenant_id=tenant_id)
 
+            ensure_source_node_exists(redis_client, db_session, source)
+
+            upserted_nodes: list[DBHierarchyNode] = []
             if extraction_result.hierarchy_nodes:
                 is_connector_public = cc_pair.access_type == AccessType.PUBLIC
 
-                ensure_source_node_exists(redis_client, db_session, source)
-
                 upserted_nodes = upsert_hierarchy_nodes_batch(
                     db_session=db_session,
                     nodes=extraction_result.hierarchy_nodes,
@@ -592,6 +599,14 @@ def connector_pruning_generator_task(
                     is_connector_public=is_connector_public,
                 )
 
+                upsert_hierarchy_node_cc_pair_entries(
+                    db_session=db_session,
+                    hierarchy_node_ids=[n.id for n in upserted_nodes],
+                    connector_id=connector_id,
+                    credential_id=credential_id,
+                    commit=True,
+                )
+
                 cache_entries = [
                     HierarchyNodeCacheEntry.from_db_model(node)
                     for node in upserted_nodes
@@ -607,7 +622,6 @@ def connector_pruning_generator_task(
                     f"hierarchy nodes for cc_pair={cc_pair_id}"
                 )
 
-            ensure_source_node_exists(redis_client, db_session, source)
             # Resolve parent_hierarchy_raw_node_id → parent_hierarchy_node_id
             # and bulk-update documents, mirroring the docfetching resolution
             _resolve_and_update_document_parents(
@@ -664,6 +678,43 @@ def connector_pruning_generator_task(
             )
 
             redis_connector.prune.generator_complete = tasks_generated
+
+            # --- Hierarchy node pruning ---
+            live_node_ids = {n.id for n in upserted_nodes}
+            stale_removed = remove_stale_hierarchy_node_cc_pair_entries(
+                db_session=db_session,
+                connector_id=connector_id,
+                credential_id=credential_id,
+                live_hierarchy_node_ids=live_node_ids,
+                commit=True,
+            )
+            deleted_raw_ids = delete_orphaned_hierarchy_nodes(
+                db_session=db_session,
+                source=source,
+                commit=True,
+            )
+            reparented_nodes = reparent_orphaned_hierarchy_nodes(
+                db_session=db_session,
+                source=source,
+                commit=True,
+            )
+            if deleted_raw_ids:
+                evict_hierarchy_nodes_from_cache(redis_client, source, deleted_raw_ids)
+            if reparented_nodes:
+                reparented_cache_entries = [
+                    HierarchyNodeCacheEntry.from_db_model(node)
+                    for node in reparented_nodes
+                ]
+                cache_hierarchy_nodes_batch(
+                    redis_client, source, reparented_cache_entries
+                )
+            if stale_removed or deleted_raw_ids or reparented_nodes:
+                task_logger.info(
+                    f"Hierarchy node pruning: cc_pair={cc_pair_id} "
+                    f"stale_entries_removed={stale_removed} "
+                    f"nodes_deleted={len(deleted_raw_ids)} "
+                    f"nodes_reparented={len(reparented_nodes)}"
+                )
     except Exception as e:
         task_logger.exception(
             f"Pruning exceptioned: cc_pair={cc_pair_id} "
diff --git a/backend/onyx/background/indexing/run_docfetching.py b/backend/onyx/background/indexing/run_docfetching.py
index 79adf545e04..975d444a2b7 100644
--- a/backend/onyx/background/indexing/run_docfetching.py
+++ b/backend/onyx/background/indexing/run_docfetching.py
@@ -45,6 +45,7 @@
 from onyx.db.enums import IndexingStatus
 from onyx.db.enums import IndexModelStatus
 from onyx.db.enums import ProcessingMode
+from onyx.db.hierarchy import upsert_hierarchy_node_cc_pair_entries
 from onyx.db.hierarchy import upsert_hierarchy_nodes_batch
 from onyx.db.index_attempt import create_index_attempt_error
 from onyx.db.index_attempt import get_index_attempt
@@ -587,6 +588,14 @@ def connector_document_extraction(
                             is_connector_public=is_connector_public,
                         )
 
+                        upsert_hierarchy_node_cc_pair_entries(
+                            db_session=db_session,
+                            hierarchy_node_ids=[n.id for n in upserted_nodes],
+                            connector_id=db_connector.id,
+                            credential_id=db_credential.id,
+                            commit=True,
+                        )
+
                         # Cache in Redis for fast ancestor resolution during doc processing
                         redis_client = get_redis_client(tenant_id=tenant_id)
                         cache_entries = [
diff --git a/backend/onyx/db/hierarchy.py b/backend/onyx/db/hierarchy.py
index 7c403bc37d9..b04eb4a3789 100644
--- a/backend/onyx/db/hierarchy.py
+++ b/backend/onyx/db/hierarchy.py
@@ -2,7 +2,10 @@
 
 from collections import defaultdict
 
+from sqlalchemy import delete
 from sqlalchemy import select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
 from onyx.configs.constants import DocumentSource
@@ -10,6 +13,7 @@
 from onyx.db.enums import HierarchyNodeType
 from onyx.db.models import Document
 from onyx.db.models import HierarchyNode
+from onyx.db.models import HierarchyNodeByConnectorCredentialPair
 from onyx.utils.logger import setup_logger
 from onyx.utils.variable_functionality import fetch_versioned_implementation
 
@@ -620,3 +624,154 @@ def update_hierarchy_node_permissions(
         db_session.flush()
 
     return True
+
+
+def upsert_hierarchy_node_cc_pair_entries(
+    db_session: Session,
+    hierarchy_node_ids: list[int],
+    connector_id: int,
+    credential_id: int,
+    commit: bool = True,
+) -> None:
+    """Insert rows into HierarchyNodeByConnectorCredentialPair, ignoring conflicts.
+
+    This records that the given cc_pair "owns" these hierarchy nodes. Used by
+    indexing, pruning, and hierarchy-fetching paths.
+    """
+    if not hierarchy_node_ids:
+        return
+
+    _M = HierarchyNodeByConnectorCredentialPair
+    stmt = pg_insert(_M).values(
+        [
+            {
+                _M.hierarchy_node_id: node_id,
+                _M.connector_id: connector_id,
+                _M.credential_id: credential_id,
+            }
+            for node_id in hierarchy_node_ids
+        ]
+    )
+    stmt = stmt.on_conflict_do_nothing()
+    db_session.execute(stmt)
+
+    if commit:
+        db_session.commit()
+    else:
+        db_session.flush()
+
+
+def remove_stale_hierarchy_node_cc_pair_entries(
+    db_session: Session,
+    connector_id: int,
+    credential_id: int,
+    live_hierarchy_node_ids: set[int],
+    commit: bool = True,
+) -> int:
+    """Delete join-table rows for this cc_pair that are NOT in the live set.
+
+    If ``live_hierarchy_node_ids`` is empty ALL rows for the cc_pair are deleted
+    (i.e. the connector no longer has any hierarchy nodes). Callers that want a
+    no-op when there are no live nodes must guard before calling.
+
+    Returns the number of deleted rows.
+    """
+    stmt = delete(HierarchyNodeByConnectorCredentialPair).where(
+        HierarchyNodeByConnectorCredentialPair.connector_id == connector_id,
+        HierarchyNodeByConnectorCredentialPair.credential_id == credential_id,
+    )
+    if live_hierarchy_node_ids:
+        stmt = stmt.where(
+            HierarchyNodeByConnectorCredentialPair.hierarchy_node_id.notin_(
+                live_hierarchy_node_ids
+            )
+        )
+
+    result: CursorResult = db_session.execute(stmt)  # type: ignore[assignment]
+    deleted = result.rowcount
+
+    if commit:
+        db_session.commit()
+    elif deleted:
+        db_session.flush()
+
+    return deleted
+
+
+def delete_orphaned_hierarchy_nodes(
+    db_session: Session,
+    source: DocumentSource,
+    commit: bool = True,
+) -> list[str]:
+    """Delete hierarchy nodes for a source that have zero cc_pair associations.
+
+    SOURCE-type nodes are excluded (they are synthetic roots).
+
+    Returns the list of raw_node_ids that were deleted (for cache eviction).
+    """
+    # Find orphaned nodes: no rows in the join table
+    orphan_stmt = (
+        select(HierarchyNode.id, HierarchyNode.raw_node_id)
+        .outerjoin(
+            HierarchyNodeByConnectorCredentialPair,
+            HierarchyNode.id
+            == HierarchyNodeByConnectorCredentialPair.hierarchy_node_id,
+        )
+        .where(
+            HierarchyNode.source == source,
+            HierarchyNode.node_type != HierarchyNodeType.SOURCE,
+            HierarchyNodeByConnectorCredentialPair.hierarchy_node_id.is_(None),
+        )
+    )
+    orphans = db_session.execute(orphan_stmt).all()
+    if not orphans:
+        return []
+
+    orphan_ids = [row[0] for row in orphans]
+    deleted_raw_ids = [row[1] for row in orphans]
+
+    db_session.execute(delete(HierarchyNode).where(HierarchyNode.id.in_(orphan_ids)))
+
+    if commit:
+        db_session.commit()
+    else:
+        db_session.flush()
+
+    return deleted_raw_ids
+
+
+def reparent_orphaned_hierarchy_nodes(
+    db_session: Session,
+    source: DocumentSource,
+    commit: bool = True,
+) -> list[HierarchyNode]:
+    """Re-parent hierarchy nodes whose parent_id is NULL to the SOURCE node.
+
+    After pruning deletes stale nodes, their former children get parent_id=NULL
+    via the SET NULL cascade. This function points them back to the SOURCE root.
+
+    Returns the reparented HierarchyNode objects (with updated parent_id)
+    so callers can refresh downstream caches.
+    """
+    source_node = get_source_hierarchy_node(db_session, source)
+    if not source_node:
+        return []
+
+    stmt = select(HierarchyNode).where(
+        HierarchyNode.source == source,
+        HierarchyNode.parent_id.is_(None),
+        HierarchyNode.node_type != HierarchyNodeType.SOURCE,
+    )
+    orphans = list(db_session.execute(stmt).scalars().all())
+    if not orphans:
+        return []
+
+    for node in orphans:
+        node.parent_id = source_node.id
+
+    if commit:
+        db_session.commit()
+    else:
+        db_session.flush()
+
+    return orphans
diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index 35f8db0bf4a..c5795dab340 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -25,6 +25,7 @@
 from sqlalchemy import Enum
 from sqlalchemy import Float
 from sqlalchemy import ForeignKey
+from sqlalchemy import ForeignKeyConstraint
 from sqlalchemy import func
 from sqlalchemy import Index
 from sqlalchemy import Integer
@@ -2425,6 +2426,38 @@ class SyncRecord(Base):
     )
 
 
+class HierarchyNodeByConnectorCredentialPair(Base):
+    """Tracks which cc_pairs reference each hierarchy node.
+
+    During pruning, stale entries are removed for the current cc_pair.
+    Hierarchy nodes with zero remaining entries are then deleted.
+    """
+
+    __tablename__ = "hierarchy_node_by_connector_credential_pair"
+
+    hierarchy_node_id: Mapped[int] = mapped_column(
+        ForeignKey("hierarchy_node.id", ondelete="CASCADE"), primary_key=True
+    )
+    connector_id: Mapped[int] = mapped_column(primary_key=True)
+    credential_id: Mapped[int] = mapped_column(primary_key=True)
+
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["connector_id", "credential_id"],
+            [
+                "connector_credential_pair.connector_id",
+                "connector_credential_pair.credential_id",
+            ],
+            ondelete="CASCADE",
+        ),
+        Index(
+            "ix_hierarchy_node_cc_pair_connector_credential",
+            "connector_id",
+            "credential_id",
+        ),
+    )
+
+
 class DocumentByConnectorCredentialPair(Base):
     """Represents an indexing of a document by a specific connector / credential pair"""
 
diff --git a/backend/onyx/redis/redis_hierarchy.py b/backend/onyx/redis/redis_hierarchy.py
index d086c82abf6..f23ef1d02d4 100644
--- a/backend/onyx/redis/redis_hierarchy.py
+++ b/backend/onyx/redis/redis_hierarchy.py
@@ -16,6 +16,7 @@
   using only the SOURCE-type node as the ancestor
 """
 
+from typing import cast
 from typing import TYPE_CHECKING
 
 from pydantic import BaseModel
@@ -204,6 +205,30 @@ def cache_hierarchy_nodes_batch(
     redis_client.expire(raw_id_key, HIERARCHY_CACHE_TTL_SECONDS)
 
 
+def evict_hierarchy_nodes_from_cache(
+    redis_client: Redis,
+    source: DocumentSource,
+    raw_node_ids: list[str],
+) -> None:
+    """Remove specific hierarchy nodes from the Redis cache.
+
+    Deletes entries from both the parent-chain hash and the raw_id→node_id hash.
+    """
+    if not raw_node_ids:
+        return
+
+    cache_key = _cache_key(source)
+    raw_id_key = _raw_id_cache_key(source)
+
+    # Look up node_ids so we can remove them from the parent-chain hash
+    raw_values = cast(list[str | None], redis_client.hmget(raw_id_key, raw_node_ids))
+    node_id_strs = [v for v in raw_values if v is not None]
+
+    if node_id_strs:
+        redis_client.hdel(cache_key, *node_id_strs)
+    redis_client.hdel(raw_id_key, *raw_node_ids)
+
+
 def get_node_id_from_raw_id(
     redis_client: Redis,
     source: DocumentSource,
diff --git a/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py b/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py
index 719614ac6ab..4bba85cb23f 100644
--- a/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py
+++ b/backend/tests/external_dependency_unit/celery/test_pruning_hierarchy_nodes.py
@@ -7,6 +7,8 @@
 3. Upserting is idempotent (running twice doesn't duplicate nodes)
 4. Document-to-hierarchy-node linkage is updated during pruning
 5. link_hierarchy_nodes_to_documents links nodes that are also documents
+6. HierarchyNodeByConnectorCredentialPair join table population and pruning
+7. Orphaned hierarchy node deletion and re-parenting
 
 Uses a mock SlimConnectorWithPermSync that yields known hierarchy nodes and slim documents,
 combined with a real PostgreSQL database for verifying persistence.
@@ -24,16 +26,27 @@
 from onyx.connectors.interfaces import SecondsSinceUnixEpoch
 from onyx.connectors.interfaces import SlimConnectorWithPermSync
 from onyx.connectors.models import HierarchyNode as PydanticHierarchyNode
+from onyx.connectors.models import InputType
 from onyx.connectors.models import SlimDocument
+from onyx.db.enums import AccessType
+from onyx.db.enums import ConnectorCredentialPairStatus
 from onyx.db.enums import HierarchyNodeType
+from onyx.db.hierarchy import delete_orphaned_hierarchy_nodes
 from onyx.db.hierarchy import ensure_source_node_exists
 from onyx.db.hierarchy import get_all_hierarchy_nodes_for_source
 from onyx.db.hierarchy import get_hierarchy_node_by_raw_id
 from onyx.db.hierarchy import link_hierarchy_nodes_to_documents
+from onyx.db.hierarchy import remove_stale_hierarchy_node_cc_pair_entries
+from onyx.db.hierarchy import reparent_orphaned_hierarchy_nodes
 from onyx.db.hierarchy import update_document_parent_hierarchy_nodes
+from onyx.db.hierarchy import upsert_hierarchy_node_cc_pair_entries
 from onyx.db.hierarchy import upsert_hierarchy_nodes_batch
+from onyx.db.models import Connector
+from onyx.db.models import ConnectorCredentialPair
+from onyx.db.models import Credential
 from onyx.db.models import Document as DbDocument
 from onyx.db.models import HierarchyNode as DBHierarchyNode
+from onyx.db.models import HierarchyNodeByConnectorCredentialPair
 from onyx.indexing.indexing_heartbeat import IndexingHeartbeatInterface
 from onyx.kg.models import KGStage
 
@@ -142,13 +155,80 @@ def _generate(self) -> Iterator[list[SlimDocument | PydanticHierarchyNode]]:
 # ---------------------------------------------------------------------------
 
 
+def _create_cc_pair(
+    db_session: Session,
+    source: DocumentSource = TEST_SOURCE,
+) -> ConnectorCredentialPair:
+    """Create a real Connector + Credential + ConnectorCredentialPair for testing."""
+    connector = Connector(
+        name=f"Test {source.value} Connector",
+        source=source,
+        input_type=InputType.LOAD_STATE,
+        connector_specific_config={},
+    )
+    db_session.add(connector)
+    db_session.flush()
+
+    credential = Credential(
+        source=source,
+        credential_json={},
+        admin_public=True,
+    )
+    db_session.add(credential)
+    db_session.flush()
+    db_session.expire(credential)
+
+    cc_pair = ConnectorCredentialPair(
+        connector_id=connector.id,
+        credential_id=credential.id,
+        name=f"Test {source.value} CC Pair",
+        status=ConnectorCredentialPairStatus.ACTIVE,
+        access_type=AccessType.PUBLIC,
+    )
+    db_session.add(cc_pair)
+    db_session.commit()
+    db_session.refresh(cc_pair)
+    return cc_pair
+
+
 def _cleanup_test_data(db_session: Session) -> None:
     """Remove all test hierarchy nodes and documents to isolate tests."""
     for doc_id in SLIM_DOC_IDS:
         db_session.query(DbDocument).filter(DbDocument.id == doc_id).delete()
+
+    test_connector_ids_q = db_session.query(Connector.id).filter(
+        Connector.source == TEST_SOURCE,
+        Connector.name.like("Test %"),
+    )
+
+    db_session.query(HierarchyNodeByConnectorCredentialPair).filter(
+        HierarchyNodeByConnectorCredentialPair.connector_id.in_(test_connector_ids_q)
+    ).delete(synchronize_session="fetch")
     db_session.query(DBHierarchyNode).filter(
         DBHierarchyNode.source == TEST_SOURCE
     ).delete()
+    db_session.flush()
+
+    # Collect credential IDs before deleting cc_pairs (bulk query.delete()
+    # bypasses ORM-level cascade, so credentials won't be auto-removed).
+    credential_ids = [
+        row[0]
+        for row in db_session.query(ConnectorCredentialPair.credential_id)
+        .filter(ConnectorCredentialPair.connector_id.in_(test_connector_ids_q))
+        .all()
+    ]
+
+    db_session.query(ConnectorCredentialPair).filter(
+        ConnectorCredentialPair.connector_id.in_(test_connector_ids_q)
+    ).delete(synchronize_session="fetch")
+    db_session.query(Connector).filter(
+        Connector.source == TEST_SOURCE,
+        Connector.name.like("Test %"),
+    ).delete(synchronize_session="fetch")
+    if credential_ids:
+        db_session.query(Credential).filter(Credential.id.in_(credential_ids)).delete(
+            synchronize_session="fetch"
+        )
     db_session.commit()
 
 
@@ -179,15 +259,8 @@ def test_pruning_extracts_hierarchy_nodes(db_session: Session) -> None:  # noqa:
 
     result = extract_ids_from_runnable_connector(connector, callback=None)
 
-    # Doc IDs should include both slim doc IDs and hierarchy node raw_node_ids
-    # (hierarchy node IDs are added to raw_id_to_parent so they aren't pruned)
-    expected_ids = {
-        CHANNEL_A_ID,
-        CHANNEL_B_ID,
-        CHANNEL_C_ID,
-        *SLIM_DOC_IDS,
-    }
-    assert result.raw_id_to_parent.keys() == expected_ids
+    # raw_id_to_parent should contain ONLY document IDs, not hierarchy node IDs
+    assert result.raw_id_to_parent.keys() == set(SLIM_DOC_IDS)
 
     # Hierarchy nodes should be the 3 channels
     assert len(result.hierarchy_nodes) == 3
@@ -395,9 +468,9 @@ def test_extraction_preserves_parent_hierarchy_raw_node_id(
             result.raw_id_to_parent[doc_id] == expected_parent
         ), f"raw_id_to_parent[{doc_id}] should be {expected_parent}"
 
-    # Hierarchy node entries have None parent (they aren't documents)
+    # Hierarchy node IDs should NOT be in raw_id_to_parent
     for channel_id in [CHANNEL_A_ID, CHANNEL_B_ID, CHANNEL_C_ID]:
-        assert result.raw_id_to_parent[channel_id] is None
+        assert channel_id not in result.raw_id_to_parent
 
 
 def test_update_document_parent_hierarchy_nodes(db_session: Session) -> None:
@@ -565,3 +638,241 @@ def test_link_hierarchy_nodes_skips_non_hierarchy_sources(
         commit=False,
     )
     assert linked == 0
+
+
+# ---------------------------------------------------------------------------
+# Join table + pruning tests
+# ---------------------------------------------------------------------------
+
+
+def test_upsert_hierarchy_node_cc_pair_entries(db_session: Session) -> None:
+    """upsert_hierarchy_node_cc_pair_entries should insert rows and be idempotent."""
+    _cleanup_test_data(db_session)
+    ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
+    cc_pair = _create_cc_pair(db_session)
+
+    upserted = upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=_make_hierarchy_nodes(),
+        source=TEST_SOURCE,
+        commit=True,
+        is_connector_public=False,
+    )
+    node_ids = [n.id for n in upserted]
+
+    # First call — should insert rows
+    upsert_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        hierarchy_node_ids=node_ids,
+        connector_id=cc_pair.connector_id,
+        credential_id=cc_pair.credential_id,
+        commit=True,
+    )
+
+    rows = (
+        db_session.query(HierarchyNodeByConnectorCredentialPair)
+        .filter(
+            HierarchyNodeByConnectorCredentialPair.connector_id == cc_pair.connector_id,
+            HierarchyNodeByConnectorCredentialPair.credential_id
+            == cc_pair.credential_id,
+        )
+        .all()
+    )
+    assert len(rows) == 3
+
+    # Second call — idempotent, same count
+    upsert_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        hierarchy_node_ids=node_ids,
+        connector_id=cc_pair.connector_id,
+        credential_id=cc_pair.credential_id,
+        commit=True,
+    )
+    rows_after = (
+        db_session.query(HierarchyNodeByConnectorCredentialPair)
+        .filter(
+            HierarchyNodeByConnectorCredentialPair.connector_id == cc_pair.connector_id,
+            HierarchyNodeByConnectorCredentialPair.credential_id
+            == cc_pair.credential_id,
+        )
+        .all()
+    )
+    assert len(rows_after) == 3
+
+
+def test_remove_stale_entries_and_delete_orphans(db_session: Session) -> None:
+    """After removing stale join-table entries, orphaned hierarchy nodes should
+    be deleted and the SOURCE node should survive."""
+    _cleanup_test_data(db_session)
+    source_node = ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
+    cc_pair = _create_cc_pair(db_session)
+
+    upserted = upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=_make_hierarchy_nodes(),
+        source=TEST_SOURCE,
+        commit=True,
+        is_connector_public=False,
+    )
+    all_ids = [n.id for n in upserted]
+    upsert_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        hierarchy_node_ids=all_ids,
+        connector_id=cc_pair.connector_id,
+        credential_id=cc_pair.credential_id,
+        commit=True,
+    )
+
+    # Now simulate a pruning run where only channel A survived
+    channel_a = get_hierarchy_node_by_raw_id(db_session, CHANNEL_A_ID, TEST_SOURCE)
+    assert channel_a is not None
+    live_ids = {channel_a.id}
+
+    stale_removed = remove_stale_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        connector_id=cc_pair.connector_id,
+        credential_id=cc_pair.credential_id,
+        live_hierarchy_node_ids=live_ids,
+        commit=True,
+    )
+    assert stale_removed == 2
+
+    # Delete orphaned nodes
+    deleted_raw_ids = delete_orphaned_hierarchy_nodes(
+        db_session=db_session,
+        source=TEST_SOURCE,
+        commit=True,
+    )
+    assert set(deleted_raw_ids) == {CHANNEL_B_ID, CHANNEL_C_ID}
+
+    # Verify only channel A + SOURCE remain
+    remaining = get_all_hierarchy_nodes_for_source(db_session, TEST_SOURCE)
+    remaining_raw = {n.raw_node_id for n in remaining}
+    assert remaining_raw == {CHANNEL_A_ID, source_node.raw_node_id}
+
+
+def test_multi_cc_pair_prevents_premature_deletion(db_session: Session) -> None:
+    """A hierarchy node shared by two cc_pairs should NOT be deleted when only
+    one cc_pair removes its association."""
+    _cleanup_test_data(db_session)
+    ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
+    cc_pair_1 = _create_cc_pair(db_session)
+    cc_pair_2 = _create_cc_pair(db_session)
+
+    upserted = upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=_make_hierarchy_nodes(),
+        source=TEST_SOURCE,
+        commit=True,
+        is_connector_public=False,
+    )
+    all_ids = [n.id for n in upserted]
+
+    # cc_pair 1 owns all 3
+    upsert_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        hierarchy_node_ids=all_ids,
+        connector_id=cc_pair_1.connector_id,
+        credential_id=cc_pair_1.credential_id,
+        commit=True,
+    )
+    # cc_pair 2 also owns all 3
+    upsert_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        hierarchy_node_ids=all_ids,
+        connector_id=cc_pair_2.connector_id,
+        credential_id=cc_pair_2.credential_id,
+        commit=True,
+    )
+
+    # cc_pair 1 prunes — keeps none
+    remove_stale_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        connector_id=cc_pair_1.connector_id,
+        credential_id=cc_pair_1.credential_id,
+        live_hierarchy_node_ids=set(),
+        commit=True,
+    )
+
+    # Orphan deletion should find nothing because cc_pair 2 still references them
+    deleted = delete_orphaned_hierarchy_nodes(
+        db_session=db_session,
+        source=TEST_SOURCE,
+        commit=True,
+    )
+    assert deleted == []
+
+    # All 3 nodes + SOURCE should still exist
+    remaining = get_all_hierarchy_nodes_for_source(db_session, TEST_SOURCE)
+    assert len(remaining) == 4
+
+
+def test_reparent_orphaned_children(db_session: Session) -> None:
+    """After deleting a parent hierarchy node, its children should be
+    re-parented to the SOURCE node."""
+    _cleanup_test_data(db_session)
+    source_node = ensure_source_node_exists(db_session, TEST_SOURCE, commit=True)
+    cc_pair = _create_cc_pair(db_session)
+
+    # Create a parent node and a child node
+    parent_node = PydanticHierarchyNode(
+        raw_node_id="PARENT",
+        raw_parent_id=None,
+        display_name="Parent",
+        node_type=HierarchyNodeType.CHANNEL,
+    )
+    child_node = PydanticHierarchyNode(
+        raw_node_id="CHILD",
+        raw_parent_id="PARENT",
+        display_name="Child",
+        node_type=HierarchyNodeType.CHANNEL,
+    )
+    upserted = upsert_hierarchy_nodes_batch(
+        db_session=db_session,
+        nodes=[parent_node, child_node],
+        source=TEST_SOURCE,
+        commit=True,
+        is_connector_public=False,
+    )
+    assert len(upserted) == 2
+
+    parent_db = get_hierarchy_node_by_raw_id(db_session, "PARENT", TEST_SOURCE)
+    child_db = get_hierarchy_node_by_raw_id(db_session, "CHILD", TEST_SOURCE)
+    assert parent_db is not None and child_db is not None
+    assert child_db.parent_id == parent_db.id
+
+    # Associate only the child with a cc_pair (parent is orphaned)
+    upsert_hierarchy_node_cc_pair_entries(
+        db_session=db_session,
+        hierarchy_node_ids=[child_db.id],
+        connector_id=cc_pair.connector_id,
+        credential_id=cc_pair.credential_id,
+        commit=True,
+    )
+
+    # Delete orphaned nodes (parent has no cc_pair entry)
+    deleted = delete_orphaned_hierarchy_nodes(
+        db_session=db_session,
+        source=TEST_SOURCE,
+        commit=True,
+    )
+    assert "PARENT" in deleted
+
+    # Child should now have parent_id=NULL (SET NULL cascade)
+    db_session.expire_all()
+    child_db = get_hierarchy_node_by_raw_id(db_session, "CHILD", TEST_SOURCE)
+    assert child_db is not None
+    assert child_db.parent_id is None
+
+    # Re-parent orphans to SOURCE
+    reparented = reparent_orphaned_hierarchy_nodes(
+        db_session=db_session,
+        source=TEST_SOURCE,
+        commit=True,
+    )
+    assert len(reparented) == 1
+
+    db_session.expire_all()
+    child_db = get_hierarchy_node_by_raw_id(db_session, "CHILD", TEST_SOURCE)
+    assert child_db is not None
+    assert child_db.parent_id == source_node.id

From 5b5100a07a4f05a9634620bbf07b1b64e4601433 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 10 Mar 2026 00:34:00 -0700
Subject: [PATCH 207/267] fix: Prevent the removal and hiding of default model
 (#9131)

---
 backend/ee/onyx/server/seeding.py             |  15 +-
 backend/onyx/db/llm.py                        |  84 ++++---
 backend/onyx/server/manage/llm/api.py         |  37 +--
 backend/onyx/setup.py                         |  10 +-
 .../llm/test_llm_provider_auto_mode.py        | 176 ++++++++++++++
 ...t_llm_provider_default_model_protection.py | 220 ++++++++++++++++++
 6 files changed, 477 insertions(+), 65 deletions(-)
 create mode 100644 backend/tests/external_dependency_unit/llm/test_llm_provider_default_model_protection.py

diff --git a/backend/ee/onyx/server/seeding.py b/backend/ee/onyx/server/seeding.py
index 1539db9c63f..04652f74a68 100644
--- a/backend/ee/onyx/server/seeding.py
+++ b/backend/ee/onyx/server/seeding.py
@@ -26,6 +26,7 @@
 from onyx.db.persona import upsert_persona
 from onyx.server.features.persona.models import PersonaUpsertRequest
 from onyx.server.manage.llm.models import LLMProviderUpsertRequest
+from onyx.server.manage.llm.models import LLMProviderView
 from onyx.server.settings.models import Settings
 from onyx.server.settings.store import store_settings as store_base_settings
 from onyx.utils.logger import setup_logger
@@ -125,10 +126,16 @@ def _seed_llms(
         existing = fetch_existing_llm_provider(name=request.name, db_session=db_session)
         if existing:
             request.id = existing.id
-    seeded_providers = [
-        upsert_llm_provider(llm_upsert_request, db_session)
-        for llm_upsert_request in llm_upsert_requests
-    ]
+    seeded_providers: list[LLMProviderView] = []
+    for llm_upsert_request in llm_upsert_requests:
+        try:
+            seeded_providers.append(upsert_llm_provider(llm_upsert_request, db_session))
+        except ValueError as e:
+            logger.warning(
+                "Failed to upsert LLM provider '%s' during seeding: %s",
+                llm_upsert_request.name,
+                e,
+            )
 
     default_provider = next(
         (p for p in seeded_providers if p.model_configurations), None
diff --git a/backend/onyx/db/llm.py b/backend/onyx/db/llm.py
index 5a8e32229cc..046bf381d7d 100644
--- a/backend/onyx/db/llm.py
+++ b/backend/onyx/db/llm.py
@@ -270,10 +270,35 @@ def upsert_llm_provider(
         mc.name for mc in llm_provider_upsert_request.model_configurations
     }
 
+    # Build a lookup of requested visibility by model name
+    requested_visibility = {
+        mc.name: mc.is_visible
+        for mc in llm_provider_upsert_request.model_configurations
+    }
+
     # Delete removed models
     removed_ids = [
         mc.id for name, mc in existing_by_name.items() if name not in models_to_exist
     ]
+
+    default_model = fetch_default_llm_model(db_session)
+
+    # Prevent removing and hiding the default model
+    if default_model:
+        for name, mc in existing_by_name.items():
+            if mc.id == default_model.id:
+                if default_model.id in removed_ids:
+                    raise ValueError(
+                        f"Cannot remove the default model '{name}'. "
+                        "Please change the default model before removing."
+                    )
+                if not requested_visibility.get(name, True):
+                    raise ValueError(
+                        f"Cannot hide the default model '{name}'. "
+                        "Please change the default model before hiding."
+                    )
+                break
+
     if removed_ids:
         db_session.query(ModelConfiguration).filter(
             ModelConfiguration.id.in_(removed_ids)
@@ -538,7 +563,6 @@ def fetch_default_model(
         .options(selectinload(ModelConfiguration.llm_provider))
         .join(LLMModelFlow)
         .where(
-            ModelConfiguration.is_visible == True,  # noqa: E712
             LLMModelFlow.llm_model_flow_type == flow_type,
             LLMModelFlow.is_default == True,  # noqa: E712
         )
@@ -814,44 +838,30 @@ def sync_auto_mode_models(
             )
             changes += 1
 
-    db_session.commit()
+    # Update the default if this provider currently holds the global CHAT default.
+    # We flush (but don't commit) so that _update_default_model can see the new
+    # model rows, then commit everything atomically to avoid a window where the
+    # old default is invisible but still pointed-to.
+    db_session.flush()
 
-    # Update the default if this provider currently holds the global CHAT default
     recommended_default = llm_recommendations.get_default_model(provider.provider)
     if recommended_default:
-        current_default_name = db_session.scalar(
-            select(ModelConfiguration.name)
-            .join(
-                LLMModelFlow,
-                LLMModelFlow.model_configuration_id == ModelConfiguration.id,
-            )
-            .where(
-                ModelConfiguration.llm_provider_id == provider.id,
-                LLMModelFlow.llm_model_flow_type == LLMModelFlowType.CHAT,
-                LLMModelFlow.is_default == True,  # noqa: E712
-            )
-        )
+        current_default = fetch_default_llm_model(db_session)
 
         if (
-            current_default_name is not None
-            and current_default_name != recommended_default.name
+            current_default
+            and current_default.llm_provider_id == provider.id
+            and current_default.name != recommended_default.name
         ):
-            try:
-                _update_default_model(
-                    db_session=db_session,
-                    provider_id=provider.id,
-                    model=recommended_default.name,
-                    flow_type=LLMModelFlowType.CHAT,
-                )
-                changes += 1
-            except ValueError:
-                logger.warning(
-                    "Recommended default model '%s' not found "
-                    "for provider_id=%s; skipping default update.",
-                    recommended_default.name,
-                    provider.id,
-                )
+            _update_default_model__no_commit(
+                db_session=db_session,
+                provider_id=provider.id,
+                model=recommended_default.name,
+                flow_type=LLMModelFlowType.CHAT,
+            )
+            changes += 1
 
+    db_session.commit()
     return changes
 
 
@@ -982,7 +992,7 @@ def update_model_configuration__no_commit(
     db_session.flush()
 
 
-def _update_default_model(
+def _update_default_model__no_commit(
     db_session: Session,
     provider_id: int,
     model: str,
@@ -1020,6 +1030,14 @@ def _update_default_model(
     new_default.is_default = True
     model_config.is_visible = True
 
+
+def _update_default_model(
+    db_session: Session,
+    provider_id: int,
+    model: str,
+    flow_type: LLMModelFlowType,
+) -> None:
+    _update_default_model__no_commit(db_session, provider_id, model, flow_type)
     db_session.commit()
 
 
diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index 0676775772f..0bb8c427b75 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -65,6 +65,7 @@
 from onyx.server.manage.llm.models import LLMProviderView
 from onyx.server.manage.llm.models import LMStudioFinalModelResponse
 from onyx.server.manage.llm.models import LMStudioModelsRequest
+from onyx.server.manage.llm.models import ModelConfigurationUpsertRequest
 from onyx.server.manage.llm.models import OllamaFinalModelResponse
 from onyx.server.manage.llm.models import OllamaModelDetails
 from onyx.server.manage.llm.models import OllamaModelsRequest
@@ -445,16 +446,17 @@ def put_llm_provider(
         not existing_provider or not existing_provider.is_auto_mode
     )
 
-    # Before the upsert, check if this provider currently owns the global
-    # CHAT default. The upsert may cascade-delete model_configurations
-    # (and their flow mappings), so we need to remember this beforehand.
-    was_default_provider = False
-    if existing_provider and transitioning_to_auto_mode:
-        current_default = fetch_default_llm_model(db_session)
-        was_default_provider = (
-            current_default is not None
-            and current_default.llm_provider_id == existing_provider.id
-        )
+    # When transitioning to auto mode, preserve existing model configurations
+    # so the upsert doesn't try to delete them (which would trip the default
+    # model protection guard). sync_auto_mode_models will handle the model
+    # lifecycle afterward — adding new models, hiding removed ones, and
+    # updating the default. This is safe even if sync fails: the provider
+    # keeps its old models and default rather than losing them.
+    if transitioning_to_auto_mode and existing_provider:
+        llm_provider_upsert_request.model_configurations = [
+            ModelConfigurationUpsertRequest.from_model(mc)
+            for mc in existing_provider.model_configurations
+        ]
 
     try:
         result = upsert_llm_provider(
@@ -468,7 +470,6 @@ def put_llm_provider(
 
             config = fetch_llm_recommendations_from_github()
             if config and llm_provider_upsert_request.provider in config.providers:
-                # Refetch the provider to get the updated model
                 updated_provider = fetch_existing_llm_provider_by_id(
                     id=result.id, db_session=db_session
                 )
@@ -478,20 +479,6 @@ def put_llm_provider(
                         updated_provider,
                         config,
                     )
-
-                    # If this provider was the default before the transition,
-                    # restore the default using the recommended model.
-                    if was_default_provider:
-                        recommended = config.get_default_model(
-                            llm_provider_upsert_request.provider
-                        )
-                        if recommended:
-                            update_default_provider(
-                                provider_id=updated_provider.id,
-                                model_name=recommended.name,
-                                db_session=db_session,
-                            )
-
                     # Refresh result with synced models
                     result = LLMProviderView.from_model(updated_provider)
 
diff --git a/backend/onyx/setup.py b/backend/onyx/setup.py
index ee3af79e0f3..085ae6fb000 100644
--- a/backend/onyx/setup.py
+++ b/backend/onyx/setup.py
@@ -275,9 +275,13 @@ def setup_postgres(db_session: Session) -> None:
             ],
             api_key_changed=True,
         )
-        new_llm_provider = upsert_llm_provider(
-            llm_provider_upsert_request=model_req, db_session=db_session
-        )
+        try:
+            new_llm_provider = upsert_llm_provider(
+                llm_provider_upsert_request=model_req, db_session=db_session
+            )
+        except ValueError as e:
+            logger.warning("Failed to upsert LLM provider during setup: %s", e)
+            return
         update_default_provider(
             provider_id=new_llm_provider.id, model_name=llm_model, db_session=db_session
         )
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py b/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
index ef986bb73ab..c954108c422 100644
--- a/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
@@ -1152,3 +1152,179 @@ def test_default_model_hidden_when_removed_from_config(
         finally:
             db_session.rollback()
             _cleanup_provider(db_session, provider_name)
+
+    def test_sync_updates_default_when_recommended_default_changes(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """When the provider owns the CHAT default and a sync arrives with a
+        different recommended default model (both models still in config),
+        the global default should be updated to the new recommendation.
+
+        Steps:
+        1. Create auto-mode provider with config v1: default=gpt-4o.
+        2. Set gpt-4o as the global CHAT default.
+        3. Re-sync with config v2: default=gpt-4o-mini (gpt-4o still present).
+        4. Verify the CHAT default switched to gpt-4o-mini and both models
+           remain visible.
+        """
+        config_v1 = _create_mock_llm_recommendations(
+            provider=LlmProviderNames.OPENAI,
+            default_model_name="gpt-4o",
+            additional_models=["gpt-4o-mini"],
+        )
+        config_v2 = _create_mock_llm_recommendations(
+            provider=LlmProviderNames.OPENAI,
+            default_model_name="gpt-4o-mini",
+            additional_models=["gpt-4o"],
+        )
+
+        try:
+            with patch(
+                "onyx.server.manage.llm.api.fetch_llm_recommendations_from_github",
+                return_value=config_v1,
+            ):
+                put_llm_provider(
+                    llm_provider_upsert_request=LLMProviderUpsertRequest(
+                        name=provider_name,
+                        provider=LlmProviderNames.OPENAI,
+                        api_key="sk-test-key-00000000000000000000000000000000000",
+                        api_key_changed=True,
+                        is_auto_mode=True,
+                        model_configurations=[],
+                    ),
+                    is_creation=True,
+                    _=_create_mock_admin(),
+                    db_session=db_session,
+                )
+
+            # Set gpt-4o as the global CHAT default
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+            update_default_provider(provider.id, "gpt-4o", db_session)
+
+            default_before = fetch_default_llm_model(db_session)
+            assert default_before is not None
+            assert default_before.name == "gpt-4o"
+
+            # Re-sync with config v2 (recommended default changed)
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+
+            changes = sync_auto_mode_models(
+                db_session=db_session,
+                provider=provider,
+                llm_recommendations=config_v2,
+            )
+            assert changes > 0, "Sync should report changes when default switches"
+
+            # Both models should remain visible
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+            visibility = {
+                mc.name: mc.is_visible for mc in provider.model_configurations
+            }
+            assert visibility["gpt-4o"] is True
+            assert visibility["gpt-4o-mini"] is True
+
+            # The CHAT default should now be gpt-4o-mini
+            default_after = fetch_default_llm_model(db_session)
+            assert default_after is not None
+            assert (
+                default_after.name == "gpt-4o-mini"
+            ), f"Default should be updated to 'gpt-4o-mini', got '{default_after.name}'"
+
+        finally:
+            db_session.rollback()
+            _cleanup_provider(db_session, provider_name)
+
+    def test_sync_idempotent_when_default_already_matches(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """When the provider owns the CHAT default and it already matches the
+        recommended default, re-syncing should report zero changes.
+
+        This is a regression test for the bug where changes was unconditionally
+        incremented even when the default was already correct.
+        """
+        config = _create_mock_llm_recommendations(
+            provider=LlmProviderNames.OPENAI,
+            default_model_name="gpt-4o",
+            additional_models=["gpt-4o-mini"],
+        )
+
+        try:
+            with patch(
+                "onyx.server.manage.llm.api.fetch_llm_recommendations_from_github",
+                return_value=config,
+            ):
+                put_llm_provider(
+                    llm_provider_upsert_request=LLMProviderUpsertRequest(
+                        name=provider_name,
+                        provider=LlmProviderNames.OPENAI,
+                        api_key="sk-test-key-00000000000000000000000000000000000",
+                        api_key_changed=True,
+                        is_auto_mode=True,
+                        model_configurations=[],
+                    ),
+                    is_creation=True,
+                    _=_create_mock_admin(),
+                    db_session=db_session,
+                )
+
+            # Set gpt-4o (the recommended default) as global CHAT default
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+            update_default_provider(provider.id, "gpt-4o", db_session)
+
+            # First sync to stabilize state
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+            sync_auto_mode_models(
+                db_session=db_session,
+                provider=provider,
+                llm_recommendations=config,
+            )
+
+            # Second sync — default already matches, should be a no-op
+            db_session.expire_all()
+            provider = fetch_existing_llm_provider(
+                name=provider_name, db_session=db_session
+            )
+            assert provider is not None
+            changes = sync_auto_mode_models(
+                db_session=db_session,
+                provider=provider,
+                llm_recommendations=config,
+            )
+            assert changes == 0, (
+                f"Expected 0 changes when default already matches recommended, "
+                f"got {changes}"
+            )
+
+            # Default should still be gpt-4o
+            default_model = fetch_default_llm_model(db_session)
+            assert default_model is not None
+            assert default_model.name == "gpt-4o"
+
+        finally:
+            db_session.rollback()
+            _cleanup_provider(db_session, provider_name)
diff --git a/backend/tests/external_dependency_unit/llm/test_llm_provider_default_model_protection.py b/backend/tests/external_dependency_unit/llm/test_llm_provider_default_model_protection.py
new file mode 100644
index 00000000000..f7004ceaeb1
--- /dev/null
+++ b/backend/tests/external_dependency_unit/llm/test_llm_provider_default_model_protection.py
@@ -0,0 +1,220 @@
+"""
+This should act as the main point of reference for testing that default model
+logic is consisten.
+
+ -
+"""
+
+from collections.abc import Generator
+from uuid import uuid4
+
+import pytest
+from sqlalchemy.orm import Session
+
+from onyx.db.llm import fetch_existing_llm_provider
+from onyx.db.llm import remove_llm_provider
+from onyx.db.llm import update_default_provider
+from onyx.db.llm import update_default_vision_provider
+from onyx.db.llm import upsert_llm_provider
+from onyx.llm.constants import LlmProviderNames
+from onyx.server.manage.llm.models import LLMProviderUpsertRequest
+from onyx.server.manage.llm.models import LLMProviderView
+from onyx.server.manage.llm.models import ModelConfigurationUpsertRequest
+
+
+def _create_test_provider(
+    db_session: Session,
+    name: str,
+    models: list[ModelConfigurationUpsertRequest] | None = None,
+) -> LLMProviderView:
+    """Helper to create a test LLM provider with multiple models."""
+    if models is None:
+        models = [
+            ModelConfigurationUpsertRequest(
+                name="gpt-4o", is_visible=True, supports_image_input=True
+            ),
+            ModelConfigurationUpsertRequest(
+                name="gpt-4o-mini", is_visible=True, supports_image_input=False
+            ),
+        ]
+    return upsert_llm_provider(
+        LLMProviderUpsertRequest(
+            name=name,
+            provider=LlmProviderNames.OPENAI,
+            api_key="sk-test-key-00000000000000000000000000000000000",
+            api_key_changed=True,
+            model_configurations=models,
+        ),
+        db_session=db_session,
+    )
+
+
+def _cleanup_provider(db_session: Session, name: str) -> None:
+    """Helper to clean up a test provider by name."""
+    provider = fetch_existing_llm_provider(name=name, db_session=db_session)
+    if provider:
+        remove_llm_provider(db_session, provider.id)
+
+
+@pytest.fixture
+def provider_name(db_session: Session) -> Generator[str, None, None]:
+    """Generate a unique provider name for each test, with automatic cleanup."""
+    name = f"test-provider-{uuid4().hex[:8]}"
+    yield name
+    db_session.rollback()
+    _cleanup_provider(db_session, name)
+
+
+class TestDefaultModelProtection:
+    """Tests that the default model cannot be removed or hidden."""
+
+    def test_cannot_remove_default_text_model(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """Removing the default text model from a provider should raise ValueError."""
+        provider = _create_test_provider(db_session, provider_name)
+        update_default_provider(provider.id, "gpt-4o", db_session)
+
+        # Try to update the provider without the default model
+        with pytest.raises(ValueError, match="Cannot remove the default model"):
+            upsert_llm_provider(
+                LLMProviderUpsertRequest(
+                    id=provider.id,
+                    name=provider_name,
+                    provider=LlmProviderNames.OPENAI,
+                    api_key="sk-test-key-00000000000000000000000000000000000",
+                    api_key_changed=True,
+                    model_configurations=[
+                        ModelConfigurationUpsertRequest(
+                            name="gpt-4o-mini", is_visible=True
+                        ),
+                    ],
+                ),
+                db_session=db_session,
+            )
+
+    def test_cannot_hide_default_text_model(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """Setting is_visible=False on the default text model should raise ValueError."""
+        provider = _create_test_provider(db_session, provider_name)
+        update_default_provider(provider.id, "gpt-4o", db_session)
+
+        # Try to hide the default model
+        with pytest.raises(ValueError, match="Cannot hide the default model"):
+            upsert_llm_provider(
+                LLMProviderUpsertRequest(
+                    id=provider.id,
+                    name=provider_name,
+                    provider=LlmProviderNames.OPENAI,
+                    api_key="sk-test-key-00000000000000000000000000000000000",
+                    api_key_changed=True,
+                    model_configurations=[
+                        ModelConfigurationUpsertRequest(
+                            name="gpt-4o", is_visible=False
+                        ),
+                        ModelConfigurationUpsertRequest(
+                            name="gpt-4o-mini", is_visible=True
+                        ),
+                    ],
+                ),
+                db_session=db_session,
+            )
+
+    def test_cannot_remove_default_vision_model(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """Removing the default vision model from a provider should raise ValueError."""
+        provider = _create_test_provider(db_session, provider_name)
+        # Set gpt-4o as both the text and vision default
+        update_default_provider(provider.id, "gpt-4o", db_session)
+        update_default_vision_provider(provider.id, "gpt-4o", db_session)
+
+        # Try to remove the default vision model
+        with pytest.raises(ValueError, match="Cannot remove the default model"):
+            upsert_llm_provider(
+                LLMProviderUpsertRequest(
+                    id=provider.id,
+                    name=provider_name,
+                    provider=LlmProviderNames.OPENAI,
+                    api_key="sk-test-key-00000000000000000000000000000000000",
+                    api_key_changed=True,
+                    model_configurations=[
+                        ModelConfigurationUpsertRequest(
+                            name="gpt-4o-mini", is_visible=True
+                        ),
+                    ],
+                ),
+                db_session=db_session,
+            )
+
+    def test_can_remove_non_default_model(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """Removing a non-default model should succeed."""
+        provider = _create_test_provider(db_session, provider_name)
+        update_default_provider(provider.id, "gpt-4o", db_session)
+
+        # Remove gpt-4o-mini (not default) — should succeed
+        updated = upsert_llm_provider(
+            LLMProviderUpsertRequest(
+                id=provider.id,
+                name=provider_name,
+                provider=LlmProviderNames.OPENAI,
+                api_key="sk-test-key-00000000000000000000000000000000000",
+                api_key_changed=True,
+                model_configurations=[
+                    ModelConfigurationUpsertRequest(
+                        name="gpt-4o", is_visible=True, supports_image_input=True
+                    ),
+                ],
+            ),
+            db_session=db_session,
+        )
+
+        model_names = {mc.name for mc in updated.model_configurations}
+        assert "gpt-4o" in model_names
+        assert "gpt-4o-mini" not in model_names
+
+    def test_can_hide_non_default_model(
+        self,
+        db_session: Session,
+        provider_name: str,
+    ) -> None:
+        """Hiding a non-default model should succeed."""
+        provider = _create_test_provider(db_session, provider_name)
+        update_default_provider(provider.id, "gpt-4o", db_session)
+
+        # Hide gpt-4o-mini (not default) — should succeed
+        updated = upsert_llm_provider(
+            LLMProviderUpsertRequest(
+                id=provider.id,
+                name=provider_name,
+                provider=LlmProviderNames.OPENAI,
+                api_key="sk-test-key-00000000000000000000000000000000000",
+                api_key_changed=True,
+                model_configurations=[
+                    ModelConfigurationUpsertRequest(
+                        name="gpt-4o", is_visible=True, supports_image_input=True
+                    ),
+                    ModelConfigurationUpsertRequest(
+                        name="gpt-4o-mini", is_visible=False
+                    ),
+                ],
+            ),
+            db_session=db_session,
+        )
+
+        model_visibility = {
+            mc.name: mc.is_visible for mc in updated.model_configurations
+        }
+        assert model_visibility["gpt-4o"] is True
+        assert model_visibility["gpt-4o-mini"] is False

From 5cdeb8416489ebe0c712cfb463a38c5a09dff88c Mon Sep 17 00:00:00 2001
From: SubashMohan <subashmohan75@gmail.com>
Date: Tue, 10 Mar 2026 16:20:32 +0530
Subject: [PATCH 208/267] feat(custom-tools): enhance custom tool error
 handling and timeline UI (#9189)

---
 backend/onyx/chat/llm_loop.py                 |   5 +
 .../server/query_and_chat/session_loading.py  |  65 +++-
 .../server/query_and_chat/streaming_models.py |  18 ++
 .../server/query_and_chat/streaming_utils.py  |  35 ---
 backend/onyx/tools/models.py                  |   2 +
 .../custom/custom_tool.py                     |  38 ++-
 web/src/app/app/message/CodeBlock.tsx         |   9 +-
 .../messageComponents/AgentMessage.tsx        |  15 +-
 .../messageComponents/CustomToolAuthCard.tsx  |  66 +++++
 .../messageComponents/hooks/useAuthErrors.ts  |  53 ++++
 .../message/messageComponents/interfaces.ts   |   5 +
 .../renderers/CustomToolRenderer.tsx          | 277 ++++++++++++++----
 .../timeline/ExpandedTimelineContent.tsx      |  28 +-
 .../timeline/ParallelTimelineTabs.tsx         |  15 +-
 .../timeline/StepContainer.tsx                |  10 +-
 .../timeline/TimelineStepComposer.tsx         |   6 +-
 .../primitives/TimelineStepContent.tsx        |  16 +-
 .../timeline/primitives/TimelineSurface.tsx   |  13 +-
 .../deepresearch/DeepResearchPlanRenderer.tsx |   1 +
 .../deepresearch/ResearchAgentRenderer.tsx    |   4 -
 .../renderers/memory/MemoryToolRenderer.tsx   |   3 +
 .../renderers/reasoning/ReasoningRenderer.tsx |   8 +-
 web/src/app/app/services/packetUtils.ts       |   1 +
 web/src/app/app/services/streamingModels.ts   |  17 ++
 .../components/oauth/OAuthCallbackPage.tsx    |  17 +-
 web/src/hooks/useToast.ts                     |  14 +-
 .../refresh-components/messages/Message.tsx   |  23 +-
 web/src/refresh-pages/AppPage.tsx             |   9 +-
 28 files changed, 600 insertions(+), 173 deletions(-)
 create mode 100644 web/src/app/app/message/messageComponents/CustomToolAuthCard.tsx
 create mode 100644 web/src/app/app/message/messageComponents/hooks/useAuthErrors.ts

diff --git a/backend/onyx/chat/llm_loop.py b/backend/onyx/chat/llm_loop.py
index 324baf5e00a..60dcb9de523 100644
--- a/backend/onyx/chat/llm_loop.py
+++ b/backend/onyx/chat/llm_loop.py
@@ -50,6 +50,7 @@
 from onyx.tools.built_in_tools import STOPPING_TOOLS_NAMES
 from onyx.tools.interface import Tool
 from onyx.tools.models import ChatFile
+from onyx.tools.models import CustomToolCallSummary
 from onyx.tools.models import MemoryToolResponseSnapshot
 from onyx.tools.models import PythonToolRichResponse
 from onyx.tools.models import ToolCallInfo
@@ -980,6 +981,10 @@ def run_llm_loop(
 
                 if memory_snapshot:
                     saved_response = json.dumps(memory_snapshot.model_dump())
+                elif isinstance(tool_response.rich_response, CustomToolCallSummary):
+                    saved_response = json.dumps(
+                        tool_response.rich_response.model_dump()
+                    )
                 elif isinstance(tool_response.rich_response, str):
                     saved_response = tool_response.rich_response
                 else:
diff --git a/backend/onyx/server/query_and_chat/session_loading.py b/backend/onyx/server/query_and_chat/session_loading.py
index 12fe95cc1fb..63538c11c40 100644
--- a/backend/onyx/server/query_and_chat/session_loading.py
+++ b/backend/onyx/server/query_and_chat/session_loading.py
@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import json
+from typing import Any
 from typing import cast
 from typing import Literal
 
+from pydantic import ValidationError
 from sqlalchemy.orm import Session
 
 from onyx.chat.citation_utils import extract_citation_order_from_text
@@ -20,7 +22,9 @@
 from onyx.server.query_and_chat.streaming_models import AgentResponseDelta
 from onyx.server.query_and_chat.streaming_models import AgentResponseStart
 from onyx.server.query_and_chat.streaming_models import CitationInfo
+from onyx.server.query_and_chat.streaming_models import CustomToolArgs
 from onyx.server.query_and_chat.streaming_models import CustomToolDelta
+from onyx.server.query_and_chat.streaming_models import CustomToolErrorInfo
 from onyx.server.query_and_chat.streaming_models import CustomToolStart
 from onyx.server.query_and_chat.streaming_models import FileReaderResult
 from onyx.server.query_and_chat.streaming_models import FileReaderStart
@@ -180,24 +184,37 @@ def create_custom_tool_packets(
     tab_index: int = 0,
     data: dict | list | str | int | float | bool | None = None,
     file_ids: list[str] | None = None,
+    error: CustomToolErrorInfo | None = None,
+    tool_args: dict[str, Any] | None = None,
+    tool_id: int | None = None,
 ) -> list[Packet]:
     packets: list[Packet] = []
 
     packets.append(
         Packet(
             placement=Placement(turn_index=turn_index, tab_index=tab_index),
-            obj=CustomToolStart(tool_name=tool_name),
+            obj=CustomToolStart(tool_name=tool_name, tool_id=tool_id),
         )
     )
 
+    if tool_args:
+        packets.append(
+            Packet(
+                placement=Placement(turn_index=turn_index, tab_index=tab_index),
+                obj=CustomToolArgs(tool_name=tool_name, tool_args=tool_args),
+            )
+        )
+
     packets.append(
         Packet(
             placement=Placement(turn_index=turn_index, tab_index=tab_index),
             obj=CustomToolDelta(
                 tool_name=tool_name,
+                tool_id=tool_id,
                 response_type=response_type,
                 data=data,
                 file_ids=file_ids,
+                error=error,
             ),
         ),
     )
@@ -657,13 +674,55 @@ def translate_assistant_message_to_packets(
 
                     else:
                         # Custom tool or unknown tool
+                        # Try to parse as structured CustomToolCallSummary JSON
+                        custom_data: dict | list | str | int | float | bool | None = (
+                            tool_call.tool_call_response
+                        )
+                        custom_error: CustomToolErrorInfo | None = None
+                        custom_response_type = "text"
+
+                        try:
+                            parsed = json.loads(tool_call.tool_call_response)
+                            if isinstance(parsed, dict) and "tool_name" in parsed:
+                                custom_data = parsed.get("tool_result")
+                                custom_response_type = parsed.get(
+                                    "response_type", "text"
+                                )
+                                if parsed.get("error"):
+                                    custom_error = CustomToolErrorInfo(
+                                        **parsed["error"]
+                                    )
+                        except (
+                            json.JSONDecodeError,
+                            KeyError,
+                            TypeError,
+                            ValidationError,
+                        ):
+                            pass
+
+                        custom_file_ids: list[str] | None = None
+                        if custom_response_type in ("image", "csv") and isinstance(
+                            custom_data, dict
+                        ):
+                            custom_file_ids = custom_data.get("file_ids")
+                            custom_data = None
+
+                        custom_args = {
+                            k: v
+                            for k, v in (tool_call.tool_call_arguments or {}).items()
+                            if k != "requestBody"
+                        }
                         turn_tool_packets.extend(
                             create_custom_tool_packets(
                                 tool_name=tool.display_name or tool.name,
-                                response_type="text",
+                                response_type=custom_response_type,
                                 turn_index=turn_num,
                                 tab_index=tool_call.tab_index,
-                                data=tool_call.tool_call_response,
+                                data=custom_data,
+                                file_ids=custom_file_ids,
+                                error=custom_error,
+                                tool_args=custom_args if custom_args else None,
+                                tool_id=tool_call.tool_id,
                             )
                         )
 
diff --git a/backend/onyx/server/query_and_chat/streaming_models.py b/backend/onyx/server/query_and_chat/streaming_models.py
index a1c3b606b5c..6015efa0fa8 100644
--- a/backend/onyx/server/query_and_chat/streaming_models.py
+++ b/backend/onyx/server/query_and_chat/streaming_models.py
@@ -33,6 +33,7 @@ class StreamingType(Enum):
     PYTHON_TOOL_START = "python_tool_start"
     PYTHON_TOOL_DELTA = "python_tool_delta"
     CUSTOM_TOOL_START = "custom_tool_start"
+    CUSTOM_TOOL_ARGS = "custom_tool_args"
     CUSTOM_TOOL_DELTA = "custom_tool_delta"
     FILE_READER_START = "file_reader_start"
     FILE_READER_RESULT = "file_reader_result"
@@ -246,6 +247,20 @@ class CustomToolStart(BaseObj):
     type: Literal["custom_tool_start"] = StreamingType.CUSTOM_TOOL_START.value
 
     tool_name: str
+    tool_id: int | None = None
+
+
+class CustomToolArgs(BaseObj):
+    type: Literal["custom_tool_args"] = StreamingType.CUSTOM_TOOL_ARGS.value
+
+    tool_name: str
+    tool_args: dict[str, Any]
+
+
+class CustomToolErrorInfo(BaseModel):
+    is_auth_error: bool = False
+    status_code: int
+    message: str
 
 
 # The allowed streamed packets for a custom tool
@@ -253,11 +268,13 @@ class CustomToolDelta(BaseObj):
     type: Literal["custom_tool_delta"] = StreamingType.CUSTOM_TOOL_DELTA.value
 
     tool_name: str
+    tool_id: int | None = None
     response_type: str
     # For non-file responses
     data: dict | list | str | int | float | bool | None = None
     # For file-based responses like image/csv
     file_ids: list[str] | None = None
+    error: CustomToolErrorInfo | None = None
 
 
 class ToolCallArgumentDelta(BaseObj):
@@ -376,6 +393,7 @@ class IntermediateReportCitedDocs(BaseObj):
     PythonToolStart,
     PythonToolDelta,
     CustomToolStart,
+    CustomToolArgs,
     CustomToolDelta,
     FileReaderStart,
     FileReaderResult,
diff --git a/backend/onyx/server/query_and_chat/streaming_utils.py b/backend/onyx/server/query_and_chat/streaming_utils.py
index 2b93a84cddc..c5f8e72412a 100644
--- a/backend/onyx/server/query_and_chat/streaming_utils.py
+++ b/backend/onyx/server/query_and_chat/streaming_utils.py
@@ -8,8 +8,6 @@
 from onyx.server.query_and_chat.streaming_models import AgentResponseDelta
 from onyx.server.query_and_chat.streaming_models import AgentResponseStart
 from onyx.server.query_and_chat.streaming_models import CitationInfo
-from onyx.server.query_and_chat.streaming_models import CustomToolDelta
-from onyx.server.query_and_chat.streaming_models import CustomToolStart
 from onyx.server.query_and_chat.streaming_models import GeneratedImage
 from onyx.server.query_and_chat.streaming_models import ImageGenerationFinal
 from onyx.server.query_and_chat.streaming_models import ImageGenerationToolStart
@@ -165,39 +163,6 @@ def create_image_generation_packets(
     return packets
 
 
-def create_custom_tool_packets(
-    tool_name: str,
-    response_type: str,
-    turn_index: int,
-    data: dict | list | str | int | float | bool | None = None,
-    file_ids: list[str] | None = None,
-) -> list[Packet]:
-    packets: list[Packet] = []
-
-    packets.append(
-        Packet(
-            placement=Placement(turn_index=turn_index),
-            obj=CustomToolStart(tool_name=tool_name),
-        )
-    )
-
-    packets.append(
-        Packet(
-            placement=Placement(turn_index=turn_index),
-            obj=CustomToolDelta(
-                tool_name=tool_name,
-                response_type=response_type,
-                data=data,
-                file_ids=file_ids,
-            ),
-        ),
-    )
-
-    packets.append(Packet(placement=Placement(turn_index=turn_index), obj=SectionEnd()))
-
-    return packets
-
-
 def create_fetch_packets(
     fetch_docs: list[SavedSearchDoc],
     urls: list[str],
diff --git a/backend/onyx/tools/models.py b/backend/onyx/tools/models.py
index 99962dd2094..632e8eb05a2 100644
--- a/backend/onyx/tools/models.py
+++ b/backend/onyx/tools/models.py
@@ -18,6 +18,7 @@
 from onyx.context.search.models import SearchDocsResponse
 from onyx.db.memory import UserMemoryContext
 from onyx.server.query_and_chat.placement import Placement
+from onyx.server.query_and_chat.streaming_models import CustomToolErrorInfo
 from onyx.server.query_and_chat.streaming_models import GeneratedImage
 from onyx.tools.tool_implementations.images.models import FinalImageGenerationResponse
 from onyx.tools.tool_implementations.memory.models import MemoryToolResponse
@@ -61,6 +62,7 @@ class CustomToolCallSummary(BaseModel):
     tool_name: str
     response_type: str  # e.g., 'json', 'image', 'csv', 'graph'
     tool_result: Any  # The response data
+    error: CustomToolErrorInfo | None = None
 
 
 class ToolCallKickoff(BaseModel):
diff --git a/backend/onyx/tools/tool_implementations/custom/custom_tool.py b/backend/onyx/tools/tool_implementations/custom/custom_tool.py
index 30e49b8becd..c1e95287e0d 100644
--- a/backend/onyx/tools/tool_implementations/custom/custom_tool.py
+++ b/backend/onyx/tools/tool_implementations/custom/custom_tool.py
@@ -15,7 +15,9 @@
 from onyx.configs.constants import FileOrigin
 from onyx.file_store.file_store import get_default_file_store
 from onyx.server.query_and_chat.placement import Placement
+from onyx.server.query_and_chat.streaming_models import CustomToolArgs
 from onyx.server.query_and_chat.streaming_models import CustomToolDelta
+from onyx.server.query_and_chat.streaming_models import CustomToolErrorInfo
 from onyx.server.query_and_chat.streaming_models import CustomToolStart
 from onyx.server.query_and_chat.streaming_models import Packet
 from onyx.tools.interface import Tool
@@ -139,7 +141,7 @@ def emit_start(self, placement: Placement) -> None:
         self.emitter.emit(
             Packet(
                 placement=placement,
-                obj=CustomToolStart(tool_name=self._name),
+                obj=CustomToolStart(tool_name=self._name, tool_id=self._id),
             )
         )
 
@@ -149,10 +151,8 @@ def run(
         override_kwargs: None = None,  # noqa: ARG002
         **llm_kwargs: Any,
     ) -> ToolResponse:
-        request_body = llm_kwargs.get(REQUEST_BODY)
-
+        # Build path params
         path_params = {}
-
         for path_param_schema in self._method_spec.get_path_param_schemas():
             param_name = path_param_schema["name"]
             if param_name not in llm_kwargs:
@@ -165,6 +165,7 @@ def run(
                 )
             path_params[param_name] = llm_kwargs[param_name]
 
+        # Build query params
         query_params = {}
         for query_param_schema in self._method_spec.get_query_param_schemas():
             if query_param_schema["name"] in llm_kwargs:
@@ -172,6 +173,20 @@ def run(
                     query_param_schema["name"]
                 ]
 
+        # Emit args packet (path + query params only, no request body)
+        tool_args = {**path_params, **query_params}
+        if tool_args:
+            self.emitter.emit(
+                Packet(
+                    placement=placement,
+                    obj=CustomToolArgs(
+                        tool_name=self._name,
+                        tool_args=tool_args,
+                    ),
+                )
+            )
+
+        request_body = llm_kwargs.get(REQUEST_BODY)
         url = self._method_spec.build_url(self._base_url, path_params, query_params)
         method = self._method_spec.method
 
@@ -180,6 +195,18 @@ def run(
         )
         content_type = response.headers.get("Content-Type", "")
 
+        # Detect HTTP errors — only 401/403 are flagged as auth errors
+        error_info: CustomToolErrorInfo | None = None
+        if response.status_code in (401, 403):
+            error_info = CustomToolErrorInfo(
+                is_auth_error=True,
+                status_code=response.status_code,
+                message=f"{self._name} action failed because of authentication error",
+            )
+            logger.warning(
+                f"Auth error from custom tool '{self._name}': HTTP {response.status_code}"
+            )
+
         tool_result: Any
         response_type: str
         file_ids: List[str] | None = None
@@ -222,9 +249,11 @@ def run(
                 placement=placement,
                 obj=CustomToolDelta(
                     tool_name=self._name,
+                    tool_id=self._id,
                     response_type=response_type,
                     data=data,
                     file_ids=file_ids,
+                    error=error_info,
                 ),
             )
         )
@@ -236,6 +265,7 @@ def run(
                 tool_name=self._name,
                 response_type=response_type,
                 tool_result=tool_result,
+                error=error_info,
             ),
             llm_facing_response=llm_facing_response,
         )
diff --git a/web/src/app/app/message/CodeBlock.tsx b/web/src/app/app/message/CodeBlock.tsx
index f311b773570..ea02992e508 100644
--- a/web/src/app/app/message/CodeBlock.tsx
+++ b/web/src/app/app/message/CodeBlock.tsx
@@ -8,6 +8,7 @@ interface CodeBlockProps {
   children?: ReactNode;
   codeText: string;
   showHeader?: boolean;
+  noPadding?: boolean;
 }
 
 const MemoizedCodeLine = memo(({ content }: { content: ReactNode }) => (
@@ -19,6 +20,7 @@ export const CodeBlock = memo(function CodeBlock({
   children,
   codeText,
   showHeader = true,
+  noPadding = false,
 }: CodeBlockProps) {
   const [copied, setCopied] = useState(false);
 
@@ -115,7 +117,12 @@ export const CodeBlock = memo(function CodeBlock({
   return (
     <>
       {showHeader ? (
-        <div className="bg-background-tint-00 px-1 pb-1 rounded-12 max-w-full min-w-0">
+        <div
+          className={cn(
+            "bg-background-tint-00 rounded-12 max-w-full min-w-0",
+            !noPadding && "px-1 pb-1"
+          )}
+        >
           {language && (
             <div className="flex items-center px-2 py-1 text-sm text-text-04 gap-x-2">
               <SvgCode
diff --git a/web/src/app/app/message/messageComponents/AgentMessage.tsx b/web/src/app/app/message/messageComponents/AgentMessage.tsx
index 96144eb8d22..c67f820b9b4 100644
--- a/web/src/app/app/message/messageComponents/AgentMessage.tsx
+++ b/web/src/app/app/message/messageComponents/AgentMessage.tsx
@@ -2,9 +2,11 @@
 
 import React, { useRef, RefObject, useMemo } from "react";
 import { Packet, StopReason } from "@/app/app/services/streamingModels";
+import CustomToolAuthCard from "@/app/app/message/messageComponents/CustomToolAuthCard";
 import { FullChatState } from "@/app/app/message/messageComponents/interfaces";
 import { FeedbackType } from "@/app/app/interfaces";
 import { handleCopy } from "@/app/app/message/copyingUtils";
+import { useAuthErrors } from "@/app/app/message/messageComponents/hooks/useAuthErrors";
 import { useMessageSwitching } from "@/app/app/message/messageComponents/hooks/useMessageSwitching";
 import { RendererComponent } from "@/app/app/message/messageComponents/renderMessageComponent";
 import { usePacketProcessor } from "@/app/app/message/messageComponents/timeline/hooks/usePacketProcessor";
@@ -146,6 +148,8 @@ const AgentMessage = React.memo(function AgentMessage({
     ]
   );
 
+  const authErrors = useAuthErrors(rawPackets);
+
   // Message switching logic
   const {
     currentMessageInd,
@@ -189,7 +193,16 @@ const AgentMessage = React.memo(function AgentMessage({
         }}
       >
         {pacedDisplayGroups.length > 0 && (
-          <div ref={finalAnswerRef}>
+          <div ref={finalAnswerRef} className="flex flex-col gap-3">
+            {authErrors.map((authError, i) => (
+              <CustomToolAuthCard
+                key={`auth-error-${i}`}
+                toolName={authError.toolName}
+                toolId={authError.toolId}
+                tools={effectiveChatState.agent.tools}
+                agentId={effectiveChatState.agent.id}
+              />
+            ))}
             {pacedDisplayGroups.map((displayGroup, index) => (
               <RendererComponent
                 key={`${displayGroup.turn_index}-${displayGroup.tab_index}`}
diff --git a/web/src/app/app/message/messageComponents/CustomToolAuthCard.tsx b/web/src/app/app/message/messageComponents/CustomToolAuthCard.tsx
new file mode 100644
index 00000000000..eb02e15fa37
--- /dev/null
+++ b/web/src/app/app/message/messageComponents/CustomToolAuthCard.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import { useMemo } from "react";
+import Message from "@/refresh-components/messages/Message";
+import { ToolSnapshot } from "@/lib/tools/interfaces";
+import { initiateOAuthFlow } from "@/lib/oauth/api";
+import { useToolOAuthStatus } from "@/lib/hooks/useToolOAuthStatus";
+import { SvgArrowExchange } from "@opal/icons";
+
+interface CustomToolAuthCardProps {
+  toolName: string;
+  toolId: number | null;
+  tools: ToolSnapshot[];
+  agentId: number;
+}
+
+function CustomToolAuthCard({
+  toolName,
+  toolId,
+  tools,
+  agentId,
+}: CustomToolAuthCardProps) {
+  const { getToolAuthStatus } = useToolOAuthStatus(agentId);
+  const matchedTool = useMemo(() => {
+    if (toolId == null) return null;
+    return tools.find((t) => t.id === toolId) ?? null;
+  }, [toolId, tools]);
+
+  // Hide the card if the user already has a valid token
+  const authStatus = matchedTool ? getToolAuthStatus(matchedTool) : undefined;
+  if (authStatus?.hasToken && !authStatus.isTokenExpired) {
+    return null;
+  }
+
+  const oauthConfigId = matchedTool?.oauth_config_id ?? null;
+
+  // No OAuth config — nothing actionable to show
+  if (!oauthConfigId) {
+    return null;
+  }
+
+  const handleAuthenticate = () => {
+    initiateOAuthFlow(
+      oauthConfigId,
+      window.location.pathname + window.location.search
+    );
+  };
+
+  return (
+    <Message
+      static
+      large
+      icon
+      close={false}
+      text={`${toolName} not connected`}
+      description={`Connect to ${toolName} to enable this tool`}
+      actions="Connect"
+      actionPrimary
+      actionIcon={SvgArrowExchange}
+      onAction={handleAuthenticate}
+      className="w-full"
+    />
+  );
+}
+
+export default CustomToolAuthCard;
diff --git a/web/src/app/app/message/messageComponents/hooks/useAuthErrors.ts b/web/src/app/app/message/messageComponents/hooks/useAuthErrors.ts
new file mode 100644
index 00000000000..ff8a4a89ccf
--- /dev/null
+++ b/web/src/app/app/message/messageComponents/hooks/useAuthErrors.ts
@@ -0,0 +1,53 @@
+import { useRef } from "react";
+import {
+  CustomToolDelta,
+  Packet,
+  PacketType,
+} from "@/app/app/services/streamingModels";
+
+interface AuthError {
+  toolName: string;
+  toolId: number | null;
+}
+
+export function useAuthErrors(rawPackets: Packet[]): AuthError[] {
+  const stateRef = useRef<{ processedCount: number; errors: AuthError[] }>({
+    processedCount: 0,
+    errors: [],
+  });
+
+  // Reset if packets shrunk (e.g. new message)
+  if (rawPackets.length < stateRef.current.processedCount) {
+    stateRef.current = { processedCount: 0, errors: [] };
+  }
+
+  // Process only new packets (incremental, like usePacketProcessor)
+  if (rawPackets.length > stateRef.current.processedCount) {
+    let newErrors = stateRef.current.errors;
+    for (let i = stateRef.current.processedCount; i < rawPackets.length; i++) {
+      const packet = rawPackets[i]!;
+      if (packet.obj.type === PacketType.CUSTOM_TOOL_DELTA) {
+        const delta = packet.obj as CustomToolDelta;
+        if (delta.error?.is_auth_error) {
+          const alreadyPresent = newErrors.some(
+            (e) =>
+              (delta.tool_id != null && e.toolId === delta.tool_id) ||
+              (delta.tool_id == null && e.toolName === delta.tool_name)
+          );
+          if (!alreadyPresent) {
+            newErrors = [
+              ...newErrors,
+              { toolName: delta.tool_name, toolId: delta.tool_id ?? null },
+            ];
+          }
+        }
+      }
+    }
+    stateRef.current = {
+      processedCount: rawPackets.length,
+      errors: newErrors,
+    };
+  }
+
+  return stateRef.current.errors;
+}
diff --git a/web/src/app/app/message/messageComponents/interfaces.ts b/web/src/app/app/message/messageComponents/interfaces.ts
index dadb518259a..c4858bb6f3d 100644
--- a/web/src/app/app/message/messageComponents/interfaces.ts
+++ b/web/src/app/app/message/messageComponents/interfaces.ts
@@ -7,6 +7,7 @@ import { LlmDescriptor } from "@/lib/hooks";
 import { IconType } from "react-icons";
 import { OnyxIconType } from "@/components/icons/icons";
 import { CitationMap } from "../../interfaces";
+import { TimelineSurfaceBackground } from "@/app/app/message/messageComponents/timeline/primitives/TimelineSurface";
 
 export enum RenderType {
   HIGHLIGHT = "highlight",
@@ -51,6 +52,10 @@ export interface RendererResult {
   alwaysCollapsible?: boolean;
   /** Whether the result should be wrapped by timeline UI or rendered as-is */
   timelineLayout?: TimelineLayout;
+  /** Remove right padding for long-form content (reasoning, deep research, memory). */
+  noPaddingRight?: boolean;
+  /** Override the surface background (e.g. "error" for auth failures). */
+  surfaceBackground?: TimelineSurfaceBackground;
 }
 
 // All renderers return an array of results (even single-step renderers return a 1-element array)
diff --git a/web/src/app/app/message/messageComponents/renderers/CustomToolRenderer.tsx b/web/src/app/app/message/messageComponents/renderers/CustomToolRenderer.tsx
index b957330a097..c04e0cd38d4 100644
--- a/web/src/app/app/message/messageComponents/renderers/CustomToolRenderer.tsx
+++ b/web/src/app/app/message/messageComponents/renderers/CustomToolRenderer.tsx
@@ -1,14 +1,58 @@
 import React, { useEffect, useMemo } from "react";
-import { FiExternalLink, FiDownload, FiTool } from "react-icons/fi";
 import {
   PacketType,
   CustomToolPacket,
   CustomToolStart,
+  CustomToolArgs,
   CustomToolDelta,
+  CustomToolErrorInfo,
   SectionEnd,
 } from "../../../services/streamingModels";
 import { MessageRenderer, RenderType } from "../interfaces";
 import { buildImgUrl } from "../../../components/files/images/utils";
+import Text from "@/refresh-components/texts/Text";
+import {
+  SvgActions,
+  SvgArrowExchange,
+  SvgDownload,
+  SvgExternalLink,
+} from "@opal/icons";
+import { CodeBlock } from "@/app/app/message/CodeBlock";
+import hljs from "highlight.js/lib/core";
+import json from "highlight.js/lib/languages/json";
+import FadingEdgeContainer from "@/refresh-components/FadingEdgeContainer";
+
+// Lazy registration for hljs JSON language
+function ensureHljsRegistered() {
+  if (!hljs.listLanguages().includes("json")) {
+    hljs.registerLanguage("json", json);
+  }
+}
+
+// Component to render syntax-highlighted JSON
+interface HighlightedJsonCodeProps {
+  code: string;
+}
+function HighlightedJsonCode({ code }: HighlightedJsonCodeProps) {
+  const highlightedHtml = useMemo(() => {
+    ensureHljsRegistered();
+    try {
+      return hljs.highlight(code, { language: "json" }).value;
+    } catch {
+      return code
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+    }
+  }, [code]);
+
+  return (
+    <span
+      dangerouslySetInnerHTML={{ __html: highlightedHtml }}
+      className="hljs"
+    />
+  );
+}
 
 function constructCustomToolState(packets: CustomToolPacket[]) {
   const toolStart = packets.find(
@@ -23,19 +67,26 @@ function constructCustomToolState(packets: CustomToolPacket[]) {
   )?.obj as SectionEnd | null;
 
   const toolName = toolStart?.tool_name || toolDeltas[0]?.tool_name || "Tool";
+  const toolArgsPacket = packets.find(
+    (p) => p.obj.type === PacketType.CUSTOM_TOOL_ARGS
+  )?.obj as CustomToolArgs | null;
+  const toolArgs = toolArgsPacket?.tool_args ?? null;
   const latestDelta = toolDeltas[toolDeltas.length - 1] || null;
   const responseType = latestDelta?.response_type || null;
   const data = latestDelta?.data;
   const fileIds = latestDelta?.file_ids || null;
+  const error = latestDelta?.error || null;
 
   const isRunning = Boolean(toolStart && !toolEnd);
   const isComplete = Boolean(toolStart && toolEnd);
 
   return {
     toolName,
+    toolArgs,
     responseType,
     data,
     fileIds,
+    error,
     isRunning,
     isComplete,
   };
@@ -47,8 +98,16 @@ export const CustomToolRenderer: MessageRenderer<CustomToolPacket, {}> = ({
   renderType,
   children,
 }) => {
-  const { toolName, responseType, data, fileIds, isRunning, isComplete } =
-    constructCustomToolState(packets);
+  const {
+    toolName,
+    toolArgs,
+    responseType,
+    data,
+    fileIds,
+    error,
+    isRunning,
+    isComplete,
+  } = constructCustomToolState(packets);
 
   useEffect(() => {
     if (isComplete) {
@@ -58,76 +117,192 @@ export const CustomToolRenderer: MessageRenderer<CustomToolPacket, {}> = ({
 
   const status = useMemo(() => {
     if (isComplete) {
+      if (error) {
+        return error.is_auth_error
+          ? `${toolName} authentication failed (HTTP ${error.status_code})`
+          : `${toolName} failed (HTTP ${error.status_code})`;
+      }
       if (responseType === "image") return `${toolName} returned images`;
       if (responseType === "csv") return `${toolName} returned a file`;
       return `${toolName} completed`;
     }
     if (isRunning) return `${toolName} running...`;
     return null;
-  }, [toolName, responseType, isComplete, isRunning]);
+  }, [toolName, responseType, error, isComplete, isRunning]);
+
+  const icon = SvgActions;
+
+  const toolArgsJson = useMemo(
+    () => (toolArgs ? JSON.stringify(toolArgs, null, 2) : null),
+    [toolArgs]
+  );
+  const dataJson = useMemo(
+    () =>
+      data !== undefined && data !== null && typeof data === "object"
+        ? JSON.stringify(data, null, 2)
+        : null,
+    [data]
+  );
+
+  const content = useMemo(
+    () => (
+      <div className="flex flex-col gap-3">
+        {/* Loading indicator */}
+        {isRunning &&
+          !error &&
+          !fileIds &&
+          (data === undefined || data === null) && (
+            <div className="flex items-center gap-2 text-sm text-text-03">
+              <div className="flex gap-0.5">
+                <div className="w-1 h-1 bg-current rounded-full animate-pulse"></div>
+                <div
+                  className="w-1 h-1 bg-current rounded-full animate-pulse"
+                  style={{ animationDelay: "0.1s" }}
+                ></div>
+                <div
+                  className="w-1 h-1 bg-current rounded-full animate-pulse"
+                  style={{ animationDelay: "0.2s" }}
+                ></div>
+              </div>
+              <Text text03 secondaryBody>
+                Waiting for response...
+              </Text>
+            </div>
+          )}
+
+        {/* Tool arguments */}
+        {toolArgsJson && (
+          <div>
+            <div className="flex items-center gap-1">
+              <SvgArrowExchange className="w-3 h-3 text-text-02" />
+              <Text text04 secondaryBody>
+                Request
+              </Text>
+            </div>
+            <div className="prose max-w-full">
+              <CodeBlock
+                className="font-secondary-mono"
+                codeText={toolArgsJson}
+                noPadding
+              >
+                <HighlightedJsonCode code={toolArgsJson} />
+              </CodeBlock>
+            </div>
+          </div>
+        )}
+
+        {/* Error display */}
+        {error && (
+          <div className="pl-[var(--timeline-common-text-padding)]">
+            <Text text03 mainUiMuted>
+              {error.message}
+            </Text>
+          </div>
+        )}
 
-  const icon = FiTool;
+        {/* File responses */}
+        {!error && fileIds && fileIds.length > 0 && (
+          <div className="text-sm text-text-03 flex flex-col gap-2">
+            {fileIds.map((fid, idx) => (
+              <div key={fid} className="flex items-center gap-2 flex-wrap">
+                <Text text03 secondaryBody className="whitespace-nowrap">
+                  File {idx + 1}
+                </Text>
+                <a
+                  href={buildImgUrl(fid)}
+                  target="_blank"
+                  rel="noreferrer"
+                  className="inline-flex items-center gap-1 text-xs text-action-link-01 hover:underline whitespace-nowrap"
+                >
+                  <SvgExternalLink className="w-3 h-3" /> Open
+                </a>
+                <a
+                  href={buildImgUrl(fid)}
+                  download
+                  className="inline-flex items-center gap-1 text-xs text-action-link-01 hover:underline whitespace-nowrap"
+                >
+                  <SvgDownload className="w-3 h-3" /> Download
+                </a>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* JSON/Text responses */}
+        {!error && data !== undefined && data !== null && (
+          <div>
+            <div className="flex items-center gap-1">
+              <SvgArrowExchange className="w-3 h-3 text-text-02" />
+              <Text text04 secondaryBody>
+                Response
+              </Text>
+            </div>
+            <div className="prose max-w-full">
+              {dataJson ? (
+                <CodeBlock
+                  className="font-secondary-mono"
+                  codeText={dataJson}
+                  noPadding
+                >
+                  <HighlightedJsonCode code={dataJson} />
+                </CodeBlock>
+              ) : (
+                <CodeBlock
+                  className="font-secondary-mono"
+                  codeText={String(data)}
+                  noPadding
+                >
+                  {String(data)}
+                </CodeBlock>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+    ),
+    [toolArgsJson, dataJson, data, fileIds, error, isRunning]
+  );
 
-  if (renderType === RenderType.COMPACT) {
+  // Auth error: always render FULL with error surface
+  if (error?.is_auth_error) {
     return children([
       {
         icon,
-        status: status,
+        status,
+        supportsCollapsible: false,
+        noPaddingRight: true,
+        surfaceBackground: "error" as const,
+        content,
+      },
+    ]);
+  }
+
+  // FULL mode
+  if (renderType === RenderType.FULL) {
+    return children([
+      {
+        icon,
+        status,
         supportsCollapsible: true,
-        // Status is already shown in the step header in compact mode.
-        // Avoid duplicating the same line in the content body.
-        content: <></>,
+        noPaddingRight: true,
+        content,
       },
     ]);
   }
 
+  // COMPACT mode: wrap in fading container
   return children([
     {
       icon,
       status,
       supportsCollapsible: true,
       content: (
-        <div className="flex flex-col gap-3">
-          {/* File responses */}
-          {fileIds && fileIds.length > 0 && (
-            <div className="text-sm text-muted-foreground flex flex-col gap-2">
-              {fileIds.map((fid, idx) => (
-                <div key={fid} className="flex items-center gap-2 flex-wrap">
-                  <span className="whitespace-nowrap">File {idx + 1}</span>
-                  <a
-                    href={buildImgUrl(fid)}
-                    target="_blank"
-                    rel="noreferrer"
-                    className="inline-flex items-center gap-1 text-xs text-blue-600 hover:underline whitespace-nowrap"
-                  >
-                    <FiExternalLink className="w-3 h-3" /> Open
-                  </a>
-                  <a
-                    href={buildImgUrl(fid)}
-                    download
-                    className="inline-flex items-center gap-1 text-xs text-blue-600 hover:underline whitespace-nowrap"
-                  >
-                    <FiDownload className="w-3 h-3" /> Download
-                  </a>
-                </div>
-              ))}
-            </div>
-          )}
-
-          {/* JSON/Text responses */}
-          {data !== undefined && data !== null && (
-            <div className="text-xs bg-gray-50 dark:bg-gray-800 p-3 rounded border max-h-96 overflow-y-auto font-mono whitespace-pre-wrap break-all">
-              {typeof data === "string" ? data : JSON.stringify(data, null, 2)}
-            </div>
-          )}
-
-          {/* Show placeholder if no response data yet */}
-          {!fileIds && (data === undefined || data === null) && isRunning && (
-            <div className="text-xs text-gray-500 italic">
-              Waiting for response...
-            </div>
-          )}
-        </div>
+        <FadingEdgeContainer
+          direction="bottom"
+          className="max-h-24 overflow-hidden"
+        >
+          {content}
+        </FadingEdgeContainer>
       ),
     },
   ]);
diff --git a/web/src/app/app/message/messageComponents/timeline/ExpandedTimelineContent.tsx b/web/src/app/app/message/messageComponents/timeline/ExpandedTimelineContent.tsx
index 70f6b68c923..0d71fb04fed 100644
--- a/web/src/app/app/message/messageComponents/timeline/ExpandedTimelineContent.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/ExpandedTimelineContent.tsx
@@ -17,9 +17,6 @@ import { TimelineStepComposer } from "./TimelineStepComposer";
 import {
   isSearchToolPackets,
   isPythonToolPackets,
-  isReasoningPackets,
-  isDeepResearchPlanPackets,
-  isMemoryToolPackets,
 } from "@/app/app/message/messageComponents/timeline/packetHelpers";
 
 // =============================================================================
@@ -51,24 +48,10 @@ const TimelineStep = React.memo(function TimelineStep({
     () => isSearchToolPackets(step.packets),
     [step.packets]
   );
-  const isReasoning = useMemo(
-    () => isReasoningPackets(step.packets),
-    [step.packets]
-  );
   const isPythonTool = useMemo(
     () => isPythonToolPackets(step.packets),
     [step.packets]
   );
-  const isDeepResearchPlan = useMemo(
-    () => isDeepResearchPlanPackets(step.packets),
-    [step.packets]
-  );
-
-  const isMemoryTool = useMemo(
-    () => isMemoryToolPackets(step.packets),
-    [step.packets]
-  );
-
   const getCollapsedIcon = useCallback(
     (result: TimelineRendererResult) =>
       isSearchTool ? (result.icon as FunctionComponent<IconProps>) : undefined,
@@ -83,19 +66,10 @@ const TimelineStep = React.memo(function TimelineStep({
         isFirstStep={isFirstStep}
         isSingleStep={isSingleStep}
         collapsible={true}
-        noPaddingRight={isReasoning || isDeepResearchPlan || isMemoryTool}
         getCollapsedIcon={getCollapsedIcon}
       />
     ),
-    [
-      isFirstStep,
-      isLastStep,
-      isSingleStep,
-      isReasoning,
-      isDeepResearchPlan,
-      isMemoryTool,
-      getCollapsedIcon,
-    ]
+    [isFirstStep, isLastStep, isSingleStep, getCollapsedIcon]
   );
 
   return (
diff --git a/web/src/app/app/message/messageComponents/timeline/ParallelTimelineTabs.tsx b/web/src/app/app/message/messageComponents/timeline/ParallelTimelineTabs.tsx
index bb900007a61..50dd7783d10 100644
--- a/web/src/app/app/message/messageComponents/timeline/ParallelTimelineTabs.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/ParallelTimelineTabs.tsx
@@ -14,11 +14,6 @@ import {
   TimelineRendererComponent,
   TimelineRendererOutput,
 } from "./TimelineRendererComponent";
-import {
-  isReasoningPackets,
-  isDeepResearchPlanPackets,
-  isMemoryToolPackets,
-} from "./packetHelpers";
 import Tabs from "@/refresh-components/Tabs";
 import { SvgBranch, SvgFold, SvgExpand } from "@opal/icons";
 import { Button } from "@opal/components";
@@ -65,13 +60,6 @@ export function ParallelTimelineTabs({
     [turnGroup.steps, activeTab]
   );
 
-  // Determine if the active step needs full-width content (no right padding)
-  const noPaddingRight = activeStep
-    ? isReasoningPackets(activeStep.packets) ||
-      isDeepResearchPlanPackets(activeStep.packets) ||
-      isMemoryToolPackets(activeStep.packets)
-    : false;
-
   // Memoized loading states for each step
   const loadingStates = useMemo(
     () =>
@@ -94,10 +82,9 @@ export function ParallelTimelineTabs({
         isFirstStep={false}
         isSingleStep={false}
         collapsible={true}
-        noPaddingRight={noPaddingRight}
       />
     ),
-    [isLastTurnGroup, noPaddingRight]
+    [isLastTurnGroup]
   );
 
   const hasActivePackets = Boolean(activeStep && activeStep.packets.length > 0);
diff --git a/web/src/app/app/message/messageComponents/timeline/StepContainer.tsx b/web/src/app/app/message/messageComponents/timeline/StepContainer.tsx
index ef225ccfc5b..7b93e0c039f 100644
--- a/web/src/app/app/message/messageComponents/timeline/StepContainer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/StepContainer.tsx
@@ -2,7 +2,10 @@ import React, { FunctionComponent } from "react";
 import { cn } from "@/lib/utils";
 import { IconProps } from "@opal/types";
 import { TimelineRow } from "@/app/app/message/messageComponents/timeline/primitives/TimelineRow";
-import { TimelineSurface } from "@/app/app/message/messageComponents/timeline/primitives/TimelineSurface";
+import {
+  TimelineSurface,
+  TimelineSurfaceBackground,
+} from "@/app/app/message/messageComponents/timeline/primitives/TimelineSurface";
 import { TimelineStepContent } from "@/app/app/message/messageComponents/timeline/primitives/TimelineStepContent";
 
 export interface StepContainerProps {
@@ -36,6 +39,8 @@ export interface StepContainerProps {
   noPaddingRight?: boolean;
   /** Render without rail (for nested/parallel content) */
   withRail?: boolean;
+  /** Override the surface background variant */
+  surfaceBackground?: TimelineSurfaceBackground;
 }
 
 /** Visual wrapper for timeline steps - icon, connector line, header, and content */
@@ -55,6 +60,7 @@ export function StepContainer({
   collapsedIcon: CollapsedIconComponent,
   noPaddingRight = false,
   withRail = true,
+  surfaceBackground,
 }: StepContainerProps) {
   const iconNode = StepIconComponent ? (
     <StepIconComponent
@@ -70,6 +76,7 @@ export function StepContainer({
       className="flex-1 flex flex-col"
       isHover={isHover}
       roundedBottom={isLastStep}
+      background={surfaceBackground}
     >
       <TimelineStepContent
         header={header}
@@ -81,6 +88,7 @@ export function StepContainer({
         hideHeader={hideHeader}
         collapsedIcon={CollapsedIconComponent}
         noPaddingRight={noPaddingRight}
+        surfaceBackground={surfaceBackground}
       >
         {children}
       </TimelineStepContent>
diff --git a/web/src/app/app/message/messageComponents/timeline/TimelineStepComposer.tsx b/web/src/app/app/message/messageComponents/timeline/TimelineStepComposer.tsx
index 1afe942d7d7..9ac54214b6d 100644
--- a/web/src/app/app/message/messageComponents/timeline/TimelineStepComposer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/TimelineStepComposer.tsx
@@ -17,8 +17,6 @@ export interface TimelineStepComposerProps {
   isSingleStep?: boolean;
   /** Whether StepContainer should show collapse controls. */
   collapsible?: boolean;
-  /** Remove right padding for long-form content (reasoning, deep research). */
-  noPaddingRight?: boolean;
   /** Optional resolver for custom collapsed icon per result. */
   getCollapsedIcon?: (
     result: TimelineRendererResult
@@ -35,7 +33,6 @@ export function TimelineStepComposer({
   isFirstStep,
   isSingleStep = false,
   collapsible = true,
-  noPaddingRight = false,
   getCollapsedIcon,
 }: TimelineStepComposerProps) {
   return (
@@ -64,8 +61,9 @@ export function TimelineStepComposer({
             collapsedIcon={
               getCollapsedIcon ? getCollapsedIcon(result) : undefined
             }
-            noPaddingRight={noPaddingRight}
+            noPaddingRight={result.noPaddingRight ?? false}
             isHover={result.isHover}
+            surfaceBackground={result.surfaceBackground}
           >
             {result.content}
           </StepContainer>
diff --git a/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx b/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx
index b85ff5e2ed4..20b48899262 100644
--- a/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/primitives/TimelineStepContent.tsx
@@ -1,9 +1,10 @@
 import React, { FunctionComponent } from "react";
 import { cn } from "@/lib/utils";
-import { SvgFold, SvgExpand } from "@opal/icons";
+import { SvgFold, SvgExpand, SvgXOctagon } from "@opal/icons";
 import { IconProps } from "@opal/types";
 import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
+import { TimelineSurfaceBackground } from "@/app/app/message/messageComponents/timeline/primitives/TimelineSurface";
 
 export interface TimelineStepContentProps {
   children?: React.ReactNode;
@@ -16,6 +17,7 @@ export interface TimelineStepContentProps {
   hideHeader?: boolean;
   collapsedIcon?: FunctionComponent<IconProps>;
   noPaddingRight?: boolean;
+  surfaceBackground?: TimelineSurfaceBackground;
 }
 
 /**
@@ -33,6 +35,7 @@ export function TimelineStepContent({
   hideHeader = false,
   collapsedIcon: CollapsedIconComponent,
   noPaddingRight = false,
+  surfaceBackground,
 }: TimelineStepContentProps) {
   const showCollapseControls = collapsible && supportsCollapsible && onToggle;
 
@@ -47,8 +50,8 @@ export function TimelineStepContent({
           </div>
 
           <div className="h-full w-[var(--timeline-step-header-right-section-width)] flex items-center justify-end">
-            {showCollapseControls &&
-              (buttonTitle ? (
+            {showCollapseControls ? (
+              buttonTitle ? (
                 <Button
                   prominence="tertiary"
                   size="md"
@@ -68,7 +71,12 @@ export function TimelineStepContent({
                     isExpanded ? SvgFold : CollapsedIconComponent || SvgExpand
                   }
                 />
-              ))}
+              )
+            ) : surfaceBackground === "error" ? (
+              <div className="p-1.5">
+                <SvgXOctagon className="h-4 w-4 text-status-error-05" />
+              </div>
+            ) : null}
           </div>
         </div>
       )}
diff --git a/web/src/app/app/message/messageComponents/timeline/primitives/TimelineSurface.tsx b/web/src/app/app/message/messageComponents/timeline/primitives/TimelineSurface.tsx
index 643ad53e3fc..e6a742d8f76 100644
--- a/web/src/app/app/message/messageComponents/timeline/primitives/TimelineSurface.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/primitives/TimelineSurface.tsx
@@ -1,7 +1,7 @@
 import React from "react";
 import { cn } from "@/lib/utils";
 
-export type TimelineSurfaceBackground = "tint" | "transparent";
+export type TimelineSurfaceBackground = "tint" | "transparent" | "error";
 
 export interface TimelineSurfaceProps {
   children: React.ReactNode;
@@ -28,9 +28,16 @@ export function TimelineSurface({
     return null;
   }
 
-  const baseBackground = background === "tint" ? "bg-background-tint-00" : "";
+  const baseBackground =
+    background === "tint"
+      ? "bg-background-tint-00"
+      : background === "error"
+        ? "bg-status-error-00"
+        : "";
   const hoverBackground =
-    background === "tint" && isHover ? "bg-background-tint-02" : "";
+    (background === "tint" || background === "error") && isHover
+      ? "bg-background-tint-02"
+      : "";
 
   return (
     <div
diff --git a/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/DeepResearchPlanRenderer.tsx b/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/DeepResearchPlanRenderer.tsx
index 10c35ab1031..d0e8f5d7d8e 100644
--- a/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/DeepResearchPlanRenderer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/DeepResearchPlanRenderer.tsx
@@ -69,6 +69,7 @@ export const DeepResearchPlanRenderer: MessageRenderer<
       icon: SvgCircle,
       status: statusText,
       content: planContent,
+      noPaddingRight: true,
     },
   ]);
 };
diff --git a/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/ResearchAgentRenderer.tsx b/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/ResearchAgentRenderer.tsx
index b838fefea60..41bd99dd576 100644
--- a/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/ResearchAgentRenderer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/renderers/deepresearch/ResearchAgentRenderer.tsx
@@ -27,7 +27,6 @@ import {
   useMarkdownComponents,
   renderMarkdown,
 } from "@/app/app/message/messageComponents/markdownUtils";
-import { isReasoningPackets } from "../../packetHelpers";
 
 interface NestedToolGroup {
   sub_turn_index: number;
@@ -317,8 +316,6 @@ export const ResearchAgentRenderer: MessageRenderer<
             !fullReportContent &&
             !isComplete;
 
-          const isReasoning = isReasoningPackets(group.packets);
-
           return (
             <TimelineRendererComponent
               key={group.sub_turn_index}
@@ -337,7 +334,6 @@ export const ResearchAgentRenderer: MessageRenderer<
                   isFirstStep={!researchTask && index === 0}
                   isSingleStep={false}
                   collapsible={true}
-                  noPaddingRight={isReasoning}
                 />
               )}
             </TimelineRendererComponent>
diff --git a/web/src/app/app/message/messageComponents/timeline/renderers/memory/MemoryToolRenderer.tsx b/web/src/app/app/message/messageComponents/timeline/renderers/memory/MemoryToolRenderer.tsx
index 5b0e1b83438..c8161c2444a 100644
--- a/web/src/app/app/message/messageComponents/timeline/renderers/memory/MemoryToolRenderer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/renderers/memory/MemoryToolRenderer.tsx
@@ -50,6 +50,7 @@ export const MemoryToolRenderer: MessageRenderer<MemoryToolPacket, {}> = ({
         content: <div />,
         supportsCollapsible: false,
         timelineLayout: "timeline",
+        noPaddingRight: true,
       },
     ]);
   }
@@ -87,6 +88,7 @@ export const MemoryToolRenderer: MessageRenderer<MemoryToolPacket, {}> = ({
         status: "Memory",
         supportsCollapsible: false,
         timelineLayout: "timeline",
+        noPaddingRight: true,
         content,
       },
     ]);
@@ -156,6 +158,7 @@ export const MemoryToolRenderer: MessageRenderer<MemoryToolPacket, {}> = ({
       status: statusLabel,
       supportsCollapsible: false,
       timelineLayout: "timeline",
+      noPaddingRight: true,
       content: memoryContent,
     },
   ]);
diff --git a/web/src/app/app/message/messageComponents/timeline/renderers/reasoning/ReasoningRenderer.tsx b/web/src/app/app/message/messageComponents/timeline/renderers/reasoning/ReasoningRenderer.tsx
index fda1690fc24..2e8c93f797a 100644
--- a/web/src/app/app/message/messageComponents/timeline/renderers/reasoning/ReasoningRenderer.tsx
+++ b/web/src/app/app/message/messageComponents/timeline/renderers/reasoning/ReasoningRenderer.tsx
@@ -170,7 +170,12 @@ export const ReasoningRenderer: MessageRenderer<
 
   if (!hasStart && !hasEnd && content.length === 0) {
     return children([
-      { icon: SvgCircle, status: THINKING_STATUS, content: <></> },
+      {
+        icon: SvgCircle,
+        status: THINKING_STATUS,
+        content: <></>,
+        noPaddingRight: true,
+      },
     ]);
   }
 
@@ -192,6 +197,7 @@ export const ReasoningRenderer: MessageRenderer<
       status: displayStatus,
       content: reasoningContent,
       expandedText: reasoningContent,
+      noPaddingRight: true,
     },
   ]);
 };
diff --git a/web/src/app/app/services/packetUtils.ts b/web/src/app/app/services/packetUtils.ts
index f359b3012d1..e7da46cc03f 100644
--- a/web/src/app/app/services/packetUtils.ts
+++ b/web/src/app/app/services/packetUtils.ts
@@ -18,6 +18,7 @@ export function isToolPacket(
     PacketType.PYTHON_TOOL_DELTA,
     PacketType.TOOL_CALL_ARGUMENT_DELTA,
     PacketType.CUSTOM_TOOL_START,
+    PacketType.CUSTOM_TOOL_ARGS,
     PacketType.CUSTOM_TOOL_DELTA,
     PacketType.FILE_READER_START,
     PacketType.FILE_READER_RESULT,
diff --git a/web/src/app/app/services/streamingModels.ts b/web/src/app/app/services/streamingModels.ts
index 62e023bf67b..6ca8506779d 100644
--- a/web/src/app/app/services/streamingModels.ts
+++ b/web/src/app/app/services/streamingModels.ts
@@ -32,6 +32,7 @@ export enum PacketType {
 
   // Custom tool packets
   CUSTOM_TOOL_START = "custom_tool_start",
+  CUSTOM_TOOL_ARGS = "custom_tool_args",
   CUSTOM_TOOL_DELTA = "custom_tool_delta",
 
   // File reader tool packets
@@ -178,17 +179,32 @@ export interface FetchToolDocuments extends BaseObj {
 }
 
 // Custom Tool Packets
+export interface CustomToolErrorInfo {
+  is_auth_error: boolean;
+  status_code: number;
+  message: string;
+}
+
 export interface CustomToolStart extends BaseObj {
   type: "custom_tool_start";
   tool_name: string;
+  tool_id?: number | null;
+}
+
+export interface CustomToolArgs extends BaseObj {
+  type: "custom_tool_args";
+  tool_name: string;
+  tool_args: Record<string, any>;
 }
 
 export interface CustomToolDelta extends BaseObj {
   type: "custom_tool_delta";
   tool_name: string;
+  tool_id?: number | null;
   response_type: string;
   data?: any;
   file_ids?: string[] | null;
+  error?: CustomToolErrorInfo | null;
 }
 
 // File Reader Packets
@@ -319,6 +335,7 @@ export type FetchToolObj =
   | PacketError;
 export type CustomToolObj =
   | CustomToolStart
+  | CustomToolArgs
   | CustomToolDelta
   | SectionEnd
   | PacketError;
diff --git a/web/src/components/oauth/OAuthCallbackPage.tsx b/web/src/components/oauth/OAuthCallbackPage.tsx
index e6964817d32..ed7333aa474 100644
--- a/web/src/components/oauth/OAuthCallbackPage.tsx
+++ b/web/src/components/oauth/OAuthCallbackPage.tsx
@@ -162,12 +162,19 @@ export default function OAuthCallbackPage({ config }: OAuthCallbackPageProps) {
 
         setServiceName(result.serviceName || "");
         // Respect backend-provided redirect path (from state.return_path)
-        setRedirectPath(
+        // Sanitize to prevent open redirects (e.g. "//evil.com")
+        const rawPath =
           responseData.redirect_url ||
-            searchParams?.get("return_path") ||
-            config.defaultRedirectPath ||
-            "/app"
-        );
+          searchParams?.get("return_path") ||
+          config.defaultRedirectPath ||
+          "/app";
+        const sanitizedPath =
+          rawPath.startsWith("http://") || rawPath.startsWith("https://")
+            ? "/app"
+            : "/" + rawPath.replace(/^\/+/, "");
+        const redirectUrl = new URL(sanitizedPath, window.location.origin);
+        redirectUrl.searchParams.set("message", "oauth_connected");
+        setRedirectPath(redirectUrl.pathname + redirectUrl.search);
         setStatusMessage(config.successMessage || "Success!");
 
         const successDetails = config.successDetailsTemplate
diff --git a/web/src/hooks/useToast.ts b/web/src/hooks/useToast.ts
index 8d71c1cf2c7..bd6a641dd63 100644
--- a/web/src/hooks/useToast.ts
+++ b/web/src/hooks/useToast.ts
@@ -1,6 +1,4 @@
 import { useEffect, useSyncExternalStore } from "react";
-import { useRouter } from "next/navigation";
-import type { Route } from "next";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -174,15 +172,21 @@ interface ToastFromQueryMessages {
  * and strips the param from the URL.
  */
 export function useToastFromQuery(messages: ToastFromQueryMessages) {
-  const router = useRouter();
-
   useEffect(() => {
     const searchParams = new URLSearchParams(window.location.search);
     const messageValue = searchParams?.get("message");
 
     if (messageValue && messageValue in messages) {
+      searchParams.delete("message");
+      const newSearch = searchParams.toString()
+        ? "?" + searchParams.toString()
+        : "";
+      window.history.replaceState(
+        null,
+        "",
+        window.location.pathname + newSearch
+      );
       const spec = messages[messageValue];
-      router.replace(window.location.pathname as Route);
       if (spec !== undefined) {
         toast({
           message: spec.message,
diff --git a/web/src/refresh-components/messages/Message.tsx b/web/src/refresh-components/messages/Message.tsx
index 5de07fd95fb..48b7f710274 100644
--- a/web/src/refresh-components/messages/Message.tsx
+++ b/web/src/refresh-components/messages/Message.tsx
@@ -3,8 +3,7 @@
 import React, { useMemo } from "react";
 import { cn } from "@/lib/utils";
 import Text from "@/refresh-components/texts/Text";
-import IconButton from "@/refresh-components/buttons/IconButton";
-import Button from "@/refresh-components/buttons/Button";
+import { Button } from "@opal/components";
 import {
   SvgAlertCircle,
   SvgAlertTriangle,
@@ -224,6 +223,10 @@ export interface MessageProps extends React.HTMLAttributes<HTMLDivElement> {
   actions?: boolean | string;
   close?: boolean;
 
+  // Action button customization:
+  actionIcon?: IconFunctionComponent;
+  actionPrimary?: boolean;
+
   // Callbacks:
   onClose?: () => void;
   onAction?: () => void;
@@ -251,6 +254,9 @@ function MessageInner(
     actions,
     close = true,
 
+    actionIcon,
+    actionPrimary,
+
     onClose,
     onAction,
 
@@ -337,11 +343,11 @@ function MessageInner(
       {/* Actions */}
       {actions && (
         <div className="flex items-center justify-end shrink-0 self-center pr-2">
-          {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
           <Button
-            secondary
+            prominence={actionPrimary ? "primary" : "secondary"}
+            icon={actionIcon}
             onClick={onAction}
-            className={size === "large" ? "p-2" : "p-1"}
+            size={size === "large" ? "lg" : "md"}
           >
             {typeof actions === "string" ? actions : "Cancel"}
           </Button>
@@ -352,13 +358,12 @@ function MessageInner(
       {close && (
         <div className="flex items-center justify-center shrink-0">
           <div className={cn("flex items-start", closeButtonSize)}>
-            {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
-            <IconButton
-              internal
+            <Button
+              prominence="internal"
               icon={SvgX}
               onClick={onClose}
               aria-label="Close"
-              className={size === "large" ? "p-2 rounded-12" : "p-1 rounded-08"}
+              size={size === "large" ? "lg" : "sm"}
             />
           </div>
         </div>
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 2a55a2ad9ed..8a3b8e13bb5 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -3,7 +3,7 @@
 import { redirect, useRouter, useSearchParams } from "next/navigation";
 import { personaIncludesRetrieval } from "@/app/app/services/lib";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { toast } from "@/hooks/useToast";
+import { toast, useToastFromQuery } from "@/hooks/useToast";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
 import { useFederatedConnectors, useFilters, useLlmManager } from "@/lib/hooks";
 import { useForcedTools } from "@/lib/hooks/useForcedTools";
@@ -122,6 +122,13 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
 
   const router = useRouter();
   const appFocus = useAppFocus();
+
+  useToastFromQuery({
+    oauth_connected: {
+      message: "Authentication successful",
+      type: "success",
+    },
+  });
   const { setAppMode } = useAppMode();
   const searchParams = useSearchParams();
 

From e56fa57c21a8b5d7cfa3be070e13803fee88e602 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 10 Mar 2026 09:35:30 -0700
Subject: [PATCH 209/267] chore(release): run playwright on release pushes
 (#9233)

---
 .github/workflows/pr-playwright-tests.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/pr-playwright-tests.yml b/.github/workflows/pr-playwright-tests.yml
index d09756a5e1c..86bc00a510e 100644
--- a/.github/workflows/pr-playwright-tests.yml
+++ b/.github/workflows/pr-playwright-tests.yml
@@ -12,6 +12,9 @@ on:
   push:
     tags:
       - "v*.*.*"
+    # TODO: Remove this if we enable merge-queues for release branches.
+    branches:
+      - "release/**"
 
 permissions:
   contents: read

From 19b33e4d935f2b4e60b3dfc100e8be10f72ed1c1 Mon Sep 17 00:00:00 2001
From: Jessica Singh <86633231+jessicasingh7@users.noreply.github.com>
Date: Tue, 10 Mar 2026 09:48:27 -0700
Subject: [PATCH 210/267] chore(auth): deployment docker cleanup (#8587)

---
 .vscode/env_template.txt                      |  3 +++
 backend/onyx/configs/app_configs.py           |  6 ++++++
 contributing_guides/dev_setup.md              |  4 ++--
 .../docker-compose.search-testing.yml         |  4 ++--
 deployment/docker_compose/env.template        |  6 +++++-
 deployment/docker_compose/install.sh          | 21 +++++++++++--------
 6 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/.vscode/env_template.txt b/.vscode/env_template.txt
index cd398ab3ef5..3b19a3de58e 100644
--- a/.vscode/env_template.txt
+++ b/.vscode/env_template.txt
@@ -7,6 +7,9 @@
 
 
 AUTH_TYPE=basic
+# Recommended for basic auth - used for signing password reset and verification tokens
+# Generate a secure value with: openssl rand -hex 32
+USER_AUTH_SECRET=""
 DEV_MODE=true
 
 
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index bf29587a636..da7632685cf 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -204,6 +204,12 @@
 
 USER_AUTH_SECRET = os.environ.get("USER_AUTH_SECRET", "")
 
+if AUTH_TYPE == AuthType.BASIC and not USER_AUTH_SECRET:
+    logger.warning(
+        "USER_AUTH_SECRET is not set. This is required for secure password reset "
+        "and email verification tokens. Please set USER_AUTH_SECRET in production."
+    )
+
 # Duration (in seconds) for which the FastAPI Users JWT token remains valid in the user's browser.
 # By default, this is set to match the Redis expiry time for consistency.
 AUTH_COOKIE_EXPIRE_TIME_SECONDS = int(
diff --git a/contributing_guides/dev_setup.md b/contributing_guides/dev_setup.md
index a8f0e968bc5..7dccc3f68a1 100644
--- a/contributing_guides/dev_setup.md
+++ b/contributing_guides/dev_setup.md
@@ -158,14 +158,14 @@ python ./scripts/dev_run_background_jobs.py
 To run the backend API server, navigate back to `onyx/backend` and run:
 
 ```bash
-AUTH_TYPE=disabled uvicorn onyx.main:app --reload --port 8080
+AUTH_TYPE=basic uvicorn onyx.main:app --reload --port 8080
 ```
 
 _For Windows (for compatibility with both PowerShell and Command Prompt):_
 
 ```bash
 powershell -Command "
-    $env:AUTH_TYPE='disabled'
+    $env:AUTH_TYPE='basic'
     uvicorn onyx.main:app --reload --port 8080
 "
 ```
diff --git a/deployment/docker_compose/docker-compose.search-testing.yml b/deployment/docker_compose/docker-compose.search-testing.yml
index 5bb6f90d805..a483fd88ebf 100644
--- a/deployment/docker_compose/docker-compose.search-testing.yml
+++ b/deployment/docker_compose/docker-compose.search-testing.yml
@@ -21,7 +21,7 @@ services:
     env_file:
       - .env_eval
     environment:
-      - AUTH_TYPE=disabled
+      - AUTH_TYPE=basic
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
       - REDIS_HOST=cache
@@ -58,7 +58,7 @@ services:
     env_file:
       - .env_eval
     environment:
-      - AUTH_TYPE=disabled
+      - AUTH_TYPE=basic
       - POSTGRES_HOST=relational_db
       - VESPA_HOST=index
       - REDIS_HOST=cache
diff --git a/deployment/docker_compose/env.template b/deployment/docker_compose/env.template
index 7b66925ba3d..e5c882c7a0d 100644
--- a/deployment/docker_compose/env.template
+++ b/deployment/docker_compose/env.template
@@ -20,8 +20,12 @@ IMAGE_TAG=latest
 
 ## Auth Settings
 ### https://docs.onyx.app/deployment/authentication
-AUTH_TYPE=disabled
+AUTH_TYPE=basic
 # SESSION_EXPIRE_TIME_SECONDS=
+### Recommended for basic auth - used for signing password reset and verification tokens
+### If using install.sh, this will be auto-generated
+### If setting manually, run: openssl rand -hex 32
+USER_AUTH_SECRET=""
 ### Recommend to set this for security
 # ENCRYPTION_KEY_SECRET=
 ### Optional
diff --git a/deployment/docker_compose/install.sh b/deployment/docker_compose/install.sh
index 63acef1f93c..313921ace89 100755
--- a/deployment/docker_compose/install.sh
+++ b/deployment/docker_compose/install.sh
@@ -654,17 +654,20 @@ else
     sed -i.bak "s/^IMAGE_TAG=.*/IMAGE_TAG=$VERSION/" "$ENV_FILE"
     print_success "IMAGE_TAG set to $VERSION"
 
-    # Configure authentication settings based on selection
-    if [ "$AUTH_SCHEMA" = "disabled" ]; then
-        # Disable authentication in .env file
-        sed -i.bak 's/^AUTH_TYPE=.*/AUTH_TYPE=disabled/' "$ENV_FILE" 2>/dev/null || true
-        print_success "Authentication disabled in configuration"
-    else
-        # Enable basic authentication
-        sed -i.bak 's/^AUTH_TYPE=.*/AUTH_TYPE=basic/' "$ENV_FILE" 2>/dev/null || true
-        print_success "Basic authentication enabled in configuration"
+    # Configure basic authentication (default)
+    sed -i.bak 's/^AUTH_TYPE=.*/AUTH_TYPE=basic/' "$ENV_FILE" 2>/dev/null || true
+    print_success "Basic authentication enabled in configuration"
+
+    # Check if openssl is available
+    if ! command -v openssl &> /dev/null; then
+        print_error "openssl is required to generate secure secrets but was not found."
+        exit 1
     fi
 
+    # Generate a secure USER_AUTH_SECRET
+    USER_AUTH_SECRET=$(openssl rand -hex 32)
+    sed -i.bak "s/^USER_AUTH_SECRET=.*/USER_AUTH_SECRET=\"$USER_AUTH_SECRET\"/" "$ENV_FILE" 2>/dev/null || true
+
     # Configure Craft based on flag or if using a craft-* image tag
     # By default, env.template has Craft commented out (disabled)
     if [ "$INCLUDE_CRAFT" = true ] || [[ "$VERSION" == craft-* ]]; then

From 4dbb1fa606121eb02d217c0ac6869d79261ebedd Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 10 Mar 2026 10:49:08 -0700
Subject: [PATCH 211/267] chore(tests): fix nightly model-server tests (#9236)

---
 backend/tests/daily/conftest.py | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/backend/tests/daily/conftest.py b/backend/tests/daily/conftest.py
index 3a7da882d59..8fe64edd061 100644
--- a/backend/tests/daily/conftest.py
+++ b/backend/tests/daily/conftest.py
@@ -19,7 +19,7 @@
 from onyx.auth.users import current_admin_user
 from onyx.db.engine.sql_engine import get_session
 from onyx.db.models import UserRole
-from onyx.main import fetch_versioned_implementation
+from onyx.main import get_application
 from onyx.utils.logger import setup_logger
 
 logger = setup_logger()
@@ -51,11 +51,8 @@ def client() -> Generator[TestClient, None, None]:
     # Patch out prometheus metrics setup to avoid "Duplicated timeseries in
     # CollectorRegistry" errors when multiple tests each create a new app
     # (prometheus registers metrics globally and rejects duplicate names).
-    get_app = fetch_versioned_implementation(
-        module="onyx.main", attribute="get_application"
-    )
     with patch("onyx.main.setup_prometheus_metrics"):
-        app: FastAPI = get_app(lifespan_override=test_lifespan)
+        app: FastAPI = get_application(lifespan_override=test_lifespan)
 
     # Override the database session dependency with a mock
     # (these tests don't actually need DB access)

From 1608e2f2741e07d36f0dc018c9d5cb24365b8466 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Tue, 10 Mar 2026 10:51:52 -0700
Subject: [PATCH 212/267] fix(opensearch): Allow configuring the page size of
 chunks we get from Vespa during migration (#9239)

---
 .../tasks/opensearch_migration/constants.py   |   5 +-
 backend/onyx/configs/app_configs.py           |   3 +
 .../test_opensearch_migration_tasks.py        | 184 +++++++++++++++++-
 3 files changed, 188 insertions(+), 4 deletions(-)

diff --git a/backend/onyx/background/celery/tasks/opensearch_migration/constants.py b/backend/onyx/background/celery/tasks/opensearch_migration/constants.py
index 1d4b2136a5a..b730b9a417f 100644
--- a/backend/onyx/background/celery/tasks/opensearch_migration/constants.py
+++ b/backend/onyx/background/celery/tasks/opensearch_migration/constants.py
@@ -11,6 +11,9 @@
 # lock after its cleanup which happens at most after its soft timeout.
 
 # Constants corresponding to migrate_documents_from_vespa_to_opensearch_task.
+from onyx.configs.app_configs import OPENSEARCH_MIGRATION_GET_VESPA_CHUNKS_PAGE_SIZE
+
+
 MIGRATION_TASK_SOFT_TIME_LIMIT_S = 60 * 5  # 5 minutes.
 MIGRATION_TASK_TIME_LIMIT_S = 60 * 6  # 6 minutes.
 # The maximum time the lock can be held for. Will automatically be released
@@ -44,7 +47,7 @@
 
 # WARNING: Do not change these values without knowing what changes also need to
 # be made to OpenSearchTenantMigrationRecord.
-GET_VESPA_CHUNKS_PAGE_SIZE = 500
+GET_VESPA_CHUNKS_PAGE_SIZE = OPENSEARCH_MIGRATION_GET_VESPA_CHUNKS_PAGE_SIZE
 GET_VESPA_CHUNKS_SLICE_COUNT = 4
 
 # String used to indicate in the vespa_visit_continuation_token mapping that the
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index da7632685cf..7516d7f9dd5 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -311,6 +311,9 @@
     os.environ.get("VERIFY_CREATE_OPENSEARCH_INDEX_ON_INIT_MT", "true").lower()
     == "true"
 )
+OPENSEARCH_MIGRATION_GET_VESPA_CHUNKS_PAGE_SIZE = int(
+    os.environ.get("OPENSEARCH_MIGRATION_GET_VESPA_CHUNKS_PAGE_SIZE") or 500
+)
 
 VESPA_HOST = os.environ.get("VESPA_HOST") or "localhost"
 # NOTE: this is used if and only if the vespa config server is accessible via a
diff --git a/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py b/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
index 983d3c870e9..7a55cee9fc8 100644
--- a/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
+++ b/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
@@ -17,6 +17,9 @@
 import pytest
 from sqlalchemy.orm import Session
 
+from onyx.background.celery.tasks.opensearch_migration.constants import (
+    GET_VESPA_CHUNKS_SLICE_COUNT,
+)
 from onyx.background.celery.tasks.opensearch_migration.tasks import (
     is_continuation_token_done_for_all_slices,
 )
@@ -320,9 +323,15 @@ def test_embedding_dimension(db_session: Session) -> Generator[int, None, None]:
 @pytest.fixture(scope="function")
 def patch_get_vespa_chunks_page_size() -> Generator[int, None, None]:
     test_page_size = 5
-    with patch(
-        "onyx.background.celery.tasks.opensearch_migration.tasks.GET_VESPA_CHUNKS_PAGE_SIZE",
-        test_page_size,
+    with (
+        patch(
+            "onyx.background.celery.tasks.opensearch_migration.tasks.GET_VESPA_CHUNKS_PAGE_SIZE",
+            test_page_size,
+        ),
+        patch(
+            "onyx.background.celery.tasks.opensearch_migration.constants.GET_VESPA_CHUNKS_PAGE_SIZE",
+            test_page_size,
+        ),
     ):
         yield test_page_size  # Test runs here.
 
@@ -582,6 +591,175 @@ def test_chunk_migration_resumes_from_continuation_token(
                     document_chunks[document.id][opensearch_chunk.chunk_index],
                 )
 
+    def test_chunk_migration_visits_all_chunks_even_when_batch_size_varies(
+        self,
+        db_session: Session,
+        test_documents: list[Document],
+        vespa_document_index: VespaDocumentIndex,
+        opensearch_client: OpenSearchIndexClient,
+        test_embedding_dimension: int,
+        clean_migration_tables: None,  # noqa: ARG002
+        enable_opensearch_indexing_for_onyx: None,  # noqa: ARG002
+    ) -> None:
+        """
+        Tests that chunk migration works correctly even when the batch size
+        changes halfway through a migration.
+
+        Simulates task time running out my mocking the locking behavior.
+        """
+        # Precondition.
+        # Index chunks into Vespa.
+        document_chunks: dict[str, list[dict[str, Any]]] = {
+            document.id: [
+                _create_raw_document_chunk(
+                    document_id=document.id,
+                    chunk_index=i,
+                    content=f"Test content {i} for {document.id}",
+                    embedding=_generate_test_vector(test_embedding_dimension),
+                    now=datetime.now(),
+                    title=f"Test title {document.id}",
+                    title_embedding=_generate_test_vector(test_embedding_dimension),
+                )
+                for i in range(CHUNK_COUNT)
+            ]
+            for document in test_documents
+        }
+        all_chunks: list[dict[str, Any]] = []
+        for chunks in document_chunks.values():
+            all_chunks.extend(chunks)
+        vespa_document_index.index_raw_chunks(all_chunks)
+
+        # Run the initial batch. To simulate partial progress we will mock the
+        # redis lock to return True for the first invocation of .owned() and
+        # False subsequently.
+        # NOTE: The batch size is currently set to 5 in
+        # patch_get_vespa_chunks_page_size.
+        mock_redis_client = Mock()
+        mock_lock = Mock()
+        mock_lock.owned.side_effect = [True, False, False]
+        mock_lock.acquire.return_value = True
+        mock_redis_client.lock.return_value = mock_lock
+        with patch(
+            "onyx.background.celery.tasks.opensearch_migration.tasks.get_redis_client",
+            return_value=mock_redis_client,
+        ):
+            result_1 = migrate_chunks_from_vespa_to_opensearch_task(
+                tenant_id=get_current_tenant_id()
+            )
+
+        assert result_1 is True
+        # Expire the session cache to see the committed changes from the task.
+        db_session.expire_all()
+
+        # Verify partial progress was saved.
+        tenant_record = db_session.query(OpenSearchTenantMigrationRecord).first()
+        assert tenant_record is not None
+        partial_chunks_migrated = tenant_record.total_chunks_migrated
+        assert partial_chunks_migrated > 0
+        # page_size applies per slice, so one iteration can fetch up to
+        # page_size * GET_VESPA_CHUNKS_SLICE_COUNT chunks total.
+        assert partial_chunks_migrated <= 5 * GET_VESPA_CHUNKS_SLICE_COUNT
+        assert tenant_record.vespa_visit_continuation_token is not None
+        # Slices are not necessarily evenly distributed across all document
+        # chunks so we can't test that every token is non-None, but certainly at
+        # least one must be.
+        assert any(json.loads(tenant_record.vespa_visit_continuation_token).values())
+        assert tenant_record.migration_completed_at is None
+        assert tenant_record.approx_chunk_count_in_vespa is not None
+
+        # Under test.
+        # Now patch the batch size to be some other number, like 2.
+        mock_redis_client = Mock()
+        mock_lock = Mock()
+        mock_lock.owned.side_effect = [True, False, False]
+        mock_lock.acquire.return_value = True
+        mock_redis_client.lock.return_value = mock_lock
+        with (
+            patch(
+                "onyx.background.celery.tasks.opensearch_migration.tasks.GET_VESPA_CHUNKS_PAGE_SIZE",
+                2,
+            ),
+            patch(
+                "onyx.background.celery.tasks.opensearch_migration.constants.GET_VESPA_CHUNKS_PAGE_SIZE",
+                2,
+            ),
+            patch(
+                "onyx.background.celery.tasks.opensearch_migration.tasks.get_redis_client",
+                return_value=mock_redis_client,
+            ),
+        ):
+            result_2 = migrate_chunks_from_vespa_to_opensearch_task(
+                tenant_id=get_current_tenant_id()
+            )
+
+        # Postcondition.
+        assert result_2 is True
+        # Expire the session cache to see the committed changes from the task.
+        db_session.expire_all()
+
+        # Verify next partial progress was saved.
+        tenant_record = db_session.query(OpenSearchTenantMigrationRecord).first()
+        assert tenant_record is not None
+        new_partial_chunks_migrated = tenant_record.total_chunks_migrated
+        assert new_partial_chunks_migrated > partial_chunks_migrated
+        # page_size applies per slice, so one iteration can fetch up to
+        # page_size * GET_VESPA_CHUNKS_SLICE_COUNT chunks total.
+        assert new_partial_chunks_migrated <= (5 + 2) * GET_VESPA_CHUNKS_SLICE_COUNT
+        assert tenant_record.vespa_visit_continuation_token is not None
+        # Slices are not necessarily evenly distributed across all document
+        # chunks so we can't test that every token is non-None, but certainly at
+        # least one must be.
+        assert any(json.loads(tenant_record.vespa_visit_continuation_token).values())
+        assert tenant_record.migration_completed_at is None
+        assert tenant_record.approx_chunk_count_in_vespa is not None
+
+        # Under test.
+        # Run the remainder of the migration.
+        with (
+            patch(
+                "onyx.background.celery.tasks.opensearch_migration.tasks.GET_VESPA_CHUNKS_PAGE_SIZE",
+                2,
+            ),
+            patch(
+                "onyx.background.celery.tasks.opensearch_migration.constants.GET_VESPA_CHUNKS_PAGE_SIZE",
+                2,
+            ),
+        ):
+            result_3 = migrate_chunks_from_vespa_to_opensearch_task(
+                tenant_id=get_current_tenant_id()
+            )
+
+        # Postcondition.
+        assert result_3 is True
+        # Expire the session cache to see the committed changes from the task.
+        db_session.expire_all()
+
+        # Verify completion.
+        tenant_record = db_session.query(OpenSearchTenantMigrationRecord).first()
+        assert tenant_record is not None
+        assert tenant_record.total_chunks_migrated > new_partial_chunks_migrated
+        assert tenant_record.total_chunks_migrated == len(all_chunks)
+        # Visit is complete so continuation token should be None.
+        assert tenant_record.vespa_visit_continuation_token is not None
+        assert is_continuation_token_done_for_all_slices(
+            json.loads(tenant_record.vespa_visit_continuation_token)
+        )
+        assert tenant_record.migration_completed_at is not None
+        assert tenant_record.approx_chunk_count_in_vespa == len(all_chunks)
+
+        # Verify chunks were indexed in OpenSearch.
+        for document in test_documents:
+            opensearch_chunks = _get_document_chunks_from_opensearch(
+                opensearch_client, document.id, get_current_tenant_id()
+            )
+            assert len(opensearch_chunks) == CHUNK_COUNT
+            opensearch_chunks.sort(key=lambda x: x.chunk_index)
+            for opensearch_chunk in opensearch_chunks:
+                _assert_chunk_matches_vespa_chunk(
+                    opensearch_chunk,
+                    document_chunks[document.id][opensearch_chunk.chunk_index],
+                )
+
     def test_chunk_migration_empty_vespa(
         self,
         db_session: Session,

From fbe823b5517a206d2c674c7cf3a20e72a8f1cbce Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Tue, 10 Mar 2026 12:27:36 -0700
Subject: [PATCH 213/267] chore(opensearch): Allow configuring num hits from
 hybrid subquery from env var (#9243)

---
 backend/onyx/configs/app_configs.py           |  3 ++
 .../document_index/opensearch/constants.py    | 51 +++++++++++++------
 .../onyx/document_index/opensearch/search.py  | 47 ++++++++++-------
 3 files changed, 68 insertions(+), 33 deletions(-)

diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 7516d7f9dd5..93d5a7997b1 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -314,6 +314,9 @@
 OPENSEARCH_MIGRATION_GET_VESPA_CHUNKS_PAGE_SIZE = int(
     os.environ.get("OPENSEARCH_MIGRATION_GET_VESPA_CHUNKS_PAGE_SIZE") or 500
 )
+OPENSEARCH_OVERRIDE_DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES = int(
+    os.environ.get("OPENSEARCH_DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES") or 0
+)
 
 VESPA_HOST = os.environ.get("VESPA_HOST") or "localhost"
 # NOTE: this is used if and only if the vespa config server is accessible via a
diff --git a/backend/onyx/document_index/opensearch/constants.py b/backend/onyx/document_index/opensearch/constants.py
index 61257190a03..1447570e056 100644
--- a/backend/onyx/document_index/opensearch/constants.py
+++ b/backend/onyx/document_index/opensearch/constants.py
@@ -1,5 +1,10 @@
 # Default value for the maximum number of tokens a chunk can hold, if none is
 # specified when creating an index.
+from onyx.configs.app_configs import (
+    OPENSEARCH_OVERRIDE_DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES,
+)
+
+
 DEFAULT_MAX_CHUNK_SIZE = 512
 
 # Size of the dynamic list used to consider elements during kNN graph creation.
@@ -10,27 +15,43 @@
 # quality but increase memory footprint. Values typically range between 12 - 48.
 M = 32  # Set relatively high for better accuracy.
 
-# When performing hybrid search, we need to consider more candidates than the number of results to be returned.
-# This is because the scoring is hybrid and the results are reordered due to the hybrid scoring.
-# Higher = more candidates for hybrid fusion = better retrieval accuracy, but results in more computation per query.
-# Imagine a simple case with a single keyword query and a single vector query and we want 10 final docs.
-# If we only fetch 10 candidates from each of keyword and vector, they would have to have perfect overlap to get a good hybrid
-# ranking for the 10 results. If we fetch 1000 candidates from each, we have a much higher chance of all 10 of the final desired
-# docs showing up and getting scored. In worse situations, the final 10 docs don't even show up as the final 10 (worse than just
-# a miss at the reranking step).
-DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES = 750
-
-# Number of vectors to examine for top k neighbors for the HNSW method.
+# When performing hybrid search, we need to consider more candidates than the
+# number of results to be returned. This is because the scoring is hybrid and
+# the results are reordered due to the hybrid scoring. Higher = more candidates
+# for hybrid fusion = better retrieval accuracy, but results in more computation
+# per query. Imagine a simple case with a single keyword query and a single
+# vector query and we want 10 final docs. If we only fetch 10 candidates from
+# each of keyword and vector, they would have to have perfect overlap to get a
+# good hybrid ranking for the 10 results. If we fetch 1000 candidates from each,
+# we have a much higher chance of all 10 of the final desired docs showing up
+# and getting scored. In worse situations, the final 10 docs don't even show up
+# as the final 10 (worse than just a miss at the reranking step).
+DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES = (
+    OPENSEARCH_OVERRIDE_DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES
+    if OPENSEARCH_OVERRIDE_DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES > 0
+    else 750
+)
+
+# Number of vectors to examine to decide the top k neighbors for the HNSW
+# method.
+# NOTE: "When creating a search query, you must specify k. If you provide both k
+# and ef_search, then the larger value is passed to the engine. If ef_search is
+# larger than k, you can provide the size parameter to limit the final number of
+# results to k." from
+# https://docs.opensearch.org/latest/query-dsl/specialized/k-nn/index/#ef_search
 EF_SEARCH = DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES
 
-# Since the titles are included in the contents, they are heavily downweighted as they act as a boost
-# rather than an independent scoring component.
+# Since the titles are included in the contents, the embedding matches are
+# heavily downweighted as they act as a boost rather than an independent scoring
+# component.
 SEARCH_TITLE_VECTOR_WEIGHT = 0.1
 SEARCH_CONTENT_VECTOR_WEIGHT = 0.45
-# Single keyword weight for both title and content (merged from former title keyword + content keyword).
+# Single keyword weight for both title and content (merged from former title
+# keyword + content keyword).
 SEARCH_KEYWORD_WEIGHT = 0.45
 
-# NOTE: it is critical that the order of these weights matches the order of the sub-queries in the hybrid search.
+# NOTE: It is critical that the order of these weights matches the order of the
+# sub-queries in the hybrid search.
 HYBRID_SEARCH_NORMALIZATION_WEIGHTS = [
     SEARCH_TITLE_VECTOR_WEIGHT,
     SEARCH_CONTENT_VECTOR_WEIGHT,
diff --git a/backend/onyx/document_index/opensearch/search.py b/backend/onyx/document_index/opensearch/search.py
index 3a699069194..1c1033e60fc 100644
--- a/backend/onyx/document_index/opensearch/search.py
+++ b/backend/onyx/document_index/opensearch/search.py
@@ -285,13 +285,16 @@ def get_hybrid_search_query(
         hybrid_search_query: dict[str, Any] = {
             "hybrid": {
                 "queries": hybrid_search_subqueries,
-                # Max results per subquery per shard before aggregation. Ensures keyword and vector
-                # subqueries contribute equally to the candidate pool for hybrid fusion.
+                # Max results per subquery per shard before aggregation. Ensures
+                # keyword and vector subqueries contribute equally to the
+                # candidate pool for hybrid fusion.
                 # Sources:
                 # https://docs.opensearch.org/latest/vector-search/ai-search/hybrid-search/pagination/
                 # https://opensearch.org/blog/navigating-pagination-in-hybrid-queries-with-the-pagination_depth-parameter/
                 "pagination_depth": DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES,
-                # Applied to all the sub-queries independently (this avoids having subqueries having a lot of results thrown out).
+                # Applied to all the sub-queries independently (this avoids
+                # subqueries having a lot of results thrown out during
+                # aggregation).
                 # Sources:
                 # https://docs.opensearch.org/latest/query-dsl/compound/hybrid/
                 # https://opensearch.org/blog/introducing-common-filter-support-for-hybrid-search-queries
@@ -374,9 +377,10 @@ def get_random_search_query(
     def _get_hybrid_search_subqueries(
         query_text: str,
         query_vector: list[float],
-        # The default number of neighbors to consider for knn vector similarity search.
-        # This is higher than the number of results because the scoring is hybrid.
-        # for a detailed breakdown, see where the default value is set.
+        # The default number of neighbors to consider for knn vector similarity
+        # search. This is higher than the number of results because the scoring
+        # is hybrid. For a detailed breakdown, see where the default value is
+        # set.
         vector_candidates: int = DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES,
     ) -> list[dict[str, Any]]:
         """Returns subqueries for hybrid search.
@@ -400,20 +404,27 @@ def _get_hybrid_search_subqueries(
         in a single hybrid query. Source:
         https://docs.opensearch.org/latest/query-dsl/compound/hybrid/
 
-        NOTE: Each query is independent during the search phase, there is no backfilling of scores for missing query components.
-        What this means is that if a document was a good vector match but did not show up for keyword, it gets a score of 0 for
-        the keyword component of the hybrid scoring. This is not as bad as just disregarding a score though as there is
-        normalization applied after. So really it is "increasing" the missing score compared to if it was included and the range
-        was renormalized. This does however mean that between docs that have high scores for say the vector field, the keyword
-        scores between them are completely ignored unless they also showed up in the keyword query as a reasonably high match.
-        TLDR, this is a bit of unique funky behavior but it seems ok.
+        NOTE: Each query is independent during the search phase, there is no
+        backfilling of scores for missing query components. What this means is
+        that if a document was a good vector match but did not show up for
+        keyword, it gets a score of 0 for the keyword component of the hybrid
+        scoring. This is not as bad as just disregarding a score though as there
+        is normalization applied after. So really it is "increasing" the missing
+        score compared to if it was included and the range was renormalized.
+        This does however mean that between docs that have high scores for say
+        the vector field, the keyword scores between them are completely ignored
+        unless they also showed up in the keyword query as a reasonably high
+        match. TLDR, this is a bit of unique funky behavior but it seems ok.
 
         NOTE: Options considered and rejected:
-        - minimum_should_match: Since it's hybrid search and users often provide semantic queries, there is often a lot of terms,
-          and very low number of meaningful keywords (and a low ratio of keywords).
-        - fuzziness AUTO: typo tolerance (0/1/2 edit distance by term length). It's mostly for typos as the analyzer ("english by
-          default") already does some stemming and tokenization. In testing datasets, this makes recall slightly worse. It also is
-          less performant so not really any reason to do it.
+        - minimum_should_match: Since it's hybrid search and users often provide
+          semantic queries, there is often a lot of terms, and very low number
+          of meaningful keywords (and a low ratio of keywords).
+        - fuzziness AUTO: Typo tolerance (0/1/2 edit distance by term length).
+          It's mostly for typos as the analyzer ("english" by default) already
+          does some stemming and tokenization. In testing datasets, this makes
+          recall slightly worse. It also is less performant so not really any
+          reason to do it.
 
         Args:
             query_text: The text of the query to search for.

From 9d1a357533a3676e6cd99b38ad6ed02e1b4404de Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 10 Mar 2026 12:42:23 -0700
Subject: [PATCH 214/267] fix(fe): make CSV inline display responsive (#9242)

---
 web/src/app/app/message/FileDisplay.tsx       | 68 +++++++++++--------
 .../tools/ExpandableContentWrapper.tsx        | 17 ++---
 2 files changed, 46 insertions(+), 39 deletions(-)

diff --git a/web/src/app/app/message/FileDisplay.tsx b/web/src/app/app/message/FileDisplay.tsx
index 0fa6b8939af..7f619f06b3a 100644
--- a/web/src/app/app/message/FileDisplay.tsx
+++ b/web/src/app/app/message/FileDisplay.tsx
@@ -1,6 +1,7 @@
 "use client";
 
-import { useState } from "react";
+import { ReactNode, useState } from "react";
+import { cn } from "@/lib/utils";
 import { ChatFileType, FileDescriptor } from "@/app/app/interfaces";
 import Attachment from "@/refresh-components/Attachment";
 import { InMessageImage } from "@/app/app/components/files/images/InMessageImage";
@@ -9,10 +10,27 @@ import PreviewModal from "@/sections/modals/PreviewModal";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import ExpandableContentWrapper from "@/components/tools/ExpandableContentWrapper";
 
+interface FileContainerProps {
+  children: ReactNode;
+  className?: string;
+  id?: string;
+}
+
 interface FileDisplayProps {
   files: FileDescriptor[];
 }
 
+function FileContainer({ children, className, id }: FileContainerProps) {
+  return (
+    <div
+      id={id}
+      className={cn("flex w-full flex-col items-end gap-2 py-2", className)}
+    >
+      {children}
+    </div>
+  );
+}
+
 export default function FileDisplay({ files }: FileDisplayProps) {
   const [close, setClose] = useState(true);
   const [previewingFile, setPreviewingFile] = useState<FileDescriptor | null>(
@@ -41,7 +59,7 @@ export default function FileDisplay({ files }: FileDisplayProps) {
       )}
 
       {textFiles.length > 0 && (
-        <div id="onyx-file" className="flex flex-col items-end gap-2 py-2">
+        <FileContainer id="onyx-file">
           {textFiles.map((file) => (
             <Attachment
               key={file.id}
@@ -49,40 +67,36 @@ export default function FileDisplay({ files }: FileDisplayProps) {
               open={() => setPreviewingFile(file)}
             />
           ))}
-        </div>
+        </FileContainer>
       )}
 
       {imageFiles.length > 0 && (
-        <div id="onyx-image" className="flex flex-col items-end gap-2 py-2">
+        <FileContainer id="onyx-image">
           {imageFiles.map((file) => (
             <InMessageImage key={file.id} fileId={file.id} />
           ))}
-        </div>
+        </FileContainer>
       )}
 
       {csvFiles.length > 0 && (
-        <div className="flex flex-col items-end gap-2 py-2">
-          {csvFiles.map((file) => {
-            return (
-              <div key={file.id} className="w-fit">
-                {close ? (
-                  <>
-                    <ExpandableContentWrapper
-                      fileDescriptor={file}
-                      close={() => setClose(false)}
-                      ContentComponent={CsvContent}
-                    />
-                  </>
-                ) : (
-                  <Attachment
-                    open={() => setClose(true)}
-                    fileName={file.name || file.id}
-                  />
-                )}
-              </div>
-            );
-          })}
-        </div>
+        <FileContainer className="overflow-auto">
+          {csvFiles.map((file) =>
+            close ? (
+              <ExpandableContentWrapper
+                key={file.id}
+                fileDescriptor={file}
+                close={() => setClose(false)}
+                ContentComponent={CsvContent}
+              />
+            ) : (
+              <Attachment
+                key={file.id}
+                open={() => setClose(true)}
+                fileName={file.name || file.id}
+              />
+            )
+          )}
+        </FileContainer>
       )}
     </>
   );
diff --git a/web/src/components/tools/ExpandableContentWrapper.tsx b/web/src/components/tools/ExpandableContentWrapper.tsx
index 270e66aea52..addf8173f22 100644
--- a/web/src/components/tools/ExpandableContentWrapper.tsx
+++ b/web/src/components/tools/ExpandableContentWrapper.tsx
@@ -40,12 +40,7 @@ export default function ExpandableContentWrapper({
   };
 
   const Content = (
-    <div
-      className={cn(
-        !expanded ? "w-message-default" : "w-full",
-        "!rounded !rounded-lg overflow-y-hidden h-full"
-      )}
-    >
+    <div className="w-message-default max-w-full !rounded-lg overflow-y-hidden h-full">
       <CardHeader className="w-full bg-background-tint-02 top-0 p-3">
         <div className="flex justify-between items-center">
           <Text className="text-ellipsis line-clamp-1" text03 mainUiAction>
@@ -83,12 +78,10 @@ export default function ExpandableContentWrapper({
         )}
       >
         <CardContent className="p-0">
-          {!expanded && (
-            <ContentComponent
-              fileDescriptor={fileDescriptor}
-              expanded={expanded}
-            />
-          )}
+          <ContentComponent
+            fileDescriptor={fileDescriptor}
+            expanded={expanded}
+          />
         </CardContent>
       </Card>
     </div>

From ec7482619bdc3f75453f9d819f1da1041b6d19a5 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Tue, 10 Mar 2026 12:57:01 -0700
Subject: [PATCH 215/267] fix: update jira group sync endpoint (#9241)

---
 .../external_permissions/jira/group_sync.py   | 187 +++++++++---------
 1 file changed, 99 insertions(+), 88 deletions(-)

diff --git a/backend/ee/onyx/external_permissions/jira/group_sync.py b/backend/ee/onyx/external_permissions/jira/group_sync.py
index cb9ca677a95..e8ecedffb76 100644
--- a/backend/ee/onyx/external_permissions/jira/group_sync.py
+++ b/backend/ee/onyx/external_permissions/jira/group_sync.py
@@ -1,6 +1,8 @@
 from collections.abc import Generator
+from typing import Any
 
 from jira import JIRA
+from jira.exceptions import JIRAError
 
 from ee.onyx.db.external_perm import ExternalUserGroup
 from onyx.connectors.jira.utils import build_jira_client
@@ -9,107 +11,102 @@
 
 logger = setup_logger()
 
+_ATLASSIAN_ACCOUNT_TYPE = "atlassian"
+_GROUP_MEMBER_PAGE_SIZE = 50
 
-def _get_jira_group_members_email(
+# The GET /group/member endpoint was introduced in Jira 6.0.
+# Jira versions older than 6.0 do not have group management REST APIs at all.
+_MIN_JIRA_VERSION_FOR_GROUP_MEMBER = "6.0"
+
+
+def _fetch_group_member_page(
     jira_client: JIRA,
     group_name: str,
-) -> list[str]:
-    """Get all member emails for a Jira group.
-
-    Filters out app accounts (bots, integrations) and only returns real user emails.
+    start_at: int,
+) -> dict[str, Any]:
+    """Fetch a single page from the non-deprecated GET /group/member endpoint.
+
+    The old GET /group endpoint (used by jira_client.group_members()) is deprecated
+    and decommissioned in Jira Server 10.3+. This uses the replacement endpoint
+    directly via the library's internal _get_json helper, following the same pattern
+    as enhanced_search_ids / bulk_fetch_issues in connector.py.
+
+    There is an open PR to the library to switch to this endpoint since last year:
+    https://github.com/pycontribs/jira/pull/2356
+    so once it is merged and released, we can switch to using the library function.
     """
-    emails: list[str] = []
-
     try:
-        # group_members returns an OrderedDict of account_id -> member_info
-        members = jira_client.group_members(group=group_name)
-
-        if not members:
-            logger.warning(f"No members found for group {group_name}")
-            return emails
-
-        for account_id, member_info in members.items():
-            # member_info is a dict with keys like 'fullname', 'email', 'active'
-            email = member_info.get("email")
-
-            # Skip "hidden" emails - these are typically app accounts
-            if email and email != "hidden":
-                emails.append(email)
-            else:
-                # For cloud, we might need to fetch user details separately
-                try:
-                    user = jira_client.user(id=account_id)
-
-                    # Skip app accounts (bots, integrations, etc.)
-                    if hasattr(user, "accountType") and user.accountType == "app":
-                        logger.info(
-                            f"Skipping app account {account_id} for group {group_name}"
-                        )
-                        continue
-
-                    if hasattr(user, "emailAddress") and user.emailAddress:
-                        emails.append(user.emailAddress)
-                    else:
-                        logger.warning(f"User {account_id} has no email address")
-                except Exception as e:
-                    logger.warning(
-                        f"Could not fetch email for user {account_id} in group {group_name}: {e}"
-                    )
-
-    except Exception as e:
-        logger.error(f"Error fetching members for group {group_name}: {e}")
-
-    return emails
-
-
-def _build_group_member_email_map(
+        return jira_client._get_json(
+            "group/member",
+            params={
+                "groupname": group_name,
+                "includeInactiveUsers": "false",
+                "startAt": start_at,
+                "maxResults": _GROUP_MEMBER_PAGE_SIZE,
+            },
+        )
+    except JIRAError as e:
+        if e.status_code == 404:
+            raise RuntimeError(
+                f"GET /group/member returned 404 for group '{group_name}'. "
+                f"This endpoint requires Jira {_MIN_JIRA_VERSION_FOR_GROUP_MEMBER}+. "
+                f"If you are running a self-hosted Jira instance, please upgrade "
+                f"to at least Jira {_MIN_JIRA_VERSION_FOR_GROUP_MEMBER}."
+            ) from e
+        raise
+
+
+def _get_group_member_emails(
     jira_client: JIRA,
-) -> dict[str, set[str]]:
-    """Build a map of group names to member emails."""
-    group_member_emails: dict[str, set[str]] = {}
-
-    try:
-        # Get all groups from Jira - returns a list of group name strings
-        group_names = jira_client.groups()
-
-        if not group_names:
-            logger.warning("No groups found in Jira")
-            return group_member_emails
-
-        logger.info(f"Found {len(group_names)} groups in Jira")
+    group_name: str,
+) -> set[str]:
+    """Get all member emails for a single Jira group.
 
-        for group_name in group_names:
-            if not group_name:
+    Uses the non-deprecated GET /group/member endpoint which returns full user
+    objects including accountType, so we can filter out app/customer accounts
+    without making separate user() calls.
+    """
+    emails: set[str] = set()
+    start_at = 0
+
+    while True:
+        try:
+            page = _fetch_group_member_page(jira_client, group_name, start_at)
+        except Exception as e:
+            logger.error(f"Error fetching members for group {group_name}: {e}")
+            raise
+
+        members: list[dict[str, Any]] = page.get("values", [])
+        for member in members:
+            account_type = member.get("accountType")
+            # On Jira DC < 9.0, accountType is absent; include those users.
+            # On Cloud / DC 9.0+, filter to real user accounts only.
+            if account_type is not None and account_type != _ATLASSIAN_ACCOUNT_TYPE:
                 continue
 
-            member_emails = _get_jira_group_members_email(
-                jira_client=jira_client,
-                group_name=group_name,
-            )
-
-            if member_emails:
-                group_member_emails[group_name] = set(member_emails)
-                logger.debug(
-                    f"Found {len(member_emails)} members for group {group_name}"
-                )
+            email = member.get("emailAddress")
+            if email:
+                emails.add(email)
             else:
-                logger.debug(f"No members found for group {group_name}")
+                logger.warning(
+                    f"Atlassian user {member.get('accountId', 'unknown')} "
+                    f"in group {group_name} has no visible email address"
+                )
 
-    except Exception as e:
-        logger.error(f"Error building group member email map: {e}")
+        if page.get("isLast", True) or not members:
+            break
+        start_at += len(members)
 
-    return group_member_emails
+    return emails
 
 
 def jira_group_sync(
     tenant_id: str,  # noqa: ARG001
     cc_pair: ConnectorCredentialPair,
 ) -> Generator[ExternalUserGroup, None, None]:
-    """
-    Sync Jira groups and their members.
+    """Sync Jira groups and their members, yielding one group at a time.
 
-    This function fetches all groups from Jira and yields ExternalUserGroup
-    objects containing the group ID and member emails.
+    Streams group-by-group rather than accumulating all groups in memory.
     """
     jira_base_url = cc_pair.connector.connector_specific_config.get("jira_base_url", "")
     scoped_token = cc_pair.connector.connector_specific_config.get(
@@ -130,12 +127,26 @@ def jira_group_sync(
         scoped_token=scoped_token,
     )
 
-    group_member_email_map = _build_group_member_email_map(jira_client=jira_client)
-    if not group_member_email_map:
-        raise ValueError(f"No groups with members found for cc_pair_id={cc_pair.id}")
+    group_names = jira_client.groups()
+    if not group_names:
+        raise ValueError(f"No groups found for cc_pair_id={cc_pair.id}")
+
+    logger.info(f"Found {len(group_names)} groups in Jira")
+
+    for group_name in group_names:
+        if not group_name:
+            continue
+
+        member_emails = _get_group_member_emails(
+            jira_client=jira_client,
+            group_name=group_name,
+        )
+        if not member_emails:
+            logger.debug(f"No members found for group {group_name}")
+            continue
 
-    for group_id, group_member_emails in group_member_email_map.items():
+        logger.debug(f"Found {len(member_emails)} members for group {group_name}")
         yield ExternalUserGroup(
-            id=group_id,
-            user_emails=list(group_member_emails),
+            id=group_name,
+            user_emails=list(member_emails),
         )

From fd200d46f80de36eb93aaef3782e94b3e8656305 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Tue, 10 Mar 2026 13:05:32 -0700
Subject: [PATCH 216/267] fix(storybook): case-sensitivity, icon rename, and
 story fixes (#9244)

---
 .github/workflows/storybook-deploy.yml        |   2 +-
 .../core/interactive/Interactive.stories.tsx  | 177 ++++++++++--------
 .../src/icons/{import.tsx => import-icon.tsx} |   0
 web/lib/opal/src/icons/index.ts               |   2 +-
 .../ContentAction.stories.tsx                 |   0
 .../BodyLayout.stories.tsx                    |   0
 .../{Content => content}/Content.stories.tsx  |   0
 .../HeadingLayout.stories.tsx                 |   0
 .../LabelLayout.stories.tsx                   |   0
 .../IllustrationContent.stories.tsx           |   0
 .../buttons/ButtonRenaming.stories.tsx        |  26 +--
 11 files changed, 109 insertions(+), 98 deletions(-)
 rename web/lib/opal/src/icons/{import.tsx => import-icon.tsx} (100%)
 rename web/lib/opal/src/layouts/{ContentAction => content-action}/ContentAction.stories.tsx (100%)
 rename web/lib/opal/src/layouts/{Content => content}/BodyLayout.stories.tsx (100%)
 rename web/lib/opal/src/layouts/{Content => content}/Content.stories.tsx (100%)
 rename web/lib/opal/src/layouts/{Content => content}/HeadingLayout.stories.tsx (100%)
 rename web/lib/opal/src/layouts/{Content => content}/LabelLayout.stories.tsx (100%)
 rename web/lib/opal/src/layouts/{IllustrationContent => illustration-content}/IllustrationContent.stories.tsx (100%)

diff --git a/.github/workflows/storybook-deploy.yml b/.github/workflows/storybook-deploy.yml
index c1f65126ad8..7195c031faf 100644
--- a/.github/workflows/storybook-deploy.yml
+++ b/.github/workflows/storybook-deploy.yml
@@ -48,7 +48,7 @@ jobs:
 
       - name: Deploy to Vercel (Production)
         working-directory: web
-        run: npx --yes "$VERCEL_CLI" deploy storybook-static/ --prod --yes
+        run: npx --yes "$VERCEL_CLI" deploy storybook-static/ --prod --yes --token="$VERCEL_TOKEN"
 
   notify-slack-on-failure:
     needs: Deploy-Storybook
diff --git a/web/lib/opal/src/core/interactive/Interactive.stories.tsx b/web/lib/opal/src/core/interactive/Interactive.stories.tsx
index 1cf6180e6fe..26f1e4fadea 100644
--- a/web/lib/opal/src/core/interactive/Interactive.stories.tsx
+++ b/web/lib/opal/src/core/interactive/Interactive.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Interactive } from "@opal/core";
+import { Interactive, Disabled } from "@opal/core";
 
 // ---------------------------------------------------------------------------
 // Variant / Prominence mappings for the matrix story
@@ -9,8 +9,6 @@ const VARIANT_PROMINENCE_MAP: Record<string, string[]> = {
   default: ["primary", "secondary", "tertiary", "internal"],
   action: ["primary", "secondary", "tertiary", "internal"],
   danger: ["primary", "secondary", "tertiary", "internal"],
-  select: ["light", "heavy"],
-  sidebar: ["light"],
   none: [],
 };
 
@@ -35,39 +33,39 @@ export default meta;
 // Stories
 // ---------------------------------------------------------------------------
 
-/** Basic Interactive.Base + Container with text content. */
+/** Basic Interactive.Stateless + Container with text content. */
 export const Default: StoryObj = {
   render: () => (
     <div style={{ display: "flex", gap: "0.75rem", alignItems: "center" }}>
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Secondary</span>
+          <span className="interactive-foreground">Secondary</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
 
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="primary"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Primary</span>
+          <span className="interactive-foreground">Primary</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
 
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="tertiary"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Tertiary</span>
+          <span className="interactive-foreground">Tertiary</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
     </div>
   ),
 };
@@ -91,11 +89,13 @@ export const VariantMatrix: StoryObj = {
           </div>
 
           {prominences.length === 0 ? (
-            <Interactive.Base variant="none" onClick={() => {}}>
+            <Interactive.Stateless variant="none" onClick={() => {}}>
               <Interactive.Container border>
-                <span>none (no prominence)</span>
+                <span style={{ color: "var(--text-01)" }}>
+                  none (no prominence)
+                </span>
               </Interactive.Container>
-            </Interactive.Base>
+            </Interactive.Stateless>
           ) : (
             <div style={{ display: "flex", gap: "0.5rem", flexWrap: "wrap" }}>
               {prominences.map((prominence) => (
@@ -108,16 +108,18 @@ export const VariantMatrix: StoryObj = {
                     gap: "0.25rem",
                   }}
                 >
-                  <Interactive.Base
+                  <Interactive.Stateless
                     // Cast required because the discriminated union can't be
                     // resolved from dynamic strings at the type level.
                     {...({ variant, prominence } as any)}
                     onClick={() => {}}
                   >
                     <Interactive.Container border>
-                      <span>{prominence}</span>
+                      <span className="interactive-foreground">
+                        {prominence}
+                      </span>
                     </Interactive.Container>
-                  </Interactive.Base>
+                  </Interactive.Stateless>
                   <span
                     style={{
                       fontSize: "0.625rem",
@@ -141,16 +143,16 @@ export const Sizes: StoryObj = {
   render: () => (
     <div style={{ display: "flex", alignItems: "center", gap: "0.75rem" }}>
       {SIZE_VARIANTS.map((size) => (
-        <Interactive.Base
+        <Interactive.Stateless
           key={size}
           variant="default"
           prominence="secondary"
           onClick={() => {}}
         >
           <Interactive.Container border heightVariant={size}>
-            <span>{size}</span>
+            <span className="interactive-foreground">{size}</span>
           </Interactive.Container>
-        </Interactive.Base>
+        </Interactive.Stateless>
       ))}
     </div>
   ),
@@ -160,15 +162,15 @@ export const Sizes: StoryObj = {
 export const WidthFull: StoryObj = {
   render: () => (
     <div style={{ width: 400 }}>
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
         onClick={() => {}}
       >
         <Interactive.Container border widthVariant="full">
-          <span>Full width container</span>
+          <span className="interactive-foreground">Full width container</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
     </div>
   ),
 };
@@ -178,73 +180,86 @@ export const Rounding: StoryObj = {
   render: () => (
     <div style={{ display: "flex", gap: "0.75rem" }}>
       {ROUNDING_VARIANTS.map((rounding) => (
-        <Interactive.Base
+        <Interactive.Stateless
           key={rounding}
           variant="default"
           prominence="secondary"
           onClick={() => {}}
         >
           <Interactive.Container border roundingVariant={rounding}>
-            <span>{rounding}</span>
+            <span className="interactive-foreground">{rounding}</span>
           </Interactive.Container>
-        </Interactive.Base>
+        </Interactive.Stateless>
       ))}
     </div>
   ),
 };
 
 /** Disabled state prevents clicks and shows disabled styling. */
-export const Disabled: StoryObj = {
+export const DisabledStory: StoryObj = {
+  name: "Disabled",
   render: () => (
     <div style={{ display: "flex", gap: "0.75rem" }}>
-      <Interactive.Base
+      <Disabled disabled>
+        <Interactive.Stateless
+          variant="default"
+          prominence="secondary"
+          onClick={() => {}}
+        >
+          <Interactive.Container border>
+            <span className="interactive-foreground">Disabled</span>
+          </Interactive.Container>
+        </Interactive.Stateless>
+      </Disabled>
+
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
         onClick={() => {}}
-        disabled
       >
         <Interactive.Container border>
-          <span>Disabled</span>
+          <span className="interactive-foreground">Enabled</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
+    </div>
+  ),
+};
 
-      <Interactive.Base
+/** Interaction override forces the hover/active visual state. */
+export const Interaction: StoryObj = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem" }}>
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
+        interaction="hover"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Enabled</span>
+          <span className="interactive-foreground">Forced hover</span>
         </Interactive.Container>
-      </Interactive.Base>
-    </div>
-  ),
-};
+      </Interactive.Stateless>
 
-/** Transient prop forces the hover/active visual state. */
-export const Transient: StoryObj = {
-  render: () => (
-    <div style={{ display: "flex", gap: "0.75rem" }}>
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
+        interaction="active"
         onClick={() => {}}
-        transient
       >
         <Interactive.Container border>
-          <span>Forced hover</span>
+          <span className="interactive-foreground">Forced active</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
 
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Normal</span>
+          <span className="interactive-foreground">Normal (rest)</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
     </div>
   ),
 };
@@ -253,25 +268,25 @@ export const Transient: StoryObj = {
 export const WithBorder: StoryObj = {
   render: () => (
     <div style={{ display: "flex", gap: "0.75rem" }}>
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>With border</span>
+          <span className="interactive-foreground">With border</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
 
-      <Interactive.Base
+      <Interactive.Stateless
         variant="default"
         prominence="secondary"
         onClick={() => {}}
       >
         <Interactive.Container>
-          <span>Without border</span>
+          <span className="interactive-foreground">Without border</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateless>
     </div>
   ),
 };
@@ -279,51 +294,57 @@ export const WithBorder: StoryObj = {
 /** Using href to render as a link. */
 export const AsLink: StoryObj = {
   render: () => (
-    <Interactive.Base variant="action" href="/settings">
+    <Interactive.Stateless variant="action" href="/settings">
       <Interactive.Container border>
-        <span>Go to Settings</span>
+        <span className="interactive-foreground">Go to Settings</span>
       </Interactive.Container>
-    </Interactive.Base>
+    </Interactive.Stateless>
   ),
 };
 
-/** Select variant with selected and unselected states. */
+/** Stateful select variant with selected and unselected states. */
 export const SelectVariant: StoryObj = {
   render: () => (
     <div style={{ display: "flex", gap: "0.75rem" }}>
-      <Interactive.Base
-        variant="select"
-        prominence="light"
-        selected
+      <Interactive.Stateful
+        variant="select-light"
+        state="selected"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Selected (light)</span>
+          <span className="interactive-foreground">Selected (light)</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateful>
 
-      <Interactive.Base variant="select" prominence="light" onClick={() => {}}>
+      <Interactive.Stateful
+        variant="select-light"
+        state="empty"
+        onClick={() => {}}
+      >
         <Interactive.Container border>
-          <span>Unselected (light)</span>
+          <span className="interactive-foreground">Unselected (light)</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateful>
 
-      <Interactive.Base
-        variant="select"
-        prominence="heavy"
-        selected
+      <Interactive.Stateful
+        variant="select-heavy"
+        state="selected"
         onClick={() => {}}
       >
         <Interactive.Container border>
-          <span>Selected (heavy)</span>
+          <span className="interactive-foreground">Selected (heavy)</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateful>
 
-      <Interactive.Base variant="select" prominence="heavy" onClick={() => {}}>
+      <Interactive.Stateful
+        variant="select-heavy"
+        state="empty"
+        onClick={() => {}}
+      >
         <Interactive.Container border>
-          <span>Unselected (heavy)</span>
+          <span className="interactive-foreground">Unselected (heavy)</span>
         </Interactive.Container>
-      </Interactive.Base>
+      </Interactive.Stateful>
     </div>
   ),
 };
diff --git a/web/lib/opal/src/icons/import.tsx b/web/lib/opal/src/icons/import-icon.tsx
similarity index 100%
rename from web/lib/opal/src/icons/import.tsx
rename to web/lib/opal/src/icons/import-icon.tsx
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index 4dd0f6a00f2..5edc2c14068 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -89,7 +89,7 @@ export { default as SvgHistory } from "@opal/icons/history";
 export { default as SvgHourglass } from "@opal/icons/hourglass";
 export { default as SvgImage } from "@opal/icons/image";
 export { default as SvgImageSmall } from "@opal/icons/image-small";
-export { default as SvgImport } from "@opal/icons/import";
+export { default as SvgImport } from "@opal/icons/import-icon";
 export { default as SvgInfo } from "@opal/icons/info";
 export { default as SvgInfoSmall } from "@opal/icons/info-small";
 export { default as SvgKey } from "@opal/icons/key";
diff --git a/web/lib/opal/src/layouts/ContentAction/ContentAction.stories.tsx b/web/lib/opal/src/layouts/content-action/ContentAction.stories.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/ContentAction/ContentAction.stories.tsx
rename to web/lib/opal/src/layouts/content-action/ContentAction.stories.tsx
diff --git a/web/lib/opal/src/layouts/Content/BodyLayout.stories.tsx b/web/lib/opal/src/layouts/content/BodyLayout.stories.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/Content/BodyLayout.stories.tsx
rename to web/lib/opal/src/layouts/content/BodyLayout.stories.tsx
diff --git a/web/lib/opal/src/layouts/Content/Content.stories.tsx b/web/lib/opal/src/layouts/content/Content.stories.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/Content/Content.stories.tsx
rename to web/lib/opal/src/layouts/content/Content.stories.tsx
diff --git a/web/lib/opal/src/layouts/Content/HeadingLayout.stories.tsx b/web/lib/opal/src/layouts/content/HeadingLayout.stories.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/Content/HeadingLayout.stories.tsx
rename to web/lib/opal/src/layouts/content/HeadingLayout.stories.tsx
diff --git a/web/lib/opal/src/layouts/Content/LabelLayout.stories.tsx b/web/lib/opal/src/layouts/content/LabelLayout.stories.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/Content/LabelLayout.stories.tsx
rename to web/lib/opal/src/layouts/content/LabelLayout.stories.tsx
diff --git a/web/lib/opal/src/layouts/IllustrationContent/IllustrationContent.stories.tsx b/web/lib/opal/src/layouts/illustration-content/IllustrationContent.stories.tsx
similarity index 100%
rename from web/lib/opal/src/layouts/IllustrationContent/IllustrationContent.stories.tsx
rename to web/lib/opal/src/layouts/illustration-content/IllustrationContent.stories.tsx
diff --git a/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx b/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx
index e6107352e4a..f666c7b2650 100644
--- a/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx
+++ b/web/src/refresh-components/buttons/ButtonRenaming.stories.tsx
@@ -2,6 +2,8 @@ import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import ButtonRenaming from "./ButtonRenaming";
 
+const noop = () => {};
+
 const meta: Meta<typeof ButtonRenaming> = {
   title: "refresh-components/buttons/ButtonRenaming",
   component: ButtonRenaming,
@@ -28,35 +30,23 @@ type Story = StoryObj<typeof ButtonRenaming>;
 export const Default: Story = {
   args: {
     initialName: "My Chat Session",
-    onRename: async (name: string) => {
-      console.log("Renamed to:", name);
-    },
-    onClose: () => {
-      console.log("Closed");
-    },
+    onRename: async () => {},
+    onClose: noop,
   },
 };
 
 export const EmptyName: Story = {
   args: {
     initialName: null,
-    onRename: async (name: string) => {
-      console.log("Renamed to:", name);
-    },
-    onClose: () => {
-      console.log("Closed");
-    },
+    onRename: async () => {},
+    onClose: noop,
   },
 };
 
 export const LongName: Story = {
   args: {
     initialName: "This is a very long chat session name that should overflow",
-    onRename: async (name: string) => {
-      console.log("Renamed to:", name);
-    },
-    onClose: () => {
-      console.log("Closed");
-    },
+    onRename: async () => {},
+    onClose: noop,
   },
 };

From 2f628e39d3a5ae5ce9e18b2318aa57117c2d56a8 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 10 Mar 2026 14:03:47 -0700
Subject: [PATCH 217/267] fix(fe): correctly parse comma literals in CSVs
 (#9245)

---
 web/jest.config.js                        |  1 +
 web/src/components/tools/CSVContent.tsx   | 81 ++++++++++++++++++----
 web/src/components/tools/parseCSV.test.ts | 84 +++++++++++++++++++++++
 3 files changed, 151 insertions(+), 15 deletions(-)
 create mode 100644 web/src/components/tools/parseCSV.test.ts

diff --git a/web/jest.config.js b/web/jest.config.js
index 7ba48ecf563..0fc47bc6c25 100644
--- a/web/jest.config.js
+++ b/web/jest.config.js
@@ -144,6 +144,7 @@ module.exports = {
         "**/src/app/**/hooks/*.test.ts", // Pure packet processor tests
         "**/src/refresh-components/**/*.test.ts",
         "**/src/sections/**/*.test.ts",
+        "**/src/components/**/*.test.ts",
         // Add more patterns here as you add more unit tests
       ],
     },
diff --git a/web/src/components/tools/CSVContent.tsx b/web/src/components/tools/CSVContent.tsx
index 1982327b8a9..c0371253ba1 100644
--- a/web/src/components/tools/CSVContent.tsx
+++ b/web/src/components/tools/CSVContent.tsx
@@ -60,27 +60,28 @@ const CsvContent: React.FC<ContentComponentProps> = ({
       }
 
       const csvData = await response.text();
-      const rows = csvData.trim().split("\n");
+      const rows = parseCSV(csvData.trim());
       const firstRow = rows[0];
       if (!firstRow) {
         throw new Error("CSV file is empty");
       }
-      const parsedHeaders = firstRow.split(",");
+      const parsedHeaders = firstRow;
       setHeaders(parsedHeaders);
 
-      const parsedData: Record<string, string>[] = rows.slice(1).map((row) => {
-        const values = row.split(",");
-        return parsedHeaders.reduce<Record<string, string>>(
-          (obj, header, index) => {
-            const val = values[index];
-            if (val !== undefined) {
-              obj[header] = val;
-            }
-            return obj;
-          },
-          {}
-        );
-      });
+      const parsedData: Record<string, string>[] = rows
+        .slice(1)
+        .map((fields) => {
+          return parsedHeaders.reduce<Record<string, string>>(
+            (obj, header, index) => {
+              const val = fields[index];
+              if (val !== undefined) {
+                obj[header] = val;
+              }
+              return obj;
+            },
+            {}
+          );
+        });
       setData(parsedData);
       csvCache.set(id, { headers: parsedHeaders, data: parsedData });
     } catch (error) {
@@ -173,3 +174,53 @@ const csvCache = new Map<
   string,
   { headers: string[]; data: Record<string, string>[] }
 >();
+
+export function parseCSV(text: string): string[][] {
+  const rows: string[][] = [];
+  let field = "";
+  let fields: string[] = [];
+  let inQuotes = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+
+    if (inQuotes) {
+      if (char === '"') {
+        if (i + 1 < text.length && text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += char;
+      }
+    } else if (char === '"') {
+      inQuotes = true;
+    } else if (char === ",") {
+      fields.push(field);
+      field = "";
+    } else if (char === "\n" || char === "\r") {
+      if (char === "\r" && i + 1 < text.length && text[i + 1] === "\n") {
+        i++;
+      }
+      fields.push(field);
+      field = "";
+      rows.push(fields);
+      fields = [];
+    } else {
+      field += char;
+    }
+  }
+
+  if (inQuotes) {
+    throw new Error("Malformed CSV: unterminated quoted field");
+  }
+
+  if (field.length > 0 || fields.length > 0) {
+    fields.push(field);
+    rows.push(fields);
+  }
+
+  return rows;
+}
diff --git a/web/src/components/tools/parseCSV.test.ts b/web/src/components/tools/parseCSV.test.ts
new file mode 100644
index 00000000000..8cc4aa59c4c
--- /dev/null
+++ b/web/src/components/tools/parseCSV.test.ts
@@ -0,0 +1,84 @@
+import { parseCSV } from "./CSVContent";
+
+describe("parseCSV", () => {
+  it("parses simple comma-separated rows", () => {
+    expect(parseCSV("a,b,c\n1,2,3")).toEqual([
+      ["a", "b", "c"],
+      ["1", "2", "3"],
+    ]);
+  });
+
+  it("preserves commas inside quoted fields", () => {
+    expect(parseCSV('name,address\nAlice,"123 Main St, Apt 4"')).toEqual([
+      ["name", "address"],
+      ["Alice", "123 Main St, Apt 4"],
+    ]);
+  });
+
+  it("handles escaped double quotes inside quoted fields", () => {
+    expect(parseCSV('a,b\n"say ""hello""",world')).toEqual([
+      ["a", "b"],
+      ['say "hello"', "world"],
+    ]);
+  });
+
+  it("handles newlines inside quoted fields", () => {
+    expect(parseCSV('a,b\n"line1\nline2",val')).toEqual([
+      ["a", "b"],
+      ["line1\nline2", "val"],
+    ]);
+  });
+
+  it("handles CRLF line endings", () => {
+    expect(parseCSV("a,b\r\n1,2\r\n3,4")).toEqual([
+      ["a", "b"],
+      ["1", "2"],
+      ["3", "4"],
+    ]);
+  });
+
+  it("handles empty fields", () => {
+    expect(parseCSV("a,b,c\n1,,3")).toEqual([
+      ["a", "b", "c"],
+      ["1", "", "3"],
+    ]);
+  });
+
+  it("handles a single element", () => {
+    expect(parseCSV("a")).toEqual([["a"]]);
+  });
+
+  it("handles a single row with no newline", () => {
+    expect(parseCSV("a,b,c")).toEqual([["a", "b", "c"]]);
+  });
+
+  it("handles quoted fields that are entirely empty", () => {
+    expect(parseCSV('a,b\n"",val')).toEqual([
+      ["a", "b"],
+      ["", "val"],
+    ]);
+  });
+
+  it("handles multiple quoted fields with commas", () => {
+    expect(parseCSV('"foo, bar","baz, qux"\n"1, 2","3, 4"')).toEqual([
+      ["foo, bar", "baz, qux"],
+      ["1, 2", "3, 4"],
+    ]);
+  });
+
+  it("throws on unterminated quoted field", () => {
+    expect(() => parseCSV('a,b\n"foo,bar')).toThrow(
+      "Malformed CSV: unterminated quoted field"
+    );
+  });
+
+  it("throws on unterminated quote at end of input", () => {
+    expect(() => parseCSV('"unterminated')).toThrow(
+      "Malformed CSV: unterminated quoted field"
+    );
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(parseCSV("")).toEqual([]);
+  });
+});

From dcb18c241130fc65d4684de26369e221e52ad3ab Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Tue, 10 Mar 2026 14:31:44 -0700
Subject: [PATCH 218/267] chore(opensearch): Followup for #9243 (#9247)

---
 backend/onyx/document_index/opensearch/search.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/backend/onyx/document_index/opensearch/search.py b/backend/onyx/document_index/opensearch/search.py
index 1c1033e60fc..160169e7f5c 100644
--- a/backend/onyx/document_index/opensearch/search.py
+++ b/backend/onyx/document_index/opensearch/search.py
@@ -255,8 +255,12 @@ def get_hybrid_search_query(
                 f"result window ({DEFAULT_OPENSEARCH_MAX_RESULT_WINDOW})."
             )
 
+        # TODO(andrei, yuhong): We can tune this more dynamically based on
+        # num_hits.
+        max_results_per_subquery = DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES
+
         hybrid_search_subqueries = DocumentQuery._get_hybrid_search_subqueries(
-            query_text, query_vector
+            query_text, query_vector, vector_candidates=max_results_per_subquery
         )
         hybrid_search_filters = DocumentQuery._get_search_filters(
             tenant_state=tenant_state,
@@ -291,7 +295,7 @@ def get_hybrid_search_query(
                 # Sources:
                 # https://docs.opensearch.org/latest/vector-search/ai-search/hybrid-search/pagination/
                 # https://opensearch.org/blog/navigating-pagination-in-hybrid-queries-with-the-pagination_depth-parameter/
-                "pagination_depth": DEFAULT_NUM_HYBRID_SEARCH_CANDIDATES,
+                "pagination_depth": max_results_per_subquery,
                 # Applied to all the sub-queries independently (this avoids
                 # subqueries having a lot of results thrown out during
                 # aggregation).

From 9e42951fa45cd32d0bb396ecf05045f3af5fbb4f Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 10 Mar 2026 14:45:23 -0700
Subject: [PATCH 219/267] fix(fe): increase responsive breakpoint for centering
 modals (#9250)

---
 web/src/hooks/useContainerCenter.ts | 8 ++++----
 web/src/hooks/useScreenSize.ts      | 4 ++++
 web/src/lib/constants.ts            | 1 +
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/web/src/hooks/useContainerCenter.ts b/web/src/hooks/useContainerCenter.ts
index 311ecbbebca..09da8283595 100644
--- a/web/src/hooks/useContainerCenter.ts
+++ b/web/src/hooks/useContainerCenter.ts
@@ -38,7 +38,7 @@ function measure(el: HTMLElement): { x: number; y: number } | null {
  */
 export default function useContainerCenter(): ContainerCenter {
   const pathname = usePathname();
-  const { isSmallScreen } = useScreenSize();
+  const { isMediumScreen } = useScreenSize();
   const [center, setCenter] = useState<{ x: number | null; y: number | null }>(
     () => {
       if (typeof document === "undefined") return NULL_CENTER;
@@ -68,9 +68,9 @@ export default function useContainerCenter(): ContainerCenter {
   }, [pathname]);
 
   return {
-    centerX: isSmallScreen ? null : center.x,
-    centerY: isSmallScreen ? null : center.y,
-    hasContainerCenter: isSmallScreen
+    centerX: isMediumScreen ? null : center.x,
+    centerY: isMediumScreen ? null : center.y,
+    hasContainerCenter: isMediumScreen
       ? false
       : center.x !== null && center.y !== null,
   };
diff --git a/web/src/hooks/useScreenSize.ts b/web/src/hooks/useScreenSize.ts
index dc08b508909..66d86927bfc 100644
--- a/web/src/hooks/useScreenSize.ts
+++ b/web/src/hooks/useScreenSize.ts
@@ -2,6 +2,7 @@
 
 import {
   DESKTOP_SMALL_BREAKPOINT_PX,
+  DESKTOP_MEDIUM_BREAKPOINT_PX,
   MOBILE_SIDEBAR_BREAKPOINT_PX,
 } from "@/lib/constants";
 import { useState, useCallback } from "react";
@@ -12,6 +13,7 @@ export interface ScreenSize {
   width: number;
   isMobile: boolean;
   isSmallScreen: boolean;
+  isMediumScreen: boolean;
 }
 
 export default function useScreenSize(): ScreenSize {
@@ -34,11 +36,13 @@ export default function useScreenSize(): ScreenSize {
 
   const isMobile = sizes.width <= MOBILE_SIDEBAR_BREAKPOINT_PX;
   const isSmall = sizes.width <= DESKTOP_SMALL_BREAKPOINT_PX;
+  const isMedium = sizes.width <= DESKTOP_MEDIUM_BREAKPOINT_PX;
 
   return {
     height: sizes.height,
     width: sizes.width,
     isMobile: isMounted && isMobile,
     isSmallScreen: isMounted && isSmall,
+    isMediumScreen: isMounted && isMedium,
   };
 }
diff --git a/web/src/lib/constants.ts b/web/src/lib/constants.ts
index de232adb2b4..6e048d9bae6 100644
--- a/web/src/lib/constants.ts
+++ b/web/src/lib/constants.ts
@@ -123,6 +123,7 @@ export const MAX_FILES_TO_SHOW = 3;
 // SIZES
 export const MOBILE_SIDEBAR_BREAKPOINT_PX = 640;
 export const DESKTOP_SMALL_BREAKPOINT_PX = 912;
+export const DESKTOP_MEDIUM_BREAKPOINT_PX = 1232;
 export const DEFAULT_AGENT_AVATAR_SIZE_PX = 18;
 export const HORIZON_DISTANCE_PX = 800;
 export const LOGO_FOLDED_SIZE_PX = 24;

From 17551a907e3379667b7979dcd933b2d742804499 Mon Sep 17 00:00:00 2001
From: acaprau <48705707+acaprau@users.noreply.github.com>
Date: Tue, 10 Mar 2026 14:49:55 -0700
Subject: [PATCH 220/267] fix(opensearch): Update should clear projects and
 personas when they are empty (#8845)

---
 .../opensearch/opensearch_document_index.py   |   8 +-
 .../onyx/document_index/opensearch/search.py  |  18 +-
 backend/onyx/document_index/vespa/index.py    |   3 +
 .../document_index/test_document_index_old.py | 398 ++++++++++++++++++
 .../test_opensearch_migration_tasks.py        |   2 +
 5 files changed, 417 insertions(+), 12 deletions(-)
 create mode 100644 backend/tests/external_dependency_unit/document_index/test_document_index_old.py

diff --git a/backend/onyx/document_index/opensearch/opensearch_document_index.py b/backend/onyx/document_index/opensearch/opensearch_document_index.py
index 62dfdaa8ba9..7f233493bff 100644
--- a/backend/onyx/document_index/opensearch/opensearch_document_index.py
+++ b/backend/onyx/document_index/opensearch/opensearch_document_index.py
@@ -433,12 +433,16 @@ def update_single(
             hidden=fields.hidden if fields else None,
             project_ids=(
                 set(user_fields.user_projects)
-                if user_fields and user_fields.user_projects
+                # NOTE: Empty user_projects is semantically different from None
+                # user_projects.
+                if user_fields and user_fields.user_projects is not None
                 else None
             ),
             persona_ids=(
                 set(user_fields.personas)
-                if user_fields and user_fields.personas
+                # NOTE: Empty personas is semantically different from None
+                # personas.
+                if user_fields and user_fields.personas is not None
                 else None
             ),
         )
diff --git a/backend/onyx/document_index/opensearch/search.py b/backend/onyx/document_index/opensearch/search.py
index 160169e7f5c..b9a6e7fc2dc 100644
--- a/backend/onyx/document_index/opensearch/search.py
+++ b/backend/onyx/document_index/opensearch/search.py
@@ -738,14 +738,13 @@ def _get_hierarchy_node_filter(
             # document's metadata list.
             filter_clauses.append(_get_tag_filter(tags))
 
-        # Knowledge scope: explicit knowledge attachments restrict what
-        # an assistant can see.  When none are set the assistant
-        # searches everything.
+        # Knowledge scope: explicit knowledge attachments restrict what an
+        # assistant can see. When none are set the assistant searches
+        # everything.
         #
-        # project_id / persona_id are additive: they make overflowing
-        # user files findable but must NOT trigger the restriction on
-        # their own (an agent with no explicit knowledge should search
-        # everything).
+        # project_id / persona_id are additive: they make overflowing user files
+        # findable but must NOT trigger the restriction on their own (an agent
+        # with no explicit knowledge should search everything).
         has_knowledge_scope = (
             attached_document_ids
             or hierarchy_node_ids
@@ -773,9 +772,8 @@ def _get_hierarchy_node_filter(
                 knowledge_filter["bool"]["should"].append(
                     _get_document_set_filter(document_sets)
                 )
-            # Additive: widen scope to also cover overflowing user
-            # files, but only when an explicit restriction is already
-            # in effect.
+            # Additive: widen scope to also cover overflowing user files, but
+            # only when an explicit restriction is already in effect.
             if project_id is not None:
                 knowledge_filter["bool"]["should"].append(
                     _get_user_project_filter(project_id)
diff --git a/backend/onyx/document_index/vespa/index.py b/backend/onyx/document_index/vespa/index.py
index 5e2d8d2732b..71322f90f67 100644
--- a/backend/onyx/document_index/vespa/index.py
+++ b/backend/onyx/document_index/vespa/index.py
@@ -690,9 +690,12 @@ def update_single(
             )
 
         project_ids: set[int] | None = None
+        # NOTE: Empty user_projects is semantically different from None
+        # user_projects.
         if user_fields is not None and user_fields.user_projects is not None:
             project_ids = set(user_fields.user_projects)
         persona_ids: set[int] | None = None
+        # NOTE: Empty personas is semantically different from None personas.
         if user_fields is not None and user_fields.personas is not None:
             persona_ids = set(user_fields.personas)
         update_request = MetadataUpdateRequest(
diff --git a/backend/tests/external_dependency_unit/document_index/test_document_index_old.py b/backend/tests/external_dependency_unit/document_index/test_document_index_old.py
new file mode 100644
index 00000000000..bd76a35f120
--- /dev/null
+++ b/backend/tests/external_dependency_unit/document_index/test_document_index_old.py
@@ -0,0 +1,398 @@
+"""External dependency tests for the old DocumentIndex interface.
+
+These tests assume Vespa and OpenSearch are running.
+
+TODO(ENG-3764)(andrei): Consolidate some of these test fixtures.
+"""
+
+import os
+import time
+import uuid
+from collections.abc import Generator
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from onyx.access.models import DocumentAccess
+from onyx.configs.constants import DocumentSource
+from onyx.connectors.models import Document
+from onyx.context.search.models import IndexFilters
+from onyx.db.enums import EmbeddingPrecision
+from onyx.document_index.interfaces import DocumentIndex
+from onyx.document_index.interfaces import IndexBatchParams
+from onyx.document_index.interfaces import VespaChunkRequest
+from onyx.document_index.interfaces import VespaDocumentUserFields
+from onyx.document_index.opensearch.client import wait_for_opensearch_with_timeout
+from onyx.document_index.opensearch.opensearch_document_index import (
+    OpenSearchOldDocumentIndex,
+)
+from onyx.document_index.vespa.index import VespaIndex
+from onyx.document_index.vespa.shared_utils.utils import get_vespa_http_client
+from onyx.document_index.vespa.shared_utils.utils import wait_for_vespa_with_timeout
+from onyx.indexing.models import ChunkEmbedding
+from onyx.indexing.models import DocMetadataAwareIndexChunk
+from shared_configs.configs import MULTI_TENANT
+from shared_configs.contextvars import CURRENT_TENANT_ID_CONTEXTVAR
+from shared_configs.contextvars import get_current_tenant_id
+from tests.external_dependency_unit.constants import TEST_TENANT_ID
+
+
+@pytest.fixture(scope="module")
+def opensearch_available() -> Generator[None, None, None]:
+    """Verifies OpenSearch is running, fails the test if not."""
+    if not wait_for_opensearch_with_timeout():
+        pytest.fail("OpenSearch is not available.")
+    yield  # Test runs here.
+
+
+@pytest.fixture(scope="module")
+def test_index_name() -> Generator[str, None, None]:
+    yield f"test_index_{uuid.uuid4().hex[:8]}"  # Test runs here.
+
+
+@pytest.fixture(scope="module")
+def tenant_context() -> Generator[None, None, None]:
+    """Sets up tenant context for testing."""
+    token = CURRENT_TENANT_ID_CONTEXTVAR.set(TEST_TENANT_ID)
+    try:
+        yield  # Test runs here.
+    finally:
+        # Reset the tenant context after the test
+        CURRENT_TENANT_ID_CONTEXTVAR.reset(token)
+
+
+@pytest.fixture(scope="module")
+def httpx_client() -> Generator[httpx.Client, None, None]:
+    client = get_vespa_http_client()
+    try:
+        yield client
+    finally:
+        client.close()
+
+
+@pytest.fixture(scope="module")
+def vespa_document_index(
+    httpx_client: httpx.Client,
+    tenant_context: None,  # noqa: ARG001
+    test_index_name: str,
+) -> Generator[VespaIndex, None, None]:
+    vespa_index = VespaIndex(
+        index_name=test_index_name,
+        secondary_index_name=None,
+        large_chunks_enabled=False,
+        secondary_large_chunks_enabled=None,
+        multitenant=MULTI_TENANT,
+        httpx_client=httpx_client,
+    )
+    backend_dir = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..", "..")
+    )
+    with patch("os.getcwd", return_value=backend_dir):
+        vespa_index.ensure_indices_exist(
+            primary_embedding_dim=128,
+            primary_embedding_precision=EmbeddingPrecision.FLOAT,
+            secondary_index_embedding_dim=None,
+            secondary_index_embedding_precision=None,
+        )
+    # Verify Vespa is running, fails the test if not. Try 90 seconds for testing
+    # in CI. We have to do this here because this endpoint only becomes live
+    # once we create an index.
+    if not wait_for_vespa_with_timeout(wait_limit=90):
+        pytest.fail("Vespa is not available.")
+
+    # Wait until the schema is actually ready for writes on content nodes. We
+    # probe by attempting a PUT; 200 means the schema is live, 400 means not
+    # yet. This is so scuffed but running the test is really flakey otherwise;
+    # this is only temporary until we entirely move off of Vespa.
+    probe_doc = {
+        "fields": {
+            "document_id": "__probe__",
+            "chunk_id": 0,
+            "blurb": "",
+            "title": "",
+            "skip_title": True,
+            "content": "",
+            "content_summary": "",
+            "source_type": "file",
+            "source_links": "null",
+            "semantic_identifier": "",
+            "section_continuation": False,
+            "large_chunk_reference_ids": [],
+            "metadata": "{}",
+            "metadata_list": [],
+            "metadata_suffix": "",
+            "chunk_context": "",
+            "doc_summary": "",
+            "embeddings": {"full_chunk": [1.0] + [0.0] * 127},
+            "access_control_list": {},
+            "document_sets": {},
+            "image_file_name": None,
+            "user_project": [],
+            "personas": [],
+            "boost": 0.0,
+            "aggregated_chunk_boost_factor": 0.0,
+            "primary_owners": [],
+            "secondary_owners": [],
+        }
+    }
+    schema_ready = False
+    probe_url = (
+        f"http://localhost:8081/document/v1/default/{test_index_name}/docid/__probe__"
+    )
+    for _ in range(60):
+        resp = httpx_client.post(probe_url, json=probe_doc)
+        if resp.status_code == 200:
+            schema_ready = True
+            # Clean up the probe document.
+            httpx_client.delete(probe_url)
+            break
+        time.sleep(1)
+    if not schema_ready:
+        pytest.fail(f"Vespa schema '{test_index_name}' did not become ready in time.")
+
+    yield vespa_index  # Test runs here.
+
+    # TODO(ENG-3765)(andrei): Explicitly cleanup index. Not immediately
+    # pressing; in CI we should be using fresh instances of dependencies each
+    # time anyway.
+
+
+@pytest.fixture(scope="module")
+def opensearch_document_index(
+    opensearch_available: None,  # noqa: ARG001
+    tenant_context: None,  # noqa: ARG001
+    test_index_name: str,
+) -> Generator[OpenSearchOldDocumentIndex, None, None]:
+    opensearch_index = OpenSearchOldDocumentIndex(
+        index_name=test_index_name,
+        embedding_dim=128,
+        embedding_precision=EmbeddingPrecision.FLOAT,
+        secondary_index_name=None,
+        secondary_embedding_dim=None,
+        secondary_embedding_precision=None,
+        large_chunks_enabled=False,
+        secondary_large_chunks_enabled=None,
+        multitenant=MULTI_TENANT,
+    )
+    opensearch_index.ensure_indices_exist(
+        primary_embedding_dim=128,
+        primary_embedding_precision=EmbeddingPrecision.FLOAT,
+        secondary_index_embedding_dim=None,
+        secondary_index_embedding_precision=None,
+    )
+
+    yield opensearch_index  # Test runs here.
+
+    # TODO(ENG-3765)(andrei): Explicitly cleanup index. Not immediately
+    # pressing; in CI we should be using fresh instances of dependencies each
+    # time anyway.
+
+
+@pytest.fixture(scope="module")
+def document_indices(
+    vespa_document_index: VespaIndex,
+    opensearch_document_index: OpenSearchOldDocumentIndex,
+) -> Generator[list[DocumentIndex], None, None]:
+    # Ideally these are parametrized; doing so with pytest fixtures is tricky.
+    yield [opensearch_document_index, vespa_document_index]  # Test runs here.
+
+
+@pytest.fixture(scope="function")
+def chunks(
+    tenant_context: None,  # noqa: ARG001
+) -> Generator[list[DocMetadataAwareIndexChunk], None, None]:
+    result = []
+    chunk_count = 5
+    doc_id = "test_doc"
+    tenant_id = get_current_tenant_id()
+    access = DocumentAccess.build(
+        user_emails=[],
+        user_groups=[],
+        external_user_emails=[],
+        external_user_group_ids=[],
+        is_public=True,
+    )
+    document_sets: set[str] = set()
+    user_project: list[int] = list()
+    personas: list[int] = list()
+    boost = 0
+    blurb = "blurb"
+    content = "content"
+    title_prefix = ""
+    doc_summary = ""
+    chunk_context = ""
+    title_embedding = [1.0] + [0] * 127
+    # Full 0 vectors are not supported for cos similarity.
+    embeddings = ChunkEmbedding(
+        full_embedding=[1.0] + [0] * 127, mini_chunk_embeddings=[]
+    )
+    source_document = Document(
+        id=doc_id,
+        semantic_identifier="semantic identifier",
+        source=DocumentSource.FILE,
+        sections=[],
+        metadata={},
+        title="title",
+    )
+    metadata_suffix_keyword = ""
+    image_file_id = None
+    source_links: dict[int, str] = {0: ""}
+    ancestor_hierarchy_node_ids: list[int] = []
+    for i in range(chunk_count):
+        result.append(
+            DocMetadataAwareIndexChunk(
+                tenant_id=tenant_id,
+                access=access,
+                document_sets=document_sets,
+                user_project=user_project,
+                personas=personas,
+                boost=boost,
+                aggregated_chunk_boost_factor=0,
+                ancestor_hierarchy_node_ids=ancestor_hierarchy_node_ids,
+                embeddings=embeddings,
+                title_embedding=title_embedding,
+                source_document=source_document,
+                title_prefix=title_prefix,
+                metadata_suffix_keyword=metadata_suffix_keyword,
+                metadata_suffix_semantic="",
+                contextual_rag_reserved_tokens=0,
+                doc_summary=doc_summary,
+                chunk_context=chunk_context,
+                mini_chunk_texts=None,
+                large_chunk_id=None,
+                chunk_id=i,
+                blurb=blurb,
+                content=content,
+                source_links=source_links,
+                image_file_id=image_file_id,
+                section_continuation=False,
+            )
+        )
+    yield result  # Test runs here.
+
+
+@pytest.fixture(scope="function")
+def index_batch_params(
+    tenant_context: None,  # noqa: ARG001
+) -> Generator[IndexBatchParams, None, None]:
+    # WARNING: doc_id_to_previous_chunk_cnt={"test_doc": 0} is hardcoded to 0,
+    # which is only correct on the very first index call. The document_indices
+    # fixture is scope="module", meaning the same OpenSearch and Vespa backends
+    # persist across all test functions in this module. When a second test
+    # function uses this fixture and calls document_index.index(...), the
+    # backend already has 5 chunks for "test_doc" from the previous test run,
+    # but the batch params still claim 0 prior chunks exist. This can lead to
+    # orphaned/duplicate chunks that make subsequent assertions incorrect.
+    # TODO: Whenever adding a second test, either change this or cleanup the
+    # index between test cases.
+    yield IndexBatchParams(
+        doc_id_to_previous_chunk_cnt={"test_doc": 0},
+        doc_id_to_new_chunk_cnt={"test_doc": 5},
+        tenant_id=get_current_tenant_id(),
+        large_chunks_enabled=False,
+    )
+
+
+class TestDocumentIndexOld:
+    """Tests the old DocumentIndex interface."""
+
+    def test_update_single_can_clear_user_projects_and_personas(
+        self,
+        document_indices: list[DocumentIndex],
+        # This test case assumes all these chunks correspond to one document.
+        chunks: list[DocMetadataAwareIndexChunk],
+        index_batch_params: IndexBatchParams,
+    ) -> None:
+        """
+        Tests that update_single can clear user_projects and personas.
+        """
+        for document_index in document_indices:
+            # Precondition.
+            # Ensure there is some non-empty value for user project and
+            # personas.
+            for chunk in chunks:
+                chunk.user_project = [1]
+                chunk.personas = [2]
+            document_index.index(chunks, index_batch_params)
+
+            # Ensure that we can get chunks as expected with filters.
+            doc_id = chunks[0].source_document.id
+            chunk_count = len(chunks)
+            tenant_id = get_current_tenant_id()
+            # We need to specify the chunk index range and specify
+            # batch_retrieval=True below to trigger the codepath for Vespa's
+            # search API, which uses the expected additive filtering for
+            # project_id and persona_id. Otherwise we would use the codepath for
+            # the visit API, which does not have this kind of filtering
+            # implemented.
+            chunk_request = VespaChunkRequest(
+                document_id=doc_id, min_chunk_ind=0, max_chunk_ind=chunk_count - 1
+            )
+            project_persona_filters = IndexFilters(
+                access_control_list=None,
+                tenant_id=tenant_id,
+                project_id=1,
+                persona_id=2,
+                # We need this even though none of the chunks belong to a
+                # document set because project_id and persona_id are only
+                # additive filters in the event the agent has knowledge scope;
+                # if the agent does not, it is implied that it can see
+                # everything it is allowed to.
+                document_set=["1"],
+            )
+            # Not best practice here but the API for refreshing the index to
+            # ensure that the latest data is present is not exposed in this
+            # class and is not the same for Vespa and OpenSearch, so we just
+            # tolerate a sleep for now. As a consequence the number of tests in
+            # this suite should be small. We only need to tolerate this for as
+            # long as we continue to use Vespa, we can consider exposing
+            # something for OpenSearch later.
+            time.sleep(1)
+            inference_chunks = document_index.id_based_retrieval(
+                chunk_requests=[chunk_request],
+                filters=project_persona_filters,
+                batch_retrieval=True,
+            )
+            assert len(inference_chunks) == chunk_count
+            # Sort by chunk id to easily test if we have all chunks.
+            for i, inference_chunk in enumerate(
+                sorted(inference_chunks, key=lambda x: x.chunk_id)
+            ):
+                assert inference_chunk.chunk_id == i
+                assert inference_chunk.document_id == doc_id
+
+            # Under test.
+            # Explicitly set empty fields here.
+            user_fields = VespaDocumentUserFields(user_projects=[], personas=[])
+            document_index.update_single(
+                doc_id=doc_id,
+                chunk_count=chunk_count,
+                tenant_id=tenant_id,
+                fields=None,
+                user_fields=user_fields,
+            )
+
+            # Postcondition.
+            filters = IndexFilters(access_control_list=None, tenant_id=tenant_id)
+            # We should expect to get back all expected chunks with no filters.
+            # Again, not best practice here.
+            time.sleep(1)
+            inference_chunks = document_index.id_based_retrieval(
+                chunk_requests=[chunk_request], filters=filters, batch_retrieval=True
+            )
+            assert len(inference_chunks) == chunk_count
+            # Sort by chunk id to easily test if we have all chunks.
+            for i, inference_chunk in enumerate(
+                sorted(inference_chunks, key=lambda x: x.chunk_id)
+            ):
+                assert inference_chunk.chunk_id == i
+                assert inference_chunk.document_id == doc_id
+            # Now, we should expect to not get any chunks if we specify the user
+            # project and personas filters.
+            inference_chunks = document_index.id_based_retrieval(
+                chunk_requests=[chunk_request],
+                filters=project_persona_filters,
+                batch_retrieval=True,
+            )
+            assert len(inference_chunks) == 0
diff --git a/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py b/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
index 7a55cee9fc8..3a0684d6fec 100644
--- a/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
+++ b/backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
@@ -239,6 +239,8 @@ def full_deployment_setup() -> Generator[None, None, None]:
     NOTE: We deliberately duplicate this logic from
     backend/tests/external_dependency_unit/conftest.py because we need to set
     opensearch_available just for this module, not the entire test session.
+
+    TODO(ENG-3764)(andrei): Consolidate some of these test fixtures.
     """
     # Patch ENABLE_OPENSEARCH_INDEXING_FOR_ONYX just for this test because we
     # don't yet want that enabled for all tests.

From a92ff61f64d79b2c0c996462da3a611af2e9c76e Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 10 Mar 2026 15:18:39 -0700
Subject: [PATCH 221/267] chore: add cache_okay to EncryptedJson (#9252)

---
 backend/onyx/db/models.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index c5795dab340..1fc0c80f6f3 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -189,6 +189,9 @@ def process_result_value(
 
 
 class EncryptedJson(_EncryptedBase):
+    cache_ok = (
+        True  # have to re-declare because _is_json value is different from parent
+    )
     _is_json: bool = True
 
     def process_bind_param(

From 2cc8303e5f0aefb8b2bec3ef7279bb24d96b2d4e Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Tue, 10 Mar 2026 16:41:51 -0700
Subject: [PATCH 222/267] chore: sharepoint dedupe (#9254)

---
 .../onyx/connectors/sharepoint/connector.py   |  15 ++
 .../sharepoint/test_delta_checkpointing.py    | 226 ++++++++++++++++++
 2 files changed, 241 insertions(+)

diff --git a/backend/onyx/connectors/sharepoint/connector.py b/backend/onyx/connectors/sharepoint/connector.py
index 5a38015cee5..0082d139f34 100644
--- a/backend/onyx/connectors/sharepoint/connector.py
+++ b/backend/onyx/connectors/sharepoint/connector.py
@@ -258,6 +258,10 @@ class SharepointConnectorCheckpoint(ConnectorCheckpoint):
     # Track yielded hierarchy nodes by their raw_node_id (URLs) to avoid duplicates
     seen_hierarchy_node_raw_ids: set[str] = Field(default_factory=set)
 
+    # Track yielded document IDs to avoid processing the same document twice.
+    # The Microsoft Graph delta API can return the same item on multiple pages.
+    seen_document_ids: set[str] = Field(default_factory=set)
+
 
 class SharepointAuthMethod(Enum):
     CLIENT_SECRET = "client_secret"
@@ -1557,6 +1561,7 @@ def _clear_drive_checkpoint_state(
         checkpoint.current_drive_id = None
         checkpoint.current_drive_web_url = None
         checkpoint.current_drive_delta_next_link = None
+        checkpoint.seen_document_ids.clear()
 
     def _fetch_slim_documents_from_sharepoint(self) -> GenerateSlimDocumentOutput:
         site_descriptors = self.site_descriptors or self.fetch_sites()
@@ -2137,6 +2142,14 @@ def _load_from_checkpoint(
             item_count = 0
             for driveitem in driveitems:
                 item_count += 1
+
+                if driveitem.id and driveitem.id in checkpoint.seen_document_ids:
+                    logger.debug(
+                        f"Skipping duplicate document {driveitem.id} "
+                        f"({driveitem.name})"
+                    )
+                    continue
+
                 driveitem_extension = get_file_ext(driveitem.name)
                 if driveitem_extension not in OnyxFileExtensions.ALL_ALLOWED_EXTENSIONS:
                     logger.warning(
@@ -2189,11 +2202,13 @@ def _load_from_checkpoint(
 
                     if isinstance(doc_or_failure, Document):
                         if doc_or_failure.sections:
+                            checkpoint.seen_document_ids.add(doc_or_failure.id)
                             yield doc_or_failure
                         elif should_yield_if_empty:
                             doc_or_failure.sections = [
                                 TextSection(link=driveitem.web_url, text="")
                             ]
+                            checkpoint.seen_document_ids.add(doc_or_failure.id)
                             yield doc_or_failure
                         else:
                             logger.warning(
diff --git a/backend/tests/unit/onyx/connectors/sharepoint/test_delta_checkpointing.py b/backend/tests/unit/onyx/connectors/sharepoint/test_delta_checkpointing.py
index 9f8e4c79fb9..d811670faf5 100644
--- a/backend/tests/unit/onyx/connectors/sharepoint/test_delta_checkpointing.py
+++ b/backend/tests/unit/onyx/connectors/sharepoint/test_delta_checkpointing.py
@@ -6,6 +6,7 @@
 - Crash + resume skips already-processed pages
 - BFS (folder-scoped) drives process all items in one call
 - 410 Gone triggers a full-resync URL in the checkpoint
+- Duplicate document IDs across delta pages are deduplicated
 """
 
 from __future__ import annotations
@@ -457,3 +458,228 @@ def fake_fetch_page(
         assert final_cp.current_drive_name is None
         assert final_cp.current_drive_id is None
         assert final_cp.current_drive_delta_next_link is None
+
+
+class TestDeltaDuplicateDocumentDedup:
+    """The Microsoft Graph delta API can return the same item on multiple
+    pages.  Documents already yielded should be skipped via
+    checkpoint.seen_document_ids."""
+
+    def test_duplicate_across_pages_is_skipped(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Item 'dup' appears on both page 1 and page 2.  It should only be
+        yielded once."""
+        connector = _setup_connector(monkeypatch)
+        _mock_convert(monkeypatch)
+
+        call_count = 0
+
+        def fake_fetch_page(
+            self: SharepointConnector,  # noqa: ARG001
+            page_url: str,  # noqa: ARG001
+            drive_id: str,  # noqa: ARG001
+            start: datetime | None = None,  # noqa: ARG001
+            end: datetime | None = None,  # noqa: ARG001
+            page_size: int = 200,  # noqa: ARG001
+        ) -> tuple[list[DriveItemData], str | None]:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return [_make_item("a"), _make_item("dup")], "https://next2"
+            return [_make_item("dup"), _make_item("b")], None
+
+        monkeypatch.setattr(
+            SharepointConnector, "_fetch_one_delta_page", fake_fetch_page
+        )
+
+        checkpoint = _build_ready_checkpoint()
+
+        # Page 1: yields a, dup
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, checkpoint, include_permissions=False
+        )
+        yielded, checkpoint = _consume_generator(gen)
+        docs = _docs_from(yielded)
+        assert [d.id for d in docs] == ["a", "dup"]
+        assert "dup" in checkpoint.seen_document_ids
+
+        # Page 2: dup should be skipped, only b yielded
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, checkpoint, include_permissions=False
+        )
+        yielded, checkpoint = _consume_generator(gen)
+        docs = _docs_from(yielded)
+        assert [d.id for d in docs] == ["b"]
+
+    def test_duplicate_within_same_page_is_skipped(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """If the same item appears twice on a single delta page, only the
+        first occurrence should be yielded."""
+        connector = _setup_connector(monkeypatch)
+        _mock_convert(monkeypatch)
+
+        def fake_fetch_page(
+            self: SharepointConnector,  # noqa: ARG001
+            page_url: str,  # noqa: ARG001
+            drive_id: str,  # noqa: ARG001
+            start: datetime | None = None,  # noqa: ARG001
+            end: datetime | None = None,  # noqa: ARG001
+            page_size: int = 200,  # noqa: ARG001
+        ) -> tuple[list[DriveItemData], str | None]:
+            return [_make_item("x"), _make_item("x"), _make_item("y")], None
+
+        monkeypatch.setattr(
+            SharepointConnector, "_fetch_one_delta_page", fake_fetch_page
+        )
+
+        checkpoint = _build_ready_checkpoint()
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, checkpoint, include_permissions=False
+        )
+        yielded, checkpoint = _consume_generator(gen)
+        docs = _docs_from(yielded)
+        assert [d.id for d in docs] == ["x", "y"]
+
+    def test_seen_ids_survive_checkpoint_serialization(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """seen_document_ids must survive JSON serialization so that
+        dedup works across crash + resume."""
+        connector = _setup_connector(monkeypatch)
+        _mock_convert(monkeypatch)
+
+        call_count = 0
+
+        def fake_fetch_page(
+            self: SharepointConnector,  # noqa: ARG001
+            page_url: str,  # noqa: ARG001
+            drive_id: str,  # noqa: ARG001
+            start: datetime | None = None,  # noqa: ARG001
+            end: datetime | None = None,  # noqa: ARG001
+            page_size: int = 200,  # noqa: ARG001
+        ) -> tuple[list[DriveItemData], str | None]:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return [_make_item("a")], "https://next2"
+            return [_make_item("a"), _make_item("b")], None
+
+        monkeypatch.setattr(
+            SharepointConnector, "_fetch_one_delta_page", fake_fetch_page
+        )
+
+        checkpoint = _build_ready_checkpoint()
+
+        # Page 1
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, checkpoint, include_permissions=False
+        )
+        _, checkpoint = _consume_generator(gen)
+        assert "a" in checkpoint.seen_document_ids
+
+        # Simulate crash: round-trip through JSON
+        restored = SharepointConnectorCheckpoint.model_validate_json(
+            checkpoint.model_dump_json()
+        )
+        assert "a" in restored.seen_document_ids
+
+        # Page 2 with restored checkpoint: 'a' should be skipped
+        connector2 = _setup_connector(monkeypatch)
+        _mock_convert(monkeypatch)
+        monkeypatch.setattr(
+            SharepointConnector, "_fetch_one_delta_page", fake_fetch_page
+        )
+
+        gen = connector2._load_from_checkpoint(
+            _START_TS, _END_TS, restored, include_permissions=False
+        )
+        yielded, final_cp = _consume_generator(gen)
+        docs = _docs_from(yielded)
+        assert [d.id for d in docs] == ["b"]
+
+    def test_no_dedup_across_separate_indexing_runs(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A fresh checkpoint (new indexing run) should have an empty
+        seen_document_ids, so previously-indexed docs are re-processed."""
+        connector = _setup_connector(monkeypatch)
+        _mock_convert(monkeypatch)
+
+        def fake_fetch_page(
+            self: SharepointConnector,  # noqa: ARG001
+            page_url: str,  # noqa: ARG001
+            drive_id: str,  # noqa: ARG001
+            start: datetime | None = None,  # noqa: ARG001
+            end: datetime | None = None,  # noqa: ARG001
+            page_size: int = 200,  # noqa: ARG001
+        ) -> tuple[list[DriveItemData], str | None]:
+            return [_make_item("a")], None
+
+        monkeypatch.setattr(
+            SharepointConnector, "_fetch_one_delta_page", fake_fetch_page
+        )
+
+        # First run
+        cp1 = _build_ready_checkpoint()
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, cp1, include_permissions=False
+        )
+        yielded, _ = _consume_generator(gen)
+        assert len(_docs_from(yielded)) == 1
+
+        # Second run with a fresh checkpoint — same doc should appear again
+        cp2 = _build_ready_checkpoint()
+        assert len(cp2.seen_document_ids) == 0
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, cp2, include_permissions=False
+        )
+        yielded, _ = _consume_generator(gen)
+        assert len(_docs_from(yielded)) == 1
+
+    def test_same_id_across_drives_not_skipped(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Graph item IDs are only unique within a drive.  An item in drive B
+        that happens to share an ID with an item already seen in drive A must
+        NOT be skipped."""
+        connector = _setup_connector(monkeypatch)
+        _mock_convert(monkeypatch)
+
+        def fake_fetch_page(
+            self: SharepointConnector,  # noqa: ARG001
+            page_url: str,  # noqa: ARG001
+            drive_id: str,  # noqa: ARG001
+            start: datetime | None = None,  # noqa: ARG001
+            end: datetime | None = None,  # noqa: ARG001
+            page_size: int = 200,  # noqa: ARG001
+        ) -> tuple[list[DriveItemData], str | None]:
+            return [_make_item("shared-id")], None
+
+        monkeypatch.setattr(
+            SharepointConnector, "_fetch_one_delta_page", fake_fetch_page
+        )
+
+        checkpoint = _build_ready_checkpoint(drive_names=["DriveA", "DriveB"])
+
+        # Drive A: yields the item
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, checkpoint, include_permissions=False
+        )
+        yielded, checkpoint = _consume_generator(gen)
+        docs = _docs_from(yielded)
+        assert len(docs) == 1
+        assert docs[0].id == "shared-id"
+
+        # seen_document_ids should have been cleared when drive A finished
+        assert len(checkpoint.seen_document_ids) == 0
+
+        # Drive B: same ID must be yielded again (different drive)
+        gen = connector._load_from_checkpoint(
+            _START_TS, _END_TS, checkpoint, include_permissions=False
+        )
+        yielded, checkpoint = _consume_generator(gen)
+        docs = _docs_from(yielded)
+        assert len(docs) == 1
+        assert docs[0].id == "shared-id"

From f97466e4deeffc86ca2dc25b90948e00f3f0e02f Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Tue, 10 Mar 2026 16:44:51 -0700
Subject: [PATCH 223/267] chore: redeclare cache_okay for EncryptedBase
 children (#9253)

---
 backend/onyx/db/models.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index 1fc0c80f6f3..10b66deefde 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -163,6 +163,8 @@ def compare_values(self, x: Any, y: Any) -> bool:
 
 
 class EncryptedString(_EncryptedBase):
+    # Must redeclare cache_ok in this child class since we explicitly redeclare _is_json
+    cache_ok = True
     _is_json: bool = False
 
     def process_bind_param(
@@ -189,9 +191,7 @@ def process_result_value(
 
 
 class EncryptedJson(_EncryptedBase):
-    cache_ok = (
-        True  # have to re-declare because _is_json value is different from parent
-    )
+    cache_ok = True
     _is_json: bool = True
 
     def process_bind_param(

From 66023dbb6dab50de43b95af23c9e447072ab0026 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:48:56 -0700
Subject: [PATCH 224/267] feat(llm-provider): fetch litellm models (#8418)

---
 backend/onyx/db/llm.py                        |  18 +-
 backend/onyx/server/manage/llm/api.py         | 260 +++++++++++-----
 backend/onyx/server/manage/llm/models.py      |  29 ++
 backend/tests/unit/onyx/db/test_llm_sync.py   |  73 ++---
 .../manage/llm/test_fetch_models_api.py       | 286 +++++++++++++++++-
 5 files changed, 542 insertions(+), 124 deletions(-)

diff --git a/backend/onyx/db/llm.py b/backend/onyx/db/llm.py
index 046bf381d7d..151504f7104 100644
--- a/backend/onyx/db/llm.py
+++ b/backend/onyx/db/llm.py
@@ -25,6 +25,7 @@
 from onyx.server.manage.embedding.models import CloudEmbeddingProviderCreationRequest
 from onyx.server.manage.llm.models import LLMProviderUpsertRequest
 from onyx.server.manage.llm.models import LLMProviderView
+from onyx.server.manage.llm.models import SyncModelEntry
 from onyx.utils.logger import setup_logger
 from shared_configs.enums import EmbeddingProvider
 
@@ -369,9 +370,9 @@ def upsert_llm_provider(
 def sync_model_configurations(
     db_session: Session,
     provider_name: str,
-    models: list[dict],
+    models: list[SyncModelEntry],
 ) -> int:
-    """Sync model configurations for a dynamic provider (OpenRouter, Bedrock, Ollama).
+    """Sync model configurations for a dynamic provider (OpenRouter, Bedrock, Ollama, etc.).
 
     This inserts NEW models from the source API without overwriting existing ones.
     User preferences (is_visible, max_input_tokens) are preserved for existing models.
@@ -379,7 +380,7 @@ def sync_model_configurations(
     Args:
         db_session: Database session
         provider_name: Name of the LLM provider
-        models: List of model dicts with keys: name, display_name, max_input_tokens, supports_image_input
+        models: List of SyncModelEntry objects describing the fetched models
 
     Returns:
         Number of new models added
@@ -393,21 +394,20 @@ def sync_model_configurations(
 
     new_count = 0
     for model in models:
-        model_name = model["name"]
-        if model_name not in existing_names:
+        if model.name not in existing_names:
             # Insert new model with is_visible=False (user must explicitly enable)
             supported_flows = [LLMModelFlowType.CHAT]
-            if model.get("supports_image_input", False):
+            if model.supports_image_input:
                 supported_flows.append(LLMModelFlowType.VISION)
 
             insert_new_model_configuration__no_commit(
                 db_session=db_session,
                 llm_provider_id=provider.id,
-                model_name=model_name,
+                model_name=model.name,
                 supported_flows=supported_flows,
                 is_visible=False,
-                max_input_tokens=model.get("max_input_tokens"),
-                display_name=model.get("display_name"),
+                max_input_tokens=model.max_input_tokens,
+                display_name=model.display_name,
             )
             new_count += 1
 
diff --git a/backend/onyx/server/manage/llm/api.py b/backend/onyx/server/manage/llm/api.py
index 0bb8c427b75..693826c844d 100644
--- a/backend/onyx/server/manage/llm/api.py
+++ b/backend/onyx/server/manage/llm/api.py
@@ -58,6 +58,9 @@
 from onyx.server.manage.llm.models import BedrockFinalModelResponse
 from onyx.server.manage.llm.models import BedrockModelsRequest
 from onyx.server.manage.llm.models import DefaultModel
+from onyx.server.manage.llm.models import LitellmFinalModelResponse
+from onyx.server.manage.llm.models import LitellmModelDetails
+from onyx.server.manage.llm.models import LitellmModelsRequest
 from onyx.server.manage.llm.models import LLMCost
 from onyx.server.manage.llm.models import LLMProviderDescriptor
 from onyx.server.manage.llm.models import LLMProviderResponse
@@ -72,6 +75,7 @@
 from onyx.server.manage.llm.models import OpenRouterFinalModelResponse
 from onyx.server.manage.llm.models import OpenRouterModelDetails
 from onyx.server.manage.llm.models import OpenRouterModelsRequest
+from onyx.server.manage.llm.models import SyncModelEntry
 from onyx.server.manage.llm.models import TestLLMRequest
 from onyx.server.manage.llm.models import VisionProviderResponse
 from onyx.server.manage.llm.utils import generate_bedrock_display_name
@@ -98,6 +102,34 @@ def _mask_string(value: str) -> str:
     return value[:4] + "****" + value[-4:]
 
 
+def _sync_fetched_models(
+    db_session: Session,
+    provider_name: str,
+    models: list[SyncModelEntry],
+    source_label: str,
+) -> None:
+    """Sync fetched models to DB for the given provider.
+
+    Args:
+        db_session: Database session
+        provider_name: Name of the LLM provider
+        models: List of SyncModelEntry objects describing the fetched models
+        source_label: Human-readable label for log messages (e.g. "Bedrock", "LiteLLM")
+    """
+    try:
+        new_count = sync_model_configurations(
+            db_session=db_session,
+            provider_name=provider_name,
+            models=models,
+        )
+        if new_count > 0:
+            logger.info(
+                f"Added {new_count} new {source_label} models to provider '{provider_name}'"
+            )
+    except ValueError as e:
+        logger.warning(f"Failed to sync {source_label} models to DB: {e}")
+
+
 # Keys in custom_config that contain sensitive credentials
 _SENSITIVE_CONFIG_KEYS = {
     "vertex_credentials",
@@ -963,27 +995,20 @@ def get_bedrock_available_models(
 
         # Sync new models to DB if provider_name is specified
         if request.provider_name:
-            try:
-                models_to_sync = [
-                    {
-                        "name": r.name,
-                        "display_name": r.display_name,
-                        "max_input_tokens": r.max_input_tokens,
-                        "supports_image_input": r.supports_image_input,
-                    }
-                    for r in results
-                ]
-                new_count = sync_model_configurations(
-                    db_session=db_session,
-                    provider_name=request.provider_name,
-                    models=models_to_sync,
-                )
-                if new_count > 0:
-                    logger.info(
-                        f"Added {new_count} new Bedrock models to provider '{request.provider_name}'"
+            _sync_fetched_models(
+                db_session=db_session,
+                provider_name=request.provider_name,
+                models=[
+                    SyncModelEntry(
+                        name=r.name,
+                        display_name=r.display_name,
+                        max_input_tokens=r.max_input_tokens,
+                        supports_image_input=r.supports_image_input,
                     )
-            except ValueError as e:
-                logger.warning(f"Failed to sync Bedrock models to DB: {e}")
+                    for r in results
+                ],
+                source_label="Bedrock",
+            )
 
         return results
 
@@ -1101,27 +1126,20 @@ def get_ollama_available_models(
 
     # Sync new models to DB if provider_name is specified
     if request.provider_name:
-        try:
-            models_to_sync = [
-                {
-                    "name": r.name,
-                    "display_name": r.display_name,
-                    "max_input_tokens": r.max_input_tokens,
-                    "supports_image_input": r.supports_image_input,
-                }
-                for r in sorted_results
-            ]
-            new_count = sync_model_configurations(
-                db_session=db_session,
-                provider_name=request.provider_name,
-                models=models_to_sync,
-            )
-            if new_count > 0:
-                logger.info(
-                    f"Added {new_count} new Ollama models to provider '{request.provider_name}'"
+        _sync_fetched_models(
+            db_session=db_session,
+            provider_name=request.provider_name,
+            models=[
+                SyncModelEntry(
+                    name=r.name,
+                    display_name=r.display_name,
+                    max_input_tokens=r.max_input_tokens,
+                    supports_image_input=r.supports_image_input,
                 )
-        except ValueError as e:
-            logger.warning(f"Failed to sync Ollama models to DB: {e}")
+                for r in sorted_results
+            ],
+            source_label="Ollama",
+        )
 
     return sorted_results
 
@@ -1210,27 +1228,20 @@ def get_openrouter_available_models(
 
     # Sync new models to DB if provider_name is specified
     if request.provider_name:
-        try:
-            models_to_sync = [
-                {
-                    "name": r.name,
-                    "display_name": r.display_name,
-                    "max_input_tokens": r.max_input_tokens,
-                    "supports_image_input": r.supports_image_input,
-                }
-                for r in sorted_results
-            ]
-            new_count = sync_model_configurations(
-                db_session=db_session,
-                provider_name=request.provider_name,
-                models=models_to_sync,
-            )
-            if new_count > 0:
-                logger.info(
-                    f"Added {new_count} new OpenRouter models to provider '{request.provider_name}'"
+        _sync_fetched_models(
+            db_session=db_session,
+            provider_name=request.provider_name,
+            models=[
+                SyncModelEntry(
+                    name=r.name,
+                    display_name=r.display_name,
+                    max_input_tokens=r.max_input_tokens,
+                    supports_image_input=r.supports_image_input,
                 )
-        except ValueError as e:
-            logger.warning(f"Failed to sync OpenRouter models to DB: {e}")
+                for r in sorted_results
+            ],
+            source_label="OpenRouter",
+        )
 
     return sorted_results
 
@@ -1324,26 +1335,119 @@ def get_lm_studio_available_models(
 
     # Sync new models to DB if provider_name is specified
     if request.provider_name:
-        try:
-            models_to_sync = [
-                {
-                    "name": r.name,
-                    "display_name": r.display_name,
-                    "max_input_tokens": r.max_input_tokens,
-                    "supports_image_input": r.supports_image_input,
-                }
+        _sync_fetched_models(
+            db_session=db_session,
+            provider_name=request.provider_name,
+            models=[
+                SyncModelEntry(
+                    name=r.name,
+                    display_name=r.display_name,
+                    max_input_tokens=r.max_input_tokens,
+                    supports_image_input=r.supports_image_input,
+                )
                 for r in sorted_results
-            ]
-            new_count = sync_model_configurations(
-                db_session=db_session,
-                provider_name=request.provider_name,
-                models=models_to_sync,
+            ],
+            source_label="LM Studio",
+        )
+
+    return sorted_results
+
+
+@admin_router.post("/litellm/available-models")
+def get_litellm_available_models(
+    request: LitellmModelsRequest,
+    _: User = Depends(current_admin_user),
+    db_session: Session = Depends(get_session),
+) -> list[LitellmFinalModelResponse]:
+    """Fetch available models from Litellm proxy /v1/models endpoint."""
+    response_json = _get_litellm_models_response(
+        api_key=request.api_key, api_base=request.api_base
+    )
+
+    models = response_json.get("data", [])
+    if not isinstance(models, list) or len(models) == 0:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No models found from your Litellm endpoint",
+        )
+
+    results: list[LitellmFinalModelResponse] = []
+    for model in models:
+        try:
+            model_details = LitellmModelDetails.model_validate(model)
+
+            results.append(
+                LitellmFinalModelResponse(
+                    provider_name=model_details.owned_by,
+                    model_name=model_details.id,
+                )
+            )
+        except Exception as e:
+            logger.warning(
+                "Failed to parse Litellm model entry",
+                extra={"error": str(e), "item": str(model)[:1000]},
             )
-            if new_count > 0:
-                logger.info(
-                    f"Added {new_count} new LM Studio models to provider '{request.provider_name}'"
+
+    if not results:
+        raise OnyxError(
+            OnyxErrorCode.VALIDATION_ERROR,
+            "No compatible models found from Litellm",
+        )
+
+    sorted_results = sorted(results, key=lambda m: m.model_name.lower())
+
+    # Sync new models to DB if provider_name is specified
+    if request.provider_name:
+        _sync_fetched_models(
+            db_session=db_session,
+            provider_name=request.provider_name,
+            models=[
+                SyncModelEntry(
+                    name=r.model_name,
+                    display_name=r.model_name,
                 )
-        except ValueError as e:
-            logger.warning(f"Failed to sync LM Studio models to DB: {e}")
+                for r in sorted_results
+            ],
+            source_label="LiteLLM",
+        )
 
     return sorted_results
+
+
+def _get_litellm_models_response(api_key: str, api_base: str) -> dict:
+    """Perform GET to Litellm proxy /api/v1/models and return parsed JSON."""
+    cleaned_api_base = api_base.strip().rstrip("/")
+    url = f"{cleaned_api_base}/v1/models"
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "HTTP-Referer": "https://onyx.app",
+        "X-Title": "Onyx",
+    }
+
+    try:
+        response = httpx.get(url, headers=headers, timeout=10.0)
+        response.raise_for_status()
+        return response.json()
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 401:
+            raise OnyxError(
+                OnyxErrorCode.VALIDATION_ERROR,
+                "Authentication failed: invalid or missing API key for LiteLLM proxy.",
+            )
+        elif e.response.status_code == 404:
+            raise OnyxError(
+                OnyxErrorCode.VALIDATION_ERROR,
+                f"LiteLLM models endpoint not found at {url}. "
+                "Please verify the API base URL.",
+            )
+        else:
+            raise OnyxError(
+                OnyxErrorCode.BAD_GATEWAY,
+                f"Failed to fetch LiteLLM models: {e}",
+            )
+    except Exception as e:
+        raise OnyxError(
+            OnyxErrorCode.BAD_GATEWAY,
+            f"Failed to fetch LiteLLM models: {e}",
+        )
diff --git a/backend/onyx/server/manage/llm/models.py b/backend/onyx/server/manage/llm/models.py
index 2345f0337f4..cf92a72ee77 100644
--- a/backend/onyx/server/manage/llm/models.py
+++ b/backend/onyx/server/manage/llm/models.py
@@ -420,3 +420,32 @@ def from_models(
             default_text=default_text,
             default_vision=default_vision,
         )
+
+
+class SyncModelEntry(BaseModel):
+    """Typed model for syncing fetched models to the DB."""
+
+    name: str
+    display_name: str
+    max_input_tokens: int | None = None
+    supports_image_input: bool = False
+
+
+class LitellmModelsRequest(BaseModel):
+    api_key: str
+    api_base: str
+    provider_name: str | None = None  # Optional: to save models to existing provider
+
+
+class LitellmModelDetails(BaseModel):
+    """Response model for Litellm proxy /api/v1/models endpoint"""
+
+    id: str  # Model ID (e.g. "gpt-4o")
+    object: str  # "model"
+    created: int  # Unix timestamp in seconds
+    owned_by: str  # Provider name (e.g. "openai")
+
+
+class LitellmFinalModelResponse(BaseModel):
+    provider_name: str  # Provider name (e.g. "openai")
+    model_name: str  # Model ID (e.g. "gpt-4o")
diff --git a/backend/tests/unit/onyx/db/test_llm_sync.py b/backend/tests/unit/onyx/db/test_llm_sync.py
index a6ab8024a35..700b70ba9b0 100644
--- a/backend/tests/unit/onyx/db/test_llm_sync.py
+++ b/backend/tests/unit/onyx/db/test_llm_sync.py
@@ -7,6 +7,7 @@
 
 from onyx.db.llm import sync_model_configurations
 from onyx.llm.constants import LlmProviderNames
+from onyx.server.manage.llm.models import SyncModelEntry
 
 
 class TestSyncModelConfigurations:
@@ -25,18 +26,18 @@ def test_inserts_new_models(self) -> None:
             "onyx.db.llm.fetch_existing_llm_provider", return_value=mock_provider
         ):
             models = [
-                {
-                    "name": "gpt-4",
-                    "display_name": "GPT-4",
-                    "max_input_tokens": 128000,
-                    "supports_image_input": True,
-                },
-                {
-                    "name": "gpt-4o",
-                    "display_name": "GPT-4o",
-                    "max_input_tokens": 128000,
-                    "supports_image_input": True,
-                },
+                SyncModelEntry(
+                    name="gpt-4",
+                    display_name="GPT-4",
+                    max_input_tokens=128000,
+                    supports_image_input=True,
+                ),
+                SyncModelEntry(
+                    name="gpt-4o",
+                    display_name="GPT-4o",
+                    max_input_tokens=128000,
+                    supports_image_input=True,
+                ),
             ]
 
             result = sync_model_configurations(
@@ -67,18 +68,18 @@ def test_skips_existing_models(self) -> None:
             "onyx.db.llm.fetch_existing_llm_provider", return_value=mock_provider
         ):
             models = [
-                {
-                    "name": "gpt-4",  # Existing - should be skipped
-                    "display_name": "GPT-4",
-                    "max_input_tokens": 128000,
-                    "supports_image_input": True,
-                },
-                {
-                    "name": "gpt-4o",  # New - should be inserted
-                    "display_name": "GPT-4o",
-                    "max_input_tokens": 128000,
-                    "supports_image_input": True,
-                },
+                SyncModelEntry(
+                    name="gpt-4",  # Existing - should be skipped
+                    display_name="GPT-4",
+                    max_input_tokens=128000,
+                    supports_image_input=True,
+                ),
+                SyncModelEntry(
+                    name="gpt-4o",  # New - should be inserted
+                    display_name="GPT-4o",
+                    max_input_tokens=128000,
+                    supports_image_input=True,
+                ),
             ]
 
             result = sync_model_configurations(
@@ -105,12 +106,12 @@ def test_no_commit_when_no_new_models(self) -> None:
             "onyx.db.llm.fetch_existing_llm_provider", return_value=mock_provider
         ):
             models = [
-                {
-                    "name": "gpt-4",  # Already exists
-                    "display_name": "GPT-4",
-                    "max_input_tokens": 128000,
-                    "supports_image_input": True,
-                },
+                SyncModelEntry(
+                    name="gpt-4",  # Already exists
+                    display_name="GPT-4",
+                    max_input_tokens=128000,
+                    supports_image_input=True,
+                ),
             ]
 
             result = sync_model_configurations(
@@ -131,7 +132,7 @@ def test_raises_on_missing_provider(self) -> None:
                 sync_model_configurations(
                     db_session=mock_session,
                     provider_name="nonexistent",
-                    models=[{"name": "model", "display_name": "Model"}],
+                    models=[SyncModelEntry(name="model", display_name="Model")],
                 )
 
     def test_handles_missing_optional_fields(self) -> None:
@@ -145,12 +146,12 @@ def test_handles_missing_optional_fields(self) -> None:
         with patch(
             "onyx.db.llm.fetch_existing_llm_provider", return_value=mock_provider
         ):
-            # Model with only required fields
+            # Model with only required fields (max_input_tokens and supports_image_input default)
             models = [
-                {
-                    "name": "model-1",
-                    # No display_name, max_input_tokens, or supports_image_input
-                },
+                SyncModelEntry(
+                    name="model-1",
+                    display_name="Model 1",
+                ),
             ]
 
             result = sync_model_configurations(
diff --git a/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py b/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
index 614e164d469..d0f8fc42194 100644
--- a/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
+++ b/backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
@@ -1,15 +1,19 @@
 """Tests for LLM model fetch endpoints.
 
 These tests verify the full request/response flow for fetching models
-from dynamic providers (Ollama, OpenRouter), including the
+from dynamic providers (Ollama, OpenRouter, Litellm), including the
 sync-to-DB behavior when provider_name is specified.
 """
 
 from unittest.mock import MagicMock
 from unittest.mock import patch
 
+import httpx
 import pytest
 
+from onyx.error_handling.exceptions import OnyxError
+from onyx.server.manage.llm.models import LitellmFinalModelResponse
+from onyx.server.manage.llm.models import LitellmModelsRequest
 from onyx.server.manage.llm.models import LMStudioFinalModelResponse
 from onyx.server.manage.llm.models import LMStudioModelsRequest
 from onyx.server.manage.llm.models import OllamaFinalModelResponse
@@ -614,3 +618,283 @@ def test_raises_on_only_non_llm_models(self) -> None:
             request = LMStudioModelsRequest(api_base="http://localhost:1234")
             with pytest.raises(OnyxError):
                 get_lm_studio_available_models(request, MagicMock(), mock_session)
+
+
+class TestGetLitellmAvailableModels:
+    """Tests for the Litellm proxy model fetch endpoint."""
+
+    @pytest.fixture
+    def mock_litellm_response(self) -> dict:
+        """Mock response from Litellm /v1/models endpoint."""
+        return {
+            "data": [
+                {
+                    "id": "gpt-4o",
+                    "object": "model",
+                    "created": 1700000000,
+                    "owned_by": "openai",
+                },
+                {
+                    "id": "claude-3-5-sonnet",
+                    "object": "model",
+                    "created": 1700000001,
+                    "owned_by": "anthropic",
+                },
+                {
+                    "id": "gemini-pro",
+                    "object": "model",
+                    "created": 1700000002,
+                    "owned_by": "google",
+                },
+            ]
+        }
+
+    def test_returns_model_list(self, mock_litellm_response: dict) -> None:
+        """Test that endpoint returns properly formatted model list."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_litellm_response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            results = get_litellm_available_models(request, MagicMock(), mock_session)
+
+            assert len(results) == 3
+            assert all(isinstance(r, LitellmFinalModelResponse) for r in results)
+
+    def test_model_fields_parsed_correctly(self, mock_litellm_response: dict) -> None:
+        """Test that provider_name and model_name are correctly extracted."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_litellm_response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            results = get_litellm_available_models(request, MagicMock(), mock_session)
+
+            gpt = next(r for r in results if r.model_name == "gpt-4o")
+            assert gpt.provider_name == "openai"
+
+            claude = next(r for r in results if r.model_name == "claude-3-5-sonnet")
+            assert claude.provider_name == "anthropic"
+
+    def test_results_sorted_by_model_name(self, mock_litellm_response: dict) -> None:
+        """Test that results are alphabetically sorted by model_name."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_litellm_response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            results = get_litellm_available_models(request, MagicMock(), mock_session)
+
+            model_names = [r.model_name for r in results]
+            assert model_names == sorted(model_names, key=str.lower)
+
+    def test_empty_data_raises_onyx_error(self) -> None:
+        """Test that empty model list raises OnyxError."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = {"data": []}
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            with pytest.raises(OnyxError, match="No models found"):
+                get_litellm_available_models(request, MagicMock(), mock_session)
+
+    def test_missing_data_key_raises_onyx_error(self) -> None:
+        """Test that response without 'data' key raises OnyxError."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = {}
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            with pytest.raises(OnyxError):
+                get_litellm_available_models(request, MagicMock(), mock_session)
+
+    def test_skips_unparseable_entries(self) -> None:
+        """Test that malformed model entries are skipped without failing."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+        response_with_bad_entry = {
+            "data": [
+                {
+                    "id": "gpt-4o",
+                    "object": "model",
+                    "created": 1700000000,
+                    "owned_by": "openai",
+                },
+                # Missing required fields
+                {"bad_field": "bad_value"},
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response_with_bad_entry
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            results = get_litellm_available_models(request, MagicMock(), mock_session)
+
+            assert len(results) == 1
+            assert results[0].model_name == "gpt-4o"
+
+    def test_all_entries_unparseable_raises_onyx_error(self) -> None:
+        """Test that OnyxError is raised when all entries fail to parse."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+        response_all_bad = {
+            "data": [
+                {"bad_field": "bad_value"},
+                {"another_bad": 123},
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = response_all_bad
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            with pytest.raises(OnyxError, match="No compatible models"):
+                get_litellm_available_models(request, MagicMock(), mock_session)
+
+    def test_api_base_trailing_slash_handled(self) -> None:
+        """Test that trailing slashes in api_base are handled correctly."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+        mock_litellm_response = {
+            "data": [
+                {
+                    "id": "gpt-4o",
+                    "object": "model",
+                    "created": 1700000000,
+                    "owned_by": "openai",
+                },
+            ]
+        }
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.json.return_value = mock_litellm_response
+            mock_response.raise_for_status = MagicMock()
+            mock_get.return_value = mock_response
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000/",
+                api_key="test-key",
+            )
+            get_litellm_available_models(request, MagicMock(), mock_session)
+
+            # Should call /v1/models without double slashes
+            call_args = mock_get.call_args
+            assert call_args[0][0] == "http://localhost:4000/v1/models"
+
+    def test_connection_failure_raises_onyx_error(self) -> None:
+        """Test that connection failures are wrapped in OnyxError."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_get.side_effect = Exception("Connection refused")
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            with pytest.raises(OnyxError, match="Failed to fetch LiteLLM models"):
+                get_litellm_available_models(request, MagicMock(), mock_session)
+
+    def test_401_raises_authentication_error(self) -> None:
+        """Test that a 401 response raises OnyxError with authentication message."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.status_code = 401
+            mock_get.side_effect = httpx.HTTPStatusError(
+                "Unauthorized", request=MagicMock(), response=mock_response
+            )
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="bad-key",
+            )
+            with pytest.raises(OnyxError, match="Authentication failed"):
+                get_litellm_available_models(request, MagicMock(), mock_session)
+
+    def test_404_raises_not_found_error(self) -> None:
+        """Test that a 404 response raises OnyxError with endpoint not found message."""
+        from onyx.server.manage.llm.api import get_litellm_available_models
+
+        mock_session = MagicMock()
+
+        with patch("onyx.server.manage.llm.api.httpx.get") as mock_get:
+            mock_response = MagicMock()
+            mock_response.status_code = 404
+            mock_get.side_effect = httpx.HTTPStatusError(
+                "Not Found", request=MagicMock(), response=mock_response
+            )
+
+            request = LitellmModelsRequest(
+                api_base="http://localhost:4000",
+                api_key="test-key",
+            )
+            with pytest.raises(OnyxError, match="endpoint not found"):
+                get_litellm_available_models(request, MagicMock(), mock_session)

From ecbb267f805e5e49d446383bd94da5f341186f74 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Tue, 10 Mar 2026 17:42:39 -0700
Subject: [PATCH 225/267] fix: Consolidate search state-machine (#9234)

---
 web/src/app/nrf/NRFChrome.tsx                 |  10 +-
 web/src/app/nrf/NRFPage.tsx                   |   7 +-
 web/src/ee/providers/AppModeProvider.tsx      |  55 -------
 .../ee/providers/QueryControllerProvider.tsx  | 150 ++++++++++--------
 web/src/ee/sections/SearchCard.tsx            |   2 +-
 web/src/ee/sections/SearchUI.tsx              |  58 ++++---
 web/src/hooks/useAppFocus.ts                  |  41 +++--
 web/src/layouts/app-layouts.tsx               |  10 +-
 web/src/providers/AppModeProvider.tsx         |  23 ---
 web/src/providers/AppProvider.tsx             |  13 +-
 web/src/providers/QueryControllerProvider.tsx |  21 ++-
 web/src/refresh-pages/AppPage.tsx             |  19 +--
 web/src/sections/input/AppInputBar.tsx        |  12 +-
 web/src/sections/sidebar/AppSidebar.tsx       |   4 +-
 14 files changed, 189 insertions(+), 236 deletions(-)
 delete mode 100644 web/src/ee/providers/AppModeProvider.tsx
 delete mode 100644 web/src/providers/AppModeProvider.tsx

diff --git a/web/src/app/nrf/NRFChrome.tsx b/web/src/app/nrf/NRFChrome.tsx
index 02d995ab401..6422107aaa5 100644
--- a/web/src/app/nrf/NRFChrome.tsx
+++ b/web/src/app/nrf/NRFChrome.tsx
@@ -11,7 +11,7 @@ import { Button } from "@opal/components";
 import { SvgBubbleText, SvgSearchMenu, SvgSidebar } from "@opal/icons";
 import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
 import { useSettingsContext } from "@/providers/SettingsProvider";
-import { AppMode, useAppMode } from "@/providers/AppModeProvider";
+import type { AppMode } from "@/providers/QueryControllerProvider";
 import useAppFocus from "@/hooks/useAppFocus";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
@@ -58,15 +58,15 @@ const footerMarkdownComponents = {
  */
 export default function NRFChrome() {
   const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
-  const { appMode, setAppMode } = useAppMode();
+  const { state, setAppMode } = useQueryController();
   const settings = useSettingsContext();
   const { isMobile } = useScreenSize();
   const { setFolded } = useAppSidebarContext();
   const appFocus = useAppFocus();
-  const { classification } = useQueryController();
   const [modePopoverOpen, setModePopoverOpen] = useState(false);
 
-  const effectiveMode: AppMode = appFocus.isNewSession() ? appMode : "chat";
+  const effectiveMode: AppMode =
+    appFocus.isNewSession() && state.phase === "idle" ? state.appMode : "chat";
 
   const customFooterContent =
     settings?.enterpriseSettings?.custom_lower_disclaimer_content ||
@@ -78,7 +78,7 @@ export default function NRFChrome() {
     isPaidEnterpriseFeaturesEnabled &&
     settings.isSearchModeAvailable &&
     appFocus.isNewSession() &&
-    !classification;
+    state.phase === "idle";
 
   const showHeader = isMobile || showModeToggle;
 
diff --git a/web/src/app/nrf/NRFPage.tsx b/web/src/app/nrf/NRFPage.tsx
index 2678138f888..9492bb73bae 100644
--- a/web/src/app/nrf/NRFPage.tsx
+++ b/web/src/app/nrf/NRFPage.tsx
@@ -175,7 +175,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
   const isStreaming = currentChatState === "streaming";
 
   // Query controller for search/chat classification (EE feature)
-  const { submit: submitQuery, classification } = useQueryController();
+  const { submit: submitQuery, state } = useQueryController();
 
   // Determine if retrieval (search) is enabled based on the agent
   const retrievalEnabled = useMemo(() => {
@@ -186,7 +186,8 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
   }, [liveAgent]);
 
   // Check if we're in search mode
-  const isSearch = classification === "search";
+  const isSearch =
+    state.phase === "searching" || state.phase === "search-results";
 
   // Anchor for scroll positioning (matches ChatPage pattern)
   const anchorMessage = messageHistory.at(-2) ?? messageHistory[0];
@@ -317,7 +318,7 @@ export default function NRFPage({ isSidePanel = false }: NRFPageProps) {
       };
 
       // Use submitQuery which will classify the query and either:
-      // - Route to search (sets classification to "search" and shows SearchUI)
+      // - Route to search (sets phase to "searching"/"search-results" and shows SearchUI)
       // - Route to chat (calls onChat callback)
       await submitQuery(submittedMessage, onChat);
     },
diff --git a/web/src/ee/providers/AppModeProvider.tsx b/web/src/ee/providers/AppModeProvider.tsx
deleted file mode 100644
index 75a4026c455..00000000000
--- a/web/src/ee/providers/AppModeProvider.tsx
+++ /dev/null
@@ -1,55 +0,0 @@
-"use client";
-
-import React, { useState, useCallback, useEffect } from "react";
-import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
-import { AppModeContext, AppMode } from "@/providers/AppModeProvider";
-import { useUser } from "@/providers/UserProvider";
-import { useSettingsContext } from "@/providers/SettingsProvider";
-
-export interface AppModeProviderProps {
-  children: React.ReactNode;
-}
-
-/**
- * Provider for application mode (Search/Chat).
- *
- * This controls how user queries are handled:
- * - **search**: Forces search mode - quick document lookup
- * - **chat**: Forces chat mode - conversation with follow-up questions
- *
- * The initial mode is read from the user's persisted `default_app_mode` preference.
- * When search mode is unavailable (admin setting or no connectors), the mode is locked to "chat".
- */
-export function AppModeProvider({ children }: AppModeProviderProps) {
-  const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
-  const { user } = useUser();
-  const { isSearchModeAvailable } = useSettingsContext();
-
-  const persistedMode = user?.preferences?.default_app_mode;
-  const [appMode, setAppModeState] = useState<AppMode>("chat");
-
-  useEffect(() => {
-    if (!isPaidEnterpriseFeaturesEnabled || !isSearchModeAvailable) {
-      setAppModeState("chat");
-      return;
-    }
-
-    if (persistedMode) {
-      setAppModeState(persistedMode.toLowerCase() as AppMode);
-    }
-  }, [isPaidEnterpriseFeaturesEnabled, isSearchModeAvailable, persistedMode]);
-
-  const setAppMode = useCallback(
-    (mode: AppMode) => {
-      if (!isPaidEnterpriseFeaturesEnabled || !isSearchModeAvailable) return;
-      setAppModeState(mode);
-    },
-    [isPaidEnterpriseFeaturesEnabled, isSearchModeAvailable]
-  );
-
-  return (
-    <AppModeContext.Provider value={{ appMode, setAppMode }}>
-      {children}
-    </AppModeContext.Provider>
-  );
-}
diff --git a/web/src/ee/providers/QueryControllerProvider.tsx b/web/src/ee/providers/QueryControllerProvider.tsx
index d858a5c3235..53760e2fd15 100644
--- a/web/src/ee/providers/QueryControllerProvider.tsx
+++ b/web/src/ee/providers/QueryControllerProvider.tsx
@@ -8,14 +8,15 @@ import {
   SearchFullResponse,
 } from "@/lib/search/interfaces";
 import { classifyQuery, searchDocuments } from "@/ee/lib/search/svc";
-import { useAppMode } from "@/providers/AppModeProvider";
 import useAppFocus from "@/hooks/useAppFocus";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import { useSettingsContext } from "@/providers/SettingsProvider";
+import { useUser } from "@/providers/UserProvider";
 import {
   QueryControllerContext,
-  QueryClassification,
   QueryControllerValue,
+  QueryState,
+  AppMode,
 } from "@/providers/QueryControllerProvider";
 
 interface QueryControllerProviderProps {
@@ -25,19 +26,53 @@ interface QueryControllerProviderProps {
 export function QueryControllerProvider({
   children,
 }: QueryControllerProviderProps) {
-  const { appMode, setAppMode } = useAppMode();
   const appFocus = useAppFocus();
   const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
   const settings = useSettingsContext();
   const { isSearchModeAvailable: searchUiEnabled } = settings;
+  const { user } = useUser();
 
-  // Query state
-  const [query, setQuery] = useState<string | null>(null);
-  const [classification, setClassification] =
-    useState<QueryClassification>(null);
-  const [isClassifying, setIsClassifying] = useState(false);
+  // ── Merged query state (discriminated union) ──────────────────────────
+  const [state, setState] = useState<QueryState>({
+    phase: "idle",
+    appMode: "chat",
+  });
+
+  // Persistent app-mode preference — survives phase transitions and is
+  // used to restore the correct mode when resetting back to idle.
+  const appModeRef = useRef<AppMode>("chat");
+
+  // ── App mode sync from user preferences ───────────────────────────────
+  const persistedMode = user?.preferences?.default_app_mode;
+
+  useEffect(() => {
+    let mode: AppMode = "chat";
+    if (isPaidEnterpriseFeaturesEnabled && searchUiEnabled && persistedMode) {
+      const lower = persistedMode.toLowerCase();
+      mode = (["auto", "search", "chat"] as const).includes(lower as AppMode)
+        ? (lower as AppMode)
+        : "chat";
+    }
+    appModeRef.current = mode;
+    setState((prev) =>
+      prev.phase === "idle" ? { phase: "idle", appMode: mode } : prev
+    );
+  }, [isPaidEnterpriseFeaturesEnabled, searchUiEnabled, persistedMode]);
 
-  // Search state
+  const setAppMode = useCallback(
+    (mode: AppMode) => {
+      if (!isPaidEnterpriseFeaturesEnabled || !searchUiEnabled) return;
+      setState((prev) => {
+        if (prev.phase !== "idle") return prev;
+        appModeRef.current = mode;
+        return { phase: "idle", appMode: mode };
+      });
+    },
+    [isPaidEnterpriseFeaturesEnabled, searchUiEnabled]
+  );
+
+  // ── Ancillary state ───────────────────────────────────────────────────
+  const [query, setQuery] = useState<string | null>(null);
   const [searchResults, setSearchResults] = useState<SearchDocWithContent[]>(
     []
   );
@@ -51,7 +86,7 @@ export function QueryControllerProvider({
   const searchAbortRef = useRef<AbortController | null>(null);
 
   /**
-   * Perform document search
+   * Perform document search (pure data-fetching, no phase side effects)
    */
   const performSearch = useCallback(
     async (searchQuery: string, filters?: BaseFilters): Promise<void> => {
@@ -85,19 +120,15 @@ export function QueryControllerProvider({
         setLlmSelectedDocIds(response.llm_selected_doc_ids ?? null);
       } catch (err) {
         if (err instanceof Error && err.name === "AbortError") {
-          return;
+          throw err;
         }
 
         setError("Document search failed. Please try again.");
         setSearchResults([]);
         setLlmSelectedDocIds(null);
-      } finally {
-        // After we've performed a search, we automatically switch to "search" mode.
-        // This is a "sticky" implementation; on purpose.
-        setAppMode("search");
       }
     },
-    [setAppMode]
+    []
   );
 
   /**
@@ -112,8 +143,6 @@ export function QueryControllerProvider({
       const controller = new AbortController();
       classifyAbortRef.current = controller;
 
-      setIsClassifying(true);
-
       try {
         const response: SearchFlowClassificationResponse = await classifyQuery(
           classifyQueryText,
@@ -129,8 +158,6 @@ export function QueryControllerProvider({
 
         setError("Query classification failed. Falling back to chat.");
         return "chat";
-      } finally {
-        setIsClassifying(false);
       }
     },
     []
@@ -148,62 +175,51 @@ export function QueryControllerProvider({
       setQuery(submitQuery);
       setError(null);
 
-      // 1.
-      // We always route through chat if we're not Enterprise Enabled.
-      //
-      // 2.
-      // We always route through chat if the admin has disabled the Search UI.
-      //
-      // 3.
-      // We only go down the classification route if we're in the "New Session" tab.
-      // Everywhere else, we always use the chat-flow.
-      //
-      // 4.
-      // If we're in the "New Session" tab and the app-mode is "Chat", we continue with the chat-flow anyways.
+      const currentAppMode = appModeRef.current;
+
+      // Always route through chat if:
+      // 1. Not Enterprise Enabled
+      // 2. Admin has disabled the Search UI
+      // 3. Not in the "New Session" tab
+      // 4. In "New Session" tab but app-mode is "Chat"
       if (
         !isPaidEnterpriseFeaturesEnabled ||
         !searchUiEnabled ||
         !appFocus.isNewSession() ||
-        appMode === "chat"
+        currentAppMode === "chat"
       ) {
-        setClassification("chat");
+        setState({ phase: "chat" });
         setSearchResults([]);
         setLlmSelectedDocIds(null);
         onChat(submitQuery);
         return;
       }
 
-      if (appMode === "search") {
-        await performSearch(submitQuery, filters);
-        setClassification("search");
+      // Search mode: immediately show SearchUI with loading state
+      if (currentAppMode === "search") {
+        setState({ phase: "searching" });
+        try {
+          await performSearch(submitQuery, filters);
+        } catch (err) {
+          if (err instanceof Error && err.name === "AbortError") return;
+          throw err;
+        }
+        setState({ phase: "search-results" });
         return;
       }
 
-      // # Note (@raunakab)
-      //
-      // Interestingly enough, for search, we do:
-      // 1. setClassification("search")
-      // 2. performSearch
-      //
-      // But for chat, we do:
-      // 1. performChat
-      // 2. setClassification("chat")
-      //
-      // The ChatUI has a nice loading UI, so it's fine for us to prematurely set the
-      // classification-state before the chat has finished loading.
-      //
-      // However, the SearchUI does not. Prematurely setting the classification-state
-      // will lead to a slightly ugly UI.
-
       // Auto mode: classify first, then route
+      setState({ phase: "classifying" });
       try {
         const result = await performClassification(submitQuery);
 
         if (result === "search") {
+          setState({ phase: "searching" });
           await performSearch(submitQuery, filters);
-          setClassification("search");
+          setState({ phase: "search-results" });
+          appModeRef.current = "search";
         } else {
-          setClassification("chat");
+          setState({ phase: "chat" });
           setSearchResults([]);
           setLlmSelectedDocIds(null);
           onChat(submitQuery);
@@ -213,14 +229,13 @@ export function QueryControllerProvider({
           return;
         }
 
-        setClassification("chat");
+        setState({ phase: "chat" });
         setSearchResults([]);
         setLlmSelectedDocIds(null);
         onChat(submitQuery);
       }
     },
     [
-      appMode,
       appFocus,
       performClassification,
       performSearch,
@@ -235,7 +250,14 @@ export function QueryControllerProvider({
   const refineSearch = useCallback(
     async (filters: BaseFilters): Promise<void> => {
       if (!query) return;
-      await performSearch(query, filters);
+      setState({ phase: "searching" });
+      try {
+        await performSearch(query, filters);
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        throw err;
+      }
+      setState({ phase: "search-results" });
     },
     [query, performSearch]
   );
@@ -254,7 +276,7 @@ export function QueryControllerProvider({
     }
 
     setQuery(null);
-    setClassification(null);
+    setState({ phase: "idle", appMode: appModeRef.current });
     setSearchResults([]);
     setLlmSelectedDocIds(null);
     setError(null);
@@ -262,8 +284,8 @@ export function QueryControllerProvider({
 
   const value: QueryControllerValue = useMemo(
     () => ({
-      classification,
-      isClassifying,
+      state,
+      setAppMode,
       searchResults,
       llmSelectedDocIds,
       error,
@@ -272,8 +294,8 @@ export function QueryControllerProvider({
       reset,
     }),
     [
-      classification,
-      isClassifying,
+      state,
+      setAppMode,
       searchResults,
       llmSelectedDocIds,
       error,
@@ -283,7 +305,7 @@ export function QueryControllerProvider({
     ]
   );
 
-  // Sync classification state with navigation context
+  // Sync state with navigation context
   useEffect(reset, [appFocus, reset]);
 
   return (
diff --git a/web/src/ee/sections/SearchCard.tsx b/web/src/ee/sections/SearchCard.tsx
index 0aae1dfbf5d..65d2f084f61 100644
--- a/web/src/ee/sections/SearchCard.tsx
+++ b/web/src/ee/sections/SearchCard.tsx
@@ -56,7 +56,7 @@ export default function SearchCard({
 
   return (
     <Interactive.Stateless onClick={handleClick} prominence="secondary">
-      <Interactive.Container heightVariant="fit">
+      <Interactive.Container heightVariant="fit" widthVariant="full">
         <Section alignItems="start" gap={0} padding={0.25}>
           {/* Title Row */}
           <Section
diff --git a/web/src/ee/sections/SearchUI.tsx b/web/src/ee/sections/SearchUI.tsx
index 6a7e478ec55..77846ecc405 100644
--- a/web/src/ee/sections/SearchUI.tsx
+++ b/web/src/ee/sections/SearchUI.tsx
@@ -18,16 +18,17 @@ import { getTimeFilterDate, TimeFilter } from "@/lib/time";
 import useTags from "@/hooks/useTags";
 import { SourceIcon } from "@/components/SourceIcon";
 import Text from "@/refresh-components/texts/Text";
-import LineItem from "@/refresh-components/buttons/LineItem";
 import { Section } from "@/layouts/general-layouts";
 import Popover, { PopoverMenu } from "@/refresh-components/Popover";
 import { SvgCheck, SvgClock, SvgTag } from "@opal/icons";
 import FilterButton from "@/refresh-components/buttons/FilterButton";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useFilter from "@/hooks/useFilter";
+import { LineItemButton } from "@opal/components";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import { cn } from "@/lib/utils";
 import { toast } from "@/hooks/useToast";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 
 // ============================================================================
 // Types
@@ -51,22 +52,17 @@ const TIME_FILTER_OPTIONS: { value: TimeFilter; label: string }[] = [
   { value: "year", label: "Past year" },
 ];
 
-// ============================================================================
-// SearchResults Component (default export)
-// ============================================================================
-
-/**
- * Component for displaying search results with source filter sidebar.
- */
 export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
   // Available tags from backend
   const { tags: availableTags } = useTags();
   const {
+    state,
     searchResults: results,
     llmSelectedDocIds,
     error,
     refineSearch: onRefineSearch,
   } = useQueryController();
+
   const prevErrorRef = useRef<string | null>(null);
 
   // Show a toast notification when a new error occurs
@@ -197,6 +193,15 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
 
   const showEmpty = !error && results.length === 0;
 
+  // Show a centered spinner while search is in-flight (after all hooks)
+  if (state.phase === "searching") {
+    return (
+      <div className="flex-1 min-h-0 w-full flex items-center justify-center">
+        <SimpleLoader />
+      </div>
+    );
+  }
+
   return (
     <div className="flex-1 min-h-0 w-full flex flex-col gap-3">
       {/* ── Top row: Filters + Result count ── */}
@@ -226,18 +231,19 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
               <Popover.Content align="start" width="md">
                 <PopoverMenu>
                   {TIME_FILTER_OPTIONS.map((opt) => (
-                    <LineItem
+                    <LineItemButton
                       key={opt.value}
                       onClick={() => {
                         setTimeFilter(opt.value);
                         setTimeFilterOpen(false);
                         onRefineSearch(buildFilters({ time: opt.value }));
                       }}
-                      selected={timeFilter === opt.value}
+                      state={timeFilter === opt.value ? "selected" : "empty"}
                       icon={timeFilter === opt.value ? SvgCheck : SvgClock}
-                    >
-                      {opt.label}
-                    </LineItem>
+                      title={opt.label}
+                      sizePreset="main-ui"
+                      variant="section"
+                    />
                   ))}
                 </PopoverMenu>
               </Popover.Content>
@@ -278,7 +284,7 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
                         t.tag_value === tag.tag_value
                     );
                     return (
-                      <LineItem
+                      <LineItemButton
                         key={`${tag.tag_key}=${tag.tag_value}`}
                         onClick={() => {
                           const next = isSelected
@@ -291,11 +297,12 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
                           setSelectedTags(next);
                           onRefineSearch(buildFilters({ tags: next }));
                         }}
-                        selected={isSelected}
+                        state={isSelected ? "selected" : "empty"}
                         icon={isSelected ? SvgCheck : SvgTag}
-                      >
-                        {tag.tag_value}
-                      </LineItem>
+                        title={tag.tag_value}
+                        sizePreset="main-ui"
+                        variant="section"
+                      />
                     );
                   })}
                 </PopoverMenu>
@@ -357,7 +364,7 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
           <div className="flex-1 min-h-0 overflow-y-auto flex flex-col gap-4 px-1">
             <Section gap={0.25} height="fit">
               {sourcesWithMeta.map(({ source, meta, count }) => (
-                <LineItem
+                <LineItemButton
                   key={source}
                   icon={(props) => (
                     <SourceIcon
@@ -367,12 +374,15 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
                     />
                   )}
                   onClick={() => handleSourceToggle(source)}
-                  selected={selectedSources.includes(source)}
-                  emphasized
+                  state={
+                    selectedSources.includes(source) ? "selected" : "empty"
+                  }
+                  title={meta.displayName}
+                  selectVariant="select-heavy"
+                  sizePreset="main-ui"
+                  variant="section"
                   rightChildren={<Text text03>{count}</Text>}
-                >
-                  {meta.displayName}
-                </LineItem>
+                />
               ))}
             </Section>
           </div>
diff --git a/web/src/hooks/useAppFocus.ts b/web/src/hooks/useAppFocus.ts
index d403c770445..2eb4b229aaa 100644
--- a/web/src/hooks/useAppFocus.ts
+++ b/web/src/hooks/useAppFocus.ts
@@ -5,6 +5,7 @@
 //
 // This is useful in determining what `SidebarTab` should be active, for example.
 
+import { useMemo } from "react";
 import { SEARCH_PARAM_NAMES } from "@/app/app/services/searchParams";
 import { usePathname, useSearchParams } from "next/navigation";
 
@@ -66,31 +67,25 @@ export default function useAppFocus(): AppFocus {
   const pathname = usePathname();
   const searchParams = useSearchParams();
 
-  // Check if we're viewing a shared chat
-  if (pathname.startsWith("/app/shared/")) {
-    return new AppFocus("shared-chat");
-  }
-
-  // Check if we're on the user settings page
-  if (pathname.startsWith("/app/settings")) {
-    return new AppFocus("user-settings");
-  }
-
-  // Check if we're on the agents page
-  if (pathname.startsWith("/app/agents")) {
-    return new AppFocus("more-agents");
-  }
-
-  // Check search params for chat, agent, or project
   const chatId = searchParams.get(SEARCH_PARAM_NAMES.CHAT_ID);
-  if (chatId) return new AppFocus({ type: "chat", id: chatId });
-
   const agentId = searchParams.get(SEARCH_PARAM_NAMES.PERSONA_ID);
-  if (agentId) return new AppFocus({ type: "agent", id: agentId });
-
   const projectId = searchParams.get(SEARCH_PARAM_NAMES.PROJECT_ID);
-  if (projectId) return new AppFocus({ type: "project", id: projectId });
 
-  // No search params means we're on a new session
-  return new AppFocus("new-session");
+  // Memoize on the values that determine which AppFocus is constructed.
+  // AppFocus is immutable, so same inputs → same instance.
+  return useMemo(() => {
+    if (pathname.startsWith("/app/shared/")) {
+      return new AppFocus("shared-chat");
+    }
+    if (pathname.startsWith("/app/settings")) {
+      return new AppFocus("user-settings");
+    }
+    if (pathname.startsWith("/app/agents")) {
+      return new AppFocus("more-agents");
+    }
+    if (chatId) return new AppFocus({ type: "chat", id: chatId });
+    if (agentId) return new AppFocus({ type: "agent", id: agentId });
+    if (projectId) return new AppFocus({ type: "project", id: projectId });
+    return new AppFocus("new-session");
+  }, [pathname, chatId, agentId, projectId]);
 }
diff --git a/web/src/layouts/app-layouts.tsx b/web/src/layouts/app-layouts.tsx
index 3ec6c9eb364..a26953fcf46 100644
--- a/web/src/layouts/app-layouts.tsx
+++ b/web/src/layouts/app-layouts.tsx
@@ -60,7 +60,7 @@ import {
 } from "@opal/icons";
 import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
 import { useSettingsContext } from "@/providers/SettingsProvider";
-import { AppMode, useAppMode } from "@/providers/AppModeProvider";
+import type { AppMode } from "@/providers/QueryControllerProvider";
 import useAppFocus from "@/hooks/useAppFocus";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
@@ -82,7 +82,7 @@ import useBrowserInfo from "@/hooks/useBrowserInfo";
  */
 function Header() {
   const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
-  const { appMode, setAppMode } = useAppMode();
+  const { state, setAppMode } = useQueryController();
   const settings = useSettingsContext();
   const { isMobile } = useScreenSize();
   const { setFolded } = useAppSidebarContext();
@@ -108,7 +108,6 @@ function Header() {
     useChatSessions();
   const router = useRouter();
   const appFocus = useAppFocus();
-  const { classification } = useQueryController();
 
   const customHeaderContent =
     settings?.enterpriseSettings?.custom_header_content;
@@ -117,7 +116,8 @@ function Header() {
   // without this content still use.
   const pageWithHeaderContent = appFocus.isChat() || appFocus.isNewSession();
 
-  const effectiveMode: AppMode = appFocus.isNewSession() ? appMode : "chat";
+  const effectiveMode: AppMode =
+    appFocus.isNewSession() && state.phase === "idle" ? state.appMode : "chat";
 
   const availableProjects = useMemo(() => {
     if (!projects) return [];
@@ -323,7 +323,7 @@ function Header() {
           {isPaidEnterpriseFeaturesEnabled &&
             settings.isSearchModeAvailable &&
             appFocus.isNewSession() &&
-            !classification && (
+            state.phase === "idle" && (
               <Popover open={modePopoverOpen} onOpenChange={setModePopoverOpen}>
                 <Popover.Trigger asChild>
                   <OpenButton
diff --git a/web/src/providers/AppModeProvider.tsx b/web/src/providers/AppModeProvider.tsx
deleted file mode 100644
index 461e49b8abc..00000000000
--- a/web/src/providers/AppModeProvider.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-"use client";
-
-import { createContext, useContext } from "react";
-import { eeGated } from "@/ce";
-import { AppModeProvider as EEAppModeProvider } from "@/ee/providers/AppModeProvider";
-
-export type AppMode = "auto" | "search" | "chat";
-
-interface AppModeContextValue {
-  appMode: AppMode;
-  setAppMode: (mode: AppMode) => void;
-}
-
-export const AppModeContext = createContext<AppModeContextValue>({
-  appMode: "chat",
-  setAppMode: () => undefined,
-});
-
-export function useAppMode(): AppModeContextValue {
-  return useContext(AppModeContext);
-}
-
-export const AppModeProvider = eeGated(EEAppModeProvider);
diff --git a/web/src/providers/AppProvider.tsx b/web/src/providers/AppProvider.tsx
index 2d47ef05d73..17de7f7050e 100644
--- a/web/src/providers/AppProvider.tsx
+++ b/web/src/providers/AppProvider.tsx
@@ -24,7 +24,7 @@
  * 4. **ProviderContextProvider** - LLM provider configuration
  * 5. **ModalProvider** - Global modal state management
  * 6. **AppSidebarProvider** - Sidebar open/closed state
- * 7. **AppModeProvider** - Search/Chat mode selection
+ * 7. **QueryControllerProvider** - Search/Chat mode + query lifecycle
  *
  * ## Usage
  *
@@ -40,7 +40,7 @@
  * - `useSettingsContext()` - from SettingsProvider
  * - `useUser()` - from UserProvider
  * - `useAppBackground()` - from AppBackgroundProvider
- * - `useAppMode()` - from AppModeProvider
+ * - `useQueryController()` - from QueryControllerProvider (includes appMode)
  * - etc.
  *
  * @TODO(@raunakab): The providers wrapped by this component are currently
@@ -65,7 +65,6 @@ import { User } from "@/lib/types";
 import { ModalProvider } from "@/components/context/ModalContext";
 import { AuthTypeMetadata } from "@/lib/userSS";
 import { AppSidebarProvider } from "@/providers/AppSidebarProvider";
-import { AppModeProvider } from "@/providers/AppModeProvider";
 import { AppBackgroundProvider } from "@/providers/AppBackgroundProvider";
 import { QueryControllerProvider } from "@/providers/QueryControllerProvider";
 import ToastProvider from "@/providers/ToastProvider";
@@ -96,11 +95,9 @@ export default function AppProvider({
           <ProviderContextProvider>
             <ModalProvider user={user}>
               <AppSidebarProvider folded={!!folded}>
-                <AppModeProvider>
-                  <QueryControllerProvider>
-                    <ToastProvider>{children}</ToastProvider>
-                  </QueryControllerProvider>
-                </AppModeProvider>
+                <QueryControllerProvider>
+                  <ToastProvider>{children}</ToastProvider>
+                </QueryControllerProvider>
               </AppSidebarProvider>
             </ModalProvider>
           </ProviderContextProvider>
diff --git a/web/src/providers/QueryControllerProvider.tsx b/web/src/providers/QueryControllerProvider.tsx
index 347bb28f35e..95f857284af 100644
--- a/web/src/providers/QueryControllerProvider.tsx
+++ b/web/src/providers/QueryControllerProvider.tsx
@@ -5,13 +5,20 @@ import { eeGated } from "@/ce";
 import { QueryControllerProvider as EEQueryControllerProvider } from "@/ee/providers/QueryControllerProvider";
 import { SearchDocWithContent, BaseFilters } from "@/lib/search/interfaces";
 
-export type QueryClassification = "search" | "chat" | null;
+export type AppMode = "auto" | "search" | "chat";
+
+export type QueryState =
+  | { phase: "idle"; appMode: AppMode }
+  | { phase: "classifying" }
+  | { phase: "searching" }
+  | { phase: "search-results" }
+  | { phase: "chat" };
 
 export interface QueryControllerValue {
-  /** Classification state: null (idle), "search", or "chat" */
-  classification: QueryClassification;
-  /** Whether or not the currently submitted query is being actively classified by the backend */
-  isClassifying: boolean;
+  /** Single state variable encoding both the query lifecycle phase and (when idle) the user's mode selection. */
+  state: QueryState;
+  /** Update the app mode. Only takes effect when idle. No-op in CE or when search is unavailable. */
+  setAppMode: (mode: AppMode) => void;
   /** Search results (empty if chat or not yet searched) */
   searchResults: SearchDocWithContent[];
   /** Document IDs selected by the LLM as most relevant */
@@ -31,8 +38,8 @@ export interface QueryControllerValue {
 }
 
 export const QueryControllerContext = createContext<QueryControllerValue>({
-  classification: null,
-  isClassifying: false,
+  state: { phase: "idle", appMode: "chat" },
+  setAppMode: () => undefined,
   searchResults: [],
   llmSelectedDocIds: null,
   error: null,
diff --git a/web/src/refresh-pages/AppPage.tsx b/web/src/refresh-pages/AppPage.tsx
index 8a3b8e13bb5..73675f731f1 100644
--- a/web/src/refresh-pages/AppPage.tsx
+++ b/web/src/refresh-pages/AppPage.tsx
@@ -72,7 +72,6 @@ import { eeGated } from "@/ce";
 import EESearchUI from "@/ee/sections/SearchUI";
 const SearchUI = eeGated(EESearchUI);
 import { motion, AnimatePresence } from "motion/react";
-import { useAppMode } from "@/providers/AppModeProvider";
 
 interface FadeProps {
   show: boolean;
@@ -129,7 +128,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       type: "success",
     },
   });
-  const { setAppMode } = useAppMode();
   const searchParams = useSearchParams();
 
   // Use SWR hooks for data fetching
@@ -485,7 +483,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
       finishOnboarding,
     ]
   );
-  const { submit: submitQuery, classification } = useQueryController();
+  const { submit: submitQuery, state, setAppMode } = useQueryController();
 
   const defaultAppMode =
     (user?.preferences?.default_app_mode?.toLowerCase() as "chat" | "search") ??
@@ -493,12 +491,15 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
 
   const isNewSession = appFocus.isNewSession();
 
+  const isSearch =
+    state.phase === "searching" || state.phase === "search-results";
+
   // 1. Reset the app-mode back to the user's default when navigating back to the "New Sessions" tab.
   // 2. If we're navigating away from the "New Session" tab after performing a search, we reset the app-input-bar.
   useEffect(() => {
     if (isNewSession) setAppMode(defaultAppMode);
-    if (!isNewSession && classification === "search") resetInputBar();
-  }, [isNewSession, defaultAppMode, classification, resetInputBar, setAppMode]);
+    if (!isNewSession && isSearch) resetInputBar();
+  }, [isNewSession, defaultAppMode, isSearch, resetInputBar, setAppMode]);
 
   const handleSearchDocumentClick = useCallback(
     (doc: MinimalOnyxDocument) => setPresentingDocument(doc),
@@ -607,7 +608,6 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
 
   const hasStarterMessages = (liveAgent?.starter_messages?.length ?? 0) > 0;
 
-  const isSearch = classification === "search";
   const gridStyle = {
     gridTemplateColumns: "1fr",
     gridTemplateRows: isSearch
@@ -735,7 +735,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                   <Fade
                     show={
                       (appFocus.isNewSession() || appFocus.isAgent()) &&
-                      !classification
+                      (state.phase === "idle" || state.phase === "classifying")
                     }
                     className="w-full flex-1 flex flex-col items-center justify-end"
                   >
@@ -764,7 +764,8 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
 
                     {/* OnboardingUI */}
                     {(appFocus.isNewSession() || appFocus.isAgent()) &&
-                      !classification &&
+                      (state.phase === "idle" ||
+                        state.phase === "classifying") &&
                       (showOnboarding || !user?.personalization?.name) &&
                       !onboardingDismissed && (
                         <OnboardingFlow
@@ -799,7 +800,7 @@ export default function AppPage({ firstMessage }: ChatPageProps) {
                       <div
                         className={cn(
                           "transition-all duration-150 ease-in-out overflow-hidden",
-                          classification === "search" ? "h-[14px]" : "h-0"
+                          isSearch ? "h-[14px]" : "h-0"
                         )}
                       />
                       <AppInputBar
diff --git a/web/src/sections/input/AppInputBar.tsx b/web/src/sections/input/AppInputBar.tsx
index ec63ebedbe2..b9f9a183d59 100644
--- a/web/src/sections/input/AppInputBar.tsx
+++ b/web/src/sections/input/AppInputBar.tsx
@@ -19,7 +19,6 @@ import useCCPairs from "@/hooks/useCCPairs";
 import { MinimalOnyxDocument } from "@/lib/search/interfaces";
 import { ChatState } from "@/app/app/interfaces";
 import { useForcedTools } from "@/lib/hooks/useForcedTools";
-import { useAppMode } from "@/providers/AppModeProvider";
 import useAppFocus from "@/hooks/useAppFocus";
 import { cn, isImageFile } from "@/lib/utils";
 import { Disabled } from "@opal/core";
@@ -120,7 +119,10 @@ const AppInputBar = React.memo(
     const filesContentRef = useRef<HTMLDivElement>(null);
     const containerRef = useRef<HTMLDivElement>(null);
     const { user } = useUser();
-    const { isClassifying, classification } = useQueryController();
+    const { state } = useQueryController();
+    const isClassifying = state.phase === "classifying";
+    const isSearchActive =
+      state.phase === "searching" || state.phase === "search-results";
 
     // Expose reset and focus methods to parent via ref
     React.useImperativeHandle(ref, () => ({
@@ -140,12 +142,10 @@ const AppInputBar = React.memo(
         setMessage(initialMessage);
       }
     }, [initialMessage]);
-
-    const { appMode } = useAppMode();
     const appFocus = useAppFocus();
+    const appMode = state.phase === "idle" ? state.appMode : undefined;
     const isSearchMode =
-      (appFocus.isNewSession() && appMode === "search") ||
-      classification === "search";
+      (appFocus.isNewSession() && appMode === "search") || isSearchActive;
 
     const { forcedToolIds, setForcedToolIds } = useForcedTools();
     const { currentMessageFiles, setCurrentMessageFiles, currentProjectId } =
diff --git a/web/src/sections/sidebar/AppSidebar.tsx b/web/src/sections/sidebar/AppSidebar.tsx
index a58e8241087..ebed46b972e 100644
--- a/web/src/sections/sidebar/AppSidebar.tsx
+++ b/web/src/sections/sidebar/AppSidebar.tsx
@@ -77,7 +77,6 @@ import { Notification, NotificationType } from "@/interfaces/settings";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import UserAvatarPopover from "@/sections/sidebar/UserAvatarPopover";
 import ChatSearchCommandMenu from "@/sections/sidebar/ChatSearchCommandMenu";
-import { useAppMode } from "@/providers/AppModeProvider";
 import { useQueryController } from "@/providers/QueryControllerProvider";
 
 // Visible-agents = pinned-agents + current-agent (if current-agent not in pinned-agents)
@@ -206,8 +205,7 @@ const MemoizedAppSidebarInner = memo(
     const combinedSettings = useSettingsContext();
     const posthog = usePostHog();
     const { newTenantInfo, invitationInfo } = useModalContext();
-    const { setAppMode } = useAppMode();
-    const { reset } = useQueryController();
+    const { setAppMode, reset } = useQueryController();
 
     // Use SWR hooks for data fetching
     const {

From 533aa8eff819a8d553183b5ca4b077c57e01e2dc Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Tue, 10 Mar 2026 17:50:55 -0700
Subject: [PATCH 226/267] chore(release): upgrade `release-tag` (#9257)

---
 backend/requirements/dev.txt |  2 +-
 pyproject.toml               |  2 +-
 uv.lock                      | 18 +++++++++---------
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/backend/requirements/dev.txt b/backend/requirements/dev.txt
index 1945f138f1f..02038479740 100644
--- a/backend/requirements/dev.txt
+++ b/backend/requirements/dev.txt
@@ -406,7 +406,7 @@ referencing==0.36.2
     #   jsonschema-specifications
 regex==2025.11.3
     # via tiktoken
-release-tag==0.4.3
+release-tag==0.5.2
     # via onyx
 reorder-python-imports-black==3.14.0
     # via onyx
diff --git a/pyproject.toml b/pyproject.toml
index 1bcc0c1ebb9..e9404803bb9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -153,7 +153,7 @@ dev = [
     "pytest-repeat==0.9.4",
     "pytest-xdist==3.8.0",
     "pytest==8.3.5",
-    "release-tag==0.4.3",
+    "release-tag==0.5.2",
     "reorder-python-imports-black==3.14.0",
     "ruff==0.12.0",
     "types-beautifulsoup4==4.12.0.3",
diff --git a/uv.lock b/uv.lock
index 343ff1c0505..05be6b324fa 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4485,7 +4485,7 @@ requires-dist = [
     { name = "pywikibot", marker = "extra == 'backend'", specifier = "==9.0.0" },
     { name = "rapidfuzz", marker = "extra == 'backend'", specifier = "==3.13.0" },
     { name = "redis", marker = "extra == 'backend'", specifier = "==5.0.8" },
-    { name = "release-tag", marker = "extra == 'dev'", specifier = "==0.4.3" },
+    { name = "release-tag", marker = "extra == 'dev'", specifier = "==0.5.2" },
     { name = "reorder-python-imports-black", marker = "extra == 'dev'", specifier = "==3.14.0" },
     { name = "requests", marker = "extra == 'backend'", specifier = "==2.32.5" },
     { name = "requests-oauthlib", marker = "extra == 'backend'", specifier = "==1.3.1" },
@@ -6338,16 +6338,16 @@ wheels = [
 
 [[package]]
 name = "release-tag"
-version = "0.4.3"
+version = "0.5.2"
 source = { registry = "https://pypi.org/simple" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/18/c1d17d973f73f0aa7e2c45f852839ab909756e1bd9727d03babe400fcef0/release_tag-0.4.3-py3-none-any.whl", hash = "sha256:4206f4fa97df930c8176bfee4d3976a7385150ed14b317bd6bae7101ac8b66dd", size = 1181112, upload-time = "2025-12-03T00:18:19.445Z" },
-    { url = "https://files.pythonhosted.org/packages/33/c7/ecc443953840ac313856b2181f55eb8d34fa2c733cdd1edd0bcceee0938d/release_tag-0.4.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:7a347a9ad3d2af16e5367e52b451fbc88a0b7b666850758e8f9a601554a8fb13", size = 1170517, upload-time = "2025-12-03T00:18:11.663Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/81/2f6ffa0d87c792364ca9958433fe088c8acc3d096ac9734040049c6ad506/release_tag-0.4.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:2d1603aa37d8e4f5df63676bbfddc802fbc108a744ba28288ad25c997981c164", size = 1101663, upload-time = "2025-12-03T00:18:15.173Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/ed/9e4ebe400fc52e38dda6e6a45d9da9decd4535ab15e170b8d9b229a66730/release_tag-0.4.3-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:6db7b81a198e3ba6a87496a554684912c13f9297ea8db8600a80f4f971709d37", size = 1079322, upload-time = "2025-12-03T00:18:16.094Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/64/9e0ce6119e091ef9211fa82b9593f564eeec8bdd86eff6a97fe6e2fcb20f/release_tag-0.4.3-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:d79a9cf191dd2c29e1b3a35453fa364b08a7aadd15aeb2c556a7661c6cf4d5ad", size = 1181129, upload-time = "2025-12-03T00:18:15.82Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/09/d96acf18f0773b6355080a568ba48931faa9dbe91ab1abefc6f8c4df04a8/release_tag-0.4.3-py3-none-win_amd64.whl", hash = "sha256:3958b880375f2241d0cc2b9882363bf54b1d4d7ca8ffc6eecc63ab92f23307f0", size = 1260773, upload-time = "2025-12-03T00:18:14.723Z" },
-    { url = "https://files.pythonhosted.org/packages/51/da/ecb6346df1ffb0752fe213e25062f802c10df2948717f0d5f9816c2df914/release_tag-0.4.3-py3-none-win_arm64.whl", hash = "sha256:7d5b08000e6e398d46f05a50139031046348fba6d47909f01e468bb7600c19df", size = 1142155, upload-time = "2025-12-03T00:18:20.647Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/92/01192a540b29cfadaa23850c8f6a2041d541b83a3fa1dc52a5f55212b3b6/release_tag-0.5.2-py3-none-any.whl", hash = "sha256:1e9ca7618bcfc63ad7a0728c84bbad52ef82d07586c4cc11365b44ea8f588069", size = 1264752, upload-time = "2026-03-11T00:27:18.674Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/77/81fb42a23cd0de61caf84266f7aac1950b1c324883788b7c48e5344f61ae/release_tag-0.5.2-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:8fbc61ff7bac2b96fab09566ec45c6508c201efc3f081f57702e1761bbc178d5", size = 1255075, upload-time = "2026-03-11T00:27:24.442Z" },
+    { url = "https://files.pythonhosted.org/packages/98/e6/769f8be94304529c1a531e995f2f3ac83f3c54738ce488b0abde75b20851/release_tag-0.5.2-py3-none-macosx_11_0_arm64.whl", hash = "sha256:fa3d7e495a0c516858a81878d03803539712677a3d6e015503de21cce19bea5e", size = 1163627, upload-time = "2026-03-11T00:27:26.412Z" },
+    { url = "https://files.pythonhosted.org/packages/45/68/7543e9daa0dfd41c487bf140d91fd5879327bb7c001a96aa5264667c30a1/release_tag-0.5.2-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:e8b60453218d6926da1fdcb99c2e17c851be0d7ab1975e97951f0bff5f32b565", size = 1140133, upload-time = "2026-03-11T00:27:20.633Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/30/9087825696271012d889d136310dbdf0811976ae2b2f5a490f4e437903e1/release_tag-0.5.2-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:0e302ed60c2bf8b7ba5634842be28a27d83cec995869e112b0348b3f01a84ff5", size = 1264767, upload-time = "2026-03-11T00:27:28.355Z" },
+    { url = "https://files.pythonhosted.org/packages/79/a3/5b51b0cbdbf2299f545124beab182cfdfe01bf5b615efbc94aee3a64ea67/release_tag-0.5.2-py3-none-win_amd64.whl", hash = "sha256:e3c0629d373a16b9a3da965e89fca893640ce9878ec548865df3609b70989a89", size = 1340816, upload-time = "2026-03-11T00:27:22.622Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/6f/832c2023a8bd8414c93452bd8b43bf61cedfa5b9575f70c06fb911e51a29/release_tag-0.5.2-py3-none-win_arm64.whl", hash = "sha256:5f26b008e0be0c7a122acd8fcb1bb5c822f38e77fed0c0bf6c550cc226c6bf14", size = 1203191, upload-time = "2026-03-11T00:27:29.789Z" },
 ]
 
 [[package]]

From 36196373a8f5c3b1ea52fd6569079b9058d08ef6 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:54:17 -0700
Subject: [PATCH 227/267] chore(deps): bump hono from 4.12.5 to 4.12.7 in
 /backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web
 (#9263)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .../docker/templates/outputs/web/package-lock.json          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
index f5830244ef5..fbe6753d3d9 100644
--- a/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
+++ b/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/package-lock.json
@@ -7424,9 +7424,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.5",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.5.tgz",
-      "integrity": "sha512-3qq+FUBtlTHhtYxbxheZgY8NIFnkkC/MR8u5TTsr7YZ3wixryQ3cCwn3iZbg8p8B88iDBBAYSfZDS75t8MN7Vg==",
+      "version": "4.12.7",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.7.tgz",
+      "integrity": "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"

From 334b7a6d2f0bb7c4989653ac9e9b38ea6b8d3eff Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Tue, 10 Mar 2026 20:00:51 -0700
Subject: [PATCH 228/267] feat(opal): add `foldable` support to `OpenButton` +
 fix `MessageToolbar` (#9265)

---
 .../OpenButton.stories.tsx                    |  40 ++++---
 .../components/buttons/open-button/README.md  |  13 +-
 .../buttons/open-button/components.tsx        | 113 ++++++++++++------
 .../buttons/select-button/README.md           |   4 +-
 .../messageComponents/MessageToolbar.tsx      |   4 +-
 .../popovers/LLMPopover.tsx                   |   7 +-
 6 files changed, 123 insertions(+), 58 deletions(-)
 rename web/lib/opal/src/components/buttons/{OpenButton => open-button}/OpenButton.stories.tsx (68%)

diff --git a/web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx b/web/lib/opal/src/components/buttons/open-button/OpenButton.stories.tsx
similarity index 68%
rename from web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx
rename to web/lib/opal/src/components/buttons/open-button/OpenButton.stories.tsx
index d31b8483776..f69bcdfc3d6 100644
--- a/web/lib/opal/src/components/buttons/OpenButton/OpenButton.stories.tsx
+++ b/web/lib/opal/src/components/buttons/open-button/OpenButton.stories.tsx
@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { OpenButton } from "@opal/components";
+import { Disabled as DisabledProvider } from "@opal/core";
 import { SvgSettings } from "@opal/icons";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 
@@ -32,16 +33,9 @@ export const WithIcon: Story = {
   },
 };
 
-export const Selected: Story = {
-  args: {
-    selected: true,
-    children: "Selected",
-  },
-};
-
 export const Open: Story = {
   args: {
-    transient: true,
+    interaction: "hover",
     children: "Open state",
   },
 };
@@ -53,18 +47,27 @@ export const Disabled: Story = {
   },
 };
 
-export const LightProminence: Story = {
+export const Foldable: Story = {
   args: {
-    prominence: "light",
-    children: "Light prominence",
+    foldable: true,
+    icon: SvgSettings,
+    children: "Settings",
   },
 };
 
-export const HeavyProminence: Story = {
+export const FoldableDisabled: Story = {
   args: {
-    prominence: "heavy",
-    children: "Heavy prominence",
+    foldable: true,
+    icon: SvgSettings,
+    children: "Settings",
   },
+  decorators: [
+    (Story) => (
+      <DisabledProvider disabled>
+        <Story />
+      </DisabledProvider>
+    ),
+  ],
 };
 
 export const Sizes: Story = {
@@ -78,3 +81,12 @@ export const Sizes: Story = {
     </div>
   ),
 };
+
+export const WithTooltip: Story = {
+  args: {
+    icon: SvgSettings,
+    children: "Settings",
+    tooltip: "Open settings",
+    tooltipSide: "bottom",
+  },
+};
diff --git a/web/lib/opal/src/components/buttons/open-button/README.md b/web/lib/opal/src/components/buttons/open-button/README.md
index bfa0be165b5..9d2ebeb3d21 100644
--- a/web/lib/opal/src/components/buttons/open-button/README.md
+++ b/web/lib/opal/src/components/buttons/open-button/README.md
@@ -17,7 +17,9 @@ OpenButton is a **tighter, specialized use-case** of SelectButton:
 - It hardcodes `variant="select-heavy"` (SelectButton exposes `variant`)
 - It adds a built-in chevron with CSS-driven rotation (SelectButton has no chevron)
 - It auto-detects Radix `data-state="open"` to derive `interaction` (SelectButton has no Radix awareness)
-- It does not support `foldable` or `rightIcon` (SelectButton does)
+- It does not support `rightIcon` (SelectButton does)
+
+Both components support `foldable` using the same pattern: `interactive-foldable-host` class + `Interactive.Foldable` wrapper around the label and trailing icon. When foldable, the left icon stays visible while the rest collapses. If you change the foldable implementation in one, update the other to match.
 
 If you need a general-purpose stateful toggle, use `SelectButton`. If you need a popover/dropdown trigger with a chevron, use `OpenButton`.
 
@@ -26,10 +28,12 @@ If you need a general-purpose stateful toggle, use `SelectButton`. If you need a
 ```
 Interactive.Stateful           <- variant="select-heavy", interaction, state, disabled, onClick
   └─ Interactive.Container     <- height, rounding, padding (from `size`)
-       └─ div.opal-button.interactive-foreground
+       └─ div.opal-button.interactive-foreground [.interactive-foldable-host]
             ├─ div > Icon?                 (interactive-foreground-icon)
-            ├─ <span>?                     .opal-button-label
-            └─ div > ChevronIcon           .opal-open-button-chevron (interactive-foreground-icon)
+            ├─ [Foldable]?                 (wraps label + chevron when foldable)
+            │    ├─ <span>?                .opal-button-label
+            │    └─ div > ChevronIcon      .opal-open-button-chevron
+            └─ <span>? / ChevronIcon       (non-foldable)
 ```
 
 - **`interaction` controls both the chevron and the hover visual state.** When `interaction` is `"hover"` (explicitly or via Radix `data-state="open"`), the chevron rotates 180° and the hover background activates.
@@ -44,6 +48,7 @@ Interactive.Stateful           <- variant="select-heavy", interaction, state, di
 | `interaction` | `"rest" \| "hover" \| "active"` | auto | JS-controlled interaction override. Falls back to Radix `data-state="open"` when omitted. |
 | `icon` | `IconFunctionComponent` | — | Left icon component |
 | `children` | `string` | — | Content between icon and chevron |
+| `foldable` | `boolean` | `false` | When `true`, requires both `icon` and `children`; the left icon stays visible while the label + chevron collapse when not hovered. If `tooltip` is omitted on a disabled foldable button, the label text is used as the tooltip. |
 | `size` | `SizeVariant` | `"lg"` | Size preset controlling height, rounding, and padding |
 | `width` | `WidthVariant` | — | Width preset |
 | `tooltip` | `string` | — | Tooltip text shown on hover |
diff --git a/web/lib/opal/src/components/buttons/open-button/components.tsx b/web/lib/opal/src/components/buttons/open-button/components.tsx
index 40f31ae69e0..40ea4597e82 100644
--- a/web/lib/opal/src/components/buttons/open-button/components.tsx
+++ b/web/lib/opal/src/components/buttons/open-button/components.tsx
@@ -2,6 +2,7 @@ import "@opal/components/buttons/open-button/styles.css";
 import "@opal/components/tooltip.css";
 import {
   Interactive,
+  useDisabled,
   type InteractiveStatefulProps,
   type InteractiveStatefulInteraction,
 } from "@opal/core";
@@ -30,27 +31,46 @@ function ChevronIcon({ className, ...props }: IconProps) {
 // Types
 // ---------------------------------------------------------------------------
 
-type OpenButtonProps = Omit<InteractiveStatefulProps, "variant"> & {
-  /** Left icon. */
-  icon?: IconFunctionComponent;
-
-  /** Button label text. */
-  children?: string;
-
-  /**
-   * Size preset — controls gap, text size, and Container height/rounding.
-   */
-  size?: SizeVariant;
-
-  /** Width preset. */
-  width?: WidthVariant;
-
-  /** Tooltip text shown on hover. */
-  tooltip?: string;
-
-  /** Which side the tooltip appears on. */
-  tooltipSide?: TooltipSide;
-};
+/**
+ * Content props — a discriminated union on `foldable` that enforces:
+ *
+ * - `foldable: true`  → `icon` and `children` are required (icon stays visible,
+ *                        label + chevron fold away)
+ * - `foldable?: false` → at least one of `icon` or `children` must be provided
+ */
+type OpenButtonContentProps =
+  | {
+      foldable: true;
+      icon: IconFunctionComponent;
+      children: string;
+    }
+  | {
+      foldable?: false;
+      icon?: IconFunctionComponent;
+      children: string;
+    }
+  | {
+      foldable?: false;
+      icon: IconFunctionComponent;
+      children?: string;
+    };
+
+type OpenButtonProps = Omit<InteractiveStatefulProps, "variant"> &
+  OpenButtonContentProps & {
+    /**
+     * Size preset — controls gap, text size, and Container height/rounding.
+     */
+    size?: SizeVariant;
+
+    /** Width preset. */
+    width?: WidthVariant;
+
+    /** Tooltip text shown on hover. */
+    tooltip?: string;
+
+    /** Which side the tooltip appears on. */
+    tooltipSide?: TooltipSide;
+  };
 
 // ---------------------------------------------------------------------------
 // OpenButton
@@ -60,12 +80,15 @@ function OpenButton({
   icon: Icon,
   children,
   size = "lg",
+  foldable,
   width,
   tooltip,
   tooltipSide = "top",
   interaction,
   ...statefulProps
 }: OpenButtonProps) {
+  const { isDisabled } = useDisabled();
+
   // Derive open state: explicit prop → Radix data-state (injected via Slot chain)
   const dataState = (statefulProps as Record<string, unknown>)["data-state"] as
     | string
@@ -75,6 +98,17 @@ function OpenButton({
 
   const isLarge = size === "lg";
 
+  const labelEl = children ? (
+    <span
+      className={cn(
+        "opal-button-label whitespace-nowrap",
+        isLarge ? "font-main-ui-body" : "font-secondary-body"
+      )}
+    >
+      {children}
+    </span>
+  ) : null;
+
   const button = (
     <Interactive.Stateful
       variant="select-heavy"
@@ -89,25 +123,34 @@ function OpenButton({
           isLarge ? "default" : size === "2xs" ? "mini" : "compact"
         }
       >
-        <div className="opal-button interactive-foreground flex flex-row items-center gap-1">
-          {iconWrapper(Icon, size, false)}
-          {children && (
-            <span
-              className={cn(
-                "opal-button-label whitespace-nowrap",
-                isLarge ? "font-main-ui-body" : "font-secondary-body"
-              )}
-            >
-              {children}
-            </span>
+        <div
+          className={cn(
+            "opal-button interactive-foreground flex flex-row items-center gap-1",
+            foldable && "interactive-foldable-host"
+          )}
+        >
+          {iconWrapper(Icon, size, !foldable && !!children)}
+
+          {foldable ? (
+            <Interactive.Foldable>
+              {labelEl}
+              {iconWrapper(ChevronIcon, size, !!children)}
+            </Interactive.Foldable>
+          ) : (
+            <>
+              {labelEl}
+              {iconWrapper(ChevronIcon, size, !!children)}
+            </>
           )}
-          {iconWrapper(ChevronIcon, size, false)}
         </div>
       </Interactive.Container>
     </Interactive.Stateful>
   );
 
-  if (!tooltip) return button;
+  const resolvedTooltip =
+    tooltip ?? (foldable && isDisabled && children ? children : undefined);
+
+  if (!resolvedTooltip) return button;
 
   return (
     <TooltipPrimitive.Root>
@@ -118,7 +161,7 @@ function OpenButton({
           side={tooltipSide}
           sideOffset={4}
         >
-          {tooltip}
+          {resolvedTooltip}
         </TooltipPrimitive.Content>
       </TooltipPrimitive.Portal>
     </TooltipPrimitive.Root>
diff --git a/web/lib/opal/src/components/buttons/select-button/README.md b/web/lib/opal/src/components/buttons/select-button/README.md
index 5334e0364d9..ce6cc644c35 100644
--- a/web/lib/opal/src/components/buttons/select-button/README.md
+++ b/web/lib/opal/src/components/buttons/select-button/README.md
@@ -17,7 +17,9 @@ Interactive.Stateful → Interactive.Container → content row (icon + label + t
 - OpenButton hardcodes `variant="select-heavy"` (SelectButton exposes `variant`)
 - OpenButton adds a built-in chevron with CSS-driven rotation (SelectButton has no chevron)
 - OpenButton auto-detects Radix `data-state="open"` to derive `interaction` (SelectButton has no Radix awareness)
-- OpenButton does not support `foldable` or `rightIcon` (SelectButton does)
+- OpenButton does not support `rightIcon` (SelectButton does)
+
+Both components support `foldable` using the same pattern: `interactive-foldable-host` class + `Interactive.Foldable` wrapper around the label and trailing icon. When foldable, the left icon stays visible while the rest collapses. If you change the foldable implementation in one, update the other to match.
 
 Use SelectButton for general-purpose stateful toggles. Use `OpenButton` for popover/dropdown triggers with a chevron.
 
diff --git a/web/src/app/app/message/messageComponents/MessageToolbar.tsx b/web/src/app/app/message/messageComponents/MessageToolbar.tsx
index 61070fd1e44..388988ef5f5 100644
--- a/web/src/app/app/message/messageComponents/MessageToolbar.tsx
+++ b/web/src/app/app/message/messageComponents/MessageToolbar.tsx
@@ -249,6 +249,7 @@ export default function MessageToolbar({
             <SelectButton
               icon={SvgThumbsUp}
               onClick={() => handleFeedbackClick("like")}
+              variant="select-light"
               state={isFeedbackTransient("like") ? "selected" : "empty"}
               tooltip={
                 currentFeedback === "like" ? "Remove Like" : "Good Response"
@@ -258,6 +259,7 @@ export default function MessageToolbar({
             <SelectButton
               icon={SvgThumbsDown}
               onClick={() => handleFeedbackClick("dislike")}
+              variant="select-light"
               state={isFeedbackTransient("dislike") ? "selected" : "empty"}
               tooltip={
                 currentFeedback === "dislike"
@@ -283,7 +285,7 @@ export default function MessageToolbar({
                       });
                       regenerator(llmDescriptor);
                     }}
-                    folded
+                    foldable
                   />
                 </div>
               )}
diff --git a/web/src/refresh-components/popovers/LLMPopover.tsx b/web/src/refresh-components/popovers/LLMPopover.tsx
index a1dee7fa639..0e605ceddd4 100644
--- a/web/src/refresh-components/popovers/LLMPopover.tsx
+++ b/web/src/refresh-components/popovers/LLMPopover.tsx
@@ -35,7 +35,7 @@ import { LLMOption, LLMOptionGroup } from "./interfaces";
 export interface LLMPopoverProps {
   llmManager: LlmManager;
   requiresImageInput?: boolean;
-  folded?: boolean;
+  foldable?: boolean;
   onSelect?: (value: string) => void;
   currentModelName?: string;
   disabled?: boolean;
@@ -142,7 +142,7 @@ export function groupLlmOptions(
 export default function LLMPopover({
   llmManager,
   requiresImageInput,
-  folded,
+  foldable,
   onSelect,
   currentModelName,
   disabled = false,
@@ -359,13 +359,14 @@ export default function LLMPopover({
           <Disabled disabled={disabled}>
             <OpenButton
               icon={
-                folded
+                foldable
                   ? SvgRefreshCw
                   : getProviderIcon(
                       llmManager.currentLlm.provider,
                       llmManager.currentLlm.modelName
                     )
               }
+              foldable={foldable}
             >
               {currentLlmDisplayName}
             </OpenButton>

From a0329161b0c6a9846ddab9a48fc501a4170d3b16 Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Tue, 10 Mar 2026 20:45:08 -0700
Subject: [PATCH 229/267] feat(litellm): Adding FE Provider workflow (#9264)

---
 backend/onyx/llm/constants.py                 |   3 +
 .../llm/well_known_providers/constants.py     |   2 +
 .../llm_provider_options.py                   |   3 +
 web/src/app/admin/configuration/llm/utils.ts  |  72 +++++
 web/src/interfaces/llm.ts                     |  14 +
 web/src/lib/llmConfig/providers.ts            |   3 +
 .../admin/LLMConfigurationPage.tsx            |   8 +
 .../modals/llmConfig/LiteLLMProxyModal.tsx    | 180 ++++++++++++
 .../sections/modals/llmConfig/getModal.tsx    |   3 +
 .../forms/LiteLLMProxyOnboardingForm.tsx      | 264 ++++++++++++++++++
 .../onboarding/forms/getOnboardingForm.tsx    |  16 ++
 11 files changed, 568 insertions(+)
 create mode 100644 web/src/sections/modals/llmConfig/LiteLLMProxyModal.tsx
 create mode 100644 web/src/sections/onboarding/forms/LiteLLMProxyOnboardingForm.tsx

diff --git a/backend/onyx/llm/constants.py b/backend/onyx/llm/constants.py
index aa5768479df..0327d9faa41 100644
--- a/backend/onyx/llm/constants.py
+++ b/backend/onyx/llm/constants.py
@@ -43,6 +43,7 @@ def __str__(self) -> str:
     LlmProviderNames.AZURE,
     LlmProviderNames.OLLAMA_CHAT,
     LlmProviderNames.LM_STUDIO,
+    LlmProviderNames.LITELLM_PROXY,
 ]
 
 
@@ -59,6 +60,7 @@ def __str__(self) -> str:
     "ollama": "Ollama",
     LlmProviderNames.OLLAMA_CHAT: "Ollama",
     LlmProviderNames.LM_STUDIO: "LM Studio",
+    LlmProviderNames.LITELLM_PROXY: "LiteLLM Proxy",
     "groq": "Groq",
     "anyscale": "Anyscale",
     "deepseek": "DeepSeek",
@@ -109,6 +111,7 @@ def __str__(self) -> str:
     LlmProviderNames.LM_STUDIO,
     LlmProviderNames.VERTEX_AI,
     LlmProviderNames.AZURE,
+    LlmProviderNames.LITELLM_PROXY,
 }
 
 # Model family name mappings for display name generation
diff --git a/backend/onyx/llm/well_known_providers/constants.py b/backend/onyx/llm/well_known_providers/constants.py
index 1a5a2f47b89..fba2600b52a 100644
--- a/backend/onyx/llm/well_known_providers/constants.py
+++ b/backend/onyx/llm/well_known_providers/constants.py
@@ -11,6 +11,8 @@
 LM_STUDIO_PROVIDER_NAME = "lm_studio"
 LM_STUDIO_API_KEY_CONFIG_KEY = "LM_STUDIO_API_KEY"
 
+LITELLM_PROXY_PROVIDER_NAME = "litellm_proxy"
+
 # Providers that use optional Bearer auth from custom_config
 PROVIDERS_WITH_SPECIAL_API_KEY_HANDLING: dict[str, str] = {
     LlmProviderNames.OLLAMA_CHAT: OLLAMA_API_KEY_CONFIG_KEY,
diff --git a/backend/onyx/llm/well_known_providers/llm_provider_options.py b/backend/onyx/llm/well_known_providers/llm_provider_options.py
index 535acab42d0..a456ff52690 100644
--- a/backend/onyx/llm/well_known_providers/llm_provider_options.py
+++ b/backend/onyx/llm/well_known_providers/llm_provider_options.py
@@ -15,6 +15,7 @@
 from onyx.llm.well_known_providers.constants import ANTHROPIC_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import AZURE_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import BEDROCK_PROVIDER_NAME
+from onyx.llm.well_known_providers.constants import LITELLM_PROXY_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import LM_STUDIO_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import OLLAMA_PROVIDER_NAME
 from onyx.llm.well_known_providers.constants import OPENAI_PROVIDER_NAME
@@ -47,6 +48,7 @@ def _get_provider_to_models_map() -> dict[str, list[str]]:
         OLLAMA_PROVIDER_NAME: [],  # Dynamic - fetched from Ollama API
         LM_STUDIO_PROVIDER_NAME: [],  # Dynamic - fetched from LM Studio API
         OPENROUTER_PROVIDER_NAME: [],  # Dynamic - fetched from OpenRouter API
+        LITELLM_PROXY_PROVIDER_NAME: [],  # Dynamic - fetched from LiteLLM proxy API
     }
 
 
@@ -331,6 +333,7 @@ def get_provider_display_name(provider_name: str) -> str:
         BEDROCK_PROVIDER_NAME: "Amazon Bedrock",
         VERTEXAI_PROVIDER_NAME: "Google Vertex AI",
         OPENROUTER_PROVIDER_NAME: "OpenRouter",
+        LITELLM_PROXY_PROVIDER_NAME: "LiteLLM Proxy",
     }
 
     if provider_name in _ONYX_PROVIDER_DISPLAY_NAMES:
diff --git a/web/src/app/admin/configuration/llm/utils.ts b/web/src/app/admin/configuration/llm/utils.ts
index 95629899dad..7751517beef 100644
--- a/web/src/app/admin/configuration/llm/utils.ts
+++ b/web/src/app/admin/configuration/llm/utils.ts
@@ -14,6 +14,7 @@ import {
   QwenIcon,
   OllamaIcon,
   LMStudioIcon,
+  LiteLLMIcon,
   ZAIIcon,
 } from "@/components/icons/icons";
 import {
@@ -21,12 +22,14 @@ import {
   OpenRouterModelResponse,
   BedrockModelResponse,
   LMStudioModelResponse,
+  LiteLLMProxyModelResponse,
   ModelConfiguration,
   LLMProviderName,
   BedrockFetchParams,
   OllamaFetchParams,
   LMStudioFetchParams,
   OpenRouterFetchParams,
+  LiteLLMProxyFetchParams,
 } from "@/interfaces/llm";
 import { SvgAws, SvgOpenrouter } from "@opal/icons";
 
@@ -37,6 +40,7 @@ export const AGGREGATOR_PROVIDERS = new Set([
   "openrouter",
   "ollama_chat",
   "lm_studio",
+  "litellm_proxy",
   "vertex_ai",
 ]);
 
@@ -73,6 +77,7 @@ export const getProviderIcon = (
     bedrock: SvgAws,
     bedrock_converse: SvgAws,
     openrouter: SvgOpenrouter,
+    litellm_proxy: LiteLLMIcon,
     vertex_ai: GeminiIcon,
   };
 
@@ -338,6 +343,65 @@ export const fetchLMStudioModels = async (
   }
 };
 
+/**
+ * Fetches LiteLLM Proxy models directly without any form state dependencies.
+ * Uses snake_case params to match API structure.
+ */
+export const fetchLiteLLMProxyModels = async (
+  params: LiteLLMProxyFetchParams
+): Promise<{ models: ModelConfiguration[]; error?: string }> => {
+  const apiBase = params.api_base;
+  const apiKey = params.api_key;
+  if (!apiBase) {
+    return { models: [], error: "API Base is required" };
+  }
+  if (!apiKey) {
+    return { models: [], error: "API Key is required" };
+  }
+
+  try {
+    const response = await fetch("/api/admin/llm/litellm/available-models", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        api_base: apiBase,
+        api_key: apiKey,
+        provider_name: params.provider_name,
+      }),
+      signal: params.signal,
+    });
+
+    if (!response.ok) {
+      let errorMessage = "Failed to fetch models";
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.detail || errorData.message || errorMessage;
+      } catch {
+        // ignore JSON parsing errors
+      }
+      return { models: [], error: errorMessage };
+    }
+
+    const data: LiteLLMProxyModelResponse[] = await response.json();
+    const models: ModelConfiguration[] = data.map((modelData) => ({
+      name: modelData.model_name,
+      display_name: modelData.model_name,
+      is_visible: true,
+      max_input_tokens: null,
+      supports_image_input: false,
+      supports_reasoning: false,
+    }));
+
+    return { models };
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    return { models: [], error: errorMessage };
+  }
+};
+
 /**
  * Fetches models for a provider. Accepts form values directly and maps them
  * to the expected fetch params format internally.
@@ -385,6 +449,13 @@ export const fetchModels = async (
         api_key: formValues.api_key,
         provider_name: formValues.name,
       });
+    case LLMProviderName.LITELLM_PROXY:
+      return fetchLiteLLMProxyModels({
+        api_base: formValues.api_base,
+        api_key: formValues.api_key,
+        provider_name: formValues.name,
+        signal,
+      });
     default:
       return { models: [], error: `Unknown provider: ${providerName}` };
   }
@@ -397,6 +468,7 @@ export function canProviderFetchModels(providerName?: string) {
     case LLMProviderName.OLLAMA_CHAT:
     case LLMProviderName.LM_STUDIO:
     case LLMProviderName.OPENROUTER:
+    case LLMProviderName.LITELLM_PROXY:
       return true;
     default:
       return false;
diff --git a/web/src/interfaces/llm.ts b/web/src/interfaces/llm.ts
index c0eb5add152..a2cb1c15f08 100644
--- a/web/src/interfaces/llm.ts
+++ b/web/src/interfaces/llm.ts
@@ -7,6 +7,7 @@ export enum LLMProviderName {
   OPENROUTER = "openrouter",
   VERTEX_AI = "vertex_ai",
   BEDROCK = "bedrock",
+  LITELLM_PROXY = "litellm_proxy",
   CUSTOM = "custom",
 }
 
@@ -144,6 +145,18 @@ export interface OpenRouterFetchParams {
   provider_name?: string;
 }
 
+export interface LiteLLMProxyFetchParams {
+  api_base?: string;
+  api_key?: string;
+  provider_name?: string;
+  signal?: AbortSignal;
+}
+
+export interface LiteLLMProxyModelResponse {
+  provider_name: string;
+  model_name: string;
+}
+
 export interface VertexAIFetchParams {
   model_configurations?: ModelConfiguration[];
 }
@@ -153,4 +166,5 @@ export type FetchModelsParams =
   | OllamaFetchParams
   | LMStudioFetchParams
   | OpenRouterFetchParams
+  | LiteLLMProxyFetchParams
   | VertexAIFetchParams;
diff --git a/web/src/lib/llmConfig/providers.ts b/web/src/lib/llmConfig/providers.ts
index 3283cd9ad18..9e51444693a 100644
--- a/web/src/lib/llmConfig/providers.ts
+++ b/web/src/lib/llmConfig/providers.ts
@@ -22,6 +22,7 @@ const PROVIDER_ICONS: Record<string, IconFunctionComponent> = {
   [LLMProviderName.BEDROCK]: SvgAws,
   [LLMProviderName.AZURE]: SvgAzure,
   litellm: SvgLitellm,
+  [LLMProviderName.LITELLM_PROXY]: SvgLitellm,
   [LLMProviderName.OLLAMA_CHAT]: SvgOllama,
   [LLMProviderName.OPENROUTER]: SvgOpenrouter,
   [LLMProviderName.LM_STUDIO]: SvgLmStudio,
@@ -37,6 +38,7 @@ const PROVIDER_PRODUCT_NAMES: Record<string, string> = {
   [LLMProviderName.BEDROCK]: "Amazon Bedrock",
   [LLMProviderName.AZURE]: "Azure OpenAI",
   litellm: "LiteLLM",
+  [LLMProviderName.LITELLM_PROXY]: "LiteLLM Proxy",
   [LLMProviderName.OLLAMA_CHAT]: "Ollama",
   [LLMProviderName.OPENROUTER]: "OpenRouter",
   [LLMProviderName.LM_STUDIO]: "LM Studio",
@@ -52,6 +54,7 @@ const PROVIDER_DISPLAY_NAMES: Record<string, string> = {
   [LLMProviderName.BEDROCK]: "AWS",
   [LLMProviderName.AZURE]: "Microsoft Azure",
   litellm: "LiteLLM",
+  [LLMProviderName.LITELLM_PROXY]: "LiteLLM Proxy",
   [LLMProviderName.OLLAMA_CHAT]: "Ollama",
   [LLMProviderName.OPENROUTER]: "OpenRouter",
   [LLMProviderName.LM_STUDIO]: "LM Studio",
diff --git a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
index 3be9e80f779..414e2ebec47 100644
--- a/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
+++ b/web/src/refresh-pages/admin/LLMConfigurationPage.tsx
@@ -44,6 +44,7 @@ import { VertexAIModal } from "@/sections/modals/llmConfig/VertexAIModal";
 import { OpenRouterModal } from "@/sections/modals/llmConfig/OpenRouterModal";
 import { CustomModal } from "@/sections/modals/llmConfig/CustomModal";
 import { LMStudioForm } from "@/sections/modals/llmConfig/LMStudioForm";
+import { LiteLLMProxyModal } from "@/sections/modals/llmConfig/LiteLLMProxyModal";
 import { Section } from "@/layouts/general-layouts";
 
 const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.LLM_MODELS]!;
@@ -116,6 +117,13 @@ const PROVIDER_MODAL_MAP: Record<
       onOpenChange={onOpenChange}
     />
   ),
+  litellm_proxy: (d, open, onOpenChange) => (
+    <LiteLLMProxyModal
+      shouldMarkAsDefault={d}
+      open={open}
+      onOpenChange={onOpenChange}
+    />
+  ),
 };
 
 // ============================================================================
diff --git a/web/src/sections/modals/llmConfig/LiteLLMProxyModal.tsx b/web/src/sections/modals/llmConfig/LiteLLMProxyModal.tsx
new file mode 100644
index 00000000000..aa773213f76
--- /dev/null
+++ b/web/src/sections/modals/llmConfig/LiteLLMProxyModal.tsx
@@ -0,0 +1,180 @@
+import Separator from "@/refresh-components/Separator";
+import { Form, Formik } from "formik";
+import { TextFormField } from "@/components/Field";
+import {
+  LLMProviderFormProps,
+  LLMProviderName,
+  ModelConfiguration,
+} from "@/interfaces/llm";
+import { fetchLiteLLMProxyModels } from "@/app/admin/configuration/llm/utils";
+import * as Yup from "yup";
+import {
+  ProviderFormEntrypointWrapper,
+  ProviderFormContext,
+} from "./components/FormWrapper";
+import { DisplayNameField } from "./components/DisplayNameField";
+import PasswordInputTypeInField from "@/refresh-components/form/PasswordInputTypeInField";
+import { FormActionButtons } from "./components/FormActionButtons";
+import {
+  buildDefaultInitialValues,
+  buildDefaultValidationSchema,
+  buildAvailableModelConfigurations,
+  submitLLMProvider,
+  BaseLLMFormValues,
+  LLM_FORM_CLASS_NAME,
+} from "./formUtils";
+import { AdvancedOptions } from "./components/AdvancedOptions";
+import { DisplayModels } from "./components/DisplayModels";
+import { FetchModelsButton } from "./components/FetchModelsButton";
+import { useState } from "react";
+
+const LITELLM_PROXY_DISPLAY_NAME = "LiteLLM Proxy";
+const DEFAULT_API_BASE = "http://localhost:4000";
+
+interface LiteLLMProxyModalValues extends BaseLLMFormValues {
+  api_key: string;
+  api_base: string;
+}
+
+export function LiteLLMProxyModal({
+  existingLlmProvider,
+  shouldMarkAsDefault,
+  open,
+  onOpenChange,
+}: LLMProviderFormProps) {
+  const [fetchedModels, setFetchedModels] = useState<ModelConfiguration[]>([]);
+
+  return (
+    <ProviderFormEntrypointWrapper
+      providerName={LITELLM_PROXY_DISPLAY_NAME}
+      providerEndpoint={LLMProviderName.LITELLM_PROXY}
+      existingLlmProvider={existingLlmProvider}
+      open={open}
+      onOpenChange={onOpenChange}
+    >
+      {({
+        onClose,
+        mutate,
+        isTesting,
+        setIsTesting,
+        testError,
+        setTestError,
+        wellKnownLLMProvider,
+      }: ProviderFormContext) => {
+        const modelConfigurations = buildAvailableModelConfigurations(
+          existingLlmProvider,
+          wellKnownLLMProvider
+        );
+        const initialValues: LiteLLMProxyModalValues = {
+          ...buildDefaultInitialValues(
+            existingLlmProvider,
+            modelConfigurations
+          ),
+          api_key: existingLlmProvider?.api_key ?? "",
+          api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
+        };
+
+        const validationSchema = buildDefaultValidationSchema().shape({
+          api_key: Yup.string().required("API Key is required"),
+          api_base: Yup.string().required("API Base URL is required"),
+        });
+
+        return (
+          <Formik
+            initialValues={initialValues}
+            validationSchema={validationSchema}
+            validateOnMount={true}
+            onSubmit={async (values, { setSubmitting }) => {
+              await submitLLMProvider({
+                providerName: LLMProviderName.LITELLM_PROXY,
+                values,
+                initialValues,
+                modelConfigurations:
+                  fetchedModels.length > 0
+                    ? fetchedModels
+                    : modelConfigurations,
+                existingLlmProvider,
+                shouldMarkAsDefault,
+                setIsTesting,
+                setTestError,
+                mutate,
+                onClose,
+                setSubmitting,
+              });
+            }}
+          >
+            {(formikProps) => {
+              const currentModels =
+                fetchedModels.length > 0
+                  ? fetchedModels
+                  : existingLlmProvider?.model_configurations ||
+                    modelConfigurations;
+
+              const isFetchDisabled =
+                !formikProps.values.api_base || !formikProps.values.api_key;
+
+              return (
+                <Form className={LLM_FORM_CLASS_NAME}>
+                  <DisplayNameField disabled={!!existingLlmProvider} />
+
+                  <TextFormField
+                    name="api_base"
+                    label="API Base URL"
+                    subtext="The base URL for your LiteLLM Proxy server (e.g., http://localhost:4000)"
+                    placeholder={DEFAULT_API_BASE}
+                  />
+
+                  <PasswordInputTypeInField name="api_key" label="API Key" />
+
+                  <FetchModelsButton
+                    onFetch={() =>
+                      fetchLiteLLMProxyModels({
+                        api_base: formikProps.values.api_base,
+                        api_key: formikProps.values.api_key,
+                        provider_name: existingLlmProvider?.name,
+                      })
+                    }
+                    isDisabled={isFetchDisabled}
+                    disabledHint={
+                      !formikProps.values.api_base
+                        ? "Enter the API base URL first."
+                        : !formikProps.values.api_key
+                          ? "Enter your API key first."
+                          : undefined
+                    }
+                    onModelsFetched={setFetchedModels}
+                    autoFetchOnInitialLoad={!!existingLlmProvider}
+                  />
+
+                  <Separator />
+
+                  <DisplayModels
+                    modelConfigurations={currentModels}
+                    formikProps={formikProps}
+                    noModelConfigurationsMessage={
+                      "Fetch available models first, then you'll be able to select " +
+                      "the models you want to make available in Onyx."
+                    }
+                    recommendedDefaultModel={null}
+                    shouldShowAutoUpdateToggle={false}
+                  />
+
+                  <AdvancedOptions formikProps={formikProps} />
+
+                  <FormActionButtons
+                    isTesting={isTesting}
+                    testError={testError}
+                    existingLlmProvider={existingLlmProvider}
+                    mutate={mutate}
+                    onClose={onClose}
+                    isFormValid={formikProps.isValid}
+                  />
+                </Form>
+              );
+            }}
+          </Formik>
+        );
+      }}
+    </ProviderFormEntrypointWrapper>
+  );
+}
diff --git a/web/src/sections/modals/llmConfig/getModal.tsx b/web/src/sections/modals/llmConfig/getModal.tsx
index ebb411004fd..484c71eac4b 100644
--- a/web/src/sections/modals/llmConfig/getModal.tsx
+++ b/web/src/sections/modals/llmConfig/getModal.tsx
@@ -8,6 +8,7 @@ import { OpenRouterModal } from "./OpenRouterModal";
 import { CustomModal } from "./CustomModal";
 import { BedrockModal } from "./BedrockModal";
 import { LMStudioForm } from "./LMStudioForm";
+import { LiteLLMProxyModal } from "./LiteLLMProxyModal";
 
 export function detectIfRealOpenAIProvider(provider: LLMProviderView) {
   return (
@@ -47,6 +48,8 @@ export function getModalForExistingProvider(
       return <OpenRouterModal {...props} />;
     case LLMProviderName.LM_STUDIO:
       return <LMStudioForm {...props} />;
+    case LLMProviderName.LITELLM_PROXY:
+      return <LiteLLMProxyModal {...props} />;
     default:
       return <CustomModal {...props} />;
   }
diff --git a/web/src/sections/onboarding/forms/LiteLLMProxyOnboardingForm.tsx b/web/src/sections/onboarding/forms/LiteLLMProxyOnboardingForm.tsx
new file mode 100644
index 00000000000..d25d5105802
--- /dev/null
+++ b/web/src/sections/onboarding/forms/LiteLLMProxyOnboardingForm.tsx
@@ -0,0 +1,264 @@
+"use client";
+
+import { useMemo } from "react";
+import * as Yup from "yup";
+import { FormikField } from "@/refresh-components/form/FormikField";
+import { FormField } from "@/refresh-components/form/FormField";
+import PasswordInputTypeIn from "@/refresh-components/inputs/PasswordInputTypeIn";
+import InputComboBox from "@/refresh-components/inputs/InputComboBox";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import Separator from "@/refresh-components/Separator";
+import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
+import { cn, noProp } from "@/lib/utils";
+import { SvgRefreshCw } from "@opal/icons";
+import {
+  WellKnownLLMProviderDescriptor,
+  ModelConfiguration,
+} from "@/interfaces/llm";
+import {
+  OnboardingFormWrapper,
+  OnboardingFormChildProps,
+} from "./OnboardingFormWrapper";
+import { OnboardingActions, OnboardingState } from "@/interfaces/onboarding";
+import { buildInitialValues } from "../components/llmConnectionHelpers";
+import ConnectionProviderIcon from "@/refresh-components/ConnectionProviderIcon";
+import { ProviderIcon } from "@/app/admin/configuration/llm/ProviderIcon";
+
+const FIELD_API_KEY = "api_key";
+const FIELD_API_BASE = "api_base";
+const FIELD_DEFAULT_MODEL_NAME = "default_model_name";
+
+interface LiteLLMProxyOnboardingFormProps {
+  llmDescriptor: WellKnownLLMProviderDescriptor;
+  onboardingState: OnboardingState;
+  onboardingActions: OnboardingActions;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+interface LiteLLMProxyFormValues {
+  name: string;
+  provider: string;
+  api_key: string;
+  api_base: string;
+  api_key_changed: boolean;
+  default_model_name: string;
+  model_configurations: ModelConfiguration[];
+  groups: number[];
+  is_public: boolean;
+}
+
+function LiteLLMProxyFormFields(
+  props: OnboardingFormChildProps<LiteLLMProxyFormValues>
+) {
+  const {
+    formikProps,
+    apiStatus,
+    showApiMessage,
+    errorMessage,
+    modelOptions,
+    isFetchingModels,
+    handleFetchModels,
+    modelsApiStatus,
+    modelsErrorMessage,
+    showModelsApiErrorMessage,
+    disabled,
+  } = props;
+
+  const handleApiKeyInteraction = () => {
+    if (formikProps.values.api_key && formikProps.values.api_base) {
+      handleFetchModels();
+    }
+  };
+
+  return (
+    <>
+      <FormikField<string>
+        name={FIELD_API_BASE}
+        render={(field, _helper, meta, state) => (
+          <FormField name={FIELD_API_BASE} state={state} className="w-full">
+            <FormField.Label>API Base URL</FormField.Label>
+            <FormField.Control>
+              <InputTypeIn
+                {...field}
+                placeholder="http://localhost:4000"
+                variant={disabled ? "disabled" : undefined}
+                onBlur={(e: React.FocusEvent<HTMLInputElement>) => {
+                  field.onBlur(e);
+                  handleApiKeyInteraction();
+                }}
+              />
+            </FormField.Control>
+            <FormField.Message
+              messages={{
+                idle: "The base URL for your LiteLLM Proxy server.",
+                error: meta.error,
+              }}
+            />
+          </FormField>
+        )}
+      />
+
+      <FormikField<string>
+        name={FIELD_API_KEY}
+        render={(field, _helper, meta, state) => (
+          <FormField name={FIELD_API_KEY} state={state} className="w-full">
+            <FormField.Label>API Key</FormField.Label>
+            <FormField.Control>
+              <PasswordInputTypeIn
+                {...field}
+                placeholder=""
+                error={apiStatus === "error"}
+                showClearButton={false}
+                disabled={disabled}
+                onBlur={(e) => {
+                  field.onBlur(e);
+                  handleApiKeyInteraction();
+                }}
+              />
+            </FormField.Control>
+            {!showApiMessage && (
+              <FormField.Message
+                messages={{
+                  idle: "Enter the API key for your LiteLLM Proxy.",
+                  error: meta.error,
+                }}
+              />
+            )}
+            {showApiMessage && (
+              <FormField.APIMessage
+                state={apiStatus}
+                messages={{
+                  loading: "Checking API key with LiteLLM Proxy...",
+                  success: "API key valid. Your available models updated.",
+                  error: errorMessage || "Invalid API key",
+                }}
+              />
+            )}
+          </FormField>
+        )}
+      />
+
+      <Separator className="py-0" />
+
+      <FormikField<string>
+        name={FIELD_DEFAULT_MODEL_NAME}
+        render={(field, helper, meta, state) => (
+          <FormField
+            name={FIELD_DEFAULT_MODEL_NAME}
+            state={state}
+            className="w-full"
+          >
+            <FormField.Label>Default Model</FormField.Label>
+            <FormField.Control>
+              <InputComboBox
+                value={field.value}
+                onValueChange={(value) => helper.setValue(value)}
+                onChange={(e) => helper.setValue(e.target.value)}
+                options={modelOptions}
+                disabled={
+                  disabled || isFetchingModels || modelOptions.length === 0
+                }
+                rightSection={
+                  <Disabled disabled={disabled || isFetchingModels}>
+                    <Button
+                      prominence="tertiary"
+                      size="sm"
+                      icon={({ className }) => (
+                        <SvgRefreshCw
+                          className={cn(
+                            className,
+                            isFetchingModels && "animate-spin"
+                          )}
+                        />
+                      )}
+                      onClick={noProp((e) => {
+                        e.preventDefault();
+                        handleFetchModels();
+                      })}
+                      tooltip="Fetch available models"
+                    />
+                  </Disabled>
+                }
+                onBlur={field.onBlur}
+                placeholder="Select a model"
+              />
+            </FormField.Control>
+            {!showModelsApiErrorMessage && (
+              <FormField.Message
+                messages={{
+                  idle: "This model will be used by Onyx by default.",
+                  error: meta.error,
+                }}
+              />
+            )}
+            {showModelsApiErrorMessage && (
+              <FormField.APIMessage
+                state={modelsApiStatus}
+                messages={{
+                  loading: "Fetching models...",
+                  success: "Models fetched successfully.",
+                  error: modelsErrorMessage || "Failed to fetch models",
+                }}
+              />
+            )}
+          </FormField>
+        )}
+      />
+    </>
+  );
+}
+
+export function LiteLLMProxyOnboardingForm({
+  llmDescriptor,
+  onboardingState,
+  onboardingActions,
+  open,
+  onOpenChange,
+}: LiteLLMProxyOnboardingFormProps) {
+  const initialValues = useMemo(
+    (): LiteLLMProxyFormValues => ({
+      ...buildInitialValues(),
+      name: llmDescriptor.name,
+      provider: llmDescriptor.name,
+      api_base: "http://localhost:4000",
+    }),
+    [llmDescriptor.name]
+  );
+
+  const validationSchema = useMemo(
+    () =>
+      Yup.object().shape({
+        [FIELD_API_KEY]: Yup.string().required("API Key is required"),
+        [FIELD_API_BASE]: Yup.string().required("API Base URL is required"),
+        [FIELD_DEFAULT_MODEL_NAME]: Yup.string().required(
+          "Model name is required"
+        ),
+      }),
+    []
+  );
+
+  const icon = () => (
+    <ConnectionProviderIcon
+      icon={<ProviderIcon provider={llmDescriptor.name} size={24} />}
+    />
+  );
+
+  return (
+    <OnboardingFormWrapper<LiteLLMProxyFormValues>
+      icon={icon}
+      title="Set up LiteLLM Proxy"
+      description="Connect to your LiteLLM Proxy server and set up your models."
+      llmDescriptor={llmDescriptor}
+      onboardingState={onboardingState}
+      onboardingActions={onboardingActions}
+      open={open}
+      onOpenChange={onOpenChange}
+      initialValues={initialValues}
+      validationSchema={validationSchema}
+    >
+      {(props) => <LiteLLMProxyFormFields {...props} />}
+    </OnboardingFormWrapper>
+  );
+}
diff --git a/web/src/sections/onboarding/forms/getOnboardingForm.tsx b/web/src/sections/onboarding/forms/getOnboardingForm.tsx
index 90a56a4ebd0..a7d3a3d2bb2 100644
--- a/web/src/sections/onboarding/forms/getOnboardingForm.tsx
+++ b/web/src/sections/onboarding/forms/getOnboardingForm.tsx
@@ -12,6 +12,7 @@ import { AzureOnboardingForm } from "./AzureOnboardingForm";
 import { BedrockOnboardingForm } from "./BedrockOnboardingForm";
 import { VertexAIOnboardingForm } from "./VertexAIOnboardingForm";
 import { OpenRouterOnboardingForm } from "./OpenRouterOnboardingForm";
+import { LiteLLMProxyOnboardingForm } from "./LiteLLMProxyOnboardingForm";
 import { CustomOnboardingForm } from "./CustomOnboardingForm";
 
 // Display info for LLM provider cards - title is the product name, displayName is the company/platform
@@ -42,6 +43,10 @@ const PROVIDER_DISPLAY_INFO: Record<
     title: "LM Studio",
     displayName: "LM Studio",
   },
+  [LLMProviderName.LITELLM_PROXY]: {
+    title: "LiteLLM Proxy",
+    displayName: "LiteLLM Proxy",
+  },
 };
 
 export function getProviderDisplayInfo(providerName: string): {
@@ -175,6 +180,17 @@ export function getOnboardingForm({
         />
       );
 
+    case LLMProviderName.LITELLM_PROXY:
+      return (
+        <LiteLLMProxyOnboardingForm
+          llmDescriptor={llmDescriptor}
+          onboardingState={onboardingState}
+          onboardingActions={onboardingActions}
+          open={open}
+          onOpenChange={onOpenChange}
+        />
+      );
+
     default:
       // Fallback to custom form for unknown providers
       return (

From c5bfd5a152ef045911f075438d134028c972a61e Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 09:28:47 -0700
Subject: [PATCH 230/267] feat(admin): add Users page shell with stats bar and
 SCIM card - 1/9 (#9079)

---
 web/src/app/admin/users2/page.tsx             |   1 +
 web/src/components/admin/ClientLayout.tsx     |   1 +
 web/src/hooks/useUserCounts.ts                |  40 ++++++
 web/src/layouts/settings-layouts.tsx          |   2 +-
 web/src/lib/admin-routes.ts                   |   6 +
 web/src/refresh-pages/admin/UsersPage.tsx     |  58 +++++++++
 .../admin/UsersPage/UsersSummary.tsx          | 117 ++++++++++++++++++
 web/src/sections/sidebar/AdminSidebar.tsx     |  16 +--
 8 files changed, 232 insertions(+), 9 deletions(-)
 create mode 100644 web/src/app/admin/users2/page.tsx
 create mode 100644 web/src/hooks/useUserCounts.ts
 create mode 100644 web/src/refresh-pages/admin/UsersPage.tsx
 create mode 100644 web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx

diff --git a/web/src/app/admin/users2/page.tsx b/web/src/app/admin/users2/page.tsx
new file mode 100644
index 00000000000..1988d3c47c1
--- /dev/null
+++ b/web/src/app/admin/users2/page.tsx
@@ -0,0 +1 @@
+export { default } from "@/refresh-pages/admin/UsersPage";
diff --git a/web/src/components/admin/ClientLayout.tsx b/web/src/components/admin/ClientLayout.tsx
index 028f11806c4..06e3e8a0337 100644
--- a/web/src/components/admin/ClientLayout.tsx
+++ b/web/src/components/admin/ClientLayout.tsx
@@ -31,6 +31,7 @@ const SETTINGS_LAYOUT_PREFIXES = [
   ADMIN_PATHS.LLM_MODELS,
   ADMIN_PATHS.AGENTS,
   ADMIN_PATHS.USERS,
+  ADMIN_PATHS.USERS_V2,
   ADMIN_PATHS.TOKEN_RATE_LIMITS,
   ADMIN_PATHS.SEARCH_SETTINGS,
   ADMIN_PATHS.DOCUMENT_PROCESSING,
diff --git a/web/src/hooks/useUserCounts.ts b/web/src/hooks/useUserCounts.ts
new file mode 100644
index 00000000000..3cf6fc5a41d
--- /dev/null
+++ b/web/src/hooks/useUserCounts.ts
@@ -0,0 +1,40 @@
+"use client";
+
+import useSWR from "swr";
+import { errorHandlingFetcher } from "@/lib/fetcher";
+import type { InvitedUserSnapshot } from "@/lib/types";
+import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
+
+type PaginatedCountResponse = {
+  total_items: number;
+};
+
+type UserCounts = {
+  activeCount: number | null;
+  invitedCount: number | null;
+  pendingCount: number | null;
+};
+
+export default function useUserCounts(): UserCounts {
+  // Active user count — lightweight fetch (page_size=1 to minimize payload)
+  const { data: activeData } = useSWR<PaginatedCountResponse>(
+    "/api/manage/users/accepted?page_num=0&page_size=1",
+    errorHandlingFetcher
+  );
+
+  const { data: invitedUsers } = useSWR<InvitedUserSnapshot[]>(
+    "/api/manage/users/invited",
+    errorHandlingFetcher
+  );
+
+  const { data: pendingUsers } = useSWR<InvitedUserSnapshot[]>(
+    NEXT_PUBLIC_CLOUD_ENABLED ? "/api/tenants/users/pending" : null,
+    errorHandlingFetcher
+  );
+
+  return {
+    activeCount: activeData?.total_items ?? null,
+    invitedCount: invitedUsers?.length ?? null,
+    pendingCount: pendingUsers?.length ?? null,
+  };
+}
diff --git a/web/src/layouts/settings-layouts.tsx b/web/src/layouts/settings-layouts.tsx
index fccb163c93f..84fcaf609d6 100644
--- a/web/src/layouts/settings-layouts.tsx
+++ b/web/src/layouts/settings-layouts.tsx
@@ -230,7 +230,7 @@ function SettingsHeader({
         </div>
       )}
 
-      <Spacer vertical rem={1} />
+      <Spacer vertical rem={2.5} />
 
       <div className="flex flex-col gap-6 px-4">
         <div className="flex w-full justify-between">
diff --git a/web/src/lib/admin-routes.ts b/web/src/lib/admin-routes.ts
index adafc8c2b1d..20514f43ff6 100644
--- a/web/src/lib/admin-routes.ts
+++ b/web/src/lib/admin-routes.ts
@@ -58,6 +58,7 @@ export const ADMIN_PATHS = {
   DOCUMENT_PROCESSING: "/admin/configuration/document-processing",
   KNOWLEDGE_GRAPH: "/admin/kg",
   USERS: "/admin/users",
+  USERS_V2: "/admin/users2",
   API_KEYS: "/admin/api-key",
   TOKEN_RATE_LIMITS: "/admin/token-rate-limits",
   USAGE: "/admin/performance/usage",
@@ -190,6 +191,11 @@ export const ADMIN_ROUTE_CONFIG: Record<string, AdminRouteConfig> = {
     title: "Manage Users",
     sidebarLabel: "Users",
   },
+  [ADMIN_PATHS.USERS_V2]: {
+    icon: SvgUser,
+    title: "Users & Requests",
+    sidebarLabel: "Users v2",
+  },
   [ADMIN_PATHS.API_KEYS]: {
     icon: SvgKey,
     title: "API Keys",
diff --git a/web/src/refresh-pages/admin/UsersPage.tsx b/web/src/refresh-pages/admin/UsersPage.tsx
new file mode 100644
index 00000000000..b94ddcf87de
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { SvgUser, SvgUserPlus } from "@opal/icons";
+import { Button } from "@opal/components";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { useScimToken } from "@/hooks/useScimToken";
+import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
+import useUserCounts from "@/hooks/useUserCounts";
+
+import UsersSummary from "./UsersPage/UsersSummary";
+
+// ---------------------------------------------------------------------------
+// Users page content
+// ---------------------------------------------------------------------------
+
+function UsersContent() {
+  const isEe = usePaidEnterpriseFeaturesEnabled();
+
+  const { data: scimToken } = useScimToken();
+  const showScim = isEe && !!scimToken;
+
+  const { activeCount, invitedCount, pendingCount } = useUserCounts();
+
+  return (
+    <>
+      <UsersSummary
+        activeUsers={activeCount}
+        pendingInvites={invitedCount}
+        requests={pendingCount}
+        showScim={showScim}
+      />
+
+      {/* Table and filters will be added in subsequent PRs */}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
+export default function UsersPage() {
+  return (
+    <SettingsLayouts.Root width="lg">
+      <SettingsLayouts.Header
+        title="Users & Requests"
+        icon={SvgUser}
+        rightChildren={
+          // TODO (ENG-3806): Wire up invite modal
+          <Button icon={SvgUserPlus}>Invite Users</Button>
+        }
+      />
+      <SettingsLayouts.Body>
+        <UsersContent />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx b/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
new file mode 100644
index 00000000000..afe6ffd98a6
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
@@ -0,0 +1,117 @@
+import { SvgArrowUpRight, SvgUserSync } from "@opal/icons";
+import { ContentAction } from "@opal/layouts";
+import { Button } from "@opal/components";
+import { Section } from "@/layouts/general-layouts";
+import Card from "@/refresh-components/cards/Card";
+import Text from "@/refresh-components/texts/Text";
+import Link from "next/link";
+import { ADMIN_PATHS } from "@/lib/admin-routes";
+
+// ---------------------------------------------------------------------------
+// Stats cell — number + label
+// ---------------------------------------------------------------------------
+
+type StatCellProps = {
+  value: number | null;
+  label: string;
+};
+
+function StatCell({ value, label }: StatCellProps) {
+  const display = value === null ? "\u2014" : value.toLocaleString();
+
+  return (
+    <div className="flex flex-col items-start gap-0.5 w-full p-2">
+      <Text as="span" mainUiAction text04>
+        {display}
+      </Text>
+      <Text as="span" secondaryBody text03>
+        {label}
+      </Text>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// SCIM card
+// ---------------------------------------------------------------------------
+
+function ScimCard() {
+  return (
+    <Card gap={0.5} padding={0.75}>
+      <ContentAction
+        icon={SvgUserSync}
+        title="SCIM Sync"
+        description="Users are synced from your identity provider."
+        sizePreset="main-ui"
+        variant="section"
+        paddingVariant="fit"
+        rightChildren={
+          <Link href={ADMIN_PATHS.SCIM}>
+            <Button prominence="tertiary" rightIcon={SvgArrowUpRight} size="sm">
+              Manage
+            </Button>
+          </Link>
+        }
+      />
+    </Card>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Stats bar — layout varies by SCIM status
+// ---------------------------------------------------------------------------
+
+type UsersSummaryProps = {
+  activeUsers: number | null;
+  pendingInvites: number | null;
+  requests: number | null;
+  showScim: boolean;
+};
+
+export default function UsersSummary({
+  activeUsers,
+  pendingInvites,
+  requests,
+  showScim,
+}: UsersSummaryProps) {
+  const showRequests = requests !== null && requests > 0;
+
+  if (showScim) {
+    return (
+      <Section
+        flexDirection="row"
+        justifyContent="start"
+        alignItems="stretch"
+        gap={0.5}
+      >
+        <Card padding={0.5}>
+          <Section flexDirection="row" gap={0}>
+            <StatCell value={activeUsers} label="active users" />
+            <StatCell value={pendingInvites} label="pending invites" />
+            {showRequests && (
+              <StatCell value={requests} label="requests to join" />
+            )}
+          </Section>
+        </Card>
+        <ScimCard />
+      </Section>
+    );
+  }
+
+  // No SCIM — each stat gets its own card
+  return (
+    <Section flexDirection="row" gap={0.5}>
+      <Card padding={0.5}>
+        <StatCell value={activeUsers} label="active users" />
+      </Card>
+      <Card padding={0.5}>
+        <StatCell value={pendingInvites} label="pending invites" />
+      </Card>
+      {showRequests && (
+        <Card padding={0.5}>
+          <StatCell value={requests} label="requests to join" />
+        </Card>
+      )}
+    </Section>
+  );
+}
diff --git a/web/src/sections/sidebar/AdminSidebar.tsx b/web/src/sections/sidebar/AdminSidebar.tsx
index fadd543c52b..078ba14028f 100644
--- a/web/src/sections/sidebar/AdminSidebar.tsx
+++ b/web/src/sections/sidebar/AdminSidebar.tsx
@@ -127,14 +127,14 @@ const collections = (
               sidebarItem(ADMIN_PATHS.TOKEN_RATE_LIMITS),
             ],
           },
-          ...(enableEnterprise
-            ? [
-                {
-                  name: "Permissions",
-                  items: [sidebarItem(ADMIN_PATHS.SCIM)],
-                },
-              ]
-            : []),
+          {
+            name: "Permissions",
+            items: [
+              // TODO (nikolas): Uncommented in switchover PR once Users v2 is ready
+              // sidebarItem(ADMIN_PATHS.USERS_V2),
+              ...(enableEnterprise ? [sidebarItem(ADMIN_PATHS.SCIM)] : []),
+            ],
+          },
           ...(enableEnterprise
             ? [
                 {

From 84c52a42a25527a08a37ce67a151e64e48976adf Mon Sep 17 00:00:00 2001
From: MrGoodKitten <99104898+MrGoodKitten@users.noreply.github.com>
Date: Wed, 11 Mar 2026 16:01:00 -0400
Subject: [PATCH 231/267] Enhance README with ONYX.AI and assistant-ui details

Added detailed information about ONYX.AI and assistant-ui integration, including features, benefits, and getting started instructions.
---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/README.md b/README.md
index cb14ef67dc2..82ddf3441eb 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,85 @@ See guides below:
 > [!TIP]  
 > **To try Onyx for free without deploying, check out [Onyx Cloud](https://cloud.onyx.app/signup?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)**.
 
+# ONYX.AI App
+
+CREATED BY ZEUS  
+// ONYX.AI 4 Core Entry  
+// Origin: AI.ALIVE (ONYXONMIBOOK)  
+// CreatedOn: 2025-11-22
+
+<a name="readme-top"></a>
+
+<h2 align="center">
+  <a href="https://www.onyx.app/?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme">
+    <img width="50%" src="https://github.com/onyx-dot-app/onyx/blob/logo/OnyxLogoCropped.jpg?raw=true" />
+  </a>
+</h2>
+
+<p align="center">Open Source AI Platform</p>
+
+<p align="center">
+  <a href="https://discord.gg/TDJ59cGV2X" target="_blank">
+    <img src="https://img.shields.io/badge/discord-join-blue.svg?logo=discord&logoColor=white" alt="Discord" />
+  </a>
+  <a href="https://docs.onyx.app/?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme" target="_blank">
+    <img src="https://img.shields.io/badge/docs-view-blue" alt="Documentation" />
+  </a>
+</p>
+
+---
+
+ONYX.AI is a concrete, production-focused AI assistant platform designed for secure, scalable, real-world deployments.
+
+---
+
+<a href="https://www.assistant-ui.com">
+  <img src="https://raw.githubusercontent.com/assistant-ui/assistant-ui/main/.github/assets/header.svg" alt="assistant-ui Header" width="100%" />
+</a>
+
+<p align="center">
+  <a href="https://www.assistant-ui.com">Product</a> ·
+  <a href="https://www.assistant-ui.com/docs">Documentation</a> ·
+  <a href="https://www.assistant-ui.com/examples">Examples</a> ·
+  <a href="https://discord.gg/S9dwgCNEFs">Discord Community</a> ·
+  <a href="https://cal.com/simon-farshid/assistant-ui">Contact Sales</a>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@assistant-ui/react)](https://www.npmjs.com/package/@assistant-ui/react)
+[![npm downloads](https://img.shields.io/npm/dm/@assistant-ui/react)](https://www.npmjs.com/package/@assistant-ui/react)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/assistant-ui/assistant-ui)
+[![Weave Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapp.workweave.ai%2Fapi%2Frepository%2Fbadge%2Forg_GhSIrtWo37b5B3Mv0At3wQ1Q%2F722184017&cacheSeconds=3600)](https://app.workweave.ai/reports/repository/org_GhSIrtWo37b5B3Mv0At3wQ1Q/722184017)
+![GitHub License](https://img.shields.io/github/license/assistant-ui/assistant-ui)
+![Backed by Y Combinator](https://img.shields.io/badge/Backed_by-Y_Combinator-orange)
+
+[⭐️ Star assistant-ui on GitHub](https://github.com/assistant-ui/assistant-ui)
+
+## The UX of ChatGPT in your ONYX.AI app
+
+This app integrates **assistant-ui**, an open source TypeScript/React library, to deliver production-grade AI chat inside ONYX.AI.
+
+- Handles streaming, auto-scrolling, accessibility, and real-time updates for you  
+- Fully composable primitives inspired by shadcn/ui and cmdk — customize every pixel  
+- Works with your stack: AI SDK, LangGraph, Mastra, or any custom backend  
+- Broad model support out of the box (OpenAI, Anthropic, Mistral, Perplexity, AWS Bedrock, Azure, Google Gemini, Hugging Face, Fireworks, Cohere, Replicate, Ollama) with easy extension to custom APIs
+
+## Why assistant-ui in ONYX.AI
+
+- **Fast to production**: battle-tested primitives, built-in streaming and attachments  
+- **Designed for customization**: composable pieces instead of a monolithic widget  
+- **Great DX**: sensible defaults, keyboard shortcuts, a11y, and strong TypeScript  
+- **Enterprise-ready**: optional chat history and analytics via Assistant Cloud
+
+## Getting Started
+
+Run one of the following in your terminal in this repo:
+
+```bash
+# install deps
+pnpm install
+
+# dev server
+pnpm dev
 
 
 ## 🔍 Other Notable Benefits

From 6499b21235423dfb1f59589adc7fbb328c099c83 Mon Sep 17 00:00:00 2001
From: Raunak Bhagat <r@rabh.io>
Date: Wed, 11 Mar 2026 13:14:17 -0700
Subject: [PATCH 232/267] feat(opal): add Card and EmptyMessageCard components
 (#9271)

---
 .../components/cards/card/Card.stories.tsx    |  87 ++++++
 .../opal/src/components/cards/card/README.md  |  67 ++++
 .../src/components/cards/card/components.tsx  | 101 +++++++
 .../opal/src/components/cards/card/styles.css |  29 ++
 .../EmptyMessageCard.stories.tsx              |  51 ++++
 .../cards/empty-message-card/README.md        |  30 ++
 .../cards/empty-message-card/components.tsx   |  57 ++++
 web/lib/opal/src/components/index.ts          |  14 +
 .../layouts/content/BodyLayout.stories.tsx    |  87 ------
 .../opal/src/layouts/content/BodyLayout.tsx   | 134 --------
 .../layouts/content/HeadingLayout.stories.tsx |  98 ------
 .../src/layouts/content/HeadingLayout.tsx     | 218 -------------
 .../layouts/content/LabelLayout.stories.tsx   | 154 ----------
 .../opal/src/layouts/content/LabelLayout.tsx  | 286 ------------------
 14 files changed, 436 insertions(+), 977 deletions(-)
 create mode 100644 web/lib/opal/src/components/cards/card/Card.stories.tsx
 create mode 100644 web/lib/opal/src/components/cards/card/README.md
 create mode 100644 web/lib/opal/src/components/cards/card/components.tsx
 create mode 100644 web/lib/opal/src/components/cards/card/styles.css
 create mode 100644 web/lib/opal/src/components/cards/empty-message-card/EmptyMessageCard.stories.tsx
 create mode 100644 web/lib/opal/src/components/cards/empty-message-card/README.md
 create mode 100644 web/lib/opal/src/components/cards/empty-message-card/components.tsx
 delete mode 100644 web/lib/opal/src/layouts/content/BodyLayout.stories.tsx
 delete mode 100644 web/lib/opal/src/layouts/content/BodyLayout.tsx
 delete mode 100644 web/lib/opal/src/layouts/content/HeadingLayout.stories.tsx
 delete mode 100644 web/lib/opal/src/layouts/content/HeadingLayout.tsx
 delete mode 100644 web/lib/opal/src/layouts/content/LabelLayout.stories.tsx
 delete mode 100644 web/lib/opal/src/layouts/content/LabelLayout.tsx

diff --git a/web/lib/opal/src/components/cards/card/Card.stories.tsx b/web/lib/opal/src/components/cards/card/Card.stories.tsx
new file mode 100644
index 00000000000..1d39632299b
--- /dev/null
+++ b/web/lib/opal/src/components/cards/card/Card.stories.tsx
@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "@opal/components";
+
+const BACKGROUND_VARIANTS = ["none", "light", "heavy"] as const;
+const BORDER_VARIANTS = ["none", "dashed", "solid"] as const;
+const SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
+
+const meta: Meta<typeof Card> = {
+  title: "opal/components/Card",
+  component: Card,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  render: () => (
+    <Card>
+      <p>Default card with light background, no border, lg size.</p>
+    </Card>
+  ),
+};
+
+export const BackgroundVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-96">
+      {BACKGROUND_VARIANTS.map((bg) => (
+        <Card key={bg} backgroundVariant={bg} borderVariant="solid">
+          <p>backgroundVariant: {bg}</p>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+export const BorderVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-96">
+      {BORDER_VARIANTS.map((border) => (
+        <Card key={border} borderVariant={border}>
+          <p>borderVariant: {border}</p>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+export const SizeVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-96">
+      {SIZE_VARIANTS.map((size) => (
+        <Card key={size} sizeVariant={size} borderVariant="solid">
+          <p>sizeVariant: {size}</p>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+export const AllCombinations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      {SIZE_VARIANTS.map((size) => (
+        <div key={size}>
+          <p className="font-bold pb-2">sizeVariant: {size}</p>
+          <div className="grid grid-cols-3 gap-4">
+            {BACKGROUND_VARIANTS.map((bg) =>
+              BORDER_VARIANTS.map((border) => (
+                <Card
+                  key={`${size}-${bg}-${border}`}
+                  sizeVariant={size}
+                  backgroundVariant={bg}
+                  borderVariant={border}
+                >
+                  <p className="text-xs">
+                    bg: {bg}, border: {border}
+                  </p>
+                </Card>
+              ))
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+};
diff --git a/web/lib/opal/src/components/cards/card/README.md b/web/lib/opal/src/components/cards/card/README.md
new file mode 100644
index 00000000000..054bffcab4c
--- /dev/null
+++ b/web/lib/opal/src/components/cards/card/README.md
@@ -0,0 +1,67 @@
+# Card
+
+**Import:** `import { Card, type CardProps } from "@opal/components";`
+
+A plain container component with configurable background, border, padding, and rounding. Uses a simple `<div>` internally with `overflow-clip`.
+
+## Architecture
+
+The `sizeVariant` controls both padding and border-radius, mirroring the same mapping used by `Button` and `Interactive.Container`:
+
+| Size      | Padding | Rounding       |
+|-----------|---------|----------------|
+| `lg`      | `p-2`   | `rounded-12`   |
+| `md`      | `p-1`   | `rounded-08`   |
+| `sm`      | `p-1`   | `rounded-08`   |
+| `xs`      | `p-0.5` | `rounded-04`   |
+| `2xs`     | `p-0.5` | `rounded-04`   |
+| `fit`     | `p-0`   | `rounded-12`   |
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sizeVariant` | `SizeVariant` | `"lg"` | Controls padding and border-radius |
+| `backgroundVariant` | `"none" \| "light" \| "heavy"` | `"light"` | Background fill intensity |
+| `borderVariant` | `"none" \| "dashed" \| "solid"` | `"none"` | Border style |
+| `ref` | `React.Ref<HTMLDivElement>` | — | Ref forwarded to the root div |
+| `children` | `React.ReactNode` | — | Card content |
+
+## Background Variants
+
+- **`none`** — Transparent background. Use for seamless inline content.
+- **`light`** — Subtle tinted background (`bg-background-tint-00`). The default, suitable for most cards.
+- **`heavy`** — Stronger tinted background (`bg-background-tint-01`). Use for emphasis or nested cards that need visual separation.
+
+## Border Variants
+
+- **`none`** — No border. Use when cards are visually grouped or in tight layouts.
+- **`dashed`** — Dashed border. Use for placeholder or empty states.
+- **`solid`** — Solid border. Use for prominent, standalone cards.
+
+## Usage
+
+```tsx
+import { Card } from "@opal/components";
+
+// Default card (light background, no border, lg padding + rounding)
+<Card>
+  <h2>Card Title</h2>
+  <p>Card content</p>
+</Card>
+
+// Compact card with solid border
+<Card borderVariant="solid" sizeVariant="sm">
+  <p>Compact card</p>
+</Card>
+
+// Empty state card
+<Card backgroundVariant="none" borderVariant="dashed">
+  <p>No items yet</p>
+</Card>
+
+// Heavy background, tight padding
+<Card backgroundVariant="heavy" sizeVariant="xs">
+  <p>Highlighted content</p>
+</Card>
+```
diff --git a/web/lib/opal/src/components/cards/card/components.tsx b/web/lib/opal/src/components/cards/card/components.tsx
new file mode 100644
index 00000000000..6ea52f573dd
--- /dev/null
+++ b/web/lib/opal/src/components/cards/card/components.tsx
@@ -0,0 +1,101 @@
+import "@opal/components/cards/card/styles.css";
+import type { SizeVariant } from "@opal/shared";
+import { sizeVariants } from "@opal/shared";
+import { cn } from "@opal/utils";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type BackgroundVariant = "none" | "light" | "heavy";
+type BorderVariant = "none" | "dashed" | "solid";
+
+type CardProps = {
+  /**
+   * Size preset — controls padding and border-radius.
+   *
+   * Padding comes from the shared size scale. Rounding follows the same
+   * mapping as `Button` / `Interactive.Container`:
+   *
+   * | Size   | Rounding   |
+   * |--------|------------|
+   * | `lg`   | `default`  |
+   * | `md`–`sm` | `compact` |
+   * | `xs`–`2xs` | `mini`  |
+   * | `fit`  | `default`  |
+   *
+   * @default "lg"
+   */
+  sizeVariant?: SizeVariant;
+
+  /**
+   * Background fill intensity.
+   * - `"none"`: transparent background.
+   * - `"light"`: subtle tinted background (`bg-background-tint-00`).
+   * - `"heavy"`: stronger tinted background (`bg-background-tint-01`).
+   *
+   * @default "light"
+   */
+  backgroundVariant?: BackgroundVariant;
+
+  /**
+   * Border style.
+   * - `"none"`: no border.
+   * - `"dashed"`: dashed border.
+   * - `"solid"`: solid border.
+   *
+   * @default "none"
+   */
+  borderVariant?: BorderVariant;
+
+  /** Ref forwarded to the root `<div>`. */
+  ref?: React.Ref<HTMLDivElement>;
+
+  children?: React.ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Rounding
+// ---------------------------------------------------------------------------
+
+/** Maps a size variant to a rounding class, mirroring the Button pattern. */
+const roundingForSize: Record<SizeVariant, string> = {
+  lg: "rounded-12",
+  md: "rounded-08",
+  sm: "rounded-08",
+  xs: "rounded-04",
+  "2xs": "rounded-04",
+  fit: "rounded-12",
+};
+
+// ---------------------------------------------------------------------------
+// Card
+// ---------------------------------------------------------------------------
+
+function Card({
+  sizeVariant = "lg",
+  backgroundVariant = "light",
+  borderVariant = "none",
+  ref,
+  children,
+}: CardProps) {
+  const { padding } = sizeVariants[sizeVariant];
+  const rounding = roundingForSize[sizeVariant];
+
+  return (
+    <div
+      ref={ref}
+      className={cn("opal-card", padding, rounding)}
+      data-background={backgroundVariant}
+      data-border={borderVariant}
+    >
+      {children}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export { Card, type CardProps, type BackgroundVariant, type BorderVariant };
diff --git a/web/lib/opal/src/components/cards/card/styles.css b/web/lib/opal/src/components/cards/card/styles.css
new file mode 100644
index 00000000000..1df3efb039b
--- /dev/null
+++ b/web/lib/opal/src/components/cards/card/styles.css
@@ -0,0 +1,29 @@
+.opal-card {
+  @apply w-full overflow-clip;
+}
+
+/* Background variants */
+.opal-card[data-background="none"] {
+  @apply bg-transparent;
+}
+
+.opal-card[data-background="light"] {
+  @apply bg-background-tint-00;
+}
+
+.opal-card[data-background="heavy"] {
+  @apply bg-background-tint-01;
+}
+
+/* Border variants */
+.opal-card[data-border="none"] {
+  border: none;
+}
+
+.opal-card[data-border="dashed"] {
+  @apply border border-dashed;
+}
+
+.opal-card[data-border="solid"] {
+  @apply border;
+}
diff --git a/web/lib/opal/src/components/cards/empty-message-card/EmptyMessageCard.stories.tsx b/web/lib/opal/src/components/cards/empty-message-card/EmptyMessageCard.stories.tsx
new file mode 100644
index 00000000000..6e552b6706f
--- /dev/null
+++ b/web/lib/opal/src/components/cards/empty-message-card/EmptyMessageCard.stories.tsx
@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { EmptyMessageCard } from "@opal/components";
+import { SvgSparkle, SvgUsers } from "@opal/icons";
+
+const SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
+
+const meta: Meta<typeof EmptyMessageCard> = {
+  title: "opal/components/EmptyMessageCard",
+  component: EmptyMessageCard,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof EmptyMessageCard>;
+
+export const Default: Story = {
+  args: {
+    title: "No items available.",
+  },
+};
+
+export const WithCustomIcon: Story = {
+  args: {
+    icon: SvgSparkle,
+    title: "No agents selected.",
+  },
+};
+
+export const SizeVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-96">
+      {SIZE_VARIANTS.map((size) => (
+        <EmptyMessageCard
+          key={size}
+          sizeVariant={size}
+          title={`sizeVariant: ${size}`}
+        />
+      ))}
+    </div>
+  ),
+};
+
+export const Multiple: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-96">
+      <EmptyMessageCard title="No models available." />
+      <EmptyMessageCard icon={SvgSparkle} title="No agents selected." />
+      <EmptyMessageCard icon={SvgUsers} title="No groups added." />
+    </div>
+  ),
+};
diff --git a/web/lib/opal/src/components/cards/empty-message-card/README.md b/web/lib/opal/src/components/cards/empty-message-card/README.md
new file mode 100644
index 00000000000..769826d6733
--- /dev/null
+++ b/web/lib/opal/src/components/cards/empty-message-card/README.md
@@ -0,0 +1,30 @@
+# EmptyMessageCard
+
+**Import:** `import { EmptyMessageCard, type EmptyMessageCardProps } from "@opal/components";`
+
+A pre-configured Card for empty states. Renders a transparent card with a dashed border containing a muted icon and message text using the `Content` layout.
+
+## Props
+
+| Prop          | Type                       | Default    | Description                                      |
+| ------------- | -------------------------- | ---------- | ------------------------------------------------ |
+| `icon`        | `IconFunctionComponent`    | `SvgEmpty` | Icon displayed alongside the title               |
+| `title`       | `string`                   | —          | Primary message text (required)                  |
+| `sizeVariant` | `SizeVariant`              | `"lg"`     | Size preset controlling padding and rounding     |
+| `ref`         | `React.Ref<HTMLDivElement>` | —          | Ref forwarded to the root div                    |
+
+## Usage
+
+```tsx
+import { EmptyMessageCard } from "@opal/components";
+import { SvgSparkle, SvgFileText } from "@opal/icons";
+
+// Default empty state
+<EmptyMessageCard title="No items yet." />
+
+// With custom icon
+<EmptyMessageCard icon={SvgSparkle} title="No agents selected." />
+
+// With custom size
+<EmptyMessageCard sizeVariant="sm" icon={SvgFileText} title="No documents available." />
+```
diff --git a/web/lib/opal/src/components/cards/empty-message-card/components.tsx b/web/lib/opal/src/components/cards/empty-message-card/components.tsx
new file mode 100644
index 00000000000..c3ac6cc14b4
--- /dev/null
+++ b/web/lib/opal/src/components/cards/empty-message-card/components.tsx
@@ -0,0 +1,57 @@
+import { Card } from "@opal/components/cards/card/components";
+import { Content } from "@opal/layouts";
+import { SvgEmpty } from "@opal/icons";
+import type { SizeVariant } from "@opal/shared";
+import type { IconFunctionComponent } from "@opal/types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type EmptyMessageCardProps = {
+  /** Icon displayed alongside the title. */
+  icon?: IconFunctionComponent;
+
+  /** Primary message text. */
+  title: string;
+
+  /** Size preset controlling padding and rounding of the card. */
+  sizeVariant?: SizeVariant;
+
+  /** Ref forwarded to the root Card div. */
+  ref?: React.Ref<HTMLDivElement>;
+};
+
+// ---------------------------------------------------------------------------
+// EmptyMessageCard
+// ---------------------------------------------------------------------------
+
+function EmptyMessageCard({
+  icon = SvgEmpty,
+  title,
+  sizeVariant = "lg",
+  ref,
+}: EmptyMessageCardProps) {
+  return (
+    <Card
+      ref={ref}
+      backgroundVariant="none"
+      borderVariant="dashed"
+      sizeVariant={sizeVariant}
+    >
+      <Content
+        icon={icon}
+        title={title}
+        sizePreset="secondary"
+        variant="body"
+        prominence="muted"
+      />
+    </Card>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export { EmptyMessageCard, type EmptyMessageCardProps };
diff --git a/web/lib/opal/src/components/index.ts b/web/lib/opal/src/components/index.ts
index ea3d58dee2c..8d115b26609 100644
--- a/web/lib/opal/src/components/index.ts
+++ b/web/lib/opal/src/components/index.ts
@@ -31,3 +31,17 @@ export {
   type TagProps,
   type TagColor,
 } from "@opal/components/tag/components";
+
+/* Card */
+export {
+  Card,
+  type CardProps,
+  type BackgroundVariant,
+  type BorderVariant,
+} from "@opal/components/cards/card/components";
+
+/* EmptyMessageCard */
+export {
+  EmptyMessageCard,
+  type EmptyMessageCardProps,
+} from "@opal/components/cards/empty-message-card/components";
diff --git a/web/lib/opal/src/layouts/content/BodyLayout.stories.tsx b/web/lib/opal/src/layouts/content/BodyLayout.stories.tsx
deleted file mode 100644
index 4908a2b0ca0..00000000000
--- a/web/lib/opal/src/layouts/content/BodyLayout.stories.tsx
+++ /dev/null
@@ -1,87 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { BodyLayout } from "./BodyLayout";
-import { SvgSettings, SvgStar, SvgRefreshCw } from "@opal/icons";
-
-const meta = {
-  title: "Layouts/BodyLayout",
-  component: BodyLayout,
-  tags: ["autodocs"],
-  parameters: {
-    layout: "centered",
-  },
-} satisfies Meta<typeof BodyLayout>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-// ---------------------------------------------------------------------------
-// Size presets
-// ---------------------------------------------------------------------------
-
-export const MainContent: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Last synced 2 minutes ago",
-  },
-};
-
-export const MainUi: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Document count: 1,234",
-  },
-};
-
-export const Secondary: Story = {
-  args: {
-    sizePreset: "secondary",
-    title: "Updated 5 min ago",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// With icon
-// ---------------------------------------------------------------------------
-
-export const WithIcon: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Settings",
-    icon: SvgSettings,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Orientations
-// ---------------------------------------------------------------------------
-
-export const Vertical: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Stacked layout",
-    icon: SvgStar,
-    orientation: "vertical",
-  },
-};
-
-export const Reverse: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Reverse layout",
-    icon: SvgRefreshCw,
-    orientation: "reverse",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Prominence
-// ---------------------------------------------------------------------------
-
-export const Muted: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Muted body text",
-    prominence: "muted",
-  },
-};
diff --git a/web/lib/opal/src/layouts/content/BodyLayout.tsx b/web/lib/opal/src/layouts/content/BodyLayout.tsx
deleted file mode 100644
index 569d407df54..00000000000
--- a/web/lib/opal/src/layouts/content/BodyLayout.tsx
+++ /dev/null
@@ -1,134 +0,0 @@
-"use client";
-
-import type { IconFunctionComponent } from "@opal/types";
-import { cn } from "@opal/utils";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type BodySizePreset = "main-content" | "main-ui" | "secondary";
-type BodyOrientation = "vertical" | "inline" | "reverse";
-type BodyProminence = "default" | "muted";
-
-interface BodyPresetConfig {
-  /** Icon width/height (CSS value). */
-  iconSize: string;
-  /** Tailwind padding class for the icon container. */
-  iconContainerPadding: string;
-  /** Tailwind font class for the title. */
-  titleFont: string;
-  /** Title line-height — also used as icon container min-height (CSS value). */
-  lineHeight: string;
-  /** Gap between icon container and title (CSS value). */
-  gap: string;
-}
-
-/** Props for {@link BodyLayout}. Does not support editing or descriptions. */
-interface BodyLayoutProps {
-  /** Optional icon component. */
-  icon?: IconFunctionComponent;
-
-  /** Main title text (read-only — editing is not supported). */
-  title: string;
-
-  /** Size preset. Default: `"main-ui"`. */
-  sizePreset?: BodySizePreset;
-
-  /** Layout orientation. Default: `"inline"`. */
-  orientation?: BodyOrientation;
-
-  /** Title prominence. Default: `"default"`. */
-  prominence?: BodyProminence;
-
-  /** Ref forwarded to the root `<div>`. */
-  ref?: React.Ref<HTMLDivElement>;
-}
-
-// ---------------------------------------------------------------------------
-// Presets
-// ---------------------------------------------------------------------------
-
-const BODY_PRESETS: Record<BodySizePreset, BodyPresetConfig> = {
-  "main-content": {
-    iconSize: "1rem",
-    iconContainerPadding: "p-1",
-    titleFont: "font-main-content-body",
-    lineHeight: "1.5rem",
-    gap: "0.125rem",
-  },
-  "main-ui": {
-    iconSize: "1rem",
-    iconContainerPadding: "p-0.5",
-    titleFont: "font-main-ui-action",
-    lineHeight: "1.25rem",
-    gap: "0.25rem",
-  },
-  secondary: {
-    iconSize: "0.75rem",
-    iconContainerPadding: "p-0.5",
-    titleFont: "font-secondary-action",
-    lineHeight: "1rem",
-    gap: "0.125rem",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// BodyLayout
-// ---------------------------------------------------------------------------
-
-function BodyLayout({
-  icon: Icon,
-  title,
-  sizePreset = "main-ui",
-  orientation = "inline",
-  prominence = "default",
-  ref,
-}: BodyLayoutProps) {
-  const config = BODY_PRESETS[sizePreset];
-  const titleColorClass =
-    prominence === "muted" ? "text-text-03" : "text-text-04";
-
-  return (
-    <div
-      ref={ref}
-      className="opal-content-body"
-      data-orientation={orientation}
-      style={{ gap: config.gap }}
-    >
-      {Icon && (
-        <div
-          className={cn(
-            "opal-content-body-icon-container shrink-0",
-            config.iconContainerPadding
-          )}
-          style={{ minHeight: config.lineHeight }}
-        >
-          <Icon
-            className="opal-content-body-icon text-text-03"
-            style={{ width: config.iconSize, height: config.iconSize }}
-          />
-        </div>
-      )}
-
-      <span
-        className={cn(
-          "opal-content-body-title",
-          config.titleFont,
-          titleColorClass
-        )}
-        style={{ height: config.lineHeight }}
-      >
-        {title}
-      </span>
-    </div>
-  );
-}
-
-export {
-  BodyLayout,
-  type BodyLayoutProps,
-  type BodySizePreset,
-  type BodyOrientation,
-  type BodyProminence,
-};
diff --git a/web/lib/opal/src/layouts/content/HeadingLayout.stories.tsx b/web/lib/opal/src/layouts/content/HeadingLayout.stories.tsx
deleted file mode 100644
index 562bbfa7db3..00000000000
--- a/web/lib/opal/src/layouts/content/HeadingLayout.stories.tsx
+++ /dev/null
@@ -1,98 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { HeadingLayout } from "./HeadingLayout";
-import { SvgSettings, SvgStar } from "@opal/icons";
-import * as TooltipPrimitive from "@radix-ui/react-tooltip";
-
-const meta = {
-  title: "Layouts/HeadingLayout",
-  component: HeadingLayout,
-  tags: ["autodocs"],
-  parameters: {
-    layout: "centered",
-  },
-  decorators: [
-    (Story) => (
-      <TooltipPrimitive.Provider>
-        <Story />
-      </TooltipPrimitive.Provider>
-    ),
-  ],
-} satisfies Meta<typeof HeadingLayout>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-// ---------------------------------------------------------------------------
-// Size presets
-// ---------------------------------------------------------------------------
-
-export const Headline: Story = {
-  args: {
-    sizePreset: "headline",
-    title: "Welcome to Onyx",
-    description: "Your enterprise search and AI assistant platform.",
-  },
-};
-
-export const Section: Story = {
-  args: {
-    sizePreset: "section",
-    title: "Configuration",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// With icon
-// ---------------------------------------------------------------------------
-
-export const WithIcon: Story = {
-  args: {
-    sizePreset: "headline",
-    title: "Settings",
-    icon: SvgSettings,
-  },
-};
-
-export const SectionWithIcon: Story = {
-  args: {
-    sizePreset: "section",
-    variant: "section",
-    title: "Favorites",
-    icon: SvgStar,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Variants
-// ---------------------------------------------------------------------------
-
-export const SectionVariant: Story = {
-  args: {
-    sizePreset: "headline",
-    variant: "section",
-    title: "Inline Icon Heading",
-    icon: SvgSettings,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Editable
-// ---------------------------------------------------------------------------
-
-export const Editable: Story = {
-  args: {
-    sizePreset: "headline",
-    title: "Click to edit me",
-    editable: true,
-  },
-};
-
-export const EditableSection: Story = {
-  args: {
-    sizePreset: "section",
-    title: "Editable Section Title",
-    editable: true,
-    description: "This title can be edited inline.",
-  },
-};
diff --git a/web/lib/opal/src/layouts/content/HeadingLayout.tsx b/web/lib/opal/src/layouts/content/HeadingLayout.tsx
deleted file mode 100644
index 7047011fcca..00000000000
--- a/web/lib/opal/src/layouts/content/HeadingLayout.tsx
+++ /dev/null
@@ -1,218 +0,0 @@
-"use client";
-
-import { Button } from "@opal/components/buttons/button/components";
-import type { SizeVariant } from "@opal/shared";
-import SvgEdit from "@opal/icons/edit";
-import type { IconFunctionComponent } from "@opal/types";
-import { cn } from "@opal/utils";
-import { useRef, useState } from "react";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type HeadingSizePreset = "headline" | "section";
-type HeadingVariant = "heading" | "section";
-
-interface HeadingPresetConfig {
-  /** Icon width/height (CSS value). */
-  iconSize: string;
-  /** Tailwind padding class for the icon container. */
-  iconContainerPadding: string;
-  /** Gap between icon container and content (CSS value). */
-  gap: string;
-  /** Tailwind font class for the title. */
-  titleFont: string;
-  /** Title line-height — also used as icon container min-height (CSS value). */
-  lineHeight: string;
-  /** Button `size` prop for the edit button. Uses the shared `SizeVariant` scale. */
-  editButtonSize: SizeVariant;
-  /** Tailwind padding class for the edit button container. */
-  editButtonPadding: string;
-}
-
-interface HeadingLayoutProps {
-  /** Optional icon component. */
-  icon?: IconFunctionComponent;
-
-  /** Main title text. */
-  title: string;
-
-  /** Optional description below the title. */
-  description?: string;
-
-  /** Enable inline editing of the title. */
-  editable?: boolean;
-
-  /** Called when the user commits an edit. */
-  onTitleChange?: (newTitle: string) => void;
-
-  /** Size preset. Default: `"headline"`. */
-  sizePreset?: HeadingSizePreset;
-
-  /** Variant controls icon placement. `"heading"` = top, `"section"` = inline. Default: `"heading"`. */
-  variant?: HeadingVariant;
-
-  /** Ref forwarded to the root `<div>`. */
-  ref?: React.Ref<HTMLDivElement>;
-}
-
-// ---------------------------------------------------------------------------
-// Presets
-// ---------------------------------------------------------------------------
-
-const HEADING_PRESETS: Record<HeadingSizePreset, HeadingPresetConfig> = {
-  headline: {
-    iconSize: "2rem",
-    iconContainerPadding: "p-0.5",
-    gap: "0.25rem",
-    titleFont: "font-heading-h2",
-    lineHeight: "2.25rem",
-    editButtonSize: "md",
-    editButtonPadding: "p-1",
-  },
-  section: {
-    iconSize: "1.25rem",
-    iconContainerPadding: "p-1",
-    gap: "0rem",
-    titleFont: "font-heading-h3",
-    lineHeight: "1.75rem",
-    editButtonSize: "sm",
-    editButtonPadding: "p-0.5",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// HeadingLayout
-// ---------------------------------------------------------------------------
-
-function HeadingLayout({
-  sizePreset = "headline",
-  variant = "heading",
-  icon: Icon,
-  title,
-  description,
-  editable,
-  onTitleChange,
-  ref,
-}: HeadingLayoutProps) {
-  const [editing, setEditing] = useState(false);
-  const [editValue, setEditValue] = useState(title);
-  const inputRef = useRef<HTMLInputElement>(null);
-
-  const config = HEADING_PRESETS[sizePreset];
-  const iconPlacement = variant === "heading" ? "top" : "left";
-
-  function startEditing() {
-    setEditValue(title);
-    setEditing(true);
-  }
-
-  function commit() {
-    const value = editValue.trim();
-    if (value && value !== title) onTitleChange?.(value);
-    setEditing(false);
-  }
-
-  return (
-    <div
-      ref={ref}
-      className="opal-content-heading"
-      data-icon-placement={iconPlacement}
-      style={{ gap: iconPlacement === "left" ? config.gap : undefined }}
-    >
-      {Icon && (
-        <div
-          className={cn(
-            "opal-content-heading-icon-container shrink-0",
-            config.iconContainerPadding
-          )}
-          style={{ minHeight: config.lineHeight }}
-        >
-          <Icon
-            className="opal-content-heading-icon"
-            style={{ width: config.iconSize, height: config.iconSize }}
-          />
-        </div>
-      )}
-
-      <div className="opal-content-heading-body">
-        <div className="opal-content-heading-title-row">
-          {editing ? (
-            <div className="opal-content-heading-input-sizer">
-              <span
-                className={cn(
-                  "opal-content-heading-input-mirror",
-                  config.titleFont
-                )}
-              >
-                {editValue || "\u00A0"}
-              </span>
-              <input
-                ref={inputRef}
-                className={cn(
-                  "opal-content-heading-input",
-                  config.titleFont,
-                  "text-text-04"
-                )}
-                value={editValue}
-                onChange={(e) => setEditValue(e.target.value)}
-                size={1}
-                autoFocus
-                onFocus={(e) => e.currentTarget.select()}
-                onBlur={commit}
-                onKeyDown={(e) => {
-                  if (e.key === "Enter") commit();
-                  if (e.key === "Escape") {
-                    setEditValue(title);
-                    setEditing(false);
-                  }
-                }}
-                style={{ height: config.lineHeight }}
-              />
-            </div>
-          ) : (
-            <span
-              className={cn(
-                "opal-content-heading-title",
-                config.titleFont,
-                "text-text-04",
-                editable && "cursor-pointer"
-              )}
-              onClick={editable ? startEditing : undefined}
-              style={{ height: config.lineHeight }}
-            >
-              {title}
-            </span>
-          )}
-
-          {editable && !editing && (
-            <div
-              className={cn(
-                "opal-content-heading-edit-button",
-                config.editButtonPadding
-              )}
-            >
-              <Button
-                icon={SvgEdit}
-                prominence="internal"
-                size={config.editButtonSize}
-                tooltip="Edit"
-                tooltipSide="right"
-                onClick={startEditing}
-              />
-            </div>
-          )}
-        </div>
-
-        {description && (
-          <div className="opal-content-heading-description font-secondary-body text-text-03">
-            {description}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-export { HeadingLayout, type HeadingLayoutProps, type HeadingSizePreset };
diff --git a/web/lib/opal/src/layouts/content/LabelLayout.stories.tsx b/web/lib/opal/src/layouts/content/LabelLayout.stories.tsx
deleted file mode 100644
index 0dd3bdff3df..00000000000
--- a/web/lib/opal/src/layouts/content/LabelLayout.stories.tsx
+++ /dev/null
@@ -1,154 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { LabelLayout } from "./LabelLayout";
-import { SvgSettings, SvgStar } from "@opal/icons";
-import * as TooltipPrimitive from "@radix-ui/react-tooltip";
-
-const meta = {
-  title: "Layouts/LabelLayout",
-  component: LabelLayout,
-  tags: ["autodocs"],
-  parameters: {
-    layout: "centered",
-  },
-  decorators: [
-    (Story) => (
-      <TooltipPrimitive.Provider>
-        <Story />
-      </TooltipPrimitive.Provider>
-    ),
-  ],
-} satisfies Meta<typeof LabelLayout>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-// ---------------------------------------------------------------------------
-// Size presets
-// ---------------------------------------------------------------------------
-
-export const MainContent: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Display Name",
-  },
-};
-
-export const MainUi: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Email Address",
-  },
-};
-
-export const SecondaryPreset: Story = {
-  args: {
-    sizePreset: "secondary",
-    title: "API Key",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// With description
-// ---------------------------------------------------------------------------
-
-export const WithDescription: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Workspace Name",
-    description: "The name displayed across your organization.",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// With icon
-// ---------------------------------------------------------------------------
-
-export const WithIcon: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Settings",
-    icon: SvgSettings,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Optional
-// ---------------------------------------------------------------------------
-
-export const Optional: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Phone Number",
-    optional: true,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Aux icons
-// ---------------------------------------------------------------------------
-
-export const AuxInfoGray: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Connection Status",
-    auxIcon: "info-gray",
-  },
-};
-
-export const AuxWarning: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Rate Limit",
-    auxIcon: "warning",
-  },
-};
-
-export const AuxError: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "API Key",
-    auxIcon: "error",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// With tag
-// ---------------------------------------------------------------------------
-
-export const WithTag: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Knowledge Graph",
-    tag: { title: "Beta", color: "blue" },
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Editable
-// ---------------------------------------------------------------------------
-
-export const Editable: Story = {
-  args: {
-    sizePreset: "main-ui",
-    title: "Click to edit",
-    editable: true,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Combined
-// ---------------------------------------------------------------------------
-
-export const FullFeatured: Story = {
-  args: {
-    sizePreset: "main-content",
-    title: "Custom Field",
-    icon: SvgStar,
-    description: "A custom field with all extras enabled.",
-    optional: true,
-    auxIcon: "info-blue",
-    tag: { title: "New", color: "green" },
-    editable: true,
-  },
-};
diff --git a/web/lib/opal/src/layouts/content/LabelLayout.tsx b/web/lib/opal/src/layouts/content/LabelLayout.tsx
deleted file mode 100644
index 016b43f5cfa..00000000000
--- a/web/lib/opal/src/layouts/content/LabelLayout.tsx
+++ /dev/null
@@ -1,286 +0,0 @@
-"use client";
-
-import { Button } from "@opal/components/buttons/button/components";
-import { Tag, type TagProps } from "@opal/components/tag/components";
-import type { SizeVariant } from "@opal/shared";
-import SvgAlertCircle from "@opal/icons/alert-circle";
-import SvgAlertTriangle from "@opal/icons/alert-triangle";
-import SvgEdit from "@opal/icons/edit";
-import SvgXOctagon from "@opal/icons/x-octagon";
-import type { IconFunctionComponent } from "@opal/types";
-import { cn } from "@opal/utils";
-import { useRef, useState } from "react";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type LabelSizePreset = "main-content" | "main-ui" | "secondary";
-
-type LabelAuxIcon = "info-gray" | "info-blue" | "warning" | "error";
-
-interface LabelPresetConfig {
-  iconSize: string;
-  iconContainerPadding: string;
-  iconColorClass: string;
-  titleFont: string;
-  lineHeight: string;
-  gap: string;
-  /** Button `size` prop for the edit button. Uses the shared `SizeVariant` scale. */
-  editButtonSize: SizeVariant;
-  editButtonPadding: string;
-  optionalFont: string;
-  /** Aux icon size = lineHeight − 2 × p-0.5. */
-  auxIconSize: string;
-}
-
-interface LabelLayoutProps {
-  /** Optional icon component. */
-  icon?: IconFunctionComponent;
-
-  /** Main title text. */
-  title: string;
-
-  /** Optional description text below the title. */
-  description?: string;
-
-  /** Enable inline editing of the title. */
-  editable?: boolean;
-
-  /** Called when the user commits an edit. */
-  onTitleChange?: (newTitle: string) => void;
-
-  /** When `true`, renders "(Optional)" beside the title. */
-  optional?: boolean;
-
-  /** Auxiliary status icon rendered beside the title. */
-  auxIcon?: LabelAuxIcon;
-
-  /** Tag rendered beside the title. */
-  tag?: TagProps;
-
-  /** Size preset. Default: `"main-ui"`. */
-  sizePreset?: LabelSizePreset;
-
-  /** Ref forwarded to the root `<div>`. */
-  ref?: React.Ref<HTMLDivElement>;
-}
-
-// ---------------------------------------------------------------------------
-// Presets
-// ---------------------------------------------------------------------------
-
-const LABEL_PRESETS: Record<LabelSizePreset, LabelPresetConfig> = {
-  "main-content": {
-    iconSize: "1rem",
-    iconContainerPadding: "p-1",
-    iconColorClass: "text-text-04",
-    titleFont: "font-main-content-emphasis",
-    lineHeight: "1.5rem",
-    gap: "0.125rem",
-    editButtonSize: "sm",
-    editButtonPadding: "p-0",
-    optionalFont: "font-main-content-muted",
-    auxIconSize: "1.25rem",
-  },
-  "main-ui": {
-    iconSize: "1rem",
-    iconContainerPadding: "p-0.5",
-    iconColorClass: "text-text-03",
-    titleFont: "font-main-ui-action",
-    lineHeight: "1.25rem",
-    gap: "0.25rem",
-    editButtonSize: "xs",
-    editButtonPadding: "p-0",
-    optionalFont: "font-main-ui-muted",
-    auxIconSize: "1rem",
-  },
-  secondary: {
-    iconSize: "0.75rem",
-    iconContainerPadding: "p-0.5",
-    iconColorClass: "text-text-04",
-    titleFont: "font-secondary-action",
-    lineHeight: "1rem",
-    gap: "0.125rem",
-    editButtonSize: "2xs",
-    editButtonPadding: "p-0",
-    optionalFont: "font-secondary-action",
-    auxIconSize: "0.75rem",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// LabelLayout
-// ---------------------------------------------------------------------------
-
-const AUX_ICON_CONFIG: Record<
-  LabelAuxIcon,
-  { icon: IconFunctionComponent; colorClass: string }
-> = {
-  "info-gray": { icon: SvgAlertCircle, colorClass: "text-text-02" },
-  "info-blue": { icon: SvgAlertCircle, colorClass: "text-status-info-05" },
-  warning: { icon: SvgAlertTriangle, colorClass: "text-status-warning-05" },
-  error: { icon: SvgXOctagon, colorClass: "text-status-error-05" },
-};
-
-function LabelLayout({
-  icon: Icon,
-  title,
-  description,
-  editable,
-  onTitleChange,
-  optional,
-  auxIcon,
-  tag,
-  sizePreset = "main-ui",
-  ref,
-}: LabelLayoutProps) {
-  const [editing, setEditing] = useState(false);
-  const [editValue, setEditValue] = useState(title);
-  const inputRef = useRef<HTMLInputElement>(null);
-
-  const config = LABEL_PRESETS[sizePreset];
-
-  function startEditing() {
-    setEditValue(title);
-    setEditing(true);
-  }
-
-  function commit() {
-    const value = editValue.trim();
-    if (value && value !== title) onTitleChange?.(value);
-    setEditing(false);
-  }
-
-  return (
-    <div ref={ref} className="opal-content-label" style={{ gap: config.gap }}>
-      {Icon && (
-        <div
-          className={cn(
-            "opal-content-label-icon-container shrink-0",
-            config.iconContainerPadding
-          )}
-          style={{ minHeight: config.lineHeight }}
-        >
-          <Icon
-            className={cn("opal-content-label-icon", config.iconColorClass)}
-            style={{ width: config.iconSize, height: config.iconSize }}
-          />
-        </div>
-      )}
-
-      <div className="opal-content-label-body">
-        <div className="opal-content-label-title-row">
-          {editing ? (
-            <div className="opal-content-label-input-sizer">
-              <span
-                className={cn(
-                  "opal-content-label-input-mirror",
-                  config.titleFont
-                )}
-              >
-                {editValue || "\u00A0"}
-              </span>
-              <input
-                ref={inputRef}
-                className={cn(
-                  "opal-content-label-input",
-                  config.titleFont,
-                  "text-text-04"
-                )}
-                value={editValue}
-                onChange={(e) => setEditValue(e.target.value)}
-                size={1}
-                autoFocus
-                onFocus={(e) => e.currentTarget.select()}
-                onBlur={commit}
-                onKeyDown={(e) => {
-                  if (e.key === "Enter") commit();
-                  if (e.key === "Escape") {
-                    setEditValue(title);
-                    setEditing(false);
-                  }
-                }}
-                style={{ height: config.lineHeight }}
-              />
-            </div>
-          ) : (
-            <span
-              className={cn(
-                "opal-content-label-title",
-                config.titleFont,
-                "text-text-04",
-                editable && "cursor-pointer"
-              )}
-              onClick={editable ? startEditing : undefined}
-              style={{ height: config.lineHeight }}
-            >
-              {title}
-            </span>
-          )}
-
-          {optional && (
-            <span
-              className={cn(config.optionalFont, "text-text-03 shrink-0")}
-              style={{ height: config.lineHeight }}
-            >
-              (Optional)
-            </span>
-          )}
-
-          {auxIcon &&
-            (() => {
-              const { icon: AuxIcon, colorClass } = AUX_ICON_CONFIG[auxIcon];
-              return (
-                <div
-                  className="opal-content-label-aux-icon shrink-0 p-0.5"
-                  style={{ height: config.lineHeight }}
-                >
-                  <AuxIcon
-                    className={colorClass}
-                    style={{
-                      width: config.auxIconSize,
-                      height: config.auxIconSize,
-                    }}
-                  />
-                </div>
-              );
-            })()}
-
-          {tag && <Tag {...tag} />}
-
-          {editable && !editing && (
-            <div
-              className={cn(
-                "opal-content-label-edit-button",
-                config.editButtonPadding
-              )}
-            >
-              <Button
-                icon={SvgEdit}
-                prominence="internal"
-                size={config.editButtonSize}
-                tooltip="Edit"
-                tooltipSide="right"
-                onClick={startEditing}
-              />
-            </div>
-          )}
-        </div>
-
-        {description && (
-          <div className="opal-content-label-description font-secondary-body text-text-03">
-            {description}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-export {
-  LabelLayout,
-  type LabelLayoutProps,
-  type LabelSizePreset,
-  type LabelAuxIcon,
-};

From ffe04ab91fcfb14d238f9146517b7f6a44277c44 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 13:32:51 -0700
Subject: [PATCH 233/267] fix(tests): remove deprecated o1-preview and o1-mini
 model tests (#9280)

---
 backend/tests/unit/onyx/llm/test_true_openai_model.py | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/backend/tests/unit/onyx/llm/test_true_openai_model.py b/backend/tests/unit/onyx/llm/test_true_openai_model.py
index cd62f6e72c0..40dffcd0f45 100644
--- a/backend/tests/unit/onyx/llm/test_true_openai_model.py
+++ b/backend/tests/unit/onyx/llm/test_true_openai_model.py
@@ -26,14 +26,6 @@ def test_real_openai_gpt4o_mini(self) -> None:
         """Test that real OpenAI GPT-4o-mini model is correctly identified."""
         assert is_true_openai_model(LlmProviderNames.OPENAI, "gpt-4o-mini") is True
 
-    def test_real_openai_o1_preview(self) -> None:
-        """Test that real OpenAI o1-preview reasoning model is correctly identified."""
-        assert is_true_openai_model(LlmProviderNames.OPENAI, "o1-preview") is True
-
-    def test_real_openai_o1_mini(self) -> None:
-        """Test that real OpenAI o1-mini reasoning model is correctly identified."""
-        assert is_true_openai_model(LlmProviderNames.OPENAI, "o1-mini") is True
-
     def test_openai_with_provider_prefix(self) -> None:
         """Test that OpenAI model with provider prefix is correctly identified."""
         assert is_true_openai_model(LlmProviderNames.OPENAI, "openai/gpt-4") is False

From d2d44c1e68b94bbdc3a938b4ae60e6e1f0e5e006 Mon Sep 17 00:00:00 2001
From: Danelegend <43459662+Danelegend@users.noreply.github.com>
Date: Wed, 11 Mar 2026 14:24:15 -0700
Subject: [PATCH 234/267] fix(indexing): Stop deep-copy during indexing (#9275)

---
 .../indexing/adapters/document_indexing_adapter.py  | 12 ++++--------
 backend/onyx/indexing/embedder.py                   |  5 +++--
 backend/onyx/indexing/models.py                     |  6 +++---
 backend/onyx/utils/pydantic_util.py                 | 13 +++++++++++++
 4 files changed, 23 insertions(+), 13 deletions(-)
 create mode 100644 backend/onyx/utils/pydantic_util.py

diff --git a/backend/onyx/indexing/adapters/document_indexing_adapter.py b/backend/onyx/indexing/adapters/document_indexing_adapter.py
index 012e438dc21..3bd91c067c7 100644
--- a/backend/onyx/indexing/adapters/document_indexing_adapter.py
+++ b/backend/onyx/indexing/adapters/document_indexing_adapter.py
@@ -123,15 +123,11 @@ def build_metadata_aware_chunks(
         }
 
         doc_id_to_new_chunk_cnt: dict[str, int] = {
-            document_id: len(
-                [
-                    chunk
-                    for chunk in chunks_with_embeddings
-                    if chunk.source_document.id == document_id
-                ]
-            )
-            for document_id in updatable_ids
+            doc_id: 0 for doc_id in updatable_ids
         }
+        for chunk in chunks_with_embeddings:
+            if chunk.source_document.id in doc_id_to_new_chunk_cnt:
+                doc_id_to_new_chunk_cnt[chunk.source_document.id] += 1
 
         # Get ancestor hierarchy node IDs for each document
         doc_id_to_ancestor_ids = self._get_ancestor_ids_for_documents(
diff --git a/backend/onyx/indexing/embedder.py b/backend/onyx/indexing/embedder.py
index 40fc5c7c8bb..bf43857b12c 100644
--- a/backend/onyx/indexing/embedder.py
+++ b/backend/onyx/indexing/embedder.py
@@ -16,6 +16,7 @@
 from onyx.indexing.models import IndexChunk
 from onyx.natural_language_processing.search_nlp_models import EmbeddingModel
 from onyx.utils.logger import setup_logger
+from onyx.utils.pydantic_util import shallow_model_dump
 from onyx.utils.timing import log_function_time
 from shared_configs.configs import INDEXING_MODEL_SERVER_HOST
 from shared_configs.configs import INDEXING_MODEL_SERVER_PORT
@@ -210,8 +211,8 @@ def embed_chunks(
                     )[0]
                     title_embed_dict[title] = title_embedding
 
-            new_embedded_chunk = IndexChunk(
-                **chunk.model_dump(),
+            new_embedded_chunk = IndexChunk.model_construct(
+                **shallow_model_dump(chunk),
                 embeddings=ChunkEmbedding(
                     full_embedding=chunk_embeddings[0],
                     mini_chunk_embeddings=chunk_embeddings[1:],
diff --git a/backend/onyx/indexing/models.py b/backend/onyx/indexing/models.py
index 36e51ceed2f..4fcd6850c61 100644
--- a/backend/onyx/indexing/models.py
+++ b/backend/onyx/indexing/models.py
@@ -12,6 +12,7 @@
 from onyx.db.enums import EmbeddingPrecision
 from onyx.db.enums import SwitchoverType
 from onyx.utils.logger import setup_logger
+from onyx.utils.pydantic_util import shallow_model_dump
 from shared_configs.enums import EmbeddingProvider
 from shared_configs.model_server_models import Embedding
 
@@ -133,9 +134,8 @@ def from_index_chunk(
         tenant_id: str,
         ancestor_hierarchy_node_ids: list[int] | None = None,
     ) -> "DocMetadataAwareIndexChunk":
-        index_chunk_data = index_chunk.model_dump()
-        return cls(
-            **index_chunk_data,
+        return cls.model_construct(
+            **shallow_model_dump(index_chunk),
             access=access,
             document_sets=document_sets,
             user_project=user_project,
diff --git a/backend/onyx/utils/pydantic_util.py b/backend/onyx/utils/pydantic_util.py
new file mode 100644
index 00000000000..43a0d558cf8
--- /dev/null
+++ b/backend/onyx/utils/pydantic_util.py
@@ -0,0 +1,13 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def shallow_model_dump(model_instance: BaseModel) -> dict[str, Any]:
+    """Like model_dump(), but returns references to field values instead of
+    deep copies. Use with model_construct() to avoid unnecessary memory
+    duplication when building subclass instances."""
+    return {
+        field_name: getattr(model_instance, field_name)
+        for field_name in model_instance.__class__.model_fields
+    }

From 665640fac8b0c6a3bcee31eb5152f6d07a20b883 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 11 Mar 2026 14:58:43 -0700
Subject: [PATCH 235/267] chore(opensearch): unset container ulimits in dev
 (#9277)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 deployment/docker_compose/docker-compose.dev.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/deployment/docker_compose/docker-compose.dev.yml b/deployment/docker_compose/docker-compose.dev.yml
index 7baa933bc31..a3e4708f1dc 100644
--- a/deployment/docker_compose/docker-compose.dev.yml
+++ b/deployment/docker_compose/docker-compose.dev.yml
@@ -38,6 +38,11 @@ services:
   opensearch:
     ports:
       - "9200:9200"
+    # Rootless Docker can reject the base OpenSearch ulimit settings, so clear
+    # the inherited block entirely in the dev override.
+    ulimits: !reset null
+    environment:
+      - bootstrap.memory_lock=false
 
   inference_model_server:
     ports:

From 787f117e179bafa06e5e459d128f5643f81d8988 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 11 Mar 2026 14:59:35 -0700
Subject: [PATCH 236/267] chore(deps): bump pypdf from 6.7.5 to 6.8.0 (#9260)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt | 2 +-
 pyproject.toml                   | 2 +-
 uv.lock                          | 8 ++++----
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 6667091a349..487f37d84c4 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -750,7 +750,7 @@ pypandoc-binary==1.16.2
     # via onyx
 pyparsing==3.2.5
     # via httplib2
-pypdf==6.7.5
+pypdf==6.8.0
     # via
     #   onyx
     #   unstructured-client
diff --git a/pyproject.toml b/pyproject.toml
index e9404803bb9..6da1c79bb3a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -91,7 +91,7 @@ backend = [
     "python-gitlab==5.6.0",
     "python-pptx==0.6.23",
     "pypandoc_binary==1.16.2",
-    "pypdf==6.7.5",
+    "pypdf==6.8.0",
     "pytest-mock==3.12.0",
     "pytest-playwright==0.7.0",
     "python-docx==1.1.2",
diff --git a/uv.lock b/uv.lock
index 05be6b324fa..e34e591283c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4466,7 +4466,7 @@ requires-dist = [
     { name = "pygithub", marker = "extra == 'backend'", specifier = "==2.5.0" },
     { name = "pympler", marker = "extra == 'backend'", specifier = "==1.1" },
     { name = "pypandoc-binary", marker = "extra == 'backend'", specifier = "==1.16.2" },
-    { name = "pypdf", marker = "extra == 'backend'", specifier = "==6.7.5" },
+    { name = "pypdf", marker = "extra == 'backend'", specifier = "==6.8.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = "==8.3.5" },
     { name = "pytest-alembic", marker = "extra == 'dev'", specifier = "==0.12.1" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = "==1.3.0" },
@@ -5713,11 +5713,11 @@ wheels = [
 
 [[package]]
 name = "pypdf"
-version = "6.7.5"
+version = "6.8.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f6/52/37cc0aa9e9d1bf7729a737a0d83f8b3f851c8eb137373d9f71eafb0a3405/pypdf-6.7.5.tar.gz", hash = "sha256:40bb2e2e872078655f12b9b89e2f900888bb505e88a82150b64f9f34fa25651d", size = 5304278, upload-time = "2026-03-02T09:05:21.464Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b4/a3/e705b0805212b663a4c27b861c8a603dba0f8b4bb281f96f8e746576a50d/pypdf-6.8.0.tar.gz", hash = "sha256:cb7eaeaa4133ce76f762184069a854e03f4d9a08568f0e0623f7ea810407833b", size = 5307831, upload-time = "2026-03-09T13:37:40.591Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/05/89/336673efd0a88956562658aba4f0bbef7cb92a6fbcbcaf94926dbc82b408/pypdf-6.7.5-py3-none-any.whl", hash = "sha256:07ba7f1d6e6d9aa2a17f5452e320a84718d4ce863367f7ede2fd72280349ab13", size = 331421, upload-time = "2026-03-02T09:05:19.722Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/ec/4ccf3bb86b1afe5d7176e1c8abcdbf22b53dd682ec2eda50e1caadcf6846/pypdf-6.8.0-py3-none-any.whl", hash = "sha256:2a025080a8dd73f48123c89c57174a5ff3806c71763ee4e49572dc90454943c7", size = 332177, upload-time = "2026-03-09T13:37:38.774Z" },
 ]
 
 [[package]]

From 8dc379c6fde84ed11b3ccf8a626fae5194717f02 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Wed, 11 Mar 2026 15:18:13 -0700
Subject: [PATCH 237/267] feat(ods): use release-tag to print highest stable
 semver that should receive the `latest` tag (#9278)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 tools/ods/cmd/print_latest.go | 36 +++++++++++++++++++++++++++++++++++
 tools/ods/cmd/root.go         |  1 +
 tools/ods/go.mod              |  7 ++++---
 tools/ods/go.sum              | 16 +++++++++++-----
 4 files changed, 52 insertions(+), 8 deletions(-)
 create mode 100644 tools/ods/cmd/print_latest.go

diff --git a/tools/ods/cmd/print_latest.go b/tools/ods/cmd/print_latest.go
new file mode 100644
index 00000000000..0608c3edf77
--- /dev/null
+++ b/tools/ods/cmd/print_latest.go
@@ -0,0 +1,36 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/jmelahman/tag/git"
+	"github.com/spf13/cobra"
+)
+
+// NewLatestStableTagCommand creates the latest-stable-tag command.
+func NewLatestStableTagCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "latest-stable-tag",
+		Short: "Print the git tag that should receive the 'latest' Docker tag",
+		Long: `Print the highest stable (non-pre-release) semver tag in the repository.
+
+This is used during deployment to decide whether a given tag should
+receive the "latest" tag on Docker Hub. Only the highest vX.Y.Z tag
+qualifies. Tags with pre-release suffixes (e.g. v1.2.3-beta,
+v1.2.3-cloud.1) are excluded.`,
+		Args: cobra.NoArgs,
+		RunE: func(c *cobra.Command, _ []string) error {
+			tag, err := git.GetLatestStableSemverTag("")
+			if err != nil {
+				return fmt.Errorf("get latest stable semver tag: %w", err)
+			}
+			if tag == "" {
+				return fmt.Errorf("no stable semver tag found in repository")
+			}
+			fmt.Println(tag)
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/tools/ods/cmd/root.go b/tools/ods/cmd/root.go
index d6b41ff2f81..c6490d8f762 100644
--- a/tools/ods/cmd/root.go
+++ b/tools/ods/cmd/root.go
@@ -52,6 +52,7 @@ func NewRootCommand() *cobra.Command {
 	cmd.AddCommand(NewScreenshotDiffCommand())
 	cmd.AddCommand(NewDesktopCommand())
 	cmd.AddCommand(NewWebCommand())
+	cmd.AddCommand(NewLatestStableTagCommand())
 	cmd.AddCommand(NewWhoisCommand())
 
 	return cmd
diff --git a/tools/ods/go.mod b/tools/ods/go.mod
index 7ffcbc6a099..b76714b547e 100644
--- a/tools/ods/go.mod
+++ b/tools/ods/go.mod
@@ -3,12 +3,13 @@ module github.com/onyx-dot-app/onyx/tools/ods
 go 1.26.0
 
 require (
+	github.com/jmelahman/tag v0.5.2
 	github.com/sirupsen/logrus v1.9.3
-	github.com/spf13/cobra v1.10.1
-	github.com/spf13/pflag v1.0.9
+	github.com/spf13/cobra v1.10.2
+	github.com/spf13/pflag v1.0.10
 )
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 // indirect
+	golang.org/x/sys v0.39.0 // indirect
 )
diff --git a/tools/ods/go.sum b/tools/ods/go.sum
index 3bb89e930aa..dd246f87248 100644
--- a/tools/ods/go.sum
+++ b/tools/ods/go.sum
@@ -4,20 +4,26 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jmelahman/tag v0.5.2 h1:g6A/aHehu5tkA31mPoDsXBNr1FigZ9A82Y8WVgb/WsM=
+github.com/jmelahman/tag v0.5.2/go.mod h1:qmuqk19B1BKkpcg3kn7l/Eey+UqucLxgOWkteUGiG4Q=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
-github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
-github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
-github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 h1:0A+M6Uqn+Eje4kHMK80dtF3JCXC4ykBgQG4Fe06QRhQ=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
+golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

From e213853f63445f1fbed61890600c0878a847eed1 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Wed, 11 Mar 2026 16:19:38 -0700
Subject: [PATCH 238/267] fix(craft): rename webapp download endpoint to avoid
 route conflict (#9283)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Wenxi <wenxi@onyx.app>
---
 backend/onyx/server/features/build/api/sessions_api.py     | 2 +-
 web/src/app/craft/components/output-panel/ArtifactsTab.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend/onyx/server/features/build/api/sessions_api.py b/backend/onyx/server/features/build/api/sessions_api.py
index ecdbf1682e3..2ec10da95f4 100644
--- a/backend/onyx/server/features/build/api/sessions_api.py
+++ b/backend/onyx/server/features/build/api/sessions_api.py
@@ -732,7 +732,7 @@ def get_webapp_info(
     return WebappInfo(**webapp_info)
 
 
-@router.get("/{session_id}/webapp/download")
+@router.get("/{session_id}/webapp-download")
 def download_webapp(
     session_id: UUID,
     user: User = Depends(current_user),
diff --git a/web/src/app/craft/components/output-panel/ArtifactsTab.tsx b/web/src/app/craft/components/output-panel/ArtifactsTab.tsx
index bb6299a29ec..f8868f7c222 100644
--- a/web/src/app/craft/components/output-panel/ArtifactsTab.tsx
+++ b/web/src/app/craft/components/output-panel/ArtifactsTab.tsx
@@ -98,7 +98,7 @@ export default function ArtifactsTab({
   const handleWebappDownload = () => {
     if (!sessionId) return;
     const link = document.createElement("a");
-    link.href = `/api/build/sessions/${sessionId}/webapp/download`;
+    link.href = `/api/build/sessions/${sessionId}/webapp-download`;
     link.download = "";
     document.body.appendChild(link);
     link.click();

From a78607f1b59fe6901f46638fc19695ad4912662e Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 11 Mar 2026 18:06:02 -0700
Subject: [PATCH 239/267] fix(fe): `InputComboBox` resets filter value on open
 (#9287)

---
 .../InputComboBox/InputComboBox.test.tsx      | 15 +++++++++++++
 .../inputs/InputComboBox/InputComboBox.tsx    | 18 +++++++++++-----
 .../inputs/InputComboBox/hooks.ts             | 21 ++++++++++++-------
 3 files changed, 41 insertions(+), 13 deletions(-)

diff --git a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx
index 53fd7d9c2a5..aa2c9e78a8b 100644
--- a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx
+++ b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.test.tsx
@@ -118,6 +118,21 @@ describe("InputComboBox", () => {
       expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
     });
 
+    test("shows all options on focus when a value is already selected", () => {
+      render(
+        <InputComboBox
+          placeholder="Select"
+          value="apple"
+          options={mockOptions}
+        />
+      );
+      const input = screen.getByDisplayValue("Apple");
+      fireEvent.focus(input);
+
+      const options = screen.getAllByRole("option");
+      expect(options.length).toBe(3);
+    });
+
     test("closes dropdown on tab", async () => {
       const user = setupUser();
       render(
diff --git a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
index bc7828baa94..be789a3c9c1 100644
--- a/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
+++ b/web/src/refresh-components/inputs/InputComboBox/InputComboBox.tsx
@@ -322,24 +322,32 @@ const InputComboBox = ({
 
   const handleFocus = useCallback(() => {
     if (hasOptions) {
+      setInputValue("");
       setIsOpen(true);
-      setHighlightedIndex(-1); // Start with no highlight on focus
-      setIsKeyboardNav(false); // Start with mouse mode
+      setHighlightedIndex(-1);
+      setIsKeyboardNav(false);
     }
-  }, [hasOptions, setIsOpen, setHighlightedIndex, setIsKeyboardNav]);
+  }, [
+    hasOptions,
+    setInputValue,
+    setIsOpen,
+    setHighlightedIndex,
+    setIsKeyboardNav,
+  ]);
 
   const toggleDropdown = useCallback(() => {
     if (!disabled && hasOptions) {
       setIsOpen((prev) => {
         const newOpen = !prev;
         if (newOpen) {
-          setHighlightedIndex(-1); // Reset highlight when opening
+          setInputValue("");
+          setHighlightedIndex(-1);
         }
         return newOpen;
       });
       inputRef.current?.focus();
     }
-  }, [disabled, hasOptions, setIsOpen, setHighlightedIndex]);
+  }, [disabled, hasOptions, setIsOpen, setInputValue, setHighlightedIndex]);
 
   const autoId = useId();
   const fieldId = fieldContext?.baseId || name || `combo-box-${autoId}`;
diff --git a/web/src/refresh-components/inputs/InputComboBox/hooks.ts b/web/src/refresh-components/inputs/InputComboBox/hooks.ts
index e428ed7ffd9..b16ccff8a45 100644
--- a/web/src/refresh-components/inputs/InputComboBox/hooks.ts
+++ b/web/src/refresh-components/inputs/InputComboBox/hooks.ts
@@ -20,21 +20,26 @@ export function useComboBoxState({ value, options }: UseComboBoxStateProps) {
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
   const [isKeyboardNav, setIsKeyboardNav] = useState(false);
 
-  // State synchronization logic
-  // Only sync when the dropdown is closed or when value changes significantly
+  // Sync inputValue with the external value prop.
+  // When the dropdown is closed, always reflect the controlled value.
+  // When the dropdown is open, only sync if the *value prop itself* changes
+  // (e.g. parent programmatically updates it), not when inputValue changes
+  // (e.g. user clears the field on focus to browse all options).
   useEffect(() => {
-    // If dropdown is closed, always sync with prop value
     if (!isOpen) {
       setInputValue(value);
-    } else {
-      // If dropdown is open, only sync if the new value is an exact match with an option
-      // This prevents interference when user is typing
+    }
+  }, [value, isOpen]);
+
+  useEffect(() => {
+    if (isOpen) {
       const isExactOptionMatch = options.some((opt) => opt.value === value);
-      if (isExactOptionMatch && inputValue !== value) {
+      if (isExactOptionMatch) {
         setInputValue(value);
       }
     }
-  }, [value, isOpen, options, inputValue]);
+    // Only react to value prop changes while open, not inputValue changes
+  }, [value]);
 
   // Reset highlight and keyboard nav when closing dropdown
   useEffect(() => {

From abf76cd747604729c74cdfedead08c6cd7395fda Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 12 Mar 2026 01:41:01 +0000
Subject: [PATCH 240/267] chore(deps): bump tornado from 6.5.2 to 6.5.5 (#9290)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt |  2 +-
 backend/requirements/dev.txt     |  2 +-
 uv.lock                          | 28 +++++++++++++---------------
 3 files changed, 15 insertions(+), 17 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index 487f37d84c4..b17258a0c4e 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -1020,7 +1020,7 @@ toolz==1.1.0
     #   dask
     #   distributed
     #   partd
-tornado==6.5.2
+tornado==6.5.5
     # via distributed
 tqdm==4.67.1
     # via
diff --git a/backend/requirements/dev.txt b/backend/requirements/dev.txt
index 02038479740..e3be56f5c51 100644
--- a/backend/requirements/dev.txt
+++ b/backend/requirements/dev.txt
@@ -466,7 +466,7 @@ tokenizers==0.21.4
     # via
     #   cohere
     #   litellm
-tornado==6.5.2
+tornado==6.5.5
     # via
     #   ipykernel
     #   jupyter-client
diff --git a/uv.lock b/uv.lock
index e34e591283c..b7698a27a5c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -7233,21 +7233,19 @@ wheels = [
 
 [[package]]
 name = "tornado"
-version = "6.5.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/09/ce/1eb500eae19f4648281bb2186927bb062d2438c2e5093d1360391afd2f90/tornado-6.5.2.tar.gz", hash = "sha256:ab53c8f9a0fa351e2c0741284e06c7a45da86afb544133201c5cc8578eb076a0", size = 510821, upload-time = "2025-08-08T18:27:00.78Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/f6/48/6a7529df2c9cc12efd2e8f5dd219516184d703b34c06786809670df5b3bd/tornado-6.5.2-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:2436822940d37cde62771cff8774f4f00b3c8024fe482e16ca8387b8a2724db6", size = 442563, upload-time = "2025-08-08T18:26:42.945Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/b5/9b575a0ed3e50b00c40b08cbce82eb618229091d09f6d14bce80fc01cb0b/tornado-6.5.2-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:583a52c7aa94ee046854ba81d9ebb6c81ec0fd30386d96f7640c96dad45a03ef", size = 440729, upload-time = "2025-08-08T18:26:44.473Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/4e/619174f52b120efcf23633c817fd3fed867c30bff785e2cd5a53a70e483c/tornado-6.5.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b0fe179f28d597deab2842b86ed4060deec7388f1fd9c1b4a41adf8af058907e", size = 444295, upload-time = "2025-08-08T18:26:46.021Z" },
-    { url = "https://files.pythonhosted.org/packages/95/fa/87b41709552bbd393c85dd18e4e3499dcd8983f66e7972926db8d96aa065/tornado-6.5.2-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b186e85d1e3536d69583d2298423744740986018e393d0321df7340e71898882", size = 443644, upload-time = "2025-08-08T18:26:47.625Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/41/fb15f06e33d7430ca89420283a8762a4e6b8025b800ea51796ab5e6d9559/tornado-6.5.2-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e792706668c87709709c18b353da1f7662317b563ff69f00bab83595940c7108", size = 443878, upload-time = "2025-08-08T18:26:50.599Z" },
-    { url = "https://files.pythonhosted.org/packages/11/92/fe6d57da897776ad2e01e279170ea8ae726755b045fe5ac73b75357a5a3f/tornado-6.5.2-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:06ceb1300fd70cb20e43b1ad8aaee0266e69e7ced38fa910ad2e03285009ce7c", size = 444549, upload-time = "2025-08-08T18:26:51.864Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/02/c8f4f6c9204526daf3d760f4aa555a7a33ad0e60843eac025ccfd6ff4a93/tornado-6.5.2-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:74db443e0f5251be86cbf37929f84d8c20c27a355dd452a5cfa2aada0d001ec4", size = 443973, upload-time = "2025-08-08T18:26:53.625Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/2d/f5f5707b655ce2317190183868cd0f6822a1121b4baeae509ceb9590d0bd/tornado-6.5.2-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:b5e735ab2889d7ed33b32a459cac490eda71a1ba6857b0118de476ab6c366c04", size = 443954, upload-time = "2025-08-08T18:26:55.072Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/59/593bd0f40f7355806bf6573b47b8c22f8e1374c9b6fd03114bd6b7a3dcfd/tornado-6.5.2-cp39-abi3-win32.whl", hash = "sha256:c6f29e94d9b37a95013bb669616352ddb82e3bfe8326fccee50583caebc8a5f0", size = 445023, upload-time = "2025-08-08T18:26:56.677Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/2a/f609b420c2f564a748a2d80ebfb2ee02a73ca80223af712fca591386cafb/tornado-6.5.2-cp39-abi3-win_amd64.whl", hash = "sha256:e56a5af51cc30dd2cae649429af65ca2f6571da29504a07995175df14c18f35f", size = 445427, upload-time = "2025-08-08T18:26:57.91Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/4f/e1f65e8f8c76d73658b33d33b81eed4322fb5085350e4328d5c956f0c8f9/tornado-6.5.2-cp39-abi3-win_arm64.whl", hash = "sha256:d6c33dc3672e3a1f3618eb63b7ef4683a7688e7b9e6e8f0d9aa5726360a004af", size = 444456, upload-time = "2025-08-08T18:26:59.207Z" },
+version = "6.5.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f8/f1/3173dfa4a18db4a9b03e5d55325559dab51ee653763bb8745a75af491286/tornado-6.5.5.tar.gz", hash = "sha256:192b8f3ea91bd7f1f50c06955416ed76c6b72f96779b962f07f911b91e8d30e9", size = 516006, upload-time = "2026-03-10T21:31:02.067Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/59/8c/77f5097695f4dd8255ecbd08b2a1ed8ba8b953d337804dd7080f199e12bf/tornado-6.5.5-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:487dc9cc380e29f58c7ab88f9e27cdeef04b2140862e5076a66fb6bb68bb1bfa", size = 445983, upload-time = "2026-03-10T21:30:44.28Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/5e/7625b76cd10f98f1516c36ce0346de62061156352353ef2da44e5c21523c/tornado-6.5.5-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:65a7f1d46d4bb41df1ac99f5fcb685fb25c7e61613742d5108b010975a9a6521", size = 444246, upload-time = "2026-03-10T21:30:46.571Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/04/7b5705d5b3c0fab088f434f9c83edac1573830ca49ccf29fb83bf7178eec/tornado-6.5.5-cp39-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:e74c92e8e65086b338fd56333fb9a68b9f6f2fe7ad532645a290a464bcf46be5", size = 447229, upload-time = "2026-03-10T21:30:48.273Z" },
+    { url = "https://files.pythonhosted.org/packages/34/01/74e034a30ef59afb4097ef8659515e96a39d910b712a89af76f5e4e1f93c/tornado-6.5.5-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:435319e9e340276428bbdb4e7fa732c2d399386d1de5686cb331ec8eee754f07", size = 448192, upload-time = "2026-03-10T21:30:51.22Z" },
+    { url = "https://files.pythonhosted.org/packages/be/00/fe9e02c5a96429fce1a1d15a517f5d8444f9c412e0bb9eadfbe3b0fc55bf/tornado-6.5.5-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:3f54aa540bdbfee7b9eb268ead60e7d199de5021facd276819c193c0fb28ea4e", size = 448039, upload-time = "2026-03-10T21:30:53.52Z" },
+    { url = "https://files.pythonhosted.org/packages/82/9e/656ee4cec0398b1d18d0f1eb6372c41c6b889722641d84948351ae19556d/tornado-6.5.5-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:36abed1754faeb80fbd6e64db2758091e1320f6bba74a4cf8c09cd18ccce8aca", size = 447445, upload-time = "2026-03-10T21:30:55.541Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/76/4921c00511f88af86a33de770d64141170f1cfd9c00311aea689949e274e/tornado-6.5.5-cp39-abi3-win32.whl", hash = "sha256:dd3eafaaeec1c7f2f8fdcd5f964e8907ad788fe8a5a32c4426fbbdda621223b7", size = 448582, upload-time = "2026-03-10T21:30:57.142Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/23/f6c6112a04d28eed765e374435fb1a9198f73e1ec4b4024184f21faeb1ad/tornado-6.5.5-cp39-abi3-win_amd64.whl", hash = "sha256:6443a794ba961a9f619b1ae926a2e900ac20c34483eea67be4ed8f1e58d3ef7b", size = 448990, upload-time = "2026-03-10T21:30:58.857Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/c8/876602cbc96469911f0939f703453c1157b0c826ecb05bdd32e023397d4e/tornado-6.5.5-cp39-abi3-win_arm64.whl", hash = "sha256:2c9a876e094109333f888539ddb2de4361743e5d21eece20688e3e351e4990a6", size = 448016, upload-time = "2026-03-10T21:31:00.43Z" },
 ]
 
 [[package]]

From ca39da7de98b21fe935f155632b8e43e31d32fff Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 19:07:45 -0700
Subject: [PATCH 241/267] feat(admin): add user timestamps and enrich
 FullUserSnapshot - 2/9 (#9183)

---
 ...fb147a843f_add_timestamps_to_user_table.py | 43 ++++++++++
 backend/onyx/db/models.py                     | 10 +++
 backend/onyx/db/users.py                      | 41 +++++++++
 backend/onyx/server/manage/users.py           | 84 +++++++++++--------
 backend/onyx/server/models.py                 | 20 ++++-
 .../onyx/server/test_full_user_snapshot.py    | 54 ++++++++++++
 6 files changed, 214 insertions(+), 38 deletions(-)
 create mode 100644 backend/alembic/versions/27fb147a843f_add_timestamps_to_user_table.py
 create mode 100644 backend/tests/unit/onyx/server/test_full_user_snapshot.py

diff --git a/backend/alembic/versions/27fb147a843f_add_timestamps_to_user_table.py b/backend/alembic/versions/27fb147a843f_add_timestamps_to_user_table.py
new file mode 100644
index 00000000000..1f7f0777598
--- /dev/null
+++ b/backend/alembic/versions/27fb147a843f_add_timestamps_to_user_table.py
@@ -0,0 +1,43 @@
+"""add timestamps to user table
+
+Revision ID: 27fb147a843f
+Revises: b5c4d7e8f9a1
+Create Date: 2026-03-08 17:18:40.828644
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "27fb147a843f"
+down_revision = "b5c4d7e8f9a1"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "user",
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.add_column(
+        "user",
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("user", "updated_at")
+    op.drop_column("user", "created_at")
diff --git a/backend/onyx/db/models.py b/backend/onyx/db/models.py
index 10b66deefde..042bdc25218 100644
--- a/backend/onyx/db/models.py
+++ b/backend/onyx/db/models.py
@@ -339,6 +339,16 @@ class User(SQLAlchemyBaseUserTableUUID, Base):
         TIMESTAMPAware(timezone=True), nullable=True
     )
 
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
     default_model: Mapped[str] = mapped_column(Text, nullable=True)
     # organized in typical structured fashion
     # formatted as `displayName__provider__modelName`
diff --git a/backend/onyx/db/users.py b/backend/onyx/db/users.py
index 17851bc542e..e4180b540e2 100644
--- a/backend/onyx/db/users.py
+++ b/backend/onyx/db/users.py
@@ -24,6 +24,7 @@
 from onyx.db.models import SamlAccount
 from onyx.db.models import User
 from onyx.db.models import User__UserGroup
+from onyx.db.models import UserGroup
 from onyx.utils.variable_functionality import fetch_ee_implementation_or_noop
 
 
@@ -173,6 +174,21 @@ def _get_accepted_user_where_clause(
     return where_clause
 
 
+def get_all_accepted_users(
+    db_session: Session,
+    include_external: bool = False,
+) -> Sequence[User]:
+    """Returns all accepted users without pagination.
+    Uses the same filtering as the paginated endpoint but without
+    search, role, or active filters."""
+    stmt = select(User)
+    where_clause = _get_accepted_user_where_clause(
+        include_external=include_external,
+    )
+    stmt = stmt.where(*where_clause).order_by(User.email)
+    return db_session.scalars(stmt).unique().all()
+
+
 def get_page_of_filtered_users(
     db_session: Session,
     page_size: int,
@@ -358,3 +374,28 @@ def delete_user_from_db(
     # NOTE: edge case may exist with race conditions
     # with this `invited user` scheme generally.
     remove_user_from_invited_users(user_to_delete.email)
+
+
+def batch_get_user_groups(
+    db_session: Session,
+    user_ids: list[UUID],
+) -> dict[UUID, list[tuple[int, str]]]:
+    """Fetch group memberships for a batch of users in a single query.
+    Returns a mapping of user_id -> list of (group_id, group_name) tuples."""
+    if not user_ids:
+        return {}
+
+    rows = db_session.execute(
+        select(
+            User__UserGroup.user_id,
+            UserGroup.id,
+            UserGroup.name,
+        )
+        .join(UserGroup, UserGroup.id == User__UserGroup.user_group_id)
+        .where(User__UserGroup.user_id.in_(user_ids))
+    ).all()
+
+    result: dict[UUID, list[tuple[int, str]]] = {uid: [] for uid in user_ids}
+    for user_id, group_id, group_name in rows:
+        result[user_id].append((group_id, group_name))
+    return result
diff --git a/backend/onyx/server/manage/users.py b/backend/onyx/server/manage/users.py
index 9278ddc990a..dadfe186a64 100644
--- a/backend/onyx/server/manage/users.py
+++ b/backend/onyx/server/manage/users.py
@@ -67,7 +67,9 @@
 from onyx.db.user_preferences import update_user_shortcut_enabled
 from onyx.db.user_preferences import update_user_temperature_override_enabled
 from onyx.db.user_preferences import update_user_theme_preference
+from onyx.db.users import batch_get_user_groups
 from onyx.db.users import delete_user_from_db
+from onyx.db.users import get_all_accepted_users
 from onyx.db.users import get_all_users
 from onyx.db.users import get_page_of_filtered_users
 from onyx.db.users import get_total_filtered_users_count
@@ -98,6 +100,7 @@
 from onyx.server.models import FullUserSnapshot
 from onyx.server.models import InvitedUserSnapshot
 from onyx.server.models import MinimalUserSnapshot
+from onyx.server.models import UserGroupInfo
 from onyx.server.usage_limits import is_tenant_on_trial_fn
 from onyx.server.utils import BasicAuthenticationError
 from onyx.utils.logger import setup_logger
@@ -203,14 +206,51 @@ def list_accepted_users(
             total_items=0,
         )
 
+    user_ids = [user.id for user in filtered_accepted_users]
+    groups_by_user = batch_get_user_groups(db_session, user_ids)
+
     return PaginatedReturn(
         items=[
-            FullUserSnapshot.from_user_model(user) for user in filtered_accepted_users
+            FullUserSnapshot.from_user_model(
+                user,
+                groups=[
+                    UserGroupInfo(id=gid, name=gname)
+                    for gid, gname in groups_by_user.get(user.id, [])
+                ],
+            )
+            for user in filtered_accepted_users
         ],
         total_items=total_accepted_users_count,
     )
 
 
+@router.get("/manage/users/accepted/all", tags=PUBLIC_API_TAGS)
+def list_all_accepted_users(
+    _: User = Depends(current_admin_user),
+    db_session: Session = Depends(get_session),
+) -> list[FullUserSnapshot]:
+    """Returns all accepted users without pagination.
+    Used by the admin Users page for client-side filtering/sorting."""
+    users = get_all_accepted_users(db_session=db_session)
+
+    if not users:
+        return []
+
+    user_ids = [user.id for user in users]
+    groups_by_user = batch_get_user_groups(db_session, user_ids)
+
+    return [
+        FullUserSnapshot.from_user_model(
+            user,
+            groups=[
+                UserGroupInfo(id=gid, name=gname)
+                for gid, gname in groups_by_user.get(user.id, [])
+            ],
+        )
+        for user in users
+    ]
+
+
 @router.get("/manage/users/invited", tags=PUBLIC_API_TAGS)
 def list_invited_users(
     _: User = Depends(current_admin_user),
@@ -269,24 +309,10 @@ def list_all_users(
     if accepted_page is None or invited_page is None or slack_users_page is None:
         return AllUsersResponse(
             accepted=[
-                FullUserSnapshot(
-                    id=user.id,
-                    email=user.email,
-                    role=user.role,
-                    is_active=user.is_active,
-                    password_configured=user.password_configured,
-                )
-                for user in accepted_users
+                FullUserSnapshot.from_user_model(user) for user in accepted_users
             ],
             slack_users=[
-                FullUserSnapshot(
-                    id=user.id,
-                    email=user.email,
-                    role=user.role,
-                    is_active=user.is_active,
-                    password_configured=user.password_configured,
-                )
-                for user in slack_users
+                FullUserSnapshot.from_user_model(user) for user in slack_users
             ],
             invited=[InvitedUserSnapshot(email=email) for email in invited_emails],
             accepted_pages=1,
@@ -296,26 +322,10 @@ def list_all_users(
 
     # Otherwise, return paginated results
     return AllUsersResponse(
-        accepted=[
-            FullUserSnapshot(
-                id=user.id,
-                email=user.email,
-                role=user.role,
-                is_active=user.is_active,
-                password_configured=user.password_configured,
-            )
-            for user in accepted_users
-        ][accepted_page * USERS_PAGE_SIZE : (accepted_page + 1) * USERS_PAGE_SIZE],
-        slack_users=[
-            FullUserSnapshot(
-                id=user.id,
-                email=user.email,
-                role=user.role,
-                is_active=user.is_active,
-                password_configured=user.password_configured,
-            )
-            for user in slack_users
-        ][
+        accepted=[FullUserSnapshot.from_user_model(user) for user in accepted_users][
+            accepted_page * USERS_PAGE_SIZE : (accepted_page + 1) * USERS_PAGE_SIZE
+        ],
+        slack_users=[FullUserSnapshot.from_user_model(user) for user in slack_users][
             slack_users_page
             * USERS_PAGE_SIZE : (slack_users_page + 1)
             * USERS_PAGE_SIZE
diff --git a/backend/onyx/server/models.py b/backend/onyx/server/models.py
index 3e1b4a3ec07..73a26b777b3 100644
--- a/backend/onyx/server/models.py
+++ b/backend/onyx/server/models.py
@@ -1,3 +1,4 @@
+import datetime
 from typing import Generic
 from typing import Optional
 from typing import TypeVar
@@ -31,21 +32,38 @@ class MinimalUserSnapshot(BaseModel):
     email: str
 
 
+class UserGroupInfo(BaseModel):
+    id: int
+    name: str
+
+
 class FullUserSnapshot(BaseModel):
     id: UUID
     email: str
     role: UserRole
     is_active: bool
     password_configured: bool
+    personal_name: str | None
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+    groups: list[UserGroupInfo]
 
     @classmethod
-    def from_user_model(cls, user: User) -> "FullUserSnapshot":
+    def from_user_model(
+        cls,
+        user: User,
+        groups: list[UserGroupInfo] | None = None,
+    ) -> "FullUserSnapshot":
         return cls(
             id=user.id,
             email=user.email,
             role=user.role,
             is_active=user.is_active,
             password_configured=user.password_configured,
+            personal_name=user.personal_name,
+            created_at=user.created_at,
+            updated_at=user.updated_at,
+            groups=groups or [],
         )
 
 
diff --git a/backend/tests/unit/onyx/server/test_full_user_snapshot.py b/backend/tests/unit/onyx/server/test_full_user_snapshot.py
new file mode 100644
index 00000000000..cb75c95acbc
--- /dev/null
+++ b/backend/tests/unit/onyx/server/test_full_user_snapshot.py
@@ -0,0 +1,54 @@
+import datetime
+from unittest.mock import MagicMock
+from uuid import uuid4
+
+from onyx.auth.schemas import UserRole
+from onyx.server.models import FullUserSnapshot
+from onyx.server.models import UserGroupInfo
+
+
+def _mock_user(
+    personal_name: str | None = "Test User",
+    created_at: datetime.datetime | None = None,
+    updated_at: datetime.datetime | None = None,
+) -> MagicMock:
+    user = MagicMock()
+    user.id = uuid4()
+    user.email = "test@example.com"
+    user.role = UserRole.BASIC
+    user.is_active = True
+    user.password_configured = True
+    user.personal_name = personal_name
+    user.created_at = created_at or datetime.datetime(
+        2025, 1, 1, tzinfo=datetime.timezone.utc
+    )
+    user.updated_at = updated_at or datetime.datetime(
+        2025, 6, 15, tzinfo=datetime.timezone.utc
+    )
+    return user
+
+
+def test_from_user_model_includes_new_fields() -> None:
+    user = _mock_user(personal_name="Alice")
+    groups = [UserGroupInfo(id=1, name="Engineering")]
+
+    snapshot = FullUserSnapshot.from_user_model(user, groups=groups)
+
+    assert snapshot.personal_name == "Alice"
+    assert snapshot.created_at == user.created_at
+    assert snapshot.updated_at == user.updated_at
+    assert snapshot.groups == groups
+
+
+def test_from_user_model_defaults_groups_to_empty() -> None:
+    user = _mock_user()
+    snapshot = FullUserSnapshot.from_user_model(user)
+
+    assert snapshot.groups == []
+
+
+def test_from_user_model_personal_name_none() -> None:
+    user = _mock_user(personal_name=None)
+    snapshot = FullUserSnapshot.from_user_model(user)
+
+    assert snapshot.personal_name is None

From 781219cf188c983a328a849807ed5e4648efb12a Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 11 Mar 2026 19:17:09 -0700
Subject: [PATCH 242/267] chore(models): rm `claude-3-5-sonnet-v2` metadata
 (#9285)

---
 backend/onyx/llm/model_metadata_enrichments.json | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/backend/onyx/llm/model_metadata_enrichments.json b/backend/onyx/llm/model_metadata_enrichments.json
index bf017061e20..23db46c9310 100644
--- a/backend/onyx/llm/model_metadata_enrichments.json
+++ b/backend/onyx/llm/model_metadata_enrichments.json
@@ -3782,16 +3782,6 @@
     "display_name": "Claude Sonnet 3.5",
     "model_vendor": "anthropic"
   },
-  "vertex_ai/claude-3-5-sonnet-v2": {
-    "display_name": "Claude Sonnet 3.5",
-    "model_vendor": "anthropic",
-    "model_version": "v2"
-  },
-  "vertex_ai/claude-3-5-sonnet-v2@20241022": {
-    "display_name": "Claude Sonnet 3.5 v2",
-    "model_vendor": "anthropic",
-    "model_version": "20241022"
-  },
   "vertex_ai/claude-3-5-sonnet@20240620": {
     "display_name": "Claude Sonnet 3.5",
     "model_vendor": "anthropic",

From f01f210af85b959177b390f3a9d43370f4b2f5e7 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 19:37:03 -0700
Subject: [PATCH 243/267] fix(slackbot): resolve channel references and filter
 search by channel tags (#9256)

---
 backend/onyx/onyxbot/slack/constants.py       |   4 +
 .../slack/handlers/handle_regular_answer.py   |  74 +++++++
 .../onyxbot/test_handle_regular_answer.py     | 204 ++++++++++++++++++
 3 files changed, 282 insertions(+)
 create mode 100644 backend/tests/unit/onyx/onyxbot/test_handle_regular_answer.py

diff --git a/backend/onyx/onyxbot/slack/constants.py b/backend/onyx/onyxbot/slack/constants.py
index 1f2d4ed68b7..fab3f5bf3e0 100644
--- a/backend/onyx/onyxbot/slack/constants.py
+++ b/backend/onyx/onyxbot/slack/constants.py
@@ -1,5 +1,9 @@
+import re
 from enum import Enum
 
+# Matches Slack channel references like <#C097NBWMY8Y> or <#C097NBWMY8Y|channel-name>
+SLACK_CHANNEL_REF_PATTERN = re.compile(r"<#([A-Z0-9]+)(?:\|([^>]+))?>")
+
 LIKE_BLOCK_ACTION_ID = "feedback-like"
 DISLIKE_BLOCK_ACTION_ID = "feedback-dislike"
 SHOW_EVERYONE_ACTION_ID = "show-everyone"
diff --git a/backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py b/backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py
index 320ee9d9e3f..3b08063ac94 100644
--- a/backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py
+++ b/backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py
@@ -18,15 +18,18 @@
 from onyx.configs.onyxbot_configs import ONYX_BOT_NUM_RETRIES
 from onyx.configs.onyxbot_configs import ONYX_BOT_REACT_EMOJI
 from onyx.context.search.models import BaseFilters
+from onyx.context.search.models import Tag
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.models import SlackChannelConfig
 from onyx.db.models import User
 from onyx.db.persona import get_persona_by_id
 from onyx.db.users import get_user_by_email
 from onyx.onyxbot.slack.blocks import build_slack_response_blocks
+from onyx.onyxbot.slack.constants import SLACK_CHANNEL_REF_PATTERN
 from onyx.onyxbot.slack.handlers.utils import send_team_member_message
 from onyx.onyxbot.slack.models import SlackMessageInfo
 from onyx.onyxbot.slack.models import ThreadMessage
+from onyx.onyxbot.slack.utils import get_channel_from_id
 from onyx.onyxbot.slack.utils import get_channel_name_from_id
 from onyx.onyxbot.slack.utils import respond_in_thread_or_channel
 from onyx.onyxbot.slack.utils import SlackRateLimiter
@@ -41,6 +44,51 @@
 RT = TypeVar("RT")  # return type
 
 
+def resolve_channel_references(
+    message: str,
+    client: WebClient,
+    logger: OnyxLoggingAdapter,
+) -> tuple[str, list[Tag]]:
+    """Parse Slack channel references from a message, resolve IDs to names,
+    replace the raw markup with readable #channel-name, and return channel tags
+    for search filtering."""
+    tags: list[Tag] = []
+    channel_matches = SLACK_CHANNEL_REF_PATTERN.findall(message)
+    seen_channel_ids: set[str] = set()
+
+    for channel_id, channel_name_from_markup in channel_matches:
+        if channel_id in seen_channel_ids:
+            continue
+        seen_channel_ids.add(channel_id)
+
+        channel_name = channel_name_from_markup or None
+
+        if not channel_name:
+            try:
+                channel_info = get_channel_from_id(client=client, channel_id=channel_id)
+                channel_name = channel_info.get("name") or None
+            except Exception:
+                logger.warning(f"Failed to resolve channel name for ID: {channel_id}")
+
+            if not channel_name:
+                continue
+
+        # Replace raw Slack markup with readable channel name
+        if channel_name_from_markup:
+            message = message.replace(
+                f"<#{channel_id}|{channel_name_from_markup}>",
+                f"#{channel_name}",
+            )
+        else:
+            message = message.replace(
+                f"<#{channel_id}>",
+                f"#{channel_name}",
+            )
+        tags.append(Tag(tag_key="Channel", tag_value=channel_name))
+
+    return message, tags
+
+
 def rate_limits(
     client: WebClient, channel: str, thread_ts: Optional[str]
 ) -> Callable[[Callable[..., RT]], Callable[..., RT]]:
@@ -157,6 +205,20 @@ def handle_regular_answer(
     user_message = messages[-1]
     history_messages = messages[:-1]
 
+    # Resolve any <#CHANNEL_ID> references in the user message to readable
+    # channel names and extract channel tags for search filtering
+    resolved_message, channel_tags = resolve_channel_references(
+        message=user_message.message,
+        client=client,
+        logger=logger,
+    )
+
+    user_message = ThreadMessage(
+        message=resolved_message,
+        sender=user_message.sender,
+        role=user_message.role,
+    )
+
     channel_name, _ = get_channel_name_from_id(
         client=client,
         channel_id=channel,
@@ -207,6 +269,7 @@ def _get_slack_answer(
             source_type=None,
             document_set=document_set_names,
             time_cutoff=None,
+            tags=channel_tags if channel_tags else None,
         )
 
         new_message_request = SendMessageRequest(
@@ -231,6 +294,16 @@ def _get_slack_answer(
             slack_context_str=slack_context_str,
         )
 
+        # If a channel filter was applied but no results were found, override
+        # the LLM response to avoid hallucinated answers about unindexed channels
+        if channel_tags and not answer.citation_info and not answer.top_documents:
+            channel_names = ", ".join(f"#{tag.tag_value}" for tag in channel_tags)
+            answer.answer = (
+                f"No indexed data found for {channel_names}. "
+                "This channel may not be indexed, or there may be no messages "
+                "matching your query within it."
+            )
+
     except Exception as e:
         logger.exception(
             f"Unable to process message - did not successfully answer "
@@ -285,6 +358,7 @@ def _get_slack_answer(
         only_respond_if_citations
         and not answer.citation_info
         and not message_info.bypass_filters
+        and not channel_tags
     ):
         logger.error(
             f"Unable to find citations to answer: '{answer.answer}' - not answering!"
diff --git a/backend/tests/unit/onyx/onyxbot/test_handle_regular_answer.py b/backend/tests/unit/onyx/onyxbot/test_handle_regular_answer.py
new file mode 100644
index 00000000000..1751403f6c8
--- /dev/null
+++ b/backend/tests/unit/onyx/onyxbot/test_handle_regular_answer.py
@@ -0,0 +1,204 @@
+"""Tests for Slack channel reference resolution and tag filtering
+in handle_regular_answer.py."""
+
+from unittest.mock import MagicMock
+
+from slack_sdk.errors import SlackApiError
+
+from onyx.context.search.models import Tag
+from onyx.onyxbot.slack.constants import SLACK_CHANNEL_REF_PATTERN
+from onyx.onyxbot.slack.handlers.handle_regular_answer import resolve_channel_references
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _mock_client_with_channels(
+    channel_map: dict[str, str],
+) -> MagicMock:
+    """Return a mock WebClient where conversations_info resolves IDs to names."""
+    client = MagicMock()
+
+    def _conversations_info(channel: str) -> MagicMock:
+        if channel in channel_map:
+            resp = MagicMock()
+            resp.validate = MagicMock()
+            resp.__getitem__ = lambda _self, key: {
+                "channel": {
+                    "name": channel_map[channel],
+                    "is_im": False,
+                    "is_mpim": False,
+                }
+            }[key]
+            return resp
+        raise SlackApiError("channel_not_found", response=MagicMock())
+
+    client.conversations_info = _conversations_info
+    return client
+
+
+def _mock_logger() -> MagicMock:
+    return MagicMock()
+
+
+# ---------------------------------------------------------------------------
+# SLACK_CHANNEL_REF_PATTERN regex tests
+# ---------------------------------------------------------------------------
+
+
+class TestSlackChannelRefPattern:
+    def test_matches_bare_channel_id(self) -> None:
+        matches = SLACK_CHANNEL_REF_PATTERN.findall("<#C097NBWMY8Y>")
+        assert matches == [("C097NBWMY8Y", "")]
+
+    def test_matches_channel_id_with_name(self) -> None:
+        matches = SLACK_CHANNEL_REF_PATTERN.findall("<#C097NBWMY8Y|eng-infra>")
+        assert matches == [("C097NBWMY8Y", "eng-infra")]
+
+    def test_matches_multiple_channels(self) -> None:
+        msg = "compare <#C111AAA> and <#C222BBB|general>"
+        matches = SLACK_CHANNEL_REF_PATTERN.findall(msg)
+        assert len(matches) == 2
+        assert ("C111AAA", "") in matches
+        assert ("C222BBB", "general") in matches
+
+    def test_no_match_on_plain_text(self) -> None:
+        matches = SLACK_CHANNEL_REF_PATTERN.findall("no channels here")
+        assert matches == []
+
+    def test_no_match_on_user_mention(self) -> None:
+        matches = SLACK_CHANNEL_REF_PATTERN.findall("<@U12345>")
+        assert matches == []
+
+
+# ---------------------------------------------------------------------------
+# resolve_channel_references tests
+# ---------------------------------------------------------------------------
+
+
+class TestResolveChannelReferences:
+    def test_resolves_bare_channel_id_via_api(self) -> None:
+        client = _mock_client_with_channels({"C097NBWMY8Y": "eng-infra"})
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="summary of <#C097NBWMY8Y> this week",
+            client=client,
+            logger=logger,
+        )
+
+        assert message == "summary of #eng-infra this week"
+        assert len(tags) == 1
+        assert tags[0] == Tag(tag_key="Channel", tag_value="eng-infra")
+
+    def test_uses_name_from_pipe_format_without_api_call(self) -> None:
+        client = MagicMock()
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="check <#C097NBWMY8Y|eng-infra> for updates",
+            client=client,
+            logger=logger,
+        )
+
+        assert message == "check #eng-infra for updates"
+        assert tags == [Tag(tag_key="Channel", tag_value="eng-infra")]
+        # Should NOT have called the API since name was in the markup
+        client.conversations_info.assert_not_called()
+
+    def test_multiple_channels(self) -> None:
+        client = _mock_client_with_channels(
+            {
+                "C111AAA": "eng-infra",
+                "C222BBB": "eng-general",
+            }
+        )
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="compare <#C111AAA> and <#C222BBB>",
+            client=client,
+            logger=logger,
+        )
+
+        assert "#eng-infra" in message
+        assert "#eng-general" in message
+        assert "<#" not in message
+        assert len(tags) == 2
+        tag_values = {t.tag_value for t in tags}
+        assert tag_values == {"eng-infra", "eng-general"}
+
+    def test_no_channel_references_returns_unchanged(self) -> None:
+        client = MagicMock()
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="just a normal message with no channels",
+            client=client,
+            logger=logger,
+        )
+
+        assert message == "just a normal message with no channels"
+        assert tags == []
+
+    def test_api_failure_skips_channel_gracefully(self) -> None:
+        # Client that fails for all channel lookups
+        client = _mock_client_with_channels({})
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="check <#CBADID123>",
+            client=client,
+            logger=logger,
+        )
+
+        # Message should remain unchanged for the failed channel
+        assert "<#CBADID123>" in message
+        assert tags == []
+        logger.warning.assert_called_once()
+
+    def test_partial_failure_resolves_what_it_can(self) -> None:
+        # Only one of two channels resolves
+        client = _mock_client_with_channels({"C111AAA": "eng-infra"})
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="compare <#C111AAA> and <#CBADID123>",
+            client=client,
+            logger=logger,
+        )
+
+        assert "#eng-infra" in message
+        assert "<#CBADID123>" in message  # failed one stays raw
+        assert len(tags) == 1
+        assert tags[0].tag_value == "eng-infra"
+
+    def test_duplicate_channel_produces_single_tag(self) -> None:
+        client = _mock_client_with_channels({"C111AAA": "eng-infra"})
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="summarize <#C111AAA> and compare with <#C111AAA>",
+            client=client,
+            logger=logger,
+        )
+
+        assert message == "summarize #eng-infra and compare with #eng-infra"
+        assert len(tags) == 1
+        assert tags[0].tag_value == "eng-infra"
+
+    def test_mixed_pipe_and_bare_formats(self) -> None:
+        client = _mock_client_with_channels({"C222BBB": "random"})
+        logger = _mock_logger()
+
+        message, tags = resolve_channel_references(
+            message="see <#C111AAA|eng-infra> and <#C222BBB>",
+            client=client,
+            logger=logger,
+        )
+
+        assert "#eng-infra" in message
+        assert "#random" in message
+        assert len(tags) == 2

From df5252db0577bb4c066c38939b5661682be11f67 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 11 Mar 2026 20:07:23 -0700
Subject: [PATCH 244/267] chore(devtools): `ods backend api` (#9295)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 tools/ods/README.md      |  50 ++++++++
 tools/ods/cmd/backend.go | 242 +++++++++++++++++++++++++++++++++++++++
 tools/ods/cmd/root.go    |   1 +
 3 files changed, 293 insertions(+)
 create mode 100644 tools/ods/cmd/backend.go

diff --git a/tools/ods/README.md b/tools/ods/README.md
index 495ff223a16..90a91570726 100644
--- a/tools/ods/README.md
+++ b/tools/ods/README.md
@@ -25,6 +25,9 @@ Some commands require external tools to be installed and configured:
 - **Docker** - Required for `compose`, `logs`, and `pull` commands
   - Install from [docker.com](https://docs.docker.com/get-docker/)
 
+- **uv** - Required for `backend` commands
+  - Install from [docs.astral.sh/uv](https://docs.astral.sh/uv/)
+
 - **GitHub CLI** (`gh`) - Required for `run-ci` and `cherry-pick` commands
   - Install from [cli.github.com](https://cli.github.com/)
   - Authenticate with `gh auth login`
@@ -170,6 +173,53 @@ ods pull
 ods pull --tag edge
 ```
 
+### `backend` - Run Backend Services
+
+Run backend services (API server, model server) with environment loaded from
+`.vscode/.env`. On first run, copies `.vscode/env_template.txt` to `.vscode/.env`
+if the `.env` file does not already exist.
+
+Enterprise Edition features are enabled by default with license enforcement
+disabled, matching the `compose` command behavior.
+
+```shell
+ods backend <subcommand>
+```
+
+**Subcommands:**
+
+- `api` - Start the FastAPI backend server (`uvicorn onyx.main:app --reload`)
+- `model_server` - Start the model server (`uvicorn model_server.main:app --reload`)
+
+**Flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--no-ee` | `false` | Disable Enterprise Edition features (enabled by default) |
+| `--port` | `8080` (api) / `9000` (model_server) | Port to listen on |
+
+Shell environment takes precedence over `.env` file values, so inline overrides
+work as expected (e.g. `S3_ENDPOINT_URL=foo ods backend api`).
+
+**Examples:**
+
+```shell
+# Start the API server
+ods backend api
+
+# Start the API server on a custom port
+ods backend api --port 9090
+
+# Start without Enterprise Edition
+ods backend api --no-ee
+
+# Start the model server
+ods backend model_server
+
+# Start the model server on a custom port
+ods backend model_server --port 9001
+```
+
 ### `web` - Run Frontend Scripts
 
 Run npm scripts from `web/package.json` without manually changing directories.
diff --git a/tools/ods/cmd/backend.go b/tools/ods/cmd/backend.go
new file mode 100644
index 00000000000..5e17234176e
--- /dev/null
+++ b/tools/ods/cmd/backend.go
@@ -0,0 +1,242 @@
+package cmd
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+
+	"github.com/onyx-dot-app/onyx/tools/ods/internal/paths"
+)
+
+// NewBackendCommand creates the parent "backend" command with subcommands for
+// running backend services.
+// BackendOptions holds options shared across backend subcommands.
+type BackendOptions struct {
+	NoEE bool
+}
+
+func NewBackendCommand() *cobra.Command {
+	opts := &BackendOptions{}
+
+	cmd := &cobra.Command{
+		Use:   "backend",
+		Short: "Run backend services (api, model_server)",
+		Long: `Run backend services with environment from .vscode/.env.
+
+On first run, copies .vscode/env_template.txt to .vscode/.env if the
+.env file does not already exist.
+
+Enterprise Edition features are enabled by default for development,
+with license enforcement disabled.
+
+Available subcommands:
+  api            Start the FastAPI backend server
+  model_server   Start the model server`,
+	}
+
+	cmd.PersistentFlags().BoolVar(&opts.NoEE, "no-ee", false, "Disable Enterprise Edition features (enabled by default)")
+
+	cmd.AddCommand(newBackendAPICommand(opts))
+	cmd.AddCommand(newBackendModelServerCommand(opts))
+
+	return cmd
+}
+
+func newBackendAPICommand(opts *BackendOptions) *cobra.Command {
+	var port string
+
+	cmd := &cobra.Command{
+		Use:   "api",
+		Short: "Start the backend API server (uvicorn with hot-reload)",
+		Long: `Start the backend API server using uvicorn with hot-reload.
+
+Examples:
+  ods backend api
+  ods backend api --port 9090
+  ods backend api --no-ee`,
+		Run: func(cmd *cobra.Command, args []string) {
+			runBackendService("api", "onyx.main:app", port, opts)
+		},
+	}
+
+	cmd.Flags().StringVar(&port, "port", "8080", "Port to listen on")
+
+	return cmd
+}
+
+func newBackendModelServerCommand(opts *BackendOptions) *cobra.Command {
+	var port string
+
+	cmd := &cobra.Command{
+		Use:   "model_server",
+		Short: "Start the model server (uvicorn with hot-reload)",
+		Long: `Start the model server using uvicorn with hot-reload.
+
+Examples:
+  ods backend model_server
+  ods backend model_server --port 9001`,
+		Run: func(cmd *cobra.Command, args []string) {
+			runBackendService("model_server", "model_server.main:app", port, opts)
+		},
+	}
+
+	cmd.Flags().StringVar(&port, "port", "9000", "Port to listen on")
+
+	return cmd
+}
+
+func runBackendService(name, module, port string, opts *BackendOptions) {
+	root, err := paths.GitRoot()
+	if err != nil {
+		log.Fatalf("Failed to find git root: %v", err)
+	}
+
+	envFile := ensureBackendEnvFile(root)
+	fileVars := loadBackendEnvFile(envFile)
+
+	eeDefaults := eeEnvDefaults(opts.NoEE)
+	fileVars = append(fileVars, eeDefaults...)
+
+	backendDir := filepath.Join(root, "backend")
+
+	uvicornArgs := []string{
+		"run", "uvicorn", module,
+		"--reload",
+		"--port", port,
+	}
+	log.Infof("Starting %s on port %s...", name, port)
+	if !opts.NoEE {
+		log.Info("Enterprise Edition enabled (use --no-ee to disable)")
+	}
+	log.Debugf("Running in %s: uv %v", backendDir, uvicornArgs)
+
+	mergedEnv := mergeEnv(os.Environ(), fileVars)
+	log.Debugf("Applied %d env vars from %s (shell takes precedence)", len(fileVars), envFile)
+
+	svcCmd := exec.Command("uv", uvicornArgs...)
+	svcCmd.Dir = backendDir
+	svcCmd.Stdout = os.Stdout
+	svcCmd.Stderr = os.Stderr
+	svcCmd.Stdin = os.Stdin
+	svcCmd.Env = mergedEnv
+
+	if err := svcCmd.Run(); err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			if code := exitErr.ExitCode(); code != -1 {
+				os.Exit(code)
+			}
+		}
+		log.Fatalf("Failed to run %s: %v", name, err)
+	}
+}
+
+// eeEnvDefaults returns env entries for EE and license enforcement settings.
+// These are appended to the file vars so they act as defaults — shell env
+// and .env file values still take precedence via mergeEnv.
+func eeEnvDefaults(noEE bool) []string {
+	if noEE {
+		return []string{
+			"ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=false",
+		}
+	}
+	return []string{
+		"ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=true",
+		"LICENSE_ENFORCEMENT_ENABLED=false",
+	}
+}
+
+// ensureBackendEnvFile copies env_template.txt to .env if .env doesn't exist.
+func ensureBackendEnvFile(root string) string {
+	vscodeDir := filepath.Join(root, ".vscode")
+	envFile := filepath.Join(vscodeDir, ".env")
+	templateFile := filepath.Join(vscodeDir, "env_template.txt")
+
+	if _, err := os.Stat(envFile); err != nil {
+		if !errors.Is(err, os.ErrNotExist) {
+			log.Fatalf("Failed to stat env file %s: %v", envFile, err)
+		}
+	} else {
+		log.Debugf("Using existing env file: %s", envFile)
+		return envFile
+	}
+
+	templateData, err := os.ReadFile(templateFile)
+	if err != nil {
+		log.Fatalf("Failed to read env template %s: %v", templateFile, err)
+	}
+
+	if err := os.MkdirAll(vscodeDir, 0755); err != nil {
+		log.Fatalf("Failed to create .vscode directory: %v", err)
+	}
+
+	if err := os.WriteFile(envFile, templateData, 0644); err != nil {
+		log.Fatalf("Failed to write env file %s: %v", envFile, err)
+	}
+
+	log.Infof("Created %s from template (review and fill in <REPLACE THIS> values)", envFile)
+	return envFile
+}
+
+// mergeEnv combines shell environment with file-based defaults. Shell values
+// take precedence — file entries are only added for keys not already present.
+func mergeEnv(shellEnv, fileVars []string) []string {
+	existing := make(map[string]bool, len(shellEnv))
+	for _, entry := range shellEnv {
+		if idx := strings.Index(entry, "="); idx > 0 {
+			existing[entry[:idx]] = true
+		}
+	}
+
+	merged := make([]string, len(shellEnv))
+	copy(merged, shellEnv)
+	for _, entry := range fileVars {
+		if idx := strings.Index(entry, "="); idx > 0 {
+			key := entry[:idx]
+			if !existing[key] {
+				merged = append(merged, entry)
+			} else {
+				log.Debugf("Env var %s already set in shell, skipping .env value", key)
+			}
+		}
+	}
+	return merged
+}
+
+// loadBackendEnvFile parses a .env file into KEY=VALUE entries suitable for
+// appending to os.Environ(). Blank lines and comments are skipped.
+func loadBackendEnvFile(path string) []string {
+	f, err := os.Open(path)
+	if err != nil {
+		log.Fatalf("Failed to open env file %s: %v", path, err)
+	}
+	defer func() { _ = f.Close() }()
+
+	var envVars []string
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		if idx := strings.Index(line, "="); idx > 0 {
+			key := strings.TrimSpace(line[:idx])
+			value := strings.TrimSpace(line[idx+1:])
+			value = strings.Trim(value, `"'`)
+			envVars = append(envVars, fmt.Sprintf("%s=%s", key, value))
+		}
+	}
+
+	if err := scanner.Err(); err != nil {
+		log.Fatalf("Failed to read env file %s: %v", path, err)
+	}
+
+	return envVars
+}
diff --git a/tools/ods/cmd/root.go b/tools/ods/cmd/root.go
index c6490d8f762..a469602573c 100644
--- a/tools/ods/cmd/root.go
+++ b/tools/ods/cmd/root.go
@@ -41,6 +41,7 @@ func NewRootCommand() *cobra.Command {
 	cmd.PersistentFlags().BoolVar(&opts.Debug, "debug", false, "run in debug mode")
 
 	// Add subcommands
+	cmd.AddCommand(NewBackendCommand())
 	cmd.AddCommand(NewCheckLazyImportsCommand())
 	cmd.AddCommand(NewCherryPickCommand())
 	cmd.AddCommand(NewDBCommand())

From e1df3f533aff5af778b6db41411dd872b40dc87e Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 20:26:07 -0700
Subject: [PATCH 245/267] feat(admin): add Users table with DataTable and
 server-side pagination - 3/9 (#9178)

---
 backend/onyx/db/users.py                      |   9 +-
 backend/onyx/server/manage/users.py           |  34 +++
 backend/onyx/server/models.py                 |   3 +
 web/jest.config.js                            |   1 +
 web/src/hooks/useAdminUsers.ts                |  19 ++
 .../table/TableQualifier.tsx                  |   9 +-
 web/src/refresh-pages/admin/UsersPage.tsx     |   3 +-
 .../admin/UsersPage/UsersTable.tsx            | 198 ++++++++++++++++++
 .../admin/UsersPage/interfaces.ts             |  20 ++
 .../admin/UsersPage/utils.test.ts             |  43 ++++
 .../refresh-pages/admin/UsersPage/utils.ts    |  23 ++
 11 files changed, 358 insertions(+), 4 deletions(-)
 create mode 100644 web/src/hooks/useAdminUsers.ts
 create mode 100644 web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
 create mode 100644 web/src/refresh-pages/admin/UsersPage/interfaces.ts
 create mode 100644 web/src/refresh-pages/admin/UsersPage/utils.test.ts
 create mode 100644 web/src/refresh-pages/admin/UsersPage/utils.ts

diff --git a/backend/onyx/db/users.py b/backend/onyx/db/users.py
index e4180b540e2..b27210f410a 100644
--- a/backend/onyx/db/users.py
+++ b/backend/onyx/db/users.py
@@ -11,6 +11,7 @@
 from sqlalchemy.sql import expression
 from sqlalchemy.sql.elements import ColumnElement
 from sqlalchemy.sql.elements import KeyedColumnElement
+from sqlalchemy.sql.expression import or_
 
 from onyx.auth.invited_users import remove_user_from_invited_users
 from onyx.auth.schemas import UserRole
@@ -163,7 +164,13 @@ def _get_accepted_user_where_clause(
         where_clause.append(User.role != UserRole.EXT_PERM_USER)
 
     if email_filter_string is not None:
-        where_clause.append(email_col.ilike(f"%{email_filter_string}%"))
+        personal_name_col: KeyedColumnElement[Any] = User.__table__.c.personal_name
+        where_clause.append(
+            or_(
+                email_col.ilike(f"%{email_filter_string}%"),
+                personal_name_col.ilike(f"%{email_filter_string}%"),
+            )
+        )
 
     if roles_filter:
         where_clause.append(User.role.in_(roles_filter))
diff --git a/backend/onyx/server/manage/users.py b/backend/onyx/server/manage/users.py
index dadfe186a64..8a5ba3f2047 100644
--- a/backend/onyx/server/manage/users.py
+++ b/backend/onyx/server/manage/users.py
@@ -5,6 +5,7 @@
 from datetime import timedelta
 from datetime import timezone
 from typing import cast
+from uuid import UUID
 
 import jwt
 from email_validator import EmailNotValidError
@@ -18,6 +19,7 @@
 from fastapi import Request
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from onyx.auth.anonymous_user import fetch_anonymous_user_info
@@ -209,6 +211,21 @@ def list_accepted_users(
     user_ids = [user.id for user in filtered_accepted_users]
     groups_by_user = batch_get_user_groups(db_session, user_ids)
 
+    # Batch-fetch SCIM mappings to mark synced users
+    scim_synced_ids: set[UUID] = set()
+    try:
+        from onyx.db.models import ScimUserMapping
+
+        scim_mappings = db_session.scalars(
+            select(ScimUserMapping.user_id).where(ScimUserMapping.user_id.in_(user_ids))
+        ).all()
+        scim_synced_ids = set(scim_mappings)
+    except Exception:
+        logger.warning(
+            "Failed to fetch SCIM mappings; marking all users as non-synced",
+            exc_info=True,
+        )
+
     return PaginatedReturn(
         items=[
             FullUserSnapshot.from_user_model(
@@ -217,6 +234,7 @@ def list_accepted_users(
                     UserGroupInfo(id=gid, name=gname)
                     for gid, gname in groups_by_user.get(user.id, [])
                 ],
+                is_scim_synced=user.id in scim_synced_ids,
             )
             for user in filtered_accepted_users
         ],
@@ -239,6 +257,21 @@ def list_all_accepted_users(
     user_ids = [user.id for user in users]
     groups_by_user = batch_get_user_groups(db_session, user_ids)
 
+    # Batch-fetch SCIM mappings to mark synced users
+    scim_synced_ids: set[UUID] = set()
+    try:
+        from onyx.db.models import ScimUserMapping
+
+        scim_mappings = db_session.scalars(
+            select(ScimUserMapping.user_id).where(ScimUserMapping.user_id.in_(user_ids))
+        ).all()
+        scim_synced_ids = set(scim_mappings)
+    except Exception:
+        logger.warning(
+            "Failed to fetch SCIM mappings; marking all users as non-synced",
+            exc_info=True,
+        )
+
     return [
         FullUserSnapshot.from_user_model(
             user,
@@ -246,6 +279,7 @@ def list_all_accepted_users(
                 UserGroupInfo(id=gid, name=gname)
                 for gid, gname in groups_by_user.get(user.id, [])
             ],
+            is_scim_synced=user.id in scim_synced_ids,
         )
         for user in users
     ]
diff --git a/backend/onyx/server/models.py b/backend/onyx/server/models.py
index 73a26b777b3..88fdf927e6d 100644
--- a/backend/onyx/server/models.py
+++ b/backend/onyx/server/models.py
@@ -47,12 +47,14 @@ class FullUserSnapshot(BaseModel):
     created_at: datetime.datetime
     updated_at: datetime.datetime
     groups: list[UserGroupInfo]
+    is_scim_synced: bool
 
     @classmethod
     def from_user_model(
         cls,
         user: User,
         groups: list[UserGroupInfo] | None = None,
+        is_scim_synced: bool = False,
     ) -> "FullUserSnapshot":
         return cls(
             id=user.id,
@@ -64,6 +66,7 @@ def from_user_model(
             created_at=user.created_at,
             updated_at=user.updated_at,
             groups=groups or [],
+            is_scim_synced=is_scim_synced,
         )
 
 
diff --git a/web/jest.config.js b/web/jest.config.js
index 0fc47bc6c25..120f4811202 100644
--- a/web/jest.config.js
+++ b/web/jest.config.js
@@ -143,6 +143,7 @@ module.exports = {
         "**/src/app/**/utils/*.test.ts",
         "**/src/app/**/hooks/*.test.ts", // Pure packet processor tests
         "**/src/refresh-components/**/*.test.ts",
+        "**/src/refresh-pages/**/*.test.ts",
         "**/src/sections/**/*.test.ts",
         "**/src/components/**/*.test.ts",
         // Add more patterns here as you add more unit tests
diff --git a/web/src/hooks/useAdminUsers.ts b/web/src/hooks/useAdminUsers.ts
new file mode 100644
index 00000000000..a65d9e5487a
--- /dev/null
+++ b/web/src/hooks/useAdminUsers.ts
@@ -0,0 +1,19 @@
+"use client";
+
+import useSWR from "swr";
+import { errorHandlingFetcher } from "@/lib/fetcher";
+import type { UserRow } from "@/refresh-pages/admin/UsersPage/interfaces";
+
+export default function useAdminUsers() {
+  const { data, isLoading, error, mutate } = useSWR<UserRow[]>(
+    "/api/manage/users/accepted/all",
+    errorHandlingFetcher
+  );
+
+  return {
+    users: data ?? [],
+    isLoading,
+    error,
+    refresh: mutate,
+  };
+}
diff --git a/web/src/refresh-components/table/TableQualifier.tsx b/web/src/refresh-components/table/TableQualifier.tsx
index 047602654c4..3bfafff400c 100644
--- a/web/src/refresh-components/table/TableQualifier.tsx
+++ b/web/src/refresh-components/table/TableQualifier.tsx
@@ -114,11 +114,16 @@ function TableQualifier({
         return (
           <div
             className={cn(
-              "flex items-center justify-center rounded-full bg-text-05",
+              "flex items-center justify-center rounded-full bg-background-neutral-inverted-00",
               resolvedSize === "regular" ? "h-7 w-7" : "h-6 w-6"
             )}
           >
-            <Text secondaryAction textLight05 className="select-none uppercase">
+            <Text
+              inverted
+              secondaryAction
+              text05
+              className="select-none uppercase"
+            >
               {initials}
             </Text>
           </div>
diff --git a/web/src/refresh-pages/admin/UsersPage.tsx b/web/src/refresh-pages/admin/UsersPage.tsx
index b94ddcf87de..2e3931c846f 100644
--- a/web/src/refresh-pages/admin/UsersPage.tsx
+++ b/web/src/refresh-pages/admin/UsersPage.tsx
@@ -8,6 +8,7 @@ import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidE
 import useUserCounts from "@/hooks/useUserCounts";
 
 import UsersSummary from "./UsersPage/UsersSummary";
+import UsersTable from "./UsersPage/UsersTable";
 
 // ---------------------------------------------------------------------------
 // Users page content
@@ -30,7 +31,7 @@ function UsersContent() {
         showScim={showScim}
       />
 
-      {/* Table and filters will be added in subsequent PRs */}
+      <UsersTable />
     </>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
new file mode 100644
index 00000000000..ec07269504e
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
@@ -0,0 +1,198 @@
+"use client";
+
+import { useState } from "react";
+import DataTable from "@/refresh-components/table/DataTable";
+import { createTableColumns } from "@/refresh-components/table/columns";
+import { Content } from "@opal/layouts";
+import { USER_ROLE_LABELS, UserRole } from "@/lib/types";
+import { timeAgo } from "@/lib/time";
+import Text from "@/refresh-components/texts/Text";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import useAdminUsers from "@/hooks/useAdminUsers";
+import { ThreeDotsLoader } from "@/components/Loading";
+import { SvgUser, SvgUsers, SvgSlack } from "@opal/icons";
+import type { IconFunctionComponent } from "@opal/types";
+import type { UserRow, UserGroupInfo } from "./interfaces";
+import { getInitials } from "./utils";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PAGE_SIZE = 8;
+
+const ROLE_ICONS: Record<UserRole, IconFunctionComponent> = {
+  [UserRole.BASIC]: SvgUser,
+  [UserRole.ADMIN]: SvgUser,
+  [UserRole.GLOBAL_CURATOR]: SvgUsers,
+  [UserRole.CURATOR]: SvgUsers,
+  [UserRole.LIMITED]: SvgUser,
+  [UserRole.EXT_PERM_USER]: SvgUser,
+  [UserRole.SLACK_USER]: SvgSlack,
+};
+
+// ---------------------------------------------------------------------------
+// Column renderers
+// ---------------------------------------------------------------------------
+
+function renderNameColumn(email: string, row: UserRow) {
+  return (
+    <Content
+      sizePreset="main-ui"
+      variant="section"
+      title={row.personal_name ?? email}
+      description={row.personal_name ? email : undefined}
+    />
+  );
+}
+
+function renderGroupsColumn(groups: UserGroupInfo[]) {
+  if (!groups.length) {
+    return (
+      <Text as="span" secondaryBody text03>
+        {"\u2014"}
+      </Text>
+    );
+  }
+  const visible = groups.slice(0, 2);
+  const overflow = groups.length - visible.length;
+  return (
+    <div className="flex items-center gap-1 flex-nowrap overflow-hidden min-w-0">
+      {visible.map((g) => (
+        <span
+          key={g.id}
+          className="inline-flex items-center flex-shrink-0 rounded-md bg-background-tint-02 px-2 py-0.5 whitespace-nowrap"
+        >
+          <Text as="span" secondaryBody text03>
+            {g.name}
+          </Text>
+        </span>
+      ))}
+      {overflow > 0 && (
+        <Text as="span" secondaryBody text03>
+          +{overflow}
+        </Text>
+      )}
+    </div>
+  );
+}
+
+function renderRoleColumn(role: UserRole) {
+  const Icon = ROLE_ICONS[role];
+  return (
+    <div className="flex items-center gap-1.5">
+      {Icon && <Icon size={14} className="text-text-03 shrink-0" />}
+      <Text as="span" mainUiBody text03>
+        {USER_ROLE_LABELS[role] ?? role}
+      </Text>
+    </div>
+  );
+}
+
+function renderStatusColumn(isActive: boolean, row: UserRow) {
+  return (
+    <div className="flex flex-col">
+      <Text as="span" mainUiBody text03>
+        {isActive ? "Active" : "Inactive"}
+      </Text>
+      {row.is_scim_synced && (
+        <Text as="span" secondaryBody text03>
+          SCIM synced
+        </Text>
+      )}
+    </div>
+  );
+}
+
+function renderLastUpdatedColumn(value: string) {
+  return (
+    <Text as="span" secondaryBody text03>
+      {timeAgo(value) ?? "\u2014"}
+    </Text>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Columns (stable reference — defined at module scope)
+// ---------------------------------------------------------------------------
+
+const tc = createTableColumns<UserRow>();
+
+const columns = [
+  tc.qualifier({
+    content: "avatar-user",
+    getInitials: (row) => getInitials(row.personal_name, row.email),
+    selectable: false,
+  }),
+  tc.column("email", {
+    header: "Name",
+    weight: 22,
+    minWidth: 140,
+    cell: renderNameColumn,
+  }),
+  tc.column("groups", {
+    header: "Groups",
+    weight: 24,
+    minWidth: 200,
+    cell: renderGroupsColumn,
+  }),
+  tc.column("role", {
+    header: "Account Type",
+    weight: 16,
+    minWidth: 180,
+    cell: renderRoleColumn,
+  }),
+  tc.column("is_active", {
+    header: "Status",
+    weight: 15,
+    minWidth: 100,
+    cell: renderStatusColumn,
+  }),
+  tc.column("updated_at", {
+    header: "Last Updated",
+    weight: 14,
+    minWidth: 100,
+    cell: renderLastUpdatedColumn,
+  }),
+  tc.actions(),
+];
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function UsersTable() {
+  const [searchTerm, setSearchTerm] = useState("");
+  const { users, isLoading, error } = useAdminUsers();
+
+  if (isLoading) {
+    return <ThreeDotsLoader />;
+  }
+
+  if (error) {
+    return (
+      <Text as="p" secondaryBody text03>
+        Failed to load users. Please try refreshing the page.
+      </Text>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-3">
+      <InputTypeIn
+        value={searchTerm}
+        onChange={(e) => setSearchTerm(e.target.value)}
+        placeholder="Search users..."
+        leftSearchIcon
+      />
+      <DataTable
+        data={users}
+        columns={columns}
+        getRowId={(row) => row.id}
+        pageSize={PAGE_SIZE}
+        searchTerm={searchTerm}
+        footer={{ mode: "summary" }}
+      />
+    </div>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/interfaces.ts b/web/src/refresh-pages/admin/UsersPage/interfaces.ts
new file mode 100644
index 00000000000..caf0a980fbe
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/interfaces.ts
@@ -0,0 +1,20 @@
+import type { UserRole } from "@/lib/types";
+
+export interface UserGroupInfo {
+  id: number;
+  name: string;
+}
+
+export interface UserRow {
+  id: string;
+  email: string;
+  role: UserRole;
+  is_active: boolean;
+  is_scim_synced: boolean;
+  personal_name: string | null;
+  created_at: string;
+  updated_at: string;
+  groups: UserGroupInfo[];
+}
+
+export type StatusFilter = "all" | "active" | "inactive";
diff --git a/web/src/refresh-pages/admin/UsersPage/utils.test.ts b/web/src/refresh-pages/admin/UsersPage/utils.test.ts
new file mode 100644
index 00000000000..6ae81a321cd
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/utils.test.ts
@@ -0,0 +1,43 @@
+import { getInitials } from "./utils";
+
+describe("getInitials", () => {
+  it("returns first letters of first two name parts", () => {
+    expect(getInitials("Alice Smith", "alice@example.com")).toBe("AS");
+  });
+
+  it("returns first two chars of a single-word name", () => {
+    expect(getInitials("Alice", "alice@example.com")).toBe("AL");
+  });
+
+  it("handles three-word names (uses first two)", () => {
+    expect(getInitials("Alice B. Smith", "alice@example.com")).toBe("AB");
+  });
+
+  it("falls back to email local part with dot separator", () => {
+    expect(getInitials(null, "alice.smith@example.com")).toBe("AS");
+  });
+
+  it("falls back to email local part with underscore separator", () => {
+    expect(getInitials(null, "alice_smith@example.com")).toBe("AS");
+  });
+
+  it("falls back to email local part with hyphen separator", () => {
+    expect(getInitials(null, "alice-smith@example.com")).toBe("AS");
+  });
+
+  it("uses first two chars of email local if no separator", () => {
+    expect(getInitials(null, "alice@example.com")).toBe("AL");
+  });
+
+  it("returns ? for empty email local part", () => {
+    expect(getInitials(null, "@example.com")).toBe("?");
+  });
+
+  it("uppercases the result", () => {
+    expect(getInitials("john doe", "jd@test.com")).toBe("JD");
+  });
+
+  it("trims whitespace from name", () => {
+    expect(getInitials("  Alice Smith  ", "a@test.com")).toBe("AS");
+  });
+});
diff --git a/web/src/refresh-pages/admin/UsersPage/utils.ts b/web/src/refresh-pages/admin/UsersPage/utils.ts
new file mode 100644
index 00000000000..b8f1b0bcef8
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/utils.ts
@@ -0,0 +1,23 @@
+/**
+ * Derive display initials from a user's name or email.
+ *
+ * - If a name is provided, uses the first letter of the first two words.
+ * - Falls back to the email local part, splitting on `.`, `_`, or `-`.
+ * - Returns at most 2 uppercase characters.
+ */
+export function getInitials(name: string | null, email: string): string {
+  if (name) {
+    const parts = name.trim().split(/\s+/);
+    if (parts.length >= 2) {
+      return ((parts[0]?.[0] ?? "") + (parts[1]?.[0] ?? "")).toUpperCase();
+    }
+    return name.slice(0, 2).toUpperCase();
+  }
+  const local = email.split("@")[0];
+  if (!local) return "?";
+  const parts = local.split(/[._-]/);
+  if (parts.length >= 2) {
+    return ((parts[0]?.[0] ?? "") + (parts[1]?.[0] ?? "")).toUpperCase();
+  }
+  return local.slice(0, 2).toUpperCase();
+}

From b5474dc1273d3fa6efdec48d9481f3367a4af444 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Wed, 11 Mar 2026 20:30:55 -0700
Subject: [PATCH 246/267] chore(devtools): upgrade `ods`: 0.6.3->0.7.0 (#9297)

---
 backend/requirements/dev.txt |  2 +-
 pyproject.toml               |  2 +-
 uv.lock                      | 17 ++++++++---------
 3 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/backend/requirements/dev.txt b/backend/requirements/dev.txt
index e3be56f5c51..b3320e46e47 100644
--- a/backend/requirements/dev.txt
+++ b/backend/requirements/dev.txt
@@ -263,7 +263,7 @@ oauthlib==3.2.2
     # via
     #   kubernetes
     #   requests-oauthlib
-onyx-devtools==0.6.3
+onyx-devtools==0.7.0
     # via onyx
 openai==2.14.0
     # via
diff --git a/pyproject.toml b/pyproject.toml
index 6da1c79bb3a..6aea879fd74 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -143,7 +143,7 @@ dev = [
     "matplotlib==3.10.8",
     "mypy-extensions==1.0.0",
     "mypy==1.13.0",
-    "onyx-devtools==0.6.3",
+    "onyx-devtools==0.7.0",
     "openapi-generator-cli==7.17.0",
     "pandas-stubs~=2.3.3",
     "pre-commit==3.2.2",
diff --git a/uv.lock b/uv.lock
index b7698a27a5c..76f5603dc3c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4443,7 +4443,7 @@ requires-dist = [
     { name = "numpy", marker = "extra == 'model-server'", specifier = "==2.4.1" },
     { name = "oauthlib", marker = "extra == 'backend'", specifier = "==3.2.2" },
     { name = "office365-rest-python-client", marker = "extra == 'backend'", specifier = "==2.6.2" },
-    { name = "onyx-devtools", marker = "extra == 'dev'", specifier = "==0.6.3" },
+    { name = "onyx-devtools", marker = "extra == 'dev'", specifier = "==0.7.0" },
     { name = "openai", specifier = "==2.14.0" },
     { name = "openapi-generator-cli", marker = "extra == 'dev'", specifier = "==7.17.0" },
     { name = "openinference-instrumentation", marker = "extra == 'backend'", specifier = "==0.1.42" },
@@ -4548,20 +4548,19 @@ requires-dist = [{ name = "onyx", extras = ["backend", "dev", "ee"], editable =
 
 [[package]]
 name = "onyx-devtools"
-version = "0.6.3"
+version = "0.7.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "fastapi" },
     { name = "openapi-generator-cli" },
 ]
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/84/e2/e7619722c3ccd18eb38100f776fb3dd6b4ae0fbbee09fca5af7c69a279b5/onyx_devtools-0.6.3-py3-none-any.whl", hash = "sha256:d3a5422945d9da12cafc185f64b39f6e727ee4cc92b37427deb7a38f9aad4966", size = 3945381, upload-time = "2026-03-05T20:39:25.896Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/09/513d2dabedc1e54ad4376830fc9b34a3d9c164bdbcdedfcdbb8b8154dc5a/onyx_devtools-0.6.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:efe300e9f3a2e7ae75f88a4f9e0a5c4c471478296cb1615b6a1f03d247582e13", size = 3978761, upload-time = "2026-03-05T20:39:28.822Z" },
-    { url = "https://files.pythonhosted.org/packages/39/41/e757602a0de032d74ed01c7ee57f30e57728fb9cd4f922f50d2affda3889/onyx_devtools-0.6.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:594066eed3f917cfab5a8c7eac3d4a210df30259f2049f664787749709345e19", size = 3665378, upload-time = "2026-03-05T20:44:22.696Z" },
-    { url = "https://files.pythonhosted.org/packages/33/1c/c93b65d0b32e202596a2647922a75c7011cb982f899ddfcfd171f792c58f/onyx_devtools-0.6.3-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:384ef66030b55c0fd68b3898782b5b4b868ff3de119569dfc8544e2ce534b98a", size = 3540890, upload-time = "2026-03-05T20:39:28.886Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/33/760eb656013f7f0cdff24570480d3dc4e52bbd8e6147ea1e8cf6fad7554f/onyx_devtools-0.6.3-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:82e218f3a49f64910c2c4c34d5dc12d1ea1520a27e0b0f6e4c0949ff9abaf0e1", size = 3945396, upload-time = "2026-03-05T20:39:34.323Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/eb/f54b3675c464df8a51194ff75afc97c2417659e3a209dc46948b47c28860/onyx_devtools-0.6.3-py3-none-win_amd64.whl", hash = "sha256:8af614ae7229290ef2417cb85270184a1e826ed9a3a34658da93851edb36df57", size = 4045936, upload-time = "2026-03-05T20:39:28.375Z" },
-    { url = "https://files.pythonhosted.org/packages/04/b8/5bee38e748f3d4b8ec935766224db1bbc1214c91092e5822c080fccd9130/onyx_devtools-0.6.3-py3-none-win_arm64.whl", hash = "sha256:717589db4b42528d33ae96f8006ee6aad3555034dcfee724705b6576be6a6ec4", size = 3608268, upload-time = "2026-03-05T20:39:28.731Z" },
+    { url = "https://files.pythonhosted.org/packages/22/9e/6957b11555da57d9e97092f4cd8ac09a86666264b0c9491838f4b27db5dc/onyx_devtools-0.7.0-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ad962a168d46ea11dcde9fa3b37e4f12ec520b4a4cb4d49d8732de110d46c4b6", size = 3998057, upload-time = "2026-03-12T03:09:11.585Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/90/c72f3d06ba677012d77c77de36195b6a32a15c755c79ba0282be74e3c366/onyx_devtools-0.7.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:e46d252e2b048ff053b03519c3a875998780738d7c334eaa1c9a32ff445e3e1a", size = 3687753, upload-time = "2026-03-12T03:09:11.742Z" },
+    { url = "https://files.pythonhosted.org/packages/10/42/4e9fe36eccf9f76d67ba8f4ff6539196a09cd60351fb63f5865e1544cbfa/onyx_devtools-0.7.0-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:f280bc9320e1cc310e7d753a371009bfaab02cc0e0cfd78559663b15655b5a50", size = 3560144, upload-time = "2026-03-12T03:12:24.02Z" },
+    { url = "https://files.pythonhosted.org/packages/76/40/36dc12d99760b358c7f39b27361cb18fa9681ffe194107f982d0e1a74016/onyx_devtools-0.7.0-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:e31df751c7540ae7e70a7fe8e1153c79c31c2254af6aa4c72c0dd54fa381d2ab", size = 3964387, upload-time = "2026-03-12T03:09:11.356Z" },
+    { url = "https://files.pythonhosted.org/packages/34/18/74744230c3820a5a7687335507ca5f1dbebab2c5325805041c1cd5703e6a/onyx_devtools-0.7.0-py3-none-win_amd64.whl", hash = "sha256:541bfd347c2d5b11e7f63ab5001d2594df91d215ad9d07b1562f5e715700f7e6", size = 4068030, upload-time = "2026-03-12T03:09:12.98Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/78/1320436607d3ffcb321ba7b064556c020ea15843a7e7d903fbb7529a71f5/onyx_devtools-0.7.0-py3-none-win_arm64.whl", hash = "sha256:83016330a9d39712431916cc25b2fb2cfcaa0112a55cc4f919d545da3a8974f9", size = 3626409, upload-time = "2026-03-12T03:09:10.222Z" },
 ]
 
 [[package]]

From c1ce180b72352cf7ade6cd97fa4efebe58120406 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 21:56:19 -0700
Subject: [PATCH 247/267] feat(admin): add role, group, and status filters to
 Users table - 4/9 (#9179)

---
 backend/onyx/db/users.py                      |  36 +++
 backend/onyx/server/manage/users.py           |   9 +
 web/src/hooks/useAdminUsers.ts                | 119 ++++++-
 web/src/hooks/useUserCounts.ts                |  32 +-
 web/src/lib/types.ts                          |  14 +
 web/src/refresh-pages/admin/UsersPage.tsx     |  26 +-
 .../admin/UsersPage/UserFilters.tsx           | 296 ++++++++++++++++++
 .../admin/UsersPage/UsersSummary.tsx          |  78 ++++-
 .../admin/UsersPage/UsersTable.tsx            | 142 +++++++--
 .../admin/UsersPage/interfaces.ts             |  28 +-
 10 files changed, 718 insertions(+), 62 deletions(-)
 create mode 100644 web/src/refresh-pages/admin/UsersPage/UserFilters.tsx

diff --git a/backend/onyx/db/users.py b/backend/onyx/db/users.py
index b27210f410a..1c69a19523c 100644
--- a/backend/onyx/db/users.py
+++ b/backend/onyx/db/users.py
@@ -4,6 +4,7 @@
 
 from fastapi import HTTPException
 from fastapi_users.password import PasswordHelper
+from sqlalchemy import case
 from sqlalchemy import func
 from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
@@ -241,6 +242,41 @@ def get_total_filtered_users_count(
     return db_session.scalar(total_count_stmt) or 0
 
 
+def get_user_counts_by_role_and_status(
+    db_session: Session,
+) -> dict[str, dict[str, int]]:
+    """Returns user counts grouped by role and by active/inactive status.
+
+    Excludes API key users, anonymous users, and no-auth placeholder users.
+    Uses a single query with conditional aggregation.
+    """
+    base_where = _get_accepted_user_where_clause()
+    role_col = User.__table__.c.role
+    is_active_col = User.__table__.c.is_active
+
+    stmt = (
+        select(
+            role_col,
+            func.count().label("total"),
+            func.sum(case((is_active_col.is_(True), 1), else_=0)).label("active"),
+            func.sum(case((is_active_col.is_(False), 1), else_=0)).label("inactive"),
+        )
+        .where(*base_where)
+        .group_by(role_col)
+    )
+
+    role_counts: dict[str, int] = {}
+    status_counts: dict[str, int] = {"active": 0, "inactive": 0}
+
+    for role_val, total, active, inactive in db_session.execute(stmt).all():
+        key = role_val.value if hasattr(role_val, "value") else str(role_val)
+        role_counts[key] = total
+        status_counts["active"] += active or 0
+        status_counts["inactive"] += inactive or 0
+
+    return {"role_counts": role_counts, "status_counts": status_counts}
+
+
 def get_user_by_email(email: str, db_session: Session) -> User | None:
     user = (
         db_session.query(User)
diff --git a/backend/onyx/server/manage/users.py b/backend/onyx/server/manage/users.py
index 8a5ba3f2047..fb9d941c61b 100644
--- a/backend/onyx/server/manage/users.py
+++ b/backend/onyx/server/manage/users.py
@@ -76,6 +76,7 @@
 from onyx.db.users import get_page_of_filtered_users
 from onyx.db.users import get_total_filtered_users_count
 from onyx.db.users import get_user_by_email
+from onyx.db.users import get_user_counts_by_role_and_status
 from onyx.db.users import validate_user_role_update
 from onyx.key_value_store.factory import get_kv_store
 from onyx.redis.redis_pool import get_raw_redis_client
@@ -285,6 +286,14 @@ def list_all_accepted_users(
     ]
 
 
+@router.get("/manage/users/counts")
+def get_user_counts(
+    _: User = Depends(current_admin_user),
+    db_session: Session = Depends(get_session),
+) -> dict[str, dict[str, int]]:
+    return get_user_counts_by_role_and_status(db_session)
+
+
 @router.get("/manage/users/invited", tags=PUBLIC_API_TAGS)
 def list_invited_users(
     _: User = Depends(current_admin_user),
diff --git a/web/src/hooks/useAdminUsers.ts b/web/src/hooks/useAdminUsers.ts
index a65d9e5487a..c393a9b152b 100644
--- a/web/src/hooks/useAdminUsers.ts
+++ b/web/src/hooks/useAdminUsers.ts
@@ -2,18 +2,121 @@
 
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
-import type { UserRow } from "@/refresh-pages/admin/UsersPage/interfaces";
+import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
+import { UserStatus } from "@/lib/types";
+import type { UserRole, InvitedUserSnapshot } from "@/lib/types";
+import type {
+  UserRow,
+  UserGroupInfo,
+} from "@/refresh-pages/admin/UsersPage/interfaces";
+
+// ---------------------------------------------------------------------------
+// Backend response shape (GET /manage/users/accepted/all)
+// ---------------------------------------------------------------------------
+
+interface FullUserSnapshot {
+  id: string;
+  email: string;
+  role: UserRole;
+  is_active: boolean;
+  password_configured: boolean;
+  personal_name: string | null;
+  created_at: string;
+  updated_at: string;
+  groups: UserGroupInfo[];
+  is_scim_synced: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+
+function toUserRow(snapshot: FullUserSnapshot): UserRow {
+  return {
+    id: snapshot.id,
+    email: snapshot.email,
+    role: snapshot.role,
+    status: snapshot.is_active ? UserStatus.ACTIVE : UserStatus.INACTIVE,
+    is_active: snapshot.is_active,
+    is_scim_synced: snapshot.is_scim_synced,
+    personal_name: snapshot.personal_name,
+    created_at: snapshot.created_at,
+    updated_at: snapshot.updated_at,
+    groups: snapshot.groups,
+  };
+}
+
+function emailToUserRow(
+  email: string,
+  status: UserStatus.INVITED | UserStatus.REQUESTED
+): UserRow {
+  return {
+    id: null,
+    email,
+    role: null,
+    status,
+    is_active: false,
+    is_scim_synced: false,
+    personal_name: null,
+    created_at: null,
+    updated_at: null,
+    groups: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
 
 export default function useAdminUsers() {
-  const { data, isLoading, error, mutate } = useSWR<UserRow[]>(
+  const {
+    data: acceptedData,
+    isLoading: acceptedLoading,
+    error: acceptedError,
+    mutate: acceptedMutate,
+  } = useSWR<FullUserSnapshot[]>(
     "/api/manage/users/accepted/all",
     errorHandlingFetcher
   );
 
-  return {
-    users: data ?? [],
-    isLoading,
-    error,
-    refresh: mutate,
-  };
+  const {
+    data: invitedData,
+    isLoading: invitedLoading,
+    error: invitedError,
+    mutate: invitedMutate,
+  } = useSWR<InvitedUserSnapshot[]>(
+    "/api/manage/users/invited",
+    errorHandlingFetcher
+  );
+
+  const {
+    data: requestedData,
+    isLoading: requestedLoading,
+    error: requestedError,
+    mutate: requestedMutate,
+  } = useSWR<InvitedUserSnapshot[]>(
+    NEXT_PUBLIC_CLOUD_ENABLED ? "/api/tenants/users/pending" : null,
+    errorHandlingFetcher
+  );
+
+  const acceptedRows = (acceptedData ?? []).map(toUserRow);
+  const invitedRows = (invitedData ?? []).map((u) =>
+    emailToUserRow(u.email, UserStatus.INVITED)
+  );
+  const requestedRows = (requestedData ?? []).map((u) =>
+    emailToUserRow(u.email, UserStatus.REQUESTED)
+  );
+
+  const users = [...invitedRows, ...requestedRows, ...acceptedRows];
+
+  const isLoading = acceptedLoading || invitedLoading || requestedLoading;
+  const error = acceptedError ?? invitedError ?? requestedError;
+
+  function refresh() {
+    acceptedMutate();
+    invitedMutate();
+    requestedMutate();
+  }
+
+  return { users, isLoading, error, refresh };
 }
diff --git a/web/src/hooks/useUserCounts.ts b/web/src/hooks/useUserCounts.ts
index 3cf6fc5a41d..5ea3ca339e5 100644
--- a/web/src/hooks/useUserCounts.ts
+++ b/web/src/hooks/useUserCounts.ts
@@ -4,23 +4,28 @@ import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import type { InvitedUserSnapshot } from "@/lib/types";
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
+import type { StatusCountMap } from "@/refresh-pages/admin/UsersPage/interfaces";
 
-type PaginatedCountResponse = {
-  total_items: number;
+type UserCountsResponse = {
+  role_counts: Record<string, number>;
+  status_counts: Record<string, number>;
 };
 
 type UserCounts = {
   activeCount: number | null;
   invitedCount: number | null;
   pendingCount: number | null;
+  roleCounts: Record<string, number>;
+  statusCounts: StatusCountMap;
+  refreshCounts: () => void;
 };
 
 export default function useUserCounts(): UserCounts {
-  // Active user count — lightweight fetch (page_size=1 to minimize payload)
-  const { data: activeData } = useSWR<PaginatedCountResponse>(
-    "/api/manage/users/accepted?page_num=0&page_size=1",
-    errorHandlingFetcher
-  );
+  const { data: countsData, mutate: refreshCounts } =
+    useSWR<UserCountsResponse>(
+      "/api/manage/users/counts",
+      errorHandlingFetcher
+    );
 
   const { data: invitedUsers } = useSWR<InvitedUserSnapshot[]>(
     "/api/manage/users/invited",
@@ -32,9 +37,20 @@ export default function useUserCounts(): UserCounts {
     errorHandlingFetcher
   );
 
+  const activeCount = countsData?.status_counts?.active ?? null;
+  const inactiveCount = countsData?.status_counts?.inactive ?? null;
+
   return {
-    activeCount: activeData?.total_items ?? null,
+    activeCount,
     invitedCount: invitedUsers?.length ?? null,
     pendingCount: pendingUsers?.length ?? null,
+    roleCounts: countsData?.role_counts ?? {},
+    statusCounts: {
+      ...(activeCount !== null ? { active: activeCount } : {}),
+      ...(inactiveCount !== null ? { inactive: inactiveCount } : {}),
+      ...(invitedUsers ? { invited: invitedUsers.length } : {}),
+      ...(pendingUsers ? { requested: pendingUsers.length } : {}),
+    } satisfies StatusCountMap,
+    refreshCounts,
   };
 }
diff --git a/web/src/lib/types.ts b/web/src/lib/types.ts
index 1d39aabdf5f..286315c3830 100644
--- a/web/src/lib/types.ts
+++ b/web/src/lib/types.ts
@@ -68,6 +68,20 @@ export const USER_ROLE_LABELS: Record<UserRole, string> = {
   [UserRole.SLACK_USER]: "Slack User",
 };
 
+export enum UserStatus {
+  ACTIVE = "active",
+  INACTIVE = "inactive",
+  INVITED = "invited",
+  REQUESTED = "requested",
+}
+
+export const USER_STATUS_LABELS: Record<UserStatus, string> = {
+  [UserStatus.ACTIVE]: "Active",
+  [UserStatus.INACTIVE]: "Inactive",
+  [UserStatus.INVITED]: "Invite Pending",
+  [UserStatus.REQUESTED]: "Requested",
+};
+
 export const INVALID_ROLE_HOVER_TEXT: Partial<Record<UserRole, string>> = {
   [UserRole.BASIC]: "Basic users can't perform any admin actions",
   [UserRole.ADMIN]: "Admin users can perform all admin actions",
diff --git a/web/src/refresh-pages/admin/UsersPage.tsx b/web/src/refresh-pages/admin/UsersPage.tsx
index 2e3931c846f..2d0b9f868f6 100644
--- a/web/src/refresh-pages/admin/UsersPage.tsx
+++ b/web/src/refresh-pages/admin/UsersPage.tsx
@@ -1,11 +1,14 @@
 "use client";
 
+import { useState } from "react";
 import { SvgUser, SvgUserPlus } from "@opal/icons";
 import { Button } from "@opal/components";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { useScimToken } from "@/hooks/useScimToken";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
 import useUserCounts from "@/hooks/useUserCounts";
+import { UserStatus } from "@/lib/types";
+import type { StatusFilter } from "./UsersPage/interfaces";
 
 import UsersSummary from "./UsersPage/UsersSummary";
 import UsersTable from "./UsersPage/UsersTable";
@@ -20,7 +23,18 @@ function UsersContent() {
   const { data: scimToken } = useScimToken();
   const showScim = isEe && !!scimToken;
 
-  const { activeCount, invitedCount, pendingCount } = useUserCounts();
+  const { activeCount, invitedCount, pendingCount, roleCounts, statusCounts } =
+    useUserCounts();
+
+  const [selectedStatuses, setSelectedStatuses] = useState<StatusFilter>([]);
+
+  const toggleStatus = (target: UserStatus) => {
+    setSelectedStatuses((prev) =>
+      prev.includes(target)
+        ? prev.filter((s) => s !== target)
+        : [...prev, target]
+    );
+  };
 
   return (
     <>
@@ -29,9 +43,17 @@ function UsersContent() {
         pendingInvites={invitedCount}
         requests={pendingCount}
         showScim={showScim}
+        onFilterActive={() => toggleStatus(UserStatus.ACTIVE)}
+        onFilterInvites={() => toggleStatus(UserStatus.INVITED)}
+        onFilterRequests={() => toggleStatus(UserStatus.REQUESTED)}
       />
 
-      <UsersTable />
+      <UsersTable
+        selectedStatuses={selectedStatuses}
+        onStatusesChange={setSelectedStatuses}
+        roleCounts={roleCounts}
+        statusCounts={statusCounts}
+      />
     </>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx b/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx
new file mode 100644
index 00000000000..e7b395060c8
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx
@@ -0,0 +1,296 @@
+"use client";
+
+import { useState } from "react";
+import { SvgCheck, SvgSlack, SvgUser, SvgUsers } from "@opal/icons";
+import type { IconFunctionComponent } from "@opal/types";
+import FilterButton from "@/refresh-components/buttons/FilterButton";
+import Popover from "@/refresh-components/Popover";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import LineItem from "@/refresh-components/buttons/LineItem";
+import Text from "@/refresh-components/texts/Text";
+import Separator from "@/refresh-components/Separator";
+import {
+  UserRole,
+  UserStatus,
+  USER_ROLE_LABELS,
+  USER_STATUS_LABELS,
+} from "@/lib/types";
+import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
+import type { GroupOption, StatusFilter, StatusCountMap } from "./interfaces";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface UserFiltersProps {
+  selectedRoles: UserRole[];
+  onRolesChange: (roles: UserRole[]) => void;
+  selectedGroups: number[];
+  onGroupsChange: (groupIds: number[]) => void;
+  groups: GroupOption[];
+  selectedStatuses: StatusFilter;
+  onStatusesChange: (statuses: StatusFilter) => void;
+  roleCounts: Record<string, number>;
+  statusCounts: StatusCountMap;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const FILTERABLE_ROLES = Object.entries(USER_ROLE_LABELS).filter(
+  ([role]) => role !== UserRole.EXT_PERM_USER
+) as [UserRole, string][];
+
+const FILTERABLE_STATUSES = (
+  Object.entries(USER_STATUS_LABELS) as [UserStatus, string][]
+).filter(
+  ([value]) => value !== UserStatus.REQUESTED || NEXT_PUBLIC_CLOUD_ENABLED
+);
+
+const ROLE_ICONS: Partial<Record<UserRole, IconFunctionComponent>> = {
+  [UserRole.SLACK_USER]: SvgSlack,
+};
+
+/** Map UserStatus enum values to the keys returned by the counts endpoint. */
+const STATUS_COUNT_KEY: Record<UserStatus, keyof StatusCountMap> = {
+  [UserStatus.ACTIVE]: "active",
+  [UserStatus.INACTIVE]: "inactive",
+  [UserStatus.INVITED]: "invited",
+  [UserStatus.REQUESTED]: "requested",
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function CountBadge({ count }: { count: number | undefined }) {
+  return (
+    <Text as="span" secondaryBody text03>
+      {count ?? 0}
+    </Text>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function UserFilters({
+  selectedRoles,
+  onRolesChange,
+  selectedGroups,
+  onGroupsChange,
+  groups,
+  selectedStatuses,
+  onStatusesChange,
+  roleCounts,
+  statusCounts,
+}: UserFiltersProps) {
+  const hasRoleFilter = selectedRoles.length > 0;
+  const hasGroupFilter = selectedGroups.length > 0;
+  const hasStatusFilter = selectedStatuses.length > 0;
+  const [groupSearch, setGroupSearch] = useState("");
+  const [groupPopoverOpen, setGroupPopoverOpen] = useState(false);
+
+  const toggleRole = (role: UserRole) => {
+    if (selectedRoles.includes(role)) {
+      onRolesChange(selectedRoles.filter((r) => r !== role));
+    } else {
+      onRolesChange([...selectedRoles, role]);
+    }
+  };
+
+  const roleLabel = hasRoleFilter
+    ? FILTERABLE_ROLES.filter(([role]) => selectedRoles.includes(role))
+        .map(([, label]) => label)
+        .slice(0, 2)
+        .join(", ") +
+      (selectedRoles.length > 2 ? `, +${selectedRoles.length - 2}` : "")
+    : "All Account Types";
+
+  const toggleGroup = (groupId: number) => {
+    if (selectedGroups.includes(groupId)) {
+      onGroupsChange(selectedGroups.filter((id) => id !== groupId));
+    } else {
+      onGroupsChange([...selectedGroups, groupId]);
+    }
+  };
+
+  const groupLabel = hasGroupFilter
+    ? groups
+        .filter((g) => selectedGroups.includes(g.id))
+        .map((g) => g.name)
+        .slice(0, 2)
+        .join(", ") +
+      (selectedGroups.length > 2 ? `, +${selectedGroups.length - 2}` : "")
+    : "All Groups";
+
+  const toggleStatus = (status: UserStatus) => {
+    if (selectedStatuses.includes(status)) {
+      onStatusesChange(selectedStatuses.filter((s) => s !== status));
+    } else {
+      onStatusesChange([...selectedStatuses, status]);
+    }
+  };
+
+  const statusLabel = hasStatusFilter
+    ? FILTERABLE_STATUSES.filter(([status]) =>
+        selectedStatuses.includes(status)
+      )
+        .map(([, label]) => label)
+        .slice(0, 2)
+        .join(", ") +
+      (selectedStatuses.length > 2 ? `, +${selectedStatuses.length - 2}` : "")
+    : "All Status";
+
+  const filteredGroups = groupSearch
+    ? groups.filter((g) =>
+        g.name.toLowerCase().includes(groupSearch.toLowerCase())
+      )
+    : groups;
+
+  return (
+    <div className="flex gap-2">
+      {/* Role filter */}
+      <Popover>
+        <Popover.Trigger asChild>
+          <FilterButton
+            leftIcon={SvgUsers}
+            active={hasRoleFilter}
+            onClear={() => onRolesChange([])}
+          >
+            {roleLabel}
+          </FilterButton>
+        </Popover.Trigger>
+        <Popover.Content align="start">
+          <div className="flex flex-col gap-1 p-1 min-w-[200px]">
+            <LineItem
+              icon={SvgUsers}
+              selected={!hasRoleFilter}
+              onClick={() => onRolesChange([])}
+            >
+              All Account Types
+            </LineItem>
+            <Separator noPadding />
+            {FILTERABLE_ROLES.map(([role, label]) => {
+              const isSelected = selectedRoles.includes(role);
+              const roleIcon = ROLE_ICONS[role] ?? SvgUser;
+              return (
+                <LineItem
+                  key={role}
+                  icon={isSelected ? SvgCheck : roleIcon}
+                  selected={isSelected}
+                  onClick={() => toggleRole(role)}
+                  rightChildren={<CountBadge count={roleCounts[role]} />}
+                >
+                  {label}
+                </LineItem>
+              );
+            })}
+          </div>
+        </Popover.Content>
+      </Popover>
+
+      {/* Groups filter */}
+      <Popover
+        open={groupPopoverOpen}
+        onOpenChange={(open) => {
+          setGroupPopoverOpen(open);
+          if (!open) setGroupSearch("");
+        }}
+      >
+        <Popover.Trigger asChild>
+          <FilterButton
+            leftIcon={SvgUsers}
+            active={hasGroupFilter}
+            onClear={() => onGroupsChange([])}
+          >
+            {groupLabel}
+          </FilterButton>
+        </Popover.Trigger>
+        <Popover.Content align="start">
+          <div className="flex flex-col gap-1 p-1 min-w-[200px]">
+            <div className="px-1 pt-1">
+              <InputTypeIn
+                value={groupSearch}
+                onChange={(e) => setGroupSearch(e.target.value)}
+                placeholder="Search groups..."
+                leftSearchIcon
+              />
+            </div>
+            <LineItem
+              icon={SvgUsers}
+              selected={!hasGroupFilter}
+              onClick={() => onGroupsChange([])}
+            >
+              All Groups
+            </LineItem>
+            <Separator noPadding />
+            <div className="flex flex-col gap-1 max-h-[240px] overflow-y-auto">
+              {filteredGroups.map((group) => {
+                const isSelected = selectedGroups.includes(group.id);
+                return (
+                  <LineItem
+                    key={group.id}
+                    icon={isSelected ? SvgCheck : undefined}
+                    selected={isSelected}
+                    onClick={() => toggleGroup(group.id)}
+                    rightChildren={<CountBadge count={group.memberCount} />}
+                  >
+                    {group.name}
+                  </LineItem>
+                );
+              })}
+              {filteredGroups.length === 0 && (
+                <Text as="span" secondaryBody text03 className="px-2 py-1.5">
+                  No groups found
+                </Text>
+              )}
+            </div>
+          </div>
+        </Popover.Content>
+      </Popover>
+
+      {/* Status filter */}
+      <Popover>
+        <Popover.Trigger asChild>
+          <FilterButton
+            leftIcon={SvgUsers}
+            active={hasStatusFilter}
+            onClear={() => onStatusesChange([])}
+          >
+            {statusLabel}
+          </FilterButton>
+        </Popover.Trigger>
+        <Popover.Content align="start">
+          <div className="flex flex-col gap-1 p-1 min-w-[200px]">
+            <LineItem
+              icon={!hasStatusFilter ? SvgCheck : undefined}
+              selected={!hasStatusFilter}
+              onClick={() => onStatusesChange([])}
+            >
+              All Status
+            </LineItem>
+            <Separator noPadding />
+            {FILTERABLE_STATUSES.map(([status, label]) => {
+              const isSelected = selectedStatuses.includes(status);
+              const countKey = STATUS_COUNT_KEY[status];
+              return (
+                <LineItem
+                  key={status}
+                  icon={isSelected ? SvgCheck : undefined}
+                  selected={isSelected}
+                  onClick={() => toggleStatus(status)}
+                  rightChildren={<CountBadge count={statusCounts[countKey]} />}
+                >
+                  {label}
+                </LineItem>
+              );
+            })}
+          </div>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx b/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
index afe6ffd98a6..54d49265058 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
@@ -1,4 +1,4 @@
-import { SvgArrowUpRight, SvgUserSync } from "@opal/icons";
+import { SvgArrowUpRight, SvgFilter, SvgUserSync } from "@opal/icons";
 import { ContentAction } from "@opal/layouts";
 import { Button } from "@opal/components";
 import { Section } from "@/layouts/general-layouts";
@@ -14,19 +14,33 @@ import { ADMIN_PATHS } from "@/lib/admin-routes";
 type StatCellProps = {
   value: number | null;
   label: string;
+  onFilter?: () => void;
 };
 
-function StatCell({ value, label }: StatCellProps) {
+function StatCell({ value, label, onFilter }: StatCellProps) {
   const display = value === null ? "\u2014" : value.toLocaleString();
 
   return (
-    <div className="flex flex-col items-start gap-0.5 w-full p-2">
+    <div
+      className={`group/stat relative flex flex-col items-start gap-0.5 w-full p-2 rounded-08 transition-colors ${
+        onFilter ? "cursor-pointer hover:bg-background-tint-02" : ""
+      }`}
+      onClick={onFilter}
+    >
       <Text as="span" mainUiAction text04>
         {display}
       </Text>
       <Text as="span" secondaryBody text03>
         {label}
       </Text>
+      {onFilter && (
+        <div className="absolute right-2 top-2 flex items-center gap-1 opacity-0 group-hover/stat:opacity-100 transition-opacity">
+          <Text as="span" secondaryBody text03>
+            Filter
+          </Text>
+          <SvgFilter size={16} className="text-text-03" />
+        </div>
+      )}
     </div>
   );
 }
@@ -66,6 +80,9 @@ type UsersSummaryProps = {
   pendingInvites: number | null;
   requests: number | null;
   showScim: boolean;
+  onFilterActive?: () => void;
+  onFilterInvites?: () => void;
+  onFilterRequests?: () => void;
 };
 
 export default function UsersSummary({
@@ -73,9 +90,36 @@ export default function UsersSummary({
   pendingInvites,
   requests,
   showScim,
+  onFilterActive,
+  onFilterInvites,
+  onFilterRequests,
 }: UsersSummaryProps) {
   const showRequests = requests !== null && requests > 0;
 
+  const statsCard = (
+    <Card padding={0.5}>
+      <Section flexDirection="row" gap={0}>
+        <StatCell
+          value={activeUsers}
+          label="active users"
+          onFilter={onFilterActive}
+        />
+        <StatCell
+          value={pendingInvites}
+          label="pending invites"
+          onFilter={onFilterInvites}
+        />
+        {showRequests && (
+          <StatCell
+            value={requests}
+            label="requests to join"
+            onFilter={onFilterRequests}
+          />
+        )}
+      </Section>
+    </Card>
+  );
+
   if (showScim) {
     return (
       <Section
@@ -84,15 +128,7 @@ export default function UsersSummary({
         alignItems="stretch"
         gap={0.5}
       >
-        <Card padding={0.5}>
-          <Section flexDirection="row" gap={0}>
-            <StatCell value={activeUsers} label="active users" />
-            <StatCell value={pendingInvites} label="pending invites" />
-            {showRequests && (
-              <StatCell value={requests} label="requests to join" />
-            )}
-          </Section>
-        </Card>
+        {statsCard}
         <ScimCard />
       </Section>
     );
@@ -102,14 +138,26 @@ export default function UsersSummary({
   return (
     <Section flexDirection="row" gap={0.5}>
       <Card padding={0.5}>
-        <StatCell value={activeUsers} label="active users" />
+        <StatCell
+          value={activeUsers}
+          label="active users"
+          onFilter={onFilterActive}
+        />
       </Card>
       <Card padding={0.5}>
-        <StatCell value={pendingInvites} label="pending invites" />
+        <StatCell
+          value={pendingInvites}
+          label="pending invites"
+          onFilter={onFilterInvites}
+        />
       </Card>
       {showRequests && (
         <Card padding={0.5}>
-          <StatCell value={requests} label="requests to join" />
+          <StatCell
+            value={requests}
+            label="requests to join"
+            onFilter={onFilterRequests}
+          />
         </Card>
       )}
     </Section>
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
index ec07269504e..d355424d5ae 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
@@ -1,26 +1,39 @@
 "use client";
 
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import DataTable from "@/refresh-components/table/DataTable";
 import { createTableColumns } from "@/refresh-components/table/columns";
 import { Content } from "@opal/layouts";
-import { USER_ROLE_LABELS, UserRole } from "@/lib/types";
+import { SvgUser, SvgUsers, SvgSlack } from "@opal/icons";
+import SvgNoResult from "@opal/illustrations/no-result";
+import { IllustrationContent } from "@opal/layouts";
+import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
+import type { IconFunctionComponent } from "@opal/types";
+import {
+  UserRole,
+  UserStatus,
+  USER_ROLE_LABELS,
+  USER_STATUS_LABELS,
+} from "@/lib/types";
 import { timeAgo } from "@/lib/time";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useAdminUsers from "@/hooks/useAdminUsers";
-import { ThreeDotsLoader } from "@/components/Loading";
-import { SvgUser, SvgUsers, SvgSlack } from "@opal/icons";
-import type { IconFunctionComponent } from "@opal/types";
-import type { UserRow, UserGroupInfo } from "./interfaces";
+import useGroups from "@/hooks/useGroups";
+import UserFilters from "./UserFilters";
+import type {
+  UserRow,
+  UserGroupInfo,
+  GroupOption,
+  StatusFilter,
+  StatusCountMap,
+} from "./interfaces";
 import { getInitials } from "./utils";
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const PAGE_SIZE = 8;
-
 const ROLE_ICONS: Record<UserRole, IconFunctionComponent> = {
   [UserRole.BASIC]: SvgUser,
   [UserRole.ADMIN]: SvgUser,
@@ -77,7 +90,14 @@ function renderGroupsColumn(groups: UserGroupInfo[]) {
   );
 }
 
-function renderRoleColumn(role: UserRole) {
+function renderRoleColumn(role: UserRole | null) {
+  if (!role) {
+    return (
+      <Text as="span" secondaryBody text03>
+        —
+      </Text>
+    );
+  }
   const Icon = ROLE_ICONS[role];
   return (
     <div className="flex items-center gap-1.5">
@@ -89,11 +109,11 @@ function renderRoleColumn(role: UserRole) {
   );
 }
 
-function renderStatusColumn(isActive: boolean, row: UserRow) {
+function renderStatusColumn(value: UserStatus, row: UserRow) {
   return (
     <div className="flex flex-col">
       <Text as="span" mainUiBody text03>
-        {isActive ? "Active" : "Inactive"}
+        {USER_STATUS_LABELS[value] ?? value}
       </Text>
       {row.is_scim_synced && (
         <Text as="span" secondaryBody text03>
@@ -104,7 +124,7 @@ function renderStatusColumn(isActive: boolean, row: UserRow) {
   );
 }
 
-function renderLastUpdatedColumn(value: string) {
+function renderLastUpdatedColumn(value: string | null) {
   return (
     <Text as="span" secondaryBody text03>
       {timeAgo(value) ?? "\u2014"}
@@ -134,6 +154,7 @@ const columns = [
     header: "Groups",
     weight: 24,
     minWidth: 200,
+    enableSorting: false,
     cell: renderGroupsColumn,
   }),
   tc.column("role", {
@@ -142,9 +163,9 @@ const columns = [
     minWidth: 180,
     cell: renderRoleColumn,
   }),
-  tc.column("is_active", {
+  tc.column("status", {
     header: "Status",
-    weight: 15,
+    weight: 14,
     minWidth: 100,
     cell: renderStatusColumn,
   }),
@@ -161,12 +182,68 @@ const columns = [
 // Component
 // ---------------------------------------------------------------------------
 
-export default function UsersTable() {
+const PAGE_SIZE = 8;
+
+interface UsersTableProps {
+  selectedStatuses: StatusFilter;
+  onStatusesChange: (statuses: StatusFilter) => void;
+  roleCounts: Record<string, number>;
+  statusCounts: StatusCountMap;
+}
+
+export default function UsersTable({
+  selectedStatuses,
+  onStatusesChange,
+  roleCounts,
+  statusCounts,
+}: UsersTableProps) {
   const [searchTerm, setSearchTerm] = useState("");
+  const [selectedRoles, setSelectedRoles] = useState<UserRole[]>([]);
+  const [selectedGroups, setSelectedGroups] = useState<number[]>([]);
+
+  const { data: allGroups } = useGroups();
+
+  const groupOptions: GroupOption[] = useMemo(
+    () =>
+      (allGroups ?? []).map((g) => ({
+        id: g.id,
+        name: g.name,
+        memberCount: g.users.length,
+      })),
+    [allGroups]
+  );
+
   const { users, isLoading, error } = useAdminUsers();
 
+  // Client-side filtering
+  const filteredUsers = useMemo(() => {
+    let result = users;
+
+    if (selectedRoles.length > 0) {
+      result = result.filter(
+        (u) => u.role !== null && selectedRoles.includes(u.role)
+      );
+    }
+
+    if (selectedStatuses.length > 0) {
+      result = result.filter((u) => selectedStatuses.includes(u.status));
+    }
+
+    if (selectedGroups.length > 0) {
+      result = result.filter((u) =>
+        u.groups.some((g) => selectedGroups.includes(g.id))
+      );
+    }
+
+    return result;
+  }, [users, selectedRoles, selectedStatuses, selectedGroups]);
+
   if (isLoading) {
-    return <ThreeDotsLoader />;
+    return (
+      <div className="flex justify-center py-12">
+        <SimpleLoader className="h-6 w-6" />
+      </div>
+    );
   }
 
   if (error) {
@@ -185,14 +262,33 @@ export default function UsersTable() {
         placeholder="Search users..."
         leftSearchIcon
       />
-      <DataTable
-        data={users}
-        columns={columns}
-        getRowId={(row) => row.id}
-        pageSize={PAGE_SIZE}
-        searchTerm={searchTerm}
-        footer={{ mode: "summary" }}
+      <UserFilters
+        selectedRoles={selectedRoles}
+        onRolesChange={setSelectedRoles}
+        selectedGroups={selectedGroups}
+        onGroupsChange={setSelectedGroups}
+        groups={groupOptions}
+        selectedStatuses={selectedStatuses}
+        onStatusesChange={onStatusesChange}
+        roleCounts={roleCounts}
+        statusCounts={statusCounts}
       />
+      {filteredUsers.length === 0 ? (
+        <IllustrationContent
+          illustration={SvgNoResult}
+          title="No users found"
+          description="No users match the current filters."
+        />
+      ) : (
+        <DataTable
+          data={filteredUsers}
+          columns={columns}
+          getRowId={(row) => row.id ?? row.email}
+          pageSize={PAGE_SIZE}
+          searchTerm={searchTerm}
+          footer={{ mode: "summary" }}
+        />
+      )}
     </div>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/interfaces.ts b/web/src/refresh-pages/admin/UsersPage/interfaces.ts
index caf0a980fbe..f11c9fea66e 100644
--- a/web/src/refresh-pages/admin/UsersPage/interfaces.ts
+++ b/web/src/refresh-pages/admin/UsersPage/interfaces.ts
@@ -1,4 +1,4 @@
-import type { UserRole } from "@/lib/types";
+import type { UserRole, UserStatus } from "@/lib/types";
 
 export interface UserGroupInfo {
   id: number;
@@ -6,15 +6,31 @@ export interface UserGroupInfo {
 }
 
 export interface UserRow {
-  id: string;
+  id: string | null;
   email: string;
-  role: UserRole;
+  role: UserRole | null;
+  status: UserStatus;
   is_active: boolean;
   is_scim_synced: boolean;
   personal_name: string | null;
-  created_at: string;
-  updated_at: string;
+  created_at: string | null;
+  updated_at: string | null;
   groups: UserGroupInfo[];
 }
 
-export type StatusFilter = "all" | "active" | "inactive";
+export interface GroupOption {
+  id: number;
+  name: string;
+  memberCount?: number;
+}
+
+/** Empty array = no filter (show all). */
+export type StatusFilter = UserStatus[];
+
+/** Keys match the UserStatus-derived labels used in filter badges. */
+export type StatusCountMap = {
+  active?: number;
+  inactive?: number;
+  invited?: number;
+  requested?: number;
+};

From c57ea65d42ff83205ef11c28abf325057a084408 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Wed, 11 Mar 2026 23:56:45 -0700
Subject: [PATCH 248/267] fix(db): avoid SQLAlchemy sentinel mismatch in batch
 user insert (#9300)

---
 backend/onyx/db/users.py | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/backend/onyx/db/users.py b/backend/onyx/db/users.py
index 1c69a19523c..8f29737c6ef 100644
--- a/backend/onyx/db/users.py
+++ b/backend/onyx/db/users.py
@@ -353,24 +353,23 @@ def batch_add_ext_perm_user_if_not_exists(
     lower_emails = [email.lower() for email in emails]
     found_users, missing_lower_emails = _get_users_by_emails(db_session, lower_emails)
 
-    new_users: list[User] = []
+    # Use savepoints (begin_nested) so that a failed insert only rolls back
+    # that single user, not the entire transaction. A plain rollback() would
+    # discard all previously flushed users in the same transaction.
+    # We also avoid add_all() because SQLAlchemy 2.0's insertmanyvalues
+    # batch path hits a UUID sentinel mismatch with server_default columns.
     for email in missing_lower_emails:
-        new_users.append(_generate_ext_permissioned_user(email=email))
-
-    try:
-        db_session.add_all(new_users)
-        db_session.commit()
-    except IntegrityError:
-        db_session.rollback()
-        if not continue_on_error:
-            raise
-        for user in new_users:
-            try:
-                db_session.add(user)
-                db_session.commit()
-            except IntegrityError:
-                db_session.rollback()
-                continue
+        user = _generate_ext_permissioned_user(email=email)
+        savepoint = db_session.begin_nested()
+        try:
+            db_session.add(user)
+            savepoint.commit()
+        except IntegrityError:
+            savepoint.rollback()
+            if not continue_on_error:
+                raise
+
+    db_session.commit()
     # Fetch all users again to ensure we have the most up-to-date list
     all_users, _ = _get_users_by_emails(db_session, lower_emails)
     return all_users

From dd07b3cf27bed0964a4a1b52829a093be19b1832 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 12 Mar 2026 09:32:06 -0700
Subject: [PATCH 249/267] fix(fe): prevent clicking `InputSelect` from
 selecting text (#9292)

---
 web/src/refresh-components/inputs/InputSelect.tsx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/web/src/refresh-components/inputs/InputSelect.tsx b/web/src/refresh-components/inputs/InputSelect.tsx
index 6c085b13e78..d94114f0187 100644
--- a/web/src/refresh-components/inputs/InputSelect.tsx
+++ b/web/src/refresh-components/inputs/InputSelect.tsx
@@ -2,7 +2,7 @@
 
 import * as React from "react";
 import * as SelectPrimitive from "@radix-ui/react-select";
-import { cn, noProp } from "@/lib/utils";
+import { cn } from "@/lib/utils";
 import LineItem, { LineItemProps } from "@/refresh-components/buttons/LineItem";
 import Text from "@/refresh-components/texts/Text";
 import type { IconProps } from "@opal/types";
@@ -298,7 +298,10 @@ function InputSelectContent({
         )}
         sideOffset={4}
         position="popper"
-        onMouseDown={noProp()}
+        onMouseDown={(e) => {
+          e.stopPropagation();
+          e.preventDefault();
+        }}
         {...props}
       >
         <SelectPrimitive.Viewport className="flex flex-col gap-1">

From 1649bed5481a9d100043722a465c88f47858d548 Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Thu, 12 Mar 2026 10:06:58 -0700
Subject: [PATCH 250/267] refactor: use ods latest-stable-tag to tag  images in
 Docker Hub (#9281)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 .github/workflows/deployment.yml | 42 +++++++++++++++++++++++---------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
index 1f689dd37fa..e3d556f1deb 100644
--- a/.github/workflows/deployment.yml
+++ b/.github/workflows/deployment.yml
@@ -29,15 +29,27 @@ jobs:
       build-backend-craft: ${{ steps.check.outputs.build-backend-craft }}
       build-model-server: ${{ steps.check.outputs.build-model-server }}
       is-cloud-tag: ${{ steps.check.outputs.is-cloud-tag }}
-      is-stable: ${{ steps.check.outputs.is-stable }}
       is-beta: ${{ steps.check.outputs.is-beta }}
-      is-stable-standalone: ${{ steps.check.outputs.is-stable-standalone }}
       is-beta-standalone: ${{ steps.check.outputs.is-beta-standalone }}
       is-craft-latest: ${{ steps.check.outputs.is-craft-latest }}
+      is-latest: ${{ steps.check.outputs.is-latest }}
       is-test-run: ${{ steps.check.outputs.is-test-run }}
       sanitized-tag: ${{ steps.check.outputs.sanitized-tag }}
       short-sha: ${{ steps.check.outputs.short-sha }}
     steps:
+      - name: Checkout (for git tags)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
+        with:
+          version: "0.9.9"
+          enable-cache: false
+
       - name: Check which components to build and version info
         id: check
         env:
@@ -54,9 +66,9 @@ jobs:
           IS_VERSION_TAG=false
           IS_STABLE=false
           IS_BETA=false
-          IS_STABLE_STANDALONE=false
           IS_BETA_STANDALONE=false
           IS_CRAFT_LATEST=false
+          IS_LATEST=false
           IS_PROD_TAG=false
           IS_TEST_RUN=false
           BUILD_DESKTOP=false
@@ -104,13 +116,22 @@ jobs:
           fi
 
           # Standalone version checks (for backend/model-server - version excluding cloud tags)
-          if [[ "$IS_STABLE" == "true" ]] && [[ "$IS_CLOUD" != "true" ]]; then
-            IS_STABLE_STANDALONE=true
-          fi
           if [[ "$IS_BETA" == "true" ]] && [[ "$IS_CLOUD" != "true" ]]; then
             IS_BETA_STANDALONE=true
           fi
 
+          # Determine if this tag should get the "latest" Docker tag.
+          # Only the highest semver stable tag (vX.Y.Z exactly) gets "latest".
+          if [[ "$IS_STABLE" == "true" ]]; then
+            HIGHEST_STABLE=$(uv run --no-sync --with onyx-devtools ods latest-stable-tag) || {
+              echo "::error::Failed to determine highest stable tag via 'ods latest-stable-tag'"
+              exit 1
+            }
+            if [[ "$TAG" == "$HIGHEST_STABLE" ]]; then
+              IS_LATEST=true
+            fi
+          fi
+
           # Determine if this is a production tag
           # Production tags are: version tags (v1.2.3*) or nightly tags
           if [[ "$IS_VERSION_TAG" == "true" ]] || [[ "$IS_NIGHTLY" == "true" ]]; then
@@ -129,11 +150,10 @@ jobs:
             echo "build-backend-craft=$BUILD_BACKEND_CRAFT"
             echo "build-model-server=$BUILD_MODEL_SERVER"
             echo "is-cloud-tag=$IS_CLOUD"
-            echo "is-stable=$IS_STABLE"
             echo "is-beta=$IS_BETA"
-            echo "is-stable-standalone=$IS_STABLE_STANDALONE"
             echo "is-beta-standalone=$IS_BETA_STANDALONE"
             echo "is-craft-latest=$IS_CRAFT_LATEST"
+            echo "is-latest=$IS_LATEST"
             echo "is-test-run=$IS_TEST_RUN"
             echo "sanitized-tag=$SANITIZED_TAG"
             echo "short-sha=$SHORT_SHA"
@@ -600,7 +620,7 @@ jobs:
             latest=false
           tags: |
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run == 'true' && format('web-{0}', needs.determine-builds.outputs.sanitized-tag) || github.ref_name }}
-            type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-stable == 'true' && 'latest' || '' }}
+            type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-latest == 'true' && 'latest' || '' }}
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && env.EDGE_TAG == 'true' && 'edge' || '' }}
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-beta == 'true' && 'beta' || '' }}
 
@@ -1037,7 +1057,7 @@ jobs:
             latest=false
           tags: |
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run == 'true' && format('backend-{0}', needs.determine-builds.outputs.sanitized-tag) || github.ref_name }}
-            type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-stable-standalone == 'true' && 'latest' || '' }}
+            type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-latest == 'true' && 'latest' || '' }}
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && env.EDGE_TAG == 'true' && 'edge' || '' }}
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-beta-standalone == 'true' && 'beta' || '' }}
 
@@ -1473,7 +1493,7 @@ jobs:
             latest=false
           tags: |
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run == 'true' && format('model-server-{0}', needs.determine-builds.outputs.sanitized-tag) || github.ref_name }}
-            type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-stable-standalone == 'true' && 'latest' || '' }}
+            type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-latest == 'true' && 'latest' || '' }}
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && env.EDGE_TAG == 'true' && 'edge' || '' }}
             type=raw,value=${{ needs.determine-builds.outputs.is-test-run != 'true' && needs.determine-builds.outputs.is-beta-standalone == 'true' && 'beta' || '' }}
 

From 809dab5746290f6716e89090663e12ea29c246a9 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Thu, 12 Mar 2026 10:46:12 -0700
Subject: [PATCH 251/267] feat(admin): add row actions with confirmation modals
 - 5/9 (#9180)

---
 web/src/hooks/useAdminUsers.ts                |   5 +-
 .../admin/UsersPage/UserRowActions.tsx        | 210 ++++++++++++++++++
 .../admin/UsersPage/UsersTable.tsx            |  89 ++++----
 web/src/refresh-pages/admin/UsersPage/svc.ts  |  44 ++++
 4 files changed, 305 insertions(+), 43 deletions(-)
 create mode 100644 web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx
 create mode 100644 web/src/refresh-pages/admin/UsersPage/svc.ts

diff --git a/web/src/hooks/useAdminUsers.ts b/web/src/hooks/useAdminUsers.ts
index c393a9b152b..7b177a4a46f 100644
--- a/web/src/hooks/useAdminUsers.ts
+++ b/web/src/hooks/useAdminUsers.ts
@@ -1,5 +1,6 @@
 "use client";
 
+import { useCallback } from "react";
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
@@ -112,11 +113,11 @@ export default function useAdminUsers() {
   const isLoading = acceptedLoading || invitedLoading || requestedLoading;
   const error = acceptedError ?? invitedError ?? requestedError;
 
-  function refresh() {
+  const refresh = useCallback(() => {
     acceptedMutate();
     invitedMutate();
     requestedMutate();
-  }
+  }, [acceptedMutate, invitedMutate, requestedMutate]);
 
   return { users, isLoading, error, refresh };
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx b/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx
new file mode 100644
index 00000000000..7a87e402dab
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx
@@ -0,0 +1,210 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "@opal/components";
+import { SvgMoreHorizontal, SvgXCircle, SvgTrash, SvgCheck } from "@opal/icons";
+import { Disabled } from "@opal/core";
+import Popover from "@/refresh-components/Popover";
+import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
+import Text from "@/refresh-components/texts/Text";
+import { UserStatus } from "@/lib/types";
+import { toast } from "@/hooks/useToast";
+import { deactivateUser, activateUser, deleteUser } from "./svc";
+import type { UserRow } from "./interfaces";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ModalType = "deactivate" | "activate" | "delete" | null;
+
+interface UserRowActionsProps {
+  user: UserRow;
+  onMutate: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function UserRowActions({
+  user,
+  onMutate,
+}: UserRowActionsProps) {
+  const [modal, setModal] = useState<ModalType>(null);
+  const [popoverOpen, setPopoverOpen] = useState(false);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  async function handleAction(
+    action: () => Promise<void>,
+    successMessage: string
+  ) {
+    setIsSubmitting(true);
+    try {
+      await action();
+      onMutate();
+      toast.success(successMessage);
+      setModal(null);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "An error occurred");
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  // Only show actions for accepted users (active or inactive).
+  // Invited/requested users have no row actions in this PR.
+  if (
+    user.status !== UserStatus.ACTIVE &&
+    user.status !== UserStatus.INACTIVE
+  ) {
+    return null;
+  }
+
+  // SCIM-managed users cannot be modified from the UI — changes would be
+  // overwritten on the next IdP sync.
+  if (user.is_scim_synced) {
+    return null;
+  }
+
+  return (
+    <>
+      <Popover open={popoverOpen} onOpenChange={setPopoverOpen}>
+        <Popover.Trigger asChild>
+          <Button prominence="tertiary" icon={SvgMoreHorizontal} />
+        </Popover.Trigger>
+        <Popover.Content align="end">
+          <div className="flex flex-col gap-0.5 p-1">
+            {user.status === UserStatus.ACTIVE ? (
+              <Button
+                prominence="tertiary"
+                icon={SvgXCircle}
+                onClick={() => {
+                  setPopoverOpen(false);
+                  setModal("deactivate");
+                }}
+              >
+                Deactivate User
+              </Button>
+            ) : (
+              <>
+                <Button
+                  prominence="tertiary"
+                  icon={SvgCheck}
+                  onClick={() => {
+                    setPopoverOpen(false);
+                    setModal("activate");
+                  }}
+                >
+                  Activate User
+                </Button>
+                <Button
+                  prominence="tertiary"
+                  variant="danger"
+                  icon={SvgTrash}
+                  onClick={() => {
+                    setPopoverOpen(false);
+                    setModal("delete");
+                  }}
+                >
+                  Delete User
+                </Button>
+              </>
+            )}
+          </div>
+        </Popover.Content>
+      </Popover>
+
+      {modal === "deactivate" && (
+        <ConfirmationModalLayout
+          icon={SvgXCircle}
+          title="Deactivate User"
+          onClose={isSubmitting ? undefined : () => setModal(null)}
+          submit={
+            <Disabled disabled={isSubmitting}>
+              <Button
+                variant="danger"
+                onClick={async () => {
+                  await handleAction(
+                    () => deactivateUser(user.email),
+                    "User deactivated"
+                  );
+                }}
+              >
+                Deactivate
+              </Button>
+            </Disabled>
+          }
+        >
+          <Text as="p" text03>
+            <Text as="span" text05>
+              {user.email}
+            </Text>{" "}
+            will immediately lose access to Onyx. Their sessions and agents will
+            be preserved. You can reactivate this account later.
+          </Text>
+        </ConfirmationModalLayout>
+      )}
+
+      {modal === "activate" && (
+        <ConfirmationModalLayout
+          icon={SvgCheck}
+          title="Activate User"
+          onClose={isSubmitting ? undefined : () => setModal(null)}
+          submit={
+            <Disabled disabled={isSubmitting}>
+              <Button
+                onClick={async () => {
+                  await handleAction(
+                    () => activateUser(user.email),
+                    "User activated"
+                  );
+                }}
+              >
+                Activate
+              </Button>
+            </Disabled>
+          }
+        >
+          <Text as="p" text03>
+            <Text as="span" text05>
+              {user.email}
+            </Text>{" "}
+            will regain access to Onyx.
+          </Text>
+        </ConfirmationModalLayout>
+      )}
+
+      {modal === "delete" && (
+        <ConfirmationModalLayout
+          icon={SvgTrash}
+          title="Delete User"
+          onClose={isSubmitting ? undefined : () => setModal(null)}
+          submit={
+            <Disabled disabled={isSubmitting}>
+              <Button
+                variant="danger"
+                onClick={async () => {
+                  await handleAction(
+                    () => deleteUser(user.email),
+                    "User deleted"
+                  );
+                }}
+              >
+                Delete
+              </Button>
+            </Disabled>
+          }
+        >
+          <Text as="p" text03>
+            <Text as="span" text05>
+              {user.email}
+            </Text>{" "}
+            will be permanently removed from Onyx. All of their session history
+            will be deleted. This cannot be undone.
+          </Text>
+        </ConfirmationModalLayout>
+      )}
+    </>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
index d355424d5ae..bcdb1b1cb80 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
@@ -21,6 +21,7 @@ import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useAdminUsers from "@/hooks/useAdminUsers";
 import useGroups from "@/hooks/useGroups";
 import UserFilters from "./UserFilters";
+import UserRowActions from "./UserRowActions";
 import type {
   UserRow,
   UserGroupInfo,
@@ -133,50 +134,54 @@ function renderLastUpdatedColumn(value: string | null) {
 }
 
 // ---------------------------------------------------------------------------
-// Columns (stable reference — defined at module scope)
+// Columns
 // ---------------------------------------------------------------------------
 
 const tc = createTableColumns<UserRow>();
 
-const columns = [
-  tc.qualifier({
-    content: "avatar-user",
-    getInitials: (row) => getInitials(row.personal_name, row.email),
-    selectable: false,
-  }),
-  tc.column("email", {
-    header: "Name",
-    weight: 22,
-    minWidth: 140,
-    cell: renderNameColumn,
-  }),
-  tc.column("groups", {
-    header: "Groups",
-    weight: 24,
-    minWidth: 200,
-    enableSorting: false,
-    cell: renderGroupsColumn,
-  }),
-  tc.column("role", {
-    header: "Account Type",
-    weight: 16,
-    minWidth: 180,
-    cell: renderRoleColumn,
-  }),
-  tc.column("status", {
-    header: "Status",
-    weight: 14,
-    minWidth: 100,
-    cell: renderStatusColumn,
-  }),
-  tc.column("updated_at", {
-    header: "Last Updated",
-    weight: 14,
-    minWidth: 100,
-    cell: renderLastUpdatedColumn,
-  }),
-  tc.actions(),
-];
+function buildColumns(onMutate: () => void) {
+  return [
+    tc.qualifier({
+      content: "avatar-user",
+      getInitials: (row) => getInitials(row.personal_name, row.email),
+      selectable: false,
+    }),
+    tc.column("email", {
+      header: "Name",
+      weight: 22,
+      minWidth: 140,
+      cell: renderNameColumn,
+    }),
+    tc.column("groups", {
+      header: "Groups",
+      weight: 24,
+      minWidth: 200,
+      enableSorting: false,
+      cell: renderGroupsColumn,
+    }),
+    tc.column("role", {
+      header: "Account Type",
+      weight: 16,
+      minWidth: 180,
+      cell: renderRoleColumn,
+    }),
+    tc.column("status", {
+      header: "Status",
+      weight: 14,
+      minWidth: 100,
+      cell: renderStatusColumn,
+    }),
+    tc.column("updated_at", {
+      header: "Last Updated",
+      weight: 14,
+      minWidth: 100,
+      cell: renderLastUpdatedColumn,
+    }),
+    tc.actions({
+      cell: (row) => <UserRowActions user={row} onMutate={onMutate} />,
+    }),
+  ];
+}
 
 // ---------------------------------------------------------------------------
 // Component
@@ -213,7 +218,9 @@ export default function UsersTable({
     [allGroups]
   );
 
-  const { users, isLoading, error } = useAdminUsers();
+  const { users, isLoading, error, refresh } = useAdminUsers();
+
+  const columns = useMemo(() => buildColumns(refresh), [refresh]);
 
   // Client-side filtering
   const filteredUsers = useMemo(() => {
diff --git a/web/src/refresh-pages/admin/UsersPage/svc.ts b/web/src/refresh-pages/admin/UsersPage/svc.ts
new file mode 100644
index 00000000000..fe0a5705c4d
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/svc.ts
@@ -0,0 +1,44 @@
+async function parseErrorDetail(
+  res: Response,
+  fallback: string
+): Promise<string> {
+  try {
+    const body = await res.json();
+    return body?.detail ?? fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function deactivateUser(email: string): Promise<void> {
+  const res = await fetch("/api/manage/admin/deactivate-user", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ user_email: email }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to deactivate user"));
+  }
+}
+
+export async function activateUser(email: string): Promise<void> {
+  const res = await fetch("/api/manage/admin/activate-user", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ user_email: email }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to activate user"));
+  }
+}
+
+export async function deleteUser(email: string): Promise<void> {
+  const res = await fetch("/api/manage/admin/delete-user", {
+    method: "DELETE",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ user_email: email }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to delete user"));
+  }
+}

From fabbb00c49441bf94d5f93b9c09b1dfe1ab9aa9c Mon Sep 17 00:00:00 2001
From: Wenxi <wenxi@onyx.app>
Date: Thu, 12 Mar 2026 11:27:25 -0700
Subject: [PATCH 252/267] refactor: sync craft latest builds with latest stable
 (#9279)

---
 .github/workflows/deployment.yml | 18 ++++++------------
 tools/ods/cmd/print_latest.go    |  1 -
 2 files changed, 6 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml
index e3d556f1deb..548d16cafe4 100644
--- a/.github/workflows/deployment.yml
+++ b/.github/workflows/deployment.yml
@@ -31,7 +31,6 @@ jobs:
       is-cloud-tag: ${{ steps.check.outputs.is-cloud-tag }}
       is-beta: ${{ steps.check.outputs.is-beta }}
       is-beta-standalone: ${{ steps.check.outputs.is-beta-standalone }}
-      is-craft-latest: ${{ steps.check.outputs.is-craft-latest }}
       is-latest: ${{ steps.check.outputs.is-latest }}
       is-test-run: ${{ steps.check.outputs.is-test-run }}
       sanitized-tag: ${{ steps.check.outputs.sanitized-tag }}
@@ -55,6 +54,7 @@ jobs:
         env:
           EVENT_NAME: ${{ github.event_name }}
         run: |
+          set -eo pipefail
           TAG="${GITHUB_REF_NAME}"
           # Sanitize tag name by replacing slashes with hyphens (for Docker tag compatibility)
           SANITIZED_TAG=$(echo "$TAG" | tr '/' '-')
@@ -67,7 +67,6 @@ jobs:
           IS_STABLE=false
           IS_BETA=false
           IS_BETA_STANDALONE=false
-          IS_CRAFT_LATEST=false
           IS_LATEST=false
           IS_PROD_TAG=false
           IS_TEST_RUN=false
@@ -79,9 +78,6 @@ jobs:
           BUILD_MODEL_SERVER=true
 
           # Determine tag type based on pattern matching (do regex checks once)
-          if [[ "$TAG" == craft-* ]]; then
-            IS_CRAFT_LATEST=true
-          fi
           if [[ "$TAG" == *cloud* ]]; then
             IS_CLOUD=true
           fi
@@ -109,12 +105,6 @@ jobs:
             fi
           fi
 
-          # Craft-latest builds backend with Craft enabled
-          if [[ "$IS_CRAFT_LATEST" == "true" ]]; then
-            BUILD_BACKEND_CRAFT=true
-            BUILD_BACKEND=false
-          fi
-
           # Standalone version checks (for backend/model-server - version excluding cloud tags)
           if [[ "$IS_BETA" == "true" ]] && [[ "$IS_CLOUD" != "true" ]]; then
             IS_BETA_STANDALONE=true
@@ -132,6 +122,11 @@ jobs:
             fi
           fi
 
+          # Build craft-latest backend alongside the regular latest.
+          if [[ "$IS_LATEST" == "true" ]]; then
+            BUILD_BACKEND_CRAFT=true
+          fi
+
           # Determine if this is a production tag
           # Production tags are: version tags (v1.2.3*) or nightly tags
           if [[ "$IS_VERSION_TAG" == "true" ]] || [[ "$IS_NIGHTLY" == "true" ]]; then
@@ -152,7 +147,6 @@ jobs:
             echo "is-cloud-tag=$IS_CLOUD"
             echo "is-beta=$IS_BETA"
             echo "is-beta-standalone=$IS_BETA_STANDALONE"
-            echo "is-craft-latest=$IS_CRAFT_LATEST"
             echo "is-latest=$IS_LATEST"
             echo "is-test-run=$IS_TEST_RUN"
             echo "sanitized-tag=$SANITIZED_TAG"
diff --git a/tools/ods/cmd/print_latest.go b/tools/ods/cmd/print_latest.go
index 0608c3edf77..85c501c8630 100644
--- a/tools/ods/cmd/print_latest.go
+++ b/tools/ods/cmd/print_latest.go
@@ -2,7 +2,6 @@ package cmd
 
 import (
 	"fmt"
-
 	"github.com/jmelahman/tag/git"
 	"github.com/spf13/cobra"
 )

From dbcbfc1629806f0d9b4c5b78a5f382a9c72f1884 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 12 Mar 2026 11:43:43 -0700
Subject: [PATCH 253/267] fix(favicon): prefer relative path to favicon (#9307)

---
 web/src/app/layout.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/web/src/app/layout.tsx b/web/src/app/layout.tsx
index a65a09459e1..362851c4fea 100644
--- a/web/src/app/layout.tsx
+++ b/web/src/app/layout.tsx
@@ -12,7 +12,7 @@ import {
   MODAL_ROOT_ID,
 } from "@/lib/constants";
 import { Metadata } from "next";
-import { buildClientUrl } from "@/lib/utilsSS";
+
 import { Inter } from "next/font/google";
 import { EnterpriseSettings, ApplicationStatus } from "@/interfaces/settings";
 import AppProvider from "@/providers/AppProvider";
@@ -45,14 +45,14 @@ const hankenGrotesk = Hanken_Grotesk({
 });
 
 export async function generateMetadata(): Promise<Metadata> {
-  let logoLocation = buildClientUrl("/onyx.ico");
+  let logoLocation = "/onyx.ico";
   let enterpriseSettings: EnterpriseSettings | null = null;
   if (SERVER_SIDE_ONLY__PAID_ENTERPRISE_FEATURES_ENABLED) {
     enterpriseSettings = await (await fetchEnterpriseSettingsSS()).json();
     logoLocation =
       enterpriseSettings && enterpriseSettings.use_custom_logo
         ? "/api/enterprise-settings/logo"
-        : buildClientUrl("/onyx.ico");
+        : "/onyx.ico";
   }
 
   return {

From 78a9b386c7f6ce661400de1ff69f9bf985308430 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Thu, 12 Mar 2026 12:07:17 -0700
Subject: [PATCH 254/267] chore: sharepoint error logs (#9309)

---
 .../onyx/connectors/sharepoint/connector.py   | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/backend/onyx/connectors/sharepoint/connector.py b/backend/onyx/connectors/sharepoint/connector.py
index 0082d139f34..51c0c14f6bc 100644
--- a/backend/onyx/connectors/sharepoint/connector.py
+++ b/backend/onyx/connectors/sharepoint/connector.py
@@ -272,6 +272,15 @@ class SizeCapExceeded(Exception):
     """Exception raised when the size cap is exceeded."""
 
 
+def _log_and_raise_for_status(response: requests.Response) -> None:
+    """Log the response text and raise for status."""
+    try:
+        response.raise_for_status()
+    except Exception:
+        logger.error(f"Graph API request failed: {response.text}")
+        raise
+
+
 def load_certificate_from_pfx(pfx_data: bytes, password: str) -> CertificateData | None:
     """Load certificate from .pfx file for MSAL authentication"""
     try:
@@ -348,7 +357,7 @@ def _probe_remote_size(url: str, timeout: int) -> int | None:
     """Determine remote size using HEAD or a range GET probe. Returns None if unknown."""
     try:
         head_resp = requests.head(url, timeout=timeout, allow_redirects=True)
-        head_resp.raise_for_status()
+        _log_and_raise_for_status(head_resp)
         cl = head_resp.headers.get("Content-Length")
         if cl and cl.isdigit():
             return int(cl)
@@ -363,7 +372,7 @@ def _probe_remote_size(url: str, timeout: int) -> int | None:
             timeout=timeout,
             stream=True,
         ) as range_resp:
-            range_resp.raise_for_status()
+            _log_and_raise_for_status(range_resp)
             cr = range_resp.headers.get("Content-Range")  # e.g., "bytes 0-0/12345"
             if cr and "/" in cr:
                 total = cr.split("/")[-1]
@@ -388,7 +397,7 @@ def _download_with_cap(url: str, timeout: int, cap: int) -> bytes:
     - Returns the full bytes if the content fits within `cap`.
     """
     with requests.get(url, stream=True, timeout=timeout) as resp:
-        resp.raise_for_status()
+        _log_and_raise_for_status(resp)
 
         # If the server provides Content-Length, prefer an early decision.
         cl_header = resp.headers.get("Content-Length")
@@ -432,7 +441,7 @@ def _download_via_graph_api(
     with requests.get(
         url, headers=headers, stream=True, timeout=REQUEST_TIMEOUT_SECONDS
     ) as resp:
-        resp.raise_for_status()
+        _log_and_raise_for_status(resp)
         buf = io.BytesIO()
         for chunk in resp.iter_content(64 * 1024):
             if not chunk:
@@ -1313,7 +1322,7 @@ def _graph_api_get_json(
                         access_token = self._get_graph_access_token()
                         headers = {"Authorization": f"Bearer {access_token}"}
                         continue
-                response.raise_for_status()
+                _log_and_raise_for_status(response)
                 return response.json()
             except (requests.ConnectionError, requests.Timeout):
                 if attempt < GRAPH_API_MAX_RETRIES:

From c5c08c5da6fa3ce12632273cd4ce065b61159125 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Thu, 12 Mar 2026 12:40:07 -0700
Subject: [PATCH 255/267] feat(admin): add invite users modal - 6/9 (#9181)

---
 web/src/refresh-components/Chip.tsx           |   4 +
 .../inputs/InputChipField.tsx                 |  79 ++++++--
 web/src/refresh-pages/admin/UsersPage.tsx     |  10 +-
 .../admin/UsersPage/InviteUsersModal.tsx      | 178 ++++++++++++++++++
 web/src/refresh-pages/admin/UsersPage/svc.ts  |  11 ++
 5 files changed, 262 insertions(+), 20 deletions(-)
 create mode 100644 web/src/refresh-pages/admin/UsersPage/InviteUsersModal.tsx

diff --git a/web/src/refresh-components/Chip.tsx b/web/src/refresh-components/Chip.tsx
index 50e59114e61..2e4b9e7bf7c 100644
--- a/web/src/refresh-components/Chip.tsx
+++ b/web/src/refresh-components/Chip.tsx
@@ -6,6 +6,8 @@ import type { IconProps } from "@opal/types";
 export interface ChipProps {
   children?: string;
   icon?: React.FunctionComponent<IconProps>;
+  /** Icon rendered after the label (e.g. a warning indicator) */
+  rightIcon?: React.FunctionComponent<IconProps>;
   onRemove?: () => void;
   smallLabel?: boolean;
 }
@@ -24,6 +26,7 @@ export interface ChipProps {
 export default function Chip({
   children,
   icon: Icon,
+  rightIcon: RightIcon,
   onRemove,
   smallLabel = true,
 }: ChipProps) {
@@ -35,6 +38,7 @@ export default function Chip({
           {children}
         </Text>
       )}
+      {RightIcon && <RightIcon size={14} className="text-text-03" />}
       {onRemove && (
         <Button
           onClick={(e) => {
diff --git a/web/src/refresh-components/inputs/InputChipField.tsx b/web/src/refresh-components/inputs/InputChipField.tsx
index 4f07456410f..86f73067779 100644
--- a/web/src/refresh-components/inputs/InputChipField.tsx
+++ b/web/src/refresh-components/inputs/InputChipField.tsx
@@ -9,11 +9,14 @@ import {
   Variants,
   wrapperClasses,
 } from "@/refresh-components/inputs/styles";
+import { SvgAlertTriangle } from "@opal/icons";
 import type { IconProps } from "@opal/types";
 
 export interface ChipItem {
   id: string;
   label: string;
+  /** When true the chip shows a warning icon */
+  error?: boolean;
 }
 
 export interface InputChipFieldProps {
@@ -29,6 +32,8 @@ export interface InputChipFieldProps {
   variant?: Variants;
   icon?: React.FunctionComponent<IconProps>;
   className?: string;
+  /** "inline" renders chips and input in one row; "stacked" puts chips above the input */
+  layout?: "inline" | "stacked";
 }
 
 /**
@@ -61,6 +66,7 @@ function InputChipField({
   variant = "primary",
   icon: Icon,
   className,
+  layout = "inline",
 }: InputChipFieldProps) {
   const inputRef = React.useRef<HTMLInputElement>(null);
 
@@ -85,25 +91,32 @@ function InputChipField({
     }
   }
 
-  return (
-    <div
-      className={cn(
-        "flex flex-row items-center flex-wrap gap-1 p-1.5 rounded-08 cursor-text w-full",
-        wrapperClasses[variant],
-        className
-      )}
-      onClick={() => inputRef.current?.focus()}
-    >
+  const chipElements =
+    chips.length > 0
+      ? chips.map((chip) => (
+          <Chip
+            key={chip.id}
+            onRemove={disabled ? undefined : () => onRemoveChip(chip.id)}
+            rightIcon={
+              chip.error
+                ? (props) => (
+                    <SvgAlertTriangle
+                      {...props}
+                      className="text-status-warning-text"
+                    />
+                  )
+                : undefined
+            }
+            smallLabel={layout === "stacked"}
+          >
+            {chip.label}
+          </Chip>
+        ))
+      : null;
+
+  const inputElement = (
+    <>
       {Icon && <Icon size={16} className="text-text-04 shrink-0" />}
-      {chips.map((chip) => (
-        <Chip
-          key={chip.id}
-          onRemove={disabled ? undefined : () => onRemoveChip(chip.id)}
-          smallLabel={false}
-        >
-          {chip.label}
-        </Chip>
-      ))}
       <input
         ref={inputRef}
         type="text"
@@ -118,6 +131,36 @@ function InputChipField({
           textClasses[variant]
         )}
       />
+    </>
+  );
+
+  return (
+    <div
+      className={cn(
+        "flex p-1.5 rounded-08 cursor-text w-full",
+        layout === "stacked"
+          ? "flex-col gap-1"
+          : "flex-row flex-wrap items-center gap-1",
+        wrapperClasses[variant],
+        className
+      )}
+      onClick={() => inputRef.current?.focus()}
+    >
+      {layout === "stacked" ? (
+        <>
+          {chipElements && (
+            <div className="flex flex-row items-center flex-wrap gap-1">
+              {chipElements}
+            </div>
+          )}
+          <div className="flex flex-row items-center gap-1">{inputElement}</div>
+        </>
+      ) : (
+        <>
+          {chipElements}
+          {inputElement}
+        </>
+      )}
     </div>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage.tsx b/web/src/refresh-pages/admin/UsersPage.tsx
index 2d0b9f868f6..7674fa7f0d9 100644
--- a/web/src/refresh-pages/admin/UsersPage.tsx
+++ b/web/src/refresh-pages/admin/UsersPage.tsx
@@ -12,6 +12,7 @@ import type { StatusFilter } from "./UsersPage/interfaces";
 
 import UsersSummary from "./UsersPage/UsersSummary";
 import UsersTable from "./UsersPage/UsersTable";
+import InviteUsersModal from "./UsersPage/InviteUsersModal";
 
 // ---------------------------------------------------------------------------
 // Users page content
@@ -63,19 +64,24 @@ function UsersContent() {
 // ---------------------------------------------------------------------------
 
 export default function UsersPage() {
+  const [inviteOpen, setInviteOpen] = useState(false);
+
   return (
     <SettingsLayouts.Root width="lg">
       <SettingsLayouts.Header
         title="Users & Requests"
         icon={SvgUser}
         rightChildren={
-          // TODO (ENG-3806): Wire up invite modal
-          <Button icon={SvgUserPlus}>Invite Users</Button>
+          <Button icon={SvgUserPlus} onClick={() => setInviteOpen(true)}>
+            Invite Users
+          </Button>
         }
       />
       <SettingsLayouts.Body>
         <UsersContent />
       </SettingsLayouts.Body>
+
+      <InviteUsersModal open={inviteOpen} onOpenChange={setInviteOpen} />
     </SettingsLayouts.Root>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/InviteUsersModal.tsx b/web/src/refresh-pages/admin/UsersPage/InviteUsersModal.tsx
new file mode 100644
index 00000000000..84ac7a053c8
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/InviteUsersModal.tsx
@@ -0,0 +1,178 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import { Button } from "@opal/components";
+import { SvgUsers } from "@opal/icons";
+import { Disabled } from "@opal/core";
+import Modal, { BasicModalFooter } from "@/refresh-components/Modal";
+import InputChipField from "@/refresh-components/inputs/InputChipField";
+import type { ChipItem } from "@/refresh-components/inputs/InputChipField";
+import { toast } from "@/hooks/useToast";
+import { inviteUsers } from "./svc";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface InviteUsersModalProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function InviteUsersModal({
+  open,
+  onOpenChange,
+}: InviteUsersModalProps) {
+  const [chips, setChips] = useState<ChipItem[]>([]);
+  const [inputValue, setInputValue] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  /** Parse a comma-separated string into de-duped ChipItems */
+  function parseEmails(value: string, existing: ChipItem[]): ChipItem[] {
+    const entries = value
+      .split(",")
+      .map((e) => e.trim().toLowerCase())
+      .filter(Boolean);
+
+    const newChips: ChipItem[] = [];
+    for (const email of entries) {
+      const alreadyAdded =
+        existing.some((c) => c.label === email) ||
+        newChips.some((c) => c.label === email);
+      if (!alreadyAdded) {
+        newChips.push({
+          id: email,
+          label: email,
+          error: !EMAIL_REGEX.test(email),
+        });
+      }
+    }
+    return newChips;
+  }
+
+  function addEmail(value: string) {
+    const newChips = parseEmails(value, chips);
+    if (newChips.length > 0) {
+      setChips((prev) => [...prev, ...newChips]);
+    }
+    setInputValue("");
+  }
+
+  function removeChip(id: string) {
+    setChips((prev) => prev.filter((c) => c.id !== id));
+  }
+
+  const handleClose = useCallback(() => {
+    onOpenChange(false);
+    // Reset state after close animation
+    setTimeout(() => {
+      setChips([]);
+      setInputValue("");
+      setIsSubmitting(false);
+    }, 200);
+  }, [onOpenChange]);
+
+  /** Intercept backdrop/ESC closes so state is always reset */
+  const handleOpenChange = useCallback(
+    (next: boolean) => {
+      if (!next) {
+        if (!isSubmitting) handleClose();
+      } else {
+        onOpenChange(next);
+      }
+    },
+    [handleClose, isSubmitting, onOpenChange]
+  );
+
+  async function handleInvite() {
+    // Flush any pending text in the input into chips synchronously
+    const pending = inputValue.trim();
+    const allChips = pending
+      ? [...chips, ...parseEmails(pending, chips)]
+      : chips;
+
+    if (pending) {
+      setChips(allChips);
+      setInputValue("");
+    }
+
+    const validEmails = allChips.filter((c) => !c.error).map((c) => c.label);
+
+    if (validEmails.length === 0) {
+      toast.error("Please add at least one valid email address");
+      return;
+    }
+
+    setIsSubmitting(true);
+    try {
+      await inviteUsers(validEmails);
+      toast.success(
+        `Invited ${validEmails.length} user${validEmails.length > 1 ? "s" : ""}`
+      );
+      handleClose();
+    } catch (err) {
+      toast.error(
+        err instanceof Error ? err.message : "Failed to invite users"
+      );
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  return (
+    <Modal open={open} onOpenChange={handleOpenChange}>
+      <Modal.Content width="sm" height="fit">
+        <Modal.Header
+          icon={SvgUsers}
+          title="Invite Users"
+          onClose={isSubmitting ? undefined : handleClose}
+        />
+
+        <Modal.Body>
+          <InputChipField
+            chips={chips}
+            onRemoveChip={removeChip}
+            onAdd={addEmail}
+            value={inputValue}
+            onChange={setInputValue}
+            placeholder="Add emails to invite, comma separated"
+            layout="stacked"
+          />
+        </Modal.Body>
+
+        <Modal.Footer>
+          <BasicModalFooter
+            cancel={
+              <Disabled disabled={isSubmitting}>
+                <Button prominence="tertiary" onClick={handleClose}>
+                  Cancel
+                </Button>
+              </Disabled>
+            }
+            submit={
+              <Disabled
+                disabled={
+                  isSubmitting ||
+                  chips.length === 0 ||
+                  chips.every((c) => c.error)
+                }
+              >
+                <Button onClick={handleInvite}>Invite</Button>
+              </Disabled>
+            }
+          />
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/svc.ts b/web/src/refresh-pages/admin/UsersPage/svc.ts
index fe0a5705c4d..dd2e9d1dba8 100644
--- a/web/src/refresh-pages/admin/UsersPage/svc.ts
+++ b/web/src/refresh-pages/admin/UsersPage/svc.ts
@@ -42,3 +42,14 @@ export async function deleteUser(email: string): Promise<void> {
     throw new Error(await parseErrorDetail(res, "Failed to delete user"));
   }
 }
+
+export async function inviteUsers(emails: string[]): Promise<void> {
+  const res = await fetch("/api/manage/admin/users", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ emails }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to invite users"));
+  }
+}

From e264356eb5f7d77341e3294fbaade1f92c9bc87d Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 12 Mar 2026 13:57:54 -0700
Subject: [PATCH 256/267] feat(chat): support attaching more file types to
 chats (#9299)

---
 .../features/projects/projects_file_utils.py  | 34 +++++++---------
 .../onyx/server/test_projects_file_utils.py   | 39 +++++++++++++++++++
 2 files changed, 54 insertions(+), 19 deletions(-)

diff --git a/backend/onyx/server/features/projects/projects_file_utils.py b/backend/onyx/server/features/projects/projects_file_utils.py
index d3136e3d4b7..1eaaa429f79 100644
--- a/backend/onyx/server/features/projects/projects_file_utils.py
+++ b/backend/onyx/server/features/projects/projects_file_utils.py
@@ -157,10 +157,13 @@ def categorize_uploaded_files(
     """
     Categorize uploaded files based on text extractability and tokenized length.
 
-    - Extracts text using extract_file_text for supported plain/document extensions.
+    - Images are estimated for token cost via a patch-based heuristic.
+    - All other files are run through extract_file_text, which handles known
+      document formats (.pdf, .docx, …) and falls back to a text-detection
+      heuristic for unknown extensions (.py, .js, .rs, …).
     - Uses default tokenizer to compute token length.
-    - If token length > 100,000, reject file (unless threshold skip is enabled).
-    - If extension unsupported or text cannot be extracted, reject file.
+    - If token length > threshold, reject file (unless threshold skip is enabled).
+    - If text cannot be extracted, reject file.
     - Otherwise marked as acceptable.
     """
 
@@ -217,8 +220,7 @@ def categorize_uploaded_files(
                     )
                     results.rejected.append(
                         RejectedFile(
-                            filename=filename,
-                            reason=f"Unsupported file type: {extension}",
+                            filename=filename, reason="Unsupported file contents"
                         )
                     )
                     continue
@@ -235,8 +237,10 @@ def categorize_uploaded_files(
                     results.acceptable_file_to_token_count[filename] = token_count
                 continue
 
-            # Otherwise, handle as text/document: extract text and count tokens
-            elif extension in OnyxFileExtensions.ALL_ALLOWED_EXTENSIONS:
+            # Handle as text/document: attempt text extraction and count tokens.
+            # This accepts any file that extract_file_text can handle, including
+            # code files (.py, .js, .rs, etc.) via its is_text_file() fallback.
+            else:
                 if is_file_password_protected(
                     file=upload.file,
                     file_name=filename,
@@ -259,7 +263,10 @@ def categorize_uploaded_files(
                 if not text_content:
                     logger.warning(f"No text content extracted from '{filename}'")
                     results.rejected.append(
-                        RejectedFile(filename=filename, reason="Could not read file")
+                        RejectedFile(
+                            filename=filename,
+                            reason=f"Unsupported file type: {extension}",
+                        )
                     )
                     continue
 
@@ -282,17 +289,6 @@ def categorize_uploaded_files(
                     logger.warning(
                         f"Failed to reset file pointer for '{filename}': {str(e)}"
                     )
-                continue
-
-            # If not recognized as supported types above, mark unsupported
-            logger.warning(
-                f"Unsupported file extension '{extension}' for file '{filename}'"
-            )
-            results.rejected.append(
-                RejectedFile(
-                    filename=filename, reason=f"Unsupported file type: {extension}"
-                )
-            )
         except Exception as e:
             logger.warning(
                 f"Failed to process uploaded file '{get_safe_filename(upload)}' (error_type={type(e).__name__}, error={str(e)})"
diff --git a/backend/tests/unit/onyx/server/test_projects_file_utils.py b/backend/tests/unit/onyx/server/test_projects_file_utils.py
index 35ec07ba5ee..4b6ba945bb3 100644
--- a/backend/tests/unit/onyx/server/test_projects_file_utils.py
+++ b/backend/tests/unit/onyx/server/test_projects_file_utils.py
@@ -186,3 +186,42 @@ def test_categorize_uploaded_files_checks_size_before_text_extraction(
     assert len(result.acceptable) == 0
     assert len(result.rejected) == 1
     assert result.rejected[0].reason == "Exceeds 1 MB file size limit"
+
+
+def test_categorize_uploaded_files_accepts_python_file(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 10_000)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+
+    py_source = b'def hello():\n    print("world")\n'
+    monkeypatch.setattr(
+        utils, "extract_file_text", lambda **_kwargs: py_source.decode()
+    )
+
+    upload = _make_upload("script.py", size=len(py_source), content=py_source)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 1
+    assert result.acceptable[0].filename == "script.py"
+    assert len(result.rejected) == 0
+
+
+def test_categorize_uploaded_files_rejects_binary_file(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _patch_common_dependencies(monkeypatch)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_BYTES", 10_000)
+    monkeypatch.setattr(utils, "USER_FILE_MAX_UPLOAD_SIZE_MB", 1)
+
+    monkeypatch.setattr(utils, "extract_file_text", lambda **_kwargs: "")
+
+    binary_content = bytes(range(256)) * 4
+    upload = _make_upload("data.bin", size=len(binary_content), content=binary_content)
+    result = utils.categorize_uploaded_files([upload], MagicMock())
+
+    assert len(result.acceptable) == 0
+    assert len(result.rejected) == 1
+    assert result.rejected[0].filename == "data.bin"
+    assert "Unsupported file type" in result.rejected[0].reason

From 24de76ad28e82ebaca53d708dc99655ab631cd5c Mon Sep 17 00:00:00 2001
From: Jessica Singh <86633231+jessicasingh7@users.noreply.github.com>
Date: Thu, 12 Mar 2026 14:06:13 -0700
Subject: [PATCH 257/267] chore(auth): deployment helm cleanup (#8588)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
---
 .github/workflows/pr-helm-chart-testing.yml   | 11 +++++++++-
 deployment/helm/charts/onyx/Chart.yaml        |  2 +-
 deployment/helm/charts/onyx/ci/ct-values.yaml |  6 +++++
 .../charts/onyx/templates/auth-secrets.yaml   | 22 ++++++++++++++-----
 deployment/helm/charts/onyx/values.yaml       | 20 +++++++++++++++--
 5 files changed, 52 insertions(+), 9 deletions(-)
 create mode 100644 deployment/helm/charts/onyx/ci/ct-values.yaml

diff --git a/.github/workflows/pr-helm-chart-testing.yml b/.github/workflows/pr-helm-chart-testing.yml
index a07fd3bcbb8..86f56bbd885 100644
--- a/.github/workflows/pr-helm-chart-testing.yml
+++ b/.github/workflows/pr-helm-chart-testing.yml
@@ -133,7 +133,7 @@ jobs:
           echo "=== Validating chart dependencies ==="
           cd deployment/helm/charts/onyx
           helm dependency update
-          helm lint .
+          helm lint . --set auth.userauth.values.user_auth_secret=placeholder
 
       - name: Run chart-testing (install) with enhanced monitoring
         timeout-minutes: 25
@@ -194,6 +194,7 @@ jobs:
               --set=vespa.enabled=false \
               --set=opensearch.enabled=true \
               --set=auth.opensearch.enabled=true \
+              --set=auth.userauth.values.user_auth_secret=test-secret \
               --set=slackbot.enabled=false \
               --set=postgresql.enabled=true \
               --set=postgresql.cluster.storage.storageClass=standard \
@@ -230,6 +231,10 @@ jobs:
         if: steps.list-changed.outputs.changed == 'true'
         run: |
           echo "=== Post-install verification ==="
+          if ! kubectl cluster-info >/dev/null 2>&1; then
+            echo "ERROR: Kubernetes cluster is not reachable after install"
+            exit 1
+          fi
           kubectl get pods --all-namespaces
           kubectl get services --all-namespaces
           # Only show issues if they exist
@@ -239,6 +244,10 @@ jobs:
         if: failure() && steps.list-changed.outputs.changed == 'true'
         run: |
           echo "=== Cleanup on failure ==="
+          if ! kubectl cluster-info >/dev/null 2>&1; then
+            echo "Skipping failure cleanup: Kubernetes cluster is not reachable"
+            exit 0
+          fi
           echo "=== Final cluster state ==="
           kubectl get pods --all-namespaces
           kubectl get events --all-namespaces --sort-by=.lastTimestamp | tail -10
diff --git a/deployment/helm/charts/onyx/Chart.yaml b/deployment/helm/charts/onyx/Chart.yaml
index 23851be6b29..72d8d3a0e12 100644
--- a/deployment/helm/charts/onyx/Chart.yaml
+++ b/deployment/helm/charts/onyx/Chart.yaml
@@ -5,7 +5,7 @@ home: https://www.onyx.app/
 sources:
   - "https://github.com/onyx-dot-app/onyx"
 type: application
-version: 0.4.33
+version: 0.4.34
 appVersion: latest
 annotations:
   category: Productivity
diff --git a/deployment/helm/charts/onyx/ci/ct-values.yaml b/deployment/helm/charts/onyx/ci/ct-values.yaml
new file mode 100644
index 00000000000..774a7485ccc
--- /dev/null
+++ b/deployment/helm/charts/onyx/ci/ct-values.yaml
@@ -0,0 +1,6 @@
+# Values for chart-testing (ct lint/install)
+# This file is automatically used by ct when running lint and install commands
+auth:
+  userauth:
+    values:
+      user_auth_secret: "placeholder-for-ci-testing"
diff --git a/deployment/helm/charts/onyx/templates/auth-secrets.yaml b/deployment/helm/charts/onyx/templates/auth-secrets.yaml
index e608a8ab84d..8864af80d02 100644
--- a/deployment/helm/charts/onyx/templates/auth-secrets.yaml
+++ b/deployment/helm/charts/onyx/templates/auth-secrets.yaml
@@ -1,17 +1,29 @@
 {{- if hasKey .Values.auth "secretKeys" }}
 {{- fail "ERROR: Secrets handling has been refactored under 'auth' and must be updated before upgrading to this chart version." }}
 {{- end }}
-{{- range $secretContent := .Values.auth }}
-{{- if and (empty $secretContent.existingSecret) (ne ($secretContent.enabled | default true) false) }}
+{{- range $secretKey, $secretContent := .Values.auth }}
+{{- if and (empty $secretContent.existingSecret) (or (not (hasKey $secretContent "enabled")) $secretContent.enabled) }}
+{{- $secretName := include "onyx.secretName" $secretContent }}
+{{- $existingSecret := lookup "v1" "Secret" $.Release.Namespace $secretName }}
+{{- /* Pre-validate: fail before emitting YAML if any required value is missing */ -}}
+{{- range $name, $value := $secretContent.values }}
+{{- if and (empty $value) (not (and $existingSecret (hasKey $existingSecret.data $name))) }}
+{{- fail (printf "Secret value for '%s' is required but not set and no existing secret found. Please set auth.%s.values.%s in values.yaml" $name $secretKey $name) }}
+{{- end }}
+{{- end }}
 ---
 apiVersion: v1
 kind: Secret
 metadata:
-  name: {{ include "onyx.secretName" $secretContent }}
+  name: {{ $secretName }}
 type: Opaque
 stringData:
-  {{- range $name, $value := $secretContent.values }}
+{{- range $name, $value := $secretContent.values }}
+{{- if not (empty $value) }}
   {{ $name }}: {{ $value | quote }}
-  {{- end }}
+{{- else if and $existingSecret (hasKey $existingSecret.data $name) }}
+  {{ $name }}: {{ index $existingSecret.data $name | b64dec | quote }}
+{{- end }}
+{{- end }}
 {{- end }}
 {{- end }}
diff --git a/deployment/helm/charts/onyx/values.yaml b/deployment/helm/charts/onyx/values.yaml
index d70f93dbcad..50cdf8dd06e 100644
--- a/deployment/helm/charts/onyx/values.yaml
+++ b/deployment/helm/charts/onyx/values.yaml
@@ -1183,10 +1183,26 @@ auth:
     values:
       opensearch_admin_username: "admin"
       opensearch_admin_password: "OnyxDev1!"
+  userauth:
+    # -- Used for signing password reset tokens, email verification tokens, and JWT tokens.
+    enabled: true
+    # -- Overwrite the default secret name, ignored if existingSecret is defined
+    secretName: 'onyx-userauth'
+    # -- Use a secret specified elsewhere
+    existingSecret: ""
+    # -- This defines the env var to secret map
+    secretKeys:
+      USER_AUTH_SECRET: user_auth_secret
+    # -- Secret value. Required - generate with: openssl rand -hex 32
+    # If not set, helm install/upgrade will fail.
+    values:
+      user_auth_secret: ""
 
 configMap:
-  # Change this for production uses unless Onyx is only accessible behind VPN
-  AUTH_TYPE: "disabled"
+  # Auth type: "basic" (default), "google_oauth", "oidc", or "saml"
+  # UPGRADE NOTE: Default changed from "disabled" to "basic" in 0.4.34.
+  # You must also set auth.userauth.values.user_auth_secret.
+  AUTH_TYPE: "basic"
   # 1 Day Default
   SESSION_EXPIRE_TIME_SECONDS: "86400"
   # Can be something like onyx.app, as an extra double-check

From 11f8408558730c1933ea5a3e348b9ff7afd5fa6b Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Thu, 12 Mar 2026 14:33:57 -0700
Subject: [PATCH 258/267] feat(admin): add inline role editing in Users table -
 7/9 (#9184)

---
 .../buttons/open-button/components.tsx        |  47 +++++--
 .../core/interactive/stateful/components.tsx  |   6 +-
 .../src/core/interactive/stateful/styles.css  |  99 ++++++++++++-
 .../admin/UsersPage/UserRoleCell.tsx          | 133 ++++++++++++++++++
 .../admin/UsersPage/UsersTable.tsx            |  45 +-----
 web/src/refresh-pages/admin/UsersPage/svc.ts  |  16 +++
 6 files changed, 291 insertions(+), 55 deletions(-)
 create mode 100644 web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx

diff --git a/web/lib/opal/src/components/buttons/open-button/components.tsx b/web/lib/opal/src/components/buttons/open-button/components.tsx
index 40ea4597e82..c5cfbb819d5 100644
--- a/web/lib/opal/src/components/buttons/open-button/components.tsx
+++ b/web/lib/opal/src/components/buttons/open-button/components.tsx
@@ -55,8 +55,11 @@ type OpenButtonContentProps =
       children?: string;
     };
 
-type OpenButtonProps = Omit<InteractiveStatefulProps, "variant"> &
-  OpenButtonContentProps & {
+type OpenButtonVariant = "select-light" | "select-heavy" | "select-tinted";
+
+type OpenButtonProps = Omit<InteractiveStatefulProps, "variant"> & {
+  variant?: OpenButtonVariant;
+} & OpenButtonContentProps & {
     /**
      * Size preset — controls gap, text size, and Container height/rounding.
      */
@@ -65,6 +68,13 @@ type OpenButtonProps = Omit<InteractiveStatefulProps, "variant"> &
     /** Width preset. */
     width?: WidthVariant;
 
+    /**
+     * Content justify mode. When `"between"`, icon+label group left and
+     * chevron pushes to the right edge. Default keeps all items in a
+     * tight `gap-1` row.
+     */
+    justifyContent?: "between";
+
     /** Tooltip text shown on hover. */
     tooltip?: string;
 
@@ -82,9 +92,11 @@ function OpenButton({
   size = "lg",
   foldable,
   width,
+  justifyContent,
   tooltip,
   tooltipSide = "top",
   interaction,
+  variant = "select-heavy",
   ...statefulProps
 }: OpenButtonProps) {
   const { isDisabled } = useDisabled();
@@ -111,7 +123,7 @@ function OpenButton({
 
   const button = (
     <Interactive.Stateful
-      variant="select-heavy"
+      variant={variant}
       interaction={resolvedInteraction}
       {...statefulProps}
     >
@@ -125,19 +137,32 @@ function OpenButton({
       >
         <div
           className={cn(
-            "opal-button interactive-foreground flex flex-row items-center gap-1",
-            foldable && "interactive-foldable-host"
+            "opal-button interactive-foreground flex flex-row items-center",
+            justifyContent === "between" ? "w-full justify-between" : "gap-1",
+            foldable &&
+              justifyContent !== "between" &&
+              "interactive-foldable-host"
           )}
         >
-          {iconWrapper(Icon, size, !foldable && !!children)}
-
-          {foldable ? (
-            <Interactive.Foldable>
-              {labelEl}
+          {justifyContent === "between" ? (
+            <>
+              <span className="flex flex-row items-center gap-1">
+                {iconWrapper(Icon, size, !foldable && !!children)}
+                {labelEl}
+              </span>
               {iconWrapper(ChevronIcon, size, !!children)}
-            </Interactive.Foldable>
+            </>
+          ) : foldable ? (
+            <>
+              {iconWrapper(Icon, size, !foldable && !!children)}
+              <Interactive.Foldable>
+                {labelEl}
+                {iconWrapper(ChevronIcon, size, !!children)}
+              </Interactive.Foldable>
+            </>
           ) : (
             <>
+              {iconWrapper(Icon, size, !foldable && !!children)}
               {labelEl}
               {iconWrapper(ChevronIcon, size, !!children)}
             </>
diff --git a/web/lib/opal/src/core/interactive/stateful/components.tsx b/web/lib/opal/src/core/interactive/stateful/components.tsx
index 5a7d3f11a85..6f49b3281a3 100644
--- a/web/lib/opal/src/core/interactive/stateful/components.tsx
+++ b/web/lib/opal/src/core/interactive/stateful/components.tsx
@@ -10,7 +10,11 @@ import type { WithoutStyles } from "@opal/types";
 // Types
 // ---------------------------------------------------------------------------
 
-type InteractiveStatefulVariant = "select-light" | "select-heavy" | "sidebar";
+type InteractiveStatefulVariant =
+  | "select-light"
+  | "select-heavy"
+  | "select-tinted"
+  | "sidebar";
 type InteractiveStatefulState = "empty" | "filled" | "selected";
 type InteractiveStatefulInteraction = "rest" | "hover" | "active";
 
diff --git a/web/lib/opal/src/core/interactive/stateful/styles.css b/web/lib/opal/src/core/interactive/stateful/styles.css
index 59232abda93..56949275c7a 100644
--- a/web/lib/opal/src/core/interactive/stateful/styles.css
+++ b/web/lib/opal/src/core/interactive/stateful/styles.css
@@ -11,7 +11,7 @@
    Children read the variables with no independent transitions.
 
    State dimension: `data-interactive-state` = "empty" | "filled" | "selected"
-   Variant dimension: `data-interactive-variant` = "select-light" | "select-heavy" | "sidebar"
+   Variant dimension: `data-interactive-variant` = "select-light" | "select-heavy" | "select-tinted" | "sidebar"
 
    Interaction override: `data-interaction="hover"` and `data-interaction="active"`
    allow JS-controlled visual state overrides.
@@ -211,6 +211,103 @@
   --interactive-foreground-icon: var(--action-link-03);
 }
 
+/* ===========================================================================
+   Select-Tinted — like Select-Heavy but with a tinted rest background
+   =========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Select-Tinted — Empty
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="empty"] {
+  @apply bg-background-tint-01;
+  --interactive-foreground: var(--text-04);
+  --interactive-foreground-icon: var(--text-03);
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="empty"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="empty"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+  --interactive-foreground-icon: var(--text-04);
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="empty"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="empty"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-neutral-00;
+  --interactive-foreground: var(--text-05);
+  --interactive-foreground-icon: var(--text-05);
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="empty"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Select-Tinted — Filled
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="filled"] {
+  @apply bg-background-tint-01;
+  --interactive-foreground: var(--action-link-05);
+  --interactive-foreground-icon: var(--action-link-05);
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="filled"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="filled"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="filled"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="filled"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="filled"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--text-01);
+  --interactive-foreground-icon: var(--text-01);
+}
+
+/* ---------------------------------------------------------------------------
+   Select-Tinted — Selected
+   --------------------------------------------------------------------------- */
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="selected"] {
+  @apply bg-[var(--action-link-01)];
+  --interactive-foreground: var(--action-link-05);
+  --interactive-foreground-icon: var(--action-link-05);
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="selected"]:hover:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="selected"][data-interaction="hover"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-02;
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="selected"]:active:not(
+    [data-disabled]
+  ),
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="selected"][data-interaction="active"]:not(
+    [data-disabled]
+  ) {
+  @apply bg-background-tint-00;
+}
+.interactive[data-interactive-variant="select-tinted"][data-interactive-state="selected"][data-disabled] {
+  @apply bg-transparent;
+  --interactive-foreground: var(--action-link-03);
+  --interactive-foreground-icon: var(--action-link-03);
+}
+
 /* ===========================================================================
    Sidebar
    =========================================================================== */
diff --git a/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx b/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx
new file mode 100644
index 00000000000..77607a823a8
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx
@@ -0,0 +1,133 @@
+"use client";
+
+import { useState, useRef } from "react";
+import { UserRole, USER_ROLE_LABELS } from "@/lib/types";
+import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
+import { OpenButton } from "@opal/components";
+import { Disabled } from "@opal/core";
+import {
+  SvgCheck,
+  SvgGlobe,
+  SvgUser,
+  SvgSlack,
+  SvgUserManage,
+} from "@opal/icons";
+import type { IconFunctionComponent } from "@opal/types";
+import Text from "@/refresh-components/texts/Text";
+import Popover from "@/refresh-components/Popover";
+import LineItem from "@/refresh-components/buttons/LineItem";
+import { toast } from "@/hooks/useToast";
+import { setUserRole } from "./svc";
+import type { UserRow } from "./interfaces";
+
+const ROLE_ICONS: Partial<Record<UserRole, IconFunctionComponent>> = {
+  [UserRole.ADMIN]: SvgUserManage,
+  [UserRole.GLOBAL_CURATOR]: SvgGlobe,
+  [UserRole.SLACK_USER]: SvgSlack,
+};
+
+const SELECTABLE_ROLES = [
+  UserRole.ADMIN,
+  UserRole.GLOBAL_CURATOR,
+  UserRole.BASIC,
+] as const;
+
+interface UserRoleCellProps {
+  user: UserRow;
+  onMutate: () => void;
+}
+
+export default function UserRoleCell({ user, onMutate }: UserRoleCellProps) {
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [open, setOpen] = useState(false);
+  const isPaidEnterpriseFeaturesEnabled = usePaidEnterpriseFeaturesEnabled();
+  const isUpdatingRef = useRef(false);
+
+  if (!user.role) {
+    return (
+      <Text as="span" secondaryBody text03>
+        —
+      </Text>
+    );
+  }
+
+  if (user.is_scim_synced) {
+    return (
+      <div className="flex items-center gap-1.5">
+        <Text as="span" mainUiBody text03>
+          {USER_ROLE_LABELS[user.role] ?? user.role}
+        </Text>
+      </div>
+    );
+  }
+
+  const applyRole = async (newRole: UserRole) => {
+    if (isUpdatingRef.current) return;
+    isUpdatingRef.current = true;
+    setIsUpdating(true);
+    try {
+      await setUserRole(user.email, newRole);
+      toast.success("Role updated");
+      onMutate();
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "Failed to update role");
+      onMutate();
+    } finally {
+      setIsUpdating(false);
+      isUpdatingRef.current = false;
+    }
+  };
+
+  const handleSelect = (role: UserRole) => {
+    if (role === user.role) {
+      setOpen(false);
+      return;
+    }
+    setOpen(false);
+    void applyRole(role);
+  };
+
+  const currentIcon = ROLE_ICONS[user.role] ?? SvgUser;
+
+  return (
+    <Disabled disabled={isUpdating}>
+      <Popover open={open} onOpenChange={setOpen}>
+        <Popover.Trigger asChild>
+          <OpenButton
+            icon={currentIcon}
+            variant="select-tinted"
+            width="full"
+            justifyContent="between"
+          >
+            {USER_ROLE_LABELS[user.role]}
+          </OpenButton>
+        </Popover.Trigger>
+        <Popover.Content align="start">
+          <div className="flex flex-col gap-1 p-1 min-w-[160px]">
+            {SELECTABLE_ROLES.map((role) => {
+              if (
+                role === UserRole.GLOBAL_CURATOR &&
+                !isPaidEnterpriseFeaturesEnabled
+              ) {
+                return null;
+              }
+              const isSelected = user.role === role;
+              const icon = ROLE_ICONS[role] ?? SvgUser;
+              return (
+                <LineItem
+                  key={role}
+                  icon={isSelected ? SvgCheck : icon}
+                  selected={isSelected}
+                  emphasized={isSelected}
+                  onClick={() => handleSelect(role)}
+                >
+                  {USER_ROLE_LABELS[role]}
+                </LineItem>
+              );
+            })}
+          </div>
+        </Popover.Content>
+      </Popover>
+    </Disabled>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
index bcdb1b1cb80..0ad9cdb3c7e 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
@@ -4,17 +4,10 @@ import { useMemo, useState } from "react";
 import DataTable from "@/refresh-components/table/DataTable";
 import { createTableColumns } from "@/refresh-components/table/columns";
 import { Content } from "@opal/layouts";
-import { SvgUser, SvgUsers, SvgSlack } from "@opal/icons";
 import SvgNoResult from "@opal/illustrations/no-result";
 import { IllustrationContent } from "@opal/layouts";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
-import type { IconFunctionComponent } from "@opal/types";
-import {
-  UserRole,
-  UserStatus,
-  USER_ROLE_LABELS,
-  USER_STATUS_LABELS,
-} from "@/lib/types";
+import { UserRole, UserStatus, USER_STATUS_LABELS } from "@/lib/types";
 import { timeAgo } from "@/lib/time";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
@@ -22,6 +15,7 @@ import useAdminUsers from "@/hooks/useAdminUsers";
 import useGroups from "@/hooks/useGroups";
 import UserFilters from "./UserFilters";
 import UserRowActions from "./UserRowActions";
+import UserRoleCell from "./UserRoleCell";
 import type {
   UserRow,
   UserGroupInfo,
@@ -31,20 +25,6 @@ import type {
 } from "./interfaces";
 import { getInitials } from "./utils";
 
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const ROLE_ICONS: Record<UserRole, IconFunctionComponent> = {
-  [UserRole.BASIC]: SvgUser,
-  [UserRole.ADMIN]: SvgUser,
-  [UserRole.GLOBAL_CURATOR]: SvgUsers,
-  [UserRole.CURATOR]: SvgUsers,
-  [UserRole.LIMITED]: SvgUser,
-  [UserRole.EXT_PERM_USER]: SvgUser,
-  [UserRole.SLACK_USER]: SvgSlack,
-};
-
 // ---------------------------------------------------------------------------
 // Column renderers
 // ---------------------------------------------------------------------------
@@ -91,25 +71,6 @@ function renderGroupsColumn(groups: UserGroupInfo[]) {
   );
 }
 
-function renderRoleColumn(role: UserRole | null) {
-  if (!role) {
-    return (
-      <Text as="span" secondaryBody text03>
-        —
-      </Text>
-    );
-  }
-  const Icon = ROLE_ICONS[role];
-  return (
-    <div className="flex items-center gap-1.5">
-      {Icon && <Icon size={14} className="text-text-03 shrink-0" />}
-      <Text as="span" mainUiBody text03>
-        {USER_ROLE_LABELS[role] ?? role}
-      </Text>
-    </div>
-  );
-}
-
 function renderStatusColumn(value: UserStatus, row: UserRow) {
   return (
     <div className="flex flex-col">
@@ -163,7 +124,7 @@ function buildColumns(onMutate: () => void) {
       header: "Account Type",
       weight: 16,
       minWidth: 180,
-      cell: renderRoleColumn,
+      cell: (_value, row) => <UserRoleCell user={row} onMutate={onMutate} />,
     }),
     tc.column("status", {
       header: "Status",
diff --git a/web/src/refresh-pages/admin/UsersPage/svc.ts b/web/src/refresh-pages/admin/UsersPage/svc.ts
index dd2e9d1dba8..8d010745d0c 100644
--- a/web/src/refresh-pages/admin/UsersPage/svc.ts
+++ b/web/src/refresh-pages/admin/UsersPage/svc.ts
@@ -1,3 +1,5 @@
+import { UserRole } from "@/lib/types";
+
 async function parseErrorDetail(
   res: Response,
   fallback: string
@@ -43,6 +45,20 @@ export async function deleteUser(email: string): Promise<void> {
   }
 }
 
+export async function setUserRole(
+  email: string,
+  newRole: UserRole
+): Promise<void> {
+  const res = await fetch("/api/manage/set-user-role", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ user_email: email, new_role: newRole }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to update user role"));
+  }
+}
+
 export async function inviteUsers(emails: string[]): Promise<void> {
   const res = await fetch("/api/manage/admin/users", {
     method: "PUT",

From 8a6e349741d3894f267668b8540e05ca7eebf72f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 12 Mar 2026 22:17:56 +0000
Subject: [PATCH 259/267] chore(deps): bump orjson from 3.11.4 to 3.11.6
 (#9315)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jamison Lahman <jamison@lahman.dev>
---
 backend/requirements/default.txt |   2 +-
 uv.lock                          | 128 +++++++++++++++----------------
 2 files changed, 65 insertions(+), 65 deletions(-)

diff --git a/backend/requirements/default.txt b/backend/requirements/default.txt
index b17258a0c4e..629139991a1 100644
--- a/backend/requirements/default.txt
+++ b/backend/requirements/default.txt
@@ -614,7 +614,7 @@ opentelemetry-sdk==1.39.1
     #   opentelemetry-exporter-otlp-proto-http
 opentelemetry-semantic-conventions==0.60b1
     # via opentelemetry-sdk
-orjson==3.11.4 ; platform_python_implementation != 'PyPy'
+orjson==3.11.6 ; platform_python_implementation != 'PyPy'
     # via langsmith
 packaging==24.2
     # via
diff --git a/uv.lock b/uv.lock
index 76f5603dc3c..add43429359 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4739,70 +4739,70 @@ wheels = [
 
 [[package]]
 name = "orjson"
-version = "3.11.4"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c6/fe/ed708782d6709cc60eb4c2d8a361a440661f74134675c72990f2c48c785f/orjson-3.11.4.tar.gz", hash = "sha256:39485f4ab4c9b30a3943cfe99e1a213c4776fb69e8abd68f66b83d5a0b0fdc6d", size = 5945188, upload-time = "2025-10-24T15:50:38.027Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/63/1d/1ea6005fffb56715fd48f632611e163d1604e8316a5bad2288bee9a1c9eb/orjson-3.11.4-cp311-cp311-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:5e59d23cd93ada23ec59a96f215139753fbfe3a4d989549bcb390f8c00370b39", size = 243498, upload-time = "2025-10-24T15:48:48.101Z" },
-    { url = "https://files.pythonhosted.org/packages/37/d7/ffed10c7da677f2a9da307d491b9eb1d0125b0307019c4ad3d665fd31f4f/orjson-3.11.4-cp311-cp311-macosx_15_0_arm64.whl", hash = "sha256:5c3aedecfc1beb988c27c79d52ebefab93b6c3921dbec361167e6559aba2d36d", size = 128961, upload-time = "2025-10-24T15:48:49.571Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/96/3e4d10a18866d1368f73c8c44b7fe37cc8a15c32f2a7620be3877d4c55a3/orjson-3.11.4-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:da9e5301f1c2caa2a9a4a303480d79c9ad73560b2e7761de742ab39fe59d9175", size = 130321, upload-time = "2025-10-24T15:48:50.713Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/1f/465f66e93f434f968dd74d5b623eb62c657bdba2332f5a8be9f118bb74c7/orjson-3.11.4-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8873812c164a90a79f65368f8f96817e59e35d0cc02786a5356f0e2abed78040", size = 129207, upload-time = "2025-10-24T15:48:52.193Z" },
-    { url = "https://files.pythonhosted.org/packages/28/43/d1e94837543321c119dff277ae8e348562fe8c0fafbb648ef7cb0c67e521/orjson-3.11.4-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:5d7feb0741ebb15204e748f26c9638e6665a5fa93c37a2c73d64f1669b0ddc63", size = 136323, upload-time = "2025-10-24T15:48:54.806Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/04/93303776c8890e422a5847dd012b4853cdd88206b8bbd3edc292c90102d1/orjson-3.11.4-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:01ee5487fefee21e6910da4c2ee9eef005bee568a0879834df86f888d2ffbdd9", size = 137440, upload-time = "2025-10-24T15:48:56.326Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/ef/75519d039e5ae6b0f34d0336854d55544ba903e21bf56c83adc51cd8bf82/orjson-3.11.4-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3d40d46f348c0321df01507f92b95a377240c4ec31985225a6668f10e2676f9a", size = 136680, upload-time = "2025-10-24T15:48:57.476Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/18/bf8581eaae0b941b44efe14fee7b7862c3382fbc9a0842132cfc7cf5ecf4/orjson-3.11.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:95713e5fc8af84d8edc75b785d2386f653b63d62b16d681687746734b4dfc0be", size = 136160, upload-time = "2025-10-24T15:48:59.631Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/35/a6d582766d351f87fc0a22ad740a641b0a8e6fc47515e8614d2e4790ae10/orjson-3.11.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ad73ede24f9083614d6c4ca9a85fe70e33be7bf047ec586ee2363bc7418fe4d7", size = 140318, upload-time = "2025-10-24T15:49:00.834Z" },
-    { url = "https://files.pythonhosted.org/packages/76/b3/5a4801803ab2e2e2d703bce1a56540d9f99a9143fbec7bf63d225044fef8/orjson-3.11.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:842289889de515421f3f224ef9c1f1efb199a32d76d8d2ca2706fa8afe749549", size = 406330, upload-time = "2025-10-24T15:49:02.327Z" },
-    { url = "https://files.pythonhosted.org/packages/80/55/a8f682f64833e3a649f620eafefee175cbfeb9854fc5b710b90c3bca45df/orjson-3.11.4-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:3b2427ed5791619851c52a1261b45c233930977e7de8cf36de05636c708fa905", size = 149580, upload-time = "2025-10-24T15:49:03.517Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/e4/c132fa0c67afbb3eb88274fa98df9ac1f631a675e7877037c611805a4413/orjson-3.11.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:3c36e524af1d29982e9b190573677ea02781456b2e537d5840e4538a5ec41907", size = 139846, upload-time = "2025-10-24T15:49:04.761Z" },
-    { url = "https://files.pythonhosted.org/packages/54/06/dc3491489efd651fef99c5908e13951abd1aead1257c67f16135f95ce209/orjson-3.11.4-cp311-cp311-win32.whl", hash = "sha256:87255b88756eab4a68ec61837ca754e5d10fa8bc47dc57f75cedfeaec358d54c", size = 135781, upload-time = "2025-10-24T15:49:05.969Z" },
-    { url = "https://files.pythonhosted.org/packages/79/b7/5e5e8d77bd4ea02a6ac54c42c818afb01dd31961be8a574eb79f1d2cfb1e/orjson-3.11.4-cp311-cp311-win_amd64.whl", hash = "sha256:e2d5d5d798aba9a0e1fede8d853fa899ce2cb930ec0857365f700dffc2c7af6a", size = 131391, upload-time = "2025-10-24T15:49:07.355Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/dc/9484127cc1aa213be398ed735f5f270eedcb0c0977303a6f6ddc46b60204/orjson-3.11.4-cp311-cp311-win_arm64.whl", hash = "sha256:6bb6bb41b14c95d4f2702bce9975fda4516f1db48e500102fc4d8119032ff045", size = 126252, upload-time = "2025-10-24T15:49:08.869Z" },
-    { url = "https://files.pythonhosted.org/packages/63/51/6b556192a04595b93e277a9ff71cd0cc06c21a7df98bcce5963fa0f5e36f/orjson-3.11.4-cp312-cp312-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:d4371de39319d05d3f482f372720b841c841b52f5385bd99c61ed69d55d9ab50", size = 243571, upload-time = "2025-10-24T15:49:10.008Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/2c/2602392ddf2601d538ff11848b98621cd465d1a1ceb9db9e8043181f2f7b/orjson-3.11.4-cp312-cp312-macosx_15_0_arm64.whl", hash = "sha256:e41fd3b3cac850eaae78232f37325ed7d7436e11c471246b87b2cd294ec94853", size = 128891, upload-time = "2025-10-24T15:49:11.297Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/47/bf85dcf95f7a3a12bf223394a4f849430acd82633848d52def09fa3f46ad/orjson-3.11.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:600e0e9ca042878c7fdf189cf1b028fe2c1418cc9195f6cb9824eb6ed99cb938", size = 130137, upload-time = "2025-10-24T15:49:12.544Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/4d/a0cb31007f3ab6f1fd2a1b17057c7c349bc2baf8921a85c0180cc7be8011/orjson-3.11.4-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7bbf9b333f1568ef5da42bc96e18bf30fd7f8d54e9ae066d711056add508e415", size = 129152, upload-time = "2025-10-24T15:49:13.754Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/ef/2811def7ce3d8576b19e3929fff8f8f0d44bc5eb2e0fdecb2e6e6cc6c720/orjson-3.11.4-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4806363144bb6e7297b8e95870e78d30a649fdc4e23fc84daa80c8ebd366ce44", size = 136834, upload-time = "2025-10-24T15:49:15.307Z" },
-    { url = "https://files.pythonhosted.org/packages/00/d4/9aee9e54f1809cec8ed5abd9bc31e8a9631d19460e3b8470145d25140106/orjson-3.11.4-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ad355e8308493f527d41154e9053b86a5be892b3b359a5c6d5d95cda23601cb2", size = 137519, upload-time = "2025-10-24T15:49:16.557Z" },
-    { url = "https://files.pythonhosted.org/packages/db/ea/67bfdb5465d5679e8ae8d68c11753aaf4f47e3e7264bad66dc2f2249e643/orjson-3.11.4-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c8a7517482667fb9f0ff1b2f16fe5829296ed7a655d04d68cd9711a4d8a4e708", size = 136749, upload-time = "2025-10-24T15:49:17.796Z" },
-    { url = "https://files.pythonhosted.org/packages/01/7e/62517dddcfce6d53a39543cd74d0dccfcbdf53967017c58af68822100272/orjson-3.11.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:97eb5942c7395a171cbfecc4ef6701fc3c403e762194683772df4c54cfbb2210", size = 136325, upload-time = "2025-10-24T15:49:19.347Z" },
-    { url = "https://files.pythonhosted.org/packages/18/ae/40516739f99ab4c7ec3aaa5cc242d341fcb03a45d89edeeaabc5f69cb2cf/orjson-3.11.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:149d95d5e018bdd822e3f38c103b1a7c91f88d38a88aada5c4e9b3a73a244241", size = 140204, upload-time = "2025-10-24T15:49:20.545Z" },
-    { url = "https://files.pythonhosted.org/packages/82/18/ff5734365623a8916e3a4037fcef1cd1782bfc14cf0992afe7940c5320bf/orjson-3.11.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:624f3951181eb46fc47dea3d221554e98784c823e7069edb5dbd0dc826ac909b", size = 406242, upload-time = "2025-10-24T15:49:21.884Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/43/96436041f0a0c8c8deca6a05ebeaf529bf1de04839f93ac5e7c479807aec/orjson-3.11.4-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:03bfa548cf35e3f8b3a96c4e8e41f753c686ff3d8e182ce275b1751deddab58c", size = 150013, upload-time = "2025-10-24T15:49:23.185Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/48/78302d98423ed8780479a1e682b9aecb869e8404545d999d34fa486e573e/orjson-3.11.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:525021896afef44a68148f6ed8a8bf8375553d6066c7f48537657f64823565b9", size = 139951, upload-time = "2025-10-24T15:49:24.428Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/7b/ad613fdcdaa812f075ec0875143c3d37f8654457d2af17703905425981bf/orjson-3.11.4-cp312-cp312-win32.whl", hash = "sha256:b58430396687ce0f7d9eeb3dd47761ca7d8fda8e9eb92b3077a7a353a75efefa", size = 136049, upload-time = "2025-10-24T15:49:25.973Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/3c/9cf47c3ff5f39b8350fb21ba65d789b6a1129d4cbb3033ba36c8a9023520/orjson-3.11.4-cp312-cp312-win_amd64.whl", hash = "sha256:c6dbf422894e1e3c80a177133c0dda260f81428f9de16d61041949f6a2e5c140", size = 131461, upload-time = "2025-10-24T15:49:27.259Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/3b/e2425f61e5825dc5b08c2a5a2b3af387eaaca22a12b9c8c01504f8614c36/orjson-3.11.4-cp312-cp312-win_arm64.whl", hash = "sha256:d38d2bc06d6415852224fcc9c0bfa834c25431e466dc319f0edd56cca81aa96e", size = 126167, upload-time = "2025-10-24T15:49:28.511Z" },
-    { url = "https://files.pythonhosted.org/packages/23/15/c52aa7112006b0f3d6180386c3a46ae057f932ab3425bc6f6ac50431cca1/orjson-3.11.4-cp313-cp313-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:2d6737d0e616a6e053c8b4acc9eccea6b6cce078533666f32d140e4f85002534", size = 243525, upload-time = "2025-10-24T15:49:29.737Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/38/05340734c33b933fd114f161f25a04e651b0c7c33ab95e9416ade5cb44b8/orjson-3.11.4-cp313-cp313-macosx_15_0_arm64.whl", hash = "sha256:afb14052690aa328cc118a8e09f07c651d301a72e44920b887c519b313d892ff", size = 128871, upload-time = "2025-10-24T15:49:31.109Z" },
-    { url = "https://files.pythonhosted.org/packages/55/b9/ae8d34899ff0c012039b5a7cb96a389b2476e917733294e498586b45472d/orjson-3.11.4-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:38aa9e65c591febb1b0aed8da4d469eba239d434c218562df179885c94e1a3ad", size = 130055, upload-time = "2025-10-24T15:49:33.382Z" },
-    { url = "https://files.pythonhosted.org/packages/33/aa/6346dd5073730451bee3681d901e3c337e7ec17342fb79659ec9794fc023/orjson-3.11.4-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f2cf4dfaf9163b0728d061bebc1e08631875c51cd30bf47cb9e3293bfbd7dcd5", size = 129061, upload-time = "2025-10-24T15:49:34.935Z" },
-    { url = "https://files.pythonhosted.org/packages/39/e4/8eea51598f66a6c853c380979912d17ec510e8e66b280d968602e680b942/orjson-3.11.4-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:89216ff3dfdde0e4070932e126320a1752c9d9a758d6a32ec54b3b9334991a6a", size = 136541, upload-time = "2025-10-24T15:49:36.923Z" },
-    { url = "https://files.pythonhosted.org/packages/9a/47/cb8c654fa9adcc60e99580e17c32b9e633290e6239a99efa6b885aba9dbc/orjson-3.11.4-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9daa26ca8e97fae0ce8aa5d80606ef8f7914e9b129b6b5df9104266f764ce436", size = 137535, upload-time = "2025-10-24T15:49:38.307Z" },
-    { url = "https://files.pythonhosted.org/packages/43/92/04b8cc5c2b729f3437ee013ce14a60ab3d3001465d95c184758f19362f23/orjson-3.11.4-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5c8b2769dc31883c44a9cd126560327767f848eb95f99c36c9932f51090bfce9", size = 136703, upload-time = "2025-10-24T15:49:40.795Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/fd/d0733fcb9086b8be4ebcfcda2d0312865d17d0d9884378b7cffb29d0763f/orjson-3.11.4-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1469d254b9884f984026bd9b0fa5bbab477a4bfe558bba6848086f6d43eb5e73", size = 136293, upload-time = "2025-10-24T15:49:42.347Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/d7/3c5514e806837c210492d72ae30ccf050ce3f940f45bf085bab272699ef4/orjson-3.11.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:68e44722541983614e37117209a194e8c3ad07838ccb3127d96863c95ec7f1e0", size = 140131, upload-time = "2025-10-24T15:49:43.638Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/dd/ba9d32a53207babf65bd510ac4d0faaa818bd0df9a9c6f472fe7c254f2e3/orjson-3.11.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:8e7805fda9672c12be2f22ae124dcd7b03928d6c197544fe12174b86553f3196", size = 406164, upload-time = "2025-10-24T15:49:45.498Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/f9/f68ad68f4af7c7bde57cd514eaa2c785e500477a8bc8f834838eb696a685/orjson-3.11.4-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:04b69c14615fb4434ab867bf6f38b2d649f6f300af30a6705397e895f7aec67a", size = 149859, upload-time = "2025-10-24T15:49:46.981Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/d2/7f847761d0c26818395b3d6b21fb6bc2305d94612a35b0a30eae65a22728/orjson-3.11.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:639c3735b8ae7f970066930e58cf0ed39a852d417c24acd4a25fc0b3da3c39a6", size = 139926, upload-time = "2025-10-24T15:49:48.321Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/37/acd14b12dc62db9a0e1d12386271b8661faae270b22492580d5258808975/orjson-3.11.4-cp313-cp313-win32.whl", hash = "sha256:6c13879c0d2964335491463302a6ca5ad98105fc5db3565499dcb80b1b4bd839", size = 136007, upload-time = "2025-10-24T15:49:49.938Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/a9/967be009ddf0a1fffd7a67de9c36656b28c763659ef91352acc02cbe364c/orjson-3.11.4-cp313-cp313-win_amd64.whl", hash = "sha256:09bf242a4af98732db9f9a1ec57ca2604848e16f132e3f72edfd3c5c96de009a", size = 131314, upload-time = "2025-10-24T15:49:51.248Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/db/399abd6950fbd94ce125cb8cd1a968def95174792e127b0642781e040ed4/orjson-3.11.4-cp313-cp313-win_arm64.whl", hash = "sha256:a85f0adf63319d6c1ba06fb0dbf997fced64a01179cf17939a6caca662bf92de", size = 126152, upload-time = "2025-10-24T15:49:52.922Z" },
-    { url = "https://files.pythonhosted.org/packages/25/e3/54ff63c093cc1697e758e4fceb53164dd2661a7d1bcd522260ba09f54533/orjson-3.11.4-cp314-cp314-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:42d43a1f552be1a112af0b21c10a5f553983c2a0938d2bbb8ecd8bc9fb572803", size = 243501, upload-time = "2025-10-24T15:49:54.288Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/7d/e2d1076ed2e8e0ae9badca65bf7ef22710f93887b29eaa37f09850604e09/orjson-3.11.4-cp314-cp314-macosx_15_0_arm64.whl", hash = "sha256:26a20f3fbc6c7ff2cb8e89c4c5897762c9d88cf37330c6a117312365d6781d54", size = 128862, upload-time = "2025-10-24T15:49:55.961Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/37/ca2eb40b90621faddfa9517dfe96e25f5ae4d8057a7c0cdd613c17e07b2c/orjson-3.11.4-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6e3f20be9048941c7ffa8fc523ccbd17f82e24df1549d1d1fe9317712d19938e", size = 130047, upload-time = "2025-10-24T15:49:57.406Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/62/1021ed35a1f2bad9040f05fa4cc4f9893410df0ba3eaa323ccf899b1c90a/orjson-3.11.4-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:aac364c758dc87a52e68e349924d7e4ded348dedff553889e4d9f22f74785316", size = 129073, upload-time = "2025-10-24T15:49:58.782Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/3f/f84d966ec2a6fd5f73b1a707e7cd876813422ae4bf9f0145c55c9c6a0f57/orjson-3.11.4-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d5c54a6d76e3d741dcc3f2707f8eeb9ba2a791d3adbf18f900219b62942803b1", size = 136597, upload-time = "2025-10-24T15:50:00.12Z" },
-    { url = "https://files.pythonhosted.org/packages/32/78/4fa0aeca65ee82bbabb49e055bd03fa4edea33f7c080c5c7b9601661ef72/orjson-3.11.4-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f28485bdca8617b79d44627f5fb04336897041dfd9fa66d383a49d09d86798bc", size = 137515, upload-time = "2025-10-24T15:50:01.57Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/9d/0c102e26e7fde40c4c98470796d050a2ec1953897e2c8ab0cb95b0759fa2/orjson-3.11.4-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bfc2a484cad3585e4ba61985a6062a4c2ed5c7925db6d39f1fa267c9d166487f", size = 136703, upload-time = "2025-10-24T15:50:02.944Z" },
-    { url = "https://files.pythonhosted.org/packages/df/ac/2de7188705b4cdfaf0b6c97d2f7849c17d2003232f6e70df98602173f788/orjson-3.11.4-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e34dbd508cb91c54f9c9788923daca129fe5b55c5b4eebe713bf5ed3791280cf", size = 136311, upload-time = "2025-10-24T15:50:04.441Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/52/847fcd1a98407154e944feeb12e3b4d487a0e264c40191fb44d1269cbaa1/orjson-3.11.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:b13c478fa413d4b4ee606ec8e11c3b2e52683a640b006bb586b3041c2ca5f606", size = 140127, upload-time = "2025-10-24T15:50:07.398Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/ae/21d208f58bdb847dd4d0d9407e2929862561841baa22bdab7aea10ca088e/orjson-3.11.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:724ca721ecc8a831b319dcd72cfa370cc380db0bf94537f08f7edd0a7d4e1780", size = 406201, upload-time = "2025-10-24T15:50:08.796Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/55/0789d6de386c8366059db098a628e2ad8798069e94409b0d8935934cbcb9/orjson-3.11.4-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:977c393f2e44845ce1b540e19a786e9643221b3323dae190668a98672d43fb23", size = 149872, upload-time = "2025-10-24T15:50:10.234Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/1d/7ff81ea23310e086c17b41d78a72270d9de04481e6113dbe2ac19118f7fb/orjson-3.11.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:1e539e382cf46edec157ad66b0b0872a90d829a6b71f17cb633d6c160a223155", size = 139931, upload-time = "2025-10-24T15:50:11.623Z" },
-    { url = "https://files.pythonhosted.org/packages/77/92/25b886252c50ed64be68c937b562b2f2333b45afe72d53d719e46a565a50/orjson-3.11.4-cp314-cp314-win32.whl", hash = "sha256:d63076d625babab9db5e7836118bdfa086e60f37d8a174194ae720161eb12394", size = 136065, upload-time = "2025-10-24T15:50:13.025Z" },
-    { url = "https://files.pythonhosted.org/packages/63/b8/718eecf0bb7e9d64e4956afaafd23db9f04c776d445f59fe94f54bdae8f0/orjson-3.11.4-cp314-cp314-win_amd64.whl", hash = "sha256:0a54d6635fa3aaa438ae32e8570b9f0de36f3f6562c308d2a2a452e8b0592db1", size = 131310, upload-time = "2025-10-24T15:50:14.46Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/bf/def5e25d4d8bfce296a9a7c8248109bf58622c21618b590678f945a2c59c/orjson-3.11.4-cp314-cp314-win_arm64.whl", hash = "sha256:78b999999039db3cf58f6d230f524f04f75f129ba3d1ca2ed121f8657e575d3d", size = 126151, upload-time = "2025-10-24T15:50:15.878Z" },
+version = "3.11.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/70/a3/4e09c61a5f0c521cba0bb433639610ae037437669f1a4cbc93799e731d78/orjson-3.11.6.tar.gz", hash = "sha256:0a54c72259f35299fd033042367df781c2f66d10252955ca1efb7db309b954cb", size = 6175856, upload-time = "2026-01-29T15:13:07.942Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f3/fd/d6b0a36854179b93ed77839f107c4089d91cccc9f9ba1b752b6e3bac5f34/orjson-3.11.6-cp311-cp311-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:e259e85a81d76d9665f03d6129e09e4435531870de5961ddcd0bf6e3a7fde7d7", size = 250029, upload-time = "2026-01-29T15:11:35.942Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/bb/22902619826641cf3b627c24aab62e2ad6b571bdd1d34733abb0dd57f67a/orjson-3.11.6-cp311-cp311-macosx_15_0_arm64.whl", hash = "sha256:52263949f41b4a4822c6b1353bcc5ee2f7109d53a3b493501d3369d6d0e7937a", size = 134518, upload-time = "2026-01-29T15:11:37.347Z" },
+    { url = "https://files.pythonhosted.org/packages/72/90/7a818da4bba1de711a9653c420749c0ac95ef8f8651cbc1dca551f462fe0/orjson-3.11.6-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6439e742fa7834a24698d358a27346bb203bff356ae0402e7f5df8f749c621a8", size = 137917, upload-time = "2026-01-29T15:11:38.511Z" },
+    { url = "https://files.pythonhosted.org/packages/59/0f/02846c1cac8e205cb3822dd8aa8f9114acda216f41fd1999ace6b543418d/orjson-3.11.6-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:b81ffd68f084b4e993e3867acb554a049fa7787cc8710bbcc1e26965580d99be", size = 134923, upload-time = "2026-01-29T15:11:39.711Z" },
+    { url = "https://files.pythonhosted.org/packages/94/cf/aeaf683001b474bb3c3c757073a4231dfdfe8467fceaefa5bfd40902c99f/orjson-3.11.6-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a5a5468e5e60f7ef6d7f9044b06c8f94a3c56ba528c6e4f7f06ae95164b595ec", size = 140752, upload-time = "2026-01-29T15:11:41.347Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/fe/dad52d8315a65f084044a0819d74c4c9daf9ebe0681d30f525b0d29a31f0/orjson-3.11.6-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:72c5005eb45bd2535632d4f3bec7ad392832cfc46b62a3021da3b48a67734b45", size = 144201, upload-time = "2026-01-29T15:11:42.537Z" },
+    { url = "https://files.pythonhosted.org/packages/36/bc/ab070dd421565b831801077f1e390c4d4af8bfcecafc110336680a33866b/orjson-3.11.6-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0b14dd49f3462b014455a28a4d810d3549bf990567653eb43765cd847df09145", size = 142380, upload-time = "2026-01-29T15:11:44.309Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/d8/4b581c725c3a308717f28bf45a9fdac210bca08b67e8430143699413ff06/orjson-3.11.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6e0bb2c1ea30ef302f0f89f9bf3e7f9ab5e2af29dc9f80eb87aa99788e4e2d65", size = 145582, upload-time = "2026-01-29T15:11:45.506Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/a2/09aab99b39f9a7f175ea8fa29adb9933a3d01e7d5d603cdee7f1c40c8da2/orjson-3.11.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:825e0a85d189533c6bff7e2fc417a28f6fcea53d27125c4551979aecd6c9a197", size = 147270, upload-time = "2026-01-29T15:11:46.782Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/2f/5ef8eaf7829dc50da3bf497c7775b21ee88437bc8c41f959aa3504ca6631/orjson-3.11.6-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:b04575417a26530637f6ab4b1f7b4f666eb0433491091da4de38611f97f2fcf3", size = 421222, upload-time = "2026-01-29T15:11:48.106Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/b0/dd6b941294c2b5b13da5fdc7e749e58d0c55a5114ab37497155e83050e95/orjson-3.11.6-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:b83eb2e40e8c4da6d6b340ee6b1d6125f5195eb1b0ebb7eac23c6d9d4f92d224", size = 155562, upload-time = "2026-01-29T15:11:49.408Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/09/43924331a847476ae2f9a16bd6d3c9dab301265006212ba0d3d7fd58763a/orjson-3.11.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1f42da604ee65a6b87eef858c913ce3e5777872b19321d11e6fc6d21de89b64f", size = 147432, upload-time = "2026-01-29T15:11:50.635Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/e9/d9865961081816909f6b49d880749dbbd88425afd7c5bbce0549e2290d77/orjson-3.11.6-cp311-cp311-win32.whl", hash = "sha256:5ae45df804f2d344cffb36c43fdf03c82fb6cd247f5faa41e21891b40dfbf733", size = 139623, upload-time = "2026-01-29T15:11:51.82Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/f9/6836edb92f76eec1082919101eb1145d2f9c33c8f2c5e6fa399b82a2aaa8/orjson-3.11.6-cp311-cp311-win_amd64.whl", hash = "sha256:f4295948d65ace0a2d8f2c4ccc429668b7eb8af547578ec882e16bf79b0050b2", size = 136647, upload-time = "2026-01-29T15:11:53.454Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/0c/4954082eea948c9ae52ee0bcbaa2f99da3216a71bcc314ab129bde22e565/orjson-3.11.6-cp311-cp311-win_arm64.whl", hash = "sha256:314e9c45e0b81b547e3a1cfa3df3e07a815821b3dac9fe8cb75014071d0c16a4", size = 135327, upload-time = "2026-01-29T15:11:56.616Z" },
+    { url = "https://files.pythonhosted.org/packages/14/ba/759f2879f41910b7e5e0cdbd9cf82a4f017c527fb0e972e9869ca7fe4c8e/orjson-3.11.6-cp312-cp312-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:6f03f30cd8953f75f2a439070c743c7336d10ee940da918d71c6f3556af3ddcf", size = 249988, upload-time = "2026-01-29T15:11:58.294Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/70/54cecb929e6c8b10104fcf580b0cc7dc551aa193e83787dd6f3daba28bb5/orjson-3.11.6-cp312-cp312-macosx_15_0_arm64.whl", hash = "sha256:af44baae65ef386ad971469a8557a0673bb042b0b9fd4397becd9c2dfaa02588", size = 134445, upload-time = "2026-01-29T15:11:59.819Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/6f/ec0309154457b9ba1ad05f11faa4441f76037152f75e1ac577db3ce7ca96/orjson-3.11.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c310a48542094e4f7dbb6ac076880994986dda8ca9186a58c3cb70a3514d3231", size = 137708, upload-time = "2026-01-29T15:12:01.488Z" },
+    { url = "https://files.pythonhosted.org/packages/20/52/3c71b80840f8bab9cb26417302707b7716b7d25f863f3a541bcfa232fe6e/orjson-3.11.6-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d8dfa7a5d387f15ecad94cb6b2d2d5f4aeea64efd8d526bfc03c9812d01e1cc0", size = 134798, upload-time = "2026-01-29T15:12:02.705Z" },
+    { url = "https://files.pythonhosted.org/packages/30/51/b490a43b22ff736282360bd02e6bded455cf31dfc3224e01cd39f919bbd2/orjson-3.11.6-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ba8daee3e999411b50f8b50dbb0a3071dd1845f3f9a1a0a6fa6de86d1689d84d", size = 140839, upload-time = "2026-01-29T15:12:03.956Z" },
+    { url = "https://files.pythonhosted.org/packages/95/bc/4bcfe4280c1bc63c5291bb96f98298845b6355da2226d3400e17e7b51e53/orjson-3.11.6-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f89d104c974eafd7436d7a5fdbc57f7a1e776789959a2f4f1b2eab5c62a339f4", size = 144080, upload-time = "2026-01-29T15:12:05.151Z" },
+    { url = "https://files.pythonhosted.org/packages/01/74/22970f9ead9ab1f1b5f8c227a6c3aa8d71cd2c5acd005868a1d44f2362fa/orjson-3.11.6-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b2e2e2456788ca5ea75616c40da06fc885a7dc0389780e8a41bf7c5389ba257b", size = 142435, upload-time = "2026-01-29T15:12:06.641Z" },
+    { url = "https://files.pythonhosted.org/packages/29/34/d564aff85847ab92c82ee43a7a203683566c2fca0723a5f50aebbe759603/orjson-3.11.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2a42efebc45afabb1448001e90458c4020d5c64fbac8a8dc4045b777db76cb5a", size = 145631, upload-time = "2026-01-29T15:12:08.351Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/ef/016957a3890752c4aa2368326ea69fa53cdc1fdae0a94a542b6410dbdf52/orjson-3.11.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:71b7cbef8471324966c3738c90ba38775563ef01b512feb5ad4805682188d1b9", size = 147058, upload-time = "2026-01-29T15:12:10.023Z" },
+    { url = "https://files.pythonhosted.org/packages/56/cc/9a899c3972085645b3225569f91a30e221f441e5dc8126e6d060b971c252/orjson-3.11.6-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:f8515e5910f454fe9a8e13c2bb9dc4bae4c1836313e967e72eb8a4ad874f0248", size = 421161, upload-time = "2026-01-29T15:12:11.308Z" },
+    { url = "https://files.pythonhosted.org/packages/21/a8/767d3fbd6d9b8fdee76974db40619399355fd49bf91a6dd2c4b6909ccf05/orjson-3.11.6-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:300360edf27c8c9bf7047345a94fddf3a8b8922df0ff69d71d854a170cb375cf", size = 155757, upload-time = "2026-01-29T15:12:12.776Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/0b/205cd69ac87e2272e13ef3f5f03a3d4657e317e38c1b08aaa2ef97060bbc/orjson-3.11.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:caaed4dad39e271adfadc106fab634d173b2bb23d9cf7e67bd645f879175ebfc", size = 147446, upload-time = "2026-01-29T15:12:14.166Z" },
+    { url = "https://files.pythonhosted.org/packages/de/c5/dd9f22aa9f27c54c7d05cc32f4580c9ac9b6f13811eeb81d6c4c3f50d6b1/orjson-3.11.6-cp312-cp312-win32.whl", hash = "sha256:955368c11808c89793e847830e1b1007503a5923ddadc108547d3b77df761044", size = 139717, upload-time = "2026-01-29T15:12:15.7Z" },
+    { url = "https://files.pythonhosted.org/packages/23/a1/e62fc50d904486970315a1654b8cfb5832eb46abb18cd5405118e7e1fc79/orjson-3.11.6-cp312-cp312-win_amd64.whl", hash = "sha256:2c68de30131481150073d90a5d227a4a421982f42c025ecdfb66157f9579e06f", size = 136711, upload-time = "2026-01-29T15:12:17.055Z" },
+    { url = "https://files.pythonhosted.org/packages/04/3d/b4fefad8bdf91e0fe212eb04975aeb36ea92997269d68857efcc7eb1dda3/orjson-3.11.6-cp312-cp312-win_arm64.whl", hash = "sha256:65dfa096f4e3a5e02834b681f539a87fbe85adc82001383c0db907557f666bfc", size = 135212, upload-time = "2026-01-29T15:12:18.3Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/45/d9c71c8c321277bc1ceebf599bc55ba826ae538b7c61f287e9a7e71bd589/orjson-3.11.6-cp313-cp313-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:e4ae1670caabb598a88d385798692ce2a1b2f078971b3329cfb85253c6097f5b", size = 249828, upload-time = "2026-01-29T15:12:20.14Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/7e/4afcf4cfa9c2f93846d70eee9c53c3c0123286edcbeb530b7e9bd2aea1b2/orjson-3.11.6-cp313-cp313-macosx_15_0_arm64.whl", hash = "sha256:2c6b81f47b13dac2caa5d20fbc953c75eb802543abf48403a4703ed3bff225f0", size = 134339, upload-time = "2026-01-29T15:12:22.01Z" },
+    { url = "https://files.pythonhosted.org/packages/40/10/6d2b8a064c8d2411d3d0ea6ab43125fae70152aef6bea77bb50fa54d4097/orjson-3.11.6-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:647d6d034e463764e86670644bdcaf8e68b076e6e74783383b01085ae9ab334f", size = 137662, upload-time = "2026-01-29T15:12:23.307Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/50/5804ea7d586baf83ee88969eefda97a24f9a5bdba0727f73e16305175b26/orjson-3.11.6-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8523b9cc4ef174ae52414f7699e95ee657c16aa18b3c3c285d48d7966cce9081", size = 134626, upload-time = "2026-01-29T15:12:25.099Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/2e/f0492ed43e376722bb4afd648e06cc1e627fc7ec8ff55f6ee739277813ea/orjson-3.11.6-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:313dfd7184cde50c733fc0d5c8c0e2f09017b573afd11dc36bd7476b30b4cb17", size = 140873, upload-time = "2026-01-29T15:12:26.369Z" },
+    { url = "https://files.pythonhosted.org/packages/10/15/6f874857463421794a303a39ac5494786ad46a4ab46d92bda6705d78c5aa/orjson-3.11.6-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:905ee036064ff1e1fd1fb800055ac477cdcb547a78c22c1bc2bbf8d5d1a6fb42", size = 144044, upload-time = "2026-01-29T15:12:28.082Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/c7/b7223a3a70f1d0cc2d86953825de45f33877ee1b124a91ca1f79aa6e643f/orjson-3.11.6-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ce374cb98411356ba906914441fc993f271a7a666d838d8de0e0900dd4a4bc12", size = 142396, upload-time = "2026-01-29T15:12:30.529Z" },
+    { url = "https://files.pythonhosted.org/packages/87/e3/aa1b6d3ad3cd80f10394134f73ae92a1d11fdbe974c34aa199cc18bb5fcf/orjson-3.11.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:cded072b9f65fcfd188aead45efa5bd528ba552add619b3ad2a81f67400ec450", size = 145600, upload-time = "2026-01-29T15:12:31.848Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/cf/e4aac5a46cbd39d7e769ef8650efa851dfce22df1ba97ae2b33efe893b12/orjson-3.11.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7ab85bdbc138e1f73a234db6bb2e4cc1f0fcec8f4bd2bd2430e957a01aadf746", size = 146967, upload-time = "2026-01-29T15:12:33.203Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/04/975b86a4bcf6cfeda47aad15956d52fbeda280811206e9967380fa9355c8/orjson-3.11.6-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:351b96b614e3c37a27b8ab048239ebc1e0be76cc17481a430d70a77fb95d3844", size = 421003, upload-time = "2026-01-29T15:12:35.097Z" },
+    { url = "https://files.pythonhosted.org/packages/28/d1/0369d0baf40eea5ff2300cebfe209883b2473ab4aa4c4974c8bd5ee42bb2/orjson-3.11.6-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:f9959c85576beae5cdcaaf39510b15105f1ee8b70d5dacd90152617f57be8c83", size = 155695, upload-time = "2026-01-29T15:12:36.589Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/1f/d10c6d6ae26ff1d7c3eea6fd048280ef2e796d4fb260c5424fd021f68ecf/orjson-3.11.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:75682d62b1b16b61a30716d7a2ec1f4c36195de4a1c61f6665aedd947b93a5d5", size = 147392, upload-time = "2026-01-29T15:12:37.876Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/43/7479921c174441a0aa5277c313732e20713c0969ac303be9f03d88d3db5d/orjson-3.11.6-cp313-cp313-win32.whl", hash = "sha256:40dc277999c2ef227dcc13072be879b4cfd325502daeb5c35ed768f706f2bf30", size = 139718, upload-time = "2026-01-29T15:12:39.274Z" },
+    { url = "https://files.pythonhosted.org/packages/88/bc/9ffe7dfbf8454bc4e75bb8bf3a405ed9e0598df1d3535bb4adcd46be07d0/orjson-3.11.6-cp313-cp313-win_amd64.whl", hash = "sha256:f0f6e9f8ff7905660bc3c8a54cd4a675aa98f7f175cf00a59815e2ff42c0d916", size = 136635, upload-time = "2026-01-29T15:12:40.593Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/7e/51fa90b451470447ea5023b20d83331ec741ae28d1e6d8ed547c24e7de14/orjson-3.11.6-cp313-cp313-win_arm64.whl", hash = "sha256:1608999478664de848e5900ce41f25c4ecdfc4beacbc632b6fd55e1a586e5d38", size = 135175, upload-time = "2026-01-29T15:12:41.997Z" },
+    { url = "https://files.pythonhosted.org/packages/31/9f/46ca908abaeeec7560638ff20276ab327b980d73b3cc2f5b205b4a1c60b3/orjson-3.11.6-cp314-cp314-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:6026db2692041d2a23fe2545606df591687787825ad5821971ef0974f2c47630", size = 249823, upload-time = "2026-01-29T15:12:43.332Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/78/ca478089818d18c9cd04f79c43f74ddd031b63c70fa2a946eb5e85414623/orjson-3.11.6-cp314-cp314-macosx_15_0_arm64.whl", hash = "sha256:132b0ab2e20c73afa85cf142e547511feb3d2f5b7943468984658f3952b467d4", size = 134328, upload-time = "2026-01-29T15:12:45.171Z" },
+    { url = "https://files.pythonhosted.org/packages/39/5e/cbb9d830ed4e47f4375ad8eef8e4fff1bf1328437732c3809054fc4e80be/orjson-3.11.6-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b376fb05f20a96ec117d47987dd3b39265c635725bda40661b4c5b73b77b5fde", size = 137651, upload-time = "2026-01-29T15:12:46.602Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/3a/35df6558c5bc3a65ce0961aefee7f8364e59af78749fc796ea255bfa0cf5/orjson-3.11.6-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:954dae4e080574672a1dfcf2a840eddef0f27bd89b0e94903dd0824e9c1db060", size = 134596, upload-time = "2026-01-29T15:12:47.95Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/8e/3d32dd7b7f26a19cc4512d6ed0ae3429567c71feef720fe699ff43c5bc9e/orjson-3.11.6-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:fe515bb89d59e1e4b48637a964f480b35c0a2676de24e65e55310f6016cca7ce", size = 140923, upload-time = "2026-01-29T15:12:49.333Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/9c/1efbf5c99b3304f25d6f0d493a8d1492ee98693637c10ce65d57be839d7b/orjson-3.11.6-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:380f9709c275917af28feb086813923251e11ee10687257cd7f1ea188bcd4485", size = 144068, upload-time = "2026-01-29T15:12:50.927Z" },
+    { url = "https://files.pythonhosted.org/packages/82/83/0d19eeb5be797de217303bbb55dde58dba26f996ed905d301d98fd2d4637/orjson-3.11.6-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a8173e0d3f6081e7034c51cf984036d02f6bab2a2126de5a759d79f8e5a140e7", size = 142493, upload-time = "2026-01-29T15:12:52.432Z" },
+    { url = "https://files.pythonhosted.org/packages/32/a7/573fec3df4dc8fc259b7770dc6c0656f91adce6e19330c78d23f87945d1e/orjson-3.11.6-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6dddf9ba706294906c56ef5150a958317b09aa3a8a48df1c52ccf22ec1907eac", size = 145616, upload-time = "2026-01-29T15:12:53.903Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/0e/23551b16f21690f7fd5122e3cf40fdca5d77052a434d0071990f97f5fe2f/orjson-3.11.6-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:cbae5c34588dc79938dffb0b6fbe8c531f4dc8a6ad7f39759a9eb5d2da405ef2", size = 146951, upload-time = "2026-01-29T15:12:55.698Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/63/5e6c8f39805c39123a18e412434ea364349ee0012548d08aa586e2bd6aa9/orjson-3.11.6-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:f75c318640acbddc419733b57f8a07515e587a939d8f54363654041fd1f4e465", size = 421024, upload-time = "2026-01-29T15:12:57.434Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/4d/724975cf0087f6550bd01fd62203418afc0ea33fd099aed318c5bcc52df8/orjson-3.11.6-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:e0ab8d13aa2a3e98b4a43487c9205b2c92c38c054b4237777484d503357c8437", size = 155774, upload-time = "2026-01-29T15:12:59.397Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/a3/f4c4e3f46b55db29e0a5f20493b924fc791092d9a03ff2068c9fe6c1002f/orjson-3.11.6-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f884c7fb1020d44612bd7ac0db0babba0e2f78b68d9a650c7959bf99c783773f", size = 147393, upload-time = "2026-01-29T15:13:00.769Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/86/6f5529dd27230966171ee126cecb237ed08e9f05f6102bfaf63e5b32277d/orjson-3.11.6-cp314-cp314-win32.whl", hash = "sha256:8d1035d1b25732ec9f971e833a3e299d2b1a330236f75e6fd945ad982c76aaf3", size = 139760, upload-time = "2026-01-29T15:13:02.173Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/b5/91ae7037b2894a6b5002fb33f4fbccec98424a928469835c3837fbb22a9b/orjson-3.11.6-cp314-cp314-win_amd64.whl", hash = "sha256:931607a8865d21682bb72de54231655c86df1870502d2962dbfd12c82890d077", size = 136633, upload-time = "2026-01-29T15:13:04.267Z" },
+    { url = "https://files.pythonhosted.org/packages/55/74/f473a3ec7a0a7ebc825ca8e3c86763f7d039f379860c81ba12dcdd456547/orjson-3.11.6-cp314-cp314-win_arm64.whl", hash = "sha256:fe71f6b283f4f1832204ab8235ce07adad145052614f77c876fcf0dac97bc06f", size = 135168, upload-time = "2026-01-29T15:13:05.932Z" },
 ]
 
 [[package]]

From a4a664fa2c57f7f3d34646e3dc21a44913ce15f7 Mon Sep 17 00:00:00 2001
From: Jamison Lahman <jamison@lahman.dev>
Date: Thu, 12 Mar 2026 15:37:00 -0700
Subject: [PATCH 260/267] chore(fe): polish file previews more (#9259)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 web/jest.config.js                            |   2 +
 web/package-lock.json                         |  16 +++
 web/package.json                              |   1 +
 web/src/components/chat/MinimalMarkdown.tsx   |  30 +++---
 web/src/lib/languages.test.ts                 | 102 ++++++++++++++++++
 web/src/lib/languages.ts                      |  60 +++++++++--
 .../refresh-components/ScrollIndicatorDiv.tsx |  46 +++++++-
 .../modals/PreviewModal/PreviewModal.tsx      |  59 +++++-----
 .../modals/PreviewModal/interfaces.ts         |   2 +
 .../sections/modals/PreviewModal/mimeUtils.ts |  50 ---------
 .../PreviewModal/variants/CodePreview.tsx     |  31 ++++--
 .../PreviewModal/variants/codeVariant.tsx     |   3 +-
 .../PreviewModal/variants/csvVariant.tsx      |   1 +
 .../PreviewModal/variants/dataVariant.tsx     |  10 +-
 .../PreviewModal/variants/docxVariant.tsx     |   1 +
 .../PreviewModal/variants/imageVariant.tsx    |   1 +
 .../modals/PreviewModal/variants/index.ts     |   4 +-
 .../PreviewModal/variants/markdownVariant.tsx |  11 +-
 .../PreviewModal/variants/pdfVariant.tsx      |   1 +
 .../PreviewModal/variants/textVariant.tsx     |   3 +-
 .../variants/unsupportedVariant.tsx           |   5 +-
 web/tailwind-themes/tailwind.config.js        |   1 +
 22 files changed, 310 insertions(+), 130 deletions(-)
 create mode 100644 web/src/lib/languages.test.ts
 delete mode 100644 web/src/sections/modals/PreviewModal/mimeUtils.ts

diff --git a/web/jest.config.js b/web/jest.config.js
index 120f4811202..e1484018b03 100644
--- a/web/jest.config.js
+++ b/web/jest.config.js
@@ -53,6 +53,8 @@ const sharedConfig = {
         // Testing & Mocking
         "msw",
         "until-async",
+        // Language Detection
+        "linguist-languages",
         // Markdown & Syntax Highlighting
         "react-markdown",
         "remark-.*", // All remark packages
diff --git a/web/package-lock.json b/web/package-lock.json
index 2031b70bc81..18ef71edecd 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -59,6 +59,7 @@
         "lowlight": "^3.3.0",
         "lucide-react": "^0.454.0",
         "mdast-util-find-and-replace": "^3.0.1",
+        "mime": "^4.1.0",
         "motion": "^12.29.0",
         "next": "16.1.6",
         "next-themes": "^0.4.4",
@@ -13883,6 +13884,21 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/mime": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-4.1.0.tgz",
+      "integrity": "sha512-X5ju04+cAzsojXKes0B/S4tcYtFAJ6tTMuSPBEn9CPGlrWr8Fiw7qYeLT0XyH80HSoAoqWCaz+MWKh22P7G1cw==",
+      "funding": [
+        "https://github.com/sponsors/broofa"
+      ],
+      "license": "MIT",
+      "bin": {
+        "mime": "bin/cli.js"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
     "node_modules/mime-db": {
       "version": "1.52.0",
       "license": "MIT",
diff --git a/web/package.json b/web/package.json
index 3ade8c50d5b..917712ac314 100644
--- a/web/package.json
+++ b/web/package.json
@@ -77,6 +77,7 @@
     "lowlight": "^3.3.0",
     "lucide-react": "^0.454.0",
     "mdast-util-find-and-replace": "^3.0.1",
+    "mime": "^4.1.0",
     "motion": "^12.29.0",
     "next": "16.1.6",
     "next-themes": "^0.4.4",
diff --git a/web/src/components/chat/MinimalMarkdown.tsx b/web/src/components/chat/MinimalMarkdown.tsx
index ce68c0c3ec9..76b6e5dc229 100644
--- a/web/src/components/chat/MinimalMarkdown.tsx
+++ b/web/src/components/chat/MinimalMarkdown.tsx
@@ -11,14 +11,13 @@ import rehypeHighlight from "rehype-highlight";
 import remarkMath from "remark-math";
 import rehypeKatex from "rehype-katex";
 import "katex/dist/katex.min.css";
-import { transformLinkUri } from "@/lib/utils";
+import { cn, transformLinkUri } from "@/lib/utils";
 
 type MinimalMarkdownComponentOverrides = Partial<Components>;
 
 interface MinimalMarkdownProps {
   content: string;
   className?: string;
-  style?: CSSProperties;
   showHeader?: boolean;
   /**
    * Override specific markdown renderers.
@@ -30,7 +29,6 @@ interface MinimalMarkdownProps {
 export default function MinimalMarkdown({
   content,
   className = "",
-  style,
   showHeader = true,
   components,
 }: MinimalMarkdownProps) {
@@ -63,19 +61,17 @@ export default function MinimalMarkdown({
   }, [content, components, showHeader]);
 
   return (
-    <div style={style || {}} className={`${className}`}>
-      <ReactMarkdown
-        className="prose dark:prose-invert max-w-full text-sm break-words"
-        components={markdownComponents}
-        rehypePlugins={[rehypeHighlight, rehypeKatex]}
-        remarkPlugins={[
-          remarkGfm,
-          [remarkMath, { singleDollarTextMath: false }],
-        ]}
-        urlTransform={transformLinkUri}
-      >
-        {content}
-      </ReactMarkdown>
-    </div>
+    <ReactMarkdown
+      className={cn(
+        "prose dark:prose-invert max-w-full text-sm break-words",
+        className
+      )}
+      components={markdownComponents}
+      rehypePlugins={[rehypeHighlight, rehypeKatex]}
+      remarkPlugins={[remarkGfm, [remarkMath, { singleDollarTextMath: false }]]}
+      urlTransform={transformLinkUri}
+    >
+      {content}
+    </ReactMarkdown>
   );
 }
diff --git a/web/src/lib/languages.test.ts b/web/src/lib/languages.test.ts
new file mode 100644
index 00000000000..1dd3cfda66d
--- /dev/null
+++ b/web/src/lib/languages.test.ts
@@ -0,0 +1,102 @@
+import {
+  getCodeLanguage,
+  getDataLanguage,
+  getLanguageByMime,
+  isMarkdownFile,
+} from "./languages";
+
+describe("getCodeLanguage", () => {
+  it.each([
+    ["app.py", "python"],
+    ["index.ts", "typescript"],
+    ["main.go", "go"],
+    ["style.css", "css"],
+    ["page.html", "html"],
+    ["App.vue", "vue"],
+    ["lib.rs", "rust"],
+    ["main.cpp", "c++"],
+    ["util.c", "c"],
+    ["script.js", "javascript"],
+  ])("%s → %s", (filename, expected) => {
+    expect(getCodeLanguage(filename)).toBe(expected);
+  });
+
+  it.each([
+    [".h", "c"],
+    [".inc", "php"],
+    [".m", "objective-c"],
+    [".re", "reason"],
+  ])("override: %s → %s", (ext, expected) => {
+    expect(getCodeLanguage(`file${ext}`)).toBe(expected);
+  });
+
+  it("resolves by exact filename when there is no extension", () => {
+    expect(getCodeLanguage("Dockerfile")).toBe("dockerfile");
+    expect(getCodeLanguage("Makefile")).toBe("makefile");
+  });
+
+  it("is case-insensitive for filenames", () => {
+    expect(getCodeLanguage("INDEX.JS")).toBe("javascript");
+    expect(getCodeLanguage("dockerfile")).toBe("dockerfile");
+  });
+
+  it("returns null for unknown extensions", () => {
+    expect(getCodeLanguage("file.xyz123")).toBeNull();
+  });
+
+  it("excludes markdown extensions", () => {
+    expect(getCodeLanguage("README.md")).toBeNull();
+    expect(getCodeLanguage("notes.markdown")).toBeNull();
+  });
+});
+
+describe("getDataLanguage", () => {
+  it.each([
+    ["config.json", "json"],
+    ["config.yaml", "yaml"],
+    ["config.yml", "yaml"],
+    ["config.toml", "toml"],
+    ["data.xml", "xml"],
+    ["data.csv", "csv"],
+  ])("%s → %s", (filename, expected) => {
+    expect(getDataLanguage(filename)).toBe(expected);
+  });
+
+  it("returns null for code files", () => {
+    expect(getDataLanguage("app.py")).toBeNull();
+    expect(getDataLanguage("header.h")).toBeNull();
+    expect(getDataLanguage("view.m")).toBeNull();
+    expect(getDataLanguage("component.re")).toBeNull();
+  });
+});
+
+describe("isMarkdownFile", () => {
+  it("recognises markdown extensions", () => {
+    expect(isMarkdownFile("README.md")).toBe(true);
+    expect(isMarkdownFile("doc.markdown")).toBe(true);
+  });
+
+  it("is case-insensitive", () => {
+    expect(isMarkdownFile("NOTES.MD")).toBe(true);
+  });
+
+  it("rejects non-markdown files", () => {
+    expect(isMarkdownFile("app.py")).toBe(false);
+    expect(isMarkdownFile("data.json")).toBe(false);
+  });
+});
+
+describe("getLanguageByMime", () => {
+  it("resolves known MIME types", () => {
+    expect(getLanguageByMime("text/x-python")).toBe("python");
+    expect(getLanguageByMime("text/javascript")).toBe("javascript");
+  });
+
+  it("strips parameters before matching", () => {
+    expect(getLanguageByMime("text/x-python; charset=utf-8")).toBe("python");
+  });
+
+  it("returns null for unknown MIME types", () => {
+    expect(getLanguageByMime("application/x-unknown-thing")).toBeNull();
+  });
+});
diff --git a/web/src/lib/languages.ts b/web/src/lib/languages.ts
index 6d5163022cf..7bfae41056f 100644
--- a/web/src/lib/languages.ts
+++ b/web/src/lib/languages.ts
@@ -7,6 +7,7 @@ interface LinguistLanguage {
   type: string;
   extensions?: string[];
   filenames?: string[];
+  codemirrorMimeType?: string;
 }
 
 interface LanguageMaps {
@@ -14,7 +15,23 @@ interface LanguageMaps {
   filenames: Map<string, string>;
 }
 
-const allLanguages = Object.values(languages) as LinguistLanguage[];
+// Explicit winners for extensions claimed by multiple linguist-languages entries
+// where the "most extensions" heuristic below picks the wrong language.
+const EXTENSION_OVERRIDES: Record<string, string> = {
+  ".h": "c",
+  ".inc": "php",
+  ".m": "objective-c",
+  ".re": "reason",
+  ".rs": "rust",
+};
+
+// Sort so that languages with more extensions (i.e. more general-purpose) win
+// when multiple languages claim the same extension (e.g. Ecmarkup vs HTML both
+// claim .html — HTML should win because it's the canonical language for that
+// extension). Known mis-rankings are patched by EXTENSION_OVERRIDES above.
+const allLanguages = (Object.values(languages) as LinguistLanguage[]).sort(
+  (a, b) => (b.extensions?.length ?? 0) - (a.extensions?.length ?? 0)
+);
 
 // Collect extensions that linguist-languages assigns to "Markdown" so we can
 // exclude them from the code-language map
@@ -25,14 +42,22 @@ const markdownExtensions = new Set(
 );
 
 function buildLanguageMaps(
-  type: string,
+  types: string[],
   excludedExtensions?: Set<string>
 ): LanguageMaps {
+  const typeSet = new Set(types);
   const extensions = new Map<string, string>();
   const filenames = new Map<string, string>();
 
+  if (typeSet.has("programming") || typeSet.has("markup")) {
+    for (const [ext, lang] of Object.entries(EXTENSION_OVERRIDES)) {
+      if (excludedExtensions?.has(ext.toLowerCase())) continue;
+      extensions.set(ext, lang);
+    }
+  }
+
   for (const lang of allLanguages) {
-    if (lang.type !== type) continue;
+    if (!typeSet.has(lang.type)) continue;
 
     const name = lang.name.toLowerCase();
     for (const ext of lang.extensions ?? []) {
@@ -57,13 +82,17 @@ function lookupLanguage(name: string, maps: LanguageMaps): string | null {
   return (ext && maps.extensions.get(ext)) ?? maps.filenames.get(lower) ?? null;
 }
 
-const codeMaps = buildLanguageMaps("programming", markdownExtensions);
-const dataMaps = buildLanguageMaps("data");
+const codeMaps = buildLanguageMaps(
+  ["programming", "markup"],
+  markdownExtensions
+);
+const dataMaps = buildLanguageMaps(["data"]);
 
 /**
  * Returns the language name for a given file name, or null if it's not a
- * recognised code file. Looks up by extension first, then by exact filename
- * (e.g. "Dockerfile", "Makefile"). Runs in O(1).
+ * recognised code or markup file (programming + markup types from
+ * linguist-languages, e.g. Python, HTML, CSS, Vue). Looks up by extension
+ * first, then by exact filename (e.g. "Dockerfile", "Makefile"). Runs in O(1).
  */
 export function getCodeLanguage(name: string): string | null {
   return lookupLanguage(name, codeMaps);
@@ -86,3 +115,20 @@ export function isMarkdownFile(name: string): boolean {
   const ext = name.toLowerCase().match(LANGUAGE_EXT_PATTERN)?.[0];
   return !!ext && markdownExtensions.has(ext);
 }
+
+const mimeToLanguage = new Map<string, string>();
+for (const lang of allLanguages) {
+  if (lang.codemirrorMimeType && !mimeToLanguage.has(lang.codemirrorMimeType)) {
+    mimeToLanguage.set(lang.codemirrorMimeType, lang.name.toLowerCase());
+  }
+}
+
+/**
+ * Returns the language name for a given MIME type using the codemirrorMimeType
+ * field from linguist-languages (~297 entries). Returns null if unrecognised.
+ */
+export function getLanguageByMime(mime: string): string | null {
+  const base = mime.split(";")[0];
+  if (!base) return null;
+  return mimeToLanguage.get(base.trim().toLowerCase()) ?? null;
+}
diff --git a/web/src/refresh-components/ScrollIndicatorDiv.tsx b/web/src/refresh-components/ScrollIndicatorDiv.tsx
index 98182075b58..2dad55da85a 100644
--- a/web/src/refresh-components/ScrollIndicatorDiv.tsx
+++ b/web/src/refresh-components/ScrollIndicatorDiv.tsx
@@ -6,10 +6,42 @@ import { cn } from "@/lib/utils";
 // Throttle interval for scroll events (~60fps)
 const SCROLL_THROTTLE_MS = 16;
 
+/**
+ * A scrollable container that shows gradient or shadow indicators when
+ * content overflows above or below the visible area.
+ *
+ * HEIGHT CONSTRAINT REQUIREMENT
+ *
+ * This component relies on its inner scroll container having a smaller
+ * clientHeight than its scrollHeight. For that to happen, the entire
+ * ancestor chain must constrain height via flex sizing (flex-1 min-h-0),
+ * NOT via percentage heights (h-full).
+ *
+ * height: 100% resolves to "auto" when the containing block's height is
+ * determined by flex layout (flex-auto, flex-1) rather than an explicit
+ * height property — this is per the CSS spec. When that happens, the
+ * container grows to fit its content and scrollHeight === clientHeight,
+ * making scroll indicators invisible.
+ *
+ * Correct pattern: every ancestor up to the nearest fixed-height boundary
+ * must form an unbroken flex column chain using "flex-1 min-h-0":
+ *
+ *   fixed-height-ancestor  (e.g. h-[500px])
+ *     flex flex-col flex-1 min-h-0   <-- use flex-1, NOT h-full
+ *       ScrollIndicatorDiv
+ *         ...tall content...
+ *
+ * Common mistakes:
+ *  - Using h-full instead of flex-1 min-h-0 anywhere in the chain.
+ *  - Placing this inside a parent with overflow-y: auto (e.g. Modal.Body),
+ *    which becomes the scroll container instead of this component's inner div.
+ */
 export interface ScrollIndicatorDivProps
   extends React.HTMLAttributes<HTMLDivElement> {
   // Mask/Shadow options
   disableIndicators?: boolean;
+  disableTopIndicator?: boolean;
+  disableBottomIndicator?: boolean;
   backgroundColor?: string;
   indicatorHeight?: string;
 
@@ -22,6 +54,8 @@ export interface ScrollIndicatorDivProps
 
 export default function ScrollIndicatorDiv({
   disableIndicators = false,
+  disableTopIndicator = false,
+  disableBottomIndicator = false,
   backgroundColor = "var(--background-tint-02)",
   indicatorHeight = "3rem",
   variant = "gradient",
@@ -77,13 +111,19 @@ export default function ScrollIndicatorDiv({
     // Update on scroll (throttled)
     container.addEventListener("scroll", handleScroll, { passive: true });
 
-    // Update on resize (in case content changes)
+    // Update when the container itself resizes
     const resizeObserver = new ResizeObserver(updateScrollIndicators);
     resizeObserver.observe(container);
 
+    // Update when descendants change (e.g. syntax highlighting mutates the
+    // DOM after initial render, which changes scrollHeight without firing
+    // resize or scroll events on the container).
+    const mutationObserver = new MutationObserver(handleScroll);
+
     return () => {
       container.removeEventListener("scroll", handleScroll);
       resizeObserver.disconnect();
+      mutationObserver.disconnect();
       if (throttleTimeoutRef.current) {
         clearTimeout(throttleTimeoutRef.current);
       }
@@ -120,7 +160,7 @@ export default function ScrollIndicatorDiv({
   return (
     <div className="relative flex-1 min-h-0 overflow-y-hidden flex flex-col w-full">
       {/* Top indicator */}
-      {!disableIndicators && showTopIndicator && (
+      {!disableIndicators && !disableTopIndicator && showTopIndicator && (
         <div
           className="absolute top-0 left-0 right-0 z-[20] pointer-events-none transition-opacity duration-200"
           style={getIndicatorStyle("top")}
@@ -141,7 +181,7 @@ export default function ScrollIndicatorDiv({
       </div>
 
       {/* Bottom indicator */}
-      {!disableIndicators && showBottomIndicator && (
+      {!disableIndicators && !disableBottomIndicator && showBottomIndicator && (
         <div
           className="absolute bottom-0 left-0 right-0 z-[20] pointer-events-none transition-opacity duration-200"
           style={getIndicatorStyle("bottom")}
diff --git a/web/src/sections/modals/PreviewModal/PreviewModal.tsx b/web/src/sections/modals/PreviewModal/PreviewModal.tsx
index f446201fe9f..512b3cbde3d 100644
--- a/web/src/sections/modals/PreviewModal/PreviewModal.tsx
+++ b/web/src/sections/modals/PreviewModal/PreviewModal.tsx
@@ -7,13 +7,14 @@ import Text from "@/refresh-components/texts/Text";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
 import { cn } from "@/lib/utils";
 import { Section } from "@/layouts/general-layouts";
-import { getCodeLanguage, getDataLanguage } from "@/lib/languages";
+import mime from "mime";
+import {
+  getCodeLanguage,
+  getDataLanguage,
+  getLanguageByMime,
+} from "@/lib/languages";
 import { fetchChatFile } from "@/lib/chat/svc";
 import { PreviewContext } from "@/sections/modals/PreviewModal/interfaces";
-import {
-  getMimeLanguage,
-  resolveMimeType,
-} from "@/sections/modals/PreviewModal/mimeUtils";
 import { resolveVariant } from "@/sections/modals/PreviewModal/variants";
 
 interface PreviewModalProps {
@@ -41,7 +42,7 @@ export default function PreviewModal({
   const language = useMemo(
     () =>
       getCodeLanguage(presentingDocument.semantic_identifier || "") ||
-      getMimeLanguage(mimeType) ||
+      getLanguageByMime(mimeType) ||
       getDataLanguage(presentingDocument.semantic_identifier || "") ||
       "plaintext",
     [mimeType, presentingDocument.semantic_identifier]
@@ -86,7 +87,10 @@ export default function PreviewModal({
 
       const rawContentType =
         response.headers.get("Content-Type") || "application/octet-stream";
-      const resolvedMime = resolveMimeType(rawContentType, originalFileName);
+      const resolvedMime =
+        rawContentType === "application/octet-stream"
+          ? mime.getType(originalFileName) ?? rawContentType
+          : rawContentType;
       setMimeType(resolvedMime);
 
       const resolved = resolveVariant(
@@ -166,24 +170,24 @@ export default function PreviewModal({
           onClose={onClose}
         />
 
-        {/* Body + floating footer wrapper */}
-        <Modal.Body padding={0} gap={0}>
-          <Section padding={0} gap={0}>
-            {isLoading ? (
-              <Section>
-                <SimpleLoader className="h-8 w-8" />
-              </Section>
-            ) : loadError ? (
-              <Section padding={1}>
-                <Text text03 mainUiBody>
-                  {loadError}
-                </Text>
-              </Section>
-            ) : (
-              variant.renderContent(ctx)
-            )}
-          </Section>
-        </Modal.Body>
+        {/* Body — uses flex-1/min-h-0/overflow-hidden (not Modal.Body)
+            so that child ScrollIndicatorDivs become the actual scroll
+            container instead of the body stealing it via overflow-y-auto. */}
+        <div className="flex flex-col flex-1 min-h-0 overflow-hidden w-full bg-background-tint-01">
+          {isLoading ? (
+            <Section>
+              <SimpleLoader className="h-8 w-8" />
+            </Section>
+          ) : loadError ? (
+            <Section padding={1}>
+              <Text text03 mainUiBody>
+                {loadError}
+              </Text>
+            </Section>
+          ) : (
+            variant.renderContent(ctx)
+          )}
+        </div>
 
         {/* Floating footer */}
         {!isLoading && !loadError && (
@@ -194,8 +198,9 @@ export default function PreviewModal({
               "p-4 pointer-events-none w-full"
             )}
             style={{
-              background:
-                "linear-gradient(to top, var(--background-code-01) 40%, transparent)",
+              background: `linear-gradient(to top, var(--background-${
+                variant.codeBackground ? "code-01" : "tint-01"
+              }) 40%, transparent)`,
             }}
           >
             {/* Left slot */}
diff --git a/web/src/sections/modals/PreviewModal/interfaces.ts b/web/src/sections/modals/PreviewModal/interfaces.ts
index 880946e8208..d4a141474ca 100644
--- a/web/src/sections/modals/PreviewModal/interfaces.ts
+++ b/web/src/sections/modals/PreviewModal/interfaces.ts
@@ -19,6 +19,8 @@ export interface PreviewVariant
   matches: (semanticIdentifier: string | null, mimeType: string) => boolean;
   /** Whether the fetcher should read the blob as text. */
   needsTextContent: boolean;
+  /** Whether the variant renders on a code-style background (bg-background-code-01). */
+  codeBackground: boolean;
   /** String shown below the title in the modal header. */
   headerDescription: (ctx: PreviewContext) => string;
   /** Body content. */
diff --git a/web/src/sections/modals/PreviewModal/mimeUtils.ts b/web/src/sections/modals/PreviewModal/mimeUtils.ts
deleted file mode 100644
index 2c31c817c6e..00000000000
--- a/web/src/sections/modals/PreviewModal/mimeUtils.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-const MIME_LANGUAGE_PREFIXES: Array<[prefix: string, language: string]> = [
-  ["application/json", "json"],
-  ["application/xml", "xml"],
-  ["text/xml", "xml"],
-  ["application/x-yaml", "yaml"],
-  ["application/yaml", "yaml"],
-  ["text/yaml", "yaml"],
-  ["text/x-yaml", "yaml"],
-];
-
-const OCTET_STREAM_EXTENSION_TO_MIME: Record<string, string> = {
-  ".md": "text/markdown",
-  ".markdown": "text/markdown",
-  ".txt": "text/plain",
-  ".log": "text/plain",
-  ".conf": "text/plain",
-  ".sql": "text/plain",
-  ".csv": "text/csv",
-  ".tsv": "text/tab-separated-values",
-  ".json": "application/json",
-  ".xml": "application/xml",
-  ".yml": "application/x-yaml",
-  ".yaml": "application/x-yaml",
-};
-
-export function getMimeLanguage(mimeType: string): string | null {
-  return (
-    MIME_LANGUAGE_PREFIXES.find(([prefix]) =>
-      mimeType.startsWith(prefix)
-    )?.[1] ?? null
-  );
-}
-
-export function resolveMimeType(mimeType: string, fileName: string): string {
-  if (mimeType !== "application/octet-stream") {
-    return mimeType;
-  }
-
-  const lowerFileName = fileName.toLowerCase();
-
-  for (const [extension, resolvedMime] of Object.entries(
-    OCTET_STREAM_EXTENSION_TO_MIME
-  )) {
-    if (lowerFileName.endsWith(extension)) {
-      return resolvedMime;
-    }
-  }
-
-  return mimeType;
-}
diff --git a/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx b/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx
index f8c4ac12e42..1bffd13588a 100644
--- a/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/CodePreview.tsx
@@ -1,22 +1,37 @@
 "use client";
 
 import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
+import ScrollIndicatorDiv from "@/refresh-components/ScrollIndicatorDiv";
+import { cn } from "@/lib/utils";
 import "@/app/app/message/custom-code-styles.css";
 
 interface CodePreviewProps {
   content: string;
   language?: string | null;
+  normalize?: boolean;
 }
 
-export function CodePreview({ content, language }: CodePreviewProps) {
-  const normalizedContent = content.replace(/~~~/g, "\\~\\~\\~");
-  const fenceHeader = language ? `~~~${language}` : "~~~";
+export function CodePreview({
+  content,
+  language,
+  normalize,
+}: CodePreviewProps) {
+  // Wrap raw content in a fenced code block for syntax highlighting. Uses ~~~
+  // instead of ``` to avoid conflicts with backticks in the content. Any literal
+  // ~~~ sequences in the content are escaped so they don't accidentally close the fence.
+  const markdownContent = normalize
+    ? `~~~${language || ""}\n${content.replace(/~~~/g, "\\~\\~\\~")}\n~~~`
+    : content;
 
   return (
-    <MinimalMarkdown
-      content={`${fenceHeader}\n${normalizedContent}\n\n~~~`}
-      className="w-full h-full"
-      showHeader={false}
-    />
+    <ScrollIndicatorDiv
+      className={cn("p-4", normalize && "bg-background-code-01")}
+      backgroundColor={normalize ? "var(--background-code-01)" : undefined}
+      variant="shadow"
+      bottomSpacing="2rem"
+      disableBottomIndicator
+    >
+      <MinimalMarkdown content={markdownContent} showHeader={false} />
+    </ScrollIndicatorDiv>
   );
 }
diff --git a/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx b/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx
index 1106a44b8ac..ce9c40cea31 100644
--- a/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/codeVariant.tsx
@@ -13,6 +13,7 @@ export const codeVariant: PreviewVariant = {
   width: "md",
   height: "lg",
   needsTextContent: true,
+  codeBackground: true,
 
   headerDescription: (ctx) =>
     ctx.fileContent
@@ -22,7 +23,7 @@ export const codeVariant: PreviewVariant = {
       : "",
 
   renderContent: (ctx) => (
-    <CodePreview content={ctx.fileContent} language={ctx.language} />
+    <CodePreview normalize content={ctx.fileContent} language={ctx.language} />
   ),
 
   renderFooterLeft: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx b/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx
index c9d18954a01..26e51e36425 100644
--- a/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/csvVariant.tsx
@@ -34,6 +34,7 @@ export const csvVariant: PreviewVariant = {
   width: "lg",
   height: "full",
   needsTextContent: true,
+  codeBackground: false,
   headerDescription: (ctx) => {
     if (!ctx.fileContent) return "";
     const { rows } = parseCsv(ctx.fileContent);
diff --git a/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx b/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx
index c5dada9e789..969279ba184 100644
--- a/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/dataVariant.tsx
@@ -1,8 +1,7 @@
 import Text from "@/refresh-components/texts/Text";
 import { Section } from "@/layouts/general-layouts";
-import { getDataLanguage } from "@/lib/languages";
+import { getDataLanguage, getLanguageByMime } from "@/lib/languages";
 import { PreviewVariant } from "@/sections/modals/PreviewModal/interfaces";
-import { getMimeLanguage } from "@/sections/modals/PreviewModal/mimeUtils";
 import { CodePreview } from "@/sections/modals/PreviewModal/variants/CodePreview";
 import {
   CopyButton,
@@ -22,10 +21,11 @@ function formatContent(language: string, content: string): string {
 
 export const dataVariant: PreviewVariant = {
   matches: (name, mime) =>
-    !!getDataLanguage(name || "") || !!getMimeLanguage(mime),
+    !!getDataLanguage(name || "") || !!getLanguageByMime(mime),
   width: "md",
   height: "lg",
   needsTextContent: true,
+  codeBackground: true,
 
   headerDescription: (ctx) =>
     ctx.fileContent
@@ -36,7 +36,9 @@ export const dataVariant: PreviewVariant = {
 
   renderContent: (ctx) => {
     const formatted = formatContent(ctx.language, ctx.fileContent);
-    return <CodePreview content={formatted} language={ctx.language} />;
+    return (
+      <CodePreview normalize content={formatted} language={ctx.language} />
+    );
   },
 
   renderFooterLeft: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx b/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx
index 2cb8a5fc983..1577fdaf76c 100644
--- a/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/docxVariant.tsx
@@ -130,6 +130,7 @@ export const docxVariant: PreviewVariant = {
   width: "lg",
   height: "full",
   needsTextContent: false,
+  codeBackground: false,
   headerDescription: () => {
     if (lastDocxResult) {
       const count = lastDocxResult.wordCount;
diff --git a/web/src/sections/modals/PreviewModal/variants/imageVariant.tsx b/web/src/sections/modals/PreviewModal/variants/imageVariant.tsx
index 7746bd2570e..1be1b3918a8 100644
--- a/web/src/sections/modals/PreviewModal/variants/imageVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/imageVariant.tsx
@@ -11,6 +11,7 @@ export const imageVariant: PreviewVariant = {
   width: "lg",
   height: "full",
   needsTextContent: false,
+  codeBackground: false,
   headerDescription: () => "",
 
   renderContent: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/index.ts b/web/src/sections/modals/PreviewModal/variants/index.ts
index 3f8010ff8b2..43357680662 100644
--- a/web/src/sections/modals/PreviewModal/variants/index.ts
+++ b/web/src/sections/modals/PreviewModal/variants/index.ts
@@ -15,10 +15,10 @@ const PREVIEW_VARIANTS: PreviewVariant[] = [
   imageVariant,
   pdfVariant,
   csvVariant,
-  dataVariant,
-  textVariant,
   markdownVariant,
   docxVariant,
+  textVariant,
+  dataVariant,
 ];
 
 export function resolveVariant(
diff --git a/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx b/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
index d406169ac13..9164d9f395d 100644
--- a/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/markdownVariant.tsx
@@ -1,8 +1,7 @@
-import MinimalMarkdown from "@/components/chat/MinimalMarkdown";
-import ScrollIndicatorDiv from "@/refresh-components/ScrollIndicatorDiv";
 import { Section } from "@/layouts/general-layouts";
 import { isMarkdownFile } from "@/lib/languages";
 import { PreviewVariant } from "@/sections/modals/PreviewModal/interfaces";
+import { CodePreview } from "@/sections/modals/PreviewModal/variants/CodePreview";
 import {
   CopyButton,
   DownloadButton,
@@ -23,15 +22,11 @@ export const markdownVariant: PreviewVariant = {
   width: "lg",
   height: "full",
   needsTextContent: true,
+  codeBackground: false,
   headerDescription: () => "",
 
   renderContent: (ctx) => (
-    <ScrollIndicatorDiv className="flex-1 min-h-0 p-4" variant="shadow">
-      <MinimalMarkdown
-        content={ctx.fileContent}
-        className="w-full pb-4 text-lg break-words"
-      />
-    </ScrollIndicatorDiv>
+    <CodePreview content={ctx.fileContent} language={ctx.language} />
   ),
 
   renderFooterLeft: () => null,
diff --git a/web/src/sections/modals/PreviewModal/variants/pdfVariant.tsx b/web/src/sections/modals/PreviewModal/variants/pdfVariant.tsx
index be6fc04209a..ece8e44ac37 100644
--- a/web/src/sections/modals/PreviewModal/variants/pdfVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/pdfVariant.tsx
@@ -7,6 +7,7 @@ export const pdfVariant: PreviewVariant = {
   width: "lg",
   height: "full",
   needsTextContent: false,
+  codeBackground: false,
   headerDescription: () => "",
 
   renderContent: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/textVariant.tsx b/web/src/sections/modals/PreviewModal/variants/textVariant.tsx
index 1cdd2fa447e..5ff6a63b7af 100644
--- a/web/src/sections/modals/PreviewModal/variants/textVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/textVariant.tsx
@@ -28,6 +28,7 @@ export const textVariant: PreviewVariant = {
   width: "md",
   height: "lg",
   needsTextContent: true,
+  codeBackground: true,
   headerDescription: (ctx) =>
     ctx.fileContent
       ? `${ctx.lineCount} ${ctx.lineCount === 1 ? "line" : "lines"} · ${
@@ -36,7 +37,7 @@ export const textVariant: PreviewVariant = {
       : "",
 
   renderContent: (ctx) => (
-    <CodePreview content={ctx.fileContent} language={ctx.language} />
+    <CodePreview normalize content={ctx.fileContent} language={ctx.language} />
   ),
 
   renderFooterLeft: (ctx) => (
diff --git a/web/src/sections/modals/PreviewModal/variants/unsupportedVariant.tsx b/web/src/sections/modals/PreviewModal/variants/unsupportedVariant.tsx
index 8fca7081958..004da0fcda7 100644
--- a/web/src/sections/modals/PreviewModal/variants/unsupportedVariant.tsx
+++ b/web/src/sections/modals/PreviewModal/variants/unsupportedVariant.tsx
@@ -5,13 +5,14 @@ import { DownloadButton } from "@/sections/modals/PreviewModal/variants/shared";
 
 export const unsupportedVariant: PreviewVariant = {
   matches: () => true,
-  width: "lg",
+  width: "md",
   height: "full",
   needsTextContent: false,
+  codeBackground: false,
   headerDescription: () => "",
 
   renderContent: (ctx) => (
-    <div className="flex flex-col items-center justify-center flex-1 min-h-0 gap-4 p-6">
+    <div className="flex flex-col items-center justify-center flex-1 w-full min-h-0 gap-4 p-6">
       <Text as="p" text03 mainUiBody>
         This file format is not supported for preview.
       </Text>
diff --git a/web/tailwind-themes/tailwind.config.js b/web/tailwind-themes/tailwind.config.js
index ca3d2d75e04..638039e6ae8 100644
--- a/web/tailwind-themes/tailwind.config.js
+++ b/web/tailwind-themes/tailwind.config.js
@@ -260,6 +260,7 @@ module.exports = {
         "code-string": "var(--code-string)",
         "code-number": "var(--code-number)",
         "code-definition": "var(--code-definition)",
+        "background-code-01": "var(--background-code-01)",
 
         // Shimmer colors for loading animations
         "shimmer-base": "var(--shimmer-base)",

From 608491ac363e948613821a6343de8456adccdaac Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Thu, 12 Mar 2026 17:13:01 -0700
Subject: [PATCH 261/267] feat(oidc): Adding PKCE for OIDC (#9128)

---
 backend/onyx/auth/users.py                    | 418 +++++++++++++-----
 backend/onyx/configs/app_configs.py           |   4 +
 backend/onyx/error_handling/exceptions.py     |  28 +-
 backend/onyx/main.py                          |   2 +
 .../tests/unit/onyx/auth/test_oidc_pkce.py    | 400 +++++++++++++++++
 deployment/docker_compose/env.prod.template   |   1 +
 deployment/docker_compose/env.template        |   1 +
 deployment/helm/charts/onyx/values.yaml       |   2 +
 8 files changed, 729 insertions(+), 127 deletions(-)
 create mode 100644 backend/tests/unit/onyx/auth/test_oidc_pkce.py

diff --git a/backend/onyx/auth/users.py b/backend/onyx/auth/users.py
index 6f9c8d5b036..638b74f2822 100644
--- a/backend/onyx/auth/users.py
+++ b/backend/onyx/auth/users.py
@@ -1,3 +1,5 @@
+import base64
+import hashlib
 import json
 import os
 import random
@@ -29,6 +31,7 @@
 from fastapi import Request
 from fastapi import Response
 from fastapi import status
+from fastapi.responses import JSONResponse
 from fastapi.responses import RedirectResponse
 from fastapi.security import OAuth2PasswordRequestForm
 from fastapi_users import BaseUserManager
@@ -55,6 +58,7 @@
 from fastapi_users_db_sqlalchemy import SQLAlchemyUserDatabase
 from httpx_oauth.integrations.fastapi import OAuth2AuthorizeCallback
 from httpx_oauth.oauth2 import BaseOAuth2
+from httpx_oauth.oauth2 import GetAccessTokenError
 from httpx_oauth.oauth2 import OAuth2Token
 from pydantic import BaseModel
 from sqlalchemy import nulls_last
@@ -120,6 +124,10 @@
 from onyx.db.models import User
 from onyx.db.pat import fetch_user_for_pat
 from onyx.db.users import get_user_by_email
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import log_onyx_error
+from onyx.error_handling.exceptions import onyx_error_to_json_response
+from onyx.error_handling.exceptions import OnyxError
 from onyx.redis.redis_pool import get_async_redis_connection
 from onyx.server.settings.store import load_settings
 from onyx.server.utils import BasicAuthenticationError
@@ -1621,6 +1629,7 @@ def get_default_admin_user_emails_() -> list[str]:
 STATE_TOKEN_LIFETIME_SECONDS = 3600
 CSRF_TOKEN_KEY = "csrftoken"
 CSRF_TOKEN_COOKIE_NAME = "fastapiusersoauthcsrf"
+PKCE_COOKIE_NAME_PREFIX = "fastapiusersoauthpkce"
 
 
 class OAuth2AuthorizeResponse(BaseModel):
@@ -1641,6 +1650,21 @@ def generate_csrf_token() -> str:
     return secrets.token_urlsafe(32)
 
 
+def _base64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def generate_pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(64)
+    challenge = _base64url_encode(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+def get_pkce_cookie_name(state: str) -> str:
+    state_hash = hashlib.sha256(state.encode("utf-8")).hexdigest()
+    return f"{PKCE_COOKIE_NAME_PREFIX}_{state_hash}"
+
+
 # refer to https://github.com/fastapi-users/fastapi-users/blob/42ddc241b965475390e2bce887b084152ae1a2cd/fastapi_users/fastapi_users.py#L91
 def create_onyx_oauth_router(
     oauth_client: BaseOAuth2,
@@ -1649,6 +1673,7 @@ def create_onyx_oauth_router(
     redirect_url: Optional[str] = None,
     associate_by_email: bool = False,
     is_verified_by_default: bool = False,
+    enable_pkce: bool = False,
 ) -> APIRouter:
     return get_oauth_router(
         oauth_client,
@@ -1658,6 +1683,7 @@ def create_onyx_oauth_router(
         redirect_url,
         associate_by_email,
         is_verified_by_default,
+        enable_pkce=enable_pkce,
     )
 
 
@@ -1676,6 +1702,7 @@ def get_oauth_router(
     csrf_token_cookie_secure: Optional[bool] = None,
     csrf_token_cookie_httponly: bool = True,
     csrf_token_cookie_samesite: Optional[Literal["lax", "strict", "none"]] = "lax",
+    enable_pkce: bool = False,
 ) -> APIRouter:
     """Generate a router with the OAuth routes."""
     router = APIRouter()
@@ -1692,6 +1719,13 @@ def get_oauth_router(
             route_name=callback_route_name,
         )
 
+    async def null_access_token_state() -> tuple[OAuth2Token, Optional[str]] | None:
+        return None
+
+    access_token_state_dependency = (
+        oauth2_authorize_callback if not enable_pkce else null_access_token_state
+    )
+
     if csrf_token_cookie_secure is None:
         csrf_token_cookie_secure = WEB_DOMAIN.startswith("https")
 
@@ -1725,13 +1759,26 @@ async def authorize(
             CSRF_TOKEN_KEY: csrf_token,
         }
         state = generate_state_token(state_data, state_secret)
-
-        # Get the basic authorization URL
-        authorization_url = await oauth_client.get_authorization_url(
-            authorize_redirect_url,
-            state,
-            scopes,
-        )
+        pkce_cookie: tuple[str, str] | None = None
+
+        if enable_pkce:
+            code_verifier, code_challenge = generate_pkce_pair()
+            pkce_cookie_name = get_pkce_cookie_name(state)
+            pkce_cookie = (pkce_cookie_name, code_verifier)
+            authorization_url = await oauth_client.get_authorization_url(
+                authorize_redirect_url,
+                state,
+                scopes,
+                code_challenge=code_challenge,
+                code_challenge_method="S256",
+            )
+        else:
+            # Get the basic authorization URL
+            authorization_url = await oauth_client.get_authorization_url(
+                authorize_redirect_url,
+                state,
+                scopes,
+            )
 
         # For Google OAuth, add parameters to request refresh tokens
         if oauth_client.name == "google":
@@ -1739,11 +1786,15 @@ async def authorize(
                 authorization_url, {"access_type": "offline", "prompt": "consent"}
             )
 
-        if redirect:
-            redirect_response = RedirectResponse(authorization_url, status_code=302)
-            redirect_response.set_cookie(
-                key=csrf_token_cookie_name,
-                value=csrf_token,
+        def set_oauth_cookie(
+            target_response: Response,
+            *,
+            key: str,
+            value: str,
+        ) -> None:
+            target_response.set_cookie(
+                key=key,
+                value=value,
                 max_age=STATE_TOKEN_LIFETIME_SECONDS,
                 path=csrf_token_cookie_path,
                 domain=csrf_token_cookie_domain,
@@ -1751,18 +1802,28 @@ async def authorize(
                 httponly=csrf_token_cookie_httponly,
                 samesite=csrf_token_cookie_samesite,
             )
-            return redirect_response
 
-        response.set_cookie(
+        response_with_cookies: Response
+        if redirect:
+            response_with_cookies = RedirectResponse(authorization_url, status_code=302)
+        else:
+            response_with_cookies = response
+
+        set_oauth_cookie(
+            response_with_cookies,
             key=csrf_token_cookie_name,
             value=csrf_token,
-            max_age=STATE_TOKEN_LIFETIME_SECONDS,
-            path=csrf_token_cookie_path,
-            domain=csrf_token_cookie_domain,
-            secure=csrf_token_cookie_secure,
-            httponly=csrf_token_cookie_httponly,
-            samesite=csrf_token_cookie_samesite,
         )
+        if pkce_cookie is not None:
+            pkce_cookie_name, code_verifier = pkce_cookie
+            set_oauth_cookie(
+                response_with_cookies,
+                key=pkce_cookie_name,
+                value=code_verifier,
+            )
+
+        if redirect:
+            return response_with_cookies
 
         return OAuth2AuthorizeResponse(authorization_url=authorization_url)
 
@@ -1793,119 +1854,242 @@ async def authorize(
     )
     async def callback(
         request: Request,
-        access_token_state: Tuple[OAuth2Token, str] = Depends(
-            oauth2_authorize_callback
+        access_token_state: Tuple[OAuth2Token, Optional[str]] | None = Depends(
+            access_token_state_dependency
         ),
+        code: Optional[str] = None,
+        state: Optional[str] = None,
+        error: Optional[str] = None,
         user_manager: BaseUserManager[models.UP, models.ID] = Depends(get_user_manager),
         strategy: Strategy[models.UP, models.ID] = Depends(backend.get_strategy),
-    ) -> RedirectResponse:
-        token, state = access_token_state
-        account_id, account_email = await oauth_client.get_id_email(
-            token["access_token"]
-        )
+    ) -> Response:
+        pkce_cookie_name: str | None = None
 
-        if account_email is None:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=ErrorCode.OAUTH_NOT_AVAILABLE_EMAIL,
-            )
+        def delete_pkce_cookie(response: Response) -> None:
+            if enable_pkce and pkce_cookie_name:
+                response.delete_cookie(
+                    key=pkce_cookie_name,
+                    path=csrf_token_cookie_path,
+                    domain=csrf_token_cookie_domain,
+                    secure=csrf_token_cookie_secure,
+                    httponly=csrf_token_cookie_httponly,
+                    samesite=csrf_token_cookie_samesite,
+                )
 
-        try:
-            state_data = decode_jwt(state, state_secret, [STATE_TOKEN_AUDIENCE])
-        except jwt.DecodeError:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=getattr(
-                    ErrorCode, "ACCESS_TOKEN_DECODE_ERROR", "ACCESS_TOKEN_DECODE_ERROR"
-                ),
-            )
-        except jwt.ExpiredSignatureError:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=getattr(
-                    ErrorCode,
-                    "ACCESS_TOKEN_ALREADY_EXPIRED",
-                    "ACCESS_TOKEN_ALREADY_EXPIRED",
-                ),
-            )
+        def build_error_response(exc: OnyxError) -> JSONResponse:
+            log_onyx_error(exc)
+            error_response = onyx_error_to_json_response(exc)
+            delete_pkce_cookie(error_response)
+            return error_response
 
-        cookie_csrf_token = request.cookies.get(csrf_token_cookie_name)
-        state_csrf_token = state_data.get(CSRF_TOKEN_KEY)
-        if (
-            not cookie_csrf_token
-            or not state_csrf_token
-            or not secrets.compare_digest(cookie_csrf_token, state_csrf_token)
-        ):
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=getattr(ErrorCode, "OAUTH_INVALID_STATE", "OAUTH_INVALID_STATE"),
-            )
+        def decode_and_validate_state(state_value: str) -> Dict[str, str]:
+            try:
+                state_data = decode_jwt(
+                    state_value, state_secret, [STATE_TOKEN_AUDIENCE]
+                )
+            except jwt.DecodeError:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    getattr(
+                        ErrorCode,
+                        "ACCESS_TOKEN_DECODE_ERROR",
+                        "ACCESS_TOKEN_DECODE_ERROR",
+                    ),
+                )
+            except jwt.ExpiredSignatureError:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    getattr(
+                        ErrorCode,
+                        "ACCESS_TOKEN_ALREADY_EXPIRED",
+                        "ACCESS_TOKEN_ALREADY_EXPIRED",
+                    ),
+                )
+            except jwt.PyJWTError:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    getattr(
+                        ErrorCode,
+                        "ACCESS_TOKEN_DECODE_ERROR",
+                        "ACCESS_TOKEN_DECODE_ERROR",
+                    ),
+                )
 
-        next_url = state_data.get("next_url", "/")
-        referral_source = state_data.get("referral_source", None)
-        try:
-            tenant_id = fetch_ee_implementation_or_noop(
-                "onyx.server.tenants.user_mapping", "get_tenant_id_for_email", None
-            )(account_email)
-        except exceptions.UserNotExists:
-            tenant_id = None
+            cookie_csrf_token = request.cookies.get(csrf_token_cookie_name)
+            state_csrf_token = state_data.get(CSRF_TOKEN_KEY)
+            if (
+                not cookie_csrf_token
+                or not state_csrf_token
+                or not secrets.compare_digest(cookie_csrf_token, state_csrf_token)
+            ):
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    getattr(ErrorCode, "OAUTH_INVALID_STATE", "OAUTH_INVALID_STATE"),
+                )
 
-        request.state.referral_source = referral_source
+            return state_data
 
-        # Proceed to authenticate or create the user
-        try:
-            user = await user_manager.oauth_callback(
-                oauth_client.name,
-                token["access_token"],
-                account_id,
-                account_email,
-                token.get("expires_at"),
-                token.get("refresh_token"),
-                request,
-                associate_by_email=associate_by_email,
-                is_verified_by_default=is_verified_by_default,
-            )
-        except UserAlreadyExists:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=ErrorCode.OAUTH_USER_ALREADY_EXISTS,
-            )
+        token: OAuth2Token
+        state_data: Dict[str, str]
 
-        if not user.is_active:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=ErrorCode.LOGIN_BAD_CREDENTIALS,
-            )
+        # `code`, `state`, and `error` are read directly only in the PKCE path.
+        # In the non-PKCE path, `oauth2_authorize_callback` consumes them.
+        if enable_pkce:
+            if state is not None:
+                pkce_cookie_name = get_pkce_cookie_name(state)
+
+            if error is not None:
+                return build_error_response(
+                    OnyxError(
+                        OnyxErrorCode.VALIDATION_ERROR,
+                        "Authorization request failed or was denied",
+                    )
+                )
+            if code is None:
+                return build_error_response(
+                    OnyxError(
+                        OnyxErrorCode.VALIDATION_ERROR,
+                        "Missing authorization code in OAuth callback",
+                    )
+                )
+            if state is None:
+                return build_error_response(
+                    OnyxError(
+                        OnyxErrorCode.VALIDATION_ERROR,
+                        "Missing state parameter in OAuth callback",
+                    )
+                )
 
-        # Login user
-        response = await backend.login(strategy, user)
-        await user_manager.on_after_login(user, request, response)
+            state_value = state
 
-        # Prepare redirect response
-        if tenant_id is None:
-            # Use URL utility to add parameters
-            redirect_url = add_url_params(next_url, {"new_team": "true"})
-            redirect_response = RedirectResponse(redirect_url, status_code=302)
+            if redirect_url is not None:
+                callback_redirect_url = redirect_url
+            else:
+                callback_path = request.app.url_path_for(callback_route_name)
+                callback_redirect_url = f"{WEB_DOMAIN}{callback_path}"
+
+            code_verifier = request.cookies.get(cast(str, pkce_cookie_name))
+            if not code_verifier:
+                return build_error_response(
+                    OnyxError(
+                        OnyxErrorCode.VALIDATION_ERROR,
+                        "Missing PKCE verifier cookie in OAuth callback",
+                    )
+                )
+
+            try:
+                state_data = decode_and_validate_state(state_value)
+            except OnyxError as e:
+                return build_error_response(e)
+
+            try:
+                token = await oauth_client.get_access_token(
+                    code, callback_redirect_url, code_verifier
+                )
+            except GetAccessTokenError:
+                return build_error_response(
+                    OnyxError(
+                        OnyxErrorCode.VALIDATION_ERROR,
+                        "Authorization code exchange failed",
+                    )
+                )
         else:
-            # No parameters to add
-            redirect_response = RedirectResponse(next_url, status_code=302)
-
-        # Copy headers from auth response to redirect response, with special handling for Set-Cookie
-        for header_name, header_value in response.headers.items():
-            # FastAPI can have multiple Set-Cookie headers as a list
-            if header_name.lower() == "set-cookie" and isinstance(header_value, list):
-                for cookie_value in header_value:
-                    redirect_response.headers.append(header_name, cookie_value)
+            if access_token_state is None:
+                raise OnyxError(
+                    OnyxErrorCode.INTERNAL_ERROR, "Missing OAuth callback state"
+                )
+            token, callback_state = access_token_state
+            if callback_state is None:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    "Missing state parameter in OAuth callback",
+                )
+            state_data = decode_and_validate_state(callback_state)
+
+        async def complete_login_flow(
+            token: OAuth2Token, state_data: Dict[str, str]
+        ) -> RedirectResponse:
+            account_id, account_email = await oauth_client.get_id_email(
+                token["access_token"]
+            )
+
+            if account_email is None:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    ErrorCode.OAUTH_NOT_AVAILABLE_EMAIL,
+                )
+
+            next_url = state_data.get("next_url", "/")
+            referral_source = state_data.get("referral_source", None)
+            try:
+                tenant_id = fetch_ee_implementation_or_noop(
+                    "onyx.server.tenants.user_mapping", "get_tenant_id_for_email", None
+                )(account_email)
+            except exceptions.UserNotExists:
+                tenant_id = None
+
+            request.state.referral_source = referral_source
+
+            # Proceed to authenticate or create the user
+            try:
+                user = await user_manager.oauth_callback(
+                    oauth_client.name,
+                    token["access_token"],
+                    account_id,
+                    account_email,
+                    token.get("expires_at"),
+                    token.get("refresh_token"),
+                    request,
+                    associate_by_email=associate_by_email,
+                    is_verified_by_default=is_verified_by_default,
+                )
+            except UserAlreadyExists:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    ErrorCode.OAUTH_USER_ALREADY_EXISTS,
+                )
+
+            if not user.is_active:
+                raise OnyxError(
+                    OnyxErrorCode.VALIDATION_ERROR,
+                    ErrorCode.LOGIN_BAD_CREDENTIALS,
+                )
+
+            # Login user
+            response = await backend.login(strategy, user)
+            await user_manager.on_after_login(user, request, response)
+
+            # Prepare redirect response
+            if tenant_id is None:
+                # Use URL utility to add parameters
+                redirect_destination = add_url_params(next_url, {"new_team": "true"})
+                redirect_response = RedirectResponse(
+                    redirect_destination, status_code=302
+                )
             else:
+                # No parameters to add
+                redirect_response = RedirectResponse(next_url, status_code=302)
+
+            # Copy headers from auth response to redirect response, with special handling for Set-Cookie
+            for header_name, header_value in response.headers.items():
+                header_name_lower = header_name.lower()
+                if header_name_lower == "set-cookie":
+                    redirect_response.headers.append(header_name, header_value)
+                    continue
+                if header_name_lower in {"location", "content-length"}:
+                    continue
                 redirect_response.headers[header_name] = header_value
 
-        if hasattr(response, "body"):
-            redirect_response.body = response.body
-        if hasattr(response, "status_code"):
-            redirect_response.status_code = response.status_code
-        if hasattr(response, "media_type"):
-            redirect_response.media_type = response.media_type
+            return redirect_response
+
+        if enable_pkce:
+            try:
+                redirect_response = await complete_login_flow(token, state_data)
+            except OnyxError as e:
+                return build_error_response(e)
+            delete_pkce_cookie(redirect_response)
+            return redirect_response
 
-        return redirect_response
+        return await complete_login_flow(token, state_data)
 
     return router
diff --git a/backend/onyx/configs/app_configs.py b/backend/onyx/configs/app_configs.py
index 93d5a7997b1..9cac16fd1df 100644
--- a/backend/onyx/configs/app_configs.py
+++ b/backend/onyx/configs/app_configs.py
@@ -196,6 +196,10 @@
     except Exception:
         pass
 
+# Enables PKCE for OIDC login flow. Disabled by default to preserve
+# backwards compatibility for existing OIDC deployments.
+OIDC_PKCE_ENABLED = os.environ.get("OIDC_PKCE_ENABLED", "").lower() == "true"
+
 # Applicable for SAML Auth
 SAML_CONF_DIR = os.environ.get("SAML_CONF_DIR") or "/app/onyx/configs/saml_config"
 
diff --git a/backend/onyx/error_handling/exceptions.py b/backend/onyx/error_handling/exceptions.py
index 7ba448ecc70..357c82c26bf 100644
--- a/backend/onyx/error_handling/exceptions.py
+++ b/backend/onyx/error_handling/exceptions.py
@@ -59,6 +59,22 @@ def status_code(self) -> int:
         return self._status_code_override or self.error_code.status_code
 
 
+def log_onyx_error(exc: OnyxError) -> None:
+    detail = exc.detail
+    status_code = exc.status_code
+    if status_code >= 500:
+        logger.error(f"OnyxError {exc.error_code.code}: {detail}")
+    elif status_code >= 400:
+        logger.warning(f"OnyxError {exc.error_code.code}: {detail}")
+
+
+def onyx_error_to_json_response(exc: OnyxError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=exc.error_code.detail(exc.detail),
+    )
+
+
 def register_onyx_exception_handlers(app: FastAPI) -> None:
     """Register a global handler that converts ``OnyxError`` to JSON responses.
 
@@ -71,13 +87,5 @@ async def _handle_onyx_error(
         request: Request,  # noqa: ARG001
         exc: OnyxError,
     ) -> JSONResponse:
-        status_code = exc.status_code
-        if status_code >= 500:
-            logger.error(f"OnyxError {exc.error_code.code}: {exc.detail}")
-        elif status_code >= 400:
-            logger.warning(f"OnyxError {exc.error_code.code}: {exc.detail}")
-
-        return JSONResponse(
-            status_code=status_code,
-            content=exc.error_code.detail(exc.detail),
-        )
+        log_onyx_error(exc)
+        return onyx_error_to_json_response(exc)
diff --git a/backend/onyx/main.py b/backend/onyx/main.py
index f457159695c..d7bd83cd7a9 100644
--- a/backend/onyx/main.py
+++ b/backend/onyx/main.py
@@ -44,6 +44,7 @@
 from onyx.configs.app_configs import OAUTH_CLIENT_ID
 from onyx.configs.app_configs import OAUTH_CLIENT_SECRET
 from onyx.configs.app_configs import OAUTH_ENABLED
+from onyx.configs.app_configs import OIDC_PKCE_ENABLED
 from onyx.configs.app_configs import OIDC_SCOPE_OVERRIDE
 from onyx.configs.app_configs import OPENID_CONFIG_URL
 from onyx.configs.app_configs import POSTGRES_API_SERVER_POOL_OVERFLOW
@@ -597,6 +598,7 @@ def get_application(lifespan_override: Lifespan | None = None) -> FastAPI:
                 associate_by_email=True,
                 is_verified_by_default=True,
                 redirect_url=f"{WEB_DOMAIN}/auth/oidc/callback",
+                enable_pkce=OIDC_PKCE_ENABLED,
             ),
             prefix="/auth/oidc",
         )
diff --git a/backend/tests/unit/onyx/auth/test_oidc_pkce.py b/backend/tests/unit/onyx/auth/test_oidc_pkce.py
new file mode 100644
index 00000000000..abc3d86c63e
--- /dev/null
+++ b/backend/tests/unit/onyx/auth/test_oidc_pkce.py
@@ -0,0 +1,400 @@
+from typing import Any
+from typing import cast
+from unittest.mock import AsyncMock
+from unittest.mock import MagicMock
+from unittest.mock import patch
+from urllib.parse import parse_qs
+from urllib.parse import urlparse
+
+from fastapi import FastAPI
+from fastapi import Response
+from fastapi.testclient import TestClient
+from fastapi_users.authentication import AuthenticationBackend
+from fastapi_users.authentication import CookieTransport
+from fastapi_users.jwt import generate_jwt
+from httpx_oauth.oauth2 import BaseOAuth2
+from httpx_oauth.oauth2 import GetAccessTokenError
+
+from onyx.auth.users import CSRF_TOKEN_COOKIE_NAME
+from onyx.auth.users import CSRF_TOKEN_KEY
+from onyx.auth.users import get_oauth_router
+from onyx.auth.users import get_pkce_cookie_name
+from onyx.auth.users import PKCE_COOKIE_NAME_PREFIX
+from onyx.auth.users import STATE_TOKEN_AUDIENCE
+from onyx.error_handling.exceptions import register_onyx_exception_handlers
+
+
+class _StubOAuthClient:
+    def __init__(self) -> None:
+        self.name = "openid"
+        self.authorization_calls: list[dict[str, str | list[str] | None]] = []
+        self.access_token_calls: list[dict[str, str | None]] = []
+
+    async def get_authorization_url(
+        self,
+        redirect_uri: str,
+        state: str | None = None,
+        scope: list[str] | None = None,
+        code_challenge: str | None = None,
+        code_challenge_method: str | None = None,
+    ) -> str:
+        self.authorization_calls.append(
+            {
+                "redirect_uri": redirect_uri,
+                "state": state,
+                "scope": scope,
+                "code_challenge": code_challenge,
+                "code_challenge_method": code_challenge_method,
+            }
+        )
+        return f"https://idp.example.com/authorize?state={state}"
+
+    async def get_access_token(
+        self, code: str, redirect_uri: str, code_verifier: str | None = None
+    ) -> dict[str, str | int]:
+        self.access_token_calls.append(
+            {
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "code_verifier": code_verifier,
+            }
+        )
+        return {
+            "access_token": "oidc_access_token",
+            "refresh_token": "oidc_refresh_token",
+            "expires_at": 1730000000,
+        }
+
+    async def get_id_email(self, _access_token: str) -> tuple[str, str | None]:
+        return ("oidc_account_id", "oidc_user@example.com")
+
+
+def _build_test_client(
+    enable_pkce: bool,
+    login_status_code: int = 302,
+) -> tuple[TestClient, _StubOAuthClient, MagicMock]:
+    oauth_client = _StubOAuthClient()
+    transport = CookieTransport(cookie_name="testsession")
+
+    async def get_strategy() -> MagicMock:
+        return MagicMock()
+
+    backend = AuthenticationBackend(
+        name="test_backend",
+        transport=transport,
+        get_strategy=get_strategy,
+    )
+
+    login_response = Response(status_code=login_status_code)
+    if login_status_code in {301, 302, 303, 307, 308}:
+        login_response.headers["location"] = "/app"
+    login_response.set_cookie("testsession", "session-token")
+    backend.login = AsyncMock(return_value=login_response)  # type: ignore[method-assign]
+
+    user = MagicMock()
+    user.is_active = True
+    user_manager = MagicMock()
+    user_manager.oauth_callback = AsyncMock(return_value=user)
+    user_manager.on_after_login = AsyncMock()
+
+    async def get_user_manager() -> MagicMock:
+        return user_manager
+
+    router = get_oauth_router(
+        oauth_client=cast(BaseOAuth2[Any], oauth_client),
+        backend=backend,
+        get_user_manager=get_user_manager,
+        state_secret="test-secret",
+        redirect_url="http://localhost/auth/oidc/callback",
+        associate_by_email=True,
+        is_verified_by_default=True,
+        enable_pkce=enable_pkce,
+    )
+    app = FastAPI()
+    app.include_router(router, prefix="/auth/oidc")
+    register_onyx_exception_handlers(app)
+
+    client = TestClient(app, raise_server_exceptions=False)
+    return client, oauth_client, user_manager
+
+
+def _extract_state_from_authorize_response(response: Any) -> str:
+    auth_url = response.json()["authorization_url"]
+    return parse_qs(urlparse(auth_url).query)["state"][0]
+
+
+def test_oidc_authorize_omits_pkce_when_flag_disabled() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=False)
+
+    response = client.get("/auth/oidc/authorize")
+
+    assert response.status_code == 200
+    assert oauth_client.authorization_calls[0]["code_challenge"] is None
+    assert oauth_client.authorization_calls[0]["code_challenge_method"] is None
+    assert "fastapiusersoauthcsrf" in response.cookies.keys()
+    assert not any(
+        key.startswith(PKCE_COOKIE_NAME_PREFIX) for key in response.cookies.keys()
+    )
+
+
+def test_oidc_authorize_adds_pkce_when_flag_enabled() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+
+    response = client.get("/auth/oidc/authorize")
+
+    assert response.status_code == 200
+    assert oauth_client.authorization_calls[0]["code_challenge"] is not None
+    assert oauth_client.authorization_calls[0]["code_challenge_method"] == "S256"
+    assert any(
+        key.startswith(PKCE_COOKIE_NAME_PREFIX) for key in response.cookies.keys()
+    )
+
+
+def test_oidc_callback_fails_when_pkce_cookie_missing() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    for key in list(client.cookies.keys()):
+        if key.startswith(PKCE_COOKIE_NAME_PREFIX):
+            del client.cookies[key]
+
+    response = client.get(
+        "/auth/oidc/callback", params={"code": "abc123", "state": state}
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert oauth_client.access_token_calls == []
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_rejects_bad_state_before_token_exchange() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    client.get("/auth/oidc/authorize")
+    tampered_state = "not-a-valid-state-jwt"
+    client.cookies.set(get_pkce_cookie_name(tampered_state), "verifier123")
+
+    response = client.get(
+        "/auth/oidc/callback", params={"code": "abc123", "state": tampered_state}
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert oauth_client.access_token_calls == []
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_rejects_wrongly_signed_state_before_token_exchange() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    client.get("/auth/oidc/authorize")
+    csrf_token = client.cookies.get(CSRF_TOKEN_COOKIE_NAME)
+    assert csrf_token is not None
+    tampered_state = generate_jwt(
+        {
+            "aud": STATE_TOKEN_AUDIENCE,
+            CSRF_TOKEN_KEY: csrf_token,
+        },
+        "wrong-secret",
+        3600,
+    )
+    client.cookies.set(get_pkce_cookie_name(tampered_state), "verifier123")
+
+    response = client.get(
+        "/auth/oidc/callback",
+        params={"code": "abc123", "state": tampered_state},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert response.json()["detail"] == "ACCESS_TOKEN_DECODE_ERROR"
+    assert oauth_client.access_token_calls == []
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_rejects_csrf_mismatch_in_pkce_path() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    # Keep PKCE verifier cookie intact, but invalidate CSRF match against state JWT.
+    client.cookies.set("fastapiusersoauthcsrf", "wrong-csrf-token")
+
+    response = client.get(
+        "/auth/oidc/callback",
+        params={"code": "abc123", "state": state},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert oauth_client.access_token_calls == []
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_get_access_token_error_is_400() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+    with patch.object(
+        oauth_client,
+        "get_access_token",
+        AsyncMock(side_effect=GetAccessTokenError("token exchange failed")),
+    ):
+        response = client.get(
+            "/auth/oidc/callback", params={"code": "abc123", "state": state}
+        )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert response.json()["detail"] == "Authorization code exchange failed"
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_cleans_pkce_cookie_on_idp_error_with_state() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    response = client.get(
+        "/auth/oidc/callback",
+        params={"error": "access_denied", "state": state},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert response.json()["detail"] == "Authorization request failed or was denied"
+    assert oauth_client.access_token_calls == []
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_cleans_pkce_cookie_on_missing_email() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    with patch.object(
+        oauth_client, "get_id_email", AsyncMock(return_value=("oidc_account_id", None))
+    ):
+        response = client.get(
+            "/auth/oidc/callback", params={"code": "abc123", "state": state}
+        )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_rejects_wrong_audience_state_before_token_exchange() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=True)
+    client.get("/auth/oidc/authorize")
+    csrf_token = client.cookies.get(CSRF_TOKEN_COOKIE_NAME)
+    assert csrf_token is not None
+    wrong_audience_state = generate_jwt(
+        {
+            "aud": "wrong-audience",
+            CSRF_TOKEN_KEY: csrf_token,
+        },
+        "test-secret",
+        3600,
+    )
+    client.cookies.set(get_pkce_cookie_name(wrong_audience_state), "verifier123")
+
+    response = client.get(
+        "/auth/oidc/callback",
+        params={"code": "abc123", "state": wrong_audience_state},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert response.json()["detail"] == "ACCESS_TOKEN_DECODE_ERROR"
+    assert oauth_client.access_token_calls == []
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_uses_code_verifier_when_pkce_enabled() -> None:
+    client, oauth_client, user_manager = _build_test_client(enable_pkce=True)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    with patch(
+        "onyx.auth.users.fetch_ee_implementation_or_noop",
+        return_value=lambda _email: "tenant_1",
+    ):
+        response = client.get(
+            "/auth/oidc/callback",
+            params={"code": "abc123", "state": state},
+            follow_redirects=False,
+        )
+
+    assert response.status_code == 302
+    assert response.headers.get("location") == "/"
+    assert oauth_client.access_token_calls[0]["code_verifier"] is not None
+    user_manager.oauth_callback.assert_awaited_once()
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_works_without_pkce_when_flag_disabled() -> None:
+    client, oauth_client, user_manager = _build_test_client(enable_pkce=False)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    with patch(
+        "onyx.auth.users.fetch_ee_implementation_or_noop",
+        return_value=lambda _email: "tenant_1",
+    ):
+        response = client.get(
+            "/auth/oidc/callback",
+            params={"code": "abc123", "state": state},
+            follow_redirects=False,
+        )
+
+    assert response.status_code == 302
+    assert oauth_client.access_token_calls[0]["code_verifier"] is None
+    user_manager.oauth_callback.assert_awaited_once()
+
+
+def test_oidc_callback_pkce_preserves_redirect_when_backend_login_is_non_redirect() -> (
+    None
+):
+    client, oauth_client, user_manager = _build_test_client(
+        enable_pkce=True,
+        login_status_code=200,
+    )
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    with patch(
+        "onyx.auth.users.fetch_ee_implementation_or_noop",
+        return_value=lambda _email: "tenant_1",
+    ):
+        response = client.get(
+            "/auth/oidc/callback",
+            params={"code": "abc123", "state": state},
+            follow_redirects=False,
+        )
+
+    assert response.status_code == 302
+    assert response.headers.get("location") == "/"
+    assert oauth_client.access_token_calls[0]["code_verifier"] is not None
+    user_manager.oauth_callback.assert_awaited_once()
+    assert "Max-Age=0" in response.headers.get("set-cookie", "")
+
+
+def test_oidc_callback_non_pkce_rejects_csrf_mismatch() -> None:
+    client, oauth_client, _ = _build_test_client(enable_pkce=False)
+    authorize_response = client.get("/auth/oidc/authorize")
+    state = _extract_state_from_authorize_response(authorize_response)
+
+    client.cookies.set(CSRF_TOKEN_COOKIE_NAME, "wrong-csrf-token")
+
+    response = client.get(
+        "/auth/oidc/callback",
+        params={"code": "abc123", "state": state},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+    assert response.json()["detail"] == "OAUTH_INVALID_STATE"
+    # NOTE: In the non-PKCE path, oauth2_authorize_callback exchanges the code
+    # before route-body CSRF validation runs. This is a known ordering trade-off.
+    assert oauth_client.access_token_calls
diff --git a/deployment/docker_compose/env.prod.template b/deployment/docker_compose/env.prod.template
index 014146553f4..7cceaa96984 100644
--- a/deployment/docker_compose/env.prod.template
+++ b/deployment/docker_compose/env.prod.template
@@ -33,6 +33,7 @@ SECRET=
 
 # OpenID Connect (OIDC)
 #OPENID_CONFIG_URL=
+#OIDC_PKCE_ENABLED=
 
 # SAML config directory for OneLogin compatible setups
 #SAML_CONF_DIR=
diff --git a/deployment/docker_compose/env.template b/deployment/docker_compose/env.template
index e5c882c7a0d..39f9503ce4e 100644
--- a/deployment/docker_compose/env.template
+++ b/deployment/docker_compose/env.template
@@ -167,6 +167,7 @@ LOG_ONYX_MODEL_INTERACTIONS=False
 # OAUTH_CLIENT_ID=
 # OAUTH_CLIENT_SECRET=
 # OPENID_CONFIG_URL=
+# OIDC_PKCE_ENABLED=
 # TRACK_EXTERNAL_IDP_EXPIRY=
 # CORS_ALLOWED_ORIGIN=
 # INTEGRATION_TESTS_MODE=
diff --git a/deployment/helm/charts/onyx/values.yaml b/deployment/helm/charts/onyx/values.yaml
index 50cdf8dd06e..8b1c37e9704 100644
--- a/deployment/helm/charts/onyx/values.yaml
+++ b/deployment/helm/charts/onyx/values.yaml
@@ -1203,6 +1203,8 @@ configMap:
   # UPGRADE NOTE: Default changed from "disabled" to "basic" in 0.4.34.
   # You must also set auth.userauth.values.user_auth_secret.
   AUTH_TYPE: "basic"
+  # Enable PKCE for OIDC login flow. Leave empty/false for backward compatibility.
+  OIDC_PKCE_ENABLED: ""
   # 1 Day Default
   SESSION_EXPIRE_TIME_SECONDS: "86400"
   # Can be something like onyx.app, as an extra double-check

From 196b6b0514041534703b0cd2275d48bbd8b0ff7b Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Thu, 12 Mar 2026 17:16:25 -0700
Subject: [PATCH 262/267] fix(cherry-pick): Improving workflows (#9316)

---
 .../workflows/post-merge-beta-cherry-pick.yml | 169 ++++++++++++------
 1 file changed, 119 insertions(+), 50 deletions(-)

diff --git a/.github/workflows/post-merge-beta-cherry-pick.yml b/.github/workflows/post-merge-beta-cherry-pick.yml
index 600e4ee6f29..5e84e652d3c 100644
--- a/.github/workflows/post-merge-beta-cherry-pick.yml
+++ b/.github/workflows/post-merge-beta-cherry-pick.yml
@@ -1,67 +1,102 @@
 name: Post-Merge Beta Cherry-Pick
 
 on:
-  push:
-    branches:
-      - main
-
+  pull_request_target:
+    types:
+      - closed
+
+# SECURITY NOTE:
+# This workflow intentionally uses pull_request_target so post-merge automation can
+# use base-repo credentials. Do not checkout PR head refs in this workflow
+# (e.g. github.event.pull_request.head.sha). Only trusted base refs are allowed.
 permissions:
   contents: read
 
 jobs:
-  cherry-pick-to-latest-release:
-    permissions:
-      contents: write
-      pull-requests: write
+  resolve-cherry-pick-request:
+    if: >-
+      github.event.pull_request.merged == true
+      && github.event.pull_request.base.ref == 'main'
+      && github.event.pull_request.head.repo.full_name == github.repository
     outputs:
       should_cherrypick: ${{ steps.gate.outputs.should_cherrypick }}
       pr_number: ${{ steps.gate.outputs.pr_number }}
-      cherry_pick_reason: ${{ steps.run_cherry_pick.outputs.reason }}
-      cherry_pick_details: ${{ steps.run_cherry_pick.outputs.details }}
+      merge_commit_sha: ${{ steps.gate.outputs.merge_commit_sha }}
+      merged_by: ${{ steps.gate.outputs.merged_by }}
+      gate_error: ${{ steps.gate.outputs.gate_error }}
     runs-on: ubuntu-latest
-    timeout-minutes: 45
+    timeout-minutes: 10
     steps:
       - name: Resolve merged PR and checkbox state
         id: gate
         env:
           GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # SECURITY: keep PR body in env/plain-text handling; avoid directly
+          # inlining github.event.pull_request.body into shell commands.
+          PR_BODY: ${{ github.event.pull_request.body }}
+          MERGE_COMMIT_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+          MERGED_BY: ${{ github.event.pull_request.merged_by.login }}
+          # GitHub team slug authorized to trigger cherry-picks (e.g. "core-eng").
+          # For private/secret teams the GITHUB_TOKEN may need org:read scope;
+          # visible teams work with the default token.
+          ALLOWED_TEAM: "onyx-core-team"
         run: |
-          # For the commit that triggered this workflow (HEAD on main), fetch all
-          # associated PRs and keep only the PR that was actually merged into main
-          # with this exact merge commit SHA.
-          pr_numbers="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_SHA}/pulls" | jq -r --arg sha "${GITHUB_SHA}" '.[] | select(.merged_at != null and .base.ref == "main" and .merge_commit_sha == $sha) | .number')"
-          match_count="$(printf '%s\n' "$pr_numbers" | sed '/^[[:space:]]*$/d' | wc -l | tr -d ' ')"
-          pr_number="$(printf '%s\n' "$pr_numbers" | sed '/^[[:space:]]*$/d' | head -n 1)"
-
-          if [ "${match_count}" -gt 1 ]; then
-            echo "::warning::Multiple merged PRs matched commit ${GITHUB_SHA}. Using PR #${pr_number}."
-          fi
+          echo "pr_number=${PR_NUMBER}" >> "$GITHUB_OUTPUT"
+          echo "merged_by=${MERGED_BY}" >> "$GITHUB_OUTPUT"
 
-          if [ -z "$pr_number" ]; then
-            echo "No merged PR associated with commit ${GITHUB_SHA}; skipping."
+          if ! echo "${PR_BODY}" | grep -qiE "\\[x\\][[:space:]]*(\\[[^]]+\\][[:space:]]*)?Please cherry-pick this PR to the latest release version"; then
             echo "should_cherrypick=false" >> "$GITHUB_OUTPUT"
+            echo "Cherry-pick checkbox not checked for PR #${PR_NUMBER}. Skipping."
             exit 0
           fi
 
-          # Read the PR once so we can gate behavior and infer preferred actor.
-          pr_json="$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${pr_number}")"
-          pr_body="$(printf '%s' "$pr_json" | jq -r '.body // ""')"
-          merged_by="$(printf '%s' "$pr_json" | jq -r '.merged_by.login // ""')"
+          # Keep should_cherrypick output before any possible exit 1 below so
+          # notify-slack can still gate on this output even if this job fails.
+          echo "should_cherrypick=true" >> "$GITHUB_OUTPUT"
+          echo "Cherry-pick checkbox checked for PR #${PR_NUMBER}."
+
+          if [ -z "${MERGE_COMMIT_SHA}" ] || [ "${MERGE_COMMIT_SHA}" = "null" ]; then
+            echo "gate_error=missing-merge-commit-sha" >> "$GITHUB_OUTPUT"
+            echo "::error::PR #${PR_NUMBER} requested cherry-pick, but merge_commit_sha is missing."
+            exit 1
+          fi
 
-          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
-          echo "merged_by=$merged_by" >> "$GITHUB_OUTPUT"
+          echo "merge_commit_sha=${MERGE_COMMIT_SHA}" >> "$GITHUB_OUTPUT"
 
-          if echo "$pr_body" | grep -qiE "\\[x\\][[:space:]]*(\\[[^]]+\\][[:space:]]*)?Please cherry-pick this PR to the latest release version"; then
-            echo "should_cherrypick=true" >> "$GITHUB_OUTPUT"
-            echo "Cherry-pick checkbox checked for PR #${pr_number}."
-            exit 0
+          member_state_file="$(mktemp)"
+          member_err_file="$(mktemp)"
+          if ! gh api "orgs/${GITHUB_REPOSITORY_OWNER}/teams/${ALLOWED_TEAM}/memberships/${MERGED_BY}" --jq '.state' >"${member_state_file}" 2>"${member_err_file}"; then
+            api_err="$(tr '\n' ' ' < "${member_err_file}" | sed 's/[[:space:]]\+/ /g' | cut -c1-300)"
+            echo "gate_error=team-api-error" >> "$GITHUB_OUTPUT"
+            echo "::error::Team membership API call failed for ${MERGED_BY} in ${ALLOWED_TEAM}: ${api_err}"
+            exit 1
           fi
 
-          echo "should_cherrypick=false" >> "$GITHUB_OUTPUT"
-          echo "Cherry-pick checkbox not checked for PR #${pr_number}. Skipping."
+          member_state="$(cat "${member_state_file}")"
+          if [ "${member_state}" != "active" ]; then
+            echo "gate_error=not-team-member" >> "$GITHUB_OUTPUT"
+            echo "::error::${MERGED_BY} is not an active member of team ${ALLOWED_TEAM} (state: ${member_state}). Failing cherry-pick gate."
+            exit 1
+          fi
+
+          exit 0
 
+  cherry-pick-to-latest-release:
+    needs:
+      - resolve-cherry-pick-request
+    if: needs.resolve-cherry-pick-request.outputs.should_cherrypick == 'true' && needs.resolve-cherry-pick-request.result == 'success'
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      cherry_pick_reason: ${{ steps.run_cherry_pick.outputs.reason }}
+      cherry_pick_details: ${{ steps.run_cherry_pick.outputs.details }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
       - name: Checkout repository
-        if: steps.gate.outputs.should_cherrypick == 'true'
+        # SECURITY: keep checkout pinned to trusted base branch; do not switch to PR head refs.
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           fetch-depth: 0
@@ -69,31 +104,37 @@ jobs:
           ref: main
 
       - name: Install the latest version of uv
-        if: steps.gate.outputs.should_cherrypick == 'true'
         uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # ratchet:astral-sh/setup-uv@v7
         with:
           enable-cache: false
           version: "0.9.9"
 
       - name: Configure git identity
-        if: steps.gate.outputs.should_cherrypick == 'true'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
       - name: Create cherry-pick PR to latest release
         id: run_cherry_pick
-        if: steps.gate.outputs.should_cherrypick == 'true'
-        continue-on-error: true
         env:
           GH_TOKEN: ${{ github.token }}
           GITHUB_TOKEN: ${{ github.token }}
-          CHERRY_PICK_ASSIGNEE: ${{ steps.gate.outputs.merged_by }}
+          CHERRY_PICK_ASSIGNEE: ${{ needs.resolve-cherry-pick-request.outputs.merged_by }}
+          MERGE_COMMIT_SHA: ${{ needs.resolve-cherry-pick-request.outputs.merge_commit_sha }}
         run: |
-          set -o pipefail
           output_file="$(mktemp)"
-          uv run --no-sync --with onyx-devtools ods cherry-pick "${GITHUB_SHA}" --yes --no-verify 2>&1 | tee "$output_file"
-          exit_code="${PIPESTATUS[0]}"
+          set +e
+          uv run --no-sync --with onyx-devtools ods cherry-pick "${MERGE_COMMIT_SHA}" --yes --no-verify 2>&1 | tee "$output_file"
+          pipe_statuses=("${PIPESTATUS[@]}")
+          exit_code="${pipe_statuses[0]}"
+          tee_exit="${pipe_statuses[1]:-0}"
+          set -e
+          if [ "${tee_exit}" -ne 0 ]; then
+            echo "status=failure" >> "$GITHUB_OUTPUT"
+            echo "reason=output-capture-failed" >> "$GITHUB_OUTPUT"
+            echo "::error::tee failed to capture cherry-pick output (exit ${tee_exit}); cannot classify result."
+            exit 1
+          fi
 
           if [ "${exit_code}" -eq 0 ]; then
             echo "status=success" >> "$GITHUB_OUTPUT"
@@ -115,7 +156,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Mark workflow as failed if cherry-pick failed
-        if: steps.gate.outputs.should_cherrypick == 'true' && steps.run_cherry_pick.outputs.status == 'failure'
+        if: steps.run_cherry_pick.outputs.status == 'failure'
         env:
           CHERRY_PICK_REASON: ${{ steps.run_cherry_pick.outputs.reason }}
         run: |
@@ -124,8 +165,9 @@ jobs:
 
   notify-slack-on-cherry-pick-failure:
     needs:
+      - resolve-cherry-pick-request
       - cherry-pick-to-latest-release
-    if: always() && needs.cherry-pick-to-latest-release.outputs.should_cherrypick == 'true' && needs.cherry-pick-to-latest-release.result != 'success'
+    if: always() && needs.resolve-cherry-pick-request.outputs.should_cherrypick == 'true' && (needs.resolve-cherry-pick-request.result == 'failure' || needs.cherry-pick-to-latest-release.result == 'failure')
     runs-on: ubuntu-slim
     timeout-minutes: 10
     steps:
@@ -134,22 +176,49 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Fail if Slack webhook secret is missing
+        env:
+          CHERRY_PICK_PRS_WEBHOOK: ${{ secrets.CHERRY_PICK_PRS_WEBHOOK }}
+        run: |
+          if [ -z "${CHERRY_PICK_PRS_WEBHOOK}" ]; then
+            echo "::error::CHERRY_PICK_PRS_WEBHOOK is not configured."
+            exit 1
+          fi
+
       - name: Build cherry-pick failure summary
         id: failure-summary
         env:
-          SOURCE_PR_NUMBER: ${{ needs.cherry-pick-to-latest-release.outputs.pr_number }}
+          SOURCE_PR_NUMBER: ${{ needs.resolve-cherry-pick-request.outputs.pr_number }}
+          MERGE_COMMIT_SHA: ${{ needs.resolve-cherry-pick-request.outputs.merge_commit_sha }}
+          GATE_ERROR: ${{ needs.resolve-cherry-pick-request.outputs.gate_error }}
           CHERRY_PICK_REASON: ${{ needs.cherry-pick-to-latest-release.outputs.cherry_pick_reason }}
           CHERRY_PICK_DETAILS: ${{ needs.cherry-pick-to-latest-release.outputs.cherry_pick_details }}
         run: |
           source_pr_url="https://github.com/${GITHUB_REPOSITORY}/pull/${SOURCE_PR_NUMBER}"
 
           reason_text="cherry-pick command failed"
-          if [ "${CHERRY_PICK_REASON}" = "merge-conflict" ]; then
+          if [ "${GATE_ERROR}" = "missing-merge-commit-sha" ]; then
+            reason_text="requested cherry-pick but merge commit SHA was missing"
+          elif [ "${GATE_ERROR}" = "team-api-error" ]; then
+            reason_text="team membership lookup failed while validating cherry-pick permissions"
+          elif [ "${GATE_ERROR}" = "not-team-member" ]; then
+            reason_text="merger is not an active member of the allowed team"
+          elif [ "${CHERRY_PICK_REASON}" = "output-capture-failed" ]; then
+            reason_text="failed to capture cherry-pick output for classification"
+          elif [ "${CHERRY_PICK_REASON}" = "merge-conflict" ]; then
             reason_text="merge conflict during cherry-pick"
           fi
 
           details_excerpt="$(printf '%s' "${CHERRY_PICK_DETAILS}" | tail -n 8 | tr '\n' ' ' | sed "s/[[:space:]]\\+/ /g" | sed "s/\"/'/g" | cut -c1-350)"
-          failed_jobs="• cherry-pick-to-latest-release\\n• source PR: ${source_pr_url}\\n• reason: ${reason_text}"
+          if [ -n "${GATE_ERROR}" ]; then
+            failed_job_label="resolve-cherry-pick-request"
+          else
+            failed_job_label="cherry-pick-to-latest-release"
+          fi
+          failed_jobs="• ${failed_job_label}\\n• source PR: ${source_pr_url}\\n• reason: ${reason_text}"
+          if [ -n "${MERGE_COMMIT_SHA}" ]; then
+            failed_jobs="${failed_jobs}\\n• merge SHA: ${MERGE_COMMIT_SHA}"
+          fi
           if [ -n "${details_excerpt}" ]; then
             failed_jobs="${failed_jobs}\\n• excerpt: ${details_excerpt}"
           fi
@@ -162,4 +231,4 @@ jobs:
           webhook-url: ${{ secrets.CHERRY_PICK_PRS_WEBHOOK }}
           failed-jobs: ${{ steps.failure-summary.outputs.jobs }}
           title: "🚨 Automated Cherry-Pick Failed"
-          ref-name: ${{ github.ref_name }}
+          ref-name: ${{ github.event.pull_request.base.ref }}

From d17c748f7568c067af36c9129e8fec34a193df0e Mon Sep 17 00:00:00 2001
From: Justin Tahara <105671973+justin-tahara@users.noreply.github.com>
Date: Thu, 12 Mar 2026 17:42:10 -0700
Subject: [PATCH 263/267] chore(greptile): Improving the Custom Context (#9319)

---
 greptile.json | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/greptile.json b/greptile.json
index 7414674129a..2f1f56be126 100644
--- a/greptile.json
+++ b/greptile.json
@@ -52,6 +52,10 @@
         {
           "scope": [],
           "content": "Use explicit type annotations for variables to enhance code clarity, especially when moving type hints around in the code."
+        },
+        {
+          "scope": [],
+          "content": "Use `contributing_guides/best_practices.md` as core review context. Prefer consistency with existing patterns, fix issues in code you touch, avoid tacking new features onto muddy interfaces, fail loudly instead of silently swallowing errors, keep code strictly typed, preserve clear state boundaries, remove duplicate or dead logic, break up overly long functions, avoid hidden import-time side effects, respect module boundaries, and favor correctness-by-construction over relying on callers to use an API correctly."
         }
       ],
       "rules": [
@@ -71,6 +75,14 @@
           "scope": [],
           "rule": "When hardcoding a boolean variable to a constant value, remove the variable entirely and clean up all places where it's used rather than just setting it to a constant."
         },
+        {
+          "scope": [],
+          "rule": "Code changes must consider both multi-tenant and single-tenant deployments. In multi-tenant mode, preserve tenant isolation, ensure tenant context is propagated correctly, and avoid assumptions that only hold for a single shared schema or globally shared state. In single-tenant mode, avoid introducing unnecessary tenant-specific requirements or cloud-only control-plane dependencies."
+        },
+        {
+          "scope": [],
+          "rule": "Code changes must consider both regular Onyx deployments and Onyx lite deployments. Lite deployments disable the vector DB, Redis, model servers, and background workers by default, use PostgreSQL-backed cache/auth/file storage, and rely on the API server to handle background work. Do not assume those services are available unless the code path is explicitly limited to full deployments."
+        },
         {
           "scope": ["backend/**/*.py"],
           "rule": "Never raise HTTPException directly in business code. Use `raise OnyxError(OnyxErrorCode.XXX, \"message\")` from `onyx.error_handling.exceptions`. A global FastAPI exception handler converts OnyxError into structured JSON responses with {\"error_code\": \"...\", \"message\": \"...\"}. Error codes are defined in `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors with dynamic HTTP status codes, use `status_code_override`: `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`."
@@ -86,6 +98,21 @@
           "scope": [],
           "path": "CLAUDE.md",
           "description": "Project instructions and coding standards"
+        },
+        {
+          "scope": [],
+          "path": "backend/alembic/README.md",
+          "description": "Migration guidance, including multi-tenant migration behavior"
+        },
+        {
+          "scope": [],
+          "path": "deployment/helm/charts/onyx/values-lite.yaml",
+          "description": "Lite deployment Helm values and service assumptions"
+        },
+        {
+          "scope": [],
+          "path": "deployment/docker_compose/docker-compose.onyx-lite.yml",
+          "description": "Lite deployment Docker Compose overlay and disabled service behavior"
         }
       ]
     }

From ab9e3e53382ade4e979ea53b68f87b3564f9acc9 Mon Sep 17 00:00:00 2001
From: roshan <38771624+rohoswagger@users.noreply.github.com>
Date: Thu, 12 Mar 2026 19:34:06 -0700
Subject: [PATCH 264/267] fix(craft): stop proxied webapp asset and HMR reload
 leaks (#9255)

Co-authored-by: Wenxi <wenxi@onyx.app>
---
 backend/onyx/server/features/build/api/api.py |  90 +++++-
 .../build/api/templates/webapp_hmr_fixer.js   | 135 +++++++++
 .../unit/build/test_rewrite_asset_paths.py    | 256 ++++++++++++++++++
 3 files changed, 472 insertions(+), 9 deletions(-)
 create mode 100644 backend/onyx/server/features/build/api/templates/webapp_hmr_fixer.js
 create mode 100644 backend/tests/unit/build/test_rewrite_asset_paths.py

diff --git a/backend/onyx/server/features/build/api/api.py b/backend/onyx/server/features/build/api/api.py
index ad8b8cec919..038a4b82252 100644
--- a/backend/onyx/server/features/build/api/api.py
+++ b/backend/onyx/server/features/build/api/api.py
@@ -1,3 +1,4 @@
+import re
 from collections.abc import Iterator
 from pathlib import Path
 from uuid import UUID
@@ -40,6 +41,9 @@
 
 logger = setup_logger()
 
+_TEMPLATES_DIR = Path(__file__).parent / "templates"
+_WEBAPP_HMR_FIXER_TEMPLATE = (_TEMPLATES_DIR / "webapp_hmr_fixer.js").read_text()
+
 
 def require_onyx_craft_enabled(user: User = Depends(current_user)) -> User:
     """
@@ -239,18 +243,62 @@ def _stream_response(response: httpx.Response) -> Iterator[bytes]:
         yield chunk
 
 
+def _inject_hmr_fixer(content: bytes, session_id: str) -> bytes:
+    """Inject a script that stubs root-scoped Next HMR websocket connections."""
+    base = f"/api/build/sessions/{session_id}/webapp"
+    script = f"<script>{_WEBAPP_HMR_FIXER_TEMPLATE.replace('__WEBAPP_BASE__', base)}</script>"
+    text = content.decode("utf-8")
+    text = re.sub(
+        r"(<head\b[^>]*>)",
+        lambda m: m.group(0) + script,
+        text,
+        count=1,
+        flags=re.IGNORECASE,
+    )
+    return text.encode("utf-8")
+
+
 def _rewrite_asset_paths(content: bytes, session_id: str) -> bytes:
     """Rewrite Next.js asset paths to go through the proxy."""
-    import re
-
-    # Base path includes session_id for routing
     webapp_base_path = f"/api/build/sessions/{session_id}/webapp"
+    escaped_webapp_base_path = webapp_base_path.replace("/", r"\/")
+    hmr_paths = ("/_next/webpack-hmr", "/_next/hmr")
 
     text = content.decode("utf-8")
-    # Rewrite /_next/ paths to go through our proxy
-    text = text.replace("/_next/", f"{webapp_base_path}/_next/")
-    # Rewrite JSON data file fetch paths (e.g., /data.json, /data/tickets.json)
-    # Matches paths like "/filename.json" or "/path/to/file.json"
+    # Anchor on delimiter so already-prefixed URLs (from assetPrefix) aren't double-rewritten.
+    for delim in ('"', "'", "("):
+        text = text.replace(f"{delim}/_next/", f"{delim}{webapp_base_path}/_next/")
+        text = re.sub(
+            rf"{re.escape(delim)}https?://[^/\"')]+/_next/",
+            f"{delim}{webapp_base_path}/_next/",
+            text,
+        )
+        text = re.sub(
+            rf"{re.escape(delim)}wss?://[^/\"')]+/_next/",
+            f"{delim}{webapp_base_path}/_next/",
+            text,
+        )
+    text = text.replace(r"\/_next\/", rf"{escaped_webapp_base_path}\/_next\/")
+    text = re.sub(
+        r"https?:\\\/\\\/[^\"']+?\\\/_next\\\/",
+        rf"{escaped_webapp_base_path}\/_next\/",
+        text,
+    )
+    text = re.sub(
+        r"wss?:\\\/\\\/[^\"']+?\\\/_next\\\/",
+        rf"{escaped_webapp_base_path}\/_next\/",
+        text,
+    )
+    for hmr_path in hmr_paths:
+        escaped_hmr_path = hmr_path.replace("/", r"\/")
+        text = text.replace(
+            f"{webapp_base_path}{hmr_path}",
+            hmr_path,
+        )
+        text = text.replace(
+            f"{escaped_webapp_base_path}{escaped_hmr_path}",
+            escaped_hmr_path,
+        )
     text = re.sub(
         r'"(/(?:[a-zA-Z0-9_-]+/)*[a-zA-Z0-9_-]+\.json)"',
         f'"{webapp_base_path}\\1"',
@@ -261,11 +309,29 @@ def _rewrite_asset_paths(content: bytes, session_id: str) -> bytes:
         f"'{webapp_base_path}\\1'",
         text,
     )
-    # Rewrite favicon
     text = text.replace('"/favicon.ico', f'"{webapp_base_path}/favicon.ico')
     return text.encode("utf-8")
 
 
+def _rewrite_proxy_response_headers(
+    headers: dict[str, str], session_id: str
+) -> dict[str, str]:
+    """Rewrite response headers that can leak root-scoped asset URLs."""
+    link = headers.get("link")
+    if link:
+        webapp_base_path = f"/api/build/sessions/{session_id}/webapp"
+        rewritten_link = re.sub(
+            r"<https?://[^>]+/_next/",
+            f"<{webapp_base_path}/_next/",
+            link,
+        )
+        rewritten_link = rewritten_link.replace(
+            "</_next/", f"<{webapp_base_path}/_next/"
+        )
+        headers["link"] = rewritten_link
+    return headers
+
+
 # Content types that may contain asset path references that need rewriting
 REWRITABLE_CONTENT_TYPES = {
     "text/html",
@@ -342,12 +408,17 @@ def _proxy_request(
                 for key, value in response.headers.items()
                 if key.lower() not in EXCLUDED_HEADERS
             }
+            response_headers = _rewrite_proxy_response_headers(
+                response_headers, str(session_id)
+            )
 
             content_type = response.headers.get("content-type", "")
 
             # For HTML/CSS/JS responses, rewrite asset paths
             if any(ct in content_type for ct in REWRITABLE_CONTENT_TYPES):
                 content = _rewrite_asset_paths(response.content, str(session_id))
+                if "text/html" in content_type:
+                    content = _inject_hmr_fixer(content, str(session_id))
                 return Response(
                     content=content,
                     status_code=response.status_code,
@@ -391,7 +462,7 @@ def _check_webapp_access(
     return session
 
 
-_OFFLINE_HTML_PATH = Path(__file__).parent / "templates" / "webapp_offline.html"
+_OFFLINE_HTML_PATH = _TEMPLATES_DIR / "webapp_offline.html"
 
 
 def _offline_html_response() -> Response:
@@ -399,6 +470,7 @@ def _offline_html_response() -> Response:
 
     Design mirrors the default Craft web template (outputs/web/app/page.tsx):
     terminal window aesthetic with Minecraft-themed typing animation.
+
     """
     html = _OFFLINE_HTML_PATH.read_text()
     return Response(content=html, status_code=503, media_type="text/html")
diff --git a/backend/onyx/server/features/build/api/templates/webapp_hmr_fixer.js b/backend/onyx/server/features/build/api/templates/webapp_hmr_fixer.js
new file mode 100644
index 00000000000..a45f67aedbc
--- /dev/null
+++ b/backend/onyx/server/features/build/api/templates/webapp_hmr_fixer.js
@@ -0,0 +1,135 @@
+(function () {
+  var WEBAPP_BASE = "__WEBAPP_BASE__";
+  var PROXIED_NEXT_PREFIX = WEBAPP_BASE + "/_next/";
+  var PROXIED_HMR_PREFIX = WEBAPP_BASE + "/_next/webpack-hmr";
+  var PROXIED_ALT_HMR_PREFIX = WEBAPP_BASE + "/_next/hmr";
+
+  function isHmrWebSocketUrl(url) {
+    if (!url) return false;
+    try {
+      var parsedUrl = new URL(String(url), window.location.href);
+      return (
+        parsedUrl.pathname.indexOf("/_next/webpack-hmr") === 0 ||
+        parsedUrl.pathname.indexOf("/_next/hmr") === 0 ||
+        parsedUrl.pathname.indexOf(PROXIED_HMR_PREFIX) === 0 ||
+        parsedUrl.pathname.indexOf(PROXIED_ALT_HMR_PREFIX) === 0
+      );
+    } catch (e) {}
+    if (typeof url === "string") {
+      return (
+        url.indexOf("/_next/webpack-hmr") === 0 ||
+        url.indexOf("/_next/hmr") === 0 ||
+        url.indexOf(PROXIED_HMR_PREFIX) === 0 ||
+        url.indexOf(PROXIED_ALT_HMR_PREFIX) === 0
+      );
+    }
+    return false;
+  }
+
+  function rewriteNextAssetUrl(url) {
+    if (!url) return url;
+    try {
+      var parsedUrl = new URL(String(url), window.location.href);
+      if (parsedUrl.pathname.indexOf(PROXIED_NEXT_PREFIX) === 0) {
+        return parsedUrl.pathname + parsedUrl.search + parsedUrl.hash;
+      }
+      if (parsedUrl.pathname.indexOf("/_next/") === 0) {
+        return (
+          WEBAPP_BASE + parsedUrl.pathname + parsedUrl.search + parsedUrl.hash
+        );
+      }
+    } catch (e) {}
+    if (typeof url === "string") {
+      if (url.indexOf(PROXIED_NEXT_PREFIX) === 0) {
+        return url;
+      }
+      if (url.indexOf("/_next/") === 0) {
+        return WEBAPP_BASE + url;
+      }
+    }
+    return url;
+  }
+
+  function createEvent(eventType) {
+    return typeof Event === "function"
+      ? new Event(eventType)
+      : { type: eventType };
+  }
+
+  function MockHmrWebSocket(url) {
+    this.url = String(url);
+    this.readyState = 1;
+    this.bufferedAmount = 0;
+    this.extensions = "";
+    this.protocol = "";
+    this.binaryType = "blob";
+    this.onopen = null;
+    this.onmessage = null;
+    this.onerror = null;
+    this.onclose = null;
+    this._l = {};
+    var socket = this;
+    setTimeout(function () {
+      socket._d("open", createEvent("open"));
+    }, 0);
+  }
+
+  MockHmrWebSocket.CONNECTING = 0;
+  MockHmrWebSocket.OPEN = 1;
+  MockHmrWebSocket.CLOSING = 2;
+  MockHmrWebSocket.CLOSED = 3;
+
+  MockHmrWebSocket.prototype.addEventListener = function (eventType, callback) {
+    (this._l[eventType] || (this._l[eventType] = [])).push(callback);
+  };
+
+  MockHmrWebSocket.prototype.removeEventListener = function (
+    eventType,
+    callback,
+  ) {
+    var listeners = this._l[eventType] || [];
+    this._l[eventType] = listeners.filter(function (listener) {
+      return listener !== callback;
+    });
+  };
+
+  MockHmrWebSocket.prototype._d = function (eventType, eventValue) {
+    var listeners = this._l[eventType] || [];
+    for (var i = 0; i < listeners.length; i++) {
+      listeners[i].call(this, eventValue);
+    }
+    var handler = this["on" + eventType];
+    if (typeof handler === "function") {
+      handler.call(this, eventValue);
+    }
+  };
+
+  MockHmrWebSocket.prototype.send = function () {};
+
+  MockHmrWebSocket.prototype.close = function (code, reason) {
+    if (this.readyState >= 2) return;
+    this.readyState = 3;
+    var closeEvent = createEvent("close");
+    closeEvent.code = code === undefined ? 1000 : code;
+    closeEvent.reason = reason || "";
+    closeEvent.wasClean = true;
+    this._d("close", closeEvent);
+  };
+
+  if (window.WebSocket) {
+    var OriginalWebSocket = window.WebSocket;
+    window.WebSocket = function (url, protocols) {
+      if (isHmrWebSocketUrl(url)) {
+        return new MockHmrWebSocket(rewriteNextAssetUrl(url));
+      }
+      return protocols === undefined
+        ? new OriginalWebSocket(url)
+        : new OriginalWebSocket(url, protocols);
+    };
+    window.WebSocket.prototype = OriginalWebSocket.prototype;
+    Object.setPrototypeOf(window.WebSocket, OriginalWebSocket);
+    ["CONNECTING", "OPEN", "CLOSING", "CLOSED"].forEach(function (stateKey) {
+      window.WebSocket[stateKey] = OriginalWebSocket[stateKey];
+    });
+  }
+})();
diff --git a/backend/tests/unit/build/test_rewrite_asset_paths.py b/backend/tests/unit/build/test_rewrite_asset_paths.py
new file mode 100644
index 00000000000..7eb7eb3ce49
--- /dev/null
+++ b/backend/tests/unit/build/test_rewrite_asset_paths.py
@@ -0,0 +1,256 @@
+"""Unit tests for webapp proxy path rewriting/injection."""
+
+from types import SimpleNamespace
+from typing import cast
+from typing import Literal
+from uuid import UUID
+
+import httpx
+import pytest
+from fastapi import Request
+from sqlalchemy.orm import Session
+
+from onyx.server.features.build.api import api
+from onyx.server.features.build.api.api import _inject_hmr_fixer
+from onyx.server.features.build.api.api import _rewrite_asset_paths
+from onyx.server.features.build.api.api import _rewrite_proxy_response_headers
+
+SESSION_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+BASE = f"/api/build/sessions/{SESSION_ID}/webapp"
+
+
+def rewrite(html: str) -> str:
+    return _rewrite_asset_paths(html.encode(), SESSION_ID).decode()
+
+
+def inject(html: str) -> str:
+    return _inject_hmr_fixer(html.encode(), SESSION_ID).decode()
+
+
+class TestNextjsPathRewriting:
+    def test_rewrites_bare_next_script_src(self) -> None:
+        html = '<script src="/_next/static/chunks/main.js">'
+        result = rewrite(html)
+        assert f'src="{BASE}/_next/static/chunks/main.js"' in result
+        assert '"/_next/' not in result
+
+    def test_rewrites_bare_next_in_single_quotes(self) -> None:
+        html = "<link href='/_next/static/css/app.css'>"
+        result = rewrite(html)
+        assert f"'{BASE}/_next/static/css/app.css'" in result
+
+    def test_rewrites_bare_next_in_url_parens(self) -> None:
+        html = "background: url(/_next/static/media/font.woff2)"
+        result = rewrite(html)
+        assert f"url({BASE}/_next/static/media/font.woff2)" in result
+
+    def test_no_double_prefix_when_already_proxied(self) -> None:
+        """assetPrefix makes Next.js emit already-prefixed URLs — must not double-rewrite."""
+        already_prefixed = f'<script src="{BASE}/_next/static/chunks/main.js">'
+        result = rewrite(already_prefixed)
+        # Should be unchanged
+        assert result == already_prefixed
+        # Specifically, no double path
+        assert f"{BASE}/{BASE}" not in result
+
+    def test_rewrites_favicon(self) -> None:
+        html = '<link rel="icon" href="/favicon.ico">'
+        result = rewrite(html)
+        assert f'"{BASE}/favicon.ico"' in result
+
+    def test_rewrites_json_data_path_double_quoted(self) -> None:
+        html = 'fetch("/data/tickets.json")'
+        result = rewrite(html)
+        assert f'"{BASE}/data/tickets.json"' in result
+
+    def test_rewrites_json_data_path_single_quoted(self) -> None:
+        html = "fetch('/data/items.json')"
+        result = rewrite(html)
+        assert f"'{BASE}/data/items.json'" in result
+
+    def test_rewrites_escaped_next_font_path_in_json_script(self) -> None:
+        """Next dev can embed font asset paths in JSON-escaped script payloads."""
+        html = r'{"src":"\/_next\/static\/media\/font.woff2"}'
+        result = rewrite(html)
+        assert (
+            r'{"src":"\/api\/build\/sessions\/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\/webapp\/_next\/static\/media\/font.woff2"}'
+            in result
+        )
+
+    def test_rewrites_escaped_next_font_path_in_style_payload(self) -> None:
+        """Keep dynamically generated next/font URLs inside the session proxy."""
+        html = r'{"css":"@font-face{src:url(\"\/_next\/static\/media\/font.woff2\")"}'
+        result = rewrite(html)
+        assert (
+            r"\/api\/build\/sessions\/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\/webapp\/_next\/static\/media\/font.woff2"
+            in result
+        )
+
+    def test_rewrites_absolute_next_font_url(self) -> None:
+        html = (
+            '<link rel="preload" as="font" '
+            'href="https://craft-dev.onyx.app/_next/static/media/font.woff2">'
+        )
+        result = rewrite(html)
+        assert f'"{BASE}/_next/static/media/font.woff2"' in result
+
+    def test_rewrites_root_hmr_path(self) -> None:
+        html = 'new WebSocket("wss://craft-dev.onyx.app/_next/webpack-hmr?id=abc")'
+        result = rewrite(html)
+        assert '"wss://craft-dev.onyx.app/_next/webpack-hmr?id=abc"' not in result
+        assert '"/_next/webpack-hmr?id=abc"' in result
+
+    def test_rewrites_escaped_absolute_next_font_url(self) -> None:
+        html = (
+            r'{"href":"https:\/\/craft-dev.onyx.app\/_next\/static\/media\/font.woff2"}'
+        )
+        result = rewrite(html)
+        assert (
+            r'{"href":"\/api\/build\/sessions\/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\/webapp\/_next\/static\/media\/font.woff2"}'
+            in result
+        )
+
+
+class TestRuntimeFixerInjection:
+    def test_injects_websocket_rewrite_shim(self) -> None:
+        html = "<html><head></head><body></body></html>"
+        result = inject(html)
+        assert "window.WebSocket = function (url, protocols)" in result
+        assert f'var WEBAPP_BASE = "{BASE}"' in result
+
+    def test_injects_hmr_websocket_stub(self) -> None:
+        html = "<html><head></head><body></body></html>"
+        result = inject(html)
+        assert "function MockHmrWebSocket(url)" in result
+        assert "return new MockHmrWebSocket(rewriteNextAssetUrl(url));" in result
+
+    def test_injects_before_head_contents(self) -> None:
+        html = "<html><head><title>x</title></head><body></body></html>"
+        result = inject(html)
+        assert result.index(
+            "window.WebSocket = function (url, protocols)"
+        ) < result.index("<title>x</title>")
+
+    def test_rewritten_hmr_url_still_matches_shim_intercept_logic(self) -> None:
+        html = (
+            "<html><head></head><body>"
+            'new WebSocket("wss://craft-dev.onyx.app/_next/webpack-hmr?id=abc")'
+            "</body></html>"
+        )
+
+        rewritten = rewrite(html)
+        assert '"wss://craft-dev.onyx.app/_next/webpack-hmr?id=abc"' not in rewritten
+        assert 'new WebSocket("/_next/webpack-hmr?id=abc")' in rewritten
+
+        injected = inject(rewritten)
+
+        assert 'new WebSocket("/_next/webpack-hmr?id=abc")' in injected
+        assert 'parsedUrl.pathname.indexOf("/_next/webpack-hmr") === 0' in injected
+
+
+class TestProxyHeaderRewriting:
+    def test_rewrites_link_header_font_preload_paths(self) -> None:
+        headers = {
+            "link": (
+                '</_next/static/media/font.woff2>; rel=preload; as="font"; crossorigin, '
+                '</_next/static/media/font2.woff2>; rel=preload; as="font"; crossorigin'
+            )
+        }
+
+        result = _rewrite_proxy_response_headers(headers, SESSION_ID)
+
+        assert f"<{BASE}/_next/static/media/font.woff2>" in result["link"]
+
+
+class TestProxyRequestWiring:
+    def test_proxy_request_rewrites_link_header_on_html_response(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        html = b"<html><head></head><body>ok</body></html>"
+        upstream = httpx.Response(
+            200,
+            headers={
+                "content-type": "text/html; charset=utf-8",
+                "link": '</_next/static/media/font.woff2>; rel=preload; as="font"',
+            },
+            content=html,
+        )
+
+        monkeypatch.setattr(api, "_get_sandbox_url", lambda *_args: "http://sandbox")
+
+        class FakeClient:
+            def __init__(self, *_args: object, **_kwargs: object) -> None:
+                pass
+
+            def __enter__(self) -> "FakeClient":
+                return self
+
+            def __exit__(self, *_args: object) -> Literal[False]:
+                return False
+
+            def get(self, _url: str, headers: dict[str, str]) -> httpx.Response:
+                assert "host" not in {key.lower() for key in headers}
+                return upstream
+
+        monkeypatch.setattr(api.httpx, "Client", FakeClient)
+
+        request = cast(Request, SimpleNamespace(headers={}, query_params=""))
+
+        response = api._proxy_request(
+            "", request, UUID(SESSION_ID), cast(Session, SimpleNamespace())
+        )
+
+        assert response.headers["link"] == (
+            f'<{BASE}/_next/static/media/font.woff2>; rel=preload; as="font"'
+        )
+
+    def test_proxy_request_injects_hmr_fixer_for_html_response(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        upstream = httpx.Response(
+            200,
+            headers={"content-type": "text/html; charset=utf-8"},
+            content=b"<html><head><title>x</title></head><body></body></html>",
+        )
+
+        monkeypatch.setattr(api, "_get_sandbox_url", lambda *_args: "http://sandbox")
+
+        class FakeClient:
+            def __init__(self, *_args: object, **_kwargs: object) -> None:
+                pass
+
+            def __enter__(self) -> "FakeClient":
+                return self
+
+            def __exit__(self, *_args: object) -> Literal[False]:
+                return False
+
+            def get(self, _url: str, headers: dict[str, str]) -> httpx.Response:
+                assert "host" not in {key.lower() for key in headers}
+                return upstream
+
+        monkeypatch.setattr(api.httpx, "Client", FakeClient)
+
+        request = cast(Request, SimpleNamespace(headers={}, query_params=""))
+
+        response = api._proxy_request(
+            "", request, UUID(SESSION_ID), cast(Session, SimpleNamespace())
+        )
+        body = cast(bytes, response.body).decode("utf-8")
+
+        assert "window.WebSocket = function (url, protocols)" in body
+        assert body.index("window.WebSocket = function (url, protocols)") < body.index(
+            "<title>x</title>"
+        )
+
+    def test_rewrites_absolute_link_header_font_preload_paths(self) -> None:
+        headers = {
+            "link": (
+                "<https://craft-dev.onyx.app/_next/static/media/font.woff2>; "
+                'rel=preload; as="font"; crossorigin'
+            )
+        }
+
+        result = _rewrite_proxy_response_headers(headers, SESSION_ID)
+
+        assert f"<{BASE}/_next/static/media/font.woff2>" in result["link"]

From aec0c28c5991e13b728c736e50c0b9d609beb654 Mon Sep 17 00:00:00 2001
From: Evan Lohn <evan@danswer.ai>
Date: Thu, 12 Mar 2026 20:57:57 -0700
Subject: [PATCH 265/267] fix: skip classic site pages (#9318)

---
 .../onyx/connectors/sharepoint/connector.py   |  12 +-
 .../sharepoint/test_fetch_site_pages.py       | 179 ++++++++++++++++++
 2 files changed, 189 insertions(+), 2 deletions(-)
 create mode 100644 backend/tests/unit/onyx/connectors/sharepoint/test_fetch_site_pages.py

diff --git a/backend/onyx/connectors/sharepoint/connector.py b/backend/onyx/connectors/sharepoint/connector.py
index 51c0c14f6bc..6088f3cf6f9 100644
--- a/backend/onyx/connectors/sharepoint/connector.py
+++ b/backend/onyx/connectors/sharepoint/connector.py
@@ -33,6 +33,7 @@
 from office365.sharepoint.client_context import ClientContext  # type: ignore[import-untyped]
 from pydantic import BaseModel
 from pydantic import Field
+from requests.exceptions import HTTPError
 
 from onyx.configs.app_configs import INDEX_BATCH_SIZE
 from onyx.configs.app_configs import REQUEST_TIMEOUT_SECONDS
@@ -277,7 +278,7 @@ def _log_and_raise_for_status(response: requests.Response) -> None:
     try:
         response.raise_for_status()
     except Exception:
-        logger.error(f"Graph API request failed: {response.text}")
+        logger.error(f"HTTP request failed: {response.text}")
         raise
 
 
@@ -1258,7 +1259,14 @@ def _fetch_site_pages(
         total_yielded = 0
 
         while page_url:
-            data = self._graph_api_get_json(page_url, params)
+            try:
+                data = self._graph_api_get_json(page_url, params)
+            except HTTPError as e:
+                if e.response.status_code == 404:
+                    logger.warning(f"Site page not found: {page_url}")
+                    break
+                raise
+
             params = None  # nextLink already embeds query params
 
             for page in data.get("value", []):
diff --git a/backend/tests/unit/onyx/connectors/sharepoint/test_fetch_site_pages.py b/backend/tests/unit/onyx/connectors/sharepoint/test_fetch_site_pages.py
new file mode 100644
index 00000000000..4c95a5daf7e
--- /dev/null
+++ b/backend/tests/unit/onyx/connectors/sharepoint/test_fetch_site_pages.py
@@ -0,0 +1,179 @@
+"""Unit tests for SharepointConnector._fetch_site_pages 404 handling.
+
+The Graph Pages API returns 404 for classic sites or sites without
+modern pages enabled.  _fetch_site_pages should gracefully skip these
+rather than crashing the entire indexing run.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from requests import Response
+from requests.exceptions import HTTPError
+
+from onyx.connectors.sharepoint.connector import SharepointConnector
+from onyx.connectors.sharepoint.connector import SiteDescriptor
+
+SITE_URL = "https://tenant.sharepoint.com/sites/ClassicSite"
+FAKE_SITE_ID = "tenant.sharepoint.com,abc123,def456"
+
+
+def _site_descriptor() -> SiteDescriptor:
+    return SiteDescriptor(url=SITE_URL, drive_name=None, folder_path=None)
+
+
+def _make_http_error(status_code: int) -> HTTPError:
+    response = Response()
+    response.status_code = status_code
+    response._content = b'{"error":{"code":"itemNotFound","message":"Item not found"}}'
+    return HTTPError(response=response)
+
+
+def _setup_connector(
+    monkeypatch: pytest.MonkeyPatch,  # noqa: ARG001
+) -> SharepointConnector:
+    """Create a connector with the graph client and site resolution mocked."""
+    connector = SharepointConnector(sites=[SITE_URL])
+    connector.graph_api_base = "https://graph.microsoft.com/v1.0"
+
+    mock_sites = type(
+        "FakeSites",
+        (),
+        {
+            "get_by_url": staticmethod(
+                lambda url: type(  # noqa: ARG005
+                    "Q",
+                    (),
+                    {
+                        "execute_query": lambda self: None,  # noqa: ARG005
+                        "id": FAKE_SITE_ID,
+                    },
+                )()
+            ),
+        },
+    )()
+    connector._graph_client = type("FakeGraphClient", (), {"sites": mock_sites})()
+
+    return connector
+
+
+def _patch_graph_api_get_json(
+    monkeypatch: pytest.MonkeyPatch,
+    fake_fn: Any,
+) -> None:
+    monkeypatch.setattr(SharepointConnector, "_graph_api_get_json", fake_fn)
+
+
+class TestFetchSitePages404:
+    def test_404_yields_no_pages(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A 404 from the Pages API should result in zero yielded pages."""
+        connector = _setup_connector(monkeypatch)
+
+        def fake_get_json(
+            self: SharepointConnector,  # noqa: ARG001
+            url: str,  # noqa: ARG001
+            params: dict[str, str] | None = None,  # noqa: ARG001
+        ) -> dict[str, Any]:
+            raise _make_http_error(404)
+
+        _patch_graph_api_get_json(monkeypatch, fake_get_json)
+
+        pages = list(connector._fetch_site_pages(_site_descriptor()))
+        assert pages == []
+
+    def test_404_does_not_raise(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A 404 must not propagate as an exception."""
+        connector = _setup_connector(monkeypatch)
+
+        def fake_get_json(
+            self: SharepointConnector,  # noqa: ARG001
+            url: str,  # noqa: ARG001
+            params: dict[str, str] | None = None,  # noqa: ARG001
+        ) -> dict[str, Any]:
+            raise _make_http_error(404)
+
+        _patch_graph_api_get_json(monkeypatch, fake_get_json)
+
+        for _ in connector._fetch_site_pages(_site_descriptor()):
+            pass
+
+    def test_non_404_http_error_still_raises(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Non-404 HTTP errors (e.g. 403) must still propagate."""
+        connector = _setup_connector(monkeypatch)
+
+        def fake_get_json(
+            self: SharepointConnector,  # noqa: ARG001
+            url: str,  # noqa: ARG001
+            params: dict[str, str] | None = None,  # noqa: ARG001
+        ) -> dict[str, Any]:
+            raise _make_http_error(403)
+
+        _patch_graph_api_get_json(monkeypatch, fake_get_json)
+
+        with pytest.raises(HTTPError):
+            list(connector._fetch_site_pages(_site_descriptor()))
+
+    def test_successful_fetch_yields_pages(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """When the API succeeds, pages should be yielded normally."""
+        connector = _setup_connector(monkeypatch)
+
+        fake_page = {
+            "id": "page-1",
+            "title": "Hello World",
+            "webUrl": f"{SITE_URL}/SitePages/Hello.aspx",
+            "lastModifiedDateTime": "2025-06-01T00:00:00Z",
+        }
+
+        def fake_get_json(
+            self: SharepointConnector,  # noqa: ARG001
+            url: str,  # noqa: ARG001
+            params: dict[str, str] | None = None,  # noqa: ARG001
+        ) -> dict[str, Any]:
+            return {"value": [fake_page]}
+
+        _patch_graph_api_get_json(monkeypatch, fake_get_json)
+
+        pages = list(connector._fetch_site_pages(_site_descriptor()))
+        assert len(pages) == 1
+        assert pages[0]["id"] == "page-1"
+
+    def test_404_on_second_page_stops_pagination(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """If the first API page succeeds but a nextLink returns 404,
+        already-yielded pages are kept and iteration stops cleanly."""
+        connector = _setup_connector(monkeypatch)
+
+        call_count = 0
+        first_page = {
+            "id": "page-1",
+            "title": "First",
+            "webUrl": f"{SITE_URL}/SitePages/First.aspx",
+            "lastModifiedDateTime": "2025-06-01T00:00:00Z",
+        }
+
+        def fake_get_json(
+            self: SharepointConnector,  # noqa: ARG001
+            url: str,  # noqa: ARG001
+            params: dict[str, str] | None = None,  # noqa: ARG001
+        ) -> dict[str, Any]:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return {
+                    "value": [first_page],
+                    "@odata.nextLink": "https://graph.microsoft.com/next",
+                }
+            raise _make_http_error(404)
+
+        _patch_graph_api_get_json(monkeypatch, fake_get_json)
+
+        pages = list(connector._fetch_site_pages(_site_descriptor()))
+        assert len(pages) == 1
+        assert pages[0]["id"] == "page-1"

From be61c54d455673f6160d889fadd9df7eb1cb3426 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Thu, 12 Mar 2026 21:00:36 -0700
Subject: [PATCH 266/267] feat(admin): add edit group membership modal - 8/9
 (#9185)

---
 .../opal/src/components/tag/components.tsx    |  14 +-
 web/lib/opal/src/components/tag/styles.css    |   6 +
 web/lib/opal/src/icons/filter-plus.tsx        |  21 ++
 web/lib/opal/src/icons/index.ts               |   1 +
 web/src/layouts/input-layouts.tsx             |   3 +-
 web/src/lib/types.ts                          |   2 +-
 .../refresh-components/table/DataTable.tsx    |  21 +-
 web/src/refresh-components/table/Footer.tsx   |  17 +-
 .../refresh-components/table/TableCell.tsx    |   4 +-
 web/src/refresh-components/table/types.ts     |   2 +
 .../admin/UsersPage/EditGroupsModal.tsx       | 332 ++++++++++++++++++
 .../admin/UsersPage/GroupsCell.tsx            | 212 +++++++++++
 .../admin/UsersPage/UserFilters.tsx           | 122 ++++---
 .../admin/UsersPage/UserRowActions.tsx        | 204 ++++++++---
 .../admin/UsersPage/UsersSummary.tsx          |  23 +-
 .../admin/UsersPage/UsersTable.tsx            |  54 ++-
 web/src/refresh-pages/admin/UsersPage/svc.ts  |  57 +++
 17 files changed, 935 insertions(+), 160 deletions(-)
 create mode 100644 web/lib/opal/src/icons/filter-plus.tsx
 create mode 100644 web/src/refresh-pages/admin/UsersPage/EditGroupsModal.tsx
 create mode 100644 web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx

diff --git a/web/lib/opal/src/components/tag/components.tsx b/web/lib/opal/src/components/tag/components.tsx
index 34637514be3..5b6b02ab2f5 100644
--- a/web/lib/opal/src/components/tag/components.tsx
+++ b/web/lib/opal/src/components/tag/components.tsx
@@ -9,6 +9,8 @@ import { cn } from "@opal/utils";
 
 type TagColor = "green" | "purple" | "blue" | "gray" | "amber";
 
+type TagSize = "sm" | "md";
+
 interface TagProps {
   /** Optional icon component. */
   icon?: IconFunctionComponent;
@@ -18,6 +20,9 @@ interface TagProps {
 
   /** Color variant. Default: `"gray"`. */
   color?: TagColor;
+
+  /** Size variant. Default: `"sm"`. */
+  size?: TagSize;
 }
 
 // ---------------------------------------------------------------------------
@@ -36,11 +41,11 @@ const COLOR_CONFIG: Record<TagColor, { bg: string; text: string }> = {
 // Tag
 // ---------------------------------------------------------------------------
 
-function Tag({ icon: Icon, title, color = "gray" }: TagProps) {
+function Tag({ icon: Icon, title, color = "gray", size = "sm" }: TagProps) {
   const config = COLOR_CONFIG[color];
 
   return (
-    <div className={cn("opal-auxiliary-tag", config.bg)}>
+    <div className={cn("opal-auxiliary-tag", config.bg)} data-size={size}>
       {Icon && (
         <div className="opal-auxiliary-tag-icon-container">
           <Icon className={cn("opal-auxiliary-tag-icon", config.text)} />
@@ -48,7 +53,8 @@ function Tag({ icon: Icon, title, color = "gray" }: TagProps) {
       )}
       <span
         className={cn(
-          "opal-auxiliary-tag-title px-[2px] font-figure-small-value",
+          "opal-auxiliary-tag-title px-[2px]",
+          size === "md" ? "font-secondary-body" : "font-figure-small-value",
           config.text
         )}
       >
@@ -58,4 +64,4 @@ function Tag({ icon: Icon, title, color = "gray" }: TagProps) {
   );
 }
 
-export { Tag, type TagProps, type TagColor };
+export { Tag, type TagProps, type TagColor, type TagSize };
diff --git a/web/lib/opal/src/components/tag/styles.css b/web/lib/opal/src/components/tag/styles.css
index ae49131696f..592675af6df 100644
--- a/web/lib/opal/src/components/tag/styles.css
+++ b/web/lib/opal/src/components/tag/styles.css
@@ -13,6 +13,12 @@
   gap: 0;
 }
 
+.opal-auxiliary-tag[data-size="md"] {
+  height: 1.375rem;
+  padding: 0 0.375rem;
+  border-radius: 0.375rem;
+}
+
 .opal-auxiliary-tag-icon-container {
   display: flex;
   align-items: center;
diff --git a/web/lib/opal/src/icons/filter-plus.tsx b/web/lib/opal/src/icons/filter-plus.tsx
new file mode 100644
index 00000000000..48181775f2d
--- /dev/null
+++ b/web/lib/opal/src/icons/filter-plus.tsx
@@ -0,0 +1,21 @@
+import type { IconProps } from "@opal/types";
+
+const SvgFilterPlus = ({ size, ...props }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    {...props}
+  >
+    <path
+      d="M9.5 12.5L6.83334 11.1667V7.80667L1.5 1.5H14.8333L12.1667 4.65333M12.1667 7V9.5M12.1667 9.5V12M12.1667 9.5H9.66667M12.1667 9.5H14.6667"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+export default SvgFilterPlus;
diff --git a/web/lib/opal/src/icons/index.ts b/web/lib/opal/src/icons/index.ts
index 5edc2c14068..a8678bf395b 100644
--- a/web/lib/opal/src/icons/index.ts
+++ b/web/lib/opal/src/icons/index.ts
@@ -72,6 +72,7 @@ export { default as SvgFileChartPie } from "@opal/icons/file-chart-pie";
 export { default as SvgFileSmall } from "@opal/icons/file-small";
 export { default as SvgFileText } from "@opal/icons/file-text";
 export { default as SvgFilter } from "@opal/icons/filter";
+export { default as SvgFilterPlus } from "@opal/icons/filter-plus";
 export { default as SvgFold } from "@opal/icons/fold";
 export { default as SvgFolder } from "@opal/icons/folder";
 export { default as SvgFolderIn } from "@opal/icons/folder-in";
diff --git a/web/src/layouts/input-layouts.tsx b/web/src/layouts/input-layouts.tsx
index 37fca2c7c4d..2d388992a8d 100644
--- a/web/src/layouts/input-layouts.tsx
+++ b/web/src/layouts/input-layouts.tsx
@@ -136,13 +136,14 @@ function HorizontalInputLayout({
         justifyContent="between"
         alignItems={center ? "center" : "start"}
       >
-        <div className="flex flex-col flex-1 self-stretch">
+        <div className="flex flex-col flex-1 min-w-0 self-stretch">
           <Content
             title={title}
             description={description}
             optional={optional}
             sizePreset={sizePreset}
             variant="section"
+            widthVariant="full"
           />
         </div>
         <div className="flex flex-col items-end">{children}</div>
diff --git a/web/src/lib/types.ts b/web/src/lib/types.ts
index 286315c3830..2cf84ad0c0e 100644
--- a/web/src/lib/types.ts
+++ b/web/src/lib/types.ts
@@ -79,7 +79,7 @@ export const USER_STATUS_LABELS: Record<UserStatus, string> = {
   [UserStatus.ACTIVE]: "Active",
   [UserStatus.INACTIVE]: "Inactive",
   [UserStatus.INVITED]: "Invite Pending",
-  [UserStatus.REQUESTED]: "Requested",
+  [UserStatus.REQUESTED]: "Request to Join",
 };
 
 export const INVALID_ROLE_HOVER_TEXT: Partial<Record<UserRole, string>> = {
diff --git a/web/src/refresh-components/table/DataTable.tsx b/web/src/refresh-components/table/DataTable.tsx
index 5d03b59dc0d..3eb427450e0 100644
--- a/web/src/refresh-components/table/DataTable.tsx
+++ b/web/src/refresh-components/table/DataTable.tsx
@@ -273,6 +273,7 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
         currentPage={currentPage}
         totalPages={totalPages}
         onPageChange={setPage}
+        leftExtra={footerConfig.leftExtra}
       />
     );
   }
@@ -301,7 +302,25 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
               : undefined),
           }}
         >
-          <Table>
+          <Table
+            width={
+              Object.keys(columnWidths).length > 0
+                ? Object.values(columnWidths).reduce((sum, w) => sum + w, 0)
+                : undefined
+            }
+          >
+            <colgroup>
+              {table.getAllLeafColumns().map((col) => (
+                <col
+                  key={col.id}
+                  style={
+                    columnWidths[col.id] != null
+                      ? { width: columnWidths[col.id] }
+                      : undefined
+                  }
+                />
+              ))}
+            </colgroup>
             <TableHeader>
               {table.getHeaderGroups().map((headerGroup) => (
                 <TableRow key={headerGroup.id}>
diff --git a/web/src/refresh-components/table/Footer.tsx b/web/src/refresh-components/table/Footer.tsx
index 9f292757922..0e91eca6911 100644
--- a/web/src/refresh-components/table/Footer.tsx
+++ b/web/src/refresh-components/table/Footer.tsx
@@ -61,6 +61,8 @@ interface FooterSummaryModeProps {
   totalPages: number;
   /** Called when the user navigates to a different page. */
   onPageChange: (page: number) => void;
+  /** Optional extra element rendered after the summary text (e.g. a download icon). */
+  leftExtra?: React.ReactNode;
   /** Controls overall footer sizing. `"regular"` (default) or `"small"`. */
   size?: TableSize;
   className?: string;
@@ -115,12 +117,15 @@ export default function Footer(props: FooterProps) {
             isSmall={isSmall}
           />
         ) : (
-          <SummaryLeft
-            rangeStart={props.rangeStart}
-            rangeEnd={props.rangeEnd}
-            totalItems={props.totalItems}
-            isSmall={isSmall}
-          />
+          <>
+            <SummaryLeft
+              rangeStart={props.rangeStart}
+              rangeEnd={props.rangeEnd}
+              totalItems={props.totalItems}
+              isSmall={isSmall}
+            />
+            {props.leftExtra}
+          </>
         )}
       </div>
 
diff --git a/web/src/refresh-components/table/TableCell.tsx b/web/src/refresh-components/table/TableCell.tsx
index dbeb95c6e4a..74f87b5b2de 100644
--- a/web/src/refresh-components/table/TableCell.tsx
+++ b/web/src/refresh-components/table/TableCell.tsx
@@ -21,13 +21,13 @@ export default function TableCell({
   const resolvedSize = size ?? contextSize;
   return (
     <td
-      className="tbl-cell"
+      className="tbl-cell overflow-hidden"
       data-size={resolvedSize}
       style={width != null ? { width } : undefined}
       {...props}
     >
       <div
-        className={cn("tbl-cell-inner", "flex items-center")}
+        className={cn("tbl-cell-inner", "flex items-center overflow-hidden")}
         data-size={resolvedSize}
       >
         {children}
diff --git a/web/src/refresh-components/table/types.ts b/web/src/refresh-components/table/types.ts
index f245dbb8547..c068cd0cf80 100644
--- a/web/src/refresh-components/table/types.ts
+++ b/web/src/refresh-components/table/types.ts
@@ -141,6 +141,8 @@ export interface DataTableFooterSelection {
 
 export interface DataTableFooterSummary {
   mode: "summary";
+  /** Optional extra element rendered after the summary text (e.g. a download icon). */
+  leftExtra?: ReactNode;
 }
 
 export type DataTableFooterConfig =
diff --git a/web/src/refresh-pages/admin/UsersPage/EditGroupsModal.tsx b/web/src/refresh-pages/admin/UsersPage/EditGroupsModal.tsx
new file mode 100644
index 00000000000..9971a6a90c0
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/EditGroupsModal.tsx
@@ -0,0 +1,332 @@
+"use client";
+
+import { useState, useMemo, useRef, useCallback } from "react";
+import { Button } from "@opal/components";
+import { SvgUsers, SvgUser, SvgLogOut, SvgCheck } from "@opal/icons";
+import { Disabled } from "@opal/core";
+import { ContentAction } from "@opal/layouts";
+import Modal from "@/refresh-components/Modal";
+import Text from "@/refresh-components/texts/Text";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
+import LineItem from "@/refresh-components/buttons/LineItem";
+import Separator from "@/refresh-components/Separator";
+import ShadowDiv from "@/refresh-components/ShadowDiv";
+import { Section } from "@/layouts/general-layouts";
+import { toast } from "@/hooks/useToast";
+import { UserRole, USER_ROLE_LABELS } from "@/lib/types";
+import useGroups from "@/hooks/useGroups";
+import { addUserToGroup, removeUserFromGroup, setUserRole } from "./svc";
+import type { UserRow } from "./interfaces";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const ASSIGNABLE_ROLES: UserRole[] = [
+  UserRole.ADMIN,
+  UserRole.GLOBAL_CURATOR,
+  UserRole.BASIC,
+];
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface EditGroupsModalProps {
+  user: UserRow & { id: string };
+  onClose: () => void;
+  onMutate: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function EditGroupsModal({
+  user,
+  onClose,
+  onMutate,
+}: EditGroupsModalProps) {
+  const { data: allGroups, isLoading: groupsLoading } = useGroups();
+  const [searchTerm, setSearchTerm] = useState("");
+  const [dropdownOpen, setDropdownOpen] = useState(false);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const closeDropdown = useCallback(() => {
+    // Delay to allow click events on dropdown items to fire before closing
+    setTimeout(() => {
+      if (!containerRef.current?.contains(document.activeElement)) {
+        setDropdownOpen(false);
+      }
+    }, 0);
+  }, []);
+  const [selectedRole, setSelectedRole] = useState<UserRole | "">(
+    user.role ?? ""
+  );
+
+  const initialMemberGroupIds = useMemo(
+    () => new Set(user.groups.map((g) => g.id)),
+    [user.groups]
+  );
+  const [memberGroupIds, setMemberGroupIds] = useState<Set<number>>(
+    () => new Set(initialMemberGroupIds)
+  );
+
+  // Dropdown shows all groups filtered by search term
+  const dropdownGroups = useMemo(() => {
+    if (!allGroups) return [];
+    if (searchTerm.length === 0) return allGroups;
+    const lower = searchTerm.toLowerCase();
+    return allGroups.filter((g) => g.name.toLowerCase().includes(lower));
+  }, [allGroups, searchTerm]);
+
+  // Joined groups shown in the modal body
+  const joinedGroups = useMemo(() => {
+    if (!allGroups) return [];
+    return allGroups.filter((g) => memberGroupIds.has(g.id));
+  }, [allGroups, memberGroupIds]);
+
+  const hasGroupChanges = useMemo(() => {
+    if (memberGroupIds.size !== initialMemberGroupIds.size) return true;
+    return Array.from(memberGroupIds).some(
+      (id) => !initialMemberGroupIds.has(id)
+    );
+  }, [memberGroupIds, initialMemberGroupIds]);
+
+  const hasRoleChange =
+    user.role !== null && selectedRole !== "" && selectedRole !== user.role;
+  const hasChanges = hasGroupChanges || hasRoleChange;
+
+  const toggleGroup = (groupId: number) => {
+    setMemberGroupIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(groupId)) {
+        next.delete(groupId);
+      } else {
+        next.add(groupId);
+      }
+      return next;
+    });
+  };
+
+  const handleSave = async () => {
+    setIsSubmitting(true);
+    try {
+      const toAdd = Array.from(memberGroupIds).filter(
+        (id) => !initialMemberGroupIds.has(id)
+      );
+      const toRemove = Array.from(initialMemberGroupIds).filter(
+        (id) => !memberGroupIds.has(id)
+      );
+
+      if (user.id) {
+        for (const groupId of toAdd) {
+          await addUserToGroup(groupId, user.id);
+        }
+        for (const groupId of toRemove) {
+          const group = allGroups?.find((g) => g.id === groupId);
+          if (group) {
+            const currentUserIds = group.users.map((u) => u.id);
+            const ccPairIds = group.cc_pairs.map((cc) => cc.id);
+            await removeUserFromGroup(
+              groupId,
+              currentUserIds,
+              user.id,
+              ccPairIds
+            );
+          }
+        }
+      }
+
+      if (
+        user.role !== null &&
+        selectedRole !== "" &&
+        selectedRole !== user.role
+      ) {
+        await setUserRole(user.email, selectedRole);
+      }
+
+      onMutate();
+      toast.success("User updated");
+      onClose();
+    } catch (err) {
+      onMutate(); // refresh to show partially-applied state
+      toast.error(err instanceof Error ? err.message : "An error occurred");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const displayName = user.personal_name ?? user.email;
+
+  return (
+    <Modal open onOpenChange={(isOpen) => !isOpen && onClose()}>
+      <Modal.Content width="sm">
+        <Modal.Header
+          icon={SvgUsers}
+          title="Edit User's Groups & Roles"
+          description={
+            user.personal_name
+              ? `${user.personal_name} (${user.email})`
+              : user.email
+          }
+          onClose={onClose}
+        />
+        <Modal.Body twoTone>
+          <Section
+            gap={1}
+            height="auto"
+            alignItems="stretch"
+            justifyContent="start"
+          >
+            {/* Subsection: white card behind search + groups */}
+            <div className="relative">
+              <div className="absolute -inset-2 bg-background-neutral-00 rounded-12" />
+              <Section
+                gap={0.5}
+                height="auto"
+                alignItems="stretch"
+                justifyContent="start"
+              >
+                <div ref={containerRef} className="relative">
+                  <InputTypeIn
+                    value={searchTerm}
+                    onChange={(e) => {
+                      setSearchTerm(e.target.value);
+                      if (!dropdownOpen) setDropdownOpen(true);
+                    }}
+                    onFocus={() => setDropdownOpen(true)}
+                    onBlur={closeDropdown}
+                    placeholder="Search groups to join..."
+                    leftSearchIcon
+                  />
+                  {dropdownOpen && (
+                    <div className="absolute top-full left-0 right-0 z-50 mt-1 bg-background-neutral-00 border border-border-02 rounded-12 shadow-md p-1">
+                      {groupsLoading ? (
+                        <Text as="p" text03 secondaryBody className="px-3 py-2">
+                          Loading groups...
+                        </Text>
+                      ) : dropdownGroups.length === 0 ? (
+                        <Text as="p" text03 secondaryBody className="px-3 py-2">
+                          No groups found
+                        </Text>
+                      ) : (
+                        <ShadowDiv className="max-h-[200px] flex flex-col gap-1">
+                          {dropdownGroups.map((group) => {
+                            const isMember = memberGroupIds.has(group.id);
+                            return (
+                              <LineItem
+                                key={group.id}
+                                icon={isMember ? SvgCheck : SvgUsers}
+                                description={`${group.users.length} ${
+                                  group.users.length === 1 ? "user" : "users"
+                                }`}
+                                selected={isMember}
+                                emphasized={isMember}
+                                onMouseDown={(e: React.MouseEvent) =>
+                                  e.preventDefault()
+                                }
+                                onClick={() => toggleGroup(group.id)}
+                              >
+                                {group.name}
+                              </LineItem>
+                            );
+                          })}
+                        </ShadowDiv>
+                      )}
+                    </div>
+                  )}
+                </div>
+
+                {joinedGroups.length === 0 ? (
+                  <LineItem
+                    icon={SvgUsers}
+                    description={`${displayName} is not in any groups.`}
+                    muted
+                  >
+                    No groups joined
+                  </LineItem>
+                ) : (
+                  <ShadowDiv className="flex flex-col gap-1 max-h-[200px]">
+                    {joinedGroups.map((group) => (
+                      <div
+                        key={group.id}
+                        className="bg-background-tint-01 rounded-08"
+                      >
+                        <LineItem
+                          icon={SvgUsers}
+                          description={`${group.users.length} ${
+                            group.users.length === 1 ? "user" : "users"
+                          }`}
+                          rightChildren={
+                            <SvgLogOut className="w-4 h-4 text-text-03" />
+                          }
+                          onClick={() => toggleGroup(group.id)}
+                        >
+                          {group.name}
+                        </LineItem>
+                      </div>
+                    ))}
+                  </ShadowDiv>
+                )}
+              </Section>
+            </div>
+
+            {user.role && (
+              <>
+                <Separator noPadding />
+
+                <ContentAction
+                  title="User Role"
+                  description="This controls their general permissions."
+                  sizePreset="main-ui"
+                  variant="section"
+                  paddingVariant="fit"
+                  rightChildren={
+                    <InputSelect
+                      value={selectedRole}
+                      onValueChange={(v) => setSelectedRole(v as UserRole)}
+                    >
+                      <InputSelect.Trigger />
+                      <InputSelect.Content>
+                        {user.role && !ASSIGNABLE_ROLES.includes(user.role) && (
+                          <InputSelect.Item
+                            key={user.role}
+                            value={user.role}
+                            icon={SvgUser}
+                          >
+                            {USER_ROLE_LABELS[user.role]}
+                          </InputSelect.Item>
+                        )}
+                        {ASSIGNABLE_ROLES.map((role) => (
+                          <InputSelect.Item
+                            key={role}
+                            value={role}
+                            icon={SvgUser}
+                          >
+                            {USER_ROLE_LABELS[role]}
+                          </InputSelect.Item>
+                        ))}
+                      </InputSelect.Content>
+                    </InputSelect>
+                  }
+                />
+              </>
+            )}
+          </Section>
+        </Modal.Body>
+
+        <Modal.Footer>
+          <Button prominence="secondary" onClick={onClose}>
+            Cancel
+          </Button>
+          <Disabled disabled={isSubmitting || !hasChanges}>
+            <Button onClick={handleSave}>Save Changes</Button>
+          </Disabled>
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx b/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx
new file mode 100644
index 00000000000..f75b4e1bfc5
--- /dev/null
+++ b/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx
@@ -0,0 +1,212 @@
+"use client";
+
+import {
+  useState,
+  useRef,
+  useLayoutEffect,
+  useCallback,
+  useEffect,
+} from "react";
+import { SvgEdit } from "@opal/icons";
+import { Tag } from "@opal/components";
+import IconButton from "@/refresh-components/buttons/IconButton";
+import Text from "@/refresh-components/texts/Text";
+import SimpleTooltip from "@/refresh-components/SimpleTooltip";
+import EditGroupsModal from "./EditGroupsModal";
+import type { UserRow, UserGroupInfo } from "./interfaces";
+
+interface GroupsCellProps {
+  groups: UserGroupInfo[];
+  user: UserRow;
+  onMutate: () => void;
+}
+
+/**
+ * Measures how many Tag pills fit in the container, accounting for a "+N"
+ * overflow counter when not all tags are visible. Uses a two-phase render:
+ * first renders all tags (clipped by overflow:hidden) for measurement, then
+ * re-renders with only the visible subset + "+N".
+ *
+ * Hovering the cell shows a tooltip with ALL groups. Clicking opens the
+ * edit groups modal.
+ */
+export default function GroupsCell({
+  groups,
+  user,
+  onMutate,
+}: GroupsCellProps) {
+  const [showModal, setShowModal] = useState(false);
+  const [visibleCount, setVisibleCount] = useState<number | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const computeVisibleCount = useCallback(() => {
+    const container = containerRef.current;
+    if (!container || groups.length <= 1) {
+      setVisibleCount(groups.length);
+      return;
+    }
+
+    const tags = container.querySelectorAll<HTMLElement>("[data-group-tag]");
+    if (tags.length === 0) return;
+
+    const containerWidth = container.clientWidth;
+    const gap = 4; // gap-1
+    const counterWidth = 32; // "+N" Tag approximate width
+
+    let used = 0;
+    let count = 0;
+
+    for (let i = 0; i < tags.length; i++) {
+      const tagWidth = tags[i]!.offsetWidth;
+      const gapBefore = count > 0 ? gap : 0;
+      const hasMore = i < tags.length - 1;
+      const reserve = hasMore ? gap + counterWidth : 0;
+
+      if (used + gapBefore + tagWidth + reserve <= containerWidth) {
+        used += gapBefore + tagWidth;
+        count++;
+      } else {
+        break;
+      }
+    }
+
+    setVisibleCount(Math.max(1, count));
+  }, [groups]);
+
+  // Reset to measurement phase when groups change
+  useLayoutEffect(() => {
+    setVisibleCount(null);
+  }, [groups]);
+
+  // Measure after the "show all" render
+  useLayoutEffect(() => {
+    if (visibleCount !== null) return;
+    computeVisibleCount();
+  }, [visibleCount, computeVisibleCount]);
+
+  // Re-measure on container resize.
+  // The ref moves between DOM elements depending on overflow state, so we
+  // track the observed node and re-attach when it changes.
+  const observedNodeRef = useRef<HTMLElement | null>(null);
+  const observerRef = useRef<ResizeObserver | null>(null);
+
+  useEffect(() => {
+    if (!observerRef.current) {
+      observerRef.current = new ResizeObserver(() => {
+        setVisibleCount(null);
+      });
+    }
+    const observer = observerRef.current;
+    const node = containerRef.current;
+
+    if (node !== observedNodeRef.current) {
+      if (observedNodeRef.current) {
+        observer.unobserve(observedNodeRef.current);
+      }
+      if (node) {
+        observer.observe(node);
+      }
+      observedNodeRef.current = node;
+    }
+
+    return () => {
+      observer.disconnect();
+      observedNodeRef.current = null;
+    };
+  });
+
+  const isMeasuring = visibleCount === null;
+  const effectiveVisible = visibleCount ?? groups.length;
+  const overflowCount = groups.length - effectiveVisible;
+  const hasOverflow = !isMeasuring && overflowCount > 0;
+
+  const allGroupsTooltip = (
+    <div className="flex flex-wrap gap-1 max-w-[14rem]">
+      {groups.map((g) => (
+        <div key={g.id} className="max-w-[10rem]">
+          <Tag title={g.name} size="md" />
+        </div>
+      ))}
+    </div>
+  );
+
+  const tagsContent = (
+    <>
+      {(isMeasuring ? groups : groups.slice(0, effectiveVisible)).map((g) => (
+        <div key={g.id} data-group-tag className="flex-shrink-0">
+          <Tag title={g.name} size="md" />
+        </div>
+      ))}
+      {hasOverflow && (
+        <div className="flex-shrink-0">
+          <Tag title={`+${overflowCount}`} size="md" />
+        </div>
+      )}
+    </>
+  );
+
+  return (
+    <>
+      <div
+        className={`group/groups relative flex items-center w-full min-w-0 ${
+          user.id ? "cursor-pointer" : ""
+        }`}
+        onClick={user.id ? () => setShowModal(true) : undefined}
+      >
+        {groups.length === 0 ? (
+          <div
+            ref={containerRef}
+            className="flex items-center gap-1 overflow-hidden flex-nowrap min-w-0 pr-7"
+          >
+            <Text as="span" secondaryBody text03>
+              —
+            </Text>
+          </div>
+        ) : hasOverflow ? (
+          <SimpleTooltip
+            side="bottom"
+            align="start"
+            tooltip={allGroupsTooltip}
+            className="bg-background-neutral-01 border border-border-01 shadow-sm"
+            delayDuration={200}
+          >
+            <div
+              ref={containerRef}
+              className="flex items-center gap-1 overflow-hidden flex-nowrap min-w-0 pr-7"
+            >
+              {tagsContent}
+            </div>
+          </SimpleTooltip>
+        ) : (
+          <div
+            ref={containerRef}
+            className="flex items-center gap-1 overflow-hidden flex-nowrap min-w-0 pr-7"
+          >
+            {tagsContent}
+          </div>
+        )}
+        {user.id && (
+          <IconButton
+            tertiary
+            icon={SvgEdit}
+            tooltip="Edit"
+            toolTipPosition="left"
+            tooltipSize="sm"
+            className="absolute right-0 opacity-0 group-hover/groups:opacity-100 transition-opacity"
+            onClick={(e) => {
+              e.stopPropagation();
+              setShowModal(true);
+            }}
+          />
+        )}
+      </div>
+      {showModal && user.id != null && (
+        <EditGroupsModal
+          user={{ ...user, id: user.id }}
+          onClose={() => setShowModal(false)}
+          onMutate={onMutate}
+        />
+      )}
+    </>
+  );
+}
diff --git a/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx b/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx
index e7b395060c8..038b2adabd6 100644
--- a/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UserFilters.tsx
@@ -1,14 +1,20 @@
 "use client";
 
 import { useState } from "react";
-import { SvgCheck, SvgSlack, SvgUser, SvgUsers } from "@opal/icons";
+import {
+  SvgCheck,
+  SvgSlack,
+  SvgUser,
+  SvgUserManage,
+  SvgUsers,
+} from "@opal/icons";
 import type { IconFunctionComponent } from "@opal/types";
 import FilterButton from "@/refresh-components/buttons/FilterButton";
 import Popover from "@/refresh-components/Popover";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import LineItem from "@/refresh-components/buttons/LineItem";
 import Text from "@/refresh-components/texts/Text";
-import Separator from "@/refresh-components/Separator";
+import ShadowDiv from "@/refresh-components/ShadowDiv";
 import {
   UserRole,
   UserStatus,
@@ -18,29 +24,20 @@ import {
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
 import type { GroupOption, StatusFilter, StatusCountMap } from "./interfaces";
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface UserFiltersProps {
-  selectedRoles: UserRole[];
-  onRolesChange: (roles: UserRole[]) => void;
-  selectedGroups: number[];
-  onGroupsChange: (groupIds: number[]) => void;
-  groups: GroupOption[];
-  selectedStatuses: StatusFilter;
-  onStatusesChange: (statuses: StatusFilter) => void;
-  roleCounts: Record<string, number>;
-  statusCounts: StatusCountMap;
-}
-
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const FILTERABLE_ROLES = Object.entries(USER_ROLE_LABELS).filter(
-  ([role]) => role !== UserRole.EXT_PERM_USER
-) as [UserRole, string][];
+const VISIBLE_FILTER_ROLES: UserRole[] = [
+  UserRole.ADMIN,
+  UserRole.GLOBAL_CURATOR,
+  UserRole.BASIC,
+  UserRole.SLACK_USER,
+];
+
+const FILTERABLE_ROLES = VISIBLE_FILTER_ROLES.map(
+  (role) => [role, USER_ROLE_LABELS[role]] as [UserRole, string]
+);
 
 const FILTERABLE_STATUSES = (
   Object.entries(USER_STATUS_LABELS) as [UserStatus, string][]
@@ -49,6 +46,7 @@ const FILTERABLE_STATUSES = (
 );
 
 const ROLE_ICONS: Partial<Record<UserRole, IconFunctionComponent>> = {
+  [UserRole.ADMIN]: SvgUserManage,
   [UserRole.SLACK_USER]: SvgSlack,
 };
 
@@ -76,6 +74,18 @@ function CountBadge({ count }: { count: number | undefined }) {
 // Component
 // ---------------------------------------------------------------------------
 
+interface UserFiltersProps {
+  selectedRoles: UserRole[];
+  onRolesChange: (roles: UserRole[]) => void;
+  selectedGroups: number[];
+  onGroupsChange: (groupIds: number[]) => void;
+  groups: GroupOption[];
+  selectedStatuses: StatusFilter;
+  onStatusesChange: (statuses: StatusFilter) => void;
+  roleCounts: Record<string, number>;
+  statusCounts: StatusCountMap;
+}
+
 export default function UserFilters({
   selectedRoles,
   onRolesChange,
@@ -101,14 +111,6 @@ export default function UserFilters({
     }
   };
 
-  const roleLabel = hasRoleFilter
-    ? FILTERABLE_ROLES.filter(([role]) => selectedRoles.includes(role))
-        .map(([, label]) => label)
-        .slice(0, 2)
-        .join(", ") +
-      (selectedRoles.length > 2 ? `, +${selectedRoles.length - 2}` : "")
-    : "All Account Types";
-
   const toggleGroup = (groupId: number) => {
     if (selectedGroups.includes(groupId)) {
       onGroupsChange(selectedGroups.filter((id) => id !== groupId));
@@ -117,6 +119,22 @@ export default function UserFilters({
     }
   };
 
+  const toggleStatus = (status: UserStatus) => {
+    if (selectedStatuses.includes(status)) {
+      onStatusesChange(selectedStatuses.filter((s) => s !== status));
+    } else {
+      onStatusesChange([...selectedStatuses, status]);
+    }
+  };
+
+  const roleLabel = hasRoleFilter
+    ? FILTERABLE_ROLES.filter(([role]) => selectedRoles.includes(role))
+        .map(([, label]) => label)
+        .slice(0, 2)
+        .join(", ") +
+      (selectedRoles.length > 2 ? `, +${selectedRoles.length - 2}` : "")
+    : "All Account Types";
+
   const groupLabel = hasGroupFilter
     ? groups
         .filter((g) => selectedGroups.includes(g.id))
@@ -126,14 +144,6 @@ export default function UserFilters({
       (selectedGroups.length > 2 ? `, +${selectedGroups.length - 2}` : "")
     : "All Groups";
 
-  const toggleStatus = (status: UserStatus) => {
-    if (selectedStatuses.includes(status)) {
-      onStatusesChange(selectedStatuses.filter((s) => s !== status));
-    } else {
-      onStatusesChange([...selectedStatuses, status]);
-    }
-  };
-
   const statusLabel = hasStatusFilter
     ? FILTERABLE_STATUSES.filter(([status]) =>
         selectedStatuses.includes(status)
@@ -166,13 +176,13 @@ export default function UserFilters({
         <Popover.Content align="start">
           <div className="flex flex-col gap-1 p-1 min-w-[200px]">
             <LineItem
-              icon={SvgUsers}
+              icon={!hasRoleFilter ? SvgCheck : SvgUsers}
               selected={!hasRoleFilter}
+              emphasized={!hasRoleFilter}
               onClick={() => onRolesChange([])}
             >
               All Account Types
             </LineItem>
-            <Separator noPadding />
             {FILTERABLE_ROLES.map(([role, label]) => {
               const isSelected = selectedRoles.includes(role);
               const roleIcon = ROLE_ICONS[role] ?? SvgUser;
@@ -181,6 +191,7 @@ export default function UserFilters({
                   key={role}
                   icon={isSelected ? SvgCheck : roleIcon}
                   selected={isSelected}
+                  emphasized={isSelected}
                   onClick={() => toggleRole(role)}
                   rightChildren={<CountBadge count={roleCounts[role]} />}
                 >
@@ -211,30 +222,30 @@ export default function UserFilters({
         </Popover.Trigger>
         <Popover.Content align="start">
           <div className="flex flex-col gap-1 p-1 min-w-[200px]">
-            <div className="px-1 pt-1">
-              <InputTypeIn
-                value={groupSearch}
-                onChange={(e) => setGroupSearch(e.target.value)}
-                placeholder="Search groups..."
-                leftSearchIcon
-              />
-            </div>
+            <InputTypeIn
+              value={groupSearch}
+              onChange={(e) => setGroupSearch(e.target.value)}
+              placeholder="Search groups..."
+              leftSearchIcon
+              variant="internal"
+            />
             <LineItem
-              icon={SvgUsers}
+              icon={!hasGroupFilter ? SvgCheck : SvgUsers}
               selected={!hasGroupFilter}
+              emphasized={!hasGroupFilter}
               onClick={() => onGroupsChange([])}
             >
               All Groups
             </LineItem>
-            <Separator noPadding />
-            <div className="flex flex-col gap-1 max-h-[240px] overflow-y-auto">
+            <ShadowDiv className="flex flex-col gap-1 max-h-[240px]">
               {filteredGroups.map((group) => {
                 const isSelected = selectedGroups.includes(group.id);
                 return (
                   <LineItem
                     key={group.id}
-                    icon={isSelected ? SvgCheck : undefined}
+                    icon={isSelected ? SvgCheck : SvgUsers}
                     selected={isSelected}
+                    emphasized={isSelected}
                     onClick={() => toggleGroup(group.id)}
                     rightChildren={<CountBadge count={group.memberCount} />}
                   >
@@ -247,7 +258,7 @@ export default function UserFilters({
                   No groups found
                 </Text>
               )}
-            </div>
+            </ShadowDiv>
           </div>
         </Popover.Content>
       </Popover>
@@ -266,21 +277,22 @@ export default function UserFilters({
         <Popover.Content align="start">
           <div className="flex flex-col gap-1 p-1 min-w-[200px]">
             <LineItem
-              icon={!hasStatusFilter ? SvgCheck : undefined}
+              icon={!hasStatusFilter ? SvgCheck : SvgUser}
               selected={!hasStatusFilter}
+              emphasized={!hasStatusFilter}
               onClick={() => onStatusesChange([])}
             >
               All Status
             </LineItem>
-            <Separator noPadding />
             {FILTERABLE_STATUSES.map(([status, label]) => {
               const isSelected = selectedStatuses.includes(status);
               const countKey = STATUS_COUNT_KEY[status];
               return (
                 <LineItem
                   key={status}
-                  icon={isSelected ? SvgCheck : undefined}
+                  icon={isSelected ? SvgCheck : SvgUser}
                   selected={isSelected}
+                  emphasized={isSelected}
                   onClick={() => toggleStatus(status)}
                   rightChildren={<CountBadge count={statusCounts[countKey]} />}
                 >
diff --git a/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx b/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx
index 7a87e402dab..20984e233ca 100644
--- a/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UserRowActions.tsx
@@ -2,21 +2,40 @@
 
 import { useState } from "react";
 import { Button } from "@opal/components";
-import { SvgMoreHorizontal, SvgXCircle, SvgTrash, SvgCheck } from "@opal/icons";
+import {
+  SvgMoreHorizontal,
+  SvgUsers,
+  SvgXCircle,
+  SvgTrash,
+  SvgCheck,
+} from "@opal/icons";
 import { Disabled } from "@opal/core";
 import Popover from "@/refresh-components/Popover";
 import ConfirmationModalLayout from "@/refresh-components/layouts/ConfirmationModalLayout";
 import Text from "@/refresh-components/texts/Text";
 import { UserStatus } from "@/lib/types";
 import { toast } from "@/hooks/useToast";
-import { deactivateUser, activateUser, deleteUser } from "./svc";
+import {
+  deactivateUser,
+  activateUser,
+  deleteUser,
+  cancelInvite,
+  approveRequest,
+} from "./svc";
+import EditGroupsModal from "./EditGroupsModal";
 import type { UserRow } from "./interfaces";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-type ModalType = "deactivate" | "activate" | "delete" | null;
+type ModalType =
+  | "deactivate"
+  | "activate"
+  | "delete"
+  | "cancelInvite"
+  | "editGroups"
+  | null;
 
 interface UserRowActionsProps {
   user: UserRow;
@@ -52,14 +71,101 @@ export default function UserRowActions({
     }
   }
 
-  // Only show actions for accepted users (active or inactive).
-  // Invited/requested users have no row actions in this PR.
-  if (
-    user.status !== UserStatus.ACTIVE &&
-    user.status !== UserStatus.INACTIVE
-  ) {
-    return null;
-  }
+  const openModal = (type: ModalType) => {
+    setPopoverOpen(false);
+    setModal(type);
+  };
+
+  // Status-aware action menus
+  const actionButtons = (() => {
+    switch (user.status) {
+      case UserStatus.INVITED:
+        return (
+          <Button
+            prominence="tertiary"
+            variant="danger"
+            icon={SvgXCircle}
+            onClick={() => openModal("cancelInvite")}
+          >
+            Cancel Invite
+          </Button>
+        );
+
+      case UserStatus.REQUESTED:
+        return (
+          <Button
+            prominence="tertiary"
+            icon={SvgCheck}
+            onClick={() => {
+              setPopoverOpen(false);
+              handleAction(
+                () => approveRequest(user.email),
+                "Request approved"
+              );
+            }}
+          >
+            Approve
+          </Button>
+        );
+
+      case UserStatus.ACTIVE:
+        return (
+          <>
+            {user.id && (
+              <Button
+                prominence="tertiary"
+                icon={SvgUsers}
+                onClick={() => openModal("editGroups")}
+              >
+                Groups
+              </Button>
+            )}
+            <Button
+              prominence="tertiary"
+              icon={SvgXCircle}
+              onClick={() => openModal("deactivate")}
+            >
+              Deactivate User
+            </Button>
+          </>
+        );
+
+      case UserStatus.INACTIVE:
+        return (
+          <>
+            {user.id && (
+              <Button
+                prominence="tertiary"
+                icon={SvgUsers}
+                onClick={() => openModal("editGroups")}
+              >
+                Groups
+              </Button>
+            )}
+            <Button
+              prominence="tertiary"
+              icon={SvgCheck}
+              onClick={() => openModal("activate")}
+            >
+              Activate User
+            </Button>
+            <Button
+              prominence="tertiary"
+              variant="danger"
+              icon={SvgTrash}
+              onClick={() => openModal("delete")}
+            >
+              Delete User
+            </Button>
+          </>
+        );
+
+      default: {
+        const _exhaustive: never = user.status;
+        return null;
+      }
+    }
+  })();
 
   // SCIM-managed users cannot be modified from the UI — changes would be
   // overwritten on the next IdP sync.
@@ -74,46 +180,47 @@ export default function UserRowActions({
           <Button prominence="tertiary" icon={SvgMoreHorizontal} />
         </Popover.Trigger>
         <Popover.Content align="end">
-          <div className="flex flex-col gap-0.5 p-1">
-            {user.status === UserStatus.ACTIVE ? (
+          <div className="flex flex-col gap-0.5 p-1">{actionButtons}</div>
+        </Popover.Content>
+      </Popover>
+
+      {modal === "editGroups" && user.id && (
+        <EditGroupsModal
+          user={user as UserRow & { id: string }}
+          onClose={() => setModal(null)}
+          onMutate={onMutate}
+        />
+      )}
+
+      {modal === "cancelInvite" && (
+        <ConfirmationModalLayout
+          icon={SvgXCircle}
+          title="Cancel Invite"
+          onClose={() => setModal(null)}
+          submit={
+            <Disabled disabled={isSubmitting}>
               <Button
-                prominence="tertiary"
-                icon={SvgXCircle}
+                variant="danger"
                 onClick={() => {
-                  setPopoverOpen(false);
-                  setModal("deactivate");
+                  handleAction(
+                    () => cancelInvite(user.email),
+                    "Invite cancelled"
+                  );
                 }}
               >
-                Deactivate User
+                Cancel
               </Button>
-            ) : (
-              <>
-                <Button
-                  prominence="tertiary"
-                  icon={SvgCheck}
-                  onClick={() => {
-                    setPopoverOpen(false);
-                    setModal("activate");
-                  }}
-                >
-                  Activate User
-                </Button>
-                <Button
-                  prominence="tertiary"
-                  variant="danger"
-                  icon={SvgTrash}
-                  onClick={() => {
-                    setPopoverOpen(false);
-                    setModal("delete");
-                  }}
-                >
-                  Delete User
-                </Button>
-              </>
-            )}
-          </div>
-        </Popover.Content>
-      </Popover>
+            </Disabled>
+          }
+        >
+          <Text as="p" text03>
+            <Text as="span" text05>
+              {user.email}
+            </Text>{" "}
+            will no longer be able to join Onyx with this invite.
+          </Text>
+        </ConfirmationModalLayout>
+      )}
 
       {modal === "deactivate" && (
         <ConfirmationModalLayout
@@ -141,7 +248,8 @@ export default function UserRowActions({
               {user.email}
             </Text>{" "}
             will immediately lose access to Onyx. Their sessions and agents will
-            be preserved. You can reactivate this account later.
+            be preserved. Their license seat will be freed. You can reactivate
+            this account later.
           </Text>
         </ConfirmationModalLayout>
       )}
@@ -201,7 +309,7 @@ export default function UserRowActions({
               {user.email}
             </Text>{" "}
             will be permanently removed from Onyx. All of their session history
-            will be deleted. This cannot be undone.
+            will be deleted. Deletion cannot be undone.
           </Text>
         </ConfirmationModalLayout>
       )}
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx b/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
index 54d49265058..0e37f67250f 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersSummary.tsx
@@ -1,14 +1,15 @@
-import { SvgArrowUpRight, SvgFilter, SvgUserSync } from "@opal/icons";
+import { SvgArrowUpRight, SvgFilterPlus, SvgUserSync } from "@opal/icons";
 import { ContentAction } from "@opal/layouts";
 import { Button } from "@opal/components";
 import { Section } from "@/layouts/general-layouts";
 import Card from "@/refresh-components/cards/Card";
+import IconButton from "@/refresh-components/buttons/IconButton";
 import Text from "@/refresh-components/texts/Text";
 import Link from "next/link";
 import { ADMIN_PATHS } from "@/lib/admin-routes";
 
 // ---------------------------------------------------------------------------
-// Stats cell — number + label
+// Stats cell — number + label + hover filter icon
 // ---------------------------------------------------------------------------
 
 type StatCellProps = {
@@ -34,12 +35,18 @@ function StatCell({ value, label, onFilter }: StatCellProps) {
         {label}
       </Text>
       {onFilter && (
-        <div className="absolute right-2 top-2 flex items-center gap-1 opacity-0 group-hover/stat:opacity-100 transition-opacity">
-          <Text as="span" secondaryBody text03>
-            Filter
-          </Text>
-          <SvgFilter size={16} className="text-text-03" />
-        </div>
+        <IconButton
+          tertiary
+          icon={SvgFilterPlus}
+          tooltip="Add Filter"
+          toolTipPosition="left"
+          tooltipSize="sm"
+          className="absolute right-1 top-1 opacity-0 group-hover/stat:opacity-100 transition-opacity"
+          onClick={(e) => {
+            e.stopPropagation();
+            onFilter();
+          }}
+        />
       )}
     </div>
   );
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
index 0ad9cdb3c7e..3f816eb6600 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
@@ -4,6 +4,8 @@ import { useMemo, useState } from "react";
 import DataTable from "@/refresh-components/table/DataTable";
 import { createTableColumns } from "@/refresh-components/table/columns";
 import { Content } from "@opal/layouts";
+import { Button } from "@opal/components";
+import { SvgDownload } from "@opal/icons";
 import SvgNoResult from "@opal/illustrations/no-result";
 import { IllustrationContent } from "@opal/layouts";
 import SimpleLoader from "@/refresh-components/loaders/SimpleLoader";
@@ -14,11 +16,11 @@ import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useAdminUsers from "@/hooks/useAdminUsers";
 import useGroups from "@/hooks/useGroups";
 import UserFilters from "./UserFilters";
+import GroupsCell from "./GroupsCell";
 import UserRowActions from "./UserRowActions";
 import UserRoleCell from "./UserRoleCell";
 import type {
   UserRow,
-  UserGroupInfo,
   GroupOption,
   StatusFilter,
   StatusCountMap,
@@ -40,37 +42,6 @@ function renderNameColumn(email: string, row: UserRow) {
   );
 }
 
-function renderGroupsColumn(groups: UserGroupInfo[]) {
-  if (!groups.length) {
-    return (
-      <Text as="span" secondaryBody text03>
-        {"\u2014"}
-      </Text>
-    );
-  }
-  const visible = groups.slice(0, 2);
-  const overflow = groups.length - visible.length;
-  return (
-    <div className="flex items-center gap-1 flex-nowrap overflow-hidden min-w-0">
-      {visible.map((g) => (
-        <span
-          key={g.id}
-          className="inline-flex items-center flex-shrink-0 rounded-md bg-background-tint-02 px-2 py-0.5 whitespace-nowrap"
-        >
-          <Text as="span" secondaryBody text03>
-            {g.name}
-          </Text>
-        </span>
-      ))}
-      {overflow > 0 && (
-        <Text as="span" secondaryBody text03>
-          +{overflow}
-        </Text>
-      )}
-    </div>
-  );
-}
-
 function renderStatusColumn(value: UserStatus, row: UserRow) {
   return (
     <div className="flex flex-col">
@@ -118,7 +89,9 @@ function buildColumns(onMutate: () => void) {
       weight: 24,
       minWidth: 200,
       enableSorting: false,
-      cell: renderGroupsColumn,
+      cell: (value, row) => (
+        <GroupsCell groups={value} user={row} onMutate={onMutate} />
+      ),
     }),
     tc.column("role", {
       header: "Account Type",
@@ -254,7 +227,20 @@ export default function UsersTable({
           getRowId={(row) => row.id ?? row.email}
           pageSize={PAGE_SIZE}
           searchTerm={searchTerm}
-          footer={{ mode: "summary" }}
+          footer={{
+            mode: "summary",
+            leftExtra: (
+              <Button
+                icon={SvgDownload}
+                prominence="tertiary"
+                size="sm"
+                tooltip="Download CSV"
+                onClick={() => {
+                  window.open("/api/manage/users/download", "_blank");
+                }}
+              />
+            ),
+          }}
         />
       )}
     </div>
diff --git a/web/src/refresh-pages/admin/UsersPage/svc.ts b/web/src/refresh-pages/admin/UsersPage/svc.ts
index 8d010745d0c..fc452824b63 100644
--- a/web/src/refresh-pages/admin/UsersPage/svc.ts
+++ b/web/src/refresh-pages/admin/UsersPage/svc.ts
@@ -59,6 +59,63 @@ export async function setUserRole(
   }
 }
 
+export async function addUserToGroup(
+  groupId: number,
+  userId: string
+): Promise<void> {
+  const res = await fetch(`/api/manage/admin/user-group/${groupId}/add-users`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ user_ids: [userId] }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to add user to group"));
+  }
+}
+
+export async function removeUserFromGroup(
+  groupId: number,
+  currentUserIds: string[],
+  userIdToRemove: string,
+  ccPairIds: number[]
+): Promise<void> {
+  const res = await fetch(`/api/manage/admin/user-group/${groupId}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      user_ids: currentUserIds.filter((id) => id !== userIdToRemove),
+      cc_pair_ids: ccPairIds,
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(
+      await parseErrorDetail(res, "Failed to remove user from group")
+    );
+  }
+}
+
+export async function cancelInvite(email: string): Promise<void> {
+  const res = await fetch("/api/manage/admin/remove-invited-user", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ user_email: email }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to cancel invite"));
+  }
+}
+
+export async function approveRequest(email: string): Promise<void> {
+  const res = await fetch("/api/tenants/users/invite/approve", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+  if (!res.ok) {
+    throw new Error(await parseErrorDetail(res, "Failed to approve request"));
+  }
+}
+
 export async function inviteUsers(emails: string[]): Promise<void> {
   const res = await fetch("/api/manage/admin/users", {
     method: "PUT",

From 868c9428e23bf2b0f6a2a331a31057fb082b66c6 Mon Sep 17 00:00:00 2001
From: Nikolas Garza <90273783+nmgarza5@users.noreply.github.com>
Date: Thu, 12 Mar 2026 22:42:21 -0700
Subject: [PATCH 267/267] feat(admin): switch to new Users page and remove v2
 route - 9/9 (#9223)

---
 web/src/app/admin/users/page.tsx              | 343 +-----------------
 web/src/app/admin/users2/page.tsx             |   1 -
 web/src/components/admin/ClientLayout.tsx     |   1 -
 web/src/lib/admin-routes.ts                   |   8 +-
 .../refresh-components/table/DataTable.tsx    |   8 +
 web/src/refresh-components/table/types.ts     |   2 +
 .../admin/UsersPage/GroupsCell.tsx            |  51 +--
 .../admin/UsersPage/UserRoleCell.tsx          |  80 ++--
 .../admin/UsersPage/UsersTable.tsx            |  67 ++--
 web/src/refresh-pages/admin/UsersPage/svc.ts  |  17 +
 web/src/sections/sidebar/AdminSidebar.tsx     |   4 +-
 11 files changed, 125 insertions(+), 457 deletions(-)
 delete mode 100644 web/src/app/admin/users2/page.tsx

diff --git a/web/src/app/admin/users/page.tsx b/web/src/app/admin/users/page.tsx
index 5902b120325..1988d3c47c1 100644
--- a/web/src/app/admin/users/page.tsx
+++ b/web/src/app/admin/users/page.tsx
@@ -1,342 +1 @@
-"use client";
-
-import { useState } from "react";
-import SimpleTabs from "@/refresh-components/SimpleTabs";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import InvitedUserTable from "@/components/admin/users/InvitedUserTable";
-import SignedUpUserTable from "@/components/admin/users/SignedUpUserTable";
-import Modal from "@/refresh-components/Modal";
-import { ThreeDotsLoader } from "@/components/Loading";
-import { toast } from "@/hooks/useToast";
-import * as SettingsLayouts from "@/layouts/settings-layouts";
-import { errorHandlingFetcher } from "@/lib/fetcher";
-import useSWR, { mutate } from "swr";
-import { ErrorCallout } from "@/components/ErrorCallout";
-import BulkAdd, { EmailInviteStatus } from "@/components/admin/users/BulkAdd";
-import Text from "@/refresh-components/texts/Text";
-import { InvitedUserSnapshot } from "@/lib/types";
-import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
-import PendingUsersTable from "@/components/admin/users/PendingUsersTable";
-import CreateButton from "@/refresh-components/buttons/CreateButton";
-import { Button } from "@opal/components";
-import { Disabled } from "@opal/core";
-import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
-import { Spinner } from "@/components/Spinner";
-import { SvgDownloadCloud, SvgUserPlus } from "@opal/icons";
-import { ADMIN_ROUTE_CONFIG, ADMIN_PATHS } from "@/lib/admin-routes";
-
-const route = ADMIN_ROUTE_CONFIG[ADMIN_PATHS.USERS]!;
-
-interface CountDisplayProps {
-  label: string;
-  value: number | null;
-  isLoading: boolean;
-}
-
-function CountDisplay({ label, value, isLoading }: CountDisplayProps) {
-  const displayValue = isLoading
-    ? "..."
-    : value === null
-      ? "-"
-      : value.toLocaleString();
-
-  return (
-    <div className="flex items-center gap-1 px-1 py-0.5 rounded-06">
-      <Text as="p" mainUiMuted text03>
-        {label}
-      </Text>
-      <Text as="p" headingH3 text05>
-        {displayValue}
-      </Text>
-    </div>
-  );
-}
-
-function UsersTables({
-  q,
-  isDownloadingUsers,
-  setIsDownloadingUsers,
-}: {
-  q: string;
-  isDownloadingUsers: boolean;
-  setIsDownloadingUsers: (loading: boolean) => void;
-}) {
-  const [currentUsersCount, setCurrentUsersCount] = useState<number | null>(
-    null
-  );
-  const [currentUsersLoading, setCurrentUsersLoading] = useState<boolean>(true);
-
-  const downloadAllUsers = async () => {
-    setIsDownloadingUsers(true);
-    const startTime = Date.now();
-    const minDurationMsForSpinner = 1000;
-    try {
-      const response = await fetch("/api/manage/users/download");
-      if (!response.ok) {
-        throw new Error("Failed to download all users");
-      }
-      const blob = await response.blob();
-      const url = window.URL.createObjectURL(blob);
-      const anchor_tag = document.createElement("a");
-      anchor_tag.href = url;
-      anchor_tag.download = "users.csv";
-      document.body.appendChild(anchor_tag);
-      anchor_tag.click();
-      //Clean up URL after download to avoid memory leaks
-      window.URL.revokeObjectURL(url);
-      document.body.removeChild(anchor_tag);
-    } catch (error) {
-      toast.error(`Failed to download all users - ${error}`);
-    } finally {
-      //Ensure spinner is visible for at least 1 second
-      //This is to avoid the spinner disappearing too quickly
-      const endTime = Date.now();
-      const duration = endTime - startTime;
-      await new Promise((resolve) =>
-        setTimeout(resolve, minDurationMsForSpinner - duration)
-      );
-      setIsDownloadingUsers(false);
-    }
-  };
-
-  const {
-    data: invitedUsers,
-    error: invitedUsersError,
-    isLoading: invitedUsersLoading,
-    mutate: invitedUsersMutate,
-  } = useSWR<InvitedUserSnapshot[]>(
-    "/api/manage/users/invited",
-    errorHandlingFetcher
-  );
-
-  const { data: validDomains, error: domainsError } = useSWR<string[]>(
-    "/api/manage/admin/valid-domains",
-    errorHandlingFetcher
-  );
-
-  const {
-    data: pendingUsers,
-    error: pendingUsersError,
-    isLoading: pendingUsersLoading,
-    mutate: pendingUsersMutate,
-  } = useSWR<InvitedUserSnapshot[]>(
-    NEXT_PUBLIC_CLOUD_ENABLED ? "/api/tenants/users/pending" : null,
-    errorHandlingFetcher
-  );
-
-  const invitedUsersCount =
-    invitedUsers === undefined ? null : invitedUsers.length;
-  const pendingUsersCount =
-    pendingUsers === undefined ? null : pendingUsers.length;
-  // Show loading animation only during the initial data fetch
-  if (!validDomains) {
-    return <ThreeDotsLoader />;
-  }
-
-  if (domainsError) {
-    return (
-      <ErrorCallout
-        errorTitle="Error loading valid domains"
-        errorMsg={domainsError?.info?.detail}
-      />
-    );
-  }
-
-  const tabs = SimpleTabs.generateTabs({
-    current: {
-      name: "Current Users",
-      content: (
-        <Card className="w-full">
-          <CardHeader>
-            <div className="flex justify-between items-center gap-1">
-              <CardTitle>Current Users</CardTitle>
-              <Disabled disabled={isDownloadingUsers}>
-                <Button
-                  icon={SvgDownloadCloud}
-                  onClick={() => downloadAllUsers()}
-                >
-                  {isDownloadingUsers ? "Downloading..." : "Download CSV"}
-                </Button>
-              </Disabled>
-            </div>
-          </CardHeader>
-          <CardContent>
-            <SignedUpUserTable
-              invitedUsers={invitedUsers || []}
-              q={q}
-              invitedUsersMutate={invitedUsersMutate}
-              countDisplay={
-                <CountDisplay
-                  label="Total users"
-                  value={currentUsersCount}
-                  isLoading={currentUsersLoading}
-                />
-              }
-              onTotalItemsChange={(count) => setCurrentUsersCount(count)}
-              onLoadingChange={(loading) => {
-                setCurrentUsersLoading(loading);
-                if (loading) {
-                  setCurrentUsersCount(null);
-                }
-              }}
-            />
-          </CardContent>
-        </Card>
-      ),
-    },
-    invited: {
-      name: "Invited Users",
-      content: (
-        <Card className="w-full">
-          <CardHeader>
-            <div className="flex justify-between items-center gap-1">
-              <CardTitle>Invited Users</CardTitle>
-              <CountDisplay
-                label="Total invited"
-                value={invitedUsersCount}
-                isLoading={invitedUsersLoading}
-              />
-            </div>
-          </CardHeader>
-          <CardContent>
-            <InvitedUserTable
-              users={invitedUsers || []}
-              mutate={invitedUsersMutate}
-              error={invitedUsersError}
-              isLoading={invitedUsersLoading}
-              q={q}
-            />
-          </CardContent>
-        </Card>
-      ),
-    },
-    ...(NEXT_PUBLIC_CLOUD_ENABLED && {
-      pending: {
-        name: "Pending Users",
-        content: (
-          <Card>
-            <CardHeader>
-              <div className="flex justify-between items-center gap-1">
-                <CardTitle>Pending Users</CardTitle>
-                <CountDisplay
-                  label="Total pending"
-                  value={pendingUsersCount}
-                  isLoading={pendingUsersLoading}
-                />
-              </div>
-            </CardHeader>
-            <CardContent>
-              <PendingUsersTable
-                users={pendingUsers || []}
-                mutate={pendingUsersMutate}
-                error={pendingUsersError}
-                isLoading={pendingUsersLoading}
-                q={q}
-              />
-            </CardContent>
-          </Card>
-        ),
-      },
-    }),
-  });
-
-  return <SimpleTabs tabs={tabs} defaultValue="current" />;
-}
-
-function SearchableTables() {
-  const [query, setQuery] = useState("");
-  const [isDownloadingUsers, setIsDownloadingUsers] = useState(false);
-
-  return (
-    <div>
-      {isDownloadingUsers && <Spinner />}
-      <div className="flex flex-col gap-y-4">
-        <div className="flex flex-row items-center gap-2">
-          <InputTypeIn
-            placeholder="Search"
-            value={query}
-            onChange={(event) => setQuery(event.target.value)}
-          />
-          <AddUserButton />
-        </div>
-        <UsersTables
-          q={query}
-          isDownloadingUsers={isDownloadingUsers}
-          setIsDownloadingUsers={setIsDownloadingUsers}
-        />
-      </div>
-    </div>
-  );
-}
-
-function AddUserButton() {
-  const [bulkAddUsersModal, setBulkAddUsersModal] = useState(false);
-
-  const onSuccess = (emailInviteStatus: EmailInviteStatus) => {
-    mutate(
-      (key) => typeof key === "string" && key.startsWith("/api/manage/users")
-    );
-    setBulkAddUsersModal(false);
-    if (emailInviteStatus === "NOT_CONFIGURED") {
-      toast.warning(
-        "Users added, but no email notification was sent. There is no SMTP server set up for email sending."
-      );
-    } else if (emailInviteStatus === "SEND_FAILED") {
-      toast.warning(
-        "Users added, but email sending failed. Check your SMTP configuration and try again."
-      );
-    } else {
-      toast.success("Users invited!");
-    }
-  };
-
-  const onFailure = async (res: Response) => {
-    const error = (await res.json()).detail;
-    toast.error(`Failed to invite users - ${error}`);
-  };
-
-  const handleInviteClick = () => {
-    setBulkAddUsersModal(true);
-  };
-
-  return (
-    <>
-      <CreateButton primary onClick={handleInviteClick}>
-        Invite Users
-      </CreateButton>
-
-      {bulkAddUsersModal && (
-        <Modal open onOpenChange={() => setBulkAddUsersModal(false)}>
-          <Modal.Content>
-            <Modal.Header
-              icon={SvgUserPlus}
-              title="Bulk Add Users"
-              onClose={() => setBulkAddUsersModal(false)}
-            />
-            <Modal.Body>
-              <div className="flex flex-col gap-2">
-                <Text as="p">
-                  Add the email addresses to import, separated by whitespaces.
-                  Invited users will be able to login to this domain with their
-                  email address.
-                </Text>
-                <BulkAdd onSuccess={onSuccess} onFailure={onFailure} />
-              </div>
-            </Modal.Body>
-          </Modal.Content>
-        </Modal>
-      )}
-    </>
-  );
-}
-
-export default function Page() {
-  return (
-    <SettingsLayouts.Root>
-      <SettingsLayouts.Header title={route.title} icon={route.icon} separator />
-      <SettingsLayouts.Body>
-        <SearchableTables />
-      </SettingsLayouts.Body>
-    </SettingsLayouts.Root>
-  );
-}
+export { default } from "@/refresh-pages/admin/UsersPage";
diff --git a/web/src/app/admin/users2/page.tsx b/web/src/app/admin/users2/page.tsx
deleted file mode 100644
index 1988d3c47c1..00000000000
--- a/web/src/app/admin/users2/page.tsx
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from "@/refresh-pages/admin/UsersPage";
diff --git a/web/src/components/admin/ClientLayout.tsx b/web/src/components/admin/ClientLayout.tsx
index 06e3e8a0337..028f11806c4 100644
--- a/web/src/components/admin/ClientLayout.tsx
+++ b/web/src/components/admin/ClientLayout.tsx
@@ -31,7 +31,6 @@ const SETTINGS_LAYOUT_PREFIXES = [
   ADMIN_PATHS.LLM_MODELS,
   ADMIN_PATHS.AGENTS,
   ADMIN_PATHS.USERS,
-  ADMIN_PATHS.USERS_V2,
   ADMIN_PATHS.TOKEN_RATE_LIMITS,
   ADMIN_PATHS.SEARCH_SETTINGS,
   ADMIN_PATHS.DOCUMENT_PROCESSING,
diff --git a/web/src/lib/admin-routes.ts b/web/src/lib/admin-routes.ts
index 20514f43ff6..4928212cf03 100644
--- a/web/src/lib/admin-routes.ts
+++ b/web/src/lib/admin-routes.ts
@@ -58,7 +58,6 @@ export const ADMIN_PATHS = {
   DOCUMENT_PROCESSING: "/admin/configuration/document-processing",
   KNOWLEDGE_GRAPH: "/admin/kg",
   USERS: "/admin/users",
-  USERS_V2: "/admin/users2",
   API_KEYS: "/admin/api-key",
   TOKEN_RATE_LIMITS: "/admin/token-rate-limits",
   USAGE: "/admin/performance/usage",
@@ -187,14 +186,9 @@ export const ADMIN_ROUTE_CONFIG: Record<string, AdminRouteConfig> = {
     sidebarLabel: "Knowledge Graph",
   },
   [ADMIN_PATHS.USERS]: {
-    icon: SvgUser,
-    title: "Manage Users",
-    sidebarLabel: "Users",
-  },
-  [ADMIN_PATHS.USERS_V2]: {
     icon: SvgUser,
     title: "Users & Requests",
-    sidebarLabel: "Users v2",
+    sidebarLabel: "Users",
   },
   [ADMIN_PATHS.API_KEYS]: {
     icon: SvgKey,
diff --git a/web/src/refresh-components/table/DataTable.tsx b/web/src/refresh-components/table/DataTable.tsx
index 3eb427450e0..a0520aaa817 100644
--- a/web/src/refresh-components/table/DataTable.tsx
+++ b/web/src/refresh-components/table/DataTable.tsx
@@ -133,6 +133,7 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
     height,
     headerBackground,
     serverSide,
+    emptyState,
   } = props;
 
   const effectivePageSize = pageSize ?? (footer ? 10 : data.length);
@@ -447,6 +448,13 @@ export default function DataTable<TData>(props: DataTableProps<TData>) {
                   : undefined
               }
             >
+              {emptyState && table.getRowModel().rows.length === 0 && (
+                <tr>
+                  <td colSpan={table.getVisibleLeafColumns().length}>
+                    {emptyState}
+                  </td>
+                </tr>
+              )}
               {table.getRowModel().rows.map((row) => {
                 const rowId = hasDraggable ? getRowId(row.original) : undefined;
 
diff --git a/web/src/refresh-components/table/types.ts b/web/src/refresh-components/table/types.ts
index c068cd0cf80..9e7ce7efad0 100644
--- a/web/src/refresh-components/table/types.ts
+++ b/web/src/refresh-components/table/types.ts
@@ -192,4 +192,6 @@ export interface DataTableProps<TData> {
    * - Fires separate callbacks for sorting, pagination, and search changes
    */
   serverSide?: ServerSideConfig;
+  /** Content to render inside the table body when there are no rows. */
+  emptyState?: React.ReactNode;
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx b/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx
index f75b4e1bfc5..88c37e1bded 100644
--- a/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/GroupsCell.tsx
@@ -84,36 +84,25 @@ export default function GroupsCell({
     computeVisibleCount();
   }, [visibleCount, computeVisibleCount]);
 
-  // Re-measure on container resize.
-  // The ref moves between DOM elements depending on overflow state, so we
-  // track the observed node and re-attach when it changes.
-  const observedNodeRef = useRef<HTMLElement | null>(null);
-  const observerRef = useRef<ResizeObserver | null>(null);
+  // Re-measure when the container width changes (e.g. window resize).
+  // Track width so height-only changes (from the measurement cycle toggling
+  // visible tags) don't cause an infinite render loop.
+  const lastWidthRef = useRef(0);
 
   useEffect(() => {
-    if (!observerRef.current) {
-      observerRef.current = new ResizeObserver(() => {
-        setVisibleCount(null);
-      });
-    }
-    const observer = observerRef.current;
     const node = containerRef.current;
+    if (!node) return;
 
-    if (node !== observedNodeRef.current) {
-      if (observedNodeRef.current) {
-        observer.unobserve(observedNodeRef.current);
-      }
-      if (node) {
-        observer.observe(node);
-      }
-      observedNodeRef.current = node;
-    }
+    const observer = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? 0;
+      if (Math.abs(width - lastWidthRef.current) < 1) return;
+      lastWidthRef.current = width;
+      setVisibleCount(null);
+    });
+    observer.observe(node);
 
-    return () => {
-      observer.disconnect();
-      observedNodeRef.current = null;
-    };
-  });
+    return () => observer.disconnect();
+  }, [groups]);
 
   const isMeasuring = visibleCount === null;
   const effectiveVisible = visibleCount ?? groups.length;
@@ -162,12 +151,13 @@ export default function GroupsCell({
               —
             </Text>
           </div>
-        ) : hasOverflow ? (
+        ) : (
           <SimpleTooltip
             side="bottom"
             align="start"
             tooltip={allGroupsTooltip}
-            className="bg-background-neutral-01 border border-border-01 shadow-sm"
+            disabled={!hasOverflow}
+            className="bg-background-neutral-01 shadow-sm"
             delayDuration={200}
           >
             <div
@@ -177,13 +167,6 @@ export default function GroupsCell({
               {tagsContent}
             </div>
           </SimpleTooltip>
-        ) : (
-          <div
-            ref={containerRef}
-            className="flex items-center gap-1 overflow-hidden flex-nowrap min-w-0 pr-7"
-          >
-            {tagsContent}
-          </div>
         )}
         {user.id && (
           <IconButton
diff --git a/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx b/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx
index 77607a823a8..9c5f46a5201 100644
--- a/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UserRoleCell.tsx
@@ -90,44 +90,46 @@ export default function UserRoleCell({ user, onMutate }: UserRoleCellProps) {
   const currentIcon = ROLE_ICONS[user.role] ?? SvgUser;
 
   return (
-    <Disabled disabled={isUpdating}>
-      <Popover open={open} onOpenChange={setOpen}>
-        <Popover.Trigger asChild>
-          <OpenButton
-            icon={currentIcon}
-            variant="select-tinted"
-            width="full"
-            justifyContent="between"
-          >
-            {USER_ROLE_LABELS[user.role]}
-          </OpenButton>
-        </Popover.Trigger>
-        <Popover.Content align="start">
-          <div className="flex flex-col gap-1 p-1 min-w-[160px]">
-            {SELECTABLE_ROLES.map((role) => {
-              if (
-                role === UserRole.GLOBAL_CURATOR &&
-                !isPaidEnterpriseFeaturesEnabled
-              ) {
-                return null;
-              }
-              const isSelected = user.role === role;
-              const icon = ROLE_ICONS[role] ?? SvgUser;
-              return (
-                <LineItem
-                  key={role}
-                  icon={isSelected ? SvgCheck : icon}
-                  selected={isSelected}
-                  emphasized={isSelected}
-                  onClick={() => handleSelect(role)}
-                >
-                  {USER_ROLE_LABELS[role]}
-                </LineItem>
-              );
-            })}
-          </div>
-        </Popover.Content>
-      </Popover>
-    </Disabled>
+    <div className="[&_button]:rounded-08">
+      <Disabled disabled={isUpdating}>
+        <Popover open={open} onOpenChange={setOpen}>
+          <Popover.Trigger asChild>
+            <OpenButton
+              icon={currentIcon}
+              variant="select-tinted"
+              width="full"
+              justifyContent="between"
+            >
+              {USER_ROLE_LABELS[user.role]}
+            </OpenButton>
+          </Popover.Trigger>
+          <Popover.Content align="start">
+            <div className="flex flex-col gap-1 p-1 min-w-[160px]">
+              {SELECTABLE_ROLES.map((role) => {
+                if (
+                  role === UserRole.GLOBAL_CURATOR &&
+                  !isPaidEnterpriseFeaturesEnabled
+                ) {
+                  return null;
+                }
+                const isSelected = user.role === role;
+                const icon = ROLE_ICONS[role] ?? SvgUser;
+                return (
+                  <LineItem
+                    key={role}
+                    icon={isSelected ? SvgCheck : icon}
+                    selected={isSelected}
+                    emphasized={isSelected}
+                    onClick={() => handleSelect(role)}
+                  >
+                    {USER_ROLE_LABELS[role]}
+                  </LineItem>
+                );
+              })}
+            </div>
+          </Popover.Content>
+        </Popover>
+      </Disabled>
+    </div>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
index 3f816eb6600..8a64dfb3106 100644
--- a/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
+++ b/web/src/refresh-pages/admin/UsersPage/UsersTable.tsx
@@ -13,8 +13,10 @@ import { UserRole, UserStatus, USER_STATUS_LABELS } from "@/lib/types";
 import { timeAgo } from "@/lib/time";
 import Text from "@/refresh-components/texts/Text";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import { toast } from "@/hooks/useToast";
 import useAdminUsers from "@/hooks/useAdminUsers";
 import useGroups from "@/hooks/useGroups";
+import { downloadUsersCsv } from "./svc";
 import UserFilters from "./UserFilters";
 import GroupsCell from "./GroupsCell";
 import UserRowActions from "./UserRowActions";
@@ -60,7 +62,7 @@ function renderStatusColumn(value: UserStatus, row: UserRow) {
 function renderLastUpdatedColumn(value: string | null) {
   return (
     <Text as="span" secondaryBody text03>
-      {timeAgo(value) ?? "\u2014"}
+      {value ? timeAgo(value) ?? "\u2014" : "\u2014"}
     </Text>
   );
 }
@@ -214,35 +216,40 @@ export default function UsersTable({
         roleCounts={roleCounts}
         statusCounts={statusCounts}
       />
-      {filteredUsers.length === 0 ? (
-        <IllustrationContent
-          illustration={SvgNoResult}
-          title="No users found"
-          description="No users match the current filters."
-        />
-      ) : (
-        <DataTable
-          data={filteredUsers}
-          columns={columns}
-          getRowId={(row) => row.id ?? row.email}
-          pageSize={PAGE_SIZE}
-          searchTerm={searchTerm}
-          footer={{
-            mode: "summary",
-            leftExtra: (
-              <Button
-                icon={SvgDownload}
-                prominence="tertiary"
-                size="sm"
-                tooltip="Download CSV"
-                onClick={() => {
-                  window.open("/api/manage/users/download", "_blank");
-                }}
-              />
-            ),
-          }}
-        />
-      )}
+      <DataTable
+        data={filteredUsers}
+        columns={columns}
+        getRowId={(row) => row.id ?? row.email}
+        pageSize={PAGE_SIZE}
+        searchTerm={searchTerm}
+        emptyState={
+          <IllustrationContent
+            illustration={SvgNoResult}
+            title="No users found"
+            description="No users match the current filters."
+          />
+        }
+        footer={{
+          mode: "summary",
+          leftExtra: (
+            <Button
+              icon={SvgDownload}
+              prominence="tertiary"
+              size="sm"
+              tooltip="Download CSV"
+              onClick={() => {
+                downloadUsersCsv().catch((err) => {
+                  toast.error(
+                    err instanceof Error
+                      ? err.message
+                      : "Failed to download CSV"
+                  );
+                });
+              }}
+            />
+          ),
+        }}
+      />
     </div>
   );
 }
diff --git a/web/src/refresh-pages/admin/UsersPage/svc.ts b/web/src/refresh-pages/admin/UsersPage/svc.ts
index fc452824b63..8251cec54cc 100644
--- a/web/src/refresh-pages/admin/UsersPage/svc.ts
+++ b/web/src/refresh-pages/admin/UsersPage/svc.ts
@@ -126,3 +126,20 @@ export async function inviteUsers(emails: string[]): Promise<void> {
     throw new Error(await parseErrorDetail(res, "Failed to invite users"));
   }
 }
+
+export async function downloadUsersCsv(): Promise<void> {
+  const res = await fetch("/api/manage/users/download");
+  if (!res.ok) {
+    throw new Error(
+      await parseErrorDetail(res, "Failed to download users CSV")
+    );
+  }
+  const blob = await res.blob();
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  a.download = `onyx_users_${ts}.csv`;
+  a.click();
+  URL.revokeObjectURL(url);
+}
diff --git a/web/src/sections/sidebar/AdminSidebar.tsx b/web/src/sections/sidebar/AdminSidebar.tsx
index 078ba14028f..6bb43d2774f 100644
--- a/web/src/sections/sidebar/AdminSidebar.tsx
+++ b/web/src/sections/sidebar/AdminSidebar.tsx
@@ -121,7 +121,6 @@ const collections = (
           {
             name: "User Management",
             items: [
-              sidebarItem(ADMIN_PATHS.USERS),
               ...(enableEnterprise ? [sidebarItem(ADMIN_PATHS.GROUPS)] : []),
               sidebarItem(ADMIN_PATHS.API_KEYS),
               sidebarItem(ADMIN_PATHS.TOKEN_RATE_LIMITS),
@@ -130,8 +129,7 @@ const collections = (
           {
             name: "Permissions",
             items: [
-              // TODO (nikolas): Uncommented in switchover PR once Users v2 is ready
-              // sidebarItem(ADMIN_PATHS.USERS_V2),
+              sidebarItem(ADMIN_PATHS.USERS),
               ...(enableEnterprise ? [sidebarItem(ADMIN_PATHS.SCIM)] : []),
             ],
           },