@wix/agent-skills 1.29.0 → 1.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

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

@@ -23,11 +23,13 @@ doesn't express — or once the site exists and the work turns to managing or ex
 
 - **Shipped code is the implementation.** Every vertical ships in the repository's
   `wix-headless-templates` skill (`skills/wix-headless-templates/<vertical>/`), not in this skill's
-  folder: `node <SKILL_ROOT>/install/templates.mjs`
-  fetches all of it once into `<SKILL_ROOT>/templates/` (a second) and prints the path; every
-  script below fetches it itself when the folder is missing. The folder stays with the project
-  (only the composed `project/` scaffolds are left out of its repository), so a later session
-  reads the version the project was built from. Each vertical holds:
+  folder. `node <SKILL_ROOT>/install/templates.mjs` prints where that skill is: the sibling folder
+  `<SKILL_ROOT>/../wix-headless-templates/` when the install carried both skills (the cold start
+  does), else a one-time fetch into `<SKILL_ROOT>/templates/` (a second); every script below
+  resolves it the same way. **Every `templates/...` path in this document is relative to that
+  printed root** — there is no `templates/` folder inside this skill when the sibling exists.
+  The folder stays with the project (only the composed `project/` scaffolds are left out of its
+  repository), so a later session reads the version the project was built from. Each vertical holds:
   - `app/` — the framework-agnostic core (TypeScript): a data layer that returns **plain,
     serializable DTOs** (images resolved to https URLs, prices pre-formatted), React hooks, and
     routing-free headless components. Works in Astro islands, Vite SPAs, and Next.
@@ -251,9 +253,7 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    INSTRUCTIONS and the shared floors — `templates/shared/DESIGN.md` +
    `templates/shared/CONTENT.md` — now (not earlier — their contracts matter only from this
    step on); the hook/DTO
-   contracts are inlined there, so don't open the shipped files themselves. **Author your
-   surfaces in as few messages as possible** — batch multiple Write calls in one message
-   (components are independent files); don't pay a round-trip per file.
+   contracts are inlined there, so don't open the shipped files themselves.
    If the brief needs a core operation that shipped code does not cover, read
    `templates/shared/CUSTOM_OPERATIONS.md` before writing it. Use one documented path and
    implement it; do not reverse-engineer SDK internals.
