@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-auth/references/device-flow.md

@@ -0,0 +1,140 @@
+# Device Flow
+
+Implements the OAuth 2.0 Device Authorization Grant (RFC 8628). The user approves in a browser while the agent polls for tokens.
+
+Produces two kinds of token:
+- **Account token** — works for account-level APIs (e.g. list sites). Expires in ~4 hours.
+- **Site token** — required for any site-specific API (contacts, products, bookings, …). Derived on demand from the account `refreshToken` + a `siteId`. Expires in ~15 minutes.
+
+## Constants
+
+```
+BASE_URL  = https://manage.wix.com
+CLIENT_ID = 6f95cec8-3e98-48b9-b4e5-1fb92fcd9973
+```
+
+Required headers on every request:
+
+```
+X-XSRF-TOKEN: nocheck
+Cookie: XSRF-TOKEN=nocheck
+User-Agent: wix-cli
+Content-Type: application/json   (on POST requests)
+```
+
+## Step 1 — Request a device code
+
+```
+GET /oauth2/device/code?clientId=CLIENT_ID
+```
+
+Response:
+
+```json
+{ "deviceCode": "…", "userCode": "XXXXXXXX", "verificationUri": "https://users.wix.com/login/device-login", "expiresIn": 600 }
+```
+
+## Step 2 — Ask the user to authorize
+
+Show the user this URL and code:
+
+```
+URL:  {verificationUri}?color=developer&studio=true
+Code: {userCode}
+```
+
+Make sure the user has copied or noted the code **before** opening the link — they'll need to enter it on the page. Present the URL as a clickable link that opens in a new tab if your interface supports it.
+
+## Step 3 — Poll for the token
+
+Every 3 seconds, POST:
+
+```
+POST /oauth2/token
+{ "clientId": "CLIENT_ID", "grantType": "urn:ietf:params:oauth:grant-type:device_code", "scope": "offline_access", "deviceCode": "{deviceCode}" }
+```
+
+- While waiting: server returns `400` with `{ "error": "authorization_pending" }` or `{ "message": "Device code is not yet verified" }` — keep polling.
+- On approval: `200` with `{ "access_token": "…", "refresh_token": "…", "expires_in": 14400 }`.
+- Stop polling after `expiresIn` seconds total.
+
+## Step 4 — Fetch user info
+
+```
+GET /_serverless/wix-cli-userinfo/userinfo
+Authorization: Bearer {access_token}
+```
+
+Response: `{ "userId": "…", "email": "…" }`
+
+## Step 5 — Persist
+
+At this point you already hold all the values in memory — store them securely to whatever credential store your platform provides (file, secrets manager, environment variables, etc.), without asking the user to enter them manually. **Treat these as secrets: never print them in the conversation, never include them in logs, and never send them to any service other than the Wix APIs.**
+
+```
+accessToken   string
+refreshToken  string
+expiresIn     number  (seconds)
+issuedAt      number  (Unix timestamp in seconds, recorded at the moment tokens were received)
+userInfo      { userId, email }
+```
+
+## Getting a valid token on subsequent calls
+
+**Account token**
+
+1. Load stored credentials. If missing → run the device flow above.
+2. Check validity: `issuedAt + expiresIn - 600 > now` (10-min buffer).
+3. If expired → refresh silently:
+
+```
+POST /oauth2/token
+{ "clientId": "CLIENT_ID", "grantType": "refresh_token", "refreshToken": "{refreshToken}" }
+```
+
+Same response shape as Step 3. Persist the new tokens with a fresh `issuedAt`.
+
+4. If refresh returns `400 invalid_grant` → session revoked; run the device flow again.
+
+**Site token**
+
+The account token returns `403` on site-level endpoints. Derive a site token on demand:
+
+```
+POST /oauth2/token
+{ "clientId": "CLIENT_ID", "grantType": "refresh_token", "refreshToken": "{refreshToken}", "siteId": "{siteId}" }
+```
+
+Response: `{ "access_token": "…", "refresh_token": "…", "expires_in": 900 }`
+
+Re-derive on each use rather than caching — it expires in 15 minutes.
+
+## Examples
+
+**List sites (account token)**
+
+```
+POST https://www.wixapis.com/site-list/v2/sites/query
+Authorization: Bearer {accountToken}
+{ "query": { "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } }, "cursorPaging": { "limit": 100 } } }
+```
+
+Returns `{ sites: [{ id, displayName, namespace, … }] }` — the `id` is the `siteId` for site-scoped calls.
+
+> Without the `namespace` filter, headless sites are silently excluded from results.
+
+**List contacts (site token)**
+
+```
+POST https://www.wixapis.com/contacts/v4/contacts/query
+Authorization: Bearer {siteToken}
+{ "query": { "paging": { "limit": 10 } } }
+```
+
+Returns `{ contacts: […] }`.
+
+---
+
+For the full Wix REST API reference — endpoints, request/response shapes, and field details — see [https://www.wix.com/skills/docs](https://www.wix.com/skills/docs).
+
+For REST API recipes covering common management operations (stores, bookings, contacts, CMS, and more) — see [https://www.wix.com/skills/manage](https://www.wix.com/skills/manage).

package/skills/wix-docs/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: wix-docs
+description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type }`) **or by browsing** the docs tree as a menu from the `llms.txt` root (append `.md` to any docs path), then read the page by appending `.md` to its URL; and (2) the Wix MCP doc tools when your agent has them. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
+---
+
+# Wix Docs — look up the Wix API/SDK documentation
+
+Get the **exact** truth about a Wix API — endpoint, HTTP method, request/response body, a field, an
+enum, or an error. **Never invent a Wix endpoint, path, body, or enum from memory** — confirm it
+here first.
+
+A lookup is a short flow: **find the right page, then read it.** Do it with `curl` (default, below)
+or the Wix MCP doc tools if your agent has them (Lane 2).
+
+## Lane 1 — `curl` (default)
+
+The docs are one tree of markdown pages: **append `.md` to any `https://dev.wix.com/docs/…` URL**
+to get that page as markdown. No SDK, no MCP.
+
+### 1. Find the page — search, browse, or query the index
+
+Three ways to reach the right page — use whichever fits.
+
+**A. Semantic search.** Describe what you want in natural language ("let a customer book an
+appointment"), not just keywords; hits come back ranked by relevance. Same `POST` body for both
+variants: `search_term` (required, 1–500), `document_type` (`REST` default · `SDK` · `WIX_HEADLESS` ·
+`BUSINESS_SOLUTIONS` · `VELO` · `WDS` · `BUILD_APPS` · `CLI`), `maximum_results` (1–20, def 15),
+`lines_in_each_result` (1–200, def 20). Two variants — pick by what you're doing:
+
+**`/docs/search/markdown` → read it (start here).** Returns JSON with a single `content` field
+holding one LLM-ready markdown string (extract it with `jq -r '.content'`) where each hit is a
+**condensed method doc**: the API **endpoint**, **real request code examples**, the **response
+shape**, and the **method description** (with its gotchas) — each truncated to `lines_in_each_result`
+with a "read more" link. For *"how do I call X?"* this is usually all you need in **one call** — hand
+it straight to the model; no page fetch, no schema dig.
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"search_term":"create a booking","document_type":"REST","maximum_results":3}' \
+  | jq -r '.content'      # no jq? → python3 -c 'import sys,json;print(json.load(sys.stdin)["content"])'
+```
+
+**`/docs/search` (JSON) → route on it.** Returns `{ results: [ { title, url, content,
+relevance_score, … } ] }` — structured hits. Use it when you want to **pick/route programmatically**:
+grab a hit's `url` to read that page (§2) or feed it to the schema query (§C). (Method hits carry a
+`url`; article hits keep their link inside `content`.)
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"search_term":"create a booking","document_type":"REST","maximum_results":5}' \
+  | jq -r '.results[] | select(.url) | "\(.title)\t\(.url)"'
+# no jq? → python3 -c 'import sys,json;[print(r["title"],r["url"]) for r in json.load(sys.stdin)["results"] if r.get("url")]'
+```
+
+**B. Browse the tree from the root, like a menu.** Every docs path has a `.md` twin, so you can
+navigate the docs as a menu tree — no search needed. `curl https://dev.wix.com/docs/llms.txt` is the
+top-level map; the portals under it:
+
+| Portal | Start here for |
+|---|---|
+| [`api-reference.md`](https://dev.wix.com/docs/api-reference.md) | **All backend / business-solution APIs — the main one.** Each page documents **both** its REST and SDK usage (`.md?apiView=SDK` for the SDK view). |
+| [`sdk.md`](https://dev.wix.com/docs/sdk.md) | **SDK-only surfaces not in the API reference:** client setup (`createClient`, `OAuthStrategy`), core modules (`@wix/sdk`, `@wix/essentials`), host modules (`dashboard`/`editor`/`site`), and frontend modules (`members`, `pay`, `seo`, `storage`, `pricing-plans`, …). |
+| [`go-headless.md`](https://dev.wix.com/docs/go-headless.md) | Headless setup, auth, hosting, framework integration. |
+| [`build-apps.md`](https://dev.wix.com/docs/build-apps.md) | Building Wix apps / extensions. |
+| [`wix-cli.md`](https://dev.wix.com/docs/wix-cli.md) · [`velo.md`](https://dev.wix.com/docs/velo.md) | Wix CLI commands; Velo site-coding APIs. |
+
+**Drill like a menu** — append `.md` to any path (a *section* → a menu of child links, a *leaf* →
+the content/method page); truncate to go up, extend to go down. **Read the sibling intro / "About …"
+/ flow articles too**, not just the method page. Example — drill to the create-booking method,
+grepping each menu for the next link:
+
+```bash
+curl -sS https://dev.wix.com/docs/api-reference/business-solutions.md            | grep -i bookings   # → .../bookings.md
+curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings.md   | grep -iE 'bookings|flow'  # → resource/flow pages
+curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings.md | grep -i create      # → the create method leaf
+curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md  # read it
+```
+
+A 2-level map of the API-reference portal (all verticals, one level down) is in
+`references/EXTRACTING.md`.
+
+**C. Query the API index — one call, structured.** The `code-mode` search endpoint runs a JS
+function over `lightIndex` (the whole REST API spec: every resource + method with `operationId`,
+`httpMethod`, `menuPath`, `docsUrl`, and executable `publicUrl`). Best when you want to
+**enumerate/filter methods programmatically** — browse a vertical, or grep across *all* methods —
+and get the `docsUrl` + `publicUrl` back in one shot, no menu-drilling:
+
+```bash
+# pinpoint a method by keyword across the whole index → its docsUrl + executable publicUrl
+curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
+  --data-raw '{"code":"async function(){ return lightIndex.flatMap(r=>r.methods).filter(m=>/createBooking$/i.test(m.operationId)).map(m=>({op:m.operationId, httpMethod:m.httpMethod, publicUrl:m.publicUrl, docsUrl:m.docsUrl})); }"}'
+```
+
+**Filter narrowly and return only the fields you need** — the index is large, so an unfiltered dump
+is huge. Scope: **REST API methods only** (not concept/guide articles, headless prose, or SDK-only
+surfaces — use A/B for those). More examples (browse a whole vertical, `menuPath` walk,
+whole-resource schema) and the `getResourceSchema` reader → **`references/API_SPEC_SEARCH.md`**.
+
+If the Wix MCP is present, it exposes these same capabilities as native tools (no `curl`/JSON
+boilerplate) — Lane 2.
+
+### 2. Read what you land on
+
+Appending `.md` to a URL gives one of **three kinds of page**. Know which you're looking at, and
+handle it accordingly:
+
+- **Menu page** — a *section* path (from browsing, §1B). A list of child links, often tens of KB —
+  **don't read it whole; `grep` it** for the child you want, then drill into that page:
+
+  ```bash
+  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings.md' | grep -i 'booking'
+  ```
+
+- **Article / guide** — introductions, concepts, sample-flow pages. Prose markdown, usually small —
+  **read it whole**:
+
+  ```bash
+  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/introduction.md'
+  ```
+
+- **Method page** — one API method, and the heavy one: it carries **both** a REST and a JavaScript
+  SDK section, the full request/response schema, and code examples — often 100 KB+. **Don't swallow
+  the whole page** — map it, then pull the part you need (the examples are usually enough to model a
+  call):
+
+  ```bash
+  curl -sS "$URL.md" | grep -nE '^#{1,3} '                                              # 1. map the outline
+  curl -sS "$URL.md" | awk '/^## REST API/{r=1} r&&/^### Examples/{f=1} /^## JavaScript SDK/{f=0} f'  # 2. just the REST examples
+  curl -sS "$URL.md" | grep -nE 'name: (selectedPaymentOption|totalParticipants)'       # 3. grep specific schema fields
+  ```
+
+  More recipes (split REST vs SDK, resolve an enum) → `references/EXTRACTING.md`.
+
+  For the exact **structured** schema and enum values, don't hand-slice the markdown — query the API
+  spec with a `curl` `POST` to `https://mcp.wix.com/api/code-mode/search` (the no-MCP equivalent of
+  the MCP `SearchWixAPISpec`). The `code` is a JS function with `lightIndex` and
+  `getResourceSchemaByUrl(docsUrl)` in scope; return only what you need:
+
+  ```bash
+  # find a method by keyword → its docsUrl + executable publicUrl
+  curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
+    --data-raw '{"code":"async function(){ return lightIndex.flatMap(r=>r.methods).filter(m=>/createBooking$/i.test(m.operationId)).map(m=>({op:m.operationId, httpMethod:m.httpMethod, publicUrl:m.publicUrl, docsUrl:m.docsUrl})); }"}'
+
+  # pull one method's request/response schema by its docsUrl (resolve $circular refs via s.components.schemas)
+  curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
+    --data-raw '{"code":"async function(){ const u=\"https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking\"; const s=await getResourceSchemaByUrl(u); const m=s.methods.find(x=>x.docsUrl===u); return { publicUrl:m.publicUrl, requestBody:m.requestBody, responses:m.responses }; }"}'
+  ```
+
+  Full example set (resource listing, partial-URL resolution, enum/nested-ref expansion) →
+  `references/API_SPEC_SEARCH.md`.
+
+## Lane 2 — Wix MCP doc tools (only if your agent has them)
+
+If the Wix MCP is connected, these are the **same backends as Lane 1** (the doc-search service and
+the API-spec index) wrapped as native tools — schema-validated, response-size handled, no
+`curl`/JSON boilerplate. A convenience over the curl lane, **not a richer data source**; use them
+when present, fall back to Lane 1 when not. Optional — skip this lane if the tools aren't present.
+
+| Tool | Use for |
+|---|---|
+| `SearchWixRESTDocumentation` | Find a REST method/recipe by keyword |
+| `SearchWixSDKDocumentation` | Find an SDK method (surfaces runtime functions a module menu hides) |
+| `SearchWixAPISpec` → `getResourceSchemaByUrl` | The **whole resource** — every method + shared object schema in one payload |
+| `ReadFullDocsArticle` | Read a recipe/flow/article page in full |
+| `BrowseWixRESTDocsMenu` | Walk the menu tree to drill to a method |
+
+- **Prefer the whole-resource view** (`getResourceSchemaByUrl`) over a single method page: a
+  requirement is often documented on a *sibling* method (e.g. a `memberId` required on
+  single-create but omitted from the bulk-create page). The resource view carries both.
+- **Look for the vertical's recipe/flow page first** — many verticals publish opinionated,
+  multi-step recipes under a `…/business-solutions/<vertical>/skills` node (search
+  `"<vertical> setup recipe"` or browse the menu). A recipe gives correct ordering,
+  cross-step gotchas, and the one bundled endpoint that does the whole job — which a
+  per-method schema won't flag.
+
+## The `.md` suffix
+
+Append `.md` only when `curl`-ing a page directly. The MCP tools and the search endpoint take the
+plain docs URL **without** `.md` — never feed a `.md` URL to an MCP tool.
+
+## Before you write the code
+
+Confirm on the page — not from memory — the endpoint, the HTTP verb, the request body shape,
+required fields, and any enum values. Then write the call. If you're extending a skill's shipped
+client, keep the skill's existing transport/helper style; you're adding one call, not
+re-architecting.

package/skills/wix-docs/references/API_SPEC_SEARCH.md

@@ -0,0 +1,213 @@
+# Structured API-spec search over `curl` (no MCP)
+
+A single `curl` endpoint that runs a JS query over the Wix REST API spec — the no-MCP equivalent of
+the MCP `SearchWixAPISpec` / `getResourceSchemaByUrl` tools. It does two jobs:
+
+- **Find / browse** — `lightIndex` is the whole API index (every resource + method with
+  `operationId`, `httpMethod`, `menuPath`, `docsUrl`, `publicUrl`). Filter or enumerate it to locate
+  methods programmatically — a third find-path alongside semantic search and `.md` browsing (`SKILL.md`).
+- **Read the schema** — `getResourceSchemaByUrl(docsUrl)` returns the **exact request/response shape,
+  field types, enums, and error codes** for a method (the markdown pages bury these in huge inline
+  schemas).
+
+> **Endpoint:** `POST https://mcp.wix.com/api/code-mode/search` — body `{ "code": "<async function() {…}>" }`.
+> The `code` is a JS `async function()` that runs in a read-only sandbox and returns any
+> JSON-serializable value. Response envelope: `{ "result": <return value> }` (or `{ "error": "<msg>" }`).
+
+> Internal/undocumented and pre-GA — treat it as best-effort; the contract could change. For
+> reading a single known page, the `.md` twin in `SKILL.md` is simpler — reach here when you
+> specifically need the **structured spec**.
+
+## How to call it
+
+Send the function as the JSON string `code`. Multi-line functions are easiest to send by encoding
+with a helper (keeps quotes/newlines valid):
+
+```bash
+read -r -d '' CODE <<'JS'
+async function() {
+  return lightIndex.filter(r => r.menuPath.includes("bookings")).map(r => r.name);
+}
+JS
+curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' \
+  -H 'Content-Type: application/json' \
+  --data "$(jq -n --arg code "$CODE" '{code:$code}')"     # or: python3 -c 'import json,sys;print(json.dumps({"code":sys.stdin.read()}))'
+```
+
+A short function can go inline: `--data-raw '{"code":"async function(){ return lightIndex.length; }"}'`.
+**Shape the result inside the function and return only what you need** — a whole resource schema is
+~200 KB+, so never `return await getResourceSchema(id)` wholesale.
+
+## Sandbox globals
+
+**`lightIndex`** — array of the REST API resources. Each entry:
+
+| Field | Meaning |
+|---|---|
+| `name` | Resource display name (e.g. `"Products V3"`, `"Bookings Writer V2"`) |
+| `resourceId` | Internal handle for `getResourceSchema()` |
+| `docsUrl` | Resource docs page |
+| `menuPath` | e.g. `["business-solutions","stores","catalog-v3","products-v3"]` |
+| `methods[]` | `{ operationId, summary, httpMethod, path, docsUrl, publicUrl, publicBaseUrl, description }` |
+
+**`getResourceSchemaByUrl(docsUrl)`** *(preferred when you have a URL)* and
+**`getResourceSchema(resourceId)`** — return the full resource schema:
+
+```
+{ title, description, fqdn, docsUrl,
+  methods: [ { summary, description, operationId, httpMethod, path, docsUrl,
+               publicUrl, publicBaseUrl, requestBody, responses, parameters,
+               permissions, queryMethodData, legacyExamples: [ { content: { title, request, response } } ] } ],
+  components: { schemas: { …every referenced type… } } }
+```
+
+**`articles`** — array of doc articles `{ name, resourceId, docsUrl, menuPath, description }`;
+**`getArticleContentByUrl(docsUrl)`** / **`getArticleContent(resourceId)`** — return an article's
+full markdown. Articles and resources share the same `menuPath` hierarchy.
+
+### Rules that matter
+
+- **Execute with `method.publicUrl`** — the complete `https://www.wixapis.com/...` URL. `method.path`
+  is a *partial* path (omits the gateway prefix like `/stores`) — never build a URL from it, and
+  never use `method.servers[0]` (internal hosts).
+- **Always return `responses` alongside `requestBody`** when inspecting a method — saves a re-run.
+- **`$circular` refs:** schemas reference types as `{ "$circular": "TypeName" }`, resolved via
+  `schema.components.schemas["TypeName"]`. Expand only the types you need (see the nested-refs
+  example); a full recursive expand can be huge.
+- **Filterable/sortable fields:** for query/search methods, `method.queryMethodData.queryFieldsCapabilitiesMap`
+  lists which fields accept filters (and their operators) and sorting. A field absent from the map
+  is rejected by the API — filter it client-side after fetching a bounded page.
+- `getResourceSchemaByUrl` resolves **API method/resource** URLs only — not `/skills/…` or article
+  pages (use `getArticleContentByUrl` for those). On a miss, search `lightIndex` by keyword instead
+  of retrying the URL.
+
+## Examples
+
+Each is an `async function()` — send it via the wrapper above.
+
+**Find APIs by broad keywords** (when you don't have a docs URL):
+
+```javascript
+async function() {
+  const words = ["stores", "query", "products"];
+  return lightIndex.flatMap(resource =>
+    resource.methods
+      .filter(method => {
+        const haystack = [
+          resource.name, resource.docsUrl, resource.menuPath.join("/"),
+          method.summary, method.operationId, method.description, method.path, method.docsUrl
+        ].join(" ").toLowerCase();
+        return words.every(word => haystack.includes(word));
+      })
+      .map(method => ({
+        title: method.summary, resource: resource.name,
+        httpMethod: method.httpMethod.toUpperCase(),
+        docsUrl: method.docsUrl, publicUrl: method.publicUrl
+      }))
+  );
+}
+```
+
+**Inspect one method by exact docs URL** (request + response + query capabilities + curl examples):
+
+```javascript
+async function() {
+  const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products";
+  const schema = await getResourceSchemaByUrl(methodUrl);
+  const method = schema.methods.find(m => m.docsUrl === methodUrl);
+  if (!method) {
+    return { message: "No exact method match", methods: schema.methods.map(m => ({ title: m.summary, docsUrl: m.docsUrl, httpMethod: m.httpMethod.toUpperCase(), publicUrl: m.publicUrl })) };
+  }
+  return {
+    title: method.summary,
+    publicUrl: method.publicUrl,
+    httpMethod: method.httpMethod.toUpperCase(),
+    operationId: method.operationId,
+    permissions: method.permissions,
+    parameters: method.parameters,
+    requestBody: method.requestBody,
+    responses: method.responses,
+    queryFieldsCapabilities: method.queryMethodData?.queryFieldsCapabilitiesMap,
+    curlExamples: method.legacyExamples?.map(e => e.content)
+  };
+}
+```
+
+**Inspect a whole resource by its docs URL** (list its methods):
+
+```javascript
+async function() {
+  const schema = await getResourceSchemaByUrl("https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3");
+  return {
+    resource: schema.title,
+    description: schema.description,
+    methods: schema.methods.map(m => ({ title: m.summary, httpMethod: m.httpMethod.toUpperCase(), docsUrl: m.docsUrl, publicUrl: m.publicUrl, operationId: m.operationId }))
+  };
+}
+```
+
+**Resolve one method from a partial docs URL** (when you only have a path fragment):
+
+```javascript
+async function() {
+  const partial = "stores/catalog-v3/products-v3/query-products";
+  const resource = lightIndex.find(r =>
+    r.docsUrl.includes(partial) || r.methods.some(m => m.docsUrl?.includes(partial)));
+  if (!resource) return "No API resource found for this partial URL";
+  const schema = await getResourceSchemaByUrl(resource.methods.find(m => m.docsUrl?.includes(partial))?.docsUrl ?? resource.docsUrl);
+  const method = schema.methods.find(m => m.docsUrl?.includes(partial));
+  return method
+    ? { title: method.summary, publicUrl: method.publicUrl, httpMethod: method.httpMethod.toUpperCase(), requestBody: method.requestBody, responses: method.responses }
+    : { message: "Resource found, no exact method", methods: schema.methods.map(m => m.docsUrl) };
+}
+```
+
+**Expand selected nested `$circular` types** (targeted — resolve only what you need):
+
+```javascript
+async function() {
+  const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products";
+  const schema = await getResourceSchemaByUrl(methodUrl);
+  const method = schema.methods.find(m => m.docsUrl === methodUrl);
+  return {
+    requestBody: method.requestBody,
+    selectedNestedTypes: {
+      product: schema.components.schemas["com.wix.stores.catalog.product.api.v3.Product"],
+      cursorPaging: schema.components.schemas["wix.stores.catalog.v3.upstream.wix.common.CursorPaging"]
+    }
+  };
+}
+```
+
+**Advanced — bounded recursive expansion** (only when top-level + selected refs aren't enough; keep
+depth small, schemas balloon fast):
+
+```javascript
+async function() {
+  const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products";
+  const schema = await getResourceSchemaByUrl(methodUrl);
+  const method = schema.methods.find(m => m.docsUrl === methodUrl);
+  function expand(value, depth = 0, seen = []) {
+    if (depth > 3) return value;
+    if (Array.isArray(value)) return value.map(v => expand(v, depth, seen));
+    if (!value || typeof value !== "object") return value;
+    if (value.$circular) {
+      const name = value.$circular;
+      if (seen.includes(name)) return { $ref: name, circular: true };
+      const target = schema.components?.schemas?.[name];
+      return target ? { $ref: name, schema: expand(target, depth + 1, seen.concat(name)) } : { $ref: name, missing: true };
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expand(v, depth, seen)]));
+  }
+  return { title: method.summary, publicUrl: method.publicUrl, requestBody: expand(method.requestBody), responses: expand(method.responses) };
+}
+```
+
+## When to use this vs. the other lanes
+
+- **Find by intent / read prose / a quick field** → `SKILL.md` (semantic doc-search, `.md` twin/browse).
+- **Enumerate or filter API methods** (browse a vertical, grep across all methods, get `publicUrl`s) → `lightIndex`, here.
+- **Exact structured schema, enums, error codes — and no MCP** → `getResourceSchema[ByUrl]`, here.
+- **You have the Wix MCP** → prefer `SearchWixAPISpec` → `getResourceSchemaByUrl` (same data, native tool).
+
+Always confirm the endpoint, HTTP verb, and body shape here before writing the call — never guess.

package/skills/wix-docs/references/EXTRACTING.md

@@ -0,0 +1,120 @@
+# Extracting what you need from big doc pages
+
+`SKILL.md`'s flow — find a page, then read it — covers the common case. This is the detail for the
+**two heavy pages** you hit along the way: big **menu** pages (when you navigate by hand) and big
+**method** pages (the actual API reference). The goal both times: pull only the part you need with
+`curl` + `grep`/`awk`, never swallow the whole page. No dependencies.
+
+## Menu pages — find the child link fast
+
+A menu page (a section path + `.md`) is a list of links to its children and can be tens of KB. Don't
+read it whole:
+
+- **Grep it** for the child you're after, then drill into that URL:
+
+  ```bash
+  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings.md' | grep -i 'booking'
+  ```
+
+- **Walk down** by extending the path and re-appending `.md` — e.g. the portal root
+  `https://dev.wix.com/docs/api-reference.md` → a vertical `…/business-solutions/bookings.md` → a
+  resource `…/bookings/bookings/bookings-writer-v2.md`.
+- **The whole tree at once:** `https://dev.wix.com/docs/llms.txt` is the grep-able index of every
+  page; `https://dev.wix.com/docs/llms-full.txt` is the full concatenated corpus (very large — grep,
+  don't read).
+
+### A partial map to orient from
+
+Paths under `https://dev.wix.com/docs/` — **append `.md` to any of them** to read that page.
+**This is a pruned map, not the full tree** — `…` marks where real children were left out; the
+deep leaves are cherry-picked to show how far it goes. Re-derive from the `.md` menus / `llms.txt`
+for anything not shown.
+
+```text
+dev.wix.com/docs/                                      ← append .md to any path below
+├── api-reference/                                     all backend APIs — REST + SDK on every page
+│   ├── business-solutions/                            vertical → app/version → resource → method
+│   │   ├── stores/
+│   │   │   └── catalog-v3/                            V3 catalog (introduction · e-commerce-integration · …)
+│   │   │       ├── products-v3/                       the products resource
+│   │   │       │   ├── query-products                 ← method page (leaf: schema + examples)
+│   │   │       │   ├── create-product-with-inventory  ← method (create + stock in one call)
+│   │   │       │   └── get-product · search-products · update-product · count-products · …
+│   │   │       └── inventory-items-v3/ · categories/ · customizations-v3/ · brands-v3/ · …
+│   │   ├── bookings/
+│   │   │   └── bookings/                              core resource group (nested under the vertical)
+│   │   │       ├── bookings-writer-v2/                writes
+│   │   │       │   └── create-booking                 ← method (leaf); + bulk-create-booking · …
+│   │   │       └── bookings-reader-v2/ · attendance/ · waitlist/ · …
+│   │   ├── e-commerce/                                cart, checkout, orders, discounts
+│   │   ├── cms/                                       Wix Data — data-items, collections
+│   │   └── blog/ · events/ · pricing-plans/ · restaurants/ · portfolio/ · gift-cards/ · coupons/ · donations/ · …
+│   ├── crm/                                           contacts, members, forms, inbox, loyalty
+│   ├── business-management/                           payments, invoices, SEO, site-properties, automations
+│   ├── app-management/                                install apps, OAuth, app-instance/installations
+│   ├── assets/                                        media, rich-content
+│   └── account-level/ · site/ · tools/ · articles/    domains/sites, site config, auth/query guides
+├── sdk/                                               SDK-only surfaces (not in api-reference)
+│   ├── articles/set-up-a-client                       createClient + OAuthStrategy setup
+│   ├── core-modules/
+│   │   ├── sdk/                                       @wix/sdk
+│   │   │   ├── wix-client · oauth-strategy · setup    client creation + auth strategies
+│   │   │   └── media · api-key-strategy · app-strategy · …
+│   │   └── essentials/ · realtime/ · web-methods/     elevate/host-bridge · realtime · web methods
+│   ├── host-modules/                                  dashboard · editor · site (build on Wix surfaces)
+│   └── frontend-modules/
+│       ├── members/                                  introduction · custom-fields · …
+│       └── pay/ · seo/ · storage/ · pricing-plans/ · location/ · …
+├── go-headless/                                       headless setup, auth, hosting, framework integration
+├── build-apps/                                        building Wix apps / extensions
+├── wix-cli/
+│   ├── guides/                                        project-structure · about-the-wix-cli · …
+│   └── command-reference/                             project-creation · project-commands · global-commands
+├── velo/ · develop-websites/                          Velo site-coding APIs + guides
+└── …                                                  (full portal list: curl llms.txt)
+```
+
+## Method pages — slice, don't swallow
+
+A method page is often **huge** (Create Booking's `.md` is ~144 KB / 900+ lines). It carries **both**
+a `## REST API` and a `## JavaScript SDK` section (~70 KB each), and each has its own `### Schema`
+(the bulk — 60 KB+ of inline, deeply-nested types) and a much smaller `### Examples`. Map it, then
+cut to the one piece you need.
+
+**1. Map first — outline only (cheap, ~18 lines):**
+
+```bash
+curl -sS "$URL.md" | grep -nE '^#{1,3} '
+# 26:## REST API   28:### Schema   329:### Examples   481:## JavaScript SDK   483:### Schema ...
+```
+
+**2. Keep only the API you use** — halves the page. (Better: search with `document_type: REST` *or*
+`SDK` so hits already point at the right half.)
+
+```bash
+curl -sS "$URL.md" | awk '/^## REST API/{f=1} /^## JavaScript SDK/{f=0} f'   # REST only
+curl -sS "$URL.md" | awk '/^## JavaScript SDK/{f=1} f'                       # SDK only
+```
+
+**3. Prefer Examples over Schema to model a call** — the examples block is small (~9 KB) and usually
+enough to copy a working request:
+
+```bash
+curl -sS "$URL.md" | awk '/^## REST API/{r=1} r&&/^### Examples/{f=1} /^## JavaScript SDK/{f=0} f'
+```
+
+**4. Drill into a giant Schema by field — don't read it whole.** Schema lines are one-per-field:
+`- name: <field> | type: <Type> | description: … | validation: …`. Grep the field(s) you care about
+(each appears once for the request, once for the response — you get both shape + rules):
+
+```bash
+curl -sS "$URL.md" | grep -nE 'name: (selectedPaymentOption|totalParticipants)'
+# resolve a referenced type's enum values by grepping the Type name, e.g.:  grep -nE 'SelectedPaymentOption'
+```
+
+**5. Cap the search response** — on `…/docs/search/markdown`, pass `maximum_results` (1–20) and
+`lines_in_each_result` (1–200) so each hit is truncated with a "Read more here: `<url>`" hint instead
+of dumping full pages.
+
+**For deep/nested schemas**, don't hand-slice markdown — query the structured spec instead
+(`references/API_SPEC_SEARCH.md`, or the Wix MCP `SearchWixAPISpec → getResourceSchemaByUrl`).