@runcontext/cli 0.3.5 → 0.4.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command16 } from "commander";
+import { Command as Command18 } from "commander";
 
 // src/commands/lint.ts
 import { Command } from "commander";
@@ -141,7 +141,7 @@ function formatSarif(diagnostics) {
         tool: {
           driver: {
             name: "ContextKit",
-            version: "0.2.1",
+            version: "0.4.1",
             informationUri: "https://github.com/erickittelson/ContextKit",
             rules: Array.from(ruleMap.values())
           }
@@ -525,11 +525,13 @@ import {
 import { Command as Command5 } from "commander";
 import chalk6 from "chalk";
 import path5 from "path";
-import { mkdirSync, writeFileSync as writeFileSync2, existsSync } from "fs";
+import { mkdirSync, writeFileSync as writeFileSync2, existsSync, readFileSync as readFileSync2, unlinkSync } from "fs";
+import * as p from "@clack/prompts";
 import {
   loadConfig as loadConfig4,
   createAdapter,
-  scaffoldFromSchema
+  scaffoldFromSchema,
+  MissingDriverError
 } from "@runcontext/core";
 function parseDbUrl(db) {
   if (db.startsWith("duckdb://")) {
@@ -538,20 +540,52 @@ function parseDbUrl(db) {
   if (db.startsWith("postgres://") || db.startsWith("postgresql://")) {
     return { adapter: "postgres", connection: db };
   }
-  if (db.endsWith(".duckdb") || db.endsWith(".db")) {
+  if (db.startsWith("mysql://")) {
+    return { adapter: "mysql", connection: db };
+  }
+  if (db.startsWith("mssql://") || db.startsWith("sqlserver://")) {
+    return { adapter: "mssql", connection: db };
+  }
+  if (db.startsWith("clickhouse://")) {
+    return { adapter: "clickhouse", host: db };
+  }
+  if (db.startsWith("snowflake://")) {
+    const parts = db.slice("snowflake://".length).split("/");
+    return {
+      adapter: "snowflake",
+      account: parts[0] ?? "",
+      database: parts[1] ?? "",
+      schema: parts[2] ?? ""
+    };
+  }
+  if (db.startsWith("bigquery://")) {
+    const parts = db.slice("bigquery://".length).split("/");
+    return {
+      adapter: "bigquery",
+      project: parts[0] ?? "",
+      dataset: parts[1] ?? ""
+    };
+  }
+  if (db.endsWith(".duckdb")) {
+    return { adapter: "duckdb", path: db };
+  }
+  if (db.endsWith(".sqlite") || db.endsWith(".sqlite3")) {
+    return { adapter: "sqlite", path: db };
+  }
+  if (db.endsWith(".db")) {
     return { adapter: "duckdb", path: db };
   }
   throw new Error(
-    `Cannot determine adapter from "${db}". Use duckdb:// or postgres:// prefix.`
+    `Cannot determine adapter from "${db}". Use a URL prefix (duckdb://, postgres://, mysql://, mssql://, clickhouse://, snowflake://, bigquery://) or a recognized file extension (.duckdb, .db, .sqlite, .sqlite3).`
   );
 }
-var introspectCommand = new Command5("introspect").description("Introspect a database and scaffold Bronze-level OSI metadata").option(
+var introspectCommand = new Command5("introspect").description("Introspect a database and scaffold Bronze-level OSI metadata. Supports: duckdb://, postgres://, mysql://, mssql://, snowflake://, bigquery://, clickhouse://, .sqlite, .duckdb files, and Databricks (via config).").option(
   "--db <url>",
-  "Database URL (e.g., duckdb://path.duckdb or postgres://...)"
+  "Database URL (duckdb://path.duckdb, postgres://user:pass@host/db, mysql://..., mssql://..., snowflake://account/db/schema, bigquery://project/dataset, clickhouse://host, or file.sqlite)"
 ).option(
   "--source <name>",
   "Use a named data_source from contextkit.config.yaml"
-).option("--tables <glob>", 'Filter tables by glob pattern (e.g., "vw_*")').option(
+).option("--tables <glob>", 'Filter tables by glob pattern (e.g., "vw_*")').option("--select", "Interactively select which tables to include").option(
   "--model-name <name>",
   "Name for the generated model (default: derived from source)"
 ).action(async (opts) => {
@@ -602,6 +636,25 @@ var introspectCommand = new Command5("introspect").description("Introspect a dat
       tables = tables.filter((t) => regex.test(t.name));
     }
     console.log(`Discovered ${tables.length} tables/views`);
+    if (opts.select && tables.length > 1) {
+      const selection = await p.multiselect({
+        message: `Select tables to include (${tables.length} found)`,
+        options: tables.map((t) => ({
+          value: t.name,
+          label: t.name,
+          hint: `${t.row_count.toLocaleString()} rows`
+        })),
+        initialValues: tables.map((t) => t.name),
+        required: true
+      });
+      if (p.isCancel(selection)) {
+        await adapter.disconnect();
+        process.exit(0);
+      }
+      const selected = new Set(selection);
+      tables = tables.filter((t) => selected.has(t.name));
+      console.log(`Selected ${tables.length} tables`);
+    }
     const columns = {};
     for (const table of tables) {
       columns[table.name] = await adapter.listColumns(table.name);
@@ -640,15 +693,46 @@ var introspectCommand = new Command5("introspect").description("Introspect a dat
     console.log(`  ${path5.relative(process.cwd(), osiPath)}`);
     console.log(`  ${path5.relative(process.cwd(), govPath)}`);
     console.log(`  ${path5.relative(process.cwd(), ownerPath)}`);
+    const exampleFiles = [
+      path5.join(contextDir, "models", "example-model.osi.yaml"),
+      path5.join(contextDir, "governance", "example-model.governance.yaml"),
+      path5.join(contextDir, "glossary", "glossary.term.yaml"),
+      path5.join(contextDir, "owners", "data-team.owner.yaml")
+    ];
+    let removedCount = 0;
+    for (const exFile of exampleFiles) {
+      if (existsSync(exFile)) {
+        try {
+          const content = readFileSync2(exFile, "utf-8");
+          if (content.includes("example-model") || content.includes("Replace this") || content.includes("Example Term") || content.includes("team: data-team")) {
+            unlinkSync(exFile);
+            removedCount++;
+          }
+        } catch {
+        }
+      }
+    }
+    if (removedCount > 0) {
+      p.log.info(`Removed ${removedCount} example template file(s) from init`);
+    }
     console.log("");
     console.log(chalk6.cyan("Run `context tier` to check your tier score."));
     console.log(
       chalk6.cyan("Run `context verify` to validate against data.")
     );
   } catch (err) {
-    console.error(
-      chalk6.red(`Introspect failed: ${err.message}`)
-    );
+    if (err instanceof MissingDriverError) {
+      console.error(chalk6.yellow(`
+Missing driver: "${err.driverPackage}" is required for ${err.adapter}.
+`));
+      console.error(chalk6.white(`Install it with:
+  npm install ${err.driverPackage}
+`));
+    } else {
+      console.error(
+        chalk6.red(`Introspect failed: ${err.message}`)
+      );
+    }
     process.exit(1);
   }
 });
@@ -914,7 +998,7 @@ var fixCommand = new Command7("fix").description("Auto-fix lint issues").option(
 import { Command as Command8 } from "commander";
 import chalk9 from "chalk";
 import path8 from "path";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
 import {
   compile as compile7,
   loadConfig as loadConfig7,
@@ -944,7 +1028,7 @@ async function runLint(contextDir, fix) {
   if (fix) {
     const fixable = allDiags.filter((d) => d.fixable && d.fix);
     if (fixable.length > 0) {
-      const fixes = applyFixes3(fixable, (filePath) => readFileSync2(filePath, "utf-8"));
+      const fixes = applyFixes3(fixable, (filePath) => readFileSync3(filePath, "utf-8"));
       for (const [file, content] of fixes) {
         writeFileSync3(file, content, "utf-8");
       }
@@ -993,7 +1077,7 @@ async function runLint(contextDir, fix) {
   console.log("");
   previousDiags = currentDiags;
 }
-var devCommand = new Command8("dev").description("Watch mode \u2014 re-run lint on file changes").option("--context-dir <path>", "Path to context directory").option("--fix", "Auto-fix problems on each re-lint").action(async (opts) => {
+var devCommand = new Command8("dev").description("Watch mode \u2014 re-run lint on file changes").option("--context-dir <path>", "Path to context directory").option("--fix", "Auto-fix problems on each re-lint").option("--studio", "Open interactive metadata editor in the browser").option("--port <number>", "Studio server port (default: 4040)", "4040").option("--host <address>", "Studio server host (default: localhost)", "localhost").action(async (opts) => {
   try {
     const config = loadConfig7(process.cwd());
     const contextDir = opts.contextDir ? path8.resolve(opts.contextDir) : path8.resolve(config.context_dir);
@@ -1002,6 +1086,28 @@ var devCommand = new Command8("dev").description("Watch mode \u2014 re-run lint
     if (fix) console.log(chalk9.blue("Auto-fix enabled."));
     console.log(chalk9.gray("Press Ctrl+C to stop.\n"));
     await runLint(contextDir, fix);
+    let recompileAndBroadcast;
+    if (opts.studio) {
+      const { startStudioServer } = await import("./server-DEKWPP3H.js");
+      const studioPort = parseInt(opts.port, 10);
+      const { server: _studioServer, recompileAndBroadcast: rab } = await startStudioServer({
+        contextDir,
+        rootDir: process.cwd(),
+        port: studioPort,
+        host: opts.host
+      });
+      recompileAndBroadcast = rab;
+      const studioUrl = `http://${opts.host === "0.0.0.0" ? "localhost" : opts.host}:${studioPort}`;
+      console.log(chalk9.green(`
+  Studio running at ${chalk9.bold(studioUrl)}
+`));
+      const { execFile } = await import("child_process");
+      const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+      const openArgs = process.platform === "win32" ? ["/c", "start", studioUrl] : [studioUrl];
+      execFile(openCmd, openArgs, (err) => {
+        if (err) console.log(chalk9.gray(`  Open ${studioUrl} in your browser`));
+      });
+    }
     const { watch } = await import("chokidar");
     let debounceTimer = null;
     const watcher = watch(contextDir, {
@@ -1015,6 +1121,9 @@ var devCommand = new Command8("dev").description("Watch mode \u2014 re-run lint
       debounceTimer = setTimeout(async () => {
         try {
           await runLint(contextDir, fix);
+          if (recompileAndBroadcast) {
+            await recompileAndBroadcast();
+          }
         } catch (err) {
           console.error(
             chalk9.red(`Lint error: ${err.message}`)
@@ -1293,7 +1402,7 @@ var validateOsiCommand = new Command12("validate-osi").description("Validate a s
 import { Command as Command13 } from "commander";
 import chalk14 from "chalk";
 import path12 from "path";
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync4, mkdirSync as mkdirSync2, existsSync as existsSync2, readdirSync } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, mkdirSync as mkdirSync2, existsSync as existsSync2, readdirSync } from "fs";
 import * as yaml from "yaml";
 import {
   compile as compile9,
@@ -1373,7 +1482,7 @@ var enrichCommand = new Command13("enrich").description("Suggest or apply metada
       }
       const govFilePath = findFileRecursive(contextDir, `${modelName}.governance.yaml`);
       if (govFilePath) {
-        const govContent = readFileSync3(govFilePath, "utf-8");
+        const govContent = readFileSync4(govFilePath, "utf-8");
         const govDoc = yaml.parse(govContent) ?? {};
         if (suggestions.governance?.trust) {
           govDoc.trust = suggestions.governance.trust;
@@ -1576,15 +1685,479 @@ var rulesCommand = new Command14("rules").description("List all lint rules with
 
 // src/commands/setup.ts
 import { Command as Command15 } from "commander";
-import * as p9 from "@clack/prompts";
+import * as p10 from "@clack/prompts";
 import chalk16 from "chalk";
 
 // src/setup/steps/connect.ts
-import * as p from "@clack/prompts";
-import path13 from "path";
-import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
+import * as p2 from "@clack/prompts";
+import path14 from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
+import { execFileSync } from "child_process";
 import * as yaml2 from "yaml";
-import { loadConfig as loadConfig10, createAdapter as createAdapter5 } from "@runcontext/core";
+import { loadConfig as loadConfig10, createAdapter as createAdapter5, MissingDriverError as MissingDriverError2 } from "@runcontext/core";
+
+// src/setup/mcp-discovery.ts
+import * as fs4 from "fs";
+import * as path13 from "path";
+import * as os from "os";
+var NAME_PATTERNS = {
+  duckdb: "duckdb",
+  motherduck: "duckdb",
+  postgres: "postgres",
+  postgresql: "postgres",
+  neon: "postgres",
+  supabase: "postgres",
+  mysql: "mysql",
+  sqlite: "sqlite",
+  snowflake: "snowflake",
+  bigquery: "bigquery",
+  clickhouse: "clickhouse",
+  databricks: "databricks",
+  mssql: "mssql",
+  "sql-server": "mssql",
+  redshift: "postgres"
+  // Redshift is Postgres-compatible
+};
+var PACKAGE_PATTERNS = {
+  "@motherduck/mcp": "duckdb",
+  "mcp-server-duckdb": "duckdb",
+  "mcp-server-postgres": "postgres",
+  "mcp-server-postgresql": "postgres",
+  "@neon/mcp": "postgres",
+  "@supabase/mcp": "postgres",
+  "mcp-server-mysql": "mysql",
+  "mcp-server-sqlite": "sqlite",
+  "mcp-server-snowflake": "snowflake",
+  "mcp-server-bigquery": "bigquery",
+  "mcp-server-clickhouse": "clickhouse",
+  "mcp-server-databricks": "databricks",
+  "mcp-server-mssql": "mssql",
+  "mcp-server-redshift": "postgres"
+};
+var CONNECTION_ENV_VARS = [
+  "DATABASE_URL",
+  "POSTGRES_URL",
+  "POSTGRESQL_URL",
+  "PG_CONNECTION_STRING",
+  "MYSQL_URL",
+  "MYSQL_CONNECTION_STRING",
+  "DUCKDB_PATH",
+  "SQLITE_PATH",
+  "SNOWFLAKE_ACCOUNT",
+  "BIGQUERY_PROJECT",
+  "CLICKHOUSE_URL",
+  "DATABRICKS_HOST",
+  "MSSQL_CONNECTION_STRING",
+  "REDSHIFT_URL"
+];
+var CONNECTION_FLAGS = [
+  "--db-path",
+  "--database",
+  "--connection-string",
+  "--connection",
+  "--host",
+  "--port",
+  "--db",
+  "--dsn"
+];
+var URI_SCHEMES = {
+  "postgres://": "postgres",
+  "postgresql://": "postgres",
+  "mysql://": "mysql",
+  "clickhouse://": "clickhouse",
+  "mssql://": "mssql",
+  "jdbc:": "postgres"
+  // conservative fallback
+};
+function getConfigLocations(cwd) {
+  const home = os.homedir();
+  const isMac = process.platform === "darwin";
+  const locations = [
+    // Claude Code
+    { ide: "claude-code", scope: "user", path: path13.join(home, ".claude.json") },
+    { ide: "claude-code", scope: "project", path: path13.join(cwd, ".mcp.json") },
+    // Cursor
+    { ide: "cursor", scope: "user", path: path13.join(home, ".cursor", "mcp.json") },
+    { ide: "cursor", scope: "project", path: path13.join(cwd, ".cursor", "mcp.json") },
+    // VS Code / Copilot
+    { ide: "vscode", scope: "project", path: path13.join(cwd, ".vscode", "mcp.json") },
+    // Windsurf
+    { ide: "windsurf", scope: "user", path: path13.join(home, ".codeium", "windsurf", "mcp_config.json") }
+  ];
+  if (isMac) {
+    locations.push(
+      {
+        ide: "claude-code",
+        scope: "managed",
+        path: path13.join("/", "Library", "Application Support", "ClaudeCode", "managed-mcp.json")
+      },
+      {
+        ide: "claude-desktop",
+        scope: "user",
+        path: path13.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+      }
+    );
+  }
+  return locations;
+}
+function readJsonSafe(filePath) {
+  try {
+    if (!fs4.existsSync(filePath)) return null;
+    const raw = fs4.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function extractServers(json, ide) {
+  if (json === null || typeof json !== "object") return null;
+  const obj = json;
+  if (ide === "vscode") {
+    const servers = obj["servers"];
+    if (servers && typeof servers === "object") {
+      return servers;
+    }
+    return null;
+  }
+  const mcpServers = obj["mcpServers"];
+  if (mcpServers && typeof mcpServers === "object") {
+    return mcpServers;
+  }
+  return null;
+}
+function expandEnvValue(value) {
+  return value.replace(/\$\{([^}]+)\}/g, (_match, expr) => {
+    const defaultSep = expr.indexOf(":-");
+    if (defaultSep !== -1) {
+      const varName = expr.slice(0, defaultSep);
+      const defaultVal = expr.slice(defaultSep + 2);
+      return process.env[varName] ?? defaultVal;
+    }
+    return process.env[expr] ?? "";
+  });
+}
+function expandEnvMap(env) {
+  if (!env) return void 0;
+  const expanded = {};
+  for (const [key, value] of Object.entries(env)) {
+    expanded[key] = expandEnvValue(String(value));
+  }
+  return expanded;
+}
+function detectAdapterType(serverName, entry) {
+  const nameLower = serverName.toLowerCase();
+  for (const [pattern, adapter] of Object.entries(NAME_PATTERNS)) {
+    if (nameLower.includes(pattern)) return adapter;
+  }
+  const allTokens = [entry.command ?? "", ...entry.args ?? []].map(
+    (s) => String(s).toLowerCase()
+  );
+  for (const [pkg, adapter] of Object.entries(PACKAGE_PATTERNS)) {
+    if (allTokens.some((t) => t.includes(pkg.toLowerCase()))) return adapter;
+  }
+  const argsStr = (entry.args ?? []).join(" ").toLowerCase();
+  for (const flag of CONNECTION_FLAGS) {
+    if (argsStr.includes(flag)) {
+      return inferAdapterFromArgs(entry.args ?? []);
+    }
+  }
+  if (entry.env) {
+    for (const envVar of CONNECTION_ENV_VARS) {
+      if (envVar in entry.env) {
+        return inferAdapterFromEnvVar(envVar, entry.env[envVar] ?? "");
+      }
+    }
+  }
+  for (const arg of entry.args ?? []) {
+    for (const [scheme, adapter] of Object.entries(URI_SCHEMES)) {
+      if (String(arg).startsWith(scheme)) return adapter;
+    }
+  }
+  return null;
+}
+function inferAdapterFromEnvVar(varName, value) {
+  const upper = varName.toUpperCase();
+  if (upper.includes("POSTGRES") || upper.includes("PG_")) return "postgres";
+  if (upper.includes("MYSQL")) return "mysql";
+  if (upper.includes("DUCKDB")) return "duckdb";
+  if (upper.includes("SQLITE")) return "sqlite";
+  if (upper.includes("SNOWFLAKE")) return "snowflake";
+  if (upper.includes("BIGQUERY")) return "bigquery";
+  if (upper.includes("CLICKHOUSE")) return "clickhouse";
+  if (upper.includes("DATABRICKS")) return "databricks";
+  if (upper.includes("MSSQL")) return "mssql";
+  if (upper.includes("REDSHIFT")) return "postgres";
+  if (upper === "DATABASE_URL") {
+    for (const [scheme, adapter] of Object.entries(URI_SCHEMES)) {
+      if (String(value).startsWith(scheme)) return adapter;
+    }
+  }
+  return "postgres";
+}
+function inferAdapterFromArgs(args) {
+  const joined = args.join(" ").toLowerCase();
+  for (const [scheme, adapter] of Object.entries(URI_SCHEMES)) {
+    if (joined.includes(scheme)) return adapter;
+  }
+  if (joined.includes(".duckdb") || joined.includes(".db") || joined.includes("duckdb")) return "duckdb";
+  if (joined.includes(".sqlite") || joined.includes(".sqlite3")) return "sqlite";
+  return null;
+}
+function extractConnectionDetails(entry, adapterType) {
+  const args = (entry.args ?? []).map(String);
+  const env = expandEnvMap(entry.env);
+  const command = String(entry.command ?? "");
+  const details = {
+    command,
+    args,
+    env
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const nextArg = i + 1 < args.length ? args[i + 1] : void 0;
+    if ((arg === "--db-path" || arg === "--database" || arg === "--db") && nextArg) {
+      if (adapterType === "duckdb" || adapterType === "sqlite") {
+        details.path = nextArg;
+      } else {
+        details.database = nextArg;
+      }
+    }
+    if ((arg === "--connection-string" || arg === "--connection" || arg === "--dsn") && nextArg) {
+      details.connection = nextArg;
+    }
+    if (arg === "--host" && nextArg) {
+      details.host = nextArg;
+    }
+    if (arg === "--port" && nextArg) {
+      const port = parseInt(nextArg, 10);
+      if (!isNaN(port)) details.port = port;
+    }
+  }
+  if (!details.connection && !details.path) {
+    for (const arg of args) {
+      for (const scheme of Object.keys(URI_SCHEMES)) {
+        if (arg.startsWith(scheme)) {
+          details.connection = arg;
+          break;
+        }
+      }
+      if (details.connection) break;
+      if ((adapterType === "duckdb" || adapterType === "sqlite") && (arg.endsWith(".duckdb") || arg.endsWith(".db") || arg.endsWith(".sqlite") || arg.endsWith(".sqlite3"))) {
+        details.path = arg;
+        break;
+      }
+    }
+  }
+  if (env) {
+    if (!details.connection) {
+      for (const varName of CONNECTION_ENV_VARS) {
+        if (env[varName]) {
+          const val = env[varName];
+          for (const scheme of Object.keys(URI_SCHEMES)) {
+            if (val.startsWith(scheme)) {
+              details.connection = val;
+              break;
+            }
+          }
+          if (details.connection) break;
+          if ((adapterType === "duckdb" || adapterType === "sqlite") && (varName.includes("PATH") || varName.includes("DATABASE"))) {
+            details.path = val;
+            break;
+          }
+        }
+      }
+    }
+    if (!details.host && env["HOST"]) details.host = env["HOST"];
+    if (!details.host && env["DB_HOST"]) details.host = env["DB_HOST"];
+    if (!details.port && env["PORT"]) {
+      const p11 = parseInt(env["PORT"], 10);
+      if (!isNaN(p11)) details.port = p11;
+    }
+    if (!details.port && env["DB_PORT"]) {
+      const p11 = parseInt(env["DB_PORT"], 10);
+      if (!isNaN(p11)) details.port = p11;
+    }
+    if (!details.database && env["DB_NAME"]) details.database = env["DB_NAME"];
+  }
+  return details;
+}
+var IDE_LABELS = {
+  "claude-code": "Claude Code",
+  cursor: "Cursor",
+  vscode: "VS Code",
+  windsurf: "Windsurf",
+  "claude-desktop": "Claude Desktop"
+};
+var ADAPTER_LABELS = {
+  duckdb: "DuckDB",
+  postgres: "PostgreSQL",
+  mysql: "MySQL",
+  sqlite: "SQLite",
+  snowflake: "Snowflake",
+  bigquery: "BigQuery",
+  clickhouse: "ClickHouse",
+  databricks: "Databricks",
+  mssql: "SQL Server"
+};
+function buildLabel(serverName, adapterType, details, ide) {
+  const adapterLabel = ADAPTER_LABELS[adapterType] ?? adapterType;
+  const ideLabel = IDE_LABELS[ide] ?? ide;
+  let descriptor = "";
+  if (details.path) {
+    descriptor = path13.basename(details.path);
+  } else if (details.database) {
+    descriptor = details.database;
+  } else if (details.connection) {
+    try {
+      const url = new URL(details.connection);
+      const dbName = url.pathname.replace(/^\//, "");
+      if (dbName) descriptor = dbName;
+    } catch {
+    }
+  }
+  if (!descriptor && details.host) {
+    descriptor = details.host;
+  }
+  if (descriptor) {
+    return `${adapterLabel} \u2014 ${descriptor} (from ${ideLabel})`;
+  }
+  return `${adapterLabel} \u2014 ${serverName} (from ${ideLabel})`;
+}
+function deduplicationKey(db) {
+  const parts = [db.adapterType];
+  if (db.connectionDetails.path) parts.push(db.connectionDetails.path);
+  if (db.connectionDetails.connection) parts.push(db.connectionDetails.connection);
+  if (db.connectionDetails.host) parts.push(db.connectionDetails.host);
+  if (db.connectionDetails.port) parts.push(String(db.connectionDetails.port));
+  if (db.connectionDetails.database) parts.push(db.connectionDetails.database);
+  if (parts.length === 1) parts.push(db.serverName);
+  return parts.join("|");
+}
+function discoverDatabases(cwd) {
+  const results = [];
+  try {
+    const locations = getConfigLocations(cwd);
+    for (const loc of locations) {
+      try {
+        const json = readJsonSafe(loc.path);
+        if (json === null) continue;
+        const servers = extractServers(json, loc.ide);
+        if (!servers) continue;
+        for (const [serverName, entry] of Object.entries(servers)) {
+          try {
+            if (!entry || typeof entry !== "object") continue;
+            const adapterType = detectAdapterType(serverName, entry);
+            if (!adapterType) continue;
+            const connectionDetails = extractConnectionDetails(entry, adapterType);
+            const label = buildLabel(serverName, adapterType, connectionDetails, loc.ide);
+            results.push({
+              ide: loc.ide,
+              scope: loc.scope,
+              serverName,
+              adapterType,
+              connectionDetails,
+              label
+            });
+          } catch {
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  const scopeOrder = { project: 0, user: 1, managed: 2 };
+  results.sort((a, b) => {
+    const sa = scopeOrder[a.scope] ?? 9;
+    const sb = scopeOrder[b.scope] ?? 9;
+    return sa - sb;
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const db of results) {
+    const key = deduplicationKey(db);
+    if (!seen.has(key)) {
+      seen.add(key);
+      deduped.push(db);
+    }
+  }
+  return deduped;
+}
+function toDataSourceConfig(discovered) {
+  const { adapterType, connectionDetails } = discovered;
+  switch (adapterType) {
+    case "duckdb":
+    case "sqlite": {
+      const filePath = connectionDetails.path;
+      if (!filePath) return null;
+      return { adapter: adapterType, path: filePath };
+    }
+    case "postgres":
+    case "mysql":
+    case "mssql": {
+      if (connectionDetails.connection) {
+        return { adapter: adapterType, connection: connectionDetails.connection };
+      }
+      if (connectionDetails.host) {
+        const config = {
+          adapter: adapterType,
+          host: connectionDetails.host
+        };
+        if (connectionDetails.port) config.port = connectionDetails.port;
+        if (connectionDetails.database) config.database = connectionDetails.database;
+        return config;
+      }
+      return null;
+    }
+    case "snowflake": {
+      if (connectionDetails.host) {
+        return {
+          adapter: "snowflake",
+          account: connectionDetails.host,
+          database: connectionDetails.database
+        };
+      }
+      return null;
+    }
+    case "bigquery": {
+      if (connectionDetails.database) {
+        return {
+          adapter: "bigquery",
+          project: connectionDetails.database
+        };
+      }
+      return null;
+    }
+    case "clickhouse": {
+      if (connectionDetails.connection) {
+        return { adapter: "clickhouse", host: connectionDetails.connection };
+      }
+      if (connectionDetails.host) {
+        const config = {
+          adapter: "clickhouse",
+          host: connectionDetails.host
+        };
+        if (connectionDetails.port) config.port = connectionDetails.port;
+        if (connectionDetails.database) config.database = connectionDetails.database;
+        return config;
+      }
+      return null;
+    }
+    case "databricks": {
+      if (connectionDetails.host) {
+        return {
+          adapter: "databricks",
+          serverHostname: connectionDetails.host
+        };
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+// src/setup/steps/connect.ts
 function autoDetectDb(cwd) {
   try {
     const config = loadConfig10(cwd);
@@ -1603,26 +2176,37 @@ function autoDetectDb(cwd) {
     } catch {
     }
   }
-  if (process.env.DUCKDB_PATH && existsSync3(process.env.DUCKDB_PATH)) {
+  if (process.env.DUCKDB_PATH && existsSync4(process.env.DUCKDB_PATH)) {
     return {
       dsConfig: { adapter: "duckdb", path: process.env.DUCKDB_PATH },
       label: `duckdb \u2014 $DUCKDB_PATH`
     };
   }
-  const mcpPath = path13.join(cwd, ".claude", "mcp.json");
-  if (existsSync3(mcpPath)) {
+  try {
+    const discovered = discoverDatabases(cwd);
+    if (discovered.length > 0) {
+      const first = discovered[0];
+      const ds = toDataSourceConfig(first);
+      if (ds) {
+        return { dsConfig: ds, label: first.label };
+      }
+    }
+  } catch {
+  }
+  const mcpPath = path14.join(cwd, ".claude", "mcp.json");
+  if (existsSync4(mcpPath)) {
     try {
-      const mcpConfig = JSON.parse(readFileSync4(mcpPath, "utf-8"));
+      const mcpConfig = JSON.parse(readFileSync6(mcpPath, "utf-8"));
       const duckdbServer = mcpConfig.mcpServers?.duckdb;
       if (duckdbServer?.args) {
         const args = duckdbServer.args;
         const idx = args.indexOf("--db-path");
         if (idx >= 0 && args[idx + 1]) {
           const dbPath = args[idx + 1];
-          if (existsSync3(dbPath)) {
+          if (existsSync4(dbPath)) {
             return {
               dsConfig: { adapter: "duckdb", path: dbPath },
-              label: `duckdb \u2014 ${path13.basename(dbPath)} (from .claude/mcp.json)`
+              label: `duckdb \u2014 ${path14.basename(dbPath)} (from .claude/mcp.json)`
             };
           }
         }
@@ -1632,84 +2216,308 @@ function autoDetectDb(cwd) {
   }
   return void 0;
 }
-async function promptForConnection() {
-  const connector = await p.select({
-    message: "Select your database",
+function discoverAllDatabases(cwd) {
+  try {
+    return discoverDatabases(cwd).map((d) => {
+      const dsConfig = toDataSourceConfig(d);
+      if (!dsConfig) return null;
+      return { dsConfig, label: d.label };
+    }).filter((d) => d !== null);
+  } catch {
+    return [];
+  }
+}
+async function promptForFileDb(adapter, ext, envDefault) {
+  const method = await p2.select({
+    message: "How do you connect?",
     options: [
-      { value: "duckdb", label: "DuckDB", hint: "Local .duckdb file" },
-      { value: "postgres", label: "PostgreSQL", hint: "Connection string" }
+      { value: "env", label: "Environment variable", hint: `e.g. ${envDefault}` },
+      { value: "path", label: "File path", hint: `e.g. ./warehouse${ext}` }
     ]
   });
-  if (p.isCancel(connector)) return void 0;
-  if (connector === "duckdb") {
-    const method = await p.select({
-      message: "How do you connect?",
-      options: [
-        { value: "env", label: "Environment variable", hint: "e.g. DUCKDB_PATH" },
-        { value: "path", label: "File path", hint: "e.g. ./warehouse.duckdb" }
-      ]
+  if (p2.isCancel(method)) return void 0;
+  if (method === "env") {
+    const envName = await p2.text({
+      message: "Environment variable name",
+      initialValue: envDefault,
+      validate(value) {
+        if (!value) return "Required";
+        const resolved = process.env[value];
+        if (!resolved) return `$${value} is not set`;
+        if (!existsSync4(resolved)) return `$${value} points to "${resolved}" which does not exist`;
+      }
     });
-    if (p.isCancel(method)) return void 0;
-    if (method === "env") {
-      const envName = await p.text({
-        message: "Environment variable name",
-        initialValue: "DUCKDB_PATH",
-        validate(value) {
-          if (!value) return "Required";
-          const resolved = process.env[value];
-          if (!resolved) return `$${value} is not set`;
-          if (!existsSync3(resolved)) return `$${value} points to "${resolved}" which does not exist`;
-        }
-      });
-      if (p.isCancel(envName)) return void 0;
-      return { adapter: "duckdb", path: process.env[envName] };
-    } else {
-      const filePath = await p.text({
-        message: "Path to .duckdb file",
-        placeholder: "./warehouse.duckdb",
-        validate(value) {
-          if (!value) return "Required";
-          if (!existsSync3(value)) return `File not found: ${value}`;
-        }
-      });
-      if (p.isCancel(filePath)) return void 0;
-      return { adapter: "duckdb", path: path13.resolve(filePath) };
-    }
+    if (p2.isCancel(envName)) return void 0;
+    return { adapter, path: process.env[envName] };
   } else {
-    const method = await p.select({
-      message: "How do you connect?",
-      options: [
-        { value: "env", label: "Environment variable", hint: "e.g. DATABASE_URL" },
-        { value: "url", label: "Connection string", hint: "postgres://..." }
-      ]
+    const filePath = await p2.text({
+      message: `Path to ${ext} file`,
+      placeholder: `./warehouse${ext}`,
+      validate(value) {
+        if (!value) return "Required";
+        if (!existsSync4(value)) return `File not found: ${value}`;
+      }
     });
-    if (p.isCancel(method)) return void 0;
-    if (method === "env") {
-      const envName = await p.text({
-        message: "Environment variable name",
-        initialValue: "DATABASE_URL",
-        validate(value) {
-          if (!value) return "Required";
-          const resolved = process.env[value];
-          if (!resolved) return `$${value} is not set`;
-        }
-      });
-      if (p.isCancel(envName)) return void 0;
-      return { adapter: "postgres", connection: process.env[envName] };
-    } else {
-      const url = await p.text({
-        message: "Connection string",
-        placeholder: "postgres://user:pass@host:5432/dbname",
-        validate(value) {
-          if (!value) return "Required";
-          if (!value.startsWith("postgres://") && !value.startsWith("postgresql://")) {
-            return "Must start with postgres:// or postgresql://";
-          }
+    if (p2.isCancel(filePath)) return void 0;
+    return { adapter, path: path14.resolve(filePath) };
+  }
+}
+async function promptForConnectionString(adapter, scheme, envDefault) {
+  const method = await p2.select({
+    message: "How do you connect?",
+    options: [
+      { value: "env", label: "Environment variable", hint: `e.g. ${envDefault}` },
+      { value: "url", label: "Connection string", hint: `${scheme}://...` }
+    ]
+  });
+  if (p2.isCancel(method)) return void 0;
+  if (method === "env") {
+    const envName = await p2.text({
+      message: "Environment variable name",
+      initialValue: envDefault,
+      validate(value) {
+        if (!value) return "Required";
+        const resolved = process.env[value];
+        if (!resolved) return `$${value} is not set`;
+      }
+    });
+    if (p2.isCancel(envName)) return void 0;
+    return { adapter, connection: process.env[envName] };
+  } else {
+    const url = await p2.text({
+      message: "Connection string",
+      placeholder: `${scheme}://user:pass@host:5432/dbname`,
+      validate(value) {
+        if (!value) return "Required";
+        if (!value.startsWith(`${scheme}://`)) {
+          return `Must start with ${scheme}://`;
         }
-      });
-      if (p.isCancel(url)) return void 0;
-      return { adapter: "postgres", connection: url };
+      }
+    });
+    if (p2.isCancel(url)) return void 0;
+    return { adapter, connection: url };
+  }
+}
+async function promptForSnowflake() {
+  const account = await p2.text({
+    message: "Snowflake account identifier",
+    placeholder: "xy12345.us-east-1",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(account)) return void 0;
+  const username = await p2.text({
+    message: "Username",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(username)) return void 0;
+  const password2 = await p2.password({
+    message: "Password",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(password2)) return void 0;
+  const warehouse = await p2.text({
+    message: "Warehouse",
+    placeholder: "COMPUTE_WH",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(warehouse)) return void 0;
+  const database = await p2.text({
+    message: "Database",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(database)) return void 0;
+  const schema = await p2.text({
+    message: "Schema",
+    initialValue: "PUBLIC",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(schema)) return void 0;
+  return {
+    adapter: "snowflake",
+    account,
+    username,
+    password: password2,
+    warehouse,
+    database,
+    schema
+  };
+}
+async function promptForBigQuery() {
+  const project = await p2.text({
+    message: "Google Cloud project ID",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(project)) return void 0;
+  const dataset = await p2.text({
+    message: "Dataset",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(dataset)) return void 0;
+  const keyFilename = await p2.text({
+    message: "Path to service account key file (JSON)",
+    placeholder: "./service-account.json",
+    validate(value) {
+      if (!value) return "Required";
+      if (!existsSync4(value)) return `File not found: ${value}`;
+    }
+  });
+  if (p2.isCancel(keyFilename)) return void 0;
+  return {
+    adapter: "bigquery",
+    project,
+    dataset,
+    keyFilename: path14.resolve(keyFilename)
+  };
+}
+async function promptForClickHouse() {
+  const host = await p2.text({
+    message: "Host",
+    initialValue: "localhost",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(host)) return void 0;
+  const port = await p2.text({
+    message: "HTTP port",
+    initialValue: "8123",
+    validate(value) {
+      if (!value) return "Required";
+      if (!/^\d+$/.test(value)) return "Must be a number";
+    }
+  });
+  if (p2.isCancel(port)) return void 0;
+  const database = await p2.text({
+    message: "Database",
+    initialValue: "default",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(database)) return void 0;
+  const username = await p2.text({
+    message: "Username",
+    initialValue: "default",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(username)) return void 0;
+  const password2 = await p2.password({
+    message: "Password (leave empty if none)"
+  });
+  if (p2.isCancel(password2)) return void 0;
+  return {
+    adapter: "clickhouse",
+    host,
+    port: parseInt(port, 10),
+    database,
+    username,
+    password: password2 || void 0
+  };
+}
+async function promptForDatabricks() {
+  const serverHostname = await p2.text({
+    message: "Server hostname",
+    placeholder: "abc-12345678-wxyz.cloud.databricks.com",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(serverHostname)) return void 0;
+  const httpPath = await p2.text({
+    message: "HTTP path",
+    placeholder: "/sql/1.0/warehouses/abcdef1234567890",
+    validate(value) {
+      if (!value) return "Required";
+    }
+  });
+  if (p2.isCancel(httpPath)) return void 0;
+  const token = await p2.password({
+    message: "Personal access token",
+    validate(value) {
+      if (!value) return "Required";
     }
+  });
+  if (p2.isCancel(token)) return void 0;
+  return {
+    adapter: "databricks",
+    serverHostname,
+    httpPath,
+    token
+  };
+}
+async function promptForConnection() {
+  const cwd = process.cwd();
+  const discovered = discoverAllDatabases(cwd);
+  const discoveredMap = /* @__PURE__ */ new Map();
+  const options = [];
+  for (let i = 0; i < discovered.length; i++) {
+    const key = `discovered:${i}`;
+    discoveredMap.set(key, discovered[i].dsConfig);
+    options.push({ value: key, label: discovered[i].label });
+  }
+  if (discovered.length > 0) {
+    options.push({ value: "__separator__", label: "\u2500\u2500\u2500 Or connect manually \u2500\u2500\u2500" });
+  }
+  options.push(
+    { value: "duckdb", label: "DuckDB", hint: "Local .duckdb file" },
+    { value: "postgres", label: "PostgreSQL", hint: "Connection string" },
+    { value: "mysql", label: "MySQL / MariaDB", hint: "Connection string" },
+    { value: "mssql", label: "SQL Server", hint: "Connection string" },
+    { value: "snowflake", label: "Snowflake", hint: "Account credentials" },
+    { value: "bigquery", label: "BigQuery", hint: "Google Cloud project" },
+    { value: "clickhouse", label: "ClickHouse", hint: "HTTP connection" },
+    { value: "databricks", label: "Databricks", hint: "Workspace connection" },
+    { value: "sqlite", label: "SQLite", hint: "Local .db file" }
+  );
+  const selection = await p2.select({
+    message: "Select your database",
+    options
+  });
+  if (p2.isCancel(selection)) return void 0;
+  const connector = selection;
+  if (discoveredMap.has(connector)) {
+    return discoveredMap.get(connector);
+  }
+  if (connector === "__separator__") return promptForConnection();
+  switch (connector) {
+    case "duckdb":
+      return promptForFileDb("duckdb", ".duckdb", "DUCKDB_PATH");
+    case "sqlite":
+      return promptForFileDb("sqlite", ".db", "SQLITE_PATH");
+    case "postgres":
+      return promptForConnectionString("postgres", "postgres", "DATABASE_URL");
+    case "mysql":
+      return promptForConnectionString("mysql", "mysql", "MYSQL_URL");
+    case "mssql":
+      return promptForConnectionString("mssql", "mssql", "MSSQL_URL");
+    case "snowflake":
+      return promptForSnowflake();
+    case "bigquery":
+      return promptForBigQuery();
+    case "clickhouse":
+      return promptForClickHouse();
+    case "databricks":
+      return promptForDatabricks();
+    default:
+      return void 0;
   }
 }
 async function runConnectStep() {
@@ -1717,10 +2525,10 @@ async function runConnectStep() {
   let dsConfig;
   const detected = autoDetectDb(cwd);
   if (detected) {
-    p.log.info(`Detected: ${detected.label}`);
-    const useDetected = await p.confirm({ message: "Use this database?" });
-    if (p.isCancel(useDetected)) {
-      p.cancel("Setup cancelled.");
+    p2.log.info(`Detected: ${detected.label}`);
+    const useDetected = await p2.confirm({ message: "Use this database?" });
+    if (p2.isCancel(useDetected)) {
+      p2.cancel("Setup cancelled.");
       return void 0;
     }
     if (useDetected) {
@@ -1728,7 +2536,7 @@ async function runConnectStep() {
     } else {
       const manual = await promptForConnection();
       if (!manual) {
-        p.cancel("Setup cancelled.");
+        p2.cancel("Setup cancelled.");
         return void 0;
       }
       dsConfig = manual;
@@ -1736,12 +2544,12 @@ async function runConnectStep() {
   } else {
     const manual = await promptForConnection();
     if (!manual) {
-      p.cancel("Setup cancelled.");
+      p2.cancel("Setup cancelled.");
       return void 0;
     }
     dsConfig = manual;
   }
-  const spin = p.spinner();
+  const spin = p2.spinner();
   spin.start("Connecting to database...");
   let adapter;
   try {
@@ -1749,21 +2557,84 @@ async function runConnectStep() {
     await adapter.connect();
   } catch (err) {
     spin.stop("Connection failed");
-    p.log.error(err.message);
-    p.cancel("Could not connect to database.");
-    return void 0;
+    if (err instanceof MissingDriverError2) {
+      p2.log.warn(`The ${err.adapter} adapter requires the "${err.driverPackage}" npm package.`);
+      const shouldInstall = await p2.confirm({
+        message: `Install "${err.driverPackage}" now?`
+      });
+      if (!p2.isCancel(shouldInstall) && shouldInstall) {
+        const installSpin = p2.spinner();
+        installSpin.start(`Installing ${err.driverPackage}...`);
+        try {
+          execFileSync("npm", ["install", err.driverPackage], {
+            stdio: "pipe",
+            cwd: process.cwd()
+          });
+          installSpin.stop(`Installed ${err.driverPackage}`);
+          spin.start("Retrying connection...");
+          try {
+            adapter = await createAdapter5(dsConfig);
+            await adapter.connect();
+            spin.stop("Connected");
+          } catch (retryErr) {
+            spin.stop("Connection failed");
+            p2.log.error(retryErr.message);
+            p2.cancel("Could not connect to database.");
+            return void 0;
+          }
+        } catch {
+          installSpin.stop("Installation failed");
+          p2.log.error(`Could not install ${err.driverPackage}. Try manually:
+  npm install ${err.driverPackage}`);
+          p2.cancel("Could not connect to database.");
+          return void 0;
+        }
+      } else {
+        p2.log.info(`Install it manually with:
+  npm install ${err.driverPackage}`);
+        p2.cancel("Could not connect to database.");
+        return void 0;
+      }
+    } else {
+      p2.log.error(err.message);
+      p2.cancel("Could not connect to database.");
+      return void 0;
+    }
   }
-  const tables = await adapter.listTables();
+  const allTables = await adapter.listTables();
+  spin.stop(`Found ${allTables.length} tables`);
+  let tables = allTables;
+  if (allTables.length > 1) {
+    const tableSelection = await p2.multiselect({
+      message: `Select tables to include (${allTables.length} found)`,
+      options: allTables.map((t) => ({
+        value: t.name,
+        label: t.name,
+        hint: `${t.row_count.toLocaleString()} rows`
+      })),
+      initialValues: allTables.map((t) => t.name),
+      required: true
+    });
+    if (p2.isCancel(tableSelection)) {
+      p2.cancel("Setup cancelled.");
+      await adapter.disconnect();
+      return void 0;
+    }
+    const selected = new Set(tableSelection);
+    tables = allTables.filter((t) => selected.has(t.name));
+  }
+  const colSpin = p2.spinner();
+  colSpin.start(`Introspecting ${tables.length} tables...`);
   const columns = {};
   for (const table of tables) {
     columns[table.name] = await adapter.listColumns(table.name);
   }
   const totalCols = Object.values(columns).reduce((sum, c) => sum + c.length, 0);
-  spin.stop(`Found ${tables.length} tables, ${totalCols} columns`);
+  colSpin.stop(`${tables.length} tables, ${totalCols} columns`);
   const tableLines = tables.map((t) => `  ${t.name.padEnd(30)} ${t.row_count.toLocaleString()} rows`).join("\n");
-  p.note(tableLines, "Discovered Tables");
-  const defaultModel = path13.basename(cwd).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-  const modelInput = await p.text({
+  p2.note(tableLines, "Selected Tables");
+  const defaultModel = path14.basename(cwd).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  const modelInput = await p2.text({
     message: "Model name",
     initialValue: defaultModel,
     validate(value) {
@@ -1771,12 +2642,12 @@ async function runConnectStep() {
       if (!/^[a-z0-9-]+$/.test(value)) return "Use lowercase letters, numbers, and hyphens only";
     }
   });
-  if (p.isCancel(modelInput)) {
-    p.cancel("Setup cancelled.");
+  if (p2.isCancel(modelInput)) {
+    p2.cancel("Setup cancelled.");
     await adapter.disconnect();
     return void 0;
   }
-  const tierInput = await p.select({
+  const tierInput = await p2.select({
     message: "Target metadata tier",
     options: [
       { value: "bronze", label: "Bronze", hint: "Schema + ownership + grain" },
@@ -1784,12 +2655,40 @@ async function runConnectStep() {
       { value: "gold", label: "Gold", hint: "+ semantic roles, rules, golden queries (needs curation)" }
     ]
   });
-  if (p.isCancel(tierInput)) {
-    p.cancel("Setup cancelled.");
+  if (p2.isCancel(tierInput)) {
+    p2.cancel("Setup cancelled.");
     await adapter.disconnect();
     return void 0;
   }
-  const configPath = path13.join(cwd, "contextkit.config.yaml");
+  let intent;
+  const wantsIntent = await p2.confirm({
+    message: "Describe what you're building? (helps AI agents curate better metadata)"
+  });
+  if (!p2.isCancel(wantsIntent) && wantsIntent) {
+    const goalsInput = await p2.text({
+      message: "What are you trying to accomplish with this data?",
+      placeholder: "e.g., Analyze coffee shop site selection using demographic and market signals"
+    });
+    if (p2.isCancel(goalsInput)) {
+      p2.cancel("Setup cancelled.");
+      await adapter.disconnect();
+      return void 0;
+    }
+    const metricsInput = await p2.text({
+      message: "What metrics or outcomes matter most? (optional)",
+      placeholder: "e.g., opportunity score, supply saturation, demand signals"
+    });
+    const audienceInput = await p2.text({
+      message: "Who will consume this data? (optional)",
+      placeholder: "e.g., AI agents writing SQL, analysts building dashboards"
+    });
+    intent = {
+      goals: goalsInput,
+      metrics: p2.isCancel(metricsInput) ? void 0 : metricsInput || void 0,
+      audience: p2.isCancel(audienceInput) ? void 0 : audienceInput || void 0
+    };
+  }
+  const configPath = path14.join(cwd, "contextkit.config.yaml");
   let config;
   try {
     config = loadConfig10(cwd);
@@ -1804,7 +2703,7 @@ async function runConnectStep() {
     writeFileSync5(configPath, yaml2.stringify(newConfig, { lineWidth: 120 }), "utf-8");
     config = loadConfig10(cwd);
   }
-  const contextDir = path13.resolve(cwd, config.context_dir ?? "./context");
+  const contextDir = path14.resolve(cwd, config.context_dir ?? "./context");
   return {
     cwd,
     contextDir,
@@ -1813,31 +2712,32 @@ async function runConnectStep() {
     tables,
     columns,
     modelName: modelInput,
-    targetTier: tierInput
+    targetTier: tierInput,
+    intent
   };
 }
 
 // src/setup/steps/scaffold.ts
-import * as p3 from "@clack/prompts";
-import path14 from "path";
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync6, existsSync as existsSync4 } from "fs";
+import * as p4 from "@clack/prompts";
+import path15 from "path";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync6, existsSync as existsSync5 } from "fs";
 import { scaffoldFromSchema as scaffoldFromSchema2, compile as compile10, computeTier as computeTier3, loadConfig as loadConfig11 } from "@runcontext/core";
 
 // src/setup/display.ts
-import * as p2 from "@clack/prompts";
+import * as p3 from "@clack/prompts";
 function displayTierScore(score) {
-  p2.note(formatTierScore(score), "Tier Scorecard");
+  p3.note(formatTierScore(score), "Tier Scorecard");
 }
 
 // src/setup/steps/scaffold.ts
 async function runScaffoldStep(ctx) {
-  const shouldRun = await p3.confirm({
+  const shouldRun = await p4.confirm({
     message: "Scaffold Bronze metadata from database schema?"
   });
-  if (p3.isCancel(shouldRun) || !shouldRun) {
+  if (p4.isCancel(shouldRun) || !shouldRun) {
     return { skipped: true, summary: "Skipped" };
   }
-  const spin = p3.spinner();
+  const spin = p4.spinner();
   spin.start("Scaffolding Bronze metadata...");
   const result = scaffoldFromSchema2({
     modelName: ctx.modelName,
@@ -1845,18 +2745,40 @@ async function runScaffoldStep(ctx) {
     tables: ctx.tables,
     columns: ctx.columns
   });
-  for (const dir of ["models", "governance", "owners"]) {
-    const dirPath = path14.join(ctx.contextDir, dir);
-    if (!existsSync4(dirPath)) mkdirSync3(dirPath, { recursive: true });
+  for (const dir of ["models", "governance", "owners", "reference"]) {
+    const dirPath = path15.join(ctx.contextDir, dir);
+    if (!existsSync5(dirPath)) mkdirSync3(dirPath, { recursive: true });
+  }
+  const refReadme = path15.join(ctx.contextDir, "reference", "README.md");
+  if (!existsSync5(refReadme)) {
+    writeFileSync6(refReadme, `# Reference Documents
+
+Drop files here that help describe your data \u2014 the AI agent will read them when curating metadata.
+
+Examples of useful reference documents:
+- Data dictionaries (CSV, Excel, PDF)
+- Confluence or wiki exports
+- ERD diagrams or schema docs
+- Business glossaries from your organization
+- Dashboard screenshots or descriptions
+- Data pipeline documentation
+- Slack/email threads explaining metric definitions
+
+The agent will use these as context when writing descriptions, defining metrics,
+creating glossary terms, and building business context. The more context you
+provide, the better the metadata quality.
+
+Supported formats: .md, .txt, .csv, .json, .yaml, .pdf
+`, "utf-8");
   }
   const created = [];
   const files = [
-    { rel: path14.join("models", result.files.osi), content: result.osiYaml },
-    { rel: path14.join("governance", result.files.governance), content: result.governanceYaml },
-    { rel: path14.join("owners", result.files.owner), content: result.ownerYaml }
+    { rel: path15.join("models", result.files.osi), content: result.osiYaml },
+    { rel: path15.join("governance", result.files.governance), content: result.governanceYaml },
+    { rel: path15.join("owners", result.files.owner), content: result.ownerYaml }
   ];
   for (const f of files) {
-    const fullPath = path14.join(ctx.contextDir, f.rel);
+    const fullPath = path15.join(ctx.contextDir, f.rel);
     writeFileSync6(fullPath, f.content, "utf-8");
     created.push(f.rel);
   }
@@ -1866,15 +2788,15 @@ async function runScaffoldStep(ctx) {
   ctx.tierScore = computeTier3(ctx.modelName, graph);
   spin.stop(`Created ${created.length} files`);
   const fileList = created.map((f) => `  ${f}`).join("\n");
-  p3.note(fileList, "Files Created");
+  p4.note(fileList, "Files Created");
   displayTierScore(ctx.tierScore);
   return { skipped: false, summary: `${created.length} files \u2192 ${ctx.tierScore.tier.toUpperCase()}` };
 }
 
 // src/setup/steps/enrich-silver.ts
-import * as p4 from "@clack/prompts";
-import path15 from "path";
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync5, readdirSync as readdirSync2 } from "fs";
+import * as p5 from "@clack/prompts";
+import path16 from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync6, readdirSync as readdirSync2 } from "fs";
 import * as yaml3 from "yaml";
 import {
   compile as compile11,
@@ -1883,10 +2805,10 @@ import {
   loadConfig as loadConfig12
 } from "@runcontext/core";
 function findFileRecursive2(dir, suffix) {
-  if (!existsSync5(dir)) return void 0;
+  if (!existsSync6(dir)) return void 0;
   const entries = readdirSync2(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = path15.join(dir, entry.name);
+    const fullPath = path16.join(dir, entry.name);
     if (entry.isDirectory()) {
       const found = findFileRecursive2(fullPath, suffix);
       if (found) return found;
@@ -1902,13 +2824,13 @@ async function runEnrichSilverStep(ctx) {
   ctx.graph = graph;
   const tierScore = computeTier4(ctx.modelName, graph);
   if (tierScore.silver.passed) {
-    p4.log.success("Already at Silver or above \u2014 skipping.");
+    p5.log.success("Already at Silver or above \u2014 skipping.");
     ctx.tierScore = tierScore;
     return { skipped: true, summary: "Already Silver" };
   }
   const model = graph.models.get(ctx.modelName);
   if (!model) {
-    p4.log.error(`Model "${ctx.modelName}" not found in graph.`);
+    p5.log.error(`Model "${ctx.modelName}" not found in graph.`);
     return { skipped: true, summary: "Model not found" };
   }
   const datasetNames = model.datasets.map((d) => d.name);
@@ -1921,19 +2843,19 @@ async function runEnrichSilverStep(ctx) {
   if (suggestions.glossaryTerms) preview.push(`+ ${suggestions.glossaryTerms.length} glossary term(s)`);
   if (suggestions.needsSampleValues) preview.push("+ sample_values from live data");
   if (preview.length > 0) {
-    p4.note(preview.join("\n"), "Silver Enrichments");
+    p5.note(preview.join("\n"), "Silver Enrichments");
   }
-  const shouldRun = await p4.confirm({
+  const shouldRun = await p5.confirm({
     message: "Apply Silver enrichments?"
   });
-  if (p4.isCancel(shouldRun) || !shouldRun) {
+  if (p5.isCancel(shouldRun) || !shouldRun) {
     return { skipped: true, summary: "Skipped" };
   }
-  const spin = p4.spinner();
+  const spin = p5.spinner();
   spin.start("Enriching to Silver...");
   const govFilePath = findFileRecursive2(ctx.contextDir, `${ctx.modelName}.governance.yaml`);
   if (govFilePath) {
-    const govContent = readFileSync5(govFilePath, "utf-8");
+    const govContent = readFileSync7(govFilePath, "utf-8");
     const govDoc = yaml3.parse(govContent) ?? {};
     if (suggestions.governance?.trust) govDoc.trust = suggestions.governance.trust;
     if (suggestions.governance?.tags) govDoc.tags = suggestions.governance.tags;
@@ -1972,20 +2894,20 @@ async function runEnrichSilverStep(ctx) {
     writeFileSync7(govFilePath, yaml3.stringify(govDoc, { lineWidth: 120 }), "utf-8");
   }
   if (suggestions.lineage) {
-    const lineageDir = path15.join(ctx.contextDir, "lineage");
-    if (!existsSync5(lineageDir)) mkdirSync4(lineageDir, { recursive: true });
-    const lineagePath = path15.join(lineageDir, `${ctx.modelName}.lineage.yaml`);
-    if (!existsSync5(lineagePath)) {
+    const lineageDir = path16.join(ctx.contextDir, "lineage");
+    if (!existsSync6(lineageDir)) mkdirSync4(lineageDir, { recursive: true });
+    const lineagePath = path16.join(lineageDir, `${ctx.modelName}.lineage.yaml`);
+    if (!existsSync6(lineagePath)) {
       const lineageDoc = { model: ctx.modelName, upstream: suggestions.lineage.upstream };
       writeFileSync7(lineagePath, yaml3.stringify(lineageDoc, { lineWidth: 120 }), "utf-8");
     }
   }
   if (suggestions.glossaryTerms) {
-    const glossaryDir = path15.join(ctx.contextDir, "glossary");
-    if (!existsSync5(glossaryDir)) mkdirSync4(glossaryDir, { recursive: true });
+    const glossaryDir = path16.join(ctx.contextDir, "glossary");
+    if (!existsSync6(glossaryDir)) mkdirSync4(glossaryDir, { recursive: true });
     for (const term of suggestions.glossaryTerms) {
-      const termPath = path15.join(glossaryDir, `${term.id}.term.yaml`);
-      if (!existsSync5(termPath)) {
+      const termPath = path16.join(glossaryDir, `${term.id}.term.yaml`);
+      if (!existsSync6(termPath)) {
         writeFileSync7(termPath, yaml3.stringify(term, { lineWidth: 120 }), "utf-8");
       }
     }
@@ -1999,9 +2921,9 @@ async function runEnrichSilverStep(ctx) {
 }
 
 // src/setup/steps/enrich-gold.ts
-import * as p5 from "@clack/prompts";
-import path16 from "path";
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync8, mkdirSync as mkdirSync5, existsSync as existsSync6, readdirSync as readdirSync3 } from "fs";
+import * as p6 from "@clack/prompts";
+import path17 from "path";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync8, mkdirSync as mkdirSync5, existsSync as existsSync7, readdirSync as readdirSync3 } from "fs";
 import * as yaml4 from "yaml";
 import {
   compile as compile12,
@@ -2012,10 +2934,10 @@ import {
   loadConfig as loadConfig13
 } from "@runcontext/core";
 function findFileRecursive3(dir, suffix) {
-  if (!existsSync6(dir)) return void 0;
+  if (!existsSync7(dir)) return void 0;
   const entries = readdirSync3(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = path16.join(dir, entry.name);
+    const fullPath = path17.join(dir, entry.name);
     if (entry.isDirectory()) {
       const found = findFileRecursive3(fullPath, suffix);
       if (found) return found;
@@ -2031,13 +2953,13 @@ async function runEnrichGoldStep(ctx) {
   ctx.graph = graph;
   const tierScore = computeTier5(ctx.modelName, graph);
   if (tierScore.gold.passed) {
-    p5.log.success("Already at Gold \u2014 skipping.");
+    p6.log.success("Already at Gold \u2014 skipping.");
     ctx.tierScore = tierScore;
     return { skipped: true, summary: "Already Gold" };
   }
   const model = graph.models.get(ctx.modelName);
   if (!model) {
-    p5.log.error(`Model "${ctx.modelName}" not found.`);
+    p6.log.error(`Model "${ctx.modelName}" not found.`);
     return { skipped: true, summary: "Model not found" };
   }
   const datasetNames = model.datasets.map((d) => d.name);
@@ -2050,20 +2972,20 @@ async function runEnrichGoldStep(ctx) {
   preview.push("+ Add ai_context placeholder to model");
   preview.push("+ Infer relationships from column name patterns");
   if (preview.length > 0) {
-    p5.note(preview.join("\n"), "Gold Enrichments");
+    p6.note(preview.join("\n"), "Gold Enrichments");
   }
-  p5.log.warning("Gold enrichments create TODO placeholders that need manual curation.");
-  const shouldRun = await p5.confirm({
+  p6.log.warning("Gold enrichments create TODO placeholders that need manual curation.");
+  const shouldRun = await p6.confirm({
     message: "Apply Gold enrichments?"
   });
-  if (p5.isCancel(shouldRun) || !shouldRun) {
+  if (p6.isCancel(shouldRun) || !shouldRun) {
     return { skipped: true, summary: "Skipped" };
   }
-  const spin = p5.spinner();
+  const spin = p6.spinner();
   spin.start("Enriching to Gold...");
   const govFilePath = findFileRecursive3(ctx.contextDir, `${ctx.modelName}.governance.yaml`);
   if (govFilePath) {
-    const govContent = readFileSync6(govFilePath, "utf-8");
+    const govContent = readFileSync8(govFilePath, "utf-8");
     const govDoc = yaml4.parse(govContent) ?? {};
     if (suggestions.governance?.trust) govDoc.trust = suggestions.governance.trust;
     if (suggestions.needsSemanticRoles) {
@@ -2103,7 +3025,7 @@ async function runEnrichGoldStep(ctx) {
   }
   const modelFilePath = findFileRecursive3(ctx.contextDir, `${ctx.modelName}.osi.yaml`);
   if (modelFilePath) {
-    const modelContent = readFileSync6(modelFilePath, "utf-8");
+    const modelContent = readFileSync8(modelFilePath, "utf-8");
     const modelDoc = yaml4.parse(modelContent) ?? {};
     const semModels = modelDoc.semantic_model ?? [];
     let changed = false;
@@ -2156,10 +3078,10 @@ async function runEnrichGoldStep(ctx) {
     }
   }
   if (suggestions.needsRulesFile) {
-    const rulesDir = path16.join(ctx.contextDir, "rules");
-    if (!existsSync6(rulesDir)) mkdirSync5(rulesDir, { recursive: true });
-    const rulesPath = path16.join(rulesDir, `${ctx.modelName}.rules.yaml`);
-    if (!existsSync6(rulesPath)) {
+    const rulesDir = path17.join(ctx.contextDir, "rules");
+    if (!existsSync7(rulesDir)) mkdirSync5(rulesDir, { recursive: true });
+    const rulesPath = path17.join(rulesDir, `${ctx.modelName}.rules.yaml`);
+    if (!existsSync7(rulesPath)) {
       const rulesDoc = {
         model: ctx.modelName,
         golden_queries: [
@@ -2185,13 +3107,13 @@ async function runEnrichGoldStep(ctx) {
   ctx.tierScore = computeTier5(ctx.modelName, newGraph);
   spin.stop("Applied Gold enrichments");
   const todos = suggestions.needsRulesFile ? "\nThe rules file contains TODO placeholders \u2014 edit context/rules/ to complete Gold." : "";
-  if (todos) p5.log.warning(todos);
+  if (todos) p6.log.warning(todos);
   displayTierScore(ctx.tierScore);
   return { skipped: false, summary: `${ctx.tierScore.tier.toUpperCase()} (may need curation)` };
 }
 
 // src/setup/steps/verify.ts
-import * as p6 from "@clack/prompts";
+import * as p7 from "@clack/prompts";
 import {
   compile as compile13,
   LintEngine as LintEngine5,
@@ -2200,13 +3122,13 @@ import {
   loadConfig as loadConfig14
 } from "@runcontext/core";
 async function runVerifyStep(ctx) {
-  const shouldRun = await p6.confirm({
+  const shouldRun = await p7.confirm({
     message: "Verify metadata against live data?"
   });
-  if (p6.isCancel(shouldRun) || !shouldRun) {
+  if (p7.isCancel(shouldRun) || !shouldRun) {
     return { skipped: true, summary: "Skipped" };
   }
-  const spin = p6.spinner();
+  const spin = p7.spinner();
   spin.start("Verifying against database...");
   const config = loadConfig14(ctx.cwd);
   const { graph } = await compile13({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
@@ -2225,7 +3147,7 @@ async function runVerifyStep(ctx) {
   } else {
     spin.stop(`${errors} error(s), ${warnings} warning(s)`);
     const details = dataDiags.map((d) => `  ${d.severity === "error" ? "x" : "!"} ${d.message}`).join("\n");
-    p6.note(details, "Data Validation Issues");
+    p7.note(details, "Data Validation Issues");
   }
   return {
     skipped: false,
@@ -2234,8 +3156,8 @@ async function runVerifyStep(ctx) {
 }
 
 // src/setup/steps/autofix.ts
-import * as p7 from "@clack/prompts";
-import fs4 from "fs";
+import * as p8 from "@clack/prompts";
+import fs5 from "fs";
 import {
   compile as compile14,
   LintEngine as LintEngine6,
@@ -2253,23 +3175,23 @@ async function runAutofixStep(ctx) {
   const diagnostics = engine.run(graph);
   const fixable = diagnostics.filter((d) => d.fixable);
   if (fixable.length === 0) {
-    p7.log.success("No fixable issues found.");
+    p8.log.success("No fixable issues found.");
     ctx.graph = graph;
     ctx.tierScore = computeTier7(ctx.modelName, graph);
     return { skipped: true, summary: "Nothing to fix" };
   }
-  const shouldRun = await p7.confirm({
+  const shouldRun = await p8.confirm({
     message: `Auto-fix ${fixable.length} issue(s)?`
   });
-  if (p7.isCancel(shouldRun) || !shouldRun) {
+  if (p8.isCancel(shouldRun) || !shouldRun) {
     return { skipped: true, summary: "Skipped" };
   }
-  const spin = p7.spinner();
+  const spin = p8.spinner();
   spin.start("Fixing...");
-  const readFile = (filePath) => fs4.readFileSync(filePath, "utf-8");
+  const readFile = (filePath) => fs5.readFileSync(filePath, "utf-8");
   const fixedFiles = applyFixes4(fixable, readFile);
   for (const [file, content] of fixedFiles) {
-    fs4.writeFileSync(file, content, "utf-8");
+    fs5.writeFileSync(file, content, "utf-8");
   }
   const { graph: newGraph } = await compile14({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
   ctx.graph = newGraph;
@@ -2280,12 +3202,14 @@ async function runAutofixStep(ctx) {
 }
 
 // src/setup/steps/claude-md.ts
-import * as p8 from "@clack/prompts";
-import path17 from "path";
-import { existsSync as existsSync7, writeFileSync as writeFileSync9 } from "fs";
-function buildClaudeMd(ctx) {
+import * as p9 from "@clack/prompts";
+import path18 from "path";
+import { existsSync as existsSync8, writeFileSync as writeFileSync9 } from "fs";
+function buildAgentInstructions(ctx) {
   const modelName = ctx.modelName;
   const tier = ctx.tierScore?.tier?.toUpperCase() ?? "UNKNOWN";
+  const tableList = ctx.tables.map((t) => t.name).join(", ");
+  const dbInfo = ctx.dsConfig.path ?? ctx.dsConfig.connection ?? "configured";
   const model = ctx.graph?.models.get(modelName);
   const datasets = model?.datasets ?? [];
   const datasetList = datasets.map((ds) => `- \`${ds.name}\` \u2014 ${ds.fields?.length ?? 0} fields`).join("\n");
@@ -2304,13 +3228,24 @@ function buildClaudeMd(ctx) {
   const failingSection = failingChecks.length > 0 ? `### Failing Checks
 
 ${failingChecks.join("\n")}` : "All checks passing.";
-  return `# ContextKit Agent Instructions
+  const intentSection = ctx.intent ? `## Project Goals
+
+${ctx.intent.goals}
+${ctx.intent.metrics ? `
+**Key metrics/outcomes:** ${ctx.intent.metrics}` : ""}
+${ctx.intent.audience ? `
+**Audience:** ${ctx.intent.audience}` : ""}
 
-You have two MCP servers: **duckdb** (query data) and **contextkit** (query metadata).
+Use these goals to prioritize which datasets, fields, and metrics to curate first.
+
+` : "";
+  return `# ContextKit Agent Instructions
 
 Model: **${modelName}** | Current Tier: **${tier}**
+Database: ${ctx.dsConfig.adapter} (${dbInfo})
+Tables: ${tableList}
 
-## The Cardinal Rule: Never Fabricate Metadata
+${intentSection}## The Cardinal Rule: Never Fabricate Metadata
 
 **Every piece of metadata you write must be grounded in evidence from the actual data.**
 
@@ -2322,24 +3257,102 @@ Model: **${modelName}** | Current Tier: **${tier}**
 - NEVER write a business_context narrative you can't justify from the data
 - NEVER create a glossary definition that is just "Definition for X"
 
-If you don't know something, say so. Leave it as a TODO with a note about what you'd need to determine the answer. A honest TODO is infinitely better than fabricated metadata that looks plausible but is wrong.
+If you don't know something, **ask the user**. A honest "I'm not sure \u2014 can you tell me what this field means?" is infinitely better than fabricated metadata that looks plausible but is wrong.
+
+## Reference Documents
+
+Check \`context/reference/\` for any files the user has provided \u2014 data dictionaries, Confluence exports, ERDs, business glossaries, dashboard docs, etc. **Read these first** before querying the database. They contain domain knowledge that will dramatically improve your metadata quality.
+
+If the folder is empty, ask the user: "Do you have any existing documentation about this data? Data dictionaries, wiki pages, spreadsheets? Drop them in context/reference/ and I'll use them."
 
 ## On Session Start
 
-1. Run \`context_tier\` to check the current metadata tier (Bronze/Silver/Gold)
-2. Report the current tier and list failing checks
-3. Ask the user what they'd like to work on \u2014 don't start changing files unprompted
+1. Check \`context/reference/\` for any reference documents \u2014 read them if present
+2. Run \`context tier\` to check the current metadata tier (Bronze/Silver/Gold)
+3. Report the current tier and summarize failing checks
+4. Ask the user what they'd like to focus on \u2014 don't start changing files unprompted
+5. If the user says "get me to Gold" or "build my semantic layer," follow the iterative workflow below
+
+## The Iterative Workflow
+
+Building a semantic layer is a **conversation**. You and the user go back and forth \u2014 you query the data, propose metadata, ask questions, and iterate. Here's the loop:
+
+\`\`\`
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502   context tier           \u2502
+                    \u2502   (check failing checks) \u2502
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                               \u2502
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502  Pick highest-impact     \u2502
+                    \u2502  failing check           \u2502
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                               \u2502
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502  Query the database      \u2502
+                    \u2502  to gather evidence      \u2502
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                               \u2502
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502  Need user input?        \u2502\u2500\u2500\u2500\u2500 YES \u2500\u2500\u2192 Ask the user
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518              (then continue)
+                               \u2502 NO
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502  Edit YAML metadata      \u2502
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                               \u2502
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502  context lint            \u2502
+                    \u2502  context tier            \u2502
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                               \u2502
+                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+                    \u2502  All Gold checks pass?   \u2502\u2500\u2500\u2500\u2500 NO \u2500\u2500\u2192 Loop back
+                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                               \u2502 YES
+                            \u2713 DONE
+\`\`\`
+
+### What to Ask the User About
+
+You know the data. The user knows the business. Ask them about:
 
-## When Asked to Reach Gold
+- **Ownership** \u2014 "Who owns this data? What team maintains it?"
+- **Metric intent** \u2014 "Should revenue be summed or averaged? Is this an additive metric?"
+- **Business rules** \u2014 "Are there any filters that should always be applied? (e.g., only active records)"
+- **Data lineage** \u2014 "Where does this data come from originally? What upstream system?"
+- **Use cases** \u2014 "What questions do people ask this data? What dashboards use it?"
+- **Glossary terms** \u2014 "What does 'churn rate' mean in your organization?"
+- **Data quality** \u2014 "I see 15% null values in this column \u2014 is that expected?"
 
-Work through ALL failing Gold checks iteratively until \`context tier\` reports Gold:
+Don't batch all questions at once. Ask as you encounter each field or concept that needs clarification.
 
-1. Run \`context_tier\` and collect every failing check
+### CLI Commands to Use
+
+\`\`\`bash
+# Check where you are
+context tier                    # Show Bronze/Silver/Gold scorecard with failing checks
+context lint                    # Run all 40 lint rules
+context explain ${modelName}     # Full model details \u2014 governance, rules, lineage, tier
+
+# Build and fix
+context enrich --target silver --apply --source default  # Auto-enrich to Silver
+context fix --write             # Auto-fix lint issues where possible
+context verify                  # Validate metadata against the live database
+
+# Serve to other agents
+context serve --stdio           # Start MCP server (for Claude, Cursor, etc.)
+context dev --studio            # Open visual editor in browser
+\`\`\`
+
+### Do NOT Stop Until Gold
+
+1. Run \`context tier\` and collect every failing check
 2. For each failing check, query the database to gather evidence, then fix the metadata
-3. Run \`context_tier\` again
+3. Run \`context tier\` again
 4. If checks still fail, go back to step 2
-5. **Do NOT stop until every Gold check passes** or you hit something that genuinely requires human input (like real owner contact info)
-6. For checks you cannot fix (e.g., owner email), leave a clear TODO explaining what a human needs to provide
+5. **Do NOT stop until every Gold check passes** or you hit something that genuinely requires human input
+6. For checks you cannot fix, ask the user or leave a clear TODO explaining what's needed
 
 You must iterate \u2014 a single pass is never enough. Each \`context tier\` run may reveal new failures after earlier ones are fixed.
 
@@ -2441,7 +3454,7 @@ ${datasetList || "(none detected)"}
 
 ${failingSection}
 
-## MCP Tools
+## MCP Tools (if using ContextKit as an MCP server)
 
 | Tool | Parameters | What it does |
 |------|-----------|-------------|
@@ -2593,36 +3606,40 @@ hierarchies:
     dataset: my_table
 \`\`\`
 
-## CLI Commands
+## File Structure
 
-\`\`\`bash
-context tier                  # Check scorecard
-context verify --db <path>    # Validate against live data
-context fix --db <path>       # Auto-fix data warnings
-context setup                 # Interactive setup wizard
-context dev                   # Watch mode for live editing
+\`\`\`
+context/
+  models/*.osi.yaml              # OSI semantic model (schema, relationships, metrics)
+  governance/*.governance.yaml   # Ownership, trust, security, semantic roles
+  rules/*.rules.yaml             # Golden queries, business rules, guardrails
+  lineage/*.lineage.yaml         # Upstream sources
+  glossary/*.term.yaml           # Business term definitions
+  owners/*.owner.yaml            # Team ownership records
+  reference/                     # User-provided docs (data dictionaries, wiki exports, etc.)
+  AGENT_INSTRUCTIONS.md          # This file
 \`\`\`
 `;
 }
-async function runClaudeMdStep(ctx) {
-  const instructionsPath = path17.join(ctx.contextDir, "AGENT_INSTRUCTIONS.md");
-  if (existsSync7(instructionsPath)) {
-    const shouldOverwrite = await p8.confirm({
+async function runAgentInstructionsStep(ctx) {
+  const instructionsPath = path18.join(ctx.contextDir, "AGENT_INSTRUCTIONS.md");
+  if (existsSync8(instructionsPath)) {
+    const shouldOverwrite = await p9.confirm({
       message: "context/AGENT_INSTRUCTIONS.md already exists. Overwrite with updated instructions?"
     });
-    if (p8.isCancel(shouldOverwrite) || !shouldOverwrite) {
+    if (p9.isCancel(shouldOverwrite) || !shouldOverwrite) {
       return { skipped: true, summary: "context/AGENT_INSTRUCTIONS.md already exists, kept existing" };
     }
   }
-  const content = buildClaudeMd(ctx);
+  const content = buildAgentInstructions(ctx);
   writeFileSync9(instructionsPath, content, "utf-8");
-  p8.log.success("Generated context/AGENT_INSTRUCTIONS.md with agent curation instructions");
+  p9.log.success("Generated context/AGENT_INSTRUCTIONS.md \u2014 the agent curation guide");
   return { skipped: false, summary: "Generated context/AGENT_INSTRUCTIONS.md" };
 }
 
 // src/commands/setup.ts
-var setupCommand = new Command15("setup").description("Interactive wizard to scaffold and enrich metadata from a database").action(async () => {
-  p9.intro(chalk16.bgCyan(chalk16.black(" ContextKit Setup ")));
+var setupCommand = new Command15("setup").description("Interactive wizard \u2014 detects databases, introspects schema, scaffolds metadata, enriches to Silver, generates agent instructions. Supports DuckDB, PostgreSQL, MySQL, SQL Server, SQLite, Snowflake, BigQuery, ClickHouse, and Databricks.").action(async () => {
+  p10.intro(chalk16.bgCyan(chalk16.black(" ContextKit Setup ")));
   const ctx = await runConnectStep();
   if (!ctx) return;
   try {
@@ -2638,39 +3655,42 @@ var setupCommand = new Command15("setup").description("Interactive wizard to sca
     steps.push(
       { name: "Verify data", fn: runVerifyStep },
       { name: "Auto-fix", fn: runAutofixStep },
-      { name: "Generate agent instructions", fn: runClaudeMdStep }
+      { name: "Generate agent instructions", fn: runAgentInstructionsStep }
     );
     const results = [];
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
-      p9.log.step(`${chalk16.dim(`[${i + 1}/${steps.length}]`)} ${step.name}`);
+      p10.log.step(`${chalk16.dim(`[${i + 1}/${steps.length}]`)} ${step.name}`);
       const result = await step.fn(ctx);
       results.push({ name: step.name, summary: result.summary });
     }
     const summaryLines = results.map((r) => `  ${chalk16.green("+")} ${r.name}: ${r.summary}`).join("\n");
-    p9.note(summaryLines, "Summary");
+    p10.note(summaryLines, "Summary");
     if (ctx.tierScore) {
       displayTierScore(ctx.tierScore);
     }
     const currentTier = ctx.tierScore?.tier ?? "none";
     const reachedTarget = ctx.targetTier === "bronze" && ["bronze", "silver", "gold"].includes(currentTier) || ctx.targetTier === "silver" && ["silver", "gold"].includes(currentTier) || ctx.targetTier === "gold" && currentTier === "gold";
     if (reachedTarget) {
-      p9.outro(`Done! You're at ${chalk16.bold(currentTier.toUpperCase())}. Run ${chalk16.cyan("context tier")} anytime to check.`);
+      p10.outro(`Done! You're at ${chalk16.bold(currentTier.toUpperCase())}. Run ${chalk16.cyan("context tier")} anytime to check.`);
     } else if (ctx.targetTier === "gold" && currentTier !== "gold") {
       const nextSteps = [
-        `Your metadata is at ${chalk16.bold(currentTier.toUpperCase())} \u2014 Gold needs curation.`,
+        `Your metadata is at ${chalk16.bold(currentTier.toUpperCase())} \u2014 Gold needs human curation.`,
         "",
-        `${chalk16.bold("To reach Gold, tell your AI assistant:")}`,
+        `${chalk16.bold("If you're an AI agent:")}`,
+        `  Read ${chalk16.cyan("context/AGENT_INSTRUCTIONS.md")} for the full curation guide.`,
+        `  Run ${chalk16.cyan("context tier")} \u2192 pick a failing check \u2192 query the database \u2192 fix it \u2192 repeat.`,
+        `  Ask the user about ownership, metric intent, and business rules as you go.`,
         "",
-        `  "Read ${chalk16.cyan("context/AGENT_INSTRUCTIONS.md")} for curation guidelines.`,
-        `   Run ${chalk16.cyan("context tier")} and fix every failing Gold check.`,
-        `   Query the database before writing any metadata.`,
-        `   Keep iterating until ${chalk16.cyan("context tier")} reports Gold."`
+        `${chalk16.bold("If you're a human:")}`,
+        `  Tell your AI agent: "Read context/AGENT_INSTRUCTIONS.md and get this project to Gold."`,
+        `  The agent will go back and forth with you, asking about your data as it builds.`,
+        `  Or use ${chalk16.cyan("context dev --studio")} to edit metadata visually in the browser.`
       ];
-      p9.note(nextSteps.join("\n"), "Next Steps");
-      p9.outro(`Run ${chalk16.cyan("context dev")} to watch for changes as you edit.`);
+      p10.note(nextSteps.join("\n"), "Next Steps");
+      p10.outro(`Run ${chalk16.cyan("context tier")} to check your scorecard.`);
     } else {
-      p9.outro(`Run ${chalk16.cyan("context tier")} to check your scorecard.`);
+      p10.outro(`Run ${chalk16.cyan("context tier")} to check your scorecard.`);
     }
   } finally {
     try {
@@ -2680,9 +3700,438 @@ var setupCommand = new Command15("setup").description("Interactive wizard to sca
   }
 });
 
+// src/commands/blueprint.ts
+import { Command as Command16 } from "commander";
+import chalk17 from "chalk";
+import path19 from "path";
+import fs6 from "fs";
+import { compile as compile15, loadConfig as loadConfig16, emitManifest as emitManifest3 } from "@runcontext/core";
+var blueprintCommand = new Command16("blueprint").description("Export AI Blueprints \u2014 portable, Gold-tier data product specs (OSI v1.0 YAML)").argument("[model]", "Model name to export (omit for all models)").option("--context-dir <path>", "Path to context directory").option("--out <path>", "Output directory for blueprint files", "./blueprints").option("--stdout", "Print to stdout instead of writing files").action(async (modelArg, opts) => {
+  try {
+    const config = loadConfig16(process.cwd());
+    const contextDir = opts.contextDir ? path19.resolve(opts.contextDir) : path19.resolve(config.context_dir);
+    const { graph, diagnostics } = await compile15({ contextDir, config, rootDir: process.cwd() });
+    const errors = diagnostics.filter((d) => d.severity === "error");
+    if (errors.length > 0) {
+      console.error(chalk17.red(`Build failed with ${errors.length} error(s). Run "context build" to see details.`));
+      process.exit(1);
+    }
+    const manifest = emitManifest3(graph, config);
+    const modelNames = modelArg ? [modelArg] : Object.keys(manifest.models);
+    if (modelNames.length === 0) {
+      console.error(chalk17.yellow('No models found. Run "context introspect" first.'));
+      process.exit(1);
+    }
+    if (modelArg && !manifest.models[modelArg]) {
+      const available = Object.keys(manifest.models).join(", ");
+      console.error(formatError(`Model "${modelArg}" not found. Available: ${available}`));
+      process.exit(1);
+    }
+    if (!opts.stdout) {
+      const outDir = path19.resolve(opts.out);
+      fs6.mkdirSync(outDir, { recursive: true });
+    }
+    for (const name of modelNames) {
+      const yaml6 = emitBlueprint(name, manifest);
+      if (opts.stdout) {
+        if (modelNames.length > 1) {
+          console.log(chalk17.gray(`# \u2500\u2500 ${name} ${"\u2500".repeat(60 - name.length)}`));
+        }
+        console.log(yaml6);
+      } else {
+        const outDir = path19.resolve(opts.out);
+        const filePath = path19.join(outDir, `${name}.data-product.osi.yaml`);
+        fs6.writeFileSync(filePath, yaml6, "utf-8");
+        console.log(formatSuccess(`${filePath}`));
+      }
+    }
+    if (!opts.stdout) {
+      const outDir = path19.resolve(opts.out);
+      console.log(
+        chalk17.blue(`
+${modelNames.length} AI Blueprint(s) written to ${outDir}/`)
+      );
+      console.log(chalk17.gray("These portable YAML files contain the full semantic spec for each data product."));
+      console.log(chalk17.gray("Share them, serve them via MCP, or import them into any OSI-compliant tool."));
+    }
+  } catch (err) {
+    console.error(formatError(err.message));
+    process.exit(1);
+  }
+});
+function emitBlueprint(name, manifest) {
+  const model = manifest.models[name];
+  const governance = manifest.governance[name];
+  const rules = manifest.rules[name];
+  const tier = manifest.tiers[name];
+  const lines = [];
+  lines.push(`# ${name}.data-product.osi.yaml`);
+  lines.push(`# AI Blueprint \u2014 Open Semantic Interchange (OSI) v1.0`);
+  lines.push(`# The complete semantic spec for this data product, ready for any AI agent`);
+  lines.push(`# Generated by ContextKit (context blueprint)`);
+  lines.push(``);
+  lines.push(`osi_version: "1.0"`);
+  lines.push(``);
+  lines.push(`semantic_model:`);
+  lines.push(`  name: ${name}`);
+  if (model?.description) {
+    lines.push(`  description: >`);
+    wrapText(lines, model.description, 4);
+  }
+  if (governance) {
+    if (governance.owner) lines.push(`  owner: ${governance.owner}`);
+    if (governance.trust) lines.push(`  trust_status: ${governance.trust}`);
+  }
+  if (tier) {
+    lines.push(`  tier: ${tier.tier ?? "bronze"}`);
+  }
+  if (governance?.tags && governance.tags.length > 0) {
+    lines.push(`  tags:`);
+    for (const tag of governance.tags) {
+      lines.push(`    - ${tag}`);
+    }
+  }
+  const relatedTerms = Object.entries(manifest.terms).filter(([, term]) => {
+    const maps = term.maps_to ?? [];
+    return maps.some((m) => m.startsWith(`${name}.`));
+  });
+  if (relatedTerms.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Glossary \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  glossary:`);
+    for (const [, term] of relatedTerms) {
+      lines.push(`    - term: ${term.id}`);
+      if (term.definition) {
+        lines.push(`      definition: >`);
+        wrapText(lines, term.definition, 8);
+      }
+      if (term.synonyms && term.synonyms.length > 0) {
+        lines.push(`      synonyms:`);
+        for (const s of term.synonyms) {
+          lines.push(`        - ${s}`);
+        }
+      }
+      if (term.maps_to && term.maps_to.length > 0) {
+        lines.push(`      related_fields:`);
+        for (const m of term.maps_to) {
+          lines.push(`        - ${m}`);
+        }
+      }
+    }
+  }
+  if (model?.datasets && model.datasets.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Datasets \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  datasets:`);
+    for (const ds of model.datasets) {
+      lines.push(`    - name: ${ds.name}`);
+      if (ds.description) {
+        lines.push(`      description: ${yamlStr(ds.description)}`);
+      }
+      if (ds.source) lines.push(`      source: ${ds.source}`);
+      if (ds.primary_key && ds.primary_key.length > 0) {
+        lines.push(`      primary_key: [${ds.primary_key.join(", ")}]`);
+      }
+      const dsGov = governance?.datasets?.[ds.name];
+      if (dsGov) {
+        if (dsGov.grain) lines.push(`      grain: ${dsGov.grain}`);
+        if (dsGov.table_type) lines.push(`      table_type: ${dsGov.table_type}`);
+      }
+      if (ds.ai_context) {
+        emitAiContext(lines, ds.ai_context, 6);
+      }
+      if (ds.fields && ds.fields.length > 0) {
+        lines.push(`      fields:`);
+        for (const f of ds.fields) {
+          lines.push(`        - name: ${f.name}`);
+          if (f.expression) {
+            const expr = typeof f.expression === "string" ? f.expression : JSON.stringify(f.expression);
+            lines.push(`          expression: ${expr}`);
+          }
+          if (f.description) {
+            lines.push(`          description: ${yamlStr(f.description)}`);
+          }
+          if (f.dimension) lines.push(`          dimension: true`);
+          if (f.label) lines.push(`          label: true`);
+          const fGov = governance?.fields?.[`${ds.name}.${f.name}`] ?? governance?.fields?.[f.name];
+          if (fGov) {
+            if (fGov.semantic_role) lines.push(`          semantic_role: ${fGov.semantic_role}`);
+            if (fGov.default_aggregation) lines.push(`          aggregation: ${fGov.default_aggregation}`);
+            if (fGov.sample_values && fGov.sample_values.length > 0) {
+              lines.push(`          sample_values:`);
+              for (const sv of fGov.sample_values) {
+                lines.push(`            - ${sv}`);
+              }
+            }
+            if (fGov.default_filter) lines.push(`          default_filter: ${yamlStr(fGov.default_filter)}`);
+          }
+          if (f.ai_context) {
+            emitAiContext(lines, f.ai_context, 10);
+          }
+        }
+      }
+    }
+  }
+  if (model?.relationships && model.relationships.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Relationships \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  relationships:`);
+    for (const rel of model.relationships) {
+      lines.push(`    - name: ${rel.name}`);
+      lines.push(`      from:`);
+      lines.push(`        dataset: ${rel.from}`);
+      lines.push(`        columns: [${rel.from_columns.join(", ")}]`);
+      lines.push(`      to:`);
+      lines.push(`        dataset: ${rel.to}`);
+      lines.push(`        columns: [${rel.to_columns.join(", ")}]`);
+      if (rel.cardinality) lines.push(`      cardinality: ${rel.cardinality}`);
+    }
+  }
+  if (model?.metrics && model.metrics.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Metrics \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  metrics:`);
+    for (const met of model.metrics) {
+      lines.push(`    - name: ${met.name}`);
+      if (met.expression) {
+        const expr = typeof met.expression === "string" ? met.expression : JSON.stringify(met.expression);
+        lines.push(`      expression: ${expr}`);
+      }
+      if (met.description) {
+        lines.push(`      description: ${yamlStr(met.description)}`);
+      }
+      if (met.ai_context) {
+        emitAiContext(lines, met.ai_context, 6);
+      }
+    }
+  }
+  if (rules?.business_rules && rules.business_rules.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Business Rules \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  business_rules:`);
+    for (const br of rules.business_rules) {
+      lines.push(`    - name: ${br.name}`);
+      if (br.definition) lines.push(`      definition: ${yamlStr(br.definition)}`);
+      if (br.enforcement && br.enforcement.length > 0) {
+        lines.push(`      enforcement:`);
+        for (const e of br.enforcement) {
+          lines.push(`        - ${yamlStr(e)}`);
+        }
+      }
+      if (br.avoid && br.avoid.length > 0) {
+        lines.push(`      avoid:`);
+        for (const a of br.avoid) {
+          lines.push(`        - ${yamlStr(a)}`);
+        }
+      }
+      if (br.applied_always) lines.push(`      applied_always: true`);
+    }
+  }
+  if (rules?.guardrail_filters && rules.guardrail_filters.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Guardrails \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  guardrail_filters:`);
+    for (const gf of rules.guardrail_filters) {
+      lines.push(`    - name: ${gf.name}`);
+      if (gf.reason) lines.push(`      reason: ${yamlStr(gf.reason)}`);
+      if (gf.filter) lines.push(`      filter: ${yamlStr(gf.filter)}`);
+      if (gf.tables && gf.tables.length > 0) {
+        lines.push(`      tables: [${gf.tables.join(", ")}]`);
+      }
+    }
+  }
+  if (rules?.golden_queries && rules.golden_queries.length > 0) {
+    lines.push(``);
+    lines.push(`  # \u2500\u2500 Golden Queries \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    lines.push(`  golden_queries:`);
+    for (const gq of rules.golden_queries) {
+      lines.push(`    - question: ${yamlStr(gq.question)}`);
+      if (gq.intent) lines.push(`      intent: ${yamlStr(gq.intent)}`);
+      if (gq.sql) {
+        lines.push(`      sql: |`);
+        for (const sqlLine of gq.sql.split("\n")) {
+          lines.push(`        ${sqlLine}`);
+        }
+      }
+      if (gq.dialect) lines.push(`      dialect: ${gq.dialect}`);
+      if (gq.caveats) lines.push(`      caveats: ${yamlStr(gq.caveats)}`);
+    }
+  }
+  lines.push(``);
+  return lines.join("\n");
+}
+function emitAiContext(lines, ctx, indent) {
+  const pad = " ".repeat(indent);
+  if (typeof ctx === "string") {
+    lines.push(`${pad}ai_context: ${yamlStr(ctx)}`);
+  } else {
+    lines.push(`${pad}ai_context:`);
+    if (ctx.instructions) {
+      lines.push(`${pad}  instructions: >`);
+      wrapText(lines, ctx.instructions, indent + 4);
+    }
+    if (ctx.synonyms && ctx.synonyms.length > 0) {
+      lines.push(`${pad}  synonyms:`);
+      for (const s of ctx.synonyms) {
+        lines.push(`${pad}    - ${s}`);
+      }
+    }
+    if (ctx.examples && ctx.examples.length > 0) {
+      lines.push(`${pad}  examples:`);
+      for (const e of ctx.examples) {
+        lines.push(`${pad}    - ${yamlStr(e)}`);
+      }
+    }
+  }
+}
+function yamlStr(s) {
+  if (s.includes("\n") || s.includes(": ") || s.includes("#") || s.includes('"') || s.includes("'")) {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+function wrapText(lines, text2, indent) {
+  const pad = " ".repeat(indent);
+  const words = text2.replace(/\n/g, " ").split(/\s+/);
+  let line = "";
+  for (const word of words) {
+    if (line.length + word.length + 1 > 76) {
+      lines.push(`${pad}${line.trim()}`);
+      line = "";
+    }
+    line += word + " ";
+  }
+  if (line.trim()) {
+    lines.push(`${pad}${line.trim()}`);
+  }
+}
+
+// src/commands/new.ts
+import { Command as Command17 } from "commander";
+import chalk18 from "chalk";
+import path20 from "path";
+import fs7 from "fs";
+import * as yaml5 from "yaml";
+import { loadConfig as loadConfig17 } from "@runcontext/core";
+var STARTER_OSI = (name, dataSource) => {
+  const doc = {
+    version: "1.0",
+    semantic_model: [
+      {
+        name,
+        description: `Data product: ${name}`,
+        ...dataSource ? { data_source: dataSource } : {},
+        datasets: []
+      }
+    ]
+  };
+  return yaml5.stringify(doc, { lineWidth: 120 });
+};
+var STARTER_GOVERNANCE = (name) => {
+  const doc = {
+    model: name,
+    owner: "default-team",
+    security: "internal",
+    datasets: {}
+  };
+  return yaml5.stringify(doc, { lineWidth: 120 });
+};
+var STARTER_RULES = (name) => {
+  const doc = {
+    model: name,
+    business_rules: [],
+    guardrail_filters: [],
+    golden_queries: []
+  };
+  return yaml5.stringify(doc, { lineWidth: 120 });
+};
+var STARTER_OWNER = () => {
+  const doc = {
+    id: "default-team",
+    display_name: "Default Team"
+  };
+  return yaml5.stringify(doc, { lineWidth: 120 });
+};
+var newCommand = new Command17("new").description("Scaffold a new data product inside your context directory").argument("<name>", "Name for the data product (e.g. sales-analytics)").option("--source <name>", "Bind to a named data source from contextkit.config.yaml").option("--context-dir <path>", "Path to context directory").action(async (name, opts) => {
+  try {
+    const config = loadConfig17(process.cwd());
+    const contextDir = opts.contextDir ? path20.resolve(opts.contextDir) : path20.resolve(config.context_dir);
+    if (opts.source && config.data_sources) {
+      const sources = config.data_sources;
+      if (!sources[opts.source]) {
+        const available = Object.keys(sources).join(", ");
+        console.error(formatError(
+          `Data source "${opts.source}" not found in contextkit.config.yaml. Available: ${available || "(none)"}`
+        ));
+        process.exit(1);
+      }
+    }
+    const dirs = [
+      path20.join(contextDir, "models"),
+      path20.join(contextDir, "governance"),
+      path20.join(contextDir, "owners"),
+      path20.join(contextDir, "reference")
+    ];
+    for (const dir of dirs) {
+      if (!fs7.existsSync(dir)) fs7.mkdirSync(dir, { recursive: true });
+    }
+    const files = [
+      {
+        rel: path20.join("models", `${name}.osi.yaml`),
+        content: STARTER_OSI(name, opts.source)
+      },
+      {
+        rel: path20.join("governance", `${name}.governance.yaml`),
+        content: STARTER_GOVERNANCE(name)
+      },
+      {
+        rel: path20.join("governance", `${name}.rules.yaml`),
+        content: STARTER_RULES(name)
+      },
+      {
+        rel: path20.join("owners", "default-team.owner.yaml"),
+        content: STARTER_OWNER()
+      }
+    ];
+    const created = [];
+    const skipped = [];
+    for (const f of files) {
+      const fullPath = path20.join(contextDir, f.rel);
+      if (fs7.existsSync(fullPath)) {
+        skipped.push(f.rel);
+      } else {
+        fs7.writeFileSync(fullPath, f.content, "utf-8");
+        created.push(f.rel);
+      }
+    }
+    console.log("");
+    if (created.length > 0) {
+      console.log(formatSuccess(`Data product "${name}" scaffolded`));
+      console.log("");
+      for (const f of created) {
+        console.log(chalk18.green(`  + ${f}`));
+      }
+    }
+    if (skipped.length > 0) {
+      for (const f of skipped) {
+        console.log(chalk18.gray(`  ~ ${f} (exists)`));
+      }
+    }
+    console.log("");
+    console.log(chalk18.gray("Next steps:"));
+    console.log(chalk18.gray(`  1. Run ${chalk18.cyan(`context introspect --db <url>`)} to populate from a database`));
+    console.log(chalk18.gray(`  2. Run ${chalk18.cyan(`context enrich --target silver --apply`)} to auto-fill descriptions`));
+    console.log(chalk18.gray(`  3. Run ${chalk18.cyan(`context tier`)} to check progress toward Gold`));
+    console.log(chalk18.gray(`  4. Run ${chalk18.cyan(`context blueprint ${name}`)} to export the AI Blueprint`));
+  } catch (err) {
+    console.error(formatError(err.message));
+    process.exit(1);
+  }
+});
+
 // src/index.ts
-var program = new Command16();
-program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.3.1");
+var program = new Command18();
+program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.4.1");
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
 program.addCommand(tierCommand);
@@ -2698,5 +4147,7 @@ program.addCommand(verifyCommand);
 program.addCommand(enrichCommand);
 program.addCommand(rulesCommand);
 program.addCommand(setupCommand);
+program.addCommand(blueprintCommand);
+program.addCommand(newCommand);
 program.parse();
 //# sourceMappingURL=index.js.map