@wix/agent-skills 1.30.0 → 1.31.1

package/skills/wix-headless-templates/storefront/seed/seed-store.mjs

@@ -12,13 +12,13 @@
 // Plan shape (see SEED.md):
 //   { "products": [{ "name", "description", "price", "compareAtPrice"?, "quantity",
 //                    "options"?: [{ "name", "type"?: "text"|"color",
-//                                   "choices": ["S","M"] | [{ "name", "colorCode"?, "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"? }] }],
+//                                   "choices": ["S","M"] | [{ "name", "colorCode"?, "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"? }] }],
 //                    "variantPrices"?: { "<choice name>": price },
 //                    "ribbon"?, "modifiers"?: [{ "name", "type"?: "choices"|"text", "mandatory"?,
 //                                              "choices"?: ["Gift wrap"], "maxChars"?, "minChars"? }],
 //                    "infoSections"?: [{ "title", "description" }],
 //                    "preorder"?: { "message"?, "limit"? },
-//                    "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"?,
+//                    "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"?,
 //                    "digitalFileUrl"? | "digitalFilePath"?, "digitalFileName"? }],
 //     "categories"?: { "<category name>": ["<product name>", ...] },
 //     "categoryDetails"?: { "<category name>": { "description"?, "imageUrl"? | "imagePath"? | "imagePrompt"? } } }
@@ -29,7 +29,7 @@
 import { setSiteCurrency } from "../../shared/seed/site.mjs";
 import { basename } from "node:path";
 import { readFileSync } from "node:fs";
-import { resolveItemImages } from "../../shared/seed/images.mjs";
+import { resolveItemImages, resolveItemImagesDetailed } from "../../shared/seed/images.mjs";
 import { seedSiteId } from "../../shared/seed/site-context.mjs";
 import { wixToken } from "../../shared/seed/wix-cli.mjs";
 
@@ -472,9 +472,11 @@ export async function addProductsToCategories(ctx, mapping) {
   }
 }
 
-// Bulk image attach in ONE call. items: [{ id, url, altText }] — no revision to pass: the
+// Bulk image attach in ONE call. items: [{ id, url, mediaId?, altText }] — no revision to pass: the
 // current revision is read right before the update, so attach any number of times, any pass.
-// Wix re-hosts each url server-side; the media can take a little while to appear on read-back
+// An item with a mediaId (a file already in this site's Media Manager) is attached by that id and
+// reused as it is; a bare url is re-hosted by Wix server-side, a new file each time. The media can
+// take a little while to appear on read-back
 // (propagation) — normal, not a failure.
 // The bulk update returns 200 on PARTIAL failure, like the bulk create: each item's outcome is
 // in results[].itemMetadata (success, error, originalIndex). Seen live (runs 85 and 86,
