From 8669bf69ecf683eacbbdee055753e2b435f32466 Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 05:33:27 +0700
Subject: [PATCH 1/7] feat(ui): add InfoTooltip and PresetSlider shared
 components

---
 src/shared/components/InfoTooltip.tsx  | 34 ++++++++++++++
 src/shared/components/PresetSlider.tsx | 64 ++++++++++++++++++++++++++
 src/shared/components/index.tsx        |  2 +
 3 files changed, 100 insertions(+)
 create mode 100644 src/shared/components/InfoTooltip.tsx
 create mode 100644 src/shared/components/PresetSlider.tsx

diff --git a/src/shared/components/InfoTooltip.tsx b/src/shared/components/InfoTooltip.tsx
new file mode 100644
index 0000000000..9f62de5b16
--- /dev/null
+++ b/src/shared/components/InfoTooltip.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+interface InfoTooltipProps {
+  text: string;
+  className?: string;
+}
+
+export default function InfoTooltip({ text, className }: InfoTooltipProps) {
+  return (
+    <span className={cn("relative inline-flex group", className)}>
+      <span
+        className="material-symbols-outlined text-[16px] text-text-muted cursor-help"
+        aria-label={text}
+      >
+        info
+      </span>
+      <span
+        role="tooltip"
+        className={cn(
+          "absolute bottom-full left-1/2 -translate-x-1/2 mb-2",
+          "px-2.5 py-1.5 text-xs font-medium text-white bg-gray-900/95 rounded-md shadow-lg",
+          "whitespace-nowrap pointer-events-none",
+          "border border-white/10",
+          "opacity-0 group-hover:opacity-100 transition-opacity duration-150",
+          "z-50"
+        )}
+      >
+        {text}
+      </span>
+    </span>
+  );
+}
diff --git a/src/shared/components/PresetSlider.tsx b/src/shared/components/PresetSlider.tsx
new file mode 100644
index 0000000000..17ffe35471
--- /dev/null
+++ b/src/shared/components/PresetSlider.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+interface PresetSliderProps {
+  value: number;
+  onChange: (value: number) => void;
+  presets: { label: string; value: number }[];
+  min?: number;
+  max?: number;
+  step?: number;
+  className?: string;
+}
+
+export default function PresetSlider({
+  value,
+  onChange,
+  presets,
+  min = 0,
+  max = 100,
+  step = 1,
+  className,
+}: PresetSliderProps) {
+  return (
+    <div className={cn("flex flex-col gap-3", className)}>
+      <div className="flex flex-wrap gap-2">
+        {presets.map((preset) => (
+          <button
+            key={preset.value}
+            type="button"
+            onClick={() => onChange(preset.value)}
+            className={cn(
+              "px-3 py-1.5 text-xs font-medium rounded-full transition-colors",
+              "border",
+              value === preset.value
+                ? "bg-primary text-white border-primary"
+                : "bg-transparent text-text-muted border-black/10 dark:border-white/10 hover:border-primary/30 hover:text-text-main"
+            )}
+          >
+            {preset.label}
+          </button>
+        ))}
+      </div>
+      <input
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={(e) => onChange(Number(e.target.value))}
+        className={cn(
+          "w-full h-1.5 rounded-full appearance-none cursor-pointer",
+          "bg-black/10 dark:bg-white/10",
+          "accent-primary"
+        )}
+      />
+      <div className="flex justify-between text-[10px] text-text-muted">
+        <span>{min}</span>
+        <span className="font-medium text-text-main">{value}</span>
+        <span>{max}</span>
+      </div>
+    </div>
+  );
+}
diff --git a/src/shared/components/index.tsx b/src/shared/components/index.tsx
index 1039804883..e1a90df42a 100644
--- a/src/shared/components/index.tsx
+++ b/src/shared/components/index.tsx
@@ -33,6 +33,8 @@ export { default as NotificationToast } from "./NotificationToast";
 export { default as FilterBar } from "./FilterBar";
 export { default as ColumnToggle } from "./ColumnToggle";
 export { default as DataTable } from "./DataTable";
+export { default as InfoTooltip } from "./InfoTooltip";
+export { default as PresetSlider } from "./PresetSlider";
 
 // Layouts
 export * from "./layouts";

From 801f3c9c223e4a61a4187fecdb3da4135ba38f69 Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 05:35:41 +0700
Subject: [PATCH 2/7] feat(ui): add simple/advanced mode switch to Caveman page

