pr comments

backend/onyx/configs/app_configs.py

@@ -286,9 +286,11 @@ USING_AWS_MANAGED_OPENSEARCH = (
     os.environ.get("USING_AWS_MANAGED_OPENSEARCH", "").lower() == "true"
 )
 # Profiling adds some overhead to OpenSearch operations. This overhead is
-# unknown right now. Defaults to True.
+# unknown right now. It is enabled by default so we can get useful logs for
+# investigating slow queries. We may never disable it if the overhead is
+# minimal.
 OPENSEARCH_PROFILING_DISABLED = (
-    os.environ.get("OPENSEARCH_PROFILING_DISABLED", "true").lower() == "true"
+    os.environ.get("OPENSEARCH_PROFILING_DISABLED", "").lower() == "true"
 )
 # Whether to disable match highlights for OpenSearch. Defaults to True for now
 # as we investigate query performance.
@@ -940,20 +942,9 @@ CUSTOM_ANSWER_VALIDITY_CONDITIONS = json.loads(
 )
 
 VESPA_REQUEST_TIMEOUT = int(os.environ.get("VESPA_REQUEST_TIMEOUT") or "15")
-# This is the timeout for the client side of the Vespa migration task. When
-# exceeded, an exception is raised in our code. This value should be higher than
-# VESPA_MIGRATION_SERVER_SIDE_REQUEST_TIMEOUT.
 VESPA_MIGRATION_REQUEST_TIMEOUT_S = int(
     os.environ.get("VESPA_MIGRATION_REQUEST_TIMEOUT_S") or "120"
 )
-# This is the timeout Vespa uses on the server side to know when to wrap up its
-# traversal and try to report partial results. This differs from the client
-# timeout above which raises an exception in our code when exceeded. This
-# timeout allows Vespa to return gracefully. This value should be lower than
-# VESPA_MIGRATION_REQUEST_TIMEOUT_S. Formatted as <number of seconds>s.
-VESPA_MIGRATION_SERVER_SIDE_REQUEST_TIMEOUT = os.environ.get(
-    "VESPA_MIGRATION_SERVER_SIDE_REQUEST_TIMEOUT", "110s"
-)
 
 SYSTEM_RECURSION_LIMIT = int(os.environ.get("SYSTEM_RECURSION_LIMIT") or "1000")
 

backend/onyx/connectors/google_drive/connector.py

@@ -42,6 +42,9 @@ from onyx.connectors.google_drive.file_retrieval import (
     get_all_files_in_my_drive_and_shared,
 )
 from onyx.connectors.google_drive.file_retrieval import get_external_access_for_folder
+from onyx.connectors.google_drive.file_retrieval import (
+    get_files_by_web_view_links_batch,
+)
 from onyx.connectors.google_drive.file_retrieval import get_files_in_shared_drive
 from onyx.connectors.google_drive.file_retrieval import get_folder_metadata
 from onyx.connectors.google_drive.file_retrieval import get_root_folder_id
@@ -70,11 +73,13 @@ from onyx.connectors.interfaces import CheckpointedConnectorWithPermSync
 from onyx.connectors.interfaces import CheckpointOutput
 from onyx.connectors.interfaces import GenerateSlimDocumentOutput
 from onyx.connectors.interfaces import NormalizationResult
+from onyx.connectors.interfaces import Resolver
 from onyx.connectors.interfaces import SecondsSinceUnixEpoch
 from onyx.connectors.interfaces import SlimConnectorWithPermSync
 from onyx.connectors.models import ConnectorFailure
 from onyx.connectors.models import ConnectorMissingCredentialError
 from onyx.connectors.models import Document
+from onyx.connectors.models import DocumentFailure
 from onyx.connectors.models import EntityFailure
 from onyx.connectors.models import HierarchyNode
 from onyx.connectors.models import SlimDocument
