@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,104 +0,0 @@
-# Deployment — managed (Wix CLI release)
-
-For a **managed** project, Wix owns the hosting, so finalizing the live site is a single command — Wix handles publishing the site **and** registering the deployed origin on the OAuth app **out of the box**. There are no manual publish or origin-registration calls (unlike the self-hosted types).
-
-## Release
-
-From the project directory:
-
-```bash
-CI=1 npx @wix/cli@latest release
-```
-
-- Publishes whatever the managed project is configured to deploy to Wix's hosting/CDN, and brings the live site up.
-- The deployed origin is registered on the OAuth app automatically — the frontend's visitor SDK calls are accepted from the live URL with no extra step.
-- The published URL is printed on stdout (`Site published on <url>`).
-
-## Give the user both links — the live site **and** the dashboard
-
-When you close the run, surface **two** links, not one:
-
-1. **The live site URL** — the `Site published on <url>` value from release above.
-2. **The site dashboard (Business Manager)** — `https://manage.wix.com/dashboard/<SITE_ID>`, where `<SITE_ID>` is the `siteId` held in scratch (read from `wix.config.json`). This is where the owner manages the site behind the headless frontend — view store orders, edit content, manage members, etc. **Always include it**: a headless site has no editor button, so without this link the owner has no obvious way back into their own backend, and the seeded content/apps look unreachable.
-
-Present them plainly, e.g.:
-
-```
-Live site:  <published-url>
-Dashboard:  https://manage.wix.com/dashboard/<SITE_ID>
-```
-
-## Suggest a custom domain (required, after release)
-
-The published URL is a generic Wix subdomain, so a custom domain is the obvious next step and the CLI handles the whole flow. **Run step 1 on every managed release and put its result in the same message as the links above** — this is a step you execute, not a judgment call about whether the user seems interested. It applies in a non-interactive run too: there's no one to ask, so just include the suggestions and a checkout link in your final message and let the user act on them.
-
-1. **Run the suggestion command.** Build a search query from what you know about the site — its business name, topic, or purpose from this run (not a generic placeholder):
-
-   ```bash
-   npx @wix/cli@latest account domain suggest "<business name or site topic>" --limit 5 --json
-   ```
-
-   All returned suggestions are already available for purchase. Name a few of the best fits in your message, and mention they can explore more options — re-run `suggest` with different keywords, a higher `--limit`, or `--tld com net ...` to filter extensions.
-
-2. **Give a checkout link.** Generate a site-scoped deep link for the domain the user picks — or, if nobody is there to pick, for the best of the suggestions — so the purchase is tied to this site and can be connected after payment:
-
-   ```bash
-   npx @wix/cli@latest account --site-id <SITE_ID> domain checkout-link <domain> --json
-   ```
-
-   Use the `siteId` from `wix.config.json`. `checkout-link` only returns a site-scoped checkout URL; it does **not** purchase a domain or charge the user. The user completes payment in the browser.
-
-   > Your site is live at <published-url>, and you can manage it from your [dashboard](https://manage.wix.com/dashboard/<SITE_ID>).
-   > To build a professional online presence, [connect a custom domain](<checkout-url>) — **mybusiness.com** is available.
-
-Once the suggestions and the link are in front of the user, you're done: if they don't want a domain, drop it — one offer, no upselling.
-
-## Before you sign off — feedback checkpoint
-
-This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the
-user to complain: run a quick self-check over the whole session (not just this final step) — a
-confusing API response, a doc that was wrong/missing, an extra retry, a workaround you had to invent,
-anything that cost more turns than it should have. If anything qualifies, **offer** to relay it to Wix
-as you deliver the links above; send only after an explicit yes.
-
-## Member login on a **non-Astro** frontend — register the callback URI (post-release)
-
-**Only when the run has member login on a non-Astro SPA/static frontend using the Wix login page** (`inline-recipes/how-to-code-members-non-astro.md` — the `getAuthUrl` → `/callback` handshake). Astro's built-in `/api/auth/*` callback shapes are auto-registered; a **non-Astro SPA's own callback path is not** — and **login stays dead (4xx on the login redirect) until you register it**. This is a genuine gap `wix release` does *not* close for you.
-
-- `release` auto-registers the deployed **origin** (`allowedRedirectDomains`) — that's the visitor-SDK/CORS surface (above). It does **not** register the member-login **callback URL** (`allowedRedirectUris`). These are two different fields; members needs **both**, and only the first is automatic.
-- **This is a post-release step** — the callback URL embeds the deployed origin, which is unknown until `release` prints it. Do it right after release, once the URL is known.
-- **⚠️ `allowedRedirectUris` IS writable via the API — do not conclude it's read-only/dashboard-only.** The `UpdateOAuthApp` reference may not list it among the obvious updatable fields, but a masked `PATCH` sets it. The trap is a **required field mask**: without `mask.paths` the `PATCH` returns `200` and **silently no-ops**.
-
-```bash
-ID="<clientId>"   # the OAuth app id == the public clientId
-# 1) GET first and append — the PATCH REPLACES the array, so include what's already there:
-curl -sS -w "\nHTTP_STATUS:%{http_code}" https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID \
-  -H "Authorization: Bearer $TOKEN"
-# 2) PATCH with the field mask (register BOTH the exact callback and the versioned-preview wildcard):
-curl -sS -X PATCH https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID \
-  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-  -w "\nHTTP_STATUS:%{http_code}" -d '{
-    "oAuthApp": { "id": "'"$ID"'",
-      "allowedRedirectUris": [ <existing…>, "https://<host>/callback", "https://*-<host>/callback" ] },
-    "mask": { "paths": ["allowedRedirectUris"] }
-  }'
-```
-
-- Include **both** the exact URL **and** the `https://*-<host>/…` wildcard — Wix serves versioned preview subdomains. The callback path must match the recipe's `redirectUri` **exactly** (e.g. `window.location.origin + '/callback'`).
-- `allowedRedirectDomains` and `allowedRedirectUris` can go in **one** `PATCH` (list both under `mask.paths`) if you ever need to set the origin by hand too.
-- **If you're not the one deploying**, you can't know the domain — flag the member-login callback URI to the user to register, and note **login is dead until they do** (higher-stakes than the origin flag).
-
-> **Custom-login** (`how-to-code-members-custom-login.md`) does **not** need this — `register`/`login` are direct API calls with no login-page redirect. Only `sendPasswordResetEmail`'s `redirectUri` and logout's return URL need allow-listing there.
-
-## Static frontends (no build step)
-
-These two fixes are **Wix-hosting facts** — they apply to a connected **static** site (plain HTML, no bundler) on the managed path, and the docs are silent on both. A bundler SPA that builds to its own output directory doesn't need them.
-
-- **The entry file must be named `index.html`.** Wix serves `index.html` at the site root. A brought-in design named anything else (e.g. `"My Design.html"`) **publishes "successfully" but 500s/404s at runtime**. Rename the entry to `index.html` **before** release and fix internal references to it.
-- **`site.outputDirectory` must point at the directory holding `index.html`.** `init` writes `site.outputDirectory: "./dist"`, which assumes an SPA that *builds* to `dist`. A static site has no build, so `./dist` is wrong — set `outputDirectory` in `wix.config.json` to the directory that actually contains `index.html`, or `release` publishes but the live site 404s at root.
-
-## Transient errors
-
-A release can hit transient infrastructure errors (`ECONNRESET`, `ETIMEDOUT`, `STATE_MISMATCH`, "try again shortly"). Retry the release serially up to **3×** with a short backoff. **Build failures are not retryable** — they're code bugs; fix the code, not the retry.
-
-That's the whole of finalize for `managed` — no `site-publisher` call, and no `oauth-app` **origin** PATCH (the origin is auto-registered). The **one** exception is the member-login callback on a non-Astro frontend above — that `allowedRedirectUris` PATCH is manual and required.

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

@@ -1,59 +0,0 @@
-# Non-Astro — the pinned docs to read *before* wiring a non-Astro frontend to Wix
-
-This is the framework reference for any **non-Astro** frontend — React/Vue/Svelte/Vite SPA or plain static HTML. Astro stays the default (`astro.md`); read this when the user **names a framework** or **brings a non-Astro design**. Like `astro.md`, it's an **index of doc pages** with one-line "what it settles" notes, **then a Caveats section**. It carries **no design, templates, payloads, or per-framework code** — the model designs and writes the whole frontend; this file says only *how it connects*.
-
-**This file is framework-axis only — it is mode-agnostic.** It is read in **both** the managed and self-managed flows, so it contains **no managed-vs-self-managed branching**: no `init` vs OAuth-app, no `wix release` vs external host, no `outputDirectory`, no `wix.config.json`. Anything that differs by *who hosts* lives in the project-type files (`managed/`, `self-managed/`) — you're already reading those in a known mode. Here is only what's **identical across both flows**: a non-Astro frontend talks to Wix through a manual `OAuthStrategy` visitor client + the SDK, the same way no matter who hosts it.
-
-**The auth rule (the cross-skill boundary).** **Astro = auto-auth, no client. Non-Astro = manual client.** Unlike Astro, you create a client — `createClient({ modules, auth: OAuthStrategy({ clientId }) })`. For non-Astro this is the **documented, correct** model (the "Create a Client with OAuth" doc scopes itself to "frameworks other than Astro"). The `clientId` is the project's **public** OAuth client id — **not** a secret. **Where that id comes from is your flow's `AUTHENTICATION.md`** (managed: the `appId` in `wix.config.json`; self-managed: the OAuth app you created) — this file just *uses* it.
-
-**Two sub-shapes, split on build — a framework fact, not a hosting fact:** **bundler SPA** (has a build step → `npm install` + `import`) vs **static HTML** (no build → load the SDK from a CDN). The caveats below split on that.
-
-**How to use it.** Before authenticating or wiring data, read the pinned pages top-to-bottom — read-then-act, never invent a URL or a body from memory.
-
-**URL form & how to read it.** Each link is the **`.md` twin** of a docs article. A page pinned here is **already curated — read it directly; don't re-discover it with search.** The two read paths take **different URL forms** — don't mix them:
-
-- **`curl` the link — first priority. Fetch it as-is (keep the `.md`)** for raw markdown.
-- **MCP doc tools — second priority** (discovery of a page this file doesn't pin, or a fallback if a fetch fails). Pass the URL *without* the `.md` suffix — `ReadFullDocsArticle` for the article pages here, `SearchWixSDKDocumentation` to reach SDK methods this file doesn't pin.
-- **No MCP, or a shape not pinned anywhere → doc discovery** (`DOC_DISCOVERY.md`): a `curl` semantic search (`document_type: SDK`/`WIX_HEADLESS`) plus structured schema lookup, then read the hit's `.md?apiView=SDK`.
-
----
-
-## 1 — Authenticate (the heart — manual client, identical in both flows)
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/oauth/create-a-client-for-authentication-with-oauth.md> | **The model.** Install `@wix/sdk` + the domain packages, then `createClient({ modules, auth: OAuthStrategy({ clientId }) })`. clientId only, **no secret in the frontend**. Explicitly scoped to "frameworks other than Astro." Create the client **once** and reuse it. |
-| <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md> | **`OAuthStrategy` reference** — visitor sessions (automatic) vs member flows (managed/custom/external); token + session methods; confirms `clientId` only. |
-| <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/visitors/handle-visitors-using-the-js-sdk.md> | **Visitors & members via the JS SDK** — visitor token sessions out of the box, and member login when the site needs it. Members are **first-class** on the non-Astro path (not deferred). |
-| <https://dev.wix.com/docs/go-headless/authentication/members/wix-login-page/add-a-wix-login-page-js-sdk.md> | **Member login (Wix login page)** — the manual `OAuthStrategy` handshake: `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`. Login *is* sign-up (the Wix page logs in or registers); member tokens are the **same shape** as visitor tokens (`role: member`), so they reuse the visitor session machinery — login just swaps the token set. **`clientId` only (no secret); the connected site must be PUBLISHED and the `redirectUri` must be an exact-match allow-listed URI, or `getAuthUrl` fails; default to the Wix login page** over custom/external. **Full frontend contract → Read `inline-recipes/how-to-code-members-non-astro.md`** (local — Read it, don't curl). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields → Read `inline-recipes/how-to-code-members-custom-login.md`** instead (`client.auth.register`/`login`; works on any project type — pick by intent, not project type). |
-| <https://dev.wix.com/docs/sdk/articles/set-up-a-client/about-the-wix-client.md> | **Confirms non-Astro *does* need a client** — the "when you need a client vs not" list; non-Astro (managed or self-managed) is on the "needs a client" side, the mirror of Astro. |
-
-> **clientId source is deferred.** This file uses the `clientId`; it does **not** say where it comes from. That's `{managed,self-managed}/AUTHENTICATION.md` — managed reads `appId` from `wix.config.json`; self-managed uses the OAuth app you created. Don't re-mint or re-fetch it if the flow already provides it.
-
-## 2 — Frontend data access (identical in both flows)
-
-All reads and writes go through the client from §1 — the SDK call shapes are framework-identical (the model adapts the idiom: React effect / Vue `onMounted` / Svelte store). For **which packages** a capability needs and the **SDK module docs** for each call shape, use `SDK_HANDOFF.md` §3 (the package map) — don't restate it here. For **what was seeded** and the IDs to bind, cross-link `SEED.md`; the frontend reads it with the visitor client.
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/install-sdk-packages.md> | Installing `@wix/sdk` + domain packages and their current versions (bundler path). |
-
-## 3 — Build the frontend (framework fact, not hosting)
-
-- **Bundler SPA** — produce the build output with the project's own `npm run build`.
-- **Static HTML** — there is **no build**; the HTML *is* the deployable artifact.
-
-This file **stops at "produce the build output."** *Where that output is deployed and how* — `outputDirectory`, publish, origin registration, the `index.html`-at-root rule — is host-specific and lives in `{managed,self-managed}/DEPLOYMENT.md`, not here.
-
-## 4 — Caveats (framework-invariant only)
-
-These hold regardless of who hosts. Host-specific gotchas (static `outputDirectory`, the `index.html` rename) are filed in `managed/DEPLOYMENT.md`, where you're in a known mode. (Numbering: N2/N3 were retired; the gap is intentional and the remaining IDs are kept stable so inbound references don't shift.)
-
-| Caveat | What it says |
-|---|---|
-| **N1 — No Wix scaffolder for a new non-Astro site** | There is **no** Wix command to scaffold a fresh React/Vue/static site — the non-Astro flow is connect-only. To *create* from scratch, the model runs the framework's **own** `npm create …` (e.g. `npm create vite@latest`), then the flow connects it. **Never infer a framework the user didn't name.** |
-| **N4 — No-bundler sites load the SDK from a CDN** | With **no bundler** (static HTML), import the SDK in a `<script type="module">` from `https://esm.sh/@wix/sdk@1` (plus the domain packages the same way) — there's no `npm install` step to bundle it. With a bundler, use normal `npm install` + `import`. |
-| **N5 — Client-only ⇒ no elevation ⇒ public-read** | A pure SPA/static frontend runs with a **visitor** token and **no server**, so there is no `auth.elevate`. CMS collections it reads must be **public-read**; anything member-scoped needs member auth. True regardless of who hosts. (Contrast Astro, which can elevate in a backend `/api` endpoint.) |
-| **N6 — `clientId` is public; inline it** | The OAuth `clientId` is public, not a secret — it's fine to inline it directly in client code/bundle; there's no runtime secret to protect and no env-var indirection required. (Where the value comes from is still the flow's `AUTHENTICATION.md`.) |
-| **N7 — Resolve `wix:image://` URIs with the SDK, never by hand** | SDK media fields (product/blog/CMS images) come back as internal identifiers like `wix:image://v1/<hash>/<file>#originWidth=…`, **not** ready URLs. Convert them with the SDK media module — `import { media } from '@wix/sdk'`, then `media.getScaledToFillImageUrl(uri, w, h, {})` (**returns the URL string directly — do NOT append `.url`; the 4th `options` arg is required, pass `{}`**), or `media.getImageUrl(uri).url` for the original (**that** one returns a `{ url }` object). The two shapes differ — mixing them (`getScaledToFillImageUrl(...).url`) resolves every image to `undefined`. Hand-building a `static.wixstatic.com/.../v1/fit/...` URL gets the format wrong and the image **403s** (or silently fails to load). Only `wix:image://` values need this — an already-absolute `https://` URL (e.g. an Unsplash placeholder) passes straight through. Docs: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>. |
-| **N8 — Member login is a manual `OAuthStrategy` round-trip on the same client** | Login (which *is* sign-up), logout and "am I a member?" run on the visitor client from §1 — don't build a second client. Drive the handshake yourself: `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`; **persist and renew** member tokens exactly like visitor tokens (`renewToken`, re-hydrate with `setTokens` on boot). Preconditions that bite: **`clientId` only**, **site PUBLISHED**, **`redirectUri` allow-listed exact-match**, **default to the Wix login page**. Read the current member with **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`). **No `auth.elevate`** — a member reads their own data under the member token, and a serverless SPA has no elevation anyway (N5). Full contract: `inline-recipes/how-to-code-members-non-astro.md`. |

package/skills/wix-headless/references/self-managed/AUTHENTICATION.md

@@ -1,22 +0,0 @@
-# Authentication — self-managed (TBD)
-
-For a **self-managed** project (self-hosted, where the user manages their own hosting and credential supply), the authentication method is **not yet decided — TBD**.
-
-When defined, this file must specify how `self-managed` obtains, for the rest of the (project-type-agnostic) flow:
-
-- **`$TOKEN`** — a bearer token authorized for the metasite (used as `Authorization: Bearer $TOKEN`).
-- **`$SITE_ID`** — the metasite id (used as the `wix-site-id` header on every site-scoped call).
-- **`clientId`** — the OAuth app's public client id for the frontend's `OAuthStrategy` (the OAuth **app id and client id are the same value** — app-id === client-id).
-
-It then ends at the same universal REST call shape every type uses:
-
-```bash
-curl -sS -w "\nHTTP_STATUS:%{http_code}" \
-  -X POST "https://www.wixapis.com/<endpoint>" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "wix-site-id: $SITE_ID" \
-  -H "Content-Type: application/json" \
-  -d '<body>'
-```
-
-> **TBD.** Until the self-managed auth method is defined, a `self-managed` run can't obtain a token — **stop with a clear error** and tell the user this project type isn't wired yet.

package/skills/wix-headless/references/self-managed/DEPLOYMENT.md

@@ -1,15 +0,0 @@
-# Deployment — self-managed (TBD)
-
-For a **self-managed** project, the deploy/finalize steps are **not yet decided — TBD**.
-
-Because hosting is the user's (not Wix's), this will likely mirror the self-hosted finalize pattern — **publish the metasite** and **register the deployed origin** on the OAuth app once the live URL is known (see `../stripe/DEPLOYMENT.md` for that shape) — but the exact mechanism, and how credentials/URL are supplied, are TBD.
-
-> **TBD.** Until this is defined, tell the user that `self-managed` deployment isn't wired yet, and that the frontend's visitor calls will be rejected until its origin is registered on the OAuth app.
-
-## Before you sign off — feedback checkpoint
-
-This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the
-user to complain: run a quick self-check over the whole session — a confusing API response, a doc
-that was wrong/missing, an extra retry, a workaround you had to invent, anything that cost more turns
-than it should have. If anything qualifies, **offer** to relay it to Wix before you close out; send
-only after an explicit yes.

package/skills/wix-headless/references/stripe/AUTHENTICATION.md

@@ -1,55 +0,0 @@
-# Authentication — stripe (Stripe Projects → Wix)
-
-For a **stripe** project (self-hosted, provisioned via Stripe Projects), every Wix call is a plain `curl` against `wixapis.com` with a bearer token. The credentials come from the project's `.env` (synced by Stripe Projects when Wix was connected), and the token is minted directly from the OAuth client-credentials grant. This file is the authority for how `stripe` obtains `$TOKEN`, `$SITE_ID`, and the public `clientId`; the flow files defer here.
-
-## Inputs from `.env`
-
-Stripe Projects namespaces each provider's vars, and Wix's own names already begin with `WIX_`, so a real provision yields a **doubled prefix**:
-
-| Var                     | Role                                                                                              |
-| ----------------------- | ------------------------------------------------------------------------------------------------- |
-| `WIX_WIX_CLIENT_ID`     | the OAuth app `client_id` — also the frontend `OAuthStrategy({ clientId })`                       |
-| `WIX_WIX_CLIENT_SECRET` | the OAuth app `client_secret` — **server-side only**; mints the token, never goes to the frontend |
-| `WIX_WIX_METASITE_ID`   | the metasite id → the `wix-site-id` header on every site-scoped call                              |
-
-The plain `WIX_*` names are accepted as a fallback (in case the provider definition changes). Read them at runtime. If `client_id`/`client_secret` are absent, Wix isn't connected in this project — **stop with a clear error**.
-
-The public `clientId` for the frontend's `OAuthStrategy` is `WIX_WIX_CLIENT_ID` (not secret).
-
-## Minting the token — inline, secret stays out of context
-
-Run this as a **single Bash call**. It sources `.env` *inside the shell*, so the command text references `$WIX_WIX_CLIENT_SECRET` but the secret value is never typed, printed, or returned. The minted token is written to a tmp file so later calls reuse it **without re-minting and without the token entering the model context**:
-
-```bash
-set -a; . ./.env; set +a
-curl -sS -X POST "https://www.wixapis.com/oauth2/token" \
-  -H "Content-Type: application/json" \
-  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}\",\"client_secret\":\"${WIX_WIX_CLIENT_SECRET:-$WIX_CLIENT_SECRET}\"}" \
-  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])" > /tmp/wix_token \
-  && test -s /tmp/wix_token && echo "token minted" || echo "MINT FAILED — Wix not connected, or app/creds invalid"
-```
-
-That endpoint returns `{ "access_token": "<…>", "token_type": "Bearer", "expires_in": 14400 }`. `instance_id` is **optional and omitted**. The token is a real OAuth token with a **4-hour expiry**.
-
-> **Shell state does not persist between Bash calls** — that is *why* the token goes to `/tmp/wix_token`. Mint once at the start of the run; every later call reads it back. Each mint here returns a *different, equally valid* token; "mint once" is for simplicity, not because re-minting is pointless.
-
-## REST call shape
-
-Every later call re-sources `.env` (for the non-secret metasite id) and reads the token from the tmp file — both cheap, both keep secrets out of context:
-
-```bash
-set -a; . ./.env; set +a
-TOKEN=$(cat /tmp/wix_token)
-SITE_ID="${WIX_WIX_METASITE_ID:-$WIX_METASITE_ID}"
-curl -sS -w "\nHTTP_STATUS:%{http_code}" \
-  -X POST "https://www.wixapis.com/<endpoint>" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "wix-site-id: $SITE_ID" \
-  -H "Content-Type: application/json" \
-  -d '<body>'
-```
-
-- **`Authorization: Bearer $TOKEN`** — the `Bearer` prefix is required.
-- **`wix-site-id: $SITE_ID`** — required by every site-scoped family (Stores v3, CMS v2, Blog v3, Forms v4, Apps-Installer v1, …). Harmless where unread; include it always.
-- **`Content-Type: application/json`** — on every POST/PATCH body.
-- **Parsing the response:** `-w` appends a `HTTP_STATUS:<code>` line *after* the JSON body. `grep` that line for the status, but parse the **body separately** — piping the combined output to a JSON parser (`python3 -m json.tool`, `json.load`, `jq`) chokes on the trailing status line (`Extra data: line 2 …`). Capture the body to a file with `-o body.json` (status still comes from `-w`), or drop the last line, before parsing.

package/skills/wix-headless/references/stripe/DEPLOYMENT.md

@@ -1,71 +0,0 @@
-# Deployment — stripe (self-hosted; publish + register origin)
-
-For a **stripe** project, hosting is the user's, so two one-time backend actions finalize the live site. Both use the token from this folder's `AUTHENTICATION.md`; run them once the deployed site is up.
-
-## 1 · Publish the Wix site
-
-**Always publish the metasite after deploying.** Some Wix-served flows the frontend relies on (redirects to Wix-hosted pages and other features served from the published site) only work once the site has been published. Just publish every time, so a flow that needs it never silently fails. The call is idempotent and takes **no body**:
-
-```bash
-set -a; . ./.env; set +a
-TOKEN=$(cat /tmp/wix_token); SITE_ID="${WIX_WIX_METASITE_ID:-$WIX_METASITE_ID}"
-curl -sS -w "\nHTTP_STATUS:%{http_code}" \
-  -X POST "https://www.wixapis.com/site-publisher/v1/site/publish" \
-  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: $SITE_ID" \
-  -H "Content-Type: application/json" -d '{}'
-# 200 with an empty body `{}` means published — that 200 is the only success signal (no URL is returned).
-```
-
-## 2 · Register the deployed origin on the OAuth app
-
-For the frontend's visitor calls (`OAuthStrategy` with the public `clientId`) to be **accepted from the deployed site**, the site's origin must be on the OAuth app's allowed domains. Otherwise every browser SDK call from the live URL is rejected.
-
-We don't own the hosting, so the deployed URL is unknown until the site is deployed — this is a **post-deploy step performed once the URL is known** (it can't be done during Setup/Seed). The OAuth app's id **is the `clientId`** — `WIX_WIX_CLIENT_ID`.
-
-### Idempotent — register a given URL only once
-
-First **read** the app's current allowed domains; if the deployed origin is already present, the registration is already done — **skip it**. Only ever add a URL that isn't there yet.
-
-```bash
-set -a; . ./.env; set +a
-TOKEN=$(cat /tmp/wix_token); ID="${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}"
-curl -sS -w "\nHTTP_STATUS:%{http_code}" \
-  "https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID" \
-  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"
-# → read oAuthApp.allowedRedirectDomains; if the deployed origin is already in it, you're done.
-```
-
-### Add the deployed origin
-
-`PATCH` the app, sending the **existing** `allowedRedirectDomains` **plus** the new origin (the API replaces the field, so include what's already there), with a field mask:
-
-```bash
-set -a; . ./.env; set +a
-TOKEN=$(cat /tmp/wix_token); ID="${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}"
-curl -sS -w "\nHTTP_STATUS:%{http_code}" -X PATCH \
-  "https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID" \
-  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-  -d '{
-    "oAuthApp": { "id": "'"$ID"'", "allowedRedirectDomains": [ <existing…>, "<deployed-origin>" ] },
-    "mask": { "paths": ["allowedRedirectDomains"] }
-  }'
-```
-
-- `<deployed-origin>` is the live site's domain/URL (what the browser SDK runs on).
-- For the **exact field semantics and format** (domain vs. full URL, member-login redirect URIs vs. allowed domains), read the doc — don't guess: <https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app.md>. Member-login redirect URIs are a **separate field** (`allowedRedirectUris`) from the origin (`allowedRedirectDomains`): the visitor SDK only needs the origin allowed, but **if this deploy has member login via the Wix login page, the member-login callback must also be registered** in `allowedRedirectUris` — same masked-`PATCH` shape as the origin (add both under one `mask.paths`), and required or login 4xxs. Mechanics + the "not read-only" gotcha: `../managed/DEPLOYMENT.md` → "Member login on a non-Astro frontend". (Custom login — `../inline-recipes/how-to-code-members-custom-login.md` — needs neither, as it has no login-page redirect.)
-
-> **If the live site's visitor token call still 400s after the origin is registered, suspect the bundle — not CORS.** An unregistered origin and an `undefined` `clientId` in the build produce the same browser-side 400. Before chasing CORS/propagation, confirm the real `clientId` value is actually inlined in the deployed bundle (see `../SDK_HANDOFF.md` §2).
-
-## If deployment is NOT part of this agent flow
-
-If the agent isn't the one deploying — the user will deploy the site themselves — the skill **cannot know the deployed URL**, so it cannot register the origin. (It can still publish the site — step 1 doesn't need the URL.) **Flag the origin step to the user clearly**, e.g.:
-
-> *"One required step remains before the frontend can talk to Wix: once your site is live, its URL must be registered on the Wix OAuth app (allowed domains). Give me the deployed URL — or re-run this skill with it — and I'll register it. Until then, Wix SDK calls from the live site will be rejected."*
-
-## Before you sign off — feedback checkpoint
-
-This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the
-user to complain: run a quick self-check over the whole session (not just this final step) — a
-confusing API response, a doc that was wrong/missing, an extra retry, a workaround you had to invent,
-anything that cost more turns than it should have. If anything qualifies, **offer** to relay it to Wix
-before you close out; send only after an explicit yes.

