@databrainhq/mcp-server 0.2.10 → 0.2.12

package/dist/index.js

@@ -8,7 +8,8 @@ import { z, ZodError } from "zod";
 var configSchema = z.object({
   serviceToken: z.string().min(1).optional(),
   apiToken: z.string().min(1).optional(),
-  apiUrl: z.string().url().default("https://api.usedatabrain.com")
+  apiUrl: z.string().url().default("https://api.usedatabrain.com"),
+  demoDomain: z.string().url().default("https://demo.usedatabrain.com")
 }).refine((c) => c.serviceToken || c.apiToken, {
   message: "At least one of DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN must be set"
 });
@@ -19,8 +20,10 @@ function formatConfigError(err) {
     lines.push(`  - ${issue}`);
   }
   lines.push("");
-  lines.push("  Get a service token at Settings > Service Tokens in your Databrain dashboard.");
+  lines.push("  Set DATABRAIN_SERVICE_TOKEN (Settings > Service Tokens) \u2014 org-level token for setup and management.");
   lines.push('  Then add to your MCP config: { "env": { "DATABRAIN_SERVICE_TOKEN": "..." } }');
+  lines.push("");
+  lines.push("  Self-hosted? Also set DATABRAIN_API_URL to your instance's API origin (e.g. https://api.your-databrain.example.com). Tokens minted on cloud do not work against a self-hosted instance and vice versa.");
   return lines.join("\n");
 }
 function loadConfig() {
@@ -28,7 +31,8 @@ function loadConfig() {
     return configSchema.parse({
       serviceToken: process.env.DATABRAIN_SERVICE_TOKEN || void 0,
       apiToken: process.env.DATABRAIN_API_TOKEN || void 0,
-      apiUrl: process.env.DATABRAIN_API_URL || "https://api.usedatabrain.com"
+      apiUrl: process.env.DATABRAIN_API_URL || "https://api.usedatabrain.com",
+      demoDomain: process.env.DATABRAIN_DEMO_DOMAIN || "https://demo.usedatabrain.com"
     });
   } catch (err) {
     if (err instanceof ZodError) {
@@ -78,13 +82,39 @@ var DatabrainApiError = class extends Error {
     this.name = "DatabrainApiError";
   }
   toToolResponse() {
+    const parts = [`Error: ${this.message}`];
+    const detailDump = this.formatDetails();
+    if (detailDump) parts.push(detailDump);
+    const hint = this.hint();
+    if (hint) parts.push(hint);
     return {
-      content: [{ type: "text", text: `Error: ${this.message}
-
-${this.hint()}` }],
+      content: [{ type: "text", text: parts.join("\n\n") }],
       isError: true
     };
   }
+  /**
+   * Surface API-returned details for 4xx errors so the LLM can recover or
+   * report the real reason (validation messages, field names, etc.). Skips
+   * fields already collapsed into `message`/`code`, and skips 5xx where the
+   * payload usually isn't actionable.
+   */
+  formatDetails() {
+    if (this.status < 400 || this.status >= 500) return "";
+    if (!this.details || typeof this.details !== "object") return "";
+    const skipKeys = /* @__PURE__ */ new Set(["message", "detail", "error", "code"]);
+    const extra = {};
+    for (const [k, v] of Object.entries(this.details)) {
+      if (skipKeys.has(k)) continue;
+      if (v === null || v === void 0) continue;
+      extra[k] = v;
+    }
+    if (Object.keys(extra).length === 0) return "";
+    try {
+      return `API details: ${JSON.stringify(extra)}`;
+    } catch {
+      return "";
+    }
+  }
   hint() {
     if (this.status === 401 || this.status === 403) {
       if (this.code === "INVALID_SERVICE_TOKEN" || this.code === "MISSING_SERVICE_TOKEN" || this.message.toLowerCase().includes("service token")) {
@@ -154,8 +184,10 @@ var logger = {
   error: (msg, data) => log("error", msg, data)
 };
 
+// src/version.ts
+var MCP_SERVER_VERSION = "0.2.10";
+
 // src/client/databrain-client.ts
-var MCP_SERVER_VERSION = "0.2.0";
 var MCP_USER_AGENT = `databrain-mcp-server/${MCP_SERVER_VERSION}`;
 var MAX_RETRIES = 3;
 var REQUEST_TIMEOUT_MS = 3e4;
@@ -188,12 +220,27 @@ var DatabrainClient = class {
   getApiUrl() {
     return this.config.apiUrl;
   }
+  getDemoDomain() {
+    return this.config.demoDomain;
+  }
+  /**
+   * Describes which credential is currently used as the bearer for outgoing
+   * API calls. Used by `whoami` so the LLM can give the user a truthful answer.
+   */
+  getActiveAuth() {
+    if (this.config.serviceToken) return { source: "service-token" };
+    if (this.runtimeApiToken || this.config.apiToken) return { source: "api-token" };
+    return { source: "none" };
+  }
   getToken(auth) {
     if (auth === "none") return void 0;
     if (auth === "service") return this.config.serviceToken;
     return this.runtimeApiToken || this.config.apiToken;
   }
   async request(options) {
+    return this.requestInternal(options);
+  }
+  async requestInternal(options) {
     if (options.invalidateCache) {
       for (const prefix of options.invalidateCache) {
         this.cache.invalidateByPrefix(prefix);
@@ -596,6 +643,69 @@ var QueryApi = class {
       throw err;
     }
   }
+  async startSemanticLayerGeneration(datamartId) {
+    return this.client.request({
+      method: "POST",
+      path: `/api/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/auto-generate`,
+      auth: "service",
+      invalidateCache: ["semantic_layer_"]
+    });
+  }
+  async getSemanticLayerGenerationStatus(datamartId) {
+    return this.client.request({
+      method: "GET",
+      path: `/api/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/generation-status`,
+      auth: "service"
+    });
+  }
+};
+
+// src/api/scheduled-reports-api.ts
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function normalizeRecords(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => asRecord(item) !== null);
+  }
+  const record = asRecord(value);
+  if (!record) return [];
+  const candidates = [
+    record.scheduleEmailReports,
+    record.reports,
+    record.items,
+    record.data
+  ];
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      return candidate.filter((item) => asRecord(item) !== null);
+    }
+  }
+  return [];
+}
+var ScheduledReportsApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async listByEmbed(params) {
+    const query = {
+      embedId: params.embedId,
+      clientId: params.clientId
+    };
+    if (params.userIdentifier) query.userIdentifier = params.userIdentifier;
+    if (params.pageNumber !== void 0) query.pageNumber = String(params.pageNumber);
+    if (params.isPagination !== void 0) {
+      query.isPagination = params.isPagination ? "true" : "false";
+    }
+    const response = await this.client.request({
+      method: "GET",
+      path: "/api/v2/data-app/embeds/reports",
+      auth: "api",
+      query
+    });
+    return normalizeRecords(response);
+  }
 };
 
 // src/api/widgets-api.ts
@@ -735,19 +845,19 @@ var DEFAULT_ACCESS_SETTINGS = {
 function isNonEmptyString2(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
-function asRecord(value) {
+function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
 function extractAccessSettings(embed) {
-  const metadata = asRecord(embed.embedMetadata);
-  const metadataConfig = asRecord(metadata?.embedConfig);
-  const options = asRecord(embed.options);
+  const metadata = asRecord2(embed.embedMetadata);
+  const metadataConfig = asRecord2(metadata?.embedConfig);
+  const options = asRecord2(embed.options);
   const candidates = [
-    asRecord(embed.accessSettings),
-    asRecord(metadata?.accessSettings),
-    asRecord(metadataConfig?.accessSettings),
-    asRecord(options?.accessSettings)
+    asRecord2(embed.accessSettings),
+    asRecord2(metadata?.accessSettings),
+    asRecord2(metadataConfig?.accessSettings),
+    asRecord2(options?.accessSettings)
   ].filter((c) => !!c);
   for (const candidate of candidates) {
     if (Object.keys(candidate).length > 0) return candidate;
@@ -755,8 +865,8 @@ function extractAccessSettings(embed) {
   return null;
 }
 function extractDatamartName(embed, existingAccess) {
-  const metadata = asRecord(embed.embedMetadata);
-  const metadataConfig = asRecord(metadata?.embedConfig);
+  const metadata = asRecord2(embed.embedMetadata);
+  const metadataConfig = asRecord2(metadata?.embedConfig);
   const values = [
     existingAccess?.datamartName,
     existingAccess?.dataMartName,
@@ -793,7 +903,7 @@ var EmbedService = class {
     return this.embedsApi.listEmbeds(dataAppName);
   }
   async createEmbedStrict(body) {
-    const accessSettings = asRecord(body.accessSettings);
+    const accessSettings = asRecord2(body.accessSettings);
     if (!accessSettings || Object.keys(accessSettings).length === 0) {
       throw new Error(
         "Embed creation requires `accessSettings` for future update compatibility."
@@ -881,8 +991,8 @@ Run \`update_embed\` with explicit \`accessSettings.datamartName\`, or recreate
   }
   async updateEmbed(embedId, updatePatch) {
     const body = await this.buildUpdateBase(embedId);
-    const baseAccessSettings = asRecord(body.accessSettings);
-    const patchAccessSettings = asRecord(updatePatch.accessSettings);
+    const baseAccessSettings = asRecord2(body.accessSettings);
+    const patchAccessSettings = asRecord2(updatePatch.accessSettings);
     for (const [key, value] of Object.entries(updatePatch)) {
       if (key === "accessSettings") continue;
       if (value !== void 0) body[key] = value;
@@ -942,7 +1052,7 @@ var GuestTokenService = class {
 
 // src/services/widget-service.ts
 var isNonEmptyString3 = (v) => typeof v === "string" && v.trim().length > 0;
-var asRecord2 = (v) => {
+var asRecord3 = (v) => {
   if (!v || typeof v !== "object" || Array.isArray(v)) return null;
   return v;
 };
@@ -1263,8 +1373,8 @@ Do not guess between the two \u2014 wait for the user to choose.`
     if (!exact) {
       throw new Error(`Embed "${embedId}" not found. Run \`list_embeds\` to verify.`);
     }
-    const metadata = asRecord2(exact.embedMetadata);
-    const externalDashboard = asRecord2(exact.externalDashboard);
+    const metadata = asRecord3(exact.embedMetadata);
+    const externalDashboard = asRecord3(exact.externalDashboard);
     const dataAppId = isNonEmptyString3(exact.dataAppId) ? exact.dataAppId : null;
     const externalDashboardId = isNonEmptyString3(exact.externalDashboardId) && exact.externalDashboardId || (externalDashboard && isNonEmptyString3(externalDashboard.externalDashboardId) ? externalDashboard.externalDashboardId : null) || (metadata && isNonEmptyString3(metadata.externalDashboardId) ? metadata.externalDashboardId : null);
     const dashboardId = isNonEmptyString3(exact.dashboardId) && exact.dashboardId || (metadata && isNonEmptyString3(metadata.dashboardId) ? metadata.dashboardId : null);
@@ -1314,7 +1424,7 @@ Do not guess between the two \u2014 wait for the user to choose.`
       guestToken,
       templateMetricId
     );
-    const metric = asRecord2(response.externalMetric);
+    const metric = asRecord3(response.externalMetric);
     if (!metric) {
       throw new Error(
         `Template metric "${templateMetricId}" not found or could not be loaded. Response keys: ${Object.keys(
@@ -1330,7 +1440,7 @@ Do not guess between the two \u2014 wait for the user to choose.`
       query: metric.query || void 0,
       metricQuery: metric.metricQuery || void 0,
       description: metric.description || "",
-      chartOptions: asRecord2(metric.chartOptions) || {},
+      chartOptions: asRecord3(metric.chartOptions) || {},
       companyId: metric.companyId || void 0,
       companyIntegrationId: metric.companyIntegrationId || void 0,
       integrationName: metric.integrationName || void 0,
@@ -1371,6 +1481,7 @@ function createServiceBundle(client) {
   const datasourcesApi = new DatasourcesApi(client);
   const guestTokenApi = new GuestTokenApi(client);
   const queryApi = new QueryApi(client);
+  const scheduledReportsApi = new ScheduledReportsApi(client);
   const widgetsApi = new WidgetsApi(client);
   const workspacesApi = new WorkspacesApi(client);
   const discoveryService = new DiscoveryService();
@@ -1383,6 +1494,7 @@ function createServiceBundle(client) {
     datasourcesApi,
     workspacesApi,
     queryApi,
+    scheduledReportsApi,
     widgetsApi,
     embedService: new EmbedService(embedsApi, datamartsApi),
     discoveryService,
@@ -1990,68 +2102,223 @@ function registerListWorkspaces(server, client) {
   );
 }
 
-// src/tools/infrastructure/link-datamart-to-workspace.ts
+// src/tools/infrastructure/create-datamart.ts
 import { z as z9 } from "zod";
-function registerLinkDatamartToWorkspace(server, client) {
+
+// src/tools/widgets/production-guards.ts
+var APPLY_TO_PRODUCTION_CONFIRMATION = "APPLY_TO_PRODUCTION";
+function validateProductionApply(params) {
+  if (params.confirm !== APPLY_TO_PRODUCTION_CONFIRMATION) {
+    return `Applying to production requires confirm: "${APPLY_TO_PRODUCTION_CONFIRMATION}". Run dry-run first, review the plan, then retry with that confirmation string.`;
+  }
+  return null;
+}
+function productionSafetyNote(workspaceName) {
+  return `This workspace is production-backed. Dry-run is the default; apply requires explicit production confirmation. Resolved workspace: "${workspaceName.trim()}".`;
+}
+function genericProductionSafetyNote() {
+  return "This operation targets production-backed Databrain resources. Dry-run is the default; apply requires explicit production confirmation.";
+}
+
+// src/tools/infrastructure/create-datamart.ts
+var columnSchema = z9.object({
+  name: z9.string(),
+  alias: z9.string().optional(),
+  label: z9.string().optional(),
+  isHide: z9.boolean().optional(),
+  isCustomColumn: z9.boolean().optional(),
+  sql: z9.string().optional()
+});
+var tableSchema = z9.object({
+  name: z9.string(),
+  schemaName: z9.string().optional(),
+  clientColumn: z9.string().optional(),
+  label: z9.string().optional(),
+  columns: z9.array(columnSchema)
+});
+var relationshipSchema = z9.object({
+  parentTableName: z9.string(),
+  parentColumnName: z9.string(),
+  childTableName: z9.string(),
+  childColumnName: z9.string(),
+  cardinality: z9.enum(["OneToOne", "OneToMany", "ManyToOne", "ManyToMany"]),
+  join: z9.enum(["INNER JOIN", "LEFT JOIN", "RIGHT JOIN", "FULL JOIN"]),
+  relationshipName: z9.string()
+});
+function datamartSuccessMessage(name, result) {
+  return `Datamart "${name}" created successfully (ID: ${result.id || result._id || "UNKNOWN"}).
+
+**To query data**, complete the semantic layer first:
+1. \`get_semantic_layer\` with \`datamartName: "${name}"\` \u2014 check if table descriptions exist
+2. \`update_semantic_layer\` \u2014 add table/column descriptions and synonyms so the AI can generate accurate SQL
+3. \`ask_question\` with \`datamartName: "${name}"\` \u2014 ask natural language questions
+
+**To embed dashboards** (optional):
+1. Connect this datamart to a workspace outside MCP
+2. Create a dashboard in the Databrain UI
+3. Use \`create_embed\` to embed the dashboard`;
+}
+function registerCreateDatamart(server, client) {
+  const services = createServiceBundle(client);
   server.tool(
-    "link_datamart_to_workspace",
-    "Link a datamart to an existing workspace. ALWAYS ask the user which workspace to use \u2014 do not auto-select.",
+    "create_datamart",
+    "Create a production datamart from selected tables and relationships. Defaults to dry-run; apply requires explicit confirmation.",
     {
-      workspaceName: z9.string().optional().describe(
-        "Name of the workspace to update. Omit to list available workspaces and let the user choose."
-      ),
-      datamartName: z9.string().describe(
-        "Name of the datamart to link. Use `list_datamarts` to find it."
-      )
+      mode: z9.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run returns the plan only; apply creates the datamart"),
+      confirm: z9.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      name: z9.string().describe("Unique datamart name"),
+      datasourceName: z9.string().optional().describe("Name of the datasource to use. Omit to list available datasources."),
+      tableList: z9.array(tableSchema).optional().describe("Array of tables with their columns"),
+      relationships: z9.array(relationshipSchema).optional().describe("Join definitions between tables"),
+      tenancySettings: z9.object({
+        tenancyLevel: z9.enum(["TABLE", "DATABASE"]).optional(),
+        clientColumnType: z9.string().optional(),
+        schemaName: z9.string().optional(),
+        tableName: z9.string().optional(),
+        tableClientNameColumn: z9.string().optional(),
+        tablePrimaryKeyColumn: z9.string().optional()
+      }).optional().describe("Multi-tenant configuration"),
+      body: z9.record(z9.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/datamarts")
     },
-    WRITE_IDEMPOTENT,
-    async ({ workspaceName, datamartName }) => {
+    WRITE_CREATE,
+    async (params) => {
       try {
-        if (!workspaceName) {
-          const workspaces = await client.request({
-            method: "GET",
-            path: "/api/v2/workspace",
-            auth: "service",
-            cacheKey: "list_workspaces",
-            cacheTtlMs: 5 * 60 * 1e3
+        const mode = params.mode || "dry_run";
+        if (!params.body) {
+          const datasources = await services.datasourcesApi.listDatasources();
+          const resolution = resolveResource({
+            items: datasources,
+            name: params.datasourceName,
+            getName: (ds) => ds.name,
+            formatItem: formatDatasource,
+            resourceType: "datasource",
+            toolName: "create_datamart"
           });
-          if (!Array.isArray(workspaces) || workspaces.length === 0) {
+          if (resolution.kind !== "resolved") return resolution.response;
+          if (!params.tableList || params.tableList.length === 0) {
             return toolError(
-              "No workspaces found. Create a workspace in the **Databrain UI** first, then come back here to link the datamart."
+              "tableList is required. Use `discover_datasource_schema` to see available tables first."
+            );
+          }
+          const body = {
+            name: params.name,
+            datasourceName: resolution.name,
+            tableList: params.tableList,
+            relationships: params.relationships,
+            tenancySettings: params.tenancySettings
+          };
+          if (mode === "dry_run") {
+            return toolSuccess(
+              JSON.stringify(
+                {
+                  status: "dry_run_only",
+                  safety: genericProductionSafetyNote(),
+                  requiredApplyConfirmation: APPLY_TO_PRODUCTION_CONFIRMATION,
+                  body,
+                  nextStep: `Review this plan. To execute, call again with mode="apply" and confirm="${APPLY_TO_PRODUCTION_CONFIRMATION}".`
+                },
+                null,
+                2
+              )
             );
           }
-          const list = workspaces.map((ws) => `- **${ws.name}** (ID: ${ws._id || ws.id})`).join("\n");
+          const guardError2 = validateProductionApply({ confirm: params.confirm });
+          if (guardError2) return toolError(guardError2);
+          const result2 = await client.request({
+            method: "POST",
+            path: "/api/v2/data-app/datamarts",
+            body,
+            auth: "service",
+            invalidateCache: ["list_datamarts"]
+          });
+          if (result2.error) {
+            return toolError(`Datamart creation failed: ${stringify(result2.error)}`);
+          }
+          return toolSuccess(datamartSuccessMessage(params.name, result2));
+        }
+        if (mode === "dry_run") {
           return toolSuccess(
-            `Found ${workspaces.length} workspace(s):
-
-${list}
-
-**Ask the user** which workspace they want to link to datamart **${datamartName}**, then call \`link_datamart_to_workspace\` with both \`workspaceName\` and \`datamartName\`.`
+            JSON.stringify(
+              {
+                status: "dry_run_only",
+                safety: genericProductionSafetyNote(),
+                requiredApplyConfirmation: APPLY_TO_PRODUCTION_CONFIRMATION,
+                body: params.body,
+                nextStep: `Review this raw datamart body. To execute, call again with mode="apply" and confirm="${APPLY_TO_PRODUCTION_CONFIRMATION}".`
+              },
+              null,
+              2
+            )
           );
         }
+        const guardError = validateProductionApply({ confirm: params.confirm });
+        if (guardError) return toolError(guardError);
         const result = await client.request({
-          method: "PUT",
-          path: "/api/v2/workspace",
-          body: {
-            name: workspaceName,
-            connectionType: "DATAMART",
-            datamartName
-          },
+          method: "POST",
+          path: "/api/v2/data-app/datamarts",
+          body: params.body,
           auth: "service",
-          invalidateCache: ["list_workspaces"]
+          invalidateCache: ["list_datamarts"]
         });
         if (result.error) {
-          return toolError(
-            `Failed to link datamart: ${typeof result.error === "object" ? JSON.stringify(result.error) : result.error}`
-          );
+          return toolError(`Datamart creation failed: ${stringify(result.error)}`);
+        }
+        return toolSuccess(datamartSuccessMessage(params.name, result));
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/infrastructure/sync-datasource.ts
+import { z as z10 } from "zod";
+function registerSyncDatasource(server, client) {
+  const datasourcesApi = new DatasourcesApi(client);
+  server.tool(
+    "sync_datasource",
+    "Trigger a datasource schema sync to refresh table and column metadata. If datasourceName is omitted and there are multiple datasources, returns the list so the user can choose.",
+    {
+      datasourceName: z10.string().optional().describe("Name of the datasource to sync. Omit to list available datasources.")
+    },
+    WRITE_IDEMPOTENT,
+    async (params) => {
+      try {
+        const datasources = await client.request({
+          method: "GET",
+          path: "/api/v2/datasource/",
+          auth: "service",
+          cacheKey: "list_datasources",
+          cacheTtlMs: 10 * 60 * 1e3
+        });
+        const resolution = resolveResource({
+          items: datasources,
+          name: params.datasourceName,
+          getName: (ds) => ds.name,
+          formatItem: formatDatasource,
+          resourceType: "datasource",
+          toolName: "sync_datasource"
+        });
+        if (resolution.kind !== "resolved") return resolution.response;
+        const { selected } = resolution;
+        const datasourceId = selected._id || selected.id || (selected.name ? await datasourcesApi.resolveIdByName(selected.name) : null);
+        if (!datasourceId) {
+          return toolError(`Datasource "${selected.name}" found but has no ID. This is unexpected.`);
         }
+        const result = await client.request({
+          method: "POST",
+          path: "/api/v2/datasource/sync",
+          body: { input: { datasourceId } },
+          auth: "service",
+          invalidateCache: [`datasource_schema_${selected.name}`]
+        });
+        const message = result?.data?.message || "Sync completed";
         return toolSuccess(
-          `Workspace **${workspaceName}** is now linked to datamart **${datamartName}**.
+          `Datasource "${selected.name}" sync triggered (ID: ${datasourceId}).
+Status: ${message}
 
-Next steps:
-- Build dashboards in the Databrain UI using this workspace
-- Use \`list_dashboards\` to find dashboards in this workspace
-- Use \`create_embed\` to embed dashboards into your app`
+The schema metadata will be refreshed. You can now use \`discover_datasource_schema\` or \`create_datamart\` to select tables.`
         );
       } catch (err) {
         if (err instanceof DatabrainApiError) return err.toToolResponse();
@@ -2062,7 +2329,7 @@ Next steps:
 }
 
 // src/tools/embed/create-embed.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowMetricCreation: false,
   isAllowMetricDeletion: false,
@@ -2075,18 +2342,18 @@ var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowCreateDashboardView: false,
   metricCreationMode: "DRAG_DROP"
 };
-var accessSettingsSchema = z10.object({
-  datamartName: z10.string().describe("Name of the datamart (required)"),
-  isAllowMetricCreation: z10.boolean().optional().describe("Allow end-users to create metrics"),
-  metricCreationMode: z10.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
-  isAllowMetricDeletion: z10.boolean().optional().describe("Allow metric deletion"),
-  isAllowMetricUpdate: z10.boolean().optional().describe("Allow metric editing"),
-  isAllowMetricLayoutChange: z10.boolean().optional().describe("Allow layout changes"),
-  isAllowManageMetrics: z10.boolean().optional().describe("Show manage metrics UI"),
-  isAllowUnderlyingData: z10.boolean().optional().describe("Allow viewing underlying data"),
-  isAllowAiPilot: z10.boolean().optional().describe("Enable AI pilot features"),
-  isAllowEmailReports: z10.boolean().optional().describe("Allow email report scheduling"),
-  isAllowCreateDashboardView: z10.boolean().optional().describe("Allow creating dashboard views")
+var accessSettingsSchema = z11.object({
+  datamartName: z11.string().describe("Name of the datamart (required)"),
+  isAllowMetricCreation: z11.boolean().optional().describe("Allow end-users to create metrics"),
+  metricCreationMode: z11.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
+  isAllowMetricDeletion: z11.boolean().optional().describe("Allow metric deletion"),
+  isAllowMetricUpdate: z11.boolean().optional().describe("Allow metric editing"),
+  isAllowMetricLayoutChange: z11.boolean().optional().describe("Allow layout changes"),
+  isAllowManageMetrics: z11.boolean().optional().describe("Show manage metrics UI"),
+  isAllowUnderlyingData: z11.boolean().optional().describe("Allow viewing underlying data"),
+  isAllowAiPilot: z11.boolean().optional().describe("Enable AI pilot features"),
+  isAllowEmailReports: z11.boolean().optional().describe("Allow email report scheduling"),
+  isAllowCreateDashboardView: z11.boolean().optional().describe("Allow creating dashboard views")
 }).describe("Embed access settings. Only datamartName is required \u2014 all flags default to false.");
 function registerCreateEmbed(server, client) {
   const services = createServiceBundle(client);
@@ -2094,23 +2361,23 @@ function registerCreateEmbed(server, client) {
     "create_embed",
     "Create an embed. Provide dashboardId, workspaceName, accessSettings.datamartName. Add clientId for multi-tenant per-client dashboards. All isAllow* flags default to false.",
     {
-      body: z10.record(z10.unknown()).optional().describe(
+      body: z11.record(z11.unknown()).optional().describe(
         "Raw API body passthrough. If provided, all other fields are ignored."
       ),
-      dashboardId: z10.string().optional().describe("Dashboard identifier for embed creation"),
-      workspaceName: z10.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
-      embedType: z10.enum(["dashboard", "metric"]).optional().describe("Embed type"),
-      metricId: z10.string().optional().describe("Required for metric embed type"),
-      name: z10.string().optional().describe("Human-readable embed config name"),
+      dashboardId: z11.string().optional().describe("Dashboard identifier for embed creation"),
+      workspaceName: z11.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
+      embedType: z11.enum(["dashboard", "metric"]).optional().describe("Embed type"),
+      metricId: z11.string().optional().describe("Required for metric embed type"),
+      name: z11.string().optional().describe("Human-readable embed config name"),
       accessSettings: accessSettingsSchema.optional(),
       // Multi-tenant (dashboard embed) params
-      clientId: z10.string().optional().describe(
+      clientId: z11.string().optional().describe(
         "Client identifier for multi-tenant isolation. When provided, creates a dashboard embed (each client gets their own dashboard copy)."
       ),
-      templateDashboardId: z10.string().optional().describe("Template dashboard ID to clone metrics from"),
-      isImportMetrics: z10.boolean().optional().describe("Import metrics from template dashboard"),
-      metricImportMode: z10.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
-      isRenameDashboard: z10.boolean().optional().describe("Rename the dashboard for this client")
+      templateDashboardId: z11.string().optional().describe("Template dashboard ID to clone metrics from"),
+      isImportMetrics: z11.boolean().optional().describe("Import metrics from template dashboard"),
+      metricImportMode: z11.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
+      isRenameDashboard: z11.boolean().optional().describe("Rename the dashboard for this client")
     },
     WRITE_CREATE,
     async (params) => {
@@ -2212,14 +2479,14 @@ Next: run \`get_embed_details\` to verify the embed configuration.`
 }
 
 // src/tools/embed/list-embeds.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 function registerListEmbeds(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_embeds",
-    "List embed configurations. Requires an API token (use create_api_token first).",
+    "List embed configurations. Requires an API token (use create_api_token first). Response includes `distinctClientIds` \u2014 a deduped list of end-customer client IDs that have multi-tenant dashboard embeds, useful for discovering which customers exist when only the workspace operator persona knows them.",
     {
-      dataAppName: z11.string().optional().describe("Filter by data app name")
+      dataAppName: z12.string().optional().describe("Filter by data app name")
     },
     READ_ONLY,
     async (params) => {
@@ -2230,19 +2497,28 @@ function registerListEmbeds(server, client) {
             "No embeds found. Create an embed in the Databrain UI, then run `list_embeds` again."
           );
         }
+        const embeds = result.map((e) => {
+          const n = services.discoveryService.normalizeEmbed(e);
+          const clientId = typeof e.clientId === "string" && e.clientId.trim().length > 0 ? e.clientId : null;
+          return {
+            embedId: n.embedId || null,
+            internalId: !n.embedId && n.internalId ? n.internalId : void 0,
+            name: n.name,
+            type: n.embedType || "dashboard",
+            dashboardId: n.dashboardId || null,
+            dataApp: n.dataAppName || null,
+            clientId
+          };
+        });
+        const distinctClientIds = Array.from(
+          new Set(
+            embeds.map((e) => e.clientId).filter((id) => typeof id === "string" && id.length > 0)
+          )
+        ).sort();
         return toolSuccess(JSON.stringify({
-          count: result.length,
-          embeds: result.map((e) => {
-            const n = services.discoveryService.normalizeEmbed(e);
-            return {
-              embedId: n.embedId || null,
-              internalId: !n.embedId && n.internalId ? n.internalId : void 0,
-              name: n.name,
-              type: n.embedType || "dashboard",
-              dashboardId: n.dashboardId || null,
-              dataApp: n.dataAppName || null
-            };
-          })
+          count: embeds.length,
+          distinctClientIds,
+          embeds
         }));
       } catch (err) {
         if (err instanceof DatabrainApiError) return err.toToolResponse();
@@ -2253,14 +2529,14 @@ function registerListEmbeds(server, client) {
 }
 
 // src/tools/embed/get-embed-details.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 function registerGetEmbedDetails(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "get_embed_details",
     "Get full embed configuration including access settings and theme.",
     {
-      embedId: z12.string().describe("ID of the embed")
+      embedId: z13.string().describe("ID of the embed")
     },
     READ_ONLY,
     async (params) => {
@@ -2276,7 +2552,7 @@ function registerGetEmbedDetails(server, client) {
 }
 
 // src/tools/embed/update-embed.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 
 // src/tools/embed/helpers.ts
 var GUEST_TOKEN_REMINDER = "\n\n\u26A0\uFE0F **Guest tokens must be regenerated** for these changes to take effect. Existing guest tokens still carry the old settings. Call `generate_guest_token` to create a new token with the updated configuration.";
@@ -2314,15 +2590,15 @@ function registerUpdateEmbed(server, client) {
     "update_embed",
     "Update embed access settings, permissions, theme, or name.",
     {
-      embedId: z13.string().describe("ID of the embed to update"),
-      body: z13.record(z13.unknown()).optional().describe(
+      embedId: z14.string().describe("ID of the embed to update"),
+      body: z14.record(z14.unknown()).optional().describe(
         "Raw API body for PUT /api/v2/data-app/embeds. If provided, it is sent directly (passthrough mode)."
       ),
-      name: z13.string().optional().describe("New name for the embed"),
-      accessSettings: z13.record(z13.unknown()).optional().describe(
+      name: z14.string().optional().describe("New name for the embed"),
+      accessSettings: z14.record(z14.unknown()).optional().describe(
         "Partial update of access settings. See `get_embed_details` for current settings."
       ),
-      theme: z13.record(z13.unknown()).optional().describe(
+      theme: z14.record(z14.unknown()).optional().describe(
         "Theme configuration object. See databrain://theme-reference for the full schema."
       )
     },
@@ -2368,7 +2644,7 @@ function registerUpdateEmbed(server, client) {
 }
 
 // src/tools/embed/customize-theme.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var THEME_PRESETS = {
   light: {
     general: {
@@ -2502,7 +2778,7 @@ var ACCESS_PRESETS = {
     metricCreationMode: "CHAT"
   }
 };
-var fontFamilyEnum = z14.enum([
+var fontFamilyEnum = z15.enum([
   "Inter",
   "Roboto",
   "Open Sans",
@@ -2514,17 +2790,17 @@ var fontFamilyEnum = z14.enum([
   "Nunito",
   "system-ui"
 ]).describe("Font family");
-var tooltipFontSchema = z14.object({
-  fontFamily: z14.string().optional(),
-  fontSize: z14.number().optional(),
-  fontWeight: z14.number().optional(),
-  fontColor: z14.string().optional()
+var tooltipFontSchema = z15.object({
+  fontFamily: z15.string().optional(),
+  fontSize: z15.number().optional(),
+  fontWeight: z15.number().optional(),
+  fontColor: z15.string().optional()
 }).optional();
-var fontConfigInputSchema = z14.object({
-  fontSize: z14.number().optional(),
-  fontFamily: z14.string().optional(),
-  fontWeight: z14.number().optional(),
-  color: z14.string().optional()
+var fontConfigInputSchema = z15.object({
+  fontSize: z15.number().optional(),
+  fontFamily: z15.string().optional(),
+  fontWeight: z15.number().optional(),
+  color: z15.string().optional()
 }).optional();
 function mapToFrontendFontConfig(input) {
   if (!input) return void 0;
@@ -2535,23 +2811,23 @@ function mapToFrontendFontConfig(input) {
     ...input.color && { color: input.color }
   };
 }
-var axisSchema = z14.object({
-  hideAxisLines: z14.boolean().optional().describe("Hide axis lines"),
-  hideSplitLines: z14.boolean().optional().describe("Hide grid/split lines"),
-  hideAxisLabels: z14.boolean().optional().describe("Hide axis labels"),
-  hideAxisTicks: z14.boolean().optional().describe("Hide axis tick marks"),
-  axisName: z14.string().optional().describe("Axis title text"),
-  axisNameOffset: z14.number().optional().describe("Axis title offset from axis"),
-  axisLabelMargin: z14.number().optional().describe("Margin between axis labels and chart area in pixels"),
-  fontSize: z14.number().optional().describe("Axis label font size"),
-  fontFamily: z14.string().optional().describe("Axis label font family"),
-  fontWeight: z14.number().optional().describe("Axis label font weight"),
-  color: z14.string().optional().describe("Axis label color (hex)"),
-  axisColor: z14.string().optional().describe("Axis line color (hex)"),
-  axisNameFontConfig: z14.object({
-    fontFamily: z14.string().optional(),
-    fontSize: z14.number().optional(),
-    fontWeight: z14.number().optional()
+var axisSchema = z15.object({
+  hideAxisLines: z15.boolean().optional().describe("Hide axis lines"),
+  hideSplitLines: z15.boolean().optional().describe("Hide grid/split lines"),
+  hideAxisLabels: z15.boolean().optional().describe("Hide axis labels"),
+  hideAxisTicks: z15.boolean().optional().describe("Hide axis tick marks"),
+  axisName: z15.string().optional().describe("Axis title text"),
+  axisNameOffset: z15.number().optional().describe("Axis title offset from axis"),
+  axisLabelMargin: z15.number().optional().describe("Margin between axis labels and chart area in pixels"),
+  fontSize: z15.number().optional().describe("Axis label font size"),
+  fontFamily: z15.string().optional().describe("Axis label font family"),
+  fontWeight: z15.number().optional().describe("Axis label font weight"),
+  color: z15.string().optional().describe("Axis label color (hex)"),
+  axisColor: z15.string().optional().describe("Axis line color (hex)"),
+  axisNameFontConfig: z15.object({
+    fontFamily: z15.string().optional(),
+    fontSize: z15.number().optional(),
+    fontWeight: z15.number().optional()
   }).optional().describe("Axis title font configuration")
 }).optional();
 function buildAdminTheme(p, presetBase) {
@@ -2610,37 +2886,37 @@ function buildAdminTheme(p, presetBase) {
 function buildComponentTheme(p) {
   const componentTheme = {};
   if (p.buttonPrimaryColor || p.buttonPrimaryTextColor || p.buttonSecondaryColor || p.buttonSecondaryTextColor) {
-    componentTheme.button = {
-      ...p.buttonPrimaryColor && { primary: p.buttonPrimaryColor },
-      ...p.buttonPrimaryTextColor && { primaryText: p.buttonPrimaryTextColor },
-      ...p.buttonSecondaryColor && { secondary: p.buttonSecondaryColor },
-      ...p.buttonSecondaryTextColor && { secondaryText: p.buttonSecondaryTextColor }
-    };
+    const button = {};
+    if (p.buttonPrimaryColor) button.primary = p.buttonPrimaryColor;
+    if (p.buttonPrimaryTextColor) button.primaryText = p.buttonPrimaryTextColor;
+    if (p.buttonSecondaryColor) button.secondary = p.buttonSecondaryColor;
+    if (p.buttonSecondaryTextColor) button.secondaryText = p.buttonSecondaryTextColor;
+    componentTheme.button = button;
   }
   if (p.checkboxCheckedColor || p.checkboxUncheckedColor) {
-    componentTheme.checkbox = {
-      ...p.checkboxCheckedColor && { checked: p.checkboxCheckedColor },
-      ...p.checkboxUncheckedColor && { unChecked: p.checkboxUncheckedColor }
-    };
+    const checkbox = {};
+    if (p.checkboxCheckedColor) checkbox.checked = p.checkboxCheckedColor;
+    if (p.checkboxUncheckedColor) checkbox.unChecked = p.checkboxUncheckedColor;
+    componentTheme.checkbox = checkbox;
   }
   if (p.switchEnabledColor || p.switchDisabledColor) {
-    componentTheme.switch = {
-      ...p.switchEnabledColor && { enabled: p.switchEnabledColor },
-      ...p.switchDisabledColor && { disabled: p.switchDisabledColor }
-    };
+    const switchTheme = {};
+    if (p.switchEnabledColor) switchTheme.enabled = p.switchEnabledColor;
+    if (p.switchDisabledColor) switchTheme.disabled = p.switchDisabledColor;
+    componentTheme.switch = switchTheme;
   }
   if (p.breadcrumbFontFamily || p.breadcrumbFontColor || p.breadcrumbActiveColor) {
-    componentTheme.drillBreadCrumbs = {
-      ...p.breadcrumbFontFamily && { fontFamily: p.breadcrumbFontFamily },
-      ...p.breadcrumbFontColor && { fontColor: p.breadcrumbFontColor },
-      ...p.breadcrumbActiveColor && { activeColor: p.breadcrumbActiveColor }
-    };
+    const drillBreadCrumbs = {};
+    if (p.breadcrumbFontFamily) drillBreadCrumbs.fontFamily = p.breadcrumbFontFamily;
+    if (p.breadcrumbFontColor) drillBreadCrumbs.fontColor = p.breadcrumbFontColor;
+    if (p.breadcrumbActiveColor) drillBreadCrumbs.activeColor = p.breadcrumbActiveColor;
+    componentTheme.drillBreadCrumbs = drillBreadCrumbs;
   }
   if (p.filterBadgeColor || p.filterBadgeTextColor) {
-    componentTheme.multiSelectFilterDropdown = {
-      ...p.filterBadgeColor && { badgeColor: p.filterBadgeColor },
-      ...p.filterBadgeTextColor && { badgeTextColor: p.filterBadgeTextColor }
-    };
+    const multiSelectFilterDropdown = {};
+    if (p.filterBadgeColor) multiSelectFilterDropdown.badgeColor = p.filterBadgeColor;
+    if (p.filterBadgeTextColor) multiSelectFilterDropdown.badgeTextColor = p.filterBadgeTextColor;
+    componentTheme.multiSelectFilterDropdown = multiSelectFilterDropdown;
   }
   if (p.datePickerColor) componentTheme.datePickerColor = p.datePickerColor;
   const breakpoint = {};
@@ -2707,94 +2983,94 @@ function registerCustomizeTheme(server, client) {
     "customize_embed_theme",
     `Theme an embed: presets (${Object.keys(THEME_PRESETS).join("/")}), colors, fonts, cards, chart appearance, responsive layout, or access presets (${Object.keys(ACCESS_PRESETS).join("/")}).`,
     {
-      embedId: z14.string().describe("ID of the embed to theme"),
-      body: z14.record(z14.unknown()).optional().describe(
+      embedId: z15.string().describe("ID of the embed to theme"),
+      body: z15.record(z15.unknown()).optional().describe(
         "Raw API body for PUT /api/v2/data-app/embeds. If provided, sent directly and all convenience fields are ignored."
       ),
       // --- Presets ---
-      themePreset: z14.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
-      accessPreset: z14.enum(["view-only", "power-user", "export-only", "ai-enabled"]).optional().describe("Apply an access settings preset"),
+      themePreset: z15.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
+      accessPreset: z15.enum(["view-only", "power-user", "export-only", "ai-enabled"]).optional().describe("Apply an access settings preset"),
       // --- General ---
       fontFamily: fontFamilyEnum.optional().describe("Global font family"),
-      datePickerFormat: z14.string().optional().describe("Date picker display format"),
+      datePickerFormat: z15.string().optional().describe("Date picker display format"),
       // --- Colors ---
-      primaryColor: z14.string().optional().describe("Primary accent color (hex)"),
-      backgroundColor: z14.string().optional().describe("Overall background color (hex)"),
-      textColor: z14.string().optional().describe("Default text color (hex)"),
-      ctaColor: z14.string().optional().describe("Call-to-action button color (hex)"),
-      ctaTextColor: z14.string().optional().describe("CTA button text color (hex)"),
+      primaryColor: z15.string().optional().describe("Primary accent color (hex)"),
+      backgroundColor: z15.string().optional().describe("Overall background color (hex)"),
+      textColor: z15.string().optional().describe("Default text color (hex)"),
+      ctaColor: z15.string().optional().describe("Call-to-action button color (hex)"),
+      ctaTextColor: z15.string().optional().describe("CTA button text color (hex)"),
       // --- Dashboard ---
-      dashboardBackgroundColor: z14.string().optional().describe("Dashboard container background (hex)"),
-      selectBoxSize: z14.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
-      selectBoxVariant: z14.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
-      selectBoxBorderRadius: z14.string().optional().describe('Select box border radius (e.g. "20px")'),
-      selectBoxTextColor: z14.string().optional().describe("Select box text color (hex)"),
-      metricCardColor: z14.string().optional().describe("Metric card background color (hex)"),
+      dashboardBackgroundColor: z15.string().optional().describe("Dashboard container background (hex)"),
+      selectBoxSize: z15.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
+      selectBoxVariant: z15.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
+      selectBoxBorderRadius: z15.string().optional().describe('Select box border radius (e.g. "20px")'),
+      selectBoxTextColor: z15.string().optional().describe("Select box text color (hex)"),
+      metricCardColor: z15.string().optional().describe("Metric card background color (hex)"),
       // --- Card Title ---
-      cardTitleFontSize: z14.string().optional().describe('Card title font size (e.g. "16px")'),
-      cardTitleFontWeight: z14.string().optional().describe('Card title font weight (e.g. "600")'),
-      cardTitleColor: z14.string().optional().describe("Card title text color (hex)"),
+      cardTitleFontSize: z15.string().optional().describe('Card title font size (e.g. "16px")'),
+      cardTitleFontWeight: z15.string().optional().describe('Card title font weight (e.g. "600")'),
+      cardTitleColor: z15.string().optional().describe("Card title text color (hex)"),
       // --- Card Description ---
-      cardDescriptionFontSize: z14.string().optional().describe("Card description font size"),
-      cardDescriptionFontWeight: z14.string().optional().describe("Card description font weight"),
-      cardDescriptionColor: z14.string().optional().describe("Card description text color (hex)"),
+      cardDescriptionFontSize: z15.string().optional().describe("Card description font size"),
+      cardDescriptionFontWeight: z15.string().optional().describe("Card description font weight"),
+      cardDescriptionColor: z15.string().optional().describe("Card description text color (hex)"),
       // --- Card Customization ---
-      cardPadding: z14.string().optional().describe("Card internal padding"),
-      cardBorderRadius: z14.string().optional().describe("Card border radius"),
-      cardShadow: z14.string().optional().describe("Card box-shadow CSS value"),
-      disableShadowOnHover: z14.boolean().optional().describe("Disable shadow on card hover"),
-      disableCardStroke: z14.boolean().optional().describe("Remove card border stroke"),
-      cardStrokeColor: z14.string().optional().describe("Card border stroke color (hex)"),
+      cardPadding: z15.string().optional().describe("Card internal padding"),
+      cardBorderRadius: z15.string().optional().describe("Card border radius"),
+      cardShadow: z15.string().optional().describe("Card box-shadow CSS value"),
+      disableShadowOnHover: z15.boolean().optional().describe("Disable shadow on card hover"),
+      disableCardStroke: z15.boolean().optional().describe("Remove card border stroke"),
+      cardStrokeColor: z15.string().optional().describe("Card border stroke color (hex)"),
       // --- Chart Colors (admin theme level) ---
-      chartFontFamily: z14.string().optional().describe("Font family for chart text"),
-      chartFontColor: z14.string().optional().describe("Font color for chart text (hex)"),
-      chartColors: z14.array(z14.string()).optional().describe("Array of chart series colors (hex)"),
-      chartPaletteName: z14.string().optional().describe("Name for a custom palette"),
-      chartPaletteColors: z14.array(z14.string()).optional().describe("9 colors for a custom palette"),
+      chartFontFamily: z15.string().optional().describe("Font family for chart text"),
+      chartFontColor: z15.string().optional().describe("Font color for chart text (hex)"),
+      chartColors: z15.array(z15.string()).optional().describe("Array of chart series colors (hex)"),
+      chartPaletteName: z15.string().optional().describe("Name for a custom palette"),
+      chartPaletteColors: z15.array(z15.string()).optional().describe("9 colors for a custom palette"),
       // --- Chart Tooltip (admin theme level) ---
       tooltipHeader: tooltipFontSchema.describe("Tooltip header font config"),
       tooltipLabel: tooltipFontSchema.describe("Tooltip label font config"),
       tooltipValue: tooltipFontSchema.describe("Tooltip value font config"),
       // --- Component Theme ---
-      buttonPrimaryColor: z14.string().optional().describe("Primary button background (hex)"),
-      buttonPrimaryTextColor: z14.string().optional().describe("Primary button text (hex)"),
-      buttonSecondaryColor: z14.string().optional().describe("Secondary button background (hex)"),
-      buttonSecondaryTextColor: z14.string().optional().describe("Secondary button text (hex)"),
-      checkboxCheckedColor: z14.string().optional().describe("Checked checkbox color (hex)"),
-      checkboxUncheckedColor: z14.string().optional().describe("Unchecked checkbox color (hex)"),
-      switchEnabledColor: z14.string().optional().describe("Enabled switch color (hex)"),
-      switchDisabledColor: z14.string().optional().describe("Disabled switch color (hex)"),
-      breadcrumbFontFamily: z14.string().optional().describe("Drill breadcrumb font family"),
-      breadcrumbFontColor: z14.string().optional().describe("Drill breadcrumb font color (hex)"),
-      breadcrumbActiveColor: z14.string().optional().describe("Active breadcrumb color (hex)"),
-      filterBadgeColor: z14.string().optional().describe("Multi-select filter badge color (hex)"),
-      filterBadgeTextColor: z14.string().optional().describe("Filter badge text color (hex)"),
-      datePickerColor: z14.string().optional().describe("Date picker accent color (hex)"),
+      buttonPrimaryColor: z15.string().optional().describe("Primary button background (hex)"),
+      buttonPrimaryTextColor: z15.string().optional().describe("Primary button text (hex)"),
+      buttonSecondaryColor: z15.string().optional().describe("Secondary button background (hex)"),
+      buttonSecondaryTextColor: z15.string().optional().describe("Secondary button text (hex)"),
+      checkboxCheckedColor: z15.string().optional().describe("Checked checkbox color (hex)"),
+      checkboxUncheckedColor: z15.string().optional().describe("Unchecked checkbox color (hex)"),
+      switchEnabledColor: z15.string().optional().describe("Enabled switch color (hex)"),
+      switchDisabledColor: z15.string().optional().describe("Disabled switch color (hex)"),
+      breadcrumbFontFamily: z15.string().optional().describe("Drill breadcrumb font family"),
+      breadcrumbFontColor: z15.string().optional().describe("Drill breadcrumb font color (hex)"),
+      breadcrumbActiveColor: z15.string().optional().describe("Active breadcrumb color (hex)"),
+      filterBadgeColor: z15.string().optional().describe("Multi-select filter badge color (hex)"),
+      filterBadgeTextColor: z15.string().optional().describe("Filter badge text color (hex)"),
+      datePickerColor: z15.string().optional().describe("Date picker accent color (hex)"),
       // --- Responsive Breakpoints ---
-      breakpointXl: z14.number().optional().describe("XL breakpoint width in px"),
-      breakpointLg: z14.number().optional().describe("LG breakpoint width in px"),
-      breakpointMd: z14.number().optional().describe("MD breakpoint width in px"),
-      breakpointSm: z14.number().optional().describe("SM breakpoint width in px"),
-      breakpointXs: z14.number().optional().describe("XS breakpoint width in px"),
+      breakpointXl: z15.number().optional().describe("XL breakpoint width in px"),
+      breakpointLg: z15.number().optional().describe("LG breakpoint width in px"),
+      breakpointMd: z15.number().optional().describe("MD breakpoint width in px"),
+      breakpointSm: z15.number().optional().describe("SM breakpoint width in px"),
+      breakpointXs: z15.number().optional().describe("XS breakpoint width in px"),
       // --- Metric Layout Columns ---
-      layoutColsXl: z14.number().optional().describe("Grid columns at XL breakpoint"),
-      layoutColsLg: z14.number().optional().describe("Grid columns at LG breakpoint"),
-      layoutColsMd: z14.number().optional().describe("Grid columns at MD breakpoint"),
-      layoutColsSm: z14.number().optional().describe("Grid columns at SM breakpoint"),
-      layoutColsXs: z14.number().optional().describe("Grid columns at XS breakpoint"),
-      layoutColsXxs: z14.number().optional().describe("Grid columns at XXS breakpoint"),
+      layoutColsXl: z15.number().optional().describe("Grid columns at XL breakpoint"),
+      layoutColsLg: z15.number().optional().describe("Grid columns at LG breakpoint"),
+      layoutColsMd: z15.number().optional().describe("Grid columns at MD breakpoint"),
+      layoutColsSm: z15.number().optional().describe("Grid columns at SM breakpoint"),
+      layoutColsXs: z15.number().optional().describe("Grid columns at XS breakpoint"),
+      layoutColsXxs: z15.number().optional().describe("Grid columns at XXS breakpoint"),
       // --- Chart Appearance (detailed) ---
       tooltipHeaderStyle: fontConfigInputSchema.describe("Tooltip header: fontSize, fontFamily, fontWeight, color"),
       tooltipLabelStyle: fontConfigInputSchema.describe("Tooltip label: fontSize, fontFamily, fontWeight, color"),
       tooltipValueStyle: fontConfigInputSchema.describe("Tooltip value: fontSize, fontFamily, fontWeight, color"),
-      labelPosition: z14.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
-      radialLabelPosition: z14.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
-      marginTop: z14.number().optional().describe("Chart top margin in pixels"),
-      marginLeft: z14.number().optional().describe("Chart left margin in pixels"),
-      marginRight: z14.number().optional().describe("Chart right margin in pixels"),
-      marginBottom: z14.number().optional().describe("Chart bottom margin in pixels"),
-      legendShow: z14.boolean().optional().describe("Show or hide chart legend"),
-      legendPosition: z14.enum([
+      labelPosition: z15.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
+      radialLabelPosition: z15.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
+      marginTop: z15.number().optional().describe("Chart top margin in pixels"),
+      marginLeft: z15.number().optional().describe("Chart left margin in pixels"),
+      marginRight: z15.number().optional().describe("Chart right margin in pixels"),
+      marginBottom: z15.number().optional().describe("Chart bottom margin in pixels"),
+      legendShow: z15.boolean().optional().describe("Show or hide chart legend"),
+      legendPosition: z15.enum([
         "top-left",
         "top-center",
         "top-right",
@@ -2804,17 +3080,17 @@ function registerCustomizeTheme(server, client) {
         "bottom-center",
         "bottom-right"
       ]).optional().describe("Legend position"),
-      legendLayout: z14.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
-      legendShape: z14.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
-      legendFontSize: z14.number().optional().describe("Legend font size"),
-      legendFontWeight: z14.number().optional().describe("Legend font weight"),
-      legendFontFamily: z14.string().optional().describe("Legend font family"),
-      legendColor: z14.string().optional().describe("Legend text color (hex)"),
-      legendTruncateLength: z14.number().optional().describe("Max characters before truncating legend"),
-      disableLegendScrolling: z14.boolean().optional().describe("Disable scrolling in legend"),
-      enableVariableLegendPosition: z14.boolean().optional().describe("Allow user to drag legend"),
-      legendTop: z14.number().optional().describe("Custom legend top offset"),
-      legendLeft: z14.number().optional().describe("Custom legend left offset"),
+      legendLayout: z15.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
+      legendShape: z15.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
+      legendFontSize: z15.number().optional().describe("Legend font size"),
+      legendFontWeight: z15.number().optional().describe("Legend font weight"),
+      legendFontFamily: z15.string().optional().describe("Legend font family"),
+      legendColor: z15.string().optional().describe("Legend text color (hex)"),
+      legendTruncateLength: z15.number().optional().describe("Max characters before truncating legend"),
+      disableLegendScrolling: z15.boolean().optional().describe("Disable scrolling in legend"),
+      enableVariableLegendPosition: z15.boolean().optional().describe("Allow user to drag legend"),
+      legendTop: z15.number().optional().describe("Custom legend top offset"),
+      legendLeft: z15.number().optional().describe("Custom legend left offset"),
       verticalAxis: axisSchema.describe("Vertical (Y) axis configuration"),
       horizontalAxis: axisSchema.describe("Horizontal (X) axis configuration")
     },
@@ -2888,71 +3164,141 @@ Use \`get_embed_details\` to view the full current theme configuration.` + GUEST
   );
 }
 
+// src/tools/embed/get-demo-link.ts
+import { z as z16 } from "zod";
+var HOUR_MS = 60 * 60 * 1e3;
+var DEFAULT_EXPIRY_HOURS = 24;
+var MAX_EXPIRY_HOURS = 24 * 30;
+function registerGetDemoLink(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "get_demo_link",
+    `Get a shareable demo URL for a dashboard embed scoped to a specific clientId \u2014 same link the UI's "Share Demo Link" generates. Loads the dashboard as that end-customer sees it. Use to verify ops-built widgets without a test app.`,
+    {
+      clientId: z16.string().describe("End-customer identifier to scope the preview to."),
+      dashboardName: z16.string().optional().describe("Dashboard name (non-technical). Preferred \u2014 pass with optional `workspaceName`."),
+      workspaceName: z16.string().optional().describe("Workspace name. Only needed if `dashboardName` is ambiguous."),
+      embedId: z16.string().optional().describe("Technical alternative to `dashboardName`."),
+      expiryHours: z16.number().min(1).max(MAX_EXPIRY_HOURS).optional().describe(`Token TTL in hours. Defaults to ${DEFAULT_EXPIRY_HOURS}. Max ${MAX_EXPIRY_HOURS} (30 days).`)
+    },
+    WRITE_CREATE,
+    async (params) => {
+      try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const dashboardName = embed.value.resolvedFrom?.dashboardName || null;
+        const ctx = await services.widgetService.resolveEmbedContext(embedId);
+        if (!ctx.dataAppName) {
+          return toolError(
+            `Could not resolve the data app for embed "${embedId}". The demo link needs a data app to mint a guest token against. Run \`list_data_apps\` to confirm one exists, or pass \`embedId\` for an embed with metadata.dataAppName populated.`
+          );
+        }
+        const dashboardSlug = ctx.externalDashboardId || ctx.dashboardId;
+        if (!dashboardSlug) {
+          return toolError(
+            `Embed "${embedId}" has no dashboardId/externalDashboardId \u2014 the demo URL requires one to load the dashboard. This is unexpected; verify the embed in the Databrain UI.`
+          );
+        }
+        const expiryHours = params.expiryHours ?? DEFAULT_EXPIRY_HOURS;
+        const { token } = await services.guestTokenService.generateToken({
+          clientId: params.clientId,
+          dataAppName: ctx.dataAppName,
+          allowedEmbeds: [embedId],
+          expiryTime: expiryHours * HOUR_MS
+        });
+        const baseUrl = client.getDemoDomain().replace(/\/+$/, "");
+        const demoUrl = `${baseUrl}/?token=${encodeURIComponent(token)}&dashboardId=${encodeURIComponent(dashboardSlug)}`;
+        return toolSuccess(
+          JSON.stringify({
+            demoUrl,
+            clientId: params.clientId,
+            dashboardName,
+            embedId,
+            dashboardId: dashboardSlug,
+            dataAppName: ctx.dataAppName,
+            expiresInHours: expiryHours,
+            note: `Open this URL in a browser to preview the dashboard exactly as the end-customer sees it. This matches the UI's "Share Demo Link" flow. Override the host with DATABRAIN_DEMO_DOMAIN for self-hosted / custom preview domains.`
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
 // src/tools/frontend/generate-guest-token.ts
-import { z as z15 } from "zod";
+import { z as z17 } from "zod";
 function registerGenerateGuestToken(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "generate_guest_token",
     "Generate a guest token for frontend embedding. Requires clientId. Omit dataAppName to auto-resolve.",
     {
-      clientId: z15.string().describe('Unique end-user identifier for multi-tenant filtering. Use "None" if no tenancy.'),
-      dataAppName: z15.string().optional().describe("Name of the data app. Omit to list available data apps."),
-      body: z15.record(z15.unknown()).optional().describe(
+      clientId: z17.string().describe('Unique end-user identifier for multi-tenant filtering. Use "None" if no tenancy.'),
+      dataAppName: z17.string().optional().describe("Name of the data app. Omit to list available data apps."),
+      body: z17.record(z17.unknown()).optional().describe(
         "Raw API body for POST /api/v2/guest-token/create. If provided, sent directly and convenience fields are ignored."
       ),
-      params: z15.object({
-        allowedEmbeds: z15.array(z15.string()).optional().describe("Restrict token to specific embed IDs"),
-        rlsSettings: z15.array(z15.object({
-          metricId: z15.string().describe("Metric ID"),
-          values: z15.record(z15.unknown()).describe("RLS values by column name")
+      params: z17.object({
+        allowedEmbeds: z17.array(z17.string()).optional().describe("Restrict token to specific embed IDs"),
+        rlsSettings: z17.array(z17.object({
+          metricId: z17.string().describe("Metric ID"),
+          values: z17.record(z17.unknown()).describe("RLS values by column name")
         })).optional().describe("Legacy alias used in docs/examples; forwarded as params.rlsSettings"),
-        appFilters: z15.array(z15.object({
-          metricId: z15.string().describe("Metric ID"),
-          values: z15.record(z15.unknown()).describe("Filter values by column name")
+        appFilters: z17.array(z17.object({
+          metricId: z17.string().describe("Metric ID"),
+          values: z17.record(z17.unknown()).describe("Filter values by column name")
         })).optional().describe("Metric-level app filters"),
-        dashboardAppFilters: z15.array(z15.object({
-          dashboardId: z15.string().describe("Dashboard ID"),
-          values: z15.record(z15.unknown()).describe("Filter values by dashboard filter name"),
-          isShowOnUrl: z15.boolean().optional().describe("Whether filters are shown in URL params")
+        dashboardAppFilters: z17.array(z17.object({
+          dashboardId: z17.string().describe("Dashboard ID"),
+          values: z17.record(z17.unknown()).describe("Filter values by dashboard filter name"),
+          isShowOnUrl: z17.boolean().optional().describe("Whether filters are shown in URL params")
         })).optional().describe("Dashboard-level app filters"),
-        hideDashboardFilters: z15.array(z15.string()).optional().describe("Dashboard filter names to hide"),
-        userIdentifier: z15.string().optional().describe("End-user identifier for private metrics support"),
-        timezone: z15.string().optional().describe('IANA timezone, e.g. "America/New_York"')
+        hideDashboardFilters: z17.array(z17.string()).optional().describe("Dashboard filter names to hide"),
+        userIdentifier: z17.string().optional().describe("End-user identifier for private metrics support"),
+        timezone: z17.string().optional().describe('IANA timezone, e.g. "America/New_York"')
       }).optional().describe("Advanced token params"),
       // Legacy convenience fields (auto-mapped into params for backward compatibility)
-      timezone: z15.string().optional().describe("Legacy: moved under params.timezone"),
-      allowedEmbeds: z15.array(z15.string()).optional().describe("Legacy: moved under params.allowedEmbeds"),
-      rlsSettings: z15.array(z15.object({
-        metricId: z15.string().describe("Metric ID"),
-        values: z15.record(z15.unknown()).describe("RLS values by column name")
+      timezone: z17.string().optional().describe("Legacy: moved under params.timezone"),
+      allowedEmbeds: z17.array(z17.string()).optional().describe("Legacy: moved under params.allowedEmbeds"),
+      rlsSettings: z17.array(z17.object({
+        metricId: z17.string().describe("Metric ID"),
+        values: z17.record(z17.unknown()).describe("RLS values by column name")
       })).optional().describe("Legacy: moved under params.rlsSettings"),
-      appFilters: z15.array(z15.object({
-        metricId: z15.string().describe("Metric ID"),
-        values: z15.record(z15.unknown()).describe("Filter values by column name")
+      appFilters: z17.array(z17.object({
+        metricId: z17.string().describe("Metric ID"),
+        values: z17.record(z17.unknown()).describe("Filter values by column name")
       })).optional().describe("Legacy: moved under params.appFilters"),
-      dashboardAppFilters: z15.array(z15.object({
-        dashboardId: z15.string().describe("Dashboard ID to apply filters to"),
-        values: z15.record(z15.unknown()).describe("Filter values for this dashboard"),
-        isShowOnUrl: z15.boolean().optional().describe("Whether filters are shown in URL params")
+      dashboardAppFilters: z17.array(z17.object({
+        dashboardId: z17.string().describe("Dashboard ID to apply filters to"),
+        values: z17.record(z17.unknown()).describe("Filter values for this dashboard"),
+        isShowOnUrl: z17.boolean().optional().describe("Whether filters are shown in URL params")
       })).optional().describe("Legacy: moved under params.dashboardAppFilters"),
-      permissions: z15.object({
-        isEnableArchiveMetrics: z15.boolean().optional(),
-        isEnableManageMetrics: z15.boolean().optional(),
-        isEnableCreateDashboardView: z15.boolean().optional(),
-        isEnableMetricUpdation: z15.boolean().optional(),
-        isEnableCustomizeLayout: z15.boolean().optional(),
-        isEnableUnderlyingData: z15.boolean().optional(),
-        isEnableDownloadMetrics: z15.boolean().optional(),
-        isShowSideBar: z15.boolean().optional(),
-        isShowDashboardName: z15.boolean().optional(),
-        isDisableMetricCreation: z15.boolean().optional()
+      permissions: z17.object({
+        isEnableArchiveMetrics: z17.boolean().optional(),
+        isEnableManageMetrics: z17.boolean().optional(),
+        isEnableCreateDashboardView: z17.boolean().optional(),
+        isEnableMetricUpdation: z17.boolean().optional(),
+        isEnableCustomizeLayout: z17.boolean().optional(),
+        isEnableUnderlyingData: z17.boolean().optional(),
+        isEnableDownloadMetrics: z17.boolean().optional(),
+        isShowSideBar: z17.boolean().optional(),
+        isShowDashboardName: z17.boolean().optional(),
+        isDisableMetricCreation: z17.boolean().optional()
       }).optional().describe("Runtime permission overrides (merge with and override embed-level settings)"),
-      theme: z15.record(z15.unknown()).optional().describe("Runtime theme overrides (overrides embed-level theme)"),
-      hideDashboardFilters: z15.array(z15.string()).optional().describe("Legacy: moved under params.hideDashboardFilters"),
-      userIdentifier: z15.string().optional().describe("Legacy: moved under params.userIdentifier"),
-      expiryTime: z15.number().optional().describe("Token TTL in milliseconds"),
-      datasourceName: z15.string().optional().describe("Datasource name for multi-datasource routing")
+      theme: z17.record(z17.unknown()).optional().describe("Runtime theme overrides (overrides embed-level theme)"),
+      hideDashboardFilters: z17.array(z17.string()).optional().describe("Legacy: moved under params.hideDashboardFilters"),
+      userIdentifier: z17.string().optional().describe("Legacy: moved under params.userIdentifier"),
+      expiryTime: z17.number().optional().describe("Token TTL in milliseconds"),
+      datasourceName: z17.string().optional().describe("Datasource name for multi-datasource routing")
     },
     WRITE_CREATE,
     async (params) => {
@@ -3005,7 +3351,7 @@ Next step: Use \`generate_embed_code\` to get copy-paste-ready frontend code.`
 }
 
 // src/tools/frontend/generate-embed-code.ts
-import { z as z16 } from "zod";
+import { z as z18 } from "zod";
 
 // src/templates/react.ts
 function kebabCase(str) {
@@ -3114,7 +3460,7 @@ export default function DatabrainEmbed() {
 ### Environment Variables
 Set the following environment variables on your backend server:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -3247,7 +3593,7 @@ export default function DatabrainEmbed() {
 ### Environment Variables
 Add the following to your \`.env.local\` file:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -3379,7 +3725,7 @@ onMounted(async () => {
 ### Environment Variables
 Set the following environment variables on your backend server:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -3529,7 +3875,7 @@ export class DatabrainEmbedComponent implements OnInit {
 ### Environment Variables
 Set the following environment variables on your backend server:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -3671,7 +4017,7 @@ app.listen(3001, () => {
 ### Environment Variables
 Set the following environment variables on your backend server:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -3803,7 +4149,7 @@ export default function DatabrainEmbed() {
 ### Environment Variables
 Set the following environment variables on your backend server:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -3950,7 +4296,7 @@ app.listen(3001, () => {
 ### Environment Variables
 Set the following environment variables on your backend server:
 - \`DATABRAIN_API_TOKEN\` - Your Databrain API token
-- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://app.usedatabrain.com)
+- \`DATABRAIN_API_URL\` - Your Databrain API base URL (e.g. https://api.usedatabrain.com)
 - \`DATABRAIN_DATA_APP_NAME\` - Default data app name for guest token generation
 
 ### Security
@@ -4001,22 +4347,22 @@ function registerGenerateEmbedCode(server, _client) {
     "generate_embed_code",
     "Generate framework-specific embed code (React, Next.js, Vue, Angular, Svelte, SolidJS, vanilla HTML).",
     {
-      embedId: z16.string().describe("The embed ID to generate code for"),
-      framework: z16.enum(FRAMEWORKS).describe("Frontend framework"),
-      embedType: z16.enum(["dashboard", "metric"]).optional().default("dashboard"),
-      options: z16.object({
-        enableDownloadCsv: z16.boolean().optional(),
-        enableEmailCsv: z16.boolean().optional(),
-        enableDownloadAllMetrics: z16.boolean().optional(),
-        enableDownloadAllPdf: z16.boolean().optional(),
-        disableFullscreen: z16.boolean().optional(),
-        isHideTablePreview: z16.boolean().optional(),
-        isHideChartSettings: z16.boolean().optional(),
-        isStickyDashboardFilters: z16.boolean().optional(),
-        enableMultiMetricFilters: z16.boolean().optional(),
-        themeName: z16.string().optional(),
-        customTheme: z16.record(z16.unknown()).optional(),
-        optionsIcon: z16.enum(["kebab-menu-vertical", "download"]).optional()
+      embedId: z18.string().describe("The embed ID to generate code for"),
+      framework: z18.enum(FRAMEWORKS).describe("Frontend framework"),
+      embedType: z18.enum(["dashboard", "metric"]).optional().default("dashboard"),
+      options: z18.object({
+        enableDownloadCsv: z18.boolean().optional(),
+        enableEmailCsv: z18.boolean().optional(),
+        enableDownloadAllMetrics: z18.boolean().optional(),
+        enableDownloadAllPdf: z18.boolean().optional(),
+        disableFullscreen: z18.boolean().optional(),
+        isHideTablePreview: z18.boolean().optional(),
+        isHideChartSettings: z18.boolean().optional(),
+        isStickyDashboardFilters: z18.boolean().optional(),
+        enableMultiMetricFilters: z18.boolean().optional(),
+        themeName: z18.string().optional(),
+        customTheme: z18.record(z18.unknown()).optional(),
+        optionsIcon: z18.enum(["kebab-menu-vertical", "download"]).optional()
       }).optional()
     },
     READ_ONLY,
@@ -4056,17 +4402,17 @@ ${generated.instructions}`;
 }
 
 // src/tools/analytics/list-dashboards.ts
-import { z as z17 } from "zod";
+import { z as z19 } from "zod";
 function registerListDashboards(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_dashboards",
     "List dashboards globally or for a specific data app.",
     {
-      scope: z17.enum(["auto", "global", "data_app"]).optional().describe(
+      scope: z19.enum(["auto", "global", "data_app"]).optional().describe(
         "Dashboard listing scope. auto: use data_app when dataAppName + API token are available, otherwise global."
       ),
-      dataAppName: z17.string().optional().describe("Data app name for data_app scope. Ignored for global scope.")
+      dataAppName: z19.string().optional().describe("Data app name for data_app scope. Ignored for global scope.")
     },
     READ_ONLY,
     async (params) => {
@@ -4101,7 +4447,7 @@ function registerListDashboards(server, client) {
 }
 
 // src/tools/query/ask-question.ts
-import { z as z18 } from "zod";
+import { z as z20 } from "zod";
 var MAX_DISPLAY_ROWS = 50;
 function formatDataTable(data, columns) {
   if (!Array.isArray(data) || data.length === 0) return "_No data returned._";
@@ -4131,16 +4477,16 @@ function registerAskQuestion(server, client) {
     "ask_question",
     "Ask a natural language question \u2014 converts to SQL, returns data + chart suggestion. Requires datamartName with a populated semantic layer.",
     {
-      question: z18.string().describe(
+      question: z20.string().describe(
         'The natural language question to ask (e.g. "What was total revenue last month?")'
       ),
-      datamartName: z18.string().optional().describe(
+      datamartName: z20.string().optional().describe(
         "Name of the datamart to query. Use `list_datamarts` to find available names. REQUIRED unless exactly one datamart exists (auto-resolved). Do NOT pass a workspace name here."
       ),
-      sessionId: z18.string().optional().describe(
+      sessionId: z20.string().optional().describe(
         "Session ID from a previous ask_question response, for follow-up questions."
       ),
-      timezone: z18.string().optional().describe('IANA timezone (e.g. "America/New_York"). Defaults to UTC.')
+      timezone: z20.string().optional().describe('IANA timezone (e.g. "America/New_York"). Defaults to UTC.')
     },
     WRITE_CREATE,
     async (params) => {
@@ -4154,7 +4500,13 @@ function registerAskQuestion(server, client) {
             );
           }
           if (datamarts.length === 1) {
-            datamartName = datamarts[0].name || datamarts[0].datamartName;
+            const resolvedName = datamarts[0].name || datamarts[0].datamartName;
+            if (!resolvedName) {
+              return toolError(
+                "Found one datamart, but the API did not return a usable name. Use `list_datamarts` to inspect the response and pass `datamartName` explicitly."
+              );
+            }
+            datamartName = resolvedName;
           } else {
             const list = datamarts.map(formatDatamart).join("\n");
             return toolSuccess(
@@ -4166,6 +4518,11 @@ Call \`ask_question\` again with the \`datamartName\` parameter.`
             );
           }
         }
+        if (!datamartName) {
+          return toolError(
+            "Could not resolve a datamart name. Use `list_datamarts`, then call `ask_question` again with `datamartName`."
+          );
+        }
         try {
           const semanticLayer = await services.queryApi.getSemanticLayer(
             datamartName
@@ -4305,14 +4662,14 @@ To fix this:
 }
 
 // src/tools/query/get-semantic-layer.ts
-import { z as z19 } from "zod";
+import { z as z21 } from "zod";
 function registerGetSemanticLayer(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "get_semantic_layer",
     "Get semantic layer metadata for a datamart: table/column descriptions, synonyms, completion score. Omit datamartName to auto-resolve.",
     {
-      datamartName: z19.string().optional().describe(
+      datamartName: z21.string().optional().describe(
         "Name of the datamart to inspect. Omit to list available datamarts."
       )
     },
@@ -4422,15 +4779,15 @@ ${result.feedback}`);
 }
 
 // src/tools/query/update-semantic-layer.ts
-import { z as z20 } from "zod";
-var columnSchema = z20.object({
-  name: z20.string().describe("Column name (must exist in the datamart)"),
-  description: z20.string().optional().describe("Business-friendly description of what this column represents"),
-  synonyms: z20.array(z20.string()).optional().describe(
+import { z as z22 } from "zod";
+var columnSchema2 = z22.object({
+  name: z22.string().describe("Column name (must exist in the datamart)"),
+  description: z22.string().optional().describe("Business-friendly description of what this column represents"),
+  synonyms: z22.array(z22.string()).optional().describe(
     'Alternative names users might use for this column (e.g. ["revenue", "sales amount"])'
   ),
-  miscellaneousInfo: z20.string().optional().describe("Additional context such as valid values, units, or caveats"),
-  columnType: z20.enum([
+  miscellaneousInfo: z22.string().optional().describe("Additional context such as valid values, units, or caveats"),
+  columnType: z22.enum([
     "String",
     "Long String",
     "String (Custom)",
@@ -4443,30 +4800,58 @@ var columnSchema = z20.object({
     "JSON"
   ]).nullable().optional().describe('Semantic column type. Use "Identifier" for IDs/foreign keys, "Number" for numeric values, "String" for text. Omit for date columns.')
 });
-var tableSchema = z20.object({
-  name: z20.string().describe("Table name (must exist in the datamart)"),
-  description: z20.string().optional().describe(
+var tableSchema2 = z22.object({
+  name: z22.string().describe("Table name (must exist in the datamart)"),
+  description: z22.string().optional().describe(
     "Business-friendly description of what this table represents"
   ),
-  synonyms: z20.array(z20.string()).optional().describe("Alternative names for this table"),
-  miscellaneousInfo: z20.string().optional().describe(
+  synonyms: z22.array(z22.string()).optional().describe("Alternative names for this table"),
+  miscellaneousInfo: z22.string().optional().describe(
     "Additional context such as how the table relates to other tables"
   ),
-  columns: z20.array(columnSchema).optional().describe("Column-level semantic definitions to update")
+  columns: z22.array(columnSchema2).optional().describe("Column-level semantic definitions to update")
 });
+function normalizeTablesForApi(tables) {
+  if (!tables) return void 0;
+  return tables.map((table) => {
+    const normalized = { name: table.name };
+    if (table.description !== void 0) normalized.description = table.description;
+    if (table.synonyms !== void 0) normalized.synonyms = table.synonyms;
+    if (table.miscellaneousInfo !== void 0) {
+      normalized.miscellaneousInfo = table.miscellaneousInfo;
+    }
+    if (table.columns !== void 0) {
+      normalized.columns = table.columns.map((column) => {
+        const normalizedColumn = { name: column.name };
+        if (column.description !== void 0) {
+          normalizedColumn.description = column.description;
+        }
+        if (column.synonyms !== void 0) normalizedColumn.synonyms = column.synonyms;
+        if (column.miscellaneousInfo !== void 0) {
+          normalizedColumn.miscellaneousInfo = column.miscellaneousInfo;
+        }
+        if (column.columnType !== void 0 && column.columnType !== null) {
+          normalizedColumn.columnType = column.columnType;
+        }
+        return normalizedColumn;
+      });
+    }
+    return normalized;
+  });
+}
 function registerUpdateSemanticLayer(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "update_semantic_layer",
     "Populate or update the semantic layer for a datamart. Add table/column descriptions, synonyms, context. Required before ask_question works. Auto-generate descriptions from column names when empty.",
     {
-      datamartName: z20.string().optional().describe(
+      datamartName: z22.string().optional().describe(
         "Name of the datamart to update. Omit to list available datamarts."
       ),
-      tables: z20.array(tableSchema).optional().describe(
+      tables: z22.array(tableSchema2).optional().describe(
         "Table and column definitions to update. Only include tables/columns you want to change."
       ),
-      feedback: z20.string().optional().describe(
+      feedback: z22.string().optional().describe(
         'General feedback or context about the datamart (e.g. "This datamart contains e-commerce data for the US market").'
       )
     },
@@ -4489,9 +4874,10 @@ function registerUpdateSemanticLayer(server, client) {
         });
         if (resolution.kind !== "resolved") return resolution.response;
         const datamartName = resolution.name;
+        const tables = normalizeTablesForApi(params.tables);
         await services.queryApi.updateSemanticLayer({
           datamartName,
-          tables: params.tables,
+          tables,
           feedback: params.feedback
         });
         const updatedParts = [];
@@ -4523,18 +4909,128 @@ You can now:
   );
 }
 
+// src/tools/query/semantic-generation.ts
+import { z as z23 } from "zod";
+function datamartIdFrom(datamart) {
+  return typeof datamart.id === "string" && datamart.id || typeof datamart._id === "string" && datamart._id || typeof datamart.datamartId === "string" && datamart.datamartId || null;
+}
+async function resolveDatamart(params) {
+  const services = createServiceBundle(params.client);
+  const datamarts = await services.datamartsApi.listDatamarts();
+  const resolution = resolveResource({
+    items: datamarts,
+    name: params.datamartName,
+    getName: (dm) => dm.name || dm.datamartName,
+    formatItem: formatDatamart,
+    resourceType: "datamart",
+    toolName: params.toolName
+  });
+  if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
+  const datamartId = datamartIdFrom(resolution.selected);
+  if (!datamartId) {
+    return {
+      ok: false,
+      response: toolError(
+        `Datamart "${resolution.name}" resolved by name but no id/_id/datamartId was returned. Use list_datamarts to verify the API response includes IDs.`
+      )
+    };
+  }
+  return {
+    ok: true,
+    datamartName: resolution.name,
+    datamartId
+  };
+}
+function registerStartSemanticLayerGeneration(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "start_semantic_layer_generation",
+    "Start backend semantic-layer auto-generation for a datamart. Returns an async job id to poll.",
+    {
+      datamartName: z23.string().optional().describe("Datamart name. Omit to list available datamarts")
+    },
+    WRITE_CREATE,
+    async (params) => {
+      try {
+        const resolved = await resolveDatamart({
+          client,
+          datamartName: params.datamartName,
+          toolName: "start_semantic_layer_generation"
+        });
+        if (!resolved.ok) return resolved.response;
+        const result = await services.queryApi.startSemanticLayerGeneration(
+          resolved.datamartId
+        );
+        return toolSuccess(
+          JSON.stringify(
+            {
+              datamartName: resolved.datamartName,
+              datamartId: resolved.datamartId,
+              ...result,
+              nextStep: "Call get_semantic_layer_generation_status with the same datamartName until status is complete or failed."
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+function registerGetSemanticLayerGenerationStatus(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "get_semantic_layer_generation_status",
+    "Get semantic-layer auto-generation job status for a datamart.",
+    {
+      datamartName: z23.string().optional().describe("Datamart name. Omit to list available datamarts")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const resolved = await resolveDatamart({
+          client,
+          datamartName: params.datamartName,
+          toolName: "get_semantic_layer_generation_status"
+        });
+        if (!resolved.ok) return resolved.response;
+        const result = await services.queryApi.getSemanticLayerGenerationStatus(
+          resolved.datamartId
+        );
+        return toolSuccess(
+          JSON.stringify(
+            {
+              datamartName: resolved.datamartName,
+              datamartId: resolved.datamartId,
+              ...result
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
 // src/tools/widgets/list-widgets.ts
-import { z as z21 } from "zod";
+import { z as z24 } from "zod";
 function registerListWidgets(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_widgets",
     "List widgets on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Returns each widget's externalMetricId (uuid, used for update/remove), metricId (slug), name, published state, and creator identifier.",
     {
-      clientId: z21.string().describe("Client/tenant identifier for this dashboard"),
-      dashboardName: z21.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z21.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z21.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
+      clientId: z24.string().describe("Client/tenant identifier for this dashboard"),
+      dashboardName: z24.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z24.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z24.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
     },
     READ_ONLY,
     async (params) => {
@@ -4580,28 +5076,28 @@ function registerListWidgets(server, client) {
 }
 
 // src/tools/widgets/add-widget.ts
-import { z as z22 } from "zod";
+import { z as z25 } from "zod";
 function registerAddWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "add_widget",
     "Add a widget to a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Cloning via `templateMetricId` is the recommended path \u2014 query, chart config, and datasource are all inherited. Data app and datasource auto-resolve; never ask the user for them.",
     {
-      clientId: z22.string().describe("Client/tenant identifier (widget is created in their scope)"),
-      dashboardName: z22.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z22.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z22.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z22.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
-      templateMetricId: z22.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
-      name: z22.string().optional().describe("Widget name (overrides template)"),
-      metricId: z22.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
-      query: z22.string().optional().describe("SQL query body (overrides template)"),
-      chartOptions: z22.record(z22.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
-      description: z22.string().optional(),
-      companyIntegrationId: z22.string().optional().describe("Datasource UUID override. Auto-resolved from `embedId` or sole active datasource; leave blank unless the user explicitly picked one by ID."),
-      integrationName: z22.string().optional().describe('Datasource display name (e.g. "Snowflake"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically.'),
-      isPublished: z22.boolean().optional().describe("Publish immediately (default true)"),
-      body: z22.record(z22.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params.")
+      clientId: z25.string().describe("Client/tenant identifier (widget is created in their scope)"),
+      dashboardName: z25.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z25.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z25.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z25.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      templateMetricId: z25.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
+      name: z25.string().optional().describe("Widget name (overrides template)"),
+      metricId: z25.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
+      query: z25.string().optional().describe("SQL query body (overrides template)"),
+      chartOptions: z25.record(z25.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
+      description: z25.string().optional(),
+      companyIntegrationId: z25.string().optional().describe("Datasource UUID override. Auto-resolved from `embedId` or sole active datasource; leave blank unless the user explicitly picked one by ID."),
+      integrationName: z25.string().optional().describe('Datasource display name (e.g. "Snowflake"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically.'),
+      isPublished: z25.boolean().optional().describe("Publish immediately (default true)"),
+      body: z25.record(z25.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params.")
     },
     WRITE_CREATE,
     async (params) => {
@@ -4711,20 +5207,20 @@ Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust
 }
 
 // src/tools/widgets/update-widget.ts
-import { z as z23 } from "zod";
+import { z as z26 } from "zod";
 function registerUpdateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "update_widget",
     "Update a widget on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId` + `set`. Data app auto-resolves from the dashboard.",
     {
-      externalMetricId: z23.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
-      clientId: z23.string().describe("Client/tenant identifier"),
-      dashboardName: z23.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z23.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z23.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z23.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
-      set: z23.record(z23.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
+      externalMetricId: z26.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
+      clientId: z26.string().describe("Client/tenant identifier"),
+      dashboardName: z26.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z26.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z26.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z26.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
+      set: z26.record(z26.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -4779,19 +5275,19 @@ Use \`list_widgets\` to verify.`
 }
 
 // src/tools/widgets/remove-widget.ts
-import { z as z24 } from "zod";
+import { z as z27 } from "zod";
 function registerRemoveWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "remove_widget",
     "Remove a widget from a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId`. Per-client soft delete \u2014 the widget stays on the template dashboard and on other customers' dashboards.",
     {
-      externalMetricId: z24.string().describe("Internal uuid of the widget (externalMetrics.id)"),
-      clientId: z24.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
-      dashboardName: z24.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z24.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z24.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z24.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
+      externalMetricId: z27.string().describe("Internal uuid of the widget (externalMetrics.id)"),
+      clientId: z27.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
+      dashboardName: z27.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z27.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z27.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z27.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
     },
     DESTRUCTIVE,
     async (params) => {
@@ -4839,21 +5335,21 @@ Note: this is a per-client soft delete. The widget remains available for other c
 }
 
 // src/tools/widgets/generate-widget.ts
-import { z as z25 } from "zod";
+import { z as z28 } from "zod";
 function registerGenerateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "generate_widget",
     "AI-generate a widget draft from a natural-language prompt. Does NOT persist \u2014 returns a draft to pass to `add_widget`. Non-technical flow: `clientId` + `dashboardName` (+ `workspaceName` if ambiguous); data app and datasource auto-resolve. Never ask the user for data app, datasource, or integration.",
     {
-      clientId: z25.string().describe("Client/tenant identifier"),
-      userInputs: z25.record(z25.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
-      dashboardName: z25.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z25.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z25.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z25.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
-      integrationId: z25.string().optional().describe("Technical override \u2014 the datasource UUID. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets."),
-      integrationName: z25.string().optional().describe("Technical override \u2014 datasource display name. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets.")
+      clientId: z28.string().describe("Client/tenant identifier"),
+      userInputs: z28.record(z28.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
+      dashboardName: z28.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z28.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z28.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z28.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      integrationId: z28.string().optional().describe("Technical override \u2014 the datasource UUID. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets."),
+      integrationName: z28.string().optional().describe("Technical override \u2014 datasource display name. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets.")
     },
     READ_ONLY,
     async (params) => {
@@ -4918,13 +5414,417 @@ function registerGenerateWidget(server, client) {
   );
 }
 
+// src/tools/widgets/create-or-update-metric-from-query.ts
+import { z as z29 } from "zod";
+var modeSchema = z29.enum(["dry_run", "apply"]).default("dry_run");
+var conflictStrategySchema = z29.enum(["fail", "update", "create_new"]).default("fail");
+function makePlanText(plan) {
+  return JSON.stringify(plan, null, 2);
+}
+function externalMetricIdFrom(widget) {
+  return typeof widget.externalMetricId === "string" && widget.externalMetricId || typeof widget.id === "string" && widget.id || typeof widget._id === "string" && widget._id || null;
+}
+function createSuffix() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+}
+function registerCreateOrUpdateMetricFromQuery(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "create_or_update_metric_from_query",
+    "Create or update a production metric/widget from validated SQL. Defaults to dry-run; apply requires explicit confirmation.",
+    {
+      mode: modeSchema.describe("dry_run returns the plan only; apply executes after confirmation"),
+      confirm: z29.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      conflictStrategy: conflictStrategySchema.describe("What to do if metricId already exists on the target dashboard"),
+      clientId: z29.string().describe("Client/tenant identifier for the dashboard widget scope"),
+      workspaceName: z29.string().describe("Target workspace name"),
+      dashboardName: z29.string().optional().describe("Dashboard name to attach to"),
+      embedId: z29.string().optional().describe("Technical embed id alternative to dashboardName"),
+      dataAppName: z29.string().optional().describe("Optional data app override"),
+      name: z29.string().describe("Metric/widget display name"),
+      metricId: z29.string().describe("Stable metric slug to create or update"),
+      query: z29.string().describe("SQL query already validated against the warehouse"),
+      description: z29.string().optional().describe("Metric description"),
+      chartOptions: z29.record(z29.unknown()).optional().describe("Chart configuration JSON"),
+      companyIntegrationId: z29.string().optional().describe("Datasource UUID override"),
+      integrationName: z29.string().optional().describe("Datasource display name override"),
+      isPublished: z29.boolean().optional().describe("Publish after apply. Defaults to false for production safety"),
+      requestedBy: z29.string().optional().describe("Human operator/request context to store on the metric when supported")
+    },
+    WRITE_IDEMPOTENT,
+    async (params) => {
+      try {
+        const mode = params.mode || "dry_run";
+        const conflictStrategy = params.conflictStrategy || "fail";
+        if (!params.name.trim()) return toolError("`name` cannot be empty.");
+        if (!params.metricId.trim()) return toolError("`metricId` cannot be empty.");
+        if (!params.query.trim()) return toolError("`query` cannot be empty.");
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const ctx = await services.widgetService.resolveEmbedContext(embedId);
+        if (!ctx.externalDashboardId) {
+          return toolError(
+            `Dashboard "${params.dashboardName || embedId}" has no externalDashboardId. Verify with get_embed_details before creating metrics.`
+          );
+        }
+        const dataAppName = await services.widgetService.resolveDataAppName(
+          params.dataAppName,
+          embedId
+        );
+        if (!dataAppName.ok) return toolError(dataAppName.error);
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          dataAppName.value,
+          [embedId]
+        );
+        const datasource = await services.widgetService.resolveDatasource(guestToken, {
+          embedId,
+          clientId: params.clientId,
+          integrationId: params.companyIntegrationId,
+          integrationName: params.integrationName
+        });
+        if (!datasource.ok) return toolError(datasource.error);
+        const widgets = await services.widgetsApi.listWidgets(embedId, params.clientId);
+        const existing = widgets.find((widget) => widget.metricId === params.metricId);
+        const existingExternalMetricId = existing ? externalMetricIdFrom(existing) : null;
+        if (existing && conflictStrategy === "fail") {
+          return toolError(
+            `MetricId "${params.metricId}" already exists on this dashboard. Retry with conflictStrategy="update" to update it or "create_new" to create a suffixed copy.`
+          );
+        }
+        if (existing && conflictStrategy === "update" && !existingExternalMetricId) {
+          return toolError(
+            `MetricId "${params.metricId}" exists but no externalMetricId/id was returned, so it cannot be updated safely.`
+          );
+        }
+        const finalMetricId = existing && conflictStrategy === "create_new" ? `${params.metricId}-${createSuffix()}` : params.metricId;
+        const createBody = {
+          name: params.name,
+          metricId: finalMetricId,
+          query: params.query,
+          description: params.description || "",
+          chartOptions: params.chartOptions || {},
+          companyIntegrationId: datasource.value.integrationId,
+          integrationName: datasource.value.integrationName,
+          isPublished: params.isPublished ?? false,
+          isCreatedByClient: false,
+          createdBy: params.requestedBy,
+          externalDashboardIds: [{ externalDashboardId: ctx.externalDashboardId }]
+        };
+        const updateSet = {
+          name: params.name,
+          query: params.query,
+          description: params.description || "",
+          chartOptions: params.chartOptions || {},
+          companyIntegrationId: datasource.value.integrationId,
+          integrationName: datasource.value.integrationName,
+          isPublished: params.isPublished ?? false,
+          createdBy: params.requestedBy
+        };
+        const operation = existing && conflictStrategy === "update" ? "update_metric" : "create_metric";
+        const plan = {
+          mode,
+          operation,
+          safety: productionSafetyNote(params.workspaceName),
+          requiredApplyConfirmation: APPLY_TO_PRODUCTION_CONFIRMATION,
+          resolved: {
+            workspaceName: params.workspaceName,
+            dashboardName: embed.value.resolvedFrom?.dashboardName || params.dashboardName || null,
+            embedId,
+            dataAppName: dataAppName.value,
+            externalDashboardId: ctx.externalDashboardId,
+            clientId: params.clientId,
+            datasource: datasource.value
+          },
+          conflict: existing ? {
+            metricId: existing.metricId || params.metricId,
+            externalMetricId: existingExternalMetricId,
+            strategy: conflictStrategy
+          } : null,
+          metric: operation === "update_metric" ? { externalMetricId: existingExternalMetricId, set: updateSet } : createBody
+        };
+        if (mode === "dry_run") {
+          return toolSuccess(
+            makePlanText({
+              ...plan,
+              status: "dry_run_only",
+              nextStep: `Review this plan. To execute, call again with mode="apply" and confirm="${APPLY_TO_PRODUCTION_CONFIRMATION}".`
+            })
+          );
+        }
+        const guardError = validateProductionApply({
+          workspaceName: params.workspaceName,
+          confirm: params.confirm
+        });
+        if (guardError) return toolError(guardError);
+        if (operation === "update_metric") {
+          const result2 = await services.widgetsApi.updateMetric(guestToken, {
+            externalMetricId: existingExternalMetricId,
+            set: updateSet
+          });
+          if (result2.error) {
+            return toolError(`Metric update failed: ${stringify(result2.error)}`);
+          }
+          return toolSuccess(
+            makePlanText({
+              ...plan,
+              status: "applied",
+              result: result2,
+              verifyWith: "list_widgets"
+            })
+          );
+        }
+        const result = await services.widgetsApi.createMetric(guestToken, createBody);
+        if (result.error) {
+          return toolError(`Metric creation failed: ${stringify(result.error)}`);
+        }
+        return toolSuccess(
+          makePlanText({
+            ...plan,
+            status: "applied",
+            result,
+            verifyWith: "list_widgets"
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/validate-metric-spec.ts
+import { z as z30 } from "zod";
+function registerValidateMetricSpec(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "validate_metric_spec",
+    "Validate a production metric spec from SQL without saving it. Resolves dashboard, data app, datasource, conflicts, and required fields.",
+    {
+      clientId: z30.string().describe("Client/tenant identifier used to validate dashboard widget scope"),
+      workspaceName: z30.string().describe("Target production-backed workspace name"),
+      dashboardName: z30.string().optional().describe("Dashboard name to attach to"),
+      embedId: z30.string().optional().describe("Technical embed id alternative to dashboardName"),
+      dataAppName: z30.string().optional().describe("Optional data app override"),
+      name: z30.string().describe("Metric/widget display name"),
+      metricId: z30.string().describe("Stable metric slug to create or update"),
+      query: z30.string().describe("SQL query already validated against the warehouse"),
+      description: z30.string().optional().describe("Metric description"),
+      chartOptions: z30.record(z30.unknown()).optional().describe("Chart configuration JSON"),
+      companyIntegrationId: z30.string().optional().describe("Datasource UUID override"),
+      integrationName: z30.string().optional().describe("Datasource display name override")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        if (!params.name.trim()) return toolError("`name` cannot be empty.");
+        if (!params.metricId.trim()) return toolError("`metricId` cannot be empty.");
+        if (!params.query.trim()) return toolError("`query` cannot be empty.");
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const ctx = await services.widgetService.resolveEmbedContext(embedId);
+        if (!ctx.externalDashboardId) {
+          return toolError(
+            `Dashboard "${params.dashboardName || embedId}" has no externalDashboardId. Verify with get_embed_details before creating metrics.`
+          );
+        }
+        const dataAppName = await services.widgetService.resolveDataAppName(
+          params.dataAppName,
+          embedId
+        );
+        if (!dataAppName.ok) return toolError(dataAppName.error);
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          dataAppName.value,
+          [embedId]
+        );
+        const datasource = await services.widgetService.resolveDatasource(guestToken, {
+          embedId,
+          clientId: params.clientId,
+          integrationId: params.companyIntegrationId,
+          integrationName: params.integrationName
+        });
+        if (!datasource.ok) return toolError(datasource.error);
+        const widgets = await services.widgetsApi.listWidgets(embedId, params.clientId);
+        const existing = widgets.find((widget) => widget.metricId === params.metricId);
+        return toolSuccess(
+          JSON.stringify(
+            {
+              status: "valid_for_production_dry_run",
+              safety: productionSafetyNote(params.workspaceName),
+              resolved: {
+                workspaceName: params.workspaceName,
+                dashboardName: embed.value.resolvedFrom?.dashboardName || params.dashboardName || null,
+                embedId,
+                dataAppName: dataAppName.value,
+                externalDashboardId: ctx.externalDashboardId,
+                datasource
+              },
+              conflict: existing ? {
+                strategyNeeded: true,
+                metricId: existing.metricId,
+                externalMetricId: existing.externalMetricId || existing.id || existing._id || null,
+                name: existing.name || null
+              } : null,
+              proposedMetric: {
+                name: params.name,
+                metricId: params.metricId,
+                query: params.query,
+                description: params.description || "",
+                chartOptions: params.chartOptions || {},
+                isPublishedDefault: false
+              },
+              nextStep: `Call create_or_update_metric_from_query with mode="dry_run" first, then mode="apply" and confirm="${APPLY_TO_PRODUCTION_CONFIRMATION}" only after reviewing the plan.`
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/reports/list-scheduled-reports.ts
+import { z as z31 } from "zod";
+function registerListScheduledReports(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "list_scheduled_reports",
+    "List configured scheduled reports for a specific client/dashboard embed. Shows schedule metadata, not delivery success history.",
+    {
+      clientId: z31.string().describe("Client/tenant identifier. Required by the current backend API for non-empty results"),
+      dashboardName: z31.string().optional().describe("Dashboard name to inspect"),
+      workspaceName: z31.string().optional().describe("Workspace name if dashboardName is ambiguous"),
+      embedId: z31.string().optional().describe("Technical embed id alternative to dashboardName"),
+      userIdentifier: z31.string().optional().describe("Optional creator/user filter"),
+      pageNumber: z31.number().int().positive().optional().describe("Page number when pagination is enabled"),
+      isPagination: z31.boolean().optional().describe("Enable backend pagination")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const reports = await services.scheduledReportsApi.listByEmbed({
+          embedId,
+          clientId: params.clientId,
+          userIdentifier: params.userIdentifier,
+          pageNumber: params.pageNumber,
+          isPagination: params.isPagination
+        });
+        return toolSuccess(
+          JSON.stringify(
+            {
+              count: Array.isArray(reports) ? reports.length : 0,
+              dashboardName: embed.value.resolvedFrom?.dashboardName || params.dashboardName || null,
+              embedId,
+              clientId: params.clientId,
+              note: "This lists configured schedules only. Delivery success/failure history is not persisted in the current MCP/API surface yet.",
+              reports: (Array.isArray(reports) ? reports : []).map((report) => ({
+                id: report.id || null,
+                subject: report.subject || null,
+                nextScheduledAt: report.nextScheduledAt || null,
+                recipientCount: Array.isArray(report.emails) ? report.emails.length : null,
+                chartCount: Array.isArray(report.scheduleEmailReportCharts) ? report.scheduleEmailReportCharts.length : null,
+                isDownloadFile: report.isDownloadFile ?? null,
+                downloadFileFormat: report.downloadFileFormat || null,
+                timeConfigurations: report.timeConfigurations || null
+              }))
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/auth/whoami.ts
+function registerWhoami(server, client) {
+  server.tool(
+    "whoami",
+    "Return the credential currently used for API calls. Use to confirm which auth mode this MCP session is operating under before mutating actions.",
+    {},
+    READ_ONLY,
+    async () => {
+      const auth = client.getActiveAuth();
+      if (auth.source === "service-token") {
+        return toolSuccess(
+          JSON.stringify(
+            {
+              status: "authenticated",
+              activeBearer: "service-token",
+              note: "Org-level service token (DATABRAIN_SERVICE_TOKEN). Per-user identity is NOT bound \u2014 mutations are audit-logged as actor=system. Per-user binding will be available once the OAuth login flow ships."
+            },
+            null,
+            2
+          )
+        );
+      }
+      if (auth.source === "api-token") {
+        return toolSuccess(
+          JSON.stringify(
+            {
+              status: "authenticated",
+              activeBearer: "api-token",
+              note: "Per-data-app API token. Limited to embedding operations on that data app. Org-level setup tools require DATABRAIN_SERVICE_TOKEN."
+            },
+            null,
+            2
+          )
+        );
+      }
+      return toolSuccess(
+        JSON.stringify(
+          {
+            status: "not_authenticated",
+            activeBearer: "none",
+            note: "No usable credential is configured. Set DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN in the MCP config."
+          },
+          null,
+          2
+        )
+      );
+    }
+  );
+}
+
 // src/tools/registry.ts
 function registerAllTools(server, client) {
+  registerWhoami(server, client);
   registerListDatasources(server, client);
   registerDiscoverDatasourceSchema(server, client);
   registerListDatamarts(server, client);
   registerListWorkspaces(server, client);
-  registerLinkDatamartToWorkspace(server, client);
+  registerSyncDatasource(server, client);
+  registerCreateDatamart(server, client);
   registerListDataApps(server, client);
   registerCreateDataApp(server, client);
   registerListApiTokens(server, client);
@@ -4935,17 +5835,23 @@ function registerAllTools(server, client) {
   registerGetEmbedDetails(server, client);
   registerUpdateEmbed(server, client);
   registerCustomizeTheme(server, client);
+  registerGetDemoLink(server, client);
   registerGenerateGuestToken(server, client);
   registerGenerateEmbedCode(server, client);
   registerListDashboards(server, client);
   registerAskQuestion(server, client);
   registerGetSemanticLayer(server, client);
   registerUpdateSemanticLayer(server, client);
+  registerStartSemanticLayerGeneration(server, client);
+  registerGetSemanticLayerGenerationStatus(server, client);
   registerListWidgets(server, client);
+  registerValidateMetricSpec(server, client);
+  registerCreateOrUpdateMetricFromQuery(server, client);
   registerAddWidget(server, client);
   registerUpdateWidget(server, client);
   registerRemoveWidget(server, client);
   registerGenerateWidget(server, client);
+  registerListScheduledReports(server, client);
 }
 
 // src/resources/content/getting-started.ts
@@ -7308,7 +8214,7 @@ Then create an embed configuration with tenancy settings:
 
 ### Step 5: Generate Guest Tokens Per Tenant
 
-On your backend, when a user from "Acme Corp" (org_id = "acme") logs in:
+On your backend, when a user from tenant A (org_id = "tenant_a") logs in:
 
 \`\`\`typescript
 // Server-side
@@ -7320,12 +8226,12 @@ const guestToken = await fetch('https://api.usedatabrain.com/api/v2/guest-token/
   },
   body: JSON.stringify({
     embedId: 'embed-789',
-    clientId: 'acme',  // Maps to org_id values in the database
+    clientId: 'tenant_a',  // Maps to org_id values in the database
   }),
 });
 \`\`\`
 
-When a user from "Globex" (org_id = "globex") logs in:
+When a user from tenant B (org_id = "tenant_b") logs in:
 
 \`\`\`typescript
 const guestToken = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
@@ -7336,7 +8242,7 @@ const guestToken = await fetch('https://api.usedatabrain.com/api/v2/guest-token/
   },
   body: JSON.stringify({
     embedId: 'embed-789',
-    clientId: 'globex',
+    clientId: 'tenant_b',
   }),
 });
 \`\`\`
@@ -7344,20 +8250,20 @@ const guestToken = await fetch('https://api.usedatabrain.com/api/v2/guest-token/
 ### Step 6: Render
 
 Both users see the same dashboard layout and metrics, but:
-- Acme sees only their projects, tasks, and team members
-- Globex sees only their projects, tasks, and team members
+- Tenant A sees only their projects, tasks, and team members
+- Tenant B sees only their projects, tasks, and team members
 - Both see all task statuses (shared reference table)
 
 ### Result
 
 \`\`\`
-Acme User sees:
-  - 12 projects (all with org_id = 'acme')
+Tenant A user sees:
+  - 12 projects (all with org_id = 'tenant_a')
   - 87 tasks
   - 15 team members
 
-Globex User sees:
-  - 8 projects (all with org_id = 'globex')
+Tenant B user sees:
+  - 8 projects (all with org_id = 'tenant_b')
   - 45 tasks
   - 9 team members
 \`\`\`
@@ -8018,8 +8924,10 @@ Wait for explicit confirmation before calling \`remove_widget({ externalMetricId
 **Step 4 \u2014 Verify**
 Call \`list_widgets({ clientId, dashboardName, workspaceName? })\` again. Present the updated list and confirm the changes match what the user asked for.
 
-**Step 5 \u2014 (Optional) regenerate guest token for live preview**
-If the user wants to see the changes in their running app, regenerate their guest token and reload. The MCP tools mint tokens internally for widget operations; a cached frontend token will not show the changes until refreshed.
+**Step 5 \u2014 Hand off the demo link**
+Always close with a demo link so the user can verify visually. Call \`get_demo_link({ clientId, dashboardName, workspaceName? })\` \u2014 it returns the same URL the Databrain UI's "Share Demo Link" button generates: a hosted preview page that loads the dashboard exactly as that \`clientId\` will see it. Default expiry is 24h; pass \`expiryHours\` to override.
+
+Present the URL to the user and remind them: (a) only \`isPublished: true\` widgets appear in the preview, so flag any unpublished widgets from the Step 4 \`list_widgets\` output; (b) if they already have the embed wired up in their own app, the cached frontend guest token there must be refreshed before changes appear.
 
 **Important rules:**
 - STOP after each step. Present results and wait for user input before proceeding.
@@ -8029,6 +8937,108 @@ If the user wants to see the changes in their running app, regenerate their gues
 
 After completion, suggest: \`brand-my-embed\` if they want to adjust theme, or \`manage-embeds\` if they want to tweak access settings / options.`;
 
+// src/prompts/sql-to-metric-migration.ts
+var sqlToMetricMigrationPrompt = `You are helping migrate validated warehouse SQL into Databrain metrics/widgets for a production-backed workspace.
+
+This workflow is built for agent-assisted SQL migration: the user already has SQL converted and validated against their warehouse. Your job is to resolve the Databrain dashboard/data-app/datasource context, validate the metric spec, produce a dry-run plan, and only apply after explicit confirmation.
+
+**Critical safety rules**
+- Default to dry-run. Never apply on the first pass.
+- Applying requires the exact confirmation string: \`APPLY_TO_PRODUCTION\`.
+- Service-token mode means writes are attributed as system until OAuth ships. State that clearly before apply.
+- Do not create datasources or workspaces in this workflow.
+- If a datamart is needed, use \`create_datamart\` in \`dry_run\` first; apply only after confirmation.
+- Keep \`isPublished: false\` unless the user explicitly asks to publish.
+
+**Minimum inputs**
+- \`clientId\`
+- \`workspaceName\`
+- \`dashboardName\` or \`embedId\`
+- \`metricId\`
+- \`name\`
+- \`query\`
+- Optional: \`description\`, \`chartOptions\`, \`integrationName\`, \`companyIntegrationId\`
+
+**Step 1 \u2014 Check context**
+Call:
+\`\`\`
+list_workspaces
+list_dashboards({ workspaceName })
+list_widgets({ clientId, dashboardName, workspaceName })
+\`\`\`
+Show the current target dashboard and existing widgets. If \`metricId\` already exists, tell the user they must choose \`conflictStrategy: "update"\` or \`"create_new"\`.
+
+**Step 2 \u2014 Validate without saving**
+Call:
+\`\`\`
+validate_metric_spec({
+  clientId,
+  workspaceName,
+  dashboardName,
+  metricId,
+  name,
+  query,
+  description,
+  chartOptions
+})
+\`\`\`
+Present the resolved data app, datasource, embed id, dashboard id, and any conflict.
+
+**Step 3 \u2014 Dry-run the write**
+Call:
+\`\`\`
+create_or_update_metric_from_query({
+  mode: "dry_run",
+  conflictStrategy,
+  clientId,
+  workspaceName,
+  dashboardName,
+  metricId,
+  name,
+  query,
+  description,
+  chartOptions,
+  isPublished: false
+})
+\`\`\`
+Show the exact plan. Stop and ask the user to review it.
+
+**Step 4 \u2014 Apply only after explicit confirmation**
+Only after the user approves, call:
+\`\`\`
+create_or_update_metric_from_query({
+  mode: "apply",
+  confirm: "APPLY_TO_PRODUCTION",
+  conflictStrategy,
+  clientId,
+  workspaceName,
+  dashboardName,
+  metricId,
+  name,
+  query,
+  description,
+  chartOptions,
+  isPublished: false,
+  requestedBy: "<human/operator context>"
+})
+\`\`\`
+Never invent the confirmation. The user must provide explicit approval.
+
+**Step 5 \u2014 Verify**
+Call:
+\`\`\`
+list_widgets({ clientId, dashboardName, workspaceName })
+get_demo_link({ clientId, dashboardName, workspaceName })
+\`\`\`
+Tell the user that unpublished widgets may not appear in the preview until published.
+
+**Scheduled reports**
+If the user asks about schedule visibility, call:
+\`\`\`
+list_scheduled_reports({ clientId, dashboardName, workspaceName })
+\`\`\`
+Clarify that this lists configured schedules only. Delivery success/failure history is not yet persisted in the MCP/API surface.`;
+
 // src/prompts/registry.ts
 var prompts = [
   {
@@ -8060,6 +9070,11 @@ var prompts = [
     name: "customize-customer-dashboard",
     description: "Add, modify, or remove widgets on a specific customer's dashboard embed. Per-client scope \u2014 changes only affect that customer.",
     content: customizeCustomerDashboardPrompt
+  },
+  {
+    name: "sql-to-metric-migration",
+    description: "Production-safe SQL-to-metric migration workflow: validate, dry-run, then apply with explicit confirmation.",
+    content: sqlToMetricMigrationPrompt
   }
 ];
 function registerAllPrompts(server) {
@@ -8080,24 +9095,38 @@ function registerAllPrompts(server) {
 
 // src/server.ts
 function createServer(config) {
+  const client = new DatabrainClient(config);
+  const auth = client.getActiveAuth();
+  let operatorBlurb;
+  if (auth.source === "service-token") {
+    operatorBlurb = "OPERATOR IDENTITY: service-token mode. Calls are authenticated at org level \u2014 actions in the audit log are tagged actor=system, not a specific user. Per-user identity binding will be added when the OAuth-based login flow ships. Do NOT ask the user for credentials or tokens.\n\n";
+  } else if (auth.source === "api-token") {
+    operatorBlurb = "OPERATOR IDENTITY: API-token-only mode. A per-data-app API token is configured, but DATABRAIN_SERVICE_TOKEN is not. Embedding operations can use the configured API token, but org-level setup tools require DATABRAIN_SERVICE_TOKEN in the MCP config.\n\n";
+  } else {
+    operatorBlurb = "OPERATOR IDENTITY: no usable token is configured. The MCP server normally refuses this config at startup. Ask the user to add DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN to the MCP config before proceeding.\n\n";
+  }
+  const serviceTokenStatus = config.serviceToken ? "This MCP server has DATABRAIN_SERVICE_TOKEN configured; never ask the user for it." : "DATABRAIN_SERVICE_TOKEN is not configured. Ask the user to add it to the MCP config only if org-level setup is needed.";
+  const apiTokenStatus = client.hasApiToken() ? "This MCP server has a per-data-app API token configured." : "Created/rotated via create_api_token or rotate_api_token during setup when DATABRAIN_SERVICE_TOKEN is available.";
   const server = new McpServer(
     {
       name: "databrain",
-      version: "0.1.0",
-      description: "Databrain MCP Server \u2014 embed analytics dashboards and charts into your app. Focused on embed discovery, deterministic embed updates, theming, filters, localization, permissions, and guest token generation."
+      version: MCP_SERVER_VERSION,
+      description: "Databrain MCP Server \u2014 embed analytics dashboards and charts into your app. Supports embed setup, semantic-layer maintenance, production dry-run/apply metric creation, theming, filters, permissions, and guest token generation."
     },
     {
-      instructions: `Databrain uses two token types \u2014 never confuse them:
-\u2022 SERVICE TOKEN (DATABRAIN_SERVICE_TOKEN): org-level, pre-configured in MCP server config. Used for: list_datasources, discover_datasource_schema, list_datamarts, list_workspaces, link_datamart_to_workspace, list_data_apps, create_data_app, list_api_tokens, create_api_token, rotate_api_token, list_dashboards (workspace scope), ask_question, get_semantic_layer, update_semantic_layer. You already have this \u2014 never ask the user for it.
-\u2022 API TOKEN (per data app): scoped to one data app, used for embedding operations (list_embeds, get_embed_details, create_embed, update_embed, generate_guest_token) and data-app scoped dashboard listing. Created/rotated via create_api_token or rotate_api_token during setup.
+      instructions: operatorBlurb + `Databrain uses two token types \u2014 never confuse them:
+\u2022 SERVICE TOKEN (DATABRAIN_SERVICE_TOKEN): org-level, pre-configured in MCP server config. Used for: list_datasources, discover_datasource_schema, sync_datasource, list_datamarts, create_datamart, list_workspaces, list_data_apps, create_data_app, list_api_tokens, create_api_token, rotate_api_token, list_dashboards (workspace scope), ask_question, get_semantic_layer, update_semantic_layer, start_semantic_layer_generation, get_semantic_layer_generation_status. ${serviceTokenStatus}
+\u2022 API TOKEN (per data app): scoped to one data app, used for embedding operations (list_embeds, get_embed_details, create_embed, update_embed, generate_guest_token), data-app scoped dashboard listing, widget CRUD/metric creation through guest-token APIs, and list_scheduled_reports. ${apiTokenStatus}
 
-3 core use cases \u2014 match the user's scenario to the right prompt:
+4 core use cases \u2014 match the user's scenario to the right prompt:
 1. Embed existing dashboard \u2192 prompt: embed-existing-dashboard (list_data_apps \u2192 create_api_token \u2192 list_dashboards \u2192 create_embed \u2192 generate_guest_token \u2192 generate_embed_code)
 2. Blank dashboard per client \u2192 prompt: embed-blank-dashboard (list_data_apps \u2192 list_datamarts \u2192 create_embed with clientId per client \u2192 generate_guest_token \u2192 generate_embed_code)
 3. Explore & query data \u2192 prompt: query-data (list_datamarts \u2192 get_semantic_layer \u2192 if empty, auto-generate descriptions with update_semantic_layer or use populate-semantic-layer prompt \u2192 ask_question)
+4. SQL-to-metric migration \u2192 prompt: sql-to-metric-migration (validate_metric_spec \u2192 create_or_update_metric_from_query dry_run \u2192 apply only with explicit production confirmation)
+
+Production safety: OAuth may not be available yet. In service-token mode, writes are actor=system. For create_datamart and create_or_update_metric_from_query, dry_run is the default. Apply requires confirm="APPLY_TO_PRODUCTION" after the user reviews the plan. Do not apply from a vague request.
 
-Infrastructure CREATION (datasources, datamarts, workspaces) is done in the Databrain UI.
-However, the **semantic layer** is populated and maintained entirely via MCP tools (get_semantic_layer, update_semantic_layer). When the semantic layer is empty, YOU (the assistant) should auto-generate descriptions from table/column names and push them with update_semantic_layer \u2014 do NOT send the user to the UI for this.
+Infrastructure creation is intentionally narrow in MCP: datasource and workspace creation still happen outside this workflow; sync_datasource and dry-run/apply create_datamart are available. The semantic layer is populated and maintained via MCP tools (get_semantic_layer, update_semantic_layer, start_semantic_layer_generation, get_semantic_layer_generation_status). When the semantic layer is empty, use these tools \u2014 do NOT send the user to the UI for semantic metadata.
 
 After embed setup, customize with: brand-my-embed prompt for theming. Use update_embed (body passthrough) for filters, localization, and permissions.
 Use generate_guest_token for frontend auth and generate_embed_code for framework snippets.
@@ -8114,7 +9143,6 @@ IMPORTANT \u2014 Be interactive. Present results from each tool call and ask the
 Trigger keywords: embed, dashboard, analytics, Databrain, guest token, theme, filters, permissions, datasource, datamart, workspace, metric creation.`
     }
   );
-  const client = new DatabrainClient(config);
   registerAllTools(server, client);
   registerAllResources(server);
   registerAllPrompts(server);
@@ -8122,7 +9150,6 @@ Trigger keywords: embed, dashboard, analytics, Databrain, guest token, theme, fi
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
 function banner(msg) {
   process.stderr.write(`[databrain] ${msg}
 `);
@@ -8133,7 +9160,7 @@ async function main() {
     const server = createServer(config);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    banner(`v${VERSION} ready (21 tools, 11 resources, 5 prompts)`);
+    banner(`v${MCP_SERVER_VERSION} ready`);
   } catch (error) {
     logger.error("Failed to start server", error);
     process.exit(1);