@salesforce/afv-skills 1.8.0 → 1.9.1

package/skills/building-omnistudio-callable-apex/assets/pattern_callable_openinterface.cls

@@ -0,0 +1,40 @@
+/**
+ * System.Callable skeleton — same inputMap/options structure as VlocityOpenInterface.
+ * Use when integrating with Open Interface callers or when callers pass { inputMap, options }.
+ * Backward-compatible: if args lacks 'inputMap', treats args itself as inputMap.
+ *
+ * Replace Industries_XxxCallable and actionOne with the actual class/action names.
+ */
+public with sharing class Industries_XxxCallable implements System.Callable {
+
+    public Object call(String action, Map<String, Object> args) {
+        Map<String, Object> inputMap = (args != null && args.containsKey('inputMap'))
+            ? (Map<String, Object>) args.get('inputMap')
+            : (args != null ? args : new Map<String, Object>());
+        Map<String, Object> options  = (args != null && args.containsKey('options'))
+            ? (Map<String, Object>) args.get('options')
+            : new Map<String, Object>();
+        if (inputMap == null) { inputMap = new Map<String, Object>(); }
+        if (options  == null) { options  = new Map<String, Object>(); }
+
+        switch on action {
+            when 'actionOne' {
+                return actionOne(inputMap, options);
+            }
+            when else {
+                throw new IndustriesCallableException('Unsupported action: ' + action);
+            }
+        }
+    }
+
+    private Map<String, Object> actionOne(Map<String, Object> inputMap, Map<String, Object> options) {
+        // 1. Validate required keys from inputMap
+        // 2. Coerce types safely
+        // 3. Run business logic (SOQL with WITH USER_MODE, DML with sharing)
+        // 4. Return response envelope
+        return new Map<String, Object>{
+            'success' => true,
+            'data'    => new Map<String, Object>()
+        };
+    }
+}

package/skills/building-omnistudio-callable-apex/assets/pattern_callable_vanilla.cls

@@ -0,0 +1,32 @@
+/**
+ * Vanilla System.Callable skeleton — flat args, no Open Interface coupling.
+ * Use when callers pass flat args and no VlocityOpenInterface integration is required.
+ *
+ * Replace Industries_XxxCallable and actionOne with the actual class/action names.
+ */
+public with sharing class Industries_XxxCallable implements System.Callable {
+
+    public Object call(String action, Map<String, Object> args) {
+        Map<String, Object> input = args != null ? args : new Map<String, Object>();
+
+        switch on action {
+            when 'actionOne' {
+                return actionOne(input);
+            }
+            when else {
+                throw new IndustriesCallableException('Unsupported action: ' + action);
+            }
+        }
+    }
+
+    private Map<String, Object> actionOne(Map<String, Object> args) {
+        // 1. Validate required keys (e.g. args.get('requiredKey'))
+        // 2. Coerce types safely
+        // 3. Run business logic (SOQL with WITH USER_MODE, DML with sharing)
+        // 4. Return response envelope
+        return new Map<String, Object>{
+            'success' => true,
+            'data'    => new Map<String, Object>()
+        };
+    }
+}

package/skills/building-omnistudio-callable-apex/assets/pattern_migration.cls

