@salesforce/afv-skills 1.58.0 → 1.60.0

package/skills/tableau-next-asset-create/references/sharing-and-promotion.md

@@ -0,0 +1,306 @@
+# Sharing and promotion/reuse — payloads and gotchas
+
+Load this from `tasks/share-asset.md` or `tasks/promote-or-reuse.md`. Not a
+first hop.
+
+Principal lookup, access-level rules, safe share mutation, and the Reuse /
+Promotion request lifecycle live here once. Task guides stay thin.
+
+The MCP tools are namespaced per server — names here are bare; use whichever
+server prefix is connected.
+
+## Contents
+
+Intent → heading:
+
+- Resolve a recipient / `recordId` / share row → Share: principal lookup
+- `accessType` / `owner` / `viewer` / group vs user → Share: permission matrix
+- Personal Org share vs production → Share: Personal Org
+- Duplicate / partial batch / silent 204 / last owner → Share: safe mutation
+- `defaultExc` vs empty 204 / error array → Share: response wrap
+- Reuse vs Promotion, poll fields, list filters → Promote: request lifecycle
+- Package URL, `sf` CLI, git/`gh` PR → Promote: pull-request recovery
+
+---
+
+## Share: principal lookup
+
+**Resolve the recipient before `add_asset_share`.** Call
+`search_users_and_groups` first. Pass the query as `usersAndGroupsQueryInput`
+(not a bare top-level `searchTerm`). Each result item's `id` is the
+`userOrGroupId` to pass.
+
+- `searchTerm`: **Minimum 2 characters**. A single character is rejected (not
+  "few results"). Matching is **case-insensitive**.
+- Results interleave users and groups in `items`. Paginate with independent
+  `nextUserOffset` and `nextGroupOffset` — do not add `items.length` to a
+  single offset.
+- `useAutoSuggest` defaults to `false`; typeahead is opt-in.
+- `recipientSearchTerm` on `list_asset_shares` is a case-insensitive
+  **substring** on display name / username. **No minimum length**; blank
+  values are ignored. Do not treat it as the same rule as `searchTerm`.
+
+**`recordId` is the asset's Salesforce record ID**, not its `apiName` or label.
+Obtain it from `get_dashboard`, `get_visualization`, `list_workspaces`, or
+`get_semantic_model`. An id that is not a known asset type (dashboard,
+workspace, visualization, semantic model) returns `INVALID_INPUT`. Missing
+entity-level view permission → `ACCESS_DENIED`.
+
+**`list_asset_shares`:** do not pass `setupObjectType` — the asset type is
+inferred from the `recordId` prefix.
+
+- `limit` Defaults to **10**. No enforced maximum. Paginate; a first page is
+  not the full recipient list.
+- `orderBy` is only `CreatedDate` (default) or `UserDisplayName`. Anything
+  else errors.
+- `sortOrder` is case-sensitive: only the exact string `"ASC"` is ascending.
+  `"asc"` (or anything else) silently falls back to descending.
+- `filterByRecipientType` `Group` maps internally to both Group and Queue.
+- Callers who are not an owner or manager of the asset get a **filtered view**
+  (owner-level shares plus their own entry) with no indication that other
+  rows were hidden.
+- `ownerCount` is always the unfiltered total, even when `filterByAccessType`
+  or `limit` narrows `recordAccessMappings`.
+- Shares for deleted users/groups are silently omitted (no tombstone).
+
+**Existing shares (update / remove):** `list_asset_shares` first, then use the
+`userOrGroupId` on each entry. `update_asset_share` **Does not remap** ids —
+pass the listed (shadow) value. A prod-sourced add-time id **will not match**
+and the update **fails** — that is not the remove path's HTTP 204 silent
+no-op.
+
+---
+
+## Share: permission matrix
+
+`accessType` allowed values **vary by** `setupObjectType`. An unsupported
+combination returns `INVALID_INPUT`. `commenter` and `manager` are **never**
+valid for any asset type.
+
+| `setupObjectType` | Production | Notes |
+|---|---|---|
+| `analyticsvisualization` | `viewer` only | Personal Org writes: `ACCESS_DENIED` (workspace only) |
+| `analyticsdashboard` | `viewer` only | Personal Org writes: `ACCESS_DENIED` (workspace only) |
+| `analyticsworkspace` | `viewer`, `editor`, `owner` | Personal Org: `viewer`, `editor` (not `owner`) |
+| `semanticmodel` | `viewer`, `editor`, `owner` | Personal Org writes: `ACCESS_DENIED` (workspace only) |
+
+**Groups cannot be `owner`** on any asset type → `INVALID_INPUT`.
+
+`applicationDomain` is required on each `accessRequestItems` entry and must
+literally be `"Tableau"`.
+
+`add_asset_share` and `update_asset_share` take **top-level** parameters
+alongside `recordId` — do not nest them in a `body` wrapper.
+
+Reference shape (substitute ids from `list_*` / `search_users_and_groups`):
+
+```json
+{
+  "recordId": "<18-char asset id>",
+  "accessRequestItems": [
+    {
+      "userOrGroupId": "<id from search_users_and_groups>",
+      "setupObjectType": "analyticsdashboard",
+      "accessType": "viewer",
+      "applicationDomain": "Tableau"
+    }
+  ]
+}
+```
+
+---
+
+## Share: Personal Org
+
+**Writes** (`add_asset_share`, `update_asset_share`, `remove_asset_share`): only
+`analyticsworkspace`. Any other `setupObjectType` returns `ACCESS_DENIED`
+(`You can only modify sharing for workspaces in a Personal Org.`). The call
+is rejected on asset type before `accessType` is checked — a personal-org
+dashboard or visualization is not a `viewer` share.
+
+**Group sharing is not supported** in Personal Orgs. Recipients must be
+individual users. `ALL_USERS` as the group id returns `ACCESS_DENIED`.
+
+**Reads:** listing shares is not restricted to workspaces — you can list shares
+on dashboards, visualizations, and models there even though you cannot add /
+update / remove them.
+
+**Search:** `search_users_and_groups` **does not fail** in a Personal Org; it
+returns the same results as production, and you may call either server's tool.
+Only **user** results are usable as share recipients there (see group rule).
+Do not skip to a "production-only" search on the belief that personal-org
+search always fails.
+
+**IDs:** `add_asset_share` stores a local **shadow ID**. `list_asset_shares`
+returns that shadow on `userOrGroupId` and `userOrGroup.id`. Use the shadow
+with `update_asset_share` and `remove_asset_share`. For a user who is **not
+yet** in the personal org, pass the prod-sourced id from
+`search_users_and_groups` into **add** — no shadow ID exists yet for that user.
+Do **not** keep the prod id for remove: that call returns HTTP 204 and the
+share stays. The same prod id on `update_asset_share` **fails** (no remap,
+not a silent 204). List after every remove.
+
+---
+
+## Share: safe mutation
+
+Confirm recipient + asset + `accessType` before add or update. Confirm before
+remove — the user **loses access immediately**.
+
+- **`sendNotificationToRecipients`:** optional; emails the recipient. The grant
+  still takes effect without it.
+- **Duplicate add:** that item fails with `DUPLICATE_VALUE` in
+  `failedRecordShares`; other items in the same request can still succeed.
+  Always inspect `failedRecordShares` on an otherwise successful response.
+- **Partial update:** same `failedRecordShares` rule.
+- **No existing share on update:** a **multi-item** batch reports
+  `RESOURCE_NOT_FOUND` per item in `failedRecordShares`. A **single-item**
+  request instead fails the call with top-level
+  `RESOURCE_UPDATE_FAILURE_UNPROCESSABLE`. Verify the row via `list_asset_shares`
+  before a one-item update.
+- **Invalid id format on update:** `fails the entire batch` with
+  `INVALID_INPUT` and `failedRecordShares` empty — not a per-item failure.
+- **Minimum owner:** the API keeps **at least one owner**. Downgrading or
+  removing the last owner → `INVALID_INPUT`.
+- **Cannot remove your own share** → `INVALID_INPUT`. The API checks own share before
+  the minimum-owner rule, so the last owner who is also the caller sees the
+  own-share error.
+- **Remove id mismatch / missing row:** HTTP 204 silently (looks like
+  success) with **no error**. In a Personal Org, a prod-sourced add-time id
+  is this silent no-op — the share remains. Verify with `list_asset_shares`
+  before and after; 204 is not proof the row is gone.
+- **Conversation visualizations** (`creationSource = CONVERSATION`): add and
+  list GET return `INVALID_INPUT` when the ephemeral viz sharing gate is on.
+
+To **revoke access entirely**, use `remove_asset_share` — `update_asset_share`
+only changes `accessType`.
+
+---
+
+## Share: response wrap
+
+`add_asset_share`, `update_asset_share`, and `search_users_and_groups`
+double-wrap as `{"defaultExc": "<stringified JSON>", "responseCode": <number>}`.
+Parse `JSON.parse(response.defaultExc)` (same pattern as
+`sdm-tool-reference.md` Response double-wrap).
+
+`remove_asset_share` does **not**. Success is an empty body (HTTP 204). Failure
+is a raw **JSON array** (`[{"errorCode": "...", "message": "..."}]`).
+
+`list_asset_shares` is unwrapped.
+
+---
+
+## Promote: request lifecycle
+
+`create_reuse_promotion_request` is one tool for two directions — meaning flips.
+Pass the create fields as **flat top-level params** (`requestType`, `assetId`,
+`label`, `workspaceIdOrApiName`, `requesterComment`) — there is **no**
+`dataAssetRequestInput` (or any other) body wrapper; the schema is
+`additionalProperties: false` and rejects one. Create `requestType` is
+`Reuse`/`Promotion` (capitalized). `list_promotion_reuse_requests` uses
+lowercase `reuse` (case-insensitive); the create response also shows
+`reuse` | `promotion`.
+
+| `requestType` | `assetId` | `workspaceIdOrApiName` |
+|---|---|---|
+| Reuse | prod asset to copy | Personal Org **destination** workspace |
+| Promotion | Personal Org asset to package | Personal Org workspace **containing** the asset |
+
+`workspaceIdOrApiName` is an id or true apiName, **NOT the workspace label**
+with spaces.
+
+**Reuse `assetId` types:** Dashboard, Visualization, DMO, SDM, or CIO only.
+Do **not** pass a Data Lake Object (`0gO`) or a Data Connection id — those
+requests are rejected.
+
+`requesterComment` is required (max **254** chars). Do not omit or pass null
+— the downstream UI will break.
+
+**Org:** caller must be in a Personal Org. Otherwise
+`INVALID_INPUT: "Request is not supported in this type of org"`.
+
+**After create — poll `get_promotion_reuse_request` by the returned `id`**
+(listing a known request is not the poll path — `get_promotion_reuse_request`
+is cheaper and returns more detail).
+
+`status` is lowercase on the wire. Documented values: `requested`,
+`reviewContent`, `markAcceptedOrRejected`, `accepted`, `rejected`,
+`extracting`, `extractionComplete`, `migrating`, `migrationSucceeded`,
+`failed`, `cancelled`, `manageCsv`, `manageAccess`, `manageDataPolicy`,
+`markComplete`, `completed`.
+
+- **Reuse:** poll `status` until the terminal `completed`
+  (`taskProgressStatus: terminal`). Happy path: `requested` → `accepted` →
+  `extracting` → `extractionComplete` → `migrating` → `migrationSucceeded` →
+  `completed`. Do **not** wait for `migrationSucceeded` as the end state — it
+  is a brief intermediate a late poll skips right past on the way to
+  `completed`. **STOP** on `failed`, `cancelled`, or `rejected` — do not keep
+  polling for success. When `status = rejected`, read `rejectionComment` (that
+  is when it is populated) and surface it; do not invent a reason.
+- **Promotion:** poll `packageExportStatus` every **10 seconds** for up to
+  30 seconds until it is `ready`. **The wire value is lowercase** (`ready`,
+  `packaging`, …) even though the `create_reuse_promotion_request` schema enum
+  and older docs show it capitalized (`"Ready"`) — match case-insensitively; a
+  strict `=== "Ready"` check never fires. Note `status` itself stays
+  `requested` throughout a Promotion (it does not advance like Reuse) — gate
+  only on `packageExportStatus`. If it is ready, **ask** the user before
+  `create_promotion_pull_request`. If it is not ready, tell them to try
+  `create_promotion_pull_request` later — do not poll indefinitely.
+  `packageExportStatus` must be `ready` before `create_promotion_pull_request`.
+  Same stop on Reuse-style `failed` / `cancelled` / `rejected` if `status`
+  lands there before export is ready.
+
+**`list_promotion_reuse_requests`:** optional query fields are **top-level**
+(combinable) — `workspaceIdOrApiName`, `assetId`, `assetType`, `createdBy`,
+`searchQueryTerm`, `status`, `taskProgressStatus`, `sortBy`, `orderBy`,
+`limit`, `offset`. Do **not** nest them in a `requestParams` wrapper (that
+name is the Connect Java map, not an MCP key). Always pass
+`requestType=reuse` (case-insensitive). Omitting it mixes Promotion rows
+into the list with no error.
+
+- `assetId` — filter to one source prod asset.
+- `createdBy` — user id of the requester.
+- `searchQueryTerm` — free-text match against label / comment.
+- `assetType` — `dashboard` / `visualization` / `semanticModel` / etc.
+  Do not invent further values.
+- `status` — **comma-separated**, e.g. `requested,extracting,migrating` for
+  in-flight or `rejected,failed` for terminal. Values are **silently
+  accepted** even when spelled wrong — a typo returns an empty list, not a
+  validation error. Spell statuses like the get-by-id lifecycle above.
+- `taskProgressStatus` — also comma-separated; **finer-grained than
+  `status`**. Do not send one field's values on the other.
+- `sortBy` and `orderBy` — sort key plus asc / desc. Do not invent allowed
+  keys; omit unless the user named a sort.
+- `limit` / `offset` — paginate. A default page size applies if `limit` is
+  omitted (do not assume the first page is complete).
+- For one known id, prefer `get_promotion_reuse_request` — cheaper, more
+  detail.
+
+Create/list may double-wrap: if the body looks like `defaultExc`, parse it
+the same way as Share wrap. Get-by-id is unwrapped (do not assume
+`defaultExc` on a failed poll).
+
+---
+
+## Promote: pull-request recovery
+
+`create_promotion_pull_request` does **not** open the GitHub PR. It returns a
+GET-only `presignedUrl` (expires in **5 minutes**) plus `requestId`. Download
+immediately. Git / `gh pr create` is **client-side**.
+
+1. `PROMO_DIR=/tmp/promotion_<requestId>` (and `mdapi` / `source` under it) so
+   concurrent promotions do not collide.
+2. `curl` the zip. Decode `&amp;` in the URL to `&` first.
+3. Unzip into `$PROMO_DIR/mdapi/`.
+4. If the Salesforce sf CLI is missing, **STOP**. Tell the user it is required to
+   convert the package, and give them the remaining commands — do not continue.
+5. Write `$PROMO_DIR/source/sfdx-project.json` as
+   `{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"67.0"}`.
+   Convert: `sf project convert mdapi --root-dir $PROMO_DIR/mdapi/unpackaged
+   --output-dir $PROMO_DIR/source/force-app`. Output files carry a `-meta.xml`
+   suffix.
+6. **Ask** which directory in the target repo should receive the files. Copy
+   the contents **inside** `force-app/main/default/` (not the parent folders).
+7. **Ask** for the branch name. Commit, push, `gh pr create`. Title the
+   promotion; body lists the datakit files and the **promotion request id**.

