@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/platform-trial-org-create/scripts/create_signup_request.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+#
+# create_signup_request.sh — Create a Salesforce trial org by inserting a
+# SignupRequest sObject against an authenticated host org.
+#
+# This wraps the deterministic parts of the create step: enforcing the
+# "exactly one of --template-id / --edition" rule, assembling and quoting the
+# `sf data create record --values` payload, running the insert, and returning
+# the assigned SignupRequest id (0SR...). Prose interpretation is not needed —
+# the field-selection and serialization rules live here.
+#
+# Auth is handled by the `sf` CLI (the access token never surfaces here).
+#
+# Usage:
+#   create_signup_request.sh --target-org <alias-or-username> \
+#     --last-name <name> --email <addr> --username <email-format> \
+#     --company <name> --country <ISO> \
+#     ( --template-id 0TT... | --edition Developer ) \
+#     [--first-name <name>]
+#
+# Options:
+#   --target-org, -o <org>  REQUIRED. Host org alias or username to create in.
+#   --last-name <name>      REQUIRED. Admin user last name.
+#   --email <addr>          REQUIRED. SignupEmail — a real inbox.
+#   --username <email>      REQUIRED. Admin username (email-format, globally unique).
+#   --company <name>        REQUIRED. Company / org name (spaces allowed).
+#   --country <ISO>         REQUIRED. ISO country code (e.g. US, GB, IN).
+#   --template-id 0TT...    Trialforce template id. Mutually exclusive with --edition.
+#   --edition <Edition>     Generic edition (Developer, Enterprise, ...). Mutually
+#                           exclusive with --template-id.
+#   --first-name <name>     Optional. Admin user first name.
+#   --output-dir <dir>      On a rejected create, write the failure outcome to
+#                           <dir>/signup-request-result.json (so the run still
+#                           has an artifact when no org is created).
+#   --json                  Emit the raw `sf` create envelope as-is (default:
+#                           print the 0SR id on success, error text on failure).
+#   --help, -h              Show this help.
+#
+# Output:
+#   On success (default): the SignupRequest id (0SR...) on stdout, exit 0.
+#   On success (--json):  the raw `sf data create record --json` envelope.
+#   On failure:           the raw CLI error (name/code + message) on stderr, and
+#                         (with --output-dir) a create-rejected artifact JSON.
+#
+# Exit codes:
+#   0  create succeeded
+#   1  create rejected by the API (validation / entitlement / access error)
+#   2  bad usage or missing dependency (sf or jq)
+
+set -uo pipefail
+
+die() { echo "Error: $*" >&2; exit 2; }
+
+command -v sf >/dev/null 2>&1 || die "Salesforce CLI ('sf') not found on PATH."
+command -v jq >/dev/null 2>&1 || die "'jq' not found on PATH."
+
+TARGET_ORG=""
+LAST_NAME=""
+EMAIL=""
+USERNAME=""
+COMPANY=""
+COUNTRY=""
+TEMPLATE_ID=""
+EDITION=""
+FIRST_NAME=""
+OUTPUT_DIR=""
+OUTPUT="id"
+
+usage() { sed -n '2,/^set -uo/p' "$0" | sed '/^set -uo/d; s/^# \{0,1\}//; s/^#//'; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target-org|-o) TARGET_ORG="${2:-}"; shift 2 ;;
+    --last-name)     LAST_NAME="${2:-}"; shift 2 ;;
+    --email)         EMAIL="${2:-}"; shift 2 ;;
+    --username)      USERNAME="${2:-}"; shift 2 ;;
+    --company)       COMPANY="${2:-}"; shift 2 ;;
+    --country)       COUNTRY="${2:-}"; shift 2 ;;
+    --template-id)   TEMPLATE_ID="${2:-}"; shift 2 ;;
+    --edition)       EDITION="${2:-}"; shift 2 ;;
+    --first-name)    FIRST_NAME="${2:-}"; shift 2 ;;
+    --output-dir)    OUTPUT_DIR="${2:-}"; shift 2 ;;
+    --json)          OUTPUT="json"; shift ;;
+    --help|-h)       usage; exit 0 ;;
+    *)               die "Unknown argument: $1" ;;
+  esac
+done
+
+# --- required-field validation ------------------------------------------
+[ -n "$TARGET_ORG" ] || die "--target-org is required (host org alias or username)."
+[ -n "$LAST_NAME" ]  || die "--last-name is required."
+[ -n "$EMAIL" ]      || die "--email is required."
+[ -n "$USERNAME" ]   || die "--username is required."
+[ -n "$COMPANY" ]    || die "--company is required."
+[ -n "$COUNTRY" ]    || die "--country is required (ISO code, e.g. US)."
+
+# --- exactly-one-of rule (TemplateId XOR Edition) -----------------------
+if [ -n "$TEMPLATE_ID" ] && [ -n "$EDITION" ]; then
+  die "Send exactly one of --template-id or --edition, not both (would fail with redundantTemplateId)."
+fi
+if [ -z "$TEMPLATE_ID" ] && [ -z "$EDITION" ]; then
+  die "Send exactly one of --template-id or --edition (neither given would fail with missingEdition)."
+fi
+
+# --- reject values 'sf --values' cannot represent -----------------------
+# A value containing BOTH a single and a double quote cannot be expressed in the
+# space-separated --values string, whose parser honors only one quote style per
+# token. Check here in the main scope: a guard inside sf_quote would run inside
+# $(...) command substitution, where `exit` kills only the subshell and (with no
+# `set -e`) the script would carry on and issue a malformed create.
+for v in "$LAST_NAME" "$EMAIL" "$USERNAME" "$COMPANY" "$COUNTRY" \
+         "$FIRST_NAME" "$TEMPLATE_ID" "$EDITION"; do
+  case "$v" in
+    *\'*\"* | *\"*\'*) die "Value contains both single and double quotes, which 'sf --values' cannot represent: $v" ;;
+  esac
+done
+
+# --- assemble the --values payload --------------------------------------
+# `sf data create record --values` takes ONE space-separated string of
+# Field=Value pairs and re-splits it on whitespace, honoring only quotes that
+# appear *inside* that string (see plugin-data's stringToDictionary parser).
+# So any value containing whitespace (e.g. Company="Acme Corporation") must be
+# quoted within the payload, or sf mis-parses it into separate tokens. Quote
+# each value: single-quote by default; switch to double quotes when the value
+# itself contains a single quote (e.g. a last name like O'Brien). Values with
+# both quote types are already rejected above.
+sf_quote() {
+  case "$1" in
+    *\'*) printf '"%s"' "$1" ;;
+    *)    printf "'%s'" "$1" ;;
+  esac
+}
+
+PAIRS=(
+  "LastName=$(sf_quote "$LAST_NAME")"
+  "SignupEmail=$(sf_quote "$EMAIL")"
+  "Username=$(sf_quote "$USERNAME")"
+  "Company=$(sf_quote "$COMPANY")"
+  "Country=$(sf_quote "$COUNTRY")"
+)
+[ -n "$FIRST_NAME" ]  && PAIRS+=("FirstName=$(sf_quote "$FIRST_NAME")")
+[ -n "$TEMPLATE_ID" ] && PAIRS+=("TemplateId=$(sf_quote "$TEMPLATE_ID")")
+[ -n "$EDITION" ]     && PAIRS+=("Edition=$(sf_quote "$EDITION")")
+
+# Join the quoted pairs into the single space-separated string sf expects.
+VALUES_STR="${PAIRS[*]}"
+
+# --- run the insert ------------------------------------------------------
+RESP="$(sf data create record --target-org "$TARGET_ORG" --sobject SignupRequest \
+  --values "$VALUES_STR" --json 2>/dev/null)"
+
+STATUS="$(printf '%s' "$RESP" | jq -r '.status // 1' 2>/dev/null)"
+
+if [ "$STATUS" != "0" ]; then
+  # Surface the raw CLI error verbatim (name/code + message) — do not diagnose.
+  NAME="$(printf '%s' "$RESP" | jq -r '.name // .code // "ERROR"')"
+  MSG="$(printf '%s' "$RESP" | jq -r '.message // "unknown error"')"
+  printf '%s: %s\n' "$NAME" "$MSG" >&2
+  # No org is created on a rejected create, so get_signup_request.sh never runs.
+  # Still leave the run an artifact when --output-dir is given: capture the
+  # create-rejected outcome and the raw error verbatim (no diagnosis).
+  if [ -n "$OUTPUT_DIR" ]; then
+    mkdir -p "$OUTPUT_DIR"
+    jq -n --arg name "$NAME" --arg msg "$MSG" \
+      '{outcome: "create-rejected", error: {name: $name, message: $msg}, CreatedOrgId: null, Status: null}' \
+      > "$OUTPUT_DIR/signup-request-result.json"
+  fi
+  exit 1
+fi
+
+if [ "$OUTPUT" = "json" ]; then
+  printf '%s\n' "$RESP"
+else
+  printf '%s\n' "$(printf '%s' "$RESP" | jq -r '.result.id')"
+fi

