@salesforce/afv-skills 1.66.0 → 1.67.0

package/skills/education-cloud-domain-configure/SKILL.md

@@ -2,7 +2,7 @@
 name: education-cloud-domain-configure
 description: "Use this skill to configure Education Cloud domains (Student Success, Recruitment & Admissions, Academic Operations, Alumni Relations, Student Management, or Mentoring) through conversational setup. Triggers when a user wants to enable or configure Education Cloud features. Guides step-by-step: enables Person Accounts prerequisite, activates target domain, then configures domain sub-features. Covers support processes, case record types, success teams, care plans, applications, admissions, course catalog, alumni engagement, fundraising, enrollment, programs, and mentoring. Explains each feature, confirms before proceeding, verifies every change took effect, and warns that domain and feature toggles are IRREVERSIBLE. DO NOT TRIGGER for metadata generation, custom objects, or package deployment — this configures existing platform features via org settings, not metadata files."
 metadata:
-  version: "1.0"
+  version: "1.1"
   minApiVersion: "60.0"
   domains:
     - "Education"
@@ -66,7 +66,13 @@ Every domain/sub-feature toggle lives on the `IndustriesSettings` settings file
 
 Before first call, probe transport health: `GET /services/data/vXX.X/limits` via headless-360 dispatch. 2xx → route all calls through it. On absent/4xx/5xx → probe other available transports (other Salesforce MCP, authenticated `sf` CLI, custom MCP) with the same read, use first healthy, announce it. None healthy → stop, ask user to connect one; never fabricate.
 
-> **SOQL routes via headless-360 — pass the query through `queryParams`, NOT inline `?q=` in `url`.** `GET /services/data/vXX.0/query` (or `/tooling/query`) with `queryParams: {"q": "SELECT ..."}` returns records normally; putting `?q=...` directly in the `url` string 404s (`ROUTE_NOT_FOUND`) — a call-shape mistake, not a platform limitation. `?fields=` on a plain sObject GET is still not supported (router treats it as an external-id path segment) — use `/describe` for field lists instead. Prefer a direct SOQL existence/Id lookup over asking the user to supply a record Id; where no REST route exists at all (license/permission provisioning UI-only), ask the user or confirm in Setup UI.
+> **SOQL routes via headless-360 — pass the query through `queryParams`, NOT inline `?q=` in `url`** (inline 404s with `ROUTE_NOT_FOUND`). Call-shape detail: `references/gotchas-extended.md` ("Transport call shapes").
+
+---
+
+## Setup Widgets
+
+Five HXL widgets (`display_widget`: Intent, Review, Plan, Apply, Verify) visualize the workflow. Render each automatically at its checkpoint; never ask whether to show one. They are visual aids, never gates: if the host or org cannot paint them, continue in text. Compute every prop from live reads. A click on a row's action button (for example Enable) is the user's approval of that one item: no separate confirmation turn. Checkpoints, prop contracts, render call, and fallback: `references/setup-widgets.md`.
 
 ---
 
@@ -76,6 +82,8 @@ Before first call, probe transport health: `GET /services/data/vXX.X/limits` via
 
 All Education Cloud domains require these foundation settings. Verify before proceeding to domain configuration.
 
+> **Visual review.** After the Phase 0, 1, and 1.5 reads, render the 8 prerequisites once with `HxlSetupReview` (see Setup Widgets), then walk the pending items conversationally. Re-render after each enable.
+
 1. **Check org edition** — query `GET /services/data/v68.0/query` with `queryParams: {"q": "SELECT OrganizationType FROM Organization"}` (singleton, no Id needed), then pipe the record into `scripts/check_org_edition.py --allowed "Enterprise Edition,Performance Edition,Unlimited Edition,Developer Edition"` (stdin: `{"records": [...]}`). `eligible: false` → warn user Education Cloud requires Enterprise+ edition.
 
 2. **Check Lightning Experience** — verify Lightning Experience is enabled. If not enabled, instruct user to navigate to Setup → User Interface → Enable Lightning Experience.