@@ -284,7 +284,9 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    that fix it: **Accept payments** `https://manage.wix.com/dashboard/<siteId>/wix-cashier/payments`
    (connect a payment method; "manual payments" is enough for free and pay-in-person flows) and
    **Upgrade the plan** `https://www.wix.com/upgrade/website?metaSiteId=<siteId>` (online payments
-   need a premium plan). Both are the owner's steps, not a defect in the site. **Copy the live URL verbatim from the
+   need a premium plan). Both are the owner's steps, not a defect in the site. When the run started
+   from the owner's own pages, name what those pages promised that the released site does not do.
+   **Copy the live URL verbatim from the
    `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
    a 404). Before you sign off, run the feedback self-check over the whole session
    (`guides/feedback.md`): anything that cost more turns than it should have, including what you
@@ -303,7 +305,7 @@ how to close such a run. A public site is still better served by managed Astro;
 close.
 
 Without a machine at all, or when the install, the CLI or the login is blocked where you are,
-read `<SKILL_ROOT>/guides/no-machine.md`: the same run, step by step, as the Wix API calls the
+read `<SKILL_ROOT>/guides/api-run.md`: the same run, step by step, as the Wix API calls the
 scripts make and the files beside this skill that carry the contracts.
 
 ## Verticals

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

@@ -0,0 +1,123 @@
+# The kit's run as Wix API calls
+
+Read when the commands this skill is built on cannot run where you are, or stopped: no shell, no
+file system, a sandbox that blocks the install, the CLI or the login, or a host that only talks to
+Wix through the Wix MCP. It walks the run of SKILL.md step by step and names, for each, the Wix
+API call the CLI or the script performs and the file beside this skill that carries the contract;
+where a script can run where you are, it says so.
+
+## Where these skills are
+
+This skill is one of a set, and the guide reads from three of them:
+
+- `{SKILL_ROOT}` — this skill, `wix-headless-kit`: the run, its guides, the Verticals table.
+- `{TEMPLATES}` — `wix-headless-templates`: the shipped, verified code per Wix Business Solution,
+  one folder each, with its `INSTRUCTIONS.md` (the contracts), `seed/` (the seed script and
+  `SEED.md`) and `rest/` (the data layer over plain `fetch`). Installed beside this skill, or
+  fetched to `{SKILL_ROOT}/templates/`.
+- `{MANAGE}` — `wix-manage`: REST recipes to configure and manage a site's business solutions, one
+  recipe per operation with the exact endpoint and payload; its `SKILL.md` is the index.
+- `{DOCS}` — `wix-docs`: how to look up the Wix API and SDK documentation and confirm a method's
+  exact shape before writing a call.
+
+Installed, they sit beside each other under `.agents/skills/`. Online, they are published alongside
+each other under the same names, each with a manifest of its files, and in the `wix/skills`
+repository on GitHub under `skills/{skill}/`; a sandbox that reaches GitHub has the whole set on
+disk from a clone.
+
+What such a run does not produce: the Astro build and its release. Those need a machine with the
+CLI. Everything else the kit does to a site, it does through calls you can make.
+
+## 0. Identity
+
+Every call below runs as the site owner, with whatever identity your host gives you: the Wix
+MCP's `ExecuteWixAPI` carries the user's login; an API key from the user's account goes in the
+`Authorization` header of any call, as `{MANAGE}/SKILL.md` describes; a site token from the Wix CLI
+works the same way when the user runs the CLI for you. The site's OAuth app (`client_id`) mints
+visitor tokens only, which cover what a visitor may see and nothing here.
+
+## 1. The brief → the solutions
+
+Unchanged from SKILL.md step 2 and its Verticals table: the brief names the business, the table
+names the solutions it needs. Read each solution's `{TEMPLATES}/{solution}/INSTRUCTIONS.md` for
+what it covers and `{TEMPLATES}/{solution}/seed/SEED.md` for what a seeded site holds.
+
+## 2. The site
+
+The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
+with `origin: agent-<your-id>`, a name, and the solutions to install as `seedOptions`. The recipe
+is `{MANAGE}/references/sites/create-headless-site.md`; it returns the `metaSiteId` and the
+site's OAuth client `appId`. Do not create a site any other way: a project from Create Project or
+a template is neither headless nor publishable, and a later run with a machine cannot attach to it.
+
+A site that already exists (the brief names it) is read first, never seeded unasked: SKILL.md
+step 2 and `{SKILL_ROOT}/guides/existing-site.md` apply as written.
+
+## 3. The apps
+
+A solution the provision call did not install, or a capability's app (Members Area, Forms,
+Restaurants, Donations, FAQ), goes on with the Apps Installer:
+`{MANAGE}/references/app-installation/install-wix-apps.md`. The app ids are in each
+`seed-{solution}.mjs`, which installs them before seeding.
+
+## 4. The seed
+
+`seed-{solution}.mjs` is a sequence of REST calls, and `SEED.md` is its contract: the plan shape
+(what to create, how many, which images), the order the entities need, and the traps the script
+encodes (a Bookings service needs a category to be visible and takes resource ids, not staff ids;
+a Forms field is registered by its `validation` block; a product's choice photos are linked after
+the gallery holds them). Read `SEED.md`, read the script for any call `SEED.md` only names, and make the same
+calls through `{MANAGE}`'s recipe for each (services, products, posts, events, collections). Keep
+the script's rules: create, never delete, and report what the site already held. Image prompts
+need the Media Manager; without it, products and services stay text-only, say so.
+
+## 5. The frontend
+
+The Astro pages cannot be released here: that is a run with a machine and a CLI login, which
+attaches to this site (`guides/existing-site.md`) rather than making a new one. What ships from here
+is static files, dropped onto the site from step 2 through
+`{MANAGE}/references/sites/upload-static-site.md`. Which files depends on whether the compose can
+run.
+
+**When the compose can run** (the skills on disk and Node), the frontend is the kit's own shipped code. The compose
+`{SKILL_ROOT}/install/deploy.mjs {solution} --stack static --out site --client-id {appId}` fetches the
+templates and writes the solution's REST data layer and stores to `site/js/wix/` as plain ES modules
+(`guides/reference-mode.md`, the static site): the transport, the cores, the state machines, verified,
+with the `.ts` beside each `.js` for reading. You write the pages and the rendering on those stores,
+imported relative to `site/` in a `<script type="module">`, and nothing of the data layer. The drop
+takes the complete file set in one call and a response has a hard size limit; the recipe's "Change it
+later" section downloads what the site serves, so a later drop adds files to a live set without
+resending what is already there.
+
+**When it cannot**, a page that loads the Wix SDK from a package CDN and talks to the site as a
+visitor. A few files at most, each written in full before it is dropped; the same size limit and
+the same way to add files to a live set apply. The
+SDK comes from a pinned package URL, `https://esm.sh/@wix/sdk@{version}` and the solution's package
+(`@wix/bookings`, `@wix/stores`, `@wix/blog`, …); the client is
+`createClient({ modules: { … }, auth: OAuthStrategy({ clientId }) })` with the `appId` the provision
+call returned, and the SDK mints and refreshes the visitor token itself. Markup, a render function
+per state, the event handlers: that is what you write. Keep what the page shows to what the site
+holds; nothing invented, as in SKILL.md step 4.
+
+**The calls**, on that second path, take their shape from the kit's own transport for the solution,
+`{TEMPLATES}/{solution}/app/wix/{solution}/*.ts` (`services.ts`, `booking.ts`, `catalog.ts`, …,
+with `{TEMPLATES}/shared/app/wix/sdk.ts` for the client wiring): those files call the same SDK
+modules the page imports, and they are verified. Copy the form of the call, not the file. The
+cores beside them (`*-core.ts`) hold the rules the page needs and nothing else does: which fields
+to read, how a price or a duration is formatted, which slot is bookable, how an id is read.
+
+**A call those files don't cover** is confirmed before it is written, the way `{DOCS}` describes:
+the method's SDK page, and when the page and the package disagree, the package's own type
+declarations (the `@wix/auto_sdk_{solution}_<module>` package the solution package depends on,
+its `index.d.ts`) are the truth. Two shapes that recur, as examples of what the types settle and
+the kit's files already encode: SDK query methods return a query builder finished with `.find()`;
+and an entity's id arrives as `_id` on some objects and `id` on others (the kit reads both,
+`rawId`). Dates travel as local wall-clock strings in the business time zone. A page cannot be run
+here, so a wrong shape fails silently in the browser; the file beside the skill is the check that is
+available.
+
+## 6. Closing
+
+SKILL.md step 5's closing, with two additions: the site id, so a run with a machine attaches to this
+site (`guides/existing-site.md`) instead of making a new one; and, when files were dropped, that a
+change re-drops the whole set.

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.29.0"
+    "ref": "v1.31.0"
   }
 }

