scc-universal 1.1.0

package/skills/_reference/REPORTING_API.md

@@ -0,0 +1,143 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.api_analytics.meta/api_analytics/sforce_analytics_rest_api_intro.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+
+# Reporting & Analytics API — Salesforce Reference
+
+## Report Formats
+
+| Format | Grouping | Summary Fields | Use Case |
+|---|---|---|---|
+| Tabular | None | Column totals only | Flat lists, CSV export |
+| Summary | Up to 3 row groupings | Subtotals per group | Grouped data with subtotals |
+| Matrix | Row AND column groupings | Intersection summaries | Cross-tabulation / pivot |
+| Joined | Per-block groupings (up to 5 blocks) | Per-block summaries | Side-by-side comparisons |
+
+## Analytics REST API Endpoints
+
+Base path: `/services/data/v{version}/analytics`
+
+### Report Endpoints
+
+| Method | URI | Description |
+|---|---|---|
+| GET | `/reports` | List up to 200 recently viewed reports |
+| POST | `/reports` | Create a new report |
+| GET | `/reports/{id}` | Retrieve report metadata |
+| PUT | `/reports/{id}` | Save report changes |
+| DELETE | `/reports/{id}` | Delete a report |
+| GET | `/reports/{id}/describe` | Get report structure (fields, groupings, filters) |
+| GET | `/reports/{id}/instances` | List async report run instances |
+| POST | `/reports/{id}/instances` | Execute report asynchronously |
+| GET | `/reports/{id}/instances/{instanceId}` | Retrieve async execution results |
+
+### Dashboard Endpoints
+
+| Method | URI | Description |
+|---|---|---|
+| GET | `/dashboards` | List recently viewed dashboards |
+| GET | `/dashboards/{id}` | Retrieve dashboard metadata and status |
+| PUT | `/dashboards/{id}` | Update dashboard |
+| DELETE | `/dashboards/{id}` | Delete dashboard |
+| GET | `/dashboards/{id}/describe` | Dashboard structure info |
+| POST | `/dashboards/{id}/instances` | Execute async dashboard refresh |
+
+### Report Type Endpoints (API v39.0+)
+
+| Method | URI | Description |
+|---|---|---|
+| GET | `/reportTypes` | List available report types |
+| GET | `/reportTypes/{type}` | Get single report type detail |
+
+## API Limits
+
+| Limit | Value |
+|---|---|
+| Synchronous report runs per hour (org) | 500 |
+| Concurrent synchronous report requests | 20 |
+| Detail rows returned per run | 2,000 (sync); larger via async |
+| Async report instances listed | Up to 2,000 |
+| Async results retention | 24-hour rolling window |
+| Dashboard refreshes per hour (org) | 200 |
+| Custom field filters at runtime | Up to 20 |
+| Dashboard filters per dashboard | Up to 5 |
+
+## Apex Analytics API Classes
+
+| Class | Purpose |
+|---|---|
+| `Reports.ReportManager` | Run, describe, list reports |
+| `Reports.ReportResults` | Access fact map, metadata, totals |
+| `Reports.ReportMetadata` | Read/modify filters, groupings, columns |
+| `Reports.ReportExtendedMetadata` | Aggregate column info, detail columns |
+| `Reports.ReportFilter` | Set column, operator, value for runtime filter |
+| `Reports.ReportInstance` | Handle async report execution + status |
+| `Reports.ReportFactWithDetails` | Traverse row data + aggregates |
+| `Reports.SummaryValue` | Individual aggregate value (label + value) |
+| `Reports.ReportDetailRow` | Single row of detail data |
+| `Reports.ReportDataCell` | Single cell (label + value) |
+
+## Fact Map Keys
+
+| Key | Meaning |
+|---|---|
+| `T!T` | Grand total row and column |
+| `0!T` | First row grouping, all columns |
+| `T!0` | All rows, first column grouping |
+| `0!0` | First row grouping, first column grouping |
+| `{row}_{col}` | Specific intersection in matrix report |
+
+## Custom Report Type Relationship Patterns
+
+| Pattern | Description | SQL Equivalent |
+|---|---|---|
+| A with B | A must have related B records | INNER JOIN |
+| A with or without B | A included even without B | LEFT OUTER JOIN |
+| A with B, B with C | Three-level relationship | Double JOIN |
+
+Max objects in a custom report type: 4 (A-B-C-D chain).
+
+## Dashboard Component Types
+
+| Component | Best For | Data Source |
+|---|---|---|
+| Chart (bar, line, pie, donut, funnel) | Visual trends, comparisons | Source report |
+| Gauge | Progress toward a target value | Source report + target |
+| Metric | Single KPI number | Source report |
+| Table | Tabular data in dashboard | Source report |
+| Lightning Component | Custom interactive widget | Custom LWC |
+
+## Filter Types
+
+| Filter Type | Scope | Example |
+|---|---|---|
+| Standard Filter | Predefined (Show Me, Date) | "My accounts", "This quarter" |
+| Field Filter | Any field on report type | `Amount > 50000` |
+| Cross Filter | Related object existence | "Accounts WITH Opportunities" |
+| Row Limit | Cap result count | "Top 10 by Amount" |
+| Bucket Field | Group values without formula | Amount ranges: Small/Medium/Large |
+
+## Report Metadata Source Format
+
+```
+reports/<FolderName>/<ReportName>.report-meta.xml
+dashboards/<FolderName>/<DashboardName>.dashboard-meta.xml
+```
+
+## CLI Commands
+
+| Command | Purpose |
+|---|---|
+| `sf project retrieve start --metadata Report:<folder/name>` | Retrieve a report |
+| `sf project deploy start --source-dir force-app/main/default/reports` | Deploy reports |
+| `sf project retrieve start --metadata Dashboard:<folder/name>` | Retrieve a dashboard |
+
+## Performance Anti-Patterns
+
+| Anti-Pattern | Fix |
+|---|---|
+| Large object reports without date filters | Always add date range filter |
+| More than 3 cross-filters | Use custom report types instead |
+| Custom report type with 4+ objects | Limit to 2-3; use formula fields |
+| Dashboard with 20+ components | Keep to 10-12 focused components |
+| Hardcoded report IDs in Apex | Store DeveloperName in Custom Metadata |
+| Synchronous `runReport()` for >2,000 rows | Use `runAsyncReport()` or Batch Apex |

