@wix/agent-skills 1.18.0 → 1.18.2

package/skills/wix-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 — a structured, typed, counted browse of the REST API reference (`POST /mcp-docs-search/v1/docs/menu/browse`), or the `.md` menu tree from the `llms.txt` root for any portal — 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."
+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 }`, incl. the SKILLS recipe corpus for multi-step workflows) **or by browsing** a docs portal as a menu — a structured, typed, counted browse of the REST, SDK, CLI, Build Apps, and Headless portals (`POST /mcp-docs-search/v1/docs/menu/browse`), or the `.md` menu tree from the `llms.txt` root for any surface — then read the page by appending `.md` to its URL; (2) the Wix MCP doc tools when present. 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
@@ -11,7 +11,17 @@ here first. That includes the example endpoints in this skill: they illustrate t
 go stale like any snapshot — discover the real contract before you rely on one.
 
 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).
+or the Wix MCP doc tools if your agent has them (Lane 2). Either way, route by what you already
+know:
+
+- **You have a docs URL** → just read it (§2). Don't re-search for a page you can already name.
+- **A multi-step workflow** ("take a booking from service setup to payment") → look for a **recipe**
+  first: semantic search with `document_type: "SKILLS"` (§1A). A recipe carries step ordering,
+  cross-step gotchas, and the one bundled endpoint that does the whole job — things no single
+  method page states. No relevant recipe → search the relevant API corpus and assemble the workflow
+  from verified per-method contracts.
+- **One specific operation, field, or enum** → search its API corpus (`REST` / `SDK`), then read or
+  schema-check what you land on.
 
 ## Lane 1 — `curl` (default)
 
@@ -24,16 +34,22 @@ 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:
+variants: `search_term` (required, 1–500), `document_type` (`REST` default · `SDK` · `SKILLS` ·
+`WIX_HEADLESS` · `BUSINESS_SOLUTIONS` · `VELO` · `WDS` · `BUILD_APPS` · `CLI` · `OVERVIEW`),
+`maximum_results` (1–20, def 15), `lines_in_each_result` (0–200, def 20; `0` = no per-hit line cap).
+`SKILLS` is the dedicated **recipe corpus** — multi-step workflow pages that a `REST` search does
+not return; `OVERVIEW` is platform orientation (which development approach, which API family). 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.
+shape**, and the **method description** (with its gotchas). Hits are **previews, not full pages**:
+the condensed format has fixed per-section limits, so raising `lines_in_each_result` does not expand
+every section, and `0` only removes the per-hit line cap — it never reproduces the whole source page.
+Before building on a hit, check sufficiency: do you have the required inputs, the conditions that
+apply to your case, and the REST contract or SDK signature you need? If yes, proceed — no extra
+fetch. If not, make **one targeted follow-up**: read the method page (§2) or pull its schema (§C).
 
 ```bash
 curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
@@ -42,6 +58,15 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdow
   | jq -r '.content'      # no jq? → python3 -c 'import sys,json;print(json.load(sys.stdin)["content"])'
 ```
 
+For a workflow, hit the recipe corpus first, then resolve each step's call in `REST`/`SDK`:
+
+```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":"end to end booking flow","document_type":"SKILLS","maximum_results":2}' \
+  | jq -r '.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
@@ -55,19 +80,37 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
 # 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 docs tree as a menu.** Two ways: the **structured browse endpoint** for the REST
