From 2d3aa6129cdefbe9786bc7f0b517c5c789858bcf Mon Sep 17 00:00:00 2001
From: charliebirch <charlie.birch@relevanceai.com>
Date: Tue, 21 Apr 2026 10:06:09 +1000
Subject: [PATCH] fix(slide-builder): brand kit PUT is destructive, not a
 partial update

The "Update Brand Kit" section claimed "Partial update -- only provided
fields are changed". That contradicts the destructive-semantics warning
carried in the downstream SE Agent Builder docs:

- `.claude/rules/universal.md` "Brand Kits" section: PUT wipes any
  array field (colors, logos, inspiration_photos) that is omitted from
  the body; scalar fields (name, brand_tone, voice, fonts) are
  preserved. The fix pattern is fetch-merge-save.
- `build-kit/tools/platform-tool-gotchas.md` "Brand Kit API": same
  warning, with an additional note on the singular/plural endpoint
  naming mismatch (GET is `/branding_kit/{id}`, PUT/DELETE are
  `/branding_kits/{id}`).

Bringing the cc-plugin skill docs into alignment so every project
consuming this plugin gets the same guidance.

Changes:

- Rewrites the "Update Brand Kit" example as fetch-merge-save and adds
  a BAD counter-example showing the partial PUT that wipes arrays.
- Annotates the Brand Kit Endpoints table with the singular/plural
  naming inconsistency so future readers don't "fix" it.

Docs-only; no API contract change.
---
 .../skills/relevance-slide-builder/SKILL.md   | 51 ++++++++++++++-----
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/plugins/relevance-ai/skills/relevance-slide-builder/SKILL.md b/plugins/relevance-ai/skills/relevance-slide-builder/SKILL.md
index eb4d3e1..31025ae 100644
--- a/plugins/relevance-ai/skills/relevance-slide-builder/SKILL.md
+++ b/plugins/relevance-ai/skills/relevance-slide-builder/SKILL.md
@@ -75,16 +75,39 @@ const kit = await relevance_api_request({
 
 ### Update Brand Kit
 
-Partial update — only provided fields are changed.
+**CRITICAL: PUT has destructive semantics for array fields.** Any array you omit from the body (`colors`, `logos`, `inspiration_photos`) is wiped to `[]`. Scalar fields (`name`, `brand_tone`, `voice`, font objects) are preserved if omitted — it is only arrays that get reset.
+
+**Always fetch-merge-save** when updating a brand kit:
 
 ```typescript
+// 1. GET the full brand kit
+const existing = await relevance_api_request({
+  endpoint: `/branding_kit/${brandingKitId}`,
+  method: 'GET',
+});
+
+// 2. Merge your changes into the COMPLETE object
+const updated = {
+  ...existing,
+  brand_tone: 'Friendly and approachable',
+};
+
+// 3. PUT the full object (arrays included)
 await relevance_api_request({
   endpoint: `/branding_kits/${brandingKitId}`,
   method: 'PUT',
-  body: {
-    name: 'Updated Brand',
-    brand_tone: 'Friendly and approachable',
-  },
+  body: updated,
+});
+```
+
+Do NOT issue a partial PUT — `colors`, `logos`, and `inspiration_photos` will be wiped:
+
+```typescript
+// BAD: wipes all arrays
+await relevance_api_request({
+  endpoint: `/branding_kits/${brandingKitId}`,
+  method: 'PUT',
+  body: { brand_tone: 'new tone' },
 });
 ```
 
@@ -300,14 +323,16 @@ const { success } = await relevance_api_request({
 
 ### Brand Kit Endpoints
 
-| Method   | Endpoint                          | Description                         |
-| -------- | --------------------------------- | ----------------------------------- |
-| `GET`    | `/branding_kits`                  | List all brand kits                 |
-| `POST`   | `/branding_kits`                  | Create brand kit                    |
-| `GET`    | `/branding_kit/:branding_kit_id`  | Get brand kit                       |
-| `PUT`    | `/branding_kits/:branding_kit_id` | Update brand kit                    |
-| `DELETE` | `/branding_kits/:branding_kit_id` | Delete brand kit                    |
-| `POST`   | `/branding_kits/generate`         | Generate brand kit from images (AI) |
+| Method   | Endpoint                          | Description                                      |
+| -------- | --------------------------------- | ------------------------------------------------ |
+| `GET`    | `/branding_kits`                  | List all brand kits                              |
+| `POST`   | `/branding_kits`                  | Create brand kit                                 |
+| `GET`    | `/branding_kit/:branding_kit_id`  | Get brand kit (note: singular `branding_kit`)    |
+| `PUT`    | `/branding_kits/:branding_kit_id` | Update brand kit (destructive — see above)       |
+| `DELETE` | `/branding_kits/:branding_kit_id` | Delete brand kit                                 |
+| `POST`   | `/branding_kits/generate`         | Generate brand kit from images (AI)              |
+
+**Endpoint naming inconsistency:** `GET` uses singular `/branding_kit/{id}`, `PUT`/`DELETE` use plural `/branding_kits/{id}`. Both are correct — do not "fix" one to match the other.
 
 ### Slideshow Endpoints