@salesforce/afv-skills 1.1.0 → 1.2.0

package/skills/salesforce-fragment/SKILL.md

@@ -16,7 +16,7 @@ Use this skill when you need to:
 # Fragment Generation Guide
 
 ## 📋 Overview
-Fragments are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating and editing fragments. 
+Fragments are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating and editing fragments.
 
 ## 🎯 Purpose
 Fragments render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc
@@ -24,19 +24,94 @@ Fragments render data in a structured and unified way across various Salesforce
 ## ⚙️ Composition
 A fragment is a UEM (Unified Experience Model) tree of blocks and regions. The fragment you return must follow the Typescript interfaces below:
 
-- **Block definition**: Follow `{namespace}}/{{blockName}` convention and use the same value as the block's definition when it appears in a fragment.
-
 ```ts
 interface BlockType {
-  type: 'block'
-  definition: string  // {namespace}/{blockName}, e.g. "bcx/heading"
-  attributes?: Record<string, any>
-  children?: (BlockType | RegionType)[]
+    type: 'block'
+    definition: string  // {namespace}/{blockName}
+    attributes?: Record<string, any>
+    children?: (BlockType | RegionType)[]
 }
 
 interface RegionType {
-  type: 'region'
-  name: string
-  children: BlockType[]
+    type: 'region'
+    name: string
+    children: BlockType[]
 }
 ```
+
+---
+
+## 🔧 Available Metadata Actions
+
+### When to Use Each Action
+
+#### discoverUiComponents
+
+**When:** You want to see what block components are available for fragments.
+
+**Purpose:** Discover the palette of available blocks that can be used in fragment composition.
+
+**Input Parameters:**
+- `pageType` (required): "FRAGMENT"
+- `pageContext` (optional): JSON object - not required for FRAGMENT type
+- `searchQuery` (optional): String to filter components by name or description
+
+**Returns:** List of components with:
+- `definition`: Fully qualified name (e.g., "namespace/definiton")
+- `description`: Component description
+- `label`: Human-readable label
+- `attributes`: Optional attribute metadata
+
+**Use for:** Finding available blocks before building your fragment structure.
+
+#### getUiComponentSchemas
+
+**When:** You know which components you want but need to understand their properties and attributes.
+
+**Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.
+
+**Input Parameters:**
+- `pageType` (required): "FRAGMENT"
+- `pageContext` (optional): JSON object - not required for FRAGMENT type
+- `componentDefinitions` (required): List of fully qualified names (e.g., ["namespace/definition"])
+- `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance
+
+**Returns:**
+- `componentSchemas`: List of results (supports partial failures)
+- **Success entries**: Contains JSON schema with property definitions, types, constraints
+- **Failure entries**: Contains error message explaining why schema couldn't be retrieved
+- `$defs`: Schema definitions and references (if schema transformation applied)
+
+**Use for:** Understanding how to configure component attributes before adding blocks to your fragment.
+
+**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
+
+---
+
+## 💡 Typical Workflow
+
+1. **Discover Available Blocks**
+- Use `discoverUiComponents` to explore what blocks are available
+- Optional: Use `searchQuery` to filter by keywords (e.g., "text", "button", "image")
+
+2. **Select Components**
+- Choose blocks that fit your fragment requirements
+- Note their fully qualified definitions (e.g., "namespace/definition")
+
+3. **Get Component Schemas**
+- Use `getUiComponentSchemas` with the selected component definitions
+- Review the JSON schemas to understand required and optional attributes
+
+4. **Build Fragment**
+- Construct your fragment using the UEM tree structure
+- Configure block attributes according to the schemas
+- Use the TypeScript interfaces defined above
+
+---
+
+## ⚠️ Important Notes
+
+- Block definitions always follow the `{namespace}/{blockName}` convention
+- Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas`
+- The FRAGMENT page type doesn't require additional `pageContext` parameters
+- Schemas include both required and optional attributes - review carefully to ensure valid configuration

