@wix/agent-skills 1.16.1 → 1.16.3

package/skills/wix-design-system/SKILL.md

@@ -95,27 +95,27 @@ Don't read these files fully. Grep for keywords, then read specific sections wit
 
 ## Quick Component Mapping (Design to WDS)
 
-| Design Element | WDS Component | Notes |
-| --- | --- | --- |
-| Rectangle/container | `<Box>` | Layout wrapper |
-| Text button | `<TextButton>` | Secondary actions |
-| Input with label | `<FormField>` + `<Input>` | Wrap inputs |
-| Toggle | `<ToggleSwitch>` | On/off settings |
-| Modal | `<Modal>` + `<CustomModalLayout>` | Use together |
-| Grid | `<Layout>` + `<Cell>` | Responsive |
+| Design Element      | WDS Component                     | Notes             |
+| ------------------- | --------------------------------- | ----------------- |
+| Rectangle/container | `<Box>`                           | Layout wrapper    |
+| Text button         | `<TextButton>`                    | Secondary actions |
+| Input with label    | `<FormField>` + `<Input>`         | Wrap inputs       |
+| Toggle              | `<ToggleSwitch>`                  | On/off settings   |
+| Modal               | `<Modal>` + `<CustomModalLayout>` | Use together      |
+| Grid                | `<Layout>` + `<Cell>`             | Responsive        |
 
 ## Spacing (px to SP conversion)
 
 When designer specifies pixels, convert to the nearest SP token:
 
 | Token | Classic | Studio |
-| --- | --- | --- |
-| `SP1` | 6px | 4px |
-| `SP2` | 12px | 8px |
-| `SP3` | 18px | 12px |
-| `SP4` | 24px | 16px |
-| `SP5` | 30px | 20px |
-| `SP6` | 36px | 24px |
+| ----- | ------- | ------ |
+| `SP1` | 6px     | 4px    |
+| `SP2` | 12px    | 8px    |
+| `SP3` | 18px    | 12px   |
+| `SP4` | 24px    | 16px   |
+| `SP5` | 30px    | 20px   |
+| `SP6` | 36px    | 24px   |
 
 ```tsx
 <Box gap="SP2" padding="SP3">
@@ -130,6 +130,10 @@ import { Button, Card, Image } from "@wix/design-system";
 import { Add, Edit, Delete } from "@wix/wix-ui-icons-common";
 ```
 
+## GUIDELINES
+
+1. Don't ever override WDS CSS tokens. Only if it's not possible otherwise, mention that very clearly to the prompter, that this is an anti-pattern and should be avoided at all costs.
+
 ### Troubleshooting
 
 - **Components render unstyled** (plain HTML look, missing WDS spacing/typography): add `import "@wix/design-system/styles.global.css";` once to the root/main component (e.g. `page.tsx`, modal entry) — not child/tab/helper files.

package/skills/wix-docs/SKILL.md

@@ -7,7 +7,8 @@ description: "Look up the Wix API/SDK documentation to confirm an exact endpoint
 
 Get the **exact** truth about a Wix API — endpoint, HTTP method, request/response body, a field, an
 enum, or an error. **Never invent a Wix endpoint, path, body, or enum from memory** — confirm it
-here first.
+here first. That includes the example endpoints in this skill: they illustrate the mechanics and
+go stale like any snapshot — discover the real contract before you rely on one.
 
 A lookup is a short flow: **find the right page, then read it.** Do it with `curl` (default, below)
 or the Wix MCP doc tools if your agent has them (Lane 2).
@@ -212,6 +213,79 @@ when present, fall back to Lane 1 when not. Optional — skip this lane if the t
 Append `.md` only when `curl`-ing a page directly. The MCP tools and the search endpoint take the
 plain docs URL **without** `.md` — never feed a `.md` URL to an MCP tool.
 
