diff --git a/.claude/skills/create-core-component/SKILL.md b/.claude/skills/create-core-component/SKILL.md
index 93b7ad3a05..14d22b1408 100644
--- a/.claude/skills/create-core-component/SKILL.md
+++ b/.claude/skills/create-core-component/SKILL.md
@@ -17,17 +17,21 @@ Scaffold a complete, production-ready AEM Core Form Component across all layers
 
 ### Phase 1: Gather Requirements
 
-Before generating any code, collect the following from the user:
-
-1. **Component name** — e.g., `ImageChoice`, `StarRating`, `ColorPicker`
-2. **Component type** — which category:
-   - **Simple field** (text-like input) → extends `AbstractFieldImpl` / implements `Field`
-   - **Options field** (multiple choices) → extends `AbstractOptionsFieldImpl` / implements `OptionsConstraint`
-   - **Container** (holds child components) → extends `AbstractContainerImpl`
-   - **Display-only** (non-input: text, image, separator) → extends `AbstractBaseImpl` / implements `Base`
-3. **Custom properties** — any JCR properties beyond what the base class provides
-4. **Widget HTML** — what the interactive element looks like (input, select, custom markup)
+Before generating any code or reading any reference files, collect all of the following from the user in a single message. Do not proceed until all answers are received.
+
+1. **Component name and purpose** — e.g., `ImageChoice` (radio group with image thumbnails), `StarRating` (captures 1–5 star rating)
+2. **Component type** — which category (see `docs/architecture/overview.md` for the base class and interface each one maps to):
+   - **Simple field** (text-like input that captures a single value)
+   - **Options field** (multiple choices: checkboxes, radios, dropdowns)
+   - **Container** (holds child components)
+   - **Step / display** (non-input: text, image, separator)
+   - **Display/text** (renders authored HTML content with a title label) — `sling:resourceSuperType="core/fd/components/form/text/v1/text"`
+3. **Custom properties** — any JCR properties beyond what the base class provides (name, type, default, purpose for each)
+4. **Widget HTML** — what the interactive element looks like (input type, select, custom div, etc.)
 5. **Constraints** — which constraint interfaces apply (String, Number, Date, Options, File)
+6. **Target repository and component group** — which repo (`aem-core-forms-components`, or a project overlay) and what `componentGroup` for the author toolbar (e.g., `".core-adaptiveform"`)
+7. **Java backend** — does this component need a custom Sling Model, or can it reuse an existing Core model via `sling:resourceSuperType`? (Reuse is appropriate when the component only adds JS behavior on top of an existing field type; custom Java is required for new authored properties exposed in HTL or JSON)
+8. **FormContainer-level properties** — does this component need any configuration authored on the parent form container rather than on the component instance itself? (e.g., a signing service path set once for the whole form) If yes: what properties, and what tab name should they appear under in the form container dialog?
 
 ### Phase 2: Derive Naming Conventions
 
@@ -44,6 +48,7 @@ From the component name, derive all naming variants. For example, given `ImageCh
 | Resource type | `core/fd/components/form/imagechoice/v1/imagechoice` |
 | Clientlib category | `core.forms.components.imagechoice.v1.runtime` |
 | FormConstant | `RT_FD_FORM_IMAGE_CHOICE_V1` |
+| `fd:viewType` (step only) | `image-choice` |
 
 ### Phase 3: Generate Files
 
@@ -70,9 +75,14 @@ Read `references/templates.md` for the full template set. Read `references/compo
 
 #### 3b. UI AF Apps (HTL, Dialogs, Clientlibs)
 
