@salesforce/afv-skills 1.61.0 → 1.62.0

package/skills/crm-analytics-wave-generate/examples/pipeline-by-industry-quarter.wdpr

@@ -0,0 +1,236 @@
+{
+    "runMode": "full",
+    "nodes": {
+        "LOAD_OPPORTUNITY": {
+            "action": "load",
+            "sources": [],
+            "parameters": {
+                "dataset": {
+                    "type": "connectedDataset",
+                    "label": "Opportunity",
+                    "connectionName": "SFDC_LOCAL",
+                    "sourceObjectName": "Opportunity"
+                },
+                "fields": ["Id", "AccountId", "Name", "StageName", "CloseDate", "Amount"],
+                "mode": "SYNCED",
+                "preserveCurrencyFields": [],
+                "sampleDetails": {
+                    "type": "TopN",
+                    "sortBy": []
+                }
+            }
+        },
+        "LOAD_ACCOUNT": {
+            "action": "load",
+            "sources": [],
+            "parameters": {
+                "dataset": {
+                    "type": "connectedDataset",
+                    "label": "Account",
+                    "connectionName": "SFDC_LOCAL",
+                    "sourceObjectName": "Account"
+                },
+                "fields": ["Id", "Name", "Industry"],
+                "mode": "SYNCED",
+                "preserveCurrencyFields": [],
+                "sampleDetails": {
+                    "type": "TopN",
+                    "sortBy": []
+                }
+            }
+        },
+        "JOIN_ACCOUNT": {
+            "action": "join",
+            "sources": ["LOAD_OPPORTUNITY", "LOAD_ACCOUNT"],
+            "parameters": {
+                "joinType": "LOOKUP",
+                "leftKeys": ["AccountId"],
+                "rightKeys": ["Id"],
+                "rightQualifier": "Account"
+            }
+        },
+        "COMPUTE_TOTAL_REVENUE": {
+            "action": "formula",
+            "sources": ["JOIN_ACCOUNT"],
+            "parameters": {
+                "expressionType": "SQL",
+                "fields": [
+                    {
+                        "name": "TotalRevenue",
+                        "label": "Total Revenue",
+                        "type": "NUMBER",
+                        "formulaExpression": "Amount"
+                    }
+                ]
+            }
+        },
+        "COMPUTE_CLOSE_YEAR": {
+            "action": "formula",
+            "sources": ["COMPUTE_TOTAL_REVENUE"],
+            "parameters": {
+                "expressionType": "SQL",
+                "fields": [
+                    {
+                        "name": "CloseYear",
+                        "label": "Close Year",
+                        "type": "TEXT",
+                        "formulaExpression": "date_format(CloseDate, 'yyyy')"
+                    }
+                ]
+            }
+        },
+        "COMPUTE_CLOSE_QUARTER": {
+            "action": "formula",
+            "sources": ["COMPUTE_CLOSE_YEAR"],
+            "parameters": {
+                "expressionType": "SQL",
+                "fields": [
+                    {
+                        "name": "CloseQuarter",
+                        "label": "Close Quarter",
+                        "type": "TEXT",
+                        "formulaExpression": "case when date_format(CloseDate, 'MM') <= '03' then 'Q1' when date_format(CloseDate, 'MM') <= '06' then 'Q2' when date_format(CloseDate, 'MM') <= '09' then 'Q3' else 'Q4' end"
+                    }
+                ]
+            }
+        },
+        "COMPUTE_INDUSTRY_FILLED": {
+            "action": "formula",
+            "sources": ["COMPUTE_CLOSE_QUARTER"],
+            "parameters": {
+                "expressionType": "SQL",
+                "fields": [
+                    {
+                        "name": "IndustryFilled",
+                        "label": "Industry Filled",
+                        "type": "TEXT",
+                        "formulaExpression": "case when (Account.Industry is null or Account.Industry = '') then 'Unknown' else Account.Industry end"
+                    }
+                ]
+            }
+        },
+        "COMPUTE_DEAL_SIZE": {
+            "action": "formula",
+            "sources": ["COMPUTE_INDUSTRY_FILLED"],
+            "parameters": {
+                "expressionType": "SQL",
+                "fields": [
+                    {
+                        "name": "DealSize",
+                        "label": "Deal Size",
+                        "type": "TEXT",
+                        "formulaExpression": "case when Amount >= 100000 then 'Large' when Amount >= 50000 then 'Medium' else 'Small' end"
+                    }
+                ]
+            }
+        },
+        "EXTRACT0": {
+            "action": "extractGrains",
+            "sources": ["COMPUTE_DEAL_SIZE"],
+            "parameters": {
+                "grainExtractions": []
+            }
+        },
+        "AGGREGATE_BY_INDUSTRY_QUARTER": {
+            "action": "aggregate",
+            "sources": ["EXTRACT0"],
+            "parameters": {
+                "aggregations": [
+                    {
+                        "name": "TotalRevenue",
+                        "label": "Total Revenue",
+                        "action": "SUM",
+                        "source": "TotalRevenue"
+                    }
+                ],
+                "groupings": ["AccountId", "Account.Name", "IndustryFilled", "CloseYear", "CloseQuarter", "DealSize"],
+                "nodeType": "STANDARD",
+                "pivots": []
+            }
+        },
+        "OUTPUT_DTS_PIPELINE": {
+            "action": "save",
+            "sources": ["AGGREGATE_BY_INDUSTRY_QUARTER"],
+            "parameters": {
+                "dataset": {
+                    "type": "analyticsDataset",
+                    "label": "DTS_PipelineByIndustry",
+                    "name": "DTS_PipelineByIndustry",
+                    "folderName": "SkillBuildInsights"
+                },
+                "fields": [],
+                "measuresToCurrencies": []
+            }
+        }
+    },
+    "ui": {
+        "nodes": {
+            "LOAD_OPPORTUNITY": {
+                "label": "Opportunity",
+                "type": "LOAD_DATASET",
+                "top": 112,
+                "left": 112,
+                "parameters": { "sampleSize": 2000 }
+            },
+            "LOAD_ACCOUNT": {
+                "label": "Account",
+                "type": "LOAD_DATASET",
+                "top": 252,
+                "left": 252,
+                "parameters": { "sampleSize": 2000 }
+            },
+            "JOIN_ACCOUNT": {
+                "label": "JOIN_ACCOUNT",
+                "type": "JOIN",
+                "top": 112,
+                "left": 392
+            },
+            "TRANSFORM0": {
+                "label": "TRANSFORM0",
+                "type": "TRANSFORM",
+                "top": 112,
+                "left": 532,
+                "graph": {
+                    "COMPUTE_TOTAL_REVENUE": { "parameters": { "type": "BASE_FORMULA_UI" } },
+                    "COMPUTE_CLOSE_YEAR": { "parameters": { "type": "BASE_FORMULA_UI" } },
+                    "COMPUTE_CLOSE_QUARTER": { "parameters": { "type": "BASE_FORMULA_UI" } },
+                    "COMPUTE_INDUSTRY_FILLED": { "parameters": { "type": "BASE_FORMULA_UI" } },
+                    "COMPUTE_DEAL_SIZE": { "parameters": { "type": "BASE_FORMULA_UI" } }
+                },
+                "connectors": [
+                    { "source": "COMPUTE_TOTAL_REVENUE", "target": "COMPUTE_CLOSE_YEAR" },
+                    { "source": "COMPUTE_CLOSE_YEAR", "target": "COMPUTE_CLOSE_QUARTER" },
+                    { "source": "COMPUTE_CLOSE_QUARTER", "target": "COMPUTE_INDUSTRY_FILLED" },
+                    { "source": "COMPUTE_INDUSTRY_FILLED", "target": "COMPUTE_DEAL_SIZE" }
+                ]
+            },
+            "AGGREGATE0": {
+                "label": "AGGREGATE0",
+                "type": "AGGREGATE",
+                "top": 112,
+                "left": 672,
+                "graph": {
+                    "EXTRACT0": null,
+                    "AGGREGATE_BY_INDUSTRY_QUARTER": null
+                },
+                "connectors": [
+                    { "source": "EXTRACT0", "target": "AGGREGATE_BY_INDUSTRY_QUARTER" }
+                ]
+            },
+            "OUTPUT_DTS_PIPELINE": {
+                "label": "OUTPUT_DTS_PIPELINE",
+                "type": "OUTPUT",
+                "top": 112,
+                "left": 812
+            }
+        },
+        "connectors": [
+            { "source": "LOAD_OPPORTUNITY", "target": "JOIN_ACCOUNT" },
+            { "source": "LOAD_ACCOUNT", "target": "JOIN_ACCOUNT" },
+            { "source": "JOIN_ACCOUNT", "target": "TRANSFORM0" },
+            { "source": "TRANSFORM0", "target": "AGGREGATE0" },
+            { "source": "AGGREGATE0", "target": "OUTPUT_DTS_PIPELINE" }
+        ],
+        "hiddenColumns": []
+    }
+}

