@agent-native/core-corpus 0.209.0 → 0.209.1-nightly-20261015033458

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 12297
+- template files: 12422

package/corpus/templates/analytics/.agents/skills/adhoc-analysis/SKILL.md

@@ -63,7 +63,7 @@ Use the available actions to pull data. Read the relevant `.agents/skills/<provi
 **Tips for data gathering:**
 
 - Start with the primary source (e.g., HubSpot for deals), then enrich with secondary sources
-- For named deal/account deep dives, call `account-deep-dive` first with the
+- For the CRM side of named deal/account deep dives, call `account-deep-dive` first (ask what was said in Gong calls with `run-gong-native-insight`) with the
   account, company, domain, deal, or opportunity name. It returns HubSpot deals,
   associated companies/contacts/tickets/notes/emails, Gong call detail, compact
   transcript excerpts, coverage counts, and gaps. Use targeted `hubspot-records`

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -235,6 +235,34 @@ catalog template. Existing dashboards remain readable while the native
 replacement is validated. Bespoke interaction flows, arbitrary layouts, and
 visualizations outside these contracts may remain Custom Blocks.
 
+## Sigma workbook import
+
+The dashboard menu opens the Sigma import flow, where users can browse and
+preview workbooks. Imports remain disabled for elements whose source project
+Analytics cannot verify: Sigma's connection API reports provider type and
+metadata but does not expose a BigQuery project identifier. Do not call
+`migrate-sigma-workbook` for an unverified source or treat an Analytics
+BigQuery credential as proof that it targets Sigma's project. Users can list
+workbooks with `list-sigma-workbooks` and inspect one with
+`inspect-sigma-workbook`. The feature is controlled by
+`analytics.sigma-dashboard-migration` and requires a Sigma connection granted
+to Analytics.
+
+Use an existing Dispatch Sigma connection when it is granted to Analytics; the
+import flow discovers accessible connections without copying their Vault
+values. If direct setup is needed, an organization owner or admin can enter
+Sigma client credentials in the Analytics dialog. Analytics saves those values
+under Analytics-specific encrypted organization secrets and links them to an
+Analytics-only connection. Credential values must never pass through agent chat,
+action arguments, logs, source, or screenshots.
+
+If Sigma adds verifiable source mapping in the future, the planned import will
+create a private snapshot in the user's personal `Sigma` folder. Other source
+types and unsupported elements will become review callouts. Preserve migration
+warnings and never describe a future result as parity-complete or automatically
+synchronized. Sigma's workbook-code API is public Beta and can omit unsupported
+workbook features before inspection receives the response.
+
 The source tree ships four provider-free v2 manifests in
 `server/lib/native-v2-dashboards.ts`: Customer ROI, Account Engagement,
 Cross-sell, and Win / Loss. They intentionally contain no customer names,
@@ -356,6 +384,8 @@ An unwrapped `{{<id>:list}}` with no selection fails the query on purpose. Optio
 
 Filters auto-apply on change — there is no Apply button. Each filter change writes to the URL and re-runs the affected panels. Other filters are preserved (the URL update is functional, not destructive). If you see a filter "reset" itself when another filter changes, look for a duplicate `id` first.
 
+**Reset filters** in the filter bar returns the dashboard to what a fresh load shows: the default saved view when the dashboard has one, otherwise each filter's own `default`. It shows only while a filter's resolved value differs from that, so `f_timeRange=30d` on a 30d-default filter counts as reset. To reset for the user with `set-search-params`, remove every `f_` param and `view`, or set the default view's params and `view=<id>`.
+
 ## Modifying A Dashboard
 
 For existing dashboard edits, default to `mutate-dashboard`. It gives the

package/corpus/templates/analytics/.agents/skills/data-querying/SKILL.md

@@ -149,7 +149,7 @@ pnpm action account-deep-dive --query="The Knot" --days=180 --gongLimit=10 --tra
 # HubSpot contacts or companies
 pnpm action hubspot-records --objectType=companies --query=builder.io --properties=name,domain,lifecyclestage
 
-# Gong call content for a customer deep dive
+# Gong call evidence (quotes, counts); ask run-gong-native-insight first for "what did they say"
 pnpm action gong-calls --company="The Knot" --days=180 --includeTranscripts=true --transcriptLimit=5
 ```
 
