@wix/agent-skills 1.7.0 → 1.9.0

package/skills/wix-headless/scripts/write-decorative-json.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Write the decorative slot→URL map to src/decorative-images.json for a
+// framework-SPA (`own`) frontend. This is the `own`-branch analog of
+// patch-decorative-slots.mjs (which injects <img> into .astro source) — but
+// instead of patching framework source, the generated SPA *imports* this JSON
+// and its hero/about components read it, with a themed-block fallback when a
+// slot is empty/absent. This avoids fragile JSX/Vue/Svelte string-patching and
+// mirrors how the SPA already imports .wix/design-tokens.css.
+//
+// It is called twice in the `own` flow (BUILD-own-build.md):
+//   1. At bootstrap, with EMPTY stdin → writes `{}` (placeholder), so the app
+//      builds + renders themed blocks even if Image Phase 1 never runs.
+//   2. At the seed gate (ai-generated only), with Image Phase 1's data.slots
+//      piped in → OVERWRITES the file with the real URLs. This MUST happen
+//      before `npm run build` (Vite resolves the JSON import at build time).
+//
+// Writes to src/decorative-images.json (inside the Vite root, so it is always
+// importable — unlike .wix/, which may sit outside the bundler root).
+//
+// Usage:
+//   echo '{"hero":"https://...","about":"https://..."}' \
+//     | node write-decorative-json.mjs <project-dir>
+//   : | node write-decorative-json.mjs <project-dir>     # placeholder {}
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const projectDir = process.argv[2] ?? process.cwd();
+
+let slots = {};
+if (!process.stdin.isTTY) {
+  const raw = readFileSync(0, "utf8").trim();
+  if (raw) {
+    try {
+      slots = JSON.parse(raw);
+    } catch (e) {
+      console.error(JSON.stringify({ status: "error", reason: `stdin is not valid JSON (${e.message})` }));
+      process.exit(2);
+    }
+    if (!slots || typeof slots !== "object" || Array.isArray(slots)) {
+      console.error(JSON.stringify({ status: "error", reason: "expected a JSON object mapping slot keys to URLs" }));
+      process.exit(2);
+    }
+  }
+}
+
+// Drop empty/falsy URLs so the component's themed-block fallback kicks in.
+const clean = {};
+for (const [k, v] of Object.entries(slots)) {
+  if (typeof v === "string" && v.trim()) clean[k] = v.trim();
+}
+
+const srcDir = join(projectDir, "src");
+mkdirSync(srcDir, { recursive: true });
+const dest = join(srcDir, "decorative-images.json");
+writeFileSync(dest, JSON.stringify(clean, null, 2) + "\n");
+
+console.log(JSON.stringify({
+  status: Object.keys(clean).length ? "ok" : "placeholder",
+  file: dest,
+  slots: Object.keys(clean),
+}, null, 2));

package/skills/wix-manage/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires Wix REST API access (API key or OAuth).
 
 # Management Recipes Index
 
