@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/forms-and-interactions.md

@@ -1,245 +1,245 @@
----
-title: "Forms and interactions"
-description: "Attaching, publishing and verifying forms, and interactive sections: menus, accordions, modals and consent."
----
-
-# Forms and interactive components
-
-**Outcome.** Interactive sections keep working after componentization, and editors change the
-intended content without touching unsafe implementation controls.
-
-Doctrine: `new_form` prompt, `CM-72`. Component props and slots: [components.md](components.md)
-(its §1 shows where a `form` prop actually renders).
-
-## Contents
-
-- [Inventory behaviour](#inventory-behaviour) · [Pattern contracts](#pattern-contracts)
-- [Forms: the rules](#forms-the-rules) · [Editor UX](#editor-ux) · [Acceptance](#acceptance)
-- Forms as code: [pipeline](#1-pipeline) · [field types](#2-field-types-and-server-checks) ·
-  [MCP versus dashboard](#3-mcp-versus-dashboard) · [self-hosted wiring](#4-wiring-a-self-hosted-site) ·
-  [per-rung facts](#5-per-rung-facts) · [traps](#6-traps)
-
-## Inventory behaviour
-
-For each interaction record its markup, state management, dependencies, events, destinations,
-responsive behaviour, accessibility semantics and persistence. Then sort what it exposes:
-
-- **Content-configurable:** labels, headings, body, images, links, items, variants.
-- **Behaviour-configurable:** a closed choice such as initial open state, autoplay, modal
-  size, display frequency, or which form.
-- **Code-owned:** search algorithms, authentication, payments, booking, complex validation,
-  server actions, experiments.
-
-Code-owned behaviour never becomes a free text field, and never a promise that editors can
-change it safely.
-
-## Pattern contracts
-
-| Pattern | Editor model | Runtime checks |
-|---|---|---|
-| Navigation / mobile menu | global layout component; repeatable link groups; logo; explicit CTA | keyboard and touch, focus return, active route, breakpoint, skip link |
-| Accordion / FAQ | one section with a repeatable Question + narrowed rich-text Answer | button trigger, `aria-expanded`, panel association, focus, single or multi open |
-| Tabs | repeatable label + panel, or a nested component per panel when layouts differ | stable ids, arrow-key navigation, selected state, responsive fallback |
-| Modal / dialog | trigger + modal content in a slot or section; size as a variant | focus trap, Escape, focus return, scroll lock, accessible name, reduced motion |
-| Pop-up / promo bar | sitewide or page component; message, CTA, variant, closed display rules | frequency and dismiss persistence, mobile layout, consent |
-| Carousel | repeatable items or nested slides; limited motion controls | pause, keyboard, announcements, reduced motion, no hidden content loss |
-| Cookie consent | global component with policy links and category labels | consent storage, script gating, change-choice path; legal settings need owner review |
-| Search / filter | labels and options editable; query and index logic code-owned | empty, loading and error states, URL state, keyboard, result accuracy |
-
-For a complex one-off component, keep the working code and expose only an intentional prop
-contract. A nested child is edited through a `slot` prop or its own instance; the edit must
-address the child instance, never the parent definition. A `slot` holds one nested
-component, or a list of them with `config.multiple`; a fixed set of different children is the
-section's ordered children. A write that would nest a component inside itself is refused
-(`component_cycle`).
-
-## Forms: the rules
-
-Detect each form's fields, labels, types, required states, validation, consent copy, spam
-controls, endpoint, uploads, confirmation and error states, notifications and integrations.
-
-- **A form is a Form document, and a section references it.** Create it as a draft
-  (`create_form`) and place it with a `form` block `{ formId }` inside a section. To make WHICH
-  form editable per placement, declare a `form` prop on the component targeting that block's
-  `props`. The prop stores `{ formId }` and nothing else: never re-model the questions as
-  component props, or the same fields live in two places and drift at the first edit.
-- **Draft until published.** A draft form renders nothing live and every public submission is
-  refused with 403. Publish it with `publish_form` (it needs the publish permission) only after
-  its destination and consent behaviour are tested.
-- **Spam controls** are per form: Turnstile on or off and a honeypot field name. The Turnstile
-  secret key is dashboard-only.
-- **Self-hosted renderers** render only forms whose `status` is `"published"` and post to
-  `${apiUrl}/api/v1/forms/public/:formId/submissions` through the SDK's `submitForm`, never to the
-  forms worker directly and never with an API key in the browser.
-- **Integrations** are configured in the dashboard. A submission classified as spam is stored
-  and triggers none of them.
-
-Classify each form:
-
-1. **Native:** BetterCMS owns fields, validation, submissions and delivery.
-2. **Connected provider:** BetterCMS owns the presentation or the reference; a provider owns
-   delivery. Keep provider ids; the owner sets up the credentials.
-3. **Custom action:** keep the existing code path until an adapter passes the same tests.
-
-A form rendering is not a working integration. Require a test submission that shows the
-expected record (`list_form_submissions`), the notification, the failure state, spam handling
-and consent handling.
-
-## Editor UX
-
-Label fields the way editors think: `Question`, `Answer`, `Add FAQ item`; `Open modal`,
-`Modal title`, `Modal body`, `Close label`. CSS selectors, callbacks, endpoint URLs and secret
-keys stay out of editor fields. Expose curated variants and behaviour switches whose effect is
-obvious. An empty optional field should remove its element cleanly.
-
-## Acceptance
-
-- Interactions work with keyboard, touch, screen-reader semantics, mobile layouts and reduced
-  motion where relevant.
-- Editing a label, body or item changes the intended instance without breaking its state.
-- Nested elements keep their order, ids and edit scope.
-- Every form is `draft`, `ready for verification` or `verified live`; only the last has an
-  end-to-end submission receipt.
-- Consent-dependent scripts do not run before consent is given.
-
-## Forms as code
-
-The pipeline with the code that enforces each hop.
-
-### 1. Pipeline
-
-| # | Hop | Code |
-|---|---|---|
-| 1 | Define: `create_form` / `update_form`, or the dashboard. Postgres `forms` row, `status` defaults to `draft` | `packages/db/src/schema/forms.ts:35` |
-| 2 | Publish: `publish_form`, or the dashboard Forms tab. Both need publish permission | `src/routes/management/forms.ts:276`, `src/routes/admin/forms.ts:529`, `:530` |
-| 3 | Place: a `form` block `{ formId }` inside a section | `packages/types/src/block.ts:253`, `:257` |
-| 4 | Render: hosted renderer, Next `BcmsForm`, or Astro `BcmsForm.astro` | `packages/next/src/form.tsx:74` |
-| 5 | Submit: `POST /api/v1/forms/public/:formId/submissions` with `{ data, "cf-turnstile-response"? }` | `src/routes/delivery/forms-public.ts:48`, `src/lib/validation/schemas/forms.ts:297`, `:298` |
-| 6a | Ingress: rate limit per client IP (10), before anything else | `src/routes/delivery/forms-public.ts:61`, `src/lib/forms/submit-gate.ts:23` |
-| 6b | Ingress: form lookup, 404 when missing; draft form, 403 | `src/routes/delivery/forms-public.ts:65`, `:71` |
-| 6c | Ingress: Turnstile; 403 on a failed token; skipped when not configured | `src/routes/delivery/forms-public.ts:80`, `:89` |
-| 6d | Ingress: field validation, 400 `{ code: "FORM_FIELD_INVALID", errors, issues }` | `src/lib/forms/submit-gate.ts:75` |
-| 6e | Ingress: spam classification (honeypot) | `src/lib/forms/spam.ts:40` |
-| 6f | Ingress: rate limit per workspace (100 per 60 s), one bucket shared with the API-key route | `src/lib/forms/submit-gate.ts:80` |
-| 7 | Store: forms worker writes the submission to D1 (`FORMS_DB`); CRM intents to `crm_intents` | `workers/bcms-forms-worker/src/index.ts:2`, `workers/bcms-forms-worker/migrations/0004_crm_intents.sql:1` |
-| 8 | Inbox side effects (non-spam only): contact upsert, integrations, notification | `src/routes/delivery/forms-public.ts:120`, `:144`, `:158` |
-| 9 | CRM delivery drain: `POST /api/v1/internal/crm/drain` | `src/index.ts:976`, `src/routes/internal/crm.ts:4` |
-| 10 | Read: `list_form_submissions`, dashboard inbox | `packages/mcp/src/tools.ts:1600` |
-
-### 2. Field types and server checks
-
-Thirteen input types exist (`src/lib/validation/schemas/forms.ts`), plus `step`, a divider. No file upload.
-
-| Type | The server checks |
-|---|---|
-| `email` | Address shape; optional `emailPolicy: "business"` rule |
-| `number` | Numeric; optional `min` / `max` rules |
-| `select`, `radio`, `checkboxes` | Value is one of the listed options; a field saved with an empty options list accepts nothing |
-| `consent` | Must be truthy |
-| `phone` | Digits, spaces, `+ ( ) -`; stricter with `phoneFormat: "e164"` |
-| `text` / `textarea` | At most 1000 / 10000 characters; optional `pattern` rule |
-| `url` | Starts with `http://` or `https://` |
-| `date` | `YYYY-MM-DD` |
-| `checkbox`, `hidden` | Nothing beyond `required` |
-| `step` | Nothing: a divider is never required and never submitted; a value sent under its key is refused with rule `step` |
-
-Any field with `required` is checked for presence. Every value must be a plain value or a flat
-list of them; a nested object is refused with rule `scalar`. Each refusal is
-`FORM_FIELD_INVALID` with `issues: [{ field, rule, message }]`. Keys that are not fields are not
-refused.
-
-The API-key submit route runs the same validation, spam check and workspace limit, but no per-IP
-limit (`src/routes/delivery/forms.ts:106`).
-
-Definition refusals (`create_form` / `update_form`) carry `FORM_DEFINITION_INVALID`: duplicate or
-over-long keys, too many fields or options, and a `showIf` that names a field not on the form.
-That last one is refused on create and kept as sent on update.
-
-Rules:
-
-- Send only the form's field keys (plus the honeypot and Turnstile token), each as a plain value.
-- Read `issues[].field` and `issues[].rule` to fix a refused submission; retrying unchanged returns
-  the same refusal.
-
-#### Steps
-
-A multi-step form is one form with `step` fields in `fields`: `{ key, type: "step", label }` opens
-a page named `label`, and the fields before the first `step` are page 1. A step takes only `key`
-and `label` (`step_has_input_keys`), needs a field after it (`step_empty`), and a form has at most
-ten (`step_limit`). The visitor sees one page at a time with Back and Next, and the form posts
-once, at the end, as one submission whose body never carries a step key. Without JavaScript every
-page shows at once, as one long form. Map a source form's `fieldset` pages, or a "Next" button that
-only reveals the next group, to `step` fields; keep one `required` per real question, not per page.
-
-### 3. MCP versus dashboard
-
-| Operation | Where |
-|---|---|
-| List, read, create, update, delete forms | MCP: `list_forms`, `get_form`, `create_form`, `update_form`, `delete_form` |
-| Read and delete submissions | MCP: `list_form_submissions`, `delete_form_submission` |
-| Publish | MCP: `publish_form`. Unpublish: dashboard Forms tab |
-| Mark a derived form as not a form (a search box, a widget), or restore it | MCP: `update_form { ignored: true }` / `{ ignored: false }` |
-| Integrations (Google Sheets, Slack, webhook, email, HubSpot, Salesforce) | Dashboard |
-| Turnstile on/off, honeypot field name, notification emails | MCP: `create_form` / `update_form` (`turnstileEnabled`, `honeypotField`, `notifyEmails`). The Turnstile secret key: dashboard only; sending `turnstileSecretKey` through the API is refused with 403 `FORM_SECRET_DASHBOARD_ONLY` |
-
-`update_form` with `fields` replaces the whole array: send every field you want to keep.
-
-Setup imports two kinds of form already ignored, each kept as a restorable row: the site's own
-sign-in, register and password forms, and a shop's add-to-basket, buy-now or checkout form (it
-posts to the cart and asks only a quantity or a variant). Both stay the site's code. An imported
-form is named for what it is for: its `aria-label`, its one legend, a heading inside it or in its
-own band, else its purpose ("Newsletter signup", "Contact"). Rename it with `update_form` if the
-site calls it something else.
-
-**An imported form's words are edited in the form, and written into the built page.** On a new
-import, setup binds each part of the built `<form>` to its form row: field labels, placeholders,
-help lines, select and radio options, and the submit button's text. Change one with `update_form`
-(`fields[].label`, `placeholder`, `helpText`, `options`, or `submitLabel`) and the next content
-apply writes it into every built page that draws the form, with no rebuild. The built form
-carries the stamps:
-
-| Stamp | On | Says |
-|---|---|---|
-| `data-bcms-form-bound="<formId>"` | the `<form>` | Its parts are this form's. Never `data-bcms-form`: that one means the form posts to BetterCMS. |
-| `data-bcms-form-part` | a part | `label`, `help`, `option` or `submit`, as `BcmsForm` names them. |
-| `data-bcms-form-field="<key>"` | a part or a control | The field it belongs to. |
-| `data-bcms-form-value="form:<formId>:<path>"` | a part shown as text | The address written: `fields.<key>.label`, `fields.<key>.helpText`, `fields.<key>.options.<i>`, `submitLabel`. A placeholder is a `data-bcms-props` entry (`form:<formId>:fields.<key>.placeholder`). |
-
-Only words are written. The lane adds and removes no element and never touches `name`, `id`,
-`for`, `action`, `value`, a validation attribute or a hidden input, so the site's own script and
-endpoint keep working. An option added to the row has no element until the site's code is
-rebuilt, and is reported as not on the page. A fieldset's `<legend>` and an
-`<input type="submit">` stay the code's. A form setup ignored (sign-in, basket) and a form
-already wired with `data-bcms-form` take no stamp. The submit button belongs to the form: its
-text is `submitLabel`, never a page field.
-
-### 4. Wiring a self-hosted site
-
-- **Next**: `getForm('Name')` (or an id) reads the form from `bcms-content.json`; render
-  `<BcmsForm form={form} />`. It renders the honeypot input under the form's own
-  `honeypotField` name, reads the `cf-turnstile-response` token when a Turnstile widget is on the
-  page, and submits through the SDK `submitForm`.
-- **Astro**: `BcmsForm.astro` renders the same hidden honeypot input and sends
-  `cf-turnstile-response` when present.
-- Neither component checks `status`. Render a form only when `form.status === "published"`.
-- The honeypot name is per form. Never hardcode it; read `form.honeypotField`.
-
-### 5. Per-rung facts
-
-| Situation | Answer |
-|---|---|
-| `FORMS_WORKER_URL` set but blank on the API | 503 `FORMS_WORKER_NOT_CONFIGURED`. A blank never falls back to the default worker |
-| Worker without `FORMS_SHARED_SECRET` | 503 `FORMS_WORKER_SECRET_UNSET` on data routes |
-| No Turnstile secret for the form or env | Token not verified; the submission continues |
-| Rate-limit store unavailable | Limits allow the request |
-| Management delete of a submission not in that form | 404 `FORM_SUBMISSION_NOT_FOUND` |
-
-### 6. Traps
-
-| Symptom | Cause | Rule |
-|---|---|---|
-| Every submission 403 | Form still draft | Call `publish_form` |
-| Submissions 503 on a dev or preview API | Worker URL blank or worker secret unset | Report the code to the owner; do not change the site |
-| Lead stored but no contact, integration or notification | Classified as spam (honeypot filled); side effects run for inbox leads only | Keep the honeypot input hidden and empty |
-| Submission 400 `FORM_FIELD_INVALID` rule `scalar` | A field value sent as an object | Send plain values; checkboxes as a flat list |
-| Webhook integration never fires | Target is not a public http(s) host | Use a public https endpoint |
+---
+title: "Forms and interactions"
+description: "Attaching, publishing and verifying forms, and interactive sections: menus, accordions, modals and consent."
+---
+
+# Forms and interactive components
+
+**Outcome.** Interactive sections keep working after componentization, and editors change the
+intended content without touching unsafe implementation controls.
+
+Doctrine: `new_form` prompt, `CM-72`. Component props and slots: [components.md](components.md)
+(its §1 shows where a `form` prop actually renders).
+
+## Contents
+
+- [Inventory behaviour](#inventory-behaviour) · [Pattern contracts](#pattern-contracts)
+- [Forms: the rules](#forms-the-rules) · [Editor UX](#editor-ux) · [Acceptance](#acceptance)
+- Forms as code: [pipeline](#1-pipeline) · [field types](#2-field-types-and-server-checks) ·
+  [MCP versus dashboard](#3-mcp-versus-dashboard) · [self-hosted wiring](#4-wiring-a-self-hosted-site) ·
+  [per-rung facts](#5-per-rung-facts) · [traps](#6-traps)
+
+## Inventory behaviour
+
+For each interaction record its markup, state management, dependencies, events, destinations,
+responsive behaviour, accessibility semantics and persistence. Then sort what it exposes:
+
+- **Content-configurable:** labels, headings, body, images, links, items, variants.
+- **Behaviour-configurable:** a closed choice such as initial open state, autoplay, modal
+  size, display frequency, or which form.
+- **Code-owned:** search algorithms, authentication, payments, booking, complex validation,
+  server actions, experiments.
+
+Code-owned behaviour never becomes a free text field, and never a promise that editors can
+change it safely.
+
+## Pattern contracts
+
+| Pattern | Editor model | Runtime checks |
+|---|---|---|
+| Navigation / mobile menu | global layout component; repeatable link groups; logo; explicit CTA | keyboard and touch, focus return, active route, breakpoint, skip link |
+| Accordion / FAQ | one section with a repeatable Question + narrowed rich-text Answer | button trigger, `aria-expanded`, panel association, focus, single or multi open |
+| Tabs | repeatable label + panel, or a nested component per panel when layouts differ | stable ids, arrow-key navigation, selected state, responsive fallback |
+| Modal / dialog | trigger + modal content in a slot or section; size as a variant | focus trap, Escape, focus return, scroll lock, accessible name, reduced motion |
+| Pop-up / promo bar | sitewide or page component; message, CTA, variant, closed display rules | frequency and dismiss persistence, mobile layout, consent |
+| Carousel | repeatable items or nested slides; limited motion controls | pause, keyboard, announcements, reduced motion, no hidden content loss |
+| Cookie consent | global component with policy links and category labels | consent storage, script gating, change-choice path; legal settings need owner review |
+| Search / filter | labels and options editable; query and index logic code-owned | empty, loading and error states, URL state, keyboard, result accuracy |
+
+For a complex one-off component, keep the working code and expose only an intentional prop
+contract. A nested child is edited through a `slot` prop or its own instance; the edit must
+address the child instance, never the parent definition. A `slot` holds one nested
+component, or a list of them with `config.multiple`; a fixed set of different children is the
+section's ordered children. A write that would nest a component inside itself is refused
+(`component_cycle`).
+
+## Forms: the rules
+
+Detect each form's fields, labels, types, required states, validation, consent copy, spam
+controls, endpoint, uploads, confirmation and error states, notifications and integrations.
+
+- **A form is a Form document, and a section references it.** Create it as a draft
+  (`create_form`) and place it with a `form` block `{ formId }` inside a section. To make WHICH
+  form editable per placement, declare a `form` prop on the component targeting that block's
+  `props`. The prop stores `{ formId }` and nothing else: never re-model the questions as
+  component props, or the same fields live in two places and drift at the first edit.
+- **Draft until published.** A draft form renders nothing live and every public submission is
+  refused with 403. Publish it with `publish_form` (it needs the publish permission) only after
+  its destination and consent behaviour are tested.
+- **Spam controls** are per form: Turnstile on or off and a honeypot field name. The Turnstile
+  secret key is dashboard-only.
+- **Self-hosted renderers** render only forms whose `status` is `"published"` and post to
+  `${apiUrl}/api/v1/forms/public/:formId/submissions` through the SDK's `submitForm`, never to the
+  forms worker directly and never with an API key in the browser.
+- **Integrations** are configured in the dashboard. A submission classified as spam is stored
+  and triggers none of them.
+
+Classify each form:
+
+1. **Native:** BetterCMS owns fields, validation, submissions and delivery.
+2. **Connected provider:** BetterCMS owns the presentation or the reference; a provider owns
+   delivery. Keep provider ids; the owner sets up the credentials.
+3. **Custom action:** keep the existing code path until an adapter passes the same tests.
+
+A form rendering is not a working integration. Require a test submission that shows the
+expected record (`list_form_submissions`), the notification, the failure state, spam handling
+and consent handling.
+
+## Editor UX
+
+Label fields the way editors think: `Question`, `Answer`, `Add FAQ item`; `Open modal`,
+`Modal title`, `Modal body`, `Close label`. CSS selectors, callbacks, endpoint URLs and secret
+keys stay out of editor fields. Expose curated variants and behaviour switches whose effect is
+obvious. An empty optional field should remove its element cleanly.
+
+## Acceptance
+
+- Interactions work with keyboard, touch, screen-reader semantics, mobile layouts and reduced
+  motion where relevant.
+- Editing a label, body or item changes the intended instance without breaking its state.
+- Nested elements keep their order, ids and edit scope.
+- Every form is `draft`, `ready for verification` or `verified live`; only the last has an
+  end-to-end submission receipt.
+- Consent-dependent scripts do not run before consent is given.
+
+## Forms as code
+
+The pipeline with the code that enforces each hop.
+
+### 1. Pipeline
+
+| # | Hop | Code |
+|---|---|---|
+| 1 | Define: `create_form` / `update_form`, or the dashboard. Postgres `forms` row, `status` defaults to `draft` | `packages/db/src/schema/forms.ts:35` |
+| 2 | Publish: `publish_form`, or the dashboard Forms tab. Both need publish permission | `src/routes/management/forms.ts:276`, `src/routes/admin/forms.ts:529`, `:530` |
+| 3 | Place: a `form` block `{ formId }` inside a section | `packages/types/src/block.ts:253`, `:257` |
+| 4 | Render: hosted renderer, Next `BcmsForm`, or Astro `BcmsForm.astro` | `packages/next/src/form.tsx:74` |
+| 5 | Submit: `POST /api/v1/forms/public/:formId/submissions` with `{ data, "cf-turnstile-response"? }` | `src/routes/delivery/forms-public.ts:48`, `src/lib/validation/schemas/forms.ts:297`, `:298` |
+| 6a | Ingress: rate limit per client IP (10), before anything else | `src/routes/delivery/forms-public.ts:61`, `src/lib/forms/submit-gate.ts:23` |
+| 6b | Ingress: form lookup, 404 when missing; draft form, 403 | `src/routes/delivery/forms-public.ts:65`, `:71` |
+| 6c | Ingress: Turnstile; 403 on a failed token; skipped when not configured | `src/routes/delivery/forms-public.ts:80`, `:89` |
+| 6d | Ingress: field validation, 400 `{ code: "FORM_FIELD_INVALID", errors, issues }` | `src/lib/forms/submit-gate.ts:75` |
+| 6e | Ingress: spam classification (honeypot) | `src/lib/forms/spam.ts:40` |
+| 6f | Ingress: rate limit per workspace (100 per 60 s), one bucket shared with the API-key route | `src/lib/forms/submit-gate.ts:80` |
+| 7 | Store: forms worker writes the submission to D1 (`FORMS_DB`); CRM intents to `crm_intents` | `workers/bcms-forms-worker/src/index.ts:2`, `workers/bcms-forms-worker/migrations/0004_crm_intents.sql:1` |
+| 8 | Inbox side effects (non-spam only): contact upsert, integrations, notification | `src/routes/delivery/forms-public.ts:120`, `:144`, `:158` |
+| 9 | CRM delivery drain: `POST /api/v1/internal/crm/drain` | `src/index.ts:976`, `src/routes/internal/crm.ts:4` |
+| 10 | Read: `list_form_submissions`, dashboard inbox | `packages/mcp/src/tools.ts:1600` |
+
+### 2. Field types and server checks
+
+Thirteen input types exist (`src/lib/validation/schemas/forms.ts`), plus `step`, a divider. No file upload.
+
+| Type | The server checks |
+|---|---|
+| `email` | Address shape; optional `emailPolicy: "business"` rule |
+| `number` | Numeric; optional `min` / `max` rules |
+| `select`, `radio`, `checkboxes` | Value is one of the listed options; a field saved with an empty options list accepts nothing |
+| `consent` | Must be truthy |
+| `phone` | Digits, spaces, `+ ( ) -`; stricter with `phoneFormat: "e164"` |
+| `text` / `textarea` | At most 1000 / 10000 characters; optional `pattern` rule |
+| `url` | Starts with `http://` or `https://` |
+| `date` | `YYYY-MM-DD` |
+| `checkbox`, `hidden` | Nothing beyond `required` |
+| `step` | Nothing: a divider is never required and never submitted; a value sent under its key is refused with rule `step` |
+
+Any field with `required` is checked for presence. Every value must be a plain value or a flat
+list of them; a nested object is refused with rule `scalar`. Each refusal is
+`FORM_FIELD_INVALID` with `issues: [{ field, rule, message }]`. Keys that are not fields are not
+refused.
+
+The API-key submit route runs the same validation, spam check and workspace limit, but no per-IP
+limit (`src/routes/delivery/forms.ts:106`).
+
+Definition refusals (`create_form` / `update_form`) carry `FORM_DEFINITION_INVALID`: duplicate or
+over-long keys, too many fields or options, and a `showIf` that names a field not on the form.
+That last one is refused on create and kept as sent on update.
+
+Rules:
+
+- Send only the form's field keys (plus the honeypot and Turnstile token), each as a plain value.
+- Read `issues[].field` and `issues[].rule` to fix a refused submission; retrying unchanged returns
+  the same refusal.
+
+#### Steps
+
+A multi-step form is one form with `step` fields in `fields`: `{ key, type: "step", label }` opens
+a page named `label`, and the fields before the first `step` are page 1. A step takes only `key`
+and `label` (`step_has_input_keys`), needs a field after it (`step_empty`), and a form has at most
+ten (`step_limit`). The visitor sees one page at a time with Back and Next, and the form posts
+once, at the end, as one submission whose body never carries a step key. Without JavaScript every
+page shows at once, as one long form. Map a source form's `fieldset` pages, or a "Next" button that
+only reveals the next group, to `step` fields; keep one `required` per real question, not per page.
+
+### 3. MCP versus dashboard
+
+| Operation | Where |
+|---|---|
+| List, read, create, update, delete forms | MCP: `list_forms`, `get_form`, `create_form`, `update_form`, `delete_form` |
+| Read and delete submissions | MCP: `list_form_submissions`, `delete_form_submission` |
+| Publish | MCP: `publish_form`. Unpublish: dashboard Forms tab |
+| Mark a derived form as not a form (a search box, a widget), or restore it | MCP: `update_form { ignored: true }` / `{ ignored: false }` |
+| Integrations (Google Sheets, Slack, webhook, email, HubSpot, Salesforce) | Dashboard |
+| Turnstile on/off, honeypot field name, notification emails | MCP: `create_form` / `update_form` (`turnstileEnabled`, `honeypotField`, `notifyEmails`). The Turnstile secret key: dashboard only; sending `turnstileSecretKey` through the API is refused with 403 `FORM_SECRET_DASHBOARD_ONLY` |
+
+`update_form` with `fields` replaces the whole array: send every field you want to keep.
+
+Setup imports two kinds of form already ignored, each kept as a restorable row: the site's own
+sign-in, register and password forms, and a shop's add-to-basket, buy-now or checkout form (it
+posts to the cart and asks only a quantity or a variant). Both stay the site's code. An imported
+form is named for what it is for: its `aria-label`, its one legend, a heading inside it or in its
+own band, else its purpose ("Newsletter signup", "Contact"). Rename it with `update_form` if the
+site calls it something else.
+
+**An imported form's words are edited in the form, and written into the built page.** On a new
+import, setup binds each part of the built `<form>` to its form row: field labels, placeholders,
+help lines, select and radio options, and the submit button's text. Change one with `update_form`
+(`fields[].label`, `placeholder`, `helpText`, `options`, or `submitLabel`) and the next content
+apply writes it into every built page that draws the form, with no rebuild. The built form
+carries the stamps:
+
+| Stamp | On | Says |
+|---|---|---|
+| `data-bcms-form-bound="<formId>"` | the `<form>` | Its parts are this form's. Never `data-bcms-form`: that one means the form posts to BetterCMS. |
+| `data-bcms-form-part` | a part | `label`, `help`, `option` or `submit`, as `BcmsForm` names them. |
+| `data-bcms-form-field="<key>"` | a part or a control | The field it belongs to. |
+| `data-bcms-form-value="form:<formId>:<path>"` | a part shown as text | The address written: `fields.<key>.label`, `fields.<key>.helpText`, `fields.<key>.options.<i>`, `submitLabel`. A placeholder is a `data-bcms-props` entry (`form:<formId>:fields.<key>.placeholder`). |
+
+Only words are written. The lane adds and removes no element and never touches `name`, `id`,
+`for`, `action`, `value`, a validation attribute or a hidden input, so the site's own script and
+endpoint keep working. An option added to the row has no element until the site's code is
+rebuilt, and is reported as not on the page. A fieldset's `<legend>` and an
+`<input type="submit">` stay the code's. A form setup ignored (sign-in, basket) and a form
+already wired with `data-bcms-form` take no stamp. The submit button belongs to the form: its
+text is `submitLabel`, never a page field.
+
+### 4. Wiring a self-hosted site
+
+- **Next**: `getForm('Name')` (or an id) reads the form from `bcms-content.json`; render
+  `<BcmsForm form={form} />`. It renders the honeypot input under the form's own
+  `honeypotField` name, reads the `cf-turnstile-response` token when a Turnstile widget is on the
+  page, and submits through the SDK `submitForm`.
+- **Astro**: `BcmsForm.astro` renders the same hidden honeypot input and sends
+  `cf-turnstile-response` when present.
+- Neither component checks `status`. Render a form only when `form.status === "published"`.
+- The honeypot name is per form. Never hardcode it; read `form.honeypotField`.
+
+### 5. Per-rung facts
+
+| Situation | Answer |
+|---|---|
+| `FORMS_WORKER_URL` set but blank on the API | 503 `FORMS_WORKER_NOT_CONFIGURED`. A blank never falls back to the default worker |
+| Worker without `FORMS_SHARED_SECRET` | 503 `FORMS_WORKER_SECRET_UNSET` on data routes |
+| No Turnstile secret for the form or env | Token not verified; the submission continues |
+| Rate-limit store unavailable | Limits allow the request |
+| Management delete of a submission not in that form | 404 `FORM_SUBMISSION_NOT_FOUND` |
+
+### 6. Traps
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Every submission 403 | Form still draft | Call `publish_form` |
+| Submissions 503 on a dev or preview API | Worker URL blank or worker secret unset | Report the code to the owner; do not change the site |
+| Lead stored but no contact, integration or notification | Classified as spam (honeypot filled); side effects run for inbox leads only | Keep the honeypot input hidden and empty |
+| Submission 400 `FORM_FIELD_INVALID` rule `scalar` | A field value sent as an object | Send plain values; checkboxes as a flat list |
+| Webhook integration never fires | Target is not a public http(s) host | Use a public https endpoint |