@@ -0,0 +1,54 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// BEFORE: VlocityOpenInterface2
+// Results written into outputMap by reference; return value is Boolean success flag.
+// ─────────────────────────────────────────────────────────────────────────────
+// global class OrderOpenInterface implements omnistudio.VlocityOpenInterface2 {
+//     global Boolean invokeMethod(String methodName, Map<String, Object> input,
+//                                 Map<String, Object> output,
+//                                 Map<String, Object> options) {
+//         if (methodName == 'createOrder') {
+//             output.putAll(createOrder(input, options));
+//             return true;
+//         }
+//         return false;
+//     }
+//
+//     private Map<String, Object> createOrder(Map<String, Object> inputMap,
+//                                             Map<String, Object> options) {
+//         return new Map<String, Object>{ 'success' => true };
+//     }
+// }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AFTER: System.Callable
+// Same inputs (inputMap, options); return value replaces outputMap mutation.
+// Action strings mirror the original methodName values to keep callers stable.
+// ─────────────────────────────────────────────────────────────────────────────
+public with sharing class Industries_XxxCallable implements System.Callable {
+
+    public Object call(String action, Map<String, Object> args) {
+        Map<String, Object> inputMap = (args != null && args.containsKey('inputMap'))
+            ? (Map<String, Object>) args.get('inputMap')
+            : (args != null ? args : new Map<String, Object>());
+        Map<String, Object> options  = (args != null && args.containsKey('options'))
+            ? (Map<String, Object>) args.get('options')
+            : new Map<String, Object>();
+        if (inputMap == null) { inputMap = new Map<String, Object>(); }
+        if (options  == null) { options  = new Map<String, Object>(); }
+
+        switch on action {
+            when 'createOrder' {
+                return createOrder(inputMap, options);
+            }
+            when else {
+                throw new IndustriesCallableException('Unsupported action: ' + action);
+            }
+        }
+    }
+
+    private Map<String, Object> createOrder(Map<String, Object> inputMap,
+                                            Map<String, Object> options) {
+        // Validate input, run business logic, return response envelope
+        return new Map<String, Object>{ 'success' => true, 'data' => new Map<String, Object>() };
+    }
+}

package/skills/building-omnistudio-callable-apex/assets/pattern_openinterface.cls

@@ -0,0 +1,45 @@
+/**
+ * VlocityOpenInterface2 implementation skeleton.
+ * Use when the Industries extension point requires the legacy Open Interface contract.
+ *
+ * Key rules:
+ * - Write results into outputMap via putAll(); do NOT return the envelope from invokeMethod
+ * - Return true for success, false for unsupported/failed actions
+ * - Delegate to the same private methods as the Callable (same inputMap, options signature)
+ * - Populate outputMap with the same envelope shape (success, data, errors)
+ *
+ * Replace Industries_XxxOpenInterface and actionOne with the actual class/action names.
+ */
+global with sharing class Industries_XxxOpenInterface implements omnistudio.VlocityOpenInterface2 {
+
+    global Boolean invokeMethod(String methodName, Map<String, Object> inputMap,
+                                Map<String, Object> outputMap, Map<String, Object> options) {
+        switch on methodName {
+            when 'actionOne' {
+                Map<String, Object> result = actionOne(inputMap, options);
+                outputMap.putAll(result);
+                return true;
+            }
+            when else {
+                outputMap.put('success', false);
+                outputMap.put('errors', new List<Map<String, Object>>{
+                    new Map<String, Object>{
+                        'code'    => 'UNSUPPORTED_ACTION',
+                        'message' => 'Unsupported action: ' + methodName
+                    }
+                });
+                return false;
+            }
+        }
+    }
+
+    private Map<String, Object> actionOne(Map<String, Object> inputMap, Map<String, Object> options) {
+        // 1. Validate required keys from inputMap
+        // 2. Run business logic (SOQL with WITH USER_MODE, DML with sharing)
+        // 3. Return response envelope (written into outputMap by the caller above)
+        return new Map<String, Object>{
+            'success' => true,
+            'data'    => new Map<String, Object>()
+        };
+    }
+}

package/skills/building-omnistudio-callable-apex/assets/pattern_test_class.cls

