@usgb/forms 1.0.2 → 1.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 Shared lead and newsletter forms for the **PWA** (React) and **WordPress** (Web Component) hosts.
 
-You pick a predefined `formId`. The package owns fields, validation, consent copy, tracking keys, and layout. You own the submit endpoint, legal-document URLs, heading/subheading/CTA copy, and thank-you behavior.
+You pick a predefined `formId`. The package owns fields, validation, consent copy, and layout. You own the submit endpoint, legal-document URLs, heading/subheading/CTA copy, and thank-you behavior. The backend owns tracking and page-context collection.
 
 ## What you get
 
@@ -17,33 +17,61 @@ The Web Component script injects the same CSS once on load. React hosts must imp
 
 ## Mental model
 
-| 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                                                           |
+| You pass                            | Package already decided                                               |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| `formId`                            | Fields, required/optional rules, consent pins, 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.
+Hosts **must not** invent field lists or consent wording. New forms are new catalog entries in this package, not host-built schemas.
 
-Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of available `formId`s. Deeper catalog rules: [`src/definitions/context.md`](src/definitions/context.md).
+Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of available `formId`s, and `listEditorOptions(formId)` for the settings that picker may expose (see [Editor options](#editor-options)).
 
 ## Available forms
 
-| `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`                      |
+| `formId`                    | Kind         | Fields                                                    | Consent                                                         | Size/layout                                                  |
+| --------------------------- | ------------ | --------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
+| `magento-fik`               | `lead`       | First name, last name, email (required); phone (optional) | Optional TCPA (v1), marketing SMS, and terms/privacy checkboxes | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `magento-ira-kick-article`  | `lead`       | First name, last name, email, phone (all required)        | Optional TCPA checkbox (v2, links terms and privacy)            | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `magento-fik-blog-rail`     | `lead`       | First name, last name, email, phone (all required)        | Required TCPA checkbox (v3, links terms and privacy)            | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `main-investors-kit-notice` | `lead`       | Same as `magento-fik`                                     | Clickwrap notice only (`lead-clickwrap` v2)                     | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `newsletter`                | `newsletter` | Email only                                                | None                                                            | None — omit `variant` and `twoColumn` / `two-column`         |
 
 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).
 
-## Install
+### Editor options
+
+`editorOptions` in the manifest lists every host-owned setting an editor may apply, and each form's `editor.options` lists the ones that form accepts. A CMS panel should build its controls from those two lists instead of hardcoding prop names:
+
+| Option           | Control   | React prop       | Attribute                                | Applies to                                       |
+| ---------------- | --------- | ---------------- | ---------------------------------------- | ------------------------------------------------ |
+| `appearance`     | select    | `appearance`     | `appearance`                             | All forms — values in `supportedAppearances`     |
+| `variant`        | select    | `variant`        | `variant`                                | Lead forms — values in `supportedVariants`       |
+| `twoColumn`      | checkbox  | `twoColumn`      | `two-column`                             | Lead forms — independent of the size variant     |
+| `heading`        | text      | `heading`        | `heading`                                | All forms                                        |
+| `subheading`     | text      | `subheading`     | `subheading`                             | All forms                                        |
+| `ctaLabel`       | text      | `ctaLabel`       | `cta`                                    | All forms — default is the form's `ctaLabel`     |
+| `legalUrls`      | url group | `legalUrls`      | `*-url` (see `attributes` on the option) | Forms with consent — keys in `requiredLegalUrls` |
+| `successMessage` | text      | `successMessage` | `success-message`                        | All forms                                        |
+| `successUrl`     | url       | `successUrl`     | `success-url`                            | All forms                                        |
+
+Only `legalUrls` is required, and only for the keys a form's consents name — the form does not render when one is missing. Everything else is optional.
 
-Registry package name, scope, and CDN base URL are **TBD** — examples below use the working package name `@usgb/forms` and a placeholder CDN host. Replace them when publishing is finalized.
+`listEditorOptions(formId)` returns those options already resolved for one form (allowed values, effective default, React prop, and attribute), so a Gutenberg panel does not have to follow the `valuesFrom` / `defaultFrom` pointers itself:
+
+```ts
+import { listEditorOptions } from '@usgb/forms'
+
+listEditorOptions('newsletter')
+// [{ key: 'appearance', control: 'select', values: ['on-light', 'on-dark'], defaultValue: 'on-light', … }, …]
+// `variant`, `twoColumn`, and `legalUrls` are absent — newsletter takes none.
+```
+
+## Install
 
 ### npm (React / PWA)
 
@@ -64,46 +92,13 @@ Peer dependency: `react` and `react-dom` `^18` or `^19`.
 
 ### CDN (Web Component / WordPress)
 
-Load the built IIFE (styles inject themselves):
+Load the built script for a release (styles inject themselves):
 
 ```html
-<script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
+<script src="https://forms.usgoldbureau.com/usgb-forms.1.0.4.js"></script>
 ```
 
-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.
-
-### 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.
+Pin the script and the catalog together: `usgb-forms.<version>.js` and `forms-manifest.<version>.json` on `https://forms.usgoldbureau.com/`. Gutenberg should load that matching manifest when listing `formId`s.
 
 ## React (PWA)
 
@@ -111,14 +106,13 @@ Copy those into the plugin on its build, or enqueue them from a local static ser
 import { UsgbForm, createStubAdapter, PWA_LEGAL_URLS } from '@usgb/forms'
 import '@usgb/forms/usgb-forms.css'
 ;<UsgbForm
-    formId="main-investors-kit"
+    formId="magento-fik"
     appearance="on-dark"
-    variants={['large', 'two-column']}
+    variant="large"
+    twoColumn
     heading="Get My Free Guide"
     subheading="Enter your details to receive the Main Investors Kit."
     ctaLabel="GET MY FREE GUIDE"
-    source="cms-home"
-    campaign="spring-kit"
     legalUrls={PWA_LEGAL_URLS}
     successMessage="Thanks — we will send your kit shortly."
     adapter={yourHostAdapter}
@@ -131,7 +125,7 @@ import '@usgb/forms/usgb-forms.css'
 />
 ```
 
-Newsletter (no consent, no variants):
+Newsletter (no consent or lead layout options):
 
 ```tsx
 <UsgbForm
@@ -145,42 +139,51 @@ Newsletter (no consent, no variants):
 
 ### React props
 
-| Prop                      | Required                   | Role                                                                                                |
-| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
-| `formId`                  | yes                        | Catalog key (`main-investors-kit`, `newsletter`, …)                                                 |
-| `adapter`                 | yes                        | `HostAdapter` with `host`, `getTrackingHints()`, `submit()`                                         |
-| `appearance`              | no                         | `on-light` (default) or `on-dark`                                                                   |
-| `variants`                | no                         | Lead only. Default `['dense']`. One of `dense` \| `large` \| `sidebar`, optionally add `two-column` |
-| `heading` / `subheading`  | no                         | Title and supporting copy                                                                           |
-| `ctaLabel`                | no                         | Submit button label. Falls back to the catalog `ctaLabel` for that `formId`                         |
-| `source` / `campaign`     | no                         | Placement / campaign context in the payload                                                         |
-| `legalUrls`               | when consent requires them | Host CMS paths for legal links in consent copy                                                      |
-| `successMessage`          | no                         | Inline thank-you when `successUrl` is omitted                                                       |
-| `successUrl`              | no                         | Redirect after accept (analytics / `onAccepted` are invoked first; see Success behavior)            |
-| `analytics`               | no                         | `(event) => void` for view / validation / submit / success / failure                                |
-| `className`               | no                         | Extra class on `.usgb-form`                                                                         |
-| `onAccepted` / `onFailed` | no                         | Callbacks with the submission payload                                                               |
+| Prop                      | Required                   | Role                                                                                                                                                              |
+| ------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formId`                  | yes                        | Catalog key (`magento-fik`, `newsletter`, …)                                                                                                                      |
+| `adapter`                 | yes                        | `HostAdapter` with `host` and `submit()`                                                                                                                          |
+| `appearance`              | no                         | `on-light` (default) or `on-dark`                                                                                                                                 |
+| `variant`                 | no                         | Lead only. Default `dense`. Exactly one of `dense` \| `large` \| `sidebar`                                                                                        |
+| `twoColumn`               | no                         | Lead only. Places grouped name fields in two columns when space allows                                                                                            |
+| `heading` / `subheading`  | no                         | Title and supporting copy                                                                                                                                         |
+| `ctaLabel`                | no                         | Submit button label. Falls back to the catalog `ctaLabel` for that `formId`                                                                                       |
+| `legalUrls`               | when consent requires them | Host CMS paths. Keys: `clientAgreement`, `privacyPolicy`, `userAgreement`, `marketLossPolicy`, `electronicDisclaimer`, `termsOfSale` (see Consent and legal URLs) |
+| `successMessage`          | no                         | Inline thank-you when `successUrl` is omitted                                                                                                                     |
+| `successUrl`              | no                         | Redirect after accept (analytics / `onAccepted` are invoked first; see Success behavior)                                                                          |
+| `analytics`               | no                         | `(event) => void`. Event `type`: `view` \| `validation_failure` \| `submit_attempt` \| `success` \| `failure`. React-only — the Web Component has no equivalent   |
+| `className`               | no                         | Extra class on `.usgb-form`. React-only — put classes on the host page around `<usgb-form>`                                                                       |
+| `onAccepted` / `onFailed` | no                         | Callbacks with the submission payload. Web Component: `usgb-form:success` / `usgb-form:failure`                                                                   |
 
 ## Web Component (WordPress)
 
 Load one script. Styles are injected automatically.
 
-````html
-<script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
+```html
+<script src="https://forms.usgoldbureau.com/usgb-forms.1.0.4.js"></script>
 <usgb-form
-    ```
-    form-id="main-investors-kit"
+    form-id="magento-fik"
     appearance="on-dark"
-    variant="large two-column"
+    variant="large"
+    two-column
     heading="Get My Free Guide"
     subheading="Enter your details to receive the Main Investors Kit."
     cta="GET MY FREE GUIDE"
-    source="cms-home"
-    client-agreement-url="/client-agreement/"
+    user-agreement-url="/user-agreement/"
     privacy-policy-url="/privacy-policy/"
     success-message="Thanks — we will send your kit shortly."
 ></usgb-form>
-````
+```
+
+Clickwrap kit (`main-investors-kit-notice`) needs the two notice URLs:
+
+```html
+<usgb-form
+    form-id="main-investors-kit-notice"
+    privacy-policy-url="/privacy-policy/"
+    user-agreement-url="/user-agreement/"
+></usgb-form>
+```
 
 Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real `HostAdapter` in script:
 
@@ -189,10 +192,6 @@ Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real
     const el = document.querySelector('usgb-form')
     el.adapter = {
         host: 'wordpress',
-        getTrackingHints() {
-            // Cookies, UTMs, click ids — keys must match the package tracking registry
-            return {}
-        },
         async submit(payload) {
             const res = await fetch('/your-form-submit', {
                 method: 'POST',
@@ -215,48 +214,72 @@ Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real
 
 ### Attribute map
 
-| Attribute                                       | React prop                                                    |
-| ----------------------------------------------- | ------------------------------------------------------------- |
-| `form-id`                                       | `formId`                                                      |
-| `appearance`                                    | `appearance`                                                  |
-| `variant`                                       | `variants` (space-separated)                                  |
-| `heading` / `subheading`                        | `heading` / `subheading`                                      |
-| `cta`                                           | `ctaLabel`                                                    |
-| `source` / `campaign`                           | `source` / `campaign`                                         |
-| `success-message` / `success-url`               | `successMessage` / `successUrl`                               |
-| `client-agreement-url`, `privacy-policy-url`, … | `legalUrls.*`                                                 |
-| `host`                                          | Used only for the stub adapter before you assign `el.adapter` |
+`form-id` defaults to `magento-fik`, `appearance` to `on-light`, `variant` to `dense`, and `host` to `wordpress`. `two-column` is a boolean attribute and is off when omitted. There is no `version` attribute — `definitionVersion` comes from the catalog.
+
+| Attribute                   | React prop                                                    |
+| --------------------------- | ------------------------------------------------------------- |
+| `form-id`                   | `formId`                                                      |
+| `appearance`                | `appearance`                                                  |
+| `variant`                   | `variant`                                                     |
+| `two-column`                | `twoColumn`                                                   |
+| `heading` / `subheading`    | `heading` / `subheading`                                      |
+| `cta`                       | `ctaLabel`                                                    |
+| `success-message`           | `successMessage`                                              |
+| `success-url`               | `successUrl`                                                  |
+| `client-agreement-url`      | `legalUrls.clientAgreement`                                   |
+| `privacy-policy-url`        | `legalUrls.privacyPolicy`                                     |
+| `user-agreement-url`        | `legalUrls.userAgreement`                                     |
+| `market-loss-policy-url`    | `legalUrls.marketLossPolicy`                                  |
+| `electronic-disclaimer-url` | `legalUrls.electronicDisclaimer`                              |
+| `terms-of-sale-url`         | `legalUrls.termsOfSale`                                       |
+| `host`                      | Used only for the stub adapter before you assign `el.adapter` |
+
+Same names are exported as `LEGAL_URL_ATTRS` (`legalUrls` key → attribute). Gutenberg and other generators should use that map instead of hard-coding strings.
+
+### Properties and events
+
+| Surface             | Role                                                                                    |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| `el.adapter`        | Assign a `HostAdapter`. Not an attribute. Markup without this uses `createStubAdapter`. |
+| `usgb-form:success` | `e.detail` is `SubmissionPayload` (same as React `onAccepted`)                          |
+| `usgb-form:failure` | `e.detail` is `{ payload, message }` (same as React `onFailed`)                         |
+
+The Web Component does not expose `analytics` or `className`. Listen for the events above, or wrap the element for layout.
 
 ## Host adapter
 
 ```ts
 interface HostAdapter {
     host: 'pwa' | 'wordpress'
-    getTrackingHints(): Partial<Record<TrackingKey, string | undefined>>
     submit(payload: SubmissionPayload): Promise<SubmitResult>
 }
 ```
 
 -   `submit` must return `{ status: 'accepted' }` or `{ status: 'failed', message?: string }`.
--   The package never embeds Workato, Magento, or WordPress endpoints.
--   `createStubAdapter('pwa' | 'wordpress')` accepts every payload (playground / markup-only WC).
--   Tracking keys and destination names live in `forms-manifest.json`. Hosts may supply values for registered keys; they must not invent new ones.
+-   The package does not choose a submit URL.
+-   `createStubAdapter('pwa' | 'wordpress')` accepts every payload (markup-only Web Component).
+-   Tracking, UTMs, page URL, referrer, and similar context are collected by the backend. This package does not send a `context` object.
 
 ### Payload shape (summary)
 
-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.
+Successful submits send `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), and optional `consents` (grant booleans, opt-in dates, and `*_consent_language` strings). Exact field sets come from the form’s catalog entry.
 
 ## Consent and legal URLs
 
 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**.
 
--   `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.
+-   `magento-fik` pins `lead-tcpa`, `lead-sms`, and `lead-tospp` (all v1, optional checkboxes). Required URLs: `userAgreement`, `privacyPolicy` (`user-agreement-url`, `privacy-policy-url`).
+-   `magento-ira-kick-article` pins `lead-tcpa` v2 only (optional checkbox). Unlike v1, v2 links the terms and privacy policy, so required URLs: `userAgreement`, `privacyPolicy`.
+-   `magento-fik-blog-rail` pins `lead-tcpa` v3 only (required checkbox: automated text-message consent; “Terms of Service” links `userAgreement`, “Privacy Policy” links `privacyPolicy`). It shares the v1 payload keys. Required URLs: `userAgreement`, `privacyPolicy`.
+-   `main-investors-kit-notice` pins `lead-clickwrap` v2 (notice only: Privacy Policy, Terms & Conditions, and text/call consent). Required URLs: `privacyPolicy`, `userAgreement`. It shares the v1 payload key `clickwrap_consent_language`. `lead-clickwrap` v1 (five document links) stays in the catalog and is not pinned.
+-   `newsletter` has no consents and needs no legal URLs.
+-   `LEGAL_URL_ATTRS` lists every host-owned slot, including `clientAgreement` / `client-agreement-url`. No current catalog consent requires `clientAgreement`; it is still valid on `legalUrls` / the attribute (PWA Magento ships it in `PWA_LEGAL_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**.
+-   WordPress must pass every URL required by the selected consents. A form with a missing required URL **does not render**. CMS pickers can compute the list with `getFormDefinition`, `resolveFormConsents`, and `collectRequiredLegalUrls`, then map keys through `LEGAL_URL_ATTRS`.
+-   `isCompleteLegalUrls(legalUrls, requiredKeys)` is the same check the renderer uses.
 -   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.
+-   Hosts supply document hrefs only. Consent wording stays in this package.
 
 ## Success behavior
 
@@ -304,6 +327,8 @@ Prefer **custom properties** on `.usgb-form` for color, type, and spacing:
 
 Use class selectors when a token does not exist (`.usgb-form .usgb-btn { border-radius: 0; }`).
 
+**Fonts.** Body copy, fields, and the button inherit the host page's `font-family`, so WordPress (`'Montserrat', sans-serif` on `body`) and the PWA (`next/font`'s hashed `__Montserrat_…` family) both render in Montserrat with no extra setup. Set `--usgb-font-primary` on `.usgb-form` only to force a different stack. The heading uses `--usgb-font-secondary`, which reads the host variable `--font-kameron` first and falls back to the `Kameron` family name; a `next/font` host should expose `Kameron({ variable: '--font-kameron' })` on `<html>`, or override `--usgb-font-secondary` directly.
+
 Stable hooks: `.usgb-form` (`data-appearance`, `data-variant`, `data-kind`), `.usgb-form-heading`, `.usgb-form-subheading`, `.usgb-form-grid`, `.usgb-form-inline`, `.usgb-field-control`, `.usgb-field-error`, `.usgb-consent-*`, `.usgb-btn`, `.usgb-form-status-*`.
 
 Semantic tokens (`--usgb-field-*`, `--usgb-button-*`, `--usgb-newsletter-underline`, …) are the first place to retheme. Palette vars (`--usgb-blue-1`, …) are a PWA snapshot. Error and checkbox glyphs are inline SVGs that use `currentColor` — override `--usgb-alert-danger` or `--usgb-checkbox-mark` to recolor them.
@@ -312,42 +337,6 @@ Appearance never paints a card. Put the form on a dark host surface and pass `ap
 
 ```html
 <div style="background: #001f3d; padding: 2rem; border-radius: 0.75rem">
-    <usgb-form form-id="main-investors-kit" appearance="on-dark" …></usgb-form>
+    <usgb-form form-id="magento-fik" appearance="on-dark" …></usgb-form>
 </div>
 ```
-
-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)
-
-```bash
-yarn install
-yarn dev      # Vite playground (tries :5174)
-yarn build
-yarn typecheck
-yarn lint
-yarn format
-```
-
-Prettier and ESLint match magento-frontend (4-space indent, single quotes, no semicolons, print width 80).
-
-## Git
-
-Local repo only. Connect a GitHub remote later when ready to publish.