@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.ai-common/prompts/generate-embedded-components.md

@@ -0,0 +1,315 @@
+---
+ai-description: "Generate Pega components styled to match a customer's existing application — given a component list and a Design Profile, produces a pega-components/ folder with implementations that satisfy the Pega behavioral contract while rendering with the customer's design system, tokens, and styling approach, and reading like their own code"
+---
+
+## Step 0 — Resolve missing information
+
+Read the user's message carefully. Extract:
+
+- **Component list** — the Pega component names to generate (e.g., `TextInput`, `Dropdown`, `DefaultForm`, `TwoColumn`, `ToDo`)
+- **Design Profile location** — the path to the `.design-profile.md` file (default: `pega-components/.design-profile.md`)
+- **Output path** — where to write the generated components (default: `pega-components/`)
+
+The **component list** is required. If it is not provided and cannot be inferred from prior conversation context, stop and ask the user.
+
+Two components are required whether or not the list names them. Add them silently and note the addition in the summary report:
+
+- **`FieldValueList`** — when the list contains any field component. Every field renders its display-only mode through it
+- **`ActionButtons`** — always. Every assignment renders action controls, and leaving it ungenerated puts SDK-styled buttons in the middle of the customer's form
+
+If no Design Profile exists at the expected location:
+
+- Ask the user: "No Design Profile found. Should I analyze your codebase first to create one?"
+- If yes, execute the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo.md` skill first, then return here.
+
+---
+
+## Step 1 — Name resolution and categorization
+
+Every component you generate must correspond to one canonical component listed in `{{PROMPT_DIR}}/component-manifest.json`. Pega defines a fixed set of components, and the manifest is the complete list of them. A name the user supplies may not be one of those names — it may be the name their design system uses. Your job in this step is to turn every requested name into exactly one canonical name.
+
+Read `{{PROMPT_DIR}}/component-manifest.json` once. It contains three things you need here:
+
+- `components` — the canonical names, grouped by type (`field`, `template`, `widget`, `designSystemExtension`, `infra`)
+- `aliases` — known non-canonical names and the canonical name each one maps to
+- `behaviorClasses` — a fixed list of behaviour descriptions, each mapping to one or more canonical names
+
+For each component name in the user's list, work through the following stages in order. Stop at the first stage that produces an answer.
+
+### Stage 1 — Normalized name match
+
+1. Take the requested name and make a normalized form: convert it to lowercase, then remove all spaces, hyphens, and underscores, then remove a trailing `field`, `component`, `input`, or `control` if one is present.
+2. Build the same normalized form for every canonical name in `components`.
+3. If exactly one canonical name has the same normalized form, that is the answer.
+
+### Stage 2 — Alias lookup
+
+1. Look up the requested name in the `aliases` object. Compare using the normalized form from Stage 1 so that casing and spacing do not matter.
+2. If the name is present, the value it maps to is the answer.
+
+### Stage 3 — Behaviour class match
+
+Do not search for a "similar sounding" name here. Follow these three sub-steps exactly.
+
+1. Decide what the requested component does for the end user, and choose **exactly one** entry from the `behaviorClasses` list that describes that behaviour. You must pick one of the listed classes. If you cannot honestly place the component in any of them, go to Stage 4.
+2. Read the canonical names that class maps to. If the class maps to exactly one name, that is the candidate.
+3. Read the candidate's skill file (see Step 4a for the location) and confirm its behavioural contract covers what the user asked for. If it clearly does not, go to Stage 4.
+
+If the class maps to more than one canonical name, choose between them using the case type and surrounding context the user has already given you. If the context does not make the choice obvious, go to Stage 4.
+
+### Stage 4 — Ask the user
+
+Tell the user that the requested name is not a Pega component name, list the two or three canonical names you considered most likely, and ask which one they want. Do not guess, and do not proceed with that component until they answer.
+
+### Rules for this step
+
+- This process always ends in one of two ways: a single canonical name, or a question to the user. It never ends with you inventing a component.
+- Once a canonical name is chosen, use it everywhere afterwards: the type grouping, the skill file you read, the generated folder name, and the registry key. The originally requested name is only used when reporting the substitution back to the user.
+- Record the pairing of requested name and canonical name. You will report it in Step 6e.
+- If two different requested names resolve to the same canonical name, generate that component once.
+- If a requested name resolves to a component listed under `infra` in the manifest, generate it only if it is one of the three overridable chrome components (`ActionButtons`, `Stages`, `MultiStep`). Every other `infra` component is SDK-provided and must be skipped. See Guardrail 9.
+
+After every name is resolved, group the canonical names by type so you can read each type's skill files together.
+
+---
+
+## Step 2 — Read foundational context (once)
+
+Read the following **once** before the generation loop:
+
+1. **The Design Profile** — read the full `.design-profile.md`. Its design tokens, styling convention, and validation display convention are authoritative and must be replicated. Its component patterns (input interface, state management, event handling) and file conventions describe the customer's own code — read them for context, but generated components follow the Pega contract and Pega-owned paths instead.
+
+2. **General type-level skills** — for each component type present in the grouped list, read the corresponding general skill:
+
+   | Type                    | Skill file                                 |
+   | ----------------------- | ------------------------------------------ |
+   | `field`                 | `{{SKILL_DIR}}/field-components.md`        |
+   | `template`              | `{{SKILL_DIR}}/template-components.md`     |
+   | `widget`                | `{{SKILL_DIR}}/widget-components.md`       |
+   | `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension.md` |
+   | `infra`                 | `{{SKILL_DIR}}/infra-components.md`        |
+
+   These establish the shared behavioral contract for each category.
+
+3. **The embedded component rules** — read `{{INSTRUCTIONS_DIR}}/embedded-component{{AI_FILE_EXT}}` for the constraints specific to embedded/customer-context generation.
+
+---
+
+## Step 3 — Discover and inspect the customer's UI primitives (once)
+
+The Design Profile names the customer's UI library and lists representative components, but it does not record how those components are _called_. This step fills that gap. Collect rendering surface only — import path, composition shape, and the prop names for value, change, disabled, and invalid states. Behaviour is not part of this: Pega owns state, events, and validation regardless of what the customer's primitive offers.
+
+The two cases below are not exclusive — a project that vendors its UI library into its own source tree is both.
+
+1. If the customer uses a third-party UI library:
+   - Locate the library's installed package in the project
+   - Inspect its available components (input, select, checkbox, radio, textarea, layout containers, cards, etc.)
+   - Note their prop interfaces and usage patterns from the package documentation or type definitions
+
+2. If the customer's primitives live in their own source tree:
+   - Read the components listed in the Design Profile's representative component examples
+   - Note the same details from the source
+
+3. For each primitive, record whether it is a single element or a composed set — a select may be `<Select>` alone, or a `Select` plus trigger, value, content, and item parts that must be nested in a fixed order.
+
+4. Produce a **UI Primitive Inventory** (kept in working memory, not written to disk):
+
+   | Primitive kind | Customer's component | Import | Composition and props |
+   | -------------- | -------------------- | ------ | --------------------- |
+   | Text input     | ...                  | ...    | ...                   |
+   | Select         | ...                  | ...    | ...                   |
+   | ...            | ...                  | ...    | ...                   |
+
+If a primitive kind has no equivalent in the customer's project, record that too. Step 4b composes one from the primitives that do exist, and Guardrail 1 still applies — composition uses their primitives, never an invented or newly installed one.
+
+---
+
+## Step 4 — Generate components (loop)
+
+For each component in the list, in the grouped order (fields first, then templates, then widgets, then DSE, then any overridable chrome components):
+
+### 4a. Read the component-specific skill
+
+Look for `{{SKILL_DIR}}/{type}-skills/{ComponentName}.md` where `{type}` is `field`, `template`, `widget`, `design-system-extension`, or `infra`.
+
+If the file exists, read it fully. It defines:
+
+- The component's specific behavioral contract (beyond the general type contract)
+- Required states, modes, and edge cases
+- Any sub-components or dependencies
+
+Use the canonical name resolved in Step 1 to locate this file — not the name the user originally typed. Because Step 1 always ends at a canonical name, a skill file is expected to exist. Rely on the general type skill alone only when the resolved canonical name genuinely has no skill file of its own.
+
+### 4b. Determine the target UI primitive
+
+From the UI Primitive Inventory (Step 3), identify the customer's primitive to render this Pega component with. If no direct equivalent exists, compose from the customer's available primitives.
+
+### 4c. Generate the component
+
+Create the component implementation that satisfies **both**:
+
+1. **The Pega behavioral contract** (from skill files):
+   - All required inputs/outputs as defined by the type contract
+   - All required behaviors (display modes, validation feedback, event handling, accessibility)
+   - Bridge integration (PConnect access, registry lookups for sub-components)
+
+2. **The customer's conventions** (from Design Profile):
+   - Use the customer's UI library primitives for rendering
+   - Follow the customer's styling approach (apply styles the way they do)
+   - Follow the customer's import conventions (aliases, grouping, named/default)
+   - Use the customer's export style and co-located file layout (barrel files, types, styles)
+
+State, events, validation wiring, and prop contracts are deliberately absent from that list — they come from the Pega behavioral contract above, no matter how the customer writes their own forms. A customer whose own screens use a form library does not change how a generated component holds a value or commits it.
+
+**Exception — the output path is not the customer's to choose.** `pega-components/` is a generated, Pega-owned tree that the customer never authors in, so its layout is fixed rather than inferred from the Design Profile. Write the component to:
+
+```
+{output_path}/{type}/{ComponentName}/{ComponentName}.{ext}
+```
+
+- `{type}` is literal — `field`, `template`, `widget`, `designSystemExtension`, or `infra` — and is never renamed or flattened. The instruction globs match on it.
+- `{ComponentName}` is the canonical Pega component name resolved in Step 1, verbatim, for both the folder and the implementation file, whatever the customer's naming style is. `Checkbox` produces `Checkbox/Checkbox.*`, never `checkbox/CheckboxField.*`; `Date` produces `Date/Date.*`, never `date/DateField.*`.
+- `{ext}` follows the customer's framework, not their file-naming style.
+
+Deterministic paths are what let tooling, globs, and regeneration find components again. Customer conventions govern the _contents_ of these files, not their location or name. If the customer's repo lints file names, exclude `pega-components/` from that rule rather than bending the paths.
+
+### 4d. Register the component
+
+Add an entry for this component in the registry file at `{output_path}/component-map.*`:
+
+- The key must be the canonical Pega component name (as resolved in Step 1)
+- The value must reference the generated component's export
+
+---
+
+## Step 5 — Create the registry file
+
+After all components are generated, ensure the registry file (`{output_path}/component-map.*`) is complete:
+
+1. It must export a function that registers all generated components into a provided component registry
+2. It must spread/include the SDK's built-in infrastructure components from the SDK adapter package. Most of these are **never generated** — they ship as-is from the SDK with their own styling (loaded via the SDK stylesheet imported in the host entry point):
+   - **NavBar** — renders navigation controls
+   - **DeferLoad** — handles deferred/lazy content loading
+   - **VerticalTabs** — renders vertical tab navigation
+   - **DashboardFilter** — renders dashboard filtering controls
+3. Three infrastructure components are **overridable chrome**. They render inline with the case form, so SDK styling on them is the most visible mismatch in an embedded flow — they may be generated and registered as overrides. An override key replaces the spread SDK entry, so it must be listed _after_ the spread:
+   - **ActionButtons** — the Cancel/Save/Submit row at the bottom of an assignment
+   - **Stages** — the case stage progress indicator
+   - **MultiStep** — the step navigation within a multi-step assignment
+4. Every component from the input list must have a corresponding entry
+5. No `infra` component other than those three may appear in the generated output — the rest are always sourced from the SDK adapter package
+
+---
+
+## Step 5.1 — Create a fallback component
+
+Generate a simple fallback component at `{output_path}/FallbackComponent.*` that renders when the SDK requests a component not found in the registry. This component should:
+
+1. Accept the same base interface as all Pega components (the PConnect accessor)
+2. Display the unresolved component's name so the developer knows what's missing
+3. Render any children passed to it (so the component tree continues rendering)
+4. Use minimal, unobtrusive styling (a bordered box with the component name) following the customer's styling approach
+5. Be suitable for development only — in production, all components should be registered
+
+The registry file from Step 5 should export this fallback component alongside the registration function.
+
+---
+
+## Step 6 — Verify
+
+Execute the following checks. Do **not** declare completion until all pass.
+
+### 6a. Type/compilation check
+
+Run the project's type-checking or compilation command. If any errors exist in the generated files:
+
+- Read the error messages
+- Fix the affected component
+- Re-run the check
+- Maximum 2 retry cycles per component
+
+### 6b. Contract compliance
+
+For each generated component, verify it meets its behavioral contract by reading the source:
+
+**Field components must:**
+
+- Accept and use the PConnect accessor
+- Handle display modes (at minimum: editable, display-only)
+- Render validation feedback when validation state is present
+- Wire value change and commit events through the SDK actions API
+- Pass through the test identifier
+
+**Template components must:**
+
+- Traverse child component descriptors via the PConnect accessor
+- Delegate child rendering to the SDK bridge component
+- Support inherited property propagation to children
+
+**Widget components must:**
+
+- Consume configuration properties from the PConnect accessor
+- Render display content based on provided data sources
+
+**Design system extension components must:**
+
+- Accept the inputs their pattern requires — the PConnect accessor for data-aware display components, plain display props for pure-presentation components, the field input contract for rich editors
+- Render display content only — no value commit wiring, since these components do not own field state
+- Preserve the prop shape other components depend on, because they are resolved through the registry rather than imported directly (for example, every field component renders its display-only mode through `FieldValueList`, which must keep accepting `name`, `value`, and an optional `variant`)
+- Pass through the test identifier when the component renders an identifiable container
+
+**Infrastructure (chrome) components must:**
+
+- Accept exactly the props the SDK component accepts — these do not share one shape. `ActionButtons` takes `arMainButtons`, `arSecondaryButtons`, and `onButtonPress(action, buttonType)` and receives **no** PConnect accessor; `Stages` takes the PConnect accessor plus `stages`; `MultiStep` takes the PConnect accessor plus `children`, `itemKey`, `actionButtons`, and `onButtonPress`
+- Localize labels through the Pega locale utilities rather than hardcoding text
+- Differ from the SDK implementation in markup and styling only — props, callback signatures, and localization are unchanged
+
+### 6c. Registry completeness
+
+Read the generated registry file and confirm:
+
+- Every component from the input list has a corresponding key
+- All imports resolve to existing generated files
+- The SDK infrastructure components are included via spread/merge
+
+### 6d. Dependency validation
+
+Verify that every import in the generated files resolves to either:
+
+- A package present in the customer's dependency manifest
+- A file within the generated `pega-components/` folder
+- The Pega SDK packages (added in integration wiring)
+
+If any import references a package not in the project, either:
+
+- Replace it with an available equivalent, or
+- Flag it for the user: "The component `X` requires package `Y` which is not currently installed."
+
+### 6e. Summary report
+
+Output a table summarizing the generation:
+
+| Requested Name | Resolved As  | Type     | Status | Notes                                        |
+| -------------- | ------------ | -------- | ------ | -------------------------------------------- |
+| TextInput      | TextInput    | field    | ✅     | Generated using [customer's input component] |
+| Combobox       | AutoComplete | field    | ✅     | Resolved by alias                            |
+| DefaultForm    | DefaultForm  | template | ✅     | Uses [customer's grid/layout]                |
+| ...            | ...          | ...      | ...    | ...                                          |
+
+Whenever `Requested Name` and `Resolved As` differ, say so in your reply as well, and name the stage that produced the match (normalized name, alias, behaviour class, or user's choice). The user must never discover a substitution only by reading the generated files.
+
+---
+
+## Guardrails
+
+1. **Never invent UI primitives** — only use components available in the customer's UI library or their custom component set
+2. **Never skip behavioral requirements** — every item in the skill file's contract must be implemented, even if the customer's equivalent doesn't natively support it (add the behavior manually)
+3. **Never break existing code** — the generated `pega-components/` folder is additive; never modify the customer's existing components. This prompt does not wire the integration or verify it — those are separate steps, and they are the only ones permitted to edit the customer's files, confined to the seams their skills enumerate
+4. **Never hardcode design tokens** — always reference the customer's token system (variables, constants, theme values)
+5. **Respect the customer's code conventions** — the contents of generated files should look like the customer wrote them
+6. **One folder per component** — each component gets its own folder named after its canonical Pega name; paths are Pega's, contents are the customer's
+7. **Preserve SDK bridge contract** — the component must work with the SDK bridge component's resolution and rendering mechanism; the input interface defined in the skill file is non-negotiable
+8. **Only canonical components exist** — every generated component must correspond to a canonical name in the component manifest, and every registry key must be that canonical name. Never create a component for a name that is not in the manifest, and never add the user's original wording as an extra registry key or alias. Pega resolves components by its own naming standard, so a non-canonical key would never be requested at runtime.
+9. **Never generate infrastructure components, except the three overridable chrome components** — `ActionButtons`, `MultiStep`, and `Stages` may be generated into `{output_path}/infra/` and registered as overrides, because they render inline with the case form and must match the customer's UI. They are not interchangeable: `ActionButtons` and `MultiStep` are **assignment** chrome and belong in an embedded flow, whereas `Stages` is **case** chrome that only appears on a case-view surface and must not be generated for an embedded flow. Every other component categorized as `infra` in the component manifest (NavBar, DeferLoad, VerticalTabs, DashboardFilter) is provided by the SDK adapter package and must never be generated, overridden, or customized. If one of those appears in the input list, skip it and note in the summary report that it is SDK-provided.
+
+10. **Reproduce the chrome components' contract exactly** — read the skill file for `ActionButtons`, `MultiStep`, or `Stages` in `{{SKILL_DIR}}/infra-skills/` before generating it. Only the markup and styling change; props, callback signatures, and localization are fixed by the SDK.

package/templates/react-sdk-reference/.ai-common/prompts/generate-field-components.md

@@ -0,0 +1,190 @@
+---
+ai-description: Generate all (or a subset of) field components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where field components should be generated (e.g. `src/components/field/`, `app/ui/fields/`)
+- **Component list** — which components to generate (default: all 27 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the output path, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the field components be generated? (e.g. `src/components/field/`)
+
+If the user specified a subset (e.g., "just TextInput and Dropdown"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default)
+
+| Component       | Pega Name       |
+| --------------- | --------------- |
+| AutoComplete    | AutoComplete    |
+| CancelAlert     | CancelAlert     |
+| Checkbox        | Checkbox        |
+| Currency        | Currency        |
+| Date            | Date            |
+| DateTime        | DateTime        |
+| Decimal         | Decimal         |
+| Dropdown        | Dropdown        |
+| Email           | Email           |
+| Group           | Group           |
+| Integer         | Integer         |
+| Location        | Location        |
+| Multiselect     | Multiselect     |
+| ObjectReference | ObjectReference |
+| Percentage      | Percentage      |
+| Phone           | Phone           |
+| RadioButtons    | RadioButtons    |
+| RichText        | RichText        |
+| ScalarList      | ScalarList      |
+| SelectableCard  | SelectableCard  |
+| SemanticLink    | SemanticLink    |
+| TextArea        | TextArea        |
+| TextContent     | TextContent     |
+| TextInput       | TextInput       |
+| Time            | Time            |
+| URL             | URL             |
+| UserReference   | UserReference   |
+
+---
+
+## Step 1 — Read `field-components.md` (once, for the entire session)
+
+Read the full contents of `{{SKILL_DIR}}/field-components.md`.
+
+This gives you:
+
+- The behavioral skeleton every field component must follow (state, effects, event handling, display modes)
+- The Design System Adaptation guide (prop mapping conventions, form layout wrappers)
+- The abstract template to use as a base for all components
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed.
+
+**Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
+
+You MUST also thoroughly inspect the installed design system package:
+
+1. **Discover all available components** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every input control the package actually provides (Input, Select, Checkbox, DatePicker, Radio, etc.). Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map each field component to the best available DS component** — the component names in the list (e.g. `AutoComplete`, `Dropdown`) may not have an exact name match in the installed design system. Using the complete list you just discovered, identify which DS component best serves the same purpose. If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every component you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
+
+Also check:
+
+- Whether the design system has a **form layout wrapper** (label + input + helper text) — use it instead of manual margins
+- Whether it has **size/density/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **companion icons package** — read its exports before using any icon name; never guess icon names
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+Build a **DS API reference map** from this discovery. You will reuse it for every component — do not repeat this discovery per component.
+
+### 2.1 — Install the DS styles package and configure global CSS (MANDATORY)
+
+Design systems require their global stylesheet — without it, components render unstyled.
+
+#### Known DS style requirements (examples — verify against the README you already read):
+
+| Design System | Styles Package (example) | CSS Import (example)                     | Provider Wrapper (example) |
+| ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
+| Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
+| Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
+| Radix Themes  | `@radix-ui/themes`       | `import '@radix-ui/themes/styles.css';`  | `<Theme>`                  |
+| Chakra UI     | (included)               | (none — runtime)                         | `<ChakraProvider>`         |
+| Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
+| MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
+
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted from the README — they take precedence over this table.
+
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder in `node_modules` for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
+
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
+
+Report what was installed/configured (or "already configured").
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether the component's file or directory already exists at the output path.
+
+If **any** exist, report them all at once and ask:
+
+> "The following N components already exist: [list]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/field-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `field-components.md`.
+
+After reading, extract and keep active:
+
+- **Behavioral Contract** — state management, option loading, edge cases specific to this component
+- **Design System Mapping** table — the recommended DS component for the chosen design system
+- **UI control type** — use this to select the closest DS primitive if the chosen DS is not in the mapping table
+
+If no skill file exists at that path, use the general behavioral skeleton from `field-components.md` loaded in Step 1.
+
+⚠️ The general skill file (`field-components.md`) provides the behavioral skeleton. The component-specific skill file provides the **exact event handling, option-loading logic, and edge cases**. Both are needed — generating from only the general skill will produce generic inputs that miss component-specific behavior (e.g., AutoComplete's async search, Currency's formatting).
+
+### 4b — Generate the component files
+
+Create the directory `<outputPath>/<ComponentName>/`.
+
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
+
+Follow the implementation structure described in `field-components.md` (loaded in Step 1). That file specifies the exact imports, interface, props handling, display mode guards, event handling, and render approach for this project's framework. Use the DS component you identified in Step 2 as the primary input element.
+
+Apply the Behavioral Contract from the component skill file (state management, option loading, event sequences, edge cases specific to this component).
+
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern.
+
+### 4c — Register the component
+
+Open the project's component map file (the file that maps component names to their implementations) and:
+
+1. Add an import at the top of the file in the **Fields** section
+2. Add an entry in the component map object under the fields comment
+
+⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping:
+
+- `Date: DateField` (not `DateField,`) — `Date` is a reserved JS global
+- `URL: URLComponent` (not `URLComponent,`) — `URL` is a reserved JS global
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
+
+---
+
+## Step 5 — Verify the build
+
+Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.