@salesforce/afv-skills 1.66.0 → 1.68.0

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

@@ -1,9 +1,10 @@
 ---
 name: platform-dataspace-access-configure
-description: "Use this skill to configure or inspect Salesforce Data Cloud DataSpace access for permission sets. Grants dataspace-level access via MDAPI PermissionSet XML with dataspaceScopes elements, optionally grants object-level access to DMO, DLO, or CIO objects via the Object Access Grants Connect API, and inspects existing scopes via read-only PermissionSet metadata retrieval. TRIGGER when: user needs to create or update a permission set with DataSpace access, grant access to a specific dataspace, list permission sets with access to a DataSpace, configure dataAccessLevel/objectAccessLevel, add RBAC object access grants, or list/remove object access grants for a permission set + DataSpace pair. DO NOT TRIGGER when: the task is a generic permission set without dataspace access (use platform-permission-set-generate), the request is about data ingestion/streams, or the work involves creating dataspaces themselves rather than granting access to them."
+description: "THE skill for granting Data Cloud data-space access and the PERMISSION-SET / RBAC way of granting object access. Grants data-space-level access via MDAPI PermissionSet XML with dataspaceScopes, grants object-level access to DMO/DLO/CIO objects via the Object Access Grants Connect API (RBAC object grants), and inspects existing scopes read-only. TRIGGER when the user needs to grant access to a data space / dataspace, create/update a permission set with DataSpace access, list/configure scopes, or add/list/remove RBAC object access grants — 'grant access to a data space' routes here. DO NOT TRIGGER for a generic permission set (use platform-permission-set-generate), data ingestion/streams, creating dataspaces themselves, or an access POLICY / policy rule / tag/classification-based access (use platform-policy-rule-generate). For a vague object-access ask, surface both skills and ASK the permission-set way vs the policy way; if unsure the object is Data Cloud, ask which first."
 metadata:
   relatedSkills:
     - "platform-permission-set-generate"
+    - "platform-policy-rule-generate"
   version: "1.0"
   domains: ["Platform", "Data 360"]
   minApiVersion: "67.0"
@@ -27,6 +28,23 @@ The MDAPI layer is required to establish the PermissionSet → DataSpace linkage
 
 ---
 
+## When to use this skill (routing)
+
+This is the **permission-set / RBAC** path to Data Cloud access:
+
+- **"Grant access to a data space" / dataspace access** → this skill (Layer 1, `dataspaceScopes` on a permission set).
+- **Grant object access via a permission set / RBAC object grant** → this skill (Layer 2, Object Access Grants Connect API).
+
+Object access has a second, separate path — a **data-governance access policy** (a tag/OLS `PolicyRuleDefinition`), owned by **`platform-policy-rule-generate`**. Infer the mechanism from context; ask only when the request is vague:
+
+- The user is **driving from a permission set** (mentions a permission set, RBAC, or an object grant on a permset) → object access grant → **this skill**, no need to ask.
+- The user **frames it as a policy** (create a policy / access policy / policy rule, OLS/FLS/RLS, tag/classification-based) → route to **`platform-policy-rule-generate`**.
+- The request is **genuinely vague** — "grant object access to X" with no mechanism and no clue → **ASK**: the **permission-set way** (this skill) or the **policy way** (`platform-policy-rule-generate`)? If it is also unclear whether the object is a Data Cloud object, ask which object first.
+
+"Access to a **data space**" is always this skill (the permission-set / `dataspaceScopes` path) — no disambiguation needed.
+
+---
+
 ## Decide the Case First
 
 Pick exactly one case from the table below before writing any files. Each case has a different output shape.

package/skills/platform-metadata-deploy/README.md

@@ -86,7 +86,7 @@ platform-custom-object-generate/automation-flow-generate → platform-metadata-d
 
 | Related Skill | When to Use |
 |---------------|-------------|
-| platform-custom-object-generate / platform-custom-field-generate | Create objects/fields BEFORE deploy |
+| platform-custom-object-generate | Create objects/fields BEFORE deploy |
 | platform-apex-test-run | Run tests AFTER deployment |
 | platform-data-manage | Create describe-validated test data AFTER deployment |
 

package/skills/platform-metadata-deploy/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: platform-metadata-deploy
-description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code (use platform-apex-generate), building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate or platform-custom-field-generate), or querying org data (use platform-data-manage)."
+description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage)."
 metadata:
-  version: "1.1"
+  version: "1.2"
   domains: ["Platform", "Developer Experience"]
   relatedSkills:
     - "agentforce-generate"
@@ -11,9 +11,7 @@ metadata:
     - "experience-lwc-generate"
     - "integration-connectivity-connected-app-configure"
     - "integration-connectivity-generate"
-    - "platform-apex-generate"
     - "platform-apex-test-run"
-    - "platform-custom-field-generate"
     - "platform-custom-object-generate"
     - "platform-data-manage"
   cliTools:
@@ -40,9 +38,9 @@ Use `platform-metadata-deploy` when the work involves:
 - troubleshooting deployment failures and dependency ordering
 
 Delegate elsewhere when the user is:
-- authoring Apex code → [platform-apex-generate](../platform-apex-generate/SKILL.md)
+- authoring Apex code (this skill only deploys it)
 - authoring LWC components → [experience-lwc-generate](../experience-lwc-generate/SKILL.md)
