@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless/references/inline-recipes/how-to-code-donations.md

@@ -0,0 +1,146 @@
+---
+name: "How to Code Donations"
+description: Read Wix Donations campaigns and accept one-time or recurring donations through Cart V2 and a Headless redirect session. Covers numeric cart amounts, omitted one-time frequency, donor selections, misleading catalog errors and staged verification; does not create campaigns or prescribe hosting.
+---
+# Accept a donation on a Headless site
+
+Use existing Wix Donations campaigns; setup/editing belongs to
+[the management recipe](../../../wix-manage/references/donations/create-and-update-donation-campaigns.md).
+Read the [donor-experience guidance](experience-donations.md) when building
+the UI. Resolve sibling links locally when installed; otherwise read the same repository path under
+`https://www.wix.com/skills/`. This contract is independent of framework and hosting.
+
+## 1. Read the campaign as the donor will
+
+Use one visitor identity per browser session; reuse the existing auth/transport. A public OAuth client
+ID is not a secret; API keys, app secrets and owner tokens never belong in the browser. Confirm the
+client targets the supplied content site. Do not require donor login or provision a replacement site.
+
+| Need | REST call and minimal body | SDK equivalent |
+| --- | --- | --- |
+| Discover campaigns | `POST https://www.wixapis.com/donation-campaigns/v2/donation-campaigns/query` · `{ "query": { "filter": { "archived": false }, "cursorPaging": { "limit": 100 } } }` | `donationCampaigns.queryDonationCampaigns().eq('archived', false).limit(100).find()` |
+| Campaign detail | `GET https://www.wixapis.com/donation-campaigns/v2/donation-campaigns/<ID>` | `donationCampaigns.getDonationCampaign(id)` |
+| Goal metrics, only with a goal and permitted access | `GET https://www.wixapis.com/donation-campaigns/v2/donation-campaigns/<ID>/metrics` | `donationCampaigns.getDonationCampaignMetrics(id)` |
+
+REST returns `donationCampaigns` / `donationCampaign`; SDK queries return `items`, SDK entities use
+`_id`. Continue query paging with the returned cursor. Resolve detail routes from live IDs, not a
+seed-time list; missing/archived campaigns are unavailable, not a fallback to the first campaign.
+Offer giving only when `status === 'COLLECTING'` and not archived. Reaching a goal does not close a
+campaign if it allows further donations. A refused query is an error, not an empty campaign list.
+
+Render from `donationFrequencies`, `predefinedDonationAmounts[].price` and `.description`,
+`customAmountEnabled` / `customAmountOptions`, `commentsEnabled`, `askDonorCoverFee`, and optional
+`campaignGoal`. Currency is the site's default; use formatted API values or a verified currency code,
+never assume USD. A metrics failure must not invent a raised total, donor count or currency.
+Campaign story copy is site-authored; the entity has no story or slug.
+
+Carry an explicitly chosen giving frequency through discovery and campaign links to the form, but
+only when that campaign offers it. Retain later donor edits. Keep a short-lived, site/visitor/campaign-
+scoped draft (preset/custom amount, cadence, fee, note) across refresh and checkout abandonment; notes
+never belong in query strings or logs. Restore and revalidate against live settings before allowing
+checkout. Do not clear the draft merely because a return URL was visited; see the shared experience
+reference for recovery and accessible form requirements. This is UI state, not an extra Wix API.
+
+Docs: [query](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/query-donation-campaigns),
+[get](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/get-donation-campaign),
+[metrics and permissions](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/get-donation-campaign-metrics).
+For SDK shapes read their `.md?apiView=SDK` views. Modules: `donationCampaigns` from `@wix/donations`,
+`cartV2` from `@wix/ecom`, `redirects` from `@wix/redirects`, on the project's existing SDK client or
+ambient auth. REST-only projects do not install an SDK just for this flow.
+
+## 2. Build the catalog reference correctly
+
+**Campaign prices are decimal strings; cart `options.amount` must be a JSON number.** Convert and
+validate before the request. `ONE_TIME` belongs to the campaign/UI enum; **omit `frequency` from
+the cart options for one-time giving**. Only `WEEK`, `MONTH`, `YEAR` are recurring cart values.
+
+```js
+const amount = Number(selectedAmount);
+if (!Number.isFinite(amount) || amount <= 0) throw new Error('Enter a positive donation amount.');
+// Before this: validate against the selected campaign's presets/custom limits and offered frequency.
+const catalogItems = [{
+  quantity: 1,
+  catalogReference: {
+    appId: '333b456e-dd48-4d6b-b32b-9fd48d74e163',
+    catalogItemId: campaignId,
+    options: {
+      amount,
+      ...(frequency !== 'ONE_TIME' ? { frequency } : {}),
+      ...(askDonorCoverFee && donorOptedIn ? { donorCoveringFees: true } : {}),
+    },
+  },
+}];
+```
+
+Validate a nonempty amount first: `Number('')` is zero, not a donor selection. Honor the campaign's
+allowed choices. Put an enabled donor message in `cart.note` (Cart V2 limit 1,000 characters), not
+invented catalog options. Fee coverage adds the documented 2.9% **through the flag**; send the base
+donation amount, not a locally inflated amount plus the flag. Recurring coverage applies per charge.
+Do not create custom-priced items to bypass campaign rules.
+[Donation catalog-reference contract](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/e-commerce-integration-with-donation-campaigns).
+
+## 3. Create a fresh Cart V2, then a redirect session
+
+Use the same visitor identity throughout. Keep this separate from the shopper's current merchandise
+cart. New Cart V2 flows have **no separate Create Checkout call**; the returned cart ID is the ID
+handed to `ecomCheckout.checkoutId`. Do not mix in the V1 create-checkout-from-cart step.
+[Cart V2 migration](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
+
+| Step | REST request | Result |
+| --- | --- | --- |
+| Create cart | `POST https://www.wixapis.com/ecom/v2/carts` · `{ "cart": { "source": { "channelType": "WEB" } }, "catalogItems": [...] }` (the numeric reference above; optional `cart.note`) | `cart.id` |
+| Inspect calculated totals during verification | `POST https://www.wixapis.com/ecom/v2/carts/<CART_ID>/calculate` · `{}` | `cart` and `summary`; inspect the donation line, currency, calculated amounts and issues |
+| Create redirect session | `POST https://www.wixapis.com/_api/redirects-api/v1/redirect-session` · `{ "ecomCheckout": { "checkoutId": "<CART_ID>" }, "callbacks": { "postFlowUrl": "<ORIGIN>/donate/<ID>", "thankYouPageUrl": "<ORIGIN>/donate/thank-you" } }` | `redirectSession.fullUrl` |
+
+SDK: `cartV2.createCart({ cart: { source: { channelType: 'WEB' }, ...(note ? { note } : {}) }, catalogItems })`
+returns a cart with `_id`; pass it to `redirects.createRedirectSession` with the same body as above.
+Navigate the **full document** to the exact returned URL (`window.location.assign(fullUrl)`), not an
+SPA router, iframe, guessed checkout URL or manually created order.
+
+Use actual, reachable callback routes on the deployed origin; the external origin must be allowed
+on the OAuth client. `postFlowUrl` is also used on abandonment: it is not a paid signal. A success
+callback may carry `orderId`; confirm order/payment state through an authorized read before stating
+that a donation was paid. Never grant owner access just to populate a public thank-you page.
+
+Docs: [create cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart),
+[calculate](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/calculate-cart),
+[redirect session](https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session).
+On a Kit build, call its shipped `donationCheckoutUrl` / form instead of rebuilding this sequence.
+
+## 4. Diagnose the failed stage, not a guessed cause
+
+- `ITEM_NOT_FOUND_IN_CATALOG`: first inspect the exact donation app ID, campaign ID, **numeric**
+  `options.amount`, and one-time frequency omission. Check the campaign on the same site/identity.
+  The error alone is not proof of a missing campaign, a missing app, or a premium requirement.
+- Keep status, application error code/body and failing stage available to the developer, with tokens,
+  checkout-session URLs and donor data redacted. Give the donor a recoverable inline message. Never
+  replace every error with an unexplained generic failure or convert failures to empty/success states.
+- Keep the form disabled while creating the cart/session. Do not run both add-to-current-cart and
+  donate handlers on the same action. Do not silently retry cart creation after a timeout or redirect
+  failure; inspect/reuse the known cart when possible rather than duplicating the action.
+- Distinguish API handoff from payment acceptance. Cart/session creation can succeed before live
+  payments are enabled. A payments-capable plan and connected, eligible provider are separate
+  go-live checks; recurring donations also need recurring support. Do not hardcode either “premium
+  is never required” or “every checkout error means upgrade”.
+  [Payment setup](https://support.wix.com/en/article/wix-donations-adding-and-setting-up-wix-donations).
+
+## 5. Verify before handoff
+
+For a build accepting donations, run a bounded API smoke test with an **anonymous visitor token**,
+not the owner's token: read a real campaign → create a cart with one numeric donation line → calculate
+and inspect it → create the redirect session. Use the exact requests above with `curl --fail-with-body`,
+`Authorization: <VISITOR_TOKEN>` and `Content-Type: application/json`; mint that identity, when needed,
+with `POST https://www.wixapis.com/oauth2/token`, body
+`{ "clientId": "<PUBLIC_CLIENT_ID>", "grantType": "anonymous" }` → `access_token` / `refresh_token`.
+Confirm permission for this test before creating its cart; do not seed or mutate campaigns to make
+the test pass. Stop at the failing stage and preserve the sanitized response; never loop blind retries.
+
+Check one-time and an offered recurring selection, custom bounds and correction, fee on/off when
+offered, and notes when enabled. Local/mocked checks do not prove live API permissions. In a browser,
+check discovery and form first screens at desktop, 390px and 320px widths, plus keyboard/error behavior.
+Follow a monthly entry through cause selection; confirm its cadence, then cancel/back from checkout
+and refresh to verify the donor's choices survive without implying payment. Confirm hosted checkout
+shows the intended cause, amount, currency and cadence; a resized desktop viewport alone does not
+verify the mobile checkout. **Do not submit a payment** without
+explicit authorization for that transaction and amount. Handoff states which levels passed (API,
+hosted checkout, payment/return), what was blocked, and which setup remains; no mandatory report file.

package/skills/wix-headless/references/inline-recipes/setup-donations.md

@@ -0,0 +1,15 @@
+---
+name: "Set Up Donations"
+description: Set up Wix Donations campaigns through the shared management recipe; reuse existing campaigns and keep configuration separate from the donor-facing implementation.
+---
+# Set up Donations
+
+Read [Create and Update Donation Campaigns](../../../wix-manage/references/donations/create-and-update-donation-campaigns.md)
+and execute its read-before-write flow with this project's owner-authorized credentials and site ID.
+If the sibling skill is not installed, read
+`https://www.wix.com/skills/wix-manage/references/donations/create-and-update-donation-campaigns.md`.
+
+Reuse the supplied site's campaigns. Only create/edit the causes and settings the user approved;
+do not manufacture a goal, deadline or impact claim. Keep any created campaign IDs only for setup
+verification/media attachment; the frontend discovers campaigns live. The donation form and checkout
+are [How to Code Donations](how-to-code-donations.md), not this setup operation.

package/skills/wix-headless/references/managed/CREATE.md

@@ -108,7 +108,7 @@ Either way, `CONTENT.md` §1 (the business's category must read literally above
 a page a first-time visitor can't identify isn't done yet, regardless of voice.
 
 **If a loaded vertical ships an experience overlay** — `references/inline-recipes/experience-<vertical>.md`
-(today: `experience-store.md`) — read it after `DESIGN.md`/`CONTENT.md`. It carries that vertical's own
+(today: `experience-store.md`, `experience-donations.md`) — read it after `DESIGN.md`/`CONTENT.md`. It carries that vertical's own
 design and copy bar (what its surfaces must show, how to derive the direction from its content); the
 general files stay the floor.
 

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

@@ -86,19 +86,74 @@ doesn't express — or once the site exists and the work turns to managing or ex
   content seed) — the index fills within about half a minute of the install. Playbook:
   `templates/shared/capabilities/site-search/INSTRUCTIONS.md`.
 
+### The scripts
+
+`<SKILL_ROOT>/install/` holds plain Node scripts, no build step, each with a header comment that
+says what it does and how it is called. They are the deterministic steps of the run: each copies,
+composes, installs or seeds, and prints one JSON object (or one JSON event per line) saying what it
+found and did. Read any of them when you want to know what a step does before running it, or when a
+step's output surprises you; the templates' seed modules are the reference for the Wix calls a
+vertical needs, in the order that works.
+
+| Script | Does |
+|---|---|
+| `templates.mjs` | Finds the shipped code (the `wix-headless-templates` skill beside this one), or fetches it once as a sparse clone; prints its folder. |
+| `context.mjs` | Reads `wix.config.json` and `.env.local`, pulls the env on the CLI route when it is missing, and prints the folder's shape, the deploy site and the content site, the publisher (`cli` or `plugin`), whether npm reaches the registry, and whether the upload tool's S3 host answers from this shell (`carrier.s3`). Changes nothing. |
+| `setup.mjs` | One call from the folder and the brief to a project ready for the brand layer: scaffolds (or, with `--site --app`, copies the composed template and writes the config and env), deploys the vertical's code, writes the agent config files, starts the install, and seeds a site it created. |
+| `attach.mjs` | `setup.mjs` for a site that already exists: does what `wix create` does after creating one (OAuth app, hosting, env, `wix.config.json`) against the site id given, then scaffolds, deploys and installs; seeds only with `--plan`; with `--hosting self`, puts the given origins on the OAuth app's allow-list instead of Wix hosting. |
+| `deploy.mjs` | Composes a vertical's code layers into the project for the stack (`astro`, `react`, `lib`, `static`), adds its dependencies, and keeps the lock valid for `npm ci` (`lock.mjs`). |
+| `install.mjs` | The one dependency install: decides none, `npm install` or `npm ci` from the lock and what `node_modules` already holds; writes `.install-exit`. |
+| `bootstrap.mjs` | CLI route only: checks the Wix CLI and runs the device-code login, one JSON event per line. |
+| `check.mjs` | Compares this installed skill and its templates with the repository they came from; read-only, prints the commands that would update. |
+| `agents-md.mjs`, `env-ignore.mjs` | Write a new project's `AGENTS.md`, `CLAUDE.md` and `.gemini/settings.json`; keep `.env.local` out of git. |
+| `proc.mjs`, `background.mjs`, `pins.json` | npm and npx started the same way on every OS; the detached install and seed; the pinned CLI and template versions. |
+| `templates/<vertical>/seed/seed-*.mjs`, `read-site.mjs` | The vertical's seed from a plan, and a read of what the site already holds. `SEED.md` beside them is the plan's contract. |
+
 ## The run
 
-Needed throughout: Node ≥ 22.12 (Astro 7; the Wix CLI alone runs on 20.11), git, a logged-in Wix CLI (`npx @wix/cli@latest whoami`;
-`npx @wix/cli@latest login` is a device-code flow: surface the URL and code to the user, never
-read tokens into context), and the two companion skills installed beside this one, `wix-docs`
-and `wix-manage`. `node <SKILL_ROOT>/install/bootstrap.mjs` checks the CLI and runs the login
-when there is none; the cold-start page, `https://www.wix.com/skills/headless-cold-start/headless-kit.md`,
-gets a machine with none of this, the skills included, to that point. In a folder that
+Needed throughout: Node ≥ 24.18, git, the two companion skills installed beside this one,
+`wix-docs` and `wix-manage`, and one of two ways to Wix. `node <SKILL_ROOT>/install/context.mjs`
+prints which one this machine has, as `publisher`:
+
+- **`plugin`** — no Wix CLI session on this machine; the Wix MCP's tools are in your tool list
+  (`ExecuteWixAPI`, `UploadHeadlessWebsiteFiles`: a Wix plugin or connector, connected); and `npm`
+  reaches the registry, so the kit runs here. The MCP carries the user's login. The site is provisioned through `ExecuteWixAPI` with the recipe
+  `wix-manage/references/sites/create-headless-site.md` (the provision call returns the
+  `metaSiteId` and the site's OAuth client `appId`); step 3's setup takes both as `--site` and
+  `--app` and runs no CLI; the seed is an `ExecuteWixAPI` script written from the vertical's
+  `SEED.md` (`guides/api-run.md` section 4); the release is `npx astro build`, then the build
+  uploaded with `UploadHeadlessWebsiteFiles` (step 5), attached in one call where the client shows
+  `attachments` as a local path, or in two calls with `curl` to the URLs the first returns, from a
+  shell that reaches the internet (the URLs are on Amazon S3; `curl -sI -m 25 https://s3.amazonaws.com`
+  answers with S3's own headers where they work, `x-amz-request-id` and usually `Server: AmazonS3`,
+  and a sandbox limited to a few hosts gets a proxy's refusal with neither). The tool releases the build to the site's Wix hosting, stores the project's source in the
+  site's Code Store repository, and returns the live URL. The plugin route asks for no login.
+  **The carrier is settled before the build**, from `context.mjs`'s `carrier.s3` and from whether
+  the client hands `attachments` over as files (the tool's `attachments` description names the
+  clients that do): with neither, the Astro build has no way to the site and the run is
+  `guides/api-run.md`, the site, the apps and the seed through `ExecuteWixAPI` and the frontend as
+  a few small static pages dropped in the tool's `files` form, written against the kit's REST
+  twins and cores as reference (its step 5); the compose is not run, since every file it writes
+  would have to be written out as text.
+- **`cli`** — where the Wix MCP is not connected, or a Wix CLI session is already on this machine:
+  a logged-in Wix CLI (`npx @wix/cli@latest whoami`; `npx @wix/cli@latest login` is a
+  device-code flow: surface the URL and code to the user, never read tokens into context).
+  `node <SKILL_ROOT>/install/bootstrap.mjs` checks the CLI and runs the login when there is none;
+  `wix create`, `wix env pull` and `wix release` do what the steps below say.
+
+The cold-start page, `https://www.wix.com/skills/headless-cold-start/headless-kit.md`, gets a
+machine with none of this, the skills included, to that point. The four skills this run reads
+(`wix-headless-kit`, `wix-headless-templates`, `wix-docs`, `wix-manage`) are on disk after that
+install (`.agents/skills/`, or a plugin's folder), or served by the client's skill tool (text to
+read, not files: the scripts and the templates run only from disk), or online at
+`https://www.wix.com/skills/<skill>/<path>`, where `<skill>.manifest.json` lists every file with its
+size and a folder's `_content` returns its files at once; `<SKILL_ROOT>` below is the kit's folder
+on disk. In a folder that
 already holds a `wix.config.json`, `node <SKILL_ROOT>/install/context.mjs` first: it runs
-`wix env pull` when `.env.local` is missing and prints the folder's **shape** (`folder.shape`, the
-cases of step 3, with the `next` for each) and the two identities a project has — the deploy site
-(the config, where `wix release` goes) and the content site (the env, whose app the SDK client runs
-as and whose dashboard manages the business). They are one site, except on a **migration preview**
+`wix env pull` when `.env.local` is missing (on the CLI route) and prints the folder's **shape**
+(`folder.shape`, the cases of step 3, with the `next` for each) and the two identities a project
+has — the deploy site (the config, where the release goes) and the content site (the env, whose
+app the SDK client runs as and whose dashboard manages the business). They are one site, except on a **migration preview**
 (`guides/migration.md`), where the env names the site being migrated. Every script here reads that
 context; the site a call targets is never guessed from the config alone. Then fetch the shipped
 code once: `node <SKILL_ROOT>/install/templates.mjs`. It prints the folder; the `templates/…`
@@ -191,10 +246,10 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
 
    | the folder holds | shape | what setup does | seeded by setup |
    |---|---|---|---|
-   | nothing, or loose files (a CSV, a brief) | **empty** → create | `wix create` with the vertical's composed template, here; `--business-name` names the site | **yes**, from `--plan` |
+   | nothing, or loose files (a CSV, a brief) | **empty** → create | `wix create` with the vertical's composed template, here; `--business-name` names the site. On the plugin route, `--site <metaSiteId> --app <appId>`: the ids the provision call returned for a new site, or, for a site that exists with no project (a dropped site), its id and the companion app's id from `get-or-create` (`guides/existing-site.md`); the composed template is copied in and `wix.config.json` and `.env.local` written for that site, no CLI | **yes**, from `--plan`, on the CLI route. On the plugin route setup takes no `--plan` and seeds nothing: the plan is seeded through `ExecuteWixAPI` (`guides/api-run.md` section 4) |
    | a frontend, no config (a `package.json`, or `index.html` at the root: someone's Astro, Vite, Next, plain HTML) | **project** → adopt | `init` in place gives it a new, empty site, then deploys; `--stack` from step 1 is required; make the project what that stack needs on Wix hosting (step 1) before or right after | **yes**, from `--plan` |
    | a config whose `.env.local` declares an active editor migration (`EDITOR_MIGRATION_STATUS=ACTIVE`), with or without the blank Astro starter the download carries | **migration** → migrate | the shipped code into the starter (or the composed template around a bare config), deployed with the migrated site's app as the client, the install starts; `ready_for_brand_layer` says `mode: "migrate"`, the parent as `siteId`, the child as `deploySiteId` (`guides/migration.md`) | no, ever |
-   | a config, no frontend | **config-only** → refuses | the site exists and has no frontend yet: `attach.mjs` (below) takes the site from the config, reuses its hosting, scaffolds and deploys. That config is what `init` leaves behind, and `init` always creates a site: this site was made for this run and is empty | **yes**: draft the plan as for create, then `attach.mjs --plan` |
+   | a config, no frontend | **config-only** → refuses | the site exists and has no frontend yet: on the CLI route `attach.mjs` (below) takes the site from the config, reuses its hosting, scaffolds and deploys; on the plugin route `setup.mjs --site --app` with the config's ids, in an empty folder, then the build released by `UploadHeadlessWebsiteFiles` (`guides/existing-site.md`). That config is what `init` leaves behind, and `init` always creates a site: this site was made for this run and is empty | **yes**: draft the plan as for create, then `attach.mjs --plan` |
    | a config and a frontend (a `package.json`, or `index.html` inside the folder `site.outputDirectory` names) | **wix-project** → refuses | iterate: never scaffold, `init` or reseed. `deploy.mjs <vertical…> --stack <stack>` adds a solution (the client id comes from `.env.local`, the config as the fallback), then one install, `node <SKILL_ROOT>/install/install.mjs` (nothing when `node_modules` already satisfies the lock); a change is file edits; then release | no |
    | a config, a `package.json`, `public/index.html` and no `src/pages/` (a site published through the drop flow, on its Wix Dev Machine) | **static-in-astro** → refuses | the pages stay plain files in `public/`: `deploy.mjs <vertical…> --stack static --out public` puts the REST layer in `public/js/wix/`, the pages are wired in place (reference mode), and no Astro pages are added; release with `build` then `release`, the URL stays | no |
    | a config and the CLI's blank Astro starter with no work of its own (`wix-astro-blank`, only the blank template's packages: a Dev Machine's never-released site, a bare `wix create`) | **blank-starter** → refuses | `attach.mjs --business-name <brand> --vertical <v…> [--plan plan.json]` on the config's site: the vertical's composed template takes the starter's place (its lockfile with it), the install and the seed start detached; build the brand layer while they run | **yes**, from `--plan`: the site was made for this run and is empty, unless `read-site.mjs` shows content |
@@ -226,7 +281,8 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
 
    `--vertical` is required and picks which shipped code deploys AND which seed runs. The
    `ready_for_brand_layer` event says `mode` (`create`, `adopt`, `migrate`, `published-static`),
-   `shape`, the stack, and the `next` for that stack, including how it releases.
+   `shape`, the stack, `publisher` (`cli` or `plugin`), and the `next` for that stack, including how
+   it releases.
 
    setup scaffolds with `--skip-git`: it composes its own steps and leaves version control to
    you / the enclosing repo, so it does **not** create the scaffold's usual git repo + initial
@@ -256,6 +312,10 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    A code change on an existing project is done when it is **released** (step 5) and the live
    URL shows it — not when a dev server or a local build shows it. A management change (a
    recipe against the site) needs no release; the frontend reads it live.
+   A site released through the upload tool keeps its source in its Code Store repository: a later
+   change, in any session, downloads it (`guides/existing-site.md`), edits, builds and uploads with
+   the downloaded revision as `expectedHeadRevisionId`. One site keeps one writer path: such a site
+   is not changed through `wix release` or a plain drop.
 
 4. **Design and build the presentation while the install finishes** — in the project dir from
    the `ready_for_brand_layer` event, per the vertical's `INSTRUCTIONS.md`: set the `@theme`
@@ -284,7 +344,34 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    exit code is the result and its stdout is the JSON — wait on the process (a foreground run,
    or `wait` on its pid), not on a file. Then
    **build & release once** (managed), as the `next` of the `ready_for_brand_layer` event says
-   for the stack: Astro → `npx @wix/cli@latest build` then `npx @wix/cli@latest release`;
+   for the stack and the publisher: Astro on the CLI route → `npx @wix/cli@latest build` then
+   `npx @wix/cli@latest release`; Astro on the plugin route → `npx astro build` from the project
+   root, then `UploadHeadlessWebsiteFiles` with the site's `siteId`, in one of two forms (the `next`
+   carries the zip commands, with Python's `zipfile` where there is no `zip` binary):
+   - **attached**, one call: the project zipped without `node_modules` (`.wix/build-metadata.json`
+     and `dist/` in it), passed as `attachments`. The build is released and the source in the same
+     zip is stored.
+   - **two calls**, from a shell that reaches the internet (the upload URLs are on Amazon S3:
+     `curl -sI -m 25 https://s3.amazonaws.com` answers with S3's own headers where they work,
+     `x-amz-request-id` and usually `Server: AmazonS3`; a sandbox limited to a few hosts gets a
+     proxy's refusal with neither, and cannot release a build this way): the build zip (`zip -qr build.zip dist .wix`) and the source zip, the project
+     without `node_modules`, `dist`, `.wix`, `.astro`, `.env*`, `.agents`
+     (`zip -qr source.zip . -x 'node_modules/*' 'dist/*' '.wix/*' '.astro/*' '.agents/*' '.env*' 'build.zip'`).
+     First `{ siteId, prepare: true, size }`, `size` being `wc -c < build.zip`: the reply gives a
+     `curl -X PUT ... --data-binary @build.zip "<putUrl>"`, one for the source zip when the site's
+     repository takes it, the repository's `headRevisionId`, and the exact second call. Run the
+     curls as given, then `{ siteId, uploadKey, sourceUploadId, expectedHeadRevisionId }`.
+
+   The service deploys, commits the source to the site's Code Store repository, then releases; a
+   refused commit releases nothing. `expectedHeadRevisionId` is the revision the project started
+   from: the one it was downloaded at, or for a project started in this run the `headRevisionId`
+   the prepare returned. Left out, the release works only on a repository with nothing in it yet;
+   otherwise it answers `EXPECTED_HEAD_REQUIRED` and releases nothing. A 409
+   `CODE_STORE_HEAD_CHANGED` means the repository moved since: download it again
+   (`guides/existing-site.md`), carry the change over, build and upload. A 404 on the second call
+   means the upload expired: prepare again. The result carries the live URL; a release replaces
+   static pages dropped on the site before, at the same URL.
+   Otherwise:
    React or another bundler → the project's own build, then `npx @wix/cli@latest release` of
    the build folder named in `wix.config.json` (deep URLs must answer 200 directly, step 1);
    static → `release` alone. If the install failed, run it once more and then build. Don't
@@ -293,8 +380,8 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    site is released — close with the live URL and the dashboard link
    `https://manage.wix.com/dashboard/<siteId>` (the `siteId` of the `ready_for_brand_layer`
    event: on a migration preview that is the migrated site's dashboard, the release URL is the
-   preview's, the original site is unchanged, and completing the migration is the user's next
-   step in the Wix CLI once they approve — say all three). Tell the user how to put their own
+   preview's, the original site is unchanged, and you complete the migration once they
+   approve (`guides/migration.md`) — say all three). Tell the user how to put their own
    domain on the site, per the `wix-manage` recipe `references/domains/domain-search-purchase-and-connect.md`
    (installed beside this skill, else `https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md`):
    bought through Wix, or one they already own. When the site takes money through
@@ -307,8 +394,8 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    need a premium plan). Both are the owner's steps, not a defect in the site. When the run started
    from the owner's own pages, name what those pages promised that the released site does not do.
    **Copy the live URL verbatim from the
-   `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
-   a 404). Before you sign off, run the feedback self-check over the whole session
+   release output (the CLI's, or the upload tool's result) — never retype it from memory** (a
+   mistyped subdomain hands the user a 404). Before you sign off, run the feedback self-check over the whole session
    (`guides/feedback.md`): anything that cost more turns than it should have, including what you
    recovered from silently, is signal; if anything qualifies, offer to relay it as you deliver the
    links, and send only after an explicit yes.
@@ -324,9 +411,11 @@ 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/api-run.md`: the same run, step by step, as the Wix API calls the
-scripts make and the files beside this skill that carry the contracts.
+Where the kit does not run (no route to npm, no Node), or when the install, the CLI or the login is
+blocked where you are, read `<SKILL_ROOT>/guides/api-run.md`: the same run, step by step, as the Wix API calls the
+scripts make and the files beside this skill that carry the contracts. On the plugin route the same
+guide is the reference for the calls that go through `ExecuteWixAPI` (the provision call, the seed);
+the build and the release are this skill's step 5.
 
 ## Verticals
 

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

@@ -1,8 +1,7 @@
 # The kit's run as Wix API calls
 
-Read when the commands this skill is built on cannot run where you are, or stopped: your shell
-can't reach Wix, there is no shell, or the install, the
-CLI or the login is blocked. Wix is then reachable through the Wix MCP: every call below is an
+Read when the kit does not run where you are, or stopped: no Node, no route to npm (the install
+and the build need it), no shell at all, or the install, the CLI or the login is blocked. Wix is then reachable through the Wix MCP: every call below is an
 `ExecuteWixAPI` call, and files reach the site through the upload recipe. With no Wix MCP tools in
 your tool list (a plugin's skills can be on disk while its Wix connector is not connected), ask the
 user to connect Wix to this chat first. It walks the run of
@@ -52,9 +51,11 @@ doesn't list is a wrong path; find the file there before writing anything in its
 hold, served or on disk, is current when its size in bytes matches the manifest's; a file whose size
 differs is read online.
 
-What such a run does not produce: the Astro build and its release. Those need a machine with the
-CLI. Everything else the kit does to a site, it does through calls you can make, the frontend
-included: step 5 ships it as static files.
+What such a run does not produce: the Astro build. A build needs the kit running where you are (Node,
+and `npm` reaching the registry); then the run is SKILL.md's plugin route (`setup.mjs --site --app`, `astro build`, the build released by
+`UploadHeadlessWebsiteFiles`), and sections 2 to 4 here are the calls it makes through
+`ExecuteWixAPI`. Everything else the kit does to a site, it does through calls you can make, the
+frontend included: step 5 ships it as static files.
 
 ## 0. Identity
 
@@ -76,7 +77,7 @@ A brief that needs no solution (a game, a landing page, a tool) is a run of two
 ## 2. The site
 
 The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
-with `origin: "drop"`, a name, and the solutions to install as `seedOptions`. The recipe
+with `origin: "agent"` and a name. 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.
@@ -124,9 +125,10 @@ half a run.
 A payment (a cart, a paid booking, a ticket, a plan, a donation) ends in Wix's hosted checkout,
 reached through a redirect session, and is wired on the first pass, payments connected or not.
 
-The Astro pages cannot be released here: that is a run with a machine and a CLI login, which
-attaches to this site (`guides/existing-site.md`) rather than making a new one. What ships from here
-is static files, dropped onto the site from step 2 through
+The Astro pages are not built here: the kit does not run where you are. A later run where it does
+takes this site (SKILL.md's plugin route with `--site --app`, or `guides/existing-site.md` with the
+CLI) rather than making a new one; its release replaces the pages dropped here, at the same URL.
+What ships from here is static files, dropped onto the site from step 2 through
 `{MANAGE}/references/sites/upload-static-site.md`: the Wix MCP's upload tool, or a script that
 downloads what the site serves, edits it and drops it back, so only what changed is written. Which
 files depends on whether the compose can run, and on what writing them costs: when files reach the
@@ -197,6 +199,6 @@ failing call is fixed first, on the site or in the page. The closing reports the
 
 ## 6. Closing
 
-SKILL.md step 5's closing, with two additions: the site id, so a run with a machine attaches to this
-site (`guides/existing-site.md`) instead of making a new one; and, when files were dropped, that a
-change re-drops the whole set.
+SKILL.md step 5's closing, with two additions: the site id and the `appId`, so a run where the kit
+runs takes this site (`setup.mjs --site --app`, or `guides/existing-site.md`) instead of making a new one;
+and, when files were dropped, that a change re-drops the whole set.

package/skills/wix-headless-kit/guides/existing-site.md

@@ -10,6 +10,37 @@ part below applies there too, against the migrated site.) `<SKILL_ROOT>` is the
 in the folder `node <SKILL_ROOT>/install/templates.mjs` prints (`<templates>` below; SKILL.md, "The
 model").
 
+**A site with a Code Store repository** (one released through the upload tool, in this session or
+an earlier one): the project is there, and it is continued, not rebuilt. Its repository is the
+managed project whose id is the site's app id: the `appId` in `wix.config.json` when the folder has
+one, else `POST https://manage.wix.com/_api/companion-apps/v1/companion-apps/get-or-create` with
+body `{}`, whose `companionApp.id` it is. Both calls go through `ExecuteWixAPI` in site scope
+(`siteId` set); an account-scoped token is refused (403).
+
+```text
+POST https://www.wixapis.com/codestore/v2/git-code-store-projects/<appId>/generate-download-url
+{}
+→ { downloadUrl, revision: { id } }
+```
+
+```bash
+curl -o project.zip "<downloadUrl>"    # signed, 5 minutes, no Wix auth
+unzip -q project.zip -d . && rm project.zip
+node <SKILL_ROOT>/install/setup.mjs --vertical <vertical> --site <siteId> --app <appId>
+```
+
+Keep `revision.id`: it is the release's `expectedHeadRevisionId`. The download has no `.env.local`;
+setup writes it, installs when `node_modules` is missing, and scaffolds, deploys and seeds nothing.
+Then edit, `npx astro build`, and upload as SKILL.md step 5 says, with that revision. A 404
+(`NOT_FOUND`, `GIT_BRANCH_NOT_FOUND`) means the site has no project yet: a dropped site has none, its
+pages live only in the drop. On the plugin route that is the create flow against this site: `get-or-create` above gives the
+`appId`, then in an empty folder `node <SKILL_ROOT>/install/setup.mjs --vertical <vertical> --site
+<siteId> --app <appId>`, build, and release through `UploadHeadlessWebsiteFiles` with the
+`headRevisionId` the prepare returns (the drop's import commit, or none); the release replaces the
+dropped pages at the same URL and stores the project. The site owns its content: read it first, and
+seed only what the brief supplies or asks to add. On the CLI route the sections below apply, and the
+first release creates the repository.
+
 **Read the site, then run attach.** First, one call tells you what
 the site is — its name, currency, and the Wix apps installed on it:
 

package/skills/wix-headless-kit/guides/migration.md

@@ -1,11 +1,12 @@
 # A migration preview: a site being moved to headless
 
-Read when setup reports `mode: "migrate"`, or when a folder holds a `wix.config.json` and
-`node <SKILL_ROOT>/install/context.mjs` prints `migration.active: true`. The brief is the prompt
-the Wix dashboard's Headless settings hand the owner after "Go Headless": download the project from
-`https://manage.wix.com/download-headless-business/<siteId>/download.zip`, the names of the apps
-the site already has, and the instruction not to probe, install or seed anything. The zip holds
-`wix.config.json` (the deploy site and its app) beside the CLI's blank Astro starter.
+Read when setup reports `mode: "migrate"`, when a folder holds a `wix.config.json` and
+`node <SKILL_ROOT>/install/context.mjs` prints `migration.active: true`, or when the user asks to
+complete the migration (the dashboard's second prompt names `wix finalize-migration`). The brief is
+the prompt the Wix dashboard's Headless settings hand the owner after "Go Headless": download the
+project from `https://manage.wix.com/download-headless-business/<siteId>/download.zip`, the names of
+the apps the site already has, and the instruction not to probe, install or seed anything. The zip
+holds `wix.config.json` (the deploy site and its app) beside the CLI's blank Astro starter.
 
 **What `.env.local` says.** `wix env pull` copies the project's `prod` environment: the parent's
 `WIX_CLIENT_ID`, and the migration's own variables, `EDITOR_MIGRATION_STATUS` (`ACTIVE` while the
@@ -14,10 +15,10 @@ migration is under way, `COMPLETED` once the parent serves this frontend), `EDIT
 two; the shape is `migration` whenever the status is active, whatever else the folder holds.
 
 **Two sites, one project.** `wix.config.json` names a site created only to host the deployment:
-`wix release` goes there and nowhere else. `.env.local` (what `wix env pull` writes; setup and
-`context.mjs` pull it when it is missing) carries the credentials of the site being migrated, the
-**parent**, and says so. The parent owns everything the pages show and everything the business
-manages. So:
+`wix release` goes there and nowhere else until completion repoints the config (below). `.env.local`
+(what `wix env pull` writes; setup and `context.mjs` pull it when it is missing) carries the
+credentials of the site being migrated, the **parent**, and says so. The parent owns everything the
+pages show and everything the business manages. So:
 
 - **The SDK client is the parent's.** The Astro integration reads `WIX_CLIENT_ID` from the env and
   never the config; `deploy.mjs` copies the same value into `src/wix/config.ts` (react, lib) and
@@ -45,10 +46,41 @@ app, hosting and credentials came with the download; nothing is provisioned or r
 
 **The close.** The release is a **preview** on the deploy site. Close with the preview URL (copied
 from the `wix release` output), the parent's dashboard link, and the two facts: the original site
-is unchanged, and completing the migration, which makes the parent serve this frontend and retires
-the deploy site, is the user's next step once they approve the preview: the dashboard hands them
-a second prompt for it (`wix env pull`, `wix finalize-migration`, `wix build`, `wix release`, in
-that order). That step is not part of this skill and the command may not be in the installed CLI
-yet; do not invent one, do not run `wix release` against the parent, and do not edit
-`wix.config.json`. On every stack the code already carries the parent's client id,
-so completion needs no redeploy from here.
+is unchanged, and completing the migration puts this frontend live on the parent and retires the
+deploy site. Offer to complete it once they approve the preview.
+
+## Completing the migration
+
+Run it once the user approves the preview and asks to go live, or pastes the dashboard's finalize
+prompt: it switches the parent's live site to this frontend. The calls target the parent
+(`migration.parentSiteId` from `context.mjs`).
+
+1. **Read the migration.**
+
+   ```bash
+   curl -sS "https://www.wixapis.com/headless-business-setup/v1/editor-migrations" \
+     -H "Authorization: $(npx -y @wix/cli@latest token --site <parentSiteId>)"
+   ```
+
+   `migration.phase` `ITERATING` → step 2; `MIGRATION_FINALIZING` or `COMPLETED` → step 3;
+   `PREPARING` → the preview release is not observed yet, read again shortly; anything else → stop
+   and report it with the dashboard link.
+
+2. **Accept it**, as the dashboard's Complete Migration button does. On
+   `STALE_MIGRATION_REVISION`, read again and resend.
+
+   ```bash
+   curl -sS -X POST "https://www.wixapis.com/headless-business-setup/v1/editor-migrations/prepare-commit" \
+     -H "Authorization: $(npx -y @wix/cli@latest token --site <parentSiteId>)" \
+     -H "Content-Type: application/json" \
+     -d '{"migrationId":"<migration.id>","expectedRevision":<migration.revision>}'
+   ```
+
+3. **Release to the parent.** `npx @wix/cli@latest finalize-migration` (`@wix/cli` 1.1.256 or later)
+   repoints `wix.config.json` to the parent, builds and releases. React and static projects have no such command: set
+   `wix.config.json`'s `appId` and `siteId` to `.env.local`'s `WIX_CLIENT_ID` and
+   `EDITOR_MIGRATION_PARENT_SITE_ID`, then build and release as in SKILL.md step 5.
+
+Close with the parent's URL and its dashboard link, and say Wix finishes the switch on its side;
+the dashboard notifies them when it is done. Later changes ship with a plain build and
+`wix release`.

package/skills/wix-headless-kit/install/agents-md.mjs

@@ -23,7 +23,7 @@ export function writeAgentsMd(projectDir, vars) {
   else {
     // {{MIGRATION}} is a paragraph on a migration preview (vars.migration = { parentSiteId, deploySiteId }), else nothing.
     const migration = vars.migration
-      ? `\n\n**Under migration.** \`wix.config.json\` names site ${vars.migration.deploySiteId}, which only hosts this deployment; the site being migrated is ${vars.migration.parentSiteId} — its content is what the pages show and its dashboard (\`https://manage.wix.com/dashboard/${vars.migration.parentSiteId}\`) is where the business is managed. \`.env.local\` (\`wix env pull\`) carries that site's app: the SDK client and every admin, discovery and seed call run against it; only \`wix release\` goes to the deploy site. Completing the migration is a separate Wix CLI step, run by the user after approving the preview.`
+      ? `\n\n**Under migration.** \`wix.config.json\` names site ${vars.migration.deploySiteId}, which only hosts this deployment; the site being migrated is ${vars.migration.parentSiteId} — its content is what the pages show and its dashboard (\`https://manage.wix.com/dashboard/${vars.migration.parentSiteId}\`) is where the business is managed. \`.env.local\` (\`wix env pull\`) carries that site's app: the SDK client and every admin, discovery and seed call run against it; only \`wix release\` goes to the deploy site. Completing the migration, once the user approves the preview, follows \`.agents/skills/${vars.skill}/guides/migration.md\`.`
       : "";
     const text = readFileSync(TEMPLATE, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => (k === "MIGRATION" ? migration : (vars[k.toLowerCase()] ?? "")));
     writeFileSync(agents, text); written.push("AGENTS.md");