scc-universal 1.1.0

package/skills/_reference/DOCKER_CI_PATTERNS.md

@@ -0,0 +1,138 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ci.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+
+# Docker & CI Patterns — Salesforce Reference
+
+## Docker Images
+
+| Image | Status | Notes |
+|---|---|---|
+| `salesforce/cli` (Docker Hub) | Active | Weekly releases; tags: `latest`, `latest-rc`, `{version}-full`, `{version}-slim` |
+| `salesforce/salesforcedx` | Deprecated | Do not use; migrate to `salesforce/cli` |
+| `node:20-slim` + `npm i -g @salesforce/cli` | Recommended alternative | Full control over base image; smaller footprint |
+
+### Image Tag Variants
+
+| Tag | Contents |
+|---|---|
+| `latest` | Current stable release (retagged weekly from `latest-rc`) |
+| `latest-rc` | Release candidate (published each week) |
+| `{version}-full` | Full Node.js LTS + `sf` installed via npm |
+| `{version}-slim` | Minimal image, smaller footprint |
+
+### Release Cadence
+
+- New `latest-rc` image published **weekly**
+- Retagged to `latest` the following week
+- Versioned tags match CLI version (e.g., `2.70.7-slim`)
+
+## CI Authentication Methods
+
+| Method | Command | Best For |
+|---|---|---|
+| JWT Bearer Flow | `sf org login jwt --client-id $KEY --jwt-key-file server.key --username $USER` | CI/CD (headless, no browser) |
+| SFDX Auth URL | `sf org login sfdx-url --sfdx-url-file auth.txt` | CI/CD (simpler setup) |
+| Web Login | `sf org login web` | Local dev only (requires browser) |
+
+JWT Bearer Flow is the **recommended** method for CI pipelines.
+
+## CI Pipeline Structure
+
+Salesforce recommends splitting CI into two jobs:
+
+| Job | Tools | Purpose |
+|---|---|---|
+| Job 1: Lint & LWC Tests | Node.js, ESLint, Jest, Prettier | Format, lint, and unit-test LWC |
+| Job 2: Deploy & Apex Tests | Salesforce CLI, Scratch Org | Deploy metadata, run Apex tests |
+
+## Core CLI Commands for CI
+
+| Command | Purpose |
+|---|---|
+| `sf org login jwt ...` | Authenticate to DevHub (headless) |
+| `sf org login sfdx-url --sfdx-url-file auth.txt --set-default-dev-hub` | Auth via stored URL |
+| `sf org create scratch --definition-file config/project-scratch-def.json --alias ci --duration-days 1` | Create ephemeral scratch org |
+| `sf project deploy start --target-org ci` | Deploy source to scratch org |
+| `sf apex run test --test-level RunLocalTests --code-coverage --result-format human --target-org ci` | Run Apex tests with coverage |
+| `sf org delete scratch --target-org ci --no-prompt` | Cleanup scratch org |
+| `sf code-analyzer run --target force-app --format table` | Static analysis (Code Analyzer) |
+
+## Scratch Org Lifecycle in CI
+
+| Step | Duration | Notes |
+|---|---|---|
+| Create | ~60-120s | Use `--duration-days 1` for auto-cleanup |
+| Deploy | Varies | Full source push |
+| Test | Varies | `RunLocalTests` excludes managed package tests |
+| Delete | ~10s | Always run in `if: always()` / `post` block |
+
+## Supported CI Platforms
+
+| Platform | Sample Repos / Docs |
+|---|---|
+| GitHub Actions | `forcedotcom/sfdx-github-actions` |
+| Jenkins | Salesforce DX Developer Guide: CI with Jenkins |
+| CircleCI | Salesforce DX Developer Guide: CI with CircleCI |
+| GitLab CI | Community examples; same CLI commands |
+| Bitbucket Pipelines | Community examples; same CLI commands |
+
+## GitHub Actions Workflow Pattern
+
+```yaml
+name: Salesforce CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: node:20-slim
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm install -g @salesforce/cli
+      - name: Auth DevHub
+        run: |
+          echo "${{ secrets.SFDX_AUTH_URL }}" > auth.txt
+          sf org login sfdx-url --sfdx-url-file auth.txt --set-default-dev-hub
+      - name: Create Scratch Org
+        run: sf org create scratch --definition-file config/project-scratch-def.json --alias ci --duration-days 1
+      - name: Deploy
+        run: sf project deploy start --target-org ci
+      - name: Test
+        run: sf apex run test --test-level RunLocalTests --code-coverage --result-format human --target-org ci
+      - name: Cleanup
+        if: always()
+        run: |
+          rm -f auth.txt server.key
+          sf org delete scratch --target-org ci --no-prompt
+```
+
+## Security Hardening
+
+| Practice | Implementation |
+|---|---|
+| Non-root user | `RUN adduser --system appuser` then `USER appuser` |
+| Credential cleanup | `rm -f auth.txt server.key` after auth |
+| Secret storage | GitHub Secrets / CI vault; never commit credentials |
+| Auth volume | Named volume for `.sf` directory (dev only, not CI) |
+
+## Cache Optimization
+
+| Strategy | Implementation |
+|---|---|
+| Layer ordering | Install CLI first (rarely changes), copy source last |
+| npm cache (GitHub Actions) | `actions/cache@v4` with `~/.npm` path, key on `package-lock.json` hash |
+| Dependency install | `npm ci --omit=dev` for production builds |
+| Multi-stage build | Stage 1: build + lint + scan; Stage 2: runtime with `sf` only |
+
+## Best Practices
+
+| Practice | Reason |
+|---|---|
+| Use `node:20-slim` + npm install | `salesforce/cli` images may lag; full control over base |
+| Pin image versions (`node:20.19-slim`) | Reproducible builds |
+| `--duration-days 1` for CI scratch orgs | Auto-cleanup if delete step fails |
+| Always delete scratch orgs in `if: always()` | Prevent DevHub scratch org limit exhaustion |
+| Store auth URLs / JWT keys as CI secrets | Never commit credentials |
+| Run Code Analyzer in Docker | Consistent static analysis across machines |
+| Multi-stage builds | Smaller final image; lint/scan in build stage only |
+| Non-root container user | Security hardening for production |

