@databrainhq/mcp-server 0.3.0-rc.1 → 0.3.0-rc.10

package/dist/{chunk-7DS7OLWP.js → chunk-ERTAKB2H.js}

@@ -1,619 +1,68 @@
 #!/usr/bin/env node
-
-// src/utils/logger.ts
-var LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
-var currentLevel = process.env.DATABRAIN_LOG_LEVEL || "warn";
-function log(level, message, data) {
-  if (LOG_LEVELS[level] < LOG_LEVELS[currentLevel]) return;
-  const line = `[databrain-mcp] [${level.toUpperCase()}] ${message}`;
-  if (data !== void 0) {
-    process.stderr.write(`${line} ${JSON.stringify(data)}
-`);
-  } else {
-    process.stderr.write(`${line}
-`);
-  }
-}
-var logger = {
-  debug: (msg, data) => log("debug", msg, data),
-  info: (msg, data) => log("info", msg, data),
-  warn: (msg, data) => log("warn", msg, data),
-  error: (msg, data) => log("error", msg, data)
-};
-
-// package.json
-var package_default = {
-  name: "@databrainhq/mcp-server",
-  version: "0.3.0-rc.1",
-  description: "MCP server for Databrain embedded analytics - connect databases, create datamarts, configure embeds, and generate frontend code",
-  type: "module",
-  bin: {
-    "mcp-server": "dist/index.js",
-    "databrain-mcp-server": "dist/index.js",
-    "databrain-mcp-chart-apps": "dist/apps/stdio.js"
-  },
-  main: "dist/index.js",
-  types: "dist/index.d.ts",
-  files: [
-    "dist",
-    "skills",
-    ".claude-plugin",
-    ".mcp.json"
-  ],
-  scripts: {
-    build: "tsup",
-    dev: "tsx src/index.ts",
-    test: "vitest run",
-    "test:watch": "vitest",
-    "test:live": "vitest run tests/integration/prompt-flows.test.ts",
-    lint: "tsc --noEmit",
-    prepublishOnly: "npm run build"
-  },
-  keywords: [
-    "mcp",
-    "databrain",
-    "embedded-analytics",
-    "ai",
-    "model-context-protocol"
-  ],
-  license: "MIT",
-  dependencies: {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "@posthog/mcp": "^0.10.7",
-    "posthog-node": "^5.21.2",
-    zod: "^3.24.0"
-  },
-  devDependencies: {
-    "@types/node": "^25.3.5",
-    tsup: "^8.4.0",
-    tsx: "^4.19.0",
-    typescript: "^5.7.0",
-    vitest: "^3.0.0"
-  },
-  publishConfig: {
-    access: "public"
-  },
-  repository: {
-    type: "git",
-    url: "git+https://github.com/databrainhq/mcp-server.git"
-  },
-  engines: {
-    node: ">=18.0.0"
-  }
-};
-
-// src/version.ts
-var MCP_SERVER_VERSION = package_default.version;
-
-// src/utils/cache.ts
-var TtlCache = class {
-  store = /* @__PURE__ */ new Map();
-  get(key) {
-    const entry = this.store.get(key);
-    if (!entry) return void 0;
-    if (Date.now() > entry.expiresAt) {
-      this.store.delete(key);
-      return void 0;
-    }
-    return entry.value;
-  }
-  set(key, value, ttlMs) {
-    this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
-  }
-  invalidateByPrefix(prefix) {
-    for (const key of this.store.keys()) {
-      if (key.startsWith(prefix)) {
-        this.store.delete(key);
-      }
-    }
-  }
-  clear() {
-    this.store.clear();
-  }
-};
-
-// src/utils/errors.ts
-var DatabrainApiError = class extends Error {
-  constructor(status, code, message, details) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.details = details;
-    this.name = "DatabrainApiError";
-  }
-  toToolResponse() {
-    const parts = [`Error: ${this.message}`];
-    const detailDump = this.formatDetails();
-    if (detailDump) parts.push(detailDump);
-    const hint = this.hint();
-    if (hint) parts.push(hint);
-    return {
-      content: [{ type: "text", text: parts.join("\n\n") }],
-      isError: true
-    };
-  }
-  /**
-   * Surface API-returned details for 4xx errors so the LLM can recover or
-   * report the real reason (validation messages, field names, etc.). Skips
-   * fields already collapsed into `message`/`code`, and skips 5xx where the
-   * payload usually isn't actionable.
-   */
-  formatDetails() {
-    if (this.status < 400 || this.status >= 500) return "";
-    if (!this.details || typeof this.details !== "object") return "";
-    const skipKeys = /* @__PURE__ */ new Set(["message", "detail", "error", "code"]);
-    const extra = {};
-    for (const [k, v] of Object.entries(this.details)) {
-      if (skipKeys.has(k)) continue;
-      if (v === null || v === void 0) continue;
-      extra[k] = v;
-    }
-    if (Object.keys(extra).length === 0) return "";
-    try {
-      return `API details: ${JSON.stringify(extra)}`;
-    } catch {
-      return "";
-    }
-  }
-  hint() {
-    if (this.status === 401 || this.status === 403) {
-      if (this.code === "OAUTH_API_ERROR") {
-        return "Hint: Check that the backend accepts the configured OAuth issuer and resource, and that the service principal has permission for this operation. Static fallback applies only to token acquisition failures.";
-      }
-      if (this.code === "INVALID_SERVICE_TOKEN" || this.code === "MISSING_SERVICE_TOKEN" || this.message.toLowerCase().includes("service token")) {
-        return "Hint: The service token (DATABRAIN_SERVICE_TOKEN) is invalid, expired, or missing. It must be set in the MCP server config (not at runtime). Check Settings > Service Tokens in the Databrain UI.";
-      }
-      return "Hint: The per-data-app API token is invalid or expired. Use `create_api_token` to generate a new one. Do not ask the user \u2014 manage tokens via MCP tools.";
-    }
-    if (this.status === 400) {
-      return "Hint: The request was invalid. Check parameter values match expected types and formats. Use the corresponding list tool to verify IDs and names.";
-    }
-    if (this.status === 404) {
-      return "Hint: The requested resource was not found. Verify the ID or name is correct using the corresponding list tool.";
-    }
-    if (this.status === 409) {
-      return "Hint: A resource with this name already exists. Use a different name or list existing resources first.";
-    }
-    if (this.status === 422) {
-      return "Hint: The request parameters are invalid. Check the required fields and their formats.";
-    }
-    if (this.status === 429) {
-      return "Hint: API rate limit reached. Wait a moment and try again.";
-    }
-    if (this.status >= 500) {
-      return "Hint: The Databrain API is experiencing issues. Try again in a few moments.";
-    }
-    return "";
-  }
-};
-function toolError(message) {
-  return {
-    content: [{ type: "text", text: message }],
-    isError: true
-  };
-}
-function stringify(value) {
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
-}
-function toolSuccess(text) {
-  return {
-    content: [{ type: "text", text }]
-  };
-}
-
-// src/utils/tool-context.ts
-import { AsyncLocalStorage } from "async_hooks";
-var toolContext = new AsyncLocalStorage();
-
-// src/client/oauth-client-credentials.ts
-import { z } from "zod";
-var oauthHttpsUrl = z.string().refine((value) => {
-  try {
-    const url = new URL(value);
-    return url.protocol === "https:" && !url.username && !url.password && !url.hash;
-  } catch {
-    return false;
-  }
-}, "OAuth URLs must use HTTPS without userinfo or fragments");
-var oauthConfigSchema = z.object({
-  issuer: oauthHttpsUrl.refine((value) => {
-    try {
-      return !new URL(value).search;
-    } catch {
-      return false;
-    }
-  }, "OAuth issuer must not contain a query"),
-  clientId: z.string().min(1),
-  clientSecret: z.string().min(1),
-  resource: oauthHttpsUrl,
-  scope: z.string().min(1).optional(),
-  authMethod: z.enum(["client_secret_basic", "client_secret_post"]).default("client_secret_basic")
-});
-var metadataSchema = z.object({
-  issuer: z.string(),
-  token_endpoint: oauthHttpsUrl,
-  token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
-  grant_types_supported: z.array(z.string()).optional()
-});
-var tokenSchema = z.object({
-  access_token: z.string().regex(/^[A-Za-z0-9\-._~+/]+=*$/),
-  token_type: z.string().refine((value) => value.toLowerCase() === "bearer"),
-  expires_in: z.number().finite().positive().optional()
-});
-var TOKEN_TIMEOUT_MS = 1e4;
-var FAILURE_COOLDOWN_MS = 3e4;
-var MAX_REFRESH_SKEW_MS = 6e4;
-function authError() {
-  return new Error("OAuth token acquisition failed. Check the configured issuer, client credentials, resource and scopes.");
-}
-var OAuthClientCredentials = class {
-  config;
-  tokenEndpoint;
-  cached;
-  pending;
-  retryAt = 0;
-  constructor(config) {
-    const parsed = oauthConfigSchema.safeParse(config);
-    if (!parsed.success) throw authError();
-    this.config = Object.freeze(parsed.data);
-  }
-  getStatus() {
-    if (this.cached && Date.now() < this.cached.renewAt) return "ready";
-    if (this.retryAt > 0) return "unavailable";
-    return "configured";
-  }
-  async getToken() {
-    if (this.cached && Date.now() < this.cached.renewAt) return this.cached.value;
-    if (this.pending) return this.pending;
-    if (Date.now() < this.retryAt) throw authError();
-    this.cached = void 0;
-    this.pending = this.acquire().catch(() => {
-      this.retryAt = Date.now() + FAILURE_COOLDOWN_MS;
-      throw authError();
-    }).finally(() => {
-      this.pending = void 0;
-    });
-    return this.pending;
-  }
-  async discoverTokenEndpoint(signal) {
-    if (this.tokenEndpoint) return this.tokenEndpoint;
-    const issuer = new URL(this.config.issuer);
-    const path = issuer.pathname.replace(/\/$/, "");
-    const candidates = [.../* @__PURE__ */ new Set([
-      `${issuer.origin}/.well-known/oauth-authorization-server${path}`,
-      `${issuer.origin}/.well-known/openid-configuration${path}`,
-      `${issuer.origin}${path}/.well-known/openid-configuration`
-    ])];
-    for (const url of candidates) {
-      const response = await fetch(url, {
-        headers: { Accept: "application/json" },
-        redirect: "error",
-        signal
-      });
-      if (response.status === 404 || response.status === 405) continue;
-      if (!response.ok) throw authError();
-      const metadata = metadataSchema.parse(await response.json());
-      if (metadata.issuer !== this.config.issuer) throw authError();
-      const methods = metadata.token_endpoint_auth_methods_supported ?? ["client_secret_basic"];
-      if (!methods.includes(this.config.authMethod)) throw authError();
-      if (metadata.grant_types_supported && !metadata.grant_types_supported.includes("client_credentials")) {
-        throw authError();
-      }
-      this.tokenEndpoint = metadata.token_endpoint;
-      return this.tokenEndpoint;
-    }
-    throw authError();
-  }
-  async acquire() {
-    const signal = AbortSignal.timeout(TOKEN_TIMEOUT_MS);
-    const endpoint = await this.discoverTokenEndpoint(signal);
-    const body = new URLSearchParams({
-      grant_type: "client_credentials",
-      resource: this.config.resource
-    });
-    if (this.config.scope) body.set("scope", this.config.scope);
-    const headers = {
-      Accept: "application/json",
-      "Content-Type": "application/x-www-form-urlencoded"
-    };
-    if (this.config.authMethod === "client_secret_post") {
-      body.set("client_id", this.config.clientId);
-      body.set("client_secret", this.config.clientSecret);
-    } else {
-      const encode = (value) => new URLSearchParams({ value }).toString().slice(6);
-      headers.Authorization = `Basic ${Buffer.from(`${encode(this.config.clientId)}:${encode(this.config.clientSecret)}`).toString("base64")}`;
-    }
-    const startedAt = Date.now();
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers,
-      body: body.toString(),
-      redirect: "error",
-      signal
-    });
-    if (!response.ok) throw authError();
-    const token = tokenSchema.parse(await response.json());
-    if (token.expires_in !== void 0) {
-      const lifetimeMs = token.expires_in * 1e3;
-      const expiresAt = startedAt + lifetimeMs;
-      if (!Number.isFinite(expiresAt) || Date.now() >= expiresAt) throw authError();
-      this.cached = {
-        value: token.access_token,
-        renewAt: expiresAt - Math.min(MAX_REFRESH_SKEW_MS, lifetimeMs * 0.1)
-      };
-    }
-    this.retryAt = 0;
-    return token.access_token;
-  }
-};
-
-// src/client/databrain-client.ts
-var MCP_USER_AGENT = `databrain-mcp-server/${MCP_SERVER_VERSION}`;
-var MAX_RETRIES = 3;
-var REQUEST_TIMEOUT_MS = 3e4;
-var NON_TRANSIENT_PATTERNS = [
-  "out of context",
-  "Definition not found",
-  "not a data question",
-  "Query generation failed",
-  "not found",
-  "not authenticated",
-  "Invalid Service Token",
-  "service token"
-];
-var DatabrainClient = class {
-  constructor(config) {
-    this.config = config;
-    if (config.oauth) {
-      if (!oauthHttpsUrl.safeParse(config.apiUrl).success) {
-        throw new Error("OAuth requires an HTTPS Databrain API URL without userinfo or fragments.");
-      }
-      this.oauth = new OAuthClientCredentials(config.oauth);
-      this.config = Object.freeze({ ...config });
-    }
-  }
-  cache = new TtlCache();
-  runtimeApiToken;
-  oauth;
-  oauthFallback = false;
-  hasApiToken() {
-    return !!(this.runtimeApiToken || this.config.apiToken);
-  }
-  setRuntimeApiToken(token) {
-    this.runtimeApiToken = token;
-    logger.info("Runtime API token set for this session");
-  }
-  getServiceToken() {
-    return this.config.serviceToken;
-  }
-  getApiUrl() {
-    return this.config.apiUrl;
-  }
-  getDemoDomain() {
-    return this.config.demoDomain;
-  }
-  /**
-   * Describes which credential is currently used as the bearer for outgoing
-   * API calls. Used by `whoami` so the LLM can give the user a truthful answer.
-   */
-  getActiveAuth() {
-    if (this.oauth) {
-      if (this.oauthFallback) return { source: "service-token", oauthFallback: true };
-      return { source: "oauth-client-credentials", status: this.oauth.getStatus() };
-    }
-    if (this.config.serviceToken) return { source: "service-token" };
-    if (this.runtimeApiToken || this.config.apiToken) return { source: "api-token" };
-    return { source: "none" };
-  }
-  async getToken(auth) {
-    if (auth === "none") return void 0;
-    if (auth === "service") {
-      if (this.oauth) {
-        try {
-          const token = await this.oauth.getToken();
-          this.oauthFallback = false;
-          return token;
-        } catch {
-          if (!this.config.serviceToken) {
-            throw new DatabrainApiError(
-              0,
-              "OAUTH_TOKEN_ERROR",
-              "OAuth token acquisition failed. Check the configured issuer, client credentials, resource and scopes."
-            );
-          }
-          if (!this.oauthFallback) logger.warn("OAuth unavailable; using the configured static service token.");
-          this.oauthFallback = true;
-        }
-      }
-      return this.config.serviceToken;
-    }
-    return this.runtimeApiToken || this.config.apiToken;
-  }
-  async request(options) {
-    return this.requestInternal(options);
-  }
-  async requestInternal(options) {
-    const usesOAuth = !!this.oauth && options.auth === "service" && !options.token;
-    const cacheAllowed = !usesOAuth;
-    if (options.invalidateCache) {
-      for (const prefix of options.invalidateCache) {
-        this.cache.invalidateByPrefix(prefix);
-      }
-    }
-    if (cacheAllowed && options.cacheKey && options.cacheTtlMs) {
-      const cached = this.cache.get(options.cacheKey);
-      if (cached !== void 0) {
-        logger.debug(`Cache hit: ${options.cacheKey}`);
-        return cached;
-      }
-    }
-    let token = options.token ?? await this.getToken(options.auth);
-    if (options.auth !== "none" && !options.token && !token) {
-      if (options.auth === "service") {
-        throw new DatabrainApiError(
-          401,
-          "MISSING_SERVICE_TOKEN",
-          "DATABRAIN_SERVICE_TOKEN is required for this operation (org-level token for discovery and data app management). It must be set in the MCP server configuration \u2014 do not ask the user for it at runtime."
-        );
-      }
-      throw new DatabrainApiError(
-        401,
-        "MISSING_API_TOKEN",
-        "A per-data-app API token is required for this embedding operation but none is configured. Call `create_api_token` to generate one, or `set_api_token` if you already have the value. Do not ask the user for this token \u2014 create it via the MCP tools."
-      );
-    }
-    let url = `${this.config.apiUrl}${options.path}`;
-    if (options.query) {
-      const params = new URLSearchParams(options.query);
-      url += `?${params.toString()}`;
-    }
-    let lastError;
-    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
-      try {
-        if (usesOAuth && attempt > 1) token = await this.getToken(options.auth);
-        const headers = {
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": MCP_USER_AGENT,
-          "X-Databrain-Client": MCP_USER_AGENT,
-          ...options.headers
-        };
-        const ctx = toolContext.getStore();
-        if (ctx) {
-          headers["X-Databrain-MCP-Tool"] = ctx.tool;
-          headers["X-Databrain-MCP-Tool-Category"] = ctx.category;
-          headers["X-Databrain-MCP-Workflow-Intent"] = ctx.workflowIntent;
-          headers["X-Databrain-MCP-Input-Mode"] = ctx.inputMode;
-        }
-        if (token) {
-          if (options.auth === "none") {
-            headers["x-plugin-token"] = token;
-            headers["Origin"] = "https://mcp.usedatabrain.com";
-          } else {
-            headers["Authorization"] = `Bearer ${token}`;
-          }
-        }
-        const response = await fetch(url, {
-          method: options.method,
-          headers,
-          body: options.body ? JSON.stringify(options.body) : void 0,
-          signal: AbortSignal.timeout(options.timeoutMs || REQUEST_TIMEOUT_MS),
-          ...usesOAuth ? { redirect: "error" } : {}
-        });
-        if (!response.ok) {
-          if (usesOAuth) {
-            throw new DatabrainApiError(
-              response.status,
-              "OAUTH_API_ERROR",
-              `Databrain API request failed with status ${response.status} using configured service credentials.`
-            );
-          }
-          const errorBody = await response.text();
-          logger.warn(`[API Error] ${options.method} ${options.path} status=${response.status} body=${errorBody.slice(0, 500)}`);
-          let parsed = {};
-          try {
-            parsed = JSON.parse(errorBody);
-          } catch {
-          }
-          const errorMsg = parsed.message || parsed.detail || (typeof parsed.error === "string" ? parsed.error : JSON.stringify(parsed.error)) || `API request failed with status ${response.status}`;
-          const error = new DatabrainApiError(
-            response.status,
-            parsed.code || `HTTP_${response.status}`,
-            errorMsg,
-            parsed
-          );
-          const isTransient = response.status === 429 || response.status >= 500 && !NON_TRANSIENT_PATTERNS.some((p) => errorMsg.includes(p));
-          if (isTransient && attempt < MAX_RETRIES) {
-            const delay = Math.min(1e3 * Math.pow(2, attempt - 1), 8e3);
-            logger.warn(`Retrying in ${delay}ms (attempt ${attempt}/${MAX_RETRIES})`, {
-              status: response.status,
-              path: options.path
-            });
-            await new Promise((r) => setTimeout(r, delay));
-            lastError = error;
-            continue;
-          }
-          throw error;
-        }
-        const text = await response.text();
-        let data = text ? JSON.parse(text) : {};
-        if (!options.skipDataUnwrap && data && typeof data === "object" && !Array.isArray(data) && "data" in data) {
-          const inner = data.data;
-          if (inner !== null && inner !== void 0) {
-            data = inner;
-          }
-        }
-        if (cacheAllowed && options.cacheKey && options.cacheTtlMs) {
-          this.cache.set(options.cacheKey, data, options.cacheTtlMs);
-        }
-        return data;
-      } catch (err) {
-        if (err instanceof DatabrainApiError) throw err;
-        if (attempt < MAX_RETRIES && err?.name === "TimeoutError" && !options.noRetryOnTimeout) {
-          const delay = Math.min(1e3 * Math.pow(2, attempt - 1), 8e3);
-          logger.warn(`Request timed out, retrying in ${delay}ms`, { path: options.path });
-          await new Promise((r) => setTimeout(r, delay));
-          lastError = err;
-          continue;
-        }
-        throw new DatabrainApiError(
-          0,
-          "NETWORK_ERROR",
-          usesOAuth ? "Failed to connect to Databrain API using configured service credentials." : `Failed to connect to Databrain API: ${err.message}`
-        );
-      }
-    }
-    throw lastError || new DatabrainApiError(0, "UNKNOWN", "Request failed after retries");
-  }
-};
+import {
+  CustomChartsApi,
+  DatabrainApiError,
+  apiProblems,
+  buildProject,
+  bundleSizeBytes,
+  contentHash,
+  createCustomChartsApi,
+  logger,
+  optionSchema,
+  planUpload,
+  readDist,
+  scaffoldProject,
+  slotSchema,
+  stringify,
+  toolContext,
+  toolError,
+  toolSuccess,
+  validateBundle
+} from "./chunk-OCBTNAAO.js";
 
 // src/apps/contract.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 var CHART_URI = "ui://databrain/chart-tile";
 var KPI_URI = "ui://databrain/kpi-tile";
 var APP_MIME = "text/html;profile=mcp-app";
+var RESOURCE_URI_META_KEY = "ui/resourceUri";
 var PAGE_SIZE = 50;
