@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.ai-common/instructions/widget-component.md

@@ -0,0 +1,45 @@
+---
+ai-globs: **/widget/**/*
+---
+
+# Widget Component Rules
+
+When creating or modifying widget components, follow these rules:
+
+## Required Structure
+
+1. **Extend the base widget props interface** — the project's standard props type, or the field props type if the widget behaves like a field (e.g. Attachment) — when defining the component's prop interface.
+
+2. **Export the component** using the project's standard export convention.
+
+## Widget Patterns
+
+### Data-Fetching Widget (ToDo, CaseHistory, Followers)
+
+Fetches data from the platform's data pages on mount. Obtain the current context from the PConnect accessor, request the datasource via the platform's data page utility, and store the result in local state. Render the fetched data inside the widget's card/list presentation.
+
+### Action Widget (ToDo)
+
+Triggers case actions. Retrieve the list of assignments using the platform's assignment helper (passing the PConnect accessor). Each assignment provides an `onClick` callback, urgency, name, and other display metadata.
+
+### File Widget (Attachment, FileUtility)
+
+Handles file upload/download via the platform's attachment utility APIs — upload with progress/error callbacks and context, download by attachment id and context.
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's component props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop legacy styling utility classes — map each one to an equivalent style.
+
+## Key Rules
+
+- Widgets are self-contained — they manage their own data fetching
+- Use the platform's data page utility for data page access
+- Use the platform's attachment utility for file operations
+- Always handle loading and error states
+- Widgets may subscribe to platform events via the platform's pub/sub utility
+- Clean up subscriptions when the component unmounts
+- Do NOT drop card padding, list item spacing, or avatar sizing when removing legacy presentation components — replicate them in the replacement

package/templates/react-sdk-reference/.ai-common/prompts/add-component.md