package/skills/crm-analytics-wave-generate/examples/wdpr-skeleton.wdpr

@@ -0,0 +1,62 @@
+{
+  "runMode": "full",
+  "nodes": {
+    "LOAD_OPP": {
+      "action": "load",
+      "sources": [],
+      "parameters": {
+        "dataset": { "type": "connectedDataset", "label": "Opportunity", "connectionName": "SFDC_LOCAL", "sourceObjectName": "Opportunity" },
+        "fields": ["Id", "Amount", "CloseDate", "StageName"],
+        "mode": "SYNCED",
+        "preserveCurrencyFields": [],
+        "sampleDetails": { "type": "TopN", "sortBy": [] }
+      }
+    },
+    "COMPUTE_YEAR": {
+      "action": "formula",
+      "sources": ["LOAD_OPP"],
+      "parameters": {
+        "expressionType": "SQL",
+        "fields": [{ "name": "CloseYear", "label": "Close Year", "type": "TEXT", "formulaExpression": "date_format(CloseDate, 'yyyy')" }]
+      }
+    },
+    "EXTRACT0": {
+      "action": "extractGrains",
+      "sources": ["COMPUTE_YEAR"],
+      "parameters": { "grainExtractions": [] }
+    },
+    "AGG0": {
+      "action": "aggregate",
+      "sources": ["EXTRACT0"],
+      "parameters": {
+        "aggregations": [{ "name": "TotalAmount", "label": "Total Amount", "action": "SUM", "source": "Amount" }],
+        "groupings": ["StageName"],
+        "nodeType": "STANDARD",
+        "pivots": []
+      }
+    },
+    "OUTPUT": {
+      "action": "save",
+      "sources": ["AGG0"],
+      "parameters": {
+        "dataset": { "type": "analyticsDataset", "label": "DTS_Opportunity", "name": "DTS_Opportunity", "folderName": "MyApp" },
+        "fields": [],
+        "measuresToCurrencies": []
+      }
+    }
+  },
+  "ui": {
+    "nodes": {
+      "LOAD_OPP":    { "label": "Opportunity", "type": "LOAD_DATASET", "top": 112, "left": 112, "parameters": { "sampleSize": 2000 } },
+      "TRANSFORM0":  { "label": "TRANSFORM0",  "type": "TRANSFORM",    "top": 112, "left": 252, "graph": { "COMPUTE_YEAR": { "parameters": { "type": "BASE_FORMULA_UI" } } }, "connectors": [] },
+      "AGGREGATE0":  { "label": "AGGREGATE0",  "type": "AGGREGATE",    "top": 112, "left": 392, "graph": { "EXTRACT0": null, "AGG0": null }, "connectors": [{ "source": "EXTRACT0", "target": "AGG0" }] },
+      "OUTPUT":      { "label": "Output",      "type": "OUTPUT",       "top": 112, "left": 532 }
+    },
+    "connectors": [
+      { "source": "LOAD_OPP",   "target": "TRANSFORM0" },
+      { "source": "TRANSFORM0", "target": "AGGREGATE0" },
+      { "source": "AGGREGATE0", "target": "OUTPUT" }
+    ],
+    "hiddenColumns": []
+  }
+}

