@wix/agent-skills 1.32.0 → 1.33.1

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

@@ -1,313 +1,144 @@
 ---
 name: "Build and Manage Wix Automations"
-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."
+description: "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."
 ---
 
-**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
-
-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.
-
-## Required guides
-
-| Task | Guide |
-| --- | --- |
-| 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.
+This publication is being released in stages. Where a topic guide is not yet published, consult the official Automations API reference and method schemas before using that feature; do not guess its contract. Exception: Send an email and other opaque-widget (provider-owned) actions are outside stage 3 until Automations Email Actions is published; explain the limit instead of configuring them from the API reference. “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).
+
+# Wix Automations Builder
+
+You build automations with the **public** Wix Automations APIs. The result is only done when it
+(1) passes **Validate Automation**, (2) **renders and is editable in the Wix dashboard builder**
+(`https://manage.wix.com/dashboard/<metaSiteId>/triggers`), and (3) does what the user asked —
+the right trigger, the right side effect, the right recipient.
+
+An automation is `Trigger → (optional filters) → a tree of steps`: app actions (send a message,
+add label, create task…), conditions, delays, a rate limit, variables and parallel paths.
+
+## References — load on demand, never all at once
+
+| File                                        | Load when…                                                                                                                                                                                                                        |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog)                 | **Always first.** Auth, every public endpoint (REST + SDK), catalog discovery without flooding context, what is NOT public.                                                                                                       |
+| Automations Feasibility and Planning (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))    | Before promising or refusing anything, and before any update. What's impossible, unsupported actions, update locks, planning heuristics.                                                                                          |
+| [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model)            | Designing the graph / assembling the Automation object. Tree invariants, node shapes, namespaces, the per-step "what data can I read" (aggregated schema) rule.                                                                   |
+| [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration)                    | Choosing and configuring the trigger and its filters.                                                                                                                                                                             |
+| [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration)                     | Choosing an app action and writing its `inputMapping`.                                                                                                                                                                            |
+| 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))    | A field needs an id (form, label, service, email…), or the component has special handling (**provider APIs registry**: triggered emails, webhooks, scheduled, custom trigger…).                                                   |
+| Automations Item Selection (topic guide not yet published; until it is published, resolve IDs with a vertical public API or ask the user) | List a trigger's or action's selectable entity ids: dependent fields, statuses, value shapes. |
+| Automations Email Actions (not yet published; email configuration is outside stage 3) | Initialize each new email action, persist it, then edit content; preserve existing email mappings. |
+| [Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions)         | Writing ANY `{{ … }}` value (mappings, filters, delays, variables).                                                                                                                                                               |
+| [Automations Conditions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-conditions)                  | Adding a CONDITION or CODE_CONDITION.                                                                                                                                                                                             |
+| [Automations Delays Variables and Branches](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-delays-variables-and-branches)             | DELAY, RATE_LIMIT, SET_VARIABLES, SPLIT, node naming (CODE_CONDITION spec: [Automations Conditions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-conditions)).                                                                                                                                      |
+| [Automations Schemas and Scheduling](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-schemas-and-scheduling)      | Dynamic schemas, override output schema, scheduled / date-based triggers, timezone.                                                                                                                                               |
+| [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) | **Before every save** — the builder-renderability checklist (§4, a hard gate), Validate, fix loop, persistence + read-back, what the builder does on open, Test Automation. |
+| [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) | **Is it active / turn it on or off?** Status-only operations, locks, idempotence and read-back. |
+
+A typical build needs 4–6 of these. If your harness supports subagents, push broad catalog
+sweeps and multi-schema reads into a subagent and keep only its conclusions.
+
+## Prerequisites
+
+- **Site + auth.** A token with the **Set Up Automations** scope
+  and the target `metaSiteId` (see [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §1). Lock one site for the whole task; confirm it before the first write.
+  Never print tokens or auth headers.
+- **What the user wants**, concretely enough to pick a trigger and each side effect. Ask only
+  what you can't find out from the site's catalog or data.
+
+## Workflow — keep the stages separate
+
+For status-only requests, go directly to [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status); it requires no planning or
+rebuilding of the automation. Query only discovers matching IDs: after one exact match, Get that ID and report its `configuration.status`. Explain ACTIVE as eligible for new trigger events and INACTIVE as not eligible; neither proves past run success.
+
+### 0. Feasibility — Automations Feasibility and Planning (topic guide not yet published; consult the [Automations API reference](https://dev.wix.com/docs/api-reference/business-management/automations))
+
+Check the request against what the public APIs and the builder support **before** planning.
+Avoid both failure poles: _false impossibility_ (refusing something supported — parallel paths,
+month-end schedules checked in code) and _false success_ (saving
+something that can't work). If an ask can't be met as stated, offer alternatives and let the
+user choose. For an update, Get the automation first and check `origin` / `settings` locks
+([Automations Validation and Persistence — included update restrictions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence)).
+
+### 1. Resolve real components — [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog), [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration), [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration)
+
+Find the trigger and actions in **this site's** catalog (Resolve Triggers with `basicFieldsOnly`;
+Resolve Actions filtered by `appId`/`actionKey` — it has no `basicFieldsOnly`; small pages; search
+locally). Never invent an `appId`,
+`triggerKey` or `actionKey`, and never reuse example or placeholder ids from these
+references (ids explicitly marked as fixed platform constants — e.g. the webhook filter id, the
+Forms app id, the owner role — are required as written). Decide by payload and
+input schemas, not display names. Hydrate only the shortlisted components with full schemas.
+
+### 2. Skeleton — [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model)
+
+Plan the structure only: trigger, step list with fresh uuid v4 ids and builder-format
+namespaces, connections, and a one-line note per step (what it does, which entity ids it needs).
+Hard rules (the builder breaks otherwise):
+
+- exactly **one** root; a RATE_LIMIT, if any, is that root and the only one;
+- every `postActionIds` / `truePostActionIds` / `falsePostActionIds` has **at most one** id;
+- a **single-parent tree** — no joins, cycles, orphans, or MERGE. To "continue after both
+  branches", duplicate the downstream steps in each branch with fresh ids;
+- parallelism only through SPLIT (alpha — see [Automations Delays Variables and Branches](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-delays-variables-and-branches)).
+
+### 3. Configure one step at a time, top-down
+
+For each step load only the matching reference, then:
+
+1. **Compute the step's aggregated schema locally** ([Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model)): trigger payload
+   (dynamic schema only after its filters are final) + each _ancestor_ action's output under its
+   namespace (dynamic output only after that action's mapping is final) + variables + identity
+   enrichment. Only paths in it may appear in `var("…")`.
+2. **Action input.** Map every required field yourself, following the field-type rules in
+   [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration) / [Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions). Check the **provider APIs registry** in
+   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)) first — some components have a dedicated configuration API.
+   **Later stages only — email is outside stage 3:** **Send an email** (`triggered-emails`) — initialization and content: Automations Email Actions (not yet published; email configuration is outside stage 3).
+   **Later stages only — not in stage 3:** Other opaque widgets require their provider API or manual setup.
+3. **Entity ids.** Fields backed by an entity selector take **ids**, never display names. Get
+   them through the owning vertical's public API, or ask the user (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))).
+   A failed lookup means _unknown_, not _doesn't exist_.
+4. **Expressions.** Self-check every `{{ … }}` against [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) — builder-renderable functions and operators only; anything the condition
+   panel can't render becomes a CODE_CONDITION.
+
+### 4. Validate → fix → loop — [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence)
+
+Run the **builder-renderability checklist** (§4 there — the single pre-save gate; script its
+[code] items: graph, ids, namespaces, `var()` paths, field limits), then **Validate Automation** on
+the full unsaved object. Fix and re-validate; 2–3 attempts per error class, and re-read the owning
+reference instead of mutating blindly when an error repeats.
+
+**Hard gate:** never create, edit configuration or activate until every applicable checklist item
+holds AND the final full Validate has no `CRITICAL` error. `VALID` alone is not enough: the builder
+re-validates on open, pins every error to its node, blocks Activate while any remains, and
+silently deletes or rewrites shapes the checklist forbids.
+Status-only deactivation follows §3 of that reference without requiring configuration repair.
+Creation restrictions do not require changing existing builder-supported nodes on an unrelated update.
+
+### 5. Persist and hand off
+
+- **Create:** Create Automation with `origin: "USER"`, `configuration.status: "INACTIVE"` and no
+  `settings` → **Get** it back on the same site and compare → give the user the name, id, status
+  and edit link `https://manage.wix.com/dashboard/<metaSiteId>/triggers/edit/<automationId>`, and
+  tell them the builder's main button (**Activate**) turns it on → activate via the API (Update with
+  `status: "ACTIVE"`) only when the user asks.
+- **Update:** if the user has been editing it in the builder, ask them to publish or discard
+  there first (their draft is invisible to you) → Get with override schemas and current `revision` → change only what was
+  asked → checklist + Validate → confirm first if the automation is ACTIVE (updates are live) or
+  if you delete nodes (unless already authorized) → Update with the complete merged object,
+  preserving origin/settings/status → Get the returned id back (preinstalled overrides can change ids).
+- Report honestly: validated ≠ saved ≠ verified ≠ active. Never claim runtime behavior from
+  validation alone. **Test Automation executes real side effects** — only with explicit consent.
+
+## Non-negotiables
+
+- Use the API contracts in these references and the public Automations docs. Supported
+  `automationConfigMapping` fields are described here even where the docs omit them; use the
+  catalog's configuration schema and preserve the mapping on updates.
+- Builder renderability is part of correctness, not polish: the §4 checklist in
+  [Automations Validation and Persistence](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-validation-and-persistence) gates Create, configuration edits and activation; deactivation
+  uses its status-only procedure.
+- Real ids from the site; no display names in id fields; no invented content (addresses,
+  coupon codes, template ids).
+- Obtain authorization for activating, live edits, deleting or test runs when the request does
+  not already authorize that action. Do not ask again for an explicitly requested status change.