@@ -0,0 +1,193 @@
+---
+ai-description: Add a new component type to the registry
+---
+
+## Step 0 — Resolve missing information
+
+Read the user's message carefully. Extract:
+
+- **Component name** — the exact name (e.g. `AutoComplete`, `DatePicker`)
+- **Component type** — one of: `field` | `template` | `widget` | `designSystemExtension` | `infra`
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output path** — the exact or relative path where the component should be generated (e.g. `src/components/field/AutoComplete`)
+
+All four values above are required. If any are 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 provide ALL of: component name, component type, design system, and 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 to ask (only ask the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is the exact component name?
+3. What type of component is this? (field / template / widget / designSystemExtension / infra)
+4. What is the exact or relative path where the component should be generated? (e.g. `src/components/field/AutoComplete`)
+
+### Case-insensitive component name matching
+
+The user may enter the component name in any casing (e.g. `autocomplete`, `Autocomplete`, `autoComplete`). It is your responsibility to match it to the correct canonical name by checking the skill files in `{{SKILL_DIR}}/field-skills/`, `{{SKILL_DIR}}/template-skills/`, `{{SKILL_DIR}}/widget-skills/`, `{{SKILL_DIR}}/design-system-extension-skills/`, and `{{SKILL_DIR}}/infra-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
+
+Once all four are known, continue to Step 1.
+
+---
+
+## Step 1 — Check for existing component (overwrite check)
+
+Before generating, check if a component already exists at the resolved output path:
+
+1. Check if the component file or directory already exists at the resolved output path.
+2. If it **does exist**, ask the user: _"A component named `<ComponentName>` already exists at `<outputPath>`. Do you want to overwrite it with the new implementation?"_
+   - If the user says **yes**, proceed to overwrite.
+   - If the user says **no**, stop and skip generation.
+3. If it **does not exist**, continue to Step 2.
+
+---
+
+## Step 2 — Check for skill files
+
+Always read the **general type skill** for the component type:
+
+| Component Type          | General 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`        |
+
+Only three `infra` components may be added — `ActionButtons`, `Stages`, and `MultiStep`. Every other infrastructure component is SDK-provided; if the user names one, stop and tell them it is not generated.
+
+Then look for a **component-specific skill** based on the component type:
+
+| Component Type          | Specific Skill Location                                           |
+| ----------------------- | ----------------------------------------------------------------- |
+| `field`                 | `{{SKILL_DIR}}/field-skills/<ComponentName>.md`                   |
+| `template`              | `{{SKILL_DIR}}/template-skills/<ComponentName>.md`                |
+| `widget`                | `{{SKILL_DIR}}/widget-skills/<ComponentName>.md`                  |
+| `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` |
+| `infra`                 | `{{SKILL_DIR}}/infra-skills/<ComponentName>.md`                   |
+
+If the component-specific skill file exists, read it fully. Pay special attention to:
+
+- **Behavioral Contract** — state management, event handling, option loading, edge cases
+- **Design System Mapping** table — the recommended component for the chosen design system
+
+You must read **both** the general type skill and the component-specific skill (if it exists) before proceeding.
+
+Examples:
+
+- `AutoComplete` (field) → read `field-components.md` + `field-skills/AutoComplete.md`
+- `AdvancedSearch` (template) → read `template-components.md` + `template-skills/AdvancedSearch.md`
+- `AppAnnouncement` (widget) → read `widget-components.md` + `widget-skills/AppAnnouncement.md`
+- `AlertBanner` (designSystemExtension) → read `design-system-extension.md` + `design-system-extension-skills/AlertBanner.md`
+- `ActionButtons` (infra) → read `infra-components.md` + `infra-skills/ActionButtons.md`
+
+If no component-specific skill file exists, continue using the general pattern from the type skill.
+
+---
+
+## Step 3 — Check and install dependencies
+
+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 component the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map the requested component to the best available DS component** — the component name provided by the user (e.g. `AutoComplete`) may not have an exact name match in the installed design system. Using the complete component list you just discovered, identify which DS component best serves the same purpose. For example, `@carbon/react` does not export an `AutoComplete` component — but it does export `ComboBox`, which provides equivalent autocomplete/typeahead functionality. 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
+
+### 3.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.
+
+Since you have already read the design system's README, install the styles package it specifies (if any). If you have already installed it, skip this step. If the README did not provide enough detail about design-system-specific styles, browse the `styles/` folder within the installed design system package to locate the correct stylesheet and understand how it should be applied. Ensure these design system styles are applied globally so that all generated components render correctly.
+
+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 5 — Generate the component
+
+Create the component directory at the resolved output path (from Step 0).
+
+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).
+
+### field
+
+Follow the implementation structure described in `field-components.md` (read in Step 2). That file specifies the exact imports, interface, props destructuring, display mode guards, event handling, and render approach for this project's framework. Use the DS component you identified in Step 3 as the primary input element.
+
+If a component-specific skill file exists, also incorporate its Behavioral Contract (validation rules, option loading, event sequences, edge cases).
+
+### template
+
+Follow the implementation structure described in `template-components.md` (read in Step 2). That file specifies the layout, form, and page patterns — including how to render child components — for this project's framework.
+
+### widget
+
+Follow the implementation structure described in `widget-components.md` (read in Step 2). That file specifies the imports, interface, data-fetching lifecycle, and render approach for this project's framework. Use the DS components you identified in Step 3 for presentation.
+
+If a component-specific skill file exists, follow its Behavioral Contract for data-fetching logic, state management, and interaction handling.
+
+### designSystemExtension
+
+Follow the implementation structure described in `design-system-extension.md` (read in Step 2). That file specifies the pattern variants (pure display, PConnect display, complex display) for this project's framework.
+
+---
+
+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.
+
+---
+
+## Step 6 — Register in component-map.ts
+
+Open the project's component map file (the file that maps component names to their implementations) and:
+
+1. Add the import at the top of the file, in the correct section (Fields / Templates / Widgets / Design System Extension / Infra)
+2. Add an entry in the component map object under the matching category comment
+
+An `infra` entry is an override of a component the SDK already contributes, so it must be listed **after** the SDK's built-in component spread. Listed before it, the spread replaces it and the override silently does nothing.
+
+⚠️ **Key name exceptions** — verify after registration:
+
+- `Date: DateField` (not `DateField,`) — `Date` is a reserved JS global
+- `URL: URLComponent` (not `URLComponent,`) — `URL` is a reserved JS global
+- `Todo: ToDo` (not `ToDo,`) — Pega sends `Todo`, not `ToDo`
+
+If the component being added matches any of the above, use the explicit `key: value` mapping instead of shorthand.
+
+Do not restructure or reorder any existing entries.
+
+---
+
+## Step 7 — Verify the build
+
+Run the project's build process to confirm everything compiles without errors.
+
+If build errors occur, diagnose and fix them before reporting completion. Report what files were created and what was registered in the component map.

