@salesforce/afv-skills 1.59.0 → 1.61.0

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

@@ -0,0 +1,80 @@
+# Task: Edit an existing dashboard
+
+Modify a dashboard that already exists — add/edit/move/remove a widget, or
+add/rename/delete a page — via the atomic `edit_dashboard` batch tool, and only
+persist the change on explicit request. For building a brand-new dashboard, use
+`build-dashboard.md` instead. Entry point 20 ("add/edit a widget on an existing
+dashboard" — see `build-dashboard.md`'s entry-point list).
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1** · Conditional: **G3** (◐, only if placing a viz/metric widget
+whose `id`/apiName you have not read back this session) · **G8** (◐, only if the
+edit changes the narrative structure — e.g. adding a new KPI/chart — not a pure
+reposition/rename)
+
+- **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`).
+- **No G2/G7 by default.** Repositioning, renaming, or removing an
+  already-placed widget mutates layout, not data — the data-presence and
+  query-returns-real-data gates don't re-apply. They DO apply transitively when
+  the edit places a **new** viz/metric widget: that widget's underlying query
+  must have returned real rows first (same rule as `build-dashboard.md`).
+- **G8** (◐): reposition-only edits don't need a restated narrative; adding a
+  widget that changes the story (a new KPI, a new breakdown) does — confirm it
+  still fits the KPIs → trends → breakdowns → correlations order.
+
+## Steps
+
+The operation-type table, every `upsert_*_widget` shape, the widget-identity
+rule, grid conventions, and draft-vs-persist mechanics are in
+**`../edit-dashboard.md`**.
+
+- **Before building a payload, Read the operation's schema file.**
+  `../edit-dashboard.md` §2's table names the exact
+  `../schemas/edit-dashboard/<operation>.json` for whichever operation(s) you're
+  about to send (e.g. `upsert_metric_widget.json`, `move_widget.json`) — it has
+  the authoritative required/optional fields, enums, and a worked example. Read
+  only the file(s) for this batch, not the whole directory.
+- **Always pass `minorVersion: -1` explicitly** on every `edit_dashboard` call —
+  the schema shows it as a default, but it is not auto-applied; omitting it can
+  surface `ILLEGAL_QUERY_PARAMETER_VALUE: Illegal value for query parameter
+  'minorVersion': ''`.
+- **Upsert → place, same discipline as viz creation.** An `upsert_*_widget`
+  operation only *defines* a widget (create or full replace) — it renders
+  nowhere until paired with `place_widget_on_page` (same batch, or a later one
+  before you save) unless it's replacing an already-placed widget. Never
+  define a new widget without also placing it.
+- **Widget identity.** `widget.name` always identifies the widget inside an
+  `upsert_*_widget` call; add `widget.id` only to fully replace an already
+  *persisted* widget (never invent this value — read it back first, e.g. via
+  `render_dashboard`/`get_dashboard`), and omit it to create a new widget. An
+  unsaved draft widget has no `id` — replace it by `widget.name` alone. Page
+  ops (`place_widget_on_page`/`remove_widget_from_page`/`move_widget`/
+  `move_widget_to_page`) use a third, separate field: `placement.name`. Full
+  detail: `../edit-dashboard.md` §3.
+- **`autosave` is now top-level and batch-wide** (a sibling of `operations`,
+  not a per-operation field). Leave it unset (default `false`) to stage a
+  draft. The batch response IS the preview — show it, then ask before
+  persisting. Drafts **accumulate** across successive `edit_dashboard` calls on
+  the same dashboard until saved/discarded; the dashboard read tool will NOT
+  show a staged draft.
+- **Persist only on explicit confirmation.** `save_dashboard` may now appear
+  standalone (commits whatever draft is already staged) or after other
+  mutations in the same batch (persists once they succeed) — it's no longer
+  required to be the batch's sole operation. Regardless of batch shape, only
+  send it after the user confirms **having seen** the draft — even if the
+  original request already said "save it" in the same message as the edit.
+- **To revert an unsaved draft:** `undo` (standalone: reverts the last staged
+  change; in a mixed batch: cancels every operation in that batch) or
+  `discard_dashboard` (standalone: drops the whole staged draft; in a mixed
+  batch: ignores every other operation in that batch). `undo` only works while
+  a draft is staged — after a save there's nothing to undo (`RESOURCE_NOT_FOUND:
+  "No staged draft to undo for dashboard <name>"`).
+- **To fully delete a widget (not just unplace it):** use
+  `remove_widget_from_dashboard` — a bare `widgetName`, deletes the definition
+  and every placement across every page in one operation, in the same batch as
+  any other `edit_dashboard` operations. `remove_widget_from_page` alone only
+  removes the page placement, leaving an orphaned widget definition in the
+  dashboard's `widgets` map — see `edit-dashboard.md` §6.
+- No existing dashboard to edit? Route to **`build-dashboard.md`** instead.

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

@@ -0,0 +1,106 @@
+# Task: Edit the semantic model — add a raw object / field / join / logical view
+
+Create a model, or add a **raw** data object, dimension, measure, relationship,
+logical view, or parameter to one. (For **calculated** dimensions/measures/metrics, use
+`enrich-model.md`.) Entry points 7, 8, 9, 10.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+This guide serves five mutating intents; required gates differ per intent:
+
+- **Create new model (entry 7):** Required **G1, G2, G5** · Conditional **G6**
+  (◐). Nested explicit fields mean you control apiNames at create; still
+  light-confirm with `list_*` before relationships (G3).
+- **Add data object (entry 8):** Required **G1, G2, G3, G5** · Conditional **G4**
+  (◐, once ≥2 objects — no islands), **G6** (◐).
+- **Add dimension / measure (entry 9):** Required **G1, G2, G3, G5** ·
+  Conditional **G6** (◐). Use this only to add a *single extra field* to an
+  already-bound object — not for the initial bind.
+- **Add relationship / join (entry 10):** Required **G1, G2, G3, G4, G7**. A raw
+  join creates no metadata, so G5 does not apply.
+- **Add logical view (HardJoin / Union / CustomSQL):** Required **G1, G2, G3, G5**.
+  Field apiNames are assigned at first save — read them back with
+  `get_semantic_model_logical_view` before joining. `Hierarchy` is **not
+  currently supported via MCP**.
+
+- **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`).
+- **G2:** COUNT(*) the source object before adding it — never add a 0-row object.
+- **G3:** read apiNames back with `list_*` before writing any relationship criteria
+  or field reference (semantic apiName + `leftFieldType: "TableField"`). For a
+  logical view, read assigned names from `get_semantic_model_logical_view`.
+- **G4:** once ≥2 objects exist, no islands — ◐ when adding an object (entry 8),
+  **required** when adding a relationship (entry 10).
+- **G5** (create model / add object / add field / add logical view — not raw
+  joins): set the required metadata at creation and prefer **nested explicit
+  fields** on `create_semantic_model` / `add_semantic_model_data_object`
+  (`shouldIncludeAllFields: false`) — full metadata list in `shared-gates.md`
+  G5. CustomSQL **requires** explicit fields (`shouldIncludeAllFields` does
+  not satisfy validation).
+- **G7** (add-relationship): after adding, confirm the join key matches real rows
+  with a JOIN row-count — ~0 rows = broken.
+- **G6** (◐): if a column's role/type isn't understood, profile first
+  (`../data-understanding.md`) — but do NOT re-run Step 0 ingest on a pre-existing
+  model.
+
+## Steps
+
+Tool-by-tool input shapes, suffix rules, the apiName-mutation gotcha, and
+logical-view shapes are in **`../sdm-tool-reference.md`**; the numbered spine
+(create model with nested fields, add objects, add relationships) is
+`../build-workflow.md` Steps 4–6.
+
+- **Create model** — `create_semantic_model` + `update_semantic_model` (Step 4).
+  Nested `semanticDataObjects[].label` is REQUIRED. Bind fields **in this
+  call**: `shouldIncludeAllFields: false` plus explicit
+  `semanticDimensions[]` / `semanticMeasurements[]` (fetch fields first;
+  include join keys). Relationships, metrics, calcs, parameters, and logical
+  views are still post-create `add_semantic_model_*`. **Extend a Model** uses
+  the same tool with `baseModels[]` of `{ "apiName": "<existing SDM>" }` in
+  the same `dataspace` (typical label `"<Base Label> (Extended)"`; payload in
+  **`../sdm-tool-reference.md`**). Prefer **anchor-plus-nested-fields create**,
+  then incremental `add_semantic_model_data_object` with the same nested
+  arrays. If a table has no FK to the anchor, add the intermediate first,
+  then bridge through it. Bulk-create timeout (`postSemanticModelCollection`)
+  may still persist the SDM — wait ~30s and `list_semantic_models` before
+  retrying (naive retry → Unique constraint violated). Optional sanity check:
+  `get_semantic_model` with `includeModelContent=true`.
+- **Add data object** — `add_semantic_model_data_object` (`dataObjectType:"Dmo"`,
+  name `*__dlm`) with nested `semanticDimensions[]` /
+  `semanticMeasurements[]` (`shouldIncludeAllFields: false`). Omit
+  `primaryNameField` at create (G5 known gap).
+- **Add dimension / measure** — `add_semantic_model_dimension` / `_measure`
+  only for a *single extra field* on an already-bound object. Do **not** use
+  these for the initial bind (that is the nested create / add-data-object
+  path above).
+- **Add relationship / join** — `add_semantic_model_relationship`
+  (`leftFieldType:"TableField"`, `joinType:"Auto"`, `label` required even though
+  schema marks it optional). Validate the join with a real JOIN row-count (G7).
+- **Add / update a parameter** — post-create only (`add_semantic_model_parameter`;
+  cannot be created inline on `create_semantic_model`). Updates are PUT, not
+  PATCH — re-send `label`/`type`/`dataType`/`defaultValue` even for a
+  description-only change. `List` needs `values` and a matching `defaultValue`.
+  Shapes: **`../sdm-tool-reference.md`** (Parameters).
+- **Add logical view** — `add_semantic_model_logical_view`. Enumerate existing
+  views via `get_semantic_model` (`semanticLogicalViews[]`) first. `label` is
+  required. Rules and reference payloads: **`../sdm-tool-reference.md`**
+  (Logical views).
+  - **HardJoin 3-step:** objects only → GET assigned apiNames → relationship
+    with LV `joinType` `Left`/`Right`/`Inner`/`Full` (**not** `Auto`). Prefix
+    LV object apiNames `LV_`.
+  - **Union:** exactly one `semanticUnions[]` entry. **Do NOT pass
+    `"semanticViewTypeEnum": "Union"`**. Mapped-field apiNames are
+    **locally-scoped** on that ULV object.
+  - **CustomSQL:** `customSQLV2`; exactly one `CustomSQL` data object with
+    **explicit** dims/measures.
+  - **Update (PATCH):** `update_semantic_model_logical_view` only persists
+    `description`, `filterLogic`, and `filters`. Empty body `{}` is rejected.
+    GET via `get_semantic_model_logical_view` first before replacing filters.
+    **Label is silently ignored** (API accepts it, never persists). SQL or
+    view-type changes require delete-and-recreate — do not treat a 2xx PATCH
+    as a successful rename or SQL edit.
+  To remove a logical view, see **`../sdm-tool-reference.md`** (Deleting) —
+  a blocked LV delete is HTTP 500 `DEPENDENCY_EXISTS` (do not retry).
+
+Do NOT re-profile from scratch or re-ingest on an already-built model — assume the
+model exists and touch only what the request names.

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

