@wix/agent-skills 1.27.0 → 1.28.0

package/package.json

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

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/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-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.257",
+  "@wix/create-new": "0.0.123",
+  "typescript": "5.8.3",
+  "templates": {
+    "ref": "v1.28.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

package/skills/wix-headless-templates/donations/app/wix/donations/donate.ts

@@ -1,29 +1,19 @@
-// The donation flow over the SDK: a visitor's choice → an eCom checkout with one donation line →
-// the Wix-hosted checkout URL; and the thank-you page's order read. Payment, donor details and
-// receipts are Wix's hosted checkout and the eCom order — nothing here creates an order or builds
-// a URL by hand. Bodies and result readers live in ./donations-core (shared with the REST twin);
-// this file is the transport only. Copy as-is.
-//
-// Two routes to a checkout id, both kept:
-//   createDonationCheckout        — Create Checkout with the line (a donation never merges into a
-//                                   storefront visitor's current cart). The default.
-//   createDonationCheckoutViaCart — the Wix widget's own sequence: Create Cart → Create Checkout
-//                                   from the cart, channelType OTHER_PLATFORM. The fallback when
-//                                   the direct route is refused; also reachable by name.
-// Whether the Donations catalog plugin prices a line created directly is not yet verified live,
-// hence the automatic fallback.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// The donation flow over the SDK: a visitor's choice → an eCom cart with one donation line → the
+// Wix-hosted checkout URL; and the thank-you page's order read. In Cart V2 there is no separate
+// checkout entity: the cart IS the checkout, so its id is the id the redirect session takes.
+// Payment, donor details and receipts are Wix's hosted checkout and the eCom order — nothing here
+// creates an order or builds a URL by hand. Bodies and result readers live in ./donations-core
+// (shared with the REST twin); this file is the transport only. Copy as-is.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
-import { cart as cartModule, checkout as checkoutModule, orders as ordersModule } from "@wix/ecom";
+import { cartV2 as cartV2Module, orders as ordersModule } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";
 import {
   cartBody,
-  checkoutBody,
+  cartIdOf,
   checkoutError,
-  checkoutIdOf,
-  rawId,
   redirectBody,
   redirectUrl,
   toReceipt,
@@ -34,8 +24,7 @@ import type { DonationInput, DonationReceipt } from "./types";
 
 export type { DonatePaths };
 
-const checkoutApi = wixModule(checkoutModule);
-const cartApi = wixModule(cartModule);
+const cartV2Api = wixModule(cartV2Module);
 const ordersApi = wixModule(ordersModule);
 const redirects = wixModule(redirectsModule);
 
@@ -46,37 +35,21 @@ export interface DonateOptions {
   paths?: DonatePaths;
 }
 
-/** Create Checkout with the donation line → checkout id. */
-export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
-  const checkout: Raw = await checkoutApi.createCheckout(checkoutBody(campaignId, input) as any);
-  return checkoutIdOf(checkout);
-}
-
-/** The Wix widget's route: Create Cart (the note as buyerNote) → Create Checkout from the cart → checkout id. */
-export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
-  const cart: Raw = await cartApi.createCart(cartBody(campaignId, input) as any);
-  const res: Raw = await cartApi.createCheckout(rawId(cart), { channelType: "OTHER_PLATFORM" });
-  return checkoutIdOf(res);
-}
-
 /**
  * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
- * Direct Create Checkout first, the cart route when that is refused, then one redirect session
- * whose thank-you callback lands on `/donate/thank-you?orderId=`.
+ * One Create Cart (the cart is the checkout) → one redirect session whose thank-you callback lands
+ * on `/donate/thank-you?orderId=`.
  */
 export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
   const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
-  let checkoutId: string;
+  let cartId: string;
   try {
-    checkoutId = await createDonationCheckout(campaignId, input);
-  } catch (direct) {
-    try {
-      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
-    } catch {
-      throw checkoutError(direct);
-    }
+    const cart: Raw = await cartV2Api.createCart(cartBody(campaignId, input) as any);
+    cartId = cartIdOf(cart);
+  } catch (e) {
+    throw checkoutError(e);
   }
-  const session: Raw = await redirects.createRedirectSession(redirectBody(checkoutId, campaignId, site, paths) as any);
+  const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
   return redirectUrl(session);
 }
 

package/skills/wix-headless-templates/donations/app/wix/donations/donations-core.ts

