@salesforce/afv-skills 1.30.0 → 1.31.0

package/skills/experience-ui-bundle-app-coordinate/scripts/check-hosting-target.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Check which hosting target is configured in .uibundle-meta.xml files
+
+# Find all .uibundle-meta.xml files
+META_FILES=$(find . -name "*.uibundle-meta.xml" -type f 2>/dev/null)
+
+if [ -z "$META_FILES" ]; then
+  echo "ERROR: No .uibundle-meta.xml files found"
+  exit 1
+fi
+
+# Check for ExperienceSite target
+if echo "$META_FILES" | xargs grep -q '<target>ExperienceSite</target>' 2>/dev/null; then
+  echo "ExperienceSite"
+  exit 0
+fi
+
+# Check for CustomApplication target
+if echo "$META_FILES" | xargs grep -q '<target>CustomApplication</target>' 2>/dev/null; then
+  echo "CustomApplication"
+  exit 0
+fi
+
+# No valid target found
+echo "ERROR: No valid hosting target found in .uibundle-meta.xml"
+exit 1

package/skills/experience-ui-bundle-app-coordinate/scripts/check-sfdx-project.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Check if sfdx-project.json exists and is valid JSON
+
+if [ ! -f sfdx-project.json ]; then
+  echo 'ERROR: sfdx-project.json not found'
+  exit 1
+fi
+
+# Validate JSON format using python (more portable than node)
+if ! python3 -c "import json; json.load(open('sfdx-project.json'))" 2>/dev/null; then
+  echo 'ERROR: sfdx-project.json is not valid JSON'
+  exit 1
+fi
+
+echo 'sfdx-project.json is valid'

package/skills/experience-ui-bundle-metadata-generate/SKILL.md

@@ -1,8 +1,18 @@
 ---
 name: experience-ui-bundle-metadata-generate
-description: "MUST activate when the project contains a uiBundles/*/src/ directory and scaffolding a new UI bundle or app, or when editing ui-bundle.json, .uibundle-meta.xml, or CSP trusted site files. Use this skill when scaffolding with sf template generate ui-bundle, configuring ui-bundle.json (routing, headers, outputDir), or registering CSP Trusted Sites. Activate when the task involves files matching *.uibundle-meta.xml, ui-bundle.json, or cspTrustedSites/*.cspTrustedSite-meta.xml."
+description: "Use this skill when adding a front-end React UI bundle to an existing project or configuring UI bundle metadata and config files. TRIGGER when: adding or scaffolding a new UI bundle inside a project that already exists; running sf template generate ui-bundle; editing ui-bundle.json routing, headers, or output directory; working with *.uibundle-meta.xml files; or registering CSP Trusted Sites, resolving blocked images or fonts or external API calls, or editing cspTrustedSites/*.cspTrustedSite-meta.xml files. DO NOT TRIGGER when: creating a brand-new Salesforce project from scratch, where the whole SFDX starter project (UI bundle plus Experience Site metadata and toolchain) is generated together (use experience-ui-bundle-project-generate)."
 metadata:
   version: "1.0"
+  minApiVersion: "51.0"
+  relatedSkills:
+    - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-custom-app-generate"
+    - "experience-ui-bundle-site-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6"
 ---
 
 # UI Bundle Metadata
@@ -11,9 +21,9 @@ metadata:
 
 Use `sf template generate ui-bundle` to create new apps — not create-react-app, Vite, or other generic scaffolds.
 
-**Always pass `--template reactbasic`** to scaffold a React-based bundle.
-
-**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+- **Always pass `--template reactbasic`** to scaffold a React-based bundle.
+- **UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+- Pass `--output-dir` to use a different location for template generation.
 
 **Example:**
 ```bash
@@ -21,10 +31,11 @@ sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
 ```
 
 After generation:
-1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
-2. Populate the home page with real content (landing section, banners, hero, navigation)
-3. Update navigation and placeholders (see the `experience-ui-bundle-frontend-generate` skill)
-4. **Configure a hosting target** — a UI bundle without a `<target>` in its meta XML will not be visible in the org. Use `experience-ui-bundle-custom-app-generate` for internal (App Launcher) apps or `experience-ui-bundle-site-generate` for external (Experience Site) apps.
+1. **Verify API version** — run `bash <skill_dir>/scripts/check-api-version.sh` from the project root to ensure `sourceApiVersion` in `sfdx-project.json` is 67.0 or higher. The script will automatically update it if needed.
+2. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
+3. Populate the home page with real content (landing section, banners, hero, navigation)
+4. Update navigation and placeholders (see the `experience-ui-bundle-frontend-generate` skill)
+5. **Configure a hosting target** — a UI bundle without a `<target>` in its meta XML will not be visible in the org. Use `experience-ui-bundle-custom-app-generate` for internal (App Launcher) apps or `experience-ui-bundle-site-generate` for external (Experience Site) apps.
 
 Always install dependencies before running any scripts in the UI bundle directory.
 

package/skills/experience-ui-bundle-metadata-generate/references/csp-metadata-format.md

@@ -2,7 +2,7 @@
 
 ## File location
 
-```
+```text
 force-app/main/default/cspTrustedSites/{Name}.cspTrustedSite-meta.xml
 ```
 
@@ -256,7 +256,7 @@ Some services split resources across multiple subdomains. Create one CSP Trusted
 
 If the browser console shows a CSP error like:
 
-```
+```text
 Refused to load the image 'https://example.com/image.png' because it violates
 the following Content Security Policy directive: "img-src 'self' ..."
 ```

package/skills/experience-ui-bundle-metadata-generate/scripts/check-api-version.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Checks that sourceApiVersion in sfdx-project.json is 67.0 or higher.
+# If lower, updates it to "67.0".
+
+set -e
+
+PROJECT_FILE="sfdx-project.json"
+
+if [[ ! -f "$PROJECT_FILE" ]]; then
+  echo "ERROR: $PROJECT_FILE not found in current directory"
+  exit 1
+fi
+
+# Extract sourceApiVersion and check if it's below 67.0
+version=$(jq -r '.sourceApiVersion // "0"' "$PROJECT_FILE")
+is_below=$(jq --arg v "$version" -n '($v | split(".") | .[0] | tonumber) < 67')
+
+if [[ "$is_below" == "true" ]]; then
+  echo "WARNING: sourceApiVersion is $version (< 67.0)"
+  echo "Updating $PROJECT_FILE to set sourceApiVersion to \"67.0\""
+
+  # Update the file
+  jq '.sourceApiVersion = "67.0"' "$PROJECT_FILE" > "$PROJECT_FILE.tmp"
+  mv "$PROJECT_FILE.tmp" "$PROJECT_FILE"
+
+  echo "OK: Updated sourceApiVersion to 67.0"
+  exit 0
+fi
+
+echo "OK: sourceApiVersion is $version (>= 67.0)"

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

@@ -4,6 +4,7 @@ description: "Use this skill when users need to create, generate, or validate Sa
 metadata:
   version: "1.0"
   minApiVersion: "51.0"
+  relatedSkills: ["platform-value-set-generate", "platform-validation-rule-generate"]
 ---
 
 # Salesforce Custom Field Generator and Validator
@@ -20,7 +21,7 @@ Every generated field must include these tags:
 
 | Attribute | Requirement | Notes |
 |-----------|-------------|-------|
-| `<fullName>` | Required | **Field** name only: derive from `<label>` — capitalize each word, replace spaces with `_`, append `__c`. Must start with a letter. E.g., label `Total Contract Value` → `Total_Contract_Value__c`. ⚠️ This rule is for the FIELD name. **Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c`** (e.g. `Closed Won`, NOT `Closed_Won`). See [`references/advanced-picklists.md`](references/advanced-picklists.md) (ref §3). |
+| `<fullName>` | Required | **Field** name only: derive from `<label>` — capitalize each word, replace spaces with `_`, append `__c`. Must start with a letter. E.g., label `Total Contract Value` → `Total_Contract_Value__c`. This rule is for the FIELD name. **Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c`** (e.g. `Closed Won`, NOT `Closed_Won`). See [`references/advanced-picklists.md`](references/advanced-picklists.md) (ref §3). |
 | `<label>` | Required | The UI name (Title Case) |
 | `<description>` | Always include | Explain the business reason *why* this field exists. |
 | `<inlineHelpText>` | Always include | Actionable end-user guidance that adds value beyond the label (e.g., "Enter the value in USD including tax", not "The amount"). |