package/skills/_reference/SCRATCH_ORG_PATTERNS.md

@@ -0,0 +1,126 @@
+<!-- Source: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs.htm -->
+<!-- Last verified: API v66.0 — 2026-03-29 -->
+<!-- ⚠️ UNVERIFIED — Salesforce docs site returned JS-only content; facts sourced from Trailhead + skill knowledge -->
+
+# Scratch Org Patterns — Salesforce Reference
+
+## project-scratch-def.json Top-Level Fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `orgName` | string | No | Display name |
+| `edition` | string | Yes | See editions table below |
+| `hasSampleData` | boolean | No | Default `false` |
+| `language` | string | No | e.g. `en_US` |
+| `country` | string | No | e.g. `US` |
+| `adminEmail` | string | No | Admin user email |
+| `description` | string | No | Free-text |
+| `duration` | integer | No | 1–30 days; default 7 |
+| `features` | string[] | No | See features table |
+| `settings` | object | No | Nested settings objects |
+| `sourceOrg` | string | No | Org ID for org shape |
+| `snapshot` | string | No | Snapshot name (pilot) |
+
+## Supported Editions
+
+| Edition | Use Case |
+|---|---|
+| `Developer` | Standard development; most features available |
+| `Enterprise` | Testing enterprise-specific features |
+| `Partner Developer` | ISV / partner development |
+| `Group` | Testing simplified CRM features |
+
+## Common Features
+
+| Feature | Purpose |
+|---|---|
+| `API` | API access (always include) |
+| `AuthorApex` | Apex development |
+| `Communities` | Experience Cloud |
+| `ContactsToMultipleAccounts` | Multi-account contacts |
+| `CustomProfiles` | Custom user profiles |
+| `DebugApex` | Apex debugger |
+| `EnableSetPasswordInApi` | Set passwords via API |
+| `FieldService` | Field Service Lightning |
+| `LightningExperienceEnabled` | Lightning UI (always include) |
+| `LiveAgentEnabled` | Live Agent chat |
+| `MultiCurrency` | Multi-currency support |
+| `Omnichannel` | Omni-Channel routing |
+| `PersonAccounts` | Person Account record type |
+| `SalesUser` | Sales Cloud user features |
+| `ServiceUser` | Service Cloud user features |
+| `Sites` | Salesforce Sites |
+| `Territory2` | Territory Management 2.0 |
+| `Translation` | Translation Workbench |
+
+## Dev Hub Scratch Org Limits
+
+| Dev Hub Edition | Active Orgs | Daily Creates |
+|---|---|---|
+| Developer Edition | 6 | 3 |
+| Enterprise (paid) | 40 | 20 |
+| Unlimited (paid) | 100 | 40 |
+
+## Duration Strategy
+
+| Scenario | Duration | Definition File |
+|---|---|---|
+| CI pipeline | 1–3 days | Minimal (3 features: API, AuthorApex, DebugApex) |
+| Feature development | 7 days (default) | Full project scratch def |
+| Complex feature | Up to 30 days (max) | Full project scratch def |
+
+Minimal CI orgs spin up in ~2–3 min vs 5+ min for feature-rich orgs.
+
+## Core CLI Commands
+
+| Command | Purpose |
+|---|---|
+| `sf org create scratch --definition-file <path> --alias <name> --set-default --duration-days <n>` | Create scratch org |
+| `sf project deploy start --source-dir force-app --target-org <alias>` | Push source to org |
+| `sf project retrieve start --source-dir force-app --target-org <alias>` | Pull changes from org |
+| `sf project deploy preview --source-dir force-app --target-org <alias>` | Preview local changes not yet pushed |
+| `sf project retrieve preview --source-dir force-app --target-org <alias>` | Preview org changes not yet pulled |
+| `sf project deploy start --ignore-conflicts --target-org <alias>` | Force push (resolve conflict: local wins) |
+| `sf project retrieve start --ignore-conflicts --target-org <alias>` | Force pull (resolve conflict: org wins) |
+| `sf project reset tracking --target-org <alias>` | Reset corrupted source tracking |
+| `sf org list --verbose` | List all scratch orgs |
+| `sf org display --target-org <alias>` | Show org details and expiry |
+| `sf org delete scratch --target-org <alias> --no-prompt` | Delete and free allocation |
+| `sf org open --target-org <alias>` | Open org in browser |
+| `sf config set target-org <alias>` | Set default target org |
+
+## Org Shape & Snapshots
+
+| Feature | Status | Prerequisites |
+|---|---|---|
+| Org Shape | GA | "Org Shape" enabled in Dev Hub; source org = production or Developer Edition; user needs "Manage Org Shapes" permission |
+| Scratch Org Snapshots | Pilot/Beta | Requires Salesforce enablement; contact account team |
+
+## sfdx-project.json Key Fields
+
+| Field | Purpose |
+|---|---|
+| `packageDirectories[].path` | Source directory (e.g. `force-app`) |
+| `packageDirectories[].default` | Primary package directory |
+| `packageDirectories[].package` | Package name (for packaging) |
+| `packageDirectories[].versionNumber` | e.g. `1.0.0.NEXT` |
+| `packageDirectories[].dependencies` | Array of `{ package, versionNumber }` |
+| `namespace` | Package namespace (empty string = no namespace) |
+| `sourceApiVersion` | e.g. `66.0` |
+| `packageAliases` | Map of alias to Salesforce ID |
+
+> **Note:** `sfdcLoginUrl` is deprecated. Use `sf org login web --instance-url` instead.
+
+## Daily Dev Workflow Summary
+
+| Step | Command |
+|---|---|
+| 1. Auth Dev Hub (one-time) | `sf org login web --set-default-dev-hub --alias devhub` |
+| 2. Create scratch org | `sf org create scratch --definition-file config/project-scratch-def.json --alias feature-123 --set-default --duration-days 7` |
+| 3. Install dependencies | `sf package install --package 04t... --target-org feature-123 --wait 10` |
+| 4. Push source | `sf project deploy start --source-dir force-app --target-org feature-123` |
+| 5. Load test data | `sf apex run --file scripts/apex/create-test-data.apex --target-org feature-123` |
+| 6. Open org | `sf org open --target-org feature-123` |
+| 7. Pull declarative changes | `sf project retrieve start --source-dir force-app --target-org feature-123` |
+| 8. Deploy with tests | `sf project deploy start --source-dir force-app --test-level RunLocalTests --target-org feature-123` |
+| 9. Delete when done | `sf org delete scratch --target-org feature-123 --no-prompt` |