-API reference (preferred there — typed, counted, filterable), and the **`.md` menu tree** for every
-portal and for reading pages.
-
-**B1. Structured browse — REST API reference (`api-reference`).** `POST
-/mcp-docs-search/v1/docs/menu/browse` walks the tree and returns each child with its **kind**, its
-**HTTP verb** (for methods), and **subtree counts** ("Catalog V3 — 121 methods, 32 articles"), so
-you pick the right area by shape — in ~2 KB, not a ~40 KB menu page you have to `grep`. `include`,
-`name_filter`, and `depth` jump straight to what you want. Body: `menu_url?` (absolute docs URL;
-omit for the portal root — the top-level verticals), `document_type?` (`REST`, default), `depth?`
-(1, max 6), `include?` (`CATEGORY`·`RESOURCE`·`METHOD`·`ARTICLE`·`WEBHOOK`·`OBJECT`·`SKILL`),
-`deprecated?` (`HIDE` default·`SHOW`·`ONLY`), `name_filter?`, `format?` (`MARKDOWN` default →
-`content` string; `STRUCTURED` → JSON tree with `url`/`http_method`/`resource_id`/`child_counts`).
+**B. Browse the docs tree as a menu.** Two ways: the **structured browse endpoint** for the
+supported portals (preferred there — typed, counted, filterable), and the **`.md` menu tree** for
+any surface and for reading pages.
+
+**B1. Structured browse — the supported portals.** `POST /mcp-docs-search/v1/docs/menu/browse`
+walks a portal's tree and returns each child with its **kind**, its **HTTP verb** (for methods), and
+**subtree counts** ("Catalog V3 — 121 methods, 32 articles"), so you pick the right area by shape —
+in ~2 KB, not a ~40 KB menu page you have to `grep`. `include`, `name_filter`, and `depth` jump
+straight to what you want.
+
+Portals (`document_type`): `REST` (default — the `api-reference` portal) · `FRONTEND_SDK` (`sdk`) ·
+`CLI` (`wix-cli`) · `BUILD_APPS` (`build-apps`) · `WIX_HEADLESS` (`go-headless`). In **browse only**,
+`SDK` is an alias for `REST` (the API reference documents both views on every page) — it does **not**
+select `FRONTEND_SDK`, and the alias doesn't apply to semantic search. To discover a portal's areas,
+omit `menu_url` — you get the portal root; passing a supported portal's URL as `menu_url` also infers
+the portal for you.
+
+Body: `menu_url?` (absolute docs URL; omit for the portal root), `document_type?`, `depth?` (1, max
+6), `include?` (`CATEGORY`·`RESOURCE`·`METHOD`·`ARTICLE`·`WEBHOOK`·`OBJECT`·`SKILL`), `deprecated?`
+(`HIDE` default·`SHOW`·`ONLY`), `name_filter?`, `max_nodes?`, `format?` (`MARKDOWN` default →
+`content` string; `STRUCTURED` → JSON tree with `url`/`http_method`/`resource_id`/`child_counts`,
+plus `counts_by_type`, `truncated`, `deprecated_counts_by_type`).
+
+Two response signals to act on, not ignore:
+
+- **`truncated: true`** — the node cap cut the listing. Narrow instead of re-reading: browse a
+  deeper `menu_url`, tighten `include`/`name_filter`, or lower `depth`.
+- **Deprecation filtering** — deprecated entries are **hidden by default**;
+  `deprecated_counts_by_type` reports how many were filtered out. An API missing from a browse may
+  be deprecated, not nonexistent — re-browse with `deprecated: "SHOW"` (or `"ONLY"`) to inspect it,
+  and follow its replacement pointer where one is documented.
 
 ```bash
 # a vertical's structure, with per-child subtree counts
@@ -81,14 +124,19 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
   -H 'Content-Type: application/json' \
   --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/bookings","include":["METHOD"],"name_filter":"cancel","depth":4}' \
   | jq -r '.content'
+
+# a non-REST portal: the CLI docs, from the portal root
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"document_type":"CLI","depth":2}' | jq -r '.content'
 ```
 
-REST (`api-reference`) only, and browse-only: it hands you the page **URL** — read it by appending
-`.md` (§2), and get the exact schema from §C.
+Browse-only: it hands you the page **URL** — read it by appending `.md` (§2), and get the exact
+schema from §C.
 