@@ -98,13 +106,15 @@ All Education Cloud domains require these foundation settings. Verify before pro
    - Student Management
    - Mentoring
 
+   Render `HxlSetupIntent` with these six domains and their status.
+
 7. **Explain Person Accounts** — explain: "Person Accounts are required for Education Cloud. They allow individuals (students, applicants, alumni) to be tracked as both Accounts and Contacts in a unified record."
 
    > **WARNING**: Person Accounts cannot be disabled once enabled. Confirm user understands this is irreversible before proceeding.
 
 8. **Enable Person Accounts (UI)** — Person Accounts has no supported org-preferences write API (the `setup/org/preferences/{name}` endpoint returns 404). Instruct user to navigate to Setup → Quick Find → "Account Settings" → Select Account Settings → Turn on "Enable Person Accounts" → Click Save. Wait for user confirmation toggle is ON and saved, then proceed to Phase 1.5.
 
-    To verify: `GET /services/data/v68.0/sobjects/Account/describe` and confirm `IsPersonAccount`/`Person*` fields are present in the `fields` array; if headless routing is unavailable, fall back to `sf sobject describe -s Account` and grep for the same. This describe call is the ONLY valid verification method — do NOT run any SOQL query against `IsPersonAccount` or Person-Account fields (on `Account`, `Organization`, or any object) to check enablement status; SOQL on an unrecognized field returns `INVALID_FIELD`/"No such column", and that failure does NOT mean Person Accounts is off — it means you used the wrong check.
+    To verify: `GET /services/data/v68.0/sobjects/Account/describe` and confirm `IsPersonAccount`/`Person*` fields are present. This describe call is the ONLY valid check; never run SOQL against `IsPersonAccount` or Person-Account fields (see `references/gotchas-extended.md`, "Person Accounts verification").
 
 ### Phase 1.5 — Setup Basics: Dependent Features & Data Space Mapping
 
@@ -112,11 +122,7 @@ This mirrors Setup's own "Setup Basics" grouping (Person Accounts, Dependent Fea
 
 9. **Present Dependent Features** — read `references/dependent-features.md` and present the full list to the user, grouped by category (confirmed API toggle / manual-UI-only / untested), leading with feature name + one-line "what it does", not the API element name. **Always present this list and ask which to enable now**, even if the user declines all of them — record that decision explicitly and proceed to Phase 2 rather than skipping the step. Anything declined can be revisited later.
 
-10. **Configure each selected Dependent Feature** — `references/dependent-features.md` categorizes every feature into one of four shapes; look up the selected feature there for its exact element names, DurableIds, and gotchas:
-    - **Confirmed `IndustriesSettings` toggle** — IRREVERSIBLE, warn user. Use the **Domain & Feature Toggle Write Path**: READ → WRITE (`PUT /services/data/v68.0/headless/metadata`) → cold-VERIFY.
-    - **Confirmed toggle via a different mechanism** (e.g. Einstein Generative AI master toggle) — a Setup-Connect **org preference**, not `IndustriesSettings`: `GET /services/data/v68.0/setup/org/preferences/<PrefName>` → `PATCH` same path with `{"desiredState": true|false}` → cold-VERIFY. Some of these are reversible — check the reference before assuming one-way.
-    - **Overlaps a domain sub-feature** (several toggles are shared with Student Success and/or Mentoring sub-features) — cold-read first; if already `true` from a prior domain's configuration, report as already enabled rather than re-writing.
-    - **Manual UI only, no API route** — instruct user to the Setup path in the reference. Flag where a custom permission set / object permissions are also required, not just a toggle — surface as manual follow-up.
+10. **Configure each selected Dependent Feature** — `references/dependent-features.md` ("Configuration shapes") categorizes every feature into one of four shapes (`IndustriesSettings` toggle, org-preference toggle, overlap with a domain sub-feature, manual UI only); look up the selected feature there for its exact element names, DurableIds, and gotchas. Toggles are IRREVERSIBLE unless the reference says otherwise: warn, then READ → WRITE → cold-VERIFY.
 
 11. **Enable OmniStudio** — OmniStudio is included with Education Cloud license. Attempt API call or instruct user to navigate to Setup → OmniStudio Settings → Enable.
 
