@wix/agent-skills 1.30.0 → 1.31.1

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

@@ -5,287 +5,300 @@ description: Publish a user's ready-made website — an index.html, a static bui
 
 # Upload a Website or HTML Files
 
-The user has a finished website as files — hand-written HTML, a static build, a
-zip, or the output of an AI site builder — and wants it live on Wix as a static,
-Wix-hosted site.
-
-## Choose the route
-
-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 | 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 |
-
-What sets them apart:
-
-- **`curl -F` streams files from disk** — the bytes never pass through you: any type, any
-  number, up to the [limits](#what-the-upload-accepts-and-how-it-fails).
-- **`ExecuteWixAPI` has no filesystem.** The Wix MCP's tool runs JavaScript whose
-  `wix.request` calls carry the user's login — no install, no token — but every
-  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. 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
-  changes from disk and
-  [Keep building](#keep-building-add-a-backend-when-you-need-one).
-- **Anonymous** needs no identity, but the record expires after an hour and the
-  URL changes on claim.
-- **The headless skill** is the heaviest — an install, a project, a build — and
-  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 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.
-
-Publishing yourself beats the drop page whenever an option fits — the user gets a
-live site without uploading anything. Never report an upload you couldn't
-perform; whenever a route fails partway, hand over the drop page.
+The user has a finished website — hand-written HTML, a static build, a zip, a
+project an AI builder exported — and wants it live on Wix. Every route below ends
+the same way: a headless site in the user's Wix account that serves those files
+at a `*.wix-site-host.com` URL.
+
+## What decides the route
+
+Three things about where you run decide it:
+
+- **Does your shell reach Wix?** `curl -sI https://www.wixapis.com` answers with an
+  HTTP status line. When it fails, or there is no shell, it doesn't.
+- **Is the Wix MCP connected?** Its tools are in your tool list: `ExecuteWixAPI`,
+  and usually `UploadHeadlessWebsiteFiles`.
+- **Do your files travel as files?** Some clients resolve a tool's `attachments`
+  param themselves: a file the user attached, or one you wrote to disk, reaches
+  the upload tool as the file. Elsewhere `attachments` comes back unresolved, and
+  every file you send through the MCP is text you write into the call.
+
+| Your situation | Route |
+| --- | --- |
+| The shell reaches Wix | [Create the site](#create-the-site) and [drop the files with `curl`](#drop-with-curl) and a CLI token; without a login, [publish anonymously](#publish-anonymously). A site of text files can take the MCP route below instead, with no login. |
+| The shell doesn't reach Wix, or there is no shell, and the Wix MCP is connected | [Create the site](#create-the-site) and [drop through the MCP](#drop-through-the-wix-mcp): the files themselves when they travel as files, a text bundle when they don't. |
+| A project that needs a build (a `package.json`) | Build it where its dependencies install, then drop the build output. When the shell reaches Wix, the [headless skill](#connect-a-backend) builds and releases it. When it can't be built anywhere you are, ask the user for the build output. |
+| None of these, or every route failed | The [drop page](#the-drop-page): the user uploads the files. |
+
+When files don't travel as files, writing them costs nothing for a page already
+in the conversation and a read and a rewrite for text files on disk; images never
+travel as text (see [Images](#images)). Publishing yourself beats the drop page
+whenever a route fits. Never report an upload you couldn't perform; when a route
+fails partway, hand over the drop page.
 
 ## Before the calls
 
-The `curl` examples here and in the anonymous route read shell variables.
-
-- **`$ACCESS_TOKEN`** is the user's access token, from wherever you have it. A
-  token from the Wix CLI (`npx @wix/cli token`) lasts 15 minutes; running the
-  command again returns a valid one, refreshed if needed, so set `$ACCESS_TOKEN`
-  again when it may have expired, and always after a `403`.
-- **`$META_SITE_ID`, `$UPLOAD_ID`, …** come from the previous response; set each
-  one before the next call.
-
-In an `ExecuteWixAPI` script there is no token to handle, and the ids go into the
-URL as values; a `$NAME` there is sent as is.
-
-## Publish into the user's account
-
-### 1. Create the site
+- **With a shell that reaches Wix**, `$ACCESS_TOKEN` is the user's token: run
+  `npx @wix/cli@latest login` once (the user approves in the browser), then
+  `npx @wix/cli@latest token` prints a token that lasts 15 minutes. Run it again
+  when the token may have expired, and always after a `403`.
+- **Through the Wix MCP**, `ExecuteWixAPI` runs JavaScript
+  whose `wix.request` calls carry the user's login: no token. Ids go into URLs as
+  values; a `$NAME` there is sent as is. `wix.request` returns `{ status, data }`.
+- **`$AGENT`** is a short lowercase slug naming you (`claude-code`, `cursor`,
+  `codex-cli`, `chatgpt`, `claude-ai`; `unknown-agent` if you can't tell). Every drop and upload
+  carries `?campaign=mcp&agent=$AGENT`, which attributes the site to you in Wix's
+  reports.
+- **`$META_SITE_ID`, `$UPLOAD_ID`, …** come from the previous response.
+
+**Reading the pages this recipe links.** A Wix skill you have installed is read
+from disk. Otherwise a `www.wix.com/skills/…` or `dev.wix.com/docs/…` page is read
+with the Wix MCP's `ReadFullDocsArticle` when the MCP is connected; it returns the
+page whole. A web fetch is the fallback.
+
+## Create the site
 
 The [Create Headless Site](create-headless-site.md) call with no Wix Business
-Solutions. Name it after the page's `<title>`, and keep `"origin": "drop"`: it marks
-the site as a dropped one, the same as the drop page and the anonymous route do.
+Solutions. Name it after the page's `<title>` and keep `"origin": "drop"`.
 
 ```bash
 curl -sS -X POST "https://www.wixapis.com/headless-business-setup/v1/headless-business/provision" \
   -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
   -d '{"origin":"drop","newMetasite":{"namingStrategy":{"metaSiteName":"Northwind Studio"},"seedOptions":[]},
        "synchronousSteps":["SET_METASITE_NAME","CONFIGURE_HEADLESS_APP"]}'
+# {"metaSiteId":"7597a72e-bedc-4d86-af86-9a25d11f0632","appId":"9f0a8b59-1acb-4a67-aafd-f8602259cbfa"}
 ```
 
-```json
-{ "metaSiteId": "7597a72e-bedc-4d86-af86-9a25d11f0632", "appId": "9f0a8b59-1acb-4a67-aafd-f8602259cbfa" }
+In a script, the same call:
+
+```javascript
+const created = await wix.request({ scope: 'account', method: 'POST',
+  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'] } });
+// created.data.metaSiteId
 ```
 
-### 2. Drop the files — the site goes live
+The site is in the user's account. When it goes live, give the user its
+`siteUrl` and the dashboard, `https://manage.wix.com/dashboard/{metaSiteId}`.
+
+## Drop with curl
 
 One multipart request uploads and releases. Each file is a part named `files`
-whose **filename is its path relative to the site root** — that is how
-subdirectories survive; with `curl`, set it with `;filename=` whenever it isn't
-just the basename. A single `.zip` part works too — it's unpacked server-side, a
-single wrapping folder stripped.
+whose **filename is its path relative to the site root**; that is how
+subdirectories survive. A single `.zip` part works too: it is unpacked
+server-side, a single wrapping folder stripped.
 
 ```bash
 curl -sS -X POST \
-  "https://www.wixapis.com/headless-business-setup/v1/headless-business/$META_SITE_ID/drop" \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/$META_SITE_ID/drop?campaign=mcp&agent=$AGENT" \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -F "files=@index.html;filename=index.html" \
   -F "files=@assets/styles.css;filename=assets/styles.css" \
   -F "files=@assets/logo.png;filename=assets/logo.png"
+# {"uploadId":"c0d5b3bb-…","siteUrl":"https://headless-zjfqzddjtww-northwind-1406.wix-site-host.com"}
 ```
 
-```json
-{ "uploadId": "c0d5b3bb-60a9-43f9-9d27-7ca8df967825",
-  "siteUrl": "https://headless-zjfqzddjtww-northwind-1406.wix-site-host.com" }
-```
+`siteUrl` is final.
+
+## Drop through the Wix MCP
+
+### With the Wix MCP's upload tool
+
+When the Wix MCP lists `UploadHeadlessWebsiteFiles`, it is the drop: pass it the
+`metaSiteId` from [Create the site](#create-the-site) as `siteId`, and the files.
+It replaces the whole file set, stamps the attribution itself, and returns
+`siteUrl` and the dashboard link. It creates no site and makes no other call.
 
-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.
+- **When your files travel as files**, pass them as `attachments`: zip the whole
+  site folder, images included, and pass the zip as one attachment. It is
+  unpacked, a wrapping folder stripped, up to 10 MB per call. Nothing is written
+  out by you. Where `attachments` doesn't resolve, a path passed in it fails:
+  your files don't travel as files, and they go in the bundle below.
+- **When they don't**, pass a `files` text bundle: each file starts with a line
+  `=== FILE: <path> ===` followed by its raw text, `<path>` relative to the site
+  root. Nothing in it is escaped. It carries text files: HTML, CSS, JavaScript,
+  SVG. Other images reach the site as [Images](#images) says.
 
 ```
 === 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>
+<link rel="stylesheet" href="assets/styles.css"></head><body><h1>Northwind Studio</h1><img src="assets/logo.svg"></body></html>
 === FILE: assets/styles.css ===
 body { font-family: sans-serif; margin: 0; padding: 4rem; }
-=== FILE: assets/logo.png base64 ===
-iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==
+=== FILE: assets/logo.svg ===
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="4"/></svg>
 ```
 
-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.
+The bundle can't carry a file with a line that reads exactly `=== FILE: … ===`.
+
+### From an ExecuteWixAPI script
+
+Without the upload tool, both calls run in one script. The same bundle goes in
+the tool's **`files` param**, never in `code`; in `code` it is the `files` global
+(`[{ path, content, encoding? }]`), and `wix.multipart()` turns it into the body.
 
 ```javascript
 async function run() {
+  const agent = 'your-agent-slug';         // $AGENT
   const created = await wix.request({ scope: 'account', method: 'POST',
     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'] } });
-  const mp = wix.multipart();                                   // the `files` param; or pass [{ path, content | base64 | bytes }]
+  const mp = wix.multipart();              // from 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': mp.contentType },
-    body: mp.body });
+    url: `https://www.wixapis.com/headless-business-setup/v1/headless-business/${created.data.metaSiteId}/drop?campaign=mcp&agent=${agent}`,
+    headers: { 'Content-Type': mp.contentType }, body: mp.body });
 }
 ```
 
-`wix.request` returns `{ status, data }`; read a response's fields from `data`
-(`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
-`https://manage.wix.com/dashboard/{metaSiteId}`.
-
-### Change it later
-
-Re-run step 2 on the same `metaSiteId` with the **full** file set: each drop
-replaces the site's files (a file left out is gone), and `siteUrl` stays the same.
-Never create another site for a change. The same call updates any site the user
-owns that was published this way, including one claimed from an
-[anonymous publish](#publish-anonymously). For a site from an earlier conversation,
-find its `metaSiteId` with the [Query Sites](#claim-it-into-the-users-account) call
-below, matching the site's name or `viewUrl`.
-
-**When you no longer have the files** (a small change to a site from an earlier
-conversation), download what the site serves, edit it, and drop the full set
-back. Leave out `wix.config.json`; the download adds it, and it isn't part of the
-site.
+A zip passed through `attachments` is one entry; unpack it first:
+`wix.multipart(await wix.unzip(files[0].content))`. Don't build a multipart body
+by hand while `wix.multipart()` exists (a malformed one is a bare `500`).
+
+**An older `ExecuteWixAPI` with no `files` param** still has `wix.multipart()`:
+pass it the entries written in `code`, `[{ path, content }]`, the text as template
+literals. Escape `\` as `\\` first, then `` ` `` as `` \` `` and `${` as `\${`; an
+unescaped `\` is dropped or reinterpreted. Only when
+`typeof wix.multipart !== 'function'` is the body a string you build: parts named
+`files` with the path as `filename`, lines ending in `\r\n`, the body ending with
+`--<boundary>--`, and `Content-Type: multipart/form-data; boundary=<the same
+boundary>`.
+
+## Change it later
+
+On the same `metaSiteId`, never a new site. Each drop replaces every file, and
+`siteUrl` stays.
+
+- **With a shell that reaches Wix**, edit the files and drop the full set with
+  `curl`.
+- **Through the MCP**, change the site in one `ExecuteWixAPI` script: download
+  what it serves, edit in code, and drop the full set back. Only the edit is
+  written; images travel back as they are. When your files travel as files, a
+  new zip of the whole site through the upload tool works as well. A full
+  rewrite of the text bundle is for a site rewritten wholesale.
+
+For a site from an earlier conversation, find its `metaSiteId` with
+[Query Sites](#claim-it-into-the-users-account), matching the name or `viewUrl`.
+The download holds what the site serves plus a `wix.config.json`, which is left
+out of the drop:
 
 ```bash
 curl -sSL -o current.zip \
   "https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/$META_SITE_ID/download.zip"
-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 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.
+In a script, request that URL with `responseType: 'base64'` and pass `r.data` to
+`wix.unzip()`. Each entry is `{ path, bytes, text() }`; call `text()` only on text
+files, since a decoded image is corrupted. Entries go back to `wix.multipart()` as
+they are, an edited one as `{ path, content }`:
 
 ```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 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` });
+const entries = (await wix.unzip(r.data)).filter((e) => e.path !== 'wix.config.json').map((e) =>
+  e.path === 'index.html' ? { path: e.path, content: e.text().replace('Welcome', 'Bloom Cafe — Now Open') } : e);
+const mp = wix.multipart(entries);
+// then the drop call: headers { 'Content-Type': mp.contentType }, body mp.body
 ```
 
-The live URL itself (`*.wix-site-host.com`) can't be read from a script; this
-download is the way back to the files. Don't rebuild the site from memory.
+Never rebuild a site from memory.
+
+## Connect a backend
+
+A dropped site is static. Stores, payments, bookings, a CMS, members or forms
+need a **Wix Headless project**, which the headless skill builds and releases on
+the same site, appId and URL.
+
+**A mock that shows a business solution: publish it, then ask before connecting.**
+Any control on the page that promises what static files can't deliver —
+something to buy, book, order, join, submit or pay — is a Wix Business Solution
+the page pretends to have. First get the site live from what the user gave you.
+Then, with the live URL, name each such control, the solution that would make it
+work, and what connecting it involves: what gets created from the page's own
+content (the products, services or form). Ask whether to go ahead, and connect only after the user says
+yes; a request that already asks for it (a working shop, real bookings) is that
+yes. A page that promises nothing beyond its content stops at the pages.
+
+A site published anonymously is [claimed](#claim-it-into-the-users-account)
+before a backend: the headless skill works on a site in the user's account.
+
+The headless skill starts at its cold-start page,
+`https://www.wix.com/skills/headless-cold-start/headless-kit.md` (read it as
+[Before the calls](#before-the-calls) says). It installs the skills, runs a
+bootstrap that checks the Wix CLI login, and hands off to the kit's `SKILL.md`,
+which reads the folder, deploys the solution's code, seeds, builds and releases.
+Its commands run:
+
+- **With a shell that reaches Wix**, in a folder holding the site, from the
+  site's own download:
+
+  ```bash
+  curl -sSL -o project.zip \
+    "https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/$META_SITE_ID/download.zip"
+  unzip project.zip -d project
+  ```
+- **Through the Wix MCP alone**, the kit's API-call guide,
+  `https://www.wix.com/skills/wix-headless-kit/guides/api-run.md`, does the same
+  run as Wix API calls through the Wix MCP, with the frontend dropped as this
+  recipe says.
+
+## Images
+
+You never write an image's bytes yourself, as base64 or in any other form: model
+output corrupts them past a few thousand characters, and every byte costs tokens.
+An SVG is text and goes in like a page. Every other image reaches Wix one of four
+ways:
+
+1. **With a shell that reaches Wix**, in the `curl` drop, from disk.
+2. **When your files travel as files**, inside the zip you pass the upload tool.
+3. **A public URL**: the page keeps the absolute URL.
+4. **The user uploads it** to the site's Media Manager. This is the way for images
+   that exist only as files you can't send. Publish the pages first, then name
+   the missing files, give the user
+   `https://manage.wix.com/dashboard/{metaSiteId}/media-manager`, and ask them to
+   tell you once they're uploaded. Then [list the site's files](../media/upload-media-to-wix.md),
+   match each to the page's reference by `displayName`, point the reference at the
+   file's `static.wixstatic.com` URL, and drop again.
+
+Never stand in drawings or placeholders of your own for the user's images, and
+never shrink or re-encode them. The closing message names every image still
+missing.
 
 ## Publish anonymously
 
-No identity needed: the site is created under a temporary owner and lives for one
-hour unless the user keeps it.
-
-Generate `anonymousId` yourself — any UUID, **once per site, not once per
-request** — and reuse it, with the returned `metaSiteId`, for every call for that
-site. **Finish within one hour of step 1**: after that the record expires and
-every later call, claim included, returns `404`.
-
-### 1. Create the site
+With a shell that reaches Wix and no login: the site belongs to a temporary owner and
+lives one hour unless the user keeps it. Generate `anonymousId` yourself, any
+UUID, once per site, and reuse it with the returned `metaSiteId` for every call.
+After one hour every call, claim included, returns `404`.
 
 ```bash
-curl -sS -X POST \
-  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID"
-```
-
-```json
-{ "metaSiteId": "f0ad8672-09e9-4111-b6fe-070c70bd2df5",
-  "projectId":  "54528d34-b23c-4fbe-b07d-2c522350abd7" }
-```
-
-Keep both: `metaSiteId` addresses the site, `projectId` builds the save link.
-
-### 2. Upload the files
+# 1. create
+curl -sS -X POST "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID"
+# {"metaSiteId":"f0ad8672-…","projectId":"54528d34-…"}
 
-Same multipart shape as the [drop](#2-drop-the-files--the-site-goes-live), to the
-upload path, with the attribution parameters (in a script: `wix.multipart()` with
-the `files` param, posted to this URL):
-
-```bash
+# 2. upload: the drop's multipart shape; nothing is live yet
 curl -sS -X POST \
   "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/upload?campaign=mcp&agent=$AGENT" \
-  -F "files=@index.html;filename=index.html" \
-  -F "files=@assets/styles.css;filename=assets/styles.css"
-```
-
-```json
-{ "uploadId": "03244542-d820-42f6-acfa-166c6658b1a6" }
-```
-
-Keep `campaign=mcp` (the referral tag — don't change it) and set `agent` to your
-own identifier: a short, stable, lowercase-hyphenated slug for the coding agent or
-tool you are (e.g. `claude-code`, `cursor`, `codex-cli`, `windsurf`,
-`github-copilot`, or your product's name; `unknown-agent` if you can't name
-yourself). Nothing is live yet; this only stages and validates.
-
-### 3. Release — the site goes live
+  -F "files=@index.html;filename=index.html" -F "files=@assets/styles.css;filename=assets/styles.css"
+# {"uploadId":"03244542-…"}
 
-```bash
+# 3. release: the site goes live
 curl -sS -X POST \
   "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/release" \
   -H 'Content-Type: application/json' -d "{\"uploadId\":\"$UPLOAD_ID\"}"
+# {"siteUrl":"https://instant-hguwrvtcrniw-headlessstack-140d.wix-site-host.com"}
 ```
 
-```json
-{ "siteUrl": "https://instant-hguwrvtcrniw-headlessstack-140d.wix-site-host.com" }
-```
-
-**To change it**, re-run steps 2–3 with the same `anonymousId` and `metaSiteId` and
-the full file set; `siteUrl` stays the same. Never go back to step 1 for a change.
-Iterate first, claim last: after a claim, changes are a [drop](#change-it-later),
-which needs the user's identity — a CLI token for files on disk.
-
-**When it's final:** with the user's identity, [claim it](#claim-it-into-the-users-account).
-Without it, stop here — a finished result. Give the user `siteUrl` plus the save
-link, which is how the site survives:
+To change the site, repeat steps 2 and 3 with the full file set. When it's final,
+claim it with the user's identity. Without one, give the user `siteUrl` and the
+save link, which signs them in to keep the site. Whoever opens the link while
+signed in to Wix gets the site, so give it only to the user:
 
 ```
 https://www.wix.com/live-headless-site/{projectId}?anonymousId={anonymousId}
 ```
 
-That page shows the site with a countdown and signs the user in to keep it. Treat
-the link as a secret — whoever opens it while signed in to Wix claims the site
-into *their* account — so give it only to the user who asked.
-
 ### Claim it into the user's account
 
 ```bash
@@ -294,14 +307,11 @@ curl -sS -X POST \
   -H "Authorization: Bearer $ACCESS_TOKEN"
 ```
 
-Returns `{}`. Claim after the release, never before — it consumes the anonymous
-record, so the anonymous endpoints stop working for this site; later changes go
-through the [drop](#change-it-later).
-
-**The URL changes on claim**: the step-3 host stops resolving. Read the new one
-with [Query Sites](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites),
-filtered to the `HEADLESS` namespace (the default query omits headless sites, and
-an `id` filter is rejected, so match the id yourself):
+Claim last: it ends the anonymous record, and later changes are
+[drops](#change-it-later). **The URL changes on claim.** Read the new `viewUrl`
+with Query Sites in the `HEADLESS` namespace; the default query omits headless
+sites and rejects an `id` filter, so match the id yourself, paging with
+`metadata.cursors.next`:
 
 ```bash
 curl -sS -X POST "https://www.wixapis.com/site-list/v2/sites/query" \
@@ -309,85 +319,54 @@ curl -sS -X POST "https://www.wixapis.com/site-list/v2/sites/query" \
   -d '{"query":{"filter":{"namespace":"HEADLESS"},"cursorPaging":{"limit":100}}}'
 ```
 
-Take `viewUrl` from the entry whose `id` is your `metaSiteId` (page with
-`metadata.cursors.next` if needed), and give the user it plus
-`https://manage.wix.com/dashboard/{metaSiteId}`.
-
 ## The drop page
 
 ```
 https://www.wix.com/headless/drop?utm_campaign=mcp&agent=<your-agent-id>
 ```
 
-Keep `utm_campaign=mcp` and set `agent` to your own identifier, as in the
-[upload](#2-upload-the-files). The user drags in their files (no login), Wix hosts
-them on a live URL at once, and a banner offers to sign in and keep the site. Tell
-them the [requirements](#what-the-upload-accepts-and-how-it-fails) so it doesn't
-fail on the first try.
+The user drags in the files without logging in, the site is live at once, and a
+banner offers to keep it. Tell them the limits below first.
 
-## What the upload accepts, and how it fails
+When no route reached Wix from where you are, say what would let you publish it
+yourself: a shell whose network reaches Wix, or the Wix MCP connected (the Wix
+plugin or connector in a chat client).
 
-These apply to every route:
+## Limits and failures
 
-- **A top-level HTML file is required.** A lone top-level HTML of any name becomes
-  the homepage; with more than one, an `index.html` must be among them.
+- **A top-level HTML file.** A lone one of any name is the homepage; with more
+  than one, `index.html` must be among them.
 - **3 MB per file, 20 MB per site.**
-- **Static files only** — HTML, CSS, JS, images, fonts. Framework source that
-  needs a build step (a `package.json`, React/Vue sources) must be built first;
-  upload the build output, or take the project to the headless skill (option E).
-
-Failures come back as HTTP 400 with a code in `details.applicationError.code`:
-`MISSING_INDEX_HTML`, `FILE_TOO_LARGE`, `TOTAL_TOO_LARGE`. Beyond those:
-
-- **`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 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
-  claimed; start again.
-
-**If publishing fails for any reason you can't quickly fix, hand the user the
-[drop page](#the-drop-page).** Never leave them with a failed publish and no way
-forward.
-
-## Keep building: add a backend when you need one
-
-The headless skill, `https://wix.com/headless/skill.md`, builds and releases a
-**Wix Headless project** with the Wix CLI: it adopts a project folder (a
-`package.json`, or an `index.html` at its root) into a new site, or takes a
-dropped one. A dropped site is **static**; when it needs a real backend — stores,
-payments, bookings, a CMS, members, forms — it moves to a headless project,
-keeping the same site, appId and URL. This is a choice the user makes when the
-need appears; static changes never need it, they're a [drop](#change-it-later).
-
-To move a dropped site, in a shell, once it's in the user's account:
+- **Static files only** in a drop. A project that needs a build is built first,
+  and its build output is dropped.
 
-```bash
-curl -sSL -o project.zip \
-  "https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/$META_SITE_ID/download.zip"
-unzip project.zip -d project      # the site's files + wix.config.json
-```
+| Failure | Meaning |
+| --- | --- |
+| `400` `MISSING_INDEX_HTML`, `FILE_TOO_LARGE`, `TOTAL_TOO_LARGE` | In `details.applicationError.code`; fix the files. |
+| `403 PERMISSION_DENIED` on a drop | The token expired or is missing, or the site isn't the caller's. An anonymous site takes upload and release, not a drop. |
+| `500` on a drop or upload | A malformed multipart body; rebuild it as shown. The same body fails again. |
+| `404` on the anonymous route | The hour passed or the site was claimed. |
+
+## Send feedback to Wix
 
-Then follow the headless skill from that folder: it turns the files into a
-headless project bound to the same site, released with the Wix CLI from then on.
+When this flow didn't work well enough, offer to send it to Wix as feedback,
+following [Send Feedback to Wix](send-feedback-to-wix.md): a route failed and you
+fell back, a call errored or needed retries, images had to wait on the user, or
+the recipe left you guessing and you had to invent a
+workaround.
 
 ## Route the request correctly
 
-- **A new site from the user's files** — [Choose the route](#choose-the-route).
-- **A change to a site published this way** — the same site, full file set: a
-  [drop](#change-it-later) when it's in the user's account, upload + release while
-  it's anonymous.
-- **An anonymous site the user wants to keep** — [claim](#claim-it-into-the-users-account)
-  it, else the save link.
-- **A site that now needs a backend** — [Keep building](#keep-building-add-a-backend-when-you-need-one).
-- **Migrating a live site/store from another platform by URL, or CSV/TSV
-  exports** — [Site Import](site-import.md).
-- **Adding HTML, an embed, or code to an existing Wix site** — not this recipe
-  (that's custom code in the editor).
-- **Images, videos, or documents for a site** —
-  [Upload Media to Wix](../media/upload-media-to-wix.md).
-
-Don't create the site from a template — that makes an empty site, not a published
-copy of the user's files.
+- **A new site from the user's files**: [What decides the route](#what-decides-the-route).
+- **A change to a site published this way**: the [same site](#change-it-later);
+  upload and release while it's anonymous.
+- **An anonymous site the user wants to keep**: [claim it](#claim-it-into-the-users-account), or the save link.
+- **A site that now needs a backend**: [Connect a backend](#connect-a-backend).
+- **Migrating a live site or store from another platform by URL, or CSV/TSV
+  exports**: [Site Import](site-import.md).
+- **HTML, an embed or code inside an existing Wix site**: not this recipe; that is
+  custom code in the editor.
+- **Images, videos or documents for a site's media**: [Upload Media to Wix](../media/upload-media-to-wix.md).
+
+Don't create the site from a template: that makes an empty site, not a copy of
+the user's files.