docs: llmo config 2 better patch docs

docs/openapi/customer-config-api.yaml

@@ -119,16 +119,23 @@ llmo-customer-config-by-space-cat-id-v2:
       Merges the provided partial configuration with the existing configuration in S3.
       This allows incremental updates without sending the entire config.
 
+      **Merge Behavior:**
       - Only the fields provided in the request will be updated
-      - Arrays (brands, categories, topics) are merged by ID
+      - Top-level arrays (brands, categories, topics) are merged by ID
+      - Within a brand, if you provide an array field (brandAliases, competitors, urls, socialAccounts, prompts), it **replaces** the entire array
+      - To add items to an existing array, include all existing items plus new ones
       - Unchanged items preserve their metadata (updatedBy, updatedAt)
       - Modified or new items get updated metadata with current user and timestamp
 
-      Use this endpoint to:
+      **Use Cases:**
       - Add new brands without affecting existing ones
-      - Update specific categories or topics
+      - Update specific brand fields (description, vertical, aliases, competitors, URLs, etc.)
       - Add prompts to existing brands
-      - Update brand metadata
+      - Update categories or topics
+
+      **Array Replacement Example:**
+      If a brand has `brandAliases: [{name: "PS"}]` and you PATCH with `brandAliases: [{name: "Photoshop"}]`,
+      the result will be `brandAliases: [{name: "Photoshop"}]` (not both).
 
       The endpoint tracks and returns statistics about what was modified.
     operationId: patchCustomerConfigBySpaceCatIdV2
@@ -158,15 +165,20 @@ llmo-customer-config-by-space-cat-id-v2:
                         - value: "https://example.com"
                           regions: ["US"]
                       prompts: []
+            updateSingleBrand:
+              $ref: './examples.yaml#/customer-config-v2-patch-update-single-brand'
+            addPromptsToBrand:
+              $ref: './examples.yaml#/customer-config-v2-patch-add-prompts-to-brand'
+            updateBrandAliases:
+              $ref: './examples.yaml#/customer-config-v2-patch-update-brand-aliases'
+            updateBrandCompetitors:
+              $ref: './examples.yaml#/customer-config-v2-patch-update-brand-competitors'
+            updateBrandUrls:
+              $ref: './examples.yaml#/customer-config-v2-patch-update-brand-urls'
+            updateMultipleBrandFields:
+              $ref: './examples.yaml#/customer-config-v2-patch-update-multiple-brand-fields'
             updateCategory:
-              summary: Update specific categories
-              value:
-                customer:
-                  categories:
-                    - id: "category-1"
-                      name: "Updated Category Name"
-                      status: "active"
-                      origin: "human"
+              $ref: './examples.yaml#/customer-config-v2-patch-update-category'
     responses:
       '200':
         description: Customer configuration updated successfully

docs/openapi/examples.yaml

@@ -631,4 +631,145 @@ customer-config-v2-patch:
               origin: "manual"
               source: "api"
               categoryId: "859b91c5-0420-4f3b-a464-8d6f6ac34f64"