@@ -49,7 +50,7 @@ To ensure deployment success, follow these mathematical constraints:
 
 ### The "Fixed 255" Rule
 
-**TextArea: always include `<length>255</length>` exactly** — this literal value is required by the Metadata API and **omitting it fails deployment**, even though the UI exposes no length control. Unlike every other type where `length` is a value you calculate, TextArea's is a fixed constant.
+**TextArea: do NOT include `<length>`** — the Metadata API fixes the length at 255 implicitly and **rejects an explicit `<length>` value** with "Can not specify 'length' for a CustomField of type TextArea". Omit `<length>` entirely; the field only needs `<fullName>`, `<label>`, and `<type>TextArea</type>`.
 
 ### Visible Lines
 
@@ -76,7 +77,7 @@ Mandatory for Long/Rich text and Multi-select picklists to control UI height.
 | Phone | `Phone` | Standardizes phone number formatting |
 | Picklist | `Picklist` | `valueSet` containing EITHER `valueSetDefinition` (inline) OR `valueSetName` (reference); `restricted` (see "Picklist `restricted` default" below; advanced cases in §3.4) |
 | Text | `Text` | `length` (Max 255) |
-| Text Area | `TextArea` | `<length>255</length>` |
+| Text Area | `TextArea` | None — do NOT include `<length>`; the API fixes length at 255 implicitly |
 | Text (Long) | `LongTextArea` | `length`, `visibleLines` (default 3) |
 | Text (Rich) | `Html` | `length`, `visibleLines` (default 25) |
 | Time | `Time` | Stores time only (no date) |
@@ -112,7 +113,7 @@ Mandatory for Long/Rich text and Multi-select picklists to control UI height.
 
 ### 3.4 Advanced Picklists
 
-The inline `<valueSetDefinition>` above is the simple case. Full rules and worked ✅/❌
+The inline `<valueSetDefinition>` above is the simple case. Full rules and worked correct/incorrect
 examples for everything below are in
 [`references/advanced-picklists.md`](references/advanced-picklists.md) — load it for any
 non-trivial picklist. Section numbers in parentheses below (e.g. "ref §1") point to that
@@ -166,12 +167,12 @@ Master-Detail fields have **strict attribute restrictions** that differ from Loo
 
 | Attribute | Master-Detail | Lookup |
 |-----------|---------------|--------|
-| `<required>` | ❌ FORBIDDEN | ✅ Optional |
-| `<deleteConstraint>` | ❌ FORBIDDEN (always CASCADE) | ✅ Required (`SetNull`, `Restrict`, `Cascade`) |
-| `<lookupFilter>` | ❌ FORBIDDEN | ✅ Optional |
-| `<relationshipOrder>` | ✅ Required (0 or 1) | ❌ Not applicable |
-| `<reparentableMasterDetail>` | ✅ Optional | ❌ Not applicable |
-| `<writeRequiresMasterRead>` | ✅ Optional | ❌ Not applicable |
+| `<required>` | FORBIDDEN | Optional |
+| `<deleteConstraint>` | FORBIDDEN (always CASCADE) | Required (`SetNull`, `Restrict`, `Cascade`) |
+| `<lookupFilter>` | FORBIDDEN | Optional |
+| `<relationshipOrder>` | Required (0 or 1) | Not applicable |
+| `<reparentableMasterDetail>` | Optional | Not applicable |
+| `<writeRequiresMasterRead>` | Optional | Not applicable |
 
 ### INCORRECT — Master-Detail with forbidden attributes:
 
@@ -451,7 +452,7 @@ Before generating CustomField XML, verify:
 - [ ] Is `precision ≤ 18`?
 
 ### Text Area Checks
-- [ ] For TextArea: Is `<length>255</length>` explicitly included?
+- [ ] For TextArea: Is `<length>` **omitted**? (The API rejects an explicit `<length>` value on TextArea fields.)
 - [ ] For LongTextArea/Html: Is `<visibleLines>` set?
 
 ### Relationship Limit Checks

package/skills/platform-custom-field-generate/references/advanced-picklists.md