-4. **Component definition** — `.content.xml` with `sling:resourceSuperType="core/fd/components/form/base/v1/base"`
+4. **Component definition** — `.content.xml` with `sling:resourceSuperType` set to the appropriate base. Also create `_cq_template.xml` (instance defaults: `jcr:title`, `fieldType`, and `fd:viewType` for step components) and `_cq_editConfig.xml` (author toolbar — use the inplace RTE variant from `references/templates.md` template #16 for display/text components). See `references/templates.md` templates #6, #6b, and #16.
 
-5. **HTL template** — Follow the standard structure:
+5. **HTL template** — Choose the correct variant from `references/templates.md`:
+   - **Template #7** — field components (captures a value)
+   - **Template #7b** — step/display components (no widget)
+   - **Template #7c** — display/text with label and rich-text value area
+   
+     Follow the standard structure for the chosen variant:
    - Include shared templates via `data-sly-use` (label, shortDescription, longDescription, errorMessage, questionMark)
    - Root `<div>` with `data-cmp-is`, `data-cmp-visible`, `data-cmp-enabled`, `data-cmp-required`, `data-cmp-readonly`
    - Label container with label + question mark
@@ -87,9 +97,9 @@ Read `references/templates.md` for the full template set. Read `references/compo
 
 7. **Dialog XML** — Include base dialog fields via `granite/ui/components/coral/foundation/include`, add component-specific tabs/fields
 
-8. **Site clientlib** — `.content.xml`, `js.txt`, `css.txt`, view JS, styles. **Before writing the view JS, read `references/runtime-view-js.md`** — it defines the `FormFieldBase` override contract (`super` calls, `updateEmptyStatus`, composite-widget focus guard).
+8. **Site clientlib** — `.content.xml`, `js.txt`, `css.txt`, view JS (`references/templates.md` #11 or #11b), the CSS stub (empty BEM rules in `aem-core-forms-components`) plus the theme SCSS (actual styles in `aem-forms-theme-canvas`). See `references/css-architecture.md` and `references/templates.md` #12. **Before writing the view JS, read `references/runtime-view-js.md`** — it defines the `FormFieldBase` override contract (`super` calls, `updateEmptyStatus`, composite-widget focus guard).
 
-9. **Editor clientlib** — `.content.xml` with editor category. In editor JS use `textContent` (never `innerHTML`) and don't wrap locale-neutral format strings in `Granite.I18n.get`.
+9. **Editor clientlib** — `.content.xml` with editor category. See `references/editor-clientlib.md` for JS safety rules (`textContent` vs `innerHTML`, i18n) and the conditional-field-visibility pattern.
 
 10. **Register the runtime clientlib** — embed the component's `core.forms.components.{componentname}.v1.runtime` category in `ui.af.apps/.../af-clientlibs/core-forms-components-runtime-all/.content.xml`. Missing this silently breaks the runtime Cypress suite.
 
@@ -120,15 +130,21 @@ required** (they catch HTL/view-JS/dialog/sync bugs that unit tests cannot). Rea
 17. **Example content page** — Page structure with `guideContainer` and sample component instance
 18. **Register in example index** — Add entry to `examples/ui.content/.../adaptive-form/.content.xml`
 
-### Phase 4: Accessibility Verification
+#### 3e. Wiring and Registration
+
+After all files are created, complete the wiring steps from `references/wiring-steps.md`:
 
-After generating all files, read `references/accessibility-checklist.md` and verify:
+- **Step 1** — Embed the clientlib category in `core-forms-components-runtime-all/.content.xml`
+- **Step 2** — Add `FormConstants` resource type constant (if needed by other Java code)
+- **Step 3** — Add i18n strings to all 10 language files (if new constraint messages were added)
+- **Step 4** — Content migration (see `migrate-foundation-component` skill — not applicable for new components)
+- **Step 5** — Extend FormContainer dialog (if component reads form-level properties)
+- **Step 6** — Register component group in the production template policy
+- **Step 7** — Create integration test content and register it in the IT template policy
+
+### Phase 4: Accessibility Verification
 
-1. **HTL template** — Every interactive element has `aria-label` or `<label for>`, error div has `aria-live="assertive"`, descriptions have `aria-live="polite"`. For a grouped widget, give the group `aria-label="${component.label.value}"` — **the shared label template emits no `id`, so `aria-labelledby="...__label"` is broken** (see `references/runtime-view-js.md` and the accessibility checklist).
-2. **JS view** — Prefer the inherited `FormFieldBase` handlers. If you override `updateValidity` / `updateEnabled` / `updateReadOnly` / `updateValue`, **call `super.<handler>(value, state)` first** so `data-cmp-*` attributes, the error message, and `--filled`/`--empty` stay in sync; only then add component-specific behaviour. Focus/blur handlers call `setActive()`/`setInactive()`. Read `references/runtime-view-js.md` — this is the #1 source of runtime bugs.
-3. **LESS styles** — `:focus` has visible `outline` with `2px` minimum, error states use color + text
-4. **Keyboard** — All interactive elements have `tabindex` if not natively focusable
-5. **BEM** — All class names follow `cmp-adaptiveform-{componentname}__{element}` convention
+After generating all files, work through `references/accessibility-checklist.md` and satisfy every applicable item (labels, ARIA states, live regions, keyboard, focus, BEM). That file is the single source of truth for the WCAG 2.1 AA requirements. It also covers the two highest-risk items: the `FormFieldBase` override contract (if you override `updateValidity` / `updateEnabled` / `updateReadOnly` / `updateValue`, call `super.<handler>(value, state)` first — see `references/runtime-view-js.md`, the #1 source of runtime bugs) and the grouped-widget label pitfall (use `aria-label="${component.label.value}"`, not `aria-labelledby`, because the shared label template emits no `id`).
 
 ### Phase 5: Validation
 
@@ -190,28 +206,39 @@ described in `references/runtime-view-js.md`.
 ## Key References
 
 - `references/component-anatomy.md` — Full file checklist (incl. Cypress + wiring), interface/implementation hierarchy, FormConstants pattern
-- `references/templates.md` — Copy-paste-ready templates for every file type with placeholders
+- `references/templates.md` — Copy-paste-ready templates for every file type with placeholders (including variants 2b, 6b, 7b, 7c, 11b, 11c, 16)
 - `references/runtime-view-js.md` — **The `FormFieldBase` override contract** (super calls, `updateEmptyStatus`, composite widgets) — read before writing any view JS
 - `references/cypress-tests.md` — Required runtime + authoring specs, wiring, and Cypress gotchas
 - `references/accessibility-checklist.md` — WCAG 2.1 AA checklist with AEM-specific ARIA patterns
+- `docs/architecture/overview.md` — Component-layer diagram, runtime data flow, and Java/JS base-class selection guide
+- `references/css-architecture.md` — Two-layer CSS split: stub in `aem-core-forms-components`, SCSS in `aem-forms-theme-canvas`
+- `references/widget-patterns.md` — HTML widget element patterns for each component type
+- `references/wiring-steps.md` — Post-generation wiring: clientlib embed, FormConstants, i18n, FormContainer dialog, template policy
+- `references/verification-checklist.md` — Post-implementation checklist covering structure, wiring, CSS, HTL, JS, Java, and tests
+- `references/common-mistakes.md` — Common implementation mistakes with fixes
+- `references/editor-clientlib.md` — JS-driven conditional field visibility in author dialogs, and editor JS safety rules
+- `references/composite-multifield.md` — Composite multifield patterns for repeatable dialog items
+- `references/datasource-servlet.md` — Dynamic JCR-sourced options for Granite UI selects
 - `scripts/validate_component.py` — Automated validator — run after generating all files
 
 ## Critical Rules
 
-1. **Never skip the accessibility checklist** — Every component must satisfy WCAG 2.1 AA
-2. **Always use existing abstract base classes** — Do not reinvent label/description/tooltip/error handling
-3. **Always register in FormConstants** — The resource type constant is required for Sling Model resolution
-4. **Follow BEM strictly** — `cmp-adaptiveform-{componentname}__{element}` with no exceptions
-5. **Use shared field templates** — Label, description, error message, question mark templates from `af-commons`
-6. **JSON export must validate** — The exporter JSON test validates against the Adaptive Form JSON schema
-7. **Match existing copyright headers** — Apache License 2.0 headers on all Java, JS, HTL, and LESS files. Use the **current calendar year** (not a hardcoded year) in `Copyright {year} Adobe`
-8. **Include `data-cmp-data-layer`** — The root `<div>` in HTL must include `data-cmp-data-layer="${{componentname}.data.json}"` for analytics/data layer integration
-9. **Use `@ValueMapValue` with `InjectionStrategy.OPTIONAL`** — Never use `REQUIRED`; missing properties should use defaults
-10. **Test both `Resource` and `SlingHttpServletRequest` adaptation** — The `@Model` annotation must list both `adaptables`
-11. **Widget ID convention** — Always `{componentId}-widget` via `${'{0}-{1}' @ format=[component.id, 'widget']}`
-12. **Call `super` when overriding `update*` handlers** — `FormFieldBase` keeps the root `data-cmp-*` attributes, the error message, and `--filled`/`--empty` in sync; an override that skips `super` silently breaks them. An overridden `updateValue` must also end with `this.updateEmptyStatus()`. See `references/runtime-view-js.md`.
-13. **Cypress specs are mandatory** — ship `{componentname}.runtime.cy.js` + `{componentname}.authoring.cy.js`, the IT sample content, the `formsConstants.js` entry, and the runtime-all embed. Run the runtime spec green against `localhost:4502` before sign-off.
+Terse non-negotiables. Where a rule has a detailed rationale or failure mode, it is documented once in the referenced file — do not restate it here.
+
+1. **Never skip accessibility** — satisfy every applicable item in `references/accessibility-checklist.md` (WCAG 2.1 AA), including the grouped-widget label pitfall (use `aria-label`, not `aria-labelledby`).
+2. **Always extend an existing abstract base class** — do not reinvent label/description/tooltip/error handling. See `docs/architecture/overview.md`.
+3. **Always register in FormConstants** — the resource type constant is required for Sling Model resolution.
+4. **Follow BEM strictly** — `cmp-adaptiveform-{componentname}__{element}`, no exceptions.
+5. **Use shared field templates** from `af-commons` (label, description, error message, question mark).
+6. **JSON export must validate** against the Adaptive Form JSON schema (exporter test).
+7. **Match existing copyright headers** — Apache License 2.0 on all Java/JS/HTL/LESS files, using the current calendar year.
+8. **Include `data-cmp-data-layer`** on the root `<div>` for data-layer integration.
+9. **Widget ID convention** — always `{componentId}-widget` via `${'{0}-{1}' @ format=[component.id, 'widget']}`.
+10. **`_cq_editConfig.xml` is required** for every component (display/text with inplace editing uses the extended variant — `references/templates.md` template #16).
+11. **CSS is split across two repos** — see `references/css-architecture.md` for what goes where.
+12. **Call `super` when overriding `update*` handlers** — an override that skips `super` silently breaks `data-cmp-*`, the error message, and `--filled`/`--empty`; an overridden `updateValue` must also end with `this.updateEmptyStatus()`. See `references/runtime-view-js.md`.
+13. **Cypress specs are mandatory** — ship `{componentname}.runtime.cy.js` + `{componentname}.authoring.cy.js`, the IT sample content, the `formsConstants.js` entry, and the runtime-all embed. Run the runtime spec green against `localhost:4502` before sign-off. See `references/cypress-tests.md`.
 14. **No empty styling or dialogs** — every BEM modifier class you emit must have a CSS rule; never ship an empty `_cq_design_dialog` tab.
-15. **Group label uses `aria-label`** — the shared label template emits no `id`, so `aria-labelledby="...__label"` is broken; use `aria-label="${component.label.value}"` for `role="group"` widgets.
-16. **Composite widgets**: only the hidden combined input carries `name`; never repopulate a sub-input the user is actively editing.
-17. **Editor JS safety** — use `textContent` not `innerHTML`; don't wrap locale-neutral format strings (`'YYYY-MM-DD'`) in `Granite.I18n.get`.
+15. **Composite widgets** — only the hidden combined input carries `name`; never repopulate a sub-input the user is actively editing. See `references/runtime-view-js.md`.
+16. **Editor JS safety** — see `references/editor-clientlib.md` (`textContent` vs `innerHTML`, locale-neutral format strings).
+17. **Read `references/common-mistakes.md` before Phase 3** — it is the source of truth for the recurring failure modes (`@ValueMapValue`/`InjectionStrategy.OPTIONAL`, dual `adaptables`, `data-sly-test` on `__value`, and others); those are not repeated here.
diff --git a/.claude/skills/create-core-component/references/accessibility-checklist.md b/.claude/skills/create-core-component/references/accessibility-checklist.md
index 51c798bc07..896dc491a1 100644
--- a/.claude/skills/create-core-component/references/accessibility-checklist.md
+++ b/.claude/skills/create-core-component/references/accessibility-checklist.md
@@ -63,17 +63,7 @@ Every component MUST satisfy all applicable items below. This checklist is deriv
 
 ## BEM Naming Convention for Accessibility Elements
 
-Every component follows this naming pattern:
-```
-.cmp-adaptiveform-{componentname}              — root container
-.cmp-adaptiveform-{componentname}__label        — label element
-.cmp-adaptiveform-{componentname}__widget       — main interactive widget
-.cmp-adaptiveform-{componentname}__errormessage — error message area
-.cmp-adaptiveform-{componentname}__shortdescription — tooltip
-.cmp-adaptiveform-{componentname}__longdescription  — expanded help text
-.cmp-adaptiveform-{componentname}__questionmark     — help toggle button
-.cmp-adaptiveform-{componentname}__label-container  — label + question mark wrapper
-```
+For the standard BEM element set (`__label`, `__widget`, `__errormessage`, `__shortdescription`, `__longdescription`, `__questionmark`, `__label-container`), see the table in `references/css-architecture.md`. Every one of those elements must be present and correctly linked for accessibility.
 
 ## ID Convention for ARIA Linkage
 
@@ -97,9 +87,9 @@ common source of runtime bugs.
 
 | Method | If you override it… |
 |--------|---------------------|
-| `updateValidity(validity, state)` | call `super` (it renders the error message + sets `data-cmp-valid`), then mirror `aria-invalid` onto extra sub-widgets |
-| `updateReadOnly(readOnly, state)` | call `super` (sets `data-cmp-readonly`), then set `aria-readonly`/`readonly` on sub-widgets |
-| `updateEnabled(enabled, state)` | call `super` (sets `data-cmp-enabled`), then toggle `disabled` on sub-widgets |
+| `updateValidity(validity, state)` | call `super` first, then mirror `aria-invalid` onto extra sub-widgets |
+| `updateReadOnly(readOnly, state)` | call `super` first, then set `aria-readonly`/`readonly` on sub-widgets |
+| `updateEnabled(enabled, state)` | call `super` first, then toggle `disabled` on sub-widgets |
 | `updateValue(value)` | end with `this.updateEmptyStatus()`; for composite widgets, don't repopulate a focused sub-input |
 | `setModel(model)` | register focus/blur listeners for `setActive()`/`setInactive()` |
 
diff --git a/.claude/skills/create-core-component/references/common-mistakes.md b/.claude/skills/create-core-component/references/common-mistakes.md
new file mode 100644
index 0000000000..f512d83582
--- /dev/null
+++ b/.claude/skills/create-core-component/references/common-mistakes.md
@@ -0,0 +1,62 @@
+# Common Implementation Mistakes
+
+1. **`data-cmp-is` mismatch** — The single most common failure. The string in HTML must equal `static IS` in JS. One extra capital letter breaks the wiring.
+
+2. **Wrong `fieldType` format** — Core uses kebab-case: `text-input`, not `textInput` or `TEXT_INPUT`. Check `references/component-anatomy.md` (FieldType Values section) for the full list.
+
+3. **`@Inject` instead of `@ValueMapValue`** — `@Inject` uses Sling's default injector chain and may pick up values from places other than the resource value map. Always use `@ValueMapValue` for JCR properties.
+
+4. **Missing `InjectionStrategy.OPTIONAL`** — Without it, Sling Model adaptation fails at runtime if the JCR property is absent on an existing content node.
+
+5. **Foundation package imports in Java** — Any import starting with `com.adobe.guides.*` or `com.adobe.fd.guide.*` means you are cross-referencing foundation. Remove it.
+
+6. **Boolean `data-cmp-*` attributes as bare booleans** — `data-cmp-visible="${model.visible}"` outputs `true`/`false` as strings correctly in some HTL versions but fails in others. Always use `${model.visible ? 'true' : 'false'}`.
+
+7. **Missing `aria-describedby`** — All interactive widgets must reference all three IDs (`{id}__errormessage`, `{id}__longdescription`, `{id}__shortdescription`). Omitting any of them breaks screen reader support and fails accessibility audits.
+
+8. **Clientlib category typo** — The category in `runtime/.content.xml` must exactly match what you embed in the `core-forms-components-runtime-all` clientlib. A single character difference means the component's JS/CSS never loads.
+
+9. **Step component extending FormFieldBase** — Steps have no widget and no value. Extending `FormFieldBase` instead of `FormContainer` causes null errors on `getWidget()`.
+
+10. **`fd:viewType` on field components** — `fd:viewType` is for step/display components that share `fieldType=plain-text` but need distinct rendering. Field components (text-input, number-input, etc.) do not need `fd:viewType`.
+
+11. **CSS properties in the core-forms-components stub file** — `{name}view.css` inside `aem-core-forms-components` must have empty rules only. Visual properties go in `aem-forms-theme-canvas`.
+
+12. **Hardcoded colour or size values in theme SCSS** — Always use design tokens from `_variables.scss`. Hardcoded values (`#666`, `40px`) break when the theme is customised. If no suitable token exists, add one to `_variables.scss`.
+
+13. **Forgetting `[data-cmp-valid]` selectors in theme SCSS** — Without these, validation state changes written by the JS view produce no visual feedback. Add both `[data-cmp-valid=false]` and `[data-cmp-valid=true]` selectors for every interactive field component.
+
+14. **Not importing the new SCSS file in `theme.scss`** — The Parcel build only includes what is imported. A missing `@import` means the component has zero styles even after `npm run build`.
+
+15. **`data-sly-test` on the `__value` div** — Never put `data-sly-test` on the outer `__value` wrapper. `getWidget()` in the JS view must always find `.cmp-adaptiveform-{name}__value`. Put the conditional **inside** the div with a `<sly data-sly-test="…">` wrapper.
+
+16. **Destructive `updateValue` fallback** — Do not set `this.element.innerHTML` when `getWidget()` returns null. That wipes the `__label-container`. Update only `getWidget()`; fix HTL if the widget is missing.
+
+17. **Invented dialog text during migration** *(migration mode only)* — Adding `fieldDescription` to Core dialog fields that had no description in the foundation dialog, or rephrasing foundation `fieldLabel` / option `text` without justification. Rule: copy foundation text verbatim; omit `fieldDescription` when the foundation field had none; only write original text for fields that are genuinely new in Core.
+
+---
+
+## Display/Text Component Mistakes
+
+These apply to any component that uses HTL template 7c and `sling:resourceSuperType="core/fd/components/form/text/v1/text"`.
+
+1. **Title not rendering on display/text components** — Symptom: only rich-text `value` shows but `jcr:title` is set in CRX. Causes and fixes:
+    - HTL used `resource.properties['jcr:title']` instead of `baseModel.label.value` → use HTL template 7c with `data-sly-use.baseModel="…Base"` (see "Sling Model – Display/Text" in `references/templates.md`).
+    - Sling Model `adapters` omitted `Base.class` → add `Base.class` alongside `Text.class`.
+    - Bound only `Text` in HTL for label → `Text` has no `getLabel()`; extend `AbstractBaseImpl` and register `Base.class` in `adapters`.
+    - Parent `text/v1/text` dialog hides Title → re-declare `./jcr:title` and `./hideTitle` in child `_cq_dialog`.
+    - **Verify:** CRX has `jcr:title`; DevTools shows `label.cmp-adaptiveform-{name}__label` inside `__label-container`.
+
+---
+
+## Author Dialog and Coral Interactivity
+
+These apply to any component whose author dialog uses composite multifields or JavaScript-driven conditional field visibility. `references/editor-clientlib.md` is the canonical source for the patterns and fixes below (JS boilerplate, `getSelectValue`, `setVisible`) — this list only flags the symptoms so you recognize them.
+
+1. **Coral listener ordering race** — a `coral-collection:add` handler never fires for a programmatically-added item. See "Listener registration order" in `references/editor-clientlib.md`.
+2. **Both conditional fields visible on new multifield item** — adding an item briefly shows all conditionally-hidden fields before they settle. See "Default-off fields in new items" in `references/editor-clientlib.md`.
+3. **`getSelectValue` returns nothing** — reading `.val()` on a `granite:class`-wrapped element instead of the `coral-select` DOM property. See `getSelectValue` in `references/editor-clientlib.md`.
+4. **`setVisible` hides more than intended** — `.closest(".coral-Form-fieldwrapper")` traverses past the multifield item boundary to a parent container's fieldwrapper. See "`setVisible` boundary" in `references/editor-clientlib.md`.
+5. **Select default not applied when `emptyText` omitted** — the JS may read `val === ""` before Coral finishes upgrading. See "Select Default Behavior" in `references/editor-clientlib.md`.
+
+---
diff --git a/.claude/skills/create-core-component/references/component-anatomy.md b/.claude/skills/create-core-component/references/component-anatomy.md
index ea8e0b0d36..f5feb6deb2 100644
--- a/.claude/skills/create-core-component/references/component-anatomy.md
+++ b/.claude/skills/create-core-component/references/component-anatomy.md
@@ -77,25 +77,7 @@ FormComponent
 
 ## Implementation Hierarchy
 
-```
-AbstractComponentImpl (WCM Core)
-  └── AbstractFormComponentImpl (name, fieldType, dataRef, visible, value, events, rules)
-        └── AbstractBaseImpl (label, description, tooltip, type, required, enabled)
-              └── AbstractFieldImpl (readOnly, default, placeholder, min/max constraints)
-                    ├── AbstractOptionsFieldImpl (enum, enumNames, enforceEnum)
-                    └── [Direct subclasses for simple fields]
-```
-
-Choose the appropriate base class:
-- **Simple text/number field** -> extend `AbstractFieldImpl`
-- **Options-based field** (checkboxes, radios, selects) -> extend `AbstractOptionsFieldImpl`
-- **Container/panel** -> extend `AbstractContainerImpl`
-- **Non-input component** (button, text, image) -> extend `AbstractBaseImpl`
-- **Composite / split widget** (e.g. day/month/year, multiple visible inputs feeding
-  one value) -> still extend the field base that matches the data type
-  (`AbstractFieldImpl` for date), but render **one hidden combined `<input>`** as the
-  value-bearing widget plus the visible sub-inputs. This category has extra runtime
-  rules — read `references/runtime-view-js.md` before writing the view JS.
+For the full class hierarchy (Impl classes) and base-class selection guide (including the composite / split-widget case), see `docs/architecture/overview.md` — the "Java Model Hierarchy" section is the single source of truth; do not restate it here.
 
 ---
 
diff --git a/.claude/skills/create-core-component/references/composite-multifield.md b/.claude/skills/create-core-component/references/composite-multifield.md
new file mode 100644
index 0000000000..9ebf07cd8f
--- /dev/null
+++ b/.claude/skills/create-core-component/references/composite-multifield.md
@@ -0,0 +1,93 @@
+# Composite Multifield in Granite UI Dialogs
+
+Use a `composite="true"` multifield when each item in a repeatable list has multiple named sub-fields (e.g., a list of signers each with email, authentication method, and phone number). Each item is stored as a child JCR node under the multifield's named path.
+
+---
+
+## 1. XML Structure
+
+```xml
+<myMultifield
+    jcr:primaryType="nt:unstructured"
+    sling:resourceType="granite/ui/components/coral/foundation/form/multifield"
+    composite="true"
+    fieldDescription="Add one or more items."
+    fieldLabel="Items"
+    name="./items/item">
+    <field
+        jcr:primaryType="nt:unstructured"
+        sling:resourceType="granite/ui/components/coral/foundation/container"
+        name="./items/item">
+        <items jcr:primaryType="nt:unstructured">
+            <!-- Sub-fields — note: NO "./" prefix on name attributes here -->
+            <title
+                jcr:primaryType="nt:unstructured"
+                sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
+                fieldLabel="Title"
+                name="title"/>
+            <mode
+                jcr:primaryType="nt:unstructured"
+                sling:resourceType="granite/ui/components/coral/foundation/form/select"
+                fieldLabel="Mode"
+                name="mode">
+                <items jcr:primaryType="nt:unstructured">
+                    <opt1 jcr:primaryType="nt:unstructured" text="Option A" value="A"/>
+                    <opt2 jcr:primaryType="nt:unstructured" text="Option B" value="B"/>
+                </items>
+            </mode>
+        </items>
+    </field>
+</myMultifield>
+```
+
+**Critical rules:**
+- `composite="true"` (not `composite="{Boolean}true"`) — the literal string form is required.
+- The `field` container's `name` must match the multifield's `name` exactly (including the `./` prefix).
+- Sub-field `name` attributes inside the template do NOT use `./` prefix — they are relative to the multifield item node automatically.
+- The `granite:class` on the `field` container provides the JS hook for the whole item row.
+
+---
+
+## 2. JCR Storage
+
+Each item is stored as a numbered child of the multifield node:
+```
+./items/item/item0/title = "First item title"
+./items/item/item0/mode  = "A"
+./items/item/item1/title = "Second item title"
+./items/item/item1/mode  = "B"
+```
+
+---
+
+## 3. Reading in a Sling Model
+
+```java
+@ChildResource(injectionStrategy = InjectionStrategy.OPTIONAL, name = "items")
+private Resource itemsResource;
+
+@PostConstruct
+private void init() {
+    if (itemsResource != null) {
+        Resource itemContainer = itemsResource.getChild("item");
+        if (itemContainer != null) {
+            List<MyItemModel> list = new ArrayList<>();
+            for (Resource child : itemContainer.getChildren()) {
+                MyItemModel m = child.adaptTo(MyItemModel.class);
+                if (m != null) list.add(m);
+            }
+            items = Collections.unmodifiableList(list);
+        }
+    }
+}
+```
+
+The item model class must be annotated with `adaptables = { Resource.class }` (not `SlingHttpServletRequest.class`) since it adapts from child resources, not from a request.
+
+---
+
+## 4. JS Selector for Sub-Fields
+
+Inside a `coral-collection:add` handler, `e.detail.item` is the `coral-multifield-item` element. The item div (from `granite:class` on the `field` container) is a child of it — find it with `$(e.detail.item).find(".your-item-class")`. The template HTML is fully rendered (including `granite:class` values) when the event fires, but Coral sub-components (`coral-select`, `coral-radiogroup`) may still be upgrading — use `Coral.commons.ready(e.detail.item, callback)` before reading `coral-select.value`.
+
+**Also see:** `references/editor-clientlib.md` for the full JS boilerplate pattern including listener registration order, default-off field hiding, and `getSelectValue` helpers.
diff --git a/.claude/skills/create-core-component/references/css-architecture.md b/.claude/skills/create-core-component/references/css-architecture.md
new file mode 100644
index 0000000000..bde48d0154
--- /dev/null
+++ b/.claude/skills/create-core-component/references/css-architecture.md
@@ -0,0 +1,70 @@
+# CSS Two-Layer Architecture
+
+## How CSS is Split Between the Two Repos
+
+```
+aem-core-forms-components                    aem-forms-theme-canvas
+─────────────────────────────────────        ──────────────────────────────────────
+ui.af.apps/.../form/{name}/v1/{name}/        src/components/{name}/_{name}.scss
+  clientlibs/
+    runtime/
+      css.txt  ← lists {name}view.css        src/site/_variables.scss (design tokens)
+      css/
+        {name}view.css  ← EMPTY STUBS        src/theme.scss ← imports all components
+                                             dist/theme.css ← compiled output
+                                             → deployed as AEM clientlib
+```
+
+**Rule**: Never put visual CSS properties in `aem-core-forms-components`. Never put only BEM structure definitions in `aem-forms-theme-canvas`.
+
+## What Goes in Each Layer
+
+| | `aem-core-forms-components` stub CSS | `aem-forms-theme-canvas` SCSS |
+|-|--------------------------------------|-------------------------------|
+| BEM class declarations | All classes, empty `{ }` | Same class names, with properties |
+| Colors, spacing, fonts | Never | Via `$variables` tokens |
+| Validation states | Never | `[data-cmp-valid=false/true]` selectors |
+| Focus / hover / disabled | Never | Pseudo-class selectors |
+| Responsive breakpoints | Never | Media queries |
+| Design tokens | Never | `_variables.scss` |
+| Build step | None — plain CSS | Parcel 2.0 → `npm run build` |
+
+## Standard BEM Elements for Every Field Component
+
+This table is the single source of truth for the standard BEM element set; other references point here.
+
+Every field component's HTL template emits these elements. The stub CSS and theme SCSS must cover all of them:
+
+| BEM element suffix | CSS class | What it wraps |
+|-------------------|-----------|---------------|
+| *(root block)* | `.cmp-adaptiveform-{name}` | Outer container `<div>` |
+| `__label-container` | `.cmp-adaptiveform-{name}__label-container` | Label + question mark row |
+| `__label` | `.cmp-adaptiveform-{name}__label` | The `<label>` element |
+| `__questionmark` | `.cmp-adaptiveform-{name}__questionmark` | Help icon |
+| `__widget` | `.cmp-adaptiveform-{name}__widget` | The `<input>`, `<select>`, `<textarea>`, or custom `<div>` |
+| `__shortdescription` | `.cmp-adaptiveform-{name}__shortdescription` | Tooltip / short help text |
+| `__longdescription` | `.cmp-adaptiveform-{name}__longdescription` | Long description paragraph |
+| `__errormessage` | `.cmp-adaptiveform-{name}__errormessage` | Validation error text |
+
+Validation state attribute selectors (set by JS view at runtime):
+
+```scss
+.cmp-adaptiveform-{name}[data-cmp-valid=false] { ... }   // invalid
+.cmp-adaptiveform-{name}[data-cmp-valid=true]  { ... }   // valid
+```
+
+Visibility/state attributes (set by JS view at runtime):
+
+```scss
+.cmp-adaptiveform-{name}[data-cmp-visible=false] { display: none; }
+.cmp-adaptiveform-{name}[data-cmp-enabled=false]  { opacity: 0.5; pointer-events: none; }
+```
+
+## Build and Deploy the Theme
+
+```bash
+# in aem-forms-theme-canvas/
+npm run build              # Parcel compiles all SCSS → dist/theme.css
+npm run create-clientlib   # packages dist/ as AEM clientlib (outputs to theme-clientlibs/)
+# then install theme-clientlibs/ package into AEM via Package Manager
+```
diff --git a/.claude/skills/create-core-component/references/datasource-servlet.md b/.claude/skills/create-core-component/references/datasource-servlet.md
new file mode 100644
index 0000000000..1bb685e84c
--- /dev/null
+++ b/.claude/skills/create-core-component/references/datasource-servlet.md
@@ -0,0 +1,139 @@
+# Datasource Servlet for Granite UI Selects
+
+Use a datasource servlet when a Granite UI `form/select` (or `form/autocomplete`) needs to be populated dynamically from JCR content at dialog-open time — for example, listing all form fields compatible with a given data type, or listing cloud service configurations.
+
+---
+
+## 1. Servlet Pattern
+
+```java
+@Component(service = { Servlet.class }, property = {
+    "sling.servlet.resourceTypes=core/fd/components/form/container/v2/container/datasource/myfields",
+    "sling.servlet.methods=GET",
+    "sling.servlet.extensions=html"
+})
+public class MyFieldsDataSourceServlet extends AbstractDataSourceServlet {
+
+    @Reference
+    private transient ExpressionResolver expressionResolver;
+
+    @NotNull
+    @Override
+    protected ExpressionResolver getExpressionResolver() {
+        return expressionResolver;
+    }
+
+    @Override
+    protected void doGet(@NotNull SlingHttpServletRequest request,
+                         @NotNull SlingHttpServletResponse response) {
+        ResourceResolver resolver = request.getResourceResolver();
+        // The suffix is the path of the component instance being configured
+        String suffix = request.getRequestPathInfo().getSuffix();
+        List<Resource> entries = new ArrayList<>();
+
+        if (resolver != null && suffix != null) {
+            Resource component = resolver.getResource(suffix);
+            Resource form = ComponentUtils.getFormContainer(component);
+            if (form != null) {
+                collectEntries(form, entries, resolver);
+            }
+        }
+
+        request.setAttribute(DataSource.class.getName(),
+            new SimpleDataSource(entries.iterator()));
+    }
+
+    private void collectEntries(Resource parent, List<Resource> result,
+                                ResourceResolver resolver) {
+        for (Resource child : parent.getChildren()) {
+            String rt = child.getValueMap().get("sling:resourceType", String.class);
+            if (rt == null) continue;
+            // recurse into containers, skip non-interactive types, add data fields
+            if (isContainer(rt)) {
+                collectEntries(child, result, resolver);
+            } else if (isDataField(rt)) {
+                ValueMap vm = child.getValueMap();
+                String fieldName = vm.get("name", child.getName());
+                String label = vm.get("fieldLabel", fieldName);
+                result.add(createEntry(resolver, label + " (" + fieldName + ")", fieldName));
+            }
+        }
+    }
+
+    private Resource createEntry(ResourceResolver resolver, String text, String value) {
+        Map<String, Object> map = new HashMap<>();
+        map.put("text", text);
+        map.put("value", value);
+        return new ValueMapResource(resolver, "", JcrConstants.NT_UNSTRUCTURED,
+            new ValueMapDecorator(map));
+    }
+}
+```
+
+**Required imports:**
+```java
+import com.adobe.granite.ui.components.ds.DataSource;
+import com.adobe.granite.ui.components.ds.SimpleDataSource;
+import com.adobe.granite.ui.components.ds.ValueMapResource;
+import org.apache.sling.api.wrappers.ValueMapDecorator;
+import org.apache.jackrabbit.JcrConstants;
+```
+
+---
+
+## 2. Wiring the Datasource in the Dialog XML
+
+Point the select's datasource node to the servlet's resource type. The suffix is injected automatically by Granite UI as the path of the component being edited.
+
+```xml
+<mySelect
+    jcr:primaryType="nt:unstructured"
+    sling:resourceType="granite/ui/components/coral/foundation/form/select"
+    fieldLabel="Select a Form Field"
+    multiple="{Boolean}true"
+    name="./myFieldRef">
+    <datasource
+        jcr:primaryType="nt:unstructured"
+        sling:resourceType="core/fd/components/form/container/v2/container/datasource/myfields"/>
+</mySelect>
+```
+
+Create the datasource node in the content package:
+```
+ui.af.apps/.../container/v2/container/datasource/myfields/
+└── .content.xml   ← jcr:primaryType="sling:Folder"
+```
+
+Register the resource type constant in `FormConstants.java`:
+```java
+public static final String RT_FD_FORM_MYFIELDS_DATASOURCE_V1 =
+    RT_FD_FORM_PREFIX + "container/v2/container/datasource/myfields";
+```
+
+---
+
+## 3. Exclusion Pattern for Form Tree Traversal
+
+When collecting compatible form fields, use fragment-matching exclusion sets rather than resource type equality. This handles version suffixes (`/v1/`, `/v2/`) automatically:
+
+```java
+private static final Set<String> CONTAINER_FRAGMENTS = new HashSet<>(Arrays.asList(
+    "form/container/", "form/panel/", "form/panelcontainer/",
+    "form/accordion/", "form/wizard/", "form/tabsontop/",
+    "form/verticaltabs/", "form/fragmentcontainer"
+));
+
+private static final Set<String> SKIP_FRAGMENTS = new HashSet<>(Arrays.asList(
+    "form/text/v", "form/title/", "form/image/", "form/button/",
+    "form/actions/", "form/recaptcha", "form/hcaptcha", "form/terms"
+));
+
+private static boolean matchesAny(String rt, Set<String> fragments) {
+    for (String f : fragments) {
+        if (rt.contains(f)) return true;
+    }
+    return false;
+}
+```
+
+Use `rt.startsWith(FormConstants.RT_FD_FORM_PREFIX)` to skip non-form components before the exclusion checks.
diff --git a/.claude/skills/create-core-component/references/editor-clientlib.md b/.claude/skills/create-core-component/references/editor-clientlib.md
new file mode 100644
index 0000000000..89379ee645
--- /dev/null
+++ b/.claude/skills/create-core-component/references/editor-clientlib.md
@@ -0,0 +1,157 @@
+# Editor Clientlib for Dialog Interactivity
+
+When a FormContainer dialog tab (or any complex author dialog) needs JavaScript-driven conditional field visibility, add an editor clientlib alongside the dialog. This is separate from the component's `runtime` clientlib — it runs only in the AEM author UI.
+
+---
+
+## 1. Clientlib Structure
+
+```
+ui.af.apps/.../form/container/v2/container/
+└── clientlibs/
+    └── editor/
+        ├── .content.xml           ← cq:ClientLibraryFolder
+        ├── js.txt
+        └── js/
+            └── myTabDialog.js
+```
+
+**`.content.xml`:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0"
+          xmlns:jcr="http://www.jcp.org/jcr/1.0"
+    jcr:primaryType="cq:ClientLibraryFolder"
+    allowProxy="{Boolean}true"
+    categories="[core.forms.components.container.v2.editor]"/>
+```
+
+Wire it to the dialog by adding the category to `extraClientlibs` on the dialog's `.content.xml`:
+```xml
+extraClientlibs="[core.forms.components.container.v1.editor,core.forms.components.container.v2.editor]"
+```
+
+---
+
+## 2. JS Boilerplate
+
+```javascript
+(function($, channel, Coral) {
+    "use strict";
+
+    var SELECTORS = {
+        myTab: ".cmp-adaptiveform-container__mytab",
+        enableCheckbox: ".cmp-adaptiveform-container__enable-feature",
+        configSection: ".cmp-adaptiveform-container__config-section",
+        sourceSelect: ".cmp-adaptiveform-container__source-select",
+        autocompleteField: ".cmp-adaptiveform-container__autocomplete",
+        textField: ".cmp-adaptiveform-container__text-input"
+    };
+
+    /**
+     * Returns the value from a coral-select, handling granite:class on a wrapper.
+     */
+    function getSelectValue($el) {
+        var cs = $el.is("coral-select") ? $el[0] : $el.find("coral-select")[0];
+        return cs ? (cs.value || "") : "";
+    }
+
+    /**
+     * Show/hide a field's fieldwrapper, capped at a known boundary to prevent
+     * accidentally hiding parent containers.
+     */
+    function setVisible($el, visible, $boundary) {
+        var $candidate = $el.closest(".coral-Form-fieldwrapper");
+        var useWrapper = $candidate.length && (!$boundary || $.contains($boundary[0], $candidate[0]));
+        (useWrapper ? $candidate : $el).toggle(visible);
+    }
+
+    function applySourceRules($item) {
+        var val = getSelectValue($item.find(SELECTORS.sourceSelect));
+        // Treat "" same as the default option to handle pre-Coral-upgrade state
+        setVisible($item.find(SELECTORS.autocompleteField), val === "form" || val === "", $item);
+        setVisible($item.find(SELECTORS.textField), val === "typed", $item);
+    }
+
+    function initDialog(dialog) {
+        var $dialog = $(dialog);
+        if (!$dialog.find(SELECTORS.myTab).length) return;
+
+        // CRITICAL: register all listeners BEFORE any code that adds multifield items.
+        // Coral.commons.ready may fire synchronously — if a listener is not yet registered
+        // when an item is programmatically added, its coral-collection:add event is missed.
+        $dialog.on("change", SELECTORS.enableCheckbox, function() {
+            $dialog.find(SELECTORS.configSection).toggle(isEnabled($dialog));
+        });
+
+        $dialog.on("change", SELECTORS.sourceSelect, function(e) {
+            applySourceRules($(e.target).closest(".your-item-class"));
+        });
+
+        $dialog.on("coral-collection:add", "coral-multifield[name='./items/item']", function(e) {
+            var newItem = e.detail.item;
+            // Immediately hide default-off fields BEFORE Coral upgrades sub-components.
+            // This prevents a flash where all fields appear simultaneously.
+            var $imm = $(newItem).find(".your-item-class");
+            if ($imm.length) {
+                setVisible($imm.find(SELECTORS.textField), false, $imm);
+            }
+            Coral.commons.ready(newItem, function() {
+                var $item = $(newItem).find(".your-item-class");
+                if ($item.length) {
+                    applySourceRules($item);
+                }
+            });
+        });
+
+        // Initialize existing items (for re-opened dialogs with saved data).
+        // We are inside Coral.commons.ready(dialog), so all existing Coral selects are ready.
+        $dialog.find(".your-item-class").each(function() {
+            var $item = $(this);
+            setVisible($item.find(SELECTORS.textField), false, $item); // default-off pre-hide
+            applySourceRules($item);
+        });
+
+        // Initialize top-level checkbox state
+        $dialog.find(SELECTORS.configSection).toggle(isEnabled($dialog));
+    }
+
+    channel.on("dialog-ready", function() {
+        var dialog = $(".cq-dialog")[0];
+        if (dialog) {
+            Coral.commons.ready(dialog, function() {
+                initDialog(dialog);
+            });
+        }
+    });
+
+})(jQuery, jQuery(document), Coral);
+```
+
+---
+
+## 3. Key Patterns
+
+| Pattern | Rule |
+|---------|------|
+| Listener registration order | Always register `coral-collection:add` and other listeners BEFORE any code that triggers item insertion. `Coral.commons.ready` may fire synchronously. |
+| Default-off fields in new items | Immediately hide them on `e.detail.item` before calling `Coral.commons.ready`. The DOM is ready; Coral sub-components are not. |
+| `getSelectValue` | Never read `$("coral-select").val()` — use `coralSelect.value` (the DOM property). Wrap so it handles both direct select and granite:class wrapper. |
+| `val === ""` as default | When a select has no `emptyText` and the first item is the default, Coral returns the first item's value when upgraded. Before upgrade, it returns `""`. Treat both the same in your rules function. |
+| `setVisible` boundary | Cap `.closest(".coral-Form-fieldwrapper")` at a known container boundary so it never traverses up to a parent container fieldwrapper and hides more than intended. |
+| Dialog submit validation | Use `channel.on("cq-dialog-submit.namespaced", function(e) { if (!valid) { e.preventDefault(); e.stopImmediatePropagation(); } })` for required-field validation. |
+
+---
+
+## 4. Select Default Behavior (no `emptyText`)
+
+Omitting `emptyText` from a Granite UI `form/select` makes the first `<items>` child the pre-selected default. No placeholder is shown. This is the correct pattern when there is always a valid default (e.g., "From Form Field", "None"). Only add `emptyText="Select"` when forcing the author to make an explicit choice before saving.
+
+---
+
+## 5. Editor JS Safety
+
+Applies to every author-side script (`clientlibs/editor/js/*.js`), not just dialog-interactivity scripts:
+
+- **Never assign `innerHTML`** from a value — use `textContent`. Even `Granite.I18n.get(...)` output should go through `textContent` (a translator could introduce markup).
+- **Do not wrap locale-neutral format strings** (e.g. `'YYYY-MM-DD'`) in `Granite.I18n.get(...)`. Use a plain constant; only run genuinely translatable sentences through `I18n.get`.
diff --git a/.claude/skills/create-core-component/references/runtime-view-js.md b/.claude/skills/create-core-component/references/runtime-view-js.md
index 520b48d5e7..bee1d3b60d 100644
--- a/.claude/skills/create-core-component/references/runtime-view-js.md
+++ b/.claude/skills/create-core-component/references/runtime-view-js.md
@@ -97,9 +97,5 @@ value. Extra rules:
 
 ## Editor clientlib JS (`clientlibs/editor/js/*.js`)
 
-- **Never assign `innerHTML`** from a value — use `textContent`. Even
-  `Granite.I18n.get(...)` output should go through `textContent` (a translator
-  could introduce markup).
-- **Do not wrap locale-neutral format strings** (e.g. `'YYYY-MM-DD'`) in
-  `Granite.I18n.get(...)`. Use a plain constant; only run genuinely translatable
-  sentences through `I18n.get`.
+Author-side scripts have their own safety rules (`innerHTML`/`textContent`, i18n) — see
+`references/editor-clientlib.md`.
diff --git a/.claude/skills/create-core-component/references/templates.md b/.claude/skills/create-core-component/references/templates.md
index 9f431b7fc2..ec1fcd815f 100644
--- a/.claude/skills/create-core-component/references/templates.md
+++ b/.claude/skills/create-core-component/references/templates.md
@@ -116,6 +116,90 @@ public class {ComponentName}Impl extends {BaseClass} implements {ComponentName}
 
 ---
 
+## 2b. Sling Model – Display/Text Components
+
+Use this variant instead of template #2 when `sling:resourceSuperType` is `core/fd/components/form/text/v1/text` — i.e., components that render authored HTML content in a `__value` div and show a title label above it (e.g., Adobe Sign Block, text component extensions).
+
+**Path:** `bundles/af-core/src/main/java/com/adobe/cq/forms/core/components/internal/models/v1/form/{ComponentName}Impl.java`
+
+```java
+/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~ Copyright {currentYear} Adobe
+ ~
+ ~ Licensed under the Apache License, Version 2.0 (the "License");
+ ~ you may not use this file except in compliance with the License.
+ ~ You may obtain a copy of the License at
+ ~
+ ~     http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
+package com.adobe.cq.forms.core.components.internal.models.v1.form;
+
+import com.adobe.cq.export.json.ComponentExporter;
+import com.adobe.cq.export.json.ExporterConstants;
+import com.adobe.cq.forms.core.components.internal.form.FormConstants;
+import com.adobe.cq.forms.core.components.internal.form.ReservedProperties;
+import com.adobe.cq.forms.core.components.models.form.Base;
+import com.adobe.cq.forms.core.components.models.form.FieldType;
+import com.adobe.cq.forms.core.components.models.form.Text;
+import com.adobe.cq.forms.core.components.util.AbstractBaseImpl;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import org.apache.sling.api.SlingHttpServletRequest;
+import org.apache.sling.api.resource.Resource;
+import org.apache.sling.models.annotations.Default;
+import org.apache.sling.models.annotations.Exporter;
+import org.apache.sling.models.annotations.Model;
+import org.apache.sling.models.annotations.injectorspecific.InjectionStrategy;
+import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
+
+@Model(
+    adaptables = { SlingHttpServletRequest.class, Resource.class },
+    adapters = { Text.class, Base.class, ComponentExporter.class },
+    resourceType = { FormConstants.RT_FD_FORM_{COMPONENT_NAME}_V1 })
+@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME,
+          extensions = ExporterConstants.SLING_MODEL_EXTENSION)
+public class {ComponentName}Impl extends AbstractBaseImpl implements Text {
+
+    @ValueMapValue(injectionStrategy = InjectionStrategy.OPTIONAL,
+                  name = ReservedProperties.PN_TEXT_IS_RICH)
+    @Default(booleanValues = false)
+    private boolean textIsRich;
+
+    @Override
+    public String getValue() {
+        return translate("value", value);
+    }
+
+    @Override
+    public boolean isRichText() {
+        return textIsRich;
+    }
+
+    @Override
+    @JsonIgnore
+    public String getText() {
+        return getValue();
+    }
+
+    @Override
+    public String getFieldType() {
+        return super.getFieldType(FieldType.PLAIN_TEXT);
+    }
+}
+```
+
+**Rules for this variant:**
+- `adapters` MUST include both `Text.class` and `Base.class` — `Base.class` wires `getLabel()` into the HTL `baseModel.label.*` calls and the exported form JSON `label` object
+- Extend `AbstractBaseImpl`, NOT `TextImpl` — `TextImpl` returns `null` for `getLabel()`
+- Use HTL template 7c for the corresponding HTML template
+
+---
+
 ## 3. FormConstants Entry
 
 Add to `bundles/af-core/src/main/java/com/adobe/cq/forms/core/components/internal/form/FormConstants.java`:
@@ -238,9 +322,47 @@ public class {ComponentName}ImplTest {
 
 ---
 
-## 7. HTL Template
+## 6b. Instance Defaults (`_cq_template.xml`)
+
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/_cq_template.xml`
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/{componentname}.html`
+Sets the default property values for a newly dropped component instance.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
+    jcr:primaryType="nt:unstructured"
+    jcr:title="{componentTitle}"
+    fieldType="{fieldType}"/>
+```
+
+For step components that share `fieldType="plain-text"` but need distinct rendering, add `fd:viewType`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:fd="http://www.adobe.com/aemfd/fd/components/adaptive-form/formmetadata/2.0"
+    xmlns:jcr="http://www.jcp.org/jcr/1.0"
+    jcr:primaryType="nt:unstructured"
+    jcr:title="{componentTitle}"
+    fieldType="plain-text"
+    fd:viewType="{component-name}"/>
+```
+
+For components that are hidden at runtime but visible in author edit mode (e.g., signing blocks revealed by an external SDK), add:
+
+```xml
+    visible="{Boolean}false"
+```
+
+The `{fieldType}` value must be kebab-case: `text-input`, `number-input`, `plain-text`, etc. See `references/component-anatomy.md` for the full `FieldType` mapping.
+
+---
+
+## 7. HTL Template – Field Components
+
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/{componentname}.html`
+
+Use for components that capture a user value. For step/display components without a widget, use template 7b. For display/text with a title label and rich-text value area, use template 7c.
 
 ```html
 <!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -300,7 +422,7 @@ public class {ComponentName}ImplTest {
            readonly="${{componentname}.readOnly}"
            required="${{componentname}.required}"
            placeholder="${{componentname}.placeHolder}"
-           aria-label="${{componentname}.label.value}"
+           aria-describedby="${{componentname}.id}__errormessage ${{componentname}.id}__longdescription ${{componentname}.id}__shortdescription"
            dir="auto"/>
 
     <!-- Short Description (tooltip) -->
@@ -322,9 +444,116 @@ public class {ComponentName}ImplTest {
 
 ---
 
+## 7b. HTL Template – Step / Display Components
+
+Use for step or display components with no interactive widget. Binds the Impl class directly since step components typically have no separate public interface.
+
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/{componentname}.html`
+
+```html
+<!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ Copyright {currentYear} Adobe
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
+<sly data-sly-use.{componentname}="com.adobe.cq.forms.core.components.internal.models.v1.form.{ComponentName}Impl"
+     data-sly-use.clientlib="${'/libs/granite/sightly/templates/clientlib.html'}"></sly>
+
+<div data-sly-use.formstructparser="com.adobe.cq.forms.core.components.models.form.FormStructureParser"
+     class="cmp-adaptiveform-{componentname}"
+     data-cmp-is="adaptiveForm{ComponentName}"
+     data-cmp-visible="${{componentname}.visible ? 'true' : 'false'}"
+     id="${{componentname}.id}"
+     data-cmp-adaptiveformcontainer-path="${formstructparser.formContainerPath}">
+    <!--
+      Step-specific content here.
+      For a step that renders child components:
+        <sly data-sly-resource="${'.' @ resourceType='core/fd/components/form/container/v2/container'}"></sly>
+      For custom rendering (signature iframe, summary text), put HTML here.
+    -->
+    <div class="cmp-adaptiveform-{componentname}__content">
+        <!-- component-specific structure -->
+    </div>
+</div>
+```
+
+---
+
+## 7c. HTL Template – Display/Text with Label and Rich-Text Value
+
+Use when the component renders authored HTML content (`value`) with a title label above it — e.g., Adobe Sign Block or Text component extensions. Requires two Sling Model bindings: `textModel` for content, `baseModel` for the label. Use Sling Model template 2b.
+
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/{componentname}.html`
+
+```html
+<!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ Copyright {currentYear} Adobe
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
+<div data-sly-use.textModel="com.adobe.cq.forms.core.components.models.form.Text"
+     data-sly-use.baseModel="com.adobe.cq.forms.core.components.models.form.Base"
+     data-sly-use.formstructparser="com.adobe.cq.forms.core.components.models.form.FormStructureParser"
+     data-sly-use.templates="core/wcm/components/commons/v1/templates.html"
+     data-sly-use.labelTemplate="core/fd/components/af-commons/v1/fieldTemplates/label.html"
+     data-cmp-is="adaptiveForm{ComponentName}"
+     id="${textModel.id}"
+     data-cmp-data-layer="${textModel.data.json}"
+     data-cmp-adaptiveformcontainer-path="${formstructparser.formContainerPath}"
+     data-cmp-visible="${textModel.visible ? 'true' : 'false'}"
+     class="cmp-adaptiveform-{componentname} ${resource.properties['styleClass']}">
+    <div class="cmp-adaptiveform-{componentname}__label-container">
+        <div data-sly-call="${labelTemplate.label @
+                 componentId=textModel.id,
+                 labelValue=baseModel.label.value,
+                 labelVisible=baseModel.label.visible,
+                 labelRichText=baseModel.label.richText,
+                 bemBlock='cmp-adaptiveform-{componentname}'}"
+             data-sly-unwrap></div>
+    </div>
+    <!--
+      Always render __value unconditionally — JS getWidget() must never return null.
+      Put conditional content inside using <sly data-sly-test>, never on the outer __value div.
+    -->
+    <div class="cmp-adaptiveform-{componentname}__value">
+        <sly data-sly-test.richContent="${textModel.value}">
+            <div data-sly-unwrap="${textModel.isRichText}">${richContent @ context = textModel.isRichText ? 'html' : 'text'}</div>
+        </sly>
+    </div>
+</div>
+<sly data-sly-call="${templates.placeholder @ isEmpty = !richContent, classAppend='cmp-adaptiveform-{componentname}'}"></sly>
+```
+
+**Notes:**
+- Use `baseModel.label.value` (not `resource.properties['jcr:title']`) — it applies i18n translation and correctly reads `hideTitle`
+- `Text` has no `getLabel()` — `Base.class` MUST be in the Sling Model `adapters` array (use template 2b)
+- `styleClass` is the only acceptable `resource.properties` read in this template
+
+---
+
 ## 8. Renderer JS
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/{componentname}.js`
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/{componentname}.js`
 
 ```javascript
 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -347,7 +576,7 @@ use(function () {
 
 ## 9. Author Dialog
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/_cq_dialog/.content.xml`
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/_cq_dialog/.content.xml`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -418,7 +647,7 @@ use(function () {
 
 ## 10. Site Clientlib Definition
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/clientlibs/site/.content.xml`
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/clientlibs/site/.content.xml`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -446,7 +675,7 @@ use(function () {
 
 ## 11. Client-Side View Class
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/clientlibs/site/js/{componentname}view.js`
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/clientlibs/site/js/{componentname}view.js`
 
 ```javascript
 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -561,65 +790,197 @@ use(function () {
 
 ---
 
-## 12. LESS Stylesheet
+## 11b. Client-Side View – Step / Container Components
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/clientlibs/site/css/{componentname}.less`
+Use when the component has no widget and does not capture a value. Extends `FormView.FormContainer` instead of `FormFieldBase`.
 
-```less
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/clientlibs/site/js/{componentname}view.js`
+
+```javascript
 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ~ Copyright {currentYear} Adobe
+ ~
+ ~ Licensed under the Apache License, Version 2.0 (the "License");
+ ~ you may not use this file except in compliance with the License.
+ ~ You may obtain a copy of the License at
+ ~
+ ~     http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
+(function() {
+    "use strict";
 
-.cmp-adaptiveform-{componentname} {
-    &__label {
-        display: block;
-        margin-bottom: 4px;
-    }
-
-    &__label-container {
-        display: flex;
-        align-items: center;
-    }
+    class {ComponentName}View extends FormView.FormContainer {
+        static NS = FormView.Constants.NS;
+        static IS = "adaptiveForm{ComponentName}";
+        static bemBlock = 'cmp-adaptiveform-{componentname}';
 
-    &__widget {
-        width: 100%;
-        box-sizing: border-box;
+        static selectors = {
+            self: "[data-" + {ComponentName}View.NS + '-is="' + {ComponentName}View.IS + '"]'
+        };
 
-        &:focus {
-            outline: 2px solid var(--cmp-adaptiveform-focus-color, #0265DC);
-            outline-offset: 2px;
+        constructor(params) {
+            super(params);
         }
 
-        &[aria-invalid="true"] {
-            border-color: var(--cmp-adaptiveform-error-color, #D7373F);
+        initialize() {
+            super.initialize();
+            // component-specific setup (e.g., load external SDK, observe model state changes)
         }
     }
 
-    &__errormessage {
-        color: var(--cmp-adaptiveform-error-color, #D7373F);
-        font-size: 0.875rem;
+    FormView.Utils.setupField(({element, formContainer}) => {
+        return new {ComponentName}View({element, formContainer});
+    }, {ComponentName}View.selectors.self);
+})();
+```
+
+---
+
+## 11c. updateValue and updateLabel Overrides for Rich-Text Components
+
+Add these method overrides to any view class that renders authored HTML inside a `__value` div alongside a `__label-container`. Without the `updateLabel` guard, the form engine calling `updateLabel(null)` on model bind will throw. Without the `updateValue` guard, the default implementation may overwrite the entire element `innerHTML` and destroy the label.
+
+```javascript
+updateValue(value) {
+    const actualValue = typeof value === "undefined" ? "" : value;
+
+    const sanitizedValue = window.DOMPurify ? window.DOMPurify.sanitize(actualValue, {
+        ALLOWED_TAGS: [
+            "b", "strong", "i", "em", "u", "sub", "sup", "small",
+            "blockquote", "ul", "ol", "li", "a", "br", "p", "span",
+            "h1", "h2", "h3", "h4", "h5", "h6"
+        ],
+        ALLOWED_ATTR: [
+            "href", "target", "rel", "class", "id", "style"
+            // add any custom data-* attributes your SDK requires
+        ]
+    }) : actualValue;
+
+    const widget = this.getWidget();
+    if (widget) {
+        widget.innerHTML = sanitizedValue;
     }
+    // No else fallback — the __value div must always be present in the DOM (see template 7c).
+    // If getWidget() returns null, fix the HTL so __value renders unconditionally.
+}
 
-    &__questionmark {
-        cursor: pointer;
-        background: none;
-        border: none;
-        padding: 4px;
+updateLabel(label) {
+    if (label) {
+        super.updateLabel(label);
     }
+}
+```
+
+---
 
-    &__shortdescription,
-    &__longdescription {
-        font-size: 0.875rem;
-        color: var(--cmp-adaptiveform-description-color, #6E6E6E);
+## 12. CSS Stub and Theme SCSS
+
+Styles are split across two repositories — see `references/css-architecture.md` for the full explanation.
+
+### 12a. CSS Stub (in `aem-core-forms-components`)
+
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/clientlibs/site/css/{componentname}.less`
+
+Declares every BEM class the HTL template emits with **empty rules only** — no CSS property values. All visual styling belongs in `aem-forms-theme-canvas`.
+
+```less
+/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~ Copyright {currentYear} Adobe
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
+
+.cmp-adaptiveform-{componentname} { }
+.cmp-adaptiveform-{componentname}__label-container { }
+.cmp-adaptiveform-{componentname}__label { }
+.cmp-adaptiveform-{componentname}__widget { }
+.cmp-adaptiveform-{componentname}__questionmark { }
+.cmp-adaptiveform-{componentname}__shortdescription { }
+.cmp-adaptiveform-{componentname}__longdescription { }
+.cmp-adaptiveform-{componentname}__errormessage { }
+```
+
+Add a rule for every additional BEM element introduced in the HTL template. Do not add any CSS properties here.
+
+### 12b. Theme SCSS (in `aem-forms-theme-canvas`)
+
+**Path:** `aem-forms-theme-canvas/src/components/{componentname}/_{componentname}.scss`
+
+All actual visual styles using design tokens from `src/site/_variables.scss`.
+
+```scss
+// {ComponentName} — Core Adaptive Form Component
+
+.cmp-adaptiveform-{componentname} {
+    display: flex;
+    flex-direction: column;
+    margin: $field-margin;
+    font-family: $font-family;
+    font-size: $font-md;
+    color: $dark-gray;
+}
+
+.cmp-adaptiveform-{componentname}__label-container {
+    display: flex;
+    align-items: center;
+}
+
+.cmp-adaptiveform-{componentname}__label {
+    font-size: $font-sm;
+    color: $dark-gray;
+}
+
+.cmp-adaptiveform-{componentname}__widget {
+    height: $field-height;
+    padding-left: $field-padding-left;
+    border: 1px solid $very-light-gray;
+    border-radius: 4px;
+    font-size: $font-md;
+
+    &:focus {
+        outline: 2px solid $focus-ring-color;
+        outline-offset: 2px;
     }
 }
+
+/* Validation states — written by JS view via data-cmp-valid attribute */
+.cmp-adaptiveform-{componentname}[data-cmp-valid=false] {
+    .cmp-adaptiveform-{componentname}__widget { border-left: 3px solid $error; }
+}
+
+.cmp-adaptiveform-{componentname}[data-cmp-valid=true] {
+    .cmp-adaptiveform-{componentname}__widget { border-left: 3px solid $success; }
+}
+
+.cmp-adaptiveform-{componentname}__errormessage {
+    font-size: $font-xsm;
+    color: $error;
+}
+
+.cmp-adaptiveform-{componentname}__shortdescription,
+.cmp-adaptiveform-{componentname}__longdescription {
+    font-size: $font-xsm;
+    color: $gray;
+}
+```
+
+After creating the SCSS file, import it in `aem-forms-theme-canvas/src/theme.scss`:
+
+```scss
+@import './components/{componentname}/_{componentname}.scss';
 ```
 
+Then build: `npm run build && npm run create-clientlib` from `aem-forms-theme-canvas/`.
+
 ---
 
 ## 13. Editor Clientlib
 
-**Path:** `ui.af.apps/.../form/{componentname}/v1/{componentname}/clientlibs/editor/.content.xml`
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/clientlibs/editor/.content.xml`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -702,3 +1063,65 @@ use(function () {
     </jcr:content>
 </jcr:root>
 ```
+
+---
+
+## 16. Edit Config (`_cq_editConfig.xml`)
+
+**Path:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentname}/v1/{componentname}/_cq_editConfig.xml`
+
+Every form component needs this file to configure the author toolbar. Place it alongside `.content.xml`.
+
+### Standard (all field and step components)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0"
+    xmlns:jcr="http://www.jcp.org/jcr/1.0"
+    jcr:primaryType="cq:EditConfig"
+    cq:actions="[-,-,copymove,delete,-,-,-]"
+    cq:dialogMode="floating"
+    cq:layout="editbar"
+    cq:disableTargeting="{Boolean}true"/>
+```
+
+### Extended – Display/Text Components with Inplace Rich-Text Editing
+
+For components that use HTL template 7c and support inplace editing of the `__value` area:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0"
+    xmlns:jcr="http://www.jcp.org/jcr/1.0"
+    xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
+    jcr:primaryType="cq:EditConfig"
+    cq:actions="[-,-,copymove,delete,-,-,-]"
+    cq:dialogMode="floating"
+    cq:layout="editbar"
+    cq:disableTargeting="{Boolean}true">
+    <cq:inplaceEditing
+        jcr:primaryType="cq:InplaceEditingConfig"
+        active="{Boolean}true"
+        editorType="text"
+        editElementQuery=".cmp-adaptiveform-{componentname}__value"
+        name="./value"
+        textPropertyName="./value"
+        hideLabel="{Boolean}true">
+        <config jcr:primaryType="nt:unstructured">
+            <rtePlugins jcr:primaryType="nt:unstructured">
+                <format jcr:primaryType="nt:unstructured" features="bold,italic,underline"/>
+                <fullscreen jcr:primaryType="nt:unstructured" features="*"/>
+                <control jcr:primaryType="nt:unstructured" features="close,save"/>
+            </rtePlugins>
+            <uiSettings jcr:primaryType="nt:unstructured">
+                <cui jcr:primaryType="nt:unstructured">
+                    <inline jcr:primaryType="nt:unstructured"
+                        toolbar="[format#bold,format#italic,format#underline,fullscreen#start,control#close,control#save]"/>
+                </cui>
+            </uiSettings>
+        </config>
+    </cq:inplaceEditing>
+</jcr:root>
+```
+
+For components needing a custom RTE plugin, add the plugin entry to `rtePlugins` and insert the plugin command before `fullscreen#start` in the `toolbar` string.
diff --git a/.claude/skills/create-core-component/references/verification-checklist.md b/.claude/skills/create-core-component/references/verification-checklist.md
new file mode 100644
index 0000000000..be5eb7bbc3
--- /dev/null
+++ b/.claude/skills/create-core-component/references/verification-checklist.md
@@ -0,0 +1,94 @@
+# Post-Implementation Verification Checklist
+
+Work through every item after all files are written. Fix all failures before declaring the component complete.
+
+---
+
+## Structure
+
+- [ ] Component node path follows `core/fd/components/form/{name}/v1/{name}/`
+- [ ] `.content.xml` has `jcr:primaryType="cq:Component"` and correct `sling:resourceSuperType`
+- [ ] `_cq_template.xml` has `fieldType` matching the Core Forms schema value (e.g., `text-input`, not `textInput`)
+- [ ] `_cq_editConfig.xml` is present alongside `.content.xml` with `cq:disableTargeting="{Boolean}true"`
+- [ ] Clientlib category in `runtime/.content.xml` follows `core.forms.components.{name}.v1.runtime`
+- [ ] Clientlib `dependencies` includes `core.forms.components.base.runtime`
+
+## Wiring
+
+- [ ] `core-forms-components-runtime-all/.content.xml` — `core.forms.components.{name}.v1.runtime` is present in the `embedsValue` array
+- [ ] `aem-forms-theme-canvas/src/theme.scss` — `@import './components/{name}/_{name}.scss'` is present
+- [ ] *(if applicable)* `FormConstants.java` — `RT_FD_FORM_{NAME_UPPER}_V1` constant added and matches the JCR path exactly
+- [ ] *(if new i18n messages added)* All 10 language files in `resources/i18n/` updated with the new message keys
+
+## Container Registration
+
+- [ ] Component group is allowed in the **integration test** template policy (`it/content/.../wcm/policies/.content.xml`)
+- [ ] Component group is allowed in the **production** template policy (`conf/{siteName}/settings/wcm/policies/`) — verify by checking component appears in author picker
+- [ ] *(if component needs form-level properties)* FormContainer dialog overlay created with the new tab — dialog opens on the form container and shows the new tab correctly in authoring mode (see `references/wiring-steps.md`)
+- [ ] *(if component reads container properties)* `getContainerProperty()` pattern in Sling Model correctly traverses to parent container — verified via unit test with a parent container resource in `test-content.json` (see `references/wiring-steps.md`)
+- [ ] No explicit wizard/panel step registration needed — wizard and panel discover child components dynamically via JCR child iteration
+
+## CSS — Two-Layer Check
+
+- [ ] **Layer 1 (stub file in `aem-core-forms-components`):** `clientlibs/runtime/css/{name}view.css` exists and declares every BEM class emitted by the HTL template — all rules are empty (`{ }`)
+- [ ] `clientlibs/runtime/css.txt` references `{name}view.css`
+- [ ] Every HTML element in the HTL template that carries a `class` attribute has a corresponding empty rule in the stub file
+- [ ] **Layer 2 (real styles in `aem-forms-theme-canvas`):** `src/components/{name}/_{name}.scss` exists with actual property values
+- [ ] The SCSS file uses only design tokens from `src/site/_variables.scss` — no hardcoded colour or size values
+- [ ] `[data-cmp-valid=false]` and `[data-cmp-valid=true]` attribute selectors are present for interactive field components
+- [ ] The new SCSS file is imported in `src/theme.scss`
+- [ ] `npm run build` runs without errors in `aem-forms-theme-canvas`
+
+## HTL
+
+- [ ] `data-cmp-is` value matches JS `static IS` exactly
+- [ ] Boolean `data-cmp-*` attributes use ternary `? 'true' : 'false'`
+- [ ] No `<script>` or `<style>` elements in the HTL file
+- [ ] `data-sly-use.model` references the correct Sling Model class
+- [ ] No `data-sly-test` on the `__value` div (for display/text components)
+- [ ] Accessibility: every applicable item in `references/accessibility-checklist.md` is satisfied (aria-describedby triple, live regions, focus, keyboard)
+
+## JavaScript
+
+- [ ] `static IS` copied verbatim to `data-cmp-is` in HTL
+- [ ] `static bemBlock` matches the CSS class on the root `<div>` exactly
+- [ ] All 6 selector methods present for `FormFieldBase` subclasses
+- [ ] `FormView.Utils.setupField` called with the correct selector
+- [ ] No jQuery, no `$`, no `window.jQuery`
+
+## Java (if applicable)
+
+- [ ] `RESOURCE_TYPE` string matches the JCR path exactly
+- [ ] `@Model resourceType` includes `RESOURCE_TYPE`
+- [ ] Only `@ValueMapValue` used for JCR injection (no `@Inject`)
+- [ ] `InjectionStrategy.OPTIONAL` on all optional properties
+- [ ] No imports from `com.adobe.guides.*` or `com.adobe.fd.guide.*`
+- [ ] `getExportedType()` returns `RESOURCE_TYPE`
+
+## Tests
+
+- [ ] `{NamePascal}ImplTest.java` exists and all tests pass: `mvn test -pl bundles/af-core -Dtest={NamePascal}ImplTest`
+- [ ] `test-content.json` has at least two nodes: one fully configured and one with no custom properties
+- [ ] JSON export snapshot file exists at `form/{name}/{name}.json` and `testJSONExport()` passes without diff
+- [ ] JaCoCo coverage is ≥ 60% — confirmed by running `mvn verify -pl bundles/af-core` (build fails below threshold)
+- [ ] *(if `it/` content added)* Integration test content `.content.xml` present and referenced in policy
+
+## Feature Parity for Dropped JCR Properties (migration only)
+
+For every property listed as **dropped** in the migration plan's Property Mapping table, verify the Core equivalent is actually wired up:
+- [ ] All expression properties (`visibleExp`, `enabledExp`, `calculateExp`, `initializeExp`) → Rules Editor tab is present in the Core dialog (confirm via the inherited base dialog; add explicitly if custom dialog was created without it)
+- [ ] `displayPictureClause` / `validatePictureClause` → `displayFormat` / `editFormat` dialog fields are present and documented with the Core format syntax
+- [ ] `css` (CSS Class field) → `_cq_design_dialog` exists with a Style System tab; style classes defined in the template policy; corresponding CSS modifier classes added to theme SCSS
+- [ ] `*InlineStyles` / `height` / `width` → equivalent CSS rules exist in the theme SCSS targeting the BEM element selectors
+- [ ] `fieldLayout` → HTL template renders the correct layout structure directly in BEM HTML
+- [ ] `colspan` → responsibility delegated to the form container / panel
+- [ ] `navTitle` → the component's `jcr:title` / `label` is set correctly
+- [ ] `clientLibRef` → component's own clientlib node is created and its category is embedded in the form's runtime-all clientlib
+- [ ] No dropped property has a blank "Core equivalent" cell — every dropped property has an explicit resolution
+
+## No Cross-Referencing
+
+- [ ] Zero imports or references to foundation packages (`com.adobe.guides`, `com.adobe.fd.guide`, `guideWidget`)
+- [ ] No JSP includes or JSP code fragments
+- [ ] No XFA model properties included without explicit user approval
+- [ ] Component does not require foundation forms overlay to be installed
diff --git a/.claude/skills/create-core-component/references/widget-patterns.md b/.claude/skills/create-core-component/references/widget-patterns.md
new file mode 100644
index 0000000000..3f2209468f
--- /dev/null
+++ b/.claude/skills/create-core-component/references/widget-patterns.md
@@ -0,0 +1,89 @@
+# Widget HTML Patterns
+
+Replace the `<input>` placeholder in the HTL field template (template #7) with the appropriate element for the component type.
+
+## Standard widget attributes
+
+Every widget element carries this base attribute set. The patterns below list **only the attributes that are added or changed** on top of it — do not re-type these on each widget.
+
+```html
+class="cmp-adaptiveform-{componentname}__widget"
+id="${widgetId}"
+name="${{componentname}.name}"
+data-cmp-data-layer="${{componentname}.data.json}"
+disabled="${!{componentname}.enabled}"
+readonly="${{componentname}.readOnly}"
+required="${{componentname}.required}"
+aria-describedby="${{componentname}.id}__errormessage ${{componentname}.id}__longdescription ${{componentname}.id}__shortdescription"
+```
+
+Notes:
+- `readonly` does not apply to `file`, `select`, or custom `div` widgets — omit it there.
+- The `aria-describedby` triple (errormessage / longdescription / shortdescription) is mandatory on every widget; see `references/accessibility-checklist.md`.
+
+## Single-Line Text Input
+
+Base attributes plus:
+
+```html
+<input type="text" value="${{componentname}.default}"
+       placeholder="${{componentname}.placeHolder}"
+       minlength="${{componentname}.minLength}" maxlength="${{componentname}.maxLength}"
+       dir="auto"/>
+```
+
+## Multi-Line Textarea (shown when `{componentname}.multiLine` is true)
+
+Renders a `<textarea>` when `multiLine` is set, otherwise the single-line `<input>` above. Both carry the base attributes; the textarea adds `placeholder`, `minlength`, `maxlength` (no `value`/`type`/`dir`).
+
+```html
+<textarea data-sly-test="${{componentname}.multiLine}"
+          placeholder="${{componentname}.placeHolder}"
+          minlength="${{componentname}.minLength}" maxlength="${{componentname}.maxLength}">
+</textarea>
+<input data-sly-test="${!{componentname}.multiLine}" type="text"
+       value="${{componentname}.default}" placeholder="${{componentname}.placeHolder}"
+       minlength="${{componentname}.minLength}" maxlength="${{componentname}.maxLength}"
+       dir="auto"/>
+```
+
+## Number Input
+
+Base attributes plus:
+
+```html
+<input type="number" value="${{componentname}.default}"
+       min="${{componentname}.minimum}" max="${{componentname}.maximum}"
+       placeholder="${{componentname}.placeHolder}"/>
+```
+
+## File Input
+
+Base attributes (omit `readonly`) plus:
+
+```html
+<input type="file" accept="${{componentname}.accept}"/>
+```
+
+## Select / Dropdown
+
+Base attributes (omit `readonly`) plus the options list:
+
+```html
+<select>
+    <sly data-sly-list.option="${{componentname}.enumNames}">
+        <option value="${{componentname}.enum[itemList.index]}"
+                selected="${{componentname}.default == {componentname}.enum[itemList.index]}">${option}</option>
+    </sly>
+</select>
+```
+
+## Custom / External Widget (e.g., signature pad, rich text, map)
+
+Base attributes (omit `readonly`) plus `role="presentation"`; JS populates the container:
+
+```html
+<div role="presentation">
+    <!-- JS will populate this container -->
+</div>
+```
diff --git a/.claude/skills/create-core-component/references/wiring-steps.md b/.claude/skills/create-core-component/references/wiring-steps.md
new file mode 100644
index 0000000000..26033773f1
--- /dev/null
+++ b/.claude/skills/create-core-component/references/wiring-steps.md
@@ -0,0 +1,275 @@
+# Wiring Steps and Integration Registration
+
+---
+
+## Wiring Step 1: Embed Clientlib in `core-forms-components-runtime-all`
+
+**File to update:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/af-clientlibs/core-forms-components-runtime-all/.content.xml`
+
+This file has an `embedsValue` array listing every component's runtime clientlib category. Add the new component's category to this list. Without this step, the component's JS and CSS are never loaded when the form renders.
+
+Read the current file first, then add `core.forms.components.{name}.v1.runtime` to the existing array:
+
+```xml
+<!-- existing entry, for reference -->
+embedsValue="[...,core.forms.components.textinput.v1.runtime,...,core.forms.components.{name}.v1.runtime]"
+```
+
+Append at the end of the array. Do not reorder existing entries.
+
+---
+
+## Wiring Step 2: `FormConstants.java` — Resource Type Constant (conditional)
+
+**Only needed if** other Java classes (export processors, servlet filters, `@Model` `resourceType` arrays in other components, etc.) need to reference this component's resource type string.
+
+**File to update:** `bundles/af-core/src/main/java/com/adobe/cq/forms/core/components/internal/form/FormConstants.java`
+
+Add a constant following the existing naming pattern:
+
+```java
+// Resource type constant — follows existing RT_FD_FORM_*_V1 naming convention
+public static final String RT_FD_FORM_{NAME_UPPER}_V1 =
+    "core/fd/components/form/{name}/v1/{name}";
+```
+
+Example for a `signaturestep` component:
+```java
+public static final String RT_FD_FORM_SIGNATURE_STEP_V1 =
+    "core/fd/components/form/signaturestep/v1/signaturestep";
+```
+
+Read the file first to check naming conventions and add in alphabetical order with the other constants.
+
+---
+
+## Wiring Step 3: i18n Additions (conditional)
+
+**When needed:** Only if the component introduces new validation constraint messages beyond the standard ones already in the base runtime. Standard messages (`required`, `minLength`, `maxLength`, `pattern`, `minimum`, `maximum`, `fileSize`, `accept`) are already present and do not need to be added again.
+
+**File to update:** `ui.af.apps/src/main/content/jcr_root/apps/core/fd/af-clientlibs/core-forms-components-runtime-all/resources/i18n/en.json`
+
+Add new message keys following the existing pattern:
+
+```json
+{
+  "...(existing keys)...",
+  "{componentName}CustomConstraintMessage": "Default English message text for the constraint."
+}
+```
+
+**Localization requirement:** The key must be added to **all 10 language files** in the same `i18n/` directory:
+`en.json`, `de.json`, `es.json`, `fr.json`, `it.json`, `ja.json`, `ko-kr.json`, `pt-br.json`, `zh-cn.json`, `zh-tw.json`
+
+For languages you cannot translate, use the English string as a placeholder. Do not omit a language file entry; missing keys fall back to the key name (not the English string) in some runtime versions.
+
+---
+
+## Wiring Step 4: Content Migration
+
+see `migrate-foundation-component` skill.
+
+---
+
+## Wiring Step 5: FormContainer Dialog Extension (conditional)
+
+**When needed:** When the component reads properties authored on the *parent form container*, not on its own JCR node.
+
+The FormContainer's author dialog is at:
+`ui.af.apps/.../form/container/v2/container/_cq_dialog/.content.xml`
+
+Its tabs are: `basic` (form title, prefill, client lib), `dataModel`, `autosave`, `submitActions`, `advanced`.
+
+**Do not edit this file directly.** Instead, create a `_cq_dialog` overlay inside the component's repo using `sling:resourceSuperType` to inherit and extend the FormContainer dialog:
+
+**File to create:** `ui.af.apps/src/main/content/jcr_root/apps/{overlay-path}/form/container/v2/container/_cq_dialog/.content.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
+          xmlns:cq="http://www.day.com/jcr/cq/1.0"
+          xmlns:jcr="http://www.jcp.org/jcr/1.0"
+          xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
+    jcr:primaryType="nt:unstructured"
+    jcr:title="Adaptive Form Container"
+    sling:resourceSuperType="core/fd/components/form/container/v2/container/cq:dialog"
+    sling:resourceType="cq/gui/components/authoring/dialog">
+    <content
+        jcr:primaryType="nt:unstructured"
+        sling:resourceType="granite/ui/components/coral/foundation/container">
+        <items jcr:primaryType="nt:unstructured">
+            <tabs
+                jcr:primaryType="nt:unstructured"
+                sling:resourceType="granite/ui/components/coral/foundation/tabs"
+                maximized="{Boolean}true">
+                <items jcr:primaryType="nt:unstructured">
+
+                    <!-- New tab — add after existing inherited tabs -->
+                    <{tabNodeName}
+                        jcr:primaryType="nt:unstructured"
+                        jcr:title="{Tab Title visible to author}"
+                        sling:resourceType="granite/ui/components/coral/foundation/container">
+                        <items jcr:primaryType="nt:unstructured">
+                            <columns
+                                jcr:primaryType="nt:unstructured"
+                                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
+                                <items jcr:primaryType="nt:unstructured">
+                                    <column
+                                        jcr:primaryType="nt:unstructured"
+                                        sling:resourceType="granite/ui/components/coral/foundation/container">
+                                        <items jcr:primaryType="nt:unstructured">
+
+                                            <!-- Cloud service config picker (for service integrations) -->
+                                            <{configField}
+                                                jcr:primaryType="nt:unstructured"
+                                                sling:resourceType="granite/ui/components/coral/foundation/form/pathfield"
+                                                fieldDescription="Select the {ServiceName} cloud configuration."
+                                                fieldLabel="{ServiceName} Configuration"
+                                                name="./cq:cloudserviceconfigs"
+                                                rootPath="/etc/cloudservices/{service-name}"
+                                                type="cq:Page"/>
+
+                                            <!-- Or a simple text / select field for other form-level properties -->
+                                            <{fieldNodeName}
+                                                jcr:primaryType="nt:unstructured"
+                                                sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
+                                                fieldLabel="{Property Label}"
+                                                fieldDescription="{Help text}"
+                                                name="./{jcr-property-name}"/>
+
+                                        </items>
+                                    </column>
+                                </items>
+                            </columns>
+                        </items>
+                    </{tabNodeName}>
+
+                </items>
+            </tabs>
+        </items>
+    </content>
+</jcr:root>
+```
+
+**Important:** The overlay path `{overlay-path}` must match the repo's overlay root — in `cq-guides` this is typically `apps/fd/` or the project-specific apps root, not `apps/core/fd/`.
+
+---
+
+## Wiring Step 5b: Reading FormContainer Properties in the Component's Sling Model
+
+**Pattern:** The component's Sling Model injects the `FormStructureParser` and walks up the resource hierarchy to the parent FormContainer, then reads the container's properties.
+
+```java
+import com.adobe.cq.forms.core.components.internal.form.FormConstants;
+import com.adobe.cq.forms.core.components.util.ComponentUtils;
+import org.apache.sling.api.resource.Resource;
+
+// Additional injected fields:
+@Self
+private SlingHttpServletRequest request;
+
+// Read a property from the parent FormContainer
+private String getContainerProperty(String propertyName, String defaultValue) {
+    // Check request-cached container path first
+    String containerPath = (String) request.getAttribute(FormConstants.REQ_ATTR_FORMCONTAINER_PATH);
+
+    Resource containerResource = null;
+    if (containerPath != null) {
+        containerResource = request.getResourceResolver().getResource(containerPath);
+    }
+
+    if (containerResource == null) {
+        // Fallback: walk up the resource tree
+        containerResource = findFormContainer(request.getResource());
+    }
+
+    if (containerResource != null) {
+        return containerResource.getValueMap().get(propertyName, defaultValue);
+    }
+    return defaultValue;
+}
+
+private Resource findFormContainer(Resource resource) {
+    if (resource == null) {
+        return null;
+    }
+    if (ComponentUtils.isAFContainer(resource)) {
+        return resource;
+    }
+    return findFormContainer(resource.getParent());
+}
+```
+
+Then call from any getter:
+```java
+@Override
+public String getSigningService() {
+    return getContainerProperty("signingService", "");
+}
+```
+
+Notes:
+- `FormConstants.REQ_ATTR_FORMCONTAINER_PATH` is set by `FormContainerImpl` during request processing — using it avoids repeated tree-walking.
+- `ComponentUtils.isAFContainer(resource)` checks if a resource is a FormContainer by inspecting its `sling:resourceType` or `fieldType`.
+- Always provide a non-null default in `getValueMap().get(propName, default)`.
+
+---
+
+## Wiring Step 6: Production Template Policy (allowed components in author picker)
+
+**What it controls:** When an author opens a Core Component form in the Sites/Forms editor and opens the component picker, the list of available components is controlled by the template policy.
+
+**Where it lives (production):** `conf/{siteName}/settings/wcm/policies/.content.xml` — inside the AEM repository. In a project repository (e.g., `cq-guides` or `integration-adobesign`), this file lives in the content package that carries site/template configuration.
+
+**File to update** (or create if policy doesn't exist for the form container):
+
+```xml
+<!-- Under the policy node for the form container component -->
+<policy_{uniqueId}
+    jcr:primaryType="nt:unstructured"
+    jcr:title="formcontainer-policy"
+    sling:resourceType="wcm/core/components/policy/policy"
+    components="[group:{ExistingGroup},group:{NewComponentGroup}]">
+    <jcr:content jcr:primaryType="nt:unstructured"/>
+</policy_{uniqueId}>
+```
+
+Add the new component's group name to the `components` array. Do not remove existing groups.
+
+**Alternative (recommended for production):** Use the AEM Template Editor UI to allow the component group in the policy — modifies the same JCR node without needing a content package deploy.
+
+**Verify** by opening a form in authoring mode, clicking the `+` (insert component) button, and confirming the new component appears in the component picker under its group.
+
+---
+
+## Wiring Step 7: Integration Test Content
+
+**File path:** `it/content/src/main/content/jcr_root/content/forms/af/core-components-it/samples/{name}/basic/.content.xml`
+
+This provides a sample form instance for integration tests run against a live AEM instance. It must also be added to the allowed-components policy.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
+          xmlns:cq="http://www.day.com/jcr/cq/1.0"
+          xmlns:jcr="http://www.jcp.org/jcr/1.0"
+          xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
+          xmlns:fd="http://www.adobe.com/aemfd/fd/components/adaptive-form/formmetadata/2.0"
+    jcr:primaryType="nt:unstructured"
+    sling:resourceType="core/fd/components/form/{name}/v1/{name}"
+    fieldType="{field-type}"
+    jcr:title="{ComponentDisplayName}"
+    name="{name}"
+    visible="{Boolean}true"
+    enabled="{Boolean}true"
+    {customProperty}="{sampleValue}"/>
+```
+
+After creating this file, update the template policy to allow the new component's group:
+
+**File to update:** `it/content/src/main/content/jcr_root/content/wcm/policies/.content.xml`
+
+Find the `components` property of the relevant policy and add the component group:
+```xml
+components="[group:{ComponentGroupName},...]"
+```
diff --git a/.claude/skills/migrate-foundation-component/SKILL.md b/.claude/skills/migrate-foundation-component/SKILL.md
index 94d7ac940d..b85985b2f4 100644
--- a/.claude/skills/migrate-foundation-component/SKILL.md
+++ b/.claude/skills/migrate-foundation-component/SKILL.md
@@ -23,7 +23,11 @@ Analyze an existing AEM Foundation (Guide) Form Component and migrate it to a fu
 
 ### Phase 1: Identify the Foundation Component
 
-Ask the user **which foundation component** to migrate.
+Before loading any data, collect the following upfront. Ask in a single message and wait for all answers:
+
+- **Which foundation component** to migrate (name or path)
+- **Target repository and component group** — which repo (`aem-core-forms-components`, or a project overlay) and what `componentGroup` for the author toolbar
+- **FormContainer-level properties** — does the component need any configuration authored on the parent form container rather than on the component instance itself? If yes: what properties and what tab name?
 
 #### Known Components (data embedded in skill)
 
@@ -175,7 +179,7 @@ Based on the analysis, determine the inputs for the `create-core-component` skil
 
 3. **Custom properties** — all properties identified in Phase 3 that are NOT in the base classes
 
-4. **Widget HTML** — translate the foundation widget rendering to HTL:
+4. **Widget HTML** — translate the foundation widget rendering to HTL. Read `references/code-patterns.md` for before/after code-level translation examples. Key mappings:
    - `<c:if>` → `data-sly-test`
    - `<c:choose>/<c:when>` → `data-sly-test` chains
    - `<c:forEach>` → `data-sly-list` or `data-sly-repeat`
@@ -298,8 +302,9 @@ Present this report to the user for review.
 
 - `references/known-components.md` — Complete embedded data for all standard foundation components (properties, dialogs, rendering)
 - `references/foundation-anatomy.md` — Foundation component file structure, patterns, and Java hierarchy
-- `references/property-mapping.md` — Foundation → Core type/property/pattern mapping tables
+- `references/property-mapping.md` — Foundation → Core type/property/pattern mapping tables (includes renamed, dropped with Core equivalents, and per-review properties)
 - `references/migration-checklist.md` — Post-migration verification checklist
+- `references/code-patterns.md` — Code-level before/after translation: JSP→HTL, Foundation Java→Sling Model, jQuery→DOM, dialog XML
 
 ## Critical Rules
 
diff --git a/.claude/skills/migrate-foundation-component/references/code-patterns.md b/.claude/skills/migrate-foundation-component/references/code-patterns.md
new file mode 100644
index 0000000000..3e4150e71f
--- /dev/null
+++ b/.claude/skills/migrate-foundation-component/references/code-patterns.md
@@ -0,0 +1,113 @@
+# Foundation Code Patterns and Core Equivalents
+
+---
+
+## JSP Conditional → HTL
+
+```jsp
+<% if (component.getProperty("showBadge", false)) { %><span class="badge"></span><% } %>
+```
+```html
+<span data-sly-test="${model.showBadge}" class="cmp-adaptiveform-{name}__badge"></span>
+```
+
+---
+
+## JSP Loop Over Items → HTL
+
+```jsp
+<% for (String item : items) { %><li><%= item %></li><% } %>
+```
+```html
+<li data-sly-list.item="${model.items}">${item}</li>
+```
+
+---
+
+## Foundation Java Bean Getter → Sling Model
+
+```java
+// Foundation
+public String getSigningService() {
+    return getProperty("signingService", "");
+}
+```
+```java
+// Core
+@ValueMapValue(name = "signingService", injectionStrategy = InjectionStrategy.OPTIONAL)
+@Nullable
+private String signingService;
+
+@Override
+public String getSigningService() {
+    return signingService != null ? signingService : "";
+}
+```
+
+---
+
+## Foundation jQuery Event → Core JS
+
+```javascript
+// Foundation
+var $widget = $("[guide-item-value='" + field.dataRef + "']");
+$widget.on("change", function(e) { field.value = e.target.value; });
+```
+```javascript
+// Core
+setModel(model) {
+    super.setModel(model);
+    this.widget.addEventListener("change", (e) => {
+        this._model.value = e.target.value;
+    });
+}
+```
+
+---
+
+## Foundation XFA `mandatory` → Core `required`
+
+```
+Foundation JCR:  mandatory="true"
+Core JCR:        required="{Boolean}true"
+Core getter:     isRequired()
+```
+
+---
+
+## Foundation `assistPriority`/`speak` → Core
+
+These are handled automatically by `AbstractBaseImpl`. Do not port them as explicit properties — the Core base class computes appropriate accessibility attributes from `label`, `description`, and `tooltip`.
+
+---
+
+## Foundation `sOM` Expression → Core
+
+The SOM expression is computed by the Core runtime. Do not set it as a JCR property.
+
+---
+
+## Foundation Dialog Field → Core Dialog Field
+
+```xml
+<!-- Foundation (ExtJS / cq:Widget) -->
+<items jcr:primaryType="cq:WidgetCollection">
+    <myField jcr:primaryType="cq:Widget"
+             xtype="textfield"
+             fieldLabel="My Field"
+             name="./myField"/>
+</items>
+```
+```xml
+<!-- Core (Granite UI / Coral) -->
+<myField
+    jcr:primaryType="nt:unstructured"
+    sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
+    fieldLabel="My Field"
+    name="./myField"/>
+```
+
+Key differences:
+- No `xtype` — use `sling:resourceType` instead
+- No `cq:WidgetCollection` wrapper — use `nt:unstructured` with `jcr:primaryType` only
+- Property `name` must start with `./`
diff --git a/.claude/skills/migrate-foundation-component/references/property-mapping.md b/.claude/skills/migrate-foundation-component/references/property-mapping.md
index f26b388b2b..e55178d832 100644
--- a/.claude/skills/migrate-foundation-component/references/property-mapping.md
+++ b/.claude/skills/migrate-foundation-component/references/property-mapping.md
@@ -63,28 +63,58 @@ These properties exist in the foundation base `GuideField` / `GuideNode` and are
 
 | Foundation Property | Foundation JCR | Core JCR | Notes |
 |--------------------|---------------|----------|-------|
-| `jcr:title` (field title) | `jcr:title` | `jcr:title` (via label) | Core wraps in label object |
-| `mandatory` | `mandatory` | `required` | Name change |
-| `placeholderText` | `placeholderText` | `emptyText` / `placeholder` | Check Core convention |
-| `bindRef` | `bindRef` | `dataRef` | Core uses `dataRef` |
-| `cssClassName` | `cssClassName` | *(handled differently)* | Core uses data-layer |
+| `jcr:title` (field title) | `jcr:title` | `jcr:title` (via label object) | Core wraps in label object with `value` and `visible` sub-properties |
+| `mandatory` | `mandatory` | `required` | Aligned with HTML/JSON Schema standard |
+| `placeholderText` | `placeholderText` | `placeholder` | Shortened to match HTML attribute |
+| `bindRef` | `bindRef` | `name` | Core binds via `name`; `bindRef` is XFA-specific |
+| `_value` | `_value` | `default` | Foundation prefixed `_` to avoid JCR conflicts; Core uses `default` |
+| `shortDescription` | `shortDescription` | `tooltip` | Concept rename: short description = tooltip in Core |
+| `longDescription` | `longDescription` | `description` | Concept rename |
+| `shortVisible` | `shortVisible` | `tooltipVisible` | Renamed to match its field |
+| `isTitleRichText` | `isTitleRichText` | `label.richText` sub-property | Moved into the label object |
+| `hideTitle` | `hideTitle` | `label` sub-node with `visible=false` | Label is now an object |
+| `maxChars` | `maxChars` | `maxLength` | Aligned with HTML5 `maxlength` |
+| `validatePictureClause` | `validatePictureClause` | `pattern` | XFA picture clause → standard regex |
+| `validatePictureClauseMessage` | `validatePictureClauseMessage` | constraint message for `pattern` | Goes into constraint messages map |
+| `mandatoryMessage` | `mandatoryMessage` | constraint message for `required` | Same constraint messages map |
+| `cssClassName` | `cssClassName` | *(Style System)* | Core uses Design Dialog Style System; see dropped properties |
 
 ## Properties Commonly Dropped
 
-These foundation properties are typically NOT migrated to Core:
-
-| Foundation Property | JCR Name | Reason |
-|--------------------|----------|--------|
-| `guideNodeClass` | `guideNodeClass` | Foundation-only; Sling Model resolution replaces this |
-| `xdpRef` | `xdpRef` | XFA template reference; only if XFA support needed |
-| `dorTemplateRef` | `dorTemplateRef` | Document of Record template ref; separate concern in Core |
-| `dorType` | `dorType` | DOR configuration; handled differently in Core |
-| `dorExclusion` | `dorExclusion` | DOR exclusion; handled differently in Core |
-| `fieldLayout` | `fieldLayout` | Foundation layout system; Core uses CSS/BEM |
-| `allowedParents` | (metadata) | Foundation parsys constraint; Core uses policy |
-| `wrapData` | `wrapData` | XFA data wrapping; not applicable |
-| `assistPriority` | `assistPriority` | Foundation accessibility priority; Core uses explicit ARIA |
-| `custom` | `custom` | Foundation custom object; Core uses `properties` |
+"Dropped" means the specific JCR property has no place on a Core JCR node. It does NOT mean the feature disappears. For every dropped property, the "Core provides this via" column is mandatory in the migration plan — leaving it blank is not acceptable.
+
+| Foundation Property | JCR Name | Why Dropped | Core provides this via | Action required |
+|--------------------|----------|-------------|------------------------|-----------------|
+| `guideNodeClass` | `guideNodeClass` | Foundation-only; Sling Model resolution replaces this | `sling:resourceType` | None — Core resolves via resource type |
+| `visibleExp` | `visibleExp` | Core does not evaluate this string at runtime | **Rules Editor** — Visibility rule; stored in `fd:rules` | Ensure Rules Editor tab is present in Core dialog |
+| `enabledExp` | `enabledExp` | Same | **Rules Editor** — Enable rule | Same |
+| `calculateExp` | `calculateExp` | Same | **Rules Editor** — Set Value of rule | Same |
+| `initializeExp` | `initializeExp` | Same | **Rules Editor** — Initialize rule | Same |
+| `sOM` | `sOM` | Auto-computed; never authored | **Core runtime** — computed from form schema | Nothing — Core computes automatically |
+| `guideFieldType` | `guideFieldType` | Replaced by a different property | **`fieldType`** in `_cq_template.xml` (kebab-case) | Set correct `fieldType` |
+| `fieldLayout` | `fieldLayout` | Foundation layout system; Core uses CSS/BEM | **HTL template structure** — layout baked into `.html` | Implement correct layout in HTL |
+| `colspan` | `colspan` | Foundation grid system removed | **Container responsive grid** — managed at container level | Configure at container level |
+| `css` (CSS Class field) | `css` | Arbitrary class injection is not a Core pattern | **Style System** — `_cq_design_dialog` with allowed styles | Implement `_cq_design_dialog` with Style System tab |
+| `assistPriority` | `assistPriority` | Foundation accessibility priority; Core uses explicit ARIA | **Core ARIA attributes** — `aria-label`, `aria-describedby` set by shared templates and JS | Nothing — Core handles automatically |
+| `xdpRef` | `xdpRef` | XFA template reference | Nothing (unless XFA support explicitly needed) | Flag for user review |
+| `dorTemplateRef` | `dorTemplateRef` | Document of Record template ref | Separate concern in Core DOR templates | Flag for user review |
+| `dorType` | `dorType` | DOR configuration; handled differently in Core | Core DOR templates | Flag for user review |
+| `dorExclusion` | `dorExclusion` | DOR exclusion flag | Core DOR templates | Flag for user review |
+| `wrapData` | `wrapData` | XFA data wrapping; not applicable | Nothing | No action needed |
+| `allowedParents` | (metadata) | Foundation parsys constraint; Core uses policy | **Template policy** — component groups in `wcm/policies` | Add component group to template policy |
+
+## Properties Requiring Per-Migration Review
+
+These properties exist in some foundation components and need case-by-case evaluation:
+
+| Foundation Property | Core Status | What to do |
+|--------------------|-------------|-----------|
+| `assistPriority` enum values | Supported, but enum values differ: Foundation uses `caption`, `toolTip`, `name`, `custom`; Core uses `LABEL`, `DESCRIPTION`, `NAME`, `CUSTOM` | Remap: `caption`→`LABEL`, `toolTip`→`DESCRIPTION`, `name`→`NAME`, `custom`→`CUSTOM` |
+| `speak` / `custom` (screen reader text) | `custom` JCR property is the same in Core | Port directly; only the `assistPriority` enum needs remapping |
+| `multiLine` + `allowRichText` | `multiLine` supported; `allowRichText` → `richText` | Port both; use the renamed key for rich text |
+| `rows` / `cols` | No Core equivalent | Drop — textarea sizing is controlled by theme CSS |
+| `displayPictureClause` | XFA picture syntax not parsed by Core | Migrate to `displayFormat` using ISO/standard format equivalent |
+| `displayIsSameAsValidate` | No equivalent — `displayFormat` and `editFormat` are always independent in Core | Set both `displayFormat` and `editFormat` explicitly in the dialog |
 
 ## Component-Specific Property Mappings
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 9978f40e29..89549683ca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,7 +6,7 @@ AEM Core Forms Components — Adaptive Forms v2 component library.
 
 ### Architecture
 - **Project overview**: [`docs/architecture/overview.md`](docs/architecture/overview.md)
-  Module structure, Java model hierarchy, form JSON model, IT infrastructure, Cypress patterns, JCR content XML patterns.
+  Module structure, component layer architecture (dialog → JCR → Sling Model → HTL → JS view), Java model hierarchy, form JSON model, IT infrastructure, Cypress patterns, JCR content XML patterns.
 - **Runtime internals**: [`docs/architecture/runtime-internals.md`](docs/architecture/runtime-internals.md)
   Deep dive into the form initialization pipeline, repeatable container/InstanceManager mechanics, FT_FORMS-24358 items-array export, common crash signatures, and debugging checklist.
 
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 5bef7119da..5610c667be 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -38,9 +38,82 @@ aem-core-forms-components/
 
 ---
 
-## 2. Java Model Hierarchy
+## 2. Component Layer Architecture
 
-Three key base classes, each responsible for one concern.
+Every AF2 form component is implemented across five layers, in this order:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Author Dialog   _cq_dialog/.content.xml (Granite UI XML)    │
+│  Author edits properties → saved to JCR node                 │
+└──────────────────────────┬───────────────────────────────────┘
+                           │ JCR properties
+┌──────────────────────────▼───────────────────────────────────┐
+│  JCR Content Node   /content/forms/af/{form}/{component}     │
+│  fieldType, name, required, label, custom properties...       │
+└──────────────────────────┬───────────────────────────────────┘
+                           │ adapted via Sling
+┌──────────────────────────▼───────────────────────────────────┐
+│  Sling Model   {ComponentName}Impl extends Abstract{Base}Impl │
+│  @Model(adaptables=SlingHttpServletRequest.class)            │
+│  Typed getters, computed values, JSON export                  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │ data-sly-use in HTL
+┌──────────────────────────▼───────────────────────────────────┐
+│  HTL Template   {componentname}.html                          │
+│  Renders BEM HTML with data-cmp-* runtime attributes          │
+│  class="cmp-adaptiveform-{componentname}"                     │
+│  data-cmp-is="adaptiveForm{ComponentName}"                    │
+└──────────────────────────┬───────────────────────────────────┘
+                           │ registered via FormView.Utils.setupField,
+                           │ scanned during Utils.initializeAllFields
+┌──────────────────────────▼───────────────────────────────────┐
+│  JS View   {componentname}view.js                             │
+│  class {ComponentName}View extends FormView.FormFieldBase     │
+│  Manages widget↔model sync, events, accessibility state       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Data flow at runtime
+
+The full sequence — DOM registration and scan, model tree construction, `setModel`
+timing, widget↔model sync — is documented in [`runtime-internals.md`](runtime-internals.md);
+that file is the single source of truth for it, do not restate it here.
+
+### JS view base class
+
+| JS Base Class | Use when |
+|---------------|----------|
+| `FormView.FormFieldBase` | Component captures a value (field) |
+| `FormView.FormContainer` | Component is a step, panel, or container |
+
+---
+
+## 3. Java Model Hierarchy
+
+### Class hierarchy
+
+```
+AbstractComponentImpl (WCM Core)
+  └── AbstractFormComponentImpl (name, fieldType, dataRef, visible, value, events, rules)
+        ├── AbstractBaseImpl (label, description, tooltip, type, required, enabled)
+        │     └── AbstractFieldImpl (readOnly, default, placeholder, min/max constraints)
+        │           └── AbstractOptionsFieldImpl (enum, enumNames, enforceEnum)
+        └── AbstractContainerImpl (child enumeration, container-specific behavior)
+```
+
+### Which class to extend
+
+| Class | Use when | Provides |
+|-------|----------|----------|
+| `AbstractBaseImpl` | Step, display, or non-value component (button, text, image) | `id`, `name`, `visible`, `enabled`, `required`, `description`, `label`, `data` |
+| `AbstractFieldImpl` | Captures a single user-submitted value (text, number, date) | Everything in Base + `readOnly`, `default`, `placeholder`, `constraints`, validation |
+| `AbstractOptionsFieldImpl` | Options-based field (checkboxes, radios, selects) | Everything in Field + `enum`, `enumNames`, `enforceEnum` |
+| `AbstractContainerImpl` | Holds child components (container/panel) | Everything in Base + child enumeration, container-specific behavior |
+
+**Composite / split widget** (e.g. day/month/year — multiple visible inputs feeding one value): still extend the field base that matches the data type (`AbstractFieldImpl` for a date), rendering one hidden combined `<input>` as the value-bearing widget plus the visible sub-inputs.
+
+Three of these classes carry additional runtime behavior beyond property storage:
 
 ### `AbstractFormComponentImpl`
 
@@ -75,7 +148,7 @@ Reads `System.getProperty(toggleId)`, returns `true` only when the value is exac
 
 ---
 
-## 3. Form JSON Model
+## 4. Form JSON Model
 
 The server renders a page at `<path>.model.json`. This is consumed directly by af2-web-runtime to hydrate the form.
 
@@ -109,7 +182,7 @@ The server renders a page at `<path>.model.json`. This is consumed directly by a
 
 ---
 
-## 4. IT Test Infrastructure
+## 5. IT Test Infrastructure
 
 ### Content page locations
 
@@ -146,7 +219,7 @@ curl -s -u admin:admin \
 
 ---
 
-## 5. Cypress Test Patterns
+## 6. Cypress Test Patterns
 
 ### Key commands (defined in `libs/support/commands.js`)
 
@@ -192,7 +265,7 @@ it('should behave differently when FT_FORMS-XXXXX is enabled', () => {
 
 ---
 
-## 6. JCR Content XML Patterns
+## 7. JCR Content XML Patterns
 
 ### Fragment definition page
 
@@ -240,7 +313,7 @@ A `<fragment>` node embedded in a parent form references the fragment by path:
 
 ---
 
-## 7. Running Tests
+## 8. Running Tests
 
 ```bash
 cd ui.tests/test-module