@wix/agent-skills 1.31.2 → 1.33.0

package/skills/wix-base44-connector/SKILL.md

@@ -111,7 +111,7 @@ const wx = require(require("path").resolve(P));
 - `wx.bash(cmd)` — shell over saved files (GNU grep/sed; awk is mawk; no rg)
 - `wx.spec(docsUrl | code)` — a method's exact schema, plus the titles of the docs' own request examples saved at `examplesPath`; pass a hit's docsUrl (direct load), or raw code to query the index yourself
 - `wx.mgmtRecipes(q?)` — management-recipe index; no arg → categories, a word → matching recipes
-- `wx.ensureOAuthApp(token, { name, redirectUris, redirectDomains })` — the headless OAuth app, found by name or created, with the redirect lists merged into whatever it already allows; returns `{ clientId, created }`. `clientId` is what the browser mints visitor tokens from. Run it whenever `context` reports no OAuth app, or before any Wix-hosted flow that returns to this app — see Visitor authentication and Wix-hosted flows
+- `wx.ensureOAuthApp(token, { name, redirectUris, redirectDomains })` — the headless OAuth app, found by name or created with `origin: "base44-app"`, with the redirect lists merged into whatever it already allows; returns `{ clientId, created }`. `clientId` is what the browser mints visitor tokens from. Run it whenever `context` reports no OAuth app, or before any Wix-hosted flow that returns to this app — see Visitor authentication and Wix-hosted flows
 - `wx.installApp(appDefId, siteId, token)` — install a Wix app on the site (Apps Installer). If discovery finds an API whose app isn't installed on the site, install it first — that's a one-call prerequisite, **not** a reason to fall back to a hand-built alternative. `appDefId` from `search` or the Apps-Created-by-Wix table; `siteId` from `context` (the site report)
 
 Search makes one combined request across REST, management recipes, and Headless by default.
@@ -363,7 +363,9 @@ creating the OAuth app when the site has none and adding your URLs to its lists
 has one. Returns only complete for URLs in those lists, and a missing one breaks silently —
 create-checkout and the anonymous token still succeed — until a real buyer is redirected and
 stranded on Wix. It is idempotent by name: never create a second OAuth app for the same Base44
-app, or the first `clientId`'s returns stop working.
+app, or the first `clientId`'s returns stop working. The app is created with `origin: "base44-app"`,
+the name of this flow on the OAuth app; `origin` is set at creation only, so an OAuth app created
+by hand carries the same value in its create call.
 
 ```js
 // Register BOTH of this app's own URLs — its preview URL and its published URL — so returns work

package/skills/wix-base44-connector/scripts/utils.cjs

@@ -432,7 +432,10 @@ async function installApp(appDefId, siteId, token) {
 // return needs. Idempotent by name — a site reached by the "connect an existing site" flow
 // has none, and creating a second one for the same app strands the first app's returns.
 // Redirect lists are merged, never replaced: an app that already serves a custom domain
-// keeps it when a preview URL is added.
+// keeps it when a preview URL is added. `origin` names the flow that created the app; it is
+// written once, at creation, and an update leaves it as it is.
+const OAUTH_APP_ORIGIN = "base44-app";
+
 async function ensureOAuthApp(token, { name, redirectUris = [], redirectDomains = [] }) {
   const { oAuthApps = [] } = await post(
     "https://www.wixapis.com/oauth-app/v1/oauth-apps/query", { query: {} }, token);
@@ -440,7 +443,7 @@ async function ensureOAuthApp(token, { name, redirectUris = [], redirectDomains
   const merge = (a = [], b = []) => [...new Set([...a, ...b])];
   if (!existing) {
     const { oAuthApp } = await post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
-      oAuthApp: { name, allowedRedirectUris: redirectUris, allowedRedirectDomains: redirectDomains },
+      oAuthApp: { name, allowedRedirectUris: redirectUris, allowedRedirectDomains: redirectDomains, origin: OAUTH_APP_ORIGIN },
     }, token);
     return { clientId: oAuthApp.id, created: true, oAuthApp };
   }

package/skills/wix-headless-kit/SKILL.md

@@ -294,7 +294,10 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    `https://manage.wix.com/dashboard/<siteId>` (the `siteId` of the `ready_for_brand_layer`
    event: on a migration preview that is the migrated site's dashboard, the release URL is the
    preview's, the original site is unchanged, and completing the migration is the user's next