Simple mode shows stats, language packs, and output mode only.
Advanced mode reveals the full CompressionSettingsTab with all
engine internals, thresholds, and tool strategies.
---
 .../caveman/CavemanContextPageClient.tsx      | 24 ++++++++++++++-----
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/src/app/(dashboard)/dashboard/context/caveman/CavemanContextPageClient.tsx b/src/app/(dashboard)/dashboard/context/caveman/CavemanContextPageClient.tsx
index e879548954..7847079b17 100644
--- a/src/app/(dashboard)/dashboard/context/caveman/CavemanContextPageClient.tsx
+++ b/src/app/(dashboard)/dashboard/context/caveman/CavemanContextPageClient.tsx
@@ -2,6 +2,7 @@
 
 import { useEffect, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
+import { SegmentedControl } from "@/shared/components";
 import CompressionSettingsTab from "@/app/(dashboard)/dashboard/settings/components/CompressionSettingsTab";
 
 type AnalyticsSummary = {
@@ -44,6 +45,7 @@ export default function CavemanContextPageClient() {
   const [settings, setSettings] = useState<CompressionSettings | null>(null);
   const [languagePacks, setLanguagePacks] = useState<LanguagePack[]>([]);
   const [saving, setSaving] = useState(false);
+  const [viewMode, setViewMode] = useState<"simple" | "advanced">("simple");
 
   const refreshSettings = () => {
     fetch("/api/context/caveman/config")
@@ -118,12 +120,22 @@ export default function CavemanContextPageClient() {
   return (
     <div className="mx-auto flex max-w-6xl flex-col gap-6">
       <header className="flex flex-col gap-2">
-        <div className="flex items-center gap-3">
-          <span className="material-symbols-outlined text-[30px] text-primary">compress</span>
-          <div>
-            <h1 className="text-2xl font-bold text-text-main">{t("title")}</h1>
-            <p className="text-sm text-text-muted">{t("description")}</p>
+        <div className="flex items-center justify-between gap-3">
+          <div className="flex items-center gap-3">
+            <span className="material-symbols-outlined text-[30px] text-primary">compress</span>
+            <div>
+              <h1 className="text-2xl font-bold text-text-main">{t("title")}</h1>
+              <p className="text-sm text-text-muted">{t("description")}</p>
+            </div>
           </div>
+          <SegmentedControl
+            value={viewMode}
+            onChange={(v) => setViewMode(v as "simple" | "advanced")}
+            options={[
+              { value: "simple", label: t("simpleMode") || "Simple" },
+              { value: "advanced", label: t("advancedMode") || "Advanced" },
+            ]}
+          />
         </div>
       </header>
 
@@ -256,7 +268,7 @@ export default function CavemanContextPageClient() {
         </div>
       </section>
 
-      <CompressionSettingsTab />
+      {viewMode === "advanced" && <CompressionSettingsTab />}
     </div>
   );
 }

From 3757e6dc3002c2067c38f18f2c1d6889029ad880 Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 05:38:04 +0700
Subject: [PATCH 3/7] feat(ui): add simple/advanced mode switch to RTK page

Simple mode shows stats, config, and collapsible filter catalog.
Advanced mode adds filter testing with raw JSON preview.
---
 .../context/rtk/RtkContextPageClient.tsx      | 162 ++++++++++--------
 1 file changed, 93 insertions(+), 69 deletions(-)

diff --git a/src/app/(dashboard)/dashboard/context/rtk/RtkContextPageClient.tsx b/src/app/(dashboard)/dashboard/context/rtk/RtkContextPageClient.tsx
index e42b098115..8ae6106560 100644
--- a/src/app/(dashboard)/dashboard/context/rtk/RtkContextPageClient.tsx
+++ b/src/app/(dashboard)/dashboard/context/rtk/RtkContextPageClient.tsx
@@ -2,6 +2,7 @@
 
 import { useEffect, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
+import { SegmentedControl, Collapsible } from "@/shared/components";
 
 type RtkFilter = {
   id: string;
@@ -66,6 +67,7 @@ export default function RtkContextPageClient() {
   const [sample, setSample] = useState(SAMPLE_OUTPUT);
   const [preview, setPreview] = useState<PreviewResult | null>(null);
   const [saving, setSaving] = useState(false);
+  const [viewMode, setViewMode] = useState<"simple" | "advanced">("simple");
 
   useEffect(() => {
     fetch("/api/context/rtk/filters")
@@ -140,12 +142,22 @@ export default function RtkContextPageClient() {
   return (
     <div className="mx-auto flex max-w-6xl flex-col gap-6">
       <header className="flex flex-col gap-2">
-        <div className="flex items-center gap-3">
-          <span className="material-symbols-outlined text-[30px] text-primary">filter_alt</span>
-          <div>
-            <h1 className="text-2xl font-bold text-text-main">{t("title")}</h1>
-            <p className="text-sm text-text-muted">{t("description")}</p>
+        <div className="flex items-center justify-between gap-3">
+          <div className="flex items-center gap-3">
+            <span className="material-symbols-outlined text-[30px] text-primary">filter_alt</span>
+            <div>
+              <h1 className="text-2xl font-bold text-text-main">{t("title")}</h1>
+              <p className="text-sm text-text-muted">{t("description")}</p>
+            </div>
           </div>
+          <SegmentedControl
+            value={viewMode}
+            onChange={(v) => setViewMode(v as "simple" | "advanced")}
+            options={[
+              { value: "simple", label: t("simpleMode") || "Simple" },
+              { value: "advanced", label: t("advancedMode") || "Advanced" },
+            ]}
+          />
         </div>
       </header>
 
@@ -278,72 +290,84 @@ export default function RtkContextPageClient() {
         </section>
       )}
 
-      <section className="grid grid-cols-1 gap-4 xl:grid-cols-[1fr_1fr]">
-        <div className="rounded-lg border border-border bg-surface p-4">
-          <div className="mb-3 flex items-center justify-between">
-            <h2 className="text-sm font-semibold text-text-main">{t("filterTesting")}</h2>
-            <button
-              onClick={runPreview}
-              className="rounded-lg bg-primary px-3 py-2 text-sm font-medium text-white"
-            >
-              {t("run")}
-            </button>
-          </div>
-          <textarea
-            value={sample}
-            onChange={(event) => setSample(event.target.value)}
-            placeholder={t("pasteOutput")}
-            className="h-72 w-full rounded-lg border border-border bg-bg p-3 font-mono text-xs text-text-main"
-          />
-        </div>
-        <div className="rounded-lg border border-border bg-surface p-4">
-          <h2 className="mb-3 text-sm font-semibold text-text-main">{t("result")}</h2>
-          {preview?.detection && (
-            <p className="mb-2 text-xs text-text-muted">
-              {t("detected")}: {preview.detection.type} (
-              {Math.round(preview.detection.confidence * 100)}%)
-            </p>
-          )}
-          <pre className="h-72 overflow-auto rounded-lg border border-border bg-bg p-3 text-xs text-text-main">
-            {preview ? JSON.stringify(preview, null, 2) : t("previewEmpty")}
-          </pre>
-        </div>
-      </section>
-
-      <section className="grid grid-cols-1 gap-3 md:grid-cols-2 xl:grid-cols-3">
-        {Object.entries(groupedFilters).map(([category, items]) => (
-          <div key={category} className="rounded-lg border border-border bg-surface p-4">
-            <h2 className="text-sm font-semibold capitalize text-text-main">{category}</h2>
-            <div className="mt-3 space-y-3">
-              {items.map((filter) => {
-                const enabled = config ? !config.disabledFilters.includes(filter.id) : true;
-                return (
-                  <div
-                    key={filter.id}
-                    className="border-t border-border pt-3 first:border-t-0 first:pt-0"
-                  >
-                    <div className="flex items-start justify-between gap-3">
-                      <div className="min-w-0">
-                        <p className="text-sm font-medium text-text-main">{filter.name}</p>
-                        <p className="mt-1 text-xs text-text-muted">{filter.description}</p>
-                      </div>
-                      <input
-                        type="checkbox"
-                        checked={enabled}
-                        disabled={!config || saving}
-                        onChange={(event) => toggleFilter(filter.id, event.target.checked)}
-                      />
-                    </div>
-                    <p className="mt-2 font-mono text-[11px] text-text-muted">
-                      {filter.commandTypes.join(", ")}
-                    </p>
-                  </div>
-                );
-              })}
+      {viewMode === "advanced" && (
+        <section className="grid grid-cols-1 gap-4 xl:grid-cols-[1fr_1fr]">
+          <div className="rounded-lg border border-border bg-surface p-4">
+            <div className="mb-3 flex items-center justify-between">
+              <h2 className="text-sm font-semibold text-text-main">{t("filterTesting")}</h2>
+              <button
+                onClick={runPreview}
+                className="rounded-lg bg-primary px-3 py-2 text-sm font-medium text-white"
+              >
+                {t("run")}
+              </button>
             </div>
+            <textarea
+              value={sample}
+              onChange={(event) => setSample(event.target.value)}
+              placeholder={t("pasteOutput")}
+              className="h-72 w-full rounded-lg border border-border bg-bg p-3 font-mono text-xs text-text-main"
+            />
           </div>
-        ))}
-      </section>
+          <div className="rounded-lg border border-border bg-surface p-4">
+            <h2 className="mb-3 text-sm font-semibold text-text-main">{t("result")}</h2>
+            {preview?.detection && (
+              <p className="mb-2 text-xs text-text-muted">
+                {t("detected")}: {preview.detection.type} (
+                {Math.round(preview.detection.confidence * 100)}%)
+              </p>
+            )}
+            <pre className="h-72 overflow-auto rounded-lg border border-border bg-bg p-3 text-xs text-text-main">
+              {preview ? JSON.stringify(preview, null, 2) : t("previewEmpty")}
+            </pre>
+          </div>
+        </section>
+      )}
+
+      <Collapsible
+        title={t("filterCatalog") || "Filter Catalog"}
+        subtitle={t("filterCatalogDesc") || "Available output filters by category"}
+        icon="filter_list"
+        trailing={
+          <span className="text-xs text-text-muted">
+            {Object.values(groupedFilters).flat().length} {t("filtersActive") || "filters"}
+          </span>
+        }
+        defaultOpen={viewMode === "advanced"}
+      >
+        <div className="grid grid-cols-1 gap-3 md:grid-cols-2 xl:grid-cols-3">
+          {Object.entries(groupedFilters).map(([category, items]) => (
+            <div key={category} className="rounded-lg border border-border bg-bg p-3">
+              <h3 className="text-xs font-semibold capitalize text-text-main">{category}</h3>
+              <div className="mt-2 space-y-2">
+                {items.map((filter) => {
+                  const enabled = config ? !config.disabledFilters.includes(filter.id) : true;
+                  return (
+                    <div
+                      key={filter.id}
+                      className="border-t border-border pt-2 first:border-t-0 first:pt-0"
+                    >
+                      <div className="flex items-start justify-between gap-2">
+                        <div className="min-w-0">
+                          <p className="text-xs font-medium text-text-main">{filter.name}</p>
+                          <p className="mt-0.5 text-[11px] text-text-muted">{filter.description}</p>
+                        </div>
+                        <input
+                          type="checkbox"
+                          checked={enabled}
+                          disabled={!config || saving}
+                          onChange={(event) => toggleFilter(filter.id, event.target.checked)}
+                          className="mt-0.5"
+                        />
+                      </div>
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+          ))}
+        </div>
+      </Collapsible>
     </div>
   );
 }

From 8afaca4b9fe9bd9b1d492aea7ce95c8c42a0c7f4 Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 05:41:50 +0700
Subject: [PATCH 4/7] feat(i18n): add simple/advanced mode keys for Caveman and
 RTK pages

---
 src/i18n/messages/en.json | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json
index 1ae9bbfd8a..f865e59fb2 100644
--- a/src/i18n/messages/en.json
+++ b/src/i18n/messages/en.json
@@ -3854,7 +3854,11 @@
     "tokensFiltered": "Tokens filtered",
     "filtersActive": "Filters active",
     "requests": "Requests",
-    "avgSavings": "Avg savings"
+    "avgSavings": "Avg savings",
+    "simpleMode": "Simple",
+    "advancedMode": "Advanced",
+    "filterCatalog": "Filter Catalog",
+    "filterCatalogDesc": "Available output filters by category"
   },
   "contextCombos": {
     "title": "Compression Combos",
@@ -3897,6 +3901,8 @@
     "autoClarity": "Auto-Clarity Bypass",
     "bypassConditions": "Bypass conditions",
     "bypassConditionsList": "security, irreversible, clarification, order-sensitive",
+    "simpleMode": "Simple",
+    "advancedMode": "Advanced",
     "preview": {
       "lite": "Respond concise. Preserve technical terms, code, errors, URLs, and identifiers.",
       "full": "Respond terse and compact. Preserve all technical substance.",

From 13ca2cc62a6520f2f59a4b2ad91141c108b3e127 Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 05:56:05 +0700
Subject: [PATCH 5/7] feat(ui): add sidebar item subtitles for confusing
 navigation items

Add subtitleKey to SidebarItemDefinition and render subtitles under
sidebar labels for: Endpoints, API Manager, Combos, Batch, Caveman,
RTK, and Webhooks. Helps non-technical users understand navigation.
---
 src/i18n/messages/en.json                 |  7 ++++
 src/shared/components/Sidebar.tsx         | 15 ++++++--
 src/shared/constants/sidebarVisibility.ts | 43 ++++++++++++++++++++---
 3 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json
index f865e59fb2..69d9652f50 100644
--- a/src/i18n/messages/en.json
+++ b/src/i18n/messages/en.json
@@ -677,9 +677,16 @@
     "docs": "Docs",
     "issues": "Issues",
     "endpoints": "Endpoints",
+    "endpointsSubtitle": "Your AI connection URLs",
     "apiManager": "API Manager",
+    "apiManagerSubtitle": "Manage API keys and access",
     "logs": "Logs",
     "webhooks": "Webhooks",
+    "webhooksSubtitle": "Get notified of events",
+    "combosSubtitle": "Group providers for failover",
+    "batchSubtitle": "Process multiple requests",
+    "contextCavemanSubtitle": "Prompt compression",
+    "contextRtkSubtitle": "Output filtering",
     "auditLog": "Audit Log",
     "shutdown": "Shutdown",
     "restart": "Restart",
diff --git a/src/shared/components/Sidebar.tsx b/src/shared/components/Sidebar.tsx
index e42443f7dc..83ceb61bbe 100644
--- a/src/shared/components/Sidebar.tsx
+++ b/src/shared/components/Sidebar.tsx
@@ -131,7 +131,11 @@ export default function Sidebar({
       ...section,
       title: getSidebarLabel(section.titleKey, section.titleFallback),
       items: section.items
-        .map((item) => ({ ...item, label: t(item.i18nKey) }))
+        .map((item) => ({
+          ...item,
+          label: t(item.i18nKey),
+          subtitle: item.subtitleKey ? t(item.subtitleKey) : undefined,
+        }))
         .filter((item) => !hiddenSidebarSet.has(item.id)),
     }))
     .filter((section) => section.items.length > 0);
@@ -156,7 +160,14 @@ export default function Sidebar({
     const content = (
       <>
         <span className={iconClassName}>{item.icon}</span>
-        {!collapsed && <span className="text-sm font-medium">{item.label}</span>}
+        {!collapsed && (
+          <div className="flex flex-col min-w-0">
+            <span className="text-sm font-medium">{item.label}</span>
+            {item.subtitle && (
+              <span className="text-[10px] text-text-muted/60 truncate">{item.subtitle}</span>
+            )}
+          </div>
+        )}
       </>
     );
 
diff --git a/src/shared/constants/sidebarVisibility.ts b/src/shared/constants/sidebarVisibility.ts
index 68622a0aa3..04b514ad20 100644
--- a/src/shared/constants/sidebarVisibility.ts
+++ b/src/shared/constants/sidebarVisibility.ts
@@ -40,6 +40,7 @@ export interface SidebarItemDefinition {
   id: HideableSidebarItemId;
   href: string;
   i18nKey: string;
+  subtitleKey?: string;
   icon: string;
   exact?: boolean;
   external?: boolean;
@@ -56,11 +57,35 @@ export interface SidebarSectionDefinition {
 
 const PRIMARY_SIDEBAR_ITEMS: readonly SidebarItemDefinition[] = [
   { id: "home", href: "/dashboard", i18nKey: "home", icon: "home", exact: true },
-  { id: "endpoints", href: "/dashboard/endpoint", i18nKey: "endpoints", icon: "api" },
-  { id: "api-manager", href: "/dashboard/api-manager", i18nKey: "apiManager", icon: "vpn_key" },
+  {
+    id: "endpoints",
+    href: "/dashboard/endpoint",
+    i18nKey: "endpoints",
+    subtitleKey: "endpointsSubtitle",
+    icon: "api",
+  },
+  {
+    id: "api-manager",
+    href: "/dashboard/api-manager",
+    i18nKey: "apiManager",
+    subtitleKey: "apiManagerSubtitle",
+    icon: "vpn_key",
+  },
   { id: "providers", href: "/dashboard/providers", i18nKey: "providers", icon: "dns" },
-  { id: "combos", href: "/dashboard/combos", i18nKey: "combos", icon: "layers" },
-  { id: "batch", href: "/dashboard/batch", i18nKey: "batch", icon: "view_list" },
+  {
+    id: "combos",
+    href: "/dashboard/combos",
+    i18nKey: "combos",
+    subtitleKey: "combosSubtitle",
+    icon: "layers",
+  },
+  {
+    id: "batch",
+    href: "/dashboard/batch",
+    i18nKey: "batch",
+    subtitleKey: "batchSubtitle",
+    icon: "view_list",
+  },
   { id: "costs", href: "/dashboard/costs", i18nKey: "costs", icon: "account_balance_wallet" },
   { id: "analytics", href: "/dashboard/analytics", i18nKey: "analytics", icon: "analytics" },
   { id: "cache", href: "/dashboard/cache", i18nKey: "cache", icon: "cached" },
@@ -82,12 +107,14 @@ const CONTEXT_SIDEBAR_ITEMS: readonly SidebarItemDefinition[] = [
     id: "context-caveman",
     href: "/dashboard/context/caveman",
     i18nKey: "contextCaveman",
+    subtitleKey: "contextCavemanSubtitle",
     icon: "compress",
   },
   {
     id: "context-rtk",
     href: "/dashboard/context/rtk",
     i18nKey: "contextRtk",
+    subtitleKey: "contextRtkSubtitle",
     icon: "filter_alt",
   },
   {
@@ -112,7 +139,13 @@ const DEBUG_SIDEBAR_ITEMS: readonly SidebarItemDefinition[] = [
 const SYSTEM_SIDEBAR_ITEMS: readonly SidebarItemDefinition[] = [
   { id: "logs", href: "/dashboard/logs", i18nKey: "logs", icon: "description" },
   { id: "audit", href: "/dashboard/audit", i18nKey: "auditLog", icon: "policy" },
-  { id: "webhooks", href: "/dashboard/webhooks", i18nKey: "webhooks", icon: "webhook" },
+  {
+    id: "webhooks",
+    href: "/dashboard/webhooks",
+    i18nKey: "webhooks",
+    subtitleKey: "webhooksSubtitle",
+    icon: "webhook",
+  },
   { id: "health", href: "/dashboard/health", i18nKey: "health", icon: "health_and_safety" },
   { id: "proxy", href: "/dashboard/system/proxy", i18nKey: "proxy", icon: "dns" },
   { id: "settings", href: "/dashboard/settings", i18nKey: "settings", icon: "settings" },

From 8a23c5527e660b4219cd9ad2dc0631f0299aafec Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 05:58:41 +0700
Subject: [PATCH 6/7] feat(ui): replace cryptic error badges with
 human-readable labels

Replace AUTH/429/5XX/NET/RUNTIME with Auth/Rate limited/Server
error/Network/Runtime in provider error badges.
---
 src/app/(dashboard)/dashboard/providers/page.tsx | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/app/(dashboard)/dashboard/providers/page.tsx b/src/app/(dashboard)/dashboard/providers/page.tsx
index ab3a1c583b..4c752a757c 100644
--- a/src/app/(dashboard)/dashboard/providers/page.tsx
+++ b/src/app/(dashboard)/dashboard/providers/page.tsx
@@ -65,18 +65,18 @@ function getConnectionErrorTag(connection) {
   if (!connection) return null;
 
   const explicitType = connection.lastErrorType;
-  if (explicitType === "runtime_error") return "RUNTIME";
+  if (explicitType === "runtime_error") return "Runtime";
   if (
     explicitType === "upstream_auth_error" ||
     explicitType === "auth_missing" ||
     explicitType === "token_refresh_failed" ||
     explicitType === "token_expired"
   ) {
-    return "AUTH";
+    return "Auth";
   }
-  if (explicitType === "upstream_rate_limited") return "429";
-  if (explicitType === "upstream_unavailable") return "5XX";
-  if (explicitType === "network_error") return "NET";
+  if (explicitType === "upstream_rate_limited") return "Rate limited";
+  if (explicitType === "upstream_unavailable") return "Server error";
+  if (explicitType === "network_error") return "Network";
 
   const numericCode = Number(connection.errorCode);
   if (Number.isFinite(numericCode) && numericCode >= 400) {
@@ -84,19 +84,19 @@ function getConnectionErrorTag(connection) {
   }
 
   const fromMessage = getErrorCode(connection.lastError);
-  if (fromMessage === "401" || fromMessage === "403") return "AUTH";
+  if (fromMessage === "401" || fromMessage === "403") return "Auth";
   if (fromMessage && fromMessage !== "ERR") return fromMessage;
 
   const msg = (connection.lastError || "").toLowerCase();
   if (msg.includes("runtime") || msg.includes("not runnable") || msg.includes("not installed"))
-    return "RUNTIME";
+    return "Runtime";
   if (
     msg.includes("invalid api key") ||
     msg.includes("token invalid") ||
     msg.includes("revoked") ||
     msg.includes("unauthorized")
   )
-    return "AUTH";
+    return "Auth";
 
   return "ERR";
 }

From a4a870cda3a7b15327207ce47df22ea573b2d5e0 Mon Sep 17 00:00:00 2001
From: oyi77 <oyi77@users.noreply.github.com>
Date: Sun, 17 May 2026 07:56:22 +0700
Subject: [PATCH 7/7] feat(ui): add newbie-friendly UX improvements across
 dashboard

- Providers page: empty state with guided 'Add your first provider' card
- Providers page: home page shows only configured providers by default
- Settings: add intro text to Routing, Resilience, and AI tabs
- i18n: fix 'Api Key Mgmt' to 'API Key Management', remove duplicate key
- i18n: add keys for empty state, settings intros, free-only filter
---
 .../(dashboard)/dashboard/HomePageClient.tsx  | 33 +++++++++++++-----
 .../(dashboard)/dashboard/providers/page.tsx  | 34 +++++++++++++++++++
 .../(dashboard)/dashboard/settings/page.tsx   | 18 +++++++++-
 src/i18n/messages/en.json                     | 15 ++++++--
 4 files changed, 88 insertions(+), 12 deletions(-)

diff --git a/src/app/(dashboard)/dashboard/HomePageClient.tsx b/src/app/(dashboard)/dashboard/HomePageClient.tsx
index c9b4d06e34..2c39d93630 100644
--- a/src/app/(dashboard)/dashboard/HomePageClient.tsx
+++ b/src/app/(dashboard)/dashboard/HomePageClient.tsx
@@ -787,14 +787,31 @@ export default function HomePageClient({ machineId }: HomePageClientProps) {
         </div>
 
         <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-3">
-          {providerStats.map((item) => (
-            <ProviderOverviewCard
-              key={item.id}
-              item={item}
-              metrics={providerMetrics[item.provider.alias] || providerMetrics[item.id]}
-              onClick={() => setSelectedProvider(item)}
-            />
-          ))}
+          {providerStats
+            .filter((item) => item.total > 0)
+            .map((item) => (
+              <ProviderOverviewCard
+                key={item.id}
+                item={item}
+                metrics={providerMetrics[item.provider.alias] || providerMetrics[item.id]}
+                onClick={() => setSelectedProvider(item)}
+              />
+            ))}
+          {providerStats.filter((item) => item.total > 0).length === 0 && (
+            <div className="col-span-full py-8 text-center">
+              <span className="material-symbols-outlined text-[32px] text-text-muted/40">dns</span>
+              <p className="text-sm text-text-muted mt-2">
+                {t("noProvidersConfigured") || "No providers configured yet"}
+              </p>
+              <Link
+                href="/dashboard/providers"
+                className="inline-flex items-center gap-1 mt-2 text-xs text-primary hover:underline"
+              >
+                {t("addProvider") || "Add a provider"}{" "}
+                <span className="material-symbols-outlined text-[14px]">arrow_forward</span>
+              </Link>
+            </div>
+          )}
         </div>
       </Card>
 
diff --git a/src/app/(dashboard)/dashboard/providers/page.tsx b/src/app/(dashboard)/dashboard/providers/page.tsx
index 4c752a757c..2cad07fd78 100644
--- a/src/app/(dashboard)/dashboard/providers/page.tsx
+++ b/src/app/(dashboard)/dashboard/providers/page.tsx
@@ -541,6 +541,40 @@ export default function ProvidersPage() {
     );
   }
 
+  const totalConfigured =
+    oauthProviderEntriesAll.filter((e) => Number(e.stats?.total || 0) > 0).length +
+    apiKeyProviderEntriesAll.filter((e) => Number(e.stats?.total || 0) > 0).length +
+    webCookieProviderEntriesAll.filter((e) => Number(e.stats?.total || 0) > 0).length +
+    localProviderEntriesAll.filter((e) => Number(e.stats?.total || 0) > 0).length;
+
+  if (totalConfigured === 0 && !searchQuery) {
+    return (
+      <div className="flex flex-col items-center justify-center py-20 text-center">
+        <div className="flex items-center justify-center size-16 rounded-full bg-primary/10 mb-4">
+          <span className="material-symbols-outlined text-[32px] text-primary">dns</span>
+        </div>
+        <h2 className="text-xl font-semibold text-text-main">
+          {t("addFirstProvider") || "Add your first provider"}
+        </h2>
+        <p className="text-sm text-text-muted mt-2 max-w-md">
+          {t("addFirstProviderDesc") ||
+            "Connect an AI provider to start routing requests through OmniRoute. You can use free providers, API keys, or OAuth accounts."}
+        </p>
+        <div className="flex items-center gap-3 mt-4">
+          <a
+            href="https://docs.omniroute.io/providers"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-1.5 px-4 py-2 text-sm font-medium rounded-lg border border-border text-text-muted hover:text-text-main hover:bg-bg-subtle transition-colors"
+          >
+            <span className="material-symbols-outlined text-[16px]">help</span>
+            {t("learnMore") || "Learn more"}
+          </a>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div className="flex flex-col gap-6">
       {/* Search Bar */}
diff --git a/src/app/(dashboard)/dashboard/settings/page.tsx b/src/app/(dashboard)/dashboard/settings/page.tsx
index ecc54f1133..aa4cdb90cc 100644
--- a/src/app/(dashboard)/dashboard/settings/page.tsx
+++ b/src/app/(dashboard)/dashboard/settings/page.tsx
@@ -93,6 +93,10 @@ export default function SettingsPage() {
 
           {activeTab === "ai" && (
             <div className="flex flex-col gap-6">
+              <p className="text-sm text-text-muted">
+                {t("aiSettingsIntro") ||
+                  "AI-specific settings for thinking budget, model behavior, and compression."}
+              </p>
               <ThinkingBudgetTab />
               <Link
                 href="/dashboard/context/caveman"
@@ -124,6 +128,10 @@ export default function SettingsPage() {
 
           {activeTab === "routing" && (
             <div className="flex flex-col gap-6">
+              <p className="text-sm text-text-muted">
+                {t("routingSettingsIntro") ||
+                  "Controls how your requests are routed, transformed, and sent to AI providers."}
+              </p>
               <RoutingTab />
               <ModelRoutingSection />
               <ComboDefaultsTab />
@@ -132,7 +140,15 @@ export default function SettingsPage() {
             </div>
           )}
 
-          {activeTab === "resilience" && <ResilienceTab />}
+          {activeTab === "resilience" && (
+            <div className="flex flex-col gap-6">
+              <p className="text-sm text-text-muted">
+                {t("resilienceSettingsIntro") ||
+                  "Automatic retry, cooldown, and fallback when providers fail."}
+              </p>
+              <ResilienceTab />
+            </div>
+          )}
 
           {activeTab === "advanced" && (
             <div className="flex flex-col gap-6">
diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json
index 69d9652f50..efe8a5e14e 100644
--- a/src/i18n/messages/en.json
+++ b/src/i18n/messages/en.json
@@ -365,6 +365,10 @@
     "apiKeyForCheck": "Api Key For Check",
     "cloudRequestTimeout": "Cloud Request Timeout",
     "showConfiguredOnly": "Show Configured Only",
+    "showFreeOnly": "Free only",
+    "addFirstProvider": "Add your first provider",
+    "addFirstProviderDesc": "Connect an AI provider to start routing requests through OmniRoute. You can use free providers, API keys, or OAuth accounts.",
+    "learnMore": "Learn more",
     "includeDomains": "Include Domains",
     "promptCache": "Prompt Cache",
     "cloudConnected": "Cloud Connected",
@@ -405,7 +409,7 @@
     "expirationBannerExpiringSoonDesc": "Expiration Banner Expiring Soon Desc",
     "source": "Source",
     "failed": "Failed",
-    "apiKeyMgmt": "Api Key Mgmt",
+    "apiKeyMgmt": "API Key Management",
     "mcpQuickStartStep1": "Mcp Quick Start Step1",
     "runTest": "Run Test",
     "loadingFallbackChains": "Loading Fallback Chains",
@@ -905,6 +909,8 @@
     "providersOverview": "Providers Overview",
     "configuredOf": "{configured} configured of {total} available providers",
     "noModelsAvailable": "No models available for this provider.",
+    "noProvidersConfigured": "No providers configured yet",
+    "addProvider": "Add a provider",
     "configureFirst": "Configure a connection first in {providers}",
     "configureProvider": "Configure Provider",
     "modelAvailable": "{count} model available",
@@ -2618,7 +2624,6 @@
     "welcomeDesc": "OmniRoute is your local AI API proxy. It routes requests to multiple AI providers with load balancing, failover, and usage tracking.",
     "multiProvider": "Multi-Provider",
     "usageTracking": "Usage Tracking",
-    "apiKeyMgmt": "API Key Mgmt",
     "securityDesc": "Set a password to protect your dashboard, or skip for now.",
     "providerDesc": "Connect your first AI provider. You can add more later.",
     "apiKeyRequired": "API Key (required)",
@@ -2637,7 +2642,8 @@
     "failedSetPassword": "Failed to set password. Try again.",
     "failedAddProvider": "Failed to add provider. Try again.",
     "connectionError": "Connection error. Please try again.",
-    "provider": "Provider"
+    "provider": "Provider",
+    "apiKeyHelp": "An API key is a password for AI services. Get one from your provider's website (e.g., platform.openai.com, console.anthropic.com)."
   },
   "providers": {
     "title": "Providers",
@@ -3148,6 +3154,9 @@
     "routing": "Routing",
     "cache": "Cache",
     "resilience": "Resilience",
+    "routingSettingsIntro": "Controls how your requests are routed, transformed, and sent to AI providers.",
+    "resilienceSettingsIntro": "Automatic retry, cooldown, and fallback when providers fail.",
+    "aiSettingsIntro": "AI-specific settings for thinking budget, model behavior, and compression.",
     "systemPrompt": "System Prompt",
     "thinkingBudget": "Thinking Budget",
     "proxy": "Proxy",