@@ -202,7 +207,9 @@ class DriveIdStatus(Enum):
 
 
 class GoogleDriveConnector(
-    SlimConnectorWithPermSync, CheckpointedConnectorWithPermSync[GoogleDriveCheckpoint]
+    SlimConnectorWithPermSync,
+    CheckpointedConnectorWithPermSync[GoogleDriveCheckpoint],
+    Resolver,
 ):
     def __init__(
         self,
@@ -1665,6 +1672,82 @@ class GoogleDriveConnector(
             start, end, checkpoint, include_permissions=True
         )
 
+    @override
+    def resolve_errors(
+        self,
+        errors: list[ConnectorFailure],
+        include_permissions: bool = False,
+    ) -> Generator[Document | ConnectorFailure | HierarchyNode, None, None]:
+        if self._creds is None or self._primary_admin_email is None:
+            raise RuntimeError(
+                "Credentials missing, should not call this method before calling load_credentials"
+            )
+
+        logger.info(f"Resolving {len(errors)} errors")
+        doc_ids = [
+            failure.failed_document.document_id
+            for failure in errors
+            if failure.failed_document
+        ]
+        service = get_drive_service(self.creds, self.primary_admin_email)
+        field_type = (
+            DriveFileFieldType.WITH_PERMISSIONS
+            if include_permissions or self.exclude_domain_link_only
+            else DriveFileFieldType.STANDARD
+        )
+        batch_result = get_files_by_web_view_links_batch(service, doc_ids, field_type)
+
+        for doc_id, error in batch_result.errors.items():
+            yield ConnectorFailure(
+                failed_document=DocumentFailure(
+                    document_id=doc_id,
+                    document_link=doc_id,
+                ),
+                failure_message=f"Failed to retrieve file during error resolution: {error}",
+                exception=error,
+            )
+
+        permission_sync_context = (
+            PermissionSyncContext(
+                primary_admin_email=self.primary_admin_email,
+                google_domain=self.google_domain,
+            )
+            if include_permissions
+            else None
+        )
+
+        retrieved_files = [
+            RetrievedDriveFile(
+                drive_file=file,
+                user_email=self.primary_admin_email,
+                completion_stage=DriveRetrievalStage.DONE,
+            )
+            for file in batch_result.files.values()
+        ]
+
+        yield from self._get_new_ancestors_for_files(
+            files=retrieved_files,
+            seen_hierarchy_node_raw_ids=ThreadSafeSet(),
+            fully_walked_hierarchy_node_raw_ids=ThreadSafeSet(),
+            permission_sync_context=permission_sync_context,
+            add_prefix=True,
+        )
+
+        func_with_args = [
+            (
+                self._convert_retrieved_file_to_document,
+                (rf, permission_sync_context),
+            )
+            for rf in retrieved_files
+        ]
+        results = cast(
+            list[Document | ConnectorFailure | None],
+            run_functions_tuples_in_parallel(func_with_args, max_workers=8),
+        )
+        for result in results:
+            if result is not None:
+                yield result
+
     def _extract_slim_docs_from_google_drive(
         self,
         checkpoint: GoogleDriveCheckpoint,

backend/onyx/connectors/google_drive/file_retrieval.py

@@ -9,6 +9,7 @@ from urllib.parse import urlparse
 
 from googleapiclient.discovery import Resource  # type: ignore
 from googleapiclient.errors import HttpError  # type: ignore
+from googleapiclient.http import BatchHttpRequest  # type: ignore
 
 from onyx.access.models import ExternalAccess
 from onyx.connectors.google_drive.constants import DRIVE_FOLDER_TYPE
@@ -60,6 +61,8 @@ SLIM_FILE_FIELDS = (
 )
 FOLDER_FIELDS = "nextPageToken, files(id, name, permissions, modifiedTime, webViewLink, shortcutDetails)"
 
+MAX_BATCH_SIZE = 100
+
 HIERARCHY_FIELDS = "id, name, parents, webViewLink, mimeType, driveId"
 
 HIERARCHY_FIELDS_WITH_PERMISSIONS = (
@@ -216,7 +219,7 @@ def get_external_access_for_folder(
 
 
 def _get_fields_for_file_type(field_type: DriveFileFieldType) -> str:
-    """Get the appropriate fields string based on the field type enum"""
+    """Get the appropriate fields string for files().list() based on the field type enum."""
     if field_type == DriveFileFieldType.SLIM:
         return SLIM_FILE_FIELDS
     elif field_type == DriveFileFieldType.WITH_PERMISSIONS:
@@ -225,6 +228,25 @@ def _get_fields_for_file_type(field_type: DriveFileFieldType) -> str:
         return FILE_FIELDS
 
 
+def _extract_single_file_fields(list_fields: str) -> str:
+    """Convert a files().list() fields string to one suitable for files().get().
+
+    List fields look like "nextPageToken, files(field1, field2, ...)"
+    Single-file fields should be just "field1, field2, ..."
+    """
+    start = list_fields.find("files(")
+    if start == -1:
+        return list_fields
+    inner_start = start + len("files(")
+    inner_end = list_fields.rfind(")")
+    return list_fields[inner_start:inner_end]
+
+
+def _get_single_file_fields(field_type: DriveFileFieldType) -> str:
+    """Get the appropriate fields string for files().get() based on the field type enum."""
+    return _extract_single_file_fields(_get_fields_for_file_type(field_type))
+
+
 def _get_files_in_parent(
     service: Resource,
     parent_id: str,
@@ -536,3 +558,74 @@ def get_file_by_web_view_link(
         )
         .execute()
     )
+
+
+class BatchRetrievalResult:
+    """Result of a batch file retrieval, separating successes from errors."""
+
+    def __init__(self) -> None:
+        self.files: dict[str, GoogleDriveFileType] = {}
+        self.errors: dict[str, Exception] = {}
+
+
+def get_files_by_web_view_links_batch(
+    service: GoogleDriveService,
+    web_view_links: list[str],
+    field_type: DriveFileFieldType,
+) -> BatchRetrievalResult:
+    """Retrieve multiple Google Drive files by webViewLink using the batch API.
+
+    Returns a BatchRetrievalResult containing successful file retrievals
+    and errors for any files that could not be fetched.
+    Automatically splits into chunks of MAX_BATCH_SIZE.
+    """
+    fields = _get_single_file_fields(field_type)
+    if len(web_view_links) <= MAX_BATCH_SIZE:
+        return _get_files_by_web_view_links_batch(service, web_view_links, fields)
+
+    combined = BatchRetrievalResult()
+    for i in range(0, len(web_view_links), MAX_BATCH_SIZE):
+        chunk = web_view_links[i : i + MAX_BATCH_SIZE]
+        chunk_result = _get_files_by_web_view_links_batch(service, chunk, fields)
+        combined.files.update(chunk_result.files)
+        combined.errors.update(chunk_result.errors)
+    return combined
+
+
+def _get_files_by_web_view_links_batch(
+    service: GoogleDriveService,
+    web_view_links: list[str],
+    fields: str,
+) -> BatchRetrievalResult:
+    """Single-batch implementation."""
+
+    result = BatchRetrievalResult()
+
+    def callback(
+        request_id: str,
+        response: GoogleDriveFileType,
+        exception: Exception | None,
+    ) -> None:
+        if exception:
+            logger.warning(f"Error retrieving file {request_id}: {exception}")
+            result.errors[request_id] = exception
+        else:
+            result.files[request_id] = response
+
+    batch = cast(BatchHttpRequest, service.new_batch_http_request(callback=callback))
+
+    for web_view_link in web_view_links:
+        try:
+            file_id = _extract_file_id_from_web_view_link(web_view_link)
+            request = service.files().get(
+                fileId=file_id,
+                supportsAllDrives=True,
+                fields=fields,
+            )
+            batch.add(request, request_id=web_view_link)
+        except ValueError as e:
+            logger.warning(f"Failed to extract file ID from {web_view_link}: {e}")
+            result.errors[web_view_link] = e
+
+    batch.execute()
+    return result

backend/onyx/connectors/interfaces.py

@@ -298,6 +298,22 @@ class CheckpointedConnectorWithPermSync(CheckpointedConnector[CT]):
         raise NotImplementedError
 
 
+class Resolver(BaseConnector):
+    @abc.abstractmethod
+    def resolve_errors(
+        self,
+        errors: list[ConnectorFailure],
+        include_permissions: bool = False,
+    ) -> Generator[Document | ConnectorFailure | HierarchyNode, None, None]:
+        """Attempts to yield back ALL the documents described by the errors, no checkpointing.
+
+        Caller's responsibility is to delete the old ConnectorFailures and replace with the new ones.
+        If include_permissions is True, the documents will have permissions synced.
+        May also yield HierarchyNode objects for ancestor folders of resolved documents.
+        """
+        raise NotImplementedError
+
+
 class HierarchyConnector(BaseConnector):
     @abc.abstractmethod
     def load_hierarchy(

backend/onyx/db/api_key.py

@@ -4,6 +4,7 @@ from fastapi_users.password import PasswordHelper
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import joinedload
+from sqlalchemy.orm import selectinload
 from sqlalchemy.orm import Session
 
 from onyx.auth.api_key import ApiKeyDescriptor
@@ -54,6 +55,7 @@ async def fetch_user_for_api_key(
         select(User)
         .join(ApiKey, ApiKey.user_id == User.id)
         .where(ApiKey.hashed_api_key == hashed_api_key)
+        .options(selectinload(User.memories))
     )
 
 

backend/onyx/db/auth.py

@@ -13,6 +13,7 @@ from sqlalchemy import func
 from sqlalchemy import Select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
+from sqlalchemy.orm import selectinload
 from sqlalchemy.orm import Session
 
 from onyx.auth.schemas import UserRole
@@ -97,6 +98,11 @@ async def get_user_count(only_admin_users: bool = False) -> int:
 
 # Need to override this because FastAPI Users doesn't give flexibility for backend field creation logic in OAuth flow
 class SQLAlchemyUserAdminDB(SQLAlchemyUserDatabase[UP, ID]):
+    async def _get_user(self, statement: Select) -> UP | None:
+        statement = statement.options(selectinload(User.memories))
+        results = await self.session.execute(statement)
+        return results.unique().scalar_one_or_none()
+
     async def create(
         self,
         create_dict: Dict[str, Any],

backend/onyx/db/pat.py

@@ -8,6 +8,7 @@ from uuid import UUID
 from sqlalchemy import select
 from sqlalchemy import update
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
 from sqlalchemy.orm import Session
 
 from onyx.auth.pat import build_displayable_pat
@@ -46,6 +47,7 @@ async def fetch_user_for_pat(
             (PersonalAccessToken.expires_at.is_(None))
             | (PersonalAccessToken.expires_at > now)
         )
+        .options(selectinload(User.memories))
     )
     if not user:
         return None

backend/onyx/db/user_preferences.py

@@ -229,9 +229,7 @@ def get_memories_for_user(
     user_id: UUID,
     db_session: Session,
 ) -> Sequence[Memory]:
-    return db_session.scalars(
-        select(Memory).where(Memory.user_id == user_id).order_by(Memory.id.desc())
-    ).all()
+    return db_session.scalars(select(Memory).where(Memory.user_id == user_id)).all()
 
 
 def update_user_pinned_assistants(

backend/onyx/document_index/opensearch/constants.py

@@ -37,10 +37,10 @@ M = 32  # Set relatively high for better accuracy.
 # 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).
-# Defaults to 500 for now. Initially this defaulted to 750 but we were seeing
-# poor search performance; bumped from 100 to 500 to improve recall.
+# Defaults to 100 for now. Initially this defaulted to 750 but we were seeing
+# poor search performance.
 DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES = int(
-    os.environ.get("DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES", 500)
+    os.environ.get("DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES", 100)
 )
 
 # Number of vectors to examine to decide the top k neighbors for the HNSW

backend/onyx/document_index/vespa/chunk_retrieval.py

@@ -20,7 +20,6 @@ from onyx.background.celery.tasks.opensearch_migration.transformer import (
 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.configs.app_configs import VESPA_MIGRATION_SERVER_SIDE_REQUEST_TIMEOUT
 from onyx.context.search.models import IndexFilters
 from onyx.context.search.models import InferenceChunkUncleaned
 from onyx.document_index.interfaces import VespaChunkRequest
@@ -336,11 +335,6 @@ def get_all_chunks_paginated(
             "format.tensors": "short-value",
             "slices": total_slices,
             "sliceId": slice_id,
-            # When exceeded, Vespa should return gracefully with partial
-            # results. Even if no hits are returned, Vespa should still return a
-            # new continuation token representing a new spot in the linear
-            # traversal.
-            "timeout": VESPA_MIGRATION_SERVER_SIDE_REQUEST_TIMEOUT,
         }
         if continuation_token is not None:
             params["continuation"] = continuation_token
@@ -349,9 +343,6 @@ def get_all_chunks_paginated(
         start_time = time.monotonic()
         try:
             with get_vespa_http_client(
-                # When exceeded, an exception is raised in our code. No progress
-                # is saved, and the task will retry this spot in the traversal
-                # later.
                 timeout=VESPA_MIGRATION_REQUEST_TIMEOUT_S
             ) as http_client:
                 response = http_client.get(url, params=params)

backend/onyx/hooks/points/document_ingestion.py

@@ -1,114 +1,33 @@
 from pydantic import BaseModel
-from pydantic import Field
 
 from onyx.db.enums import HookFailStrategy
 from onyx.db.enums import HookPoint
 from onyx.hooks.points.base import HookPointSpec
 
 
-class DocumentIngestionSection(BaseModel):
-    """Represents a single section of a document — either text or image, not both.
-
-    Text section: set `text`, leave `image_file_id` null.
-    Image section: set `image_file_id`, leave `text` null.
-    """
-
-    text: str | None = Field(
-        default=None,
-        description="Text content of this section. Set for text sections, null for image sections.",
-    )
-    link: str | None = Field(
-        default=None,
-        description="Optional URL associated with this section. Preserve the original link from the payload if you want it retained.",
-    )
-    image_file_id: str | None = Field(
-        default=None,
-        description=(
-            "Opaque identifier for an image stored in the file store. "
-            "The image content is not included — this field signals that the section is an image. "
-            "Hooks can use its presence to reorder or drop image sections, but cannot read or modify the image itself."
-        ),
-    )
-
-
-class DocumentIngestionOwner(BaseModel):
-    display_name: str | None = Field(
-        default=None,
-        description="Human-readable name of the owner.",
-    )
-    email: str | None = Field(
-        default=None,
-        description="Email address of the owner.",
-    )
-
-
+# TODO(@Bo-Onyx): define payload and response fields
 class DocumentIngestionPayload(BaseModel):
-    document_id: str = Field(
-        description="Unique identifier for the document. Read-only — changes are ignored."
-    )
-    title: str | None = Field(description="Title of the document.")
-    semantic_identifier: str = Field(
-        description="Human-readable identifier used for display (e.g. file name, page title)."
-    )
-    source: str = Field(
-        description=(
-            "Connector source type (e.g. confluence, slack, google_drive). "
-            "Read-only — changes are ignored. "
-            "Full list of values: https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/constants.py#L195"
-        )
-    )
-    sections: list[DocumentIngestionSection] = Field(
-        description="Sections of the document. Includes both text sections (text set, image_file_id null) and image sections (image_file_id set, text null)."
-    )
-    metadata: dict[str, list[str]] = Field(
-        description="Key-value metadata attached to the document. Values are always a list of strings."
-    )
-    doc_updated_at: str | None = Field(
-        description="ISO 8601 UTC timestamp of the last update at the source, or null if unknown. Example: '2024-03-15T10:30:00+00:00'."
-    )
-    primary_owners: list[DocumentIngestionOwner] | None = Field(
-        description="Primary owners of the document, or null if not available."
-    )
-    secondary_owners: list[DocumentIngestionOwner] | None = Field(
-        description="Secondary owners of the document, or null if not available."
-    )
+    pass
 
 
 class DocumentIngestionResponse(BaseModel):
-    # Intentionally permissive — customer endpoints may return extra fields.
-    sections: list[DocumentIngestionSection] | None = Field(
-        description="The sections to index, in the desired order. Reorder, drop, or modify sections freely. Null or empty list drops the document."
-    )
-    rejection_reason: str | None = Field(
-        default=None,
-        description="Logged when sections is null or empty. Falls back to a generic message if omitted.",
-    )
+    pass
 
 
 class DocumentIngestionSpec(HookPointSpec):
-    """Hook point that runs on every document before it enters the indexing pipeline.
+    """Hook point that runs during document ingestion.
 
-    Call site: immediately after Onyx's internal validation and before the
-    indexing pipeline begins — no partial writes have occurred yet.
-
-    If a Document Ingestion hook is configured, it takes precedence —
-    Document Ingestion Light will not run. Configure only one per deployment.
-
-    Supported use cases:
-    - Document filtering: drop documents based on content or metadata
-    - Content rewriting: redact PII or normalize text before indexing
+    # TODO(@Bo-Onyx): define call site, input/output schema, and timeout budget.
     """
 
     hook_point = HookPoint.DOCUMENT_INGESTION
     display_name = "Document Ingestion"
-    description = (
-        "Runs on every document before it enters the indexing pipeline. "
-        "Allows filtering, rewriting, or dropping documents."
-    )
+    description = "Runs during document ingestion. Allows filtering or transforming documents before indexing."
     default_timeout_seconds = 30.0
     fail_hard_description = "The document will not be indexed."
     default_fail_strategy = HookFailStrategy.HARD
-    docs_url = "https://docs.onyx.app/admins/advanced_configs/hook_extensions#document-ingestion"
+    # TODO(Bo-Onyx): update later
+    docs_url = "https://docs.google.com/document/d/1pGhB8Wcnhhj8rS4baEJL6CX05yFhuIDNk1gbBRiWu94/edit?tab=t.ue263ual5vdi"
 
     payload_model = DocumentIngestionPayload
     response_model = DocumentIngestionResponse

backend/onyx/hooks/points/query_processing.py

@@ -65,9 +65,8 @@ class QueryProcessingSpec(HookPointSpec):
         "The query will be blocked and the user will see an error message."
     )
     default_fail_strategy = HookFailStrategy.HARD
-    docs_url = (
-        "https://docs.onyx.app/admins/advanced_configs/hook_extensions#query-processing"
-    )
+    # TODO(Bo-Onyx): update later
+    docs_url = "https://docs.google.com/document/d/1pGhB8Wcnhhj8rS4baEJL6CX05yFhuIDNk1gbBRiWu94/edit?tab=t.g2r1a1699u87"
 
     payload_model = QueryProcessingPayload
     response_model = QueryProcessingResponse

backend/onyx/indexing/indexing_pipeline.py

@@ -33,7 +33,6 @@ from onyx.connectors.models import TextSection
 from onyx.db.document import get_documents_by_ids
 from onyx.db.document import upsert_document_by_connector_credential_pair
 from onyx.db.document import upsert_documents
-from onyx.db.enums import HookPoint
 from onyx.db.hierarchy import link_hierarchy_nodes_to_documents
 from onyx.db.models import Document as DBDocument
 from onyx.db.models import IndexModelStatus
@@ -48,13 +47,6 @@ from onyx.document_index.interfaces import DocumentMetadata
 from onyx.document_index.interfaces import IndexBatchParams
 from onyx.file_processing.image_summarization import summarize_image_with_error_handling
 from onyx.file_store.file_store import get_default_file_store
-from onyx.hooks.executor import execute_hook
-from onyx.hooks.executor import HookSkipped
-from onyx.hooks.executor import HookSoftFailed
-from onyx.hooks.points.document_ingestion import DocumentIngestionOwner
-from onyx.hooks.points.document_ingestion import DocumentIngestionPayload
-from onyx.hooks.points.document_ingestion import DocumentIngestionResponse
-from onyx.hooks.points.document_ingestion import DocumentIngestionSection
 from onyx.indexing.chunk_batch_store import ChunkBatchStore
 from onyx.indexing.chunker import Chunker
 from onyx.indexing.embedder import embed_chunks_with_failure_handling
@@ -305,7 +297,6 @@ def index_doc_batch_with_handler(
     document_batch: list[Document],
     request_id: str | None,
     tenant_id: str,
-    db_session: Session,
     adapter: IndexingBatchAdapter,
     ignore_time_skip: bool = False,
     enable_contextual_rag: bool = False,
@@ -319,7 +310,6 @@ def index_doc_batch_with_handler(
             document_batch=document_batch,
             request_id=request_id,
             tenant_id=tenant_id,
-            db_session=db_session,
             adapter=adapter,
             ignore_time_skip=ignore_time_skip,
             enable_contextual_rag=enable_contextual_rag,
@@ -795,132 +785,6 @@ def _verify_indexing_completeness(
         )
 
 
-def _apply_document_ingestion_hook(
-    documents: list[Document],
-    db_session: Session,
-) -> list[Document]:
-    """Apply the Document Ingestion hook to each document in the batch.
-
-    - HookSkipped / HookSoftFailed → document passes through unchanged.
-    - Response with sections=None → document is dropped (logged).
-    - Response with sections → document sections are replaced with the hook's output.
-    """
-
-    def _build_payload(doc: Document) -> DocumentIngestionPayload:
-        return DocumentIngestionPayload(
-            document_id=doc.id or "",
-            title=doc.title,
-            semantic_identifier=doc.semantic_identifier,
-            source=doc.source.value if doc.source is not None else "",
-            sections=[
-                DocumentIngestionSection(
-                    text=s.text if isinstance(s, TextSection) else None,
-                    link=s.link,
-                    image_file_id=(
-                        s.image_file_id if isinstance(s, ImageSection) else None
-                    ),
-                )
-                for s in doc.sections
-            ],
-            metadata={
-                k: v if isinstance(v, list) else [v] for k, v in doc.metadata.items()
-            },
-            doc_updated_at=(
-                doc.doc_updated_at.isoformat() if doc.doc_updated_at else None
-            ),
-            primary_owners=(
-                [
-                    DocumentIngestionOwner(
-                        display_name=o.get_semantic_name() or None,
-                        email=o.email,
-                    )
-                    for o in doc.primary_owners
-                ]
-                if doc.primary_owners
-                else None
-            ),
-            secondary_owners=(
-                [
-                    DocumentIngestionOwner(
-                        display_name=o.get_semantic_name() or None,
-                        email=o.email,
-                    )
-                    for o in doc.secondary_owners
-                ]
-                if doc.secondary_owners
-                else None
-            ),
-        )
-
-    def _apply_result(
-        doc: Document,
-        hook_result: DocumentIngestionResponse | HookSkipped | HookSoftFailed,
-    ) -> Document | None:
-        """Return the modified doc, original doc (skip/soft-fail), or None (drop)."""
-        if isinstance(hook_result, (HookSkipped, HookSoftFailed)):
-            return doc
-        if not hook_result.sections:
-            reason = hook_result.rejection_reason or "Document rejected by hook"
-            logger.info(
-                f"Document ingestion hook dropped document doc_id={doc.id!r}: {reason}"
-            )
-            return None
-        new_sections: list[TextSection | ImageSection] = []
-        for s in hook_result.sections:
-            if s.image_file_id is not None:
-                new_sections.append(
-                    ImageSection(image_file_id=s.image_file_id, link=s.link)
-                )
-            elif s.text is not None:
-                new_sections.append(TextSection(text=s.text, link=s.link))
-            else:
-                logger.warning(
-                    f"Document ingestion hook returned a section with neither text nor "
-                    f"image_file_id for doc_id={doc.id!r} — skipping section."
-                )
-        if not new_sections:
-            logger.info(
-                f"Document ingestion hook produced no valid sections for doc_id={doc.id!r} — dropping document."
-            )
-            return None
-        return doc.model_copy(update={"sections": new_sections})
-
-    if not documents:
-        return documents
-
-    # Run the hook for the first document. If it returns HookSkipped the hook
-    # is not configured — skip the remaining N-1 DB lookups.
-    first_doc = documents[0]
-    first_payload = _build_payload(first_doc).model_dump()
-    first_hook_result = execute_hook(
-        db_session=db_session,
-        hook_point=HookPoint.DOCUMENT_INGESTION,
-        payload=first_payload,
-        response_type=DocumentIngestionResponse,
-    )
-    if isinstance(first_hook_result, HookSkipped):
-        return documents
-
-    result: list[Document] = []
-    first_applied = _apply_result(first_doc, first_hook_result)
-    if first_applied is not None:
-        result.append(first_applied)
-
-    for doc in documents[1:]:
-        payload = _build_payload(doc).model_dump()
-        hook_result = execute_hook(
-            db_session=db_session,
-            hook_point=HookPoint.DOCUMENT_INGESTION,
-            payload=payload,
-            response_type=DocumentIngestionResponse,
-        )
-        applied = _apply_result(doc, hook_result)
-        if applied is not None:
-            result.append(applied)
-
-    return result
-
-
 @log_function_time(debug_only=True)
 def index_doc_batch(
     *,
@@ -930,7 +794,6 @@ def index_doc_batch(
     document_indices: list[DocumentIndex],
     request_id: str | None,
     tenant_id: str,
-    db_session: Session,
     adapter: IndexingBatchAdapter,
     enable_contextual_rag: bool = False,
     llm: LLM | None = None,
@@ -955,7 +818,6 @@ def index_doc_batch(
     )
 
     filtered_documents = filter_fnc(document_batch)
-    filtered_documents = _apply_document_ingestion_hook(filtered_documents, db_session)
     context = adapter.prepare(filtered_documents, ignore_time_skip)
     if not context:
         return IndexingPipelineResult.empty(len(filtered_documents))
@@ -1143,7 +1005,6 @@ def run_indexing_pipeline(
         document_batch=document_batch,
         request_id=request_id,
         tenant_id=tenant_id,
-        db_session=db_session,
         adapter=adapter,
         enable_contextual_rag=enable_contextual_rag,
         llm=llm,

backend/onyx/server/manage/models.py

@@ -147,7 +147,6 @@ class UserInfo(BaseModel):
         is_anonymous_user: bool | None = None,
         tenant_info: TenantInfo | None = None,
         assistant_specific_configs: UserSpecificAssistantPreferences | None = None,
-        memories: list[MemoryItem] | None = None,
     ) -> "UserInfo":
         return cls(
             id=str(user.id),
@@ -192,7 +191,10 @@ class UserInfo(BaseModel):
                 role=user.personal_role or "",
                 use_memories=user.use_memories,
                 enable_memory_tool=user.enable_memory_tool,
-                memories=memories or [],
+                memories=[
+                    MemoryItem(id=memory.id, content=memory.memory_text)
+                    for memory in (user.memories or [])
+                ],
                 user_preferences=user.user_preferences or "",
             ),
         )

backend/onyx/server/manage/users.py

@@ -57,7 +57,6 @@ from onyx.db.user_preferences import activate_user
 from onyx.db.user_preferences import deactivate_user
 from onyx.db.user_preferences import get_all_user_assistant_specific_configs
 from onyx.db.user_preferences import get_latest_access_token_for_user
-from onyx.db.user_preferences import get_memories_for_user
 from onyx.db.user_preferences import update_assistant_preferences
 from onyx.db.user_preferences import update_user_assistant_visibility
 from onyx.db.user_preferences import update_user_auto_scroll
@@ -824,11 +823,6 @@ def verify_user_logged_in(
             [],
         ),
     )
-    memories = [
-        MemoryItem(id=memory.id, content=memory.memory_text)
-        for memory in get_memories_for_user(user.id, db_session)
-    ]
-
     user_info = UserInfo.from_model(
         user,
         current_token_created_at=token_created_at,
@@ -839,7 +833,6 @@ def verify_user_logged_in(
             new_tenant=new_tenant,
             invitation=tenant_invitation,
         ),
-        memories=memories,
     )
 
     return user_info
@@ -937,8 +930,7 @@ def update_user_personalization_api(
         else user.enable_memory_tool
     )
     existing_memories = [
-        MemoryItem(id=memory.id, content=memory.memory_text)
-        for memory in get_memories_for_user(user.id, db_session)
+        MemoryItem(id=memory.id, content=memory.memory_text) for memory in user.memories
     ]
     new_memories = (
         request.memories if request.memories is not None else existing_memories

backend/tests/daily/connectors/google_drive/test_resolver.py

@@ -0,0 +1,239 @@
+"""Tests for GoogleDriveConnector.resolve_errors against real Google Drive."""
+
+import json
+import os
+from collections.abc import Callable
+from unittest.mock import patch
+
+from onyx.connectors.google_drive.connector import GoogleDriveConnector
+from onyx.connectors.models import ConnectorFailure
+from onyx.connectors.models import Document
+from onyx.connectors.models import DocumentFailure
+from onyx.connectors.models import HierarchyNode
+from tests.daily.connectors.google_drive.consts_and_utils import ADMIN_EMAIL
+from tests.daily.connectors.google_drive.consts_and_utils import (
+    ALL_EXPECTED_HIERARCHY_NODES,
+)
+from tests.daily.connectors.google_drive.consts_and_utils import FOLDER_1_ID
+from tests.daily.connectors.google_drive.consts_and_utils import SHARED_DRIVE_1_ID
+
+_DRIVE_ID_MAPPING_PATH = os.path.join(
+    os.path.dirname(__file__), "drive_id_mapping.json"
+)
+
+
+def _load_web_view_links(file_ids: list[int]) -> list[str]:
+    with open(_DRIVE_ID_MAPPING_PATH) as f:
+        mapping: dict[str, str] = json.load(f)
+    return [mapping[str(fid)] for fid in file_ids]
+
+
+def _build_failures(web_view_links: list[str]) -> list[ConnectorFailure]:
+    return [
+        ConnectorFailure(
+            failed_document=DocumentFailure(
+                document_id=link,
+                document_link=link,
+            ),
+            failure_message=f"Synthetic failure for {link}",
+        )
+        for link in web_view_links
+    ]
+
+
+@patch("onyx.file_processing.extract_file_text.get_unstructured_api_key")
+def test_resolve_single_file(
+    mock_api_key: None,  # noqa: ARG001
+    google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
+) -> None:
+    """Resolve a single known file and verify we get back exactly one Document."""
+    connector = google_drive_service_acct_connector_factory(
+        primary_admin_email=ADMIN_EMAIL,
+        include_shared_drives=True,
+        shared_drive_urls=None,
+        include_my_drives=True,
+        my_drive_emails=None,
+        shared_folder_urls=None,
+        include_files_shared_with_me=False,
+    )
+
+    web_view_links = _load_web_view_links([0])
+    failures = _build_failures(web_view_links)
+
+    results = list(connector.resolve_errors(failures))
+
+    docs = [r for r in results if isinstance(r, Document)]
+    new_failures = [r for r in results if isinstance(r, ConnectorFailure)]
+    hierarchy_nodes = [r for r in results if isinstance(r, HierarchyNode)]
+
+    assert len(docs) == 1
+    assert len(new_failures) == 0
+    assert docs[0].semantic_identifier == "file_0.txt"
+
+    # Should yield at least one hierarchy node (the file's parent folder chain)
+    assert len(hierarchy_nodes) > 0
+
+
+@patch("onyx.file_processing.extract_file_text.get_unstructured_api_key")
+def test_resolve_multiple_files(
+    mock_api_key: None,  # noqa: ARG001
+    google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
+) -> None:
+    """Resolve multiple files across different folders via batch API."""
+    connector = google_drive_service_acct_connector_factory(
+        primary_admin_email=ADMIN_EMAIL,
+        include_shared_drives=True,
+        shared_drive_urls=None,
+        include_my_drives=True,
+        my_drive_emails=None,
+        shared_folder_urls=None,
+        include_files_shared_with_me=False,
+    )
+
+    # Pick files from different folders: admin files (0-4), shared drive 1 (20-24), folder_2 (45-49)
+    file_ids = [0, 1, 20, 21, 45]
+    web_view_links = _load_web_view_links(file_ids)
+    failures = _build_failures(web_view_links)
+
+    results = list(connector.resolve_errors(failures))
+
+    docs = [r for r in results if isinstance(r, Document)]
+    new_failures = [r for r in results if isinstance(r, ConnectorFailure)]
+    hierarchy_nodes = [r for r in results if isinstance(r, HierarchyNode)]
+
+    assert len(new_failures) == 0
+    retrieved_names = {doc.semantic_identifier for doc in docs}
+    expected_names = {f"file_{fid}.txt" for fid in file_ids}
+    assert expected_names == retrieved_names
+
+    # Files span multiple folders, so we should get hierarchy nodes
+    assert len(hierarchy_nodes) > 0
+
+
+@patch("onyx.file_processing.extract_file_text.get_unstructured_api_key")
+def test_resolve_hierarchy_nodes_are_valid(
+    mock_api_key: None,  # noqa: ARG001
+    google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
+) -> None:
+    """Verify that hierarchy nodes from resolve_errors match expected structure."""
+    connector = google_drive_service_acct_connector_factory(
+        primary_admin_email=ADMIN_EMAIL,
+        include_shared_drives=True,
+        shared_drive_urls=None,
+        include_my_drives=True,
+        my_drive_emails=None,
+        shared_folder_urls=None,
+        include_files_shared_with_me=False,
+    )
+
+    # File in folder_1 (inside shared_drive_1) — should walk up to shared_drive_1 root
+    web_view_links = _load_web_view_links([25])
+    failures = _build_failures(web_view_links)
+
+    results = list(connector.resolve_errors(failures))
+
+    hierarchy_nodes = [r for r in results if isinstance(r, HierarchyNode)]
+    node_ids = {node.raw_node_id for node in hierarchy_nodes}
+
+    # File 25 is in folder_1 which is inside shared_drive_1.
+    # The parent walk must yield at least these two ancestors.
+    assert (
+        FOLDER_1_ID in node_ids
+    ), f"Expected folder_1 ({FOLDER_1_ID}) in hierarchy nodes, got: {node_ids}"
+    assert (
+        SHARED_DRIVE_1_ID in node_ids
+    ), f"Expected shared_drive_1 ({SHARED_DRIVE_1_ID}) in hierarchy nodes, got: {node_ids}"
+
+    for node in hierarchy_nodes:
+        if node.raw_node_id not in ALL_EXPECTED_HIERARCHY_NODES:
+            continue
+        expected = ALL_EXPECTED_HIERARCHY_NODES[node.raw_node_id]
+        assert node.display_name == expected.display_name, (
+            f"Display name mismatch for {node.raw_node_id}: "
+            f"expected '{expected.display_name}', got '{node.display_name}'"
+        )
+        assert node.node_type == expected.node_type, (
+            f"Node type mismatch for {node.raw_node_id}: "
+            f"expected '{expected.node_type}', got '{node.node_type}'"
+        )
+
+
+@patch("onyx.file_processing.extract_file_text.get_unstructured_api_key")
+def test_resolve_with_invalid_link(
+    mock_api_key: None,  # noqa: ARG001
+    google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
+) -> None:
+    """Resolve with a mix of valid and invalid links — invalid ones yield ConnectorFailure."""
+    connector = google_drive_service_acct_connector_factory(
+        primary_admin_email=ADMIN_EMAIL,
+        include_shared_drives=True,
+        shared_drive_urls=None,
+        include_my_drives=True,
+        my_drive_emails=None,
+        shared_folder_urls=None,
+        include_files_shared_with_me=False,
+    )
+
+    valid_links = _load_web_view_links([0])
+    invalid_link = "https://drive.google.com/file/d/NONEXISTENT_FILE_ID_12345"
+    failures = _build_failures(valid_links + [invalid_link])
+
+    results = list(connector.resolve_errors(failures))
+
+    docs = [r for r in results if isinstance(r, Document)]
+    new_failures = [r for r in results if isinstance(r, ConnectorFailure)]
+
+    assert len(docs) == 1
+    assert docs[0].semantic_identifier == "file_0.txt"
+    assert len(new_failures) == 1
+    assert new_failures[0].failed_document is not None
+    assert new_failures[0].failed_document.document_id == invalid_link
+
+
+@patch("onyx.file_processing.extract_file_text.get_unstructured_api_key")
+def test_resolve_empty_errors(
+    mock_api_key: None,  # noqa: ARG001
+    google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
+) -> None:
+    """Resolving an empty error list should yield nothing."""
+    connector = google_drive_service_acct_connector_factory(
+        primary_admin_email=ADMIN_EMAIL,
+        include_shared_drives=True,
+        shared_drive_urls=None,
+        include_my_drives=True,
+        my_drive_emails=None,
+        shared_folder_urls=None,
+        include_files_shared_with_me=False,
+    )
+
+    results = list(connector.resolve_errors([]))
+
+    assert len(results) == 0
+
+
+@patch("onyx.file_processing.extract_file_text.get_unstructured_api_key")
+def test_resolve_entity_failures_are_skipped(
+    mock_api_key: None,  # noqa: ARG001
+    google_drive_service_acct_connector_factory: Callable[..., GoogleDriveConnector],
+) -> None:
+    """Entity failures (not document failures) should be skipped by resolve_errors."""
+    from onyx.connectors.models import EntityFailure
+
+    connector = google_drive_service_acct_connector_factory(
+        primary_admin_email=ADMIN_EMAIL,
+        include_shared_drives=True,
+        shared_drive_urls=None,
+        include_my_drives=True,
+        my_drive_emails=None,
+        shared_folder_urls=None,
+        include_files_shared_with_me=False,
+    )
+
+    entity_failure = ConnectorFailure(
+        failed_entity=EntityFailure(entity_id="some_stage"),
+        failure_message="retrieval failure",
+    )
+
+    results = list(connector.resolve_errors([entity_failure]))
+
+    assert len(results) == 0

backend/tests/unit/onyx/indexing/test_indexing_pipeline.py

@@ -2,7 +2,6 @@ import threading
 from typing import Any
 from typing import cast
 from typing import List
-from unittest.mock import MagicMock
 from unittest.mock import Mock
 from unittest.mock import patch
 
@@ -13,13 +12,8 @@ from onyx.connectors.models import Document
 from onyx.connectors.models import DocumentSource
 from onyx.connectors.models import ImageSection
 from onyx.connectors.models import TextSection
-from onyx.hooks.executor import HookSkipped
-from onyx.hooks.executor import HookSoftFailed
-from onyx.hooks.points.document_ingestion import DocumentIngestionResponse
-from onyx.hooks.points.document_ingestion import DocumentIngestionSection
 from onyx.indexing.chunker import Chunker
 from onyx.indexing.embedder import DefaultIndexingEmbedder
-from onyx.indexing.indexing_pipeline import _apply_document_ingestion_hook
 from onyx.indexing.indexing_pipeline import add_contextual_summaries
 from onyx.indexing.indexing_pipeline import filter_documents
 from onyx.indexing.indexing_pipeline import process_image_sections
@@ -229,148 +223,3 @@ def test_contextual_rag(
             count += 1
         assert chunk.doc_summary == doc_summary
         assert chunk.chunk_context == chunk_context
-
-
-# ---------------------------------------------------------------------------
-# _apply_document_ingestion_hook
-# ---------------------------------------------------------------------------
-
-_PATCH_EXECUTE_HOOK = "onyx.indexing.indexing_pipeline.execute_hook"
-
-
-def _make_doc(
-    doc_id: str = "doc1",
-    sections: list[TextSection | ImageSection] | None = None,
-) -> Document:
-    if sections is None:
-        sections = [TextSection(text="Hello", link="http://example.com")]
-    return Document(
-        id=doc_id,
-        title="Test Doc",
-        semantic_identifier="test-doc",
-        sections=cast(list[TextSection | ImageSection], sections),
-        source=DocumentSource.FILE,
-        metadata={},
-    )
-
-
-def test_document_ingestion_hook_skipped_passes_through() -> None:
-    doc = _make_doc()
-    with patch(_PATCH_EXECUTE_HOOK, return_value=HookSkipped()):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert result == [doc]
-
-
-def test_document_ingestion_hook_soft_failed_passes_through() -> None:
-    doc = _make_doc()
-    with patch(_PATCH_EXECUTE_HOOK, return_value=HookSoftFailed()):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert result == [doc]
-
-
-def test_document_ingestion_hook_none_sections_drops_document() -> None:
-    doc = _make_doc()
-    with patch(
-        _PATCH_EXECUTE_HOOK,
-        return_value=DocumentIngestionResponse(
-            sections=None, rejection_reason="PII detected"
-        ),
-    ):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert result == []
-
-
-def test_document_ingestion_hook_all_invalid_sections_drops_document() -> None:
-    """A non-empty list where every section has neither text nor image_file_id drops the doc."""
-    doc = _make_doc()
-    with patch(
-        _PATCH_EXECUTE_HOOK,
-        return_value=DocumentIngestionResponse(sections=[DocumentIngestionSection()]),
-    ):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert result == []
-
-
-def test_document_ingestion_hook_empty_sections_drops_document() -> None:
-    doc = _make_doc()
-    with patch(
-        _PATCH_EXECUTE_HOOK,
-        return_value=DocumentIngestionResponse(sections=[]),
-    ):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert result == []
-
-
-def test_document_ingestion_hook_rewrites_text_sections() -> None:
-    doc = _make_doc(sections=[TextSection(text="original", link="http://a.com")])
-    with patch(
-        _PATCH_EXECUTE_HOOK,
-        return_value=DocumentIngestionResponse(
-            sections=[DocumentIngestionSection(text="rewritten", link="http://b.com")]
-        ),
-    ):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert len(result) == 1
-    assert len(result[0].sections) == 1
-    section = result[0].sections[0]
-    assert isinstance(section, TextSection)
-    assert section.text == "rewritten"
-    assert section.link == "http://b.com"
-
-
-def test_document_ingestion_hook_preserves_image_section_order() -> None:
-    """Hook receives all sections including images and controls final ordering."""
-    image = ImageSection(image_file_id="img-1", link=None)
-    doc = _make_doc(
-        sections=cast(
-            list[TextSection | ImageSection],
-            [TextSection(text="original", link=None), image],
-        )
-    )
-    # Hook moves the image before the text section
-    with patch(
-        _PATCH_EXECUTE_HOOK,
-        return_value=DocumentIngestionResponse(
-            sections=[
-                DocumentIngestionSection(image_file_id="img-1", link=None),
-                DocumentIngestionSection(text="rewritten", link=None),
-            ]
-        ),
-    ):
-        result = _apply_document_ingestion_hook([doc], MagicMock())
-    assert len(result) == 1
-    sections = result[0].sections
-    assert len(sections) == 2
-    assert (
-        isinstance(sections[0], ImageSection) and sections[0].image_file_id == "img-1"
-    )
-    assert isinstance(sections[1], TextSection) and sections[1].text == "rewritten"
-
-
-def test_document_ingestion_hook_mixed_batch() -> None:
-    """Drop one doc, rewrite another, pass through a third."""
-    doc_drop = _make_doc(doc_id="drop")
-    doc_rewrite = _make_doc(doc_id="rewrite")
-    doc_skip = _make_doc(doc_id="skip")
-
-    def _side_effect(**kwargs: Any) -> Any:
-        doc_id = kwargs["payload"]["document_id"]
-        if doc_id == "drop":
-            return DocumentIngestionResponse(sections=None)
-        if doc_id == "rewrite":
-            return DocumentIngestionResponse(
-                sections=[DocumentIngestionSection(text="new text", link=None)]
-            )
-        return HookSkipped()
-
-    with patch(_PATCH_EXECUTE_HOOK, side_effect=_side_effect):
-        result = _apply_document_ingestion_hook(
-            [doc_drop, doc_rewrite, doc_skip], MagicMock()
-        )
-
-    assert len(result) == 2
-    ids = {d.id for d in result}
-    assert ids == {"rewrite", "skip"}
-    rewritten = next(d for d in result if d.id == "rewrite")
-    assert isinstance(rewritten.sections[0], TextSection)
-    assert rewritten.sections[0].text == "new text"

web/AGENTS.md

@@ -231,23 +231,6 @@ import { Hoverable } from "@opal/core";
 
 # Best Practices
 
-## 0. Size Variant Defaults
-
-**When using `SizeVariants` (or any subset like `PaddingVariants`, `RoundingVariants`) as a prop
-type, always default to `"md"`.**
-
-**Reason:** `"md"` is the standard middle-of-the-road preset across the design system. Consistent
-defaults make components predictable — callers only need to specify a size when they want something
-other than the norm.
-
-```typescript
-// ✅ Good — default to "md"
-function MyCard({ padding = "md", rounding = "md" }: MyCardProps) { ... }
-
-// ❌ Bad — arbitrary or inconsistent defaults
-function MyCard({ padding = "sm", rounding = "lg" }: MyCardProps) { ... }
-```
-
 ## 1. Tailwind Dark Mode
 
 **Strictly forbid using the `dark:` modifier in Tailwind classes, except for logo icon handling.**

web/lib/opal/src/components/cards/card/Card.stories.tsx

@@ -29,7 +29,7 @@ export const BackgroundVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
       {BACKGROUND_VARIANTS.map((bg) => (
-        <Card key={bg} background={bg} border="solid">
+        <Card key={bg} backgroundVariant={bg} borderVariant="solid">
           <p>backgroundVariant: {bg}</p>
         </Card>
       ))}
@@ -41,7 +41,7 @@ export const BorderVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
       {BORDER_VARIANTS.map((border) => (
-        <Card key={border} border={border}>
+        <Card key={border} borderVariant={border}>
           <p>borderVariant: {border}</p>
         </Card>
       ))}
@@ -53,7 +53,7 @@ export const PaddingVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
       {PADDING_VARIANTS.map((padding) => (
-        <Card key={padding} padding={padding} border="solid">
+        <Card key={padding} paddingVariant={padding} borderVariant="solid">
           <p>paddingVariant: {padding}</p>
         </Card>
       ))}
@@ -65,7 +65,7 @@ export const RoundingVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
       {ROUNDING_VARIANTS.map((rounding) => (
-        <Card key={rounding} rounding={rounding} border="solid">
+        <Card key={rounding} roundingVariant={rounding} borderVariant="solid">
           <p>roundingVariant: {rounding}</p>
         </Card>
       ))}
@@ -84,9 +84,9 @@ export const AllCombinations: Story = {
               BORDER_VARIANTS.map((border) => (
                 <Card
                   key={`${padding}-${bg}-${border}`}
-                  padding={padding}
-                  background={bg}
-                  border={border}
+                  paddingVariant={padding}
+                  backgroundVariant={bg}
+                  borderVariant={border}
                 >
                   <p className="text-xs">
                     bg: {bg}, border: {border}

web/lib/opal/src/components/cards/card/README.md

@@ -8,30 +8,30 @@ A plain container component with configurable background, border, padding, and r
 
 Padding and rounding are controlled independently:
 
-| `padding` | Class   |
-|-----------|---------|
-| `"lg"`    | `p-6`   |
-| `"md"`    | `p-4`   |
-| `"sm"`    | `p-2`   |
-| `"xs"`    | `p-1`   |
-| `"2xs"`   | `p-0.5` |
-| `"fit"`   | `p-0`   |
+| `paddingVariant` | Class   |
+|------------------|---------|
+| `"lg"`           | `p-6`   |
+| `"md"`           | `p-4`   |
+| `"sm"`           | `p-2`   |
+| `"xs"`           | `p-1`   |
+| `"2xs"`          | `p-0.5` |
+| `"fit"`          | `p-0`   |
 
-| `rounding` | Class        |
-|------------|--------------|
-| `"xs"`     | `rounded-04` |
-| `"sm"`     | `rounded-08` |
-| `"md"`     | `rounded-12` |
-| `"lg"`     | `rounded-16` |
+| `roundingVariant` | Class        |
+|-------------------|--------------|
+| `"xs"`            | `rounded-04` |
+| `"sm"`            | `rounded-08` |
+| `"md"`            | `rounded-12` |
+| `"lg"`            | `rounded-16` |
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `padding` | `PaddingVariants` | `"sm"` | Padding preset |
-| `rounding` | `RoundingVariants` | `"md"` | Border-radius preset |
-| `background` | `"none" \| "light" \| "heavy"` | `"light"` | Background fill intensity |
-| `border` | `"none" \| "dashed" \| "solid"` | `"none"` | Border style |
+| `paddingVariant` | `PaddingVariants` | `"sm"` | Padding preset |
+| `roundingVariant` | `RoundingVariants` | `"md"` | Border-radius preset |
+| `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 |
 
@@ -47,17 +47,17 @@ import { Card } from "@opal/components";
 </Card>
 
 // Large padding + rounding with solid border
-<Card padding="lg" rounding="lg" border="solid">
+<Card paddingVariant="lg" roundingVariant="lg" borderVariant="solid">
   <p>Spacious card</p>
 </Card>
 
 // Compact card with solid border
-<Card padding="xs" rounding="sm" border="solid">
+<Card paddingVariant="xs" roundingVariant="sm" borderVariant="solid">
   <p>Compact card</p>
 </Card>
 
 // Empty state card
-<Card background="none" border="dashed">
+<Card backgroundVariant="none" borderVariant="dashed">
   <p>No items yet</p>
 </Card>
 ```

web/lib/opal/src/components/cards/card/components.tsx

@@ -1,6 +1,5 @@
 import "@opal/components/cards/card/styles.css";
 import type { PaddingVariants, RoundingVariants } from "@opal/types";
-import { cardPaddingVariants, cardRoundingVariants } from "@opal/shared";
 import { cn } from "@opal/utils";
 
 // ---------------------------------------------------------------------------
@@ -23,9 +22,9 @@ type CardProps = {
    * | `"2xs"` | `p-0.5` |
    * | `"fit"` | `p-0`   |
    *
-   * @default "md"
+   * @default "sm"
    */
-  padding?: PaddingVariants;
+  paddingVariant?: PaddingVariants;
 
   /**
    * Border-radius preset.
@@ -39,7 +38,7 @@ type CardProps = {
    *
    * @default "md"
    */
-  rounding?: RoundingVariants;
+  roundingVariant?: RoundingVariants;
 
   /**
    * Background fill intensity.
@@ -49,7 +48,7 @@ type CardProps = {
    *
    * @default "light"
    */
-  background?: BackgroundVariant;
+  backgroundVariant?: BackgroundVariant;
 
   /**
    * Border style.
@@ -59,7 +58,7 @@ type CardProps = {
    *
    * @default "none"
    */
-  border?: BorderVariant;
+  borderVariant?: BorderVariant;
 
   /** Ref forwarded to the root `<div>`. */
   ref?: React.Ref<HTMLDivElement>;
@@ -67,27 +66,47 @@ type CardProps = {
   children?: React.ReactNode;
 };
 
+// ---------------------------------------------------------------------------
+// Mappings
+// ---------------------------------------------------------------------------
+
+const paddingForVariant: Record<PaddingVariants, string> = {
+  lg: "p-6",
+  md: "p-4",
+  sm: "p-2",
+  xs: "p-1",
+  "2xs": "p-0.5",
+  fit: "p-0",
+};
+
+const roundingForVariant: Record<RoundingVariants, string> = {
+  lg: "rounded-16",
+  md: "rounded-12",
+  sm: "rounded-08",
+  xs: "rounded-04",
+};
+
 // ---------------------------------------------------------------------------
 // Card
 // ---------------------------------------------------------------------------
 
 function Card({
-  padding: paddingProp = "md",
-  rounding: roundingProp = "md",
-  background = "light",
-  border = "none",
+  paddingVariant = "sm",
+  roundingVariant = "md",
+  backgroundVariant = "light",
+  borderVariant = "none",
   ref,
   children,
 }: CardProps) {
-  const padding = cardPaddingVariants[paddingProp];
-  const rounding = cardRoundingVariants[roundingProp];
+  const padding = paddingForVariant[paddingVariant];
+  const rounding = roundingForVariant[roundingVariant];
 
   return (
     <div
       ref={ref}
       className={cn("opal-card", padding, rounding)}
-      data-background={background}
-      data-border={border}
+      data-background={backgroundVariant}
+      data-border={borderVariant}
     >
       {children}
     </div>

web/lib/opal/src/components/cards/empty-message-card/EmptyMessageCard.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from "@storybook/react";
 import { EmptyMessageCard } from "@opal/components";
 import { SvgSparkle, SvgUsers } from "@opal/icons";
 
-const PADDING_VARIANTS = ["fit", "2xs", "xs", "sm", "md", "lg"] as const;
+const SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
 
 const meta: Meta<typeof EmptyMessageCard> = {
   title: "opal/components/EmptyMessageCard",
@@ -26,14 +26,14 @@ export const WithCustomIcon: Story = {
   },
 };
 
-export const PaddingVariants: Story = {
+export const SizeVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
-      {PADDING_VARIANTS.map((padding) => (
+      {SIZE_VARIANTS.map((size) => (
         <EmptyMessageCard
-          key={padding}
-          padding={padding}
-          title={`padding: ${padding}`}
+          key={size}
+          sizeVariant={size}
+          title={`sizeVariant: ${size}`}
         />
       ))}
     </div>

web/lib/opal/src/components/cards/empty-message-card/README.md

@@ -6,12 +6,12 @@ A pre-configured Card for empty states. Renders a transparent card with a dashed
 
 ## Props
 
-| Prop      | Type                        | Default    | Description                      |
-| --------- | --------------------------- | ---------- | -------------------------------- |
-| `icon`    | `IconFunctionComponent`     | `SvgEmpty` | Icon displayed alongside the title |
-| `title`   | `string`                    | —          | Primary message text (required)  |
-| `padding` | `PaddingVariants`           | `"sm"`     | Padding preset for the card      |
-| `ref`     | `React.Ref<HTMLDivElement>` | —          | Ref forwarded to the root div    |
+| Prop              | Type                        | Default    | Description                                      |
+| ----------------- | --------------------------- | ---------- | ------------------------------------------------ |
+| `icon`            | `IconFunctionComponent`     | `SvgEmpty` | Icon displayed alongside the title               |
+| `title`           | `string`                    | —          | Primary message text (required)                  |
+| `paddingVariant`  | `PaddingVariants`           | `"sm"`     | Padding preset for the card                      |
+| `ref`             | `React.Ref<HTMLDivElement>` | —          | Ref forwarded to the root div                    |
 
 ## Usage
 
@@ -26,5 +26,5 @@ import { SvgSparkle, SvgFileText } from "@opal/icons";
 <EmptyMessageCard icon={SvgSparkle} title="No agents selected." />
 
 // With custom padding
-<EmptyMessageCard padding="xs" icon={SvgFileText} title="No documents available." />
+<EmptyMessageCard paddingVariant="xs" icon={SvgFileText} title="No documents available." />
 ```

web/lib/opal/src/components/cards/empty-message-card/components.tsx

@@ -14,8 +14,8 @@ type EmptyMessageCardProps = {
   /** Primary message text. */
   title: string;
 
-  /** Padding preset for the card. @default "md" */
-  padding?: PaddingVariants;
+  /** Padding preset for the card. */
+  paddingVariant?: PaddingVariants;
 
   /** Ref forwarded to the root Card div. */
   ref?: React.Ref<HTMLDivElement>;
@@ -28,16 +28,15 @@ type EmptyMessageCardProps = {
 function EmptyMessageCard({
   icon = SvgEmpty,
   title,
-  padding = "md",
+  paddingVariant = "sm",
   ref,
 }: EmptyMessageCardProps) {
   return (
     <Card
       ref={ref}
-      background="none"
-      border="dashed"
-      padding={padding}
-      rounding="md"
+      backgroundVariant="none"
+      borderVariant="dashed"
+      paddingVariant={paddingVariant}
     >
       <Content
         icon={icon}

web/lib/opal/src/components/cards/select-card/README.md

@@ -2,11 +2,11 @@
 
 **Import:** `import { SelectCard, type SelectCardProps } from "@opal/components";`
 
-A stateful interactive card — the card counterpart to [`SelectButton`](../../buttons/select-button/README.md). Built on `Interactive.Stateful` (Slot) with a structural `<div>` that owns padding, rounding, border, and overflow. Always uses the `select-card` Interactive.Stateful variant internally.
+A stateful interactive card — the card counterpart to [`SelectButton`](../../buttons/select-button/README.md). Built on `Interactive.Stateful` (Slot) with a structural `<div>` that owns padding, rounding, border, and overflow.
 
 ## Relationship to Card
 
-`Card` is a plain, non-interactive container. `SelectCard` adds stateful interactivity (hover, active, disabled, state-driven colors) by wrapping its root div with `Interactive.Stateful`. Both share the same independent `padding` / `rounding` API.
+`Card` is a plain, non-interactive container. `SelectCard` adds stateful interactivity (hover, active, disabled, state-driven colors) by wrapping its root div with `Interactive.Stateful`. The relationship mirrors `Button` (stateless) vs `SelectButton` (stateful).
 
 ## Relationship to SelectButton
 
@@ -18,15 +18,15 @@ Interactive.Stateful → structural element → content
 
 The key differences:
 
-- SelectCard renders a `<div>` (not `Interactive.Container`) — cards have their own rounding scale and don't need Container's height/min-width.
+- SelectCard renders a `<div>` (not `Interactive.Container`) — cards have their own rounding scale (one notch larger than buttons) and don't need Container's height/min-width.
 - SelectCard has no `foldable` prop — use `Interactive.Foldable` directly inside children.
 - SelectCard's children are fully composable — use `CardHeaderLayout`, `ContentAction`, `Content`, buttons, etc. inside.
 
 ## Architecture
 
 ```
-Interactive.Stateful (variant="select-card")  <- state, interaction, disabled, onClick
-  └─ div.opal-select-card                    <- padding, rounding, border, overflow
+Interactive.Stateful              <- variant, state, interaction, disabled, onClick
+  └─ div.opal-select-card        <- padding, rounding, border, overflow
        └─ children (composable)
 ```
 
@@ -34,36 +34,28 @@ The `Interactive.Stateful` Slot merges onto the div, producing a single DOM elem
 
 ## Props
 
-Inherits **all** props from `InteractiveStatefulProps` (except `variant`, which is hardcoded to `select-card`) plus:
+Inherits **all** props from `InteractiveStatefulProps` (variant, state, interaction, onClick, href, etc.) plus:
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `padding` | `PaddingVariants` | `"sm"` | Padding preset |
-| `rounding` | `RoundingVariants` | `"lg"` | Border-radius preset |
+| `sizeVariant` | `ContainerSizeVariants` | `"lg"` | Controls padding and border-radius |
 | `ref` | `React.Ref<HTMLDivElement>` | — | Ref forwarded to the root div |
 | `children` | `React.ReactNode` | — | Card content |
 
-### Padding scale
-
-| `padding` | Class   |
-|-----------|---------|
-| `"lg"`    | `p-6`   |
-| `"md"`    | `p-4`   |
-| `"sm"`    | `p-2`   |
-| `"xs"`    | `p-1`   |
-| `"2xs"`   | `p-0.5` |
-| `"fit"`   | `p-0`   |
-
 ### Rounding scale
 
-| `rounding` | Class        |
-|------------|--------------|
-| `"xs"`     | `rounded-04` |
-| `"sm"`     | `rounded-08` |
-| `"md"`     | `rounded-12` |
-| `"lg"`     | `rounded-16` |
+Cards use a bumped-up rounding scale compared to buttons:
 
-### State colors (`select-card` variant)
+| Size | Rounding | Effective radius |
+|---|---|---|
+| `lg` | `rounded-16` | 1rem (16px) |
+| `md`–`sm` | `rounded-12` | 0.75rem (12px) |
+| `xs`–`2xs` | `rounded-08` | 0.5rem (8px) |
+| `fit` | `rounded-16` | 1rem (16px) |
+
+### Recommended variant: `select-card`
+
+The `select-card` Interactive.Stateful variant is specifically designed for cards. Unlike `select-heavy` (which only changes foreground color between empty and filled), `select-card` gives the filled state a visible background — important on larger surfaces where background carries more of the visual distinction.
 
 | State | Rest background | Rest foreground |
 |---|---|---|
@@ -90,7 +82,7 @@ All background and foreground colors come from the Interactive.Stateful CSS, not
 import { SelectCard } from "@opal/components";
 import { CardHeaderLayout } from "@opal/layouts";
 
-<SelectCard state="selected" onClick={handleClick}>
+<SelectCard variant="select-card" state="selected" onClick={handleClick}>
   <CardHeaderLayout
     icon={SvgGlobe}
     title="Google"
@@ -108,7 +100,7 @@ import { CardHeaderLayout } from "@opal/layouts";
 ### Disconnected state (clickable)
 
 ```tsx
-<SelectCard state="empty" onClick={handleConnect}>
+<SelectCard variant="select-card" state="empty" onClick={handleConnect}>
   <CardHeaderLayout
     icon={SvgCloud}
     title="OpenAI"
@@ -123,7 +115,7 @@ import { CardHeaderLayout } from "@opal/layouts";
 ### With foldable hover-reveal
 
 ```tsx
-<SelectCard state="filled">
+<SelectCard variant="select-card" state="filled">
   <CardHeaderLayout
     icon={SvgCloud}
     title="OpenAI"

web/lib/opal/src/components/cards/select-card/SelectCard.stories.tsx

@@ -21,8 +21,7 @@ const withTooltipProvider: Decorator = (Story) => (
 );
 
 const STATES = ["empty", "filled", "selected"] as const;
-const PADDING_VARIANTS = ["fit", "2xs", "xs", "sm", "md", "lg"] as const;
-const ROUNDING_VARIANTS = ["xs", "sm", "md", "lg"] as const;
+const SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
 
 const meta = {
   title: "opal/components/SelectCard",
@@ -45,7 +44,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   render: () => (
     <div className="w-96">
-      <SelectCard state="empty">
+      <SelectCard variant="select-card" state="empty">
         <div className="p-2">
           <Content
             sizePreset="main-ui"
@@ -64,7 +63,7 @@ export const AllStates: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
       {STATES.map((state) => (
-        <SelectCard key={state} state={state}>
+        <SelectCard key={state} variant="select-card" state={state}>
           <div className="p-2">
             <Content
               sizePreset="main-ui"
@@ -83,7 +82,11 @@ export const AllStates: Story = {
 export const Clickable: Story = {
   render: () => (
     <div className="w-96">
-      <SelectCard state="empty" onClick={() => alert("Card clicked")}>
+      <SelectCard
+        variant="select-card"
+        state="empty"
+        onClick={() => alert("Card clicked")}
+      >
         <div className="p-2">
           <Content
             sizePreset="main-ui"
@@ -102,7 +105,7 @@ export const WithActions: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-[28rem]">
       {/* Disconnected */}
-      <SelectCard state="empty" onClick={() => {}}>
+      <SelectCard variant="select-card" state="empty" onClick={() => {}}>
         <div className="flex flex-row items-stretch w-full">
           <div className="flex-1 p-2">
             <Content
@@ -122,7 +125,7 @@ export const WithActions: Story = {
       </SelectCard>
 
       {/* Connected with foldable */}
-      <SelectCard state="filled">
+      <SelectCard variant="select-card" state="filled">
         <div className="flex flex-row items-stretch w-full">
           <div className="flex-1 p-2">
             <Content
@@ -160,7 +163,7 @@ export const WithActions: Story = {
       </SelectCard>
 
       {/* Selected */}
-      <SelectCard state="selected">
+      <SelectCard variant="select-card" state="selected">
         <div className="flex flex-row items-stretch w-full">
           <div className="flex-1 p-2">
             <Content
@@ -200,17 +203,22 @@ export const WithActions: Story = {
   ),
 };
 
-export const PaddingVariants: Story = {
+export const SizeVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
-      {PADDING_VARIANTS.map((padding) => (
-        <SelectCard key={padding} state="filled" padding={padding}>
+      {SIZE_VARIANTS.map((size) => (
+        <SelectCard
+          key={size}
+          variant="select-card"
+          state="filled"
+          sizeVariant={size}
+        >
           <Content
             sizePreset="main-ui"
             variant="section"
             icon={SvgGlobe}
-            title={`paddingVariant: ${padding}`}
-            description="Shows padding differences."
+            title={`sizeVariant: ${size}`}
+            description="Shows padding and rounding differences."
           />
         </SelectCard>
       ))}
@@ -218,18 +226,20 @@ export const PaddingVariants: Story = {
   ),
 };
 
-export const RoundingVariants: Story = {
+export const SelectHeavyVariant: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
-      {ROUNDING_VARIANTS.map((rounding) => (
-        <SelectCard key={rounding} state="filled" rounding={rounding}>
-          <Content
-            sizePreset="main-ui"
-            variant="section"
-            icon={SvgGlobe}
-            title={`roundingVariant: ${rounding}`}
-            description="Shows rounding differences."
-          />
+      {STATES.map((state) => (
+        <SelectCard key={state} variant="select-heavy" state={state}>
+          <div className="p-2">
+            <Content
+              sizePreset="main-ui"
+              variant="section"
+              icon={SvgGlobe}
+              title={`select-heavy / ${state}`}
+              description="For comparison with select-card variant."
+            />
+          </div>
         </SelectCard>
       ))}
     </div>

web/lib/opal/src/components/cards/select-card/components.tsx

@@ -1,6 +1,6 @@
 import "@opal/components/cards/select-card/styles.css";
-import type { PaddingVariants, RoundingVariants } from "@opal/types";
-import { cardPaddingVariants, cardRoundingVariants } from "@opal/shared";
+import type { ContainerSizeVariants } from "@opal/types";
+import { containerSizeVariants } from "@opal/shared";
 import { cn } from "@opal/utils";
 import { Interactive, type InteractiveStatefulProps } from "@opal/core";
 
@@ -8,36 +8,23 @@ import { Interactive, type InteractiveStatefulProps } from "@opal/core";
 // Types
 // ---------------------------------------------------------------------------
 
-type SelectCardProps = Omit<InteractiveStatefulProps, "variant"> & {
+type SelectCardProps = InteractiveStatefulProps & {
   /**
-   * Padding preset.
+   * Size preset — controls padding and border-radius.
    *
-   * | Value   | Class   |
-   * |---------|---------|
-   * | `"lg"`  | `p-6`   |
-   * | `"md"`  | `p-4`   |
-   * | `"sm"`  | `p-2`   |
-   * | `"xs"`  | `p-1`   |
-   * | `"2xs"` | `p-0.5` |
-   * | `"fit"` | `p-0`   |
+   * Padding comes from the shared size scale. Rounding follows the same
+   * mapping as `Card` / `Button` / `Interactive.Container`:
    *
-   * @default "md"
+   * | Size       | Rounding     |
+   * |------------|--------------|
+   * | `lg`       | `rounded-16` |
+   * | `md`–`sm`  | `rounded-12` |
+   * | `xs`–`2xs` | `rounded-08` |
+   * | `fit`      | `rounded-16` |
+   *
+   * @default "lg"
    */
-  padding?: PaddingVariants;
-
-  /**
-   * Border-radius preset.
-   *
-   * | Value  | Class        |
-   * |--------|--------------|
-   * | `"xs"` | `rounded-04` |
-   * | `"sm"` | `rounded-08` |
-   * | `"md"` | `rounded-12` |
-   * | `"lg"` | `rounded-16` |
-   *
-   * @default "md"
-   */
-  rounding?: RoundingVariants;
+  sizeVariant?: ContainerSizeVariants;
 
   /** Ref forwarded to the root `<div>`. */
   ref?: React.Ref<HTMLDivElement>;
@@ -45,6 +32,19 @@ type SelectCardProps = Omit<InteractiveStatefulProps, "variant"> & {
   children?: React.ReactNode;
 };
 
+// ---------------------------------------------------------------------------
+// Rounding
+// ---------------------------------------------------------------------------
+
+const roundingForSize: Record<ContainerSizeVariants, string> = {
+  lg: "rounded-16",
+  md: "rounded-12",
+  sm: "rounded-12",
+  xs: "rounded-08",
+  "2xs": "rounded-08",
+  fit: "rounded-16",
+};
+
 // ---------------------------------------------------------------------------
 // SelectCard
 // ---------------------------------------------------------------------------
@@ -61,7 +61,7 @@ type SelectCardProps = Omit<InteractiveStatefulProps, "variant"> & {
  *
  * @example
  * ```tsx
- * <SelectCard state="selected" onClick={handleClick}>
+ * <SelectCard variant="select-card" state="selected" onClick={handleClick}>
  *   <ContentAction
  *     icon={SvgGlobe}
  *     title="Google"
@@ -72,17 +72,16 @@ type SelectCardProps = Omit<InteractiveStatefulProps, "variant"> & {
  * ```
  */
 function SelectCard({
-  padding: paddingProp = "md",
-  rounding: roundingProp = "md",
+  sizeVariant = "lg",
   ref,
   children,
   ...statefulProps
 }: SelectCardProps) {
-  const padding = cardPaddingVariants[paddingProp];
-  const rounding = cardRoundingVariants[roundingProp];
+  const { padding } = containerSizeVariants[sizeVariant];
+  const rounding = roundingForSize[sizeVariant];
 
   return (
-    <Interactive.Stateful {...statefulProps} variant="select-card">
+    <Interactive.Stateful {...statefulProps}>
       <div ref={ref} className={cn("opal-select-card", padding, rounding)}>
         {children}
       </div>

web/lib/opal/src/shared.ts

@@ -11,8 +11,6 @@ import type {
   OverridableExtremaSizeVariants,
   ContainerSizeVariants,
   ExtremaSizeVariants,
-  PaddingVariants,
-  RoundingVariants,
 } from "@opal/types";
 
 /**
@@ -90,40 +88,12 @@ const heightVariants: Record<ExtremaSizeVariants, string> = {
   full: "h-full",
 } as const;
 
-// ---------------------------------------------------------------------------
-// Card Variants
-//
-// Shared padding and rounding scales for card components (Card, SelectCard).
-//
-// Consumers:
-//   - Card          (paddingVariant, roundingVariant)
-//   - SelectCard    (paddingVariant, roundingVariant)
-// ---------------------------------------------------------------------------
-
-const cardPaddingVariants: Record<PaddingVariants, string> = {
-  lg: "p-6",
-  md: "p-4",
-  sm: "p-2",
-  xs: "p-1",
-  "2xs": "p-0.5",
-  fit: "p-0",
-};
-
-const cardRoundingVariants: Record<RoundingVariants, string> = {
-  lg: "rounded-16",
-  md: "rounded-12",
-  sm: "rounded-08",
-  xs: "rounded-04",
-};
-
 export {
   type ExtremaSizeVariants,
   type ContainerSizeVariants,
   type OverridableExtremaSizeVariants,
   type SizeVariants,
   containerSizeVariants,
-  cardPaddingVariants,
-  cardRoundingVariants,
   widthVariants,
   heightVariants,
 };

web/src/app/admin/billing/PlansView.tsx

@@ -7,7 +7,6 @@ import {
   SvgGlobe,
   SvgHardDrive,
   SvgHeadsetMic,
-  SvgHookNodes,
   SvgKey,
   SvgLock,
   SvgPaintBrush,
@@ -64,7 +63,6 @@ const BUSINESS_FEATURES: PlanFeature[] = [
   { icon: SvgKey, text: "Service Account API Keys" },
   { icon: SvgHardDrive, text: "Self-hosting (Optional)" },
   { icon: SvgPaintBrush, text: "Custom Theming" },
-  { icon: SvgHookNodes, text: "Hook Extensions" },
 ];
 
 const ENTERPRISE_FEATURES: PlanFeature[] = [

web/src/refresh-pages/admin/ChatPreferencesPage.tsx

@@ -1008,7 +1008,7 @@ function ChatPreferencesForm() {
                       )}
                     </Text>
                   </Section>
-                  <OpalCard background="none" border="solid" padding="sm">
+                  <OpalCard backgroundVariant="none" borderVariant="solid">
                     <Content
                       sizePreset="main-ui"
                       icon={SvgAlertCircle}

web/src/refresh-pages/admin/CodeInterpreterPage/index.tsx

@@ -112,7 +112,7 @@ export default function CodeInterpreterPage() {
       <SettingsLayouts.Body>
         {isEnabled || isLoading ? (
           <Hoverable.Root group="code-interpreter/Card">
-            <SelectCard state="filled" padding="sm" rounding="lg">
+            <SelectCard variant="select-card" state="filled" sizeVariant="lg">
               <CardHeaderLayout
                 sizePreset="main-ui"
                 variant="section"
@@ -157,9 +157,9 @@ export default function CodeInterpreterPage() {
           </Hoverable.Root>
         ) : (
           <SelectCard
+            variant="select-card"
             state="empty"
-            padding="sm"
-            rounding="lg"
+            sizeVariant="lg"
             onClick={() => handleToggle(true)}
           >
             <CardHeaderLayout

web/src/refresh-pages/admin/ImageGenerationPage/ImageGenerationContent.tsx

@@ -248,9 +248,9 @@ export default function ImageGenerationContent() {
                   group="image-gen/ProviderCard"
                 >
                   <SelectCard
+                    variant="select-card"
                     state={STATUS_TO_STATE[status]}
-                    padding="sm"
-                    rounding="lg"
+                    sizeVariant="lg"
                     aria-label={`image-gen-provider-${provider.image_provider_id}`}
                     onClick={
                       isDisconnected

web/src/refresh-pages/admin/LLMConfigurationPage.tsx

@@ -212,9 +212,9 @@ function ExistingProviderCard({
 
       <Hoverable.Root group="ExistingProviderCard">
         <SelectCard
+          variant="select-card"
           state="filled"
-          padding="sm"
-          rounding="lg"
+          sizeVariant="lg"
           onClick={() => setIsOpen(true)}
         >
           <CardHeaderLayout
@@ -287,9 +287,9 @@ function NewProviderCard({
 
   return (
     <SelectCard
+      variant="select-card"
       state="empty"
-      padding="sm"
-      rounding="lg"
+      sizeVariant="lg"
       onClick={() => setIsOpen(true)}
     >
       <CardHeaderLayout
@@ -331,9 +331,9 @@ function NewCustomProviderCard({
 
   return (
     <SelectCard
+      variant="select-card"
       state="empty"
-      padding="sm"
-      rounding="lg"
+      sizeVariant="lg"
       onClick={() => setIsOpen(true)}
     >
       <CardHeaderLayout

web/src/refresh-pages/admin/WebSearchPage/index.tsx

@@ -264,9 +264,9 @@ function ProviderCard({
   return (
     <Hoverable.Root group="web-search/ProviderCard">
       <SelectCard
+        variant="select-card"
         state={STATUS_TO_STATE[status]}
-        padding="sm"
-        rounding="lg"
+        sizeVariant="lg"
         onClick={
           isDisconnected && onConnect
             ? onConnect

web/src/sections/admin/AdminListHeader.tsx

@@ -67,7 +67,7 @@ export default function AdminListHeader({
 
   if (!hasItems) {
     return (
-      <Card rounding="lg" border="solid">
+      <Card paddingVariant="md" roundingVariant="lg" borderVariant="solid">
         <div className="flex flex-row items-center justify-between gap-3">
           <Content
             title={emptyStateText}

web/src/sections/admin/ProviderCard.tsx

@@ -86,9 +86,9 @@ export default function ProviderCard({
 
   return (
     <SelectCard
+      variant="select-card"
       state={STATUS_TO_STATE[status]}
-      padding="sm"
-      rounding="lg"
+      sizeVariant="lg"
       aria-label={ariaLabel}
       onClick={isDisconnected && onConnect ? onConnect : undefined}
     >

web/src/sections/modals/llmConfig/BedrockModal.tsx

@@ -225,7 +225,11 @@ function BedrockModalInternals({
       </FieldWrapper>
 
       {authMethod === AUTH_METHOD_ACCESS_KEY && (
-        <Card background="light" border="none" padding="sm">
+        <Card
+          backgroundVariant="light"
+          borderVariant="none"
+          paddingVariant="sm"
+        >
           <Section gap={1}>
             <InputLayouts.Vertical
               name={FIELD_AWS_ACCESS_KEY_ID}
@@ -251,7 +255,7 @@ function BedrockModalInternals({
 
       {authMethod === AUTH_METHOD_IAM && (
         <FieldWrapper>
-          <Card background="none" border="solid" padding="sm">
+          <Card backgroundVariant="none" borderVariant="solid">
             <Content
               icon={SvgAlertCircle}
               title="Onyx will use the IAM role attached to the environment it’s running in to authenticate."
@@ -263,7 +267,11 @@ function BedrockModalInternals({
       )}
 
       {authMethod === AUTH_METHOD_LONG_TERM_API_KEY && (
-        <Card background="light" border="none" padding="sm">
+        <Card
+          backgroundVariant="light"
+          borderVariant="none"
+          paddingVariant="sm"
+        >
           <Section gap={0.5}>
             <InputLayouts.Vertical
               name={FIELD_AWS_BEARER_TOKEN_BEDROCK}

web/src/sections/modals/llmConfig/CustomModal.tsx

@@ -166,7 +166,7 @@ function ModelConfigurationList({ formikProps }: ModelConfigurationListProps) {
           ))}
         </div>
       ) : (
-        <EmptyMessageCard title="No models added yet." padding="sm" />
+        <EmptyMessageCard title="No models added yet." />
       )}
 
       <Button
@@ -393,7 +393,7 @@ export default function CustomModal({
               />
             </FieldWrapper>
 
-            <Card padding="sm">
+            <Card>
               <ModelConfigurationList formikProps={formikProps as any} />
             </Card>
           </Section>

web/src/sections/modals/llmConfig/OllamaModal.tsx

@@ -140,7 +140,7 @@ function OllamaModalInternals({
       isTesting={isTesting}
       isSubmitting={formikProps.isSubmitting}
     >
-      <Card background="light" border="none" padding="sm">
+      <Card backgroundVariant="light" borderVariant="none" paddingVariant="sm">
         <Tabs defaultValue={defaultTab}>
           <Tabs.List>
             <Tabs.Trigger value={TAB_SELF_HOSTED}>

web/src/sections/modals/llmConfig/shared.tsx

@@ -250,7 +250,11 @@ export function ModelsAccessField<T extends BaseLLMFormValues>({
       </FieldWrapper>
 
       {!isPublic && (
-        <Card background="light" border="none" padding="sm">
+        <Card
+          backgroundVariant="light"
+          borderVariant="none"
+          paddingVariant="sm"
+        >
           <Section gap={0.5}>
             <InputComboBox
               placeholder="Add groups and agents"
@@ -262,7 +266,7 @@ export function ModelsAccessField<T extends BaseLLMFormValues>({
               leftSearchIcon
             />
 
-            <Card background="heavy" border="none" padding="sm">
+            <Card backgroundVariant="heavy" borderVariant="none">
               <ContentAction
                 icon={SvgUserManage}
                 title="Admin"
@@ -286,7 +290,7 @@ export function ModelsAccessField<T extends BaseLLMFormValues>({
                   const memberCount = group?.users.length ?? 0;
                   return (
                     <div key={`group-${id}`} className="min-w-0">
-                      <Card background="heavy" border="none" padding="sm">
+                      <Card backgroundVariant="heavy" borderVariant="none">
                         <ContentAction
                           icon={SvgUsers}
                           title={group?.name ?? `Group ${id}`}
@@ -321,7 +325,7 @@ export function ModelsAccessField<T extends BaseLLMFormValues>({
                   const agent = agentMap.get(id);
                   return (
                     <div key={`agent-${id}`} className="min-w-0">
-                      <Card background="heavy" border="none" padding="sm">
+                      <Card backgroundVariant="heavy" borderVariant="none">
                         <ContentAction
                           icon={
                             agent
@@ -448,7 +452,7 @@ export function ModelsField<T extends BaseLLMFormValues>({
   const visibleModels = modelConfigurations.filter((m) => m.is_visible);
 
   return (
-    <Card background="light" border="none" padding="sm">
+    <Card backgroundVariant="light" borderVariant="none" paddingVariant="sm">
       <Section gap={0.5}>
         <InputLayouts.Horizontal
           title="Models"
@@ -487,7 +491,7 @@ export function ModelsField<T extends BaseLLMFormValues>({
         </InputLayouts.Horizontal>
 
         {modelConfigurations.length === 0 ? (
-          <EmptyMessageCard title="No models available." padding="sm" />
+          <EmptyMessageCard title="No models available." />
         ) : (
           <Section gap={0.25}>
             {isAutoMode