fix(fe): editing an LLM provider uses the global default model

AGENTS.md

@@ -167,7 +167,284 @@ web/
 
 ## Frontend Standards
 
-Frontend standards for the `web/` and `desktop/` projects live in `web/AGENTS.md`.
+### 1. Import Standards
+
+**Always use absolute imports with the `@` prefix.**
+
+**Reason:** Moving files around becomes easier since you don't also have to update those import statements. This makes modifications to the codebase much nicer.
+
+```typescript
+// ✅ Good
+import { Button } from "@/components/ui/button";
+import { useAuth } from "@/hooks/useAuth";
+import { Text } from "@/refresh-components/texts/Text";
+
+// ❌ Bad
+import { Button } from "../../../components/ui/button";
+import { useAuth } from "./hooks/useAuth";
+```
+
+### 2. React Component Functions
+
+**Prefer regular functions over arrow functions for React components.**
+
+**Reason:** Functions just become easier to read.
+
+```typescript
+// ✅ Good
+function UserProfile({ userId }: UserProfileProps) {
+  return <div>User Profile</div>
+}
+
+// ❌ Bad
+const UserProfile = ({ userId }: UserProfileProps) => {
+  return <div>User Profile</div>
+}
+```
+
+### 3. Props Interface Extraction
+
+**Extract prop types into their own interface definitions.**
+
+**Reason:** Functions just become easier to read.
+
+```typescript
+// ✅ Good
+interface UserCardProps {
+  user: User
+  showActions?: boolean
+  onEdit?: (userId: string) => void
+}
+
+function UserCard({ user, showActions = false, onEdit }: UserCardProps) {
+  return <div>User Card</div>
+}
+
+// ❌ Bad
+function UserCard({
+  user,
+  showActions = false,
+  onEdit
+}: {
+  user: User
+  showActions?: boolean
+  onEdit?: (userId: string) => void
+}) {
+  return <div>User Card</div>
+}
+```
+
+### 4. Spacing Guidelines
+
+**Prefer padding over margins for spacing.**
+
+**Reason:** We want to consolidate usage to paddings instead of margins.
+
+```typescript
+// ✅ Good
+<div className="p-4 space-y-2">
+  <div className="p-2">Content</div>
+</div>
+
+// ❌ Bad
+<div className="m-4 space-y-2">
+  <div className="m-2">Content</div>
+</div>
+```
+
+### 5. Tailwind Dark Mode
+
+**Strictly forbid using the `dark:` modifier in Tailwind classes, except for logo icon handling.**
+
+**Reason:** The `colors.css` file already, VERY CAREFULLY, defines what the exact opposite colour of each light-mode colour is. Overriding this behaviour is VERY bad and will lead to horrible UI breakages.
+
+**Exception:** The `createLogoIcon` helper in `web/src/components/icons/icons.tsx` uses `dark:` modifiers (`dark:invert`, `dark:hidden`, `dark:block`) to handle third-party logo icons that cannot automatically adapt through `colors.css`. This is the ONLY acceptable use of dark mode modifiers.
+
+```typescript
+// ✅ Good - Standard components use `tailwind-themes/tailwind.config.js` / `src/app/css/colors.css`
+<div className="bg-background-neutral-03 text-text-02">
+  Content
+</div>
+
+// ✅ Good - Logo icons with dark mode handling via createLogoIcon
+export const GithubIcon = createLogoIcon(githubLightIcon, {
+  monochromatic: true,  // Will apply dark:invert internally
+});
+
+export const GitbookIcon = createLogoIcon(gitbookLightIcon, {
+  darkSrc: gitbookDarkIcon,  // Will use dark:hidden/dark:block internally
+});
+
+// ❌ Bad - Manual dark mode overrides
+<div className="bg-white dark:bg-black text-black dark:text-white">
+  Content
+</div>
+```
+
+### 6. Class Name Utilities
+
+**Use the `cn` utility instead of raw string formatting for classNames.**
+
+**Reason:** `cn`s are easier to read. They also allow for more complex types (i.e., string-arrays) to get formatted properly (it flattens each element in that string array down). As a result, it can allow things such as conditionals (i.e., `myCondition && "some-tailwind-class"`, which evaluates to `false` when `myCondition` is `false`) to get filtered out.
+
+```typescript
+import { cn } from '@/lib/utils'
+
+// ✅ Good
+<div className={cn(
+  'base-class',
+  isActive && 'active-class',
+  className
+)}>
+  Content
+</div>
+
+// ❌ Bad
+<div className={`base-class ${isActive ? 'active-class' : ''} ${className}`}>
+  Content
+</div>
+```
+
+### 7. Custom Hooks Organization
+
+**Follow a "hook-per-file" layout. Each hook should live in its own file within `web/src/hooks`.**
+
+**Reason:** This is just a layout preference. Keeps code clean.
+
+```typescript
+// web/src/hooks/useUserData.ts
+export function useUserData(userId: string) {
+  // hook implementation
+}
+
+// web/src/hooks/useLocalStorage.ts
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  // hook implementation
+}
+```
+
+### 8. Icon Usage
+
+**ONLY use icons from the `web/src/icons` directory. Do NOT use icons from `react-icons`, `lucide`, or other external libraries.**
+
+**Reason:** We have a very carefully curated selection of icons that match our Onyx guidelines. We do NOT want to muddy those up with different aesthetic stylings.
+
+```typescript
+// ✅ Good
+import SvgX from "@/icons/x";
+import SvgMoreHorizontal from "@/icons/more-horizontal";
+
+// ❌ Bad
+import { User } from "lucide-react";
+import { FiSearch } from "react-icons/fi";
+```
+
+**Missing Icons**: If an icon is needed but doesn't exist in the `web/src/icons` directory, import it from Figma using the Figma MCP tool and add it to the icons directory.
+If you need help with this step, reach out to `raunak@onyx.app`.
+
+### 9. Text Rendering
+
+**Prefer using the `refresh-components/texts/Text` component for all text rendering. Avoid "naked" text nodes.**
+
+**Reason:** The `Text` component is fully compliant with the stylings provided in Figma. It provides easy utilities to specify the text-colour and font-size in the form of flags. Super duper easy.
+
+```typescript
+// ✅ Good
+import { Text } from '@/refresh-components/texts/Text'
+
+function UserCard({ name }: { name: string }) {
+  return (
+    <Text
+      {/* The `text03` flag makes the text it renders to be coloured the 3rd-scale grey */}
+      text03
+      {/* The `mainAction` flag makes the text it renders to be "main-action" font + line-height + weightage, as described in the Figma */}
+      mainAction
+    >
+      {name}
+    </Text>
+  )
+}
+
+// ❌ Bad
+function UserCard({ name }: { name: string }) {
+  return (
+    <div>
+      <h2>{name}</h2>
+      <p>User details</p>
+    </div>
+  )
+}
+```
+
+### 10. Component Usage
+
+**Heavily avoid raw HTML input components. Always use components from the `web/src/refresh-components` or `web/lib/opal/src` directory.**
+
+**Reason:** We've put in a lot of effort to unify the components that are rendered in the Onyx app. Using raw components breaks the entire UI of the application, and leaves it in a muddier state than before.
+
+```typescript
+// ✅ Good
+import Button from '@/refresh-components/buttons/Button'
+import InputTypeIn from '@/refresh-components/inputs/InputTypeIn'
+import SvgPlusCircle from '@/icons/plus-circle'
+
+function ContactForm() {
+  return (
+    <form>
+      <InputTypeIn placeholder="Search..." />
+      <Button type="submit" leftIcon={SvgPlusCircle}>Submit</Button>
+    </form>
+  )
+}
+
+// ❌ Bad
+function ContactForm() {
+  return (
+    <form>
+      <input placeholder="Name" />
+      <textarea placeholder="Message" />
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+### 11. Colors
+
+**Always use custom overrides for colors and borders rather than built in Tailwind CSS colors. These overrides live in `web/tailwind-themes/tailwind.config.js`.**
+
+**Reason:** Our custom color system uses CSS variables that automatically handle dark mode and maintain design consistency across the app. Standard Tailwind colors bypass this system.
+
+**Available color categories:**
+
+- **Text:** `text-01` through `text-05`, `text-inverted-XX`
+- **Backgrounds:** `background-neutral-XX`, `background-tint-XX` (and inverted variants)
+- **Borders:** `border-01` through `border-05`, `border-inverted-XX`
+- **Actions:** `action-link-XX`, `action-danger-XX`
+- **Status:** `status-info-XX`, `status-success-XX`, `status-warning-XX`, `status-error-XX`
+- **Theme:** `theme-primary-XX`, `theme-red-XX`, `theme-blue-XX`, etc.
+
+```typescript
+// ✅ Good - Use custom Onyx color classes
+<div className="bg-background-neutral-01 border border-border-02" />
+<div className="bg-background-tint-02 border border-border-01" />
+<div className="bg-status-success-01" />
+<div className="bg-action-link-01" />
+<div className="bg-theme-primary-05" />
+
+// ❌ Bad - Do NOT use standard Tailwind colors
+<div className="bg-gray-100 border border-gray-300 text-gray-600" />
+<div className="bg-white border border-slate-200" />
+<div className="bg-green-100 text-green-700" />
+<div className="bg-blue-100 text-blue-600" />
+<div className="bg-indigo-500" />
+```
+
+### 12. Data Fetching
+
+**Prefer using `useSWR` for data fetching. Data should generally be fetched on the client side. Components that need data should display a loader / placeholder while waiting for that data. Prefer loading data within the component that needs it rather than at the top level and passing it down.**
+
+**Reason:** Client side fetching allows us to load the skeleton of the page without waiting for data to load, leading to a snappier UX. Loading data where needed reduces dependencies between a component and its parent component(s).
 
 ## Database & Migrations
 

backend/Dockerfile

@@ -47,8 +47,6 @@ RUN apt-get update && \
         gcc \
         nano \
         vim \
-        # Install procps so kubernetes exec sessions can use ps aux for debugging
-        procps \
         libjemalloc2 \
         && \
     rm -rf /var/lib/apt/lists/* && \

backend/onyx/connectors/google_utils/google_utils.py

@@ -157,7 +157,9 @@ def _execute_single_retrieval(
             logger.error(f"Error executing request: {e}")
             raise e
         elif _is_rate_limit_error(e):
-            results = _execute_with_retry(retrieval_function(**request_kwargs))
+            results = _execute_with_retry(
+                lambda: retrieval_function(**request_kwargs).execute()
+            )
         elif e.resp.status == 404 or e.resp.status == 403:
             if continue_on_404_or_403:
                 logger.debug(f"Error executing request: {e}")

backend/onyx/document_index/opensearch/client.py

@@ -1,4 +1,3 @@
-import json
 import logging
 import time
 from contextlib import AbstractContextManager
@@ -1063,7 +1062,7 @@ class OpenSearchIndexClient(OpenSearchClient):
                 f"Body: {get_new_body_without_vectors(body)}\n"
                 f"Search pipeline ID: {search_pipeline_id}\n"
                 f"Phase took: {phase_took}\n"
-                f"Profile: {json.dumps(profile, indent=2)}\n"
+                f"Profile: {profile}\n"
             )
         if timed_out:
             error_str = f"OpenSearch client error: Search timed out for index {self._index_name}."

backend/onyx/document_index/opensearch/opensearch_document_index.py

@@ -950,86 +950,7 @@ class OpenSearchDocumentIndex(DocumentIndex):
             search_pipeline_id=normalization_pipeline_name,
         )
 
-        # Good place for a breakpoint to inspect the search hits if you have
-        # "explain" enabled.
-        inference_chunks_uncleaned: list[InferenceChunkUncleaned] = [
-            _convert_retrieved_opensearch_chunk_to_inference_chunk_uncleaned(
-                search_hit.document_chunk, search_hit.score, search_hit.match_highlights
-            )
-            for search_hit in search_hits
-        ]
-        inference_chunks: list[InferenceChunk] = cleanup_content_for_chunks(
-            inference_chunks_uncleaned
-        )
-
-        return inference_chunks
-
-    def keyword_retrieval(
-        self,
-        query: str,
-        filters: IndexFilters,
-        num_to_retrieve: int,
-    ) -> list[InferenceChunk]:
-        logger.debug(
-            f"[OpenSearchDocumentIndex] Keyword retrieving {num_to_retrieve} chunks for index {self._index_name}."
-        )
-        query_body = DocumentQuery.get_keyword_search_query(
-            query_text=query,
-            num_hits=num_to_retrieve,
-            tenant_state=self._tenant_state,
-            # NOTE: Index filters includes metadata tags which were filtered
-            # for invalid unicode at indexing time. In theory it would be
-            # ideal to do filtering here as well, in practice we never did
-            # that in the Vespa codepath and have not seen issues in
-            # production, so we deliberately conform to the existing logic
-            # in order to not unknowningly introduce a possible bug.
-            index_filters=filters,
-            include_hidden=False,
-        )
-        search_hits: list[SearchHit[DocumentChunkWithoutVectors]] = self._client.search(
-            body=query_body,
-            search_pipeline_id=None,
-        )
-
-        inference_chunks_uncleaned: list[InferenceChunkUncleaned] = [
-            _convert_retrieved_opensearch_chunk_to_inference_chunk_uncleaned(
-                search_hit.document_chunk, search_hit.score, search_hit.match_highlights
-            )
-            for search_hit in search_hits
-        ]
-        inference_chunks: list[InferenceChunk] = cleanup_content_for_chunks(
-            inference_chunks_uncleaned
-        )
-
-        return inference_chunks
-
-    def semantic_retrieval(
-        self,
-        query_embedding: Embedding,
-        filters: IndexFilters,
-        num_to_retrieve: int,
-    ) -> list[InferenceChunk]:
-        logger.debug(
-            f"[OpenSearchDocumentIndex] Semantic retrieving {num_to_retrieve} chunks for index {self._index_name}."
-        )
-        query_body = DocumentQuery.get_semantic_search_query(
-            query_embedding=query_embedding,
-            num_hits=num_to_retrieve,
-            tenant_state=self._tenant_state,
-            # NOTE: Index filters includes metadata tags which were filtered
-            # for invalid unicode at indexing time. In theory it would be
-            # ideal to do filtering here as well, in practice we never did
-            # that in the Vespa codepath and have not seen issues in
-            # production, so we deliberately conform to the existing logic
-            # in order to not unknowningly introduce a possible bug.
-            index_filters=filters,
-            include_hidden=False,
-        )
-        search_hits: list[SearchHit[DocumentChunkWithoutVectors]] = self._client.search(
-            body=query_body,
-            search_pipeline_id=None,
-        )
-
+        # Good place for a breakpoint to inspect the search hits if you have "explain" enabled.
         inference_chunks_uncleaned: list[InferenceChunkUncleaned] = [
             _convert_retrieved_opensearch_chunk_to_inference_chunk_uncleaned(
                 search_hit.document_chunk, search_hit.score, search_hit.match_highlights

backend/onyx/document_index/opensearch/search.py

@@ -404,170 +404,12 @@ class DocumentQuery:
                 DocumentQuery._get_match_highlights_configuration()
             )
 
-        # Explain is for scoring breakdowns. Setting this significantly
-        # increases query latency.
+        # Explain is for scoring breakdowns.
         if OPENSEARCH_EXPLAIN_ENABLED:
             final_hybrid_search_body["explain"] = True
 
         return final_hybrid_search_body
 
-    @staticmethod
-    def get_keyword_search_query(
-        query_text: str,
-        num_hits: int,
-        tenant_state: TenantState,
-        index_filters: IndexFilters,
-        include_hidden: bool,
-    ) -> dict[str, Any]:
-        """Returns a final keyword search query.
-
-        This query can be directly supplied to the OpenSearch client.
-
-        Args:
-            query_text: The text to query for.
-            num_hits: The final number of hits to return.
-            tenant_state: Tenant state containing the tenant ID.
-            index_filters: Filters for the keyword search query.
-            include_hidden: Whether to include hidden documents.
-
-        Returns:
-            A dictionary representing the final keyword search query.
-        """
-        if num_hits > DEFAULT_OPENSEARCH_MAX_RESULT_WINDOW:
-            raise ValueError(
-                f"Bug: num_hits ({num_hits}) is greater than the current maximum allowed "
-                f"result window ({DEFAULT_OPENSEARCH_MAX_RESULT_WINDOW})."
-            )
-
-        keyword_search_filters = DocumentQuery._get_search_filters(
-            tenant_state=tenant_state,
-            include_hidden=include_hidden,
-            # TODO(andrei): We've done no filtering for PUBLIC_DOC_PAT up to
-            # now. This should not cause any issues but it can introduce
-            # redundant filters in queries that may affect performance.
-            access_control_list=index_filters.access_control_list,
-            source_types=index_filters.source_type or [],
-            tags=index_filters.tags or [],
-            document_sets=index_filters.document_set or [],
-            user_file_ids=index_filters.user_file_ids or [],
-            project_id=index_filters.project_id,
-            persona_id=index_filters.persona_id,
-            time_cutoff=index_filters.time_cutoff,
-            min_chunk_index=None,
-            max_chunk_index=None,
-            attached_document_ids=index_filters.attached_document_ids,
-            hierarchy_node_ids=index_filters.hierarchy_node_ids,
-        )
-
-        keyword_search_query = (
-            DocumentQuery._get_title_content_combined_keyword_search_query(
-                query_text, search_filters=keyword_search_filters
-            )
-        )
-
-        final_keyword_search_query: dict[str, Any] = {
-            "query": keyword_search_query,
-            "size": num_hits,
-            "timeout": f"{DEFAULT_OPENSEARCH_QUERY_TIMEOUT_S}s",
-            # Exclude retrieving the vector fields in order to save on
-            # retrieval cost as we don't need them upstream.
-            "_source": {
-                "excludes": [TITLE_VECTOR_FIELD_NAME, CONTENT_VECTOR_FIELD_NAME]
-            },
-        }
-
-        if not OPENSEARCH_MATCH_HIGHLIGHTS_DISABLED:
-            final_keyword_search_query["highlight"] = (
-                DocumentQuery._get_match_highlights_configuration()
-            )
-
-        if not OPENSEARCH_PROFILING_DISABLED:
-            final_keyword_search_query["profile"] = True
-
-        # Explain is for scoring breakdowns. Setting this significantly
-        # increases query latency.
-        if OPENSEARCH_EXPLAIN_ENABLED:
-            final_keyword_search_query["explain"] = True
-
-        return final_keyword_search_query
-
-    @staticmethod
-    def get_semantic_search_query(
-        query_embedding: list[float],
-        num_hits: int,
-        tenant_state: TenantState,
-        index_filters: IndexFilters,
-        include_hidden: bool,
-    ) -> dict[str, Any]:
-        """Returns a final semantic search query.
-
-        This query can be directly supplied to the OpenSearch client.
-
-        Args:
-            query_embedding: The vector embedding of the text to query for.
-            num_hits: The final number of hits to return.
-            tenant_state: Tenant state containing the tenant ID.
-            index_filters: Filters for the semantic search query.
-            include_hidden: Whether to include hidden documents.
-
-        Returns:
-            A dictionary representing the final semantic search query.
-        """
-        if num_hits > DEFAULT_OPENSEARCH_MAX_RESULT_WINDOW:
-            raise ValueError(
-                f"Bug: num_hits ({num_hits}) is greater than the current maximum allowed "
-                f"result window ({DEFAULT_OPENSEARCH_MAX_RESULT_WINDOW})."
-            )
-
-        semantic_search_filters = DocumentQuery._get_search_filters(
-            tenant_state=tenant_state,
-            include_hidden=include_hidden,
-            # TODO(andrei): We've done no filtering for PUBLIC_DOC_PAT up to
-            # now. This should not cause any issues but it can introduce
-            # redundant filters in queries that may affect performance.
-            access_control_list=index_filters.access_control_list,
-            source_types=index_filters.source_type or [],
-            tags=index_filters.tags or [],
-            document_sets=index_filters.document_set or [],
-            user_file_ids=index_filters.user_file_ids or [],
-            project_id=index_filters.project_id,
-            persona_id=index_filters.persona_id,
-            time_cutoff=index_filters.time_cutoff,
-            min_chunk_index=None,
-            max_chunk_index=None,
-            attached_document_ids=index_filters.attached_document_ids,
-            hierarchy_node_ids=index_filters.hierarchy_node_ids,
-        )
-
-        semantic_search_query = (
-            DocumentQuery._get_content_vector_similarity_search_query(
-                query_embedding,
-                vector_candidates=num_hits,
-                search_filters=semantic_search_filters,
-            )
-        )
-
-        final_semantic_search_query: dict[str, Any] = {
-            "query": semantic_search_query,
-            "size": num_hits,
-            "timeout": f"{DEFAULT_OPENSEARCH_QUERY_TIMEOUT_S}s",
-            # Exclude retrieving the vector fields in order to save on
-            # retrieval cost as we don't need them upstream.
-            "_source": {
-                "excludes": [TITLE_VECTOR_FIELD_NAME, CONTENT_VECTOR_FIELD_NAME]
-            },
-        }
-
-        if not OPENSEARCH_PROFILING_DISABLED:
-            final_semantic_search_query["profile"] = True
-
-        # Explain is for scoring breakdowns. Setting this significantly
-        # increases query latency.
-        if OPENSEARCH_EXPLAIN_ENABLED:
-            final_semantic_search_query["explain"] = True
-
-        return final_semantic_search_query
-
     @staticmethod
     def get_random_search_query(
         tenant_state: TenantState,
@@ -739,9 +581,8 @@ class DocumentQuery:
     def _get_content_vector_similarity_search_query(
         query_vector: list[float],
         vector_candidates: int = DEFAULT_NUM_HYBRID_SUBQUERY_CANDIDATES,
-        search_filters: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any]:
-        query = {
+        return {
             "knn": {
                 CONTENT_VECTOR_FIELD_NAME: {
                     "vector": query_vector,
@@ -750,19 +591,11 @@ class DocumentQuery:
             }
         }
 
-        if search_filters is not None:
-            query["knn"][CONTENT_VECTOR_FIELD_NAME]["filter"] = {
-                "bool": {"filter": search_filters}
-            }
-
-        return query
-
     @staticmethod
     def _get_title_content_combined_keyword_search_query(
         query_text: str,
-        search_filters: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any]:
-        query = {
+        return {
             "bool": {
                 "should": [
                     {
@@ -803,19 +636,10 @@ class DocumentQuery:
                             }
                         }
                     },
-                ],
-                # Ensure at least one term from the query is present in the
-                # document. This defaults to 1, unless a filter or must clause
-                # is supplied, in which case it defaults to 0.
-                "minimum_should_match": 1,
+                ]
             }
         }
 
-        if search_filters is not None:
-            query["bool"]["filter"] = search_filters
-
-        return query
-
     @staticmethod
     def _get_search_filters(
         tenant_state: TenantState,

backend/onyx/llm/multi_llm.py

@@ -530,11 +530,6 @@ class LitellmLLM(LLM):
                 ):
                     messages = _strip_tool_content_from_messages(messages)
 
-                # Only pass tool_choice when tools are present — some providers (e.g. Fireworks)
-                # reject requests where tool_choice is explicitly null.
-                if tools and tool_choice is not None:
-                    optional_kwargs["tool_choice"] = tool_choice
-
                 response = litellm.completion(
                     mock_response=get_llm_mock_response() or MOCK_LLM_RESPONSE,
                     model=model,
@@ -543,6 +538,7 @@ class LitellmLLM(LLM):
                     custom_llm_provider=self._custom_llm_provider or None,
                     messages=messages,
                     tools=tools,
+                    tool_choice=tool_choice,
                     stream=stream,
                     temperature=temperature,
                     timeout=timeout_override or self._timeout,

backend/tests/external_dependency_unit/opensearch/test_opensearch_client.py

@@ -1640,275 +1640,3 @@ class TestOpenSearchClient:
                     for k in DocumentChunkWithoutVectors.model_fields
                 }
             )
-
-    def test_keyword_search(
-        self,
-        test_client: OpenSearchIndexClient,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """
-        Tests keyword search with filters for ACL, hidden documents, and tenant
-        isolation.
-        """
-        # Precondition.
-        _patch_global_tenant_state(monkeypatch, True)
-        _patch_opensearch_match_highlights_disabled(monkeypatch, False)
-        tenant_x = TenantState(tenant_id="tenant-x", multitenant=True)
-        tenant_y = TenantState(tenant_id="tenant-y", multitenant=True)
-        mappings = DocumentSchema.get_document_schema(
-            vector_dimension=128, multitenant=tenant_x.multitenant
-        )
-        settings = DocumentSchema.get_index_settings_based_on_environment()
-        test_client.create_index(mappings=mappings, settings=settings)
-
-        # Index documents with different public/hidden and tenant states.
-        docs = {
-            "public-doc": _create_test_document_chunk(
-                document_id="public-doc",
-                chunk_index=0,
-                content="Public document content",
-                hidden=False,
-                tenant_state=tenant_x,
-            ),
-            "hidden-doc": _create_test_document_chunk(
-                document_id="hidden-doc",
-                chunk_index=0,
-                content="Hidden document content, spooky",
-                hidden=True,
-                tenant_state=tenant_x,
-            ),
-            "private-doc-user-a": _create_test_document_chunk(
-                document_id="private-doc-user-a",
-                chunk_index=0,
-                content="Private document content, btw my SSN is 123-45-6789",
-                hidden=False,
-                tenant_state=tenant_x,
-                document_access=DocumentAccess.build(
-                    user_emails=["user-a@example.com"],
-                    user_groups=[],
-                    external_user_emails=[],
-                    external_user_group_ids=[],
-                    is_public=False,
-                ),
-            ),
-            # Tests that we don't return documents that don't match keywords at
-            # all, even if they match filters.
-            "private-but-not-relevant-doc-user-a": _create_test_document_chunk(
-                document_id="private-but-not-relevant-doc-user-a",
-                chunk_index=0,
-                content="This text should not match the query at all",
-                hidden=False,
-                tenant_state=tenant_x,
-                document_access=DocumentAccess.build(
-                    user_emails=["user-a@example.com"],
-                    user_groups=[],
-                    external_user_emails=[],
-                    external_user_group_ids=[],
-                    is_public=False,
-                ),
-            ),
-            "private-doc-user-b": _create_test_document_chunk(
-                document_id="private-doc-user-b",
-                chunk_index=0,
-                content="Private document content, btw my SSN is 987-65-4321",
-                hidden=False,
-                tenant_state=tenant_x,
-                document_access=DocumentAccess.build(
-                    user_emails=["user-b@example.com"],
-                    user_groups=[],
-                    external_user_emails=[],
-                    external_user_group_ids=[],
-                    is_public=False,
-                ),
-            ),
-            "should-not-exist-from-tenant-x-pov": _create_test_document_chunk(
-                document_id="should-not-exist-from-tenant-x-pov",
-                chunk_index=0,
-                content="This is an entirely different tenant, x should never see this",
-                # Make this as permissive as possible to exercise tenant
-                # isolation.
-                hidden=False,
-                tenant_state=tenant_y,
-            ),
-        }
-        for doc in docs.values():
-            test_client.index_document(document=doc, tenant_state=doc.tenant_id)
-
-        # Refresh index to make documents searchable.
-        test_client.refresh_index()
-
-        # Should not match private-but-not-relevant-doc-user-a.
-        query_text = "document content"
-        search_body = DocumentQuery.get_keyword_search_query(
-            query_text=query_text,
-            num_hits=5,
-            tenant_state=tenant_x,
-            # The user should only be able to see their private docs. tenant_id
-            # in this object is not relevant.
-            index_filters=IndexFilters(
-                access_control_list=[prefix_user_email("user-a@example.com")],
-                tenant_id=None,
-            ),
-            include_hidden=False,
-        )
-
-        # Under test.
-        results = test_client.search(body=search_body, search_pipeline_id=None)
-
-        # Postcondition.
-        # Should only get the public, non-hidden document, and the private
-        # document for which the user has access.
-        assert len(results) == 2
-        # This should be the highest-ranked result, as a higher percentage of
-        # the content matches the query.
-        assert results[0].document_chunk.document_id == "public-doc"
-        # Make sure the chunk contents are preserved.
-        assert results[0].document_chunk == DocumentChunkWithoutVectors(
-            **{
-                k: getattr(docs["public-doc"], k)
-                for k in DocumentChunkWithoutVectors.model_fields
-            }
-        )
-        # Make sure score reporting seems reasonable (it should not be None
-        # or 0).
-        assert results[0].score
-        # Make sure there is some kind of match highlight.
-        assert results[0].match_highlights.get(CONTENT_FIELD_NAME, [])
-        # Same for the second result.
-        assert results[1].document_chunk.document_id == "private-doc-user-a"
-        assert results[1].document_chunk == DocumentChunkWithoutVectors(
-            **{
-                k: getattr(docs["private-doc-user-a"], k)
-                for k in DocumentChunkWithoutVectors.model_fields
-            }
-        )
-        assert results[1].score
-        assert results[1].match_highlights.get(CONTENT_FIELD_NAME, [])
-        assert results[1].score < results[0].score
-
-    def test_semantic_search(
-        self,
-        test_client: OpenSearchIndexClient,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """
-        Tests semantic search with filters for ACL, hidden documents, and tenant
-        isolation.
-        """
-        # Precondition.
-        _patch_global_tenant_state(monkeypatch, True)
-        tenant_x = TenantState(tenant_id="tenant-x", multitenant=True)
-        tenant_y = TenantState(tenant_id="tenant-y", multitenant=True)
-        mappings = DocumentSchema.get_document_schema(
-            vector_dimension=128, multitenant=tenant_x.multitenant
-        )
-        settings = DocumentSchema.get_index_settings_based_on_environment()
-        test_client.create_index(mappings=mappings, settings=settings)
-
-        # Index documents with different public/hidden and tenant states.
-        docs = {
-            "public-doc": _create_test_document_chunk(
-                document_id="public-doc",
-                chunk_index=0,
-                content="Public document content",
-                hidden=False,
-                tenant_state=tenant_x,
-                # Make this identical to the query vector to test that this
-                # result is returned first.
-                content_vector=_generate_test_vector(0.6),
-            ),
-            "hidden-doc": _create_test_document_chunk(
-                document_id="hidden-doc",
-                chunk_index=0,
-                content="Hidden document content, spooky",
-                hidden=True,
-                tenant_state=tenant_x,
-            ),
-            "private-doc-user-a": _create_test_document_chunk(
-                document_id="private-doc-user-a",
-                chunk_index=0,
-                content="Private document content, btw my SSN is 123-45-6789",
-                hidden=False,
-                tenant_state=tenant_x,
-                document_access=DocumentAccess.build(
-                    user_emails=["user-a@example.com"],
-                    user_groups=[],
-                    external_user_emails=[],
-                    external_user_group_ids=[],
-                    is_public=False,
-                ),
-                # Make this different from the query vector to test that this
-                # result is returned second.
-                content_vector=_generate_test_vector(0.5),
-            ),
-            "private-doc-user-b": _create_test_document_chunk(
-                document_id="private-doc-user-b",
-                chunk_index=0,
-                content="Private document content, btw my SSN is 987-65-4321",
-                hidden=False,
-                tenant_state=tenant_x,
-                document_access=DocumentAccess.build(
-                    user_emails=["user-b@example.com"],
-                    user_groups=[],
-                    external_user_emails=[],
-                    external_user_group_ids=[],
-                    is_public=False,
-                ),
-            ),
-            "should-not-exist-from-tenant-x-pov": _create_test_document_chunk(
-                document_id="should-not-exist-from-tenant-x-pov",
-                chunk_index=0,
-                content="This is an entirely different tenant, x should never see this",
-                # Make this as permissive as possible to exercise tenant
-                # isolation.
-                hidden=False,
-                tenant_state=tenant_y,
-            ),
-        }
-        for doc in docs.values():
-            test_client.index_document(document=doc, tenant_state=doc.tenant_id)
-
-        # Refresh index to make documents searchable.
-        test_client.refresh_index()
-
-        query_vector = _generate_test_vector(0.6)
-        search_body = DocumentQuery.get_semantic_search_query(
-            query_embedding=query_vector,
-            num_hits=5,
-            tenant_state=tenant_x,
-            # The user should only be able to see their private docs. tenant_id
-            # in this object is not relevant.
-            index_filters=IndexFilters(
-                access_control_list=[prefix_user_email("user-a@example.com")],
-                tenant_id=None,
-            ),
-            include_hidden=False,
-        )
-
-        # Under test.
-        results = test_client.search(body=search_body, search_pipeline_id=None)
-
-        # Postcondition.
-        # Should only get the public, non-hidden document, and the private
-        # document for which the user has access.
-        assert len(results) == 2
-        # We explicitly expect this to be the highest-ranked result.
-        assert results[0].document_chunk.document_id == "public-doc"
-        # Make sure the chunk contents are preserved.
-        assert results[0].document_chunk == DocumentChunkWithoutVectors(
-            **{
-                k: getattr(docs["public-doc"], k)
-                for k in DocumentChunkWithoutVectors.model_fields
-            }
-        )
-        assert results[0].score == 1.0
-        # Same for the second result.
-        assert results[1].document_chunk.document_id == "private-doc-user-a"
-        assert results[1].document_chunk == DocumentChunkWithoutVectors(
-            **{
-                k: getattr(docs["private-doc-user-a"], k)
-                for k in DocumentChunkWithoutVectors.model_fields
-            }
-        )
-        assert results[1].score
-        assert 0.0 < results[1].score < 1.0

backend/tests/unit/onyx/llm/test_multi_llm.py

@@ -256,6 +256,7 @@ def test_multiple_tool_calls(default_multi_llm: LitellmLLM) -> None:
                 {"role": "user", "content": "What's the weather and time in New York?"}
             ],
             tools=tools,
+            tool_choice=None,
             stream=True,
             temperature=0.0,  # Default value from GEN_AI_TEMPERATURE
             timeout=30,
@@ -411,6 +412,7 @@ def test_multiple_tool_calls_streaming(default_multi_llm: LitellmLLM) -> None:
                 {"role": "user", "content": "What's the weather and time in New York?"}
             ],
             tools=tools,
+            tool_choice=None,
             stream=True,
             temperature=0.0,  # Default value from GEN_AI_TEMPERATURE
             timeout=30,
@@ -1429,36 +1431,3 @@ def test_strip_tool_content_merges_consecutive_tool_results() -> None:
     assert "sunny 72F" in merged
     assert "tc_2" in merged
     assert "headline news" in merged
-
-
-def test_no_tool_choice_sent_when_no_tools(default_multi_llm: LitellmLLM) -> None:
-    """Regression test for providers (e.g. Fireworks) that reject tool_choice=null.
-
-    When no tools are provided, tool_choice must not be forwarded to
-    litellm.completion() at all — not even as None.
-    """
-    messages: LanguageModelInput = [UserMessage(content="Hello!")]
-
-    mock_stream_chunks = [
-        litellm.ModelResponse(
-            id="chatcmpl-123",
-            choices=[
-                litellm.Choices(
-                    delta=_create_delta(role="assistant", content="Hello!"),
-                    finish_reason="stop",
-                    index=0,
-                )
-            ],
-            model="gpt-3.5-turbo",
-        ),
-    ]
-
-    with patch("litellm.completion") as mock_completion:
-        mock_completion.return_value = mock_stream_chunks
-
-        default_multi_llm.invoke(messages, tools=None)
-
-        _, kwargs = mock_completion.call_args
-        assert (
-            "tool_choice" not in kwargs
-        ), "tool_choice must not be sent to providers when no tools are provided"

cubic.yaml

@@ -1,93 +0,0 @@
-# yaml-language-server: $schema=https://cubic.dev/schema/cubic-repository-config.schema.json
-version: 1
-
-reviews:
-  enabled: true
-  sensitivity: medium
-  incremental_commits: true
-  check_drafts: false
-
-  custom_instructions: |
-    Use explicit type annotations for variables to enhance code clarity,
-    especially when moving type hints around in the code.
-
-    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.
-
-    Reference these files for additional context:
-    - `contributing_guides/best_practices.md` — Best practices for contributing to the codebase
-    - `CLAUDE.md` — Project instructions and coding standards
-    - `backend/alembic/README.md` — Migration guidance, including multi-tenant migration behavior
-    - `deployment/helm/charts/onyx/values-lite.yaml` — Lite deployment Helm values and service assumptions
-    - `deployment/docker_compose/docker-compose.onyx-lite.yml` — Lite deployment Docker Compose overlay and disabled service behavior
-
-  ignore:
-    files:
-      - greptile.json
-      - cubic.yaml
-
-  custom_rules:
-    - name: TODO format
-      description: >
-        Whenever a TODO is added, there must always be an associated name or
-        ticket in the style of TODO(name): ... or TODO(1234): ...
-
-    - name: Frontend standards
-      description: >
-        For frontend changes, enforce all standards described in the
-        web/AGENTS.md file.
-      include:
-        - web/**
-        - desktop/**
-
-    - name: No debugging code
-      description: >
-        Remove temporary debugging code before merging to production,
-        especially tenant-specific debugging logs.
-
-    - name: No hardcoded booleans
-      description: >
-        When hardcoding a boolean variable to a constant value, remove the
-        variable entirely and clean up all places where it's used rather than
-        just setting it to a constant.
-
-    - name: Multi-tenant awareness
-      description: >
-        Code changes must consider both multi-tenant and single-tenant
-        deployments. In multi-tenant mode, preserve tenant isolation, ensure
-        tenant context is propagated correctly, and avoid assumptions that only
-        hold for a single shared schema or globally shared state. In
-        single-tenant mode, avoid introducing unnecessary tenant-specific
-        requirements or cloud-only control-plane dependencies.
-
-    - name: Onyx lite compatibility
-      description: >
-        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.
-
-    - name: OnyxError over HTTPException
-      description: >
-        Never raise HTTPException directly in business code. Use
-        `raise OnyxError(OnyxErrorCode.XXX, "message")` from
-        `onyx.error_handling.exceptions`. A global FastAPI exception handler
-        converts OnyxError into structured JSON responses with
-        {"error_code": "...", "detail": "..."}. Error codes are defined in
-        `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors
-        with dynamic HTTP status codes, use `status_code_override`:
-        `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`.
-      include:
-        - backend/**/*.py
-
-issues:
-  fix_with_cubic_buttons: true
-  pr_comment_fixes: true
-  fix_commits_to_pr: true

