scc-universal 1.1.0

package/skills/_reference/INTEGRATION_PATTERNS.md

@@ -0,0 +1,105 @@
+# Integration Patterns — Reference
+
+> Source: <https://architect.salesforce.com/fundamentals/integration-patterns>
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_timeouts.htm>
+> Source: <https://help.salesforce.com/s/articleView?id=xcloud.nc_auth_protocols.htm>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Apex Callout Limits
+
+| Limit | Value |
+|---|---|
+| Max callouts per transaction | 100 |
+| Max cumulative timeout (all callouts) | 120 s |
+| Default timeout per callout | 10 s |
+| Max configurable timeout per callout | 120 s (120,000 ms) |
+| Max request size (sync) | 6 MB |
+| Max request size (async) | 12 MB |
+| Max response size (sync) | 6 MB |
+| Max response size (async) | 12 MB |
+| Continuation max timeout | 120 s |
+| Continuation max callouts per request | 3 |
+| Max redirects followed | 5 |
+
+## Composite API Limits
+
+| Resource | Max Subrequests | Notes |
+|---|---|---|
+| **Composite** | 25 | Supports references between subrequests; max 5 query/sObject Collections ops |
+| **Composite Batch** | 25 | Independent subrequests; no inter-reference |
+| **Composite Graph** | 500 | Up to 500 nodes across all graphs in one request |
+| **sObject Tree** | 200 records | Insert only; max 5 levels deep |
+| **sObject Collections** | 200 records | Create/update/upsert/delete per request |
+
+Each full Composite request counts as **1 API call** against org limits regardless of subrequest count.
+
+## Named Credentials Architecture (New Model, Winter '23+)
+
+Legacy Named Credentials are deprecated. New model splits into two components:
+
+| Component | Purpose |
+|---|---|
+| **Named Credential** | Defines callout endpoint URL + HTTP transport protocol |
+| **External Credential** | Defines authentication protocol + user identity mapping |
+
+One External Credential can back multiple Named Credentials.
+
+### External Credential — Authentication Protocols
+
+| Protocol | Variants |
+|---|---|
+| **OAuth 2.0** | Client Credentials (client secret), Client Credentials (JWT assertion), JWT Bearer, Browser Flow |
+| **JWT** | Signing certificate from subscriber org |
+| **AWS Signature V4** | Standard (access key + secret), STS (temporary credentials), STS Roles Anywhere (certificate-based) |
+| **Custom** | User-defined headers/tokens; populated via API or per-user |
+| **No Authentication** | Anonymous callouts |
+
+### Identity Types
+
+| Type | Behavior |
+|---|---|
+| **Named Principal** | Single credential shared across all users |
+| **Per User** | Each user maps to their own external credential |
+| **Anonymous** | No authentication sent |
+
+## Integration Pattern Decision Matrix
+
+| Pattern | Direction | Timing | Protocols / Mechanisms | Volume | Use When |
+|---|---|---|---|---|---|
+| **Request and Reply** | SF -> External | Sync | Apex REST/SOAP callout, External Services | Small | Need response in same transaction |
+| **Fire and Forget** | SF -> External | Async | Platform Events, CDC, Outbound Messages, Pub/Sub API | Small-Med | No response needed; eventual consistency OK |
+| **Batch Data Sync** | Bidirectional | Async | Bulk API 2.0, Data Loader, Composite API, ETL | Large (2K+) | Scheduled bulk data movement |
+| **Remote Call-In** | External -> SF | Sync | REST API, SOAP API, Composite, Bulk API 2.0, Pub/Sub API | Any | External system initiates CRUD or event publish |
+| **UI Update on Data Change** | Internal | Async | CDC, Platform Events, Streaming API, Emp API (LWC) | Real-time | Push UI updates without polling |
+| **Data Virtualization** | SF -> External | Sync | Apex HTTP callouts, Salesforce Connect (OData), External Objects | Small | Real-time read without persisting external data |
+
+## Platform Event Limits (Reference)
+
+| Limit | Value |
+|---|---|
+| Event publish (Apex) | 150 per transaction |
+| Event publish (Flow) | 150 per transaction |
+| Event publish (API) | Based on API limits |
+| Event delivery retention | 72 hours (standard), 24 hours (high-volume) |
+| CometD subscribers per org | 2,000 |
+| Max event message size | 1 MB |
+
+## External Services Limits
+
+| Limit | Value |
+|---|---|
+| Schema format | OpenAPI 2.0 and 3.0 |
+| Max schema upload size | 10 MB |
+| Callouts per Apex transaction | 100 (shared with all Apex callouts) |
+| Supported invocation | Flow, Apex, Agentforce Actions |
+| Inbound webhooks | Not supported |
+
+## Callout Best Practices (Quick Reference)
+
+- Always use **Named Credentials** — never hard-code endpoints or tokens in Apex.
+- Use **Continuations** for long-running callouts in LWC/Aura to avoid holding a thread.
+- Use **Queueable** or **@future(callout=true)** to move callouts out of trigger context.
+- Use **Composite API** (not individual REST calls) when external systems call into Salesforce to reduce API consumption.
+- Use **Platform Events** or **CDC** for fire-and-forget; prefer over Outbound Messages for new builds.
+- Use **Bulk API 2.0** (not REST/SOAP) for anything over 2,000 records.
+- Set explicit **timeout values** — the 10 s default is often too short for third-party APIs.