@@ -1,7 +1,7 @@
 // Donation rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./campaigns.ts
 // + ./donate.ts (the SDK, managed Astro and React) and the REST twins in templates/donations/rest/
 // (fetch, a static site or a port to another language). Every rule about amounts, fees, frequency,
-// goal math, validation, the checkout line and the redirect body lives HERE, once. A raw campaign
+// goal math, validation, the cart line and the redirect body lives HERE, once. A raw campaign
 // may come from the SDK (`_id`, coverImage as a `wix:image://` string) or from REST (`id`,
 // coverImage as { id, url }); the mappers accept both. Has its own formatMoney so it stands alone
 // when stripped. Imports are type-only so a strip to JS emits no imports.
@@ -351,10 +351,10 @@ export function toInput(options: DonationOptions, sel: DonationSelection): Donat
   return { amount, frequency: sel.frequency, coverFee: options.askCoverFee && sel.coverFee, note: sel.note.trim() };
 }
 
-// ---- checkout -------------------------------------------------------------------------------------
+// ---- cart -----------------------------------------------------------------------------------------
 
 /**
- * The one line item a donation checkout carries. `amount` is a NUMBER and `frequency` the enum
+ * The one catalog item a donation cart carries. `amount` is a NUMBER and `frequency` the enum
  * string; `donorCoveringFees` is sent only when the donor opted in (the Donations catalog plugin
  * prices the line from these options — never a customLineItem, never a computed price).
  */
@@ -370,27 +370,26 @@ export function donationLineItem(campaignId: string, input: DonationInput): Raw
   };
 }
 
-/** Create Checkout body: the donation line, channelType WEB, the note as the checkout's buyerNote. */
-export function checkoutBody(campaignId: string, input: DonationInput): Raw {
-  return {
-    lineItems: [donationLineItem(campaignId, input)],
-    channelType: "WEB",
-    ...(input.note ? { checkoutInfo: { buyerNote: input.note } } : {}),
-  };
-}
-
-/** Create Cart body — the Wix widget's own route (fallback): the note as the cart's buyerNote. */
+/**
+ * Create Cart body (Cart V2): the single donation catalog item, the WEB channel on the cart's
+ * `source`, the donor note as the cart's `note`. In V2 the created cart IS the checkout — its id is
+ * the id the redirect session takes; there is no separate Create Checkout step.
+ */
 export function cartBody(campaignId: string, input: DonationInput): Raw {
   return {
-    lineItems: [donationLineItem(campaignId, input)],
-    ...(input.note ? { cartInfo: { buyerNote: input.note } } : {}),
+    cart: { source: { channelType: "WEB" }, ...(input.note ? { note: input.note } : {}) },
+    catalogItems: [donationLineItem(campaignId, input)],
   };
 }
 