deployment/docker_compose/install.sh

@@ -207,16 +207,6 @@ prompt_yn_or_default() {
     fi
 }
 
-confirm_action() {
-    local description="$1"
-    prompt_yn_or_default "Install ${description}? (Y/n) [default: Y] " "Y"
-    if [[ "$REPLY" =~ ^[Nn] ]]; then
-        print_warning "Skipping: ${description}"
-        return 1
-    fi
-    return 0
-}
-
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -405,11 +395,6 @@ fi
 
 if ! command -v docker &> /dev/null; then
     if [[ "$OSTYPE" == "linux-gnu"* ]] || [[ -n "${WSL_DISTRO_NAME:-}" ]]; then
-        print_info "Docker is required but not installed."
-        if ! confirm_action "Docker Engine"; then
-            print_error "Docker is required to run Onyx."
-            exit 1
-        fi
         install_docker_linux
         if ! command -v docker &> /dev/null; then
             print_error "Docker installation failed."
@@ -426,11 +411,7 @@ if command -v docker &> /dev/null \
     && ! command -v docker-compose &> /dev/null \
     && { [[ "$OSTYPE" == "linux-gnu"* ]] || [[ -n "${WSL_DISTRO_NAME:-}" ]]; }; then
 
-    print_info "Docker Compose is required but not installed."
-    if ! confirm_action "Docker Compose plugin"; then
-        print_error "Docker Compose is required to run Onyx."
-        exit 1
-    fi
+    print_info "Docker Compose not found — installing plugin..."
     COMPOSE_ARCH="$(uname -m)"
     COMPOSE_URL="https://github.com/docker/compose/releases/latest/download/docker-compose-linux-${COMPOSE_ARCH}"
     COMPOSE_DIR="/usr/local/lib/docker/cli-plugins"