@@ -160,10 +160,13 @@ endpoint/filter a shortcut can't express) have **no bespoke action** — reach
 them through the shared provider API escape-hatch pattern:
 `provider-api-catalog` / `provider-api-docs` to learn the endpoint, then
 `provider-api-request` (or `providerFetch` inside `run-code`) against the
-provider's real HTTP API. For broad/corpus-wide questions ("how many", "which",
-"any/none across all …") prefer this raw-API + `run-code` path from the first
-step — fetch the full cohort with `fetchAllPages`/`saveToFile` and
-grep/aggregate locally — rather than stretching a capped shortcut action.
+provider's real HTTP API. Ask the provider to do the work first: use its own
+search or semantic tool, or a server-side filter on a bounded window (for
+Gong, `run-gong-native-insight`). Only for exhaustive coverage, exact counts, or
+an absence claim ("how many", "any/none across all …") stage the raw API
+response with `stageAs`/`saveToFile` and reduce it with `query-staged-dataset`
+or `run-code`, rather than stretching a capped shortcut action or paging by
+hand to filter locally.
 
 ### Writing Ad-Hoc Scripts
 
@@ -194,7 +197,7 @@ For complete answers, combine data from multiple sources:
 - **BigQuery** for analytics events, signups, pageviews
 - **First-party Analytics** (`query-agent-native-analytics`) for events collected through `/track`
 - **HubSpot** for CRM data — `hubspot-records` for contacts/companies/tickets/general lookup; `hubspot-deals` and `hubspot-metrics` for pipeline and revenue analysis
-- **Gong** for sales-call evidence — use `gong-calls` with `includeTranscripts=true` for deep dives, objections, risks, or next steps
+- **Gong** for sales-call evidence — ask `run-gong-native-insight` first for what was said, risks, objections, or next steps; use `gong-calls` with `includeTranscripts=true` for quotes, counts, or when native operations are not connected
 - **Jira** for engineering metrics — tickets, sprints
 - **GitHub** for code metrics — PRs, reviews
 - **Agent-Native Analytics Monitoring -> Errors** for first-party captured

package/corpus/templates/analytics/.agents/skills/gong/SKILL.md

@@ -10,29 +10,47 @@ description: >-
 Use Gong for sales-call evidence. Call metadata alone is not enough for a deep
 dive that asks what happened in customer conversations.
 
