chore(opensearch): Increase DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES to 500, disable profiling by default (#9844)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

backend/onyx/configs/app_configs.py

@@ -286,11 +286,9 @@ 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. 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.
+# unknown right now. Defaults to True.
 OPENSEARCH_PROFILING_DISABLED = (
-    os.environ.get("OPENSEARCH_PROFILING_DISABLED", "").lower() == "true"
+    os.environ.get("OPENSEARCH_PROFILING_DISABLED", "true").lower() == "true"
 )
 # Whether to disable match highlights for OpenSearch. Defaults to True for now
 # as we investigate query performance.
@@ -942,9 +940,20 @@ 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/db/api_key.py

@@ -4,7 +4,6 @@ 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
@@ -55,7 +54,6 @@ 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,7 +13,6 @@ 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
@@ -98,11 +97,6 @@ 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,7 +8,6 @@ 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
@@ -47,7 +46,6 @@ 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,7 +229,9 @@ 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)).all()
+    return db_session.scalars(
+        select(Memory).where(Memory.user_id == user_id).order_by(Memory.id.desc())
+    ).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 100 for now. Initially this defaulted to 750 but we were seeing
-# poor search performance.
+# 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.
 DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES = int(
-    os.environ.get("DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES", 100)
+    os.environ.get("DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES", 500)
 )
 
 # Number of vectors to examine to decide the top k neighbors for the HNSW

backend/onyx/document_index/vespa/chunk_retrieval.py

@@ -20,6 +20,7 @@ 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
@@ -335,6 +336,11 @@ 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
@@ -343,6 +349,9 @@ 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,33 +1,114 @@
 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
 
 
-# TODO(@Bo-Onyx): define payload and response fields
+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.",
+    )
+
+
 class DocumentIngestionPayload(BaseModel):
-    pass
+    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."
+    )
 
 
 class DocumentIngestionResponse(BaseModel):
-    pass
+    # 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.",
+    )
 
 
 class DocumentIngestionSpec(HookPointSpec):
-    """Hook point that runs during document ingestion.
+    """Hook point that runs on every document before it enters the indexing pipeline.
 