package/skills/wix-headless-templates/shared/seed/images.mjs

@@ -151,10 +151,13 @@ export async function importImage(ctx, url, displayName = "image.png") {
  * THE seed entry point. Resolves a batch of image specs to Wix Media files in ONE parallel
  * wave. Each spec: { path } (LOCAL file — the user's own asset, uploaded) OR { url }
  * (verified external URL — imported) OR { prompt } (generated, ~1 credit) — plus optional
- * displayName, width, height. Returns an array aligned with the input: { id, url } per
- * success, null per failure or empty spec. Never throws.
+ * displayName, width, height. Returns an array aligned with the input: { file, error } per
+ * spec — `file` is { id, url } on success and null otherwise; `error` is the reason it is null
+ * (the thrown message, "empty spec", or "timed out"). Never throws. Every failure is also
+ * printed to stderr, so a seed log names the image and the reason even when the seed's
+ * own report does not.
  */
-export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
+export async function resolveItemImagesDetailed(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
   // unref: the budget timer must never keep the seed process alive after the work is done —
   // a lingering timer delays the seed's exit (and the run's .seed-exit marker) by the budget.
   const deadline = new Promise((r) => {
@@ -179,5 +182,22 @@ export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000
       return Promise.race([resolve, deadline]);
     }),
   );
-  return results.map((r) => (r.status === "fulfilled" ? r.value : null));
+  return results.map((r, i) => {
+    const spec = specs?.[i] ?? {};
+    const label = spec.displayName ?? spec.path ?? spec.url ?? (spec.prompt ? "(prompt)" : "(empty)");
+    if (r.status === "fulfilled") {
+      if (r.value) return { file: r.value, error: null };
+      const error = !spec.path && !spec.url && !spec.prompt ? "empty spec" : `timed out after ${perImageBudgetMs} ms`;
+      if (error !== "empty spec") console.error(`image ${label}: ${error}`);
+      return { file: null, error };
+    }
+    const error = r.reason?.message ?? String(r.reason);
+    console.error(`image ${label}: ${error.slice(0, 200)}`);
+    return { file: null, error };
+  });
+}
+
+/** The plain array of { id, url } | null the seeds consume today; failures are still printed. */
+export async function resolveItemImages(ctx, specs, opts) {
+  return (await resolveItemImagesDetailed(ctx, specs, opts)).map((r) => r.file);
 }

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

@@ -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";
 
@@ -686,7 +686,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
@@ -739,12 +739,13 @@ export async function setupStore(ctx, { products = [], categories = {}, category
         .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` },
         })),
     ));
   const flatChoiceSpecs = choiceSpecs.flat();
-  const files = await resolveItemImages(ctx, [
+  const resolved = await resolveItemImagesDetailed(ctx, [
     ...withNames.map((p, i) => ({
       url: products[i]?.imageUrl,
       path: products[i]?.imagePath,
@@ -753,7 +754,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));
@@ -774,6 +777,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.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,6 +800,9 @@ 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;
@@ -800,6 +815,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-vibe-headless/platforms/base44-ecom-light-seed-with-install.md

@@ -112,7 +112,13 @@ fails. You can finish without waiting for those images or replacing their placeh
 
 **Never paste a Wix dashboard link or path.**
 
-**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. Use its handoff guidance, note that the seeded catalog is mock data they can edit, replace or delete, and state any requested workflows that remain unfinished and what is needed to complete them.
+**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders, inventory and payments?", prefer_dashboard=true)`. Use its handoff guidance, note that the seeded catalog is mock data they can edit, replace or delete, and state any requested workflows that remain unfinished and what is needed to complete them.
+
+**A payment ask is a store ask.** The store carries its own checkout, in every region, so
+nothing separate connects payments and no payment provider is installed alongside it — send
+the user to the same dashboard page the handoff call names. A note that Base44 Payments /
+Wix Payments is unavailable in their region is about a provider installed into the app, and
+says nothing about their store's checkout.
 
 ## Additional Wix functionality
 

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed.md

@@ -106,7 +106,13 @@ fails. You can finish without waiting for those images or replacing their placeh
 
 **Never paste a Wix dashboard link or path.**
 
-**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. Use its handoff guidance, note that the seeded catalog is mock data they can edit, replace or delete, and state any requested workflows that remain unfinished and what is needed to complete them.
+**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders, inventory and payments?", prefer_dashboard=true)`. Use its handoff guidance, note that the seeded catalog is mock data they can edit, replace or delete, and state any requested workflows that remain unfinished and what is needed to complete them.
+
+**A payment ask is a store ask.** The store carries its own checkout, in every region, so
+nothing separate connects payments and no payment provider is installed alongside it — send
+the user to the same dashboard page the handoff call names. A note that Base44 Payments /
+Wix Payments is unavailable in their region is about a provider installed into the app, and
+says nothing about their store's checkout.
 
 ## Additional Wix functionality
 

package/skills/wix-vibe-headless/platforms/base44-ecom-light.md

@@ -72,7 +72,13 @@ fails. You can finish without waiting for those images or replacing their placeh
 
 **Never paste a Wix dashboard link or path.**
 
-**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. Use its handoff guidance, state any requested workflows that remain unfinished and what is needed to complete them.
+**Before writing your final text response, make one handoff call** — `search_base44_docs(query="how do I manage my store's products, orders, inventory and payments?", prefer_dashboard=true)`. Use its handoff guidance, state any requested workflows that remain unfinished and what is needed to complete them.
+
+**A payment ask is a store ask.** The store carries its own checkout, in every region, so
+nothing separate connects payments and no payment provider is installed alongside it — send
+the user to the same dashboard page the handoff call names. A note that Base44 Payments /
+Wix Payments is unavailable in their region is about a provider installed into the app, and
+says nothing about their store's checkout.
 
 ## Additional Wix functionality
 

package/skills/wix-headless-kit/guides/no-machine.md

@@ -1,115 +0,0 @@
-# No machine: the kit's run through the Wix APIs
-
-Read when you cannot run the commands this skill is built on: no shell, no file system, no Node, a
-sandbox that blocks the install, the CLI or the login, or a host that only talks to Wix through
-the Wix MCP. Nothing in this guide installs, downloads or runs anything. It walks the run of
-SKILL.md step by step and names, for each, the Wix API call the CLI or the script performs, and
-the file beside this skill that carries the contract.
-
-## Where these skills are
-
-This skill is one of a set, and the guide reads from three of them:
-
-- `<SKILL_ROOT>` — this skill, `wix-headless-kit`: the run, its guides, the Verticals table.
-- `<TEMPLATES>` — `wix-headless-templates`: the shipped, verified code per Wix Business Solution,
-  one folder each, with its `INSTRUCTIONS.md` (the contracts), `seed/` (the seed script and
-  `SEED.md`) and `rest/` (the data layer over plain `fetch`). Installed beside this skill, or
-  fetched to `<SKILL_ROOT>/templates/`.
-- `<MANAGE>` — `wix-manage`: REST recipes to configure and manage a site's business solutions, one
-  recipe per operation with the exact endpoint and payload; its `SKILL.md` is the index.
-- `<DOCS>` — `wix-docs`: how to look up the Wix API and SDK documentation and confirm a method's
-  exact shape before writing a call.
-
-They install together and sit beside each other. When you are reading this skill online rather
-than from an install, the others are published alongside it, by those names, and each skill's
-manifest lists its files. Read each file in full: a fetch tool that summarizes drops the exact
-calls and shapes; a tool that returns the file's text, or one that runs code and can fetch a URL,
-does not.
-
-Two things such a run does not produce, and never claims: a frontend built from the shipped `app/`
-code (that needs a build), and a release of one. Everything else the kit does to a site, it does
-through calls you can make.
-
-## 0. Identity
-
-Every call below runs as the site owner, with whatever identity your host gives you: the Wix
-MCP's `ExecuteWixAPI` carries the user's login; an API key from the user's account goes in the
-`Authorization` header of any call, as `<MANAGE>/SKILL.md` describes; a site token from the Wix CLI
-works the same way when the user runs the CLI for you. The site's OAuth app (`client_id`) mints
-visitor tokens only, which cover what a visitor may see and nothing here.
-
-## 1. The brief → the solutions
-
-Unchanged from SKILL.md step 2 and its Verticals table: the brief names the business, the table
-names the solutions it needs. Read each solution's `<TEMPLATES>/<solution>/INSTRUCTIONS.md` for
-what it covers and `<TEMPLATES>/<solution>/seed/SEED.md` for what a seeded site holds.
-
-## 2. The site
-
-The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
-with `origin: agent-<your-id>`, a name, and the solutions to install as `seedOptions`. The recipe
-is `<MANAGE>/references/sites/create-headless-site.md`; it returns the `metaSiteId` and the
-site's OAuth client `appId`. Do not create a site any other way: a project from Create Project or
-a template is neither headless nor publishable, and a later run with a machine cannot attach to it.
-
-A site that already exists (the brief names it) is read first, never seeded unasked: SKILL.md
-step 2 and `<SKILL_ROOT>/guides/existing-site.md` apply as written.
-
-## 3. The apps
-
-A solution the provision call did not install, or a capability's app (Members Area, Forms,
-Restaurants, Donations, FAQ), goes on with the Apps Installer:
-`<MANAGE>/references/app-installation/install-wix-apps.md`. The app ids are in each
-`seed-<solution>.mjs`, which installs them before seeding.
-
-## 4. The seed
-
-`seed-<solution>.mjs` is a sequence of REST calls, and `SEED.md` is its contract: the plan shape
-(what to create, how many, which images), the order the entities need, and the traps the script
-encodes (a Bookings service needs a category to be visible and takes resource ids, not staff ids;
-a Forms field is registered by its `validation` block; a product's choice photos are linked after
-the gallery holds them). Read `SEED.md`, read the script for any call `SEED.md` only names, and make the same
-calls through `<MANAGE>`'s recipe for each (services, products, posts, events, collections). Keep
-the script's rules: create, never delete, and report what the site already held. Image prompts
-need the Media Manager; without it, products and services stay text-only, say so.
-
-## 5. The frontend
-
-The shipped `app/` code cannot be built here, and the Astro pages cannot be released. A page can
-still be shipped: one self-contained `index.html` that loads the Wix SDK from a package CDN and
-talks to the site as a visitor, dropped onto the site from step 2 through
-`<MANAGE>/references/sites/upload-static-site.md`. The kit's own frontend for this site is a run
-with a machine, which attaches to this site (`guides/existing-site.md`) rather than making a new one.
-
-**The page.** One file, a few hundred lines, written in full before the first drop: the drop takes
-the complete file set in one call, and a response has a hard size limit, so there is no second
-pass. The SDK comes from a pinned package URL, `https://esm.sh/@wix/sdk@<version>` and the
-solution's package (`@wix/bookings`, `@wix/stores`, `@wix/blog`, …); the client is
-`createClient({ modules: { … }, auth: OAuthStrategy({ clientId }) })` with the `appId` the provision
-call returned, and the SDK mints and refreshes the visitor token itself. Markup, a render function
-per state, the event handlers: that is what you write. Keep what the page shows to what the site
-holds; nothing invented, as in SKILL.md step 4.
-
-**The calls.** Take every SDK call's shape from the kit's own transport for the solution,
-`<TEMPLATES>/<solution>/app/wix/<solution>/*.ts` (`services.ts`, `booking.ts`, `catalog.ts`, …,
-with `<TEMPLATES>/shared/app/wix/sdk.ts` for the client wiring): those files call the same SDK
-modules the page imports, and they are verified. Copy the form of the call, not the file. The
-cores beside them (`*-core.ts`) hold the rules the page needs and nothing else does: which fields
-to read, how a price or a duration is formatted, which slot is bookable, how an id is read.
-
-**A call those files don't cover** is confirmed before it is written, the way `<DOCS>` describes:
-the method's SDK page, and when the page and the package disagree, the package's own type
-declarations (the `@wix/auto_sdk_<solution>_<module>` package the solution package depends on,
-its `index.d.ts`) are the truth. Two shapes that recur, as examples of what the types settle and
-the kit's files already encode: SDK query methods return a query builder finished with `.find()`;
-and an entity's id arrives as `_id` on some objects and `id` on others (the kit reads both,
-`rawId`). Dates travel as local
-wall-clock strings in the business time zone. A page cannot be run here, so a wrong shape fails
-silently in the browser; the file beside the skill is the check that is available.
-
-## 6. Closing
-
-As in SKILL.md step 5, minus the live URL when nothing was released: what exists on the site, by
-name; the dashboard link `https://manage.wix.com/dashboard/<metaSiteId>` and each solution's own
-pages from its INSTRUCTIONS.md table; what is placeholder; payments, when the site takes money;
-and what this run could not do, with the site id, so a run with a machine continues here.