-   step in the Wix CLI once they approve — say all three). When the site takes money through
+   step in the Wix CLI once they approve — say all three). Tell the user how to put their own
+   domain on the site, per the `wix-manage` recipe `references/domains/domain-search-purchase-and-connect.md`
+   (installed beside this skill, else `https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md`):
+   bought through Wix, or one they already own. When the site takes money through
    hosted checkout (a cart, a paid booking or rental, tickets, plans, donations) and nothing says
    payments are already set up, say what a visitor meets at checkout until they are — "We
    can't accept online payments. Contact us for help with your order." — and hand the two links

package/skills/wix-headless-kit/guides/api-run.md

@@ -76,7 +76,7 @@ A brief that needs no solution (a game, a landing page, a tool) is a run of two
 ## 2. The site
 
 The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
-with `origin: agent-<your-id>`, a name, and the solutions to install as `seedOptions`. The recipe
+with `origin: "drop"`, a name, and the solutions to install as `seedOptions`. The recipe
 is `{MANAGE}/references/sites/create-headless-site.md`; it returns the `metaSiteId` and the
 site's OAuth client `appId`. Do not create a site any other way: a project from Create Project or
 a template is neither headless nor publishable, and a later run with a machine cannot attach to it.
@@ -95,9 +95,10 @@ Restaurants, Donations, FAQ), goes on with the Apps Installer:
 
 `seed-{solution}.mjs` is a sequence of REST calls, and `SEED.md` is its contract: the plan shape
 (what to create, how many, which images), the order the entities need, the request bodies and the
-traps the script encodes. Read `SEED.md` before the first create: it maps the brief's words to the
-fields, and the script's builder functions turn those fields into each request, so the bodies you
-send are the ones they build. A call `SEED.md` only names is made through `{MANAGE}`'s recipe for
+traps the script encodes. Write the seed as your own `ExecuteWixAPI` script, its calls made on the
+new site: `wix.request({ scope: "site", siteId: <the metaSiteId>, … })`. Read `SEED.md` before
+the first create: it maps the brief's words to the fields. Build each request body in your script the
+way the script's builder functions do. A call `SEED.md` only names is made through `{MANAGE}`'s recipe for
 it. Keep the script's rules: create, never delete, and report what the site already held. The closing
 names entities you drafted as placeholders.
 
@@ -142,25 +143,20 @@ takes the complete file set in one call and a response has a hard size limit; th
 later" section downloads what the site serves, so a later drop adds files to a live set without
 resending what is already there.
 
-**When it cannot**, or when its output would all have to be written out by hand, a page that loads
-the Wix SDK from a package CDN and talks to the site as a visitor. One file per call, a few hundred lines, written in full inside that call: a response has a
+**When it cannot**, or when its output would all have to be written out by hand, a page that talks
+to the site as a visitor over plain `fetch`. One file per call, a few hundred lines, written in full inside that call: a response has a
 hard size limit, and a call that carries the whole frontend at once exceeds it. A second file joins
 the first the recipe's way, "Change it later": the same call downloads the live set and drops the
 union. The