@@ -0,0 +1,40 @@
+# Task: Edit an existing visualization
+
+Modify a visualization that already exists — add/remove/replace a shelf field,
+filter, forecast, sort, mark encoding, mark type, dual axis, reference line, table
+calc, or axis title — and, only on explicit request, save the result. For building a
+brand-new chart, use `create-viz.md` instead.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1** · Conditional: **G3** (◐, only if an operation references a field/
+apiName you have not read back this session — e.g. adding a brand-new shelf field)
+
+- **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`).
+- **No G2/G7/G8 by default.** You are mutating an already-created, already-verified
+  visualization — this is not a fresh build from a new query, so the data-presence,
+  query-returns-real-data, and narrative-design gates that gate `create_visualization`
+  do not re-apply here.
+
+## Steps
+
+The `editOperations` operation-type reference, filter-operator rules, the
+`{model:}`/`{expression:}` decision rule, and the reference-line `field.function` vs
+`line.function` disambiguation are in **`../edit-visualization.md`**.
+
+- Obtain the current `visualizationId` — from `get_visualization`, or from a
+  prior `edit_visualization`/`update_visualization` call. Do **not** pass a
+  `visualizationMetadata` blob into `edit_visualization` or `update_visualization`.
+- Build the `editOperations` array per `../edit-visualization.md`; JSON-stringify the
+  whole array into a single string — never pass a raw array.
+- Call `edit_visualization` with `visualizationId` + that string. Its result
+  renders inline automatically — do **not** call `render_visualization` on it.
+- **Never call `update_visualization` automatically.** After `edit_visualization`
+  renders the preview, ask the user whether to save; call `update_visualization`
+  only on their confirmation *after seeing that preview*, passing **only**
+  `visualizationId` (the server persists its working state for that id). This
+  applies even if the user's original request already said to save it — the
+  edit still renders a preview first, and only a confirmation given after that
+  preview authorizes the persist.
+- No existing chart to edit? Route to **`create-viz.md`** instead.

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

@@ -0,0 +1,68 @@
+# Task: Enrich the model — calculated dimension / measure / metric
+
+Add a **calculated** dimension or measure, or create a metric, on a model that
+already exists. This is the guardrail-densest entry point. Entry points 11, 12, 13.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+This guide serves three intents; G7 required-ness differs per intent:
+
+- **Add calculated dimension (entry 11):** Required **G1, G2, G3, G5, G6** ·
+  Conditional **G7** (◐, only if the calc references data you haven't just
+  verified with `run_semantic_query`).
+- **Add calculated measure (entry 12):** Required **G1, G2, G3, G5, G6** ·
+  Conditional **G7** (◐, same rule as entry 11).
+- **Create metric (entry 13):** Required **G1, G2, G3, G5, G6, G7** — a metric is
+  always query-facing, so G7 is unconditional here.
+
+- **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:** confirm grain + additivity + that your date is a **business-event date**
+  (`../data-understanding.md`) — a metric on a load/system/partition timestamp is
+  wrong even if it returns rows. Applies on a pre-existing model; do NOT re-ingest.
+- **G5:** run the per-component coverage `list_*` check FIRST (calc dimension, calc
+  measure, and metric each require different `list_*` calls) and set the required
+  metric shape — the authoritative sub-rules (`UserAgg`-not-`Auto`, concrete
+  `aggregationType`, `identifyingDimension`, count-via-numeric, full-PUT
+  `insightsSettings`) are in `shared-gates.md` G5. Don't proceed without it.
+- **G3:** read back exact apiNames via `list_*` before referencing them in a
+  formula or `measurementReference`.
+- **G2:** the underlying object has rows (required for all three intents).
+- **G7:** `run_semantic_query` returns real data before you trust the
+  calculation — required for a metric (entry 13); for a calc dimension/measure
+  (entries 11/12) only re-verify if you haven't already confirmed the query
+  path on this data (see header above).
+
+## Steps
+
+Worked calc-dimension / calc-measure / metric payloads and the field-shape matrix
+are in **`../semantic-query-and-enrichment.md`**; the extra metric gotchas
+(`Auto` rejection, `identifyingDimension`, count-by-numeric, the row-level-ratio
+`Average` case) are in `../ingest-and-metric-gotchas.md` §B; `../build-workflow.md` Step 8
+is the spine.
+
+**Identify the analysis intent first** (trend / comparison / part-to-whole /
+correlation / forecast — see `create-viz.md` / `viz-authoring.md` §3) so
+enrichment produces the fields that intent needs: a business-meaningful date
+anchor for trend/forecast, a slicing dimension for part-to-whole, two measures
+for correlation.
+
+- **Calc dimension** — `add_semantic_model_calculated_dimension` (after the
+  coverage `list_*`); distinct label + description (homonym dates → two dims).
+- **Calc measure** — `add_semantic_model_calculated_measure`; `UserAgg` when the
+  expression aggregates. Inputs are a **JSON object, NOT a stringified JSON
+  string**. Do not set `externalLevel` / `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 defaults).
+- **Metric** — `add_semantic_model_metric` with the full verified shape (concrete
+  `aggregationType`, `identifyingDimension`, count-via-numeric, `sentiment`).
+  `identifyingDimension` MAY point at a field on a **joined** object
+  (cross-object). Create the metric by default when the request implies a
+  tracked number and a meaningful event date exists. Updates are full PUT
+  (GET via `get_semantic_model_metric` first; `{description}` → `MasterLabel`
+  means send `label`).
+
+When asked to create two fields with the same/equivalent formula, treat it as a
+synonym (G5): declare one canonical, decline or ask about the other — don't
+silently create both.