package/skills/_reference/LWC_PATTERNS.md

@@ -0,0 +1,79 @@
+# LWC Patterns — Reference
+
+> Source: <https://developer.salesforce.com/docs/platform/lwc/guide/>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Lifecycle Hooks (Execution Order)
+
+| # | Hook | Fires when | Direction | Key constraints |
+|---|------|-----------|-----------|----------------|
+| 1 | `constructor()` | Component instantiated | — | No DOM access. No attributes/public props. Call `super()` first. |
+| 2 | `connectedCallback()` | Inserted into DOM | Parent → child | Can fire more than once (reorder/reinsert). Cannot access child elements. Use `this.isConnected` to check. |
+| 3 | `render()` | Before each render | — | Return alternate template import. Rarely needed. |
+| 4 | `renderedCallback()` | Render complete | Child → parent | Fires every render. Guard one-time logic with a boolean. Updating state here risks infinite loops. |
+| 5 | `disconnectedCallback()` | Removed from DOM | Parent → child | Clean up listeners, caches, message-channel subscriptions. |
+| 6 | `errorCallback(error, stack)` | Descendant error | Child → parent | Catches errors in descendant lifecycle/render. Acts as boundary. |
+
+## Reactive Property Rules
+
+| Decorator | Reactivity scope | When required |
+|-----------|-----------------|---------------|
+| *(none)* | Shallow (`===`) on primitives, new assignment on objects/arrays | Default since Spring '20. All fields are reactive. |
+| `@track` | Deep — observes internal mutations on plain `{}` and `[]` | Mutating object properties or array elements in place. Does NOT observe `Date`, `Set`, `Map`, or class instances. |
+| `@api` | Shallow — reactive when parent sets new value | Exposing public properties/methods. Defines component API. |
+| `@wire` | Reactive via `$`-prefixed params | Binding to wire adapters or Apex methods. |
+
+**Re-render trigger**: only fields accessed during the previous render cycle. New/unaccessed properties do not trigger re-render even with `@track`.
+
+## Wire Service Rules
+
+- `@wire` provisions an **immutable stream**; data objects are read-only (shallow-copy to mutate).
+- `$`-prefixed params are reactive; changes re-provision data. Only top-level config values use `$`.
+- Wire evaluates only when **all** dynamic params are defined (non-`undefined`).
+- Data may come from LDS cache (no network call). Arrival time is **non-deterministic**.
+- Do NOT update wire config in `renderedCallback()` (infinite loop).
+- Wire chains: one `@wire` output can feed another via `$record.data.fieldName`.
+- On init: `constructor` → LDS provisions `{data: undefined, error: undefined}` → `connectedCallback` → `render` → `renderedCallback` → data arrives → re-render.
+
+## Wire Adapters by Module
+
+| Module | Wire adapters | Functions |
+|--------|--------------|-----------|
+| `lightning/uiRecordApi` | `getRecord`, `getRecords`, `getRecordCreateDefaults` | `createRecord`, `updateRecord`, `deleteRecord`, `notifyRecordUpdateAvailable`, `getFieldValue`, `getFieldDisplayValue`, `generateRecordInputForCreate`, `generateRecordInputForUpdate`, `createRecordInputFilteredByEditedFields` |
+| `lightning/uiObjectInfoApi` | `getObjectInfo`, `getObjectInfos`, `getPicklistValues`, `getPicklistValuesByRecordType` | — |
+| `lightning/uiListApi` *(deprecated)* | `getListUi` | — |
+| `lightning/uiListsApi` | `getListInfoByName`, `getListInfosByListReference` | — |
+| `lightning/uiRelatedListApi` | `getRelatedListRecords`, `getRelatedListCount`, `getRelatedListInfo`, `getRelatedListsInfo`, `getRelatedListRecordsBatch`, `getRelatedListInfoBatch` | — |
+| `lightning/uiLayoutApi` | `getLayoutUserState` | `updateLayoutUserState` |
+| `lightning/graphql` | `graphql` | — |
+| `lightning/messageService` | — | `publish`, `subscribe`, `unsubscribe`, `createMessageContext`, `releaseMessageContext` |
+| `@salesforce/apex` | Apex methods via `@wire` | Imperative `method({params})` |
+
+## Event Propagation
+
+| `bubbles` | `composed` | Behavior |
+|-----------|-----------|----------|
+| `false` | `false` | **Default / recommended.** Does not bubble. Does not cross shadow boundary. Listener must be on dispatching element. |
+| `true` | `false` | Bubbles within owner's shadow tree. Stops at shadow boundary. Works across slots. |
+| `true` | `true` | Bubbles to document root, crosses all shadow boundaries. Becomes public API — namespace event names. |
+| `false` | `true` | Uncommon. Does not bubble but crosses shadow boundary. |
+
+- **Retargeting**: `Event.target` is retargeted at each shadow boundary to the host element.
+- `Event.composedPath()` returns the full propagation path.
+- Always use `CustomEvent` with a `detail` property for data payload.
+- Event names: lowercase, no spaces, use hyphens if needed.
+
+## Slot Rules
+
+| Rule | Detail |
+|------|--------|
+| Unnamed slot | `<slot></slot>` — receives any unslotted child markup. One per component recommended. |
+| Named slot | `<slot name="header"></slot>` — parent targets via `slot="header"`. `name` must be a static string. |
+| Fallback content | Markup inside `<slot>` renders when no content is passed. |
+| Ownership | Slotted content is owned by the **parent** (provider), not the component declaring the `<slot>`. |
+| CSS | Parent styles apply to slotted content. Component styles do not pierce into slotted content. |
+| DOM access | Slotted elements: `this.querySelector()`. Shadow elements: `this.template.querySelector()`. |
+| `slotchange` event | Fires when direct children of a slot change. Does NOT fire for nested child changes. Bubbles but does not cross shadow boundary. |
+| Aura interop | Cannot pass Aura components into LWC slots. |
+| Conditional slots | Use `lwc:if` / `lwc:else` on `<template>` wrapping slots. Avoid deprecated `if:true`. |
+| No ID selectors | IDs are transformed at render time; never use `querySelector('#id')` for slotted or shadow elements. |