-SDK comes from a pinned package URL, `https://esm.sh/@wix/sdk@{version}` and the solution's package
-(`@wix/bookings`, `@wix/stores`, `@wix/blog`, …); the client is
-`createClient({ modules: { … }, auth: OAuthStrategy({ clientId }) })` with the `appId` the provision
-call returned, and the SDK mints and refreshes the visitor token itself. Markup, a render function
+page calls the Wix REST API with `fetch` and mints the visitor token itself with the `appId` the
+provision call returned, as `{TEMPLATES}/shared/rest/client.ts` does. Markup, a render function
 per state, the event handlers: that is what you write. Keep what the page shows to what the site
 holds; nothing invented, as in SKILL.md step 4.
 
-**The calls**, on that second path, take their shape from the kit's own transport for the solution,
-`{TEMPLATES}/{solution}/app/wix/{solution}/*.ts` (`services.ts`, `booking.ts`, `catalog.ts`, …,
-with `{TEMPLATES}/shared/app/wix/sdk.ts` for the client wiring): those files call the same SDK
-modules the page imports, and they are verified. Copy the form of the call, not the file. A page
-that talks to Wix over plain `fetch`, with no SDK, takes them from the REST twins instead:
+**The calls**, on that second path, take their shape from the kit's REST twins for the solution:
 `{TEMPLATES}/shared/rest/client.ts` (the visitor token and the request) and
 `{TEMPLATES}/{solution}/rest/*.ts` (the calls), each importing its helpers by their real paths.
+They are verified. Copy the form of the call, not the file.
 The cores,
 `{TEMPLATES}/{solution}/app/wix/{solution}/*-core.ts`, hold the rules the page needs and nothing else
 does: which fields to read, how a price or a duration is formatted, which slot is bookable, how an
@@ -170,11 +166,9 @@ a translatable object, a quantity a nested one). What you write is the markup, t
 the cores return, and the event handlers.
 
 **A call those files don't cover** is confirmed before it is written, the way `{DOCS}` describes:
-the method's SDK page, and when the page and the package disagree, the package's own type
-declarations (the `@wix/auto_sdk_{solution}_<module>` package the solution package depends on,
-its `index.d.ts`) are the truth. Two shapes that recur, as examples of what the types settle and
-the kit's files already encode: SDK query methods return a query builder finished with `.find()`;
-and an entity's id arrives as `_id` on some objects and `id` on others (the kit reads both,
+the method's REST page, and its schema (SearchWixAPISpec on the method's docs URL) for the exact
+request and response. A shape that recurs, as an example of what the kit's files already encode:
+an entity's id arrives as `_id` on some objects and `id` on others (the kit reads both,
 `rawId`). Dates travel as local wall-clock strings in the business time zone.
 
 **The check**, before every upload: a page cannot be opened here, so a wrong shape fails silently in

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.31.2"
+    "ref": "v1.33.0"
   }
 }

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "REST recipes to configure and manage a Wix site's business solutions — stores, bookings, payments, CMS, and more. Open the matching recipe for the exact endpoint, method, and payload before calling — never guess a Wix API, never write Wix dashboard URL from memory. Routes to: automations, stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, custom-apps, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, google-business-profile, analytics, accessibility, seo, dashboard-navigation."
+description: "REST recipes to configure and manage a Wix site's business solutions — stores, bookings, payments, CMS, and more. Open the matching recipe for the exact endpoint, method, and payload before calling — never guess a Wix API, never write Wix dashboard URL from memory. Routes to: automations, stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, custom-apps, pricing-plans, restaurants, ricos rich-content, sites, collaborators, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, google-business-profile, analytics, accessibility, seo, dashboard-navigation."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -47,7 +47,7 @@ Lists all apps installed on a site using Apps Installer API. Useful for verifyin
 Read and update SEO titles and tags at the right level. For "change my site's SEO title", clarify homepage, specific page, or page-type pattern before discovery or writes; site-level tags accept meta tags only, never titles. Discover item IDs and pattern variables, read before every full-replace write, and report resolved tags with their sources.
 
 ### [Manage URL Redirects on a Wix Site](references/seo/manage-url-redirects.md)
