@databrainhq/mcp-server 0.2.11 → 0.2.13

package/dist/index.js

@@ -8,11 +8,10 @@ import { z, ZodError } from "zod";
 var configSchema = z.object({
   serviceToken: z.string().min(1).optional(),
   apiToken: z.string().min(1).optional(),
-  pat: z.string().min(1).optional(),
   apiUrl: z.string().url().default("https://api.usedatabrain.com"),
   demoDomain: z.string().url().default("https://demo.usedatabrain.com")
-}).refine((c) => c.serviceToken || c.apiToken || c.pat, {
-  message: "At least one of DATABRAIN_PAT, DATABRAIN_SERVICE_TOKEN, or DATABRAIN_API_TOKEN must be set"
+}).refine((c) => c.serviceToken || c.apiToken, {
+  message: "At least one of DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN must be set"
 });
 function formatConfigError(err) {
   const issues = err.issues.map((i) => i.message);
@@ -21,10 +20,8 @@ function formatConfigError(err) {
     lines.push(`  - ${issue}`);
   }
   lines.push("");
-  lines.push("  Either:");
-  lines.push("    \u2022 Set DATABRAIN_PAT to a Personal Access Token (Settings > Personal Access Tokens) \u2014 preferred, binds this MCP session to your user.");
-  lines.push("    \u2022 OR set DATABRAIN_SERVICE_TOKEN (Settings > Service Tokens) \u2014 org-level, no per-user audit; the `connect` tool can mint a PAT on top.");
-  lines.push('  Then add to your MCP config: { "env": { "DATABRAIN_PAT": "..." } }');
+  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");
@@ -34,7 +31,6 @@ function loadConfig() {
     return configSchema.parse({
       serviceToken: process.env.DATABRAIN_SERVICE_TOKEN || void 0,
       apiToken: process.env.DATABRAIN_API_TOKEN || void 0,
-      pat: process.env.DATABRAIN_PAT || void 0,
       apiUrl: process.env.DATABRAIN_API_URL || "https://api.usedatabrain.com",
       demoDomain: process.env.DATABRAIN_DEMO_DOMAIN || "https://demo.usedatabrain.com"
     });
@@ -188,124 +184,10 @@ var logger = {
   error: (msg, data) => log("error", msg, data)
 };
 
-// src/auth/credential-store.ts
-import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync, unlinkSync, existsSync } from "fs";
-import { homedir } from "os";
-import { dirname, join } from "path";
-function defaultStorePath() {
-  const override = process.env.DATABRAIN_CREDENTIAL_PATH;
-  if (override) return override;
-  return join(homedir(), ".databrain", "mcp", "credentials.json");
-}
-function readStore(path) {
-  if (!existsSync(path)) return {};
-  try {
-    const raw = readFileSync(path, "utf8");
-    if (!raw.trim()) return {};
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed;
-    }
-    return {};
-  } catch (err) {
-    logger.warn("Credential store unreadable, starting fresh", {
-      error: err.message
-    });
-    return {};
-  }
-}
-function writeStore(path, store) {
-  const dir = dirname(path);
-  mkdirSync(dir, { recursive: true, mode: 448 });
-  const tmp = `${path}.tmp.${process.pid}`;
-  writeFileSync(tmp, JSON.stringify(store, null, 2), { mode: 384 });
-  renameSync(tmp, path);
-  try {
-    chmodSync(path, 384);
-  } catch {
-  }
-}
-var CredentialStore = class {
-  constructor(path = defaultStorePath()) {
-    this.path = path;
-  }
-  get(baseUrl) {
-    const store = readStore(this.path);
-    const cred = store[normalizeUrl(baseUrl)];
-    return cred ?? null;
-  }
-  set(baseUrl, cred) {
-    const store = readStore(this.path);
-    store[normalizeUrl(baseUrl)] = cred;
-    writeStore(this.path, store);
-  }
-  clear(baseUrl) {
-    const store = readStore(this.path);
-    const key = normalizeUrl(baseUrl);
-    if (!(key in store)) return false;
-    delete store[key];
-    if (Object.keys(store).length === 0 && existsSync(this.path)) {
-      unlinkSync(this.path);
-    } else {
-      writeStore(this.path, store);
-    }
-    return true;
-  }
-  getPath() {
-    return this.path;
-  }
-};
-function normalizeUrl(url) {
-  return url.replace(/\/+$/, "");
-}
-
-// src/auth/operator.ts
-var OPERATOR_PAT_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
-var storeSingleton;
-function getCredentialStore() {
-  if (!storeSingleton) storeSingleton = new CredentialStore();
-  return storeSingleton;
-}
-function loadCachedOperator(baseUrl) {
-  let cred;
-  try {
-    cred = getCredentialStore().get(baseUrl);
-  } catch (err) {
-    logger.warn("Credential store unreadable, treating as empty", {
-      error: err.message
-    });
-    return null;
-  }
-  if (!cred) return null;
-  if (cred.expiresAt && cred.expiresAt < Date.now()) return null;
-  return cred;
-}
-function persistOperator(baseUrl, response) {
-  const cred = {
-    pat: response.pat,
-    email: response.email,
-    userId: response.userId,
-    role: response.role,
-    workspaces: response.workspaces,
-    expiresAt: response.expiresAt
-  };
-  try {
-    getCredentialStore().set(baseUrl, cred);
-    return { cred, persisted: true };
-  } catch (err) {
-    logger.warn(
-      "Could not write operator credential to disk \u2014 using in-memory only for this session",
-      { error: err.message }
-    );
-    return { cred, persisted: false };
-  }
-}
-function clearOperator(baseUrl) {
-  return getCredentialStore().clear(baseUrl);
-}
+// 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;
@@ -325,8 +207,6 @@ var DatabrainClient = class {
   }
   cache = new TtlCache();
   runtimeApiToken;
