@salesforce/afv-skills 1.29.0 → 1.31.0

package/skills/platform-data-manage/references/orchestration.md

@@ -7,7 +7,7 @@ This document details how platform-data-manage fits into the multi-skill workflo
 
 ## Standard Orchestration Order
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  STANDARD MULTI-SKILL ORCHESTRATION ORDER                                   │
 ├─────────────────────────────────────────────────────────────────────────────┤
@@ -35,7 +35,7 @@ This document details how platform-data-manage fits into the multi-skill workflo
 - Run test factories
 - Generate bulk test data
 
-```
+```text
 ERROR: "SObject type 'Quote__c' is not supported"
 CAUSE: Quote__c object was never deployed to the org
 FIX:   Run platform-metadata-deploy BEFORE platform-data-manage
@@ -58,7 +58,7 @@ FIX:   Run platform-metadata-deploy BEFORE platform-data-manage
 
 When testing triggers or flows, always create test data AFTER deployment:
 
-```
+```text
 1. sf-apex   → Create trigger handler class
 2. sf-flow   → Create record-triggered flow
 3. platform-metadata-deploy → Deploy trigger + flow + objects
@@ -74,7 +74,7 @@ When testing triggers or flows, always create test data AFTER deployment:
 
 Always test with **251 records** to cross the 200-record batch boundary:
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  BATCH BOUNDARY TESTING                                                     │
 ├─────────────────────────────────────────────────────────────────────────────┤
@@ -129,7 +129,7 @@ sf data query --query "SELECT Id FROM FieldPermissions WHERE SobjectType='MyObje
 
 Test Data Factory classes work with platform-data-manage:
 
-```
+```text
 sf-apex:  Creates TestDataFactory_Account.cls
           ↓
 platform-metadata-deploy: Deploys factory class
@@ -151,7 +151,7 @@ System.debug('Created ' + accounts.size() + ' accounts');
 
 After testing, clean up in reverse order:
 
-```
+```text
 1. platform-data-manage   → Delete test records
 2. platform-metadata-deploy → Deactivate flows (if needed)
 3. platform-metadata-deploy → Remove test metadata (if needed)

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", ""))

