@kvasar/openclaw-storyblok-plugin 0.2.2 → 0.2.4

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-storyblok",
   "name": "Storyblok Integration",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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.2",
+  "version": "0.2.4",
   "description": "OpenClaw plugin — interact with Storyblok CMS via Management API and Delivery API",
   "type": "module",
   "main": "./dist/index.js",

package/skills/storyblok/SKILL.md

@@ -1,536 +1,114 @@
 ---
 name: storyblok
-description: Comprehensive skill for interacting with Storyblok CMS: query content, manage stories, generate pages, and sync with frontend repositories.
-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
-
-author: Jordi Marti
-version: "2.1"
+description: Comprehensive skill for interacting with Storyblok CMS: query content, manage stories, create and update components, generate AI-assisted pages, and sync with frontend repositories. Use when the user mentions Storyblok, CMS content, stories, components, landing pages, or any content management task involving Storyblok.
+license: Proprietary
+metadata:
+  author: Jordi Marti
+  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
 ---
 
-
-
 # Storyblok Integration Skill
 
-This skill package provides agents with the ability to work with **Storyblok CMS** using the `openclaw-storyblok` plugin. It covers four main workflows:
-
-1. **Content Query** – Retrieve spaces, stories, components, and listings.
-2. **Content Management** – Create, update, publish, and unpublish stories.
-3. **Page Generation** – Use AI-assisted reasoning to create new landing pages.
-4. **Sync Workflow** – Synchronize content or schemas between Storyblok and a frontend repository.
-
-## Core Concepts
-
-
-### Storyblok Block Types
-
-Storyblok components can be organized into three structural categories:
-
-#### Nestable Block
-
-Reusable blocks that are inserted **inside other blocks or pages**.
+## Gotchas
 
-Examples:
+Non-obvious behaviors that cause silent mistakes:
 
-- Hero  
-- Grid  
-- Section  
-- Newsletter Section  
-- Chapter  
-- Full Width Image  
-- Slider  
-- CTA Banner  
-- Feature Grid  
-
-Use these when building modular page layouts.
+- **`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.
+- **`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.
 
 ---
 