-/** The checkout id out of either transport's response for either route. */
-export function checkoutIdOf(res: Raw | null | undefined): string {
-  const id = res?._id ?? res?.id ?? res?.checkoutId ?? res?.checkout?.id ?? res?.checkout?._id ?? "";
-  if (!id) throw new Error("Checkout couldn't start: no checkout id returned.");
+/**
+ * The cart id out of the Create Cart response — the id a V2 donation hands the redirect session
+ * (the cart is the checkout). The SDK returns a Cart directly (`_id`); REST wraps it as
+ * `{ cart: { id } }`.
+ */
+export function cartIdOf(res: Raw | null | undefined): string {
+  const id = res?._id ?? res?.id ?? res?.cart?._id ?? res?.cart?.id ?? "";
+  if (!id) throw new Error("Checkout couldn't start: no cart id returned.");
   return String(id);
 }
 

package/skills/wix-headless-templates/donations/project/src/wix/donations/donate.ts

@@ -1,29 +1,19 @@
-// The donation flow over the SDK: a visitor's choice → an eCom checkout with one donation line →
-// the Wix-hosted checkout URL; and the thank-you page's order read. Payment, donor details and
-// receipts are Wix's hosted checkout and the eCom order — nothing here creates an order or builds
-// a URL by hand. Bodies and result readers live in ./donations-core (shared with the REST twin);
-// this file is the transport only. Copy as-is.
-//
-// Two routes to a checkout id, both kept:
-//   createDonationCheckout        — Create Checkout with the line (a donation never merges into a
-//                                   storefront visitor's current cart). The default.
-//   createDonationCheckoutViaCart — the Wix widget's own sequence: Create Cart → Create Checkout
-//                                   from the cart, channelType OTHER_PLATFORM. The fallback when
-//                                   the direct route is refused; also reachable by name.
-// Whether the Donations catalog plugin prices a line created directly is not yet verified live,
-// hence the automatic fallback.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// The donation flow over the SDK: a visitor's choice → an eCom cart with one donation line → the
+// Wix-hosted checkout URL; and the thank-you page's order read. In Cart V2 there is no separate
+// checkout entity: the cart IS the checkout, so its id is the id the redirect session takes.
+// Payment, donor details and receipts are Wix's hosted checkout and the eCom order — nothing here
+// creates an order or builds a URL by hand. Bodies and result readers live in ./donations-core
+// (shared with the REST twin); this file is the transport only. Copy as-is.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
-import { cart as cartModule, checkout as checkoutModule, orders as ordersModule } from "@wix/ecom";
+import { cartV2 as cartV2Module, orders as ordersModule } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";
 import {
   cartBody,
-  checkoutBody,
+  cartIdOf,
   checkoutError,
-  checkoutIdOf,
-  rawId,
   redirectBody,
   redirectUrl,
   toReceipt,
@@ -34,8 +24,7 @@ import type { DonationInput, DonationReceipt } from "./types";
 
 export type { DonatePaths };
 
-const checkoutApi = wixModule(checkoutModule);
-const cartApi = wixModule(cartModule);
+const cartV2Api = wixModule(cartV2Module);
 const ordersApi = wixModule(ordersModule);
 const redirects = wixModule(redirectsModule);
 
@@ -46,37 +35,21 @@ export interface DonateOptions {
   paths?: DonatePaths;
 }
 
-/** Create Checkout with the donation line → checkout id. */
-export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
-  const checkout: Raw = await checkoutApi.createCheckout(checkoutBody(campaignId, input) as any);
-  return checkoutIdOf(checkout);
-}
-
-/** The Wix widget's route: Create Cart (the note as buyerNote) → Create Checkout from the cart → checkout id. */
-export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
-  const cart: Raw = await cartApi.createCart(cartBody(campaignId, input) as any);
-  const res: Raw = await cartApi.createCheckout(rawId(cart), { channelType: "OTHER_PLATFORM" });
-  return checkoutIdOf(res);
-}
-
 /**
  * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
- * Direct Create Checkout first, the cart route when that is refused, then one redirect session
- * whose thank-you callback lands on `/donate/thank-you?orderId=`.
+ * One Create Cart (the cart is the checkout) → one redirect session whose thank-you callback lands
+ * on `/donate/thank-you?orderId=`.
  */
 export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
   const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
-  let checkoutId: string;
+  let cartId: string;
   try {
-    checkoutId = await createDonationCheckout(campaignId, input);
-  } catch (direct) {
-    try {
-      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
-    } catch {
-      throw checkoutError(direct);
-    }
+    const cart: Raw = await cartV2Api.createCart(cartBody(campaignId, input) as any);
+    cartId = cartIdOf(cart);
+  } catch (e) {
+    throw checkoutError(e);
   }
-  const session: Raw = await redirects.createRedirectSession(redirectBody(checkoutId, campaignId, site, paths) as any);
+  const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
   return redirectUrl(session);
 }
 

package/skills/wix-headless-templates/donations/project/src/wix/donations/donations-core.ts

@@ -1,7 +1,7 @@
 // Donation rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./campaigns.ts
 // + ./donate.ts (the SDK, managed Astro and React) and the REST twins in templates/donations/rest/
 // (fetch, a static site or a port to another language). Every rule about amounts, fees, frequency,
-// goal math, validation, the checkout line and the redirect body lives HERE, once. A raw campaign
+// goal math, validation, the cart line and the redirect body lives HERE, once. A raw campaign
 // may come from the SDK (`_id`, coverImage as a `wix:image://` string) or from REST (`id`,
 // coverImage as { id, url }); the mappers accept both. Has its own formatMoney so it stands alone
 // when stripped. Imports are type-only so a strip to JS emits no imports.
@@ -351,10 +351,10 @@ export function toInput(options: DonationOptions, sel: DonationSelection): Donat
   return { amount, frequency: sel.frequency, coverFee: options.askCoverFee && sel.coverFee, note: sel.note.trim() };
 }
 
-// ---- checkout -------------------------------------------------------------------------------------
+// ---- cart -----------------------------------------------------------------------------------------
 
 /**
- * The one line item a donation checkout carries. `amount` is a NUMBER and `frequency` the enum
+ * The one catalog item a donation cart carries. `amount` is a NUMBER and `frequency` the enum
  * string; `donorCoveringFees` is sent only when the donor opted in (the Donations catalog plugin
  * prices the line from these options — never a customLineItem, never a computed price).
  */