-- creating custom objects or fields → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md), [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md)
+- creating custom objects or fields → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md)
 - building Flows → [automation-flow-generate](../automation-flow-generate/SKILL.md)
 - doing org data operations → [platform-data-manage](../platform-data-manage/SKILL.md)
 - authoring or testing Agentforce agents → [agentforce-generate](../agentforce-generate/SKILL.md)
@@ -54,6 +52,7 @@ Delegate elsewhere when the user is:
 - Use **`sf` CLI v2 only**.
 - On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as `--source-dir`, `--metadata`, or `--manifest`.
 - Prefer **`--dry-run` first** before real deploys.
+- **Never run `sf project deploy start` against a production org.** Production goes through the validate → quick-deploy path below (server-side validation returns a 10-day job ID; quick-deploy promotes it without re-running tests, behind an explicit confirmation).
 - For Flows, deploy safely and activate only after validation.
 - Keep test-data creation guidance delegated to **`platform-data-manage`** after metadata is validated or deployed.
 
@@ -82,7 +81,7 @@ Ask for or infer:
 Preflight checks:
 ```bash
 sf --version
-sf org list
+sf org list --skip-connection-status
 sf org display --target-org <alias> --json
 test -f sfdx-project.json
 ```
@@ -94,7 +93,25 @@ test -f sfdx-project.json
 ### 1. Preflight
 Confirm auth, repo shape, package directories, and target scope.
 