-  operator = null;
-  operatorLoaded = false;
   hasApiToken() {
     return !!(this.runtimeApiToken || this.config.apiToken);
   }
@@ -343,85 +223,22 @@ var DatabrainClient = class {
   getDemoDomain() {
     return this.config.demoDomain;
   }
-  getOperator() {
-    if (!this.operatorLoaded) {
-      this.operator = loadCachedOperator(this.config.apiUrl);
-      this.operatorLoaded = true;
-    }
-    return this.operator;
-  }
-  setOperator(cred) {
-    this.operator = cred;
-    this.operatorLoaded = true;
-    this.cache.invalidateByPrefix("");
-  }
-  clearOperator() {
-    this.operator = null;
-    this.operatorLoaded = true;
-    this.cache.invalidateByPrefix("");
-    return clearOperator(this.config.apiUrl);
-  }
-  async bootstrapOperator(email) {
-    if (!this.config.serviceToken) {
-      throw new DatabrainApiError(
-        401,
-        "MISSING_SERVICE_TOKEN",
-        "Cannot connect \u2014 DATABRAIN_SERVICE_TOKEN is not configured. Set it in your MCP server config first."
-      );
-    }
-    const response = await this.request({
-      method: "POST",
-      path: "/api/mcp/bootstrap",
-      body: { email },
-      auth: "service",
-      // Bootstrap uses the service token explicitly — not the operator PAT.
-      token: this.config.serviceToken
-    });
-    const result = persistOperator(this.config.apiUrl, response);
-    this.setOperator(result.cred);
-    return result;
-  }
   /**
    * 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.pat) return { source: "env-pat" };
-    const op = this.getOperator();
-    if (op?.pat) return { source: "cached-pat", operator: op };
     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 (this.config.pat) return this.config.pat;
-    const op = this.getOperator();
-    if (op?.pat) return op.pat;
     if (auth === "service") return this.config.serviceToken;
     return this.runtimeApiToken || this.config.apiToken;
   }
   async request(options) {
-    try {
-      return await this.requestInternal(options);
-    } catch (err) {
-      if (err instanceof DatabrainApiError && err.code === "PAT_EXPIRED" && !options.token && !this.config.pat && options.path !== "/api/mcp/bootstrap") {
-        const op = this.getOperator();
-        if (op?.email) {
-          logger.info("Operator PAT expired \u2014 silently re-bootstrapping");
-          try {
-            await this.bootstrapOperator(op.email);
-          } catch (bootstrapErr) {
-            logger.warn("Silent re-bootstrap failed", {
-              error: bootstrapErr.message
-            });
-            throw err;
-          }
-          return this.requestInternal(options);
-        }
-      }
-      throw err;
-    }
+    return this.requestInternal(options);
   }
   async requestInternal(options) {
     if (options.invalidateCache) {
@@ -826,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
@@ -965,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;
@@ -985,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,
@@ -1023,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."
@@ -1111,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;
@@ -1172,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;
 };
@@ -1493,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);
@@ -1544,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(
@@ -1560,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,
@@ -1601,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();
@@ -1613,6 +1494,7 @@ function createServiceBundle(client) {
     datasourcesApi,
     workspacesApi,
     queryApi,
+    scheduledReportsApi,
     widgetsApi,
     embedService: new EmbedService(embedsApi, datamartsApi),
     discoveryService,
@@ -2220,8 +2102,234 @@ function registerListWorkspaces(server, client) {
   );
 }
 
-// src/tools/embed/create-embed.ts
+// src/tools/infrastructure/create-datamart.ts
 import { z as z9 } from "zod";
+
+// 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(
+    "create_datamart",
+    "Create a production datamart from selected tables and relationships. Defaults to dry-run; apply requires explicit confirmation.",
+    {
+      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_CREATE,
+    async (params) => {
+      try {
+        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 (resolution.kind !== "resolved") return resolution.response;
+          if (!params.tableList || params.tableList.length === 0) {
+            return toolError(
+              "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 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(
+            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: "POST",
+          path: "/api/v2/data-app/datamarts",
+          body: params.body,
+          auth: "service",
+          invalidateCache: ["list_datamarts"]
+        });
+        if (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(
+          `Datasource "${selected.name}" sync triggered (ID: ${datasourceId}).
+Status: ${message}
+
+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();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/embed/create-embed.ts
+import { z as z11 } from "zod";
 var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowMetricCreation: false,
   isAllowMetricDeletion: false,
@@ -2234,18 +2342,18 @@ var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowCreateDashboardView: false,
   metricCreationMode: "DRAG_DROP"
 };
-var accessSettingsSchema = z9.object({
-  datamartName: z9.string().describe("Name of the datamart (required)"),
-  isAllowMetricCreation: z9.boolean().optional().describe("Allow end-users to create metrics"),
-  metricCreationMode: z9.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
-  isAllowMetricDeletion: z9.boolean().optional().describe("Allow metric deletion"),
-  isAllowMetricUpdate: z9.boolean().optional().describe("Allow metric editing"),
-  isAllowMetricLayoutChange: z9.boolean().optional().describe("Allow layout changes"),
-  isAllowManageMetrics: z9.boolean().optional().describe("Show manage metrics UI"),
-  isAllowUnderlyingData: z9.boolean().optional().describe("Allow viewing underlying data"),
-  isAllowAiPilot: z9.boolean().optional().describe("Enable AI pilot features"),
-  isAllowEmailReports: z9.boolean().optional().describe("Allow email report scheduling"),
-  isAllowCreateDashboardView: z9.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);
@@ -2253,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: z9.record(z9.unknown()).optional().describe(
+      body: z11.record(z11.unknown()).optional().describe(
         "Raw API body passthrough. If provided, all other fields are ignored."
       ),
-      dashboardId: z9.string().optional().describe("Dashboard identifier for embed creation"),
-      workspaceName: z9.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
-      embedType: z9.enum(["dashboard", "metric"]).optional().describe("Embed type"),
-      metricId: z9.string().optional().describe("Required for metric embed type"),
-      name: z9.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: z9.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: z9.string().optional().describe("Template dashboard ID to clone metrics from"),
-      isImportMetrics: z9.boolean().optional().describe("Import metrics from template dashboard"),
-      metricImportMode: z9.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
-      isRenameDashboard: z9.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) => {
@@ -2371,14 +2479,14 @@ Next: run \`get_embed_details\` to verify the embed configuration.`
 }
 
 // src/tools/embed/list-embeds.ts
-import { z as z10 } 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). 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: z10.string().optional().describe("Filter by data app name")
+      dataAppName: z12.string().optional().describe("Filter by data app name")
     },
     READ_ONLY,
     async (params) => {
@@ -2421,14 +2529,14 @@ function registerListEmbeds(server, client) {
 }
 
 // src/tools/embed/get-embed-details.ts
-import { z as z11 } 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: z11.string().describe("ID of the embed")
+      embedId: z13.string().describe("ID of the embed")
     },
     READ_ONLY,
     async (params) => {
@@ -2444,7 +2552,7 @@ function registerGetEmbedDetails(server, client) {
 }
 
 // src/tools/embed/update-embed.ts
-import { z as z12 } 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.";
@@ -2482,15 +2590,15 @@ function registerUpdateEmbed(server, client) {
     "update_embed",
     "Update embed access settings, permissions, theme, or name.",
     {
-      embedId: z12.string().describe("ID of the embed to update"),
-      body: z12.record(z12.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: z12.string().optional().describe("New name for the embed"),
-      accessSettings: z12.record(z12.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: z12.record(z12.unknown()).optional().describe(
+      theme: z14.record(z14.unknown()).optional().describe(
         "Theme configuration object. See databrain://theme-reference for the full schema."
       )
     },
@@ -2536,7 +2644,7 @@ function registerUpdateEmbed(server, client) {
 }
 
 // src/tools/embed/customize-theme.ts
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 var THEME_PRESETS = {
   light: {
     general: {
@@ -2670,7 +2778,7 @@ var ACCESS_PRESETS = {
     metricCreationMode: "CHAT"
   }
 };
-var fontFamilyEnum = z13.enum([
+var fontFamilyEnum = z15.enum([
   "Inter",
   "Roboto",
   "Open Sans",
@@ -2682,17 +2790,17 @@ var fontFamilyEnum = z13.enum([
   "Nunito",
   "system-ui"
 ]).describe("Font family");
-var tooltipFontSchema = z13.object({
-  fontFamily: z13.string().optional(),
-  fontSize: z13.number().optional(),
-  fontWeight: z13.number().optional(),
-  fontColor: z13.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 = z13.object({
-  fontSize: z13.number().optional(),
-  fontFamily: z13.string().optional(),
-  fontWeight: z13.number().optional(),
-  color: z13.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;
@@ -2703,23 +2811,23 @@ function mapToFrontendFontConfig(input) {
     ...input.color && { color: input.color }
   };
 }
-var axisSchema = z13.object({
-  hideAxisLines: z13.boolean().optional().describe("Hide axis lines"),
-  hideSplitLines: z13.boolean().optional().describe("Hide grid/split lines"),
-  hideAxisLabels: z13.boolean().optional().describe("Hide axis labels"),
-  hideAxisTicks: z13.boolean().optional().describe("Hide axis tick marks"),
-  axisName: z13.string().optional().describe("Axis title text"),
-  axisNameOffset: z13.number().optional().describe("Axis title offset from axis"),
-  axisLabelMargin: z13.number().optional().describe("Margin between axis labels and chart area in pixels"),
-  fontSize: z13.number().optional().describe("Axis label font size"),
-  fontFamily: z13.string().optional().describe("Axis label font family"),
-  fontWeight: z13.number().optional().describe("Axis label font weight"),
-  color: z13.string().optional().describe("Axis label color (hex)"),
-  axisColor: z13.string().optional().describe("Axis line color (hex)"),
-  axisNameFontConfig: z13.object({
-    fontFamily: z13.string().optional(),
-    fontSize: z13.number().optional(),
-    fontWeight: z13.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) {
@@ -2778,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 = {};
@@ -2875,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: z13.string().describe("ID of the embed to theme"),
-      body: z13.record(z13.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: z13.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
-      accessPreset: z13.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: z13.string().optional().describe("Date picker display format"),
+      datePickerFormat: z15.string().optional().describe("Date picker display format"),
       // --- Colors ---
-      primaryColor: z13.string().optional().describe("Primary accent color (hex)"),
-      backgroundColor: z13.string().optional().describe("Overall background color (hex)"),
-      textColor: z13.string().optional().describe("Default text color (hex)"),
-      ctaColor: z13.string().optional().describe("Call-to-action button color (hex)"),
-      ctaTextColor: z13.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: z13.string().optional().describe("Dashboard container background (hex)"),
-      selectBoxSize: z13.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
-      selectBoxVariant: z13.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
-      selectBoxBorderRadius: z13.string().optional().describe('Select box border radius (e.g. "20px")'),
-      selectBoxTextColor: z13.string().optional().describe("Select box text color (hex)"),
-      metricCardColor: z13.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: z13.string().optional().describe('Card title font size (e.g. "16px")'),
-      cardTitleFontWeight: z13.string().optional().describe('Card title font weight (e.g. "600")'),
-      cardTitleColor: z13.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: z13.string().optional().describe("Card description font size"),
-      cardDescriptionFontWeight: z13.string().optional().describe("Card description font weight"),
-      cardDescriptionColor: z13.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: z13.string().optional().describe("Card internal padding"),
-      cardBorderRadius: z13.string().optional().describe("Card border radius"),
-      cardShadow: z13.string().optional().describe("Card box-shadow CSS value"),
-      disableShadowOnHover: z13.boolean().optional().describe("Disable shadow on card hover"),
-      disableCardStroke: z13.boolean().optional().describe("Remove card border stroke"),
-      cardStrokeColor: z13.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: z13.string().optional().describe("Font family for chart text"),
-      chartFontColor: z13.string().optional().describe("Font color for chart text (hex)"),
-      chartColors: z13.array(z13.string()).optional().describe("Array of chart series colors (hex)"),
-      chartPaletteName: z13.string().optional().describe("Name for a custom palette"),
-      chartPaletteColors: z13.array(z13.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: z13.string().optional().describe("Primary button background (hex)"),
-      buttonPrimaryTextColor: z13.string().optional().describe("Primary button text (hex)"),
-      buttonSecondaryColor: z13.string().optional().describe("Secondary button background (hex)"),
-      buttonSecondaryTextColor: z13.string().optional().describe("Secondary button text (hex)"),
-      checkboxCheckedColor: z13.string().optional().describe("Checked checkbox color (hex)"),
-      checkboxUncheckedColor: z13.string().optional().describe("Unchecked checkbox color (hex)"),
-      switchEnabledColor: z13.string().optional().describe("Enabled switch color (hex)"),
-      switchDisabledColor: z13.string().optional().describe("Disabled switch color (hex)"),
-      breadcrumbFontFamily: z13.string().optional().describe("Drill breadcrumb font family"),
-      breadcrumbFontColor: z13.string().optional().describe("Drill breadcrumb font color (hex)"),
-      breadcrumbActiveColor: z13.string().optional().describe("Active breadcrumb color (hex)"),
-      filterBadgeColor: z13.string().optional().describe("Multi-select filter badge color (hex)"),
-      filterBadgeTextColor: z13.string().optional().describe("Filter badge text color (hex)"),
-      datePickerColor: z13.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: z13.number().optional().describe("XL breakpoint width in px"),
-      breakpointLg: z13.number().optional().describe("LG breakpoint width in px"),
-      breakpointMd: z13.number().optional().describe("MD breakpoint width in px"),
-      breakpointSm: z13.number().optional().describe("SM breakpoint width in px"),
-      breakpointXs: z13.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: z13.number().optional().describe("Grid columns at XL breakpoint"),
-      layoutColsLg: z13.number().optional().describe("Grid columns at LG breakpoint"),
-      layoutColsMd: z13.number().optional().describe("Grid columns at MD breakpoint"),
-      layoutColsSm: z13.number().optional().describe("Grid columns at SM breakpoint"),
-      layoutColsXs: z13.number().optional().describe("Grid columns at XS breakpoint"),
-      layoutColsXxs: z13.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: z13.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
-      radialLabelPosition: z13.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
-      marginTop: z13.number().optional().describe("Chart top margin in pixels"),
-      marginLeft: z13.number().optional().describe("Chart left margin in pixels"),
-      marginRight: z13.number().optional().describe("Chart right margin in pixels"),
-      marginBottom: z13.number().optional().describe("Chart bottom margin in pixels"),
-      legendShow: z13.boolean().optional().describe("Show or hide chart legend"),
-      legendPosition: z13.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",
@@ -2972,17 +3080,17 @@ function registerCustomizeTheme(server, client) {
         "bottom-center",
         "bottom-right"
       ]).optional().describe("Legend position"),
-      legendLayout: z13.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
-      legendShape: z13.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
-      legendFontSize: z13.number().optional().describe("Legend font size"),
-      legendFontWeight: z13.number().optional().describe("Legend font weight"),
-      legendFontFamily: z13.string().optional().describe("Legend font family"),
-      legendColor: z13.string().optional().describe("Legend text color (hex)"),
-      legendTruncateLength: z13.number().optional().describe("Max characters before truncating legend"),
-      disableLegendScrolling: z13.boolean().optional().describe("Disable scrolling in legend"),
-      enableVariableLegendPosition: z13.boolean().optional().describe("Allow user to drag legend"),
-      legendTop: z13.number().optional().describe("Custom legend top offset"),
-      legendLeft: z13.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")
     },
@@ -3057,7 +3165,7 @@ Use \`get_embed_details\` to view the full current theme configuration.` + GUEST
 }
 
 // src/tools/embed/get-demo-link.ts
-import { z as z14 } from "zod";
+import { z as z16 } from "zod";
 var HOUR_MS = 60 * 60 * 1e3;
 var DEFAULT_EXPIRY_HOURS = 24;
 var MAX_EXPIRY_HOURS = 24 * 30;
@@ -3067,13 +3175,13 @@ function registerGetDemoLink(server, client) {
     "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: z14.string().describe("End-customer identifier to scope the preview to."),
-      dashboardName: z14.string().optional().describe("Dashboard name (non-technical). Preferred \u2014 pass with optional `workspaceName`."),
-      workspaceName: z14.string().optional().describe("Workspace name. Only needed if `dashboardName` is ambiguous."),
-      embedId: z14.string().optional().describe("Technical alternative to `dashboardName`."),
-      expiryHours: z14.number().min(1).max(MAX_EXPIRY_HOURS).optional().describe(`Token TTL in hours. Defaults to ${DEFAULT_EXPIRY_HOURS}. Max ${MAX_EXPIRY_HOURS} (30 days).`)
+      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).`)
     },
-    READ_ONLY,
+    WRITE_CREATE,
     async (params) => {
       try {
         const embed = await services.widgetService.resolveEmbedId({
@@ -3127,70 +3235,70 @@ function registerGetDemoLink(server, client) {
 }
 
 // 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) => {
@@ -3243,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) {
@@ -3352,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
@@ -3485,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
@@ -3617,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
@@ -3767,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
@@ -3909,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
@@ -4041,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
@@ -4188,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
@@ -4239,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,
@@ -4294,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) => {
@@ -4339,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._";
@@ -4369,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) => {
@@ -4392,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(
@@ -4404,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
@@ -4543,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."
       )
     },
@@ -4660,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)",
@@ -4679,32 +4798,91 @@ var columnSchema = z20.object({
     "Identifier",
     "Number",
     "JSON"
-  ]).nullable().optional().describe('Semantic column type. Use "Identifier" for IDs/foreign keys, "Number" for numeric values, "String" for text. Omit for date columns.')
+  ]).nullable().optional().describe('Semantic column type. Use "Identifier" for IDs/foreign keys, "Number" for numeric values, "String" for text. Omit for date and boolean 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 columnKey(tableName, columnName) {
+  return `${tableName.toLowerCase()}\0${columnName.toLowerCase()}`;
+}
+function buildColumnDatatypeMap(semanticLayer) {
+  const datatypes = /* @__PURE__ */ new Map();
+  for (const table of semanticLayer.tables ?? []) {
+    for (const column of table.columns ?? []) {
+      if (column.datatype) {
+        datatypes.set(columnKey(table.name, column.name), column.datatype);
+      }
+    }
+  }
+  return datatypes;
+}
+function hasExplicitColumnType(tables) {
+  return tables?.some(
+    (table) => table.columns?.some(
+      (column) => column.columnType !== void 0 && column.columnType !== null
+    )
+  ) ?? false;
+}
+function shouldOmitColumnTypeForDatatype(datatype) {
+  if (!datatype) return false;
+  const normalized = datatype.trim().toLowerCase();
+  return normalized === "boolean" || normalized === "bool" || normalized === "date" || normalized.startsWith("date(") || normalized.startsWith("datetime") || normalized.startsWith("timestamp") || normalized === "time" || normalized.startsWith("time(") || normalized.startsWith("time ");
+}
+function normalizeTablesForApi(tables, datatypesByColumn) {
+  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) {
+          const datatype = datatypesByColumn?.get(
+            columnKey(table.name, column.name)
+          );
+          if (!shouldOmitColumnTypeForDatatype(datatype)) {
+            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").'
       )
     },