@@ -128,22 +134,13 @@ This mirrors Setup's own "Setup Basics" grouping (Person Accounts, Dependent Fea
 
 14. **Explain domain purpose** — look up the selected domain in `references/domain-features.md`'s index and open the linked per-domain file (e.g. `references/domain-features/student-success.md`) to explain to user what the domain provides, including prerequisites.
 
-15. **Check domain-specific prerequisites** — beyond OmniStudio/Business Rules Engine (already enabled in Phase 0), most domains need an added license: Experience Cloud (Recruitment & Admissions, Mentoring, and portals generally), Salesforce Scheduler (Student Success, Recruitment & Admissions), Fundraising (Alumni Relations, if using gift management), or a prior domain (Student Management requires Academic Operations already configured). See the selected domain's file under `references/domain-features/` for the full list. If prerequisites are missing, warn user and ask whether to continue with available features or provision prerequisites first.
+15. **Check domain-specific prerequisites** — beyond OmniStudio/Business Rules Engine (Phase 0), most domains need an added license or a prior domain; the per-domain list is in `references/domain-features.md` ("Domain prerequisites"). If prerequisites are missing, warn user and ask whether to continue with available features or provision prerequisites first. Render `HxlSetupReview` with these domain prerequisites.
 
 16. **Confirm domain enablement** — **IRREVERSIBLE — one-way by design (`false → true` only).** Warn the user explicitly and do NOT promise a revert/rollback. Ask: "Ready to enable [Domain Name]? This activates domain-specific objects, fields, and setup features and CANNOT be turned off afterward."
 
 17. **Enable the domain toggle** — each domain is an `enableXXX` field on `IndustriesSettings`. Follow the **Domain & Feature Toggle Write Path**: READ (tooling GET via DurableId) → WRITE (`PUT /services/data/v68.0/headless/metadata` with the single `<enableXXX>true</enableXXX>` element in `xmlRep`, via the `dispatch` write tool) → VERIFY (tooling GET shows `true`).
 
-    Toggle field per domain:
-
-    | Domain | `IndustriesSettings` field |
-    |--------|----------------------------|
-    | Student Success | `enableStudentSuccess` |
-    | Academic Operations | `enableAcademicOperations` |
-    | Mentoring | `enableMentoring` |
-    | Alumni Relations | `enableAlumniRelations` |
-    | Recruitment & Admissions | **No master toggle** — configured via 2 independent sub-feature settings (`enableApplnDecStdSharing`, `enableAppMaterialsProtection`); skip this step, go to `references/domain-features/recruitment-admissions.md` "Enablement & Toggles" |
-    | Student Management | `enableStudentManagement` |
+    Toggle field per domain: `references/domain-features.md` ("Domain toggle fields"). Recruitment & Admissions has no master toggle; skip this step and go to `references/domain-features/recruitment-admissions.md` "Enablement & Toggles".
 
     On success (`200 { success: true }`, synchronous, no polling), proceed to step 18. On failure, instruct user to navigate to Setup → "Set Up Education Cloud" → the domain section (e.g., "Set Up the Student Success App") → turn on the domain toggle → Save, and wait for confirmation.
 
@@ -153,11 +150,11 @@ This mirrors Setup's own "Setup Basics" grouping (Person Accounts, Dependent Fea
 
 19. **Read sub-feature reference** — load the selected domain's file under `references/domain-features/` to identify available sub-features and their detailed setup steps.
 