package/skills/crm-analytics-wave-generate/references/dashboard-authoring.md

@@ -0,0 +1,157 @@
+# Dashboard Authoring
+
+## Deploy-time rules
+
+The `.wdash` file contains ONLY the `state` object — no `label`, `description`, or `application` keys at root (those belong in `.wdash-meta.xml`).
+
+Critical deploy-time rules:
+- `state.dataSourceLinksInfo` must be an **object** (`{}`), not an array.
+- `state.gridLayouts[].numColumns` is `24` for modern dashboards.
+- **Widget `type` and `parameters` go in the top-level `widgets` dict, NOT in `gridLayouts`.** `gridLayouts[].pages[].widgets[]` entries hold positioning keys: `name`, `row`, `column`, `colspan`, `rowspan`, and optionally `widgetStyle`. Do NOT use `col` (singular) — that triggers `Unrecognized field "col"`.
+- Do NOT include `type` on gridLayouts widget entries — rejected with `Unrecognized field "type" (Class GridLayoutWidgetInputRepresentation)`.
+- Step `type`: use `saql` or `aggregateflex`. SAQL steps must NOT include `isGlobal`, `receiveFacet`, `datasets`, or `label`.
+- Keep widget `parameters` minimal at deploy time: `{ step }` for listselector/valuestable, `{ step, measureField }` for number, `{ step, visualizationType }` for chart. Add everything else via PATCH.
+
+## Proven-accepted PATCH fields per widget type
+
+| Widget type | Accepted in `parameters` |
+|-------------|--------------------------|
+| `number` | `step`, `measureField`, `title`, `titleColor`, `titleSize`, `numberColor`, `numberSize`, `textAlignment`, `compact`, `showActionMenu`, `exploreLink`, `tooltip: { customizeTooltip: true }`, `interactions: []` |
+| `chart` | `step`, `visualizationType`, `title` (object), `titleColor`, `titleSize`, `legend`, `trellis`, `theme`, `showActionMenu`, `exploreLink`, `interactions: []`, `dimensionAxis`, `measureAxis1` — **no `tooltip`** |
+| `listselector` | `step`, `title`, `compact`, `displayMode`, `expanded`, `exploreLink`, `filterStyle: { titleColor, valueColor }`, `instant`, `interactions: []`, `showActionMenu` |
+| `valuestable` | `step` ONLY — all styling fields rejected. Use `chart` with `visualizationType: "flatTable"` for dark theming |
+| `text` | `content` (rich text), `interactions: []` — no styling fields |
+
+**`chart` `title` object shape** (not a plain string):
+```json
+"title": { "label": "Revenue by Industry", "fontSize": 14, "subtitleFontSize": 11, "align": "left", "subtitleLabel": "" }
+```
+
+**`chart` `dimensionAxis` and `measureAxis1`** (make bars draw with labelled axes):
+```json
+"dimensionAxis": { "showTitle": false, "customSize": "auto", "showAxis": true, "title": "Industry" },
+"measureAxis1":  { "sqrtScale": false, "showTitle": false, "showAxis": true, "title": "Revenue ($)", "customDomain": { "showDomain": false } }
+```
+
+## Outer PATCH fields
+
+- `gridLayouts[i].style`: `backgroundColor`, `cellSpacingX`, `cellSpacingY`, `gutterColor`, `alignmentX`, `alignmentY`, `fit`.
+- `gridLayouts[i].pages[j].widgets[k].widgetStyle`: `backgroundColor`, `borderColor`, `borderEdges`, `borderRadius` (**integer**, e.g. `8`), `borderWidth`.
+
+**Dark theme values** (page bg `#0d1117`, card bg `#161b22`, accent `#4cc9f0`):
+```json
+"gridLayouts[0].style": { "backgroundColor": "#0d1117", "cellSpacingX": 8, "cellSpacingY": 8, "gutterColor": "#0d1117" }
+"widgetStyle": { "backgroundColor": "#161b22", "borderColor": "#30363d", "borderEdges": ["all"], "borderRadius": 8, "borderWidth": 1 }
+```
+
+## The SAQL re-encoding trap
+
+When the API stores a dashboard, it HTML-entity-encodes SAQL (e.g. `"` → `"`). Single-level encoding is normal. If you GET → PATCH without decoding, the API encodes again → `"`. After two cycles widgets render "Error" with errorCode 119 `Unexpected character '&'`.
+
+**Always decode every `state.steps[*].query` immediately after a GET, before any mutation + PATCH.**
+
+```javascript
+function decodeAll(s) {
+  let prev = null;
+  while (prev !== s) {
+    prev = s;
+    s = s.replace(/"/g, '"').replace(/'/g, "'").replace(/&/g, '&');
+  }
+  return s;
+}
+```
+
+## Dataset references in SAQL
+
+Store name-based load: `q = load "DTS_OpportunityRev"; …`. The dashboard runtime resolves the name internally.
+
+Do NOT use id/version form `q = load "0Fb.../0Fc..."` — the PATCH input rep rejects the `datasets` binding required for id-based loads, so widgets render *"To use the [0Fb...] datasets in the query, add them to the lens first."*
+
+To verify a stored name-based SAQL step: fetch → decode → **swap name for `datasetId/currentVersionId`** → POST to `/wave/query`. The `/wave/query` endpoint cannot resolve names.
+
+## KPI total — always use `group q by all`
+
+```saql
+q = load "MyDataset";
+q = group q by all;
+q = foreach q generate sum('TotalRevenue') as 'TotalRevenue';
+```
+
+`foreach` without `group by all` acts as a window function returning one row per source row.
+
+## Query bindings — selection widget driving another step's SAQL
+
+Faceting (`broadcastFacet: true` / `useGlobal: true`) is the default filter path. When a listselector must drive a **specific** SAQL filter in another step — not a global facet — use an explicit query binding.
+
+Proven pattern from working org dashboards:
+
+```saql
+q = load "DTS_PipelineByIndustry";
+q = filter q by {{column(step_industry_sel.selection, ["Industry"]).asEquality("Account.Industry")}};
+q = group q by all;
+q = foreach q generate sum('TotalRevenue') as 'TotalRevenue';
+```
+
+| Binding | Use when |
+|---|---|
+| `{{column(step.selection, ["Field"]).asEquality("TargetField")}}` | Selection should become `TargetField == value` (or `in` for multi). Empty selection is a no-op (all rows). **This is the default for a listselector driving a filter.** |
+| `{{column(step.selection, ["Field"]).asObject()}}` | Inject the selected values as a SAQL list. Empty selection can yield zero rows — prefer `asEquality` unless you need the raw list. |
+| `{{cell(step.selection, 0, "Field").asString()}}` | Single-cell string (e.g. a title). Do **not** use this as the filter itself — null selection breaks the query. |
+
+Rules:
+- The selector step aliases the field to the name used in `column(..., ["Industry"])`. If the step projects `'Account.Industry' as 'Industry'`, bind `["Industry"]`, not `["Account.Industry"]`.
+- Set `broadcastFacet: false` and `useGlobal: false` on **both** the selector step and the bound data steps. Combining faceting with an explicit binding double-filters.
+- Bindings are dashboard-runtime only. `/wave/query` cannot resolve `{{column(...)}}`. To verify a bound step: strip the `filter q by {{...}}` clause (or substitute a literal), swap the dataset name for `id/version`, then POST.
+- Store the binding in the SAQL string with raw quotes. Never HTML-encode it yourself — the API encodes on write. Always `decodeAll` before PATCH (see below).
+
+Selector step (no binding on itself):
+
+```saql
+q = load "DTS_PipelineByIndustry";
+q = group q by 'Account.Industry';
+q = foreach q generate 'Account.Industry' as 'Industry';
+q = order q by 'Industry' asc;
+```
+
+## Filter widgets — use `listselector`
+
+`toggleGroup` does not exist as a stored type. Always use `listselector`.
+
+For a measure-typed field (e.g. CloseMonth as NUMBER): use `foreach` without GROUP BY — `listselector` deduplicates internally:
+```saql
+q = load "MyDataset";
+q = foreach q generate 'CloseMonth' as 'CloseMonth';
+q = limit q 1000;
+```
+
+## Step shape that renders correctly
+
+```json
+{
+  "type": "saql",
+  "query": "q = load \"<DatasetName>\"; …",
+  "broadcastFacet": true,
+  "useGlobal": true,
+  "selectMode": "single",
+  "groups": [],
+  "numbers": [],
+  "strings": []
+}
+```
+
+Do NOT include: `datasets`, `start`, `isGlobal`, `receiveFacet`, `visualizationParameters`, `label`.
+
+## Common errors → fixes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `errorCode 264 "Classic Dashboards have been retired"` on POST | REST POST only creates legacy dashboards | Use Metadata API deploy |
+| `Unrecognized field "label"` on deploy | Top-level metadata inside `.wdash` | Move `label`, `description`, `application` to `.wdash-meta.xml` |
+| `Can not deserialize … out of START_ARRAY token` | `dataSourceLinksInfo` was an array | Change to empty object `{}` |
+| `Unrecognized field "type" (Class GridLayoutWidgetInputRepresentation)` | Widget `type` in gridLayouts entries | Move `type` + `parameters` to top-level `widgets` dict |
+| `Unrecognized field "col"` | Used `col` instead of `column` | Rename to `column` |
+| All widgets "Error" after PATCH | SAQL re-encoding | Apply `decodeAll` before every PATCH |
+| Bound step shows all rows even when a value is selected | Selector uses `broadcastFacet`/`useGlobal` *and* an explicit `{{column}}` binding, or the `column` alias doesn't match the `as 'Industry'` projection | Set both flags `false`; bind the projected alias |
+| `/wave/query` 400 on a bound step | Bindings are dashboard-runtime only | Strip `filter q by {{...}}` (or substitute a literal) before posting |
+| `Unrecognized field "datasets"` on PATCH | `state.steps[*].datasets` is output-only | Remove from PATCH body |
+| Widgets: "To use [0Fb...] datasets … add them to the lens first" | Stored SAQL uses id/version load | Switch to name-based `q = load "<DatasetName>"` |

