dry run

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/deployment.yml

@@ -455,7 +455,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -529,7 +529,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -607,7 +607,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -668,7 +668,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -750,7 +750,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -836,7 +836,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -894,7 +894,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -967,7 +967,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -1044,7 +1044,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -1105,7 +1105,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
           flavor: |
@@ -1178,7 +1178,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
           flavor: |
@@ -1256,7 +1256,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
           flavor: |
@@ -1317,7 +1317,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -1397,7 +1397,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |
@@ -1480,7 +1480,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ needs.determine-builds.outputs.is-test-run == 'true' && env.RUNS_ON_ECR_CACHE || env.REGISTRY_IMAGE }}
           flavor: |

.github/workflows/pr-desktop-build.yml

@@ -105,7 +105,7 @@ jobs:
 
       - name: Upload build artifacts
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: desktop-build-${{ matrix.platform }}-${{ github.run_id }}
           path: |

.github/workflows/pr-external-dependency-unit-tests.yml

@@ -174,7 +174,7 @@ jobs:
 
       - name: Upload Docker logs
         if: failure()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-logs-${{ matrix.test-dir }}
           path: docker-logs/

.github/workflows/pr-golang-tests.yml

@@ -25,7 +25,7 @@ jobs:
     outputs:
       modules: ${{ steps.set-modules.outputs.modules }}
     steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
           persist-credentials: false
       - id: set-modules
@@ -39,7 +39,7 @@ jobs:
       matrix:
         modules: ${{ fromJSON(needs.detect-modules.outputs.modules) }}
     steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # ratchet:actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           persist-credentials: false
       - uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # zizmor: ignore[cache-poisoning]

.github/workflows/pr-integration-tests.yml

@@ -466,7 +466,7 @@ jobs:
 
       - name: Upload logs
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-all-logs-${{ matrix.edition }}-${{ matrix.test-dir.name }}
           path: ${{ github.workspace }}/docker-compose.log
@@ -587,7 +587,7 @@ jobs:
 
       - name: Upload logs (onyx-lite)
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-all-logs-onyx-lite
           path: ${{ github.workspace }}/docker-compose-onyx-lite.log
@@ -725,7 +725,7 @@ jobs:
 
       - name: Upload logs (multi-tenant)
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-all-logs-multitenant
           path: ${{ github.workspace }}/docker-compose-multitenant.log

.github/workflows/pr-jest-tests.yml

@@ -44,7 +44,7 @@ jobs:
 
       - name: Upload coverage reports
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: jest-coverage-${{ github.run_id }}
           path: ./web/coverage

.github/workflows/pr-playwright-tests.yml

@@ -445,7 +445,7 @@ jobs:
         run: |
           npx playwright test --project ${PROJECT}
 
-      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         if: always()
         with:
           # Includes test results and trace.zip files
@@ -454,7 +454,7 @@ jobs:
           retention-days: 30
 
       - name: Upload screenshots
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         if: always()
         with:
           name: playwright-screenshots-${{ matrix.project }}-${{ github.run_id }}
@@ -534,7 +534,7 @@ jobs:
             "s3://${PLAYWRIGHT_S3_BUCKET}/reports/pr-${PR_NUMBER}/${RUN_ID}/${PROJECT}/"
 
       - name: Upload visual diff summary
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         if: always()
         with:
           name: screenshot-diff-summary-${{ matrix.project }}
@@ -543,7 +543,7 @@ jobs:
           retention-days: 5
 
       - name: Upload visual diff report artifact
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         if: always()
         with:
           name: screenshot-diff-report-${{ matrix.project }}-${{ github.run_id }}
@@ -590,7 +590,7 @@ jobs:
 
       - name: Upload logs
         if: success() || failure()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-logs-${{ matrix.project }}-${{ github.run_id }}
           path: ${{ github.workspace }}/docker-compose.log
@@ -674,7 +674,7 @@ jobs:
         working-directory: ./web
         run: npx playwright test --project lite
 
-      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         if: always()
         with:
           name: playwright-test-results-lite-${{ github.run_id }}
@@ -692,7 +692,7 @@ jobs:
 
       - name: Upload logs
         if: success() || failure()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-logs-lite-${{ github.run_id }}
           path: ${{ github.workspace }}/docker-compose.log

.github/workflows/pr-python-model-tests.yml

@@ -122,7 +122,7 @@ jobs:
 
       - name: Upload logs
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-all-logs
           path: ${{ github.workspace }}/docker-compose.log

.github/workflows/reusable-nightly-llm-provider-chat.yml

@@ -319,7 +319,7 @@ jobs:
 
       - name: Upload logs
         if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
         with:
           name: docker-all-logs-nightly-${{ matrix.provider }}-llm-provider
           path: |

.github/workflows/sandbox-deployment.yml

@@ -125,7 +125,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
           flavor: |
@@ -195,7 +195,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
           flavor: |
@@ -268,7 +268,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # ratchet:docker/metadata-action@v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # ratchet:docker/metadata-action@v6.0.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
           flavor: |

backend/ee/onyx/configs/app_configs.py

@@ -118,9 +118,7 @@ JWT_PUBLIC_KEY_URL: str | None = os.getenv("JWT_PUBLIC_KEY_URL", None)
 SUPER_USERS = json.loads(os.environ.get("SUPER_USERS", "[]"))
 SUPER_CLOUD_API_KEY = os.environ.get("SUPER_CLOUD_API_KEY", "api_key")
 
