@salesforce/afv-skills 1.30.0 → 1.31.0

package/skills/platform-custom-report-type-generate/examples/AccountProjectsWithTasks.reportType-meta.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ReportType xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>AccountProjectsWithTasks</fullName>
+    <baseObject>Account</baseObject>
+    <category>other</category>
+    <deployed>true</deployed>
+    <label>Accounts with Projects with Tasks</label>
+    <description>Reports on accounts that have projects, and those projects that have tasks — useful for active-engagement tracking. Demonstrates a nested inner join chain and how each level extends the dotted relationship path in <table> (Account → Account.Projects__r → Account.Projects__r.Tasks__r).</description>
+    <join>
+        <outerJoin>false</outerJoin>
+        <relationship>Projects__r</relationship>
+        <join>
+            <outerJoin>false</outerJoin>
+            <relationship>Tasks__r</relationship>
+        </join>
+    </join>
+    <sections>
+        <masterLabel>Account Fields</masterLabel>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Name</field>
+            <table>Account</table>
+        </columns>
+    </sections>
+    <sections>
+        <masterLabel>Project Fields</masterLabel>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Name</field>
+            <table>Account.Projects__r</table>
+        </columns>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Status__c</field>
+            <table>Account.Projects__r</table>
+        </columns>
+    </sections>
+    <sections>
+        <masterLabel>Task Fields</masterLabel>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Name</field>
+            <table>Account.Projects__r.Tasks__r</table>
+        </columns>
+        <columns>
+            <checkedByDefault>false</checkedByDefault>
+            <field>Due_Date__c</field>
+            <table>Account.Projects__r.Tasks__r</table>
+        </columns>
+    </sections>
+</ReportType>

package/skills/platform-custom-report-type-generate/examples/AccountsWithIndustry.reportType-meta.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ReportType xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>AccountsWithIndustry</fullName>
+    <baseObject>Account</baseObject>
+    <category>accounts</category>
+    <deployed>true</deployed>
+    <label>Accounts with Industry Detail</label>
+    <description>Report framework for reviewing accounts with industry and revenue fields surfaced.</description>
+    <sections>
+        <masterLabel>Account Fields</masterLabel>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Name</field>
+            <table>Account</table>
+        </columns>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Industry</field>
+            <table>Account</table>
+        </columns>
+        <columns>
+            <checkedByDefault>false</checkedByDefault>
+            <field>AnnualRevenue</field>
+            <table>Account</table>
+        </columns>
+    </sections>
+</ReportType>

package/skills/platform-custom-report-type-generate/examples/AccountsWithProjects.reportType-meta.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ReportType xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>AccountsWithProjects</fullName>
+    <baseObject>Account</baseObject>
+    <category>accounts</category>
+    <deployed>true</deployed>
+    <label>Accounts with or without Projects</label>
+    <description>Shows every account; related project fields appear when projects exist. Demonstrates outer join — primary records included regardless of related-record presence — and the dotted relationship path used in <table>Account.Projects__r</table> for joined-object fields.</description>
+    <join>
+        <outerJoin>true</outerJoin>
+        <relationship>Projects__r</relationship>
+    </join>
+    <sections>
+        <masterLabel>Account Fields</masterLabel>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Name</field>
+            <table>Account</table>
+        </columns>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Industry</field>
+            <table>Account</table>
+        </columns>
+    </sections>
+    <sections>
+        <masterLabel>Project Fields</masterLabel>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Name</field>
+            <table>Account.Projects__r</table>
+        </columns>
+        <columns>
+            <checkedByDefault>true</checkedByDefault>
+            <field>Status__c</field>
+            <table>Account.Projects__r</table>
+        </columns>
+        <columns>
+            <checkedByDefault>false</checkedByDefault>
+            <field>CreatedDate</field>
+            <table>Account.Projects__r</table>
+        </columns>
+    </sections>
+</ReportType>