-**B2. `.md` menu tree — every portal, and how you read pages.** Every docs path has a `.md` twin, so
-you can navigate any portal with zero dependencies; use it for the **non-REST portals** (SDK, Velo,
-Headless, CLI) and to read leaves. `curl https://dev.wix.com/docs/llms.txt` is the
+**B2. `.md` menu tree — any surface, and how you read pages.** Every docs path has a `.md` twin, so
+you can navigate any surface with zero dependencies; use it for surfaces structured browse doesn't
+cover (e.g. Velo) and to read leaves. `curl https://dev.wix.com/docs/llms.txt` is the
 top-level map; the portals under it:
 
 | Portal | Start here for |
@@ -127,9 +175,13 @@ curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: ap
 ```
 
 **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`**.
+is huge. Scope: the **REST surface**. `lightIndex` indexes REST **methods**; a sibling `articles`
+index plus `getArticleContentByUrl(docsUrl)` / `getArticleContent(resourceId)` cover the REST
+portal's **prose** (introductions, recipes, flow pages). SDK-only surfaces and the other portals
+aren't here — use A/B for those, and note the schemas returned are REST contracts, not SDK
+signatures (the SDK view of the same method lives on its docs page, §2). More examples (browse a
+vertical, `menuPath` walk, resource schema) and the schema/article readers →
+**`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.
@@ -169,18 +221,30 @@ handle it accordingly:
   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:
+  `getResourceSchemaByUrl(docsUrl)` in scope; return only what you need.
+
+  `getResourceSchemaByUrl` scopes to the URL you pass: a **method URL** returns a schema whose
+  `methods` array holds just that method — read it as `methods[0]`, and don't select it by comparing
+  `m.docsUrl` to your input (the reader normalizes URLs). A **resource URL** (the method URL minus
+  its last segment) returns the **whole resource** — fetch that when you need sibling operations or
+  shared resource context.
 
   ```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)
+  # a METHOD URL → that one method's contract (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 }; }"}'
+    --data-raw '{"code":"async function(){ const s=await getResourceSchemaByUrl(\"https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking\"); const m=s.methods[0]; return { publicUrl:m.publicUrl, requestBody:m.requestBody, responses:m.responses }; }"}'
   ```
 
+  The envelope is `{ "result": … }` or `{ "error": "<message>" }` — **both arrive as HTTP 200**, so
+  check the body, not the status. The error text names the fix: an article URL → switch to
+  `getArticleContentByUrl`; an unknown URL → search `lightIndex` by keyword. Don't re-send an
+  identical failed lookup — change something based on the error, and if discovery still fails,
+  report the limitation instead of guessing the contract.
+
   Full example set (resource listing, partial-URL resolution, enum/nested-ref expansion) →
   `references/API_SPEC_SEARCH.md`.
 
@@ -195,18 +259,17 @@ when present, fall back to Lane 1 when not. Optional — skip this lane if the t
 |---|---|
 | `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 |