-> **Standard call shape for every curl example across these recipes.** The `<AUTH>` placeholder in example curls is shorthand for the `Authorization` header only; every actual call ALSO needs `wix-site-id: <SITE_ID>` and `Content-Type: application/json`. **POST/PATCH against `wix-data/*`, `form-schema-service/*`, `stores/v3/*`, `blog/v3/*`, and other site-scoped REST families return 403 without `wix-site-id`** — observed seeder regression cost ~100 s rediscovering this on a 2026-05-24 run. Mint the token via `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape for every curl example across these recipes.** The `<AUTH>` placeholder in example curls is shorthand for the `Authorization` header only; body-bearing calls also need `Content-Type: application/json`.
 
 ## What Are Management Recipes?
 
@@ -52,6 +52,18 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Create and Update Booking Services](references/bookings/create-and-update-booking-services.md)
 **Technical:** Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
 
+### [Create Booking Service from Prompt](references/bookings/create-booking-service-from-prompt.md)
+**Technical:** Use when the user wants to create a booking service — e.g. "create a yoga class for $50", "set up consultations", "add a personal training appointment". Routes to the correct type-specific recipe (APPOINTMENT, CLASS, or COURSE), gathers business context, applies defaults, and creates the service.
+
+### [Create Appointment Service](references/bookings/create-appointment-service.md)
+**Technical:** Use when the user wants to create an appointment/consultation/1-on-1 service — e.g. "set up consultations for $75", "create a meeting service". Handles staff assignment, session duration, and pricing via bulkCreateServices API.
+
+### [Create Class Service](references/bookings/create-class-service.md)
+**Technical:** Use when the user wants to create a group class — e.g. "create a yoga class for $50", "set up a pilates class". Handles group capacity, recurring sessions, and pricing via bulkCreateServices API.
+
+### [Create Course Service](references/bookings/create-course-service.md)
+**Technical:** Use when the user wants to create a multi-session course — e.g. "create a 6-week workshop", "set up a training program for $300". Handles group capacity, full-course pricing, and fixed series via bulkCreateServices API.
+
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
 **Technical:** Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
 

package/skills/wix-manage/references/app-installation/install-wix-apps.md

@@ -4,7 +4,7 @@ description: Installs Wix apps on a site using Apps Installer API. Covers enabli
 ---
 # Install Wix Apps on a Site
 
-This recipe guides you through installing Wix apps on a site using the Apps Installer REST API, including enabling Velo (Wix Code) when needed.
+This recipe guides you through installing Wix apps on a site using the Apps Installer REST API.
 
 ## Prerequisites
 
@@ -51,30 +51,8 @@ Use the returned `appId` as the `appDefId` in Step 2.
 - The `appDefId` field in the install request and the `appId` field returned here are the same value
 - If multiple results come back, match on `basicInfo.name` to confirm you have the right app before installing
 - Only listings with `status: "PUBLISHED"` can be installed
-## Step 1: Enable Velo (Wix Code) if Needed
 
-If you receive the error `WDE0110: Wix Code not enabled`, you must first enable Velo on the site.
-
-**Endpoint**: `POST https://www.wixapis.com/mcp-serverless/v1/velo/provision`
-
-**Request**:
-```bash
-curl -X POST \
-  'https://www.wixapis.com/mcp-serverless/v1/velo/provision/' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{}'
-```
-
-**Response**: Empty body on success.
-
-### IMPORTANT NOTES:
-- Only call this endpoint if you receive the `WDE0110` error
-- This is a one-time operation per site
-
----
-
-## Step 2: Install the Wix App
+## Install the Wix App
 
 Use the Apps Installer API to install any Wix app on a site.
 
@@ -122,6 +100,7 @@ Some common apps:
 | Wix Blog | `14bcded7-0066-7c35-14d7-466cb3f09103` |
 | Wix Events | `140603ad-af8d-84a5-2c80-a0f60cb47351` |
 | Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
+| Wix CMS | `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
 
 ### IMPORTANT NOTES:
 - NEVER guess the `appDefId`. For Wix-built apps, use the table above. For any other app, resolve the ID using Step 0 (Search Market Listings).
@@ -135,9 +114,6 @@ Some common apps:
 ### App Not Installed Error
 If you receive an error indicating a required app is not installed, use this recipe to install it before proceeding.
 
-### WDE0110: Wix Code not enabled
-Call the Velo provision endpoint (Step 1) first, then retry the original operation.
-
 ---
 
 ## Next Steps

package/skills/wix-manage/references/blog/how-to-create-blog-posts.md

@@ -5,7 +5,7 @@ description: Creates and publishes blog posts using Blog Posts API. Covers Ricos
 
 **Article: Create and Publish Blog Posts with Rich Content and Images**
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `blog/v3/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-appointment-service.md