package/templates/react-sdk-reference/{.claude → .ai-common}/prompts/component-manifest.json

@@ -119,7 +119,9 @@
       { "name": "SubTabs", "path": "src/components/template/SubTabs" },
       { "name": "TwoColumn", "path": "src/components/template/TwoColumn" },
       { "name": "WideNarrow", "path": "src/components/template/WideNarrow" },
-      { "name": "WssNavBar", "path": "src/components/template/WssNavBar" }
+      { "name": "WssNavBar", "path": "src/components/template/WssNavBar" },
+      { "name": "SearchForm", "path": "src/components/template/DataReference/SearchForm" },
+      { "name": "SearchGroups", "path": "src/components/template/AdvancedSearch/SearchGroups" }
     ],
     "widget": [
       {
@@ -133,7 +135,11 @@
       { "name": "QuickCreate", "path": "src/components/widget/QuickCreate" },
       { "name": "SummaryItem", "path": "src/components/widget/SummaryItem" },
       { "name": "SummaryList", "path": "src/components/widget/SummaryList" },
-      { "name": "ToDo", "path": "src/components/widget/ToDo" }
+      { "name": "ToDo", "path": "src/components/widget/ToDo" },
+      {
+        "name": "ActionButtonsForFileUtil",
+        "path": "src/components/widget/FileUtility/ActionButtonsForFileUtil"
+      }
     ],
     "infra": [
       { "name": "ActionButtons", "path": "src/components/infra/ActionButtons" },
@@ -142,6 +148,7 @@
         "path": "src/components/infra/DashboardFilter"
       },
       { "name": "DeferLoad", "path": "src/components/infra/DeferLoad" },
+      { "name": "MultiStep", "path": "src/components/infra/MultiStep" },
       { "name": "NavBar", "path": "src/components/infra/NavBar" },
       { "name": "Stages", "path": "src/components/infra/Stages" },
       { "name": "VerticalTabs", "path": "src/components/infra/VerticalTabs" }
@@ -189,5 +196,102 @@
         "path": "src/components/designSystemExtension/WssQuickCreate"
       }
     ]
