@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/platform-salesforce-connect-adapter-generate/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: platform-salesforce-connect-adapter-generate
+description: "Custom Apex adapter generation for Salesforce Connect — connects any external REST API to Salesforce as live, queryable External Objects without ETL or data copying. TRIGGER when: user wants to connect a non-standard external API to Salesforce, asks to write a DataSource.Provider or DataSource.Connection, wants to surface external data as Salesforce records, says \"connect my API to Salesforce without copying data\", or asks whether custom Apex is the right approach for any system. Also trigger on: \"custom adapter\", \"ExternalId field\", \"DataSource namespace\". DO NOT TRIGGER when: user is configuring a standard adapter they already have and is NOT asking about custom Apex (e.g., OData endpoint setup, Snowflake connector config). DO NOT TRIGGER when: user wants to copy or bulk-sync data — use platform-data-manage. DO NOT TRIGGER for Apex callouts outside Connect — use platform-apex-generate or integration-connectivity-generate."
+metadata:
+  version: "1.0"
+  minApiVersion: "66.0"
+  accessCheck:
+    - type: license
+      value: SalesforceConnect
+  domains:
+    - Platform
+  relatedSkills:
+    - integration-connectivity-generate
+    - platform-apex-generate
+    - platform-data-manage
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Salesforce Connect — Custom Apex Adapter
+
+Route the user through building a complete custom Salesforce Connect Apex adapter: two Apex classes, metadata deployment, and registration. Do not guess at the user's API shape — ask before generating.
+
+## Scope
+
+**In scope:** Generating `DataSource.Connection` and `DataSource.Provider` Apex classes, Named Credential metadata, deployment via sf CLI, and step-by-step Setup registration guidance for any REST API.
+
+**Out of scope:** Configuring standard adapters (OData, Snowflake, GraphQL — those have their own flows). Generating the External Data Source metadata file (not deployable via sf CLI — must be registered manually in Setup). Writing Apex that calls external APIs outside the Salesforce Connect framework (use [platform-apex-generate](../platform-apex-generate/SKILL.md) or [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md)).
+
+## Before starting
+
+Confirm two things. If either is missing, ask before proceeding.
+
+**1. Is this actually a Salesforce Connect use case?**
+
+| The user wants to… | Right tool |
+|---|---|
+| Query external data live without copying it — read-only or read-write, appears as Salesforce records | **This skill** |
+| Copy or sync data into Salesforce on a schedule | [platform-data-manage](../platform-data-manage/SKILL.md) |
+| Connect to OData, GraphQL, DynamoDB, Athena, or Cross-Org | Standard adapter setup — no Apex needed, different flow |
+| Connect to Snowflake via Salesforce's native Snowflake adapter (direct Snowflake protocol) | Built-in Snowflake adapter — no Apex needed |
+| Access Snowflake (or any database) data via a REST or HTTP API | **This skill** — Snowflake REST endpoint → custom Apex adapter |
+| Call an external API from Apex or Flow logic | [platform-apex-generate](../platform-apex-generate/SKILL.md) or [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md) |
+| Expose Salesforce data to an external system | [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md) |
+| Receive real-time pushed data or subscribe to external events | Not Salesforce Connect — Connect is pull-only. Use Platform Events or Change Data Capture instead |
+| Sync or copy data for analytics or bulk processing | Data Cloud or ETL — Connect is zero-copy virtualization only |
+
+If the user has a standard adapter available, tell them — writing a custom adapter when a standard one fits is unnecessary work.
+
+**2. Do they have a Salesforce Connect license?**
+
+A custom adapter requires a Salesforce Connect license (one license per External Data Source). Without it, the External Data Source menu won't show the Apex option. If the user doesn't have one, tell them before going further.
+
+---
+
+## Default org context (when running locally)
+
+If the user does not specify an org alias, use `demo-org`.
+If the user does not specify an SFDX project path, use `~/salesforce-connect-apex-skill/sfconnect-demo/`.
+These are the defaults for local testing — always override if the user specifies their own.
+
+---
+
+## Collect inputs before generating
+
+Never generate code without these. If any are missing, ask:
+
+| Input | Why it matters |
+|---|---|
+| API name and what it does | Names the classes and sets context for field mapping |
+| Base URL | Becomes the Named Credential endpoint |
+| Auth type | Determines Named Credential setup and `getAuthenticationMode()` |
+| Key GET endpoint(s) + sample response | Defines the External Object schema — field names, types, nesting |
+| Write support needed? | Determines whether to implement `upsertRows()` and `deleteRows()` |
+| Org type (DE, scratch, sandbox) | Sets `apiVersion` in `.cls-meta.xml` |
+
+If the user provides an OpenAPI spec, extract:
+- All GET endpoints returning arrays → each becomes a `DataSource.Table`
+- Response object properties → `DataSource.Column` entries
+- `id` / `uuid` / primary key → map to `ExternalId`
+- Property types → use the field type mapping table below
+
+---
+
+## What to build
+
+Every custom Salesforce Connect adapter is exactly two Apex classes.
+
+### DataSource.Connection
+Handles communication with the external API. Exact signatures:
+
+```apex
+override global DataSource.TableResult query(DataSource.QueryContext context)
+override global List<DataSource.TableResult> search(DataSource.SearchContext context)
+
+// Write support — only if API supports it:
+global override List<DataSource.UpsertResult> upsertRows(DataSource.UpsertContext context)
+global override List<DataSource.DeleteResult> deleteRows(DataSource.DeleteContext context)
+```
+
+Key distinction: `query()` always operates on **one** table (`QueryContext` has a single `TableSelection`). `search()` can operate on **multiple** tables simultaneously (`SearchContext` has multiple `TableSelection` instances) — handle each in a loop and return a result per table.
+
+### DataSource.Provider
+Declares the adapter's capabilities and schema to Salesforce. Required methods:
+
+- `getAuthenticationMode()` — return `ANONYMOUS` for public APIs; `NAMED_PRINCIPAL` or `PER_USER` for authenticated APIs
+- `getCapabilities()` — declare `QUERY`, `SEARCH`; add `ROW_CREATE`, `ROW_UPDATE`, `ROW_DELETE` only if implementing writes
+- `getConnection(ConnectionParams params)` — return `new YourConnection(params)`
+- `sync()` — called when the user clicks "Validate and Sync" in Setup; returns `List<DataSource.Table>` defining the External Object schema and columns
+
+The Provider class appears in Salesforce Setup as **`Custom-[ClassName]`** under the External Data Source type dropdown.
+
+**Critical:** whenever you edit the Connection class, you must resave the Provider class too — even with no changes. Otherwise the adapter disappears from the Type picklist and existing External Object tabs break.
+
+---
+
+## Field type mapping
+
+| External API type | Use this |
+|---|---|
+| string / text | `DataSource.DataType.TEXT_TYPE` |
+| number / integer / decimal | `DataSource.DataType.NUMBER_TYPE` |
+| boolean | `DataSource.DataType.BOOLEAN_TYPE` |
+| date (ISO 8601) | `DataSource.DataType.DATE_TYPE` |
+| datetime / timestamp | `DataSource.DataType.DATETIME_TYPE` |
+| URL | `DataSource.DataType.URL_TYPE` |
+| email | `DataSource.DataType.EMAIL_TYPE` |
+| phone | `DataSource.DataType.PHONE_TYPE` |
+| enum / picklist | `TEXT_TYPE` — map enum values as strings |
+| nested object / JSON blob | Flatten to scalar fields, or `TEXT_TYPE` and parse in `query()` |
+| array | Derive a count field (`NUMBER_TYPE`), or flatten first-element fields |
+| string > 255 chars | Long text area — do not truncate; Salesforce maps it automatically |
+
+Every `DataSource.Table` **must** include these columns:
+```apex
+DataSource.Column.text('ExternalId', 255)  // unique key from external system — REQUIRED
+DataSource.Column.text('Name', 255)        // display label shown in Salesforce UI — REQUIRED
+DataSource.Column.url('DisplayUrl')        // link to the record in the external system — recommended
+```
+Missing `ExternalId` is the most common reason an adapter deploys but records don't appear.
+`DisplayUrl` enables the clickable link icon in list views — populate it with the external record's URL.
+
+---
+
+## Scenarios
+
+Four scenarios: (1) public read-only, (2) authenticated API key/OAuth, (3) read-write with upsert/delete, (4) paginated API. Full code patterns for each are in [`references/scenarios.md`](references/scenarios.md).
+
+**Key differences by scenario:**
+
+| Scenario | Auth mode | Extra capabilities | Named Credential |
+|----------|-----------|-------------------|-----------------|
+| Public read-only | `ANONYMOUS` | `QUERY`, `SEARCH` | Deploy as metadata |
+| Authenticated | `NAMED_PRINCIPAL` or `PER_USER` | `QUERY`, `SEARCH` | Create manually in Setup — never deploy credentials as metadata |
+| Read-write | `ANONYMOUS` or auth | Add `ROW_CREATE`, `ROW_UPDATE`, `ROW_DELETE` | Per above |
+| Paginated | Any | Any | Use `context.tableSelection.numberOfRows` (default 500 if null); no automatic `queryMore` |
+
+---
+
+## How to verify the adapter is working
+
+### Option 1 — SOQL via sf CLI (fastest, no UI needed)
+```bash
+sf data query \
+  --query "SELECT ExternalId, Name__c FROM [YourObject]__x LIMIT 5" \
+  --target-org [org-alias]
+```
+If rows come back, the adapter is working. If 0 rows, check the troubleshooting steps below.
+
+### Option 2 — Visualforce page (best for demos, works on any org)
+
+Deploy a Visualforce page + Apex controller that queries `[Object]__x` and renders rows in an `apex:pageBlockTable`. Open at `[orgUrl]/apex/[PageName]`. More reliable than list views for testing — bypasses tab requirements, deployment status, and filter issues. See [`references/scenarios.md`](references/scenarios.md) for the standard template.
+
+### Option 3 — List view (standard UI, but requires extra steps)
+
+For the list view to show records, all four of these must be true:
+1. External Object Deployment Status = **Deployed** (Object Manager → Edit)
+2. A tab exists for the External Object (Setup → Tabs → Custom Object Tabs → New)
+3. List view filter is set to **All** (not "Recently Viewed")
+4. Remote Site Setting exists for the external API URL
+
+### Troubleshooting: 0 records with no error
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| SOQL returns 0 | Remote Site Setting missing | Setup → Remote Site Settings → New |
+| SOQL returns 0 | Named Credential not found | Setup → Named Credentials → confirm `callout:` name matches exactly |
+| SOQL returns 0 | Org proxy blocks external URLs | Use loopback pattern or switch to an external DE org |
+| List view shows 0 | Deployment Status = In Development | Object Manager → [Object]__x → Edit → Deployed |
+| List view shows 0 | Filter is "Recently Viewed" | Change filter to "All" |
+| App Launcher shows nothing | No tab created | Setup → Tabs → Custom Object Tabs → New |
+
+---
+
+## What the agent deploys vs. what the developer does manually
+
+### Agent deploys (one `sf project deploy start` command)
+
+| File | Notes |
+|---|---|
+| `classes/[API]DataSourceConnection.cls` + meta | Always |
+| `classes/[API]DataSourceProvider.cls` + meta | Always |
+| `namedCredentials/[API].namedCredential-meta.xml` | **Public APIs only** — skip for any API requiring credentials |
+
+**Do NOT generate `externalDataSources/[API].externalDataSource-meta.xml`.** The External Data Source must be registered manually in Setup after deploying the Apex classes. The `sf project deploy start` command cannot deploy custom Apex External Data Sources — the sf CLI will error with "Could not infer a metadata type." Tell the user to go to Setup → External Data Sources → New after deployment.
+
+Correct NamedCredential XML format (no `<name>` element — the API name comes from the filename):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>My API</label>
+    <endpoint>https://api.example.com</endpoint>
+    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
+    <allowMergeFieldsInHeader>false</allowMergeFieldsInHeader>
+    <generateAuthorizationHeader>false</generateAuthorizationHeader>
+    <principalType>Anonymous</principalType>
+    <protocol>NoAuthentication</protocol>
+</NamedCredential>
+```
+
+Deploy command:
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/ \
+  --target-org [org-alias]
+```
+
+### Developer does manually (always — no metadata equivalent exists)
+
+**Validate and Sync** triggers a live call to the external API to discover its schema and create External Object definitions. This cannot be scripted.
+
+```text
+Setup → External Data Sources → [your data source] → Validate and Sync
+Check the box next to each External Object → Sync
+App Launcher → search [External Object name] → confirm records appear
+```
+
+Always end with: "Deployment complete. One step left: open the External Data Source in Salesforce Setup and click Validate and Sync."
+
+---
+
+## Error handling rules
+
+Never let an exception propagate uncaught out of `query()` — Salesforce shows a generic error to the user with no context.
+
+| Situation | Handle it by |
+|---|---|
+| HTTP 401 | `throw new DataSource.OAuthTokenExpiredException()` |
+| HTTP 429 / rate limit | Return empty rows; log via `System.debug()` |
+| HTTP 500 or network error | Return empty rows; do not rethrow |
+| Null field in response | `record.get('field') != null ? (String) record.get('field') : ''` |
+| Nested JSON that won't flatten | Return raw JSON string as a TEXT_TYPE field rather than failing the whole query |
+
+---
+
+## Governor limits
+
+- Max 100 HTTP callouts per transaction — each `query()` call is one transaction
+- Heap limit 6 MB (synchronous) — don't deserialize massive payloads; use server-side pagination
+- CPU limit 10 seconds — avoid nested loops over large response arrays
+
+---
+
+## Setup prerequisites — in this exact order
+
+### 1. Deploy Apex classes first
+The `Salesforce Connect: Custom (Developed with Apex)` type only appears in the External Data Source type dropdown **after** at least one `DataSource.Provider` subclass is deployed in the org.
+
+This is not a permissions issue. It is a dependency — Salesforce discovers available Provider classes at runtime. No deployed Provider = no option in the dropdown.
+
+**Correct sequence — always:**
+1. Deploy Apex classes first (`sf project deploy start`)
+2. Then go to Setup → External Data Sources → New → the Custom Apex type will appear
+
+If the user says "I don't see the Custom Apex option in the dropdown", the answer is: deploy the classes first, then come back to Setup.
+
+### 2. Add Remote Site Setting before testing
+
+The external API's base URL must be whitelisted or callouts fail silently — `query()` returns empty rows with no exception, no error message. Deploy as metadata or add at Setup → Remote Site Settings → New.
+
+### 3. After Validate and Sync — set Deployment Status to Deployed
+
+After Validate and Sync, Salesforce creates the External Object with status **"In Development"**. Records return 0 results in list views and SOQL until this is changed. No error is shown — another silent failure.
+
+```text
+Setup → Object Manager → [YourObject]__x → Edit
+  Deployment Status → Deployed → Save
+```
+
+Always tell the user this step after Validate and Sync completes.
+
+### 4. Create a tab to surface the External Object in App Launcher
+
+External Objects are invisible in the UI without a tab. Create one at:
+```text
+Setup → Tabs → Custom Object Tabs → New → select [YourObject]__x → Save
+```
+
+### Also required
+- **Salesforce Connect license** — without it, all Connect adapter types including OData are hidden. If the user sees OData and Cross-Org in the dropdown, the license is already active.
+
+---
+
+## Anti-patterns
+
+| Don't | Why | Do |
+|---|---|---|
+| Generate code without knowing the API shape | Wrong field types, wrong ExternalId mapping, broken adapter | Ask for API name, base URL, auth type, sample response first |
+| Deploy ExternalDataSource as metadata | Not a deployable metadata type — sf CLI will error | Register the External Data Source manually in Setup after deploying the Apex classes |
+| Use `upsertRow()` or `deleteRow()` (singular) | These methods don't exist — compile error | Use `upsertRows()` and `deleteRows()` (plural) |
+| Put `sync()` only on Provider | On some API versions `sync()` must be on Connection — compiler will tell you | Implement `sync()` on Connection; remove from Provider if it errors |
+| Hardcode the API URL in Apex | Credentials exposed in source, callout blocked | Always use `callout:NamedCredentialName` |
+| Return a single `DataSource.TableResult` from `search()` | `search()` returns `List<DataSource.TableResult>` — compile error | Loop over `context.tableSelections` and return one result per table |
+| Skip COUNT handling in `query()` | List views fire COUNT queries; without detection they return wrong results | Check `columnsSelected[0].aggregation == DataSource.QueryAggregation.COUNT` |
+| Leave External Object in "In Development" | Records return 0 with no error — invisible to the user | After Validate and Sync: Object Manager → [Object]__x → Edit → Deployed |
+| Skip the Remote Site Setting | Callout fires silently, returns empty rows, no exception | Deploy `remoteSiteSettings/[API].remoteSite-meta.xml` or add manually in Setup |
+
+---
+
+## Before shipping
+
+Confirm: inputs collected (API name, URL, auth, sample response, write support) → code has `sync()` + `query()` + `search()` on Connection, `getCapabilities()` + `getConnection()` on Provider, `ExternalId` and `nameColumn` on every table, COUNT handling in `query()`, mock data for tests, `callout:` prefix on all endpoints → both `.cls-meta.xml` files generated → deploy command given → post-deploy steps communicated (Named Credential setup, Remote Site Setting, External Data Source registered, Validate and Sync, Deployment Status → Deployed, tab created).
+
+---
+
+## Reference examples
+
+See [`references/official-examples.md`](references/official-examples.md) for annotated study of the official Salesforce Connect adapter examples — GitHub Issues (full DML, picklist, cross-table relationships), Google Drive (OAuth + test mock), Google Books (pagination), StackOverflow (multiple tables), and Loopback (filter translation). Read before generating for a new user.
+
+---
+
+## Project setup — if the developer has no SFDX project yet
+
+Before deploying, they need a project structure. If one doesn't exist, generate it first:
+
+```bash
+sf project generate --name my-adapter --output-dir .
+cd my-adapter
+```
+
+This creates `force-app/main/default/classes/` and the required `sfdx-project.json`. All generated files go into this structure. The developer does not need VS Code, Agentforce Vibes, or any Salesforce IDE — just `sf` CLI installed and an org authenticated via `sf org login web --alias my-org`.
+
+This skill works with **any coding agent** that can read a context file — Claude Code, Cursor, Windsurf, GitHub Copilot, or any agent with the SKILL.md loaded. No Salesforce MCP server, no Agentforce Vibes, no internal Salesforce tooling required.
+
+---
+
+## Output format
+
+Generate files in this order, then give the deploy command:
+
+1. `force-app/main/default/classes/[API]DataSourceConnection.cls`
+2. `force-app/main/default/classes/[API]DataSourceProvider.cls`
+3. `force-app/main/default/classes/[API]DataSourceConnection.cls-meta.xml`
+4. `force-app/main/default/classes/[API]DataSourceProvider.cls-meta.xml`
+5. `force-app/main/default/namedCredentials/[API].namedCredential-meta.xml` — public APIs only
+
+One-line comment at top of each Apex class: `// Salesforce Connect custom adapter for [API name]`
+No other inline comments unless a logic choice is non-obvious.