@@ -21,7 +21,7 @@ A picklist field can either define its values **inline** or **reference an exist
 value set** (a Global Value Set or a Standard Value Set). The shared set is defined
 once and reused across many fields.
 
-### ⭐ HARD RULE: `<valueSet>` is EITHER a reference OR inline — never both
+### HARD RULE: `<valueSet>` is EITHER a reference OR inline — never both
 
 A `<valueSet>` element must contain **exactly one** of:
 
@@ -30,7 +30,7 @@ A `<valueSet>` element must contain **exactly one** of:
 
 Including both in the same `<valueSet>` is a deployment error.
 
-#### ❌ INCORRECT — both reference and inline definition:
+#### INCORRECT — both reference and inline definition:
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -54,7 +54,7 @@ Including both in the same `<valueSet>` is a deployment error.
 
 **Error:** `Value set must reference a value set name or define a value set, but not both.`
 
-#### ✅ CORRECT — reference a Global Value Set:
+#### CORRECT — reference a Global Value Set:
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -88,7 +88,7 @@ the name you put inside it differs.
 > local project" warning) is expected org-storage display — keep local metadata on the bare name.
 > Never append `__c` to a value-set name either.
 
-#### ✅ CORRECT — reference a Standard Value Set (bare name, no suffix):
+#### CORRECT — reference a Standard Value Set (bare name, no suffix):
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -126,7 +126,7 @@ A **dependent** picklist filters its available values based on the selected valu
 **dependent** field via a `<controllingField>` element plus one `<valueSettings>` block
 per (controlling value → dependent value) pair.
 
-### ⭐ Use the MODERN API 38.0+ form ONLY
+### Use the MODERN API 38.0+ form ONLY
 
 | Form | Elements | Status |
 |------|----------|--------|
@@ -136,7 +136,7 @@ per (controlling value → dependent value) pair.
 Never emit the legacy `<picklist>`, `<picklistValues>`, or `<controllingFieldValues>`
 tags. They are not valid against the modern Metadata API and will fail deployment.
 
-### ⭐ HARD RULE: both the controlling and dependent field must be `<restricted>true</restricted>`
+### HARD RULE: both the controlling and dependent field must be `<restricted>true</restricted>`
 
 A field dependency requires a fixed, admin-defined value set on **both** ends. **Always emit
 `<restricted>true</restricted>` inside the `<valueSet>` of the controlling field AND the
@@ -186,7 +186,7 @@ Inside the dependent field's `<valueSet>`, in this order:
 > EMEA→UK,Germany) you emit **one block for each (controllingValue, dependentValue) pair** — four
 > pairs = four `<valueSettings>` blocks. And remember: both fields carry `<restricted>true</restricted>`.
 
-### ✅ CORRECT — State dependent on Country (USA → California, Texas)
+### CORRECT — State dependent on Country (USA → California, Texas)
 
 **Controlling field — `Country__c` (a plain restricted picklist):**
 
@@ -258,7 +258,7 @@ Inside the dependent field's `<valueSet>`, in this order:
 > `<valueSettings>` block with that country's `<controllingFieldValue>` and
 > `<valueName>California</valueName>`.
 
-### ❌ INCORRECT — deprecated legacy form:
+### INCORRECT — deprecated legacy form:
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -282,7 +282,7 @@ legacy dependency elements are not valid in the modern `<valueSet>` structure.
 
 ## 3. Enhanced Value Attributes
 
-### ⭐ Value-name fidelity — do NOT underscore picklist value names
+### Value-name fidelity — do NOT underscore picklist value names
 
 A **picklist value's `<fullName>` is NOT a field API name** and must NOT be transformed.
 Use the value text **exactly as the user spelled it**, spaces and all. A value the user
@@ -315,7 +315,7 @@ Inline `<value>` entries (CustomValue subfields) support more than `<fullName>`,
 
 These are independent of `<default>` and `<label>` and may be combined freely.
 
-### ✅ CORRECT — Status picklist with colors and an inactive value
+### CORRECT — Status picklist with colors and an inactive value
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -367,7 +367,7 @@ The Metadata API rejects malformed picklist values at deploy time. Two common fa
 Two `<value>` entries with the same `<fullName>` inside one `<valueSetDefinition>` are
 rejected.
 
