npm - @wix/agent-skills - Versions diffs - 1.18.0 → 1.18.1 - Mend

@wix/agent-skills 1.18.0 → 1.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md CHANGED Viewed

@@ -1,32 +1,26 @@
 # Wix Editor React Component Builder
-Build Editor React Components for Harmony Editor and Studio2 in Wix CLI
-applications. These components are not supported in other Wix editors.
-## Before You Start
-Determine whether the request creates a component or edits an existing one.
-Inspect the existing component before changing it.
+Build Editor React Components for Harmony/Studio2 Wix CLI apps only. First
+determine **create vs edit**; for edits, inspect the existing component and
+never re-scaffold.
 ## File Contract
 Use the Wix CLI scaffold as the source of truth. Do not replace it with a custom
-layout or a hand-written manifest. After applying this workflow, preserve these
-file responsibilities:
+layout or a hand-written manifest. Preserve these file responsibilities:
 | File | Ownership | Purpose |
 | --- | --- | --- |
-| `<component-name>.props.ts` | Edit | Export the props type and `defaultProps` from one shared source. |
-| `<component-name>.tsx` | Edit | Implement the component UI and behavior. |
-| `<component-name>.module.css` | Edit | Define scoped component styles. |
-| `component.tsx` | Keep generated | Wire the component and `defaultProps` with `withDefaults`. |
-| `component.preview.tsx` | Edit narrowly | Keep generated wrappers; sync the preview adapter, one crucial data field, and root class. |
-| `<component-name>.generated.ts` | NEVER edit | Generated manifest consumed by the editor. |
-| `<component-name>.extension.ts` | Edit narrowly | Apply supported partial manifest overrides. |
-Supplementary files such as `constants.ts`, hooks, or internal sub-components
-are allowed when the implementation needs them. Keep the scaffolded files and
-their responsibilities intact.
+| `<component-name>.props.ts` | Edit | Props type + `defaultProps` |
+| `<component-name>.tsx` | Edit | Component UI and behavior |
+| `<component-name>.module.css` | Edit | Scoped component styles |
+| `component.tsx` | Keep generated | Wire component and `defaultProps` with `withDefaults` |
+| `component.preview.tsx` | Edit narrowly | Sync preview adapter, one crucial data field, root class |
+| `<component-name>.generated.ts` | NEVER edit | Generated manifest — do not edit |
+| `<component-name>.extension.ts` | Edit narrowly | Supported partial manifest overrides |
+Supplementary files (constants, hooks, sub-components) are allowed; keep scaffold
+roles intact.
 ## Workflow
@@ -36,9 +30,8 @@ their responsibilities intact.
    npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description"}'
    ```
-   The command creates `src/extensions/site/components/<component-name>/` and
-   registers the extension in `src/extensions.ts`. Do not rerun it for an
-   existing component.
+   Creates `src/extensions/site/components/<component-name>/` and registers the
+   extension in `src/extensions.ts`. Do not rerun for an existing component.
 2. **Run the dependency preflight.** Verify that all component creation and
    accessibility-review dependencies are installed:
@@ -47,25 +40,23 @@ their responsibilities intact.
    node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y'];const missing=ps.filter(p=>!(require.resolve.paths(p)||[]).some(d=>fs.existsSync(path.join(d,p,'package.json'))));if(missing.length){console.error('Missing dependencies: '+missing.join(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; fi; }
    ```
-3. **Plan the contract and structure.** Identify content and behavior props,
-   elect the semantic root, identify named inner parts, and decide which design
-   states each part supports. Read the relevant references from the routing
-   table below before writing code.
+3. **Plan the contract and structure.** Identify props, semantic root, named
+   parts, and design states; read routed references below before writing code.
-4. **Implement the editable sources.** Preserve the scaffold contract. Keep
-   props/defaults in the props file, component logic in the main TSX file, and
-   static styling in the CSS Module. Do not edit `*.generated.ts`.
+4. **Implement the editable sources.** Preserve the scaffold contract: props in
+   the props file, logic in TSX, styles in the CSS Module. Do not edit
+   `*.generated.ts`.
 5. **Run the accessibility review.** Follow