package/skills/salesforce-lightning-app-build/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: salesforce-lightning-app-build
-description: Use this skill to build and orchestrate complete Salesforce Lightning Applications (LEX Apps), custom projects, or end-to-end business solutions from a natural language scenario. Triggers when a user requests a "custom app", a "business solution", or describes any scenario requiring multiple interconnected Salesforce components to be built together into a complete Lightning Experience (LEX) Application. Orchestrates the sequenced creation of Custom Objects, Relationships, Fields, Lightning Record Pages, Custom Tabs, Custom Applications, Permission Sets, and OPTIONALLY Flows and Validation Rules.
+description: Build complete Salesforce Lightning Experience applications from natural language descriptions. Use this skill when a user requests a "complete app", "Lightning app", "business solution", "management system", or describes a scenario requiring multiple interconnected Salesforce components (objects, fields, pages, tabs, security). Orchestrates all required metadata types in proper dependency order to produce a deployable application.
 metadata:
   category: orchestration
-  related-skills: salesforce-custom-object, salesforce-custom-field, salesforce-custom-tab, salesforce-flexipage, salesforce-custom-application, salesforce-flow, salesforce-validation-rule, salesforce-list-view
+  version: "1.0"
+  related-skills: salesforce-custom-object, salesforce-custom-field, salesforce-custom-tab, salesforce-flexipage, salesforce-custom-application, salesforce-flow, salesforce-validation-rule, salesforce-list-view, generate-permission-set
 ---
 
 # Salesforce Lightning Application Build
 
 ## Overview
 
-Build complete Lightning Experience applications from natural language by orchestrating multiple metadata types in proper dependency order. This skill acts as a "conductor" that invokes specialized metadata skills when available, or generates metadata directly when no skill exists.
+Build a complete, deployable Salesforce Lightning Experience application from a natural language description by orchestrating multiple metadata types in correct dependency order. Invoke specialized metadata skills when available; generate metadata directly when no skill exists.
 
 ## When to Use This Skill
 **Use when:**
@@ -34,7 +35,6 @@ Build complete Lightning Experience applications from natural language by orches
 - Troubleshooting or debugging existing metadata
 - Building Salesforce Classic apps (not Lightning Experience)
 - User asks for just one object, or just one page, or just one permission set (without others)
----
 
 ## Metadata Type Registry
 
@@ -50,7 +50,7 @@ This table shows which metadata types are commonly needed for LEX apps and their
 | **List View** | ✅ YES | `salesforce-list-view` | MUST use skill |
 | **Validation Rule** | ✅ YES | `salesforce-validation-rule` | MUST use skill (if requested) |
 | **Flow** | ✅ YES | `salesforce-flow` | MUST use skill (if requested) |
-| **Permission Set** | ❌ NO | - | Generate directly using Metadata API knowledge |
+| **Permission Set** | ✅ YES | `generate-permission-set` | MUST use skill |
 
 ### Skill Usage Rules
 
