fix(groups): reject deletion of reserved group names with a 409 error

fix(api): handle reserved group names in group creation and updates
fix(api-key): reconcile default-group membership on role change

.github/workflows/deployment.yml

@@ -1509,105 +1509,232 @@ jobs:
             $(printf '%s\n' "${META_TAGS}" | xargs -I {} echo -t {}) \
             $IMAGES
 
-  trivy-scan:
+  trivy-scan-web:
     needs:
       - determine-builds
       - merge-web
-      - merge-web-cloud
-      - merge-backend
-      - merge-model-server
-    if: >-
-      always() && !cancelled() &&
-      (needs.merge-web.result == 'success' ||
-       needs.merge-web-cloud.result == 'success' ||
-       needs.merge-backend.result == 'success' ||
-       needs.merge-model-server.result == 'success')
+    if: needs.merge-web.result == 'success'
     runs-on:
       - runs-on
       - runner=2cpu-linux-arm64
-      - run-id=${{ github.run_id }}-trivy-scan-${{ matrix.component }}
+      - run-id=${{ github.run_id }}-trivy-scan-web
       - extras=ecr-cache
-    permissions:
-      security-events: write # needed for SARIF uploads
-    timeout-minutes: 10
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - component: web
-            registry-image: onyxdotapp/onyx-web-server
-          - component: web-cloud
-            registry-image: onyxdotapp/onyx-web-server-cloud
-          - component: backend
-            registry-image: ${{ contains(github.ref_name, 'cloud') && 'onyxdotapp/onyx-backend-cloud' || 'onyxdotapp/onyx-backend' }}
-            trivyignore: backend/.trivyignore
-          - component: model-server
-            registry-image: ${{ contains(github.ref_name, 'cloud') && 'onyxdotapp/onyx-model-server-cloud' || 'onyxdotapp/onyx-model-server' }}
+    timeout-minutes: 90
+    environment: release
+    env:
+      REGISTRY_IMAGE: onyxdotapp/onyx-web-server
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
+
+      - name: Run Trivy vulnerability scanner
+        uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # ratchet:nick-fields/retry@v3
+        with:
+          timeout_minutes: 30
+          max_attempts: 3
+          retry_wait_seconds: 10
+          command: |
+            if [ "${{ needs.determine-builds.outputs.is-test-run }}" == "true" ]; then
+              SCAN_IMAGE="${{ env.RUNS_ON_ECR_CACHE }}:web-${{ needs.determine-builds.outputs.sanitized-tag }}"
+            else
+              SCAN_IMAGE="docker.io/${{ env.REGISTRY_IMAGE }}:${{ github.ref_name }}"
+            fi
+            docker run --rm -v $HOME/.cache/trivy:/root/.cache/trivy \
+              -e TRIVY_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-db:2" \
+              -e TRIVY_JAVA_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-java-db:1" \
+              -e TRIVY_USERNAME="${{ env.DOCKER_USERNAME }}" \
+              -e TRIVY_PASSWORD="${{ env.DOCKER_TOKEN }}" \
+              aquasec/trivy@sha256:a22415a38938a56c379387a8163fcb0ce38b10ace73e593475d3658d578b2436 \
+              image \
+              --skip-version-check \
+              --timeout 20m \
+              --severity CRITICAL,HIGH \
+              ${SCAN_IMAGE}
+
+  trivy-scan-web-cloud:
+    needs:
+      - determine-builds
+      - merge-web-cloud
+    if: needs.merge-web-cloud.result == 'success'
+    runs-on:
+      - runs-on
+      - runner=2cpu-linux-arm64
+      - run-id=${{ github.run_id }}-trivy-scan-web-cloud
+      - extras=ecr-cache
+    timeout-minutes: 90
+    environment: release
+    env:
+      REGISTRY_IMAGE: onyxdotapp/onyx-web-server-cloud
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
+
+      - name: Run Trivy vulnerability scanner
+        uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # ratchet:nick-fields/retry@v3
+        with:
+          timeout_minutes: 30
+          max_attempts: 3
+          retry_wait_seconds: 10
+          command: |
+            if [ "${{ needs.determine-builds.outputs.is-test-run }}" == "true" ]; then
+              SCAN_IMAGE="${{ env.RUNS_ON_ECR_CACHE }}:web-cloud-${{ needs.determine-builds.outputs.sanitized-tag }}"
+            else
+              SCAN_IMAGE="docker.io/${{ env.REGISTRY_IMAGE }}:${{ github.ref_name }}"
+            fi
+            docker run --rm -v $HOME/.cache/trivy:/root/.cache/trivy \
+              -e TRIVY_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-db:2" \
+              -e TRIVY_JAVA_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-java-db:1" \
+              -e TRIVY_USERNAME="${{ env.DOCKER_USERNAME }}" \
+              -e TRIVY_PASSWORD="${{ env.DOCKER_TOKEN }}" \
+              aquasec/trivy@sha256:a22415a38938a56c379387a8163fcb0ce38b10ace73e593475d3658d578b2436 \
+              image \
+              --skip-version-check \
+              --timeout 20m \
+              --severity CRITICAL,HIGH \
+              ${SCAN_IMAGE}
+
+  trivy-scan-backend:
+    needs:
+      - determine-builds
+      - merge-backend
+    if: needs.merge-backend.result == 'success'
+    runs-on:
+      - runs-on
+      - runner=2cpu-linux-arm64
+      - run-id=${{ github.run_id }}-trivy-scan-backend
+      - extras=ecr-cache
+    timeout-minutes: 90
+    environment: release
+    env:
+      REGISTRY_IMAGE: ${{ contains(github.ref_name, 'cloud') && 'onyxdotapp/onyx-backend-cloud' || 'onyxdotapp/onyx-backend' }}
     steps:
-      - name: Check if this scan should run
-        id: should-run
-        run: |
-          case "$COMPONENT" in
-            web) RESULT="$MERGE_WEB" ;;
-            web-cloud) RESULT="$MERGE_WEB_CLOUD" ;;
-            backend) RESULT="$MERGE_BACKEND" ;;
-            model-server) RESULT="$MERGE_MODEL_SERVER" ;;
-          esac
-          if [ "$RESULT" == "success" ]; then
-            echo "run=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "run=false" >> "$GITHUB_OUTPUT"
-          fi
-        env:
-          COMPONENT: ${{ matrix.component }}
-          MERGE_WEB: ${{ needs.merge-web.result }}
-          MERGE_WEB_CLOUD: ${{ needs.merge-web-cloud.result }}
-          MERGE_BACKEND: ${{ needs.merge-backend.result }}
-          MERGE_MODEL_SERVER: ${{ needs.merge-model-server.result }}
-
       - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
-        if: steps.should-run.outputs.run == 'true'
 
       - name: Checkout
-        if: steps.should-run.outputs.run == 'true' && matrix.trivyignore != ''
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
         with:
           persist-credentials: false
 
-      - name: Determine scan image
-        if: steps.should-run.outputs.run == 'true'
-        id: scan-image
-        run: |
-          if [ "$IS_TEST_RUN" == "true" ]; then
-            echo "image=${RUNS_ON_ECR_CACHE}:${TAG_PREFIX}-${SANITIZED_TAG}" >> "$GITHUB_OUTPUT"
-          else
-            echo "image=docker.io/${REGISTRY_IMAGE}:${REF_NAME}" >> "$GITHUB_OUTPUT"
-          fi
-        env:
-          IS_TEST_RUN: ${{ needs.determine-builds.outputs.is-test-run }}
-          TAG_PREFIX: ${{ matrix.component }}
-          SANITIZED_TAG: ${{ needs.determine-builds.outputs.sanitized-tag }}
-          REGISTRY_IMAGE: ${{ matrix.registry-image }}
-          REF_NAME: ${{ github.ref_name }}
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
 
       - name: Run Trivy vulnerability scanner
-        if: steps.should-run.outputs.run == 'true'
-        uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # ratchet:aquasecurity/trivy-action@v0.35.0
+        uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # ratchet:nick-fields/retry@v3
         with:
-          image-ref: ${{ steps.scan-image.outputs.image }}
-          severity: CRITICAL,HIGH
-          format: "sarif"
-          output: "trivy-results.sarif"
-          trivyignores: ${{ matrix.trivyignore }}
-        env:
-          TRIVY_USERNAME: ${{ secrets.DOCKER_USERNAME }}
-          TRIVY_PASSWORD: ${{ secrets.DOCKER_TOKEN }}
+          timeout_minutes: 30
+          max_attempts: 3
+          retry_wait_seconds: 10
+          command: |
+            if [ "${{ needs.determine-builds.outputs.is-test-run }}" == "true" ]; then
+              SCAN_IMAGE="${{ env.RUNS_ON_ECR_CACHE }}:backend-${{ needs.determine-builds.outputs.sanitized-tag }}"
+            else
+              SCAN_IMAGE="docker.io/${{ env.REGISTRY_IMAGE }}:${{ github.ref_name }}"
+            fi
+            docker run --rm -v $HOME/.cache/trivy:/root/.cache/trivy \
+              -v ${{ github.workspace }}/backend/.trivyignore:/tmp/.trivyignore:ro \
+              -e TRIVY_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-db:2" \
+              -e TRIVY_JAVA_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-java-db:1" \
+              -e TRIVY_USERNAME="${{ env.DOCKER_USERNAME }}" \
+              -e TRIVY_PASSWORD="${{ env.DOCKER_TOKEN }}" \
+              aquasec/trivy@sha256:a22415a38938a56c379387a8163fcb0ce38b10ace73e593475d3658d578b2436 \
+              image \
+              --skip-version-check \
+              --timeout 20m \
+              --severity CRITICAL,HIGH \
+              --ignorefile /tmp/.trivyignore \
+              ${SCAN_IMAGE}
 
-      - name: Upload Trivy scan results to GitHub Security tab
-        if: steps.should-run.outputs.run == 'true'
-        uses: github/codeql-action/upload-sarif@ba454b8ab46733eb6145342877cd148270bb77ab
+  trivy-scan-model-server:
+    needs:
+      - determine-builds
+      - merge-model-server
+    if: needs.merge-model-server.result == 'success'
+    runs-on:
+      - runs-on
+      - runner=2cpu-linux-arm64
+      - run-id=${{ github.run_id }}-trivy-scan-model-server
+      - extras=ecr-cache
+    timeout-minutes: 90
+    environment: release
+    env:
+      REGISTRY_IMAGE: ${{ contains(github.ref_name, 'cloud') && 'onyxdotapp/onyx-model-server-cloud' || 'onyxdotapp/onyx-model-server' }}
+    steps:
+      - uses: runs-on/action@cd2b598b0515d39d78c38a02d529db87d2196d1e # ratchet:runs-on/action@v2
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
         with:
-          sarif_file: "trivy-results.sarif"
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+
+      - name: Get AWS Secrets
+        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
+        with:
+          secret-ids: |
+            DOCKER_USERNAME, deploy/docker-username
+            DOCKER_TOKEN, deploy/docker-token
+          parse-json-secrets: true
+
+      - name: Run Trivy vulnerability scanner
+        uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # ratchet:nick-fields/retry@v3
+        with:
+          timeout_minutes: 30
+          max_attempts: 3
+          retry_wait_seconds: 10
+          command: |
+            if [ "${{ needs.determine-builds.outputs.is-test-run }}" == "true" ]; then
+              SCAN_IMAGE="${{ env.RUNS_ON_ECR_CACHE }}:model-server-${{ needs.determine-builds.outputs.sanitized-tag }}"
+            else
+              SCAN_IMAGE="docker.io/${{ env.REGISTRY_IMAGE }}:${{ github.ref_name }}"
+            fi
+            docker run --rm -v $HOME/.cache/trivy:/root/.cache/trivy \
+              -e TRIVY_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-db:2" \
+              -e TRIVY_JAVA_DB_REPOSITORY="public.ecr.aws/aquasecurity/trivy-java-db:1" \
+              -e TRIVY_USERNAME="${{ env.DOCKER_USERNAME }}" \
+              -e TRIVY_PASSWORD="${{ env.DOCKER_TOKEN }}" \
+              aquasec/trivy@sha256:a22415a38938a56c379387a8163fcb0ce38b10ace73e593475d3658d578b2436 \
+              image \
+              --skip-version-check \
+              --timeout 20m \
+              --severity CRITICAL,HIGH \
+              ${SCAN_IMAGE}
 
   notify-slack-on-failure:
     needs:

.greptile/rules.md

@@ -6,7 +6,7 @@ Use explicit type annotations for variables to enhance code clarity, especially
 
 ## Best Practices
 
-Use the "Engineering Best Practices" section of `CONTRIBUTING.md` as core review context. Prefer consistency with existing patterns, fix issues in code you touch, avoid tacking new features onto muddy interfaces, fail loudly instead of silently swallowing errors, keep code strictly typed, preserve clear state boundaries, remove duplicate or dead logic, break up overly long functions, avoid hidden import-time side effects, respect module boundaries, and favor correctness-by-construction over relying on callers to use an API correctly.
+Use `contributing_guides/best_practices.md` as core review context. Prefer consistency with existing patterns, fix issues in code you touch, avoid tacking new features onto muddy interfaces, fail loudly instead of silently swallowing errors, keep code strictly typed, preserve clear state boundaries, remove duplicate or dead logic, break up overly long functions, avoid hidden import-time side effects, respect module boundaries, and favor correctness-by-construction over relying on callers to use an API correctly.
 
 ## TODOs
 
@@ -27,7 +27,6 @@ Code changes must consider both multi-tenant and single-tenant deployments. In m
 ## Nginx Routing — New Backend Routes
 
 Whenever a new backend route is added that does NOT start with `/api`, it must also be explicitly added to ALL nginx configs:
-
 - `deployment/helm/charts/onyx/templates/nginx-conf.yaml` (Helm/k8s)
 - `deployment/data/nginx/app.conf.template` (docker-compose dev)
 - `deployment/data/nginx/app.conf.template.prod` (docker-compose prod)