+| `SearchWixAPISpec` → `getResourceSchemaByUrl` | Structured schema — a **method URL** for that method's contract, a **resource URL** for the whole resource |
 | `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.
+- **Fetch the method for its contract; fetch the resource for context.** A method URL gives exactly
+  that method. When a requirement may live on a *sibling* method (e.g. a `memberId` required on
+  single-create but omitted from the bulk-create page), fetch the **resource** URL instead — the
+  resource view carries every method plus the shared object schema.
+- The **recipe-first routing** at the top of this skill applies here too: for a multi-step workflow,
+  search the recipe corpus (many verticals publish recipes under a
+  `…/business-solutions/<vertical>/skills` node) before assembling per-method calls.
 
 ## The `.md` suffix
 
@@ -215,76 +278,11 @@ plain docs URL **without** `.md` — never feed a `.md` URL to an MCP tool.
 
 ## From docs to calls
 
-The contract you just read runs under one of two identities — and which one a call wants is part
-of what you read:
-
-| identity | token | for |
-|---|---|---|
-| **admin** | an admin token (API key, connector, or OAuth-app admin grant) | managing the site — ad hoc calls, or the same fetch inside an app's backend function |
-| **visitor** | minted from the site's OAuth app, in frontend code | everything the site's end user does — storefront reads, cart, checkout |
-
-**Admin** — any management or read call, straight from its docs contract:
-
-```bash
-curl -sS -X POST 'https://www.wixapis.com/contacts/v5/contacts/query' \
-  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-  --data-raw '{"query": {"cursorPaging": {"limit": 10}}}'
-```
-
-In a Wix CLI project, the CLI mints `$ADMIN_TOKEN` — at either scope:
-
-```bash
-TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")   # site-scoped: this one site's APIs
-TOKEN=$(npx @wix/cli@latest token)                     # account-scoped: account-level APIs (list sites, …)
-```
-
-Mint once per run and cache it — within a run the CLI returns a byte-identical token, so re-minting
-only spends startup time.
-
-**Visitor — minted from the OAuth app's client id.** The client id is a public value, and it is
-usually already on disk before it is in any API: in a managed headless project it is the `appId`
-field of `wix.config.json` — **the OAuth app id and the client id are the same value** — so read it
-from the project's config instead of querying the OAuth-apps API for it. The mint is one
-unauthenticated call, so it belongs in the site's own frontend code:
-
-```bash
-curl -sS -X POST 'https://www.wixapis.com/oauth2/token' \
-  -H 'Content-Type: application/json' \
-  --data-raw '{"clientId": "<oauth app client id>", "grantType": "anonymous"}'
-# → { "access_token": "OauthNG.JWS.…", … } — bearer for products, cart, checkout
-```
-
-The cart and checkout APIs act on the *caller's* identity, so they want the visitor token — the
-admin token is for managing the site, the visitor token is for being on it.
-
-The authentication docs (append `.md` to read):
-
-- [`about-identities`](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) — the identity model
-- [`rest-api-authentication`](https://dev.wix.com/docs/api-reference/articles/authentication/rest-api-authentication) — headers, token kinds
-- [`retrieve-tokens`](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens) — the `/oauth2/token` contract, all grant types
-- [`about-authentication`](https://dev.wix.com/docs/go-headless/authentication/about-authentication) — visitor vs member sessions
-- [`create-an-oauth-app-for-visitors-and-members`](https://dev.wix.com/docs/go-headless/getting-started/setup/authentication/create-an-oauth-app-for-visitors-and-members) — where the client id comes from
-- [`set-up-a-headless-client`](https://dev.wix.com/docs/go-headless/authentication/setup/set-up-a-headless-client) — wiring the client
-
-## Special APIs worth knowing
-
-**Dynamic Site Context — "what IS this site?"** One admin call returns a markdown report of the
-whole site — installed apps, status, URL, locale, CMS collections — the same output the Wix MCP's
-site-context tool renders:
-
-```bash
-curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
-  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-  --data-raw '{"siteId": "<metasite id>"}' | jq -r '.markdown'
-```
-
-A `200` with `"markdown": ""` means the token or `siteId` is wrong — the endpoint reports an empty
-context instead of an auth error, so treat empty as "check auth", never as "empty site".
-
-For site management, the **`wix-manage`** skill carries per-area recipes. It may already be
-installed at
-`.agents/skills/wix-manage/`; install it with `npx -y skills add wix/skills/skills/wix-manage`,
-or read it straight off the registry: `https://www.wix.com/skills/wix-manage`.
+Understanding the contract is this skill's job; executing it needs an identity. Which identities a
+method accepts is part of what you read — check the method page's permissions and identity notes
+before calling, and confirm your token's site/account scope matches. Token minting (CLI admin
+tokens, visitor tokens), the identity model, and the dynamic site-context report →
+**`references/CALLING.md`**.
 
 ## Before you write the code
 

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