@@ -115,8 +115,8 @@ Custom Application (depends on: Tabs exist)
 Permission Sets (depends on: Objects, Fields, Tabs, App exist)
 ```
 
-**Fallback generation (no skill available):**
-1. Generate Permission Set XML directly with access to:
+**Skills to invoke:**
+1. `generate-permission-set` for each permission set with access to:
    - Objects (Read, Create, Edit, Delete)
    - Fields (Read, Edit)
    - Tabs (Visible)
@@ -170,7 +170,7 @@ METADATA SKILLS TO INVOKE:
 - salesforce-custom-tab (x N)
 - salesforce-flexipage (x N)
 - salesforce-custom-application (x 1)
-- [fallback] Permission Set XML generation (x N)
+- generate-permission-set (x N)
 
 DEPENDENCY ORDER:
 1. Phase 1: Data Model (Objects → Fields)
@@ -198,7 +198,99 @@ Execute in strict dependency order. For each metadata component:
 - For Custom Tab → Invoke `salesforce-custom-tab`
 - For FlexiPage → Invoke `salesforce-flexipage`
 - For Custom Application → Invoke `salesforce-custom-application`
-- For Permission Sets (no skill) → Generate XML directly
+- For Permission Set → Invoke `generate-permission-set`
+
+### STEP 3: Final Artifact Assembly
+
+After all phases complete, consolidate outputs into deployment-ready structure.
+
+---
+
+## Output
+
+The completed build produces:
+
+1. **Salesforce DX Project Directory** containing all generated metadata
+   - Organized by standard SFDX structure: `force-app/main/default/`
+
+2. **Metadata Files** - One file per component, organized by type:
+   ```
+   force-app/main/default/
+   ├── objects/              # Custom Objects (.object-meta.xml)
+   ├── fields/               # Custom Fields (.field-meta.xml)
+   ├── tabs/                 # Custom Tabs (.tab-meta.xml)
+   ├── flexipages/           # Lightning Pages (.flexipage-meta.xml)
+   ├── applications/         # Custom Applications (.app-meta.xml)
+   ├── permissionsets/       # Permission Sets (.permissionset-meta.xml)
+   ├── flows/                # Flows (.flow-meta.xml) - if applicable
+   └── objects/.../validationRules/  # Validation Rules (.validationRule-meta.xml) - if applicable
+   ```
+
+3. **Deployment Manifest** (`package.xml`)
+   - Lists all components with proper API version
+   - Organized by metadata type in dependency order
+   - Ready for Salesforce CLI deployment or Metadata API deployment
+
+4. **Build Summary Report** - A markdown file listing:
+   - Every component created
+   - Component type and API name
+   - File path location
+   - Dependency relationships
+   - Any warnings or recommendations
+
+**Example Summary Structure:**
+```
+📦 Lightning App Build Complete: Project Management App
+
+METADATA GENERATED:
+✅ 3 Custom Objects
+   - Project__c → force-app/main/default/objects/Project__c/Project__c.object-meta.xml
+   - Task__c → force-app/main/default/objects/Task__c/Task__c.object-meta.xml
+   - Resource__c → force-app/main/default/objects/Resource__c/Resource__c.object-meta.xml
+
+✅ 12 Custom Fields
+   - Project__c.Name → force-app/main/default/objects/Project__c/fields/Name.field-meta.xml
+   - Project__c.Status__c → force-app/main/default/objects/Project__c/fields/Status__c.field-meta.xml
+   [... etc ...]
+
+✅ 3 Custom Tabs
+   - Project__c → force-app/main/default/tabs/Project__c.tab-meta.xml
+   [... etc ...]
+
+✅ 3 Lightning Record Pages
+   - Project_Record_Page → force-app/main/default/flexipages/Project_Record_Page.flexipage-meta.xml
+   [... etc ...]
+
+✅ 1 Custom Application
+   - Project_Management → force-app/main/default/applications/Project_Management.app-meta.xml
+
+✅ 2 Permission Sets
+   - Project_Manager → force-app/main/default/permissionsets/Project_Manager.permissionset-meta.xml
+   - Project_User → force-app/main/default/permissionsets/Project_User.permissionset-meta.xml
+
+⚠️  WARNINGS: None
+```
+
+---
+
+## Validation
+
+Before presenting the completed build to the user, verify cross-component integrity:
+
+- [ ] **Object-Tab Coverage**: Every Custom Object has at least one Custom Tab
+- [ ] **Relationship Integrity**: Every Custom Object referenced in a relationship (parent or child) exists in the build
+- [ ] **Field References in Pages**: Every field referenced in a FlexiPage exists on the corresponding object
+- [ ] **Tab References in App**: Every tab referenced in the Custom Application was successfully created
+- [ ] **Permission Set Completeness**: Permission Sets grant access to all generated objects, fields, tabs, and the application
+- [ ] **No Orphaned Components**: No tabs without objects, no pages without corresponding tabs, no app without tabs
+- [ ] **Deployment Manifest Completeness**: `package.xml` includes all generated components in proper dependency order
+
+**Validation Failure Handling:**
+- If validation fails, include failed checks in the Build Summary Report under a `⚠️ VALIDATION WARNINGS` section
+- Do NOT block delivery of the build, but clearly communicate what needs manual review or correction
+- Provide specific remediation steps for each failed validation check
+
+**Note**: Individual component validations (reserved words, name lengths, field types, etc.) are handled by specialized metadata skills and do not need to be re-validated here.
 
 ---
 
@@ -246,7 +338,7 @@ When user doesn't specify details:
 - Enable Search and Reports for user-facing objects
 - Set sharingModel based on relationships
 
-### 5. Validate Before Building
+### 4. Validate Before Building
 Check for:
 - Reserved words in API names
 - Relationship limits (max 2 M-D per object)

package/skills/apex-class/SKILL.md

@@ -1,253 +0,0 @@
----
-name: apex-class
-description: Generate production-ready Apex classes for Salesforce following enterprise best practices. Covers service classes, selectors, domain classes, batch/queueable/schedulable, DTOs, utilities, interfaces, abstract classes, and custom exceptions. Not for triggers or unit tests. Use this skill whenever the user asks to create, write, build, generate, or scaffold any Apex class — including when they describe functionality that would require an Apex class without explicitly saying "Apex class." Trigger on phrases like "build a service for," "create a handler," "I need a class that," "write Apex to," "scaffold a batch job," "create a queueable," or any request involving Salesforce server-side logic. Also use when the user asks to refactor, improve, or restructure existing Apex classes. Even if the request is vague like "I need something that processes Opportunities nightly," use this skill if the solution would involve an Apex class.
----
-
-# Apex Class
-
-Generate well-structured, production-ready Apex classes for Salesforce development.
-
-## Scope
-
-**Generates:**
-- Service classes (business logic layer)
-- Selector / query classes (SOQL encapsulation)
-- Domain classes (SObject-specific logic)
-- Batch Apex classes (`Database.Batchable`)
-- Queueable Apex classes (`Queueable`, optionally `Finalizer`)
-- Schedulable Apex classes (`Schedulable`)
-- DTO / wrapper / request-response classes
-- Utility / helper classes
-- Custom exception classes
-- Interfaces and abstract classes
-
-**Does NOT generate:**
-- Triggers (use a trigger framework skill)
-- Unit tests (use a test writer skill)
-- Aura controllers
-- LWC JavaScript controllers
-
----
-
-## Gathering Requirements
-
-Before generating code, gather these inputs from the user (ask if not provided):
-
-1. **Class type** — Service, Selector, Batch, Queueable, Schedulable, Domain, DTO, Utility, Interface, Abstract, Exception
-2. **Class name** — or enough context to derive a meaningful name
-3. **SObject(s) involved** — if applicable
-4. **Business requirements** — plain-language description of what the class should do
-5. **Optional preferences:**
-   - Sharing model (`with sharing`, `without sharing`, `inherited sharing`)
-   - Access modifier (`public` or `global`)
-   - API version (default: `62.0`)
-   - Whether to include ApexDoc comments (default: yes)
-
-If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.
-
----
-
-## Code Standards — ALWAYS Follow These
-
-### Separation of Concerns
-- **Service classes** contain business logic. They call Selectors for data and may call Domain classes for SObject-specific behavior.
-- **Selector classes** encapsulate all SOQL queries. Services never contain inline SOQL.
-- **Domain classes** encapsulate SObject-specific logic (field defaults, validation, transformation).
-- Keep classes focused on a single responsibility.
-
-### Bulkification
-- All methods must operate on collections (`List`, `Set`, `Map`) by default.
-- Never accept a single SObject when a `List<SObject>` is appropriate.
-- Provide convenience overloads for single-record callers only when it makes the API cleaner, and have them delegate to the bulk method.
-
-### Governor Limit Safety
-- **No SOQL or DML inside loops.** Ever.
-- Collect IDs/records first, query/DML once outside the loop.
-- Use `Limits` class checks in batch/bulk operations where appropriate.
-- Prefer `Database.insert(records, false)` with error handling in batch contexts.
-
-### Sharing Model
-- Default to `with sharing` unless the user specifies otherwise.
-- If `without sharing` or `inherited sharing` is used, add an ApexDoc `@description` comment explaining WHY.
-
-### Naming Conventions
-
-| Class Type   | Pattern                        | Example                        |
-|-------------|-------------------------------|-------------------------------|
-| Service      | `{SObject}Service`            | `AccountService`              |
-| Selector     | `{SObject}Selector`           | `AccountSelector`             |
-| Domain       | `{SObject}Domain`             | `OpportunityDomain`           |
-| Batch        | `{Descriptive}Batch`          | `AccountDeduplicationBatch`   |
-| Queueable    | `{Descriptive}Queueable`      | `ExternalSyncQueueable`       |
-| Schedulable  | `{Descriptive}Schedulable`    | `DailyCleanupSchedulable`     |
-| DTO          | `{Descriptive}DTO`            | `AccountMergeRequestDTO`      |
-| Wrapper      | `{Descriptive}Wrapper`        | `OpportunityLineWrapper`      |
-| Utility      | `{Descriptive}Util`           | `StringUtil`, `DateUtil`      |
-| Interface    | `I{Descriptive}`              | `INotificationService`        |
-| Abstract     | `Abstract{Descriptive}`       | `AbstractIntegrationService`  |
-| Exception    | `{Descriptive}Exception`      | `AccountServiceException`     |
-
-### ApexDoc Comments
-Include ApexDoc on every `public` and `global` method and on the class itself:
-
-```apex
-/**
- * @description Brief description of what the class does
- * @author Generated by Apex Class Writer Skill
- */
-```
-
-```apex
-/**
- * @description Brief description of what the method does
- * @param paramName Description of the parameter
- * @return Description of the return value
- * @example
- * List<Account> results = AccountService.deduplicateAccounts(accountIds);
- */
-```
-
-### Null Safety
-- Use guard clauses at the top of methods for null/empty inputs.
-- Use safe navigation (`?.`) where appropriate.
-- Return empty collections rather than `null`.
-
-### Constants
-- No magic strings or numbers in logic.
-- Use `private static final` constants or a dedicated constants class.
-- Use `Label.` custom labels for user-facing strings when appropriate.
-
-### Custom Exceptions
-- Each service class should define or reference a corresponding custom exception.
-- Inner exception classes are preferred for simple cases: `public class AccountServiceException extends Exception {}`
-- Include meaningful error messages with context.
-
-### Error Handling
-- Catch specific exceptions, not generic `Exception` unless re-throwing.
-- Log errors meaningfully (assume a logging utility exists or stub one).
-- In batch contexts, use `Database.SaveResult` / `Database.UpsertResult` with partial success.
-
----
-
-## Output Format
-
-For every class, produce TWO files:
-
-1. **`{ClassName}.cls`** — The Apex class source code
-2. **`{ClassName}.cls-meta.xml`** — The metadata file
-
-### Meta XML Template
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>{API_VERSION}</apiVersion>
-    <status>Active</status>
-</ApexClass>
-```
-
-Default `apiVersion` is `62.0` unless the user specifies otherwise.
-
----
-
-## Class Type–Specific Instructions
-
-### Service Classes
-- Read and follow: `templates/service.cls`
-- Stateless — no instance variables holding mutable state
-- All public methods should be `static` unless there's a compelling reason for instance methods
-- Delegate queries to a Selector class
-- Wrap business logic errors in a custom exception
-
-### Selector Classes
-- Read and follow: `templates/selector.cls`
-- One Selector per SObject (or per logical query domain)
-- Return `List<SObject>` or `Map<Id, SObject>`
-- Accept filter criteria as method parameters, not hardcoded
-- Include a private method that returns the base field list to keep DRY
-
-### Domain Classes
-- Read and follow: `templates/domain.cls`
-- Encapsulate field-level defaults, derivations, and validations
-- Operate on `List<SObject>` — designed to be called from triggers or services
-- No SOQL or DML — only in-memory SObject manipulation
-
-### Batch Classes
-- Read and follow: `templates/batch.cls`
-- Implement `Database.Batchable<SObject>` and optionally `Database.Stateful`
-- Use `Database.QueryLocator` in `start()` for large datasets
-- Handle partial failures in `execute()` using `Database.SaveResult`
-- Implement meaningful `finish()` — at minimum, log completion
-
-### Queueable Classes
-- Read and follow: `templates/queueable.cls`
-- Implement `Queueable` and optionally `Database.AllowsCallouts`
-- Accept data through the constructor — queueables are stateful
-- For chaining, include guard logic to prevent infinite chains
-- Optionally implement `Finalizer` for error recovery
-
-### Schedulable Classes
-- Read and follow: `templates/schedulable.cls`
-- Implement `Schedulable`
-- Keep `execute()` lightweight — delegate to a Batch or Queueable
-- Include a static method that returns a CRON expression for convenience
-- Document the expected schedule in ApexDoc
-
-### DTO / Wrapper Classes
-- Read and follow: `templates/dto.cls`
-- Use `public` properties — no getters/setters unless validation is needed
-- Include a no-arg constructor and optionally a parameterized constructor
-- Implement `Comparable` if sorting is needed
-- Keep them serialization-friendly (no transient state unless intentional)
-
-### Utility Classes
-- Read and follow: `templates/utility.cls`
-- All methods `public static`
-- Class should be `public with sharing` with a `private` constructor to prevent instantiation
-- Group related utilities (e.g., `StringUtil`, `DateUtil`, `CollectionUtil`)
-- Every method must be side-effect-free (no DML, no SOQL)
-
-### Interfaces
-- Read and follow: `templates/interface.cls`
-- Define the contract clearly with ApexDoc on every method signature
-- Use meaningful names that describe the capability: `INotificationService`, `IRetryable`
-
-### Abstract Classes
-- Read and follow: `templates/abstract.cls`
-- Provide default implementations for common behavior
-- Mark extension points as `protected virtual` or `protected abstract`
-- Include a concrete example in the ApexDoc showing how to extend
-
-### Custom Exceptions
-- Read and follow: `templates/exception.cls`
-- Extend `Exception`
-- Keep them simple — Apex exceptions don't support custom constructors well
-- Name them descriptively: `AccountServiceException`, `IntegrationTimeoutException`
-
----
-
-## Generation Workflow
-
-1. Determine the class type from the user's request
-2. Read the corresponding template from `templates/`
-3. Read relevant examples from `examples/` if the class type has one
-4. Apply the user's requirements to the template pattern
-5. Generate the `.cls` file with full ApexDoc
-6. Generate the `.cls-meta.xml` file
-7. Present both files to the user
-8. Include a brief note on design decisions if any non-obvious choices were made
-
----
-
-## Anti-Patterns to Avoid
-
-- ❌ SOQL or DML inside loops
-- ❌ Hardcoded IDs or record type names (use `Schema.SObjectType` or Custom Metadata)
-- ❌ God classes that mix query + logic + DML
-- ❌ `public` fields on service classes
-- ❌ Returning `null` from methods that should return collections
-- ❌ Generic `catch (Exception e)` without re-throwing or meaningful handling
-- ❌ Business logic in Batch `start()` methods
-- ❌ Tight coupling between classes — use interfaces for extensibility
-- ❌ Magic strings or numbers
-- ❌ Methods longer than ~40 lines — break them into private helpers