package/skills/crm-analytics-wave-generate/references/dataset-hygiene.md

@@ -0,0 +1,27 @@
+# Dataset Hygiene and Dashboard Auditing
+
+## Finding unused dataset fields
+
+Run `scripts/find_unused_dataset_fields.js <alias> <DatasetName>`. It:
+
+1. Resolves the dataset → fetches its main XMD → enumerates `dimensions ∪ measures ∪ dates` → set of canonical field names.
+2. Pages through `GET /wave/dashboards?pageSize=200`.
+3. For each dashboard, `GET /wave/dashboards/{id}` → concatenates every `state.steps[*].query`.
+4. Keeps only dashboards whose SAQL contains `load "<DatasetName>"` (tolerates `&quot;` HTML-encoded form).
+5. Extracts every single-quoted token from SAQL, intersects with the field-name set.
+6. Outputs the unused set.
+
+**Caveats:**
+- Compound steps referencing fields with the same name across multiple datasets will look "used" against any dataset with a matching field name.
+- Aggregateflex steps store column references in a structured `columns` block, not in a SAQL `query`. The scanner only handles SAQL steps — extend the extractor for `state.steps[*].columns[*].field` if needed.
+- Dashboards in retired/archived apps still count as "users" unless you filter by folder.
+
+## Finding where a field is used
+
+Same scanner, inverted: for a single field name, list every (dashboard, step) whose SAQL token set contains it. Adapt `find_unused_dataset_fields.js` — replace the field-set intersection with a single-field membership test.
+
+## Detecting SAQL re-encoding decay
+
+Dashboards edited via PATCH without first decoding SAQL accumulate `&amp;quot;`, `&amp;amp;quot;`, etc. Detection: GET every dashboard in the target app, count occurrences of the substring `&amp;` in each `state.steps[*].query`. Anything > 0 means at least one extra encoding layer. (Single-level `&quot;` is normal and expected.)
+
+Fix: apply the `decodeAll` helper from `references/dashboard-authoring.md` to every affected step's query, then PATCH the dashboard with the decoded state.