+  },
+  "aliases": {
+    "Combobox": "AutoComplete",
+    "ComboBox": "AutoComplete",
+    "Typeahead": "AutoComplete",
+    "Autosuggest": "AutoComplete",
+    "SearchSelect": "AutoComplete",
+    "Select": "Dropdown",
+    "Picklist": "Dropdown",
+    "SingleSelect": "Dropdown",
+    "Radio": "RadioButtons",
+    "RadioGroup": "RadioButtons",
+    "OptionGroup": "RadioButtons",
+    "Switch": "Checkbox",
+    "Toggle": "Checkbox",
+    "Boolean": "Checkbox",
+    "Textbox": "TextInput",
+    "StringInput": "TextInput",
+    "SingleLineText": "TextInput",
+    "Memo": "TextArea",
+    "MultilineText": "TextArea",
+    "Notes": "TextArea",
+    "WYSIWYG": "RichText",
+    "HtmlEditor": "RichText",
+    "FormattedText": "RichText",
+    "DatePicker": "Date",
+    "Calendar": "Date",
+    "TimePicker": "Time",
+    "DateTimePicker": "DateTime",
+    "Timestamp": "DateTime",
+    "Money": "Currency",
+    "Amount": "Currency",
+    "Percent": "Percentage",
+    "Ratio": "Percentage",
+    "Tags": "Multiselect",
+    "Chips": "Multiselect",
+    "TokenInput": "Multiselect",
+    "MultiSelectList": "Multiselect",
+    "Hyperlink": "SemanticLink",
+    "Anchor": "SemanticLink",
+    "FileUpload": "Attachment",
+    "Dropzone": "Attachment",
+    "Attachments": "Attachment",
+    "Grid": "SimpleTable",
+    "Table": "SimpleTable",
+    "DataTable": "SimpleTable",
+    "Repeater": "SimpleTable",
+    "Card": "SelectableCard",
+    "Tile": "SelectableCard",
+    "Address": "Location",
+    "Map": "Location",
+    "GeoPoint": "Location",
+    "Person": "UserReference",
+    "Assignee": "UserReference",
+    "Label": "TextContent",
+    "StaticText": "TextContent",
+    "Paragraph": "TextContent"
+  },
+  "behaviorClasses": {
+    "free text entry": ["TextInput"],
+    "long or multi-line text entry": ["TextArea"],
+    "text entry with suggestion list": ["AutoComplete"],
+    "single choice from a list": ["Dropdown"],
+    "single choice with all options visible": ["RadioButtons"],
+    "multiple choice from a list": ["Multiselect"],
+    "on/off value": ["Checkbox"],
+    "date value": ["Date"],
+    "time value": ["Time"],
+    "date and time value": ["DateTime"],
+    "whole number": ["Integer"],
+    "fractional number": ["Decimal"],
+    "monetary amount": ["Currency"],
+    "percentage": ["Percentage"],
+    "email address": ["Email"],
+    "phone number": ["Phone"],
+    "web address": ["URL"],
+    "formatted rich text entry": ["RichText", "RichTextEditor"],
+    "list of simple values": ["ScalarList"],
+    "reference to another record": ["ObjectReference"],
+    "reference to a person": ["UserReference", "Operator"],
+    "geographic location": ["Location"],
+    "file handling": ["Attachment", "FileUtility"],
+    "read-only text display": ["TextContent"],
+    "link display": ["SemanticLink"],
+    "grouped set of fields": ["Group", "FieldGroup", "FieldGroupList"],
+    "confirmation or alert message": ["CancelAlert", "AlertBanner", "Banner"],
+    "layout container": ["DefaultForm", "OneColumn", "TwoColumn", "NarrowWide", "WideNarrow"],
+    "tabular list": ["SimpleTable", "ListView"],
+    "selectable card": ["SelectableCard"],
+    "summary or display block": ["SummaryItem", "SummaryList", "Details", "DetailsFields", "CaseSummary"],
+    "label and value pair list": ["FieldValueList", "CaseSummaryFields"],
+    "task or work item list": ["ToDo"],
+    "activity or history feed": ["CaseHistory", "Pulse"],
+    "announcement or promotional block": ["AppAnnouncement"],
+    "record creation shortcut": ["QuickCreate", "WssQuickCreate"],
+    "people following a record": ["Followers"],
+    "search input form": ["SearchForm", "AdvancedSearch", "PromotedFilters"]
   }
 }

package/templates/react-sdk-reference/.ai-common/prompts/embedded-component-manifest.md