package/skills/wix-headless/scripts/bootstrap.mjs

@@ -1,156 +0,0 @@
-#!/usr/bin/env node
-import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-// ── tiny event protocol (one JSON object per line) ───────────────────────────
-const emit = (event, extra = {}) =>
-  process.stdout.write(JSON.stringify({ event, ...extra }) + '\n');
-const fail = (event, extra = {}) => {
-  emit(event, { ok: false, ...extra });
-  process.exit(1);
-};
-
-// ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
-const isWin = process.platform === 'win32';
-const bin = (name) => (isWin ? `${name}.cmd` : name);
-const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
-
-// Force the CLI into non-interactive "agent" mode. Without an agent signal in
-// the env, `wix login` renders an interactive Ink TUI (device code + keypress)
-// that needs a raw TTY and crashes in an agent sandbox — and it never emits the
-// JSON login events this script forwards. The CLI uses @vercel/detect-agent,
-// whose first check is the AI_AGENT env var, so setting it guarantees agent mode
-// (and the awaiting_user/success/logged_in events) for every child we spawn.
-// Respect an existing value so a known runner (claude, cursor, …) keeps its name.
-const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-skill' };
-
-// Where the detached login parks its output between runs. It has to outlive this
-// process, so it can't be a pipe and can't live in the project.
-const STATE_DIR = join(tmpdir(), 'wix-headless-login');
-const LOG = join(STATE_DIR, 'login.log');
-const PIDFILE = join(STATE_DIR, 'login.pid');
-
-// run a command, capture stdout+stderr (combined), return {status, out}
-function capture(cmd, args, opts = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
-  return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
-}
-
-// ── 1. CLI reachable (via npx — no install) ──────────────────────────────────
-function checkCli() {
-  const r = capture(WIX[0], [...WIX.slice(1), '--version']);
-  if (r.status !== 0) fail('cli_unreachable', { detail: r.out.trim().slice(0, 400) });
-  // npx interleaves "npm notice …" lines with the version, so don't just take the
-  // last line — pick the first semver-looking token, falling back to the last line.
-  const version = (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
-  emit('cli_ok', { version });
-}
-
-// ── 2. Reuse an existing session, or start device login ──────────────────────
-const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
-
-function loginEvents() {
-  if (!existsSync(LOG)) return [];
-  return readFileSync(LOG, 'utf8')
-    .split('\n')
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .map((l) => {
-      try {
-        return JSON.parse(l);
-      } catch {
-        return null; // non-JSON CLI chatter
-      }
-    })
-    .filter((e) => e && e.event);
-}
-
-const alive = (pid) => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-// A login this machine started earlier may still be waiting on the browser. Reuse
-// its code instead of minting a second one — a new login invalidates nothing, but
-// it hands the user a different code than the one already on their screen.
-function pendingLogin() {
-  if (!existsSync(PIDFILE)) return null;
-  let state;
-  try {
-    state = JSON.parse(readFileSync(PIDFILE, 'utf8'));
-  } catch {
-    return null;
-  }
-  if (!state.pid || !alive(state.pid)) return null;
-  const ev = loginEvents().find((e) => e.event === 'awaiting_user');
-  if (!ev) return null;
-  // Don't hand back a code that's about to expire mid-typing.
-  const ageSeconds = Math.round((Date.now() - state.startedAt) / 1000);
-  if (ageSeconds > (ev.expiresInSeconds ?? 600) - 60) return null;
-  return ev;
-}
-
-// Detach so the login keeps polling after this process exits. stdio goes to a
-// file, not a pipe: a pipe dies with the parent, and the CLI would get EPIPE.
-function startLogin() {
-  mkdirSync(STATE_DIR, { recursive: true });
-  writeFileSync(LOG, '');
-  const out = openSync(LOG, 'a');
-  const child = spawn(WIX[0], [...WIX.slice(1), 'login'], {
-    detached: true,
-    stdio: ['ignore', out, out],
-    env: AGENT_ENV,
-    shell: isWin,
-  });
-  child.on('error', (e) => fail('login_failed', { detail: String(e) }));
-  writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
-  child.unref();
-}
-
-async function waitForCode(timeoutMs = 60000) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const events = loginEvents();
-    const ev = events.find((e) => e.event === 'awaiting_user');
-    if (ev) return ev;
-    const bad = events.find((e) => e.event === 'login_failed');
-    if (bad) fail('login_failed', bad);
-    await new Promise((r) => setTimeout(r, 500));
-  }
-  const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
-  fail('login_failed', {
-    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
-  });
-}
-
-// The next move is the user's, so hand the code back and exit rather than holding
-// the caller open for a browser round-trip. `message` is the sentence to relay.
-function surrenderTo(ev) {
-  emit('awaiting_user', {
-    ...ev,
-    message:
-      `To connect your Wix account, open ${ev.verificationUri} and enter the code ` +
-      `${ev.userCode}. Tell me once you're done and I'll continue.`,
-  });
-  process.exit(0);
-}
-
-// ── main ────────────────────────────────────────────────────────────────────
-checkCli();
-
-if (hasExistingSession()) {
-  emit('logged_in');
-  process.exit(0);
-}
-
-const pending = pendingLogin();
-if (pending) surrenderTo(pending);
-
-startLogin();
-surrenderTo(await waitForCode());

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