@@ -370,27 +370,26 @@ export function donationLineItem(campaignId: string, input: DonationInput): Raw
   };
 }
 
-/** Create Checkout body: the donation line, channelType WEB, the note as the checkout's buyerNote. */
-export function checkoutBody(campaignId: string, input: DonationInput): Raw {
-  return {
-    lineItems: [donationLineItem(campaignId, input)],
-    channelType: "WEB",
-    ...(input.note ? { checkoutInfo: { buyerNote: input.note } } : {}),
-  };
-}
-
-/** Create Cart body — the Wix widget's own route (fallback): the note as the cart's buyerNote. */
+/**
+ * Create Cart body (Cart V2): the single donation catalog item, the WEB channel on the cart's
+ * `source`, the donor note as the cart's `note`. In V2 the created cart IS the checkout — its id is
+ * the id the redirect session takes; there is no separate Create Checkout step.
+ */
 export function cartBody(campaignId: string, input: DonationInput): Raw {
   return {
-    lineItems: [donationLineItem(campaignId, input)],
-    ...(input.note ? { cartInfo: { buyerNote: input.note } } : {}),
+    cart: { source: { channelType: "WEB" }, ...(input.note ? { note: input.note } : {}) },
+    catalogItems: [donationLineItem(campaignId, input)],
   };
 }
 
-/** The checkout id out of either transport's response for either route. */
-export function checkoutIdOf(res: Raw | null | undefined): string {
-  const id = res?._id ?? res?.id ?? res?.checkoutId ?? res?.checkout?.id ?? res?.checkout?._id ?? "";
-  if (!id) throw new Error("Checkout couldn't start: no checkout id returned.");
+/**
+ * The cart id out of the Create Cart response — the id a V2 donation hands the redirect session
+ * (the cart is the checkout). The SDK returns a Cart directly (`_id`); REST wraps it as
+ * `{ cart: { id } }`.
+ */
+export function cartIdOf(res: Raw | null | undefined): string {
+  const id = res?._id ?? res?.id ?? res?.cart?._id ?? res?.cart?.id ?? "";
+  if (!id) throw new Error("Checkout couldn't start: no cart id returned.");
   return String(id);
 }
 

package/skills/wix-headless-templates/donations/rest/donate.ts

@@ -1,19 +1,17 @@
 // The donation flow over REST — the twin of app/wix/donations/donate.ts. Same exports, same
 // signatures; the bodies and result readers come from donations-core (the SAME file the SDK
-// transport uses). A donation is an eCom checkout with one catalog line; the hosted checkout takes
-// payment and donor details. Never create the order yourself, never hand-build a checkout URL.
-// Two routes to a checkout id, both kept: Create Checkout directly (default), and the Wix widget's
-// Create Cart → Create Checkout from the cart (the fallback when the direct route is refused).
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// transport uses). A donation is an eCom cart with one catalog line; the hosted checkout takes
+// payment and donor details. In Cart V2 the cart IS the checkout — its id is the id the redirect
+// session takes, so there is one route and no separate Create Checkout call. Never create the
+// order yourself, never hand-build a checkout URL.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
 import { wixRequest } from "./client.js";
 import {
   cartBody,
-  checkoutBody,
+  cartIdOf,
   checkoutError,
-  checkoutIdOf,
-  rawId,
   redirectBody,
   redirectUrl,
   toReceipt,
@@ -31,46 +29,22 @@ export interface DonateOptions {
   paths?: DonatePaths;
 }
 
-/**
- * Create Checkout with the donation line → checkout id.
- * POST /ecom/v1/checkouts  { lineItems: [{ quantity: 1, catalogReference: { appId, catalogItemId, options: { amount, frequency, donorCoveringFees? } } }], channelType: "WEB", checkoutInfo?: { buyerNote } }  → { checkout: { id } }
- */
-export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
-  const res = await wixRequest<Raw>("/ecom/v1/checkouts", { body: checkoutBody(campaignId, input) });
-  return checkoutIdOf(res);
-}
-
-/**
- * The Wix widget's route → checkout id.
- * POST /ecom/v1/carts  { lineItems, cartInfo?: { buyerNote } }  → { cart: { id } }
- * POST /ecom/v1/carts/{id}/create-checkout  { channelType: "OTHER_PLATFORM" }  → { checkoutId }
- */
-export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
-  const created = await wixRequest<Raw>("/ecom/v1/carts", { body: cartBody(campaignId, input) });
-  const cartId = rawId(created?.cart);
-  if (!cartId) throw new Error("Checkout couldn't start: no cart id returned.");
-  const res = await wixRequest<Raw>(`/ecom/v1/carts/${cartId}/create-checkout`, { body: { channelType: "OTHER_PLATFORM" } });
-  return checkoutIdOf(res);
-}
-
 /**
  * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
  * `origin` must be the site's real https origin as registered on the OAuth app's allowed domains.
+ * POST /ecom/v2/carts  { cart: { source: { channelType: "WEB" }, note? }, catalogItems: [{ quantity: 1, catalogReference: { appId, catalogItemId, options: { amount, frequency, donorCoveringFees? } } }] }  → { cart: { id } } (the cart is the checkout)
  * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }  → { redirectSession: { fullUrl } }
  */
 export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
   const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