-var MAX_RESULT_CHARS = 125e3;
-var id = z2.string().trim().min(1).max(256);
-var cell = z2.union([z2.string().max(2e3), z2.number().finite(), z2.boolean(), z2.null()]);
-var rowsSchema = z2.array(z2.record(cell)).max(PAGE_SIZE);
-var referenceSchema = z2.object({ embedId: id, clientId: id, widgetId: id }).strict();
-var point = z2.object({
+var MAX_RESULT_CHARS = 124e3;
+var id = z.string().trim().min(1).max(256);
+var cell = z.union([z.string().max(2e3), z.number().finite(), z.boolean(), z.null()]);
+var rowsSchema = z.array(z.record(cell)).max(PAGE_SIZE);
+var referenceSchema = z.object({ embedId: id, clientId: id, widgetId: id }).strict();
+var point = z.object({
   key: id,
-  label: z2.string().max(2e3),
+  label: z.string().max(2e3),
   value: cell,
-  x: z2.number().min(0),
-  y: z2.number().min(0),
-  width: z2.number().positive(),
-  height: z2.number().positive(),
+  x: z.number().min(0),
+  y: z.number().min(0),
+  width: z.number().positive(),
+  height: z.number().positive(),
   drillId: id.optional()
 }).strict();
-var dateRangeSchema = z2.object({
-  from: z2.string().date(),
-  to: z2.string().date()
+var dateRangeSchema = z.object({
+  from: z.string().date(),
+  to: z.string().date()
 }).strict().refine((value) => value.from <= value.to, "Date range must be ordered");
-var viewSchema = z2.object({
-  cursor: z2.string().min(1).max(2048).optional(),
+var viewSchema = z.object({
+  cursor: z.string().min(1).max(2048).optional(),
   dateRange: dateRangeSchema.optional(),
   drillId: id.optional()
 }).strict();
-var pageSchema = z2.object({
-  kind: z2.enum(["chart", "kpi"]),
-  title: z2.string().max(500),
-  chartSpec: z2.object({ type: z2.string().max(80) }).strict(),
+var pageSchema = z.object({
+  kind: z.enum(["chart", "kpi"]),
+  title: z.string().max(500),
+  chartSpec: z.object({ type: z.string().max(80) }).strict(),
   rows: rowsSchema,
-  columns: z2.array(z2.string().max(128)).max(20),
-  svg: z2.string().max(1e5).optional(),
-  width: z2.number().int().min(240).max(1200),
-  height: z2.number().int().min(120).max(800),
-  points: z2.array(point).max(PAGE_SIZE),
+  columns: z.array(z.string().max(128)).max(20),
+  svg: z.string().max(1e5).optional(),
+  width: z.number().int().min(240).max(1200),
+  height: z.number().int().min(120).max(800),
+  points: z.array(point).max(PAGE_SIZE),
   value: cell.optional(),
-  nextCursor: z2.string().min(1).max(2048).optional()
+  nextCursor: z.string().min(1).max(2048).optional()
 }).strict().superRefine((page, ctx) => {
   if (page.kind === "chart" && !page.svg) ctx.addIssue({ code: "custom", message: "SVG required" });
   if (page.kind === "kpi" && (page.svg || page.points.length || page.value === void 0)) {
@@ -639,6 +88,9 @@ function firstRows(value) {
 }
 
 // src/apps/feature.ts
+function appMeta(visibility) {
+  return { ui: { resourceUri: CHART_URI, visibility }, [RESOURCE_URI_META_KEY]: CHART_URI };
+}
 var enabled = /* @__PURE__ */ new WeakSet();
 function enableChartApps(server) {
   enabled.add(server);
@@ -647,79 +99,122 @@ function hasChartApps(server) {
   return enabled.has(server);
 }
 function tagChartTool(server, tool) {
-  if (hasChartApps(server)) tool.update({ _meta: { ui: { resourceUri: CHART_URI, visibility: ["model", "app"] } } });
+  if (hasChartApps(server)) tool.update({ _meta: appMeta(["model", "app"]) });
 }
 function chartResult(summary, payload) {
-  return bounded({ content: [{ type: "text", text: summary }], structuredContent: payload });
+  return bounded({
+    content: [{ type: "text", text: summary }],
+    structuredContent: payload,
+    _meta: appMeta(["model", "app"])
+  });
 }
 
 // src/tools/tool-metadata.ts
 var DEFAULT_TOOL_META = {
   category: "discovery",
-  workflowIntent: "other"
+  workflowIntent: "other",
+  // Fail closed: an unregistered/unclassified tool is treated as a commit
+  // until someone deliberately marks it read or view.
+  effect: "commit"
 };
 var TOOL_METADATA = {
   // Identity / discovery
-  whoami: { category: "discovery", workflowIntent: "discovery" },
+  whoami: { category: "discovery", workflowIntent: "discovery", effect: "read" },
   // Infrastructure / data setup
-  list_datasources: { category: "infrastructure", workflowIntent: "setup_data" },
-  discover_datasource_schema: { category: "infrastructure", workflowIntent: "setup_data" },
-  list_datamarts: { category: "infrastructure", workflowIntent: "setup_data" },
-  list_workspaces: { category: "infrastructure", workflowIntent: "setup_data" },
-  sync_datasource: { category: "infrastructure", workflowIntent: "setup_data" },
-  create_datamart: { category: "infrastructure", workflowIntent: "setup_data" },
+  list_datasources: { category: "infrastructure", workflowIntent: "setup_data", effect: "read" },
+  discover_datasource_schema: { category: "infrastructure", workflowIntent: "setup_data", effect: "read" },
+  list_datamarts: { category: "infrastructure", workflowIntent: "setup_data", effect: "read" },
+  list_workspaces: { category: "infrastructure", workflowIntent: "setup_data", effect: "read" },
+  // Triggers a backend sync job that refreshes stored schema metadata — a real mutation, not a read.
+  sync_datasource: { category: "infrastructure", workflowIntent: "setup_data", effect: "commit" },
+  // dry_run is the default, but mode:"apply" performs a real POST that creates the datamart.
+  create_datamart: { category: "infrastructure", workflowIntent: "setup_data", effect: "commit" },
+  // Hosted only (an "All workspaces" sign-in); stdio does not register it.
+  create_workspace: { category: "infrastructure", workflowIntent: "setup_data", effect: "commit" },
   // Embedding — data apps & tokens
-  list_data_apps: { category: "embedding", workflowIntent: "embed_dashboard" },
-  list_tenants: { category: "embedding", workflowIntent: "embed_dashboard" },
-  create_data_app: { category: "embedding", workflowIntent: "embed_dashboard" },
-  list_api_tokens: { category: "embedding", workflowIntent: "embed_dashboard" },
-  create_api_token: { category: "embedding", workflowIntent: "embed_dashboard" },
-  rotate_api_token: { category: "embedding", workflowIntent: "embed_dashboard" },
+  list_data_apps: { category: "embedding", workflowIntent: "embed_dashboard", effect: "read" },
+  list_tenants: { category: "embedding", workflowIntent: "embed_dashboard", effect: "read" },
+  create_data_app: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
+  list_api_tokens: { category: "embedding", workflowIntent: "embed_dashboard", effect: "read" },
+  create_api_token: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
+  rotate_api_token: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
   // Embedding — embed management
-  create_embed: { category: "embedding", workflowIntent: "embed_dashboard" },
-  list_embeds: { category: "embedding", workflowIntent: "embed_dashboard" },
-  get_embed_details: { category: "embedding", workflowIntent: "embed_dashboard" },
-  update_embed: { category: "embedding", workflowIntent: "embed_dashboard" },
-  customize_embed_theme: { category: "embedding", workflowIntent: "embed_dashboard" },
-  get_demo_link: { category: "embedding", workflowIntent: "embed_dashboard" },
+  create_embed: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
+  list_embeds: { category: "embedding", workflowIntent: "embed_dashboard", effect: "read" },
+  get_embed_details: { category: "embedding", workflowIntent: "embed_dashboard", effect: "read" },
+  update_embed: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
+  // Persists theme/access config on the embed record — a real write, not a display-only tweak.
+  customize_embed_theme: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
+  // Mints and returns a live guest token embedded in the demo URL.
+  get_demo_link: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
   // Embedding — frontend
-  generate_guest_token: { category: "embedding", workflowIntent: "embed_dashboard" },
-  generate_embed_code: { category: "embedding", workflowIntent: "embed_dashboard" },
+  generate_guest_token: { category: "embedding", workflowIntent: "embed_dashboard", effect: "commit" },
+  generate_embed_code: { category: "embedding", workflowIntent: "embed_dashboard", effect: "read" },
   // Embedding — customer dashboards & widgets
-  list_dashboards: { category: "embedding", workflowIntent: "embedded_widget" },
-  create_dashboard: { category: "embedding", workflowIntent: "author_dashboard" },
-  get_dashboard: { category: "embedding", workflowIntent: "author_dashboard" },
-  generate_dashboard_tiles: { category: "embedding", workflowIntent: "author_dashboard" },
-  list_widgets: { category: "embedding", workflowIntent: "embedded_widget" },
-  add_widget: { category: "embedding", workflowIntent: "embedded_widget" },
-  update_widget: { category: "embedding", workflowIntent: "embedded_widget" },
-  remove_widget: { category: "embedding", workflowIntent: "embedded_widget" },
-  generate_widget: { category: "embedding", workflowIntent: "embedded_widget" },
-  validate_metric_spec: { category: "embedding", workflowIntent: "sql_to_embedded_metric" },
+  list_dashboards: { category: "embedding", workflowIntent: "embedded_widget", effect: "read" },
+  create_dashboard: { category: "embedding", workflowIntent: "author_dashboard", effect: "commit" },
+  get_dashboard: { category: "embedding", workflowIntent: "author_dashboard", effect: "read" },
+  // Persists nothing the user sees, but the backend mints (and then deletes) an internal guest token to render it.
+  dashboard_snapshot: { category: "internal_analytics", workflowIntent: "query_data", effect: "commit" },
+  // Does not persist a dashboard, but mints an internal guest token to render tile previews.
+  generate_dashboard_tiles: { category: "embedding", workflowIntent: "author_dashboard", effect: "commit" },
+  list_widgets: { category: "embedding", workflowIntent: "embedded_widget", effect: "read" },
+  add_widget: { category: "embedding", workflowIntent: "embedded_widget", effect: "commit" },
+  update_widget: { category: "embedding", workflowIntent: "embedded_widget", effect: "commit" },
+  remove_widget: { category: "embedding", workflowIntent: "embedded_widget", effect: "commit" },
+  // Returns an unsaved draft, but mints an internal write-capable guest token to generate it.
+  generate_widget: { category: "embedding", workflowIntent: "embedded_widget", effect: "commit" },
+  // Dry-run validation only, but mints an internal write-capable guest token to check conflicts.
+  validate_metric_spec: { category: "embedding", workflowIntent: "sql_to_embedded_metric", effect: "commit" },
   create_or_update_metric_from_query: {
     category: "embedding",
-    workflowIntent: "sql_to_embedded_metric"
+    workflowIntent: "sql_to_embedded_metric",
+    effect: "commit"
   },
   // Internal analytics
   create_workspace_metric: {
     category: "internal_analytics",
-    workflowIntent: "sql_to_workspace_metric"
+    workflowIntent: "sql_to_workspace_metric",
+    effect: "commit"
   },
-  ask_question: { category: "internal_analytics", workflowIntent: "query_data" },
+  // Runs a query and returns rows; no dashboard/widget/row is persisted.
+  ask_question: { category: "internal_analytics", workflowIntent: "query_data", effect: "read" },
+  preview_chart: { category: "internal_analytics", workflowIntent: "query_data", effect: "view" },
+  save_chart_as_dashboard: { category: "internal_analytics", workflowIntent: "author_dashboard", effect: "commit" },
+  // Read-only to the user, but each interaction mints an embed-scoped guest credential.
+  render_chart: { category: "embedding", workflowIntent: "chart_app", effect: "commit" },
+  refresh_widget: { category: "embedding", workflowIntent: "chart_app", effect: "commit" },
+  drill_down: { category: "embedding", workflowIntent: "chart_app", effect: "commit" },
+  change_date_range: { category: "embedding", workflowIntent: "chart_app", effect: "commit" },
   // Semantic layer
-  get_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data" },
-  update_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data" },
-  start_semantic_layer_generation: { category: "semantic_layer", workflowIntent: "query_data" },
+  search_semantic_model: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  get_semantic_entity: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  propose_semantic_change: { category: "semantic_layer", workflowIntent: "model_data", effect: "read" },
+  apply_semantic_change: { category: "semantic_layer", workflowIntent: "model_data", effect: "commit" },
+  eval_semantic_model: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  get_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data", effect: "read" },
+  update_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data", effect: "commit" },
+  start_semantic_layer_generation: { category: "semantic_layer", workflowIntent: "query_data", effect: "commit" },
   get_semantic_layer_generation_status: {
     category: "semantic_layer",
-    workflowIntent: "query_data"
+    workflowIntent: "query_data",
+    effect: "read"
   },
   // Reports
-  list_scheduled_reports: { category: "reports", workflowIntent: "reports" }
+  list_scheduled_reports: { category: "reports", workflowIntent: "reports", effect: "read" },
+  // Custom chart types (DAT-925)
+  // Returns template files; nothing is written or persisted.
+  custom_chart_scaffold: { category: "custom_charts", workflowIntent: "custom_chart", effect: "read" },
+  // Local rules plus POST /validate, which never persists.
+  custom_chart_validate: { category: "custom_charts", workflowIntent: "custom_chart", effect: "read" },
+  // dry_run is the default, but mode:"apply" creates a chart or a version (and may publish).
+  custom_chart_upload: { category: "custom_charts", workflowIntent: "custom_chart", effect: "commit" },
+  list_custom_charts: { category: "custom_charts", workflowIntent: "custom_chart", effect: "read" },
+  publish_custom_chart: { category: "custom_charts", workflowIntent: "custom_chart", effect: "commit" }
 };
 
 // src/tools/data-app/list-data-apps.ts
-import { z as z3 } from "zod";
+import { z as z2 } from "zod";
 
 // src/api/dashboards-api.ts
 var DashboardsApi = class {
@@ -1011,18 +506,18 @@ var QueryApi = class {
       throw err;
     }
   }
-  async startSemanticLayerGeneration(datamartId) {
+  async startSemanticLayerGeneration(datamartId2) {
     return this.client.request({
       method: "POST",
-      path: `/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/auto-generate`,
+      path: `/api/v2/data-app/datamarts/${encodeURIComponent(datamartId2)}/semantic-layer/generate`,
       auth: "service",
       invalidateCache: ["semantic_layer_"]
     });
   }
-  async getSemanticLayerGenerationStatus(datamartId) {
+  async getSemanticLayerGenerationStatus(datamartId2) {
     return this.client.request({
       method: "GET",
-      path: `/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/generation-status`,
+      path: `/api/v2/data-app/datamarts/${encodeURIComponent(datamartId2)}/semantic-layer/generation-status`,
       auth: "service"
     });
   }
@@ -1045,9 +540,9 @@ function normalizeRecords(value) {
     record.items,
     record.data
   ];
-  for (const candidate of candidates) {
-    if (Array.isArray(candidate)) {
-      return candidate.filter((item) => asRecord(item) !== null);
+  for (const candidate2 of candidates) {
+    if (Array.isArray(candidate2)) {
+      return candidate2.filter((item) => asRecord(item) !== null);
     }
   }
   return [];
@@ -1076,6 +571,62 @@ var ScheduledReportsApi = class {
   }
 };
 
+// src/api/semantic-model-api.ts
+var SemanticModelApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  path(id2, verb) {
+    return `/api/v2/semantic/${encodeURIComponent(id2)}/${verb}`;
+  }
+  pull(id2) {
+    return this.client.request({ method: "GET", path: this.path(id2, "pull"), auth: "service" });
+  }
+  retrieve(id2, q, k) {
+    return this.client.request({
+      method: "GET",
+      path: this.path(id2, "retrieve"),
+      auth: "service",
+      query: { q, k: String(k) }
+    });
+  }
+  validate(id2, source2) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "validate"),
+      auth: "service",
+      body: { source: source2 }
+    });
+  }
+  plan(id2, source2, expected_content_hash) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "plan"),
+      auth: "service",
+      body: { source: source2, expected_content_hash }
+    });
+  }
+  apply(id2, source2, expected_content_hash) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "apply"),
+      auth: "service",
+      body: { source: source2, expected_content_hash },
+      noRetryOnTimeout: true
+    });
+  }
+  evaluate(id2, body) {
+    return this.client.request({
+      method: "POST",
+      path: this.path(id2, "eval"),
+      auth: "service",
+      body,
+      timeoutMs: 3e5,
+      noRetryOnTimeout: true
+    });
+  }
+};
+
 // src/api/tenants-api.ts
 var TenantsApi = class {
   constructor(client) {
@@ -1258,8 +809,8 @@ function extractAccessSettings(embed) {
     asRecord2(metadataConfig?.accessSettings),
     asRecord2(options?.accessSettings)
   ].filter((c) => !!c);
-  for (const candidate of candidates) {
-    if (Object.keys(candidate).length > 0) return candidate;
+  for (const candidate2 of candidates) {
+    if (Object.keys(candidate2).length > 0) return candidate2;
   }
   return null;
 }
@@ -1672,6 +1223,54 @@ var WidgetService = class {
       }
     };
   }
+  /**
+   * Read-only sibling of `ensureTenantDashboardScope`.
+   *
+   * The tenant gate above exists to stop a WRITE landing on the data-app
+   * dashboard when the caller meant a tenant's copy, so it insists the
+   * tenant-scoped embed lookup returns the target. A data-app embed has no
+   * tenant row, `listEmbeds(dataAppName, clientId)` answers with an empty list,
+   * and the render path was denied before it ever reached the backend. That is
+   * the wrong trade for a read: the chart route re-derives everything from the
+   * guest token it is handed (embed inside the token's data app, `allowedEmbeds`,
+   * the tenancy subset for the client, and per-metric client visibility), so the
+   * only thing this check can usefully add is refusing another tenant's embed.
+   */
+  async ensureReadableDashboardScope(params) {
+    const clientId = params.clientId.trim();
+    if (!clientId) {
+      return {
+        ok: false,
+        error: "`clientId` cannot be empty. Pick a tenant/client first."
+      };
+    }
+    let ctx;
+    try {
+      ctx = await this.resolveEmbedContext(params.embedId);
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+    if (ctx.embedClientId && ctx.embedClientId !== clientId) {
+      return {
+        ok: false,
+        error: `Embed "${params.embedId}" belongs to another client. Pass the \`clientId\` the embed was created for.`
+      };
+    }
+    if (!ctx.embedClientId && ctx.externalDashboardCreatedBy && ctx.externalDashboardCreatedBy !== clientId) {
+      return {
+        ok: false,
+        error: `Dashboard behind embed "${params.embedId}" belongs to another client. Pass the \`clientId\` the dashboard was created for.`
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        embedId: params.embedId,
+        clientId,
+        dataAppName: ctx.dataAppName || params.dataAppName || null
+      }
+    };
+  }
   /**
    * Resolve a datasource for a widget. Priority:
    *   1. Explicit integrationId + integrationName (fast path).
@@ -1857,6 +1456,7 @@ Do not guess between the two \u2014 wait for the user to choose.`
       dataAppName,
       externalDashboardId,
       dashboardId,
+      embedClientId: isNonEmptyString3(exact.clientId) && exact.clientId || (metadata && isNonEmptyString3(metadata.clientId) ? metadata.clientId : null),
       externalDashboardCreatedBy: (externalDashboard && isNonEmptyString3(externalDashboard.createdBy) ? externalDashboard.createdBy : null) || (isNonEmptyString3(exact.createdBy) ? exact.createdBy : null) || (metadata && isNonEmptyString3(metadata.createdBy) ? metadata.createdBy : null) || (isNonEmptyString3(exact.clientId) ? exact.clientId : null)
     };
   }
@@ -1942,6 +1542,8 @@ function createServiceBundle(client) {
   const guestTokenApi = new GuestTokenApi(client);
   const queryApi = new QueryApi(client);
   const scheduledReportsApi = new ScheduledReportsApi(client);
+  const semanticModelApi = new SemanticModelApi(client);
+  const customChartsApi = new CustomChartsApi(client);
   const tenantsApi = new TenantsApi(client);
   const widgetsApi = new WidgetsApi(client);
   const workspacesApi = new WorkspacesApi(client);
@@ -1956,6 +1558,8 @@ function createServiceBundle(client) {
     workspacesApi,
     queryApi,
     scheduledReportsApi,
+    semanticModelApi,
+    customChartsApi,
     tenantsApi,
     widgetsApi,
     embedService: new EmbedService(embedsApi, datamartsApi),
@@ -2006,7 +1610,7 @@ function registerListDataApps(server, client) {
     "list_data_apps",
     "List data apps in your organization. Start here for embed setup.",
     {
-      workspaceName: z3.string().optional().describe("Filter by workspace name")
+      workspaceName: z2.string().optional().describe("Filter by workspace name")
     },
     READ_ONLY,
     async (params) => {
@@ -2035,7 +1639,7 @@ function registerListDataApps(server, client) {
 }
 
 // src/tools/data-app/list-tenants.ts
-import { z as z4 } from "zod";
+import { z as z3 } from "zod";
 var isNonEmptyString4 = (value) => typeof value === "string" && value.trim().length > 0;
 function workspaceIdFrom(workspace) {
   return isNonEmptyString4(workspace.id) && workspace.id || isNonEmptyString4(workspace._id) && workspace._id || isNonEmptyString4(workspace.workspaceId) && workspace.workspaceId || null;
@@ -2073,12 +1677,12 @@ function registerListTenants(server, client) {
     "list_tenants",
     "List available tenants/clients from the workspace tenancy database. Use this to pick a valid clientId before creating guest tokens or editing customer dashboards.",
     {
-      workspaceName: z4.string().optional().describe("Workspace name. Preferred for non-technical callers; the tool resolves it to a workspaceId."),
-      workspaceId: z4.string().optional().describe("Technical workspace UUID. Provide this instead of workspaceName if already known."),
-      searchValue: z4.string().optional().describe("Optional case-insensitive search string for tenant/client labels."),
-      limit: z4.number().int().positive().max(500).optional().describe("Maximum number of tenants to return. Backend may apply connector-specific limits."),
-      datasourceId: z4.string().optional().describe("Optional datasource UUID override when the workspace has multiple datasource contexts."),
-      datamartId: z4.string().optional().describe("Optional datamart UUID override when tenant lookup should use a specific datamart.")
+      workspaceName: z3.string().optional().describe("Workspace name. Preferred for non-technical callers; the tool resolves it to a workspaceId."),
+      workspaceId: z3.string().optional().describe("Technical workspace UUID. Provide this instead of workspaceName if already known."),
+      searchValue: z3.string().optional().describe("Optional case-insensitive search string for tenant/client labels."),
+      limit: z3.number().int().positive().max(500).optional().describe("Maximum number of tenants to return. Backend may apply connector-specific limits."),
+      datasourceId: z3.string().optional().describe("Optional datasource UUID override when the workspace has multiple datasource contexts."),
+      datamartId: z3.string().optional().describe("Optional datamart UUID override when tenant lookup should use a specific datamart.")
     },
     READ_ONLY,
     async (params) => {
@@ -2172,15 +1776,15 @@ function registerListTenants(server, client) {
 }
 
 // src/tools/data-app/create-data-app.ts
-import { z as z5 } from "zod";
+import { z as z4 } from "zod";
 function registerCreateDataApp(server, client) {
   server.tool(
     "create_data_app",
     "Create a new data app.",
     {
-      name: z5.string().describe("Data app name"),
-      workspaceName: z5.string().optional().describe("Optional workspace name if required by backend"),
-      body: z5.record(z5.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/")
+      name: z4.string().describe("Data app name"),
+      workspaceName: z4.string().optional().describe("Optional workspace name if required by backend"),
+      body: z4.record(z4.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/")
     },
     WRITE_CREATE,
     async (params) => {
@@ -2214,7 +1818,7 @@ function registerCreateDataApp(server, client) {
 }
 
 // src/tools/data-app/list-api-tokens.ts
-import { z as z6 } from "zod";
+import { z as z5 } from "zod";
 
 // src/utils/resolve-resource.ts
 function resolveResource(options) {
@@ -2283,7 +1887,7 @@ function registerListApiTokens(server, client) {
     "list_api_tokens",
     "List API tokens for a data app. Omit dataAppName to auto-resolve.",
     {
-      dataAppName: z6.string().optional().describe("Data app name. Omit to list available data apps.")
+      dataAppName: z5.string().optional().describe("Data app name. Omit to list available data apps.")
     },
     READ_ONLY,
     async (params) => {
@@ -2328,16 +1932,16 @@ function registerListApiTokens(server, client) {
 }
 
 // src/tools/data-app/create-api-token.ts
-import { z as z7 } from "zod";
+import { z as z6 } from "zod";
 function registerCreateApiToken(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "create_api_token",
     "Create an API token for a data app and activate it for this session. Omit dataAppName to auto-resolve.",
     {
-      dataAppName: z7.string().optional().describe("Data app name. Omit to list available data apps."),
-      name: z7.string().optional().describe("Optional token name"),
-      body: z7.record(z7.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/api-tokens")
+      dataAppName: z6.string().optional().describe("Data app name. Omit to list available data apps."),
+      name: z6.string().optional().describe("Optional token name"),
+      body: z6.record(z6.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/api-tokens")
     },
     WRITE_CREATE,
     async (params) => {
@@ -2373,8 +1977,9 @@ function registerCreateApiToken(server, client) {
           );
         }
         client.setRuntimeApiToken(key);
+        const used = client.hasApiToken() ? "API token created and set for this MCP session." : "API token created. This session keeps acting as the signed-in user; the token is for your backend.";
         return toolSuccess(
-          `API token created and set for this MCP session.
+          `${used}
 
 **Token:** \`${key}\`
 
@@ -2389,16 +1994,16 @@ Save this in backend secrets immediately. This value may not be returned again.`
 }
 
 // src/tools/data-app/rotate-api-token.ts
-import { z as z8 } from "zod";
+import { z as z7 } from "zod";
 function registerRotateApiToken(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "rotate_api_token",
     "Rotate (invalidate and replace) an API token. Previous token becomes stale.",
     {
-      dataAppName: z8.string().optional().describe("Data app name. Omit to list available data apps."),
-      tokenId: z8.string().optional().describe("Optional token ID to rotate"),
-      body: z8.record(z8.unknown()).optional().describe("Raw API body passthrough for rotate endpoint")
+      dataAppName: z7.string().optional().describe("Data app name. Omit to list available data apps."),
+      tokenId: z7.string().optional().describe("Optional token ID to rotate"),
+      body: z7.record(z7.unknown()).optional().describe("Raw API body passthrough for rotate endpoint")
     },
     DESTRUCTIVE,
     async (params) => {
@@ -2517,14 +2122,14 @@ function registerListDatasources(server, client) {
 }
 
 // src/tools/infrastructure/discover-datasource-schema.ts
-import { z as z9 } from "zod";
+import { z as z8 } from "zod";
 function registerDiscoverDatasourceSchema(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "discover_datasource_schema",
     "Inspect tables and columns in a datasource. Omit datasourceName to list available datasources.",
     {
-      datasourceName: z9.string().optional().describe(
+      datasourceName: z8.string().optional().describe(
         "Name of the datasource to inspect. Omit to list available datasources."
       )
     },
@@ -2607,13 +2212,13 @@ Fix the connection or add a new database in the **Databrain UI**.`
 }
 
 // src/tools/infrastructure/list-datamarts.ts
-import { z as z10 } from "zod";
+import { z as z9 } from "zod";
 function registerListDatamarts(server, client) {
   server.tool(
     "list_datamarts",
     "List datamarts with table counts and semantic layer scores.",
     {
-      dataAppName: z10.string().optional().describe("Filter by data app name")
+      dataAppName: z9.string().optional().describe("Filter by data app name")
     },
     READ_ONLY,
     async (params) => {
@@ -2702,7 +2307,7 @@ function registerListWorkspaces(server, client) {
 }
 
 // src/tools/infrastructure/create-datamart.ts
-import { z as z11 } from "zod";
+import { z as z10 } from "zod";
 
 // src/tools/widgets/production-guards.ts
 var APPLY_TO_PRODUCTION_CONFIRMATION = "APPLY_TO_PRODUCTION";
@@ -2720,29 +2325,29 @@ function genericProductionSafetyNote() {
 }
 
 // src/tools/infrastructure/create-datamart.ts
-var columnSchema = z11.object({
-  name: z11.string(),
-  alias: z11.string().optional(),
-  label: z11.string().optional(),
-  isHide: z11.boolean().optional(),
-  isCustomColumn: z11.boolean().optional(),
-  sql: z11.string().optional()
+var columnSchema = z10.object({
+  name: z10.string(),
+  alias: z10.string().optional(),
+  label: z10.string().optional(),
+  isHide: z10.boolean().optional(),
+  isCustomColumn: z10.boolean().optional(),
+  sql: z10.string().optional()
 });
-var tableSchema = z11.object({
-  name: z11.string(),
-  schemaName: z11.string().optional(),
-  clientColumn: z11.string().optional(),
-  label: z11.string().optional(),
-  columns: z11.array(columnSchema)
+var tableSchema = z10.object({
+  name: z10.string(),
+  schemaName: z10.string().optional(),
+  clientColumn: z10.string().optional(),
+  label: z10.string().optional(),
+  columns: z10.array(columnSchema)
 });
-var relationshipSchema = z11.object({
-  parentTableName: z11.string(),
-  parentColumnName: z11.string(),
-  childTableName: z11.string(),
-  childColumnName: z11.string(),
-  cardinality: z11.enum(["OneToOne", "OneToMany", "ManyToOne", "ManyToMany"]),
-  join: z11.enum(["INNER JOIN", "LEFT JOIN", "RIGHT JOIN", "FULL JOIN"]),
-  relationshipName: z11.string()
+var relationshipSchema = z10.object({
+  parentTableName: z10.string(),
+  parentColumnName: z10.string(),
+  childTableName: z10.string(),
+  childColumnName: z10.string(),
+  cardinality: z10.enum(["OneToOne", "OneToMany", "ManyToOne", "ManyToMany"]),
+  join: z10.enum(["INNER JOIN", "LEFT JOIN", "RIGHT JOIN", "FULL JOIN"]),
+  relationshipName: z10.string()
 });
 function datamartSuccessMessage(name, result) {
   return `Datamart "${name}" created successfully (ID: ${result.id || result._id || "UNKNOWN"}).
@@ -2763,21 +2368,21 @@ function registerCreateDatamart(server, client) {
     "create_datamart",
     "Create a production datamart from selected tables and relationships. Defaults to dry-run; apply requires explicit confirmation.",
     {
-      mode: z11.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run returns the plan only; apply creates the datamart"),
-      confirm: z11.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
-      name: z11.string().describe("Unique datamart name"),
-      datasourceName: z11.string().optional().describe("Name of the datasource to use. Omit to list available datasources."),
-      tableList: z11.array(tableSchema).optional().describe("Array of tables with their columns"),
-      relationships: z11.array(relationshipSchema).optional().describe("Join definitions between tables"),
-      tenancySettings: z11.object({
-        tenancyLevel: z11.enum(["TABLE", "DATABASE"]).optional(),
-        clientColumnType: z11.string().optional(),
-        schemaName: z11.string().optional(),
-        tableName: z11.string().optional(),
-        tableClientNameColumn: z11.string().optional(),
-        tablePrimaryKeyColumn: z11.string().optional()
+      mode: z10.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run returns the plan only; apply creates the datamart"),
+      confirm: z10.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      name: z10.string().describe("Unique datamart name"),
+      datasourceName: z10.string().optional().describe("Name of the datasource to use. Omit to list available datasources."),
+      tableList: z10.array(tableSchema).optional().describe("Array of tables with their columns"),
+      relationships: z10.array(relationshipSchema).optional().describe("Join definitions between tables"),
+      tenancySettings: z10.object({
+        tenancyLevel: z10.enum(["TABLE", "DATABASE"]).optional(),
+        clientColumnType: z10.string().optional(),
+        schemaName: z10.string().optional(),
+        tableName: z10.string().optional(),
+        tableClientNameColumn: z10.string().optional(),
+        tablePrimaryKeyColumn: z10.string().optional()
       }).optional().describe("Multi-tenant configuration"),
-      body: z11.record(z11.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/datamarts")
+      body: z10.record(z10.unknown()).optional().describe("Raw API body passthrough for POST /api/v2/data-app/datamarts")
     },
     WRITE_CREATE,
     async (params) => {
@@ -2872,14 +2477,14 @@ function registerCreateDatamart(server, client) {
 }
 
 // src/tools/infrastructure/sync-datasource.ts
-import { z as z12 } from "zod";
+import { z as z11 } 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: z12.string().optional().describe("Name of the datasource to sync. Omit to list available datasources.")
+      datasourceName: z11.string().optional().describe("Name of the datasource to sync. Omit to list available datasources.")
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -2928,7 +2533,7 @@ The schema metadata will be refreshed. You can now use \`discover_datasource_sch
 }
 
 // src/tools/embed/create-embed.ts
-import { z as z13 } from "zod";
+import { z as z12 } from "zod";
 var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowMetricCreation: false,
   isAllowMetricDeletion: false,
@@ -2941,18 +2546,18 @@ var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowCreateDashboardView: false,
   metricCreationMode: "DRAG_DROP"
 };
-var accessSettingsSchema = z13.object({
-  datamartName: z13.string().describe("Name of the datamart (required)"),
-  isAllowMetricCreation: z13.boolean().optional().describe("Allow end-users to create metrics"),
-  metricCreationMode: z13.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
-  isAllowMetricDeletion: z13.boolean().optional().describe("Allow metric deletion"),
-  isAllowMetricUpdate: z13.boolean().optional().describe("Allow metric editing"),
-  isAllowMetricLayoutChange: z13.boolean().optional().describe("Allow layout changes"),
-  isAllowManageMetrics: z13.boolean().optional().describe("Show manage metrics UI"),
-  isAllowUnderlyingData: z13.boolean().optional().describe("Allow viewing underlying data"),
-  isAllowAiPilot: z13.boolean().optional().describe("Enable AI pilot features"),
-  isAllowEmailReports: z13.boolean().optional().describe("Allow email report scheduling"),
-  isAllowCreateDashboardView: z13.boolean().optional().describe("Allow creating dashboard views")
+var accessSettingsSchema = z12.object({
+  datamartName: z12.string().describe("Name of the datamart (required)"),
+  isAllowMetricCreation: z12.boolean().optional().describe("Allow end-users to create metrics"),
+  metricCreationMode: z12.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
+  isAllowMetricDeletion: z12.boolean().optional().describe("Allow metric deletion"),
+  isAllowMetricUpdate: z12.boolean().optional().describe("Allow metric editing"),
+  isAllowMetricLayoutChange: z12.boolean().optional().describe("Allow layout changes"),
+  isAllowManageMetrics: z12.boolean().optional().describe("Show manage metrics UI"),
+  isAllowUnderlyingData: z12.boolean().optional().describe("Allow viewing underlying data"),
+  isAllowAiPilot: z12.boolean().optional().describe("Enable AI pilot features"),
+  isAllowEmailReports: z12.boolean().optional().describe("Allow email report scheduling"),
+  isAllowCreateDashboardView: z12.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);
@@ -2960,23 +2565,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: z13.record(z13.unknown()).optional().describe(
+      body: z12.record(z12.unknown()).optional().describe(
         "Raw API body passthrough. If provided, all other fields are ignored."
       ),
-      dashboardId: z13.string().optional().describe("Dashboard identifier for embed creation"),
-      workspaceName: z13.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
-      embedType: z13.enum(["dashboard", "metric"]).optional().describe("Embed type"),
-      metricId: z13.string().optional().describe("Required for metric embed type"),
-      name: z13.string().optional().describe("Human-readable embed config name"),
+      dashboardId: z12.string().optional().describe("Dashboard identifier for embed creation"),
+      workspaceName: z12.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
+      embedType: z12.enum(["dashboard", "metric"]).optional().describe("Embed type"),
+      metricId: z12.string().optional().describe("Required for metric embed type"),
+      name: z12.string().optional().describe("Human-readable embed config name"),
       accessSettings: accessSettingsSchema.optional(),
       // Multi-tenant (dashboard embed) params
-      clientId: z13.string().optional().describe(
+      clientId: z12.string().optional().describe(
         "Client identifier for multi-tenant isolation. When provided, creates a dashboard embed (each client gets their own dashboard copy)."
       ),
-      templateDashboardId: z13.string().optional().describe("Template dashboard ID to clone metrics from"),
-      isImportMetrics: z13.boolean().optional().describe("Import metrics from template dashboard"),
-      metricImportMode: z13.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
-      isRenameDashboard: z13.boolean().optional().describe("Rename the dashboard for this client")
+      templateDashboardId: z12.string().optional().describe("Template dashboard ID to clone metrics from"),
+      isImportMetrics: z12.boolean().optional().describe("Import metrics from template dashboard"),
+      metricImportMode: z12.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
+      isRenameDashboard: z12.boolean().optional().describe("Rename the dashboard for this client")
     },
     WRITE_CREATE,
     async (params) => {
@@ -3078,14 +2683,14 @@ Next: run \`get_embed_details\` to verify the embed configuration.`
 }
 
 // src/tools/embed/list-embeds.ts
-import { z as z14 } from "zod";
+import { z as z13 } 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). Use `list_tenants` for authoritative client discovery from the tenancy database.",
     {
-      dataAppName: z14.string().optional().describe("Filter by data app name")
+      dataAppName: z13.string().optional().describe("Filter by data app name")
     },
     READ_ONLY,
     async (params) => {
@@ -3136,14 +2741,14 @@ function registerListEmbeds(server, client) {
 }
 
 // src/tools/embed/get-embed-details.ts
-import { z as z15 } from "zod";
+import { z as z14 } 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: z15.string().describe("ID of the embed")
+      embedId: z14.string().describe("ID of the embed")
     },
     READ_ONLY,
     async (params) => {
@@ -3159,7 +2764,7 @@ function registerGetEmbedDetails(server, client) {
 }
 
 // src/tools/embed/update-embed.ts
-import { z as z16 } from "zod";
+import { z as z15 } 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.";
@@ -3197,15 +2802,15 @@ function registerUpdateEmbed(server, client) {
     "update_embed",
     "Update embed access settings, permissions, theme, or name.",
     {
-      embedId: z16.string().describe("ID of the embed to update"),
-      body: z16.record(z16.unknown()).optional().describe(
+      embedId: z15.string().describe("ID of the embed to update"),
+      body: z15.record(z15.unknown()).optional().describe(
         "Raw API body for PUT /api/v2/data-app/embeds. If provided, it is sent directly (passthrough mode)."
       ),
-      name: z16.string().optional().describe("New name for the embed"),
-      accessSettings: z16.record(z16.unknown()).optional().describe(
+      name: z15.string().optional().describe("New name for the embed"),
+      accessSettings: z15.record(z15.unknown()).optional().describe(
         "Partial update of access settings. See `get_embed_details` for current settings."
       ),
-      theme: z16.record(z16.unknown()).optional().describe(
+      theme: z15.record(z15.unknown()).optional().describe(
         "Theme configuration object. See databrain://theme-reference for the full schema."
       )
     },
@@ -3251,7 +2856,7 @@ function registerUpdateEmbed(server, client) {
 }
 
 // src/tools/embed/customize-theme.ts
-import { z as z17 } from "zod";
+import { z as z16 } from "zod";
 var THEME_PRESETS = {
   light: {
     general: {
@@ -3385,7 +2990,7 @@ var ACCESS_PRESETS = {
     metricCreationMode: "CHAT"
   }
 };
-var fontFamilyEnum = z17.enum([
+var fontFamilyEnum = z16.enum([
   "Inter",
   "Roboto",
   "Open Sans",
@@ -3397,17 +3002,17 @@ var fontFamilyEnum = z17.enum([
   "Nunito",
   "system-ui"
 ]).describe("Font family");
-var tooltipFontSchema = z17.object({
-  fontFamily: z17.string().optional(),
-  fontSize: z17.number().optional(),
-  fontWeight: z17.number().optional(),
-  fontColor: z17.string().optional()
+var tooltipFontSchema = z16.object({
+  fontFamily: z16.string().optional(),
+  fontSize: z16.number().optional(),
+  fontWeight: z16.number().optional(),
+  fontColor: z16.string().optional()
 }).optional();
-var fontConfigInputSchema = z17.object({
-  fontSize: z17.number().optional(),
-  fontFamily: z17.string().optional(),
-  fontWeight: z17.number().optional(),
-  color: z17.string().optional()
+var fontConfigInputSchema = z16.object({
+  fontSize: z16.number().optional(),
+  fontFamily: z16.string().optional(),
+  fontWeight: z16.number().optional(),
+  color: z16.string().optional()
 }).optional();
 function mapToFrontendFontConfig(input) {
   if (!input) return void 0;
@@ -3418,23 +3023,23 @@ function mapToFrontendFontConfig(input) {
     ...input.color && { color: input.color }
   };
 }
-var axisSchema = z17.object({
-  hideAxisLines: z17.boolean().optional().describe("Hide axis lines"),
-  hideSplitLines: z17.boolean().optional().describe("Hide grid/split lines"),
-  hideAxisLabels: z17.boolean().optional().describe("Hide axis labels"),
-  hideAxisTicks: z17.boolean().optional().describe("Hide axis tick marks"),
-  axisName: z17.string().optional().describe("Axis title text"),
-  axisNameOffset: z17.number().optional().describe("Axis title offset from axis"),
-  axisLabelMargin: z17.number().optional().describe("Margin between axis labels and chart area in pixels"),
-  fontSize: z17.number().optional().describe("Axis label font size"),
-  fontFamily: z17.string().optional().describe("Axis label font family"),
-  fontWeight: z17.number().optional().describe("Axis label font weight"),
-  color: z17.string().optional().describe("Axis label color (hex)"),
-  axisColor: z17.string().optional().describe("Axis line color (hex)"),
-  axisNameFontConfig: z17.object({
-    fontFamily: z17.string().optional(),
-    fontSize: z17.number().optional(),
-    fontWeight: z17.number().optional()
+var axisSchema = z16.object({
+  hideAxisLines: z16.boolean().optional().describe("Hide axis lines"),
+  hideSplitLines: z16.boolean().optional().describe("Hide grid/split lines"),
+  hideAxisLabels: z16.boolean().optional().describe("Hide axis labels"),
+  hideAxisTicks: z16.boolean().optional().describe("Hide axis tick marks"),
+  axisName: z16.string().optional().describe("Axis title text"),
+  axisNameOffset: z16.number().optional().describe("Axis title offset from axis"),
+  axisLabelMargin: z16.number().optional().describe("Margin between axis labels and chart area in pixels"),
+  fontSize: z16.number().optional().describe("Axis label font size"),
+  fontFamily: z16.string().optional().describe("Axis label font family"),
+  fontWeight: z16.number().optional().describe("Axis label font weight"),
+  color: z16.string().optional().describe("Axis label color (hex)"),
+  axisColor: z16.string().optional().describe("Axis line color (hex)"),
+  axisNameFontConfig: z16.object({
+    fontFamily: z16.string().optional(),
+    fontSize: z16.number().optional(),
+    fontWeight: z16.number().optional()
   }).optional().describe("Axis title font configuration")
 }).optional();
 function buildAdminTheme(p, presetBase) {
@@ -3590,94 +3195,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: z17.string().describe("ID of the embed to theme"),
-      body: z17.record(z17.unknown()).optional().describe(
+      embedId: z16.string().describe("ID of the embed to theme"),
+      body: z16.record(z16.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: z17.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
-      accessPreset: z17.enum(["view-only", "power-user", "export-only", "ai-enabled"]).optional().describe("Apply an access settings preset"),
+      themePreset: z16.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
+      accessPreset: z16.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: z17.string().optional().describe("Date picker display format"),
+      datePickerFormat: z16.string().optional().describe("Date picker display format"),
       // --- Colors ---
-      primaryColor: z17.string().optional().describe("Primary accent color (hex)"),
-      backgroundColor: z17.string().optional().describe("Overall background color (hex)"),
-      textColor: z17.string().optional().describe("Default text color (hex)"),
-      ctaColor: z17.string().optional().describe("Call-to-action button color (hex)"),
-      ctaTextColor: z17.string().optional().describe("CTA button text color (hex)"),
+      primaryColor: z16.string().optional().describe("Primary accent color (hex)"),
+      backgroundColor: z16.string().optional().describe("Overall background color (hex)"),
+      textColor: z16.string().optional().describe("Default text color (hex)"),
+      ctaColor: z16.string().optional().describe("Call-to-action button color (hex)"),
+      ctaTextColor: z16.string().optional().describe("CTA button text color (hex)"),
       // --- Dashboard ---
-      dashboardBackgroundColor: z17.string().optional().describe("Dashboard container background (hex)"),
-      selectBoxSize: z17.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
-      selectBoxVariant: z17.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
-      selectBoxBorderRadius: z17.string().optional().describe('Select box border radius (e.g. "20px")'),
-      selectBoxTextColor: z17.string().optional().describe("Select box text color (hex)"),
-      metricCardColor: z17.string().optional().describe("Metric card background color (hex)"),
+      dashboardBackgroundColor: z16.string().optional().describe("Dashboard container background (hex)"),
+      selectBoxSize: z16.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
+      selectBoxVariant: z16.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
+      selectBoxBorderRadius: z16.string().optional().describe('Select box border radius (e.g. "20px")'),
+      selectBoxTextColor: z16.string().optional().describe("Select box text color (hex)"),
+      metricCardColor: z16.string().optional().describe("Metric card background color (hex)"),
       // --- Card Title ---
-      cardTitleFontSize: z17.string().optional().describe('Card title font size (e.g. "16px")'),
-      cardTitleFontWeight: z17.string().optional().describe('Card title font weight (e.g. "600")'),
-      cardTitleColor: z17.string().optional().describe("Card title text color (hex)"),
+      cardTitleFontSize: z16.string().optional().describe('Card title font size (e.g. "16px")'),
+      cardTitleFontWeight: z16.string().optional().describe('Card title font weight (e.g. "600")'),
+      cardTitleColor: z16.string().optional().describe("Card title text color (hex)"),
       // --- Card Description ---
-      cardDescriptionFontSize: z17.string().optional().describe("Card description font size"),
-      cardDescriptionFontWeight: z17.string().optional().describe("Card description font weight"),
-      cardDescriptionColor: z17.string().optional().describe("Card description text color (hex)"),
+      cardDescriptionFontSize: z16.string().optional().describe("Card description font size"),
+      cardDescriptionFontWeight: z16.string().optional().describe("Card description font weight"),
+      cardDescriptionColor: z16.string().optional().describe("Card description text color (hex)"),
       // --- Card Customization ---
-      cardPadding: z17.string().optional().describe("Card internal padding"),
-      cardBorderRadius: z17.string().optional().describe("Card border radius"),
-      cardShadow: z17.string().optional().describe("Card box-shadow CSS value"),
-      disableShadowOnHover: z17.boolean().optional().describe("Disable shadow on card hover"),
-      disableCardStroke: z17.boolean().optional().describe("Remove card border stroke"),
-      cardStrokeColor: z17.string().optional().describe("Card border stroke color (hex)"),
+      cardPadding: z16.string().optional().describe("Card internal padding"),
+      cardBorderRadius: z16.string().optional().describe("Card border radius"),
+      cardShadow: z16.string().optional().describe("Card box-shadow CSS value"),
+      disableShadowOnHover: z16.boolean().optional().describe("Disable shadow on card hover"),
+      disableCardStroke: z16.boolean().optional().describe("Remove card border stroke"),
+      cardStrokeColor: z16.string().optional().describe("Card border stroke color (hex)"),
       // --- Chart Colors (admin theme level) ---
-      chartFontFamily: z17.string().optional().describe("Font family for chart text"),
-      chartFontColor: z17.string().optional().describe("Font color for chart text (hex)"),
-      chartColors: z17.array(z17.string()).optional().describe("Array of chart series colors (hex)"),
-      chartPaletteName: z17.string().optional().describe("Name for a custom palette"),
-      chartPaletteColors: z17.array(z17.string()).optional().describe("9 colors for a custom palette"),
+      chartFontFamily: z16.string().optional().describe("Font family for chart text"),
+      chartFontColor: z16.string().optional().describe("Font color for chart text (hex)"),
+      chartColors: z16.array(z16.string()).optional().describe("Array of chart series colors (hex)"),
+      chartPaletteName: z16.string().optional().describe("Name for a custom palette"),
+      chartPaletteColors: z16.array(z16.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: z17.string().optional().describe("Primary button background (hex)"),
-      buttonPrimaryTextColor: z17.string().optional().describe("Primary button text (hex)"),
-      buttonSecondaryColor: z17.string().optional().describe("Secondary button background (hex)"),
-      buttonSecondaryTextColor: z17.string().optional().describe("Secondary button text (hex)"),
-      checkboxCheckedColor: z17.string().optional().describe("Checked checkbox color (hex)"),
-      checkboxUncheckedColor: z17.string().optional().describe("Unchecked checkbox color (hex)"),
-      switchEnabledColor: z17.string().optional().describe("Enabled switch color (hex)"),
-      switchDisabledColor: z17.string().optional().describe("Disabled switch color (hex)"),
-      breadcrumbFontFamily: z17.string().optional().describe("Drill breadcrumb font family"),
-      breadcrumbFontColor: z17.string().optional().describe("Drill breadcrumb font color (hex)"),
-      breadcrumbActiveColor: z17.string().optional().describe("Active breadcrumb color (hex)"),
-      filterBadgeColor: z17.string().optional().describe("Multi-select filter badge color (hex)"),
-      filterBadgeTextColor: z17.string().optional().describe("Filter badge text color (hex)"),
-      datePickerColor: z17.string().optional().describe("Date picker accent color (hex)"),
+      buttonPrimaryColor: z16.string().optional().describe("Primary button background (hex)"),
+      buttonPrimaryTextColor: z16.string().optional().describe("Primary button text (hex)"),
+      buttonSecondaryColor: z16.string().optional().describe("Secondary button background (hex)"),
+      buttonSecondaryTextColor: z16.string().optional().describe("Secondary button text (hex)"),
+      checkboxCheckedColor: z16.string().optional().describe("Checked checkbox color (hex)"),
+      checkboxUncheckedColor: z16.string().optional().describe("Unchecked checkbox color (hex)"),
+      switchEnabledColor: z16.string().optional().describe("Enabled switch color (hex)"),
+      switchDisabledColor: z16.string().optional().describe("Disabled switch color (hex)"),
+      breadcrumbFontFamily: z16.string().optional().describe("Drill breadcrumb font family"),
+      breadcrumbFontColor: z16.string().optional().describe("Drill breadcrumb font color (hex)"),
+      breadcrumbActiveColor: z16.string().optional().describe("Active breadcrumb color (hex)"),
+      filterBadgeColor: z16.string().optional().describe("Multi-select filter badge color (hex)"),
+      filterBadgeTextColor: z16.string().optional().describe("Filter badge text color (hex)"),
+      datePickerColor: z16.string().optional().describe("Date picker accent color (hex)"),
       // --- Responsive Breakpoints ---
-      breakpointXl: z17.number().optional().describe("XL breakpoint width in px"),
-      breakpointLg: z17.number().optional().describe("LG breakpoint width in px"),
-      breakpointMd: z17.number().optional().describe("MD breakpoint width in px"),
-      breakpointSm: z17.number().optional().describe("SM breakpoint width in px"),
-      breakpointXs: z17.number().optional().describe("XS breakpoint width in px"),
+      breakpointXl: z16.number().optional().describe("XL breakpoint width in px"),
+      breakpointLg: z16.number().optional().describe("LG breakpoint width in px"),
+      breakpointMd: z16.number().optional().describe("MD breakpoint width in px"),
+      breakpointSm: z16.number().optional().describe("SM breakpoint width in px"),
+      breakpointXs: z16.number().optional().describe("XS breakpoint width in px"),
       // --- Metric Layout Columns ---
-      layoutColsXl: z17.number().optional().describe("Grid columns at XL breakpoint"),
-      layoutColsLg: z17.number().optional().describe("Grid columns at LG breakpoint"),
-      layoutColsMd: z17.number().optional().describe("Grid columns at MD breakpoint"),
-      layoutColsSm: z17.number().optional().describe("Grid columns at SM breakpoint"),
-      layoutColsXs: z17.number().optional().describe("Grid columns at XS breakpoint"),
-      layoutColsXxs: z17.number().optional().describe("Grid columns at XXS breakpoint"),
+      layoutColsXl: z16.number().optional().describe("Grid columns at XL breakpoint"),
+      layoutColsLg: z16.number().optional().describe("Grid columns at LG breakpoint"),
+      layoutColsMd: z16.number().optional().describe("Grid columns at MD breakpoint"),
+      layoutColsSm: z16.number().optional().describe("Grid columns at SM breakpoint"),
+      layoutColsXs: z16.number().optional().describe("Grid columns at XS breakpoint"),
+      layoutColsXxs: z16.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: z17.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
-      radialLabelPosition: z17.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
-      marginTop: z17.number().optional().describe("Chart top margin in pixels"),
-      marginLeft: z17.number().optional().describe("Chart left margin in pixels"),
-      marginRight: z17.number().optional().describe("Chart right margin in pixels"),
-      marginBottom: z17.number().optional().describe("Chart bottom margin in pixels"),
-      legendShow: z17.boolean().optional().describe("Show or hide chart legend"),
-      legendPosition: z17.enum([
+      labelPosition: z16.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
+      radialLabelPosition: z16.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
+      marginTop: z16.number().optional().describe("Chart top margin in pixels"),
+      marginLeft: z16.number().optional().describe("Chart left margin in pixels"),
+      marginRight: z16.number().optional().describe("Chart right margin in pixels"),
+      marginBottom: z16.number().optional().describe("Chart bottom margin in pixels"),
+      legendShow: z16.boolean().optional().describe("Show or hide chart legend"),
+      legendPosition: z16.enum([
         "top-left",
         "top-center",
         "top-right",
@@ -3687,17 +3292,17 @@ function registerCustomizeTheme(server, client) {
         "bottom-center",
         "bottom-right"
       ]).optional().describe("Legend position"),
-      legendLayout: z17.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
-      legendShape: z17.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
-      legendFontSize: z17.number().optional().describe("Legend font size"),
-      legendFontWeight: z17.number().optional().describe("Legend font weight"),
-      legendFontFamily: z17.string().optional().describe("Legend font family"),
-      legendColor: z17.string().optional().describe("Legend text color (hex)"),
-      legendTruncateLength: z17.number().optional().describe("Max characters before truncating legend"),
-      disableLegendScrolling: z17.boolean().optional().describe("Disable scrolling in legend"),
-      enableVariableLegendPosition: z17.boolean().optional().describe("Allow user to drag legend"),
-      legendTop: z17.number().optional().describe("Custom legend top offset"),
-      legendLeft: z17.number().optional().describe("Custom legend left offset"),
+      legendLayout: z16.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
+      legendShape: z16.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
+      legendFontSize: z16.number().optional().describe("Legend font size"),
+      legendFontWeight: z16.number().optional().describe("Legend font weight"),
+      legendFontFamily: z16.string().optional().describe("Legend font family"),
+      legendColor: z16.string().optional().describe("Legend text color (hex)"),
+      legendTruncateLength: z16.number().optional().describe("Max characters before truncating legend"),
+      disableLegendScrolling: z16.boolean().optional().describe("Disable scrolling in legend"),
+      enableVariableLegendPosition: z16.boolean().optional().describe("Allow user to drag legend"),
+      legendTop: z16.number().optional().describe("Custom legend top offset"),
+      legendLeft: z16.number().optional().describe("Custom legend left offset"),
       verticalAxis: axisSchema.describe("Vertical (Y) axis configuration"),
       horizontalAxis: axisSchema.describe("Horizontal (X) axis configuration")
     },
@@ -3772,7 +3377,7 @@ Use \`get_embed_details\` to view the full current theme configuration.` + GUEST
 }
 
 // src/tools/embed/get-demo-link.ts
-import { z as z18 } from "zod";
+import { z as z17 } from "zod";
 var HOUR_MS = 60 * 60 * 1e3;
 var DEFAULT_EXPIRY_HOURS = 24;
 var MAX_EXPIRY_HOURS = 24 * 30;
@@ -3782,11 +3387,11 @@ 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: z18.string().describe("End-customer identifier to scope the preview to."),
-      dashboardName: z18.string().optional().describe("Dashboard name (non-technical). Preferred \u2014 pass with optional `workspaceName`."),
-      workspaceName: z18.string().optional().describe("Workspace name. Only needed if `dashboardName` is ambiguous."),
-      embedId: z18.string().optional().describe("Technical alternative to `dashboardName`."),
-      expiryHours: z18.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: z17.string().describe("End-customer identifier to scope the preview to."),
+      dashboardName: z17.string().optional().describe("Dashboard name (non-technical). Preferred \u2014 pass with optional `workspaceName`."),
+      workspaceName: z17.string().optional().describe("Workspace name. Only needed if `dashboardName` is ambiguous."),
+      embedId: z17.string().optional().describe("Technical alternative to `dashboardName`."),
+      expiryHours: z17.number().min(1).max(MAX_EXPIRY_HOURS).optional().describe(`Token TTL in hours. Defaults to ${DEFAULT_EXPIRY_HOURS}. Max ${MAX_EXPIRY_HOURS} (30 days).`)
     },
     WRITE_CREATE,
     async (params) => {
@@ -3842,70 +3447,70 @@ function registerGetDemoLink(server, client) {
 }
 
 // src/tools/frontend/generate-guest-token.ts
-import { z as z19 } from "zod";
+import { z as z18 } 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: z19.string().describe('Unique end-user identifier for multi-tenant filtering. Use "None" if no tenancy.'),
-      dataAppName: z19.string().optional().describe("Name of the data app. Omit to list available data apps."),
-      body: z19.record(z19.unknown()).optional().describe(
+      clientId: z18.string().describe('Unique end-user identifier for multi-tenant filtering. Use "None" if no tenancy.'),
+      dataAppName: z18.string().optional().describe("Name of the data app. Omit to list available data apps."),
+      body: z18.record(z18.unknown()).optional().describe(
         "Raw API body for POST /api/v2/guest-token/create. If provided, sent directly and convenience fields are ignored."
       ),
-      params: z19.object({
-        allowedEmbeds: z19.array(z19.string()).optional().describe("Restrict token to specific embed IDs"),
-        rlsSettings: z19.array(z19.object({
-          metricId: z19.string().describe("Metric ID"),
-          values: z19.record(z19.unknown()).describe("RLS values by column name")
+      params: z18.object({
+        allowedEmbeds: z18.array(z18.string()).optional().describe("Restrict token to specific embed IDs"),
+        rlsSettings: z18.array(z18.object({
+          metricId: z18.string().describe("Metric ID"),
+          values: z18.record(z18.unknown()).describe("RLS values by column name")
         })).optional().describe("Legacy alias used in docs/examples; forwarded as params.rlsSettings"),
-        appFilters: z19.array(z19.object({
-          metricId: z19.string().describe("Metric ID"),
-          values: z19.record(z19.unknown()).describe("Filter values by column name")
+        appFilters: z18.array(z18.object({
+          metricId: z18.string().describe("Metric ID"),
+          values: z18.record(z18.unknown()).describe("Filter values by column name")
         })).optional().describe("Metric-level app filters"),
-        dashboardAppFilters: z19.array(z19.object({
-          dashboardId: z19.string().describe("Dashboard ID"),
-          values: z19.record(z19.unknown()).describe("Filter values by dashboard filter name"),
-          isShowOnUrl: z19.boolean().optional().describe("Whether filters are shown in URL params")
+        dashboardAppFilters: z18.array(z18.object({
+          dashboardId: z18.string().describe("Dashboard ID"),
+          values: z18.record(z18.unknown()).describe("Filter values by dashboard filter name"),
+          isShowOnUrl: z18.boolean().optional().describe("Whether filters are shown in URL params")
         })).optional().describe("Dashboard-level app filters"),
-        hideDashboardFilters: z19.array(z19.string()).optional().describe("Dashboard filter names to hide"),
-        userIdentifier: z19.string().optional().describe("End-user identifier for private metrics support"),
-        timezone: z19.string().optional().describe('IANA timezone, e.g. "America/New_York"')
+        hideDashboardFilters: z18.array(z18.string()).optional().describe("Dashboard filter names to hide"),
+        userIdentifier: z18.string().optional().describe("End-user identifier for private metrics support"),
+        timezone: z18.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: z19.string().optional().describe("Legacy: moved under params.timezone"),
-      allowedEmbeds: z19.array(z19.string()).optional().describe("Legacy: moved under params.allowedEmbeds"),
-      rlsSettings: z19.array(z19.object({
-        metricId: z19.string().describe("Metric ID"),
-        values: z19.record(z19.unknown()).describe("RLS values by column name")
+      timezone: z18.string().optional().describe("Legacy: moved under params.timezone"),
+      allowedEmbeds: z18.array(z18.string()).optional().describe("Legacy: moved under params.allowedEmbeds"),
+      rlsSettings: z18.array(z18.object({
+        metricId: z18.string().describe("Metric ID"),
+        values: z18.record(z18.unknown()).describe("RLS values by column name")
       })).optional().describe("Legacy: moved under params.rlsSettings"),
-      appFilters: z19.array(z19.object({
-        metricId: z19.string().describe("Metric ID"),
-        values: z19.record(z19.unknown()).describe("Filter values by column name")
+      appFilters: z18.array(z18.object({
+        metricId: z18.string().describe("Metric ID"),
+        values: z18.record(z18.unknown()).describe("Filter values by column name")
       })).optional().describe("Legacy: moved under params.appFilters"),
-      dashboardAppFilters: z19.array(z19.object({
-        dashboardId: z19.string().describe("Dashboard ID to apply filters to"),
-        values: z19.record(z19.unknown()).describe("Filter values for this dashboard"),
-        isShowOnUrl: z19.boolean().optional().describe("Whether filters are shown in URL params")
+      dashboardAppFilters: z18.array(z18.object({
+        dashboardId: z18.string().describe("Dashboard ID to apply filters to"),
+        values: z18.record(z18.unknown()).describe("Filter values for this dashboard"),
+        isShowOnUrl: z18.boolean().optional().describe("Whether filters are shown in URL params")
       })).optional().describe("Legacy: moved under params.dashboardAppFilters"),
-      permissions: z19.object({
-        isEnableArchiveMetrics: z19.boolean().optional(),
-        isEnableManageMetrics: z19.boolean().optional(),
-        isEnableCreateDashboardView: z19.boolean().optional(),
-        isEnableMetricUpdation: z19.boolean().optional(),
-        isEnableCustomizeLayout: z19.boolean().optional(),
-        isEnableUnderlyingData: z19.boolean().optional(),
-        isEnableDownloadMetrics: z19.boolean().optional(),
-        isShowSideBar: z19.boolean().optional(),
-        isShowDashboardName: z19.boolean().optional(),
-        isDisableMetricCreation: z19.boolean().optional()
+      permissions: z18.object({
+        isEnableArchiveMetrics: z18.boolean().optional(),
+        isEnableManageMetrics: z18.boolean().optional(),
+        isEnableCreateDashboardView: z18.boolean().optional(),
+        isEnableMetricUpdation: z18.boolean().optional(),
+        isEnableCustomizeLayout: z18.boolean().optional(),
+        isEnableUnderlyingData: z18.boolean().optional(),
+        isEnableDownloadMetrics: z18.boolean().optional(),
+        isShowSideBar: z18.boolean().optional(),
+        isShowDashboardName: z18.boolean().optional(),
+        isDisableMetricCreation: z18.boolean().optional()
       }).optional().describe("Runtime permission overrides (merge with and override embed-level settings)"),
-      theme: z19.record(z19.unknown()).optional().describe("Runtime theme overrides (overrides embed-level theme)"),
-      hideDashboardFilters: z19.array(z19.string()).optional().describe("Legacy: moved under params.hideDashboardFilters"),
-      userIdentifier: z19.string().optional().describe("Legacy: moved under params.userIdentifier"),
-      expiryTime: z19.number().optional().describe("Token TTL in milliseconds"),
-      datasourceName: z19.string().optional().describe("Datasource name for multi-datasource routing")
+      theme: z18.record(z18.unknown()).optional().describe("Runtime theme overrides (overrides embed-level theme)"),
+      hideDashboardFilters: z18.array(z18.string()).optional().describe("Legacy: moved under params.hideDashboardFilters"),
+      userIdentifier: z18.string().optional().describe("Legacy: moved under params.userIdentifier"),
+      expiryTime: z18.number().optional().describe("Token TTL in milliseconds"),
+      datasourceName: z18.string().optional().describe("Datasource name for multi-datasource routing")
     },
     WRITE_CREATE,
     async (params) => {
@@ -3958,7 +3563,7 @@ Next step: Use \`generate_embed_code\` to get copy-paste-ready frontend code.`
 }
 
 // src/tools/frontend/generate-embed-code.ts
-import { z as z20 } from "zod";
+import { z as z19 } from "zod";
 
 // src/templates/react.ts
 function kebabCase(str) {
@@ -4954,22 +4559,22 @@ function registerGenerateEmbedCode(server, _client) {
     "generate_embed_code",
     "Generate framework-specific embed code (React, Next.js, Vue, Angular, Svelte, SolidJS, vanilla HTML).",
     {
-      embedId: z20.string().describe("The embed ID to generate code for"),
-      framework: z20.enum(FRAMEWORKS).describe("Frontend framework"),
-      embedType: z20.enum(["dashboard", "metric"]).optional().default("dashboard"),
-      options: z20.object({
-        enableDownloadCsv: z20.boolean().optional(),
-        enableEmailCsv: z20.boolean().optional(),
-        enableDownloadAllMetrics: z20.boolean().optional(),
-        enableDownloadAllPdf: z20.boolean().optional(),
-        disableFullscreen: z20.boolean().optional(),
-        isHideTablePreview: z20.boolean().optional(),
-        isHideChartSettings: z20.boolean().optional(),
-        isStickyDashboardFilters: z20.boolean().optional(),
-        enableMultiMetricFilters: z20.boolean().optional(),
-        themeName: z20.string().optional(),
-        customTheme: z20.record(z20.unknown()).optional(),
-        optionsIcon: z20.enum(["kebab-menu-vertical", "download"]).optional()
+      embedId: z19.string().describe("The embed ID to generate code for"),
+      framework: z19.enum(FRAMEWORKS).describe("Frontend framework"),
+      embedType: z19.enum(["dashboard", "metric"]).optional().default("dashboard"),
+      options: z19.object({
+        enableDownloadCsv: z19.boolean().optional(),
+        enableEmailCsv: z19.boolean().optional(),
+        enableDownloadAllMetrics: z19.boolean().optional(),
+        enableDownloadAllPdf: z19.boolean().optional(),
+        disableFullscreen: z19.boolean().optional(),
+        isHideTablePreview: z19.boolean().optional(),
+        isHideChartSettings: z19.boolean().optional(),
+        isStickyDashboardFilters: z19.boolean().optional(),
+        enableMultiMetricFilters: z19.boolean().optional(),
+        themeName: z19.string().optional(),
+        customTheme: z19.record(z19.unknown()).optional(),
+        optionsIcon: z19.enum(["kebab-menu-vertical", "download"]).optional()
       }).optional()
     },
     READ_ONLY,
@@ -5009,17 +4614,17 @@ ${generated.instructions}`;
 }
 
 // src/tools/analytics/list-dashboards.ts
-import { z as z21 } from "zod";
+import { z as z20 } from "zod";
 function registerListDashboards(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_dashboards",
     "List dashboards globally or for a specific data app.",
     {
-      scope: z21.enum(["auto", "global", "data_app"]).optional().describe(
+      scope: z20.enum(["auto", "global", "data_app"]).optional().describe(
         "Dashboard listing scope. auto: use data_app when dataAppName + API token are available, otherwise global."
       ),
-      dataAppName: z21.string().optional().describe("Data app name for data_app scope. Ignored for global scope.")
+      dataAppName: z20.string().optional().describe("Data app name for data_app scope. Ignored for global scope.")
     },
     READ_ONLY,
     async (params) => {
@@ -5054,36 +4659,36 @@ function registerListDashboards(server, client) {
 }
 
 // src/tools/dashboard/schema.ts
-import { z as z22 } from "zod";
-var dashboardPositionSchema = z22.object({
-  x: z22.number().int().min(0).max(23),
-  y: z22.number().int().min(0),
-  w: z22.number().int().min(1).max(24),
-  h: z22.number().int().min(1).max(40)
+import { z as z21 } from "zod";
+var dashboardPositionSchema = z21.object({
+  x: z21.number().int().min(0).max(23),
+  y: z21.number().int().min(0),
+  w: z21.number().int().min(1).max(24),
+  h: z21.number().int().min(1).max(40)
 }).strict();
-var dashboardChartSchema = z22.object({
-  type: z22.string(),
-  metricRef: z22.string().optional(),
-  query: z22.string().optional(),
-  companyIntegrationId: z22.string().optional(),
-  chartOptions: z22.record(z22.unknown()).optional()
+var dashboardChartSchema = z21.object({
+  type: z21.string(),
+  metricRef: z21.string().optional(),
+  query: z21.string().optional(),
+  companyIntegrationId: z21.string().optional(),
+  chartOptions: z21.record(z21.unknown()).optional()
 }).passthrough();
-var dashboardTileSchema = z22.object({
-  id: z22.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
-  kind: z22.literal("databrain-chart"),
+var dashboardTileSchema = z21.object({
+  id: z21.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
+  kind: z21.literal("databrain-chart"),
   position: dashboardPositionSchema,
-  title: z22.string().min(1).max(200),
+  title: z21.string().min(1).max(200),
   chart: dashboardChartSchema.optional()
 }).strict();
 var dashboardDocumentShape = {
-  schemaVersion: z22.literal(1),
-  title: z22.string().min(1).max(200),
-  description: z22.string().max(2e3).optional(),
-  layout: z22.object({ columns: z22.union([z22.literal(12), z22.literal(24)]).default(24) }).strict().optional(),
-  tiles: z22.array(dashboardTileSchema).min(1).max(50)
+  schemaVersion: z21.literal(1),
+  title: z21.string().min(1).max(200),
+  description: z21.string().max(2e3).optional(),
+  layout: z21.object({ columns: z21.union([z21.literal(12), z21.literal(24)]).default(24) }).strict().optional(),
+  tiles: z21.array(dashboardTileSchema).min(1).max(50)
 };
-var workspaceNameSchema = z22.string().min(1).describe("Target workspace name");
-var idempotencyKeySchema = z22.string().regex(
+var workspaceNameSchema = z21.string().min(1).describe("Target workspace name");
+var idempotencyKeySchema = z21.string().regex(
   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
   "idempotencyKey must be a UUID v4"
 ).describe("UUID v4 unique to this workspace dashboard create request");
@@ -5136,7 +4741,7 @@ ${stringify(validation)}`
 }
 
 // src/tools/dashboard/generate-dashboard-tiles.ts
-import { z as z23 } from "zod";
+import { z as z22 } from "zod";
 function registerGenerateDashboardTiles(server, client) {
   const services = createServiceBundle(client);
   server.tool(
@@ -5144,15 +4749,15 @@ function registerGenerateDashboardTiles(server, client) {
     "Generate multiple workspace dashboard tile drafts without persisting them.",
     {
       workspaceName: workspaceNameSchema,
-      dataAppName: z23.string().optional().describe("Data app in the workspace; auto-resolved when unique"),
-      integrationId: z23.string().optional().describe("Datasource UUID override"),
-      integrationName: z23.string().optional().describe("Datasource name override"),
-      tiles: z23.array(
-        z23.object({
-          id: z23.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
-          title: z23.string().min(1).max(200),
+      dataAppName: z22.string().optional().describe("Data app in the workspace; auto-resolved when unique"),
+      integrationId: z22.string().optional().describe("Datasource UUID override"),
+      integrationName: z22.string().optional().describe("Datasource name override"),
+      tiles: z22.array(
+        z22.object({
+          id: z22.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
+          title: z22.string().min(1).max(200),
           position: dashboardPositionSchema,
-          userInputs: z23.record(z23.unknown())
+          userInputs: z22.record(z22.unknown())
         }).strict()
       ).min(1).max(50)
     },
@@ -5236,14 +4841,14 @@ function registerGenerateDashboardTiles(server, client) {
 }
 
 // src/tools/dashboard/get-dashboard.ts
-import { z as z24 } from "zod";
+import { z as z23 } from "zod";
 function registerGetDashboard(server, client) {
   server.tool(
     "get_dashboard",
     "Retrieve a workspace dashboard projected back into the versioned tile-list contract.",
     {
       workspaceName: workspaceNameSchema,
-      dashboardId: z24.string().min(1).describe("Dashboard identifier returned by create_dashboard")
+      dashboardId: z23.string().min(1).describe("Dashboard identifier returned by create_dashboard")
     },
     READ_ONLY,
     async (params) => {
@@ -5266,8 +4871,229 @@ function registerGetDashboard(server, client) {
   );
 }
 
-// src/tools/query/ask-question.ts
+// src/tools/dashboard/dashboard-snapshot.ts
+import { z as z24 } from "zod";
+var SNAPSHOT_REQUEST_MS = 45e3;
+function registerDashboardSnapshot(server, client) {
+  server.tool(
+    "dashboard_snapshot",
+    "Get a PNG picture of a dashboard, or of one chart on it (metricId), as the signed-in user sees it in Databrain. Light or dark, 480 to 1600 px wide. Needs a Databrain sign-in (OAuth), not a service token.",
+    {
+      workspaceName: workspaceNameSchema.optional(),
+      dashboardId: z24.string().min(1).max(200).optional().describe("Dashboard id from list_dashboards. Needed unless metricId is given."),
+      metricId: z24.string().min(1).max(200).optional().describe("One chart (metric) id: draw only that chart, from a dashboard it is on."),
+      theme: z24.enum(["light", "dark"]).default("light").describe("Picture colours"),
+      width: z24.number().int().min(480).max(1600).default(1200).describe("Picture width in pixels")
+    },
+    READ_ONLY,
+    async (params) => {
+      if (!params.dashboardId && !params.metricId) {
+        return toolError("Name a dashboardId (from list_dashboards), or a metricId for one chart.");
+      }
+      try {
+        const result = await client.request({
+          method: "POST",
+          path: "/api/v2/workspace/dashboard/snapshot",
+          auth: "service",
+          timeoutMs: SNAPSHOT_REQUEST_MS,
+          body: {
+            ...params.workspaceName ? { workspaceName: params.workspaceName } : {},
+            ...params.dashboardId ? { dashboardId: params.dashboardId } : {},
+            ...params.metricId ? { metricId: params.metricId } : {},
+            theme: params.theme,
+            width: params.width
+          }
+        });
+        if (result?.mimeType !== "image/png" || typeof result.image !== "string" || !result.image) {
+          return toolError("The snapshot answer had no picture. Try again.");
+        }
+        const what = result.metric?.name ? `Chart "${result.metric.name}" on dashboard "${result.dashboard?.name ?? ""}"` : `Dashboard "${result.dashboard?.name ?? ""}"`;
+        const text2 = [
+          `${what} in workspace "${result.workspace?.name ?? ""}", ${result.theme ?? params.theme}, ${result.width}x${result.height} px.`,
+          result.summary ?? ""
+        ].filter(Boolean).join("\n");
+        return {
+          content: [
+            { type: "text", text: text2 },
+            { type: "image", data: result.image, mimeType: "image/png" }
+          ]
+        };
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/apps/preview.ts
+import { createHash } from "crypto";
 import { z as z25 } from "zod";
+var draftSchema = z25.object({
+  question: z25.string().min(1).max(2e3),
+  sql: z25.string().min(1).max(2e4),
+  datamartName: z25.string().min(1).max(256),
+  dimensions: z25.array(z25.string().max(128)).max(20).default([]),
+  measures: z25.array(z25.string().max(128)).max(20).default([]),
+  chartType: z25.string().min(1).max(80),
+  title: z25.string().min(1).max(200),
+  sessionId: z25.string().max(256).optional(),
+  /** Workspaces built on this datamart. One means Save needs no choice. */
+  workspaces: z25.array(z25.string().max(256)).max(50).default([])
+}).strict();
+var PREVIEW_PATH = "/api/v2/data-app/chart-preview";
+var METRIC_PATH = "/api/mcp/metrics/create";
+var DASHBOARD_PATH = "/api/v2/workspace/dashboard";
+var PREVIEW_TYPES = ["bar", "row", "line", "area", "pie", "doughnut", "table"];
+var RENDER_TYPES = [...PREVIEW_TYPES, "single value"];
+async function previewPage(client, draft, rows, chartType) {
+  const page = await client.request({
+    method: "POST",
+    path: PREVIEW_PATH,
+    auth: "service",
+    skipDataUnwrap: true,
+    body: {
+      rows: firstRows(rows),
+      chartType,
+      title: draft.title,
+      dimensions: draft.dimensions,
+      measures: draft.measures,
+      width: 600,
+      height: 320
+    }
+  });
+  return pageSchema.parse(page);
+}
+function tablePage(draft, rows) {
+  const page = firstRows(rows);
+  return {
+    kind: "table",
+    title: draft.title,
+    chartSpec: { type: "table" },
+    rows: page,
+    columns: Object.keys(page[0] ?? {})
+  };
+}
+async function draftPage(client, draft, rows, chartType) {
+  const data = rowsSchema.parse(firstRows(rows));
+  const carry = { draft: { ...draft, chartType }, previewTypes: PREVIEW_TYPES };
+  if (chartType === "table" || !data.length) return { ...tablePage(draft, data), ...carry };
+  try {
+    return { ...await previewPage(client, draft, data, chartType), ...carry };
+  } catch (error) {
+    const previewError = error instanceof DatabrainApiError ? error.code : "PREVIEW_UNAVAILABLE";
+    return { ...tablePage(draft, data), ...carry, draft: { ...draft, chartType: "table" }, previewError };
+  }
+}
+var sameName = (a, b) => typeof a === "string" && a.trim().toLowerCase() === b.trim().toLowerCase();
+async function workspacesForDatamart(client, datamartName, mode = "hint") {
+  const cached = (key) => mode === "hint" ? { cacheKey: key, cacheTtlMs: 5 * 60 * 1e3 } : {};
+  try {
+    const [workspaces, datamarts] = await Promise.all([
+      client.request({ method: "GET", path: "/api/v2/workspace", auth: "service", ...cached("list_workspaces") }),
+      client.request({ method: "GET", path: "/api/v2/data-app/datamarts", auth: "service", ...cached("list_datamarts") })
+    ]);
+    const datasource = (Array.isArray(datamarts) ? datamarts : []).find((d) => sameName(d?.name ?? d?.datamartName, datamartName))?.companyIntegration?.id;
+    const all = (Array.isArray(workspaces) ? workspaces : []).filter((w) => typeof w?.name === "string");
+    const onDatamart = all.filter((w) => sameName(w.datamart?.name ?? w.datamartName, datamartName));
+    const onDatasource = datasource ? all.filter((w) => !w.datamart && w.companyIntegration?.id === datasource) : [];
+    return [...new Set([...onDatamart, ...onDatasource].map((w) => w.name))];
+  } catch {
+    return [];
+  }
+}
+function saveKey(draft, input) {
+  const h = createHash("sha256").update(JSON.stringify({
+    sql: draft.sql,
+    datamartName: draft.datamartName,
+    workspaceName: input.workspaceName,
+    dashboardTitle: input.dashboardTitle,
+    chartType: input.chartType,
+    // One attempt, many retries: the tile mints an id when the form opens and re-sends it on
+    // retry, so a retry replays and a fresh Save is a fresh key. Without one, content is the key.
+    attemptId: input.attemptId ?? null
+  })).digest();
+  h[6] = h[6] & 15 | 64;
+  h[8] = h[8] & 63 | 128;
+  const x = h.subarray(0, 16).toString("hex");
+  return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20, 32)}`;
+}
+async function saveDraftAsDashboard(client, draft, input) {
+  const metric = await client.request({
+    method: "POST",
+    path: METRIC_PATH,
+    auth: "service",
+    body: {
+      workspaceName: input.workspaceName,
+      name: input.dashboardTitle,
+      query: draft.sql,
+      description: draft.question,
+      isPublished: false,
+      validateOnly: false
+    }
+  });
+  const metricId = metric?.metricId || metric?.id;
+  if (!metricId) throw new DatabrainApiError(502, "METRIC_ID_MISSING", "The metric was created but returned no id.");
+  const slug = input.dashboardTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63) || "chart";
+  const body = {
+    schemaVersion: 1,
+    title: input.dashboardTitle,
+    description: draft.question,
+    layout: { columns: 24 },
+    tiles: [{
+      id: slug,
+      kind: "databrain-chart",
+      title: input.dashboardTitle,
+      position: { x: 0, y: 0, w: 12, h: 8 },
+      chart: { type: input.chartType, metricRef: metricId }
+    }]
+  };
+  const dashboard = await client.request({
+    method: "POST",
+    path: DASHBOARD_PATH,
+    auth: "service",
+    query: { workspaceName: input.workspaceName },
+    headers: { "Idempotency-Key": saveKey(draft, input) },
+    body,
+    invalidateCache: ["list_dashboards"],
+    // A metadata insert: 15s keeps the attempt and its retries inside the host's 60s window.
+    timeoutMs: 15e3
+  });
+  if (!dashboard?.dashboardId) {
+    throw new DatabrainApiError(502, "DASHBOARD_ID_MISSING", `Metric ${metricId} was saved but the dashboard returned no id.`);
+  }
+  return { dashboardId: dashboard.dashboardId, metricId, workspaceName: input.workspaceName, title: input.dashboardTitle };
+}
+
+// src/tools/query/ask-question.ts
+import { z as z26 } from "zod";
+
+// src/tools/query/answer-format.ts
+function formatConfidence(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const percent = value > 1 ? value : value * 100;
+  return `${Math.round(Math.min(Math.max(percent, 0), 100))}%`;
+}
+function formatProse(value) {
+  if (Array.isArray(value)) {
+    const items = value.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => `- ${item.trim()}`);
+    return items.length ? items.join("\n") : null;
+  }
+  if (typeof value === "string" && value.trim() !== "") return value.trim();
+  return null;
+}
+
+// src/tools/query/ask-question.ts
+function normalizePreviewType(type) {
+  const t = (type || "").toLowerCase().trim();
+  if (RENDER_TYPES.includes(t)) return t;
+  if (t === "single value" || t === "kpi" || t === "number") return "single value";
+  if (t === "time series" || t === "stepped") return "line";
+  if (t === "stack" || t === "column") return "bar";
+  if (t === "horizontal stack" || t === "horizontal bar") return "row";
+  if (t === "stacked area") return "area";
+  return "table";
+}
 var MAX_DISPLAY_ROWS = 50;
 function formatDataTable(data, columns) {
   if (!Array.isArray(data) || data.length === 0) return "_No data returned._";
@@ -5297,16 +5123,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: z25.string().describe(
+      question: z26.string().describe(
         'The natural language question to ask (e.g. "What was total revenue last month?")'
       ),
-      datamartName: z25.string().optional().describe(
+      datamartName: z26.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: z25.string().optional().describe(
+      sessionId: z26.string().optional().describe(
         "Session ID from a previous ask_question response, for follow-up questions."
       ),
-      timezone: z25.string().optional().describe('IANA timezone (e.g. "America/New_York"). Defaults to UTC.')
+      timezone: z26.string().optional().describe('IANA timezone (e.g. "America/New_York"). Defaults to UTC.')
     },
     WRITE_CREATE,
     async (params) => {
@@ -5411,15 +5237,26 @@ You can verify with \`get_semantic_layer\` using datamartName "${datamartName}".
         });
         const data = Array.isArray(result.data) ? result.data : [];
         if (hasChartApps(server)) {
+          const chartType = normalizePreviewType(result.suggestedChartType);
+          const draft = {
+            question: params.question,
+            sql: result.query || "",
+            datamartName,
+            dimensions: result.columns?.dimensions || [],
+            measures: result.columns?.measures || [],
+            chartType,
+            title: params.question.slice(0, 200),
+            sessionId: result.sessionId || void 0,
+            workspaces: await workspacesForDatamart(client, datamartName)
+          };
           const rows = firstRows(data);
-          return chartResult(`Query Results: ${data.length} rows returned; showing the first ${rows.length}.`, {
-            kind: "table",
-            title: "Query results",
-            chartSpec: { type: result.suggestedChartType || "table" },
-            rows,
-            columns: Object.keys(rows[0] ?? {}),
-            description: "Showing the first page. Interactive chart preview is not available for this query yet."
-          });
+          const page = draft.sql ? await draftPage(client, draft, rows, chartType) : { ...tablePage(draft, rows), previewTypes: [] };
+          const shown = rows.length === data.length ? `${data.length} rows` : `first ${rows.length} of ${data.length} rows`;
+          try {
+            return chartResult(`${page.kind === "table" ? "Table" : "Chart"} ready (${page.chartSpec && page.chartSpec.type}): ${shown}.` + (result.summary ? ` ${result.summary}` : ""), { ...page, rowsTotal: data.length });
+          } catch (error) {
+            if (!(error instanceof Error) || error.message !== "Chart page exceeds payload budget") throw error;
+          }
         }
         const table = formatDataTable(data, result.columns);
         const parts = [];
@@ -5431,23 +5268,24 @@ You can verify with \`get_semantic_layer\` using datamartName "${datamartName}".
         parts.push(
           `**Suggested chart type:** ${result.suggestedChartType}`
         );
-        if (result.confidence !== null) {
-          parts.push(
-            `**Confidence:** ${Math.round(result.confidence * 100)}%`
-          );
+        const confidence = formatConfidence(result.confidence);
+        if (confidence) {
+          parts.push(`**Confidence:** ${confidence}`);
         }
         parts.push(
           `**Rows returned:** ${data.length} | **Time:** ${result.timeTaken}ms`
         );
-        if (result.reasoning) {
+        const reasoning = formatProse(result.reasoning);
+        if (reasoning) {
           parts.push(`
 ### Reasoning