package/skills/platform-salesforce-connect-adapter-generate/references/official-examples.md

@@ -0,0 +1,69 @@
+# Official Salesforce Connect Adapter Examples
+
+Study these before generating code for a user. Each example demonstrates distinct patterns — don't generate from memory alone.
+
+## GitHub Issues adapter — read this one first
+
+The most complete example, built by the Salesforce Connect team as the definitive reference. It is the only official example with:
+- Full DML: create, update, delete (`upsertRows` + `deleteRows`)
+- Date fields and picklist / multi-picklist fields
+- Two related external object tables (Issues + Comments) with cross-table relationships
+- `DataSource.Column.externalLookup()` and `DataSource.Column.indirectLookup()`
+- `DataSource.QueryUtils.process(context, rows)` — handles ORDER BY and LIMIT automatically; use this instead of manual sorting
+
+Read it: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_connector_example_github_issues.htm
+
+Key patterns to bring forward:
+
+```apex
+// Let QueryUtils handle sorting and limiting — don't do it manually
+return DataSource.TableResult.get(context,
+    DataSource.QueryUtils.process(context, rows));
+
+// Cross-object relationship to another external object
+DataSource.Column.externalLookup('issue_number', 'GithubIssues__x')
+
+// Indirect lookup — link external object to a standard Salesforce object
+DataSource.Column.indirectLookup('repository_url', 'Product2', 'Repository__c')
+
+// Picklist column
+DataSource.Column.picklist('State', new List<String>{'Open', 'Closed'})
+```
+
+## Other official examples — each demonstrates one specific feature
+
+| Example | The one thing it's best for | Unique pattern |
+|---------|----------------------------|----------------|
+| **GitHub (users)** | Indirect lookup to a standard object | `DataSource.Column.indirectLookup('login', 'Contact', 'github_username__c')` — links external records to Contact via a custom external ID field |
+| **Google Drive** | OAuth per-user auth + test mock pattern | `System.Test.isRunningTest()` returns static `mockResponse` to avoid real callouts in tests; `'Authorization', 'Bearer '+ connectionInfo.oauthToken` for OAuth |
+| **Google Books** | Pagination against an API with a hard page-size cap | Explicit loop accumulating batches: `data.addAll(getData(url + startIndex))` incrementing offset by 40; `column.sortable = false` for non-sortable fields |
+| **StackOverflow** | Multiple tables with external lookup between them | `DataSource.Column.externalLookup('owner_id', 'stackoverflowUser__x')` linking child posts to parent user external object |
+| **Loopback** | Filter translation from `DataSource.Filter` to SOQL | `getSoqlFilter()` recursively maps all `FilterType` values (EQUALS, LESS_THAN, STARTS_WITH, AND_, OR_, NOT_ etc.) to SOQL operators — use this when the user's API supports server-side filtering |
+| **GitHub Issues** | Full DML + picklist + date + two related tables | See primary reference above |
+
+Base URL: `https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/`
+
+## Test mock pattern (from Google Drive)
+
+Use this in all generated adapters to make them testable:
+
+```apex
+if (System.Test.isRunningTest()) {
+    return mockResponse; // return static test data
+}
+Http http = new Http();
+// ... real callout
+```
+
+## Filter translation pattern (from Loopback)
+
+Use this when pushing WHERE clause conditions to the external API:
+
+```apex
+// Access filter from query context
+DataSource.Filter filter = context.tableSelection.filter;
+// filter.type is one of: EQUALS, NOT_EQUALS, LESS_THAN, GREATER_THAN,
+// LESS_THAN_OR_EQUAL_TO, GREATER_THAN_OR_EQUAL_TO, STARTS_WITH, ENDS_WITH,
+// LIKE_, AND_, OR_, NOT_
+// filter.columnName, filter.columnValue, filter.subfilters (for compound)
+```

