@kvasar/openclaw-storyblok-plugin 0.2.6 → 0.2.8

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-storyblok",
   "name": "Storyblok Integration",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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.6",
+  "version": "0.2.8",
   "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.4"
+  version: "2.6"
 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,14 +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`.
+- **`storyblok_update_story` requires the full content object.** Always fetch first with `storyblok_get_story`, merge your changes, then send the complete object. Never send a partial object — it silently overwrites and loses existing fields, blocks, assets, and translations.
+- **`storyblok_update_component` is for schema changes only.** Use it to add/modify field definitions in a component schema. Never use it to write actual translated content into a story.
+- **Never create separate stories per language.** Always use field-level i18n keys inside the same story.
+- **`publish=false` does NOT unpublish.** It saves as draft. To unpublish, 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.
-- **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.
+- **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`).
 
 ---
 
@@ -37,11 +38,10 @@ 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` |
-| Update story structure (add/remove/reorder components) | `storyblok_update_story` (full object) |
+| Update story structure or translated content | `storyblok_update_story` (full object required) |
+| Add/modify translatable field definitions in a component schema | `storyblok_update_component` |
 | Publish | `storyblok_publish_story` or `publish=true` on create/update |
 | Unpublish | `storyblok_unpublish_story` only |
-| Create/update component | `storyblok_create_component` |
-| Update the values of a component. |`storyblok_update_component` |
 
 ---
 
@@ -50,16 +50,16 @@ Non-obvious behaviors that cause silent mistakes:
 ### Content Management
 
 1. If content type is unknown, run `storyblok_get_components` first.
-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.
+2. To update a story (structure or content): fetch with `storyblok_get_story`, merge changes into the full object, send with `storyblok_update_story`. Never send partial content.
+3. To change a component schema (add a field definition, mark a field translatable): use `storyblok_update_component` — it patches only what you pass and does not affect existing story values.
+4. Save as draft unless the user explicitly asks to publish.
 5. To unpublish: `storyblok_unpublish_story` — never `update_story`.
 
 ### Component Management
 
 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 → `storyblok_update_component` (partial, only what you pass changes). Existing story values are NOT affected by component schema changes.
+3. Use `storyblok_update_component` for partial schema patches only (add a field, rename a label, mark translatable). It does not affect existing story values.
 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 +86,47 @@ For AI-generated copy, spawn a sub-session via `sessions_spawn` with the same to
 
 ## Multilingual Stories
 
-Always use field-level i18n inside the **same** story — never separate stories per language.
+Always use field-level i18n keys inside the **same** story — never create separate stories per language.
 
 - Default language: English (unless specified)
-- Translation keys: `field_i18n_es`, `field_i18n_ca`, `field_i18n_de`, etc.
+- i18n key format: `field__i18n__xx` (e.g. `headline__i18n__de`, `teaser__i18n__ca`)
 - Use SEO-friendly English slugs
 - Ensure `localized_paths` includes all enabled locales
 
-**Adding new language translations — correct workflow:**
+### Two separate cases
 
-**Never use `storyblok_update_story` to add translations.** Use `storyblok_update_component` instead.
+**A) Translate existing story content** → `storyblok_get_story` + `storyblok_update_story`
 
-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.
+**B) Add translatable field definitions to a component schema** → `storyblok_get_component` + `storyblok_update_component`
 
-```json
-{
-  "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_de": "Warum die meisten Strategien scheitern"
-}
-```
+Never mix these up: `storyblok_update_component` writes schema definitions, not story content.
+
+---
 
-After completing multilingual work, confirm: languages added, existing translations preserved, `storyblok_update_component` used (not `update_story`), no separate stories created.
+### A) Adding or updating a translation for an existing story
+
+1. Call `storyblok_get_story` with the numeric story ID to get the full current content.
+2. Inspect the content and identify the fields that need translation.
+3. Add the new i18n keys inside the same content object. Examples:
+   - `headline__i18n__de`
+   - `teaser__i18n__de`
+   - `text__i18n__de`
+   - `paragraphs__i18n__de`
+4. Preserve the full existing content object including `_uid`, `component`, nav references, nested blocks, assets, and all existing translations. **Do not remove any existing keys** unless the user explicitly asks.
+5. For rich text fields: preserve the full Storyblok rich text JSON structure. Translate only the `text` node values. Never stringify rich text.
+6. Call `storyblok_update_story` with the complete merged content object.
+7. Save as draft unless the user explicitly asks to publish.
+8. After updating, verify:
+   - New language fields exist
+   - Existing translations are still present
+   - Rich text is valid JSON (not a string)
+   - No separate story was created
+
+### B) Adding translatable field definitions to a component schema
+
+1. Call `storyblok_get_component` with the numeric component ID.
+2. Inspect the current schema and identify fields that need to be marked translatable.
+3. Add or update field definitions with `"translatable": true`. Do not remove existing fields unless the user asks.
+4. Call `storyblok_update_component` with the patched schema.
+
+After completing multilingual work, confirm: languages added, existing translations preserved, correct tool used (`update_story` for content, `update_component` for schema), no separate stories created.