package/skills/tableau-next-asset-create/references/tasks/ingest-flat-file.md

@@ -0,0 +1,68 @@
+# Task: Ingest a file or existing connection → DLO → DMO
+
+Ingest local CSV/Excel **or** a table from an existing Data Cloud connection
+into Data Lake Objects and Data Model Objects — the front half that the SDM
+build assumes already exists. Entry point 1. (Entry point 3 — probing a
+large/cryptic file *before* ingesting — is diagnostic and lives in
+`profile-dataset.md` / `../large-flat-file-handling.md`; this guide's G6 bullet
+below just points there.)
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1, G2, G5-light** · Conditional: **G6** (◐, for a large/cryptic file)
+
+- **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 the file is large/wide/cryptic, use `infer_object_schema`
+  FIRST, decode the column-naming grammar, then verify one known number with
+  `run_query` after ingest (`../large-flat-file-handling.md`). Do not slurp the
+  whole file into context or add a local parsing step.
+- **G2 (post-ingest):** `run_data_stream` is mandatory; then wait until the DLO
+  is Active and the DMO is Ready. 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 — not that gate
+  (`shared-gates.md` G2). For a self-created mapped DMO, do not refuse SDM
+  create because `COUNT = 0`; do not proceed while the table is missing.
+- **G5-light:** file-upload DLOs **and** DMOs require `category: "Other"` (never
+  `"Engagement"`); DLO→DMO mapping field dev names carry a literal `__c` on both
+  sides — copy them from the materialized table, not from `get_data_stream`.
+  Full AI-readiness metadata lands later when objects/fields are added.
+- **Schema confirmation:** after `infer_object_schema`, present the fields and
+  **wait for the user to explicitly confirm** or adjust types / primary key /
+  skipped columns. Do not call `create_data_stream` until they approve or say
+  to proceed.
+
+## Steps
+
+The fixed, ordered ingestion chain with verified payloads is in
+**`../ingest-and-metric-gotchas.md`**:
+
+**File CSV / Excel — §A:**
+`get_upload_connection` → `generate_presigned_credential` (per file; PUT with
+decoded URL + optional `headers`; opaque `parentDirectory` /
+`importDirectory`; re-call if `expiryTime` passed) → Excel: `list_data_connection_objects` for sheets →
+`infer_object_schema` → **confirm schema** → `create_data_stream` (`*__dll`
+DLO, including `mappings` / `refreshConfig` / `advancedAttributes`) →
+**`run_data_stream` + wait until Active** → SCHEMA REALITY CHECK
+(materialized DLO, not `get_data_stream`) + real Primary Key read-back →
+`create_data_model_object` (unsuffixed name — `Orders`, not
+`Orders__dlm`; the platform adds `__dlm`) → **wait until Ready** →
+`create_dlo_to_dmo_mapping` → inspect mapping
+(`get_dlo_to_dmo_mapping_status` for `ERROR`) → **poll `run_query` until
+`<dmo>__dlm` exists** (`COUNT = 0` is READY).
+
+**Existing database / lakehouse connection — §C:**
+`list_connections` (exact `connectorType` casing) → optional
+`test_existing_connection` (once; `9cg` id) → `list_data_connection_objects`
+→ `infer_object_schema` (table `resourceName`; uppercase `SCHEMA`/`DATABASE`)
+→ **confirm schema** → `create_data_stream` with `dataAccessMode:
+"Direct_Access"` and the connection **developer name** → `run_data_stream`
+`interactive: false` → then the same SCHEMA REALITY CHECK → DMO → mapping
+tail as §A.
+
+After `run_query` succeeds on the `__dlm` table, continue with `edit-sdm.md`
+(build the model) or `build-end-to-end.md` Step 4. `COUNT = 0` on that
+successful query is READY for these self-created DMOs (G2); `42P01` is not.
+Ingestion gotchas (status waits, SCHEMA REALITY CHECK, `category:"Other"`,
+universal-`__c`, stream payload traps) are in
+`../ingest-and-metric-gotchas.md` §A / §C.

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