-"Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, batches of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
+"Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, bulk creates of up to 100 and bulk deletes of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
 
 ### [Generate and Read a Wix Site's Content Plan](references/seo/manage-content-plan.md)
 Generate an SEO content plan and read its blog post topics, or troubleshoot an existing content plan flow stuck at KEYWORD_RESEARCH while polling GetContentPlanFlow. Use this recipe for both generation and stalled-flow questions: it explains the intentional pause, the Create Content Plan release request, missing flow IDs, and the exact public API paths and response fields.
@@ -252,8 +252,11 @@ Routes discounts, coupons, sales and bundles to promotion recipes, and visual pr
 ### [Update Form](references/forms/update-form.md)
 "Changes a Wix form that already exists, with Form Schemas v4 `PATCH` — add a field to my form, add a dropdown, make a field required or optional, rename a label, reorder or retire a question. Covers reading the form back for its `revision` (and the required `namespace` query parameter), the whole-form body that a `PATCH` needs, the wholesale `formFields` replace that silently soft-deletes anything you omit, changing a field's component type in place, retiring a field that already has submissions, and the read-back that proves what was stored. Use whenever the form exists and the request changes what it collects; use Create Form when there is no form yet."
 
+### [Read Forms and Submissions](references/forms/read-forms-and-submissions.md)
+"Reads a site's Wix forms and the submissions visitors sent to them — what forms do I have, find a form by name, show the latest submissions, who filled in my contact form, how many submissions did I get last week, submissions from one contact, unread submissions. Covers finding the form's namespace instead of guessing it, where that namespace goes on each read, the Form Schemas and Form Submissions endpoints (and the look-alike URLs that 404), forms hidden from a default listing, the closed list of submission fields you can filter and sort by, date ranges, cursor paging, totals per form, and reading answers by field. Read-only; changing a form is Update Form, building one is Create Form."
+
 ### [Forms Dashboard Navigation](references/forms/forms-dashboard-navigation.md)
-"Builds direct links to Wix Forms dashboard pages on manage.wix.com. The paths are not guessable and appear in no API reference, so take them from here: under `https://manage.wix.com/dashboard/{metaSiteId}/`, the forms list is `wix-forms`, a form's builder is `wix-forms/form/{formId}`, and that form's submissions are `wix-forms/form/{formId}/submissions` — there is no site-wide submissions page, and nothing lives under `contacts/forms`, `forms`, `form-builder` or `wix-forms-and-payments` (the legacy app). Also standalone forms, and each Forms entity paired with its read API so you can fetch one and hand back a 'view it in your dashboard' link."
+"Builds direct links to Wix Forms dashboard pages on manage.wix.com. The paths are not guessable and appear in no API reference, so take them from here: under `https://manage.wix.com/dashboard/{metaSiteId}/`, the forms list is `wix-forms`, a form's builder is `wix-forms/form/{formId}`, and that form's submissions are `wix-forms/form/{formId}/submissions` — there is no site-wide submissions page, and nothing lives under `contacts/forms`, `forms`, `form-builder` or `wix-forms-and-payments` (the legacy app). Also standalone forms, and the dashboard link for each Forms entity; reading forms and submissions is Read Forms and Submissions."
 
 ---
 