+## From docs to calls
+
+The contract you just read runs under one of two identities — and which one a call wants is part
+of what you read:
+
+| identity | token | for |
+|---|---|---|
+| **admin** | an admin token (API key, connector, or OAuth-app admin grant) | managing the site — ad hoc calls, or the same fetch inside an app's backend function |
+| **visitor** | minted from the site's OAuth app, in frontend code | everything the site's end user does — storefront reads, cart, checkout |
+
+**Admin** — any management or read call, straight from its docs contract:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/contacts/v5/contacts/query' \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
+  --data-raw '{"query": {"cursorPaging": {"limit": 10}}}'
+```
+
+In a Wix CLI project, the CLI mints `$ADMIN_TOKEN` — at either scope:
+
+```bash
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")   # site-scoped: this one site's APIs
+TOKEN=$(npx @wix/cli@latest token)                     # account-scoped: account-level APIs (list sites, …)
+```
+
+Mint once per run and cache it — within a run the CLI returns a byte-identical token, so re-minting
+only spends startup time.
+
+**Visitor — minted from the OAuth app's client id.** The client id is a public value, and it is
+usually already on disk before it is in any API: in a managed headless project it is the `appId`
+field of `wix.config.json` — **the OAuth app id and the client id are the same value** — so read it
+from the project's config instead of querying the OAuth-apps API for it. The mint is one
+unauthenticated call, so it belongs in the site's own frontend code:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"clientId": "<oauth app client id>", "grantType": "anonymous"}'
+# → { "access_token": "OauthNG.JWS.…", … } — bearer for products, cart, checkout
+```
+
+The cart and checkout APIs act on the *caller's* identity, so they want the visitor token — the
+admin token is for managing the site, the visitor token is for being on it.
+
+The authentication docs (append `.md` to read):
+
+- [`about-identities`](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) — the identity model
+- [`rest-api-authentication`](https://dev.wix.com/docs/api-reference/articles/authentication/rest-api-authentication) — headers, token kinds
+- [`retrieve-tokens`](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens) — the `/oauth2/token` contract, all grant types
+- [`about-authentication`](https://dev.wix.com/docs/go-headless/authentication/about-authentication) — visitor vs member sessions
+- [`create-an-oauth-app-for-visitors-and-members`](https://dev.wix.com/docs/go-headless/getting-started/setup/authentication/create-an-oauth-app-for-visitors-and-members) — where the client id comes from
+- [`set-up-a-headless-client`](https://dev.wix.com/docs/go-headless/authentication/setup/set-up-a-headless-client) — wiring the client
+
+## Special APIs worth knowing
+
+**Dynamic Site Context — "what IS this site?"** One admin call returns a markdown report of the
+whole site — installed apps, status, URL, locale, CMS collections — the same output the Wix MCP's
+site-context tool renders:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
+  --data-raw '{"siteId": "<metasite id>"}' | jq -r '.markdown'
+```
+
+A `200` with `"markdown": ""` means the token or `siteId` is wrong — the endpoint reports an empty
+context instead of an auth error, so treat empty as "check auth", never as "empty site".
+
+For site management, the **`wix-manage`** skill carries per-area recipes. It may already be
+installed at
+`.agents/skills/wix-manage/`; install it with `npx -y skills add wix/skills/skills/wix-manage`,
+or read it straight off the registry: `https://www.wix.com/skills/wix-manage`.
+
 ## Before you write the code
 
 Confirm on the page — not from memory — the endpoint, the HTTP verb, the request body shape,

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, analytics, accessibility, dashboard-navigation."
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, analytics, accessibility, dashboard-navigation."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -166,8 +166,8 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ## Domains
 
-### [Domain Search and Purchase](references/domains/domain-search-and-purchase.md)
-**Technical:** Search for available domains, get domain suggestions, and generate purchase links using Domain Search V2 API. Covers availability checks, TLD filtering, and connecting domains to Wix sites.
+### [Domain Search, Purchase and Connect](references/domains/domain-search-purchase-and-connect.md)
+**Technical:** Purchase domains, connect domains to Wix sites, search for available domains and get domain suggestions. Covers availability checks, TLD filtering, purchase flow and connecting domains to Wix sites.
 
 ### [Domains Dashboard Navigation](references/domains/domains-dashboard-navigation.md)
 **Technical:** Direct links to the site-level domain settings page and the account-level My Domains page on manage.wix.com, paired with the Domain Search read APIs.
@@ -230,10 +230,10 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ## Events
 
 ### [Create Event](references/events/create-wix-event.md)
-**Technical:** Creates an event with the Wix Events V3 API — required request body, ISO-8601 date and time settings, venue/online/TBD location and street addresses, RSVP vs ticketed registration, guest capacity, and short vs Ricos rich-text descriptions. Distinguishes Wix Events from the Calendar, Marketing Calendar and Automations APIs that share the "events" name. Key endpoint: /events/v3/events.
+**Technical:** Creates an event with the Wix Events V3 API — required request body, ISO-8601 date and time settings, venue/online/TBD location and street addresses, RSVP vs ticketed registration, guest capacity, short vs Ricos rich-text descriptions, ticket tiers and pricing, and recurring series from explicit occurrence dates. Distinguishes Wix Events from the Calendar, Marketing Calendar and Automations APIs that share the "events" name. Key endpoints: /events/v3/events, /events/v3/ticket-definitions.
 
 ### [Manage Events](references/events/manage-wix-events.md)
-**Technical:** Manages existing events with the Wix Events V3 API — ticket definitions and pricing (fixed, free, donation, multiple tiers), publishing a draft, cancelling, deleting, cloning, updating an event's date, counting events, and building recurring series from explicit occurrence dates. Key endpoints: /events/v3/events, /events/v3/ticket-definitions.
+**Technical:** Operates on events that already exist with the Wix Events V3 API — publishing a draft, cancelling, deleting, cloning, updating an event's date, and counting events, plus the draft-event permission that makes those calls fail with 403. Key endpoint: /events/v3/events.
 
 ---
 
@@ -341,11 +341,13 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ## Rich Content
 
+> **Routing rule (READ FIRST).** For every request to hand-author, output, or return Ricos / `richContent` JSON (`nodes` tree) for Blog, Stores, Events, or CMS, use the available full-documentation reading capability to retrieve and read the canonical [Author Ricos Rich Content](references/rich-content/author-ricos-rich-content.md) recipe before using API schema search, convert/validate APIs, or memory. This also applies when the user asks for JSON only.
+
 ### [Ricos Converter Service](references/rich-content/ricos-converter-service.md)
 **Technical:** Validates and converts content between Ricos documents and HTML/Markdown/plain text using the Ricos Documents API. Covers plugin configuration, format conversion in both directions, and document validation.
 
 ### [Author Ricos Rich Content](references/rich-content/author-ricos-rich-content.md)
-**Technical:** Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) reused across Blog, Stores, Events, and CMS. Covers every common node shape — paragraphs, headings, lists, blockquotes, dividers, tables with cell fills, code blocks, images — plus inline text decorations and the nesting rules the format enforces.
+**Technical:** Required first source for every request to hand-author, output, or return Ricos / `richContent` JSON (`nodes` tree) for Blog, Stores, Events, or CMS. Retrieve and read this full article before API schema search or constructing the JSON. Covers node shapes — paragraphs, headings, lists, blockquotes, dividers, tables with cell fills, code blocks, images, buttons, audio, video, galleries, collapsible lists, HTML embeds — plus inline text decorations (including spoiler) and nesting rules.
 
 ---
 
@@ -367,9 +369,15 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Create Headless Site](references/sites/create-headless-site.md)
 **Technical:** Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
 
+### [Manage OAuth Apps](references/sites/manage-oauth-apps.md)
+**Technical:** Create, read, update, and query OAuth apps for a Wix headless site. Each OAuth app's `id` is the `client_id` for frontends connecting to the site's Wix APIs. Secret and rotation are dashboard-only.
+
 ### [Query Sites](references/sites/query-sites.md)
 **Technical:** Lists and queries all sites associated with a Wix account using Sites API. Covers pagination with cursor-based navigation.
 
+### [Read Account or Site Context](references/sites/read-site-context.md)
+**Technical:** One call that returns a site's installed apps (by display name), locale, currency, status, and catalog version. Replaces separate query-sites + list-installed-apps + site-properties calls. Use this first on any unfamiliar site to decide which management recipes to follow.
+
 ### [Site Import](references/sites/site-import.md)
 **Technical:** Drives the autonomous Wix Site Import agent over REST (`/site-import/v1/imports`) to migrate a store/site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix. Covers Start/Poll/Reply/Cancel, relaying agent questions and progress in plain language, handling `DEPLOYED`/`FAILED`/`AUTH_EXPIRED`/`SESSION_EXPIRED` states, and post-deploy follow-up changes. Use when the user wants to import, migrate, or clone an existing store/site into Wix.
 
@@ -383,18 +391,11 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Add Store Pages to Site](references/stores/add-store-pages-to-site.md)
 **Technical:** Adds missing checkout and cart pages to a site when Stores app is installed. Used when store pages are missing after migration or setup issues.
 
-### [Bulk Create Products with Options](references/stores/bulk-create-products-with-options.md)
-**Technical:** Uses bulk products endpoint to create multiple products with inventory in a single request. Handles variant generation from options, media format requirements, and error handling for partial failures.
-
-### [Create Product from Image](references/stores/create-product-from-image.md)
-**Technical:** **MANDATORY entry point** for any "create product from image" or "create product from photo" request. STEP 1 auto-detects the site's catalog version (V1/V3) via the provision endpoint, then runs the matching flow inline — V3 supports up to 3 images, info sections, SEO, options/variants, and atomic creation; V1 supports a single image, simple product, and a separate media-attach call. Combines Media Upload + LLM analysis + Product Creation + (V1 only) Add Product Media in one self-contained recipe.
-
-
 ### [Create Product (Catalog V1)](references/stores/create-product-catalog-v1.md)
 **Technical:** Create products using the Catalog V1 Products API. Use this recipe when the site's catalog version is CATALOG_V1. Covers simple product creation, product with options, and key V1 request structure differences from V3.
 
-### [Create Product with Options (Catalog V3)](references/stores/create-product-with-options-catalog-v3.md)
-**Technical:** Single product creation with options using Catalog V3 Products API. Covers option types (TEXT_CHOICES, SWATCH_CHOICES), choice configuration, and automatic variant generation.
+### [Create Product (Catalog V3)](references/stores/create-product-catalog-v3.md)
+**Technical:** **Mandatory first read for every Catalog V3 create-product request, including vague requests.** Before any other documentation or API tool, load exactly `https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-catalog-v3`. When no product is identified, that recipe read must be the final tool call; respond only: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.” Then stop. **Never replace this with a list or questions for name, price, description, type, images, inventory, SKU, options, SEO, or other fields.** If name or price is missing, ask for it or offer to suggest it, then stop. When name and price are present, create from supplied details without requiring optional enrichment. Never default price to `0`. The recipe owns single/bulk endpoint choice, inventory, physical/digital products, images, options, variants, prices, SKUs, limits, and validation.
 
 ### [Find Products (Query and Search, Catalog V3)](references/stores/find-products-query-and-search-catalog-v3.md)
 **Technical:** Find, search, query, and list products from a Wix Store using Catalog V3 Search Products and Query Products endpoints. Explains when to use each endpoint, correct fields enum values, filtering, sorting, and paging.
@@ -402,9 +403,6 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Query Products (Catalog V1)](references/stores/query-products-catalog-v1.md)
 **Technical:** Query and list products from a Wix Store using the Catalog V1 Query Products endpoint. Use this recipe when the site's catalog version is CATALOG_V1. Covers basic queries, filtering, sorting, and paging.
 
-### [Setup Online Store (Catalog V3)](references/stores/setup-online-store-catalog-v3.md)
-**Technical:** Initializes a Stores catalog with Catalog V3 Products API, bulk products endpoint, and Categories API. Covers product creation, option configuration, variant management, and category assignment.
-
 ### [Update Product Pre-Order](references/stores/update-product-pre-order.md)
 **Technical:** Manages pre-order settings for product variants using V3 Inventory API. Covers enabling/disabling pre-orders, setting messages, configuring limits, and handling trackQuantity requirements.
 

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

@@ -149,7 +149,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `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`
+**Response:** Save the service ID from `results[0].itemMetadata.id`
 
 ---