@@ -4727,9 +4905,13 @@ function registerUpdateSemanticLayer(server, client) {
         });
         if (resolution.kind !== "resolved") return resolution.response;
         const datamartName = resolution.name;
+        const datatypesByColumn = hasExplicitColumnType(params.tables) ? buildColumnDatatypeMap(
+          await services.queryApi.getSemanticLayer(datamartName)
+        ) : void 0;
+        const tables = normalizeTablesForApi(params.tables, datatypesByColumn);
         await services.queryApi.updateSemanticLayer({
           datamartName,
-          tables: params.tables,
+          tables,
           feedback: params.feedback
         });
         const updatedParts = [];
@@ -4761,35 +4943,273 @@ You can now:
   );
 }
 
-// src/tools/widgets/list-widgets.ts
-import { z as z21 } 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.")
-    },
-    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 widgets = await services.widgetsApi.listWidgets(
-          embedId,
-          params.clientId
-        );
-        if (!Array.isArray(widgets) || widgets.length === 0) {
+// src/tools/query/semantic-generation.ts
+import { z as z23 } from "zod";
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function datamartIdFrom(datamart) {
+  return nonEmptyString(datamart.id) || nonEmptyString(datamart._id) || nonEmptyString(datamart.datamartId) || nonEmptyString(datamart.dataMartId) || null;
+}
+function nestedDatamartFromWorkspace(workspace) {
+  const nested = workspace.datamart;
+  return nested && typeof nested === "object" && !Array.isArray(nested) ? nested : null;
+}
+function workspaceDatamartIdFrom(workspace) {
+  const nested = nestedDatamartFromWorkspace(workspace);
+  return nonEmptyString(workspace.dataMartId) || nonEmptyString(workspace.datamartId) || (nested ? datamartIdFrom(nested) : null);
+}
+function workspaceDatamartNameFrom(workspace) {
+  const nested = nestedDatamartFromWorkspace(workspace);
+  return (nested ? nonEmptyString(nested.name) || nonEmptyString(nested.datamartName) : null) || nonEmptyString(workspace.datamartName) || null;
+}
+async function resolveDatamartFromWorkspace(params) {
+  const services = createServiceBundle(params.client);
+  const workspaces = await services.workspacesApi.listWorkspaces();
+  const resolution = resolveResource({
+    items: workspaces,
+    name: params.workspaceName,
+    getName: (ws) => ws.name,
+    formatItem: formatWorkspace,
+    resourceType: "workspace",
+    toolName: params.toolName
+  });
+  if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
+  const selected = resolution.selected;
+  const datamartId = workspaceDatamartIdFrom(selected);
+  const workspaceDatamartName = workspaceDatamartNameFrom(selected);
+  if (!datamartId) {
+    return {
+      ok: false,
+      response: toolError(
+        `Workspace "${resolution.name}" does not expose a linked dataMartId/datamart.id. Pass datamartId directly or choose a workspace linked to a datamart.`
+      )
+    };
+  }
+  if (params.datamartName && workspaceDatamartName && workspaceDatamartName.toLowerCase() !== params.datamartName.toLowerCase()) {
+    return {
+      ok: false,
+      response: toolError(
+        `Workspace "${resolution.name}" is linked to datamart "${workspaceDatamartName}", not "${params.datamartName}". Use the linked datamart name or choose another workspace.`
+      )
+    };
+  }
+  return {
+    ok: true,
+    datamartName: workspaceDatamartName || params.datamartName || datamartId,
+    datamartId,
+    workspaceName: resolution.name
+  };
+}
+async function findDatamartIdInLinkedWorkspaces(params) {
+  const services = createServiceBundle(params.client);
+  const workspaces = await services.workspacesApi.listWorkspaces();
+  const matches = workspaces.map((workspace) => {
+    const record = workspace;
+    return {
+      name: nonEmptyString(record.name),
+      datamartName: workspaceDatamartNameFrom(record),
+      datamartId: workspaceDatamartIdFrom(record)
+    };
+  }).filter(
+    (workspace) => workspace.datamartName?.toLowerCase() === params.datamartName.toLowerCase() && workspace.datamartId
+  );
+  const uniqueIds = [...new Set(matches.map((workspace) => workspace.datamartId))];
+  if (uniqueIds.length === 1 && uniqueIds[0]) {
+    return {
+      kind: "resolved",
+      datamartId: uniqueIds[0],
+      workspaceName: matches.find((workspace) => workspace.datamartId === uniqueIds[0])?.name || void 0
+    };
+  }
+  if (uniqueIds.length > 1) {
+    return {
+      kind: "ambiguous",
+      workspaceNames: matches.map((workspace) => workspace.name).filter((name) => !!name)
+    };
+  }
+  return { kind: "none" };
+}
+async function resolveDatamart(params) {
+  if (params.datamartId) {
+    return {
+      ok: true,
+      datamartName: params.datamartName || params.datamartId,
+      datamartId: params.datamartId,
+      workspaceName: params.workspaceName
+    };
+  }
+  if (params.workspaceName) {
+    return resolveDatamartFromWorkspace({
+      client: params.client,
+      workspaceName: params.workspaceName,
+      datamartName: params.datamartName,
+      toolName: params.toolName
+    });
+  }
+  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) {
+    const workspaceMatch = await findDatamartIdInLinkedWorkspaces({
+      client: params.client,
+      datamartName: resolution.name
+    });
+    if (workspaceMatch.kind === "resolved") {
+      return {
+        ok: true,
+        datamartName: resolution.name,
+        datamartId: workspaceMatch.datamartId,
+        workspaceName: workspaceMatch.workspaceName
+      };
+    }
+    if (workspaceMatch.kind === "ambiguous") {
+      return {
+        ok: false,
+        response: toolError(
+          `Datamart "${resolution.name}" is linked from multiple workspaces with different IDs. Call ${params.toolName} again with workspaceName. Matching workspaces: ${workspaceMatch.workspaceNames.join(", ")}`
+        )
+      };
+    }
+    return {
+      ok: false,
+      response: toolError(
+        `Datamart "${resolution.name}" resolved by name but no id/_id/datamartId/dataMartId was returned and no linked workspace exposed its ID. Pass workspaceName for a workspace linked to this datamart, pass datamartId directly, or update the datamart list API to include 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"),
+      workspaceName: z23.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z23.string().optional().describe("Datamart UUID. Use only when already known.")
+    },
+    WRITE_CREATE,
+    async (params) => {
+      try {
+        const resolved = await resolveDatamart({
+          client,
+          datamartId: params.datamartId,
+          datamartName: params.datamartName,
+          workspaceName: params.workspaceName,
+          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,
+              workspaceName: resolved.workspaceName,
+              ...result,
+              nextStep: "Call get_semantic_layer_generation_status with the same datamartName or workspaceName 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"),
+      workspaceName: z23.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z23.string().optional().describe("Datamart UUID. Use only when already known.")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const resolved = await resolveDatamart({
+          client,
+          datamartId: params.datamartId,
+          datamartName: params.datamartName,
+          workspaceName: params.workspaceName,
+          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,
+              workspaceName: resolved.workspaceName,
+              ...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 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: 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) => {
+      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 widgets = await services.widgetsApi.listWidgets(
+          embedId,
+          params.clientId
+        );
+        if (!Array.isArray(widgets) || widgets.length === 0) {
           return toolSuccess(
             `No widgets found on dashboard "${embed.value.resolvedFrom?.dashboardName || embedId}" for client "${params.clientId}".`
           );
@@ -4818,28 +5238,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) => {
@@ -4949,20 +5369,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) => {
@@ -5017,19 +5437,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) => {
@@ -5077,21 +5497,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) => {
@@ -5156,51 +5576,280 @@ function registerGenerateWidget(server, client) {
   );
 }
 
-// src/tools/auth/connect.ts
-import { z as z26 } from "zod";
-function registerConnect(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(
-    "connect",
-    "Bind this MCP session to a Databrain user. Pass the user's Databrain login email; the server mints a personal token cached locally so subsequent actions are role-checked and audited under that user. One-time per machine.",
+    "create_or_update_metric_from_query",
+    "Create or update a production metric/widget from validated SQL. Defaults to dry-run; apply requires explicit confirmation.",
     {
-      email: z26.string().email().describe("The Databrain login email for the user running this MCP session.")
+      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 ({ email }) => {
+    async (params) => {
       try {
-        const { cred, persisted } = await client.bootstrapOperator(email);
-        const expiresInDays = Math.max(
-          0,
-          Math.round((cred.expiresAt - Date.now()) / (24 * 60 * 60 * 1e3))
+        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
         );
-        const envPatActive = client.getActiveAuth().source === "env-pat";
-        const notes = [];
-        if (envPatActive) {
-          notes.push(
-            "DATABRAIN_PAT is set in your MCP env, so that token continues to be used as the bearer for API calls. The cached identity is now available for `whoami`. Unset DATABRAIN_PAT if you want this freshly minted PAT to be used instead."
+        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.`
           );
-        } else {
-          notes.push(
-            "Mutations from this MCP session are now role-checked and audit-logged under this user."
+        }
+        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"
+            })
           );
         }
