@kvasar/openclaw-storyblok-plugin 0.2.5 → 0.2.7

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-storyblok",
   "name": "Storyblok Integration",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Provides tools to interact with Storyblok CMS via Management API and Delivery API. Supports stories, components, and space management.",
     "activation": {
     "onStartup": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kvasar/openclaw-storyblok-plugin",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "OpenClaw plugin — interact with Storyblok CMS via Management API and Delivery API",
   "type": "module",
   "main": "./dist/index.js",

package/skills/storyblok/SKILL.md

@@ -4,7 +4,7 @@ description: Comprehensive skill for interacting with Storyblok CMS: query conte
 license: Proprietary
 metadata:
   author: Jordi Marti
-  version: "2.5"
+  version: "2.4"
 allowed-tools: storyblok_get_space, storyblok_get_story, storyblok_list_stories, storyblok_get_components, storyblok_get_component, storyblok_create_story, storyblok_update_story, storyblok_publish_story, storyblok_unpublish_story, storyblok_create_asset_folder, storyblok_delete_asset_folder, storyblok_get_asset_folder, storyblok_create_component, storyblok_get_content_folders, storyblok_update_component, storyblok_update_component_folder, sessions_spawn, read, write, edit
 ---
 
@@ -16,12 +16,15 @@ Non-obvious behaviors that cause silent mistakes:
 
 - **`storyblok_get_story` requires a numeric ID only.** If you have a slug or UUID, first call `storyblok_list_stories` with `with_slug` or `by_uuids` to resolve the numeric ID.
 - **`storyblok_list_stories` does not return `content`.** Use `storyblok_get_story` for full content, or add `with_summary=true` for a lightweight field-type summary.
+- **`storyblok_update_story` is only for updating the story structure** — adding/removing components, reordering blocks, changing the story layout. It requires the full content object; always fetch first with `storyblok_get_story`, merge your changes, then send the complete object. Never use it for translations or field-level edits — partial content silently overwrites and loses existing fields.
 - **`publish=false` does NOT unpublish.** It saves as draft. To unpublish a live story, use `storyblok_unpublish_story`.
 - **`component_group_uuid` ≠ `component_group_id`.** When assigning a component to a folder, use the UUID field — not the numeric ID.
 - **Schema updates don't touch existing stories.** After `storyblok_update_component`, stories already using that component keep their old field values.
 - **`content` is a reserved component name.** Component `name` must be snake_case and must not be `content` alone.
 - **`force_update=true` causes a content conflict** if another user has the story open. Use only when necessary.
 - **Never create separate stories per language.** Always use field-level i18n keys inside the same story.
+- **Storyblok rich text fields are structured JSON objects, not strings.** Always preserve the complete Storyblok rich text schema (including `_uid`, `type`, `content`, and other properties). Never stringify rich text content before sending it to the Management API. This applies to both standard and translated rich text fields (`field_i18n_xx`).
+- **Never use `storyblok_update_story` to add language translations.** Use `storyblok_update_component` instead: fetch components with `storyblok_get_components`, iterate each relevant one with `storyblok_get_component`, add new `field_i18n_xx` keys, and call `storyblok_update_component`. Never remove existing translation keys unless the user explicitly asks.
 
 ---
 
@@ -35,11 +38,12 @@ Non-obvious behaviors that cause silent mistakes:
 | Inspect available block types | `storyblok_get_components` |
 | Full schema of one component | `storyblok_get_component` |
 | Create story | `storyblok_create_story` |
-| Edit story | `storyblok_update_story` |
+| Update story structure (add/remove/reorder components) | `storyblok_update_story` (full object) |
 | Publish | `storyblok_publish_story` or `publish=true` on create/update |
 | Unpublish | `storyblok_unpublish_story` only |
-| Create Component | `storyblok_create_component` |
+| Create/update component | `storyblok_create_component` |
 | Update the values of a component. |`storyblok_update_component` |
+
 ---
 
 ## Workflows
@@ -47,8 +51,10 @@ Non-obvious behaviors that cause silent mistakes:
 ### Content Management
 
 1. If content type is unknown, run `storyblok_get_components` first.
-2. Build `content` as a structured object matching the component schema (JSON string also accepted but object preferred).
+2. Build `content` as a structured object matching the component schema. For rich text fields (`type: "richtext"`), ensure the value is a valid Storyblok rich text JSON object with properties like `_uid`, `type`, `content`, etc. — never a plain string.
 3. Create or update the story.
+2. Use `storyblok_update_story` only to change story structure — adding/removing/reordering components or blocks. Always fetch first with `storyblok_get_story`, merge, then send the full object. Never use it for translations or field edits.
+3. For partial schema changes (add a field, rename a label), use `storyblok_update_component` instead — it patches only what you pass.
 4. Publish only on explicit user confirmation.
 5. To unpublish: `storyblok_unpublish_story` — never `update_story`.
 
@@ -56,7 +62,7 @@ Non-obvious behaviors that cause silent mistakes:
 
 1. Run `storyblok_get_components` to check if a component with the same name already exists.
 2. Decide type (`is_root`, `is_nestable`) before creating — restructuring after stories use it can break content.
-3. To update the entire story content `use storyblok_update_story` (full object required). To update only component schema fields use `storyblok_update_component` (partial, only what you pass changes). Never update partial using `storyblok_update_story` 
+3. To update the entire story content use `storyblok_update_story` (full object required). To update only component schema fields → `storyblok_update_component` (partial, only what you pass changes). Existing story values are NOT affected by component schema changes.
 4. Mark user-facing text fields `"translatable": true`; leave technical fields non-translatable.
 5. Do not create or delete components without user confirmation.
 
@@ -86,29 +92,26 @@ For AI-generated copy, spawn a sub-session via `sessions_spawn` with the same to
 Always use field-level i18n inside the **same** story — never separate stories per language.
 
 - Default language: English (unless specified)
-
--Store translations using Storyblok i18n field keys:
- -field_i18n_es
- -field_i18n_ca
- -field_i18n_de
- -etc.
- - Translation keys: `field_i18n_es`, `field_i18n_ca`, `field_i18n_de`, etc.
+- Translation keys: `field_i18n_es`, `field_i18n_ca`, `field_i18n_de`, etc.
 - Use SEO-friendly English slugs
 - Ensure `localized_paths` includes all enabled locales
 
+**Adding new language translations — correct workflow:**
+
+**Never use `storyblok_update_story` to add translations.** Use `storyblok_update_component` instead.
+
+1. Call `storyblok_get_components` to get the full list of components used in the space.
+2. For each relevant component, call `storyblok_get_component` to inspect its current schema and existing translation fields.
+3. For each component, add the new `field_i18n_xx` keys to the schema — **do not remove existing translation keys** unless the user explicitly asks.
+4. Call `storyblok_update_component` for each component with the merged schema.
+
 ```json
 {
-  "headline": "Why Most Strategies Fail",
+  "headline": { "type": "text", "pos": 0, "translatable": true },
   "headline_i18n_es": "Por qué fracasan la mayoría de las estrategias",
-  "headline_i18n_ca": "Per què fracassen la majoria d'estratègies"
+  "headline_i18n_ca": "Per què fracassen la majoria d'estratègies",
+  "headline_i18n_de": "Warum die meisten Strategien scheitern"
 }
 ```
 
-After completing multilingual work, confirm: languages added, field-level keys used, no separate stories created.
-
-## Notes
-
-- Always handle errors gracefully and report to the user.
-- Avoid publishing without explicit user consent.
-- For large exports, use pagination (`per_page`, `page`) to stay within response limits.
-- Respect rate limits: Storyblok API may have limits; consider adding delays if many requests.
+After completing multilingual work, confirm: languages added, existing translations preserved, `storyblok_update_component` used (not `update_story`), no separate stories created.