@wix/agent-skills 1.18.0 → 1.18.2

package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md

@@ -1,11 +1,13 @@
 # CSS Guidelines
 
 Use these rules for the scaffolded `<component-name>.module.css` file and any
-colocated CSS Modules owned by internal sub-components. Keep existing visual
-decisions outside the request unchanged. These rules keep the component
+colocated CSS Modules owned by internal sub-components. These rules keep the component
 editable by zero config, responsive to its Wix-owned container, and safe in
 both LTR and RTL layouts.
 
+**Visual intent.** When the request specifies how the component should look —
+mood, palette, layout style, or a reference — follow that direction. Default to a modern, refined look — intentional layout, pleasing proportions, polished and deliberate styling.
+
 ## Contents
 
 - [Classes and Named Parts](#classes-and-named-parts)
@@ -210,20 +212,30 @@ and do not expose a visual prop solely for that purpose.
 
 ## Default Visual Quality
 
-When creating a component and the request has no visual direction, use a
-restrained accessible default. When editing an existing component, preserve its
-visual language unless the request changes it.
+Create a clear hierarchy with at least two techniques that fit the component:
+a defined surface, border or soft shadow, type scale or weight, spacing, an
+accent, or visible interaction states. Use these neutral defaults unless the
+request or existing design provides better values:
+
+- 16px or larger body text, 14px or larger labels, and 600–700 weight for titles
+- 8–16px spacing inside controls and 16–32px spacing inside containers
+- 8–12px corner radii for cards and controls; `50%` for circular media
+- a subtle border or soft shadow when a card, panel, or control needs separation
+- touch targets at least 44 by 44px and visible keyboard focus states
+
+### Foreground and Background Ownership
+
+If the component is a self-contained block (card, panel, banner, accordion item), give the root a background. If it is an inline control meant to blend in (link, ghost button, icon button), control may leave the root transparent instead.
+
+- On a transparent root, don't hardcode text or icon colors; inherit them from the parent.
+- Set the background and main text/icon color together on the same element. Any secondary text (captions, hints, icons) must still be readable against that same background.
+- If an interactive state changes the background, set the foreground color in that state too. Don't assume a color inherited from a parent or from a previous state will still look right on the new background.
+- In every default and interactive state, meet WCAG AA contrast: 4.5:1 for body text and 3:1 for large text and UI controls.
 
-- body text at least 16px and labels at least 14px, with an explicit `font-family`
-- WCAG AA contrast (4.5:1 body text, 3:1 large text and UI controls)
-- touch targets at least 44 by 44px
-- clear hierarchy and visible focus states
-- generous but consistent spacing
-- transparent root backgrounds unless the design requires a surface
+A neutral owned surface may use a light background with dark primary and
+secondary foregrounds, plus one accessible accent. The exact colors are not a
+contract; the contrast relationship is.
 
-Avoid prescribing a brand palette in a generic component. Only when the prompt
-explicitly requests branded or themed output, use its named brand tokens rather
-than hardcoded generic color choices.
 
 ## Checklist
 
@@ -239,3 +251,6 @@ than hardcoded generic color choices.
 - [ ] Every part that sets `font-size` also sets `font-family`, on the part that
       should own the typography control.
 - [ ] Interactive elements expose pointer events and accessible design states.
+- [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
+- [ ] Every explicit foreground has a known contrasting background; transparent
+      components inherit foregrounds from their host.

package/skills/wix-base44-connector/SKILL.md

@@ -18,36 +18,54 @@ does not inherit an earlier turn's context, so re-read it before building on or
 **A management or admin task starts at the recipes**: call `wx.mgmtRecipes` (Learn Wix) and follow
 the one that fits. A recipe states outright what an API does not support, which fields a bulk call
 actually writes, and the order two calls have to go in — from the schemas alone those get re-derived
-several errors at a time. A REST search ranks the matching recipes too (`recipes` in its return), so
+several errors at a time. `wx.search` ranks the matching recipes too (recipe entries in `hits`), so
 they also surface from a search that began at the methods.
 
+In this skill:
+
+- **What are you building?** — route each feature to its identity: visitor token, admin token
+  in a backend function, or admin ad hoc in exec_tool
+- **The helpers** — the `wx.*` loader every exec opens with
+- **Gather context** — `wx.context`, the report of what the site actually has
+- **Learn Wix** — find the APIs, learn their contracts
+  - **Management recipes** — first stop for an admin task (`wx.mgmtRecipes`)
+  - **Search and browse** — `wx.search` across methods, recipes and articles
+  - **Read a doc page** — `wx.page` for a located doc URL
+  - **The spec index** — `wx.spec`, a located method's exact schema
+- **Write the code**
+  - **Admin ops while building** — you, in exec_tool
+  - **Backend functions** — the app, as the owner
+  - **Visitor authentication and Wix-hosted flows** — the visitor client, redirect sessions,
+    the headless OAuth app — and bootstrapping a whole vertical with `wix-vibe-headless`
+
 ## What are you building?
 
-The app's audience picks the token, and the token picks the architecture: the **visitor token is
-public** — anyone can mint it from the site's `clientId` — and the **admin token is a secret**,
-the connector's, server-side only.
+Choose the token by who the code acts for. A headless app can serve visitors, provide admin
+management tools, or do both.
+
+**A site for visitors** — use a visitor token for public reads and actions on behalf of the
+visitor, never the admin connector token. Call Wix directly from the browser through one shared
+visitor client (Write the code, below). Redirect sessions for Wix-hosted flows also require a
+visitor token minted for the headless OAuth app; see Visitor authentication and Wix-hosted flows below.
+Anyone can mint an anonymous visitor token from the
+OAuth app's public `clientId`; no visitor login is required. APIs for the "current visitor"
+use that token to identify whose data and state to access. This applies both to a standalone
+headless frontend and to a frontend extending an existing Wix site.
+
+**An admin tool for the owner** — use the admin connector token in backend functions implementing
+admin logic; keep it secret and server-side. The frontend calls those functions, not Wix with
+visitor tokens. A custom headless management site extending the Wix back office follows this
+flow too. Ad hoc management calls in `exec_tool` also use the admin token. Backend functions
+also handle work requiring the owner's permissions, such as webhooks, scheduled jobs, and
+explicitly authorized elevated operations. For an app with both visitor and admin features,
+keep each feature on its corresponding flow.
 
 ```
-browser            ──(visitor token)─► wixapis.com   the visitor's own reads & actions
-base44/functions/… ──(admin token)───► wixapis.com   work that needs the owner's identity
-exec_tool          ──(admin token)───► wixapis.com   you: ad hoc probing/managing while building
+visitor pages ──(visitor token)────────────────────────► wixapis.com
+admin pages   ──► base44/functions/… ──(admin token)────► wixapis.com
+exec_tool     ──(admin token, ad hoc management)────────► wixapis.com
 ```
 
-**A site for visitors** — store, blog, booking, ecom, CMS, CRM, and the rest of the business solutions.
-Your app is the site's frontend — whether the site is headless (no pages of its own) or your
-frontend extends an existing site. **The complete visitor experience —
-every page, every read, every action a visitor takes — is browser calls on the visitor token;
-none of it needs a backend function.** Public reads
-included (the visitor token queries public content directly), and per-visitor state is scoped to
-the CALLER — an API that acts on "the current visitor's" data resolves the visitor from the
-token, so only the visitor token reaches that visitor's own state. One shared visitor client
-carries it all (Write the code, below). `base44/functions/…` appear only where work
-needs the owner's identity — elevated-permission ops a visitor triggers, webhooks, scheduled
-jobs — and for the app's non-Wix backend.
-
-**An admin tool for the owner** — dashboard, back office. Admin pages and agent act as the
-owner, using the secret admin token: `pages → base44/functions/… ──(admin token)──► wixapis.com`.
-
 ## The helpers
 
 Research and probing run in exec_tool, and one loader opens every exec (execs share no state —
@@ -55,26 +73,29 @@ reload each round; the module lives on disk next to this file, network only as f
 fallback):
 
 ```js
-const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.cjs";
 if (!fs.existsSync(P)) { fs.mkdirSync(".agents/skills/wix-base44-connector", { recursive: true });
-  fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.js")).text()); }
-const wx = (() => { const m = { exports: {} };
-  new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
+  fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.cjs")).text()); }
+const wx = require(require("path").resolve(P));
 ```
 
 `wx` exports these helpers:
 
 - `wx.post/get/patch/put/del(url, [body], token?)` — JSON transports, one per verb (`get`/`del` take no body): Bearer from `token`, non-2xx **throws** the API's own error
 - `wx.clip(value)` — cap a return value: oversized → `{ truncated, total, head }`; renders `undefined` as `null` so absence stays visible
-- `wx.context(token, section?)` — the site's dynamic context report; no section → its outline
+- `wx.context(token)` — the site's full dynamic context report; inline when small, otherwise a saved Markdown file with a heading outline
 - `wx.browse(menuUrl, { include, filter, depth })` — walk a docs-portal menu deterministically
-- `wx.search(term, { type, max, lines })` — ranked docs search; hits carry endpoint (`VERB url`) + docsUrl + gist, and the worked requests the docs publish for them. A REST search also ranks the **management recipes**, returned as their own `recipes` list ahead of the methods — each with its steps, the endpoints it calls, and `file` when the wix-manage skill is on disk
+- `wx.search(term, { type, max, lines })` — ranked REST docs, Headless articles, and management recipes in one `hits` list; see the response type under Search and browse. Only method hits carry an endpoint.
 - `wx.page(docsUrl)` — read a doc page; its worked examples come back as titles + line numbers
 - `wx.bash(cmd)` — shell over saved files (GNU grep/sed; awk is mawk; no rg)
 - `wx.spec(docsUrl | code)` — a method's exact schema, plus the titles of the docs' own request examples saved at `examplesPath`; pass a hit's docsUrl (direct load), or raw code to query the index yourself
 - `wx.mgmtRecipes(q?)` — management-recipe index; no arg → categories, a word → matching recipes
 - `wx.installApp(appDefId, siteId, token)` — install a Wix app on the site (Apps Installer). If discovery finds an API whose app isn't installed on the site, install it first — that's a one-call prerequisite, **not** a reason to fall back to a hand-built alternative. `appDefId` from `search` or the Apps-Created-by-Wix table; `siteId` from `context` (the site report)
 
+Search makes one combined request across REST, management recipes, and Headless by default.
+The service ranks them together and interleaves methods and articles; the helper preserves that
+order. `max` limits the combined result count (default 15).
+
 Every helper answers inline when the result fits (≤ 4,000 chars — exec results clip at ~5,000).
 A bigger result is saved under `.agents/skills/wix-base44-connector/tmp/` and comes back as
 `{ path, bytes, lines, outline }` — the outline is your map into the file. Work a saved file in
@@ -86,13 +107,16 @@ two moves: find with `wx.bash("grep -n 'term' <path> | head -40")` (or across ev
 
 ```js
 const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
-return await wx.context(accessToken, "Apps");   // no section arg → the report's outline
+return await wx.context(accessToken);
 ```
 
 One report: installed apps **with ids** (incl. Stores' catalog version — V1 vs V3 decides its
 endpoints), the OAuth app id (**also the visitor `clientId`**), locale, currency, CMS collections.
 An empty report = bad token, never an empty site.
 
+Reports over 4,000 characters are saved in full to a temporary Markdown file. The result includes
+its path, byte and line counts, and a heading outline. Read that file to inspect the site context.
+
 ## Learn Wix — find the APIs, learn their contracts
 
 ### Management recipes — first stop for an admin task
@@ -107,14 +131,36 @@ await wx.mgmtRecipes("stores");   // a category's list — or any task word: wx.
 // straight off disk — else `url`: wx.page(url), whole when small, saved + outline when big
 ```
 
-A recipe carries prerequisites, order, and gotchas that no method page has. A REST search ranks
-these same recipes as its own `recipes` list, so they surface either way.
+A recipe carries prerequisites, order, and gotchas that no method page has. `wx.search` ranks
+these same recipes in its `hits` list, so they surface either way.
+
+### Search and browse
+
+`wx.search` returns a saved-file reference and ranked hits. Each hit is a method,
+article, or recipe, identified by its title field; only methods have an endpoint.
+
+```ts
+type Section = { title: string; line: number }; // 1-based line in the saved file
+type SearchResult = {
+  path: string; bytes: number; lines: number; note?: string;
+  hits: ({ docsUrl: string } & (
+    | { method: string; endpoint: string | null; gist?: string; examples?: Section[] }
+    | { article: string | null; line: number; outline?: Section[] }
+    | { recipe: string | null; line: number; lines: number;
+        file?: string; steps?: string[]; calls?: string[] }
+  ))[];
+};
+```
 
-### Find a method — search and browse
+The file at `path` keeps the full returned Markdown, while optional details and excess
+hits may be omitted from the inline response. Null titles or endpoints were not parsed.
+If no result blocks parse, `head` and `note` replace `hits`; the final size-limit fallback
+is `{ truncated: true, total: number, head: string }` instead of the object above.
 
 ```js
 // name the method? search finds it in one call:
-await wx.search("stores v3 update product");   // → [{ method, endpoint: "VERB url", docsUrl, gist }]; call wx.<verb>(url, body, token); spec(docsUrl) for the full schema
+const result = await wx.search("stores v3 update product"); // SearchResult above
+// Keep all hit kinds; only a method hit has an endpoint to call and a schema for wx.spec.
 // exploring an unfamiliar product? browse is deterministic — menuUrl alone orients (children + counts);
 // filter before listing methods. browse works for both portals this skill uses — REST
 // (api-reference) and WIX_HEADLESS (go-headless) — just pass that portal's menu URL.
@@ -125,12 +171,7 @@ await wx.browse("https://dev.wix.com/docs/go-headless/authentication", { depth:
 
 // don't know where it lives? search ranks, never says "no match" — drop wrong-product hits
 await wx.search("pause a pricing plan subscription and resume it");
-// → { hits: [{ method, endpoint /* callable */, docsUrl, gist }] } — hits often ARE the answer
-
-// { type } picks the portal (default "REST" — the HTTP APIs this skill calls). Same query,
-// other corpus — search WIX_HEADLESS for headless/external client code (visitor auth,
-// JS SDK, quick-starts). It returns article-style hits (method gists thin out) — read the saved path.
-await wx.search("mint a visitor token and read the current cart", { type: "WIX_HEADLESS" });
+// Same SearchResult: methods, articles, and recipes remain in ranked order.
 ```
 
 Products and their capabilities — the common ones, partial lists:
@@ -250,7 +291,7 @@ return (await res.json()).contacts;
 - One file per business area, not per call — each file is its own deploy, and deploys cost time.
 - Call every function you deploy and fix what breaks. Deploying is not testing.
 
-### A visitor client — src/lib/wixClient.js
+### Visitor authentication and Wix-hosted flows
 
 The "site for visitors" shape (What are you building?), in code — one file pages import. Neither
 `clientId` (from the context report) nor the minted token is a secret; together they are "an
@@ -270,22 +311,101 @@ export const wix = (path, opts = {}) => fetch("https://www.wixapis.com" + path,
   headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
 ```
 
-Token contract: `…/headless/authentication/retrieve-tokens`. Prove the lane in one exec before
-writing pages — mint a visitor, make one public read with it:
+If you need to test a visitor API, including redirect sessions, you can do so in `exec_tool`. Mint a visitor
+token and pass it to the API call so the test uses the same identity as the visitor frontend.
+Token contract: [Retrieve Tokens](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens.md).
+For example, test a public read:
 
 ```js
-const { access_token } = await wx.post("https://www.wixapis.com/oauth2/token",
+const { access_token: visitorToken } = await wx.post("https://www.wixapis.com/oauth2/token",
   { clientId: WIX_CLIENT_ID, grantType: "anonymous" });   // clientId: from the context report
-return await wx.post("<a public read from Learn Wix>", { query: {} }, access_token);
+return await wx.post("<a public read from Learn Wix>", { query: {} }, visitorToken);
 // 200 ⇒ every visitor-facing page in the app is this same call, no server between
 // a lean default response isn't the whole shape — contracts often define a fields param
 // that opts INTO heavier parts (formatted prices, media); read the contract for it
 ```
 
-No OAuth app in the context report to take the `clientId` from? Create one (admin, one-time) —
-the returned `id` IS the `clientId`:
+**Any Wix-hosted flow that returns the visitor to your app needs the headless OAuth app's
+redirect config set.** This covers redirect sessions *and* sending a buyer to the Wix-hosted
+checkout `checkoutUrl` and back — any flow where Wix redirects to a URL on your app. Use the
+OAuth app's `clientId` from `wx.context()`; if the report has no OAuth app, create one with the
+admin connector token as shown below, then mint a visitor token from its `clientId` (anonymous
+visitors do not need to log in). **Always set `allowedRedirectUris` and `allowedRedirectDomains`
+when you create it** — an OAuth app created with a name only cannot complete any return, and the
+break is silent (create-checkout and the anonymous token still succeed) until a real buyer is
+redirected and stranded on Wix.
+
+```js
+// Register BOTH of this app's own URLs — its preview URL and its published URL — so returns work
+// before AND after publish. Both are built from the Base44 app id (NOT the Wix OAuth client_id /
+// appId used above):
+//   preview:   https://preview-sandbox--<base44-app-id>.base44.app
+//   published: https://<app-name-slug>-<last 8 of the base44-app-id>.base44.app
+//              where <app-name-slug> is the app's name (the brand name) slugified — e.g.
+//              "Flash Sale Spark" -> flash-sale-spark-a4615088.base44.app.
+// A custom domain the owner connects overrides the published one; the app name (hence the slug)
+// can also change. So prefer the app's real current published URL when you have it, and update
+// this same OAuth app whenever the name or domain changes — never create another.
+const appOrigins = [previewUrl, publishedUrl]; // this app's actual preview + published URLs
+const loginCallbacks = appOrigins.map(origin => new URL("/login-callback", origin).href);
+const returnDomains = appOrigins.map(origin => new URL(origin).hostname);
+
+// OAuth redirect configuration: exact login URLs versus domains for other returns.
+// https://dev.wix.com/docs/go-headless/authentication/setup/allow-redirect-uris-and-domains.md
+const { accessToken: adminToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const { oAuthApp } = await wx.post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
+  oAuthApp: {
+    name: "My App",
+    // Login callbacks: the authorization request's redirect URI must match exactly.
+    allowedRedirectUris: loginCallbacks,
+    // Returns from Wix-hosted flows: hostnames only, allowing URLs under each domain.
+    allowedRedirectDomains: returnDomains,
+  },
+}, adminToken);
+const clientId = oAuthApp.id; // Public visitor client ID, used by the frontend client above.
+
+// If destinations change later, update this OAuth app rather than creating another.
+// Read its existing lists and merge new entries before updating, preserving old entries.
+// https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app.md
+
+```
+
+Frontend redirect example, using the visitor client above after obtaining a visitor token:
 
 ```js
-const { oAuthApp } = await wx.post("https://www.wixapis.com/oauth-app/v1/oauth-apps",
-  { oAuthApp: { name: "My App" } }, accessToken);   // oAuthApp.id is the visitor clientId
+import { wix } from "@/lib/wixClient";
+
+// Flow prerequisites and supported intents:
+// https://dev.wix.com/docs/go-headless/business-solutions/wix-hosted-pages/redirect-using-the-rest-api.md
+export async function redirectToWix(intent, returnPath = "/") {
+  // wix sends the minted visitor token. Never use the admin token here.
+  // Admin tokens are for ad hoc management calls or backend functions implementing admin logic.
+  // Pass the intent required by the selected flow's schema.
+  const response = await wix("/headless/v1/redirect-session", {
+    method: "POST",
+    body: JSON.stringify({
+      ...intent,
+      callbacks: {
+        postFlowUrl: new URL(returnPath, window.location.origin).href,
+      },
+    }),
+  });
+  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
+  const { redirectSession } = await response.json();
+  window.location.assign(redirectSession.fullUrl);
+}
 ```
+
+**Building a whole vertical? Bootstrap it with `wix-vibe-headless`.** When the build is a
+visitor-facing site on a Wix vertical it supports — a storefront, bookings, pricing plans,
+events, restaurants, rentals, a blog and more — the `wix-vibe-headless` skill stands the
+vertical up fast: it is built entirely on the same Wix APIs as this skill, but ships working
+code (REST transport, scaffolds, UI) plus management-API abstractions (seeding,
+configuration), so the vertical bootstraps on Base44 in a fraction of the calls.
+Read the entry point at
+[`www.wix.com/skills/wix-vibe-headless/platforms/base44.md`](https://www.wix.com/skills/wix-vibe-headless/platforms/base44.md).
+Its STEP 1 carries the install itself — the verbatim `npx skills add` call to run through
+exec_tool, the companion skills, the vertical table and the scaffold deploy — after which the
+guide lives at `.agents/skills/wix-vibe-headless/platforms/base44.md`. Reading it as
+reference alone is fine, but when you do install, go through its flow end to end — the
+shipped scaffolds and seed path are most of its value.

package/skills/wix-base44-connector/scripts/{utils.js → utils.cjs}

@@ -3,17 +3,16 @@
 // back as { path, bytes, lines, outline } with the read tools pre-pointed at it.
 //
 // Load per exec (execs share no state) — from disk, network only as first-touch fallback:
-//   const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+//   const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.cjs";
 //   if (!fs.existsSync(P)) { fs.mkdirSync(".agents/skills/wix-base44-connector", { recursive: true });
-//     fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.js")).text()); }
-//   const wx = (() => { const m = { exports: {} };
-//     new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
+//     fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.cjs")).text()); }
+//   const wx = require(require("path").resolve(P));
 //
 // Read a saved file the way you already know how: wx.bash("grep -n 'term' <path> | head -40")
 // to find, read_file(<path>) with offset/limit to window (numbered lines, 45K cap — no exec
 // round needed), pipelines for the rest (GNU grep/sed; awk is mawk; no rg).
 //
-// API responses are site data and never saved — post() projects them to facts.
+// API transports return data directly; oversized context reports are saved for reading.
 
 const fs = require("fs");
 const path = require("path");
@@ -40,9 +39,12 @@ async function req(method, url, body, token) {
     headers: { "Content-Type": "application/json", ...(token && { Authorization: `Bearer ${token}` }) } });
   if (!r.ok) {
     const head = (await r.text()).slice(0, 300);
-    throw new Error(r.status + " " + head + (r.status < 500
-      ? " — a 4xx means wrong body or reference: read this endpoint's contract before changing the call"
-      : ""));
+    const guidance = r.status === 401 || r.status === 403
+      ? " — check the endpoint's required caller identity, token validity, and permissions"
+      : r.status >= 400 && r.status < 500
+        ? " — read the API error and endpoint contract before changing the call"
+        : "";
+    throw new Error(r.status + " " + head + guidance);
   }
   return r.json();
 }
@@ -87,19 +89,14 @@ async function resolveRef(ref) {
 
 // ── gather context ────────────────────────────────────────────────────────────
 
-// The dynamic context report — site data, never saved. No section → the whole report
-// when it fits, else its header outline; with one → that section's text. Empty
-// report = bad token, never an empty site.
-async function context(token, section) {
+// Return the full dynamic context report inline when it fits. Larger reports use the
+// same saved-file and heading-outline format as documentation pages.
+async function context(token) {
   const { markdown } = await post(
     "https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown", {}, token);
-  if (!section) {
-    if (markdown.length <= BUDGET) return markdown;   // most sites: the whole report, one round
-    return { truncated: true, total: markdown.length, head: markdown.slice(0, BUDGET),
-             note: "site data — never saved (no path); narrow: wx.context(token, '<section name>')" };
-  }
-  const m = markdown.match(new RegExp("^#{1,3} .*" + section + "[\\s\\S]*?(?=\\n#{1,3} |$)", "im"));
-  return clip({ total: markdown.length, section: m ? m[0] : "not found — call context(token) for the outline" });
+  if (markdown.length <= BUDGET) return markdown;
+  const saved = save("site-context-" + require("crypto").randomUUID() + ".md", markdown);
+  return { ...saved, ...outlineOf(markdown.split("\n")) };
 }
 
 // The wix-manage skill, when it is installed in the sandbox, is these same recipes on disk —
@@ -153,28 +150,22 @@ async function browse(menuUrl, { include, filter, depth } = {}) {
 // Semantic search — ranks, never says "no match". The reduced hits come back inline AND the full
 // raw content is saved for grep/window follow-ups. { type } picks the corpus, one per request:
 // REST (default) · SKILLS · WIX_HEADLESS · SDK · VELO · CLI · WDS · BUILD_APPS · OVERVIEW ·
-// BUSINESS_SOLUTIONS. A REST search also runs SKILLS — the management recipes rank as their own
-// hits, ahead of the methods, and land in the saved file whole. Each method hit lists the worked
+// BUSINESS_SOLUTIONS. A REST search also runs SKILLS and WIX_HEADLESS — the management recipes appear as recipe hits
+// alongside methods and articles, and land in the saved file whole. Each method hit lists the worked
 // requests the docs publish for it; every line number reads with read_file(path, offset: <line>).
-async function search(term, { type = "REST", max = 5, lines = 0, recipes = type === "REST" } = {}) {
-  const ask = (document_type, maximum_results) =>
-    post("https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
-      // lines_in_each_result 0 skips the server's per-section budget, which otherwise cuts every
-      // code example after the first 30 lines and the rest after 5, and every recipe at 20 —
-      // the saved file would carry stubs instead of the requests and flows the hits point at
-      { search_term: term, document_type, maximum_results, lines_in_each_result: lines });
-  const [main, skills] = await Promise.all([ask(type, max),
-    recipes ? ask("SKILLS", 3).catch(() => null) : null]);   // a recipe corpus miss must not fail the search
-  const recipeText = skills?.content ? skills.content.trimEnd() + "\n" : "";
-  const content = recipeText + main.content;
+async function search(term, { type = "REST", max = 15, lines = 0, recipes = type === "REST", headless = type === "REST" } = {}) {
+  const document_types = [...new Set([type, ...(recipes ? ["SKILLS"] : []), ...(headless ? ["WIX_HEADLESS"] : [])])];
+  // Keep full documentation in the saved file; compact only the inline index.
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
+    { search_term: term, document_types, maximum_results: max, lines_in_each_result: lines });
   const nl = [];   // newline offsets — a match's char offset becomes its line in the saved file
   for (let i = content.indexOf("\n"); i >= 0; i = content.indexOf("\n", i + 1)) nl.push(i);
   const lineAt = (off) => { let lo = 0, hi = nl.length; while (lo < hi) { const m = (lo + hi) >> 1; nl[m] < off ? lo = m + 1 : hi = m; } return lo + 1; };
   // recipes are articles — no "# Method:" header, no code-example delimiters, and no fixed body
   // shape. Two things every one of them has: headings, and the endpoints it calls. Those are the
   // outline — enough to tell whether this is the recipe for the task without reading 400 lines.
-  const recipeHits = !recipeText ? [] : recipeText.split(/\n---\n+(?=#### )/).map(b => {
-    const at = content.indexOf(b), rows = b.split("\n");
+  const parseRecipe = (b, at) => {
+    const rows = b.split("\n");
     const steps = [], calls = [];
     let verb = null;
     for (const t of rows) {
@@ -196,44 +187,74 @@ async function search(term, { type = "REST", max = 5, lines = 0, recipes = type
              line: at < 0 ? 1 : lineAt(at), lines: rows.length,
              ...(steps.length && { steps: steps.slice(0, 6) }),
              ...(calls.length && { calls: calls.slice(0, 4) }) };
-  }).filter(h => h.docsUrl && h.recipe);
-  let cursor = recipeText.length;
-  const hits = main.content.split(/\n---\n+(?=#### )/).map(b => {
+  };
+  const articleOutline = (block, start) => {
+    const outline = [];
+    let fenced = false, offset = 0;
+    for (const row of block.split("\n")) {
+      if (/^\s*(```|~~~)/.test(row)) fenced = !fenced;
+      const heading = !fenced && row.match(/^#{2,3} (.+)$/);
+      if (heading && !/^(Resource|Article|Article Link|Article Content):/.test(heading[1])) {
+        outline.push({ title: heading[1].slice(0, 64), line: lineAt(start + offset) });
+        if (outline.length === 3) break;
+      }
+      offset += row.length + 1;
+    }
+    return outline;
+  };
+  let cursor = 0;
+  const hits = content.split(/\n---\n+(?=#### )/).map(b => {
     const start = content.indexOf(b, cursor); cursor = start + b.length;
     const examples = [...b.matchAll(/--- Code Example: (.+?) ---/g)]
       .map(m => ({ title: m[1].trim(), line: lineAt(start + m.index) }));
     const docsUrl = (b.match(/#### \[[^\]]+\]\((https:[^)]+)\)/) || [])[1];
     const method = (b.match(/^# Method: (.+)$/m) || [])[1];
+    if (!method && docsUrl && new URL(docsUrl).pathname.includes("/skills/")) return parseRecipe(b, start);
     // the REST corpus mixes guides in with the methods — an article has no method header, so
     // name it from its own title rather than returning a row of nulls
     if (!method) return { article: (b.match(/^## (?:Resource|Article): (.+)$/m) || [])[1], docsUrl,
-                          line: start < 0 ? 1 : lineAt(start) };
+                          line: start < 0 ? 1 : lineAt(start),
+                          outline: articleOutline(b, start) };
     return {
     method,
     endpoint: (b.match(/^# Method API Endpoint: (.+)$/m) || [])[1],   // "VERB url" — read the verb + url; call wx.<verb>(url, body, token)
     docsUrl,
-    gist: ((b.match(/## Method Description:\s*\n([\s\S]{0,400})/) || [])[1] || "")
-      .trim().replace(/\s+/g, " ").slice(0, 220),
+    gist: (() => {
+      const description = ((b.match(/## Method Description:\s*\n([\s\S]*?)(?=\n## |$)/) || [])[1] || "")
+        .trim().replace(/\s+/g, " ");
+      return description.length > 160 ? description.slice(0, 159).trimEnd() + "…" : description;
+    })(),
     ...(examples.length && { examples }),
   }; }).filter(h => h.docsUrl);
   const saved = save("search-" + term.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40) + ".md", content);
-  if (!hits.length && !recipeHits.length) return clip({ ...saved, head: content.slice(0, 1200),
-    note: `no method blocks parsed — raw head above; wx.bash("grep -in 'term' ${saved.path}") for the rest` });
-  // one URL, one row: a long article is indexed in chunks that rank separately, and a stray skills
-  // page sits in the REST corpus, so the same page can rank two or three times
+  if (!hits.length) return clip({ ...saved, head: content.slice(0, 1200),
+    note: `no result blocks parsed — raw head above; wx.bash("grep -in 'term' ${saved.path}") for the rest` });
+  // Keep the service's combined ranking/interleave; retain the first occurrence of each URL.
   const seen = new Set();
-  const recipeRows = recipeHits.filter(r => !seen.has(r.docsUrl) && seen.add(r.docsUrl));
-  const uniq = hits.filter(h => !seen.has(h.docsUrl) && seen.add(h.docsUrl));
-  const out = { ...saved, ...(recipeRows.length && { recipes: recipeRows }), hits: uniq };
+  const ordered = hits.filter(h => !seen.has(h.docsUrl) && seen.add(h.docsUrl));
+  const recipeRows = ordered.filter(h => h.recipe);
+  const uniq = ordered.filter(h => !h.recipe);
+  const out = { ...saved, hits: ordered };
   // over budget, shed enrichment rather than structure — clip would drop the whole shape, and
   // every title, URL and line number stays useful with the outlines gone
   for (const shed of [() => recipeRows.forEach(r => delete r.calls),
                       () => recipeRows.forEach(r => delete r.steps),
                       () => uniq.forEach(h => { if (h.examples) h.examples = h.examples.slice(0, 3); }),
-                      () => uniq.forEach(h => delete h.examples)]) {
+                      () => uniq.forEach(h => delete h.examples),
+                      () => uniq.forEach(h => delete h.gist),
+                      () => uniq.forEach(h => delete h.outline)]) {
     if (JSON.stringify(out).length <= BUDGET) break;
     shed();
   }
+  // Preserve at least one result of each kind when the inline index needs trimming.
+  while (JSON.stringify(out).length > BUDGET) {
+    const kind = h => h.recipe ? "recipe" : h.method ? "method" : "article";
+    const counts = out.hits.reduce((n, h) => (n[kind(h)] = (n[kind(h)] || 0) + 1, n), {});
+    const index = out.hits.findLastIndex(h => counts[kind(h)] > 1);
+    if (index < 0) break;
+    out.hits.splice(index, 1);
+    out.note = "Additional results are in the saved file.";
+  }
   return clip(out);
 }