From 4982a2b0668841215c0ea445d9c9a03e8d347aad Mon Sep 17 00:00:00 2001
From: "eduardo.guedes" <eduardo.guedes@opus-software.com.br>
Date: Mon, 25 May 2026 16:27:41 -0300
Subject: [PATCH 1/2] docs: document `interface.marketplace.categories`

---
 .../object_structure/interface.mdx            | 50 ++++++++++++++++++-
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx
index f3f851650..2e2206c5f 100644
--- a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx
+++ b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx
@@ -685,14 +685,14 @@ interface:
 
 ## marketplace
 
-Enables/disables access to the Agent Marketplace.
+Enables/disables access to the Agent Marketplace and, optionally, defines custom categories used to organize agents within it.
 
 > **Deprecated for permission management.** Seeds the `MARKETPLACE` role permission at startup for the default `USER` role only. Prefer the [Admin Panel](/docs/features/admin_panel).
 
 **Key:**
 <OptionTable
   options={[
-    ['marketplace', 'Object', 'Configuration for Agent Marketplace access control.'],
+    ['marketplace', 'Object', 'Configuration for Agent Marketplace access control and custom categories.'],
   ]}
 />
 
@@ -701,6 +701,7 @@ Enables/disables access to the Agent Marketplace.
 <OptionTable
   options={[
     ['use', 'Boolean', 'Enables or disables marketplace access. Default: false'],
+    ['categories', 'Object', 'Optional. Configures default and custom marketplace categories. Only applied when use is true. See below.'],
   ]}
 />
 
@@ -716,3 +717,48 @@ interface:
   marketplace:
     use: true  # Enable marketplace access
 ```
+
+### categories
+
+Customizes the categories displayed in the Agent Marketplace. The list is synced to the database on startup: new entries are created, existing entries are updated, and custom entries removed from the YAML are deleted from the database. Categories are only synced when `marketplace.use` is `true`.
+
+**Key:**
+<OptionTable
+  options={[
+    ['categories', 'Object', 'Configuration for marketplace categories. Synced to the database on startup.'],
+  ]}
+/>
+
+**Sub-keys:**
+
+<OptionTable
+  options={[
+    ['enableDefaultCategories', 'Boolean', "When true, LibreChat's built-in default categories are kept active and appear before custom categories. Default: true"],
+    ['list', 'Array of Objects', 'Ordered list of custom categories. The declared order is preserved in the marketplace UI (after default categories when enableDefaultCategories is true).'],
+  ]}
+/>
+
+**`list` item sub-keys:**
+
+<OptionTable
+  options={[
+    ['value', 'String', 'Display name for the category. Stored lowercase internally and treated case-insensitively when matching existing categories.'],
+    ['description', 'String', 'Short description shown alongside the category in the marketplace.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="interface / marketplace / categories"
+interface:
+  marketplace:
+    use: true
+    categories:
+      enableDefaultCategories: true  # Built-in categories appear first
+      list:                          # Order here determines marketplace order
+        - value: "Education"
+          description: "Educational agents."
+        - value: "Productivity"
+          description: "Productivity agents."
+```
+
+> **Note:** Removing a custom category from `list` deletes it from the database on the next startup. Default categories are never deleted, `enableDefaultCategories: false` only hides them.

From ecf189d16b2d992e49533eaa5bec97ed741d1da5 Mon Sep 17 00:00:00 2001
From: Eduardo Cruz Guedes <eduardo9cruz@gmail.com>
Date: Thu, 6 Aug 2026 17:06:00 -0300
Subject: [PATCH 2/2] docs: document optional category label and built-in
 overrides

---
 .../object_structure/interface.mdx            | 54 ++++++++++++++++---
 1 file changed, 48 insertions(+), 6 deletions(-)