-    # TODO(@Bo-Onyx): define call site, input/output schema, and timeout budget.
+    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
     """
 
     hook_point = HookPoint.DOCUMENT_INGESTION
     display_name = "Document Ingestion"
-    description = "Runs during document ingestion. Allows filtering or transforming documents before indexing."
+    description = (
+        "Runs on every document before it enters the indexing pipeline. "
+        "Allows filtering, rewriting, or dropping documents."
+    )
     default_timeout_seconds = 30.0
     fail_hard_description = "The document will not be indexed."
     default_fail_strategy = HookFailStrategy.HARD
-    # TODO(Bo-Onyx): update later
-    docs_url = "https://docs.google.com/document/d/1pGhB8Wcnhhj8rS4baEJL6CX05yFhuIDNk1gbBRiWu94/edit?tab=t.ue263ual5vdi"
+    docs_url = "https://docs.onyx.app/admins/advanced_configs/hook_extensions#document-ingestion"
 
     payload_model = DocumentIngestionPayload
     response_model = DocumentIngestionResponse

backend/onyx/hooks/points/query_processing.py

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

backend/onyx/indexing/indexing_pipeline.py

@@ -33,6 +33,7 @@ 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
@@ -47,6 +48,13 @@ 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
@@ -297,6 +305,7 @@ 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,
@@ -310,6 +319,7 @@ 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,
@@ -785,6 +795,132 @@ 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(
     *,
@@ -794,6 +930,7 @@ 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,
@@ -818,6 +955,7 @@ 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))
@@ -1005,6 +1143,7 @@ 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,6 +147,7 @@ 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),
@@ -191,10 +192,7 @@ class UserInfo(BaseModel):
                 role=user.personal_role or "",
                 use_memories=user.use_memories,
                 enable_memory_tool=user.enable_memory_tool,
-                memories=[
-                    MemoryItem(id=memory.id, content=memory.memory_text)
-                    for memory in (user.memories or [])
-                ],
+                memories=memories or [],
                 user_preferences=user.user_preferences or "",
             ),
         )

backend/onyx/server/manage/users.py

@@ -57,6 +57,7 @@ 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
@@ -823,6 +824,11 @@ 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,
@@ -833,6 +839,7 @@ def verify_user_logged_in(
             new_tenant=new_tenant,
             invitation=tenant_invitation,
         ),
+        memories=memories,
     )
 
     return user_info
@@ -930,7 +937,8 @@ def update_user_personalization_api(
         else user.enable_memory_tool
     )
     existing_memories = [
-        MemoryItem(id=memory.id, content=memory.memory_text) for memory in user.memories
+        MemoryItem(id=memory.id, content=memory.memory_text)
+        for memory in get_memories_for_user(user.id, db_session)
     ]
     new_memories = (
         request.memories if request.memories is not None else existing_memories

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

@@ -2,6 +2,7 @@ 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
 
@@ -12,8 +13,13 @@ 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
@@ -223,3 +229,148 @@ 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,6 +231,23 @@ 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} backgroundVariant={bg} borderVariant="solid">
+        <Card key={bg} background={bg} border="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} borderVariant={border}>
+        <Card key={border} border={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} paddingVariant={padding} borderVariant="solid">
+        <Card key={padding} padding={padding} border="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} roundingVariant={rounding} borderVariant="solid">
+        <Card key={rounding} rounding={rounding} border="solid">
           <p>roundingVariant: {rounding}</p>
         </Card>
       ))}
@@ -84,9 +84,9 @@ export const AllCombinations: Story = {
               BORDER_VARIANTS.map((border) => (
                 <Card
                   key={`${padding}-${bg}-${border}`}
-                  paddingVariant={padding}
-                  backgroundVariant={bg}
-                  borderVariant={border}
+                  padding={padding}
+                  background={bg}
+                  border={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:
 
-| `paddingVariant` | Class   |
-|------------------|---------|
-| `"lg"`           | `p-6`   |
-| `"md"`           | `p-4`   |
-| `"sm"`           | `p-2`   |
-| `"xs"`           | `p-1`   |
-| `"2xs"`          | `p-0.5` |
-| `"fit"`          | `p-0`   |
+| `padding` | Class   |
+|-----------|---------|
+| `"lg"`    | `p-6`   |
+| `"md"`    | `p-4`   |
+| `"sm"`    | `p-2`   |
+| `"xs"`    | `p-1`   |
+| `"2xs"`   | `p-0.5` |
+| `"fit"`   | `p-0`   |
 
-| `roundingVariant` | Class        |
-|-------------------|--------------|
-| `"xs"`            | `rounded-04` |
-| `"sm"`            | `rounded-08` |
-| `"md"`            | `rounded-12` |
-| `"lg"`            | `rounded-16` |
+| `rounding` | Class        |
+|------------|--------------|
+| `"xs"`     | `rounded-04` |
+| `"sm"`     | `rounded-08` |
+| `"md"`     | `rounded-12` |
+| `"lg"`     | `rounded-16` |
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `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 |
+| `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 |
 | `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 paddingVariant="lg" roundingVariant="lg" borderVariant="solid">
+<Card padding="lg" rounding="lg" border="solid">
   <p>Spacious card</p>
 </Card>
 
 // Compact card with solid border
-<Card paddingVariant="xs" roundingVariant="sm" borderVariant="solid">
+<Card padding="xs" rounding="sm" border="solid">
   <p>Compact card</p>
 </Card>
 
 // Empty state card
-<Card backgroundVariant="none" borderVariant="dashed">
+<Card background="none" border="dashed">
   <p>No items yet</p>
 </Card>
 ```

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

@@ -1,5 +1,6 @@
 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";
 
 // ---------------------------------------------------------------------------
@@ -22,9 +23,9 @@ type CardProps = {
    * | `"2xs"` | `p-0.5` |
    * | `"fit"` | `p-0`   |
    *
-   * @default "sm"
+   * @default "md"
    */
-  paddingVariant?: PaddingVariants;
+  padding?: PaddingVariants;
 
   /**
    * Border-radius preset.
@@ -38,7 +39,7 @@ type CardProps = {
    *
    * @default "md"
    */
-  roundingVariant?: RoundingVariants;
+  rounding?: RoundingVariants;
 
   /**
    * Background fill intensity.
@@ -48,7 +49,7 @@ type CardProps = {
    *
    * @default "light"
    */
-  backgroundVariant?: BackgroundVariant;
+  background?: BackgroundVariant;
 
   /**
    * Border style.
@@ -58,7 +59,7 @@ type CardProps = {
    *
    * @default "none"
    */
-  borderVariant?: BorderVariant;
+  border?: BorderVariant;
 
   /** Ref forwarded to the root `<div>`. */
   ref?: React.Ref<HTMLDivElement>;
@@ -66,47 +67,27 @@ 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({
-  paddingVariant = "sm",
-  roundingVariant = "md",
-  backgroundVariant = "light",
-  borderVariant = "none",
+  padding: paddingProp = "md",
+  rounding: roundingProp = "md",
+  background = "light",
+  border = "none",
   ref,
   children,
 }: CardProps) {
-  const padding = paddingForVariant[paddingVariant];
-  const rounding = roundingForVariant[roundingVariant];
+  const padding = cardPaddingVariants[paddingProp];
+  const rounding = cardRoundingVariants[roundingProp];
 
   return (
     <div
       ref={ref}
       className={cn("opal-card", padding, rounding)}
-      data-background={backgroundVariant}
-      data-border={borderVariant}
+      data-background={background}
+      data-border={border}
     >
       {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 SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
+const PADDING_VARIANTS = ["fit", "2xs", "xs", "sm", "md", "lg"] as const;
 
 const meta: Meta<typeof EmptyMessageCard> = {
   title: "opal/components/EmptyMessageCard",
@@ -26,14 +26,14 @@ export const WithCustomIcon: Story = {
   },
 };
 
-export const SizeVariants: Story = {
+export const PaddingVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
-      {SIZE_VARIANTS.map((size) => (
+      {PADDING_VARIANTS.map((padding) => (
         <EmptyMessageCard
-          key={size}
-          sizeVariant={size}
-          title={`sizeVariant: ${size}`}
+          key={padding}
+          padding={padding}
+          title={`padding: ${padding}`}
         />
       ))}
     </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)                  |
-| `paddingVariant`  | `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)  |
+| `padding` | `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 paddingVariant="xs" icon={SvgFileText} title="No documents available." />
+<EmptyMessageCard padding="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. */
-  paddingVariant?: PaddingVariants;
+  /** Padding preset for the card. @default "md" */
+  padding?: PaddingVariants;
 
   /** Ref forwarded to the root Card div. */
   ref?: React.Ref<HTMLDivElement>;
@@ -28,15 +28,16 @@ type EmptyMessageCardProps = {
 function EmptyMessageCard({
   icon = SvgEmpty,
   title,
-  paddingVariant = "sm",
+  padding = "md",
   ref,
 }: EmptyMessageCardProps) {
   return (
     <Card
       ref={ref}
-      backgroundVariant="none"
-      borderVariant="dashed"
-      paddingVariant={paddingVariant}
+      background="none"
+      border="dashed"
+      padding={padding}
+      rounding="md"
     >
       <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.
+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.
 
 ## 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`. The relationship mirrors `Button` (stateless) vs `SelectButton` (stateful).
+`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.
 
 ## 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 (one notch larger than buttons) and don't need Container's height/min-width.
+- SelectCard renders a `<div>` (not `Interactive.Container`) — cards have their own rounding scale 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, state, interaction, disabled, onClick
-  └─ div.opal-select-card        <- padding, rounding, border, overflow
+Interactive.Stateful (variant="select-card")  <- state, interaction, disabled, onClick
+  └─ div.opal-select-card                    <- padding, rounding, border, overflow
        └─ children (composable)
 ```
 
@@ -34,28 +34,36 @@ The `Interactive.Stateful` Slot merges onto the div, producing a single DOM elem
 
 ## Props
 
-Inherits **all** props from `InteractiveStatefulProps` (variant, state, interaction, onClick, href, etc.) plus:
+Inherits **all** props from `InteractiveStatefulProps` (except `variant`, which is hardcoded to `select-card`) plus:
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `sizeVariant` | `ContainerSizeVariants` | `"lg"` | Controls padding and border-radius |
+| `padding` | `PaddingVariants` | `"sm"` | Padding preset |
+| `rounding` | `RoundingVariants` | `"lg"` | Border-radius preset |
 | `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
 
-Cards use a bumped-up rounding scale compared to buttons:
+| `rounding` | Class        |
+|------------|--------------|
+| `"xs"`     | `rounded-04` |
+| `"sm"`     | `rounded-08` |
+| `"md"`     | `rounded-12` |
+| `"lg"`     | `rounded-16` |
 
-| 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 colors (`select-card` variant)
 
 | State | Rest background | Rest foreground |
 |---|---|---|
@@ -82,7 +90,7 @@ All background and foreground colors come from the Interactive.Stateful CSS, not
 import { SelectCard } from "@opal/components";
 import { CardHeaderLayout } from "@opal/layouts";
 
-<SelectCard variant="select-card" state="selected" onClick={handleClick}>
+<SelectCard state="selected" onClick={handleClick}>
   <CardHeaderLayout
     icon={SvgGlobe}
     title="Google"
@@ -100,7 +108,7 @@ import { CardHeaderLayout } from "@opal/layouts";
 ### Disconnected state (clickable)
 
 ```tsx
-<SelectCard variant="select-card" state="empty" onClick={handleConnect}>
+<SelectCard state="empty" onClick={handleConnect}>
   <CardHeaderLayout
     icon={SvgCloud}
     title="OpenAI"
@@ -115,7 +123,7 @@ import { CardHeaderLayout } from "@opal/layouts";
 ### With foldable hover-reveal
 
 ```tsx
-<SelectCard variant="select-card" state="filled">
+<SelectCard state="filled">
   <CardHeaderLayout
     icon={SvgCloud}
     title="OpenAI"

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

@@ -21,7 +21,8 @@ const withTooltipProvider: Decorator = (Story) => (
 );
 
 const STATES = ["empty", "filled", "selected"] as const;
-const SIZE_VARIANTS = ["lg", "md", "sm", "xs", "2xs", "fit"] as const;
+const PADDING_VARIANTS = ["fit", "2xs", "xs", "sm", "md", "lg"] as const;
+const ROUNDING_VARIANTS = ["xs", "sm", "md", "lg"] as const;
 
 const meta = {
   title: "opal/components/SelectCard",
@@ -44,7 +45,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   render: () => (
     <div className="w-96">
-      <SelectCard variant="select-card" state="empty">
+      <SelectCard state="empty">
         <div className="p-2">
           <Content
             sizePreset="main-ui"
@@ -63,7 +64,7 @@ export const AllStates: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
       {STATES.map((state) => (
-        <SelectCard key={state} variant="select-card" state={state}>
+        <SelectCard key={state} state={state}>
           <div className="p-2">
             <Content
               sizePreset="main-ui"
@@ -82,11 +83,7 @@ export const AllStates: Story = {
 export const Clickable: Story = {
   render: () => (
     <div className="w-96">
-      <SelectCard
-        variant="select-card"
-        state="empty"
-        onClick={() => alert("Card clicked")}
-      >
+      <SelectCard state="empty" onClick={() => alert("Card clicked")}>
         <div className="p-2">
           <Content
             sizePreset="main-ui"
@@ -105,7 +102,7 @@ export const WithActions: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-[28rem]">
       {/* Disconnected */}
-      <SelectCard variant="select-card" state="empty" onClick={() => {}}>
+      <SelectCard state="empty" onClick={() => {}}>
         <div className="flex flex-row items-stretch w-full">
           <div className="flex-1 p-2">
             <Content
@@ -125,7 +122,7 @@ export const WithActions: Story = {
       </SelectCard>
 
       {/* Connected with foldable */}
-      <SelectCard variant="select-card" state="filled">
+      <SelectCard state="filled">
         <div className="flex flex-row items-stretch w-full">
           <div className="flex-1 p-2">
             <Content
@@ -163,7 +160,7 @@ export const WithActions: Story = {
       </SelectCard>
 
       {/* Selected */}
-      <SelectCard variant="select-card" state="selected">
+      <SelectCard state="selected">
         <div className="flex flex-row items-stretch w-full">
           <div className="flex-1 p-2">
             <Content
@@ -203,22 +200,17 @@ export const WithActions: Story = {
   ),
 };
 
-export const SizeVariants: Story = {
+export const PaddingVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
-      {SIZE_VARIANTS.map((size) => (
-        <SelectCard
-          key={size}
-          variant="select-card"
-          state="filled"
-          sizeVariant={size}
-        >
+      {PADDING_VARIANTS.map((padding) => (
+        <SelectCard key={padding} state="filled" padding={padding}>
           <Content
             sizePreset="main-ui"
             variant="section"
             icon={SvgGlobe}
-            title={`sizeVariant: ${size}`}
-            description="Shows padding and rounding differences."
+            title={`paddingVariant: ${padding}`}
+            description="Shows padding differences."
           />
         </SelectCard>
       ))}
@@ -226,20 +218,18 @@ export const SizeVariants: Story = {
   ),
 };
 
-export const SelectHeavyVariant: Story = {
+export const RoundingVariants: Story = {
   render: () => (
     <div className="flex flex-col gap-4 w-96">
-      {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>
+      {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."
+          />
         </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 { ContainerSizeVariants } from "@opal/types";
-import { containerSizeVariants } from "@opal/shared";
+import type { PaddingVariants, RoundingVariants } from "@opal/types";
+import { cardPaddingVariants, cardRoundingVariants } from "@opal/shared";
 import { cn } from "@opal/utils";
 import { Interactive, type InteractiveStatefulProps } from "@opal/core";
 
@@ -8,23 +8,36 @@ import { Interactive, type InteractiveStatefulProps } from "@opal/core";
 // Types
 // ---------------------------------------------------------------------------
 
-type SelectCardProps = InteractiveStatefulProps & {
+type SelectCardProps = Omit<InteractiveStatefulProps, "variant"> & {
   /**
-   * Size preset — controls padding and border-radius.
+   * Padding preset.
    *
-   * Padding comes from the shared size scale. Rounding follows the same
-   * mapping as `Card` / `Button` / `Interactive.Container`:
+   * | Value   | Class   |
+   * |---------|---------|
+   * | `"lg"`  | `p-6`   |
+   * | `"md"`  | `p-4`   |
+   * | `"sm"`  | `p-2`   |
+   * | `"xs"`  | `p-1`   |
+   * | `"2xs"` | `p-0.5` |
+   * | `"fit"` | `p-0`   |
    *
-   * | Size       | Rounding     |
-   * |------------|--------------|
-   * | `lg`       | `rounded-16` |
-   * | `md`–`sm`  | `rounded-12` |
-   * | `xs`–`2xs` | `rounded-08` |
-   * | `fit`      | `rounded-16` |
-   *
-   * @default "lg"
+   * @default "md"
    */
-  sizeVariant?: ContainerSizeVariants;
+  padding?: PaddingVariants;
+
+  /**
+   * Border-radius preset.
+   *
+   * | Value  | Class        |
+   * |--------|--------------|
+   * | `"xs"` | `rounded-04` |
+   * | `"sm"` | `rounded-08` |
+   * | `"md"` | `rounded-12` |
+   * | `"lg"` | `rounded-16` |
+   *
+   * @default "md"
+   */
+  rounding?: RoundingVariants;
 
   /** Ref forwarded to the root `<div>`. */
   ref?: React.Ref<HTMLDivElement>;
@@ -32,19 +45,6 @@ type SelectCardProps = InteractiveStatefulProps & {
   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 @@ const roundingForSize: Record<ContainerSizeVariants, string> = {
  *
  * @example
  * ```tsx
- * <SelectCard variant="select-card" state="selected" onClick={handleClick}>
+ * <SelectCard state="selected" onClick={handleClick}>
  *   <ContentAction
  *     icon={SvgGlobe}
  *     title="Google"
@@ -72,16 +72,17 @@ const roundingForSize: Record<ContainerSizeVariants, string> = {
  * ```
  */
 function SelectCard({
-  sizeVariant = "lg",
+  padding: paddingProp = "md",
+  rounding: roundingProp = "md",
   ref,
   children,
   ...statefulProps
 }: SelectCardProps) {
-  const { padding } = containerSizeVariants[sizeVariant];
-  const rounding = roundingForSize[sizeVariant];
+  const padding = cardPaddingVariants[paddingProp];
+  const rounding = cardRoundingVariants[roundingProp];
 
   return (
-    <Interactive.Stateful {...statefulProps}>
+    <Interactive.Stateful {...statefulProps} variant="select-card">
       <div ref={ref} className={cn("opal-select-card", padding, rounding)}>
         {children}
       </div>

web/lib/opal/src/shared.ts

@@ -11,6 +11,8 @@ import type {
   OverridableExtremaSizeVariants,
   ContainerSizeVariants,
   ExtremaSizeVariants,
+  PaddingVariants,
+  RoundingVariants,
 } from "@opal/types";
 
 /**
@@ -88,12 +90,40 @@ 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,6 +7,7 @@ import {
   SvgGlobe,
   SvgHardDrive,
   SvgHeadsetMic,
+  SvgHookNodes,
   SvgKey,
   SvgLock,
   SvgPaintBrush,
@@ -63,6 +64,7 @@ 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 backgroundVariant="none" borderVariant="solid">
+                  <OpalCard background="none" border="solid" padding="sm">
                     <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 variant="select-card" state="filled" sizeVariant="lg">
+            <SelectCard state="filled" padding="sm" rounding="lg">
               <CardHeaderLayout
                 sizePreset="main-ui"
                 variant="section"
@@ -157,9 +157,9 @@ export default function CodeInterpreterPage() {
           </Hoverable.Root>
         ) : (
           <SelectCard
-            variant="select-card"
             state="empty"
-            sizeVariant="lg"
+            padding="sm"
+            rounding="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]}
-                    sizeVariant="lg"
+                    padding="sm"
+                    rounding="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"
-          sizeVariant="lg"
+          padding="sm"
+          rounding="lg"
           onClick={() => setIsOpen(true)}
         >
           <CardHeaderLayout
@@ -287,9 +287,9 @@ function NewProviderCard({
 
   return (
     <SelectCard
-      variant="select-card"
       state="empty"
-      sizeVariant="lg"
+      padding="sm"
+      rounding="lg"
       onClick={() => setIsOpen(true)}
     >
       <CardHeaderLayout
@@ -331,9 +331,9 @@ function NewCustomProviderCard({
 
   return (
     <SelectCard
-      variant="select-card"
       state="empty"
-      sizeVariant="lg"
+      padding="sm"
+      rounding="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]}
-        sizeVariant="lg"
+        padding="sm"
+        rounding="lg"
         onClick={
           isDisconnected && onConnect
             ? onConnect

web/src/sections/admin/AdminListHeader.tsx

@@ -67,7 +67,7 @@ export default function AdminListHeader({
 
   if (!hasItems) {
     return (
-      <Card paddingVariant="md" roundingVariant="lg" borderVariant="solid">
+      <Card rounding="lg" border="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]}
-      sizeVariant="lg"
+      padding="sm"
+      rounding="lg"
       aria-label={ariaLabel}
       onClick={isDisconnected && onConnect ? onConnect : undefined}
     >

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

@@ -225,11 +225,7 @@ function BedrockModalInternals({
       </FieldWrapper>
 
       {authMethod === AUTH_METHOD_ACCESS_KEY && (
-        <Card
-          backgroundVariant="light"
-          borderVariant="none"
-          paddingVariant="sm"
-        >
+        <Card background="light" border="none" padding="sm">
           <Section gap={1}>
             <InputLayouts.Vertical
               name={FIELD_AWS_ACCESS_KEY_ID}
@@ -255,7 +251,7 @@ function BedrockModalInternals({
 
       {authMethod === AUTH_METHOD_IAM && (
         <FieldWrapper>
-          <Card backgroundVariant="none" borderVariant="solid">
+          <Card background="none" border="solid" padding="sm">
             <Content
               icon={SvgAlertCircle}
               title="Onyx will use the IAM role attached to the environment it’s running in to authenticate."
@@ -267,11 +263,7 @@ function BedrockModalInternals({
       )}
 
       {authMethod === AUTH_METHOD_LONG_TERM_API_KEY && (
-        <Card
-          backgroundVariant="light"
-          borderVariant="none"
-          paddingVariant="sm"
-        >
+        <Card background="light" border="none" padding="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." />
+        <EmptyMessageCard title="No models added yet." padding="sm" />
       )}
 
       <Button
@@ -393,7 +393,7 @@ export default function CustomModal({
               />
             </FieldWrapper>
 
-            <Card>
+            <Card padding="sm">
               <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 backgroundVariant="light" borderVariant="none" paddingVariant="sm">
+      <Card background="light" border="none" padding="sm">
         <Tabs defaultValue={defaultTab}>
           <Tabs.List>
             <Tabs.Trigger value={TAB_SELF_HOSTED}>

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

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