package/skills/platform-trial-org-create/scripts/get_signup_request.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+#
+# get_signup_request.sh — Read back a SignupRequest to pick up the assigned
+# trial org id, applying a fixed polling policy, and (optionally) write the
+# record as the skill's output artifact.
+#
+# Trial-org provisioning is asynchronous: the insert only returns the 0SR
+# handle, while CreatedOrgId / Status populate shortly after. This script
+# encapsulates the deterministic policy so every invocation behaves the same:
+#   - read the record;
+#   - stop as soon as CreatedOrgId is populated (this typically happens while
+#     Status is still InProgress — the caller need not wait for Success);
+#   - otherwise re-read up to --max-attempts times TOTAL, sleeping --delay
+#     seconds between reads, then return the current state (no infinite loop);
+#   - stop immediately on a terminal Status (Success or Error) or a CLI error.
+#
+# It always prints the resolved record (its `result` object) as JSON on stdout.
+# With --output-dir it also writes that JSON to <dir>/signup-request-result.json.
+#
+# Auth is handled by the `sf` CLI (the access token never surfaces here).
+#
+# Usage:
+#   get_signup_request.sh --target-org <org> --id <0SR...> [--output-dir <dir>]
+#   get_signup_request.sh --target-org <org> --id <0SR...> --max-attempts 3 --delay 20
+#
+# Options:
+#   --target-org, -o <org>  REQUIRED. Host org alias or username.
+#   --id, -i <0SR...>       REQUIRED. SignupRequest id to read.
+#   --output-dir <dir>      Write the record JSON to <dir>/signup-request-result.json.
+#   --max-attempts <n>      TOTAL reads before giving up on an empty CreatedOrgId
+#                           (1 to 3; default 3). Provisioning is async, so we do
+#                           not poll indefinitely: at most three lookups, then
+#                           hand back the request id (exit 3) for the user to
+#                           re-check.
+#   --delay <seconds>       Sleep between reads (default 20).
+#   --help, -h              Show this help.
+#
+# Output:
+#   The SignupRequest record (the `sf` envelope's `result`) as JSON on stdout.
+#
+# Exit codes:
+#   0  CreatedOrgId populated (org allocated) — the only exit that carries an org id
+#   1  Status=Error, or the record could not be read (auth / id not found)
+#   2  bad usage or missing dependency (sf or jq)
+#   3  no org id available — record read but CreatedOrgId still empty (still
+#      provisioning after --max-attempts, or a terminal status with no id).
+#      Not an error. The caller reports the 0SR id and the record's REAL Status,
+#      and tells the user to re-check later. The exit code never reflects a
+#      synthesized status — only what is actually on the record.
+
+set -uo pipefail
+
+die() { echo "Error: $*" >&2; exit 2; }
+
+command -v sf >/dev/null 2>&1 || die "Salesforce CLI ('sf') not found on PATH."
+command -v jq >/dev/null 2>&1 || die "'jq' not found on PATH."
+
+TARGET_ORG=""
+SR_ID=""
+OUTPUT_DIR=""
+MAX_ATTEMPTS=3
+DELAY=20
+
+usage() { sed -n '2,/^set -uo/p' "$0" | sed '/^set -uo/d; s/^# \{0,1\}//; s/^#//'; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target-org|-o) TARGET_ORG="${2:-}"; shift 2 ;;
+    --id|-i)         SR_ID="${2:-}"; shift 2 ;;
+    --output-dir)    OUTPUT_DIR="${2:-}"; shift 2 ;;
+    --max-attempts)  MAX_ATTEMPTS="${2:-}"; shift 2 ;;
+    --delay)         DELAY="${2:-}"; shift 2 ;;
+    --help|-h)       usage; exit 0 ;;
+    *)               die "Unknown argument: $1" ;;
+  esac
+done
+
+[ -n "$TARGET_ORG" ] || die "--target-org is required."
+[ -n "$SR_ID" ]      || die "--id is required (the 0SR... SignupRequest id)."
+case "$MAX_ATTEMPTS" in 1|2|3) ;; *) die "--max-attempts must be 1, 2, or 3 (provisioning is async; we do not poll more than three times)." ;; esac
+case "$DELAY" in ''|*[!0-9]*) die "--delay must be a non-negative integer." ;; esac
+
+# read the record once; sets RESULT (the `result` object) and RECORD_STATUS,
+# or returns non-zero on a CLI error (RESULT holds the raw error envelope).
+read_record() {
+  local resp env_status
+  resp="$(sf data get record --target-org "$TARGET_ORG" --sobject SignupRequest \
+    --record-id "$SR_ID" --json 2>/dev/null)"
+  env_status="$(printf '%s' "$resp" | jq -r '.status // 1' 2>/dev/null)"
+  if [ "$env_status" != "0" ]; then
+    printf '%s' "$resp" | jq -r '"\(.name // .code // "ERROR"): \(.message // "unknown error")"' >&2
+    return 1
+  fi
+  RESULT="$(printf '%s' "$resp" | jq '.result')"
+  RECORD_STATUS="$(printf '%s' "$RESULT" | jq -r '.Status // ""' | tr '[:upper:]' '[:lower:]')"
+  CREATED_ORG_ID="$(printf '%s' "$RESULT" | jq -r '.CreatedOrgId // ""')"
+  return 0
+}
+
+RESULT=""
+RECORD_STATUS=""
+CREATED_ORG_ID=""
+FINAL_RC=0
+
+# At most MAX_ATTEMPTS total reads (1 to 3). Provisioning is async, so if the
+# org id has not appeared by the final read we stop and hand back the request
+# id rather than polling on — the caller reports 0SR and asks the user to
+# re-check later (exit 3).
+attempt=0
+while : ; do
+  if ! read_record; then
+    exit 1
+  fi
+  attempt=$((attempt + 1))
+  # Stop as soon as the org is allocated, or on a terminal status. Success and
+  # Error are both terminal — there is nothing to gain by re-reading either, so
+  # neither consumes the retry budget. The exit code is driven by what is
+  # actually on the record, never by a synthesized value:
+  #   - CreatedOrgId present            -> 0 (org allocated; caller shares the id)
+  #   - Status=Error                    -> 1 (provisioning failed)
+  #   - terminal but no id (e.g. odd
+  #     Success with empty CreatedOrgId) -> 3 (no id to give; report real Status)
+  if [ -n "$CREATED_ORG_ID" ]; then
+    FINAL_RC=0
+    break
+  fi
+  if [ "$RECORD_STATUS" = "error" ]; then
+    FINAL_RC=1
+    break
+  fi
+  if [ "$RECORD_STATUS" = "success" ]; then
+    # Terminal, but the org id never populated — stop (nothing to re-read) and
+    # hand back the request id with the record's real Status.
+    FINAL_RC=3
+    break
+  fi
+  # CreatedOrgId still empty and status not yet terminal. Give up once we've
+  # used our lookup budget.
+  if [ "$attempt" -ge "$MAX_ATTEMPTS" ]; then
+    FINAL_RC=3
+    break
+  fi
+  sleep "$DELAY"
+done
+
+# Always emit the record as JSON on stdout.
+printf '%s\n' "$RESULT"
+
+# Defined output artifact: write the record when an output dir is given.
+if [ -n "$OUTPUT_DIR" ]; then
+  mkdir -p "$OUTPUT_DIR"
+  printf '%s\n' "$RESULT" > "$OUTPUT_DIR/signup-request-result.json"
+fi
+
+exit "$FINAL_RC"