@@ -390,13 +393,20 @@ Authoritative recipe for hand-authoring valid Ricos rich-content JSON (the richC
 
 ---
 
+## Collaborators
+
+### [Manage Site Collaborators](references/collaborators/manage-site-collaborators.md)
+Manages who has access to a Wix site as a collaborator (contributor) — finds the site's current collaborators, invites someone, removes a collaborator, and resends or revokes a pending collaborator invite. Use when the user wants to give someone access to the site, take it away, or follow up on an invitation that has not been accepted.
+
+---
+
 ## Sites
 
 ### [Create Site from Template](references/sites/create-site-from-template.md)
 Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, and publishing. Not for headless sites.
 
 ### [Create Headless Site](references/sites/create-headless-site.md)
-Creates a Wix Headless website: a site in the user's Wix account whose frontend is files uploaded to Wix hosting, with the Wix business backend behind it through APIs. Creating, uploading, updating and connecting a backend are one flow, in Upload a Website or HTML Files.
+Creates a Wix Headless website: a site in the user's Wix account whose frontend is files uploaded to Wix hosting, with the Wix business backend behind it through APIs. The site is created and its pages put live by Upload a Website or HTML Files; a Wix Business Solution (a store, blog, bookings and more) is then integrated into it by the Wix Headless kit, from its cold start.
 
 ### [Manage OAuth Apps](references/sites/manage-oauth-apps.md)
 Create, read, update, and query OAuth apps for a Wix headless site. Each OAuth app's id is the client_id a frontend uses to mint anonymous visitor tokens and call Wix APIs.
@@ -417,7 +427,7 @@ Drive the Wix Site Import agent to migrate an existing store or site from anothe
 "Builds direct links to the account-level sites pages on manage.wix.com — the My Sites list (all sites in the account) and each site's own dashboard. Pairs the site list with the Query Sites read API. 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."
 
 ### [Upload a Website or HTML Files](references/sites/upload-static-site.md)
-Create and update a Wix Headless website by uploading its files — an index.html, a static build, a zip exported from an AI builder or any other tool, or pages you write for the user — as a live site in the user's Wix account. Covers every route: uploading with the user's identity (curl with a Wix CLI token, or the Wix MCP), publishing anonymously with a save link when you don't hold it, and the Wix Headless drop page; then updating the same site and URL, and connecting a Wix backend (stores, bookings, forms) through the headless skill. Use when the user wants to upload, publish, deploy or host HTML/CSS/JS as a new Wix site, their own or written for them, or to change a site published this way. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+Publish HTML, CSS, JavaScript or a static build as a Wix Headless website; inspect its deployed files and edit them on the same site and URL. Covers file and ZIP uploads, selective additions, replacements and deletions while preserving other files, full-site replacement, authenticated and anonymous publishing, verification, and connecting a Wix business backend. Use for files the user supplies or pages you create for them. Not for migrating a live site from another platform by URL or CSV (use Site Import), embedding code in an editor-built Wix site, or uploading assets to Media Manager.
 
 ---
 
@@ -454,16 +464,28 @@ 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)
-Discover installed automation triggers and actions and inspect an automation’s current active status without changing site data.
+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.
 
 <details>
 <summary>Internal skills (loaded on demand by Build and Manage Wix Automations — do NOT use directly)</summary>
 
 - [Automations API Catalog](references/automations/api-catalog.md)
-  Discover installed automation triggers and actions and inspect their schemas through site-scoped public catalog APIs.
+  Discover site-specific triggers and actions, authenticate public Automation API calls, and choose the API for validation, persistence or catalog lookups.
+
+- [Automations Graph and Data Model](references/automations/automation-model.md)
+  Assemble builder-editable automation graphs with valid node relationships, namespaces and ancestor data access.
+
+- [Automations Trigger Configuration](references/automations/triggers.md)
+  Select and configure automation triggers, trigger filters and event payload schemas using the site catalog.
+
+- [Automations Action Configuration](references/automations/actions.md)
+  Configure app-defined automation actions from their input schemas and preserve supported existing action mappings.
+
+- [Automations Mapping Expressions](references/automations/bracket-expressions.md)
+  Write builder-compatible automation mapping expressions, literals and data references.
 
 - [Automations Activation Status](references/automations/activation-status.md)
-  Read an automation’s current ACTIVE or INACTIVE status and distinguish it from historical run outcomes.
+  Read an automation’s current ACTIVE or INACTIVE status, and activate or deactivate it when the user asks.
 
 </details>
 

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

