@wix/agent-skills 1.31.2 → 1.32.0

package/skills/wix-manage/references/automations/bracket-expressions.md

@@ -0,0 +1,132 @@
+---
+name: "Automations Mapping Expressions"
+description: "Write builder-compatible automation mapping expressions, literals and data references."
+---
+
+> **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).
+
+# Bracket Expressions (Formulas) — `{{…}}`
+
+**TL;DR**
+
+- `{{expression}}`; fields via `var("dotted.path")` (double quotes, one argument); arguments separated by `;`; string literals in double quotes and URI-encoded.
+- In formula fields (action inputs, set-variable values, delay due dates) use ONLY the builder function list in §2. Conditions and trigger filters have their own, stricter vocabularies — Automations Conditions (not yet published), [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §4.2.
+- The builder type-checks every argument and the arity (§2): `eq`/`gt`/`gte`/`lt`/`lte` take NUMBERS only (strings → `stringEq`, dates → `date*`); `if()`'s first argument is boolean. There are no operators.
+- No array element access in any form. Project with `arrayMap(array;"path")`, aggregate with `array*`. A single-value field can never be filled from an array — ask the user which item.
+- Only data from the step's aggregated schema (trigger + ancestors) is in scope ([Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model) §4).
+
+---
+
+## 1. Syntax
+
+| Form                                                | Example                                                                      |
+| --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Literal                                             | `{{"text"}}`, `{{10}}`, `{{true}}`, `{{["a","b"]}}`                          |
+| Variable                                            | `{{var("contact.name.first")}}`                                              |
+| Function                                            | `{{concat(var("a");" - ";var("b"))}}`                                        |
+| Text with embedded expressions (string fields only) | `Hi {{var("contact.name.first")}}, your total is {{toString(var("total"))}}` |
+
+MUST:
+
+- Every field access is `var("path")` with ONE argument — `{{fieldName}}` is not supported.
+- Double quotes only (`var('x')` is an unknown variable to the builder). In JSON escape them: `"{{var(\"contact.email\")}}"`.
+- `;` between arguments, no leading/trailing/double `;`, balanced parentheses. No whitespace outside string literals — `{{ concat(…` or `sum( 1;2)` is unreadable to the builder.
+- Numbers: plain decimal literals (`5`, `-3`, `12.5`). Never `0.5`, `.5`, `-0.25`, `05` or `1e3` — the builder's parser rejects them (conditions, filters, delays and rate limits stop loading). Write `divide(1;2)` instead. Percentages follow the same rule: 10% of `x` is `divide(x;10)` and 15% is `divide(multiply(x;15);100)`, never `multiply(x;0.1)`.
+- Path segments may contain hyphens (`var("triggered-emails-1.messageId")`); a space inside a segment is invalid.
+- **URI-encode every string literal inside `{{…}}`** exactly as `encodeURIComponent` does — this is how the builder's panels and the platform store them: `"a@b.com"` → `"a%40b.com"`, `"50%"` → `"50%25"`, `"New York"` → `"New%20York"`, `"&"` → `"%26"`. Letters, digits and `- _ . ! ~ * ' ( )` stay as they are, so uuids and `arrayMap` paths are unchanged. Do NOT encode `var("…")` paths (except in trigger filters, where the filter panel encodes the path too — [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration)) or text outside `{{…}}`, nor a date-time literal in a formula field (§2). Decode literals when you read an existing automation. Action formula fields display literals as stored, so in string fields keep fixed text outside `{{…}}` (`Hi {{var("contact.name.first")}}, welcome!`) rather than in `concat("…")`.
+
+Prefix rules: trigger fields have no prefix; action outputs `"<namespace>.<field>"` (namespace = the step's `namespace`, e.g. `createTask-1`); set variables `"setVariable.<key>"`; identity enrichment `"contact.…"` / `"member.…"`. `siteInfo.*` is not available — don't reference it.
+
+## 2. Functions the builder renders in formula fields (complete list)
+
+- **Math**: `sum(n;n;…)` · `subtract(n;n)` · `multiply(n;n;…)` · `divide(n;n)` · `average(n;…)` · `min(n;…)` · `max(n;…)` · `median(n;…)` · `mod(n;n)` · `round(n;decimals)` · `abs(n)` → number · `eq(n;n)` · `gt(n;n)` · `gte(n;n)` · `lt(n;n)` · `lte(n;n)` → boolean (numbers only)
+- **Array**: `arraySize(a)` · `arraySum(a)` · `arrayMultiply(a)` · `arrayAverage(a)` · `arrayMin(a)` · `arrayMax(a)` · `arrayMedian(a)` → number · `arrayMap(a;"item.path")` → array
+- **Text**: `concat(s;s;…)` · `substring(s;start;length)` (0-based) · `lower(s)` · `upper(s)` → string · `stringLen(s)` → number · `stringEq(a;b)` · `stringHasSubString(s;sub)` · `startsWith(s;prefix)` · `endsWith(s;suffix)` · `isEmptyString(s)` → boolean
+- **Date**: `hour(dt)` · `minute(dt)` · `year(d)` · `month(d)` · `day(d)` → number · `weekDay(d)` → lowercase day name · `dateEq/dateBefore/dateAfter(d;d)` (calendar date) · `dateTimeEq/dateTimeBefore/dateTimeAfter(dt;dt)` → boolean · `addToDate(d;years;months;days)` · `subtractFromDate(d;years;months;days)` → date-time · `now()` → date-time string
+- **Format**: `toString(v)` → string · `toNumber(v)` → number
+- **Logic**: `if(bool;then;else)` · `and(b;b;…)` · `or(b;b;…)` · `not(b)` · `isEmpty(v)` (any value, incl. arrays) → boolean (`if` → its branches' value)
+
+Arity (write exactly these counts; the builder flags missing and extra arguments for fixed-arity functions): `var`, `not`, `toString`, `toNumber`, `upper`, `lower`, `stringLen`, `abs`, `isEmptyString`, `isEmpty`, every `array*` aggregate = 1 · comparisons, `round`, `subtract`/`divide`/`mod`, `arrayMap` = 2 · `if`, `substring` = 3 (always pass the length) · `addToDate`/`subtractFromDate` = 4 · `now` = 0 · `and`/`or`/`concat`/`sum`/`multiply` ≥ 2 · `min`/`max`/`average`/`median` ≥ 1.
+
+Argument types the builder enforces (convert with `toString()`/`toNumber()`):
+
+| Parameter                                                                     | Accepts                                                                                                                                                           |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| number (math, comparisons, `substring` offsets, date offsets)                 | number literal, number/integer var, number-returning function; wrap a string `format: number` var (money `value`s) in `toNumber()` — the platform rejects it bare |
+| string (text functions, `concat`)                                             | string literal/var/function — never a number or boolean (wrap in `toString()`)                                                                                    |
+| boolean (`if` arg 1, `and`, `or`, `not`)                                      | comparison, boolean var, `isEmpty`/`isEmptyString`/`startsWith`/…                                                                                                 |
+| date (`year`, `month`, `day`, `weekDay`, `dateEq/Before/After`, `addToDate`…) | a var whose schema has `format: date` or `date-time`, a `"YYYY-MM-DD"` literal, or a function (`now()`, `addToDate(…)`)                                           |
+| date-time (`hour`, `minute`, `dateTimeEq/Before/After`)                       | a var with `format: date-time`, a function, or an ISO date-time literal — a `format: date` var or plain-string var is rejected                                    |
+| array (`array*` functions, `isEmpty`)                                         | array var or `arrayMap(…)`; no other function takes an array argument                                                                                             |
+
+An encoded date-time literal (`"2026-12-25T10%3A00%3A00Z"`) is not recognized as a date in a formula field — pass a `"YYYY-MM-DD"` literal or a function, or make the whole field a plain ISO value (§4). This exception is for formula fields only: in a CONDITION the panel itself writes date-time literals encoded and reads both forms (§2 of Automations Conditions (not yet published)).
+
+Semantics: `stringEq` and `stringHasSubString` are case-insensitive (normalize with `lower()` if it matters). Booleans: use the value directly (`if(var("isVip");…)`, `not(var("isVip"))`), never `eq(var("isVip");true)`.
+
+**Never use in a formula field** (the builder flags them as unknown functions):
+`toEpoch`, `arrayFilter`, `hasSubstring`, `textWithExpressions`, `contains`, `arraySome`, `arrayEvery`, `arrayIncludesAnyOf/AllOf/Only`, `stringContains`, `numberContains`, `boolEq`, `numberEq/numberGt/numberGte/numberLt/numberLte`. (Several of these ARE the condition vocabulary — §2 of Automations Conditions (not yet published) — and `contains`/`arraySome` the trigger-filter vocabulary.)
+
+**Do not exist** (never guess): `replace`, `replaceAll`, `trim`, `split`, `join`, `indexOf`, regex/`match`, `ceil`, `floor`, `parseInt`, `parseFloat`, `random`, `filter`, `reduce`, `sort`, `switch`, loops, `try/catch`, `coalesce`, `formatDate`, `formatNumber`, `formatCurrency`, `titleCase`, `add`, `addDays`, `equals`.
+
+## 3. `if()` needs a boolean first argument
+
+Valid first arguments: a comparison (`eq`, `gt`, `stringEq`, `dateBefore`, `startsWith`, …), a genuinely boolean field, or `and`/`or`/`not`/`isEmptyString`/`isEmpty`.
+
+In number and boolean target fields BOTH branches must return exactly the field's type — a number literal/var/function for a number field. A nested `if` as a branch counts as "any" and is flagged there: wrap it (`toNumber(if(…))`) or, for booleans, use `and`/`or`. Nested `if` is fine in string fields.
+
+- ✅ `{{if(stringEq(var("status");"active");"Active";"Inactive")}}`
+- ✅ fallback when the value is missing or empty: `{{if(or(isEmpty(var("contact.name.first"));isEmptyString(var("contact.name.first")));"there";var("contact.name.first"))}}`
+- ❌ `{{if(var("status");…)}}` when `status` is a string · ❌ `{{if("active";…)}}`
+
+## 4. Field-type rules (what the builder accepts per target field)
+
+- **string** — Plain text, one expression, or text mixed with any number of `{{…}}`; no expression may return an array.
+- **number / integer (incl. string `format: number`)** — Exactly ONE `{{…}}` covering the whole value, returning a number — or a plain number literal. No surrounding text.
+- **boolean** — Exactly ONE `{{…}}` returning boolean — or `true`/`false`.
+- **date / date-time** — A plain ISO literal without `{{}}` (`2026-12-25T16:00:00Z`), or ONE expression: a function (`now()`, `addToDate(…)`) or a var. For a `date-time` field the var must be `format: date-time` — wrap a `format: date` var as `addToDate(var("d");0;0;0)`.
+- **array / object** — A literal array/object built field by field, or one `{{var("…")}}` of the same shape.
+- **field without `dynamicValuesOptions.enabled` in the UI schema** — Literal only — no `{{…}}` ([Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration) §3).
+
+A `strict` dynamic field requires the exact return type/format. `skipActionExpression` is `"{{true}}"` or absent.
+
+## 5. Arrays — hard limits
+
+- **No element access**: `var("items[0]")`, `var("items.0.name")`, `var("items[0].name")` are all invalid. Don't invent `firstItem`/`items.id` helper paths either.
+- **Projection**: `{{arrayMap(var("order.items");"product.name")}}` — second argument is a quoted literal path (never `$_` or an expression).
+- **Aggregates**: `{{arraySize(var("lineItems"))}}`, `{{arraySum(arrayMap(var("lineItems");"totalPrice.value"))}}`. Never `arraySum(var("items.price"))` — a path cannot cross an array boundary.
+- **No per-element arithmetic** (price × quantity): sum a per-line total field if one exists, else say it is not derivable.
+- **No lists as text**: no `join`; an `arrayMap` result can't go into `concat` or a string field.
+- **Single-value field from an array → impossible.** Ask the user which item or use a user-given value; don't retry array-shaped variants.
+- Empty arrays make `arraySum/arrayMin/arrayMax/arrayMedian/arrayMultiply` fail at runtime.
+- Membership tests (`does the order contain X`) belong in a condition (§3 of Automations Conditions (not yet published)) or, for complex logic, a code condition.
+
+## 6. Dates
+
+- `date*` compare calendar dates, `dateTime*` instants (argument formats: §2). `addToDate`/`subtractFromDate` offset by whole years/months/days.
+- "Within N days before X": `{{dateAfter(var("d");subtractFromDate(var("x");0;0;7))}}`. Day differences can't be computed renderably (no `toEpoch`) — use a DELAY, such a comparison, or a code condition.
+- **Annual dates (birthdays)**: never `dateEq(var("birthdate");now())`. Compare month and day: `{{and(eq(month(var("contact.birthdate"));month(now()));eq(day(var("contact.birthdate"));day(now())))}}` — in a formula field; as a condition use code or a boolean set-variable (§4 of Automations Conditions (not yet published)).
+- **Never hardcode a year**; derive it: `{{dateAfter(var("order_date");concat(toString(year(var("order_date")));"-10-31"))}}`. Use `year(now())` only when the rule is about the current calendar year.
+- Windows crossing New Year (Dec 26 – Jan 4): `{{or(and(eq(month(var("d"));12);gt(day(var("d"));25));and(eq(month(var("d"));1);lt(day(var("d"));5)))}}`; pick `gt`/`gte` from the user's wording.
+- Formatting: `{{toString(month(var("d")))}}/{{toString(day(var("d")))}}/{{toString(year(var("d")))}}` in a string field.
+
+## 7. Conversions
+
+`toString()` numbers/booleans before text functions; `toNumber()` string `format: number` fields before math; neither converts arrays.
+
+## 8. Workarounds that stay renderable
+
+- Strip a known prefix: `{{if(startsWith(var("price");"%24");substring(var("price");1;subtract(stringLen(var("price"));1));var("price"))}}` (`"%24"` is the encoded `"$"`).
+- Title case: `{{upper(substring(var("t");0;1))}}{{lower(substring(var("t");1;subtract(stringLen(var("t"));1)))}}`.
+- Anything needing replace/split/regex/loops → a code condition (for branching) or tell the user it cannot be computed.
+
+## 9. Self-validation checklist (run on every expression)
+
+1. Parses: balanced `{{}}` and parentheses, `;` separators, double-quoted strings, no whitespace outside strings, no `0.x`/`.x`/exponent numbers.
+2. Every function is in §2 (formula fields), the condition table (conditions) or the filter shapes (filters).
+3. Arity matches §2 exactly (`substring` 3, `round` 2).
+4. Argument types match the §2 table: numbers to math/`eq`/`gt`…, strings to text functions (`toString` numbers), dates with the right `format`, arrays only to `array*`/`isEmpty`; `if` arg 1 boolean and, in number/boolean fields, both branches of the field's type; `arrayMap` arg 2 a literal path.
+5. Every `var()` path exists in the aggregated schema of THIS step (ancestors only). If the unknown path has an array prefix (`items.id` where `items` is an array), element access is inexpressible — stop, don't respell.
+6. `$_` appears only inside `arraySome`/`arrayEvery` predicates (conditions/filters), bare (never `var($_)` or `$_.x`).
+7. Result type fits the target field (§4); no array into a single-value field.
+8. String literals URI-encoded; no single quotes.
+9. Final gate: Validate Automation returns no mapping errors — it misses some paths and every builder-only rule above, so steps 1–8 are yours.

package/skills/wix-manage/references/automations/build-and-manage-automations.md

@@ -1,34 +1,313 @@
 ---
 name: "Build and Manage Wix Automations"
-description: "Discover installed automation triggers and actions and inspect an automation’s current active status without changing site data."
+description: "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."
 ---
 
+**Topic guides not yet published:** Automations Feasibility and Planning; Automations Entity and Provider Configuration; Automations Item Selection; Automations Email Actions; Automations Conditions; Automations Delays Variables and Branches; Automations Schemas and Scheduling. References marked “not yet published” refer to procedures that are not in this stage; the general API reference does not contain them. Do not attempt a workflow that requires one of them.
+
+This stage supports read-only inspection, creation of immediate, linear APP_DEFINED automations with schema-defined inputs, and turning an automation on or off when the user asks ([Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status)). Configuration updates of saved automations, deletion, execution tests, email/opaque widgets, entity pickers, schedules, conditions and special steps are outside this stage. Do not perform those workflows with this skill. Validation and its numbered checklist are included in this guide. “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).
+
 # Build and Manage Wix Automations
 
-Use this guide to discover installed automation capabilities and inspect whether an
-automation is active. These are read-only workflows. Creation, configuration edits,
-activation and test execution are outside what this skill covers.
-Do not perform a write when the user asks only to inspect.
+If a request needs a workflow outside the scope above, explain the limit; do not substitute a
+different business operation. A conditional formula in a schema-enabled input is supported by
+the expression guide; it is not a condition node.
 
-| Request | Load |
+## Required guides
+
+| Task | Guide |
 | --- | --- |
-| Check which triggers/actions are available and what inputs they need | [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) |
-| Is an automation turned on? What does its status mean? | [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) |
-
-For a capability check, resolve the site's catalogs, retain the returned app/key identities,
-and inspect the selected schemas. A remembered action key is a search hint, not evidence that
-the action is installed. State missing prerequisites without offering an unverified substitute.
-If a requested action isn't found, report it exactly as the "Bounded fallback" section of
-[Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) says (scan evidence, "not found" vs "not installed", closest
-related actions).
-Resolve the trigger once and scan the action catalog once; answer from those results instead
-of repeating either call.
-
-For current status, find the exact automation, Get its returned ID, and report the status
-from that response. Every status answer names the automation and its returned ID. Current ACTIVE/INACTIVE status is separate from historical run results.
-
-Status questions need only Query and Get Automation: don't call the trigger or action catalogs
-for them. Query by the exact name with one bounded page before paging further.
-
-Keep the requested site context fixed. Do not expose tokens or credentials. Tie every claim
-to the returned data, and distinguish a missing record from proof of nonexistence.
+| Resolve installed trigger/action identities and API requests | [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) |
+| Construct a single-parent graph, IDs and namespaces | [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model) |
+| Configure trigger payload and filters | [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) |
+| Check action semantics and effective schemas | [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration) |
+| Type-safe input formulas, literal escaping and ancestor variables | [Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions) |
+| Check status, or turn an automation on or off | [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) |
+
+## Check what the site supports (read-only)
+
+For "does my site support X / what would I need", resolve the trigger once and scan the action
+catalog once ([Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §6), inspect the chosen schemas, and report the pair
+and the inputs the user would supply. If something isn't found, report it as that section says
+(scan evidence, "not found in the installed catalog", closest related entries). Don't build,
+validate or save a candidate to answer this.
+
+## Create and verify
+
+1. Keep the requested site fixed. Discover the installed catalogs and inspect the exact
+   trigger/action schemas. Resolve semantic capability first: an action that retrieves a
+   task is not one that creates it. If no suitable installed action exists, report the gap.
+2. Map the user's values and compatible payload fields. Ask for missing required values;
+   never invent IDs or use a display name where an ID is required. An ID or key the user
+   supplies (for example a label key for a trigger filter) may be used as given; never call a
+   create or find-or-create endpoint (such as Find or Create Label) to check or replace it,
+   and if Validate warns that it doesn't exist, keep it and say so in your answer. If Validate
+   returns a CRITICAL error for it instead, don't save: tell the user it wasn't found and ask
+   them to confirm it. If an action
+   is an opaque widget (a `WIDGET_COMPONENT` action whose `inputSchema` does not fully describe
+   the request; [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration) §3), or a field needs an entity looked up by name, stop
+   at the scope limit above. A `WIDGET_COMPONENT` action whose schema does describe the
+   request is hand-authored as that guide's §5.2 explains.
+3. Construct a linear graph using the model and expression guides. Keep actions within
+   45 nodes. Set `origin: "USER"`, no `settings`, and `configuration.status: "INACTIVE"`.
+4. Follow **Validation and Verification below**: its §4 checklist is the actual hard gate,
+   followed by full Validate, Create and Get read-back (§§2–3). Its numbered items are
+   included here so references from other guides can be followed without an unpublished page.
+   Items for out-of-scope node types are not permission to create those types.
+5. Save only with the user's authorization. Report the returned ID, inactive status and
+   verified content. If the user asked to turn it on, activate it after the read-back as
+   [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) describes, then report it active. Do not run a test.
+
+The included procedure keeps only the headings of its update and execution-test sections;
+those workflows are published in a later stage, and the stage limits above take precedence.
+
+
+# Validation and Verification
+
+How to prove an automation is correct, saved, and editable in the builder before you tell the
+user it exists. This file owns the create procedure. API shapes: [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog).
+
+**TL;DR**
+
+- Climb the ladder in order: **§4 renderability checklist → Validate Automation → Create →
+  Get Automation read-back.**
+- **§4 gates Create and activation.** `VALID` alone does not prove the
+  builder can draw, edit and re-save the automation. Status-only deactivation follows §3 and
+  must not be blocked by unrelated configuration errors.
+- Create and Update do not validate; an unvalidated or unsaved automation is **not created**.
+- **Later stages only — not in stage 2:** Test Automation executes actions for real.
+
+## 1. Local checks and semantic review
+
+Run the §4 checklist on the complete automation object before **every** Validate call. Items
+tagged **[code]** are deterministic — a small script beats reasoning (ids, graph, namespaces,
+`var()` inventory, field limits). The rest need you to read schemas.
+
+Semantic review (you, not code) — required for every action before acceptance; full rules in
+[Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration) §6:
+
+- **Side-effect contract:** the action does what the user's verb says to the affected entity —
+  retrieval is not assignment; a message about a change is not the change.
+- **Recipient lineage** (email, chat, SMS, push): prove the recipient path — the trigger contact and
+  an upstream-created contact differ even when both are `contactId`; copy never proves who receives
+  it; for emails (later stages only — email is outside stage 2) the audience fields decide (§3 of Automations Email Actions (not yet published)).
+- **No fabricated content:** every user-specific value (recipient, subject, entity, amount) comes
+  from the user, the site, or the payload.
+
+## 2. Validate Automation
+
+Request: `{automation: <full object>, validationSettings?}`. Validate the complete candidate
+you intend to save; an unsaved object doesn't need an id. For creation, set `origin: "USER"`,
+a real `name`, and `configuration.status: "INACTIVE"`. For activation, validate the candidate with
+`configuration.status: "ACTIVE"`. Never rewrite an installed automation's origin or deactivate a live
+automation merely to validate it.
+
+`validationSettings.actionIds` validates just the listed actions — useful while configuring node
+by node. `skipProviderValidations: true` skips app-specific checks — acceptable for intermediate
+checks only. **The final gate is always a full validation with no settings.**
+
+Response: `status` is `VALID`, `VALID_WITH_WARNINGS` (only `errorSeverity: WARNING`), or
+`INVALID` (at least one `CRITICAL`). Target `VALID`. Accept `VALID_WITH_WARNINGS` only when you
+understand each warning and tell the user about it.
+
+**What the builder does with it.** When the user opens the automation, the builder runs the same
+full Validate and pins **every** returned error to its node (trigger or action) — mapping errors
+included. A `CRITICAL` shows as a node error and **blocks Activate / Publish** until fixed; a
+`WARNING` shows as a node warning. Mapping errors show on the step until the user opens it, then
+its form replaces them with field-level marks; other configuration errors show as error/warning
+text; a provider error shows as "title: message". So an automation you save with errors opens
+broken.
+
+Each `triggerValidationErrors[]` / `actionValidationErrors[]` item has `errorType`
+(`CONFIGURATION_ERROR` | `PROVIDER_ERROR`), `errorSeverity`, and one of:
+
+- `configurationError{errorType, filterFieldKey | fieldKey}` — a platform check (tables below);
+- `providerConfigurationError{title, message, ctaLabel, ctaUrl}` — the owning app's own check
+  (`validateConfiguration`; often a missing connection or entity).
+  Action errors also carry `actionId`, `appId`, `actionKey`.
+
+### Error types → fix
+
+Trigger (`configurationError.errorType`):
+
+- `NOT_FOUND`, `INVALID_TRIGGER_KEY` — not in this site's catalog → re-resolve; never guess keys.
+- `APP_NOT_INSTALLED`, `MODERATION_MISMATCH` — not available on this site → tell the user; don't
+  substitute silently.
+- `DEPRECATED` — being retired → prefer its replacement, or tell the user.
+- `INVALID_FILTER_FIELD_KEY` — not a filter the trigger defines → use only its `filters[]`.
+- `INVALID_FILTER_EXPRESSION` → rebuild with the filter shapes in [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §4.
+- `MISSING_REQUIRED_FILTER` → add it (ask the user for its value if needed).
+
+Action (`configurationError.errorType`, with `fieldKey` — fix the field it names; never delete a
+field to silence an error):
+
+- `NOT_FOUND`, `INVALID_ACTION_KEY`, `APP_NOT_INSTALLED`, `MODERATION_MISMATCH` — not available
+  on this site → re-resolve; pick another action or tell the user.
+- `DEPRECATED` — the builder shows "Action will be removed soon" → use its replacement
+  (§2 of Automations Feasibility and Planning (not yet published)).
+- `INVALID_MAPPING` → remove keys not in the effective schema; re-fetch the dynamic input schema.
+- `MAPPING_TYPE_MISMATCH` → convert (`toString`, `toNumber`), map another field, or build the
+  object shape (e.g. MONEY).
+- `MAPPING_MISSING_REQUIRED_FIELD` → map it from the payload or ask the user; never a dummy value.
+- `MAPPING_SCHEMA_MISMATCH` (enum, uuid, email format…) → a legal enum value / real id.
+- `MAPPING_VARIABLE_MISSING_FROM_SCHEMA` → fix the path against the aggregated schema, or reorder
+  so the source is an ancestor.
+- `SAMPLE_CODE_RUN_FAILED` → fix the code step (guard missing fields — §5 of Automations Conditions (not yet published)).
+- `POST_ACTION_NOT_FOUND` → a successor id doesn't exist; fix the graph.
+
+Create/Update can also fail with `ON_BEFORE_SAVE_ACTION_EXCEPTION`: the owning app's save hook (e.g. for Send an email) rejected the step. Treat it like a provider error — read the message, fix the mapping or tell the user; don't retry the same write blindly.
+`PROVIDER_ERROR` usually needs something only the user can do (connect an account, pick a
+resource, finish setup). Report its `title`/`message` and the `ctaUrl`, and don't loop on it.
+
+### Fix loop
+
+1. Group errors by class (type + node). Fix all independent errors in one pass.
+2. Re-run the §4 checklist, then re-validate.
+3. At most 2–3 attempts per class. If an error comes back unchanged, re-read the reference that
+   owns that construct rather than trying variations.
+4. Still failing → stop. Tell the user exactly which node and why, and what you need from them.
+   Don't save an INVALID configuration or activate it. Status-only deactivation is still
+   allowed under §3; stopping future runs does not require repairing the automation first.
+
+## 3. Persistence, read-back and honest reporting
+
+### Create
+
+1. §4 checklist passes and the final full Validate is `VALID` (or understood warnings).
+2. Create Automation with `origin: "USER"`, `configuration.status: "INACTIVE"`, no `settings`.
+   Capture `id`. Send Create as its own call, after a separate full Validate call has returned
+   `VALID` (or understood warnings) — never in the same script as that Validate or as discovery.
+   Send it once per candidate: if a Create's outcome is unknown, Query Automations before
+   resending it (Reporting rules below). A Create that was never sent is not an attempt.
+3. **Read back** with Get Automation on the same site. Confirm the trigger, the root id, and the
+   set of action ids/types match what you sent (string literals come back URI-encoded, as sent).
+   If you used an override schema, Get with `fields: ["OVERRIDE_SCHEMA"]` ([Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §2).
+   Run the Get as a separate call once Create has returned (not batched into the same script),
+   and keep its response body as returned: the returned `automation` is the evidence, so don't
+   replace it with a summary you assemble from selected fields.
+4. Hand off, leading with the outcome. Make the first line of your answer the saved state, for
+   example: "Saved **<name>** as inactive (ID `<automationId>`). Click **Activate** in the
+   builder to turn it on: `https://manage.wix.com/dashboard/<metaSiteId>/triggers/edit/<automationId>`".
+   That first line MUST name the automation, its status and its ID together; don't move the ID
+   to a later line, because a reader may see only the first line.
+   Then say what it does, and ask the user to review it in the builder. If the user asked to
+   turn it on, activate it first (step 5) and make the first line the active state instead:
+   "Saved **<name>** and turned it on (ID `<automationId>`): <edit link>".
+5. Activate only on request — see "Activation status, activate, deactivate" below.
+
+### Update
+
+> **Later stages only:** not available in stage 2; this section is published in stage 3.
+
+### What happens when the user opens it in the builder
+
+- The builder edits a **hidden draft copy** and autosaves the user's changes into it. The
+  published object (what Get returns) changes only when they click **Activate** (inactive
+  automation) or **Publish Changes** (active one) — both publish, and Activate also turns it on.
+- On load it re-resolves every trigger/action from the site catalog ("not found" on a miss), runs
+  Validate (§2) plus its own checks (required filters, empty filters, the create-contact rule in
+  §4), and pins the results to nodes.
+- On load/save it silently rewrites some shapes: RATE_LIMIT `{{1440}} MINUTES` → `{{24}} HOURS`;
+  a webhook trigger filter that is missing or has another id is rebuilt from `webhookId`; unreachable actions and root ids that
+  point nowhere are **deleted**; an empty name becomes "Untitled …". The §4 checklist avoids all of
+  these, so the user's first save doesn't change your automation.
+- Before you Update an automation the user has been editing in the builder, ask them to publish
+  or discard there and close the tab, then Get — else their publish can overwrite your change.
+
+### Activation status, activate, deactivate
+
+Read or change status only as [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) describes; this guide adds no status
+procedure of its own. Deactivation does not require repairing the configuration.
+
+### Reporting rules
+
+- Report separate counts: **attempted**, **acknowledged**, **verified** by read-back, **active**.
+  Only verified automations "exist".
+- An id without a successful read-back is **unverified** — say so; don't blindly retry the create
+  (Query Automations first to see whether it landed).
+- A validated-but-unsaved object is a proposal, not an automation.
+- Never describe runtime behavior ("it will send…") as verified — only validated.
+
+## 4. Builder-renderability checklist — the single pre-save gate
+
+Use this gate before Create and activation, not status-only deactivation.
+Creation restrictions ("never add", conservative feature support) do not require rewriting
+existing builder-supported nodes during an unrelated update. Preserve those nodes and their
+metadata; use the owning reference's preservation rules and full Validate. A failing item is a
+blocker, not a warning: some make the canvas spin forever or crash, others are silently
+rewritten or deleted on the user's first save. Each owning reference has a detailed checklist —
+this list is the union; run those too for the node types you used.
+
+**Graph and ids** — [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model)
+
+1. [code] Exactly one `rootActionIds` entry, and it exists in `actions`. RATE_LIMIT, if present, is
+   that root and the only one.
+2. [code] Single-parent tree: every successor list (`postActionIds`, `truePostActionIds`,
+   `falsePostActionIds`, SPLIT `postActionId`) has ≤ 1 id and points to an existing action; every
+   non-root action has exactly one parent and is reachable from the root; no cycles; no MERGE /
+   `mergeActionId`. Converging branches = duplicated downstream steps.
+3. [code] `actions[k].id === k`; ids are fresh uuid v4, unique across actions, SPLIT path ids and
+   the trigger key, and never collide with `<id>true`, `<id>false`, `<id>-end`.
+4. [code] Each action has a known `type`, only its own type's `*Info`, `[]` (not omitted) for an
+   ending successor list, and a builder-format `namespace`. Namespaces are unique except that
+   SET_VARIABLES steps share `setVariable`; their output keys must be unique across steps.
+   For every action type, `skipActionExpression` is `"{{true}}"` or absent.
+
+**Trigger** — [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §7
+
+5. `appId`+`triggerKey` came from Resolve Triggers on this site.
+6. Filters: catalog filter `id`, verbatim `fieldKey`, Shape A/B expression whose literal value array
+   holds the form its filter type allows ([Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §4.1: quoted entity ids, quoted static
+   values, or exactly one bare number/boolean); **no filter with an empty `filterExpression`**; ≤ 5 filters; every required
+   filter present, plus required follow-ups of every set parent. Webhook trigger: exactly its
+   `webhookId` shape.
+7. Scheduled / future-date configuration and `scheduledEventOffset` match
+   Automations Schemas and Scheduling (not yet published).
+
+**Actions** — [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration), Automations Entity and Provider Configuration (not yet published), §2 of Automations Feasibility and Planning (not yet published)
+
+8. Every APP_DEFINED `appId`+`actionKey` came from Resolve Actions on this site; no unsupported
+   action added — including no new code-variable step (the public Create refuses it).
+   **Later stages only — email is outside stage 2:** New email steps have a provider-generated mapping used once and persisted before content edits; no fabricated opaque-widget mapping; unrelated existing ones unchanged
+   (except the documented site-owner audience replacement).
+9. `inputMapping`: only schema keys (an existing email/widget step's mapping passes through unchanged), types and
+   enums match, every required field mapped (optional ones per [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration) §5.2), entity-selector fields hold ids, formulas
+   only in `dynamicValuesOptions.enabled` fields.
+10. No "Create a contact" action (`contacts-create_contact`) when the trigger payload already has
+    an `identityType: "contact"` field — the builder marks it "can't create a contact" and blocks
+    activation.
+
+**Expressions and conditions** — [Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions) §9, §6 of Automations Conditions (not yet published)
+
+11. [code] Every `var()` path exists in that node's aggregated schema
+    — trigger + ancestor outputs only — with a compatible type.
+12. Builder-renderable functions only; `;` separators; double-quoted, URI-encoded string literals;
+    number/boolean fields hold exactly one expression of that type.
+13. CONDITION: exactly one expression group with `AND`/`OR` and 1–20 panel-renderable expressions;
+    not both branches empty; otherwise a CODE_CONDITION.
+
+**Special steps** — Automations Delays Variables and Branches (not yet published)
+
+14. DELAY: exactly one mode — relative (`offsetExpression` a `{{N}}` literal + unit) or absolute
+    (`dueDateExpression`). RATE_LIMIT: `{{1}}`, a trigger identifier allowed by
+    §2 of Automations Delays Variables and Branches (not yet published) (preserve existing supported member/user/UUID identifiers), and a
+    duration (`{{24}} HOURS`, never `{{1440}} MINUTES`) unless the user explicitly wants
+    "only ever once" (no duration).
+    SET_VARIABLES: matching keys, every property has a `title`, keys unique across all variable
+    steps; preserve existing image-variable metadata per §3 of Automations Delays Variables and Branches (not yet published).
+    SPLIT: 2–10 paths.
+
+**Object and limits**
+
+15. [code] Text limits: `name` 1–100 chars (API allows 500; the builder's name field holds 100),
+    `description` ≤ 2000, action `displayName` 1–60, `namespace` ≤ 100, SPLIT path `name` ≤ 100.
+    Expression limits: condition expression ≤ 5000 chars (a longer one fails the builder's save),
+    code ≤ 1000, filter expression ≤ 5000, `skipActionExpression`/delay/rate-limit expressions ≤ 1000.
+    Step count: ≤ 45 actions of any type — at 45 the builder blocks adding or duplicating steps.
+    Count before duplicating downstream steps into each branch.
+16. On create: `origin: "USER"`, no `settings` (never `hidden` or `readonly`).
+17. Full Validate Automation returns no `CRITICAL` errors, and you can explain every `WARNING`.
+
+## 5. Test Automation — only with explicit authorization
+
+> **Later stages only:** not available in stage 2; this section is published in stage 3.