@wix/agent-skills 1.16.2 → 1.17.0

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

@@ -1,173 +1,89 @@
-# React Component Implementation Guide
+# React Implementation Guide
 
-This guide defines rules and guidance on **how to implement** production-quality Editor React components for Wix CLI applications. Editor React components are React components that integrate with the Wix Editor, allowing site owners to customize content, styling, and behavior through a visual interface.
+Use this reference when planning or editing the component's React implementation.
+The entry workflow remains authoritative; this file owns implementation decisions.
 
-**Topic reference files:**
-- [`PARTS.md`](PARTS.md) — What qualifies as a named part (mandatory filter)
-- [`DESIGN-STATES.md`](DESIGN-STATES.md) — Which design states a part supports, and how to author them
-- [`ACCESSIBILITY.md`](ACCESSIBILITY.md) — ARIA/a11y rules and patterns
-- [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
-- [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
-- [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
-- [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks
-- [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
-- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
+## Plan the Component
 
-## React 18 features are not supported
+For a new component, make every decision below. For an edit, revisit only the
+contracts changed by the request:
 
-The Wix runtime does not currently support React 18 features. Stick
-to React 17-compatible APIs and avoid libraries that depend on
-React 18 features.
+1. Elect the best semantic root and identify independently editable inner parts.
+2. Separate user-authored content and stable behavior from derived values and
+   visual styling.
+3. Identify interaction and selectable states affected by the request.
+4. Keep implementation behavior internal unless the component specification
+   requests a public callback.
+5. Identify runtime concerns such as browser APIs, autoplay, editor-only
+   behavior, or live site context before implementation.
 
-# Part 0: Component Behavior Guide
+## Implementation Rules
 
-Understand the component and infer its behavior. Extract what is provided; use reasonable defaults for anything not specified.
+### Runtime Compatibility
 
-1. **Identity** — Component name.
-2. **Structure** — Elect the root element per [`PARTS.md`](PARTS.md) Step 0, then identify named inner parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
-3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally. If the component's primary content is a **playable animation** (Lottie/JSON, animated GIF/SVG, canvas/WebGL loop, video-like surface), it gets a play/pause control — follow [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
-4. **States** — For every part, decide which design states it supports (native: `hover`/`focus`/`disabled`/`invalid`; custom: `selected`/`active`/`open`/… ) by applying the heuristic in [`DESIGN-STATES.md`](DESIGN-STATES.md), and record them in the plan. These become the editor's per-element state styling controls.
-
-**Understanding → implementation (checklist):** For every part, decide `elementProps` vs CSS-only and which design states it supports ([`DESIGN-STATES.md`](DESIGN-STATES.md)); build the props interface (data + behavior); wire interaction in React (`useState`, `useEffect`, refs, native event handlers); give every named inner element an `elementProps` entry and spread it + merge its `className` ([`COMPONENT-API.md`](COMPONENT-API.md)); generate TS + CSS. Infer reasonable defaults where anything is unspecified.
-
-# Part 1: Standards & Conventions
-
-These are the mandatory patterns and conventions for all components.
-
-## 1.1 Mandatory Features
-
-Every component MUST include:
-
-### Direction Support (RTL/LTR)
-
-Direction support is mandatory — see [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
-
-### Accessibility ARIA Support
-
-See [`ACCESSIBILITY.md`](ACCESSIBILITY.md) for full rules and patterns.
+- Use React 18-compatible APIs. Do not use React 19-only runtime features.
+- Keep rendering SSR-safe and deterministic. Do not access browser globals
+  during render or derive initial output from time-dependent/generated values.
 
 ### TypeScript
 
-- All components must be fully typed
-- NO `any` types
-- Export all prop interfaces
-- Use proper React types (`React.FC`, `React.ReactNode`, etc.)
-- **Array type syntax:** Use `Array<T>` instead of `T[]` (e.g., `Array<Item>` not `Item[]`)
-- **Array element types:** `T` must be an object with named keys — `Array<{ key: ValueType, ... }>` or a named interface that is itself a keyed object. Never `Array<string>`, `Array<number>`, `Array<boolean>`, or `Array<DataType>` (`Image`, `Link`, `Video`, `Audio`, `VectorArt`, `RichText`, etc.). See [`COMPONENT-API.md`](COMPONENT-API.md) for full rules.
-- **Component function pattern:**
-  - Use inline arrow functions with `export const`
-  - Accept `props` as the argument (do NOT destructure in function signature)
-  - Destructure props inside the component body
-
-## 1.2 Implementation Standards
-
-### When to Use elementProps
-
-See [`COMPONENT-API.md`](COMPONENT-API.md) for full elementProps rules and the decision tree.
-
-### React & Runtime Standards
-
-All components MUST follow these patterns:
-
-**1. SSR-Safe Implementation**
-
-- NO browser APIs at module scope (window, document, navigator, etc.)
-- Guard browser APIs with typeof checks or useEffect
-- All browser-dependent logic must run client-side only
-
-See [`REACT-PATTERNS.md`](REACT-PATTERNS.md) §1.1 for code examples.
-
-**2. Clean Code**
-
-- NO TypeScript errors
-- NO unused variables or imports
-- NO comments in React component files — code should be self-documenting through clear naming
-- NO TODO comments in generated code
-- **Remove ALL comments from the final component** — including any comments from templates/examples
-
-**3. Data-Driven Components (NO children in exported props)**
-
-See [`COMPONENT-API.md`](COMPONENT-API.md) for full rules and patterns.
-
-**4. Breakpoint-Responsive Properties (NO props for visual variations)**
-
-See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) for full rules and patterns.
-
-**5. Reactive to Prop Changes**
-
-- Components MUST react to prop changes
-- If state is derived from props, use `useEffect` with prop dependencies
-- State initialized from props should update when props change
-
-**6. Event Handler Scope (Internal by Default)**
-
-Unless explicitly specified as a component capability/API in the specification, all event handlers are **internal** and NOT exposed as props.
-
-**Internal handlers (default):**
-
-- Used for component behavior (autoplay, animations, state management)
-- NOT exposed in the component's props interface
-
-**External handlers (only when specified):**
-
-- Only expose handlers that are explicitly listed as component capabilities
-- Use the standard SDK prop names and DOM wiring rules from [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md)
-
-**Child component handlers:**
-
-- Internal sub-components receive handlers from parent via props
-- These are still internal to the main component
-
-## 1.3 Implementation Workflow
-
-### Step 1: Analyze Component Parts
-
-For each part of the component, decide:
-
-**CSS class only if**:
-
-- ✅ Purely visual/decorative
-- ✅ No data or configuration needed
-- ✅ No direction override needed
-- ✅ No custom behavior needed
-
-**Use elementProps if**:
-
-- ✅ Needs data/content
-- ✅ Needs direction override
-- ✅ Has state or behavior
-- ✅ Needs event handlers
-
-For the same part, also decide which **design states** it supports (native + custom) per [`DESIGN-STATES.md`](DESIGN-STATES.md).
-
-See [`COMPONENT-API.md`](COMPONENT-API.md) and [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) for the decision trees.
-
-### Step 2: Build Props Interface
-
-Combine:
-
-1. Data/content props (from specification)
-2. Behavior props (from specification)
-3. Mandatory React props (direction, a11y, className, id)
-4. elementProps (only for parts that need it)
-
-### Step 3: Implement
-
-Follow Part 2 templates with mandatory patterns applied. For each part's supported design states, author the interactive markup / class toggles and the state CSS per [`DESIGN-STATES.md`](DESIGN-STATES.md).
-
-# Part 2: CSS Rules
-
-All CSS authoring rules — root layout, naming, RTL, state styles,
-transitions, etc. — live in [`CSS-GUIDELINES.md`](CSS-GUIDELINES.md).
-
-See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.md) for the prop vs CSS vs `elementProps` decision trees.
-
-# Part 3: Examples & Reference
-
-## 3.1 Implementation Checklist
-
-**Phase 1: Analysis** — Parse information, map component structure and supported design states (see Part 0)
-
-**Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
-
-**Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md)). If the request uses the words **branded**, **themed**, or **brand-aware**, also apply [`BRANDED-COMPONENTS.md`](BRANDED-COMPONENTS.md) before writing CSS.
+- Fully type component props and export the props type.
+- Do not use `any`.
+- Use `Array<T>` rather than `T[]`; exported array elements must be objects with
+  named keys.
+- Export the component as an arrow function, accept `props` as its argument,
+  and destructure inside the function body.
+
+```tsx
+export const ProfileCard: React.FC<ProfileCardProps> = (props) => {
+  const { heading } = props;
+  return <article>{heading}</article>;
+};
+```
+
+### Props and State
+
+- Keep `id`, `className`, `direction`, and `a11y` in the public contract.
+- Compute simple derived values during render instead of duplicating them in
+  props or state.
+- When local state intentionally mirrors a prop, synchronize it when that prop
+  changes. Do not use effect-managed state for a value that can be derived
+  during render.
+- Keep implementation-only handlers internal. Expose a callback only when the
+  specification makes it part of the component API.
+
+### Structure and Parts
+
+- Apply the root contract to the elected semantic root; do not add a wrapper
+  solely to hold `id`, `dir`, classes, or ARIA attributes.
+- Give every named inner part a matching `elementProps` entry and spread it onto
+  that element. Merge its injected `className` on raw HTML elements.
+- Keep structural wrappers and decorative elements module-class-only.
+- Use semantic HTML for controls, lists, navigation, headings, and landmarks.
+
+### Accessibility and Direction
+
+- Route ARIA through the typed `a11y` contract.
+- Put `dir={direction}` and the unconditional fallback-direction class on the
+  elected root. Use logical CSS properties; use runtime direction hooks only
+  when direction changes JavaScript behavior.
+
+### Code Quality
+
+- Leave no TypeScript errors, unused imports, TODO placeholders, or template
+  commentary in the final component.
+- Prefer clear names and small internal components over long inline JSX blocks.
+- Preserve useful comments that explain non-obvious behavior; remove comments
+  that merely narrate the code or were copied from examples.
+
+## Implementation Checklist
+
+- [ ] The semantic root owns the top-level component contract.
+- [ ] Props contain content and behavior, not breakpoint styling decisions.
+- [ ] Every named inner part has global/module classes and `elementProps` wiring.
+- [ ] Native and custom design states in scope are wired to their affected parts.
+- [ ] Render output is deterministic and SSR-safe.
+- [ ] Direction and accessibility contracts are wired to the correct elements.
+- [ ] Public handlers use supported SDK names; internal handlers stay internal.
+- [ ] CSS changed by the request keeps editable selectors flat and scoped.
+- [ ] The accessibility review runs after JSX edits.

package/skills/wix-app/references/editor-react-component/SITE-CONTEXT-HOOKS.md

@@ -1,16 +1,18 @@
 # Site Context Hooks
 
-Rules and patterns for reading **runtime site context** in Editor React
-components — the site's page tree, the current URL, the language direction, and
-editor mode. None of these can be carried by a prop.
+Use this reference when the component must read **live runtime context** that the
+site owner cannot author as component data: the site page tree, current URL,
+language direction, editor mode, or reduced-motion preference.
 
 All of them come from hooks in `@wix/react-component-utils`, already a base
 dependency. No additional install is needed, but the hooks require
 `@wix/react-component-utils` ≥ 1.12.0.
 
----
+Verify the installed version before using these hooks. If it is older than
+1.12.0, report the version mismatch instead of writing code against unavailable
+exports or silently upgrading the package.
 
-## When this applies
+## Apply When
 
 Apply only when the component genuinely needs live site context:
 
@@ -25,15 +27,24 @@ Apply only when the component genuinely needs live site context:
 - **Behavior must differ inside the editor** — suppressing autoplay, network
   calls, or timers while the site owner is designing
 
+When behavior differs only in editor rendering, keep the main component's live
+contract unchanged and add the editor-only gate to the generated
+`component.preview.tsx` while preserving its wrappers.
+
 The test is whether the site owner **authors** the data. A hook reports state the
 owner cannot write — which page is being rendered, what the site's URL is. Data
 the owner chooses belongs in props, even when it happens to point at site
-pages — see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and
-[`COMPONENT-API.md`](COMPONENT-API.md). Purely visual RTL needs no hook
-either — use logical CSS properties, see
-[`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+pages. Purely visual RTL needs no hook either; use logical CSS properties.
+
+## Contents
 
----
+- [Rules](#rules)
+- [Read Values During Render](#read-values-during-render)
+- [Walking the Page Tree](#walking-the-page-tree)
+- [Building a Link to a Page](#building-a-link-to-a-page)
+- [Direction-Dependent Logic](#direction-dependent-logic)
+- [Avoid Direction Logic for Visual CSS](#avoid-direction-logic-for-visual-css)
+- [Checklist](#checklist)
 
 ## Rules
 
@@ -47,8 +58,8 @@ either — use logical CSS properties, see
 | `useSiteUrl()` | `string` | The site's public base URL |
 | `useCurrentUrl()` | `string` | Full URL of the page being rendered |
 | `useLanguageDirection()` | `'ltr' \| 'rtl'` | The site's language direction |
-| `useIsEditMode()` | `boolean` | `true` in editor design mode — see [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) |
-| `useReducedMotion()` | `boolean` | `true` when the OS requests reduced motion — see [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) |
+| `useIsEditMode()` | `boolean` | `true` in editor design mode |
+| `useReducedMotion()` | `boolean` | `true` when the OS requests reduced motion |
 
 All import from the same place:
 
@@ -63,7 +74,7 @@ scope, inside a callback, or conditionally.
 ### Read Values During Render
 
 Hook values are read on the server too, so their results are part of the server
-markup — see [`SSR.md`](SSR.md). Use the value directly.
+markup. Use the value directly.
 
 **✅ Correct:**
 
@@ -79,8 +90,6 @@ const [siteUrl, setSiteUrl] = useState('');
 useEffect(() => setSiteUrl(resolvedUrl), []);
 ```
 
----
-
 ## Patterns
 
 ### Walking the Page Tree
@@ -164,11 +173,9 @@ const onKeyDown = (event: React.KeyboardEvent) => {
 };
 ```
 
----
+## Avoid Direction Logic for Visual CSS
 
-## Common Mistake: Direction Logic Instead of Logical CSS
-
-Calling `useLanguageDirection()` to pick between physical CSS properties.
+Do not call `useLanguageDirection()` to choose between physical CSS properties.
 
 **❌ Wrong:**
 
@@ -180,8 +187,16 @@ const isRTL = useLanguageDirection() === 'rtl';
 
 **✅ Correct:**
 
-```scss
+```css
 .element {
-  padding-inline-start: 8px; // Auto RTL/LTR, no hook needed
+  padding-inline-start: 8px;
 }
 ```
+
+## Checklist
+
+- [ ] A hook supplies live context that cannot be represented by authored props.
+- [ ] Hooks are called unconditionally inside a component or custom hook.
+- [ ] Hook values are read during render rather than copied through an effect.
+- [ ] Page-tree traversal filters popups and guards parent cycles.
+- [ ] Direction hooks affect JavaScript behavior, not visual CSS choices.

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

@@ -1,119 +1,50 @@
-# Server-Side Rendering (SSR)
+# Server-Side Rendering
 
-Rules and patterns for SSR-safe Editor React components.
+Use this reference before introducing browser APIs, effects, time-dependent
+output, or client-only enhancement. Editor React Components are server-rendered
+and hydrated; the initial server and client markup must match.
 
-Editor React components are server-rendered and then hydrated on the client — every component MUST render correctly, completely, and identically on the server. SSR safety is mandatory for every component.
+## Browser APIs
 
----
-
-## Rules
-
-### No browser globals at module scope or during render
-
-`window`, `document`, `navigator`, `localStorage`, `sessionStorage`, `matchMedia`, `IntersectionObserver`, `ResizeObserver`, and other DOM/BOM APIs do not exist on the server. Never touch them at module scope or in the render body. Access them only inside `useEffect`, optionally guarded with `typeof window !== 'undefined'`.
-
-**❌ Wrong:**
-
-```typescript
-const userAgent = window.navigator.userAgent;
-```
-
-**✅ Correct:**
-
-```typescript
-useEffect(() => {
-  if (typeof window !== "undefined") {
-    const userAgent = window.navigator.userAgent;
-  }
-}, []);
-```
-
-### First render must be complete
-
-Render all parts unconditionally — never gate structural elements behind effect-set state. Initialize `useState` to a valid, server-renderable default so the first (server) render already shows the final structure. Element visibility is platform-managed; see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`REACT-PATTERNS.md`](REACT-PATTERNS.md) §1.2.
-
-**❌ Wrong — content only appears after an effect runs (missing on the server):**
+Do not access `window`, `document`, `navigator`, storage, observers, or other
+DOM/BOM APIs at module scope or during render. Use them inside `useEffect` and
+guard when needed.
 
 ```tsx
-const [items, setItems] = useState<Array<Item>>([]);
 useEffect(() => {
-  setItems(buildItems(props));
-}, [props]);
-return <ul>{items.map(/* ... */)}</ul>; // empty on the server
-```
-
-**✅ Correct — derive during render so it exists on the first pass:**
-
-```tsx
-const items = buildItems(props);
-return <ul>{items.map(/* ... */)}</ul>;
-```
-
-### Deterministic render
-
-The same props MUST produce the same markup on the server and the client. No `Math.random()`, `Date.now()`, `new Date()`, or locale/timezone-dependent output during render — these differ across environments and break hydration.
-
-**❌ Wrong:**
-
-```tsx
-<span>{new Date().toLocaleString()}</span>
-```
-
-**✅ Correct — derive from props, or compute in an effect:**
-
-```tsx
-<span>{formatDate(props.timestamp)}</span>
+  if (typeof window === 'undefined') return;
+  const userAgent = window.navigator.userAgent;
+  // client-only enhancement
+}, []);
 ```
 
-### Stable IDs via `useStableId`
-
-When a component needs an internal id (ARIA wiring such as `aria-controls` / `aria-labelledby`, or `htmlFor`), generate it with `useStableId` from `@wix/react-component-utils`. Never use `Math.random()`, a manual counter, or a bare `React.useId()` — those break hydration or are not available across runtimes. Pass the component's `id` prop as the override so a caller-supplied id wins, then derive child ids from the result.
+## Complete First Render
 
-**✅ Correct:**
+Derive renderable data directly from props when possible. Do not leave required
+structure empty until an effect copies or transforms props.
 
 ```tsx
-import { useStableId } from '@wix/react-component-utils';
-
-const rootId = useStableId(id);
-const panelId = `${rootId}-panel`;
-
-<button aria-controls={panelId}>{label}</button>
-<div id={panelId} role="tabpanel">{content}</div>
+// Correct: complete on the server and first client render.
+const items = buildItems(props.items);
+return <ul>{items.map(renderItem)}</ul>;
 ```
 
-**❌ Wrong:**
+This does not require every data branch to render simultaneously. Empty,
+loading, and error states may be conditional when their initial value is stable
+and the same on server and client.
 
-```tsx
-const panelId = `tab-${Math.random()}`; // ❌ differs every render
-const panelId = React.useId();          // ❌ use the useStableId util instead
-```
-
-### No `useLayoutEffect`
-
-`useLayoutEffect` does nothing on the server and triggers a React warning. Use `useEffect` for client-only work.
-
-**❌ Wrong:**
-
-```tsx
-useLayoutEffect(() => { measure(); }, []);
-```
+## Deterministic Output
 
-**✅ Correct:**
+Do not call `Math.random()`, `Date.now()`, `new Date()`, or environment-dependent
+locale/timezone formatting during render. Use a prop, a fixed deterministic
+format, or a client-only enhancement that does not replace the initial markup.
 
 ```tsx
-useEffect(() => { measure(); }, []);
+<time dateTime={timestamp}>{formattedDate}</time>
 ```
 
-### Effects are client-only enhancement
-
-`useEffect` runs only after hydration, never on the server. Use effects to enhance — not to produce the initial UI. The server-rendered default state must already look correct before any effect runs.
-
----
-
-## SSR Checklist
+## Checklist
 
-- [ ] No browser globals at module scope or in the render body — guarded inside `useEffect` only
-- [ ] All parts render unconditionally on the first pass; state initialized to a server-safe default
-- [ ] Render output is deterministic — no `Math.random()` / `Date.now()` / `new Date()` / locale-dependent output during render
-- [ ] Internal ids come from `useStableId(id)`, never random values, counters, or bare `React.useId()`
-- [ ] No `useLayoutEffect`
+- [ ] No browser globals are accessed at module scope or during render.
+- [ ] Initial server/client markup is complete and identical.
+- [ ] Render output does not depend on random, clock, locale, or timezone state.

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

@@ -50,13 +50,13 @@ const wx = (() => { const 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 }` —
+under `.agents/skills/wix-base44-connector/tmp/` 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
+across everything saved: `grep -rn 'term' .agents/skills/wix-base44-connector/tmp/`), 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
+never saved** — 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
@@ -74,13 +74,21 @@ An empty report = bad token, never an empty site.
 
 ```js
 // know the product? browse is deterministic — menuUrl alone orients (children + counts);
-// filter before listing methods, unfiltered listings clip
+// 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.
 await wx.browse("https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings",
                 { include: ["METHOD"], filter: "resched", depth: 4 });
+// non-REST portal — same call, that portal's menu URL:
+await wx.browse("https://dev.wix.com/docs/go-headless/authentication", { depth: 2 });
 
 // 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" });
 ```
 
 Go deeper for fields, enums, or absence — only the spec index proves absence.
@@ -102,29 +110,39 @@ return wx.bash(`sed -n '/^## REST API/,/^## JavaScript SDK/p' ${pg.path} | grep
 `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
+### The spec index — a located method's exact schema
 
-Answers questions about pages you already found — arrive with a `docsUrl`, match by it. Also the
-only proof an API does NOT exist:
+Read the schema of a method you already have a `docsUrl` for (from search/browse):
 
 ```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
+  const url = "<docsUrl from search/browse>";           // API method page, not a skill/article page
+  const s = await getResourceSchemaByUrl(url);
+  const m = s.methods.find(x => x.docsUrl === url);
+  return {
+    call: m.publicUrl,                                       // callable https://www.wixapis.com/… URL
+    body: m.requestBody?.content["application/json"].schema.properties,
+    responses: m.responses,
+    filterable: m.queryMethodData?.queryFieldsCapabilitiesMap      // query methods
+             || m.searchMethodData?.searchFieldsCapabilitiesMap,   // search methods
+    example: m.legacyExamples?.[0]?.content,
+  };
+  // { $circular: "<name>" } types resolve via s.components.schemas["<name>"] — complete in this call
 `);
-// 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>"]
 ```
 
+`filterable` maps each field to its allowed operators + sort — filter server-side only on what it
+lists, else filter in code.
+
 ### Management recipes — check before composing admin flows
 
-~100 curated multi-step recipes (install apps, seed catalogs, set up whole verticals):
+~100 curated multi-step management (admin) flows across 23 categories — the largest are
+ecommerce (24), bookings (13), stores (9), cms (7), google-ads (7), sites (7), contacts (5),
+then get-paid, marketing, pricing-plans, events, blog, forms, restaurants, domains, media, …:
 
 ```js
-await wx.recipes();           // categories with counts
-await wx.recipes("stores");   // a category's list — or any task word: wx.recipes("coupon")
+await wx.mgmtRecipes();           // categories with counts
+await wx.mgmtRecipes("stores");   // a category's list — or any task word: wx.mgmtRecipes("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
 ```
@@ -167,7 +185,6 @@ const mint = async (body) => {
 };
 // 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" } });
 ```