@wix/agent-skills 1.27.0 → 1.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,7 @@
     "url": "https://github.com/wix/skills/issues"
   },
   "scripts": {
-    "version": "node .github/scripts/sync-plugin-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json plugin.json gemini-extension.json"
+    "version": "node .github/scripts/sync-plugin-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json plugin.json gemini-extension.json skills/wix-headless-kit/install/pins.json"
   },
   "files": [
     "skills/**",

package/skills/wix-app/SKILL.md

@@ -492,7 +492,7 @@ Execute these steps sequentially after all implementation is complete. See [APP_
 1. **Package Installation** — Detect package manager, run install
 2. **TypeScript Compilation** — `npx tsc --noEmit -p .`
 3. **Build** — `npx wix build`
-4. **Preview** — `npx wix preview`, in the foreground: it uploads, prints the preview URLs and exits on its own, so no `timeout`, backgrounding or `sleep`
+4. **Preview** — `npx wix preview`, in the foreground and unpiped: it uploads, prints the preview URLs and exits on its own, so no `timeout`, backgrounding, `sleep` or `| tail`. If your shell moves it to the background anyway, it stalled: read what it printed and `.wix/debug.log` once, then report that the preview did not complete. Don't poll, and don't promise a URL
 
 Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 

package/skills/wix-app/references/APP_VALIDATION.md

@@ -85,14 +85,18 @@ npx wix build
 
 ### Step 4: Preview Deployment
 
-`npx wix preview` is a one-shot command, not a server: it uploads a preview build, prints the preview URLs and **exits on its own**, in seconds. Run it in the foreground and read its output:
+`npx wix preview` is a one-shot command, not a server: it uploads a preview build, prints the preview URLs and **exits on its own**, in seconds. Run it in the foreground, exactly as written, and read its output:
 
 ```bash
 npx wix preview
 ```
 
+Don't pipe it (`| tail`, `| head`, `| grep`). The output is short, and a pipe holds back everything until the command exits, so a slow preview shows nothing at all.
+
 Don't wrap it in `timeout` (macOS has none, so the call fails before preview runs), background it, `sleep` or poll a log for it, or `kill` it afterwards. There is no process left to wait for or stop.
 
+**If it doesn't return:** your shell may move a long call to the background on its own (for example, after a 120s limit). That means the preview stalled, not that it's still working normally. Read the output it left and `.wix/debug.log` **once**. If neither has the preview URLs, report "preview did not complete" with whatever they show and stop validation. Don't sleep, poll, schedule a wake-up or start the preview again, and don't tell the user a URL is coming.
+
 **Success criteria:**
 - The command exits 0
 - It printed `✔ Preview created successfully!` and the preview URLs

package/skills/wix-app/references/SDK_MODULE_MAP.md

@@ -15,7 +15,7 @@ Data owned by an existing Wix business app is read and written through that app'
 | pricing plans / subscriptions | `@wix/pricing-plans` |
 | bookings / services / staff / time slots | `@wix/bookings` |
 | calendar events / schedules | `@wix/calendar` |
-| table reservations | `@wix/table-reservations` |
+| table reservations | `@wix/table-reservations` (namespace `reservations`) — not `@wix/restaurants` |
 | restaurant menus / online orders | `@wix/restaurants` |
 | blog posts | `@wix/blog` |
 | site events / tickets / RSVPs | `@wix/events` |

package/skills/wix-app/references/editor-react-component/PARTS.md

@@ -51,7 +51,7 @@ CSS driven by a data attribute, or disable it when it should remain visible.
 After generating the manifest, confirm that its `elements` include every
 intended named part.
 
-## Sanity Check
+## Plausibility Check
 
 For each candidate, ask:
 

package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md

@@ -76,7 +76,7 @@ customTriggers.provideHandlers({
 1. **Trigger IDs must match** - The `customTriggerId` in `getEligibleTriggers` must match an `_id` from `listTriggers`
 2. **Both handlers required** - You must implement both `getEligibleTriggers` and `listTriggers`
 3. **Dynamic eligibility** - `getEligibleTriggers` is called during checkout to determine which triggers are currently active
-4. **Static list** - `listTriggers` provides the master list of all possible triggers for configuration in the Wix dashboard
+4. **Static list** - `listTriggers` provides the full list of all possible triggers for configuration in the Wix dashboard
 5. **Manual step required, every time** — this plugin only supplies *eligibility*. It has no visible effect until the merchant creates an Automatic Discount that uses your trigger. Tell the user this step is required; don't imply the discount is live just because the plugin is installed. Confirmed live, click-by-click in the dashboard:
    1. Go to **Catalog** (left sidebar) → **Discounts** → **Automatic Discounts**.
    2. Click **Create Discount**.

package/skills/wix-app/references/stores/GET_PRODUCT.md

@@ -4,13 +4,21 @@
 
 ```typescript
 if (v === 'V3_CATALOG') {
-  const product = await productsV3.getProduct(id);  // returns Product directly
+  const product = await productsV3.getProduct(id);  // returns V3Product directly
   return product;
 }
 const { product } = await products.getProduct(id);  // V1 wraps in { product }
 return product;
 ```
 
+The V3 entity type is `productsV3.V3Product`.
+
+---
+
+## Product page URL
+
+V3 `product.url` is populated only when the request's `fields` includes `'URL'` — `getProduct(id, { fields: ['URL'] })`, or the direct-call `searchProducts` / `queryProducts(query, { fields: ['URL'] })` (the fluent builder's `.find()` takes no options). V1 `productPageUrl` is an object, `{ base, path }`, not a string.
+
 ---
 
 ## Read product options and choices (V1 vs V3)

package/skills/wix-app/references/stores/INVENTORY.md

@@ -18,6 +18,8 @@ if (v === 'V3_CATALOG') {
 }
 ```
 
+V3 increments work only for inventory items with `trackQuantity: true`; the entries are `{ inventoryItemId, incrementBy }` with `incrementBy` 1 to 99999.
+
 To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
 
 ---

package/skills/wix-app/references/stores/QUERY.md

@@ -8,7 +8,7 @@ Both versions expose a fluent query builder, but the paging method differs:
 |--------|--------------------------------|----------------------------------|
 | API style | Fluent builder: `.skip().limit().find()` | Fluent builder: `.skipTo(cursor).limit().find()` |
 | Pagination | Offset (`.skip(n)`) | Cursor (`.skipTo(cursor)`) |
-| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `Product[]`) |
+| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `productsV3.V3Product[]`) |
 | Total count | `res.totalCount` | **None** — V3 only has `cursors.next` + `hasNext()` |
 | `hasNext` | `res.hasNext()` (method) | `res.hasNext()` (method) |
 | Next cursor | n/a | `res.cursors.next` (string) |
@@ -35,7 +35,7 @@ export async function listProductsPage(
   if (v === 'V3_CATALOG') {
     let builder = productsV3.queryProducts().limit(limit);
     if (typeof cursorOrSkip === 'string') builder = builder.skipTo(cursorOrSkip);
-    // Do NOT chain a sort — see OVERVIEW.md gotcha #10.
+    // Do NOT chain a sort — see [STORES_VERSIONING.md](../STORES_VERSIONING.md) gotcha #10.
     const res = await builder.find();
     return {
       products: res.items,

package/skills/wix-app/references/stores/WRITE.md

@@ -32,7 +32,7 @@ return product;
 
 ```typescript
 if (v === 'V3_CATALOG') {
-  // Signature: updateProduct(_id, productFields). Returns Product directly.
+  // Signature: updateProduct(_id, productFields). Returns V3Product directly.
   const current = await productsV3.getProduct(id);
   if (current.revision == null) throw new Error(`Product ${id} has no revision`);
   return await productsV3.updateProduct(id, {

package/skills/wix-headless/references/astro.md

@@ -81,7 +81,7 @@ The **per-vertical values** — which `WIX_APPS.*PageMetadata` accessor + `seoTa
 
 ## 7 — Caveats (the gaps the docs don't mention)
 
-The heart of the file: tribal knowledge the docs won't surface. These are **guidance the model must follow when it writes the frontend** — not things this skill writes for it.
+The heart of the file: hard-won knowledge the docs won't surface. These are **guidance the model must follow when it writes the frontend** — not things this skill writes for it.
 
 | Caveat | What it says |
 |---|---|

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

@@ -302,6 +302,10 @@ browser versus the server, the OAuth allow-list for a self-hosted origin, pre-re
 how to close such a run. A public site is still better served by managed Astro; say so when you
 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
+scripts make and the files beside this skill that carry the contracts.
+
 ## Verticals
 
 The shortlist. Match the brief against the first column; when it names a Wix product or a

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

@@ -0,0 +1,115 @@
+# 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.

package/skills/wix-headless-kit/install/attach.mjs

@@ -44,7 +44,7 @@
 // business instead.
 //
 // Emits ONE JSON event per line (attached, scaffolded, deployed, install_started,
-// ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@latest whoami`)
+// ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@<pinned> whoami`, the version in pins.json)
 // whose account owns or co-manages the site.
 import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
@@ -53,6 +53,8 @@ import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
 import { frontendPresent, siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const MANAGE = "https://manage.wix.com";
@@ -135,9 +137,9 @@ emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cw
 
 // ---- http ---------------------------------------------------------------------------------------
 const cliToken = (site) => {
-  const r = spawnSync("npx", ["-y", "@wix/cli@latest", "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
+  const r = spawnSync("npx", ["-y", WIX_CLI, "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
   const t = (r.stdout || "").trim();
-  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || "no token — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-400));
+  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || `no token — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-400));
   return t;
 };
 async function call(base, path, { method = "POST", token, site, body, query } = {}) {

package/skills/wix-headless-kit/install/bootstrap.mjs

@@ -3,6 +3,8 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 // ── tiny event protocol (one JSON object per line) ───────────────────────────
 const emit = (event, extra = {}) =>
@@ -15,7 +17,7 @@ const fail = (event, extra = {}) => {
 // ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
 const isWin = process.platform === 'win32';
 const bin = (name) => (isWin ? `${name}.cmd` : name);
-const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
+const WIX = [bin('npx'), '-y', WIX_CLI]; // run the CLI via npx — no global install/mutation
 
 // Force the CLI into non-interactive "agent" mode. Without an agent signal in
 // the env, `wix login` renders an interactive Ink TUI (device code + keypress)

package/skills/wix-headless-kit/install/context.mjs

@@ -19,6 +19,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 // The variables the editor-to-headless migration writes into the child project's `prod`
 // environment (headless-bo, editorMigrations/environmentMetadata.ts), which `wix env pull` copies
@@ -57,7 +59,7 @@ export function readWixConfig(cwd) {
   try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
 }
 
-const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
+const ENV_PULL = ["-y", WIX_CLI, "env", "pull"];
 const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
 
 /**
@@ -70,7 +72,7 @@ export function pullEnv(cwd) {
   const envFile = join(cwd, ".env.local");
   const r = runPull(cwd);
   if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
-  return { ok: false, error: (r.stderr || r.stdout || "env pull produced no .env.local — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").trim().slice(-400) };
+  return { ok: false, error: (r.stderr || r.stdout || `env pull produced no .env.local — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).trim().slice(-400) };
 }
 
 /**

package/skills/wix-headless-kit/install/deploy.mjs

@@ -46,6 +46,8 @@ import { fileURLToPath } from "node:url";
 import { templatesDir } from "./templates.mjs";
 import { syncLockRoot } from "./lock.mjs";
 import { siteContext } from "./context.mjs";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // The shipped code: the repository's templates/ (a checkout, the cache, or fetched now).
@@ -275,7 +277,7 @@ if (stack === "static") {
   // .env.local (`wix env pull`; on a migration preview the parent site's app), else the config's appId.
   let clientId = clientIdFlag ?? (existsSync(join(PROJECT, "wix.config.json")) ? siteContext({ cwd: PROJECT }).content.clientId : null);
   if (!clientId) {
-    console.log(JSON.stringify({ error: "static stack needs the public OAuth client id — run `npm create @wix/new@latest init` here first, or pass --client-id" }));
+    console.log(JSON.stringify({ error: `static stack needs the public OAuth client id — run \`npm create @wix/new@${PINS["@wix/create-new"]} init\` here first, or pass --client-id` }));
     process.exit(1);
   }
   const missing = requested.filter((v) => !existsSync(join(REF, v, "rest")));
@@ -336,7 +338,7 @@ if (stack === "static") {
   const sources = readdirSync(JS).filter((f) => f.endsWith(".ts")).map((f) => join(JS, f));
   const tsc = spawnSync(
     "npx",
-    ["-y", "-p", "typescript@5", "tsc", ...sources, "--outDir", JS, "--module", "esnext", "--target", "es2022",
+    ["-y", "-p", `typescript@${PINS.typescript}`, "tsc", ...sources, "--outDir", JS, "--module", "esnext", "--target", "es2022",
      "--moduleResolution", "bundler", "--lib", "es2022,dom", "--strict", "--skipLibCheck", "--removeComments", "false"],
     { encoding: "utf8", timeout: 180_000 },
   );

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

@@ -0,0 +1,8 @@
+{
+  "@wix/cli": "1.1.258",
+  "@wix/create-new": "0.0.124",
+  "typescript": "5.8.3",
+  "templates": {
+    "ref": "v1.29.0"
+  }
+}

package/skills/wix-headless-kit/install/setup.mjs

@@ -37,6 +37,8 @@ import { fileURLToPath } from "node:url";
 import { AGENT_CONFIG_FILES, writeAgentsMd } from "./agents-md.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
 import { folderShape, siteContext } from "./context.mjs";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -134,14 +136,14 @@ if (mode === "create") {
       // commit" is noise here, and becomes a nested-repo (submodule gitlink) hazard
       // if the project is later placed inside an existing repo. --skip-install for the
       // same reason: deps install in a detached step below.
-      ["create", "@wix/new@latest", "--", "headless",
+      ["create", `@wix/new@${PINS["@wix/create-new"]}`, "--", "headless",
        "--folder-name", folderName, "--business-name", businessName,
        "--site-template", "blank", ...(template ? ["--template-path", template] : []),
        "--skip-install", "--skip-git", "--no-publish"],
       { env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 },
     );
     if (scaffold.status !== 0 || !existsSync(join(projectDir, "wix.config.json"))) {
-      fail("scaffold", (scaffold.stderr || scaffold.stdout || "scaffold produced no wix.config.json — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-600));
+      fail("scaffold", (scaffold.stderr || scaffold.stdout || `scaffold produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
     }
   }
 } else if (mode === "migrate") {
@@ -177,10 +179,10 @@ if (mode === "create") {
   // wix.config.json and .env.local, touches nothing else. Non-interactive under CI=1; the site is
   // named after the folder (rename it in the dashboard).
   emit("adopting", { folder: cwd });
-  const init = spawnSync("npm", ["create", "@wix/new@latest", "--", "init"],
+  const init = spawnSync("npm", ["create", `@wix/new@${PINS["@wix/create-new"]}`, "--", "init"],
     { cwd, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 });
   if (init.status !== 0 || !has("wix.config.json")) {
-    fail("init", (init.stderr || init.stdout || "init produced no wix.config.json — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-600));
+    fail("init", (init.stderr || init.stdout || `init produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
   }
 }
 const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
@@ -296,10 +298,10 @@ if (planPath && madeTheSite) {
 
 // ---- done ----------------------------------------------------------------------------------------
 const release = {
-  astro: "npx @wix/cli@latest build, then npx @wix/cli@latest release",
-  react: "the project's own build, then npx @wix/cli@latest release of the build folder named in wix.config.json (what Wix hosting serves and how routes must be shaped: SKILL.md step 1)",
-  lib: "the project's own build, then npx @wix/cli@latest release of the build folder named in wix.config.json (SKILL.md step 1)",
-  static: `npx @wix/cli@latest release — no build; it uploads ${STATIC_OUT}/ whole (wix.config.json site.outputDirectory), so the pages, styles and assets move into ${STATIC_OUT}/ first and import the modules from ./js/wix/ there; the root keeps the config, the plan, the seed output and the skills`,
+  astro: `npx ${WIX_CLI} build, then npx ${WIX_CLI} release`,
+  react: `the project's own build, then npx ${WIX_CLI} release of the build folder named in wix.config.json (what Wix hosting serves and how routes must be shaped: SKILL.md step 1)`,
+  lib: `the project's own build, then npx ${WIX_CLI} release of the build folder named in wix.config.json (SKILL.md step 1)`,
+  static: `npx ${WIX_CLI} release — no build; it uploads ${STATIC_OUT}/ whole (wix.config.json site.outputDirectory), so the pages, styles and assets move into ${STATIC_OUT}/ first and import the modules from ./js/wix/ there; the root keeps the config, the plan, the seed output and the skills`,
 }[stack];
 // On a migration preview the links and `siteId` are the PARENT's — the site whose content the pages
 // show and whose dashboard manages it; `deploySiteId` is where `wix release` goes.

package/skills/wix-headless-kit/install/templates.mjs

@@ -11,9 +11,13 @@
 //   2. the cache `<SKILL_ROOT>/templates/`, filled by an earlier call (`--refresh` refetches).
 //   3. a fetch: a sparse, shallow clone of `skills/wix-headless-templates/` from the repository the skill was installed
 //      from (skills-lock.json's `source`, default wix/skills), at the branch or tag the install
-//      named (its `ref`, falling back to the default branch when that ref no longer exists) or the
-//      repository's default branch. The lock records no commit, so there is nothing more exact to
-//      pin to; `WIX_HEADLESS_FAST_TEMPLATES_REF=<branch|tag|sha>` overrides the ref.
+//      named (its `ref`, falling back to the default branch when that ref no longer exists), else
+//      the repository's default branch: a skill installed from the repository tracks the repository,
+//      so the templates match the kit beside them. A kit that came from a package (no skills-lock.json
+//      above it) fetches at the release tag in `install/pins.json` (`templates.ref`, kept equal to the
+//      package version by the release flow), the code it was released with; the package carries the
+//      templates skill beside the kit anyway, so that fetch is the rare path.
+//      `WIX_HEADLESS_FAST_TEMPLATES_REF=<branch|tag|sha>` overrides all of it.
 // The cache stays with the project: its `.gitignore` leaves out only the composed `project/`
 // folders (the scaffolds with their lockfiles, read once, at create or attach) and the repository
 // tooling, so the code layers, playbooks, seeds and readers are committed at the commit the project
@@ -29,6 +33,8 @@ export const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..")
 export const DEFAULT_REPO = "https://github.com/wix/skills.git";
 /** The templates skill's folder in the repository. */
 export const TEMPLATES_PATH = "skills/wix-headless-templates";
+/** Pinned versions, shared by the install scripts; `templates.ref` is the release tag the fetch defaults to. */
+export const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 
 const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 180_000, ...opts });
 
@@ -46,7 +52,7 @@ export function installSource() {
         if (typeof entry?.source === "string" && entry.source) {
           const parsed = parseSource(entry.source);
           // `ref` is the branch or tag the install named (skills-lock.json v1 keeps it beside `source`)
-          return { ...parsed, ref: parsed.ref ?? (typeof entry.ref === "string" && entry.ref ? entry.ref : null) };
+          return { ...parsed, ref: parsed.ref ?? (typeof entry.ref === "string" && entry.ref ? entry.ref : null), fromLock: true };
         }
       } catch { /* fall through to the default */ }
       break;
@@ -55,7 +61,7 @@ export function installSource() {
     if (up === dir) break;
     dir = up;
   }
-  return { repo: DEFAULT_REPO, ref: null };
+  return { repo: DEFAULT_REPO, ref: null, fromLock: false };
 }
 
 function parseSource(src) {
@@ -112,15 +118,19 @@ export function templatesSource(dir) {
 }
 
 function fetchTemplates(cache) {
-  const { repo, ref: lockRef } = installSource();
+  const { repo, ref: lockRef, fromLock } = installSource();
   const envRef = process.env.WIX_HEADLESS_FAST_TEMPLATES_REF || null;
-  let ref = envRef || lockRef || null;
+  // Installed from the repository (a lock above the skill) and no ref named: the default branch, so
+  // the templates match the kit. No lock at all is a package install: the release tag it shipped with.
+  const pinnedRef = fromLock ? null : (PINS.templates?.ref || null);
+  let ref = envRef || lockRef || pinnedRef || null;
   let r = cloneSparse(repo, ref);
   // The branch the skill was installed from can be gone by the time the code is first needed
   // (merged and deleted). The lock's ref then falls back to the default branch; an explicit env
   // ref does not.
   let fellBack = false;
   if (r.status !== 0 && ref && !envRef && /not found|couldn't find remote ref|unknown revision/i.test(r.stderr || "")) {
+    // (the pinned tag, too: a fork or a pre-release checkout may not carry it)
     rmSync(r.tmp, { recursive: true, force: true });
     fellBack = true; ref = null;
     r = cloneSparse(repo, null);
@@ -141,7 +151,7 @@ function fetchTemplates(cache) {
   catch { cpSync(join(tmp, TEMPLATES_PATH), cache, { recursive: true }); }
   rmSync(tmp, { recursive: true, force: true });
   writeFileSync(join(cache, ".gitignore"), IGNORED.join("\n") + "\n");
-  writeFileSync(join(cache, ".source"), JSON.stringify({ repo, ref: ref ?? (fellBack ? `default branch (${lockRef} not found)` : "default branch"), commit, fetchedAt: new Date().toISOString() }, null, 2) + "\n");
+  writeFileSync(join(cache, ".source"), JSON.stringify({ repo, ref: ref ?? (fellBack ? `default branch (${lockRef || pinnedRef} not found)` : "default branch"), commit, fetchedAt: new Date().toISOString() }, null, 2) + "\n");
 }
 
 // A sparse, shallow clone of the templates skill's folder at a ref (branch, tag, or commit id) into a temp dir.

package/skills/wix-headless-templates/donations/INSTRUCTIONS.md

@@ -6,8 +6,9 @@ typed end-to-end. **The presentation is yours**: you design and implement the ca
 campaigns index, the campaign page's layout around the shipped form, the home page and the brand. You
 never write checkout logic; you never skip designing.
 
-A donation is an eCom checkout with one line that references the campaign; Wix's hosted checkout takes
-the payment and the donor's details, and the eCom order is the receipt. The campaign entity carries
+A donation is an eCom cart (Cart V2) with one line that references the campaign; in V2 the cart IS the
+checkout, so the cart's id is the id the redirect session takes — there is no separate checkout entity.
+Wix's hosted checkout takes the payment and the donor's details, and the eCom order is the receipt. The campaign entity carries
 **no description and no slug**: the story on a campaign page is the site's own copy, and routes key by
 the campaign id (`/donate/<id>`).
 
@@ -29,7 +30,7 @@ Astro markup), your campaign page layout, and your home page.
 | `wix/media.ts` · `wix/money.ts` | `imgAttrs(url, sizes, ratio)` — every `<img>` attribute for a DTO image: `<img {...imgAttrs(c.imageUrl, "50vw", 9 / 16)} alt={c.name} />`; `imgSrc()` / `imgSrcSet()` underneath |
 | `wix/donations/types.ts` | the DTOs (`CampaignSummary`, `CampaignDetail`, `GoalProgress`, `DonationOptions`, `DonationReceipt`) — contracts inlined below |
 | `wix/donations/campaigns.ts` | `fetchCampaigns`, `fetchCampaign(id)`, `fetchDefaultCampaign` — the transport; the rules and DTO mappers are in `donations-core.ts` beside it (shared with the REST layer) |
-| `wix/donations/donate.ts` | `donationCheckoutUrl(campaignId, input)` — the checkout line + hosted redirect session; `fetchDonationReceipt(orderId)` — the thank-you page's order read; bodies in `donations-core.ts` |
+| `wix/donations/donate.ts` | `donationCheckoutUrl(campaignId, input)` — the donation cart + hosted redirect session; `fetchDonationReceipt(orderId)` — the thank-you page's order read; bodies in `donations-core.ts` |
 | `wix/donations/donation-store.ts` · `campaigns-store.ts` · `receipt-store.ts` | the form, listing and receipt state machines, framework-free (`createDonationStore(campaign)`, `createCampaignsStore()`, `createReceiptStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly |
 | `hooks/donations/useDonation.ts` | React binding of `donation-store.ts`: the donate form's state and actions — contract below |
 | `hooks/donations/useCampaigns.ts` | React binding of `campaigns-store.ts`: the listing — contract below |
@@ -328,12 +329,10 @@ first real site and read the owning file if one bites.
   shows) and `options.currency` "" (the button reads "Donate" without an amount; preset labels still
   carry the API's own formatted amounts). If the campaign query itself is refused, the pages render
   their empty state.
-- **Direct Create Checkout vs the Wix widget's cart route.** The default creates the checkout directly
-  (a donation must never merge into a storefront visitor's cart); if the Donations catalog refuses to
-  price that line, `donationCheckoutUrl` falls back to the widget's own Create Cart → Create Checkout
-  (`channelType: OTHER_PLATFORM`), reachable by name as `createDonationCheckoutViaCart`. The cart route
-  can answer `CURRENT_CART_ALREADY_EXISTS` for a visitor who already holds a cart — surfaced as the
-  form's error.
+- **Create Cart is the whole path (Cart V2).** `donationCheckoutUrl` creates one fresh cart with the
+  donation line (`cart.source.channelType: WEB`, the donor note as `cart.note`) and hands that cart's
+  id straight to the redirect session — the cart is the checkout, so there is no separate Create
+  Checkout call and nothing merges into a storefront visitor's current cart.
 - **Site currency.** Comes from the metrics response ("returns only the site's default currency");
   On a campaign nobody has donated to yet the metrics carry no currency either, so the transports read the site's currency once from the eCommerce settings (BUSINESS_INFO); unknown → "".
 - **Reading the order on the thank-you page.** `GET /ecom/v1/orders/{id}` with the visitor's token is