package/skills/crm-analytics-wave-generate/references/external-data-upload.md

@@ -0,0 +1,61 @@
+# External Data Uploads (CSV → Dataset)
+
+Use this when landing a CSV into a Wave dataset without running a recipe — e.g. synthetic test data, one-off external feeds, or standing up a dashboard before recipe sources are available.
+
+## Process (4 steps)
+
+1. `POST /services/data/v66.0/sobjects/InsightsExternalData` with:
+   ```json
+   { "Format": "Csv", "EdgemartAlias": "<datasetName>", "EdgemartContainer": "<folderId>",
+     "Operation": "Overwrite", "Action": "None", "MetadataJson": "<base64 of metadata.json>" }
+   ```
+   Returns `{ id }` — the header id.
+
+2. `POST /services/data/v66.0/sobjects/InsightsExternalDataPart` for each chunk:
+   ```json
+   { "InsightsExternalDataId": "<headerId>", "PartNumber": 1, "DataFile": "<base64 of CSV bytes>" }
+   ```
+   Keep parts ≤ 8 MB.
+
+3. `PATCH /services/data/v66.0/sobjects/InsightsExternalData/<headerId>` with `{ "Action": "Process" }`. Returns 204; ingestion is queued.
+
+4. Poll: `SELECT Id, Status, StatusMessage FROM InsightsExternalData WHERE Id = '<headerId>'`. Status flow: `New` → `Queued` → `InProgress` → `Completed` | `CompletedWithWarnings` | `Failed`.
+
+## metadata.json minimum-viable schema
+
+```json
+{
+  "fileFormat": { "charsetName": "UTF-8", "fieldsDelimitedBy": ",", "linesTerminatedBy": "\n", "numberOfLinesToIgnore": 1 },
+  "objects": [{
+    "connector": "CSV",
+    "fullyQualifiedName": "<datasetName>",
+    "name": "<datasetName>",
+    "label": "<display label>",
+    "fields": [
+      { "name": "AccountId",    "fullyQualifiedName": "AccountId",    "label": "Account ID",    "type": "Text" },
+      { "name": "TotalRevenue", "fullyQualifiedName": "TotalRevenue", "label": "Total Revenue", "type": "Numeric", "precision": 18, "scale": 2, "defaultValue": "0", "format": "$#,##0.00" }
+    ]
+  }]
+}
+```
+
+## Critical rules
+
+- **Every field needs `fullyQualifiedName`** — omitting it returns `FIELD_INTEGRITY_EXCEPTION: The fully-qualified name for field [X] cannot be empty`.
+- **Field names cannot contain dots** — recipe join fields like `Account.Name` must be renamed `Account_Name`. Labels can keep the original spelling.
+- **`type`** must be `Text`, `Numeric`, or `Date`. For Numeric: supply `precision` + `scale`. For Date: `format` must be a SimpleDateFormat string (e.g. `"yyyy-MM-dd"`).
+- **CSV nulls** are empty fields — do not write the literal string `null`.
+- **Folder** = `EdgemartContainer` is the WaveApplication folder id from `GET /wave/folders`, not the folder name.
+- **Operation modes**: `Overwrite` replaces data; `Append` adds rows; `Upsert` requires `isUniqueId: true`; `Delete` removes rows matching key.
+- **A 200 on Action=Process ≠ data is queryable.** Wait for `Status = Completed`, then verify with a SAQL count query.
+
+## Common errors
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `FIELD_INTEGRITY_EXCEPTION: fully-qualified name … cannot be empty` | Missing `fullyQualifiedName` | Add to every field |
+| `Object name not allowed` / dot in name | Dataset or field name contains `.` or `-` | Use `[A-Za-z][A-Za-z0-9_]*` only |
+| `Status: Failed` referencing a specific row | CSV value doesn't parse as declared type | Check row in `StatusMessage`; ensure no currency symbols in numeric data |
+| `Status: Completed` but 0 rows | Wrong `Operation` or `numberOfLinesToIgnore` too large | Check both values |
+| SAQL `Syntax Error … as 'rows'` | `rows` is a reserved SAQL word | Use `'row_count'` or `'cnt'` as alias |
+| `Invalid group expression: <Field>` (errorCode 119) | Field is a measure (NUMBER type) in XMD | Use `case` in SAQL or change recipe to emit TEXT version |

