scc-universal 1.1.0

package/skills/_reference/APEX_CURSOR.md

@@ -0,0 +1,159 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_class_System_Cursor.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+<!-- WARNING: Web fetch of canonical URL failed (JS-rendered page). Facts extracted from SCC skill sf-apex-cursor. Verify against official docs before relying on limits. -->
+
+# Apex Cursor Reference
+
+## Classes
+
+| Class | Purpose | AuraEnabled |
+|-------|---------|-------------|
+| `Database.Cursor` | Server-side pointer for paginated SOQL iteration | No (use PaginationCursor) |
+| `Database.PaginationCursor` | UI-oriented cursor for LWC / `@AuraEnabled` methods | Yes |
+
+## Database.Cursor Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `Database.getCursor(String soql)` | `Database.Cursor` | Open a new cursor from a SOQL query |
+| `Database.getCursor(String cursorId)` | `Database.Cursor` | Re-open a serialized cursor in a new transaction |
+| `cursor.fetch(Integer offset, Integer pageSize)` | `List<SObject>` | Fetch a page of records starting at offset |
+| `cursor.getNumRecords()` | `Integer` | Total row count the cursor can return |
+| `cursor.getId()` | `String` | Serialize cursor ID for cross-transaction use |
+| `cursor.close()` | `void` | Release server-side resources |
+
+## Database.PaginationCursor Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `Database.getPaginationCursor(String soql)` | `Database.PaginationCursor` | Open a new pagination cursor |
+| `Database.getPaginationCursor(String cursorId)` | `Database.PaginationCursor` | Resume from a client-provided cursor ID |
+| `cursor.fetch(Integer pageSize)` | `List<SObject>` | Fetch next page (auto-advances position) |
+| `cursor.hasMore()` | `Boolean` | Whether more pages remain |
+| `cursor.getNumRecords()` | `Integer` | Total row count |
+| `cursor.getId()` | `String` | Cursor ID safe to return to LWC client |
+
+## Governor Limits
+
+| Constraint | Value |
+|------------|-------|
+| Max records per cursor | 50,000,000 |
+| Cursor lifetime (sync transaction) | 10 minutes |
+| Cursor lifetime (async / Queueable) | 60 minutes |
+| Max page size per `fetch()` call | 2,000 rows |
+| Max open cursors per transaction | 10 |
+
+## Availability
+
+| Detail | Value |
+|--------|-------|
+| GA release | Spring '26 |
+| Minimum API version | 66.0 |
+
+## Exception Types
+
+| Exception | Cause |
+|-----------|-------|
+| `System.CursorException: Cursor has been closed` | Called `fetch()` after `close()` |
+| `System.CursorException: Cursor has expired` | Exceeded 10 min (sync) or 60 min (async) |
+| `System.CursorException: Maximum cursors exceeded` | More than 10 open cursors in one transaction |
+| `System.QueryException: Non-selective query` | WHERE clause not indexed on large table |
+
+## Cursor vs OFFSET vs Batch Apex
+
+| Approach | Max Records | Heap Impact | Best For |
+|----------|-------------|-------------|----------|
+| SOQL `OFFSET` | 2,000 | Full result set in heap | Small UI pagination |
+| Batch Apex (`QueryLocator`) | Unlimited | Per-execute governor reset | Background mass processing |
+| `Cursor` class | 50,000,000 | Per-page only | Large paginated reports, async chaining, LWC infinite scroll |
+
+## Performance Guidance
+
+| Record Count | Recommended Approach |
+|-------------|----------------------|
+| < 200 | Standard SOQL with `LIMIT` |
+| 200 - 2,000 | `OFFSET` pagination |
+| 2,000 - 50,000 | `Cursor` |
+| 50,000+ | `Cursor` + Queueable chaining |
+| Batch processing | `Database.QueryLocator` |
+
+## Key Rules
+
+- Always close cursors in a `finally` block to prevent server-side resource leaks.
+- `Cursor` is read-only; collect IDs separately for DML.
+- Cursor ID is serializable; pass it across Queueable jobs for async chaining.
+- OFFSET forces the DB to skip N rows per request; Cursor maintains a server-side pointer with no scanning overhead.
+
+## Error Recovery Patterns
+
+### try/finally Cursor Cleanup
+
+Always close cursors in `finally` to prevent resource leaks, even on exceptions.
+
+```apex
+Database.Cursor cursor = Database.getCursor('SELECT Id, Name FROM Account');
+try {
+    Integer total = cursor.getNumRecords();
+    for (Integer offset = 0; offset < total; offset += 200) {
+        List<Account> page = (List<Account>) cursor.fetch(offset, 200);
+        // process page...
+    }
+} finally {
+    cursor.close();
+}
+```
+
+### Expired Cursor Recovery
+
+If a cursor expires mid-pagination (10 min sync, 60 min async), catch the exception and re-open from the last known offset.
+
+```apex
+public static void processLargeDataset(String soql) {
+    Database.Cursor cursor = Database.getCursor(soql);
+    Integer offset = 0;
+    try {
+        Integer total = cursor.getNumRecords();
+        while (offset < total) {
+            try {
+                List<SObject> page = cursor.fetch(offset, 2000);
+                processBatch(page);
+                offset += page.size();
+            } catch (System.CursorException e) {
+                if (e.getMessage().contains('expired')) {
+                    cursor = Database.getCursor(soql); // re-open
+                    continue; // retry from same offset
+                }
+                throw e;
+            }
+        }
+    } finally {
+        cursor.close();
+    }
+}
+```
+
+### PaginationCursor — LWC @AuraEnabled Pattern
+
+Return cursor ID to client; handle expiry by issuing a fresh cursor.
+
+```apex
+@AuraEnabled
+public static Map<String, Object> getPage(String cursorId, String soql) {
+    Database.PaginationCursor cursor;
+    try {
+        cursor = (cursorId != null)
+            ? Database.getPaginationCursor(cursorId)
+            : Database.getPaginationCursor(soql);
+    } catch (System.CursorException e) {
+        // Cursor expired — start fresh
+        cursor = Database.getPaginationCursor(soql);
+    }
+    List<SObject> records = cursor.fetch(200);
+    return new Map<String, Object>{
+        'records' => records,
+        'cursorId' => cursor.getId(),
+        'hasMore' => cursor.hasMore(),
+        'totalCount' => cursor.getNumRecords()
+    };
+}
+```