@@ -38,7 +37,3 @@ Routes not starting with `/api` are not caught by the existing `^/(api|openapi\.
 ## Full vs Lite Deployments
 
 Code changes must consider both regular Onyx deployments and Onyx lite deployments. Lite deployments disable the vector DB, Redis, model servers, and background workers by default, use PostgreSQL-backed cache/auth/file storage, and rely on the API server to handle background work. Do not assume those services are available unless the code path is explicitly limited to full deployments.
-
-## SWR Cache Keys — Always Use SWR_KEYS Registry
-
-All `useSWR()` calls and `mutate()` calls in the frontend must reference the centralized `SWR_KEYS` registry in `web/src/lib/swr-keys.ts` instead of inline endpoint strings or local string constants. Never write `useSWR("/api/some/endpoint", ...)` or `mutate("/api/some/endpoint")` — always use the corresponding `SWR_KEYS.someEndpoint` constant. If the endpoint does not yet exist in the registry, add it there first. This applies to all variants of an endpoint (e.g. query-string variants like `?get_editable=true` must also be registered as their own key).

AGENTS.md

@@ -357,5 +357,5 @@ raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=e.respon
 ## Best Practices
 
 In addition to the other content in this file, best practices for contributing
-to the codebase can be found in the "Engineering Best Practices" section of
-`CONTRIBUTING.md`. Understand its contents and follow them.
+to the codebase can be found at `contributing_guides/best_practices.md`.
+Understand its contents and follow them.

CONTRIBUTING.md

@@ -1,487 +1,32 @@
 # Contributing to Onyx
-
 Hey there! We are so excited that you're interested in Onyx.
 
-## Table of Contents
-
-- [Contribution Opportunities](#contribution-opportunities)
-- [Contribution Process](#contribution-process)
-- [Development Setup](#development-setup)
-  - [Prerequisites](#prerequisites)
-  - [Backend: Python Requirements](#backend-python-requirements)
-  - [Frontend: Node Dependencies](#frontend-node-dependencies)
-  - [Formatting and Linting](#formatting-and-linting)
-- [Running the Application](#running-the-application)
-  - [VSCode Debugger (Recommended)](#vscode-debugger-recommended)
-  - [Manually Running for Development](#manually-running-for-development)
-  - [Running in Docker](#running-in-docker)
-- [macOS-Specific Notes](#macos-specific-notes)
-- [Engineering Best Practices](#engineering-best-practices)
-  - [Principles and Collaboration](#principles-and-collaboration)
-  - [Style and Maintainability](#style-and-maintainability)
-  - [Performance and Correctness](#performance-and-correctness)
-  - [Repository Conventions](#repository-conventions)
-- [Release Process](#release-process)
-- [Getting Help](#getting-help)
-- [Enterprise Edition Contributions](#enterprise-edition-contributions)
-
----
 
 ## Contribution Opportunities
-
 The [GitHub Issues](https://github.com/onyx-dot-app/onyx/issues) page is a great place to look for and share contribution ideas.
 
-If you have your own feature that you would like to build, please create an issue and community members can provide feedback and upvote if they feel a common need.
+If you have your own feature that you would like to build please create an issue and community members can provide feedback and
+thumb it up if they feel a common need. 
 
----
 
-## Contribution Process
+## Contributing Code
+Please reference the documents in contributing_guides folder to ensure that the code base is kept to a high standard.
+1. dev_setup.md (start here): gives you a guide to setting up a local development environment.
+2. contribution_process.md: how to ensure you are building valuable features that will get reviewed and merged.
+3. best_practices.md: before asking for reviews, ensure your changes meet the repo code quality standards.
 
 To contribute, please follow the
 ["fork and pull request"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow.
 
-### 1. Get the feature or enhancement approved
-
-Create a GitHub issue and see if there are upvotes. If you feel the feature is sufficiently value-additive and you would like approval to contribute it to the repo, tag [Yuhong](https://github.com/yuhongsun96) to review.
-
-If you do not get a response within a week, feel free to email yuhong@onyx.app and include the issue in the message.
-
-Not all small features and enhancements will be accepted as there is a balance between feature richness and bloat. We strive to provide the best user experience possible so we have to be intentional about what we include in the app.
-
-### 2. Get the design approved
-
-The Onyx team will either provide a design doc and PRD for the feature or request one from you, the contributor. The scope and detail of the design will depend on the individual feature.
-
-### 3. IP attribution for EE contributions
-
-If you are contributing features to Onyx Enterprise Edition, you are required to sign the [IP Assignment Agreement](contributor_ip_assignment/EE_Contributor_IP_Assignment_Agreement.md).
-
-### 4. Review and testing
-
-Your features must pass all tests and all comments must be addressed prior to merging.
-
-### Implicit agreements
-
-If we approve an issue, we are promising you the following:
-- Your work will receive timely attention and we will put aside other important items to ensure you are not blocked.
-- You will receive necessary coaching on eng quality, system design, etc. to ensure the feature is completed well.
-- The Onyx team will pull resources and bandwidth from design, PM, and engineering to ensure that you have all the resources to build the feature to the quality required for merging.
-
-Because this is a large investment from our team, we ask that you:
-- Thoroughly read all the requirements of the design docs, engineering best practices, and try to minimize overhead for the Onyx team.
-- Complete the feature in a timely manner to reduce context switching and an ongoing resource pull from the Onyx team.
-
----
-
-## Development Setup
-
-Onyx being a fully functional app, relies on some external software, specifically:
-
-- [Postgres](https://www.postgresql.org/) (Relational DB)
-- [OpenSearch](https://opensearch.org/) (Vector DB/Search Engine)
-- [Redis](https://redis.io/) (Cache)
-- [MinIO](https://min.io/) (File Store)
-- [Nginx](https://nginx.org/) (Not needed for development flows generally)
-
-> **Note:**
-> This guide provides instructions to build and run Onyx locally from source with Docker containers providing the above external software.
-> We believe this combination is easier for development purposes. If you prefer to use pre-built container images, see [Running in Docker](#running-in-docker) below.
-
-### Prerequisites
-
-- **Python 3.11** — If using a lower version, modifications will have to be made to the code. Higher versions may have library compatibility issues.
-- **Docker** — Required for running external services (Postgres, OpenSearch, Redis, MinIO).
-- **Node.js v22** — We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node installations.
-
-### Backend: Python Requirements
-
-We use [uv](https://docs.astral.sh/uv/) and recommend creating a [virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment).
-
-```bash
-uv venv .venv --python 3.11
-source .venv/bin/activate
-```
-
-_For Windows, activate the virtual environment using Command Prompt:_
-
-```bash
-.venv\Scripts\activate
-```
-
-If using PowerShell, the command slightly differs:
-
-```powershell
-.venv\Scripts\Activate.ps1
-```
-
-Install the required Python dependencies:
-
-```bash
-uv sync --all-extras
-```
-
-Install Playwright for Python (headless browser required by the Web Connector):
-
-```bash
-uv run playwright install
-```
-
-### Frontend: Node Dependencies
-
-```bash
-nvm install 22 && nvm use 22
-node -v # verify your active version
-```
-
-Navigate to `onyx/web` and run:
-
-```bash
-npm i
-```
-
-### Formatting and Linting
-
-#### Backend
-
-Set up pre-commit hooks (black / reorder-python-imports):
-
-```bash
-uv run pre-commit install
-```
-
-We also use `mypy` for static type checking. Onyx is fully type-annotated, and we want to keep it that way! To run the mypy checks manually:
-
-```bash
-uv run mypy .  # from onyx/backend
-```
-
-#### Frontend
-
-We use `prettier` for formatting. The desired version will be installed via `npm i` from the `onyx/web` directory. To run the formatter:
-
-```bash
-npx prettier --write .  # from onyx/web
-```
-
-Pre-commit will also run prettier automatically on files you've recently touched. If re-formatted, your commit will fail. Re-stage your changes and commit again.
-
----
-
-## Running the Application
-
-### VSCode Debugger (Recommended)
-
-We highly recommend using VSCode's debugger for development.
-
-#### Initial Setup
-
-1. Copy `.vscode/env_template.txt` to `.vscode/.env`
-2. Fill in the necessary environment variables in `.vscode/.env`
-
-#### Using the Debugger
-
-Before starting, make sure the Docker Daemon is running.
-
-1. Open the Debug view in VSCode (Cmd+Shift+D on macOS)
-2. From the dropdown at the top, select "Clear and Restart External Volumes and Containers" and press the green play button
-3. From the dropdown at the top, select "Run All Onyx Services" and press the green play button
-4. Navigate to http://localhost:3000 in your browser to start using the app
-5. Set breakpoints by clicking to the left of line numbers to help debug while the app is running
-6. Use the debug toolbar to step through code, inspect variables, etc.
-
-> **Note:** "Clear and Restart External Volumes and Containers" will reset your Postgres and OpenSearch (relational-db and index). Only run this if you are okay with wiping your data.
-
-**Features:**
-- Hot reload is enabled for the web server and API servers
-- Python debugging is configured with debugpy
-- Environment variables are loaded from `.vscode/.env`
-- Console output is organized in the integrated terminal with labeled tabs
-
-### Manually Running for Development
-
-#### Docker containers for external software
-
-You will need Docker installed to run these containers.
-
-Navigate to `onyx/deployment/docker_compose`, then start up Postgres/OpenSearch/Redis/MinIO with:
-
-```bash
-docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d index relational_db cache minio
-```
-
-(index refers to OpenSearch, relational_db refers to Postgres, and cache refers to Redis)
-
-#### Running Onyx locally
-
-To start the frontend, navigate to `onyx/web` and run:
-
-```bash
-npm run dev
-```
-
-Next, start the model server which runs the local NLP models. Navigate to `onyx/backend` and run:
-
-```bash
-uvicorn model_server.main:app --reload --port 9000
-```
-
-_For Windows (for compatibility with both PowerShell and Command Prompt):_
-
-```bash
-powershell -Command "uvicorn model_server.main:app --reload --port 9000"
-```
-
-The first time running Onyx, you will need to run the DB migrations for Postgres. After the first time, this is no longer required unless the DB models change.
-
-Navigate to `onyx/backend` and with the venv active, run:
-
-```bash
-alembic upgrade head
-```
-
-Next, start the task queue which orchestrates the background jobs. Still in `onyx/backend`, run:
-
-```bash
-python ./scripts/dev_run_background_jobs.py
-```
-
-To run the backend API server, navigate back to `onyx/backend` and run:
-
-```bash
-AUTH_TYPE=basic uvicorn onyx.main:app --reload --port 8080
-```
-
-_For Windows (for compatibility with both PowerShell and Command Prompt):_
-
-```bash
-powershell -Command "
-    $env:AUTH_TYPE='basic'
-    uvicorn onyx.main:app --reload --port 8080
-"
-```
-
-> **Note:** If you need finer logging, add the additional environment variable `LOG_LEVEL=DEBUG` to the relevant services.
-
-#### Wrapping up
-
-You should now have 4 servers running:
-
-- Web server
-- Backend API
-- Model server
-- Background jobs
-
-Now, visit http://localhost:3000 in your browser. You should see the Onyx onboarding wizard where you can connect your external LLM provider to Onyx.
-
-You've successfully set up a local Onyx instance!
-
-### Running in Docker
-
-You can run the full Onyx application stack from pre-built images including all external software dependencies.
-
-Navigate to `onyx/deployment/docker_compose` and run:
-
-```bash
-docker compose up -d
-```
-
-After Docker pulls and starts these containers, navigate to http://localhost:3000 to use Onyx.
-
-If you want to make changes to Onyx and run those changes in Docker, you can also build a local version of the Onyx container images that incorporates your changes:
-
-```bash
-docker compose up -d --build
-```
-
----
-
-## macOS-Specific Notes
-
-### Setting up Python
-
-Ensure [Homebrew](https://brew.sh/) is already set up, then install Python 3.11:
-
-```bash
-brew install python@3.11
-```
-
-Add Python 3.11 to your path by adding the following line to `~/.zshrc`:
-
-```
-export PATH="$(brew --prefix)/opt/python@3.11/libexec/bin:$PATH"
-```
-
-> **Note:** You will need to open a new terminal for the path change above to take effect.
-
-### Setting up Docker
-
-On macOS, you will need to install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and ensure it is running before continuing with the docker commands.
-
-### Formatting and Linting
-
-macOS will likely require you to remove some quarantine attributes on some of the hooks for them to execute properly. After installing pre-commit, run the following command:
-
-```bash
-sudo xattr -r -d com.apple.quarantine ~/.cache/pre-commit
-```
-
----
-
-## Engineering Best Practices
-
-> These are also what we adhere to as a team internally, we love to build in the open and to uplevel our community and each other through being transparent.
-
-### Principles and Collaboration
-
-- **Use 1-way vs 2-way doors.** For 2-way doors, move faster and iterate. For 1-way doors, be more deliberate.
-- **Consistency > being "right."** Prefer consistent patterns across the codebase. If something is truly bad, fix it everywhere.
-- **Fix what you touch (selectively).**
-  - Don't feel obligated to fix every best-practice issue you notice.
-  - Don't introduce new bad practices.
-  - If your change touches code that violates best practices, fix it as part of the change.
-- **Don't tack features on.** When adding functionality, restructure logically as needed to avoid muddying interfaces and accumulating tech debt.
-
-### Style and Maintainability
-
-#### Comments and readability
-Add clear comments:
-- At logical boundaries (e.g., interfaces) so the reader doesn't need to dig 10 layers deeper.
-- Wherever assumptions are made or something non-obvious/unexpected is done.
-- For complicated flows/functions.
-- Wherever it saves time (e.g., nontrivial regex patterns).
-
-#### Errors and exceptions
-- **Fail loudly** rather than silently skipping work.
-  - Example: raise and let exceptions propagate instead of silently dropping a document.
-- **Don't overuse `try/except`.**
-  - Put `try/except` at the correct logical level.
-  - Do not mask exceptions unless it is clearly appropriate.
-
-#### Typing
-- Everything should be **as strictly typed as possible**.
-- Use `cast` for annoying/loose-typed interfaces (e.g., results of `run_functions_tuples_in_parallel`).
-  - Only `cast` when the type checker sees `Any` or types are too loose.
-- Prefer types that are easy to read.
-  - Avoid dense types like `dict[tuple[str, str], list[list[float]]]`.
-  - Prefer domain models, e.g.:
-    - `EmbeddingModel(provider_name, model_name)` as a Pydantic model
-    - `dict[EmbeddingModel, list[EmbeddingVector]]`
-
-#### State, objects, and boundaries
-- Keep **clear logical boundaries** for state containers and objects.
-- A **config** object should never contain things like a `db_session`.
-- Avoid state containers that are overly nested, or huge + flat (use judgment).
-- Prefer **composition and functional style** over inheritance/OOP.
-- Prefer **no mutation** unless there's a strong reason.
-- State objects should be **intentional and explicit**, ideally nonmutating.
-- Use interfaces/objects to create clear separation of responsibility.
-- Prefer simplicity when there's no clear gain.
-  - Avoid overcomplicated mechanisms like semaphores.
-  - Prefer **hash maps (dicts)** over tree structures unless there's a strong reason.
-
-#### Naming
-- Name variables carefully and intentionally.
-- Prefer long, explicit names when undecided.
-- Avoid single-character variables except for small, self-contained utilities (or not at all).
-- Keep the same object/name consistent through the call stack and within functions when reasonable.
-  - Good: `for token in tokens:`
-  - Bad: `for msg in tokens:` (if iterating tokens)
-- Function names should bias toward **long + descriptive** for codebase search.
-  - IntelliSense can miss call sites; search works best with unique names.
-
-#### Correctness by construction
-- Prefer self-contained correctness — don't rely on callers to "use it right" if you can make misuse hard.
-- Avoid redundancies: if a function takes an arg, it shouldn't also take a state object that contains that same arg.
-- No dead code (unless there's a very good reason).
-- No commented-out code in main or feature branches (unless there's a very good reason).
-- No duplicate logic:
-  - Don't copy/paste into branches when shared logic can live above the conditional.
-  - If you're afraid to touch the original, you don't understand it well enough.
-  - LLMs often create subtle duplicate logic — review carefully and remove it.
-  - Avoid "nearly identical" objects that confuse when to use which.
-- Avoid extremely long functions with chained logic:
-  - Encapsulate steps into helpers for readability, even if not reused.
-  - "Pythonic" multi-step expressions are OK in moderation; don't trade clarity for cleverness.
-
-### Performance and Correctness
-
-- Avoid holding resources for extended periods (DB sessions, locks/semaphores).
-- Validate objects on creation and right before use.
-- Connector code (data to Onyx documents):
-  - Any in-memory structure that can grow without bound based on input must be periodically size-checked.
-  - If a connector is OOMing (often shows up as "missing celery tasks"), this is a top thing to check retroactively.
-- Async and event loops:
-  - Never introduce new async/event loop Python code, and try to make existing async code synchronous when possible if it makes sense.
-  - Writing async code without 100% understanding the code and having a concrete reason to do so is likely to introduce bugs and not add any meaningful performance gains.
-
-### Repository Conventions
-
-#### Where code lives
-- Pydantic + data models: `models.py` files.
-- DB interface functions (excluding lazy loading): `db/` directory.
-- LLM prompts: `prompts/` directory, roughly mirroring the code layout that uses them.
-- API routes: `server/` directory.
-
-#### Pydantic and modeling
-- Prefer **Pydantic** over dataclasses.
-- If absolutely required, use `allow_arbitrary_types`.
-
-#### Data conventions
-- Prefer explicit `None` over sentinel empty strings (usually; depends on intent).
-- Prefer explicit identifiers: use string enums instead of integer codes.
-- Avoid magic numbers (co-location is good when necessary). **Always avoid magic strings.**
-
-#### Logging
-- Log messages where they are created.
-- Don't propagate log messages around just to log them elsewhere.
-
-#### Encapsulation
-- Don't use private attributes/methods/properties from other classes/modules.
-- "Private" is private — respect that boundary.
-
-#### SQLAlchemy guidance
-- Lazy loading is often bad at scale, especially across multiple list relationships.
-- Be careful when accessing SQLAlchemy object attributes:
-  - It can help avoid redundant DB queries,
-  - but it can also fail if accessed outside an active session,
-  - and lazy loading can add hidden DB dependencies to otherwise "simple" functions.
-- Reference: https://www.reddit.com/r/SQLAlchemy/comments/138f248/joinedload_vs_selectinload/
-
-#### Trunk-based development and feature flags
-- **PRs should contain no more than 500 lines of real change.**
-- **Merge to main frequently.** Avoid long-lived feature branches — they create merge conflicts and integration pain.
-- **Use feature flags for incremental rollout.**
-  - Large features should be merged in small, shippable increments behind a flag.
-  - This allows continuous integration without exposing incomplete functionality.
-- **Keep flags short-lived.** Once a feature is fully rolled out, remove the flag and dead code paths promptly.
-- **Flag at the right level.** Prefer flagging at API/UI entry points rather than deep in business logic.
-- **Test both flag states.** Ensure the codebase works correctly with the flag on and off.
-
-#### Miscellaneous
-- Any TODOs you add in the code must be accompanied by either the name/username of the owner of that TODO, or an issue number for an issue referencing that piece of work.
-- Avoid module-level logic that runs on import, which leads to import-time side effects. Essentially every piece of meaningful logic should exist within some function that has to be explicitly invoked. Acceptable exceptions may include loading environment variables or setting up loggers.
-  - If you find yourself needing something like this, you may want that logic to exist in a file dedicated for manual execution (contains `if __name__ == "__main__":`) which should not be imported by anything else.
-- Do not conflate Python scripts you intend to run from the command line (contains `if __name__ == "__main__":`) with modules you intend to import from elsewhere. If for some unlikely reason they have to be the same file, any logic specific to executing the file (including imports) should be contained in the `if __name__ == "__main__":` block.
-  - Generally these executable files exist in `backend/scripts/`.
-
----
-
-## Release Process
-
-Onyx loosely follows the SemVer versioning standard.
-A set of Docker containers will be pushed automatically to DockerHub with every tag.
-You can see the containers [here](https://hub.docker.com/search?q=onyx%2F).
-
----
-
-## Getting Help
 
+## Getting Help 🙋
 We have support channels and generally interesting discussions on our [Discord](https://discord.gg/4NA5SbzrWb).
 
 See you there!
 
----
 
-## Enterprise Edition Contributions
-
-If you are contributing features to Onyx Enterprise Edition (code under any `ee/` directory), you are required to sign the [IP Assignment Agreement](contributor_ip_assignment/EE_Contributor_IP_Assignment_Agreement.md) ([PDF version](contributor_ip_assignment/EE_Contributor_IP_Assignment_Agreement.pdf)).
+## Release Process
+Onyx loosely follows the SemVer versioning standard.
+Major changes are released with a "minor" version bump. Currently we use patch release versions to indicate small feature changes.
+A set of Docker containers will be pushed automatically to DockerHub with every tag.
+You can see the containers [here](https://hub.docker.com/search?q=onyx%2F).

README.md

@@ -4,6 +4,8 @@
     <a href="https://www.onyx.app/?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme"> <img width="50%" src="https://github.com/onyx-dot-app/onyx/blob/logo/OnyxLogoCropped.jpg?raw=true" /></a>
 </h2>
 
+<p align="center">Open Source AI Platform</p>
+
 <p align="center">
     <a href="https://discord.gg/TDJ59cGV2X" target="_blank">
         <img src="https://img.shields.io/badge/discord-join-blue.svg?logo=discord&logoColor=white" alt="Discord" />
@@ -25,94 +27,82 @@
   </a>
 </p>
 
-# Onyx - The Open Source AI Platform
 
-**[Onyx](https://www.onyx.app/?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)** is the application layer for LLMs - bringing a feature-rich interface that can be easily hosted by anyone.
-Onyx enables LLMs through advanced capabilities like RAG, web search, code execution, file creation, deep research and more.
+**[Onyx](https://www.onyx.app/?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)** is a feature-rich, self-hostable Chat UI that works with any LLM. It is easy to deploy and can run in a completely airgapped environment.
 
-Connect your applications with over 50+ indexing based connectors provided out of the box or via MCP.
+Onyx comes loaded with advanced features like Agents, Web Search, RAG, MCP, Deep Research, Connectors to 40+ knowledge sources, and more.
 
 > [!TIP]
-> Deploy with a single command:
+> Run Onyx with one command (or see deployment section below):
 > ```
 > curl -fsSL https://onyx.app/install_onyx.sh | bash
 > ```
 
-![Onyx Chat Silent Demo](https://github.com/onyx-dot-app/onyx/releases/download/v3.0.0/Onyx.gif)
+****
+
+![Onyx Chat Silent Demo](https://github.com/onyx-dot-app/onyx/releases/download/v0.21.1/OnyxChatSilentDemo.gif)
+
 
----
 
 ## ⭐ Features
-
-- **🔍 Agentic RAG:** Get best in class search and answer quality based on hybrid index + AI Agents for information retrieval
-  - Benchmark to release soon!
-- **🔬 Deep Research:** Get in depth reports with a multi-step research flow.
-  - Top of [leaderboard](https://github.com/onyx-dot-app/onyx_deep_research_bench) as of Feb 2026.
-- **🤖 Custom Agents:** Build AI Agents with unique instructions, knowledge, and actions.
-- **🌍 Web Search:** Browse the web to get up to date information.
-  - Supports Serper, Google PSE, Brave, SearXNG, and others.
-  - Comes with an in house web crawler and support for Firecrawl/Exa.
-- **📄 Artifacts:** Generate documents, graphics, and other downloadable artifacts.
-- **▶️ Actions & MCP:** Let Onyx agents interact with external applications, comes with flexible Auth options.
-- **💻 Code Execution:** Execute code in a sandbox to analyze data, render graphs, or modify files.
-- **🎙️ Voice Mode:** Chat with Onyx via text-to-speech and speech-to-text.
+- **🤖 Custom Agents:** Build AI Agents with unique instructions, knowledge and actions.
+- **🌍 Web Search:** Browse the web with Google PSE, Exa, and Serper as well as an in-house scraper or Firecrawl.
+- **🔍 RAG:** Best in class hybrid-search + knowledge graph for uploaded files and ingested documents from connectors. 
+- **🔄 Connectors:** Pull knowledge, metadata, and access information from over 40 applications.
+- **🔬 Deep Research:** Get in depth answers with an agentic multi-step search.
+- **▶️ Actions & MCP:** Give AI Agents the ability to interact with external systems.
+- **💻 Code Interpreter:** Execute code to analyze data, render graphs and create files.
 - **🎨 Image Generation:** Generate images based on user prompts.
+- **👥 Collaboration:** Chat sharing, feedback gathering, user management, usage analytics, and more.
 
-Onyx supports all major LLM providers, both self-hosted (like Ollama, LiteLLM, vLLM, etc.) and proprietary (like Anthropic, OpenAI, Gemini, etc.).
+Onyx works with all LLMs (like OpenAI, Anthropic, Gemini, etc.) and self-hosted LLMs (like Ollama, vLLM, etc.)
 
-To learn more - check out our [docs](https://docs.onyx.app/welcome?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)!
+To learn more about the features, check out our [documentation](https://docs.onyx.app/welcome?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)!
 
----
 
-## 🚀 Deployment Modes
 
-> Onyx supports deployments in Docker, Kubernetes, Helm/Terraform and provides guides for major cloud providers.
-> Detailed deployment guides found [here](https://docs.onyx.app/deployment/overview).
+## 🚀 Deployment
+Onyx supports deployments in Docker, Kubernetes, Terraform, along with guides for major cloud providers.
 
-Onyx supports two separate deployment options: standard and lite.
-
-#### Onyx Lite
-
-The Lite mode can be thought of as a lightweight Chat UI. It requires less resources (under 1GB memory) and runs a less complex stack.
-It is great for users who want to test out Onyx quickly or for teams who are only interested in the Chat UI and Agents functionalities.
-
-#### Standard Onyx
-
-The complete feature set of Onyx which is recommended for serious users and larger teams. Additional components not included in Lite mode:
-- Vector + Keyword index for RAG.
-- Background containers to run job queues and workers for syncing knowledge from connectors.
-- AI model inference servers to run deep learning models used during indexing and inference.
-- Performance optimizations for large scale use via in memory cache (Redis) and blob store (MinIO).
+See guides below:
+- [Docker](https://docs.onyx.app/deployment/local/docker?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme) or [Quickstart](https://docs.onyx.app/deployment/getting_started/quickstart?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme) (best for most users)
+- [Kubernetes](https://docs.onyx.app/deployment/local/kubernetes?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme) (best for large teams)
+- [Terraform](https://docs.onyx.app/deployment/local/terraform?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme) (best for teams already using Terraform)
+- Cloud specific guides (best if specifically using [AWS EKS](https://docs.onyx.app/deployment/cloud/aws/eks?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme), [Azure VMs](https://docs.onyx.app/deployment/cloud/azure?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme), etc.)
 
 > [!TIP]  
-> **To try Onyx for free without deploying, visit [Onyx Cloud](https://cloud.onyx.app/signup?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)**.
+> **To try Onyx for free without deploying, check out [Onyx Cloud](https://cloud.onyx.app/signup?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme)**.
 
----
 
-## 🏢 Onyx for Enterprise
 
-Onyx is built for teams of all sizes, from individual users to the largest global enterprises:
-- 👥 Collaboration: Share chats and agents with other members of your organization.
-- 🔐 Single Sign On: SSO via Google OAuth, OIDC, or SAML. Group syncing and user provisioning via SCIM.
-- 🛡️ Role Based Access Control: RBAC for sensitive resources like access to agents, actions, etc.
-- 📊 Analytics: Usage graphs broken down by teams, LLMs, or agents.
-- 🕵️ Query History: Audit usage to ensure safe adoption of AI in your organization.
-- 💻 Custom code: Run custom code to remove PII, reject sensitive queries, or to run custom analysis.
-- 🎨 Whitelabeling: Customize the look and feel of Onyx with custom naming, icons, banners, and more.
+## 🔍 Other Notable Benefits
+Onyx is built for teams of all sizes, from individual users to the largest global enterprises.
+
+- **Enterprise Search**: far more than simple RAG, Onyx has custom indexing and retrieval that remains performant and accurate for scales of up to tens of millions of documents.
+- **Security**: SSO (OIDC/SAML/OAuth2), RBAC, encryption of credentials, etc.
+- **Management UI**: different user roles such as basic, curator, and admin.
+- **Document Permissioning**: mirrors user access from external apps for RAG use cases.
+
+
+
+## 🚧 Roadmap
+To see ongoing and upcoming projects, check out our [roadmap](https://github.com/orgs/onyx-dot-app/projects/2)!
+
+
 
 ## 📚 Licensing
-
 There are two editions of Onyx:
 
-- Onyx Community Edition (CE) is available freely under the MIT license and covers all of the core features for Chat, RAG, Agents, and Actions.
+- Onyx Community Edition (CE) is available freely under the MIT license.
 - Onyx Enterprise Edition (EE) includes extra features that are primarily useful for larger organizations.
-
 For feature details, check out [our website](https://www.onyx.app/pricing?utm_source=onyx_repo&utm_medium=github&utm_campaign=readme).
 
-## 👪 Community
 
+
+## 👪 Community
 Join our open source community on **[Discord](https://discord.gg/TDJ59cGV2X)**!
 
-## 💡 Contributing
 
+
+## 💡 Contributing
 Looking to contribute? Please check out the [Contribution Guide](CONTRIBUTING.md) for more details.

backend/alembic/versions/03d085c5c38d_backfill_account_type.py

@@ -0,0 +1,108 @@
+"""backfill_account_type
+
+Revision ID: 03d085c5c38d
+Revises: 977e834c1427
+Create Date: 2026-03-25 16:00:00.000000
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "03d085c5c38d"
+down_revision = "977e834c1427"
+branch_labels = None
+depends_on = None
+
+_STANDARD = "STANDARD"
+_BOT = "BOT"
+_EXT_PERM_USER = "EXT_PERM_USER"
+_SERVICE_ACCOUNT = "SERVICE_ACCOUNT"
+_ANONYMOUS = "ANONYMOUS"
+
+# Well-known anonymous user UUID
+ANONYMOUS_USER_ID = "00000000-0000-0000-0000-000000000002"
+
+# Email pattern for API key virtual users
+API_KEY_EMAIL_PATTERN = r"API\_KEY\_\_%"
+
+# Reflect the table structure for use in DML
+user_table = sa.table(
+    "user",
+    sa.column("id", sa.Uuid),
+    sa.column("email", sa.String),
+    sa.column("role", sa.String),
+    sa.column("account_type", sa.String),
+)
+
+
+def upgrade() -> None:
+    # ------------------------------------------------------------------
+    # Step 1: Backfill account_type from role.
+    # Order matters — most-specific matches first so the final catch-all
+    # only touches rows that haven't been classified yet.
+    # ------------------------------------------------------------------
+
+    # 1a. API key virtual users → SERVICE_ACCOUNT
+    op.execute(
+        sa.update(user_table)
+        .where(
+            user_table.c.email.ilike(API_KEY_EMAIL_PATTERN),
+            user_table.c.account_type.is_(None),
+        )
+        .values(account_type=_SERVICE_ACCOUNT)
+    )
+
+    # 1b. Anonymous user → ANONYMOUS
+    op.execute(
+        sa.update(user_table)
+        .where(
+            user_table.c.id == ANONYMOUS_USER_ID,
+            user_table.c.account_type.is_(None),
+        )
+        .values(account_type=_ANONYMOUS)
+    )
+
+    # 1c. SLACK_USER role → BOT
+    op.execute(
+        sa.update(user_table)
+        .where(
+            user_table.c.role == "SLACK_USER",
+            user_table.c.account_type.is_(None),
+        )
+        .values(account_type=_BOT)
+    )
+
+    # 1d. EXT_PERM_USER role → EXT_PERM_USER
+    op.execute(
+        sa.update(user_table)
+        .where(
+            user_table.c.role == "EXT_PERM_USER",
+            user_table.c.account_type.is_(None),
+        )
+        .values(account_type=_EXT_PERM_USER)
+    )
+
+    # 1e. Everything else → STANDARD
+    op.execute(
+        sa.update(user_table)
+        .where(user_table.c.account_type.is_(None))
+        .values(account_type=_STANDARD)
+    )
+
+    # ------------------------------------------------------------------
+    # Step 2: Set account_type to NOT NULL now that every row is filled.
+    # ------------------------------------------------------------------
+    op.alter_column(
+        "user",
+        "account_type",
+        nullable=False,
+        server_default="STANDARD",
+    )
+
+
+def downgrade() -> None:
+    op.alter_column("user", "account_type", nullable=True, server_default=None)
+    op.execute(sa.update(user_table).values(account_type=None))

backend/alembic/versions/503883791c39_add_effective_permissions.py

@@ -0,0 +1,104 @@
+"""add_effective_permissions
+
+Adds a JSONB column `effective_permissions` to the user table to store
+directly granted permissions (e.g. ["admin"] or ["basic"]). Implied
+permissions are expanded at read time, not stored.
+
+Backfill: joins user__user_group → permission_grant to collect each
+user's granted permissions into a JSON array. Users without group
+memberships keep the default [].
+
+Revision ID: 503883791c39
+Revises: b4b7e1028dfd
+Create Date: 2026-03-30 14:49:22.261748
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision = "503883791c39"
+down_revision = "b4b7e1028dfd"
+branch_labels: str | None = None
+depends_on: str | Sequence[str] | None = None
+
+user_table = sa.table(
+    "user",
+    sa.column("id", sa.Uuid),
+    sa.column("effective_permissions", postgresql.JSONB),
+)
+
+user_user_group = sa.table(
+    "user__user_group",
+    sa.column("user_id", sa.Uuid),
+    sa.column("user_group_id", sa.Integer),
+)
+
+permission_grant = sa.table(
+    "permission_grant",
+    sa.column("group_id", sa.Integer),
+    sa.column("permission", sa.String),
+    sa.column("is_deleted", sa.Boolean),
+)
+
+
+def upgrade() -> None:
+    op.add_column(
+        "user",
+        sa.Column(
+            "effective_permissions",
+            postgresql.JSONB(),
+            nullable=False,
+            server_default=sa.text("'[]'::jsonb"),
+        ),
+    )
+
+    conn = op.get_bind()
+
+    # Deduplicated permissions per user
+    deduped = (
+        sa.select(
+            user_user_group.c.user_id,
+            permission_grant.c.permission,
+        )
+        .select_from(
+            user_user_group.join(
+                permission_grant,
+                sa.and_(
+                    permission_grant.c.group_id == user_user_group.c.user_group_id,
+                    permission_grant.c.is_deleted == sa.false(),
+                ),
+            )
+        )
+        .distinct()
+        .subquery("deduped")
+    )
+
+    # Aggregate into JSONB array per user (order is not guaranteed;
+    # consumers read this as a set so ordering does not matter)
+    perms_per_user = (
+        sa.select(
+            deduped.c.user_id,
+            sa.func.jsonb_agg(
+                deduped.c.permission,
+                type_=postgresql.JSONB,
+            ).label("perms"),
+        )
+        .group_by(deduped.c.user_id)
+        .subquery("sub")
+    )
+
+    conn.execute(
+        user_table.update()
+        .where(user_table.c.id == perms_per_user.c.user_id)
+        .values(effective_permissions=perms_per_user.c.perms)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("user", "effective_permissions")

backend/alembic/versions/977e834c1427_seed_default_groups.py

@@ -0,0 +1,136 @@
+"""seed_default_groups
+
+Revision ID: 977e834c1427
+Revises: 8188861f4e92
+Create Date: 2026-03-25 14:59:41.313091
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+
+# revision identifiers, used by Alembic.
+revision = "977e834c1427"
+down_revision = "8188861f4e92"
+branch_labels = None
+depends_on = None
+
+# (group_name, permission_value)
+DEFAULT_GROUPS = [
+    ("Admin", "admin"),
+    ("Basic", "basic"),
+]
+
+CUSTOM_SUFFIX = "(Custom)"
+
+MAX_RENAME_ATTEMPTS = 100
+
+# Reflect table structures for use in DML
+user_group_table = sa.table(
+    "user_group",
+    sa.column("id", sa.Integer),
+    sa.column("name", sa.String),
+    sa.column("is_up_to_date", sa.Boolean),
+    sa.column("is_up_for_deletion", sa.Boolean),
+    sa.column("is_default", sa.Boolean),
+)
+
+permission_grant_table = sa.table(
+    "permission_grant",
+    sa.column("group_id", sa.Integer),
+    sa.column("permission", sa.String),
+    sa.column("grant_source", sa.String),
+)
+
+user__user_group_table = sa.table(
+    "user__user_group",
+    sa.column("user_group_id", sa.Integer),
+    sa.column("user_id", sa.Uuid),
+)
+
+
+def _find_available_name(conn: sa.engine.Connection, base: str) -> str:
+    """Return a name like 'Admin (Custom)' or 'Admin (Custom 2)' that is not taken."""
+    candidate = f"{base} {CUSTOM_SUFFIX}"
+    attempt = 1
+    while attempt <= MAX_RENAME_ATTEMPTS:
+        exists = conn.execute(
+            sa.select(sa.literal(1))
+            .select_from(user_group_table)
+            .where(user_group_table.c.name == candidate)
+            .limit(1)
+        ).fetchone()
+        if exists is None:
+            return candidate
+        attempt += 1
+        candidate = f"{base} (Custom {attempt})"
+    raise RuntimeError(
+        f"Could not find an available name for group '{base}' "
+        f"after {MAX_RENAME_ATTEMPTS} attempts"
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    for group_name, permission_value in DEFAULT_GROUPS:
+        # Step 1: Rename ALL existing groups that clash with the canonical name.
+        conflicting = conn.execute(
+            sa.select(user_group_table.c.id, user_group_table.c.name).where(
+                user_group_table.c.name == group_name
+            )
+        ).fetchall()
+
+        for row_id, row_name in conflicting:
+            new_name = _find_available_name(conn, row_name)
+            op.execute(
+                sa.update(user_group_table)
+                .where(user_group_table.c.id == row_id)
+                .values(name=new_name, is_up_to_date=False)
+            )
+
+        # Step 2: Create a fresh default group.
+        result = conn.execute(
+            user_group_table.insert()
+            .values(
+                name=group_name,
+                is_up_to_date=True,
+                is_up_for_deletion=False,
+                is_default=True,
+            )
+            .returning(user_group_table.c.id)
+        ).fetchone()
+        assert result is not None
+        group_id = result[0]
+
+        # Step 3: Upsert permission grant.
+        op.execute(
+            pg_insert(permission_grant_table)
+            .values(
+                group_id=group_id,
+                permission=permission_value,
+                grant_source="SYSTEM",
+            )
+            .on_conflict_do_nothing(index_elements=["group_id", "permission"])
+        )
+
+
+def downgrade() -> None:
+    # Remove the default groups created by this migration.
+    # First remove user-group memberships that reference default groups
+    # to avoid FK violations, then delete the groups themselves.
+    default_group_ids = sa.select(user_group_table.c.id).where(
+        user_group_table.c.is_default == True  # noqa: E712
+    )
+    op.execute(
+        sa.delete(user__user_group_table).where(
+            user__user_group_table.c.user_group_id.in_(default_group_ids)
+        )
+    )
+    op.execute(
+        sa.delete(user_group_table).where(
+            user_group_table.c.is_default == True  # noqa: E712
+        )
+    )

backend/alembic/versions/b4b7e1028dfd_grant_basic_to_existing_groups.py

@@ -0,0 +1,84 @@
+"""grant_basic_to_existing_groups
+
+Grants the "basic" permission to all existing groups that don't already
+have it. Every group should have at least "basic" so that its members
+get basic access when effective_permissions is backfilled.
+
+Revision ID: b4b7e1028dfd
+Revises: b7bcc991d722
+Create Date: 2026-03-30 16:15:17.093498
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "b4b7e1028dfd"
+down_revision = "b7bcc991d722"
+branch_labels: str | None = None
+depends_on: str | Sequence[str] | None = None
+
+user_group = sa.table(
+    "user_group",
+    sa.column("id", sa.Integer),
+    sa.column("is_default", sa.Boolean),
+)
+
+permission_grant = sa.table(
+    "permission_grant",
+    sa.column("group_id", sa.Integer),
+    sa.column("permission", sa.String),
+    sa.column("grant_source", sa.String),
+    sa.column("is_deleted", sa.Boolean),
+)
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    already_has_basic = (
+        sa.select(sa.literal(1))
+        .select_from(permission_grant)
+        .where(
+            permission_grant.c.group_id == user_group.c.id,
+            permission_grant.c.permission == "basic",
+        )
+        .exists()
+    )
+
+    groups_needing_basic = sa.select(
+        user_group.c.id,
+        sa.literal("basic").label("permission"),
+        sa.literal("SYSTEM").label("grant_source"),
+        sa.literal(False).label("is_deleted"),
+    ).where(
+        user_group.c.is_default == sa.false(),
+        ~already_has_basic,
+    )
+
+    conn.execute(
+        permission_grant.insert().from_select(
+            ["group_id", "permission", "grant_source", "is_deleted"],
+            groups_needing_basic,
+        )
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    non_default_group_ids = sa.select(user_group.c.id).where(
+        user_group.c.is_default == sa.false()
+    )
+
+    conn.execute(
+        permission_grant.delete().where(
+            permission_grant.c.permission == "basic",
+            permission_grant.c.grant_source == "SYSTEM",
+            permission_grant.c.group_id.in_(non_default_group_ids),
+        )
+    )

backend/alembic/versions/b7bcc991d722_assign_users_to_default_groups.py

@@ -0,0 +1,116 @@
+"""assign_users_to_default_groups
+
+Revision ID: b7bcc991d722
+Revises: 03d085c5c38d
+Create Date: 2026-03-25 16:30:39.529301
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+
+# revision identifiers, used by Alembic.
+revision = "b7bcc991d722"
+down_revision = "03d085c5c38d"
+branch_labels = None
+depends_on = None
+
+# Reflect table structures for use in DML
+user_group_table = sa.table(
+    "user_group",
+    sa.column("id", sa.Integer),
+    sa.column("name", sa.String),
+    sa.column("is_default", sa.Boolean),
+)
+
+user_table = sa.table(
+    "user",
+    sa.column("id", sa.Uuid),
+    sa.column("role", sa.String),
+    sa.column("account_type", sa.String),
+    sa.column("is_active", sa.Boolean),
+)
+
+user__user_group_table = sa.table(
+    "user__user_group",
+    sa.column("user_group_id", sa.Integer),
+    sa.column("user_id", sa.Uuid),
+)
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Look up default group IDs
+    admin_row = conn.execute(
+        sa.select(user_group_table.c.id).where(
+            user_group_table.c.name == "Admin",
+            user_group_table.c.is_default == True,  # noqa: E712
+        )
+    ).fetchone()
+
+    basic_row = conn.execute(
+        sa.select(user_group_table.c.id).where(
+            user_group_table.c.name == "Basic",
+            user_group_table.c.is_default == True,  # noqa: E712
+        )
+    ).fetchone()
+
+    if admin_row is None:
+        raise RuntimeError(
+            "Default 'Admin' group not found. "
+            "Ensure migration 977e834c1427 (seed_default_groups) ran successfully."
+        )
+
+    if basic_row is None:
+        raise RuntimeError(
+            "Default 'Basic' group not found. "
+            "Ensure migration 977e834c1427 (seed_default_groups) ran successfully."
+        )
+
+    # Users with role=admin → Admin group
+    # Exclude inactive placeholder/anonymous users that are not real users
+    admin_users = sa.select(
+        sa.literal(admin_row[0]).label("user_group_id"),
+        user_table.c.id.label("user_id"),
+    ).where(
+        user_table.c.role == "ADMIN",
+        user_table.c.is_active == True,  # noqa: E712
+    )
+    op.execute(
+        pg_insert(user__user_group_table)
+        .from_select(["user_group_id", "user_id"], admin_users)
+        .on_conflict_do_nothing(index_elements=["user_group_id", "user_id"])
+    )
+
+    # STANDARD users (non-admin) and SERVICE_ACCOUNT users (role=basic) → Basic group
+    # Exclude inactive placeholder/anonymous users that are not real users
+    basic_users = sa.select(
+        sa.literal(basic_row[0]).label("user_group_id"),
+        user_table.c.id.label("user_id"),
+    ).where(
+        user_table.c.is_active == True,  # noqa: E712
+        sa.or_(
+            sa.and_(
+                user_table.c.account_type == "STANDARD",
+                user_table.c.role != "ADMIN",
+            ),
+            sa.and_(
+                user_table.c.account_type == "SERVICE_ACCOUNT",
+                user_table.c.role == "BASIC",
+            ),
+        ),
+    )
+    op.execute(
+        pg_insert(user__user_group_table)
+        .from_select(["user_group_id", "user_id"], basic_users)
+        .on_conflict_do_nothing(index_elements=["user_group_id", "user_id"])
+    )
+
+
+def downgrade() -> None:
+    # Group memberships are left in place — removing them risks
+    # deleting memberships that existed before this migration.
+    pass

backend/ee/onyx/db/user_group.py

@@ -19,6 +19,8 @@ from onyx.configs.app_configs import DISABLE_VECTOR_DB
 from onyx.db.connector_credential_pair import get_connector_credential_pair_from_id
 from onyx.db.enums import AccessType
 from onyx.db.enums import ConnectorCredentialPairStatus
+from onyx.db.enums import GrantSource
+from onyx.db.enums import Permission
 from onyx.db.models import ConnectorCredentialPair
 from onyx.db.models import Credential
 from onyx.db.models import Credential__UserGroup
@@ -28,6 +30,7 @@ from onyx.db.models import DocumentSet
 from onyx.db.models import DocumentSet__UserGroup
 from onyx.db.models import FederatedConnector__DocumentSet
 from onyx.db.models import LLMProvider__UserGroup
+from onyx.db.models import PermissionGrant
 from onyx.db.models import Persona
 from onyx.db.models import Persona__UserGroup
 from onyx.db.models import TokenRateLimit__UserGroup
@@ -36,6 +39,7 @@ from onyx.db.models import User__UserGroup
 from onyx.db.models import UserGroup
 from onyx.db.models import UserGroup__ConnectorCredentialPair
 from onyx.db.models import UserRole
+from onyx.db.permissions import recompute_user_permissions__no_commit
 from onyx.db.users import fetch_user_by_id
 from onyx.utils.logger import setup_logger
 
@@ -255,6 +259,7 @@ def fetch_user_groups(
     db_session: Session,
     only_up_to_date: bool = True,
     eager_load_for_snapshot: bool = False,
+    include_default: bool = True,
 ) -> Sequence[UserGroup]:
     """
     Fetches user groups from the database.
@@ -269,6 +274,7 @@ def fetch_user_groups(
             to include only up to date user groups. Defaults to `True`.
         eager_load_for_snapshot: If True, adds eager loading for all relationships
             needed by UserGroup.from_model snapshot creation.
+        include_default: If False, excludes system default groups (is_default=True).
 
     Returns:
         Sequence[UserGroup]: A sequence of `UserGroup` objects matching the query criteria.
@@ -276,6 +282,8 @@ def fetch_user_groups(
     stmt = select(UserGroup)
     if only_up_to_date:
         stmt = stmt.where(UserGroup.is_up_to_date == True)  # noqa: E712
+    if not include_default:
+        stmt = stmt.where(UserGroup.is_default == False)  # noqa: E712
     if eager_load_for_snapshot:
         stmt = _add_user_group_snapshot_eager_loads(stmt)
     return db_session.scalars(stmt).unique().all()
@@ -286,6 +294,7 @@ def fetch_user_groups_for_user(
     user_id: UUID,
     only_curator_groups: bool = False,
     eager_load_for_snapshot: bool = False,
+    include_default: bool = True,
 ) -> Sequence[UserGroup]:
     stmt = (
         select(UserGroup)
@@ -295,6 +304,8 @@ def fetch_user_groups_for_user(
     )
     if only_curator_groups:
         stmt = stmt.where(User__UserGroup.is_curator == True)  # noqa: E712
+    if not include_default:
+        stmt = stmt.where(UserGroup.is_default == False)  # noqa: E712
     if eager_load_for_snapshot:
         stmt = _add_user_group_snapshot_eager_loads(stmt)
     return db_session.scalars(stmt).unique().all()
@@ -478,6 +489,16 @@ def insert_user_group(db_session: Session, user_group: UserGroupCreate) -> UserG
     db_session.add(db_user_group)
     db_session.flush()  # give the group an ID
 
+    # Every group gets the "basic" permission by default
+    db_session.add(
+        PermissionGrant(
+            group_id=db_user_group.id,
+            permission=Permission.BASIC_ACCESS,
+            grant_source=GrantSource.SYSTEM,
+        )
+    )
+    db_session.flush()
+
     _add_user__user_group_relationships__no_commit(
         db_session=db_session,
         user_group_id=db_user_group.id,
@@ -489,6 +510,8 @@ def insert_user_group(db_session: Session, user_group: UserGroupCreate) -> UserG
         cc_pair_ids=user_group.cc_pair_ids,
     )
 
+    recompute_user_permissions__no_commit(user_group.user_ids, db_session)
+
     db_session.commit()
     return db_user_group
 
@@ -796,6 +819,10 @@ def update_user_group(
     # update "time_updated" to now
     db_user_group.time_last_modified_by_user = func.now()
 
+    recompute_user_permissions__no_commit(
+        list(set(added_user_ids) | set(removed_user_ids)), db_session
+    )
+
     db_session.commit()
     return db_user_group
 
@@ -835,6 +862,19 @@ def prepare_user_group_for_deletion(db_session: Session, user_group_id: int) ->
 
     _check_user_group_is_modifiable(db_user_group)
 
+    # Collect affected user IDs before cleanup deletes the relationships
+    affected_user_ids: list[UUID] = [
+        uid
+        for uid in db_session.execute(
+            select(User__UserGroup.user_id).where(
+                User__UserGroup.user_group_id == user_group_id
+            )
+        )
+        .scalars()
+        .all()
+        if uid is not None
+    ]
+
     _mark_user_group__cc_pair_relationships_outdated__no_commit(
         db_session=db_session, user_group_id=user_group_id
     )
@@ -863,6 +903,10 @@ def prepare_user_group_for_deletion(db_session: Session, user_group_id: int) ->
         db_session=db_session, user_group_id=user_group_id
     )
 
+    # Recompute permissions for affected users now that their
+    # membership in this group has been removed
+    recompute_user_permissions__no_commit(affected_user_ids, db_session)
+
     db_user_group.is_up_to_date = False
     db_user_group.is_up_for_deletion = True
     db_session.commit()

backend/ee/onyx/server/scim/api.py

@@ -52,16 +52,26 @@ from ee.onyx.server.scim.schema_definitions import SERVICE_PROVIDER_CONFIG
 from ee.onyx.server.scim.schema_definitions import USER_RESOURCE_TYPE
 from ee.onyx.server.scim.schema_definitions import USER_SCHEMA_DEF
 from onyx.db.engine.sql_engine import get_session
+from onyx.db.enums import AccountType
+from onyx.db.enums import GrantSource
+from onyx.db.enums import Permission
+from onyx.db.models import PermissionGrant
 from onyx.db.models import ScimToken
 from onyx.db.models import ScimUserMapping
 from onyx.db.models import User
 from onyx.db.models import UserGroup
 from onyx.db.models import UserRole
+from onyx.db.permissions import recompute_permissions_for_group__no_commit
+from onyx.db.permissions import recompute_user_permissions__no_commit
+from onyx.db.users import assign_user_to_default_groups__no_commit
 from onyx.utils.logger import setup_logger
 from onyx.utils.variable_functionality import fetch_ee_implementation_or_noop
 
 logger = setup_logger()
 
+# Group names reserved for system default groups (seeded by migration).
+_RESERVED_GROUP_NAMES = frozenset({"Admin", "Basic"})
+
 
 class ScimJSONResponse(JSONResponse):
     """JSONResponse with Content-Type: application/scim+json (RFC 7644 §3.1)."""
@@ -486,6 +496,7 @@ def create_user(
         email=email,
         hashed_password=_pw_helper.hash(_pw_helper.generate()),
         role=UserRole.BASIC,
+        account_type=AccountType.STANDARD,
         is_active=user_resource.active,
         is_verified=True,
         personal_name=personal_name,
@@ -506,13 +517,25 @@ def create_user(
             scim_username=scim_username,
             fields=fields,
         )
-        dal.commit()
     except IntegrityError:
         dal.rollback()
         return _scim_error_response(
             409, f"User with email {email} already has a SCIM mapping"
         )
 
+    # Assign user to default group BEFORE commit so everything is atomic.
+    # If this fails, the entire user creation rolls back and IdP can retry.
+    try:
+        assign_user_to_default_groups__no_commit(db_session, user)
+    except Exception:
+        dal.rollback()
+        logger.exception(f"Failed to assign SCIM user {email} to default groups")
+        return _scim_error_response(
+            500, f"Failed to assign user {email} to default group"
+        )
+
+    dal.commit()
+
     return _scim_resource_response(
         provider.build_user_resource(
             user,
@@ -857,6 +880,11 @@ def create_group(
     dal = ScimDAL(db_session)
     dal.update_token_last_used(_token.id)
 
+    if group_resource.displayName in _RESERVED_GROUP_NAMES:
+        return _scim_error_response(
+            409, f"'{group_resource.displayName}' is a reserved group name."
+        )
+
     if dal.get_group_by_name(group_resource.displayName):
         return _scim_error_response(
             409, f"Group with name '{group_resource.displayName}' already exists"
@@ -879,8 +907,21 @@ def create_group(
             409, f"Group with name '{group_resource.displayName}' already exists"
         )
 
+    # Every group gets the "basic" permission by default.
+    db_session.add(
+        PermissionGrant(
+            group_id=db_group.id,
+            permission=Permission.BASIC_ACCESS,
+            grant_source=GrantSource.SYSTEM,
+        )
+    )
+    db_session.flush()
+
     dal.upsert_group_members(db_group.id, member_uuids)
 
+    # Recompute permissions for initial members.
+    recompute_user_permissions__no_commit(member_uuids, db_session)
+
     external_id = group_resource.externalId
     if external_id:
         dal.create_group_mapping(external_id=external_id, user_group_id=db_group.id)
@@ -911,14 +952,31 @@ def replace_group(
         return result
     group = result
 
+    if (
+        group_resource.displayName in _RESERVED_GROUP_NAMES
+        and group_resource.displayName != group.name
+    ):
+        return _scim_error_response(
+            409, f"'{group_resource.displayName}' is a reserved group name."
+        )
+
     member_uuids, err = _validate_and_parse_members(group_resource.members, dal)
     if err:
         return _scim_error_response(400, err)
 
+    # Capture old member IDs before replacing so we can recompute their
+    # permissions after they are removed from the group.
+    old_member_ids = {uid for uid, _ in dal.get_group_members(group.id)}
+
     dal.update_group(group, name=group_resource.displayName)
     dal.replace_group_members(group.id, member_uuids)
     dal.sync_group_external_id(group.id, group_resource.externalId)
 
+    # Recompute permissions for current members (batch) and removed members.
+    recompute_permissions_for_group__no_commit(group.id, db_session)
+    removed_ids = list(old_member_ids - set(member_uuids))
+    recompute_user_permissions__no_commit(removed_ids, db_session)
+
     dal.commit()
 
     members = dal.get_group_members(group.id)
@@ -961,8 +1019,14 @@ def patch_group(
         return _scim_error_response(e.status, e.detail)
 
     new_name = patched.displayName if patched.displayName != group.name else None
+
+    if new_name and new_name in _RESERVED_GROUP_NAMES:
+        return _scim_error_response(409, f"'{new_name}' is a reserved group name.")
+
     dal.update_group(group, name=new_name)
 
+    affected_uuids: list[UUID] = []
+
     if added_ids:
         add_uuids = [UUID(mid) for mid in added_ids if _is_valid_uuid(mid)]
         if add_uuids:
@@ -973,10 +1037,15 @@ def patch_group(
                     f"Member(s) not found: {', '.join(str(u) for u in missing)}",
                 )
             dal.upsert_group_members(group.id, add_uuids)
+            affected_uuids.extend(add_uuids)
 
     if removed_ids:
         remove_uuids = [UUID(mid) for mid in removed_ids if _is_valid_uuid(mid)]
         dal.remove_group_members(group.id, remove_uuids)
+        affected_uuids.extend(remove_uuids)
+
+    # Recompute permissions for all users whose group membership changed.
+    recompute_user_permissions__no_commit(affected_uuids, db_session)
 
     dal.sync_group_external_id(group.id, patched.externalId)
     dal.commit()
@@ -1002,11 +1071,21 @@ def delete_group(
         return result
     group = result
 
+    if group.name in _RESERVED_GROUP_NAMES:
+        return _scim_error_response(409, f"'{group.name}' is a reserved group name.")
+
+    # Capture member IDs before deletion so we can recompute their permissions.
+    affected_user_ids = [uid for uid, _ in dal.get_group_members(group.id)]
+
     mapping = dal.get_group_mapping_by_group_id(group.id)
     if mapping:
         dal.delete_group_mapping(mapping.id)
 
     dal.delete_group_with_members(group)
+
+    # Recompute permissions for users who lost this group membership.
+    recompute_user_permissions__no_commit(affected_user_ids, db_session)
+
     dal.commit()
 
     return Response(status_code=204)

backend/ee/onyx/server/user_group/api.py

@@ -43,12 +43,16 @@ router = APIRouter(prefix="/manage", tags=PUBLIC_API_TAGS)
 
 @router.get("/admin/user-group")
 def list_user_groups(
+    include_default: bool = False,
     user: User = Depends(current_curator_or_admin_user),
     db_session: Session = Depends(get_session),
 ) -> list[UserGroup]:
     if user.role == UserRole.ADMIN:
         user_groups = fetch_user_groups(
-            db_session, only_up_to_date=False, eager_load_for_snapshot=True
+            db_session,
+            only_up_to_date=False,
+            eager_load_for_snapshot=True,
+            include_default=include_default,
         )
     else:
         user_groups = fetch_user_groups_for_user(
@@ -56,27 +60,50 @@ def list_user_groups(
             user_id=user.id,
             only_curator_groups=user.role == UserRole.CURATOR,
             eager_load_for_snapshot=True,
+            include_default=include_default,
         )
     return [UserGroup.from_model(user_group) for user_group in user_groups]
 
 
 @router.get("/user-groups/minimal")
 def list_minimal_user_groups(
+    include_default: bool = False,
     user: User = Depends(current_user),
     db_session: Session = Depends(get_session),
 ) -> list[MinimalUserGroupSnapshot]:
     if user.role == UserRole.ADMIN:
-        user_groups = fetch_user_groups(db_session, only_up_to_date=False)
+        user_groups = fetch_user_groups(
+            db_session,
+            only_up_to_date=False,
+            include_default=include_default,
+        )
     else:
         user_groups = fetch_user_groups_for_user(
             db_session=db_session,
             user_id=user.id,
+            include_default=include_default,
         )
     return [
         MinimalUserGroupSnapshot.from_model(user_group) for user_group in user_groups
     ]
 
 
+@router.get("/admin/user-group/{user_group_id}/permissions")
+def get_user_group_permissions(
+    user_group_id: int,
+    _: User = Depends(current_admin_user),
+    db_session: Session = Depends(get_session),
+) -> list[str]:
+    group = fetch_user_group(db_session, user_group_id)
+    if group is None:
+        raise OnyxError(OnyxErrorCode.NOT_FOUND, "User group not found")
+    return [
+        grant.permission.value
+        for grant in group.permission_grants
+        if not grant.is_deleted
+    ]
+
+
 @router.post("/admin/user-group")
 def create_user_group(
     user_group: UserGroupCreate,
@@ -100,6 +127,9 @@ def rename_user_group_endpoint(
     _: User = Depends(current_admin_user),
     db_session: Session = Depends(get_session),
 ) -> UserGroup:
+    group = fetch_user_group(db_session, rename_request.id)
+    if group and group.is_default:
+        raise OnyxError(OnyxErrorCode.CONFLICT, "Cannot rename a default system group.")
     try:
         return UserGroup.from_model(
             rename_user_group(
@@ -185,6 +215,9 @@ def delete_user_group(
     _: User = Depends(current_admin_user),
     db_session: Session = Depends(get_session),
 ) -> None:
+    group = fetch_user_group(db_session, user_group_id)
+    if group and group.is_default:
+        raise OnyxError(OnyxErrorCode.CONFLICT, "Cannot delete a default system group.")
     try:
         prepare_user_group_for_deletion(db_session, user_group_id)
     except ValueError as e:

backend/ee/onyx/server/user_group/models.py

@@ -22,6 +22,7 @@ class UserGroup(BaseModel):
     personas: list[PersonaSnapshot]
     is_up_to_date: bool
     is_up_for_deletion: bool
+    is_default: bool
 
     @classmethod
     def from_model(cls, user_group_model: UserGroupModel) -> "UserGroup":
@@ -74,18 +75,21 @@ class UserGroup(BaseModel):
             ],
             is_up_to_date=user_group_model.is_up_to_date,
             is_up_for_deletion=user_group_model.is_up_for_deletion,
+            is_default=user_group_model.is_default,
         )
 
 
 class MinimalUserGroupSnapshot(BaseModel):
     id: int
     name: str
+    is_default: bool
 
     @classmethod
     def from_model(cls, user_group_model: UserGroupModel) -> "MinimalUserGroupSnapshot":
         return cls(
             id=user_group_model.id,
             name=user_group_model.name,
+            is_default=user_group_model.is_default,
         )
 
 

backend/onyx/auth/permissions.py

@@ -0,0 +1,110 @@
+"""
+Permission resolution for group-based authorization.
+
+Granted permissions are stored as a JSONB column on the User table and
+loaded for free with every auth query. Implied permissions are expanded
+at read time — only directly granted permissions are persisted.
+"""
+
+from collections.abc import Callable
+from collections.abc import Coroutine
+from typing import Any
+
+from fastapi import Depends
+
+from onyx.auth.users import current_user
+from onyx.db.enums import Permission
+from onyx.db.models import User
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+from onyx.utils.logger import setup_logger
+
+logger = setup_logger()
+
+ALL_PERMISSIONS: frozenset[str] = frozenset(p.value for p in Permission)
+
+# Implication map: granted permission -> set of permissions it implies.
+IMPLIED_PERMISSIONS: dict[str, set[str]] = {
+    Permission.ADD_AGENTS.value: {Permission.READ_AGENTS.value},
+    Permission.MANAGE_AGENTS.value: {
+        Permission.ADD_AGENTS.value,
+        Permission.READ_AGENTS.value,
+    },
+    Permission.MANAGE_DOCUMENT_SETS.value: {
+        Permission.READ_DOCUMENT_SETS.value,
+        Permission.READ_CONNECTORS.value,
+    },
+    Permission.ADD_CONNECTORS.value: {Permission.READ_CONNECTORS.value},
+    Permission.MANAGE_CONNECTORS.value: {
+        Permission.ADD_CONNECTORS.value,
+        Permission.READ_CONNECTORS.value,
+    },
+    Permission.MANAGE_USER_GROUPS.value: {
+        Permission.READ_CONNECTORS.value,
+        Permission.READ_DOCUMENT_SETS.value,
+        Permission.READ_AGENTS.value,
+        Permission.READ_USERS.value,
+    },
+}
+
+
+def resolve_effective_permissions(granted: set[str]) -> set[str]:
+    """Expand granted permissions with their implied permissions.
+
+    If "admin" is present, returns all 19 permissions.
+    """
+    if Permission.FULL_ADMIN_PANEL_ACCESS.value in granted:
+        return set(ALL_PERMISSIONS)
+
+    effective = set(granted)
+    changed = True
+    while changed:
+        changed = False
+        for perm in list(effective):
+            implied = IMPLIED_PERMISSIONS.get(perm)
+            if implied and not implied.issubset(effective):
+                effective |= implied
+                changed = True
+    return effective
+
+
+def get_effective_permissions(user: User) -> set[Permission]:
+    """Read granted permissions from the column and expand implied permissions."""
+    granted: set[Permission] = set()
+    for p in user.effective_permissions:
+        try:
+            granted.add(Permission(p))
+        except ValueError:
+            logger.warning(f"Skipping unknown permission '{p}' for user {user.id}")
+    if Permission.FULL_ADMIN_PANEL_ACCESS in granted:
+        return set(Permission)
+    expanded = resolve_effective_permissions({p.value for p in granted})
+    return {Permission(p) for p in expanded}
+
+
+def require_permission(
+    required: Permission,
+) -> Callable[..., Coroutine[Any, Any, User]]:
+    """FastAPI dependency factory for permission-based access control.
+
+    Usage:
+        @router.get("/endpoint")
+        def endpoint(user: User = Depends(require_permission(Permission.MANAGE_CONNECTORS))):
+            ...
+    """
+
+    async def dependency(user: User = Depends(current_user)) -> User:
+        effective = get_effective_permissions(user)
+
+        if Permission.FULL_ADMIN_PANEL_ACCESS in effective:
+            return user
+
+        if required not in effective:
+            raise OnyxError(
+                OnyxErrorCode.INSUFFICIENT_PERMISSIONS,
+                "You do not have the required permissions for this action.",
+            )
+
+        return user
+
+    return dependency

backend/onyx/auth/schemas.py

@@ -5,6 +5,8 @@ from typing import Any
 from fastapi_users import schemas
 from typing_extensions import override
 
+from onyx.db.enums import AccountType
+
 
 class UserRole(str, Enum):
     """
@@ -41,6 +43,7 @@ class UserRead(schemas.BaseUser[uuid.UUID]):
 
 class UserCreate(schemas.BaseUserCreate):
     role: UserRole = UserRole.BASIC
+    account_type: AccountType = AccountType.STANDARD
     tenant_id: str | None = None
     # Captcha token for cloud signup protection (optional, only used when captcha is enabled)
     # Excluded from create_update_dict so it never reaches the DB layer
@@ -50,12 +53,16 @@ class UserCreate(schemas.BaseUserCreate):
     def create_update_dict(self) -> dict[str, Any]:
         d = super().create_update_dict()
         d.pop("captcha_token", None)
+        # Force STANDARD for self-registration; only trusted paths
+        # (SCIM, API key creation) supply a different account_type directly.
+        d["account_type"] = AccountType.STANDARD
         return d
 
     @override
     def create_update_dict_superuser(self) -> dict[str, Any]:
         d = super().create_update_dict_superuser()
         d.pop("captcha_token", None)
+        d.setdefault("account_type", self.account_type)
         return d
 
 

backend/onyx/auth/users.py

@@ -120,11 +120,13 @@ from onyx.db.engine.async_sql_engine import get_async_session
 from onyx.db.engine.async_sql_engine import get_async_session_context_manager
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.engine.sql_engine import get_session_with_tenant
+from onyx.db.enums import AccountType
 from onyx.db.models import AccessToken
 from onyx.db.models import OAuthAccount
 from onyx.db.models import Persona
 from onyx.db.models import User
 from onyx.db.pat import fetch_user_for_pat
+from onyx.db.users import assign_user_to_default_groups__no_commit
 from onyx.db.users import get_user_by_email
 from onyx.error_handling.error_codes import OnyxErrorCode
 from onyx.error_handling.exceptions import log_onyx_error
@@ -694,6 +696,7 @@ class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
                         "email": account_email,
                         "hashed_password": self.password_helper.hash(password),
                         "is_verified": is_verified_by_default,
+                        "account_type": AccountType.STANDARD,
                     }
 
                     user = await self.user_db.create(user_dict)
@@ -743,14 +746,23 @@ class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
                     with get_session_with_current_tenant() as sync_db:
                         enforce_seat_limit(sync_db)
 
-                await self.user_db.update(
-                    user,
-                    {
-                        "is_verified": is_verified_by_default,
-                        "role": UserRole.BASIC,
-                        **({"is_active": True} if not user.is_active else {}),
-                    },
-                )
+                # Upgrade the user and assign default groups in a single
+                # transaction so neither change is visible without the other.
+                was_inactive = not user.is_active
+                with get_session_with_current_tenant() as sync_db:
+                    sync_user = sync_db.query(User).filter(User.id == user.id).first()  # type: ignore[arg-type]
+                    if sync_user:
+                        sync_user.is_verified = is_verified_by_default
+                        sync_user.role = UserRole.BASIC
+                        sync_user.account_type = AccountType.STANDARD
+                        if was_inactive:
+                            sync_user.is_active = True
+                        assign_user_to_default_groups__no_commit(sync_db, sync_user)
+                        sync_db.commit()
+
+                # Refresh the async user object so downstream code
+                # (e.g. oidc_expiry check) sees the updated fields.
+                user = await self.user_db.get(user.id)  # type: ignore[arg-type]
 
             # this is needed if an organization goes from `TRACK_EXTERNAL_IDP_EXPIRY=true` to `false`
             # otherwise, the oidc expiry will always be old, and the user will never be able to login
@@ -836,6 +848,16 @@ class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
                     event=MilestoneRecordType.TENANT_CREATED,
                 )
 
+            # Assign user to the appropriate default group (Admin or Basic).
+            # Must happen inside the try block while tenant context is active,
+            # otherwise get_session_with_current_tenant() targets the wrong schema.
+            is_admin = user_count == 1 or user.email in get_default_admin_user_emails()
+            with get_session_with_current_tenant() as db_session:
+                assign_user_to_default_groups__no_commit(
+                    db_session, user, is_admin=is_admin
+                )
+                db_session.commit()
+
         finally:
             CURRENT_TENANT_ID_CONTEXTVAR.reset(token)
 
@@ -1554,6 +1576,7 @@ def get_anonymous_user() -> User:
         is_verified=True,
         is_superuser=False,
         role=UserRole.LIMITED,
+        account_type=AccountType.ANONYMOUS,
         use_memories=False,
         enable_memory_tool=False,
     )

backend/onyx/chat/chat_utils.py

@@ -5,7 +5,6 @@ from typing import cast
 from uuid import UUID
 
 from fastapi.datastructures import Headers
-from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
 from onyx.chat.models import ChatHistoryResult
@@ -52,60 +51,6 @@ logger = setup_logger()
 IMAGE_GENERATION_TOOL_NAME = "generate_image"
 
 
-class FileContextResult(BaseModel):
-    """Result of building a file's LLM context representation."""
-
-    message: ChatMessageSimple
-    tool_metadata: FileToolMetadata
-
-
-def build_file_context(
-    tool_file_id: str,
-    filename: str,
-    file_type: ChatFileType,
-    content_text: str | None = None,
-    token_count: int = 0,
-    approx_char_count: int | None = None,
-) -> FileContextResult:
-    """Build the LLM context representation for a single file.
-
-    Centralises how files should appear in the LLM prompt
-    — the ID that FileReaderTool accepts (``UserFile.id`` for user files).
-    """
-    if file_type.use_metadata_only():
-        message_text = (
-            f"File: {filename} (id={tool_file_id})\n"
-            "Use the file_reader or python tools to access "
-            "this file's contents."
-        )
-        message = ChatMessageSimple(
-            message=message_text,
-            token_count=max(1, len(message_text) // 4),
-            message_type=MessageType.USER,
-            file_id=tool_file_id,
-        )
-    else:
-        message_text = f"File: {filename}\n{content_text or ''}\nEnd of File"
-        message = ChatMessageSimple(
-            message=message_text,
-            token_count=token_count,
-            message_type=MessageType.USER,
-            file_id=tool_file_id,
-        )
-
-    metadata = FileToolMetadata(
-        file_id=tool_file_id,
-        filename=filename,
-        approx_char_count=(
-            approx_char_count
-            if approx_char_count is not None
-            else len(content_text or "")
-        ),
-    )
-
-    return FileContextResult(message=message, tool_metadata=metadata)
-
-
 def create_chat_session_from_request(
     chat_session_request: ChatSessionCreationRequest,
     user_id: UUID | None,
@@ -593,7 +538,7 @@ def convert_chat_history(
     for idx, chat_message in enumerate(chat_history):
         if chat_message.message_type == MessageType.USER:
             # Process files attached to this message
-            text_files: list[tuple[ChatLoadedFile, FileDescriptor]] = []
+            text_files: list[ChatLoadedFile] = []
             image_files: list[ChatLoadedFile] = []
 
             if chat_message.files:
@@ -604,26 +549,34 @@ def convert_chat_history(
                         if loaded_file.file_type == ChatFileType.IMAGE:
                             image_files.append(loaded_file)
                         else:
-                            # Text files (DOC, PLAIN_TEXT, TABULAR) are added as separate messages
-                            text_files.append((loaded_file, file_descriptor))
+                            # Text files (DOC, PLAIN_TEXT, CSV) are added as separate messages
+                            text_files.append(loaded_file)
 
             # Add text files as separate messages before the user message.
             # Each message is tagged with ``file_id`` so that forgotten files
             # can be detected after context-window truncation.
-            for text_file, fd in text_files:
-                # Use user_file_id as the FileReaderTool accepts that.
-                # Fall back to the file-store path id.
-                tool_id = fd.get("user_file_id") or text_file.file_id
-                filename = text_file.filename or "unknown"
-                ctx = build_file_context(
-                    tool_file_id=tool_id,
-                    filename=filename,
-                    file_type=text_file.file_type,
-                    content_text=text_file.content_text,
-                    token_count=text_file.token_count,
+            for text_file in text_files:
+                file_text = text_file.content_text or ""
+                filename = text_file.filename
+                message = (
+                    f"File: {filename}\n{file_text}\nEnd of File"
+                    if filename
+                    else file_text
+                )
+                simple_messages.append(
+                    ChatMessageSimple(
+                        message=message,
+                        token_count=text_file.token_count,
+                        message_type=MessageType.USER,
+                        image_files=None,
+                        file_id=text_file.file_id,
+                    )
+                )
+                all_injected_file_metadata[text_file.file_id] = FileToolMetadata(
+                    file_id=text_file.file_id,
+                    filename=filename or "unknown",
+                    approx_char_count=len(file_text),
                 )
-                simple_messages.append(ctx.message)
-                all_injected_file_metadata[tool_id] = ctx.tool_metadata
 
             # Sum token counts from image files (excluding project image files)
             image_token_count = (

backend/onyx/chat/process_message.py

@@ -18,7 +18,6 @@ from onyx.cache.interface import CacheBackend
 from onyx.chat.chat_processing_checker import set_processing_status
 from onyx.chat.chat_state import ChatStateContainer
 from onyx.chat.chat_state import run_chat_loop_with_state_containers
-from onyx.chat.chat_utils import build_file_context
 from onyx.chat.chat_utils import convert_chat_history
 from onyx.chat.chat_utils import create_chat_history_chain
 from onyx.chat.chat_utils import create_chat_session_from_request
@@ -91,7 +90,6 @@ from onyx.llm.request_context import reset_llm_mock_response
 from onyx.llm.request_context import set_llm_mock_response
 from onyx.llm.utils import litellm_exception_to_error_msg
 from onyx.onyxbot.slack.models import SlackContext
-from onyx.server.query_and_chat.chat_utils import mime_type_to_chat_file_type
 from onyx.server.query_and_chat.models import AUTO_PLACE_AFTER_LATEST_MESSAGE
 from onyx.server.query_and_chat.models import MessageResponseIDInfo
 from onyx.server.query_and_chat.models import SendMessageRequest
@@ -119,8 +117,6 @@ from shared_configs.contextvars import get_current_tenant_id
 logger = setup_logger()
 ERROR_TYPE_CANCELLED = "cancelled"
 
-APPROX_CHARS_PER_TOKEN = 4
-
 
 class _AvailableFiles(BaseModel):
     """Separated file IDs for the FileReaderTool so it knows which loader to use."""
@@ -305,27 +301,16 @@ def extract_context_files(
     if not user_files:
         return _empty_extracted_context_files()
 
-    # Aggregate tokens for the file content that will be added
-    # Skip tokens for those with metadata only
-    aggregate_tokens = sum(
-        uf.token_count or 0
-        for uf in user_files
-        if not mime_type_to_chat_file_type(uf.file_type).use_metadata_only()
-    )
+    aggregate_tokens = sum(uf.token_count or 0 for uf in user_files)
     max_actual_tokens = (
         llm_max_context_window - reserved_token_count
     ) * max_llm_context_percentage
 
     if aggregate_tokens >= max_actual_tokens:
+        tool_metadata = []
         use_as_search_filter = not DISABLE_VECTOR_DB
         if DISABLE_VECTOR_DB:
-            overflow_tool_metadata = [_build_tool_metadata(uf) for uf in user_files]
-        else:
-            overflow_tool_metadata = [
-                _build_tool_metadata(uf)
-                for uf in user_files
-                if mime_type_to_chat_file_type(uf.file_type).use_metadata_only()
-            ]
+            tool_metadata = _build_file_tool_metadata_for_user_files(user_files)
         return ExtractedContextFiles(
             file_texts=[],
             image_files=[],
@@ -333,11 +318,11 @@ def extract_context_files(
             total_token_count=0,
             file_metadata=[],
             uncapped_token_count=aggregate_tokens,
-            file_metadata_for_tool=overflow_tool_metadata,
+            file_metadata_for_tool=tool_metadata,
         )
 
     # Files fit — load them into context
-    user_file_map = {uf.file_id: uf for uf in user_files}
+    user_file_map = {str(uf.id): uf for uf in user_files}
     in_memory_files = load_in_memory_chat_files(
         user_file_ids=[uf.id for uf in user_files],
         db_session=db_session,
@@ -346,38 +331,23 @@ def extract_context_files(
     file_texts: list[str] = []
     image_files: list[ChatLoadedFile] = []
     file_metadata: list[ContextFileMetadata] = []
-    tool_metadata: list[FileToolMetadata] = []
     total_token_count = 0
 
     for f in in_memory_files:
         uf = user_file_map.get(str(f.file_id))
-        filename = f.filename or f"file_{f.file_id}"
-
-        if f.file_type.use_metadata_only():
-            # Metadata-only files are not injected as full text.
-            # Only the metadata is provided, with LLM using tools
-            if not uf:
-                logger.error(
-                    f"File with id={f.file_id} in metadata-only path with no associated user file"
-                )
-                continue
-            tool_metadata.append(_build_tool_metadata(uf))
-        elif f.file_type.is_text_file():
+        if f.file_type.is_text_file():
             text_content = _extract_text_from_in_memory_file(f)
             if not text_content:
                 continue
-            if not uf:
-                logger.warning(f"No user file for file_id={f.file_id}")
-                continue
             file_texts.append(text_content)
             file_metadata.append(
                 ContextFileMetadata(
-                    file_id=str(uf.id),
-                    filename=filename,
+                    file_id=str(f.file_id),
+                    filename=f.filename or f"file_{f.file_id}",
                     file_content=text_content,
                 )
             )
-            if uf.token_count:
+            if uf and uf.token_count:
                 total_token_count += uf.token_count
         elif f.file_type == ChatFileType.IMAGE:
             token_count = uf.token_count if uf and uf.token_count else 0
@@ -400,22 +370,24 @@ def extract_context_files(
         total_token_count=total_token_count,
         file_metadata=file_metadata,
         uncapped_token_count=aggregate_tokens,
-        file_metadata_for_tool=tool_metadata,
     )
 
 
-def _build_tool_metadata(user_file: UserFile) -> FileToolMetadata:
-    """Build lightweight FileToolMetadata from a UserFile record.
+APPROX_CHARS_PER_TOKEN = 4
 
-    Delegates to ``build_file_context`` so that the file ID exposed to the
-    LLM is always consistent with what FileReaderTool expects.
-    """
-    return build_file_context(
-        tool_file_id=str(user_file.id),
-        filename=user_file.name,
-        file_type=mime_type_to_chat_file_type(user_file.file_type),
-        approx_char_count=(user_file.token_count or 0) * APPROX_CHARS_PER_TOKEN,
-    ).tool_metadata
+
+def _build_file_tool_metadata_for_user_files(
+    user_files: list[UserFile],
+) -> list[FileToolMetadata]:
+    """Build lightweight FileToolMetadata from a list of UserFile records."""
+    return [
+        FileToolMetadata(
+            file_id=str(uf.id),
+            filename=uf.name,
+            approx_char_count=(uf.token_count or 0) * APPROX_CHARS_PER_TOKEN,
+        )
+        for uf in user_files
+    ]
 
 
 def determine_search_params(

backend/onyx/configs/constants.py

@@ -278,6 +278,7 @@ class NotificationType(str, Enum):
     RELEASE_NOTES = "release_notes"
     ASSISTANT_FILES_READY = "assistant_files_ready"
     FEATURE_ANNOUNCEMENT = "feature_announcement"
+    USER_GROUP_ASSIGNMENT_FAILED = "user_group_assignment_failed"
 
 
 class BlobType(str, Enum):

backend/onyx/db/api_key.py

@@ -1,6 +1,7 @@
 import uuid
 
 from fastapi_users.password import PasswordHelper
+from sqlalchemy import delete
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import joinedload
@@ -11,14 +12,22 @@ from onyx.auth.api_key import ApiKeyDescriptor
 from onyx.auth.api_key import build_displayable_api_key
 from onyx.auth.api_key import generate_api_key
 from onyx.auth.api_key import hash_api_key
+from onyx.auth.schemas import UserRole
 from onyx.configs.constants import DANSWER_API_KEY_DUMMY_EMAIL_DOMAIN
 from onyx.configs.constants import DANSWER_API_KEY_PREFIX
 from onyx.configs.constants import UNNAMED_KEY_PLACEHOLDER
+from onyx.db.enums import AccountType
 from onyx.db.models import ApiKey
 from onyx.db.models import User
+from onyx.db.models import User__UserGroup
+from onyx.db.models import UserGroup
+from onyx.db.permissions import recompute_user_permissions__no_commit
 from onyx.server.api_key.models import APIKeyArgs
+from onyx.utils.logger import setup_logger
 from shared_configs.contextvars import get_current_tenant_id
 
+logger = setup_logger()
+
 
 def get_api_key_email_pattern() -> str:
     return DANSWER_API_KEY_DUMMY_EMAIL_DOMAIN
@@ -87,6 +96,7 @@ def insert_api_key(
         is_superuser=False,
         is_verified=True,
         role=api_key_args.role,
+        account_type=AccountType.SERVICE_ACCOUNT,
     )
     db_session.add(api_key_user_row)
 
@@ -99,7 +109,21 @@ def insert_api_key(
     )
     db_session.add(api_key_row)
 
+    # Assign the API key virtual user to the appropriate default group
+    # before commit so everything is atomic.
+    # LIMITED role service accounts should have no group membership.
+    # Late import to avoid circular dependency (api_key <- users <- api_key).
+    if api_key_args.role != UserRole.LIMITED:
+        from onyx.db.users import assign_user_to_default_groups__no_commit
+
+        assign_user_to_default_groups__no_commit(
+            db_session,
+            api_key_user_row,
+            is_admin=(api_key_args.role == UserRole.ADMIN),
+        )
+
     db_session.commit()
+
     return ApiKeyDescriptor(
         api_key_id=api_key_row.id,
         api_key_role=api_key_user_row.role,
@@ -126,7 +150,33 @@ def update_api_key(
 
     email_name = api_key_args.name or UNNAMED_KEY_PLACEHOLDER
     api_key_user.email = get_api_key_fake_email(email_name, str(api_key_user.id))
+
+    old_role = api_key_user.role
     api_key_user.role = api_key_args.role
+
+    # Reconcile default-group membership when the role changes.
+    if old_role != api_key_args.role:
+        # Remove from all default groups first.
+        delete_stmt = delete(User__UserGroup).where(
+            User__UserGroup.user_id == api_key_user.id,
+            User__UserGroup.user_group_id.in_(
+                select(UserGroup.id).where(UserGroup.is_default.is_(True))
+            ),
+        )
+        db_session.execute(delete_stmt)
+
+        # Re-assign to the correct default group (skip for LIMITED).
+        if api_key_args.role != UserRole.LIMITED:
+            from onyx.db.users import assign_user_to_default_groups__no_commit
+
+            assign_user_to_default_groups__no_commit(
+                db_session,
+                api_key_user,
+                is_admin=(api_key_args.role == UserRole.ADMIN),
+            )
+
+        recompute_user_permissions__no_commit(api_key_user.id, db_session)
+
     db_session.commit()
 
     return ApiKeyDescriptor(

backend/onyx/db/enums.py

@@ -13,19 +13,19 @@ class AccountType(str, PyEnum):
     BOT, EXT_PERM_USER, ANONYMOUS → fixed behavior
     """
 
-    STANDARD = "standard"
-    BOT = "bot"
-    EXT_PERM_USER = "ext_perm_user"
-    SERVICE_ACCOUNT = "service_account"
-    ANONYMOUS = "anonymous"
+    STANDARD = "STANDARD"
+    BOT = "BOT"
+    EXT_PERM_USER = "EXT_PERM_USER"
+    SERVICE_ACCOUNT = "SERVICE_ACCOUNT"
+    ANONYMOUS = "ANONYMOUS"
 
 
 class GrantSource(str, PyEnum):
     """How a permission grant was created."""
 
-    USER = "user"
-    SCIM = "scim"
-    SYSTEM = "system"
+    USER = "USER"
+    SCIM = "SCIM"
+    SYSTEM = "SYSTEM"
 
 
 class IndexingStatus(str, PyEnum):

backend/onyx/db/models.py

@@ -305,8 +305,11 @@ class User(SQLAlchemyBaseUserTableUUID, Base):
     role: Mapped[UserRole] = mapped_column(
         Enum(UserRole, native_enum=False, default=UserRole.BASIC)
     )
-    account_type: Mapped[AccountType | None] = mapped_column(
-        Enum(AccountType, native_enum=False), nullable=True
+    account_type: Mapped[AccountType] = mapped_column(
+        Enum(AccountType, native_enum=False),
+        nullable=False,
+        default=AccountType.STANDARD,
+        server_default="STANDARD",
     )
 
     """
@@ -353,6 +356,13 @@ class User(SQLAlchemyBaseUserTableUUID, Base):
         postgresql.JSONB(), nullable=True, default=None
     )
 
+    effective_permissions: Mapped[list[str]] = mapped_column(
+        postgresql.JSONB(),
+        nullable=False,
+        default=list,
+        server_default=text("'[]'::jsonb"),
+    )
+
     oidc_expiry: Mapped[datetime.datetime] = mapped_column(
         TIMESTAMPAware(timezone=True), nullable=True
     )
@@ -4016,7 +4026,12 @@ class PermissionGrant(Base):
         ForeignKey("user_group.id", ondelete="CASCADE"), nullable=False
     )
     permission: Mapped[Permission] = mapped_column(
-        Enum(Permission, native_enum=False), nullable=False
+        Enum(
+            Permission,
+            native_enum=False,
+            values_callable=lambda x: [e.value for e in x],
+        ),
+        nullable=False,
     )
     grant_source: Mapped[GrantSource] = mapped_column(
         Enum(GrantSource, native_enum=False), nullable=False

backend/onyx/db/notification.py

@@ -3,6 +3,7 @@ from datetime import timezone
 from uuid import UUID
 
 from sqlalchemy import cast
+from sqlalchemy import or_
 from sqlalchemy import select
 from sqlalchemy.dialects import postgresql
 from sqlalchemy.dialects.postgresql import insert
@@ -90,9 +91,18 @@ def get_notifications(
     notif_type: NotificationType | None = None,
     include_dismissed: bool = True,
 ) -> list[Notification]:
-    query = select(Notification).where(
-        Notification.user_id == user.id if user else Notification.user_id.is_(None)
-    )
+    if user is None:
+        user_filter = Notification.user_id.is_(None)
+    elif user.role == UserRole.ADMIN:
+        # Admins see their own notifications AND admin-targeted ones (user_id IS NULL)
+        user_filter = or_(
+            Notification.user_id == user.id,
+            Notification.user_id.is_(None),
+        )
+    else:
+        user_filter = Notification.user_id == user.id
+
+    query = select(Notification).where(user_filter)
     if not include_dismissed:
         query = query.where(Notification.dismissed.is_(False))
     if notif_type:

backend/onyx/db/permissions.py

@@ -0,0 +1,95 @@
+"""
+DB operations for recomputing user effective_permissions.
+
+These live in onyx/db/ (not onyx/auth/) because they are pure DB operations
+that query PermissionGrant rows and update the User.effective_permissions
+JSONB column.  Keeping them here avoids circular imports when called from
+other onyx/db/ modules such as users.py.
+"""
+
+from collections import defaultdict
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy import update
+from sqlalchemy.orm import Session
+
+from onyx.db.models import PermissionGrant
+from onyx.db.models import User
+from onyx.db.models import User__UserGroup
+
+
+def recompute_user_permissions__no_commit(
+    user_ids: UUID | list[UUID], db_session: Session
+) -> None:
+    """Recompute granted permissions for one or more users.
+
+    Accepts a single UUID or a list.  Uses a single query regardless of
+    how many users are passed, avoiding N+1 issues.
+
+    Stores only directly granted permissions — implication expansion
+    happens at read time via get_effective_permissions().
+
+    Does NOT commit — caller must commit the session.
+    """
+    if isinstance(user_ids, UUID):
+        uid_list = [user_ids]
+    else:
+        uid_list = list(user_ids)
+
+    if not uid_list:
+        return
+
+    # Single query to fetch ALL permissions for these users across ALL their
+    # groups (a user may belong to multiple groups with different grants).
+    rows = db_session.execute(
+        select(User__UserGroup.user_id, PermissionGrant.permission)
+        .join(
+            PermissionGrant,
+            PermissionGrant.group_id == User__UserGroup.user_group_id,
+        )
+        .where(
+            User__UserGroup.user_id.in_(uid_list),
+            PermissionGrant.is_deleted.is_(False),
+        )
+    ).all()
+
+    # Group permissions by user; users with no grants get an empty set.
+    perms_by_user: dict[UUID, set[str]] = defaultdict(set)
+    for uid in uid_list:
+        perms_by_user[uid]  # ensure every user has an entry
+    for uid, perm in rows:
+        perms_by_user[uid].add(perm.value)
+
+    for uid, perms in perms_by_user.items():
+        db_session.execute(
+            update(User)
+            .where(User.id == uid)  # type: ignore[arg-type]
+            .values(effective_permissions=sorted(perms))
+        )
+
+
+def recompute_permissions_for_group__no_commit(
+    group_id: int, db_session: Session
+) -> None:
+    """Recompute granted permissions for all users in a group.
+
+    Does NOT commit — caller must commit the session.
+    """
+    user_ids: list[UUID] = [
+        uid
+        for uid in db_session.execute(
+            select(User__UserGroup.user_id).where(
+                User__UserGroup.user_group_id == group_id,
+                User__UserGroup.user_id.isnot(None),
+            )
+        )
+        .scalars()
+        .all()
+        if uid is not None
+    ]
+
+    if not user_ids:
+        return
+
+    recompute_user_permissions__no_commit(user_ids, db_session)

backend/onyx/db/users.py

@@ -19,6 +19,7 @@ from onyx.auth.schemas import UserRole
 from onyx.configs.constants import ANONYMOUS_USER_EMAIL
 from onyx.configs.constants import NO_AUTH_PLACEHOLDER_USER_EMAIL
 from onyx.db.api_key import DANSWER_API_KEY_DUMMY_EMAIL_DOMAIN
+from onyx.db.enums import AccountType
 from onyx.db.models import DocumentSet
 from onyx.db.models import DocumentSet__User
 from onyx.db.models import Persona
@@ -27,8 +28,11 @@ from onyx.db.models import SamlAccount
 from onyx.db.models import User
 from onyx.db.models import User__UserGroup
 from onyx.db.models import UserGroup
+from onyx.utils.logger import setup_logger
 from onyx.utils.variable_functionality import fetch_ee_implementation_or_noop
 
+logger = setup_logger()
+
 
 def validate_user_role_update(
     requested_role: UserRole, current_role: UserRole, explicit_override: bool = False
@@ -298,6 +302,7 @@ def _generate_slack_user(email: str) -> User:
         email=email,
         hashed_password=hashed_pass,
         role=UserRole.SLACK_USER,
+        account_type=AccountType.BOT,
     )
 
 
@@ -308,6 +313,7 @@ def add_slack_user_if_not_exists(db_session: Session, email: str) -> User:
         # If the user is an external permissioned user, we update it to a slack user
         if user.role == UserRole.EXT_PERM_USER:
             user.role = UserRole.SLACK_USER
+            user.account_type = AccountType.BOT
             db_session.commit()
         return user
 
@@ -344,6 +350,7 @@ def _generate_ext_permissioned_user(email: str) -> User:
         email=email,
         hashed_password=hashed_pass,
         role=UserRole.EXT_PERM_USER,
+        account_type=AccountType.EXT_PERM_USER,
     )
 
 
@@ -375,6 +382,81 @@ def batch_add_ext_perm_user_if_not_exists(
     return all_users
 
 
+def assign_user_to_default_groups__no_commit(
+    db_session: Session,
+    user: User,
+    is_admin: bool = False,
+) -> None:
+    """Assign a newly created user to the appropriate default group.
+
+    Does NOT commit — callers must commit the session themselves so that
+    group assignment can be part of the same transaction as user creation.
+
+    Args:
+        is_admin: If True, assign to Admin default group; otherwise Basic.
+            Callers determine this from their own context (e.g. user_count,
+            admin email list, explicit choice). Defaults to False (Basic).
+    """
+    if user.account_type in (
+        AccountType.BOT,
+        AccountType.EXT_PERM_USER,
+        AccountType.ANONYMOUS,
+    ):
+        return
+
+    target_group_name = "Admin" if is_admin else "Basic"
+
+    default_group = (
+        db_session.query(UserGroup)
+        .filter(
+            UserGroup.name == target_group_name,
+            UserGroup.is_default.is_(True),
+        )
+        .first()
+    )
+
+    if default_group is None:
+        raise RuntimeError(
+            f"Default group '{target_group_name}' not found. "
+            f"Cannot assign user {user.email} to a group. "
+            f"Ensure the seed_default_groups migration has run."
+        )
+
+    # Check if the user is already in the group
+    existing = (
+        db_session.query(User__UserGroup)
+        .filter(
+            User__UserGroup.user_id == user.id,
+            User__UserGroup.user_group_id == default_group.id,
+        )
+        .first()
+    )
+    if existing is not None:
+        return
+
+    savepoint = db_session.begin_nested()
+    try:
+        db_session.add(
+            User__UserGroup(
+                user_id=user.id,
+                user_group_id=default_group.id,
+            )
+        )
+        db_session.flush()
+    except IntegrityError:
+        # Race condition: another transaction inserted this membership
+        # between our SELECT and INSERT. The savepoint isolates the failure
+        # so the outer transaction (user creation) stays intact.
+        savepoint.rollback()
+        return
+
+    from onyx.db.permissions import recompute_user_permissions__no_commit
+
+    recompute_user_permissions__no_commit(user.id, db_session)
+
+    logger.info(f"Assigned user {user.email} to default group '{default_group.name}'")
+
+
 def delete_user_from_db(
     user_to_delete: User,
     db_session: Session,
@@ -421,13 +503,14 @@ def delete_user_from_db(
 def batch_get_user_groups(
     db_session: Session,
     user_ids: list[UUID],
+    include_default: bool = False,
 ) -> dict[UUID, list[tuple[int, str]]]:
     """Fetch group memberships for a batch of users in a single query.
     Returns a mapping of user_id -> list of (group_id, group_name) tuples."""
     if not user_ids:
         return {}
 
-    rows = db_session.execute(
+    stmt = (
         select(
             User__UserGroup.user_id,
             UserGroup.id,
@@ -435,7 +518,11 @@ def batch_get_user_groups(
         )
         .join(UserGroup, UserGroup.id == User__UserGroup.user_group_id)
         .where(User__UserGroup.user_id.in_(user_ids))
-    ).all()
+    )
+    if not include_default:
+        stmt = stmt.where(UserGroup.is_default == False)  # noqa: E712
+
+    rows = db_session.execute(stmt).all()
 
     result: dict[UUID, list[tuple[int, str]]] = {uid: [] for uid in user_ids}
     for user_id, group_id, group_name in rows:

backend/onyx/file_store/models.py

@@ -23,11 +23,6 @@ class ChatFileType(str, Enum):
             ChatFileType.TABULAR,
         )
 
-    def use_metadata_only(self) -> bool:
-        """File types where we can ignore the file content
-        and only use the metadata."""
-        return self in (ChatFileType.TABULAR,)
-
 
 class FileDescriptor(TypedDict):
     """NOTE: is a `TypedDict` so it can be used as a type hint for a JSONB column

backend/onyx/file_store/utils.py

@@ -110,20 +110,16 @@ def load_user_file(file_id: UUID, db_session: Session) -> InMemoryChatFile:
     # check for plain text normalized version first, then use original file otherwise
     try:
         file_io = file_store.read_file(plaintext_file_name, mode="b")
-        # Metadata-only file types preserve their original type so
-        # downstream injection paths can route them correctly.
-        if chat_file_type.use_metadata_only():
-            plaintext_chat_file_type = chat_file_type
-        elif file_io is not None:
-            # if we have plaintext for image (which happens when image
-            # extraction is enabled), we use PLAIN_TEXT type
+        # For plaintext versions, use PLAIN_TEXT type (unless it's an image which doesn't have plaintext)
+        plaintext_chat_file_type = (
+            ChatFileType.PLAIN_TEXT
+            if chat_file_type != ChatFileType.IMAGE
+            else chat_file_type
+        )
+
+        # if we have plaintext for image (which happens when image extraction is enabled), we use PLAIN_TEXT type
+        if file_io is not None:
             plaintext_chat_file_type = ChatFileType.PLAIN_TEXT
-        else:
-            plaintext_chat_file_type = (
-                ChatFileType.PLAIN_TEXT
-                if chat_file_type != ChatFileType.IMAGE
-                else chat_file_type
-            )
 
         chat_file = InMemoryChatFile(
             file_id=str(user_file.file_id),

backend/onyx/server/manage/users.py

@@ -27,6 +27,7 @@ from onyx.auth.email_utils import send_user_email_invite
 from onyx.auth.invited_users import get_invited_users
 from onyx.auth.invited_users import remove_user_from_invited_users
 from onyx.auth.invited_users import write_invited_users
+from onyx.auth.permissions import get_effective_permissions
 from onyx.auth.schemas import UserRole
 from onyx.auth.users import anonymous_user_enabled
 from onyx.auth.users import current_admin_user
@@ -773,6 +774,13 @@ def _get_token_created_at(
     return get_current_token_creation_postgres(user, db_session)
 
 
+@router.get("/me/permissions", tags=PUBLIC_API_TAGS)
+def get_current_user_permissions(
+    user: User = Depends(current_user),
+) -> list[str]:
+    return sorted(p.value for p in get_effective_permissions(user))
+
+
 @router.get("/me", tags=PUBLIC_API_TAGS)
 def verify_user_logged_in(
     request: Request,

backend/onyx/server/models.py

@@ -7,6 +7,7 @@ from uuid import UUID
 from pydantic import BaseModel
 
 from onyx.auth.schemas import UserRole
+from onyx.db.enums import AccountType
 from onyx.db.models import User
 
 
@@ -41,6 +42,7 @@ class FullUserSnapshot(BaseModel):
     id: UUID
     email: str
     role: UserRole
+    account_type: AccountType
     is_active: bool
     password_configured: bool
     personal_name: str | None
@@ -60,6 +62,7 @@ class FullUserSnapshot(BaseModel):
             id=user.id,
             email=user.email,
             role=user.role,
+            account_type=user.account_type,
             is_active=user.is_active,
             password_configured=user.password_configured,
             personal_name=user.personal_name,

backend/requirements/default.txt

@@ -271,7 +271,7 @@ fastapi-users-db-sqlalchemy==7.0.0
     # via onyx
 fastavro==1.12.1
     # via cohere
-fastmcp==3.2.0
+fastmcp==3.0.2
     # via onyx
 fastuuid==0.14.0
     # via litellm
@@ -1102,8 +1102,6 @@ tzdata==2025.2
     #   tzlocal
 tzlocal==5.3.1
     # via dateparser
-uncalled-for==0.2.0
-    # via fastmcp
 unstructured==0.18.27
     # via onyx
 unstructured-client==0.42.6

backend/tests/external_dependency_unit/conftest.py

@@ -7,6 +7,7 @@ from sqlalchemy.orm import Session
 
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.engine.sql_engine import SqlEngine
+from onyx.db.enums import AccountType
 from onyx.db.models import User
 from onyx.db.models import UserRole
 from onyx.file_store.file_store import get_default_file_store
@@ -52,7 +53,12 @@ def tenant_context() -> Generator[None, None, None]:
         CURRENT_TENANT_ID_CONTEXTVAR.reset(token)
 
 
-def create_test_user(db_session: Session, email_prefix: str) -> User:
+def create_test_user(
+    db_session: Session,
+    email_prefix: str,
+    role: UserRole = UserRole.BASIC,
+    account_type: AccountType = AccountType.STANDARD,
+) -> User:
     """Helper to create a test user with a unique email"""
     # Use UUID to ensure unique email addresses
     unique_email = f"{email_prefix}_{uuid4().hex[:8]}@example.com"
@@ -68,7 +74,8 @@ def create_test_user(db_session: Session, email_prefix: str) -> User:
         is_active=True,
         is_superuser=False,
         is_verified=True,
-        role=UserRole.EXT_PERM_USER,
+        role=role,
+        account_type=account_type,
     )
     db_session.add(user)
     db_session.commit()

backend/tests/external_dependency_unit/connectors/google_drive/test_google_drive_group_sync.py

@@ -13,16 +13,29 @@ from onyx.access.utils import build_ext_group_name_for_onyx
 from onyx.configs.constants import DocumentSource
 from onyx.connectors.models import InputType
 from onyx.db.enums import AccessType
+from onyx.db.enums import AccountType
 from onyx.db.enums import ConnectorCredentialPairStatus
 from onyx.db.models import Connector
 from onyx.db.models import ConnectorCredentialPair
 from onyx.db.models import Credential
 from onyx.db.models import PublicExternalUserGroup
+from onyx.db.models import User
 from onyx.db.models import User__ExternalUserGroupId
+from onyx.db.models import UserRole
 from tests.external_dependency_unit.conftest import create_test_user
 from tests.external_dependency_unit.constants import TEST_TENANT_ID
 
 
+def _create_ext_perm_user(db_session: Session, name: str) -> User:
+    """Create an external-permission user for group sync tests."""
+    return create_test_user(
+        db_session,
+        name,
+        role=UserRole.EXT_PERM_USER,
+        account_type=AccountType.EXT_PERM_USER,
+    )
+
+
 def _create_test_connector_credential_pair(
     db_session: Session, source: DocumentSource = DocumentSource.GOOGLE_DRIVE
 ) -> ConnectorCredentialPair:
@@ -100,9 +113,9 @@ class TestPerformExternalGroupSync:
     def test_initial_group_sync(self, db_session: Session) -> None:
         """Test syncing external groups for the first time (initial sync)"""
         # Create test data
-        user1 = create_test_user(db_session, "user1")
-        user2 = create_test_user(db_session, "user2")
-        user3 = create_test_user(db_session, "user3")
+        user1 = _create_ext_perm_user(db_session, "user1")
+        user2 = _create_ext_perm_user(db_session, "user2")
+        user3 = _create_ext_perm_user(db_session, "user3")
         cc_pair = _create_test_connector_credential_pair(db_session)
 
         # Mock external groups data as a generator that yields the expected groups
@@ -175,9 +188,9 @@ class TestPerformExternalGroupSync:
     def test_update_existing_groups(self, db_session: Session) -> None:
         """Test updating existing groups (adding/removing users)"""
         # Create test data
-        user1 = create_test_user(db_session, "user1")
-        user2 = create_test_user(db_session, "user2")
-        user3 = create_test_user(db_session, "user3")
+        user1 = _create_ext_perm_user(db_session, "user1")
+        user2 = _create_ext_perm_user(db_session, "user2")
+        user3 = _create_ext_perm_user(db_session, "user3")
         cc_pair = _create_test_connector_credential_pair(db_session)
 
         # Initial sync with original groups
@@ -272,8 +285,8 @@ class TestPerformExternalGroupSync:
     def test_remove_groups(self, db_session: Session) -> None:
         """Test removing groups (groups that no longer exist in external system)"""
         # Create test data
-        user1 = create_test_user(db_session, "user1")
-        user2 = create_test_user(db_session, "user2")
+        user1 = _create_ext_perm_user(db_session, "user1")
+        user2 = _create_ext_perm_user(db_session, "user2")
         cc_pair = _create_test_connector_credential_pair(db_session)
 
         # Initial sync with multiple groups
@@ -357,7 +370,7 @@ class TestPerformExternalGroupSync:
     def test_empty_group_sync(self, db_session: Session) -> None:
         """Test syncing when no groups are returned (all groups removed)"""
         # Create test data
-        user1 = create_test_user(db_session, "user1")
+        user1 = _create_ext_perm_user(db_session, "user1")
         cc_pair = _create_test_connector_credential_pair(db_session)
 
         # Initial sync with groups
@@ -413,7 +426,7 @@ class TestPerformExternalGroupSync:
         # Create many test users
         users = []
         for i in range(150):  # More than the batch size of 100
-            users.append(create_test_user(db_session, f"user{i}"))
+            users.append(_create_ext_perm_user(db_session, f"user{i}"))
 
         cc_pair = _create_test_connector_credential_pair(db_session)
 
@@ -452,8 +465,8 @@ class TestPerformExternalGroupSync:
     def test_mixed_regular_and_public_groups(self, db_session: Session) -> None:
         """Test syncing a mix of regular and public groups"""
         # Create test data
-        user1 = create_test_user(db_session, "user1")
-        user2 = create_test_user(db_session, "user2")
+        user1 = _create_ext_perm_user(db_session, "user1")
+        user2 = _create_ext_perm_user(db_session, "user2")
         cc_pair = _create_test_connector_credential_pair(db_session)
 
         def mixed_group_sync_func(

backend/tests/external_dependency_unit/craft/conftest.py

@@ -9,6 +9,7 @@ from sqlalchemy.orm import Session
 
 from onyx.db.engine.sql_engine import get_session_with_current_tenant
 from onyx.db.engine.sql_engine import SqlEngine
+from onyx.db.enums import AccountType
 from onyx.db.enums import BuildSessionStatus
 from onyx.db.models import BuildSession
 from onyx.db.models import User
@@ -52,6 +53,7 @@ def test_user(db_session: Session, tenant_context: None) -> User:  # noqa: ARG00
         is_superuser=False,
         is_verified=True,
         role=UserRole.EXT_PERM_USER,
+        account_type=AccountType.EXT_PERM_USER,
     )
     db_session.add(user)
     db_session.commit()

backend/tests/external_dependency_unit/db/test_user_account_type.py

@@ -0,0 +1,51 @@
+"""
+Tests that account_type is correctly set when creating users through
+the internal DB functions: add_slack_user_if_not_exists and
+batch_add_ext_perm_user_if_not_exists.
+
+These functions are called by background workers (Slack bot, permission sync)
+and are not exposed via API endpoints, so they must be tested directly.
+"""
+
+from sqlalchemy.orm import Session
+
+from onyx.db.enums import AccountType
+from onyx.db.models import UserRole
+from onyx.db.users import add_slack_user_if_not_exists
+from onyx.db.users import batch_add_ext_perm_user_if_not_exists
+
+
+def test_slack_user_creation_sets_account_type_bot(db_session: Session) -> None:
+    """add_slack_user_if_not_exists sets account_type=BOT and role=SLACK_USER."""
+    user = add_slack_user_if_not_exists(db_session, "slack_acct_type@test.com")
+
+    assert user.role == UserRole.SLACK_USER
+    assert user.account_type == AccountType.BOT
+
+
+def test_ext_perm_user_creation_sets_account_type(db_session: Session) -> None:
+    """batch_add_ext_perm_user_if_not_exists sets account_type=EXT_PERM_USER."""
+    users = batch_add_ext_perm_user_if_not_exists(
+        db_session, ["extperm_acct_type@test.com"]
+    )
+
+    assert len(users) == 1
+    user = users[0]
+    assert user.role == UserRole.EXT_PERM_USER
+    assert user.account_type == AccountType.EXT_PERM_USER
+
+
+def test_ext_perm_to_slack_upgrade_updates_role_and_account_type(
+    db_session: Session,
+) -> None:
+    """When an EXT_PERM_USER is upgraded to slack, both role and account_type update."""
+    email = "ext_to_slack_acct_type@test.com"
+
+    # Create as ext_perm user first
+    batch_add_ext_perm_user_if_not_exists(db_session, [email])
+
+    # Now "upgrade" via slack path
+    user = add_slack_user_if_not_exists(db_session, email)
+
+    assert user.role == UserRole.SLACK_USER
+    assert user.account_type == AccountType.BOT

backend/tests/external_dependency_unit/llm/test_llm_provider_called.py

@@ -8,6 +8,7 @@ import pytest
 from fastapi_users.password import PasswordHelper
 from sqlalchemy.orm import Session
 
+from onyx.db.enums import AccountType
 from onyx.db.llm import fetch_existing_llm_provider
 from onyx.db.llm import remove_llm_provider
 from onyx.db.llm import update_default_provider
@@ -46,6 +47,7 @@ def _create_admin(db_session: Session) -> User:
         is_superuser=True,
         is_verified=True,
         role=UserRole.ADMIN,
+        account_type=AccountType.STANDARD,
     )
     db_session.add(user)
     db_session.commit()

backend/tests/integration/common_utils/managers/user.py

@@ -126,6 +126,15 @@ class UserManager:
 
         return test_user
 
+    @staticmethod
+    def get_permissions(user: DATestUser) -> list[str]:
+        response = requests.get(
+            url=f"{API_SERVER_URL}/me/permissions",
+            headers=user.headers,
+        )
+        response.raise_for_status()
+        return response.json()
+
     @staticmethod
     def is_role(
         user_to_verify: DATestUser,

backend/tests/integration/common_utils/managers/user_group.py

@@ -104,13 +104,30 @@ class UserGroupManager:
         )
         response.raise_for_status()
 
+    @staticmethod
+    def get_permissions(
+        user_group: DATestUserGroup,
+        user_performing_action: DATestUser,
+    ) -> list[str]:
+        response = requests.get(
+            f"{API_SERVER_URL}/manage/admin/user-group/{user_group.id}/permissions",
+            headers=user_performing_action.headers,
+        )
+        response.raise_for_status()
+        return response.json()
+
     @staticmethod
     def get_all(
         user_performing_action: DATestUser,
+        include_default: bool = False,
     ) -> list[UserGroup]:
+        params: dict[str, str] = {}
+        if include_default:
+            params["include_default"] = "true"
         response = requests.get(
             f"{API_SERVER_URL}/manage/admin/user-group",
             headers=user_performing_action.headers,
+            params=params,
         )
         response.raise_for_status()
         return [UserGroup(**ug) for ug in response.json()]

backend/tests/integration/tests/api_key/test_api_key.py

@@ -1,9 +1,13 @@
+from uuid import UUID
+
 import requests
 
 from onyx.auth.schemas import UserRole
+from onyx.db.enums import AccountType
 from tests.integration.common_utils.constants import API_SERVER_URL
 from tests.integration.common_utils.managers.api_key import APIKeyManager
 from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.managers.user_group import UserGroupManager
 from tests.integration.common_utils.test_models import DATestAPIKey
 from tests.integration.common_utils.test_models import DATestUser
 
@@ -33,3 +37,120 @@ def test_limited(reset: None) -> None:  # noqa: ARG001
         headers=api_key.headers,
     )
     assert response.status_code == 403
+
+
+def _get_service_account_account_type(
+    admin_user: DATestUser,
+    api_key_user_id: UUID,
+) -> AccountType:
+    """Fetch the account_type of a service account user via the user listing API."""
+    response = requests.get(
+        f"{API_SERVER_URL}/manage/users",
+        headers=admin_user.headers,
+        params={"include_api_keys": "true"},
+    )
+    response.raise_for_status()
+    data = response.json()
+    user_id_str = str(api_key_user_id)
+    for user in data["accepted"]:
+        if user["id"] == user_id_str:
+            return AccountType(user["account_type"])
+    raise AssertionError(
+        f"Service account user {user_id_str} not found in user listing"
+    )
+
+
+def _get_default_group_user_ids(
+    admin_user: DATestUser,
+) -> tuple[set[str], set[str]]:
+    """Return (admin_group_user_ids, basic_group_user_ids) from default groups."""
+    all_groups = UserGroupManager.get_all(
+        user_performing_action=admin_user,
+        include_default=True,
+    )
+    admin_group = next(
+        (g for g in all_groups if g.name == "Admin" and g.is_default), None
+    )
+    basic_group = next(
+        (g for g in all_groups if g.name == "Basic" and g.is_default), None
+    )
+    assert admin_group is not None, "Admin default group not found"
+    assert basic_group is not None, "Basic default group not found"
+
+    admin_ids = {str(u.id) for u in admin_group.users}
+    basic_ids = {str(u.id) for u in basic_group.users}
+    return admin_ids, basic_ids
+
+
+def test_api_key_limited_service_account(reset: None) -> None:  # noqa: ARG001
+    """LIMITED role API key: account_type is SERVICE_ACCOUNT, no group membership."""
+    admin_user: DATestUser = UserManager.create(name="admin_user")
+
+    api_key: DATestAPIKey = APIKeyManager.create(
+        api_key_role=UserRole.LIMITED,
+        user_performing_action=admin_user,
+    )
+
+    # Verify account_type
+    account_type = _get_service_account_account_type(admin_user, api_key.user_id)
+    assert (
+        account_type == AccountType.SERVICE_ACCOUNT
+    ), f"Expected account_type={AccountType.SERVICE_ACCOUNT}, got {account_type}"
+
+    # Verify no group membership
+    admin_ids, basic_ids = _get_default_group_user_ids(admin_user)
+    user_id_str = str(api_key.user_id)
+    assert (
+        user_id_str not in admin_ids
+    ), "LIMITED API key should NOT be in Admin default group"
+    assert (
+        user_id_str not in basic_ids
+    ), "LIMITED API key should NOT be in Basic default group"
+
+
+def test_api_key_basic_service_account(reset: None) -> None:  # noqa: ARG001
+    """BASIC role API key: account_type is SERVICE_ACCOUNT, in Basic group only."""
+    admin_user: DATestUser = UserManager.create(name="admin_user")
+
+    api_key: DATestAPIKey = APIKeyManager.create(
+        api_key_role=UserRole.BASIC,
+        user_performing_action=admin_user,
+    )
+
+    # Verify account_type
+    account_type = _get_service_account_account_type(admin_user, api_key.user_id)
+    assert (
+        account_type == AccountType.SERVICE_ACCOUNT
+    ), f"Expected account_type={AccountType.SERVICE_ACCOUNT}, got {account_type}"
+
+    # Verify Basic group membership
+    admin_ids, basic_ids = _get_default_group_user_ids(admin_user)
+    user_id_str = str(api_key.user_id)
+    assert user_id_str in basic_ids, "BASIC API key should be in Basic default group"
+    assert (
+        user_id_str not in admin_ids
+    ), "BASIC API key should NOT be in Admin default group"
+
+
+def test_api_key_admin_service_account(reset: None) -> None:  # noqa: ARG001
+    """ADMIN role API key: account_type is SERVICE_ACCOUNT, in Admin group only."""
+    admin_user: DATestUser = UserManager.create(name="admin_user")
+
+    api_key: DATestAPIKey = APIKeyManager.create(
+        api_key_role=UserRole.ADMIN,
+        user_performing_action=admin_user,
+    )
+
+    # Verify account_type
+    account_type = _get_service_account_account_type(admin_user, api_key.user_id)
+    assert (
+        account_type == AccountType.SERVICE_ACCOUNT
+    ), f"Expected account_type={AccountType.SERVICE_ACCOUNT}, got {account_type}"
+
+    # Verify Admin group membership
+    admin_ids, basic_ids = _get_default_group_user_ids(admin_user)
+    user_id_str = str(api_key.user_id)
+    assert user_id_str in admin_ids, "ADMIN API key should be in Admin default group"
+    assert (
+        user_id_str not in basic_ids
+    ), "ADMIN API key should NOT be in Basic default group"

backend/tests/integration/tests/auth/test_saml_user_conversion.py

@@ -4,8 +4,10 @@ import pytest
 import requests
 
 from onyx.auth.schemas import UserRole
+from onyx.db.enums import AccountType
 from tests.integration.common_utils.constants import API_SERVER_URL
 from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.managers.user_group import UserGroupManager
 from tests.integration.common_utils.test_models import DATestUser
 
 
@@ -95,3 +97,63 @@ def test_saml_user_conversion(reset: None) -> None:  # noqa: ARG001
 
     # Verify the user's role was changed in the database
     assert UserManager.is_role(slack_user, UserRole.BASIC)
+
+
+@pytest.mark.skipif(
+    os.environ.get("ENABLE_PAID_ENTERPRISE_EDITION_FEATURES", "").lower() != "true",
+    reason="SAML tests are enterprise only",
+)
+def test_saml_user_conversion_sets_account_type_and_group(
+    reset: None,  # noqa: ARG001
+) -> None:
+    """
+    Test that SAML login sets account_type to STANDARD when converting a
+    non-web user (EXT_PERM_USER) and that the user receives the correct role
+    (BASIC) after conversion.
+
+    This validates the permissions-migration-phase2 changes which ensure that:
+    1. account_type is updated to 'standard' on SAML conversion
+    2. The converted user is assigned to the Basic default group
+    """
+    # Create an admin user (first user is automatically admin)
+    admin_user: DATestUser = UserManager.create(email="admin@example.com")
+
+    # Create a user and set them as EXT_PERM_USER
+    test_email = "ext_convert@example.com"
+    test_user = UserManager.create(email=test_email)
+    UserManager.set_role(
+        user_to_set=test_user,
+        target_role=UserRole.EXT_PERM_USER,
+        user_performing_action=admin_user,
+        explicit_override=True,
+    )
+    assert UserManager.is_role(test_user, UserRole.EXT_PERM_USER)
+
+    # Simulate SAML login
+    response = requests.post(
+        f"{API_SERVER_URL}/manage/users/test-upsert-user",
+        json={"email": test_email},
+        headers=admin_user.headers,
+    )
+    response.raise_for_status()
+    user_data = response.json()
+
+    # Verify account_type is set to standard after conversion
+    assert (
+        user_data["account_type"] == AccountType.STANDARD.value
+    ), f"Expected account_type='{AccountType.STANDARD.value}', got '{user_data['account_type']}'"
+
+    # Verify role is BASIC after conversion
+    assert user_data["role"] == UserRole.BASIC.value
+
+    # Verify the user was assigned to the Basic default group
+    all_groups = UserGroupManager.get_all(admin_user, include_default=True)
+    basic_default = [g for g in all_groups if g.is_default and g.name == "Basic"]
+    assert basic_default, "Basic default group not found"
+
+    basic_group = basic_default[0]
+    member_emails = {u.email for u in basic_group.users}
+    assert test_email in member_emails, (
+        f"Converted user '{test_email}' not found in Basic default group members: "
+        f"{member_emails}"
+    )

backend/tests/integration/tests/scim/test_scim_groups.py

@@ -21,8 +21,15 @@ import pytest
 import requests
 
 from onyx.auth.schemas import UserRole
+from tests.integration.common_utils.constants import ADMIN_USER_NAME
+from tests.integration.common_utils.constants import API_SERVER_URL
+from tests.integration.common_utils.constants import GENERAL_HEADERS
 from tests.integration.common_utils.managers.scim_client import ScimClient
 from tests.integration.common_utils.managers.scim_token import ScimTokenManager
+from tests.integration.common_utils.managers.user import build_email
+from tests.integration.common_utils.managers.user import DEFAULT_PASSWORD
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.test_models import DATestUser
 
 
 SCIM_GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group"
@@ -44,13 +51,6 @@ def scim_token(idp_style: str) -> str:
     per IdP-style run and reuse. Uses UserManager directly to avoid
     fixture-scope conflicts with the function-scoped admin_user fixture.
     """
-    from tests.integration.common_utils.constants import ADMIN_USER_NAME
-    from tests.integration.common_utils.constants import GENERAL_HEADERS
-    from tests.integration.common_utils.managers.user import build_email
-    from tests.integration.common_utils.managers.user import DEFAULT_PASSWORD
-    from tests.integration.common_utils.managers.user import UserManager
-    from tests.integration.common_utils.test_models import DATestUser
-
     try:
         admin = UserManager.create(name=ADMIN_USER_NAME)
     except Exception:
@@ -550,3 +550,96 @@ def test_patch_add_duplicate_member_is_idempotent(
     )
     assert resp.status_code == 200
     assert len(resp.json()["members"]) == 1  # still just one member
+
+
+def test_create_group_reserved_name_admin(scim_token: str) -> None:
+    """POST /Groups with reserved name 'Admin' returns 409."""
+    resp = _create_scim_group(scim_token, "Admin", external_id="ext-reserved-admin")
+    assert resp.status_code == 409
+    assert "reserved" in resp.json()["detail"].lower()
+
+
+def test_create_group_reserved_name_basic(scim_token: str) -> None:
+    """POST /Groups with reserved name 'Basic' returns 409."""
+    resp = _create_scim_group(scim_token, "Basic", external_id="ext-reserved-basic")
+    assert resp.status_code == 409
+    assert "reserved" in resp.json()["detail"].lower()
+
+
+def test_replace_group_cannot_rename_to_reserved(
+    scim_token: str, idp_style: str
+) -> None:
+    """PUT /Groups/{id} renaming a group to 'Admin' returns 409."""
+    created = _create_scim_group(
+        scim_token,
+        f"Rename To Reserved {idp_style}",
+        external_id=f"ext-rtr-{idp_style}",
+    ).json()
+
+    resp = ScimClient.put(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_group_resource(
+            display_name="Admin", external_id=f"ext-rtr-{idp_style}"
+        ),
+    )
+    assert resp.status_code == 409
+    assert "reserved" in resp.json()["detail"].lower()
+
+
+def test_patch_rename_to_reserved_name(scim_token: str, idp_style: str) -> None:
+    """PATCH /Groups/{id} renaming a group to 'Basic' returns 409."""
+    created = _create_scim_group(
+        scim_token,
+        f"Patch Rename Reserved {idp_style}",
+        external_id=f"ext-prr-{idp_style}",
+    ).json()
+
+    resp = ScimClient.patch(
+        f"/Groups/{created['id']}",
+        scim_token,
+        json=_make_patch_request(
+            [{"op": "replace", "path": "displayName", "value": "Basic"}],
+            idp_style,
+        ),
+    )
+    assert resp.status_code == 409
+    assert "reserved" in resp.json()["detail"].lower()
+
+
+def test_delete_reserved_group_rejected(scim_token: str) -> None:
+    """DELETE /Groups/{id} on a reserved group ('Admin') returns 409."""
+    # Look up the reserved 'Admin' group via SCIM filter
+    resp = ScimClient.get('/Groups?filter=displayName eq "Admin"', scim_token)
+    assert resp.status_code == 200
+    resources = resp.json()["Resources"]
+    assert len(resources) >= 1, "Expected reserved 'Admin' group to exist"
+    admin_group_id = resources[0]["id"]
+
+    resp = ScimClient.delete(f"/Groups/{admin_group_id}", scim_token)
+    assert resp.status_code == 409
+    assert "reserved" in resp.json()["detail"].lower()
+
+
+def test_scim_created_group_has_basic_permission(
+    scim_token: str, idp_style: str
+) -> None:
+    """POST /Groups assigns the 'basic' permission to the group itself."""
+    # Create a SCIM group (no members needed — we check the group's permissions)
+    resp = _create_scim_group(
+        scim_token,
+        f"Basic Perm Group {idp_style}",
+        external_id=f"ext-basic-perm-{idp_style}",
+    )
+    assert resp.status_code == 201
+    group_id = resp.json()["id"]
+
+    # Verify the group itself was granted the basic permission
+    admin_user = UserManager.create(name=f"admin_basic_perm_check_{idp_style}")
+    perms_resp = requests.get(
+        f"{API_SERVER_URL}/manage/admin/user-group/{group_id}/permissions",
+        headers=admin_user.headers,
+    )
+    perms_resp.raise_for_status()
+    perms = perms_resp.json()
+    assert "basic" in perms, f"SCIM group should have 'basic' permission, got: {perms}"

backend/tests/integration/tests/scim/test_scim_users.py

@@ -35,9 +35,16 @@ from onyx.auth.schemas import UserRole
 from onyx.configs.app_configs import REDIS_DB_NUMBER
 from onyx.configs.app_configs import REDIS_HOST
 from onyx.configs.app_configs import REDIS_PORT
+from onyx.db.enums import AccountType
 from onyx.server.settings.models import ApplicationStatus
+from tests.integration.common_utils.constants import ADMIN_USER_NAME
+from tests.integration.common_utils.constants import GENERAL_HEADERS
 from tests.integration.common_utils.managers.scim_client import ScimClient
 from tests.integration.common_utils.managers.scim_token import ScimTokenManager
+from tests.integration.common_utils.managers.user import build_email
+from tests.integration.common_utils.managers.user import DEFAULT_PASSWORD
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.test_models import DATestUser
 
 
 SCIM_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
@@ -211,6 +218,49 @@ def test_create_user(scim_token: str, idp_style: str) -> None:
         _assert_entra_emails(body, email)
 
 
+def test_create_user_default_group_and_account_type(
+    scim_token: str, idp_style: str
+) -> None:
+    """SCIM-provisioned users get Basic default group and STANDARD account_type."""
+    email = f"scim_defaults_{idp_style}@example.com"
+    ext_id = f"ext-defaults-{idp_style}"
+    resp = _create_scim_user(scim_token, email, ext_id, idp_style)
+    assert resp.status_code == 201
+    user_id = resp.json()["id"]
+
+    # --- Verify group assignment via SCIM GET ---
+    get_resp = ScimClient.get(f"/Users/{user_id}", scim_token)
+    assert get_resp.status_code == 200
+    groups = get_resp.json().get("groups", [])
+    group_names = {g["display"] for g in groups}
+    assert "Basic" in group_names, f"Expected 'Basic' in groups, got {group_names}"
+    assert "Admin" not in group_names, "SCIM user should not be in Admin group"
+
+    # --- Verify account_type via admin API ---
+    admin = UserManager.login_as_user(
+        DATestUser(
+            id="",
+            email=build_email(ADMIN_USER_NAME),
+            password=DEFAULT_PASSWORD,
+            headers=GENERAL_HEADERS,
+            role=UserRole.ADMIN,
+            is_active=True,
+        )
+    )
+    page = UserManager.get_user_page(
+        user_performing_action=admin,
+        search_query=email,
+    )
+    assert page.total_items >= 1
+    scim_user_snapshot = next((u for u in page.items if u.email == email), None)
+    assert (
+        scim_user_snapshot is not None
+    ), f"SCIM user {email} not found in user listing"
+    assert (
+        scim_user_snapshot.account_type == AccountType.STANDARD
+    ), f"Expected STANDARD, got {scim_user_snapshot.account_type}"
+
+
 def test_get_user(scim_token: str, idp_style: str) -> None:
     """GET /Users/{id} returns the user resource with all stored fields."""
     email = f"scim_get_{idp_style}@example.com"

backend/tests/integration/tests/usergroup/test_group_membership_updates_user_permissions.py

@@ -0,0 +1,118 @@
+import os
+
+import pytest
+
+from onyx.db.engine.sql_engine import get_session_with_current_tenant
+from onyx.db.enums import Permission
+from onyx.db.models import PermissionGrant
+from onyx.db.models import UserGroup as UserGroupModel
+from onyx.db.permissions import recompute_permissions_for_group__no_commit
+from onyx.db.permissions import recompute_user_permissions__no_commit
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.managers.user_group import UserGroupManager
+from tests.integration.common_utils.test_models import DATestUser
+
+
+@pytest.mark.skipif(
+    os.environ.get("ENABLE_PAID_ENTERPRISE_EDITION_FEATURES", "").lower() != "true",
+    reason="User group tests are enterprise only",
+)
+def test_user_gets_permissions_when_added_to_group(
+    reset: None,  # noqa: ARG001
+) -> None:
+    admin_user: DATestUser = UserManager.create(name="admin_for_perm_test")
+    basic_user: DATestUser = UserManager.create(name="basic_user_for_perm_test")
+
+    # basic_user starts with only "basic" from the default group
+    initial_permissions = UserManager.get_permissions(basic_user)
+    assert "basic" in initial_permissions
+    assert "add:agents" not in initial_permissions
+
+    # Create a new group and add basic_user
+    group = UserGroupManager.create(
+        name="perm-test-group",
+        user_ids=[admin_user.id, basic_user.id],
+        user_performing_action=admin_user,
+    )
+
+    # Grant a non-basic permission to the group and recompute
+    with get_session_with_current_tenant() as db_session:
+        db_group = db_session.get(UserGroupModel, group.id)
+        assert db_group is not None
+        db_session.add(
+            PermissionGrant(
+                group_id=db_group.id,
+                permission=Permission.ADD_AGENTS,
+                grant_source="SYSTEM",
+            )
+        )
+        db_session.flush()
+        recompute_user_permissions__no_commit(basic_user.id, db_session)
+        db_session.commit()
+
+    # Verify the user gained the new permission (expanded includes read:agents)
+    updated_permissions = UserManager.get_permissions(basic_user)
+    assert (
+        "add:agents" in updated_permissions
+    ), f"User should have 'add:agents' after group grant, got: {updated_permissions}"
+    assert (
+        "read:agents" in updated_permissions
+    ), f"User should have implied 'read:agents', got: {updated_permissions}"
+    assert "basic" in updated_permissions
+
+
+@pytest.mark.skipif(
+    os.environ.get("ENABLE_PAID_ENTERPRISE_EDITION_FEATURES", "").lower() != "true",
+    reason="User group tests are enterprise only",
+)
+def test_group_permission_change_propagates_to_all_members(
+    reset: None,  # noqa: ARG001
+) -> None:
+    admin_user: DATestUser = UserManager.create(name="admin_propagate")
+    user_a: DATestUser = UserManager.create(name="user_a_propagate")
+    user_b: DATestUser = UserManager.create(name="user_b_propagate")
+
+    group = UserGroupManager.create(
+        name="propagate-test-group",
+        user_ids=[admin_user.id, user_a.id, user_b.id],
+        user_performing_action=admin_user,
+    )
+
+    # Neither user should have add:agents yet
+    for u in (user_a, user_b):
+        assert "add:agents" not in UserManager.get_permissions(u)
+
+    # Grant add:agents to the group, then batch-recompute
+    with get_session_with_current_tenant() as db_session:
+        grant = PermissionGrant(
+            group_id=group.id,
+            permission=Permission.ADD_AGENTS,
+            grant_source="SYSTEM",
+        )
+        db_session.add(grant)
+        db_session.flush()
+        recompute_permissions_for_group__no_commit(group.id, db_session)
+        db_session.commit()
+
+    # Both users should now have the permission (plus implied read:agents)
+    for u in (user_a, user_b):
+        perms = UserManager.get_permissions(u)
+        assert "add:agents" in perms, f"{u.id} missing add:agents: {perms}"
+        assert "read:agents" in perms, f"{u.id} missing implied read:agents: {perms}"
+
+    # Soft-delete the grant and recompute — permission should be removed
+    with get_session_with_current_tenant() as db_session:
+        db_grant = (
+            db_session.query(PermissionGrant)
+            .filter_by(group_id=group.id, permission=Permission.ADD_AGENTS)
+            .first()
+        )
+        assert db_grant is not None
+        db_grant.is_deleted = True
+        db_session.flush()
+        recompute_permissions_for_group__no_commit(group.id, db_session)
+        db_session.commit()
+
+    for u in (user_a, user_b):
+        perms = UserManager.get_permissions(u)
+        assert "add:agents" not in perms, f"{u.id} still has add:agents: {perms}"

backend/tests/integration/tests/usergroup/test_new_group_gets_basic_permission.py

@@ -0,0 +1,30 @@
+import os
+
+import pytest
+
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.managers.user_group import UserGroupManager
+from tests.integration.common_utils.test_models import DATestUser
+
+
+@pytest.mark.skipif(
+    os.environ.get("ENABLE_PAID_ENTERPRISE_EDITION_FEATURES", "").lower() != "true",
+    reason="User group tests are enterprise only",
+)
+def test_new_group_gets_basic_permission(reset: None) -> None:  # noqa: ARG001
+    admin_user: DATestUser = UserManager.create(name="admin_for_basic_perm")
+
+    user_group = UserGroupManager.create(
+        name="basic-perm-test-group",
+        user_ids=[admin_user.id],
+        user_performing_action=admin_user,
+    )
+
+    permissions = UserGroupManager.get_permissions(
+        user_group=user_group,
+        user_performing_action=admin_user,
+    )
+
+    assert (
+        "basic" in permissions
+    ), f"New group should have 'basic' permission, got: {permissions}"

backend/tests/integration/tests/users/test_default_group_assignment.py

@@ -0,0 +1,78 @@
+"""Integration tests for default group assignment on user registration.
+
+Verifies that:
+- The first registered user is assigned to the Admin default group
+- Subsequent registered users are assigned to the Basic default group
+- account_type is set to STANDARD for email/password registrations
+"""
+
+from onyx.auth.schemas import UserRole
+from onyx.db.enums import AccountType
+from tests.integration.common_utils.managers.user import UserManager
+from tests.integration.common_utils.managers.user_group import UserGroupManager
+from tests.integration.common_utils.test_models import DATestUser
+
+
+def test_default_group_assignment_on_registration(reset: None) -> None:  # noqa: ARG001
+    # Register first user — should become admin
+    admin_user: DATestUser = UserManager.create(name="first_user")
+    assert admin_user.role == UserRole.ADMIN
+
+    # Register second user — should become basic
+    basic_user: DATestUser = UserManager.create(name="second_user")
+    assert basic_user.role == UserRole.BASIC
+
+    # Fetch all groups including default ones
+    all_groups = UserGroupManager.get_all(
+        user_performing_action=admin_user,
+        include_default=True,
+    )
+
+    # Find the default Admin and Basic groups
+    admin_group = next(
+        (g for g in all_groups if g.name == "Admin" and g.is_default), None
+    )
+    basic_group = next(
+        (g for g in all_groups if g.name == "Basic" and g.is_default), None
+    )
+    assert admin_group is not None, "Admin default group not found"
+    assert basic_group is not None, "Basic default group not found"
+
+    # Verify admin user is in Admin group and NOT in Basic group
+    admin_group_user_ids = {str(u.id) for u in admin_group.users}
+    basic_group_user_ids = {str(u.id) for u in basic_group.users}
+
+    assert (
+        admin_user.id in admin_group_user_ids
+    ), "First user should be in Admin default group"
+    assert (
+        admin_user.id not in basic_group_user_ids
+    ), "First user should NOT be in Basic default group"
+
+    # Verify basic user is in Basic group and NOT in Admin group
+    assert (
+        basic_user.id in basic_group_user_ids
+    ), "Second user should be in Basic default group"
+    assert (
+        basic_user.id not in admin_group_user_ids
+    ), "Second user should NOT be in Admin default group"
+
+    # Verify account_type is STANDARD for both users via user listing API
+    paginated_result = UserManager.get_user_page(
+        user_performing_action=admin_user,
+        page_num=0,
+        page_size=10,
+    )
+    users_by_id = {str(u.id): u for u in paginated_result.items}
+
+    admin_snapshot = users_by_id.get(admin_user.id)
+    basic_snapshot = users_by_id.get(basic_user.id)
+    assert admin_snapshot is not None, "Admin user not found in user listing"
+    assert basic_snapshot is not None, "Basic user not found in user listing"
+
+    assert (
+        admin_snapshot.account_type == AccountType.STANDARD
+    ), f"Admin user account_type should be STANDARD, got {admin_snapshot.account_type}"
+    assert (
+        basic_snapshot.account_type == AccountType.STANDARD
+    ), f"Basic user account_type should be STANDARD, got {basic_snapshot.account_type}"

backend/tests/unit/onyx/auth/test_permissions.py

@@ -0,0 +1,176 @@
+"""
+Unit tests for onyx.auth.permissions — pure logic and FastAPI dependency.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from onyx.auth.permissions import ALL_PERMISSIONS
+from onyx.auth.permissions import get_effective_permissions
+from onyx.auth.permissions import require_permission
+from onyx.auth.permissions import resolve_effective_permissions
+from onyx.db.enums import Permission
+from onyx.error_handling.error_codes import OnyxErrorCode
+from onyx.error_handling.exceptions import OnyxError
+
+
+# ---------------------------------------------------------------------------
+# resolve_effective_permissions
+# ---------------------------------------------------------------------------
+
+
+class TestResolveEffectivePermissions:
+    def test_empty_set(self) -> None:
+        assert resolve_effective_permissions(set()) == set()
+
+    def test_basic_no_implications(self) -> None:
+        result = resolve_effective_permissions({"basic"})
+        assert result == {"basic"}
+
+    def test_single_implication(self) -> None:
+        result = resolve_effective_permissions({"add:agents"})
+        assert result == {"add:agents", "read:agents"}
+
+    def test_manage_agents_implies_add_and_read(self) -> None:
+        """manage:agents directly maps to {add:agents, read:agents}."""
+        result = resolve_effective_permissions({"manage:agents"})
+        assert result == {"manage:agents", "add:agents", "read:agents"}
+
+    def test_manage_connectors_chain(self) -> None:
+        result = resolve_effective_permissions({"manage:connectors"})
+        assert result == {"manage:connectors", "add:connectors", "read:connectors"}
+
+    def test_manage_document_sets(self) -> None:
+        result = resolve_effective_permissions({"manage:document_sets"})
+        assert result == {
+            "manage:document_sets",
+            "read:document_sets",
+            "read:connectors",
+        }
+
+    def test_manage_user_groups_implies_all_reads(self) -> None:
+        result = resolve_effective_permissions({"manage:user_groups"})
+        assert result == {
+            "manage:user_groups",
+            "read:connectors",
+            "read:document_sets",
+            "read:agents",
+            "read:users",
+        }
+
+    def test_admin_override(self) -> None:
+        result = resolve_effective_permissions({"admin"})
+        assert result == set(ALL_PERMISSIONS)
+
+    def test_admin_with_others(self) -> None:
+        result = resolve_effective_permissions({"admin", "basic"})
+        assert result == set(ALL_PERMISSIONS)
+
+    def test_multi_group_union(self) -> None:
+        result = resolve_effective_permissions(
+            {"add:agents", "manage:connectors", "basic"}
+        )
+        assert result == {
+            "basic",
+            "add:agents",
+            "read:agents",
+            "manage:connectors",
+            "add:connectors",
+            "read:connectors",
+        }
+
+    def test_toggle_permission_no_implications(self) -> None:
+        result = resolve_effective_permissions({"read:agent_analytics"})
+        assert result == {"read:agent_analytics"}
+
+    def test_all_permissions_for_admin(self) -> None:
+        result = resolve_effective_permissions({"admin"})
+        assert len(result) == len(ALL_PERMISSIONS)
+
+
+# ---------------------------------------------------------------------------
+# get_effective_permissions (expands implied at read time)
+# ---------------------------------------------------------------------------
+
+
+class TestGetEffectivePermissions:
+    def test_expands_implied_permissions(self) -> None:
+        """Column stores only granted; get_effective_permissions expands implied."""
+        user = MagicMock()
+        user.effective_permissions = ["add:agents"]
+        result = get_effective_permissions(user)
+        assert result == {Permission.ADD_AGENTS, Permission.READ_AGENTS}
+
+    def test_admin_expands_to_all(self) -> None:
+        user = MagicMock()
+        user.effective_permissions = ["admin"]
+        result = get_effective_permissions(user)
+        assert result == set(Permission)
+
+    def test_basic_stays_basic(self) -> None:
+        user = MagicMock()
+        user.effective_permissions = ["basic"]
+        result = get_effective_permissions(user)
+        assert result == {Permission.BASIC_ACCESS}
+
+    def test_empty_column(self) -> None:
+        user = MagicMock()
+        user.effective_permissions = []
+        result = get_effective_permissions(user)
+        assert result == set()
+
+
+# ---------------------------------------------------------------------------
+# require_permission (FastAPI dependency)
+# ---------------------------------------------------------------------------
+
+
+class TestRequirePermission:
+    @pytest.mark.asyncio
+    async def test_admin_bypass(self) -> None:
+        """Admin stored in column should pass any permission check."""
+        user = MagicMock()
+        user.effective_permissions = ["admin"]
+
+        dep = require_permission(Permission.MANAGE_CONNECTORS)
+        result = await dep(user=user)
+        assert result is user
+
+    @pytest.mark.asyncio
+    async def test_has_required_permission(self) -> None:
+        user = MagicMock()
+        user.effective_permissions = ["manage:connectors"]
+
+        dep = require_permission(Permission.MANAGE_CONNECTORS)
+        result = await dep(user=user)
+        assert result is user
+
+    @pytest.mark.asyncio
+    async def test_implied_permission_passes(self) -> None:
+        """manage:connectors implies read:connectors at read time."""
+        user = MagicMock()
+        user.effective_permissions = ["manage:connectors"]
+
+        dep = require_permission(Permission.READ_CONNECTORS)
+        result = await dep(user=user)
+        assert result is user
+
+    @pytest.mark.asyncio
+    async def test_missing_permission_raises(self) -> None:
+        user = MagicMock()
+        user.effective_permissions = ["basic"]
+
+        dep = require_permission(Permission.MANAGE_CONNECTORS)
+        with pytest.raises(OnyxError) as exc_info:
+            await dep(user=user)
+        assert exc_info.value.error_code == OnyxErrorCode.INSUFFICIENT_PERMISSIONS
+
+    @pytest.mark.asyncio
+    async def test_empty_permissions_fails(self) -> None:
+        user = MagicMock()
+        user.effective_permissions = []
+
+        dep = require_permission(Permission.BASIC_ACCESS)
+        with pytest.raises(OnyxError):
+            await dep(user=user)

backend/tests/unit/onyx/auth/test_user_create_schema.py

@@ -0,0 +1,29 @@
+"""
+Unit tests for UserCreate schema dict methods.
+
+Verifies that account_type is always included in create_update_dict
+and create_update_dict_superuser.
+"""
+
+from onyx.auth.schemas import UserCreate
+from onyx.db.enums import AccountType
+
+
+def test_create_update_dict_includes_default_account_type() -> None:
+    uc = UserCreate(email="a@b.com", password="secret123")
+    d = uc.create_update_dict()
+    assert d["account_type"] == AccountType.STANDARD
+
+
+def test_create_update_dict_includes_explicit_account_type() -> None:
+    uc = UserCreate(
+        email="a@b.com", password="secret123", account_type=AccountType.SERVICE_ACCOUNT
+    )
+    d = uc.create_update_dict()
+    assert d["account_type"] == AccountType.STANDARD
+
+
+def test_create_update_dict_superuser_includes_account_type() -> None:
+    uc = UserCreate(email="a@b.com", password="secret123")
+    d = uc.create_update_dict_superuser()
+    assert d["account_type"] == AccountType.STANDARD

backend/tests/unit/onyx/chat/test_context_files.py

@@ -300,66 +300,6 @@ class TestExtractContextFiles:
         assert result.file_texts == []
         assert result.total_token_count == 50
 
-    @patch("onyx.chat.process_message.load_in_memory_chat_files")
-    def test_tool_metadata_file_id_matches_chat_history_file_id(
-        self, mock_load: MagicMock
-    ) -> None:
-        """The file_id in tool metadata (from extract_context_files) and the
-        file_id in chat history messages (from build_file_context) must
-        agree, otherwise the LLM sees different IDs for the same file across
-        turns.
-
-        In production, UserFile.id (UUID PK) differs from UserFile.file_id
-        (file-store path). Both pathways should produce the same file_id
-        (UserFile.id) for FileReaderTool."""
-        from onyx.chat.chat_utils import build_file_context
-
-        user_file_uuid = uuid4()
-        file_store_path = f"user_files/{user_file_uuid}/data.csv"
-
-        uf = UserFile(
-            id=user_file_uuid,
-            file_id=file_store_path,
-            name="data.csv",
-            token_count=100,
-            file_type="text/csv",
-        )
-
-        in_memory = InMemoryChatFile(
-            file_id=file_store_path,
-            content=b"col1,col2\na,b",
-            file_type=ChatFileType.TABULAR,
-            filename="data.csv",
-        )
-
-        mock_load.return_value = [in_memory]
-
-        # Pathway 1: extract_context_files (project/persona context)
-        result = extract_context_files(
-            user_files=[uf],
-            llm_max_context_window=10000,
-            reserved_token_count=0,
-            db_session=MagicMock(),
-        )
-        assert len(result.file_metadata_for_tool) == 1
-        tool_metadata_file_id = result.file_metadata_for_tool[0].file_id
-
-        # Pathway 2: build_file_context (chat history path)
-        # In convert_chat_history, tool_file_id comes from
-        # file_descriptor["user_file_id"], which is str(UserFile.id)
-        ctx = build_file_context(
-            tool_file_id=str(user_file_uuid),
-            filename="data.csv",
-            file_type=ChatFileType.TABULAR,
-        )
-        chat_history_file_id = ctx.tool_metadata.file_id
-
-        # Both pathways must produce the same ID for the LLM
-        assert tool_metadata_file_id == chat_history_file_id, (
-            f"File ID mismatch: extract_context_files uses '{tool_metadata_file_id}' "
-            f"but build_file_context uses '{chat_history_file_id}'."
-        )
-
     @patch("onyx.chat.process_message.DISABLE_VECTOR_DB", True)
     def test_overflow_with_vector_db_disabled_provides_tool_metadata(self) -> None:
         """When vector DB is disabled, overflow produces FileToolMetadata."""
@@ -376,128 +316,6 @@ class TestExtractContextFiles:
         assert len(result.file_metadata_for_tool) == 1
         assert result.file_metadata_for_tool[0].filename == "bigfile.txt"
 
-    @patch("onyx.chat.process_message.load_in_memory_chat_files")
-    def test_metadata_only_files_not_counted_in_aggregate_tokens(
-        self, mock_load: MagicMock
-    ) -> None:
-        """Metadata-only files (TABULAR) should not count toward the token budget."""
-        text_file_id = str(uuid4())
-        text_uf = _make_user_file(token_count=100, file_id=text_file_id)
-        # TABULAR file with large token count — should be excluded from aggregate
-        tabular_uf = _make_user_file(
-            token_count=50000, name="huge.xlsx", file_id=str(uuid4())
-        )
-        tabular_uf.file_type = (
-            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-        )
-
-        mock_load.return_value = [
-            _make_in_memory_file(file_id=text_file_id, content="text content"),
-            InMemoryChatFile(
-                file_id=str(tabular_uf.id),
-                content=b"binary xlsx",
-                file_type=ChatFileType.TABULAR,
-                filename="huge.xlsx",
-            ),
-        ]
-
-        result = extract_context_files(
-            user_files=[text_uf, tabular_uf],
-            llm_max_context_window=10000,
-            reserved_token_count=0,
-            db_session=MagicMock(),
-        )
-
-        # Text file fits (100 < 6000), so files should be loaded
-        assert result.file_texts == ["text content"]
-        # TABULAR file should appear as tool metadata, not in file_texts
-        assert len(result.file_metadata_for_tool) == 1
-        assert result.file_metadata_for_tool[0].filename == "huge.xlsx"
-
-    @patch("onyx.chat.process_message.load_in_memory_chat_files")
-    def test_metadata_only_files_loaded_as_tool_metadata(
-        self, mock_load: MagicMock
-    ) -> None:
-        """When files fit, metadata-only files appear in file_metadata_for_tool."""
-        text_file_id = str(uuid4())
-        tabular_file_id = str(uuid4())
-        text_uf = _make_user_file(token_count=100, file_id=text_file_id)
-        tabular_uf = _make_user_file(
-            token_count=500, name="data.csv", file_id=tabular_file_id
-        )
-        tabular_uf.file_type = "text/csv"
-
-        mock_load.return_value = [
-            _make_in_memory_file(file_id=text_file_id, content="hello"),
-            InMemoryChatFile(
-                file_id=tabular_file_id,
-                content=b"col1,col2\na,b",
-                file_type=ChatFileType.TABULAR,
-                filename="data.csv",
-            ),
-        ]
-
-        result = extract_context_files(
-            user_files=[text_uf, tabular_uf],
-            llm_max_context_window=10000,
-            reserved_token_count=0,
-            db_session=MagicMock(),
-        )
-
-        assert result.file_texts == ["hello"]
-        assert len(result.file_metadata_for_tool) == 1
-        assert result.file_metadata_for_tool[0].filename == "data.csv"
-        # TABULAR should not appear in file_metadata (that's for citation)
-        assert all(m.filename != "data.csv" for m in result.file_metadata)
-
-    def test_overflow_with_vector_db_preserves_metadata_only_tool_metadata(
-        self,
-    ) -> None:
-        """When text files overflow with vector DB enabled, metadata-only files
-        should still be exposed via file_metadata_for_tool since they aren't
-        in the vector DB and would otherwise be inaccessible."""
-        text_uf = _make_user_file(token_count=7000, name="bigfile.txt")
-        tabular_uf = _make_user_file(token_count=500, name="data.xlsx")
-        tabular_uf.file_type = (
-            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-        )
-
-        result = extract_context_files(
-            user_files=[text_uf, tabular_uf],
-            llm_max_context_window=10000,
-            reserved_token_count=0,
-            db_session=MagicMock(),
-        )
-
-        # Text files overflow → search filter enabled
-        assert result.use_as_search_filter is True
-        assert result.file_texts == []
-        # TABULAR file should still be in tool metadata
-        assert len(result.file_metadata_for_tool) == 1
-        assert result.file_metadata_for_tool[0].filename == "data.xlsx"
-
-    @patch("onyx.chat.process_message.DISABLE_VECTOR_DB", True)
-    def test_overflow_no_vector_db_includes_all_files_in_tool_metadata(self) -> None:
-        """When vector DB is disabled and files overflow, all files
-        (both text and metadata-only) appear in file_metadata_for_tool."""
-        text_uf = _make_user_file(token_count=7000, name="bigfile.txt")
-        tabular_uf = _make_user_file(token_count=500, name="data.xlsx")
-        tabular_uf.file_type = (
-            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-        )
-
-        result = extract_context_files(
-            user_files=[text_uf, tabular_uf],
-            llm_max_context_window=10000,
-            reserved_token_count=0,
-            db_session=MagicMock(),
-        )
-
-        assert result.use_as_search_filter is False
-        assert len(result.file_metadata_for_tool) == 2
-        filenames = {m.filename for m in result.file_metadata_for_tool}
-        assert filenames == {"bigfile.txt", "data.xlsx"}
-
 
 # ===========================================================================
 # Search filter + search_usage determination

backend/tests/unit/onyx/chat/test_llm_loop.py

@@ -644,92 +644,6 @@ class TestConstructMessageHistory:
         assert "Project file 0 content" in project_message.message
         assert "Project file 1 content" in project_message.message
 
-    def test_file_metadata_for_tool_produces_message(self) -> None:
-        """When context_files has file_metadata_for_tool, a metadata listing
-        message should be injected into the history."""
-        system_prompt = create_message("System", MessageType.SYSTEM, 10)
-        user_msg = create_message("Analyze the spreadsheet", MessageType.USER, 5)
-
-        context_files = ExtractedContextFiles(
-            file_texts=[],
-            image_files=[],
-            use_as_search_filter=False,
-            total_token_count=0,
-            file_metadata=[],
-            uncapped_token_count=0,
-            file_metadata_for_tool=[
-                FileToolMetadata(
-                    file_id="xlsx-1",
-                    filename="report.xlsx",
-                    approx_char_count=100000,
-                ),
-            ],
-        )
-
-        result = construct_message_history(
-            system_prompt=system_prompt,
-            custom_agent_prompt=None,
-            simple_chat_history=[user_msg],
-            reminder_message=None,
-            context_files=context_files,
-            available_tokens=1000,
-            token_counter=_simple_token_counter,
-        )
-
-        # Should have: system, tool_metadata_message, user
-        assert len(result) == 3
-        metadata_msg = result[1]
-        assert metadata_msg.message_type == MessageType.USER
-        assert "report.xlsx" in metadata_msg.message
-        assert "xlsx-1" in metadata_msg.message
-
-    def test_metadata_only_and_text_files_both_present(self) -> None:
-        """When both text content and tool metadata are present, both messages
-        should appear in the history."""
-        system_prompt = create_message("System", MessageType.SYSTEM, 10)
-        user_msg = create_message("Summarize everything", MessageType.USER, 5)
-
-        context_files = ExtractedContextFiles(
-            file_texts=["Text file content here"],
-            image_files=[],
-            use_as_search_filter=False,
-            total_token_count=100,
-            file_metadata=[
-                ContextFileMetadata(
-                    file_id="txt-1",
-                    filename="notes.txt",
-                    file_content="Text file content here",
-                ),
-            ],
-            uncapped_token_count=100,
-            file_metadata_for_tool=[
-                FileToolMetadata(
-                    file_id="xlsx-1",
-                    filename="data.xlsx",
-                    approx_char_count=50000,
-                ),
-            ],
-        )
-
-        result = construct_message_history(
-            system_prompt=system_prompt,
-            custom_agent_prompt=None,
-            simple_chat_history=[user_msg],
-            reminder_message=None,
-            context_files=context_files,
-            available_tokens=2000,
-            token_counter=_simple_token_counter,
-        )
-
-        # Should have: system, context_files_message, tool_metadata_message, user
-        assert len(result) == 4
-        # Context files message (text content)
-        assert "documents" in result[1].message
-        assert "Text file content here" in result[1].message
-        # Tool metadata message
-        assert "data.xlsx" in result[2].message
-        assert result[3] == user_msg
-
 
 def _simple_token_counter(text: str) -> int:
     """Approximate token counter for tests (~4 chars per token)."""

backend/tests/unit/onyx/db/test_assign_default_groups.py

@@ -0,0 +1,176 @@
+"""
+Unit tests for assign_user_to_default_groups__no_commit in onyx.db.users.
+
+Covers:
+1. Standard/service-account users get assigned to the correct default group
+2. BOT, EXT_PERM_USER, ANONYMOUS account types are skipped
+3. Missing default group raises RuntimeError
+4. Already-in-group is a no-op
+5. IntegrityError race condition is handled gracefully
+6. The function never commits the session
+"""
+
+from unittest.mock import MagicMock
+from uuid import uuid4
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+
+from onyx.db.enums import AccountType
+from onyx.db.models import User__UserGroup
+from onyx.db.models import UserGroup
+from onyx.db.users import assign_user_to_default_groups__no_commit
+
+
+def _mock_user(
+    account_type: AccountType = AccountType.STANDARD,
+    email: str = "test@example.com",
+) -> MagicMock:
+    user = MagicMock()
+    user.id = uuid4()
+    user.email = email
+    user.account_type = account_type
+    return user
+
+
+def _mock_group(name: str = "Basic", group_id: int = 1) -> MagicMock:
+    group = MagicMock()
+    group.id = group_id
+    group.name = name
+    group.is_default = True
+    return group
+
+
+def _make_query_chain(first_return: object = None) -> MagicMock:
+    """Returns a mock that supports .filter(...).filter(...).first() chaining."""
+    chain = MagicMock()
+    chain.filter.return_value = chain
+    chain.first.return_value = first_return
+    return chain
+
+
+def _setup_db_session(
+    group_result: object = None,
+    membership_result: object = None,
+) -> MagicMock:
+    """Create a db_session mock that routes query(UserGroup) and query(User__UserGroup)."""
+    db_session = MagicMock()
+
+    group_chain = _make_query_chain(group_result)
+    membership_chain = _make_query_chain(membership_result)
+
+    def query_side_effect(model: type) -> MagicMock:
+        if model is UserGroup:
+            return group_chain
+        if model is User__UserGroup:
+            return membership_chain
+        return MagicMock()
+
+    db_session.query.side_effect = query_side_effect
+    return db_session
+
+
+def test_standard_user_assigned_to_basic_group() -> None:
+    group = _mock_group("Basic")
+    db_session = _setup_db_session(group_result=group, membership_result=None)
+    savepoint = MagicMock()
+    db_session.begin_nested.return_value = savepoint
+    user = _mock_user(AccountType.STANDARD)
+
+    assign_user_to_default_groups__no_commit(db_session, user, is_admin=False)
+
+    db_session.add.assert_called_once()
+    added = db_session.add.call_args[0][0]
+    assert isinstance(added, User__UserGroup)
+    assert added.user_id == user.id
+    assert added.user_group_id == group.id
+    db_session.flush.assert_called_once()
+
+
+def test_admin_user_assigned_to_admin_group() -> None:
+    group = _mock_group("Admin", group_id=2)
+    db_session = _setup_db_session(group_result=group, membership_result=None)
+    savepoint = MagicMock()
+    db_session.begin_nested.return_value = savepoint
+    user = _mock_user(AccountType.STANDARD)
+
+    assign_user_to_default_groups__no_commit(db_session, user, is_admin=True)
+
+    db_session.add.assert_called_once()
+    added = db_session.add.call_args[0][0]
+    assert isinstance(added, User__UserGroup)
+    assert added.user_group_id == group.id
+
+
+@pytest.mark.parametrize(
+    "account_type",
+    [AccountType.BOT, AccountType.EXT_PERM_USER, AccountType.ANONYMOUS],
+)
+def test_excluded_account_types_skipped(account_type: AccountType) -> None:
+    db_session = MagicMock()
+    user = _mock_user(account_type)
+
+    assign_user_to_default_groups__no_commit(db_session, user)
+
+    db_session.query.assert_not_called()
+    db_session.add.assert_not_called()
+
+
+def test_service_account_not_skipped() -> None:
+    group = _mock_group("Basic")
+    db_session = _setup_db_session(group_result=group, membership_result=None)
+    savepoint = MagicMock()
+    db_session.begin_nested.return_value = savepoint
+    user = _mock_user(AccountType.SERVICE_ACCOUNT)
+
+    assign_user_to_default_groups__no_commit(db_session, user, is_admin=False)
+
+    db_session.add.assert_called_once()
+
+
+def test_missing_default_group_raises_error() -> None:
+    db_session = _setup_db_session(group_result=None)
+    user = _mock_user()
+
+    with pytest.raises(RuntimeError, match="Default group .* not found"):
+        assign_user_to_default_groups__no_commit(db_session, user)
+
+
+def test_already_in_group_is_noop() -> None:
+    group = _mock_group("Basic")
+    existing_membership = MagicMock()
+    db_session = _setup_db_session(
+        group_result=group, membership_result=existing_membership
+    )
+    user = _mock_user()
+
+    assign_user_to_default_groups__no_commit(db_session, user)
+
+    db_session.add.assert_not_called()
+    db_session.begin_nested.assert_not_called()
+
+
+def test_integrity_error_race_condition_handled() -> None:
+    group = _mock_group("Basic")
+    db_session = _setup_db_session(group_result=group, membership_result=None)
+    savepoint = MagicMock()
+    db_session.begin_nested.return_value = savepoint
+    db_session.flush.side_effect = IntegrityError(None, None, Exception("duplicate"))
+    user = _mock_user()
+
+    # Should not raise
+    assign_user_to_default_groups__no_commit(db_session, user)
+
+    savepoint.rollback.assert_called_once()
+
+
+def test_no_commit_called_on_successful_assignment() -> None:
+    group = _mock_group("Basic")
+    db_session = _setup_db_session(group_result=group, membership_result=None)
+    savepoint = MagicMock()
+    db_session.begin_nested.return_value = savepoint
+    user = _mock_user()
+
+    assign_user_to_default_groups__no_commit(db_session, user)
+
+    db_session.commit.assert_not_called()

backend/tests/unit/onyx/server/scim/conftest.py

@@ -113,6 +113,7 @@ def make_db_group(**kwargs: Any) -> MagicMock:
     group.name = kwargs.get("name", "Engineering")
     group.is_up_for_deletion = kwargs.get("is_up_for_deletion", False)
     group.is_up_to_date = kwargs.get("is_up_to_date", True)
+    group.is_default = kwargs.get("is_default", False)
     return group
 
 

backend/tests/unit/onyx/server/test_full_user_snapshot.py

@@ -3,6 +3,7 @@ from unittest.mock import MagicMock
 from uuid import uuid4
 
 from onyx.auth.schemas import UserRole
+from onyx.db.enums import AccountType
 from onyx.server.models import FullUserSnapshot
 from onyx.server.models import UserGroupInfo
 
@@ -25,6 +26,7 @@ def _mock_user(
     user.updated_at = updated_at or datetime.datetime(
         2025, 6, 15, tzinfo=datetime.timezone.utc
     )
+    user.account_type = AccountType.STANDARD
     return user
 
 

contributing_guides/best_practices.md

@@ -0,0 +1,184 @@
+# Engineering Principles, Style, and Correctness Guide
+
+## Principles and collaboration
+
+- **Use 1-way vs 2-way doors.** For 2-way doors, move faster and iterate. For 1-way doors, be more deliberate.
+- **Consistency > being “right.”** Prefer consistent patterns across the codebase. If something is truly bad, fix it everywhere.
+- **Fix what you touch (selectively).**
+  - Don’t feel obligated to fix every best-practice issue you notice.
+  - Don’t introduce new bad practices.
+  - If your change touches code that violates best practices, fix it as part of the change.
+- **Don’t tack features on.** When adding functionality, restructure logically as needed to avoid muddying interfaces and accumulating tech debt.
+
+---
+
+## Style and maintainability
+
+### Comments and readability
+Add clear comments:
+- At logical boundaries (e.g., interfaces) so the reader doesn’t need to dig 10 layers deeper.
+- Wherever assumptions are made or something non-obvious/unexpected is done.
+- For complicated flows/functions.
+- Wherever it saves time (e.g., nontrivial regex patterns).
+
+### Errors and exceptions
+- **Fail loudly** rather than silently skipping work.
+  - Example: raise and let exceptions propagate instead of silently dropping a document.
+- **Don’t overuse `try/except`.**
+  - Put `try/except` at the correct logical level.
+  - Do not mask exceptions unless it is clearly appropriate.
+
+### Typing
+- Everything should be **as strictly typed as possible**.
+- Use `cast` for annoying/loose-typed interfaces (e.g., results of `run_functions_tuples_in_parallel`).
+  - Only `cast` when the type checker sees `Any` or types are too loose.
+- Prefer types that are easy to read.
+  - Avoid dense types like `dict[tuple[str, str], list[list[float]]]`.
+  - Prefer domain models, e.g.:
+    - `EmbeddingModel(provider_name, model_name)` as a Pydantic model
+    - `dict[EmbeddingModel, list[EmbeddingVector]]`
+
+### State, objects, and boundaries
+- Keep **clear logical boundaries** for state containers and objects.
+- A **config** object should never contain things like a `db_session`.
+- Avoid state containers that are:
+  - overly nested, or
+  - huge + flat (use judgment).
+- Prefer **composition and functional style** over inheritance/OOP.
+- Prefer **no mutation** unless there’s a strong reason.
+- State objects should be **intentional and explicit**, ideally nonmutating.
+- Use interfaces/objects to create clear separation of responsibility.
+- Prefer simplicity when there’s no clear gain
+  - Avoid overcomplicated mechanisms like semaphores.
+  - Prefer **hash maps (dicts)** over tree structures unless there’s a strong reason.
+
+### Naming
+- Name variables carefully and intentionally.
+- Prefer long, explicit names when undecided.
+- Avoid single-character variables except for small, self-contained utilities (or not at all).
+- Keep the same object/name consistent through the call stack and within functions when reasonable.
+  - Good: `for token in tokens:`
+  - Bad: `for msg in tokens:` (if iterating tokens)
+- Function names should bias toward **long + descriptive** for codebase search.
+  - IntelliSense can miss call sites; search works best with unique names.
+  - “Fetch versioned implementation” is an example of why this matters.
+
+### Correctness by construction
+- Prefer self-contained correctness.
+  - Don’t rely on callers to “use it right” if you can make misuse hard.
+- Avoid redundancies:
+  - If a function takes an arg, it shouldn’t also take a state object that contains that same arg.
+- No dead code (unless there’s a very good reason).
+- No commented-out code in main or feature branches (unless there’s a very good reason).
+- No duplicate logic:
+  - Don’t copy/paste into branches when shared logic can live above the conditional.
+  - If you’re afraid to touch the original, you don’t understand it well enough.
+  - LLMs often create subtle duplicate logic—review carefully and remove it.
+  - Avoid “nearly identical” objects that confuse when to use which.
+- Avoid extremely long functions with chained logic:
+  - Encapsulate steps into helpers for readability, even if not reused.
+  - “Pythonic” multi-step expressions are OK in moderation; don’t trade clarity for cleverness.
+
+---
+
+## Performance and correctness
+
+- Avoid holding resources for extended periods:
+  - DB sessions
+  - locks/semaphores
+- Validate objects:
+  - on creation, and
+  - right before use.
+- Connector code (data → Onyx documents):
+  - Any in-memory structure that can grow without bound based on input must be periodically size-checked.
+  - If a connector is OOMing (often shows up as “missing celery tasks”), this is a top thing to check retroactively.
+- Async and event loops:
+  - Never introduce new async/event loop Python code, and try to make existing
+    async code synchronous when possible if it makes sense.
+    - Writing async code without 100% understanding the code and having a
+      concrete reason to do so is likely to introduce bugs and not add any
+      meaningful performance gains.
+
+---
+
+## Repository conventions: where code lives
+
+- Pydantic + data models: `models.py` files.
+- DB interface functions (excluding lazy loading): `db/` directory.
+- LLM prompts: `prompts/` directory, roughly mirroring the code layout that uses them.
+- API routes: `server/` directory.
+
+---
+
+## Pydantic and modeling rules
+
+- Prefer **Pydantic** over dataclasses.
+- If absolutely required, use `allow_arbitrary_types`.
+
+---
+
+## Data conventions
+
+- Prefer explicit `None` over sentinel empty strings (usually; depends on intent).
+- Prefer explicit identifiers:
+  - Use string enums instead of integer codes.
+- Avoid magic numbers (co-location is good when necessary). **Always avoid magic strings.**
+
+---
+
+## Logging
+
+- Log messages where they are created.
+- Don’t propagate log messages around just to log them elsewhere.
+
+---
+
+## Encapsulation
+
+- Don’t use private attributes/methods/properties from other classes/modules.
+- “Private” is private—respect that boundary.
+
+---
+
+## SQLAlchemy guidance
+
+- Lazy loading is often bad at scale, especially across multiple list relationships.
+- Be careful when accessing SQLAlchemy object attributes:
+  - It can help avoid redundant DB queries,
+  - but it can also fail if accessed outside an active session,
+  - and lazy loading can add hidden DB dependencies to otherwise “simple” functions.
+- Reference: https://www.reddit.com/r/SQLAlchemy/comments/138f248/joinedload_vs_selectinload/
+
+---
+
+## Trunk-based development and feature flags
+
+- **PRs should contain no more than 500 lines of real change.**
+- **Merge to main frequently.** Avoid long-lived feature branches—they create merge conflicts and integration pain.
+- **Use feature flags for incremental rollout.**
+  - Large features should be merged in small, shippable increments behind a flag.
+  - This allows continuous integration without exposing incomplete functionality.
+- **Keep flags short-lived.** Once a feature is fully rolled out, remove the flag and dead code paths promptly.
+- **Flag at the right level.** Prefer flagging at API/UI entry points rather than deep in business logic.
+- **Test both flag states.** Ensure the codebase works correctly with the flag on and off.
+
+---
+
+## Misc
+
+- Any TODOs you add in the code must be accompanied by either the name/username
+  of the owner of that TODO, or an issue number for an issue referencing that
+  piece of work.
+- Avoid module-level logic that runs on import, which leads to import-time side
+  effects. Essentially every piece of meaningful logic should exist within some
+  function that has to be explicitly invoked. Acceptable exceptions to this may
+  include loading environment variables or setting up loggers.
+  - If you find yourself needing something like this, you may want that logic to
+    exist in a file dedicated for manual execution (contains `if __name__ ==
+    "__main__":`) which should not be imported by anything else.
+- Related to the above, do not conflate Python scripts you intend to run from
+  the command line (contains `if __name__ == "__main__":`) with modules you
+  intend to import from elsewhere. If for some unlikely reason they have to be
+  the same file, any logic specific to executing the file (including imports)
+  should be contained in the `if __name__ == "__main__":` block.
+  - Generally these executable files exist in `backend/scripts/`.

contributing_guides/contributing_macos.md

@@ -0,0 +1,36 @@
+## Some additional notes for Mac Users
+
+The base instructions to set up the development environment are located in [CONTRIBUTING.md](https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md).
+
+### Setting up Python
+
+Ensure [Homebrew](https://brew.sh/) is already set up.
+
+Then install python 3.11.
+
+```bash
+brew install python@3.11
+```
+
+Add python 3.11 to your path: add the following line to ~/.zshrc
+
+```
+export PATH="$(brew --prefix)/opt/python@3.11/libexec/bin:$PATH"
+```
+
+> **Note:**
+> You will need to open a new terminal for the path change above to take effect.
+
+### Setting up Docker
+
+On macOS, you will need to install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and
+ensure it is running before continuing with the docker commands.
+
+### Formatting and Linting
+
+MacOS will likely require you to remove some quarantine attributes on some of the hooks for them to execute properly.
+After installing pre-commit, run the following command:
+
+```bash
+sudo xattr -r -d com.apple.quarantine ~/.cache/pre-commit
+```

contributing_guides/contributing_vscode.md

@@ -0,0 +1,30 @@
+# VSCode Debugging Setup
+
+This guide explains how to set up and use VSCode's debugging capabilities with this project.
+
+## Initial Setup
+
+1. **Environment Setup**:
+   - Copy `.vscode/env_template.txt` to `.vscode/.env`
+   - Fill in the necessary environment variables in `.vscode/.env`
+
+## Using the Debugger
+
+Before starting, make sure the Docker Daemon is running.
+
+1. Open the Debug view in VSCode (Cmd+Shift+D on macOS)
+2. From the dropdown at the top, select "Clear and Restart External Volumes and Containers" and press the green play button
+3. From the dropdown at the top, select "Run All Onyx Services" and press the green play button
+4. Now, you can navigate to onyx in your browser (default is http://localhost:3000) and start using the app
+5. You can set breakpoints by clicking to the left of line numbers to help debug while the app is running
+6. Use the debug toolbar to step through code, inspect variables, etc.
+
+Note: Clear and Restart External Volumes and Containers will reset your postgres and Vespa (relational-db and index).
+Only run this if you are okay with wiping your data.
+
+## Features
+
+- Hot reload is enabled for the web server and API servers
+- Python debugging is configured with debugpy
+- Environment variables are loaded from `.vscode/.env`
+- Console output is organized in the integrated terminal with labeled tabs

contributing_guides/contribution_process.md

@@ -0,0 +1,38 @@
+# Contribution Process
+
+## 1. Get the feature or enhancement approved
+Create a GitHub issue and see if there are upvotes. If you feel the feature is sufficiently value additive and you would like
+approval to contribute it to the repo, tag [Yuhong](https://github.com/yuhongsun96) to review.
+
+If you do not get a response within a week, feel free to email yuhong@onyx.app and include the issue in the message.
+
+Not all small features and enhancements will be accepted as there is a balance between feature richness and bloat.
+We strive to provide the best user experience possible so we have to be intentional about what we include in the app.
+
+
+## 2. Get the design approved
+The Onyx team will either provide a design doc and PRD for the feature or request one from you, the contributor.
+
+The scope and detail of the design will depend on the individual feature.
+
+
+# 3. IP attribution for EE contributions
+If you are contributing features to Onyx Enterprise Edition, you are required to sign the IP Assignment Agreement in the
+contributing_guides directory.
+
+
+## 4. Review and testing
+Your features must pass all tests and all comments must be addressed prior to merging.
+
+
+# Implicit agreements
+If we approve an issue, we are promising you the following:
+- Your work will receive timely attention and we will put aside other high priority items to ensure you are not blocked.
+- You will receive necessary coaching on eng quality, system design, etc. to ensure the feature is completed well.
+- The Onyx team will pull resources and bandwidth from design, PM, and engineering to ensure that you have all the
+resources to build the feature to the quality required for merging.
+
+Because this is a large investment from our team, we ask that you:
+- Thoroughly read all the requirements of the design docs, engineering best practices, and try to minimize overhead for
+the Onyx team.
+- Complete the feature in a timely manner to reduce context switching and an ongoing resource pull from the Onyx team.

contributing_guides/dev_setup.md

@@ -0,0 +1,205 @@
+## Get Started 🚀
+
+Onyx being a fully functional app, relies on some external software, specifically:
+
+- [Postgres](https://www.postgresql.org/) (Relational DB)
+- [Vespa](https://vespa.ai/) (Vector DB/Search Engine)
+- [Redis](https://redis.io/) (Cache)
+- [MinIO](https://min.io/) (File Store)
+- [Nginx](https://nginx.org/) (Not needed for development flows generally)
+
+> **Note:**
+> This guide provides instructions to build and run Onyx locally from source with Docker containers providing the above external software. We believe this combination is easier for
+> development purposes. If you prefer to use pre-built container images, we provide instructions on running the full Onyx stack within Docker below.
+
+### Local Set Up
+
+Be sure to use Python version 3.11. For instructions on installing Python 3.11 on macOS, refer to the [contributing_macos.md](./contributing_macos.md) readme.
+
+If using a lower version, modifications will have to be made to the code.
+If using a higher version, sometimes some libraries will not be available (i.e. we had problems with Tensorflow in the past with higher versions of python).
+
+#### Backend: Python requirements
+
+Currently, we use [uv](https://docs.astral.sh/uv/) and recommend creating a [virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment).
+
+For convenience here's a command for it:
+
+```bash
+uv venv .venv --python 3.11
+source .venv/bin/activate
+```
+
+_For Windows, activate the virtual environment using Command Prompt:_
+
+```bash
+.venv\Scripts\activate
+```
+
+If using PowerShell, the command slightly differs:
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+Install the required python dependencies:
+
+```bash
+uv sync --all-extras
+```
+
+Install Playwright for Python (headless browser required by the Web Connector):
+
+```bash
+uv run playwright install
+```
+
+#### Frontend: Node dependencies
+
+Onyx uses Node v22.20.0. We highly recommend you use [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm)
+to manage your Node installations. Once installed, you can run
+
+```bash
+nvm install 22 && nvm use 22
+node -v # verify your active version
+```
+
+Navigate to `onyx/web` and run:
+
+```bash
+npm i
+```
+
+## Formatting and Linting
+
+### Backend
+
+For the backend, you'll need to setup pre-commit hooks (black / reorder-python-imports).
+
+Then run:
+
+```bash
+uv run pre-commit install
+```
+
+Additionally, we use `mypy` for static type checking.
+Onyx is fully type-annotated, and we want to keep it that way!
+To run the mypy checks manually, run `uv run mypy .` from the `onyx/backend` directory.
+
+### Web
+
+We use `prettier` for formatting. The desired version will be installed via a `npm i` from the `onyx/web` directory.
+To run the formatter, use `npx prettier --write .` from the `onyx/web` directory.
+
+Pre-commit will also run prettier automatically on files you've recently touched. If re-formatted, your commit will fail.
+Re-stage your changes and commit again.
+
+# Running the application for development
+
+## Developing using VSCode Debugger (recommended)
+
+**We highly recommend using VSCode debugger for development.**
+See [contributing_vscode.md](./contributing_vscode.md) for more details.
+
+Otherwise, you can follow the instructions below to run the application for development.
+
+## Manually running the application for development
+### Docker containers for external software
+
+You will need Docker installed to run these containers.
+
+First navigate to `onyx/deployment/docker_compose`, then start up Postgres/Vespa/Redis/MinIO with:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d index relational_db cache minio
+```
+
+(index refers to Vespa, relational_db refers to Postgres, and cache refers to Redis)
+
+### Running Onyx locally
+
+To start the frontend, navigate to `onyx/web` and run:
+
+```bash
+npm run dev
+```
+
+Next, start the model server which runs the local NLP models.
+Navigate to `onyx/backend` and run:
+
+```bash
+uvicorn model_server.main:app --reload --port 9000
+```
+
+_For Windows (for compatibility with both PowerShell and Command Prompt):_
+
+```bash
+powershell -Command "uvicorn model_server.main:app --reload --port 9000"
+```
+
+The first time running Onyx, you will need to run the DB migrations for Postgres.
+After the first time, this is no longer required unless the DB models change.
+
+Navigate to `onyx/backend` and with the venv active, run:
+
+```bash
+alembic upgrade head
+```
+
+Next, start the task queue which orchestrates the background jobs.
+Jobs that take more time are run async from the API server.
+
+Still in `onyx/backend`, run:
+
+```bash
+python ./scripts/dev_run_background_jobs.py
+```
+
+To run the backend API server, navigate back to `onyx/backend` and run:
+
+```bash
+AUTH_TYPE=basic uvicorn onyx.main:app --reload --port 8080
+```
+
+_For Windows (for compatibility with both PowerShell and Command Prompt):_
+
+```bash
+powershell -Command "
+    $env:AUTH_TYPE='basic'
+    uvicorn onyx.main:app --reload --port 8080
+"
+```
+
+> **Note:**
+> If you need finer logging, add the additional environment variable `LOG_LEVEL=DEBUG` to the relevant services.
+
+#### Wrapping up
+
+You should now have 4 servers running:
+
+- Web server
+- Backend API
+- Model server
+- Background jobs
+
+Now, visit `http://localhost:3000` in your browser. You should see the Onyx onboarding wizard where you can connect your external LLM provider to Onyx.
+
+You've successfully set up a local Onyx instance! 🏁
+
+#### Running the Onyx application in a container
+
+You can run the full Onyx application stack from pre-built images including all external software dependencies.
+
+Navigate to `onyx/deployment/docker_compose` and run:
+
+```bash
+docker compose up -d
+```
+
+After Docker pulls and starts these containers, navigate to `http://localhost:3000` to use Onyx.
+
+If you want to make changes to Onyx and run those changes in Docker, you can also build a local version of the Onyx container images that incorporates your changes like so:
+
+```bash
+docker compose up -d --build
+```

