@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -0,0 +1,74 @@
+# Connect — wire an existing project to a managed Wix backend
+
+**Managed only.** This flow runs when the project type is `managed` and the operation is
+`connect` **or** `iterate` — a frontend project is already on disk (or a design URL was fetched into
+CWD) and the user wants it hosted on Wix and powered by Wix Business Solutions. It attaches Wix to the
+project (or reuses the existing connection when iterating), runs the shared backend flow, wires the UI
+to that backend, builds, and releases. **The only difference for `iterate`** — the project is already
+connected, so §1 skips `init` and reuses the existing `wix.config.json`.
+**No Designer, no templates, no binding-map machinery** — `SDK_HANDOFF.md` is the wiring reference.
+
+Run these in order:
+
+## 1 · Attach Wix to the project — skip if already connected
+
+**If a `wix.config.json` (or `.wix/`) is already present, the project is already connected to Wix — this is the *iterate* case.** Do **not** run `init` again (it's for attaching a *new* Wix project). Read `./wix.config.json` → hold `SITE_ID` in scratch, and skip to §2.
+
+> **Iterate is incremental.** An already-connected project may already be set up and/or seeded from a prior run. In §3–§4, **check current state before acting** — query installed apps before installing, check for already-seeded content before seeding (re-seeding duplicates it), and inspect existing wiring before adding. Do only the delta the new intent requires; leave the rest untouched.
+
+Otherwise, attach Wix in place:
+
+```bash
+CI=1 npm create @wix/new@latest init
+```
+
+Run from the project directory. It creates `wix.config.json` (with the `siteId` and the headless
+OAuth app) and registers the project's origin on that app. Read `./wix.config.json` → hold `SITE_ID`
+in scratch.
+
+**If the design was brought in from elsewhere** (a `.zip`/folder/file, or a fetched design-file URL),
+place it into CWD **first** — unzip/copy/fetch the design's files into the working directory so it's the
+project on disk — **then** `init`. An empty CWD plus a brought-in design is still `connect`, not create:
+land the design, then attach Wix to it.
+
+## 2 · Authenticate
+
+Per `references/managed/AUTHENTICATION.md` — `whoami`/login if needed, then mint the site token
+(`$TOKEN`) for `$SITE_ID`.
+
+## 3 · Backend flow (shared)
+
+- **`references/SETUP.md`** — install the apps the resolved `verticals[]` need.
+- **`references/SEED.md`** — create the backend content (and, if `imagery` is on, attach entity images).
+
+## 4 · Wire the existing UI
+
+**Read the frontend reference for *how to connect* first**, keyed on the brought project's framework:
+an **Astro** project → **`references/astro.md`** (auto-auth, no client); **any other framework or a
+static design** → **`references/non-astro.md`** (manual `OAuthStrategy` client). The chosen file carries
+the connect mechanics and the framework caveats; **`references/SDK_HANDOFF.md`** carries the
+per-capability packages, the SDK docs, and the seeded schema (all other content is queried live).
+
+Connect the existing project to the live backend. Install the SDK packages the loaded verticals need;
+then, with **additive** edits:
+- bind seeded content into the regions that already exist (product grids, post lists, item pages…);
+- add the connected feature the intent implies where it's missing (e.g. a contact/RSVP form, a cart);
+- always guard SDK calls (try/catch + fallback) so a failed call never blanks the page.
+
+A run must end with the site actually reading from / writing to Wix — `init` + `release` with nothing
+wired is not an acceptable outcome. If `imagery` is on and a surface needs an image, generate it per
+**`references/IMAGE_GENERATION.md`** (up to the per-run `imageCap`, Discovery §4); for any slot not
+generated — off, over the cap, or a failure — render the **themed-block fallback** (a styled `div` on
+the design tokens), never an empty or broken slot.
+
+## 5 · Build & release
+
+**Release once, at the very end** — only after Setup (§3), Seed **including the entity-image attach** (`SEED.md` § "Entity images"), the UI wiring (§4), and any imagery are all complete. Don't `build && release` mid-flow to preview. **A re-release does not refresh backend content:** a headless frontend fetches seeded content and entity images at **runtime**, so they're not in the build output — changing a seeded entity or attaching an image after release is live on the next request with **no** re-publish. Re-release only when the **frontend build output** changed. A backend image that isn't showing is an attach-shape bug (`SEED.md` § "Entity images"), not a stale cache — don't re-release to clear one.
+
+If the project has its own build (`package.json` with a `build` script), run `npm run build` and point
+`wix.config.json`'s `site.outputDirectory` at the build output. A **static** site (no build) needs the
+static-hosting fixes in **`references/managed/DEPLOYMENT.md`** — the entry file must be named
+`index.html`, and `outputDirectory` must point at the directory holding it (init's `./dist` default is
+wrong for static). Then finalize per **`references/managed/DEPLOYMENT.md`** (`npx @wix/cli@latest release` — Wix
+publishes + registers the origin OOTB). Close with a short summary (apps installed, content seeded, what
+was wired) and **both links — the live site URL and the site dashboard `https://manage.wix.com/dashboard/<SITE_ID>`** (see `managed/DEPLOYMENT.md` § "Give the user both links"; `<SITE_ID>` is the `siteId` in scratch), then run the feedback checkpoint (`managed/DEPLOYMENT.md` § "Before you sign off").

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

@@ -0,0 +1,130 @@
+# Create — scaffold a new managed Wix Headless project
+
+**Managed only.** This flow runs when the project type is `managed` and the operation is
+`create` (an empty directory + a "build me a site" intent). It scaffolds a fresh Wix Headless
+project, runs the shared backend flow against it, builds the frontend wired to that backend, and
+releases. There is **no Designer and no template library** — the frontend is built ad-hoc to the
+user's intent, using `SDK_HANDOFF.md` as the integration reference.
+
+Run these in order:
+
+## 0 · Resolve the frontend framework
+
+Default is **Astro** — the documented managed default. Set `frontendFramework` to a non-Astro
+framework **only if the user names one**: "Vite", "React", "Vue", "Svelte", "Next", "plain HTML/static",
+or any "not Astro / don't use Astro" phrasing. Never infer a framework the user didn't name
+(`references/non-astro.md` Caveat N1). Hold `frontendFramework` in scratch — it selects the **scaffold
+command (§1)**, the **wiring reference (§4)**, and the **build command (§5)**. Derive `<folder-name>` as
+a lowercase, npm-safe name from the brand (lowercase letters, numbers, hyphens; starts with a letter or
+number).
+
+## 1 · Scaffold the project
+
+Branch on `frontendFramework` from §0. **Both** branches end with a `wix.config.json` (the Wix link:
+`siteId` + private-app `appId`) in the project root — read it → hold `SITE_ID` (the `siteId`) in scratch.
+
+### Astro (default)
+
+Run the **documented** create command (flags and rationale: `references/astro.md` §1):
+
+```bash
+CI=1 npm create @wix/new@latest -- headless \
+  --folder-name <folder-name> \
+  --business-name "<Brand Name>" \
+  --site-template \
+  --skip-install \
+  --no-publish
+```
+
+- The `--` separator is required. Bare `--site-template` (no value) keeps it on the **blank** starter —
+  the model owns design, so don't adopt a business template; a value, or omitting the flag, would
+  prompt and abort in a non-interactive shell.
+- The command provisions the Wix site + private app and writes `wix.config.json`. It requires a
+  logged-in CLI session (step 2 handles login if needed).
+- It creates the project in a **subdirectory named `<folder-name>`** — there is no in-place option, so
+  **`cd <folder-name>`** and run the rest of the flow from inside it (it's the project root, with the
+  single `.wix/`).
+- `--skip-install` defers dependency install to step 4 (which adds the SDK package set); run
+  `npm install` there before building.
+
+### Non-Astro (a framework was named)
+
+There is **no Wix scaffolder for a non-Astro site** (`non-astro.md` N1) — so scaffold the framework's
+**own** project first, then `init` it onto Wix (two steps, in this order):
+
+```bash
+# 1. the framework's OWN documented scaffolder — e.g. Vite + React:
+npm create vite@latest <folder-name> -- --template react
+cd <folder-name>
+# 2. connect this folder to a fresh Wix headless project, IN PLACE:
+CI=1 npm create @wix/new@latest init
+```
+
+- Use the framework's documented create command (read its docs if unsure of the template flag) — Vite,
+  Next, SvelteKit, Vue, etc. For **plain static HTML** there's no scaffolder: create the folder and an
+  `index.html` yourself, then run `init`.
+- `npm create @wix/new@latest init` runs **in place** (no new subdirectory, no Astro files added): it
+  signs you in, provisions the Wix site + private app, and writes `wix.config.json`
+  (`siteId`, `appId`, `site.outputDirectory: "./dist"`). It takes no flags. Run it **from inside**
+  `<folder-name>` *after* the framework scaffold exists.
+- A static (no-build) frontend builds to no `dist` — fix `site.outputDirectory` per
+  `managed/DEPLOYMENT.md` ("Static frontends") before release.
+
+## 2 · Authenticate
+
+Per `references/managed/AUTHENTICATION.md` — `whoami`/login if needed, then mint the site token
+(`$TOKEN`) for `$SITE_ID`. (Scaffold already required a logged-in CLI session.)
+
+## 3 · Backend flow (shared)
+
+Run the agnostic flow against the scaffolded site:
+- **`references/SETUP.md`** — install the apps the resolved `verticals[]` need.
+- **`references/SEED.md`** — create the backend content (and, if `imagery` is on, attach entity images).
+
+## 4 · Build the frontend (wired to the backend)
+
+**Read the frontend reference for *how to connect* first — pick it by `frontendFramework` (§0):**
+
+- **Astro** (default) → **`references/astro.md`**: managed-Astro auto-authenticates, so the frontend
+  creates **no client** (no `OAuthStrategy`, no `clientId`) — you `import { x } from "@wix/<pkg>"` and
+  call methods. astro.md also carries the load-bearing caveats (the always-on `astro.config.mjs`
+  integrations, SSR error guards, island hydration).
+- **Non-Astro** → **`references/non-astro.md`**: the manual `OAuthStrategy` visitor-client path
+  (`createClient({ modules, auth: OAuthStrategy({ clientId }) })`), where `clientId` is the public
+  `appId` from the `wix.config.json` written by `init` (§1).
+
+Then build the pages the user's intent calls for, **wired to the live backend**, using
+**`references/SDK_HANDOFF.md`** for the per-capability packages, the SDK docs, and the seeded schema to
+bind (collection/form names + field keys; all other content is queried live). Install the SDK packages the loaded verticals need, author the pages/components directly in the
+project, and bind them to the live backend content. Keep it scoped to what was asked — no speculative pages.
+
+> **`npm install` note (Astro):** always run **`npm install --ignore-scripts`**. Astro pulls `sharp`
+> as an *optional* transitive dep for **local, build-time**
+> image optimization this headless flow never uses (all imagery is remote Wix Media URLs served through
+> plain `<img>`), and its from-source native build can fail and abort the whole install; `--ignore-scripts`
+> skips that failing build up front. **Do not** use the deprecated `--no-optional` (silent no-op in modern
+> npm — sharp still builds) or `--omit=optional` (sharp still resolves). A failed/absent `sharp` is
+> **expected and harmless — never build, retry, or repair it, and never spend time diagnosing it**
+> (`astro.md` Caveat A9).
+
+If `imagery` is on and a surface needs an image (e.g. a homepage hero, an about-section visual),
+generate it per **`references/IMAGE_GENERATION.md`** and use its `file.url` — up to the per-run
+`imageCap` (Discovery §4). Generate only what the pages actually use. For any slot **not** generated
+(imagery off, over the cap, or a generation failure), render the **themed-block fallback** — a styled
+`div` on the site's design tokens — never an empty slot or a broken `<img>` (`IMAGE_GENERATION.md`).
+
+## 5 · Build & release
+
+**Release once, at the very end.** Do **not** `build && release` mid-flow to "preview" progress. Reach this step only after **all** of the earlier work is done: Setup (§3), Seed **including the entity-image attach** (`SEED.md` § "Entity images" — pass-2 patches), the frontend wiring (§4), and any page imagery. A single release at the end is the target; each extra build+release cycle is wasted wall time.
+
+**A re-release does not refresh backend content — don't reach for one to "fix" seeded data or images.** A headless frontend fetches seeded backend content **and entity images at runtime** (via the SDK / REST), so that content is *not* baked into the build output. If you change a seeded entity or attach an image **after** releasing, the live site already reflects it on the next request — there is nothing to re-publish. Re-release **only** when the **frontend build output itself** changed. In particular, a backend image that isn't showing is an **attach-shape bug** (wrong write shape → the entity has no image — see `SEED.md` § "Entity images" / the capability recipe's **Attach images** step), **not** a stale CDN cache; don't re-release to "clear a cache" for it.
+
+Produce the build output, then finalize per **`references/managed/DEPLOYMENT.md`**
+(`npx @wix/cli@latest release` — Wix publishes the site and registers the origin OOTB). The build step
+depends on `frontendFramework` (§0):
+
+- **Astro** → `npx @wix/cli@latest build`.
+- **Non-Astro** → the framework's own build (e.g. `npm run build`); a static (no-build) site skips this.
+  `release` publishes whatever `site.outputDirectory` points at (default `./dist`).
+
+Close with a short summary (apps installed, content seeded, pages built) and **both links — the live site URL and the site dashboard `https://manage.wix.com/dashboard/<SITE_ID>`** (see `managed/DEPLOYMENT.md` § "Give the user both links"; `<SITE_ID>` is the `siteId` in scratch), then run the feedback checkpoint (`managed/DEPLOYMENT.md` § "Before you sign off").

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

@@ -0,0 +1,79 @@
+# 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>
+```
+
+## 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

@@ -0,0 +1,59 @@
+# 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/self-managed-headless/authentication/members/wix-login-page/wix-managed-login-using-the-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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,15 @@
+# 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

@@ -0,0 +1,55 @@
+# 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

@@ -0,0 +1,71 @@
+# 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-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce, marketing, analytics."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -31,6 +31,13 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
+## Analytics
+
+### [Query Site Analytics](references/analytics/query-site-analytics.md)
+**Technical:** Reads a site's analytics through the Semantic Model API. Covers listing semantic models, inspecting a model's schema (measures, dimensions, parameters), and querying data with a required time interval, filters, sorting, paging, and human-readable formatting. Key endpoints: /analytics/semantic-model/v3/semantic-models, /semantic-models/{id}, /semantic-models/query-data.
+
+---
+
 ## Blog
 
 ### [How to Create Blog Posts](references/blog/how-to-create-blog-posts.md)
@@ -53,7 +60,7 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 **Technical:** Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
 
 ### [Create Booking Service from Prompt](references/bookings/create-booking-service-from-prompt.md)
-**Technical:** Use when the user wants to create a booking service — e.g. "create a yoga class for $50", "set up consultations", "add a personal training appointment". Routes to the correct type-specific recipe (APPOINTMENT, CLASS, or COURSE), gathers business context, applies defaults, and creates the service.
+**Technical:** Use when the user wants to create a booking service — e.g. "create a yoga class for $50", "set up consultations", "add a personal training appointment", "create a hidden free test course with 8 sessions". Routes to the correct type-specific recipe (APPOINTMENT, CLASS, or COURSE), gathers business context, applies defaults, and creates the service. For COURSE services with session dates/counts, the course is not bookable until separate Calendar Events are created on the returned service schedule.
 
 ### [Create Appointment Service](references/bookings/create-appointment-service.md)
 **Technical:** Use when the user wants to create an appointment/consultation/1-on-1 service — e.g. "set up consultations for $75", "create a meeting service". Handles staff assignment, session duration, and pricing via bulkCreateServices API.
@@ -62,7 +69,10 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 **Technical:** Use when the user wants to create a group class — e.g. "create a yoga class for $50", "set up a pilates class". Handles group capacity, recurring sessions, and pricing via bulkCreateServices API.
 
 ### [Create Course Service](references/bookings/create-course-service.md)
-**Technical:** Use when the user wants to create a multi-session course — e.g. "create a 6-week workshop", "set up a training program for $300". Handles group capacity, full-course pricing, and fixed series via bulkCreateServices API.
+**Technical:** Use when the user wants to create a multi-session COURSE — e.g. "create a 6-week workshop", "set up a training program for $300", "create a hidden free test course with 8 online sessions". Handles group capacity, full-course pricing, `bulkCreateServices`, then creates bookable course session events with Calendar `bulkCreateEvents` using the returned `service.schedule.id`. Never put session dates under `course.sessions` in the Services V2 payload.
+
+### [Check Bookings Availability (and Diagnose Issues)](references/bookings/diagnose-availability-issues.md)
+**Technical:** Use when someone asks whether an appointment-based service has bookable availability, or why it shows no times / "customers can't book". Reports the current availability status first (via ListAvailabilityTimeSlots); diagnoses the cause only when there's no availability or the owner asks why — ruling out service-level blockers (hidden / online booking off), then running DiagnoseAvailability (`POST /v2/time-slots/diagnose`) for ordered reason codes, with a policy/capacity fallback.
 
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
 **Technical:** Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
@@ -184,6 +194,16 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
+## Marketing
+
+### [Create and Publish a Social Media Post (with AI generation)](references/marketing/create-and-publish-social-post.md)
+**Technical:** Creates and publishes (or schedules) a social media post to a connected channel (Instagram, Facebook, LinkedIn, TikTok, Pinterest, YouTube, Google Business Profile) via the Publisher API. Optionally generates the whole post from a free-text idea or the site's own assets (products, blog posts, events, bookings, coupons, categories), generates caption/title suggestions, and edits an existing image with AI. Verifies the channel is connected (and runs the OAuth connect flow if not), checks premium publishing quota, creates a draft item, then publishes it immediately or schedules it for a future date. Use when the user wants to create, generate, write, post, or schedule a social post, wants caption ideas or suggestions, or wants to connect a social channel (e.g. "post this to Instagram", "make a post from my product", "write a caption", "give me caption ideas", "connect my Pinterest", "schedule a post").
+
+### [Generate a Marketing Plan and Schedule Its Posts](references/marketing/generate-and-publish-marketing-plan.md)
+**Technical:** Generates a site's AI social media marketing plan (a calendar of marketing activities, each with per-channel post drafts) via the Marketing Plan API, then schedules the drafts for publishing. Covers optional marketing settings (goal, channels, tone, frequency, content pillars), asynchronous generation with polling, and generating posts for additional activities. Use for "generate a marketing plan", "create a social media plan/calendar", or "schedule my plan's posts".
+
+---
+
 ## Media
 
 ### [Upload Media to Wix](references/media/upload-media-to-wix.md)
@@ -213,6 +233,9 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Ricos Converter Service](references/rich-content/ricos-converter-service.md)
 **Technical:** Validates and converts content between Ricos documents and HTML/Markdown/plain text using the Ricos Documents API. Covers plugin configuration, format conversion in both directions, and document validation.
 
+### [Author Ricos Rich Content](references/rich-content/author-ricos-rich-content.md)
+**Technical:** Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) reused across Blog, Stores, Events, and CMS. Covers every common node shape — paragraphs, headings, lists, blockquotes, dividers, tables with cell fills, code blocks, images — plus inline text decorations and the nesting rules the format enforces.
+
 ---
 
 ## Site Properties
@@ -230,6 +253,9 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Query Sites](references/sites/query-sites.md)
 **Technical:** Lists and queries all sites associated with a Wix account using Sites API. Covers pagination with cursor-based navigation.
 
+### [Site Import](references/sites/site-import.md)
+**Technical:** Drives the autonomous Wix Site Import agent over REST (`/site-import/v1/imports`) to migrate a store/site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix. Covers Start/Poll/Reply/Cancel, relaying agent questions and progress in plain language, handling `DEPLOYED`/`FAILED`/`AUTH_EXPIRED`/`SESSION_EXPIRED` states, and post-deploy follow-up changes. Use when the user wants to import, migrate, or clone an existing store/site into Wix.
+
 ---
 
 ## Stores