@@ -0,0 +1,35 @@
+# Task: Create / update / list / delete a data alert
+
+Persist an ongoing Tableau Next data monitor. One-off "why did this number
+move" questions are `analyze-data.md`, not this guide.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1**
+
+- **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):** first `create_alert` / `update_alert` /
+  `delete_alert` call is a preview. Show `alertSummary`, then retry with
+  `userConfirmed=true`. `delete_alert` is irreversible.
+
+## When **not** to use these tools
+
+- **One-off interpretation** ("why did EMEA sales drop", "compare regions
+  last quarter") → `analyze-data.md` / `analyze_data`. Do not pin an SDM
+  there either.
+- **A saved chart of current state** → `create-viz.md` / `build-dashboard.md`.
+
+## Steps
+
+Transcript-on-follow-up, do-not-pin-SDM, timeout-poll, full replacement on
+update, and never-show-`savedDataAlertId` are in **`../alerts.md`**.
+
+1. **List** — `get_alerts` (caller's alerts only).
+2. **Create** — `create_alert` with `conversationContext`. Do **not** look
+   up or pin `targetEntity*`. Preview, then `userConfirmed=true`.
+3. **Update** — resolve `savedDataAlertId` via `get_alerts`, then
+   `update_alert` with the **complete** desired configuration (omit = drop).
+4. **Delete** — `get_alerts` then `delete_alert` after preview.
+5. **Timeout** — poll `get_alerts`; do not immediately re-create.

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

@@ -0,0 +1,47 @@
+# Task: Profile / discover / verify a dataset (read-only diagnostics)
+
+Understand data before modeling it, discover what's available, or triage an empty
+source. All read-only — no mutation. Entry points 2, 3, 4, 5, 6.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+This guide serves five read-only intents; required gates differ per intent:
+
+- **Profile / understand dataset (entry 2):** Required **G1, G6** · Conditional
+  **G2** (◐, when cardinality/additivity depends on a row count).
+- **Infer a large/wide/cryptic flat file's schema (entry 3):** Required **G1,
+  G6** — same profiling rule as entry 2, starting with `infer_object_schema` as
+  described in `../large-flat-file-handling.md`.
+- **Discover data assets (entry 4):** Required **G1**.
+- **Verify presence / triage empty (entry 5):** Required **G1, G2** — you must
+  `COUNT(*)`; presence is the whole question.
+- **Confirm join keys (entry 6):** Required **G1, G2** · Conditional **G3**
+  (◐, only if you're about to persist a join with the keys you find).
+
+- **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:** profile the five things — grain, field roles, cardinality, additivity,
+  date roles (`../data-understanding.md`). This applies over an already-modeled
+  dataset too, whenever you don't yet understand what the numbers mean. For a
+  large/wide/cryptic flat file, use the infer-first variant (infer fields/types,
+  decode the naming grammar, verify one number after ingest —
+  `../large-flat-file-handling.md`).
+- **G2** (◐): when the ask is "does this source have data?", run `SELECT COUNT(*)`
+  — `count>0` usable, `count=0` empty, `does not exist`/`42P01` unmaterialized (a
+  distinct case — `../empty-source-handling.md`).
+
+## Steps (read-only — do NOT mutate)
+
+- **Discover sources** — `browse_data_assets` (a label/keyword match is a
+  *candidate list*, not the answer; calling convention + gotchas —
+  `../sdm-tool-reference.md`).
+- **Verify presence / triage empty** — `SELECT COUNT(*)`; distinguish empty from
+  unmaterialized per `../empty-source-handling.md`.
+- **Confirm join keys** — run a real JOIN row-count between two objects; a key
+  matching ~0 rows is as broken as no relationship (this is diagnostic here — the
+  persisted join lives in `edit-sdm.md`).
+- **Profile** — grain / field roles / cardinality / additivity / date roles
+  (`../data-understanding.md`); large/cryptic files → `../large-flat-file-handling.md`.
+
+This guide is diagnostic only. When you move on to *persist* structure, route to
+`edit-sdm.md`; to *enrich*, `enrich-model.md`; to *query*, `query-model.md`.

package/skills/tableau-next-asset-create/references/tasks/promote-or-reuse.md

@@ -0,0 +1,46 @@
+# Task: Reuse a prod asset or promote a Personal Org asset
+
+**Reuse** copies a production Dashboard, Visualization, DMO, SDM, or CIO
+into a Personal Org workspace. **Promotion** packages a Personal Org asset
+and, after the export is ready, lands datakits in a git repo via a reviewed
+PR. Both use `create_reuse_promotion_request`; only Promotion then uses
+`create_promotion_pull_request`.
+
+Not a greenfield create (`build-end-to-end.md` / `create_semantic_model`) and
+not sharing with a user (`share-asset.md`).
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1**
+
+- **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):** confirm `requestType` (Reuse vs Promotion),
+  `assetId`, workspace, label, and `requesterComment` before create. After a
+  Promotion export is `Ready`, **ask again** before
+  `create_promotion_pull_request`. Ask for the target directory and branch
+  name — do not invent them.
+
+## Steps
+
+Direction flip, poll fields (`status` vs `packageExportStatus`), list
+filters, HTTP 400, and the client-side convert/`gh` procedure are in
+**`../sharing-and-promotion.md`** (§Promote).
+
+1. Confirm Personal Org context. Create is rejected outside it.
+2. `create_reuse_promotion_request` with a non-empty `requesterComment`
+   (max 254 chars).
+   Reuse: prod `assetId` + Personal Org destination workspace. Promotion:
+   Personal Org `assetId` + the workspace that contains it.
+3. Poll **`get_promotion_reuse_request`** with the returned id (not an
+   unfiltered list). Reuse: wait for the terminal `completed` (not
+   `migrationSucceeded`, a transient intermediate a late poll skips); **STOP**
+   on `failed` / `cancelled` / `rejected` (`rejectionComment` when rejected).
+   Promotion: poll `packageExportStatus` for lowercase `ready` (10s × 30s
+   window); `status` stays `requested` throughout.
+4. Survey outstanding Reuse work with `list_promotion_reuse_requests` and
+   top-level `requestType=reuse` (not a `requestParams` wrapper). For one
+   known id, get-by-id.
+5. Promotion only, after user confirm: `create_promotion_pull_request`, then
+   the download / `sf` convert / copy / `gh pr create` recovery path in the
+   deep ref. Stop if `sf` is missing.

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

@@ -0,0 +1,39 @@
+# Task: Provision / list Tableau Next users / check licenses
+
+Grant, change, revoke, or deactivate a Tableau Next **role**, list users, or
+check license seats. This is org-admin work, not an asset share.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1**
+
+- **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`).
+- **ADMIN-ONLY.** Unauthorized → report and STOP. Do not fall back to
+  `search_users_and_groups` or share tools.
+- **Confirmation (this guide):** never call `upsert_user` on the request
+  turn. Preview per `../admin-users.md`, wait for an explicit yes.
+
+## When **not** to use these tools
+
+- **Share / revoke access on a dashboard, viz, workspace, or SDM** →
+  `share-asset.md` (`search_users_and_groups` + `add_asset_share` /
+  `remove_asset_share`). "Give Alice viewer access to this dashboard" is a
+  share, not a role grant.
+- **Workspace membership** (`add_workspace_asset`) is not a share and not
+  a role provision.
+
+## Steps
+
+Preview formats, ADD CONFLICT, rename-not-supported, remove≠DEACTIVATE,
+Personal Org `forceDeactivate`, and license `available=0` / `exhausted`
+are in **`../admin-users.md`**.
+
+1. **List / find users** — `get_users`. Omit `offset` on the first page;
+   paginate with `nextOffset`. Filters apply server-side.
+2. **Check seats** — `get_license_availability` before ADD or a role
+   upgrade. If `available` is 0 / `exhausted` is true, warn and stop.
+3. **Mutate** — only after a confirmed preview: `upsert_user` with the
+   admin-chosen `action` (`ADD` / `UPDATE` / `REVOKE` / `DEACTIVATE`).
+   ADD CONFLICT on existing email → do not silently retry as UPDATE.

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

@@ -0,0 +1,92 @@
+# Task: Query an existing model
+
+Pull figures from an already-built SDM via `run_semantic_query`: a plain count,
+total, or scalar ("how many / how much / what is total…"), a "give / run me the
+numbers" retrieval, or a structured table. The model does **not** have to be
+named up front — discover it with `list_semantic_models` when it isn't given.
+Prefer this over `analyze_data` whenever the user wants the figures themselves
+rather than an interpreted breakdown, ranking, trend, or comparison.
+
+Raw SQL against a DLO/DMO (`run_query`) also enters here when no SDM covers
+the data or the user asked for SQL — still prefer `run_semantic_query` when
+an SDM exists.
+
+Interpreted breakdowns, rankings, trends, and comparisons go to
+`analyze-data.md` / `analyze_data`. Scoring candidate SQL against expected
+SQL is `review-verified-questions.md` (`run_regression_evaluator`) — it
+does not query data.
+
+## Gates (assert before any tool call) → `../shared-gates.md`
+
+Required: **G1, G2, G3** · Conditional: **G4** (◐, if querying across objects),
+**G6** (◐, if you don't yet understand what the returned numbers mean)
+
+- **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`).
+- **G2:** the target object has rows (a query over an empty object returns empty).
+- **G3:** reference fields by their exact stored apiName — read back via `list_*`
+  if unsure; never invent a suffixed name.
+- **G4** (◐): only query across objects that are actually joined; do not set
+  `queryUnrelatedDataObjects:"Exception"` and query across unjoined objects.
+- **G6** (◐): if the additivity/grain of the returned numbers isn't understood,
+  profile first (`../data-understanding.md`).
+
+## Steps
+
+If the user did not name an SDM, call `list_semantic_models` and pick the
+matching populated model before querying.
+
+The proto-shaped `run_semantic_query` body, field-shape matrix, recovery strings,
+aggregation enum, detail-row, and `filter` XOR `flatten_filter` payloads are in
+**`../semantic-query-and-enrichment.md`**.
+
+- **Prefer `run_semantic_query` when an SDM exists** for the data. Fall back
+  to `run_query` (Data Cloud / Hyper SQL against a DLO `__dll` or DMO `__dlm`)
+  when the user asks for raw SQL, no SDM covers the tables, or you are
+  checking ingest materialization (`ingest-and-metric-gotchas.md` §A).
+  Discover SQL table names from `list_semantic_model_data_objects`
+  `dataObjectName` when an SDM is in play — that value already includes the
+  suffix and is ground truth. Otherwise use the suffixed DLO/DMO developer
+  name (`__dll` DLO, `__dlm` DMO). A bare DMO name (no `__dlm`) fails with
+  `42P01` / "table does not exist". Double-quote reserved words and names
+  with spaces.
+  `run_query` is Hyper SQL (full SELECT / WHERE / GROUP BY / JOIN /
+  aggregates / windows). That is a **different** engine from the SparkInternal
+  DCSQL subset on `create_data_transform` / `update_data_transform` — do not
+  copy those unsupported-op restrictions onto `run_query`, or vice versa.
+  `run_query` returns the **first chunk only** — if `returnedRows` looks short
+  or `status.completionStatus` is not `Finished`, say so and narrow with WHERE
+  / a lower `rowLimit`. Pagination tools (`query_data_status`, `query_data_rows`)
+  are not available. Response `data` is an array of **row arrays** (values in
+  `metadata` order), not row objects — join column names/types from the
+  separate `metadata` array.
+  Bind user input with `:name` placeholders and `sqlParameters` (the `name`
+  field is `"p1"` for `:p1`, no colon). `name` and `value` are required on every
+  parameter; `value` is always a serialized **string**. `type` defaults to
+  Varchar — set Integer / BigInt / Double / Boolean / Date / DateTime for
+  non-string columns (`type` tells the server how to interpret the string).
+  `dataspace` is optional; omitting it targets **default**. In a
+  multi-dataspace org that is easy to get wrong — pass the dataspace that
+  actually holds the `__dll` / `__dlm` (same name used on create/mapping)
+  rather than assuming default.
+
+- Pass **ONE** of `structuredSemanticQuery` (recommended) **OR**
+  `structuredMetricQuery` — mutually exclusive. Prefer an existing metric
+  (`structuredMetricQuery`) / calc measure over reconstructing a `SUM(...)`
+  aggregation inline.
+- Write the semantic-query body in **snake_case proto** shape (`table_field`,
+  `grouping`, `semantic_aggregation_method`) — REST-gateway camelCase examples
+  fail here.
+- Group by the correct date grain (e.g. month), not by a raw timestamp.
+- Query is org-level / SDM-level — it does **NOT** take a `workspaceId`. Any SDM
+  visible via `list_semantic_models` is queryable regardless of workspace.
+- Provisioning is gated on `orgHasDataCloudReportingEnabled` /
+  `orgHasSemanticQuery`. A permission error is a **provisioning gap**, not a
+  caller payload bug.
+- **Display:** 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.
+
+This is a read/query entry point — it does not model, enrich, or visualize. If the
+answer needs a chart, continue to `create-viz.md` (which re-asserts G7 before
+charting).