@salesforce/afv-skills 1.24.0 → 1.25.0

package/skills/experience-ui-bundle-salesforce-data-access/references/sdk-api.md

@@ -0,0 +1,217 @@
+# The Data SDK call API (`@salesforce/platform-sdk`)
+
+The `query`/`mutate` namespace, typing, and error handling. For caching and the reactive
+refresh modes see [caching.md](caching.md); for old→new conversion see [migration.md](migration.md).
+
+## Import
+
+```typescript
+import { createDataSDK, gql, type CacheControl, type NodeOfConnection } from "@salesforce/platform-sdk";
+```
+
+`createDataSDK`, `gql`, `CacheControl`, and `NodeOfConnection` all come from
+**`@salesforce/platform-sdk`**. The old `@salesforce/sdk-data` package name is dead — any
+`@salesforce/sdk-data` string you see in the repo is a stale `dist/` build artifact, not the
+canonical import.
+
+## `sdk.graphql` is a NAMESPACE, not a callable
+
+The previous SDK exposed `sdk.graphql` as a callable: `await sdk.graphql?.(query, vars)`.
+That form is gone. `sdk.graphql` is now a namespace with two methods:
+
+```typescript
+const sdk = await createDataSDK();
+
+// QUERY — reactive, cached on WebApp
+const result = await sdk.graphql!.query<TData, TVariables>({
+  query: MY_QUERY,        // gql-tagged string (the `query` key)
+  variables,              // optional
+  operationName,          // optional
+  cacheControl,           // optional — see caching.md
+});
+
+// MUTATE — request/response, never cached
+const { data, errors } = await sdk.graphql!.mutate<TData, TVariables>({
+  mutation: MY_MUTATION,  // NOTE: the key is `mutation`, not `query`
+  variables,
+  operationName,
+});
+```
+
+Type signatures (from `core/data.ts`):
+
+```typescript
+query<T, V>(options: QueryOptions<V>): Promise<QueryResult<T>>;
+mutate<T, V>(options: MutateOptions<V>): Promise<MutationResult<T>>;
+```
+
+### `sdk.graphql!` vs guard
+
+`sdk.graphql` may still be `undefined` on surfaces that do not support data operations, so it
+is typed `graphql?: DataSDKGraphQL`. Real consumer code asserts it is present after
+`createDataSDK()` with the non-null assertion:
+
+```typescript
+const result = await sdk.graphql!.query<...>({ query, variables });
+```
+
+This replaces the old optional-call `sdk.graphql?.(...)`. Do **not** reach for the dead
+callable form. Which of `!` vs a guard you use is a **surface decision** (the spine's
+[Surfaces](../SKILL.md#surfaces--sdkgraphql-vs-guard) table is the routing): `!` only if the
+bundle is WebApp-exclusive; otherwise guard, because a bare `sdk.graphql!` that later ships to
+another surface throws `Cannot read properties of undefined` at runtime — TypeScript won't catch
+it because `!` silences exactly that check.
+
+```typescript
+// `!` form — WebApp-only bundles; every shipped WebApp consumer uses it.
+const result = await sdk.graphql!.query<...>({ query, variables });
+
+// Portable guard form — safe on every surface. Use when the bundle is not WebApp-exclusive.
+if (!sdk.graphql) {
+  // No data SDK on this surface — degrade gracefully (render empty, throw, or feature-flag off).
+  return;
+}
+const result = await sdk.graphql.query<...>({ query, variables });
+```
+
+(The same `!`-vs-guard call applies to `sdk.fetch!`.)
+
+## `QueryResult<T>` — the reactive query handle
+
+`query()` resolves to a `QueryResult<T>`, which IS a snapshot AND carries two reactive methods:
+
+```typescript
+interface QuerySnapshot<T> { data: T | undefined; errors?: GraphQLError[]; }
+type QuerySubscriber<T> = (snapshot: QuerySnapshot<T>) => void;
+type Unsubscribe = () => void;
+
+interface QueryResult<T> extends QuerySnapshot<T> {
+  subscribe(cb: QuerySubscriber<T>): Unsubscribe;
+  refresh(): Promise<void>;
+}
+```
+
+- `result.data` / `result.errors` — the initial snapshot at await-time (cached value on cached
+  surfaces, else the network response).
+- `result.subscribe(cb)` — register a callback for every *subsequent* snapshot (a cache update,
+  a stale-while-revalidate refill, or an explicit `refresh()`). Returns an `Unsubscribe`. Each
+  `subscribe` is **independent** — unsubscribing one leaves the others live — and it does **not**
+  fire on registration, only on later snapshots.
+- `result.refresh()` — re-issue the request bypassing the cache, write the fresh result back, and
+  push the new snapshot to **all** current subscribers. Returns `Promise<void>`.
+
+*When* to reach for `subscribe`/`refresh` over the default cache, plus the uncached-surface
+caveats, is a strategy call — see [caching.md](caching.md).
+
+## `cacheControl` — the per-call cache policy
+
+`cacheControl` is an optional field on the query options bag. It overrides the default cache
+behavior for **one** call and does **not** change the cache key, so a `"no-cache"` call and a
+default call read/write the *same* cache slot. The type:
+
+```typescript
+type CacheControlShorthand = "no-cache" | "only-if-cached";
+interface CacheControlMaxAge { type: "max-age"; maxAge: number; }
+type CacheControl = CacheControlShorthand | CacheControlMaxAge;
+```
+
+| `cacheControl` | Behavior |
+|---|---|
+| *(omitted)* | Default — return the cached entry if fresh (300s TTL), else fetch and write back. |
+| `"no-cache"` | Skip the cache **read**, always hit the network. **Still writes the response back** for later default callers. |
+| `"only-if-cached"` | Read from cache **only**. Hit → return; **miss → `DataNotFoundError` on `result.errors`** (no network, no throw). |
+| `{ type: "max-age", maxAge: <seconds> }` | Custom TTL instead of 300s. `maxAge: 0` = written but immediately stale; invalid values silently fall back to 300s. |
+
+An `only-if-cached` miss is not an exception — the Promise resolves and the miss surfaces on
+`result.errors` as a `DataNotFoundError`. This is offline-first: a miss is **expected, not an
+error**. Check `result.errors`, render an empty state, and **do not fall back to a network read**
+— a fallback defeats the point of `only-if-cached`:
+
+```typescript
+const result = await sdk.graphql!.query({ query: GET_ACCOUNTS, variables, cacheControl: "only-if-cached" });
+if (result.errors?.length) {
+  // cold cache — render the empty state. Do NOT fall back to the network; that defeats offline-first.
+  return renderEmptyState();
+}
+```
+
+Which policy fits which goal (force-refresh button, offline-first, fast-changing data) is a
+strategy call — see the decision matrix in [caching.md](caching.md).
+
+## `MutationResult<T>` — one-shot, NO subscribe/refresh
+
+```typescript
+interface MutationResult<T> { data: T | undefined; errors?: GraphQLError[]; }
+```
+
+Mutations are request/response. The type deliberately has **no** `subscribe` and **no**
+`refresh` — mutating on subscribe is incoherent, and re-running a mutation on refresh is
+dangerous. To refresh data after a mutation, hold a query `result` and call `result.refresh()`
+(see [caching.md](caching.md)).
+
+## HTTP 200 ≠ success — always read `errors`
+
+The Promise resolves even for GraphQL/parse errors; they surface on `result.errors`, never as a
+thrown exception from `query()`/`mutate()`. Both shipped consumers gate on `errors` first:
+
+```typescript
+// accounts.ts pattern
+if (result.errors?.length) {
+  throw new Error(result.errors.map((e) => e.message).join("; "));
+}
+```
+
+```typescript
+// graphqlClient.ts (canonical scaffold) — strict wrapper
+export async function executeGraphQL<TData, TVariables>(
+  query: string,
+  variables?: TVariables,
+): Promise<TData> {
+  const sdk = await createDataSDK();
+  const result = await sdk.graphql!.query<TData, TVariables>({ query, variables });
+  if (result.errors?.length) {
+    throw new Error(`GraphQL Error: ${result.errors.map((e) => e.message).join("; ")}`);
+  }
+  if (result.data == null) {
+    throw new Error("GraphQL response data is null");
+  }
+  return result.data;
+}
+```
+
+Three error-handling stances (all read `result.errors`):
+
+```typescript
+// Strict — any errors = failure
+if (result.errors?.length) throw new Error(result.errors.map((e) => e.message).join("; "));
+
+// Tolerant — log, use whatever data came back (partial success)
+if (result.errors?.length) console.warn("GraphQL partial errors:", result.errors);
+
+// Discriminated — fail only when NO data returned
+if (!result.data && result.errors?.length) {
+  throw new Error(result.errors.map((e) => e.message).join("; "));
+}
+```
+
+## Generated types on the call
+
+After `npm run graphql:codegen`, import the generated `<Op>Query` / `<Op>QueryVariables` types
+and pass them as the type parameters. The call shape changed — types now go on `.query()`, not
+the old callable:
+
+```typescript
+import type { GetAccountsQuery, GetAccountsQueryVariables } from "../graphql-operations-types";
+
+const result = await sdk.graphql!.query<GetAccountsQuery, GetAccountsQueryVariables>({
+  query: GET_ACCOUNTS,
+  variables,
+});
+```
+
+`NodeOfConnection<T>` extracts a node type from a Connection for cleaner typing:
+
+```typescript
+import { type NodeOfConnection } from "@salesforce/platform-sdk";
+type AccountNode = NodeOfConnection<GetAccountsQuery["uiapi"]["query"]["Account"]>;
+```

package/skills/experience-ui-bundle-salesforce-data-access/scripts/graphql-search.sh

@@ -2,13 +2,20 @@
 set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipeline failures (-o pipefail)
 # graphql-search.sh — Look up one or more Salesforce entities in schema.graphql.
 #
-# Run from the SFDX project root (where schema.graphql lives):
-#   bash scripts/graphql-search.sh Account
-#   bash scripts/graphql-search.sh Account Contact Opportunity
+# Run from the SFDX project root, where schema.graphql lives:
+#   bash <skill-dir>/scripts/graphql-search.sh Account
+#   bash <skill-dir>/scripts/graphql-search.sh Account Contact Opportunity
 #
-# Pass a custom schema path with -s / --schema:
-#   bash scripts/graphql-search.sh -s /path/to/schema.graphql Account
-#   bash scripts/graphql-search.sh --schema ./other/schema.graphql Account Contact
+# The script does NOT search up the directory tree — an ancestor schema.graphql
+# may belong to a DIFFERENT org, and silently matching it would validate fields
+# against the wrong schema. If schema.graphql is not at ./ you must point the
+# script at the right file explicitly (resolution order, first hit wins):
+#   1. -s / --schema <path>      explicit flag
+#   2. $GRAPHQL_SCHEMA env var   explicit override
+#   3. ./schema.graphql          (current working directory only)
+#
+#   bash <skill-dir>/scripts/graphql-search.sh -s force-app/main/default/uiBundles/<app>/schema.graphql Account
+#   GRAPHQL_SCHEMA=/abs/path/schema.graphql bash <skill-dir>/scripts/graphql-search.sh Account
 #
 # Output sections per entity:
 #   1. Type definition          — all fields and relationships
@@ -19,7 +26,7 @@ set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipe
 #   6. Update mutation wrapper  — <Entity>UpdateInput
 #   7. Update mutation fields   — <Entity>UpdateRepresentation (for update mutations)
 
-SCHEMA="./schema.graphql"
+SCHEMA=""
 
 # ── Argument parsing ─────────────────────────────────────────────────────────
 
@@ -56,10 +63,26 @@ if [ $# -eq 0 ]; then
   exit 1
 fi
 
+# ── Schema resolution ────────────────────────────────────────────────────────
+# NO directory walk-up: resolve only from an explicit flag, an explicit env var,
+# or schema.graphql in the CURRENT directory. Searching ancestors risks matching
+# an unrelated project's schema and validating fields against the wrong org.
+# Resolution order (first hit wins): -s/--schema, then $GRAPHQL_SCHEMA, then ./schema.graphql.
+
+if [ -z "$SCHEMA" ] && [ -n "${GRAPHQL_SCHEMA-}" ]; then
+  SCHEMA="$GRAPHQL_SCHEMA"
+fi
+
+if [ -z "$SCHEMA" ]; then
+  SCHEMA="./schema.graphql"
+fi
+
 if [ ! -f "$SCHEMA" ]; then
-  echo "ERROR: schema.graphql not found at $SCHEMA"
-  echo "  Make sure you are running from the SFDX project root, or pass the path explicitly:"
+  echo "ERROR: schema.graphql not found at '$SCHEMA'."
+  echo "  This script does NOT search parent directories (an ancestor schema may be the wrong org's)."
+  echo "  Run from the SFDX project root where schema.graphql lives, or point at it explicitly:"
   echo "    bash $0 --schema <path/to/schema.graphql> <EntityName>"
+  echo "    GRAPHQL_SCHEMA=<path/to/schema.graphql> bash $0 <EntityName>"
   echo "  If the file is missing entirely, generate it from the UI bundle dir:"
   echo "    cd force-app/main/default/uiBundles/<app-name> && npm run graphql:schema"
   exit 1
@@ -78,6 +101,10 @@ if [ ! -s "$SCHEMA" ]; then
   exit 1
 fi
 
+# Announce the resolved schema so a wrong-file match is visible, not silent.
+# stderr keeps it out of the parsed lookup output on stdout.
+echo "[graphql-search] using schema: $SCHEMA" >&2
+
 # ── Helper: extract lines from a grep match through the closing brace ────────
 # Prints up to MAX_LINES lines after (and including) the first match of PATTERN.
 # Uses a generous line count — blocks are always closed by a "}" line.

package/skills/platform-agentsetup-categories-fetch/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: platform-agentsetup-categories-fetch
+description: "Fetch agentic setup prompt categories from a connected Salesforce org using the Connect API. Use this skill to call GET /agenticsetup/categories and return the list of prompt categories, optionally with their nested prompts. TRIGGER when: user asks to get, fetch, list, or show agentic setup categories, prompt categories, setup copilot categories, prompt library categories, available setup prompts, Agentforce prompt library, or copilot prompts. DO NOT TRIGGER when: user wants to create new categories, work with non-categories endpoints, or generate OpenAPI specs."
+allowed-tools: Bash Read
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# platform-agentsetup-categories-fetch
+
+Fetch prompt categories from the Agentic Setup Categories Connect API on a connected Salesforce org.
+
+## Scope
+
+**In scope:**
+- Calling `GET /services/data/{apiVersion}/agenticsetup/categories` via SF CLI
+- Passing the `fetchPrompts` query parameter to include nested prompts
+- Parsing and presenting the JSON response (categories, labels, prompts)
+- Handling errors (403 when feature is disabled, auth failures)
+
+**Out of scope — delegate elsewhere:**
+- Creating or modifying prompt categories → not supported via this API (read-only)
+- Org authentication setup → use `sf org login` separately
+- Permission set assignment → assigning-permission-set
+
+---
+
+## Required Inputs
+
+The agent needs:
+- A connected org (already authenticated via `sf org login`)
+- Optionally: whether to include nested prompts (`fetchPrompts=true`)
+- Optionally: target API version (default: v67.0). Replace `v67.0` in the URL with the user-specified version if provided.
+
+---
+
+## Workflow
+
+### 1. Verify org connectivity
+
+```bash
+sf org display --json
+```
+
+Confirm the org is authenticated and extract the instance URL. If no default org is set, ask the user which org to target with `--target-org`.
+
+### 2. Call the Categories API
+
+**Basic call (categories only):**
+```bash
+sf api request rest /services/data/v67.0/agenticsetup/categories --method GET
+```
+
+**With nested prompts:**
+```bash
+sf api request rest "/services/data/v67.0/agenticsetup/categories?fetchPrompts=true" --method GET
+```
+
+### 3. Parse and present the response
+
+The API returns a JSON object with a `categories` array. Each category has `name`, `label`, and `prompts` fields. See `references/api-response-schema.md` for the full response structure and examples for both `fetchPrompts=true` and `fetchPrompts=false`.
+
+Present the results clearly:
+- List categories with their name and label
+- If `fetchPrompts=true` was used, show nested prompts under each category
+- Note any categories with empty `prompts` arrays (means no prompts exist for that category)
+
+### 4. Handle errors
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| Success (exit 0) | 200 OK | Parse and display results |
+| `FUNCTIONALITY_NOT_ENABLED` | Feature not enabled for this org/user | Tell user the Agentic Setup Categories feature needs to be enabled — check Setup > Einstein/Agentforce |
+| `INVALID_SESSION_ID` | Session expired | Re-authenticate with `sf org login` |
+| `NOT_FOUND` | Endpoint not found | API version too old or feature not deployed to this org |
+
+---
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|------|-----------|
+| Always use `sf api request rest` — never curl or raw HTTP | curl bypasses `~/.sfdx` session tokens and requires manual Authorization headers, making it brittle |
+| NEVER use SOQL queries | Categories are NOT in standard objects — only available via this Connect REST API |
+| NEVER generate files (LWC, Apex, XML) | This is a data-fetching task, not a code generation task |
+| Default to v67.0 unless user specifies | This is the min-version where the endpoint was introduced |
+| Don't pass fetchPrompts unless asked | Reduces payload size; prompts can be large |
+| Categories are sorted by label | The API returns them alphabetically — don't re-sort |
+| Prompts are sorted by text | Within each category, prompts come alphabetically |
+
+---
+
+## Output Expectations
+
+When finishing, present:
+
+1. **Number of categories** returned
+2. **Category list** — name and label for each
+3. **Prompts** (if requested) — nested under their category
+4. **Any errors** encountered with suggested fixes
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/api-response-schema.md` | When you need to understand the full response structure and field descriptions |

package/skills/platform-agentsetup-categories-fetch/references/api-response-schema.md

@@ -0,0 +1,121 @@
+# Agentic Setup Categories API Response Schema
+
+## Endpoint
+
+```text
+GET /services/data/v67.0/agenticsetup/categories
+GET /services/data/v67.0/agenticsetup/categories?fetchPrompts=true
+```
+
+## Response Structure
+
+### PromptCategoryListRepresentation
+
+Top-level response object.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `categories` | array of PromptCategoryRepresentation | Categories sorted alphabetically by localized label |
+
+### PromptCategoryRepresentation
+
+A single prompt category.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Stable programmatic identifier (e.g., "UserManagement") |
+| `label` | string | Localized display label (e.g., "User Management") |
+| `prompts` | array of PromptRepresentation | Populated when `fetchPrompts=true`; empty array otherwise |
+
+### PromptRepresentation
+
+A single prompt entry within a category.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | string | User-facing prompt text to display and pass to the LLM |
+| `description` | string | Short helper description shown next to the prompt |
+
+## Example Response (fetchPrompts=false)
+
+```json
+{
+  "categories": [
+    {
+      "label": "Flow Management",
+      "name": "FlowManagement",
+      "prompts": []
+    },
+    {
+      "label": "Identity",
+      "name": "Identity",
+      "prompts": []
+    },
+    {
+      "label": "User Management",
+      "name": "UserManagement",
+      "prompts": []
+    }
+  ]
+}
+```
+
+## Example Response (fetchPrompts=true)
+
+```json
+{
+  "categories": [
+    {
+      "label": "Flow Management",
+      "name": "FlowManagement",
+      "prompts": [
+        {
+          "description": "Scaffold a new flow",
+          "text": "Design a flow that [describe trigger and outcome]."
+        },
+        {
+          "description": "List active flows",
+          "text": "List all active flows in this org. Include the object, trigger type, and last modified date for each."
+        }
+      ]
+    },
+    {
+      "label": "User Management",
+      "name": "UserManagement",
+      "prompts": [
+        {
+          "description": "Activate a user",
+          "text": "Activate user [user]. Confirm what becomes accessible to them again and whether their license is still available."
+        },
+        {
+          "description": "Clone a user",
+          "text": "Clone [existing user] to create a new user for [new person's name and email]."
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Error Responses
+
+### FUNCTIONALITY_NOT_ENABLED
+
+Returned when the Agentic Setup Categories feature is not enabled on the org.
+
+```json
+[
+  {
+    "message": "This feature is not currently enabled for this user type or org: [AgenticSetupCategoriesApiFamily]",
+    "errorCode": "FUNCTIONALITY_NOT_ENABLED"
+  }
+]
+```
+
+### Access Requirements
+
+The endpoint uses a two-tier security model:
+1. **Org-level**: `SetupCopilot.orgHasEnhancedAgenticSetup` must be true
+2. **User-level**: `SetupCopilot.orgHasSetupHomePromptLibrary` must be true per request
+
+If either check fails, the API returns `FUNCTIONALITY_NOT_ENABLED`.

package/skills/platform-custom-object-generate/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: platform-custom-object-generate
-description: "Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like \"create a custom object\", \"generate object metadata\", \"set up an object for...\", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work."
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like \"create a custom object\", \"generate object metadata\", \"set up an object for...\", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work, including enriching and keeping the object's description current whenever its fields or validation rules change. Do NOT use this skill for non-Custom-Object metadata (Apex, Flows, LWC, Permission Sets, Custom Metadata Types) or for standard Salesforce objects."
 metadata:
-  version: "1.0"
+  version: "1.1"
+  minApiVersion: "60.0"
 ---
 
 ## When to Use This Skill
@@ -13,6 +14,7 @@ Use this skill when you need to:
 - Configure object sharing and security settings
 - Set up object features and capabilities
 - Troubleshoot deployment errors related to custom objects
+- **Add, update, or delete a field OR a validation rule on an existing object** — any of these may make the object's `<description>` stale, so you must refresh it (propose + confirm). This applies equally to validation-rule changes, not just fields. See Section 3.B.
 
 ## Specification
 
@@ -22,6 +24,8 @@ This document defines the mandatory constraints for generating CustomObject meta
 
 **File extension:** `.object-meta.xml`
 
+> **🔔 Description freshness — applies to EVERY object change, fields AND validation rules:** Whenever you add, update, or delete a field **or a validation rule** on an object, the `<description>` may now be stale. Before finishing, refresh it per **Section 3.B** (propose, confirm with the user, write). A validation-rule change counts exactly like a field change — the change is **not** done until the description has been reconciled. This is easy to forget on validation-rule edits/deletes — don't.
+
 ---
 
 ## 2. Syntactic Essentials (Tier 1)
@@ -103,12 +107,47 @@ The agent must choose which features to enable based on the object's intended us
 </nameField>
 ```
 
-### B. Object Description
+### B. Object Description (Enrichment)
+
+**`<description>`**: **Mandatory** — every Custom Object MUST have one. It must read like human-written documentation, **never** a generic template ("Object used to track and manage...") or a metadata dump ("Contains 8 fields including `Project_Name__c`...").
+
+**Always compose an enriched description** — when creating the object, and again on **any** change to it: adding, updating, or deleting a field **or a validation rule** (so it never goes stale). The change — field or validation rule — is never "done" until you've refreshed the object's description. This is not optional; do not ask *whether* to add a description.
+
+**Confirm per change — every time.** Propose and confirm on **each** field/rule change separately. A previous "keep current" applies **only** to that one change; it is **never** standing permission to skip the proposal on a later change. Do not infer a preference from an earlier answer — re-propose and re-ask for every new change.
+
+**Compose** the description (steps below). If the object already has one, use it as a **strong signal** — preserve the business context it carries (domain, team, intent the schema can't reveal) and fold the new field/rule in rather than discarding it.
+
+Then branch on whether a description already exists:
+
+- **No existing description (brand-new object):** there is nothing to overwrite — just write the composed description. **Do not prompt.**
+- **An existing description (update, delete, or any re-enrichment):** never overwrite it silently — you can't tell from the file whether it was hand-written by an admin or generated earlier. Show the proposal, ask, and **STOP — wait for the user's reply before writing:**
+   > Proposed description for `{Object}`:
+   > `<the enriched description>`
+   > Current: `<the existing description>`
+   > Use this? (yes / keep current / edit)
+
+  **You MUST NOT write the `<description>` until the user replies** — showing the diff is not approval, even when the change looks obvious or minor. Then act: *yes* → write the proposed text · *keep current* → leave the existing one untouched (this applies to **this change only** — re-propose on the next one) · *edit* → use the user's wording.
+
+Always end with a `<description>` written.
+
+**Composing the description:**
 
-**`<description>`**: Mandatory. Every object must contain a professional summary.
+1. **Classify each field** by how it appears in the description:
+   - **Constrained** (required, unique, externalId, restricted picklist) → selective parenthetical: `VIN (required, external ID)`, `Color (Red/Green only)`
+   - **Behavioral** (formula, roll-up) → describe what it computes: "the Age Years field auto-calculates vehicle age"
+   - **Relationship** (master-detail, lookup) → woven context: "as a child of Account" (never "(Master-Detail to Account)")
+   - **Standard** → label only
+2. **Compose** in this order, using field **labels not API names**:
+   > Purpose → key fields → computed fields → validation rules (as business rules) → "Commonly used for {use cases}."
+3. **Count and trim before writing (required):** count the words; aim ~45, hard ceiling 50. If over, tighten wording first, then drop whole sentences in priority order (use cases → rules → computed; never drop sentences 1–2). Recount. Do not write until ≤ 50.
+
+**Example (Car, 46 words):**
+```xml
+<description>The Car object tracks vehicle inventory and maintenance. It captures Year, VIN (required, external ID), Color (Red/Green only), and Location; the Age Years field auto-calculates vehicle age. VIN is required and Black cars cannot be sold. Commonly used for fleet management, inventory tracking, and service scheduling.</description>
+```
+
+→ For the full workflow and examples, read **`references/description-enrichment.md`**.
 
-If the intent is vague, generate a summary:
-> "Object used to track and manage [Intent] within the organization."
 ### C. Junction Object Naming
 
 If the object is a many-to-many link between two parents, name the object by combining the two parent entities to ensure the schema remains intuitive.
@@ -234,7 +273,23 @@ Before generating the Custom Object XML, verify:
 - [ ] Do validation rule names NOT end with `__c`?
 - [ ] Do validation rule names follow alphanumeric + underscore pattern?
 
+### Description Enrichment Quality Checks
+- [ ] Opens with "The {Object} object..." + business purpose (not "Object used to track and manage...")
+- [ ] Uses field **labels**, never API names; no "Contains N fields including" dump
+- [ ] Formulas/rollups described by behavior; validations stated as business rules; relationships as context
+- [ ] Includes common use cases ("Commonly used for...") and is **under 50 words**
+- [ ] Folded any current description's business context into the proposed one (didn't discard it)
+- [ ] For an existing description (update/delete/re-enrich), STOPPED and waited for the user's reply before writing — did not treat showing the diff as approval
+
 ### Architectural Checks
-- [ ] Is `<description>` present with a meaningful summary?
+- [ ] Is `<description>` present? (Enriched per Section B — proposed and confirmed with the user before writing.)
 - [ ] Are `<enableSearch>` and `<enableReports>` set to `true` if user-facing?
 - [ ] Does the filename match the intended API name?
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/description-enrichment.md` | Composing or refreshing an object's `<description>` (on create, or when a field/rule changes) — full enrichment workflow, field-prioritization tiers, junction/child handling, edge cases, and more examples |