@@ -7,12 +7,14 @@ the MCP `SearchWixAPISpec` / `getResourceSchemaByUrl` tools. It does two jobs:
   `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).
+  field types, enums, and error codes** (the markdown pages bury these in huge inline schemas),
+  **scoped to what you pass**: a **method URL** → a schema holding just that method; a **resource
+  URL** (or `getResourceSchema(resourceId)`) → the whole resource, every method.
 
 > **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>" }`).
+> JSON-serializable value. Response envelope: `{ "result": <return value> }` or `{ "error": "<msg>" }` —
+> **both with HTTP 200**, so check the body for `error`, never just the status.
 
 > 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
@@ -51,7 +53,9 @@ A short function can go inline: `--data-raw '{"code":"async function(){ return l
 | `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:
+**`getResourceSchema(resourceId)`** — return the schema, **scoped to the input**: a method URL
+scopes `methods` to that one method (read it as `methods[0]`); a resource URL or `resourceId`
+returns every method. Shape:
 
 ```
 { title, description, fqdn, docsUrl,
@@ -61,9 +65,11 @@ A short function can go inline: `--data-raw '{"code":"async function(){ return l
   components: { schemas: { …every referenced type… } } }
 ```
 
-**`articles`** — array of doc articles `{ name, resourceId, docsUrl, menuPath, description }`;
+**`articles`** — array of the REST portal's **prose pages** (introductions, recipes, flow pages) as
+`{ name, resourceId, docsUrl, menuPath, description }`;
 **`getArticleContentByUrl(docsUrl)`** / **`getArticleContent(resourceId)`** — return an article's
-full markdown. Articles and resources share the same `menuPath` hierarchy.
+full markdown. This is the coverage `lightIndex` (methods only) doesn't have; articles and resources
+share the same `menuPath` hierarchy.
 
 ### Rules that matter
 
@@ -77,9 +83,15 @@ full markdown. Articles and resources share the same `menuPath` hierarchy.
 - **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.
+- **Never select a method by comparing `m.docsUrl` to the URL you passed in** — the reader
+  normalizes URLs (`.md`, query params, casing), so equality against your raw input can miss. On a
+  method-URL fetch the scoped result *is* the method: read `methods[0]`. Need siblings? Fetch the
+  resource URL.
 - `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.
+  pages (use `getArticleContentByUrl` for those). **Follow the error, don't retry it:** the `{error}`
+  message names the fix — an article URL points you to the article reader; an unknown URL means
+  search `lightIndex`/`articles` by keyword instead of re-sending the same lookup. If discovery
+  still fails, report the limitation — don't guess the contract.
 
 ## Examples
 
@@ -108,16 +120,15 @@ async function() {
 }
 ```
 
-**Inspect one method by exact docs URL** (request + response + query capabilities + curl examples):
+**Inspect one method by its docs URL** (request + response + query capabilities + curl examples).
+A method URL returns a schema scoped to that method — `methods[0]` is it; don't match on
+`m.docsUrl === methodUrl` (the reader normalizes URLs):
 
 ```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 })) };