@@ -0,0 +1,65 @@
+/**
+ * Test class skeleton for System.Callable implementations.
+ * Covers: positive, negative (missing input), unsupported action, and null-args cases.
+ *
+ * Replace Industries_XxxCallable, Industries_XxxCallableTest, and actionOne
+ * with the actual class/action names. Add @TestSetup data for your specific SObjects.
+ */
+@IsTest
+private class Industries_XxxCallableTest {
+
+    @TestSetup
+    static void setup() {
+        // Insert test SObject records needed by the callable here.
+        // Example:
+        // Account acc = new Account(Name = 'Test Account');
+        // insert acc;
+    }
+
+    @IsTest
+    static void testActionOne_success() {
+        System.Callable svc = new Industries_XxxCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{ 'requiredKey' => 'requiredValue' },
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('actionOne', args);
+
+        Assert.isTrue((Boolean) result.get('success'), 'Expected success=true');
+        Assert.isNotNull(result.get('data'), 'Expected data to be present');
+    }
+
+    @IsTest
+    static void testActionOne_missingInput() {
+        System.Callable svc = new Industries_XxxCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>(),
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('actionOne', args);
+
+        Assert.isFalse((Boolean) result.get('success'), 'Expected success=false for missing input');
+    }
+
+    @IsTest
+    static void testUnsupportedAction() {
+        try {
+            System.Callable svc = new Industries_XxxCallable();
+            svc.call('unknownAction', new Map<String, Object>());
+            Assert.fail('Expected IndustriesCallableException');
+        } catch (IndustriesCallableException e) {
+            Assert.isTrue(e.getMessage().contains('Unsupported action'),
+                'Expected unsupported action message');
+        }
+    }
+
+    @IsTest
+    static void testNullArgs() {
+        System.Callable svc = new Industries_XxxCallable();
+        // Null args must be handled defensively; must not throw NullPointerException
+        Map<String, Object> result = (Map<String, Object>) svc.call('actionOne', null);
+        Assert.isNotNull(result, 'Result must not be null even with null args');
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_QuoteByProductCallable/IndustriesCallableException.cls

@@ -0,0 +1,7 @@
+/**
+ * @description Custom exception for Industries callable implementations.
+ *              Thrown when an unsupported or invalid action is requested.
+ * @author      building-omnistudio-callable-apex
+ */
+public class IndustriesCallableException extends Exception {
+}

package/skills/building-omnistudio-callable-apex/examples/Test_QuoteByProductCallable/Industries_QuoteByProductCallable.cls

@@ -0,0 +1,115 @@
+/**
+ * @description Industries callable that finds Quotes on an Account that have at least one
+ *              QuoteLineItem with a specified Product2.ProductCode.
+ *              Integrates with OmniStudio/Industries extension points.
+ * @author      building-omnistudio-callable-apex
+ *
+ * Actions:
+ *   - findQuotesByProductCode: Returns Quotes for an Account with QuoteLineItems matching productCode
+ *
+ * Input (findQuotesByProductCode):
+ *   - accountId (String, required): Id of the Account
+ *   - productCode (String, required): Product2.ProductCode to match on QuoteLineItems
+ *
+ * Output envelope:
+ *   - success (Boolean)
+ *   - data (Map): quotes (List<Map> with Id, Name, QuoteNumber)
+ *   - errors (List<Map>)
+ */
+public with sharing class Industries_QuoteByProductCallable implements System.Callable {
+
+    private static final String ACTION_FIND_QUOTES = 'findQuotesByProductCode';
+
+    /**
+     * @description Dispatches to the appropriate action handler.
+     * @param action Action name (e.g. 'findQuotesByProductCode')
+     * @param args   Input map with accountId and productCode
+     * @return      Response envelope: success, data, errors
+     */
+    public Object call(String action, Map<String, Object> args) {
+        switch on action {
+            when ACTION_FIND_QUOTES {
+                return findQuotesByProductCode(args);
+            }
+            when else {
+                throw new IndustriesCallableException('Unsupported action: ' + action);
+            }
+        }
+    }
+
+    /**
+     * @description Finds all Quotes on an Account that have at least one QuoteLineItem
+     *              with the specified Product2.ProductCode.
+     * @param args  Map with keys: accountId (String), productCode (String)
+     * @return     Response envelope with quotes list or errors
+     */
+    private Map<String, Object> findQuotesByProductCode(Map<String, Object> args) {
+        List<Map<String, Object>> errors = new List<Map<String, Object>>();
+
+        Object accountIdObj = args != null ? args.get('accountId') : null;
+        Object productCodeObj = args != null ? args.get('productCode') : null;
+
+        String accountId = accountIdObj != null ? String.valueOf(accountIdObj).trim() : null;
+        String productCode = productCodeObj != null ? String.valueOf(productCodeObj).trim() : null;
+
+        if (String.isBlank(accountId)) {
+            errors.add(new Map<String, Object>{
+                'code' => 'MISSING_ACCOUNT_ID',
+                'message' => 'accountId is required'
+            });
+        }
+        if (String.isBlank(productCode)) {
+            errors.add(new Map<String, Object>{
+                'code' => 'MISSING_PRODUCT_CODE',
+                'message' => 'productCode is required'
+            });
+        }
+        if (!errors.isEmpty()) {
+            return new Map<String, Object>{
+                'success' => false,
+                'data' => new Map<String, Object>{ 'quotes' => new List<Map<String, Object>>() },
+                'errors' => errors
+            };
+        }
+
+        try {
+            List<Quote> quotes = [
+                SELECT Id, Name, QuoteNumber, OpportunityId
+                FROM Quote
+                WITH USER_MODE
+                WHERE Opportunity.AccountId = :accountId
+                AND Id IN (
+                    SELECT QuoteId
+                    FROM QuoteLineItem
+                    WHERE Product2.ProductCode = :productCode
+                )
+            ];
+
+            List<Map<String, Object>> quoteMaps = new List<Map<String, Object>>();
+            for (Quote q : quotes) {
+                quoteMaps.add(new Map<String, Object>{
+                    'Id' => q.Id,
+                    'Name' => q.Name,
+                    'QuoteNumber' => q.QuoteNumber
+                });
+            }
+
+            return new Map<String, Object>{
+                'success' => true,
+                'data' => new Map<String, Object>{ 'quotes' => quoteMaps },
+                'errors' => new List<Map<String, Object>>()
+            };
+        } catch (Exception e) {
+            return new Map<String, Object>{
+                'success' => false,
+                'data' => new Map<String, Object>{ 'quotes' => new List<Map<String, Object>>() },
+                'errors' => new List<Map<String, Object>>{
+                    new Map<String, Object>{
+                        'code' => 'QUERY_ERROR',
+                        'message' => e.getMessage()
+                    }
+                }
+            };
+        }
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_QuoteByProductCallable/Industries_QuoteByProductCallableTest.cls

@@ -0,0 +1,189 @@
+/**
+ * @description Test class for Industries_QuoteByProductCallable.
+ *              Covers positive, negative, contract, and unsupported action scenarios.
+ * @author      building-omnistudio-callable-apex
+ */
+@IsTest
+private class Industries_QuoteByProductCallableTest {
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TEST DATA SETUP
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    @TestSetup
+    static void setupTestData() {
+        Account acc = new Account(Name = 'Test Account');
+        insert acc;
+
+        Pricebook2 pb = [SELECT Id FROM Pricebook2 WHERE IsStandard = true LIMIT 1];
+
+        Opportunity opp = new Opportunity(
+            Name = 'Test Opp',
+            AccountId = acc.Id,
+            Pricebook2Id = pb.Id,
+            StageName = 'Prospecting',
+            CloseDate = Date.today().addMonths(1)
+        );
+        insert opp;
+
+        Product2 prod = new Product2(
+            Name = 'Test Product',
+            ProductCode = 'PROD-001',
+            IsActive = true
+        );
+        insert prod;
+
+        PricebookEntry pbe = new PricebookEntry(
+            Pricebook2Id = pb.Id,
+            Product2Id = prod.Id,
+            UnitPrice = 100,
+            IsActive = true
+        );
+        insert pbe;
+
+        Quote q = new Quote(
+            Name = 'Test Quote',
+            OpportunityId = opp.Id,
+            Pricebook2Id = pb.Id
+        );
+        insert q;
+
+        QuoteLineItem qli = new QuoteLineItem(
+            QuoteId = q.Id,
+            PricebookEntryId = pbe.Id,
+            Quantity = 1,
+            UnitPrice = 100
+        );
+        insert qli;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // POSITIVE TESTS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests findQuotesByProductCode returns Quotes with matching productCode
+     */
+    @IsTest
+    static void testFindQuotesByProductCode_Success() {
+        Account acc = [SELECT Id FROM Account LIMIT 1];
+        System.Callable svc = new Industries_QuoteByProductCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'accountId' => acc.Id,
+            'productCode' => 'PROD-001'
+        };
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('findQuotesByProductCode', args);
+        Test.stopTest();
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        List<Object> quotes = (List<Object>) data.get('quotes');
+        Assert.isNotNull(quotes, 'quotes list should not be null');
+        Assert.areEqual(1, quotes.size(), 'Should return 1 Quote');
+    }
+
+    /**
+     * @description Tests findQuotesByProductCode returns empty list when no match
+     */
+    @IsTest
+    static void testFindQuotesByProductCode_NoMatch_ReturnsEmpty() {
+        Account acc = [SELECT Id FROM Account LIMIT 1];
+        System.Callable svc = new Industries_QuoteByProductCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'accountId' => acc.Id,
+            'productCode' => 'NONEXISTENT'
+        };
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('findQuotesByProductCode', args);
+        Test.stopTest();
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed with empty result');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        List<Object> quotes = (List<Object>) data.get('quotes');
+        Assert.areEqual(0, quotes.size(), 'Should return 0 Quotes');
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONTRACT / INPUT VALIDATION TESTS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests missing accountId returns error envelope
+     */
+    @IsTest
+    static void testFindQuotesByProductCode_MissingAccountId_ReturnsError() {
+        Map<String, Object> args = new Map<String, Object>{
+            'productCode' => 'PROD-001'
+        };
+        System.Callable svc = new Industries_QuoteByProductCallable();
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('findQuotesByProductCode', args);
+        Test.stopTest();
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail');
+        List<Object> errors = (List<Object>) result.get('errors');
+        Assert.isTrue(errors.size() >= 1, 'Should have at least one error');
+    }
+
+    /**
+     * @description Tests missing productCode returns error envelope
+     */
+    @IsTest
+    static void testFindQuotesByProductCode_MissingProductCode_ReturnsError() {
+        Account acc = [SELECT Id FROM Account LIMIT 1];
+        Map<String, Object> args = new Map<String, Object>{
+            'accountId' => acc.Id
+        };
+        System.Callable svc = new Industries_QuoteByProductCallable();
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('findQuotesByProductCode', args);
+        Test.stopTest();
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail');
+        List<Object> errors = (List<Object>) result.get('errors');
+        Assert.isTrue(errors.size() >= 1, 'Should have at least one error');
+    }
+
+    /**
+     * @description Tests null args returns error envelope
+     */
+    @IsTest
+    static void testFindQuotesByProductCode_NullArgs_ReturnsError() {
+        System.Callable svc = new Industries_QuoteByProductCallable();
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('findQuotesByProductCode', null);
+        Test.stopTest();
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail');
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // NEGATIVE TESTS (Unsupported Action)
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests unsupported action throws IndustriesCallableException
+     */
+    @IsTest
+    static void testUnsupportedAction_ThrowsException() {
+        System.Callable svc = new Industries_QuoteByProductCallable();
+
+        Test.startTest();
+        try {
+            svc.call('unknownAction', new Map<String, Object>());
+            Assert.fail('Expected IndustriesCallableException');
+        } catch (IndustriesCallableException e) {
+            Assert.isTrue(
+                e.getMessage().contains('Unsupported action'),
+                'Error message should mention unsupported action: ' + e.getMessage()
+            );
+        }
+        Test.stopTest();
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_QuoteByProductCallable/TRANSCRIPT.md

@@ -0,0 +1,115 @@
+# Reasoning Transcript: Industries Quote-by-Product Callable
+
+This document records the reasoning process and skills used to generate `Industries_QuoteByProductCallable.cls` and `Industries_QuoteByProductCallableTest.cls`.
+
+---
+
+## Task Summary
+
+Create a callable Apex class that finds all Quotes on an Account that have at least one QuoteLineItem with a specified Product2.ProductCode, plus a supporting test class.
+
+---
+
+## Skills Applied
+
+### 1. **building-omnistudio-callable-apex** (Primary)
+
+**Path:** `~/.claude/skills/building-omnistudio-callable-apex/SKILL.md`  
+**Trigger:** Callable implementations, OmniStudio, Vlocity, Industries Apex extensions
+
+**Application:**
+
+- **Phase 1 – Requirements Gathering:**  
+  Entry point: Integration Procedure / OmniScript. Action: `findQuotesByProductCode`.  
+  Inputs: `accountId` (String), `productCode` (String).  
+  Data: Quote, QuoteLineItem, Product2. No side effects (read-only).
+
+- **Phase 2 – Contract Definition:**  
+  Response envelope: `{ success, data: { quotes }, errors }`.  
+  Action dispatch via `switch on action` with typed exception for unsupported actions.
+
+- **Phase 3 – Implementation Pattern:**  
+  - `call()` kept thin; logic delegated to `findQuotesByProductCode(args)`  
+  - Input validation for `accountId` and `productCode` (blank checks)  
+  - `with sharing` on the callable class  
+  - SOQL with `WITH USER_MODE` for CRUD/FLS  
+  - No SOQL/DML in loops  
+  - Consistent envelope shape
+
+- **Phase 4 – Testing:**  
+  Positive, negative, contract, and unsupported-action tests per skill requirements.
+
+- **Exception Class:**  
+  `IndustriesCallableException` used per skill pattern for unsupported actions.
+
+---
+
+### 2. **generating-apex** (Reference)
+
+**Path:** `~/.claude/skills/generating-apex/SKILL.md`  
+**Trigger:** Apex classes, code quality
+
+**Application:**
+
+- ApexDoc on the class and action method  
+- Naming: `Industries_QuoteByProductCallable` (callable pattern)  
+- Null-safe input handling  
+- Clear separation of concerns
+
+---
+
+### 3. **running-apex-tests** (Reference)
+
+**Path:** `~/.claude/skills/running-apex-tests/SKILL.md`  
+**Trigger:** Apex tests
+
+**Application:**
+
+- `@TestSetup` for shared data (Account, Opportunity, Product2, PricebookEntry, Quote, QuoteLineItem)  
+- Positive: success case and empty-result case  
+- Contract: missing `accountId`, missing `productCode`, null args  
+- Negative: unsupported action throws `IndustriesCallableException`  
+- GIVEN/WHEN/THEN comments (adapted from basic-test template)
+
+---
+
+### 4. **querying-soql / handling-sf-data** (Reference)
+
+**Paths:** `skills/handling-sf-data/assets/soql/`, `skills/generating-mermaid-diagrams/assets/datamodel/`  
+**Trigger:** SOQL and data model
+
+**Application:**
+
+- Quote–Opportunity–Account: `Quote.Opportunity.AccountId`  
+- QuoteLineItem–Product2: `QuoteLineItem.Product2.ProductCode`  
+- Subquery: `Id IN (SELECT QuoteId FROM QuoteLineItem WHERE Product2.ProductCode = :productCode)`  
+- Confirmation that Product2.ProductCode is queryable from QuoteLineItem
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Response envelope** | Aligns with Industries pattern: `success`, `data`, `errors` for consistent handling by Integration Procedures |
+| **Error envelope for validation** | Return structured errors instead of throwing; callers can handle without try/catch |
+| **Exception for unsupported action** | Follows skill pattern; `IndustriesCallableException` makes misuse explicit |
+| **`IndustriesCallableException` in separate class** | Reusable across callable classes, matches skill examples |
+| **`WITH USER_MODE` on SOQL** | Enforces CRUD/FLS; requires API 59+ |
+| **Quote ↔ Account path** | Standard model: `Quote.Opportunity.AccountId` (no direct Quote → Account) |
+| **Product code on Product2** | Standard `Product2.ProductCode` via `QuoteLineItem.Product2` relationship |
+
+---
+
+## Artifacts Produced
+
+1. **IndustriesCallableException.cls** – Custom exception for unsupported actions  
+2. **Industries_QuoteByProductCallable.cls** – Callable implementation  
+3. **Industries_QuoteByProductCallableTest.cls** – Test class (6 methods)  
+4. **TRANSCRIPT.md** – This reasoning transcript  
+
+---
+
+## Deployment Notes
+
+Copy the `.cls` files into your Salesforce project under `force-app/main/default/classes/` and add the corresponding `-meta.xml` files with `apiVersion` 59.0 or higher (for `WITH USER_MODE`). If your org uses an older API, remove `WITH USER_MODE` from the SOQL query.

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterface2Conversion/IndustriesCallableException.cls

@@ -0,0 +1,7 @@
+/**
+ * @description Custom exception for Industries callable implementations.
+ *              Thrown when an unsupported or invalid action is requested.
+ * @author      building-omnistudio-callable-apex
+ */
+public class IndustriesCallableException extends Exception {
+}