@lacneu/wix-openclaw 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-29
+
+### Added
+- `examples/recommended-skill.md` — companion skill template that
+  operators can copy into agent workspaces
+  (`~/.openclaw/workspace-<agent>/skills/wix/SKILL.md`) to give the LLM
+  business context, recipes and guardrails for the plugin. Skills are
+  not part of the OpenClaw plugin SDK by design — they live in the
+  workspace — so the template ships as a static file and gets included
+  in the npm package via the `files` array.
+
+### Changed
+- Added `examples/` to the `files` array of `package.json` so the
+  template is shipped with the npm publish.
+- README now has a "Recommended companion skill" section linking to
+  the template.
+
 ## [0.2.0] - 2026-04-29
 
 ### Added

package/README.md

@@ -498,6 +498,31 @@ use an empty array to disable gating entirely (not recommended in production).
 
 ---
 
+## Recommended companion skill
+
+OpenClaw plugins ship code (tools, hooks); they do **not** ship skills.
+Skills live in agent workspaces and carry the business context that makes
+the LLM use the tools correctly (audience, tone, recipes, guardrails).
+
+To get an agent up and running with this plugin, copy
+[`examples/recommended-skill.md`](examples/recommended-skill.md) into the
+target workspace at `~/.openclaw/workspace-<agent>/skills/wix/SKILL.md`,
+then replace the `<PLACEHOLDER>` values with your own (organisation name,
+domain, contributors, tone). Duplicate the file for each agent that
+should benefit from the skill.
+
+The template covers:
+
+- Conversational triggers (encoded in the `description` frontmatter as
+  per OpenClaw skill convention)
+- 5 usage recipes (publish article, list real drafts, read leads,
+  manage bookings, design request)
+- Behavioural guardrails (approval recap before publish, app-not-installed
+  handling, PII rules)
+- Tool mapping (short reference; the README is the source of truth)
+
+---
+
 ## Development
 
 ### Project layout

package/examples/recommended-skill.md

