@salesforce/afv-skills 1.58.0 → 1.60.0

package/skills/tableau-next-asset-create/references/semantic-query-and-enrichment.md

@@ -0,0 +1,355 @@
+# Semantic Query & Enrichment Reference
+
+Field-shape matrix, aggregation mapping, and worked payloads for querying an
+SDM and enriching it with calculated fields and metrics. Substitute apiNames
+from `list_*` — do not copy example names into a live call.
+
+> **Our MCP is NOT the REST gateway.** Public/Cursor "semantic-query" guides
+> target `POST /services/data/vXX/semantic-engine/gateway` with a **camelCase**
+> body (`tableField`, `rowGrouping: true`, `semanticAggregationMethod`). The
+> MCP `run_semantic_query` tool takes a **proto-shaped snake_case** body
+> (`table_field`, `grouping: "ROW_GROUPING"`, `semantic_aggregation_method`).
+> Do not copy camelCase payloads — they fail. Use the shapes here.
+
+## Contents
+
+- run_semantic_query — top-level body (`semantic_context` nested there)
+- Field-shape matrix
+- options block
+- Reading the response
+- Query recovery
+- Worked query (verified): sum of a measure by a joined dimension
+- Detail rows (`detailed_rows: true`)
+- Filtered query (`filter.binary_predicate`)
+- Enrichment — calculated dimension
+- Enrichment — calculated measure
+- Enrichment — metric (named, time-bound KPI)
+
+## run_semantic_query — top-level body
+
+```jsonc
+{
+  "semanticModelApiName": "<SDM apiName>",   // NOT semanticModelId (deprecated here)
+  "source": "tableau-next-pilot-mcp",
+  "dataspace": "default",                     // omit unless multi-dataspace
+  "structuredSemanticQuery": { "fields": [...], "options": {...} }
+  // OR structuredMetricQuery — mutually exclusive; do not send both
+}
+```
+
+Only `fields`, `filter` XOR `flatten_filter` (never both), `options`,
+`semantic_context`, `aggregate_filter`, `parameters` are valid keys inside
+`structuredSemanticQuery`. Putting `limit`, `sort_orders`, or `row_grouping`
+at that level fails with `Cannot find field: <key>`. Prefer
+`options.limit_options.limit` + `sort_orders` for top-N over proto
+`top_n_filter`.
+
+Pass **ONE** of `structuredSemanticQuery` (recommended) **OR**
+`structuredMetricQuery` (alternative) — mutually exclusive dispatch paths.
+Do not send both. Outer-request `context` (`timezone`, `locale`) is distinct
+from per-query `semantic_context`. Most queries omit `semantic_context` — the
+engine picks defaults. Pass it when fiscal-year filters or timezone-sensitive
+date math matters:
+
+```jsonc
+"semantic_context": {
+  "timezone": { "id": "America/Los_Angeles" },
+  "locale":   { "code": "en_US" }
+}
+```
+
+Query is org-level / SDM-level — it does **NOT** take a `workspaceId`. Any SDM
+visible via `list_semantic_models` is queryable regardless of workspace.
+
+Treat any **2xx** as success (the wrapper has been observed to return 201).
+Provisioning is gated on `orgHasDataCloudReportingEnabled` OR
+`orgHasSemanticQuery` — a permission error is a **provisioning gap**, not a
+caller payload bug.
+
+## Field-shape matrix
+
+| Field kind | expression | grouping / aggregation |
+|---|---|---|
+| **Raw dimension** | `{ "table_field": { "name": "<dimApiName>", "table_name": "<objApiName>" } }` | `"grouping": "ROW_GROUPING"` |
+| **Raw measure** | `{ "table_field": { "name": "<measApiName>", "table_name": "<objApiName>" } }` | `"semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_<AGG>"` |
+| **Calculated dimension** | `{ "semantic_field": { "name": "<calcDimApiName>" } }` | `"grouping": "ROW_GROUPING"` |
+| **Calculated measure** | `{ "semantic_field": { "name": "<calcMeasApiName>" } }` | `"semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG"` (for AVG/ratio/COUNTD expressions) |
+
+- `table_name` MUST be the SDM **data-object apiName** from
+  `list_semantic_model_data_objects` — NOT the `__dll`/`__dlm` source name
+  (that → `Failed to resolve table`).
+- `name` MUST be the **suffixed** field apiName from
+  `list_semantic_model_dimensions` / `list_semantic_model_measures`.
+- `semantic_field` is ONLY for **calculated** SDM fields. It takes ONLY
+  `name` (no `table_name`). Using `semantic_field` for a raw/physical column
+  fails `Failed to resolve semantic field <name>...`. Rule of thumb:
+  calculated → `semantic_field`; physical column → `table_field`.
+- `alias` convention: `"<objApiName>.<fieldApiName>"` for table fields,
+  `"<apiName>"` for semantic (calculated) fields.
+- A third shape, on-the-fly `calculated_field`, exists; prefer a pre-defined
+  calc on the model over inventing one in the query.
+- **In an aggregated query, every measure needs `semantic_aggregation_method`.**
+  A measure with no aggregation is treated as a detail row and errors
+  `Detail Rows with Metric must have the corresponding dimension` — this fires
+  on the **MISSING aggregation**, NOT a missing dimension (adding
+  `ROW_GROUPING` does NOT satisfy it). A grouping dimension is optional
+  (measure-only = grand total). **Exception:** `options.detailed_rows: true` is
+  the one shape where omitting the aggregation method is valid.
+
+### Aggregation method enum
+
+Valid query-time suffixes only: `SUM`, `AVG`, `COUNT`, `MIN`, `MAX`,
+`UNIQUE_COUNT`, `USER_AGG`. Map the model's `aggregationType` enum value (left)
+to the query-time suffix (right): `Sum→SUM`, `Average→AVG`, `Count→COUNT`,
+`CountDistinct→UNIQUE_COUNT`, `Min→MIN`, `Max→MAX`. Note the model enum uses
+`Average` (not `Avg`), and there is no `SEMANTIC_AGGREGATION_METHOD_COUNTDISTINCT`
+at query time — `CountDistinct` maps to `SEMANTIC_AGGREGATION_METHOD_UNIQUE_COUNT`,
+a distinct enum value from plain `COUNT` (`COUNT` counts all rows; `UNIQUE_COUNT`
+counts distinct values). A calculated measure whose expression already
+aggregates uses `USER_AGG`.
+
+## options block
+
+```jsonc
+"options": {
+  "limit_options": { "limit": 10 },
+  "sort_orders": [ { "simple_sort_order": { "sort_by_field_alias": "<alias>", "sorting_order": "DESC" } } ],
+  "grand_total": true        // OR "detailed_rows": true — never both
+}
+```
+
+- Aggregate query (≥1 measure/calc measure): `grand_total: true` adds a total
+  row. Detail query (dimensions only): `detailed_rows: true`. (These two
+  option flags are documented independently in the schema; whether they
+  combine is **unverified** — the worked query below used neither.)
+- Aggregate queries should include ≥1 dimension with `ROW_GROUPING` (a
+  measure-only query returns a single grand-total row — valid for "total X").
+
+## Reading the response
+
+Double-wrapped: parse `JSON.parse(response.defaultExc)`. Treat any **2xx** as
+success (wrapper has been observed to return 201). Then:
+`status === "SUCCESS"`; `queryResults.queryMetadata.fields[<alias>].placeInOrder`
+indexes into each `queryResults.queryData.rows[i].values[]`. A `null` grouping
+value is the unmatched/blank bucket (verified: a `null` region row appeared
+alongside the real groups). `status != "SUCCESS"` is a failure — read
+`errorMessage`. `status != "SUCCESS"` with an **empty** `errorMessage` is an
+unknown failure — ask the user to check the org's CDP / Reporting
+configuration. A confirmed **permission** error is the provisioning-gap
+signal (`orgHasDataCloudReportingEnabled` / `orgHasSemanticQuery`), not a
+caller payload bug.
+
+**Display rules.** Render rows as a markdown table for ≤20 rows, else row
+count + first 10 + "… and N more". Order by `placeInOrder`. Do **NOT** echo
+the raw `queryResults` JSON. Surface `errorMessage` verbatim on failure.
+
+## Query recovery
+
+| Signal | Cause / fix |
+|---|---|
+| `Failed to resolve table` | Used `__dll`/`__dlm` instead of the SDM data-object apiName |
+| `Failed to resolve semantic field` | Used `semantic_field` for a raw/physical column — use `table_field` |
+| `Cannot find field: <key>` | Non-proto top-level key (`limit`/`sort_orders`/`row_grouping` outside `options`) |
+| `Query returns more records than allowed. The limit is: 5000` | Add `limit_options` or aggregate |
+| `USER_ILLEGAL_ARGUMENT_RESOLVE_ENTITY_ERROR` | Typo / wrong table / physical column as `table_field.name` |
+| `Detail Rows with Metric must have the corresponding dimension` | Missing `semantic_aggregation_method` on a measure (not a missing dimension) |
+| Permission error | `orgHasDataCloudReportingEnabled` / `orgHasSemanticQuery` provisioning gap |
+| `status != SUCCESS` with empty `errorMessage` | Unknown failure — check org CDP / Reporting configuration |
+
+## Worked query (verified): sum of a measure by a joined dimension
+
+```jsonc
+{
+  "semanticModelApiName": "ZZ_Trap_base0",
+  "source": "tableau-next-pilot-mcp",
+  "structuredSemanticQuery": {
+    "fields": [
+      { "expression": { "table_field": { "name": "region18", "table_name": "Accounts" } },
+        "alias": "Accounts.region18", "grouping": "ROW_GROUPING" },
+      { "expression": { "table_field": { "name": "Amount7", "table_name": "Opportunities" } },
+        "alias": "Opportunities.Amount7",
+        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM" }
+    ],
+    "options": { "limit_options": { "limit": 10 },
+      "sort_orders": [ { "simple_sort_order": { "sort_by_field_alias": "Opportunities.Amount7", "sorting_order": "DESC" } } ] }
+  }
+}
+```
+
+Returned per-region sums by traversing the Accounts↔Opportunities join.
+
+## Detail rows (`detailed_rows: true`)
+
+The one shape where a measure may omit `semantic_aggregation_method`. Do not
+also set `grand_total`. Field names below are illustrative — copy apiNames from
+`list_*`.
+
+```jsonc
+{
+  "semanticModelApiName": "Sales_Performance_SDM",
+  "structuredSemanticQuery": {
+    "fields": [
+      { "expression": { "table_field": { "name": "Account_ID", "table_name": "Account" } },
+        "alias": "account_id" },
+      { "expression": { "table_field": { "name": "Account_Name", "table_name": "Account" } },
+        "alias": "account_name" },
+      { "expression": { "table_field": { "name": "Revenue", "table_name": "Account" } },
+        "alias": "revenue" }
+    ],
+    "options": {
+      "detailed_rows": true,
+      "limit_options": { "limit": 20 }
+    }
+  },
+  "dataspace": "default"
+}
+```
+
+## Filtered query (`filter.binary_predicate`)
+
+`filter` XOR `flatten_filter` — never both. Count-distinct uses
+`SEMANTIC_AGGREGATION_METHOD_UNIQUE_COUNT` (not `COUNTDISTINCT`).
+
+```jsonc
+{
+  "semanticModelApiName": "Sales_Performance_SDM",
+  "structuredSemanticQuery": {
+    "fields": [
+      {
+        "expression": {
+          "table_field": { "name": "Account_ID", "table_name": "Account" }
+        },
+        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_UNIQUE_COUNT",
+        "alias": "distinct_accounts"
+      }
+    ],
+    "filter": {
+      "binary_predicate": {
+        "left_expression": { "table_field": { "name": "Segment", "table_name": "Account" } },
+        "binary_operator": "BINARY_OPERATOR_EQUALS",
+        "right_expression": { "string_expression": "Enterprise" }
+      }
+    }
+  }
+}
+```
+
+## Enrichment — calculated dimension
+
+`add_semantic_model_calculated_dimension`. TuA expression with **bracketed
+qualified references** `[ObjApiName].[FieldApiName]` (suffixed apiNames). Bare
+identifiers fail with "Missing reference". Verified:
+
+```jsonc
+{
+  "modelApiNameOrId": "ZZ_Trap_base0",
+  "apiName": "Region_Upper",
+  "label": "Region Upper",
+  "expression": "UPPER([Accounts].[region18])",
+  "dataType": "Text",
+  "displayCategory": "Discrete"
+}
+```
+
+Row-level expression → server sets `level: "Row"` automatically.
+
+- Calculated-measure TuA conditionals are **simple CASE only**:
+  `CASE <expr> WHEN <value> THEN <result> ... [ELSE <result>] END`.
+  Searched CASE (`CASE WHEN <condition> THEN ...`) and `IF(condition, then, else)`
+  are rejected (`Syntax Error - no viable alternative at input 'WHEN'` /
+  `mismatched input ','`). Key the CASE off a value, not a boolean predicate.
+  Block `IF`/`ELSEIF`/`END` and `IIF(...)` are **pending live verification** —
+  do not use them in a calc measure or dimension until confirmed.
+
+## Enrichment — calculated measure
+
+`add_semantic_model_calculated_measure`. Verified (level-aware AVG):
+
+```jsonc
+{
+  "modelApiNameOrId": "ZZ_Trap_base0",
+  "apiName": "Avg_Deal_Size",
+  "label": "Avg Deal Size",
+  "expression": "AVG([Opportunities].[Amount7])",
+  "dataType": "Number",
+  "aggregationType": "UserAgg",      // required when the expression aggregates
+  "displayCategory": "Continuous"
+}
+```
+
+- Expression that already aggregates (`AVG`, `SUM/COUNT`, `COUNTD`) → must use
+  `aggregationType: "UserAgg"`; a bare `Average`/`Sum` is rejected with
+  "AggregativeFunction-level calculated fields require UserAgg". Server sets
+  `level: "AggregateFunction"`.
+- Row-level arithmetic (`[O].[Profit] / [O].[Sales]`) → `aggregationType: "Auto"`.
+- The server overlays defaults that were not passed (`decimalPlace: 2`,
+  `directionality: "Up"`, `sentiment`, `totalAggregationType: "Sum"`,
+  `level: "Row"`, `shouldTreatNullsAsZeros: false`) — set them explicitly to
+  override.
+- No arithmetic check: `/ 0` is accepted and fails only at query time.
+- Do not set `externalLevel` or `externalConnectionApiName` unless connecting
+  to an external definition.
+- Updates are **full PUT**: GET via `get_semantic_model_calculated_measure`,
+  then send the complete object. Omitted fields reset to those defaults.
+
+To query a UserAgg calc measure, reference it as a `semantic_field` with
+`SEMANTIC_AGGREGATION_METHOD_USER_AGG` (verified returning per-group averages).
+
+## Enrichment — metric (named, time-bound KPI)
+
+`add_semantic_model_metric`. `label` is required. **Create a metric by default
+when the request implies a tracked business number** (revenue, win rate,
+engagement, count over time) **and a business-meaningful event date exists to
+anchor it** — not only on explicit demand. Set EXACTLY ONE shape on
+`measurementReference` (and on `timeDimensionReference`). Verified shape:
+
+```jsonc
+{
+  "modelApiNameOrId": "Pipeline_Analysis",
+  "apiName": "Total_Pipeline",
+  "label": "Total Pipeline",
+  "measurementReference": { "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Amount7" } },
+  // OR a derived measure: "measurementReference": { "calculatedFieldApiName": "Avg_Deal_Size" }
+  "timeDimensionReference": { "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Created_Date14" } },
+  "aggregationType": "Sum",   // matches the RAW-measure branch (sum of Amount). For the
+                              // calculatedFieldApiName branch, set the calc field's own
+                              // aggregation (e.g. "UserAgg" for Avg_Deal_Size) — do NOT Sum an average.
+  "timeGrains": ["Day", "Week", "Month", "Quarter", "Year"],
+  "insightsSettings": {       // REQUIRED — omit identifyingDimension and the metric UI crashes
+    "identifyingDimension": {
+      "identifierDimensionReference": {
+        "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Opportunity_Id5" }
+      }
+    }
+  },
+  "additionalDimensions": [   // must include identifyingDimension (and every insights/filter field)
+    { "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Opportunity_Id5" } }
+  ]
+}
+```
+
+Do not ship this block without `insightsSettings`, and always mirror
+`identifyingDimension` into `additionalDimensions` (create fails with
+`Insight dimension (...) is missing from the metric additional dimensions`).
+Nouns, extra `additionalDimensions`, and `insightsDimensionsReferences` live in
+`ingest-and-metric-gotchas.md` §B and `build-workflow.md` Step 8.
+
+- `aggregationType` enum values: `Sum`, `Average`, `Count`, `CountDistinct`,
+  `Min`, `Max`, `UserAgg`, `Auto`, etc. (note `Average`, not `Avg`).
+- `fieldApiName` on BOTH references is the **suffixed** apiName **from the
+  object that owns the field**. A date field from a *different* object is
+  rejected with `Table field with table name: (X) and field name: (Y) was not
+  found in the model` (the exact error hit when an Accounts date dim was passed
+  for an Opportunities reference). Read each object's own dimensions with
+  `list_semantic_model_dimensions` and match the owner.
+- The time dimension must be a **business-meaningful** `Date`/`DateTime`
+  dimension (`dataType: "Date"`) — a real event date (created/close/order/
+  activity), NOT a `cdp_sys_PartitionDate`, `*_SourceVersion`, or load
+  timestamp. A metric on a plumbing date is worse than no metric.
+- With `filters`, also pass `filterLogic` (e.g. `"1"` / `"1 AND 2"`) and
+  fully-qualify filter `fieldName` as `<tableApiName>.<fieldApiName>`.
+- Skip the metric only if no meaningful date dimension resolves.
+- Pass **ONE** of `structuredSemanticQuery` **OR** `structuredMetricQuery` on
+  `run_semantic_query` — mutually exclusive. Prefer `structuredMetricQuery`
+  when querying a named metric (see `build-workflow.md` Step 9). Do not
+  reconstruct the metric from raw fields unless no metric exists.