+## Answer Questions With Gong's Own Search First
+
+Gong's MCP (`ask_account`, `ask_deal`, `generate_brief`) searches and analyzes
+the calls server-side and answers in seconds. That is how Claude answers Gong
+questions, and it is the default here too.
+
+- A question about an account, deal, customer, competitor, or topic ("what did
+  X say about Y", risks, objections, themes, next steps, call prep) →
+  `run-gong-native-insight` first, one consolidated call. Do not page `/calls`
+  or `/calls/extensive`, and do not pull transcripts, to answer a question.
+- Reach for the raw paths below only when the user needs verbatim quotes, an
+  exact count, or proof that something was absent across all calls, or when the
+  native operations are not connected (`gong-native-insights` lists them).
+- If a blocking Gong request returns a size-limit error, stop paging and switch
+  to the native operation or a narrower `gong-calls` search. Never retry the
+  same wide window.
+
 ## Actions
 
 - `gong-native-insights` — lists the connected provider-native qualitative
   synthesis operations (`ask_account`, `ask_deal`, `generate_brief`) and their
   schemas. It never calls Gong AI or spends a credit request.
 - `run-gong-native-insight` — sends one of those operations through Gong's
-  connected MCP. Use it for themes, risks, summaries, and deck narrative when
-  the native tools are connected. One invocation makes at most one Gong AI
-  request; set `allowCreditRequest=true` only for the one consolidated request
-  you intend to send, and each paid request asks for approval. Paid calls also
-  require a workspace owner to enable them once with
-  `configure-gong-native-insights`; the policy defaults off and disabling it
-  never blocks the raw evidence path.
-- `account-deep-dive` — first choice for named account/deal deep dives that
-  need HubSpot plus Gong. It searches by account/deal/company/contact domain,
-  loads Gong call details, and returns compact transcript excerpts for synthesis.
+  connected MCP. This is the first choice for questions, themes, risks,
+  summaries, and deck narrative when the native tools are connected. One
+  invocation makes one Gong AI request (one credit request), so put related
+  sub-questions in one call. It is on by default; a workspace owner can turn it
+  off with `configure-gong-native-insights`, which never blocks the raw
+  evidence path.
+- `account-deep-dive` — first choice for a named account/deal when the answer
+  needs HubSpot CRM context alongside Gong. For a question about what was said
+  in the calls, use `run-gong-native-insight` first. It searches by
+  account/deal/company/contact domain, loads Gong call details, and returns
+  compact transcript excerpts for synthesis.
 - `gong-calls` — bounded convenience reads: list recent calls, search by
   company/domain/person/email, fetch a single transcript by call ID, or return
   transcript excerpts for a small matching cohort. Its `transcriptQuery` is a
   local scan after batched transcript retrieval, not Gong's server-side
   keyword search.
 
-For broad or absence-sensitive Gong work, prefer the raw provider API surface:
+For exhaustive, count, or absence-sensitive Gong work, use the raw provider API surface:
 use `provider-api-catalog` / `provider-api-docs`, then stage `/calls/extensive`
 or another raw endpoint with `provider-api-request`. Reduce staged tracker or
 call data with `query-staged-dataset` or a Data Program. Use
@@ -41,14 +59,15 @@ native/indexed search can answer the question.
 
 ## Route Synthesis and Evidence Separately
 
-- Use `run-gong-native-insight` for qualitative synthesis where Gong may retrieve
-  and analyze evidence internally. Its result is provider synthesis: coverage
-  is unknown and raw transcript evidence is unavailable.
+- Use `run-gong-native-insight` to answer the question where Gong retrieves
+  and analyzes evidence internally. Its result is provider synthesis: coverage
+  is unknown and raw transcript evidence is unavailable, so say that when the
+  user asked for completeness.
 - Use `gong-calls` or `provider-corpus-job` for quotes, exact counts, transcript
   records, coverage-sensitive claims, and proof that something was absent.
 - Consolidate related native questions into one narrowly scoped request. Each
-  native operation independently consumes Gong credits, so do not make one call
-  per slide, bullet, or sub-question.
+  native operation independently consumes a Gong credit request, so do not make
+  one call per slide, bullet, or sub-question.
 - From a sibling app, ask Analytics a natural-language question by default.
   Analytics owns Gong/HubSpot routing, source coverage, credentials, transcript
   strategy, joins, and synthesis. Use `call-agent`'s direct `action` + `input`
@@ -90,8 +109,10 @@ When analyzing customer sentiment, objections, or voice of the customer:
 
 For account or deal deep dives:
 
-1. Call `account-deep-dive` first when the request also needs CRM context,
-   contacts, stages, amount, close date, or an overall opportunity narrative.
+1. Ask `run-gong-native-insight` first for what customers said, risks,
+   objections, and next steps. Call `account-deep-dive` first when the request
+   also needs CRM context, contacts, stages, amount, close date, or an overall
+   opportunity narrative, or when native operations are not connected.
 2. Use `gong-calls` for targeted follow-up searches by account name, domain,
    person, or email.
 3. Set `includeTranscripts=true` when the user asks for context, risks,

package/corpus/templates/analytics/.agents/skills/hubspot/SKILL.md

@@ -26,7 +26,8 @@ actions do not expose, inspect the provider catalog/docs and call
 
 ## Actions
 
-- `account-deep-dive` — first choice for named account/deal deep dives. It
+- `account-deep-dive` — first choice for the CRM side of a named account/deal
+  deep dive (use `run-gong-native-insight` for what was said in calls). It
   searches matching HubSpot deals, loads associated companies, contacts,
   tickets, notes, and emails, then pairs that CRM context with Gong evidence.
 - `hubspot-deals` — deals with normalized stage, pipeline, owner, forecast, and

package/corpus/templates/analytics/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","analytics-alert-jobs","analytics-rollup-backfill-jobs","auth","collab","config","core-routes","creative-context","dashboard-report-jobs","db","feature-flags","labs","onboarding","otel","session-replay-retention-jobs","transactional-emails","uptime-monitor-jobs"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/analytics/AGENTS.md

@@ -15,13 +15,13 @@ Use local docs only (no web research): `pnpm action docs-search --query "<topic>
 - Use one bounded SQL or server-side `run-code` call for lists, filters, counts, or cohorts. If the catalog misses, call `find-data` once, then inspect exact metadata with `search-bigquery-schema` or provider status only when needed; do not fan out per item or add unasked breakdowns.
 - For an exact owner-defined dbt metric, use `query-dbt-semantic-metric` when a dbt workspace connection is available. dbt defines metric meaning and grain; Sigma and Amplitude are examples and cross-checks. Do not infer an owner-approved metric from a model name or dashboard.
 - Answer shape: when a saved or certified dashboard answers, open with one line naming and linking it (`[Title](/dashboards/<id>)`) and how to read it there, then answer. Add a short "How it's computed" note (source, window, filters, sample size, caveats) only when it changes how to read the number. Show SQL, tables, or schema only when asked, when the user writes SQL or asks about tables or columns, or when no dashboard matches. Label figures “Unverified” if no live query ran; never cite the public `demo` source as real evidence unless asked.
-- Create or change saved artifacts only when asked. For named accounts, use `account-deep-dive`; for health, read `account-health`. When challenged on coverage, rerun from the source cohort and provide the updated answer.
+- Create or change saved artifacts only when asked. For a named account, use `run-gong-native-insight` for Gong and `account-deep-dive` for HubSpot context; for health, read `account-health`. When challenged on coverage, rerun from the source cohort and provide the updated answer.
 
 ## Core rules
 
 - UI feedback: target 100 ms, never exceed 400 ms; acknowledge before network work.
 - Sibling apps delegate metrics and product questions over A2A in natural language, never SQL. Analytics owns schema, source selection, and stable shaped reads.
-- Use actions for data and sharing; respect ownable access checks. Provider actions are shortcuts: for broad/absence-sensitive Gong work stage and reduce raw data with `query-staged-dataset` or a Data Program.
+- Use actions for data and sharing; respect ownable access checks. Provider actions are shortcuts; stage broad Gong scans with `query-staged-dataset` or a Data Program.
 - Reports/alerts use SQL actions and cap at five recipients. Store large payloads in file/blob storage, not SQL or app state.
 - Never invent data or source semantics. For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - For MCP, use allowlisted cataloged actions; use `ask_app` for interpretation, source selection, multi-step, or unsupported actions.

package/corpus/templates/analytics/actions/account-deep-dive.ts

@@ -366,7 +366,7 @@ async function loadGongEvidence(options: {
 
 export default defineAction({
   description:
-    "Build a bounded CRM/Gong account or deal evidence bundle from HubSpot and Gong. Use this first for named account, customer, deal, opportunity, renewal, risk, or deep-dive prompts. This is not a complete account-health result: for account health, follow it with verified product-usage queries for the resolved customer using the account-health skill.",
+    "Build a bounded CRM/Gong account or deal evidence bundle from HubSpot and Gong. Use it for the HubSpot CRM context of a named account, deal, or opportunity; ask run-gong-native-insight first for what was said in calls. This is not a complete account-health result: for account health, follow it with verified product-usage queries for the resolved customer using the account-health skill.",
   schema: z.object({
     query: z
       .string()

package/corpus/templates/analytics/actions/compose-dashboard.ts

@@ -178,6 +178,10 @@ export default defineAction({
       height: 680,
     }),
   },
+  // Append skips ids already present and merges onto the latest row, so a replay
+  // adds nothing. Overwrite and refreshExisting replace panels with no revision
+  // fence, so a replay could erase an edit made between calls.
+  retrySafe: (input) => !input.overwrite && !input.refreshExisting,
   run: async (args, actionContext?: ActionRunContext) => {
     const email = getRequestUserEmail();
     if (!email) throw new Error("no authenticated user");

package/corpus/templates/analytics/actions/configure-gong-native-insights.ts

@@ -5,7 +5,7 @@ import { writeGongNativeInsightsPolicy } from "../server/lib/gong-native-policy"
 
 export default defineAction({
   description:
-    "Enable or disable paid Gong native semantic operations for the current workspace. Enabling this permits individually authorized run-gong-native-insight calls to consume Gong credits; it does not send a Gong request by itself. Disable it to fail closed for every semantic request while keeping raw Gong evidence actions available.",
+    "Turn Gong native semantic operations on or off for the current workspace (organization owners and admins only). They are on by default; each run-gong-native-insight call consumes one Gong credit request. Turn them off to block every semantic request while keeping raw Gong evidence actions available.",
   schema: z.object({
     enabled: z
       .boolean()
@@ -22,7 +22,7 @@ export default defineAction({
       ...policy,
       creditRequests: 0,
       guidance: enabled
-        ? "Gong native semantic requests are enabled for this scope. Each request still requires allowCreditRequest=true and independently consumes Gong credits."
+        ? "Gong native semantic requests are enabled for this scope. Each request independently consumes one Gong credit request."
         : "Gong native semantic requests are disabled. Use gong-calls or the provider corpus evidence path.",
     };
   },

package/corpus/templates/analytics/actions/dashboard-mutation-api.ts

@@ -977,7 +977,16 @@ export function applyDashboardMutationOperations(
         case "removePanels": {
           const ids = uniqueStrings(op.panelIds);
           const panels = panelsFromConfig(config);
-          for (const id of ids) requirePanel(panels, id);
+          for (const id of ids) {
+            // A remove replayed after its first attempt committed finds the
+            // panel gone; say so, so the model checks instead of retrying.
+            if (findPanelIndex(panels, id) < 0) {
+              fail(
+                `${missingPanelHelp(panels, id)} If an earlier attempt already removed it, the dashboard is already in the requested state; confirm with get-sql-dashboard instead of retrying.`,
+                { errorCode: "dashboard_panel_not_found", statusCode: 404 },
+              );
+            }
+          }
           config.panels = panels.filter(
             (panel) => !ids.includes(panelId(panel)),
           );

package/corpus/templates/analytics/actions/find-data.ts

@@ -9,6 +9,7 @@ import { searchAnalyticsQueryCatalog } from "../server/lib/analytics-query-catal
 import type {
   SourceIndexFreshness,
   SourceIndexScanCoverage,
+  SourceIndexSourcesFreshness,
 } from "../server/lib/source-index-store.js";
 
 function countLabel(
@@ -58,9 +59,25 @@ function sourceIndexFreshnessGuidance(
   return `The generated source index is stale (${freshness.ageDays} days old; refresh threshold ${freshness.staleAfterDays} days). Use its entries only to discover leads; do not treat its definitions, grain, joins, or omissions as current. Verify current schema and owner-approved definitions before querying.`;
 }
 
+function sourceIndexSourcesFreshnessGuidance(
+  status: "not-configured" | "unavailable" | "invalid" | "available",
+  freshness: SourceIndexSourcesFreshness | null,
+): string {
+  if (status !== "available") return "";
+  if (
+    freshness?.fresh === true &&
+    freshness.sourceCount > 0 &&
+    freshness.unknownTimestampCount === 0 &&
+    freshness.staleSourceCount === 0
+  ) {
+    return "";
+  }
+  return "Per-source source-index freshness is stale or unknown. Treat missing references as inconclusive and verify current schema or source metadata before reporting that no matching source exists.";
+}
+
 export default defineAction({
   description:
-    "Find definitions, dashboard SQL, and source-index references. Returns ranked metadata, source-index freshness and scan coverage, never live values. Treat stale generated entries as discovery hints; use `search-bigquery-schema` for exact columns or partitions, then run one live query before reporting values.",
+    "Find definitions, dashboard SQL, and source-index references. Returns ranked metadata, freshness and coverage, not live values. For rosters, use row-grain sources over aggregates. Stale generated entries are hints; use `search-bigquery-schema` for columns or partitions, then query live before reporting.",
   schema: z.object({
     question: z
       .string()
@@ -103,16 +120,21 @@ export default defineAction({
       result.sourceIndexStatus,
       result.sourceIndexFreshness,
     );
+    const sourceFreshnessGuidance = sourceIndexSourcesFreshnessGuidance(
+      result.sourceIndexStatus,
+      result.sourceIndexSourcesFreshness,
+    );
     return {
       question,
       results: candidates,
       ...paginationAndCoverage,
       resultType: "reference-metadata",
       guidance: [
-        "Treat saved SQL and source-index entries as examples or unapproved metadata. Verify source scope, live schema, partitions, and current values before answering. If truncated is true and nextPage is present, continue with that cursor; if truncated is true and nextPage is null, refine the search or use an explicit dashboard/schema search because a source cap was reached.",
+        "Treat saved SQL and source-index entries as examples or unapproved metadata. Verify source scope, live schema, partitions, and current values before answering. For rosters, exclude aggregates and snapshots as member sources. If none remain, report no row-grain source and check index coverage or schema. If truncated is true and nextPage is present, continue with that cursor; if truncated is true and nextPage is null, refine the search or use an explicit dashboard/schema search because a source cap was reached.",
         sourceIndexGuidance,
         scanGuidance,
         freshnessGuidance,
+        sourceFreshnessGuidance,
       ]
         .filter(Boolean)
         .join(" "),

package/corpus/templates/analytics/actions/gong-native-insights.ts

@@ -8,7 +8,7 @@ import {
 
 export default defineAction({
   description:
-    "List the Gong native semantic operations (ask_account, ask_deal, generate_brief) connected in this request scope, with their input schemas. This never calls Gong AI or consumes Gong credits. To send one paid qualitative synthesis request, call run-gong-native-insight with the chosen operation. For transcripts, quotes, counts, source records, or absence/exhaustive claims use gong-calls or the provider corpus evidence path instead.",
+    "List the Gong native semantic operations (ask_account, ask_deal, generate_brief) connected in this request scope, with their input schemas. This never calls Gong AI or consumes Gong credits. Call run-gong-native-insight with the chosen operation to answer a question about an account, deal, or topic. For verbatim quotes, exact counts, or absence/exhaustive claims use gong-calls or the provider corpus evidence path instead.",
   // Paid execution moved to run-gong-native-insight. Reject its arguments here
   // instead of silently returning a listing to an older caller.
   schema: z.strictObject(

package/corpus/templates/analytics/actions/inspect-sigma-workbook.ts

@@ -0,0 +1,170 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  inspectSigmaWorkbook,
+  type SigmaPortableElement,
+  type SigmaWorkbookInspection,
+} from "../server/lib/bi-migration/sigma-adapter.js";
+import { resolveSigmaConnectionSelection } from "../server/lib/bi-migration/sigma-connections.js";
+import { requireSigmaMigrationContext } from "../server/lib/bi-migration/sigma-migration.js";
+
+const inspectSchema = z.object({
+  workbookId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .regex(/^[A-Za-z0-9_-]+$/)
+    .describe("Sigma workbook ID returned by list-sigma-workbooks."),
+  connectionId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Selected connected Sigma workspace connection, when needed."),
+});
+
+export type SigmaElementReviewReason =
+  | "unsupported_element"
+  | "unsupported_source"
+  | "source_unavailable"
+  | "source_mapping_required"
+  | "query_unavailable"
+  | "unsafe_sql"
+  | "visualization_review";
+
+export interface SigmaElementReview {
+  id: string;
+  name: string;
+  type: string;
+  importable: boolean;
+  visualizationPreserved: boolean;
+  reason?: SigmaElementReviewReason;
+}
+
+function reviewElement(
+  element: SigmaPortableElement,
+  inspection: SigmaWorkbookInspection,
+): SigmaElementReview {
+  if (element.kind !== "panel") {
+    return {
+      id: element.id,
+      name: element.title,
+      type: element.sigmaKind,
+      importable: false,
+      visualizationPreserved: false,
+      reason: "unsupported_element",
+    };
+  }
+
+  const connection = inspection.sourceConnections.find(
+    (source) => source.connectionId === element.source?.connectionId,
+  );
+  if (!connection || connection.targetProviderCandidate !== "bigquery") {
+    const sourceUnavailable = inspection.diagnostics.some(
+      (diagnostic) =>
+        diagnostic.code === "sigma_source_connection_unavailable" &&
+        diagnostic.connectionId === element.source?.connectionId,
+    );
+    return {
+      id: element.id,
+      name: element.title,
+      type: element.chartType,
+      importable: false,
+      visualizationPreserved: false,
+      reason: sourceUnavailable ? "source_unavailable" : "unsupported_source",
+    };
+  }
+
+  // Sigma reports the provider type, but the current connection API does not
+  // establish that this Analytics credential points at the same project.
+  return {
+    id: element.id,
+    name: element.title,
+    type: element.chartType,
+    importable: false,
+    visualizationPreserved: false,
+    reason: "source_mapping_required",
+  };
+}
+
+export function summarizeSigmaElementReview(args: {
+  inspection: SigmaWorkbookInspection;
+}): SigmaElementReview[] {
+  return args.inspection.elements.map((element) =>
+    reviewElement(element, args.inspection),
+  );
+}
+
+export function requireSigmaSourceInspection(
+  inspection: SigmaWorkbookInspection,
+): void {
+  if (
+    inspection.diagnostics.some((diagnostic) => diagnostic.severity === "error")
+  ) {
+    fail(
+      "Sigma source connection details could not be verified. Retry the workbook preview.",
+      {
+        errorCode: "sigma_source_inspection_failed",
+        statusCode: 503,
+      },
+    );
+  }
+}
+
+export default defineAction({
+  description:
+    "Preview a Sigma workbook without returning SQL or workbook payloads. Sigma imports remain preview-only because the current connection API does not expose a BigQuery project mapping Analytics can verify.",
+  schema: inspectSchema,
+  http: { method: "GET" },
+  readOnly: true,
+  mcpTool: false,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    await requireSigmaMigrationContext();
+    const selection = await resolveSigmaConnectionSelection(args.connectionId);
+    if (!selection.selected) {
+      fail("Select a connected Sigma workspace connection first.", {
+        errorCode: "sigma_connection_required",
+        statusCode: 400,
+      });
+    }
+    const inspection = await inspectSigmaWorkbook({
+      connectionId: selection.selected.id,
+      workbookId: args.workbookId,
+      includeSqlQueries: false,
+    });
+    requireSigmaSourceInspection(inspection);
+    const elements = summarizeSigmaElementReview({
+      inspection,
+    });
+    const importableCount = elements.filter(
+      (element) => element.importable,
+    ).length;
+    const unsupportedCount = elements.length - importableCount;
+    const reviewRequiredCount = elements.filter(
+      (element) =>
+        !element.importable || element.reason === "visualization_review",
+    ).length;
+    const sourceMappingRequiredCount = elements.filter(
+      (element) => element.reason === "source_mapping_required",
+    ).length;
+    return {
+      workbook: {
+        id: inspection.workbook.workbookId,
+        name: inspection.workbook.name,
+        updatedAt: inspection.workbook.updatedAt,
+      },
+      connectionId: selection.selected.id,
+      connectionLabel: selection.selected.label,
+      importableCount,
+      unsupportedCount,
+      reviewRequiredCount,
+      sourceMappingRequiredCount,
+      elements,
+      betaRepresentationWarning: true,
+    };
+  },
+});