pyproject.toml

@@ -49,7 +49,7 @@ backend = [
     "fastapi-users==15.0.4",
     "fastapi-users-db-sqlalchemy==7.0.0",
     "fastapi-limiter==0.1.6",
-    "fastmcp==3.2.0",
+    "fastmcp==3.0.2",
     "filelock==3.20.3",
     "google-api-python-client==2.86.0",
     "google-auth-httplib2==0.1.0",

uv.lock

@@ -1809,7 +1809,7 @@ wheels = [
 
 [[package]]
 name = "fastmcp"
-version = "3.2.0"
+version = "3.0.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "authlib" },
@@ -1829,14 +1829,13 @@ dependencies = [
     { name = "python-dotenv" },
     { name = "pyyaml" },
     { name = "rich" },
-    { name = "uncalled-for" },
     { name = "uvicorn" },
     { name = "watchfiles" },
     { name = "websockets" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d0/32/4f1b2cfd7b50db89114949f90158b1dcc2c92a1917b9f57c0ff24e47a2f4/fastmcp-3.2.0.tar.gz", hash = "sha256:d4830b8ffc3592d3d9c76dc0f398904cf41f04910e41a0de38cc1004e0903bef", size = 26318581, upload-time = "2026-03-30T20:25:37.692Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/11/6b/1a7ec89727797fb07ec0928e9070fa2f45e7b35718e1fe01633a34c35e45/fastmcp-3.0.2.tar.gz", hash = "sha256:6bd73b4a3bab773ee6932df5249dcbcd78ed18365ed0aeeb97bb42702a7198d7", size = 17239351, upload-time = "2026-02-22T16:32:28.843Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4f/67/684fa2d2de1e7504549d4ca457b4f854ccec3cd3be03bd86b33b599fbf58/fastmcp-3.2.0-py3-none-any.whl", hash = "sha256:e71aba3df16f86f546a4a9e513261d3233bcc92bef0dfa647bac3fa33623f681", size = 705550, upload-time = "2026-03-30T20:25:35.499Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/5a/f410a9015cfde71adf646dab4ef2feae49f92f34f6050fcfb265eb126b30/fastmcp-3.0.2-py3-none-any.whl", hash = "sha256:f513d80d4b30b54749fe8950116b1aab843f3c293f5cb971fc8665cb48dbb028", size = 606268, upload-time = "2026-02-22T16:32:30.992Z" },
 ]
 
 [[package]]
@@ -4422,7 +4421,7 @@ requires-dist = [
     { name = "fastapi-limiter", marker = "extra == 'backend'", specifier = "==0.1.6" },
     { name = "fastapi-users", marker = "extra == 'backend'", specifier = "==15.0.4" },
     { name = "fastapi-users-db-sqlalchemy", marker = "extra == 'backend'", specifier = "==7.0.0" },
-    { name = "fastmcp", marker = "extra == 'backend'", specifier = "==3.2.0" },
+    { name = "fastmcp", marker = "extra == 'backend'", specifier = "==3.0.2" },
     { name = "filelock", marker = "extra == 'backend'", specifier = "==3.20.3" },
     { name = "google-api-python-client", marker = "extra == 'backend'", specifier = "==2.86.0" },
     { name = "google-auth-httplib2", marker = "extra == 'backend'", specifier = "==0.1.0" },
@@ -7574,15 +7573,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c2/14/e2a54fabd4f08cd7af1c07030603c3356b74da07f7cc056e600436edfa17/tzlocal-5.3.1-py3-none-any.whl", hash = "sha256:eb1a66c3ef5847adf7a834f1be0800581b683b5608e74f86ecbcef8ab91bb85d", size = 18026, upload-time = "2025-03-05T21:17:39.857Z" },
 ]
 
-[[package]]
-name = "uncalled-for"
-version = "0.2.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/02/7c/b5b7d8136f872e3f13b0584e576886de0489d7213a12de6bebf29ff6ebfc/uncalled_for-0.2.0.tar.gz", hash = "sha256:b4f8fdbcec328c5a113807d653e041c5094473dd4afa7c34599ace69ccb7e69f", size = 49488, upload-time = "2026-02-27T17:40:58.137Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ff/7f/4320d9ce3be404e6310b915c3629fe27bf1e2f438a1a7a3cb0396e32e9a9/uncalled_for-0.2.0-py3-none-any.whl", hash = "sha256:2c0bd338faff5f930918f79e7eb9ff48290df2cb05fcc0b40a7f334e55d4d85f", size = 11351, upload-time = "2026-02-27T17:40:56.804Z" },
-]
-
 [[package]]
 name = "unstructured"
 version = "0.18.27"

web/lib/opal/src/core/interactive/foldable/styles.css

@@ -1,8 +1,8 @@
 /* ---------------------------------------------------------------------------
    Foldable — CSS grid collapse/expand animation.
 
-   Expands when an ancestor `.interactive` element is hovered, focused
-   within, or has `data-interaction="hover"` / `data-interaction="active"`.
+   Expands when an ancestor `.interactive` element is hovered or has
+   `data-interaction="hover"` / `data-interaction="active"`.
 
    Structure:
      .interactive-foldable-host   — flex parent, gap transitions 0 → 0.25rem
@@ -19,7 +19,6 @@
 }
 
 .interactive:hover:not([data-disabled]) .interactive-foldable-host,
-.interactive:focus-within:not([data-disabled]) .interactive-foldable-host,
 .interactive[data-interaction="hover"]:not([data-disabled])
   .interactive-foldable-host,
 .interactive[data-interaction="active"]:not([data-disabled])
@@ -44,9 +43,8 @@
   min-width: 0;
 }
 
-/* Expanded: hovered, focused within, or interaction override */
+/* Expanded: hovered or interaction override */
 .interactive:hover:not([data-disabled]) .interactive-foldable,
-.interactive:focus-within:not([data-disabled]) .interactive-foldable,
 .interactive[data-interaction="hover"]:not([data-disabled])
   .interactive-foldable,
 .interactive[data-interaction="active"]:not([data-disabled])

web/src/app/admin/api-key/OnyxApiKeyForm.tsx

@@ -0,0 +1,153 @@
+import { Form, Formik } from "formik";
+import { toast } from "@/hooks/useToast";
+import { createApiKey, updateApiKey } from "./lib";
+import Modal from "@/refresh-components/Modal";
+import { Button } from "@opal/components";
+import { Disabled } from "@opal/core";
+import Text from "@/refresh-components/texts/Text";
+import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
+import InputSelect from "@/refresh-components/inputs/InputSelect";
+import { FormikField } from "@/refresh-components/form/FormikField";
+import { FormField } from "@/refresh-components/form/FormField";
+import { USER_ROLE_LABELS, UserRole } from "@/lib/types";
+import { APIKey } from "./types";
+import { SvgKey } from "@opal/icons";
+
+export interface OnyxApiKeyFormProps {
+  onClose: () => void;
+  onCreateApiKey: (apiKey: APIKey) => void;
+  apiKey?: APIKey;
+}
+
+export default function OnyxApiKeyForm({
+  onClose,
+  onCreateApiKey,
+  apiKey,
+}: OnyxApiKeyFormProps) {
+  const isUpdate = apiKey !== undefined;
+
+  return (
+    <Modal open onOpenChange={onClose}>
+      <Modal.Content width="sm" height="lg">
+        <Modal.Header
+          icon={SvgKey}
+          title={isUpdate ? "Update API Key" : "Create a new API Key"}
+          onClose={onClose}
+        />
+        <Formik
+          initialValues={{
+            name: apiKey?.api_key_name || "",
+            role: apiKey?.api_key_role || UserRole.BASIC.toString(),
+          }}
+          onSubmit={async (values, formikHelpers) => {
+            formikHelpers.setSubmitting(true);
+
+            // Prepare the payload with the UserRole
+            const payload = {
+              ...values,
+              role: values.role as UserRole, // Assign the role directly as a UserRole type
+            };
+
+            let response;
+            if (isUpdate) {
+              response = await updateApiKey(apiKey.api_key_id, payload);
+            } else {
+              response = await createApiKey(payload);
+            }
+            formikHelpers.setSubmitting(false);
+            if (response.ok) {
+              toast.success(
+                isUpdate
+                  ? "Successfully updated API key!"
+                  : "Successfully created API key!"
+              );
+              if (!isUpdate) {
+                onCreateApiKey(await response.json());
+              }
+              onClose();
+            } else {
+              const responseJson = await response.json();
+              const errorMsg = responseJson.detail || responseJson.message;
+              toast.error(
+                isUpdate
+                  ? `Error updating API key - ${errorMsg}`
+                  : `Error creating API key - ${errorMsg}`
+              );
+            }
+          }}
+        >
+          {({ isSubmitting }) => (
+            <Form className="w-full overflow-visible">
+              <Modal.Body>
+                <Text as="p">
+                  Choose a memorable name for your API key. This is optional and
+                  can be added or changed later!
+                </Text>
+
+                <FormikField<string>
+                  name="name"
+                  render={(field, helper, _meta, state) => (
+                    <FormField name="name" state={state} className="w-full">
+                      <FormField.Label>Name (optional):</FormField.Label>
+                      <FormField.Control>
+                        <InputTypeIn
+                          {...field}
+                          placeholder=""
+                          onClear={() => helper.setValue("")}
+                          showClearButton={false}
+                        />
+                      </FormField.Control>
+                    </FormField>
+                  )}
+                />
+
+                <FormikField<string>
+                  name="role"
+                  render={(field, helper, _meta, state) => (
+                    <FormField name="role" state={state} className="w-full">
+                      <FormField.Label>Role:</FormField.Label>
+                      <FormField.Control>
+                        <InputSelect
+                          value={field.value}
+                          onValueChange={(value) => helper.setValue(value)}
+                        >
+                          <InputSelect.Trigger placeholder="Select a role" />
+                          <InputSelect.Content>
+                            <InputSelect.Item
+                              value={UserRole.LIMITED.toString()}
+                            >
+                              {USER_ROLE_LABELS[UserRole.LIMITED]}
+                            </InputSelect.Item>
+                            <InputSelect.Item value={UserRole.BASIC.toString()}>
+                              {USER_ROLE_LABELS[UserRole.BASIC]}
+                            </InputSelect.Item>
+                            <InputSelect.Item value={UserRole.ADMIN.toString()}>
+                              {USER_ROLE_LABELS[UserRole.ADMIN]}
+                            </InputSelect.Item>
+                          </InputSelect.Content>
+                        </InputSelect>
+                      </FormField.Control>
+                      <FormField.Description>
+                        Select the role for this API key. Limited has access to
+                        simple public APIs. Basic has access to regular user
+                        APIs. Admin has access to admin level APIs.
+                      </FormField.Description>
+                    </FormField>
+                  )}
+                />
+              </Modal.Body>
+
+              <Modal.Footer>
+                <Disabled disabled={isSubmitting}>
+                  <Button type="submit">
+                    {isUpdate ? "Update" : "Create"}
+                  </Button>
+                </Disabled>
+              </Modal.Footer>
+            </Form>
+          )}
+        </Formik>
+      </Modal.Content>
+    </Modal>
+  );
+}

web/src/app/admin/api-key/lib.ts

@@ -0,0 +1,39 @@
+import { APIKeyArgs, APIKey } from "./types";
+
+export const createApiKey = async (apiKeyArgs: APIKeyArgs) => {
+  return fetch("/api/admin/api-key", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(apiKeyArgs),
+  });
+};
+
+export const regenerateApiKey = async (apiKey: APIKey) => {
+  return fetch(`/api/admin/api-key/${apiKey.api_key_id}/regenerate`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+  });
+};
+
+export const updateApiKey = async (
+  apiKeyId: number,
+  apiKeyArgs: APIKeyArgs
+) => {
+  return fetch(`/api/admin/api-key/${apiKeyId}`, {
+    method: "PATCH",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(apiKeyArgs),
+  });
+};
+
+export const deleteApiKey = async (apiKeyId: number) => {
+  return fetch(`/api/admin/api-key/${apiKeyId}`, {
+    method: "DELETE",
+  });
+};