package/skills/platform-widget-generate/SKILL.md

@@ -2,7 +2,7 @@
 name: platform-widget-generate
 description: "Use this skill to author a complete HXL WidgetBundle (UEM body + schema.json + -meta.xml). TRIGGER when: user asks for a widget, mosaic, fragment, card, or rich UI surface for any subject, domain, feature, or entity noun; the prompt names only an entity or data shape without invoking Lightning Types, CLTs, or Apex-backed types. DO NOT TRIGGER when: the prompt explicitly says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', or references '@apexClassType/...' (use platform-lightning-type-widget-coordinate); authoring a custom-LWC renderer for a Custom Lightning Type (use platform-custom-lightning-type-generate); or editing only an LWC component."
 metadata:
-  version: "1.2"
+  version: "1.3"
   domains: ["Platform", "Agentforce"]
   minApiVersion: "68.0"
   relatedSkills:
@@ -96,6 +96,42 @@ The first child of `tile/widget.children` SHOULD be a single `tile/column`. All
 
 ---
 
+## Actions
+
+`tile/button` supports an `actions` attribute that dispatches an action node on an event. Two action definitions are supported:
+
+| Action | Timing | Required attributes | Effect |
+|---|---|---|---|
+| `action/openLink` | synchronous | `url` (string). Optional `target` (`_blank`\|`_self`, default `_blank`) | Opens a URL |
+| `action/sendMessage` | asynchronous | `content` (string) | Posts a new user message back to the agent and earns a fresh turn |
+
+```json
+{
+  "definition": "tile/button",
+  "attributes": {
+    "label": "Button Label",
+    "variant": "primary",
+    "actions": { "click": [ { "definition": "action/sendMessage", "attributes": { "content": "content" } } ] }
+  }
+}
+```
+
+```json
+{
+   "definition": "tile/button",
+   "attributes": {
+      "label": "Button Label",
+      "variant": "primary",
+      "actions": { "click": [ { "definition": "action/openLink", "attributes": { "url": "https://www.example.com", "target": "_blank" } } ] }
+   }
+}
+```
+
+
+**A `tile/button` with no `actions` attribute renders disabled** — a button exists to trigger an action, so always attach a `click` action to a button meant to be interactive.
+
+---
+
 ## Layout Best Practices
 
 These conventions cover widget *structure* — how blocks are grouped and stacked.