-20. **Present sub-feature options** — list the sub-features available for the domain (per the domain's `references/domain-features/` file) and ask user which to configure. Student Success has a required execution order (Support Process → Case Record Types → Success Teams → Care Plans → Support Programs → Salesforce Scheduler → consoles/portal); the other domains' sub-features are independent of each other.
+20. **Present sub-feature options** — list the sub-features available for the domain (per the domain's `references/domain-features/` file) and ask user which to configure. Student Success has a required execution order (Support Process → Case Record Types → Success Teams → Care Plans → Support Programs → Salesforce Scheduler → consoles/portal); the other domains' sub-features are independent of each other. Render `HxlSetupPlan` once the selection is known.
 
-21. **Configure each selected sub-feature** — explain what it does, warn if irreversible, confirm with user, then follow the exact setup path in the domain's `references/domain-features/` file (covers all five shapes: record creation via Data/Tooling API, `IndustriesSettings` toggles via the Toggle Write Path, app/console setup, Experience Cloud portal setup, OmniStudio activation — with endpoints, body shapes, gotchas, and verification per sub-feature). Toggles follow the same IRREVERSIBLE + READ→WRITE→cold-VERIFY rule as domain toggles; cold-read first if already set from Phase 1.5. On API failure, fall back to the Setup UI path in the reference.
+21. **Configure each selected sub-feature** — explain what it does, warn if irreversible, confirm with user (a click on the row's widget button counts as that confirmation), then follow the exact setup path in the domain's `references/domain-features/` file (covers all five shapes: record creation via Data/Tooling API, `IndustriesSettings` toggles via the Toggle Write Path, app/console setup, Experience Cloud portal setup, OmniStudio activation — with endpoints, body shapes, gotchas, and verification per sub-feature). Toggles follow the same IRREVERSIBLE + READ→WRITE→cold-VERIFY rule as domain toggles; cold-read first if already set from Phase 1.5. On API failure, fall back to the Setup UI path in the reference. Render `HxlSetupApply` and re-render it after each item's cold-verify.
 
-22. **Summary** — after all sub-features configured, list what was enabled via which method (API, UI, OmniStudio). Report any failures or manual steps required. If suggesting next steps, limit them to genuine blockers/dependencies actually surfaced during this session (e.g. a prerequisite that's still off, a sub-feature the user asked about but deferred) — not a generic list of every related feature or domain regardless of relevance.
+22. **Summary** — after all sub-features configured, list what was enabled via which method (API, UI, OmniStudio). Report any failures or manual steps required. If suggesting next steps, limit them to genuine blockers/dependencies actually surfaced during this session (e.g. a prerequisite that's still off, a sub-feature the user asked about but deferred) — not a generic list of every related feature or domain regardless of relevance. Render `HxlSetupVerify` with one row per cold-verified write.
 
 ---
 
@@ -203,7 +200,7 @@ Do not include a feature in the final summary as "enabled" unless both its appro
 
 ## Output Expectations
 
-This skill produces no files — configuration happens via Setup navigation, CLI commands, or API calls. Expected outputs: conversational confirmation after each step, verification results showing configuration is active, error messages with suggested fixes on failure, and a final summary listing all configured features.
+This skill produces no files — configuration happens via Setup navigation, CLI commands, or API calls. Expected outputs: conversational confirmation after each step, HXL Setup widgets (Intent, Review, Plan, Apply, Verify via `display_widget`) reflecting live state where the host and org support them, verification results showing configuration is active, error messages with suggested fixes on failure, and a final summary listing all configured features.
 
 ---
 
@@ -226,6 +223,7 @@ This skill produces no files — configuration happens via Setup navigation, CLI
 | `references/domain-features.md` | Index of per-domain reference files — start here to find the right file for the selected domain |
 | `references/domain-features/<domain>.md` | Phase 2 step 14 (explain domain purpose), Phase 3 step 19 (identify sub-features), Phase 3 step 21 (sub-feature configuration setup paths and API preference names) |
 | `references/dependent-features.md` | Phase 1.5 steps 11-12 (Setup Basics — present and configure Dependent Features before any domain), and whenever the user asks about a cross-product feature not owned by one domain — surface as "Set Up Dependent Features" and note domain overlap where relevant |
+| `references/setup-widgets.md` | Steps 6, 15, 20, 21, 22 and the Phase 0 review (prop contracts and Education Cloud mapping for the 5 HXL Setup widgets) |
 | `references/gotchas-extended.md` | When an error doesn't match one of the 10 entries in the Gotchas table above |
 | `scripts/check_org_edition.py` | Phase 0 step 1 (org edition check) |
 | `scripts/check_license_provisioned.py` | Phase 0 step 3 (Education Cloud license check) |

package/skills/education-cloud-domain-configure/references/dependent-features.md

@@ -196,3 +196,12 @@ DELETE /headless/invoke/platform/data-space-feature-mappings/delete-data-space-f
 
 - **Managed Package Runtime** — skipped at user's explicit request; do not attempt to enable.
 - **Deploy Custom LWC in Standard Runtime** — skipped at user's explicit request; do not attempt to enable.
+
+## Configuration shapes
+
+Every dependent feature is one of four shapes:
+
+- **Confirmed `IndustriesSettings` toggle** — IRREVERSIBLE, warn user. Use the **Domain & Feature Toggle Write Path**: READ → WRITE (`PUT /services/data/v68.0/headless/metadata`) → cold-VERIFY.
+- **Confirmed toggle via a different mechanism** (e.g. Einstein Generative AI master toggle) — a Setup-Connect **org preference**, not `IndustriesSettings`: `GET /services/data/v68.0/setup/org/preferences/<PrefName>` → `PATCH` same path with `{"desiredState": true|false}` → cold-VERIFY. Some of these are reversible — check the reference before assuming one-way.
+- **Overlaps a domain sub-feature** (several toggles are shared with Student Success and/or Mentoring sub-features) — cold-read first; if already `true` from a prior domain's configuration, report as already enabled rather than re-writing.
+- **Manual UI only, no API route** — instruct user to the Setup path in the reference. Flag where a custom permission set / object permissions are also required, not just a toggle — surface as manual follow-up.

package/skills/education-cloud-domain-configure/references/domain-features.md

@@ -25,3 +25,18 @@ Configuration guide for each Education Cloud domain and its sub-features. Based
 - Write domain/feature toggles via the headless metadata PUT path (IndustriesSettings `xmlRep`, write `dispatch` tool); never `setup/org/preferences/{name}` (404). Fall back to UI instructions only on error
 - EDU toggles are IRREVERSIBLE (`false → true` only) — warn the user, never promise a revert
 - Student Management has no separate domain toggle — it is enabled when Academic Operations is configured with student enrollment records
+
+## Domain prerequisites
+
+Beyond OmniStudio/Business Rules Engine (enabled in Phase 0), most domains need an added license: Experience Cloud (Recruitment & Admissions, Mentoring, and portals generally), Salesforce Scheduler (Student Success, Recruitment & Admissions), Fundraising (Alumni Relations, if using gift management), or a prior domain (Student Management requires Academic Operations already configured). See the selected domain's file under `references/domain-features/` for the full list.
+
+## Domain toggle fields
+
+| Domain | `IndustriesSettings` field |
+|--------|----------------------------|
+| Student Success | `enableStudentSuccess` |
+| Academic Operations | `enableAcademicOperations` |
+| Mentoring | `enableMentoring` |
+| Alumni Relations | `enableAlumniRelations` |
+| Recruitment & Admissions | **No master toggle** — configured via 2 independent sub-feature settings (`enableApplnDecStdSharing`, `enableAppMaterialsProtection`); skip this step, go to `references/domain-features/recruitment-admissions.md` "Enablement & Toggles" |
+| Student Management | `enableStudentManagement` |

package/skills/education-cloud-domain-configure/references/gotchas-extended.md

@@ -22,3 +22,11 @@ Lower-frequency gotchas and toggle-write failure classes, split out of `SKILL.md
 | **Failure class — type-level UPDATE block** (e.g. Timeline `TimelineSettings`, Video Calls `VideoCallsSettings`) | PUT returns HTTP 400 `UNSUPPORTED_OPERATION: "MetadataCrud does not support UPDATE on type: X"` — block is on the whole type, no `fullName` variant fixes it; manual UI only |
 | **Pattern — org preference API, not `IndustriesSettings`** (confirmed on Einstein Generative AI, `EinsteinGPTCopilotEnabled`) | Some toggles are Setup-Connect org preferences, not `IndustriesSettings` metadata fields — no `type`/`fullName`/`xmlRep`. Shape: `GET /services/data/v68.0/setup/org/preferences/<PrefName>` → `{"isPreferenceEnabled": bool}`; `PATCH` same path with `{"desiredState": true}` → response echoes post-write state. If a metadata PUT returns `FIELD_INTEGRITY_EXCEPTION: invalid at this location` for a plausible-looking element name, the field may not be on `IndustriesSettings` at all — try this org-preference path next before assuming manual-UI-only |
 | **Failure class — write-enabled `dispatch` MCP tool not connected/loaded** | Fall back to the `sf api request rest` CLI (via Bash) for the exact same READ/WRITE/cold-VERIFY calls before giving up to manual Setup UI — confirmed working in the same run where other datasets hit this identical MCP gap. Never report a toggle's state as "assumed default" or "pending admin confirmation" without trying this fallback first |
+
+## Transport call shapes
+
+**SOQL routes via headless-360 — pass the query through `queryParams`, NOT inline `?q=` in `url`.** `GET /services/data/vXX.0/query` (or `/tooling/query`) with `queryParams: {"q": "SELECT ..."}` returns records normally; putting `?q=...` directly in the `url` string 404s (`ROUTE_NOT_FOUND`) — a call-shape mistake, not a platform limitation. `?fields=` on a plain sObject GET is still not supported (router treats it as an external-id path segment) — use `/describe` for field lists instead. Prefer a direct SOQL existence/Id lookup over asking the user to supply a record Id; where no REST route exists at all (license/permission provisioning UI-only), ask the user or confirm in Setup UI.
+
+## Person Accounts verification
+
+`GET /services/data/v68.0/sobjects/Account/describe` and confirm `IsPersonAccount`/`Person*` fields are present in the `fields` array; if headless routing is unavailable, fall back to `sf sobject describe -s Account` and grep for the same. This describe call is the ONLY valid verification method — do NOT run any SOQL query against `IsPersonAccount` or Person-Account fields (on `Account`, `Organization`, or any object) to check enablement status; SOQL on an unrecognized field returns `INVALID_FIELD`/"No such column", and that failure does NOT mean Person Accounts is off — it means you used the wrong check.

package/skills/education-cloud-domain-configure/references/setup-widgets.md

@@ -0,0 +1,123 @@
+# HXL Setup Widgets — prop contracts and Education Cloud mapping
+
+Five widgets give the setup workflow a visual spine. They hold NO logic: compute every field from live reads. Each is a visual aid, never a gate.
+
+## Render call
+
+The widgets live in the shared `hxl-setup-widgets` skill, so nothing is bundled here and nothing is deployed to the org. This file holds only the Education Cloud mapping. Render one with:
+
+```text
+display_widget(
+  resourceType = "skill_widget",
+  apiName = "hxl-setup-widgets/hxlSetup<Step>",
+  props = { ... }
+)
+```
+
+Pass props at the top level of `props` (no `attributes` wrapper). Generic prop rules are also in the `hxl-setup-widgets` skill; the mapping below is Education-specific.
+
+**Fallback.** If `display_widget` is unavailable, the host does not paint MCP Apps widgets, or the call errors (including `widget not found in index`), continue in text for the rest of the session and say so once, in one line. Do not author a widget tree yourself.
+
+## Shared rules
+
+- **When it paints.** Only in hosts that mount MCP Apps widgets, and only where `display_widget` is enabled for the org. A non-mounting host (terminal) → error or text fallback. Continue in text; the numbered steps in SKILL.md are the source of truth. Never block setup on a widget.
+- **Setup links are absolute.** `setupUrl` must be a full `https://` URL on the org's Setup host. A relative path resolves against the chat host, not the org. Build it as `<setup-host>/lightning/setup/<Page>/home`, where `<setup-host>` is the org host with its trailing `.salesforce.com` replaced by `.salesforce-setup.com` (e.g. `https://acme.my.salesforce.com` → `https://acme.my.salesforce-setup.com`). Take the org host from the origin of the `url` field in any headless-360 `dispatch`/`dispatch_readonly` response (the Phase 0 Organization query already returns it).
+- **Gather first, render once.** Finish the step's reads, then render. Re-render only at the checkpoints below.
+- **Nothing hard-coded.** Every status, label, and boolean comes from a read done this session. Never show `Verified` without a passing cold-verify.
+- **Types.** `irreversible` and `enabled` are real booleans, not strings. Optional string fields you have nothing for are `""`, not omitted. A button renders only when `actionLabel` is non-empty, so verified/read-only rows pass `actionLabel: ""`.
+- **`statusVariant`** values: `success`, `warning`, `error`, `info`, `default`.
+- **`kind`** (Review/Apply items): `manual` → the widget draws its own fixed "Open Setup" link button that opens `setupUrl` in a new tab, so always set `setupUrl` and always set `actionLabel: ""` (a non-empty `actionLabel` adds a duplicate second button). Any other value (`action`, `toggle`) → the `actionLabel` button sends `message` back to the chat.
+- **Button click = approval of that one item.** A `message` arrives as a user turn. Treat the click as the user's approval to run that item's write: do not ask again. Read first, write, then cold-verify. The row already shows its Irreversible badge, and the reply that accompanies the render states the one-way warning in plain text (a statement, not a question). A click approves only the item it names.
+- Keep the text reply meaningful alongside each widget. Do not restate rows the widget already shows.
+
+## Checkpoints
+
+| Widget | `apiName` suffix | Call at |
+|--------|-----------|---------|
+| Intent | `hxlSetupIntent` | Phase 1 step 6 (domain choice) |
+| Review | `hxlSetupReview` | After Phase 0 / 1 / 1.5 reads; again at step 15 (domain prerequisites); re-render after each enable |
+| Plan | `hxlSetupPlan` | After step 20 selection, before the first write |
+| Apply | `hxlSetupApply` | Step 21, re-rendered after each item's cold-verify |
+| Verify | `hxlSetupVerify` | Step 22 summary |
+
+## Intent — `hxlSetupIntent`
+
+Props: `heading`, `subheading`, `options[]`.
+
+| Option field | Rule |
+|--------------|------|
+| `name` | Domain name. |
+| `description` | One-line "what it does" from `references/domain-features/<domain>.md`. |
+| `requires` | Domain prerequisites, e.g. Student Management → `Requires Academic Operations`; else `""`. |
+| `statusLabel` / `statusVariant` | `Enabled` / `success` when the domain toggle cold-reads `true`; else `Available` / `default`. Blocked by a missing prerequisite → `Blocked` / `warning`. |
+| `actionLabel` / `actionVariant` | `Configure` / `primary`; `""` when already enabled and nothing to configure. |
+| `message` | `Configure <Domain>`. |
+
+Options: the six domains (Student Success, Recruitment & Admissions, Academic Operations, Alumni Relations, Student Management, Mentoring). Recruitment & Admissions has no master toggle; derive its status from its sub-feature settings and say so in `description`. Skip the widget if the user already named the domain.
+
+## Review — `hxlSetupReview`
+
+Props: `heading`, `subheading`, `checks[]`.
+
+| Check field | Rule |
+|-------------|------|
+| `name` | Check name. |
+| `description` | One-line what it does. |
+| `requires` | Dependency, or `""`. |
+| `kind` | `manual` (Setup UI only) or `action` (skill can do it). |
+| `enabled` | `true` once verified. |
+| `irreversible` | `true` for Education Cloud Foundation and Person Accounts. |
+| `statusLabel` / `statusVariant` | `Verified` / `success`, `Pending` / `default`, or `Action needed` / `warning`. A manual step the user has not done is `Action needed`. |
+| `actionLabel` | `""` when verified, check-only, or `kind: "manual"`; else `Enable`. |
+| `message` | For `action` rows: `Enable <name>`. Else `""`. |
+| `setupUrl` | For `manual` rows: absolute Setup URL (see "Setup links are absolute"). Else `""`. |
+
+**Prerequisite review (after Phase 0/1/1.5 reads)** — eight rows, in order:
+
+| # | Check | kind | Notes |
+|---|-------|------|-------|
+| 1 | Org Edition | `action` | Check-only: `actionLabel ""`. |
+| 2 | Lightning Experience | `manual` | Setup → User Interface. |
+| 3 | Education Cloud License | `action` | Check-only: `actionLabel ""`; not provisioned → contact account team. |
+| 4 | Education Cloud Full Access | `manual` | Setup → Permission Sets. |
+| 5 | Education Cloud Foundation | `action` | `irreversible: true`. |
+| 6 | OmniStudio | `action` | Attempt API, else Setup → OmniStudio Settings. |
+| 7 | Business Rules Engine | `manual` | Setup → Business Rules Engine. |
+| 8 | Person Accounts | `manual` | `irreversible: true`; Setup → Account Settings. |
+
+Heading `Education Cloud prerequisites`; `subheading` = org name and edition.
+
+**Domain prerequisite review (step 15)** — same widget, one row per prerequisite the selected domain needs (Experience Cloud, Salesforce Scheduler, Fundraising, prior domain), per `references/domain-features/<domain>.md`. Heading `<Domain> prerequisites`.
+
+## Plan — `hxlSetupPlan`
+
+Read-only (no action buttons). Props: `heading`, `summary`, `planItems[]`.
+
+| Plan item field | Rule |
+|-----------------|------|
+| `name` | Feature or domain being enabled. |
+| `description` | One-line what it does. |
+| `method` | `Metadata PUT (IndustriesSettings)`, `Invoke endpoint`, `Org preference PATCH`, `Data API create`, or `Manual (Setup UI)`. |
+| `irreversible` | `true` for every one-way toggle. |
+| `impact` | One line of what changes, e.g. `Activates student success objects and setup`. |
+
+One item per pending write the user selected (domain toggle, chosen sub-features, chosen dependent features), in execution order. `summary` = count and how many are irreversible. Render it automatically; do not ask whether to show it. Plan has no buttons, so after rendering ask approve / reject / modify (authoring convention 4) unless the items are executed from Review/Apply button clicks.
+
+## Apply — `hxlSetupApply`
+
+Props: `heading`, `subheading`, `items[]`; item fields identical to Review `checks[]`.
+
+Same items as the approved Plan, with live state: `Pending` / `default`, `Applied` / `success`, `Failed` / `error`, `Action needed` / `warning` (manual step outstanding). `Applied` only after that item's cold-verify passed. Manual rows carry `kind: "manual"`, `setupUrl`, and `actionLabel: ""`; API rows carry `kind: "action"` with a `message`. Re-render after each item completes.
+
+## Verify — `hxlSetupVerify`
+
+Read-only. Props: `heading`, `status`, `statusVariant`, `summary`, `results[]`.
+
+| Result field | Rule |
+|--------------|------|
+| `name` | Feature. |
+| `detail` | The re-read value, e.g. `IsStudentSuccessEnabled = true`. |
+| `statusLabel` / `statusVariant` | `Verified` / `success`, `Failed` / `error`, or `Manual follow-up` / `warning`. |
+| `method` | How it was enabled and verified: `API`, `UI`, or `OmniStudio`. |
+
+`status` = `Complete` / `success` when every row is verified, else `Partial` / `warning`. `summary` = one line with counts. A feature appears as `Verified` only if both boxes in the Final Verification Checklist are checked (approval + cold-verify).

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 |