-#### ❌ INCORRECT — duplicate value:
+#### INCORRECT — duplicate value:
 
 ```xml
 <valueSetDefinition>
@@ -398,7 +398,7 @@ The stricter "only alphanumerics and single underscores, no leading digit, no do
 or trailing underscore" rule applies to the *field* `<fullName>` (the `__c`-suffixed
 API name), not to picklist value fullNames.
 
-#### ❌ INCORRECT — invalid value API name:
+#### INCORRECT — invalid value API name:
 
 ```xml
 <value>
@@ -410,7 +410,7 @@ API name), not to picklist value fullNames.
 
 **Error:** `Invalid fullName: must begin with a letter and use only alphanumeric characters and underscores`
 
-#### ✅ CORRECT:
+#### CORRECT:
 
 ```xml
 <value>
@@ -454,7 +454,7 @@ include a `<fullName>`** element — the record type's developer name (e.g. `<fu
 matching the filename `Internal.recordType-meta.xml`. It's bare (no object prefix); the object
 comes from the `objects/<Object>/` folder path.
 
-### ⭐ STEP 1 — Decide if this object needs a BusinessProcess (do this BEFORE writing files)
+### STEP 1 — Decide if this object needs a BusinessProcess (do this BEFORE writing files)
 
 A record type on a **BusinessProcess-gated object — Opportunity, Lead, Case, or Solution —
 will NOT deploy without a `<businessProcess>` reference**, even when it only filters a *custom*
@@ -472,7 +472,7 @@ developer name instead of generating a new one (confirm via the grounding MCP's
 if available; otherwise generate a minimal one). For everything else, **do not invent a
 BusinessProcess** — adding one to a custom-object record type is wrong.
 
-#### ✅ CORRECT — Opportunity "Enterprise" record type, two deployable files
+#### CORRECT — Opportunity "Enterprise" record type, two deployable files
 
 ```xml
 <!-- File 1: objects/Opportunity/businessProcesses/Enterprise_Sales_Process.businessProcess-meta.xml -->
@@ -519,7 +519,7 @@ BusinessProcess** — adding one to a custom-object record type is wrong.
 </RecordType>
 ```
 