web/src/app/admin/api-key/page.tsx

@@ -0,0 +1,259 @@
+"use client";
+
+import { ThreeDotsLoader } from "@/components/Loading";
+import { errorHandlingFetcher } from "@/lib/fetcher";
+import * as SettingsLayouts from "@/layouts/settings-layouts";
+import { ErrorCallout } from "@/components/ErrorCallout";
+import useSWR, { mutate } from "swr";
+import Separator from "@/refresh-components/Separator";
+import {
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Table,
+} from "@/components/ui/table";
+import Title from "@/components/ui/title";
+import { toast } from "@/hooks/useToast";
+import { useState } from "react";
+import { DeleteButton } from "@/components/DeleteButton";
+import Modal from "@/refresh-components/Modal";
+import { Spinner } from "@/components/Spinner";
+import { deleteApiKey, regenerateApiKey } from "@/app/admin/api-key/lib";
+import OnyxApiKeyForm from "@/app/admin/api-key/OnyxApiKeyForm";
+import {
+  APIKey,
+  DISCORD_SERVICE_API_KEY_NAME,
+} from "@/app/admin/api-key/types";
+import CreateButton from "@/refresh-components/buttons/CreateButton";
+import { Button } from "@opal/components";
+import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
+import Text from "@/refresh-components/texts/Text";
+import { SvgEdit, SvgKey, SvgRefreshCw } from "@opal/icons";
+import Message from "@/refresh-components/messages/Message";
+import { useCloudSubscription } from "@/hooks/useCloudSubscription";
+import { useBillingInformation } from "@/hooks/useBillingInformation";
+import { BillingStatus, hasActiveSubscription } from "@/lib/billing/interfaces";
+import { ADMIN_ROUTES } from "@/lib/admin-routes";
+
+const route = ADMIN_ROUTES.API_KEYS;
+
+function Main() {
+  const {
+    data: apiKeys,
+    isLoading,
+    error,
+  } = useSWR<APIKey[]>("/api/admin/api-key", errorHandlingFetcher);
+
+  const canCreateKeys = useCloudSubscription();
+  const { data: billingData } = useBillingInformation();
+  const isTrialing =
+    billingData !== undefined &&
+    hasActiveSubscription(billingData) &&
+    billingData.status === BillingStatus.TRIALING;
+
+  const [fullApiKey, setFullApiKey] = useState<string | null>(null);
+  const [keyIsGenerating, setKeyIsGenerating] = useState(false);
+  const [showCreateUpdateForm, setShowCreateUpdateForm] = useState(false);
+  const [selectedApiKey, setSelectedApiKey] = useState<APIKey | undefined>();
+
+  const handleEdit = (apiKey: APIKey) => {
+    setSelectedApiKey(apiKey);
+    setShowCreateUpdateForm(true);
+  };
+
+  if (isLoading) {
+    return <ThreeDotsLoader />;
+  }
+
+  if (!apiKeys || error) {
+    return (
+      <ErrorCallout
+        errorTitle="Failed to fetch API Keys"
+        errorMsg={error?.info?.detail || error.toString()}
+      />
+    );
+  }
+
+  // Filter out the discord service key from the displayed list
+  const filteredApiKeys = apiKeys.filter(
+    (key) => key.api_key_name !== DISCORD_SERVICE_API_KEY_NAME
+  );
+
+  const introSection = (
+    <div className="flex flex-col items-start gap-4">
+      {isTrialing && (
+        <Message
+          static
+          warning
+          close={false}
+          className="w-full"
+          text="Upgrade to a paid plan to create API keys."
+          description="Trial accounts do not include API key access — purchase a paid subscription to unlock this feature."
+        />
+      )}
+      <Text as="p">
+        API Keys allow you to access Onyx APIs programmatically.
+        {canCreateKeys
+          ? " Click the button below to generate a new API Key."
+          : ""}
+      </Text>
+      {canCreateKeys ? (
+        <CreateButton onClick={() => setShowCreateUpdateForm(true)}>
+          Create API Key
+        </CreateButton>
+      ) : isTrialing ? (
+        <Button href="/admin/billing">Upgrade to Paid Plan</Button>
+      ) : null}
+    </div>
+  );
+
+  if (filteredApiKeys.length === 0) {
+    return (
+      <div>
+        {introSection}
+
+        {showCreateUpdateForm && (
+          <OnyxApiKeyForm
+            onCreateApiKey={(apiKey) => {
+              setFullApiKey(apiKey.api_key);
+            }}
+            onClose={() => {
+              setShowCreateUpdateForm(false);
+              setSelectedApiKey(undefined);
+              mutate("/api/admin/api-key");
+            }}
+            apiKey={selectedApiKey}
+          />
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <Modal open={!!fullApiKey}>
+        <Modal.Content width="sm" height="sm">
+          <Modal.Header
+            title="New API Key"
+            icon={SvgKey}
+            onClose={() => setFullApiKey(null)}
+            description="Make sure you copy your new API key. You won't be able to see this key again."
+          />
+          <Modal.Body>
+            <Text as="p" className="break-all flex-1">
+              {fullApiKey}
+            </Text>
+            <CopyIconButton getCopyText={() => fullApiKey!} />
+          </Modal.Body>
+        </Modal.Content>
+      </Modal>
+
+      {keyIsGenerating && <Spinner />}
+
+      {introSection}
+
+      {canCreateKeys && (
+        <>
+          <Separator />
+
+          <Title className="mt-6">Existing API Keys</Title>
+          <Table className="overflow-visible">
+            <TableHeader>
+              <TableRow>
+                <TableHead>Name</TableHead>
+                <TableHead>API Key</TableHead>
+                <TableHead>Role</TableHead>
+                <TableHead>Regenerate</TableHead>
+                <TableHead>Delete</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {filteredApiKeys.map((apiKey) => (
+                <TableRow key={apiKey.api_key_id}>
+                  <TableCell>
+                    <Button
+                      prominence="internal"
+                      onClick={() => handleEdit(apiKey)}
+                      icon={SvgEdit}
+                    >
+                      {apiKey.api_key_name || "null"}
+                    </Button>
+                  </TableCell>
+                  <TableCell className="max-w-64">
+                    {apiKey.api_key_display}
+                  </TableCell>
+                  <TableCell className="max-w-64">
+                    {apiKey.api_key_role.toUpperCase()}
+                  </TableCell>
+                  <TableCell>
+                    <Button
+                      prominence="internal"
+                      icon={SvgRefreshCw}
+                      onClick={async () => {
+                        setKeyIsGenerating(true);
+                        const response = await regenerateApiKey(apiKey);
+                        setKeyIsGenerating(false);
+                        if (!response.ok) {
+                          const errorMsg = await response.text();
+                          toast.error(
+                            `Failed to regenerate API Key: ${errorMsg}`
+                          );
+                          return;
+                        }
+                        const newKey = (await response.json()) as APIKey;
+                        setFullApiKey(newKey.api_key);
+                        mutate("/api/admin/api-key");
+                      }}
+                    >
+                      Refresh
+                    </Button>
+                  </TableCell>
+                  <TableCell>
+                    <DeleteButton
+                      onClick={async () => {
+                        const response = await deleteApiKey(apiKey.api_key_id);
+                        if (!response.ok) {
+                          const errorMsg = await response.text();
+                          toast.error(`Failed to delete API Key: ${errorMsg}`);
+                          return;
+                        }
+                        mutate("/api/admin/api-key");
+                      }}
+                    />
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+
+          {showCreateUpdateForm && (
+            <OnyxApiKeyForm
+              onCreateApiKey={(apiKey) => {
+                setFullApiKey(apiKey.api_key);
+              }}
+              onClose={() => {
+                setShowCreateUpdateForm(false);
+                setSelectedApiKey(undefined);
+                mutate("/api/admin/api-key");
+              }}
+              apiKey={selectedApiKey}
+            />
+          )}
+        </>
+      )}
+    </>
+  );
+}
+
+export default function Page() {
+  return (
+    <SettingsLayouts.Root>
+      <SettingsLayouts.Header title={route.title} icon={route.icon} separator />
+      <SettingsLayouts.Body>
+        <Main />
+      </SettingsLayouts.Body>
+    </SettingsLayouts.Root>
+  );
+}

web/src/app/admin/api-key/types.ts

@@ -1,5 +1,6 @@
 import { UserRole } from "@/lib/types";
 
+// Discord bot service API key name - should match backend constant
 export const DISCORD_SERVICE_API_KEY_NAME = "discord-bot-service";
 
 export interface APIKey {

web/src/app/admin/bots/[bot-id]/hooks.ts

@@ -1,52 +1,43 @@
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { SlackBot, SlackChannelConfig } from "@/lib/types";
 import useSWR, { mutate } from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 
 export const useSlackChannelConfigs = () => {
-  const swrResponse = useSWR<SlackChannelConfig[]>(
-    SWR_KEYS.slackChannels,
-    errorHandlingFetcher
-  );
+  const url = "/api/manage/admin/slack-app/channel";
+  const swrResponse = useSWR<SlackChannelConfig[]>(url, errorHandlingFetcher);
 
   return {
     ...swrResponse,
-    refreshSlackChannelConfigs: () => mutate(SWR_KEYS.slackChannels),
+    refreshSlackChannelConfigs: () => mutate(url),
   };
 };
 
 export const useSlackBots = () => {
-  const swrResponse = useSWR<SlackBot[]>(
-    SWR_KEYS.slackBots,
-    errorHandlingFetcher
-  );
+  const url = "/api/manage/admin/slack-app/bots";
+  const swrResponse = useSWR<SlackBot[]>(url, errorHandlingFetcher);
 
   return {
     ...swrResponse,
-    refreshSlackBots: () => mutate(SWR_KEYS.slackBots),
+    refreshSlackBots: () => mutate(url),
   };
 };
 
 export const useSlackBot = (botId: number) => {
-  const swrResponse = useSWR<SlackBot>(
-    SWR_KEYS.slackBot(botId),
-    errorHandlingFetcher
-  );
+  const url = `/api/manage/admin/slack-app/bots/${botId}`;
+  const swrResponse = useSWR<SlackBot>(url, errorHandlingFetcher);
 
   return {
     ...swrResponse,
-    refreshSlackBot: () => mutate(SWR_KEYS.slackBot(botId)),
+    refreshSlackBot: () => mutate(url),
   };
 };
 
 export const useSlackChannelConfigsByBot = (botId: number) => {
-  const swrResponse = useSWR<SlackChannelConfig[]>(
-    SWR_KEYS.slackBotConfig(botId),
-    errorHandlingFetcher
-  );
+  const url = `/api/manage/admin/slack-app/bots/${botId}/config`;
+  const swrResponse = useSWR<SlackChannelConfig[]>(url, errorHandlingFetcher);
 
   return {
     ...swrResponse,
-    refreshSlackChannelConfigs: () => mutate(SWR_KEYS.slackBotConfig(botId)),
+    refreshSlackChannelConfigs: () => mutate(url),
   };
 };

web/src/app/admin/configuration/document-processing/page.tsx

@@ -5,7 +5,6 @@ import CardSection from "@/components/admin/CardSection";
 import { Button } from "@opal/components";
 import InputTypeIn from "@/refresh-components/inputs/InputTypeIn";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { ThreeDotsLoader } from "@/components/Loading";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import Text from "@/refresh-components/texts/Text";
@@ -23,7 +22,7 @@ function Main() {
     isLoading,
   } = useSWR<{
     unstructured_api_key: string | null;
-  }>(SWR_KEYS.unstructuredApiKeySet, (url: string) =>
+  }>("/api/search-settings/unstructured-api-key-set", (url: string) =>
     fetch(url).then((res) => res.json())
   );
 

web/src/app/admin/configuration/search/UpgradingPage.tsx

@@ -15,7 +15,6 @@ import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
 import { useMemo, useState } from "react";
 import useSWR, { mutate } from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { ReindexingProgressTable } from "../../../../components/embedding/ReindexingProgressTable";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import {
@@ -39,7 +38,7 @@ export default function UpgradingPage({
 
   const { data: connectors, isLoading: isLoadingConnectors } = useSWR<
     Connector<any>[]
-  >(vectorDbEnabled ? SWR_KEYS.connector : null, errorHandlingFetcher, {
+  >(vectorDbEnabled ? "/api/manage/connector" : null, errorHandlingFetcher, {
     refreshInterval: 5000,
   });
 
@@ -70,7 +69,7 @@ export default function UpgradingPage({
       method: "POST",
     });
     if (response.ok) {
-      mutate(SWR_KEYS.secondarySearchSettings);
+      mutate("/api/search-settings/get-secondary-search-settings");
     } else {
       alert(
         `Failed to cancel embedding model update - ${await response.text()}`

web/src/app/admin/configuration/search/page.tsx

@@ -7,7 +7,6 @@ import { Text } from "@opal/components";
 import Title from "@/components/ui/title";
 import { Button } from "@opal/components";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { ModelPreview } from "@/components/embedding/ModelSelector";
 import {
   HostedEmbeddingModel,
@@ -44,14 +43,14 @@ function Main() {
     isLoading: isLoadingCurrentModel,
     error: currentEmeddingModelError,
   } = useSWR<CloudEmbeddingModel | HostedEmbeddingModel | null>(
-    SWR_KEYS.currentSearchSettings,
+    "/api/search-settings/get-current-search-settings",
     errorHandlingFetcher,
     { refreshInterval: 5000 } // 5 seconds
   );
 
   const { data: searchSettings, isLoading: isLoadingSearchSettings } =
     useSWR<SavedSearchSettings | null>(
-      SWR_KEYS.currentSearchSettings,
+      "/api/search-settings/get-current-search-settings",
       errorHandlingFetcher,
       { refreshInterval: 5000 } // 5 seconds
     );
@@ -61,7 +60,7 @@ function Main() {
     isLoading: isLoadingFutureModel,
     error: futureEmeddingModelError,
   } = useSWR<CloudEmbeddingModel | HostedEmbeddingModel | null>(
-    SWR_KEYS.secondarySearchSettings,
+    "/api/search-settings/get-secondary-search-settings",
     errorHandlingFetcher,
     { refreshInterval: 5000 } // 5 seconds
   );

web/src/app/admin/connectors/[connector]/pages/gdrive/Credential.tsx

@@ -19,7 +19,6 @@ import {
 } from "@/lib/connectors/credentials";
 import { refreshAllGoogleData } from "@/lib/googleConnector";
 import { ValidSources } from "@/lib/types";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { buildSimilarCredentialInfoURL } from "@/app/admin/connector/[ccPairId]/lib";
 import { FiFile, FiCheck, FiLink, FiAlertTriangle } from "react-icons/fi";
 import { cn, truncateString } from "@/lib/utils";
@@ -77,7 +76,7 @@ export const DriveJsonUpload = ({ onSuccess }: { onSuccess?: () => void }) => {
         );
         if (response.ok) {
           toast.success("Successfully uploaded app credentials");
-          mutate(SWR_KEYS.googleConnectorAppCredential("google-drive"));
+          mutate("/api/manage/admin/connector/google-drive/app-credential");
           if (onSuccess) {
             onSuccess();
           }
@@ -100,7 +99,9 @@ export const DriveJsonUpload = ({ onSuccess }: { onSuccess?: () => void }) => {
         );
         if (response.ok) {
           toast.success("Successfully uploaded service account key");
-          mutate(SWR_KEYS.googleConnectorServiceAccountKey("google-drive"));
+          mutate(
+            "/api/manage/admin/connector/google-drive/service-account-key"
+          );
           if (onSuccess) {
             onSuccess();
           }
@@ -318,10 +319,8 @@ export const DriveJsonUploadSection = ({
                 onClick={async () => {
                   const endpoint =
                     localServiceAccountData?.service_account_email
-                      ? SWR_KEYS.googleConnectorServiceAccountKey(
-                          "google-drive"
-                        )
-                      : SWR_KEYS.googleConnectorAppCredential("google-drive");
+                      ? "/api/manage/admin/connector/google-drive/service-account-key"
+                      : "/api/manage/admin/connector/google-drive/app-credential";
 
                   const response = await fetch(endpoint, {
                     method: "DELETE",
@@ -335,14 +334,14 @@ export const DriveJsonUploadSection = ({
                     );
 
                     // Add additional mutations to refresh all credential-related endpoints
-                    mutate(SWR_KEYS.googleConnectorCredentials("google-drive"));
                     mutate(
-                      SWR_KEYS.googleConnectorPublicCredential("google-drive")
+                      "/api/manage/admin/connector/google-drive/credentials"
                     );
                     mutate(
-                      SWR_KEYS.googleConnectorServiceAccountCredential(
-                        "google-drive"
-                      )
+                      "/api/manage/admin/connector/google-drive/public-credential"
+                    );
+                    mutate(
+                      "/api/manage/admin/connector/google-drive/service-account-credential"
                     );
 
                     toast.success(

web/src/app/admin/connectors/[connector]/pages/gmail/Credential.tsx

@@ -21,7 +21,6 @@ import {
 } from "@/lib/connectors/credentials";
 import { refreshAllGoogleData } from "@/lib/googleConnector";
 import { ValidSources } from "@/lib/types";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { buildSimilarCredentialInfoURL } from "@/app/admin/connector/[ccPairId]/lib";
 import { FiFile, FiCheck, FiLink, FiAlertTriangle } from "react-icons/fi";
 import { cn, truncateString } from "@/lib/utils";
@@ -80,7 +79,7 @@ const GmailCredentialUpload = ({ onSuccess }: { onSuccess?: () => void }) => {
         );
         if (response.ok) {
           toast.success("Successfully uploaded app credentials");
-          mutate(SWR_KEYS.googleConnectorAppCredential("gmail"));
+          mutate("/api/manage/admin/connector/gmail/app-credential");
           if (onSuccess) {
             onSuccess();
           }
@@ -103,7 +102,7 @@ const GmailCredentialUpload = ({ onSuccess }: { onSuccess?: () => void }) => {
         );
         if (response.ok) {
           toast.success("Successfully uploaded service account key");
-          mutate(SWR_KEYS.googleConnectorServiceAccountKey("gmail"));
+          mutate("/api/manage/admin/connector/gmail/service-account-key");
           if (onSuccess) {
             onSuccess();
           }
@@ -320,8 +319,8 @@ export const GmailJsonUploadSection = ({
                 onClick={async () => {
                   const endpoint =
                     localServiceAccountData?.service_account_email
-                      ? SWR_KEYS.googleConnectorServiceAccountKey("gmail")
-                      : SWR_KEYS.googleConnectorAppCredential("gmail");
+                      ? "/api/manage/admin/connector/gmail/service-account-key"
+                      : "/api/manage/admin/connector/gmail/app-credential";
 
                   const response = await fetch(endpoint, {
                     method: "DELETE",
@@ -333,10 +332,12 @@ export const GmailJsonUploadSection = ({
                     mutate(buildSimilarCredentialInfoURL(ValidSources.Gmail));
 
                     // Add additional mutations to refresh all credential-related endpoints
-                    mutate(SWR_KEYS.googleConnectorCredentials("gmail"));
-                    mutate(SWR_KEYS.googleConnectorPublicCredential("gmail"));
+                    mutate("/api/manage/admin/connector/gmail/credentials");
                     mutate(
-                      SWR_KEYS.googleConnectorServiceAccountCredential("gmail")
+                      "/api/manage/admin/connector/gmail/public-credential"
+                    );
+                    mutate(
+                      "/api/manage/admin/connector/gmail/service-account-credential"
                     );
 
                     toast.success(

web/src/app/admin/document-index-migration/page.tsx

@@ -2,7 +2,6 @@
 
 import { useState } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import * as SettingsLayouts from "@/layouts/settings-layouts";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
 
@@ -32,7 +31,7 @@ function formatTimestamp(iso: string): string {
 
 function MigrationStatusSection() {
   const { data, isLoading, error } = useSWR<MigrationStatus>(
-    SWR_KEYS.opensearchMigrationStatus,
+    "/api/admin/opensearch-migration/status",
     errorHandlingFetcher
   );
 
@@ -122,7 +121,7 @@ function MigrationStatusSection() {
 
 function RetrievalSourceSection() {
   const { data, isLoading, error, mutate } = useSWR<RetrievalStatus>(
-    SWR_KEYS.opensearchMigrationRetrieval,
+    "/api/admin/opensearch-migration/retrieval",
     errorHandlingFetcher
   );
   const [selectedSource, setSelectedSource] = useState<string | null>(null);
@@ -137,13 +136,16 @@ function RetrievalSourceSection() {
   async function handleUpdate() {
     setUpdating(true);
     try {
-      const response = await fetch(SWR_KEYS.opensearchMigrationRetrieval, {
-        method: "PUT",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          enable_opensearch_retrieval: currentValue === "opensearch",
-        }),
-      });
+      const response = await fetch(
+        "/api/admin/opensearch-migration/retrieval",
+        {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            enable_opensearch_retrieval: currentValue === "opensearch",
+          }),
+        }
+      );
       if (!response.ok) {
         throw new Error("Failed to update retrieval setting");
       }

web/src/app/admin/embeddings/modals/ChangeCredentialsModal.tsx

@@ -11,9 +11,11 @@ import {
   CloudEmbeddingProvider,
   getFormattedProviderName,
 } from "@/components/embedding/interfaces";
-import { EMBEDDING_PROVIDERS_ADMIN_URL } from "@/lib/llmConfig/constants";
+import {
+  EMBEDDING_PROVIDERS_ADMIN_URL,
+  LLM_PROVIDERS_ADMIN_URL,
+} from "@/lib/llmConfig/constants";
 import { mutate } from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { testEmbedding } from "@/app/admin/embeddings/pages/utils";
 import { SvgSettings } from "@opal/icons";
 
@@ -100,7 +102,7 @@ export default function ChangeCredentialsModal({
         return;
       }
 
-      mutate(SWR_KEYS.adminLlmProviders);
+      mutate(LLM_PROVIDERS_ADMIN_URL);
       onDeleted();
     } catch (error) {
       setDeletionError(

web/src/app/admin/embeddings/pages/EmbeddingFormPage.tsx

@@ -17,7 +17,6 @@ import {
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { ThreeDotsLoader } from "@/components/Loading";
 import AdvancedEmbeddingFormPage from "./AdvancedEmbeddingFormPage";
 import {
@@ -120,7 +119,7 @@ export default function EmbeddingForm() {
     isLoading: isLoadingCurrentModel,
     error: currentEmbeddingModelError,
   } = useSWR<CloudEmbeddingModel | HostedEmbeddingModel | null>(
-    SWR_KEYS.currentSearchSettings,
+    "/api/search-settings/get-current-search-settings",
     errorHandlingFetcher,
     { refreshInterval: 5000 } // 5 seconds
   );
@@ -131,7 +130,7 @@ export default function EmbeddingForm() {
 
   const { data: searchSettings, isLoading: isLoadingSearchSettings } =
     useSWR<SavedSearchSettings | null>(
-      SWR_KEYS.currentSearchSettings,
+      "/api/search-settings/get-current-search-settings",
       errorHandlingFetcher,
       { refreshInterval: 5000 } // 5 seconds
     );

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

@@ -1 +1 @@
-export { default } from "@/ee/refresh-pages/admin/HooksPage";
+export { default } from "@/refresh-pages/admin/HooksPage";

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

@@ -23,7 +23,6 @@ import {
 import { sanitizeKGConfig } from "@/app/admin/kg/utils";
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { toast } from "@/hooks/useToast";
 import Title from "@/components/ui/title";
 import { redirect } from "next/navigation";
@@ -217,13 +216,13 @@ function Main() {
     data: configData,
     isLoading: configIsLoading,
     mutate: configMutate,
-  } = useSWR<KGConfigRaw>(SWR_KEYS.kgConfig, errorHandlingFetcher);
+  } = useSWR<KGConfigRaw>("/api/admin/kg/config", errorHandlingFetcher);
   const {
     data: sourceAndEntityTypesData,
     isLoading: entityTypesIsLoading,
     mutate: entityTypesMutate,
   } = useSWR<SourceAndEntityTypeView>(
-    SWR_KEYS.kgEntityTypes,
+    "/api/admin/kg/entity-types",
     errorHandlingFetcher
   );
 

web/src/app/admin/kg/utils.ts

@@ -1,7 +1,6 @@
 import { useUser } from "@/providers/UserProvider";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { KGConfig, KGConfigRaw } from "./interfaces";
 
 export type KgExposedStatus = { kgExposed: boolean; isLoading: boolean };
@@ -9,7 +8,7 @@ export type KgExposedStatus = { kgExposed: boolean; isLoading: boolean };
 export function useIsKGExposed(): KgExposedStatus {
   const { isAdmin } = useUser();
   const { data: kgExposedRaw, isLoading } = useSWR<boolean>(
-    isAdmin ? SWR_KEYS.kgExposed : null,
+    isAdmin ? "/api/admin/kg/exposed" : null,
     errorHandlingFetcher,
     {
       revalidateOnFocus: false,

web/src/app/admin/scim/ScimModal.tsx

@@ -1,5 +1,5 @@
 import { SvgDownload, SvgKey, SvgRefreshCw } from "@opal/icons";
-import { Interactive, Hoverable } from "@opal/core";
+import { Interactive } from "@opal/core";
 import { Section } from "@/layouts/general-layouts";
 import { Button } from "@opal/components";
 import { Disabled } from "@opal/core";
@@ -83,30 +83,27 @@ export default function ScimModal({
               onClose={onClose}
             />
             <Modal.Body>
-              <Hoverable.Root group="token">
-                <Interactive.Stateless
-                  onClick={() => copyToClipboard(view.rawToken)}
-                >
-                  <InputTextArea
-                    value={view.rawToken}
-                    readOnly
-                    autoResize
-                    resizable={false}
-                    rows={2}
-                    className="font-main-ui-mono break-all cursor-pointer [&_textarea]:cursor-pointer"
-                    rightSection={
-                      <div onClick={(e) => e.stopPropagation()}>
-                        <Hoverable.Item
-                          group="token"
-                          variant="opacity-on-hover"
-                        >
-                          <CopyIconButton getCopyText={() => view.rawToken} />
-                        </Hoverable.Item>
-                      </div>
-                    }
-                  />
-                </Interactive.Stateless>
-              </Hoverable.Root>
+              <Interactive.Stateless
+                group="group/token"
+                onClick={() => copyToClipboard(view.rawToken)}
+              >
+                <InputTextArea
+                  value={view.rawToken}
+                  readOnly
+                  autoResize
+                  resizable={false}
+                  rows={2}
+                  className="font-main-ui-mono break-all cursor-pointer [&_textarea]:cursor-pointer"
+                  rightSection={
+                    <div
+                      className="opacity-0 group-hover/token:opacity-100 transition-opacity"
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      <CopyIconButton getCopyText={() => view.rawToken} />
+                    </div>
+                  }
+                />
+              </Interactive.Stateless>
             </Modal.Body>
             <Modal.Footer>
               <BasicModalFooter

web/src/app/admin/service-accounts/page.tsx

@@ -1 +0,0 @@
-export { default } from "@/refresh-pages/admin/ServiceAccountsPage";

web/src/app/admin/token-rate-limits/page.tsx

@@ -12,7 +12,6 @@ import {
 import { Scope, TokenRateLimit } from "./types";
 import { GenericTokenRateLimitTable } from "./TokenRateLimitTables";
 import { mutate } from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { toast } from "@/hooks/useToast";
 import CreateRateLimitModal from "./CreateRateLimitModal";
 import { usePaidEnterpriseFeaturesEnabled } from "@/components/settings/usePaidEnterpriseFeaturesEnabled";
@@ -22,9 +21,10 @@ import { Section } from "@/layouts/general-layouts";
 import { ADMIN_ROUTES } from "@/lib/admin-routes";
 
 const route = ADMIN_ROUTES.TOKEN_RATE_LIMITS;
-const GLOBAL_TOKEN_FETCH_URL = SWR_KEYS.globalTokenRateLimits;
-const USER_TOKEN_FETCH_URL = SWR_KEYS.userTokenRateLimits;
-const USER_GROUP_FETCH_URL = SWR_KEYS.userGroupTokenRateLimits;
+const BASE_URL = "/api/admin/token-rate-limits";
+const GLOBAL_TOKEN_FETCH_URL = `${BASE_URL}/global`;
+const USER_TOKEN_FETCH_URL = `${BASE_URL}/users`;
+const USER_GROUP_FETCH_URL = `${BASE_URL}/user-groups`;
 
 const GLOBAL_DESCRIPTION =
   "Global rate limits apply to all users, user groups, and API keys. When the global \

web/src/app/app/components/files/images/InMessageImage.tsx

@@ -4,7 +4,6 @@ import { ImageShape } from "@/app/app/services/streamingModels";
 import { FullImageModal } from "@/app/app/components/files/images/FullImageModal";
 import { buildImgUrl } from "@/app/app/components/files/images/utils";
 import { Button } from "@opal/components";
-import { Hoverable } from "@opal/core";
 import { cn } from "@/lib/utils";
 
 const DEFAULT_SHAPE: ImageShape = "square";
@@ -77,42 +76,42 @@ export const InMessageImage = memo(function InMessageImage({
         onOpenChange={(open) => setFullImageShowing(open)}
       />
 
-      <Hoverable.Root group="messageImage" widthVariant="fit">
-        <div className={cn("relative", shapeContainerClasses)}>
-          {!imageLoaded && (
-            <div className="absolute inset-0 bg-background-tint-02 animate-pulse rounded-lg" />
+      <div className={cn("relative group", shapeContainerClasses)}>
+        {!imageLoaded && (
+          <div className="absolute inset-0 bg-background-tint-02 animate-pulse rounded-lg" />
+        )}
+
+        <img
+          width={1200}
+          height={1200}
+          alt="Chat Message Image"
+          onLoad={() => {
+            loadedImages.add(fileId);
+            setImageLoaded(true);
+          }}
+          className={cn(
+            "object-contain object-left overflow-hidden rounded-lg w-full h-full transition-opacity duration-300 cursor-pointer",
+            shapeImageClasses,
+            imageLoaded ? "opacity-100" : "opacity-0"
           )}
+          onClick={() => setFullImageShowing(true)}
+          src={buildImgUrl(fileId)}
+          loading="lazy"
+        />
 
-          <img
-            width={1200}
-            height={1200}
-            alt="Chat Message Image"
-            onLoad={() => {
-              loadedImages.add(fileId);
-              setImageLoaded(true);
-            }}
-            className={cn(
-              "object-contain object-left overflow-hidden rounded-lg w-full h-full transition-opacity duration-300 cursor-pointer",
-              shapeImageClasses,
-              imageLoaded ? "opacity-100" : "opacity-0"
-            )}
-            onClick={() => setFullImageShowing(true)}
-            src={buildImgUrl(fileId)}
-            loading="lazy"
+        {/* Download button - appears on hover */}
+        <div
+          className={cn(
+            "absolute bottom-2 right-2 opacity-0 group-hover:opacity-100 z-10"
+          )}
+        >
+          <Button
+            icon={SvgDownload}
+            tooltip="Download"
+            onClick={handleDownload}
           />
-
-          {/* Download button - appears on hover */}
-          <div className="absolute bottom-2 right-2 z-10">
-            <Hoverable.Item group="messageImage" variant="opacity-on-hover">
-              <Button
-                icon={SvgDownload}
-                tooltip="Download"
-                onClick={handleDownload}
-              />
-            </Hoverable.Item>
-          </div>
         </div>
-      </Hoverable.Root>
+      </div>
     </>
   );
 });

web/src/app/app/components/projects/ProjectContextPanel.tsx

@@ -20,7 +20,6 @@ import IconButton from "@/refresh-components/buttons/IconButton";
 import ButtonRenaming from "@/refresh-components/buttons/ButtonRenaming";
 import { UserFileStatus } from "../../projects/projectsService";
 import { SvgAddLines, SvgEdit, SvgFiles, SvgFolderOpen } from "@opal/icons";
-import { Hoverable } from "@opal/core";
 
 export interface ProjectContextPanelProps {
   projectTokenCount?: number;
@@ -134,40 +133,34 @@ export default function ProjectContextPanel({
       <div className="flex flex-col gap-6 w-full max-w-[var(--app-page-main-content-width)] mx-auto p-4 pt-14 pb-6">
         <div className="flex flex-col gap-1 text-text-04">
           <SvgFolderOpen className="h-8 w-8 text-text-04" />
-          <Hoverable.Root group="projectName" widthVariant="fit">
-            <div className="flex items-center gap-2">
-              {isEditingName ? (
-                <ButtonRenaming
-                  initialName={projectName}
-                  onRename={async (newName) => {
-                    if (currentProjectId) {
-                      await renameProject(currentProjectId, newName);
-                    }
-                  }}
-                  onClose={cancelEditing}
-                  className="font-heading-h2 text-text-04"
+          <div className="group flex items-center gap-2">
+            {isEditingName ? (
+              <ButtonRenaming
+                initialName={projectName}
+                onRename={async (newName) => {
+                  if (currentProjectId) {
+                    await renameProject(currentProjectId, newName);
+                  }
+                }}
+                onClose={cancelEditing}
+                className="font-heading-h2 text-text-04"
+              />
+            ) : (
+              <>
+                <Text as="p" headingH2 className="font-heading-h2">
+                  {projectName}
+                </Text>
+                {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
+                <IconButton
+                  icon={SvgEdit}
+                  internal
+                  onClick={startEditing}
+                  className="opacity-0 group-hover:opacity-100 focus-visible:opacity-100 transition-opacity"
+                  tooltip="Edit project name"
                 />
-              ) : (
-                <>
-                  <Text as="p" headingH2 className="font-heading-h2">
-                    {projectName}
-                  </Text>
-                  {/* TODO(@raunakab): migrate to opal Button once className/iconClassName is resolved */}
-                  <Hoverable.Item
-                    group="projectName"
-                    variant="opacity-on-hover"
-                  >
-                    <IconButton
-                      icon={SvgEdit}
-                      internal
-                      onClick={startEditing}
-                      tooltip="Edit project name"
-                    />
-                  </Hoverable.Item>
-                </>
-              )}
-            </div>
-          </Hoverable.Root>
+              </>
+            )}
+          </div>
         </div>
 
         <Separator className="py-0" />

web/src/app/app/message/HumanMessage.tsx

@@ -10,7 +10,6 @@ import useScreenSize from "@/hooks/useScreenSize";
 import CopyIconButton from "@/refresh-components/buttons/CopyIconButton";
 import { Button } from "@opal/components";
 import { SvgEdit } from "@opal/icons";
-import { Hoverable } from "@opal/core";
 import FileDisplay from "./FileDisplay";
 
 interface MessageEditingProps {
@@ -171,9 +170,9 @@ const HumanMessage = React.memo(function HumanMessage({
     return undefined;
   };
 
-  const copyEditButtonContent = useMemo(
+  const copyEditButton = useMemo(
     () => (
-      <div className="flex flex-row flex-shrink px-1">
+      <div className="flex flex-row flex-shrink px-1 opacity-0 group-hover:opacity-100 transition-opacity">
         <CopyIconButton
           getCopyText={() => content}
           prominence="tertiary"
@@ -191,94 +190,86 @@ const HumanMessage = React.memo(function HumanMessage({
     [content]
   );
 
-  const copyEditButton = (
-    <Hoverable.Item group="humanMessage" variant="opacity-on-hover">
-      {copyEditButtonContent}
-    </Hoverable.Item>
-  );
-
   return (
-    <Hoverable.Root group="humanMessage" widthVariant="full">
-      <div
-        id="onyx-human-message"
-        className="flex flex-col justify-end w-full relative"
-      >
-        <FileDisplay files={files || []} />
-        {isEditing ? (
-          <MessageEditing
-            content={content}
-            onSubmitEdit={(editedContent) => {
-              // Don't update UI for edits that can't be persisted
-              if (messageId === undefined || messageId === null) {
-                setIsEditing(false);
-                return;
-              }
-              onEdit?.(editedContent, messageId);
-              setContent(editedContent);
+    <div
+      id="onyx-human-message"
+      className="group flex flex-col justify-end w-full relative"
+    >
+      <FileDisplay files={files || []} />
+      {isEditing ? (
+        <MessageEditing
+          content={content}
+          onSubmitEdit={(editedContent) => {
+            // Don't update UI for edits that can't be persisted
+            if (messageId === undefined || messageId === null) {
               setIsEditing(false);
-            }}
-            onCancelEdit={() => setIsEditing(false)}
-          />
-        ) : (
-          <div className="flex justify-end">
-            {onEdit && !isMobile && copyEditButton}
-            <div className="md:max-w-[37.5rem]">
-              <div
-                className={
-                  "max-w-[30rem] md:max-w-[37.5rem] whitespace-break-spaces break-anywhere rounded-t-16 rounded-bl-16 bg-background-tint-02 py-2 px-3"
+              return;
+            }
+            onEdit?.(editedContent, messageId);
+            setContent(editedContent);
+            setIsEditing(false);
+          }}
+          onCancelEdit={() => setIsEditing(false)}
+        />
+      ) : (
+        <div className="flex justify-end">
+          {onEdit && !isMobile && copyEditButton}
+          <div className="md:max-w-[37.5rem]">
+            <div
+              className={
+                "max-w-[30rem] md:max-w-[37.5rem] whitespace-break-spaces break-anywhere rounded-t-16 rounded-bl-16 bg-background-tint-02 py-2 px-3"
+              }
+              onCopy={(e) => {
+                const selection = window.getSelection();
+                if (selection) {
+                  e.preventDefault();
+                  const text = selection
+                    .toString()
+                    .replace(/\n{2,}/g, "\n")
+                    .trim();
+                  e.clipboardData.setData("text/plain", text);
                 }
-                onCopy={(e) => {
-                  const selection = window.getSelection();
-                  if (selection) {
-                    e.preventDefault();
-                    const text = selection
-                      .toString()
-                      .replace(/\n{2,}/g, "\n")
-                      .trim();
-                    e.clipboardData.setData("text/plain", text);
-                  }
-                }}
+              }}
+            >
+              <Text
+                as="p"
+                className="inline-block align-middle"
+                mainContentBody
               >
-                <Text
-                  as="p"
-                  className="inline-block align-middle"
-                  mainContentBody
-                >
-                  {content}
-                </Text>
-              </div>
+                {content}
+              </Text>
             </div>
           </div>
-        )}
-        <div className="flex justify-end pt-1">
-          {!isEditing && onEdit && isMobile && copyEditButton}
-          {currentMessageInd !== undefined &&
-            onMessageSelection &&
-            otherMessagesCanSwitchTo &&
-            otherMessagesCanSwitchTo.length > 1 && (
-              <MessageSwitcher
-                disableForStreaming={disableSwitchingForStreaming}
-                currentPage={currentMessageInd + 1}
-                totalPages={otherMessagesCanSwitchTo.length}
-                handlePrevious={() => {
-                  stopGenerating();
-                  const prevMessage = getPreviousMessage();
-                  if (prevMessage !== undefined) {
-                    onMessageSelection(prevMessage);
-                  }
-                }}
-                handleNext={() => {
-                  stopGenerating();
-                  const nextMessage = getNextMessage();
-                  if (nextMessage !== undefined) {
-                    onMessageSelection(nextMessage);
-                  }
-                }}
-              />
-            )}
         </div>
+      )}
+      <div className="flex justify-end pt-1">
+        {!isEditing && onEdit && isMobile && copyEditButton}
+        {currentMessageInd !== undefined &&
+          onMessageSelection &&
+          otherMessagesCanSwitchTo &&
+          otherMessagesCanSwitchTo.length > 1 && (
+            <MessageSwitcher
+              disableForStreaming={disableSwitchingForStreaming}
+              currentPage={currentMessageInd + 1}
+              totalPages={otherMessagesCanSwitchTo.length}
+              handlePrevious={() => {
+                stopGenerating();
+                const prevMessage = getPreviousMessage();
+                if (prevMessage !== undefined) {
+                  onMessageSelection(prevMessage);
+                }
+              }}
+              handleNext={() => {
+                stopGenerating();
+                const nextMessage = getNextMessage();
+                if (nextMessage !== undefined) {
+                  onMessageSelection(nextMessage);
+                }
+              }}
+            />
+          )}
       </div>
-    </Hoverable.Root>
+    </div>
   );
 }, arePropsEqual);
 

web/src/app/craft/components/OutputPanel.tsx

@@ -2,7 +2,6 @@
 
 import { memo, useState, useEffect, useCallback } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import {
   useSession,
   useWebappNeedsRefresh,
@@ -204,7 +203,7 @@ const BuildOutputPanel = memo(({ onClose, isOpen }: BuildOutputPanelProps) => {
     !isWebappReady && pollingDeadline !== null && Date.now() < pollingDeadline;
 
   const { data: webappInfo, mutate } = useSWR(
-    shouldFetchWebapp ? SWR_KEYS.buildSessionWebappInfo(session.id) : null,
+    shouldFetchWebapp ? `/api/build/sessions/${session.id}/webapp-info` : null,
     () => (session?.id ? fetchWebappInfo(session.id) : null),
     {
       refreshInterval: shouldPoll ? 2000 : 0,
@@ -351,7 +350,7 @@ const BuildOutputPanel = memo(({ onClose, isOpen }: BuildOutputPanelProps) => {
     activeTab === "artifacts";
 
   const { data: polledArtifacts } = useSWR(
-    shouldFetchArtifacts ? SWR_KEYS.buildSessionArtifacts(session.id) : null,
+    shouldFetchArtifacts ? `/api/build/sessions/${session.id}/artifacts` : null,
     () => (session?.id ? fetchArtifacts(session.id) : null),
     {
       refreshInterval: 5000, // Refresh every 5 seconds to catch new artifacts

web/src/app/craft/components/output-panel/ArtifactsTab.tsx

@@ -2,7 +2,6 @@
 
 import { useCallback, useEffect, useState } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import Text from "@/refresh-components/texts/Text";
 import { Button } from "@opal/components";
 import {
@@ -41,7 +40,10 @@ export default function ArtifactsTab({
   const filesNeedsRefresh = useFilesNeedsRefresh();
   const { data: outputsListing } = useSWR(
     sessionId
-      ? [SWR_KEYS.buildSessionOutputFiles(sessionId), filesNeedsRefresh]
+      ? [
+          `/api/build/sessions/${sessionId}/files?path=outputs`,
+          filesNeedsRefresh,
+        ]
       : null,
     () => (sessionId ? fetchDirectoryListing(sessionId, "outputs") : null),
     {

web/src/app/craft/components/output-panel/FilePreviewContent.tsx

@@ -2,7 +2,6 @@
 
 import { useEffect } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { fetchFileContent } from "@/app/craft/services/apiServices";
 import Text from "@/refresh-components/texts/Text";
 import { SvgFileText } from "@opal/icons";
@@ -155,7 +154,7 @@ function FetchedFilePreview({
   refreshKey,
 }: FetchedFilePreviewProps) {
   const { data, error, isLoading, mutate } = useSWR(
-    SWR_KEYS.buildSessionArtifactFile(sessionId, filePath),
+    `/api/build/sessions/${sessionId}/artifacts/${filePath}`,
     () => fetchFileContent(sessionId, filePath),
     {
       revalidateOnFocus: false,

web/src/app/craft/components/output-panel/FilesTab.tsx

@@ -2,7 +2,6 @@
 
 import { useState, useEffect, useMemo, useRef, useCallback } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import {
   useBuildSessionStore,
   useFilesTabState,
@@ -87,7 +86,7 @@ export default function FilesTab({
     error,
     mutate,
   } = useSWR(
-    sessionId ? SWR_KEYS.buildSessionFiles(sessionId) : null,
+    sessionId ? `/api/build/sessions/${sessionId}/files?path=` : null,
     () => (sessionId ? fetchDirectoryListing(sessionId, "") : null),
     {
       revalidateOnFocus: false,

web/src/app/craft/components/output-panel/PptxPreview.tsx

@@ -2,7 +2,6 @@
 
 import { useState, useEffect, useCallback } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { cn } from "@/lib/utils";
 import Text from "@/refresh-components/texts/Text";
 import { SvgChevronLeft, SvgChevronRight, SvgFileText } from "@opal/icons";
@@ -30,7 +29,7 @@ export default function PptxPreview({
   const [imageLoading, setImageLoading] = useState(true);
 
   const { data, error, isLoading, mutate } = useSWR(
-    SWR_KEYS.buildSessionPptxPreview(sessionId, filePath),
+    `/api/build/sessions/${sessionId}/pptx-preview/${filePath}`,
     () => fetchPptxPreview(sessionId, filePath),
     {
       revalidateOnFocus: false,

web/src/app/craft/hooks/useBuildConnectors.ts

@@ -1,6 +1,5 @@
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import {
   BuildConnectorConfig,
   ConnectorStatus,
@@ -24,7 +23,7 @@ interface BuildConnectorListResponse {
  */
 export function useBuildConnectors() {
   const { data, isLoading, mutate } = useSWR<BuildConnectorListResponse>(
-    SWR_KEYS.buildConnectors,
+    "/api/build/connectors",
     errorHandlingFetcher,
     { refreshInterval: 30000 } // 30 seconds - matches configure page
   );

web/src/app/craft/v1/configure/components/UserLibraryModal.tsx

@@ -2,7 +2,6 @@
 
 import { useState, useCallback, useRef, useMemo } from "react";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import {
   fetchLibraryTree,
   uploadLibraryFiles,
@@ -95,7 +94,7 @@ export default function UserLibraryModal({
     error,
     isLoading,
     mutate,
-  } = useSWR(open ? SWR_KEYS.buildUserLibraryTree : null, fetchLibraryTree, {
+  } = useSWR(open ? "/api/build/user-library/tree" : null, fetchLibraryTree, {
     revalidateOnFocus: false,
   });
 

web/src/app/ee/admin/performance/query-history/[id]/page.tsx

@@ -12,7 +12,6 @@ import BackButton from "@/refresh-components/buttons/BackButton";
 import { FeedbackBadge } from "../FeedbackBadge";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import { ErrorCallout } from "@/components/ErrorCallout";
 import { ThreeDotsLoader } from "@/components/Loading";
 import CardSection from "@/components/admin/CardSection";
@@ -73,7 +72,7 @@ export default function QueryPage(props: { params: Promise<{ id: string }> }) {
     isLoading,
     error,
   } = useSWR<ChatSessionSnapshot>(
-    SWR_KEYS.adminChatSession(params.id),
+    `/api/admin/chat-session-history/${params.id}`,
     errorHandlingFetcher
   );
 

web/src/app/ee/admin/performance/usage/UsageReports.tsx

@@ -19,7 +19,6 @@ import Button from "@/refresh-components/buttons/Button";
 import { Button as OpalButton } from "@opal/components";
 import { Disabled } from "@opal/core";
 import useSWR from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 import React, { useState } from "react";
 import { UsageReport } from "./types";
 import { ThreeDotsLoader } from "@/components/Loading";
@@ -226,7 +225,7 @@ function GenerateReportInput({
   );
 }
 
-const USAGE_REPORT_URL = SWR_KEYS.usageReport;
+const USAGE_REPORT_URL = "/api/admin/usage-report";
 
 function UsageReportsTable({
   refreshTrigger,

web/src/app/ee/admin/standard-answer/hooks.ts

@@ -1,29 +1,26 @@
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { StandardAnswerCategory, StandardAnswer } from "@/lib/types";
 import useSWR, { mutate } from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 
 export const useStandardAnswerCategories = () => {
+  const url = "/api/manage/admin/standard-answer/category";
   const swrResponse = useSWR<StandardAnswerCategory[]>(
-    SWR_KEYS.standardAnswerCategories,
+    url,
     errorHandlingFetcher
   );
 
   return {
     ...swrResponse,
-    refreshStandardAnswerCategories: () =>
-      mutate(SWR_KEYS.standardAnswerCategories),
+    refreshStandardAnswerCategories: () => mutate(url),
   };
 };
 
 export const useStandardAnswers = () => {
-  const swrResponse = useSWR<StandardAnswer[]>(
-    SWR_KEYS.standardAnswers,
-    errorHandlingFetcher
-  );
+  const url = "/api/manage/admin/standard-answer";
+  const swrResponse = useSWR<StandardAnswer[]>(url, errorHandlingFetcher);
 
   return {
     ...swrResponse,
-    refreshStandardAnswers: () => mutate(SWR_KEYS.standardAnswers),
+    refreshStandardAnswers: () => mutate(url),
   };
 };

web/src/app/ee/admin/theme/page.tsx

@@ -15,7 +15,6 @@ import { Formik, Form } from "formik";
 import * as Yup from "yup";
 import { EnterpriseSettings } from "@/interfaces/settings";
 import { mutate } from "swr";
-import { SWR_KEYS } from "@/lib/swr-keys";
 
 const route = ADMIN_ROUTES.THEME;
 
@@ -55,7 +54,7 @@ export default function ThemePage() {
       }),
     });
     if (response.ok) {
-      await mutate(SWR_KEYS.enterpriseSettings);
+      await mutate("/api/enterprise-settings");
       return true;
     } else {
       const errorMsg = (await response.json()).detail;

web/src/hooks/useAdminUsers.ts

@@ -4,8 +4,7 @@ import { useCallback } from "react";
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
 import { NEXT_PUBLIC_CLOUD_ENABLED } from "@/lib/constants";
-import { SWR_KEYS } from "@/lib/swr-keys";
-import { UserStatus } from "@/lib/types";
+import { AccountType, UserStatus } from "@/lib/types";
 import type { UserRole, InvitedUserSnapshot } from "@/lib/types";
 import type {
   UserRow,
@@ -20,6 +19,7 @@ interface FullUserSnapshot {
   id: string;
   email: string;
   role: UserRole;
+  account_type: AccountType;
   is_active: boolean;
   password_configured: boolean;
   personal_name: string | null;
@@ -76,7 +76,10 @@ export default function useAdminUsers() {
     isLoading: acceptedLoading,
     error: acceptedError,
     mutate: acceptedMutate,
-  } = useSWR<FullUserSnapshot[]>(SWR_KEYS.acceptedUsers, errorHandlingFetcher);
+  } = useSWR<FullUserSnapshot[]>(
+    "/api/manage/users/accepted/all",
+    errorHandlingFetcher
+  );
 
   const {
     data: invitedData,
@@ -84,7 +87,7 @@ export default function useAdminUsers() {
     error: invitedError,
     mutate: invitedMutate,
   } = useSWR<InvitedUserSnapshot[]>(
-    SWR_KEYS.invitedUsers,
+    "/api/manage/users/invited",
     errorHandlingFetcher
   );
 
@@ -94,7 +97,7 @@ export default function useAdminUsers() {
     error: requestedError,
     mutate: requestedMutate,
   } = useSWR<InvitedUserSnapshot[]>(
-    NEXT_PUBLIC_CLOUD_ENABLED ? SWR_KEYS.pendingTenantUsers : null,
+    NEXT_PUBLIC_CLOUD_ENABLED ? "/api/tenants/users/pending" : null,
     errorHandlingFetcher
   );
 

web/src/hooks/useCCPairs.ts

@@ -3,7 +3,6 @@
 import useSWR from "swr";
 import { CCPairBasicInfo } from "@/lib/types";
 import { errorHandlingFetcher } from "@/lib/fetcher";
-import { SWR_KEYS } from "@/lib/swr-keys";
 
 /**
  * Hook for fetching connector-credential pairs (CC Pairs).
@@ -69,7 +68,7 @@ import { SWR_KEYS } from "@/lib/swr-keys";
  */
 export default function useCCPairs(enabled: boolean = true) {
   const { data, error, isLoading, mutate } = useSWR<CCPairBasicInfo[]>(
-    enabled ? SWR_KEYS.connectorStatus : null,
+    enabled ? "/api/manage/connector-status" : null,
     errorHandlingFetcher
   );
 

web/src/hooks/useGroups.ts

@@ -5,7 +5,6 @@ import { errorHandlingFetcher } from "@/lib/fetcher";
 import { UserGroup } from "@/lib/types";
 import { useContext } from "react";
 import { SettingsContext } from "@/providers/SettingsProvider";
-import { SWR_KEYS } from "@/lib/swr-keys";
 
 /**
  * Fetches all user groups in the organization.
@@ -44,12 +43,13 @@ export default function useGroups() {
     combinedSettings &&
     combinedSettings.enterpriseSettings !== null;
 
+  const GROUPS_URL = "/api/manage/admin/user-group";
   const { data, error, isLoading } = useSWR<UserGroup[]>(
-    isPaidEnterpriseFeaturesEnabled ? SWR_KEYS.adminUserGroups : null,
+    isPaidEnterpriseFeaturesEnabled ? GROUPS_URL : null,
     errorHandlingFetcher
   );
 
-  const refreshGroups = () => mutate(SWR_KEYS.adminUserGroups);
+  const refreshGroups = () => mutate(GROUPS_URL);
 
   if (settingsLoading) {
     return {

web/src/hooks/useHookExecutionLogs.ts

@@ -1,6 +1,6 @@
 import useSWR from "swr";
-import { fetchExecutionLogs } from "@/ee/refresh-pages/admin/HooksPage/svc";
-import type { HookExecutionRecord } from "@/ee/refresh-pages/admin/HooksPage/interfaces";
+import { fetchExecutionLogs } from "@/refresh-pages/admin/HooksPage/svc";
+import type { HookExecutionRecord } from "@/refresh-pages/admin/HooksPage/interfaces";
 
 const ONE_HOUR_MS = 60 * 60 * 1000;
 const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;

web/src/hooks/useHookSpecs.ts

@@ -2,12 +2,11 @@
 
 import useSWR from "swr";
 import { errorHandlingFetcher } from "@/lib/fetcher";
-import { HookPointMeta } from "@/ee/refresh-pages/admin/HooksPage/interfaces";
-import { SWR_KEYS } from "@/lib/swr-keys";
+import { HookPointMeta } from "@/refresh-pages/admin/HooksPage/interfaces";
 
 export function useHookSpecs() {
   const { data, isLoading, error } = useSWR<HookPointMeta[]>(
-    SWR_KEYS.hookSpecs,
+    "/api/admin/hooks/specs",
     errorHandlingFetcher,
     { revalidateOnFocus: false }
   );