@pega/custom-dx-components 26.1.11 → 26.1.12-alpha.0.2

package/src/ai/project/.claude/skills/date/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: date
+description: 'Scaffold a Pega DX Field component with subtype **Date** — date or date-time input bound to a date case property. Use when: user asks for a date picker, calendar input, due date, birth date, date range endpoint, or a formatted date display.'
+argument-hint: 'Describe the date field (e.g., "a due-date picker that blocks past dates")'
+---
+
+# Create Date Field
+
+Field subtype `Date`. Binds to a date or date-time case property.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `Date`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit, date only | `DateInput` from `@pega/cosmos-react-core` |
+| Edit, time only | `TimeInput` |
+| `DISPLAY_ONLY` | `DateTimeDisplay` |
+
+## Value Handling
+
+- Pega stores dates as ISO-8601 strings. Keep the ISO string as the source of truth and never store a `Date` object in state.
+- In Cosmos `DateInput`, `onChange` and `onBlur` receive an object `{ valueAsISOString, state }`, not a DOM event (verify against the installed `.d.ts`). A date-only value is the date part of that string:
+  The date part is the text before `T` in `valueAsISOString`; an empty value is `''`. `state` is `'invalid'` or `'incomplete'` while the user is mid-entry. In that case keep the draft and call `getValidationApi().validate(...)`; commit with `changeNblur` only for a complete valid date. See Dates in [field-behavior.md](../create-dx-component/references/field-behavior.md).
+- Use `dayjs` (already a dependency) for any comparison or arithmetic. Do not reach for `moment` or hand-rolled parsing.
+- Format for display through `DateTimeDisplay` rather than formatting the string yourself, so the user's locale is respected.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `minDate` | Earliest date | `TEXT` |  |  |
+| `maxDate` | Latest date | `TEXT` |  |  |
+| `showTime` | Include time | `BOOLEAN` | `false` |  |
+
+## Gotchas
+
+- Time zones are the main source of bugs. A date-only property must not be shifted by local offset: take the year with `value.slice(0, 4)` and, if you must parse, treat it as UTC (`dayjs.utc(value)`). `dayjs(value)` parses a bare date as local midnight and can cross a day boundary. A date-time value is a UTC instant; convert it with the operator's zone from `PCore.getEnvironmentInfo().getTimeZone()`.
+- Set a sensible year range (default 100 years back, 20 forward), widened to include the stored value's year, so a legacy date is still displayed.
+- An empty date must dispatch `''` or `null`, not the string `'Invalid Date'`.
+- Relative bounds such as "no past dates" belong in the blur handler, not in `config.json`, since they are evaluated at runtime.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/decimal/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: decimal
+description: 'Scaffold a Pega DX Field component with subtype **Decimal** — fractional number input bound to a decimal case property. Use when: user asks for a decimal input, measurement, weight, rate, score, ratio, or a precision-formatted number display.'
+argument-hint: 'Describe the decimal field (e.g., "a weight input in kg with three decimals")'
+---
+
+# Create Decimal Field
+
+Field subtype `Decimal`. Binds to a fractional-number case property.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `Decimal`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit | `NumberInput` from `@pega/cosmos-react-core` |
+| `DISPLAY_ONLY` | Number formatted to the configured precision |
+
+## Value Handling
+
+- Keep the raw typed string in the input while the user is editing. Converting on every keystroke destroys a trailing decimal point and blocks typing `1.` on the way to `1.5`.
+- Convert and dispatch on blur:
+  Take the entered text from the event; the value to commit is `''` for empty text and `Number(text)` otherwise, sent with `changeNblur`.
+- Dispatch `''` for an empty input (what the platform's numeric fields send), never `0` and never `NaN`. The stored value can be `null`; read it as `valueProp ?? ''`.
+- Read the entered text from the blur event and skip the commit when it equals the stored value; call `validate(entered)` only. See [field-behavior.md](../create-dx-component/references/field-behavior.md).
+- Keep intermediate drafts such as `-`, `-0` and `-0.` valid while typing.
+- Apply the configured precision on blur, not while typing.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `precision` | Decimal places | `NUMBER` | `2` |  |
+| `min` | Minimum | `NUMBER` |  |  |
+| `max` | Maximum | `NUMBER` |  |  |
+| `unit` | Unit suffix | `TEXT` |  |  |
+
+## Gotchas
+
+- Decimal separators are locale-dependent. Cosmos `NumberInput` hands your blur callback a canonical dot-separated string, so check what it passes before adding your own comma handling; if you parse user text yourself, normalize a comma decimal before `Number()`, which would otherwise yield `NaN`.
+- Compare the stored value and the parsed entry as strings (`value.toString() !== parsable`), not with `===` on floats and not with an epsilon. Then `1.600` redisplays as `1.6` after commit.
+- `decimalPrecision` arrives as a string. `parseInt` it; an empty string means unlimited, but any other `NaN` should fall back to 2.
+- `toFixed` returns a string. Dispatch the numeric value, and use the fixed string only for display.
+- If the property is truly monetary, use `currency` instead — it carries the currency code and minor-unit rules.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/details/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: details
+description: 'Scaffold a Pega DX Template component with subtype **DETAILS** — a read-only layout that presents child field values as label-value pairs. Use when: user asks for a details view, summary panel, review section, read-only case snapshot, or a label-value arrangement.'
+argument-hint: 'Describe the details layout (e.g., "a two-column summary panel with inline labels")'
+---
+
+# Create DETAILS Template
+
+Template subtype `DETAILS`. Presents child field values **read-only**, as label-value pairs.
+
+Read [../template/SKILL.md](../template/SKILL.md) for the shared Template rules first. This skill adds only what is specific to `DETAILS`.
+
+## Cosmos Mapping
+
+| Concern | Component |
+| --- | --- |
+| Label-value pairs | `FieldValueList` with `variant='inline'` or `'stacked'` |
+| Column arrangement | `Grid` |
+| Named section | `FieldGroup`, or `Card` + `CardHeader` + `CardContent` |
+
+## Label Variants
+
+| Variant | Layout | Use when |
+| --- | --- | --- |
+| `inline` | Label left, value right | Dense summaries, wide containers |
+| `stacked` | Label above value | Narrow columns, long values |
+
+Expose this choice as a config property rather than hard-coding it.
+
+## Layout Rules
+
+- **Force read-only on the children.** The shipped DETAILS scaffold calls `child.props.getPConnect().setInheritedProp('readOnly', true)` and `setInheritedProp('displayMode', 'DISPLAY_ONLY')` on every region child; without it the template shows editable inputs. Keep those calls (they must be idempotent).
+- `children` are regions. Read each region's fields with `getChildren()`, render them with a memoized `getComponent()`, and read the label and variant from `resolveConfigProps(getConfigProps())`. See [template-patterns.md](../create-dx-component/references/template-patterns.md).
+- Use `inline` labels by default and **stacked** when the value is long (a text area or rich text of about 60 characters or more, an image URL, a map). A Checkbox's label is its `caption`.
+- Check whether the installed `@pega/cosmos-react-work` exports `Details` / `DetailsList`; they handle column fitting, heading depth and label alignment, and are what Pega's own details view uses.
+- Prefer one `FieldValueList` over many, so labels align on a shared column. Separate lists break the alignment grid.
+- Empty values should render a neutral placeholder such as an em dash, not a blank cell that looks like a rendering bug.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `variant` | Label placement | `SELECT` | `"inline"` | options: `inline`, `stacked` |
+| `NumCols` | Number of columns | `SELECT` | `"1"` | options: `1`, `2` |
+| `showLabel` | Show section label | `BOOLEAN` | `true` |  |
+| (help text) |  | `INSTRUCTIONS` |  | no name; shows help text |
+| `A` | Region A | `CONTENTPICKER` |  | allows creating groups |
+
+The shipped DETAILS scaffold names its regions `A` and `B` (`A` for the main column, `B` for the second); `Fields` is only used by a single-region form. Keep the scaffold's region names.
+
+## Gotchas
+
+- Do not render inputs. If the author needs editing, the correct subtype is `form`.
+- `FieldValueList` needs a stable `id` per entry. Do not use the array index.
+- A details template must not call `updateFieldValue` or `triggerFieldChange`.
+- Long values need wrapping, not truncation, unless the author explicitly asked for truncation.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/email/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: email
+description: 'Scaffold a Pega DX Field component with subtype **Email** — email address input bound to a string case property. Use when: user asks for an email input, contact address field, mailto link display, or email validation.'
+argument-hint: 'Describe the email field (e.g., "a work email input restricted to the company domain")'
+---
+
+# Create Email Field
+
+Field subtype `Email`. Binds to a string case property holding an email address.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `Email`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit | `Input` with `type='email'` from `@pega/cosmos-react-core` |
+| `DISPLAY_ONLY` | `EmailDisplay` — renders a `mailto:` link |
+
+## Value Handling
+
+- `value` is a plain string. Default to `''`.
+- Lowercasing and trimming is **this skill's design choice**: the platform's own Email field commits the raw string. Ask the user before normalizing, since it changes stored data. If they agree, trim and lowercase on blur, then dispatch the normalized value:
+  Compute the normalized value, send it with `handleEvent(actions, 'blur', ...)`, then call `getValidationApi().validate(normalized)`.
+- Do not validate on every keystroke. Users see an error before they finish typing the domain.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `allowedDomains` | Allowed domains (comma separated) | `TEXT` |  |  |
+| `showMailtoLink` | Link the address when read-only | `BOOLEAN` | `true` |  |
+
+## Gotchas
+
+- Keep client-side validation permissive. Pega runs the authoritative rule, and an over-strict regex rejects valid addresses such as plus-addressing and long TLDs.
+- `EmailDisplay` builds the `mailto:` href itself. Do not construct the link manually, and never interpolate the raw value into an `href` string.
+- Domain restriction is a business rule. Read it from `config.json`, do not hard-code it.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/field/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: field
+description: 'Scaffold and implement a Pega DX **Field** component (Text, Boolean, Integer, Date, Email, Phone, Currency, Decimal, Percentage, URL, Picklist, Radiobuttons, etc.). Use when: user asks for an input/display component bound to a single case property; needs displayMode handling; asks for a Field subtype.'
+argument-hint: 'Describe the field (e.g., "a masked SSN input" or "a color-picker field bound to .FavoriteColor")'
+---
+
+# Create Field Component Skill
+
+## Prefer a Subtype Skill
+
+If the subtype is clear, use the narrower skill instead — it carries the value-handling and formatting rules this skill does not repeat.
+
+| Subtype | Skill |
+| --- | --- |
+| Text | `text` |
+| Boolean | `boolean` |
+| Integer | `integer` |
+| Decimal | `decimal` |
+| Currency | `currency` |
+| Percentage | `percentage` |
+| Date | `date` |
+| Email | `email` |
+| Phone | `phone` |
+| URL | `url` |
+| Picklist | `picklist` |
+| Radiobuttons | `radiobuttons` |
+
+Use this skill when the subtype is unclear, or for a subtype with no dedicated skill (`Text-Input`, `Text-Paragraph`, `Icon-Button-URL`, `DateTime`, `TimeOfDay`, `Picklist-Autocomplete`). The specifics of those six are in [field-subtypes-extra.md](../create-dx-component/references/field-subtypes-extra.md). For a custom control (a rating, a slider, a color or signature input), choose the subtype by the type of the **stored value** using [choosing-type-and-subtype.md](../create-dx-component/references/choosing-type-and-subtype.md), and say so if the request needs a list or several properties, which no Field subtype supports.
+
+## When to Use
+
+- User wants a component **bound to a single case property** (`value` in / `updateFieldValue` out)
+- User mentions a Field subtype: Text, Boolean, Integer, Date, Email, Phone, Currency, Decimal, Percentage, URL, Picklist, Radiobuttons
+- User needs read-only, edit, and `DISPLAY_ONLY` rendering for the same value
+
+Do NOT use this skill for layout containers (see `template`), data-driven blocks (see `widget`), or standalone read-only blocks that never bind to a property (see `widget`).
+
+## Procedure
+
+The repo-wide rules (gallery reuse, contract approval and its layout, authoring properties, consent, Cosmos first, no dead code) are in `AGENTS.md` and are not repeated here.
+
+### Step 0: Check the UI Gallery
+
+Follow [ui-gallery-reuse.md](../create-dx-component/references/ui-gallery-reuse.md).
+
+### Step 1: Agree the contract
+
+Besides the name, label, description, library and version, the draft states:
+
+- **Subtype**: any Field subtype the CLI accepts, chosen by the stored value type ([cli-workflow.md](../create-dx-component/references/cli-workflow.md))
+- **Cosmos input**: which `@pega/cosmos-react-core` control renders it (`Input`, `Checkbox`, `NumberInput`, `DateInput`, `Select`, `RadioButtonGroup`, `CurrencyInput`, `PhoneInput`, `EmailDisplay` for read, etc.)
+- **Field behavior**: bound property type, editable and read-only behavior, validation, display modes
+- **Authoring properties**: a compact, field-specific list with formats and defaults; propose `label`, `hideLabel`, `readOnly`, `required`, `disabled`, `helperText` only when they apply
+- **States to cover**: the applicable rows from [state-matrix.md](../create-dx-component/references/state-matrix.md)
+
+### Step 2: Scaffold
+
+`npm run create -- Field <cliSubtype> <Name> "<Label>" <version> <Library> "<description>" <Organization>`
+
+Pass every argument: a bare `npm run create` prompts interactively and hangs an agent. `<cliSubtype>` is the exact value from [component-manifest.json](../generate-component-set/component-manifest.json) (for example `Text-Email`, `Decimal-Currency`, `Picklist-RadioButtons`). If no library exists yet, run `npm run createLib -- <Library> 1.0.0 Y Current` first.
+
+### Step 3: Implement
+
+Implement every scaffolded file from [field-essentials.md](../create-dx-component/references/field-essentials.md); open a deeper reference only when its closing table says so. `event-utils.ts` is generated for some subtypes (for example `Integer`, `Picklist`); if the scaffold did not create it and the component needs it, copy [event-utils.ts](../create-dx-component/assets/event-utils.ts) into the component folder and `import handleEvent from './event-utils'`.
+
+### Step 4: Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` (`--no-build` while fixing), and paste the final table into your report. For a new component, run the `review-component` skill as described in [create-dx-component](../create-dx-component/SKILL.md). `npm run startStorybook` is long-running, so leave it to the user.

package/src/ai/project/.claude/skills/form/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: form
+description: 'Scaffold a Pega DX Template component with subtype **FORM** — an editable layout that arranges child input fields for data entry. Use when: user asks for a form layout, multi-column entry form, field group arrangement, wizard step layout, or an editable section container.'
+argument-hint: 'Describe the form layout (e.g., "a two-column form with a full-width notes row")'
+---
+
+# Create FORM Template
+
+Template subtype `FORM`. Arranges child **input** fields for data entry.
+
+Read [../template/SKILL.md](../template/SKILL.md) for the shared Template rules first. This skill adds only what is specific to `FORM`.
+
+## Cosmos Mapping
+
+| Concern | Component |
+| --- | --- |
+| Column arrangement | `Grid` with `container={{ cols: 'repeat(N, minmax(0, 1fr))', gap: 2 }}` |
+| Named section | `FieldGroup` |
+| Stacked rows | `Flex` with `container={{ direction: 'column', gap: 2 }}` |
+
+## FORM vs DETAILS
+
+`FORM` renders fields in **edit** mode. If every child is read-only, the author wants `details` instead — using FORM there produces inputs that cannot be edited.
+
+## Layout Rules
+
+- Render `children` directly into the `Grid`. Constellation has already resolved each child to a field component.
+- Column count comes from the `NumCols` config property, never a literal.
+- Large controls (`TextArea`, `RichText`, `RadioButtons`, `Checkbox` groups, `Attachment`, `Address`, `Group`, tables and references) span the whole row: `item={{ colStart: '1', colEnd: cols + 1 }}`. A field's `isFormWidth` config flag asks for the same. This needs per-field access, so go one level below the regions (see [template-patterns.md](../create-dx-component/references/template-patterns.md)).
+- Show `instructions` (from the `INSTRUCTIONS` property) only when a heading is shown. `templateOverrideMode` and `inheritParentLayout` let a nested form keep its parent's column count; add them if the template can be nested.
+- Do not intercept or reorder `children`. The author controls order through the content picker.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `NumCols` | Number of columns | `SELECT` | `"1"` | options: `1`, `2`, `3` |
+| `showLabel` | Show section label | `BOOLEAN` | `true` |  |
+| (help text) |  | `INSTRUCTIONS` |  | no name; shows help text |
+| `Fields` | Fields | `CONTENTPICKER` |  | allows creating groups |
+
+## Gotchas
+
+- `minmax(0, 1fr)` is required, not `1fr`. Without it a long value inside a child overflows the column instead of wrapping.
+- Merge `getPConnect().getInheritedProps()` before deciding whether to render the label — the parent may already be showing it.
+- Multi-column forms must collapse to a single column when narrow. Prefer container-width wrapping (a `ResizeObserver` on the template container) to a viewport query, because a template often sits in a side panel or modal; otherwise use the Cosmos `Grid` responsive props. A theme that places helper text above fields also forces one column.
+- Do not add validation or submit handling. The surrounding Constellation view owns both.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/generate-component-set/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: generate-component-set
+description: 'Batch-generate MANY Pega DX components in one session: every Field subtype (or a named subset), every Template subtype, a set of Widgets or Presentation components, or a full library across all four types. Use when the user asks for "all", "every", "a set of" or "a whole library of" components. For ONE component use the type skill (`field`, `template`, `widget`, `presentation`) or `create-dx-component` instead.'
+argument-hint: 'Which types or subtypes to generate (e.g. "all fields", "Date and Currency", "full library with two widgets")'
+---
+
+# Generate a Set of Components
+
+Generate several components in a single session. The shared context is loaded **once** and then reused for every component, so a batch costs far less than repeating the single-component flow.
+
+The catalogue is [component-manifest.json](./component-manifest.json): every type, every subtype, each subtype's `cliSubtype`, its skill path, and whether the type's catalogue is `fixed` or `user-supplied`. Work from that file, never from a list remembered from elsewhere.
+
+## Step 0 — Resolve inputs
+
+Read the user's message and extract:
+
+- **Types in scope**: Field, Template, Widget, Presentation (default for "full library": all four).
+- **Field and Template subtypes**: every entry of `types.Field.subtypes` / `types.Template.subtypes`, or only the ones the user named.
+- **Widgets and Presentation components**: their `catalogue` is `user-supplied`, so the user must name each one. A Widget needs a scope (`CASE` or `PAGE`) and a data source; a Presentation component needs a subtype (`CASEVIEW` or `WSSCASEVIEW`).
+- **Naming**: the PascalCase suffix per component. Default is the subtype name (`<Org>_<Library>_Text`, …). Apply any prefix or suffix convention the user gives, consistently.
+
+Stop and ask if Widget or Presentation is in scope and the user named none. Never invent widgets.
+
+Fetch the [Constellation UI Gallery](https://github.com/pegasystems/constellation-ui-gallery/tree/master/src/components) catalogue once, per [ui-gallery-reuse.md](../create-dx-component/references/ui-gallery-reuse.md), and mark each planned component as **reuse `Pega_Extensions_<Name>`** or **build from scratch**. Step 3 reuses this catalogue rather than fetching it again.
+
+The output path is fixed at `src/components/<Org>_<Library>_<Name>/`; do not ask for it. Echo the resolved plan as a numbered list before starting, and wait for confirmation if it has more than 10 components.
+
+## Step 1 — Load the shared context once
+
+Read these once and keep them active for the whole session. Do not re-read them per component.
+
+1. The type skill for each type in scope: [field](../field/SKILL.md), [template](../template/SKILL.md), [widget](../widget/SKILL.md), [presentation](../presentation/SKILL.md).
+2. [component-patterns.md](../create-dx-component/references/component-patterns.md)
+3. [config-schema.md](../create-dx-component/references/config-schema.md)
+4. [cosmos-components.md](../create-dx-component/references/cosmos-components.md)
+5. [pcore-pconnect-apis.md](../create-dx-component/references/pcore-pconnect-apis.md) (an index into the `pconnect-*` skills; open those on demand)
+6. [storybook-pattern.md](../create-dx-component/references/storybook-pattern.md)
+7. [test-pattern.md](../create-dx-component/references/test-pattern.md)
+8. One existing component in `src/components/`, end to end, to match this project's conventions.
+
+## Step 2 — Overwrite check, once
+
+Check `src/components/` for every target folder across every type. Report all collisions in one message and ask **Overwrite all / Skip existing / Cancel**, then wait for the answer. Do it once here, not per type.
+
+## Step 3 — Generate by type, in this order
+
+Fields first, then Templates (which arrange them), then Widgets, then Presentation. For each component, in manifest order:
+
+1. **Read the subtype skill (mandatory)** at the manifest's `skill` path. The type skill gives the skeleton; the subtype skill gives the exact Cosmos control, value coercion, formatting and edge cases. Generating from the parent alone produces generic components that miss subtype behavior.
+2. **Scaffold non-interactively**, passing every argument. A bare `npm run create` prompts and hangs an agent. If no library exists yet, run `npm run createLib -- <Library> 1.0.0 Y Current` first.
+
+   ```bash
+   npm run create -- <type> <cliSubtype> <Name> "<Label>" <version> <Library> "<description>" <Organization>
+   ```
+
+   `<cliSubtype>` is the manifest entry's `cliSubtype` (for example `Decimal-Currency`, not `Currency`). The organization comes from `package.json`, the library from `createLib` or `tasks.config.json`. See [cli-workflow.md](../create-dx-component/references/cli-workflow.md). If the CLI cannot be driven, create the folder by hand and copy the shared files from [assets](../create-dx-component/assets/) into `src/components/shared/`.
+
+   If Step 0 marked the component for reuse, adapt the gallery component per [ui-gallery-reuse.md](../create-dx-component/references/ui-gallery-reuse.md) instead of implementing from scratch in the next step.
+
+3. **Implement** `index.tsx`, `config.json`, `styles.ts`, `mock.ts`, `demo.stories.tsx` and `demo.test.tsx`, following the type rules below and the Cosmos-first and dead-code rules in `AGENTS.md`.
+4. **Report one line**: "`<Org>_<Library>_<Name>` ✓ — <what it uses>".
+
+### Rules by type
+
+| Type         | Read first                                                                                                     | Rules                                                                                                                                                                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Field        | the subtype skill (`text`, `date`, `currency`, …)                                                              | `handleEvent` on change and blur, `getValidationApi().validate` on blur, a `DISPLAY_ONLY` mode, string-boolean normalization for `readOnly` / `required` / `disabled`, `status` from `validatemessage`. The Cosmos control owns label, required, disabled and read-only rendering. |
+| Template     | the subtype skill (`form`, `details`, `page`, …)                                                               | Layout from Cosmos `Flex`, `Grid`, `Card`; never a hand-rolled styled `div`. Render children through PConnect and guard an empty or undefined `children`.                                                                                                         |
+| Widget       | `case` or `page-widget` by scope (CLI subtype `CASE` or `PAGE`)                                                | Render loading (`Progress`), error (`Banner`), empty (`EmptyState`) and populated states. Wrap in `Card`. Fetch in `useEffect`, never in render, and do not set state after unmount. `mock.ts` supplies a realistic fixture so the story renders without a server.   |
+| Presentation | the prop types: `CaseView.types.d.ts` in `@pega/cosmos-react-work` (`@pega/cosmos-react-wss` for `WSSCASEVIEW`) | Pure render from props: no `getPConnect`, no `PCore`, no fetching, no event wiring. Handle optional props (`subheading`, `banners`, `utilities`, …) explicitly. `config.json` has no properties by default.                                                        |
+
+All types: export with `withConfiguration()` and keep the `create-nonce` import the scaffold provides (`../shared/create-nonce` for Field, Template and Widget).
+
+## Step 4 — Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` for each generated component and keep every table for the final report, then `npm run validateAll`, `npm run test` and `npm run lint`. Fix every build, lint, spelling and coverage failure before reporting. Use [validate-component](../validate-component/SKILL.md) for failure triage.
+
+## Step 5 — Final report
+
+A table of every component: name, type, subtype or scope, and the main Cosmos component used. Then list anything the user asked for that was skipped, and why.

package/src/ai/project/.claude/skills/generate-component-set/component-manifest.json

@@ -0,0 +1,161 @@
+{
+  "$comment": "Machine-readable catalogue of every component type and subtype this library can generate. Single source of truth for the generate-component-set and identify-components skills \u2014 do not duplicate these lists in markdown.",
+  "namePrefix": "<Org>_<Library>_",
+  "namePrefixComment": "Not a literal. <Org> is the organization in package.json and <Library> is the library created with createLib (component.library in tasks.config.json).",
+  "outputPath": "src/components/{namePrefix}{Name}",
+  "skillRoot": ".claude/skills",
+  "referenceRoot": ".claude/skills/create-dx-component/references",
+  "assetRoot": ".claude/skills/create-dx-component/assets",
+  "sharedAssets": ["PConnProps.d.ts", "create-nonce.ts", "styles.ts", "event-utils.ts"],
+  "componentFiles": ["index.tsx", "config.json", "styles.ts", "mock.ts", "demo.stories.tsx", "demo.test.tsx"],
+  "types": {
+    "Field": {
+      "skill": "field/SKILL.md",
+      "catalogue": "fixed",
+      "subtypes": [
+        {
+          "subtype": "Text",
+          "cliSubtype": "Text",
+          "skill": "text/SKILL.md",
+          "cosmos": "Input / TextArea"
+        },
+        {
+          "subtype": "Boolean",
+          "cliSubtype": "Boolean",
+          "skill": "boolean/SKILL.md",
+          "cosmos": "Checkbox / BooleanDisplay"
+        },
+        {
+          "subtype": "Integer",
+          "cliSubtype": "Integer",
+          "skill": "integer/SKILL.md",
+          "cosmos": "NumberInput"
+        },
+        {
+          "subtype": "Decimal",
+          "cliSubtype": "Decimal",
+          "skill": "decimal/SKILL.md",
+          "cosmos": "NumberInput"
+        },
+        {
+          "subtype": "Currency",
+          "cliSubtype": "Decimal-Currency",
+          "skill": "currency/SKILL.md",
+          "cosmos": "CurrencyInput / CurrencyDisplay"
+        },
+        {
+          "subtype": "Percentage",
+          "cliSubtype": "Decimal-Percentage",
+          "skill": "percentage/SKILL.md",
+          "cosmos": "NumberInput with % suffix"
+        },
+        {
+          "subtype": "Date",
+          "cliSubtype": "Date",
+          "skill": "date/SKILL.md",
+          "cosmos": "DateInput / DateTimeDisplay"
+        },
+        {
+          "subtype": "Email",
+          "cliSubtype": "Text-Email",
+          "skill": "email/SKILL.md",
+          "cosmos": "Input type=email / EmailDisplay"
+        },
+        {
+          "subtype": "Phone",
+          "cliSubtype": "Text-Phone",
+          "skill": "phone/SKILL.md",
+          "cosmos": "PhoneInput / PhoneDisplay"
+        },
+        {
+          "subtype": "URL",
+          "cliSubtype": "Text-URL",
+          "skill": "url/SKILL.md",
+          "cosmos": "Input type=url / URLDisplay"
+        },
+        {
+          "subtype": "Picklist",
+          "cliSubtype": "Picklist",
+          "skill": "picklist/SKILL.md",
+          "cosmos": "Select"
+        },
+        {
+          "subtype": "RadioButtons",
+          "cliSubtype": "Picklist-RadioButtons",
+          "skill": "radiobuttons/SKILL.md",
+          "cosmos": "RadioButtonGroup"
+        }
+      ]
+    },
+    "Template": {
+      "skill": "template/SKILL.md",
+      "catalogue": "fixed",
+      "subtypes": [
+        {
+          "subtype": "FORM",
+          "cliSubtype": "FORM",
+          "skill": "form/SKILL.md",
+          "cosmos": "Grid / FieldGroup / Flex",
+          "renders": "Editable layout that arranges input children"
+        },
+        {
+          "subtype": "DETAILS",
+          "cliSubtype": "DETAILS",
+          "skill": "details/SKILL.md",
+          "cosmos": "FieldValueList / Grid / Card",
+          "renders": "Read-only label/value summary of children"
+        },
+        {
+          "subtype": "PAGE",
+          "cliSubtype": "PAGE",
+          "skill": "page/SKILL.md",
+          "cosmos": "Grid / Flex / Card",
+          "renders": "Whole-page region layout, portal shell"
+        }
+      ]
+    },
+    "Widget": {
+      "skill": "widget/SKILL.md",
+      "catalogue": "user-supplied",
+      "$comment": "Widgets have no default list. The user must name each one, its scope, and its data source.",
+      "subtypes": [
+        {
+          "subtype": "CASE",
+          "cliSubtype": "CASE",
+          "skill": "case/SKILL.md",
+          "cosmos": "Card / CardHeader / CardContent",
+          "renders": "Case-scoped chart, KPI, or related-records block"
+        },
+        {
+          "subtype": "PAGE_WIDGET",
+          "cliSubtype": "PAGE",
+          "skill": "page-widget/SKILL.md",
+          "cosmos": "Card / CardHeader / CardContent",
+          "renders": "Dashboard tile or portal block with no case context"
+        }
+      ]
+    },
+    "Presentation": {
+      "skill": "presentation/SKILL.md",
+      "catalogue": "user-supplied",
+      "$comment": "Presentation components replace how a whole case view is rendered. The user chooses the subtype (CASEVIEW or WSSCASEVIEW) and the name; there is no default set. They take all data as props and cannot use PCore or getPConnect. For badges, formatters and other read-only displays use a Field or a Widget instead.",
+      "subtypes": [
+        {
+          "subtype": "CASEVIEW",
+          "cliSubtype": "CASEVIEW",
+          "skill": "presentation/SKILL.md",
+          "cosmos": "CaseViewProps from @pega/cosmos-react-work",
+          "renders": "Replacement case view"
+        },
+        {
+          "subtype": "WSSCASEVIEW",
+          "cliSubtype": "WSSCASEVIEW",
+          "skill": "presentation/SKILL.md",
+          "cosmos": "CaseViewProps from @pega/cosmos-react-wss",
+          "renders": "Replacement case view for Web Self Service"
+        }
+      ]
+    }
+  },
+  "cliSubtypeComment": "cliSubtype is the exact <subtype> argument for 'npm run create -- <type> <subtype> ...'. Use it instead of the display name."
+}

package/src/ai/project/.claude/skills/identify-components/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: identify-components
+description: 'Analyze an attached screenshot, mockup or UI description and decide which custom Pega DX components to build (Field, Template, Widget, Presentation). Use when the user shares a design and asks what to build, or asks to break a UI into components. Outputs a compact list that feeds the `generate-component-set` skill.'
+argument-hint: 'Attach a screenshot or describe the UI'
+---
+
+# Identify Components from a Design
+
+Analyze the attached screenshot, mockup or described UI (for written requirements, links or a design system as the source, use [plan-dx-component](../plan-dx-component/SKILL.md)) and identify which **custom** Pega DX components are needed. Emit only type and subtype names that appear in [component-manifest.json](../generate-component-set/component-manifest.json).
+
+**Output only these lines**, nothing else:
+
+```
+fields="Text,Date,Picklist"
+templates="Form,Details"
+widgets="Name:CASE:dataPageOrSource"
+presentation="Name:CASEVIEW"
+```
+
+Omit any line that would be empty. The output can be handed straight to the [generate-component-set](../generate-component-set/SKILL.md) skill.
+
+## Visual recognition guide
+
+### Field: a control bound to a single case property
+
+| What you see                                         | Subtype        |
+| ---------------------------------------------------- | -------------- |
+| Single-line text box, textarea, masked string        | `text`         |
+| Checkbox, toggle, yes/no, consent switch             | `boolean`      |
+| Whole-number spinner, count, quantity, year          | `integer`      |
+| Fractional number, measurement, rate, score          | `decimal`      |
+| Money input, price, amount, budget (currency prefix) | `currency`     |
+| Percent input, discount, completion rate (% suffix)  | `percentage`   |
+| Calendar icon input, due date, birth date            | `date`         |
+| Email input, envelope icon, `mailto` display         | `email`        |
+| Telephone input with country code prefix             | `phone`        |
+| Web address input, external link icon                | `url`          |
+| Dropdown / select / lookup with chevron              | `picklist`     |
+| Radio group, small mutually exclusive choice         | `radiobuttons` |
+
+A status pill, count badge, tag, icon or formatted value bound to a property is also a Field: it handles `DISPLAY_ONLY`. Pick the subtype that matches the bound value.
+
+### Template: a layout that arranges other components
+
+| What you see                                   | Subtype   |
+| ---------------------------------------------- | --------- |
+| Card or panel wrapping editable input fields   | `form`    |
+| Read-only label/value pair summary block       | `details` |
+| Full-page shell: header, regions, content area | `page`    |
+
+### Widget: a self-fetching data block
+
+| What you see                                           | Scope  |
+| ------------------------------------------------------ | ------ |
+| Chart, KPI tile, or related-records list inside a case | `CASE` |
+| Dashboard tile or portal block with no case context    | `PAGE` |
+
+For each widget emit `Name:SCOPE:source`. If the data source is not inferable from the image, use `unknown`. Do not guess a data page name.
+
+### Presentation: a replacement case view page
+
+| What you see                                                                        | Subtype       |
+| ----------------------------------------------------------------------------------- | ------------- |
+| A full case page: case header, summary panel, stage tracker, tabs, tasks, utilities | `CASEVIEW`    |
+| The same case page in a Web Self Service portal                                     | `WSSCASEVIEW` |
+
+For each emit `Name:SUBTYPE`. A badge, pill, tag, icon or formatted value is **not** a Presentation component: classify it as the Field subtype that matches the bound value, or as a Widget if it loads its own data.
+
+## Rules
+
+1. **Only list what is visible.** Do not include components that might exist off-screen.
+2. **Do not list anything Constellation already ships.** This project builds custom components. A plain stock input, stock case view or stock nav bar is left out.
+3. **A read-only value bound to a property is a Field**, not a Presentation component.
+4. **A block that loads its own data is a Widget, not a Template.** Templates arrange `children` handed to them; widgets fetch.
+5. **When torn between two subtypes** (for example `decimal` vs `currency`), pick the one whose formatting affordance is visible. A currency symbol means `currency`.
+6. **Output only the lines shown above.** No explanation, no prose, no bullet list.