@@ -0,0 +1,134 @@
+---
+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).
+
+# App-Defined Actions — Discovery, Schemas, Input Mapping
+
+**TL;DR**
+
+- 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)).
+- Before accepting any action, prove its side effect and its recipient (§6).
+
+---
+
+## 1. APIs used here
+
+Site-scoped (`wix-site-id` header), SDK module `actionCatalog`: Resolve Actions · Get Runtime Action (the version this site runs — use it) · Get Action Dynamic Input / Output Schema (+ bulk output). Paths and request shapes: [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §4.
+
+## 2. Finding the right action
+
+1. Resolve Actions with small pages (`{"query": {"paging": {"limit": 25}}}`); filter by `appId` when known, otherwise search locally over `displayName`, `description`, `actionKey` with a keyword ladder (phrase → domain verb/noun → synonyms).
+2. Read the `description`. A name like "Add a coupon" or "Get a …" can be a value-producing step that notifies nobody.
+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).
+
+### Selection rules
+
+- Prefer a normal built-in action over any AI action.
+- **Direct action beats communication**: "apply the change" is the change, not an email about it — unless messaging was asked for.
+- **Delivery beats retrieval**: "send the customer a coupon" needs a delivery step. A staging action alone is incomplete; its output must be consumed by a delivery step on the same path.
+- Replacing an unsupported external integration: keep the channel (chat stays chat-like).
+- AI ladder — first that fits: (1) **Delegate to Aria** `ai_assistants-delegate-to-assistant`: autonomous agent, output NOT used downstream (exposes only `summary`); (2) **Custom agent** `ai_custom_agent_bm-delegate_to_agent`: autonomous agent whose output IS used downstream; (3) **Generate or analyze text** `wix_automations-llm_call`: pure LLM over data already in the payload; no tools, no internet. "LLM step" → (3). When later steps need several structured fields, use (3) with an override output schema — not a single-string text action.
+- Ask the user to choose between overlapping actions only when the difference is user-facing and context doesn't decide it.
+
+## 3. Reading the action
+
+- `inputSchema` — JSON Schema of the mapping. `required` = must map. `oneOf`/`const` = enum. `format`, `wixCustomType`, `identityType` as in [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §3.
+- `interfaceConfiguration.type` — `GENERIC` → the builder renders a form from `inputSchema` + `genericOptions.uiSchema` (rules in §5.2). `WIDGET_COMPONENT` → the app's own configuration widget, which you can't see (below).
+- `interfaceConfiguration.genericOptions.uiSchema` — per-field UI hints (below). It cannot add fields.
+- `outputSchema` — fields downstream steps read as `var("<namespace>.<field>")`. Empty and no dynamic output → later steps must not reference its namespace.
+- `implementedMethods` — `validateConfiguration` (the app validates your mapping on Validate Automation), `getQuotaInfo`. It does **not** tell you about dynamic schemas — decide by `updateSchemaOnChange` and by calling the dynamic-output API.
+
+**`WIDGET_COMPONENT` actions.** The widget owns the mapping; the builder's form rules don't apply to it. In these guides an *opaque widget* is a `WIDGET_COMPONENT` action whose `inputSchema` does not fully describe the requested configuration. If `inputSchema` fully describes what the user asked for (e.g. `addLabelsToContact`: `contactId` + `labelKeys`), hand-author it (§5.2) and tell the user to review the step; otherwise tell the user this step can’t be configured through the API here and that they can set it up in the automations builder. If the widget can't load (its app is uninstalled), the builder shows an "app not installed" state with a Replace button instead of the settings.
+
+Conditional fields (`if`/`then`/`dependencies`, e.g. a due date shown only when "add a due date" is true): set the toggle and the dependent field together, or leave both out.
+
+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: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.
+
+## 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)).
+
+## 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.
+
+**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.
+
+### 5.2 Hand-authored mapping
+
+MUST (builder renderability — the `GENERIC` form drops, rewrites or flags anything else):
+
+- Keys: only properties of the current (merged dynamic) input schema. The form drops unknown keys on the first edit.
+- Values: the schema's type — string→string, number/integer→number, boolean→boolean, array→array, object→object field by field (e.g. MONEY `{"value": "…", "currency": "…"}`).
+- Every `required` field present. An action with visible fields and a missing/`null` `inputMapping` is flagged "missing required info" and its panel can't be applied.
+- 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)).
+- `{{…}}` 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.
+
+Value kinds:
+
+```json
+{
+  "subject": "Welcome, {{var(\"contact.name.first\")}}!",
+  "priority": "HIGH",
+  "notifyCustomer": true,
+  "amount": {
+    "value": "{{var(\"order.total.value\")}}",
+    "currency": "{{var(\"order.total.currency\")}}"
+  },
+  "contactId": "{{var(\"contactId\")}}",
+  "labelKeys": ["<label-key-1>"],
+  "note": "Order {{var(\"order_number\")}} from {{var(\"createTask-1.taskId\")}}"
+}
+```
+
+Trigger fields have no prefix; action outputs use the step's `namespace` (e.g. `createTask-1.taskId`); set-variables use `setVariable.<key>`.
+
+Optional inputs with no `default` (e.g. `isDueDate`, `onlyWhenAvailable`): omit them unless the request needs them. A deprecated defaulted input (e.g. `labelIds: []` on add-label) may be omitted.
+
+Process: (1) fetch the effective schema (§4) before you write a mapping or any script that saves one — never guess an action's field names → (2) classify required vs optional; map optional fields only with a real source → (3) source each required field from payload, upstream outputs or the user; ask for user-specific content (text, recipient, which entity) → (4) build → (5) self-check against the list above → (6) Validate Automation.
+
+### 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.
+
+## 6. Side-effect and recipient review
+
+This section owns the semantic review (you, not code) required for every action before acceptance. Confirm from its catalog entry and effective schemas:
+
+- **Verb**: it performs what was asked (assign/add/send/create/update/delete). A read-only "get" action can't satisfy a mutation; sending a message about a change is not the change.
+- **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.
+  - 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.
+
+Under-required schemas: `send-message` requires only `contactId`/`visitorId` (anyOf), not the text. Always map the message too — a required-fields-only mapping ships an empty action.
+
+## 7. Common failure modes
+
+Missing required field or content-free required-only mapping · fabricated user values instead of asking · type/format mismatch, free text in an enum, a name in an id field · `var()` to a path absent from the aggregated schema (or from an unfetched dynamic schema) · formula in a static field or an unknown function · wrong verb or recipient · a single-value field filled from an array · unmapped defaults / identity fields / missing `{}` (the builder rewrites the step on first open).

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

