@salesforce/afv-skills 1.31.0 → 1.33.0

package/skills/platform-lightning-type-widget-coordinate/references/lightning-type-discovery.md

@@ -0,0 +1,124 @@
+# Lightning Type Discovery Procedure
+
+Use this procedure in Phase 2 of the orchestrator workflow. The goal is to resolve the user's named Lightning Type into an on-disk `schema.json`, verify it is **Apex-backed** (the only kind this orchestrator handles), and capture a SHA-256 fingerprint plus the Apex class FQN for the Phase 5 P0 gate and the Phase 4 widget-skill handoff.
+
+> **Applies to the `existing-lightning-type-with-widget` path only.** Skipped on the `new-lightning-type-with-widget` path (the user is creating a new Lightning Type — there is nothing to discover). Do not run this procedure when Phase 1 picks `new-lightning-type-with-widget`.
+
+---
+
+The sequence is **find → verify → ensure-class**: locate the Lightning Type (local project first, then org), verify it is Apex-backed, then ensure its backing Apex class is in the local project (retrieving it from the org if needed). The downstream widget skill and the Phase 5 `field-trace` gate both read the `.cls` to enumerate `@AuraEnabled` fields — a Lightning Type without its class in the local project is unrenderable.
+
+---
+
+## Step 1 — Search the local project files
+
+Look for any of:
+
+- `force-app/**/lightningTypes/<TypeName>/schema.json`
+- `<pkgDir>/lightningTypes/<TypeName>/schema.json` where `<pkgDir>` = `<packageDirectories[].path>/main/default` (per `platform-widget-generate/references/widget-bundle-layout.md`).
+
+Match `<TypeName>` case-insensitively for the search but preserve the directory's actual case for outputs.
+
+**Outcomes:**
+
+- **Exactly one match.** Continue to Step 3 (verify Apex-backed) before capturing path + SHA-256.
+- **Multiple matches** (case-insensitive name collision, multiple package directories, etc.). List candidates with their full paths to the user. Ask: *"Multiple Lightning Types match `<TypeName>`. Which one should the widget ground on?"* Wait for the user's pick, then continue to Step 3.
+- **No match — do not skip.** Continue to Step 2 (org retrieve).
+
+---
+
+## Step 2 — Retrieve from the org
+
+If the Lightning Type is not in the local project, run:
+
+```bash
+sf project retrieve start --metadata LightningTypeBundle:<TypeName>
+```
+
+The retrieve writes the Lightning Type bundle into the project under the configured package directory.
+
+**Outcomes:**
+
+- **Retrieve succeeds with one Lightning Type.** Continue to Step 3 (verify Apex-backed) before capturing path + SHA-256 + Apex class FQN.
+- **Retrieve succeeds with multiple Lightning Types** (wildcard match; `LightningType:*<partial>*`). List them. Ask the user to pick. Re-retrieve with the exact name if needed, then continue to Step 3.
+- **Retrieve reports "no metadata found".** The Lightning Type does not exist in the org. Continue to Step 5.
+- **Retrieve fails with an error** (auth expired, org unreachable, permission denied, etc.). Surface the CLI error verbatim. Ask the user to fix and re-run.
+
+---
+
+## Step 3 — Verify the Lightning Type is Apex-backed
+
+Read the located `schema.json`. Inspect the root `lightning:type` value.
+
+| Root `lightning:type` value | Decision |
+|---|---|
+| Starts with `@apexClassType/` (for example `@apexClassType/c__AccountBriefing`) | **Apex-backed.** Continue. Capture the FQN — everything after `@apexClassType/`. The FQN points at the **outer Apex class**, whose `@AuraEnabled` fields define the payload shape. The `$<InnerClass>` suffix is not used at the Lightning Type root; inner classes live as `List<Inner>` fields on the outer class. |
+| `lightning__objectType` (with primitive `properties`) | **Object/JSON-based.** Out of scope for this orchestrator. Tell the user: *"`<TypeName>` is an object/JSON-based Lightning Type. This orchestrator only handles Apex-backed Lightning Types. Use `platform-custom-lightning-type-generate` and `platform-widget-generate` separately for this case."* Stop. |
+| Anything else | Surface the unrecognized value to the user and stop. Do not guess. |
+
+When Apex-backed, capture path + SHA-256 + Apex class FQN, then continue to Step 4 (do not stop here — the class must be verified in the local project first).
+
+---
+
+## Step 4 — Ensure the backing Apex class is in the local project
+
+**Both entry paths converge here** — a Lightning Type located in the local project (Step 1) and one retrieved from the org (Step 2) both reach this step. Locating the Lightning Type does NOT guarantee its backing class is local: `sf project retrieve --metadata LightningTypeBundle:<TypeName>` pulls only the bundle, not the referenced Apex class, and a hand-authored or partially-synced local bundle can reference a class that was never committed.
+
+Parse `<ClassName>` from the Apex class FQN captured in Step 3 (`@apexClassType/<namespace>__<ClassName>` → `<ClassName>`; strip any `$<Inner>` suffix — retrieve the outer class). Check whether `<pkgDir>/classes/<ClassName>.cls` exists in the local project.
+
+**Outcomes (covering all four LT × class scenarios):**
+
+| Lightning Type source | `.cls` in local project? | Action |
+|---|---|---|
+| local project (Step 1) | yes | Nothing to do — continue. |
+| local project (Step 1) | no | Retrieve the class (below). |
+| org-retrieve (Step 2) | yes | Nothing to do — continue. |
+| org-retrieve (Step 2) | no | Retrieve the class (below). |
+
+When the class is absent, retrieve it by name:
+
+```bash
+sf project retrieve start --metadata ApexClass:<ClassName>
+```
+
+`ApexClass` is the metadata type; `<ClassName>` is the bare class name — no namespace prefix, no `.cls` extension. For multiple classes, comma-separate: `--metadata ApexClass:OrderSummary --metadata ApexClass:OrderLine`.
+
+**Retrieve outcomes:**
+
+- **Succeeds.** The `.cls` now lands under `<pkgDir>/classes/`. Continue.
+- **Reports "no metadata found".** The backing class exists neither in the local project nor in the org — the Lightning Type is **unrenderable** (its payload shape is undefined). Surface this to the user verbatim and STOP. Do not hand the widget skill a Lightning Type whose `@AuraEnabled` fields cannot be enumerated.
+- **Fails with an error** (auth expired, org unreachable, permission denied). Surface the CLI error verbatim. Ask the user to fix and re-run.
+
+Done — path + SHA-256 + Apex class FQN captured, and the `.cls` confirmed in the local project.
+
+---
+
+## Step 5 — Lightning Type does not exist anywhere
+
+Tell the user the Lightning Type is not in the local project and not in the org. Offer to **switch to the `new-lightning-type-with-widget` path** — generate a new Apex-backed Lightning Type (with its Apex class, auto-engaged) before authoring the widget.
+
+Wait for the user's confirmation. Do not silently pick. If the user does not want a Lightning Type at all, route them to `platform-widget-generate` directly — that case is outside this orchestrator's scope.
+
+---
+
+## Staleness rule
+
+Do **not** maintain a cross-session cache. Each invocation of this orchestrator re-reads the local project and re-retrieves from the org as needed. Any single retrieve result is treated as authoritative for the lifetime of that orchestrator run.
+
+---
+
+## Output of Phase 2
+
+```text
+lightningTypeSchema = {
+  name: "<TypeName>",
+  path: "<pkgDir>/lightningTypes/<TypeName>/schema.json",
+  sha256: "<hex>",
+  source: "fs" | "org-retrieve",
+  apexClassFqn: "<namespace>__<ClassName>",   # outer class only — no $<Inner> form
+  apexClassPath: "<pkgDir>/classes/<ClassName>.cls",   # guaranteed in the local project by Step 4
+  apexClassSource: "fs" | "org-retrieve",
+}
+```
+
+Phase 2 always ends with a non-null `lightningTypeSchema` on the `existing-lightning-type-with-widget` path, **and with the backing `.cls` confirmed in the local project** (per Step 4). If discovery fails and the user does not switch to `new-lightning-type-with-widget`, or if the backing Apex class exists nowhere, the orchestrator stops.