-#### ❌ INCORRECT — BusinessProcess file emitted but NOT referenced (most common failure)
+#### INCORRECT — BusinessProcess file emitted but NOT referenced (most common failure)
 
 ```xml
 <!-- File 1 (businessProcesses/Enterprise_Sales_Process...) was generated correctly, BUT -->
@@ -571,7 +571,7 @@ RecordType   (filters the field's values; references the BusinessProcess)
 - For Opportunity/Lead/Case/Solution, the `<businessProcess>` must exist (same package or
   already in the org) before the RecordType.
 
-### ⭐ UI-sync gotcha — values may not auto-display after API deploy
+### UI-sync gotcha — values may not auto-display after API deploy
 
 When `<picklistValues>` are loaded via the Metadata API, the values are correctly associated
 under the hood, **but they may not automatically appear as "Selected Values" in the Record

package/skills/platform-custom-report-type-generate/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: platform-custom-report-type-generate
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Report Type metadata. Trigger when users mention custom report types, report types, CRTs, reporting frameworks, cross-object reports, report builder data sources, or ask to expose fields for reporting across related objects. Also use when users mention primary and related objects for reports, inner vs outer joins in reports, report type categories, or encounter deployment errors for .reportType-meta.xml files. Do NOT trigger for: running, editing, or filtering existing reports; creating report folders, dashboards, or list views; or general reporting questions that don't involve authoring a .reportType-meta.xml file."
+metadata:
+  version: "1.0"
+  minApiVersion: "51.0"
+---
+
+## Specification
+
+# Salesforce Custom Report Type Metadata Knowledge
+
+## Overview
+Custom Report Types (CRTs) define the **data framework** for Salesforce reports. They specify a primary object, up to 3 related objects, the relationship (join) between them, and which fields are available in the report builder.
+
+## Purpose
+- Enable reporting across custom objects and custom relationships not covered by standard report types
+- Curate a focused set of fields for report builders (including fields reached via lookup)
+- Control inner/outer join behavior to include or exclude primary records without related records
+
+## Configuration
+
+**File extension:** `.reportType-meta.xml`. The file basename is the report type's developer name (e.g. `AccountsWithProjects.reportType-meta.xml`). Each CRT is a single file, not nested under an object folder.
+
+### Key Elements
+
+Top-level `<ReportType>` children:
+
+| Element | Required | Notes |
+|---------|----------|-------|
+| `<fullName>` | Yes | API identifier; must match the file name. Letters, numbers, underscores; must begin with a letter; no spaces; no trailing underscore; no consecutive underscores |
+| `<label>` | Yes | Human-friendly name shown in the report type picker |
+| `<description>` | Recommended | State the business "why" — who uses this and what they learn |
+| `<baseObject>` | Yes | API name of the primary object (e.g. `Account`, `Project__c`). Cannot be changed after initial creation. All objects, including custom and external, are supported (external objects from API 38.0+) |
+| `<category>` | Recommended | Report builder category — see `references/category-values.md` |
+| `<deployed>` | Yes | `true` to expose to users; `false` while building/iterating |
+| `<join>` | Conditional | Adds a related object and its join behavior. Nest further `<join>` blocks for deeper relationships |
+| `<sections>` | Recommended | Groups of columns available to the report type. Though not strictly required, a report without columns isn't useful |
+
+`<sections>` (group of columns) sub-elements:
+
+| Element | Required | Notes |
+|---------|----------|-------|
+| `<masterLabel>` | Yes | Section heading shown in the report builder |
+| `<columns>` | Conditional | One per field exposed in the section |
+
+`<columns>` (single field) sub-elements:
+
+| Element | Required | Notes |
+|---------|----------|-------|
+| `<field>` | Yes | Field API name (or dotted lookup-traversal path) |
+| `<table>` | Yes | The object the field belongs to — base object name or dotted relationship path |
+| `<checkedByDefault>` | Yes | `true` if the column is selected by default in the report builder |
+| `<displayNameOverride>` | No | Custom column label shown in the report builder, overriding the field's default label |
+
+## Critical Rules (Read First)
+
+### Rule 1: If `<fullName>` Is Present, It Must Match the File Name
+In source format, `fullName` is inherited from `Metadata` and derived from the file name, so the `<fullName>` element is technically optional. The repo convention is to include it. **If you include `<fullName>`, its value must equal the file name (everything before `.reportType-meta.xml`) exactly — same characters, same casing, same underscores.**
+
+**Wrong** — file name and `<fullName>` differ:
+- File: `account_projects.reportType-meta.xml`
+- `<fullName>AccountProjects</fullName>`
+  (Mismatch: file uses `account_projects`, fullName uses `AccountProjects`)
+
+**Right** — file name and `<fullName>` are identical:
+- File: `AccountProjects.reportType-meta.xml`
+- `<fullName>AccountProjects</fullName>`
+
+### Rule 2: Join Semantics — `outerJoin` Controls Inclusion
+
+Each `<join>` block has an `<outerJoin>` element that determines which primary records appear in the report:
+
+| `<outerJoin>` value | Behavior | Report Builder Label |
+|---------------------|----------|----------------------|
+| `false` | Inner join — only primary records that HAVE at least one related record | "Each 'A' record must have at least one related 'B' record" |
+| `true` | Outer join — all primary records, with or without related records | "'A' records may or may not have related 'B' records" |
+
+**Default when unspecified:** Use `true` (outer join) when the user wants to see all primary records regardless of children. Use `false` when the report only makes sense if children exist.
+
+### Rule 3: Each Object Needs Its Own `<sections>` Block
+
+Every object in the CRT (primary + each joined object) must have a corresponding `<sections>` block that lists the fields exposed for reporting. Without a section for an object, none of its fields appear in the report builder.
+
+- `<masterLabel>` on each section is the section heading in the report builder
+- `<columns>` entries list the fields — each with a `<field>` (API name) and `<table>` (object API name)
+- For fields reached via lookup, use the relationship path in `<field>` (e.g. `Owner.Name` with `<table>` set to the owning object)
+
+### Rule 4: Field API Names, Not Labels
+
+Use exact API names for fields: standard fields use their defined names (`Name`, `CreatedDate`, `OwnerId`), custom fields use `Field__c`. Custom objects must include `__c`.
+
+**Wrong:**
+- `<field>Account Name</field>`
+
+**Right:**
+- `<field>Name</field>` with `<table>Account</table>`
+
+### Rule 5: Relationship Path for Joined Objects
+
+When adding a `<join>`, the `<relationship>` element must use the **child relationship name** as defined on the lookup/master-detail field pointing from the child object to the parent. For custom relationships, this typically ends in `__r`.
+
+**Wrong:**
+- `<relationship>Project</relationship>` (for a custom child relationship)
+
+**Right:**
+- `<relationship>Projects__r</relationship>` (child relationship name)
+- `<relationship>Contacts</relationship>` (standard, non-custom child relationship)
+
+### Rule 6: Maximum 4 Objects Total in a Join Chain
+
+A single CRT can join a maximum of **four objects total** (the base object + up to 3 additional objects via nested `<join>` blocks).
+
+### Rule 7: No Inner Join After an Outer Join
+
+Once the join chain contains an outer join (`<outerJoin>true</outerJoin>`), every subsequent nested join must also be an outer join. An inner join that follows an outer join earlier in the sequence is not allowed.
+
+**Wrong:**
+```xml
+<join>
+    <outerJoin>true</outerJoin>        <!-- outer join first -->
+    <relationship>Contacts</relationship>
+    <join>
+        <outerJoin>false</outerJoin>   <!-- WRONG: inner join after outer -->
+        <relationship>Assets</relationship>
+    </join>
+</join>
+```
+
+**Right:**
+```xml
+<join>
+    <outerJoin>true</outerJoin>
+    <relationship>Contacts</relationship>
+    <join>
+        <outerJoin>true</outerJoin>    <!-- outer stays outer -->
+        <relationship>Assets</relationship>
+    </join>
+</join>
+```
+
+### Rule 8: `<table>` for Joined Objects Uses Dotted Path
+
+In `<sections>`, the `<table>` element identifies which object in the join chain each column belongs to. For the base object, use the object name directly (e.g. `Account`). For joined objects, use the **dotted relationship path** from the base object.
+
+| Object in chain | `<table>` value |
+|-----------------|-----------------|
+| Base (Account) | `Account` |
+| First join (Account → Contacts) | `Account.Contacts` |
+| Nested join (Account → Contacts → Assets) | `Account.Contacts.Assets` |
+
+### Rule 9: Field Paths Can Traverse Lookups
+
+`<field>` values may reference fields reached via lookup relationships using dot notation — for example `Owner.Email` (owner User's email) or `ReportsTo.CreatedBy.Contact.Owner.MobilePhone`. The `<table>` must still be the object that owns the starting field.
+
+### Rule 10: Historical Trending Fields Use `_hst` Suffix
+
+For a field with `trackTrending=true`, the API name in `<field>` and `<table>` uses the `_hst` suffix:
+
+```xml
+<columns>
+    <checkedByDefault>false</checkedByDefault>
+    <field>Field2__c_hst</field>
+    <table>CustomTrendedObject__c.CustomTrendedObject__c_hst</table>
+</columns>
+```
+
+### Rule 11: Primary Object Cannot Be Changed After Deployment
+
+Once deployed, the `<baseObject>` of a CRT is locked. To change the primary object, create a new CRT and retire the old one.
+
+### Rule 12: `autogenerated` Is Reserved for Historical Trending
+
+The `<autogenerated>` element (API 29.0+) marks CRTs that Salesforce created automatically when historical trending was enabled on an object. Do not set this manually on hand-authored CRTs.
+
+## Generation Workflow
+
+### Step 1: Gather Requirements
+- Primary object API name (e.g. `Account`, `Project__c`)
+- Related objects and the relationship between each (which has the lookup/master-detail to which)
+- For each relationship: inner join (children required) or outer join (children optional)?
+- Which fields to expose per object — aim for task-relevant, not the full field list
+- Audience and category — where should this appear in the report builder picker?
+- Whether this ships as `deployed=true` now or stays `deployed=false` during iteration
+
+### Step 2: Examine Existing Examples
+- Look in the project for in-project CRT patterns
+- If existing report types have been retrieved from an org, compare against those structures
+
+### Step 3: Write the Specification
+Document before authoring:
+- `fullName` and `label`
+- `baseObject`
+- Category and `deployed` state
+- Join chain: for each related object — relationship name, outer vs inner join
+- Section layout: one section per object, ordered list of fields
+- Acceptance criteria: which records should appear when the report runs, which fields are available in the builder
+
+### Step 4: Author the Metadata File
+
+Start from the closest example in `examples/` and adapt it to the user's scenario:
+
+- Primary object only (no joins) → `examples/AccountsWithIndustry.reportType-meta.xml`
+- Outer join (primary records included even without children) → `examples/AccountsWithProjects.reportType-meta.xml`
+- Nested inner join (every level requires children) → `examples/AccountProjectsWithTasks.reportType-meta.xml`
+
+Name the file `<DeveloperName>.reportType-meta.xml`.
+
+### Step 5: Validate
+- Well-formed XML with correct namespace (`xmlns="http://soap.sforce.com/2006/04/metadata"`)
+- File name (without `.reportType-meta.xml`) matches `<fullName>` when `<fullName>` is included
+- `<baseObject>` is a valid API name and the object is deployed
+- Every `<relationship>` uses the correct child relationship name (`__r` suffix for custom)
+- Each object referenced in `<sections>` is part of the CRT (primary or joined)
+- All `<field>` references exist on the parent `<table>` and use API names (not labels)
+- `<category>` is a valid Salesforce category value
+- `<deployed>` is `true` if users need to access the CRT immediately
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `examples/AccountsWithIndustry.reportType-meta.xml` | Step 2 / Step 4 — primary-object-only template |
+| `examples/AccountsWithProjects.reportType-meta.xml` | Step 2 / Step 4 — outer-join template (primary included even without children) |
+| `examples/AccountProjectsWithTasks.reportType-meta.xml` | Step 2 / Step 4 — nested inner-join template (every level requires children) |
+| `references/category-values.md` | Step 3 — to choose a valid `<category>` value from the `ReportTypeCategory` enum |
+| `references/errors-and-troubleshooting.md` | When fields don't appear in the report builder or join requirements conflict |
+
+## Verification Checklist
+
+### Universal Checks
+- [ ] File extension is `.reportType-meta.xml`
+- [ ] File basename satisfies the developer-name rules (begins with a letter, only letters/numbers/underscores, no spaces, no trailing underscore, no consecutive underscores)
+- [ ] If `<fullName>` is included, it matches the file basename exactly (same characters, casing, and underscores)
+- [ ] `<label>` is human-readable and under 40 characters
+- [ ] `<description>` explains the business purpose
+- [ ] `<baseObject>` uses a valid API name and that object is deployed
+- [ ] `<category>` is a valid `ReportTypeCategory` enum value
+- [ ] `<deployed>` is set appropriately (`true` for user access, `false` for in-progress iteration)
+- [ ] `<autogenerated>` is NOT set manually (reserved for historical-trending CRTs)
+
+### Join Checks
+- [ ] Each `<join>` uses the correct child **relationship name** (not the lookup field API name)
+- [ ] Custom relationships use `__r` suffix
+- [ ] `<outerJoin>` is set intentionally: `true` = optional children, `false` = required children
+- [ ] No inner join (`<outerJoin>false</outerJoin>`) appears after an outer join earlier in the sequence
+- [ ] Total object count (base + joins, including nested) is 4 or fewer
+
+### Section Checks
+- [ ] Every object in the CRT has a corresponding `<sections>` block
+- [ ] `<masterLabel>` on each section is descriptive
+- [ ] Every `<columns>` has both `<field>` (API name) and `<table>` (object API name or dotted path)
+- [ ] `<checkedByDefault>` is set for each column
+- [ ] `<table>` for base object is the object API name (e.g. `Account`)
+- [ ] `<table>` for joined objects uses the dotted relationship path (e.g. `Account.Projects__r`, `Account.Projects__r.Tasks__r`)
+- [ ] Field references use API names (not labels); custom fields use `__c`
+- [ ] Lookup traversal fields use dot notation (e.g. `Owner.Email`) with `<table>` set to the object owning the starting field
+- [ ] Historical trending fields use `_hst` suffix in both `<field>` and `<table>` when applicable
+- [ ] No duplicate fields within a section