@@ -0,0 +1,155 @@
+---
+ai-description: 'Design Profile template — defines the structure and schema for the customer codebase analysis output consumed by generate-embedded-components'
+---
+
+# Design Profile Schema
+
+This document defines the required structure for a Design Profile produced by the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo.md` skill. The profile is consumed by the `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}` prompt to generate Pega components matching the customer's application.
+
+---
+
+## Required Sections
+
+Every Design Profile **must** contain the following sections. If a section cannot be populated (e.g., the project has no explicit theme tokens), note "Not detected — infer from component source" rather than omitting the section.
+
+---
+
+### 1. Project Fundamentals
+
+| Field         | Description                                                                                                    | Example values                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Framework     | Application framework and version                                                                              | Any frontend framework + version                             |
+| Language      | Primary programming language and configuration                                                                 | Any typed or untyped language                                |
+| UI Library    | Component library name and version, or "Custom"                                                                | Any component library or "Custom"                            |
+| Styling       | Styling approach identifier                                                                                    | Utility classes, CSS modules, CSS-in-JS, scoped styles, etc. |
+| Form Handling | Form library or pattern used by the customer's own forms — **context only**, generated components never use it | Any form library or "Native"                                 |
+| Module System | Module format used                                                                                             | ESM, CommonJS, etc.                                          |
+
+---
+
+### 2. Design Tokens
+
+Organize by category. Use semantic names where the customer defines them; otherwise use descriptive labels.
+
+**Colors:**
+
+- Primary, secondary, accent
+- Error/danger, warning, success, info
+- Background (surface, page, card)
+- Text (primary, secondary, disabled, inverse)
+- Border (default, focus, error)
+
+**Spacing:**
+
+- The scale used (e.g., 4px base, or named sizes)
+
+**Typography:**
+
+- Font families (heading, body, mono)
+- Size scale
+- Weight scale
+- Line heights
+
+**Borders & Radii:**
+
+- Border widths
+- Radius values (small, medium, large, full)
+
+**Shadows:**
+
+- Elevation levels (if defined)
+
+**Breakpoints:**
+
+- Responsive boundaries (if defined)
+
+---
+
+### 3. Component Patterns
+
+Document how the customer's existing components work. **This section is context, not instructions.** Only the Validation Display and Styling conventions below are replicated in generated Pega components, because they affect appearance. The Input Interface, State Management, and Event Handling conventions are recorded so the reader understands the codebase — generated components follow the Pega contract for all three regardless of what is written here.
+
+**Input Interface Convention:**
+
+- How components define what they accept (typed interfaces, attribute schemas, parameter decorators, etc.)
+- Whether inputs are flat or nested/grouped
+- Common optional vs required patterns
+
+**State Management Convention:**
+
+- How components manage transient/local state
+- Controlled vs uncontrolled patterns
+- How derived/computed values are handled
+
+**Event Handling Convention:**
+
+- How components report value changes to parents
+- Whether changes are immediate, debounced, or committed on blur
+- Event naming conventions
+
+**Validation Display Convention:**
+
+Record the visual treatment only. Generated components read validation messages from PConnect, never from the customer's form state — so capture what an error _looks_ like, not where the customer's error value comes from.
+
+- Where error messages appear (below field, in tooltip, as banner)
+- How error styling is applied (border color, background, icon)
+- Whether validation is inline or form-level
+
+**Styling Convention:**
+
+- How styles are applied to elements
+- How conditional/dynamic styles are _expressed_ (e.g., error, disabled, focus states) — record the visual mechanism only; Pega supplies the state itself
+- How responsive behavior is implemented
+
+---
+
+### 4. File Conventions
+
+**Context only.** Generated components use Pega-owned paths and names (`pega-components/{type}/{ComponentName}/`), so Structure and Naming below do not apply to them. Re-exports, test location, and style location still inform co-located files.
+
+| Field          | Description                                             |
+| -------------- | ------------------------------------------------------- |
+| Structure      | Folder-per-component, flat, grouped by feature, etc.    |
+| Naming         | File and folder naming convention (casing, separators)  |
+| Re-exports     | Barrel/index file pattern (if any)                      |
+| Test location  | Co-located with component or in separate test directory |
+| Style location | Co-located, in shared styles directory, or inline       |
+
+---
+
+### 5. Import Conventions
+
+| Field                    | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| Path resolution          | Aliases used, or relative paths                                  |
+| Grouping order           | How imports are organized (external → internal → relative, etc.) |
+| Default/named preference | Which import style dominates                                     |
+| Style imports            | How stylesheets or style modules are imported                    |
+
+Generated components import the customer's UI primitives through their path aliases. Relative paths are used only _within_ `pega-components/` — for shared helpers, barrel files, and the registry file's component imports. One Pega component is never imported into another to render it; that always goes through the component registry.
+
+---
+
+### 6. Representative Component Examples
+
+List 3–5 components that were analyzed, with their file paths. These serve as reference points that the generation workflow can re-read for detailed implementation guidance.
+
+| Component | Path   | Why selected                 |
+| --------- | ------ | ---------------------------- |
+| [Name]    | [path] | Text input with validation   |
+| [Name]    | [path] | Select/dropdown with options |
+| [Name]    | [path] | Layout/container component   |
+| ...       | ...    | ...                          |
+
+---
+
+## Usage
+
+The generation prompt reads this profile once at the start of component generation. It uses:
+
+- **Project Fundamentals** → to determine which SDK adapter to reference and what language to generate
+- **Design Tokens** → to apply correct colors, spacing, typography without hardcoding values
+- **Component Patterns** → to replicate the customer's validation display and styling conventions; the rest of the section is context only
+- **File Conventions** → to inform co-located files (barrels, tests, styles); generated components' paths and names come from Pega, not from here
+- **Import Conventions** → to write imports that match the project's style
+- **Representative Examples** → as reference sources to re-read for detailed pattern matching