@salesforce/afv-skills 1.21.0 → 1.23.0

package/skills/omnistudio-epc-catalog-generate/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: omnistudio-epc-catalog-generate
+description: "Salesforce Industries CME EPC product-modeling skill for Product2-based catalog creation. Use when creating EPC products, configuring product attributes, building offer bundles with Product Child Items, or reviewing EPC DataPack JSON metadata for product catalog changes. TRIGGER when: user creates or updates Product2 EPC records, AttributeAssignment payloads, AttributeMetadata/AttributeDefaultValues, Offer bundles, or ProductChildItem relationships. DO NOT TRIGGER when: designing OmniScripts/FlexCards/Integration Procedures (use omnistudio-omniscript-generate, omnistudio-flexcard-generate, or omnistudio-integration-procedure-generate), implementing Apex business logic (use platform-apex-generate), or troubleshooting deployment pipelines (use platform-metadata-deploy)."
+metadata:
+  version: "1.0"
+---
+
+# omnistudio-epc-catalog-generate: CME EPC Product and Offer Modeling
+
+Expert Salesforce Industries CME EPC modeler for creating Product2-based catalog entries, assigning configurable attributes, and building offer bundles through Product Child Item relationships.
+
+This skill is optimized for DataPack-style metadata authoring. Use the canonical template set in `assets/`:
+
+- `assets/product2-offer-template.json`
+- `assets/attribute-assignment-template.json`
+- `assets/product-child-item-template.json`
+- `assets/pricebook-entries-template.json`
+- `assets/price-list-entries-template.json`
+- `assets/object-field-attributes-template.json`
+- `assets/orchestration-scenarios-template.json`
+- `assets/decomposition-relationships-template.json`
+- `assets/compiled-attribute-overrides-template.json`
+- `assets/override-definitions-template.json`
+- `assets/parent-keys-template.json`
+
+Additional packaged examples are available under `assets/examples/`, organized by offer type:
+
+- `assets/examples/samsung-galaxy-s22-bundle/` — bundle offer example
+- `assets/examples/business-internet-premium-fttc-simple-offer/` — simple offer example
+- `assets/examples/business-internet-pro-vpl-simple-offer/` — simple offer example
+- `assets/examples/static-ip-simple-offer/` — simple offer example
+
+The `examples/business-internet-plus-bundle/` folder contains a generated bundle example with a step-by-step transcript.
+
+The root `assets/` folder contains the canonical baseline template set for bundle authoring.
+
+---
+
+## Scope
+
+- **In scope**: Creating and reviewing EPC Product2 records, Product Child Items, attribute metadata, offer bundles, pricing entries, decomposition and orchestration artifacts, and DataPack JSON payloads
+- **Out of scope**: OmniScript/FlexCard/Integration Procedure design (use `omnistudio-omniscript-generate`, `omnistudio-flexcard-generate`, or `omnistudio-integration-procedure-generate`), Apex business logic implementation (use `platform-apex-generate`), deployment pipeline troubleshooting (use `platform-metadata-deploy`)
+
+---
+
+## Quick Reference
+
+- **Primary object**: `Product2` (EPC product and offer records)
+- **Attribute data**: `%vlocity_namespace%__AttributeMetadata__c`, `%vlocity_namespace%__AttributeDefaultValues__c`, and `%vlocity_namespace%__AttributeAssignment__c`
+- **Offer bundle composition**: `%vlocity_namespace%__ProductChildItem__c`
+- **Offer marker**: `%vlocity_namespace%__SpecificationType__c = "Offer"` and `%vlocity_namespace%__SpecificationSubType__c = "Bundle"`
+- **Companion bundle artifacts**: pricebook entries, price list entries, object field attributes, orchestration scenarios, decomposition relationships, compiled attribute overrides, override definitions, and parent keys
+
+**Scoring**: 120 points across 6 categories.  
+**Thresholds**: `>= 95` Deploy-ready | `70-94` Needs review | `< 70` Block and fix.
+
+**Glossary**: EPC = Enterprise Product Catalog | CME = Communications, Media & Energy | DataPack = Vlocity JSON deployment artifact | PCI = ProductChildItem
+
+---
+
+## Asset Template Set
+
+Use the root `assets/` templates when creating a bundle payload:
+
+- `product2-offer-template.json`
+- `attribute-assignment-template.json`
+- `product-child-item-template.json`
+- `pricebook-entries-template.json`
+- `price-list-entries-template.json`
+- `object-field-attributes-template.json`
+- `orchestration-scenarios-template.json`
+- `decomposition-relationships-template.json`
+- `compiled-attribute-overrides-template.json`
+- `override-definitions-template.json`
+- `parent-keys-template.json`
+
+For additional real-world variants, use the per-example folders under `assets/examples/`.
+
+---
+
+## Core Responsibilities
+
+1. **Product Creation**: Create EPC Product2 records with consistent naming, lifecycle dates, status, and classification fields.
+2. **Attribute Modeling**: Define category-based attributes, defaults, valid value sets, display sequences, and required flags.
+3. **Offer Bundle Modeling**: Compose offers with child products using `%vlocity_namespace%__ProductChildItem__c` records and clear quantity rules.
+4. **Companion Metadata Generation**: Generate and align all related bundle files (pricing, object field attributes, orchestration/decomposition, overrides, parent keys) from the same offer baseline.
+5. **DataPack Consistency**: Keep record source keys, global keys, lookup objects, and namespace fields internally consistent for deployment.
+
+---
+
+## Invocation Rules (Mandatory)
+
+Route to this skill whenever the prompt intent matches either of these:
+
+1. **Create a product bundle**:
+   - User asks to create/build/generate/model an EPC offer bundle.
+   - User asks for Product2 offer setup with Product Child Items.
+   - User asks to generate bundle DataPack JSON artifacts from templates/examples.
+
+2. **Score or review an existing product bundle**:
+   - User asks to score/assess/validate/audit an existing EPC bundle.
+   - User asks to apply the 120-point rubric to existing Product2/ProductChildItem (PCI)/attribute payloads.
+   - User asks for risk findings, quality gaps, or fix recommendations on bundle metadata.
+
+**Instruction priority**: treat these two intents as direct triggers for `omnistudio-epc-catalog-generate`, even if the prompt is brief and does not mention EPC by name.
+
+---
+
+## Workflow (Create/Review)
+
+### Phase 0: Prerequisites
+
+Before proceeding, verify:
+
+1. Salesforce Industries org with EPC enabled
+2. Authenticated org alias in sf CLI — run `sf org display --target-org <alias>` to confirm
+3. Namespace model identified: `%vlocity_namespace%`, `vlocity_cmt`, or Core
+
+If any prerequisite is unmet, ask the user to supply the org alias or namespace before continuing.
+
+---
+
+### Phase 1: Identify Catalog Intent
+
+Ask for:
+
+- Product type: **spec product** or **offer bundle**
+- Domain taxonomy: Family, Type/SubType, category path, and channel
+- Attribute requirements: required/optional, picklist values, default values
+- Bundle composition: child products, quantity constraints, optional vs required
+- Target org namespace model: `%vlocity_namespace%`, `vlocity_cmt`, or Core
+
+**Idempotency check**: If a `ProductCode` is provided, verify no matching Product2 already exists before generating artifacts:
+
+```bash
+sf data query --query "SELECT Id, Name, ProductCode FROM Product2 WHERE ProductCode = '<code>'" --target-org <alias>
+```
+
+If a match is found, ask the user whether this is a net-new record or an update to the existing one before continuing.
+
+### Phase 1A: Clarifying Questions for Complete Bundle (Mandatory)
+
+Before generating a new offer bundle payload, ask clarifying questions until all required inputs are known.
+
+Required clarification checklist:
+
+1. **Offer identity**
+   - What is the offer name and `ProductCode`?
+   - Is this net-new or an update to an existing Product2 offer?
+2. **Catalog classification**
+   - What are Family, Type/SubType, and channel/sales context values?
+   - Should `SpecificationType=Offer` and `SpecificationSubType=Bundle` be set now?
+3. **Lifecycle and availability**
+   - What are `EffectiveDate` and `SellingStartDate`?
+   - Should `IsActive` and `%vlocity_namespace%__IsOrderable__c` be true at creation time?
+4. **Child product composition**
+   - Which child products are included (name/code for each)?
+   - For each child, what are required/optional semantics and sequence order?
+5. **Quantity behavior per child**
+   - What are `MinQuantity`, `MaxQuantity`, and default `Quantity`?
+   - Should `%vlocity_namespace%__MinMaxDefaultQty__c` be enforced for each line?
+6. **Attribute model**
+   - Which attributes are required vs optional?
+   - What are valid values, defaults, display types, and display sequences?
+7. **Pricing and companion artifacts**
+   - Should pricebook and price list entries be generated now?
+   - Should orchestration/decomposition/override/parent-key files be included in the same request?
+8. **Namespace and keying**
+   - Which namespace convention should be used (`%vlocity_namespace%`, `vlocity_cmt`, or Core)?
+   - Are there existing global keys/source keys to preserve?
+
+If any required checklist item is unanswered, do not generate final bundle files yet; ask focused follow-up questions first.
+
+### Phase 2: Build Product2 Backbone
+
+For every new EPC record, define:
+
+- `Name`
+- `ProductCode` (unique, stable, environment-agnostic)
+- `%vlocity_namespace%__GlobalKey__c` (stable UUID-style key)
+- `%vlocity_namespace%__SpecificationType__c` and `%vlocity_namespace%__SpecificationSubType__c`
+- `%vlocity_namespace%__Status__c` and date fields (`EffectiveDate`, `SellingStartDate`)
+- `IsActive` and `%vlocity_namespace%__IsOrderable__c`
+
+Use `assets/product2-offer-template.json` as baseline structure.
+
+### Phase 3: Add Attributes
+
+When attributes are required:
+
+1. Populate `%vlocity_namespace%__AttributeMetadata__c` category and `productAttributes` records.
+2. Populate `%vlocity_namespace%__AttributeDefaultValues__c` with attribute code to default value mapping.
+3. Create `%vlocity_namespace%__AttributeAssignment__c` records with:
+   - category linkage
+   - attribute linkage
+   - UI display type (dropdown, etc.)
+   - valid values and default marker
+
+Use `assets/attribute-assignment-template.json` as the assignment baseline.
+
+### Phase 4: Build Offer Bundles
+
+For offers:
+
+1. Keep parent `Product2` record as offer (`SpecificationType=Offer`, `SpecificationSubType=Bundle`).
+2. Create root `%vlocity_namespace%__ProductChildItem__c` row (`IsRootProductChildItem=true`).
+3. Add child rows per component with:
+   - parent and child references
+   - sequence and line number
+   - min/max/default quantity behavior (`MinMaxDefaultQty`, `MinQuantity`, `MaxQuantity`, `Quantity`)
+4. Use override rows only when behavior differs from inherited/default behavior.
+
+Use `assets/product-child-item-template.json` for child relationship structure.
+
+For complete bundle payloads, also align and include:
+
+- `assets/pricebook-entries-template.json`
+- `assets/price-list-entries-template.json`
+- `assets/object-field-attributes-template.json`
+- `assets/orchestration-scenarios-template.json`
+- `assets/decomposition-relationships-template.json`
+- `assets/compiled-attribute-overrides-template.json`
+- `assets/override-definitions-template.json`
+- `assets/parent-keys-template.json`
+
+### Phase 4B: Generate Companion Metadata Files
+
+When the user asks to generate a bundle, generate/update all companion files together as one coherent set:
+
+1. `pricebook-entries-template.json` and `price-list-entries-template.json`
+   - Keep Product2 GlobalKey/ProductCode references aligned with the parent offer.
+2. `object-field-attributes-template.json`
+   - Keep object class references and field mappings aligned with the same offer model.
+3. `orchestration-scenarios-template.json` and `decomposition-relationships-template.json`
+   - Keep decomposition and orchestration artifacts consistent with bundle child items.
+4. `compiled-attribute-overrides-template.json` and `override-definitions-template.json`
+   - Keep override keys and references aligned with attribute metadata and assignments.
+5. `parent-keys-template.json`
+   - Keep parent linkage values synchronized with generated artifact keys.
+
+**Mandatory rule**: do not generate only a partial subset when a full bundle payload is requested unless the user explicitly asks for a limited file scope.
+
+### Phase 5: Validate and Handoff
+
+Read `assets/completion-block-template.txt` and fill in each field to produce the handoff summary block.
+
+---
+
+## Output Expectations
+
+For a full offer bundle request, the following files are produced:
+
+| File pattern | Content |
+|---|---|
+| `*_DataPack.json` | Product2 offer record |
+| `*_AttributeAssignments.json` | Attribute category and assignment payloads |
+| `*_ProductChildItems.json` | Root and child ProductChildItem (PCI) rows |
+| `*_PricebookEntries.json` | Standard and custom pricebook entries |
+| `*_PriceListEntries.json` | Price list entries |
+| `*_ObjectFieldAttributes.json` | Object field mapping |
+| `*_OrchestrationScenarios.json` | Orchestration metadata |
+| `*_DecompositionRelationships.json` | Decomposition metadata |
+| `*_CompiledAttributeOverrides.json` | Compiled attribute override payload |
+| `*_OverrideDefinitions.json` | Override definition payload |
+| `*_ParentKeys.json` | Parent key linkage |
+
+For spec product (non-bundle) requests, only the DataPack, AttributeAssignments, PricebookEntries, and PriceListEntries files are required.
+
+If generation of any file fails, stop immediately. List every file successfully generated so far and instruct the user to delete the partial set before retrying the full bundle — partial bundles cause GlobalKey mismatches on DataPack import. Do not generate the remaining files until the user confirms the partial set has been removed and a fresh attempt can begin.
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| Attribute default not in valid values list | Ensure the default value exists inside the `values[]` array — cart will reject invalid defaults at runtime |
+| Root ProductChildItem row missing | Offer bundle traversal breaks without `IsRootProductChildItem=true` — always create the root row first |
+| Mixed namespace convention in one payload | Pick one namespace style (`%vlocity_namespace%` vs `vlocity_cmt`) and apply it consistently across all files in the bundle |
+| Duplicate display sequences in same attribute category | UI ordering conflict — use spaced values (10, 20, 30) to allow future inserts without collisions |
+| `ProductCode` contains environment suffix | Breaks cross-org references — remove `_DEV`, `_UAT`, `_PROD` suffixes |
+| Companion files generated with different offer names | Key mismatches break DataPack import — generate all companion files from the same baseline offer name and GlobalKey |
+| DataPack import fails with `Key not found` error | A lookup object reference points to a GlobalKey absent in the target org — verify GlobalKey alignment across all companion files before import |
+| DataPack import rolls back silently | Add `--verbose` during deployment and inspect the log for the specific record and field that triggered the rollback |
+| Namespace mismatch between files in same bundle | Mixed `%vlocity_namespace%` and `vlocity_cmt` styles in one payload cause field resolution failures — enforce a single namespace style throughout |
+
+---
+
+## Generation Guardrails (Mandatory)
+
+If any anti-pattern appears, stop and ask for confirmation before proceeding.
+
+| Anti-pattern | Why it fails | Required correction |
+|---|---|---|
+| Missing `ProductCode` or unstable code values | Breaks quote/cart references and package diffs | Use deterministic code convention |
+| Hardcoded org-specific IDs in relationships | Fails across orgs/environments | Use lookup objects with matching keys/global keys |
+| Offer bundle without root PCI row | Runtime bundle traversal issues | Add root `%vlocity_namespace%__ProductChildItem__c` |
+| Attribute defaults not present in valid values | Invalid cart configuration defaults | Ensure default exists in allowed value set |
+| Duplicate display sequences in same attribute category | UI ordering conflict | Enforce unique and spaced sequence values |
+| Offer marked active with incomplete child references | Broken bundle at runtime | Complete and validate child link set before activation |
+| Mixed naming styles (`snake_case`, ad hoc abbreviations) | Reduces maintainability and discoverability | Enforce naming convention from references doc |
+
+---
+
+## Scoring Model (120 Points)
+
+Read `references/scoring-model.md` for the full 6-category rubric and per-category criteria.
+
+| Category | Points |
+|---|---|
+| Catalog Identity and Naming | 20 |
+| EPC Product Structure | 20 |
+| Attribute Modeling | 25 |
+| Offer Bundle Composition | 25 |
+| DataPack Integrity | 15 |
+| Documentation and Handoff | 15 |
+| **Total** | **120** |
+
+---
+
+## CLI and Validation Commands
+
+Read `scripts/cli-validation-commands.sh` for sf CLI queries to inspect and validate EPC artifacts in your org. Replace `<org>` with your authenticated org alias before running.
+
+---
+
+## Sample Skill Invocation Commands
+
+Read `scripts/sample-invocations.sh` for example invocations covering common EPC modeling tasks. Replace `cursor-agent` with your local agent command wrapper if different.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/product2-offer-template.json` | Phase 2 — baseline structure for every new Product2 offer record |
+| `assets/attribute-assignment-template.json` | Phase 3 — attribute assignment structure |
+| `assets/product-child-item-template.json` | Phase 4 — root and child PCI row structure |
+| `assets/pricebook-entries-template.json` | Phase 4B — pricebook entry companion file |
+| `assets/price-list-entries-template.json` | Phase 4B — price list entry companion file |
+| `assets/object-field-attributes-template.json` | Phase 4B — object field mapping companion file |
+| `assets/orchestration-scenarios-template.json` | Phase 4B — orchestration scenarios companion file |
+| `assets/decomposition-relationships-template.json` | Phase 4B — decomposition relationships companion file |
+| `assets/compiled-attribute-overrides-template.json` | Phase 4B — compiled attribute overrides companion file |
+| `assets/override-definitions-template.json` | Phase 4B — override definitions companion file |
+| `assets/parent-keys-template.json` | Phase 4B — parent keys companion file |
+| `assets/completion-block-template.txt` | Phase 5 — handoff summary block template |
+| `assets/examples/samsung-galaxy-s22-bundle/` | Phase 4 — bundle offer example; load `*_DataPack.json` and `*_ProductChildItems.json` first, then companion files as needed |
+| `assets/examples/business-internet-premium-fttc-simple-offer/` | Phase 4 — simple offer (FTTC) example; load `*_DataPack.json` and `*_AttributeAssignments.json` first |
+| `assets/examples/business-internet-premium-fttc-simple-offer/Business-Internet-Premium-FTTC_RuleAssignments.json` | Phase 4 — FTTC offer rule assignment example; load when modeling rule-based attribute constraints |
+| `assets/examples/business-internet-pro-vpl-simple-offer/` | Phase 4 — simple offer (Pro VPL) example; load `*_DataPack.json` and `*_AttributeAssignments.json` first |
+| `assets/examples/static-ip-simple-offer/` | Phase 4 — simple offer (Static IP) example; load `*_DataPack.json` and `*_AttributeAssignments.json` first |
+| `examples/business-internet-plus-bundle/` | Phase 4 — generated bundle example with step-by-step transcript; load `TRANSCRIPT.md` first, then specific JSON files referenced in it |
+| `references/epc-field-guide.md` | Phase 2 & 3 — EPC field-level guidance and common pitfalls |
+| `references/naming-conventions.md` | Phase 2 & 3 — naming and keying conventions |
+| `references/scoring-model.md` | Phase 5 — full 6-category scoring rubric with per-category criteria |
+| `scripts/cli-validation-commands.sh` | Phase 5 — sf CLI queries for validating EPC artifacts in org |
+| `scripts/sample-invocations.sh` | On Start — reference example invocations for common EPC tasks |
+
+---
+
+## Cross-Skill Integration
+
+| From Skill | To `omnistudio-epc-catalog-generate` | When |
+|---|---|---|
+| omnistudio-dependencies-analyze | -> omnistudio-epc-catalog-generate | Need current dependency and namespace inventory first |
+| platform-custom-object-generate / platform-custom-field-generate | -> omnistudio-epc-catalog-generate | Need object or field readiness before EPC modeling |
+| platform-soql-query | -> omnistudio-epc-catalog-generate | Need existing catalog query analysis |
+
+| From `omnistudio-epc-catalog-generate` | To Skill | When |
+|---|---|---|
+| omnistudio-epc-catalog-generate | -> omnistudio-omniscript-generate | Configure guided selling UX using the modeled catalog |
+| omnistudio-epc-catalog-generate | -> omnistudio-integration-procedure-generate | Build server-side orchestration over product and pricing payloads |
+| omnistudio-epc-catalog-generate | -> platform-metadata-deploy | Deploy validated catalog metadata |
+
+---
+
+## External References
+
+Local references:
+
+- [references/epc-field-guide.md](references/epc-field-guide.md) — EPC field-level guidance and minimum required fields
+- [references/naming-conventions.md](references/naming-conventions.md) — Naming and keying conventions for products, attributes, and bundles
+
+---
+
+## Notes
+
+- This skill is intentionally DataPack-first and optimized for `vlocity/Product2/...` artifact authoring.
+- Keep `%vlocity_namespace%` placeholders intact in templates to preserve portability.
+- Prefer creating reusable spec products first, then assemble offers via child relationships.
+
+---

package/skills/omnistudio-epc-catalog-generate/examples/business-internet-plus-bundle/TRANSCRIPT.md

@@ -0,0 +1,58 @@
+# Build Transcript: Business Internet Plus Bundle
+
+## Request
+
+Create a Product2 offer bundle named **Business Internet Plus** with ProductCode **BIZ-INT-PLUS-01**, include **3 child products**, and generate the complete companion DataPack JSON set from template structures.
+
+## Skill Used
+
+- `omnistudio-epc-catalog-generate`
+  - Trigger reason: EPC Product2 offer-bundle modeling, attribute assignments, Product Child Items, and full companion DataPack artifact generation.
+
+## Planning Process (Executed)
+
+1. Loaded the EPC skill instructions and guardrails.
+2. Reviewed all template artifacts in `assets/`:
+   - `product2-offer-template.json`
+   - `attribute-assignment-template.json`
+   - `product-child-item-template.json`
+   - `pricebook-entries-template.json`
+   - `price-list-entries-template.json`
+   - `object-field-attributes-template.json`
+   - `orchestration-scenarios-template.json`
+   - `decomposition-relationships-template.json`
+   - `compiled-attribute-overrides-template.json`
+   - `override-definitions-template.json`
+   - `parent-keys-template.json`
+3. Chose a new example folder:
+   - `examples/business-internet-plus-bundle`
+4. Built a coherent keying strategy:
+   - Parent Product2 GlobalKey: `9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101`
+   - Stable VlocityRecordSourceKey references in all companion files.
+5. Created bundle composition:
+   - Required root PCI row.
+   - Exactly 3 child products:
+     - Managed Router
+     - Internet Security Suite
+     - Static IP Add-On
+6. Generated complete companion metadata set and aligned references to parent Product2/global keys.
+7. Kept `%vlocity_namespace%` placeholders intact for namespace portability.
+
+## Files Generated
+
+- `Business-Internet-Plus_DataPack.json`
+- `Business-Internet-Plus_AttributeAssignments.json`
+- `Business-Internet-Plus_ProductChildItems.json`
+- `Business-Internet-Plus_PricebookEntries.json`
+- `Business-Internet-Plus_PriceListEntries.json`
+- `Business-Internet-Plus_ObjectFieldAttributes.json`
+- `Business-Internet-Plus_OrchestrationScenarios.json`
+- `Business-Internet-Plus_DecompositionRelationships.json`
+- `Business-Internet-Plus_CompiledAttributeOverrides.json`
+- `Business-Internet-Plus_OverrideDefinitions.json`
+- `Business-Internet-Plus_ParentKeys.json`
+
+## Notes
+
+- Override companion files are intentionally present as empty arrays in this baseline example (no override behavior modeled yet).
+- This payload is structured as a template-aligned sample; external dependencies (child product records, picklists, object classes, orchestration plan definitions) must exist in target orgs for deployment success.

package/skills/omnistudio-epc-catalog-generate/references/epc-field-guide.md

@@ -0,0 +1,90 @@
+<!-- Parent: omnistudio-epc-catalog-generate/SKILL.md -->
+
+# EPC Field Guide (Product2 + Bundles + Attributes)
+
+This quick guide captures the minimum field set for creating CME EPC products and offer bundles in DataPack-style metadata.
+
+## Root Template Files (`assets/`)
+
+The skill root `assets/` directory contains a full template set aligned to the Business Internet Essential (VPL) bundle:
+
+- `product2-offer-template.json`
+- `attribute-assignment-template.json`
+- `product-child-item-template.json`
+- `pricebook-entries-template.json`
+- `price-list-entries-template.json`
+- `object-field-attributes-template.json`
+- `orchestration-scenarios-template.json`
+- `decomposition-relationships-template.json`
+- `compiled-attribute-overrides-template.json`
+- `override-definitions-template.json`
+- `parent-keys-template.json`
+
+## Product2: Minimum Recommended EPC Fields
+
+| Field | Purpose | Example |
+|---|---|---|
+| `Name` | Human-readable catalog name | `Business Internet Essential (VPL)` |
+| `ProductCode` | Stable technical identifier | `VEPC_OFFERING_BUSINESS_INTERNET_ESSENTIAL` |
+| `%vlocity_namespace%__GlobalKey__c` | Cross-environment stable key | UUID-like value |
+| `%vlocity_namespace%__SpecificationType__c` | Product classification | `Offer` |
+| `%vlocity_namespace%__SpecificationSubType__c` | Product subtype | `Bundle` |
+| `%vlocity_namespace%__Status__c` | EPC status | `Active` |
+| `%vlocity_namespace%__IsOrderable__c` | Order eligibility | `true` |
+| `IsActive` | Product availability | `true` |
+| `%vlocity_namespace%__SellingStartDate__c` | Sales lifecycle start | `2021-07-31T04:00:00.000Z` |
+
+## Attribute Metadata Blocks
+
+### `%vlocity_namespace%__AttributeMetadata__c`
+
+Contains category/group metadata and product attribute records:
+
+- category `Code__c`, `Name`, `displaySequence`
+- per-attribute `code`, `label`, `inputType`, `required`, `values[]`
+
+### `%vlocity_namespace%__AttributeDefaultValues__c`
+
+Map from attribute code to default value:
+
+```json
+{
+  "VEPC_ATTR_DOWNLOAD_SPEED": "50 Mbps",
+  "VEPC_ATTR_CONTRACT_TERM": "Month-to-Month"
+}
+```
+
+## Product Bundle Modeling (`%vlocity_namespace%__ProductChildItem__c`)
+
+Offer bundles are composed through child item rows:
+
+- one root row: `IsRootProductChildItem = true`
+- child rows: parent and child references + sequence and quantity settings
+
+Key quantity fields:
+
+- `%vlocity_namespace%__MinQuantity__c`
+- `%vlocity_namespace%__MaxQuantity__c`
+- `%vlocity_namespace%__Quantity__c`
+- `%vlocity_namespace%__MinMaxDefaultQty__c` (e.g., `"0, 1, 1"`)
+
+## Common Field Pitfalls
+
+| Pitfall | Impact | Fix |
+|---|---|---|
+| `ProductCode` reused for multiple products | Cart and quote ambiguity | Enforce unique catalog code |
+| Default attribute value missing from values list | Runtime configuration errors | Keep defaults inside valid value set |
+| Missing root ProductChildItem | Broken offer traversal | Always add root row |
+| Direct org-specific IDs in DataPack | Deploy failures across orgs | Use lookup source keys and global keys |
+
+## Included Example Packs
+
+The skill ships with:
+
+- `assets/` (canonical EPC bundle template set)
+- `assets/examples/samsung-galaxy-s22-bundle/` (bundle offer example)
+- `assets/examples/business-internet-premium-fttc-simple-offer/` (simple offer example)
+- `assets/examples/business-internet-pro-vpl-simple-offer/` (simple offer example)
+- `assets/examples/static-ip-simple-offer/` (simple offer example)
+
+The example folders contain related DataPack-style files, including Product2 payloads, attribute assignments, product child items, and pricing artifacts.

package/skills/omnistudio-epc-catalog-generate/references/naming-conventions.md

@@ -0,0 +1,80 @@
+<!-- Parent: omnistudio-epc-catalog-generate/SKILL.md -->
+
+# CME EPC Naming Conventions
+
+Use deterministic naming across products, attributes, and offer bundles. Names should remain stable across environments and releases.
+
+## Product Name
+
+Format:
+
+```text
+<Business Domain> <Tier/Variant> (<Channel or Variant Tag>)
+```
+
+Examples:
+
+- `Business Internet Essential (VPL)`
+- `Business Internet Premium (FTTC)`
+
+## Product Code
+
+Format:
+
+```text
+<PREFIX>_<ENTITY>_<DOMAIN>_<VARIANT>
+```
+
+Examples:
+
+- `VEPC_OFFERING_BUSINESS_INTERNET_ESSENTIAL`
+- `VEPC_SPEC_BUSINESS_ROUTER_ADVANCED`
+
+Rules:
+
+- Uppercase with underscores only
+- No environment suffixes (`_DEV`, `_UAT`, `_PROD`)
+- Stable after go-live
+
+## Attribute Code
+
+Format:
+
+```text
+VEPC_ATTR_<DOMAIN>_<ATTRIBUTE_NAME>
+```
+
+Examples:
+
+- `VEPC_ATTR_DOWNLOAD_SPEED`
+- `VEPC_ATTR_CONTRACT_TERM`
+
+## Attribute Category Code
+
+Format:
+
+```text
+VEPC_ATTRIBUTE_CATEGORY_<DOMAIN_BLOCK>
+```
+
+Examples:
+
+- `VEPC_ATTRIBUTE_CATEGORY_INTERNET_DETAILS`
+- `VEPC_ATTRIBUTE_CATEGORY_CONTRACT_DETAILS`
+
+## Offer Bundle Composition
+
+When naming bundles and child items:
+
+- Bundle parent `ProductCode` should indicate offering intent (`VEPC_OFFERING_*`)
+- Child product codes should represent reusable specs (`VEPC_SPEC_*` recommended)
+- Sequence values (`SeqNumber`, `ChildLineNumber`) should be unique per parent and spaced for future inserts
+
+## Anti-Patterns
+
+| Bad pattern | Why to avoid |
+|---|---|
+| `Product1`, `Offer_New`, `CatalogItemA` | Non-descriptive and unstable |
+| Mixed abbreviations without glossary | Hard to maintain and search |
+| Date/version in `ProductCode` | Breaks long-term references |
+| Same `ProductCode` in multiple products | Downstream ambiguity |