@wix/agent-skills 1.31.2 → 1.33.0

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

@@ -1,81 +1,217 @@
 ---
 name: "Automations API Catalog"
-description: "Discover installed automation triggers and actions and inspect their schemas through site-scoped public catalog APIs."
+description: "Discover site-specific triggers and actions, authenticate public Automation API calls, and choose the API for validation, persistence or catalog lookups."
 ---
 
-# Discover installed automation capabilities
-
-Check the site's installed trigger/action catalogs, then inspect the chosen components'
-schemas. This recipe is read-only: do not create an automation, install an app, generate email
-content, or run an action to establish availability.
-
-## Authentication
-
-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`. OAuth app tokens are bound to a site instance. Never print credentials.
-A 401/403 is an access failure, not evidence that a catalog component is unavailable.
-
-## Resolve, select, inspect
-
-1. Use a known key only as a search hint. Resolve an exact candidate first; if it is absent,
-   browse small pages and compare names/semantics locally. Do not conclude that a remembered
-   key exists on this site without a successful Resolve response.
-2. For triggers, request `basicFieldsOnly: true` while browsing, then hydrate only the chosen
-   trigger with Get Trigger By App Id And Key. Compare its payload and filters to the intent.
-3. Actions already include schemas in Resolve. Retain the chosen returned identity and
-   required input fields; avoid repeating the whole catalog just to read display names.
-4. Summarize the available pair and required configuration, distinguishing what the trigger
-   supplies from values the user would need to choose. Do not mutate anything to prove it.
-
-### Trigger discovery
-
-`POST https://www.wixapis.com/v1/triggers/resolve`
-
-```json
-{"basicFieldsOnly":true,"query":{"filter":{"triggerKey":"contacts-new_contact_was_created"},"paging":{"limit":25,"offset":0}}}
-```
-
-Read `results[]` and `paging`. A nonempty matching result establishes an installed trigger;
-use its returned `appId` and `triggerKey` in:
-
-`GET https://www.wixapis.com/v1/triggers/apps/<appId>/keys/<triggerKey>`
-
-Read `trigger.payloadDataSchema`, `trigger.filters` and `trigger.automationConfigSchema`.
-The contact-created key above is a discovery hint; names and availability may vary by site.
-
-### Action discovery
-
-`POST https://www.wixapis.com/v1/actions/resolve`
-
-```json
-{"query":{"filter":{"actionKey":"addLabelsToContact"},"paging":{"limit":25,"offset":0}}}
-```
-
-Read `actions[]`, `paging`, and each chosen action's `appId`, `actionKey`, `inputSchema`,
-`outputSchema` and `interfaceConfiguration`. Inspect required properties, types, enums and
-field descriptions before explaining configuration. For an existing runtime version use
-`GET https://www.wixapis.com/v1/actions/apps/<appId>/keys/<actionKey>` and read `action`.
-A site may have Add label to contact without Create task; never substitute one for the other.
-
-### Bounded fallback
-
-Remove the exact-key filter to browse; use offset pages of at most 25 entries, with no sort.
-Resolve Actions has no `basicFieldsOnly` option and rejects displayName filters; search names
-locally. Compact each page to identities and display names before adding it to reasoning
-context. Fetch each catalog page and static schema once, cache it for this site, and hydrate only a
-shortlist; never re-fetch a page or schema you already have. Pages can overlap;
-de-duplicate by appId+key. Only a complete scan with distinct count equal to `paging.total`
-proves absence; state the evidence ("scanned N distinct of `paging.total` N"). Without that
-proof, say the component was "not found in the installed catalog", never that it is not
-installed. Either way, list the closest related actions you saw in that scan, as findings
-rather than substitutes, with their returned `appId`/`actionKey` and display name; don't fetch
-their schemas unless the user asks.
-
-Resolve is site-scoped; global Query catalogs can include uninstalled apps and do not prove
-availability. The method schemas below confirm the full public URLs; do not invent a private
-transport or guess a new path if access fails.
-
-Official contracts: [Resolve Triggers](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/trigger-catalog/resolve-triggers),
-[Resolve Actions](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-catalog/resolve-actions).
-For current automation status use [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status).
+> **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).
+
+# API Catalog — the public Wix Automations APIs
+
+Every call this skill needs, as a public REST endpoint (base `https://www.wixapis.com`) and the
+matching `@wix/automations` SDK method. Docs live under
+`https://dev.wix.com/docs/api-reference/business-management/automations/` — append `.md` to any
+docs URL to get raw markdown. When a field name here and the docs disagree, the docs win.
+
+**TL;DR**
+
+- Catalogs: Resolve Triggers / Resolve Actions. Oracle: **Validate Automation** — Create and
+  Update do **not** validate.
+- Persist: Create `INACTIVE` → Get read-back; activate only when asked.
+  Procedures (create, activate, read-back
+  — builder drafts are invisible publicly): [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §3.
+- **Later stages only — not in stage 2:** **Test Automation runs actions for real** — only with explicit user authorization.
+- Resolve responses are large: page small, filter by exact keys, never paste a raw catalog.
+
+## 1. Authentication and transport
+
+- **Permission scope**: **Set Up Automations** (`SCOPE.CRM.SETUP-AUTOMATIONS`) for every
+  Automations method below. Generate Action Input Mapping and Get / Set Email Content (Automation Email Action API) need **Manage
+  Email Marketing** (`SCOPE.DC-PROMOTE.EMAIL-MARKETING`) — a 403 there means that scope is missing.
+  Entity lookups in other verticals need that vertical's read scope
+  (Automations Entity and Provider Configuration (not yet published)).
+- **Token**: `Authorization: <token>` header — an OAuth app access token (`client_credentials` via
+  Create Access Token) or an account API key the site owner generated with the needed scopes.
+- **Site context**: with an **API key**, send `wix-site-id: <metaSiteId>` on every call (all calls
+  here are site-level); never together with `wix-account-id`. OAuth app tokens are already bound
+  to one site instance.
+- **SDK**: `import { automationsV2, triggerCatalog, actionCatalog, activations } from
+'@wix/automations'`, used through a `createClient` Wix client with an auth strategy.
+- **Secrets**: NEVER print, log, echo or store tokens, API keys, app secrets or auth headers — not
+  in chat, files or error reports. Redact them from any request you show.
+- **Site lock**: resolve the target `metaSiteId` once and use it for every call, read-back and
+  link. Ask the user to confirm it before the first write only when more than one site is in
+  context or the request doesn't make clear which; a site fixed by the request or session is
+  confirmed. If anything points at another site, stop.
+- **Errors**: 401 = token expired/invalid (refresh, don't retry blindly). 403 = missing scope, app
+  not installed, or — on Create/Update of an automation that validated — a step the public API
+  can't create (e.g. the code-variable step, §4 of Automations Delays Variables and Branches (not yet published)). A timeout or 5xx is
+  **unknown**, not a verdict — retry read-only calls (Get, Query, Resolve, Validate) a bounded
+  number of times. Never blindly retry Create or Update: Query or Get first to see whether the
+  write landed ([Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §3, Reporting rules).
+
+## 2. Automations V2 (`automationsV2`) — base `/automations-service/v2/automations`
+
+> Stage 2 supports Query, Get, Validate, inactive Create, and Update only to activate or deactivate ([Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status)). Configuration updates, Delete and Test Automation below are future-stage reference material; do not call them in this stage.
+
+| Purpose  | REST                                                        | SDK                                       |
+| -------- | ----------------------------------------------------------- | ----------------------------------------- |
+| Validate | `POST https://www.wixapis.com/automations-service/v2/automations/validate`         | `validateAutomation(automation, options)` |
+| Create   | `POST https://www.wixapis.com/automations-service/v2/automations`                  | `createAutomation(automation)`            |
+| Get      | `GET https://www.wixapis.com/automations-service/v2/automations/{automationId}`    | `getAutomation(automationId)`             |
+| Update   | `PATCH https://www.wixapis.com/automations-service/v2/automations/{automation.id}` | `updateAutomation(_id, automation)`       |
+| Delete   | `DELETE https://www.wixapis.com/automations-service/v2/automations/{automationId}` | `deleteAutomation(automationId)`          |
+| Query    | `POST https://www.wixapis.com/automations-service/v2/automations/query`            | `queryAutomations(query)`                 |
+
+- **Validate** (unsaved or saved): `{automation, validationSettings?{actionIds[],
+skipProviderValidations}}` → `{status: VALID|VALID_WITH_WARNINGS|INVALID,
+triggerValidationErrors[], actionValidationErrors[]}`. The main oracle; send the full object.
+  Reading errors: [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §2.
+- **Create**: `{automation}` with `name`, `origin: "USER"`, `configuration{status, trigger{appId,
+triggerKey}, rootActionIds, actions}` → created `automation` (has `id`, `revision`). Does NOT
+  validate. Always `status: "INACTIVE"`; don't send `settings`.
+- **Get**: → `automation`. Use for read-back after every write and before every update.
+  `trigger.overrideSchema` and `appDefinedInfo.overrideOutputSchema` come back **only** when you
+  request them: `fields: ["OVERRIDE_SCHEMA"]` (REST `?fields=OVERRIDE_SCHEMA`). Without it their
+  absence is not data loss (Create's response omits them too).
+  Request overrides before complete-object updates and status changes too, not just creation read-back.
+- **Update**: in this stage, only to change `configuration.status` (activate / deactivate) as [Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status) describes. Send `{automation}` exactly as fetched with `fields: ["OVERRIDE_SCHEMA"]` — `id`, current `revision`, `name`, `configuration`, plus `origin` and `settings` — with only the status changed. Without `origin` and `settings` it fails `INVALID_ORIGIN_TYPE`; a stale `revision` is rejected. Capture the returned id: a preinstalled automation's site override can change it. Configuration updates are published in stage 3.
+- **Later stages only — not in stage 2:** **Delete** — published in stage 3.
+- **Query**: `{query{filter, sort, cursorPaging{limit ≤ 500, cursor}}}` → `automations[]`,
+  `pagingMetadata.cursors.next`. Returns only automations of apps installed on the site (incl.
+  overridden preinstalled ones), and never unpublished builder drafts. Full objects are large —
+  keep only `id, name, configuration.status, configuration.trigger`. If a filtered query fails on
+  a site with many automations, page unfiltered and filter locally.
+
+Automation object fields and limits (`name` ≤ 100 for the builder, `description` ≤ 2000,
+`origin`, `settings`, `configuration`): [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model) §1.
+Create/Update accept `configuration.trigger.automationConfigMapping` for scheduled/custom/webhook
+configuration even where the docs omit it; use [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) / Automations Schemas and Scheduling (not yet published).
+
+## 3. Trigger Catalog (`triggerCatalog`)
+
+| Purpose                | REST                                              | SDK                                             |
+| ---------------------- | ------------------------------------------------- | ----------------------------------------------- |
+| Triggers on this site  | `POST https://www.wixapis.com/v1/triggers/resolve`                       | `resolveTriggers(options)`                      |
+| Global catalog         | `POST https://www.wixapis.com/v1/triggers/query`                         | `queryTriggers(query)`                          |
+| One trigger            | `GET https://www.wixapis.com/v1/triggers/apps/{appId}/keys/{triggerKey}` | `getTriggerByAppIdAndKey(identifiers, options)` |
+| Dynamic payload schema | `POST https://www.wixapis.com/v1/triggers/dynamic_schema`                | `getTriggerDynamicSchema(appId, options)`       |
+| Identity enrichment    | `POST https://www.wixapis.com/v1/triggers/identities_schema`             | `getIdentitiesSchema()`                         |
+
+- **Resolve**: `{basicFieldsOnly?, appId?, query{filter, paging{limit, offset}, fields?}}` →
+  `results[]`, `paging`. Installed apps only. `basicFieldsOnly: true` for browsing (drops payload
+  schema, config schema, filters).
+- **Query** (global): `{query{filter, …}}` → `results[]` (filterable: `appId`, `triggerKey`,
+  `displayName`, `implementedMethods.*`). Includes apps NOT installed on the site — never build on
+  a trigger Resolve didn't return.
+- **One trigger**: → `trigger` with `payloadDataSchema`, `filters[]`, `automationConfigSchema`,
+  `implementedMethods`. The preferred way to hydrate a shortlisted trigger.
+- **Dynamic schema**: `{appId, triggerKey, selectedFilterOptions[{fieldKey, values[]}] (≤ 5)}` →
+  `dynamicSchema`. Only when `implementedMethods.getDynamicSchema` is true, and only after the
+  filters that drive it are chosen — no filter chosen ⇒ form answers are unknown, not absent
+  (request and merge: [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §5).
+- **Identities schema**: `{}` → `identitiesSchema{contact, member, …}` — shape of the `contact` /
+  `member` objects added when payload fields carry `identityType`.
+
+Trigger objects have no free-text description and display names are ambiguous — decide by the
+payload schema ([Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §2).
+
+## 4. Action Catalog (`actionCatalog`)
+
+| Purpose                    | REST                                                   | SDK                                            |
+| -------------------------- | ------------------------------------------------------ | ---------------------------------------------- |
+| Actions on this site       | `POST https://www.wixapis.com/v1/actions/resolve`                             | `resolveActions(options)`                      |
+| Global catalog             | `POST https://www.wixapis.com/v1/actions/query` (and `/query-latest`)         | `queryActions(query)`, `queryLatestActions`    |
+| Version active on the site | `GET https://www.wixapis.com/v1/actions/apps/{appId}/keys/{actionKey}`        | `getRuntimeAction(identifiers)`                |
+| Latest version             | `GET https://www.wixapis.com/v1/actions/latest/apps/{appId}/keys/{actionKey}` | `getLatestAction(identifiers, options)`        |
+| Dynamic input schema       | `POST https://www.wixapis.com/v1/actions/dynamic-input-schema`                | `getActionDynamicInputSchema(appId, options)`  |
+| Dynamic output schema      | `POST https://www.wixapis.com/v1/actions/dynamic-output-schema`               | `getActionDynamicOutputSchema(appId, options)` |
+
+- **Resolve**: `{query{filter, paging{limit, offset}, fields?}}` → `actions[]`, `paging`. Offset
+  paging only (`cursorPaging` is rejected). Entries carry full `inputSchema`, `outputSchema`,
+  `uiSchema` — large. Filter by `appId`/`actionKey`, page ≤ 25.
+- **Global catalog**: not site-scoped; "latest" may be newer than what the site runs.
+- **Runtime action**: → `action`. Use this schema when configuring for this site. Latest version
+  is for reference only.
+- **Dynamic input**: `{appId, actionKey, inputMapping}` → `{inputSchema, uiSchema}`. Call when an
+  input property has `updateSchemaOnChange: true` (no public `getDynamicInputSchema` flag);
+  re-call after changing such a field.
+- **Dynamic output**: `{appId, actionKey, inputMapping}` → `outputSchema`; bulk
+  (`bulkGetActionDynamicOutputSchemas`, POST `/v1/actions/bulk/dynamic-output-schema`, ≤ 20 items) →
+  `results[]{itemMetadata{success, error}, outputSchema}`. Only after that action's mapping is
+  final. Safe for any action you place upstream of a step that reads its output (no public flag
+  says which are dynamic); an error means "no dynamic output" — keep the static `outputSchema`.
+  Merge into the static schema. A failed bulk item = unknown schema, not empty.
+- **Generate Input Mapping From Intent** (`POST https://www.wixapis.com/v1/actions/generate-input-mapping-from-intent`)
+  is AI-backed — don't call it. For actions you can't map from their schema, tell the user they can't be configured through the API here and can be set up in the automations builder.
+- **Later stages only — email is outside stage 2:** **Email content of an existing Send an email step** — Get / Set Email Content; procedure in Automations Email Actions (not yet published).
+- **Later stages only — email is outside stage 2:** **New Send an email step** — Generate Action Input Mapping; procedure in Automations Email Actions (not yet published).
+
+Action objects: `appId`, `actionKey`, `displayName`, `description`, `inputSchema`, `outputSchema`,
+`interfaceConfiguration{type: GENERIC\|WIDGET_COMPONENT, genericOptions.uiSchema}`,
+`implementedMethods{validateConfiguration, getQuotaInfo}` (public). Resolve Actions has **no**
+`basicFieldsOnly` option (only Resolve Triggers does). Mapping rules: [Automations Action Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-action-configuration).
+
+## 5. Activations (`activations`)
+
+- **Later stages only — not in stage 2:** **Test Automation** — runs every action for real; published in stage 3.
+- **Later stages only — not in stage 2:** **Run Automation / Report Event / Rerun Activation** — for the app that owns a trigger; never
+  use them to build or "test".
+
+## 6. Catalog discovery without flooding your context
+
+1. **Browse cheaply.** Triggers: `resolveTriggers({basicFieldsOnly: true, query: {paging: {limit: 25,
+offset: N}}})`. Actions: `resolveActions` with small pages; keep only `appId`, `actionKey`/
+   `triggerKey`, `displayName`, `description`, `interfaceConfiguration.type`. Field projection (`fields`) may
+   be ignored — strip locally in code before anything reaches your reasoning context. Even with
+   `basicFieldsOnly`, 100 triggers is ~100 KB: keep pages ≤ 25 when results land in your context.
+2. **Cache** that compact list per site for the session and search it locally. Fetch each catalog
+   page and static schema once; never re-fetch one you already have. Dynamic schemas are the
+   exception: re-call them after changing an `updateSchemaOnChange` field.
+3. **Hydrate the shortlist** with exact keys (Get Trigger By App Id And Key / Get Runtime Action,
+   or a Resolve filter `{"appId": "...", "actionKey": "..."}`). Full schemas only for the chosen few.
+4. **Filters that work**: exact `appId`, `triggerKey`/`actionKey`, and `$in` on the keys (both
+   Resolves); on Resolve Triggers also `displayName` `$contains` / `$in` (inside `$or` too) and
+   `triggerKey` `$startsWith`. Resolve Actions rejects `displayName` filters — search names
+   locally. A rejected filter → fall back to small pages.
+5. **Don't sort** — `sort: [{fieldName: "id"}]` fails with `SORT_PARSER_ERROR` on both Resolves.
+   Unsorted offset pages can **overlap**: page until `paging.total`, de-duplicate by `appId`+key,
+   and count distinct entries. An action or trigger is proven **missing** only after a complete,
+   de-duplicated scan (distinct count = `paging.total`). Report the evidence ("scanned N distinct
+   of `paging.total` N"); without that proof say it was "not found in the installed catalog",
+   never that it is not installed. Either way, list the closest related entries you did find with
+   their returned `appId` + key and display name — don't omit them, and don't fetch their schemas
+   unless the user asks. A shortcut:
+   take the `appId` from a related action, then Resolve by `appId`.
+
+Discovery hints:
+
+- Search by concept with a keyword ladder ("chat" → "message"). Common aliases: send a chat
+  message to the contact = `send-message` (not `inbox-send-message`); a note about a contact in
+  the site owner's Inbox, nothing sent to the contact = `inbox-send-message` ("Show in Inbox");
+  email to anyone, incl. the site
+  owner = `triggered-emails` (never the deprecated `send-mail` / "Get an email"); task =
+  `createTask`; labels = `addLabelsToContact` / `remove_labels_to_contact`; create a contact =
+  `contacts-create_contact` (for triggers whose payload has no contact, e.g. webhooks).
+- Near-duplicates exist (`booking_canceled` vs `bookings_canceled`; new Wix Forms app vs legacy
+  "Form submitted"). Compare payload schemas and filters; prefer the one whose entities you can
+  actually find on the site (Automations Entity and Provider Configuration (not yet published)).
+- Enum-like fields often list legal values only in the field `description` (e.g. paymentStatus
+  NOT_PAID / PAID). Read descriptions before mapping user words; never invent enum values.
+
+## 7. Aggregated schema — computed locally (no API takes an unsaved graph)
+
+Node N may read the trigger payload + each **ancestor**'s output (under its namespace) +
+variables + identity enrichment. Recipe and fetch order: [Automations Graph and Data Model](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-graph-and-data-model) §4.
+
+## 8. Selector options and APIs with limitations
+
+> **Later stages only:** not available in stage 2; this section is published in stage 3.
+
+**In this stage:** a "draft" is an automation created `INACTIVE` (builder drafts are invisible to the public API). To validate a saved automation, Get it and Validate the returned object. Check expressions locally, then with Validate Automation.
+
+## Related API references
+
+- [Automations V2](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/introduction)
+- [Resolve Triggers](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/trigger-catalog/resolve-triggers)
+- [Resolve Actions](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-catalog/resolve-actions)
+- [Automation Email Action](https://dev.wix.com/docs/api-reference/business-management/marketing/emails/automation-email-action/introduction)

package/skills/wix-manage/references/automations/automation-model.md

@@ -0,0 +1,199 @@
+---
+name: "Automations Graph and Data Model"
+description: "Assemble builder-editable automation graphs with valid node relationships, namespaces and ancestor data access."
+---
+
+> **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).
+
+# Automation Model — Object, Graph Rules, Payload Scope
+
+**TL;DR**
+
+- An automation = one trigger + a **single-parent tree** of actions. `rootActionIds` has EXACTLY one id; every connection field holds AT MOST one id; no joins, no cycles, no orphans. Parallelism only via SPLIT; "both branches continue" = duplicate the downstream steps per branch (the builder caps an automation at 45 actions — count before duplicating).
+- Every action: `actions[k].id === k`, a fresh uuid v4, a unique `namespace` (except variable steps, which share `setVariable`), and ONLY its own type's `*Info` object.
+- The automation MUST render and be editable in the Wix dashboard builder. The builder rules below are hard MUSTs — the API accepts shapes the builder cannot draw (some hang its loader forever).
+- A step may read (`var("...")`) only its node's **aggregated payload schema**: trigger payload + identity enrichment + outputs of its ANCESTOR steps.
+- Create and Update do NOT validate. Always call Validate Automation before Create, a configuration Update or activation ([Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog)); status-only deactivation is exempt ([Automations Activation Status](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-activation-status)).
+
+---
+
+## 1. The Automation object (public API)
+
+> In this stage you create only APP_DEFINED steps. The other step types below are documented so you can read and preserve existing automations, not to author them here.
+
+| Field                         | Rules                                                                                                                                            |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`, `revision`              | Read-only. `revision` MUST be sent back on Update Automation (§6).                                                                               |
+| `name`                        | Required, 1–100 chars (API allows 500; the builder holds 100); the business outcome ("Send welcome email to new subscribers").                   |
+| `description`                 | Optional, ≤2000 chars.                                                                                                                           |
+| `origin`                      | Required on create, immutable. `USER` for anything you create. `APPLICATION`/`PREINSTALLED` carry update locks (§4 of Automations Feasibility and Planning (not yet published)). |
+| `settings`                    | Locks for APPLICATION/PREINSTALLED (`readonly`, `actionSettings`, …). Never set it on create; on Update send it back exactly as fetched.         |
+| `configuration.status`        | Required, `ACTIVE` \| `INACTIVE`. Create `INACTIVE`; activate only on request.                                                                   |
+| `configuration.trigger`       | `{appId, triggerKey, filters[], scheduledEventOffset?, overrideSchema?, automationConfigMapping?}` — [Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration).                                |
+| `configuration.rootActionIds` | Exactly one action id.                                                                                                                           |
+| `configuration.actions`       | Map `actionId → Action`.                                                                                                                         |
+
+Action (common fields):
+
+- `id` — uuid v4, equal to its map key.
+- `type` — `APP_DEFINED`, `CONDITION`, `CODE_CONDITION`, `DELAY`, `RATE_LIMIT`, `SET_VARIABLES`, `SPLIT` (the last two are not yet in the public API docs, but the builder supports them — Automations Delays Variables and Branches (not yet published)). NEVER `UNKNOWN_ACTION_TYPE`, NEVER `MERGE`.
+- `namespace` — 1–100 chars, unique except the shared `setVariable` namespace (§3). Outputs of this step appear under it.
+- `displayName` — optional but always set it: 1–60 chars, sentence case, purpose-specific (§7 of Automations Delays Variables and Branches (not yet published)). Absent → the canvas shows the catalog name.
+- `skipActionExpression` — absent (runs) or exactly `"{{true}}"` (skipped), the only value the builder writes. A skipped step adds NO outputs downstream (§4).
+- exactly one `*Info` matching `type`: `appDefinedInfo`, `conditionInfo`, `codeConditionInfo`, `delayInfo`, `rateLimitInfo`, `setVariablesInfo`, `splitInfo`.
+
+## 2. Graph invariants — single-parent tree
+
+1. **One root, with no parent.** `rootActionIds` = `[oneId]`, and no action may point at the root. The builder draws only `rootActionIds[0]`; extra roots are saved but invisible.
+2. **One successor per field.** `appDefinedInfo.postActionIds`, `delayInfo.postActionIds`, `rateLimitInfo.postActionIds`, `setVariablesInfo.postActionIds`, `conditionInfo/codeConditionInfo.truePostActionIds` / `falsePostActionIds` each hold 0 or 1 id (API `maxItems 1`).
+3. **One parent per action.** Every non-root action is referenced from exactly one place (one connection field or one SPLIT path). A JOIN is drawn under its first parent only — the canvas misrepresents the flow.
+4. **No orphans.** An action unreachable from the root is deleted by the builder on the next save.
+5. **No cycles.** Forward only.
+6. **Empty array = the path ends** there. Use `[]`, never omit the field.
+7. **Parallel fan-out only via SPLIT** (§5 of Automations Delays Variables and Branches (not yet published)). Never two root ids, never two ids in one field.
+8. **No MERGE.** The API has a `MERGE` type and `conditionInfo.mergeActionId`, but the canvas cannot draw them (MERGE nodes never finish loading). Never create either; when you read an automation that has them, preserve them untouched and don't add more.
+
+### Builder rendering MUSTs (graph level)
+
+- MUST: the trigger's `appId` + `triggerKey` exist in the site's trigger catalog (a missing trigger can leave every node loading).
+- MUST: `actions[k].id === k` for every entry.
+- MUST: ids are unique across ALL of: action ids, SPLIT path ids, the `triggerKey` string (it is the trigger node's id), and the builder's synthetic ids `<id>true`, `<id>false`, `<id>-end`, `<id>true-end`. Duplicates crash the layout. Generate every id as a fresh uuid v4 in code; never reuse ids from these references.
+- MUST: each action carries ONLY its own type's `*Info`. The canvas ignores `type` when finding children and takes the first present of `appDefinedInfo → delayInfo → rateLimitInfo → setVariablesInfo → condition` — even an empty leftover `appDefinedInfo: {postActionIds: []}` on a CONDITION hides both branches.
+- MUST: at most one RATE_LIMIT, and only as the root (§2 of Automations Delays Variables and Branches (not yet published)). A non-root RATE_LIMIT node spins forever.
+- MUST: APP_DEFINED `appId` + `actionKey` match the site's action catalog, else the node shows "Action not available".
+
+### Designing within the tree
+
+> **Later stages only:** not available in stage 2; this section is published in stage 3.
+
+**In this stage:** put independent actions ("create a task and add a label") in one linear chain A → B → C, most time-sensitive first.
+
+### Only model what the user asked for
+
+> **Later stages only:** not available in stage 2; this section is published in stage 3.
+
+**In this stage:** add only the steps the user asked for. Audience or copy framing ("a VIP follow-up for high-value customers") is content inside one action, not a condition.
+
+## 3. Namespaces
+
+Use the builder's own convention (it derives new indexes from the trailing number):
+
+| Type                                             | Namespace                                                |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| APP_DEFINED                                      | `<actionKey>-<N>` (e.g. `triggered-emails-3`)            |
+| CONDITION and CODE_CONDITION                     | `CONDITION-<N>`                                          |
+| DELAY / SPLIT / RATE_LIMIT                       | `<TYPE>-<N>` (e.g. `DELAY-2`, `SPLIT-5`, `RATE_LIMIT-1`) |
+| SET_VARIABLES (and existing code-variable steps) | always the literal `setVariable` (§4 of Automations Delays Variables and Branches (not yet published)) |
+
+`N` = 1 + the largest number after the last `-` among **all** the automation's namespaces (one counter shared across every step type — e.g. `DELAY-1` then `createTask-2`). A namespace with no trailing number (`setVariable`) doesn't count: if it is the only one, the next `N` is 1. A CODE_CONDITION keeps `CONDITION-<N>`. The builder never rewrites an existing namespace — on update keep every existing one as is. Variable and existing code-variable steps intentionally share `setVariable`; their distinct property keys are merged. For other output-producing actions, never reuse a namespace — the later output overwrites the earlier one.
+
+## 4. Aggregated payload schema — what `var()` can read at a node
+
+This section owns the rule. Build one JSON Schema object per node, in code, from the root down its own branch, from public schema APIs (calls: [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §3–§4).
+
+1. **Trigger payload** — the trigger's `payloadDataSchema` (custom/webhook triggers: `trigger.overrideSchema` instead, §3 of Automations Schemas and Scheduling (not yet published)). If the trigger implements dynamic schema, call Get Trigger Dynamic Schema with the SELECTED (saved) filter options and MERGE its `properties` over the static ones ([Automations Trigger Configuration](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-trigger-configuration) §5); before filters are chosen, dynamic fields are UNKNOWN, not absent. Trigger fields are un-prefixed: `var("orderId")`.
+2. **Identity enrichment** — for every trigger-payload field (any object depth, not inside arrays) annotated `identityType: "contact"` or `"member"`, a root-level object is added, keyed by that field's `namespace` annotation when it has one, else its (deprecated) `name` annotation, else the identity type (`contact` / `member`). Shape: Get Identities Schema (`identitiesSchema.properties.contact` / `.member`). Both stay valid: `var("contactId")` and `var("contact.name.first")`; also e.g. `var("contact.email")`, `var("member.profile.nickname")`. A field annotated `name: "post_author_member"` (some Blog / File Share triggers) is enriched as `var("post_author_member.profile.nickname")` — two member ids on one trigger give two objects; use the key the field declares (`member.*` does not exist there). Other identity types (e.g. `visitor`) add no object; webhook/custom triggers (override schema) get none. The builder does not enrich identity fields of action outputs — don't read `contact.*` that only an action output would provide.
+3. **Ancestor action outputs** — for each non-skipped APP_DEFINED step ABOVE this node on its own path, under `properties[<namespace>]`: catalog `outputSchema`, with `overrideOutputSchema.properties` merged over it, and — when the action implements dynamic output — Get Action Dynamic Output Schema (called with that step's final `inputMapping`) merged over that: `var("triggered-emails-3.messageId")`.
+4. **Variables** — titled outputs (`outputSchema`) of non-skipped ancestor SET_VARIABLES / code-variable (`namespace: "setVariable"`) steps, merged under `setVariable`: `var("setVariable.<key>")` (§4 of Automations Delays Variables and Branches (not yet published)).
+
+Scope rules:
+
+- Only ANCESTORS. A node never sees later steps or a sibling branch (true path can't read the false path; SPLIT paths can't read each other).
+- A skipped step (`skipActionExpression: "{{true}}"`) contributes nothing; never skip a step whose outputs a later step reads.
+- Resolution order — finalize an upstream node before computing a descendant's schema: trigger filters → the trigger's dynamic schema → for each step top-down: its dynamic input schema (if any) → its final `inputMapping` → its dynamic output schema (if any) → add it to its children's schema.
+- Every `var()` path MUST exist in this node's aggregated schema with a compatible type — never reason from a raw trigger or action schema alone, and never invent a field. Copy keys from the schema (titles/labels are not keys); arrays cannot be traversed by path ([Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions) §5).
+- Preferred-language messages: map `var("contact.locale")` into the email's dynamic content; no separate "language" field is needed.
+
+Syntax of expressions and the allowed function list: [Automations Mapping Expressions](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-mapping-expressions).
+
+## 5. Minimal valid examples
+
+### 5.1 Linear (trigger → two app-defined actions)
+
+The simplest shape: one trigger and a chain of APP_DEFINED actions linked by `postActionIds`.
+The trigger and action identities below are the Contacts "new contact created" trigger and the
+Tasks "create task" action; confirm them, and each action's input keys, against the site's
+catalog before use. Generate fresh uuid v4 action ids.
+
+```json
+{
+  "automation": {
+    "name": "New contact welcome tasks",
+    "origin": "USER",
+    "configuration": {
+      "status": "INACTIVE",
+      "trigger": {
+        "appId": "74bff718-5977-47f2-9e5f-a9fd0047fd1f",
+        "triggerKey": "contacts-new_contact_was_created",
+        "filters": []
+      },
+      "rootActionIds": ["3f6c1d2e-8a4b-4c7d-9e1f-2a3b4c5d6e01"],
+      "actions": {
+        "3f6c1d2e-8a4b-4c7d-9e1f-2a3b4c5d6e01": {
+          "id": "3f6c1d2e-8a4b-4c7d-9e1f-2a3b4c5d6e01",
+          "type": "APP_DEFINED",
+          "namespace": "createTask-1",
+          "displayName": "Create welcome task",
+          "appDefinedInfo": {
+            "appId": "146c0d71-352e-4464-9a03-2e868aabe7b9",
+            "actionKey": "createTask",
+            "inputMapping": {
+              "contactId": "{{var(\"contactId\")}}",
+              "title": "Welcome {{var(\"contact.name.first\")}}"
+            },
+            "postActionIds": ["3f6c1d2e-8a4b-4c7d-9e1f-2a3b4c5d6e02"]
+          }
+        },
+        "3f6c1d2e-8a4b-4c7d-9e1f-2a3b4c5d6e02": {
+          "id": "3f6c1d2e-8a4b-4c7d-9e1f-2a3b4c5d6e02",
+          "type": "APP_DEFINED",
+          "namespace": "createTask-2",
+          "displayName": "Create follow-up task",
+          "appDefinedInfo": {
+            "appId": "146c0d71-352e-4464-9a03-2e868aabe7b9",
+            "actionKey": "createTask",
+            "inputMapping": {
+              "contactId": "{{var(\"contactId\")}}",
+              "title": "Follow up with {{var(\"contact.name.first\")}}"
+            },
+            "postActionIds": []
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Why it's valid: one parentless root; each action has at most one successor and one parent; ids
+equal their keys; namespaces are unique per §3; inputMapping keys come from the input schema;
+every `var()` path is in that node's aggregated schema; status is INACTIVE.
+
+### 5.2 Branching (trigger → condition → two branches)
+
+> **Later stages only:** not available in stage 2; this section is published in stage 3.
+
+## 6. Persistence & update lifecycle
+
+Create `INACTIVE` (your "draft"); activate only on request. Create procedure and read-back: [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §3; calls: [Automations API Catalog](https://dev.wix.com/docs/api-reference/business-management/automations/skills/automations-api-catalog) §2.
+
+**Later stages only — not in stage 2:** **Update:** Get → change only what was asked, keep every other node byte-for-byte → Validate → Update with the full merged object + `revision`, `origin` and `settings` as fetched; on an ACTIVE automation the change is live — confirm first. Locks: §4 of Automations Feasibility and Planning (not yet published).
+
+## 7. Pre-validate self-check (do in code)
+
+Script the graph/id/namespace/`var()` items of [Build and Manage Wix Automations — included validation procedure](https://dev.wix.com/docs/api-reference/business-management/automations/skills/build-and-manage-wix-automations) §4 (items 1–4 and 11 — the rules of §2–§4 above: one parentless root, RATE_LIMIT only as that root, ≤1 id per connection, one parent each, no cycles/orphans/MERGE/`mergeActionId`/`UNKNOWN_ACTION_TYPE`, keys = ids, globally unique uuid v4s incl. SPLIT path ids, `triggerKey` and `<id>true/false/-end`, own `*Info` only, §3 namespaces unique except `setVariable`, every `var()` in THAT node's aggregated schema). Also check that only user-requested conditions/delays exist; then Validate Automation must return no trigger or action errors.
+
+## 8. Anti-patterns (all wrong)
+
+```text
+A → C ← B                          // join (two parents) — drawn under one parent
+Condition → true: X, false: X      // same id twice — duplicate X instead
+Condition.mergeActionId / MERGE    // not drawable — duplicate downstream steps
+Trigger → [A, B]                   // 2 roots — use a SPLIT
+A.postActionIds: [B, C]            // fan-out — use a SPLIT
+A → B → A                          // cycle
+D in actions, never referenced     // orphan — deleted on save
+RATE_LIMIT under anything          // node never finishes loading
+DELAY carrying a leftover appDefinedInfo  // wrong wiring
+Inventing a VIP condition from email copy wording
+```