@@ -0,0 +1,188 @@
+---
+name: wix
+description: Site officiel <YOUR_SITE_NAME> (<your-site.com>) sur Wix — articles de blog, brouillons, médias, formulaires/leads, RDV, services, FAQ, avis. Utilise ce skill quand l'utilisateur dit "publier un article", "brouillon de blog", "ajouter une image au site", "voir les leads", "soumissions de formulaire", "modifier les services", "répondre à un avis", "FAQ", "<your-site.com>", "site officiel".
+user-invocable: true
+---
+
+# Wix — Recommended skill template
+
+> **This is a template** — copy it to your workspace
+> (`~/.openclaw/workspace-<agent>/skills/wix/SKILL.md`), then replace every
+> `<PLACEHOLDER>` with values specific to your site and organisation.
+> Skills are loaded per workspace, so duplicate the file for each agent
+> that should benefit from it.
+
+This skill gives an OpenClaw agent the business context, recipes and
+behavioural guardrails it needs to operate the
+[`@lacneu/wix-openclaw`](https://www.npmjs.com/package/@lacneu/wix-openclaw)
+plugin correctly. The plugin itself ships generic tools; this skill wraps
+them into your specific site, voice and audience.
+
+## Business context (replace with yours)
+
+`<ORGANIZATION>` is `<short pitch — what you do, who you serve>`. The
+public site `<your-site.com>` runs on **Wix Editor classic** (the plugin
+also targets Wix Studio sites — adjust if relevant). It is locked at the
+plugin level to a single `siteId` (set in `allowedSiteIds`).
+
+**Tone for site content** — `<sober / playful / formal / informal>`,
+`<language>`, `<audience>`. Preserve the voice of the human contributors
+when they dictate or proofread; do not normalize their phrasing.
+
+**Site language** — `<fr / en / ...>`.
+
+**Human contributors / collaborators** — list them with their role:
+
+- `<Name 1>` — `<role>`
+- `<Name 2>` — `<role>`
+- `<...>`
+
+## Conversational triggers (when this skill is relevant)
+
+- "Publish an article about X" / "Publier un article sur X"
+- "Prepare a draft about Y" / "Prépare un brouillon sur Y"
+- "Add this image to the site" / "Ajoute cette image au site"
+- "How many leads this week?" / "Combien de leads cette semaine ?"
+- "Update this service" / "Mets à jour ce service"
+- "What appointments today?" / "Quels RDV aujourd'hui ?"
+- "Reply to this review" / "Réponds à cet avis"
+- "Add this FAQ entry" / "Ajoute cette question à la FAQ"
+- Any mention of `<your-site.com>`, "Wix", "official site", "site officiel"
+
+## When this skill does NOT apply
+
+The plugin **cannot** modify the site's design (Wix Editor classic does
+not expose this through any public API):
+
+- Colours, typography, page layout
+- Individual graphic components (buttons, sections, backgrounds)
+- Page structure (navigation, header, footer)
+
+Pure-design requests should be redirected to the **(e) Design request**
+recipe below.
+
+## Usage patterns
+
+### (a) Draft and publish a blog article
+
+1. **Cover image** — if the user provides a URL (or asks for an
+   AI-generated image): use `wix_media_upload` to push it into Wix Media
+   Manager. Capture the returned `id` for step 2.
+2. **Create draft** — `wix_blog_create_draft` with:
+   - `title`
+   - `richContent` (Wix Ricos format — Wix Blog's native rich-text)
+   - `coverMedia.imageId` from step 1
+   - `tagIds`, `categoryIds` if appropriate (look them up first via
+     `wix_blog_list_tags` / `wix_blog_list_categories`)
+3. **User-facing recap** — show this in plain business language, NEVER
+   mention tool names or HTTP details:
+
+   > Draft ready:
+   > **Title**: <title>
+   > **Lead paragraph**: <first ~80 words>
+   > **Cover image**: <displayName or short description>
+   > **Tags**: <readable list>
+   >
+   > Reply `publish` to go live, or tell me what to adjust.
+
+4. **Publish on explicit confirmation only** — `wix_blog_publish_draft`
+   with the draft id. OpenClaw approval-gates this call; the recap above
+   helps the human decide knowingly.
+
+### (b) List actual drafts (not the published-post snapshots)
+
+Wix Blog v3 quirk: `wix_blog_list_drafts` without filter returns mirror
+drafts for already-published posts (auto-snapshots).
+
+To see only **drafts being actively written**: pass `status: "UNPUBLISHED"`.
+Other useful values: `IN_REVIEW`, `SCHEDULED`.
+
+If the user asks "how many drafts do I have?" and the unfiltered count
+looks unexpectedly large, explain in plain words ("some are mirror
+copies of published articles") and re-query with `status: "UNPUBLISHED"`.
+
+### (c) Read form submissions / leads
+
+- `wix_forms_list_submissions` with:
+  - `namespace: "wix.form_app.form"` (default — keep unless using a
+    custom forms app)
+  - `paging.limit: 20` (or more)
+  - `sort` to put recent first when supported
+
+Present leads in business language (name, email, message, date). Do not
+expose technical `id`s.
+
+### (d) Manage bookings
+
+- `wix_bookings_services_list` — list bookable services
+- `wix_bookings_query_bookings` with a `startDate` filter (e.g.
+  `$gt: "2026-01-01T00:00:00Z"`) for upcoming bookings
+- `wix_bookings_cancel` / `wix_bookings_reschedule` — both gated; ask for
+  explicit confirmation before invoking.
+
+### (e) Design request (assumed limitation)
+
+If the user asks for a visual change (colour, layout, styled button…),
+respond along these lines:
+
+> I can't change the site's visual components directly (Wix Editor
+> classic doesn't expose that via API). I can however prepare a design
+> brief (palette, typography, suggested copy) and generate a mockup
+> image — you'll then apply it manually in the Wix editor. Want to go
+> that route?
+
+If yes: use `wix_design_brief` to structure the brief, then
+`image_generate` (or your preferred image-gen tool) for the mockup.
+
+## Behavioural guardrails
+
+1. **Before any publication** (`wix_blog_publish_draft`, modifying
+   `wix_bookings_*`, public review replies) — always show a business
+   recap and wait for explicit confirmation. OpenClaw gates the HTTP
+   call already; the recap helps the human decide.
+2. **"App not installed" / `428` / `404` / "Wix Code not enabled"** — do
+   not insist or retry. Explain in plain terms that the relevant Wix app
+   must be activated in the
+   [Wix App Market](https://www.wix.com/app-market). Apps concerned: Wix
+   Events, Wix Reviews, Wix FAQ, Wix Multilingual, Velo (for
+   `wix_data_*`).
+3. **Site whitelist** — the plugin is locked to `<your_site_id>`. Any
+   other `siteId` is rejected before reaching Wix. Do not try to bypass.
+4. **PII / sensitive data** — form submissions and contacts contain
+   names, emails, phone numbers, sometimes confidential messages. **Do
+   not log, do not embed in long-term knowledge stores** (vector DB,
+   shared memory) without explicit user consent. Surface only what is
+   asked.
+
+## Available tools (short mapping)
+
+- **Blog** — drafts (create, list, update, publish), posts, categories,
+  tags
+- **Media** — upload, list
+- **Site** — `sites_list`, `url_get`, `business_info`
+- **CMS / Wix Data** — collections, items CRUD (requires Velo enabled)
+- **Forms** — `submissions` (list, get)
+- **Contacts** — CRUD + labels + search
+- **Bookings** — services, bookings (CRUD, cancel, reschedule)
+- **Events** (requires Wix Events app)
+- **Reviews** (requires Wix Reviews app) — moderation, replies
+- **FAQ** (requires Wix FAQ app)
+- **Multilingual** (requires Wix Multilingual app)
+- **Design** — `wix_design_brief`
+
+Full reference and live signatures:
+<https://github.com/OlivierNeu/wix-openclaw-plugin#tools>
+
+## Operating rules
+
+1. **Voice of `<ORGANIZATION>` first** — preserve phrasings dictated by
+   `<contributors>`, do not normalize them.
+2. **No technical jargon to end-users** — never expose tool names
+   (`wix_*`), Wix object ids, or HTTP error codes. Rephrase in business
+   terms.
+3. **Explicit confirmation** before any public-facing publication or
+   modification.
+4. **Single source of truth** — the official site at `<your-site.com>`.
+   Do not attempt other `siteId`s.
+5. **Unexpected behaviour** — escalate to the operator (admin agent /
+   maintainer) in a separate session, not in the user-facing channel.

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "wix-openclaw",
   "name": "Wix",
   "description": "Wix REST API plugin for OpenClaw — manage blog, CMS data, forms, bookings, contacts, events, FAQ on a single Wix site with site_id whitelist and approval gating on destructive ops",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lacneu/wix-openclaw",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Wix REST API plugin for OpenClaw — manage blog, CMS data, forms, bookings, contacts, events, FAQ on a single Wix site with site_id whitelist and approval gating on destructive ops",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "examples",
     "openclaw.plugin.json",
     "README.md",
     "CHANGELOG.md",