-  }
+  const schema = await getResourceSchemaByUrl(methodUrl);   // scoped: one method
+  const method = schema.methods[0];
   return {
     title: method.summary,
     publicUrl: method.publicUrl,
@@ -133,11 +144,13 @@ async function() {
 }
 ```
 
-**Inspect a whole resource by its docs URL** (list its methods):
+**Inspect a whole resource by its docs URL** (the method URL minus its last segment) — use this when
+you need **sibling operations** or the shared object schema (a requirement is often documented on a
+sibling method, e.g. required on single-create but omitted from bulk-create):
 
 ```javascript
 async function() {
-  const schema = await getResourceSchemaByUrl("https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3");
+  const schema = await getResourceSchemaByUrl("https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3");  // resource URL → every method
   return {
     resource: schema.title,
     description: schema.description,
@@ -154,11 +167,10 @@ async function() {
   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) };
+  const methodDocsUrl = resource.methods.find(m => m.docsUrl?.includes(partial))?.docsUrl;
+  if (!methodDocsUrl) return { message: "Resource found, no matching method", methods: resource.methods.map(m => m.docsUrl) };
+  const method = (await getResourceSchemaByUrl(methodDocsUrl)).methods[0];  // canonical method URL → scoped
+  return { title: method.summary, publicUrl: method.publicUrl, httpMethod: method.httpMethod.toUpperCase(), requestBody: method.requestBody, responses: method.responses };
 }
 ```
 
@@ -168,7 +180,7 @@ async function() {
 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);
+  const method = schema.methods[0];   // method URL → scoped result
   return {
     requestBody: method.requestBody,
     selectedNestedTypes: {
@@ -186,7 +198,7 @@ depth small, schemas balloon fast):
 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);
+  const method = schema.methods[0];   // method URL → scoped result
   function expand(value, depth = 0, seen = []) {
     if (depth > 3) return value;
     if (Array.isArray(value)) return value.map(v => expand(v, depth, seen));

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

@@ -0,0 +1,91 @@
+# From docs to calls — identities, tokens, site context
+
+You've confirmed the contract (`SKILL.md`); this is the execution side: which identity the call
+runs under, how to mint its token, and how to see what a site actually has installed.
+
+## Which identity?
+
+Wix APIs run under several identities — Wix user (admin), app, site member, site visitor — and
+**each method documents which it accepts**: check the method page's permissions/identity notes
+rather than assuming. The identity model:
+[`about-identities`](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities)
+(append `.md` to read). The two tokens you mint most often:
+
+| token | minted from | typical use |
+|---|---|---|
+| **admin** | API key, connector, OAuth-app admin grant, or the Wix CLI | managing the site — ad hoc calls, or the same fetch inside an app's backend function |
+| **visitor** | the site's OAuth app client id, `anonymous` grant | anonymous end-user calls from the site's frontend — storefront reads, cart, checkout |
+
+A logged-in **member** is a third case: member calls use a member token (the same `/oauth2/token`
+endpoint, a member grant — see
+[`about-authentication`](https://dev.wix.com/docs/go-headless/authentication/about-authentication)),
+not the visitor token.
+
+## Admin token
+
+Any management or read call, straight from its docs contract:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/contacts/v5/contacts/query' \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
+  --data-raw '{"query": {"cursorPaging": {"limit": 10}}}'
+```
+
+In a Wix CLI project, the CLI mints `$ADMIN_TOKEN` — at either scope:
+
+```bash
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")   # site-scoped: this one site's APIs
+TOKEN=$(npx @wix/cli@latest token)                     # account-scoped: account-level APIs (list sites, …)
+```
+
+Mint once per run and cache it — within a run the CLI returns a byte-identical token, so re-minting
+only spends startup time.
+
+## Visitor token
+
+Minted from the OAuth app's **client id** — a public value, usually already on disk before it is in
+any API: in a managed headless project it is the `appId` field of `wix.config.json` (**the OAuth app
+id and the client id are the same value**), so read it from the project's config instead of querying
+the OAuth-apps API for it. The mint is one unauthenticated call, so it belongs in the site's own
+frontend code:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"clientId": "<oauth app client id>", "grantType": "anonymous"}'
+# → { "access_token": "OauthNG.JWS.…", … } — bearer for products, cart, checkout
+```
+
+The cart and checkout APIs act on the *caller's* identity, so an anonymous shopper's calls want the
+visitor token — the admin token is for managing the site, the visitor (or member) token is for
+being on it.
+
+## The authentication docs
+
+Append `.md` to read:
+
+- [`about-identities`](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) — the identity model
+- [`rest-api-authentication`](https://dev.wix.com/docs/api-reference/articles/authentication/rest-api-authentication) — headers, token kinds
+- [`retrieve-tokens`](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens) — the `/oauth2/token` contract, all grant types
+- [`about-authentication`](https://dev.wix.com/docs/go-headless/authentication/about-authentication) — visitor vs member sessions
+- [`create-an-oauth-app-for-visitors-and-members`](https://dev.wix.com/docs/go-headless/getting-started/setup/authentication/create-an-oauth-app-for-visitors-and-members) — where the client id comes from
+- [`set-up-a-headless-client`](https://dev.wix.com/docs/go-headless/authentication/setup/set-up-a-headless-client) — wiring the client
+
+## Dynamic Site Context — "what IS this site?"
+
+One admin call returns a markdown report of the whole site — installed apps, status, URL, locale,
+CMS collections — the same output the Wix MCP's site-context tool renders:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
+  --data-raw '{"siteId": "<metasite id>"}' | jq -r '.markdown'
+```
+
+A `200` with `"markdown": ""` means the token or `siteId` is wrong — the endpoint reports an empty
+context instead of an auth error, so treat empty as "check auth", never as "empty site".
+
+For site management, the **`wix-manage`** skill carries per-area recipes. It may already be
+installed at
+`.agents/skills/wix-manage/`; install it with `npx -y skills add wix/skills/skills/wix-manage`,
+or read it straight off the registry: `https://www.wix.com/skills/wix-manage`.

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

