@salesforce/afv-skills 1.65.1 → 1.67.0

package/skills/experience-search-coordinate/SKILL.md

@@ -146,7 +146,7 @@ Follow this sequence for each intent Step 2 routed here. The media content type
 1. **Present available search sources via `ask_followup_question` — no other tool calls yet.** Only the sources whose tools you actually have (via introspection), plus "Other", each as its own option. Wait for the user's selection before any tool call. → Read `references/media-route.md` § "Presenting available search sources" for the full template.
 2. **Build the query, then confirm with the user before searching — required two-message pattern**, in the same turn:
    - **Search using keywords** (`search_media_cms_channels`): extract keywords (concrete nouns, max 10 terms) and taxonomies (descriptive/style/mood/category terms — extract every one the query actually contains; don't default to empty just because keywords were found). E.g. "luxury apartment with river view" → keywords `apartment OR villa OR penthouse OR residence`, taxonomies `{"OR": ["Luxury", "Premium", "Waterfront", "Riverside"]}`; "car" → taxonomies `"{}"` (no descriptive terms). Build the payload with `contentTypeFqn` set to the FQN(s) from Step 2, `searchLanguage` set to a locale (`en_US`, `es_MX`, ... — default `en_US`; **required, never null/omitted**), `searchLimit: 5`. → Read `references/media-route.md` for full worked examples.
-   - **Search using Data 360 hybrid search** (`search_electronic_media`) — pass the user's query as-is to `searchQuery`, no extraction needed.
+   - **Search using Data 360 hybrid search** (`search_electronic_media`): verbatim `searchQuery`; bare ISO `searchLanguage` only if the schema lists it; confirm first. On zero results or a language error, ask the user before one retry without it; never retry after a server error → `references/media-route.md`.
    - **Other** — ask for a direct URL, asset library path, or specific system to check (no confirmation step, since no tool is called).
 
    → Read `references/media-route.md` § "Confirming the query before searching" for the confirmation message templates (labeled-parameters chat message, then `ask_followup_question` with `Yes - search now` / `Edit search` / `Cancel`).
@@ -175,7 +175,7 @@ Each route's results are labeled and presented on their own (e.g. "Images:" for
 | `metadata-grounding` unavailable or no content types match | Apply the fallback chain in `references/content-type-discovery.md` — do not block or ask for an FQN |
 | No search results (either route) | "No [content/media] found. Try broader keywords, removing descriptive terms, or a different [content type/source]." |
 | Invalid user selection | Re-display options and ask again |
-| Tool returns error (invalid input, missing argument, or otherwise) | Show error message, offer retry with corrected parameters **on that same tool — never fall through to the other route's search tool as a workaround** (see Key Principle 3) |
+| Tool returns error (invalid input, missing argument, or otherwise) | Show error message, offer retry with corrected parameters **on that same tool — never fall through to the other route's search tool as a workaround** (see Key Principle 3); hybrid language errors: offer one no-language retry, with the user's OK (see media route) |
 | Search tool on the connected server returns a server error (5xx, timeout, connection failure — not "no results") | **Fail the call — do NOT silently retry against a different server.** Tell the user to check that server's connection/session and wait before retrying. |
 
 **Never silently fail on a route the user asked for.** If one route in a mixed request comes up empty, still present the other route's results and say so explicitly. This does not mean substituting a different server when the connected one errors — see the server-error row above.

package/skills/experience-search-coordinate/references/media-route.md

@@ -109,10 +109,25 @@ Keyword/taxonomy extraction rule: see `SKILL.md` Step 4 point 2. Extract taxonom
 
 ## Search using Data 360 hybrid search (`search_electronic_media`)
 
-1. Use the user's query **as-is** — no keyword extraction or transformation needed
-2. Call `search_electronic_media(searchQuery="<user's query>")`
+1. Pass `searchQuery` **verbatim** — same language, same script as the user wrote it. No translation, no keyword extraction: translating first only makes step 2 harder, since you'd be detecting the language of your own translation instead of the user's actual words.
+2. **Determine language** — a short ISO code read directly off the user's literal wording, before any translation happens in your reasoning. Bare 2-letter codes (`en`, `fr`, `de`, `es`, `ja`, ...) cover most languages and are the validated, simpler form; a few regional splits need a country suffix instead (`pt_BR`, `zh_CN`, `zh_TW`, ...). Default to `en` only when the message is genuinely ambiguous (e.g. a bare product name) — never because translating felt natural. Use the bare 2-letter form whenever one exists — the backend accepts only the platform's own language codes, so `fr` works but `fr_FR` is rejected as invalid (`en` and `en_US` both work because `en_US` is itself a platform code).
+3. Call `search_electronic_media(searchQuery="<verbatim query>", searchLanguage="<language code>")`. **Only send `searchLanguage` if the tool's input schema actually lists it** — orgs without language-variant search enabled don't declare the input at all. When it's absent, call with `searchQuery` alone, skip the language line in the confirmation message, and skip steps 4–5 (the backend searches primary-language content only).
+4. **Offer one retry with `searchLanguage` omitted entirely — ask the user first, never retry silently — but only when the first call either:**
+   - returns **zero results**, **or**
+   - fails with an **input-validation error about the language value itself** — an unrecognized language code errors the whole call (for example, `INVALID_API_INPUT` / "Specify a valid language code, such as en_US, fr, or de.") rather than returning an empty list.
 
-Example: user query "modern luxury apartment with natural lighting" → `search_electronic_media(searchQuery="modern luxury apartment with natural lighting")`
+   **Do NOT offer this retry on a server or transport error (5xx, timeout, connection failure).** Those must fail per `SKILL.md`'s Error Handling table — omitting the language cannot fix them and would mask the real failure. The retry exists only for the two language-specific cases above.
+
+   Offer it before concluding nothing exists and before suggesting broader keywords: tell the user what happened in plain chat text (e.g. "No results found in French."), then `ask_followup_question` with options `Yes - search without language filter` / `No - stop here`. The retry is a second backend call the user didn't confirm, so they decide whether it runs. Skip the question only if the user already said, in this conversation, to fall back to any language when nothing matches theirs — then retry directly. Omitting the field makes the backend fall back to each item's own primary/default language variant instead of the requested one — so an item that only has, say, a French variant still surfaces on the retry even when the user asked in English. Only fall through to "no results" / broadening suggestions if the user declines, or the retry also comes back empty.
+5. **Read each result item's `language` field to know which language variant you actually got** (a locale string such as `en_US` or `fr`). If it differs from the language the user asked for — typically after the retry — say so explicitly when presenting that item, e.g. "No French version exists for this item — here's the original in English." Never present a fallback-language result as if it were the requested-language match; the user needs to know a substitution happened.
+
+   If `language` is **absent** on the results of a call that sent `searchLanguage`, the backend couldn't apply the language filter (for example, the org's search index predates language-variant support) and silently returned primary-language content instead — even on the first call, with no error and no empty list. Don't claim the results are in the requested language; tell the user the search couldn't be restricted to that language.
+
+This is a **strict** filter, not soft ranking like the keyword route: the backend only returns items carrying that exact language variant, and it does **not** fall back to English (or any other language) per item on its own — that's why step 4's retry exists as an explicit, user-approved second call, not something the backend does silently.
+
+Example — French input "trouve-moi une image de pinceaux depuis le CMS" → `search_electronic_media(searchQuery="trouve-moi une image de pinceaux depuis le CMS", searchLanguage="fr")`.
+
+Example of the retry — English input "give me an image of a snowboard from the CMS" → first call `search_electronic_media(searchQuery="give me an image of a snowboard from the CMS", searchLanguage="en")` returns zero results (the only snowboard item in the org has a French variant, not English) → tell the user "No results found in English." and ask whether to search without the language filter → user picks `Yes - search without language filter` → retry `search_electronic_media(searchQuery="give me an image of a snowboard from the CMS")` with `searchLanguage` omitted → the item surfaces with `language: "fr"` → tell the user: "No English version exists for this item — here's the original in French."
 
 ## Confirming the query before searching
 