package/skills/crm-analytics-wave-generate/references/method-decision-tree.md

@@ -0,0 +1,12 @@
+# Method Decision Tree
+
+| Goal | Use | Why |
+|------|-----|-----|
+| Create a `WaveApplication` (app/folder) | Analytics REST `POST /wave/folders` | SFDX metadata deploy for WaveApplication is finicky and almost always fails; REST works in one call |
+| Create a `WaveRecipe` that compiles and runs | Analytics REST `POST /wave/recipes?format=R3` with `recipeDefinition` in JSON body | Multipart upload creates the recipe but leaves it in `New` status with no `targetDataflowId` — it can never run |
+| Run a recipe ("Run Now") | Analytics REST `POST /wave/dataflowjobs` with `{ dataflowId: targetDataflowId, command: "start" }` | `dataflowId` is the recipe's `targetDataflowId` (02K...), never the recipe id (05v...) |
+| Upload CSV into a new or existing dataset | InsightsExternalData sObject API (header → parts → `Action=Process` → poll) | Only supported no-UI path; `sf data tree import` and generic bulk APIs don't produce Wave datasets |
+| Call REST from a script | `curl` via `execSync` with `-s -w '\nHTTP_STATUS:%{http_code}'` (no `-f`) | `-f` swallows the response body on non-2xx; the status-suffix pattern surfaces the full error message |
+| Bypass OAuth scopes for quick REST call | Apex `Http` callout via `sf apex run` using `UserInfo.getSessionId()` | Internal session bypasses External Client App scope restrictions — for diagnosis only |
+| Deploy a modern grid dashboard | Metadata API: `sf project deploy start` for `.wdash` + `.wdash-meta.xml` | `POST /wave/dashboards` only creates retired classic dashboards (errorCode 264) |
+| Enrich dashboard styling after deploy | `PATCH /wave/dashboards/{id}` with `{ state: <enriched state> }` | Deploy input rep is minimal; styling fields (`gridLayouts[].style`, `widgetStyle`) are only accepted at PATCH time |