package/skills/apex-class/examples/AccountDeduplicationBatch.cls

@@ -1,148 +0,0 @@
-/**
- * @description Batch Apex class for identifying and flagging duplicate Account records.
- *              Compares Accounts by Name and BillingPostalCode to find potential duplicates.
- *              Flags duplicates by setting the Is_Potential_Duplicate__c checkbox.
- *              Implements Database.Stateful to track results across batch chunks.
- * @author Generated by Apex Class Writer Skill
- *
- * @example
- * // Run with default batch size (200)
- * Id jobId = AccountDeduplicationBatch.run();
- *
- * // Run with smaller batch size for complex processing
- * Database.executeBatch(new AccountDeduplicationBatch(), 50);
- */
-public with sharing class AccountDeduplicationBatch implements Database.Batchable<SObject>, Database.Stateful {
-
-    // ─── Constants ───────────────────────────────────────────────────────
-    private static final Integer DEFAULT_BATCH_SIZE = 200;
-
-    // ─── Stateful Tracking ───────────────────────────────────────────────
-    private Integer totalScanned = 0;
-    private Integer duplicatesFound = 0;
-    private Integer totalErrors = 0;
-    private List<String> errorMessages = new List<String>();
-
-    // ─── Batchable Interface ─────────────────────────────────────────────
-
-    /**
-     * @description Queries all active Accounts that haven't already been flagged
-     * @param bc The batch context
-     * @return QueryLocator scoped to unflagged active Accounts
-     */
-    public Database.QueryLocator start(Database.BatchableContext bc) {
-        return Database.getQueryLocator([
-            SELECT Id, Name, BillingPostalCode, Is_Potential_Duplicate__c
-            FROM Account
-            WHERE IsDeleted = FALSE
-            AND Is_Potential_Duplicate__c = FALSE
-            ORDER BY Name ASC
-        ]);
-    }
-
-    /**
-     * @description Processes each batch by building a duplicate key and checking for matches.
-     *              Uses a composite key of normalized Name + BillingPostalCode.
-     * @param bc The batch context
-     * @param scope List of Account records in the current batch
-     */
-    public void execute(Database.BatchableContext bc, List<Account> scope) {
-        totalScanned += scope.size();
-
-        // Build duplicate keys for this batch
-        Map<String, List<Account>> dupeKeyMap = new Map<String, List<Account>>();
-        for (Account acct : scope) {
-            String key = buildDuplicateKey(acct);
-            if (String.isNotBlank(key)) {
-                if (!dupeKeyMap.containsKey(key)) {
-                    dupeKeyMap.put(key, new List<Account>());
-                }
-                dupeKeyMap.get(key).add(acct);
-            }
-        }
-
-        // Flag records that share a key with another record
-        List<Account> toUpdate = new List<Account>();
-        for (String key : dupeKeyMap.keySet()) {
-            List<Account> group = dupeKeyMap.get(key);
-            if (group.size() > 1) {
-                for (Account acct : group) {
-                    toUpdate.add(new Account(
-                        Id = acct.Id,
-                        Is_Potential_Duplicate__c = true
-                    ));
-                }
-            }
-        }
-
-        if (!toUpdate.isEmpty()) {
-            List<Database.SaveResult> results = Database.update(toUpdate, false);
-            processResults(results);
-        }
-    }
-
-    /**
-     * @description Logs a summary of the deduplication batch run
-     * @param bc The batch context
-     */
-    public void finish(Database.BatchableContext bc) {
-        String summary = String.format(
-            'AccountDeduplicationBatch completed. Scanned: {0}, Duplicates flagged: {1}, Errors: {2}',
-            new List<Object>{ totalScanned, duplicatesFound, totalErrors }
-        );
-
-        System.debug(LoggingLevel.INFO, summary);
-
-        if (!errorMessages.isEmpty()) {
-            System.debug(LoggingLevel.ERROR, 'Error details:\n' + String.join(errorMessages, '\n'));
-        }
-    }
-
-    // ─── Private Helpers ─────────────────────────────────────────────────
-
-    /**
-     * @description Builds a normalized composite key for duplicate detection
-     * @param acct The Account record
-     * @return Normalized key string, or null if insufficient data
-     */
-    private String buildDuplicateKey(Account acct) {
-        if (String.isBlank(acct.Name)) {
-            return null;
-        }
-
-        String normalizedName = acct.Name.trim().toUpperCase().replaceAll('\\s+', ' ');
-        String postalCode = (acct.BillingPostalCode ?? '').trim().toUpperCase();
-
-        return normalizedName + '|' + postalCode;
-    }
-
-    /**
-     * @description Processes DML results, tracking successes and failures
-     * @param results List of Database.SaveResult from update operation
-     */
-    private void processResults(List<Database.SaveResult> results) {
-        for (Database.SaveResult sr : results) {
-            if (sr.isSuccess()) {
-                duplicatesFound++;
-            } else {
-                totalErrors++;
-                for (Database.Error err : sr.getErrors()) {
-                    errorMessages.add(
-                        'Record ' + sr.getId() + ': ' +
-                        err.getStatusCode() + ' - ' + err.getMessage()
-                    );
-                }
-            }
-        }
-    }
-
-    // ─── Static Helpers ──────────────────────────────────────────────────
-
-    /**
-     * @description Convenience method to execute with default batch size
-     * @return The batch job Id
-     */
-    public static Id run() {
-        return Database.executeBatch(new AccountDeduplicationBatch(), DEFAULT_BATCH_SIZE);
-    }
-}