@salesforce/afv-skills 1.30.0 → 1.32.0

package/skills/platform-encryption-configure/assets/encrypted-field.field-meta.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{FIELD_API_NAME}__c</fullName>
+    <label>{FIELD_LABEL}</label>
+    <type>{FIELD_TYPE}</type>
+    <length>{LENGTH}</length>
+    <encryptionScheme>ProbabilisticEncryption</encryptionScheme>
+</CustomField>
+<!--
+  TEMPLATE NOTES — delete this comment block before delivering the file.
+
+  <type>:   Text for string fields up to 255 chars; LongTextArea only for 256+.
+            "long text up to 255 characters" is Text, NOT LongTextArea.
+  <encryptionScheme> must be exactly one of:
+    ProbabilisticEncryption                strongest; NOT filterable/sortable/groupable
+    CaseSensitiveDeterministicEncryption   filterable; exact-case equality
+    CaseInsensitiveDeterministicEncryption filterable; case-normalized equality
+    None                                   removes encryption
+  Only deterministic schemes support filter / sort / group. A query that filters
+  a probabilistically-encrypted field is REJECTED with INVALID_FIELD.
+-->
+

package/skills/platform-encryption-configure/examples/cache-only-keys.settings-meta.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Worked example: enabling Cache-Only Keys WITH replay detection.
+  Note the ordering guarantee — enableCacheOnlyKeys=true is present, which is
+  the precondition for enableReplayDetection=true. Removing enableCacheOnlyKeys
+  (or setting it false) while keeping enableReplayDetection=true is invalid.
+-->
+<EncryptionKeySettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableCacheOnlyKeys>true</enableCacheOnlyKeys>
+    <enableReplayDetection>true</enableReplayDetection>
+</EncryptionKeySettings>

package/skills/platform-encryption-configure/references/encryption-schemes.md