@@ -581,31 +562,10 @@ version_compare() {
 
 # Check Docker daemon
 if ! docker info &> /dev/null; then
-    if [[ "$OSTYPE" == "darwin"* ]]; then
-        print_info "Docker daemon is not running. Starting Docker Desktop..."
-        open -a Docker
-        # Wait up to 120 seconds for Docker to be ready
-        DOCKER_WAIT=0
-        DOCKER_MAX_WAIT=120
-        while ! docker info &> /dev/null; do
-            if [ $DOCKER_WAIT -ge $DOCKER_MAX_WAIT ]; then
-                print_error "Docker Desktop did not start within ${DOCKER_MAX_WAIT} seconds."
-                print_info "Please start Docker Desktop manually and re-run this script."
-                exit 1
-            fi
-            printf "\r\033[KWaiting for Docker Desktop to start... (%ds)" "$DOCKER_WAIT"
-            sleep 2
-            DOCKER_WAIT=$((DOCKER_WAIT + 2))
-        done
-        echo ""
-        print_success "Docker Desktop is now running"
-    else
-        print_error "Docker daemon is not running. Please start Docker."
-        exit 1
-    fi
-else
-    print_success "Docker daemon is running"
+    print_error "Docker daemon is not running. Please start Docker."
+    exit 1
 fi
+print_success "Docker daemon is running"
 
 # Check Docker resources
 print_step "Verifying Docker resources"
@@ -785,7 +745,6 @@ print_success "All configuration files ready"
 # Set up deployment configuration
 print_step "Setting up deployment configs"
 ENV_FILE="${INSTALL_ROOT}/deployment/.env"
-ENV_TEMPLATE="${INSTALL_ROOT}/deployment/env.template"
 # Check if services are already running
 if [ -d "${INSTALL_ROOT}/deployment" ] && [ -f "${INSTALL_ROOT}/deployment/docker-compose.yml" ]; then
     # Determine compose command
@@ -1125,25 +1084,6 @@ else
     USE_LATEST=false
 fi
 
-# For pinned version tags, re-download config files from that tag so the
-# compose file matches the images being pulled (the initial download used main).
-if [[ "$USE_LATEST" = false ]] && [[ "$USE_LOCAL_FILES" = false ]]; then
-    PINNED_BASE="https://raw.githubusercontent.com/onyx-dot-app/onyx/${CURRENT_IMAGE_TAG}/deployment"
-    print_info "Fetching config files matching tag ${CURRENT_IMAGE_TAG}..."
-    if download_file "${PINNED_BASE}/docker_compose/docker-compose.yml" "${INSTALL_ROOT}/deployment/docker-compose.yml" 2>/dev/null; then
-        download_file "${PINNED_BASE}/data/nginx/app.conf.template" "${INSTALL_ROOT}/data/nginx/app.conf.template" 2>/dev/null || true
-        download_file "${PINNED_BASE}/data/nginx/run-nginx.sh" "${INSTALL_ROOT}/data/nginx/run-nginx.sh" 2>/dev/null || true
-        chmod +x "${INSTALL_ROOT}/data/nginx/run-nginx.sh"
-        if [[ "$LITE_MODE" = true ]]; then
-            download_file "${PINNED_BASE}/docker_compose/${LITE_COMPOSE_FILE}" \
-                "${INSTALL_ROOT}/deployment/${LITE_COMPOSE_FILE}" 2>/dev/null || true
-        fi
-        print_success "Config files updated to match ${CURRENT_IMAGE_TAG}"
-    else
-        print_warning "Tag ${CURRENT_IMAGE_TAG} not found on GitHub — using main branch configs"
-    fi
-fi
-
 # Pull Docker images with reduced output
 print_step "Pulling Docker images"
 print_info "This may take several minutes depending on your internet connection..."

desktop/AGENTS.md

@@ -1 +0,0 @@
-../web/AGENTS.md

desktop/CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

greptile.json

@@ -65,7 +65,7 @@
         },
         {
           "scope": ["web/**"],
-          "rule": "For frontend changes (changes that touch the /web directory), make sure to enforce all standards described in the web/AGENTS.md file."
+          "rule": "For frontend changes (changes that touch the /web directory), make sure to enforce all standards described in the web/STANDARDS.md file."
         },
         {
           "scope": [],
@@ -85,7 +85,7 @@
         },
         {
           "scope": ["backend/**/*.py"],
-          "rule": "Never raise HTTPException directly in business code. Use `raise OnyxError(OnyxErrorCode.XXX, \"message\")` from `onyx.error_handling.exceptions`. A global FastAPI exception handler converts OnyxError into structured JSON responses with {\"error_code\": \"...\", \"detail\": \"...\"}. Error codes are defined in `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors with dynamic HTTP status codes, use `status_code_override`: `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`."
+          "rule": "Never raise HTTPException directly in business code. Use `raise OnyxError(OnyxErrorCode.XXX, \"message\")` from `onyx.error_handling.exceptions`. A global FastAPI exception handler converts OnyxError into structured JSON responses with {\"error_code\": \"...\", \"message\": \"...\"}. Error codes are defined in `onyx.error_handling.error_codes.OnyxErrorCode`. For upstream errors with dynamic HTTP status codes, use `status_code_override`: `raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_override=upstream_status)`."
         }
       ],
       "files": [

tools/ods/cmd/run-ci.go

@@ -17,7 +17,6 @@ import (
 type RunCIOptions struct {
 	DryRun bool
 	Yes    bool
-	Rerun  bool
 }
 
 // NewRunCICommand creates a new run-ci command
@@ -50,7 +49,6 @@ Example usage:
 
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "Perform all local operations but skip pushing to remote and creating PRs")
 	cmd.Flags().BoolVar(&opts.Yes, "yes", false, "Skip confirmation prompts and automatically proceed")
-	cmd.Flags().BoolVar(&opts.Rerun, "rerun", false, "Update an existing CI PR with the latest fork changes to re-trigger CI")
 
 	return cmd
 }