-  let checkoutId: string;
+  let cartId: string;
   try {
-    checkoutId = await createDonationCheckout(campaignId, input);
-  } catch (direct) {
-    try {
-      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
-    } catch {
-      throw checkoutError(direct);
-    }
+    const res = await wixRequest<Raw>("/ecom/v2/carts", { body: cartBody(campaignId, input) });
+    cartId = cartIdOf(res);
+  } catch (e) {
+    throw checkoutError(e);
   }
-  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(checkoutId, campaignId, site, paths) });
+  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(cartId, campaignId, site, paths) });
   return redirectUrl(session);
 }
 

package/skills/wix-headless-templates/pricing-plans/INSTRUCTIONS.md

@@ -336,8 +336,10 @@ other road — an eCom checkout with one PLAN line item (`catalogItemId: plan.id
 must share one checkout with products (a cart holding a membership and a T-shirt). Both end on a
 Wix-hosted checkout with coupons, notes, and login handled there. The DTO carries
 `pricingVariantId` so the eCom path is reachable without touching the DTO if a brief needs it;
-building it means `@wix/ecom` `checkout.createCheckout` plus a redirect session with
-`ecomCheckout: { checkoutId }` — a new function beside `purchase.ts`, not a change to it.
+building it means adding the plan line (and any product lines) to the current cart with `@wix/ecom`
+`currentCartV2` — in Cart V2 the cart IS the checkout, so the cart's id is the id passed to a
+redirect session with `ecomCheckout: { checkoutId }` — a new function beside `purchase.ts`, not a
+change to it.
 
 ## Gated content — requires the `members` vertical
 

package/skills/wix-headless-templates/shared/capabilities/site-search/seed/install.mjs

@@ -29,9 +29,9 @@ if (!siteId) {
   console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
   process.exit(1);
 }
-const token = execFileSync("npx", ["-y", "@wix/cli@latest", "token", "--site", siteId], { encoding: "utf8" }).trim();
+const token = execFileSync("npx", ["-y", "@wix/cli@1.1.257", "token", "--site", siteId], { encoding: "utf8" }).trim();
 if (!token) {
-  console.log(JSON.stringify({ error: "the Wix CLI returned no token — run `npx @wix/cli@latest login` first" }));
+  console.log(JSON.stringify({ error: "the Wix CLI returned no token — run `npx @wix/cli@1.1.257 login` first" }));
   process.exit(1);
 }
 try {

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

@@ -1,12 +1,15 @@
 // The Wix CLI the seeds call for a site token and for `wix env pull`.
 //
 // Order: the project's own copy (node_modules/.bin/wix, installed with the template's lock), then
-// a `wix` on PATH, then `npx -y @wix/cli@latest` — which installs the CLI before running it, 20 to
+// a `wix` on PATH, then `npx -y @wix/cli@<pinned>` — which installs the CLI before running it, 20 to
 // 60 s and a wall of npm output on a fresh machine. The first two take under two seconds.
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
 
+// The CLI version the fallback installs; equal to `@wix/cli` in wix-headless-kit/install/pins.json.
+const WIX_CLI_VERSION = "1.1.257";
+
 export function resolveWixCli(cwd = process.cwd()) {
   const bin = process.platform === "win32" ? "wix.cmd" : "wix";
   const local = join(cwd, "node_modules", ".bin", bin);
@@ -19,7 +22,7 @@ export function resolveWixCli(cwd = process.cwd()) {
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (dir && existsSync(join(dir, bin))) return { file: join(dir, bin), prefix: [] };
   }
-  return { file: "npx", prefix: ["-y", "@wix/cli@latest"] };
+  return { file: "npx", prefix: ["-y", `@wix/cli@${WIX_CLI_VERSION}`] };
 }
 
 /**
@@ -33,7 +36,7 @@ export function wixToken(siteId, cwd = process.cwd()) {
   // An older CLI starts its "update available" box on the token's own line, so a line split is
   // not enough: the token is the first long run of token characters.
   const token = out.match(/[A-Za-z0-9._-]{40,}/)?.[0];
-  if (!token) throw new Error("The Wix CLI returned no token — run `wix login` (or `npx @wix/cli@latest login`) first.");
+  if (!token) throw new Error(`The Wix CLI returned no token — run \`wix login\` (or \`npx @wix/cli@${WIX_CLI_VERSION} login\`) first.`);
   return token;
 }
 