-              topicId: "topic-acrobat-features"
+              topicId: "topic-acrobat-features"
+customer-config-v2-patch-update-single-brand:
+  description: Example for updating a single existing brand via PATCH
+  value:
+    customer:
+      brands:
+        - id: "adobe-photoshop"
+          name: "Adobe Photoshop"
+          description: "Updated brand description for Photoshop"
+          vertical: "Software & Technology"
+          status: "active"
+customer-config-v2-patch-add-prompts-to-brand:
+  description: |
+    Example for adding prompts to an existing brand via PATCH.
+    Note: The prompts array replaces the existing array entirely.
+    To add prompts, include existing ones plus new ones.
+  value:
+    customer:
+      brands:
+        - id: "adobe-photoshop"
+          name: "Adobe Photoshop"
+          status: "active"
+          prompts:
+            - id: "photoshop-prompt-new-1"
+              prompt: "What are the new AI features in Photoshop?"
+              status: "active"
+              regions: ["us", "gb"]
+              origin: "human"
+              source: "api"
+              categoryId: "859b91c5-0420-4f3b-a464-8d6f6ac34f64"
+              topicId: "topic-acrobat-features"
+            - id: "photoshop-prompt-new-2"
+              prompt: "How to use neural filters in Photoshop?"
+              status: "active"
+              regions: ["us"]
+              origin: "human"
+              source: "api"
+              categoryId: "859b91c5-0420-4f3b-a464-8d6f6ac34f64"
+              topicId: "topic-acrobat-features"
+customer-config-v2-patch-update-category:
+  description: Example for updating a specific category via PATCH
+  value:
+    customer:
+      categories:
+        - id: "859b91c5-0420-4f3b-a464-8d6f6ac34f64"
+          name: "Product Features - Updated"
+          status: "active"
+          origin: "human"
+customer-config-v2-patch-update-brand-aliases:
+  description: |
+    Example for updating brand aliases via PATCH.
+    Note: The brandAliases array replaces the existing array entirely.
+    To add aliases, include existing ones plus new ones.
+  value:
+    customer:
+      brands:
+        - id: "adobe-photoshop"
+          name: "Adobe Photoshop"
+          status: "active"
+          brandAliases:
+            - name: "Photoshop"
+              regions: ["US", "GB"]
+            - name: "PS"
+              regions: ["US"]
+            - name: "Adobe PS"
+              regions: ["GL"]
+customer-config-v2-patch-update-brand-competitors:
+  description: |
+    Example for updating brand competitors via PATCH.
+    Note: The competitors array replaces the existing array entirely.
+  value:
+    customer:
+      brands:
+        - id: "adobe-photoshop"
+          name: "Adobe Photoshop"
+          status: "active"
+          competitors:
+            - name: "GIMP"
+              url: "https://www.gimp.org"
+              regions: ["GL"]
+            - name: "Affinity Photo"
+              url: "https://affinity.serif.com/photo"
+              regions: ["US", "GB"]
+customer-config-v2-patch-update-brand-urls:
+  description: |
+    Example for updating brand URLs and social accounts via PATCH.
+    Note: Both urls and socialAccounts arrays replace existing arrays entirely.
+  value:
+    customer:
+      brands:
+        - id: "adobe-photoshop"
+          name: "Adobe Photoshop"
+          status: "active"
+          urls:
+            - value: "https://www.adobe.com/products/photoshop.html"
+              regions: ["US", "GB"]
+            - value: "https://www.adobe.com/fr/products/photoshop.html"
+              regions: ["FR"]
+          socialAccounts:
+            - platform: "twitter"
+              url: "https://x.com/Photoshop"
+              regions: ["GL"]
+            - platform: "instagram"
+              url: "https://instagram.com/photoshop"
+              regions: ["GL"]
+customer-config-v2-patch-update-multiple-brand-fields:
+  description: Example for updating multiple brand fields at once via PATCH
+  value:
+    customer:
+      brands:
+        - id: "adobe-photoshop"
+          name: "Adobe Photoshop"
+          status: "active"
+          description: "Industry-leading image editing software with AI-powered tools"
+          vertical: "Software & Technology"
+          region: ["GL", "US", "GB", "FR"]
+          urls:
+            - value: "https://www.adobe.com/products/photoshop.html"
+              regions: ["US", "GB"]
+          brandAliases:
+            - name: "Photoshop"
+              regions: ["GL"]
+            - name: "PS"
+              regions: ["US"]
+          competitors:
+            - name: "GIMP"
+              url: "https://www.gimp.org"
+              regions: ["GL"]
+          socialAccounts:
+            - platform: "twitter"
+              url: "https://x.com/Photoshop"
+              regions: ["GL"]
+          relatedBrands:
+            - name: "Adobe Lightroom"
+              url: "https://www.adobe.com/products/photoshop-lightroom.html"
+              regions: ["GL"]
+          earnedContent:
+            - name: "Wikipedia"
+              type: "encyclopedia"
+              coverage_scope: "product history and features"
+              url: "https://en.wikipedia.org/wiki/Adobe_Photoshop"
+              regions: ["GL"]