package/skills/_reference/SECURITY_PATTERNS.md

@@ -0,0 +1,127 @@
+# Security Patterns — Salesforce Reference
+
+> Last verified: API v66.0 (Spring '26)
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_security_guide.htm>
+
+## Salesforce Security Layers
+
+```
+Authentication & Authorization  →  Who can log in? (SSO, MFA, Login Flows)
+Object-Level Security (CRUD)    →  Can user create/read/edit/delete this object? (Profiles, Permission Sets)
+Field-Level Security (FLS)      →  Can user see/edit this field? (Profiles, Permission Sets)
+Record-Level Security (Sharing) →  Can user see THIS specific record? (OWD, Sharing Rules, Role Hierarchy)
+```
+
+The UI enforces all layers automatically. Apex and SOQL require explicit enforcement.
+
+## CRUD + FLS Enforcement
+
+| Approach | Min API | Enforces | Behavior on Violation |
+|---|---|---|---|
+| `WITH USER_MODE` (SOQL) | v56.0 | CRUD + FLS | Throws `QueryException` |
+| `AccessLevel.USER_MODE` (DML) | v56.0 | CRUD + FLS | Throws `DmlException` |
+| `WITH SECURITY_ENFORCED` (SOQL) | v48.0 | CRUD + FLS (reads) | Throws `QueryException` |
+| `Security.stripInaccessible()` | v48.0 | FLS only | Silently removes inaccessible fields |
+| Manual `isAccessible()` / `isCreateable()` checks | All | CRUD only (per call) | Developer-controlled |
+
+### Preferred: WITH USER_MODE / AccessLevel.USER_MODE
+
+```apex
+// SOQL — enforces CRUD + FLS for running user
+List<Account> accounts = [SELECT Id, Name FROM Account WITH USER_MODE];
+
+// DML — enforces CRUD + FLS for running user
+Database.insert(records, false, AccessLevel.USER_MODE);
+Database.update(records, false, AccessLevel.USER_MODE);
+Database.delete(records, false, AccessLevel.USER_MODE);
+```
+
+### stripInaccessible Warning
+
+`Security.stripInaccessible()` **silently removes** fields the user cannot access. Stripped fields become `null`. Always check `getRemovedFields()` before passing records downstream — otherwise `NullPointerException` can occur on fields assumed to be populated.
+
+## Sharing Keywords
+
+| Keyword | Behavior | Default For |
+|---|---|---|
+| `with sharing` | Enforces record-level sharing rules | User-facing classes (recommended default) |
+| `without sharing` | Bypasses sharing rules — sees all records | System batch jobs (must justify) |
+| `inherited sharing` | Adopts caller's sharing context | Utility/helper classes |
+| (none specified) | Defaults to `without sharing` for existing code | — (always specify explicitly) |
+
+### Decision Tree
+
+```
+User-facing code (LWC, VF, Aura, REST API)?  →  with sharing
+Utility class called by different contexts?    →  inherited sharing
+Scheduled batch / system processing?           →  without sharing (with justification)
+When in doubt?                                 →  with sharing
+```
+
+### Critical Rule
+
+Sharing context does **NOT** propagate to called classes. A `with sharing` class calling a `without sharing` class — the called method runs **without sharing**. Each class enforces its own declared keyword independently.
+
+## SOQL Injection Prevention
+
+| Approach | Security Level | When to Use |
+|---|---|---|
+| Static SOQL with `:bindVariable` | Safest | When query structure is fixed |
+| `Database.queryWithBinds()` | Safe | When query structure must be dynamic |
+| `String.escapeSingleQuotes()` | Legacy — adequate | When bind variables are not possible |
+| String concatenation | **VULNERABLE** | Never |
+
+### Safe Dynamic SOQL Pattern
+
+When dynamic fields/sort are needed, **whitelist-validate** every dynamic component against known-safe values. Only filter values should use bind variables.
+
+## XSS Prevention
+
+### Visualforce
+
+| Context | Encoding Function |
+|---|---|
+| HTML body | `{!HTMLENCODE(value)}` |
+| HTML attribute | `{!HTMLENCODE(value)}` |
+| JavaScript string | `{!JSENCODE(value)}` |
+| JS inside HTML attribute | `{!JSINHTMLENCODE(value)}` |
+| URL parameter | `{!URLENCODE(value)}` |
+| Auto-safe components | `<apex:outputField>`, `<apex:outputText escape="true">` |
+
+### LWC
+
+LWC templates auto-encode HTML by default. Avoid `element.innerHTML = userInput` — use `textContent` or `<lightning-formatted-rich-text>` instead.
+
+## Named Credentials & External Credentials
+
+| Rule | Detail |
+|---|---|
+| Use `callout:NamedCredential` prefix | Salesforce injects auth at runtime |
+| Never hardcode API keys/tokens in Apex | Use External Credentials (API v54.0+) |
+| Never hardcode Record IDs | Differ per org/sandbox |
+| Never hardcode endpoint URLs | Use Named Credentials or Custom Metadata |
+| Never log secrets via `System.debug` | Exposed in debug logs |
+
+## Security Review Checklist
+
+- [ ] All user-facing SOQL uses `WITH USER_MODE` or explicit CRUD/FLS checks
+- [ ] No SOQL string concatenation with user input
+- [ ] Service classes declared `with sharing` by default
+- [ ] `without sharing` justified and documented
+- [ ] No hardcoded IDs, credentials, or endpoint URLs
+- [ ] No `System.debug` of sensitive field values
+- [ ] DML for user-facing operations uses `AccessLevel.USER_MODE`
+- [ ] Callouts use Named Credentials / External Credentials
+- [ ] Configuration uses Custom Metadata or Custom Settings
+
+## Common Security Review Failures
+
+| Pattern | Risk | Fix |
+|---|---|---|
+| Missing CRUD check on DML | Unauthorized data access | `AccessLevel.USER_MODE` |
+| Missing FLS check on field access | Sensitive data exposure | `WITH USER_MODE` or `stripInaccessible` |
+| Dynamic SOQL with string concatenation | SOQL injection | Bind variables or `queryWithBinds` |
+| `without sharing` on user-facing class | Record-level bypass | `with sharing` |
+| Hardcoded credentials | Credential exposure | Named Credentials |
+| Sensitive data in debug logs | Data leakage | Remove debug statements |
+| `element.innerHTML = userInput` | XSS | `textContent` or sanitized component |

package/skills/_reference/SHARING_MODEL.md

@@ -0,0 +1,120 @@
+# Sharing Model — Reference
+
+> Source: <https://architect.salesforce.com/fundamentals/platform-sharing-architecture>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Apex Sharing Keywords
+
+| Keyword | Enforcement | Behavior |
+|---|---|---|
+| `with sharing` | User mode | Enforces OWD, role hierarchy, sharing rules, manual shares for running user |
+| `without sharing` | System mode | Ignores all sharing rules; returns all records the user has object-level access to |
+| `inherited sharing` | Caller's mode | Inherits sharing context of the calling class; defaults to `with sharing` if entry point |
+| _(omitted)_ | Varies | Runs as `without sharing` **unless** called from a `with sharing` class (then inherits) |
+
+**Special contexts:**
+
+| Context | Default Sharing Mode |
+|---|---|
+| Triggers | `without sharing` (system mode); call `with sharing` class to enforce |
+| Anonymous Apex | `with sharing` enforced by default |
+| Inner classes | Do **not** inherit outer class keyword; must declare their own |
+| Visualforce controllers | Standard controller: `with sharing`; custom controller: depends on keyword |
+
+## Organization-Wide Defaults (OWD)
+
+OWD sets the **most restrictive** baseline. Additional mechanisms only open access further.
+
+| Level | Visibility | Edit | Transfer |
+|---|---|---|---|
+| **Private** | Owner + hierarchy above | Owner + hierarchy above | Owner |
+| **Public Read Only** | All users | Owner + hierarchy above | Owner |
+| **Public Read/Write** | All users | All users | Owner |
+| **Public Read/Write/Transfer** | All users | All users | All users |
+| **Controlled by Parent** | Inherited from parent record | Inherited from parent record | N/A |
+
+### Object-Specific OWD Options
+
+| Object | Available OWD Levels |
+|---|---|
+| Account | Private, Public Read Only, Public Read/Write |
+| Contact | Controlled by Parent, Private, Public Read Only, Public Read/Write |
+| Opportunity | Private, Public Read Only, Public Read/Write |
+| Case | Private, Public Read Only, Public Read/Write, Public Read/Write/Transfer |
+| Lead | Private, Public Read Only, Public Read/Write, Public Read/Write/Transfer |
+| Campaign | Private, Public Read Only, Public Full Access |
+| Price Book | No Access, View Only, Use |
+| Custom Objects | Private, Public Read Only, Public Read/Write |
+
+- **External OWD:** Separate baseline for portal/community users; must be equal to or more restrictive than internal OWD.
+- **Grant Access Using Hierarchies:** Checkbox on custom objects (default on); when disabled, role hierarchy does not auto-grant access.
+
+## Record Access Mechanisms (Evaluation Order)
+
+| # | Mechanism | Description |
+|---|---|---|
+| 1 | **OWD** | Baseline for all users |
+| 2 | **Role Hierarchy** | Managers inherit subordinate record access (unless disabled for custom objects) |
+| 3 | **Owner-Based Sharing Rules** | Share records owned by role/group A with role/group B |
+| 4 | **Criteria-Based Sharing Rules** | Share records matching field criteria with role/group |
+| 5 | **Teams** | Account Teams, Opportunity Teams, Case Teams |
+| 6 | **Territory Management** | Access based on territory assignment |
+| 7 | **Manual Sharing** | Ad-hoc grant by record owner or admin; **removed on owner change** |
+| 8 | **Apex Managed Sharing** | Programmatic share rows with custom RowCause; **survives owner change** |
+| 9 | **Restriction Rules** | Filters that further **limit** visibility (2-5 per object) |
+
+## Sharing Rule Types
+
+| Type | Shares Based On | Access Granted | Limit |
+|---|---|---|---|
+| **Owner-Based** | Record owner (role, group, territory, queue) | Read Only or Read/Write | 300 per object |
+| **Criteria-Based** | Field values on record | Read Only or Read/Write | 50 per object |
+| **Guest User** | Field values (criteria-based) | Read Only **only** | Included in criteria limit |
+
+## Implicit Sharing (Non-Configurable)
+
+| Type | Behavior |
+|---|---|
+| **Parent Implicit** | Access to child (Contact, Opp, Case) grants read-only on parent Account |
+| **Child Implicit** | Account owner gets access to child records per role-level settings |
+
+## Share Object (`__Share`) Structure — `MyObject__Share` (custom) / `AccountShare` (standard)
+
+| Field | Description | Values |
+|---|---|---|
+| `ParentId` | ID of the record being shared | Record ID |
+| `UserOrGroupId` | User, Group, or Queue receiving access | User/Group ID |
+| `AccessLevel` | Level of access granted | `Read`, `Edit`, `All` |
+| `RowCause` | Reason for the share row | See table below |
+
+### RowCause Values
+
+| RowCause | Description |
+|---|---|
+| `Owner` | Record owner (system-managed) |
+| `Manual` | Manual sharing or Apex sharing on standard objects |
+| `Rule` | Sharing rule |
+| `ImplicitChild` | Child implicit sharing |
+| `ImplicitParent` | Parent implicit sharing |
+| `Team` | Team member sharing |
+| `TerritoryRule` | Territory-based sharing |
+| `Territory2Forecast` | Enterprise territory forecast sharing |
+| _(Custom reason)_ | Apex sharing reason (custom objects only) |
+
+- Custom `RowCause` values require Setup > Object > Apex Sharing Reasons
+- Only available on **custom objects**; standard objects must use `Manual`
+- `Manual` shares are **deleted on owner change**; custom reasons **survive** owner change
+- Insert/delete `__Share` rows in `without sharing` context
+- Sharing recalculation: implement `Database.Batchable` to rebuild shares at scale
+
+## Limits
+
+| Limit | Value |
+|---|---|
+| Roles (internal / external) | 25,000 / 100,000 |
+| Role hierarchy branch depth | 10 levels recommended |
+| Public groups / nesting depth | 100,000 / 5 levels |
+| Owner-based sharing rules per object | 300 |
+| Criteria-based sharing rules per object | 50 |
+| Restriction rules per object | 2-5 (edition-dependent) |
+| Ownership skew threshold | 10,000 records per user |

package/skills/_reference/SOQL_PATTERNS.md

@@ -0,0 +1,119 @@
+# SOQL Patterns — Reference
+
+> Source: <https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Query Selectivity
+
+The Force.com query optimizer evaluates every WHERE filter against selectivity thresholds. If no filter is selective, the query does a full table scan (and fails on objects >200 000 rows in triggers).
+
+### Selectivity Thresholds
+
+| Index Type | First 1M Records | Records Beyond 1M | Max Target Rows |
+|---|---|---|---|
+| Standard index | < 30% | < 15% | 1,000,000 |
+| Custom index | < 10% | < 5% | 333,333 |
+
+A filter is **selective** when targeted rows fall below the threshold. Multiple non-selective AND filters can combine to be selective if their intersection is below the threshold.
+
+### Optimizable vs Non-Optimizable Operators
+
+| Optimizable | Non-Optimizable |
+|---|---|
+| `=`, `<`, `>`, `<=`, `>=` | `!=`, `NOT` |
+| `IN`, `LIKE` (leading-% excluded) | `NOT IN`, `EXCLUDES` |
+| `INCLUDES` | `LIKE 'abc%def'` (leading wildcard) |
+
+### Standard Indexed Fields (Auto-Created)
+
+| Field | Notes |
+|---|---|
+| `Id` | Primary key |
+| `Name` | Compound name fields on standard objects |
+| `OwnerId` | Lookup to User/Group |
+| `RecordTypeId` | |
+| `CreatedDate` | |
+| `SystemModstamp` | Preferred over `LastModifiedDate` for filtering |
+| `LastModifiedDate` | Shares index with `SystemModstamp` internally |
+| Lookup / Master-Detail fields | All relationship foreign keys |
+| `Email` | On Contact and Lead only |
+| `Division` | If multi-division enabled |
+| External ID fields | Index auto-created when field marked External ID |
+
+**Non-indexable types:** Multi-select picklist, Long text area, Rich text area, Encrypted text, Non-deterministic formula fields.
+
+## Relationship Query Limits
+
+| Constraint | Limit |
+|---|---|
+| Child-to-parent levels (dot notation) | 5 |
+| Parent-to-child subqueries per query | 20 |
+| Child-to-parent relationships per query | 55 |
+| Records returned per subquery | 2,000 |
+| Parent-to-child nesting (REST/SOAP, API v58.0+) | 5 levels |
+| Parent-to-child nesting (Apex) | 2 levels |
+
+## Aggregate Query Rules
+
+| Function | Field Types Supported |
+|---|---|
+| `COUNT()` | All (no field argument) |
+| `COUNT(field)` | All except long text, rich text |
+| `COUNT_DISTINCT(field)` | All except long text, rich text |
+| `SUM(field)` | Number, Currency, Percent |
+| `AVG(field)` | Number, Currency, Percent |
+| `MIN(field)` | Number, Currency, Percent, Date, Datetime |
+| `MAX(field)` | Number, Currency, Percent, Date, Datetime |
+
+| Constraint | Value |
+|---|---|
+| Max grouped rows returned | 2,000 |
+| Max fields in `GROUP BY` | 3 (with ROLLUP/CUBE) |
+| `GROUP BY ROLLUP` | Supported (API v18.0+) |
+| `GROUP BY CUBE` | Supported (API v18.0+) |
+| `HAVING` | Filters on aggregate result only |
+| `TYPEOF` with GROUP BY | Not supported |
+
+## SOQL Keyword Reference
+
+Core syntax: `SELECT ... FROM ... WHERE ... GROUP BY ... HAVING ... ORDER BY ... [ASC|DESC] [NULLS FIRST|LAST] LIMIT n OFFSET n` (OFFSET max 2,000).
+
+### Scope, Security & Locking Clauses
+
+| Clause | Purpose | Constraints |
+|---|---|---|
+| `FOR UPDATE` | Row-level pessimistic lock (10 s timeout) | No ORDER BY; no aggregates; max 200 rows |
+| `FOR VIEW` | Updates `RecentlyViewed` | Informational; no query behavior change |
+| `FOR REFERENCE` | Updates `RecentlyViewed` for related records | Informational; no query behavior change |
+| `WITH SECURITY_ENFORCED` | Enforce FLS in SELECT (legacy) | SELECT only; throws on violation |
+| `WITH USER_MODE` | Full CRUD + FLS + sharing (recommended) | Works in DML too; API v60.0+ |
+| `WITH SYSTEM_MODE` | Bypass all security | Works in DML too; API v60.0+ |
+| `USING SCOPE scope` | Restrict record scope | Values: `Everything`, `Mine`, `Queue`, `Delegated`, `MyTerritory`, `MyTeamTerritory`, `Team` |
+
+### TYPEOF (Polymorphic Relationships)
+
+Syntax: `TYPEOF field WHEN Type1 THEN fields WHEN Type2 THEN fields ELSE fields END`. Filter with `WHERE field.Type IN (...)`. Cannot combine with: `GROUP BY`, `ROLLUP`, `CUBE`, `HAVING`, `COUNT()`.
+
+## SOQL Cursor Pagination (API v66.0+)
+
+| Constraint | Value |
+|---|---|
+| Max records per cursor | 50,000,000 |
+| `fetch()` max page size | 2,000 rows |
+| Max `fetch()` calls per transaction | 10 |
+| Max cursors per day (org-wide) | 10,000 |
+| Max rows per day (org-wide, aggregate) | 100,000,000 |
+| Cursor lifetime (sync) | 10 minutes |
+| Cursor lifetime (async) | 60 minutes |
+
+API: `Database.getCursor(soqlString)` returns `Database.Cursor`. Use `cursor.fetch(offset, count)` and `cursor.getNumRecords()`.
+
+## SOQL Governor Limits (Quick Ref)
+
+| Resource | Synchronous | Asynchronous |
+|---|---|---|
+| SOQL queries per transaction | 100 | 200 |
+| Total rows returned | 50,000 | 50,000 |
+| `FOR UPDATE` max rows | 200 | 200 |
+| OFFSET max value | 2,000 | 2,000 |
+| QueryLocator rows (Batch) | N/A | 50,000,000 |