@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-app/scripts/scan-a11y-eslint.cjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+'use strict';
+
+// oxlint-disable no-console preserve-caught-error
+
+const path = require('path');
+const { createRequire } = require('module');
+
+const ROOT = process.cwd();
+const LOCAL_REQUIRE = createRequire(__filename);
+const ROOT_REQUIRE = createRequire(path.join(ROOT, 'package.json'));
+const { ESLint } = loadModule('eslint');
+const jsxA11y = loadModule('eslint-plugin-jsx-a11y');
+const tsParser = loadModule('@typescript-eslint/parser');
+
+const RULE_CONFIG = {
+  'jsx-a11y/alt-text': 'error',
+  'jsx-a11y/anchor-has-content': 'error',
+  'jsx-a11y/anchor-is-valid': 'error',
+  'jsx-a11y/aria-activedescendant-has-tabindex': 'error',
+  'jsx-a11y/aria-props': 'error',
+  'jsx-a11y/aria-proptypes': 'error',
+  'jsx-a11y/aria-role': 'error',
+  'jsx-a11y/aria-unsupported-elements': 'error',
+  'jsx-a11y/click-events-have-key-events': 'error',
+  'jsx-a11y/heading-has-content': 'error',
+  'jsx-a11y/iframe-has-title': 'error',
+  'jsx-a11y/img-redundant-alt': 'error',
+  'jsx-a11y/interactive-supports-focus': 'error',
+  'jsx-a11y/label-has-associated-control': 'error',
+  'jsx-a11y/media-has-caption': 'error',
+  'jsx-a11y/mouse-events-have-key-events': 'error',
+  'jsx-a11y/no-access-key': 'error',
+  'jsx-a11y/no-aria-hidden-on-focusable': 'error',
+  'jsx-a11y/no-autofocus': 'error',
+  'jsx-a11y/no-distracting-elements': 'error',
+  'jsx-a11y/no-interactive-element-to-noninteractive-role': 'error',
+  'jsx-a11y/no-noninteractive-element-interactions': 'error',
+  'jsx-a11y/no-noninteractive-element-to-interactive-role': 'error',
+  'jsx-a11y/no-noninteractive-tabindex': 'error',
+  'jsx-a11y/no-redundant-roles': 'error',
+  'jsx-a11y/no-static-element-interactions': 'error',
+  'jsx-a11y/prefer-tag-over-role': 'error',
+  'jsx-a11y/role-has-required-aria-props': 'error',
+  'jsx-a11y/role-supports-aria-props': 'error',
+  'jsx-a11y/scope': 'error',
+  'jsx-a11y/tabindex-no-positive': 'error',
+};
+
+function toRelative(filePath) {
+  return path.relative(ROOT, filePath) || filePath;
+}
+
+function severityLabel(severity) {
+  if (severity === 2) return 'error';
+  if (severity === 1) return 'warning';
+  return 'off';
+}
+
+function loadModule(name) {
+  try {
+    return LOCAL_REQUIRE(name);
+  } catch (localError) {
+    try {
+      return ROOT_REQUIRE(name);
+    } catch (rootError) {
+      throw new Error(
+        `Missing dependency "${name}". Local resolution failed: ${localError.message}. Root resolution failed: ${rootError.message}`,
+      );
+    }
+  }
+}
+
+function createEslint() {
+  try {
+    return new ESLint({
+      overrideConfigFile: true,
+      overrideConfig: [
+        {
+          files: ['**/*.{tsx,jsx,ts,js}'],
+          languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+              ecmaFeatures: { jsx: true },
+              ecmaVersion: 2022,
+              sourceType: 'module',
+            },
+          },
+          plugins: {
+            'jsx-a11y': jsxA11y,
+          },
+          rules: RULE_CONFIG,
+        },
+      ],
+    });
+  } catch (flatConfigError) {
+    try {
+      return new ESLint({
+        useEslintrc: false,
+        overrideConfig: {
+          parser: '@typescript-eslint/parser',
+          plugins: ['jsx-a11y'],
+          parserOptions: {
+            ecmaFeatures: { jsx: true },
+            ecmaVersion: 2022,
+            sourceType: 'module',
+          },
+          rules: RULE_CONFIG,
+        },
+        extensions: ['.tsx', '.jsx', '.ts', '.js'],
+      });
+    } catch (legacyConfigError) {
+      throw new Error(
+        `Failed to initialize ESLint. Flat config error: ${flatConfigError.message}. Legacy config error: ${legacyConfigError.message}`,
+      );
+    }
+  }
+}
+
+async function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.log(
+      JSON.stringify(
+        {
+          error: 'No files specified.',
+          usage: 'node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...',
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(1);
+  }
+
+  const absoluteFiles = files.map((f) => path.resolve(f));
+
+  const eslint = createEslint();
+
+  const results = await eslint.lintFiles(absoluteFiles);
+
+  const findings = [];
+  const parseErrors = [];
+
+  for (const result of results) {
+    const relFile = toRelative(result.filePath);
+
+    for (const msg of result.messages) {
+      if (msg.fatal) {
+        parseErrors.push({
+          file: relFile,
+          line: msg.line,
+          column: msg.column,
+          message: msg.message,
+        });
+        continue;
+      }
+
+      if (!msg.ruleId || !msg.ruleId.startsWith('jsx-a11y/')) continue;
+
+      findings.push({
+        file: relFile,
+        line: msg.line,
+        column: msg.column,
+        endLine: msg.endLine ?? null,
+        endColumn: msg.endColumn ?? null,
+        rule: msg.ruleId,
+        severity: severityLabel(msg.severity),
+        message: msg.message,
+      });
+    }
+  }
+
+  const ruleBreakdown = {};
+  for (const f of findings) {
+    ruleBreakdown[f.rule] = (ruleBreakdown[f.rule] || 0) + 1;
+  }
+
+  const output = {
+    meta: {
+      filesScanned: files.length,
+      engine: 'eslint + eslint-plugin-jsx-a11y',
+      rulesEnabled: Object.keys(RULE_CONFIG).length,
+      parseErrors,
+    },
+    findings,
+    summary: {
+      totalFindings: findings.length,
+      filesWithFindings: new Set(findings.map((f) => f.file)).size,
+      cleanFiles: files.length - new Set(findings.map((f) => f.file)).size,
+      ruleBreakdown,
+    },
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main().catch((err) => {
+  console.error(JSON.stringify({ error: err.message }, null, 2));
+  process.exit(1);
+});

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

@@ -0,0 +1,185 @@
+---
+name: wix-base44-connector
+description: "Build on Wix from the Base44 builder sandbox — this file is the complete guide (site context, doc discovery, API contracts, who calls Wix from where), and scripts/utils.js is its helper module, loaded from disk per exec. Triggers: build a Base44 app on a connected Wix site, look up a Wix API from the sandbox, decide frontend vs backend for a Wix call."
+---
+
+# Building on Wix from Base44
+
+The Wix connector is connected; this is how the app gets built on it — gather the site's context,
+find the APIs and learn their contracts from the docs, write the code. **Discover everything**: endpoints, paths, doc URLs,
+request and response fields all come from the calls below, never from memory or pattern. 404 or
+empty ⇒ discover, not permute. Examples teach mechanics and go stale — verify before relying.
+
+## 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.
+
+```
+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
+```
+
+**A site for visitors** — storefront, blog, booking. Headless means the Wix site has no pages of
+its own: your app IS its frontend. **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 the catalog directly), and `carts/current/*` + checkout act
+on the CALLER's cart, so only the visitor token reaches the visitor's cart. One file carries it
+all: `src/lib/wixClient.js` (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. The pages act as the owner, whose token
+is a secret: `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 —
+reload each round; the module lives on disk next to this file, network only as first-touch
+fallback):
+
+```js
+const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+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; })();
+```
+
+Results ≤ 4,000 chars come back inline (exec results clip at ~5,000); anything bigger is saved
+under `.agents/skills/wix-base44-connector/scratch/` and returns `{ path, bytes, lines, outline }` —
+the outline is the map. Read a saved file the way you already know how:
+`wx.bash("grep -n 'term' <path> | head -40")` to find (GNU grep/sed, awk is mawk, no rg;
+across everything saved: `grep -rn 'term' .agents/skills/wix-base44-connector/scratch/`), and
+`read_file` to quote — a window via `offset`/`limit` at the lines grep named, or the whole
+file when it fits read_file's 45K cap. **API responses are site data and never land in
+scratch** — project them to facts. Fetch every URL inside exec with `fetch()` — website/browser
+tools clip at 10,000 chars silently. One exec per round; timeout 10s, up to 120 via `{timeout}`.
+
+## Gather context — the dynamic context report
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+return await wx.context(accessToken, "Apps");   // no section arg → the report's outline
+```
+
+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.
+
+## Learn Wix — find the APIs, learn their contracts
+
+```js
+// know the product? browse is deterministic — menuUrl alone orients (children + counts);
+// filter before listing methods, unfiltered listings clip
+await wx.browse("https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings",
+                { include: ["METHOD"], filter: "resched", depth: 4 });
+
+// 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
+```
+
+Go deeper for fields, enums, or absence — only the spec index proves absence.
+
+### Read a doc page
+
+Method pages are 100 KB+, twin REST and SDK halves repeating field names at different types —
+map and window in the SAME exec; coordinates are for your code, not for a second round:
+
+```js
+const pg = await wx.page(docsUrl);   // whole text when small; else { path, bytes, lines, outline }
+// your half, windowed to your term and its Examples (a complete working request — URL, headers,
+// body — usually all you need), one round:
+return wx.bash(`sed -n '/^## REST API/,/^## JavaScript SDK/p' ${pg.path} | grep -B5 -A40 -i 'examples\\|<term>' | head -c 3800`);
+// a giant fenced example → its field vocabulary instead of paging it:
+// wx.bash(`sed -n '<a>,<b>p' ${pg.path} | grep -oE '"[a-zA-Z]+":' | sort -u | head -60`)
+```
+
+`search` also saves its raw content beside the inline hits — grep its `path` when a hit's six
+lines weren't enough.
+
+### The spec index
+
+Answers questions about pages you already found — arrive with a `docsUrl`, match by it. Also the
+only proof an API does NOT exist:
+
+```js
+await wx.spec(`
+  const r = lightIndex.find(x => x.docsUrl === "<docsUrl from browse/search>");
+  return r.methods.map(m => ({ op: m.operationId.split(".").pop(), verb: m.httpMethod,
+                               call: m.publicUrl }));   // publicUrl is callable — path is PARTIAL
+`);
+// request fields next round: getResourceSchemaByUrl(docsUrl) →
+//   m.requestBody.content["application/json"].schema.properties — names and types, drill deeper
+//   per round; $circular stubs resolve via s.components.schemas["<name>"]
+```
+
+### Management recipes — check before composing admin flows
+
+~100 curated multi-step recipes (install apps, seed catalogs, set up whole verticals):
+
+```js
+await wx.recipes();           // categories with counts
+await wx.recipes("stores");   // a category's list — or any task word: wx.recipes("coupon")
+await wx.page(url);           // read the chosen recipe — whole when small, saved + outline when
+                              // big; then grep / read_file windows by the outline's line numbers
+```
+
+A matching recipe beats composing the flow from single endpoints: it carries ordering and
+cross-step gotchas no method page mentions.
+
+## Write the code
+
+**Response shapes obey the discover rule in every lane**: code against fields you saw in a live
+response or the schema — remembered names are often from older versions. Probe one real row first.
+
+### Admin calls — exec ad hoc, backend functions deployed
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const data = await wx.post("https://www.wixapis.com/contacts/v5/contacts/query",   // spec-index publicUrl
+  { query: { cursorPaging: { limit: 10 } } }, accessToken);
+// let it throw — the thrown message is your result; .catch hides the answer
+return wx.clip({ error: null, count: data.contacts?.length, first: data.contacts?.[0] });
+//  ↑ one real row, whole — the shapes you code against live here, not in key names
+```
+
+The same call deploys as `base44/functions/*` (work the app does as the owner) — shipped code
+carries its own four-line fetch; the helpers are a build tool, not a runtime dependency.
+
+### A visitor client — src/lib/wixClient.js
+
+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
+anonymous visitor", safe in shipped code:
+
+```js
+// src/lib/wixClient.js
+let token;
+const mint = async (body) => {
+  const r = await (await fetch("https://www.wixapis.com/oauth2/token", { method: "POST",
+    headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) })).json();
+  token = r.access_token; sessionStorage.setItem("wixRefresh", r.refresh_token);   // expires_in: 14400s = 4h
+};
+// first visit:  mint({ clientId: WIX_CLIENT_ID, grantType: "anonymous" });
+// on expiry:    mint({ refreshToken: sessionStorage.getItem("wixRefresh"), grantType: "refresh_token" });
+//               a fresh anonymous mint is a NEW visitor — the old one's cart goes with it
+export const wix = (path, opts = {}) => fetch("https://www.wixapis.com" + path, { ...opts,
+  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:
+
+```js
+const { access_token } = 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);
+// 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
+```

package/skills/wix-base44-connector/scripts/utils.js

@@ -0,0 +1,212 @@
+// Wix docs helpers for the Base44 sandbox — the scratch-lane set. Small results return
+// inline; anything over ~4,000 chars (exec results clip at ~5,000) is saved under the
+// scratch dir and comes 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";
+//   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; })();
+//
+// 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 stay OUT of scratch (scratch ships with the app):
+// post() never saves — project responses to facts.
+
+const fs = require("fs");
+const path = require("path");
+
+const BUDGET = 4000;
+const SCRATCH = ".agents/skills/wix-base44-connector/scratch";
+
+const clip = (out) => {
+  if (typeof out === "string")
+    return out.length <= BUDGET ? out : { truncated: true, total: out.length, head: out.slice(0, BUDGET) };
+  // absence must be visible: JSON.stringify silently ERASES undefined keys, so a probe like
+  // { lineItems: resp.cart?.lineItems } loses the very field that proves the call failed —
+  // render undefined as null instead
+  const s = JSON.stringify(out, (k, v) => v === undefined ? null : v);
+  return s.length <= BUDGET ? JSON.parse(s) : { truncated: true, total: s.length, head: s.slice(0, BUDGET) };
+};
+
+// One transport for every JSON call — Content-Type, optional Bearer, ok-guard.
+// Admin calls are this with the connector token: post(publicUrl, body, accessToken).
+async function post(url, body, token) {
+  const r = await fetch(url, { method: "POST", body: JSON.stringify(body),
+    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"
+      : ""));
+  }
+  return r.json();
+}
+
+function save(name, text) {
+  const dir = path.join(process.cwd(), SCRATCH);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, name), text);
+  return { path: SCRATCH + "/" + name, bytes: Buffer.byteLength(text), lines: text.split("\n").length };
+}
+
+const outlineOf = (lines, cap = 30) => {
+  const heads = [];
+  lines.forEach((t, i) => { if (/^#{1,3} /.test(t)) heads.push({ line: i + 1, text: t.trim().slice(0, 80) }); });
+  return { outline: heads.slice(0, cap), outlineOmitted: Math.max(0, heads.length - cap) };
+};
+
+// A ref is a scratch path or the URL it came from — resolve to lines, fetching+saving
+// URLs on first touch (the .md suffix is appended for extensionless docs URLs).
+const slugOf = (url) => url.replace(/\?.*$/, "").split("/").pop().replace(/\.md$/, "") + ".md";
+async function resolveRef(ref) {
+  const isUrl = /^https?:/.test(ref);
+  const name = isUrl ? slugOf(ref) : ref.split("/").pop();
+  const file = path.join(process.cwd(), SCRATCH, name);
+  if (fs.existsSync(file)) return { path: SCRATCH + "/" + name, lines: fs.readFileSync(file, "utf8").split("\n") };
+  if (!isUrl) throw new Error("no such scratch file: " + ref + " — pass a returned path or the source URL");
+  const mdUrl = /\.[a-z]{2,5}$/.test(ref.replace(/\?.*$/, "")) ? ref : ref.replace(/\?.*$/, "") + ".md";
+  const res = await fetch(mdUrl);
+  if (!res.ok) throw new Error(res.status + " on " + mdUrl + " — not a docs page; take URLs from output, don't compose");
+  const text = await res.text();
+  const saved = save(name, text);
+  return { path: saved.path, lines: text.split("\n") };
+}
+
+// ── 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) {
+  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" });
+}
+
+// ── find what to read ─────────────────────────────────────────────────────────
+
+// Browse the docs tree — deterministic. menuUrl alone orients (children + counts);
+// filter before listing methods. An oversized listing is saved with its outline.
+async function browse(menuUrl, { include, filter, depth } = {}) {
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse", {
+    menu_url: menuUrl, ...(include && { include }),
+    ...(filter && { name_filter: filter }), ...(depth && { depth }),
+  });   // 404 "No menu node found" ⇒ re-orient a level up
+  if (content.length <= BUDGET) return content;
+  const s = save("browse-" + (menuUrl.replace(/\/+$/, "").split("/").pop() || "root") + ".md", content);
+  return { ...s, next: `wx.bash("grep -in 'term' ${s.path} | head -40")   // one line per node — or re-browse with a filter` };
+}
+
+// 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.
+async function search(term, { type = "REST", max = 5, lines = 6 } = {}) {
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
+    { search_term: term, document_type: type, maximum_results: max, lines_in_each_result: lines });
+  const hits = content.split(/\n---\n+(?=#### )/).map(b => ({
+    method:   (b.match(/^# Method: (.+)$/m) || [])[1],
+    endpoint: (b.match(/^# Method API Endpoint: (.+)$/m) || [])[1],   // callable
+    docsUrl:  (b.match(/#### \[[^\]]+\]\((https:[^)]+)\)/) || [])[1],
+    gist: ((b.match(/## Method Description:\s*\n([\s\S]{0,400})/) || [])[1] || "")
+      .trim().replace(/\s+/g, " ").slice(0, 220),
+  })).filter(h => h.docsUrl);
+  const saved = save("search-" + term.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40) + ".md", content);
+  if (!hits.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` });
+  return clip({ ...saved, hits });
+}
+
+// ── read a page (docs pages and recipes alike) ────────────────────────────────
+
+// Fetch + save + map in one round: whole text inline when small, else
+// { path, bytes, lines, outline } — the outline's line numbers feed grep and read_file windows.
+async function page(url) {
+  const { path: p, lines } = await resolveRef(url);
+  const text = lines.join("\n");
+  if (text.length <= BUDGET) return text;
+  const o = outlineOf(lines);
+  const bytes = Buffer.byteLength(text);
+  return { path: p, bytes, lines: lines.length, ...o,
+           next: [
+             `wx.bash("grep -in 'term' ${p} | head -40")`,
+             bytes <= 45000 ? `read_file ${p}   // whole (fits the 45K cap), or a window via offset/limit`
+                            : `read_file ${p} with offset/limit   // window a section by the outline's lines`,
+           ] };
+}
+
+// ── shell ─────────────────────────────────────────────────────────────────────
+
+// Compose native pipelines over scratch — grep -n, sed -n, mawk, sort, uniq, wc
+// (GNU grep/sed; awk is mawk; no rg). Cap your own output (| head -40); the return
+// clips regardless. grep's exit 1 means no match, not failure — the return says so.
+function bash(cmd) {
+  const { execSync } = require("child_process");
+  try {
+    const out = execSync(cmd, { timeout: 15000, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+    return out.trim() ? clip(out)
+      : "(no output — a filter may have swallowed the signal; rerun without the reducer)";
+  } catch (e) {
+    const exit = e.status ?? null, err = (e.stderr || "").toString().trim();
+    return { exit, ...(err && { err: err.slice(0, 300) }),
+             out: clip((e.stdout || "").toString()),
+             ...(exit === 1 && !err && { note: "exit 1 with no stderr — a no-match, not a failure" }) };
+  }
+}
+
+// ── the spec index ────────────────────────────────────────────────────────────
+
+// Run a query over the API spec index. In scope: lightIndex (RESOURCES with
+// .methods — operationId, summary, httpMethod, path [PARTIAL — never call it],
+// publicUrl [callable], docsUrl) and getResourceSchemaByUrl(docsUrl). Arrive with
+// a docsUrl and match by it — also the only proof an API does NOT exist.
+// A big result is saved as JSON; grep it for the keys you saw in its head.
+async function spec(code) {
+  if (!/^\s*async function/.test(code)) code = `async function(){ ${code} }`;
+  const { result } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  if (result == null || (Array.isArray(result) && !result.length))
+    return { result, note: "empty — the query missed the shape, not proof of absence; find the resource by docsUrl on lightIndex" };
+  const text = JSON.stringify(result, null, 1);
+  if (text.length <= BUDGET) return result;
+  return { ...save("spec.json", text),
+           shape: Array.isArray(result) ? `Array(${result.length})` : Object.keys(result || {}).slice(0, 15),
+           head: text.slice(0, 600) };
+}
+
+// ── management recipes ────────────────────────────────────────────────────────
+
+// ~100 curated multi-step admin flows. No arg → categories with counts; a category
+// name → its recipes; any other term → search every recipe's name + gist for it.
+// Read the chosen url with page(url), then grep/window/fields.
+async function recipes(q) {
+  const { base, files } = await (await fetch("https://dev.wix.com/docs/skills/manage.manifest.json")).json();
+  const cat = f => (f.path.match(/^references\/([^/]+)\//) || [])[1];
+  const row = f => ({ name: f.name, cat: cat(f), gist: (f.description || "").slice(0, 120),
+                      url: base + f.path, kb: Math.round(f.size / 1024) });
+  if (!q) {
+    const cats = {};
+    for (const f of files) { const c = cat(f); if (c) cats[c] = (cats[c] || 0) + 1; }
+    return cats;
+  }
+  const inCat = files.filter(f => cat(f) === q);
+  if (inCat.length) return clip(inCat.map(row));
+  const re = new RegExp(q, "i");
+  const m = files.filter(f => re.test(f.name + " " + (f.description || "")));
+  if (!m.length) {
+    const cats = {};
+    for (const f of files) { const c = cat(f); if (c) cats[c] = (cats[c] || 0) + 1; }
+    return { note: `nothing matches "${q}" — the categories:`, categories: cats };
+  }
+  return clip(m.map(row));
+}
+
+module.exports = { post, clip, context, browse, search, page, bash, spec, recipes };

package/skills/wix-design-system/SKILL.md

@@ -95,27 +95,27 @@ Don't read these files fully. Grep for keywords, then read specific sections wit
 
 ## Quick Component Mapping (Design to WDS)
 
-| Design Element | WDS Component | Notes |
-| --- | --- | --- |
-| Rectangle/container | `<Box>` | Layout wrapper |
-| Text button | `<TextButton>` | Secondary actions |
-| Input with label | `<FormField>` + `<Input>` | Wrap inputs |
-| Toggle | `<ToggleSwitch>` | On/off settings |
-| Modal | `<Modal>` + `<CustomModalLayout>` | Use together |
-| Grid | `<Layout>` + `<Cell>` | Responsive |
+| Design Element      | WDS Component                     | Notes             |
+| ------------------- | --------------------------------- | ----------------- |
+| Rectangle/container | `<Box>`                           | Layout wrapper    |
+| Text button         | `<TextButton>`                    | Secondary actions |
+| Input with label    | `<FormField>` + `<Input>`         | Wrap inputs       |
+| Toggle              | `<ToggleSwitch>`                  | On/off settings   |
+| Modal               | `<Modal>` + `<CustomModalLayout>` | Use together      |
+| Grid                | `<Layout>` + `<Cell>`             | Responsive        |
 
 ## Spacing (px to SP conversion)
 
 When designer specifies pixels, convert to the nearest SP token:
 
 | Token | Classic | Studio |
-| --- | --- | --- |
-| `SP1` | 6px | 4px |
-| `SP2` | 12px | 8px |
-| `SP3` | 18px | 12px |
-| `SP4` | 24px | 16px |
-| `SP5` | 30px | 20px |
-| `SP6` | 36px | 24px |
+| ----- | ------- | ------ |
+| `SP1` | 6px     | 4px    |
+| `SP2` | 12px    | 8px    |
+| `SP3` | 18px    | 12px   |
+| `SP4` | 24px    | 16px   |
+| `SP5` | 30px    | 20px   |
+| `SP6` | 36px    | 24px   |
 
 ```tsx
 <Box gap="SP2" padding="SP3">
@@ -130,6 +130,10 @@ import { Button, Card, Image } from "@wix/design-system";
 import { Add, Edit, Delete } from "@wix/wix-ui-icons-common";
 ```
 
+## GUIDELINES
+
+1. Don't ever override WDS CSS tokens. Only if it's not possible otherwise, mention that very clearly to the prompter, that this is an anti-pattern and should be avoided at all costs.
+
 ### Troubleshooting
 
 - **Components render unstyled** (plain HTML look, missing WDS spacing/typography): add `import "@wix/design-system/styles.global.css";` once to the root/main component (e.g. `page.tsx`, modal entry) — not child/tab/helper files.