package/skills/platform-salesforce-connect-adapter-generate/references/scenarios.md

@@ -0,0 +1,187 @@
+# Adapter Scenarios — Code Patterns
+
+## Scenario 1 — Public REST API, read-only
+
+**What to generate:**
+- `[API]DataSourceConnection.cls` — `query()` and `search()`, no upsert/delete
+- `[API]DataSourceProvider.cls` — `ANONYMOUS` auth, `QUERY` + `SEARCH` capabilities
+- `[API].namedCredential-meta.xml` — `NoAuthentication`, anonymous principal
+
+Do NOT generate `externalDataSources/[API].externalDataSource-meta.xml` — register the External Data Source manually in Setup after deploying the Apex classes.
+
+**search() pattern** — must return `List<DataSource.TableResult>`, one result per table:
+```apex
+override global List<DataSource.TableResult> search(DataSource.SearchContext context) {
+    List<DataSource.TableResult> results = new List<DataSource.TableResult>();
+    for (DataSource.TableSelection tableSelection : context.tableSelections) {
+        results.add(queryTable(tableSelection));
+    }
+    return results;
+}
+```
+
+**query() pattern:**
+```apex
+// Handle COUNT() — return count without fetching all rows
+if (!context.tableSelection.columnsSelected.isEmpty() &&
+    context.tableSelection.columnsSelected[0].aggregation == DataSource.QueryAggregation.COUNT) {
+    List<Map<String, Object>> countRow = new List<Map<String, Object>>();
+    countRow.add(new Map<String, Object>{ 'count' => 0 }); // replace 0 with real count
+    return DataSource.TableResult.get(context, countRow);
+}
+
+Http http = new Http();
+HttpRequest req = new HttpRequest();
+Integer pageSize = context.tableSelection.numberOfRows != null
+    ? context.tableSelection.numberOfRows : 500;
+req.setEndpoint('callout:YourNamedCredential/path?limit=' + pageSize);
+req.setMethod('GET');
+req.setTimeout(10000);
+HttpResponse res = http.send(req);
+
+if (res.getStatusCode() == 200) {
+    List<Object> items = (List<Object>) JSON.deserializeUntyped(res.getBody());
+    List<Map<String, Object>> rows = new List<Map<String, Object>>();
+    for (Object item : items) {
+        Map<String, Object> record = (Map<String, Object>) item;
+        Map<String, Object> row = new Map<String, Object>();
+        row.put('ExternalId', (String) record.get('id'));
+        row.put('Name', (String) record.get('name'));
+        rows.add(row);
+    }
+    return DataSource.TableResult.get(context, rows);
+}
+return DataSource.TableResult.get(context, new List<Map<String, Object>>());
+```
+
+## Scenario 2 — Authenticated API (API key or OAuth)
+
+**Difference from Scenario 1:** The Named Credential cannot be deployed as metadata — credentials must never live in source files. Tell the user:
+
+> "Before deploying, create the Named Credential manually in Setup. Go to Setup → Named Credentials → New Legacy, set the URL, and enter your API key or OAuth credentials there. Then run the deploy command — skip the `.namedCredential-meta.xml` file."
+
+`getAuthenticationMode()` returns:
+- `NAMED_PRINCIPAL` — all users share one credential (most common for API keys)
+- `PER_USER` — each Salesforce user authenticates separately (OAuth per-user)
+
+The API key is passed via a request header in `query()`:
+```apex
+req.setHeader('Authorization', 'Bearer {!$Credential.OAuthToken}');
+// or for API key:
+req.setHeader('X-API-Key', '{!$Credential.Password}');
+```
+
+## Scenario 3 — Read-write adapter
+
+Add to `getCapabilities()`:
+```apex
+DataSource.Capability.ROW_CREATE,
+DataSource.Capability.ROW_UPDATE,
+DataSource.Capability.ROW_DELETE
+```
+
+`upsertRows()` pattern — note plural, returns a List:
+```apex
+global override List<DataSource.UpsertResult> upsertRows(DataSource.UpsertContext context) {
+    List<DataSource.UpsertResult> results = new List<DataSource.UpsertResult>();
+    for (Map<String, Object> record : context.rows) {
+        String externalId = (String) record.get('ExternalId');
+        String method = (externalId != null) ? 'PATCH' : 'POST';
+        String path = (externalId != null) ? '/items/' + externalId : '/items';
+        // build request, call API
+        results.add(DataSource.UpsertResult.success(externalId));
+    }
+    return results;
+}
+```
+
+## Scenario 4 — Paginated API
+
+There is **no automatic paging** in the Apex Connector Framework. Two options:
+
+- **Server-driven paging** — pass `numberOfRows` and an offset/cursor to the API, return one page
+- **Client-driven paging** — fetch all records and let Salesforce slice them (risky for large datasets due to heap limit)
+
+Default batch size when `numberOfRows` is null: **500 records**.
+
+```apex
+Integer pageSize = context.tableSelection.numberOfRows != null
+    ? context.tableSelection.numberOfRows : 500;
+req.setEndpoint('callout:YourNamedCredential/items?limit=' + pageSize + '&offset=0');
+```
+
+There is no automatic `queryMore`. For large datasets, implement batched iteration explicitly and stay under the 100 callout limit per transaction.
+
+## Visualforce verification template
+
+Use this to test the adapter without creating a tab, changing Deployment Status, or configuring a list view. Works on any org type.
+
+**Apex controller:**
+```apex
+public class [Object]XController {
+    public List<[Object]__x> records { get; set; }
+    public [Object]XController() {
+        records = Database.query('SELECT ExternalId, Name__c FROM [Object]__x LIMIT 50');
+    }
+}
+```
+
+**Visualforce page:**
+```xml
+<apex:page controller="[Object]XController" title="External Object Records">
+    <apex:slds />
+    <div class="slds-scope">
+        <div class="slds-page-header">
+            <h1 class="slds-page-header__title">[Object] Records</h1>
+            <p class="slds-text-body_small">Live data via Salesforce Connect — zero copy, no ETL</p>
+        </div>
+        <apex:pageBlock>
+            <apex:pageBlockTable value="{!records}" var="r">
+                <apex:column value="{!r.Name__c}" headerValue="Name"/>
+                <apex:column value="{!r.ExternalId}" headerValue="External ID"/>
+            </apex:pageBlockTable>
+        </apex:pageBlock>
+    </div>
+</apex:page>
+```
+
+Deploy both files with `sf project deploy start`, then open at `[orgUrl]/apex/[PageName]`. Use dynamic SOQL (`Database.query(...)`) rather than static SOQL — static SOQL against External Objects fails in test context.
+
+## Scenario 5 — Loopback adapter (calls back into the same Salesforce org)
+
+Use when the adapter queries the org's own Salesforce REST API and surfaces results as External Objects — no external system involved.
+
+**Key pattern:** The Named Credential injects the current user's session token automatically. No hardcoded credentials.
+
+**Named Credential — safe to deploy as metadata (no credentials in source):**
+```xml
+<generateAuthorizationHeader>true</generateAuthorizationHeader>
+<principalType>NamedUser</principalType>
+<protocol>NoAuthentication</protocol>
+```
+`generateAuthorizationHeader=true` injects `Authorization: Bearer <current session token>` on every callout. This is what makes the loopback work — no credential entry required.
+
+**Provider — use `NAMED_PRINCIPAL` (not `ANONYMOUS`):**
+```apex
+override global List<DataSource.AuthenticationCapability> getAuthenticationCapabilities() {
+    return new List<DataSource.AuthenticationCapability>{
+        DataSource.AuthenticationCapability.NAMED_PRINCIPAL
+    };
+}
+```
+
+**Connection — callout to the org's own REST API:**
+```apex
+req.setEndpoint('callout:LoopbackOrg/services/data/v66.0/query?q=' +
+    EncodingUtil.urlEncode('SELECT Id, Name FROM Account LIMIT 500', 'UTF-8'));
+req.setMethod('GET');
+req.setTimeout(10000);
+// No Authorization header set — Named Credential injects it automatically
+HttpResponse res = new Http().send(req);
+
+// REST /query response has a 'records' array, not the top-level array pattern
+Map<String, Object> payload = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
+List<Object> records = (List<Object>) payload.get('records');
+```
+
+**Test mock** — the session token is unavailable in test context; always gate on `System.Test.isRunningTest()` and return static row data instead of making callouts.