package/skills/_reference/METADATA_TYPES.md

@@ -0,0 +1,115 @@
+# Metadata Types — Salesforce Reference
+
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm>
+> Registry: <https://github.com/forcedotcom/source-deploy-retrieve> (metadataRegistry.json)
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Common Metadata Types
+
+| package.xml Name | directoryName | suffix | inFolder | Wildcard (`*`) |
+|---|---|---|---|---|
+| ApexClass | classes | .cls | No | Yes |
+| ApexTrigger | triggers | .trigger | No | Yes |
+| ApexComponent | components | .component | No | Yes |
+| ApexPage | pages | .page | No | Yes |
+| AuraDefinitionBundle | aura | (bundle) | No | Yes |
+| LightningComponentBundle | lwc | (bundle) | No | Yes |
+| CustomObject | objects | .object | No | Yes |
+| CustomField | fields | .field | No | No (child of CustomObject) |
+| CustomMetadata | customMetadata | .md | No | Yes |
+| CustomLabels | labels | .labels | No | Yes |
+| CustomTab | tabs | .tab | No | Yes |
+| CustomApplication | applications | .app | No | Yes |
+| CustomPermission | customPermissions | .customPermission | No | Yes |
+| Layout | layouts | .layout | No | Yes |
+| CompactLayout | compactLayouts | .compactLayout | No | No (child of CustomObject) |
+| FlexiPage | flexipages | .flexipage | No | Yes |
+| Flow | flows | .flow | No | Yes |
+| Profile | profiles | .profile | No | Yes |
+| PermissionSet | permissionsets | .permissionset | No | Yes |
+| PermissionSetGroup | permissionsetgroups | .permissionsetgroup | No | Yes |
+| StaticResource | staticresources | .resource | No | Yes |
+| Report | reports | .report | Yes | No (use folder paths) |
+| Dashboard | dashboards | .dashboard | Yes | No (use folder paths) |
+| Document | documents | (varies) | Yes | No (use folder paths) |
+| EmailTemplate | email | .email | Yes | No (use folder paths) |
+| Workflow | workflows | .workflow | No | Yes |
+| ValidationRule | validationRules | .validationRule | No | No (child of CustomObject) |
+| RecordType | recordTypes | .recordType | No | No (child of CustomObject) |
+| ListView | listViews | .listView | No | No (child of CustomObject) |
+| QuickAction | quickActions | .quickAction | No | Yes |
+| GlobalValueSet | globalValueSets | .globalValueSet | No | Yes |
+| StandardValueSet | standardValueSets | .standardValueSet | No | Yes |
+| ConnectedApp | connectedApps | .connectedApp | No | Yes |
+| RemoteSiteSetting | remoteSiteSettings | .remoteSite | No | Yes |
+| NamedCredential | namedCredentials | .namedCredential | No | Yes |
+| ExternalDataSource | dataSources | .dataSource | No | Yes |
+| SharingRules | sharingRules | .sharingRules | No | No |
+| AssignmentRules | assignmentRules | .assignmentRules | No | No |
+| ApprovalProcess | approvalProcesses | .approvalProcess | No | Yes |
+| ExperienceBundle | experiences | (bundle) | No | Yes |
+| PlatformEventChannel | platformEventChannels | .platformEventChannel | No | Yes |
+| PathAssistant | pathAssistants | .pathAssistant | No | Yes |
+
+## Wildcard Rules
+
+- **Yes** — `<members>*</members>` retrieves all components of that type.
+- **No (child)** — child metadata (CustomField, ValidationRule, RecordType, ListView, CompactLayout) must be qualified: `ObjectName.FieldName`.
+- **No (inFolder)** — folder-based types (Report, Dashboard, Document, EmailTemplate) require folder-qualified members: `FolderName` or `FolderName/ReportName`.
+- **AssignmentRules / SharingRules / EscalationRules** — must specify the object: `Case`, `Lead`.
+
+## Deployment Order (Recommended)
+
+Deploy in this sequence to avoid reference errors:
+
+| Order | Types | Reason |
+|---|---|---|
+| 1 | CustomObject, CustomField, GlobalValueSet, StandardValueSet, RecordType | Schema must exist before anything references it |
+| 2 | CustomMetadata, CustomLabels, CustomPermission, CustomTab | Referenced by code and configuration |
+| 3 | ApexClass (non-test) | Business logic depends on schema |
+| 4 | ApexTrigger | Triggers depend on classes and schema |
+| 5 | Flow, Workflow, ApprovalProcess, AssignmentRules, SharingRules | Automation depends on schema + classes |
+| 6 | Layout, CompactLayout, FlexiPage, PathAssistant, QuickAction | UI depends on fields and actions |
+| 7 | LightningComponentBundle, AuraDefinitionBundle, ApexPage, ApexComponent, StaticResource | UI components |
+| 8 | Profile, PermissionSet, PermissionSetGroup | Access control references all of the above |
+| 9 | Report, Dashboard, Document, EmailTemplate | Content depends on schema + access |
+| 10 | ConnectedApp, NamedCredential, RemoteSiteSetting, ExternalDataSource | Integration config (often environment-specific) |
+| 11 | ApexClass (test), ExperienceBundle | Tests and experiences deployed last |
+
+## Bundle Types (No Single Suffix)
+
+| Type | Directory | Contents |
+|---|---|---|
+| LightningComponentBundle | lwc/`componentName`/ | `.js`, `.html`, `.css`, `.js-meta.xml` |
+| AuraDefinitionBundle | aura/`componentName`/ | `.cmp`, `.js`, `.css`, `.design`, `.svg`, `-meta.xml` |
+| ExperienceBundle | experiences/`siteName`/ | Multiple config files and directories |
+
+## package.xml Snippet
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+  <types>
+    <members>*</members>
+    <name>ApexClass</name>
+  </types>
+  <types>
+    <members>*</members>
+    <name>ApexTrigger</name>
+  </types>
+  <types>
+    <members>*</members>
+    <name>CustomObject</name>
+  </types>
+  <types>
+    <members>MyFolder</members>
+    <members>MyFolder/MyReport</members>
+    <name>Report</name>
+  </types>
+  <types>
+    <members>Account.MyField__c</members>
+    <name>CustomField</name>
+  </types>
+  <version>66.0</version>
+</Package>
+```

package/skills/_reference/NAMING_CONVENTIONS.md

@@ -0,0 +1,84 @@
+# Naming Conventions — Salesforce Reference
+
+> Last verified: API v66.0 (Spring '26)
+> Source: Salesforce Apex Developer Guide + community standards
+
+## Apex Naming
+
+### Casing Rules
+
+| Element | Casing | Example |
+|---|---|---|
+| Class names | PascalCase | `AccountService`, `OrderProcessor` |
+| Interface names | PascalCase (prefix `I` optional) | `IAccountsSelector` |
+| Method names | camelCase (start with verb) | `getActiveAccounts()`, `isEligible()` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `STATUS_ACTIVE` |
+| Variables / parameters | camelCase | `accountName`, `recordCount` |
+| Instance fields | camelCase (no underscore prefix) | `private String accountName` |
+| Enum values | UPPER_SNAKE_CASE | `Status.ACTIVE`, `Priority.HIGH` |
+
+### Class Suffixes by Role
+
+| Role | Suffix | Example |
+|---|---|---|
+| Service layer | `Service` | `AccountService` |
+| Selector / data access | `Selector` | `AccountsSelector` |
+| Domain / business logic | (object name, no suffix) | `Accounts` (FFLIB) |
+| Trigger handler | `TriggerHandler` | `AccountTriggerHandler` |
+| Batch job | `Batch` | `AccountAnnualReviewBatch` |
+| Queueable job | `Job` or `Queueable` | `AccountProcessorJob` |
+| Schedulable | `Scheduler` or `Schedule` | `AccountReviewScheduler` |
+| Controller (LWC/Aura/VF) | `Controller` | `AccountPaginationController` |
+| Test class | `Test` (suffix, not prefix) | `AccountServiceTest` |
+| Exception | `Exception` | `AccountServiceException` |
+| Utility / helper | `Util` or `Helper` | `StringUtil`, `QueryHelper` |
+
+### Test Method Naming
+
+Format: `test{MethodName}_{scenario}_{expectedResult}`
+
+| Example | Pattern |
+|---|---|
+| `testCalculateDiscount_premiumTier_returns20Percent()` | Method + scenario + outcome |
+| `testCreateAccount_duplicateName_throwsException()` | Method + edge case + error |
+| `testProcessOrders_emptyList_noExceptionThrown()` | Method + boundary + success |
+
+### Trigger Naming
+
+One trigger per object: `{ObjectName}Trigger`
+
+| Object | Trigger | Handler |
+|---|---|---|
+| Account | `AccountTrigger` | `AccountTriggerHandler` |
+| Contact | `ContactTrigger` | `ContactTriggerHandler` |
+| Opportunity | `OpportunityTrigger` | `OpportunityTriggerHandler` |
+
+## LWC Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Component folder | camelCase | `accountCard/` |
+| Component files | Match folder name | `accountCard.js`, `accountCard.html` |
+| HTML in markup | kebab-case with namespace | `<c-account-card>` |
+| Properties | camelCase | `accountName`, `isLoading` |
+| Event names | lowercase, no separators | `itemselected`, `recordchange` |
+| CSS classes | kebab-case | `.account-header`, `.card-body` |
+
+## Custom Object / Field Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Custom object | PascalCase + `__c` | `Invoice__c`, `Order_Line_Item__c` |
+| Custom field | PascalCase + `__c` | `Annual_Revenue__c`, `Is_Active__c` |
+| Relationship name | PascalCase + `__r` | `Account__r`, `Primary_Contact__r` |
+| Custom metadata type | PascalCase + `__mdt` | `Integration_Config__mdt` |
+| Custom setting | PascalCase + `__c` | `Feature_Flags__c` |
+| Platform event | PascalCase + `__e` | `Order_Status_Change__e` |
+
+## General Rules
+
+- Avoid abbreviations unless universally understood (`Id`, `URL`, `API`)
+- No Hungarian notation (`strName`, `lstAccounts`)
+- Boolean fields/methods: prefix with `is`, `has`, `can`, `should`
+- Collections: use plural nouns (`accounts`, `contactsByAccountId`)
+- Maps: name by pattern `{valueType}By{keyDescription}` (`accountById`, `contactsByAccountId`)

package/skills/_reference/PACKAGE_DEVELOPMENT.md

@@ -0,0 +1,150 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_dev2gp.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+<!-- ⚠️ UNVERIFIED — Salesforce docs site returned JS-only content; facts sourced from Trailhead + skill knowledge -->
+
+# Package Development — Salesforce Reference
+
+## Package Types
+
+| Type | Installable | Upgradeable | Namespace Required | IP Protected | Best For |
+|---|---|---|---|---|---|
+| Unmanaged | Yes | No | No | No | One-off sharing, templates, samples |
+| Unlocked (2GP) | Yes | Yes | Optional | No | Internal modular orgs, team packages |
+| Managed (2GP) | Yes | Yes | Yes | Yes | AppExchange ISV, commercial products |
+| Managed (1GP) | Yes | Yes | Yes | Yes | Legacy AppExchange packages |
+| Source (no package) | N/A | N/A | No | No | Direct org-to-org development |
+
+## 1GP vs 2GP
+
+| Aspect | 1GP (First-Generation) | 2GP (Second-Generation) |
+|---|---|---|
+| Version creation | Upload in packaging org UI | CLI: `sf package version create` |
+| Dev Hub required | No | Yes |
+| Scratch org development | Not natively supported | Full support |
+| Source-driven | No | Yes |
+| Dependency management | Manual | Declarative in `sfdx-project.json` |
+| CI/CD automation | Limited | Full CLI automation |
+
+## Salesforce ID Prefixes
+
+| Object | Prefix | Example |
+|---|---|---|
+| Package (container) | `0Ho` | `0Ho5e000000XXXXX` |
+| Package Version (installable) | `04t` | `04t5e000000XXXXX` |
+| Subscriber Package | `033` | `0335e000000XXXXX` |
+
+## Version Number Format
+
+Format: `Major.Minor.Patch.Build`
+
+| Component | Meaning | Example |
+|---|---|---|
+| Major | Breaking changes | `2.0.0.NEXT` |
+| Minor | New features, backward-compatible | `1.3.0.NEXT` |
+| Patch | Bug fixes | `1.3.1.NEXT` |
+| Build | Auto-increment with `NEXT` or explicit integer | `1.0.0.NEXT` / `1.0.0.5` |
+
+## Version Promotion States
+
+| State | Install Targets | Transition |
+|---|---|---|
+| Beta (created, not promoted) | Scratch orgs, sandboxes, Developer Edition orgs | `sf package version create` |
+| Released (promoted) | Production, sandboxes, any org | `sf package version promote` |
+| Deprecated | Cannot be newly installed; remains in existing orgs | `sf package version update --deprecated` |
+
+## Code Coverage Requirement
+
+| Context | Minimum Coverage |
+|---|---|
+| Create version with `--code-coverage` | 75% Apex code coverage |
+| Promote to released | Must have been created with `--code-coverage` passing |
+| Install in production | Released version required (which requires 75% coverage) |
+| Beta install (scratch/sandbox) | No coverage requirement |
+
+## Namespace Rules
+
+| Decision | Namespace? | When |
+|---|---|---|
+| AppExchange / commercial distribution | Yes (required) | Managed packages for external customers |
+| IP protection needed | Yes | Obfuscated Apex in managed packages |
+| Internal org modularity | No | Unlocked packages, simpler API names |
+| No AppExchange plans | No | Avoids naming complexity |
+
+### Namespace Impact on API Names
+
+| Component Type | Without Namespace | With Namespace (`myns`) |
+|---|---|---|
+| Apex class | `AccountService` | `myns.AccountService` |
+| Custom field | `Status__c` | `myns__Status__c` |
+| Custom object | `Project__c` | `myns__Project__c` |
+
+> **Irreversible:** Once a namespace is assigned to a managed package and a released version is created, the namespace is permanent.
+
+## Managed Package Upgrade Constraints
+
+| Action | Allowed After Release? |
+|---|---|
+| Add new fields (optional) | Yes |
+| Add new Apex methods | Yes |
+| Add new objects | Yes |
+| Add new metadata | Yes |
+| Delete fields or objects | **No** |
+| Change field types | **No** |
+| Remove `global` Apex methods | **No** |
+| Change namespace | **No** |
+| Add required fields | **Risky** — breaks subscribers creating records |
+
+## Apex Visibility in Managed Packages
+
+| Keyword | Subscriber Access |
+|---|---|
+| `global` | Fully accessible from subscriber Apex and Flows |
+| `@namespaceAccessible` + `public` | Accessible from subscriber Apex only |
+| `public` (no annotation) | Hidden from subscribers |
+| `private` | Hidden; IP protected |
+
+## Package CLI Commands
+
+| Command | Purpose |
+|---|---|
+| `sf package create --name <n> --type Unlocked --path <dir> --no-namespace --target-dev-hub devhub` | Create package (one-time) |
+| `sf package version create --package <n> --installation-key "$KEY" --code-coverage --wait 20 --target-dev-hub devhub` | Create beta version |
+| `sf package version promote --package "<n>@1.0.0-1" --target-dev-hub devhub` | Promote to released |
+| `sf package install --package "<n>@1.0.0-1" --installation-key "$KEY" --target-org <org> --wait 10` | Install in target org |
+| `sf package version list --packages <n> --verbose --target-dev-hub devhub` | List all versions |
+| `sf package installed list --target-org <org>` | List installed packages |
+| `sf package install --security-type AdminsOnly` | Restrict to admin profiles |
+| `sf package install --security-type AllUsers` | Grant to all profiles |
+
+## sfdx-project.json Dependency Declaration
+
+| Field | Purpose |
+|---|---|
+| `packageDirectories[].dependencies[]` | Array of `{ package, versionNumber }` |
+| `packageAliases` | Map: alias name to `0Ho` (package) or `04t` (version) ID |
+| `versionNumber` in dependency | Use `X.Y.Z.LATEST` to pick latest build of that version |
+
+Dependencies must be installed in dependency order (base packages first). No `--all` flag exists.
+
+## Package Architecture Best Practice
+
+| Pattern | Components | Layer |
+|---|---|---|
+| Shared Utilities | ~30 | Base (no dependencies) |
+| Sales Core | ~80 | Depends on Shared Utilities |
+| Service Core | ~60 | Depends on Shared Utilities |
+| Integrations | ~40 | Depends on Sales Core + Service Core |
+
+Smaller packages = faster version creation, independent deployment, clear ownership.
+
+## Subscriber Testing Workflow
+
+| Step | Command / Action |
+|---|---|
+| 1. Install beta in scratch org | `sf package install --package "04t..." --target-org myScratch --wait 20` |
+| 2. Run all tests | `sf apex run test --test-level RunAllTestsInOrg --code-coverage --target-org myScratch` |
+| 3. Verify >= 75% coverage | Check test results |
+| 4. Promote | `sf package version promote --package "<name>@X.Y.Z-N" --target-dev-hub devhub` |
+| 5. Install in subscriber sandbox | `sf package install --package "<name>@X.Y.Z-N" --target-org subscriber-sandbox --wait 30` |
+| 6. Run subscriber tests | `sf apex run test --test-level RunLocalTests --target-org subscriber-sandbox` |
+| 7. Install in production | `sf package install --package "<name>@X.Y.Z-N" --target-org production --wait 30` |

package/skills/_reference/PLATFORM_EVENTS.md

@@ -0,0 +1,121 @@
+# Platform Events & CDC — Reference
+
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_event_limits.htm>
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_allocations.htm>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Platform Event Definitions
+
+| Allocation | DE | EE / PE+API | UE / Perf |
+|---|---|---|---|
+| Max event definitions per org | 5 | 50 | 100 |
+| Max event message size | 1 MB | 1 MB | 1 MB |
+| Max concurrent CometD clients (all event types) | 20 | 1,000 | 2,000 |
+| Max flows/processes subscribing to a PE | 4,000 | 4,000 | 4,000 |
+| Max **active** flows/processes subscribing | 2,000 | 2,000 | 2,000 |
+| Custom channels (PE, excl. RTEM) | 100 | 100 | 100 |
+| Custom channels (CDC) | 100 | 100 | 100 |
+| Distinct PE per channel | 5 | 50 | 50 |
+
+## Publishing Allocations (per hour, rolling)
+
+| Allocation | DE | EE / PE+API | UE / Perf |
+|---|---|---|---|
+| Event publishing (all methods) | 50,000 | 250,000 | 250,000 |
+| With add-on license | +25,000 | +25,000 | +25,000 |
+
+Applies to: Apex `EventBus.publish()`, Pub/Sub API, REST/SOAP API, Bulk API, Flows, Process Builder. Exceeding returns `LIMIT_EXCEEDED`.
+
+## Delivery Allocations (per 24h, rolling)
+
+| Allocation | DE | EE / PE+API | UE / Perf |
+|---|---|---|---|
+| Event delivery (shared PE + CDC) | 10,000 | 25,000 | 50,000 |
+| With add-on license | +100,000/day (3M/month entitlement) | same | same |
+
+Applies to: Pub/Sub API, CometD, empApi LWC, Event Relays. **Does NOT apply to**: Apex triggers, Flows, Process Builder -- these have no delivery cap.
+
+## Event Retention
+
+| Event Type | Retention |
+|---|---|
+| High-volume platform events (default since Spring '19) | **72 hours** |
+| Legacy standard-volume events (API v44.0 and earlier) | 24 hours (retiring Summer '27) |
+| Change Data Capture events | **72 hours** |
+
+Subscribers replay missed events via Replay ID within the retention window. Replay IDs are not guaranteed contiguous. After org migration or sandbox refresh, pre-activity Replay IDs are invalid.
+
+## EventBus.publish() Behavior
+
+| Publish Behavior Setting | Transaction | Rollback | Governor Limit |
+|---|---|---|---|
+| **Publish Immediately** (default) | Independent of DML transaction | Cannot roll back | 150 `EventBus.publish()` calls (separate limit) |
+| **Publish After Commit** | Honors transaction boundary | Supports `Database.setSavepoint()` / `rollback()` | Counts as DML statement (against 150 DML limit) |
+
+- Publishing is **asynchronous** -- `Database.SaveResult.isSuccess()` = true means enqueued, not delivered.
+- Status code `OPERATION_ENQUEUED` returned on success.
+- Publish behavior setting does **not** apply to Pub/Sub API publishes.
+- `allOrNone` header is ignored for Publish Immediately; respected for initial enqueue of Publish After Commit.
+
+## Apex Publish Callbacks
+
+- Implement `EventBus.EventPublishFailureCallback` and/or `EventBus.EventPublishSuccessCallback`.
+- Pass callback instance as second arg: `EventBus.publish(eventList, callbackInstance)`.
+- Callback runs under **Automated Process** user.
+- Limit: 5 MB cumulative callback usage in last 30 minutes; max 10 callback invocations per publish.
+
+## Pub/Sub API Allocations
+
+| Allocation | Value |
+|---|---|
+| Max event message size | 1 MB |
+| Max PublishRequest payload | 4 MB (recommend < 3 MB) |
+| Recommended events per publish request | 200 |
+| Max events per FetchRequest | 100 |
+| Max managed subscriptions per org | 200 |
+| Max concurrent gRPC streams per channel | 1,000 |
+
+## Change Data Capture (CDC)
+
+### CDC Entity Selection Limits
+
+| Allocation | DE | EE | UE / Perf |
+|---|---|---|---|
+| Max selected entities (all channels combined) | 5 | 5 | 5 |
+| With add-on license | No limit | No limit | No limit |
+| Max custom channels | 100 | 100 | 100 |
+
+CDC is available for **all custom objects** and a **subset of standard objects** (Account, Contact, Lead, Opportunity, Case, Task, Event, User, Order, Product2, Pricebook2, PricebookEntry, and others -- see Object Reference for full list).
+
+### CDC Event Types
+
+| changeType | Meaning |
+|---|---|
+| `CREATE`, `UPDATE`, `DELETE`, `UNDELETE` | Normal change events with full field data |
+| `GAP_CREATE`, `GAP_UPDATE`, `GAP_DELETE`, `GAP_UNDELETE` | Header only, no field data -- retrieve record via ID |
+| `GAP_OVERFLOW` | Single transaction exceeded 100,000 changes; one overflow event per entity type |
+
+Gap events are caused by: event > 1 MB, field type conversions, internal errors, or database-level changes outside app server transactions.
+
+### Overflow Threshold
+
+First 100,000 changes in a single transaction produce normal change events. Beyond that, one overflow event per entity type. Each field change in an update counts separately toward the 100K threshold.
+
+## Testing Patterns
+
+| Method | Purpose |
+|---|---|
+| `Test.getEventBus().deliver()` | Deliver queued test events to subscribers (triggers, flows) |
+| `Test.getEventBus().fail()` | Simulate publish failure -- invokes `onFailure()` callback |
+| `Test.enableChangeDataCapture()` | Enable CDC in test context for all entities |
+| `Test.startTest()` / `Test.stopTest()` | Events delivered after `stopTest()` |
+
+- Test event bus is **separate** from production event bus.
+- Test publish limit: **500 events per test method**.
+- Replay IDs reset to 0 in test context.
+- `EventBusSubscriber.Position` and `.Tip` reset to 0 in test context.
+- Apex triggers, flows, processes fire in test context; CometD/Pub/Sub API subscribers do **not**.
+
+## Apex Trigger Batch Size
+
+Platform event and CDC triggers receive up to **2,000 records per batch** (vs. 200 for standard DML triggers). Use `EventBus.TriggerContext.currentContext().setResumeCheckpoint(replayId)` to checkpoint and resume on failure. Throw `EventBus.RetryableException` to retry from last checkpoint.