-# The posthog client does not accept empty API keys or hosts however it fails silently
-# when the capture is called. These defaults prevent Posthog issues from breaking the Onyx app
-POSTHOG_API_KEY = os.environ.get("POSTHOG_API_KEY") or "FooBar"
+POSTHOG_API_KEY = os.environ.get("POSTHOG_API_KEY")
 POSTHOG_HOST = os.environ.get("POSTHOG_HOST") or "https://us.i.posthog.com"
 POSTHOG_DEBUG_LOGS_ENABLED = (
     os.environ.get("POSTHOG_DEBUG_LOGS_ENABLED", "").lower() == "true"

backend/ee/onyx/feature_flags/posthog_provider.py

@@ -34,6 +34,9 @@ class PostHogFeatureFlagProvider(FeatureFlagProvider):
         Returns:
             True if the feature is enabled for the user, False otherwise.
         """
+        if not posthog:
+            return False
+
         try:
             posthog.set(
                 distinct_id=user_id,

backend/ee/onyx/server/tenants/provisioning.py

@@ -29,7 +29,6 @@ from onyx.configs.app_configs import OPENAI_DEFAULT_API_KEY
 from onyx.configs.app_configs import OPENROUTER_DEFAULT_API_KEY
 from onyx.configs.app_configs import VERTEXAI_DEFAULT_CREDENTIALS
 from onyx.configs.app_configs import VERTEXAI_DEFAULT_LOCATION
-from onyx.configs.constants import MilestoneRecordType
 from onyx.db.engine.sql_engine import get_session_with_shared_schema
 from onyx.db.engine.sql_engine import get_session_with_tenant
 from onyx.db.image_generation import create_default_image_gen_config_from_api_key
@@ -59,7 +58,6 @@ from onyx.server.manage.llm.models import LLMProviderUpsertRequest
 from onyx.server.manage.llm.models import ModelConfigurationUpsertRequest
 from onyx.setup import setup_onyx
 from onyx.utils.logger import setup_logger
-from onyx.utils.telemetry import mt_cloud_telemetry
 from shared_configs.configs import MULTI_TENANT
 from shared_configs.configs import POSTGRES_DEFAULT_SCHEMA
 from shared_configs.configs import TENANT_ID_PREFIX
@@ -71,7 +69,9 @@ logger = setup_logger()
 
 
 async def get_or_provision_tenant(
-    email: str, referral_source: str | None = None, request: Request | None = None
+    email: str,
+    referral_source: str | None = None,
+    request: Request | None = None,
 ) -> str:
     """
     Get existing tenant ID for an email or create a new tenant if none exists.
@@ -693,12 +693,6 @@ async def assign_tenant_to_user(
 
     try:
         add_users_to_tenant([email], tenant_id)
-
-        mt_cloud_telemetry(
-            tenant_id=tenant_id,
-            distinct_id=email,
-            event=MilestoneRecordType.TENANT_CREATED,
-        )
     except Exception:
         logger.exception(f"Failed to assign tenant {tenant_id} to user {email}")
         raise Exception("Failed to assign tenant to user")

backend/ee/onyx/utils/posthog_client.py

@@ -9,6 +9,7 @@ from ee.onyx.configs.app_configs import POSTHOG_API_KEY
 from ee.onyx.configs.app_configs import POSTHOG_DEBUG_LOGS_ENABLED
 from ee.onyx.configs.app_configs import POSTHOG_HOST
 from onyx.utils.logger import setup_logger
+from shared_configs.configs import MULTI_TENANT
 
 logger = setup_logger()
 
@@ -18,12 +19,19 @@ def posthog_on_error(error: Any, items: Any) -> None:
     logger.error(f"PostHog error: {error}, items: {items}")
 
 
-posthog = Posthog(
-    project_api_key=POSTHOG_API_KEY,
-    host=POSTHOG_HOST,
-    debug=POSTHOG_DEBUG_LOGS_ENABLED,
-    on_error=posthog_on_error,
-)
+posthog: Posthog | None = None
+if POSTHOG_API_KEY:
+    posthog = Posthog(
+        project_api_key=POSTHOG_API_KEY,
+        host=POSTHOG_HOST,
+        debug=POSTHOG_DEBUG_LOGS_ENABLED,
+        on_error=posthog_on_error,
+    )
+elif MULTI_TENANT:
+    logger.warning(
+        "POSTHOG_API_KEY is not set but MULTI_TENANT is enabled — "
+        "PostHog telemetry and feature flags will be disabled"
+    )
 
 # For cross referencing between cloud and www Onyx sites
 # NOTE: These clients are separate because they are separate posthog projects.
@@ -60,7 +68,7 @@ def capture_and_sync_with_alternate_posthog(
         logger.error(f"Error capturing marketing posthog event: {e}")
 
     try:
-        if cloud_user_id := props.get("onyx_cloud_user_id"):
+        if posthog and (cloud_user_id := props.get("onyx_cloud_user_id")):
             cloud_props = props.copy()
             cloud_props.pop("onyx_cloud_user_id", None)
 

backend/ee/onyx/utils/telemetry.py

@@ -8,6 +8,9 @@ def event_telemetry(
     distinct_id: str, event: str, properties: dict | None = None
 ) -> None:
     """Capture and send an event to PostHog, flushing immediately."""
+    if not posthog:
+        return
+
     logger.info(f"Capturing PostHog event: {distinct_id} {event} {properties}")
     try:
         posthog.capture(distinct_id, event, properties)

backend/onyx/auth/users.py

@@ -812,10 +812,17 @@ class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
 
             mt_cloud_telemetry(
                 tenant_id=tenant_id,
-                distinct_id=user.email,
+                distinct_id=str(user.id),
                 event=MilestoneRecordType.USER_SIGNED_UP,
             )
 
+            if user_count == 1:
+                mt_cloud_telemetry(
+                    tenant_id=tenant_id,
+                    distinct_id=str(user.id),
+                    event=MilestoneRecordType.TENANT_CREATED,
+                )
+
         finally:
             CURRENT_TENANT_ID_CONTEXTVAR.reset(token)
 

backend/onyx/chat/process_message.py

@@ -490,13 +490,13 @@ def handle_stream_message_objects(
         # Milestone tracking, most devs using the API don't need to understand this
         mt_cloud_telemetry(
             tenant_id=tenant_id,
-            distinct_id=user.email if not user.is_anonymous else tenant_id,
+            distinct_id=str(user.id) if not user.is_anonymous else tenant_id,
             event=MilestoneRecordType.MULTIPLE_ASSISTANTS,
         )
 
         mt_cloud_telemetry(
             tenant_id=tenant_id,
-            distinct_id=user.email if not user.is_anonymous else tenant_id,
+            distinct_id=str(user.id) if not user.is_anonymous else tenant_id,
             event=MilestoneRecordType.USER_MESSAGE_SENT,
             properties={
                 "origin": new_msg_req.origin.value,

backend/onyx/configs/app_configs.py

@@ -1046,6 +1046,8 @@ POD_NAMESPACE = os.environ.get("POD_NAMESPACE")
 
 DEV_MODE = os.environ.get("DEV_MODE", "").lower() == "true"
 
+HOOK_ENABLED = os.environ.get("HOOK_ENABLED", "").lower() == "true"
+
 INTEGRATION_TESTS_MODE = os.environ.get("INTEGRATION_TESTS_MODE", "").lower() == "true"
 
 #####

backend/onyx/error_handling/error_codes.py

@@ -35,6 +35,8 @@ class OnyxErrorCode(Enum):
     INSUFFICIENT_PERMISSIONS = ("INSUFFICIENT_PERMISSIONS", 403)
     ADMIN_ONLY = ("ADMIN_ONLY", 403)
     EE_REQUIRED = ("EE_REQUIRED", 403)
+    SINGLE_TENANT_ONLY = ("SINGLE_TENANT_ONLY", 403)
+    ENV_VAR_GATED = ("ENV_VAR_GATED", 403)
 
     # ------------------------------------------------------------------
     # Validation / Bad Request (400)

backend/onyx/hooks/api_dependencies.py

@@ -0,0 +1,26 @@
+from onyx.configs.app_configs import HOOK_ENABLED
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from shared_configs.configs import MULTI_TENANT
+
+
+def require_hook_enabled() -> None:
+    """FastAPI dependency that gates all hook management endpoints.
+
+    Hooks are only available in single-tenant / self-hosted deployments with
+    HOOK_ENABLED=true explicitly set. Two layers of protection:
+      1. MULTI_TENANT check — rejects even if HOOK_ENABLED is accidentally set true
+      2. HOOK_ENABLED flag — explicit opt-in by the operator
+
+    Use as: Depends(require_hook_enabled)
+    """
+    if MULTI_TENANT:
+        raise OnyxError(
+            OnyxErrorCode.SINGLE_TENANT_ONLY,
+            "Hooks are not available in multi-tenant deployments",
+        )
+    if not HOOK_ENABLED:
+        raise OnyxError(
+            OnyxErrorCode.ENV_VAR_GATED,
+            "Hooks are not enabled. Set HOOK_ENABLED=true to enable.",
+        )

backend/onyx/server/documents/connector.py

@@ -1319,7 +1319,7 @@ def get_connector_indexing_status(
     # Track admin page visit for analytics
     mt_cloud_telemetry(
         tenant_id=tenant_id,
-        distinct_id=user.email,
+        distinct_id=str(user.id),
         event=MilestoneRecordType.VISITED_ADMIN_PAGE,
     )
 
@@ -1533,7 +1533,7 @@ def create_connector_from_model(
 
         mt_cloud_telemetry(
             tenant_id=tenant_id,
-            distinct_id=user.email,
+            distinct_id=str(user.id),
             event=MilestoneRecordType.CREATED_CONNECTOR,
         )
 
@@ -1611,7 +1611,7 @@ def create_connector_with_mock_credential(
 
         mt_cloud_telemetry(
             tenant_id=tenant_id,
-            distinct_id=user.email,
+            distinct_id=str(user.id),
             event=MilestoneRecordType.CREATED_CONNECTOR,
         )
         return response
@@ -1915,9 +1915,7 @@ def submit_connector_request(
     if not connector_name:
         raise HTTPException(status_code=400, detail="Connector name cannot be empty")
 
-    # Get user identifier for telemetry
     user_email = user.email
-    distinct_id = user_email or tenant_id
 
     # Track connector request via PostHog telemetry (Cloud only)
     from shared_configs.configs import MULTI_TENANT
@@ -1925,11 +1923,11 @@ def submit_connector_request(
     if MULTI_TENANT:
         mt_cloud_telemetry(
             tenant_id=tenant_id,
-            distinct_id=distinct_id,
+            distinct_id=str(user.id),
             event=MilestoneRecordType.REQUESTED_CONNECTOR,
             properties={
                 "connector_name": connector_name,
-                "user_email": user_email,
+                "user_email": user.email,
             },
         )
 

backend/onyx/server/features/persona/api.py

@@ -314,7 +314,7 @@ def create_persona(
     )
     mt_cloud_telemetry(
         tenant_id=tenant_id,
-        distinct_id=user.email,
+        distinct_id=str(user.id),
         event=MilestoneRecordType.CREATED_ASSISTANT,
     )
 

backend/onyx/server/query_and_chat/chat_backend.py

@@ -561,7 +561,7 @@ def handle_send_chat_message(
     tenant_id = get_current_tenant_id()
     mt_cloud_telemetry(
         tenant_id=tenant_id,
-        distinct_id=tenant_id if user.is_anonymous else user.email,
+        distinct_id=tenant_id if user.is_anonymous else str(user.id),
         event=MilestoneRecordType.RAN_QUERY,
     )
 

backend/requirements/default.txt

@@ -65,7 +65,7 @@ attrs==25.4.0
     #   jsonschema
     #   referencing
     #   zeep
-authlib==1.6.7
+authlib==1.6.9
     # via fastmcp
 azure-cognitiveservices-speech==1.38.0
     # via onyx

backend/tests/README.md

@@ -45,6 +45,21 @@ npx playwright test <TEST_NAME>
 Shared fixtures live in `backend/tests/conftest.py`. Test subdirectories can define
 their own `conftest.py` for directory-scoped fixtures.
 
+## Running Tests Repeatedly (`pytest-repeat`)
+
+Use `pytest-repeat` to catch flaky tests by running them multiple times:
+
+```bash
+# Run a specific test 50 times
+pytest --count=50 backend/tests/unit/path/to/test.py::test_name
+
+# Stop on first failure with -x
+pytest --count=50 -x backend/tests/unit/path/to/test.py::test_name
+
+# Repeat an entire test file
+pytest --count=10 backend/tests/unit/path/to/test_file.py
+```
+
 ## Best Practices
 
 ### Use `enable_ee` fixture instead of inlining

backend/tests/unit/onyx/hooks/test_api_dependencies.py

@@ -0,0 +1,40 @@
+"""Unit tests for the hooks feature gate."""
+
+from unittest.mock import patch
+
+import pytest
+
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.hooks.api_dependencies import require_hook_enabled
+
+
+class TestRequireHookEnabled:
+    def test_raises_when_multi_tenant(self) -> None:
+        with (
+            patch("onyx.hooks.api_dependencies.MULTI_TENANT", True),
+            patch("onyx.hooks.api_dependencies.HOOK_ENABLED", True),
+        ):
+            with pytest.raises(OnyxError) as exc_info:
+                require_hook_enabled()
+        assert exc_info.value.error_code is OnyxErrorCode.SINGLE_TENANT_ONLY
+        assert exc_info.value.status_code == 403
+        assert "multi-tenant" in exc_info.value.detail
+
+    def test_raises_when_flag_disabled(self) -> None:
+        with (
+            patch("onyx.hooks.api_dependencies.MULTI_TENANT", False),
+            patch("onyx.hooks.api_dependencies.HOOK_ENABLED", False),
+        ):
+            with pytest.raises(OnyxError) as exc_info:
+                require_hook_enabled()
+        assert exc_info.value.error_code is OnyxErrorCode.ENV_VAR_GATED
+        assert exc_info.value.status_code == 403
+        assert "HOOK_ENABLED" in exc_info.value.detail
+
+    def test_passes_when_enabled_single_tenant(self) -> None:
+        with (
+            patch("onyx.hooks.api_dependencies.MULTI_TENANT", False),
+            patch("onyx.hooks.api_dependencies.HOOK_ENABLED", True),
+        ):
+            require_hook_enabled()  # must not raise

backend/tests/unit/onyx/utils/test_telemetry.py

@@ -17,7 +17,7 @@ def test_mt_cloud_telemetry_noop_when_not_multi_tenant(monkeypatch: Any) -> None
 
     telemetry_utils.mt_cloud_telemetry(
         tenant_id="tenant-1",
-        distinct_id="user@example.com",
+        distinct_id="12345678-1234-1234-1234-123456789abc",
         event=MilestoneRecordType.USER_MESSAGE_SENT,
         properties={"origin": "web"},
     )
@@ -40,7 +40,7 @@ def test_mt_cloud_telemetry_calls_event_telemetry_when_multi_tenant(
 
     telemetry_utils.mt_cloud_telemetry(
         tenant_id="tenant-1",
-        distinct_id="user@example.com",
+        distinct_id="12345678-1234-1234-1234-123456789abc",
         event=MilestoneRecordType.USER_MESSAGE_SENT,
         properties={"origin": "web"},
     )
@@ -51,7 +51,7 @@ def test_mt_cloud_telemetry_calls_event_telemetry_when_multi_tenant(
         fallback=telemetry_utils.noop_fallback,
     )
     event_telemetry.assert_called_once_with(
-        "user@example.com",
+        "12345678-1234-1234-1234-123456789abc",
         MilestoneRecordType.USER_MESSAGE_SENT,
         {"origin": "web", "tenant_id": "tenant-1"},
     )

backend/tests/unit/onyx/utils/test_threadpool_concurrency.py

@@ -32,15 +32,17 @@ def test_run_with_timeout_raises_on_timeout(slow: float, timeout: float) -> None
     """Test that a function that exceeds timeout raises TimeoutError"""
 
     def slow_function() -> None:
-        time.sleep(slow)  # Sleep for 2 seconds
+        time.sleep(slow)
 
+    start = time.monotonic()
     with pytest.raises(TimeoutError) as exc_info:
-        start = time.time()
-        run_with_timeout(timeout, slow_function)  # Set timeout to 0.1 seconds
-        end = time.time()
-        assert end - start >= timeout
-        assert end - start < (slow + timeout) / 2
+        run_with_timeout(timeout, slow_function)
+    elapsed = time.monotonic() - start
+
     assert f"timed out after {timeout} seconds" in str(exc_info.value)
+    assert elapsed >= timeout
+    # Should return around the timeout duration, not the full sleep duration
+    assert elapsed == pytest.approx(timeout, abs=0.8)
 
 
 @pytest.mark.filterwarnings("ignore::pytest.PytestUnhandledThreadExceptionWarning")

deployment/docker_compose/docker-compose.onyx-lite.yml

@@ -15,8 +15,9 @@
 #                  -f docker-compose.dev.yml up -d --wait
 #
 # This overlay:
-#   - Moves Vespa (index), both model servers, code-interpreter, Redis (cache),
-#     and the background worker to profiles so they do not start by default
+#   - Moves Vespa (index), both model servers, OpenSearch, MinIO,
+#     Redis (cache), and the background worker to profiles so they do
+#     not start by default
 #   - Makes depends_on references to removed services optional
 #   - Sets DISABLE_VECTOR_DB=true on the api_server
 #   - Uses PostgreSQL for caching and auth instead of Redis
@@ -27,7 +28,8 @@
 #   --profile inference         Inference model server
 #   --profile background        Background worker (Celery) — also needs redis
 #   --profile redis             Redis cache
-#   --profile code-interpreter  Code interpreter
+#   --profile opensearch        OpenSearch
+#   --profile s3-filestore      MinIO (S3-compatible file store)
 # =============================================================================
 
 name: onyx
@@ -38,6 +40,9 @@ services:
       index:
         condition: service_started
         required: false
+      opensearch:
+        condition: service_started
+        required: false
       cache:
         condition: service_started
         required: false
@@ -84,4 +89,10 @@ services:
   inference_model_server:
     profiles: ["inference"]
 
-  code-interpreter: {}
+  # OpenSearch is not needed in lite mode (no indexing).
+  opensearch:
+    profiles: ["opensearch"]
+
+  # MinIO is not needed in lite mode (Postgres handles file storage).
+  minio:
+    profiles: ["s3-filestore"]

deployment/docker_compose/install.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
-set -e
+set -euo pipefail
 
-# Expected resource requirements
+# Expected resource requirements (overridden below if --lite)
 EXPECTED_DOCKER_RAM_GB=10
 EXPECTED_DISK_GB=32
 
@@ -10,6 +10,11 @@ EXPECTED_DISK_GB=32
 SHUTDOWN_MODE=false
 DELETE_DATA_MODE=false
 INCLUDE_CRAFT=false  # Disabled by default, use --include-craft to enable
+LITE_MODE=false       # Disabled by default, use --lite to enable
+USE_LOCAL_FILES=false # Disabled by default, use --local to skip downloading config files
+NO_PROMPT=false
+DRY_RUN=false
+VERBOSE=false
 
 while [[ $# -gt 0 ]]; do
     case $1 in
@@ -25,6 +30,26 @@ while [[ $# -gt 0 ]]; do
             INCLUDE_CRAFT=true
             shift
             ;;
+        --lite)
+            LITE_MODE=true
+            shift
+            ;;
+        --local)
+            USE_LOCAL_FILES=true
+            shift
+            ;;
+        --no-prompt)
+            NO_PROMPT=true
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --verbose)
+            VERBOSE=true
+            shift
+            ;;
         --help|-h)
             echo "Onyx Installation Script"
             echo ""
@@ -32,15 +57,23 @@ while [[ $# -gt 0 ]]; do
             echo ""
             echo "Options:"
             echo "  --include-craft  Enable Onyx Craft (AI-powered web app building)"
+            echo "  --lite           Deploy Onyx Lite (no Vespa, Redis, or model servers)"
+            echo "  --local          Use existing config files instead of downloading from GitHub"
             echo "  --shutdown       Stop (pause) Onyx containers"
             echo "  --delete-data    Remove all Onyx data (containers, volumes, and files)"
+            echo "  --no-prompt      Run non-interactively with defaults (for CI/automation)"
+            echo "  --dry-run        Show what would be done without making changes"
+            echo "  --verbose        Show detailed output for debugging"
             echo "  --help, -h       Show this help message"
             echo ""
             echo "Examples:"
             echo "  $0                    # Install Onyx"
+            echo "  $0 --lite             # Install Onyx Lite (minimal deployment)"
             echo "  $0 --include-craft    # Install Onyx with Craft enabled"
             echo "  $0 --shutdown         # Pause Onyx services"
             echo "  $0 --delete-data      # Completely remove Onyx and all data"
+            echo "  $0 --local            # Re-run using existing config files on disk"
+            echo "  $0 --no-prompt        # Non-interactive install with defaults"
             exit 0
             ;;
         *)
@@ -51,8 +84,129 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+if [[ "$VERBOSE" = true ]]; then
+    set -x
+fi
+
+if [[ "$LITE_MODE" = true ]] && [[ "$INCLUDE_CRAFT" = true ]]; then
+    echo "ERROR: --lite and --include-craft cannot be used together."
+    echo "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
+    exit 1
+fi
+
+# When --lite is passed as a flag, lower resource thresholds early (before the
+# resource check). When lite is chosen interactively, the thresholds are adjusted
+# inside the new-deployment flow, after the resource check has already passed
+# with the standard thresholds — which is the safer direction.
+if [[ "$LITE_MODE" = true ]]; then
+    EXPECTED_DOCKER_RAM_GB=4
+    EXPECTED_DISK_GB=16
+fi
+
 INSTALL_ROOT="${INSTALL_PREFIX:-onyx_data}"
 
+LITE_COMPOSE_FILE="docker-compose.onyx-lite.yml"
+
+# Build the -f flags for docker compose.
+# Pass "true" as $1 to auto-detect a previously-downloaded lite overlay
+# (used by shutdown/delete-data so users don't need to remember --lite).
+# Without the argument, the lite overlay is only included when --lite was
+# explicitly passed — preventing install/start from silently staying in
+# lite mode just because the file exists on disk from a prior run.
+compose_file_args() {
+    local auto_detect="${1:-false}"
+    local args="-f docker-compose.yml"
+    if [[ "$LITE_MODE" = true ]] || { [[ "$auto_detect" = true ]] && [[ -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" ]]; }; then
+        args="$args -f ${LITE_COMPOSE_FILE}"
+    fi
+    echo "$args"
+}
+
+# --- Downloader detection (curl with wget fallback) ---
+DOWNLOADER=""
+detect_downloader() {
+    if command -v curl &> /dev/null; then
+        DOWNLOADER="curl"
+        return 0
+    fi
+    if command -v wget &> /dev/null; then
+        DOWNLOADER="wget"
+        return 0
+    fi
+    echo "ERROR: Neither curl nor wget found. Please install one and retry."
+    exit 1
+}
+detect_downloader
+
+download_file() {
+    local url="$1"
+    local output="$2"
+    if [[ "$DOWNLOADER" == "curl" ]]; then
+        curl -fsSL --retry 3 --retry-delay 2 --retry-connrefused -o "$output" "$url"
+    else
+        wget -q --tries=3 --timeout=20 -O "$output" "$url"
+    fi
+}
+
+# Ensures a required file is present. With --local, verifies the file exists on
+# disk. Otherwise, downloads it from the given URL. Returns 0 on success, 1 on
+# failure (caller should handle the exit).
+ensure_file() {
+    local path="$1"
+    local url="$2"
+    local desc="$3"
+
+    if [[ "$USE_LOCAL_FILES" = true ]]; then
+        if [[ -f "$path" ]]; then
+            print_success "Using existing ${desc}"
+            return 0
+        fi
+        print_error "Required file missing: ${desc} (${path})"
+        return 1
+    fi
+
+    print_info "Downloading ${desc}..."
+    if download_file "$url" "$path" 2>/dev/null; then
+        print_success "${desc} downloaded"
+        return 0
+    fi
+    print_error "Failed to download ${desc}"
+    print_info "Please ensure you have internet connection and try again"
+    return 1
+}
+
+# --- Interactive prompt helpers ---
+is_interactive() {
+    [[ "$NO_PROMPT" = false ]] && [[ -t 0 ]]
+}
+
+prompt_or_default() {
+    local prompt_text="$1"
+    local default_value="$2"
+    if is_interactive; then
+        read -p "$prompt_text" -r REPLY
+        if [[ -z "$REPLY" ]]; then
+            REPLY="$default_value"
+        fi
+    else
+        REPLY="$default_value"
+    fi
+}
+
+prompt_yn_or_default() {
+    local prompt_text="$1"
+    local default_value="$2"
+    if is_interactive; then
+        read -p "$prompt_text" -n 1 -r
+        echo ""
+        if [[ -z "$REPLY" ]]; then
+            REPLY="$default_value"
+        fi
+    else
+        REPLY="$default_value"
+    fi
+}
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -111,7 +265,7 @@ if [ "$SHUTDOWN_MODE" = true ]; then
             fi
 
             # Stop containers (without removing them)
-            (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml stop)
+            (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args true) stop)
             if [ $? -eq 0 ]; then
                 print_success "Onyx containers stopped (paused)"
             else
@@ -140,12 +294,17 @@ if [ "$DELETE_DATA_MODE" = true ]; then
     echo "  • All downloaded files and configurations"
     echo "  • All user data and documents"
     echo ""
-    read -p "Are you sure you want to continue? Type 'DELETE' to confirm: " -r
-    echo ""
-
-    if [ "$REPLY" != "DELETE" ]; then
-        print_info "Operation cancelled."
-        exit 0
+    if is_interactive; then
+        read -p "Are you sure you want to continue? Type 'DELETE' to confirm: " -r
+        echo ""
+        if [ "$REPLY" != "DELETE" ]; then
+            print_info "Operation cancelled."
+            exit 0
+        fi
+    else
+        print_error "Cannot confirm destructive operation in non-interactive mode."
+        print_info "Run interactively or remove the ${INSTALL_ROOT} directory manually."
+        exit 1
     fi
 
     print_info "Removing Onyx containers and volumes..."
@@ -164,7 +323,7 @@ if [ "$DELETE_DATA_MODE" = true ]; then
             fi
 
             # Stop and remove containers with volumes
-            (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml down -v)
+            (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args true) down -v)
             if [ $? -eq 0 ]; then
                 print_success "Onyx containers and volumes removed"
             else
@@ -186,6 +345,117 @@ if [ "$DELETE_DATA_MODE" = true ]; then
     exit 0
 fi
 
+# --- Auto-install Docker (Linux only) ---
+# Runs before the banner so a group-based re-exec doesn't repeat it.
+install_docker_linux() {
+    local distro_id=""
+    if [[ -f /etc/os-release ]]; then
+        distro_id="$(. /etc/os-release && echo "${ID:-}")"
+    fi
+
+    case "$distro_id" in
+        amzn)
+            print_info "Detected Amazon Linux — installing Docker via package manager..."
+            if command -v dnf &> /dev/null; then
+                sudo dnf install -y docker
+            else
+                sudo yum install -y docker
+            fi
+            ;;
+        *)
+            print_info "Installing Docker via get.docker.com..."
+            download_file "https://get.docker.com" /tmp/get-docker.sh
+            sudo sh /tmp/get-docker.sh
+            rm -f /tmp/get-docker.sh
+            ;;
+    esac
+
+    sudo systemctl start docker 2>/dev/null || sudo service docker start 2>/dev/null || true
+    sudo systemctl enable docker 2>/dev/null || true
+}
+
+# Detect OS (including WSL)
+IS_WSL=false
+if [[ -n "${WSL_DISTRO_NAME:-}" ]] || grep -qi microsoft /proc/version 2>/dev/null; then
+    IS_WSL=true
+fi
+
+# Dry-run: show plan and exit
+if [[ "$DRY_RUN" = true ]]; then
+    print_info "Dry run mode — showing what would happen:"
+    echo "  • Install root: ${INSTALL_ROOT}"
+    echo "  • Lite mode: ${LITE_MODE}"
+    echo "  • Include Craft: ${INCLUDE_CRAFT}"
+    echo "  • OS type: ${OSTYPE:-unknown} (WSL: ${IS_WSL})"
+    echo "  • Downloader: ${DOWNLOADER}"
+    echo ""
+    print_success "Dry run complete (no changes made)"
+    exit 0
+fi
+
+if ! command -v docker &> /dev/null; then
+    if [[ "$OSTYPE" == "linux-gnu"* ]] || [[ -n "${WSL_DISTRO_NAME:-}" ]]; then
+        install_docker_linux
+        if ! command -v docker &> /dev/null; then
+            print_error "Docker installation failed."
+            echo "  Visit: https://docs.docker.com/get-docker/"
+            exit 1
+        fi
+        print_success "Docker installed successfully"
+    fi
+fi
+
+# --- Auto-install Docker Compose plugin (Linux only) ---
+if command -v docker &> /dev/null \
+    && ! docker compose version &> /dev/null \
+    && ! command -v docker-compose &> /dev/null \
+    && { [[ "$OSTYPE" == "linux-gnu"* ]] || [[ -n "${WSL_DISTRO_NAME:-}" ]]; }; then
+
+    print_info "Docker Compose not found — installing plugin..."
+    COMPOSE_ARCH="$(uname -m)"
+    COMPOSE_URL="https://github.com/docker/compose/releases/latest/download/docker-compose-linux-${COMPOSE_ARCH}"
+    COMPOSE_DIR="/usr/local/lib/docker/cli-plugins"
+    COMPOSE_TMP="$(mktemp)"
+    sudo mkdir -p "$COMPOSE_DIR"
+    if download_file "$COMPOSE_URL" "$COMPOSE_TMP"; then
+        sudo mv "$COMPOSE_TMP" "$COMPOSE_DIR/docker-compose"
+        sudo chmod +x "$COMPOSE_DIR/docker-compose"
+        if docker compose version &> /dev/null; then
+            print_success "Docker Compose plugin installed"
+        else
+            print_error "Docker Compose plugin installed but not detected."
+            echo "  Visit: https://docs.docker.com/compose/install/"
+            exit 1
+        fi
+    else
+        rm -f "$COMPOSE_TMP"
+        print_error "Failed to download Docker Compose plugin."
+        echo "  Visit: https://docs.docker.com/compose/install/"
+        exit 1
+    fi
+fi
+
+# On Linux, ensure the current user can talk to the Docker daemon without
+# sudo.  If necessary, add them to the "docker" group and re-exec the
+# script under that group so the rest of the install proceeds normally.
+if command -v docker &> /dev/null \
+    && { [[ "$OSTYPE" == "linux-gnu"* ]] || [[ -n "${WSL_DISTRO_NAME:-}" ]]; } \
+    && [[ "$(id -u)" -ne 0 ]] \
+    && ! docker info &> /dev/null; then
+    if [[ "${_ONYX_REEXEC:-}" = "1" ]]; then
+        print_error "Cannot connect to Docker after group re-exec."
+        print_info "Log out and back in, then run the script again."
+        exit 1
+    fi
+    if ! getent group docker &> /dev/null; then
+        sudo groupadd docker
+    fi
+    print_info "Adding $USER to the docker group..."
+    sudo usermod -aG docker "$USER"
+    print_info "Re-launching with docker group active..."
+    exec sg docker -c "_ONYX_REEXEC=1 bash $(printf '%q ' "$0" "$@")"
+fi
+
 # ASCII Art Banner
 echo ""
 echo -e "${BLUE}${BOLD}"
@@ -209,8 +479,7 @@ echo "2. Check your system resources (Docker, memory, disk space)"
 echo "3. Guide you through deployment options (version, authentication)"
 echo ""
 
-# Only prompt for acknowledgment if running interactively
-if [ -t 0 ]; then
+if is_interactive; then
     echo -e "${YELLOW}${BOLD}Please acknowledge and press Enter to continue...${NC}"
     read -r
     echo ""
@@ -260,41 +529,35 @@ else
     exit 1
 fi
 
-# Function to compare version numbers
+# Returns 0 if $1 <= $2, 1 if $1 > $2
+# Handles missing or non-numeric parts gracefully (treats them as 0)
 version_compare() {
-    # Returns 0 if $1 <= $2, 1 if $1 > $2
-    local version1=$1
-    local version2=$2
+    local version1="${1:-0.0.0}"
+    local version2="${2:-0.0.0}"
 
-    # Split versions into components
-    local v1_major=$(echo $version1 | cut -d. -f1)
-    local v1_minor=$(echo $version1 | cut -d. -f2)
-    local v1_patch=$(echo $version1 | cut -d. -f3)
+    local v1_major v1_minor v1_patch v2_major v2_minor v2_patch
+    v1_major=$(echo "$version1" | cut -d. -f1)
+    v1_minor=$(echo "$version1" | cut -d. -f2)
+    v1_patch=$(echo "$version1" | cut -d. -f3)
+    v2_major=$(echo "$version2" | cut -d. -f1)
+    v2_minor=$(echo "$version2" | cut -d. -f2)
+    v2_patch=$(echo "$version2" | cut -d. -f3)
 
-    local v2_major=$(echo $version2 | cut -d. -f1)
-    local v2_minor=$(echo $version2 | cut -d. -f2)
-    local v2_patch=$(echo $version2 | cut -d. -f3)
+    # Default non-numeric or empty parts to 0
+    [[ "$v1_major" =~ ^[0-9]+$ ]] || v1_major=0
+    [[ "$v1_minor" =~ ^[0-9]+$ ]] || v1_minor=0
+    [[ "$v1_patch" =~ ^[0-9]+$ ]] || v1_patch=0
+    [[ "$v2_major" =~ ^[0-9]+$ ]] || v2_major=0
+    [[ "$v2_minor" =~ ^[0-9]+$ ]] || v2_minor=0
+    [[ "$v2_patch" =~ ^[0-9]+$ ]] || v2_patch=0
 
-    # Compare major version
-    if [ "$v1_major" -lt "$v2_major" ]; then
-        return 0
-    elif [ "$v1_major" -gt "$v2_major" ]; then
-        return 1
-    fi
+    if [ "$v1_major" -lt "$v2_major" ]; then return 0
+    elif [ "$v1_major" -gt "$v2_major" ]; then return 1; fi
 
-    # Compare minor version
-    if [ "$v1_minor" -lt "$v2_minor" ]; then
-        return 0
-    elif [ "$v1_minor" -gt "$v2_minor" ]; then
-        return 1
-    fi
+    if [ "$v1_minor" -lt "$v2_minor" ]; then return 0
+    elif [ "$v1_minor" -gt "$v2_minor" ]; then return 1; fi
 
-    # Compare patch version
-    if [ "$v1_patch" -le "$v2_patch" ]; then
-        return 0
-    else
-        return 1
-    fi
+    [ "$v1_patch" -le "$v2_patch" ]
 }
 
 # Check Docker daemon
@@ -336,10 +599,20 @@ fi
 
 # Convert to GB for display
 if [ "$MEMORY_MB" -gt 0 ]; then
-    MEMORY_GB=$((MEMORY_MB / 1024))
-    print_info "Docker memory allocation: ~${MEMORY_GB}GB"
+    MEMORY_GB=$(awk "BEGIN {printf \"%.1f\", $MEMORY_MB / 1024}")
+    if [ "$(awk "BEGIN {print ($MEMORY_MB >= 1024)}")" = "1" ]; then
+        MEMORY_DISPLAY="~${MEMORY_GB}GB"
+    else
+        MEMORY_DISPLAY="${MEMORY_MB}MB"
+    fi
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        print_info "Docker memory allocation: ${MEMORY_DISPLAY}"
+    else
+        print_info "System memory: ${MEMORY_DISPLAY} (Docker uses host memory directly)"
+    fi
 else
-    print_warning "Could not determine Docker memory allocation"
+    print_warning "Could not determine memory allocation"
+    MEMORY_DISPLAY="unknown"
     MEMORY_MB=0
 fi
 
@@ -358,7 +631,7 @@ RESOURCE_WARNING=false
 EXPECTED_RAM_MB=$((EXPECTED_DOCKER_RAM_GB * 1024))
 
 if [ "$MEMORY_MB" -gt 0 ] && [ "$MEMORY_MB" -lt "$EXPECTED_RAM_MB" ]; then
-    print_warning "Docker has less than ${EXPECTED_DOCKER_RAM_GB}GB RAM allocated (found: ~${MEMORY_GB}GB)"
+    print_warning "Less than ${EXPECTED_DOCKER_RAM_GB}GB RAM available (found: ${MEMORY_DISPLAY})"
     RESOURCE_WARNING=true
 fi
 
@@ -369,10 +642,10 @@ fi
 
 if [ "$RESOURCE_WARNING" = true ]; then
     echo ""
-    print_warning "Onyx recommends at least ${EXPECTED_DOCKER_RAM_GB}GB RAM and ${EXPECTED_DISK_GB}GB disk space for optimal performance."
-    echo ""
-    read -p "Do you want to continue anyway? (y/N): " -n 1 -r
+    print_warning "Onyx recommends at least ${EXPECTED_DOCKER_RAM_GB}GB RAM and ${EXPECTED_DISK_GB}GB disk space for optimal performance in standard mode."
+    print_warning "Lite mode requires less resources (1-4GB RAM, 8-16GB disk depending on usage), but does not include a vector database."
     echo ""
+    prompt_yn_or_default "Do you want to continue anyway? (Y/n): " "y"
     if [[ ! $REPLY =~ ^[Yy]$ ]]; then
         print_info "Installation cancelled. Please allocate more resources and try again."
         exit 1
@@ -385,117 +658,89 @@ print_step "Creating directory structure"
 if [ -d "${INSTALL_ROOT}" ]; then
     print_info "Directory structure already exists"
     print_success "Using existing ${INSTALL_ROOT} directory"
-else
-    mkdir -p "${INSTALL_ROOT}/deployment"
-    mkdir -p "${INSTALL_ROOT}/data/nginx/local"
-    print_success "Directory structure created"
 fi
+mkdir -p "${INSTALL_ROOT}/deployment"
+mkdir -p "${INSTALL_ROOT}/data/nginx/local"
+print_success "Directory structure created"
 
-# Download all required files
-print_step "Downloading Onyx configuration files"
-print_info "This step downloads all necessary configuration files from GitHub..."
-echo ""
-print_info "Downloading the following files:"
-echo "  • docker-compose.yml - Main Docker Compose configuration"
-echo "  • env.template - Environment variables template"
-echo "  • nginx/app.conf.template - Nginx web server configuration"
-echo "  • nginx/run-nginx.sh - Nginx startup script"
-echo "  • README.md - Documentation and setup instructions"
-echo ""
-
-# Download Docker Compose file
-COMPOSE_FILE="${INSTALL_ROOT}/deployment/docker-compose.yml"
-print_info "Downloading docker-compose.yml..."
-if curl -fsSL -o "$COMPOSE_FILE" "${GITHUB_RAW_URL}/docker-compose.yml" 2>/dev/null; then
-    print_success "Docker Compose file downloaded successfully"
-
-    # Check if Docker Compose version is older than 2.24.0 and show warning
-    # Skip check for dev builds (assume they're recent enough)
-    if [ "$COMPOSE_VERSION" != "dev" ] && version_compare "$COMPOSE_VERSION" "2.24.0"; then
-        print_warning "Docker Compose version $COMPOSE_VERSION is older than 2.24.0"
-        echo ""
-        print_warning "The docker-compose.yml file uses the newer env_file format that requires Docker Compose 2.24.0 or later."
-        echo ""
-        print_info "To use this configuration with your current Docker Compose version, you have two options:"
-        echo ""
-        echo "1. Upgrade Docker Compose to version 2.24.0 or later (recommended)"
-        echo "   Visit: https://docs.docker.com/compose/install/"
-        echo ""
-        echo "2. Manually replace all env_file sections in docker-compose.yml"
-        echo "   Change from:"
-        echo "     env_file:"
-        echo "       - path: .env"
-        echo "         required: false"
-        echo "   To:"
-        echo "     env_file: .env"
-        echo ""
-        print_warning "The installation will continue, but may fail if Docker Compose cannot parse the file."
-        echo ""
-        read -p "Do you want to continue anyway? (y/N): " -n 1 -r
-        echo ""
-        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-            print_info "Installation cancelled. Please upgrade Docker Compose or manually edit the docker-compose.yml file."
-            exit 1
-        fi
-        print_info "Proceeding with installation despite Docker Compose version compatibility issues..."
-    fi
-else
-    print_error "Failed to download Docker Compose file"
-    print_info "Please ensure you have internet connection and try again"
-    exit 1
-fi
-
-# Download env.template file
-ENV_TEMPLATE="${INSTALL_ROOT}/deployment/env.template"
-print_info "Downloading env.template..."
-if curl -fsSL -o "$ENV_TEMPLATE" "${GITHUB_RAW_URL}/env.template" 2>/dev/null; then
-    print_success "Environment template downloaded successfully"
-else
-    print_error "Failed to download env.template"
-    print_info "Please ensure you have internet connection and try again"
-    exit 1
-fi
-
-# Download nginx config files
+# Ensure all required configuration files are present
 NGINX_BASE_URL="https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/data/nginx"
 
-# Download app.conf.template
-NGINX_CONFIG="${INSTALL_ROOT}/data/nginx/app.conf.template"
-print_info "Downloading nginx configuration template..."
-if curl -fsSL -o "$NGINX_CONFIG" "$NGINX_BASE_URL/app.conf.template" 2>/dev/null; then
-    print_success "Nginx configuration template downloaded"
+if [[ "$USE_LOCAL_FILES" = true ]]; then
+    print_step "Verifying existing configuration files"
 else
-    print_error "Failed to download nginx configuration template"
-    print_info "Please ensure you have internet connection and try again"
-    exit 1
+    print_step "Downloading Onyx configuration files"
+    print_info "This step downloads all necessary configuration files from GitHub..."
 fi
 
-# Download run-nginx.sh script
-NGINX_RUN_SCRIPT="${INSTALL_ROOT}/data/nginx/run-nginx.sh"
-print_info "Downloading nginx startup script..."
-if curl -fsSL -o "$NGINX_RUN_SCRIPT" "$NGINX_BASE_URL/run-nginx.sh" 2>/dev/null; then
-    chmod +x "$NGINX_RUN_SCRIPT"
-    print_success "Nginx startup script downloaded and made executable"
-else
-    print_error "Failed to download nginx startup script"
-    print_info "Please ensure you have internet connection and try again"
-    exit 1
+ensure_file "${INSTALL_ROOT}/deployment/docker-compose.yml" \
+    "${GITHUB_RAW_URL}/docker-compose.yml" "docker-compose.yml" || exit 1
+
+# Check Docker Compose version compatibility after obtaining docker-compose.yml
+if [ "$COMPOSE_VERSION" != "dev" ] && version_compare "$COMPOSE_VERSION" "2.24.0"; then
+    print_warning "Docker Compose version $COMPOSE_VERSION is older than 2.24.0"
+    echo ""
+    print_warning "The docker-compose.yml file uses the newer env_file format that requires Docker Compose 2.24.0 or later."
+    echo ""
+    print_info "To use this configuration with your current Docker Compose version, you have two options:"
+    echo ""
+    echo "1. Upgrade Docker Compose to version 2.24.0 or later (recommended)"
+    echo "   Visit: https://docs.docker.com/compose/install/"
+    echo ""
+    echo "2. Manually replace all env_file sections in docker-compose.yml"
+    echo "   Change from:"
+    echo "     env_file:"
+    echo "       - path: .env"
+    echo "         required: false"
+    echo "   To:"
+    echo "     env_file: .env"
+    echo ""
+    print_warning "The installation will continue, but may fail if Docker Compose cannot parse the file."
+    echo ""
+    prompt_yn_or_default "Do you want to continue anyway? (Y/n): " "y"
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        print_info "Installation cancelled. Please upgrade Docker Compose or manually edit the docker-compose.yml file."
+        exit 1
+    fi
+    print_info "Proceeding with installation despite Docker Compose version compatibility issues..."
 fi
 
-# Download README file
-README_FILE="${INSTALL_ROOT}/README.md"
-print_info "Downloading README.md..."
-if curl -fsSL -o "$README_FILE" "${GITHUB_RAW_URL}/README.md" 2>/dev/null; then
-    print_success "README.md downloaded successfully"
-else
-    print_error "Failed to download README.md"
-    print_info "Please ensure you have internet connection and try again"
-    exit 1
+# Handle lite overlay: ensure it if --lite, clean up stale copies otherwise
+if [[ "$LITE_MODE" = true ]]; then
+    ensure_file "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" \
+        "${GITHUB_RAW_URL}/${LITE_COMPOSE_FILE}" "${LITE_COMPOSE_FILE}" || exit 1
+elif [[ -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" ]]; then
+    if [[ -f "${INSTALL_ROOT}/deployment/.env" ]]; then
+        print_warning "Existing lite overlay found but --lite was not passed."
+        prompt_yn_or_default "Remove lite overlay and switch to standard mode? (y/N): " "n"
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            print_info "Keeping existing lite overlay. Pass --lite to keep using lite mode."
+            LITE_MODE=true
+        else
+            rm -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}"
+            print_info "Removed lite overlay (switching to standard mode)"
+        fi
+    else
+        rm -f "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}"
+        print_info "Removed previous lite overlay (switching to standard mode)"
+    fi
 fi
 
-# Create empty local directory marker (if needed)
+ensure_file "${INSTALL_ROOT}/deployment/env.template" \
+    "${GITHUB_RAW_URL}/env.template" "env.template" || exit 1
+
+ensure_file "${INSTALL_ROOT}/data/nginx/app.conf.template" \
+    "$NGINX_BASE_URL/app.conf.template" "nginx/app.conf.template" || exit 1
+
+ensure_file "${INSTALL_ROOT}/data/nginx/run-nginx.sh" \
+    "$NGINX_BASE_URL/run-nginx.sh" "nginx/run-nginx.sh" || exit 1
+chmod +x "${INSTALL_ROOT}/data/nginx/run-nginx.sh"
+
+ensure_file "${INSTALL_ROOT}/README.md" \
+    "${GITHUB_RAW_URL}/README.md" "README.md" || exit 1
+
 touch "${INSTALL_ROOT}/data/nginx/local/.gitkeep"
-print_success "All configuration files downloaded successfully"
+print_success "All configuration files ready"
 
 # Set up deployment configuration
 print_step "Setting up deployment configs"
@@ -513,7 +758,7 @@ if [ -d "${INSTALL_ROOT}/deployment" ] && [ -f "${INSTALL_ROOT}/deployment/docke
 
     if [ -n "$COMPOSE_CMD" ]; then
         # Check if any containers are running
-        RUNNING_CONTAINERS=$(cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml ps -q 2>/dev/null | wc -l)
+        RUNNING_CONTAINERS=$(cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args true) ps -q 2>/dev/null | wc -l)
         if [ "$RUNNING_CONTAINERS" -gt 0 ]; then
             print_error "Onyx services are currently running!"
             echo ""
@@ -534,7 +779,7 @@ if [ -f "$ENV_FILE" ]; then
     echo "• Press Enter to restart with current configuration"
     echo "• Type 'update' to update to a newer version"
     echo ""
-    read -p "Choose an option [default: restart]: " -r
+    prompt_or_default "Choose an option [default: restart]: " ""
     echo ""
 
     if [ "$REPLY" = "update" ]; then
@@ -543,26 +788,30 @@ if [ -f "$ENV_FILE" ]; then
         echo "• Press Enter for latest (recommended)"
         echo "• Type a specific tag (e.g., v0.1.0)"
         echo ""
-        # If --include-craft was passed, default to craft-latest
         if [ "$INCLUDE_CRAFT" = true ]; then
-            read -p "Enter tag [default: craft-latest]: " -r VERSION
+            prompt_or_default "Enter tag [default: craft-latest]: " "craft-latest"
+            VERSION="$REPLY"
         else
-            read -p "Enter tag [default: latest]: " -r VERSION
+            prompt_or_default "Enter tag [default: latest]: " "latest"
+            VERSION="$REPLY"
         fi
         echo ""
 
-        if [ -z "$VERSION" ]; then
-            if [ "$INCLUDE_CRAFT" = true ]; then
-                VERSION="craft-latest"
-                print_info "Selected: craft-latest (Craft enabled)"
-            else
-                VERSION="latest"
-                print_info "Selected: Latest version"
-            fi
+        if [ "$INCLUDE_CRAFT" = true ] && [ "$VERSION" = "craft-latest" ]; then
+            print_info "Selected: craft-latest (Craft enabled)"
+        elif [ "$VERSION" = "latest" ]; then
+            print_info "Selected: Latest version"
         else
             print_info "Selected: $VERSION"
         fi
 
+        # Reject craft image tags when running in lite mode
+        if [[ "$LITE_MODE" = true ]] && [[ "${VERSION:-}" == craft-* ]]; then
+            print_error "Cannot use a craft image tag (${VERSION}) with --lite."
+            print_info "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
+            exit 1
+        fi
+
         # Update .env file with new version
         print_info "Updating configuration for version $VERSION..."
         if grep -q "^IMAGE_TAG=" "$ENV_FILE"; then
@@ -581,13 +830,67 @@ if [ -f "$ENV_FILE" ]; then
         fi
         print_success "Configuration updated for upgrade"
     else
+        # Reject restarting a craft deployment in lite mode
+        EXISTING_TAG=$(grep "^IMAGE_TAG=" "$ENV_FILE" | head -1 | cut -d'=' -f2 | tr -d ' "'"'"'')
+        if [[ "$LITE_MODE" = true ]] && [[ "${EXISTING_TAG:-}" == craft-* ]]; then
+            print_error "Cannot restart a craft deployment (${EXISTING_TAG}) with --lite."
+            print_info "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
+            exit 1
+        fi
+
         print_info "Keeping existing configuration..."
         print_success "Will restart with current settings"
     fi
+
+    # Ensure COMPOSE_PROFILES is cleared when running in lite mode on an
+    # existing .env (the template ships with s3-filestore enabled).
+    if [[ "$LITE_MODE" = true ]] && grep -q "^COMPOSE_PROFILES=.*s3-filestore" "$ENV_FILE" 2>/dev/null; then
+        sed -i.bak 's/^COMPOSE_PROFILES=.*/COMPOSE_PROFILES=/' "$ENV_FILE" 2>/dev/null || true
+        print_success "Cleared COMPOSE_PROFILES for lite mode"
+    fi
 else
     print_info "No existing .env file found. Setting up new deployment..."
     echo ""
 
+    # Ask for deployment mode (standard vs lite) unless already set via --lite flag
+    if [[ "$LITE_MODE" = false ]]; then
+        print_info "Which deployment mode would you like?"
+        echo ""
+        echo "  1) Standard  - Full deployment with search, connectors, and RAG"
+        echo "  2) Lite      - Minimal deployment (no Vespa, Redis, or model servers)"
+        echo "                  LLM chat, tools, file uploads, and Projects still work"
+        echo ""
+        prompt_or_default "Choose a mode (1 or 2) [default: 1]: " "1"
+        echo ""
+
+        case "$REPLY" in
+            2)
+                LITE_MODE=true
+                print_info "Selected: Lite mode"
+                ensure_file "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" \
+                    "${GITHUB_RAW_URL}/${LITE_COMPOSE_FILE}" "${LITE_COMPOSE_FILE}" || exit 1
+                ;;
+            *)
+                print_info "Selected: Standard mode"
+                ;;
+        esac
+    else
+        print_info "Deployment mode: Lite (set via --lite flag)"
+    fi
+
+    # Validate lite + craft combination (could now be set interactively)
+    if [[ "$LITE_MODE" = true ]] && [[ "$INCLUDE_CRAFT" = true ]]; then
+        print_error "--include-craft cannot be used with Lite mode."
+        print_info "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
+        exit 1
+    fi
+
+    # Adjust resource expectations for lite mode
+    if [[ "$LITE_MODE" = true ]]; then
+        EXPECTED_DOCKER_RAM_GB=4
+        EXPECTED_DISK_GB=16
+    fi
+
     # Ask for version
     print_info "Which tag would you like to deploy?"
     echo ""
@@ -595,23 +898,21 @@ else
         echo "• Press Enter for craft-latest (recommended for Craft)"
         echo "• Type a specific tag (e.g., craft-v1.0.0)"
         echo ""
-        read -p "Enter tag [default: craft-latest]: " -r VERSION
+        prompt_or_default "Enter tag [default: craft-latest]: " "craft-latest"
+        VERSION="$REPLY"
     else
         echo "• Press Enter for latest (recommended)"
         echo "• Type a specific tag (e.g., v0.1.0)"
         echo ""
-        read -p "Enter tag [default: latest]: " -r VERSION
+        prompt_or_default "Enter tag [default: latest]: " "latest"
+        VERSION="$REPLY"
     fi
     echo ""
 
-    if [ -z "$VERSION" ]; then
-        if [ "$INCLUDE_CRAFT" = true ]; then
-            VERSION="craft-latest"
-            print_info "Selected: craft-latest (Craft enabled)"
-        else
-            VERSION="latest"
-            print_info "Selected: Latest tag"
-        fi
+    if [ "$INCLUDE_CRAFT" = true ] && [ "$VERSION" = "craft-latest" ]; then
+        print_info "Selected: craft-latest (Craft enabled)"
+    elif [ "$VERSION" = "latest" ]; then
+        print_info "Selected: Latest tag"
     else
         print_info "Selected: $VERSION"
     fi
@@ -645,6 +946,13 @@ else
     # Use basic auth by default
     AUTH_SCHEMA="basic"
 
+    # Reject craft image tags when running in lite mode (must check before writing .env)
+    if [[ "$LITE_MODE" = true ]] && [[ "${VERSION:-}" == craft-* ]]; then
+        print_error "Cannot use a craft image tag (${VERSION}) with --lite."
+        print_info "Craft requires services (Vespa, Redis, background workers) that lite mode disables."
+        exit 1
+    fi
+
     # Create .env file from template
     print_info "Creating .env file with your selections..."
     cp "$ENV_TEMPLATE" "$ENV_FILE"
@@ -654,6 +962,13 @@ else
     sed -i.bak "s/^IMAGE_TAG=.*/IMAGE_TAG=$VERSION/" "$ENV_FILE"
     print_success "IMAGE_TAG set to $VERSION"
 
+    # In lite mode, clear COMPOSE_PROFILES so profiled services (MinIO, etc.)
+    # stay disabled — the template ships with s3-filestore enabled by default.
+    if [[ "$LITE_MODE" = true ]]; then
+        sed -i.bak 's/^COMPOSE_PROFILES=.*/COMPOSE_PROFILES=/' "$ENV_FILE" 2>/dev/null || true
+        print_success "Cleared COMPOSE_PROFILES for lite mode"
+    fi
+
     # Configure basic authentication (default)
     sed -i.bak 's/^AUTH_TYPE=.*/AUTH_TYPE=basic/' "$ENV_FILE" 2>/dev/null || true
     print_success "Basic authentication enabled in configuration"
@@ -774,7 +1089,7 @@ print_step "Pulling Docker images"
 print_info "This may take several minutes depending on your internet connection..."
 echo ""
 print_info "Downloading Docker images (this may take a while)..."
-(cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml pull --quiet)
+(cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args) pull --quiet)
 if [ $? -eq 0 ]; then
     print_success "Docker images downloaded successfully"
 else
@@ -788,9 +1103,9 @@ print_info "Launching containers..."
 echo ""
 if [ "$USE_LATEST" = true ]; then
     print_info "Force pulling latest images and recreating containers..."
-    (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml up -d --pull always --force-recreate)
+    (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args) up -d --pull always --force-recreate)
 else
-    (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml up -d)
+    (cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args) up -d)
 fi
 if [ $? -ne 0 ]; then
     print_error "Failed to start Onyx services"
@@ -812,7 +1127,7 @@ echo ""
 # Check for restart loops
 print_info "Checking container health status..."
 RESTART_ISSUES=false
-CONTAINERS=$(cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD -f docker-compose.yml ps -q 2>/dev/null)
+CONTAINERS=$(cd "${INSTALL_ROOT}/deployment" && $COMPOSE_CMD $(compose_file_args) ps -q 2>/dev/null)
 
 for CONTAINER in $CONTAINERS; do
     PROJECT_NAME="$(basename "$INSTALL_ROOT")_deployment_"
@@ -841,7 +1156,7 @@ if [ "$RESTART_ISSUES" = true ]; then
     print_error "Some containers are experiencing issues!"
     echo ""
     print_info "Please check the logs for more information:"
-    echo "  (cd \"${INSTALL_ROOT}/deployment\" && $COMPOSE_CMD -f docker-compose.yml logs)"
+    echo "  (cd \"${INSTALL_ROOT}/deployment\" && $COMPOSE_CMD $(compose_file_args) logs)"
 
     echo ""
     print_info "If the issue persists, please contact: founders@onyx.app"
@@ -860,8 +1175,12 @@ check_onyx_health() {
     echo ""
 
     while [ $attempt -le $max_attempts ]; do
-        # Check for successful HTTP responses (200, 301, 302, etc.)
-        local http_code=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port")
+        local http_code=""
+        if [[ "$DOWNLOADER" == "curl" ]]; then
+            http_code=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port" 2>/dev/null || echo "000")
+        else
+            http_code=$(wget -q --spider -S "http://localhost:$port" 2>&1 | grep "HTTP/" | tail -1 | awk '{print $2}' || echo "000")
+        fi
         if echo "$http_code" | grep -qE "^(200|301|302|303|307|308)$"; then
             return 0
         fi
@@ -917,6 +1236,18 @@ print_info "If authentication is enabled, you can create your admin account here
 echo "   • Visit http://localhost:${HOST_PORT}/auth/signup to create your admin account"
 echo "   • The first user created will automatically have admin privileges"
 echo ""
+if [[ "$LITE_MODE" = true ]]; then
+    echo ""
+    print_info "Running in Lite mode — the following services are NOT started:"
+    echo "  • Vespa (vector database)"
+    echo "  • Redis (cache)"
+    echo "  • Model servers (embedding/inference)"
+    echo "  • Background workers (Celery)"
+    echo ""
+    print_info "Connectors and RAG search are disabled. LLM chat, tools, user file"
+    print_info "uploads, Projects, Agent knowledge, and code interpreter still work."
+fi
+echo ""
 print_info "Refer to the README in the ${INSTALL_ROOT} directory for more information."
 echo ""
 print_info "For help or issues, contact: founders@onyx.app"

uv.lock

@@ -453,14 +453,14 @@ wheels = [
 
 [[package]]
 name = "authlib"
-version = "1.6.7"
+version = "1.6.9"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "cryptography" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/49/dc/ed1681bf1339dd6ea1ce56136bad4baabc6f7ad466e375810702b0237047/authlib-1.6.7.tar.gz", hash = "sha256:dbf10100011d1e1b34048c9d120e83f13b35d69a826ae762b93d2fb5aafc337b", size = 164950, upload-time = "2026-02-06T14:04:14.171Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/98/00d3dd826d46959ad8e32af2dbb2398868fd9fd0683c26e56d0789bd0e68/authlib-1.6.9.tar.gz", hash = "sha256:d8f2421e7e5980cc1ddb4e32d3f5fa659cfaf60d8eaf3281ebed192e4ab74f04", size = 165134, upload-time = "2026-03-02T07:44:01.998Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f8/00/3ed12264094ec91f534fae429945efbaa9f8c666f3aa7061cc3b2a26a0cd/authlib-1.6.7-py2.py3-none-any.whl", hash = "sha256:c637340d9a02789d2efa1d003a7437d10d3e565237bcb5fcbc6c134c7b95bab0", size = 244115, upload-time = "2026-02-06T14:04:12.141Z" },
+    { url = "https://files.pythonhosted.org/packages/53/23/b65f568ed0c22f1efacb744d2db1a33c8068f384b8c9b482b52ebdbc3ef6/authlib-1.6.9-py2.py3-none-any.whl", hash = "sha256:f08b4c14e08f0861dc18a32357b33fbcfd2ea86cfe3fe149484b4d764c4a0ac3", size = 244197, upload-time = "2026-03-02T07:44:00.307Z" },
 ]
 
 [[package]]

web/lib/opal/src/components/index.ts

@@ -45,10 +45,3 @@ export {
   EmptyMessageCard,
   type EmptyMessageCardProps,
 } from "@opal/components/cards/empty-message-card/components";
-
-/* Pagination */
-export {
-  Pagination,
-  type PaginationProps,
-  type PaginationSize,
-} from "@opal/components/pagination/components";

web/lib/opal/src/components/pagination/Pagination.stories.tsx

@@ -1,223 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import { Pagination } from "@opal/components";
-import { useState } from "react";
-
-const meta: Meta<typeof Pagination> = {
-  title: "opal/components/Pagination",
-  component: Pagination,
-  tags: ["autodocs"],
-};
-
-export default meta;
-type Story = StoryObj<typeof Pagination>;
-
-// ===========================================================================
-// variant="simple"
-// ===========================================================================
-
-export const Simple: Story = {
-  args: {
-    variant: "simple",
-    currentPage: 3,
-    totalPages: 10,
-  },
-};
-
-export const SimpleSmall: Story = {
-  args: {
-    variant: "simple",
-    currentPage: 2,
-    totalPages: 8,
-    size: "sm",
-  },
-};
-
-export const SimpleWithUnits: Story = {
-  args: {
-    variant: "simple",
-    currentPage: 1,
-    totalPages: 5,
-    units: "pages",
-  },
-};
-
-export const SimpleArrowsOnly: Story = {
-  args: {
-    variant: "simple",
-    currentPage: 2,
-    totalPages: 8,
-    showPages: false,
-  },
-};
-
-export const SimpleAllSizes: Story = {
-  render: () => (
-    <div className="flex flex-col gap-4 items-start">
-      {(["lg", "md", "sm"] as const).map((size) => (
-        <div key={size} className="flex flex-col gap-1">
-          <span className="font-secondary-body text-text-03">
-            size=&quot;{size}&quot;
-          </span>
-          <Pagination
-            variant="simple"
-            currentPage={3}
-            totalPages={10}
-            size={size}
-          />
-        </div>
-      ))}
-    </div>
-  ),
-};
-
-// ===========================================================================
-// variant="count"
-// ===========================================================================
-
-export const Count: Story = {
-  args: {
-    variant: "count",
-    pageSize: 10,
-    totalItems: 95,
-    currentPage: 2,
-    totalPages: 10,
-  },
-};
-
-export const CountWithUnits: Story = {
-  args: {
-    variant: "count",
-    pageSize: 25,
-    totalItems: 203,
-    currentPage: 1,
-    totalPages: 9,
-    units: "items",
-  },
-};
-
-export const CountWithGoto: Story = {
-  args: {
-    variant: "count",
-    pageSize: 10,
-    totalItems: 95,
-    currentPage: 3,
-    totalPages: 10,
-    goto: () => alert("Go to clicked"),
-  },
-};
-
-export const CountArrowsOnly: Story = {
-  args: {
-    variant: "count",
-    pageSize: 10,
-    totalItems: 50,
-    currentPage: 2,
-    totalPages: 5,
-    showPages: false,
-  },
-};
-
-export const CountAllSizes: Story = {
-  render: () => (
-    <div className="flex flex-col gap-4 items-start">
-      {(["lg", "md", "sm"] as const).map((size) => (
-        <div key={size} className="flex flex-col gap-1">
-          <span className="font-secondary-body text-text-03">
-            size=&quot;{size}&quot;
-          </span>
-          <Pagination
-            variant="count"
-            pageSize={10}
-            totalItems={95}
-            currentPage={3}
-            totalPages={10}
-            size={size}
-            units="items"
-          />
-        </div>
-      ))}
-    </div>
-  ),
-};
-
-// ===========================================================================
-// variant="list" (default)
-// ===========================================================================
-
-export const List: Story = {
-  args: {
-    currentPage: 5,
-    totalPages: 20,
-    onPageClick: () => {},
-  },
-};
-
-export const ListFewPages: Story = {
-  args: {
-    currentPage: 2,
-    totalPages: 4,
-    onPageClick: () => {},
-  },
-};
-
-export const ListAllSizes: Story = {
-  render: () => (
-    <div className="flex flex-col gap-4 items-start">
-      {(["lg", "md", "sm"] as const).map((size) => (
-        <div key={size} className="flex flex-col gap-1">
-          <span className="font-secondary-body text-text-03">
-            size=&quot;{size}&quot;
-          </span>
-          <Pagination
-            currentPage={3}
-            totalPages={10}
-            onPageClick={() => {}}
-            size={size}
-          />
-        </div>
-      ))}
-    </div>
-  ),
-};
-
-// ===========================================================================
-// Interactive
-// ===========================================================================
-
-function InteractiveSimpleDemo() {
-  const [page, setPage] = useState(1);
-  return (
-    <div className="flex flex-col gap-4 items-start">
-      <Pagination
-        variant="simple"
-        currentPage={page}
-        totalPages={15}
-        onArrowClick={setPage}
-        units="pages"
-      />
-      <span className="font-secondary-body text-text-03">
-        Current page: {page}
-      </span>
-    </div>
-  );
-}
-
-export const InteractiveSimple: Story = {
-  render: () => <InteractiveSimpleDemo />,
-};
-
-function InteractiveListDemo() {
-  const [page, setPage] = useState(1);
-  return (
-    <div className="flex flex-col gap-4 items-start">
-      <Pagination currentPage={page} totalPages={15} onPageClick={setPage} />
-      <span className="font-secondary-body text-text-03">
-        Current page: {page}
-      </span>
-    </div>
-  );
-}
-
-export const InteractiveList: Story = {
-  render: () => <InteractiveListDemo />,
-};

web/lib/opal/src/components/pagination/README.md

@@ -1,101 +0,0 @@
-# Pagination
-
-**Import:** `import { Pagination, type PaginationProps } from "@opal/components";`
-
-Page navigation with three display variants and prev/next arrow controls.
-
-## Variants
-
-### `"list"` (default)
-
-Numbered page buttons with ellipsis truncation for large page counts.
-
-```tsx
-<Pagination currentPage={3} totalPages={10} onPageClick={setPage} />
-```
-
-### `"simple"`
-
-Compact `currentPage/totalPages` display with prev/next arrows. Can be reduced to just arrows via `showPages={false}`.
-
-```tsx
-// With summary (default)
-<Pagination variant="simple" currentPage={1} totalPages={5} onArrowClick={setPage} />
-
-// Arrows only
-<Pagination variant="simple" currentPage={1} totalPages={5} onArrowClick={setPage} showPages={false} />
-
-// With units
-<Pagination variant="simple" currentPage={1} totalPages={5} onArrowClick={setPage} units="pages" />
-```
-
-### `"count"`
-
-Item-count display (`X~Y of Z`) with prev/next arrows. Designed for table footers.
-
-```tsx
-// Basic
-<Pagination
-  variant="count"
-  pageSize={10}
-  totalItems={95}
-  currentPage={2}
-  totalPages={10}
-  onArrowClick={setPage}
-/>
-
-// With units and goto
-<Pagination
-  variant="count"
-  pageSize={10}
-  totalItems={95}
-  currentPage={2}
-  totalPages={10}
-  onArrowClick={setPage}
-  units="items"
-  goto={() => openGoToDialog()}
-/>
-```
-
-## Props (shared)
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `variant` | `"list" \| "simple" \| "count"` | `"list"` | Display variant |
-| `currentPage` | `number` | **(required)** | 1-based current page number |
-| `totalPages` | `number` | **(required)** | Total number of pages |
-| `size` | `PaginationSize` | `"lg"` | Button and text sizing |
-
-## Props (variant-specific)
-
-### `"simple"`
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `onArrowClick` | `(page: number) => void` | — | Called when a prev/next arrow is clicked |
-| `size` | `PaginationSize` | `"lg"` | Button and text sizing |
-| `showPages` | `boolean` | `true` | Show `currentPage/totalPages` text between arrows |
-| `units` | `string` | — | Label after the summary (e.g. `"pages"`), always 4px spacing |
-
-### `"count"`
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `onArrowClick` | `(page: number) => void` | — | Called when a prev/next arrow is clicked |
-| `pageSize` | `number` | **(required)** | Items per page (for range calculation) |
-| `totalItems` | `number` | **(required)** | Total item count |
-| `size` | `PaginationSize` | `"lg"` | Button and text sizing |
-| `showPages` | `boolean` | `true` | Show current page number between arrows |
-| `units` | `string` | — | Label after the total (e.g. `"items"`), always 4px spacing |
-| `goto` | `() => void` | — | Renders a "Go to" button with matching size |
-
-### `"list"`
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `onPageClick` | `(page: number) => void` | **(required)** | Called when a page is selected (via page button or arrow) |
-| `size` | `PaginationSize` | `"lg"` | Button and text sizing |
-
-### `PaginationSize`
-
-`"lg" | "md" | "sm"`

web/lib/opal/src/components/pagination/components.tsx

@@ -1,444 +0,0 @@
-import { Button } from "@opal/components";
-import { Disabled } from "@opal/core";
-import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
-import type { WithoutStyles } from "@opal/types";
-import { cn } from "@opal/utils";
-import type { HTMLAttributes, ReactNode } from "react";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type PaginationSize = "lg" | "md" | "sm";
-
-/**
- * Compact `currentPage / totalPages` display with prev/next arrows.
- */
-interface SimplePaginationProps
-  extends Omit<WithoutStyles<HTMLAttributes<HTMLDivElement>>, "onChange"> {
-  variant: "simple";
-  /** The 1-based current page number. */
-  currentPage: number;
-  /** Total number of pages. */
-  totalPages: number;
-  /** Called when a prev/next arrow is clicked. */
-  onArrowClick?: (page: number) => void;
-  /** Controls button and text sizing. Default: `"lg"`. */
-  size?: PaginationSize;
-  /** Whether to show the `currentPage/totalPages` summary text. Default: `true`. */
-  showPages?: boolean;
-  /** Unit label shown after the summary (e.g. `"pages"`). Always has 4px spacing. */
-  units?: string;
-}
-
-/**
- * Item-count display (`X~Y of Z`) with prev/next arrows.
- * Designed for table footers.
- */
-interface CountPaginationProps
-  extends Omit<WithoutStyles<HTMLAttributes<HTMLDivElement>>, "onChange"> {
-  variant: "count";
-  /** The 1-based current page number. */
-  currentPage: number;
-  /** Total number of pages. */
-  totalPages: number;
-  /** Number of items displayed per page. Used to compute the visible range. */
-  pageSize: number;
-  /** Total number of items across all pages. */
-  totalItems: number;
-  /** Called when a prev/next arrow is clicked. */
-  onArrowClick?: (page: number) => void;
-  /** Controls button and text sizing. Default: `"lg"`. */
-  size?: PaginationSize;
-  /** Whether to show the current page number between the arrows. Default: `true`. */
-  showPages?: boolean;
-  /** Unit label shown after the total count (e.g. `"items"`). Always has 4px spacing. */
-  units?: string;
-  /** If provided, renders a "Go to" button that calls this callback when clicked. */
-  goto?: () => void;
-}
-
-/**
- * Numbered page buttons with ellipsis truncation for large page counts.
- * This is the default variant.
- */
-interface ListPaginationProps
-  extends Omit<WithoutStyles<HTMLAttributes<HTMLDivElement>>, "onChange"> {
-  variant?: "list";
-  /** The 1-based current page number. */
-  currentPage: number;
-  /** Total number of pages. */
-  totalPages: number;
-  /** Called when a page is selected (via page button or arrow). */
-  onPageClick: (page: number) => void;
-  /** Controls button and text sizing. Default: `"lg"`. */
-  size?: PaginationSize;
-}
-
-/**
- * Discriminated union of all pagination variants.
- * Use `variant` to select between `"simple"`, `"count"`, and `"list"` (default).
- */
-type PaginationProps =
-  | SimplePaginationProps
-  | CountPaginationProps
-  | ListPaginationProps;
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Computes the page numbers to display.
- *
- * - <=7 pages: render all pages individually (no ellipsis).
- * - >7 pages: always render exactly 7 slots (numbers or ellipsis).
- *   First and last page are always shown. Ellipsis takes one slot.
- *
- * Examples for totalPages=20:
- * - page 1:  `1  2  3  4  5  ...  20`
- * - page 4:  `1  2  3  4  5  ...  20`
- * - page 5:  `1  ...  4  5  6  ...  20`
- * - page 16: `1  ...  15  16  17  ...  20`
- * - page 17: `1  ...  16  17  18  19  20`
- * - page 20: `1  ...  16  17  18  19  20`
- */
-function getPageNumbers(
-  currentPage: number,
-  totalPages: number
-): (number | string)[] {
-  if (totalPages <= 7) {
-    const pages: number[] = [];
-    for (let i = 1; i <= totalPages; i++) pages.push(i);
-    return pages;
-  }
-
-  // Always 7 slots. First and last are always page 1 and totalPages.
-  // That leaves 5 inner slots.
-
-  // Near the start: no start-ellipsis needed
-  // Slots: 1, 2, 3, 4, 5, ..., totalPages
-  if (currentPage <= 4) {
-    return [1, 2, 3, 4, 5, "end-ellipsis", totalPages];
-  }
-
-  // Near the end: no end-ellipsis needed
-  // Slots: 1, ..., tp-4, tp-3, tp-2, tp-1, tp
-  if (currentPage >= totalPages - 3) {
-    return [
-      1,
-      "start-ellipsis",
-      totalPages - 4,
-      totalPages - 3,
-      totalPages - 2,
-      totalPages - 1,
-      totalPages,
-    ];
-  }
-
-  // Middle: both ellipses
-  // Slots: 1, ..., cur-1, cur, cur+1, ..., totalPages
-  return [
-    1,
-    "start-ellipsis",
-    currentPage - 1,
-    currentPage,
-    currentPage + 1,
-    "end-ellipsis",
-    totalPages,
-  ];
-}
-
-function monoClass(size: PaginationSize): string {
-  return size === "sm" ? "font-secondary-mono" : "font-main-ui-mono";
-}
-
-function textClasses(size: PaginationSize, style: "mono" | "muted"): string {
-  if (style === "mono") return monoClass(size);
-  return size === "sm" ? "font-secondary-body" : "font-main-ui-muted";
-}
-
-/** Matches the icon-only Button dimensions for each size. */
-const ELLIPSIS_SIZE: Record<PaginationSize, string> = {
-  lg: "w-[2.25rem] h-[2.25rem]",
-  md: "w-[1.75rem] h-[1.75rem]",
-  sm: "w-[1.5rem] h-[1.5rem]",
-};
-
-const PAGE_NUMBER_FONT: Record<
-  PaginationSize,
-  { active: string; inactive: string }
-> = {
-  lg: {
-    active: "font-main-ui-body text-text-04",
-    inactive: "font-main-ui-muted text-text-02",
-  },
-  md: {
-    active: "font-secondary-action text-text-04",
-    inactive: "font-secondary-body text-text-02",
-  },
-  sm: {
-    active: "font-secondary-action text-text-04",
-    inactive: "font-secondary-body text-text-02",
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Nav buttons (shared across all variants)
-// ---------------------------------------------------------------------------
-
-interface NavButtonsProps {
-  currentPage: number;
-  totalPages: number;
-  onChange: (page: number) => void;
-  size: PaginationSize;
-  children?: ReactNode;
-}
-
-function NavButtons({
-  currentPage,
-  totalPages,
-  onChange,
-  size,
-  children,
-}: NavButtonsProps) {
-  return (
-    <>
-      <Disabled disabled={currentPage <= 1}>
-        <Button
-          icon={SvgChevronLeft}
-          onClick={() => onChange(Math.max(1, currentPage - 1))}
-          size={size}
-          prominence="tertiary"
-          tooltip="Previous page"
-        />
-      </Disabled>
-      {children}
-      <Disabled disabled={currentPage >= totalPages}>
-        <Button
-          icon={SvgChevronRight}
-          onClick={() => onChange(Math.min(totalPages, currentPage + 1))}
-          size={size}
-          prominence="tertiary"
-          tooltip="Next page"
-        />
-      </Disabled>
-    </>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// PaginationSimple
-// ---------------------------------------------------------------------------
-
-function PaginationSimple({
-  currentPage,
-  totalPages,
-  onArrowClick,
-  size = "lg",
-  showPages = true,
-  units,
-  ...props
-}: SimplePaginationProps) {
-  const handleChange = (page: number) => onArrowClick?.(page);
-
-  return (
-    <div {...props} className="flex items-center">
-      <NavButtons
-        currentPage={currentPage}
-        totalPages={totalPages}
-        onChange={handleChange}
-        size={size}
-      >
-        {showPages && (
-          <span className={cn(monoClass(size), "px-1 text-text-03")}>
-            {currentPage}/{totalPages}
-            {units && <span className="ml-1">{units}</span>}
-          </span>
-        )}
-      </NavButtons>
-    </div>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// PaginationCount
-// ---------------------------------------------------------------------------
-
-function PaginationCount({
-  pageSize,
-  totalItems,
-  currentPage,
-  totalPages,
-  onArrowClick,
-  size = "lg",
-  showPages = true,
-  units,
-  goto: onGoto,
-  ...props
-}: CountPaginationProps) {
-  const handleChange = (page: number) => onArrowClick?.(page);
-  const rangeStart = totalItems === 0 ? 0 : (currentPage - 1) * pageSize + 1;
-  const rangeEnd = Math.min(currentPage * pageSize, totalItems);
-
-  return (
-    <div {...props} className="flex items-center gap-1">
-      {/* Summary: range of total [units] */}
-      <span
-        className={cn(
-          "flex items-center gap-1",
-          monoClass(size),
-          "text-text-03"
-        )}
-      >
-        {rangeStart}~{rangeEnd}
-        <span className={textClasses(size, "muted")}>of</span>
-        {totalItems}
-        {units && <span className="ml-1">{units}</span>}
-      </span>
-
-      {/* Buttons: < [page] > */}
-      <div className="flex items-center">
-        <NavButtons
-          currentPage={currentPage}
-          totalPages={totalPages}
-          onChange={handleChange}
-          size={size}
-        >
-          {showPages && (
-            <span
-              className={cn(
-                "flex items-center justify-center",
-                size === "sm" ? "w-[20px]" : "w-[28px]",
-                monoClass(size),
-                "text-text-03"
-              )}
-            >
-              {currentPage}
-            </span>
-          )}
-        </NavButtons>
-      </div>
-
-      {/* Goto */}
-      {onGoto && (
-        <Button onClick={onGoto} size={size} prominence="tertiary">
-          Go to
-        </Button>
-      )}
-    </div>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// PaginationList (default)
-// ---------------------------------------------------------------------------
-
-function PaginationList({
-  currentPage,
-  totalPages,
-  onPageClick,
-  size = "lg",
-  ...props
-}: ListPaginationProps) {
-  const pageNumbers = getPageNumbers(currentPage, totalPages);
-  const fonts = PAGE_NUMBER_FONT[size];
-
-  return (
-    <div {...props} className="flex items-center gap-1">
-      <NavButtons
-        currentPage={currentPage}
-        totalPages={totalPages}
-        onChange={onPageClick}
-        size={size}
-      >
-        <div className="flex items-center">
-          {pageNumbers.map((page) => {
-            if (typeof page === "string") {
-              return (
-                <span
-                  key={page}
-                  className={cn(
-                    "flex items-center justify-center",
-                    ELLIPSIS_SIZE[size],
-                    fonts.inactive
-                  )}
-                >
-                  ...
-                </span>
-              );
-            }
-
-            const isActive = page === currentPage;
-
-            return (
-              <Button
-                key={page}
-                onClick={() => onPageClick(page)}
-                size={size}
-                prominence="tertiary"
-                interaction={isActive ? "hover" : "rest"}
-                icon={({ className: iconClassName }) => (
-                  <div
-                    className={cn(
-                      iconClassName,
-                      "flex flex-col justify-center",
-                      isActive ? fonts.active : fonts.inactive
-                    )}
-                  >
-                    {page}
-                  </div>
-                )}
-              />
-            );
-          })}
-        </div>
-      </NavButtons>
-    </div>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Pagination (entry point)
-// ---------------------------------------------------------------------------
-
-/**
- * Page navigation component with three variants:
- *
- * - `"list"` (default) — Numbered page buttons with ellipsis truncation.
- * - `"simple"` — Compact `currentPage / totalPages` with prev/next arrows.
- * - `"count"` — Item-count display (`X~Y of Z`) with prev/next arrows.
- *
- * @example
- * ```tsx
- * // List (default)
- * <Pagination currentPage={3} totalPages={10} onPageClick={setPage} />
- *
- * // Simple
- * <Pagination variant="simple" currentPage={1} totalPages={5} onArrowClick={setPage} />
- *
- * // Count
- * <Pagination variant="count" pageSize={10} totalItems={95} currentPage={2} totalPages={10} onArrowClick={setPage} />
- * ```
- */
-function Pagination(props: PaginationProps) {
-  const normalized = {
-    ...props,
-    totalPages: Math.max(1, props.totalPages),
-    currentPage: Math.max(
-      1,
-      Math.min(props.currentPage, Math.max(1, props.totalPages))
-    ),
-  };
-  const variant = normalized.variant ?? "list";
-  switch (variant) {
-    case "simple":
-      return <PaginationSimple {...(normalized as SimplePaginationProps)} />;
-    case "count":
-      return <PaginationCount {...(normalized as CountPaginationProps)} />;
-    case "list":
-      return <PaginationList {...(normalized as ListPaginationProps)} />;
-  }
-}
-
-export { Pagination, type PaginationProps, type PaginationSize };

web/src/app/admin/agents/page.tsx

@@ -13,7 +13,7 @@ import { ThreeDotsLoader } from "@/components/Loading";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
 import { useState, useEffect } from "react";
-import { Pagination } from "@opal/components";
+import Pagination from "@/refresh-components/Pagination";
 
 const route = ADMIN_ROUTES.AGENTS;
 const PAGE_SIZE = 20;
@@ -90,7 +90,7 @@ function MainContent({
               <Pagination
                 currentPage={currentPage}
                 totalPages={totalPages}
-                onPageClick={onPageChange}
+                onPageChange={onPageChange}
               />
             )}
           </>

web/src/ee/sections/SearchUI.tsx

@@ -7,7 +7,7 @@ import {
   SourceMetadata,
 } from "@/lib/search/interfaces";
 import SearchCard from "@/ee/sections/SearchCard";
-import { Pagination } from "@opal/components";
+import Pagination from "@/refresh-components/Pagination";
 import Separator from "@/refresh-components/Separator";
 import EmptyMessage from "@/refresh-components/EmptyMessage";
 import { IllustrationContent } from "@opal/layouts";
@@ -394,7 +394,7 @@ export default function SearchUI({ onDocumentClick }: SearchResultsProps) {
         <Pagination
           currentPage={currentPage}
           totalPages={totalPages}
-          onPageClick={setCurrentPage}
+          onPageChange={setCurrentPage}
         />
       )}
     </div>

web/src/hooks/useVoiceRecorder.ts

@@ -1,5 +1,7 @@
 import { useState, useRef, useCallback, useEffect } from "react";
 
+import { IS_DEV } from "@/lib/constants";
+
 // Target format for OpenAI Realtime API
 const TARGET_SAMPLE_RATE = 24000;
 const CHUNK_INTERVAL_MS = 250;
@@ -245,9 +247,8 @@ class VoiceRecorderSession {
     const { token } = await tokenResponse.json();
 
     const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-    const isDev = window.location.port === "3000";
-    const host = isDev ? "localhost:8080" : window.location.host;
-    const path = isDev
+    const host = IS_DEV ? "localhost:8080" : window.location.host;
+    const path = IS_DEV
       ? "/voice/transcribe/stream"
       : "/api/voice/transcribe/stream";
     return `${protocol}//${host}${path}?token=${encodeURIComponent(token)}`;

web/src/layouts/general-layouts.tsx

@@ -176,7 +176,10 @@ function AttachmentItemLayout({
     <Section flexDirection="row" gap={0.25} padding={0.25}>
       <div className={cn("h-[2.25rem] aspect-square rounded-08")}>
         <Section>
-          <div className="attachment-button__icon-wrapper">
+          <div
+            className="attachment-button__icon-wrapper"
+            data-testid="attachment-item-icon-wrapper"
+          >
             <Icon className="attachment-button__icon" />
           </div>
         </Section>
@@ -187,7 +190,7 @@ function AttachmentItemLayout({
         alignItems="center"
         gap={1.5}
       >
-        <div className="flex-1 min-w-0">
+        <div data-testid="attachment-item-title" className="flex-1 min-w-0">
           <Content
             title={title}
             description={description}

web/src/lib/constants.ts

@@ -1,3 +1,5 @@
+export const IS_DEV = process.env.NODE_ENV === "development";
+
 export enum AuthType {
   BASIC = "basic",
   GOOGLE_OAUTH = "google_oauth",

web/src/lib/streamingTTS.ts

@@ -3,6 +3,8 @@
  * Plays audio chunks as they arrive for smooth, low-latency playback.
  */
 
+import { IS_DEV } from "@/lib/constants";
+
 /**
  * HTTPStreamingTTSPlayer - Uses HTTP streaming with MediaSource Extensions
  * for smooth, gapless audio playback. This is the recommended approach for
@@ -382,9 +384,8 @@ export class WebSocketStreamingTTSPlayer {
     const { token } = await tokenResponse.json();
 
     const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-    const isDev = window.location.port === "3000";
-    const host = isDev ? "localhost:8080" : window.location.host;
-    const path = isDev
+    const host = IS_DEV ? "localhost:8080" : window.location.host;
+    const path = IS_DEV
       ? "/voice/synthesize/stream"
       : "/api/voice/synthesize/stream";
     return `${protocol}//${host}${path}?token=${encodeURIComponent(token)}`;

web/src/refresh-components/Pagination.stories.tsx

@@ -0,0 +1,57 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Pagination from "./Pagination";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+const meta: Meta<typeof Pagination> = {
+  title: "refresh-components/Pagination",
+  component: Pagination,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <Story />
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Pagination>;
+
+function PaginationDemo({
+  totalPages,
+  initialPage = 1,
+}: {
+  totalPages: number;
+  initialPage?: number;
+}) {
+  const [page, setPage] = React.useState(initialPage);
+  return (
+    <Pagination
+      currentPage={page}
+      totalPages={totalPages}
+      onPageChange={setPage}
+    />
+  );
+}
+
+export const Default: Story = {
+  render: () => <PaginationDemo totalPages={10} />,
+};
+
+export const FewPages: Story = {
+  render: () => <PaginationDemo totalPages={5} />,
+};
+
+export const ManyPages: Story = {
+  render: () => <PaginationDemo totalPages={50} initialPage={25} />,
+};
+
+export const FirstPage: Story = {
+  render: () => <PaginationDemo totalPages={20} initialPage={1} />,
+};
+
+export const LastPage: Story = {
+  render: () => <PaginationDemo totalPages={20} initialPage={20} />,
+};

web/src/refresh-components/Pagination.tsx

@@ -0,0 +1,119 @@
+import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
+import Text from "@/refresh-components/texts/Text";
+import { cn } from "@/lib/utils";
+import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
+import { Section } from "@/layouts/general-layouts";
+
+interface PaginationProps {
+  currentPage: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+}
+
+export default function Pagination({
+  currentPage,
+  totalPages,
+  onPageChange,
+}: PaginationProps) {
+  // Generate page numbers to display
+  function getPageNumbers() {
+    const pages: (number | string)[] = [];
+    const maxPagesToShow = 7;
+
+    if (totalPages <= maxPagesToShow) {
+      // Show all pages if total is small
+      for (let i = 1; i <= totalPages; i++) {
+        pages.push(i);
+      }
+    } else {
+      // Always show first page
+      pages.push(1);
+
+      // Calculate range around current page
+      let startPage = Math.max(2, currentPage - 1);
+      let endPage = Math.min(totalPages - 1, currentPage + 1);
+
+      // Adjust range if we're near the start or end
+      if (currentPage <= 3) {
+        endPage = 5;
+      } else if (currentPage >= totalPages - 2) {
+        startPage = totalPages - 4;
+      }
+
+      // Add ellipsis if needed
+      if (startPage > 2) {
+        pages.push("...");
+      }
+
+      // Add middle pages
+      for (let i = startPage; i <= endPage; i++) {
+        pages.push(i);
+      }
+
+      // Add ellipsis if needed
+      if (endPage < totalPages - 1) {
+        pages.push("...");
+      }
+
+      // Always show last page
+      pages.push(totalPages);
+    }
+
+    return pages;
+  }
+
+  const pageNumbers = getPageNumbers();
+
+  return (
+    <Section flexDirection="row" height="auto" gap={0.25}>
+      {/* Previous button */}
+      <Disabled disabled={currentPage === 1}>
+        <Button
+          onClick={() => onPageChange(currentPage - 1)}
+          prominence="tertiary"
+          icon={SvgChevronLeft}
+        />
+      </Disabled>
+
+      {/* Page numbers */}
+      <Section flexDirection="row" height="auto" gap={0} width="fit">
+        {pageNumbers.map((page, index) => {
+          if (page === "...") {
+            return (
+              <Text key={`ellipsis-${index}`} secondaryBody text03>
+                ...
+              </Text>
+            );
+          }
+
+          const pageNum = page as number;
+          const isActive = pageNum === currentPage;
+
+          return (
+            <Button
+              key={pageNum}
+              onClick={() => onPageChange(pageNum)}
+              prominence="tertiary"
+              interaction={isActive ? "hover" : "rest"}
+              icon={({ className }) => (
+                <div className={cn(className, "flex flex-col justify-center")}>
+                  <Text>{pageNum}</Text>
+                </div>
+              )}
+            />
+          );
+        })}
+      </Section>
+
+      {/* Next button */}
+      <Disabled disabled={currentPage === totalPages}>
+        <Button
+          onClick={() => onPageChange(currentPage + 1)}
+          prominence="tertiary"
+          icon={SvgChevronRight}
+        />
+      </Disabled>
+    </Section>
+  );
+}

web/src/refresh-components/table/DataTable.stories.tsx

@@ -0,0 +1,365 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import DataTable from "./DataTable";
+import { createTableColumns } from "./columns";
+import type { OnyxColumnDef } from "./types";
+import Text from "@/refresh-components/texts/Text";
+
+// ---------------------------------------------------------------------------
+// Mock data
+// ---------------------------------------------------------------------------
+
+interface TeamMember {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: "active" | "invited" | "deactivated";
+  lastActive: string;
+}
+
+const MOCK_MEMBERS: TeamMember[] = [
+  {
+    id: "1",
+    name: "Alice Johnson",
+    email: "alice@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "2 hours ago",
+  },
+  {
+    id: "2",
+    name: "Bob Martinez",
+    email: "bob@acme.com",
+    role: "Editor",
+    status: "active",
+    lastActive: "5 minutes ago",
+  },
+  {
+    id: "3",
+    name: "Charlie Kim",
+    email: "charlie@acme.com",
+    role: "Viewer",
+    status: "invited",
+    lastActive: "Never",
+  },
+  {
+    id: "4",
+    name: "Diana Patel",
+    email: "diana@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "1 day ago",
+  },
+  {
+    id: "5",
+    name: "Ethan Lee",
+    email: "ethan@acme.com",
+    role: "Editor",
+    status: "deactivated",
+    lastActive: "3 weeks ago",
+  },
+  {
+    id: "6",
+    name: "Fiona Chen",
+    email: "fiona@acme.com",
+    role: "Viewer",
+    status: "active",
+    lastActive: "10 minutes ago",
+  },
+  {
+    id: "7",
+    name: "George Wu",
+    email: "george@acme.com",
+    role: "Editor",
+    status: "active",
+    lastActive: "1 hour ago",
+  },
+  {
+    id: "8",
+    name: "Hannah Davis",
+    email: "hannah@acme.com",
+    role: "Viewer",
+    status: "invited",
+    lastActive: "Never",
+  },
+  {
+    id: "9",
+    name: "Ivan Torres",
+    email: "ivan@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "30 minutes ago",
+  },
+  {
+    id: "10",
+    name: "Julia Nguyen",
+    email: "julia@acme.com",
+    role: "Editor",
+    status: "active",
+    lastActive: "3 hours ago",
+  },
+  {
+    id: "11",
+    name: "Kevin Brown",
+    email: "kevin@acme.com",
+    role: "Viewer",
+    status: "active",
+    lastActive: "Yesterday",
+  },
+  {
+    id: "12",
+    name: "Laura Smith",
+    email: "laura@acme.com",
+    role: "Editor",
+    status: "deactivated",
+    lastActive: "2 months ago",
+  },
+  {
+    id: "13",
+    name: "Mike Wilson",
+    email: "mike@acme.com",
+    role: "Viewer",
+    status: "active",
+    lastActive: "4 hours ago",
+  },
+  {
+    id: "14",
+    name: "Nina Garcia",
+    email: "nina@acme.com",
+    role: "Admin",
+    status: "active",
+    lastActive: "Just now",
+  },
+  {
+    id: "15",
+    name: "Oscar Ramirez",
+    email: "oscar@acme.com",
+    role: "Editor",
+    status: "invited",
+    lastActive: "Never",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+function getInitials(member: TeamMember): string {
+  return member.name
+    .split(" ")
+    .map((n) => n[0])
+    .join("")
+    .toUpperCase();
+}
+
+const tc = createTableColumns<TeamMember>();
+
+const defaultColumns: OnyxColumnDef<TeamMember>[] = [
+  tc.qualifier({
+    content: "avatar-user",
+    getInitials,
+    selectable: true,
+  }),
+  tc.column("name", { header: "Name", weight: 22, minWidth: 120 }),
+  tc.column("email", { header: "Email", weight: 28, minWidth: 150 }),
+  tc.column("role", { header: "Role", weight: 15, minWidth: 80 }),
+  tc.column("status", {
+    header: "Status",
+    weight: 15,
+    minWidth: 80,
+    cell: (value) => {
+      const colors: Record<string, string> = {
+        active: "text-status-success-02",
+        invited: "text-status-warning-02",
+        deactivated: "text-status-error-02",
+      };
+      return (
+        <Text mainUiBody className={colors[value]}>
+          {value.charAt(0).toUpperCase() + value.slice(1)}
+        </Text>
+      );
+    },
+  }),
+  tc.column("lastActive", {
+    header: "Last Active",
+    weight: 20,
+    minWidth: 100,
+    enableSorting: false,
+  }),
+  tc.actions(),
+];
+
+const columnsWithoutActions: OnyxColumnDef<TeamMember>[] = defaultColumns.slice(
+  0,
+  -1
+);
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta<typeof DataTable> = {
+  title: "refresh-components/table/DataTable",
+  component: DataTable,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <div style={{ maxWidth: 960, padding: 16 }}>
+          <Story />
+        </div>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DataTable>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Basic table with all default features: qualifier column, data columns, and actions. */
+export const Default: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 8)}
+      columns={defaultColumns}
+    />
+  ),
+};
+
+/** Table with summary-mode footer showing "Showing X~Y of Z" and list pagination. */
+export const WithSummaryFooter: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      pageSize={5}
+      footer={{ mode: "summary" }}
+    />
+  ),
+};
+
+/** Table with selection-mode footer showing selected count and count pagination. */
+export const WithSelectionFooter: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      pageSize={5}
+      footer={{ mode: "selection" }}
+    />
+  ),
+};
+
+/** Table with initial sorting applied to the "name" column. */
+export const WithInitialSorting: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      pageSize={5}
+      footer={{ mode: "summary" }}
+      initialSorting={[{ id: "name", desc: false }]}
+    />
+  ),
+};
+
+/** Table with some columns hidden by default via initialColumnVisibility. */
+export const WithHiddenColumns: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 8)}
+      columns={defaultColumns}
+      initialColumnVisibility={{ email: false, lastActive: false }}
+    />
+  ),
+};
+
+/** Empty table with no data rows. */
+export const EmptyState: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={[]}
+      columns={defaultColumns}
+      footer={{ mode: "summary" }}
+    />
+  ),
+};
+
+/** Small size variant with denser spacing. */
+export const SmallSize: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 6)}
+      columns={defaultColumns}
+      size="small"
+      footer={{ mode: "summary" }}
+      pageSize={5}
+    />
+  ),
+};
+
+/** Table without actions column (no sorting/visibility popovers). */
+export const WithoutActions: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS.slice(0, 8)}
+      columns={columnsWithoutActions}
+    />
+  ),
+};
+
+/** Table with a fixed max height and sticky header for scrollable content. */
+export const ScrollableFixedHeight: Story = {
+  render: () => (
+    <DataTable<TeamMember>
+      getRowId={(row) => row.id}
+      data={MOCK_MEMBERS}
+      columns={defaultColumns}
+      height={300}
+      headerBackground="var(--background-neutral-00)"
+      pageSize={Infinity}
+    />
+  ),
+};
+
+/** Table with onRowClick handler instead of default selection toggle. */
+export const WithRowClick: Story = {
+  render: () => {
+    function Demo() {
+      const [clicked, setClicked] = React.useState<string | null>(null);
+      return (
+        <div>
+          <DataTable<TeamMember>
+            getRowId={(row) => row.id}
+            data={MOCK_MEMBERS.slice(0, 5)}
+            columns={defaultColumns}
+            onRowClick={(row) => setClicked(row.name)}
+          />
+          {clicked && (
+            <Text mainUiBody text03 className="p-4">
+              Clicked: {clicked}
+            </Text>
+          )}
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};

web/src/refresh-components/table/Footer.stories.tsx

@@ -0,0 +1,183 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import Footer from "./Footer";
+import { TableSizeProvider } from "./TableSizeContext";
+
+const meta: Meta<typeof Footer> = {
+  title: "refresh-components/table/Footer",
+  component: Footer,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <TableSizeProvider size="regular">
+          <div style={{ maxWidth: 800, padding: 16 }}>
+            <Story />
+          </div>
+        </TableSizeProvider>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  parameters: {
+    layout: "padded",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Footer>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Summary mode footer showing "Showing X~Y of Z" with list pagination. */
+export const SummaryMode: Story = {
+  render: function SummaryModeStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={(page - 1) * 10 + 1}
+        rangeEnd={Math.min(page * 10, 47)}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Summary mode on the last page. */
+export const SummaryLastPage: Story = {
+  render: function SummaryLastPageStory() {
+    const [page, setPage] = React.useState(5);
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={(page - 1) * 10 + 1}
+        rangeEnd={Math.min(page * 10, 47)}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Selection mode with no items selected. */
+export const SelectionNone: Story = {
+  render: function SelectionNoneStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect
+        selectionState="none"
+        selectedCount={0}
+        onClear={() => {}}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Selection mode with some items selected. */
+export const SelectionPartial: Story = {
+  render: function SelectionPartialStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect
+        selectionState="partial"
+        selectedCount={3}
+        onView={() => alert("View selected")}
+        onClear={() => alert("Clear selection")}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Selection mode with all items selected. */
+export const SelectionAll: Story = {
+  render: function SelectionAllStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect
+        selectionState="all"
+        selectedCount={10}
+        onView={() => alert("View selected")}
+        onClear={() => alert("Clear selection")}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Single-select mode (no multi-select). */
+export const SingleSelect: Story = {
+  render: function SingleSelectStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="selection"
+        multiSelect={false}
+        selectionState="partial"
+        selectedCount={1}
+        onClear={() => alert("Clear selection")}
+        pageSize={10}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};
+
+/** Small size variant. */
+export const SmallSize: Story = {
+  decorators: [
+    (Story) => (
+      <TooltipPrimitive.Provider>
+        <TableSizeProvider size="small">
+          <div style={{ maxWidth: 800, padding: 16 }}>
+            <Story />
+          </div>
+        </TableSizeProvider>
+      </TooltipPrimitive.Provider>
+    ),
+  ],
+  render: function SmallSizeStory() {
+    const [page, setPage] = React.useState(1);
+    return (
+      <Footer
+        mode="summary"
+        rangeStart={(page - 1) * 10 + 1}
+        rangeEnd={Math.min(page * 10, 47)}
+        totalItems={47}
+        currentPage={page}
+        totalPages={5}
+        onPageChange={setPage}
+      />
+    );
+  },
+};

web/src/refresh-components/table/Footer.tsx

@@ -1,16 +1,13 @@
 "use client";
 
 import { cn } from "@/lib/utils";
-import { Button, Pagination } from "@opal/components";
+import { Button } from "@opal/components";
 import Text from "@/refresh-components/texts/Text";
+import Pagination from "@/refresh-components/table/Pagination";
 import { useTableSize } from "@/refresh-components/table/TableSizeContext";
 import type { TableSize } from "@/refresh-components/table/TableSizeContext";
 import { SvgEye, SvgXCircle } from "@opal/icons";
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
 type SelectionState = "none" | "partial" | "all";
 
 /**
@@ -66,6 +63,8 @@ interface FooterSummaryModeProps {
   onPageChange: (page: number) => void;
   /** Optional extra element rendered after the summary text (e.g. a download icon). */
   leftExtra?: React.ReactNode;
+  /** Controls overall footer sizing. `"regular"` (default) or `"small"`. */
+  size?: TableSize;
   className?: string;
 }
 
@@ -76,10 +75,6 @@ interface FooterSummaryModeProps {
  */
 export type FooterProps = FooterSelectionModeProps | FooterSummaryModeProps;
 
-// ---------------------------------------------------------------------------
-// Footer
-// ---------------------------------------------------------------------------
-
 function getSelectionMessage(
   state: SelectionState,
   multi: boolean,
@@ -98,7 +93,8 @@ function getSelectionMessage(
  * `mode: "summary"` for read-only tables.
  */
 export default function Footer(props: FooterProps) {
-  const resolvedSize = useTableSize();
+  const contextSize = useTableSize();
+  const resolvedSize = props.size ?? contextSize;
   const isSmall = resolvedSize === "small";
   return (
     <div
@@ -137,20 +133,21 @@ export default function Footer(props: FooterProps) {
       <div className="flex items-center gap-2 px-1 py-2">
         {props.mode === "selection" ? (
           <Pagination
-            variant="count"
+            type="count"
             pageSize={props.pageSize}
             totalItems={props.totalItems}
             currentPage={props.currentPage}
             totalPages={props.totalPages}
-            onArrowClick={props.onPageChange}
-            units="items"
+            onPageChange={props.onPageChange}
+            showUnits
             size={isSmall ? "sm" : "md"}
           />
         ) : (
           <Pagination
+            type="list"
             currentPage={props.currentPage}
             totalPages={props.totalPages}
-            onPageClick={props.onPageChange}
+            onPageChange={props.onPageChange}
             size={isSmall ? "md" : "lg"}
           />
         )}
@@ -159,10 +156,6 @@ export default function Footer(props: FooterProps) {
   );
 }
 
-// ---------------------------------------------------------------------------
-// Footer — left-side content
-// ---------------------------------------------------------------------------
-
 interface SelectionLeftProps {
   selectionState: SelectionState;
   multiSelect: boolean;

web/src/refresh-components/table/Pagination.tsx

@@ -0,0 +1,396 @@
+"use client";
+
+import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
+import Text from "@/refresh-components/texts/Text";
+import { cn } from "@/lib/utils";
+import { SvgChevronLeft, SvgChevronRight } from "@opal/icons";
+
+type PaginationSize = "lg" | "md" | "sm";
+
+/**
+ * Minimal page navigation showing `currentPage / totalPages` with prev/next arrows.
+ * Use when you only need simple forward/backward navigation.
+ */
+interface SimplePaginationProps {
+  type: "simple";
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** When `true`, displays the word "pages" after the page indicator. */
+  showUnits?: boolean;
+  /** When `false`, hides the page indicator between the prev/next arrows. Defaults to `true`. */
+  showPageIndicator?: boolean;
+  /** Controls button and text sizing. Defaults to `"lg"`. */
+  size?: PaginationSize;
+  className?: string;
+}
+
+/**
+ * Item-count pagination showing `currentItems of totalItems` with optional page
+ * controls and a "Go to" button. Use inside table footers that need to communicate
+ * how many items the user is viewing.
+ */
+interface CountPaginationProps {
+  type: "count";
+  /** Number of items displayed per page. Used to compute the visible range. */
+  pageSize: number;
+  /** Total number of items across all pages. */
+  totalItems: number;
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** When `false`, hides the page number between the prev/next arrows (arrows still visible). Defaults to `true`. */
+  showPageIndicator?: boolean;
+  /** When `true`, renders a "Go to" button. Requires `onGoTo`. */
+  showGoTo?: boolean;
+  /** Callback invoked when the "Go to" button is clicked. */
+  onGoTo?: () => void;
+  /** When `true`, displays the word "items" after the total count. */
+  showUnits?: boolean;
+  /** Controls button and text sizing. Defaults to `"lg"`. */
+  size?: PaginationSize;
+  className?: string;
+}
+
+/**
+ * Numbered page-list pagination with clickable page buttons and ellipsis
+ * truncation for large page counts. Does not support `"sm"` size.
+ */
+interface ListPaginationProps {
+  type: "list";
+  /** The 1-based current page number. */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Called when the user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** When `false`, hides the page buttons between the prev/next arrows. Defaults to `true`. */
+  showPageIndicator?: boolean;
+  /** Controls button and text sizing. Defaults to `"lg"`. Only `"lg"` and `"md"` are supported. */
+  size?: Exclude<PaginationSize, "sm">;
+  className?: string;
+}
+
+/**
+ * Discriminated union of all pagination variants.
+ * Use the `type` prop to select between `"simple"`, `"count"`, and `"list"`.
+ */
+export type PaginationProps =
+  | SimplePaginationProps
+  | CountPaginationProps
+  | ListPaginationProps;
+
+function getPageNumbers(currentPage: number, totalPages: number) {
+  const pages: (number | string)[] = [];
+  const maxPagesToShow = 7;
+
+  if (totalPages <= maxPagesToShow) {
+    for (let i = 1; i <= totalPages; i++) {
+      pages.push(i);
+    }
+  } else {
+    pages.push(1);
+
+    let startPage = Math.max(2, currentPage - 1);
+    let endPage = Math.min(totalPages - 1, currentPage + 1);
+
+    if (currentPage <= 3) {
+      endPage = 5;
+    } else if (currentPage >= totalPages - 2) {
+      startPage = totalPages - 4;
+    }
+
+    if (startPage > 2) {
+      if (startPage === 3) {
+        pages.push(2);
+      } else {
+        pages.push("start-ellipsis");
+      }
+    }
+
+    for (let i = startPage; i <= endPage; i++) {
+      pages.push(i);
+    }
+
+    if (endPage < totalPages - 1) {
+      if (endPage === totalPages - 2) {
+        pages.push(totalPages - 1);
+      } else {
+        pages.push("end-ellipsis");
+      }
+    }
+
+    pages.push(totalPages);
+  }
+
+  return pages;
+}
+
+function sizedTextProps(isSmall: boolean, variant: "mono" | "muted") {
+  if (variant === "mono") {
+    return isSmall ? { secondaryMono: true } : { mainUiMono: true };
+  }
+  return isSmall ? { secondaryBody: true } : { mainUiMuted: true };
+}
+
+interface NavButtonsProps {
+  currentPage: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+  size: PaginationSize;
+  children?: React.ReactNode;
+}
+
+function NavButtons({
+  currentPage,
+  totalPages,
+  onPageChange,
+  size,
+  children,
+}: NavButtonsProps) {
+  return (
+    <>
+      <Disabled disabled={currentPage <= 1}>
+        <Button
+          icon={SvgChevronLeft}
+          onClick={() => onPageChange(currentPage - 1)}
+          size={size}
+          prominence="tertiary"
+          tooltip="Previous page"
+        />
+      </Disabled>
+      {children}
+      <Disabled disabled={currentPage >= totalPages}>
+        <Button
+          icon={SvgChevronRight}
+          onClick={() => onPageChange(currentPage + 1)}
+          size={size}
+          prominence="tertiary"
+          tooltip="Next page"
+        />
+      </Disabled>
+    </>
+  );
+}
+
+/**
+ * Table pagination component with three variants: `simple`, `count`, and `list`.
+ * Pass the `type` prop to select the variant, and the component will render the
+ * appropriate UI.
+ */
+export default function Pagination(props: PaginationProps) {
+  const normalized = { ...props, totalPages: Math.max(1, props.totalPages) };
+  switch (normalized.type) {
+    case "simple":
+      return <SimplePaginationInner {...normalized} />;
+    case "count":
+      return <CountPaginationInner {...normalized} />;
+    case "list":
+      return <ListPaginationInner {...normalized} />;
+  }
+}
+
+function SimplePaginationInner({
+  currentPage,
+  totalPages,
+  onPageChange,
+  showUnits,
+  showPageIndicator = true,
+  size = "lg",
+  className,
+}: SimplePaginationProps) {
+  const isSmall = size === "sm";
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      <NavButtons
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={onPageChange}
+        size={size}
+      >
+        {showPageIndicator && (
+          <>
+            <Text {...sizedTextProps(isSmall, "mono")} text03>
+              {currentPage}
+              <Text as="span" {...sizedTextProps(isSmall, "muted")} text03>
+                /
+              </Text>
+              {totalPages}
+            </Text>
+            {showUnits && (
+              <Text {...sizedTextProps(isSmall, "muted")} text03>
+                pages
+              </Text>
+            )}
+          </>
+        )}
+      </NavButtons>
+    </div>
+  );
+}
+
+function CountPaginationInner({
+  pageSize,
+  totalItems,
+  currentPage,
+  totalPages,
+  onPageChange,
+  showPageIndicator = true,
+  showGoTo,
+  onGoTo,
+  showUnits,
+  size = "lg",
+  className,
+}: CountPaginationProps) {
+  const isSmall = size === "sm";
+  const rangeStart = totalItems === 0 ? 0 : (currentPage - 1) * pageSize + 1;
+  const rangeEnd = Math.min(currentPage * pageSize, totalItems);
+  const currentItems = `${rangeStart}~${rangeEnd}`;
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      <Text {...sizedTextProps(isSmall, "mono")} text03>
+        {currentItems}
+      </Text>
+      <Text {...sizedTextProps(isSmall, "muted")} text03>
+        of
+      </Text>
+      <Text {...sizedTextProps(isSmall, "mono")} text03>
+        {totalItems}
+      </Text>
+      {showUnits && (
+        <Text {...sizedTextProps(isSmall, "muted")} text03>
+          items
+        </Text>
+      )}
+
+      <NavButtons
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={onPageChange}
+        size={size}
+      >
+        {showPageIndicator && (
+          <Text {...sizedTextProps(isSmall, "mono")} text03>
+            {currentPage}
+          </Text>
+        )}
+      </NavButtons>
+
+      {showGoTo && onGoTo && (
+        <Button onClick={onGoTo} size={size} prominence="tertiary">
+          Go to
+        </Button>
+      )}
+    </div>
+  );
+}
+
+interface PageNumberIconProps {
+  className?: string;
+  pageNum: number;
+  isActive: boolean;
+  isLarge: boolean;
+}
+
+function PageNumberIcon({
+  className: iconClassName,
+  pageNum,
+  isActive,
+  isLarge,
+}: PageNumberIconProps) {
+  return (
+    <div className={cn(iconClassName, "flex flex-col justify-center")}>
+      {isLarge ? (
+        <Text
+          mainUiBody={isActive}
+          mainUiMuted={!isActive}
+          text04={isActive}
+          text02={!isActive}
+        >
+          {pageNum}
+        </Text>
+      ) : (
+        <Text
+          secondaryAction={isActive}
+          secondaryBody={!isActive}
+          text04={isActive}
+          text02={!isActive}
+        >
+          {pageNum}
+        </Text>
+      )}
+    </div>
+  );
+}
+
+function ListPaginationInner({
+  currentPage,
+  totalPages,
+  onPageChange,
+  showPageIndicator = true,
+  size = "lg",
+  className,
+}: ListPaginationProps) {
+  const pageNumbers = getPageNumbers(currentPage, totalPages);
+  const isLarge = size === "lg";
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      <NavButtons
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={onPageChange}
+        size={size}
+      >
+        {showPageIndicator && (
+          <div className="flex items-center">
+            {pageNumbers.map((page) => {
+              if (typeof page === "string") {
+                return (
+                  <Text
+                    key={page}
+                    mainUiMuted={isLarge}
+                    secondaryBody={!isLarge}
+                    text03
+                  >
+                    ...
+                  </Text>
+                );
+              }
+
+              const pageNum = page as number;
+              const isActive = pageNum === currentPage;
+
+              return (
+                <Button
+                  key={pageNum}
+                  onClick={() => onPageChange(pageNum)}
+                  size={size}
+                  prominence="tertiary"
+                  interaction={isActive ? "hover" : "rest"}
+                  icon={({ className: iconClassName }) => (
+                    <PageNumberIcon
+                      className={iconClassName}
+                      pageNum={pageNum}
+                      isActive={isActive}
+                      isLarge={isLarge}
+                    />
+                  )}
+                />
+              );
+            })}
+          </div>
+        )}
+      </NavButtons>
+    </div>
+  );
+}

web/tests/e2e/chat/project_files_visual_regression.spec.ts

@@ -0,0 +1,181 @@
+import { expect, test, type Locator, type Page } from "@playwright/test";
+import { loginAsWorkerUser } from "@tests/e2e/utils/auth";
+import { OnyxApiClient } from "@tests/e2e/utils/onyxApiClient";
+import { expectElementScreenshot } from "@tests/e2e/utils/visualRegression";
+
+const TEST_PREFIX = "E2E-PROJECT-FILES-VISUAL";
+const ATTACHMENT_ITEM_TITLE_TEST_ID = "attachment-item-title";
+const ATTACHMENT_ITEM_ICON_WRAPPER_TEST_ID = "attachment-item-icon-wrapper";
+const LONG_FILE_NAME =
+  "CSE_202_Final_Project_Solution_Regression_Check_Long_Name.txt";
+const FILE_CONTENT = "Visual regression test content for long filename cards.";
+
+let projectId: number | null = null;
+
+type Geometry = {
+  elementLeft: number;
+  elementRight: number;
+  elementTop: number;
+  elementBottom: number;
+  cardLeft: number;
+  cardRight: number;
+  cardTop: number;
+  cardBottom: number;
+};
+
+function getFilesSection(page: Page): Locator {
+  return page
+    .locator("div")
+    .filter({ has: page.getByRole("button", { name: "Add Files" }) })
+    .filter({ hasText: "Chats in this project can access these files." })
+    .first();
+}
+
+async function uploadFileToProject(
+  page: Page,
+  targetProjectId: number,
+  fileName: string,
+  content: string
+): Promise<void> {
+  const response = await page.request.post("/api/user/projects/file/upload", {
+    multipart: {
+      project_id: String(targetProjectId),
+      files: {
+        name: fileName,
+        mimeType: "text/plain",
+        buffer: Buffer.from(content, "utf-8"),
+      },
+    },
+  });
+
+  expect(response.ok()).toBeTruthy();
+}
+
+async function getElementGeometryInCard(
+  element: Locator
+): Promise<Geometry | null> {
+  return element.evaluate((targetEl) => {
+    let cardEl: HTMLElement | null = targetEl.parentElement;
+
+    while (cardEl) {
+      const style = window.getComputedStyle(cardEl);
+      const hasBorder =
+        parseFloat(style.borderTopWidth) > 0 ||
+        parseFloat(style.borderLeftWidth) > 0;
+      const hasRadius = parseFloat(style.borderTopLeftRadius) > 0;
+
+      if (hasBorder && hasRadius) {
+        break;
+      }
+      cardEl = cardEl.parentElement;
+    }
+
+    if (!cardEl) {
+      return null;
+    }
+
+    const elementRect = targetEl.getBoundingClientRect();
+    const cardRect = cardEl.getBoundingClientRect();
+
+    return {
+      elementLeft: elementRect.left,
+      elementRight: elementRect.right,
+      elementTop: elementRect.top,
+      elementBottom: elementRect.bottom,
+      cardLeft: cardRect.left,
+      cardRight: cardRect.right,
+      cardTop: cardRect.top,
+      cardBottom: cardRect.bottom,
+    };
+  });
+}
+
+function expectGeometryWithinCard(geometry: Geometry | null): void {
+  expect(geometry).not.toBeNull();
+  expect(geometry!.elementLeft).toBeGreaterThanOrEqual(geometry!.cardLeft - 1);
+  expect(geometry!.elementRight).toBeLessThanOrEqual(geometry!.cardRight + 1);
+  expect(geometry!.elementTop).toBeGreaterThanOrEqual(geometry!.cardTop - 1);
+  expect(geometry!.elementBottom).toBeLessThanOrEqual(geometry!.cardBottom + 1);
+}
+
+test.describe("Project Files visual regression", () => {
+  test.beforeAll(async ({ browser }, workerInfo) => {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+
+    await loginAsWorkerUser(page, workerInfo.workerIndex);
+    const client = new OnyxApiClient(page.request);
+
+    projectId = await client.createProject(`${TEST_PREFIX}-${Date.now()}`);
+    await uploadFileToProject(page, projectId, LONG_FILE_NAME, FILE_CONTENT);
+
+    await context.close();
+  });
+
+  test.afterAll(async ({ browser }, workerInfo) => {
+    if (!projectId) {
+      return;
+    }
+
+    const context = await browser.newContext();
+    const page = await context.newPage();
+
+    await loginAsWorkerUser(page, workerInfo.workerIndex);
+    const client = new OnyxApiClient(page.request);
+    await client.deleteProject(projectId);
+
+    await context.close();
+  });
+
+  test.beforeEach(async ({ page }, workerInfo) => {
+    if (projectId === null) {
+      throw new Error(
+        "Project setup failed in beforeAll; cannot run visual regression test"
+      );
+    }
+
+    await page.context().clearCookies();
+    await loginAsWorkerUser(page, workerInfo.workerIndex);
+    await page.goto(`/app?projectId=${projectId}`);
+    await page.waitForLoadState("networkidle");
+    await expect(
+      page.getByText("Chats in this project can access these files.")
+    ).toBeVisible();
+  });
+
+  test("long underscore filename stays visually contained in file card", async ({
+    page,
+  }) => {
+    const filesSection = getFilesSection(page);
+    await expect(filesSection).toBeVisible();
+
+    const fileTitle = filesSection
+      .locator(`[data-testid="${ATTACHMENT_ITEM_TITLE_TEST_ID}"]`)
+      .filter({ hasText: LONG_FILE_NAME })
+      .first();
+    await expect(fileTitle).toBeVisible();
+
+    // Wait for deterministic post-processing state before geometry checks/screenshot.
+    await expect(fileTitle).not.toContainText("Processing...", {
+      timeout: 30_000,
+    });
+    await expect(fileTitle).not.toContainText("Uploading...", {
+      timeout: 30_000,
+    });
+    await expect(fileTitle).toContainText("TXT", { timeout: 30_000 });
+
+    const iconWrapper = filesSection
+      .locator(`[data-testid="${ATTACHMENT_ITEM_ICON_WRAPPER_TEST_ID}"]`)
+      .first();
+    await expect(iconWrapper).toBeVisible();
+
+    await expectElementScreenshot(filesSection, {
+      name: "project-files-long-underscore-filename",
+    });
+
+    const iconGeometry = await getElementGeometryInCard(iconWrapper);
+    const titleGeometry = await getElementGeometryInCard(fileTitle);
+    expectGeometryWithinCard(iconGeometry);
+    expectGeometryWithinCard(titleGeometry);
+  });
+});