-### 2. Validate first
+### 1a. Classify the target org (routes prod vs non-prod)
+
+Before any deploy, classify the target from its `sf org list` record — the path forks on whether the org is **production**. Do NOT classify from `sf org display`: it reports only a plain My Domain and omits the sandbox/scratch/trial fields, so a Sandbox-or-Demo Org (SDO) is misclassified as production (forcedotcom/sf-skills#356). The `sf org list` record carries the real classification booleans. Pass `--skip-connection-status` so this stays a local read that does not refresh an OAuth token per authenticated org (forcedotcom/sf-skills#349):
+
+```bash
+sf org list --skip-connection-status --json
+```
+
+Find the record whose `alias`, `username`, or `orgId` matches the target, then classify from that record (first match wins):
+- **Scratch** — `isScratch` is `true`.
+- **Sandbox** — `isSandbox` is `true`, or the `instanceUrl` contains `--` (the My Domain sandbox marker) or `test.salesforce.com`.
+- **Trial / Developer Edition** — `trailExpirationDate` (the CLI's spelling; also accept `trialExpirationDate`) is a date in the **future**, or the `instanceUrl` host contains `orgfarm-`, `.develop.my.salesforce.com`, `.pc-rnd.`, or `.scratch.my.salesforce.com`. A past date does not count — the date is cached at login and never refreshed, so a converted trial keeps a stale past date and is not a trial.
+
+Anything else is **production** — including a **Dev Hub** (`isDevHub` is `true`) that shows none of the above signals, since Dev Hub is normally enabled in the customer's own production org. If no record matches or the record has no usable info (no `instanceUrl` and none of the flags), treat it as **unknown** and ask the user before proceeding, rather than assuming production or non-production.
+
+- **Non-production** → the dry-run + deploy path (steps 2–6).
+- **Production** → the validate → quick-deploy path ([Production deploys](#production-deploys-validate--quick-deploy)). Never run `sf project deploy start` against production.
+
+### 2. Validate first (non-production)
 ```bash
 sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json
 ```
@@ -118,9 +135,6 @@ sf project deploy start --manifest manifest/package.xml --target-org <alias> --t
 
 # manifest deploy with Spring '26 relevant-test selection
 sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json
-
-# quick deploy after successful validation
-sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json
 ```
 
 ### 5. Verify
@@ -136,6 +150,93 @@ Output template: [references/deployment-report-template.md](references/deploymen
 
 ---
 
+## Production deploys (validate → quick-deploy)
+
+Production is never deployed with `sf project deploy start`. It is a two-step promotion: a **server-side validation** produces a job ID, then a **quick deploy** promotes that validated job without re-running tests, behind an explicit confirmation.
+
+### P1. Validate against production
+
+Production validations REQUIRE a test level. Use `RunLocalTests` by default; switch to `RunSpecifiedTests --tests <ClassName>...` only if the user has explicitly listed tests.
+
+```bash
+sf project deploy validate --target-org <alias> --json [scope flags] --test-level RunLocalTests
+```
+
+Scope flags — use exactly one: `--source-dir <path>`, `--metadata <Type:Name>`, or `--manifest manifest/package.xml`.
+
+The response returns a **job ID** (`result.id`) valid for **10 days**. Persist it **with the target's immutable identity** — the org ID and instance URL from `sf org display`, not just the alias — so the quick deploy can prove the validation belongs to the org it is about to promote to:
+
+```bash
+mkdir -p .sfdx
+ORG_JSON=$(sf org display --target-org <alias> --json)
+ORG_ID=$(printf '%s' "$ORG_JSON" | jq -r '.result.id')
+INSTANCE_URL=$(printf '%s' "$ORG_JSON" | jq -r '.result.instanceUrl')
+printf '{"jobId":"%s","createdAt":"%s","targetOrg":"%s","orgId":"%s","instanceUrl":"%s","testLevel":"RunLocalTests"}\n' \
+  "<id>" "<iso8601>" "<alias>" "$ORG_ID" "$INSTANCE_URL" > .sfdx/last-validation.json
+```
+
+On validation failure, triage from `result.details.componentFailures` and `result.details.runTestResult.failures` — surface the top component errors and test failures with a scoped fix direction, then STOP. Never use `--ignore-errors`/`--ignore-warnings` during validation.
+
+### P2. Gate the quick deploy strictly
+
+Before promoting, verify all five:
+1. **Target is production** — re-confirm via step 1a's classification.
+2. **A validation exists** — read `.sfdx/last-validation.json`, or ask for the job ID, or fall back to `--use-most-recent`. Resolve `--use-most-recent` to a concrete job ID **now** (do not carry it forward as an unresolved flag), so the checks below run against a known job.
+3. **Validation belongs to THIS target** — re-run `sf org display --target-org <alias> --json` and require the current `result.id` (org ID) to equal the `orgId` persisted in `.sfdx/last-validation.json`. This closes the stale-cache hazard: a cached job ID resolves its org from the deploy cache, so without this check the banner can show org B while the job promotes to org A. On any mismatch — or if the persisted record lacks an `orgId`/`instanceUrl` to compare — treat it as a **hard stop** and re-validate (P1) against the intended target. Never promote a validation whose target you cannot prove.
+4. **Validation is fresh** — explicit `--job-id` ≤ 10 days; a `--use-most-recent` resolution ≤ 3 days. If stale, re-validate (P1) first.
+5. **Explicit user confirmation** — print the banner below and require a literal "yes". Populate every banner field from the verified validation record and the just-fetched org data — never from unverified input. Never auto-confirm.
+
+```text
+┌─ PRODUCTION DEPLOY ─────────────────────────────┐
+│ Org alias:      <alias>                         │
+│ Instance:       <instanceUrl>                   │
+│ Edition:        <edition>                       │
+│ Validation ID:  <jobId>                         │
+│ Validated:      <createdAt> (X days ago)        │
+│ Components:     <componentCount> queued         │
+│ Tests:          <run>/<passed>/<failed>         │
+└─────────────────────────────────────────────────┘
+Confirm deploy to PRODUCTION? (yes/no)
+```
+
+`sf org display --json` does not return the edition. Read `<edition>` from the Organization object's `OrganizationType` (e.g. `Enterprise Edition`):
+
+```bash
+sf data query --query "SELECT OrganizationType FROM Organization" --target-org <alias> --json | jq -r '.result.records[0].OrganizationType'
+```
+
+### P3. Promote and audit
+
+The literal "yes" from P2's banner is the authorization. In the **Salesforce development plugin** context, a PreToolUse hook (`sf-deploy-gate`) blocks a bare production `deploy quick` and only permits it when the command carries the machine-readable confirmation marker `CONFIRM_PROD=1`. Emit that marker to transmit the confirmation the user just gave — it is **not** an independent bypass, so add it **only after** the explicit "yes", never before:
+
+```bash
+# plugin context: CONFIRM_PROD=1 relays P2's confirmation to the safety hook
+CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json
+```
+
+Outside the plugin (bare CLI, headless/MCP) there is no such hook — run the same command without the marker.
+
+**Quick deploy starts a new deployment with its own job ID** — it does not reuse the validation ID. Capture the response, extract the new ID, and use *that* for polling, reporting, and the audit filename; keep the validation ID separately for traceability. Stop if the response carries no deployment ID:
+
+```bash
+QUICK_RESULT=$(CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json)
+QUICK_DEPLOY_ID=$(printf '%s' "$QUICK_RESULT" | jq -r '.result.id')
+[ -n "$QUICK_DEPLOY_ID" ] && [ "$QUICK_DEPLOY_ID" != "null" ] || { echo "No quick-deploy ID returned — do not report the validation ID as the deploy; investigate."; exit 1; }
+```
+
+Quick deploy promotes the validated components and does NOT re-run tests. Persist the report **for the quick-deploy operation** (not the validation) for the audit trail, then guide post-deploy verification (smoke-test critical paths, watch Setup → Deployment Status, prepare a rollback plan if anything regressed):
+
+```bash
+mkdir -p .sfdx/deploy-history
+sf project deploy report --job-id "$QUICK_DEPLOY_ID" --target-org <alias> --json > ".sfdx/deploy-history/${QUICK_DEPLOY_ID}.json"
+```
+
+If quick deploy times out or stays in progress, poll with the **quick-deploy ID**, not the validation ID.
+
+Adding `CONFIRM_PROD=1` after an explicit confirmation is the sanctioned path — it is not "working around" the gate. But never override a denial the user has **not** confirmed, and never override one raised for a different reason — a target mismatch (P2 check 3), a destructive deploy, or an unknown/unresolved org. Surface those denials and stop.
+
+---
+
 ## High-Signal Failure Patterns
 
 | Error / symptom | Likely cause | Default fix direction |
@@ -163,7 +264,7 @@ Default pipeline shape:
 7. verify + notify
 
 - When org policy and release risk allow it, consider `--test-level RunRelevantTests` for Apex-heavy deployments.
-- Pair this with modern Apex test annotations such as `@IsTest(testFor=...)` and `@IsTest(isCritical=true)` — see [platform-apex-generate](../platform-apex-generate/SKILL.md) for authoring guidance.
+- Pair this with modern Apex test annotations such as `@IsTest(testFor=...)` and `@IsTest(isCritical=true)`.
 
 Static analysis now uses **Code Analyzer v5** (`sf code-analyzer`), not retired `sf scanner`.
 
@@ -185,9 +286,7 @@ For full agent DevOps details, including `Agent:` pseudo metadata, publish/activ
 
 | Need | Delegate to | Reason |
 |---|---|---|
-| custom object creation | [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) | define objects before deploy |
-| custom field creation | [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md) | define fields before deploy |
-| Apex authoring / fixes | [platform-apex-generate](../platform-apex-generate/SKILL.md) | code authoring and repair |
+| custom object / field creation | [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) | define objects and fields before deploy |
 | run tests after deployment | [platform-apex-test-run](../platform-apex-test-run/SKILL.md) | post-deploy test execution and coverage |
 | Flow creation / repair | [automation-flow-generate](../automation-flow-generate/SKILL.md) | Flow authoring and activation guidance |
 | test data or seed records | [platform-data-manage](../platform-data-manage/SKILL.md) | describe-first data setup and cleanup |

package/skills/platform-metadata-deploy/references/agent-deployment-guide.md

@@ -366,9 +366,9 @@ Pass the BotVersion number you intend to activate as the third argument.
 **Critical:** Dependencies must be deployed BEFORE the agent.
 
 ```text
-1. Custom Objects/Fields (platform-custom-object-generate, platform-custom-field-generate)
+1. Custom Objects/Fields (platform-custom-object-generate)
    ↓
-2. Apex Classes (platform-apex-generate)
+2. Apex Classes
    ↓
 3. Flows (automation-flow-generate)
    ↓
@@ -571,14 +571,13 @@ sf agent activate --api-name My_Agent --target-org myorg
 | From Skill | To Skill | Purpose |
 |------------|----------|---------|
 | agentforce-generate | platform-metadata-deploy | Publish and activate agents |
-| platform-apex-generate | platform-metadata-deploy | Deploy Apex before agent |
 | automation-flow-generate | platform-metadata-deploy | Deploy Flows before agent |
 | integration-connectivity-generate | platform-metadata-deploy | Deploy Named Credentials for external APIs |
 
 ### Integration Pattern
 
 ```bash
-# 1. platform-apex-generate creates InvocableMethod class
+# 1. An InvocableMethod class is authored
 # 2. automation-flow-generate creates wrapper Flow
 # 3. agentforce-generate creates agent with flow:// action
 # 4. platform-metadata-deploy orchestrates deployment in correct order

package/skills/platform-metadata-deploy/references/orchestration.md

@@ -11,7 +11,7 @@ This document details how platform-metadata-deploy fits into the multi-skill wor
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  STANDARD MULTI-SKILL ORCHESTRATION ORDER                                   │
 ├─────────────────────────────────────────────────────────────────────────────┤
-│  1. platform-custom-object-generate / platform-custom-field-generate                      │
+│  1. platform-custom-object-generate                                                      │
 │     └── Create object/field definitions (LOCAL files)                       │
 │                                                                             │
 │  2. automation-flow-generate                                                         │
@@ -84,7 +84,7 @@ When deploying agents with external API integrations:
 ├─────────────────────────────────────────────────────────────────────────────┤
 │  1. integration-connectivity-connected-app-configure → Create OAuth Connected App                 │
 │  2. integration-connectivity-generate    → Create Named Credential + External Service          │
-│  3. platform-apex-generate   → Create @InvocableMethod (if needed)                 │
+│  3. Apex authoring          → Create @InvocableMethod (if needed)                 │
 │  4. automation-flow-generate   → Create Flow wrapper                                 │
 │                                                                             │
 │  5. platform-metadata-deploy         ◀── FIRST DEPLOYMENT                                 │
@@ -169,7 +169,6 @@ sf agent activate --api-name AgentName --version N --target-org alias --json
 |------------|--------------|------|
 | platform-custom-object-generate | → platform-metadata-deploy | "Deploy objects to [org]" |
 | automation-flow-generate | → platform-metadata-deploy | "Deploy flow with --dry-run" |
-| platform-apex-generate | → platform-metadata-deploy | "Deploy classes with RunLocalTests" |
 | agentforce-generate | → platform-metadata-deploy | "Deploy and publish agent" |
 
 ---

package/skills/platform-metadata-discovery-get/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: platform-metadata-discovery-get
+description: "Use before creating, changing, or writing code against Salesforce metadata, to find out what already exists in the org with the right tool. Routes each question to metadata grounding, scoped SOQL with sf data query, sf sobject list or describe, sf org list metadata, source retrieval, or local files, and covers orgs and setups where grounding is not available. Use to check whether an object, field, picklist, permission set, page, app, or flow already exists before creating one, confirm field names, types, and picklist values before writing Apex, LWC, SOQL, or Flow logic, list every field on an object or every member of a metadata type, find automation that runs on an object, or explain how something in the org is configured and who can access it. DO NOT TRIGGER for whole-org overviews, org comparison, or drift (use dx-org-analyze), metadata file structure or XML shape (platform-metadata-api-context-get), or Data Cloud DLO and DMO schema (data360-code-extension-generate)."
+metadata:
+  relatedSkills:
+  - data360-code-extension-generate
+  - dx-org-analyze
+  - platform-metadata-api-context-get
+  - platform-metadata-grounding-get
+  - platform-metadata-retrieve
+  version: "1.3"
+  domains:
+  - "Platform"
+  cliTools:
+  - tool:
+    - "sf"
+    semver: ">=2.0.0"
+  mcpTools:
+    metadata-grounding:
+      tools:
+      - "search_metadata"
+      - "query_metadata"
+      - "describe_metadata"
+      semver: ">=1.0.0"
+    headless-360:
+      tools:
+      - "describe"
+      - "dispatch"
+      - "dispatch_readonly"
+      semver: ">=1.0.0"
+id: "platform-metadata-discovery-get"
+---
+
+# Salesforce Metadata Discovery
+
+Before you create metadata, change it, or write code that references it, know what already exists in the org. This skill picks the tool for each question. Metadata grounding finds metadata by meaning when you do not know its name. It needs Salesforce Catalog and a connected grounding server, and many orgs and setups have neither. Every other route works with the `sf` CLI alone.
+
+Skip discovery when the request only changes local files and adds no new references to org metadata.
+
+## Check What You Have
+
+Do this once per session, before the first lookup.
+
+1. **The CLI and its org.** Run `sf org display --json` to see the default org and its id. If no org is authenticated, ask the user to run `sf org login web` and wait. If you cannot run commands at all, read `references/h360-routes.md`.
+2. **Grounding servers.** Note whether the Metadata Grounding MCP (tools `search_metadata`, `query_metadata`, `describe_metadata`) or the Salesforce MCP is connected. The Salesforce MCP is shown in Setup today as the Headless360 (H360) MCP Server. Its tools are `describe`, `dispatch`, and `dispatch_readonly`, which are different from the Metadata Grounding MCP tools.
+3. **One org.** Grounding identifiers start with the 18-character org id. If it differs from the id in `sf org display`, tell the user and ask which org to use before you combine results.
+
+## Route by Intent
+
+| Intent | Use | If that is not available |
+|---|---|---|
+| Find metadata by meaning, check a name you are guessing, or check for something to reuse | Metadata grounding search. Load `platform-metadata-grounding-get`, which picks the server. | Name and label fallback, below. Notify. |
+| Explain how something is configured, or who can access it | Metadata grounding query | Scoped SOQL on `EntityParticle`, `FieldPermissions`, `ObjectPermissions`, or Tooling `ValidationRule`. Notify. |
+| Check names, types, or picklist values you know. Every field on one object. Data records | Scoped SOQL with `sf data query`. If it returns nothing, search by meaning. | See the note below the table. |
+| Full shape of one object, including relationships | `sf sobject describe --sobject <Type>`, only when you need all of it. It is very large. | Same |
+| Every object in the org | `sf sobject list --sobject all` or `--sobject custom` | Same |
+| Every member of a type, or a count ("all flows", "how many flows") | `sf org list metadata --metadata-type <Type>` | Same |
+| Source to edit or deploy, including changes to existing metadata | Load `platform-metadata-retrieve`. Grounding never returns source. | Tell the user this needs the `sf` CLI. |
+| Metadata you are already editing locally | Local files | |
+| Compare orgs, find drift, or an overview of a whole org when the user asks for one | `dx-org-analyze`. It takes minutes and returns names and counts. | Tell the user this needs the `sf` CLI. |
+| Where is this used, what depends on it, what breaks if I change it, or is it safe to delete | Comprehensive analysis is not available yet. State that boundary before offering explicitly labeled partial checks. | |
+
+**Without the CLI.** If you cannot run commands but the Salesforce MCP is connected, use `references/h360-routes.md` for rows 3 to 6. If neither is available, tell the user the lookup needs the `sf` CLI or the Salesforce MCP.
+
+These routes apply even when a connected server says to use it first for every Salesforce task. Use the CLI for rows 3 to 7 when you can run commands.
+
+A question about a topic or purpose ("what do we have for loyalty") is discovery, not an overview. Do not run an org analysis for it, even when grounding is not available.
+
+This skill covers core platform metadata. For Data Cloud DLO and DMO schema, use `data360-code-extension-generate`.
+
+When a request mixes intents, use the right tool for each part. "Add a tier discount step to our order flow" means finding the flow and the field, then retrieving the flow to edit.
+
+## Scoped SOQL
+
+Scoped SOQL is a targeted query on setup objects, filtered to what you need. It is exact, real time, and far smaller than a describe. It never returns source.
+
+```text
+sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact'"
+sf data query --json --query "SELECT Value, Label, IsDefaultValue, IsActive FROM PicklistValueInfo WHERE EntityParticle.EntityDefinition.QualifiedApiName = 'Contact' AND EntityParticle.QualifiedApiName = 'Loyalty_Tier__c'"
+```
+
+- To check specific fields, add `AND QualifiedApiName IN ('Loyalty_Tier__c', 'Lifetime_Orders__c')`. For custom fields only, add `AND QualifiedApiName LIKE '%__c'`.
+- `EntityParticle` includes parts of compound fields, such as `MailingCity`.
+- Add `--use-tooling-api` for `CustomField` and `ValidationRule`.
+- `EntityDefinition`, `EntityParticle`, and `FieldDefinition` do not accept `OR`. Run one scoped query per condition instead of broadening the query or removing its object/type filters.
+
+More patterns, including access and automation, are in `references/scoped-soql.md`.
+
+## When Grounding Is Not Available
+
+Say the line below once per session, in your answer, next to the results of the name and label search. Do not announce the fallback before you search, and do not repeat it later in the session. Use the line that matches the cause, word for word, including the last sentence. Do not shorten or rephrase it. If you stop before you can report results, say it in that message instead.
+
+| Cause | Say |
+|---|---|
+| No grounding server connected | "Metadata Grounding isn't connected, so I matched by name and label, which can miss metadata named differently. Connect the Metadata Grounding MCP to search by meaning." |
+| Catalog not enabled | "Salesforce Catalog isn't turned on in this org, so I matched by name and label, which can miss metadata named differently. An admin can turn on Salesforce Catalog through Feature Manager in Data Cloud Setup." |
+| Permission missing | "Catalog search needs the Customize Application permission, so I matched by name and label, which can miss metadata named differently." |
+
+Then search names and labels. Try two or three likely words, one `LIKE` per query.
+
+```text
+sf data query --json --query "SELECT QualifiedApiName, Label FROM EntityDefinition WHERE Label LIKE '%loyalty%'"
+sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact' AND Label LIKE '%tier%'"
+sf data query --json --use-tooling-api --query "SELECT DeveloperName, EntityDefinition.QualifiedApiName FROM CustomField WHERE DeveloperName LIKE '%tier%' AND NamespacePrefix = null"
+sf data query --json --query "SELECT ApiName, Label, ProcessType, IsActive FROM FlowDefinitionView WHERE Label LIKE '%order%'"
+```
+
+- The `CustomField` query searches custom fields on every object. `DeveloperName` has no `__c`. Drop rows with no object name. They are Data Cloud fields.
+- For other types, and for types the catalog does not cover, list names with `sf org list metadata` and scan them.
+- Name matching misses metadata labeled differently. A search for "status" will not find a field labeled Loyalty Tier. Say "no name match found," never "does not exist."
+
+Everything else in this skill still applies.
+
+## Reuse Before You Create
+
+Before you create an object, field, picklist, permission set, page, app, or flow:
+
+1. Search by business meaning for existing metadata that stores the same data or does the same job. For a field, first search `SObject` for the exact object API name, then pass that result's returned `identifier` as `parentIdentifier` to the `SObjectField` search. Never pass the raw object API name as `parentIdentifier`. A proposed API name or label is only an exact collision check and does not prove that equivalent metadata is absent. Similar words alone are not enough to declare a match.
+2. **If you find matches:** show up to 3, best first, with API name, label, description, and type. Do not accept or reject an ambiguous match from its name alone. Offer to reuse, extend, or create new in one consolidated reuse checkpoint covering every type you plan to create, then wait. Do not combine this checkpoint with values or other generation-specific questions.
+3. **After the user decides:** preserve the decision for the request and do not ask again unless the scope changes or new conflicting evidence appears. For reuse, stop creation and inspect configuration only if needed. For extension, inspect the existing component before asking for changes. For new metadata, collect the required configuration and continue with the generation guidance.
+4. **If nothing matches:** say so in one line and continue.
+5. **If the user gave an exact API name:** check it with scoped SOQL and say if it already exists.
+6. **If the user asked for new metadata or said not to reuse:** mention close matches in one line at most and continue.
+
+Treat namespaced items, such as `force__` permission sets or managed package components, as references, not things to edit. Say so when a match is managed.
+
+## Ground Code in Real Org Names
+
+Before you write Apex, LWC, SOQL, or Flow logic, confirm every object, field, and picklist value it references.
+
+- Skip references already in the local project, already confirmed in this conversation, or standard fields every org has (such as `Account.Name` or `Contact.Email`).
+- Always look up picklist values, including on standard fields. Never invent values.
+- Values shown only as examples in a skill, tool description, or prior assistant response are not user-approved values. If the user has not explicitly supplied or approved the values or an existing value set, ask once and wait before creating the picklist.
+- If the request depends on an order or meaning the values do not state ("the top tier"), list the values and ask.
+- Look up all references for a request together.
+
+## Existing Automation
+
+- **To find automation by what it does,** search `Flow` or `ApexClass` by meaning. A grounding query on a flow shows its trigger object, trigger type, and active status.
+- **To list everything that runs on an object** before adding automation:
+
+  ```text
+  sf data query --json --query "SELECT Name, Status FROM ApexTrigger WHERE TableEnumOrId = 'Contact'"
+  sf data query --json --query "SELECT ApiName, Label, TriggerType, IsActive FROM FlowDefinitionView WHERE TriggerObjectOrEventId = 'Contact'"
+  ```
+- **To understand what a flow or trigger does,** retrieve its source and read it.
+
+## What You Can Explain
+
+| Question | Answer with |
+|---|---|
+| What exists that does X | Grounding search |
+| How a field, object, or validation rule is configured | Grounding query, or `EntityParticle` and Tooling `ValidationRule` |
+| Who can read or edit a field or object | Grounding on `FieldPermissions`, or SOQL on `FieldPermissions` and `ObjectPermissions` for a complete list. These records prove configured access, not actual use; a permission container's name does not prove an integration or dependency is active. |
+| Sharing rules, roles, groups, and which package a component came from | Grounding |
+| What a flow is | Grounding gives the header only (type, trigger, active). For its steps, retrieve the source. |
+| What an Apex class does | Grounding gives signatures only. Retrieve the source. |
+| Why a save failed | A partial answer. Check validation rules on the object, then retrieve the automation that runs on it. |
+| Page layouts, reports, custom metadata types, custom settings | Not in the catalog. Use `sf org list metadata` and retrieve. |
+| Where something is used, what depends on it, what breaks if it changes, or whether it is safe to delete | Comprehensive analysis is not available yet. Say so before any checks. You may offer narrow checks, but label each one as partial and never present their union as complete or conclude that the change is safe. |
+
+## Working With Skills
+
+- This skill decides what already exists. Build skills decide how to create it. Run discovery before any skill writes files.
+- If a loaded skill has its own equivalent semantic reuse check, use it instead of the matching step here. Do not run both. An exact-name or exact-label collision check is not equivalent and does not replace semantic reuse discovery.
+- Two exceptions, even when a skill says otherwise: always look up picklist values, and check names, types, or picklist values you know with scoped SOQL instead of a full object describe.
+- If a skill's discovery step fails or its tool is not available, use the routes in this skill and tell the user once.
+
+## Freshness and Local Files
+
+- Reuse discovery results for the rest of the conversation unless that item has changed.
+- The catalog can take several minutes to reflect deploys and other org changes. For anything changed in this session, trust the local source and deploy results, and confirm with SOQL, which is real time. If the user reports a change SOQL does not show, ask them to confirm the name and org before you write code that uses it.
+- When the metadata you need is not in the local project, retrieve it before editing, and tell the user you did.
+- If you learn the org version differs from local in ways you did not make, for example from a retrieve or a deploy conflict, show the difference and ask before you overwrite either one.
+- When scanning local source for references, read the package directories from `sfdx-project.json` and search those directories. Exclude response exports, logs, generated output, caches, and agent configuration unless the user explicitly asks to inspect them.
+- Searching local files finds exact text only. Do not use it to find org metadata by meaning.
+
+## Never
+
+- Write or deploy files built from grounding query output. It returns properties, not source.
+- Treat grounding results as a complete list. They are ranked and capped.
+- Say metadata does not exist because a search or a name match found nothing.
+- Combine results from two different orgs.
+- Present partial dependency or reference checks as a complete impact analysis, or conclude from them that metadata is safe to change or delete.
+- Treat illustrative values from examples, skills, or tool descriptions as user-approved metadata.

package/skills/platform-metadata-discovery-get/references/api-map.md

@@ -0,0 +1,25 @@
+# What Each Route Calls
+
+For engineers and reviewers. The skill names tools, not APIs, because the agent picks tools. Read from sf CLI 2.150.6 and jsforce source, and checked live on 2026-10-07.
+
+| Route | API call |
+|---|---|
+| `sf sobject list` | REST `describeGlobal` (`GET /services/data/vXX.0/sobjects`), filtered to custom or all on the client |
+| `sf sobject describe` | REST describe SObject (`GET /services/data/vXX.0/sobjects/<Type>/describe`). Tooling describe with `--use-tooling-api` |
+| `sf org list metadata` | Metadata API `listMetadata` (SOAP) |
+| `sf data query` | REST query resource (`GET /services/data/vXX.0/query`). Tooling query resource with `--use-tooling-api` |
+| `sf project retrieve start` | Metadata API `retrieve` (SOAP) |
+| Metadata grounding search | `GET /services/data/vXX.0/metadata-grounding/search` |
+| Metadata grounding describe | `POST /services/data/vXX.0/metadata-grounding/schema` |
+| Metadata grounding query | `POST /services/data/vXX.0/metadata-grounding/query` |
+
+## Which Surface Reaches Which Call
+
+| Call | `sf` CLI | Metadata Grounding MCP | Salesforce MCP |
+|---|---|---|---|
+| REST and Tooling query | Yes | No | Yes, `dispatch_readonly` |
+| REST describe and object list | Yes | No | Yes, `dispatch_readonly` |
+| Metadata API `listMetadata` and `retrieve` | Yes | No | No |
+| Metadata grounding | No. The grounding paths are reachable only through an MCP server, so a direct REST call returns not found | Yes | Yes, after `describe` on the operation id |
+
+The skills do not use the Enterprise API, the SOAP API with the org-specific WSDL. None of these tools call it.

package/skills/platform-metadata-discovery-get/references/h360-routes.md

@@ -0,0 +1,30 @@
+# Routes Through the Salesforce MCP
+
+Use this file when you reach the org through the Salesforce MCP. If you are in a terminal or IDE and can run the `sf` CLI, the CLI routes work as well.
+
+Grounding itself is covered in `platform-metadata-grounding-get`. This file covers the routes the skill body sends to the CLI.
+
+## How to Call
+
+Use `dispatch_readonly` with `method: GET`. Pass the path as `url` and the SOQL as the `q` query parameter, not appended to the URL.
+
+| Route | `url` | Query parameters |
+|---|---|---|
+| Standard SOQL | `/services/data/v66.0/query` | `q`: the SOQL |
+| Tooling SOQL | `/services/data/v66.0/tooling/query` | `q`: the SOQL |
+| Describe one object | `/services/data/v66.0/sobjects/<Type>/describe` | None |
+
+The rows are in `body.records`. For a `COUNT()` query the number is in `body.totalSize` and `records` is empty. Every pattern in `scoped-soql.md` works through these paths.
+
+## Route by Intent
+
+| Intent | Through this server |
+|---|---|
+| Check names, types, or picklist values you know. Every field on one object. Data records | Standard SOQL. Use Tooling SOQL for `CustomField` and `ValidationRule`. |
+| Full shape of one object, only when you need all of it | Describe one object. It is very large. |
+| Every object in the org | Standard SOQL on `EntityDefinition`, for example `SELECT QualifiedApiName, Label FROM EntityDefinition WHERE QualifiedApiName LIKE '%__c'` for custom objects. Never call `/sobjects` for the full object list. It returned about 1.8 million characters in one test org. |
+| Every member of a type, or a count | Tooling SOQL for Tooling types, for example `SELECT COUNT() FROM FlowDefinition`, or `ApexClass` and `ValidationRule`. To list flows with labels, use Standard SOQL on `FlowDefinitionView`. Other types cannot be listed through this server. Tell the user it needs the `sf` CLI in a terminal or IDE. |
+| Source to edit or deploy | Not available through this server. Load `platform-metadata-retrieve` if it is available. Otherwise tell the user it needs the `sf` CLI in a terminal or IDE. |
+| Compare orgs, find drift, or a whole-org overview | Not available through this server. Tell the user it needs the `sf` CLI. |
+
+If a call fails with an authentication or session error, tell the user to reconnect the Salesforce MCP. If it fails as not found or not allowed, say so, and tell the user the lookup may need the `sf` CLI in a terminal or IDE.

package/skills/platform-metadata-discovery-get/references/scoped-soql.md

@@ -0,0 +1,52 @@
+# Scoped SOQL Patterns
+
+Run each query through the Salesforce MCP with `dispatch_readonly`, as Standard or Tooling SOQL per the table. The paths are in `ref:platform-metadata-discovery-get/references/h360-routes`. In a terminal or IDE, `sf data query --json --query "<SOQL>"` works too. Add `--use-tooling-api` where the table says Tooling, and `--target-org <alias>` when the user named an org other than the default.
+
+## Objects and Fields
+
+| Need | Query | API |
+|---|---|---|
+| Does this object exist | `SELECT QualifiedApiName, Label FROM EntityDefinition WHERE QualifiedApiName = 'Loyalty_Transaction__c'` | Standard |
+| Several objects at once | `SELECT QualifiedApiName, Label FROM EntityDefinition WHERE QualifiedApiName IN ('Menu__c', 'Promotion__c')` | Standard |
+| Every field on one object | `SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact'` | Standard |
+| Custom fields only | Add `AND QualifiedApiName LIKE '%__c'` to the query above | Standard |
+| Check specific fields | Add `AND QualifiedApiName IN ('Loyalty_Tier__c', 'Email')` | Standard |
+| Picklist values | `SELECT Value, Label, IsDefaultValue, IsActive FROM PicklistValueInfo WHERE EntityParticle.EntityDefinition.QualifiedApiName = 'Contact' AND EntityParticle.QualifiedApiName = 'Loyalty_Tier__c'` | Standard |
+| Record types on an object | `SELECT Name, DeveloperName, IsActive FROM RecordType WHERE SobjectType = 'Contact'` | Standard |
+
+`EntityParticle` includes parts of compound fields, such as `MailingCity`. A full field list for Contact is about a tenth the size of a describe.
+
+## Name and Label Fallback
+
+Use these only when grounding is not available. Try two or three likely words.
+
+| Need | Query | API |
+|---|---|---|
+| Objects by label | `SELECT QualifiedApiName, Label FROM EntityDefinition WHERE Label LIKE '%loyalty%'` | Standard |
+| Fields on one object by label | `SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact' AND Label LIKE '%tier%'` | Standard |
+| Custom fields on every object by name | `SELECT DeveloperName, EntityDefinition.QualifiedApiName FROM CustomField WHERE DeveloperName LIKE '%tier%' AND NamespacePrefix = null` | Tooling |
+| Flows by label | `SELECT ApiName, Label, ProcessType, IsActive FROM FlowDefinitionView WHERE Label LIKE '%order%'` | Standard |
+| Permission sets by label | `SELECT Name, Label FROM PermissionSet WHERE IsOwnedByProfile = false AND Label LIKE '%loyalty%'` | Standard |
+
+- `EntityDefinition`, `EntityParticle`, and `FieldDefinition` do not accept `OR`. The query fails with "Disjunctions not supported." Run one query per word.
+- `CustomField` accepts `OR`. `DeveloperName` has no `__c`. Drop rows with no object name. They are Data Cloud fields.
+
+## Access
+
+| Need | Query | API |
+|---|---|---|
+| Who can read or edit a field | `SELECT Parent.Label, Parent.IsOwnedByProfile, Parent.Profile.Name, PermissionsRead, PermissionsEdit FROM FieldPermissions WHERE SobjectType = 'Contact' AND Field = 'Contact.Loyalty_Tier__c'` | Standard |
+| Who can use an object | `SELECT Parent.Label, Parent.IsOwnedByProfile, Parent.Profile.Name, PermissionsRead, PermissionsCreate, PermissionsEdit, PermissionsDelete FROM ObjectPermissions WHERE SobjectType = 'Loyalty_Transaction__c'` | Standard |
+
+When `Parent.IsOwnedByProfile` is true, the row belongs to a profile. Read the name from `Parent.Profile.Name`, because `Parent.Label` is an id for those rows. A field or object with no row for a profile or permission set has no access through it.
+
+## Automation and Rules
+
+| Need | Query | API |
+|---|---|---|
+| Triggers on an object | `SELECT Name, Status FROM ApexTrigger WHERE TableEnumOrId = 'Contact'` | Standard |
+| Flows that run on an object | `SELECT ApiName, Label, TriggerType, IsActive FROM FlowDefinitionView WHERE TriggerObjectOrEventId = 'Contact'` | Standard |
+| Validation rules on an object | `SELECT ValidationName, Active, ErrorMessage FROM ValidationRule WHERE EntityDefinition.QualifiedApiName = 'Contact'` | Tooling |
+| Count of flows | `SELECT COUNT() FROM FlowDefinition` | Tooling |
+
+These return names and status, not logic. To read what a flow, trigger, or rule does, retrieve its source.