-        if (!persisted) {
-          notes.push(
-            "Could not persist the credential to disk \u2014 likely a sandboxed or read-only home directory. The PAT is held in memory for this session only; you'll be asked to connect again next time the MCP server restarts. To avoid this, generate a PAT in Databrain Settings and paste it into your MCP config as DATABRAIN_PAT."
+        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: "connected",
-              email: cred.email,
-              userId: cred.userId,
-              role: cred.role,
-              workspaces: cred.workspaces,
-              expiresInDays,
-              persisted,
-              activeBearer: envPatActive ? "env-pat" : "cached-pat",
-              notes
+              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
@@ -5208,104 +5857,119 @@ function registerConnect(server, client) {
         );
       } catch (err) {
         if (err instanceof DatabrainApiError) return err.toToolResponse();
-        return toolError(`Unexpected error during connect: ${err.message}`);
+        return toolError(`Unexpected error: ${err.message}`);
       }
     }
   );
 }
 
-// src/tools/auth/whoami.ts
-function registerWhoami(server, client) {
+// src/tools/reports/list-scheduled-reports.ts
+import { z as z31 } from "zod";
+function registerListScheduledReports(server, client) {
+  const services = createServiceBundle(client);
   server.tool(
-    "whoami",
-    "Return the credential currently used for API calls and (if known) the Databrain user it belongs to. Use to confirm operator identity before mutating actions.",
-    {},
+    "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 () => {
-      const auth = client.getActiveAuth();
-      const cached = client.getOperator();
-      if (auth.source === "env-pat") {
-        const body = {
-          status: "connected",
-          activeBearer: "env-pat",
-          note: "Using DATABRAIN_PAT from your MCP env. The backend resolves the user behind this PAT \u2014 actions are role-checked and audited under their account."
-        };
-        if (cached) {
-          body.cachedIdentity = {
-            email: cached.email,
-            userId: cached.userId,
-            role: cached.role,
-            workspaces: cached.workspaces,
-            note: "Local cache from a prior `connect` \u2014 informational only; the env PAT is the active bearer."
-          };
-        } else {
-          body.cachedIdentity = null;
-          body.hint = "Run `connect <your-databrain-email>` to populate identity metadata locally for richer whoami output. The env PAT will continue to be the active bearer regardless.";
-        }
-        return toolSuccess(JSON.stringify(body, null, 2));
-      }
-      if (auth.source === "cached-pat") {
-        const op = auth.operator;
-        const expiresInDays = Math.max(
-          0,
-          Math.round((op.expiresAt - Date.now()) / (24 * 60 * 60 * 1e3))
-        );
+    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(
             {
-              status: "connected",
-              activeBearer: "cached-pat",
-              email: op.email,
-              userId: op.userId,
-              role: op.role,
-              workspaces: op.workspaces,
-              expiresInDays
+              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}`);
       }
-      return toolSuccess(
-        JSON.stringify(
-          {
-            status: "not_connected",
-            activeBearer: auth.source,
-            note: "No operator bound to this MCP session. Calls fall back to the org-level service token (no per-user audit). Either run `connect <email>` to bootstrap interactively, or paste a Personal Access Token into your MCP config as DATABRAIN_PAT."
-          },
-          null,
-          2
-        )
-      );
     }
   );
 }
 
-// src/tools/auth/disconnect.ts
-function registerDisconnect(server, client) {
+// src/tools/auth/whoami.ts
+function registerWhoami(server, client) {
   server.tool(
-    "disconnect",
-    "Wipe the locally cached operator credential for this Databrain instance. Use when switching Databrain accounts or revoking access on a shared machine. Subsequent calls fall back to the service token until `connect` is run again.",
+    "whoami",
+    "Return the credential currently used for API calls. Use to confirm which auth mode this MCP session is operating under before mutating actions.",
     {},
-    DESTRUCTIVE,
+    READ_ONLY,
     async () => {
-      const wasConnected = client.getOperator() !== null;
-      const envPatActive = client.getActiveAuth().source === "env-pat";
-      client.clearOperator();
-      const notes = [];
-      if (wasConnected) {
-        notes.push("Local operator credential cleared. Run `connect` again to rebind.");
-      } else {
-        notes.push("No cached operator to clear.");
+      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 (envPatActive) {
-        notes.push(
-          "DATABRAIN_PAT is still set in your MCP env, so API calls continue using that token. Unset it in your MCP config to fully disconnect."
+      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: "disconnected", wasConnected, notes },
+          {
+            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
         )
@@ -5316,13 +5980,13 @@ function registerDisconnect(server, client) {
 
 // src/tools/registry.ts
 function registerAllTools(server, client) {
-  registerConnect(server, client);
   registerWhoami(server, client);
-  registerDisconnect(server, client);
   registerListDatasources(server, client);
   registerDiscoverDatasourceSchema(server, client);
   registerListDatamarts(server, client);
   registerListWorkspaces(server, client);
+  registerSyncDatasource(server, client);
+  registerCreateDatamart(server, client);
   registerListDataApps(server, client);
   registerCreateDataApp(server, client);
   registerListApiTokens(server, client);
@@ -5340,11 +6004,16 @@ function registerAllTools(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
@@ -7707,7 +8376,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
@@ -7719,12 +8388,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', {
@@ -7735,7 +8404,7 @@ const guestToken = await fetch('https://api.usedatabrain.com/api/v2/guest-token/
   },
   body: JSON.stringify({
     embedId: 'embed-789',
-    clientId: 'globex',
+    clientId: 'tenant_b',
   }),
 });
 \`\`\`
@@ -7743,20 +8412,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
 \`\`\`
@@ -8312,7 +8981,7 @@ Guidelines for generating descriptions:
 - **Table descriptions:** Explain what the table contains in 1-2 sentences. Example: \`orders\` \u2192 "Contains customer purchase orders with line items, totals, and fulfillment status."
 - **Column descriptions:** Explain the business meaning. Example: \`total_amount\` \u2192 "Total order value in the customer's local currency, including tax and shipping."
 - **Synonyms:** Add common alternative names users might say. Example: \`total_amount\` \u2192 ["revenue", "order total", "sales amount"]
-- **Column types:** Set semantic types when obvious: "Date", "Number", "Identifier", "Category", "Currency", "Email", "Name", etc.
+- **Column types:** Only use supported semantic types: "String", "Long String", "ENUM", "Mapper", "Range", "Expression", "Identifier", "Number", or "JSON". Omit \`columnType\` for date and boolean database columns.
 
 Ask the user if they want to review and refine the descriptions before applying, or if you should go ahead and apply them directly.
 
@@ -8430,6 +9099,108 @@ Present the URL to the user and remind them: (a) only \`isPublished: true\` widg
 
 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 = [
   {
@@ -8461,6 +9232,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) {
@@ -8484,34 +9260,35 @@ function createServer(config) {
   const client = new DatabrainClient(config);
   const auth = client.getActiveAuth();
   let operatorBlurb;
-  if (auth.source === "env-pat") {
-    operatorBlurb = "OPERATOR IDENTITY: a Personal Access Token is active via DATABRAIN_PAT. The backend resolves the user behind it \u2014 all calls are role-checked and audited under their account. Do NOT ask the user to connect; their identity is already bound. Use `whoami` if you need to confirm details.\n\n";
-  } else if (auth.source === "cached-pat") {
-    const op = auth.operator;
-    operatorBlurb = `OPERATOR IDENTITY: connected as ${op.email} (${op.role}) via locally cached PAT. All mutations are role-checked and audit-logged under this user. Use \`whoami\` to confirm, \`disconnect\` to switch users.
-
-`;
+  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: not connected. On the user's first request, ask once: \"What's your Databrain login email? I'll bind this MCP session to your account so actions are role-checked and audited.\" Then call `connect` with their email. If `connect` reports it could not persist the credential (sandboxed host), suggest the user generate a PAT in Databrain Settings and paste it into their MCP config as DATABRAIN_PAT for a stable bind. If they decline to connect, fall back to service-token mode (calls still work, but mutations are tagged actor=system in the audit log). Do not pester after one ask.\n\n";
+    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: 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, list_datamarts, 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. 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.
+\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.
@@ -8535,7 +9312,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}
 `);
@@ -8546,7 +9322,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);