package/skills/tableau-next-asset-create/references/tasks/ai-readiness-audit.md

@@ -0,0 +1,51 @@
+# Task: AI-readiness audit + backfill / validate a model
+
+Backfill missing AI-readiness metadata on an existing model, or validate a model
+(no-island + query-returns-data audit). Entry points 14 and 16.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+**Backfill (entry 14):** Required **G1, G3, G5** · Conditional **G6** (◐)
+**Validate (entry 16):** Required **G1, G2, G4, G7**
+
+- **G1** (router-asserted): a `mcp__tableau-next-*__` tool must be connected.
+- **Tool names are written bare** — invoke each under your client's name for that `tableau-next-*` server tool (`shared-gates.md`).
+- **G3 (backfill):** read back the exact apiNames via `list_*` BEFORE any sparse
+  `update_*` call — sparse updates that target an assumed/suffixed name silently
+  miss. Echo `isVisible` and `dataObjectFieldName` on every dimension/measure
+  update (`shared-gates.md` G5 / `sdm-tool-reference.md`).
+- **G5 (backfill):** distinct `description` per component (never copy-paste),
+  `sentiment` on directional measures/metrics, `agentEnabled:true` via
+  `update_semantic_model`, `businessPreferences` via
+  `get_semantic_model_business_preferences` /
+  `update_semantic_model_business_preferences` (`update_semantic_model`
+  fallback), correct date/type and dimension-vs-measure roles. Full
+  checklist: `../ai-readiness.md`.
+- **G2 + G4 + G7 (validate):** every object joined (no islands) and
+  `run_semantic_query` returns real rows. Here G5 is a similarity *scan*, not
+  metadata creation — do not over-assert it.
+- **G6** (◐, backfill): profile only if a field's role/meaning isn't understood;
+  do NOT re-ingest or re-model.
+
+## Steps
+
+The complete AI-readiness checklist, description/label quality guides, ambiguity
+management, and `businessPreferences` examples are in **`../ai-readiness.md`**.
+
+- **Backfill** — read back apiNames (`list_semantic_model_dimensions` / `_measures`
+  / `_data_objects` / `_metrics`), then sparse `update_semantic_model_dimension` /
+  `_measure` (include `description` **and** echo `isVisible` + `dataObjectFieldName`
+  — description-only resets hidden fields to visible),
+  `get_semantic_model_business_preferences` then
+  `update_semantic_model_business_preferences` for prefs (GET first; full
+  replacement of `# `-prefixed lines, send only `businessPreferences`;
+  `update_semantic_model` is the fallback), `update_semantic_model` for
+  `agentEnabled`, and `sentiment` on directional measures/metrics.
+- **Validate** — audit that every object participates in ≥1 relationship (G4) and
+  that `run_semantic_query` returns real rows (G7); a ~0-row join is broken.
+- **Never declare AI-ready on metadata completeness alone** — recommend the
+  Semantic Model AI Optimization similarity scan (Semantic Model Builder UI)
+  before handoff; `modelHealth: Low` flags ambiguous components. Mention this
+  whenever the user asks whether a model is ready, finished, or handoff-able.
+- **Scoring golden Q&A / listing verified questions** is
+  `review-verified-questions.md`, not this checklist.