package/skills/platform-lightning-type-widget-coordinate/references/validation-gates.md

@@ -0,0 +1,130 @@
+# Validation Gates
+
+The orchestrator runs only **cross-skill validations** — checks that span two skills' outputs or compare against state captured in earlier phases. Widget-bundle-internal checks (schema parses, root keys, leaf types, attribute bindings resolve, `.uiwidget-meta.xml` well-formed, `<UiWidgetBundle>` root, widget-type) are owned by `platform-widget-generate` and run as part of its own self-validation step.
+
+Run every gate below. If a hard-failure gate fails, fix and re-run before reporting success. Warn-level gates are advisory — failures emit warnings but do not block.
+
+---
+
+## Hard — block on failure
+
+| Name | Gate | Failure → fix |
+|---|---|---|
+| `lightning-type-unchanged` | **`existing-lightning-type-with-widget` only** — the Lightning Type `schema.json` SHA-256 captured in Phase 2 matches the on-disk SHA at end of Phase 4. | The orchestrator (or a sub-skill) silently edited the Lightning Type. Restore the Lightning Type from `git diff` and re-author the widget against the unchanged Lightning Type. |
+| `renderer-wires-widget` | **Both paths** — RUN the check below and PRINT the result. **Reporting `pass` without running the commands is a hard violation — report `not run` instead.** | The Lightning Type does not point at this widget — the widget bundle ships dead and is unreachable from any consumer that resolves through the CLT. Author or update `renderer.json` per the widget-rendition pattern in `platform-custom-lightning-type-generate/references/widget-rendition.md`. If a different widget is already wired, surface the conflict instead of silently overwriting. |
+
+### `renderer-wires-widget` — RUN procedure
+
+Run each command below **verbatim**. Observe each command's output in the tool result and reason about it — do NOT capture into shell variables with `$(…)`, do NOT use process substitution `<(…)`, do NOT use brace expansion. Vibes' safe-shell filter blocks those patterns and prompts for manual approval even in Bypass mode. See "Hard Rules — shell commands" in the orchestrator SKILL.md.
+
+1. **Verify file exists and parses as JSON:**
+
+   ```bash
+   jq . <pkgDir>/lightningTypes/<TypeName>/renderer.json > /dev/null && echo "PARSE: ok" || echo "PARSE: FAIL"
+   ```
+
+2. **Verify definition points at this widget.** Print the actual value and compare it to the expected one in your reasoning:
+
+   ```bash
+   jq -r '.renderer.componentOverrides["$"].definition' <pkgDir>/lightningTypes/<TypeName>/renderer.json
+   ```
+
+   Expected output: `@widget/c/<widgetName>`. If output equals expected → `DEFINITION: ok`; otherwise `DEFINITION: FAIL (got <actual>, expected @widget/c/<widgetName>)`.
+
+3. **Verify attribute bindings cover every widget schema property.** Print both key lists with separate commands; compare them in your reasoning (do NOT `diff` with process substitution):
+
+   ```bash
+   echo "SCHEMA_KEYS (expected):"
+   jq -r '.properties.attributes.properties | keys[]' <pkgDir>/uiWidgets/<widgetName>/schema.json | sort -u
+   ```
+
+   ```bash
+   echo "RENDERER_KEYS (actual):"
+   jq -r '.renderer.componentOverrides["$"].attributes | keys[]' <pkgDir>/lightningTypes/<TypeName>/renderer.json | sort -u
+   ```
+
+   Classify: same set → `ATTRIBUTES: ok`. Keys in `SCHEMA_KEYS` not in `RENDERER_KEYS` → `ATTRIBUTES: FAIL (missing: <list>)`. Keys in `RENDERER_KEYS` not in `SCHEMA_KEYS` → `ATTRIBUTES: FAIL (extra: <list>)`.
+
+4. **Verify each attribute value is a well-formed binding.** Dump the attributes map and inspect each entry in your reasoning:
+
+   ```bash
+   jq '.renderer.componentOverrides["$"].attributes' <pkgDir>/lightningTypes/<TypeName>/renderer.json
+   ```
+
+   For every key `K`, the value must match `{!$attrs.K}` exactly (same key name, no whitespace). All match → `BINDINGS: ok`. Otherwise `BINDINGS: FAIL (<key>: got <value>, expected {!$attrs.<key>})` for each offender.
+
+5. **Result classification:**
+   - All checks pass → `pass`
+   - File missing or does not parse → `fail (renderer.json missing or invalid JSON)`
+   - Definition mismatch → `fail (definition does not point at widget: got <actual>)`
+   - Attribute coverage mismatch → `fail (missing bindings: <list>)` or `fail (extra bindings: <list>)`
+   - Binding format invalid → `fail (malformed binding for <key>: <actual>)`
+
+---
+
+## Warn — advisory
+
+| Name | Gate | Warning meaning |
+|---|---|---|
+| `field-trace` | **Both paths** — RUN the trace below and PRINT both lists explicitly. | See "`field-trace` — RUN procedure" below. **Reporting `pass` without printing the two lists side by side is a hard violation — report `not run` instead.** |
+| `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. | Apex / Custom Lightning Type references are unresolved when validated against the org. Common cause: the FQN in the Custom Lightning Type does not match the actual Apex class. **Reporting `pass` without running this command is a hard violation. Reporting `not run` is only valid if the source files do not exist in the local project — "not yet deployed" is not a valid reason; `--check-only` submits the source as part of the call.** |
+
+### `field-trace` — RUN procedure
+
+The gate enforces two things: no invented widget fields (subset rule), and no silent omission of `@AuraEnabled` fields (omission must be in the build plan's `Properties omitted:` and approved at Phase 3).
+
+**`APEX_FIELDS` and `WIDGET_PROPS` are labels in the printed output, NOT shell variables. Do NOT assign either with `APEX_FIELDS=$(grep …)` or `WIDGET_PROPS=$(jq …)` — Vibes' safe-shell filter blocks `$(…)` and stalls the eval on manual approval. Run each command bare and reason about the output.**
+
+1. **Resolve the payload class from the Apex class FQN**, then extract `@AuraEnabled` field names from the payload class **and from every inner class referenced by it** — both singular nested objects (e.g. `Address address`) and `List<InnerClass>` collections. Split the FQN on `$`: no `$` → the outer class is the payload; with `$` (e.g. `c__OrderResponses$CreateResult`) → the named inner class is the payload and the outer class's own `@AuraEnabled` fields are NOT part of the trace.
+
+   Read the outer `.cls` file at `<pkgDir>/classes/<ClassName>.cls`; when the payload is the outer class, grep the whole file; when the payload is an inner class, scope the grep to that inner class's block.
+
+   ```bash
+   # Outer-class payload — print the field names. Do NOT wrap in $().
+   echo "APEX_FIELDS:"
+   grep -B0 -A2 '@AuraEnabled' <pkgDir>/classes/<ClassName>.cls \
+     | grep -oE '(public|global)\s+[A-Za-z0-9_<>,\s]+\s+[a-zA-Z_][a-zA-Z0-9_]*\s*;' \
+     | sed -E 's/.*\s([a-zA-Z_][a-zA-Z0-9_]*)\s*;/\1/' \
+     | sort -u
+   ```
+
+   For an inner-class payload, read the .cls file, locate the named inner class's block (`class <InnerClass> {…}`), and run the field enumeration scoped to that block only. Identify further inner classes the payload class declares (singular `InnerClass <field>;` and `List<InnerClass> <field>;`) — typically siblings inside the same outer file — and repeat against each. Combine the printed sets in your reasoning under the label `APEX_FIELDS`. If grep returns nothing, fall back to reading the .cls file with the Read tool and listing fields manually — but do NOT skip the comparison.
+
+2. Extract widget schema property keys, expanding nested `lightning__objectType` properties to their inner-field dot paths:
+
+   ```bash
+   echo "WIDGET_PROPS:"
+   jq -r '.properties.attributes.properties | keys[]' <pkgDir>/uiWidgets/<widgetName>/schema.json | sort -u
+   ```
+
+   For any property whose `lightning:type` is `lightning__objectType`, also include the dot-notation bindings actually referenced in the widget body (e.g. `address.city`) — you can see these by reading the widget JSON directly with the Read tool. For any property whose `lightning:type` is `lightning__listType`, also include the `{!$item.<innerField>}` references inside the `forEach`. Combine in your reasoning under the label `WIDGET_PROPS`.
+
+3. PRINT both lists in the gate report (not just an assertion) — as plain text you author from the two command outputs above, NOT via a shell expression:
+
+   ```text
+   APEX_FIELDS:  cartId, currencyIsoCode, items.itemId, items.qty, itemCount, ...
+   WIDGET_PROPS: cartId, currencyIsoCode, itemCount, ...
+   INVENTED  (widget − apex): <empty>
+   OMITTED   (apex − widget): items.*
+   ```
+
+4. Result classification:
+   - `INVENTED` non-empty → **fail** (subset rule violated). Report `fail (invented: <list>)`.
+   - `OMITTED` non-empty AND every omitted field appears in the Phase 3 build plan's `Properties omitted:` section → **pass** (auditable omission).
+   - `OMITTED` non-empty AND any omitted field is NOT in `Properties omitted:` → **warn** (silent omission). Report `warn (silent omission: <list>)` and surface to the user before the final summary.
+   - Both empty → **pass**.
+
+---
+
+## Direction of subset rule
+
+The widget `schema.json` (plus the dot-notation paths it binds through nested `lightning__objectType` properties and the `{!$item.X}` references inside `lightning__listType` loops) is a **subset** of the Apex class's `@AuraEnabled` fields (outer class plus every referenced inner class). The orchestrator enforces both directions, asymmetrically:
+
+- **No invented fields (hard).** Widget MUST NOT introduce properties or inner-field paths the Apex classes do not expose. A non-empty INVENTED set fails `field-trace`.
+- **No silent omissions (warn).** Widget MAY omit Apex fields, but every omission MUST appear in the Phase 3 build plan's `Properties omitted:` section with a rationale. Omissions not in the plan are silent and warn at `field-trace` (OMITTED list flagged). The leaf skill must surface the proposed omissions to the user before authoring (`platform-widget-generate/references/schema-from-lightning-type.md`). Inner-class fields (whether reached as singular nested objects or via `List<InnerClass>`) are NEVER silently omitted.
+
+---
+
+## Reporting
+
+Phase 6 must list each gate's result by name: `pass`, `fail (<reason>)`, `warn (<reason>)`, or `not run`. Do not summarize ("all passed") — list each gate explicitly so the reviewer can spot a silent skip.

package/skills/platform-metadata-deploy/SKILL.md

@@ -3,6 +3,27 @@ name: platform-metadata-deploy
 description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code (use platform-apex-generate), building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate or platform-custom-field-generate), or querying org data (use platform-data-manage)."
 metadata:
   version: "1.1"
+  relatedSkills:
+    - "agentforce-generate"
+    - "agentforce-test"
+    - "automation-flow-generate"
+    - "experience-lwc-generate"
+    - "integration-connectivity-connected-app-configure"
+    - "integration-connectivity-generate"
+    - "platform-apex-generate"
+    - "platform-apex-test-run"
+    - "platform-custom-field-generate"
+    - "platform-custom-object-generate"
+    - "platform-data-manage"
+  cliTools:
+    - tool: ["curl"]
+      semver: ">=7.0.0"
+    - tool: ["git"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.7.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # platform-metadata-deploy: Comprehensive Salesforce DevOps Automation

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

@@ -0,0 +1,159 @@
+---
+name: platform-report-generate
+description: "Use this skill when users need to create, generate, or validate Salesforce Lightning Report metadata. Trigger when users mention reports, creating reports, report metadata, .report-meta.xml files, tabular reports, summary reports, matrix reports, joined reports, report columns, report groupings, report filters, report charts, cross-filters, bucket fields, report formulas, or report time frame filters. Also use when users say things like 'create a report', 'generate a report', 'build a report on Accounts', 'add a chart to my report', or when they encounter deployment errors for .report-meta.xml files. Do NOT trigger for: creating or modifying Custom Report Type metadata (.reportType-meta.xml — use platform-custom-report-type-generate), creating dashboards, creating list views, running or viewing existing reports in the UI, or SOQL queries."
+metadata:
+  version: "1.0"
+  minApiVersion: "51.0"
+  relatedSkills:
+    - "platform-custom-report-type-generate"
+  mcpTools:
+    salesforce-api-context:
+      tools: ["get_metadata_type_sections", "get_metadata_type_context", "get_metadata_type_shape"]
+      semver: ">=1.0.0"
+---
+
+## Overview
+
+Lightning Reports define how Salesforce data is queried, grouped, filtered, and displayed. Each report is a single `.report-meta.xml` file placed under `reports/<FolderName>/` within the project's source directory (check `sfdx-project.json` → `packageDirectories[].path` for the source root).
+
+## Critical Rules (Read First)
+
+**TOP DEPLOYMENT KILLERS — check these BEFORE generating any report:**
+1. **Grouping fields in columns** — Fields in `<groupingsDown>` or `<groupingsAcross>` must NEVER also appear in `<columns>`
+2. **Wrong column names** — Column names are report-type-specific. ALWAYS call MCP tools to verify (see `references/column-names.md`)
+3. **Wrong scope** — LeadList uses `org`, not `organization`
+4. **Filter column dot notation** — Filter `<column>` values use FLAT names (`INDUSTRY`, `TYPE`) NOT dot notation (`ACCOUNT.INDUSTRY` is INVALID)
+5. **Multi-value picklist filters** — Use ONE `<criteriaItems>` with comma-separated `<value>` (e.g., `Technology,Financial Services`). Do NOT split into multiple criteriaItems with booleanFilter
+
+### Rule 1: Format Determines Required Elements
+
+| Format | `<groupingsDown>` | `<groupingsAcross>` | `<block>` |
+|--------|-------------------|---------------------|-----------|
+| `Tabular` | Not allowed | Not allowed | No |
+| `Summary` | At least 1 (max 3) | Not allowed | No |
+| `Matrix` | At least 1 (max 3) | At least 1 (max 3) | No |
+| `Joined` | Not at top level | Not at top level | At least 2 (max 5) |
+
+### Rule 2: Use Platform Column Names
+
+Report metadata uses **platform report column names**, NOT raw API field names. **ALWAYS call `get_metadata_type_sections` or `get_metadata_type_context` to confirm valid column names.** See `references/column-names.md` for common mappings per report type.
+
+### Rule 3: Valid Report Type Required
+
+`<reportType>` must be a standard API name (e.g., `Opportunity`, `AccountList`, `CaseList`, `LeadList`, `AccountContactRole`) or a deployed custom report type developer name.
+
+### Rule 4–5: Chart & Aggregates Require Summary/Matrix
+
+Charts and `<aggregateTypes>` (Sum, Average, etc.) only work in Summary and Matrix reports.
+
+### Rule 6–8: Limits
+
+- Max **3 cross-filters** per report, each with up to **5 criteria items**
+- `<filterLogic>` must reference all filters sequentially (e.g., `1 AND (2 OR 3)`)
+- Joined reports: 2–5 blocks, each block format must be Summary or Matrix (not Tabular)
+
+### Rule 9: Folder Structure
+
+Reports must live inside a folder with a corresponding folder metadata file:
+```xml
+<sourceDir>/reports/<FolderName>/<ReportName>.report-meta.xml
+<sourceDir>/reports/<FolderName>-meta.xml
+```
+Determine `<sourceDir>` from `sfdx-project.json` (commonly `force-app/main/default`, but this is configurable).
+
+### Rule 10–11: Date Columns & Scope
+
+- Date columns use platform names (`CLOSE_DATE`, not `CloseDate`)
+- LeadList scope is `org`; Opportunity/AccountList/CaseList use `organization`
+
+### Rule 12–13: Description & Groupings
+
+- `<description>` max **255 characters**
+- Grouping fields must NOT appear in `<columns>` — automatic deployment failure
+
+### Rule 14: Folder Metadata Requires `<sharedTo>`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ReportFolder xmlns="http://soap.sforce.com/2006/04/metadata">
+    <folderShares>
+        <accessLevel>Manage</accessLevel>
+        <sharedTo>AllInternalUsers</sharedTo>
+        <sharedToType>Group</sharedToType>
+    </folderShares>
+    <name>My Report Folder</name>
+</ReportFolder>
+```
+
+### Rule 15: Valid Date Intervals Only
+
+Use `INTERVAL_CURRENT` for "this quarter", `INTERVAL_CURY` for "this year", `INTERVAL_LAST30` for last 30 days. Do NOT use `INTERVAL_CURQ` — it is not valid. See `references/date-intervals.md` for the full list.
+
+## Top-Level Elements
+
+| Element | Required | Notes |
+|---------|----------|-------|
+| `<name>` | Yes | Report name (max 40 chars) |
+| `<reportType>` | Yes | Report type API name |
+| `<format>` | Yes | `Tabular`, `Summary`, `Matrix`, or `Joined` |
+| `<scope>` | Recommended | `organization` (or `org` for LeadList) |
+| `<columns>` | Yes | Field columns — each has `<field>` and optional `<aggregateTypes>` |
+| `<filter>` | No | Contains `<criteriaItems>` with `<column>`, `<operator>`, `<value>` |
+| `<groupingsDown>` | Conditional | Row groupings: `<field>`, `<dateGranularity>`, `<sortOrder>` |
+| `<groupingsAcross>` | Conditional | Column groupings (Matrix only) |
+| `<timeFrameFilter>` | Recommended | `<dateColumn>`, `<interval>`, optional `<startDate>`/`<endDate>` |
+| `<chart>` | No | See `references/chart-types.md` |
+| `<buckets>` | No | Bucket field definitions |
+| `<crossFilters>` | No | Cross-object filters (`with`/`without`) |
+| `<showDetails>` | Recommended | `true`/`false` |
+| `<showGrandTotal>` | Recommended | `true`/`false` |
+| `<showSubTotals>` | Recommended | `true`/`false` |
+| `<description>` | Recommended | Business purpose (max 255 chars) |
+| `<block>` | Conditional | Joined format blocks |
+
+## Filter Syntax
+
+```xml
+<filter>
+    <criteriaItems>
+        <column>STAGE_NAME</column>
+        <operator>equals</operator>
+        <value>Closed Won</value>
+    </criteriaItems>
+</filter>
+```
+
+**Multi-value picklist:** Use ONE criteriaItem with comma-separated values:
+```xml
+<criteriaItems>
+    <column>INDUSTRY</column>
+    <operator>equals</operator>
+    <value>Technology,Financial Services</value>
+</criteriaItems>
+```
+
+Common operators: `equals`, `notEqual`, `lessThan`, `greaterThan`, `contains`, `startsWith`, `includes`, `excludes`, `isBlank`, `notBlank`. Full list in `references/filter-operations.md`.
+
+## Generation Workflow
+
+1. **Gather Requirements** — object, fields, groupings, filters, chart needs
+2. **Determine Format** — no groupings → Tabular; row groupings → Summary; row + column → Matrix; multiple objects → Joined
+3. **Identify Column Names** — call `get_metadata_type_sections` MCP tool to get valid platform column names for the report type
+4. **Author Metadata** — start from closest example in `examples/` and adapt
+5. **Create Folder** — generate folder directory + `<FolderName>-meta.xml` with `<folderShares>`
+6. **Validate** — run through `references/verification-checklist.md`
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/column-names.md` | Step 3 — column name mappings per report type |
+| `references/date-intervals.md` | When setting timeFrameFilter intervals |
+| `references/chart-types.md` | When adding a chart — all 17 types + legendPosition rules |
+| `references/filter-operations.md` | When building filters — complete operator reference |
+| `references/verification-checklist.md` | Step 6 — pre-deploy validation |
+| `references/errors-and-troubleshooting.md` | When fields are missing or deployment fails |
+| `examples/TabularOpportunitiesReport.report-meta.xml` | Tabular report template |
+| `examples/OpportunitiesByStageReport.report-meta.xml` | Summary report with chart |
+| `examples/OpportunitiesByStageAndQuarter.report-meta.xml` | Matrix report template |
+| `examples/AccountsCreatedThisYear.report-meta.xml` | Filtered report with time frame |

package/skills/platform-report-generate/examples/AccountsCreatedThisYear.report-meta.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Report xmlns="http://soap.sforce.com/2006/04/metadata">
+    <name>Accounts Created This Year</name>
+    <reportType>AccountList</reportType>
+    <format>Summary</format>
+    <scope>organization</scope>
+    <description>Shows accounts created in the current fiscal year, grouped by industry. Demonstrates a filtered report with timeFrameFilter, row-level filter, and date-based scoping on a non-Opportunity report type.</description>
+    <showDetails>true</showDetails>
+    <showGrandTotal>true</showGrandTotal>
+    <showSubTotals>true</showSubTotals>
+    <columns>
+        <field>ACCOUNT_NAME</field>
+    </columns>
+    <columns>
+        <field>INDUSTRY</field>
+    </columns>
+    <columns>
+        <field>TYPE</field>
+    </columns>
+    <columns>
+        <field>ANNUAL_REVENUE</field>
+        <aggregateTypes>Sum</aggregateTypes>
+        <aggregateTypes>Average</aggregateTypes>
+    </columns>
+    <columns>
+        <field>CREATED_DATE</field>
+    </columns>
+    <columns>
+        <field>OWNER_FULL_NAME</field>
+    </columns>
+    <groupingsDown>
+        <field>INDUSTRY</field>
+        <dateGranularity>None</dateGranularity>
+        <sortOrder>Asc</sortOrder>
+    </groupingsDown>
+    <filter>
+        <criteriaItems>
+            <column>TYPE</column>
+            <isUnlocked>true</isUnlocked>
+            <operator>notEqual</operator>
+            <value>Analyst,Press</value>
+        </criteriaItems>
+    </filter>
+    <timeFrameFilter>
+        <dateColumn>CREATED_DATE</dateColumn>
+        <interval>INTERVAL_CURY</interval>
+    </timeFrameFilter>
+</Report>

package/skills/platform-report-generate/examples/OpportunitiesByStageAndQuarter.report-meta.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Report xmlns="http://soap.sforce.com/2006/04/metadata">
+    <name>Opportunities Stage x Quarter</name>
+    <reportType>Opportunity</reportType>
+    <format>Matrix</format>
+    <scope>organization</scope>
+    <description>Cross-tabulates opportunities by stage (rows) and close date quarter (columns) with sum of amount. Demonstrates a Matrix report with both row and column groupings and aggregates.</description>
+    <showDetails>false</showDetails>
+    <showGrandTotal>true</showGrandTotal>
+    <showSubTotals>true</showSubTotals>
+    <columns>
+        <field>OPPORTUNITY_NAME</field>
+    </columns>
+    <columns>
+        <field>ACCOUNT_NAME</field>
+    </columns>
+    <columns>
+        <field>STAGE_NAME</field>
+    </columns>
+    <columns>
+        <field>AMOUNT</field>
+        <aggregateTypes>Sum</aggregateTypes>
+    </columns>
+    <columns>
+        <field>CLOSE_DATE</field>
+    </columns>
+    <groupingsDown>
+        <field>STAGE_NAME</field>
+        <dateGranularity>None</dateGranularity>
+        <sortOrder>Asc</sortOrder>
+    </groupingsDown>
+    <groupingsAcross>
+        <field>CLOSE_DATE</field>
+        <dateGranularity>FiscalQuarter</dateGranularity>
+        <sortOrder>Asc</sortOrder>
+    </groupingsAcross>
+    <params>
+        <name>open</name>
+        <value>all</value>
+    </params>
+    <params>
+        <name>probability</name>
+        <value>&gt;0</value>
+    </params>
+    <params>
+        <name>co</name>
+        <value>1</value>
+    </params>
+    <timeFrameFilter>
+        <dateColumn>CLOSE_DATE</dateColumn>
+        <interval>INTERVAL_CURY</interval>
+    </timeFrameFilter>
+</Report>

package/skills/platform-report-generate/examples/OpportunitiesByStageReport.report-meta.xml

@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Report xmlns="http://soap.sforce.com/2006/04/metadata">
+    <name>Opportunities by Stage</name>
+    <reportType>Opportunity</reportType>
+    <format>Summary</format>
+    <scope>organization</scope>
+    <description>Groups open opportunities by stage with a sum of amount, and includes a vertical bar chart. Demonstrates a Summary report with one grouping, an aggregate column, and an embedded chart.</description>
+    <showDetails>true</showDetails>
+    <showGrandTotal>true</showGrandTotal>
+    <showSubTotals>true</showSubTotals>
+    <columns>
+        <field>OPPORTUNITY_NAME</field>
+    </columns>
+    <columns>
+        <field>ACCOUNT_NAME</field>
+    </columns>
+    <columns>
+        <field>STAGE_NAME</field>
+    </columns>
+    <columns>
+        <field>AMOUNT</field>
+        <aggregateTypes>Sum</aggregateTypes>
+    </columns>
+    <columns>
+        <field>CLOSE_DATE</field>
+    </columns>
+    <columns>
+        <field>PROBABILITY</field>
+        <aggregateTypes>Average</aggregateTypes>
+    </columns>
+    <columns>
+        <field>FULL_NAME</field>
+    </columns>
+    <groupingsDown>
+        <field>STAGE_NAME</field>
+        <dateGranularity>None</dateGranularity>
+        <sortOrder>Asc</sortOrder>
+    </groupingsDown>
+    <filter>
+        <criteriaItems>
+            <column>STAGE_NAME</column>
+            <isUnlocked>true</isUnlocked>
+            <operator>notEqual</operator>
+            <value>Closed Won,Closed Lost</value>
+        </criteriaItems>
+    </filter>
+    <params>
+        <name>open</name>
+        <value>all</value>
+    </params>
+    <params>
+        <name>probability</name>
+        <value>&gt;0</value>
+    </params>
+    <params>
+        <name>co</name>
+        <value>1</value>
+    </params>
+    <timeFrameFilter>
+        <dateColumn>CLOSE_DATE</dateColumn>
+        <interval>INTERVAL_CURY</interval>
+    </timeFrameFilter>
+    <chart>
+        <chartType>VerticalColumn</chartType>
+        <groupingColumn>STAGE_NAME</groupingColumn>
+        <chartSummaries>
+            <aggregate>Sum</aggregate>
+            <column>AMOUNT</column>
+        </chartSummaries>
+        <enableHoverLabels>true</enableHoverLabels>
+        <location>CHART_TOP</location>
+        <size>Medium</size>
+        <title>Pipeline by Stage</title>
+    </chart>
+</Report>