@@ -491,7 +493,8 @@ export async function addProductsToCategories(ctx, mapping) {
 // whose choices were linked (by this seed or by the owner in the dashboard) gets those links put
 // back right after.
 const sameFile = (a, b) => a && b && basename(a) === basename(b);
-const galleryHas = (items, url) => items.some((it) => sameFile(it.image?.filename, url) || sameFile(it.image?.url, url));
+// A file attached by id keeps its own display name as the item's filename, so it is found by id.
+const galleryHas = (items, url, mediaId) => items.some((it) => (mediaId && it.id === mediaId) || sameFile(it.image?.filename, url) || sameFile(it.image?.url, url));
 
 export async function attachProductImages(ctx, items) {
   if (!items?.length) return { attached: [], failures: [] };
@@ -508,9 +511,10 @@ export async function attachProductImages(ctx, items) {
       const p = byId.get(it.id);
       const current = p?.media?.itemsInfo?.items ?? [];
       const wanted = it.images ?? [{ url: it.url, altText: it.altText }];
-      const fresh = wanted.filter(({ url }) => !galleryHas(current, url));
+      const fresh = wanted.filter(({ url, mediaId }) => !galleryHas(current, url, mediaId));
       if (!fresh.length) { ok.add(it.id); continue; } // every image is already there
-      toSend.push({ it, p, items: [...current.map(({ id }) => ({ id })), ...fresh.map(({ url, altText }) => ({ url, altText }))] });
+      // A file already in the Media Manager goes in by its id: set by url, Stores imports a copy.
+      toSend.push({ it, p, items: [...current.map(({ id }) => ({ id })), ...fresh.map(({ url, mediaId, altText }) => (mediaId ? { id: mediaId, altText } : { url, altText }))] });
     }
     if (toSend.length) {
       const r = await req(ctx, "/stores/v3/bulk/products/update", {
@@ -558,7 +562,8 @@ function choiceLinksOf(p) {
 
 // Per-choice images (the dashboard's "image per colour"): a choice points at an item of the
 // product's OWN gallery, so the image is attached to the gallery first (pass 2) and linked here by
-// the gallery item's id — the id of the uploaded file is a different id and 400s. Links are a
+// the gallery item's id — for a file imported by url that is a different id from the uploaded
+// file's and the file's 400s; a file attached by its Media Manager id is the item of that id. Links are a
 // product update, which the API only accepts with the variants re-sent beside the options, so the
 // current variants (id, choices, price) ride along unchanged. Wix derives a variant's own media
 // from its choice at creation only; the storefront reads the choice's image, so a link made here
@@ -686,7 +691,7 @@ export async function setupStore(ctx, { products = [], categories = {}, category
   const planNames = new Set(products.map((p) => p.name));
   let all = [];
   try { all = await readAllProducts(ctx); } catch (e) { console.error(`catalog read failed (skipping the pre-existing check): ${String(e.message).slice(0, 120)}`); }
-  const preexisting = all.filter((p) => !planNames.has(p.name));
+  let preexisting = all.filter((p) => !planNames.has(p.name));
 
   // Idempotent by name: an errored bulk create (429/5xx) may still have applied server-side,
   // and SKILL.md tells the agent to re-run a failed seed — creating only the names that don't
@@ -735,17 +740,19 @@ export async function setupStore(ctx, { products = [], categories = {}, category
   const choiceSpecs = products.map((pl, i) =>
     (pl.options ?? []).flatMap((o) =>
       (o.choices ?? [])
-        .filter((c) => typeof c === "object" && c && (c.imageUrl || c.imagePath || c.imagePrompt))
+        .filter((c) => typeof c === "object" && c && (c.imageMediaId || c.imageUrl || c.imagePath || c.imagePrompt))
         .map((c) => ({
           optionName: o.name,
           choiceName: c.name,
+          productName: pl.name,
           altText: c.altText ?? `${pl.name} — ${c.name}`,
-          spec: { url: c.imageUrl, path: c.imagePath, prompt: c.imagePrompt, displayName: `${withNames[i].slug || "product"}-${String(c.name).toLowerCase().replace(/[^a-z0-9]+/g, "-")}.png` },
+          spec: { mediaId: c.imageMediaId, url: c.imageUrl, path: c.imagePath, prompt: c.imagePrompt, displayName: `${withNames[i].slug || "product"}-${String(c.name).toLowerCase().replace(/[^a-z0-9]+/g, "-")}.png` },
         })),
     ));
   const flatChoiceSpecs = choiceSpecs.flat();
-  const files = await resolveItemImages(ctx, [
+  const resolved = await resolveItemImagesDetailed(ctx, [
     ...withNames.map((p, i) => ({
+      mediaId: products[i]?.imageMediaId,
       url: products[i]?.imageUrl,
       path: products[i]?.imagePath,
       prompt: products[i]?.imagePrompt,
@@ -753,7 +760,9 @@ export async function setupStore(ctx, { products = [], categories = {}, category
     })),
     ...flatChoiceSpecs.map((c) => c.spec),
   ]);
+  const files = resolved.map((r) => r.file);
   const choiceFiles = files.slice(withNames.length);
+  const choiceResolved = resolved.slice(withNames.length);
   let cursor = 0;
   const choiceLinks = choiceSpecs.map((specs) =>
     specs.map((c) => ({ ...c, file: choiceFiles[cursor++] })).filter((c) => c.file));
@@ -763,8 +772,8 @@ export async function setupStore(ctx, { products = [], categories = {}, category
     .map((p, i) => {
       if (!p.id) return null;
       const images = [
-        ...(files[i] ? [{ url: files[i].url, altText: products[i]?.altText ?? p.slug }] : []),
-        ...choiceLinks[i].map((c) => ({ url: c.file.url, altText: c.altText })),
+        ...(files[i] ? [{ url: files[i].url, mediaId: files[i].existing ? files[i].id : undefined, altText: products[i]?.altText ?? p.slug }] : []),
+        ...choiceLinks[i].map((c) => ({ url: c.file.url, mediaId: c.file.existing ? c.file.id : undefined, altText: c.altText })),
       ];
       return images.length ? { id: p.id, images } : null;
     })
@@ -774,6 +783,15 @@ export async function setupStore(ctx, { products = [], categories = {}, category
   // the same plan reuses the products and attaches again.
   let imagesAttached = 0;
   const imageFailures = [];
+  // A product whose image never resolved (a bad path, an unsupported file type, a refused
+  // prompt, a timeout) is not in imageItems at all, so the attach step below never sees it:
+  // it is reported here with the resolver's reason, or it ships text-only in silence.
+  withNames.forEach((p, i) => {
+    const src = products[i] ?? {};
+    if ((src.imageMediaId || src.imageUrl || src.imagePath || src.imagePrompt) && !files[i]) {
+      imageFailures.push({ name: p.name, error: resolved[i]?.error ?? "image did not resolve" });
+    }
+  });
   const nameOf = (id) => withNames.find((p) => p.id === id)?.name;
   try {
     if (imageItems.length) {
@@ -788,11 +806,15 @@ export async function setupStore(ctx, { products = [], categories = {}, category
   // Pass 3 — link each choice's image to its choice, by the gallery item's id.
   let choiceImagesLinked = 0;
   const choiceImageFailures = [];
+  flatChoiceSpecs.forEach((c, j) => {
+    if (!choiceFiles[j]) choiceImageFailures.push({ name: c.productName, choice: c.choiceName, error: choiceResolved[j]?.error ?? "image did not resolve" });
+  });
   for (const [i, p] of withNames.entries()) {
     const links = choiceLinks[i];
     if (!links.length || !p.id || !imagesAttached) continue;
     try {
-      const r = await linkChoiceImages(ctx, p.id, links.map((c) => ({ optionName: c.optionName, choiceName: c.choiceName, url: c.file.url })));
+      // a file attached by its Media Manager id is the gallery item of that id; an imported one is found by name
+      const r = await linkChoiceImages(ctx, p.id, links.map((c) => ({ optionName: c.optionName, choiceName: c.choiceName, ...(c.file.existing ? { mediaId: c.file.id } : { url: c.file.url }) })));
       choiceImagesLinked += r.linked;
       for (const m of r.missing) choiceImageFailures.push({ name: p.name, choice: m, error: "image not in the product gallery" });
     } catch (e) {
@@ -800,6 +822,17 @@ export async function setupStore(ctx, { products = [], categories = {}, category
     }
   }
 
+  // The pre-existing list is read again now: on a fresh site the Stores app was installed moments
+  // before the first read, and Wix creates its sample catalog asynchronously after the install, so
+  // that read often came back empty and the closing message said nothing about a dozen samples the
+  // live shop lists. The early read still serves the idempotency check above; this one serves the report.
+  try {
+    const after = await readAllProducts(ctx);
+    preexisting = after.filter((p) => !planNames.has(p.name));
+  } catch (e) {
+    console.error(`catalog re-read failed (reporting the pre-existing list from the first read): ${String(e.message).slice(0, 120)}`);
+  }
+
   // failures is part of the result, not an exception: a partial seed still leaves a usable
   // store, and the agent needs the names to report rather than silently shipping a short
   // catalog. Re-run the seed to retry them — existing names are skipped, not duplicated.

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "REST recipes to configure and manage a Wix site's business solutions — stores, bookings, payments, CMS, and more. Open the matching recipe for the exact endpoint, method, and payload before calling — never guess a Wix API, never write Wix dashboard URL from memory. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, custom-apps, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, google-business-profile, analytics, accessibility, seo, dashboard-navigation."
+description: "REST recipes to configure and manage a Wix site's business solutions — stores, bookings, payments, CMS, and more. Open the matching recipe for the exact endpoint, method, and payload before calling — never guess a Wix API, never write Wix dashboard URL from memory. Routes to: automations, stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, custom-apps, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, google-business-profile, analytics, accessibility, seo, dashboard-navigation."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -37,7 +37,7 @@ Lists all apps installed on a site using Apps Installer API. Useful for verifyin
 ## Custom Apps
 
 ### [Use App Skills and App Tools](references/custom-apps/use-app-skills-and-app-tools.md)
-"Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
+"Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use every time a site has custom apps installed, before acting on the user's request: knowing which apps are installed doesn't tell what they can do, so only this skill's discovery calls show whether one of them handles the request. Also use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
 
 ---
 
@@ -96,19 +96,7 @@ Sets up booking policies, cancellation rules, and waitlist configuration using t
 "Creates staff members and configures custom working hours using Staff API + Calendar Events API. Critical two-step process: create staff → assign schedule → create working hours events."
 
 ### [Create and Update Booking Services](references/bookings/create-and-update-booking-services.md)
-Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
-
-### [Create Booking Service from Prompt](references/bookings/create-booking-service-from-prompt.md)
-"Create a booking service from a user prompt — e.g. 'create a yoga class for $50', 'set up consultations for $75', 'add a personal training appointment', 'create a 6-week photography workshop', 'create a hidden free test course with 8 online sessions'. Determines the service type (APPOINTMENT, CLASS, or COURSE) and delegates to the type-specific recipe. For COURSE services with session dates/counts, follow the course recipe's separate Calendar bulkCreateEvents step; Services V2 alone does not create bookable course sessions."
-
-### [Create Appointment Service](references/bookings/create-appointment-service.md)
-"Create an appointment booking service — e.g. 'set up consultations', 'create a 1-on-1 session', 'add a personal training appointment', 'create a meeting service for $25'. Handles staff assignment (required), session duration, pricing, and 1-on-1 capacity defaults via bulkCreateServices API."
-
-### [Create Class Service](references/bookings/create-class-service.md)
-"Create a class booking service — e.g. 'create a yoga class for $50', 'set up a pilates class', 'add a group fitness session', 'create a weekly meditation class'. Handles group capacity, recurring session defaults, and pricing via bulkCreateServices API. Staff assignment is not used for classes."
-
-### [Create Course Service](references/bookings/create-course-service.md)
-"Create a course booking service — e.g. 'create a 6-week photography workshop', 'set up a training program', 'add a bootcamp course for $300', 'create a hidden free test course with 8 sessions'. Handles group capacity, full-course pricing, bulkCreateServices, and separate course session events via bulkCreateEvents. Staff assignment is not used for courses."
+"Creates and updates Wix Bookings services of every type — appointments, classes and courses — from a plain request such as 'a 60-minute consultation for $75', 'a yoga class for 12 people every Tuesday' or 'a 6-week photography course'. Covers choosing the service type, defaults for what the request leaves out, pricing (free, fixed, free-to-paid), staff, capacity, duration, categories, visibility, images, scheduling class and course sessions on the calendar, and changing existing services."
 
 ### [Check Bookings Availability (and Diagnose Issues)](references/bookings/diagnose-availability-issues.md)
 "Answers whether an appointment-based Wix Bookings service currently has bookable availability — the primary question — and diagnoses the cause only when there's no availability or the owner asks why. To diagnose, first rules out service-level blockers the availability endpoint can't see (service hidden, online booking off), then runs DiagnoseAvailability for ordered, machine-readable staff/setup reasons, with a manual fallback for booking-policy and capacity causes. Use when someone asks whether a service has availability, or why a service shows no times / customers can't book it."
@@ -419,6 +407,9 @@ List, count, and find the sites in a Wix account. Covers the namespace filter fo
 ### [Read Account or Site Context](references/sites/read-site-context.md)
 Probe a Wix site or account for full context in one call — installed apps by display name, locale, currency, timezone, and status. Account token + siteId targets one site; account token alone returns up to 10; site-scoped token alone returns the site it is scoped to.
 
+### [Send Feedback to Wix](references/sites/send-feedback-to-wix.md)
+Relay the user's feedback about building with Wix — the APIs, docs, recipes, Wix MCP and tooling — to Wix, attributed to the authenticated user. Covers when to offer it, how to compose a message Wix can act on, and the call that sends it. Use when the user asks to report something to Wix, is frustrated with a Wix API or flow, or a recipe's flow fell short. Not a support channel, and not for the user's own site content.
+
 ### [Site Import](references/sites/site-import.md)
 Drive the Wix Site Import agent to migrate an existing store or site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix — as a brand-new site or into the user's existing one — or to import from CSV/TSV export files with no source site. Use this skill whenever the user wants to import, migrate, or clone a store/site into Wix, mentions moving off Shopify/WooCommerce/Magento, or gives a source store URL and asks to bring it into Wix. Covers starting the import, polling progress, answering the agent's mid-import questions, handling deploy/failure/auth-expiry states, and sending post-deploy follow-up changes.
 
@@ -458,3 +449,22 @@ Modifies existing products and variants using Catalog V3 Products API. Covers ad
 
 ### [Stores Dashboard Navigation](references/stores/stores-dashboard-navigation.md)
 "Builds direct links to Wix Stores and eCommerce dashboard pages on manage.wix.com — products list, edit a specific product, categories, inventory, orders list, a specific order, abandoned checkouts, gift cards, shipping and tax settings. Pairs each main Stores/eCommerce entity with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+
+<!-- automations-builder-sync:begin -->
+## Automations
+
+### [Build and Manage Wix Automations](references/automations/build-and-manage-automations.md)
+Discover installed automation triggers and actions and inspect an automation’s current active status without changing site data.
+
+<details>
+<summary>Internal skills (loaded on demand by Build and Manage Wix Automations — do NOT use directly)</summary>
+
+- [Automations API Catalog](references/automations/api-catalog.md)
+  Discover installed automation triggers and actions and inspect their schemas through site-scoped public catalog APIs.
+
+- [Automations Activation Status](references/automations/activation-status.md)
+  Read an automation’s current ACTIVE or INACTIVE status and distinguish it from historical run outcomes.
+
+</details>
+
+<!-- automations-builder-sync:end -->

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

@@ -0,0 +1,52 @@
+---
+name: "Automations Activation Status"
+description: "Read an automation’s current ACTIVE or INACTIVE status and distinguish it from historical run outcomes."
+---
+
+# Inspect activation status
+
+An automation's current state is `configuration.status`: ACTIVE is eligible for new trigger
+events; INACTIVE is not. Neither value proves that a historical run succeeded or that a
+pending activation has stopped.
+
+1. Resolve the requested name with one Query Automations call filtered by that exact name
+   (below); don't page through other automations. If the ID is already supplied, go to Get.
+   If several match, open your answer by listing each match's full returned ID and asking
+   which one the user means; don't report a single status. If none match, say so and ask the
+   user to check the name or site; never guess an ID.
+2. Get the matching returned ID and read `configuration.status`.
+3. Answer briefly and completely in one reply. Start with the automation's exact name, its
+   returned ID and ACTIVE/INACTIVE from that response, then say what it means for new trigger
+   events. If the user asks whether the status says anything about past runs, answer it
+   directly in the next sentence: status does not show whether past runs succeeded; they are
+   visible in the automation's activity view in the site dashboard.
+4. If Get returns not found, do not state a status. Open with: the automation wasn't found on
+   this site, so its status can't be determined, and ask the user to confirm the site and the
+   automation ID. This question is required. Then give the possible causes below.
+
+Use an authorized site-scoped client with Set Up Automations permission. REST calls use
+`Authorization: <token>`. An API key also needs `wix-site-id: <metaSiteId>`; do not combine it
+with `wix-account-id`. Never print credentials.
+
+`POST https://www.wixapis.com/automations-service/v2/automations/query`
+
+```json
+{"query":{"filter":{"name":"<automation name>"},"cursorPaging":{"limit":25}}}
+```
+
+Read `automations[]` and `pagingMetadata.cursors.next`; continue pages if needed. Retain the
+returned `id` and exact name. Then:
+
+`GET https://www.wixapis.com/automations-service/v2/automations/<automationId>`
+
+Read `automation.configuration.status` from the Get response. Never infer status from the
+name or a previous mutation. Do not validate, change configuration, toggle status or test-run
+an automation to answer this read-only request.
+
+Not-found causes (step 4): unpublished builder drafts do not appear
+through this API, but a 404 can also mean deletion or a changed ID after overriding a
+preinstalled automation. When the user's history supports an unpublished builder draft as the
+cause, ask the owner to publish or discard it rather than reproducing its edits.
+
+Official contracts: [Query Automations](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/query-automations),
+[Get Automation](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/get-automation).

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

@@ -0,0 +1,81 @@
+---
+name: "Automations API Catalog"
+description: "Discover installed automation triggers and actions and inspect their schemas through site-scoped public catalog APIs."
+---
+
+# 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).

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

@@ -0,0 +1,34 @@
+---
+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."
+---
+
+# 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.
+
+| Request | Load |
+| --- | --- |
+| 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.