@@ -0,0 +1,34 @@
+# Encryption Schemes
+
+Shield Platform Encryption offers two families of scheme, exposed on `CustomField.encryptionScheme` (Metadata API 44.0+). Choosing between them is a trade-off between cryptographic strength and queryability.
+
+## Valid `encryptionScheme` values
+
+| Value | Filterable / sortable / groupable | When to use |
+|-------|:--:|-------------|
+| `ProbabilisticEncryption` | **No** | Default and strongest. Same plaintext encrypts to different ciphertext each time, so no two values are comparable. Use unless the field must be queried. |
+| `CaseSensitiveDeterministicEncryption` | Yes | Same plaintext always encrypts to the same ciphertext, preserving exact case. Use for exact-match filters where case matters (e.g. codes, tokens). |
+| `CaseInsensitiveDeterministicEncryption` | Yes | Deterministic with case normalized before encryption. Use for equality filters on human-entered text (names, emails) where case should not matter. |
+| `None` | n/a | Removes encryption from the field. |
+
+Only these four strings are accepted. Any other value fails deployment.
+
+## Deterministic vs Probabilistic — the decision
+
+- **Need to filter, sort, group, or use the field in a WHERE clause?** → a deterministic scheme. Deterministic encryption preserves equality so the index can be used.
+- **No query requirement?** → probabilistic. It is cryptographically stronger because identical plaintexts produce different ciphertexts, defeating frequency analysis.
+- **Case matters in matching?** → `CaseSensitive...`. Otherwise `CaseInsensitive...`.
+
+Enabling the deterministic scheme at the org level also requires `enableDeterministicEncryption=true` in `PlatformEncryptionSettings`.
+
+## Query behavior of encrypted fields — the failure mode
+
+A common misconception is that filtering or sorting on a **probabilistically**-encrypted field silently drops the clause or returns zero rows. It does not.
+
+The platform **rejects the query** with an `INVALID_FIELD` error:
+
+```text
+INVALID_FIELD: field '<FieldName>' can not be sorted / filtered / grouped in a query call
+```
+
+This is enforced server-side (see the platform's `QueryBlockingTest` coverage). The correct guidance to a user hitting this is: the query failed because the field is probabilistically encrypted — re-encrypt it with a deterministic scheme if it must be queryable, or remove the field from the filter/sort/group clause. Never tell the user the query "returns nothing" — it errors.

package/skills/platform-encryption-configure/references/key-models.md

@@ -0,0 +1,34 @@
+# Key Management Models
+
+Shield Platform Encryption supports several ways to source and control the key material that protects encrypted data. They differ in *where the key material lives* and *who controls it*.
+
+## The models
+
+| Model | Where key material lives | Who controls it | Metadata / setting |
+|-------|--------------------------|-----------------|--------------------|
+| Salesforce-derived (default) | Salesforce, derived from a tenant secret | Salesforce derivation | none — default |
+| **BYOK** (Bring Your Own Key) | Salesforce, but from *customer-supplied* material | Customer uploads key material; Salesforce stores it | `canOptOutOfDerivationWithBYOK` controls per-key derivation opt-out |
+| **BYOKMS / EKM** (External Key Management) | An *external* key store the customer runs | Customer; Salesforce calls out to the KMS | `canExternalKeyManagement` (API 63.0+) |
+| **Cache-Only Keys** | Outside Salesforce entirely; fetched on demand per callout | Customer hosts a key service; Salesforce caches, never persists | `enableCacheOnlyKeys`, `enableReplayDetection` |
+| **Data 360 keys** | Salesforce, dedicated Data 360 root key | Customer-managed root key | `canManageDataCloudKeys` (API 63.0+) |
+| **Transactional DB** | Salesforce | Org policy | `canEncryptTransactionalDatabase` (API 63.0+) |
+
+## BYOK vs BYOKMS/EKM — the distinction users get wrong
+
+- **BYOK**: you generate key material and *upload* it. Salesforce stores it and uses it like a derived key. The trust boundary still includes Salesforce storing the material.
+- **BYOKMS / EKM**: key material *never leaves your external KMS*. Salesforce makes a callout to the KMS to wrap/unwrap. This keeps the material entirely under your control.
+
+## Cache-Only Keys and replay detection
+
+Cache-Only Keys go further than EKM: Salesforce fetches key material on every use and never persists it — only caches it transiently.
+
+`enableReplayDetection` protects those callouts against replay attacks using a nonce. The contract is a **one-way dependency**:
+
+> *Requires `enableCacheOnlyKeys=true` before setting `enableReplayDetection` to true.*
+
+Two consequences the agent must respect:
+
+1. Enabling Cache-Only Keys does **not** auto-enable replay detection. You must set `enableReplayDetection=true` explicitly.
+2. An org can validly run Cache-Only Keys with replay detection **off**. It is not required.
+
+Setting `enableReplayDetection=true` without `enableCacheOnlyKeys=true` is an invalid combination and will be rejected.

package/skills/platform-encryption-configure/references/tenant-secret-lifecycle.md

@@ -0,0 +1,23 @@
+# Tenant Secret Lifecycle
+
+A **tenant secret** is the per-org root from which Shield derives (or wraps) data encryption keys. Its lifecycle operations are **UI/REST-only** — there is no `*.settings-meta.xml` for rotating, destroying, or uploading a tenant secret. When a user asks about these, return guidance and point them at Setup or the REST/Tooling API, not a metadata file.
+
+## Operations
+
+| Operation | What it does | Surface |
+|-----------|--------------|---------|
+| Generate | Creates a new active tenant secret for a key type | Setup → Key Management, or REST |
+| Rotate | Generates a new tenant secret; existing data stays readable under prior secrets | Setup / REST |
+| Destroy | Permanently destroys key material; data encrypted under it becomes unrecoverable | Setup (destructive, requires confirmation) |
+| BYOK upload | Uploads customer-supplied key material as the tenant secret | Setup / REST |
+| Cache-Only callout setup | Configures the named credential / callout endpoint the key service is fetched from | Setup (Named Credentials) |
+
+## Rotation semantics
+
+Rotating a tenant secret makes a new secret **active**; prior secrets are retained as **archived** so existing ciphertext stays readable. New writes use the active secret. To move existing data onto the new secret, run **background encryption** (a.k.a. the sync/re-encrypt process) — rotation alone does not re-encrypt existing rows.
+
+For BYOK specifically, the sequence is: rotate to (upload) the new key material, then run background encryption to apply it. Uploading new material does not retroactively re-encrypt existing data on its own.
+
+## Destruction semantics
+
+Destroying a tenant secret is **irreversible**. Any data whose keys derive from that secret and has not been re-encrypted under another active secret becomes permanently unreadable. This is intentional (right-to-be-forgotten / crypto-shredding) but must be surfaced as a hard warning — there is no recovery path.

package/skills/platform-encryption-configure/scripts/validate-encryption-metadata.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Validate a Shield Platform Encryption settings/field XML file for the two
+# deterministic contracts this skill must never get wrong:
+#   1. enableReplayDetection=true requires enableCacheOnlyKeys=true (one-way dependency)
+#   2. encryptionScheme must be one of the four valid enum values
+#
+# Usage: validate-encryption-metadata.sh <file.xml>
+#        validate-encryption-metadata.sh --help
+# Output: prints "OK" on success; prints ERROR lines to stderr and exits 1 on failure.
+
+set -euo pipefail
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  echo "Usage: validate-encryption-metadata.sh <file.xml>"
+  echo "Checks: replay-detection dependency, encryptionScheme enum."
+  exit 0
+fi
+
+FILE="${1:-}"
+if [[ -z "$FILE" ]]; then
+  echo "ERROR: no file given. Usage: validate-encryption-metadata.sh <file.xml>" >&2
+  exit 1
+fi
+if [[ ! -f "$FILE" ]]; then
+  echo "ERROR: file not found: $FILE" >&2
+  exit 1
+fi
+
+errors=0
+
+# 1. Replay-detection one-way dependency.
+if grep -q '<enableReplayDetection>true</enableReplayDetection>' "$FILE"; then
+  if ! grep -q '<enableCacheOnlyKeys>true</enableCacheOnlyKeys>' "$FILE"; then
+    echo "ERROR: enableReplayDetection=true requires enableCacheOnlyKeys=true in the same file." >&2
+    errors=$((errors + 1))
+  fi
+fi
+
+# 2. encryptionScheme enum.
+scheme=$(grep -oE '<encryptionScheme>[^<]*</encryptionScheme>' "$FILE" | sed -E 's/<\/?encryptionScheme>//g' || true)
+if [[ -n "$scheme" ]]; then
+  case "$scheme" in
+    ProbabilisticEncryption|CaseSensitiveDeterministicEncryption|CaseInsensitiveDeterministicEncryption|None) ;;
+    *)
+      echo "ERROR: invalid encryptionScheme '$scheme'. Must be one of: ProbabilisticEncryption, CaseSensitiveDeterministicEncryption, CaseInsensitiveDeterministicEncryption, None." >&2
+      errors=$((errors + 1))
+      ;;
+  esac
+fi
+
+if [[ "$errors" -gt 0 ]]; then
+  exit 1
+fi
+echo "OK"