package/skills/_reference/ENTERPRISE_PATTERNS.md

@@ -0,0 +1,122 @@
+# Apex Enterprise Patterns (FFLIB) -- Reference
+
+> Source: [fflib-apex-common](https://github.com/apex-enterprise-patterns/fflib-apex-common), [fflib.dev](https://fflib.dev/docs)
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Layer Architecture
+
+| Layer | Responsibility | Allowed Dependencies |
+|---|---|---|
+| **Selector** | All SOQL/SOSL queries for one SObject. No business logic. | None (data access only) |
+| **Domain** | Single-object logic: validation, defaults, trigger handling. No cross-object ops, no direct SOQL. | Selector (same object) |
+| **Service** | Multi-object orchestration, transaction control, business logic entry point. No direct SOQL/DML. | Domain, Selector, other Services, Unit of Work |
+| **Unit of Work** | Transactional DML aggregation. Register ops, commit once. | None (passed into Service) |
+| **Implementation** | Entry points: Controllers, Batch, Queueable, REST, Invocable. Minimal logic. | Service only |
+
+**Call direction**: Implementation -> Service -> Domain / Selector. Never reverse.
+
+## Class Naming Conventions
+
+| Layer | Class Name | Interface Name | Example |
+|---|---|---|---|
+| Selector | `{Object}sSelector` | `I{Object}sSelector` | `AccountsSelector`, `IAccountsSelector` |
+| Domain | `{Object}s` (plural) | `I{Object}s` | `Accounts`, `IAccounts` |
+| Service | `{Object}sService` | `I{Object}sService` | `AccountsService`, `IAccountsService` |
+| Unit of Work | (use `fflib_SObjectUnitOfWork`) | `fflib_ISObjectUnitOfWork` | -- |
+| Trigger Handler | `{Object}sTriggerHandler` | -- | `AccountsTriggerHandler` |
+
+Domain classes use **plural names** to emphasize bulk processing (e.g., `Opportunities`, not `Opportunity`).
+
+## Application Factory Registration
+
+| Factory | Constructor Argument | Maps To |
+|---|---|---|
+| `UnitOfWorkFactory` | `List<SObjectType>` (parent-first order) | `fflib_ISObjectUnitOfWork` |
+| `ServiceFactory` | `Map<Type, Type>` (interface -> impl) | Service instances |
+| `SelectorFactory` | `Map<SObjectType, Type>` (object -> selector class) | `fflib_ISObjectSelector` |
+| `DomainFactory` | `Application.Selector` + `Map<SObjectType, Type>` | `fflib_ISObjectDomain` |
+
+**UoW SObjectType order** matters -- parent objects first (respects DML dependency).
+DomainFactory depends on SelectorFactory (domain construction queries via selector).
+
+## Key Interfaces
+
+### fflib_ISObjectSelector
+
+| Method | Signature |
+|---|---|
+| `sObjectType` | `Schema.SObjectType sObjectType()` |
+| `selectSObjectsById` | `List<SObject> selectSObjectsById(Set<Id> idSet)` |
+
+### fflib_ISObjectDomain
+
+| Method | Signature |
+|---|---|
+| `sObjectType` | `Schema.SObjectType sObjectType()` |
+| `getRecords` | `List<SObject> getRecords()` |
+
+### fflib_ISObjectUnitOfWork (key methods)
+
+| Method | Signature |
+|---|---|
+| `registerNew` | `void registerNew(SObject record)` |
+| `registerNew` | `void registerNew(SObject record, SObjectField relField, SObject parent)` |
+| `registerDirty` | `void registerDirty(SObject record)` |
+| `registerDirty` | `void registerDirty(SObject record, List<SObjectField> dirtyFields)` |
+| `registerDeleted` | `void registerDeleted(SObject record)` |
+| `registerRelationship` | `void registerRelationship(SObject record, SObjectField relField, SObject relTo)` |
+| `registerUpsert` | `void registerUpsert(SObject record)` |
+| `commitWork` | `void commitWork()` |
+
+All `register*` methods also accept `List<SObject>` overloads.
+
+## Base Class Methods to Override
+
+### fflib_SObjectSelector (abstract)
+
+| Type | Method |
+|---|---|
+| **abstract** | `Schema.SObjectType getSObjectType()` |
+| **abstract** | `List<Schema.SObjectField> getSObjectFieldList()` |
+| virtual | `String getOrderBy()` |
+| virtual | `List<Schema.FieldSet> getSObjectFieldSetList()` |
+
+Constructor options: `(Boolean includeFieldSetFields, Boolean enforceCRUD, Boolean enforceFLS)`.
+
+### fflib_SObjectDomain (virtual trigger handlers)
+
+| Phase | Method |
+|---|---|
+| Defaults | `void onApplyDefaults()` |
+| Before | `void onBeforeInsert()` |
+| Before | `void onBeforeUpdate(Map<Id,SObject> existing)` |
+| Before | `void onBeforeDelete()` |
+| Validation | `void onValidate()` |
+| Validation | `void onValidate(Map<Id,SObject> existing)` |
+| After | `void onAfterInsert()` |
+| After | `void onAfterUpdate(Map<Id,SObject> existing)` |
+| After | `void onAfterDelete()` |
+| After | `void onAfterUndelete()` |
+
+Constructor: `fflib_SObjectDomain(List<SObject> records)`.
+
+## Dependency Rules (Strict)
+
+| Rule | Description |
+|---|---|
+| Selectors never call Services or Domains | Query-only layer |
+| Domains never call Services | Prevents circular dependencies |
+| Services own the Unit of Work | Create UoW in Service, pass to Domain if needed |
+| `Application.Domain` factory depends on `Application.Selector` | Domain construction queries records via Selector |
+| No direct DML in Service or Domain | All DML through Unit of Work |
+| No direct SOQL in Service | All queries through Selectors |
+
+## Testing with Mocks
+
+| Factory | setMock Signature |
+|---|---|
+| `Application.Selector` | `.setMock(SObjectType, fflib_ISObjectSelector)` |
+| `Application.Domain` | `.setMock(SObjectType, fflib_ISObjectDomain)` |
+| `Application.Service` | `.setMock(Type interfaceType, Object mockImpl)` |
+
+Mocking via `fflib-apex-mocks` eliminates DML/SOQL in unit tests.

package/skills/_reference/EXPERIENCE_CLOUD.md

@@ -0,0 +1,143 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_intro.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+<!-- WARNING: Web fetch of canonical URL failed (LWR client-side rendering). Facts below extracted from sf-experience-cloud skill. -->
+
+# Experience Cloud — Reference
+
+## Site Types
+
+| Site Type | Use Case | Key Features |
+|-----------|----------|-------------|
+| Customer Service | Self-service portal | Knowledge, Cases, Accounts |
+| Partner Central | Channel partner management | Leads, Opportunities, deal registration |
+| Build Your Own (LWR) | Custom branded site | Full customization, LWR framework |
+| Help Center | Public knowledge base | Knowledge articles, search, no login required |
+| Microsite | Event/campaign landing page | Lightweight, specific purpose |
+
+## LWR vs Aura-Based Sites
+
+| Aspect | LWR (Lightning Web Runtime) | Aura-Based |
+|--------|----------------------------|------------|
+| Performance | Faster, modern rendering | Heavier, legacy framework |
+| Components | LWC only | Aura + LWC |
+| SEO | Better (server-side rendering) | Limited |
+| Theming | CSS custom properties, SLDS | Theme panel, limited CSS |
+| CDN caching | Enabled by default | — |
+| Light DOM | Supported (`static renderMode = 'light'`) | Not supported |
+| Recommendation | New sites | Legacy/migration only |
+
+## User Types and Licensing
+
+| User Type | License | Access Level |
+|-----------|---------|-------------|
+| Customer Community | Community | Read/create own records only |
+| Customer Community Plus | Community Plus | Read/create + sharing rules |
+| Partner Community | Partner Community | Leads, Opps, deal registration |
+| Guest User | None (unauthenticated) | Public read access only |
+
+### External User Hierarchy (top = most access)
+
+| Level | Access Model |
+|-------|-------------|
+| Internal Users | Full org access (role hierarchy) |
+| Partner Users | Account-based + sharing rules |
+| Customer Plus Users | Account-based + sharing rules |
+| Customer Users | Own records only (no sharing rules) |
+| Guest Users | Public records only (no login) |
+
+## Guest User Security Rules
+
+| Rule | Detail |
+|------|--------|
+| NEVER grant Create, Edit, or Delete | On ANY object for guest profile |
+| ONLY grant Read | On objects explicitly needed for public display |
+| NEVER grant View All Data / Modify All Data | Critical security violation |
+| NEVER grant API access | To guest users |
+| OWD setting | Must NOT be "Public Read/Write" for guest-accessible objects |
+| Sharing rules | Use Guest User Sharing Rules (criteria-based) to control visible records |
+| Apex controllers | MUST use `with sharing` (enforces record-level sharing) |
+| SOQL in controllers | Use `WITH USER_MODE` (enforces CRUD/FLS) |
+| `with sharing` alone | Necessary but NOT sufficient; Guest User Sharing Rules must also be configured |
+
+## Sharing Model for External Users
+
+| Mechanism | How It Works |
+|-----------|-------------|
+| Account-Based Sharing | External User -> Contact -> Account -> shared records |
+| Sharing Sets | Grant access based on user's Account or Contact (admin config) |
+| All Customer Portal Users | Auto share group for all community users |
+| All Partner Users | Auto share group for all partner users |
+| Apex Managed Sharing | `CustomObject__Share` with `RowCause = Manual` |
+
+## LWC Targets for Experience Cloud
+
+| Target | Purpose |
+|--------|---------|
+| `lightningCommunity__Page` | Experience Cloud page |
+| `lightningCommunity__Default` | Default community context |
+| `lightningCommunity__Page_Layout` | Page layout region |
+
+### Community Context Imports
+
+| Import | Module | Returns |
+|--------|--------|---------|
+| `communityId` | `@salesforce/community/Id` | Current community/site ID |
+| `communityBasePath` | `@salesforce/community/basePath` | Site base URL path |
+| `isGuest` | `@salesforce/user/isGuest` | Boolean: guest user check |
+| `userId` | `@salesforce/user/Id` | Current user ID |
+
+## Navigation in Experience Cloud
+
+| Navigation Type | PageReference `type` | Key Attribute |
+|----------------|---------------------|---------------|
+| Record page | `standard__recordPage` | `recordId`, `actionName: 'view'` |
+| Named community page | `comm__namedPage` | `name` (e.g., `'Home'`, `'Contact_Support'`) |
+| External URL | `standard__webPage` | `url` |
+
+## CMS Content
+
+| Concept | Detail |
+|---------|--------|
+| CMS Workspace | Manages content types and items |
+| Publishing | Content items published to Channels (Sites) |
+| LWC API | `getContent` from `experience/cmsDeliveryApi` |
+| Wire params | `channelId`, `contentKeyOrId` |
+| Content fields | `data.title.value`, `data.body.value` |
+
+## Deployment Metadata Types
+
+| Metadata Type | Directory | Description |
+|---------------|-----------|-------------|
+| Network | `networks/` | Site definition (template, features, branding) |
+| ExperienceBundle | `experiences/` | Pages, routes, views, themes |
+| CustomSite | `sites/` | Site URL configuration |
+| NavigationMenu | `navigationMenus/` | Site navigation structure |
+| CommunityTemplateDefinition | `communityTemplateDefinitions/` | Template metadata |
+
+### Deployment Commands
+
+| Step | Command |
+|------|---------|
+| Retrieve Network | `sf project retrieve start --metadata Network:My_Community` |
+| Retrieve ExperienceBundle | `sf project retrieve start --metadata ExperienceBundle:My_Community1` |
+| Deploy experiences | `sf project deploy start --source-dir force-app/main/default/experiences` |
+| Deploy networks | `sf project deploy start --source-dir force-app/main/default/networks` |
+| Publish site | Via Experience Builder UI or `ConnectApi.Communities.publishCommunity(null, communityId)` in Apex |
+
+**Note:** `sf community publish` CLI command was removed in SF CLI v2. Publish via UI or Apex only.
+
+**Deploy order:** Network -> ExperienceBundle -> NavigationMenu -> dependent components (LWC, Apex, objects) -> Publish -> verify guest profile -> test with community user login.
+
+## Performance, Auth, and SEO
+
+| Area | Item | Detail |
+|------|------|--------|
+| Performance | CDN caching | Enabled by default (LWR sites) |
+| Performance | Lazy loading | `loading="lazy"` on images |
+| Performance | Apex caching | `@AuraEnabled(cacheable=true)` for read-only data |
+| Auth | Custom Login Page | Settings > Login & Registration > Login Page Type |
+| Auth | Self-Registration | Custom `Auth.RegistrationHandler` implementation |
+| Auth | Social Login | Google, Facebook, Apple, LinkedIn out-of-box; custom via Auth Provider |
+| SEO (LWR only) | Sitemap | Settings > SEO > Sitemap |
+| SEO (LWR only) | Semantic URLs | `/orders/12345` not `/s/detail/a01xx...` |
+| SEO (LWR only) | Multi-language | `/en/orders`, `/es/orders`; guest language from `Accept-Language` header |

package/skills/_reference/FLOW_PATTERNS.md

@@ -0,0 +1,113 @@
+# Flow Patterns — Reference
+
+> Source: <https://architect.salesforce.com/docs/architect/decision-guides/guide/record-triggered>
+> Source: <https://help.salesforce.com/s/articleView?id=platform.flow_considerations_limit_transaction.htm>
+> Source: <https://help.salesforce.com/s/articleView?id=platform.flow_concepts_bulkification.htm>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Flow Types
+
+| Type | Trigger | Context | Key Constraints |
+|---|---|---|---|
+| **Screen Flow** | User interaction | Runs in user context | Pauses transaction at each screen element |
+| **Record-Triggered (Before-Save)** | Record create/update | Same transaction, before commit | Assignment, Decision, Get Records, Loop only; no DML elements |
+| **Record-Triggered (After-Save)** | Record create/update/delete | Same transaction, after commit | Full element set; shares governor limits with before-save |
+| **Record-Triggered (Async)** | Record create/update | Separate transaction | Runs outside original transaction; own governor limits |
+| **Record-Triggered (Scheduled Path)** | Record field date/time | Separate transaction (batched) | Evaluates hours/days/minutes offset from a date field |
+| **Schedule-Triggered** | Cron schedule | Automated Process User | Runs as system; batch-processes matched records |
+| **Platform Event-Triggered** | Platform Event message | Automated Process User | Subscribes to event channel; own transaction per batch |
+| **Autolaunched (No Trigger)** | Apex, REST API, Process, button | Caller's context | Shares caller's transaction and governor limits |
+
+## Per-Transaction Limits (Shared with Apex)
+
+Flows execute under standard Apex governor limits. These are **per-transaction**, shared across all Flows and Apex in the same transaction.
+
+| Resource | Limit |
+|---|---|
+| SOQL queries | 100 (sync) / 200 (async) |
+| Records retrieved by SOQL | 50,000 |
+| DML statements | 150 |
+| Records processed by DML | 10,000 |
+| CPU time | 10,000 ms (sync) / 60,000 ms (async) |
+| Heap size | 6 MB (sync) / 12 MB (async) |
+| Callouts | 100 |
+| Executed flow elements per interview | No limit (API v57.0+); 2,000 (API v56.0 and earlier) |
+| Duplicate updates to same record in one batch | 12 |
+
+## General Org Limits
+
+| Resource | Limit |
+|---|---|
+| Flow versions per flow | 50 |
+| Active flows (Professional/Essentials editions) | 5 |
+| Paused flow interviews per org | 50,000 (removed in Winter '24+) |
+
+## Transaction Boundaries
+
+Flows break into a **new transaction** at these elements (resetting governor limits):
+
+- Screen elements
+- Scheduled Paths
+- Wait (Conditions / Amount of Time / Until Date)
+- Run Asynchronously path
+
+## Bulkification Rules
+
+Record-triggered flows auto-bulkify: when a batch of records fires the trigger, the runtime groups interviews and consolidates SOQL/DML where possible. Manual best practices:
+
+| Rule | Detail |
+|---|---|
+| **Never put SOQL inside a loop** | Get Records in a loop consumes 1 SOQL query per iteration; hits 100-query limit fast |
+| **Never put DML inside a loop** | Create/Update/Delete Records in a loop consumes 1 DML per iteration; hits 150-DML limit fast |
+| **Use collection variables** | Accumulate records in a collection inside the loop; perform single DML after the loop |
+| **Filter early** | Apply entry conditions and Get Records filters to minimize records processed |
+| **Before-save for same-record updates** | Avoids a second DML operation; most performant path for field updates on triggering record |
+
+## Error Handling Patterns
+
+| Pattern | How |
+|---|---|
+| **Fault path (per element)** | Connect a Fault Connector from any DML/callout element to a custom error handler |
+| **Fault email** | Configure fault paths to send admin email with `{!$Flow.FaultMessage}` and `{!$Flow.CurrentDateTime}` |
+| **Default fault behavior** | Without explicit fault path: rolls back transaction, shows unhandled-fault email to admin |
+| **Screen flow fault** | Display `{!$Flow.FaultMessage}` on a Screen element so the user sees the error |
+| **Rollback scope** | A fault on any after-save DML rolls back the entire transaction including before-save changes |
+
+## Flow vs Apex — Decision Matrix
+
+Based on Salesforce Architect decision guide using **automation density** as the heuristic.
+
+| Density | Automations per Object | Batch Size | Downstream DML Ops | Recommended |
+|---|---|---|---|---|
+| **Low** | < 15 | 1–200 records | 0–1 | Record-Triggered Flow |
+| **Medium** | 15–30 | Moderate batch | 2–4 | Hybrid: Flow + Invocable Apex |
+| **High** | > 30 | 2,000–10,000+ | 5+ | Apex Trigger Framework |
+
+### Use Flow When
+
+- Simple to moderate field updates, notifications, record creation
+- Scheduled processing relative to a date field (unique Flow strength)
+- Email alerts on record changes
+- Admin-maintainable logic without developer dependency
+
+### Use Apex When
+
+- Large data volumes or high-performance bulk processing
+- Complex data structures (Maps, Sets, nested collections)
+- Transaction control (savepoints, partial-success DML via `Database.update(records, false)`)
+- After-undelete context (not supported in Flow)
+- Recursive or self-referencing logic
+
+### Hybrid Pattern (Invocable Apex)
+
+- Flow handles entry criteria, routing, and orchestration
+- `@InvocableMethod` Apex handles compute-heavy operations
+- Invocable Apex only available in **after-save** context (not before-save)
+- Maintains visibility in Flow Trigger Explorer
+
+## Key Principles
+
+1. **One automation entry point per object** — avoid mixing Flow triggers and Apex triggers on the same object.
+2. **Before-save for same-record changes** — avoids extra DML, most performant path.
+3. **Avoid mega-flows** — split into focused, well-conditioned flows rather than one monolith.
+4. **Cascading automation shares limits** — Apex calling Flow (or vice versa) shares the same transaction governor limits.

package/skills/_reference/GOVERNOR_LIMITS.md

@@ -0,0 +1,77 @@
+# Governor Limits — Salesforce Reference
+
+> Last verified: API v66.0 (Spring '26)
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_gov_limits.htm>
+
+Salesforce governor limits prevent any single Apex transaction from monopolizing shared infrastructure. Hitting a limit throws `System.LimitException`, which **cannot be caught** — it terminates the transaction immediately.
+
+## Per-Transaction Limits
+
+| Resource | Synchronous | @future / Queueable | Batch execute() | Batch start/finish |
+|---|---|---|---|---|
+| **SOQL queries** | 100 | 200 | 200 | 200 |
+| **SOQL rows returned** | 50,000 | 50,000 | 50,000 | 50,000 |
+| **SOQL rows for `FOR UPDATE`** | 200 | 200 | 200 | 200 |
+| **DML statements** | 150 | 150 | 150 | 150 |
+| **DML rows** | 10,000 | 10,000 | 10,000 | 10,000 |
+| **CPU time (ms)** | 10,000 | 60,000 | 60,000 | 60,000 |
+| **Heap size** | 6 MB | 12 MB | 12 MB | 12 MB |
+| **Callouts** | 100 | 100 | 100 | 100 |
+| **Total callout time (s)** | 120 | 120 | 120 | 120 |
+| **Response size per callout** | 12 MB | 12 MB | 12 MB | 12 MB |
+| **Email invocations** | 10 | 10 | 10 | 10 |
+| **@future calls** | 50 | 0 (can't chain) | 50 | 50 |
+| **Queueable jobs** | 50 | 1 (chain in prod) | 1 | 1 |
+| **Push notifications** | 10 | 10 | 10 | 10 |
+| **Query cursor timeout (s)** | 600 | 600 | 600 | 600 |
+| **QueryLocator rows (Batch)** | N/A | N/A | 50M | N/A |
+
+## SOQL Cursor Limits (Spring '26+, API v66.0)
+
+| Constraint | Value |
+|---|---|
+| Max records per cursor | 50,000,000 |
+| Cursor lifetime (sync) | 10 minutes |
+| Cursor lifetime (async / Queueable) | 60 minutes |
+| `fetch()` max page size | 2,000 rows per call |
+| Max open cursors per transaction | 10 |
+
+## Org-Wide Limits (Not Per-Transaction)
+
+| Resource | Limit |
+|---|---|
+| Scheduled Apex jobs | 100 jobs scheduled at once |
+| Concurrent long-running requests (>5s) | 10 |
+| Batch jobs active (executing) | 5 concurrent; up to 100 in flex queue |
+| Platform event publishes per hour | 250,000 |
+
+## Limits Class — Programmatic Checking
+
+| Method | Returns |
+|---|---|
+| `Limits.getQueries()` / `Limits.getLimitQueries()` | SOQL queries used / limit |
+| `Limits.getQueryRows()` / `Limits.getLimitQueryRows()` | SOQL rows used / limit |
+| `Limits.getDmlStatements()` / `Limits.getLimitDmlStatements()` | DML statements used / limit |
+| `Limits.getDmlRows()` / `Limits.getLimitDmlRows()` | DML rows used / limit |
+| `Limits.getCpuTime()` / `Limits.getLimitCpuTime()` | CPU ms used / limit |
+| `Limits.getHeapSize()` / `Limits.getLimitHeapSize()` | Heap bytes used / limit |
+| `Limits.getCallouts()` / `Limits.getLimitCallouts()` | Callouts used / limit |
+| `Limits.getFutureCalls()` / `Limits.getLimitFutureCalls()` | @future calls used / limit |
+| `Limits.getEmailInvocations()` / `Limits.getLimitEmailInvocations()` | Emails used / limit |
+| `Limits.getQueueableJobs()` / `Limits.getLimitQueueableJobs()` | Queueable jobs used / limit |
+
+## Key Anti-Patterns
+
+| Anti-Pattern | Governor Impact | Correct Pattern |
+|---|---|---|
+| SOQL inside a loop | Exceeds 100 SOQL limit | Query once, store in Map |
+| DML inside a loop | Exceeds 150 DML limit | Collect records, single DML after loop |
+| Loading all fields when only ID needed | Heap exhaustion | SELECT only required fields |
+| Nested loops for matching | CPU time exhaustion | Map/Set lookup (O(1) vs O(n)) |
+| String concatenation in loops | Heap growth + CPU | List<String> + String.join() |
+
+## Test.startTest() / Test.stopTest()
+
+`Test.startTest()` resets all governor limit counters. Code between `startTest()` and `stopTest()` gets a fresh limit budget. Async work enqueued inside this block runs synchronously at `stopTest()`.
+
+Always test triggers with 200 records (the standard trigger batch size) to validate bulk safety.