@@ -1,52 +1,68 @@
 ---
 name: "Automations Activation Status"
-description: "Read an automation’s current ACTIVE or INACTIVE status and distinguish it from historical run outcomes."
+description: "Read an automation’s current ACTIVE or INACTIVE status, and activate or deactivate it when the user asks."
 ---
 
-# Inspect activation status
-
-An automation's current state is `configuration.status`: ACTIVE is eligible for new trigger
-events; INACTIVE is not. Neither value proves that a historical run succeeded or that a
-pending activation has stopped.
-
-1. Resolve the requested name with one Query Automations call filtered by that exact name
-   (below); don't page through other automations. If the ID is already supplied, go to Get.
-   If several match, open your answer by listing each match's full returned ID and asking
-   which one the user means; don't report a single status. If none match, say so and ask the
-   user to check the name or site; never guess an ID.
-2. Get the matching returned ID and read `configuration.status`.
-3. Answer briefly and completely in one reply. Start with the automation's exact name, its
-   returned ID and ACTIVE/INACTIVE from that response, then say what it means for new trigger
-   events. If the user asks whether the status says anything about past runs, answer it
-   directly in the next sentence: status does not show whether past runs succeeded; they are
-   visible in the automation's activity view in the site dashboard.
-4. If Get returns not found, do not state a status. Open with: the automation wasn't found on
-   this site, so its status can't be determined, and ask the user to confirm the site and the
-   automation ID. This question is required. Then give the possible causes below.
-
-Use an authorized site-scoped client with Set Up Automations permission. REST calls use
-`Authorization: <token>`. An API key also needs `wix-site-id: <metaSiteId>`; do not combine it
-with `wix-account-id`. Never print credentials.
-
-`POST https://www.wixapis.com/automations-service/v2/automations/query`
-
-```json
-{"query":{"filter":{"name":"<automation name>"},"cursorPaging":{"limit":25}}}
-```
-
-Read `automations[]` and `pagingMetadata.cursors.next`; continue pages if needed. Retain the
-returned `id` and exact name. Then:
-
-`GET https://www.wixapis.com/automations-service/v2/automations/<automationId>`
-
-Read `automation.configuration.status` from the Get response. Never infer status from the
-name or a previous mutation. Do not validate, change configuration, toggle status or test-run
-an automation to answer this read-only request.
-
-Not-found causes (step 4): unpublished builder drafts do not appear
-through this API, but a 404 can also mean deletion or a changed ID after overriding a
-preinstalled automation. When the user's history supports an unpublished builder draft as the
-cause, ask the owner to publish or discard it rather than reproducing its edits.
-
-Official contracts: [Query Automations](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/query-automations),
-[Get Automation](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/get-automation).
+> **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` —
+`ACTIVE` (eligible for new trigger events) or `INACTIVE` (not eligible for new trigger events).
+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;
+  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
+  so and ask the user to check the name or site; never guess an ID.
+- **Builder drafts are invisible to you**: if the user says "it doesn't show my latest changes",
+  tell them to publish (or discard) in the builder first — don't reproduce their edits.
+- **NOT_FOUND is ambiguous.** Open the answer by saying the status can't be determined and
+  asking the user to confirm the site and the automation ID; then give the possible causes. A never-published builder draft is absent
+  from Get/Query, but deletion and a replaced preinstalled id can also explain a 404. The first
+  update of a preinstalled automation can create an override with a new id; use the mutation's
+  returned id, or Query to find the current automation and confirm its identity. When the
+  user's history supports an unpublished builder draft as the cause, ask the owner to publish or
+  discard it rather than reproducing its edits.
+
+**Calls** (auth as in [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §1). A status question needs only Query and Get — no catalogs, Validate or writes.
+
+- Find by name: `POST https://www.wixapis.com/automations-service/v2/automations/query` with
+  `{"query":{"filter":{"name":"<automation name>"},"cursorPaging":{"limit":25}}}` → `automations[]`
+  with each `id` and exact `name`. If the user supplied the ID, skip this.
+- Read: `GET https://www.wixapis.com/automations-service/v2/automations/<automationId>` → `automation.configuration.status`. Add
+  `?fields=OVERRIDE_SCHEMA` before activating or deactivating.
+- Activate / deactivate: `PATCH https://www.wixapis.com/automations-service/v2/automations/<automationId>` with
+  `{"automation": <the object exactly as fetched, with only configuration.status changed>}` — it
+  carries `id`, the current `revision`, `origin` and any `settings` the Get returned.
+
+**Activate** (only when the user asks):
+
+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)).
+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.
+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
+   its `revision`. Nothing else changes.
+6. Capture the returned id (a preinstalled override can change it), Get that id again with
+   override schemas, and confirm `configuration.status` is `ACTIVE` and all other requested
+   content is unchanged. Report "active" only then.
+
+**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
+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.
+
+**Revision conflicts** (someone published from the builder meanwhile): re-Get and retry once;
+if the fresh object differs in ways that matter, tell the user instead of overwriting.