package/skills/platform-encryption-configure/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: platform-encryption-configure
+description: "Configure Salesforce Shield Platform Encryption — generate deployable encryption settings and encrypted-field metadata, and answer key-model and lifecycle questions. TRIGGER when: user wants to turn on deterministic encryption, encrypt a field, set up Cache-Only Keys, External Key Management, or replay detection, or mentions Shield Platform Encryption, encryption at rest, deterministic vs probabilistic encryption, encryptionScheme, PlatformEncryptionSettings, EncryptionKeySettings, BYOK, BYOKMS, tenant secrets, key rotation, or .settings-meta.xml / .field-meta.xml for encryption — even when they don't say 'Shield'. SKIP when: user needs a generic custom field with no encryption (use platform-custom-field-generate), needs the raw Metadata API type reference (use platform-metadata-api-context-get), or asks about Classic Encryption (encrypted text fields), which is a different feature. Use this skill for any Platform Encryption configuration, field-encryption, or key-model question."
+metadata:
+  version: "1.0"
+  minApiVersion: "62.0"
+  relatedSkills:
+    - "platform-custom-field-generate"
+    - "platform-metadata-api-context-get"
+---
+
+# Configure Platform Encryption
+
+Configures Salesforce Shield Platform Encryption by generating the metadata that turns it on and choosing the right settings: which encryption scheme a field should use, which key-management model fits a requirement, and how the tenant-secret lifecycle works. This is a **hybrid** skill — it emits deployable `*.settings-meta.xml` / `*.field-meta.xml` where Platform Encryption exposes a real Metadata API surface, and returns grounded guidance where the operation is UI/REST-only.
+
+## Scope
+
+- **In scope**: choosing and applying `encryptionScheme` on a field; enabling deterministic encryption, Cache-Only Keys, External Key Management, and replay detection via `PlatformEncryptionSettings` / `EncryptionKeySettings`; explaining BYOK / BYOKMS / EKM / Cache-Only key models; tenant-secret rotation and destruction semantics; the query behavior of encrypted fields.
+- **Out of scope**: a plain custom field with no encryption (use `platform-custom-field-generate`); the raw Metadata API field reference (use `platform-metadata-api-context-get`); Classic Encryption (`EncryptedText` fields) — that is a separate, legacy feature; deploying/pushing metadata to an org (that belongs to a deploy lifecycle skill).
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Question type**: is the user asking for a *deployable artifact* (a settings file, an encrypted field) or *guidance* (which model, what happens when I rotate a key)? Deployable → generate XML from `assets/`. Guidance → answer from `references/`. **A question is guidance whenever the ask is to explain, confirm, or compare** — "is that right?", "what's the relationship?", "can we…?", "is there an ordering requirement?", **"explain the difference between X and Y", "which key model should we use?"** — **even if the user also says they are about to write, deploy, or author settings themselves.** The user writing settings is *their* action; it does not make the skill's deliverable a file. Only an explicit "generate / create / give me the file / here is my field, encrypt it" is an artifact request.
+- **Key-model choice questions are guidance, not deployable metadata.** "Explain BYOK vs external key management / BYOKMS / EKM / Cache-Only", "which one keeps key material out of Salesforce?", "should we use BYOK or EKM?" → answer them in a **single markdown answer file** (the guidance write-up), not a deployable `*.settings-meta.xml`. **Naming the enabling setting in that answer (e.g. `canExternalKeyManagement`, `enableCacheOnlyKeys`) does NOT turn it into a settings artifact** — cite the field name inline in the answer file; do **not** emit an `EncryptionKey.settings-meta.xml` unless the user explicitly says "generate/create the settings file."
+- **Field encryption target** (for field work): the object and field API name, and whether the user needs to *filter, sort, or group* on the field (drives deterministic vs probabilistic).
+- **Key model** (for key work): whether keys are Salesforce-derived (default), customer-supplied (BYOK), stored in an external KMS (BYOKMS/EKM), or fetched on demand (Cache-Only).
+
+If the request is clear, generate or answer immediately — do not interrogate the user.
+
+---
+
+## Workflow
+
+1. **Classify the request** — deployable artifact vs guidance, using the Required Inputs above. Then **scope the output to exactly what was asked**:
+   - A **guidance** question produces **exactly one markdown answer file** — a single file (e.g. `answer.md`) containing the full written diagnosis/explanation — and **nothing else**. Do not also emit a `*.settings-meta.xml`, a `*.field-meta.xml`, or a second helper doc. This covers every "what happens when…?", "how do I…?", "which model…?", "is X right…?", "can we…?", "what's the relationship / ordering…?" question, including query-behavior and Cache-Only/replay questions. **A clause like "before I write our settings" or "before I author the file" describes the *user's* next step and does NOT turn the question into a deployable-metadata request — write the answer file, not a settings file.**
+   - **Naming a metadata change in a guidance answer does NOT mean emitting the deployable file for it.** A remediation or diagnosis question — *"how do I make the field queryable?"*, *"why did my query fail and how do I fix it?"*, *"which key model keeps material out of Salesforce?"* — is answered **inside the one markdown answer file**, naming the relevant element/scheme inline (e.g. "switch to a `Deterministic*` scheme and enable `enableDeterministicEncryption`", or "use External Key Management — `canExternalKeyManagement`"). Do **not** additionally materialize a `*.field-meta.xml` or `*.settings-meta.xml` to *demonstrate* that change — mentioning the element in the answer is the complete deliverable. Produce a deployable metadata file **only** when the user explicitly says generate/create/give me the field or settings file.
+   - An **artifact** request gets **only** the specific metadata file(s) named — do not add a `DEPLOYMENT_GUIDE.md`, `README.md`, an `EXPLANATION.md`, an org-`settings` file, or any companion artifact the user did not ask for.
+   - If a deploy step or org setting is a prerequisite, state it **inside the one answer file** (for guidance) or **in a code comment inside the one artifact** (for an artifact request) — never as an extra file.
+
+2. **For field encryption** — read `references/encryption-schemes.md` to choose the scheme, then load `assets/encrypted-field.field-meta.xml` as the starting template. Set `encryptionScheme` to exactly one of the four valid enum values (see the reference). Only `Deterministic*` schemes are filterable.
+
+   > **Write the field file at the SFDX source path, not the root.** A `*.field-meta.xml` **must** live at `objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml` (e.g. `objects/Patient__c/fields/Diagnosis_Notes__c.field-meta.xml`) — the object folder uses the object's API name (`Patient__c` for a custom object, `Contact` for a standard one) and the file is named after the field API name. Emitting the file at the repo root, in a flat directory, or under any other folder is a structural miss even when the XML itself is correct.
+
+3. **For org-level encryption settings** — load `assets/PlatformEncryption.settings-meta.xml` (deterministic encryption, field-history encryption, MEK permission) or `assets/EncryptionKey.settings-meta.xml` (Cache-Only, EKM, Data 360, transactional DB, replay detection). Read `references/key-models.md` before setting any key-model field.
+
+   > **Name the output file after the Settings *member*, not the root element, and write it under `settings/`.** A `Settings` file must be `settings/<member>.settings-meta.xml`, where `<member>` is the org's metadata member name — **`EncryptionKey`** (root `<EncryptionKeySettings>`) and **`PlatformEncryption`** (root `<PlatformEncryptionSettings>`). Put it in the `settings/` source folder (e.g. `settings/EncryptionKey.settings-meta.xml`), not the repo root. Naming the key-settings file `Encryption.settings-meta.xml` or `EncryptionKeySettings.settings-meta.xml` fails deployment with *"The object '…' of type Settings metadata does not exist."*
+
+   > **Cache-Only Keys and replay detection are a one-way dependency, not an auto-enable.** You may set `enableReplayDetection` only after `enableCacheOnlyKeys` is `true`; enabling Cache-Only does **not** turn replay detection on by itself. An org can validly run Cache-Only with replay detection off.
+
+4. **For tenant-secret operations** (rotate, destroy, BYOK upload, Cache-Only callout setup) — read `references/tenant-secret-lifecycle.md`. These are UI/REST-only; capture the guidance in the single markdown answer file, not a deployable metadata file.
+
+5. **Validate any generated settings XML** — run `scripts/validate-encryption-metadata.sh` with the file path as its argument, and fix anything it reports. It checks the replay-detection dependency and the `encryptionScheme` enum deterministically.
+
+6. **Compare against the worked example** — verify a generated `EncryptionKeySettings` file against `examples/cache-only-keys.settings-meta.xml`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| `encryptionScheme` must be exactly one of `CaseInsensitiveDeterministicEncryption`, `CaseSensitiveDeterministicEncryption`, `None`, `ProbabilisticEncryption` | These are the only values the Metadata API accepts (`CustomField`, API 44.0+); any other string fails deployment. |
+| Set `enableReplayDetection` only when `enableCacheOnlyKeys` is `true` | The contract is *"Requires enableCacheOnlyKeys=true before setting enableReplayDetection to true"* — a one-way dependency. |
+| Use deterministic schemes only when the field must be filtered, sorted, or grouped | Probabilistic is stronger but non-filterable; deterministic trades some cryptographic strength for queryability. |
+| Never claim a filter/sort/group on a probabilistically-encrypted field silently returns zero rows | The platform **rejects** the query with `INVALID_FIELD` (see gotchas); telling the user it "returns nothing" is factually wrong. |
+| Do not emit `enableExternalKeyManagement` — the field is `canExternalKeyManagement` | The WSDL element is `canExternalKeyManagement`; the sample in some docs uses a non-existent element name. |
+| Transactional-DB, EKM, and Data 360 key fields require API 63.0+ | `canEncryptTransactionalDatabase`, `canExternalKeyManagement`, `canManageDataCloudKeys` were introduced in 63.0. |
+| A **guidance** question produces **exactly one markdown answer file** — never a deployable `*.settings-meta.xml` / `*.field-meta.xml`, and never a second doc | The answer file is the user's reference document — it persists in the workspace and can be shared or revised. Emitting a deployable metadata file for a guidance question is unsolicited configuration that could be accidentally applied; emitting no file leaves the user without a tangible deliverable. |
+| An **artifact** request emits **only** the metadata file(s) asked for — no companion files | Adding a `DEPLOYMENT_GUIDE.md`/`README.md`/`EXPLANATION.md` or an extra `settings` file the user didn't request is noise. Prerequisites belong in a code comment inside the artifact, not a second file. |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Filtering/sorting/grouping on a probabilistically-encrypted field | The query is rejected with `INVALID_FIELD`: *"field '<Name>' can not be sorted / filtered / grouped in a query call."* Switch the field to a deterministic scheme if queryability is required. |
+| Assuming Cache-Only Keys auto-enables replay detection | It does not. Set `enableReplayDetection` explicitly, and only after `enableCacheOnlyKeys=true`. |
+| Case sensitivity in deterministic matching | `CaseSensitiveDeterministicEncryption` matches exact case; `CaseInsensitiveDeterministicEncryption` normalizes case. Choosing wrong silently breaks equality filters. |
+| Confusing BYOK with BYOKMS/EKM | BYOK = you upload key material Salesforce stores; BYOKMS/EKM = key material stays in your external KMS. See `references/key-models.md`. |
+| Using `enableExternalKeyManagement` element name | Wrong element. The field is `canExternalKeyManagement`. |
+| Classic Encryption vs Shield | `encryptionScheme` is Shield only. `EncryptedText` custom fields are the legacy Classic feature and out of scope. |
+
+---
+
+## Output Expectations
+
+Deliverables depend on the request — produce **exactly** these and nothing more:
+
+- **Guidance questions produce exactly ONE markdown answer file.** Any "what happens when…", "how do I…", "which model…", "is X right…" question — including encrypted-field query behavior, Cache-Only/replay-detection relationships, tenant-secret / BYOK / Cache-Only lifecycle, and key-model choices — is answered by writing a single markdown file (e.g. `answer.md`) that fully captures the diagnosis/explanation. Do **not** additionally emit a deployable `*.settings-meta.xml` / `*.field-meta.xml` or a second doc, and do **not** answer with no file at all — the answer file is the user's persistent reference document.
+- **Field encryption artifact**: **only** the `*.field-meta.xml` with `encryptionScheme` set, written at `objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml`. Not a settings file, not a deploy guide. Pick `<type>` to match the request: **`Text`** for a string field up to **255** chars; **`LongTextArea`** only when the field must exceed 255 chars (256+). "Long text … up to 255 characters" is a `Text` field, not `LongTextArea`. Strip the template's instructional comment block from the delivered file — ship clean metadata. **Keep the accompanying chat prose tight — one or two sentences naming the scheme chosen and why (e.g. "ProbabilisticEncryption — strongest at-rest protection; the field can't be filtered/sorted/grouped, which matches your no-query requirement"). Do not restate the whole prompt, enumerate every scheme, or add setup/deployment walkthroughs; the deliverable is the file, not an essay.**
+- **Org settings artifact**: **only** the settings file the request needs, at `settings/<member>.settings-meta.xml` named after its Metadata API member — `settings/PlatformEncryption.settings-meta.xml` (root `<PlatformEncryptionSettings>`) and/or `settings/EncryptionKey.settings-meta.xml` (root `<EncryptionKeySettings>`). Do **not** name the file after the root element, and do **not** drop it at the repo root.
+
+Do **not** add companion files (`DEPLOYMENT_GUIDE.md`, `README.md`, an extra org-settings file) that the user did not ask for — state prerequisites in a code comment inside the artifact, or inside the single answer file for guidance. File structure follows the templates in `assets/`.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| A custom field with no encryption | `platform-custom-field-generate` |
+| The raw Metadata API type/field reference | `platform-metadata-api-context-get` |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/encrypted-field.field-meta.xml` | Before generating an encrypted custom field |
+| `assets/PlatformEncryption.settings-meta.xml` | Before generating org encryption-policy settings (member `PlatformEncryption`) |
+| `assets/EncryptionKey.settings-meta.xml` | Before generating key-management settings — Cache-Only, EKM, Data 360 (member `EncryptionKey`) |
+| `references/encryption-schemes.md` | When choosing deterministic vs probabilistic, or explaining encrypted-field query behavior |
+| `references/key-models.md` | When configuring or explaining BYOK / BYOKMS / EKM / Cache-Only key models |
+| `references/tenant-secret-lifecycle.md` | When the user asks about key rotation, destruction, or BYOK upload |
+| `examples/cache-only-keys.settings-meta.xml` | To verify a generated Cache-Only key-settings file |
+| `scripts/validate-encryption-metadata.sh` | After generating any settings XML — validates the replay dependency and scheme enum |