@@ -112,9 +112,11 @@ 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.
+**5. Size the search response** — on `…/docs/search/markdown`, `maximum_results` (1–20) caps the hit
+count and `lines_in_each_result` (0–200) caps lines per hit; `0` removes the per-hit line cap. Either
+way a hit is the **condensed format with fixed per-section limits — a preview, never the full page**:
+raising the line count does not expand every section. When a hit lacks a field or condition you need,
+follow its URL (or query the structured spec) instead of re-searching with bigger numbers.
 
 **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`).

package/skills/wix-headless/references/DOC_DISCOVERY.md

@@ -22,8 +22,12 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdow
   --data-raw '{"search_term":"<what you need, in natural language>","document_type":"WIX_HEADLESS","maximum_results":3}'
 ```
 
-`document_type`: `SDK` / `WIX_HEADLESS` for code-writing, `REST` / `BUSINESS_SOLUTIONS` for seeding
-(also `VELO` · `WDS` · `BUILD_APPS` · `CLI`). Drop `/markdown` for JSON hits.
+`document_type`: `SDK` / `WIX_HEADLESS` for code-writing, `REST` / `BUSINESS_SOLUTIONS` for seeding,
+and `SKILLS` for a **multi-step workflow no pinned recipe covers** — it searches the dedicated recipe
+corpus (step ordering, cross-step gotchas), which a `REST` search does not return (also `VELO` ·
+`WDS` · `BUILD_APPS` · `CLI` · `OVERVIEW`). Drop `/markdown` for JSON hits. Found a recipe → resolve
+its individual calls against `SDK`/`REST` docs; no recipe → assemble the flow from verified
+per-method contracts.
 
 **2. Read a page** — append `.md` to its docs URL. **For an SDK shape, append `.md?apiView=SDK`** —
 the SDK view shows `_id` (what the frontend calls), the bare view shows `id`.
@@ -32,6 +36,8 @@ the SDK view shows `_id` (what the frontend calls), the bare view shows `id`.
 with `getResourceSchemaByUrl(docsUrl)` (see `wix-docs`'s `API_SPEC_SEARCH.md`).
 
 **If the host has the Wix MCP**, its `SearchWix*` / `SearchWixAPISpec → getResourceSchemaByUrl`
-tools are richer (whole-resource schema in one payload) — prefer them, per `wix-docs` Lane 2.
+tools are the same backends without the `curl` boilerplate — prefer them when present, per `wix-docs`
+Lane 2. `getResourceSchemaByUrl` scopes to the URL: a method URL → that method's contract; a
+resource URL → the whole resource (fetch that for sibling operations).
 
 **A page that IS pinned → read it directly; don't re-search for it.**