@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -1,6 +1,6 @@
 ---
 name: "Upload a Website or HTML Files"
-description: Publish HTML, CSS, JavaScript or a static build as a Wix Headless website; inspect its deployed files and edit them on the same site and URL. Covers file and ZIP uploads, selective additions, replacements and deletions while preserving other files, full-site replacement, authenticated and anonymous publishing, verification, and connecting a Wix business backend. Use for files the user supplies or pages you create for them. Not for migrating a live site from another platform by URL or CSV (use Site Import), embedding code in an editor-built Wix site, or uploading assets to Media Manager.
+description: Publish HTML, CSS, JavaScript or a static build as a Wix Headless website; inspect its deployed files and edit them on the same site and URL. Covers file and ZIP uploads, selective additions, replacements and deletions while preserving other files, full-site replacement, authenticated and anonymous publishing, verification, and connecting a Wix business backend; a Wix Astro build is released as a server-rendered site rather than dropped. Use for files the user supplies or pages you create for them. Not for migrating a live site from another platform by URL or CSV (use Site Import), embedding code in an editor-built Wix site, or uploading assets to Media Manager.
 ---
 
 # Upload a Website or HTML Files
@@ -16,6 +16,7 @@ site and are not atomic against another editor.
 | Request | Flow |
 | --- | --- |
 | Publish files as a new site | [Choose an upload route](#before-the-calls), [create once](#create-the-site), upload, [verify](#verify-and-report). |
+| Publish a Wix Astro build | [Create once](#create-the-site) for a new site, then [release it](#release-a-wix-astro-build); it is not dropped. |
 | Inspect or edit a deployed site | [Find its ID](#find-an-existing-site), then [list, read or patch](#change-it-later). Do not create another site. |
 | Replace the entire deployed frontend | Confirm replacement of the serving frontend, then drop the complete intended file set on the same ID. |
 | Make a shop, bookings, forms or other business controls work | [Connect a backend](#connect-a-backend) on the same site. A static upload alone does not make them functional. |
@@ -28,7 +29,8 @@ to inspect files authorizes no writes. Do not create from a template: that
 creates an empty site rather than publishing the supplied files.
 
 Quick reference: [upload through MCP](#drop-through-the-wix-mcp) ·
-[upload with curl](#drop-with-curl) · [list/read](#list-and-read) ·
+[upload with curl](#drop-with-curl) ·
+[release an Astro build](#release-a-wix-astro-build) · [list/read](#list-and-read) ·
 [patch](#patch-files) · [ZIP fallback](#download-edit-drop-fallback) ·
 [images](#images) · [limits/errors](#limits-and-failures).
 
@@ -56,6 +58,18 @@ Build projects that need dependencies first, and upload only their static
 output. If your environment cannot build the project, ask for the build output.
 For a Wix business project, follow [Connect a backend](#connect-a-backend).
 
+### Static pages or a Wix Astro build
+
+| What you have | How it goes live |
+| --- | --- |
+| Static pages: HTML, CSS, JS, images, or a static build's output | **Dropped**, by every route in this recipe. |
+| A Wix Astro build: `.wix/build-metadata.json` beside `dist/`, written by `astro build` with the Wix hosting adapter | **Released** as a server-rendered site, by `UploadHeadlessWebsiteFiles` only: [release a Wix Astro build](#release-a-wix-astro-build). Never dropped. |
+
+A build's `dist/client/` dropped as static pages loses its server pages, and a
+drop or patch on a site whose live release is a build replaces the build with
+static files; nothing on the server stops that. [Change it later](#change-it-later)
+tells the two apart before any edit.
+
 The JavaScript examples below run in `ExecuteWixAPI`, not directly in a shell
 or browser. Without MCP, use the curl examples and edit downloaded files locally;
 `wix.request`, `wix.multipart` and `wix.headless.files` are sandbox utilities,
@@ -91,14 +105,14 @@ when available for Wix skill/docs URLs, with web fetch as fallback.
 ## Create the site
 
 Create only for a new site. Use the page title, at most 40 characters. Keep
-`origin: 'drop'`, empty `seedOptions`, and both synchronous steps:
+`origin: 'agent'` and both synchronous steps:
 
 ```javascript
 async function run() {
   return 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: [] },
+    body: { origin: 'agent',
+      newMetasite: { namingStrategy: { metaSiteName: 'Northwind Studio' } },
       synchronousSteps: ['SET_METASITE_NAME', 'CONFIGURE_HEADLESS_APP'] }
   });
 }
@@ -110,7 +124,7 @@ The shell equivalent:
 ```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"]}'
+  -d '{"origin":"agent","newMetasite":{"namingStrategy":{"metaSiteName":"Northwind Studio"}},"synchronousSteps":["SET_METASITE_NAME","CONFIGURE_HEADLESS_APP"]}'
 ```
 
 ## Drop through the Wix MCP
@@ -167,6 +181,50 @@ curl -sS -X POST \
 A single ZIP part also works: it is unpacked server-side with one wrapping
 folder stripped. `siteUrl` is the final address.
 
+## Release a Wix Astro build
+
+This recipe releases a build you have. Making one is the Wix Headless kit's run
+(`https://www.wix.com/skills/headless-cold-start/headless-kit.md`), which states
+its own requirements: Node, a reachable npm registry, the project's install. A
+sandbox with no network cannot make one.
+
+**Who releases from here:** the build has to reach `UploadHeadlessWebsiteFiles`,
+by one of two carriers. Check before starting, measured rather than assumed:
+
+| Carrier | Check |
+| --- | --- |
+| Attachments | Your client passes `attachments` as files (a local path swapped for a download URL when the call is made). The tool's `attachments` description names the clients that do; a client that is not named, or that shows no way to pass a file, has no attachment carrier, whatever its shell can do. |
+| A shell that reaches the internet | `curl -sI -m 25 https://s3.amazonaws.com` answers with S3's own headers: `x-amz-request-id`, and `Server: AmazonS3` unless a proxy in front rewrote the Server header to its own name. The upload URLs are on Amazon S3; a sandbox limited to a few hosts gets a proxy's refusal instead, an HTTP answer with neither header. A sandbox proxy can take ten seconds to answer. |
+
+With neither, no build is released from here. For a new site, publish static
+pages instead. For a site already released as a build, report that it cannot be
+changed from this environment, and change nothing.
+
+A build goes through `UploadHeadlessWebsiteFiles` and nothing else: no drop
+route takes it. The site stays the same, at the same URL, now server-rendered.
+
+- **Attached:** zip the project from its root after `astro build`, leaving out
+  `node_modules`, `.env*` and caches, and pass the ZIP as `attachments`. The
+  tool releases the build and stores the rest as the project's source in the
+  site's Code Store repository, where a later session continues from. A ZIP of
+  only `.wix/` and `dist/` releases too, storing no source.
+- **From a shell, without attachments:** two calls. `{ siteId, prepare: true, size }`
+  with the ZIP's `size` (`wc -c < build.zip`) answers with `curl` commands for
+  the build ZIP and, when the site's repository takes it, a source ZIP; run them
+  as given, then make the second call it names:
+  `{ siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes? }`. A 404 on the
+  second call means the upload URL expired: prepare again. A prepared upload is
+  finished by that second call and by nothing else: a release made another way
+  (the ZIP attached, say) leaves the prepared upload behind and releases without
+  its source, so a prepare that failed on the way is prepared again, not replaced
+  by another carrier.
+
+`expectedHeadRevisionId` is the repository revision the project started from:
+the `headRevisionId` the prepare returned for a project made in this run, or
+the `revision.id` it was [downloaded at](#a-site-released-as-a-wix-astro-build).
+`EXPECTED_HEAD_REQUIRED` or a 409 means the repository holds newer work:
+download it, carry the change over, and release again.
+
 ## Find an existing site
 
 Reuse the ID from the earlier upload. If only a name or URL is known, query the
@@ -192,7 +250,66 @@ Unclaimed anonymous sites instead use their saved ID and
 
 ## Change it later
 
-Use the same site ID and URL. With `ExecuteWixAPI`, prefer its file helpers
+Use the same site ID and URL. The file helpers and the ZIP fallback below edit
+static pages: they read the site's last drop and drop the result. A site whose
+live release is a Wix Astro build is changed in its project instead; a drop or
+patch there replaces the build with static files, and the server does not stop
+it. So first tell what is live.
+
+When this conversation published the site, or the user says how it was made,
+you know. Otherwise one read-only call tells, in `ExecuteWixAPI`:
+
+```javascript
+async function run() {
+  return wix.request({ scope: 'account', method: 'GET',
+    url: 'https://www.wixapis.com/headless-business-setup/v1/headless-business/META_SITE_ID/files' });
+}
+// 200 { revision, files: [{ path, size }] }: the live site is its last static drop
+```
+
+| Answer | What is live | Do |
+| --- | --- | --- |
+| `200` | Its last static drop | [Edit the static pages](#a-site-of-static-pages). |
+| `409 LIVE_SITE_CHANGED` | A release replaced the last drop: a Wix Astro build | [Change the project](#a-site-released-as-a-wix-astro-build). No drop, no patch. |
+| `404 SITE_CODE_NOT_FOUND` | Nothing was ever dropped | Open the live URL. Pages there mean a build released without a drop: change the project. Nothing there means an empty site: drop as for a new one. |
+
+### A site released as a Wix Astro build
+
+The project lives in the site's Code Store repository, which is the managed
+project whose id is the site's app id: `appId` in `wix.config.json`, or the
+companion app. In `ExecuteWixAPI`, in site scope:
+
+```javascript
+async function run() {
+  const siteId = 'META_SITE_ID';
+  const app = await wix.request({ scope: 'site', siteId, method: 'POST',
+    url: 'https://manage.wix.com/_api/companion-apps/v1/companion-apps/get-or-create', body: {} });
+  const appId = app.data.companionApp.id;
+  try {
+    const dl = await wix.request({ scope: 'site', siteId, method: 'POST',
+      url: `https://www.wixapis.com/codestore/v2/git-code-store-projects/${appId}/generate-download-url`, body: {} });
+    return { appId, downloadUrl: dl.data.downloadUrl, revision: dl.data.revision };
+  } catch (e) {
+    return { appId, repository: false, error: String(e.message).slice(0, 200) };
+  }
+}
+```
+
+- **A download URL:** from a shell, `curl -o project.zip "<downloadUrl>"` (the
+  URL is signed and lasts 5 minutes; `ExecuteWixAPI` cannot fetch it), unpack,
+  `npm ci`, make the change, `npx astro build`, and
+  [release the build](#release-a-wix-astro-build) with `revision.id` as
+  `expectedHeadRevisionId`. The download holds the project without
+  `node_modules` or `.env*` files. Without a shell that can build, report that
+  the site is a server-rendered project and change nothing.
+- **A 404 (`NOT_FOUND`, `GIT_BRANCH_NOT_FOUND`), or a repository whose root
+  holds `index.html` rather than a project:** the project's source was not
+  stored with the release. The site can be changed only from the project where
+  it was built; report that, and change nothing here.
+
+### A site of static pages
+
+With `ExecuteWixAPI`, prefer its file helpers
 for selective edits, not `UploadHeadlessWebsiteFiles`: sending only changed
 files to that upload tool would remove omitted files. Without MCP, go directly
 to the [ZIP fallback](#download-edit-drop-fallback).
@@ -466,12 +583,15 @@ Wix MCP.
   `index.html` or `index.htm`.
 - 20 MB per file and site; `UploadHeadlessWebsiteFiles` limits each call
   to 10 MB. Patch also limits the final snapshot to 2,000 files.
-- Drop serves static files, not unbuilt project source.
+- Drop serves static files, not unbuilt project source. A Wix Astro build is
+  [released](#release-a-wix-astro-build), not dropped.
 
 | Failure | Action |
 | --- | --- |
 | `400` with `MISSING_INDEX_HTML`, `FILE_TOO_LARGE`, `TOTAL_TOO_LARGE` | Read `details.applicationError.code` and fix the files. |
 | Drop `403 PERMISSION_DENIED` | Check token freshness and access to this site. An unclaimed anonymous site requires upload/release, not drop. |
+| `409 LIVE_SITE_CHANGED` from the files endpoint or a patch | The live site is a Wix Astro build, not its last drop: [change the project](#a-site-released-as-a-wix-astro-build). Do not drop. |
+| Release `400 EXPECTED_HEAD_REQUIRED` / `409` | The repository holds newer work than the project started from: download it, carry the change over, release again. |
 | Drop/upload `500` | Inspect current state before retrying once; retain the request ID if it fails again and offer the drop page. Hand-built malformed multipart can also cause this: use `wix.multipart`. |
 | Anonymous `404` | The hour expired or the site was claimed; do not create a replacement without explaining. |
 

package/skills/wix-readme/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: wix-readme
+description: "What the Wix plugin holds and how to work with Wix through it: the flow the Wix MCP README returns, an index of the plugin's skills with what each does, and the Wix MCP tools with what each does. Use when the plugin was just installed or when the user asks what the Wix plugin can do or which skill or tool fits a task."
+---
+
+# The Wix plugin
+
+The plugin is two things: skills, folders of instructions and shipped code for building on Wix, each with a `SKILL.md` at its root; and the Wix MCP server at `https://mcp.wix.com/mcp`, whose tools read and change the user's Wix sites and account. The skills say how; the tools do.
+
+## How to work with Wix through the plugin
+
+Every Wix task ends in one of two places: a call made now with the user's account, or code the user keeps that makes the same calls (an app, a headless site, a script). The way there is the same.
+
+1. **Start with `WixREADME`**, once per conversation. It returns this flow in full and the account's sites with their installed apps.
+2. **Pick the site.** The `siteId` comes from the site context; when several fit, ask. A business solution's API works only on a site with that app installed, and an app's version changes its endpoints, so check the site's apps first.
+3. **Find the method.** The first source that gives it: an earlier tool result in the conversation; else the skill that covers the task (the index below says what each is for), whose example is the model when it matches the case; else the docs, `SearchWixRESTDocumentation` or `BrowseWixRESTDocsMenu` for REST, the SDK, CLI, headless and apps searches for code, then `ReadFullDocsArticle` on the method's page.
+4. **Get the exact shape.** A request is modeled on an example that matches the case: a skill's recipe or template, or the method's docs page, when it shows the fields the case needs. That is enough. The schema is for what no example shows: a field, an enum, a filter or sort key (a closed list per method). `SearchWixAPISpec` on the method's docs URL returns the request and response schemas, the REST URL and the JavaScript SDK call; `ReadFullDocsMethodSchema` when it is not available.
+5. **Make the call, or write the code.** To do it now: `ExecuteWixAPI`, one function holding every step of the task, the reads and the writes they feed. For code the user keeps: write the call from the shape found in step 4, REST or SDK. `wix-headless-templates` is that code already written and verified, one folder per business solution, and `wix-headless-kit` builds a site on it.
+
+Throughout: nothing Wix-specific from memory. Every URL, id, setting location, product fact, request shape and field name comes from a skill, the docs tools, an earlier tool result or the user.
+
+## Creating a site
+
+A new Wix site is written in code and uploaded. `StartDeployWebsite` returns the guide for a site the agent writes or files the user brought; `StartHeadlessBuild` returns the guide for a site that needs Wix business features (a store, bookings, a CMS, members, payments and the rest). Each guide creates the site, uploads it and says what comes next; call one and follow it.
+
+What the guides stand on:
+
+- **One site, created once**, by the provision call (`POST .../headless-business-setup/v1/headless-business/provision`, `origin: 'agent'`), which returns `metaSiteId`, the id every later call takes. A site made earlier is found with `ListWixSites` and uploaded to again; the URL never changes.
+- **Static pages are dropped, a Wix Astro build is released.** A drop sends the complete file set each time. A build (`.wix/build-metadata.json` beside `dist/`) is released to Wix hosting, server-rendered, through `UploadHeadlessWebsiteFiles` only: as an attachment, or in two calls (`prepare: true` with the zip's `size`, then `uploadKey`) from a shell that reaches the internet. The project's source is stored with the release, and a later session continues the site from it.
+- **`UploadHeadlessWebsiteFiles`** takes `siteId` and the files, as `attachments` or the `files` text bundle, and returns the live URL and the dashboard. Without the MCP, the same drop is a `curl` multipart call, with or without a login.
+- **Business features** come from `wix-headless-kit`'s run on the same site and `appId`: apps installed and content seeded, the Astro project built from `wix-headless-templates`, the build released.
+
+To read more: the recipe, `wix-manage/references/sites/upload-static-site.md` (https://www.wix.com/skills/wix-manage/references/sites/upload-static-site.md): the calls for every route, drop and release, finding and changing a site, the anonymous route, limits and failures. The cold start (https://www.wix.com/skills/headless-cold-start/headless-kit.md): the headless build from a cold environment to the released site.
+
+## Two ways to Wix
+
+### The plugin with the Wix MCP
+
+The preferred way. The plugin's MCP configuration connects the Wix MCP server at `https://mcp.wix.com/mcp`; the client signs the user in on the first call and the tools below are in the tool list, with nothing to install. The flow above runs on them: `WixREADME` for the context, the documentation tools to find a method and its shape, `ExecuteWixAPI` to call it, `StartDeployWebsite` and `StartHeadlessBuild` with `UploadHeadlessWebsiteFiles` to create a site and put it live. The skills are read from the plugin's folder, and `ReadFullDocsArticle` reads them online when they are not there.
+
+Context first:
+
+| Tool | What it does |
+|---|---|
+| `WixREADME` | The context every other tool assumes. Call it once per conversation before a Wix task; for another site later, call `GetSiteContext` instead. |
+| `ListWixSites` | Lists the user's sites, with an optional name filter. Needs no `WixREADME` first. |
+| `GetSiteContext` | Deep context for one site, by name or id: its apps, settings and data, as markdown. |
+
+Building and deploying a site:
+
+| Tool | What it does |
+|---|---|
+| `StartDeployWebsite` | Returns the guide to create a site on Wix and put files on it: HTML, CSS and JS, a static build, a zip, another builder's export. Updates keep the site and URL. Works with or without a Wix login. |
+| `StartHeadlessBuild` | Returns the headless guide, for a site that needs Wix business features: a store, bookings, events, a restaurant menu, a blog, pricing plans, donations, forms, members, a CMS, payments. |
+| `UploadHeadlessWebsiteFiles` | The upload step of those two guides: puts a static site or a Wix Astro build onto an existing Wix Headless site by its metaSiteId, as files, as attachments, or in two calls with presigned URLs. |
+| `GetSuggestedDomains` | Domain name suggestions for a site. |
+
+Calling Wix APIs:
+
+| Tool | What it does |
+|---|---|
+| `ExecuteWixAPI` | Reads and changes a site's or account's data with one JavaScript function over the Wix REST API: chained calls, pagination, loops, the reads that feed the writes. The preferred way to call Wix APIs. |
+| `SearchWixAPISpec` | Inspects the Wix REST API spec and each method's JavaScript SDK call by running JavaScript against the index: the exact request and response shape, enums, the SDK import and signature. |
+
+Documentation:
+
+| Tool | What it does |
+|---|---|
+| `SearchWixRESTDocumentation` | Searches the Wix REST API docs. The starting point for finding an endpoint. |
+| `BrowseWixRESTDocsMenu` | Browses the REST docs as a menu, category by category. |
+| `SearchWixSDKDocumentation` | Searches the Wix JavaScript SDK docs. |
+| `SearchWixHeadlessDocumentation` | Searches the Wix Headless docs. |
+| `SearchWixCLIDocumentation` | Searches the Wix CLI docs: commands, local development, authentication. |
+| `SearchWixWDSDocumentation` | Searches the Wix Design System docs. |
+| `SearchBuildAppsDocumentation` | Searches the Wix Build Apps docs. |
+| `SearchDevelopmentDocumentation` | Broad Wix developer docs: platform concepts and guides, after the specific searches return nothing. |
+| `SearchWixHelpCenter` | Searches the Wix Help Center: how site owners do things by hand in the dashboard and editors. |
+| `ReadFullDocsArticle` | Reads a page in full by URL: a docs article or method page, a skill's `SKILL.md` or any of its files, a Help Center article. |
+| `ReadFullDocsMethodSchema` | The full request and response schema of one method, by its docs URL. |
+
+Media and feedback:
+
+| Tool | What it does |
+|---|---|
+| `UploadImageToWixSite` | Uploads images to a site's Media Manager and returns their URLs and media ids. |
+| `PickImagesForWixMedia` | Shows the user a file picker to upload images from their device to the Media Manager. |
+| `ReportIssueToWix` | Reports one problem with Wix's tools, APIs or docs to the Wix team, when the user asks for it. |
+
+### The Wix CLI
+
+The other way, from a shell. `@wix/cli` is Wix's command-line tool: it signs in to a Wix account, creates and manages Wix projects on disk, a Wix app or a Wix Headless site, builds them and releases them to Wix, and mints tokens for REST calls. Its session lives on the machine. All as `npx @wix/cli@latest <command>`:
+
+| Command | What it does |
+|---|---|
+| `login` | Signs in with a device code and writes the session to `~/.wix/auth/account.json`. |
+| `whoami` | Shows the signed-in account. |
+| `create` | Creates a Wix project with its site: for a headless site, the site, its OAuth app and hosting, and the project's `wix.config.json` (`siteId`, `appId`). |
+| `env pull` | Writes the project's environment to `.env.local`: the site's client id and the values the build reads. |
+| `build` | Builds the project for Wix: for an Astro site, `dist/` and `.wix/build-metadata.json`. |
+| `release` | Releases the build to Wix; the site keeps its URL. |
+| `token`, `token --site <siteId>` | Mints an admin token, account-scoped or site-scoped, for REST calls from a shell: `Authorization: Bearer <token>` (`wix-docs/references/CALLING.md`). |
+
+`wix-headless-kit` builds a Wix Headless site through the MCP's tools or through the CLI; a CLI session already on the machine makes its run the CLI route, where `install/setup.mjs` runs `create`, and `build` then `release` put the site live.
+
+Without the MCP, each tool is a plain HTTP call to the same backend. `wix-docs` covers these, with the request bodies, as its `curl` lane:
+
+| Tool | Without the MCP |
+|---|---|
+| `SearchWixRESTDocumentation`, `SearchWixSDKDocumentation`, `SearchWixHeadlessDocumentation`, `SearchWixCLIDocumentation`, `SearchWixWDSDocumentation`, `SearchBuildAppsDocumentation`, `SearchDevelopmentDocumentation` | `POST https://www.wixapis.com/mcp-docs-search/v1/docs/search` (or `/search/markdown`) with `search_term` and the `document_type` of that corpus. |
+| `BrowseWixRESTDocsMenu` | `POST https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse`. |
+| `ReadFullDocsArticle` | Append `.md` to any `https://dev.wix.com/docs/...` URL; a skill's file is `https://www.wix.com/skills/<skill>/<path>`. |
+| `SearchWixAPISpec`, `ReadFullDocsMethodSchema` | `POST https://mcp.wix.com/api/code-mode/search` with the same JavaScript. |
+| `ExecuteWixAPI` | The REST call itself, to `https://www.wixapis.com`, with a token: which identity a method takes and how to mint the token are in `wix-docs/references/CALLING.md`. |
+| `StartDeployWebsite`, `StartHeadlessBuild`, `UploadHeadlessWebsiteFiles` | `create`, `build` and `release` from a shell; the `wix-manage` recipe `references/sites/upload-static-site.md` creates a site and drops files over REST. |
+
+## Skills
+
+Each skill is a folder with a `SKILL.md` at its root that says what it does and which of its files to read when. A skill may already be on disk, in the plugin's folder or under `.agents/skills/<skill>/` after `npx skills add wix/skills`, or served by the client's skill tool; read it from there. Otherwise every file is online at `https://www.wix.com/skills/<skill>/<path>`, read with `ReadFullDocsArticle` or `curl`; `https://www.wix.com/skills/<skill>/` with the trailing slash lists the skill's files. Paths below are inside the skill's folder.
+
+### wix-headless-kit
+
+Online: https://www.wix.com/skills/wix-headless-kit/SKILL.md. On disk: the plugin's `skills/wix-headless-kit/`, or `.agents/skills/wix-headless-kit/`.
+
+Builds a Wix Headless site on shipped, verified `@wix/sdk` code: one typed data layer, hooks, components, Astro pages and a seed script per Wix business solution, from `wix-headless-templates`. The agent designs the presentation on those hooks and releases to Wix hosting. Runs as a CLI flow from a shell, or as Wix API calls through the MCP.
+
+**The cold start**, `wix-headless-cold-start/headless-kit.md` (https://www.wix.com/skills/headless-cold-start/headless-kit.md, what `StartHeadlessBuild` returns), takes a cold environment to where wix-headless-kit runs, then hands off to its `SKILL.md`. It measures three facts: the Wix MCP's tools in the tool list; Node 24.18 or later with `npm` reaching the registry; a way to get a build to `UploadHeadlessWebsiteFiles`, as an attachment or by `curl` to its upload URLs. The facts pick the route: all three, the plugin route (site through `ExecuteWixAPI`, Astro build here, release through the upload tool); MCP but no way to release a build, the API-call guide (`guides/api-run.md`, static pages in the upload tool's `files`); a Wix CLI session on the machine, the CLI route. The project folder comes first, with any handed-over files extracted into it. Skills on disk are used where they are; otherwise `CI=1 npx skills@latest add wix/skills --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes`, then `node .agents/skills/wix-headless-kit/install/templates.mjs` for the templates, and `install/bootstrap.mjs` on the CLI route.
+
+- `SKILL.md`: the steps of a build and the table of business solutions.
+- `guides/api-run.md`: the whole run as Wix API calls through the MCP, for an agent with no shell or a shell that cannot reach Wix.
+- `guides/capabilities.md`: which Wix product owns which feature, and what ships for it.
+- `guides/existing-site.md`: a new frontend for a Wix site that already has its content, and continuing a site built in an earlier session.
+- `guides/migration.md`: a site moving to code after "Go Headless" in its dashboard.
+- `guides/reference-mode.md`: a stack that cannot run the shipped React code.
+- `guides/feedback.md`: sending the user's feedback on building with Wix.
+- `install/`: the scripts of a run (`setup.mjs`, `attach.mjs`, `deploy.mjs`, `install.mjs`, `templates.mjs`, `context.mjs`, `bootstrap.mjs`, `check.mjs`) and `pins.json`, the pinned CLI and templates versions.
+
+### wix-headless-templates
+
+Online: https://www.wix.com/skills/wix-headless-templates/SKILL.md. On disk: the plugin's `skills/wix-headless-templates/`, or `.agents/skills/wix-headless-templates/`.
+
+The code wix-headless-kit builds from, one folder per business solution: `storefront`, `bookings`, `rentals`, `blog`, `cms`, `forms`, `members`, `events`, `restaurants`, `donations`, `pricing-plans`, `portfolio`, `faq`, plus `blank` and `shared`. Each folder holds:
+
+- `INSTRUCTIONS.md`: the playbook, with the contracts.
+- `app/`: the typed, framework-agnostic data layer over `@wix/sdk`, React hooks and reference components.
+- `app-astro/`: the Astro pages with owner-editable SEO.
+- `rest/`: the same data layer as plain REST calls, for a site without a bundler.
+- `seed/`: the seed script that fills the site from a plan, `SEED.md` as the plan's contract, and a reader of what the site already holds.
+- `project/`: the solution composed into the CLI's Astro scaffold.
+
+`compose.mjs` at the root composes a solution's layers into a project.
+
+### wix-manage
+
+Online: https://www.wix.com/skills/wix-manage/SKILL.md. On disk: the plugin's `skills/wix-manage/`, or `.agents/skills/wix-manage/`.
+
+REST recipes to configure and manage a site's business solutions, one recipe per task with the exact endpoints, request bodies and order of steps. `SKILL.md` is the index of every recipe by area, each a link. The recipes are under `references/<area>/`: `app-installation`, `stores`, `ecommerce`, `bookings`, `calendar`, `donations`, `get-paid`, `pricing-plans`, `restaurants`, `events`, `blog`, `cms`, `rich-content`, `forms`, `contacts`, `automations`, `marketing`, `google-ads`, `google-business-profile`, `analytics`, `seo`, `media`, `sites`, `domains`, `site-properties`, `collaborators`, `custom-apps`, `dashboard-navigation`, `accessibility`. Each recipe is also a docs article under its API's section.
+
+### wix-docs
+
+Online: https://www.wix.com/skills/wix-docs/SKILL.md. On disk: the plugin's `skills/wix-docs/`, or `.agents/skills/wix-docs/`.
+
+Looks up the Wix API and SDK documentation to confirm an endpoint, method, request and response shape, field, enum or error before writing Wix code. `SKILL.md` has the two lanes, plain `curl` and the MCP's documentation tools, with the search, browse and read requests. `references/API_SPEC_SEARCH.md`: the spec index and its queries. `references/CALLING.md`: the identities a call runs as and how each token is minted. `references/EXTRACTING.md`: reading only the needed part of a big menu or method page with `curl` and `grep`.
+
+### wix-readme
+
+This index.

package/skills/wix-replatform/.publish-manifest.json

@@ -1,8 +1,8 @@
 {
-  "bundle": "replatform",
-  "version": "1.2.0",
+  "bundle": "wix-replatform",
+  "version": "2.2.3",
   "sourceRepo": "wix-private/replatform",
-  "sourcePath": "skills/",
-  "sourceCommit": "9aaaebd",
-  "publishedAt": "2026-08-05T13:55:48Z"
+  "sourcePath": "skills/wix-replatform/",
+  "sourceCommit": "6bde03f",
+  "publishedAt": "2026-10-22T22:14:10Z"
 }

package/skills/wix-replatform/CLI.md

@@ -0,0 +1,162 @@
+# RePlatform CLI
+
+`replatform` is the non-interactive process supervisor for a RePlatform migration. It starts
+an installed coding agent, gives it the active migration project, observes durable migration
+artifacts, and exposes run control from another terminal.
+
+It is **not** a second migration engine. The installed `wix-replatform` skill still chooses
+the next stage and performs migration work; existing receipts remain the only proof of
+completion. The CLI provides the outer lifecycle: start, observe, answer human checkpoints,
+cancel, and resume.
+
+## Start here
+
+From the repository during development:
+
+```bash
+yarn replatform --help
+yarn replatform run <project> --agent codex
+```
+
+From an installed bundle:
+
+```bash
+node <bundle>/scripts/replatform.js --help
+```
+
+The CLI never prompts for stdin, opens an editor or pager, or begins a vendor login flow.
+Required human work becomes a durable request that can be inspected and continued later.
+
+## Common lifecycle
+
+```bash
+# Start and receive normalized JSONL events (the default).
+replatform run migrations/example --agent codex
+
+# Check a live or completed run from another terminal.
+replatform status <project-or-run-id>
+replatform tail <project-or-run-id> --follow
+
+# Read the persisted work plan, active task, and agent topology.
+replatform tasks <project-or-run-id> --format json
+
+# Read the identity currently authenticated in the local Wix CLI before a destination action.
+replatform account
+
+# Read a required human action, then provide the permitted response.
+replatform requests <project-or-run-id>
+replatform show <project-or-run-id> <request-id>
+replatform answer --project <project> --request-id <request-id> --choice approved --continue
+
+# A manual action has no approval choice. Complete the stated prerequisite first, then
+# acknowledge it; the resumed stage verifies the prerequisite itself.
+replatform answer --project <project> --request-id <request-id> --acknowledge --continue
+
+# Stop only a supervisor that owns an active run, preserving migration recovery artifacts.
+replatform cancel <project-or-run-id>
+```
+
+## Output and liveness
+
+`run`, `resume`, and `answer --continue` default to `--format jsonl`. The first event carries
+the run ID and the final event has `type: "result"`. Use `--format json` for exactly one final
+result object, or `--format text` for a concise human result. `--format event-stream` is an
+alias for `jsonl`.
+
+When a run needs a person, its `user_action_requested` event carries the full safe action
+summary: why it is needed (`message` and `userAction.prompt`), response mode, permitted choices,
+and reviewable artifacts. A JSONL consumer can therefore render the decision without reading a
+project file; `show` remains available for the complete durable request or artifact contents.
+
+Foreground runs emit a truthful liveness heartbeat every `60s` when no newer observable
+progress exists. Detached runs default to no heartbeat. Set `--status-interval off` to disable
+foreground heartbeats, or choose a value from `10s` to `5m`. `--events-file <path>` mirrors
+normalized JSONL events to a file.
+
+## Human checkpoints
+
+`requests` lists every pending action with its response mode and a copyable next command.
+
+- `choice` accepts only one declared `--choice` value.
+- `choice` and a manual `--acknowledge` also accept an optional `--note` to record the
+  operator's context without changing the selected decision or acknowledgement.
+- `text` accepts `--text` or `--text-file`.
+- `none` is a manual prerequisite. Run the stated external action, then use
+  `--acknowledge`; this records the operator statement but does not replace deterministic
+  verification by the resumed migration stage.
+
+Some declared choices carry a narrowly scoped durable effect. For example, choosing
+`switch_to_standard` after a quick-import preflight changes `managementImportMode` to `standard`
+before `--continue` resumes. The event and result include that request's choices; the CLI never
+infers an effect from a label alone.
+
+`show` can display the action itself or an explicitly reviewable artifact. It never exposes
+arbitrary project files. If it truncates a large artifact, it prints the exact emitted and total
+byte counts.
+
+## Source and delivery choices
+
+`run --help` describes every supported value. In brief:
+
+- `--source-mode public_content` reads public pages and content.
+- `authenticated_api` uses standard source API access.
+- `private_data` requires protected source credentials.
+- `files_only` imports supplied `--file` paths.
+- `--delivery-mode management` migrates backend data; `website` migrates the frontend only;
+  `management_and_website` performs both.
+- `--management-import-mode standard` uses the full discovery and mapping flow; `quick` uses a
+  bounded public adapter and plan.
+- `--site-type headless|studio|harmony` chooses the type of a new destination site (with
+  `--destination new`). Headless is a website developed in code; Studio and Harmony are
+  websites designed in a Wix editor. There is no default: without it, a new-site run raises a
+  durable site-type request before anything is created. The type cannot be changed later.
+- `--site-business-type store|bookings|other` is valid only with `--site-type harmony`. It
+  records the business context for the run; it does not change how the site is created:
+  Harmony always starts from the blank template (Harmony site generation is not used).
+- Before the first Studio or Harmony site is created, a request shows the account the Wix CLI
+  is logged into and the site name; nothing is created until that account is confirmed.
+- Destination recovery requests (uncertain creation, editor or publication checks) are
+  answered like any other request; an answer only triggers one new bounded check, never a
+  second site. RePlatform never publishes or unpublishes an Editor site.
+
+## Safety and recovery
+
+Every run writes a run ID before it launches an agent. A run is not complete because an agent
+said so: aggregate completion receipts must validate. Cancellation is a durable state change;
+it requests graceful shutdown before forced termination, never labels a partial import as
+completed, and preserves recovery artifacts for a later `replatform resume`.
+
+Run `replatform doctor` to check available adapters and local prerequisites without printing
+credentials.
+
+`replatform account` reports the identity returned by the local `wix whoami` command. It is a
+live check, not a migration artifact: confirm that identity is authorized before acknowledging a
+destination-creation action.
+
+## Local browser console
+
+`replatform-console` is an optional loopback-only browser control surface for this CLI:
+
+```bash
+node <bundle>/scripts/replatform-console.js
+```
+
+It prints a tokenized `127.0.0.1` URL. Keep that URL private: its token authorizes local
+control requests. The console starts the same non-interactive CLI commands, renders the
+persisted work state alongside the normalized event stream, presents durable human actions, and reads only artifacts that `show`
+already permits. It never accepts credentials or exposes vendor diagnostics. `--port <port>`
+chooses a port; the server refuses any non-loopback host.
+
+The Work panel reads `state/runner/task-state.json` through `replatform tasks`, so it survives
+console reloads and restarts. It records router work and direct agent processes; extra workers
+appear only when an adapter reports their structured topology. The observed activity feed remains
+diagnostic evidence and never marks work complete by itself.
+
+For destination-creation acknowledgements, the console also displays the identity reported by
+the local Wix CLI and requires that check to succeed before it enables acknowledgement. The
+identity is shown only in the token-protected dialog and is never saved to migration artifacts.
+
+For reconnectable consumers, `tail --since <event-id>` replays events strictly after that
+event. `tail --since <duration>` uses an inclusive time window. `show --format json` returns
+the declared artifact media type plus `cursor`/`nextCursor` byte offsets for bounded reads, and
+`projects --format json` lists valid migration projects under the configured migrations root.

package/skills/wix-replatform/README.md

@@ -0,0 +1,52 @@
+# wix-replatform
+
+`wix-replatform` is a migration skill for moving business data from another platform into
+Wix.
+
+Its public entrypoint is `wix-replatform`. The bundled internal resources handle the workflow
+stages behind that entrypoint.
+
+## Quick start
+
+Install the skill:
+
+```bash
+npx skills add wix/skills/skills/wix-replatform
+```
+
+Or install it globally:
+
+```bash
+npx skills add wix/skills/skills/wix-replatform -g
+```
+
+Then, in your agent:
+
+1. Invoke `wix-replatform`.
+2. If you want the migration to run end to end with grouped intake and no routine
+   checkpoint pauses, invoke it as `wix-replatform in 1-click mode`.
+3. Provide the source site URL and any required destination/source-access details.
+4. Follow the routed workflow through discovery, mapping, setup, code generation, and import.
+5. Choose whether the run is backend-only (`management`) or backend + storefront
+   (`website`).
+6. After setup discovery, the skill writes `website/handoff.json` even for backend-only
+   runs. In `website` mode it also asks for a late `websiteScope` decision so the
+   storefront skill can start with suggested scopes based on the discovered content. In
+   `1-click mode`, it picks the deterministic default instead of pausing.
+7. If the delivery mode is `website`, continue into the frontend phase through the
+   migration project's `website/handoff.json` package.
+
+If the user explicitly asks for `1-click mode`, the skill should gather any missing
+required inputs up front once, record `automationMode=one_click` with `source: "user"`, record routine
+mapping/execution approvals as `approved` with `decidedBy: "agent"`, create a demo
+member for blog import when needed, and continue through the frontend phase as well when
+`deliveryMode=management_and_website` (or user input `both`). `deliveryMode=website` is
+frontend-only.
+
+For CSV, explicit user-requested 1-click also accepts a passing sample preview as the agent
+and continues without routine questions. Without that explicit user-authored decision, CSV
+keeps its normal mapping review, sample-preview validation, and execution-plan approval
+pauses. File upload alone never implies 1-click.
+
+Migration artifacts are written to a local project directory such as `migrations/<project>/`.
+They are not written back into the skill package.