@salesforce/afv-skills 1.59.0 → 1.61.0

package/skills/tableau-next-asset-create/references/dashboard-authoring.md

@@ -0,0 +1,302 @@
+# Dashboard Authoring — Tool Guide & Verified Payloads
+
+Load this for **Step 11** (build the dashboard). Covers dashboard creation,
+widget placement grid, metric/viz widgets, text/label widgets, and critical gotchas.
+
+> **Before placing widgets on the 48-col grid:** design the narrative and
+> visual hierarchy first — see `references/dashboard-design-principles.md`
+> (KPIs top/left, F/Z eye-path, story order: KPIs → Trends → Breakdowns →
+> Correlations). Grid placement below is the mechanics; the design doc is
+> the intent.
+
+## Contents
+
+- 1. Create the Empty Dashboard
+- 2. Grid Specification
+- 3. Editing Widgets — `edit_dashboard` (primary path)
+- 4. Gotchas Summary
+- 5. Global Filters — `add_global_filter_to_dashboard`
+- 6. Deleting a Dashboard — `delete_dashboard`
+- 7. Preflight before deleting a viz or dashboard — `list_asset_dependencies`
+- 8. Show a dashboard vs metadata-only — `render_dashboard` / `get_dashboard`
+
+---
+
+## 1. Create the Empty Dashboard
+
+Always start with an empty shell, then populate it with widgets.
+
+```jsonc
+{
+  "name": "Brightleaf_Sales_Overview",
+  "label": "Brightleaf Sales Overview",
+  "workspaceIdOrApiName": "brightleaf_demo",
+  "description": "Overview of Brightleaf sales performance by region and product",
+  "widgets": {},
+  "layouts": [{
+    "columnCount": 48,
+    "rowHeight": 20,
+    "maxWidth": 1200,
+    "style": { "backgroundColor": "#ffffff", "gutterColor": "#f3f3f3", "cellSpacingX": 4, "cellSpacingY": 4 },
+    "pages": [{ "name": "page_1", "label": "Overview", "widgets": [] }]
+  }],
+  "minorVersion": -1
+}
+```
+
+This seeded-`page_1` shell is the **default** shape — see the decision rule
+below for when `layouts: []` is the right call instead.
+
+**`workspaceIdOrApiName` is an id like `1Dyxx...` or apiName from `list_workspaces`. NOT the workspace label with spaces — that 404s.**
+
+**Silent name transforms — always read `name` back.** `create_dashboard` mutates the
+`name` you send with no warning: a duplicate name in the org gets a numeric suffix,
+non-ASCII/unicode characters are silently stripped, names past ~78-80 characters are
+silently truncated, and spaces are silently converted to underscores. Never assume
+the requested `name` was stored verbatim — read the response back before referencing
+it (e.g. in a widget's `source` or a navigation target).
+
+**Don't call `create_dashboard` with just `{name, label, workspaceIdOrApiName}`.**
+That leaks a raw Java NPE (`Cannot invoke "java.util.Map.values()" ...getWidgets()`).
+`widgets: {}` and a `layouts` value (`[]` or seeded, per the decision rule below)
+are de-facto required even when empty — never omit either.
+
+**Pick one create recipe based on what happens next — verified live
+(2026-09-13):**
+
+- **You will `edit_dashboard` immediately after — the common "create, then
+  place widgets" flow.** Seed one layout with an empty `page_1` (full `style`
+  block + `columnCount`, as in the shell above), then `edit_dashboard`.
+  `add_page`/`place_widget_on_page` operate *within* an existing layout — they
+  do not create the first one. A `create_dashboard` done with `layouts: []`
+  yields a dashboard with **no layout at all**, and the next `edit_dashboard`
+  `add_page` fails: `INVALID_INPUT: "Dashboard has no layout to add the page
+  to"`.
+- **You will NOT edit/populate the dashboard next** (e.g. handing off a bare
+  shell). `layouts: []` is fine — there's nothing to place yet anyway.
+
+If you do seed a page up front, give every layout a full `style` block and
+`columnCount` — omitting `style` at create time renders an **unstyled
+dashboard** (no crash), and omitting `columnCount` breaks grid math for every
+widget placed later.
+
+**Workspace cascade on delete.** `delete_workspace` cascade-deletes every
+workspace-asset row whose `assetUsageType="Created"`, and that delete propagates
+to the underlying asset — confirmed for `AnalyticsVisualization`, `SemanticModel`,
+AND `AnalyticsDashboard` (not just dashboards). Assets added with
+`assetUsageType="Referenced"` are NOT deleted — only their workspace association
+is removed. `create_dashboard` and `create_*_viz` each auto-create a `"Created"`
+workspace-asset row for the new asset, so any chart or dashboard authored in that
+workspace will be swept up. ALWAYS call `list_workspace_assets` first to inventory
+`Created`-typed assets before deleting a workspace — there's no undo.
+
+**Scope and response shape.** `create_dashboard` creates in the current org only —
+it does not copy a dashboard from another org. Verified live (2026-08-30): as
+observed through this tool, `create_dashboard`'s response is a **flat JSON
+object**, NOT double-wrapped. `edit_dashboard` and
+`delete_dashboard`, by contrast, ARE double-wrapped as
+`{"defaultExc": "<stringified JSON>", "responseCode": <number>}` (parse
+`JSON.parse(response.defaultExc)`; see §6 for `delete_dashboard`'s success-path
+exception). The wrapping is per-tool, don't assume it's family-wide.
+
+**`minorVersion` must be sent explicitly.** The schema shows `minorVersion:
+-1` as a default, but omitting it can surface a live client-visible error:
+`ILLEGAL_QUERY_PARAMETER_VALUE: Illegal value for query parameter
+'minorVersion': ''`. Always pass `minorVersion: -1` on `create_dashboard` (and
+on `edit_dashboard` — `edit-dashboard.md` §1).
+
+---
+
+## 2. Grid Specification
+
+The grid is **48 columns** (`columnCount: 48`), `rowHeight 20`, `maxWidth 1200`.
+Plan colspans in 48ths (a half-width chart = 24, a quarter KPI = 12).
+`columnCount` is required on every layout at create time, alongside a full
+`style` block (§1).
+
+**Always name AND label every page.** If you seed a non-empty `layouts` block
+on `create_dashboard`, each `layouts[].pages[]` entry needs both `name` (API
+id, e.g. `page_1`) and `label` (display name) set explicitly — `create_dashboard`
+does **not** auto-derive `page_N`. An omitted `name` is stored empty (any
+navigation widget targeting it by `page_N` won't resolve) and an omitted
+`label` renders a blank page tab. Set both at create time rather than fixing
+page one up later via `edit_dashboard`'s `rename_page`.
+
+---
+
+## 3. Editing Widgets — `edit_dashboard` (primary path)
+
+**Use `edit_dashboard` for all widget/page editing on an existing dashboard** —
+add, replace, move, or remove a widget of any kind (metric, visualization, text,
+button, container, filter, parameter, navigation), and add/rename/delete a
+page. It is the only supported tool for this purpose — never hand-build a
+dashboard-JSON PATCH.
+
+Full operation-type table, the widget-identity rule (`widget.name`/`widget.id`
+vs. `placement.name`), grid placement, draft-vs-persist mechanics
+(`save_dashboard`/`undo`/`discard_dashboard`), and full widget deletion via
+`remove_widget_from_dashboard` are all in **`edit-dashboard.md`**
+(task guide: `tasks/edit-dashboard.md`).
+
+---
+
+## 4. Gotchas Summary
+
+`create_dashboard` gotchas below. For `edit_dashboard` (§3, primary path)
+gotchas, see `edit-dashboard.md` §7.
+
+| Gotcha | Rule |
+|---|---|
+| Omitting `minorVersion` on `create_dashboard` | Client-visible `ILLEGAL_QUERY_PARAMETER_VALUE` on an empty value — always send `minorVersion: -1` explicitly |
+| `create_dashboard` response wrapping | Flat JSON, NOT double-wrapped (verified live) — don't apply the `defaultExc`/`responseCode` parse to it |
+| `&` in text labels | HTML-encodes to `&amp;` in round-trip — use "and" or "/" |
+| `create_dashboard` `name` mutated silently | Dup → suffix; non-ASCII stripped; ~78-80 char truncation; spaces → underscores — always read `name` back |
+| `create_dashboard` with no `widgets`/`layouts` | Leaks a raw NPE — always pass `widgets: {}` and a `layouts` value (`[]` or seeded) at minimum |
+| `add_page`/`place_widget_on_page` right after `create_dashboard` with `layouts: []` | Fails `INVALID_INPUT: "Dashboard has no layout to add the page to"` (verified live 2026-09-13) — seed one layout with an empty `page_1` in `create_dashboard` instead when you'll edit immediately (§1) |
+| Missing `layouts[].style`/`columnCount` on `create_dashboard` bulk-create | Renders an unstyled dashboard (no runtime crash at create time) — always include a full `style` block and `columnCount` |
+| Bulk-create pages with no `name`/`label` | `create_dashboard` does NOT auto-derive `page_N` — set both explicitly on every page at create time |
+| `delete_workspace` on a workspace with `Created`-typed assets | Cascades — deletes every viz/SDM/dashboard whose workspace-asset row is `assetUsageType="Created"` (`Referenced` rows only lose their association, asset itself survives); list workspace assets first |
+| `delete_visualization` / `delete_dashboard` without `list_asset_dependencies` | Preflight first (§7) — returns **counts not ids**; if `analyticsdashboard` > 0, widgets are not cleaned (`source` silently nulled) — `remove_widget_from_dashboard` first |
+| `workspaceIdOrApiName` is the workspace label with spaces | 404s — pass the id (`1Dyxx...`) or apiName from `list_workspaces`, NOT the label |
+
+---
+
+## 5. Global Filters — `add_global_filter_to_dashboard`
+
+A global filter is **dashboard-wide**, not baked into one chart — it drives every
+viz/metric widget on the dashboard that shares the filtered field's semantic model
+and object. This is a different mechanism from `create_visualization`'s own
+per-chart `filters` array (`viz-authoring.md`) or an `edit_visualization`
+`addFilter` op (`edit-visualization.md`), which each scope to one visualization
+only. Ask which the user means when it's ambiguous ("filter this chart" vs. "filter
+the dashboard").
+
+**Self-contained.** This tool builds the full filter-widget JSON and places it
+on the grid internally — no separate read/replace round trip needed. Required
+inputs: `dashboardIdOrApiName`, `semanticModelIdOrName`, `objectName`,
+`fieldName`, and a grid `placement` (48-col grid, same conventions as §2; a
+common size is full-width `colspan: 48, rowspan: 4` or half-width
+`colspan: 24, rowspan: 4`).
+
+**Value-matching rule of thumb:**
+
+- **Relative-date presets** (e.g. "default to current quarter") — pass `operator`
+  alone (`CurrentQuarter`, `CurrentMonth`, `PreviousMonth`, `LastNDays`, …); omit
+  `initialValues`.
+- **Exact/contains/range matching** — pass `operator` (`Equals`, `In`, `Contains`,
+  `GreaterThan`, …) **and** `initialValues` as a JSON array, even for one value
+  (`["West"]`, not `"West"`). Use a multi-element array for `In`.
+
+One line each: `dataType` (`Text`/`Number`/`Date`/`Boolean`/`measure`) is
+case-sensitive and defaults to `Text`; `selectionType` (`single`/`multiple`) defaults
+to `multiple`; `filterLabel` (optional display label) defaults to `fieldName`;
+`widgetName` (optional unique name) auto-generates as `filter_N` when omitted.
+A global filter is just a widget under the hood — `edit_dashboard`'s
+`remove_widget_from_page` only unplaces it; to fully remove one, use
+`remove_widget_from_dashboard` with its `widgetName` (`edit-dashboard.md` §6).
+
+---
+
+## 6. Deleting a Dashboard — `delete_dashboard`
+
+`delete_dashboard` permanently removes a dashboard. **Destructive, no undo** —
+always get explicit user confirmation first (`SKILL.md` lifecycle bullets).
+
+**Inputs:** `dashboardIdOrApiName` only (the id or apiName from
+`list_dashboards`/`browse_data_assets`). Scope is the current org only.
+
+**Response shape — verified live (2026-08-30):** double-wrapped as
+`{"defaultExc": "<stringified JSON>", "responseCode": <number>}`. On the
+success path (`responseCode: 204`), `defaultExc` is an **empty string** (`""`)
+— NOT the literal string `"204"`, and not JSON-parseable either way. Branch on
+`responseCode === 204` for success; don't try to parse `defaultExc` on that
+path.
+
+**Not idempotent.** A second `delete_dashboard` call against an
+already-deleted (or never-existent) id returns a 404:
+`RESOURCE_NOT_FOUND: "We couldn't find dashboard."` Treat that specific error
+as success-equivalent if your flow might double-call delete.
+
+**No cascade to referenced assets.** Deleting a dashboard does not delete the
+visualizations/metrics it displayed — only the dashboard and its widget
+placements. Compare `delete_workspace`'s cascade behavior (§1), which is a
+different, broader operation.
+
+---
+
+## 7. Preflight before deleting a viz or dashboard — `list_asset_dependencies`
+
+Call this before `delete_visualization` or `delete_dashboard`. Distinct from
+`list_semantic_model_dependencies` (in-model calc/metric graph; see
+`sdm-tool-reference.md`).
+
+- **`assetId` is the 18-char id only** — an apiName returns a misleading
+  workspace error.
+- Returns **COUNTS by type**, not dependent ids/names — you cannot name which
+  dashboards will break. `totalCount`/`nextOffset` page the queried-asset list,
+  not the dependents.
+- Show the counts, then **end the turn and wait for a new unambiguous yes**.
+  A prior "delete" in the same request is a plan, not confirmation.
+- `delete_visualization` does NOT clean dashboard widgets. If
+  `dependentAssets.analyticsdashboard` is nonzero, N dashboards will keep a
+  broken widget (`source` silently nulled). Prefer
+  `remove_widget_from_dashboard` first (`edit-dashboard.md` §6) for a clean
+  remove.
+
+---
+
+## 8. Show a dashboard vs metadata-only — `render_dashboard` / `get_dashboard`
+
+**If the user wants to see, open, view, display, render, bring up, pull up,
+load, or look at a dashboard** (its charts, filters, or layout) — including
+when they name or id a dashboard and want to see it — call `render_dashboard`.
+That is the dashboard analog of `get_visualization` for
+charts. **`get_dashboard` does not render.**
+
+Do **not** call `get_dashboard` just because the skill already uses it for
+`edit_dashboard` prep. Metadata-only is for inspect / `edit_dashboard` prep.
+Current org only.
+
+### `render_dashboard` — inline render
+
+Retrieves the dashboard's full metadata **bundled with its referenced
+assets** (semantic models and visualizations) so visualization / filter /
+parameter widgets can render immediately — no extra per-asset fetches.
+
+**Required inputs** (live sidecar — always send all four flags):
+
+- `dashboardIdOrApiName` — id or apiName from `list_dashboards` or
+  `browse_data_assets`
+- `addVisualization=true` — so visualization tiles can render
+- `addSdm=true` — so filter / parameter widgets that need SDM metadata can
+  render
+- `showDraft=true` — include an in-progress `edit_dashboard` draft;
+  `get_dashboard` will not show that draft
+- `minorVersion=-1` — latest **Salesforce API** minor version, **not** a
+  dashboard revision
+
+**Optional:** `pageName` (page GUID), `customViewId`, `height` (viewport
+pixels — when passed, only assets visible within that height are included).
+
+**Returns:** `{dashboard, bundledAssets}`. `dashboard` is the full metadata
+(layout, widgets, owning workspace, `url`). `bundledAssets` is a map of
+asset id → referenced semantic model / visualization. Read them at
+`response.dashboard` and `response.bundledAssets`.
+
+### `get_dashboard` — metadata only (cheaper, no bundled assets)
+
+Use when you need `label` / `widgets` / `layout` / owning workspace
+programmatically, to diff two dashboards, or to prepare an `edit_dashboard`
+batch. Do **not** use it when the intent is to *see* the dashboard — for that,
+call `render_dashboard` above.
+
+**Inputs:** `dashboardIdOrApiName`. Optional `minorVersion` is the Salesforce
+API version (e.g. `67.42`), **not** a dashboard revision — invalid values
+produce `Invalid version`.
+
+**Returns:** fields **directly** on the response (`label`, `widgets`,
+`layout`, `folder`, `url`) — flat, like `create_dashboard`; unlike
+`edit_dashboard` / `delete_dashboard`, which double-wrap (§6, `edit-dashboard.md`
+§1). `url` is a canonical **external**
+Analytics-app link — it does not render the dashboard inline. For inline
+rendering, call `render_dashboard`.

package/skills/tableau-next-asset-create/references/dashboard-design-principles.md

@@ -0,0 +1,352 @@
+# Dashboard Design Principles — Supported Practices Mapped to MCP Tools
+
+Load this alongside `viz-authoring.md` (Step 10) and `dashboard-authoring.md`
+(Step 11). This file covers the **design layer** — narrative, visual
+hierarchy, naming, field selection, color, filters, and the data-presence
+gate — translated from universal dashboard design best practices to what the
+`tableau-next-pilot` MCP tools **actually** expose.
+
+> **No named templates/patterns exist.** The MCP surface is a small set of
+> generic primitives: `create_visualization` (`marks.panes.type` ∈ `Bar`,
+> `Line`, `Circle`, `Square`, `Text`, `Donut`; `layout` ∈ `Vizql`, `Radial`,
+> `Table`), a raw 48-column dashboard grid (`create_dashboard` +
+> `edit_dashboard`'s `upsert_*_widget`/`place_widget_on_page` batch),
+> `add_global_filter_to_dashboard`,
+> and the `list_/get_semantic_model_*` discovery tools. Every principle below
+> is achieved by combining these primitives by hand — never invent a template,
+> script, or param name that isn't in `viz-authoring.md` §11/§12 or
+> `dashboard-authoring.md`.
+
+## Contents
+
+- 1. Think Like a Business User (before any `create_*` call)
+- 2. Design the Narrative Before Picking Charts (REQUIRED)
+- 3. Visual Storytelling Flow — KPIs → Trends → Breakdowns → Correlations
+- 4. Visual Hierarchy — F-Pattern, Z-Pattern, Progressive Disclosure, Color, White Space
+- 5. Business-Question → Chart-Type Mapping
+- 6. Naming Conventions
+- 7. Field Selection Priority
+- 8. Color Encoding — Real Mechanism, Not `color_dim`/`stack_dim`
+- 9. Filters — Dimensions Not Measures
+- 10. Data-Presence Gate — Hard Stop Before Any Viz
+- 11. Dashboard Quality Checklist (MCP Reality)
+- Not supported by the tableau-next-pilot MCP (do not attempt)
+
+---
+
+## 1. Think Like a Business User (before any `create_*` call)
+
+Before calling `create_visualization` or `create_dashboard`, answer three
+questions in your own reasoning — no tool enforces this:
+
+1. **What question does this chart answer?** If you can't state it in one
+   sentence, don't build it.
+2. **What action will the viewer take from this?** A chart with no
+   actionable follow-up is decoration.
+3. **Can a non-technical user read every label?** No raw field apiNames, no
+   `_Clc`/`_mtc` suffixes, no bare object names.
+
+This discipline feeds directly into `create_visualization`'s `label`/`title`
+and the dashboard's `label` — pull field labels from `list_semantic_model_dimensions`
+/ `list_semantic_model_measures` (their `label`, not `fieldName`), and cross-check
+against the SDM's own `description` via `get_semantic_model`. This is pure
+pre-authoring judgement; nothing downstream validates it for you.
+
+---
+
+## 2. Design the Narrative Before Picking Charts (REQUIRED)
+
+Before the first `create_visualization` call, write out — even briefly:
+
+- The business questions the dashboard must answer.
+- The logical flow between them (what should the eye see first, second, third).
+- Friendly names for every field you intend to use.
+- Which dimensions are actually meaningful (not IDs, not descriptions).
+- What action the viewer takes after seeing each section.
+
+This is a hard **gate on Step 9** in SKILL.md — do not call
+`create_visualization` until `run_semantic_query` (or `run_query`) has
+returned real, non-empty rows for every source you plan to chart (§9 below).
+The narrative is realized entirely through **intentional sequencing** of
+`create_visualization` calls and widget placement — there is no
+narrative/flow object to configure.
+
+---
+
+## 3. Visual Storytelling Flow — KPIs → Trends → Breakdowns → Correlations
+
+There is no flow abstraction in the MCP. Realize the sequence by widget type
+and grid row, top to bottom:
+
+| Story beat | MCP realization | Placement guidance |
+|---|---|---|
+| **KPIs** | `edit_dashboard`'s `upsert_metric_widget` + `place_widget_on_page` (`parameters.metricOption.{sdmApiName, sdmId}`; `source` optionally references the metric) | Row 0, spanning the top band |
+| **Trends** | `create_visualization` with `marks.panes.type: "Line"` | Immediately below the KPI band |
+| **Breakdowns** | `create_visualization` with `marks.panes.type: "Bar"` (plain, stacked, or Donut for <5 categories) | Below trends |
+| **Correlations** | `create_visualization` with `marks.panes.type: "Circle"` (scatter) | Bottom of the grid |
+
+Sequence widgets top-to-bottom by **ascending `placement.row`** on the
+48-column grid — that ascending-row order *is* the story order. There is no
+server-side flow validation; if you place the scatter chart at `row: 0` and
+the KPIs at `row: 40`, the story reads backwards with no warning.
+
+---
+
+## 4. Visual Hierarchy — F-Pattern, Z-Pattern, Progressive Disclosure, Color, White Space
+
+No `f_layout` / `z_layout` pattern objects exist. Build the eye-path by hand
+with `placement.{row,column,rowspan,colspan}` on the 48-column grid
+(`rowHeight: 20`, `maxWidth: 1200`).
+
+**F-pattern (metrics-left/top-heavy scan):**
+
+```jsonc
+// KPI band across the top
+{ "row": 0,  "column": 0,  "rowspan": 8,  "colspan": 12 }  // metric 1
+{ "row": 0,  "column": 12, "rowspan": 8,  "colspan": 12 }  // metric 2
+{ "row": 0,  "column": 24, "rowspan": 8,  "colspan": 12 }  // metric 3
+{ "row": 0,  "column": 36, "rowspan": 8,  "colspan": 12 }  // metric 4
+// Primary trend, full width, second scan line
+{ "row": 8,  "column": 0,  "rowspan": 18, "colspan": 48 }
+// Secondary breakdowns, left-weighted third scan line
+{ "row": 26, "column": 0,  "rowspan": 16, "colspan": 24 }
+{ "row": 26, "column": 24, "rowspan": 16, "colspan": 24 }
+```
+
+**Z-pattern (left→right, then diagonal down to left→right again):**
+
+```jsonc
+{ "row": 0,  "column": 0,  "rowspan": 8,  "colspan": 24 }  // top-left
+{ "row": 0,  "column": 24, "rowspan": 8,  "colspan": 24 }  // top-right
+{ "row": 8,  "column": 0,  "rowspan": 18, "colspan": 24 }  // bottom-left
+{ "row": 8,  "column": 24, "rowspan": 18, "colspan": 24 }  // bottom-right
+```
+
+**Progressive disclosure:** put the single most important KPI/chart at
+`row: 0, column: 0` with the largest `colspan`/`rowspan`; secondary detail
+(tables, drill-down breakdowns) go further down the grid. There is no
+drill-down/expand mechanism — "progressive disclosure" here just means
+"important things occupy the first screen's worth of rows."
+
+**Color consistency:** the same category must map to the same color across
+every chart on the dashboard. The only lever is the `Color` encoding
+fieldKey in `marks.panes.encodings` — pick the *same underlying dimension*
+(same `objectName`+`fieldName`) for the Color encoding on every chart that
+breaks down by that category. There is no shared palette/legend registry;
+consistency is achieved by field-binding discipline, not a setting.
+
+**White space:** don't tile every grid cell. Leave gaps between widget
+groups (skip a row or two between `placement.row` bands) and set
+`layouts[].style.cellSpacingX` / `cellSpacingY` (verified default: `4`) on
+the dashboard's `style` block — see `dashboard-authoring.md`. Overcrowding
+the 48-column grid (i.e. every row fully packed edge-to-edge) is a real
+readability failure with no tool-level guard; watch it yourself.
+
+---
+
+## 5. Business-Question → Chart-Type Mapping
+
+Every row maps to an achievable `marks.panes.type` / `layout` combination —
+no named templates. See `viz-authoring.md` §2–3 for the full decision matrix
+and verified payloads; summarized here with the MCP-native mechanism:
+
+| Business question | Data pattern | `marks.panes.type` / `layout` | Mechanism |
+|---|---|---|---|
+| Trending over time | Date + measure | `Line` / `Vizql` | Date on columns with `DateTruncMonth` (Continuous); measure on rows |
+| Trend by category | Date + measure + dim | `Line` / `Vizql` | + `Color` encoding on the breakdown dimension |
+| Best/worst performers | Dim + measure | `Bar` / `Vizql` | Server auto-sorts descending; override with `sortIntent` |
+| Composition (<5 categories) | Dim (<5 vals) + measure | `Donut` / `Radial` | Measure on **`Angle`** encoding (not `rows`); dim on `Color` |
+| Composition (≥5 categories) | Dim (≥5 vals) + measure | `Bar` / `Vizql` | Donut is unreadable beyond ~4 slices |
+| Breakdown by two dimensions | 2 dims + measure | `Bar` / `Vizql` | + `Color` on 2nd dim + `stack: {isAutomatic:false, isStacked:true}` |
+| Compare multiple measures | Dim + 2+ measures | `Bar` / `Vizql` | `MeasureNames`/`MeasureValues` synthetic fields, or both measures in `columns` |
+| Performance hotspots | 2 dims + measure | `Square` / `Vizql` | Two dims on rows/columns; measure on `Color` encoding |
+| Correlation | 2 measures | `Circle` / `Vizql` | X-measure on columns, Y-measure on rows; point dim on `Color`/`Detail` |
+| Detailed rankings | Multiple dims + measures | `Text` / `Table` | Dims in `groups` (outer→inner), measures in `rows` |
+| YoY comparison | Date + measure + year | `Line` / `Vizql` | `DatePartMonth` on axis, `DatePartYear` on `Color` — period overlay, not a continuous timeline |
+
+**Map (point/geographic) and Flow (Sankey) are not on this table because
+they are unsupported** — no matching mark type exists. See the closing
+section for fallbacks.
+
+---
+
+## 6. Naming Conventions
+
+**The mechanical rules — suffix stripping (`_Clc`/`_mtc`/`_MTC`/`_CLC`),
+≥3-word business-friendly titles, never exposing a raw suffixed apiName like
+`Region4`/`Amount7` — live in `viz-authoring.md` §4. Follow them.** The
+design-layer points on top of those mechanics:
+
+- **Pull display labels from the SDM's own `label`** (via
+  `list_semantic_model_dimensions` / `list_semantic_model_measures`, or
+  `get_semantic_model`) — there is no `sdm_fields[field]['label']` accessor —
+  and cross-check the intent against the SDM `description`. The label should
+  answer the business question, not just rename the field.
+- **Read the transformed name back.** `create_dashboard` and
+  `create_visualization` auto-transform the `name`/apiName you send
+  (spaces → `_`, truncation, unicode stripped) — after creation, read back
+  the actual stored `name` rather than assuming your input string survived
+  unchanged.
+
+---
+
+## 7. Field Selection Priority
+
+**The priority ladder (CLC/calculated → meaningful categorical → geographic/org
+→ name fields → avoid generic text → never ID fields), the cardinality
+thresholds (≤4 Donut / 5–50 Bar / 50+ Top-N), and the CLC + `UserAgg`
+no-double-aggregation rule all live in `viz-authoring.md` §5 and §7.** The
+design-layer framing on top of those mechanics:
+
+- Field selection is a **judgement call, not an enforced check** — nothing
+  downstream stops you from charting an ID field or a raw description, and
+  there is no `recommend_diverse_chart_types()` scoring function. Apply the
+  ladder yourself when choosing among fields returned by
+  `list_semantic_model_*`.
+- **Prefer CLC business-ready fields** precisely because they encode the
+  business definition — discover them via
+  `list_semantic_model_calculated_measures` /
+  `list_semantic_model_calculated_dimensions` before falling back to raw
+  fields.
+- Binding note: a calculated measure takes `fieldName` only (**omit
+  `objectName`** — including it on a calculated measure throws
+  `UNKNOWN_EXCEPTION`) with `function: "UserAgg"`.
+
+---
+
+## 8. Color Encoding — Real Mechanism, Not `color_dim`/`stack_dim`
+
+*(Encoding mechanics and the verified stacked-bar / `colorScale` payloads are
+in `viz-authoring.md` §6 and §11 — this section covers the design intent and
+the named-parameter myths.)*
+
+**`color_dim` and `stack_dim` do not exist as parameters anywhere in the MCP
+surface.** There is no automatic coloring for "templates when 2+ dimensions
+are present" — nothing is automatic. Color is always an explicit encoding
+entry:
+
+```jsonc
+"marks": {
+  "panes": {
+    "type": "Bar",
+    "encodings": [{ "type": "Color", "fieldKey": "<dim_field_key>" }]
+  }
+}
+```
+
+- **Stacked bar** is NOT a `stack_dim` param — it is `type: "Bar"` +
+  a `Color` encoding on the second dimension + an explicit
+  `stack: { "isAutomatic": false, "isStacked": true }` block in `marks.panes`.
+- **Any chart with a second dimension available** — add it as a `Color`
+  encoding by hand. When 2+ dimensions exist and you skip this, the chart
+  silently stays single-series; nothing warns you.
+- **Diverging color scale** for signed / around-a-target measures (profit
+  variance, YoY change): set `"colorScale": "Diverging"` on the
+  Color-encoded measure's field binding. This is a real, verified param —
+  use it only when the measure is genuinely centered on zero or a target;
+  on all-positive data it misleads.
+
+Cross-chart color coordination (same category → same color everywhere) is a
+manual field-binding discipline (§4 above), not a dashboard-level setting.
+
+---
+
+## 9. Filters — Dimensions Not Measures
+
+**Filter on dimensions, never on measures**, use business-friendly labels,
+avoid ID fields, and prefer filter fields that also appear as encodings in
+the vizzes on the same dashboard (so the filter visibly affects what the
+user is looking at).
+
+Two mechanisms, both real:
+
+1. **Per-viz filters** — `create_visualization`'s `filters[]` array:
+   `{ "fieldKey": ..., "type": "Dimension", "include": [...] }` (or
+   `exclude`) for categorical filters; `ValueRange`/`DateRange` for
+   continuous fields. A filter on a raw field is a WHERE (row filter); a
+   filter on an aggregated measure becomes a HAVING (group filter) — the
+   bucket is derived from the field, not chosen by you.
+2. **Global dashboard filters** — `add_global_filter_to_dashboard`, which
+   constructs the full filter-widget JSON and places it in one call
+   (self-contained — no separate read/replace round trip). Required
+   inputs: `dashboardIdOrApiName`, `semanticModelIdOrName`, `objectName`,
+   `fieldName`, `placement`. Set `filterLabel` explicitly for a
+   business-friendly display name (defaults to the raw `fieldName` if
+   omitted — exactly the kind of technical-name leak §6 warns against).
+
+**Always look up `objectName` — never guess it.** There is no
+`sdm_fields[field]['objectName']` accessor. `objectName` is the field's
+owning SDM data-object apiName, discovered via
+`list_semantic_model_data_objects`; it is a **required** param on
+`add_global_filter_to_dashboard`. Calculated fields have no owning object —
+omit `objectName` for them in `create_visualization` (same rule as §7).
+
+---
+
+## 10. Data-Presence Gate — Hard Stop Before Any Viz
+
+**Confirm rows exist before building anything.** This is Rule 1 of the
+parent skill (SKILL.md) and the primary defense against empty dashboards.
+
+- `run_query` — `SELECT COUNT(*) AS n FROM <table>__dll` (or `__dlm`/`__dlc`)
+  for a raw-table presence check.
+- `run_semantic_query` — for a model that traverses relationships, confirm
+  the query returns non-empty rows before charting from it (this doubles as
+  the Step 7 model-validation check in SKILL.md).
+
+**If the result is zero rows or a "table does not exist" error, STOP.** Do
+not call `create_visualization`. Report the empty/unmaterialized source to
+the user and offer an alternative source or metric — see
+`empty-source-handling.md` for exact wording.
+
+**`query_data.py --count` and `lib.query.assert_has_rows` do not exist** —
+those are constructs from an external scripting workflow, which has no
+equivalent MCP tool. The gate is real; those helpers are not. Use
+`run_query`/`run_semantic_query` directly.
+
+---
+
+## 11. Dashboard Quality Checklist (MCP Reality)
+
+**Business clarity**
+- [ ] Every chart title states the business question it answers (≥3 words, no jargon)
+- [ ] Field labels come from SDM `label` (via `list_semantic_model_*`), not raw apiNames
+- [ ] No `_Clc`/`_mtc`/`_MTC`/`_CLC` suffixes or raw apiNames visible to the end user
+- [ ] KPIs → Trends → Breakdowns → Correlations story order reflected in ascending `placement.row`
+
+**Visual design**
+- [ ] Metrics placed top/left (row 0) per the F-pattern or Z-pattern grid coordinates in §4
+- [ ] Same dimension used for `Color` encoding across every chart that breaks down by that category
+- [ ] Grid not overcrowded — deliberate empty rows/`cellSpacingX/Y` between widget groups
+- [ ] Donut used only for dimension cardinality < 5; Bar used at ≥ 5
+
+**UX**
+- [ ] Every `add_global_filter_to_dashboard` call has an explicit business-friendly `filterLabel`
+- [ ] Filters target dimensions, never measures; avoid ID fields
+- [ ] Filter fields also appear as an encoding in at least one on-dashboard viz where practical
+
+**Technical**
+- [ ] `run_query`/`run_semantic_query` confirmed non-empty rows before any `create_visualization` call (§10)
+- [ ] CLC/calculated measures use `function: "UserAgg"`, never re-aggregated with `Sum`/`Avg`
+- [ ] `objectName` omitted for calculated measures/dimensions; looked up (never guessed) for raw fields and global filters
+- [ ] Bar charts left to auto-sort descending, or `sortIntent` set deliberately
+- [ ] YoY comparisons use `DatePartMonth` + `DatePartYear` period overlay, not a continuous timeline
+- [ ] Viz created before the dashboard widget references it by `source.{id,name}` (creation order matters)
+- [ ] Text/label widgets added via `edit_dashboard`'s `upsert_text_widget` + `place_widget_on_page` — the only supported path
+- [ ] A `401`/auth-failure on any `create_*`/`update_*`/`run_*` call is treated as an expired org auth token or MCP connection — refresh org auth and reconnect the MCP server, then retry the same call; do not misdiagnose it as an empty-source or malformed-payload error
+
+---
+
+## Not supported by the tableau-next-pilot MCP (do not attempt)
+
+| Best-practices item | Why unsupported | Nearest achievable alternative |
+|---|---|---|
+| Map / geomap (point map, lat+lon+measure) | No map/geo mark type; lat/lon not routed | `Bar` chart by Region/Territory dimension |
+| Flow / Sankey (`flow_sankey`, `flow_package_*`, `flow_simple_*`) | No flow/sankey mark type | Two `Bar` charts showing source→destination volumes separately |
+| Conversion funnel | No funnel mark type | Sorted `Bar` by stage order; communicate each stage's count in the title/description |
+| Dot matrix (2 dims + 2 measures) | No dot-matrix mark | `Circle` scatter (2 measures) or ranked `Bar` |
+| Nightingale rose (measure-driven radius) | Radial layout supports `Donut` marks only — no measure-driven radius | Horizontal `Bar` |
+| Radial spoke bars | Not available in current tools | `Bar` |
+| Radial heatmap (2 ring dims + slice dim + measure) | Not available | `Square` heatmap (2D grid) |
+| Map/Flow color variants (`geomap_*` encodings, `flow_uniform_fill`, node-size color rules) | No map or flow/sankey mark exists to carry them | N/A — see map/flow fallbacks above |
+| Named layout patterns (`f_layout`, `z_layout`, `performance_overview`) with fixed filter/metric/viz counts | The patterns and their auto-select logic do not exist — only the raw 48-column grid | Hand-place widgets using the F-pattern/Z-pattern grid coordinates in §4; filter/metric/viz counts are an authoring choice, not a pattern constraint |