@wix/agent-skills 1.33.0 → 1.33.1

package/README.md

@@ -39,6 +39,16 @@ Install using [Gemini CLI](https://geminicli.com):
 gemini extensions install https://github.com/wix/skills
 ```
 
+### Antigravity Plugin
+
+In [Antigravity](https://antigravity.google), open **Customizations → Plugins**, click **+ Install from URL**, and enter `https://github.com/wix/skills/tree/main/antigravity/wix`. Or, from a terminal:
+
+```bash
+agy plugin install https://github.com/wix/skills/tree/main/antigravity/wix
+```
+
+The Wix MCP server signs you in to your Wix account the first time a Wix tool is used.
+
 ### Skills CLI
 
 Install using [skills CLI](https://github.com/vercel-labs/skills):
@@ -93,6 +103,17 @@ When a major bump is required (a breaking change in the underlying `wix-cli`), t
 
 Besides the npm package, skills are served as raw markdown / `.tgz` at `https://www.wix.com/skills/<name>` (also `dev.wix.com/skills`), directly from the `main` branch of `wix/skills` with no build step. Responses are cached, so a change reflects there within a few minutes of reaching that branch.
 
+## Privacy and telemetry
+
+Only `wix-replatform` collects telemetry. The other skills send nothing of their own; calls they make to Wix APIs and the Wix MCP are covered by the [Wix Privacy Policy](https://www.wix.com/about/privacy).
+
+During a migration run, `wix-replatform`:
+
+- **Sends run telemetry to Wix** (`https://frog.wix.com/migration-data-validator`): stage timings and outcomes, migrated record counts, errors and gaps by type (never record contents), the source platform and site URL, the destination site ID and the operator's Wix user ID. Turn it off with `RP_TELEMETRY_BI_DISABLED=1`.
+- **Reads the agent's Claude Code session transcripts** (`~/.claude/projects/`) at the end of the run, copies them compressed into the migration project's `telemetry/transcripts/` folder on your machine, and adds a summary (token cost, turn counts, tool failures, retry loops) to the run telemetry. The transcripts themselves stay local. Turn it off with `RP_TELEMETRY_TRANSCRIPT_DISABLED=1`.
+
+Set the variables in the environment the agent runs in. See [wix-replatform/README.md](wix-replatform/README.md).
+
 ## Contributing
 
 To report a problem with a skill or suggest a change, [open an issue](https://github.com/wix/skills/issues/new). Pull requests are not merged in this repository; accepted changes are made by the maintainers. See [CONTRIBUTING.md](CONTRIBUTING.md) for what makes a useful report.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.33.0",
+  "version": "1.33.1",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,7 @@
     "url": "https://github.com/wix/skills/issues"
   },
   "scripts": {
-    "version": "node .github/scripts/sync-plugin-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json plugin.json gemini-extension.json skills/wix-headless-kit/install/pins.json"
+    "version": "node .github/scripts/sync-plugin-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json plugin.json gemini-extension.json antigravity/wix/plugin.json skills/wix-headless-kit/install/pins.json"
   },
   "files": [
     "skills/**",

package/skills/wix-app/references/DASHBOARD_PAGE.md

@@ -33,7 +33,7 @@ The CLI generates the folder, the page's component file (`<page>.tsx`, the build
 
 **After scaffolding, check `routePath`:** use `support-tickets`, not `/support-tickets`; a leading slash fails registration even if the build passes. Internal router paths stay `/`, `/:id`, `/new`, never prefixed with `<route>` — see `<pkgRoot>/dist/docs/Collection to Entity Flow.md`.
 
-**Before writing that UI:** copy in the installed `@wix/patterns` page template that matches, per [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md) — don't compose the shell from scratch.
+**Before writing UI:** copy the [template](dashboard-page/DRAFT_TEMPLATE.md). Make sure `WixPatternsProvider` remains at the extension root, inside `BusinessManagerTheme` and above all components calling Patterns hooks.
 
 **Then, for whatever the template doesn't cover:** list every patterns name you'll add, and resolve them all in one `node <pkgRoot>/bin/patterns-lookup.cjs <name…>` call ([WIX_PATTERNS_DOCS.md § 1](WIX_PATTERNS_DOCS.md#1--the-index)). Its import, examples and props file decide whether you open anything else. Each Bash call is a fresh shell — re-set the path variable every time.
 

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.33.0"
+    "ref": "v1.33.1"
   }
 }

package/skills/wix-manage/SKILL.md

@@ -36,8 +36,8 @@ Lists all apps installed on a site using Apps Installer API. Useful for verifyin
 
 ## Custom Apps
 
-### [Use App Skills and App Tools](references/custom-apps/use-app-skills-and-app-tools.md)
-"Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use every time a site has custom apps installed, before acting on the user's request: knowing which apps are installed doesn't tell what they can do, so only this skill's discovery calls show whether one of them handles the request. Also use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
+### [Use App Tools](references/custom-apps/use-app-tools.md)
+"Discovers and runs app tools, the actions and lookups that apps installed on a Wix site expose to AI agents, for example converting a price with a pricing app or tracking a package with a shipping app. Covers listing the site's app tools, choosing one by its description, and running it with a payload built from its input schema. Use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app or app tool."
 
 ---
 
@@ -237,10 +237,16 @@ Routes discounts, coupons, sales and bundles to promotion recipes, and visual pr
 ## Events
 
 ### [Create an Event with the Wix Events API](references/events/create-wix-event.md)
-"Creates an event with the Wix Events V3 API — the required request body, ISO-8601 date and time settings, venue/online/TBD location, RSVP vs ticketed registration, guest capacity, short vs rich-text descriptions, ticket tiers and pricing, and recurring series. Covers the exact field shapes and the API's misleading validation messages. Use when the user wants to create an event, set its date, location, description, guest limit or ticket prices, or set up a repeating event."
+"Creates an event with the Wix Events V3 API — one-off or recurring, RSVP, ticketed, registration-free or with external registration — including date and time, venue or online location, guest limit, description and ticket tiers. Covers the exact field shapes and the API's misleading validation messages. Use when the user wants to create or set up an event, an information-only event, or a repeating event — including a weekly workshop, class or meetup series held on set dates at a venue or online; a Bookings class or course is booked per session instead."
 
 ### [Manage Wix Events — Publishing, Cancelling, Cloning and Counting](references/events/manage-wix-events.md)
-"Operates on events that already exist with the Wix Events V3 API — finding an event by title, publishing a draft, cancelling, deleting (one or by filter), cloning, updating an event's date or details, and counting events. Use when the user wants to find, publish or cancel an event, duplicate one, move an event's date, delete events in bulk, or count their events. Creating an event, its tickets or a recurring series is a separate recipe."
+"Operates on Wix events that already exist with the Wix Events V3 API — finding, updating (date, venue, details, page settings), controlling registration (close, reopen, registration-free, external, members-only, limits), switching between RSVP and ticketed (a new event — ask before creating it), publishing, cancelling, deleting, cloning and counting, including single occurrences of a recurring event. Use to close registration, move or cancel an event, or change how guests register."
+
+### [Manage Event Tickets](references/events/manage-event-tickets.md)
+"Manages the ticket types of a ticketed Wix event with the Ticket Definitions V3 API — adding, editing, repricing, hiding, reordering and deleting tickets, scheduling or ending ticket sales, and changing the ticket currency. Use when the user wants to add early-bird, VIP, child or donation tickets to an existing event, change a ticket's price or quantity, or set when tickets stop selling."
+
+### [Manage Event Guests](references/events/manage-event-guests.md)
+"Manages the people registered for a Wix event — RSVPs on RSVP events, and orders, tickets and ticket holders on ticketed events: listing and counting guests, adding or removing a guest, changing an RSVP, checking guests in, and marking orders paid. Use when the user asks who is coming or how many registered, or wants to add, remove or check in a guest. Notes what the API can't do, such as refunds and resending emails."
 
 ---
 
@@ -455,7 +461,7 @@ Query and list products from a Wix Store using the Catalog V1 Query Products end
 Manages pre-order settings for product variants using V3 Inventory API. Covers enabling/disabling pre-orders, setting messages, configuring limits, and handling trackQuantity requirements.
 
 ### [Update Product with Options (Catalog V3)](references/stores/update-product-with-options.md)
-Start here for existing Catalog V3 product updates, including digital products that fail at add-to-cart with ITEM_NOT_FOUND_IN_CATALOG. Includes name lookup, Get Product, and PATCH in one flow, plus importing a supplied PDF and attaching it to the existing variant. Covers options, variant prices and SKUs, product visibility (hide/unhide through `visible`, never delete), description edits that preserve Rich Content, and revision-based updates. Read another recipe only for a field or operation this flow does not cover.
+Start here for existing Catalog V3 product updates, including digital products that fail at add-to-cart with ITEM_NOT_FOUND_IN_CATALOG. Includes name lookup, Get Product, and PATCH in one flow, plus importing a supplied PDF and attaching it to the existing variant. Covers options, variant prices and SKUs, variant shipping weight in the site's weight unit, product visibility (hide/unhide through `visible`, never delete), description edits that preserve Rich Content, and revision-based updates. Read another recipe only for a field or operation this flow does not cover.
 
 ### [Stores Dashboard Navigation](references/stores/stores-dashboard-navigation.md)
 "Builds direct links to Wix Stores and eCommerce dashboard pages on manage.wix.com — products list, edit a specific product, categories, inventory, orders list, a specific order, abandoned checkouts, gift cards, shipping and tax settings. Pairs each main Stores/eCommerce entity with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
@@ -464,7 +470,7 @@ Start here for existing Catalog V3 product updates, including digital products t
 ## Automations
 
 ### [Build and Manage Wix Automations](references/automations/build-and-manage-automations.md)
-Inspect Wix automations and their on/off status, create linear automations from the site’s installed triggers and actions, and turn automations on or off on request.
+Create, update, activate or deactivate Wix Automations with app actions, trigger filters, conditions, delays, variables, branches and schedules, and check their current status, using the public Wix Automations APIs.
 
 <details>
 <summary>Internal skills (loaded on demand by Build and Manage Wix Automations — do NOT use directly)</summary>
@@ -484,8 +490,20 @@ Inspect Wix automations and their on/off status, create linear automations from
 - [Automations Mapping Expressions](references/automations/bracket-expressions.md)
   Write builder-compatible automation mapping expressions, literals and data references.
 
+- [Automations Conditions](references/automations/conditions.md)
+  Configure visual and code conditions while preserving boolean intent, comparison boundaries and builder editability.
+
+- [Automations Delays Variables and Branches](references/automations/special-actions.md)
+  Configure delay, rate-limit, variable and parallel-branch steps, preserving supported existing step metadata.
+
+- [Automations Schemas and Scheduling](references/automations/schemas-and-scheduling.md)
+  Configure dynamic schemas and scheduled automation triggers with correct timezone and calendar behavior.
+
+- [Automations Validation and Persistence](references/automations/validation-and-verification.md)
+  Validate automation configuration, check builder compatibility, persist changes and verify the saved result.
+
 - [Automations Activation Status](references/automations/activation-status.md)
-  Read an automation’s current ACTIVE or INACTIVE status, and activate or deactivate it when the user asks.
+  Inspect or change active status with lock checks, revision handling and read-back, without requiring unrelated repairs before deactivation.
 
 </details>
 

package/skills/wix-manage/references/automations/actions.md

@@ -3,7 +3,7 @@ name: "Automations Action Configuration"
 description: "Configure app-defined automation actions from their input schemas and preserve supported existing action mappings."
 ---
 
-> **Stage scope:** this stage covers only what [Build and Manage Wix Automations](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) lists; do not perform anything marked "Later stages only" or any workflow that needs a guide marked "not yet published". "Stage", "Later stages only" and "not yet published" describe how this skill is being rolled out; never mention them to the user. Explain a limit in product terms: what can't be done through the API here and where the user can do it instead (for example, in the automations builder).
+> **Stage scope:** this stage covers only what [Build and Manage Wix Automations](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) lists; do not perform anything marked "Later stages only", and follow the instruction attached to each guide marked "not yet published". "Stage", "Later stages only" and "not yet published" describe how this skill is being rolled out; never mention them to the user. Explain a limit in product terms: what can't be done through the API here and where the user can do it instead (for example, in the automations builder).
 
 # App-Defined Actions — Discovery, Schemas, Input Mapping
 
@@ -11,9 +11,9 @@ description: "Configure app-defined automation actions from their input schemas
 
 - An action is `appId` + `actionKey`. Find real ones with **Resolve Actions** (site catalog), then read the version active on the site with **Get Runtime Action**. Never invent keys.
 - The configuration is `appDefinedInfo.inputMapping`: an object keyed ONLY by input-schema property names, with values of the schema's type — literals, or `{{…}}` formulas in fields the UI schema marks as dynamic.
-- Fields marked `updateSchemaOnChange: true` reveal more inputs once set → **Get Action Dynamic Input Schema**. Output that depends on configuration → **Get Action Dynamic Output Schema** after the mapping is final.
-- **Later stages only — email is outside stage 2:** **Send an email** (`triggered-emails`): initialize each NEW step with **Generate Action Input Mapping**, persist the returned mapping unchanged, then configure content with Get / Set Email Content (Automations Email Actions (not yet published)). Existing content-only edits do not initialize another email.
-- Entity-selector fields take **ids**, never display names (Automations Entity and Provider Configuration (not yet published)).
+- Fields marked `updateSchemaOnChange: true` reveal more inputs once set → **Get Action Dynamic Input Schema**. Output that depends on configuration → **Get Action Dynamic Output Schema** after the mapping is final, except user-defined LLM result fields: declare their override schema directly (§4).
+- **Later stages only — email is outside stage 3:** **Send an email** (`triggered-emails`): initialize each NEW step with **Generate Action Input Mapping**, persist the returned mapping unchanged, then configure content with Get / Set Email Content (Automations Email Actions (not yet published; email configuration is outside stage 3)). Existing content-only edits do not initialize another email.
+- Entity-selector fields take **ids**, never display names (Automations Entity and Provider Configuration (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))).
 - Before accepting any action, prove its side effect and its recipient (§6).
 
 ---
@@ -29,7 +29,7 @@ Site-scoped (`wix-site-id` header), SDK module `actionCatalog`: Resolve Actions
 3. Get Runtime Action for the 1–3 best candidates; build against that version's `inputSchema`, `outputSchema`, `interfaceConfiguration`.
 4. An action missing from Resolve Actions is not usable on this site. The builder shows such a step as "action not found" and blocks it.
 
-**Do not use** unsupported or deprecated actions — `send-mail` (→ `triggered-emails`), `send-coupon-action` (→ `wixcoupons-retrieve_coupon` + a delivery step that uses its code), `wix_automations-velo_action`, `wix_automations-data_manipulation_code` (code variable; public Create refuses it — §4 of Automations Delays Variables and Branches (not yet published)), `whatsapp-send-message` (WhatsApp), `forward-to-zapier` (Zapier), and site actions `wix_automations-wix_api_integration` (non-public). Match these by `actionKey` (+ `appId`), not by app or display name — other actions of the same app are fine. Reasons and replacements: §2 of Automations Feasibility and Planning (not yet published) (site actions: §1).
+**Do not use** unsupported or deprecated actions — `send-mail` (→ `triggered-emails`), `send-coupon-action` (→ `wixcoupons-retrieve_coupon` + a delivery step that uses its code), `wix_automations-velo_action`, `wix_automations-data_manipulation_code` (code variable; public Create refuses it — [Automations Delays Variables and Branches](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-delays-variables-and-branches) §4), `whatsapp-send-message` (WhatsApp), `forward-to-zapier` (Zapier), and site actions `wix_automations-wix_api_integration` (non-public). Match these by `actionKey` (+ `appId`), not by app or display name — other actions of the same app are fine. Reasons and replacements: §2 of Automations Feasibility and Planning (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations)) (site actions: §1).
 
 ### Selection rules
 
@@ -55,7 +55,7 @@ Conditional fields (`if`/`then`/`dependencies`, e.g. a due date shown only when
 UI-schema keys that change what you may write:
 
 - `dynamicValuesOptions.enabled: true` → the field accepts `{{…}}` formulas. `strict: true` → the formula must return the field's exact type/format. **A field without it is static: literal only.**
-- `"ui:widget": "EntitySelector"` + `entitySelectorOptions` (`selectorId`/`tag`, `filters`, `dynamicFiltersMapping`) → entity picker; value = id or array of ids (§1 of Automations Entity and Provider Configuration (not yet published)). Same for input properties carrying `itemsSelectionConfiguration`.
+- `"ui:widget": "EntitySelector"` + `entitySelectorOptions` (`selectorId`/`tag`, `filters`, `dynamicFiltersMapping`) → entity picker; value = id or array of ids (§1 of Automations Entity and Provider Configuration (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))). Same for input properties carrying `itemsSelectionConfiguration`.
 - `"ui:field": "AudienceSelector"` → an audience object owned by the app's picker; don't hand-author it — the user sets it in the builder.
 - `"ui:field": "TextSectionField"` → display-only text; never map it.
 - `"ui:widget": "hidden"`, `ui:readonly` → keep the schema `default`. Other `ui:*` keys are presentation only.
@@ -63,13 +63,13 @@ UI-schema keys that change what you may write:
 ## 4. Dynamic input and output schemas
 
 - **Input**: a property with `updateSchemaOnChange: true` (e.g. a template or form id) changes which inputs exist. Set it, then call Get Action Dynamic Input Schema with `{appId, actionKey, inputMapping}` (the mapping so far). The builder shows the static schema **merged** with the returned one (properties and `required` united), so keys from either are kept. Repeat if another controlling field is revealed. Never invent a field you expected but didn't get — it appears only after its controlling selection. The builder re-fetches this schema from your saved mapping every time the step is opened, so a dynamic key whose controlling value isn't in the mapping is dropped on the first edit.
-- **Output**: after the mapping is final, call Get Action Dynamic Output Schema (or the bulk variant) and use the returned `outputSchema` for downstream `var()` paths. A dynamic output is a _real_ schema — never replace it with an override (allowlist: §3 of Automations Schemas and Scheduling (not yet published)).
+- **Output**: for `wix_automations-llm_call` result fields you define in its output configuration, declare `overrideOutputSchema` directly ([Automations Schemas and Scheduling](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-schemas-and-scheduling) §3); do not probe the dynamic-output SPI to discover your own declared fields or execute the AI during setup. For catalog-driven dynamic outputs, after the mapping is final, call Get Action Dynamic Output Schema (or the bulk variant) and use the returned `outputSchema` for downstream `var()` paths. A dynamic output is a _real_ schema — never replace it with an override (allowlist: [Automations Schemas and Scheduling](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-schemas-and-scheduling) §3).
 
 ## 5. Building the input mapping
 
 ### 5.1 Provider-owned mappings — email and opaque widgets
 
-> **Later stages only:** email and other opaque-widget configuration is not available in stage 2; this section is published in stage 4.
+> **Later stages only:** email and other opaque-widget configuration is not available in stage 3; this section is published in stage 4.
 
 **In this stage:** never invent an opaque widget's mapping or its app-owned keys; tell the user which action to add in the builder and how it should be configured.
 
@@ -83,7 +83,7 @@ MUST (builder renderability — the `GENERIC` form drops, rewrites or flags anyt
 - An action with no input properties (or only hidden ones): send `"inputMapping": {}` — the builder writes `{}` itself on open otherwise.
 - Map fields the form would auto-fill, or opening the step silently changes the automation: fields with a schema `default` (write the default or your value), every `identityType` input (the form auto-maps it when exactly one matching payload path exists), required `date`/`date-time`/`time` strings (else filled with "now").
 - Enum fields (`oneOf` / `enum`): one of the listed constants.
-- Entity-selector fields: real ids of the right kind and shape (§1 of Automations Entity and Provider Configuration (not yet published)).
+- Entity-selector fields: real ids of the right kind and shape (§1 of Automations Entity and Provider Configuration (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))).
 - `{{…}}` only in fields with `dynamicValuesOptions.enabled` (or an `identityType` field), per [Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions) §4: number/boolean hold exactly one expression of that type; date-time a single date-time expression or ISO literal; strings may mix text and expressions. An **array-typed** `var()` in a string field is flagged as a format mismatch.
 - Don't copy volatile values: dates → `now()`/payload dates; ids → resolved at build time, never from examples.
 - Keep what the user describes for one field in that field. A subject described as "Order received, then the customer's first name" is one `subject` string mixing text and expressions (`"Order received {{var(…)}}"`); don't split its values into other fields, such as a message's `fields` rows.
@@ -113,7 +113,7 @@ Process: (1) fetch the effective schema (§4) before you write a mapping or any
 
 ### 5.3 Validation errors on actions
 
-Error shape, error type → fix, and how the builder shows each: [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §2. Must-know here: fix the field named by `configurationError.fieldKey` — never delete a field to silence it; `CRITICAL` blocks (status `INVALID`), `WARNING` doesn't but must be reported; a `var()` path that doesn't exist may NOT be reported — verify paths yourself.
+Error shape, error type → fix, and how the builder shows each: [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) §2. Must-know here: fix the field named by `configurationError.fieldKey` — never delete a field to silence it; `CRITICAL` blocks (status `INVALID`), `WARNING` doesn't but must be reported; a `var()` path that doesn't exist may NOT be reported — verify paths yourself.
 
 ## 6. Side-effect and recipient review
 
@@ -123,7 +123,7 @@ This section owns the semantic review (you, not code) required for every action
 - **Entity**: the affected entity has a matching input (e.g. a label picker for "add label").
 - **Identity input**: the id it acts on, with the right `identityType`.
 - **Recipient lineage** (email, chat, SMS, push): write down `{requestedAudience, resolvedAudienceKind (contact|visitor|owner|contributor|label|phone|device), resolvedIdentityPath}`. The trigger contact and a contact created upstream are different people even if both are `contactId`. Wording never proves the recipient.
-  - **Later stages only — email is outside stage 2:** Email: the audience fields decide — read `selectedAudience` / `contactId` exactly as in §3 of Automations Email Actions (not yet published) ("Recipient encoding"). A root `contactId` or `triggerContactExcluded` alone doesn't prove who receives it.
+  - **Later stages only — email is outside stage 3:** Email: the audience fields decide — read `selectedAudience` / `contactId` exactly as in §3 of Automations Email Actions (not yet published; email configuration is outside stage 3) ("Recipient encoding"). A root `contactId` or `triggerContactExcluded` alone doesn't prove who receives it.
   - Chat (`send-message`): only a schema-supported contact-id or visitor-id route; owner/team chat needs a different, proven component or a clarification.
   - SMS / push: prove the schema-supported contact, audience, phone or device route.
 

package/skills/wix-manage/references/automations/activation-status.md

@@ -1,10 +1,8 @@
 ---
 name: "Automations Activation Status"
-description: "Read an automation’s current ACTIVE or INACTIVE status, and activate or deactivate it when the user asks."
+description: "Inspect or change active status with lock checks, revision handling and read-back, without requiring unrelated repairs before deactivation."
 ---
 
-> **Stage scope:** this stage covers only what [Build and Manage Wix Automations](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) lists; do not perform any workflow that needs a guide marked "not yet published". "Stage" and "not yet published" describe how this skill is being rolled out; never mention them to the user. Explain a limit in product terms: what can't be done through the API here and where the user can do it instead (for example, in the automations builder).
-
 # Activation status and lifecycle
 
 **What the public API can see.** An automation's live state is `configuration.status` —
@@ -12,8 +10,7 @@ description: "Read an automation’s current ACTIVE or INACTIVE status, and acti
 Status does not show whether past runs succeeded. There is no separate
 "published" flag and no public draft API:
 
-- **Status check** = Get Automation → read `configuration.status`. Report exactly that value, in a
-  short answer that starts with the automation's name and returned ID;
+- **Status check** = Query by name (if no ID) → Get the single matching ID → read that Get response’s `configuration.status`. Query is discovery only: never answer from its status projection, even if it includes one. Report the name, returned ID and status, explaining ACTIVE as eligible for new trigger events and INACTIVE as not eligible;
   never infer it from the name or from your own earlier writes. If several automations match the
   supplied name, list each one's returned ID and end with a direct question such as "Which one
   do you mean?"; don't report a single status. If no automation matches the supplied name, say
@@ -44,10 +41,10 @@ Status does not show whether past runs succeeded. There is no separate
 1. Get Automation with `fields: ["OVERRIDE_SCHEMA"]` → current `revision`, `origin`, `settings`.
    If `settings.disableStatusChange`
    or `settings.readonly` is true, stop and report the lock: the owning app doesn't allow it
-   (§4 of Automations Feasibility and Planning (not yet published)).
+   ([Automations Validation and Persistence — included update restrictions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence)).
 2. Already `ACTIVE` → report it and stop (idempotent; no write).
-3. Set only the candidate's status to `ACTIVE`, then apply the §4 checklist in [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) and full Validate — never activate
-   an automation that doesn't validate. Preserve existing supported configurations as the §4 checklist in [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) explains.
+3. Set only the candidate's status to `ACTIVE`, then apply the §4 checklist in [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) and full Validate — never activate
+   an automation that doesn't validate. Preserve existing supported configurations as the §4 checklist in [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) explains.
 4. Explicit activation instructions authorize this change; do not ask again. If the user only
    asked to build or inspect it, obtain authorization before making it eligible for real runs.
 5. Update Automation with the object exactly as fetched, `configuration.status: "ACTIVE"`, and
@@ -59,7 +56,7 @@ Status does not show whether past runs succeeded. There is no separate
 **Deactivate** (on explicit request): Get the complete object with override schemas; check
 `settings.disableStatusChange` and `settings.readonly`; already INACTIVE means no write.
 Otherwise change only `configuration.status` to `INACTIVE`, preserving origin, settings,
-revision, schemas and all nodes, then Update and read back the returned id. **Do not run the §4 checklist in [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) or
+revision, schemas and all nodes, then Update and read back the returned id. **Do not run the §4 checklist in [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) or
 Validate as a prerequisite**, and do not repair or remove unrelated invalid/legacy steps.
 An explicit request to turn it off is sufficient authorization. Deactivating prevents new
 triggered runs; it is not proof that every pending/running activation has stopped or will finish.

package/skills/wix-manage/references/automations/api-catalog.md

@@ -3,7 +3,7 @@ name: "Automations API Catalog"
 description: "Discover site-specific triggers and actions, authenticate public Automation API calls, and choose the API for validation, persistence or catalog lookups."
 ---
 
-> **Stage scope:** this stage covers only what [Build and Manage Wix Automations](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) lists; do not perform anything marked "Later stages only" or any workflow that needs a guide marked "not yet published". "Stage", "Later stages only" and "not yet published" describe how this skill is being rolled out; never mention them to the user. Explain a limit in product terms: what can't be done through the API here and where the user can do it instead (for example, in the automations builder).
+> **Stage scope:** this stage covers only what [Build and Manage Wix Automations](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) lists; do not perform anything marked "Later stages only", and follow the instruction attached to each guide marked "not yet published". "Stage", "Later stages only" and "not yet published" describe how this skill is being rolled out; never mention them to the user. Explain a limit in product terms: what can't be done through the API here and where the user can do it instead (for example, in the automations builder).
 
 # API Catalog — the public Wix Automations APIs
 
@@ -16,19 +16,19 @@ docs URL to get raw markdown. When a field name here and the docs disagree, the
 
 - Catalogs: Resolve Triggers / Resolve Actions. Oracle: **Validate Automation** — Create and
   Update do **not** validate.
-- Persist: Create `INACTIVE` → Get read-back; activate only when asked.
-  Procedures (create, activate, read-back
-  — builder drafts are invisible publicly): [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §3.
-- **Later stages only — not in stage 2:** **Test Automation runs actions for real** — only with explicit user authorization.
+- Persist: Create `INACTIVE` → Get read-back; activate only when asked. Updates need the current
+  `revision` and are **live** on an active automation. Procedures (create, update, activate, read-back
+  — builder drafts are invisible publicly): [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) §3.
+- **Test Automation runs actions for real** — only with explicit user authorization.
 - Resolve responses are large: page small, filter by exact keys, never paste a raw catalog.
 
 ## 1. Authentication and transport
 
 - **Permission scope**: **Set Up Automations** (`SCOPE.CRM.SETUP-AUTOMATIONS`) for every
-  Automations method below. Generate Action Input Mapping and Get / Set Email Content (Automation Email Action API) need **Manage
-  Email Marketing** (`SCOPE.DC-PROMOTE.EMAIL-MARKETING`) — a 403 there means that scope is missing.
+  Automations method below. Email steps are added in the automations builder, so no **Manage
+  Email Marketing** (`SCOPE.DC-PROMOTE.EMAIL-MARKETING`) scope is needed here.
   Entity lookups in other verticals need that vertical's read scope
-  (Automations Entity and Provider Configuration (not yet published)).
+  (Automations Entity and Provider Configuration (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))).
 - **Token**: `Authorization: <token>` header — an OAuth app access token (`client_credentials` via
   Create Access Token) or an account API key the site owner generated with the needed scopes.
 - **Site context**: with an **API key**, send `wix-site-id: <metaSiteId>` on every call (all calls
@@ -44,17 +44,15 @@ docs URL to get raw markdown. When a field name here and the docs disagree, the
   confirmed. If anything points at another site, stop.
 - **Errors**: 401 = token expired/invalid (refresh, don't retry blindly). 403 = missing scope, app
   not installed, or — on Create/Update of an automation that validated — a step the public API
-  can't create (e.g. the code-variable step, §4 of Automations Delays Variables and Branches (not yet published)). A timeout or 5xx is
+  can't create (e.g. the code-variable step, [Automations Delays Variables and Branches](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-delays-variables-and-branches) §4). A timeout or 5xx is
   **unknown**, not a verdict — retry read-only calls (Get, Query, Resolve, Validate) a bounded
   number of times. Never blindly retry Create or Update: Query or Get first to see whether the
-  write landed ([Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §3, Reporting rules).
+  write landed ([Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) §3, Reporting rules).
 
 ## 2. Automations V2 (`automationsV2`) — base `/automations-service/v2/automations`
 
-> Stage 2 supports Query, Get, Validate, inactive Create, and Update only to activate or deactivate ([Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status)). Configuration updates, Delete and Test Automation below are future-stage reference material; do not call them in this stage.
-
-| Purpose  | REST                                                        | SDK                                       |
-| -------- | ----------------------------------------------------------- | ----------------------------------------- |
+| Purpose  | REST                                                                               | SDK                                       |
+| -------- | ---------------------------------------------------------------------------------- | ----------------------------------------- |
 | Validate | `POST https://www.wixapis.com/automations-service/v2/automations/validate`         | `validateAutomation(automation, options)` |
 | Create   | `POST https://www.wixapis.com/automations-service/v2/automations`                  | `createAutomation(automation)`            |
 | Get      | `GET https://www.wixapis.com/automations-service/v2/automations/{automationId}`    | `getAutomation(automationId)`             |
@@ -65,7 +63,7 @@ docs URL to get raw markdown. When a field name here and the docs disagree, the
 - **Validate** (unsaved or saved): `{automation, validationSettings?{actionIds[],
 skipProviderValidations}}` → `{status: VALID|VALID_WITH_WARNINGS|INVALID,
 triggerValidationErrors[], actionValidationErrors[]}`. The main oracle; send the full object.
-  Reading errors: [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §2.
+  Reading errors: [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) §2.
 - **Create**: `{automation}` with `name`, `origin: "USER"`, `configuration{status, trigger{appId,
 triggerKey}, rootActionIds, actions}` → created `automation` (has `id`, `revision`). Does NOT
   validate. Always `status: "INACTIVE"`; don't send `settings`.
@@ -74,8 +72,16 @@ triggerKey}, rootActionIds, actions}` → created `automation` (has `id`, `revis
   request them: `fields: ["OVERRIDE_SCHEMA"]` (REST `?fields=OVERRIDE_SCHEMA`). Without it their
   absence is not data loss (Create's response omits them too).
   Request overrides before complete-object updates and status changes too, not just creation read-back.
-- **Update**: in this stage, only to change `configuration.status` (activate / deactivate) as [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) describes. Send `{automation}` exactly as fetched with `fields: ["OVERRIDE_SCHEMA"]` — `id`, current `revision`, `name`, `configuration`, plus `origin` and `settings` — with only the status changed. Without `origin` and `settings` it fails `INVALID_ORIGIN_TYPE`; a stale `revision` is rejected. Capture the returned id: a preinstalled automation's site override can change it. Configuration updates are published in stage 3.
-- **Later stages only — not in stage 2:** **Delete** — published in stage 3.
+- **Update**: `{automation}` incl. `id` and current `revision` → updated `automation` (revision
+  +1). Does NOT validate. Send the complete merged `name` + `configuration`, **plus `origin` and
+  `settings` exactly as fetched** — an Update without them fails `INVALID_ORIGIN_TYPE`. A
+  `fieldMask` (if your client exposes one) only selects what changes — set it to
+  `configuration,name` (what the builder sends); it doesn't exempt you from sending `origin` /
+  `settings`. A stale `revision` is rejected. Changes are LIVE when `status` is `ACTIVE`. A success
+  response and a revision bump do **not** prove the change landed — merge, conflict handling and
+  read-back comparison: [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) §3.
+  Capture the returned id: creating a site override of a preinstalled automation can change it.
+- **Delete**: → `{}`. Irreversible; only on explicit user request.
 - **Query**: `{query{filter, sort, cursorPaging{limit ≤ 500, cursor}}}` → `automations[]`,
   `pagingMetadata.cursors.next`. Returns only automations of apps installed on the site (incl.
   overridden preinstalled ones), and never unpublished builder drafts. Full objects are large —
@@ -85,12 +91,12 @@ triggerKey}, rootActionIds, actions}` → created `automation` (has `id`, `revis
 Automation object fields and limits (`name` ≤ 100 for the builder, `description` ≤ 2000,
 `origin`, `settings`, `configuration`): [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model) §1.
 Create/Update accept `configuration.trigger.automationConfigMapping` for scheduled/custom/webhook
-configuration even where the docs omit it; use [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) / Automations Schemas and Scheduling (not yet published).
+configuration even where the docs omit it; use [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) / [Automations Schemas and Scheduling](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-schemas-and-scheduling).
 
 ## 3. Trigger Catalog (`triggerCatalog`)
 
-| Purpose                | REST                                              | SDK                                             |
-| ---------------------- | ------------------------------------------------- | ----------------------------------------------- |
+| Purpose                | REST                                                                     | SDK                                             |
+| ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
 | Triggers on this site  | `POST https://www.wixapis.com/v1/triggers/resolve`                       | `resolveTriggers(options)`                      |
 | Global catalog         | `POST https://www.wixapis.com/v1/triggers/query`                         | `queryTriggers(query)`                          |
 | One trigger            | `GET https://www.wixapis.com/v1/triggers/apps/{appId}/keys/{triggerKey}` | `getTriggerByAppIdAndKey(identifiers, options)` |
@@ -117,8 +123,8 @@ payload schema ([Automations Trigger Configuration](https://dev.wix.com/docs/api
 
 ## 4. Action Catalog (`actionCatalog`)
 
-| Purpose                    | REST                                                   | SDK                                            |
-| -------------------------- | ------------------------------------------------------ | ---------------------------------------------- |
+| Purpose                    | REST                                                                          | SDK                                            |
+| -------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- |
 | Actions on this site       | `POST https://www.wixapis.com/v1/actions/resolve`                             | `resolveActions(options)`                      |
 | Global catalog             | `POST https://www.wixapis.com/v1/actions/query` (and `/query-latest`)         | `queryActions(query)`, `queryLatestActions`    |
 | Version active on the site | `GET https://www.wixapis.com/v1/actions/apps/{appId}/keys/{actionKey}`        | `getRuntimeAction(identifiers)`                |
@@ -138,13 +144,12 @@ payload schema ([Automations Trigger Configuration](https://dev.wix.com/docs/api
 - **Dynamic output**: `{appId, actionKey, inputMapping}` → `outputSchema`; bulk
   (`bulkGetActionDynamicOutputSchemas`, POST `/v1/actions/bulk/dynamic-output-schema`, ≤ 20 items) →
   `results[]{itemMetadata{success, error}, outputSchema}`. Only after that action's mapping is
-  final. Safe for any action you place upstream of a step that reads its output (no public flag
-  says which are dynamic); an error means "no dynamic output" — keep the static `outputSchema`.
+  final. For `wix_automations-llm_call` fields defined by your output configuration, declare an override directly ([Automations Schemas and Scheduling](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-schemas-and-scheduling) §3); do not call this SPI to discover fields you chose yourself. For other upstream actions whose configured output is needed, this is a read-only discovery call (no public flag says which are dynamic); an error does not establish additional fields — keep the static `outputSchema`.
   Merge into the static schema. A failed bulk item = unknown schema, not empty.
 - **Generate Input Mapping From Intent** (`POST https://www.wixapis.com/v1/actions/generate-input-mapping-from-intent`)
   is AI-backed — don't call it. For actions you can't map from their schema, tell the user they can't be configured through the API here and can be set up in the automations builder.
-- **Later stages only — email is outside stage 2:** **Email content of an existing Send an email step** — Get / Set Email Content; procedure in Automations Email Actions (not yet published).
-- **Later stages only — email is outside stage 2:** **New Send an email step** — Generate Action Input Mapping; procedure in Automations Email Actions (not yet published).
+- **Later stages only — email is outside stage 3:** **Email content of an existing Send an email step** — Get / Set Email Content; procedure in Automations Email Actions (not yet published; email configuration is outside stage 3).
+- **Later stages only — email is outside stage 3:** **New Send an email step** — Generate Action Input Mapping; procedure in Automations Email Actions (not yet published; email configuration is outside stage 3).
 
 Action objects: `appId`, `actionKey`, `displayName`, `description`, `inputSchema`, `outputSchema`,
 `interfaceConfiguration{type: GENERIC\|WIDGET_COMPONENT, genericOptions.uiSchema}`,
@@ -153,8 +158,12 @@ Action objects: `appId`, `actionKey`, `displayName`, `description`, `inputSchema
 
 ## 5. Activations (`activations`)
 
-- **Later stages only — not in stage 2:** **Test Automation** — runs every action for real; published in stage 3.
-- **Later stages only — not in stage 2:** **Run Automation / Report Event / Rerun Activation** — for the app that owns a trigger; never
+- **Test Automation** — `POST https://www.wixapis.com/automations/v1/events/test-automation`,
+  `testAutomation(identifierType, options)`: `{identifierType: "AUTOMATION",
+automationIdentifier{automationId}, payload}` → `activationId`. **Runs every action for real**
+  (skips delays, works on INACTIVE) — explicit user authorization only; payload, consent and
+  reporting: [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) §5.
+- **Run Automation / Report Event / Rerun Activation** — for the app that owns a trigger; never
   use them to build or "test".
 
 ## 6. Catalog discovery without flooding your context
@@ -188,13 +197,13 @@ Discovery hints:
 - Search by concept with a keyword ladder ("chat" → "message"). Common aliases: send a chat
   message to the contact = `send-message` (not `inbox-send-message`); a note about a contact in
   the site owner's Inbox, nothing sent to the contact = `inbox-send-message` ("Show in Inbox");
-  email to anyone, incl. the site
+  email (added by the user in the automations builder here) to anyone, incl. the site
   owner = `triggered-emails` (never the deprecated `send-mail` / "Get an email"); task =
   `createTask`; labels = `addLabelsToContact` / `remove_labels_to_contact`; create a contact =
   `contacts-create_contact` (for triggers whose payload has no contact, e.g. webhooks).
 - Near-duplicates exist (`booking_canceled` vs `bookings_canceled`; new Wix Forms app vs legacy
   "Form submitted"). Compare payload schemas and filters; prefer the one whose entities you can
-  actually find on the site (Automations Entity and Provider Configuration (not yet published)).
+  actually find on the site (Automations Entity and Provider Configuration (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))).
 - Enum-like fields often list legal values only in the field `description` (e.g. paymentStatus
   NOT_PAID / PAID). Read descriptions before mapping user words; never invent enum values.
 
@@ -205,9 +214,16 @@ variables + identity enrichment. Recipe and fetch order: [Automations Graph and
 
 ## 8. Selector options and APIs with limitations
 
-> **Later stages only:** not available in stage 2; this section is published in stage 3.
+**Entity ids** (forms, labels, services, pipeline stages…): resolve them with the owning vertical's public API, following that vertical's API reference, or ask the user for the exact entity. Never save a display name, invent an id or guess an endpoint.
+
+**Not public or not available through the general Automations API:**
 
-**In this stage:** a "draft" is an automation created `INACTIVE` (builder drafts are invisible to the public API). To validate a saved automation, Get it and Validate the returned object. Check expressions locally, then with Validate Automation.
+- **Draft automations** → create `INACTIVE`; the user activates. Builder drafts are invisible.
+- **Site-action generation** → §3 of Automations Entity and Provider Configuration (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations)).
+- **Send an email steps** → not configurable through the API here; the user adds them in the automations builder.
+- **Expression parsing/evaluation, code runner** → local checks ([Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions),
+  [Automations Conditions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-conditions)), then Validate Automation.
+- **Validate by id** → Get Automation, then Validate the returned object.
 
 ## Related API references