@@ -1,8 +0,0 @@
-{
-  "bundle": "wix-headless-replatform",
-  "version": "2.2.3",
-  "sourceRepo": "wix-private/replatform",
-  "sourcePath": "skills/wix-headless-replatform/",
-  "sourceCommit": "6bde03f",
-  "publishedAt": "2026-10-22T22:14:10Z"
-}

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

@@ -1,116 +0,0 @@
----
-name: wix-headless-replatform
-description: Clone, rebuild, migrate, or reverse-engineer a public website home page into a Wix Headless frontend while preserving source identity, SEO, interactions, and visual fidelity.
----
-
-# wix-headless-replatform
-
-## Role
-
-Drive a close-enough, visually polished Wix Headless frontend from a source website.
-The implemented scope is one resolved home page and the default output is
-`projects/<project-name>`, derived from the hostname. Use Wix CLI Headless, Astro,
-TypeScript, and Tailwind; use React only for complex interactive islands.
-Reject additional-page and explicit-URL scope with an actionable explanation until a later
-approved workflow defines page resolution and shared evidence across routes.
-
-This entry skill is the supervisor. It decides the next workflow stage and loads only the
-resource for that stage. Do not preload every resource or reference: stage-specific rules
-are deliberately demand-loaded.
-
-Two modes exist:
-
-- **Standalone clone:** source URL to a new, real Wix CLI Headless project.
-- **Migration phase:** `--handoff <migration-project>/website/handoff.json` continues on
-  the migration-owned destination. Never omit `--handoff` for an integrated migration:
-  the standalone command creates a second site.
-
-## Non-negotiable invariants
-
-- Treat the requested public branded homepage as authorized; apply the boundaries in
-  `references/safety.md` without asking a separate routine authorization question.
-- Browser-backed extraction is mandatory. Do not substitute HTML-only extraction.
-- Resolve the home page before capture. Build only from a validated frozen extraction
-  manifest; raw observations are never builder inputs.
-- A standalone output must be a successful Wix CLI scaffold with valid Wix identity and
-  runnable `dev` and `build` scripts. Never hand-create a Wix-shaped substitute.
-- In migration mode, reuse the handoff's site/project and route/data-binding intent; do
-  not create or retarget a second destination.
-- Preserve source structure, first-viewport evidence, chrome hierarchy, source assets,
-  fonts, core interactions, SEO, internal URL behavior, and branded fallback behavior.
-- A build is not completion. Completion requires the accepted post-build visual-review and
-  gap-loop evidence described by `rp-qa-gap-loop`, plus optional facelift acceptance only
-  when the user explicitly selected facelift mode.
-
-## Supervisor protocol
-
-On every new or resumed run:
-
-1. Resolve the source URL, output directory, and mode. In migration mode read
-   `website/handoff.json` and `docs/site-clone/frontend-automation-state.json` first.
-2. Select the first incomplete stage from the table below and read only that resource's
-   `SKILL.md` plus the references it explicitly needs.
-3. Execute that stage until it writes its required durable artifact, or records a specific
-   genuine blocker with evidence and an exact unblock action.
-4. Re-select the stage after every boundary. Do not say that a required next step “needs to
-   happen” and end the run; load its resource and perform it.
-
-| Stage | Load only when | Resource | Durable outcome |
-| --- | --- | --- | --- |
-| Context | mode, scope, project, or browser environment is unresolved | `resources/rp-project-context/SKILL.md` | valid context, approval record, runnable project/plan state, or blocker |
-| Evidence | frozen home-page extraction is absent or stale | `resources/rp-source-evidence/SKILL.md` | validated `extraction/latest.json` and frozen manifest, or global blocker |
-| Implementation | frozen build plan exists and home UI is incomplete | `resources/rp-ui-implementation/SKILL.md` | manifest-hash-aware runnable home implementation |
-| Verify and improve | build, QA, comparison, review, fix, report, release, or receipt is incomplete | `resources/rp-qa-gap-loop/SKILL.md` | accepted result, `done_with_gaps`, or global blocker |
-| Optional facelift | normal clone accepted and automation state says facelift is requested | `resources/rp-facelift/SKILL.md` | accepted facelift review, or blocker |
-
-When `frontendPhase.allowedNow` is `plan`, complete only the plan-eligible context and
-evidence work and leave a resumable plan-state record. When it is `build`, continue through
-implementation and verification against the migration-owned project.
-
-## One-click continuation
-
-A migration handoff declaring `automationMode: "one_click"` authorizes routine scope and
-frontend checkpoints. Record those approvals in
-`docs/site-clone/frontend-automation-state.json`; do not pause to ask whether to proceed
-with a required stage, screenshot review, or authorized gap-fix pass.
-An explicit facelift request may be carried from 1-click intake, but it remains gated until
-normal clone acceptance; 1-click never implies facelift by itself.
-
-In a one-click build run, keep selecting and executing stages until one of these durable
-outcomes exists:
-
-- `website/completion.json` is valid and the latest visual review is complete with no open
-  critical/high identity finding; or
-- five visual gap cycles have been completed and `website/completion.json` records the
-  truthful terminal status `done_with_gaps` with the final reviewed evidence; or
-- a genuine blocker is recorded with owner, evidence, attempted recovery, and exact next
-  authority/action needed.
-
-An owned local extraction gap is not a genuine blocker. Continue unrelated work, use no more
-than two distinct targeted recovery attempts, then build the affected dependency closure
-provisionally and surface post-assembly choices in `final-report.json` and `.md`.
-
-Before classifying a shell, browser, or network failure as a blocker, use the
-repo-local Wix/Yarn toolchain PATH ordering and follow the recovery order in
-`resources/rp-project-context/SKILL.md`: aligned-shell retry, then the
-required browser/network escalation and retry, then blocker only if it still
-fails or approval is pending. After every gap iteration, immediately return to
-the stage table; never treat a first build, a reported plan, or backend import
-as frontend completion.
-
-In migration mode the build must also leave the final route manifest that old-link
-preservation consumes (`output-contract.md`, "Migration terminal receipt"). A built site is
-not proof that old URLs work; redirect application and public verification stay pending
-until the cutover step runs them.
-
-## Commands
-
-Run `node scripts/site-clone.mjs <source-url>` for standalone mode, or
-`node scripts/site-clone.mjs <source-url> --handoff <path>` for migration mode. The active
-resource gives the exact commands and inputs for its stage.
-
-## References
-
-Resources load their own references. The shared contracts are kept under `references/`:
-`safety.md`, `workflow.md`, `extraction-schema.md`, `output-contract.md`,
-`qa-checklist.md`, and the interaction/layout/control/normalization/gap contracts.

package/skills/wix-headless-replatform/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Wix Headless RePlatform"
-  short_description: "Clone sites into Wix Headless frontends"
-  default_prompt: "Use $wix-headless-replatform to clone this website into a Wix Headless frontend."
-policy:
-  allow_implicit_invocation: true