@salesforce/afv-skills 1.65.1 → 1.67.0

package/skills/dx-devops-work-item-manage/examples/common-workflows.md

@@ -477,3 +477,52 @@ Real-world examples of typical work item operations in DevOps Center autonomous
    ```
 
 > **Note:** The CLI will return a non-zero status with error name `PR_ALREADY_EXISTS` if a PR already exists for that work item.
+
+---
+
+## Workflow 16: Commit Through the DevOps Center API (with git fallback)
+
+**User request:** "Commit the HelloWorld class to WI-000001. My changes are in the dev org <dev-org>."
+
+**Steps:**
+
+1. **Preflight on the dev org** (both orgs must be authenticated):
+   ```bash
+   sf api request rest "/services/data/v67.0/connect/devops/doceConnectionType" --target-org <dev-org>
+   ```
+   `{"isCore": true}` → continue. A failed call or `isCore` not `true` → use the git path (Workflow 3).
+
+2. **Look up the work item on the hub** (status must be New, In Progress, In Review or Ready to Promote):
+   ```bash
+   sf devops project list --target-org <hub-org> --json
+   sf devops work-item list --project-id <project-id> --target-org <hub-org> --json \
+     | jq '.result.workItems[] | select(.name == "WI-000001")'
+   ```
+
+3. **Commit** (body is the inner object, no wrapper; take `workItemId`/`projectId` from step 2):
+   ```bash
+   BODY=$(mktemp)
+   cat > "$BODY" <<'JSON'
+   {"isCommitCore":"true","workItemId":"<work-item-id>","projectId":"<project-id>",
+    "workItemName":"WI-000001","workItemLink":"<work item url>","commitMessage":"Update HelloWorld",
+    "changes":[{"fullName":"HelloWorld","type":"ApexClass","operation":"modify"}]}
+   JSON
+   sf api request rest "/services/data/v67.0/connect/devops/commitChanges" --method POST --body @"$BODY" --target-org <dev-org>
+   rm "$BODY"
+   ```
+   Expect `{"reqId":"<uuid>","status":"SUCCESS"}` (accepted). If the call fails or `status` is `ERROR`, report the error (`CODE:message` in `reqId`) and stop.
+
+4. **Poll until `SUCCESS` or `ERROR`** (every 10 s, up to 12 min):
+   ```bash
+   sf data query --target-org <dev-org> --json \
+     -q "SELECT Status, Message, ErrorDetails FROM DevopsRequestInfo WHERE RequestToken = '<reqId>'"
+   ```
+
+5. **Confirm on the hub**, then offer to create the review:
+   ```bash
+   sf data query --target-org <hub-org> --json \
+     -q "SELECT Name, CommitReference FROM WorkItemComponentList WHERE WorkItemId = '<work-item-id>' ORDER BY CreatedDate"
+   ```
+   A new row with a `CommitReference` means the commit was recorded.
+
+**Fallback:** if the preflight fails, retrieve the changes with `sf project retrieve start --target-org <dev-org>` if they exist only in the dev org, set the work item to In Progress if it is New, then follow Workflow 3 and re-check the hub before creating the PR.

package/skills/dx-devops-work-item-manage/references/commit-api.md

@@ -0,0 +1,116 @@
+# Commit through the DevOps Center API
+
+Request, response and polling were verified live (dev org + Core hub, work item `WI-000001`, status In Progress). Error codes, no-access preflight behaviour and git-path sync behaviour come from source, not live tests. Use this when the user supplies a dev org alias and the changes are already deployed in that org.
+
+## Contents
+
+- Orgs involved
+- Preflight
+- Request
+- Response and errors
+- Polling
+- Confirming on the hub
+- Differences from the git path
+- Known limits
+
+## Orgs involved
+
+| Org | Role | Used for |
+|-----|------|----------|
+| Dev org | Holds the metadata; where DX Inspector runs | `doceConnectionType`, `commitChanges`, `DevopsRequestInfo` polling |
+| Hub org | Holds projects, work items, component lists | `sf devops work-item list`, status checks, confirming the commit |
+
+The dev org reaches the hub server-side through the `ALMDevOpsCenterHub` named credential. The CLI cannot use that credential, so the hub needs its own `sf` login (`--target-org <hub-alias>`).
+
+## Preflight
+
+```bash
+sf api request rest "/services/data/v67.0/connect/devops/doceConnectionType" --target-org <dev-org>
+```
+
+The commit API is used at `v67.0`; the commands are not tied to the skill's `minApiVersion`. Treat a non-zero exit or an error body as failure for every `sf api request rest` call here (the no-access case was not tested live).
+
+- 2xx with `{"isCore": true, "isManagedPackage": false}` — Core hub; proceed. This call itself goes through the hub named credential, so success is evidence the credential works.
+- A failed call (no DX Inspector access, endpoint missing) — fall back to the git path.
+- `isCore` not `true`, or `isManagedPackage: true` — this reference covers the Core path only; use the git path.
+- Optional: `sf data query --target-org <dev-org> -q "SELECT DeveloperName FROM NamedCredential WHERE DeveloperName = 'ALMDevOpsCenterHub'"`.
+
+## Request
+
+`POST /services/data/v67.0/connect/devops/commitChanges` on the **dev org**. The REST body is the input object itself. Wrapping it in `{"commitChanges": {...}}` fails with `JSON_PARSER_ERROR: Unrecognized field "commitChanges"`.
+
+```json
+{
+  "isCommitCore": "true",
+  "workItemId": "<hub work item id>",
+  "projectId": "<hub project id>",
+  "workItemName": "WI-000001",
+  "workItemLink": "<url of the work item in the hub>",
+  "commitMessage": "<message>",
+  "changes": [
+    {"fullName": "MyClass", "type": "ApexClass", "operation": "modify"}
+  ]
+}
+```
+
+- `isCommitCore` is the **string** `"true"`. The Core path needs it together with a non-empty `workItemId`.
+- `operation` is `add`, `modify` or `delete`.
+- Rebuild the request body for **every** commit. Write it to a temp file (`mktemp`) and delete it afterwards, so a later `git add` cannot pick it up.
+- Do not send `dataChanges` or `vcsRepo` (data deployment and the Managed Package path are out of scope).
+
+```bash
+BODY=$(mktemp)   # write the JSON above to "$BODY"; rm "$BODY" when done
+sf api request rest "/services/data/v67.0/connect/devops/commitChanges" \
+  --method POST --body @"$BODY" --target-org <dev-org>
+```
+
+Pass the file with the `@` prefix (`--body @<file>`); without it the CLI treats the path as the literal body.
+
+## Response and errors
+
+Success: `{"reqId": "<uuid>", "status": "SUCCESS"}` — this means the request was accepted, not that the commit finished.
+
+Request-level failures (e.g. `JSON_PARSER_ERROR` from a malformed body) come back as real HTTP errors: surface them and stop. Business failures are returned as HTTP 200 with `status: "ERROR"` and `reqId` holding `CODE:message`. Codes seen in source: `WORKITEM_NEVERED`, `VCS_NOT_AUTHENTICATED`, `COMMIT_API_FAILURE_CORE`, `COMMIT_API_FAILURE_CLIAAS`, `COMMIT_PAYLOAD_ERROR_*`, `COMMIT_DATA_VALIDATION_ERROR`, `COMMIT_FAILED`. Always check `status`, not the exit code alone.
+
+Server-side preconditions: work item not closed (`WORKITEM_NEVERED`); status New, In Progress, In Review or Ready to Promote; the VCS connection is authenticated.
+
+## Polling
+
+There is no status resource. Query the dev org:
+
+```bash
+sf data query --target-org <dev-org> --json \
+  -q "SELECT Status, Message, ErrorDetails, RequestCompletionDate FROM DevopsRequestInfo WHERE RequestToken = '<reqId>'"
+```
+
+- Terminal `Status` values: `SUCCESS` (not `COMPLETED`) and `ERROR`. A loop that waits for `COMPLETED` never exits.
+- The commit observed took about 10 seconds. Poll every 10 seconds, deadline 12 minutes.
+- `IN_PROGRESS` comes first; `RequestToken` equals the POST `reqId`.
+- At the deadline the request is stuck (worker timeout is 10 minutes and the status can stay in progress). Report it and do not retry automatically; a retry is a new request that could race the stuck one.
+- `Message`/`ErrorDetails` carry the failure text when `Status` is `ERROR`.
+
+## Confirming on the hub
+
+```bash
+sf data query --target-org <hub-org> --json \
+  -q "SELECT Name, CommitReference, CreatedDate FROM WorkItemComponentList WHERE WorkItemId = '<id>' ORDER BY CreatedDate"
+```
+
+A new row with a `CommitReference` hash confirms the commit was recorded. A new row with a null `CommitReference` (seen with unchanged components) means the request succeeded but nothing new was committed; report "nothing to commit", not a successful commit. An In Progress work item stays In Progress; a New one is expected to move to In Progress (not tested live).
+
+## Differences from the git path
+
+| | Git path | API path |
+|---|---|---|
+| Committed content | Files on local disk | Components named in `changes`, retrieved from the dev org |
+| Orgs | Hub only | Dev org for the commit, hub for lookup and confirmation |
+| Author | The user's git identity | `DevOps Center <noreply@salesforce.com>` |
+| Branch | Work item `branch` field | The work item name (`WI-000001`); the live test could not distinguish this from `branch` |
+| Hub records | Created when the hub's external-commit sync picks the push up (only for In Progress, In Review, Ready to Promote) | Created immediately |
+| Result tracking | git exit codes | `reqId` plus `DevopsRequestInfo` |
+
+## Known limits
+
+- No rebase before push: a concurrent push to the same branch can make the commit fail as non-fast-forward.
+- An empty change set can finish `SUCCESS` with nothing committed.
+- A failed attempt can leave an orphaned component list on the hub.

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-lwc-widget-assess/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: experience-lwc-widget-assess
+description: "Assess whether a specific Lightning web component can serve its user's purpose as an HXL declarative widget. Use for LWC-to-widget feasibility, portability audits, and candidate screening; use experience-lwc-widget-migrate when the user wants the widget built."
+metadata:
+  version: "1.0"
+  domains: ["Experience", "Platform", "Agentforce"]
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "experience-lwc-widget-migrate"
+    - "platform-widget-generate"
+---
+
+# Assess LWC to widget fit
+
+Answer two questions for each LWC: **Can the current behavior be represented?** If not, **would a feasible widget still accomplish the user's goal?** Assess only; do not create metadata. A widget is its own declarative artifact, distinct from a Lightning Type. Its body renders supplied data with discovered tiles, bindings, formulas, and supported actions. It cannot run arbitrary LWC code, fetch after render, or retain reactive client state.
+
+## Evidence and decision
+
+1. Read the component's JS/TS, template, metadata, and relevant child components. State the user's goal in one sentence. Trace each visible value to its source and identify interactions essential to that goal. An `@api` property proves external input, **not** that an invocable action returns it. A user's explicit statement about action output is evidence for a feasibility assessment; verify the actual action contract and Lightning Type/renderer wiring before claiming a working migration.
+2. Map the **job** of each rendered element and action to the target surface. `platform-widget-generate` explains the discovery procedure; the actual `discoverUiComponents` response and `getUiComponentSchemas` results establish available blocks and attributes. Read its `references/widget-formulas.md` only when a transformation matters. Record the target channel from evidence rather than assuming a fixed channel or tile count. Without discovery, a documented pattern can support a **provisional candidate**, but absence from examples does not prove a block is unavailable. Use `review` when that uncertainty determines the verdict; never invent a tile, action, input submission mechanism, or formula.
+3. Check all dimensions, even after a failure: rendering vocabulary; retained state, imperative effects, and actions; data origin; and transformations. A bounded snapshot or pre-shaped collection can sometimes move into the invocable action's output. Inspect the action implementation before asserting that it can. A formula's scalar `MIN`/`MAX`, date, or regex support does not imply collection sorting or aggregation. Input forms require evidence that the current tiles can collect values **and** pass those values to an action; `sendMessage` alone does not prove that.
+4. Judge the current LWC and a proposed widget separately. A link or `sendMessage` may preserve an intent without preserving the original interaction, if the agent can actually perform the requested work with the required context. A carousel may become a product list; an order builder whose purpose is choosing quantities may not. Treat that change as a rebuild. For the widget candidate, consider a **specified proposed IA contract** when setting `rendersAsWidget`; state the contract change explicitly. If feasibility or purpose remains unresolved, use `review`, not a forced yes/no verdict.
+
+Use these outcomes:
+
+| Outcome | Meaning |
+|---|---|
+| `asIsVerdict: port-declarative` | Current visible behavior and data contract can be represented. |
+| `asIsVerdict: needs-IA-contract-change` | Only a bounded output or pre-shaping change is needed. |
+| `asIsVerdict: not-portable` | Some current behavior or visual has no verified equivalent. |
+| `asIsVerdict: review` | Evidence cannot establish the current fit. |
+| `asDisplayWidget.verdict: viable` | A verified or clearly identified candidate serves the goal, possibly after a stated contract change or rebuild. |
+| `asDisplayWidget.verdict: pointless` | It can render but loses the user's goal. |
+| `asDisplayWidget.verdict: blocked` | The proposed display/action cannot be represented. |
+| `asDisplayWidget.verdict: review` | Capability, data provenance, or purpose is unresolved. |
+
+List **every material blocker** in the report with its gate and evidence, citing a source location or concrete behavior. Gate names are `role`, `rendering vocabulary`, `behavior/interactivity`, `data source`, and `transformation`. Do not stop at the first failed dimension. `contractChange.shapeToAdd` names only fields or pre-shaped values the action could plausibly return; never invent a payload. A viable adaptation may need a contract change even when the current LWC is `not-portable`. If a proposed widget changes the UX, set `isRebuild: true` and name the lost interaction in the report. Mark uncertain conclusions low confidence and explain what would resolve them.
+
+## Output
+
+Produce two artifacts. When an output location is given, write them as `verdict.json` and `report.md`.
+
+**Verdict** — the machine-readable decision that `experience-lwc-widget-migrate` gates on. One JSON object per component; for a folder, an array. Keep exactly these fields:
+
+```json
+{
+  "component": "caseDetailsPanel",
+  "role": "renderer",
+  "asIsVerdict": "port-declarative",
+  "contractChange": {"suggested": false, "shapeToAdd": []},
+  "asDisplayWidget": {"verdict": "viable", "rendersAsWidget": true, "stillServesPurpose": true, "isRebuild": false},
+  "needsHumanReview": false
+}
+```
+
+`role` is `renderer`, `input`, or `interactive`. `stillServesPurpose` is boolean or `"unknown"`; `rendersAsWidget` is boolean or `null` when capability is unresolved. For `viable`, both are true. For `pointless`, rendering is true and purpose false. For `blocked`, rendering is false and purpose is `"unknown"`. For `review`, keep unresolved fields unknown/null. Set `needsHumanReview: true` for either `review` verdict or unknown purpose. Suggest a contract change only when a value the widget displays is **not** already in the action's output (for example, it is fetched after render). Data already in the payload needs no contract change, even when the LWC is `not-portable` or the widget is a rebuild. Any suggested contract change needs a nonempty `shapeToAdd`; `needs-IA-contract-change` requires such a suggestion. `port-declarative` has no contract change.
+
+**Report** — the human-review document. For a folder, one section per component. Use this structure:
+
+```markdown
+# <component>: <one-line conclusion>
+
+**Verdict:** <asIsVerdict> → <asDisplayWidget.verdict> (rebuild or not) · **Confidence:** high | low · **Needs human review:** yes | no
+
+## Why
+The user's goal, what maps cleanly, and what decides the verdict.
+
+## Blockers
+Each material blocker: gate, signal, evidence. "None" for `port-declarative`.
+
+## Suggested contract change
+Each field to add and why it must move into the action output. Omit when none is suggested.
+
+## What the widget keeps / drops
+Kept actions and dropped or replaced interactions.
+
+## Open questions
+What would resolve any low-confidence conclusion.
+```

package/skills/experience-lwc-widget-migrate/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: experience-lwc-widget-migrate
+description: "Convert a specific existing Lightning web component (LWC) into a declarative HXL / Agentforce widget, end to end. Gates on experience-lwc-widget-assess and stops when a widget cannot serve the LWC's purpose; otherwise hands the derived field shape to platform-widget-generate and wires the widget as the Lightning Type renderer. TRIGGER when: the user wants to convert, migrate, port, rebuild, or turn a named LWC into a widget or declarative Agentforce widget, or asks for a widget built from an existing LWC component. DO NOT TRIGGER when: the user only wants to know whether an LWC can become a widget (use experience-lwc-widget-assess), or wants a widget for a data shape, entity, or Lightning Type with no existing LWC (use platform-widget-generate or platform-lightning-type-widget-coordinate)."
+metadata:
+  version: "1.0"
+  domains: ["Experience", "Platform", "Agentforce"]
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "experience-lwc-widget-assess"
+    - "platform-widget-generate"
+    - "platform-custom-lightning-type-generate"
+    - "platform-lightning-type-widget-coordinate"
+  mcpTools:
+    metadata-experts:
+      tools: ["execute_metadata_action"]
+      semver: ">=1.0.0"
+---
+
+# Migrate an LWC to a widget
+
+Use the LWC to recover the **user's goal and data contract**, then build the closest useful widget. A widget is its own declarative artifact. `platform-widget-generate` authors it; a Lightning Type renderer may need separate wiring to make it reachable. This skill owns the comparison, handoff, integration check, and honest final status.
+
+## 1. Decide whether to proceed
+
+Read and apply `experience-lwc-widget-assess` to the component, its action output, and any existing Lightning Type/renderer. Preserve its verdict and the key findings from its report (blockers, contract change, lost interactions) in your report; do not write the assessment's own `verdict.json` or `report.md` files. Stop on `pointless`, `blocked`, `review`, or `needsHumanReview: true`. Proceed on `viable` only when the intended change is explicit:
+
+- For `port-declarative`, preserve the current visible fields and actions.
+- For `needs-IA-contract-change`, identify the exact bounded output fields or pre-shaped values required. A widget against a **proposed** contract is a draft until the action returns that contract; do not call it working.
+- For `not-portable` with a viable adaptation, describe the replacement UX and each lost interaction. Call it a rebuild, not a faithful port.
+
+## 2. Derive the generator handoff
+
+Trace each value the proposed widget displays to the actual or proposed action output. Before authoring, verify the action contract rather than relying only on an assessment prompt's description. Pass `platform-widget-generate` an ordered field shape (`name`, `type`, `required`), nested/list item fields, the intended tile role of each visible element, and supported terminal actions. Preserve render order and field paths. Use its discovery results for tile definitions and attributes, its documented formula catalog for expressions, and its instructions for schema types and bundle layout; do not maintain a second catalog here. A formula can cover supported scalar/date/regex operations, while collection restructuring may require pre-shaped output.
+
+If an LWC fixture or action example contains sample data, it can help infer the shape; sample data is optional and is **not** a documented generator input or a substitute for the action contract. Do not invent sample fields. For an action such as `sendMessage`, verify that the required context reaches the agent and that the agent has a way to perform the requested work. Do not assume a widget input form can submit collected values without a discovered, validated mechanism.
+
+## 3. Generate and connect
+
+Load `platform-widget-generate` and follow its mandatory live `discoverUiComponents` and `getUiComponentSchemas` calls. If the `metadata-experts` MCP or discovery is unavailable, stop before authoring a bundle; report the completed assessment and proposed field shape. The generator owns its three widget files and self-validation. Do not copy its UEM syntax or validation checklist into this skill.
+
+For an Agentforce renderer migration, also establish the Lightning Type that receives the action output. A bundle alone is not connected to the action:
+
+- **Existing compatible Lightning Type:** inspect its schema and current `renderer.json`. After generation, read `platform-custom-lightning-type-generate/references/widget-rendition.md`, wire the widget with field mappings, and follow `platform-lightning-type-widget-coordinate`'s renderer checks. If the existing renderer points to another widget or LWC, surface the replacement/merge decision before changing it.
+- **No compatible Lightning Type:** resolve the action's output class and a Lightning Type name from the project or the user's request. For the coordinator's supported Apex-backed route, use `platform-lightning-type-widget-coordinate` with that type and the assessed output shape; let it own bundle generation and renderer wiring. That coordinator does not cover every type. If the output/type route cannot be established, stop and identify the missing integration step. Do not claim a complete migration.
+
+If the user requested a **bundle only**, report it explicitly as an unconnected bundle. Otherwise, completion requires both the bundle and renderer wiring.
+
+## 4. Check the result
+
+Use the generator's bundle self-validation. Then compare the result to the assessed candidate: every retained visible field has a binding to the real/proposed payload; list item paths and supported actions match; omitted behavior and contract changes are stated; and, for a renderer migration, the Lightning Type points to this widget with matching attributes. Static checks establish structure and mapping, not deployed runtime behavior. Report assessment, created paths, validation results, and one of: `migrated and wired`, `bundle only`, `draft pending IA contract`, or `stopped`, with the reason.