package/skills/_reference/API_VERSIONS.md

@@ -0,0 +1,78 @@
+# Salesforce API Versions — Feature Tracker
+
+> Last verified: 2026-03-31 against Spring '26 (API v66.0)
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_versions.htm>
+>
+> **MAINTENANCE:**
+>
+> 1. When a new release ships: add section at TOP with `Added: YYYY-MM`
+> 2. Remove sections older than 24 months (model knows them by then)
+> 3. Update "Last verified" date
+> 4. Deprecations go in DEPRECATIONS.md (separate file, independent cadence)
+> 5. Releases and deprecations are INDEPENDENT — a new release does NOT deprecate the previous one
+
+## Spring '26 — API v66.0 (Current) `Added: 2026-03`
+
+| Feature | Version | Status | Description |
+|---------|---------|--------|-------------|
+| `Database.Cursor` / `Database.getCursor()` | v66.0 | GA | Paginate up to 50M SOQL rows |
+| `Database.PaginationCursor` | v66.0 | GA | `@AuraEnabled`-compatible cursor for LWC |
+| GraphQL Mutations in LWC | v66.0 | GA | `executeMutation` for create/update/delete |
+| Named Query API | v66.0 | GA | Custom SOQL exposed as REST endpoints |
+| Autonomous Actions | v66.0 | GA | Expose Apex REST / `@AuraEnabled` as Agentforce actions via OpenAPI |
+| SLDS 2.0 | v66.0 | GA | New Lightning Design System |
+| `RunRelevantTests` test level | v66.0 | **Beta** | Smart test selection — do NOT rely on for production |
+| `@testFor` annotation | v66.0 | **Beta** | Map test class to production class (pairs with RunRelevantTests) |
+| LWC Complex Template Expressions | v66.0 | **Beta/Pilot** | Do NOT use in production |
+| Agent Script | v66.0 | **Public Beta** | Deterministic + LLM blocks, no GA date |
+
+## Winter '26 — API v65.0 `Added: 2026-03`
+
+| Feature | Version | Status | Description |
+|---------|---------|--------|-------------|
+| SOAP `login()` removed | v65.0 | Breaking | Use OAuth 2.0 instead |
+| Abstract/override access modifiers | v65.0 | Breaking | Must add explicit public/protected/global |
+| GraphQL optional fields (`lightning/graphql`) | v65.0 | GA | Resilient queries with optional field support |
+| Unified Logic Testing | v65.0 | GA | Apex + Flow tests in single command |
+| External Services binary files | v65.0 | GA | Upload/download up to 16 MB via OpenAPI 3.0 |
+
+## Summer '25 — API v64.0 `Added: 2026-03`
+
+| Feature | Version | Status | Description |
+|---------|---------|--------|-------------|
+| API v21–30 retired | v64.0 | Breaking | Minimum supported version: v31.0 |
+| OpenAPI support for REST API | v64.0 | GA | Client SDK generation from OpenAPI spec |
+| Data Cloud Enrichment APIs | v64.0 | GA | Enriched related lists on Cases, Contracts |
+| Streaming API disconnect handling | v64.0 | GA | `/meta/disconnect` channel for connection status |
+
+## Stable Version-Gated Features (Older — retained for reference)
+
+| Feature | Min API Version | Release | Notes |
+|---|---|---|---|
+| Null coalescing operator (`??`) | v60.0 | Spring '24 | `value ?? defaultValue` |
+| `Database.queryWithBinds()` | v57.0 | Spring '23 | Safe dynamic SOQL with bind maps |
+| `WITH USER_MODE` / `AccessLevel.USER_MODE` | v57.0 | Spring '23 GA | CRUD + FLS enforcement (Beta v55.0 Summer '22) |
+| `Assert` class (`Assert.areEqual`, etc.) | v56.0 | Winter '23 | Replaces `System.assertEquals` |
+| External Credentials | v54.0 | Spring '22 | Secure OAuth/JWT/API key storage |
+| Null-safe navigation (`?.`) | v50.0 | Winter '21 | `obj?.field?.subfield` |
+| `WITH SECURITY_ENFORCED` | v48.0 | Spring '20 | CRUD + FLS for reads (older pattern) |
+| `Security.stripInaccessible()` | v48.0 | Spring '20 | Bulk FLS enforcement |
+
+## Version Selection Guide
+
+| Scenario | Recommendation |
+|---|---|
+| New project | Use v66.0 (Spring '26 GA) |
+| Existing project | Match `sfdx-project.json` `sourceApiVersion` |
+| Managed package | Pin to minimum supported version for subscriber compatibility |
+| `RunRelevantTests` adoption | Requires `sourceApiVersion` >= v66.0 (Beta — not for production) |
+
+## sfdx-project.json Version Setting
+
+```json
+{
+  "sourceApiVersion": "66.0"
+}
+```
+
+This controls the API version used for `sf project deploy` and `sf project retrieve`. Individual class `-meta.xml` files can override with their own `<apiVersion>` value.

package/skills/_reference/APPROVAL_PROCESSES.md

@@ -0,0 +1,105 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_process_classes.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+<!-- WARNING: Web fetch of canonical URL failed (JS-rendered page). Facts extracted from SCC skill sf-approval-processes. Verify against official docs before relying on class signatures. -->
+
+# Approval Processes Reference
+
+## Apex Approval Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Approval.ProcessSubmitRequest` | Submit a record for approval |
+| `Approval.ProcessWorkitemRequest` | Approve, reject, or remove a pending work item |
+| `Approval.ProcessResult` | Result returned by `Approval.process()` |
+
+## Approval.ProcessSubmitRequest Methods
+
+| Method | Parameter | Description |
+|--------|-----------|-------------|
+| `setObjectId(Id)` | Record ID | Record to submit for approval |
+| `setSubmitterId(Id)` | User ID | User submitting the request |
+| `setComments(String)` | Text | Submission comments |
+| `setSkipEntryCriteria(Boolean)` | true/false | Bypass entry criteria check |
+| `setProcessDefinitionNameOrId(String)` | Name or ID | Target a specific approval process |
+| `setNextApproverIds(List<Id>)` | User IDs | Explicitly set next approver(s) |
+
+## Approval.ProcessWorkitemRequest Methods
+
+| Method | Parameter | Description |
+|--------|-----------|-------------|
+| `setWorkitemId(Id)` | Work item ID | The pending work item to act on |
+| `setAction(String)` | `'Approve'` / `'Reject'` / `'Remove'` | Action to take |
+| `setComments(String)` | Text | Approver/rejector comments |
+
+## Approval.ProcessResult Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `isSuccess()` | `Boolean` | Whether the operation succeeded |
+| `getInstanceId()` | `Id` | ProcessInstance ID |
+| `getInstanceStatus()` | `String` | `'Pending'`, `'Approved'`, `'Rejected'` |
+| `getNewWorkitemIds()` | `List<Id>` | Work item IDs created by this step |
+| `getErrors()` | `List<Database.Error>` | Error details on failure |
+
+## Entry Point
+
+| Method | Signature |
+|--------|-----------|
+| `Approval.process()` | `Approval.ProcessResult Approval.process(Approval.ProcessSubmitRequest req)` |
+| `Approval.process()` | `Approval.ProcessResult Approval.process(Approval.ProcessWorkitemRequest req)` |
+
+## Approval Step Properties
+
+| Property | Options |
+|----------|---------|
+| Approver type | User field, Manager field, Queue, Related user |
+| Step criteria | All records OR filter criteria (step-specific) |
+| Reject behavior | Final rejection OR go to previous step |
+| Unanimity | All must approve OR first response |
+
+## Approval Actions by Phase
+
+| Phase | Available Actions |
+|-------|-------------------|
+| Initial Submission | Field Update, Email Alert, Record Lock, Outbound Message |
+| Final Approval | Field Update, Email Alert, Record Unlock, Workflow Task, Outbound Message |
+| Final Rejection | Field Update, Email Alert, Record Unlock |
+| Recall | Record Unlock, Field Update |
+
+## Related Standard Objects
+
+| Object | Purpose | Key Fields |
+|--------|---------|------------|
+| `ProcessInstance` | One approval submission | `TargetObjectId`, `Status`, `CreatedDate` |
+| `ProcessInstanceWorkitem` | A pending approval task | `ActorId`, `ProcessInstanceId` |
+| `ProcessInstanceStep` | One completed step in history | `StepStatus`, `Comments`, `ActorId`, `CreatedDate` |
+| `ProcessInstanceHistory` | Union of steps and work items | `StepStatus`, `Comments`, `Actor.Name` |
+
+## Key SOQL Queries
+
+| Purpose | Object | Filter |
+|---------|--------|--------|
+| Pending items for current user | `ProcessInstanceWorkitem` | `WHERE ActorId = :UserInfo.getUserId()` |
+| Approval history for a record | `ProcessInstanceStep` | `WHERE ProcessInstance.TargetObjectId = :recordId` |
+| Active work item for a record | `ProcessInstanceWorkitem` | `WHERE ProcessInstance.TargetObjectId = :recordId AND ProcessInstance.Status = 'Pending'` |
+
+## Metadata Deployment
+
+| Item | Path | package.xml Type |
+|------|------|------------------|
+| Approval process | `approvalProcesses/<Object>.<Name>.approvalProcess-meta.xml` | `ApprovalProcess` |
+| Member format | `<Object>.<ProcessName>` (e.g., `Opportunity.Discount_Approval`) | -- |
+
+## Spring '26 Feature
+
+| Feature | Detail |
+|---------|--------|
+| Integrated Approval Screen Component | Screen Flow component for in-flow approve/reject with history display |
+
+## Key Rules
+
+- Approval processes cannot be created programmatically in Apex tests; deploy via metadata.
+- Record locking is enforced at the UI/API level, not within Apex test context.
+- Dependencies (users, queues, email templates) must exist in target org before deploying approval processes.
+- Use Queues as approvers for vacation coverage; any queue member can approve.
+- Use Flow-based dynamic approvers to route based on amount, region, or other criteria.

package/skills/_reference/ASYNC_PATTERNS.md

@@ -0,0 +1,163 @@
+# Async Apex Patterns -- Reference
+
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_async_overview.htm>
+> Also: <https://architect.salesforce.com/decision-guides/async-processing>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Pattern Summary
+
+| Pattern | Interface / Annotation | Entry Point | Returns |
+|---|---|---|---|
+| **Future** | `@future` / `@future(callout=true)` | `MyClass.myMethod(args)` | `void` (no job ID) |
+| **Queueable** | `Queueable` (+optional `Database.AllowsCallouts`) | `System.enqueueJob(new MyJob())` | `Id` (AsyncApexJob ID) |
+| **Batch** | `Database.Batchable<SObject>` (+optional `Database.Stateful`, `Database.AllowsCallouts`) | `Database.executeBatch(new MyBatch(), scopeSize)` | `Id` (AsyncApexJob ID) |
+| **Schedulable** | `Schedulable` | `System.schedule(name, cron, new MyJob())` | `Id` (CronTrigger ID) |
+
+## Method Signatures
+
+**@future** -- `@future public static void doWork(List<Id> ids) { }` / `@future(callout=true) public static void doCallout(String url) { }`
+
+- Must be `static`. Return: `void` only. Params: **primitives and collections of primitives only** (no SObjects).
+
+**Queueable** -- `public class MyJob implements Queueable { public void execute(QueueableContext ctx) { } }`
+
+- Invoke: `Id jobId = System.enqueueJob(new MyJob());`
+
+**Batch** -- `implements Database.Batchable<SObject>`
+
+- `Database.QueryLocator start(Database.BatchableContext bc)` -- up to **50M rows**
+- `Iterable<SObject> start(Database.BatchableContext bc)` -- alternative, 50K row limit
+- `void execute(Database.BatchableContext bc, List<SObject> scope)` -- scope 1-2000, default 200
+- `void finish(Database.BatchableContext bc)`
+- Invoke: `Database.executeBatch(new MyBatch(), 200);`
+- Must be **outer class**. Add `Database.Stateful` to retain state across `execute()` calls.
+
+**Schedulable** -- `public class MyJob implements Schedulable { public void execute(SchedulableContext ctx) { } }`
+
+- Invoke: `System.schedule('Daily 5AM', '0 0 5 * * ?', new MyJob());`
+- CRON format: `Seconds Minutes Hours Day Month DayOfWeek OptionalYear`
+
+## Concurrency and Chaining Limits
+
+| Constraint | Limit |
+|---|---|
+| `@future` calls per sync transaction | 50 |
+| `@future` from async context | **Not allowed** (cannot call future from future/batch) |
+| Queueable jobs per sync transaction | 50 |
+| Queueable jobs from async context | 1 (chaining) |
+| Queueable chain depth (Dev/Trial orgs) | 5 |
+| Queueable chain depth (Enterprise+) | Unlimited (configurable via `AsyncOptions`) |
+| Concurrent active Batch jobs | 5 |
+| Batch jobs in flex queue | 100 |
+| Scheduled jobs per org | 100 |
+| Daily async method executions | max(250,000, user_licenses x 200) |
+
+## Queueable Advanced Features (API v50.0+)
+
+**AsyncOptions** -- pass as second arg to `System.enqueueJob(job, opts)`:
+
+- `opts.MinimumQueueableDelayInMinutes` -- 0-10 minutes
+- `opts.MaximumQueueableStackDepth` -- cap chain depth
+- `opts.DuplicateSignature` -- `new QueueableDuplicateSignature.Builder().addId(id).build()`
+
+**AsyncInfo** -- runtime introspection:
+
+- `AsyncInfo.getCurrentQueueableStackDepth()`, `.getMaximumQueueableStackDepth()`, `.hasMaxStackDepth()`
+
+**Transaction Finalizers** -- `implements Finalizer` with `void execute(FinalizerContext ctx)`:
+
+- Attach inside Queueable: `System.attachFinalizer(new MyFinalizer());`
+- `ctx.getResult()` returns `SUCCESS` or `UNHANDLED_EXCEPTION`; `ctx.getAsyncApexJobId()` returns parent job ID.
+- Runs after Queueable completes (success **or** failure). Can catch `System.LimitException` (normally uncatchable).
+- Can enqueue a new Queueable for retry (max 5 consecutive retries recommended).
+
+## Governor Limit Differences (Sync vs Async)
+
+See `GOVERNOR_LIMITS.md` for full table. Key elevated limits in async context:
+
+| Resource | Synchronous | Async (@future / Queueable / Batch) |
+|---|---|---|
+| SOQL queries | 100 | 200 |
+| CPU time | 10,000 ms | 60,000 ms |
+| Heap size | 6 MB | 12 MB |
+
+DML, callouts, and SOQL row limits remain **unchanged** between sync and async.
+
+## Decision Matrix
+
+| Criterion | @future | Queueable | Batch | Schedulable |
+|---|---|---|---|---|
+| **Record volume** | Small | Small-Medium | Large (up to 50M) | N/A (delegates) |
+| **Complex types as input** | No (primitives only) | Yes | Yes | N/A |
+| **Job monitoring** | No | Yes (job ID) | Yes (job ID) | Yes (cron ID) |
+| **Chaining** | No | Yes (1 per async) | No | No |
+| **Callouts** | `@future(callout=true)` | `Database.AllowsCallouts` | `Database.AllowsCallouts` | No (sync context) |
+| **Error recovery** | None | Transaction Finalizers | `finish()` method | None |
+| **Execution timing** | ASAP, no SLA | ASAP + optional delay (0-10 min) | Queued, off-peak | Cron schedule |
+| **Typical use case** | Simple fire-and-forget | Callouts, chained steps | Data cleansing, migration | Daily/weekly maintenance |
+
+**Default recommendation (Spring '26):** Use **Queueable** unless you need Batch's 50M-row capacity or Schedulable's cron timing. `@future` is legacy; Queueable supersedes it in all scenarios.
+
+## Error Recovery Patterns
+
+### Transaction Finalizer Retry
+
+Finalizers run after a Queueable completes — even on `System.LimitException`. Use for retry with backoff.
+
+```apex
+public class RetryableJob implements Queueable {
+    private Integer attempt;
+    public RetryableJob(Integer attempt) { this.attempt = attempt; }
+
+    public void execute(QueueableContext ctx) {
+        System.attachFinalizer(new RetryFinalizer(attempt));
+        // ... main work ...
+    }
+}
+
+public class RetryFinalizer implements Finalizer {
+    private Integer attempt;
+    public RetryFinalizer(Integer attempt) { this.attempt = attempt; }
+
+    public void execute(FinalizerContext ctx) {
+        if (ctx.getResult() == ParentJobResult.UNHANDLED_EXCEPTION && attempt < 3) {
+            System.enqueueJob(new RetryableJob(attempt + 1));
+        }
+    }
+}
+```
+
+### Platform Event Partial Publish Handling
+
+`EventBus.publish()` returns a list of `Database.SaveResult`. Check each for failures.
+
+```apex
+List<Order_Event__e> events = new List<Order_Event__e>{ /* ... */ };
+List<Database.SaveResult> results = EventBus.publish(events);
+for (Integer i = 0; i < results.size(); i++) {
+    if (!results[i].isSuccess()) {
+        for (Database.Error err : results[i].getErrors()) {
+            Logger.error('Event publish failed at index ' + i + ': ' + err.getMessage());
+        }
+    }
+}
+```
+
+### EventBus.RetryableException in Subscribers
+
+Throw `EventBus.RetryableException` in an event trigger subscriber to request platform retry (up to 9 retries over 24 hours).
+
+```apex
+trigger OrderEventTrigger on Order_Event__e (after insert) {
+    for (Order_Event__e evt : Trigger.New) {
+        try {
+            OrderProcessor.process(evt);
+        } catch (CalloutException e) {
+            // Transient error — request retry
+            throw new EventBus.RetryableException(e.getMessage());
+        }
+    }
+}
+```
+
+The platform automatically sets the replay pointer back and re-delivers the event batch. Do NOT throw `RetryableException` for permanent failures (bad data, missing config) — those will retry forever until the 24-hour window expires.

package/skills/_reference/AURA_COMPONENTS.md

@@ -0,0 +1,146 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/intro_framework.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+<!-- WARNING: Web fetch of canonical URL failed (JS-rendered page). Facts extracted from SCC skill sf-aura-development. Verify against official docs before relying on framework details. -->
+
+# Aura Components Reference
+
+## Status
+
+Aura is in **maintenance mode** (since LWC introduction, 2019). Use LWC for all new development.
+
+## Component Bundle Structure
+
+| File | Extension | Required | Purpose |
+|------|-----------|----------|---------|
+| Component markup | `.cmp` | Yes | XML template with markup and attributes |
+| Client-side controller | `Controller.js` | No | Action handlers (thin; delegates to helper) |
+| Helper | `Helper.js` | No | Reusable business logic |
+| Renderer | `Renderer.js` | No | Custom rendering overrides (rare) |
+| Styles | `.css` | No | Component-scoped CSS |
+| Design | `.design` | No | App Builder property editor config |
+| Documentation | `.auradoc` | No | Displayed in Component Library |
+| SVG icon | `.svg` | No | Custom icon (60x60) |
+| Metadata | `.cmp-meta.xml` | Yes (deploy) | apiVersion, description |
+
+Bundle path: `force-app/main/default/aura/<ComponentName>/`
+
+## Attribute Types
+
+| Category | Types |
+|----------|-------|
+| Primitive | `String`, `Integer`, `Decimal`, `Boolean`, `Date` |
+| Collection | `String[]`, `Account[]`, `Map` |
+| SObject | Any SObject name (e.g., `Contact`, `Account`) |
+| Generic | `Object` (use sparingly) |
+
+## Attribute Rules
+
+- Always provide `default` for collection types to avoid null reference errors.
+- Use `access="private"` for internal-only attributes.
+- Use `type="Object"` sparingly; prefer typed attributes.
+
+## Event Model
+
+| Aspect | Component Event | Application Event |
+|--------|----------------|-------------------|
+| Type attribute | `type="COMPONENT"` | `type="APPLICATION"` |
+| Scope | Parent-child only | Any component on the page |
+| Propagation | Bubbles up containment hierarchy | Broadcast to all handlers |
+| Registration | `<aura:registerEvent>` in child | `<aura:registerEvent>` in sender |
+| Handling | `<aura:handler>` in parent | `<aura:handler>` anywhere |
+| Performance | Lightweight | Heavier (all handlers evaluated) |
+| LWC equivalent | `CustomEvent` | Lightning Message Service |
+
+## Lifecycle Handlers
+
+| Handler | Fires When | LWC Equivalent |
+|---------|-----------|----------------|
+| `aura:handler name="init"` | Component initialized | `connectedCallback()` |
+| `aura:handler name="render"` | After render | `renderedCallback()` |
+| `aura:handler name="destroy"` | Component destroyed | `disconnectedCallback()` |
+| `aura:handler name="change"` | Attribute value changes | Reactive `@api` setter |
+
+## Server-Side Communication
+
+| Pattern | Code | Description |
+|---------|------|-------------|
+| Enqueue action | `$A.enqueueAction(action)` | All Apex calls go through the action queue |
+| Set parameters | `action.setParams({...})` | Pass arguments to `@AuraEnabled` method |
+| Callback states | `SUCCESS`, `ERROR`, `INCOMPLETE` | Always handle all three |
+| Storable action | `action.setStorable()` | Client-side caching; only for `cacheable=true` methods |
+| Background action | `action.setBackground()` | Lower priority; does not block UI queue |
+
+## Storable Action Rules
+
+- Only use on `@AuraEnabled(cacheable=true)` methods.
+- Callback may fire twice: once from cache, once from server.
+- Never use for DML operations.
+- Cache key = action name + parameters.
+
+## Security Model
+
+| Layer | Scope |
+|-------|-------|
+| Locker Service (legacy) | DOM isolation via SecureElement wrappers; namespace-scoped `document.cookie` |
+| Lightning Web Security (current) | Standard APIs with fewer restrictions |
+| CSP restrictions | No `eval()`, no `new Function()`, no inline `onclick` attributes |
+| `$A.getCallback()` | Required for all async code outside Aura lifecycle (setTimeout, Promises) |
+
+## Key Framework Objects
+
+| Object | Purpose |
+|--------|---------|
+| `$A` | Framework namespace; `$A.enqueueAction()`, `$A.get()`, `$A.getCallback()`, `$A.createComponent()` |
+| `component` | Current component instance; `.get()`, `.set()`, `.find()`, `.getEvent()`, `.isValid()`, `.getGlobalId()` |
+| `event` | Event object; `.getParam()`, `.setParams()`, `.fire()`, `.stopPropagation()`, `.getPhase()`, `.getSource()` |
+| `helper` | Shared across all instances of the component on the same page |
+
+## Common Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `force:appHostable` | Can be used as a Lightning app tab |
+| `flexipage:availableForAllPageTypes` | Available in App Builder on all page types |
+| `force:hasRecordId` | Receives record ID from record pages |
+| `force:hasSObjectName` | Receives object API name |
+
+## Aura-to-LWC Migration Map
+
+| Aura | LWC |
+|------|-----|
+| `aura:attribute` | `@api` property |
+| `aura:handler name="init"` | `connectedCallback()` |
+| `aura:handler name="render"` | `renderedCallback()` |
+| `aura:handler name="destroy"` | `disconnectedCallback()` |
+| `aura:if` / `aura:set else` | `lwc:if` / `lwc:elseif` / `lwc:else` |
+| `aura:iteration` | `for:each` / `iterator` (requires `key`) |
+| `$A.enqueueAction()` | `@wire` or imperative `async/await` import |
+| `component.get("v.attr")` | `this.propertyName` |
+| `component.set("v.attr", val)` | `this.propertyName = val` (reactive) |
+| `component.find("auraId")` | `this.template.querySelector()` |
+| `action.setStorable()` | `@wire` with `cacheable=true` |
+| Helper.js (separate file) | Class methods in single JS file |
+| `$A.getCallback()` | Not needed (LWC handles async natively) |
+| `$A.createComponent()` | `lwc:component` with `lwc:is` (API 59+) |
+| Application events | Lightning Message Service |
+| Component events | `CustomEvent` |
+| Locker Service | Lightning Web Security |
+| `aura:dependency` | ES module `import` |
+
+## Migration Strategy (ordered)
+
+| Step | Action |
+|------|--------|
+| 1 | Inventory all Aura components, dependencies, and usage locations |
+| 2 | Prioritize leaf components (no child Aura dependencies) |
+| 3 | Wrap: replace Aura parents with LWC, keep Aura children via interop |
+| 4 | Convert: rewrite using LWC patterns |
+| 5 | Test: validate behavior parity |
+| 6 | Deploy: replace Aura references on pages/apps |
+
+## LWC-in-Aura Interop Rules
+
+- LWC components embed directly in Aura markup: `<c:lwcChild record-id="{!v.recordId}" />`
+- Aura passes data to LWC via attributes mapped to `@api` properties.
+- LWC sends data to Aura via `CustomEvent`; Aura reads via `event.getParam("detail")`.
+- Pubsub pattern is deprecated; use Lightning Message Service for cross-framework communication.