yamchart 0.9.5 → 0.10.0

package/dist/{dev-GWXHBBWB.js → dev-LZ4YHNDJ.js}

@@ -1,7 +1,7 @@
 import {
   loadEnvFile,
   validateProject
-} from "./chunk-RMIDEBHD.js";
+} from "./chunk-S2CH4HUZ.js";
 import {
   box,
   detail,
@@ -12,31 +12,14 @@ import {
   spinner,
   success
 } from "./chunk-HJVVHYVN.js";
-import {
-  ChartSchema,
-  ConnectionSchema,
-  DashboardSchema,
-  EventSchema,
-  EventsFileSchema,
-  ProjectSchema,
-  ScheduleSchema,
-  SemanticQuerySchema,
-  deepMerge,
-  resolveProjectConfig
-} from "./chunk-RM6MNDVF.js";
 import {
   StreamingChatAgent,
   filterCatalogEntries
 } from "./chunk-ZMJPRNOA.js";
 import {
-  AuthDatabase,
-  generateOpaqueToken,
-  generateSessionToken,
-  hashPassword,
-  hashToken,
-  parseTtl,
-  verifyPassword
-} from "./chunk-DZVT6PHW.js";
+  createEmbedder,
+  createProviderForTask
+} from "./chunk-FN6R2LAC.js";
 import {
   BigQueryConnector,
   DuckDBConnector,
@@ -46,28 +29,56 @@ import {
   ReconnectingConnector,
   SQLiteConnector,
   SnowflakeConnector,
-  computePreviousPeriod,
+  buildSourceProfile,
   createTemplateContext,
-  expandCustomDateRange,
-  expandDatePreset,
-  expandRelativeDateRange,
-  formatPeriodLabel,
-  isCustomDateRange,
-  isDatePreset,
-  isRelativeDateRange,
+  isReadOnlySql,
   parseModelMetadata,
   renderTemplate,
   resolveBigQueryAuth,
   resolveMySQLAuth,
   resolvePostgresAuth,
   resolveSnowflakeAuth
-} from "./chunk-S7YQXEKM.js";
+} from "./chunk-QUIDZO5G.js";
 import {
   SemanticModelBuilder,
   SemanticQueryCompiler,
   SemanticValidationError,
+  buildSemanticLayer,
+  compileMetricQuery,
+  computePreviousPeriod,
+  expandCustomDateRange,
+  expandDatePreset,
+  expandRelativeDateRange,
+  formatPeriodLabel,
+  isCustomDateRange,
+  isDatePreset,
+  isRelativeDateRange,
+  loadSemanticDefinitions,
   validateSemanticQuery
-} from "./chunk-UND73EOB.js";
+} from "./chunk-UFDQ3C7Q.js";
+import {
+  ChartSchema,
+  ConnectionSchema,
+  DashboardSchema,
+  EventSchema,
+  EventsFileSchema,
+  NewBlindspotSchema,
+  ProjectSchema,
+  ScheduleSchema,
+  SemanticQuerySchema,
+  deepMerge,
+  resolveProjectConfig
+} from "./chunk-ZIY22VO7.js";
+import "./chunk-QJ5CPQJK.js";
+import {
+  AuthDatabase,
+  generateOpaqueToken,
+  generateSessionToken,
+  hashPassword,
+  hashToken,
+  parseTtl,
+  verifyPassword
+} from "./chunk-DZVT6PHW.js";
 import {
   __commonJS,
   __toESM
@@ -2230,14 +2241,14 @@ var require_resolve = __commonJS({
       "enum",
       "const"
     ]);
-    function inlineRef(schema, limit = true) {
+    function inlineRef(schema, limit2 = true) {
       if (typeof schema == "boolean")
         return true;
-      if (limit === true)
+      if (limit2 === true)
         return !hasRef(schema);
-      if (!limit)
+      if (!limit2)
         return false;
-      return countKeys(schema) <= limit;
+      return countKeys(schema) <= limit2;
     }
     exports.inlineRef = inlineRef;
     var REF_KEYWORDS = /* @__PURE__ */ new Set([
@@ -7762,7 +7773,7 @@ var QueryService = class {
   async executeRawSql(sql) {
     return this.connector.execute(sql);
   }
-  async executeModel(modelName, params, userContext, limit = 1e3, filters) {
+  async executeModel(modelName, params, userContext, limit2 = 1e3, filters) {
     const model = this.models.get(modelName);
     if (!model) {
       throw new Error(`Unknown model: ${modelName}`);
@@ -7771,9 +7782,9 @@ var QueryService = class {
     let sql = renderTemplate(model.sql, context);
     if (filters && Object.keys(filters).length > 0) {
       const clauses = Object.entries(filters).map(([field, value]) => `${field} = '${value.replace(/'/g, "''")}'`);
-      sql = `SELECT * FROM (${sql}) _detail WHERE ${clauses.join(" AND ")} LIMIT ${limit}`;
+      sql = `SELECT * FROM (${sql}) _detail WHERE ${clauses.join(" AND ")} LIMIT ${limit2}`;
     } else {
-      sql = `SELECT * FROM (${sql}) _detail LIMIT ${limit}`;
+      sql = `SELECT * FROM (${sql}) _detail LIMIT ${limit2}`;
     }
     return this.connector.execute(sql);
   }
@@ -8820,8 +8831,8 @@ async function semanticRoutes(fastify, options) {
       });
     }
     const { writeFileSync, mkdirSync } = await import("fs");
-    const { join: join11, dirname: dirname3 } = await import("path");
-    const fullPath = join11(projectDir, filePath);
+    const { join: join12, dirname: dirname3 } = await import("path");
+    const fullPath = join12(projectDir, filePath);
     mkdirSync(dirname3(fullPath), { recursive: true });
     writeFileSync(fullPath, sql, "utf-8");
     return { saved: true, path: filePath };
@@ -9179,6 +9190,292 @@ var GitService = class {
   }
 };
 
+// ../../packages/knowledge/dist/memory-store.js
+import { randomUUID } from "crypto";
+
+// ../../packages/knowledge/dist/postgres-store.js
+import { randomUUID as randomUUID2 } from "crypto";
+import pg from "pg";
+
+// ../../packages/knowledge/dist/migrations.js
+var MIGRATIONS = [
+  `CREATE TABLE IF NOT EXISTS source_profiles (
+     connection TEXT PRIMARY KEY,
+     profiled_at TIMESTAMPTZ NOT NULL,
+     profile JSONB NOT NULL
+   );`,
+  `CREATE TABLE IF NOT EXISTS hunches (
+     id TEXT PRIMARY KEY,
+     connection TEXT NOT NULL,
+     question TEXT NOT NULL,
+     sql TEXT NOT NULL,
+     generated_sql TEXT NOT NULL,
+     status TEXT NOT NULL DEFAULT 'pending',
+     tables_used JSONB NOT NULL DEFAULT '[]',
+     rationale TEXT,
+     confidence DOUBLE PRECISION,
+     last_run_sample JSONB,
+     created_at TIMESTAMPTZ NOT NULL,
+     updated_at TIMESTAMPTZ NOT NULL
+   );`,
+  `CREATE INDEX IF NOT EXISTS hunches_conn_status ON hunches (connection, status);`,
+  `CREATE TABLE IF NOT EXISTS blindspots (
+     id TEXT PRIMARY KEY, connection TEXT NOT NULL, kind TEXT NOT NULL,
+     title TEXT NOT NULL, detail TEXT NOT NULL, subject TEXT,
+     suggested_model JSONB, confidence DOUBLE PRECISION,
+     status TEXT NOT NULL DEFAULT 'open', answer TEXT,
+     created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL
+   );`,
+  `CREATE INDEX IF NOT EXISTS blindspots_conn_status ON blindspots (connection, status);`,
+  `CREATE TABLE IF NOT EXISTS knowledge_docs (
+   id TEXT PRIMARY KEY, connection TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL,
+   source TEXT NOT NULL DEFAULT 'ui', created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL
+ );`,
+  `CREATE INDEX IF NOT EXISTS knowledge_docs_conn ON knowledge_docs (connection);`,
+  `CREATE TABLE IF NOT EXISTS knowledge_embeddings (
+   id TEXT PRIMARY KEY, connection TEXT NOT NULL, source_kind TEXT NOT NULL, source_id TEXT NOT NULL,
+   text TEXT NOT NULL, vector JSONB NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+   UNIQUE (source_kind, source_id)
+ );`,
+  `CREATE INDEX IF NOT EXISTS knowledge_embeddings_conn ON knowledge_embeddings (connection);`
+];
+
+// ../../packages/knowledge/dist/postgres-store.js
+function rowToBlindspot(r) {
+  return {
+    id: r.id,
+    connection: r.connection,
+    kind: r.kind,
+    title: r.title,
+    detail: r.detail,
+    subject: r.subject ?? void 0,
+    suggestedModel: r.suggested_model ?? void 0,
+    confidence: r.confidence ?? void 0,
+    status: r.status,
+    answer: r.answer ?? void 0,
+    createdAt: new Date(r.created_at).toISOString(),
+    updatedAt: new Date(r.updated_at).toISOString()
+  };
+}
+function rowToKnowledgeDoc(r) {
+  return {
+    id: r.id,
+    connection: r.connection,
+    title: r.title,
+    content: r.content,
+    source: r.source,
+    createdAt: new Date(r.created_at).toISOString(),
+    updatedAt: new Date(r.updated_at).toISOString()
+  };
+}
+function rowToHunch(r) {
+  return {
+    id: r.id,
+    connection: r.connection,
+    question: r.question,
+    sql: r.sql,
+    generatedSql: r.generated_sql,
+    status: r.status,
+    tablesUsed: r.tables_used ?? [],
+    rationale: r.rationale ?? void 0,
+    confidence: r.confidence ?? void 0,
+    lastRunSample: r.last_run_sample ?? void 0,
+    createdAt: new Date(r.created_at).toISOString(),
+    updatedAt: new Date(r.updated_at).toISOString()
+  };
+}
+var PostgresKnowledgeStore = class {
+  pool;
+  constructor(connectionString) {
+    this.pool = new pg.Pool({ connectionString });
+  }
+  async init() {
+    for (const m of MIGRATIONS)
+      await this.pool.query(m);
+  }
+  async saveProfile(connection, profile) {
+    await this.pool.query(`INSERT INTO source_profiles (connection, profiled_at, profile) VALUES ($1,$2,$3)
+       ON CONFLICT (connection) DO UPDATE SET profiled_at = EXCLUDED.profiled_at, profile = EXCLUDED.profile`, [connection, profile.profiledAt, JSON.stringify(profile)]);
+  }
+  async getProfile(connection) {
+    const { rows } = await this.pool.query(`SELECT profile FROM source_profiles WHERE connection = $1`, [connection]);
+    return rows[0]?.profile;
+  }
+  async createHunches(items) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const out = [];
+    for (const it of items) {
+      const id = randomUUID2();
+      const { rows } = await this.pool.query(`INSERT INTO hunches (id, connection, question, sql, generated_sql, status, tables_used, rationale, confidence, created_at, updated_at)
+         VALUES ($1,$2,$3,$4,$5,'pending',$6,$7,$8,$9,$9) RETURNING *`, [id, it.connection, it.question, it.sql, it.generatedSql, JSON.stringify(it.tablesUsed ?? []), it.rationale ?? null, it.confidence ?? null, now]);
+      out.push(rowToHunch(rows[0]));
+    }
+    return out;
+  }
+  async listHunches(filter) {
+    const clauses = [];
+    const params = [];
+    if (filter.connection) {
+      params.push(filter.connection);
+      clauses.push(`connection = $${params.length}`);
+    }
+    if (filter.status) {
+      params.push(filter.status);
+      clauses.push(`status = $${params.length}`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const { rows } = await this.pool.query(`SELECT * FROM hunches ${where} ORDER BY created_at DESC`, params);
+    return rows.map(rowToHunch);
+  }
+  async getHunch(id) {
+    const { rows } = await this.pool.query(`SELECT * FROM hunches WHERE id = $1`, [id]);
+    return rows[0] ? rowToHunch(rows[0]) : void 0;
+  }
+  async updateHunch(id, patch) {
+    const sets = [];
+    const params = [];
+    if (patch.sql !== void 0) {
+      params.push(patch.sql);
+      sets.push(`sql = $${params.length}`);
+    }
+    if (patch.status !== void 0) {
+      params.push(patch.status);
+      sets.push(`status = $${params.length}`);
+    }
+    if (patch.lastRunSample !== void 0) {
+      params.push(JSON.stringify(patch.lastRunSample));
+      sets.push(`last_run_sample = $${params.length}`);
+    }
+    params.push((/* @__PURE__ */ new Date()).toISOString());
+    sets.push(`updated_at = $${params.length}`);
+    params.push(id);
+    const { rows } = await this.pool.query(`UPDATE hunches SET ${sets.join(", ")} WHERE id = $${params.length} RETURNING *`, params);
+    if (!rows[0])
+      throw new Error(`Hunch "${id}" not found.`);
+    return rowToHunch(rows[0]);
+  }
+  async createBlindspots(items) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const out = [];
+    for (const it of items) {
+      const id = randomUUID2();
+      const { rows } = await this.pool.query(`INSERT INTO blindspots (id, connection, kind, title, detail, subject, suggested_model, confidence, status, created_at, updated_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'open',$9,$9) RETURNING *`, [id, it.connection, it.kind, it.title, it.detail, it.subject ?? null, JSON.stringify(it.suggestedModel ?? null), it.confidence ?? null, now]);
+      out.push(rowToBlindspot(rows[0]));
+    }
+    return out;
+  }
+  async listBlindspots(filter) {
+    const clauses = [];
+    const params = [];
+    if (filter.connection) {
+      params.push(filter.connection);
+      clauses.push(`connection = $${params.length}`);
+    }
+    if (filter.status) {
+      params.push(filter.status);
+      clauses.push(`status = $${params.length}`);
+    }
+    if (filter.kind) {
+      params.push(filter.kind);
+      clauses.push(`kind = $${params.length}`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const { rows } = await this.pool.query(`SELECT * FROM blindspots ${where} ORDER BY created_at DESC`, params);
+    return rows.map(rowToBlindspot);
+  }
+  async getBlindspot(id) {
+    const { rows } = await this.pool.query(`SELECT * FROM blindspots WHERE id = $1`, [id]);
+    return rows[0] ? rowToBlindspot(rows[0]) : void 0;
+  }
+  async updateBlindspot(id, patch) {
+    const sets = [];
+    const params = [];
+    if (patch.status !== void 0) {
+      params.push(patch.status);
+      sets.push(`status = $${params.length}`);
+    }
+    if (patch.answer !== void 0) {
+      params.push(patch.answer);
+      sets.push(`answer = $${params.length}`);
+    }
+    params.push((/* @__PURE__ */ new Date()).toISOString());
+    sets.push(`updated_at = $${params.length}`);
+    params.push(id);
+    const { rows } = await this.pool.query(`UPDATE blindspots SET ${sets.join(", ")} WHERE id = $${params.length} RETURNING *`, params);
+    if (!rows[0])
+      throw new Error(`Blindspot "${id}" not found.`);
+    return rowToBlindspot(rows[0]);
+  }
+  async deleteOpenBlindspots(connection) {
+    await this.pool.query(`DELETE FROM blindspots WHERE connection = $1 AND status = 'open'`, [connection]);
+  }
+  async createKnowledgeDoc(doc) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const id = randomUUID2();
+    const { rows } = await this.pool.query(`INSERT INTO knowledge_docs (id, connection, title, content, source, created_at, updated_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$6) RETURNING *`, [id, doc.connection, doc.title, doc.content, doc.source, now]);
+    return [rowToKnowledgeDoc(rows[0])];
+  }
+  async listKnowledgeDocs(filter) {
+    const clauses = [];
+    const params = [];
+    if (filter.connection) {
+      params.push(filter.connection);
+      clauses.push(`connection = $${params.length}`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const { rows } = await this.pool.query(`SELECT * FROM knowledge_docs ${where} ORDER BY created_at DESC`, params);
+    return rows.map(rowToKnowledgeDoc);
+  }
+  async updateKnowledgeDoc(id, patch) {
+    const sets = [];
+    const params = [];
+    if (patch.title !== void 0) {
+      params.push(patch.title);
+      sets.push(`title = $${params.length}`);
+    }
+    if (patch.content !== void 0) {
+      params.push(patch.content);
+      sets.push(`content = $${params.length}`);
+    }
+    params.push((/* @__PURE__ */ new Date()).toISOString());
+    sets.push(`updated_at = $${params.length}`);
+    params.push(id);
+    const { rows } = await this.pool.query(`UPDATE knowledge_docs SET ${sets.join(", ")} WHERE id = $${params.length} RETURNING *`, params);
+    if (!rows[0])
+      throw new Error(`KnowledgeDoc "${id}" not found.`);
+    return rowToKnowledgeDoc(rows[0]);
+  }
+  async deleteKnowledgeDoc(id) {
+    await this.pool.query(`DELETE FROM knowledge_docs WHERE id = $1`, [id]);
+  }
+  async upsertEmbedding(e) {
+    const id = `${e.source_kind}:${e.source_id}`;
+    await this.pool.query(`INSERT INTO knowledge_embeddings (id, connection, source_kind, source_id, text, vector, updated_at)
+       VALUES ($1,$2,$3,$4,$5,$6,now())
+       ON CONFLICT (source_kind, source_id) DO UPDATE SET text=EXCLUDED.text, vector=EXCLUDED.vector, updated_at=now()`, [id, e.connection, e.source_kind, e.source_id, e.text, JSON.stringify(e.vector)]);
+  }
+  async listEmbeddings(filter) {
+    const clauses = [];
+    const params = [];
+    if (filter.connection) {
+      params.push(filter.connection);
+      clauses.push(`connection = $${params.length}`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const { rows } = await this.pool.query(`SELECT * FROM knowledge_embeddings ${where}`, params);
+    return rows.map((r) => ({ id: r.id, connection: r.connection, source_kind: r.source_kind, source_id: r.source_id, text: r.text, vector: r.vector }));
+  }
+  async getEmbedding(source_kind, source_id) {
+    const { rows } = await this.pool.query(`SELECT * FROM knowledge_embeddings WHERE source_kind = $1 AND source_id = $2`, [source_kind, source_id]);
+    if (!rows[0])
+      return void 0;
+    const r = rows[0];
+    return { id: r.id, connection: r.connection, source_kind: r.source_kind, source_id: r.source_id, text: r.text, vector: r.vector };
+  }
+};
+
 // ../../node_modules/.pnpm/tslib@2.8.1/node_modules/tslib/tslib.es6.mjs
 function __rest(s, e) {
   var t = {};
@@ -11868,8 +12165,8 @@ var RealtimeChannel = class _RealtimeChannel {
   _trigger(type, payload, ref) {
     var _a, _b;
     const typeLower = type.toLocaleLowerCase();
-    const { close, error: error2, leave, join: join11 } = CHANNEL_EVENTS;
-    const events = [close, error2, leave, join11];
+    const { close, error: error2, leave, join: join12 } = CHANNEL_EVENTS;
+    const events = [close, error2, leave, join12];
     if (ref && events.indexOf(typeLower) >= 0 && ref !== this._joinRef()) {
       return;
     }
@@ -21429,7 +21726,7 @@ async function chatRoutes(fastify, options) {
         systemParts.push("Output ONLY the new text to insert. Do NOT repeat the existing content.");
       }
       const systemPrompt = systemParts.join("\n");
-      const { AnthropicProvider } = await import("./dist-MNXSMGV6.js");
+      const { AnthropicProvider } = await import("./dist-5IFWLWND.js");
       const provider = new AnthropicProvider(apiKey);
       const response = await provider.chat({
         system: systemPrompt,
@@ -28527,8 +28824,8 @@ async function runSql(deps, args) {
   if (DESTRUCTIVE.test(sql) || /^\s*WITH\b/i.test(sql) && WRITABLE_CTE.test(sql)) {
     return "Error: Destructive SQL statements are not allowed through the MCP.";
   }
-  const limit = args.limit ?? DEFAULT_LIMIT;
-  const limited = /\blimit\b/i.test(sql) ? sql : `${sql.replace(/;\s*$/, "")} LIMIT ${limit}`;
+  const limit2 = args.limit ?? DEFAULT_LIMIT;
+  const limited = /\blimit\b/i.test(sql) ? sql : `${sql.replace(/;\s*$/, "")} LIMIT ${limit2}`;
   const result = await deps.queryService.executeRawSql(limited);
   return JSON.stringify({ columns: result.columns, rows: result.rows });
 }
@@ -28584,8 +28881,9 @@ async function listTables(deps) {
   })));
 }
 async function describeTable(deps, args) {
-  const parts = args.table.split(".");
-  const tableName = parts[parts.length - 1] ?? args.table;
+  const normalizedTable = args.schema != null && !args.table.includes(".") ? `${args.schema}.${args.table}` : args.table;
+  const parts = normalizedTable.split(".");
+  const tableName = parts[parts.length - 1] ?? normalizedTable;
   const schema = parts.length > 1 ? parts.slice(0, -1).join(".") : void 0;
   const tables = await readCatalogTables(deps.projectDir, includeFilter(deps));
   const match = tables.find((t) => t.name === tableName && (schema === void 0 || t.schema === schema));
@@ -28603,14 +28901,14 @@ async function sampleTable(deps, args) {
   if (!TABLE_IDENT.test(args.table)) {
     return `Error: Invalid table identifier "${args.table}".`;
   }
-  const limit = Math.min(Math.max(args.limit ?? 5, 1), 100);
+  const limit2 = Math.min(Math.max(args.limit ?? 5, 1), 100);
   const parts = args.table.split(".");
   const tableName = parts[parts.length - 1] ?? args.table;
   const providedSchema = parts.length > 1 ? parts.slice(0, -1).join(".") : void 0;
   const tables = await readCatalogTables(deps.projectDir, includeFilter(deps));
   const match = tables.find((t) => t.name === tableName && (providedSchema === void 0 || t.schema === providedSchema));
   const from = providedSchema === void 0 && match?.schema ? `${match.schema}.${args.table}` : args.table;
-  const result = await deps.queryService.executeRawSql(`SELECT * FROM ${from} LIMIT ${limit}`);
+  const result = await deps.queryService.executeRawSql(`SELECT * FROM ${from} LIMIT ${limit2}`);
   return JSON.stringify({ columns: result.columns, rows: result.rows });
 }
 
@@ -28691,11 +28989,40 @@ function renderChartToPng(option, opts = {}) {
   return Buffer.from(resvg.render().asPng());
 }
 
+// ../../packages/mcp-core/dist/chart-errors.js
+function flattenIssues(issues) {
+  const flat = [];
+  for (const issue of issues) {
+    if (issue.code === "invalid_union" && issue.unionErrors?.length) {
+      const typeMatchMember = issue.unionErrors.find((e) => !e.issues.some((i) => i.path.length >= 2 && i.path[i.path.length - 1] === "type" && i.code === "invalid_literal"));
+      const best = typeMatchMember ?? issue.unionErrors.reduce((a, b) => a.issues.length <= b.issues.length ? a : b);
+      flat.push(...flattenIssues(best.issues));
+    } else {
+      const path = issue.path.length ? issue.path.join(".") : "(root)";
+      let detail2 = issue.message;
+      if (/expected object, received string/i.test(issue.message)) {
+        detail2 = `expected an object like { field: "<column>", type: "temporal|quantitative|ordinal|nominal" }, received a string`;
+      }
+      flat.push({ path, message: detail2 });
+    }
+  }
+  return flat;
+}
+function formatChartErrors(error2) {
+  const issues = flattenIssues(error2.issues);
+  const lines = issues.map((i) => `  \u2022 ${i.path}: ${i.message}`);
+  return [
+    "Invalid chart spec:",
+    ...lines,
+    "Tip: call get_chart_schema (optionally with { type }) for the exact shape and a working example."
+  ].join("\n");
+}
+
 // ../../packages/mcp-core/dist/tools/visualize.js
 async function visualize(_deps, args) {
   const parsed = ChartSchema.safeParse(args.spec);
   if (!parsed.success) {
-    return { error: `Invalid chart spec: ${parsed.error.issues.map((i) => i.message).join("; ")}` };
+    return { error: formatChartErrors(parsed.error) };
   }
   try {
     const option = buildEChartsOption(parsed.data, args.data ?? []);
@@ -28722,7 +29049,7 @@ async function saveChart(deps, args) {
   }
   const parsed = ChartSchema.safeParse(args.spec);
   if (!parsed.success) {
-    return `Error: Invalid chart spec: ${parsed.error.issues.map((i) => i.message).join("; ")}`;
+    return `Error: ${formatChartErrors(parsed.error)}`;
   }
   const name = parsed.data.name;
   if (!SAFE_NAME.test(name)) {
@@ -28738,6 +29065,450 @@ async function saveChart(deps, args) {
   return `Chart "${name}" saved to charts/${name}.yaml`;
 }
 
+// ../../packages/mcp-core/dist/suggested-chart.js
+function suggestChart(input) {
+  const { name, title, metrics, timeDimension, dimensions } = input;
+  const primary = metrics[0] ?? { name: "value", format: void 0 };
+  if (dimensions.length === 0) {
+    return {
+      name,
+      title,
+      chart: {
+        type: "kpi",
+        value: { field: primary.name },
+        // KpiFormatSchema requires `type` — always include it.
+        format: primary.format?.includes("$") ? { type: "currency", currency: "USD", decimals: 0 } : { type: "number" }
+      }
+    };
+  }
+  const groupField = dimensions[0] ?? "dimension";
+  const isTime = timeDimension && dimensions.includes(timeDimension);
+  return {
+    name,
+    title,
+    chart: {
+      type: "bar",
+      x: { field: groupField, type: isTime ? "temporal" : "nominal" },
+      y: {
+        field: primary.name,
+        type: "quantitative",
+        label: primary.name,
+        ...primary.format ? { format: primary.format } : {}
+      }
+    }
+  };
+}
+
+// ../../packages/mcp-core/dist/tools/semantic.js
+function listMetrics(deps) {
+  return JSON.stringify(deps.semanticLayer.listMetrics(), null, 2);
+}
+function getMetric(deps, args) {
+  const resolved = deps.semanticLayer.resolveMetric(args.name);
+  if (!resolved) {
+    return JSON.stringify({ error: `Unknown metric "${args.name}". Call list_metrics to see governed metrics.` });
+  }
+  const { metric, entity } = resolved;
+  return JSON.stringify({
+    name: metric.name,
+    label: metric.label,
+    description: metric.description,
+    entity: entity.name,
+    source: entity.sourceRef,
+    agg: metric.agg,
+    field: metric.field,
+    sql: metric.sql,
+    filter: metric.filter,
+    filter_sql: metric.filter ? entity.filters[metric.filter]?.sql : void 0,
+    synonyms: metric.synonyms ?? [],
+    format: metric.format,
+    dimensions: entity.dimensions,
+    time_dimension: entity.timeDimension
+  }, null, 2);
+}
+async function queryMetric(deps, args) {
+  const resolved = args.metrics.map((m) => {
+    const r = deps.semanticLayer.resolveMetric(m);
+    if (!r)
+      throw new Error(`Unknown metric "${m}". Call list_metrics.`);
+    return r;
+  });
+  if (resolved.length === 0) {
+    return JSON.stringify({ error: "At least one metric is required." });
+  }
+  const entity = resolved[0].entity;
+  if (resolved.some((r) => r.entity.name !== entity.name)) {
+    return JSON.stringify({
+      error: `Metrics span multiple entities (${[...new Set(resolved.map((r) => r.entity.name))].join(", ")}). Query one entity at a time in Phase 1.`
+    });
+  }
+  const canonicalMetrics = resolved.map((r) => r.metric.name);
+  const { sql, metrics } = compileMetricQuery(entity, { ...args, metrics: canonicalMetrics }, deps.connectionType);
+  const result = await deps.queryService.executeRawSql(sql);
+  const explicitDimensions = args.dimensions ?? [];
+  const effectiveDimensions = args.grain && entity.timeDimension && !explicitDimensions.includes(entity.timeDimension) ? [entity.timeDimension, ...explicitDimensions] : explicitDimensions;
+  const suggested_chart = suggestChart({
+    name: `metric_${canonicalMetrics.join("_")}`.slice(0, 60),
+    title: metrics.map((m) => m.label ?? m.name).join(", "),
+    metrics: metrics.map((m) => ({ name: m.name, format: m.format })),
+    timeDimension: entity.timeDimension,
+    dimensions: effectiveDimensions
+  });
+  return JSON.stringify({ columns: result.columns, rows: result.rows, sql, suggested_chart }, null, 2);
+}
+
+// ../../packages/mcp-core/dist/tools/chart-dx.js
+var EXAMPLES = {
+  bar: {
+    name: "revenue_by_month",
+    title: "Revenue by Month",
+    source: { model: "monthly_revenue" },
+    chart: {
+      type: "bar",
+      x: { field: "month", type: "temporal" },
+      y: { field: "invoiced_revenue", type: "quantitative", format: "$,.0f" }
+    }
+  },
+  line: {
+    name: "revenue_trend",
+    title: "Revenue Trend",
+    source: { model: "monthly_revenue" },
+    chart: {
+      type: "line",
+      x: { field: "month", type: "temporal" },
+      y: { field: "invoiced_revenue", type: "quantitative" }
+    }
+  },
+  area: {
+    name: "revenue_area",
+    title: "Revenue Area",
+    source: { model: "monthly_revenue" },
+    chart: {
+      type: "area",
+      x: { field: "month", type: "temporal" },
+      y: { field: "invoiced_revenue", type: "quantitative" }
+    }
+  },
+  kpi: {
+    name: "total_revenue",
+    title: "Total Revenue",
+    source: { model: "total_revenue" },
+    chart: {
+      type: "kpi",
+      value: { field: "total_revenue" },
+      format: { type: "currency", currency: "USD", decimals: 0 }
+    }
+  },
+  pie: {
+    name: "revenue_by_category",
+    title: "Revenue by Category",
+    source: { model: "category_revenue" },
+    chart: {
+      type: "pie",
+      x: { field: "category", type: "nominal" },
+      y: { field: "revenue", type: "quantitative" }
+    }
+  },
+  scatter: {
+    name: "jobs_scatter",
+    title: "Jobs Scatter",
+    source: { model: "jobs" },
+    chart: {
+      type: "scatter",
+      x: { field: "cost", type: "quantitative" },
+      y: { field: "revenue", type: "quantitative" }
+    }
+  },
+  table: {
+    name: "jobs_table",
+    title: "Jobs Table",
+    source: { model: "jobs" },
+    chart: {
+      type: "table",
+      columns: [
+        { field: "job_id", label: "Job ID" },
+        { field: "revenue", label: "Revenue", format: "$,.0f" }
+      ]
+    }
+  }
+};
+function getChartSchema(args) {
+  const type = args.type != null && EXAMPLES[args.type] != null ? args.type : "bar";
+  return JSON.stringify({
+    note: "Axes are objects: { field, type: temporal|quantitative|ordinal|nominal }. source is { model } or { sql }.",
+    available_examples: Object.keys(EXAMPLES),
+    example: EXAMPLES[type]
+  }, null, 2);
+}
+function validateChart(args) {
+  const parsed = ChartSchema.safeParse(args.spec);
+  if (parsed.success)
+    return JSON.stringify({ valid: true });
+  return JSON.stringify({ valid: false, errors: formatChartErrors(parsed.error) });
+}
+function getChartSpec(deps, args) {
+  const spec = deps.configLoader.getChartByName(args.name);
+  if (spec == null) {
+    return JSON.stringify({ error: `Chart "${args.name}" not found. Call list_charts to see available charts.` });
+  }
+  return JSON.stringify(spec, null, 2);
+}
+
+// ../../packages/learning/dist/prompt.js
+function buildGenerationPrompt(profile, metricNames, count, contextBlock = "") {
+  const tables = profile.tables.map((t) => {
+    const cols = t.columns.map((c) => {
+      const top = c.topValues?.length ? ` top:[${c.topValues.slice(0, 6).map((v) => JSON.stringify(v.value)).join(", ")}]` : "";
+      const dist = c.distinctCount != null ? ` distinct:${c.distinctCount}` : "";
+      return `    - ${c.name} (${c.type})${dist}${top}`;
+    }).join("\n");
+    return `  ${t.table} (${t.rowCount ?? "?"} rows):
+${cols}`;
+  }).join("\n");
+  return [
+    `You are profiling a data warehouse to propose ${count} useful business questions a user would ask, each with correct read-only SQL.`,
+    contextBlock ? `Known business context:
+${contextBlock}` : "",
+    metricNames.length ? `Prefer these governed metrics when relevant: ${metricNames.join(", ")}.` : "",
+    `Use the ACTUAL column values shown (e.g. status values) \u2014 do not invent values.`,
+    `Tables and profiled columns:`,
+    tables,
+    `Respond with ONLY JSON: {"hunches":[{"question":string,"sql":string,"tablesUsed":string[],"confidence":number,"rationale":string}]}. SQL must be a single read-only SELECT.`
+  ].filter(Boolean).join("\n");
+}
+
+// ../../packages/learning/dist/json.js
+function extractJson(text2) {
+  const start = text2.indexOf("{");
+  if (start === -1)
+    return {};
+  let depth = 0;
+  for (let i = start; i < text2.length; i++) {
+    if (text2[i] === "{")
+      depth++;
+    else if (text2[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        try {
+          return JSON.parse(text2.slice(start, i + 1));
+        } catch {
+          return {};
+        }
+      }
+    }
+  }
+  return {};
+}
+
+// ../../packages/learning/dist/generator.js
+async function generateHunches(input) {
+  const count = input.count ?? 20;
+  const prompt = buildGenerationPrompt(input.profile, input.metricNames, count, input.contextBlock ?? "");
+  const res = await input.provider.chat({ system: "You generate governed analytics questions and SQL.", messages: [{ role: "user", content: prompt }], tools: [], maxTokens: 4e3 });
+  const text2 = res.content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+  const parsed = extractJson(text2);
+  const raw = Array.isArray(parsed.hunches) ? parsed.hunches : [];
+  const hunches = [];
+  for (const r of raw) {
+    const sql = typeof r.sql === "string" ? r.sql : "";
+    const question = typeof r.question === "string" ? r.question : "";
+    if (!sql || !question || !isReadOnlySql(sql))
+      continue;
+    hunches.push({
+      connection: input.connection,
+      question,
+      sql,
+      generatedSql: sql,
+      tablesUsed: Array.isArray(r.tablesUsed) ? r.tablesUsed : [],
+      rationale: typeof r.rationale === "string" ? r.rationale : void 0,
+      confidence: typeof r.confidence === "number" ? r.confidence : void 0
+    });
+  }
+  return hunches;
+}
+
+// ../../packages/learning/dist/blindspot.js
+function buildBlindspotPrompt(profile, metricNames, contextBlock, modelGraph) {
+  const tables = profile.tables.map((t) => {
+    const cols = t.columns.map((c) => {
+      const top = c.topValues?.length ? ` values:[${c.topValues.slice(0, 6).map((v) => JSON.stringify(v.value)).join(", ")}]` : "";
+      return `    - ${c.name} (${c.type})${top}`;
+    }).join("\n");
+    return `  ${t.table}:
+${cols}`;
+  }).join("\n");
+  return [
+    `You are auditing a data warehouse to find where you LACK business context and where useful marts are missing.`,
+    contextBlock ? `Known business context:
+${contextBlock}` : "",
+    metricNames.length ? `Governed metrics: ${metricNames.join(", ")}.` : "",
+    modelGraph ? `Model lineage (raw \u2192 staging \u2192 marts):
+${modelGraph}` : "",
+    `Profiled tables:
+${tables}`,
+    `Return ONLY JSON: {"blindspots":[{"kind":"context","title":string,"detail":string,"subject":string,"confidence":number} | {"kind":"opportunity","title":string,"detail":string,"suggestedModel":{"name":string,"description":string,"rationale":string,"columns":[{"name":string,"description":string}]},"confidence":number}]}.`,
+    `"context" = an ambiguity you need explained to write correct SQL (use the ACTUAL values shown). "opportunity" = a useful mart that does not yet exist.`
+  ].filter(Boolean).join("\n\n");
+}
+async function scanBlindspots(input) {
+  const prompt = buildBlindspotPrompt(input.profile, input.metricNames, input.contextBlock, input.modelGraph);
+  const res = await input.provider.chat({ system: "You audit data warehouses for missing business context and missing marts.", messages: [{ role: "user", content: prompt }], tools: [], maxTokens: 4e3 });
+  const text2 = res.content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+  const parsed = extractJson(text2);
+  const raw = Array.isArray(parsed.blindspots) ? parsed.blindspots : [];
+  const items = [];
+  for (const r of raw) {
+    const candidate = { ...r, connection: input.connection };
+    const result = NewBlindspotSchema.safeParse(candidate);
+    if (result.success)
+      items.push(result.data);
+  }
+  return items;
+}
+
+// ../../packages/learning/dist/context.js
+import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync } from "fs";
+import { join as join9 } from "path";
+var MAX_DOC = 6e3;
+var MAX_TOTAL = 16e3;
+function loadKnowledgeDocs(projectDir) {
+  const dir = join9(projectDir, "knowledge");
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => /\.md$/i.test(f)).map((f) => readFileSync2(join9(dir, f), "utf8"));
+}
+function buildContextBlock(input) {
+  const parts = [];
+  for (const doc of input.docs) {
+    const d = doc.length > MAX_DOC ? doc.slice(0, MAX_DOC) + "\n\u2026(truncated)" : doc;
+    parts.push(d);
+  }
+  if (input.answeredBlindspots.length) {
+    parts.push("Confirmed business context (from answered questions):");
+    for (const a of input.answeredBlindspots)
+      parts.push(`- ${a.title}: ${a.answer}`);
+  }
+  let block = parts.join("\n\n").trim();
+  if (block.length > MAX_TOTAL)
+    block = block.slice(0, MAX_TOTAL) + "\n\u2026(truncated)";
+  return block;
+}
+
+// ../../packages/learning/dist/retrieval.js
+function cosineSimilarity(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0)
+    return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+async function retrieveGrounding(input) {
+  const { question, connection, store, embedder } = input;
+  const topK = input.topK ?? 5;
+  const corpus = [];
+  for (const h of await store.listHunches({ connection, status: "confirmed" }))
+    corpus.push({ kind: "hunch", id: h.id, text: h.question, payload: { sql: h.sql, title: h.question } });
+  for (const b of await store.listBlindspots({ connection, status: "answered" }))
+    if (b.answer)
+      corpus.push({ kind: "blindspot", id: b.id, text: `${b.title}: ${b.answer}`, payload: { title: b.title } });
+  for (const d of await store.listKnowledgeDocs({ connection }))
+    corpus.push({ kind: "knowledge", id: d.id, text: `${d.title}
+${d.content}`, payload: { title: d.title } });
+  if (corpus.length === 0)
+    return [];
+  const toEmbed = [];
+  const vectors = /* @__PURE__ */ new Map();
+  for (const item of corpus) {
+    const cached = await store.getEmbedding(item.kind, item.id);
+    if (cached && cached.text === item.text)
+      vectors.set(item.id, cached.vector);
+    else
+      toEmbed.push(item);
+  }
+  if (toEmbed.length) {
+    const embs = await embedder.embed(toEmbed.map((i) => i.text));
+    for (let i = 0; i < toEmbed.length; i++) {
+      const item = toEmbed[i];
+      const vec = embs[i];
+      vectors.set(item.id, vec);
+      await store.upsertEmbedding({ connection, source_kind: item.kind, source_id: item.id, text: item.text, vector: vec });
+    }
+  }
+  const [qVec] = await embedder.embed([question]);
+  const ranked = corpus.map((item) => ({ ...item, score: cosineSimilarity(qVec, vectors.get(item.id)) })).sort((a, b) => b.score - a.score).slice(0, topK);
+  return ranked.map((r) => ({ kind: r.kind, id: r.id, text: r.text, score: r.score, payload: r.payload }));
+}
+
+// ../../packages/learning/dist/answer.js
+function extractSql(text2) {
+  const fence = text2.match(/```(?:sql)?\s*([\s\S]*?)```/i);
+  return (fence ? fence[1] : text2).trim();
+}
+async function answerQuestion(input) {
+  const { question, connection, store, embedder, provider, executeRawSql } = input;
+  const reuseThreshold = input.reuseThreshold ?? 0.9;
+  const top = await retrieveGrounding({ question, connection, store, embedder, topK: 5 });
+  if (top.length === 0) {
+    return { question, mode: "none", message: "No governed knowledge yet for this source \u2014 confirm some Hunches first." };
+  }
+  const groundedOn = top.map((t) => ({ kind: t.kind, title: t.payload.title, score: t.score }));
+  const topHunch = top.find((t) => t.kind === "hunch");
+  if (topHunch && topHunch === top[0] && topHunch.score >= reuseThreshold && topHunch.payload.sql) {
+    try {
+      const res = await executeRawSql(limit(topHunch.payload.sql));
+      return { question, mode: "reused", sql: topHunch.payload.sql, columns: res.columns, rows: res.rows, groundedOn };
+    } catch (e) {
+      return { question, mode: "reused", sql: topHunch.payload.sql, groundedOn, message: `Query failed: ${e.message}` };
+    }
+  }
+  const examples = top.filter((t) => t.kind === "hunch" && t.payload.sql).map((t) => `Q: ${t.payload.title}
+SQL: ${t.payload.sql}`).join("\n\n");
+  const context = top.filter((t) => t.kind !== "hunch").map((t) => `- ${t.text}`).join("\n");
+  const prompt = [
+    `Write a single read-only SQL query that answers the question, using ONLY these trusted examples and business context.`,
+    examples ? `Trusted examples:
+${examples}` : "",
+    context ? `Business context:
+${context}` : "",
+    `Question: ${question}`,
+    `Respond with ONLY the SQL (a single SELECT).`
+  ].filter(Boolean).join("\n\n");
+  const resp = await provider.chat({ system: "You write governed, read-only analytics SQL grounded in trusted examples.", messages: [{ role: "user", content: prompt }], tools: [], maxTokens: 1e3 });
+  const text2 = resp.content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+  const sql = extractSql(text2);
+  if (!isReadOnlySql(sql)) {
+    return { question, mode: "generated", sql, groundedOn, message: "Generated SQL was not read-only; refusing to run it." };
+  }
+  try {
+    const res = await executeRawSql(limit(sql));
+    return { question, mode: "generated", sql, columns: res.columns, rows: res.rows, groundedOn };
+  } catch (e) {
+    return { question, mode: "generated", sql, groundedOn, message: `Query failed: ${e.message}` };
+  }
+}
+function limit(sql) {
+  return /\blimit\b/i.test(sql) ? sql : `${sql.replace(/;\s*$/, "")} LIMIT 1000`;
+}
+
+// ../../packages/mcp-core/dist/tools/answer.js
+async function answerQuestionTool(deps, args) {
+  const connection = args.connection ?? deps.defaultConnectionName ?? "default";
+  const result = await answerQuestion({
+    question: args.question,
+    connection,
+    store: deps.knowledgeStore,
+    embedder: deps.embedder,
+    provider: deps.provider,
+    executeRawSql: (sql) => deps.queryService.executeRawSql(sql),
+    connectionType: deps.connectionType
+  });
+  return JSON.stringify(result, null, 2);
+}
+
 // ../../packages/mcp-core/dist/render/embedResource.js
 import { createHash } from "crypto";
 import { createUIResource } from "@mcp-ui/server";
@@ -28845,7 +29616,10 @@ function createMcpServer(deps) {
     inputSchema: { sql: z2.string(), limit: z2.number().optional() }
   }, async (args) => text(await runSql(deps, args)));
   server.registerTool("list_tables", { description: "List warehouse tables from the cached catalog (name, schema, connection, column count).", inputSchema: {} }, async () => text(await listTables(deps)));
-  server.registerTool("describe_table", { description: "Show columns and types for a catalog table.", inputSchema: { table: z2.string() } }, async (args) => text(await describeTable(deps, args)));
+  server.registerTool("describe_table", {
+    description: 'Show columns and types for a catalog table. Accepts { table } (with optional dot-notation schema: "schema.table") or { table, schema } separately.',
+    inputSchema: { table: z2.string(), schema: z2.string().optional() }
+  }, async (args) => text(await describeTable(deps, args)));
   server.registerTool("sample_table", { description: "Return a few sample rows from a table.", inputSchema: { table: z2.string(), limit: z2.number().optional() } }, async (args) => text(await sampleTable(deps, args)));
   server.registerTool("visualize", {
     description: "Render a yamchart chart spec + data rows to an interactive chart (with a static image fallback). Provide a full chart spec (name, title, source.model, chart) and the data array.",
@@ -28873,6 +29647,66 @@ function createMcpServer(deps) {
     description: "Save a yamchart chart spec to charts/<name>.yaml (requires editor/admin).",
     inputSchema: { spec: z2.record(z2.unknown()) }
   }, async (args) => text(await saveChart(deps, args)));
+  if (deps.semanticLayer) {
+    const semanticLayer = deps.semanticLayer;
+    server.registerTool("list_metrics", {
+      description: "List governed business metrics (the semantic glossary): name, synonyms, the entity they belong to, and which dimensions you can slice them by. Prefer querying these by name over writing raw SQL.",
+      inputSchema: {}
+    }, async () => text(listMetrics({ semanticLayer })));
+    server.registerTool("get_metric", {
+      description: "Get the full governed definition of a metric (by name or synonym): how it is computed (aggregation, field/sql, governed filter), its source table, format, and the dimensions/time dimension you can group it by.",
+      inputSchema: { name: z2.string() }
+    }, async (args) => text(getMetric({ semanticLayer }, args)));
+    server.registerTool("query_metric", {
+      description: "Query governed metrics by name (or synonym), optionally sliced by dimensions and a time grain, and filtered by a time range. Returns the data rows, the generated SQL (for transparency), and a ready-to-use suggested_chart spec. Prefer this over run_sql for business questions about governed metrics \u2014 it guarantees correct, governed definitions.",
+      inputSchema: {
+        metrics: z2.array(z2.string()).min(1),
+        dimensions: z2.array(z2.string()).optional(),
+        grain: z2.enum(["day", "week", "month", "quarter", "year"]).optional(),
+        time_range: z2.union([
+          z2.object({ preset: z2.string() }),
+          z2.object({ start: z2.string(), end: z2.string() })
+        ]).optional(),
+        filters: z2.array(z2.object({ dimension: z2.string(), operator: z2.string(), value: z2.any() })).optional(),
+        order_by: z2.object({ field: z2.string(), direction: z2.enum(["asc", "desc"]).optional() }).optional(),
+        limit: z2.number().int().positive().max(1e4).optional()
+      }
+    }, async (args) => {
+      try {
+        return text(await queryMetric({ semanticLayer, queryService: deps.queryService, connectionType: deps.connectionType }, args));
+      } catch (err) {
+        return text(`Error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    });
+  }
+  if (deps.knowledgeStore && deps.embedder && deps.answerProvider) {
+    const knowledgeStore = deps.knowledgeStore;
+    const embedder = deps.embedder;
+    const answerProvider = deps.answerProvider;
+    server.registerTool("answer_question", {
+      description: 'Answer a business question using governed knowledge: retrieves confirmed Hunches + business context for the source and either reuses a matching SQL or generates SQL grounded in trusted examples. Prefer this for "how many / how much / which" questions.',
+      inputSchema: { question: z2.string(), connection: z2.string().optional() }
+    }, async (args) => text(await answerQuestionTool({
+      knowledgeStore,
+      embedder,
+      provider: answerProvider,
+      queryService: deps.queryService,
+      connectionType: deps.connectionType,
+      defaultConnectionName: deps.aiConnectionName
+    }, args)));
+  }
+  server.registerTool("get_chart_schema", {
+    description: "Get the exact yamchart chart spec shape and a working example for a chart type (bar, line, area, kpi, pie, scatter, table). Call this before building a chart. Axes are objects: { field, type: temporal|quantitative|ordinal|nominal }.",
+    inputSchema: { type: z2.string().optional() }
+  }, async (args) => text(getChartSchema(args)));
+  server.registerTool("validate_chart", {
+    description: "Validate a yamchart chart spec without saving it. Returns { valid: true } or field-level errors with hints so you can self-correct before calling save_chart or visualize.",
+    inputSchema: { spec: z2.record(z2.unknown()) }
+  }, async (args) => text(validateChart(args)));
+  server.registerTool("get_chart_spec", {
+    description: "Get the full saved spec of an existing governed chart by name (so you can copy or adapt it). Call list_charts to discover names.",
+    inputSchema: { name: z2.string() }
+  }, async (args) => text(getChartSpec({ configLoader: deps.configLoader }, args)));
   return server;
 }
 
@@ -28884,13 +29718,19 @@ function getUser(request) {
   return { id: user.id, email: user.email, role: user.role, attributes: user.attributes };
 }
 async function mcpRoutes(fastify, options) {
-  const { configLoader, queryService, projectDir } = options;
+  const { configLoader, queryService, projectDir, semanticLayer, connectionType, knowledgeStore, embedder, answerProvider, aiConnectionName } = options;
   fastify.post("/mcp", async (request, reply) => {
     const server = createMcpServer({
       configLoader,
       queryService,
       projectDir,
-      user: getUser(request)
+      user: getUser(request),
+      semanticLayer,
+      connectionType,
+      knowledgeStore,
+      embedder,
+      answerProvider,
+      aiConnectionName
     });
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
     reply.raw.on("close", () => {
@@ -28914,7 +29754,7 @@ async function mcpRoutes(fastify, options) {
 }
 
 // ../server/dist/routes/catalog.js
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 import { readFile as readFile5 } from "fs/promises";
 async function catalogRoutes(fastify, options) {
   const { configLoader, projectDir } = options;
@@ -28927,7 +29767,7 @@ async function catalogRoutes(fastify, options) {
       name: m.metadata.name,
       description: m.metadata.description
     }));
-    const catalogPath = join9(projectDir, ".yamchart", "catalog.json");
+    const catalogPath = join10(projectDir, ".yamchart", "catalog.json");
     let tables = [];
     try {
       const catalogData = JSON.parse(await readFile5(catalogPath, "utf-8"));
@@ -28963,8 +29803,310 @@ async function catalogRoutes(fastify, options) {
   });
 }
 
+// ../server/dist/routes/learning.js
+var ReadOnlySqlError = class extends Error {
+  constructor() {
+    super("Only read-only SELECT queries can be confirmed.");
+    this.name = "ReadOnlySqlError";
+  }
+};
+async function confirmHunch(deps, id, body) {
+  if (body.sql !== void 0 && !isReadOnlySql(body.sql)) {
+    throw new ReadOnlySqlError();
+  }
+  return deps.store.updateHunch(id, { status: "confirmed", ...body.sql ? { sql: body.sql } : {} });
+}
+async function rejectHunch(deps, id) {
+  return deps.store.updateHunch(id, { status: "rejected" });
+}
+async function runHunch(deps, id) {
+  const hunch = await deps.store.getHunch(id);
+  if (!hunch)
+    return { error: "Hunch not found." };
+  if (!isReadOnlySql(hunch.sql))
+    return { error: "Only read-only SELECT queries can be run." };
+  const limited = /\blimit\b/i.test(hunch.sql) ? hunch.sql : `${hunch.sql.replace(/;\s*$/, "")} LIMIT 50`;
+  const res = await deps.queryService.executeRawSql(limited);
+  const sample = { columns: res.columns, rows: res.rows, ranAt: (/* @__PURE__ */ new Date()).toISOString() };
+  await deps.store.updateHunch(id, { lastRunSample: sample });
+  return { sample };
+}
+async function answerBlindspot(deps, id, body) {
+  return deps.store.updateBlindspot(id, { status: "answered", answer: body.answer });
+}
+async function dismissBlindspot(deps, id) {
+  return deps.store.updateBlindspot(id, { status: "dismissed" });
+}
+async function loadContextBlock(opts, store, connection) {
+  const fileDocs = loadKnowledgeDocs(opts.projectDir);
+  const dbDocs = (await store.listKnowledgeDocs({ connection })).map((d) => `${d.title}
+${d.content}`);
+  const answered = (await store.listBlindspots({ connection, status: "answered" })).filter((b) => b.answer).map((b) => ({ title: b.title, answer: b.answer }));
+  return buildContextBlock({ docs: [...fileDocs, ...dbDocs], answeredBlindspots: answered });
+}
+async function learningRoutes(fastify, opts) {
+  const { store, queryService } = opts;
+  const requireStore = (reply) => {
+    if (!store) {
+      reply.code(503).send({ error: "Knowledge features require a configured database (set KNOWLEDGE_DATABASE_URL)." });
+      return false;
+    }
+    return true;
+  };
+  fastify.post("/api/learn", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    const connection = request.body?.connection ?? opts.defaultConnectionName;
+    reply.raw.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    });
+    const send = (type, data) => reply.raw.write(formatSSEEvent({ type, data }));
+    try {
+      send("status", { phase: "profiling" });
+      const tables = await opts.getConnectionTables(connection);
+      const profile = await buildSourceProfile({
+        connection,
+        dialect: opts.dialect,
+        tables,
+        execute: (sql) => queryService.executeRawSql(sql)
+      });
+      await store.saveProfile(connection, profile);
+      send("status", { phase: "generating" });
+      let provider;
+      try {
+        provider = createProviderForTask(opts.aiConfig, "hunch_generation", process.env);
+      } catch (e) {
+        send("error", { message: e.message });
+        reply.raw.end();
+        return;
+      }
+      const contextBlock = await loadContextBlock(opts, store, connection);
+      const candidates = await generateHunches({
+        provider,
+        profile,
+        metricNames: opts.metricNames,
+        connection,
+        contextBlock
+      });
+      const created = await store.createHunches(candidates);
+      send("done", { hunches: created });
+    } catch (e) {
+      send("error", { message: e.message });
+    }
+    reply.raw.end();
+  });
+  fastify.get("/api/hunches", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    const q = request.query;
+    return store.listHunches({ connection: q.connection, status: q.status });
+  });
+  fastify.post("/api/hunches/:id/confirm", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    try {
+      return await confirmHunch({ store, queryService }, request.params.id, request.body ?? {});
+    } catch (e) {
+      if (e instanceof ReadOnlySqlError) {
+        reply.code(400).send({ error: e.message });
+        return;
+      }
+      throw e;
+    }
+  });
+  fastify.post("/api/hunches/:id/reject", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    return rejectHunch({ store, queryService }, request.params.id);
+  });
+  fastify.post("/api/hunches/:id/run", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    return runHunch({ store, queryService }, request.params.id);
+  });
+  fastify.post("/api/blindspots/scan", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    const connection = request.body?.connection ?? opts.defaultConnectionName;
+    reply.raw.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    });
+    const send = (type, data) => reply.raw.write(formatSSEEvent({ type, data }));
+    try {
+      send("status", { phase: "scanning" });
+      let profile = await store.getProfile(connection);
+      if (!profile) {
+        const tables = await opts.getConnectionTables(connection);
+        profile = await buildSourceProfile({
+          connection,
+          dialect: opts.dialect,
+          tables,
+          execute: (sql) => queryService.executeRawSql(sql)
+        });
+        await store.saveProfile(connection, profile);
+      }
+      const contextBlock = await loadContextBlock(opts, store, connection);
+      let provider;
+      try {
+        provider = createProviderForTask(opts.aiConfig, "blindspot_scan", process.env);
+      } catch (e) {
+        send("error", { message: e.message });
+        reply.raw.end();
+        return;
+      }
+      const items = await scanBlindspots({
+        provider,
+        profile,
+        metricNames: opts.metricNames,
+        contextBlock,
+        connection
+      });
+      await store.deleteOpenBlindspots(connection);
+      const created = await store.createBlindspots(items);
+      send("done", { blindspots: created });
+    } catch (e) {
+      send("error", { message: e.message });
+    }
+    reply.raw.end();
+  });
+  fastify.get("/api/blindspots", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    const q = request.query;
+    return store.listBlindspots({ connection: q.connection, status: q.status, kind: q.kind });
+  });
+  fastify.post("/api/blindspots/:id/answer", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    return answerBlindspot({ store }, request.params.id, request.body ?? { answer: "" });
+  });
+  fastify.post("/api/blindspots/:id/dismiss", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    return dismissBlindspot({ store }, request.params.id);
+  });
+}
+
+// ../server/dist/routes/data.js
+async function createKnowledgeDocHandler(deps, body) {
+  const [doc] = await deps.store.createKnowledgeDoc({ ...body, source: "ui" });
+  return doc;
+}
+async function dataRoutes(fastify, opts) {
+  const { store } = opts;
+  fastify.get("/api/sources", async () => {
+    const conns = opts.getConnections();
+    return Promise.all(conns.map(async (c) => {
+      let tables = 0;
+      let pendingHunches = 0;
+      let openBlindspots = 0;
+      try {
+        tables = (await opts.getConnectionTables(c.name)).length;
+      } catch {
+      }
+      if (store) {
+        pendingHunches = (await store.listHunches({ connection: c.name, status: "pending" })).length;
+        openBlindspots = (await store.listBlindspots({ connection: c.name, status: "open" })).length;
+      }
+      return { name: c.name, type: c.type, counts: { tables, pendingHunches, openBlindspots } };
+    }));
+  });
+  fastify.get("/api/sources/:connection/tables", async (request) => {
+    const connection = request.params.connection;
+    const tables = await opts.getConnectionTables(connection);
+    const profile = store ? await store.getProfile(connection) : void 0;
+    return tables.map((t) => {
+      const pt = profile?.tables.find((p) => p.table === t.table);
+      const columns = t.columns.map((c) => {
+        const pc = pt?.columns.find((x) => x.name === c.name);
+        return {
+          name: c.name,
+          type: c.type,
+          nullRate: pc?.nullRate,
+          distinctCount: pc?.distinctCount,
+          topValues: pc?.topValues
+        };
+      });
+      return { table: t.table, columns };
+    });
+  });
+  const requireStore = (reply) => {
+    if (!store) {
+      reply.code(503).send({ error: "Knowledge features require a configured database." });
+      return false;
+    }
+    return true;
+  };
+  fastify.get("/api/knowledge", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    return store.listKnowledgeDocs({ connection: request.query.connection });
+  });
+  fastify.post("/api/knowledge", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    return createKnowledgeDocHandler({ store }, request.body);
+  });
+  fastify.put("/api/knowledge/:id", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    const { id } = request.params;
+    return store.updateKnowledgeDoc(id, request.body);
+  });
+  fastify.delete("/api/knowledge/:id", async (request, reply) => {
+    if (!requireStore(reply))
+      return;
+    if (!opts.canWrite(request)) {
+      reply.code(403).send({ error: "Requires editor or admin role." });
+      return;
+    }
+    await store.deleteKnowledgeDoc(request.params.id);
+    return { ok: true };
+  });
+}
+
 // ../server/dist/oauth/service.js
-import { randomUUID, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { randomUUID as randomUUID3, timingSafeEqual as timingSafeEqual2 } from "crypto";
 
 // ../server/dist/oauth/errors.js
 var OAuthError = class extends Error {
@@ -29032,7 +30174,7 @@ var OAuthService = class {
     }
     const authMethod = input.token_endpoint_auth_method === "client_secret_post" ? "client_secret_post" : "none";
     const grantTypes = input.grant_types?.length ? input.grant_types : ["authorization_code", "refresh_token"];
-    const clientId = randomUUID();
+    const clientId = randomUUID3();
     let clientSecret;
     let clientSecretHash = null;
     if (authMethod === "client_secret_post") {
@@ -29489,17 +30631,17 @@ data: ${data}
 }
 
 // ../server/dist/server.js
-import { join as join10, dirname as dirname2 } from "path";
+import { join as join11, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 import { access as access2, readFile as readFile6 } from "fs/promises";
 import { watch as fsWatch } from "fs";
 var __dirname = dirname2(fileURLToPath(import.meta.url));
-var packageJsonPath = join10(__dirname, "..", "package.json");
+var packageJsonPath = join11(__dirname, "..", "package.json");
 var packageJson = JSON.parse(await readFile6(packageJsonPath, "utf-8"));
 var VERSION = packageJson.version;
 async function enrichRefsFromCatalog(projectDir, refs) {
   try {
-    const catalogPath = join10(projectDir, ".yamchart", "catalog.json");
+    const catalogPath = join11(projectDir, ".yamchart", "catalog.json");
     const catalogData = JSON.parse(await readFile6(catalogPath, "utf-8"));
     for (const model of catalogData.models ?? []) {
       if (model.name && model.table) {
@@ -29510,7 +30652,7 @@ async function enrichRefsFromCatalog(projectDir, refs) {
   }
 }
 async function createServer(options) {
-  const { projectDir, port = 3001, host = "0.0.0.0", watch: watch2 = false, serveStatic = process.env.NODE_ENV === "production", staticDir = join10(__dirname, "public"), auth } = options;
+  const { projectDir, port = 3001, host = "0.0.0.0", watch: watch2 = false, serveStatic = process.env.NODE_ENV === "production", staticDir = join11(__dirname, "public"), auth } = options;
   if (auth) {
     initAuthServer(auth.supabaseUrl, auth.supabaseServiceKey);
   }
@@ -29554,6 +30696,19 @@ async function createServer(options) {
     maxSize: 1e3,
     defaultTtlMs: cacheTtl
   });
+  const knowledgeUrlVar = project.knowledge?.database_url_var ?? "KNOWLEDGE_DATABASE_URL";
+  const knowledgeDbUrl = process.env[knowledgeUrlVar];
+  let knowledgeStore;
+  if (knowledgeDbUrl) {
+    const store = new PostgresKnowledgeStore(knowledgeDbUrl);
+    try {
+      await store.init();
+      knowledgeStore = store;
+    } catch (err) {
+      fastify.log.warn(`Knowledge store init failed: ${err.message}`);
+      knowledgeStore = void 0;
+    }
+  }
   const models = {};
   const refs = {};
   for (const model of configLoader.getModels()) {
@@ -29700,16 +30855,103 @@ async function createServer(options) {
     await fastify.register(catalogRoutes, { configLoader, projectDir });
   }
   const mcpBaseUrl = process.env.BASE_URL || project.defaults?.base_url || `http://localhost:${port}`;
+  let semanticLayer;
+  try {
+    const semanticDefs = loadSemanticDefinitions(projectDir);
+    if (semanticDefs.length > 0) {
+      semanticLayer = buildSemanticLayer(semanticDefs, (model) => model);
+    }
+  } catch (err) {
+    fastify.log.warn({ err }, "Failed to load curated semantic definitions; semantic MCP tools disabled");
+  }
+  const connectionType = configLoader.getDefaultConnection()?.type;
+  let embedder;
+  let answerProvider;
+  try {
+    embedder = createEmbedder(project.ai?.embedding, process.env);
+  } catch (err) {
+    fastify.log.warn({ err }, "Failed to build embedder; answer_question tool disabled");
+  }
+  try {
+    answerProvider = createProviderForTask(project.ai, "answer", process.env);
+  } catch (err) {
+    fastify.log.warn({ err }, "Failed to build answer provider; answer_question tool disabled");
+  }
+  const aiConnectionName = defaultConnection?.name ?? "default";
+  const mcpOptions = {
+    configLoader,
+    queryService,
+    projectDir,
+    semanticLayer,
+    connectionType,
+    knowledgeStore,
+    embedder,
+    answerProvider,
+    aiConnectionName
+  };
   if (authDb && oauthService) {
     const mcpAuth = createMcpAuthPreHandler({ authDb, oauthService, baseUrl: mcpBaseUrl });
     await fastify.register(async (mcpScope) => {
       mcpScope.addHook("preHandler", mcpAuth);
-      await mcpScope.register(mcpRoutes, { configLoader, queryService, projectDir });
+      await mcpScope.register(mcpRoutes, mcpOptions);
     });
   } else {
-    await fastify.register(mcpRoutes, { configLoader, queryService, projectDir });
+    await fastify.register(mcpRoutes, mcpOptions);
   }
-  const assetsDir = join10(projectDir, "assets");
+  const learningOptions = {
+    store: knowledgeStore,
+    queryService,
+    projectDir,
+    defaultConnectionName: defaultConnection?.name ?? "default",
+    dialect: defaultConnection?.type ?? "duckdb",
+    metricNames: semanticLayer?.listMetrics().map((m) => m.name) ?? [],
+    getConnectionTables: async (connection) => {
+      const catalogPath = join11(projectDir, ".yamchart", "catalog.json");
+      try {
+        const catalogData = JSON.parse(await readFile6(catalogPath, "utf-8"));
+        return (catalogData.models ?? []).filter((m) => !m.connection || m.connection === connection).map((m) => ({
+          table: m.table ?? m.name ?? "",
+          columns: (m.columns ?? []).map((c) => ({ name: c.name, type: c.data_type ?? "string" }))
+        })).filter((t) => t.table && t.columns.length > 0);
+      } catch {
+        return [];
+      }
+    },
+    // Writes (learn/confirm/reject) require editor/admin. When auth is disabled
+    // there is no request.user, so dev/local mode permits writes.
+    canWrite: (req) => {
+      const user = req.user;
+      if (!user)
+        return true;
+      return user.role !== "viewer";
+    },
+    aiConfig: project.ai
+  };
+  const dataOptions = {
+    store: knowledgeStore,
+    getConnections: () => configLoader.getConnections().map((c) => ({ name: c.name, type: c.type })),
+    getConnectionTables: learningOptions.getConnectionTables,
+    canWrite: learningOptions.canWrite
+  };
+  if (auth) {
+    await fastify.register(async (protectedRoutes) => {
+      protectedRoutes.addHook("preHandler", authMiddleware);
+      protectedRoutes.addHook("preHandler", orgMiddleware);
+      await protectedRoutes.register(learningRoutes, learningOptions);
+      await protectedRoutes.register(dataRoutes, dataOptions);
+    });
+  } else if (authDb) {
+    const localMiddleware = createLocalAuthMiddleware(authDb);
+    await fastify.register(async (protectedRoutes) => {
+      protectedRoutes.addHook("preHandler", localMiddleware);
+      await protectedRoutes.register(learningRoutes, learningOptions);
+      await protectedRoutes.register(dataRoutes, dataOptions);
+    });
+  } else {
+    await fastify.register(learningRoutes, learningOptions);
+    await fastify.register(dataRoutes, dataOptions);
+  }
+  const assetsDir = join11(projectDir, "assets");
   try {
     await access2(assetsDir);
     await fastify.register(fastifyStatic, {
@@ -29720,7 +30962,7 @@ async function createServer(options) {
   } catch {
   }
   if (project.theme?.customCss) {
-    const cssPath = join10(projectDir, project.theme.customCss);
+    const cssPath = join11(projectDir, project.theme.customCss);
     fastify.get("/api/theme/custom.css", async (_request2, reply) => {
       try {
         const content = await readFile6(cssPath, "utf-8");
@@ -29779,7 +31021,7 @@ async function createServer(options) {
       fastify.log.info(`Semantic model rebuilt: ${semanticService.getModel()?.entities.length ?? 0} entities`);
       broadcastConfigChange();
     });
-    const catalogPath = join10(projectDir, ".yamchart", "catalog.json");
+    const catalogPath = join11(projectDir, ".yamchart", "catalog.json");
     try {
       catalogWatcher = fsWatch(catalogPath, () => {
         semanticService.buildFromDisk();
@@ -29843,15 +31085,15 @@ async function runDevServer(projectDir, options) {
   let usesBrowserAuth = false;
   let localAuth;
   try {
-    const { readFileSync: readFileSync2 } = await import("fs");
+    const { readFileSync: readFileSync3 } = await import("fs");
     const { parse: parse2 } = await import("yaml");
-    const { resolveProjectConfig: resolveProjectConfig2, deepMerge: deepMerge3 } = await import("./dist-MX5K2ABB.js");
-    const raw = readFileSync2(resolve2(projectDir, "yamchart.yaml"), "utf-8");
+    const { resolveProjectConfig: resolveProjectConfig2, deepMerge: deepMerge3 } = await import("./dist-PPAD6KOM.js");
+    const raw = readFileSync3(resolve2(projectDir, "yamchart.yaml"), "utf-8");
     const rawConfig = parse2(raw);
     const resolvedEnv = options.env || process.env.YAMCHART_ENV || void 0;
     let projectConfig = resolveProjectConfig2(rawConfig, resolvedEnv);
     try {
-      const localRaw = readFileSync2(resolve2(projectDir, "yamchart.local.yaml"), "utf-8");
+      const localRaw = readFileSync3(resolve2(projectDir, "yamchart.local.yaml"), "utf-8");
       const localOverrides = parse2(localRaw);
       if (localOverrides && typeof localOverrides === "object") {
         projectConfig = deepMerge3(projectConfig, localOverrides);
@@ -29869,7 +31111,7 @@ async function runDevServer(projectDir, options) {
     const targetConn = process.env.YAMCHART_CONNECTION || projectConfig?.defaults?.connection;
     if (targetConn) {
       try {
-        const connRaw = readFileSync2(resolve2(connectionDir, `${targetConn}.yaml`), "utf-8");
+        const connRaw = readFileSync3(resolve2(connectionDir, `${targetConn}.yaml`), "utf-8");
         const connConfig = parse2(connRaw);
         if (connConfig?.auth?.type === "externalbrowser") {
           usesBrowserAuth = true;
@@ -29949,4 +31191,4 @@ async function runDevServer(projectDir, options) {
 export {
   runDevServer
 };
-//# sourceMappingURL=dev-GWXHBBWB.js.map
+//# sourceMappingURL=dev-LZ4YHNDJ.js.map