diff --git a/services/platform/app/components/ui/data-display/collapsible-guide.tsx b/services/platform/app/components/ui/data-display/collapsible-guide.tsx
index 5789fc86a..30a584268 100644
--- a/services/platform/app/components/ui/data-display/collapsible-guide.tsx
+++ b/services/platform/app/components/ui/data-display/collapsible-guide.tsx
@@ -34,7 +34,7 @@ export function CollapsibleGuide({
       <div
         className={cn(
           markdownWrapperStyles,
-          'max-w-none border-t border-border px-3 py-2 text-xs leading-relaxed',
+          'border-border max-w-none border-t px-3 py-2 text-xs leading-relaxed',
         )}
       >
         <ReactMarkdown
@@ -50,6 +50,17 @@ export function CollapsibleGuide({
                 {children}
               </a>
             ),
+            pre: ({ node: _node, className, children, ...rest }) => (
+              <pre
+                {...rest}
+                className={cn(
+                  'bg-muted/60 border-border my-2 overflow-x-auto rounded-md border p-3 font-mono text-[11px] leading-relaxed',
+                  className,
+                )}
+              >
+                {children}
+              </pre>
+            ),
           }}
         >
           {content}
diff --git a/services/platform/app/components/ui/layout/card.tsx b/services/platform/app/components/ui/layout/card.tsx
index 3b8dbbe63..1d67f018a 100644
--- a/services/platform/app/components/ui/layout/card.tsx
+++ b/services/platform/app/components/ui/layout/card.tsx
@@ -29,7 +29,7 @@ export function Card({
   return (
     <div
       className={cn(
-        'rounded-xl border bg-card text-card-foreground shadow-sm',
+        'rounded-lg border bg-card text-card-foreground shadow-sm',
         className,
       )}
     >
diff --git a/services/platform/app/components/ui/navigation/tabs.tsx b/services/platform/app/components/ui/navigation/tabs.tsx
index ebd7db946..8f4fbe2a6 100644
--- a/services/platform/app/components/ui/navigation/tabs.tsx
+++ b/services/platform/app/components/ui/navigation/tabs.tsx
@@ -30,7 +30,7 @@ interface TabsProps {
 }
 
 const listVariants = cva(
-  'scrollbar-hide inline-flex items-center overflow-x-auto text-muted-foreground',
+  'scrollbar-hide inline-flex items-center overflow-x-auto text-muted-foreground min-w-full justify-around',
   {
     variants: {
       variant: {
diff --git a/services/platform/app/features/settings/providers/components/provider-add-panel.tsx b/services/platform/app/features/settings/providers/components/provider-add-panel.tsx
index 070cdacb4..ab8cea503 100644
--- a/services/platform/app/features/settings/providers/components/provider-add-panel.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-add-panel.tsx
@@ -616,14 +616,14 @@ export function ProviderAddPanel({
             {/* ── Models section ─────────────────────────────── */}
             <Stack gap={3}>
               <HStack justify="between" align="center">
-                <Text className="text-sm font-medium">
+                <Text className="text-[15px] font-semibold tracking-[-0.01em]">
                   {t('providers.models')}
                 </Text>
-                <HStack gap={2} align="center">
+                <HStack gap={1} align="center">
                   {canFetch && (
                     <Button
                       type="button"
-                      variant="secondary"
+                      variant="ghost"
                       size="sm"
                       onClick={() => void handleFetchModels()}
                       disabled={isFetching}
@@ -638,7 +638,7 @@ export function ProviderAddPanel({
                   )}
                   <Button
                     type="button"
-                    variant="secondary"
+                    variant="ghost"
                     size="sm"
                     onClick={openAddDialog}
                   >
@@ -670,7 +670,7 @@ export function ProviderAddPanel({
 
               {isFetching && rows.length === 0 && (
                 <div
-                  className="border-border flex items-center justify-center gap-2 rounded-lg border px-4 py-8"
+                  className="border-border flex items-center justify-center gap-2 rounded-xl border px-4 py-8"
                   role="status"
                   aria-live="polite"
                 >
@@ -682,8 +682,8 @@ export function ProviderAddPanel({
               )}
 
               {rows.length > 0 && (
-                <div className="overflow-hidden rounded-lg border">
-                  <div className="border-border border-b px-3 py-2">
+                <div className="overflow-hidden rounded-xl border">
+                  <div className="border-border border-b px-3 py-2.5">
                     <SearchInput
                       value={modelSearch}
                       onChange={(e) => setModelSearch(e.target.value)}
diff --git a/services/platform/app/features/settings/providers/components/provider-detail-drawer.tsx b/services/platform/app/features/settings/providers/components/provider-detail-drawer.tsx
index 7ebb63c96..0fec77691 100644
--- a/services/platform/app/features/settings/providers/components/provider-detail-drawer.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-detail-drawer.tsx
@@ -15,14 +15,7 @@ import {
   X,
   Zap,
 } from 'lucide-react';
-import {
-  type ReactNode,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
 import { FormDialog } from '@/app/components/ui/dialog/form-dialog';
@@ -172,51 +165,104 @@ export function ProviderDetailDrawer({
 function ProviderDetailSkeleton() {
   return (
     <Stack gap={6}>
-      <Card contentClassName="p-5">
-        <Stack gap={4}>
-          <HStack justify="between" className="border-b pb-4">
-            <Skeleton className="h-5 w-16" />
-            <Skeleton className="h-4 w-20" />
-          </HStack>
-          <Stack gap={3} className="divide-y">
-            {Array.from({ length: 3 }).map((_, i) => (
-              <HStack key={i} gap={4} className="pt-3 first:pt-0">
-                <Skeleton className="h-4 w-28" />
-                <Skeleton className="h-4 w-48" />
-              </HStack>
-            ))}
-          </Stack>
-        </Stack>
-      </Card>
-      <Card contentClassName="p-5">
-        <HStack gap={4}>
+      <Stack gap={2}>
+        <HStack justify="between" align="center">
           <Skeleton className="h-5 w-16" />
-          <Skeleton className="h-5 w-32" />
-          <Skeleton className="h-4 w-28" />
+          <Skeleton className="h-8 w-20" />
         </HStack>
-      </Card>
-      <Card contentClassName="p-5">
-        <Stack gap={4}>
-          <HStack justify="between" className="border-b pb-4">
-            <Skeleton className="h-5 w-28" />
-            <Skeleton className="h-4 w-20" />
+        <Card contentClassName="p-0">
+          {Array.from({ length: 3 }).map((_, i) => (
+            <HStack
+              key={i}
+              gap={4}
+              align="start"
+              className={cn('px-4 py-2.5', i < 2 && 'border-b')}
+            >
+              <Skeleton className="h-4 w-28 shrink-0" />
+              <Skeleton className="h-4 w-48" />
+            </HStack>
+          ))}
+        </Card>
+      </Stack>
+
+      <Stack gap={2}>
+        <HStack justify="between" align="center">
+          <Skeleton className="h-5 w-16" />
+          <HStack gap={1} align="center">
+            <Skeleton className="h-8 w-28" />
+            <Skeleton className="h-8 w-24" />
           </HStack>
-          <Stack gap={3} className="divide-y">
-            {Array.from({ length: 3 }).map((_, i) => (
-              <HStack key={i} gap={4} className="pt-3 first:pt-0">
-                <Skeleton className="h-4 w-28" />
-                <Skeleton className="h-4 w-32" />
-              </HStack>
-            ))}
+        </HStack>
+        <Card contentClassName="p-0">
+          <HStack gap={4} align="center" className="px-4 py-2.5">
+            <Skeleton className="h-5 w-24 rounded-full" />
+            <Skeleton className="h-4 w-32" />
+          </HStack>
+        </Card>
+      </Stack>
+
+      <Stack gap={2}>
+        <HStack justify="between" align="start">
+          <Stack gap={1} className="min-w-0">
+            <Skeleton className="h-5 w-32" />
+            <Skeleton className="h-4 w-64" />
           </Stack>
-        </Stack>
-      </Card>
+          <Skeleton className="h-8 w-20" />
+        </HStack>
+        <Card contentClassName="p-0">
+          {Array.from({ length: 5 }).map((_, i) => (
+            <HStack
+              key={i}
+              gap={4}
+              align="start"
+              className={cn('px-4 py-2.5', i < 4 && 'border-b')}
+            >
+              <Skeleton className="h-4 w-28 shrink-0" />
+              <Skeleton className="h-4 w-32" />
+            </HStack>
+          ))}
+        </Card>
+      </Stack>
+
+      <Stack gap={2}>
+        <HStack justify="between" align="center">
+          <Skeleton className="h-5 w-48" />
+          <Skeleton className="h-8 w-20" />
+        </HStack>
+        <Skeleton className="h-9 w-full rounded-lg" />
+        <Card contentClassName="p-5">
+          <Skeleton className="h-4 w-64" />
+        </Card>
+      </Stack>
+
       <Stack gap={3}>
-        <HStack justify="between">
-          <Skeleton className="h-6 w-16" />
-          <Skeleton className="h-9 w-28" />
+        <HStack justify="between" align="center">
+          <Skeleton className="h-5 w-16" />
+          <HStack gap={1} align="center">
+            <Skeleton className="h-8 w-28" />
+            <Skeleton className="h-8 w-24" />
+          </HStack>
         </HStack>
-        <Skeleton className="h-64 w-full rounded-lg" />
+        <div className="overflow-hidden rounded-xl border">
+          <div className="border-border border-b px-3 py-2">
+            <Skeleton className="h-6 w-full" />
+          </div>
+          {Array.from({ length: 4 }).map((_, i) => (
+            <HStack
+              key={i}
+              justify="between"
+              align="center"
+              gap={4}
+              className={cn('px-4 py-2.5', i < 3 && 'border-border border-b')}
+            >
+              <HStack gap={3} align="center">
+                <Skeleton className="size-4 rounded" />
+                <Skeleton className="h-4 w-40" />
+              </HStack>
+              <Skeleton className="h-5 w-14 rounded-full" />
+            </HStack>
+          ))}
+        </div>
       </Stack>
     </Stack>
   );
@@ -274,10 +320,10 @@ function InfoRow({
   return (
     <HStack
       gap={4}
-      align="center"
-      className={cn('px-5 py-3.5', !isLast && 'border-b')}
+      align="start"
+      className={cn('px-4 py-2.5', !isLast && 'border-b')}
     >
-      <Text variant="muted" className="w-36 shrink-0 text-sm font-normal">
+      <Text variant="muted" className="w-32 shrink-0 text-sm font-normal">
         {label}
       </Text>
       <div
@@ -292,48 +338,6 @@ function InfoRow({
   );
 }
 
-function SectionHeader({
-  title,
-  description,
-  onEdit,
-  editLabel,
-  children,
-}: {
-  title: string;
-  description?: string;
-  onEdit: () => void;
-  editLabel: string;
-  children?: ReactNode;
-}) {
-  return (
-    <HStack
-      justify="between"
-      align={description ? 'start' : 'center'}
-      className="border-b px-5 py-4"
-    >
-      <Stack gap={1}>
-        <Text className="text-[15px] font-semibold tracking-[-0.01em]">
-          {title}
-        </Text>
-        {description && (
-          <Text className="text-muted-foreground text-[13px]">
-            {description}
-          </Text>
-        )}
-      </Stack>
-      {children}
-      <button
-        type="button"
-        onClick={onEdit}
-        className="text-muted-foreground hover:text-foreground focus-visible:outline-ring flex shrink-0 items-center gap-1.5 rounded-sm text-[13px] font-medium focus-visible:outline-2 focus-visible:outline-offset-2"
-      >
-        <Pencil className="size-3.5" />
-        {editLabel}
-      </button>
-    </HStack>
-  );
-}
-
 function GeneralSection({
   providerName,
   organizationId,
@@ -346,13 +350,17 @@ function GeneralSection({
   const [panelOpen, setPanelOpen] = useState(false);
 
   return (
-    <>
+    <Stack gap={2}>
+      <HStack justify="between" align="center">
+        <Text className="text-[15px] font-semibold tracking-[-0.01em]">
+          {t('providers.general')}
+        </Text>
+        <Button variant="ghost" size="sm" onClick={() => setPanelOpen(true)}>
+          <Pencil className="mr-1 size-3.5" />
+          {t('providers.editGeneral')}
+        </Button>
+      </HStack>
       <Card contentClassName="p-0">
-        <SectionHeader
-          title={t('providers.general')}
-          onEdit={() => setPanelOpen(true)}
-          editLabel={t('providers.editGeneral')}
-        />
         <InfoRow label={t('providers.displayName')}>
           {config.displayName}
         </InfoRow>
@@ -370,7 +378,7 @@ function GeneralSection({
         providerName={providerName}
         organizationId={organizationId}
       />
-    </>
+    </Stack>
   );
 }
 
@@ -397,29 +405,39 @@ function DefaultModelsSection({
 
   return (
     <>
-      <Card contentClassName="p-0">
-        <SectionHeader
-          title={t('providers.defaultModels')}
-          description={t('providers.defaultModelsDescription')}
-          onEdit={() => setPanelOpen(true)}
-          editLabel={t('providers.editDefaults')}
-        />
-        <InfoRow label={t('providers.tagChat')}>
-          {modelDisplayName(config.defaults?.chat)}
-        </InfoRow>
-        <InfoRow label={t('providers.tagVision')}>
-          {modelDisplayName(config.defaults?.vision)}
-        </InfoRow>
-        <InfoRow label={t('providers.tagEmbedding')}>
-          {modelDisplayName(config.defaults?.embedding)}
-        </InfoRow>
-        <InfoRow label={t('providers.tagImageGeneration')}>
-          {modelDisplayName(config.defaults?.['image-generation'])}
-        </InfoRow>
-        <InfoRow label={t('providers.tagTranscription')} isLast>
-          {modelDisplayName(config.defaults?.transcription)}
-        </InfoRow>
-      </Card>
+      <Stack gap={2}>
+        <HStack justify="between" align="start">
+          <Stack gap={1} className="min-w-0">
+            <Text className="text-[15px] font-semibold tracking-[-0.01em]">
+              {t('providers.defaultModels')}
+            </Text>
+            <Text className="text-muted-foreground text-[13px]">
+              {t('providers.defaultModelsDescription')}
+            </Text>
+          </Stack>
+          <Button variant="ghost" size="sm" onClick={() => setPanelOpen(true)}>
+            <Pencil className="mr-1 size-3.5" />
+            {t('providers.editDefaults')}
+          </Button>
+        </HStack>
+        <Card contentClassName="p-0">
+          <InfoRow label={t('providers.tagChat')}>
+            {modelDisplayName(config.defaults?.chat)}
+          </InfoRow>
+          <InfoRow label={t('providers.tagVision')}>
+            {modelDisplayName(config.defaults?.vision)}
+          </InfoRow>
+          <InfoRow label={t('providers.tagEmbedding')}>
+            {modelDisplayName(config.defaults?.embedding)}
+          </InfoRow>
+          <InfoRow label={t('providers.tagImageGeneration')}>
+            {modelDisplayName(config.defaults?.['image-generation'])}
+          </InfoRow>
+          <InfoRow label={t('providers.tagTranscription')} isLast>
+            {modelDisplayName(config.defaults?.transcription)}
+          </InfoRow>
+        </Card>
+      </Stack>
 
       <ProviderDefaultModelsPanel
         open={panelOpen}
@@ -446,6 +464,7 @@ function ProviderOptionsSection() {
       copy={{
         title: t('providers.providerOptions.providerLevelTitle'),
         description: t('providers.providerOptions.providerLevelDescription'),
+        guideLabel: t('providers.providerOptions.guideLabel'),
         notConfigured: t('providers.providerOptions.notConfigured'),
         editLabel: t('providers.editGeneral'),
         saveLabel: t('providers.providerOptions.save'),
@@ -550,38 +569,49 @@ function ApiKeySection({
 
   return (
     <>
-      <Card contentClassName="p-0">
-        <SectionHeader
-          title={t('providers.apiKey')}
-          onEdit={() => setDialogOpen(true)}
-          editLabel={hasSecret ? t('providers.editKey') : t('providers.addKey')}
-        >
-          <button
-            type="button"
-            onClick={() => setTestDialogOpen(true)}
-            className="text-muted-foreground hover:text-foreground focus-visible:outline-ring ml-auto flex items-center gap-1.5 rounded-sm text-[13px] font-medium focus-visible:outline-2 focus-visible:outline-offset-2"
-          >
-            <Zap className="size-3.5" />
-            {t('providers.testConnection')}
-          </button>
-        </SectionHeader>
-        {hasSecret ? (
-          <HStack gap={4} align="center" className="flex-wrap px-5 py-3.5">
-            <Badge variant="green" dot>
-              {t('providers.apiKeyConfigured')}
-            </Badge>
-            <Text className="text-muted-foreground font-mono text-sm">
-              {maskedKey}
-            </Text>
-          </HStack>
-        ) : (
-          <HStack gap={3} align="center" className="px-5 py-3.5">
-            <Badge variant="outline">
-              {t('providers.apiKeyNotConfigured')}
-            </Badge>
+      <Stack gap={2}>
+        <HStack justify="between" align="center">
+          <Text className="text-[15px] font-semibold tracking-[-0.01em]">
+            {t('providers.apiKey')}
+          </Text>
+          <HStack gap={1} align="center">
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => setTestDialogOpen(true)}
+            >
+              <Zap className="mr-1 size-3.5" />
+              {t('providers.testConnection')}
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => setDialogOpen(true)}
+            >
+              <Pencil className="mr-1 size-3.5" />
+              {hasSecret ? t('providers.editKey') : t('providers.addKey')}
+            </Button>
           </HStack>
-        )}
-      </Card>
+        </HStack>
+        <Card contentClassName="p-0">
+          {hasSecret ? (
+            <HStack gap={4} align="center" className="flex-wrap px-4 py-2.5">
+              <Badge variant="green" dot>
+                {t('providers.apiKeyConfigured')}
+              </Badge>
+              <Text className="text-muted-foreground font-mono text-sm">
+                {maskedKey}
+              </Text>
+            </HStack>
+          ) : (
+            <HStack gap={3} align="center" className="px-4 py-2.5">
+              <Badge variant="outline">
+                {t('providers.apiKeyNotConfigured')}
+              </Badge>
+            </HStack>
+          )}
+        </Card>
+      </Stack>
 
       <FormDialog
         open={dialogOpen}
@@ -1045,10 +1075,10 @@ function ModelsSection({
           <Text className="text-[15px] font-semibold tracking-[-0.01em]">
             {t('providers.models')}
           </Text>
-          <HStack gap={2} align="center">
+          <HStack gap={1} align="center">
             <Button
               type="button"
-              variant="secondary"
+              variant="ghost"
               size="sm"
               onClick={() => void handleFetchFromProvider()}
               disabled={isFetchingFromProvider}
@@ -1062,7 +1092,7 @@ function ModelsSection({
             </Button>
             <Button
               type="button"
-              variant="secondary"
+              variant="ghost"
               size="sm"
               onClick={openAddDialog}
             >
@@ -1097,7 +1127,7 @@ function ModelsSection({
           </div>
         ) : (
           <div className="overflow-hidden rounded-xl border">
-            <div className="border-border border-b px-3 py-2">
+            <div className="border-border border-b px-3 py-2.5">
               <SearchInput
                 value={searchQuery}
                 onChange={(e) => setSearchQuery(e.target.value)}
@@ -1515,6 +1545,7 @@ function ModelsSection({
                   description: t(
                     'providers.providerOptions.modelLevelDescription',
                   ),
+                  guideLabel: t('providers.providerOptions.guideLabel'),
                   helpText: t('providers.providerOptions.modelLevelHelp'),
                 }}
               />
diff --git a/services/platform/app/features/settings/providers/components/provider-options-editor.tsx b/services/platform/app/features/settings/providers/components/provider-options-editor.tsx
index 728d2d29d..df37e5a7b 100644
--- a/services/platform/app/features/settings/providers/components/provider-options-editor.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-options-editor.tsx
@@ -6,6 +6,7 @@ import { Pencil, X } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import { z } from 'zod';
 
+import { CollapsibleGuide } from '@/app/components/ui/data-display/collapsible-guide';
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
 import { JsonInput } from '@/app/components/ui/forms/json-input';
 import { Textarea } from '@/app/components/ui/forms/textarea';
@@ -106,6 +107,7 @@ interface Props {
   copy: {
     title: string;
     description: string;
+    guideLabel: string;
     notConfigured: string;
     editLabel: string;
     saveLabel: string;
@@ -232,25 +234,20 @@ export function ProviderOptionsEditor({
 
   return (
     <>
-      <Card contentClassName="p-5">
-        <HStack justify="between" align="start" className="border-b pb-4">
-          <Stack gap={1} className="min-w-0">
-            <Text className="text-sm font-semibold">{copy.title}</Text>
-            <Text className="text-muted-foreground text-[13px] whitespace-pre-line">
-              {copy.description}
-            </Text>
-          </Stack>
-          <button
-            type="button"
-            onClick={() => setOpen(true)}
-            className="text-muted-foreground hover:text-foreground focus-visible:outline-ring flex shrink-0 items-center gap-1.5 rounded-sm text-[13px] font-medium focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-none"
-          >
-            <Pencil className="size-3.5" />
+      <Stack gap={2}>
+        <HStack justify="between" align="center">
+          <Text className="text-[15px] font-semibold tracking-[-0.01em]">
+            {copy.title}
+          </Text>
+          <Button variant="ghost" size="sm" onClick={() => setOpen(true)}>
+            <Pencil className="mr-1 size-3.5" />
             {copy.editLabel}
-          </button>
+          </Button>
         </HStack>
 
-        <div className="pt-4">
+        <CollapsibleGuide label={copy.guideLabel} content={copy.description} />
+
+        <Card contentClassName="px-4 py-2.5">
           {isEmpty ? (
             <Text className="text-muted-foreground text-[13px] italic">
               {copy.notConfigured}
@@ -265,13 +262,13 @@ export function ProviderOptionsEditor({
             <pre
               role="region"
               aria-label={copy.title}
-              className="bg-muted/40 overflow-x-auto rounded-md p-3 font-mono text-xs leading-relaxed"
+              className="bg-muted/40 overflow-x-auto rounded-md font-mono text-xs leading-relaxed"
             >
               {initialJson}
             </pre>
           )}
-        </div>
-      </Card>
+        </Card>
+      </Stack>
 
       <Sheet
         open={open}
@@ -290,6 +287,7 @@ export function ProviderOptionsEditor({
         <ProviderOptionsEditorSheet
           title={copy.title}
           description={copy.description}
+          guideLabel={copy.guideLabel}
           draft={draft}
           onDraftChange={setDraft}
           onClose={requestClose}
@@ -321,6 +319,7 @@ export function ProviderOptionsEditor({
 interface SheetBodyProps {
   title: string;
   description: string;
+  guideLabel: string;
   draft: string;
   onDraftChange: (next: string) => void;
   onClose: () => void;
@@ -337,6 +336,7 @@ interface SheetBodyProps {
 function ProviderOptionsEditorSheet({
   title,
   description,
+  guideLabel,
   draft,
   onDraftChange,
   onClose,
@@ -373,9 +373,7 @@ function ProviderOptionsEditorSheet({
       <div className="flex min-h-0 flex-1 flex-col">
         <div className="flex-1 overflow-y-auto p-4 sm:px-6 sm:py-5">
           <Stack gap={3}>
-            <Text className="text-muted-foreground text-[13px] whitespace-pre-line">
-              {description}
-            </Text>
+            <CollapsibleGuide label={guideLabel} content={description} />
             <Textarea
               // `aria-label` (instead of a visible `label`) so screen
               // readers announce the textarea's purpose without
@@ -442,10 +440,11 @@ interface ModelEditorProps {
   value: string;
   /** Setter wired into the dialog's form state. */
   onChange: (next: string) => void;
-  /** Translated copy. `helpText` renders below the editor. */
+  /** Translated copy. `helpText` renders below the editor inside a CollapsibleGuide. */
   copy: {
     title: string;
     description: string;
+    guideLabel: string;
     helpText: string;
   };
 }
@@ -468,9 +467,7 @@ export function ModelProviderOptionsField({
         rows={6}
         fontSize={12}
       />
-      <Text className="text-muted-foreground text-[12px] whitespace-pre-line">
-        {copy.helpText}
-      </Text>
+      <CollapsibleGuide label={copy.guideLabel} content={copy.helpText} />
     </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/providers/components/providers-table.tsx b/services/platform/app/features/settings/providers/components/providers-table.tsx
index d51ce864e..597f81bdd 100644
--- a/services/platform/app/features/settings/providers/components/providers-table.tsx
+++ b/services/platform/app/features/settings/providers/components/providers-table.tsx
@@ -21,7 +21,8 @@ import { useT } from '@/lib/i18n/client';
 import { resolveProviderLocale } from '@/lib/shared/utils/resolve-provider-locale';
 
 import { useDeleteProvider } from '../hooks/mutations';
-import { useListProviders } from '../hooks/queries';
+import { useListProviders, useReadProvider } from '../hooks/queries';
+import { ProviderConfigProvider } from '../hooks/use-provider-config-context';
 import { useProvidersTableConfig } from '../hooks/use-providers-table-config';
 import { ProviderAddPanel } from './provider-add-panel';
 import { ProviderDetailDrawer } from './provider-detail-drawer';
@@ -174,13 +175,11 @@ export function ProvidersTable({
       />
 
       {editProvider && (
-        <ProviderEditPanel
-          open
-          onOpenChange={(open) => {
-            if (!open) setEditProvider(null);
-          }}
+        <ProviderEditPanelLoader
+          orgSlug={orgSlug}
           providerName={editProvider.name}
           organizationId={organizationId}
+          onClose={() => setEditProvider(null)}
         />
       )}
 
@@ -280,3 +279,43 @@ function ProviderRowActions({
     />
   );
 }
+
+/**
+ * Wrapper that fetches the provider's config + hash and hands them to
+ * `ProviderConfigProvider`, so the row-level Edit action gets the same
+ * optimistic-concurrency context as the detail drawer. Without it,
+ * `useProviderConfig` inside `ProviderEditPanel` throws.
+ */
+function ProviderEditPanelLoader({
+  orgSlug,
+  providerName,
+  organizationId,
+  onClose,
+}: {
+  orgSlug: string;
+  providerName: string;
+  organizationId: string;
+  onClose: () => void;
+}) {
+  const { data } = useReadProvider(orgSlug, providerName, {
+    enabled: !!orgSlug,
+  });
+  if (!data?.ok) return null;
+  return (
+    <ProviderConfigProvider
+      orgSlug={orgSlug}
+      providerName={providerName}
+      initialConfig={data.config}
+      initialHash={data.hash}
+    >
+      <ProviderEditPanel
+        open
+        onOpenChange={(open) => {
+          if (!open) onClose();
+        }}
+        providerName={providerName}
+        organizationId={organizationId}
+      />
+    </ProviderConfigProvider>
+  );
+}
diff --git a/services/platform/messages/de.json b/services/platform/messages/de.json
index d41741f4c..c7ee779ac 100644
--- a/services/platform/messages/de.json
+++ b/services/platform/messages/de.json
@@ -1050,10 +1050,11 @@
       "forbiddenDeveloperSettings": "Du hast keine Berechtigung, die Anbieter-Konfiguration zu ändern.",
       "providerOptions": {
         "providerLevelTitle": "Erweitert — Provider-Optionen",
-        "providerLevelDescription": "Freies JSON, das wortgetreu als zusätzliche Request-Body-Felder an jedes Modell dieses Anbieters weitergeleitet wird. Die Struktur wird vom Upstream-API vorgegeben — Tale interpretiert diese Felder nicht, sondern reicht sie nur durch.\n\nWelche Knöpfe verfügbar sind, hängt davon ab, ob es sich beim Upstream um ein Routing-Gateway oder einen direkten Inferenz-Anbieter handelt:\n\nGateways aggregieren mehrere Backends und exponieren Routing-Steuerungen:\n• OpenRouter — Routing-Optionen unter einem Top-Level-Schlüssel \"provider\" (Quantisierung, Fallback-Richtlinie, erlaubte Backends usw. wählen):\n { \"provider\": { \"quantizations\": [\"fp8\"], \"allow_fallbacks\": false } }\n• Vercel AI Gateway — routet primär über das Modell-ID-Präfix und HTTP-Header; Body-Level-Passthrough ist auf Observability-Felder wie \"metadata\" beschränkt:\n { \"metadata\": { \"tale_agent\": \"support\" } }\n\nDirekte Anbieter hosten ihre eigenen Modelle — es gibt keine Routing-Schicht und kein \"quantizations\"-Feld; die Präzision ist beim Deployment festgelegt. Deren Passthrough-Felder sind Modellverhaltens-Knöpfe auf oberster Body-Ebene:\n• OpenAI:\n { \"service_tier\": \"priority\", \"parallel_tool_calls\": false }\n• Together AI:\n { \"safety_model\": \"meta-llama/Llama-Guard-4-12B\", \"repetition_penalty\": 1.1 }\n\nFür die genauen Feldnamen und akzeptierten Werte die API-Dokumentation des jeweiligen Anbieters konsultieren.",
+        "guideLabel": "So funktionieren Provider-Optionen",
+        "providerLevelDescription": "Freies JSON, das wortgetreu als zusätzliche Request-Body-Felder an jedes Modell dieses Anbieters weitergeleitet wird. Die Struktur wird vom Upstream-API vorgegeben — Tale interpretiert diese Felder nicht, sondern reicht sie nur durch.\n\nWelche Knöpfe verfügbar sind, hängt davon ab, ob es sich beim Upstream um ein Routing-Gateway oder einen direkten Inferenz-Anbieter handelt:\n\n**Gateways** aggregieren mehrere Backends und exponieren Routing-Steuerungen:\n\n- **OpenRouter** — Routing-Optionen unter einem Top-Level-Schlüssel `provider` (Quantisierung, Fallback-Richtlinie, erlaubte Backends usw. wählen):\n\n```json\n{ \"provider\": { \"quantizations\": [\"fp8\"], \"allow_fallbacks\": false } }\n```\n\n- **Vercel AI Gateway** — routet primär über das Modell-ID-Präfix und HTTP-Header; Body-Level-Passthrough ist auf Observability-Felder wie `metadata` beschränkt:\n\n```json\n{ \"metadata\": { \"tale_agent\": \"support\" } }\n```\n\n**Direkte Anbieter** hosten ihre eigenen Modelle — es gibt keine Routing-Schicht und kein `quantizations`-Feld; die Präzision ist beim Deployment festgelegt. Deren Passthrough-Felder sind Modellverhaltens-Knöpfe auf oberster Body-Ebene:\n\n- **OpenAI**:\n\n```json\n{ \"service_tier\": \"priority\", \"parallel_tool_calls\": false }\n```\n\n- **Together AI**:\n\n```json\n{ \"safety_model\": \"meta-llama/Llama-Guard-4-12B\", \"repetition_penalty\": 1.1 }\n```\n\nFür die genauen Feldnamen und akzeptierten Werte die API-Dokumentation des jeweiligen Anbieters konsultieren.",
         "modelLevelTitle": "Erweitert — Provider-Optionen",
         "modelLevelDescription": "Freies JSON, das mit den Anbieter-Standards zusammengeführt und als zusätzliche Request-Body-Felder weitergeleitet wird. Die Struktur folgt dem Upstream-API und unterscheidet sich je nach Anbieter — Tale reicht das JSON wortgetreu durch, ohne es zu interpretieren.",
-        "modelLevelHelp": "Beispiele — Gateways und direkte Anbieter exponieren unterschiedliche Arten von Knöpfen:\n• OpenRouter (Gateway): { \"provider\": { \"quantizations\": [\"fp8\"] } } — ein Backend nach Quantisierung anpinnen\n• Vercel AI Gateway (Gateway): { \"metadata\": { \"tale_agent\": \"support\" } } — Observability-Tag (Routing meist über Header oder Modell-Präfix)\n• OpenAI (direkt): { \"service_tier\": \"priority\" } — eine SLA-Stufe wählen\n• Together AI (direkt): { \"safety_model\": \"meta-llama/Llama-Guard-4-12B\" } — Moderation anwenden\n\nDirekte Anbieter exponieren Quantisierung nicht als Request-Feld — stattdessen eine andere Modell-ID wählen. Schlüssel wie model / messages / max_tokens / temperature werden abgelehnt — diese auf Agent-Ebene konfigurieren. Leere Eingabe entfernt die Überschreibung.",
+        "modelLevelHelp": "Beispiele — Gateways und direkte Anbieter exponieren unterschiedliche Arten von Knöpfen:\n\n- **OpenRouter** (Gateway) — ein Backend nach Quantisierung anpinnen:\n\n```json\n{ \"provider\": { \"quantizations\": [\"fp8\"] } }\n```\n\n- **Vercel AI Gateway** (Gateway) — Observability-Tag (Routing meist über Header oder Modell-Präfix):\n\n```json\n{ \"metadata\": { \"tale_agent\": \"support\" } }\n```\n\n- **OpenAI** (direkt) — eine SLA-Stufe wählen:\n\n```json\n{ \"service_tier\": \"priority\" }\n```\n\n- **Together AI** (direkt) — Moderation anwenden:\n\n```json\n{ \"safety_model\": \"meta-llama/Llama-Guard-4-12B\" }\n```\n\nDirekte Anbieter exponieren Quantisierung nicht als Request-Feld — stattdessen eine andere Modell-ID wählen. Schlüssel wie `model` / `messages` / `max_tokens` / `temperature` werden abgelehnt — diese auf Agent-Ebene konfigurieren. Leere Eingabe entfernt die Überschreibung.",
         "notConfigured": "Nicht konfiguriert — verwendet Provider-/Laufzeit-Standards.",
         "save": "Provider-Optionen speichern",
         "saveSuccess": "Provider-Optionen gespeichert",
diff --git a/services/platform/messages/en.json b/services/platform/messages/en.json
index 6863352c5..368f03ec6 100644
--- a/services/platform/messages/en.json
+++ b/services/platform/messages/en.json
@@ -1050,10 +1050,11 @@
       "forbiddenDeveloperSettings": "You don't have permission to modify provider configuration.",
       "providerOptions": {
         "providerLevelTitle": "Advanced — Provider Options",
-        "providerLevelDescription": "Free-form JSON forwarded verbatim as extra request body fields to every model on this provider. The shape is dictated by the upstream API — Tale does not interpret these fields, it just passes them through.\n\nThe available knobs depend on whether the upstream is a routing gateway or a direct inference vendor:\n\nGateways aggregate multiple backends and expose routing controls:\n• OpenRouter — routing options live under a top-level \"provider\" key (pick the quantization, fallback policy, allowed backends, etc.):\n    { \"provider\": { \"quantizations\": [\"fp8\"], \"allow_fallbacks\": false } }\n• Vercel AI Gateway — primarily routes via the model-ID prefix and HTTP headers; body-level passthrough is limited to observability fields like \"metadata\":\n    { \"metadata\": { \"tale_agent\": \"support\" } }\n\nDirect vendors host their own models, so there is no routing layer and no \"quantizations\" field — the precision is fixed at deploy time. Their passthrough fields are model-behavior knobs at the body's top level:\n• OpenAI:\n    { \"service_tier\": \"priority\", \"parallel_tool_calls\": false }\n• Together AI:\n    { \"safety_model\": \"meta-llama/Llama-Guard-4-12B\", \"repetition_penalty\": 1.1 }\n\nRefer to each provider's API docs for the exact field names and accepted values.",
+        "guideLabel": "How provider options work",
+        "providerLevelDescription": "Free-form JSON forwarded verbatim as extra request body fields to every model on this provider. The shape is dictated by the upstream API — Tale does not interpret these fields, it just passes them through.\n\nThe available knobs depend on whether the upstream is a routing gateway or a direct inference vendor:\n\n**Gateways** aggregate multiple backends and expose routing controls:\n\n- **OpenRouter** — routing options live under a top-level `provider` key (pick the quantization, fallback policy, allowed backends, etc.):\n\n```json\n{ \"provider\": { \"quantizations\": [\"fp8\"], \"allow_fallbacks\": false } }\n```\n\n- **Vercel AI Gateway** — primarily routes via the model-ID prefix and HTTP headers; body-level passthrough is limited to observability fields like `metadata`:\n\n```json\n{ \"metadata\": { \"tale_agent\": \"support\" } }\n```\n\n**Direct vendors** host their own models, so there is no routing layer and no `quantizations` field — the precision is fixed at deploy time. Their passthrough fields are model-behavior knobs at the body's top level:\n\n- **OpenAI**:\n\n```json\n{ \"service_tier\": \"priority\", \"parallel_tool_calls\": false }\n```\n\n- **Together AI**:\n\n```json\n{ \"safety_model\": \"meta-llama/Llama-Guard-4-12B\", \"repetition_penalty\": 1.1 }\n```\n\nRefer to each provider's API docs for the exact field names and accepted values.",
         "modelLevelTitle": "Advanced — Provider Options",
         "modelLevelDescription": "Free-form JSON merged on top of the provider-level defaults and forwarded as extra request body fields. The shape mirrors the upstream API and differs per provider — Tale forwards verbatim without interpretation.",
-        "modelLevelHelp": "Examples — gateways and direct vendors expose different kinds of knobs:\n• OpenRouter (gateway): { \"provider\": { \"quantizations\": [\"fp8\"] } } — pin a backend by quantization\n• Vercel AI Gateway (gateway): { \"metadata\": { \"tale_agent\": \"support\" } } — observability tag (most routing is header- or model-prefix-based)\n• OpenAI (direct): { \"service_tier\": \"priority\" } — pick an SLA tier\n• Together AI (direct): { \"safety_model\": \"meta-llama/Llama-Guard-4-12B\" } — apply moderation\n\nDirect vendors don't expose quantization as a request field — pick a different model ID instead. Keys like model / messages / max_tokens / temperature are rejected — set those at the agent level. Empty input clears the override.",
+        "modelLevelHelp": "Examples — gateways and direct vendors expose different kinds of knobs:\n\n- **OpenRouter** (gateway) — pin a backend by quantization:\n\n```json\n{ \"provider\": { \"quantizations\": [\"fp8\"] } }\n```\n\n- **Vercel AI Gateway** (gateway) — observability tag (most routing is header- or model-prefix-based):\n\n```json\n{ \"metadata\": { \"tale_agent\": \"support\" } }\n```\n\n- **OpenAI** (direct) — pick an SLA tier:\n\n```json\n{ \"service_tier\": \"priority\" }\n```\n\n- **Together AI** (direct) — apply moderation:\n\n```json\n{ \"safety_model\": \"meta-llama/Llama-Guard-4-12B\" }\n```\n\nDirect vendors don't expose quantization as a request field — pick a different model ID instead. Keys like `model` / `messages` / `max_tokens` / `temperature` are rejected — set those at the agent level. Empty input clears the override.",
         "notConfigured": "Not configured — using provider/runtime defaults.",
         "save": "Save provider options",
         "saveSuccess": "Provider options saved",
diff --git a/services/platform/messages/fr.json b/services/platform/messages/fr.json
index 9c7014799..8f3eec858 100644
--- a/services/platform/messages/fr.json
+++ b/services/platform/messages/fr.json
@@ -1050,10 +1050,11 @@
       "forbiddenDeveloperSettings": "Tu n'as pas l'autorisation de modifier la configuration du fournisseur.",
       "providerOptions": {
         "providerLevelTitle": "Avancé — Options du fournisseur",
-        "providerLevelDescription": "JSON libre transmis tel quel comme champs de corps de requête supplémentaires à chaque modèle de ce fournisseur. La forme est dictée par l'API en amont — Tale n'interprète pas ces champs, il les transmet simplement.\n\nLes options disponibles dépendent du type de fournisseur — passerelle de routage ou fournisseur d'inférence direct :\n\nLes passerelles agrègent plusieurs backends et exposent des contrôles de routage :\n• OpenRouter — les options de routage se trouvent sous une clé \"provider\" de premier niveau (choix de la quantisation, politique de repli, backends autorisés, etc.) :\n { \"provider\": { \"quantizations\": [\"fp8\"], \"allow_fallbacks\": false } }\n• Vercel AI Gateway — route principalement via le préfixe d'ID de modèle et les en-têtes HTTP ; le passthrough au niveau du corps est limité aux champs d'observabilité comme \"metadata\" :\n { \"metadata\": { \"tale_agent\": \"support\" } }\n\nLes fournisseurs directs hébergent leurs propres modèles — il n'y a pas de couche de routage ni de champ \"quantizations\" ; la précision est figée au déploiement. Leurs champs passthrough sont des paramètres de comportement du modèle au niveau supérieur du corps :\n• OpenAI :\n { \"service_tier\": \"priority\", \"parallel_tool_calls\": false }\n• Together AI :\n { \"safety_model\": \"meta-llama/Llama-Guard-4-12B\", \"repetition_penalty\": 1.1 }\n\nConsulte la documentation API de chaque fournisseur pour les noms de champs et valeurs acceptées exacts.",
+        "guideLabel": "Fonctionnement des options du fournisseur",
+        "providerLevelDescription": "JSON libre transmis tel quel comme champs de corps de requête supplémentaires à chaque modèle de ce fournisseur. La forme est dictée par l'API en amont — Tale n'interprète pas ces champs, il les transmet simplement.\n\nLes options disponibles dépendent du type de fournisseur — passerelle de routage ou fournisseur d'inférence direct :\n\n**Les passerelles** agrègent plusieurs backends et exposent des contrôles de routage :\n\n- **OpenRouter** — les options de routage se trouvent sous une clé `provider` de premier niveau (choix de la quantisation, politique de repli, backends autorisés, etc.) :\n\n```json\n{ \"provider\": { \"quantizations\": [\"fp8\"], \"allow_fallbacks\": false } }\n```\n\n- **Vercel AI Gateway** — route principalement via le préfixe d'ID de modèle et les en-têtes HTTP ; le passthrough au niveau du corps est limité aux champs d'observabilité comme `metadata` :\n\n```json\n{ \"metadata\": { \"tale_agent\": \"support\" } }\n```\n\n**Les fournisseurs directs** hébergent leurs propres modèles — il n'y a pas de couche de routage ni de champ `quantizations` ; la précision est figée au déploiement. Leurs champs passthrough sont des paramètres de comportement du modèle au niveau supérieur du corps :\n\n- **OpenAI** :\n\n```json\n{ \"service_tier\": \"priority\", \"parallel_tool_calls\": false }\n```\n\n- **Together AI** :\n\n```json\n{ \"safety_model\": \"meta-llama/Llama-Guard-4-12B\", \"repetition_penalty\": 1.1 }\n```\n\nConsulte la documentation API de chaque fournisseur pour les noms de champs et valeurs acceptées exacts.",
         "modelLevelTitle": "Avancé — Options du fournisseur",
         "modelLevelDescription": "JSON libre fusionné par-dessus les valeurs par défaut du fournisseur et transmis comme champs de corps de requête supplémentaires. La forme suit l'API en amont et diffère selon le fournisseur — Tale transmet le JSON tel quel sans interprétation.",
-        "modelLevelHelp": "Exemples — passerelles et fournisseurs directs exposent des types d'options différents :\n• OpenRouter (passerelle) : { \"provider\": { \"quantizations\": [\"fp8\"] } } — épingle un backend par quantisation\n• Vercel AI Gateway (passerelle) : { \"metadata\": { \"tale_agent\": \"support\" } } — étiquette d'observabilité (routage principalement via en-têtes ou préfixe de modèle)\n• OpenAI (direct) : { \"service_tier\": \"priority\" } — choix d'un palier SLA\n• Together AI (direct) : { \"safety_model\": \"meta-llama/Llama-Guard-4-12B\" } — applique la modération\n\nLes fournisseurs directs n'exposent pas la quantisation comme champ de requête — choisis un autre ID de modèle à la place. Les clés comme model / messages / max_tokens / temperature sont rejetées — configure-les au niveau de l'agent. Une entrée vide efface la surcharge.",
+        "modelLevelHelp": "Exemples — passerelles et fournisseurs directs exposent des types d'options différents :\n\n- **OpenRouter** (passerelle) — épingle un backend par quantisation :\n\n```json\n{ \"provider\": { \"quantizations\": [\"fp8\"] } }\n```\n\n- **Vercel AI Gateway** (passerelle) — étiquette d'observabilité (routage principalement via en-têtes ou préfixe de modèle) :\n\n```json\n{ \"metadata\": { \"tale_agent\": \"support\" } }\n```\n\n- **OpenAI** (direct) — choix d'un palier SLA :\n\n```json\n{ \"service_tier\": \"priority\" }\n```\n\n- **Together AI** (direct) — applique la modération :\n\n```json\n{ \"safety_model\": \"meta-llama/Llama-Guard-4-12B\" }\n```\n\nLes fournisseurs directs n'exposent pas la quantisation comme champ de requête — choisis un autre ID de modèle à la place. Les clés comme `model` / `messages` / `max_tokens` / `temperature` sont rejetées — configure-les au niveau de l'agent. Une entrée vide efface la surcharge.",
         "notConfigured": "Non configuré — utilise les valeurs par défaut du fournisseur / d'exécution.",
         "save": "Enregistrer les options",
         "saveSuccess": "Options du fournisseur enregistrées",