@usgb/forms 1.0.1 → 1.0.2

package/README.md

@@ -6,24 +6,24 @@ You pick a predefined `formId`. The package owns fields, validation, consent cop
 
 ## What you get
 
-| Artifact      | Path / export                                                   | Who uses it                         |
-| ------------- | --------------------------------------------------------------- | ----------------------------------- |
-| React package | `@usgb/forms` → `dist/index.js`                                 | PWA / any React host                |
-| Stylesheet    | `@usgb/forms/usgb-forms.css`                                    | **Required** for React hosts        |
-| Web Component | `dist/usgb-forms.js` (also versioned `usgb-forms.<version>.js`) | WordPress and other non-React hosts |
-| Catalog       | `@usgb/forms/manifest` → `forms-manifest.json`                  | CMS pickers, docs, tooling          |
+| Artifact      | Path / export                                                                                              | Who uses it                         |
+| ------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| React package | `@usgb/forms` → `dist/index.js`                                                                            | PWA / any React host                |
+| Stylesheet    | `@usgb/forms/usgb-forms.css`                                                                               | **Required** for React hosts        |
+| Web Component | `dist/usgb-forms.js` (also versioned `usgb-forms.<version>.js`)                                            | WordPress and other non-React hosts |
+| Catalog       | `@usgb/forms/manifest` → `forms-manifest.json` (also versioned `forms-manifest.<version>.json` in `dist/`) | CMS pickers, Gutenberg, tooling     |
 
 The Web Component script injects the same CSS once on load. React hosts must import the stylesheet themselves.
 
 ## Mental model
 
-| You pass                         | Package already decided                                                               |
-| -------------------------------- | ------------------------------------------------------------------------------------- |
-| `formId`                         | Fields, required/optional rules, consent bundle, tracking set, layout family (`kind`) |
-| `adapter.submit`                 | Where the payload goes (never an attribute or hardcoded URL)                          |
-| `legalUrls` / `*-url`            | Hrefs for package-owned consent copy                                                  |
-| `heading`, `subheading`, `ctaLabel` | Marketing copy around the form                                                     |
-| `successMessage` or `successUrl` | Thank-you UX after accept                                                             |
+| You pass                            | Package already decided                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------- |
+| `formId`                            | Fields, required/optional rules, consent pins, tracking set, layout family (`kind`) |
+| `adapter.submit`                    | Where the payload goes (never an attribute or hardcoded URL)                        |
+| `legalUrls` / `*-url`               | Hrefs for package-owned consent copy                                                |
+| `heading`, `subheading`, `ctaLabel` | Marketing copy around the form                                                      |
+| `successMessage` or `successUrl`    | Thank-you UX after accept                                                           |
 
 Hosts **must not** invent field lists, consent wording, or tracking keys. New forms are new catalog entries in this package, not host-built schemas.
 
@@ -31,12 +31,13 @@ Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of avail
 
 ## Available forms
 
-| `formId`             | Kind         | Fields                                                    | Consent                        | Variants                                                |
-| -------------------- | ------------ | --------------------------------------------------------- | ------------------------------ | ------------------------------------------------------- |
-| `main-investors-kit` | `lead`       | First name, last name, email (required); phone (optional) | TCPA checkbox (`lead-tcpa` v1) | `dense`, `large`, `sidebar`, plus optional `two-column` |
-| `newsletter`         | `newsletter` | Email only                                                | None                           | None — omit `variants` / `variant`                      |
+| `formId`                    | Kind         | Fields                                                    | Consent                                                    | Variants                                                |
+| --------------------------- | ------------ | --------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `main-investors-kit`        | `lead`       | First name, last name, email (required); phone (optional) | Optional TCPA, marketing SMS, and terms/privacy checkboxes | `dense`, `large`, `sidebar`, plus optional `two-column` |
+| `main-investors-kit-notice` | `lead`       | Same as kit                                               | Clickwrap notice only (`lead-clickwrap` v1)                | `dense`, `large`, `sidebar`, plus optional `two-column` |
+| `newsletter`                | `newsletter` | Email only                                                | None                                                       | None — omit `variants` / `variant`                      |
 