diff --git a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx
index 1101dce3c..2654122c4 100644
--- a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx
+++ b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx
@@ -1263,8 +1263,8 @@ Customizes the categories displayed in the Agent Marketplace. The list is synced
 
 <OptionTable
   options={[
-    ['enableDefaultCategories', 'Boolean', "When true, LibreChat's built-in default categories are kept active and appear before custom categories. Default: true"],
-    ['list', 'Array of Objects', 'Ordered list of custom categories. The declared order is preserved in the marketplace UI (after default categories when enableDefaultCategories is true).'],
+    ['enableDefaultCategories', 'Boolean', "When true, LibreChat's built-in default categories are kept active and appear before custom categories. When false they are hidden, except general. Default: true"],
+    ['list', 'Array of Objects', 'Ordered list of categories. The declared order is preserved in the marketplace UI (after default categories when enableDefaultCategories is true).'],
   ]}
 />
 
@@ -1272,8 +1272,9 @@ Customizes the categories displayed in the Agent Marketplace. The list is synced
 
 <OptionTable
   options={[
-    ['value', 'String', 'Display name for the category. Stored lowercase internally and treated case-insensitively when matching existing categories.'],
-    ['description', 'String', 'Short description shown alongside the category in the marketplace.'],
+    ['value', 'String', 'Required. Identifier for the category, and the display name when label is omitted. Stored lowercase internally and treated case-insensitively when matching existing categories.'],
+    ['label', 'String', 'Optional. Display name for the category. Falls back to value when omitted.'],
+    ['description', 'String', 'Optional. Short description shown alongside the category in the marketplace.'],
   ]}
 />
 
@@ -1287,8 +1288,49 @@ interface:
       list:                          # Order here determines marketplace order
         - value: "Education"
           description: "Educational agents."
-        - value: "Productivity"
+        - value: "productivity"
+          label: "Productivity & Focus"  # Optional, defaults to value
           description: "Productivity agents."
 ```
 
-> **Note:** Removing a custom category from `list` deletes it from the database on the next startup. Default categories are never deleted, `enableDefaultCategories: false` only hides them.
+#### Localized labels and descriptions
+
+`label` and `description` are displayed verbatim unless they start with `com_`, in which case the client resolves them as UI translation keys and renders the string for each user's own language. Omitting `label` displays `value` exactly as typed, in every locale.
+
+```yaml
+list:
+  - value: "support"
+    label: "com_agents_category_aftersales"              # localized per user
+    description: "com_agents_category_aftersales_description"
+  - value: "Education"                                   # shown as "Education" everywhere
+    description: "Educational agents."
+```
+
+<Callout type="warning">
+  A `com_` key must already exist in LibreChat's bundled locale files. Unknown keys are rendered
+  literally, so a typo shows up in the UI as `com_agents_category_typo` rather than falling back to
+  the category name.
+</Callout>
+
+#### Overriding built-in categories
+
+Declaring a `value` that matches a built-in category overrides that category's `label` and `description` instead of creating a new one. Fields you omit keep their existing values, so declaring only `value` changes nothing but visibility.
+
+An overridden category stays a built-in: it keeps its original position in the marketplace, is never deleted when removed from `list`, and remains active even when `enableDefaultCategories` is `false`. That last point is how you keep a subset of the built-in categories while hiding the rest.
+
+```yaml filename="interface / marketplace / categories"
+interface:
+  marketplace:
+    use: true
+    categories:
+      enableDefaultCategories: false   # hide the built-in categories...
+      list:
+        - value: "aftersales"          # ...except this one, renamed and kept visible
+          label: "Customer Success"
+        - value: "Education"
+          description: "Educational agents."
+```
+
+> **Note:** Removing a custom category from `list` deletes it from the database on the next startup. Built-in categories are never deleted, `enableDefaultCategories: false` only hides them.
+
+> **Note:** The `general` category stays active even when `enableDefaultCategories` is `false`, because it is the category assigned to agents created without one. Hiding it would leave those agents reachable only from the "All" tab. You can still rename it by declaring `general` in `list`.