-${result.reasoning}`);
+${reasoning}`);
         }
-        if (result.summary) {
+        const summary = formatProse(result.summary);
+        if (summary) {
           parts.push(`
 ### Summary
-${result.summary}`);
+${summary}`);
         }
         parts.push(`
 ### Data
@@ -5494,14 +5332,14 @@ To fix this:
 }
 
 // src/tools/query/get-semantic-layer.ts
-import { z as z26 } from "zod";
+import { z as z27 } 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: z26.string().optional().describe(
+      datamartName: z27.string().optional().describe(
         "Name of the datamart to inspect. Omit to list available datamarts."
       )
     },
@@ -5610,16 +5448,396 @@ ${result.feedback}`);
   );
 }
 
+// src/tools/query/semantic-model.ts
+import { z as z28 } from "zod";
+
+// src/services/semantic-source.ts
+import { parseDocument, stringify as stringify2 } from "yaml";
+var ENTITY_COLLECTIONS = {
+  table: ["tables"],
+  column: ["columns"],
+  measure: ["measures"],
+  metric: ["metrics"],
+  join: ["joins"],
+  entity: ["entities"],
+  glossary: ["glossary"],
+  saved_query: ["saved_queries", "verified_queries"],
+  instruction: ["instructions", "agent_instructions"],
+  access_rule: ["access", "policies"]
+};
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertSafe(value, seen = /* @__PURE__ */ new Set(), depth = 0) {
+  if (depth > 100) throw new Error("Semantic source nesting exceeds 100 levels.");
+  if (!value || typeof value !== "object") return;
+  if (seen.has(value)) throw new Error("Recursive YAML aliases are not supported.");
+  seen.add(value);
+  for (const [key, child] of Object.entries(value)) {
+    if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error(`Unsupported source key: ${key}.`);
+    assertSafe(child, seen, depth + 1);
+  }
+  seen.delete(value);
+}
+function parseSemanticSource(source2) {
+  const document = parseDocument(source2, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length || document.warnings.length) {
+    throw new Error((document.errors[0] ?? document.warnings[0]).message);
+  }
+  const value = document.toJS({ maxAliasCount: 100 });
+  if (!isObject(value)) throw new Error("Semantic source must be a YAML mapping.");
+  assertSafe(value);
+  return value;
+}
+function semanticEntities(source2, visibleOnly = false) {
+  const out = [];
+  for (const [kind, keys] of Object.entries(ENTITY_COLLECTIONS)) {
+    if (kind === "column") continue;
+    const key = keys.find((key2) => Array.isArray(source2[key2]));
+    const entries = key ? source2[key] : [];
+    for (const entry of entries) {
+      if (!isObject(entry) || typeof entry.name !== "string" || visibleOnly && entry.hidden === true) continue;
+      const columns = Array.isArray(entry.columns) ? entry.columns.filter(isObject) : [];
+      const entity = visibleOnly && kind === "table" ? { ...entry, columns: columns.filter((column) => column.hidden !== true) } : entry;
+      out.push({ id: `${kind}:${entry.name}`, kind, name: entry.name, entity });
+      if (kind === "table") for (const column of columns) {
+        if (typeof column.name !== "string" || visibleOnly && column.hidden === true) continue;
+        const name = `${entry.name}.${column.name}`;
+        out.push({ id: `column:${name}`, kind: "column", name, entity: column });
+      }
+    }
+  }
+  return out;
+}
+function mergePatch(base, patch) {
+  if (isObject(patch)) {
+    const next = isObject(base) ? { ...base } : {};
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === null) delete next[key];
+      else next[key] = mergePatch(next[key], value);
+    }
+    return next;
+  }
+  if (Array.isArray(patch) && patch.length && patch.every((item) => isObject(item) && typeof item.name === "string")) {
+    const next = Array.isArray(base) ? [...base] : [];
+    const names = /* @__PURE__ */ new Set();
+    for (const item of patch) {
+      const name = item.name;
+      if (names.has(name)) throw new Error(`Duplicate patch entity: ${name}.`);
+      names.add(name);
+      const index = next.findIndex((entry) => isObject(entry) && entry.name === name);
+      if (index < 0) next.push(mergePatch({}, item));
+      else next[index] = mergePatch(next[index], item);
+    }
+    return next;
+  }
+  return patch;
+}
+function changeSemanticSource(source2, input) {
+  const model = parseSemanticSource(source2);
+  if (input.yaml_patch !== void 0) return stringify2(mergePatch(model, parseSemanticSource(input.yaml_patch)));
+  const change = input.change;
+  assertSafe(change);
+  let parent = model;
+  if (change.kind === "column") {
+    if (!change.table) throw new Error("A column change requires table and an unqualified column name.");
+    const table = (Array.isArray(model.tables) ? model.tables : []).find(
+      (item) => isObject(item) && item.name === change.table
+    );
+    if (!isObject(table)) throw new Error(`Table not found: ${change.table}.`);
+    parent = table;
+  } else if (change.table) throw new Error("table is only valid for a column change.");
+  const keys = ENTITY_COLLECTIONS[change.kind];
+  const key = keys.find((key2) => Array.isArray(parent[key2])) ?? keys[0];
+  const entries = Array.isArray(parent[key]) ? [...parent[key]] : [];
+  const index = entries.findIndex((entry) => isObject(entry) && entry.name === change.name);
+  if (change.operation === "remove") {
+    if (change.value !== void 0) throw new Error("A remove change must not include value.");
+    if (index < 0) throw new Error(`Entity not found: ${change.kind} ${change.name}.`);
+    entries.splice(index, 1);
+  } else {
+    if (!change.value) throw new Error("An upsert change requires value.");
+    if (change.value.name !== void 0 && change.value.name !== change.name) throw new Error("value.name must match name.");
+    const value = mergePatch(index < 0 ? {} : entries[index], { ...change.value, name: change.name });
+    if (index < 0) entries.push(value);
+    else entries[index] = value;
+  }
+  parent[key] = entries;
+  return stringify2(model);
+}
+
+// src/services/semantic-retrieval.ts
+function tokens(text2) {
+  return text2.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+}
+function text(value) {
+  return typeof value === "string" ? value : Array.isArray(value) ? value.map(text).join(" ") : "";
+}
+function retrieveSemanticSource(source2, question, k) {
+  const nodes = semanticEntities(parseSemanticSource(source2), true);
+  const query = new Set(tokens(question));
+  const score = (node) => {
+    const fields = [
+      [node.name, 8],
+      [node.entity.alias ?? node.entity.term, 6],
+      [node.entity.synonyms, 4],
+      [node.entity.description ?? node.entity.definition ?? node.entity.question, 2]
+    ];
+    return fields.reduce((sum, [value, weight]) => {
+      const words = new Set(tokens(text(value)));
+      return sum + [...query].filter((word) => words.has(word)).length * weight;
+    }, 0);
+  };
+  const ranked = nodes.map((node) => ({ ...node, score: score(node), match: "lexical" })).filter((node) => node.score > 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, k);
+  const edges = new Map(nodes.map((node) => [node.id, /* @__PURE__ */ new Set()]));
+  const byName = /* @__PURE__ */ new Map();
+  for (const node of nodes) byName.set(node.name, [...byName.get(node.name) ?? [], node.id]);
+  const link = (a, b) => {
+    if (a === b || !edges.has(b)) return;
+    edges.get(a).add(b);
+    edges.get(b).add(a);
+  };
+  const refKeys = /* @__PURE__ */ new Set([
+    "table",
+    "column",
+    "columns",
+    "references",
+    "measure",
+    "numerator",
+    "denominator",
+    "metrics",
+    "measures",
+    "glossary_refs",
+    "left",
+    "right",
+    "from",
+    "to",
+    "on",
+    "bindings",
+    "scope",
+    "targets",
+    "tables",
+    "grain",
+    "identifiers",
+    "default_time_dimension",
+    "expression",
+    "sql",
+    "on_sql",
+    "predicate",
+    "type_config"
+  ]);
+  const refs = (value) => {
+    if (typeof value === "string") return value.match(/[\p{L}_][\p{L}\p{N}_]*(?:\.[\p{L}_][\p{L}\p{N}_]*)?/gu) ?? [];
+    if (Array.isArray(value)) return value.flatMap(refs);
+    if (isObject(value)) return Object.entries(value).flatMap(([key, child]) => refKeys.has(key) ? refs(child) : []);
+    return [];
+  };
+  for (const node of nodes) {
+    if (node.kind === "column") link(node.id, `table:${node.name.split(".")[0]}`);
+    for (const ref of refs(node.entity)) for (const id2 of byName.get(ref) ?? []) link(node.id, id2);
+  }
+  const chosen = new Map(ranked.map((node) => [node.id, node]));
+  for (const node of ranked) {
+    for (const id2 of [...edges.get(node.id)].sort()) {
+      if (!chosen.has(id2)) {
+        const adjacent = nodes.find((node2) => node2.id === id2);
+        chosen.set(id2, { ...adjacent, score: 0, match: "adjacency" });
+      }
+    }
+  }
+  return { results: [...chosen.values()], k, lexical_matches: ranked.length, retrieval: "local_lexical" };
+}
+
+// src/tools/query/semantic-model.ts
+var datamartId = z28.string().trim().min(1).max(256).describe("Datamart ID from list_datamarts.");
+var source = z28.string().min(1).max(2e6).describe("Complete proposed semantic model as YAML.");
+var entityKind = z28.enum(["table", "column", "measure", "metric", "join", "entity", "glossary", "saved_query", "instruction", "access_rule"]);
+var changeInputs = {
+  source: source.optional(),
+  yaml_patch: z28.string().min(1).max(2e6).optional().describe("YAML mapping merged into the pulled model. Named lists merge by name. Other lists replace. Null removes a field. An empty list clears it."),
+  change: z28.object({
+    operation: z28.enum(["upsert", "remove"]),
+    kind: entityKind,
+    name: z28.string().trim().min(1),
+    table: z28.string().trim().min(1).optional().describe("Required for columns. Use the table name and an unqualified column name."),
+    value: z28.record(z28.unknown()).optional().describe("Fields to merge for upsert. Omit for remove.")
+  }).strict().optional().describe("One named entity change. Supply exactly one of source, yaml_patch or change.")
+};
+var expectedHash = z28.string().trim().min(1).nullable().optional().describe("Stored content_hash from the reviewed proposal. Null explicitly means the first apply. Required when dry_run is false.");
+function errorCode(error) {
+  const nested = isObject(error.details) && isObject(error.details.error) ? error.details.error : void 0;
+  return typeof nested?.code === "string" ? nested.code : error.code;
+}
+function failure(error) {
+  if (error instanceof DatabrainApiError) {
+    if (error.status === 409 || error.status === 422) {
+      return toolError(stringify({
+        status: error.status,
+        code: errorCode(error),
+        reason: error.message,
+        details: error.details,
+        recovery: error.status === 409 ? "Pull the current model and review a new proposal before applying." : "Correct the validation errors and propose the change again."
+      }));
+    }
+    return error.toToolResponse();
+  }
+  return toolError(`Semantic model error: ${error instanceof Error ? error.message : String(error)}`);
+}
+async function candidate(api, id2, input) {
+  if ([input.source, input.yaml_patch, input.change].filter((value) => value !== void 0).length !== 1) {
+    throw new Error("Supply exactly one of source, yaml_patch or change.");
+  }
+  let stored;
+  try {
+    stored = await api.pull(id2);
+  } catch (error) {
+    if (!(error instanceof DatabrainApiError && error.status === 404 && errorCode(error) === "layer_not_found" && input.source !== void 0)) throw error;
+  }
+  const hash = stored?.content_hash ?? null;
+  if (input.expected_content_hash !== void 0 && input.expected_content_hash !== hash) {
+    throw new DatabrainApiError(409, "content_hash_mismatch", "The model changed since the proposal was reviewed.", { current_hash: hash });
+  }
+  return {
+    source: input.source ?? changeSemanticSource(stored.source, input),
+    expected_content_hash: input.expected_content_hash === void 0 ? hash : input.expected_content_hash
+  };
+}
+async function proposal(api, id2, input) {
+  const next = await candidate(api, id2, input);
+  const validation = await api.validate(id2, next.source);
+  let plan = null;
+  let plan_note;
+  if (validation.ok) {
+    try {
+      plan = await api.plan(id2, next.source, next.expected_content_hash);
+    } catch (error) {
+      if (!(error instanceof DatabrainApiError && [404, 405, 501].includes(error.status))) throw error;
+      plan_note = "This Databrain API has no plan step. The validation above is the server check; apply runs it again.";
+    }
+  }
+  return { ...next, validation, errors: validation.errors, plan, ...plan_note ? { plan_note } : {}, dry_run: true };
+}
+function registerSearchSemanticModel(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "search_semantic_model",
+    "Find semantic model entities relevant to a question. Ranks names, aliases, synonyms and descriptions, then includes related entities. Uses the stored model and never writes.",
+    { datamartId, question: z28.string().trim().min(1).max(1e4), k: z28.number().int().min(1).max(100).default(10) },
+    READ_ONLY,
+    async ({ datamartId: datamartId2, question, k }) => {
+      try {
+        try {
+          return toolSuccess(stringify(await api.retrieve(datamartId2, question, k)));
+        } catch (error) {
+          if (!(error instanceof DatabrainApiError && [404, 405, 501].includes(error.status))) throw error;
+          if (["datamart_not_found", "layer_not_found", "forbidden", "unauthorized"].includes(errorCode(error))) throw error;
+        }
+        const stored = await api.pull(datamartId2);
+        return toolSuccess(stringify({ ...retrieveSemanticSource(stored.source, question, k), content_hash: stored.content_hash }));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerGetSemanticEntity(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "get_semantic_entity",
+    "Read one entity by kind and exact name from the stored semantic model. For a column, use table.column. Returns the stored content hash for change review.",
+    { datamartId, kind: entityKind, name: z28.string().trim().min(1) },
+    READ_ONLY,
+    async ({ datamartId: datamartId2, kind, name }) => {
+      try {
+        const stored = await api.pull(datamartId2);
+        const found = semanticEntities(parseSemanticSource(stored.source)).filter((entity) => entity.kind === kind && entity.name === name);
+        if (found.length !== 1) return toolError(`Expected one ${kind} named ${name}; found ${found.length}. Use search_semantic_model to find its exact name.`);
+        return toolSuccess(stringify({ ...found[0], content_hash: stored.content_hash }));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerProposeSemanticChange(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "propose_semantic_change",
+    "Prepare a semantic model change from complete YAML, a YAML patch or one structured change. Returns validation errors, the server plan, candidate YAML and the stored hash. Never writes.",
+    { datamartId, ...changeInputs },
+    READ_ONLY,
+    async (params) => {
+      try {
+        return toolSuccess(stringify(await proposal(api, params.datamartId, params)));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerApplySemanticChange(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "apply_semantic_change",
+    "Preview a semantic change by default. Setting dry_run to false applies it live and can remove entities. Requires the reviewed content hash and confirm set to APPLY_TO_PRODUCTION supplied by the user.",
+    {
+      datamartId,
+      ...changeInputs,
+      dry_run: z28.boolean().default(true),
+      expected_content_hash: expectedHash,
+      confirm: z28.string().optional().describe("User supplied APPLY_TO_PRODUCTION after reviewing the plan. Never invent confirmation.")
+    },
+    DESTRUCTIVE,
+    async (params) => {
+      try {
+        if (params.dry_run !== false) return toolSuccess(stringify(await proposal(api, params.datamartId, params)));
+        const refusal = validateProductionApply(params);
+        if (refusal) return toolError(refusal);
+        if (params.expected_content_hash === void 0) return toolError("expected_content_hash is required. Use the stored hash from the reviewed proposal, or null for the first apply.");
+        const next = await candidate(api, params.datamartId, params);
+        const validation = await api.validate(params.datamartId, next.source);
+        if (!validation.ok) return failure(new DatabrainApiError(422, "validation_failed", "Apply refused because the model does not validate.", { validation }));
+        return toolSuccess(stringify(await api.apply(params.datamartId, next.source, next.expected_content_hash)));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+function registerEvalSemanticModel(server, client) {
+  const api = createServiceBundle(client).semanticModelApi;
+  server.tool(
+    "eval_semantic_model",
+    "Evaluate saved queries and optional questions against a proposed or stored semantic model. Returns the pass rate and each verdict with its reason. Runs warehouse queries without changing the model.",
+    { datamartId, source: source.optional(), questions: z28.array(z28.union([z28.string().trim().min(1), z28.object({
+      name: z28.string().optional(),
+      question: z28.string().min(1),
+      sql: z28.string().optional(),
+      expected_columns: z28.array(z28.string()).optional(),
+      expected_empty: z28.boolean().optional()
+    }).strict()])).max(100).optional() },
+    READ_ONLY,
+    async ({ datamartId: datamartId2, source: source2, questions }) => {
+      const shaped = questions?.map((entry) => typeof entry === "string" ? { question: entry } : entry);
+      try {
+        return toolSuccess(stringify(await api.evaluate(datamartId2, { source: source2, questions: shaped })));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+
 // src/tools/query/update-semantic-layer.ts
-import { z as z27 } from "zod";
-var columnSchema2 = z27.object({
-  name: z27.string().describe("Column name (must exist in the datamart)"),
-  description: z27.string().optional().describe("Business-friendly description of what this column represents"),
-  synonyms: z27.array(z27.string()).optional().describe(
+import { z as z29 } from "zod";
+var columnSchema2 = z29.object({
+  name: z29.string().describe("Column name (must exist in the datamart)"),
+  description: z29.string().optional().describe("Business-friendly description of what this column represents"),
+  synonyms: z29.array(z29.string()).optional().describe(
     'Alternative names users might use for this column (e.g. ["revenue", "sales amount"])'
   ),
-  miscellaneousInfo: z27.string().optional().describe("Additional context such as valid values, units, or caveats"),
-  columnType: z27.enum([
+  miscellaneousInfo: z29.string().optional().describe("Additional context such as valid values, units, or caveats"),
+  columnType: z29.enum([
     "String",
     "Long String",
     "String (Custom)",
@@ -5630,18 +5848,25 @@ var columnSchema2 = z27.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 and boolean 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.'),
+  // The public PUT accepts these three as well (docs: Update Semantic Layer).
+  // They were missing here, and zod strips unknown keys, so a caller who set
+  // `isIdentifier: true` got a success message and a row with `false`.
+  columnTypeConfig: z29.union([z29.record(z29.string(), z29.string()), z29.string(), z29.object({ lowerLimit: z29.number(), upperLimit: z29.number() }), z29.null()]).optional().describe("Shape depends on columnType: value-to-description object for String / String (Custom) / ENUM / Mapper, { lowerLimit, upperLimit } for Range, a string for Expression and JSON. Omit for Identifier, Number and Long String."),
+  isIdentifier: z29.boolean().optional().describe("Mark the column as an identifier (primary or foreign key)."),
+  isNotIndexed: z29.boolean().optional().describe("Exclude the column from AI indexing.")
 });
-var tableSchema2 = z27.object({
-  name: z27.string().describe("Table name (must exist in the datamart)"),
-  description: z27.string().optional().describe(
+var tableSchema2 = z29.object({
+  name: z29.string().describe("Table name (must exist in the datamart)"),
+  schemaName: z29.string().optional().describe("Schema the table lives in, when the datamart has the same table name in more than one schema."),
+  description: z29.string().optional().describe(
     "Business-friendly description of what this table represents"
   ),
-  synonyms: z27.array(z27.string()).optional().describe("Alternative names for this table"),
-  miscellaneousInfo: z27.string().optional().describe(
+  synonyms: z29.array(z29.string()).optional().describe("Alternative names for this table"),
+  miscellaneousInfo: z29.string().optional().describe(
     "Additional context such as how the table relates to other tables"
   ),
-  columns: z27.array(columnSchema2).optional().describe("Column-level semantic definitions to update")
+  columns: z29.array(columnSchema2).optional().describe("Column-level semantic definitions to update")
 });
 function columnKey(tableName, columnName) {
   return `${tableName.toLowerCase()}\0${columnName.toLowerCase()}`;
@@ -5673,6 +5898,7 @@ function normalizeTablesForApi(tables, datatypesByColumn) {
   if (!tables) return void 0;
   return tables.map((table) => {
     const normalized = { name: table.name };
+    if (table.schemaName !== void 0) normalized.schemaName = table.schemaName;
     if (table.description !== void 0) normalized.description = table.description;
     if (table.synonyms !== void 0) normalized.synonyms = table.synonyms;
     if (table.miscellaneousInfo !== void 0) {
@@ -5696,6 +5922,15 @@ function normalizeTablesForApi(tables, datatypesByColumn) {
             normalizedColumn.columnType = column.columnType;
           }
         }
+        if (column.columnTypeConfig !== void 0) {
+          normalizedColumn.columnTypeConfig = column.columnTypeConfig;
+        }
+        if (column.isIdentifier !== void 0) {
+          normalizedColumn.isIdentifier = column.isIdentifier;
+        }
+        if (column.isNotIndexed !== void 0) {
+          normalizedColumn.isNotIndexed = column.isNotIndexed;
+        }
         return normalizedColumn;
       });
     }
@@ -5708,13 +5943,13 @@ function registerUpdateSemanticLayer(server, client) {
     "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: z27.string().optional().describe(
+      datamartName: z29.string().optional().describe(
         "Name of the datamart to update. Omit to list available datamarts."
       ),
-      tables: z27.array(tableSchema2).optional().describe(
+      tables: z29.array(tableSchema2).optional().describe(
         "Table and column definitions to update. Only include tables/columns you want to change."
       ),
-      feedback: z27.string().optional().describe(
+      feedback: z29.string().optional().describe(
         'General feedback or context about the datamart (e.g. "This datamart contains e-commerce data for the US market").'
       )
     },
@@ -5776,7 +6011,7 @@ You can now:
 }
 
 // src/tools/query/semantic-generation.ts
-import { z as z28 } from "zod";
+import { z as z30 } from "zod";
 function nonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
@@ -5808,9 +6043,9 @@ async function resolveDatamartFromWorkspace(params) {
   });
   if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
   const selected = resolution.selected;
-  const datamartId = workspaceDatamartIdFrom(selected);
+  const datamartId2 = workspaceDatamartIdFrom(selected);
   const workspaceDatamartName = workspaceDatamartNameFrom(selected);
-  if (!datamartId) {
+  if (!datamartId2) {
     return {
       ok: false,
       response: toolError(
@@ -5828,40 +6063,11 @@ async function resolveDatamartFromWorkspace(params) {
   }
   return {
     ok: true,
-    datamartName: workspaceDatamartName || params.datamartName || datamartId,
-    datamartId,
+    datamartName: workspaceDatamartName || params.datamartName || datamartId2,
+    datamartId: datamartId2,
     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 {
@@ -5890,39 +6096,19 @@ async function resolveDatamart(params) {
     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(", ")}`
-        )
-      };
-    }
+  const datamartId2 = datamartIdFrom(resolution.selected);
+  if (!datamartId2) {
     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.`
+        `Datamart "${resolution.name}" did not include an ID in the datamart list. Refresh the list and try again, or pass datamartId directly.`
       )
     };
   }
   return {
     ok: true,
     datamartName: resolution.name,
-    datamartId
+    datamartId: datamartId2
   };
 }
 function registerStartSemanticLayerGeneration(server, client) {
@@ -5931,9 +6117,9 @@ function registerStartSemanticLayerGeneration(server, client) {
     "start_semantic_layer_generation",
     "Start backend semantic-layer auto-generation for a datamart. Returns an async job id to poll.",
     {
-      datamartName: z28.string().optional().describe("Datamart name. Omit to list available datamarts"),
-      workspaceName: z28.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
-      datamartId: z28.string().optional().describe("Datamart UUID. Use only when already known.")
+      datamartName: z30.string().optional().describe("Datamart name. Omit to list available datamarts"),
+      workspaceName: z30.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z30.string().optional().describe("Datamart UUID. Use only when already known.")
     },
     WRITE_CREATE,
     async (params) => {
@@ -5975,9 +6161,9 @@ function registerGetSemanticLayerGenerationStatus(server, client) {
     "get_semantic_layer_generation_status",
     "Get semantic-layer auto-generation job status for a datamart.",
     {
-      datamartName: z28.string().optional().describe("Datamart name. Omit to list available datamarts"),
-      workspaceName: z28.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
-      datamartId: z28.string().optional().describe("Datamart UUID. Use only when already known.")
+      datamartName: z30.string().optional().describe("Datamart name. Omit to list available datamarts"),
+      workspaceName: z30.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z30.string().optional().describe("Datamart UUID. Use only when already known.")
     },
     READ_ONLY,
     async (params) => {
@@ -6014,17 +6200,23 @@ function registerGetSemanticLayerGenerationStatus(server, client) {
 }
 
 // src/tools/widgets/list-widgets.ts
-import { z as z29 } from "zod";
+import { z as z31 } from "zod";
+function widgetReferenceId(widget) {
+  for (const candidate2 of [widget.externalMetricId, widget.id, widget._id, widget.metricId]) {
+    if (typeof candidate2 === "string" && candidate2.trim().length > 0) return candidate2.trim();
+  }
+  return void 0;
+}
 function registerListWidgets(server, client) {
   const services = createServiceBundle(client);
   const tool = 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: z29.string().describe("Client/tenant identifier for this dashboard"),
-      dashboardName: z29.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z29.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z29.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
+      clientId: z31.string().describe("Client/tenant identifier for this dashboard"),
+      dashboardName: z31.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z31.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z31.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
     },
     READ_ONLY,
     async (params) => {
@@ -6043,17 +6235,18 @@ function registerListWidgets(server, client) {
         );
         if (hasChartApps(server)) {
           const visible = (Array.isArray(widgets) ? widgets : []).slice(0, 50);
-          return chartResult(`${visible.length} widgets available in the first dashboard page.`, {
+          const references = visible.flatMap((w) => {
+            const widgetId = widgetReferenceId(w);
+            return widgetId ? [{
+              name: typeof w.name === "string" ? w.name.slice(0, 500) : "Untitled widget",
+              reference: { widgetId, embedId, clientId: params.clientId }
+            }] : [];
+          });
+          return chartResult(`${references.length} widgets available in the first dashboard page.`, {
             kind: "dashboard",
             title: "Dashboard",
             rows: [],
-            widgets: visible.flatMap((w) => {
-              const widgetId = w.externalMetricId || w.id || w._id;
-              return typeof widgetId === "string" ? [{
-                name: typeof w.name === "string" ? w.name.slice(0, 500) : "Untitled widget",
-                reference: { widgetId, embedId, clientId: params.clientId }
-              }] : [];
-            }),
+            widgets: references,
             description: Array.isArray(widgets) && widgets.length > 50 ? "Showing the first 50 widgets." : ""
           });
         }
@@ -6087,29 +6280,29 @@ function registerListWidgets(server, client) {
 }
 
 // src/tools/widgets/add-widget.ts
-import { z as z30 } from "zod";
+import { z as z32 } 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: z30.string().describe("Client/tenant identifier (widget is created in their scope)"),
-      dashboardName: z30.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z30.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z30.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z30.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
-      templateMetricId: z30.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
-      name: z30.string().optional().describe("Widget name (overrides template)"),
-      metricId: z30.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
-      query: z30.string().optional().describe("SQL query body (overrides template)"),
-      chartOptions: z30.record(z30.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
-      description: z30.string().optional(),
-      companyIntegrationId: z30.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: z30.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: z30.boolean().optional().describe("Publish immediately (default true)"),
-      body: z30.record(z30.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params."),
-      widgets: z30.array(z30.record(z30.unknown())).min(1).max(50).optional().describe("Batch of raw createMetric bodies. Dashboard attachment is added to each body.")
+      clientId: z32.string().describe("Client/tenant identifier (widget is created in their scope)"),
+      dashboardName: z32.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z32.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z32.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z32.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      templateMetricId: z32.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
+      name: z32.string().optional().describe("Widget name (overrides template)"),
+      metricId: z32.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
+      query: z32.string().optional().describe("SQL query body (overrides template)"),
+      chartOptions: z32.record(z32.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
+      description: z32.string().optional(),
+      companyIntegrationId: z32.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: z32.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: z32.boolean().optional().describe("Publish immediately (default true)"),
+      body: z32.record(z32.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params."),
+      widgets: z32.array(z32.record(z32.unknown())).min(1).max(50).optional().describe("Batch of raw createMetric bodies. Dashboard attachment is added to each body.")
     },
     WRITE_CREATE,
     async (params) => {
@@ -6257,20 +6450,20 @@ Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust
 }
 
 // src/tools/widgets/update-widget.ts
-import { z as z31 } from "zod";
+import { z as z33 } 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: z31.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
-      clientId: z31.string().describe("Client/tenant identifier"),
-      dashboardName: z31.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z31.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z31.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z31.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
-      set: z31.record(z31.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
+      externalMetricId: z33.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
+      clientId: z33.string().describe("Client/tenant identifier"),
+      dashboardName: z33.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z33.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z33.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z33.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
+      set: z33.record(z33.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -6333,19 +6526,19 @@ Use \`list_widgets\` to verify.`
 }
 
 // src/tools/widgets/remove-widget.ts