-   [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md): run both bundled
-   scanners, triage their output, complete the manual semantic checklist, fix
-   confirmed issues, and rerun the scanners on changed JSX files.
+   [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md): run scanners,
+   triage output, complete the manual checklist, fix issues, rerun on changed
+   JSX.
 6. **Configure the editor extension when required.** For a new component or a
    requested sizing, installation, or manifest change, apply
    [`editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
    to `<component-name>.extension.ts`. Otherwise leave the file unchanged.
-   Finally, synchronize `requiredDataFields` and `rootClassName` in
+   Synchronize `requiredDataFields` and `rootClassName` in
    `component.preview.tsx`.
 7. **Generate and validate.** Run:
@@ -75,82 +66,71 @@ their responsibilities intact.
    npx tsc --noEmit
    ```
-   Run relevant project tests and lint commands when available. Inspect the
-   regenerated manifest; never repair it by hand. Design-state generation needs
-   `@wix/cli` 1.1.210 or newer, and prop-triggered `ElementState` generation
-   needs 1.1.215 or newer. If expected states are absent on an older CLI, report
-   the version constraint and let the user decide whether to upgrade. If the
-   build or manifest command exits with an error, diagnose it with
-   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md), apply the
-   matching fix, and rerun both commands.
+   Run relevant tests and lint when available. Inspect the regenerated manifest;
+   never repair it by hand. On failure, diagnose with
+   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 8. **Report the result.** Summarize edited files and checks. Call out any
-   unresolved instruction conflict, missing dependency, unsupported CLI
-   version, or check that could not run.
+   unresolved conflict, missing dependency, unsupported CLI version, or check
+   that could not run.
 ## Reference Policy
-Read every reference required for the current scope. Read an optional reference
-only when its trigger applies; when it does, that reference becomes required.
-Apply every matching row; do not load the entire reference set by default.
+- Read **only** matching required + triggered optional rows; optional triggers
+  become required when they match.
+- References refine the active step; they do not restart workflow or expand scope.
+- Never re-scaffold an existing component or edit `*.generated.ts`.
-References refine the active workflow step; they do not restart the workflow or
-expand the user's requested scope. `SKILL.md` is the only reference router;
-reference files are self-contained leaves and do not route to other references.
-For an existing component, preserve out-of-scope public props, styling,
-extension configuration, and supporting files. Never re-scaffold an existing
-component or edit `*.generated.ts` as a reference-driven fix.
+`SKILL.md` is the only reference router; reference files are self-contained
+leaves. For existing components, preserve out-of-scope public props, styling,
+extension configuration, and supporting files.
 ### Required References
 | Scope | Required references |
 | --- | --- |
-| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), and [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
-| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md) and [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
-| Changing the public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), and [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
-| Changing public data props or the elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| Creating or changing an item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), and [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
+| Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
+| Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
 | Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
-| Changing the root direction contract, direction-sensitive behavior, or a `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
-| Changing sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+| Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
+| Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
 ### Optional References
 | Trigger | Read |
 | --- | --- |
-| An interactive or selectable part is created or changed—for example a button, link, input, tab, accordion trigger, or carousel control—or a custom state is added | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Public event callbacks are added or changed | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
-| Browser APIs, effects, or time-dependent output are introduced | [`SSR.md`](editor-react-component/SSR.md) |
-| A CSS feature or DOM API that is not clearly long-established is introduced, or the user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
+| Interactive/selectable part or custom state | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Public event callbacks added or changed | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
+| Browser APIs, effects, or time-dependent output | [`SSR.md`](editor-react-component/SSR.md) |
+| Non-established CSS feature or DOM API, or user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
 | `npx wix build` or manifest generation exits with an error | [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md) |
-| Primary content is playable, looped, or autoplaying | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) and [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| Runtime site pages, URLs, JavaScript direction, or reduced-motion context is needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) |
-| Non-animation behavior must differ in editor design mode | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) and [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| The prompt explicitly requests a branded, themed, or brand-aware component | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
+| Animation, video, carousel, or other playable/looped/autoplaying content | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Site/runtime/editor context hooks needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) (+ [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) when design-mode behavior differs) |
+| Branded, themed, or brand-aware component requested | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
-## Core Invariants
+## Non-Negotiables
-- Use React 18-compatible APIs; do not assume React 19 runtime features.
+- React 18 only; do not assume React 19 runtime features.
 - Include typed `id`, `className`, `direction`, and `a11y` support.
-- Apply `dir={direction}` and the unconditional fallback-direction class to the
-  elected root. Use logical CSS properties for direction-sensitive layout.
-- Keep render output deterministic and avoid browser globals during render.
-- Use only Baseline Widely Available CSS features and DOM APIs, or ones that
-  fall back to them. When a design needs a feature that is not, build the
-  supported alternative.
-- Route ARIA through the typed `a11y` contract; do not add one-off ARIA props.
-- Give every named inner part a global class, a CSS Module class, and a matching
-  `elementProps` entry. The elected root uses top-level props instead.
-- Pair each eligible native editor design-state selector with its
-  editor-injected global modifier. Keep a non-input control's keyboard-only
-  `:focus-visible` indicator standalone unless editable focus styling is
-  explicitly requested. Toggle custom global state classes from data.
-- For an item array where only one body is visible, give every item a `name`,
-  use `ActiveItemIndex<'arrayPropName'>`, render every body, and hide inactive
-  bodies accessibly.
-- If primary content autoplays or loops, provide an accessible play/pause
-  control, honor reduced motion, and suppress autoplay in editor design mode.
-- In `component.preview.tsx`, keep `withDefaults` and `withFallbackPlaceholder`,
-  wrap the preview adapter when present, normally put
-  only the one data prop crucial to meaningful rendering in
-  `requiredDataFields`, and match `rootClassName` to the root global class.
+- Elected root: `dir={direction}`, fallback-direction class, logical CSS for
+  direction-sensitive layout.
+- Deterministic render; no browser globals during render.
+- Explicit foreground colors need a known contrasting background; transparent
+  roots inherit from the host.
+- Baseline Widely Available CSS/DOM only, or supported fallbacks.
+- Route ARIA through `a11y`; no one-off ARIA props.
+- Named parts: global class, module class, and `elementProps` (root uses
+  top-level props).
+- Native design states: pair selectors with injected modifiers; keep non-input
+  `:focus-visible` standalone unless editable focus is requested; toggle custom
+  state classes from data.
+- Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
+  all bodies, hide inactive accessibly.
+- Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
+  editor design mode.
+- `component.preview.tsx`: keep `withDefaults` and `withFallbackPlaceholder`,
+  wrap the preview adapter when present, one crucial `requiredDataFields`
+  entry, and `rootClassName` matching the root global class.

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

@@ -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-headless/references/inline-recipes/setup-forms.md CHANGED Viewed

@@ -71,12 +71,25 @@ exhaust the site's form allowance (read it from
 [List Forms Providers Configs](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms-providers-configs)),
 which is also why you must **never create throwaway forms to probe the shape.**
+> **⚠️ `providers-config` tells you which namespaces the site can create in — NOT its limits.** A
+> provider app declares `restrictions` **once, for all sites**, in its app dashboard; the Wix Forms
+> app separately derives the site's real form/field/step limits from its **premium plan** and
+> enforces them on every create. (A missing `restrictions` means default platform limits, not
+> unlimited.) That is why free and unpublished sites report `maxFields: 150` / `maxForms: 150` here
+> while the create rejects with `Field count reached its limit of 10` and
+> `Steps count reached its limit of 3`. **The create call is the only authority** — when it returns
+> a count error, go to "Plan gates" below.
 ### STEP 2: Create each form schema
 **One POST per form** to `https://www.wixapis.com/form-schema-service/v4/forms`. How many forms, and
 each form's fields and labels, come from the request you're fulfilling; this step gives the call and
 the required format. Forms are independent (no shared revision), so concurrent creates are safe.
+**Every body carries `"namespace": "wix.form_app.form"`** — the same literal the reads below take as
+their required `?namespace=`. A form created under anything else is reachable over the API and
+invisible in the dashboard and Editor.
 **⚠️ Generate every `id` in the shell as a lowercase UUID v4 — never type one from memory**
 (`uuidgen | tr 'A-Z' 'a-z'`). Supply them at create rather than omitting them: `steps` must
 reference each field by `fieldId` in the same request.
@@ -96,9 +109,18 @@ step unless the request needs multiple pages.
 beside `target`/`inputType`:
 ```jsonc
-"inputOptions": { "target": "full_name", "required": true, "inputType": "STRING",
-  "stringOptions": { "validation": {}, "componentType": "TEXT_INPUT",
-                     "textInputOptions": { "label": "Full Name", "showLabel": true } } }
+"inputOptions": {
+  "target": "first_name",
+  "required": true,                                    // HERE — beside target/inputType
+  "pii": true,
+  "contactMapping": { "contactField": "FIRST_NAME" },  // per field; this is what creates the contact
+  "inputType": "STRING",
+  "stringOptions": {
+    "validation": {},                                  // always present, even empty — never `required`
+    "componentType": "TEXT_INPUT",
+    "textInputOptions": { "label": "First name", "showLabel": true }
+  }
+}
 ```
 A `required` key inside `stringOptions.validation` — or any `<inputType>Options.validation`, since no
@@ -126,12 +148,21 @@ surface in the dashboard or on the first real submission.
 Three plan-tier limits return a real `400` on create. **Do not work around any of them; tell the user
 to reduce or upgrade.**
-- **`FIELDS_COUNT_RESTRICTIONS_ERROR`** — the form exceeds the plan's per-form field cap. **Do NOT
-  split the form into multiple schemas** to dodge it. Reduce the field count, or upgrade.
+- **Field count — two caps, counting different things.** `Field count reached its limit of N` is the
+  **premium** cap the Wix Forms app enforces from the site's plan, and it counts **`INPUT` fields
+  only** (display elements and the `SUBMIT_BUTTON` don't count). `FORM_FIELDS_COUNT_EXCEEDED` /
+  `FIELDS_COUNT_RESTRICTIONS_ERROR` is the schema-service cap, which counts **every** field
+  including display elements. **Do NOT split the form into multiple schemas** to dodge either — that
+  trades one submission record for several and consumes more of the site's form allowance. Reduce
+  the field count, or upgrade.
+- **`Steps count reached its limit of N`** — the premium cap on `steps.length`. Collapse the form
+  into fewer pages, or upgrade. Conditions (`formRules`) are capped the same way. Neither has a
+  schema-service equivalent, so neither appears in the Create Form error table.
 - **`FILE_UPLOAD_RESTRICTIONS_ERROR`** — a file upload, signature, or payment field on a plan below
   Core. **Do NOT suggest inlining files as base64** — it stores no real file, gives the owner nothing
   usable, and blows past submission size limits. Drop the field, or upgrade.
-- **`FORMS_COUNT_RESTRICTIONS_ERROR`** — the site hit its plan's total-form cap. Upgrade, or free a
+- **`FORMS_COUNT_RESTRICTIONS_ERROR`** / **`NAMESPACE_FORMS_COUNT_EXCEEDED`** (and
+  `NAMESPACE_DELETED_FORMS_COUNT_EXCEEDED` for the trash bin) — the site hit its plan's total-form cap. Upgrade, or free a
   slot (STEP 1's list-then-delete — but only delete forms that are clearly install sample data; ask
   before deleting anything that could be the owner's real form).
@@ -167,10 +198,19 @@ A `200` on create is not proof the form is queryable or that the dashboard will
    `formSummary.fields` is NON-EMPTY**, with a count equal to **every input field you sent** (i.e.
    `formFields[]` minus the `SUBMIT_BUTTON`). A 6-input form returns all 6 — **including non-contact
    `DROPDOWN` and `TEXT_AREA` fields** — so do *not* expect only the contact-mapped ones. This is
-   the reliable dashboard-truth check: the summary returns exactly the fields the Wix dashboard
-   shows. A `summary.fields: []`, or a count short of your inputs, means the form renders blank (or
-   partly blank) for the owner even though the public site submits fine — **do not report success;
-   fix the `identifier`s and re-create.**
+   the dashboard-truth check for *placement*. A `summary.fields: []`, or a count short of your
+   inputs, means the form renders blank (or partly blank) for the owner even though the public site
+   submits fine — **do not report success; fix the layout placement or the GUID casing and
+   re-create.**
+   **⚠️ This step does NOT prove the `identifier`s are right, so check them in step 1.** An
+   unrecognized `identifier` is accepted and stored: it comes back in `formFields[]` and accepts
+   submissions, so every API-level check passes — but the **Wix Forms editor cannot render a field
+   it doesn't recognize**, so the owner can't see or edit it, and a form built entirely from
+   invented identifiers opens **empty** in the editor. Whether such a field is also omitted from
+   `formSummary.fields` is unverified, so don't rely on this count to catch it. Assert every
+   returned `formFields[].identifier` against the known values in About Form Fields — a plain string
+   comparison, no extra call.
 3. **⚠️ If the form has a multi-choice ARRAY field (`CHECKBOX_GROUP` / `TAGS`), the two checks above
    are NOT enough — send one real `createSubmission`.** A malformed `arrayOptions.validation.items`
@@ -201,9 +241,16 @@ To change a form the request has since revised — add a field, relabel one, tig
 [Update Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form):
 ```
+GET   https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}
 PATCH https://www.wixapis.com/form-schema-service/v4/forms/{formId}
+{ "form": { …the whole object you just read, with your change…, "revision": "<its current revision>" } }
 ```
+**Read the form back first** — the `PATCH` needs its current `revision`, and `formFields` is replaced
+wholesale (anything missing from the array you send moves to `deletedFormFields`), so the read-back
+*is* the body. The read needs the **required** `?namespace=wix.form_app.form`; without it it `400`s
+with `namespace must not be empty` — a violation naming a field, so it misreads as a body problem.
 **Prefer updating over delete-and-recreate.** An update keeps the `formId` the handoff already
 carries and consumes no additional slot against the site's form cap. **Re-run STEP 3 after any update**
 — it can regress the layout or the dashboard summary exactly as a create can.