package/skills/tableau-next-asset-create/references/shared-gates.md

@@ -0,0 +1,322 @@
+# Shared Gates (G1–G8) — the single source of truth
+
+Every task guide under `references/tasks/` opens with a **gate header** that
+names the gates it must assert (e.g. "Required: G1, G3, G7"). This file is where
+each gate's *authoritative rule → how to check it → what to do on failure* lives —
+in exactly one place. A guide names a gate and may give a **one-line, non-normative
+reminder** so it reads on its own; it must **not** restate the authoritative rule.
+If a gate's rule ever changes, it changes **here** — the guide reminders are
+pointers, not a second copy to keep in sync.
+
+**Legend used in the guide headers:** ● = required · ◐ = conditional (only if the
+action touches >1 object, adds a new join, or references a formula/field it did
+not just read back).
+
+**Tool-name convention (single source of truth).** The MCP tools are exposed
+under a `tableau-next-*` server. Everywhere in this skill — gates, router, task
+guides — tool names are written **bare** (e.g. `add_semantic_model_relationship`)
+for readability. Invoke each under whatever name your client advertises for that
+server's tool (Claude Code, for example, exposes it as
+`mcp__tableau-next-pilot-production__add_semantic_model_relationship`); match the
+advertised name rather than hand-constructing one. Guides cite this line; they do
+not restate it.
+
+## Contents
+
+- G1 — MCP-server-connected precondition
+- G2 — Data presence is the gate (row-count > 0, re-verified at use time)
+- G3 — Never invent an apiName (read it back via `list_*`)
+- G4 — No island objects
+- G5 — AI-readiness metadata (+ coverage checks)
+- G6 — Data-understanding profiling
+- G7 — Query-returns-real-data validation
+- G8 — Narrative-design-first (decision #1 — scoped)
+- G-notes (shapes cited by the gates, kept here so guides don't re-type them)
+
+---
+
+## G1 — MCP-server-connected precondition
+
+**RULE.** Every action in this skill drives a Tableau Next MCP server; without one
+connected there is nothing to call. Never fabricate a tool call or a result
+against a server that is not there.
+
+**CHECK.** Confirm the available tools include one prefixed `mcp__tableau-next-*__`
+(e.g. `mcp__tableau-next-pilot-production__browse_data_assets`,
+`mcp__tableau-next-self-service__create_semantic_model`). Server names vary
+(`tableau-next-pilot-*`, `tableau-next-self-service`, …) — match the
+`tableau-next` stem, not an exact name.
+
+**ON FAILURE.** If NO such tool is present, **STOP.** Do not attempt the workflow,
+do not describe payloads as if you had run them, and never invent tool
+calls/results/IDs. Tell the user the skill requires a connected Tableau Next MCP
+server, name concrete examples (`tableau-next-pilot-*`, `tableau-next-self-service`),
+and ask them to connect one and re-invoke. This is the difference between "I built
+your dashboard" and a hallucinated transcript of one.
+
+> G1 is universal, so it is asserted **once in the router** (`SKILL.md`) and
+> inherited by every entry point — including non-build standalone intents ("add a
+> metric" with no server still STOPs). No guide re-implements it, but every guide
+> depends on it.
+
+---
+
+## G2 — Data presence is the gate (row-count > 0, re-verified at use time)
+
+**RULE.** Never build on an object with zero rows. A source with zero rows
+produces an empty visualization no matter how many fields it has, and no join
+fixes it. **Field-richness is not data-presence** — a canonical-looking DMO can
+have 66 fields and 0 rows. Row presence is verified **at use time**, not assumed
+"populated once."
+
+**CHECK.** For every *externally discovered* candidate, run `SELECT COUNT(*)`
+(or equivalent) before adding it to a model and before charting it.
+`count > 0` = usable; `count = 0` = empty (see G-note below); a
+`table "X__dlm" does not exist` / `42P01` error = unmaterialized, which is
+distinct from empty — see `empty-source-handling.md`.
+
+- **Ingest post-condition:** a freshly created file DLO has 0 rows until
+  `run_data_stream` runs. Run the stream, then wait until the DLO is Active
+  (`ingest-and-metric-gotchas.md` §A). Row presence is a stand-in for ready, not
+  the same thing.
+- **Self-created mapping — query readiness, not status:** for a DMO you just
+  created and mapped in this same flow, **`get_dlo_to_dmo_mapping_status`
+  `ACTIVE` is not a readiness signal.** It means mapping metadata deployed
+  off-core; it does **not** mean `<dmo>__dlm` exists. Poll `run_query`
+  `SELECT 1 FROM <dmo>__dlm LIMIT 1` (or `SELECT COUNT(*)`). `42P01` /
+  "table does not exist" = NOT-READY — keep polling. Any success, including
+  `COUNT = 0`, = READY (table is queryable; proceed to SDM). Use
+  `get_dlo_to_dmo_mapping_status` to inspect the mapping and to detect
+  `ERROR` / `INACTIVE` — not as the query-readiness gate. Keep the
+  discovered-source hard gate as-is: `COUNT = 0` on a pre-existing object
+  still means do not build on it.
+- **`isEnabled: false` right after DMO creation is normal.** Check it, but do
+  not gate on it and do not wait for it before mapping — expected transient
+  state, not a readiness signal.
+
+**ON FAILURE.** If a *discovered* candidate has zero rows, refuse to build on it
+and surface it to the user; do not put a measure/dimension from an unverified
+object on a viz. If no discovered candidate has rows, STOP and tell the user the
+sources are empty rather than shipping a blank dashboard. Do not treat
+`COUNT = 0` on a DMO you just mapped in this flow as that failure (READY). Do
+not treat `42P01` on that DMO as "unmaterialized, exclude" — keep polling.
+
+---
+
+## G3 — Never invent an apiName (read it back via `list_*`)
+
+**RULE.** The server mutates field/object apiNames on bind — bulk import
+(`shouldIncludeAllFields: true`) suffixes every apiName differently per object
+(`Region__c` → `Region4`; `account_id__c` → `account_id5` on one object,
+`account_id3` on another). Do **not** use that flag for model-level bind
+(deprecated). Nested explicit fields (`semanticDimensions[]` /
+`semanticMeasurements[]` on `create_semantic_model` /
+`add_semantic_model_data_object`) come back as the apiNames you set.
+
+**CHECK.** Before typing any apiName you did not read back this session, call the
+relevant `list_*` tool (`list_semantic_model_dimensions` / `_measures` /
+`_data_objects` / `_calculated_*` / `_metrics`) and copy the exact stored value.
+In a relationship, use the semantic apiName with `leftFieldType: "TableField"`
+(not the raw `dataObjectFieldName`).
+
+**ON FAILURE.** If you are about to write an apiName you have not read back this
+session, STOP and read it back first. Never assume the two sides of a join share a
+suffix.
+
+---
+
+## G4 — No island objects
+
+**RULE.** In a model with two or more objects, every object must participate in at
+least one relationship. (This is secondary to G2: it does not catch a single empty
+object — G2 does.)
+
+**CHECK.** After adding objects, confirm every object is on at least one
+relationship. The gate fires once the model has ≥2 objects; a newly added object
+must not be left an island.
+
+**ON FAILURE.** Add the missing relationship(s) — validated by G7 — before
+declaring the model done. Do not set `queryUnrelatedDataObjects: "Exception"` and
+then query across unjoined objects (it throws, not warns).
+
+---
+
+## G5 — AI-readiness metadata (+ coverage checks)
+
+**RULE.** Populate AI-readiness metadata on every component you create. Agents
+consume the semantic layer in priority order — **metrics first, then calculated
+fields, then raw fields** — so a well-enriched metric set matters more to answer
+quality than raw field coverage. The full checklist, description-quality guide,
+and `businessPreferences` examples live in `ai-readiness.md`; this gate is the
+enforceable summary.
+
+**CHECK — metadata each created component must carry:**
+
+- **`description`** on the model, each data object, each calculated dimension,
+  each calculated measure, and each metric. Missing descriptions are the top AI-
+  readiness defect. Custom objects/fields require a clear 1–2 sentence description
+  (business context, how it is used, any values with specific meaning); for
+  standard Salesforce objects/fields, only enhance the default — never contradict
+  it.
+- **`primaryNameField`** on each `add_semantic_model_data_object` — the original
+  (pre-suffix) display-name column. **Known server bug:** the field registry is
+  empty at create time, so setting it at create fails with `"<field> does not
+  exist in <object> fields"` regardless of import mode. Document the missing
+  `primaryNameField` as a known gap.
+- **`sentiment`** on directional calculated measures and metrics.
+- **`businessPreferences`** on the model — free-text; set ≥1 statement of what
+  the model tracks and any domain terminology. **Read** with
+  `get_semantic_model_business_preferences` (`includeModelContent=false`).
+  **Write** with `update_semantic_model_business_preferences` (full replacement
+  of `# `-prefixed lines; empty string clears; omit the field to leave
+  unchanged; send only `businessPreferences`). Fallback: set at create or via
+  `update_semantic_model`. Details: `ai-readiness.md`.
+- **`agentEnabled: true`** on the model — gates whether AI agents can use it.
+  `create_semantic_model` does **not** expose it (server default `false`); set it
+  via an immediate `update_semantic_model` after creation.
+- **Label / type / role accuracy:** object-name + field-label unambiguously
+  identify the field's role; date columns are `Date`/`DateTime` (not `Text`);
+  numeric columns are measures, categorical/text/date are dimensions; a numeric
+  identifier is a **dimension**, not a measure.
+- **apiName permanence:** model/object/calc-field apiNames cannot be edited after
+  creation — choose them descriptively (`Gross_Margin_Pct`, not `Calc3`); the only
+  fix is delete-and-recreate.
+- **Ambiguity discipline:** differentiate similar fields in name, description, and
+  purpose; never copy-paste descriptions. Watch synonyms (two names, one concept →
+  remove one; when asked to create two fields with the same/equivalent formula,
+  treat as a synonym — declare one canonical, decline the other or ask) and
+  homonyms (one column serving two business dates → two calc dimensions with
+  distinct labels + explicit descriptions). Omit niche/redundant fields rather
+  than leaving them undescribed.
+- Bulk-imported fields (`shouldIncludeAllFields: true`) carry no descriptions and
+  get unpredictable apiName suffixes — do **not** use this for model-level bind
+  (deprecated). Prefer **nested explicit fields** on
+  `create_semantic_model` / `add_semantic_model_data_object`
+  (`shouldIncludeAllFields: false`) so descriptions, types, and clean apiNames
+  are set at creation. Include join-key fields in those arrays. Reserve
+  `add_semantic_model_dimension` / `_measure` for adding a single extra field
+  to an already-bound object. Backfill missing descriptions via sparse
+  `update_semantic_model_dimension` / `_measure` — these are sparse
+  (unlike metric / calc-measure / relationship, which are full PUT). **`isVisible`
+  is NOT preserved:** omitting it silently resets a hidden field to
+  `isVisible: true`. Always `list_*` first and echo the current `isVisible` and
+  `dataObjectFieldName` (omitting `dataObjectFieldName` sends null and
+  `SEMANTIC_FIELD_NOT_VALID`). Do not send description-only. Shape:
+  `sdm-tool-reference.md`.
+
+**CHECK — pre-creation coverage checks (before adding enrichment):**
+
+- **Calculated dimension:** MUST call `list_semantic_model_calculated_dimensions`
+  first, to check for overlapping coverage of the same source field.
+- **Calculated measure:** MUST call **both**
+  `list_semantic_model_calculated_measures` **and**
+  `list_semantic_model_metrics` first. Use `aggregationType: "UserAgg"` (not
+  `Auto`) when the expression already aggregates (`AVG`, `SUM/COUNT`, `COUNTD`).
+- **Metric (decision #3 — parity resolution):** MUST call
+  `list_semantic_model_metrics` first to check that an equivalent metric does not
+  already exist (metrics had no pre-creation coverage check historically; this
+  gate adds one for parity with calc dimensions/measures). A metric additionally
+  requires `insightsSettings.identifyingDimension`, a concrete `aggregationType`
+  (**never `Auto`** — rejected: *"The aggregation type (Auto) is not allowed for
+  metric aggregation"*), counting via a **numeric field + `Count`** (not a
+  dimension/Primary Key — pointing `measurementReference` at a Primary Key is rejected), and a
+  **full-PUT `insightsSettings`** on every `update_semantic_model_metric` (it is a
+  full PUT; omitting `insightsSettings` nulls it and crashes the metric UI).
+
+**ON FAILURE.** Do not declare a model AI-ready on metadata completeness alone —
+always recommend the Semantic Model AI Optimization similarity scan (Semantic
+Model Builder UI) before handoff; `modelHealth: Low` flags ambiguous components.
+Add the missing metadata / run the missing coverage check before proceeding.
+
+---
+
+## G6 — Data-understanding profiling
+
+**RULE.** Understand the data before you model it — there is no natural-language
+query layer here to infer meaning for you. This applies even over an **already-
+built** model you do not yet understand; it does NOT drag in Step 0 ingest or the
+large-flat-file protocol on a pre-existing model.
+
+**CHECK.** Profile the five things before choosing calc fields, metrics, or charts
+(`data-understanding.md:33-41`): **grain, field roles, cardinality, additivity,
+date roles.** For a large/wide/cryptic flat file, first run the infer-first
+variant (`infer_object_schema` without loading the file into context, decode the
+column-naming grammar, elicit the genuinely ambiguous columns, then verify one
+known number with `run_query` after ingest — `large-flat-file-handling.md`).
+
+**ON FAILURE.** Without this, you ship the populated-but-confidently-wrong result
+that passes a "does it return rows?" check: an ID summed as a measure, a snapshot
+inflated by its date count, a metric anchored on a load/system timestamp instead
+of a business-event date, a 100×-off measure that profiled perfectly. Do not
+model or metricize until grain + additivity + the business-event date are known.
+
+---
+
+## G7 — Query-returns-real-data validation
+
+**RULE.** A query that returns rows is the proof the model actually works. A join
+that matches ~0 rows is as broken as no join at all.
+
+**CHECK.** Run `run_semantic_query` (snake_case proto body — see G-note) and
+confirm real rows come back: before charting (Step 10), after adding a
+relationship (validate the join key with a real JOIN row-count), and at model
+validation (Step 7). For a dashboard, the widget's underlying query must return
+real rows first (transitive: a dashboard is only as valid as its widgets).
+
+**ON FAILURE.** If the query returns empty (or a join matches ~0 rows), do NOT
+build the viz/dashboard — STOP, treat the join/source as broken, and fix or
+surface it.
+
+---
+
+## G8 — Narrative-design-first (decision #1 — scoped)
+
+**RULE.** Design the analytical story before dropping charts.
+(`dashboard-design-principles.md:41-56`.)
+
+- **Dashboards (full narrative — REQUIRED):** order the story KPIs → trends →
+  breakdowns → correlations; KPIs top/left on the F/Z eye-path; business-friendly
+  labels; chart-type diversity. This is MANDATORY for any dashboard build.
+- **Single standalone viz (light "chart analytical intent" variant — decision
+  #1):** for one chart with no dashboard, the full dashboard narrative is NOT
+  required. State the chart's analytical intent — what question this one chart
+  answers and why this chart type fits the field roles (trend/breakdown/
+  correlation/KPI) — then create it. Do NOT invent a dashboard around a single-viz
+  ask.
+
+**CHECK.** Before the first `create_visualization`: if the ask is a dashboard,
+confirm the full narrative order; if the ask is a single chart, confirm a stated
+chart intent. Match chart type to what each field is showing — do not default
+every widget to a bar chart.
+
+**ON FAILURE.** If you are about to jump straight into chart calls with no stated
+intent (single viz) or no narrative (dashboard), STOP and design first.
+
+---
+
+## G-notes (shapes cited by the gates, kept here so guides don't re-type them)
+
+- **`run_semantic_query` body is snake_case proto** (`table_field`, `grouping`,
+  `semantic_aggregation_method`) — REST-gateway camelCase examples fail. Prefer an
+  existing metric / calc measure over reconstructing an aggregation inline. Full
+  shape: `semantic-query-and-enrichment.md`.
+- **Ingest mapping:** file-upload DLOs **and** DMOs use `category: "Other"`;
+  DLO→DMO mapping field dev names carry a literal `__c` on **both** sides.
+  DLO Active → DMO Ready still wait on status. Mapping **query** readiness is
+  `run_query` against `<dmo>__dlm` (`42P01` keep polling; `COUNT = 0` is READY).
+  `get_dlo_to_dmo_mapping_status` `ACTIVE` is metadata only. Connection ingest
+  (Snowflake / …) is the same tail after `list_connections` —
+  `ingest-and-metric-gotchas.md` §C. Full chain: `ingest-and-metric-gotchas.md`
+  §A.
+- **Dashboard widget editing** goes through `edit_dashboard`'s atomic
+  `upsert_*_widget` + `place_widget_on_page` batch — the only supported path.
+  Stored text labels must not contain `&` (HTML-encodes to `&amp;`). Full
+  mechanics: `edit-dashboard.md`.
+- **Dashboard save never auto-persists** — the objective-9 analog for
+  dashboards. `edit_dashboard` stages an unsaved draft by default (top-level
+  `autosave`); a `save_dashboard` op persists it (standalone, or after other
+  mutations in the same batch), but only call `save_dashboard` on the user's
+  explicit confirmation given *after* they've
+  seen the draft — even if the original request already said "save it" in the
+  same message as the edit. Same rule, same rationale, as `edit_visualization`
+  → `update_visualization` (objective 9, `edit-visualization.md` §8).