-import { z as z32 } from "zod";
+import { z as z34 } 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: z32.string().describe("Internal uuid of the widget (externalMetrics.id)"),
-      clientId: z32.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
-      dashboardName: z32.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z32.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z32.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z32.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
+      externalMetricId: z34.string().describe("Internal uuid of the widget (externalMetrics.id)"),
+      clientId: z34.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
+      dashboardName: z34.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z34.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z34.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z34.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
     },
     DESTRUCTIVE,
     async (params) => {
@@ -6401,21 +6594,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 z33 } from "zod";
+import { z as z35 } from "zod";
 function registerGenerateWidget(server, client) {
   const services = createServiceBundle(client);
   const tool = 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: z33.string().describe("Client/tenant identifier"),
-      userInputs: z33.record(z33.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
-      dashboardName: z33.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
-      workspaceName: z33.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
-      embedId: z33.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
-      dataAppName: z33.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
-      integrationId: z33.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: z33.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: z35.string().describe("Client/tenant identifier"),
+      userInputs: z35.record(z35.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
+      dashboardName: z35.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z35.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z35.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z35.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      integrationId: z35.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: z35.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) => {
@@ -6500,9 +6693,9 @@ function registerGenerateWidget(server, client) {
 }
 
 // src/tools/widgets/create-or-update-metric-from-query.ts
-import { z as z34 } from "zod";
-var modeSchema = z34.enum(["dry_run", "apply"]).default("dry_run");
-var conflictStrategySchema = z34.enum(["fail", "update", "create_new"]).default("fail");
+import { z as z36 } from "zod";
+var modeSchema = z36.enum(["dry_run", "apply"]).default("dry_run");
+var conflictStrategySchema = z36.enum(["fail", "update", "create_new"]).default("fail");
 function makePlanText(plan) {
   return JSON.stringify(plan, null, 2);
 }
@@ -6519,22 +6712,22 @@ function registerCreateOrUpdateMetricFromQuery(server, client) {
     "[EMBEDDING] Create or update a production metric/widget on a customer dashboard from validated SQL. Requires clientId (multi-tenant embed). Defaults to dry-run; apply requires explicit confirmation.",
     {
       mode: modeSchema.describe("dry_run returns the plan only; apply executes after confirmation"),
-      confirm: z34.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      confirm: z36.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: z34.string().describe("Client/tenant identifier for the dashboard widget scope"),
-      workspaceName: z34.string().describe("Target workspace name"),
-      dashboardName: z34.string().optional().describe("Dashboard name to attach to"),
-      embedId: z34.string().optional().describe("Technical embed id alternative to dashboardName"),
-      dataAppName: z34.string().optional().describe("Optional data app override"),
-      name: z34.string().describe("Metric/widget display name"),
-      metricId: z34.string().describe("Stable metric slug to create or update"),
-      query: z34.string().describe("SQL query already validated against the warehouse"),
-      description: z34.string().optional().describe("Metric description"),
-      chartOptions: z34.record(z34.unknown()).optional().describe("Chart configuration JSON"),
-      companyIntegrationId: z34.string().optional().describe("Datasource UUID override"),
-      integrationName: z34.string().optional().describe("Datasource display name override"),
-      isPublished: z34.boolean().optional().describe("Publish after apply. Defaults to false for production safety"),
-      requestedBy: z34.string().optional().describe("Human operator/request context to store on the metric when supported")
+      clientId: z36.string().describe("Client/tenant identifier for the dashboard widget scope"),
+      workspaceName: z36.string().describe("Target workspace name"),
+      dashboardName: z36.string().optional().describe("Dashboard name to attach to"),
+      embedId: z36.string().optional().describe("Technical embed id alternative to dashboardName"),
+      dataAppName: z36.string().optional().describe("Optional data app override"),
+      name: z36.string().describe("Metric/widget display name"),
+      metricId: z36.string().describe("Stable metric slug to create or update"),
+      query: z36.string().describe("SQL query already validated against the warehouse"),
+      description: z36.string().optional().describe("Metric description"),
+      chartOptions: z36.record(z36.unknown()).optional().describe("Chart configuration JSON"),
+      companyIntegrationId: z36.string().optional().describe("Datasource UUID override"),
+      integrationName: z36.string().optional().describe("Datasource display name override"),
+      isPublished: z36.boolean().optional().describe("Publish after apply. Defaults to false for production safety"),
+      requestedBy: z36.string().optional().describe("Human operator/request context to store on the metric when supported")
     },
     WRITE_IDEMPOTENT,
     async (params) => {
@@ -6694,8 +6887,8 @@ function registerCreateOrUpdateMetricFromQuery(server, client) {
 }
 
 // src/tools/widgets/create-workspace-metric.ts
-import { z as z35 } from "zod";
-var modeSchema2 = z35.enum(["dry_run", "apply"]).default("dry_run");
+import { z as z37 } from "zod";
+var modeSchema2 = z37.enum(["dry_run", "apply"]).default("dry_run");
 function registerCreateWorkspaceMetric(server, client) {
   server.tool(
     "create_workspace_metric",
@@ -6704,16 +6897,18 @@ function registerCreateWorkspaceMetric(server, client) {
       mode: modeSchema2.describe(
         "dry_run validates the SQL only (no write); apply creates or updates the metric after confirmation"
       ),
-      confirm: z35.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
-      workspaceName: z35.string().describe("Target workspace name"),
-      name: z35.string().describe("Metric display name"),
-      query: z35.string().describe("SQL query to validate and store"),
-      metricId: z35.string().optional().describe(
+      confirm: z37.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      workspaceName: z37.string().describe("Target workspace name"),
+      name: z37.string().describe("Metric display name"),
+      query: z37.string().describe(
+        "SQL query to validate and store. In a TABLE-tenancy workspace never compare the client column to a fixed client value; use `client_id_variable` so each client sees only its own rows (the backend refuses it with TENANT_KEY_LITERAL)."
+      ),
+      metricId: z37.string().optional().describe(
         "Stable metric slug. Pass an existing slug to UPDATE that metric in place. Omit to create \u2014 the slug is derived deterministically from the name (no random/uniqueness suffix), so re-running with the same name upserts the same metric rather than creating a duplicate."
       ),
-      description: z35.string().optional().describe("Metric description"),
-      datasourceId: z35.string().optional().describe("Datasource UUID override; defaults to the workspace datasource"),
-      isPublished: z35.boolean().optional().describe(
+      description: z37.string().optional().describe("Metric description"),
+      datasourceId: z37.string().optional().describe("Datasource UUID override; defaults to the workspace datasource"),
+      isPublished: z37.boolean().optional().describe(
         "Publish after apply. Defaults to false. Applies to creates; on updates the existing publish state is preserved."
       )
     },
@@ -6769,25 +6964,25 @@ function registerCreateWorkspaceMetric(server, client) {
 }
 
 // src/tools/widgets/validate-metric-spec.ts
-import { z as z36 } from "zod";
+import { z as z38 } 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: z36.string().describe("Client/tenant identifier used to validate dashboard widget scope"),
-      workspaceName: z36.string().describe("Target production-backed workspace name"),
-      dashboardName: z36.string().optional().describe("Dashboard name to attach to"),
-      embedId: z36.string().optional().describe("Technical embed id alternative to dashboardName"),
-      dataAppName: z36.string().optional().describe("Optional data app override"),
-      name: z36.string().describe("Metric/widget display name"),
-      metricId: z36.string().describe("Stable metric slug to create or update"),
-      query: z36.string().describe("SQL query already validated against the warehouse"),
-      description: z36.string().optional().describe("Metric description"),
-      chartOptions: z36.record(z36.unknown()).optional().describe("Chart configuration JSON"),
-      companyIntegrationId: z36.string().optional().describe("Datasource UUID override"),
-      integrationName: z36.string().optional().describe("Datasource display name override")
+      clientId: z38.string().describe("Client/tenant identifier used to validate dashboard widget scope"),
+      workspaceName: z38.string().describe("Target production-backed workspace name"),
+      dashboardName: z38.string().optional().describe("Dashboard name to attach to"),
+      embedId: z38.string().optional().describe("Technical embed id alternative to dashboardName"),
+      dataAppName: z38.string().optional().describe("Optional data app override"),
+      name: z38.string().describe("Metric/widget display name"),
+      metricId: z38.string().describe("Stable metric slug to create or update"),
+      query: z38.string().describe("SQL query already validated against the warehouse"),
+      description: z38.string().optional().describe("Metric description"),
+      chartOptions: z38.record(z38.unknown()).optional().describe("Chart configuration JSON"),
+      companyIntegrationId: z38.string().optional().describe("Datasource UUID override"),
+      integrationName: z38.string().optional().describe("Datasource display name override")
     },
     READ_ONLY,
     async (params) => {
@@ -6878,20 +7073,20 @@ function registerValidateMetricSpec(server, client) {
 }
 
 // src/tools/reports/list-scheduled-reports.ts
-import { z as z37 } from "zod";
+import { z as z39 } from "zod";
 function registerListScheduledReports(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_scheduled_reports",
     "List configured scheduled reports for a specific client/dashboard embed. Shows schedule metadata, not delivery success history.",
     {
-      clientId: z37.string().describe("Client/tenant identifier. Required by the current backend API for non-empty results"),
-      dashboardName: z37.string().optional().describe("Dashboard name to inspect"),
-      workspaceName: z37.string().optional().describe("Workspace name if dashboardName is ambiguous"),
-      embedId: z37.string().optional().describe("Technical embed id alternative to dashboardName"),
-      userIdentifier: z37.string().optional().describe("Optional creator/user filter"),
-      pageNumber: z37.number().int().positive().optional().describe("Page number when pagination is enabled"),
-      isPagination: z37.boolean().optional().describe("Enable backend pagination")
+      clientId: z39.string().describe("Client/tenant identifier. Required by the current backend API for non-empty results"),
+      dashboardName: z39.string().optional().describe("Dashboard name to inspect"),
+      workspaceName: z39.string().optional().describe("Workspace name if dashboardName is ambiguous"),
+      embedId: z39.string().optional().describe("Technical embed id alternative to dashboardName"),
+      userIdentifier: z39.string().optional().describe("Optional creator/user filter"),
+      pageNumber: z39.number().int().positive().optional().describe("Page number when pagination is enabled"),
+      isPagination: z39.boolean().optional().describe("Enable backend pagination")
     },
     READ_ONLY,
     async (params) => {
@@ -6965,7 +7160,7 @@ function registerWhoami(server, client) {
               status: "authenticated",
               activeBearer: "service-token",
               ...auth.oauthFallback ? { oauthFallback: true } : {},
-              note: auth.oauthFallback ? "OAuth token acquisition failed; the configured static service token is in use. Mutations use the static org-level principal, with actor=system. OAuth will be retried after a short cooldown." : "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."
+              note: auth.oauthFallback ? "OAuth token acquisition failed; the configured static service token is in use. Mutations use the static org-level principal, with actor=system. OAuth will be retried after a short cooldown." : "Org-level service token (DATABRAIN_SERVICE_TOKEN). Per-user identity is NOT bound \u2014 mutations are audit-logged as actor=system. For per-user access, connect an AI app to the hosted server (it signs in with your Databrain account)."
             },
             null,
             2
@@ -7000,6 +7195,460 @@ function registerWhoami(server, client) {
   );
 }
 
+// src/tools/custom-chart/scaffold.ts
+import { z as z41 } from "zod";
+
+// src/tools/custom-chart/shared.ts
+import { z as z40 } from "zod";
+var slotInputSchema = slotSchema;
+var optionInputSchema = optionSchema;
+var manifestInputSchema = z40.record(z40.unknown()).describe("manifest.json as an object (schemaVersion 2). Validated with the same rules as the server.");
+var bundleInputShape = {
+  manifest: manifestInputSchema.optional(),
+  bundleJs: z40.string().optional().describe("dist/index.js from `databrain custom-chart build` (the shim plus the chart module)."),
+  bundleCss: z40.string().optional().describe("The raw chart.css, kept for provenance."),
+  iconSvg: z40.string().optional().describe("icon.svg, at most 16 KiB, no script, no foreignObject, no external href."),
+  projectDir: z40.string().optional().describe("Local only: a chart project folder. The tool reads it instead of manifest/bundleJs/iconSvg.")
+};
+function formatProblems(problems) {
+  if (problems.length === 0) return "No problems.";
+  return problems.map((p) => `${p.path || "/"}  ${p.code}  ${p.message}`).join("\n");
+}
+function projectDirRefusal() {
+  if (process.env.DATABRAIN_HOSTED_PUBLIC_URL) {
+    return "projectDir is not available on the hosted server. Pass manifest, bundleJs, bundleCss and iconSvg instead.";
+  }
+  return null;
+}
+async function resolveBundleInput(params, options) {
+  if (params.projectDir) {
+    const refusal = projectDirRefusal();
+    if (refusal) return { problems: [], error: refusal, source: "projectDir" };
+    if (params.manifest || params.bundleJs || params.iconSvg) {
+      return { problems: [], error: "Pass either projectDir or manifest/bundleJs/iconSvg, not both.", source: "projectDir" };
+    }
+    if (options.build) {
+      const result = await buildProject(params.projectDir, { write: false });
+      if (!result.ok || !result.outputs) return { problems: result.problems, source: "projectDir" };
+      const { manifest, bundleJs, bundleCss, iconSvg } = result.outputs;
+      return { bundle: { manifest, bundleJs, bundleCss, iconSvg }, problems: [], source: "projectDir" };
+    }
+    const dist = readDist(params.projectDir);
+    if (!dist.bundle) return { problems: dist.problems, source: "projectDir" };
+    return { bundle: dist.bundle, problems: [], source: "projectDir" };
+  }
+  if (!params.manifest) {
+    return { problems: [], error: "manifest is required (or pass projectDir when running locally).", source: "arguments" };
+  }
+  return {
+    bundle: {
+      manifest: params.manifest,
+      bundleJs: params.bundleJs,
+      bundleCss: params.bundleCss,
+      iconSvg: params.iconSvg
+    },
+    problems: [],
+    source: "arguments"
+  };
+}
+async function remoteValidate(client, bundle) {
+  try {
+    const result = await createCustomChartsApi(client).validate(bundle);
+    return { status: "ok", result };
+  } catch (err) {
+    if (err instanceof DatabrainApiError) {
+      if (err.code === "MISSING_SERVICE_TOKEN") {
+        return { status: "skipped", reason: "No service token is configured, so only the local validator ran." };
+      }
+      return { status: "failed", reason: err.message, problems: apiProblems(err) };
+    }
+    return { status: "failed", reason: err.message, problems: [] };
+  }
+}
+function isCompleteBundle(bundle) {
+  return typeof bundle.bundleJs === "string" && typeof bundle.iconSvg === "string";
+}
+
+// src/tools/custom-chart/scaffold.ts
+function registerCustomChartScaffold(server, _client) {
+  server.tool(
+    "custom_chart_scaffold",
+    "Return the files of a new custom chart project (manifest.json, chart.ts, chart.css, icon.svg, sample data, guide). Nothing is written or persisted; write the files yourself.",
+    {
+      key: z41.string().describe("Chart key, becomes chart type custom:<key>. Lowercase letters, digits, _ and -, 64 max."),
+      name: z41.string().describe("Display name shown in the chart picker, 1 to 256 characters."),
+      description: z41.string().optional().describe("Optional description, up to 500 characters."),
+      slots: z41.array(slotInputSchema).optional().describe("Data slots. Defaults to category (dimension), value (measure), target (optional measure)."),
+      options: z41.array(optionInputSchema).optional().describe("Chart options. Defaults to the template options (labels, subtitle, radius, colour, sort).")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const result = scaffoldProject({
+          key: params.key,
+          name: params.name,
+          description: params.description,
+          slots: params.slots,
+          options: params.options
+        });
+        if (!result.ok) {
+          return toolError(`The requested manifest is not valid:
+${formatProblems(result.problems)}`);
+        }
+        return toolSuccess(
+          JSON.stringify(
+            {
+              status: "scaffold_only",
+              key: params.key,
+              chartType: `custom:${params.key}`,
+              files: result.files,
+              nextStep: result.nextStep
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/custom-chart/validate.ts
+function registerCustomChartValidate(server, client) {
+  server.tool(
+    "custom_chart_validate",
+    "Validate a custom chart manifest and bundle with the local rules and, when a service token is configured, the server rules. Never persists anything.",
+    bundleInputShape,
+    READ_ONLY,
+    async (params) => {
+      try {
+        const resolved = await resolveBundleInput(params, { build: true });
+        if (resolved.error) return toolError(resolved.error);
+        if (!resolved.bundle) {
+          return toolSuccess(JSON.stringify({ ok: false, problems: resolved.problems, source: resolved.source }, null, 2));
+        }
+        const { bundle } = resolved;
+        const problems = validateBundle(bundle);
+        const complete = isCompleteBundle(bundle);
+        const result = {
+          ok: problems.length === 0,
+          problems,
+          source: resolved.source,
+          contentHash: complete && problems.length === 0 ? contentHash(bundle) : void 0,
+          sizeBytes: complete && problems.length === 0 ? bundleSizeBytes(bundle) : void 0
+        };
+        if (!complete) {
+          result.note = "Only the manifest was checked. Pass bundleJs and iconSvg (or projectDir) to check the whole package.";
+        } else if (problems.length === 0) {
+          const remote = await remoteValidate(client, bundle);
+          if (remote.status === "ok") {
+            result.remote = remote.result;
+            if (!remote.result.ok) {
+              result.ok = false;
+              result.problems = remote.result.problems;
+            }
+            if (remote.result.contentHash) result.contentHash = remote.result.contentHash;
+            if (typeof remote.result.sizeBytes === "number") result.sizeBytes = remote.result.sizeBytes;
+          } else if (remote.status === "skipped") {
+            result.remote = { status: "skipped", reason: remote.reason };
+          } else {
+            result.remote = { status: "failed", reason: remote.reason };
+            if (remote.problems.length > 0) {
+              result.ok = false;
+              result.problems = remote.problems;
+            }
+          }
+        }
+        result.nextStep = result.ok ? "Upload with custom_chart_upload (mode dry_run first) or `databrain custom-chart upload`." : "Fix every problem (path, code, message), then validate again.";
+        return toolSuccess(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/custom-chart/upload.ts
+import { z as z42 } from "zod";
+function registerCustomChartUpload(server, client) {
+  const api = createCustomChartsApi(client);
+  server.tool(
+    "custom_chart_upload",
+    "Upload a built custom chart bundle to the company. Creates the chart (private, version 1) or a new preview version. Defaults to dry_run; apply requires explicit confirmation and can publish in the same call.",
+    {
+      mode: z42.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run validates and returns the plan; apply uploads."),
+      confirm: z42.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
+      publish: z42.boolean().default(false).describe("After a successful apply, publish the uploaded version so every builder can use it."),
+      name: z42.string().optional().describe("Display name override. Defaults to manifest.name."),
+      description: z42.string().optional().describe("Description override. Defaults to manifest.description."),
+      ...bundleInputShape
+    },
+    WRITE_CREATE,
+    async (params) => {
+      try {
+        const mode = params.mode || "dry_run";
+        const resolved = await resolveBundleInput(params, { build: false });
+        if (resolved.error) return toolError(resolved.error);
+        if (!resolved.bundle) {
+          return toolError(`The project could not be read:
+${formatProblems(resolved.problems)}`);
+        }
+        const { bundle } = resolved;
+        if (!isCompleteBundle(bundle)) {
+          return toolError("manifest, bundleJs and iconSvg are all required to upload. Run `databrain custom-chart build` and pass dist/index.js, dist/manifest.json and dist/icon.svg (or projectDir when local).");
+        }
+        const problems = validateBundle(bundle);
+        if (problems.length > 0) {
+          return toolError(`The bundle is not valid. Fix these and try again:
+${formatProblems(problems)}`);
+        }
+        const manifest = bundle.manifest;
+        const key = manifest.id;
+        const body = {
+          manifest,
+          bundleJs: bundle.bundleJs,
+          bundleCss: bundle.bundleCss,
+          iconSvg: bundle.iconSvg,
+          ...params.name ? { name: params.name } : {},
+          ...params.description ? { description: params.description } : {}
+        };
+        const localHash = contentHash(bundle);
+        const localSize = bundleSizeBytes(bundle);
+        if (mode === "dry_run") {
+          const remote = await remoteValidate(client, bundle);
+          let existing;
+          let planNote;
+          try {
+            existing = (await api.list()).find((chart) => chart.key === key);
+          } catch (err) {
+            planNote = err instanceof DatabrainApiError && err.code === "MISSING_SERVICE_TOKEN" ? "No service token is configured, so the plan could not check whether the chart exists." : `Could not list custom charts: ${err.message}`;
+          }
+          const plan = planUpload(key, existing);
+          const remoteOk = remote.status !== "ok" || remote.result.ok;
+          return toolSuccess(
+            JSON.stringify(
+              {
+                status: "dry_run_only",
+                safety: genericProductionSafetyNote(),
+                ok: remoteOk,
+                key,
+                chartType: `custom:${key}`,
+                contentHash: remote.status === "ok" && remote.result.contentHash ? remote.result.contentHash : localHash,
+                sizeBytes: remote.status === "ok" && typeof remote.result.sizeBytes === "number" ? remote.result.sizeBytes : localSize,
+                problems: remote.status === "ok" ? remote.result.problems : remote.status === "failed" ? remote.problems : [],
+                remote: remote.status === "ok" ? "validated by the server" : remote.reason,
+                plan: plan.summary,
+                ...planNote ? { planNote } : {},
+                publishAfterUpload: params.publish === true,
+                requiredApplyConfirmation: APPLY_TO_PRODUCTION_CONFIRMATION,
+                nextStep: remoteOk ? `Review this plan. To execute, call again with mode="apply" and confirm="${APPLY_TO_PRODUCTION_CONFIRMATION}"${params.publish ? " (publish=true will publish the new version right away)" : ""}.` : "Fix every problem, rebuild, then run dry_run again."
+              },
+              null,
+              2
+            )
+          );
+        }
+        const guardError = validateProductionApply({ confirm: params.confirm });
+        if (guardError) return toolError(guardError);
+        const uploaded = await api.upload(body);
+        const versionNumber = uploaded.version?.versionNumber;
+        const lines = [];
+        if (uploaded.created === "none") {
+          lines.push(`This exact bundle is already v${versionNumber ?? "?"} of custom:${key}. Nothing was created.`);
+        } else if (uploaded.created === "chart") {
+          lines.push(`Created custom chart custom:${key} (v${versionNumber ?? 1}, status private).`);
+        } else {
+          lines.push(`Uploaded v${versionNumber ?? "?"} of custom:${key}. It is in preview until you publish it.`);
+        }
+        lines.push(`contentHash: ${uploaded.version?.contentHash ?? localHash}`);
+        if (params.publish) {
+          const published = await api.publish(key, uploaded.version?.id);
+          lines.push(`Published v${versionNumber ?? "?"} of custom:${key}. Status: ${published.chart?.status ?? "published"}. Every dashboard using custom:${key} now renders this version.`);
+        } else if (uploaded.created !== "none" || uploaded.chart?.status !== "published") {
+          lines.push(`To make it available to builders: publish_custom_chart with key "${key}" and confirm="${APPLY_TO_PRODUCTION_CONFIRMATION}", or Settings > Developers > Custom charts.`);
+        }
+        return toolSuccess(lines.join("\n"));
+      } catch (err) {
+        if (err instanceof DatabrainApiError) {
+          const problems = apiProblems(err);
+          if (problems.length > 0) {
+            return toolError(`The server refused the bundle: ${err.message}
+${formatProblems(problems)}`);
+          }
+          return err.toToolResponse();
+        }
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/custom-chart/list.ts
+function registerListCustomCharts(server, client) {
+  server.tool(
+    "list_custom_charts",
+    "List the custom chart types of the company (key, name, status, published and preview versions). Uses the service token.",
+    {},
+    READ_ONLY,
+    async () => {
+      try {
+        const charts = await createCustomChartsApi(client).list();
+        const rows = charts.map((chart) => ({
+          key: chart.key,
+          chartType: `custom:${chart.key}`,
+          name: chart.name,
+          status: chart.status,
+          publishedVersionId: chart.publishedVersionId ?? null,
+          publishedVersionNumber: typeof chart.publishedVersionNumber === "number" ? chart.publishedVersionNumber : void 0,
+          previewVersionId: chart.previewVersionId ?? null,
+          previewVersionNumber: typeof chart.previewVersionNumber === "number" ? chart.previewVersionNumber : void 0,
+          versionsCount: typeof chart.versionsCount === "number" ? chart.versionsCount : void 0,
+          updatedAt: chart.updatedAt,
+          createdBy: chart.createdBy ?? null
+        }));
+        if (rows.length === 0) {
+          return toolSuccess(
+            "No custom charts yet. Scaffold one with custom_chart_scaffold, build it with `databrain custom-chart build`, then upload with custom_chart_upload."
+          );
+        }
+        return toolSuccess(JSON.stringify({ count: rows.length, charts: rows }, null, 2));
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/custom-chart/publish.ts
+import { z as z43 } from "zod";
+function registerPublishCustomChart(server, client) {
+  const api = createCustomChartsApi(client);
+  server.tool(
+    "publish_custom_chart",
+    "Publish a custom chart version so every builder in the company can use chart type custom:<key>. Defaults to the preview version. Defaults to dry_run; apply requires explicit confirmation.",
+    {
+      key: z43.string().describe("The chart key (manifest.id), for example revenue-bars."),
+      versionId: z43.string().optional().describe("A specific version id to publish. Defaults to the preview version."),
+      mode: z43.enum(["dry_run", "apply"]).default("dry_run").describe("dry_run shows what would be published; apply publishes."),
+      confirm: z43.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`)
+    },
+    WRITE_IDEMPOTENT,
+    async (params) => {
+      try {
+        const mode = params.mode || "dry_run";
+        const detail = await api.get(params.key);
+        const versions = Array.isArray(detail.versions) ? detail.versions : [];
+        const targetId = params.versionId ?? detail.previewVersionId ?? null;
+        const target = versions.find((version) => version.id === targetId);
+        if (!targetId) {
+          return toolError(
+            `custom:${params.key} has no preview version to publish${detail.publishedVersionId ? ` (v published: ${detail.publishedVersionId})` : ""}. Upload a new version first, or pass versionId.`
+          );
+        }
+        if (params.versionId && versions.length > 0 && !target) {
+          return toolError(`custom:${params.key} has no version with id ${params.versionId}. Versions: ${versions.map((v) => `${v.id} (v${v.versionNumber})`).join(", ")}.`);
+        }
+        if (detail.publishedVersionId === targetId) {
+          return toolSuccess(`custom:${params.key} already has ${target ? `v${target.versionNumber}` : targetId} published. Nothing to do.`);
+        }
+        if (mode === "dry_run") {
+          return toolSuccess(
+            JSON.stringify(
+              {
+                status: "dry_run_only",
+                safety: genericProductionSafetyNote(),
+                key: params.key,
+                chartType: `custom:${params.key}`,
+                name: detail.name,
+                currentStatus: detail.status,
+                currentPublishedVersionId: detail.publishedVersionId ?? null,
+                willPublish: { versionId: targetId, versionNumber: target?.versionNumber, contentHash: target?.contentHash },
+                impact: `Every dashboard using custom:${params.key} will render this version.`,
+                requiredApplyConfirmation: APPLY_TO_PRODUCTION_CONFIRMATION,
+                nextStep: `Ask the user to confirm, then 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 api.publish(params.key, targetId);
+        return toolSuccess(
+          `Published ${target ? `v${target.versionNumber}` : targetId} of custom:${params.key} (${result.chart?.name ?? detail.name}). Status: ${result.chart?.status ?? "published"}. Every dashboard using custom:${params.key} now renders this version.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/tool-titles.ts
+var TOOL_TITLES = {
+  whoami: "Show active credential",
+  list_datasources: "List data sources",
+  discover_datasource_schema: "Discover data source schema",
+  list_datamarts: "List datamarts",
+  list_workspaces: "List workspaces",
+  sync_datasource: "Sync data source",
+  create_datamart: "Create datamart",
+  create_workspace: "Create workspace",
+  list_data_apps: "List data apps",
+  list_tenants: "List tenants",
+  create_data_app: "Create data app",
+  list_api_tokens: "List API tokens",
+  create_api_token: "Create API token",
+  rotate_api_token: "Rotate API token",
+  create_embed: "Create embed",
+  list_embeds: "List embeds",
+  get_embed_details: "Get embed details",
+  update_embed: "Update embed",
+  customize_embed_theme: "Customize embed theme",
+  get_demo_link: "Get demo link",
+  generate_guest_token: "Generate guest token",
+  generate_embed_code: "Generate embed code",
+  list_dashboards: "List dashboards",
+  create_dashboard: "Create dashboard",
+  get_dashboard: "Get dashboard",
+  dashboard_snapshot: "Dashboard snapshot (picture)",
+  generate_dashboard_tiles: "Generate dashboard tiles",
+  ask_question: "Ask a data question",
+  get_semantic_layer: "Get semantic layer",
+  update_semantic_layer: "Update semantic layer",
+  start_semantic_layer_generation: "Start semantic layer generation",
+  get_semantic_layer_generation_status: "Get semantic layer generation status",
+  search_semantic_model: "Search semantic model",
+  get_semantic_entity: "Get semantic entity",
+  propose_semantic_change: "Propose semantic model change",
+  apply_semantic_change: "Apply semantic model change",
+  eval_semantic_model: "Evaluate semantic model",
+  list_widgets: "List widgets",
+  validate_metric_spec: "Validate metric spec",
+  create_or_update_metric_from_query: "Create or update metric from SQL",
+  create_workspace_metric: "Create workspace metric",
+  add_widget: "Add widget",
+  update_widget: "Update widget",
+  remove_widget: "Remove widget",
+  generate_widget: "Generate widget",
+  list_scheduled_reports: "List scheduled reports",
+  custom_chart_scaffold: "Scaffold custom chart",
+  custom_chart_validate: "Validate custom chart",
+  custom_chart_upload: "Upload custom chart",
+  list_custom_charts: "List custom charts",
+  publish_custom_chart: "Publish custom chart"
+};
+function toolTitle(name) {
+  if (TOOL_TITLES[name]) return TOOL_TITLES[name];
+  const words = name.split("_").filter(Boolean);
+  return words.map((word, index) => index === 0 ? word[0].toUpperCase() + word.slice(1) : word).join(" ");
+}
+
 // src/tools/registry.ts
 function instrumentToolRegistration(server) {
   const original = server.tool.bind(server);
@@ -7020,7 +7669,15 @@ function instrumentToolRegistration(server) {
         () => handler(...handlerArgs)
       );
     }
-    return original(...args);
+    const title = toolTitle(name);
+    const annotationIndex = cbIndex - 1;
+    const annotations = args[annotationIndex];
+    if (annotationIndex > 1 && annotations && typeof annotations === "object" && ("readOnlyHint" in annotations || "destructiveHint" in annotations) && !("title" in annotations)) {
+      args[annotationIndex] = { title, ...annotations };
+    }
+    const registered = original(...args);
+    if (registered && typeof registered === "object" && !registered.title) registered.title = title;
+    return registered;
   };
 }
 function registerAllTools(server, client) {
@@ -7049,12 +7706,18 @@ function registerAllTools(server, client) {
   registerListDashboards(server, client);
   registerCreateDashboard(server, client);
   registerGetDashboard(server, client);
+  registerDashboardSnapshot(server, client);
   registerGenerateDashboardTiles(server, client);
   registerAskQuestion(server, client);
   registerGetSemanticLayer(server, client);
   registerUpdateSemanticLayer(server, client);
   registerStartSemanticLayerGeneration(server, client);
   registerGetSemanticLayerGenerationStatus(server, client);
+  registerSearchSemanticModel(server, client);
+  registerGetSemanticEntity(server, client);
+  registerProposeSemanticChange(server, client);
+  registerApplySemanticChange(server, client);
+  registerEvalSemanticModel(server, client);
   registerListWidgets(server, client);
   registerValidateMetricSpec(server, client);
   registerCreateOrUpdateMetricFromQuery(server, client);
@@ -7064,6 +7727,11 @@ function registerAllTools(server, client) {
   registerRemoveWidget(server, client);
   registerGenerateWidget(server, client);
   registerListScheduledReports(server, client);
+  registerCustomChartScaffold(server, client);
+  registerCustomChartValidate(server, client);
+  registerCustomChartUpload(server, client);
+  registerListCustomCharts(server, client);
+  registerPublishCustomChart(server, client);
 }
 
 // src/resources/content/getting-started.ts
@@ -8944,6 +9612,20 @@ When the same flag is set at multiple levels, the highest precedence wins:
 
 // src/resources/content/semantic-layer-guide.ts
 var semanticLayerGuideContent = `
+
+## Semantic models v2
+
+The v2 source is one YAML document. Use the configured service credential and a datamart ID from \`list_datamarts\`.
+
+1. \`search_semantic_model\` finds entities by question. \`get_semantic_entity\` reads one entity by kind and name. Column names use table.column.
+2. \`propose_semantic_change\` takes complete source YAML, a YAML patch or one structured change. It returns candidate source, validation errors, a plan and the stored expected hash without writing.
+3. \`eval_semantic_model\` evaluates the proposed source.
+4. \`apply_semantic_change\` defaults to a dry run. Live apply requires the exact reviewed source, \`expected_content_hash\`, \`dry_run: false\` and user supplied \`confirm: "APPLY_TO_PRODUCTION"\`. Never supply confirmation yourself. Apply changes the live model for all consumers. On a conflict, prepare a fresh proposal and review it again.
+
+YAML patches merge mappings and named lists by name. Other lists replace. Empty lists clear; null removes a field. Structured changes use operation upsert or remove, kind, name, and value for upsert. Column changes also require table. Patch output normalizes formatting and comments, so review the returned source before apply.
+
+The legacy maintenance workflow below applies to datamarts that have not moved to v2. Do not call \`update_semantic_layer\` for v2.
+
 # Databrain Semantic Layer Guide
 
 ## What Is the Semantic Layer?
@@ -9930,6 +10612,9 @@ If **no datamarts exist**, tell the user they need to create one in the **Databr
 
 If **no datasources exist either**, the user must first connect their database in the **Databrain UI**.
 
+**For a v2 semantic model**
+If the datamart uses v2, inspect the question's entities with \`search_semantic_model\` and \`get_semantic_entity\`. Then continue to Step 2. If metadata needs correction, use \`propose_semantic_change\`, evaluate its source with \`eval_semantic_model\`, and show the plan. Only apply the reviewed source and expected hash through \`apply_semantic_change\` after the user supplies \`APPLY_TO_PRODUCTION\`. Never use the legacy \`update_semantic_layer\` steps below for v2.
+
 **Step 1b \u2014 Verify the Semantic Layer**
 After confirming a datamart exists, use \`get_semantic_layer\` to check its tables. The semantic layer is built on the **datamart** (not the raw datasource) \u2014 do NOT use \`discover_datasource_schema\` to populate it.
 
@@ -10011,6 +10696,15 @@ If the confidence is low or results seem wrong:
 // src/prompts/populate-semantic-layer.ts
 var populateSemanticLayerPrompt = `You are helping the user populate the semantic layer for a Databrain datamart. The semantic layer provides table/column descriptions, synonyms, and context that the AI needs to convert natural language questions into accurate SQL.
 
+**For a v2 semantic model**
+If \`list_datamarts\` reports \`semanticLayerVersion: "v2"\`, or the selected datamart is already known to use v2, use this workflow instead of the legacy steps below:
+1. Inspect relevant entities with \`search_semantic_model\` and \`get_semantic_entity\`, using the datamart ID.
+2. Call \`propose_semantic_change\` with a YAML patch or structured change. Show its errors and plan. Correct errors before continuing.
+3. Call \`eval_semantic_model\` with the returned source. Show the verdicts and let the user review the candidate.
+4. Stop for the user's explicit \`APPLY_TO_PRODUCTION\` confirmation. Never supply it yourself.
+5. Call \`apply_semantic_change\` with the exact reviewed source, its \`expected_content_hash\`, \`dry_run: false\` and the user's confirmation. A conflict requires a new proposal and review.
+6. Call \`get_semantic_entity\` and inspect the changed entity. Do not call \`update_semantic_layer\` for a v2 model.
+
 **Why this matters:** Without a populated semantic layer, \`ask_question\` cannot generate SQL \u2014 every query will fail with "out of context." Populating the semantic layer is the critical step between having a datamart and being able to query it.
 
 **Step 1 \u2014 Identify the Datamart**
@@ -10372,27 +11066,28 @@ function registerAllPrompts(server) {
 }
 
 export {
-  oauthHttpsUrl,
-  oauthConfigSchema,
-  DatabrainApiError,
-  toolError,
-  toolSuccess,
-  logger,
-  MCP_SERVER_VERSION,
-  toolContext,
-  DatabrainClient,
   createServiceBundle,
   READ_ONLY,
+  WRITE_CREATE,
+  APPLY_TO_PRODUCTION_CONFIRMATION,
   CHART_URI,
   KPI_URI,
   APP_MIME,
+  rowsSchema,
   referenceSchema,
   viewSchema,
   pageSchema,
+  appMeta,
   enableChartApps,
   chartResult,
+  draftSchema,
+  PREVIEW_PATH,
+  RENDER_TYPES,
+  draftPage,
+  workspacesForDatamart,
+  saveDraftAsDashboard,
   registerAllTools,
   registerAllResources,
   registerAllPrompts
 };
-//# sourceMappingURL=chunk-7DS7OLWP.js.map
+//# sourceMappingURL=chunk-ERTAKB2H.js.map