@@ -0,0 +1,266 @@
+---
+name: "Create Appointment Service"
+description: "Create an appointment booking service — e.g. 'set up consultations', 'create a 1-on-1 session', 'add a personal training appointment', 'create a meeting service for $25'. Handles staff assignment (required), session duration, pricing, and 1-on-1 capacity defaults via bulkCreateServices API."
+---
+
+# Create Appointment Service from Prompt
+
+## When to Use
+
+- User wants to create an appointment-based service: "set up consultations", "create a 1-on-1 session", "add a personal training appointment", "create a meeting service"
+- The service type is APPOINTMENT — customer picks an available time slot during staff working hours
+- For general service creation where the type is ambiguous, see [Create Booking Service from Prompt](./create-booking-service-from-prompt.md)
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`). Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install if missing.
+- For full API field definitions, validation rules, and troubleshooting, see [Create and Update Booking Services](./create-and-update-booking-services.md)
+
+---
+
+## Step 1: Gather Business Context
+
+Run these queries to collect site data for informed defaults.
+
+### 1a. Query Staff Members (CRITICAL for Appointments)
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v1/staff-members/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": {},
+    "fields": ["RESOURCE_DETAILS"]
+  }'
+```
+
+Save each staff member's `resourceId` (not `id`). Note which one has `default: true`.
+
+**APPOINTMENT services REQUIRE at least one staff member.** If no staff members exist, create one first using [Bookings Staff Setup](./bookings-staff-setup.md).
+
+### 1b. Query Service Categories
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+### 1c. Get Site Currency
+
+```bash
+curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Authorization: <AUTH>'
+```
+
+Extract `properties.paymentCurrency`. Fall back to `USD` if unavailable.
+
+### 1d. Query Existing Services (Duplicate Check)
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/services/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": { "paging": { "limit": 100 } } }'
+```
+
+Warn the user if a service with a similar name already exists.
+
+---
+
+## Step 2: Apply Appointment Defaults
+
+For any fields the user did not explicitly specify:
+
+| Field | Default | Notes |
+|---|---|---|
+| Duration | 60 minutes | Set via `schedule.availabilityConstraints.sessionDurations` |
+| Capacity | 1 | Appointments are typically 1-on-1 |
+| Staff | Auto-assign | Use `default: true` staff, or first available |
+| Online booking | Enabled | `onlineBooking.enabled: true` |
+
+### Pricing (if not specified)
+
+- Use the site's currency from Step 1c
+- If user specifies a price → `rateType: "FIXED"`
+- If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
+- If no price mentioned → infer from context (consultations ~$50-100, sessions ~$30-60) or default to free
+
+### Staff Assignment
+
+- **1 staff member** → auto-assign using their `resourceId`
+- **Multiple staff members** → use the one with `default: true`, or the first one
+- **No staff members** → create one first using [Bookings Staff Setup](./bookings-staff-setup.md), then proceed
+
+### Category
+
+- If categories exist → assign the most relevant one
+- If no categories exist → create a "General" category:
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "category": { "name": "General" } }'
+```
+
+### Service Name & Description
+
+- Use the user's wording for the service name
+- Generate a brief, professional description (1-2 sentences)
+
+---
+
+## Step 3: Create the Appointment Service
+
+**Paid appointment:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "services": [{
+      "name": "<SERVICE_NAME>",
+      "description": "<GENERATED_DESCRIPTION>",
+      "type": "APPOINTMENT",
+
+      "onlineBooking": { "enabled": true },
+      "staffMemberIds": ["<RESOURCE_ID>"],
+      "schedule": {
+        "availabilityConstraints": {
+          "sessionDurations": [<DURATION_MINUTES>]
+        }
+      },
+      "payment": {
+        "rateType": "FIXED",
+        "options": { "online": true, "inPerson": false },
+        "fixed": {
+          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+        }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+**Free appointment:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "services": [{
+      "name": "<SERVICE_NAME>",
+      "description": "<GENERATED_DESCRIPTION>",
+      "type": "APPOINTMENT",
+
+      "onlineBooking": { "enabled": true },
+      "staffMemberIds": ["<RESOURCE_ID>"],
+      "schedule": {
+        "availabilityConstraints": {
+          "sessionDurations": [<DURATION_MINUTES>]
+        }
+      },
+      "payment": {
+        "rateType": "NO_FEE",
+        "options": { "online": false, "inPerson": true }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+### APPOINTMENT-Specific Reminders
+
+- `staffMemberIds` is **required** — uses `resourceId` values, not staff member `id`
+- `schedule.availabilityConstraints.sessionDurations` sets the appointment length
+- Availability is based on the assigned staff member's working hours schedule
+
+Save the `serviceId` from the response: `results[0].item.service.id`
+
+---
+
+## Step 4: Navigate to Service Form
+
+Use the **RUN_IN_BROWSER** tool to navigate the user to the service form for final review:
+
+```javascript
+window.location.href = `/bookings/services/form/${serviceId}?fromAria=true`;
+```
+
+This executes in the user's browser and redirects them to the service editing page.
+
+---
+
+## Step 5: Summary Message
+
+Provide a summary including:
+
+1. **What was created** — service name, price, duration, assigned staff member
+2. **Assumptions made** — list defaults used (e.g., "I set the duration to 60 minutes since you didn't specify")
+3. **Next steps** — "Click Save to finalize, then set up your availability"
+4. **Offer to adjust** — "Want me to change the price, duration, or staff assignment?"
+
+**Example:**
+
+> I created **"Strategy Consultation"**:
+>
+> - **Type**: Appointment (1-on-1)
+> - **Price**: $75 per session
+> - **Duration**: 60 minutes
+> - **Staff**: Assigned to Sarah Johnson
+> - **Category**: Consulting
+>
+> I assumed a 60-minute duration since you didn't specify. You can review and adjust the details in the service form.
+
+---
+
+## Error Handling
+
+| Error | Cause | Action |
+|---|---|---|
+| 428 "App not installed" | Bookings not installed | Install using [Install Wix Apps](../app-installation/install-wix-apps.md) |
+| 400 "staffMemberIds required" | No staff assigned | Query staff; if none exist, create one via [Bookings Staff Setup](./bookings-staff-setup.md) |
+| 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
+| 403 | Permission denied | Inform user they lack permission |
+
+---
+
+## Payment Validation Quick Reference
+
+| rateType | `options.online` | `options.inPerson` | Valid? |
+|----------|------------------|-------------------|--------|
+| FIXED    | true             | false             | ✓      |
+| FIXED    | false            | true              | ✓      |
+| FIXED    | true             | true              | ✓      |
+| NO_FEE   | false            | true              | ✓      |
+| NO_FEE   | true             | false             | ✗      |
+| Any      | false            | false             | ✗      |
+
+---
+
+## What This Skill Does NOT Cover
+
+- **Schedule/availability setup** — staff working hours need separate configuration. See [Bookings Staff Setup](./bookings-staff-setup.md)
+- **Pricing plans** — memberships and session packs are separate. See [Create and Update Pricing Plans](../pricing-plans/create-and-update-pricing-plans.md)
+- **Service images** — requires Media Manager API (see [create-and-update-booking-services.md](./create-and-update-booking-services.md))
+
+---
+
+## API Documentation Reference
+
+- [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)
+- [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
+- [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)
+- [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
+- [Query Staff Members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members)
+- [Create Staff Member](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member)
+- [Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-management/site-properties/properties/read)
+- [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
+- [About Service Payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments)

package/skills/wix-manage/references/bookings/create-booking-service-from-prompt.md

@@ -0,0 +1,37 @@
+---
+name: "Create Booking Service from Prompt"
+description: "Create a booking service from a user prompt — e.g. 'create a yoga class for $50', 'set up consultations for $75', 'add a personal training appointment', 'create a 6-week photography workshop'. Determines the service type (APPOINTMENT, CLASS, or COURSE) and delegates to the type-specific recipe."
+---
+
+# Create Booking Service from Natural Language Prompt
+
+## When to Use
+
+- User describes a service they want to create using natural language (e.g., "create a yoga class for $50", "set up consultation sessions", "add a personal training appointment")
+- The intent is autonomous creation — fill in reasonable defaults rather than asking the user for every field
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+- If Bookings is not installed, use [Install Wix Apps](../app-installation/install-wix-apps.md) to install it first
+
+---
+
+## Step 1: Determine Service Type
+
+| User mentions | Type | Recipe |
+|---|---|---|
+| consultation, appointment, meeting, 1-on-1, one-on-one, session | `APPOINTMENT` | [Create Appointment Service](./create-appointment-service.md) |
+| class, yoga, pilates, group session, group workout, bootcamp class | `CLASS` | [Create Class Service](./create-class-service.md) |
+| workshop, program, course, training program, multi-session | `COURSE` | [Create Course Service](./create-course-service.md) |
+| (unclear or unspecified) | `APPOINTMENT` | [Create Appointment Service](./create-appointment-service.md) |
+
+## Step 2: Follow the Type-Specific Recipe
+
+Once the service type is determined, follow the corresponding recipe linked above. Each recipe covers:
+
+1. Gathering business context (staff, categories, currency, duplicate check)
+2. Applying type-specific defaults (pricing, capacity, duration, staff assignment)
+3. Creating the service via `bulkCreateServices`
+4. Navigating to the service form for user review
+5. Providing a summary of what was created and assumptions made