@@ -130,11 +145,22 @@ I'll search for media with these parameters:
   Channels: Public
 ```
 
+**Message 1 — Data 360 hybrid search variant** (surface the detected language so the user can catch a mis-detection before the search runs — language detection is the most error-prone step of this route):
+
+```text
+I'll search Data 360 hybrid search with:
+
+  Query: trouve-moi une image de pinceaux depuis le CMS
+  Language: fr   (auto-detected — tell me if this is wrong)
+```
+
+Show `Query` exactly as the user wrote it (verbatim) and `Language` as the bare code you'll send. This route has no `Content Type` / `Keywords` / `Taxonomies` / `Channels` lines — it ignores channel scope and does its own semantic matching.
+
 **Message 2 (immediately after):** `ask_followup_question` with options `Yes - search now` / `Edit search` / `Cancel`.
 
 ## Presenting Search Results
 
-1. **Parse each call's response** — Extract all results (title and content type) and each item's full `managedContentChannelDeliveryDetails` array, merged across calls if the item appears in more than one response (per "Executing the search call(s)" above — nothing is dropped as a duplicate).
+1. **Parse each call's response** — Extract all results (title and content type) and each item's full `managedContentChannelDeliveryDetails` array, merged across calls if the item appears in more than one response (per "Executing the search call(s)" above — nothing is dropped as a duplicate). Data 360 hybrid search results have a different shape: each item carries `mediaUrl` (or a `mediaUrls` list of `{channelId, channelName, url}`) instead of `managedContentChannelDeliveryDetails`, plus a `language` field when language-variant search applied — use `language` per step 5 of "Search using Data 360 hybrid search" above.
 2. **Use `ask_followup_question`** to present ALL results as selectable **unique** options (one option per item, by identifier), grouped by content type — same grouping key as the Content Route (see `content-route.md` Step 6), never by channel. Show the title, content type, and channel on each option — do not display the URL. If an item's `managedContentChannelDeliveryDetails` array has more than one entry, show the **first** entry's channel name here as a lightweight hint only; the actual choice between channels is made after selection (see "Disambiguating channel at selection" below), not here. If more than one content type FQN is in scope, order the options by content type (the tool has no native grouping — approximate it by ordering and, where the UI allows a label, prefixing the option text with the content type). Regardless of grouping, always include the channel as a per-item suffix, e.g. `Product Launch Hero Banner (sfdc_cms__image) — Public`.
 3. **Receive the user's selection** from the tool response
 

package/skills/experience-ui-bundle-features-generate/SKILL.md

@@ -10,7 +10,7 @@ metadata:
       semver: ">=7.0.0"
     - tool: ["npm"]
       semver: ">=7.0.0"
-  accessCheck: "(OrgPreferences.Sites) && (License.ExperienceCloudCustomerCommunityCustomerCommunityPlus)"
+  accessCheck: "OrgPermissions.Networks"
 ---
 
 # UI Bundle Features

package/skills/experience-ui-bundle-mfa-configure/SKILL.md

@@ -10,7 +10,7 @@ metadata:
       semver: ">=1.6"
     - tool: ["sf"]
       semver: ">=2.0.0"
-  accessCheck: "License.ExperienceCloudCustomerCommunityCustomerCommunityLogin"
+  accessCheck: "OrgPermissions.Networks"
   relatedSkills:
     - "dx-org-permission-set-assign"
     - "experience-ui-bundle-deploy"

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-role-hierarchy-apply/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: platform-role-hierarchy-apply
+description: "Bulk-realign an existing Salesforce UserRole hierarchy from an external org-chart artifact (PDF, xlsx, or plain-text list of role-and-parent pairs) in one admin-approved manifest. Clarify scope and whether users move with roles, resolve identities that do not match verbatim, diff the artifact against the current tree, and submit create, rename, reparent, empty-role delete, and user-assignment mutations together. Triggers on \"reorganize the role hierarchy\", \"apply this org chart to roles\", \"bulk update role parents\", \"realign roles from PDF\", \"restructure the role hierarchy\", \"reparent roles from this spreadsheet\". Do not trigger for a single role create, rename, or reparent with no other changes, or for asking which roles exist or how they are nested — that is `managing-roles`. Do not trigger for territory, account, or forecast hierarchies, or for authoring sharing rules."
+metadata:
+  version: "1.0"
+---
+
+# Role Hierarchy Restructure
+
+Apply many UserRole changes from an artifact in one admin-approved manifest.
+
+If the admin only asks which roles exist or how they are nested, hand off to `managing-roles`. Do not query, do not ask the step 0 questions, and do not submit.
+
+## Inputs
+
+- PDF org chart (text-selectable), `.xlsx` / `.csv` with `role_name` and `parent_role_name` (empty parent = top-level), or plain text with one `Role: Parent` pair per line.
+- Or a pre-parsed list of `{roleName, parentRoleName}` objects.
+- Optional mapping hints when a chart name is not the org's `Name` or `DeveloperName`.
+
+## Flow
+
+### 0. Clarify before querying
+
+Ask anything still unresolved. Do not guess.
+
+- **Scope.** Default is selected branches: roles absent from the artifact stay. "Full hierarchy" still does not delete those roles unless the admin asked for each deletion.
+- **User reassignment.** Default is no. Do not emit `AssignUser` or `MoveUser` without an explicit yes.
+- **Ambiguous identities.** Resolve every role and user in one batch. See step 2.
+- **Conflicts.** Two parents for one role, or a role parented to itself: stop until the admin picks.
+
+If the artifact matches fewer than 20% of its roles to the current tree, stop and ask whether it is a greenfield replacement, the wrong file, or a mapping problem. Do not build a manifest until the admin confirms a greenfield replacement. Between 20% and 50%, show the fraction in the preview and continue.
+
+### 1. Read the current hierarchy
+
+```text
+SELECT Id, DeveloperName, Name, ParentRoleId
+FROM   UserRole
+LIMIT  10000
+```
+
+Match artifact roles by `DeveloperName`, then case-insensitive `Name`.
+
+### 2. Parse the artifact and resolve identities
+
+Normalize to `{roleName, parentRoleName, users?}` and show that list to the admin before the diff. A PDF that is not text-selectable cannot be parsed. Ask for a plain-text `Role: Parent` list.
+
+Roles: exact `DeveloperName`, then case-insensitive `Name`. No fuzzy match. When more than one role matches, list each candidate's `DeveloperName` and `Id` and wait. Do not pick one. Unresolved names go back to step 0.
+
+Users, only after reassignment was confirmed:
+
+1. 18-character id starting with `005` → `User.Id`
+2. Email → `User.Email`
+3. Username → `User.Username`
+4. Display name → `User.Name`, and only when exactly one active user matches
+
+`IsActive = false` is a non-match. A user listed under two roles is a conflict. Ask which role that user should land under, or whether to drop the reassignment. Do not submit until the admin answers.
+
+Stop on a cycle in the target graph. Report the path, for example `A → B → C → A`, and ask for a corrected artifact. Do not submit.
+
+### 3. Build the manifest
+
+Each mutation has `operationId`, `operationType`, `dependsOnOperationIds`, and one nested payload. `dependsOnOperationIds` is the order that matters.
+
+| operationType | Nested object | Use when |
+|---|---|---|
+| `CreateRole` | `createRole` | Role is in the artifact and not in the org. Set `roleReference`, `developerName`, `name`, and `parentRoleId` or `parentRoleReference`. Default the three account-owner access fields to the org defaults when the artifact omits them. |
+| `ReparentRole` | `reparentRole` | Role exists and the parent differs. Set `targetRoleId` or `targetRoleReference`, `expectedParentRoleId`, and `desiredParentRoleId` or `desiredParentRoleReference`. |
+| `RenameRole` | `renameRole` | Same role, different label or developer name. Set the expected and desired name fields. |
+| `DeleteRole` | `deleteRole` | Admin asked to remove an empty role. Set `targetRoleId`, `expectedParentRoleId`, `expectedAssignedUserIds`, and `expectedDirectChildRoleIds`. |
+| `AssignUser` or `MoveUser` | `userRoleAssignment` | Reassignment was confirmed. Set `userId`, `expectedCurrentRoleId`, and `desiredRoleId` or `desiredRoleReference`. |
+
+`DeleteRole` applies only when the role has no direct children and no assigned users at the moment it runs. Reparent those children and move those users in earlier mutations, and put those `operationId`s in `dependsOnOperationIds`. The delete's expected user and child lists are then empty. If the admin declined reassignment, do not delete a role that still has users.
+
+A mutation that names a role neither in the org nor created in this manifest is `missing-parent`. Name the roles that point at it. Ask whether to add a `CreateRole` for it in this manifest, skip those rows, or abort. Do not submit with that parent missing.
+
+A cycle in `dependsOnOperationIds` blocks the submit. Give every new role a `roleReference` string and point parents and assignments at that string.
+
+### 4. Validate, then preview
+
+Block the submit when any of these remain: a cycle, a missing parent, a duplicate `developerName`, a dependency cycle, an `AssignUser` or `MoveUser` without the step 0 yes, a `DeleteRole` whose expected user or child lists are not empty, or overlap under 20% without a confirmed greenfield replacement.
+
+On a duplicate `developerName`, show both rows and wait until the admin picks one or renames one.
+
+Warn in the preview, and continue only after an explicit yes:
+
+- A changed role is referenced by `Territory2.UserRoleId` or a forecast hierarchy override.
+- A changed role has `PortalType != 'None'`.
+- A changed role has more than 500 users (`SELECT COUNT() FROM User WHERE UserRoleId = :id`).
+
+```text
+Restructure preview
+-------------------
+  ReparentRole : 42
+  CreateRole   :  3
+  RenameRole   :  1
+  DeleteRole   :  2
+  MoveUser     :  2
+
+  Territory / forecast references : 1
+  Portal roles                    : 0
+  Roles with more than 500 users  : 2
+
+Approve this restructure? [yes / no]
+```
+
+`yes` submits. Anything else does not. Roles left in the org and absent from the artifact stay in place.
+
+### 5. Submit
+
+```text
+POST /services/data/v{version}/sharing/role-hierarchy-restructure
+{
+  "operation": "Save",
+  "mutations": [
+    {
+      "operationId": "reparent-sales-vp",
+      "operationType": "ReparentRole",
+      "dependsOnOperationIds": [],
+      "reparentRole": {
+        "targetRoleId": "00E000000000001",
+        "expectedParentRoleId": "00E000000000002",
+        "desiredParentRoleReference": "cro"
+      }
+    },
+    {
+      "operationId": "delete-legacy-region",
+      "operationType": "DeleteRole",
+      "dependsOnOperationIds": ["reparent-legacy-children"],
+      "deleteRole": {
+        "targetRoleId": "00E000000000003",
+        "expectedParentRoleId": "00E000000000002",
+        "expectedAssignedUserIds": [],
+        "expectedDirectChildRoleIds": []
+      }
+    }
+  ]
+}
+```
+
+`CreateRole`, `RenameRole`, `AssignUser`, and `MoveUser` use the same envelope with their nested object from step 3.
+
+Send the approved manifest once. Do not edit `UserRole` records one by one.
+
+### 6. Read the response
+
+- `Applied` — structural and sharing changes committed.
+- `AppliedSharingPending` — hierarchy is live; sharing catches up on its own. Do not poll.
+- `AsyncExecutionRequired` — the server queued the manifest. Do not poll.
+- `RoleOperationInProgress` — another restructure is running. Stop. Do not queue the manifest. Ask the admin to retry once the other operation finishes.
+- `NotApplied` — nothing committed. Show `reasonCodes` and stop.
+- `404` on submit — API not enabled for this client tier. Halt, tell the admin, do not retry, do not fall back to per-record `/sobjects/UserRole` edits.
+
+For each `operationResults[]` entry, `outcome` is `Applied`, `NotApplied`, or `DependencyNotApplied`. Show `reasonCode` for any entry that is not `Applied`. Do not retry and do not roll back.
+
+## Out of scope
+
+- A single role create, rename, or reparent with no other changes, and any request that only asks which roles exist or how they are nested (`managing-roles`).
+- Territory, account, and forecast hierarchies.
+- Authoring sharing rules.
+- Image-only PDFs. Ask for text.
+- Rollback. Report what the response says was committed.
+---
+
+<!-- skill-validate: ignore-start -->
+<!-- codey:operations start -->
+## Operations Reference
+
+Operations this skill uses — routing and dependency reference.
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `read-role-hierarchy` | read | — | `GET /services/data/v68.0/query` | — |
+| `count-users-per-role` | read | — | `GET /services/data/v68.0/query` | `read-role-hierarchy` |
+| `submit-role-hierarchy-restructure` | write | — | `POST /services/data/v68.0/sharing/role-hierarchy-restructure` | `read-role-hierarchy` |
+| `verify-role-hierarchy-restructure` | verify | — | `GET /services/data/v68.0/query` | `submit-role-hierarchy-restructure` |
+<!-- codey:operations end -->
+<!-- skill-validate: ignore-end -->