package/skills/tableau-next-asset-create/references/tasks/analyze-data.md

@@ -0,0 +1,48 @@
+# Task: Analyze data (natural-language question)
+
+Answer an interpretive analytical question through `analyze_data`: breakdowns,
+rankings, trends, and comparisons. The Analytics Agent picks the SDM — you do
+not need to pin one. Do **not** use this for a plain count, total, or scalar
+("how many orders", "what is total revenue") — that is `query-model.md` /
+`run_semantic_query`, even when no model was named.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1** · Conditional: **G6** (◐, if the returned numbers' grain is unclear)
+
+- **G1** (router-asserted): a `mcp__tableau-next-*__` tool must be connected.
+- **Tool names are written bare** — invoke each under your client's name for that
+  `tableau-next-*` server tool (`shared-gates.md`).
+- **G6** (◐): if additivity/grain of the answer isn't understood, profile first
+  (`../data-understanding.md`) — do not re-ingest.
+
+## When **not** to use this tool
+
+- **Figures** (count, total, scalar, "give / run me the numbers") →
+  `query-model.md`. Discover the SDM with `list_semantic_models` if unnamed.
+- **Named model + structured table** ("query Sales_Model for revenue by region",
+  explicit `run_semantic_query`) → `query-model.md`.
+- **Greenfield** — nothing modeled yet / CSV / "build a dashboard" →
+  `build-end-to-end.md`.
+- **Metadata discovery** (list SDMs, dashboards, fields, relationships) →
+  `list_*` / `get_*`, not `analyze_data`.
+- **Ongoing monitor** ("alert me when…", change/list/delete my alerts) →
+  `manage-alert.md`. This tool answers once; it does not persist a watch.
+
+## Steps
+
+1. Call `analyze_data` with the user's question as the utterance.
+2. **Do not pin `targetEntityNameOrId` or `targetEntityType`** unless the
+   user explicitly named a specific SDM / data source. `targetEntityType` is
+   `sdm` **only** when pinning.
+3. If a complex question fails, break it into simpler questions and reason
+   client-side.
+4. **This tool does NOT automatically render visualizations.** If `vizMetadata`
+   is returned and the user wants to see the chart, explicitly call
+   `render_visualization` with that object. (Opposite of `edit_visualization`,
+   which renders inline and must **not** be chased with `render_visualization`.)
+5. Long-running / async: a slow answer polls in the background (up to several
+   minutes) rather than timing out — wait; do not treat silence as failure.
+
+This is a read/analysis entry point — it does not model, enrich, or persist a
+chart. If the answer needs a saved visualization, continue to `create-viz.md`.

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

@@ -0,0 +1,66 @@
+# Task: Design / create a dashboard
+
+Design a dashboard narrative, create a **new** dashboard, or add a global
+filter. Entry points 18, 19, 21. (Entry point 20, "add/edit a widget on an
+existing dashboard," now lives in `edit-dashboard.md`.)
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1, G8-full** · plus per-action:
+- **Design narrative (18):** G1, G8-full · Conditional **G6** (◐, if you don't
+  yet understand what the underlying data means).
+- **Create dashboard (19):** G1, **G2/G7** (transitive), G3, G8-full.
+- **Add global filter (21):** G1, G3 only — do NOT over-gate with G2/G7/G8.
+
+- **G1** (router-asserted): a `mcp__tableau-next-*__` tool must be connected.
+- **Tool names are written bare** — invoke each under your client's name for that `tableau-next-*` server tool (`shared-gates.md`).
+- **G8-full (decision #1):** design the narrative FIRST — KPIs → trends →
+  breakdowns → correlations, KPIs top/left on the F/Z path, chart-type diversity
+  (`../dashboard-design-principles.md`, MANDATORY for a dashboard).
+- **G2/G7 (transitive):** a dashboard is only as valid as its widgets — each
+  viz/metric widget's underlying query must have returned real rows first.
+- **G3:** read back the exact metric apiName / viz `id`+`name` before referencing
+  them in a widget.
+- **G6** (◐, narrative design): if you don't yet understand grain/additivity of
+  the data the narrative is built around, profile first (`../data-understanding.md`).
+
+## Hard constraint — viz-type widgets (decision #2)
+
+A **viz-type widget requires the `id` + generated `name` returned by a prior
+`create_visualization` call** (`upsert_visualization_widget`'s `source: {id,
+name}` — `../edit-dashboard.md` §2). This dashboard shell can self-serve
+**metric + text** widgets once built, but **not** a viz widget from nothing. So:
+
+- **Metric / text widgets:** self-serve via `tasks/edit-dashboard.md` once the
+  shell exists.
+- **Viz widget:** either (a) **compose** the `create-viz.md` flow first to get the
+  `id`+`name`, or (b) **accept** a pre-existing viz `id`+`name` the user supplies.
+  If the user asks for a chart on the dashboard and no viz exists yet, route
+  through **`create-viz.md`** first, then place its `id`+`name` as a viz widget
+  via `tasks/edit-dashboard.md`.
+
+## Steps
+
+Dashboard creation and the 48-column grid spec are in
+**`../dashboard-authoring.md`**; `../build-workflow.md` Step 11 is the spine.
+Once the shell exists, all widget/page editing — metric, viz, text, or any
+other widget kind — routes through **`edit-dashboard.md`** via
+**`tasks/edit-dashboard.md`**; this guide covers create + design + global
+filter only.
+
+- **Create empty shell** — `create_dashboard` (`widgets:{}`; seed one layout
+  with an empty `page_1` since widgets get placed next — `layouts:[]` only if
+  they won't — and always pass `minorVersion: -1` explicitly —
+  `../dashboard-authoring.md` §1).
+- **Metric / viz / text / any other widget** — hand off to
+  **`tasks/edit-dashboard.md`** (`edit_dashboard`'s `upsert_*_widget` +
+  `place_widget_on_page`, staged as a draft, saved only on confirmation) — the
+  only supported path for widget/page editing.
+- **Global filter** — `add_global_filter_to_dashboard`; self-contained (no
+  separate read/replace round trip), value-matching rule of thumb, and the
+  contrast with a per-viz filter — `../dashboard-authoring.md` §5.
+- **Metric-card insight payload (app renderer only)** — `../insight-bundle.md`.
+  Do **not** call `generate_insight_bundle` on a user chat turn.
+- **Show / open an existing dashboard** — `render_dashboard`, not
+  `get_dashboard`. Flags and metadata-vs-render split:
+  `../dashboard-authoring.md` §8.

package/skills/tableau-next-asset-create/references/tasks/build-end-to-end.md

@@ -0,0 +1,73 @@
+# Task: Build a semantic model + dashboard end-to-end (greenfield)
+
+The greenfield "nothing is modeled yet" path — analyze flat files, a table
+on an existing connection, or other unmodeled data all the way through to a
+dashboard.
+
+This guide is the **gate map** for the greenfield flow, not a second copy of the
+spine: it declares which gates fire across the whole build (below), maps each step
+to the gate it enforces and the slice-guide that can be entered standalone, then
+hands the actual procedure to `../build-workflow.md`. The router points here rather
+than straight to `build-workflow.md` so the full-flow gate coverage is asserted
+before Step 0 and the mid-flow entry points stay discoverable.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required across the flow: **G1, G2, G3, G4, G5, G6, G7, G8**. Each step below
+inherits the gates its action needs (per the coverage matrix). At minimum:
+
+- **G1** (router-asserted): a `mcp__tableau-next-*__` tool must be connected.
+- **Tool names are written bare** — invoke each under your client's name for that `tableau-next-*` server tool (`shared-gates.md`).
+- **G6** *first*: profile before you model — grain, field roles, cardinality,
+  additivity, date roles. For a large/wide/cryptic file, infer its schema before
+  creating the data stream, then do value-level checks with `run_query`.
+- **G2** before adding any *discovered* object. For a DMO you just created and
+  mapped in this flow, poll `run_query` until `<dmo>__dlm` exists (`COUNT = 0`
+  is READY; `42P01` keep polling) — `shared-gates.md` G2. Keep the discovered
+  row-count gate as-is.
+- **G3** before writing any apiName you did not just read back.
+- **G4 + G7** once ≥2 objects exist: every object joined, every join row-verified.
+- **G5** on every component you create (metrics first).
+- **G7 + G8** before any `create_visualization`.
+
+## Steps
+
+The full procedural spine with verified per-tool payloads and inline gotchas lives
+in **`../build-workflow.md`** — load it and follow Step 0 → Step 11:
+
+- **Step 0 — Ingest** (CSV/Excel upload **or** existing database connection) →
+  see `../ingest-and-metric-gotchas.md` §A (file) / §C (connection) and
+  `ingest-flat-file.md` standalone. File chain: `get_upload_connection` →
+  `infer_object_schema` → `create_data_stream` → `run_data_stream` → wait DLO
+  Active → SCHEMA REALITY CHECK + real Primary Key read-back →
+  `create_data_model_object` (unsuffixed name; platform adds `__dlm`) → wait
+  DMO Ready → `create_dlo_to_dmo_mapping` → poll `run_query` until
+  `<dmo>__dlm` exists (`get_dlo_to_dmo_mapping_status` `ACTIVE` is metadata
+  only). Connection chain: `list_connections` →
+  `list_data_connection_objects` → `infer_object_schema` →
+  `create_data_stream` (`dataAccessMode: "Direct_Access"`, connection
+  developer name) → `run_data_stream` `interactive: false` → then the same
+  DMO / mapping tail.
+- **Step 0.5 / 1 — Profile + discover** (G6) → `../data-understanding.md`,
+  `../large-flat-file-handling.md`; or `profile-dataset.md`.
+- **Step 2 — Verify data presence** (G2) → `../empty-source-handling.md`. For
+  DMOs you just created and mapped in Step 0, wait until `run_query` succeeds
+  on `__dlm` (`COUNT = 0` is READY); keep the discovered-source row-count
+  gate as-is.
+- **Step 3 — Confirm join keys** (G7) with a real JOIN row-count.
+- **Steps 4–6 — Create model with nested fields, add remaining objects, add
+  relationships** (G2, G3, G4, G5) → `../sdm-tool-reference.md`; or
+  `edit-sdm.md`. Bind via one `create_semantic_model` with explicit
+  `semanticDimensions[]` / `semanticMeasurements[]` (`shouldIncludeAllFields:
+  false`); do not N-call `add_semantic_model_dimension` / `_measure`.
+- **Step 7 — Validate (BLOCKING)** (G4, G7): every object joined +
+  `run_semantic_query` returns real rows; empty → STOP.
+- **Step 8 — Enrich** (G5, G6, G7): calc dimensions/measures + metrics →
+  `../semantic-query-and-enrichment.md`; metric gotchas `../ingest-and-metric-gotchas.md`
+  §B; or `enrich-model.md`.
+- **Step 9 — Query the model** (G7) → `../semantic-query-and-enrichment.md`; or
+  `query-model.md`.
+- **Step 10 — Create visualizations** (G7, G8) → `../dashboard-design-principles.md`
+  (narrative first), `../viz-authoring.md`; or `create-viz.md`.
+- **Step 11 — Build the dashboard** (G7 transitive, G8) → `../dashboard-authoring.md`;
+  or `build-dashboard.md`.

package/skills/tableau-next-asset-create/references/tasks/create-data-transform.md

@@ -0,0 +1,51 @@
+# Task: Create or update a Data Cloud SQL transform
+
+Materialize a **derived** DLO/DMO from one or more source objects via a Data
+Cloud SQL (DCSQL) transform. Use this when the user wants a new derived table
+or to change how an existing transform-backed table is produced — not for
+CSV ingest (`ingest-flat-file.md`) and not for semantic-model calculated
+fields (`enrich-model.md`).
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1** · Conditional: **G2** (◐, source object must exist)
+
+- **G1** (router-asserted): a `mcp__tableau-next-*__` tool must be connected.
+- **Tool names are written bare** — invoke each under your client's name for that `tableau-next-*` server tool (`shared-gates.md`).
+- **Confirmation (this guide):** never call `create_data_transform`,
+  `update_data_transform`, or `run_data_transform` without an explicit "yes"
+  after showing SQL + preview. Run is a **separate** yes from create/update.
+- **G2** (◐): the **source** relation must be a real `__dll` / `__dlm` from
+  `browse_data_assets`. Do not invent the apiName.
+
+## Steps
+
+Payloads, immutable-vs-editable fields, timeout recovery, SparkInternal
+substitutions, and error strings are in
+**`../data-transform-gotchas.md`**.
+
+1. Disambiguate: **create** if the output object does not exist; **update**
+   if it is already transform-backed (never a second transform on that table).
+2. Resolve the source `assetApiName` (with suffix). Multiple matches → STOP
+   and ask.
+3. Generate DCSQL; validate (`validate_data_transform` and/or `run_query`
+   with `rowLimit: 10`). **Every output SELECT alias / `fields[].name` must
+   be `__c`-suffixed** — validate does not error on a bare alias, it
+   silently renames the derived field, and the mismatch only fails later
+   on `run_data_transform` (see the deep ref).
+4. Confirm with the user (SQL + preview + output name).
+5. Create (full nested `definitions`/`manifest`) or update (GET first; full
+   replace; copy 🔒 fields). Create, update, and validate send the **same
+   flat body** (`name` / `type` / `definitions` at the top level — no
+   `dataTransformObject` / `dataTransform` envelope). On update timeout, GET
+   and compare `compiled_code` — do not blindly retry.
+6. Create-only: add the new output object to the workspace the user named
+   (else list and ask).
+7. Confirm, then `run_data_transform` only after the transform is `ACTIVE`
+   (not `PROCESSING`). Runs may be sync or async; poll
+   `get_data_transform_run_history` until the run succeeds or fails
+   (typically 10–15 minutes). If status looks stuck, call
+   `refresh_data_transform_status` then poll history again. Do **not** treat
+   `get_data_transform` `ACTIVE` as “rows are ready.” BATCH definitions use
+   `DCSQL`; STREAMING uses `SQL`. DMO outputs need `KQ_<pk>` (see the deep
+   ref).

package/skills/tableau-next-asset-create/references/tasks/create-viz.md

@@ -0,0 +1,58 @@
+# Task: Create a visualization (single chart)
+
+Create one visualization with `create_visualization` on a built, populated model.
+Entry point 17. (For a dashboard, use `build-dashboard.md`.) This is also the
+**first hop** for a chart-type / `create_visualization` payload lookup — do not
+start at `viz-authoring.md`.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1, G2, G3, G7, G8-light** · Conditional: **G4** (◐, if the chart
+queries across >1 object), **G5/G6** (◐, consume-not-create)
+
+- **G1** (router-asserted): a `mcp__tableau-next-*__` tool must be connected.
+- **Tool names are written bare** — invoke each under your client's name for that `tableau-next-*` server tool (`shared-gates.md`).
+- **G7:** run `run_semantic_query` and confirm real rows come back BEFORE
+  `create_visualization` — never chart a model that returned empty.
+- **G2:** don't chart an empty/unverified source — field-richness ≠ data-presence.
+- **G3:** read field apiNames back via `list_*`; `create_visualization` uses a
+  `fields` map keyed by fieldKey (`{objectName, fieldName, function}`; `objectName`
+  omitted for calc measures) — NOT the retired `fieldRef`/`measureFunction` shape,
+  and distinct from `run_semantic_query`'s snake_case `table_field`.
+- **G8-light (decision #1):** state the chart's **analytical intent** — the one
+  question this chart answers and why the chart type fits the field roles
+  (trend/comparison/part-to-whole/correlation/forecast). A single standalone viz
+  does NOT require the full dashboard narrative, and you must **not invent a
+  dashboard** around it.
+- **G5/G6** (◐): viz *consumes* metadata rather than creating it — business-
+  friendly labels depend on upstream descriptions already existing.
+- **G4** (◐): only chart across objects that are actually joined — do not set
+  `queryUnrelatedDataObjects:"Exception"` and chart across unjoined objects.
+
+## Steps
+
+The visualization tool-selection guide, chart-type decision matrix (mapped to MCP
+tools), field-selection priorities, color/breakdown encoding, UserAgg handling,
+and verified payloads are in **`../viz-authoring.md`**; narrative/labeling
+guidance is `../dashboard-design-principles.md`.
+
+**First, identify the user's analysis intent — it picks the analysis type, which
+picks the chart.** Don't jump straight to a bar chart:
+
+| User intent (example) | Analysis type | Tool guidance | §reference |
+|---|---|---|---|
+| "revenue over time" | trend | Line (date on columns) | `viz-authoring.md` §11 Time Series |
+| "top categories by sales" | comparison | Bar (dim on columns, sorted) | `viz-authoring.md` §11 Bar |
+| "market-share breakdown" | part-to-whole | Donut (< 5 vals) or Bar (≥ 5) | `viz-authoring.md` §11 Donut |
+| "discount vs profit relationship" | correlation | Scatter (2 measures, 1 color dim) | `viz-authoring.md` §11 Scatter |
+| "predict next quarter revenue" | forecast | Line + `visualSpecification.forecasts` | `viz-authoring.md` §3 / §11 Time Series (forecast) |
+
+- Pick the chart type matched to intent + field roles — do not default every
+  chart to a bar chart.
+- Build with `create_visualization` (`fields` map + `visualSpecification`), only
+  after Step 9 / G7 returns real data. FieldKeys in `fields` are pointers —
+  they must exactly match `rows` / `columns` / encoding `fieldKey` strings.
+- For forecast asks: timeseries Line only, continuous `DateTrunc*` date +
+  measure, then a `forecasts` entry (`HoltWinters` or `RidgeRegression`).
+- Keep the returned viz `id` + generated `name` — a dashboard viz-widget needs
+  both (see `build-dashboard.md`).