@@ -116,11 +152,12 @@ These conventions cover widget *structure* — how blocks are grouped and stacke
 Widgets express *intent*, not pixels. Each surface provides a default look and feel; brand/theme overrides apply automatically.
 
 - **Style semantically.** Use `variant`, `size`, and other enum-typed attributes (`primary`, `destructive`, `success`, `warning`). Do not pin literal colors or pixel values.
-- **One primary action per visible group.** At most one `tile/button` with `variant: primary`. Use `secondary`, `outline`, or `ghost` for additional actions.
+- **One primary action per visible group.** At most one `tile/button` with `variant: primary`. Use `secondary` or `destructive` for additional actions (see the `tile/button` schema for the full variant enum).
+- **Every `tile/button` needs a `click` action.** See *Actions* above — an action-less button renders disabled.
 - **One `h1` per widget.** Use `h2`/`h3` for sub-section headings, `body` for prose, `caption` for helper text.
-- **Use semantic state variants on state-bearing blocks** (`tile/alert`, `tile/badge`, `tile/callout`, `tile/chip`).
-- **Accept schema defaults for `gap`, `padding`, `size`** unless there is a specific reason to override.
-- **Don't pin `width`, `height`, `maxWidth`** unless a content constraint requires it. For long text, use `truncate: true`.
+- **Use semantic state variants on state-bearing blocks** (`tile/badge`, `tile/callout`).
+- **Accept schema defaults for `gap`, `size`** unless there is a specific reason to override.
+- **Don't pin `width`** unless a content constraint requires it.
 - **Use the Lucide icon set.** Pass the Lucide name (`"check"`, `"alert-circle"`); other icon libraries are not supported.
 
 ---