package/skills/platform-custom-report-type-generate/references/category-values.md

@@ -0,0 +1,32 @@
+# `<category>` Values — `ReportTypeCategory` Enumeration
+
+The `category` value determines where the CRT appears in the report builder's "Create New Report Type" wizard. Use one of these Salesforce-defined values from the Metadata API `ReportTypeCategory` enum.
+
+| Category value | Typical use |
+|----------------|-------------|
+| `accounts` | Accounts & Contacts |
+| `opportunities` | Opportunities |
+| `forecasts` | Forecasts |
+| `cases` | Customer Support Reports |
+| `leads` | Leads |
+| `campaigns` | Campaigns |
+| `activities` | Activities |
+| `busop` | Business operations |
+| `products` | Price Books, Products and Assets |
+| `admin` | Administrative Reports |
+| `territory` | Territory management |
+| `territory2` | Territory management (Enterprise Territory Management) — API 31.0+ |
+| `usage_entitlement` | Usage entitlements |
+| `wdc` | Work.com / Calibration — API 29.0+ |
+| `calibration` | Calibration — API 29.0+ |
+| `other` | Other Reports (default for custom-object-based CRTs without a natural home) |
+| `content` | Content |
+| `quotes` | Quotes |
+| `individual` | Individual (privacy) — API 45.0+ |
+| `employee` | Employee — API 46.0+ |
+| `data_cloud` | Data Cloud — API 55.0+ |
+| `commerce` | Commerce — API 60.0+ |
+| `flow` | Flow — API 60.0+ |
+| `semantic_model` | Semantic model — API 60.0+ |
+
+**When in doubt:** Use `other` for custom-object-based CRTs.

package/skills/platform-custom-report-type-generate/references/errors-and-troubleshooting.md

@@ -0,0 +1,24 @@
+# Common Authoring Errors
+
+Read this when a generated `.reportType-meta.xml` is rejected during deployment or fields don't appear in the report builder. Use these to validate the authored XML before handing it off; deployment itself is outside this skill's scope.
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Invalid object name 'X'` on `<baseObject>` | Primary object doesn't exist or isn't deployed | Deploy the custom object before the CRT |
+| `Invalid relationship name 'X'` on `<join>` | Used the field API name instead of the child relationship name, or forgot `__r` | Use the child relationship name (e.g. `Projects__r` for a custom relationship) |
+| `Invalid field 'X' for object 'Y'` | Field doesn't exist on `<table>`, used label instead of API name, or field not yet deployed | Verify field API name; deploy dependent fields first |
+| `Invalid category value 'X'` | Typo or non-existent category | Use a valid `ReportTypeCategory` value (see `category-values.md`); use `other` for general-purpose custom-object CRTs |
+| Inner join after outer join | A nested `<join>` has `<outerJoin>false</outerJoin>` following an earlier outer join | Switch the nested join to `<outerJoin>true</outerJoin>`, or restructure so inner joins come first |
+| Fields from joined object not visible in report builder | `<table>` in `<sections>` for the joined object doesn't use the dotted relationship path | Change `<table>` to the full path (e.g. `Account.Projects__r` not `Project__c`) |
+| `Cannot change base object` on update | Attempted to change `<baseObject>` after initial deploy | Create a new CRT with the new primary object; retire the old one |
+| File not found / fullName mismatch | File name doesn't match `<fullName>` | Rename file so `<fullName>.reportType-meta.xml` matches |
+
+## Handling Conflicting Join Requirements
+
+When a user wants both "include primary records without children" AND "exclude children that lack their own children" — those constraints are inexpressible in a single CRT join chain (Rule 7 forbids inner-after-outer). Three workarounds:
+
+1. **All-outer + report-level filter** — keep all joins outer and filter at report time (e.g. `Case ID ≠ null`). Pragmatic, but every report author must remember the filter.
+2. **Flip the base object** — base on the deepest required object. Lose primary-without-children but gain the inner-join guarantee. Lookup fields on the new base let you traverse back up for context.
+3. **Two CRTs** — one all-outer for "all primary records," one inner-chained for "only primary records with full children." Users pick the right one.
+
+Surface this trade-off to the user rather than picking silently.

package/skills/platform-dataspace-access-configure/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: platform-dataspace-access-configure
+description: "Use this skill to configure Salesforce Data Cloud DataSpace access for permission sets. Grants dataspace-level access via MDAPI PermissionSet XML with dataspaceScopes elements, and optionally grants object-level access to specific DMO, DLO, or CIO objects via the Object Access Grants Connect API. TRIGGER when: user needs to create or update a permission set that includes DataSpace access, grant a permission set access to a specific dataspace, configure dataAccessLevel or objectAccessLevel for a dataspace scope, add RBAC object access grants for Data Cloud objects, or list or remove object access grants for a permission set and DataSpace pair. DO NOT TRIGGER when: the task is a generic permission set without any dataspace access (use platform-permission-set-generate), the request is about data ingestion or streams (use data360-prepare), or the work involves creating dataspaces themselves rather than granting access to them."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6"
+---
+
+# platform-dataspace-access-configure
+
+Configure DataSpace access in Salesforce Data Cloud using a two-layer model:
+
+1. **DataSpace-level access** — grant a `PermissionSet` access to a DataSpace by embedding a `<dataspaceScopes>` element in the permission set XML and deploying via MDAPI.
+2. **Object-level access (optional)** — grant that permission set access to specific DMO / DLO / CIO objects within the DataSpace using the Object Access Grants Connect API.
+
+The MDAPI layer is required to establish the PermissionSet → DataSpace linkage. The Connect API layer is optional and only needed when access should be scoped to specific objects rather than governed entirely by data governance policies.
+
+---
+
+## Decide the Case First
+
+Pick exactly one case from the table below before writing any files. Each case has a different output shape.
+
+| Case | User intent | Permission set state | Files to emit |
+|---|---|---|---|
+| **A. Create new permset with DS access** | "create a permission set called X with dataspace scope Y" | does NOT exist yet | `permissionsets/<Name>.permissionset-meta.xml` **and** `package.xml` |
+| **B. Add DS access to existing permset** | "grant existing permission set X access to dataspace Y" | already deployed (may contain other permissions) | patched `permissionsets/<Name>.permissionset-meta.xml` **and** `package.xml` — see Case B workflow below |
+| **C. Object-level grant only** | "grant permset X access to object Z (in dataspace Y)" — permset + scope already configured | already deployed with `dataspaceScopes` | `api-request.json` (Connect API body). NO permission set XML, NO `package.xml` |
+
+Only emit the files listed for the case you picked. Emitting Case A/B files for a Case C prompt (or vice versa) is a correctness failure — extra files change the deployment shape.
+
+> **Case B — critical:** PermissionSet MDAPI deploy is a **full metadata replace**. Every `<objectPermissions>`, `<fieldPermissions>`, `<userPermissions>`, `<tabSettings>`, `<applicationVisibilities>`, `<recordTypeVisibilities>`, `<customPermissions>`, `<pageAccesses>`, `<classAccesses>`, `<customMetadataTypeAccesses>`, `<customSettingAccesses>`, `<externalDataSourceAccesses>` element you omit from the redeploy is **deleted from the org**. Before adding `<dataspaceScopes>` to an existing permset, retrieve the current XML and patch it — do not hand-author from scratch.
+
+### Case B workflow
+
+1. Retrieve the existing permission set:
+   ```bash
+   sf project retrieve start --metadata PermissionSet:<Name> --target-org <alias>
+   ```
+2. Open the retrieved `permissionsets/<Name>.permissionset-meta.xml`. Keep every element already there.
+3. Insert the `<dataspaceScopes>` block for the target DataSpace (element order in the file does not matter for MDAPI). If the file already has a `<dataspaceScopes>` block **for this same DataSpace**, replace only that block. Leave every `<dataspaceScopes>` block for other DataSpaces untouched — one block per DataSpace, and removing a block revokes that DataSpace grant.
+4. Write `package.xml` listing the permset in `<members>`.
+5. Redeploy with `sf project deploy start`.
+
+---
+
+## When This Skill Owns the Task
+
+Trigger this skill when the user wants to:
+- Create a permission set that grants access to a Data Cloud DataSpace
+- Add or modify `dataspaceScopes` on an existing permission set
+- Grant a permission set access to specific DMO / DLO / CIO objects in a DataSpace
+- Configure `dataAccessLevel` and `objectAccessLevel` for a DataSpace scope
+- List or remove object access grants for a permission set + DataSpace pair
+
+Delegate elsewhere when:
+- The permission set has no DataSpace access at all → `platform-permission-set-generate`
+- The task is creating the DataSpace itself → `data360-orchestrate`
+- The task is ingesting data or configuring streams → `data360-prepare`
+
+---
+
+## Layer 1 — DataSpace-Level Access (MDAPI)
+
+Embed a `<dataspaceScopes>` element inside the `PermissionSet` XML. Deploy with MDAPI.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Data Cloud Analyst</label>
+    <description>Data cloud analyst access to the default dataspace</description>
+    <hasActivationRequired>false</hasActivationRequired>
+    <dataspaceScopes>
+        <dataspaceScope>default</dataspaceScope>
+        <dataAccessLevel>ALL</dataAccessLevel>
+        <objectAccessLevel>BY_POLICY</objectAccessLevel>
+    </dataspaceScopes>
+</PermissionSet>
+```
+
+### Element Rules
+
+| Element | Required | Valid Values | Purpose |
+|---|---|---|---|
+| `<dataspaceScopes>` | yes | parent element (plural) | Container for a single dataspace scope grant |
+| `<dataspaceScope>` | yes | DataSpace API name (e.g. `default`) | Which DataSpace this grant is for |
+| `<dataAccessLevel>` | yes | `NONE`, `CONTROLLED_BY_PARENT`, `ALL` | Row-level data access within the DataSpace |
+| `<objectAccessLevel>` | yes | `BY_POLICY`, `ALL_IN_DATASPACE` | Object-level access. `BY_POLICY` defers to data governance policies. `ALL_IN_DATASPACE` is only allowed when `dataAccessLevel` is `CONTROLLED_BY_PARENT` |
+
+### Common Mistakes
+
+- **Wrong parent name** — using `<dataspaceScopeAccess>` instead of `<dataspaceScopes>`. Deployment fails silently or with cryptic errors.
+- **Wrong child name** — using `<dataspaceScopeName>` instead of `<dataspaceScope>`.
+- **Wrong enum values** — `ViewAllRows` / `Read` / `OWNER` / `EDIT` are not valid. Use `NONE`, `CONTROLLED_BY_PARENT`, or `ALL` for `dataAccessLevel`; use `BY_POLICY` or `ALL_IN_DATASPACE` for `objectAccessLevel`. See Element Rules table for allowed combinations. Deployment error `-379999659` means invalid enum.
+- **Multiple scopes in one element** — `<dataspaceScopes>` grants access to exactly one DataSpace. To grant access to multiple, add multiple `<dataspaceScopes>` blocks.
+
+### Package Layout (Case A and Case B)
+
+A deployable bundle for Layer 1 always contains **both** files:
+
+```text
+<output-root>/
+  package.xml
+  permissionsets/<Name>.permissionset-meta.xml
+```
+
+`package.xml` (required — list every permission set being deployed in `<members>`):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Data_Cloud_Analyst</members>
+        <name>PermissionSet</name>
+    </types>
+    <version>67.0</version>
+</Package>
+```
+
+Deploy:
+
+```bash
+sf project deploy start --source-dir force-app/main/default/permissionsets/ --target-org <alias>
+```
+
+---
+
+## Layer 2 — Object-Level Access (Connect API) — Case C
+
+Only needed when `objectAccessLevel` is not `BY_POLICY`, or when governance policies do not cover the target objects. Grants are runtime — **no MDAPI deploy, no `package.xml`, no permission set XML**. The only artifact for a Case C task is a single `api-request.json` describing the Connect API call.
+
+### Resolve the API version first
+
+Every Connect API `endpoint` in this layer contains an `/services/data/v<apiVersion>/…` segment. **Do not hardcode `v67.0`.** Resolve the target org's actual API version before writing the envelope so the request matches the org's supported surface:
+
+```bash
+sf org display --target-org <alias> --json | jq -r '.result.apiVersion'
+```
+
+- Substitute the returned value (e.g. `67.0`, `68.0`) into the `endpoint` as `v<apiVersion>`.
+- If the org can't be queried (offline authoring, no alias yet), fall back to the `minApiVersion` from this skill's frontmatter (`67.0`) — the endpoint was introduced there and any newer version accepts the same body.
+- If the user explicitly specifies a version in the prompt, use that verbatim.
+
+In the templates below, `{apiVersion}` is a placeholder. Replace it with the resolved API version (e.g., `67.0`, `68.0`) before emitting `api-request.json`.
+
+### `api-request.json` — canonical shape
+
+Emit the request as a self-describing envelope with `method`, `endpoint`, `headers`, `body`, and `expectedResponse`. Do NOT emit only the body — reviewers and downstream tooling read the envelope.
+
+```json
+{
+  "method": "POST",
+  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants",
+  "headers": {
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "permissionSetName": "Data_Cloud_Analyst",
+    "dataSpaceName": "default",
+    "objectApiName": "Account__dlm"
+  },
+  "expectedResponse": {
+    "status": 201,
+    "body": {
+      "permissionSetName": "Data_Cloud_Analyst",
+      "dataSpaceName": "default",
+      "objectApiName": "Account__dlm"
+    }
+  }
+}
+```
+
+### Bulk Grant
+
+Same `api-request.json` envelope shape. `endpoint` gains the `/actions/bulk-create` suffix, `body.objectApiName` is replaced by the list-valued `body.objectApiNames`, and `expectedResponse` omits the `body` field because bulk responses return per-object status entries rather than the flat request payload (see Gotchas below).
+
+```json
+{
+  "method": "POST",
+  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants/actions/bulk-create",
+  "headers": {
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "permissionSetName": "Data_Cloud_Analyst",
+    "dataSpaceName": "default",
+    "objectApiNames": ["Account__dlm", "Contact__dlm", "Opportunity__dlm"]
+  },
+  "expectedResponse": {
+    "status": 201
+  }
+}
+```
+
+### List Grants
+
+Same envelope shape with `method: "GET"`, query parameters on the `endpoint`, and no `body`.
+
+```json
+{
+  "method": "GET",
+  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants?permissionSetName=Data_Cloud_Analyst&dataSpaceName=default",
+  "headers": {
+    "Accept": "application/json"
+  },
+  "expectedResponse": {
+    "status": 200
+  }
+}
+```
+
+### Revoke Grant
+
+Same envelope shape with `method: "DELETE"`, the object API name as a path segment, and `expectedResponse.status: 204` (No Content).
+
+```json
+{
+  "method": "DELETE",
+  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants/Account__dlm?permissionSetName=Data_Cloud_Analyst&dataSpaceName=default",
+  "headers": {
+    "Accept": "application/json"
+  },
+  "expectedResponse": {
+    "status": 204
+  }
+}
+```
+
+### Object Types
+
+- **DMO** (Data Model Object) — unified profile objects, suffix `__dlm`
+- **DLO** (Data Lake Object) — raw ingested data, suffix `__dll`
+- **CIO** (Calculated Insight Object) — computed metrics, suffix `__cio`
+
+---
+
+## Combined Setup — Case A + Case C from a Cold Start
+
+Use this section ONLY when the user is starting from nothing and asks for both the permset+scope AND per-object grants in a single request. If the user's prompt is only about the Connect API grant (Case C) — for example "grant Account__dlm access; the permset and dataspace scope already exist" — SKIP this section entirely and emit only `api-request.json` from Layer 2.
+
+The commands below are operator-facing `sf` CLI invocations (a runnable cold-start walkthrough), NOT the artifact you emit. For a normal Case C task the artifact is a single `api-request.json` envelope as documented in Layer 2 above.
+
+**Goal:** Grant `Data_Cloud_Analyst` permission set access to `Account__dlm` and `Contact__dlm` in the `default` DataSpace.
+
+**Step 1 — Deploy PermissionSet with DataSpace scope (MDAPI):**
+
+```xml
+<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Data Cloud Analyst</label>
+    <description>Data cloud analyst access to the default dataspace</description>
+    <hasActivationRequired>false</hasActivationRequired>
+    <dataspaceScopes>
+        <dataspaceScope>default</dataspaceScope>
+        <dataAccessLevel>ALL</dataAccessLevel>
+        <objectAccessLevel>BY_POLICY</objectAccessLevel>
+    </dataspaceScopes>
+</PermissionSet>
+```
+
+```bash
+sf project deploy start --source-dir permissionsets/ --target-org <alias>
+```
+
+**Step 2 — Grant object access (Connect API):**
+*(Required here because the `default` DataSpace has no governance policies covering `Account__dlm` and `Contact__dlm`. Skip Step 2 when `BY_POLICY` policies already govern the target objects — Layer 1 alone is sufficient.)*
+
+Resolve the org's API version first (see [Resolve the API version first](#resolve-the-api-version-first) above), then substitute it into the `--path` value:
+
+```bash
+API_VERSION=$(sf org display --target-org <alias> --json | jq -r '.result.apiVersion')
+
+sf org api rest --target-org <alias> \
+  --method POST \
+  --path "/services/data/v${API_VERSION}/ssot/data-governance/object-access-grants/actions/bulk-create" \
+  --body '{
+    "permissionSetName": "Data_Cloud_Analyst",
+    "dataSpaceName": "default",
+    "objectApiNames": ["Account__dlm", "Contact__dlm"]
+  }'
+```
+
+**Step 3 — Verify:**
+
+```bash
+sf org api rest --target-org <alias> \
+  --path "/services/data/v${API_VERSION}/ssot/data-governance/object-access-grants?permissionSetName=Data_Cloud_Analyst&dataSpaceName=default"
+```
+
+---
+
+## Rules and Constraints
+
+| Rule | Reason |
+|---|---|
+| Use `<dataspaceScopes>` (plural) as parent, `<dataspaceScope>` (singular) as child | XML schema requirement; other names deploy-fail |
+| `dataAccessLevel` values: `NONE`, `CONTROLLED_BY_PARENT`, `ALL` only | Other values (e.g. `OWNER`, `ViewAllRows`) are rejected |
+| `objectAccessLevel` values: `BY_POLICY`, `ALL_IN_DATASPACE` only | Other values (e.g. `READ`, `EDIT`, `Read`) are rejected. `ALL_IN_DATASPACE` requires `dataAccessLevel=CONTROLLED_BY_PARENT` |
+| Prefer `BY_POLICY` when data governance policies exist | Delegates row/column filtering to central policy — no per-object grants needed |
+| One `<dataspaceScopes>` block per DataSpace | Repeat the block for multiple DataSpaces on the same permission set |
+| Org must have Data Cloud provisioned to deploy `<dataspaceScopes>` | On non-Data-Cloud orgs, the element is ignored or rejected |
+| Do not query `DataspaceScope` / `DataspaceScopeAccess` via SOQL | Not queryable; use MDAPI retrieve to inspect existing grants |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| Deployment fails with error `-379999659` | Check enum values — `dataAccessLevel` must be `NONE`/`CONTROLLED_BY_PARENT`/`ALL`; `objectAccessLevel` must be `BY_POLICY`/`ALL_IN_DATASPACE` |
+| Permission set deploys but users still can't query DataSpace data | Layer 2 not applied — objects need explicit grants if `objectAccessLevel != BY_POLICY` |
+| Bulk-create returns `AlreadyExists` for some objects | Idempotent — safe to retry; response shows per-object status |
+| Connect API returns 404 for object grants endpoint | Org lacks Data Cloud provisioning, or the resolved API version is below the minimum. The endpoint was introduced in `v67.0` — re-run `sf org display --json` to confirm the org's `apiVersion` field is `67.0` or later, and substitute that value into the `endpoint` path |
+| Retrieved PermissionSet XML shows different element names than deployed | Metadata API sometimes echoes legacy names on retrieve — always author with current names |

package/skills/platform-docs-get/SKILL.md

@@ -3,6 +3,10 @@ name: platform-docs-get
 description: "Official Salesforce documentation retrieval skill. Use when you need authoritative Salesforce docs from developer.salesforce.com, help.salesforce.com, architect.salesforce.com, admin.salesforce.com, or lightningdesignsystem.com, especially when pages are JS-heavy, shell-rendered, or hard to extract with naive fetching. Use to ground answers in official Salesforce sources instead of third-party blogs or summaries. TRIGGER when: user asks for official Salesforce documentation, Apex or API reference, LWC docs, Agentforce docs, setup or help articles, or any doc from a Salesforce-owned domain. DO NOT TRIGGER when: user is asking for a code change, deployment task, or anything not requiring documentation retrieval — use the appropriate sf-* skill instead."
 metadata:
   version: "1.1"
+  relatedSkills: ["platform-soql-query"]
+  cliTools:
+    - tool: ["python3"]
+      semver: ">=3.8.0"
 ---
 
 # platform-docs-get

package/skills/platform-docs-get/scripts/extract_salesforce_doc.py

@@ -153,27 +153,53 @@ def extract_official_salesforce_doc(url: str, timeout_seconds: int, use_stealth:
             http_status = response.status if response else None
             page.wait_for_timeout(1500)
             try:
-                page.wait_for_function(
-                    r"""
+                page.wait_for_load_state("networkidle", timeout=min(timeout_ms, 15000))
+            except PlaywrightTimeoutError:
+                pass
+
+            # Wait for content: check both light DOM and shadow DOM content
+            is_developer = "developer.salesforce.com" in host
+            wait_js = r"""
                     () => {
+                      // Light DOM check (works for most official sites)
                       const el = document.querySelector('main, article, [role="main"]');
-                      const text = (el?.innerText || el?.textContent || '').trim();
-                      return text.length > 200;
+                      const lightText = (el?.innerText || el?.textContent || '').trim();
+                      if (lightText.length > 200) return true;
+
+                      // Shadow DOM check (needed for developer.salesforce.com)
+                      function findDeepText(root, depth) {
+                        if (depth > 5 || !root) return '';
+                        let best = '';
+                        const els = root.querySelectorAll ? root.querySelectorAll('*') : [];
+                        for (const child of els) {
+                          if (child.shadowRoot) {
+                            // Check direct children of shadow root for text
+                            for (const sc of child.shadowRoot.children) {
+                              const t = (sc.innerText || '').trim();
+                              if (t.length > best.length) best = t;
+                            }
+                            const deeper = findDeepText(child.shadowRoot, depth + 1);
+                            if (deeper.length > best.length) best = deeper;
+                          }
+                        }
+                        return best;
+                      }
+                      const shadowText = findDeepText(document, 0);
+                      return shadowText.length > 200;
                     }
-                    """,
-                    timeout=min(timeout_ms, 15000),
-                )
-            except PlaywrightTimeoutError:
-                pass
+                    """
             try:
-                page.wait_for_load_state("networkidle", timeout=min(timeout_ms, 15000))
+                page.wait_for_function(
+                    wait_js,
+                    timeout=min(timeout_ms, 20000 if is_developer else 15000),
+                )
             except PlaywrightTimeoutError:
                 pass
             page.wait_for_timeout(500)
 
             payload = page.evaluate(
                 r"""
-                () => {
+                (host) => {
                   function normalize(text) {
                     return String(text || '')
                       .replace(/\u00a0/g, ' ')
@@ -233,6 +259,14 @@ def extract_official_salesforce_doc(url: str, timeout_seconds: int, use_stealth:
                     return Array.from(urls);
                   }
 
+                  // --- Noise removal: strip cookie/consent overlays before scoring ---
+                  document.querySelectorAll(
+                    '#onetrust-banner-sdk, #onetrust-consent-sdk, .onetrust-consent-sdk, ' +
+                    '[class*="onetrust-pc"], #onetrust-pc-sdk, ' +
+                    '[id*="cookie-consent"], [class*="cookie-banner"], ' +
+                    '.evidon-consent-button, #evidon-banner'
+                  ).forEach(function(el) { el.remove(); });
+
                   const title = document.title || normalize(document.querySelector('title')?.innerText || 'Untitled');
                   const childLinks = new Set();
                   for (const root of allRoots()) {
@@ -258,12 +292,42 @@ def extract_official_salesforce_doc(url: str, timeout_seconds: int, use_stealth:
                     { selector: 'main .content, article .content', strategy: 'nested-content', base: 140 },
                   ];
 
+                  // --- Host-aware selector overrides for developer.salesforce.com ---
+                  if (host.includes('developer.salesforce.com')) {
+                    selectorConfigs.unshift(
+                      { selector: 'doc-content', strategy: 'dev-doc-content', base: 295 },
+                      { selector: '#maincontent', strategy: 'dev-maincontent', base: 290 },
+                      { selector: '.doc-body', strategy: 'dev-doc-body', base: 285 },
+                      { selector: '#topic-content', strategy: 'dev-topic-content', base: 285 },
+                      { selector: '.topicContent', strategy: 'dev-topic', base: 280 },
+                      { selector: '[class*="docContent"]', strategy: 'dev-doc-content-class', base: 275 },
+                      { selector: 'doc-xml-content .content', strategy: 'dev-xml-content', base: 270 },
+                    );
+                  }
+
+                  // Extract text from an element, including shadow root content
+                  function extractText(el) {
+                    let text = (el.innerText || el.textContent || '').trim();
+                    // If element is a shadow host with no slotted light DOM text,
+                    // gather text from its shadow root's children
+                    if (text.length < 200 && el.shadowRoot) {
+                      let shadowText = '';
+                      for (const child of el.shadowRoot.children) {
+                        shadowText += (child.innerText || child.textContent || '') + '\n';
+                      }
+                      if (shadowText.trim().length > text.length) {
+                        text = shadowText.trim();
+                      }
+                    }
+                    return text;
+                  }
+
                   const candidates = [];
                   for (const cfg of selectorConfigs) {
                     const nodes = deepQueryAll(cfg.selector);
                     for (const node of nodes) {
                       if (!isVisible(node)) continue;
-                      const text = normalize(node.innerText || node.textContent || '');
+                      const text = normalize(extractText(node));
                       if (text.length < 200) continue;
                       let score = cfg.base + Math.min(text.length, 5000) / 30;
                       const lowered = text.toLowerCase();
@@ -306,7 +370,8 @@ def extract_official_salesforce_doc(url: str, timeout_seconds: int, use_stealth:
                     candidateCount: candidates.length,
                   };
                 }
-                """
+                """,
+                host,
             )
 
             text = normalize_text(payload.get("text", ""))