@salesforce/afv-skills 1.59.0 → 1.61.0

package/skills/tableau-next-asset-create/references/tasks/review-verified-questions.md

@@ -0,0 +1,42 @@
+# Task: Review verified questions / score agent SQL
+
+List or classify Analytic Verified Questions, manage utterance records, or
+score candidate SQL against expected SQL. Do **not** use this to answer a
+business question (`query-model.md` / `analyze-data.md`) or to backfill
+readiness metadata (`ai-readiness-audit.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):** `delete_analytics_utterances` is
+  irreversible — confirm first.
+
+## When **not** to use these tools
+
+- **"What is total revenue" / live figures** → `query-model.md`.
+- **Interpreted breakdown / trend** → `analyze-data.md`.
+- **"Is my model AI-ready" / backfill descriptions** →
+  `ai-readiness-audit.md`.
+
+## Steps
+
+Filters, `classificationStatus` enum, `fetchInteractions` / only-surface-
+`query`, classify NPE if `interaction` omitted, utterance CRUD, and
+evaluator caveats are in **`../verified-questions.md`**.
+
+1. **List / audit** — `list_analytics_interactions` once for all models
+   (do not loop per SDM). Paginate with `offset`. Default sort
+   `lastModifiedDate DESC` when recency matters.
+2. **One classified question** — `get_analytics_full_interaction` by
+   utterance API name. Not for unclassified questions.
+3. **Verify / reject status** — `classify_analytics_interactions`. For
+   payload edits, `update_and_classify_analytics_interaction` (always send
+   `interaction`).
+4. **Question text only** — utterance get/create/update/delete tools. Do
+   not set `agentId` on create.
+5. **Score SQL** — `run_regression_evaluator` once per Q&A pair. Requires
+   expected + actual SQL + `dataspace`. Persists nothing.

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

@@ -0,0 +1,37 @@
+# Task: Share or revoke access to a Tableau Next asset
+
+Grant, inspect, change, or revoke a **user or group** share on a dashboard,
+visualization, workspace, or semantic model. This is not workspace
+membership (`add_workspace_asset` / `remove_workspace_asset`) and not
+deleting the asset itself.
+
+## 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):** show recipient + asset + `accessType` and
+  wait for an explicit yes before `add_asset_share` or `update_asset_share`.
+  `remove_asset_share` is destructive — the user **loses access immediately**.
+  Confirm first.
+- Granting a Tableau Next **role** (Analyst, Admin, …) is `provision-user.md`,
+  not this guide.
+
+## Steps
+
+Lookup, access-level matrix, Personal Org rules, partial-batch / silent-204
+recovery, and wrap vs unwrap are in **`../sharing-and-promotion.md`** (§Share).
+
+1. Resolve the asset `recordId` (Salesforce id, not apiName/label) from
+   `get_dashboard` / `get_visualization` / `list_workspaces` /
+   `get_semantic_model`.
+2. **New grant:** search_users_and_groups first (name or email →
+   `userOrGroupId`). Then `add_asset_share` with `applicationDomain: "Tableau"`
+   and an `accessType` allowed for that `setupObjectType`.
+3. **Inspect / verify / change / revoke:** list_asset_shares first. Update
+   and remove use the listed `userOrGroupId` (Personal Org: the **shadow ID**).
+   To **revoke access entirely**, call `remove_asset_share` — do not set a
+   weaker `accessType` on update.
+4. Always read `failedRecordShares` on add/update. After remove, list again
+   if you need to prove the row is gone (HTTP 204 is not proof).

package/skills/tableau-next-asset-create/references/verified-questions.md

@@ -0,0 +1,125 @@
+# Verified questions, utterances, and regression eval
+
+Load this from `tasks/review-verified-questions.md`. Not a first hop.
+
+Analytic Verified Questions (AVQ) and SQL calibration. This is **not**
+AI-readiness metadata (`tasks/ai-readiness-audit.md`), **not**
+`run_semantic_query` (`query-model.md`), and **not** `analyze_data`.
+
+The MCP tools are namespaced per server — names here are bare; use whichever
+server prefix is connected. All of these are **current org only**.
+
+## Contents
+
+- List / get interactions
+- Classify / update-and-classify
+- Utterance CRUD (question text only)
+- `run_regression_evaluator` (score SQL, persist nothing)
+
+---
+
+## `list_analytics_interactions`
+
+Enumerate question/answer pairs. **Covers ALL models in one query — never
+loop per SDM.** Omit `semanticModels` unless the user asked to filter to a
+specific model. Pagination is separate: a single call still returns at most
+`limit` rows; keep calling with advancing `offset` until a page is empty (or
+you have the reported total).
+
+**Inputs (all optional):**
+
+- `limit`, `offset`
+- `orderBy` — e.g. `lastModifiedDate DESC`
+- `classificationStatus` — `New` | `Regression` | `Inaccurate` | `Verified`
+  | `NeedsValidation`
+- `semanticModels` — comma-separated IDs/apiNames; omit for all models
+- `agentType` — `Concierge` | `Inspector`
+- `sourceType` — `Csv` | `Feedback` | `Generated` | `Manual`
+- `fetchInteractions` — default `false`. `false` = questions without agent
+  responses/SQL; `true` when agent response data is needed
+- `utterance` — search string
+- `isRequiresReview` — classifications needing review
+- `agentResponse` — `Nl2Sql` | `Waii`
+
+**Returns:** `items[]` with utterance, classification, semantic model,
+timestamps, and (when fetched) agent response.
+
+**When `fetchInteractions=true`:** surface **only** the `query` property of
+the agent interaction data to the user. Do not dump the rest of that
+payload.
+
+**Use when:** browse, search, or audit past interactions and classification
+status.
+
+---
+
+## `get_analytics_full_interaction`
+
+Full payload for **one** classified interaction, by utterance API name
+(from `list_analytics_interactions`).
+
+Returns utterance text, classification status, semantic model, agent
+response, and associated interaction data.
+
+**Use when:** the user wants full details of a question that already has a
+classification (reviewed / verified / rejected). **Do not** use this for
+new or unclassified questions.
+
+---
+
+## `classify_analytics_interactions`
+
+Update one or many classifications in a single request (verify, reject, or
+change status). Each item is identified by classification ID plus the
+fields to change.
+
+---
+
+## `update_and_classify_analytics_interaction`
+
+Update an interaction-with-classification record by classification ID
+(path).
+
+**Required:** `interaction` (e.g. `analyticsUtteranceId`, `agentUtterance`,
+`sources`) — even for classification-only updates. Omitting it causes a
+**500 NPE**, not a validation error.
+
+When the user asks to update a question with a SQL query, set SQL as
+`agentInteractionData` wrapped as an escaped JSON string:
+`{"query": "<escaped SQL>"}`. `agentResponse`: if the SQL starts with
+`WITH`, set `Waii`; otherwise `Nl2Sql`.
+
+---
+
+## Utterance CRUD (question text only)
+
+These operate on the **utterance** (question text/metadata). They do **not**
+create, update, or delete the interaction / agent response / classification.
+
+| Tool | Notes |
+|---|---|
+| `get_analytics_utterance` | By API name. Returns text, agent type, source type, model API name, status. |
+| `create_analytics_utterances` | Collection of utterances (text + model API name, agent type, source type). **Do not set `agentId`** — utterances must not be tied to a specific agent. |
+| `update_analytics_utterance` | By API name. Fields: utterance text, model API name, agent type, source type. |
+| `delete_analytics_utterances` | Collection of utterance API names. **DESTRUCTIVE — no undo.** Confirm first. Does not directly delete the interaction or classification. |
+
+---
+
+## `run_regression_evaluator`
+
+Score one Q&A calibration pair: candidate agent SQL
+(`actualAgentResponse`) vs expected SQL (`expectedAgentResponse`) for the
+same question.
+
+**Required:** `semanticModelApiName` (full model resolved server-side),
+`utterance`, `dataspace`, `actualAgentResponse`, `expectedAgentResponse`.
+
+**Returns:** `success` (`true` if candidate matches baseline) and
+`explanation` (human-readable rationale).
+
+**Caveats:**
+
+- **Evaluation-only** — scores a single test and **persists nothing**.
+- One Q&A pair per call; batch by calling once per pair.
+- Not a substitute for `run_semantic_query` or `analyze_data`. Those run
+  live questions against data; this compares two SQLs.