package/skills/wix-headless-templates/storefront/app/wix/storefront/cart.ts

@@ -167,8 +167,7 @@ export async function setNote(note: string): Promise<Cart> {
 /**
  * Start the Wix-hosted checkout for the current cart and return the URL to navigate to.
  * The cart's id IS the checkout id — no separate checkout-creation call (Wix's own storefront
- * does the same; `createCheckoutFromCurrentCart` is the alternative when a checkout must exist
- * before redirecting).
+ * does the same).
  * Call from the browser: the return origin must be the site's real https origin
  * (window.location.origin), never a server-derived request origin.
  */

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/cart.ts

@@ -167,8 +167,7 @@ export async function setNote(note: string): Promise<Cart> {
 /**
  * Start the Wix-hosted checkout for the current cart and return the URL to navigate to.
  * The cart's id IS the checkout id — no separate checkout-creation call (Wix's own storefront
- * does the same; `createCheckoutFromCurrentCart` is the alternative when a checkout must exist
- * before redirecting).
+ * does the same).
  * Call from the browser: the return origin must be the site's real https origin
  * (window.location.origin), never a server-derived request origin.
  */

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -16,7 +16,7 @@ Five ways to get the files live; what you have decides which are open to you.
 | Option | Needs | Carries | The user ends up with |
 | --- | --- | --- | --- |
 | **A.** `curl` + CLI token → [into the account](#publish-into-the-users-account) | A shell; a Wix CLI login | Anything on disk | A site in their account, final URL |
-| **B.** `ExecuteWixAPI` → [into the account](#publish-into-the-users-account) | The Wix MCP | Small text files already in the conversation | A site in their account, final URL |
+| **B.** `ExecuteWixAPI` → [into the account](#publish-into-the-users-account) | The Wix MCP | Files already in the conversation — text as is, small binaries as base64 — and anything downloaded from the site | A site in their account, final URL |
 | **C.** `curl` → [anonymous](#publish-anonymously) | A shell | Anything on disk | A live site for one hour; kept by a [claim](#claim-it-into-the-users-account) (through the Wix MCP or a CLI token) or the save link |
 | **D.** [The drop page](#the-drop-page) | Nothing | Whatever the user uploads | The same, after they upload it themselves |
 | **E.** [The headless skill](#keep-building-add-a-backend-when-you-need-one) | A shell; Node; a Wix CLI login | A project folder, source included (built for you) | A site in their account as a Wix Headless project, released with the Wix CLI, ready for Wix Business Solutions |
@@ -30,8 +30,13 @@ What sets them apart:
   byte is written out inside the call. That costs nothing extra for a page you
   generated or the user pasted (it's already in the conversation); for files on
   disk it means reading them in and writing them back out, and each change
-  resends all of it. A string body is sent as UTF-8, so binary files (PNG, JPG,
-  fonts, zips) arrive corrupted; link images by absolute URL.
+  resends all of it. Files travel in the tool's `files` param — text raw, a
+  binary file (PNG, JPG, fonts) as base64 — and `wix.multipart()` builds the
+  upload body (below). Base64 costs about a third more than the file and every
+  byte is tokens, so it suits small assets (an icon, a logo, a font) and files
+  you downloaded from the site to change; a photo goes in by absolute URL
+  (`<img src="https://…">`) or with `curl` from a shell. The bundle is capped at
+  4M characters.
 - **A CLI login** is one approval by the user in the browser: run
   `npx @wix/cli login` and have them approve; `npx @wix/cli token` then prints a
   token (see [Before the calls](#before-the-calls)). It also unlocks later
@@ -43,8 +48,8 @@ What sets them apart:
   the only one that takes framework source as is and leaves a project ready for a
   backend. A drop site can still move to it [later](#keep-building-add-a-backend-when-you-need-one).
 
-So: a small page already in the conversation, with the Wix MCP connected — B,
-shell or not. Static files on disk — A with a CLI login, else C (claimed through
+So: a site already in the conversation — pages, styles, a logo — with the Wix
+MCP connected — B, shell or not. Static files on disk — A with a CLI login, else C (claimed through
 the Wix MCP when it's connected). A framework project (a `package.json`), or a
 site that needs stores, bookings, a CMS or members from the start — E. Files out
 of your reach, or nothing above fits — D.
@@ -108,8 +113,27 @@ curl -sS -X POST \
   "siteUrl": "https://headless-zjfqzddjtww-northwind-1406.wix-site-host.com" }
 ```
 
-Option B — the same two calls as one `ExecuteWixAPI` script, for small text files
-already in the conversation:
+Option B — the same two calls as one `ExecuteWixAPI` script, for files already
+in the conversation. The files go in the tool's **`files` param**, not in
+`code`: one bundle, each file introduced by a line `=== FILE: <path> ===` and
+followed by its raw text, `<path>` relative to the site root. A binary file is
+introduced by `=== FILE: <path> base64 ===` and followed by its base64. Nothing
+in it is escaped, so quotes, backticks, `${}` and backslashes arrive as written.
+
+```
+=== FILE: index.html ===
+<!doctype html><html><head><title>Northwind Studio</title>
+<link rel="stylesheet" href="assets/styles.css"></head><body><h1>Northwind Studio</h1><img src="assets/logo.png"></body></html>
+=== FILE: assets/styles.css ===
+body { font-family: sans-serif; margin: 0; padding: 4rem; }
+=== FILE: assets/logo.png base64 ===
+iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==
+```
+
+In `code`, the bundle is the `files` global (`[{ path, content, encoding? }]`,
+`encoding: 'base64'` on the binary entries) and `wix.multipart()` turns it into
+the upload body: one part named `files` per file, the path as its filename, a
+content type guessed from the extension, base64 entries decoded to their bytes.
 
 ```javascript
 async function run() {
@@ -117,31 +141,21 @@ async function run() {
     url: 'https://www.wixapis.com/headless-business-setup/v1/headless-business/provision',
     body: { origin: 'drop', newMetasite: { namingStrategy: { metaSiteName: 'Northwind Studio' }, seedOptions: [] },
             synchronousSteps: ['SET_METASITE_NAME', 'CONFIGURE_HEADLESS_APP'] } });
-  // path → text content, as template literals. Escape \ as \\ first, then ` as \` and ${ as \${
-  // (an unescaped \ is dropped or reinterpreted: /\d+/ would arrive as /d+/).
-  const files = {
-    'index.html': `<!doctype html><html><head><title>Northwind Studio</title>
-<link rel="stylesheet" href="assets/styles.css"></head><body><h1>Northwind Studio</h1></body></html>`,
-    'assets/styles.css': `body { font-family: sans-serif; margin: 0; padding: 4rem; }`,
-  };
-  const boundary = '----wixdropboundary';
-  const body = Object.entries(files).flatMap(([path, text]) => [
-    '--' + boundary,
-    `Content-Disposition: form-data; name="files"; filename="${path}"`,
-    '', text,
-  ]).concat('--' + boundary + '--', '').join('\r\n');
+  const mp = wix.multipart();                                   // the `files` param; or pass [{ path, content | base64 | bytes }]
   return await wix.request({ scope: 'account', method: 'POST',
     url: `https://www.wixapis.com/headless-business-setup/v1/headless-business/${created.data.metaSiteId}/drop`,
-    headers: { 'Content-Type': 'multipart/form-data; boundary=' + boundary },
-    body });                                                          // a string body is sent verbatim
+    headers: { 'Content-Type': mp.contentType },
+    body: mp.body });
 }
 ```
 
 `wix.request` returns `{ status, data }`; read a response's fields from `data`
-(`created.data.metaSiteId`). Keep the body's shape exactly. It's a string; an
-object is sent as JSON and rejected. Lines end in `\r\n`, the body ends with
-`--<boundary>--`, and the header names the same boundary the body uses. Break any of these and the drop
-fails with a bare `500`.
+(`created.data.metaSiteId`). Don't build the multipart body by hand — a missing
+`\r\n` or a boundary mismatch is a bare `500` — and don't put file text inside
+`code` as string literals: that second layer of escaping is what corrupts
+backslashes and `${}`. Don't put image bytes in `code` either — they're a
+`base64` entry in `files`. The one thing `files` cannot carry is a file with a
+line that reads exactly `=== FILE: … ===`.
 
 `siteUrl` is the site's final address — it's already in the user's account. Give
 the user two links: `siteUrl`, and its dashboard at
@@ -169,24 +183,28 @@ unzip -o current.zip -d current      # the site's files + wix.config.json
 ```
 
 In an `ExecuteWixAPI` script, request the same URL with `responseType: 'base64'`
-and read the zip in memory. Entries are stored (method 0) or deflated (method 8):
+and unzip it in memory with `wix.unzip()`. Each entry is `{ path, bytes, text() }`:
+`bytes` is the file as stored, `text()` decodes it when it's text. Don't decode
+every entry — an image run through a text decoder is corrupted.
 
 ```javascript
 const r = await wix.request({ scope: 'account', method: 'GET', responseType: 'base64',
   url: `https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/${metaSiteId}/download.zip` });
-const z = Uint8Array.from(atob(r.data), (c) => c.charCodeAt(0));
-const u16 = (o) => z[o] | (z[o + 1] << 8), u32 = (o) => (u16(o) | (u16(o + 2) << 16)) >>> 0;
-let e = z.length - 22; while (u32(e) !== 0x06054b50) e--;            // end of central directory
-const files = {};
-for (let i = 0, p = u32(e + 16); i < u16(e + 10); i++) {            // one central-directory entry each
-  const name = new TextDecoder().decode(z.slice(p + 46, p + 46 + u16(p + 28)));
-  const at = u32(p + 42), start = at + 30 + u16(at + 26) + u16(at + 28);
-  const raw = z.slice(start, start + u32(p + 20));
-  files[name] = u16(p + 10) === 0 ? new TextDecoder().decode(raw)
-    : await new Response(new Blob([raw]).stream().pipeThrough(new DecompressionStream('deflate-raw'))).text();
-  p += 46 + u16(p + 28) + u16(p + 30) + u16(p + 32);
-}
-// files: { 'index.html': '…', 'assets/styles.css': '…', 'wix.config.json': '…' }
+const entries = await wix.unzip(r.data);
+// entries: [{ path: 'index.html', bytes, text() }, { path: 'assets/logo.png', bytes, text() }, { path: 'wix.config.json', … }]
+```
+
+Edit in memory — text through `text()`, binaries left as they are — then drop
+the full set back in the same script, leaving `wix.config.json` out. Entries go
+to `wix.multipart()` as they are; an edited file replaces its entry with
+`{ path, content }`:
+
+```javascript
+const edited = entries.filter((e) => e.path !== 'wix.config.json').map((e) =>
+  e.path === 'index.html' ? { path: e.path, content: e.text().replace('Northwind Studio', 'Northwind Studio — Est. 1998') } : e);
+const mp = wix.multipart(edited);
+await wix.request({ scope: 'account', method: 'POST', headers: { 'Content-Type': mp.contentType }, body: mp.body,
+  url: `https://www.wixapis.com/headless-business-setup/v1/headless-business/${metaSiteId}/drop` });
 ```
 
 The live URL itself (`*.wix-site-host.com`) can't be read from a script; this
@@ -219,7 +237,8 @@ Keep both: `metaSiteId` addresses the site, `projectId` builds the save link.
 ### 2. Upload the files
 
 Same multipart shape as the [drop](#2-drop-the-files--the-site-goes-live), to the
-upload path, with the attribution parameters:
+upload path, with the attribution parameters (in a script: `wix.multipart()` with
+the `files` param, posted to this URL):
 
 ```bash
 curl -sS -X POST \
@@ -323,7 +342,7 @@ Failures come back as HTTP 400 with a code in `details.applicationError.code`:
 - **`403 PERMISSION_DENIED` on a drop** — the token expired or is missing (see
   [Before the calls](#before-the-calls)), or the site isn't the caller's. A site
   that's still anonymous is changed by upload + release, not by a drop.
-- **`500` on a drop or upload** — the multipart body is malformed (see the shape
+- **`500` on a drop or upload** — the multipart body was built by hand and is malformed (see the shape
   above). Rebuild it from the example; sending it again unchanged fails the
   same way.
 - **`404` on the anonymous route after step 1** — the hour passed or the site was