package/skills/platform-lightning-type-widget-coordinate/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: platform-lightning-type-widget-coordinate
+description: "Orchestrate Apex-backed Lightning Type + HXL widget generation. TRIGGER only when the prompt EXPLICITLY invokes Lightning Types: user says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', references '@apexClassType/...', asks to build a widget or card for a named Lightning Type, asks to create a new Lightning Type and widget together, or grounds a widget in a specific Apex class as its schema. DO NOT TRIGGER when the prompt names only a subject, domain, feature, or entity noun. Also DO NOT TRIGGER when: authoring only a Custom Lightning Type (use platform-custom-lightning-type-generate), only an Apex class (use platform-apex-generate), editing an existing widget without any Lightning Type change, or grounding a widget on an object/JSON-based Lightning Type (lightning__objectType with primitives)."
+metadata:
+  version: "1.1"
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "platform-widget-generate"
+    - "platform-custom-lightning-type-generate"
+    - "platform-apex-generate"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Building a Lightning Type With a Widget
+
+Coordinate Lightning Type, Apex class, and HXL widget generation across the two paths below. This skill never authors content directly — it loads and invokes leaf skills in dependency order, gates progress on user approval, and runs validation gates before reporting completion.
+
+## Scope
+
+Apex-backed Lightning Types only — root `lightning:type` of the form `@apexClassType/<namespace>__<ClassName>` (outer class). The class itself carries the `@AuraEnabled` fields that define the payload shape; nested list-element types live as inner classes referenced by `List<Inner>` fields on the outer class. Object/JSON-based Lightning Types (root `lightning__objectType` with primitive `properties`) are out of scope; route those to `platform-custom-lightning-type-generate` and `platform-widget-generate` separately.
+
+---
+
+## Phase Graph
+
+| Phase | Purpose | Runs in | Output |
+|---|---|---|---|
+| 1 — Path selection | Pick the path (`existing-lightning-type-with-widget` · `new-lightning-type-with-widget`) from the user prompt. | All paths | `path` |
+| 2 — Lightning Type discovery | Local project first; then `sf project retrieve --metadata LightningTypeBundle:<name>`; ambiguity resolution; in-scope verification. | **`existing-lightning-type-with-widget` only** | `lightningTypeSchema` (path + SHA-256 + Apex class FQN) |
+| 3 — Build plan | Print the plan in full; proceed unless the next reply explicitly pushes back. | All paths | printed plan |
+| 4 — Generation | Load and invoke leaf skills per path. | All paths | files written |
+| 5 — Validation | Run hard gates (block) and warn gates (advisory). | All paths | gate report |
+| 6 — Summary | Files, validations, preview readiness, next steps. | All paths | summary |
+
+**Per-phase pattern:**
+
+| Step | What to do |
+|---|---|
+| 1. Load skill | Invoke the named skill. Even if you remember its content, skills evolve — always load fresh. |
+| 2. Execute | Follow the loaded skill's workflow. |
+| 3. Verify | Confirm outputs exist and match the spec. |
+| 4. Checkpoint | Confirm phase completion before moving on. |
+
+---
+
+## Phase 1 — Path selection
+
+Determine the path from the user prompt and pick the corresponding leaf-skill load order:
+
+| Path | Trigger | Phase 4 sub-skill load order |
+|---|---|---|
+| `existing-lightning-type-with-widget` | Prompt names a Lightning Type and treats it as existing (no *create*, *generate*, or *new* qualifier on the type). Phase 2 confirms it exists and is in scope. | `platform-widget-generate` (renderer wiring is authored inline per the Phase 4 "Renderer.json wiring step" — no separate skill load) |
+| `new-lightning-type-with-widget` | Prompt asks for a new Lightning Type (verbs: *create*, *generate*, *build*, *make a new*) **or** Phase 2 finds nothing in the local project or in the org. | `platform-apex-generate` → `platform-custom-lightning-type-generate` (schema authoring) → `platform-widget-generate` (renderer wiring authored inline afterwards per the Phase 4 "Renderer.json wiring step") |
+
+If the prompt names no Lightning Type at all (just a widget against prompt-provided fields or sample data), this orchestrator should not have been triggered — route the user to `platform-widget-generate` directly.
+
+If the prompt is ambiguous between the two paths, ask **one** clarifying question max and pick. The `new-lightning-type-with-widget` path's `platform-apex-generate` step is engaged automatically — do not prompt the user to confirm Apex.
+
+---
+
+## Phase 2 — Lightning Type discovery (`existing-lightning-type-with-widget` only)
+
+Skipped for `new-lightning-type-with-widget` (the Lightning Type does not yet exist).
+
+**For `existing-lightning-type-with-widget`, FIRST Read `references/lightning-type-discovery.md` (REQUIRED — do NOT skip; do not run Phase 2 from this summary alone), then execute its find → verify → ensure-class procedure step by step.** The bullets below are a reminder, not a substitute for the reference:
+
+- Local project first: search `force-app/**/lightningTypes/<TypeName>/schema.json`.
+- If not found, run `sf project retrieve --metadata LightningTypeBundle:<TypeName>` against the connected org.
+- If multiple candidates surface, list them with FQNs and paths. Ask the user to pick.
+- After locating the schema, verify it is in scope (root `lightning:type` starts with `@apexClassType/`). If the type is object/JSON-based, surface that and stop.
+- **Ensure the backing Apex class is in the local project.** Parse `<ClassName>` from the `@apexClassType/<ns>__<ClassName>` root. If `<pkgDir>/classes/<ClassName>.cls` is absent, run `sf project retrieve --metadata ApexClass:<ClassName>`. This runs whether the Lightning Type was found locally or retrieved from the org — a locally-present Lightning Type can still reference an absent class. If the class exists nowhere, surface it and stop (the type is unrenderable). See the reference for the full procedure.
+- If retrieval fails, surface the CLI error and offer: (a) ask the user to run retrieve manually and re-run, or (b) downgrade to `new-lightning-type-with-widget` if appropriate. Never silently downgrade.
+- If retrieval finds nothing, prompt the user to confirm flipping to `new-lightning-type-with-widget` before continuing.
+
+Capture the Lightning Type `schema.json` SHA-256 and the Apex class FQN (parsed from `@apexClassType/...`) at the end of this phase. The Phase 5 `lightning-type-unchanged` gate compares the SHA against the on-disk SHA at end of Phase 4 to enforce no silent schema edits.
+
+> Staleness: do NOT maintain a cross-session cache. Always read the local project fresh and always re-retrieve from the org per session.
+
+---
+
+## Phase 3 — Build plan + approval gate
+
+Print a build plan using the template in `references/build-plan-format.md`. The plan must list:
+
+- A one-line developer-facing summary of what will be built (the `PLAN:` line in the template).
+- Lightning Type name and source (existing in local project · retrieved from org · newly created), plus the Apex class FQN it references.
+- Files about to be created or modified, with absolute paths.
+- Sub-skills that will run after approval.
+- Validations that will run after generation.
+
+The plan is read by the developer. Keep it concrete: name the artifacts, files, sub-skills, and validations.
+
+**Print the plan in full, then proceed unless the user's next reply explicitly pushes back.** Explicit pushback = `no`, `stop`, `wait`, `change X`, `use Y instead`, or an equivalent rejection / revision request. Explicit approval (`yes`, `approve`, `go`, `looks good`, `ok`) is welcome but NOT required — silence, an unrelated follow-up, or the natural continuation of a single-turn eval all count as implicit approval. The plan being visible in the transcript is the invariant; blocking on interactive approval is not. If pushback arrives, revise the plan and re-print before moving on.
+
+---
+
+## Phase 4 — Generation
+
+Execute the sub-skill load order from the chosen path's row in the Phase 1 table. For each sub-skill:
+
+1. Load the skill.
+2. Execute the leaf skill's authoring workflow against the spec from Phase 3. The leaf skill is authoritative for its own deliverables.
+3. Verify the outputs match what the build plan promised.
+4. Checkpoint before invoking the next sub-skill.
+
+**`new-lightning-type-with-widget` handoff contract:**
+
+- Apex authors a class whose `@AuraEnabled` fields define the desired Lightning Type shape. Inner classes are used only for nested list-element types. Capture the **outer class FQN** (`<namespace>__<ClassName>`).
+- The Custom Lightning Type references the outer class via `lightning:type: "@apexClassType/<namespace>__<ClassName>"`.
+- Widget grounds on the outer class's `@AuraEnabled` fields and binds attributes via `{!$attrs.X}`.
+- After the widget bundle is written, author the Lightning Type's renderer wiring per the **renderer.json wiring step** below.
+
+**`existing-lightning-type-with-widget` handoff contract:**
+
+- Hand the widget skill the Lightning Type `schema.json` path and the Apex class FQN captured in Phase 2. The widget skill derives its own `schema.json` from the Apex class's `@AuraEnabled` fields (see `platform-widget-generate/references/schema-from-lightning-type.md`).
+- After the widget bundle is written, author the Lightning Type's renderer wiring per the **renderer.json wiring step** below. The Lightning Type `schema.json` is NOT modified (`lightning-type-unchanged` enforces this) — only `lightningDesktopGenAi/renderer.json` is written.
+
+**Renderer.json wiring step (BOTH flows — never optional):**
+
+**First, Read `platform-custom-lightning-type-generate/references/widget-rendition.md` (REQUIRED — do NOT skip; do not author `renderer.json` from memory or by copying an existing project sample, which may use a deprecated shape).**
+
+After the widget bundle exists, author `<pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` using the **widget-rendition pattern** documented in `platform-custom-lightning-type-generate/references/widget-rendition.md`. The renderer file is a thin wrapper — its first child references the widget via `"definition": "@widget/c/<widgetName>"` and maps **every widget schema property** to the Lightning Type instance's matching attribute via `{!$attrs.<schemaPropertyName>}`. Do **NOT** duplicate the widget body inside `renderer.json`; the widget bundle is the single source of truth for the rendering tree.
+
+Existing-renderer handling (`existing-lightning-type-with-widget` only): if `renderer.json` already exists at the target path, read it first.
+
+- If it already references the same widget (same `@widget/c/<widgetName>`) with the same attribute mapping, leave it alone.
+- If it references a **different** widget OR uses a custom-LWC root override (`c/<componentName>`), STOP and surface the conflict to the user before overwriting. Do not silently replace the user's existing rendition.
+- If the file exists but is not a widget-rendition (e.g. property-level overrides only), surface that and ask whether to merge or replace.
+
+Without this wiring the widget is unreachable from the Lightning Type — the widget bundle ships dead. `renderer-wires-widget` enforces existence and binding correctness.
+
+---
+
+## Phase 5 — Validation gates
+
+Read `references/validation-gates.md` and **run every gate**. The orchestrator runs cross-skill gates only — widget-bundle-internal checks (schema parse, root keys, leaf `lightning:type`, `{!$attrs.X}` resolution, `.uiwidget-meta.xml` well-formedness, `<UiWidgetBundle>` root, `<masterLabel>`, `<description>`, and `<widgetType>JSON</widgetType>`) are owned by `platform-widget-generate` and run as part of its own self-validation step.
+
+**Hard — block on failure:**
+
+1. `lightning-type-unchanged` — **`existing-lightning-type-with-widget` only.** Recompute SHA-256 of the on-disk Lightning Type `schema.json` and compare against the SHA captured in Phase 2. Mismatch = orchestrator silently edited the type.
+2. `renderer-wires-widget` — **both paths.** Confirm `<pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` exists, parses as JSON, wires this widget via `componentOverrides["$"].definition === "@widget/c/<widgetName>"`, and `componentOverrides["$"].attributes` binds every widget schema property as `{!$attrs.<schemaPropertyName>}`. See "renderer.json wiring step" in Phase 4 and `validation-gates.md` for the required shape.
+
+**Warn — advisory:**
+
+1. `field-trace` — **both paths.** RUN the trace procedure in `references/validation-gates.md` (grep `@AuraEnabled` from the outer .cls, `jq` widget schema property keys, print both lists, classify INVENTED vs OMITTED). PRINT both lists in the gate report — asserting `pass` without printing the lists is a hard violation. Silent omissions (Apex field absent from widget AND absent from the Phase 3 `Properties omitted:` plan) warn.
+2. `deploy-check` — **`new-lightning-type-with-widget` only.** RUN `sf project deploy --check-only --source-dir <pkgDir>/classes/<ClassName>.cls,<pkgDir>/lightningTypes/<TypeName>` and report the result. Reporting `pass` without running this command is a hard violation. See `validation-gates.md` for the "not yet deployed is not a valid skip reason" rule.
+
+Report each gate result by name in Phase 6 (`pass`, `fail (<reason>)`, `warn (<reason>)`, `not run`). Do **not** summarize as "all passed" — list each gate explicitly.
+
+---
+
+## Phase 6 — Summary
+
+Report. The summary is read by the developer — list only the files actually written; group by bundle so the developer can locate them quickly.
+
+```text
+Lightning Type + Widget Build Complete: <widgetName>
+
+FILES GENERATED:
+  Widget bundle:
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
+    <pkgDir>/uiWidgets/<widgetName>/schema.json
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml
+
+  Lightning Type bundle:
+    <pkgDir>/lightningTypes/<TypeName>/schema.json                              # only when newly created
+    <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json      # always — wires the Lightning Type to the widget
+
+  Apex (only when newly created):
+    <pkgDir>/classes/<ClassName>.cls
+    <pkgDir>/classes/<ClassName>.cls-meta.xml
+
+VALIDATIONS:
+  widget self-validation (platform-widget-generate gates): <pass | fail — see sub-skill report>
+  Lightning Type schema unchanged from before this run: <pass | fail | n/a (newly created)>
+  Lightning Type renderer wires this widget: <pass | fail (<reason>)>
+  widget↔apex field trace (INVENTED + OMITTED lists printed): <pass | warn (<reason>) | fail (invented: <list>)>
+  sf project deploy --check-only: <pass | warn | n/a (no new Apex or Lightning Type to deploy)>
+
+NEXT STEPS:
+  - Deploy: sf project deploy start --source-dir <pkgDir>
+  - Preview: <preview-surface guidance>
+```
+
+---
+
+## Hard Rules (always apply)
+
+1. **Plan-first, then proceed.** Print the full Phase 3 build plan before writing any file. If the next turn contains explicit rejection or a change request, stop and revise; otherwise continue to Phase 4. The invariant is the plan being visible in the transcript — not an interactive human approval — so this rule holds in manual chat, in agent-to-agent flows, and in single-turn eval runs where no follow-up user message arrives.
+2. **No silent schema edits** to existing Lightning Types. Phase 5 `lightning-type-unchanged` enforces this for `existing-lightning-type-with-widget`.
+3. **No silent Apex changes** to existing Apex. If Phase 4 needs to modify a pre-existing class, surface it in Phase 3. **A leaf skill that hits a shape gap mid-Phase-4 MUST stop and surface to the orchestrator instead of editing `.cls` directly** — Phase 3 covers gaps the orchestrator already knew about; this clause covers gaps discovered later by a leaf skill.
+4. **No invented fields, no silent omissions.** Every `{!$attrs.X}` must trace to the widget `schema.json`, and the widget `schema.json` must be a subset of the Apex class's `@AuraEnabled` fields. Default disposition for every Apex field is **include**; omission requires the field to appear in the Phase 3 build plan's `Properties omitted:` section with a rationale the user has approved. `field-trace` prints both APEX_FIELDS and WIDGET_PROPS lists and warns on silent omissions. `List<InnerClass>` fields are NEVER candidates for silent omission.
+5. **One clarification at most** when Lightning Type lookup is ambiguous.
+6. **Always load the leaf skill** before generation. Do not author from memory.
+7. **Out-of-scope types stop the orchestrator.** If Phase 2 discovers an object/JSON-based Lightning Type, route the user to `platform-custom-lightning-type-generate` and `platform-widget-generate` separately.
+8. **Run gates, do not describe them.** Phase 5 gates are concrete checks/commands. Reporting `pass` without executing the gate is a hard violation; report `not run` instead.
+9. **Lightning Type rendition is mandatory, never optional.** Both paths end with `<pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` wiring the Lightning Type to the widget via `@widget/c/<widgetName>` with attribute mapping per the widget-rendition pattern. Without this, the widget bundle ships dead. `renderer-wires-widget` enforces existence and binding.
+10. **No shell metacharacters that trigger the Vibes safe-shell filter.** In every `Bash` tool call emitted by this orchestrator and by any leaf skill it invokes, do NOT use command substitution (`$(…)` or backticks), process substitution (`<(…)`, `>(…)`), brace expansion (`{a,b,c}` or `{1..N}`), or `eval` / `exec`. These patterns force manual approval even under Bypass mode and stall the eval. Instead: run separate commands (`mkdir -p a && mkdir -p b`, not `mkdir -p {a,b}`); print each intermediate value with its own command and reason about the result rather than capturing it (`jq … file` on its own, not `X=$(jq … file)`); use plain shell variables (`X=literal`) or here-strings when a value must be reused across commands.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/lightning-type-discovery.md` | Phase 2 — local-project scan, org retrieve, ambiguity handling, in-scope verification, and ensuring the backing Apex class is in the local project. |
+| `references/build-plan-format.md` | Phase 3 — plan template the model fills before STOP. |
+| `references/validation-gates.md` | Phase 5 — full hard / warn gate table with error→fix mapping. |
+| `examples/existing-lightning-type-with-widget-prompt.md` | Phase 3 — before drafting the build plan, read this for a complete `existing-lightning-type-with-widget` walkthrough. |
+| `examples/new-lightning-type-with-widget-prompt.md` | Phase 3 — before drafting the build plan, read this for a complete `new-lightning-type-with-widget` walkthrough. |

package/skills/platform-lightning-type-widget-coordinate/examples/existing-lightning-type-with-widget-prompt.md

@@ -0,0 +1,80 @@
+# Worked Example — Render an Existing Apex-Backed Lightning Type
+
+## User prompt
+
+> Build a widget for the OrderSummary Lightning Type — show order id, customer, total, and a list of line items.
+
+## Walkthrough
+
+**Phase 1 — Path selection.** The prompt names a Lightning Type (`OrderSummary`) and treats it as existing → pick the `existing-lightning-type-with-widget` path. Phase 4 will load `platform-widget-generate` only, after Phase 2 confirms the type is Apex-backed.
+
+**Phase 2 — Lightning Type discovery.** Find first, verify after.
+
+```bash
+$ rg -l 'lightning:type' force-app/**/lightningTypes/OrderSummary/
+force-app/main/default/lightningTypes/OrderSummary/schema.json
+```
+
+Found in the local project. Now verify in scope — read `schema.json`. Root is `"lightning:type": "@apexClassType/orders__OrderSummary"`. Apex-backed → continue. Capture path + SHA-256 + Apex class FQN `orders__OrderSummary` (outer-class form; an inner-class root like `orders__OrderResponses$CreateResult` is also in scope and would scope the trace to that inner class). Source = `existing in local project`.
+
+> If the root had been `lightning__objectType` (object/JSON-based), the orchestrator would have stopped here and routed the user to use `platform-custom-lightning-type-generate` and `platform-widget-generate` separately.
+
+**Phase 3 — Build plan.** Print:
+
+```text
+Lightning Type + Widget Build Plan: orderSummaryWidget
+
+PLAN: Generate a widget that renders the existing OrderSummary Lightning Type.
+
+LIGHTNING TYPE:
+  Name: OrderSummary
+  Source: existing in local project
+  Path: force-app/main/default/lightningTypes/OrderSummary/schema.json
+  Renderer (wires the Lightning Type to the widget): force-app/main/default/lightningTypes/OrderSummary/lightningDesktopGenAi/renderer.json
+  Schema fingerprint (captured before any sub-skill runs): <hex>
+  Apex class FQN: orders__OrderSummary
+
+WIDGET:
+  Name: orderSummaryWidget
+  Output:
+    force-app/main/default/uiWidgets/orderSummaryWidget/orderSummaryWidget.json
+    force-app/main/default/uiWidgets/orderSummaryWidget/schema.json
+    force-app/main/default/uiWidgets/orderSummaryWidget/orderSummaryWidget.uiwidget-meta.xml
+  Schema source: derived from Apex class @AuraEnabled fields via the Lightning Type
+  Layout intent: card with header (id + customer), body (total + shipping-address fields), footer (line items list with forEach)
+  Properties omitted: lastUpdatedTime (audit field, not relevant to render — proposed omission)
+
+SUB-SKILLS THAT WILL RUN:
+  platform-widget-generate
+
+VALIDATIONS THAT WILL RUN AFTER GENERATION:
+  Widget bundle self-validation (run by platform-widget-generate):
+    - widget schema.json parses, root keys correct, every leaf has lightning:type
+    - every {!$attrs.X} (and {!$attrs.shippingAddress.city} for the singular nested address object) resolves
+    - <name>.uiwidget-meta.xml is well-formed XML, root is <UiWidgetBundle>, and declares <widgetType>JSON</widgetType>
+  Cross-skill checks (run by this orchestrator):
+    - lightning-type-unchanged: existing schema.json is byte-identical to the captured fingerprint
+    - renderer-wires-widget: renderer.json references @widget/c/orderSummaryWidget with one {!$attrs.<schemaPropertyName>} mapping per widget schema property
+    - field-trace: print @AuraEnabled fields, widget properties (with nested dot paths and list-item paths expanded), and the diff
+
+----------------------------------------------------------------
+STOP — wait for the user to Approve or Decline.
+```
+
+User picks Approve.
+
+**Phase 4 — Generation.** Load `platform-widget-generate`. Hand it the Lightning Type schema path, the Apex class FQN (`orders__OrderSummary`), and the widget name. The widget skill derives its `schema.json` from the Apex class's `@AuraEnabled` fields:
+
+- Primitive fields → primitive `lightning:type`.
+- Singular nested inner class (e.g. `Address shippingAddress`) → `lightning__objectType`; bound in the widget body via dot-notation `{!$attrs.shippingAddress.city}`, `{!$attrs.shippingAddress.zip}`.
+- `List<LineItem> lineItems` → `lightning__listType`; iterated with `forEach`/`forItem` and bound via `{!$item.<innerField>}`.
+
+The skill omits `lastUpdatedTime` per the build plan and writes the three widget files. Then author `force-app/main/default/lightningTypes/OrderSummary/lightningDesktopGenAi/renderer.json` using the widget-rendition pattern, binding each widget attribute via `{!$attrs.<schemaPropertyName>}`. (If `renderer.json` already exists referencing a different widget or a custom LWC, STOP and surface the conflict.)
+
+**Phase 5 — Validation.** The widget skill reports its own self-validation results. This orchestrator runs:
+
+- `lightning-type-unchanged` — confirms the Lightning Type was untouched.
+- `renderer-wires-widget` — confirms the renderer points at this widget and binds every widget schema property.
+- `field-trace` — prints APEX_FIELDS / WIDGET_PROPS / INVENTED / OMITTED. The omission of `lastUpdatedTime` is in the build plan and emits no warning.
+
+**Phase 6 — Summary.** Print files generated and each validation result by name (`lightning-type-unchanged: pass`, `renderer-wires-widget: pass`, `field-trace: pass`), followed by the deploy command.

package/skills/platform-lightning-type-widget-coordinate/examples/new-lightning-type-with-widget-prompt.md

@@ -0,0 +1,75 @@
+# Worked Example — Create a New Apex-Backed Lightning Type With a Widget
+
+## User prompt
+
+> Generate a Lightning Type and a widget for an account briefing — fields: account name, owner, last activity date, top three open opportunities.
+
+> Note: the user did not mention Apex. This orchestrator only supports Apex-backed Lightning Types, so the `new-lightning-type-with-widget` path implicitly engages `platform-apex-generate` because the new typed Lightning Type requires a backing Apex class. The orchestrator surfaces this Apex step in the Phase 3 build plan so the developer sees what it intends to do.
+
+## Walkthrough
+
+**Phase 1 — Path selection.** User asks for a new Lightning Type plus a widget. Pick the `new-lightning-type-with-widget` path: `platform-apex-generate` → `platform-custom-lightning-type-generate` → `platform-widget-generate`. Apex backing for the typed payload is implied; do not ask the user to confirm Apex is wanted.
+
+**Phase 2 — Lightning Type discovery.** **Skipped.** The prompt is explicit about creating a new Lightning Type, so there is no existing schema to discover and no fingerprint to capture.
+
+**Phase 3 — Build plan.** Print:
+
+```text
+Lightning Type + Widget Build Plan: accountBriefingWidget
+
+PLAN: Create a new Apex class, Lightning Type, and widget for AccountBriefing.
+
+LIGHTNING TYPE:
+  Name: AccountBriefing
+  Source: newly created
+  Path: force-app/main/default/lightningTypes/AccountBriefing/schema.json
+  Renderer (wires the Lightning Type to the widget): force-app/main/default/lightningTypes/AccountBriefing/lightningDesktopGenAi/renderer.json
+  Apex class FQN: c__AccountBriefing
+
+APEX (only when creating a new Lightning Type — auto-engaged because this orchestrator only supports Apex-backed Lightning Types):
+  Class name: AccountBriefing
+  Class FQN: c__AccountBriefing
+  Shape: outer class with @AuraEnabled fields (accountName, ownerName, lastActivityDate, primaryContact: Contact, openOpportunities: List<OpenOpportunity>). Contact is an inner class for a singular nested object. OpenOpportunity is an inner class for nested list elements. The Apex shape itself is owned by platform-apex-generate.
+  Returns: typed payload shaped to AccountBriefing
+
+WIDGET:
+  Name: accountBriefingWidget
+  Output:
+    force-app/main/default/uiWidgets/accountBriefingWidget/accountBriefingWidget.json
+    force-app/main/default/uiWidgets/accountBriefingWidget/schema.json
+    force-app/main/default/uiWidgets/accountBriefingWidget/accountBriefingWidget.uiwidget-meta.xml
+  Schema source: derived from Apex class @AuraEnabled fields via the Lightning Type
+  Layout intent: header card (name + owner + last activity + primary contact name/title via dot-notation), body list (top opportunities with forEach over List<OpenOpportunity>)
+  Properties omitted: none
+
+SUB-SKILLS THAT WILL RUN:
+  platform-apex-generate
+  platform-custom-lightning-type-generate
+  platform-widget-generate
+
+VALIDATIONS THAT WILL RUN AFTER GENERATION:
+  Widget bundle self-validation (run by platform-widget-generate):
+    - widget schema.json parses, root keys correct, every leaf has lightning:type
+    - every {!$attrs.X} (and {!$attrs.primaryContact.name} for the singular nested contact object, {!$item.X} inside forEach) resolves
+    - <name>.uiwidget-meta.xml is well-formed XML, root is <UiWidgetBundle>, and declares <masterLabel>, <description>, and <widgetType>JSON</widgetType>
+  Cross-skill checks (run by this orchestrator):
+    - renderer-wires-widget: renderer.json references @widget/c/accountBriefingWidget with one {!$attrs.<schemaPropertyName>} mapping per widget schema property
+    - field-trace: print @AuraEnabled fields from AccountBriefing plus inner classes Contact and OpenOpportunity, widget properties (with nested dot paths and list-item paths expanded), and the diff
+    - deploy-check: `sf project deploy --check-only --source-dir force-app/main/default/classes/AccountBriefing.cls,force-app/main/default/lightningTypes/AccountBriefing` (RUN the command — do not assume).
+
+----------------------------------------------------------------
+STOP — wait for the user to Approve or Decline.
+```
+
+User picks Approve.
+
+**Phase 4 — Generation.**
+
+1. Load `platform-apex-generate`. Author `AccountBriefing.cls` (outer class with `@AuraEnabled` fields including `Contact primaryContact` as a singular nested object and `List<OpenOpportunity> openOpportunities` as a list-element collection; `Contact` and `OpenOpportunity` are inner classes). Capture FQN `c__AccountBriefing` (outer-class form for this example).
+2. Load `platform-custom-lightning-type-generate`. Author `lightningTypes/AccountBriefing/schema.json` with `lightning:type: "@apexClassType/c__AccountBriefing"` (outer-class form).
+3. Load `platform-widget-generate`. Pass the Lightning Type schema path, the Apex class FQN, and the widget name. The widget skill derives its `schema.json` and writes the three widget files. `Contact primaryContact` becomes a `lightning__objectType` property bound via `{!$attrs.primaryContact.name}` etc.; `List<OpenOpportunity>` becomes a `lightning__listType` property whose body iterates with `forEach`/`forItem` and binds `{!$item.<innerField>}`.
+4. Author `lightningTypes/AccountBriefing/lightningDesktopGenAi/renderer.json` using the **widget rendition pattern** (see `platform-custom-lightning-type-generate/SKILL.md` step 4): a thin wrapper whose first child is `"definition": "@widget/c/accountBriefingWidget"` with attribute mappings binding each widget attribute to a Lightning Type schema property via `{!$attrs.<schemaPropertyName>}`.
+
+**Phase 5 — Validation.** The widget skill reports its own self-validation results. This orchestrator runs `renderer-wires-widget`, `field-trace`, and `deploy-check` (the `sf project deploy --check-only ...` command above). Reporting `pass` without running `deploy-check` is a hard violation — report `not run` instead.
+
+**Phase 6 — Summary.** Print each validation result by name and value (`renderer-wires-widget: pass`, `field-trace: pass`, `deploy-check: pass`), files generated, and the deploy command.

package/skills/platform-lightning-type-widget-coordinate/references/build-plan-format.md

@@ -0,0 +1,67 @@
+# Build Plan Format
+
+Use this template in Phase 3 to print the plan before the STOP gate. Fill every section. Do not abbreviate.
+
+---
+
+```text
+Lightning Type + Widget Build Plan: <widgetName>
+
+PLAN: <one line in developer-facing terms, e.g.:
+  "Generate a widget that renders the existing OrderStatusResponse Lightning Type"
+  OR
+  "Create a new Apex class, Lightning Type, and widget for AppointmentSummary">
+
+LIGHTNING TYPE:
+  Name: <TypeName>
+  Source: <existing in local project | retrieved from org | newly created>
+  Path: <pkgDir>/lightningTypes/<TypeName>/schema.json
+  Renderer (wires the Lightning Type to the widget): <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json
+  Schema fingerprint (captured before any sub-skill runs): <hex SHA-256>   # omit when source is "newly created"
+  Apex class FQN: <namespace>__<ClassName>[$<InnerClass>]   # outer-class form, or inner-class form when the CLT roots on a specific inner class
+
+APEX (only when creating a new Lightning Type — auto-engaged because this orchestrator only supports Apex-backed Lightning Types):
+  Class name: <ClassName>
+  Class FQN: <namespace>__<ClassName>
+  Shape: outer class with @AuraEnabled fields matching the desired Lightning Type payload. Inner classes are used for nested list-element types (e.g. List<OpenOpportunity>) and for singular nested objects (e.g. Address address). The Apex shape itself is owned by platform-apex-generate; this plan records the FQN and field summary, not the class body.
+  Returns: typed payload shaped to <TypeName>
+
+WIDGET:
+  Name: <widgetName>
+  Output:
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
+    <pkgDir>/uiWidgets/<widgetName>/schema.json
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml
+  Schema source: <derived from Apex class @AuraEnabled fields via the Lightning Type | derived from prompt fields>
+  Layout intent: <one-line description of the widget composition>
+  Properties omitted: <list any Apex class fields the widget intentionally drops, e.g. lastUpdatedTime, audit fields — or "none">
+
+SUB-SKILLS THAT WILL RUN:
+  <list per the chosen path's row in SKILL.md — skill IDs only>
+
+VALIDATIONS THAT WILL RUN AFTER GENERATION:
+  Widget bundle self-validation (run by platform-widget-generate):
+    - widget schema.json parses and has the required root keys
+    - every leaf in properties has a lightning:type
+    - every {!$attrs.X} (and {!$attrs.<outer>.<inner>} for nested objects, {!$item.X} inside forEach) resolves
+    - <name>.uiwidget-meta.xml is well-formed XML, root is <UiWidgetBundle>, and declares <widgetType>JSON</widgetType>
+  Cross-skill checks (run by this orchestrator):
+    - lightning-type-unchanged: when an existing Lightning Type was used as input, its schema.json is byte-identical to the version captured before this run
+    - renderer-wires-widget: the Lightning Type's renderer.json exists and references this widget via `@widget/c/<widgetName>`, with one {!$attrs.<schemaPropertyName>} mapping per widget schema property
+    - field-trace (advisory): print the @AuraEnabled fields from the outer Apex class plus every inner class referenced as a singular nested object or List<InnerClass>; print the widget schema properties (expanded for nested objects and list items); print the diff. Invented widget fields fail; omissions not declared above warn.
+    - deploy-check (advisory, new-type path only): `sf project deploy --check-only --source-dir <pkgDir>/classes/<ClassName>.cls,<pkgDir>/lightningTypes/<TypeName>` is run and the result reported.
+
+----------------------------------------------------------------
+STOP — wait for the user to Approve or Decline.
+The host surface may render Approve/Decline as buttons; a text reply ("approve", "yes", "go") is also accepted.
+A Decline (or edits to the plan) reprints the plan; the orchestrator does not write any file until an explicit Approve.
+```
+
+---
+
+## Notes for the model
+
+- If the user replies with edits or declines, revise the plan and reprint it. Do not assume which sections changed.
+- Approval applies only to the plan as printed. If the user later asks for additional widgets or Lightning Types, start a new planning cycle for the new ask.
+- Do not print this plan inside a code fence that the user might mistake for output. The plan is conversational, not a file.
+- "Properties omitted" makes intentional drops explicit. Examples of fields that often do not belong on a render surface: `lastUpdatedTime`, `createdBy`, audit timestamps, internal IDs.