@@ -197,12 +234,13 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 9. **Self-validate.** Before reporting, confirm each check below and report each result individually (`pass` or `fail (<reason>)`). Do **not** summarize as a single "all passed" line — list every check so a reviewer can spot a silent skip.
     - **`schema-parses`** — `<pkgDir>/uiWidgets/<widgetName>/schema.json` parses as JSON.
     - **`schema-root-keys`** — root has `title` (string), `type: "object"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: "lightning__objectType"` and a nested `properties` map. No `unevaluatedProperties: false`.
-    - **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map. See `references/schema-from-lightning-type.md`.
+    - **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: "lightning__objectType"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.
     - **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream.
     - **`body-envelope`** — `<widgetName>.json` root has `type: "lightning__agentforceWidget"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.
     - **`metaxml-wellformed`** — `<widgetName>.uiwidget-meta.xml` parses as well-formed XML.
     - **`metaxml-elements`** — `<widgetName>.uiwidget-meta.xml` has root `<UiWidgetBundle>` and contains `<masterLabel>` (non-empty), `<description>` (non-empty), and `<widgetType>JSON</widgetType>`.
     - **`files-present`** — all three files exist at the resolved `<pkgDir>/uiWidgets/<widgetName>/` path.
+    - **`button-actions-present`** — every `tile/button` in `<widgetName>.json` has an `actions.click` action node whose `definition` is `action/openLink` or `action/sendMessage`.
 
 ---
 
@@ -214,6 +252,7 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 | Never pass `tile/widget` to `getUiComponentSchemas` | It is a fixed wrapper, not a queryable component |
 | Always supply `parameters` (with required keys) when calling `execute_metadata_action` | Missing parameters cause hard failure, not partial result |
 | Every `{!$attrs.X}` in the body resolves to a property in the widget `schema.json` | No invented fields |
+| Every `tile/button` carries an `actions.click` entry using `action/openLink` or `action/sendMessage` only | These are the only two supported tile action definitions; an action-less button renders disabled |
 | No `$(…)`, backticks, `<(…)`, brace expansion `{a,b,c}`, or `eval`/`exec` in any Bash tool call | Vibes' safe-shell filter forces manual approval on these patterns even in Bypass mode. Emit separate commands (`mkdir -p a && mkdir -p b`) or print each value with its own command and reason about the output — do not capture into a shell variable |
 
 ---
@@ -226,6 +265,8 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 | Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference |
 | Output written outside `<pkgDir>/uiWidgets/<widgetName>/` | `<pkgDir>` = `<packageDirectories[].path>/main/default` (see `references/widget-bundle-layout.md`). Dropping the `main/default/` segment is the common cause of widgets landing at `force-app/uiWidgets/...` instead of `force-app/main/default/uiWidgets/...` |
 | `if` bound to a non-boolean | Use `if` only when the schema has a `lightning__booleanType` property |
+| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see *Actions* above) |
+| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX |
 
 ---
 

package/skills/platform-widget-generate/examples/conditional.json

@@ -6,7 +6,7 @@
       "children": [
         {
           "definition": "tile/column",
-          "attributes": { "gap": "md", "padding": "md" },
+          "attributes": { "gap": "md" },
           "children": [
             {
               "definition": "tile/callout",
@@ -21,7 +21,7 @@
             },
             {
               "definition": "tile/column",
-              "attributes": { "padding": "md" },
+              "attributes": { "gap": "md" },
               "meta": { "if": "{!$attrs.isVerified}"},
               "children": [
                 {
@@ -50,7 +50,7 @@
               "children": [
                 {
                   "definition": "tile/column",
-                  "attributes": { "padding": "md" },
+                  "attributes": { "gap": "md" },
                   "children": [
                     {
                       "definition": "tile/row",

package/skills/platform-widget-generate/examples/list-with-foreach.json

@@ -6,7 +6,7 @@
       "children": [
         {
           "definition": "tile/column",
-          "attributes": { "gap": "md", "padding": "md" },
+          "attributes": { "gap": "md" },
           "children": [
             {
               "definition": "tile/text",
@@ -14,7 +14,7 @@
             },
             {
               "definition": "tile/column",
-              "attributes": { "gap": "sm", "padding": "md" },
+              "attributes": { "gap": "sm" },
               "meta": { "forEach": "{!$attrs.products}", "forItem": "$product" },
               "children": [
                 {

package/skills/platform-widget-generate/examples/single-object.json

@@ -6,11 +6,11 @@
       "children": [
         {
           "definition": "tile/column",
-          "attributes": { "gap": "md", "padding": "md" },
+          "attributes": { "gap": "md" },
           "children": [
             {
               "definition": "tile/column",
-              "attributes": { "gap": "md", "padding": "lg" },
+              "attributes": { "gap": "md" },
               "children": [
                 {
                   "definition": "tile/text",

package/skills/platform-widget-generate/references/widget-bundle-layout.md

@@ -64,7 +64,7 @@ JSON Schema describing what data the widget accepts at runtime. Fields are wrapp
 
 - `description` (string)
 
-**Each leaf under `properties.attributes.properties` MUST have `lightning:type`.** Optional per-leaf: `title`, `description`. **A `lightning__listType` leaf MUST also carry `items.lightning:type`** — set to the matching primitive `lightning:type` for a list of primitives, or to an `@apexClassType/...` reference for a list of Apex objects (see `references/schema-from-lightning-type.md`).
+**Each leaf under `properties.attributes.properties` MUST have `lightning:type`.** Optional per-leaf: `title`, `description`. **A `lightning__listType` leaf MUST also carry `items.lightning:type`** — set to the matching primitive `lightning:type` for a list of primitives, or to an `@apexClassType/...` reference for a list of Apex objects (see `references/schema-from-lightning-type.md`). **For a list of plain objects with no Apex-backed type**, `items.lightning:type` is `lightning__objectType` and `items` MUST also carry a nested `properties` map inlining every field the list items expose (same shape as the outer `attributes.properties` map).
 
 Example: