@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -0,0 +1,245 @@
+---
+name: "Create Class Service"
+description: "Create a class booking service — e.g. 'create a yoga class for $50', 'set up a pilates class', 'add a group fitness session', 'create a weekly meditation class'. Handles group capacity, recurring session defaults, and pricing via bulkCreateServices API. Staff assignment is not used for classes."
+---
+
+# Create Class Service from Prompt
+
+## When to Use
+
+- User wants to create a group class: "create a yoga class", "set up a pilates class", "add a group fitness session", "create a weekly meditation class"
+- The service type is CLASS — a single event or recurring series that multiple customers can book
+- Customers can sign up for one, several, or all sessions in a class series
+- 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 Service Categories
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+### 1b. 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.
+
+### 1c. 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.
+
+> **Note:** Staff queries are optional for CLASS services since `staffMemberIds` is ignored by the API. However, querying staff can still be useful for context (e.g., mentioning instructors in the description).
+
+---
+
+## Step 2: Apply Class Defaults
+
+For any fields the user did not explicitly specify:
+
+| Field | Default | Notes |
+|---|---|---|
+| Capacity | 10 | `defaultCapacity` — required for CLASS |
+| Online booking | Enabled | `onlineBooking.enabled: true` |
+
+### Pricing (if not specified)
+
+- Use the site's currency from Step 1b
+- If user specifies a price → `rateType: "FIXED"` (per session)
+- If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
+- If no price mentioned → infer from context (yoga/fitness classes ~$15-30, art/music ~$20-40) or default to free
+
+### Capacity (if not specified)
+
+- Default: 10 participants
+- If user mentions capacity (e.g., "small group of 6", "up to 20") → use their number
+- Typical ranges: small group 4-8, standard 10-20, large 20-50
+
+### Category
+
+- If categories exist → assign the most relevant one (e.g., "Fitness", "Wellness")
+- If no categories exist → create one:
+```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) mentioning it's a group class
+
+---
+
+## Step 3: Create the Class Service
+
+**CRITICAL: CLASS services do NOT use `staffMemberIds` or `sessionDurations`.** These fields are ignored. Use `defaultCapacity` instead.
+
+**Paid class:**
+
+```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": "CLASS",
+
+      "onlineBooking": { "enabled": true },
+      "defaultCapacity": <CAPACITY>,
+      "payment": {
+        "rateType": "FIXED",
+        "options": { "online": true, "inPerson": false },
+        "fixed": {
+          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+        }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+**Free class:**
+
+```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": "CLASS",
+
+      "onlineBooking": { "enabled": true },
+      "defaultCapacity": <CAPACITY>,
+      "payment": {
+        "rateType": "NO_FEE",
+        "options": { "online": false, "inPerson": true }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+### CLASS-Specific Reminders
+
+- Do **NOT** include `staffMemberIds` — it is ignored for CLASS services
+- Do **NOT** include `schedule.availabilityConstraints.sessionDurations` — not used for CLASS
+- `defaultCapacity` is **required** — sets max participants per session
+- After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
+
+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 per session, capacity
+2. **Assumptions made** — list defaults used (e.g., "I set the capacity to 10 participants since you didn't specify")
+3. **Schedule note** — remind the user that class sessions still need to be scheduled
+4. **Next steps** — "Click Save to finalize, then set up the class schedule"
+5. **Offer to adjust** — "Want me to change the price, capacity, or description?"
+
+**Example:**
+
+> I created **"Vinyasa Yoga Class"**:
+>
+> - **Type**: Class (group session)
+> - **Price**: $25 per session
+> - **Capacity**: 10 participants
+> - **Category**: Fitness
+>
+> I assumed a capacity of 10 since you didn't specify. You can review and adjust the details in the service form.
+>
+> **Next step:** You'll need to set up the class schedule (days and times) 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 "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
+
+- **Class schedule setup** — recurring events (days/times) must be configured separately via Calendar Events API. See [Create and Update Booking Services](./create-and-update-booking-services.md) Step 3.
+- **Pricing plans** — memberships and class packs are separate. See [Create and Update Pricing Plans](../pricing-plans/create-and-update-pricing-plans.md)
+- **Instructor assignment** — `staffMemberIds` is ignored for CLASS. Staff association is managed through calendar events.
+- **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)
+- [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)
+- [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-course-service.md

@@ -0,0 +1,249 @@
+---
+name: "Create Course Service"
+description: "Create a course booking service — e.g. 'create a 6-week photography workshop', 'set up a training program', 'add a bootcamp course for $300', 'create a teacher training course'. Handles group capacity, full-course pricing, and fixed series defaults via bulkCreateServices API. Staff assignment is not used for courses."
+---
+
+# Create Course Service from Prompt
+
+## When to Use
+
+- User wants to create a multi-session course: "create a training program", "set up a 6-week workshop", "add a bootcamp course", "create a teacher training course"
+- The service type is COURSE — a fixed series with pre-defined start and end dates
+- Customers must book the entire course (all sessions), unlike CLASS where they can pick individual sessions
+- 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 Service Categories
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+### 1b. 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.
+
+### 1c. 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.
+
+> **Note:** Staff queries are optional for COURSE services since `staffMemberIds` is ignored by the API. However, querying staff can still be useful for context (e.g., mentioning the instructor in the description).
+
+---
+
+## Step 2: Apply Course Defaults
+
+For any fields the user did not explicitly specify:
+
+| Field | Default | Notes |
+|---|---|---|
+| Capacity | 10 | `defaultCapacity` — required for COURSE |
+| Online booking | Enabled | `onlineBooking.enabled: true` |
+
+### Pricing (if not specified)
+
+- Use the site's currency from Step 1b
+- If user specifies a price → `rateType: "FIXED"` (for the entire course)
+- If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
+- If no price mentioned → infer from context (workshops ~$100-300, training programs ~$200-500, bootcamps ~$150-400) or default to free
+- **Course pricing is for the full course**, not per session — remind the user of this in the summary
+
+### Capacity (if not specified)
+
+- Default: 10 participants
+- If user mentions group size → use their number
+- Typical ranges: intensive 5-10, standard 10-20, lecture-style 20-50
+
+### Category
+
+- If categories exist → assign the most relevant one (e.g., "Training", "Workshops")
+- If no categories exist → create one:
+```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) mentioning it's a multi-session course
+- If the user specified the number of sessions or duration, include that in the description
+
+---
+
+## Step 3: Create the Course Service
+
+**CRITICAL: COURSE services do NOT use `staffMemberIds` or `sessionDurations`.** These fields are ignored. Use `defaultCapacity` instead.
+
+**Paid course:**
+
+```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": "COURSE",
+
+      "onlineBooking": { "enabled": true },
+      "defaultCapacity": <CAPACITY>,
+      "payment": {
+        "rateType": "FIXED",
+        "options": { "online": true, "inPerson": false },
+        "fixed": {
+          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+        }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+**Free course:**
+
+```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": "COURSE",
+
+      "onlineBooking": { "enabled": true },
+      "defaultCapacity": <CAPACITY>,
+      "payment": {
+        "rateType": "NO_FEE",
+        "options": { "online": false, "inPerson": true }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+### COURSE-Specific Reminders
+
+- Do **NOT** include `staffMemberIds` — it is ignored for COURSE services
+- Do **NOT** include `schedule.availabilityConstraints.sessionDurations` — not used for COURSE
+- `defaultCapacity` is **required** — sets max participants for the entire course
+- Customers must book the **entire course** (all sessions), not individual sessions
+- After creation, course sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
+
+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, total course price, capacity
+2. **Assumptions made** — list defaults used (e.g., "I set the capacity to 10 participants since you didn't specify")
+3. **Pricing clarification** — note that the price is for the entire course, not per session
+4. **Schedule note** — remind the user that course sessions (dates and times) still need to be set up
+5. **Next steps** — "Click Save to finalize, then set up the course schedule"
+6. **Offer to adjust** — "Want me to change the price, capacity, or description?"
+
+**Example:**
+
+> I created **"Yoga Teacher Training"**:
+>
+> - **Type**: Course (customers book the full program)
+> - **Price**: $300 for the full course
+> - **Capacity**: 10 participants
+> - **Category**: Training
+>
+> I assumed a capacity of 10 since you didn't specify. The price of $300 covers the entire course — customers pay once for all sessions. You can review and adjust the details in the service form.
+>
+> **Next step:** You'll need to set up the course schedule (specific session dates and times) 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 "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
+
+- **Course schedule setup** — individual session events (dates/times) must be configured separately via Calendar Events API. See [Create and Update Booking Services](./create-and-update-booking-services.md) Step 3.
+- **Pricing plans** — memberships or installment payments are separate. See [Create and Update Pricing Plans](../pricing-plans/create-and-update-pricing-plans.md)
+- **Instructor assignment** — `staffMemberIds` is ignored for COURSE. Staff association is managed through calendar events.
+- **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)
+- [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)
+- [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/cms/cms-data-items-crud.md

@@ -4,13 +4,13 @@ description: "Add, query, update, and delete items in CMS collections. Use this
 ---
 # CMS Data Items CRUD
 
-> **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/PATCH against `wix-data/*` 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`.
 
 This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
 
 ## Prerequisites
 
-1. Wix CMS enabled on the site
+1. Wix CMS enabled on the site (appDefId: `e593b0bd-b783-45b8-97c2-873d42aacaf4`)
 2. Collections already created (see [CMS Schema Management](cms-schema-management.md))
 3. API access with CMS permissions
 
@@ -439,6 +439,7 @@ curl -X DELETE \
 | `WDE0007` | Bulk update: wrong ID field name | Use `id` not `_id` at element level |
 | `WDE0080` | Validation failed (multiple causes) | Bulk update: don't include `_id` in `data`; Bulk patch: use `patches` array not `dataItems` |
 | `WDE0303` | Can't set multi-reference field via data operations | Use reference endpoints: `insert-references`, `replace-references` |
+| `WDE0110` | Wix CMS (Wix Data) application is not installed | Install application with appDefId: `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
 
 ---
 

package/skills/wix-manage/references/cms/cms-references-and-relationships.md

@@ -4,7 +4,7 @@ description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use ins
 ---
 # CMS References & Relationships
 
-> **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/PATCH against `wix-data/*` 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`.
 
 This recipe covers linking CMS collections together using reference fields.
 

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -4,13 +4,13 @@ description: Create and modify CMS collection structures. Covers listing collect
 ---
 # CMS Schema Management
 
-> **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/PATCH against `wix-data/*` 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`.
 
 This recipe covers managing the structure (schema) of Wix CMS collections using the REST API.
 
 ## Prerequisites
 
-1. Wix CMS enabled on the site
+1. Wix CMS application installed on the site (appDefId: `e593b0bd-b783-45b8-97c2-873d42aacaf4`)
 2. API access with CMS permissions (Manage Data Collections scope)
 
 ## Required APIs

package/skills/wix-manage/references/domains/domain-search-and-purchase.md

@@ -218,13 +218,18 @@ Replace `{domain}` with the chosen domain (e.g. `mybakery.com`).
 ```json
 {
   "domainRegistrationIntent": {
-    "registrantContact": { "firstName": "...", "lastName": "...", "email": "...", "phone": "...", "address": { ... } },
+    "registrantContact": {
+      "firstName": "...", "lastName": "...", "email": "...", "phone": "...",
+      "streetAddress": "...", "city": "...", "country": "...", "postalCode": "..."
+    },
     "adminContact": { ... },
     "techContact": { ... }
   }
 }
 ```
 
+> Address fields are **flat** on each contact (`streetAddress`, `city`, `country`, `postalCode`) — there is no nested `address` sub-object.
+
 - **If contacts exist**: Show the info and explicitly ask "Should I use these details, or would you like to register with different info?" Wait for the user to confirm before proceeding to Step 3. Do NOT skip this confirmation.
 - **If contacts are empty**: Ask the user for: first name, last name, email, phone number, street address, city, country, and postal code. The user can provide country as a full name (e.g. "Israel", "United States") -- convert it to the 2-letter ISO country code (e.g. "IL", "US") before sending to the API. Wait for them to provide all fields before proceeding.
 
@@ -249,12 +254,10 @@ Body:
       "lastName": "Smith",
       "email": "john@email.com",
       "phone": "+1.5551234567",
-      "address": {
-        "streetAddress": "123 Main St",
-        "city": "New York",
-        "country": "US",
-        "postalCode": "10001"
-      }
+      "streetAddress": "123 Main St",
+      "city": "New York",
+      "country": "US",
+      "postalCode": "10001"
     },
     "adminContact": { ... same as registrant ... },
     "techContact": { ... same as registrant ... }

package/skills/wix-manage/references/forms/create-form.md

@@ -4,7 +4,7 @@ description: Creates a form with fields (name, email, etc.) using the Form Schem
 ---
 # RECIPE: Create a Wix Form
 
-> **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 `form-schema-service/v4/forms` 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`.
 
 Create a form on a Wix site that appears in the Forms & Submissions dashboard. The form collects visitor information (e.g., name, email) and can automatically upsert contacts on submission.
 
@@ -217,6 +217,7 @@ Verify the form in the dashboard: `https://manage.wix.com/dashboard/{siteId}/for
 - **CRITICAL: The `identifier` must be a recognized Wix value.** Custom identifiers like `"product_name"` or `"color_preference"` will cause the field to be silently dropped from the form — no error is thrown. For any generic/custom text field, use `"TEXT_INPUT"` as the identifier and set the display name via the `label` property in `textInputOptions`.
 - For plain text fields, use `"format": "UNKNOWN_FORMAT"`. For email fields, use `"format": "EMAIL"`. For phone fields, use `"format": "PHONE"`. Valid format values: `UNKNOWN_FORMAT`, `DATE`, `TIME`, `DATE_TIME`, `EMAIL`, `URL`, `UUID`, `PHONE`, `URI`, `HOSTNAME`, `COLOR_HEX`, `CURRENCY`, `LANGUAGE`, `DATE_OPTIONAL_TIME`.
 - The submit button is a `DISPLAY` field with `identifier: "SUBMIT_BUTTON"`.
+- **Build the complete form in one call — do not create throwaway "test" forms to probe field shapes.** A site has a **low form cap (~4 forms)**; iterative probing hits the cap (`maximum number of forms reached`), forcing you to `GET` the form list and `DELETE` the test forms before the real create can succeed. Assemble all fields (including any RADIO_GROUP/DROPDOWN per § "Choice fields") and POST once.
 
 ### Field Types Reference
 
@@ -228,9 +229,54 @@ Verify the form in the dashboard: `https://manage.wix.com/dashboard/{siteId}/for
 | `CONTACTS_EMAIL` | `TEXT_INPUT` | `EMAIL` | Contact email |
 | `CONTACTS_PHONE` | `TEXT_INPUT` | `PHONE` | Contact phone |
 | `SUBMIT_BUTTON` | N/A (`DISPLAY` field) | N/A | Submit button |
+| `TEXT_INPUT` | `RADIO_GROUP` | `UNKNOWN_FORMAT` | Single-choice from a fixed list (radio buttons) — see § "Choice fields" |
+| `TEXT_INPUT` | `DROPDOWN` | `UNKNOWN_FORMAT` | Single-choice from a fixed list (dropdown) — same shape as RADIO_GROUP |
 
 > **Note:** `LONG_TEXT_INPUT` is not supported as a `componentType` via REST — it throws `INVALID_ARGUMENT`. Use `TEXT_INPUT` for all text fields.
 
+### Choice fields (RADIO_GROUP / DROPDOWN)
+
+A single-choice field (radio buttons or a dropdown — e.g. an RSVP "Will you attend?") is a **`STRING` input field**, not a separate field type. It uses `identifier: "TEXT_INPUT"`, `inputType: "STRING"`, and sets `componentType` to `RADIO_GROUP` (or `DROPDOWN`) **inside `stringOptions`**. Two things must agree or the field breaks:
+
+1. **`stringOptions.validation.enum`** must list every option `value` (an empty `enum` is for free-text only).
+2. **`stringOptions.radioGroupOptions.options[]`** carries the rendered choices — each option needs its own **UUID `id`**, a `value`, and a `label`. (For `DROPDOWN`, use `dropdownOptions` with the same `{id, value, label}` shape.)
+
+> **CRITICAL — silent fallback to TEXT_INPUT.** If `radioGroupOptions` is missing/malformed (wrong key like `choices` instead of `options`, an option missing its `id`, or an empty `validation.enum`), the API does **not** error — it silently creates the field as a plain `TEXT_INPUT`. If a choice field renders as a text box, this is why. Build it correctly on the first call; do not probe.
+
+```json
+{
+  "id": "a1b2c3d4-1002-4e00-8001-000000000002",
+  "hidden": false,
+  "identifier": "TEXT_INPUT",
+  "fieldType": "INPUT",
+  "inputOptions": {
+    "target": "attending_0002",
+    "pii": false,
+    "required": true,
+    "inputType": "STRING",
+    "readOnly": false,
+    "stringOptions": {
+      "validation": {
+        "format": "UNKNOWN_FORMAT",
+        "enum": ["Joyfully accepts", "Regretfully declines"]
+      },
+      "componentType": "RADIO_GROUP",
+      "radioGroupOptions": {
+        "label": "Will you attend?",
+        "showLabel": true,
+        "numberOfColumns": "ONE",
+        "options": [
+          { "id": "c3d4e5f6-3001-4a00-8001-000000000001", "value": "Joyfully accepts", "label": "Joyfully accepts" },
+          { "id": "c3d4e5f6-3001-4a00-8001-000000000002", "value": "Regretfully declines", "label": "Regretfully declines" }
+        ]
+      }
+    }
+  }
+}
+```
+
+`numberOfColumns` is a string enum (`"ONE"`, `"TWO"`, `"THREE"`) controlling the radio layout — omit it and the field still works (defaults to one column).
+
 ### Layout
 
 The `steps[].layout.large.items` array controls how fields are positioned:
@@ -252,6 +298,8 @@ The Wix Forms app (appDefId: `14ce1214-b278-a7e4-1373-00cebd1bef7c`) must be ins
 |---|---|---|
 | `Unrecognized value passed for enum` | Invalid `componentType` value (e.g., `LONG_TEXT_INPUT`) | Use only `componentType` values from the schema: `TEXT_INPUT`, `RADIO_GROUP`, `DROPDOWN`, `DATE_TIME`, `PHONE_INPUT`, `DATE_INPUT`, `TIME_INPUT`, `DATE_PICKER`, `PASSWORD` |
 | Field silently missing from created form | Custom `identifier` value (e.g., `"product_name"`) | Use a recognized identifier like `TEXT_INPUT` and set display name via `label` |
+| Choice field rendered as a plain text box | `radioGroupOptions`/`dropdownOptions` malformed (wrong key, option missing `id`, empty `validation.enum`) — API silently falls back to `TEXT_INPUT` | Match the § "Choice fields" shape exactly: `componentType` in `stringOptions`, `options[]` each with a UUID `id`, and `validation.enum` listing all option values |
+| `maximum number of forms reached` / form-cap error | Sites cap at ~4 forms; reached by creating throwaway test forms | `GET form-schema-service/v4/forms` then `DELETE` the unwanted forms; build the real form in one call (don't probe) |
 | `Permissions for given namespace not found` | `wix.form_app.form` namespace not active | Ensure the Wix Forms app is installed; try creating a form through the UI first to activate the namespace |
 | `missing installed app` | Wix Forms app not installed | Install app `14ce1214-b278-a7e4-1373-00cebd1bef7c` via the [Install Wix Apps](../app-installation/install-wix-apps.md) recipe |