-#### Content Type Block
-
-Top-level content models representing an entry/page/document.
-
-Examples:
-
-- Landing Page  
-- Post  
-- Authors  
-- Product  
-- Page  
-- Team Members  
-- FAQ Article  
-- Case Study  
-
-Use these as standalone entries in Storyblok.
+## Which tool to use
+
+| Goal | Tool |
+|------|------|
+| Space info | `storyblok_get_space` |
+| Single story with full content | `storyblok_get_story` (numeric ID) |
+| Find stories / list / filter | `storyblok_list_stories` |
+| 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` |
+| Publish | `storyblok_publish_story` or `publish=true` on create/update |
+| Unpublish | `storyblok_unpublish_story` only |
+| Create/update component | `storyblok_create_component` / `storyblok_update_component` |
 
 ---
 
-#### Universal Block
-
-A block that can be used **both as a content type and nested block**.
-
-Examples:
-
-- FAQ Section  
-- Testimonials  
-- Rich Text Section  
-- Gallery  
-- Reusable Promo Page  
-- Contact Section  
-
-Use when flexibility is needed across multiple content structures.
-
----
-
-## Tool Reference
-
-### Content Tools
-
-### Content Tools
-
-| Tool | Required params | Optional params |
-|------|----------------|-----------------|
-| `storyblok_get_space` | — | — |
-| `storyblok_get_story` | `identifier` (ID ) |
-| `storyblok_list_stories` | — | See parameter reference below |
-| `storyblok_get_components` | — | `version`, `language` |
-| `storyblok_get_component` | `component_id` | — |
-
-#### `storyblok_list_stories` — Parameter Reference
-
-**Pagination**
-| Param | Type | Description |
-|-------|------|-------------|
-| `page` | number | Page number for paginated results |
-| `per_page` | number | Number of results per page |
-
-**Search**
-| Param | Type | Description |
-|-------|------|-------------|
-| `text_search` | string | Full-text search across name, slug, full slug, and all content fields (UIDs, field values, asset filenames, rich text). Same as the search box in the Content UI. |
-| `search` | string | Lighter search: name, slug, or full slug only |
-| `reference_search` | string | Search referenced stories/assets by UUID, name, or asset URL |
-| `contain_component` | string | Filter by nestable block name(s). Comma-separated for multiple |
-| `filter_query` | string | Filter by content type fields. Syntax: `filter_query[field][operation]=value`. Supports comma-separated values |
-
-**Sorting**
-| Param | Type | Description |
-|-------|------|-------------|
-| `sort_by` | string | Sort by story property or content field. Examples: `created_at:desc`, `content.FIELD_NAME:asc`. Append `:int` or `:float` to sort numeric fields |
-
-**Fetch by ID / UUID / Slug**
-| Param | Type | Description |
-|-------|------|-------------|
-| `by_ids` | string | Comma-separated story IDs to retrieve |
-| `excluding_ids` | string | Comma-separated story IDs to exclude |
-| `by_uuids` | string | Comma-separated UUIDs to retrieve |
-| `by_uuids_ordered` | string | Comma-separated UUIDs; response order matches input order |
-| `with_slug` | string | Retrieve stories matching an exact full slug |
-| `by_slugs` | string | Comma-separated full slugs. Supports wildcard: `posts/*` |
-| `excluding_slugs` | string | Comma-separated full slugs to exclude. Supports wildcard: `posts*` |
-| `starts_with` | string | Filter stories whose slug starts with this string |
-
-**Hierarchy**
-| Param | Type | Description |
-|-------|------|-------------|
-| `with_parent` | number | Filter by parent folder ID |
-
-**Tags**
-| Param | Type | Description |
-|-------|------|-------------|
-| `with_tag` | string | Filter by tag name(s). Comma-separated for multiple |
-
-**Type Filters**
-| Param | Type | Description |
-|-------|------|-------------|
-| `folder_only` | boolean | Return only folder-type stories |
-| `story_only` | boolean | Return only non-folder stories |
-| `in_trash` | boolean | Return only deleted (trashed) stories |
-| `is_published` | boolean | `true` = published only · `false` = draft/unpublished only |
-| `mine` | boolean | Return only stories assigned to the current user's token |
-| `favourite` | boolean | Return only stories marked as favorites in the Content UI |
-
-**Workflow & Releases**
-| Param | Type | Description |
-|-------|------|-------------|
-| `in_workflow_stages` | string | Comma-separated workflow stage IDs |
-| `in_release` | number | Retrieve stories grouped in a release (use release ID) |
-
-**Scheduling**
-| Param | Type | Description |
-|-------|------|-------------|
-| `scheduled_at_gt` | string | Stories scheduled after this ISO UTC timestamp |
-| `scheduled_at_lt` | string | Stories scheduled before this ISO UTC timestamp |
-
-**Response Shaping**
-| Param | Type | Description |
-|-------|------|-------------|
-| `with_summary` | boolean | Include a `content_summary` object listing field types found in the story content |
-
-### Component Tools
-
-| Tool | Required params | Optional params |
-|------|----------------|-----------------|
-| `storyblok_create_component` | `name` | `display_name`, `schema`, `is_root`, `is_nestable`, `preview_field`, `preview_tmpl`, `component_group_uuid`, `icon`, `color`, `internal_tag_ids`, `content_type_asset_preview`, `image` |
-| `storyblok_update_component` | `component_id` | `name`, `display_name`, `schema`, `is_root`, `is_nestable`, `preview_field`, `preview_tmpl`, `component_group_uuid`, `icon`, `color`, `internal_tag_ids`, `content_type_asset_preview`, `image` |
-| `storyblok_get_component` | `component_id` | — |
-
-> **Note:** Use `component_group_uuid` (not `component_group_id`) — this is the UUID of the component folder.
+## Workflows
 
-### Component Folder Tools
+### Content Management
 
-| Tool | Required params | Optional params |
-|------|----------------|-----------------|
-| `storyblok_get_content_folders` | — | `search`, `with_parent` |
-| `storyblok_update_component_folder` | `component_group_id` | `name`, `parent_id` (number or null) |
+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).
+3. Create or update the story.
+4. Publish only on explicit user confirmation.
+5. To unpublish: `storyblok_unpublish_story` — never `update_story`.
 
-> **Note:** `parent_id` can be set to `null` to move a folder to the root level.
+### Component Management
 
-### Management Tools
+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. For updates, use minimal patches (add a field, update a label) rather than replacing the full schema.
+4. Mark user-facing text fields `"translatable": true`; leave technical fields non-translatable.
+5. Do not create or delete components without user confirmation.
 
-| Tool | Required params | Optional params |
-|------|----------------|-----------------|
-| `storyblok_create_story` | `name` | `slug`, `folder_id`, `parent_id`, `content`, `tag_list`, `is_folder`, `publish`, `release_id` |
-| `storyblok_update_story` | `story_id` | `name`, `slug`, `content`, `parent_id`, `tag_list`, `is_folder`, `publish`, `force_update`, `lang`, `release_id`, `group_id` |
-| `storyblok_publish_story` | `story_id` | `lang`, `release_id` |
-| `storyblok_unpublish_story` | `story_id` | `lang` |
-
-### Asset Folder Tools
-
-| Tool | Required params | Optional params |
-|------|----------------|-----------------|
-| `storyblok_create_asset_folder` | `name` | `parent_id` |
-| `storyblok_delete_asset_folder` | `folder_id` | — |
-| `storyblok_get_asset_folder` | `folder_id` | — |
-
-
-### Parameter Notes
-
-- Most tools accept optional parameters; only required fields are mandatory.
-- For `storyblok_get_story`, you can specify `version` (draft/published) and `language`.
-- For `storyblok_list_stories`, you can filter by `folder_id`, `parent_id`, `status`, `tag`, `per_page`, `page`, `sort_by`, `direction`.
-- For management tools, `story_id` can be numeric ID or UUID.
-- When constructing content objects, pass them as structured objects — never as JSON strings or stringified blobs.
-
-#### `storyblok_get_story`
-- `version`: `draft` or `published`. Defaults to `published`.
-- `language`: optional language code to retrieve a specific translation.
-
-#### `storyblok_list_stories`
-- Filter options: `folder_id`, `parent_id`, `status`, `tag`, `per_page`, `page`, `sort_by`, `direction`.
-- `story_id` can be a numeric ID or UUID.
-
-#### `storyblok_update_story`
-
-- `publish=true` publishes the story. `publish=false` saves as draft — it does **not** unpublish. Use `storyblok_unpublish_story` to unpublish.
-- `force_update="true"` forces an update even if the story is locked by another user (causes a content conflict — use with caution). Has no effect if the story is locked as part of a workflow stage.
-- `group_id`: UUID shared between stories defined as alternates (used for internationalization/variants).
-- `lang`: publishes a specific language version individually (must be enabled in space internationalization settings).
-- `content`: must be a structured object — never pass it as a JSON string or serialized value.
-
-#### `storyblok_update_component`
-
-- Component updates **do not** automatically update stories that already use this component. Existing story values are preserved.
-- Use minimal updates — only change the fields that need modification. Avoid replacing the entire `schema` unless necessary.
-- To add translatable fields, set `"translatable": true` in the field definition within the `schema`.
-- Read-only fields like `id`, `created_at`, `updated_at`, `all_presets`, `real_name`, `internal_tags_list` cannot be updated.
-- See section **3.1 Component Updates** for detailed guidance on schema migration and i18n considerations.
-
-## Workflow Guides
-
-### 1. Content Query
-
-Use the query tools to explore and retrieve data.
-
-**When to use what:**
-
-- Need space info? → `storyblok_get_space`
-- Need a specific story? → `storyblok_get_story` (provide `identifier`)
-- Need a list of stories with filters? → `storyblok_list_stories` (set filters)
-- Need to know available content block types? → `storyblok_get_components`
-- Need full details of a specific component? → `storyblok_get_component` (provide `component_id`)
-
-**Example: List all published stories in the last week**
-
-```sh
-storyblok_list_stories status="published" per_page=100
-```
-
-**Example: Get a story by slug**
-
-```sh
-storyblok_get_story identifier="my-landing-page" version="published"
-```
-
-### 2. Content Management
-
-Use the management tools to create, modify, and publish content.
-
-**Workflow:**
-
-- To create a new story: `storyblok_create_story` with `name` and optional `content`, `folder_id`, etc.
-  - Set `publish=true` to publish immediately on creation.
-  - The content is a JSON object matching your component structure.
-  - You can use `storyblok_get_components` first to see available block types.
-- To edit a story: `storyblok_update_story` with `story_id` and fields to update.
-  - Set `publish=true` to publish changes immediately.
-  - Set `force_update=true` only if the story is locked and you need to override (causes content conflict).
-  - To link alternates (e.g. language variants), set `group_id` to the same UUID across stories.
-- To publish: `storyblok_publish_story` with `story_id`.
-- To unpublish: `storyblok_unpublish_story` with `story_id`. Never use `update_story` to unpublish.
-
-**Example: Create a draft story**
-
-```sh
-storyblok_create_story name="New Homepage" content={"title":"Welcome","body":"<p>Hello</p>"}
-```
-
-**Example: Create and publish immediately**
-
-```sh
-storyblok_create_story name="New Homepage" content={...} publish=true
+**Schema field example:**
+```json
+{
+  "headline": { "type": "text", "pos": 0, "translatable": true },
+  "image":    { "type": "asset", "pos": 1, "filetypes": ["images"] },
+  "body":     { "type": "richtext", "pos": 2 }
+}
 ```
 
-**Example: Update and publish**
+### Page Generation
 
-```sh
-storyblok_update_story story_id="12345" content={...} publish=true
-```
-
-**Example: Publish a story**
+- [ ] Clarify goal, tone, and key messages with the user
+- [ ] `storyblok_get_components` — identify available blocks
+- [ ] Design content structure, confirm with user before creating
+- [ ] `storyblok_create_story` with the content object
+- [ ] Publish only on explicit user confirmation
 
-```sh
-storyblok_publish_story story_id="12345" publish_notes="Initial release"
-```
-Storyblok i18n & Component Update Rules
+For AI-generated copy, spawn a sub-session via `sessions_spawn` with the same tool permissions.
 
-### 3. Multilingual Story Pattern
+---
 
-When creating or updating multilingual Storyblok stories:
+## Multilingual Stories
 
--Use field-level i18n translations inside the SAME story
--Do NOT create separate stories per language unless explicitly requested
+Always use field-level i18n inside the **same** story — never separate stories per language.
 
-Required behavior
+- Default language: English (unless specified)
 
--Default/main language must be English unless specified otherwise
--Translate content to requested locales
 -Store translations using Storyblok i18n field keys:
  -field_i18n_es
  -field_i18n_ca
  -field_i18n_de
  -etc.
--Keep all translations inside the same story object
--Ensure localized_paths contains all enabled locales
--Use SEO-friendly English slugs for the main version
--Never duplicate stories for translations
-
-Example
-
-Correct:
+ - Translation keys: `field_i18n_es`, `field_i18n_ca`, `field_i18n_de`, etc.
+- Use SEO-friendly English slugs
+- Ensure `localized_paths` includes all enabled locales
 
+```json
 {
   "headline": "Why Most Strategies Fail",
   "headline_i18n_es": "Por qué fracasan la mayoría de las estrategias",
-  "headline_i18n_ca": "Per què fracassen la majoria d’estratègies"
-}
-
-Incorrect:
-
--Separate stories per language
--Duplicated content entries
--Missing localized_paths
-
-#### Expected completion reporting
-
-After multilingual operations, clearly report:
-
--Main language used
--Languages added
--That translations were stored using field-level i18n keys
--That no separate stories were created
-
-### 3.1.- Component Updates
-
-Storyblok components can be updated individually without recreating the full schema.
-
-Use:
-
-storyblok_update_component 
-
-* Use component updates for:
-- Adding translatable fields  
-- Updating schema definitions  
-- Marking fields as translatable  
-- Updating labels/descriptions
-- Extending components for i18n  
-- Updating preview fields  
-
-#### Important behavior
-
-Updating a component schema does NOT automatically update stories already using that component.
-
-After schema updates:
-
-- Existing stories may require updates
-- Missing i18n fields may need to be added manually
-- Stories may require republishing
-
-Existing story values are preserved automatically.
-
-#### Example usage
-
-```sh
-# Add a new translatable field to component 4123
-storyblok_update_component component_id="4123" schema={"subheadline":{"type":"text","pos":1,"translatable":true},"image":{"type":"asset","pos":2,"filetypes":["images"]}}
-```
-
-```sh
-# Update component display name and icon
-storyblok_update_component component_id="4123" display_name="Hero Section" icon="photo" color="#ff6600"
-```
-
-#### i18n Component Schema Rules
-
-When creating or updating schemas:
-
--Mark user-facing text fields with:
-
-  "translatable": true
-
--Keep technical/internal fields non-translatable
--Preserve existing schema fields unless explicitly removing them
--Avoid destructive schema replacements
-
-Example:
-
-{
-  "headline": {
-    "type": "text",
-    "translatable": true
-  }
-}
-
-##### Single Component Update Strategy
-
-Prefer minimal schema updates instead of recreating full components.
-
-Good:
-
-- Add one new translatable field  
-- Update a single schema property  
-- Enable translations on existing fields  
-
-Bad:
-
-- Recreate the full schema unnecessarily  
-- Accidentally remove existing fields  
-- Break existing stories  
-- Important Storyblok Behavior  
-
-Component schema updates do NOT retroactively overwrite story content.
-
-After schema changes:
-
-- Existing stories keep current values  
-- Stories may require migration/update logic  
-- Translation fields may need manual population  
-
-This matches official Storyblok component update behavior and helps avoid destructive schema operations.
-
-
-### 4. Page Generation
-
-This workflow combines AI reasoning with Storyblok tools to produce complete pages.
-
-**Steps:**
-
-1. Clarify the page goal with the user (topic, tone, key messages).
-2. Fetch component schemas via `storyblok_get_components` to understand available block types.
-3. Use reasoning to design a JSON content structure that uses those components.
-4. Create the story with `storyblok_create_story`.
-5. Optionally publish immediately with `storyblok_publish_story`.
-
-The agent may also spawn a sub-session (using `sessions_spawn`) to generate the content with an AI model if needed.
-
-### 5. Component Management
-
-Components define the content structure of your space. Always design the schema carefully before creating — renaming or restructuring a component after stories use it can break existing content.
-
-**When creating a component, decide its type first:**
-
-| Type | `is_root` | `is_nestable` | Use case |
-|------|-----------|---------------|----------|
-| Content Type | `true` | `false` | Top-level entries (pages, posts) |
-| Nestable | `false` | `true` | Reusable blocks inside pages |
-| Universal | `true` | `true` | Can be used both ways |
-
-**Schema field definition example:**
-
-```json
-{
-  "headline": {
-    "type": "text",
-    "pos": 0,
-    "translatable": true,
-    "description": "Main heading text"
-  },
-  "image": {
-    "type": "asset",
-    "pos": 1,
-    "filetypes": ["images"]
-  },
-  "body": {
-    "type": "richtext",
-    "pos": 2
-  }
+  "headline_i18n_ca": "Per què fracassen la majoria d'estratègies"
 }
 ```
 
-**Rules:**
-
-- `name` must be snake_case. Never use `content` alone — it is a reserved keyword.
-- Always set at least one of `is_root` or `is_nestable` to `true`.
-- Use `component_group_uuid` (not `component_group_id`) when assigning a component to a folder.
-- Use `storyblok_get_components` first to check if a component with the same name already exists before creating.
-- Use `storyblok_get_component` to inspect a specific component's full schema and presets.
-- Do not create components without user confirmation — they affect the entire space.
-
-## Session Awareness
-
-This skill is designed to work in both main and sub-agent sessions. It can be used directly or spawned via `sessions_spawn` for parallel or isolated execution. When spawning, pass the same tool permissions to ensure access to Storyblok tools.
-
-## README Usage Examples
-
-### Quick Query
-
-```
-User: What stories are in folder 123?
-Agent: storyblok_list_stories folder_id=123
-```
-
-### Create and Publish
-
-```
-User: Create a blog post titled "Latest Updates" with body "We've improved performance."
-Agent: storyblok_create_story name="Latest Updates" content={"post_content":"We've improved performance."} publish=true
-```
-
-### Generate a Landing Page
-
-```
-User: Generate a landing page for our summer sale.
-Agent: (fetches components, designs structure, creates story)
-storyblok_get_components
-storyblok_create_story name="Summer Sale 2026" content={...}
-storyblok_publish_story story_id="..."
-```
-
-
+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.
-
+- Respect rate limits: Storyblok API may have limits; consider adding delays if many requests.