-Appearances for both: `on-light` | `on-dark`. Appearance only recolors the form for readability on a light or dark host background — it never sets a background, padding, or radius. The host container owns those.
+Appearances for every catalog form: `on-light` | `on-dark`. Appearance only recolors the form for readability on a light or dark host background — it never sets a background, padding, or radius. The host container owns those.
 
 `kind` is the layout family (lead grid vs inline newsletter row). The root exposes `data-kind` for CSS. Several catalog forms can share one kind (e.g. another lead kit that reuses the lead layout).
 
@@ -69,9 +70,40 @@ Load the built IIFE (styles inject themselves):
 <script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
 ```
 
-Exact CDN hostname, path, and versioning scheme are **TBD**. Prefer a versioned filename (`usgb-forms.<version>.js`) so hosts can pin releases.
+Exact CDN hostname, path, and versioning scheme are **TBD**. Prefer versioned filenames (`usgb-forms.<version>.js` and `forms-manifest.<version>.json`) so hosts can pin the script and the CMS picker to the same release. Gutenberg should load that matching manifest — not an unversioned “latest” file — when listing `formId`s.
 
-Until the package is published, you can still develop against a local checkout (`yarn add file:../usgb-forms` or `yarn link`).
+### Local development (hosts, unpublished)
+
+Hosts consume **built** artifacts (`dist/` and root `forms-manifest.json`), not `src/`. Clone this repo next to the host (or anywhere you can path to), then:
+
+```bash
+cd usgb-forms
+yarn install
+yarn build
+```
+
+Rebuild here whenever you change this package. The Vite playground (`yarn dev`) is only for package maintainers; it is not what PWA or WordPress load.
+
+**React / PWA.** Point the host at this repo with Yarn 1 `file:` (preferred — the path lives in the host `package.json`, no global link):
+
+```bash
+# from the PWA / React host, path adjusted to your layout
+yarn add file:../usgb-forms
+```
+
+Or set `"@usgb/forms": "file:../usgb-forms"` by hand and run `yarn install`. Imports stay the same (`@usgb/forms`, `@usgb/forms/usgb-forms.css`, `@usgb/forms/manifest`). After each `yarn build` in this repo, run `yarn install` (or `yarn upgrade @usgb/forms`) in the host so Yarn recopies the pack — `file:` does not live-reload.
+
+`yarn link` in this repo and `yarn link @usgb/forms` in the host also works, but it can resolve a second copy of React and break hooks. If that happens, alias `@usgb/forms` to the sibling folder in the host bundler instead of linking.
+
+**WordPress / Web Component.** Skip the CDN. After `yarn build`, load files from this repo:
+
+| Host need                | File in this repo                                               |
+| ------------------------ | --------------------------------------------------------------- |
+| Form script              | `dist/usgb-forms.js`                                            |
+| Pinned script (optional) | `dist/usgb-forms.<version>.js`                                  |
+| Gutenberg `formId` list  | `forms-manifest.json` (or `dist/forms-manifest.<version>.json`) |
+
+Copy those into the plugin on its build, or enqueue them from a local static server. A `file:` npm dependency is not required for the Web Component — only a URL (or filesystem path the plugin can enqueue) to the built JS and catalog JSON.
 
 ## React (PWA)
 
@@ -212,19 +244,19 @@ interface HostAdapter {
 
 ### Payload shape (summary)
 
-Successful submits send a nested envelope: `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), optional `consent`, and `context` (`host`, `source`, `campaign`, `page`, `tracking`). Exact field and tracking sets come from the form’s catalog entry.
+Successful submits send a nested envelope: `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), optional `consents` (grant booleans, opt-in dates, and `*_consent_language` strings), and `context` (`host`, `source`, `campaign`, `page`, `tracking`). Exact field and tracking sets come from the form’s catalog entry.
 
 ## Consent and legal URLs
 
-Consent bundles are versioned and package-owned (checkboxes and/or clickwrap notices). Hosts only supply document **hrefs**.
-
--   `main-investors-kit` uses `lead-tcpa` v1 and requires `clientAgreement` and `privacyPolicy`.
--   PWA Magento defaults: `PWA_LEGAL_URLS` → `/content/client-agreement`, `/content/privacy-policy`.
--   WordPress must pass every URL required by the selected consent. A consent form with a missing required URL **does not render**.
--   Checkbox values land in `consent.values` (and mirrored in `data`). Notices have no boolean field; the payload still records consent definition id/version.
--   Distinct legal wording requires a new consent id/version in this package — not freeform copy from the host.
+Consent policies are versioned and package-owned (checkboxes and/or clickwrap notices). Forms list zero or more pins (`definitionId` + `definitionVersion` + optional `required` for checkboxes). Hosts only supply document **hrefs**.
 
-`LEAD_CLICKWRAP_V1` (“By clicking the button…”) is in the catalog and needs five legal URLs (`privacyPolicy`, `userAgreement`, `marketLossPolicy`, `electronicDisclaimer`, `termsOfSale`). It is not attached to a `formId` until that recipe is chosen.
+-   `main-investors-kit` pins `lead-tcpa`, `lead-sms`, and `lead-tospp` (all v1, optional checkboxes). It needs `userAgreement` and `privacyPolicy` for the terms/privacy copy.
+-   `main-investors-kit-notice` pins `lead-clickwrap` v1 (notice only). It needs the five clickwrap URLs.
+-   PWA Magento defaults (`PWA_LEGAL_URLS`): `/content/client-agreement`, `/content/privacy-policy`, `/content/user-agreement`, `/content/market-loss-policy`, `/content/electronic-disclaimer`, `/content/terms-of-sale`.
+-   WordPress must pass every URL required by the selected consents. A form with a missing required URL **does not render**.
+-   Checkbox grants land in `consents` only (`tcpa_form_consent_granted`, `sms_form_consent_granted`, `tospp_form_consent_granted`). The exact copy shown is `tcpa_consent_language` (and the matching keys for other policies), even when unchecked.
+-   Checking the TCPA box also adds `tcpa_form_opt_in_date` (YYYY-MM-DD). The notice form only sends `clickwrap_consent_language`.
+-   Distinct legal wording requires a new consent id/version in this package — not freeform copy from the host. Toggle `consents[].required` on the form recipe when a checkbox must be checked.
 
 ## Success behavior
 
@@ -284,7 +316,24 @@ Appearance never paints a card. Put the form on a dark host surface and pass `ap
 </div>
 ```
 
-Visual styles are a ported snapshot of the PWA form kit. When PWA form styles change, update this package and bump the version.
+Visual styles are a ported snapshot of the PWA form kit. When PWA form styles change, update this package and bump `package.json` `version`.
+
+## Versions
+
+Day to day, bump **`package.json` `version`** (and set `compatiblePackageVersions` to `^` that version). Push to `main`: npm publishes only if that version is new; S3 always uploads `dist/`. Skipping a package bump **overwrites** the existing `usgb-forms.<version>.js` pin.
+
+Patch is enough while nothing is consuming the package. Use minor/major later for compatible vs breaking host API.
+
+Everything else is a different object — leave it alone unless that object actually changed:
+
+| Field                                         | Bump when                                                            |
+| --------------------------------------------- | -------------------------------------------------------------------- |
+| `forms[formId].definitionVersion`             | That form’s fields, consent pins, or tracking change                 |
+| Consent `definitionVersion` in `consents.tsx` | Legal wording changes (new id/version; do not edit in place)         |
+| `submissionContract.version`                  | Submit JSON shape changes (proxies read `submissionContractVersion`) |
+| `schemaVersion`                               | Manifest JSON keys/shape change (CMS parsers)                        |
+
+Form and consent rules: [`src/definitions/context.md`](src/definitions/context.md).
 
 ## Develop (package maintainers)
 

package/dist/forms-manifest.1.0.2.json

@@ -0,0 +1,305 @@
+{
+    "schemaVersion": "1.0.0",
+    "package": {
+        "name": "@usgb/forms",
+        "compatiblePackageVersions": "^1.0.2"
+    },
+    "submissionContract": {
+        "version": "1.0.0",
+        "transport": "server-proxy",
+        "payloadShape": "data-and-context"
+    },
+    "trackingRegistry": {
+        "page_url": {
+            "destination": "form_submission_url",
+            "category": "page",
+            "collection": "server",
+            "required": true,
+            "states": ["collected", "unavailable"],
+            "description": "Canonical landing-page URL at submission time"
+        },
+        "page_title": {
+            "destination": "pageName",
+            "category": "page",
+            "collection": "server",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "referrer": {
+            "destination": "referrer",
+            "category": "page",
+            "collection": "browser",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "first_touch_url": {
+            "destination": "crossDomain_landing_url",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_source": {
+            "destination": "utm_source",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_medium": {
+            "destination": "utm_medium",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_campaign": {
+            "destination": "utm_campaign",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_term": {
+            "destination": "utm_term",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_content": {
+            "destination": "utm_content",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "gclid": {
+            "destination": "gclid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "msclkid": {
+            "destination": "msclkid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "gbraid": {
+            "destination": "gbraid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "wbraid": {
+            "destination": "wbraid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "hubspot_utk": {
+            "destination": "hubspot_utk",
+            "category": "identity",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "ga_client_id": {
+            "destination": "ga_client_id",
+            "category": "analytics",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "ga_session_id": {
+            "destination": "session_id_start",
+            "category": "analytics",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "snowplow_id": {
+            "destination": "snowplow_id",
+            "category": "analytics",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "vwo_uuid": {
+            "destination": "vwo_uuid",
+            "category": "experiment",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "user_agent": {
+            "destination": "header_http_client_details",
+            "category": "technical",
+            "collection": "server",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "ip_address": {
+            "destination": "ipAddress",
+            "category": "technical",
+            "collection": "server",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        }
+    },
+    "forms": {
+        "main-investors-kit": {
+            "definitionVersion": "1",
+            "kind": "lead",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa", "wordpress"],
+            "fields": [
+                { "name": "firstname", "required": true, "group": "name" },
+                { "name": "lastname", "required": true, "group": "name" },
+                { "name": "email", "required": true },
+                { "name": "phone", "required": false }
+            ],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "first_touch_url",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "gclid",
+                "msclkid",
+                "gbraid",
+                "wbraid",
+                "hubspot_utk",
+                "ga_client_id",
+                "ga_session_id",
+                "snowplow_id",
+                "vwo_uuid",
+                "user_agent",
+                "ip_address"
+            ],
+            "ctaLabel": "GET MY FREE GUIDE",
+            "consents": [
+                {
+                    "definitionId": "lead-tcpa",
+                    "definitionVersion": "1",
+                    "required": false
+                },
+                {
+                    "definitionId": "lead-sms",
+                    "definitionVersion": "1",
+                    "required": false
+                },
+                {
+                    "definitionId": "lead-tospp",
+                    "definitionVersion": "1",
+                    "required": false
+                }
+            ],
+            "editor": {
+                "label": "Main Investors Kit",
+                "description": "Standard lead form: name, email, phone, plus optional TCPA, marketing SMS, and terms/privacy checkboxes. Use on full-width landing pages and PWA kit/sidebar placements.",
+                "whenToUse": "Default kit request with optional consent checkboxes. Do not use for affiliate landers or IRA-specific leads.",
+                "whenNotToUse": "Affiliate pages (separate definition). IRA kit (separate definition when added). Clickwrap-only kit (`main-investors-kit-notice`).",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": ["dense", "large", "sidebar", "two-column"]
+            }
+        },
+        "main-investors-kit-notice": {
+            "definitionVersion": "1",
+            "kind": "lead",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa", "wordpress"],
+            "fields": [
+                { "name": "firstname", "required": true, "group": "name" },
+                { "name": "lastname", "required": true, "group": "name" },
+                { "name": "email", "required": true },
+                { "name": "phone", "required": false }
+            ],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "first_touch_url",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "gclid",
+                "msclkid",
+                "gbraid",
+                "wbraid",
+                "hubspot_utk",
+                "ga_client_id",
+                "ga_session_id",
+                "snowplow_id",
+                "vwo_uuid",
+                "user_agent",
+                "ip_address"
+            ],
+            "ctaLabel": "GET MY FREE GUIDE",
+            "consents": [
+                { "definitionId": "lead-clickwrap", "definitionVersion": "1" }
+            ],
+            "editor": {
+                "label": "Main Investors Kit (clickwrap)",
+                "description": "Same fields as Main Investors Kit with a clickwrap notice only — no consent checkboxes.",
+                "whenToUse": "Kit request where submit acknowledges legal docs via notice copy instead of checkboxes.",
+                "whenNotToUse": "Placements that need TCPA / marketing SMS / terms checkboxes (`main-investors-kit`).",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": ["dense", "large", "sidebar", "two-column"]
+            }
+        },
+        "newsletter": {
+            "definitionVersion": "1",
+            "kind": "newsletter",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa"],
+            "fields": [{ "name": "email", "required": true }],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content"
+            ],
+            "ctaLabel": "SUBSCRIBE",
+            "editor": {
+                "label": "Newsletter",
+                "description": "Email-only newsletter signup. No TCPA consent.",
+                "whenToUse": "Footer or landing newsletter capture where only an email is required.",
+                "whenNotToUse": "Lead kits that need name, phone, or TCPA consent.",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": []
+            }
+        }
+    },
+    "hostAdapterContract": {
+        "hosts": ["pwa", "wordpress"],
+        "mayProvide": [
+            "browser cookies",
+            "URL parameters",
+            "page and placement context",
+            "host/store identity"
+        ],
+        "mustNotDefine": [
+            "new tracking keys",
+            "destination property names",
+            "consent definitions",
+            "form fields",
+            "submission endpoints"
+        ]
+    }
+}

package/dist/forms-manifest.json

@@ -2,7 +2,7 @@
     "schemaVersion": "1.0.0",
     "package": {
         "name": "@usgb/forms",
-        "compatiblePackageVersions": "^1.0.0"
+        "compatiblePackageVersions": "^1.0.2"
     },
     "submissionContract": {
         "version": "1.0.0",
@@ -187,20 +187,74 @@
                 "ip_address"
             ],
             "ctaLabel": "GET MY FREE GUIDE",
-            "consent": {
-                "definitionId": "lead-tcpa",
-                "definitionVersion": "1",
-                "required": true,
-                "submitFields": [
-                    "tcpa_form_consent_granted",
-                    "tcpa_form_opt_in_date"
-                ]
-            },
+            "consents": [
+                {
+                    "definitionId": "lead-tcpa",
+                    "definitionVersion": "1",
+                    "required": false
+                },
+                {
+                    "definitionId": "lead-sms",
+                    "definitionVersion": "1",
+                    "required": false
+                },
+                {
+                    "definitionId": "lead-tospp",
+                    "definitionVersion": "1",
+                    "required": false
+                }
+            ],
             "editor": {
                 "label": "Main Investors Kit",
-                "description": "Standard lead form: name, email, phone, TCPA consent. Use on full-width landing pages and PWA kit/sidebar placements.",
-                "whenToUse": "Default kit request. Do not use for affiliate landers or IRA-specific leads.",
-                "whenNotToUse": "Affiliate pages (separate definition). IRA kit (separate definition when added).",
+                "description": "Standard lead form: name, email, phone, plus optional TCPA, marketing SMS, and terms/privacy checkboxes. Use on full-width landing pages and PWA kit/sidebar placements.",
+                "whenToUse": "Default kit request with optional consent checkboxes. Do not use for affiliate landers or IRA-specific leads.",
+                "whenNotToUse": "Affiliate pages (separate definition). IRA kit (separate definition when added). Clickwrap-only kit (`main-investors-kit-notice`).",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": ["dense", "large", "sidebar", "two-column"]
+            }
+        },
+        "main-investors-kit-notice": {
+            "definitionVersion": "1",
+            "kind": "lead",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa", "wordpress"],
+            "fields": [
+                { "name": "firstname", "required": true, "group": "name" },
+                { "name": "lastname", "required": true, "group": "name" },
+                { "name": "email", "required": true },
+                { "name": "phone", "required": false }
+            ],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "first_touch_url",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "gclid",
+                "msclkid",
+                "gbraid",
+                "wbraid",
+                "hubspot_utk",
+                "ga_client_id",
+                "ga_session_id",
+                "snowplow_id",
+                "vwo_uuid",
+                "user_agent",
+                "ip_address"
+            ],
+            "ctaLabel": "GET MY FREE GUIDE",
+            "consents": [
+                { "definitionId": "lead-clickwrap", "definitionVersion": "1" }
+            ],
+            "editor": {
+                "label": "Main Investors Kit (clickwrap)",
+                "description": "Same fields as Main Investors Kit with a clickwrap notice only — no consent checkboxes.",
+                "whenToUse": "Kit request where submit acknowledges legal docs via notice copy instead of checkboxes.",
+                "whenNotToUse": "Placements that need TCPA / marketing SMS / terms checkboxes (`main-investors-kit`).",
                 "supportedAppearances": ["on-light", "on-dark"],
                 "supportedVariants": ["dense", "large", "sidebar", "two-column"]
             }