@@ -109,44 +107,19 @@ func runCI(cmd *cobra.Command, args []string, opts *RunCIOptions) {
 		log.Fatalf("PR #%s is not from a fork - CI should already run automatically", prNumber)
 	}
 
-	// Create the CI branch
-	ciBranch := fmt.Sprintf("run-ci/%s", prNumber)
-	prTitle := fmt.Sprintf("chore: [Running GitHub actions for #%s]", prNumber)
-	prBody := fmt.Sprintf("This PR runs GitHub Actions CI for #%s.\n\n- [x] Override Linear Check\n\n**This PR should be closed (not merged) after CI completes.**", prNumber)
-
-	// Check if a CI PR already exists for this branch
-	existingPRURL, err := findExistingCIPR(ciBranch)
-	if err != nil {
-		log.Fatalf("Failed to check for existing CI PR: %v", err)
-	}
-
-	if existingPRURL != "" && !opts.Rerun {
-		log.Infof("A CI PR already exists for #%s: %s", prNumber, existingPRURL)
-		log.Info("Run with --rerun to update it with the latest fork changes and re-trigger CI.")
-		return
-	}
-
-	if opts.Rerun && existingPRURL == "" {
-		log.Warn("--rerun was specified but no existing open CI PR was found. A new PR will be created.")
-	}
-
-	if existingPRURL != "" && opts.Rerun {
-		log.Infof("Existing CI PR found: %s", existingPRURL)
-		log.Info("Will update the CI branch with the latest fork changes to re-trigger CI.")
-	}
-
 	// Confirm before proceeding
 	if !opts.Yes {
-		action := "Create CI branch"
-		if existingPRURL != "" {
-			action = "Update existing CI branch"
-		}
-		if !prompt.Confirm(fmt.Sprintf("%s for PR #%s? (yes/no): ", action, prNumber)) {
+		if !prompt.Confirm(fmt.Sprintf("Create CI branch for PR #%s? (yes/no): ", prNumber)) {
 			log.Info("Exiting...")
 			return
 		}
 	}
 
+	// Create the CI branch
+	ciBranch := fmt.Sprintf("run-ci/%s", prNumber)
+	prTitle := fmt.Sprintf("chore: [Running GitHub actions for #%s]", prNumber)
+	prBody := fmt.Sprintf("This PR runs GitHub Actions CI for #%s.\n\n- [x] Override Linear Check\n\n**This PR should be closed (not merged) after CI completes.**", prNumber)
+
 	// Fetch the fork's branch
 	if forkRepo == "" {
 		log.Fatalf("Could not determine fork repository - headRepositoryOwner or headRepository.name is empty")
@@ -185,11 +158,7 @@ func runCI(cmd *cobra.Command, args []string, opts *RunCIOptions) {
 
 	if opts.DryRun {
 		log.Warnf("[DRY RUN] Would push CI branch: %s", ciBranch)
-		if existingPRURL == "" {
-			log.Warnf("[DRY RUN] Would create PR: %s", prTitle)
-		} else {
-			log.Warnf("[DRY RUN] Would update existing PR: %s", existingPRURL)
-		}
+		log.Warnf("[DRY RUN] Would create PR: %s", prTitle)
 		// Switch back to original branch
 		if err := git.RunCommand("switch", "--quiet", originalBranch); err != nil {
 			log.Warnf("Failed to switch back to original branch: %v", err)
@@ -207,17 +176,6 @@ func runCI(cmd *cobra.Command, args []string, opts *RunCIOptions) {
 		log.Fatalf("Failed to push CI branch: %v", err)
 	}
 
-	if existingPRURL != "" {
-		// PR already exists - force push is enough to re-trigger CI
-		log.Infof("Switching back to original branch: %s", originalBranch)
-		if err := git.RunCommand("switch", "--quiet", originalBranch); err != nil {
-			log.Warnf("Failed to switch back to original branch: %v", err)
-		}
-		log.Infof("CI PR updated successfully: %s", existingPRURL)
-		log.Info("The force push will re-trigger CI. Remember to close (not merge) this PR after CI completes!")
-		return
-	}
-
 	// Create PR using GitHub CLI
 	log.Info("Creating PR...")
 	prURL, err := createCIPR(ciBranch, prInfo.BaseRefName, prTitle, prBody)
@@ -259,39 +217,6 @@ func getPRInfo(prNumber string) (*PRInfo, error) {
 	return &prInfo, nil
 }
 
-// findExistingCIPR checks if an open PR already exists for the given CI branch.
-// Returns the PR URL if found, or empty string if not.
-func findExistingCIPR(headBranch string) (string, error) {
-	cmd := exec.Command("gh", "pr", "list",
-		"--head", headBranch,
-		"--state", "open",
-		"--json", "url",
-	)
-	output, err := cmd.Output()
-	if err != nil {
-		if exitErr, ok := err.(*exec.ExitError); ok {
-			return "", fmt.Errorf("%w: %s", err, string(exitErr.Stderr))
-		}
-		return "", err
-	}
-
-	var prs []struct {
-		URL string `json:"url"`
-	}
-	if err := json.Unmarshal(output, &prs); err != nil {
-		log.Debugf("Failed to parse PR list JSON: %v (raw: %s)", err, string(output))
-		return "", fmt.Errorf("failed to parse PR list: %w", err)
-	}
-
-	if len(prs) == 0 {
-		log.Debugf("No existing open PRs found for branch %s", headBranch)
-		return "", nil
-	}
-
-	log.Debugf("Found existing PR for branch %s: %s", headBranch, prs[0].URL)
-	return prs[0].URL, nil
-}
-
 // createCIPR creates a pull request for CI using the GitHub CLI
 func createCIPR(headBranch, baseBranch, title, body string) (string, error) {
 	cmd := exec.Command("gh", "pr", "create",

web/AGENTS.md

@@ -1,540 +0,0 @@
-# Frontend Standards
-
-This file is the single source of truth for frontend coding standards across all Onyx frontend
-projects (including, but not limited to, `/web`, `/desktop`).
-
-# Components
-
-UI components are spread across several directories while the codebase migrates to Opal:
-
-- **`web/lib/opal/src/`** — The Opal design system. Preferred for all new components.
-- **`web/src/refresh-components/`** — Production components not yet migrated to Opal.
-- **`web/src/sections/`** — Feature-specific composite components (cards, modals, etc.).
-- **`web/src/layouts/`** — Page-level layout components (settings pages, etc.).
-
-**Do NOT use anything from `web/src/components/`** — this directory contains legacy components
-that are being phased out. Always prefer Opal first; fall back to `refresh-components` only for
-components not yet available in Opal.
-
-## Opal Layouts (`lib/opal/src/layouts/`)
-
-All layout primitives are imported from `@opal/layouts`. They handle sizing, font selection, icon
-alignment, and optional inline editing.
-
-```typescript
-import { Content, ContentAction, IllustrationContent } from "@opal/layouts";
-```
-
-### Content
-
-**Use this for any combination of icon + title + description.**
-
-A two-axis layout component that automatically routes to the correct internal layout
-(`ContentXl`, `ContentLg`, `ContentMd`, `ContentSm`) based on `sizePreset` and `variant`:
-
-| sizePreset | variant | Routes to | Layout |
-|---|---|---|---|
-| `headline` / `section` | `heading` | `ContentXl` | Icon on top (flex-col) |
-| `headline` / `section` | `section` | `ContentLg` | Icon inline (flex-row) |
-| `main-content` / `main-ui` / `secondary` | `section` / `heading` | `ContentMd` | Compact inline |
-| `main-content` / `main-ui` / `secondary` | `body` | `ContentSm` | Body text layout |
-
-```typescript
-<Content
-  sizePreset="main-ui"
-  variant="section"
-  icon={SvgSettings}
-  title="Settings"
-  description="Manage your preferences"
-/>
-```
-
-### ContentAction
-
-**Use this when a Content block needs right-side actions** (buttons, badges, icons, etc.).
-
-Wraps `Content` and adds a `rightChildren` slot. Accepts all `Content` props plus:
-- `rightChildren`: `ReactNode` — actions rendered on the right
-- `paddingVariant`: `SizeVariant` — controls outer padding
-
-```typescript
-<ContentAction
-  sizePreset="main-ui"
-  variant="section"
-  icon={SvgUser}
-  title="John Doe"
-  description="Admin"
-  rightChildren={<Button icon={SvgEdit}>Edit</Button>}
-/>
-```
-
-### IllustrationContent
-
-**Use this for empty states, error pages, and informational placeholders.**
-
-A vertically-stacked, center-aligned layout that pairs a large illustration (7.5rem x 7.5rem)
-with a title and optional description.
-
-```typescript
-import SvgNoResult from "@opal/illustrations/no-result";
-
-<IllustrationContent
-  illustration={SvgNoResult}
-  title="No results found"
-  description="Try adjusting your search or filters."
-/>
-```
-
-Props:
-- `illustration`: `IconFunctionComponent` — optional, from `@opal/illustrations`
-- `title`: `string` — required
-- `description`: `string` — optional
-
-## Settings Page Layout (`src/layouts/settings-layouts.tsx`)
-
-**Use this for all admin/settings pages.** Provides a standardized layout with scroll-aware
-sticky headers, centered content containers, and responsive behavior.
-
-```typescript
-import SettingsLayouts from "@/layouts/settings-layouts";
-
-function MySettingsPage() {
-  return (
-    <SettingsLayouts.Root>
-      <SettingsLayouts.Header
-        icon={SvgSettings}
-        title="Account Settings"
-        description="Manage your account preferences"
-        rightChildren={<Button>Save</Button>}
-      >
-        <InputTypeIn placeholder="Search settings..." />
-      </SettingsLayouts.Header>
-
-      <SettingsLayouts.Body>
-        <Card>Settings content here</Card>
-      </SettingsLayouts.Body>
-    </SettingsLayouts.Root>
-  );
-}
-```
-
-Sub-components:
-- **`SettingsLayouts.Root`** — Wrapper with centered, scrollable container. Width options:
-  `"sm"` (672px), `"sm-md"` (752px), `"md"` (872px, default), `"lg"` (992px), `"full"` (100%).
-- **`SettingsLayouts.Header`** — Sticky header with icon, title, description, optional
-  `rightChildren` actions, optional `children` below (e.g., search/filter), optional `backButton`,
-  and optional `separator`. Automatically shows a scroll shadow when scrolled.
-- **`SettingsLayouts.Body`** — Content container with consistent padding and vertical spacing.
-
-## Cards (`src/sections/cards/`)
-
-**When building a card that displays information about a specific entity (agent, document set,
-file, connector, etc.), add it to `web/src/sections/cards/`.**
-
-Each card is a self-contained component focused on a single entity type. Cards typically include
-entity identification (name, avatar, icon), summary information, and quick actions.
-
-```typescript
-import AgentCard from "@/sections/cards/AgentCard";
-import DocumentSetCard from "@/sections/cards/DocumentSetCard";
-import FileCard from "@/sections/cards/FileCard";
-```
-
-Guidelines:
-- One card per entity type — keep card-specific logic within the card component.
-- Cards should be reusable across different pages and contexts.
-- Use shared components from `@opal/components`, `@opal/layouts`, and `@/refresh-components`
-  inside cards — do not duplicate layout or styling logic.
-
-## Button (`components/buttons/button/`)
-
-**Always use the Opal `Button`.** Do not use raw `<button>` elements.
-
-Built on `Interactive.Stateless` > `Interactive.Container`, so it inherits the full color/state
-system automatically.
-
-```typescript
-import { Button } from "@opal/components/buttons/button/components";
-
-// Labeled button
-<Button variant="default" prominence="primary" icon={SvgPlus}>
-  Create
-</Button>
-
-// Icon-only button (omit children)
-<Button variant="default" prominence="tertiary" icon={SvgTrash} size="sm" />
-```
-
-Key props:
-- `variant`: `"default"` | `"action"` | `"danger"` | `"none"`
-- `prominence`: `"primary"` | `"secondary"` | `"tertiary"` | `"internal"`
-- `size`: `"lg"` | `"md"` | `"sm"` | `"xs"` | `"2xs"` | `"fit"`
-- `icon`, `rightIcon`, `children`, `disabled`, `href`, `tooltip`
-
-## Core Primitives (`core/`)
-
-The `core/` directory contains the lowest-level building blocks that power all Opal components.
-**Most code should not interface with these directly** — use higher-level components like `Button`,
-`Content`, and `ContentAction` instead. These are documented here for understanding, not everyday use.
-
-### Interactive (`core/interactive/`)
-
-The foundational layer for all clickable/interactive surfaces. Defines the color matrix for
-hover, active, and disabled states.
-
-- **`Interactive.Stateless`** — Color system for stateless elements (buttons, links). Applies
-  variant/prominence/state combinations via CSS custom properties.
-- **`Interactive.Stateful`** — Color system for stateful elements (toggles, sidebar items, selects).
-  Uses `state` (`"empty"` | `"filled"` | `"selected"`) instead of prominence.
-- **`Interactive.Container`** — Structural box providing height, rounding, padding, and border.
-  Shared by both Stateless and Stateful. Renders as `<div>`, `<button>`, or `<Link>` depending
-  on context.
-- **`Interactive.Foldable`** — Zero-width collapsible wrapper with CSS grid animation.
-
-### Disabled (`core/disabled/`)
-
-Propagates disabled state via React context. `Interactive.Stateless` and `Interactive.Stateful`
-consume this automatically, so wrapping a subtree in `<Disabled disabled={true}>` disables all
-interactive descendants.
-
-### Hoverable (`core/animations/`)
-
-A standardized way to provide "opacity-100 on hover" behavior. Instead of manually wiring
-`opacity-0 group-hover:opacity-100` with Tailwind, use `Hoverable` for consistent, coordinated
-hover-to-reveal patterns.
-
-- **`Hoverable.Root`** — Wraps a hover group. Tracks mouse enter/leave and broadcasts hover
-  state to descendants via a per-group React context.
-- **`Hoverable.Item`** — Marks an element that should appear on hover. Supports two modes:
-  - **Group mode** (`group` prop provided): visibility driven by a matching `Hoverable.Root`
-    ancestor. Throws if no matching Root is found.
-  - **Local mode** (`group` omitted): uses CSS `:hover` on the item itself.
-
-```typescript
-import { Hoverable } from "@opal/core";
-
-// Group mode — hovering anywhere on the row reveals the trash icon
-<Hoverable.Root group="row">
-  <div className="flex items-center gap-2">
-    <span>Row content</span>
-    <Hoverable.Item group="row" variant="opacity-on-hover">
-      <SvgTrash />
-    </Hoverable.Item>
-  </div>
-</Hoverable.Root>
-
-// Local mode — hovering the item itself reveals it
-<Hoverable.Item variant="opacity-on-hover">
-  <SvgTrash />
-</Hoverable.Item>
-```
-
-# Best Practices
-
-## 1. Tailwind Dark Mode
-
-**Strictly forbid using the `dark:` modifier in Tailwind classes, except for logo icon handling.**
-
-**Reason:** The `colors.css` file already, VERY CAREFULLY, defines what the exact opposite colour of each light-mode colour is. Overriding this behaviour is VERY bad and will lead to horrible UI breakages.
-
-**Exception:** The `createLogoIcon` helper in `web/src/components/icons/icons.tsx` uses `dark:` modifiers (`dark:invert`, `dark:hidden`, `dark:block`) to handle third-party logo icons that cannot automatically adapt through `colors.css`. This is the ONLY acceptable use of dark mode modifiers.
-
-```typescript
-// ✅ Good - Standard components use `tailwind-themes/tailwind.config.js` / `src/app/css/colors.css`
-<div className="bg-background-neutral-03 text-text-02">
-  Content
-</div>
-
-// ✅ Good - Logo icons with dark mode handling via createLogoIcon
-export const GithubIcon = createLogoIcon(githubLightIcon, {
-  monochromatic: true,  // Will apply dark:invert internally
-});
-
-export const GitbookIcon = createLogoIcon(gitbookLightIcon, {
-  darkSrc: gitbookDarkIcon,  // Will use dark:hidden/dark:block internally
-});
-
-// ❌ Bad - Manual dark mode overrides
-<div className="bg-white dark:bg-black text-black dark:text-white">
-  Content
-</div>
-```
-
-## 2. Icon Usage
-
-**ONLY use icons from the `web/src/icons` directory. Do NOT use icons from `react-icons`, `lucide`, or other external libraries.**
-
-**Reason:** We have a very carefully curated selection of icons that match our Onyx guidelines. We do NOT want to muddy those up with different aesthetic stylings.
-
-```typescript
-// ✅ Good
-import SvgX from "@/icons/x";
-import SvgMoreHorizontal from "@/icons/more-horizontal";
-
-// ❌ Bad
-import { User } from "lucide-react";
-import { FiSearch } from "react-icons/fi";
-```
-
-**Missing Icons**: If an icon is needed but doesn't exist in the `web/src/icons` directory, import it from Figma using the Figma MCP tool and add it to the icons directory.
-If you need help with this step, reach out to `raunak@onyx.app`.
-
-## 3. Text Rendering
-
-**Prefer using the `refresh-components/texts/Text` component for all text rendering. Avoid "naked" text nodes.**
-
-**Reason:** The `Text` component is fully compliant with the stylings provided in Figma. It provides easy utilities to specify the text-colour and font-size in the form of flags. Super duper easy.
-
-```typescript
-// ✅ Good
-import { Text } from '@/refresh-components/texts/Text'
-
-function UserCard({ name }: { name: string }) {
-  return (
-    <Text
-      {/* The `text03` flag makes the text it renders to be coloured the 3rd-scale grey */}
-      text03
-      {/* The `mainAction` flag makes the text it renders to be "main-action" font + line-height + weightage, as described in the Figma */}
-      mainAction
-    >
-      {name}
-    </Text>
-  )
-}
-
-// ❌ Bad
-function UserCard({ name }: { name: string }) {
-  return (
-    <div>
-      <h2>{name}</h2>
-      <p>User details</p>
-    </div>
-  )
-}
-```
-
-## 4. Component Usage
-
-**Heavily avoid raw HTML input components. Always use components from the `web/src/refresh-components` or `web/lib/opal/src` directory.**
-
-**Reason:** We've put in a lot of effort to unify the components that are rendered in the Onyx app. Using raw components breaks the entire UI of the application, and leaves it in a muddier state than before.
-
-```typescript
-// ✅ Good
-import Button from '@/refresh-components/buttons/Button'
-import InputTypeIn from '@/refresh-components/inputs/InputTypeIn'
-import SvgPlusCircle from '@/icons/plus-circle'
-
-function ContactForm() {
-  return (
-    <form>
-      <InputTypeIn placeholder="Search..." />
-      <Button type="submit" leftIcon={SvgPlusCircle}>Submit</Button>
-    </form>
-  )
-}
-
-// ❌ Bad
-function ContactForm() {
-  return (
-    <form>
-      <input placeholder="Name" />
-      <textarea placeholder="Message" />
-      <button type="submit">Submit</button>
-    </form>
-  )
-}
-```
-
-## 5. Colors
-
-**Always use custom overrides for colors and borders rather than built in Tailwind CSS colors. These overrides live in `web/tailwind-themes/tailwind.config.js`.**
-
-**Reason:** Our custom color system uses CSS variables that automatically handle dark mode and maintain design consistency across the app. Standard Tailwind colors bypass this system.
-
-**Available color categories:**
-
-- **Text:** `text-01` through `text-05`, `text-inverted-XX`
-- **Backgrounds:** `background-neutral-XX`, `background-tint-XX` (and inverted variants)
-- **Borders:** `border-01` through `border-05`, `border-inverted-XX`
-- **Actions:** `action-link-XX`, `action-danger-XX`
-- **Status:** `status-info-XX`, `status-success-XX`, `status-warning-XX`, `status-error-XX`
-- **Theme:** `theme-primary-XX`, `theme-red-XX`, `theme-blue-XX`, etc.
-
-```typescript
-// ✅ Good - Use custom Onyx color classes
-<div className="bg-background-neutral-01 border border-border-02" />
-<div className="bg-background-tint-02 border border-border-01" />
-<div className="bg-status-success-01" />
-<div className="bg-action-link-01" />
-<div className="bg-theme-primary-05" />
-
-// ❌ Bad - Do NOT use standard Tailwind colors
-<div className="bg-gray-100 border border-gray-300 text-gray-600" />
-<div className="bg-white border border-slate-200" />
-<div className="bg-green-100 text-green-700" />
-<div className="bg-blue-100 text-blue-600" />
-<div className="bg-indigo-500" />
-```
-
-## 6. Data Fetching
-
-**Prefer using `useSWR` for data fetching. Data should generally be fetched on the client side. Components that need data should display a loader / placeholder while waiting for that data. Prefer loading data within the component that needs it rather than at the top level and passing it down.**
-
-**Reason:** Client side fetching allows us to load the skeleton of the page without waiting for data to load, leading to a snappier UX. Loading data where needed reduces dependencies between a component and its parent component(s).
-
-# Stylistic Preferences
-
-## 1. Import Standards
-
-**Always use absolute imports with the `@` prefix.**
-
-**Reason:** Moving files around becomes easier since you don't also have to update those import statements. This makes modifications to the codebase much nicer.
-
-```typescript
-// ✅ Good
-import { Button } from "@/components/ui/button";
-import { useAuth } from "@/hooks/useAuth";
-import { Text } from "@/refresh-components/texts/Text";
-
-// ❌ Bad
-import { Button } from "../../../components/ui/button";
-import { useAuth } from "./hooks/useAuth";
-```
-
-## 2. React Component Functions
-
-**Prefer regular functions over arrow functions for React components.**
-
-**Reason:** Functions just become easier to read.
-
-```typescript
-// ✅ Good
-function UserProfile({ userId }: UserProfileProps) {
-  return <div>User Profile</div>
-}
-
-// ❌ Bad
-const UserProfile = ({ userId }: UserProfileProps) => {
-  return <div>User Profile</div>
-}
-```
-
-## 3. Props Interface Extraction
-
-**Extract prop types into their own interface definitions. Keep prop interfaces in the same file
-as the component they belong to. Non-prop types (shared models, API response shapes, enums, etc.)
-should be placed in a co-located `interfaces.ts` file.**
-
-**Reason:** Prop interfaces are tightly coupled to their component and rarely imported elsewhere,
-so co-location keeps things simple. Shared types belong in `interfaces.ts` so they can be
-imported without pulling in component code.
-
-```typescript
-// ✅ Good — props interface in the same file as the component
-// UserCard.tsx
-interface UserCardProps {
-  user: User
-  showActions?: boolean
-  onEdit?: (userId: string) => void
-}
-
-function UserCard({ user, showActions = false, onEdit }: UserCardProps) {
-  return <div>User Card</div>
-}
-
-// ✅ Good — shared types in interfaces.ts
-// interfaces.ts
-export interface User {
-  id: string
-  name: string
-  role: UserRole
-}
-
-export type UserRole = "admin" | "member" | "viewer"
-
-// ❌ Bad — inline prop types
-function UserCard({
-  user,
-  showActions = false,
-  onEdit
-}: {
-  user: User
-  showActions?: boolean
-  onEdit?: (userId: string) => void
-}) {
-  return <div>User Card</div>
-}
-```
-
-## 4. Spacing Guidelines
-
-**Prefer padding over margins for spacing. When a library component exposes a padding prop
-(e.g., `paddingVariant`), use that prop instead of wrapping it in a `<div>` with padding classes.
-If a library component does not expose a padding override and you find yourself adding a wrapper
-div for spacing, consider updating the library component to accept one.**
-
-**Reason:** We want to consolidate usage to paddings instead of margins, and minimize wrapper
-divs that exist solely for spacing.
-
-```typescript
-// ✅ Good — use the component's padding prop
-<ContentAction paddingVariant="md" ... />
-
-// ✅ Good — padding utilities when no component prop exists
-<div className="p-4 space-y-2">
-  <div className="p-2">Content</div>
-</div>
-
-// ❌ Bad — wrapper div just for spacing
-<div className="p-4">
-  <ContentAction ... />
-</div>
-
-// ❌ Bad — margins
-<div className="m-4 space-y-2">
-  <div className="m-2">Content</div>
-</div>
-```
-
-## 5. Class Name Utilities
-
-**Use the `cn` utility instead of raw string formatting for classNames.**
-
-**Reason:** `cn`s are easier to read. They also allow for more complex types (i.e., string-arrays) to get formatted properly (it flattens each element in that string array down). As a result, it can allow things such as conditionals (i.e., `myCondition && "some-tailwind-class"`, which evaluates to `false` when `myCondition` is `false`) to get filtered out.
-
-```typescript
-import { cn } from '@/lib/utils'
-
-// ✅ Good
-<div className={cn(
-  'base-class',
-  isActive && 'active-class',
-  className
-)}>
-  Content
-</div>
-
-// ❌ Bad
-<div className={`base-class ${isActive ? 'active-class' : ''} ${className}`}>
-  Content
-</div>
-```
-
-## 6. Custom Hooks Organization
-
-**Follow a "hook-per-file" layout. Each hook should live in its own file within `web/src/hooks`.**
-
-**Reason:** This is just a layout preference. Keeps code clean.
-
-```typescript
-// web/src/hooks/useUserData.ts
-export function useUserData(userId: string) {
-  // hook implementation
-}
-
-// web/src/hooks/useLocalStorage.ts
-export function useLocalStorage<T>(key: string, initialValue: T) {
-  // hook implementation
-}
-```

web/CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

web/STANDARDS.md

@@ -0,0 +1,281 @@
+# Web Standards
+
+This document outlines the coding standards and best practices for the `web` directory Next.js project.
+
+## 1. Import Standards
+
+**Always use absolute imports with the `@` prefix.**
+
+**Reason:** Moving files around becomes easier since you don't also have to update those import statements. This makes modifications to the codebase much nicer.
+
+```typescript
+// ✅ Good
+import { Button } from "@/components/ui/button";
+import { useAuth } from "@/hooks/useAuth";
+import { Text } from "@/refresh-components/texts/Text";
+
+// ❌ Bad
+import { Button } from "../../../components/ui/button";
+import { useAuth } from "./hooks/useAuth";
+```
+
+## 2. React Component Functions
+
+**Prefer regular functions over arrow functions for React components.**
+
+**Reason:** Functions just become easier to read.
+
+```typescript
+// ✅ Good
+function UserProfile({ userId }: UserProfileProps) {
+  return <div>User Profile</div>
+}
+
+// ❌ Bad
+const UserProfile = ({ userId }: UserProfileProps) => {
+  return <div>User Profile</div>
+}
+```
+
+## 3. Props Interface Extraction
+
+**Extract prop types into their own interface definitions.**
+
+**Reason:** Functions just become easier to read.
+
+```typescript
+// ✅ Good
+interface UserCardProps {
+  user: User
+  showActions?: boolean
+  onEdit?: (userId: string) => void
+}
+
+function UserCard({ user, showActions = false, onEdit }: UserCardProps) {
+  return <div>User Card</div>
+}
+
+// ❌ Bad
+function UserCard({
+  user,
+  showActions = false,
+  onEdit
+}: {
+  user: User
+  showActions?: boolean
+  onEdit?: (userId: string) => void
+}) {
+  return <div>User Card</div>
+}
+```
+
+## 4. Spacing Guidelines
+
+**Prefer padding over margins for spacing.**
+
+**Reason:** We want to consolidate usage to paddings instead of margins.
+
+```typescript
+// ✅ Good
+<div className="p-4 space-y-2">
+  <div className="p-2">Content</div>
+</div>
+
+// ❌ Bad
+<div className="m-4 space-y-2">
+  <div className="m-2">Content</div>
+</div>
+```
+
+## 5. Tailwind Dark Mode
+
+**Strictly forbid using the `dark:` modifier in Tailwind classes, except for logo icon handling.**
+
+**Reason:** The `colors.css` file already, VERY CAREFULLY, defines what the exact opposite colour of each light-mode colour is. Overriding this behaviour is VERY bad and will lead to horrible UI breakages.
+
+**Exception:** The `createLogoIcon` helper in `web/src/components/icons/icons.tsx` uses `dark:` modifiers (`dark:invert`, `dark:hidden`, `dark:block`) to handle third-party logo icons that cannot automatically adapt through `colors.css`. This is the ONLY acceptable use of dark mode modifiers.
+
+```typescript
+// ✅ Good - Standard components use `tailwind-themes/tailwind.config.js` / `src/app/css/colors.css`
+<div className="bg-background-neutral-03 text-text-02">
+  Content
+</div>
+
+// ✅ Good - Logo icons with dark mode handling via createLogoIcon
+export const GithubIcon = createLogoIcon(githubLightIcon, {
+  monochromatic: true,  // Will apply dark:invert internally
+});
+
+export const GitbookIcon = createLogoIcon(gitbookLightIcon, {
+  darkSrc: gitbookDarkIcon,  // Will use dark:hidden/dark:block internally
+});
+
+// ❌ Bad - Manual dark mode overrides
+<div className="bg-white dark:bg-black text-black dark:text-white">
+  Content
+</div>
+```
+
+## 6. Class Name Utilities
+
+**Use the `cn` utility instead of raw string formatting for classNames.**
+
+**Reason:** `cn`s are easier to read. They also allow for more complex types (i.e., string-arrays) to get formatted properly (it flattens each element in that string array down). As a result, it can allow things such as conditionals (i.e., `myCondition && "some-tailwind-class"`, which evaluates to `false` when `myCondition` is `false`) to get filtered out.
+
+```typescript
+import { cn } from '@/lib/utils'
+
+// ✅ Good
+<div className={cn(
+  'base-class',
+  isActive && 'active-class',
+  className
+)}>
+  Content
+</div>
+
+// ❌ Bad
+<div className={`base-class ${isActive ? 'active-class' : ''} ${className}`}>
+  Content
+</div>
+```
+
+## 7. Custom Hooks Organization
+
+**Follow a "hook-per-file" layout. Each hook should live in its own file within `web/src/hooks`.**
+
+**Reason:** This is just a layout preference. Keeps code clean.
+
+```typescript
+// web/src/hooks/useUserData.ts
+export function useUserData(userId: string) {
+  // hook implementation
+}
+
+// web/src/hooks/useLocalStorage.ts
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  // hook implementation
+}
+```
+
+## 8. Icon Usage
+
+**ONLY use icons from the `web/src/icons` directory. Do NOT use icons from `react-icons`, `lucide`, or other external libraries.**
+
+**Reason:** We have a very carefully curated selection of icons that match our Onyx guidelines. We do NOT want to muddy those up with different aesthetic stylings.
+
+```typescript
+// ✅ Good
+import SvgX from "@/icons/x";
+import SvgMoreHorizontal from "@/icons/more-horizontal";
+
+// ❌ Bad
+import { User } from "lucide-react";
+import { FiSearch } from "react-icons/fi";
+```
+
+**Missing Icons**: If an icon is needed but doesn't exist in the `web/src/icons` directory, import it from Figma using the Figma MCP tool and add it to the icons directory.
+If you need help with this step, reach out to `raunak@onyx.app`.
+
+## 9. Text Rendering
+
+**Prefer using the `refresh-components/texts/Text` component for all text rendering. Avoid "naked" text nodes.**
+
+**Reason:** The `Text` component is fully compliant with the stylings provided in Figma. It provides easy utilities to specify the text-colour and font-size in the form of flags. Super duper easy.
+
+```typescript
+// ✅ Good
+import { Text } from '@/refresh-components/texts/Text'
+
+function UserCard({ name }: { name: string }) {
+  return (
+    <Text
+      {/* The `text03` flag makes the text it renders to be coloured the 3rd-scale grey */}
+      text03
+      {/* The `mainAction` flag makes the text it renders to be "main-action" font + line-height + weightage, as described in the Figma */}
+      mainAction
+    >
+      {name}
+    </Text>
+  )
+}
+
+// ❌ Bad
+function UserCard({ name }: { name: string }) {
+  return (
+    <div>
+      <h2>{name}</h2>
+      <p>User details</p>
+    </div>
+  )
+}
+```
+
+## 10. Component Usage
+
+**Heavily avoid raw HTML input components. Always use components from the `web/src/refresh-components` or `web/lib/opal/src` directory.**
+
+**Reason:** We've put in a lot of effort to unify the components that are rendered in the Onyx app. Using raw components breaks the entire UI of the application, and leaves it in a muddier state than before.
+
+```typescript
+// ✅ Good
+import Button from '@/refresh-components/buttons/Button'
+import InputTypeIn from '@/refresh-components/inputs/InputTypeIn'
+import SvgPlusCircle from '@/icons/plus-circle'
+
+function ContactForm() {
+  return (
+    <form>
+      <InputTypeIn placeholder="Search..." />
+      <Button type="submit" leftIcon={SvgPlusCircle}>Submit</Button>
+    </form>
+  )
+}
+
+// ❌ Bad
+function ContactForm() {
+  return (
+    <form>
+      <input placeholder="Name" />
+      <textarea placeholder="Message" />
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+## 11. Colors
+
+**Always use custom overrides for colors and borders rather than built in Tailwind CSS colors. These overrides live in `web/tailwind-themes/tailwind.config.js`.**
+
+**Reason:** Our custom color system uses CSS variables that automatically handle dark mode and maintain design consistency across the app. Standard Tailwind colors bypass this system.
+
+**Available color categories:**
+- **Text:** `text-01` through `text-05`, `text-inverted-XX`
+- **Backgrounds:** `background-neutral-XX`, `background-tint-XX` (and inverted variants)
+- **Borders:** `border-01` through `border-05`, `border-inverted-XX`
+- **Actions:** `action-link-XX`, `action-danger-XX`
+- **Status:** `status-info-XX`, `status-success-XX`, `status-warning-XX`, `status-error-XX`
+- **Theme:** `theme-primary-XX`, `theme-red-XX`, `theme-blue-XX`, etc.
+
+```typescript
+// ✅ Good - Use custom Onyx color classes
+<div className="bg-background-neutral-01 border border-border-02" />
+<div className="bg-background-tint-02 border border-border-01" />
+<div className="bg-status-success-01" />
+<div className="bg-action-link-01" />
+<div className="bg-theme-primary-05" />
+
+// ❌ Bad - Do NOT use standard Tailwind colors
+<div className="bg-gray-100 border border-gray-300 text-gray-600" />
+<div className="bg-white border border-slate-200" />
+<div className="bg-green-100 text-green-700" />
+<div className="bg-blue-100 text-blue-600" />
+<div className="bg-indigo-500" />
+```
+
+## 12. Data Fetching
+
+**Prefer using `useSWR` for data fetching. Data should generally be fetched on the client side. Components that need data should display a loader / placeholder while waiting for that data. Prefer loading data within the component that needs it rather than at the top level and passing it down.**
+
+**Reason:** Client side fetching allows us to load the skeleton of the page without waiting for data to load, leading to a snappier UX. Loading data where needed reduces dependencies between a component and its parent component(s).

web/src/interfaces/llm.ts

@@ -123,6 +123,9 @@ export interface LLMProviderFormProps {
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
 
+  /** The current default model name for this provider (from the global default). */
+  defaultModelName?: string;
+
   // Onboarding-specific (only when variant === "onboarding")
   onboardingState?: OnboardingState;
   onboardingActions?: OnboardingActions;

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

@@ -148,12 +148,14 @@ interface ExistingProviderCardProps {
   provider: LLMProviderView;
   isDefault: boolean;
   isLastProvider: boolean;
+  defaultModelName?: string;
 }
 
 function ExistingProviderCard({
   provider,
   isDefault,
   isLastProvider,
+  defaultModelName,
 }: ExistingProviderCardProps) {
   const { mutate } = useSWRConfig();
   const [isOpen, setIsOpen] = useState(false);
@@ -230,7 +232,12 @@ function ExistingProviderCard({
               </Section>
             }
           />
-          {getModalForExistingProvider(provider, isOpen, setIsOpen)}
+          {getModalForExistingProvider(
+            provider,
+            isOpen,
+            setIsOpen,
+            defaultModelName
+          )}
         </Card>
       </Hoverable.Root>
     </>
@@ -446,6 +453,11 @@ export default function LLMConfigurationPage() {
                     provider={provider}
                     isDefault={defaultText?.provider_id === provider.id}
                     isLastProvider={sortedProviders.length === 1}
+                    defaultModelName={
+                      defaultText?.provider_id === provider.id
+                        ? defaultText.model_name
+                        : undefined
+                    }
                   />
                 ))}
               </div>

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

@@ -35,6 +35,7 @@ export default function AnthropicModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -64,10 +65,15 @@ export default function AnthropicModal({
         default_model_name: DEFAULT_DEFAULT_MODEL_NAME,
       }
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         api_base: existingLlmProvider?.api_base ?? undefined,
         default_model_name:
+          defaultModelName ??
           wellKnownLLMProvider?.recommended_default_model?.name ??
           DEFAULT_DEFAULT_MODEL_NAME,
         is_auto_mode: existingLlmProvider?.is_auto_mode ?? true,

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

@@ -81,6 +81,7 @@ export default function AzureModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -109,7 +110,11 @@ export default function AzureModal({
         default_model_name: "",
       } as AzureModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         target_uri: buildTargetUri(existingLlmProvider),
       };

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

@@ -315,6 +315,7 @@ export default function BedrockModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -351,7 +352,11 @@ export default function BedrockModal({
         },
       } as BedrockModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         custom_config: {
           AWS_REGION_NAME:
             (existingLlmProvider?.custom_config?.AWS_REGION_NAME as string) ??

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

@@ -197,6 +197,7 @@ export default function CustomModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
 }: LLMProviderFormProps) {
@@ -209,7 +210,11 @@ export default function CustomModal({
   const onClose = () => onOpenChange?.(false);
 
   const initialValues = {
-    ...buildDefaultInitialValues(existingLlmProvider),
+    ...buildDefaultInitialValues(
+      existingLlmProvider,
+      undefined,
+      defaultModelName
+    ),
     ...(isOnboarding ? buildOnboardingInitialValues() : {}),
     provider: existingLlmProvider?.provider ?? "",
     model_configurations: existingLlmProvider?.model_configurations.map(

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

@@ -192,6 +192,7 @@ export default function LMStudioForm({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -225,7 +226,11 @@ export default function LMStudioForm({
         },
       } as LMStudioFormValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
         custom_config: {
           LM_STUDIO_API_KEY:

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

@@ -159,6 +159,7 @@ export default function LiteLLMProxyModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -190,7 +191,11 @@ export default function LiteLLMProxyModal({
         default_model_name: "",
       } as LiteLLMProxyModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
       };

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

@@ -212,6 +212,7 @@ export default function OllamaModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -244,7 +245,11 @@ export default function OllamaModal({
         },
       } as OllamaModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
         custom_config: {
           OLLAMA_API_KEY:

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

@@ -35,6 +35,7 @@ export default function OpenAIModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -63,9 +64,14 @@ export default function OpenAIModal({
         default_model_name: DEFAULT_DEFAULT_MODEL_NAME,
       }
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         default_model_name:
+          defaultModelName ??
           wellKnownLLMProvider?.recommended_default_model?.name ??
           DEFAULT_DEFAULT_MODEL_NAME,
         is_auto_mode: existingLlmProvider?.is_auto_mode ?? true,

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

@@ -158,6 +158,7 @@ export default function OpenRouterModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -189,7 +190,11 @@ export default function OpenRouterModal({
         default_model_name: "",
       } as OpenRouterModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         api_key: existingLlmProvider?.api_key ?? "",
         api_base: existingLlmProvider?.api_base ?? DEFAULT_API_BASE,
       };

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

@@ -48,6 +48,7 @@ export default function VertexAIModal({
   shouldMarkAsDefault,
   open,
   onOpenChange,
+  defaultModelName,
   onboardingState,
   onboardingActions,
   llmDescriptor,
@@ -80,8 +81,13 @@ export default function VertexAIModal({
         },
       } as VertexAIModalValues)
     : {
-        ...buildDefaultInitialValues(existingLlmProvider, modelConfigurations),
+        ...buildDefaultInitialValues(
+          existingLlmProvider,
+          modelConfigurations,
+          defaultModelName
+        ),
         default_model_name:
+          defaultModelName ??
           wellKnownLLMProvider?.recommended_default_model?.name ??
           VERTEXAI_DEFAULT_MODEL,
         is_auto_mode: existingLlmProvider?.is_auto_mode ?? true,

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

@@ -22,9 +22,15 @@ function detectIfRealOpenAIProvider(provider: LLMProviderView) {
 export function getModalForExistingProvider(
   provider: LLMProviderView,
   open?: boolean,
-  onOpenChange?: (open: boolean) => void
+  onOpenChange?: (open: boolean) => void,
+  defaultModelName?: string
 ) {
-  const props = { existingLlmProvider: provider, open, onOpenChange };
+  const props = {
+    existingLlmProvider: provider,
+    open,
+    onOpenChange,
+    defaultModelName,
+  };
 
   switch (provider.provider) {
     case LLMProviderName.OPENAI:

web/src/sections/modals/llmConfig/utils.ts

@@ -12,9 +12,11 @@ export const LLM_FORM_CLASS_NAME = "flex flex-col gap-y-4 items-stretch mt-6";
 
 export const buildDefaultInitialValues = (
   existingLlmProvider?: LLMProviderView,
-  modelConfigurations?: ModelConfiguration[]
+  modelConfigurations?: ModelConfiguration[],
+  currentDefaultModelName?: string
 ) => {
   const defaultModelName =
+    currentDefaultModelName ??
     existingLlmProvider?.model_configurations?.[0]?.name ??
     modelConfigurations?.[0]?.name ??
     "";