@runcontext/cli 0.3.0 → 0.3.2

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command12 } from "commander";
+import { Command as Command16 } from "commander";
 
 // src/commands/lint.ts
 import { Command } from "commander";
@@ -508,25 +508,352 @@ var explainCommand = new Command4("explain").description("Look up models, terms,
 });
 
 // src/commands/fix.ts
+import { Command as Command7 } from "commander";
+import chalk8 from "chalk";
+import path7 from "path";
+import fs2 from "fs";
+import {
+  compile as compile6,
+  loadConfig as loadConfig6,
+  LintEngine as LintEngine3,
+  ALL_RULES as ALL_RULES3,
+  applyFixes as applyFixes2,
+  createAdapter as createAdapter3
+} from "@runcontext/core";
+
+// src/commands/introspect.ts
 import { Command as Command5 } from "commander";
 import chalk6 from "chalk";
 import path5 from "path";
-import fs2 from "fs";
+import { mkdirSync, writeFileSync as writeFileSync2, existsSync } from "fs";
 import {
-  compile as compile5,
   loadConfig as loadConfig4,
+  createAdapter,
+  scaffoldFromSchema
+} from "@runcontext/core";
+function parseDbUrl(db) {
+  if (db.startsWith("duckdb://")) {
+    return { adapter: "duckdb", path: db.slice("duckdb://".length) };
+  }
+  if (db.startsWith("postgres://") || db.startsWith("postgresql://")) {
+    return { adapter: "postgres", connection: db };
+  }
+  if (db.endsWith(".duckdb") || db.endsWith(".db")) {
+    return { adapter: "duckdb", path: db };
+  }
+  throw new Error(
+    `Cannot determine adapter from "${db}". Use duckdb:// or postgres:// prefix.`
+  );
+}
+var introspectCommand = new Command5("introspect").description("Introspect a database and scaffold Bronze-level OSI metadata").option(
+  "--db <url>",
+  "Database URL (e.g., duckdb://path.duckdb or postgres://...)"
+).option(
+  "--source <name>",
+  "Use a named data_source from contextkit.config.yaml"
+).option("--tables <glob>", 'Filter tables by glob pattern (e.g., "vw_*")').option(
+  "--model-name <name>",
+  "Name for the generated model (default: derived from source)"
+).action(async (opts) => {
+  try {
+    const config = loadConfig4(process.cwd());
+    const contextDir = path5.resolve(config.context_dir);
+    let dsConfig;
+    let dsName;
+    if (opts.db) {
+      dsConfig = parseDbUrl(opts.db);
+      dsName = opts.source ?? "default";
+    } else if (opts.source) {
+      if (!config.data_sources?.[opts.source]) {
+        console.error(
+          chalk6.red(
+            `Data source "${opts.source}" not found in config`
+          )
+        );
+        process.exit(1);
+      }
+      dsConfig = config.data_sources[opts.source];
+      dsName = opts.source;
+    } else {
+      const sources = config.data_sources;
+      if (!sources || Object.keys(sources).length === 0) {
+        console.error(
+          chalk6.red(
+            "No data source specified. Use --db <url> or configure data_sources in config"
+          )
+        );
+        process.exit(1);
+      }
+      const firstName = Object.keys(sources)[0];
+      dsConfig = sources[firstName];
+      dsName = firstName;
+    }
+    const adapter = await createAdapter(dsConfig);
+    await adapter.connect();
+    console.log(
+      chalk6.green(
+        `Connected to ${dsConfig.adapter}: ${dsConfig.path ?? dsConfig.connection}`
+      )
+    );
+    let tables = await adapter.listTables();
+    if (opts.tables) {
+      const pattern = opts.tables.replace(/\*/g, ".*");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      tables = tables.filter((t) => regex.test(t.name));
+    }
+    console.log(`Discovered ${tables.length} tables/views`);
+    const columns = {};
+    for (const table of tables) {
+      columns[table.name] = await adapter.listColumns(table.name);
+    }
+    const totalCols = Object.values(columns).reduce(
+      (sum, cols) => sum + cols.length,
+      0
+    );
+    console.log(`Found ${totalCols} columns total`);
+    await adapter.disconnect();
+    const modelName = opts.modelName ?? dsName.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+    const result = scaffoldFromSchema({
+      modelName,
+      dataSourceName: dsName,
+      tables,
+      columns
+    });
+    for (const dir of ["models", "governance", "owners"]) {
+      const dirPath = path5.join(contextDir, dir);
+      if (!existsSync(dirPath)) mkdirSync(dirPath, { recursive: true });
+    }
+    const osiPath = path5.join(contextDir, "models", result.files.osi);
+    const govPath = path5.join(
+      contextDir,
+      "governance",
+      result.files.governance
+    );
+    const ownerPath = path5.join(contextDir, "owners", result.files.owner);
+    writeFileSync2(osiPath, result.osiYaml, "utf-8");
+    writeFileSync2(govPath, result.governanceYaml, "utf-8");
+    if (!existsSync(ownerPath)) {
+      writeFileSync2(ownerPath, result.ownerYaml, "utf-8");
+    }
+    console.log("");
+    console.log(chalk6.green("Scaffolded:"));
+    console.log(`  ${path5.relative(process.cwd(), osiPath)}`);
+    console.log(`  ${path5.relative(process.cwd(), govPath)}`);
+    console.log(`  ${path5.relative(process.cwd(), ownerPath)}`);
+    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}`)
+    );
+    process.exit(1);
+  }
+});
+
+// src/commands/verify.ts
+import { Command as Command6 } from "commander";
+import chalk7 from "chalk";
+import path6 from "path";
+import {
+  compile as compile5,
+  loadConfig as loadConfig5,
   LintEngine as LintEngine2,
   ALL_RULES as ALL_RULES2,
-  applyFixes as applyFixes2
+  createAdapter as createAdapter2
 } from "@runcontext/core";
-var fixCommand = new Command5("fix").description("Auto-fix lint issues").option("--context-dir <path>", "Path to context directory").option("--format <type>", "Output format: pretty or json", "pretty").option("--dry-run", "Show what would be fixed without writing files").action(async (opts) => {
+function findTable(dsName, graph, existingTables) {
+  if (existingTables.has(dsName)) return dsName;
+  for (const [, model] of graph.models) {
+    const ds = model.datasets.find((d) => d.name === dsName);
+    if (ds?.source) {
+      const tableName = ds.source.split(".").pop();
+      if (existingTables.has(tableName)) return tableName;
+    }
+  }
+  return void 0;
+}
+async function collectDataValidation(adapter, graph) {
+  const validation = {
+    existingTables: /* @__PURE__ */ new Map(),
+    existingColumns: /* @__PURE__ */ new Map(),
+    actualSampleValues: /* @__PURE__ */ new Map(),
+    goldenQueryResults: /* @__PURE__ */ new Map(),
+    guardrailResults: /* @__PURE__ */ new Map()
+  };
+  const tables = await adapter.listTables();
+  for (const t of tables) {
+    validation.existingTables.set(t.name, t.row_count);
+  }
+  for (const t of tables) {
+    const cols = await adapter.listColumns(t.name);
+    const colMap = new Map(cols.map((c) => [c.name, c.data_type]));
+    validation.existingColumns.set(t.name, colMap);
+  }
+  for (const [, gov] of graph.governance) {
+    if (!gov.fields) continue;
+    for (const [fieldKey, fieldGov] of Object.entries(gov.fields)) {
+      if (!fieldGov.sample_values || fieldGov.sample_values.length === 0)
+        continue;
+      const dotIdx = fieldKey.indexOf(".");
+      if (dotIdx < 0) continue;
+      const dsName = fieldKey.substring(0, dotIdx);
+      const fieldName = fieldKey.substring(dotIdx + 1);
+      const tableName = findTable(dsName, graph, validation.existingTables);
+      if (!tableName) continue;
+      try {
+        const result = await adapter.query(
+          `SELECT DISTINCT CAST("${fieldName}" AS VARCHAR) AS val FROM "${tableName}" WHERE "${fieldName}" IS NOT NULL LIMIT 50`
+        );
+        validation.actualSampleValues.set(
+          fieldKey,
+          result.rows.map((r) => String(r.val))
+        );
+      } catch {
+      }
+    }
+  }
+  for (const [, rules] of graph.rules) {
+    if (!rules.golden_queries) continue;
+    for (let i = 0; i < rules.golden_queries.length; i++) {
+      const gq = rules.golden_queries[i];
+      try {
+        const result = await adapter.query(gq.sql);
+        validation.goldenQueryResults.set(i, {
+          success: true,
+          rowCount: result.row_count
+        });
+      } catch (err) {
+        validation.goldenQueryResults.set(i, {
+          success: false,
+          error: err.message
+        });
+      }
+    }
+  }
+  for (const [, rules] of graph.rules) {
+    if (!rules.guardrail_filters) continue;
+    for (let i = 0; i < rules.guardrail_filters.length; i++) {
+      const gf = rules.guardrail_filters[i];
+      const testTable = gf.tables?.[0] ?? "unknown";
+      const tableName = findTable(testTable, graph, validation.existingTables);
+      if (!tableName) {
+        validation.guardrailResults.set(i, {
+          valid: false,
+          error: `Table "${testTable}" not found`
+        });
+        continue;
+      }
+      try {
+        await adapter.query(
+          `SELECT 1 FROM "${tableName}" WHERE ${gf.filter} LIMIT 1`
+        );
+        validation.guardrailResults.set(i, { valid: true });
+      } catch (err) {
+        validation.guardrailResults.set(i, {
+          valid: false,
+          error: err.message
+        });
+      }
+    }
+  }
+  return validation;
+}
+var verifyCommand = new Command6("verify").description("Validate metadata accuracy against a live database").option("--source <name>", "Use a specific data_source from config").option("--db <url>", "Database URL override (postgres:// or path.duckdb)").option("--context-dir <path>", "Path to context directory").option("--format <type>", "Output format: pretty or json", "pretty").action(async (opts) => {
   try {
-    const config = loadConfig4(process.cwd());
-    const contextDir = opts.contextDir ? path5.resolve(opts.contextDir) : path5.resolve(config.context_dir);
-    const { graph } = await compile5({ contextDir, config, rootDir: process.cwd() });
-    const overrides = config.lint?.severity_overrides;
-    const engine = new LintEngine2(overrides);
+    const config = loadConfig5(process.cwd());
+    const contextDir = opts.contextDir ? path6.resolve(opts.contextDir) : path6.resolve(config.context_dir);
+    const { graph, diagnostics: compileDiags } = await compile5({
+      contextDir,
+      config
+    });
+    let dsConfig;
+    if (opts.db) {
+      dsConfig = parseDbUrl(opts.db);
+    } else {
+      const sources = config.data_sources;
+      if (!sources || Object.keys(sources).length === 0) {
+        console.error(
+          chalk7.red(
+            "No data source configured. Add data_sources to contextkit.config.yaml or use --db."
+          )
+        );
+        process.exit(1);
+      }
+      const name = opts.source ?? Object.keys(sources)[0];
+      const resolved = sources[name];
+      if (!resolved) {
+        console.error(
+          chalk7.red(
+            `Data source "${name}" not found. Available: ${Object.keys(sources).join(", ")}`
+          )
+        );
+        process.exit(1);
+        return;
+      }
+      dsConfig = resolved;
+    }
+    const adapter = await createAdapter2(dsConfig);
+    await adapter.connect();
+    console.log(chalk7.green(`Connected to ${dsConfig.adapter}`));
+    console.log("Collecting validation data...\n");
+    graph.dataValidation = await collectDataValidation(adapter, graph);
+    await adapter.disconnect();
+    const engine = new LintEngine2();
     for (const rule of ALL_RULES2) {
+      if (rule.id.startsWith("data/")) {
+        engine.register(rule);
+      }
+    }
+    const dataDiags = engine.run(graph);
+    const allDiags = [...dataDiags];
+    if (allDiags.length === 0) {
+      const tableCount = graph.dataValidation.existingTables.size;
+      const totalRows = [
+        ...graph.dataValidation.existingTables.values()
+      ].reduce((a, b) => a + b, 0);
+      console.log(chalk7.green("All data validation checks passed.\n"));
+      console.log(
+        `Verified against ${tableCount} table(s) (${totalRows.toLocaleString()} total rows)`
+      );
+    } else {
+      console.log(formatDiagnostics(allDiags));
+    }
+    const hasErrors = allDiags.some((d) => d.severity === "error");
+    if (hasErrors) process.exit(1);
+  } catch (err) {
+    console.error(chalk7.red(`Verify failed: ${err.message}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/fix.ts
+var fixCommand = new Command7("fix").description("Auto-fix lint issues").option("--context-dir <path>", "Path to context directory").option("--format <type>", "Output format: pretty or json", "pretty").option("--dry-run", "Show what would be fixed without writing files").option("--db <url>", "Database URL for data-aware fixes (postgres:// or path.duckdb)").option("--source <name>", "Use a specific data_source from config").action(async (opts) => {
+  try {
+    const config = loadConfig6(process.cwd());
+    const contextDir = opts.contextDir ? path7.resolve(opts.contextDir) : path7.resolve(config.context_dir);
+    const { graph } = await compile6({ contextDir, config, rootDir: process.cwd() });
+    let dsConfig;
+    if (opts.db) {
+      dsConfig = parseDbUrl(opts.db);
+    } else {
+      const sources = config.data_sources;
+      if (sources && Object.keys(sources).length > 0) {
+        const name = opts.source ?? Object.keys(sources)[0];
+        dsConfig = sources[name];
+      }
+    }
+    if (dsConfig) {
+      const adapter = await createAdapter3(dsConfig);
+      await adapter.connect();
+      graph.dataValidation = await collectDataValidation(adapter, graph);
+      await adapter.disconnect();
+    }
+    const overrides = config.lint?.severity_overrides;
+    const engine = new LintEngine3(overrides);
+    for (const rule of ALL_RULES3) {
       engine.register(rule);
     }
     const diagnostics = engine.run(graph);
@@ -535,7 +862,7 @@ var fixCommand = new Command5("fix").description("Auto-fix lint issues").option(
       if (opts.format === "json") {
         console.log(formatJson({ fixedFiles: [], fixCount: 0 }));
       } else {
-        console.log(chalk6.green("No fixable issues found."));
+        console.log(chalk8.green("No fixable issues found."));
       }
       return;
     }
@@ -552,10 +879,10 @@ var fixCommand = new Command5("fix").description("Auto-fix lint issues").option(
         );
       } else {
         console.log(
-          chalk6.yellow(`Dry run: ${fixable.length} issue(s) would be fixed in ${fixedFiles.size} file(s):`)
+          chalk8.yellow(`Dry run: ${fixable.length} issue(s) would be fixed in ${fixedFiles.size} file(s):`)
         );
         for (const file of fixedFiles.keys()) {
-          console.log(chalk6.gray(`  ${file}`));
+          console.log(chalk8.gray(`  ${file}`));
         }
       }
       return;
@@ -584,15 +911,15 @@ var fixCommand = new Command5("fix").description("Auto-fix lint issues").option(
 });
 
 // src/commands/dev.ts
-import { Command as Command6 } from "commander";
-import chalk7 from "chalk";
-import path6 from "path";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { Command as Command8 } from "commander";
+import chalk9 from "chalk";
+import path8 from "path";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
 import {
-  compile as compile6,
-  loadConfig as loadConfig5,
-  LintEngine as LintEngine3,
-  ALL_RULES as ALL_RULES3,
+  compile as compile7,
+  loadConfig as loadConfig7,
+  LintEngine as LintEngine4,
+  ALL_RULES as ALL_RULES4,
   filterByDirectives as filterByDirectives2,
   applyFixes as applyFixes3
 } from "@runcontext/core";
@@ -601,15 +928,15 @@ function diagKey(d) {
 }
 var previousDiags = /* @__PURE__ */ new Map();
 async function runLint(contextDir, fix) {
-  const config = loadConfig5(process.cwd());
-  const { graph, diagnostics: compileDiags, directives } = await compile6({
+  const config = loadConfig7(process.cwd());
+  const { graph, diagnostics: compileDiags, directives } = await compile7({
     contextDir,
     config,
     rootDir: process.cwd()
   });
   const overrides = config.lint?.severity_overrides;
-  const engine = new LintEngine3(overrides);
-  for (const rule of ALL_RULES3) {
+  const engine = new LintEngine4(overrides);
+  for (const rule of ALL_RULES4) {
     engine.register(rule);
   }
   const lintDiags = engine.run(graph);
@@ -619,20 +946,20 @@ async function runLint(contextDir, fix) {
     if (fixable.length > 0) {
       const fixes = applyFixes3(fixable, (filePath) => readFileSync2(filePath, "utf-8"));
       for (const [file, content] of fixes) {
-        writeFileSync2(file, content, "utf-8");
+        writeFileSync3(file, content, "utf-8");
       }
-      const { graph: reGraph, diagnostics: reCompileDiags, directives: reDirs } = await compile6({
+      const { graph: reGraph, diagnostics: reCompileDiags, directives: reDirs } = await compile7({
         contextDir,
         config,
         rootDir: process.cwd()
       });
-      const reEngine = new LintEngine3(overrides);
-      for (const rule of ALL_RULES3) {
+      const reEngine = new LintEngine4(overrides);
+      for (const rule of ALL_RULES4) {
         reEngine.register(rule);
       }
       allDiags = filterByDirectives2([...reCompileDiags, ...reEngine.run(reGraph)], reDirs);
       if (fixable.length > 0) {
-        console.log(chalk7.green(`  Auto-fixed ${fixable.length} issue(s).`));
+        console.log(chalk9.green(`  Auto-fixed ${fixable.length} issue(s).`));
       }
     }
   }
@@ -649,16 +976,16 @@ async function runLint(contextDir, fix) {
     if (!currentDiags.has(key)) resolved.push(d);
   }
   console.clear();
-  console.log(chalk7.gray(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Linting...`));
+  console.log(chalk9.gray(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Linting...`));
   if (previousDiags.size > 0) {
     if (resolved.length > 0) {
-      console.log(chalk7.green(`  ${resolved.length} issue(s) resolved`));
+      console.log(chalk9.green(`  ${resolved.length} issue(s) resolved`));
     }
     if (newIssues.length > 0) {
-      console.log(chalk7.red(`  ${newIssues.length} new issue(s)`));
+      console.log(chalk9.red(`  ${newIssues.length} new issue(s)`));
     }
     if (resolved.length === 0 && newIssues.length === 0) {
-      console.log(chalk7.gray("  No changes"));
+      console.log(chalk9.gray("  No changes"));
     }
     console.log("");
   }
@@ -666,14 +993,14 @@ async function runLint(contextDir, fix) {
   console.log("");
   previousDiags = currentDiags;
 }
-var devCommand = new Command6("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").action(async (opts) => {
   try {
-    const config = loadConfig5(process.cwd());
-    const contextDir = opts.contextDir ? path6.resolve(opts.contextDir) : path6.resolve(config.context_dir);
+    const config = loadConfig7(process.cwd());
+    const contextDir = opts.contextDir ? path8.resolve(opts.contextDir) : path8.resolve(config.context_dir);
     const fix = opts.fix === true;
-    console.log(chalk7.blue(`Watching ${contextDir} for changes...`));
-    if (fix) console.log(chalk7.blue("Auto-fix enabled."));
-    console.log(chalk7.gray("Press Ctrl+C to stop.\n"));
+    console.log(chalk9.blue(`Watching ${contextDir} for changes...`));
+    if (fix) console.log(chalk9.blue("Auto-fix enabled."));
+    console.log(chalk9.gray("Press Ctrl+C to stop.\n"));
     await runLint(contextDir, fix);
     const { watch } = await import("chokidar");
     let debounceTimer = null;
@@ -690,21 +1017,21 @@ var devCommand = new Command6("dev").description("Watch mode \u2014 re-run lint
           await runLint(contextDir, fix);
         } catch (err) {
           console.error(
-            chalk7.red(`Lint error: ${err.message}`)
+            chalk9.red(`Lint error: ${err.message}`)
           );
         }
       }, 300);
     });
   } catch (err) {
-    console.error(chalk7.red(`Dev mode failed: ${err.message}`));
+    console.error(chalk9.red(`Dev mode failed: ${err.message}`));
     process.exit(1);
   }
 });
 
 // src/commands/init.ts
-import { Command as Command7 } from "commander";
-import chalk8 from "chalk";
-import path7 from "path";
+import { Command as Command9 } from "commander";
+import chalk10 from "chalk";
+import path9 from "path";
 import fs3 from "fs";
 var EXAMPLE_OSI = `version: "1.0"
 
@@ -769,26 +1096,26 @@ var EXAMPLE_CONFIG = `context_dir: context
 output_dir: dist
 minimum_tier: bronze
 `;
-var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit project structure").option("--dir <path>", "Root directory for the project", ".").action(async (opts) => {
+var initCommand = new Command9("init").description("Scaffold a v0.2 ContextKit project structure").option("--dir <path>", "Root directory for the project", ".").action(async (opts) => {
   try {
-    const rootDir = path7.resolve(opts.dir);
-    const contextDir = path7.join(rootDir, "context");
+    const rootDir = path9.resolve(opts.dir);
+    const contextDir = path9.join(rootDir, "context");
     const dirs = [
-      path7.join(contextDir, "models"),
-      path7.join(contextDir, "governance"),
-      path7.join(contextDir, "glossary"),
-      path7.join(contextDir, "owners")
+      path9.join(contextDir, "models"),
+      path9.join(contextDir, "governance"),
+      path9.join(contextDir, "glossary"),
+      path9.join(contextDir, "owners")
     ];
     for (const dir of dirs) {
       fs3.mkdirSync(dir, { recursive: true });
     }
     const files = [
       {
-        path: path7.join(contextDir, "models", "example-model.osi.yaml"),
+        path: path9.join(contextDir, "models", "example-model.osi.yaml"),
         content: EXAMPLE_OSI
       },
       {
-        path: path7.join(
+        path: path9.join(
           contextDir,
           "governance",
           "example-model.governance.yaml"
@@ -796,15 +1123,15 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
         content: EXAMPLE_GOVERNANCE
       },
       {
-        path: path7.join(contextDir, "glossary", "glossary.term.yaml"),
+        path: path9.join(contextDir, "glossary", "glossary.term.yaml"),
         content: EXAMPLE_TERM
       },
       {
-        path: path7.join(contextDir, "owners", "data-team.owner.yaml"),
+        path: path9.join(contextDir, "owners", "data-team.owner.yaml"),
         content: EXAMPLE_OWNER
       },
       {
-        path: path7.join(rootDir, "contextkit.config.yaml"),
+        path: path9.join(rootDir, "contextkit.config.yaml"),
         content: EXAMPLE_CONFIG
       }
     ];
@@ -812,11 +1139,11 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
     let skipped = 0;
     for (const file of files) {
       if (fs3.existsSync(file.path)) {
-        console.log(chalk8.gray(`  skip ${path7.relative(rootDir, file.path)} (exists)`));
+        console.log(chalk10.gray(`  skip ${path9.relative(rootDir, file.path)} (exists)`));
         skipped++;
       } else {
         fs3.writeFileSync(file.path, file.content, "utf-8");
-        console.log(chalk8.green(`  create ${path7.relative(rootDir, file.path)}`));
+        console.log(chalk10.green(`  create ${path9.relative(rootDir, file.path)}`));
         created++;
       }
     }
@@ -827,10 +1154,10 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
       )
     );
     console.log("");
-    console.log(chalk8.gray("Next steps:"));
-    console.log(chalk8.gray("  1. Edit the example files in context/"));
-    console.log(chalk8.gray("  2. Run: context lint"));
-    console.log(chalk8.gray("  3. Run: context build"));
+    console.log(chalk10.gray("Next steps:"));
+    console.log(chalk10.gray("  1. Edit the example files in context/"));
+    console.log(chalk10.gray("  2. Run: context lint"));
+    console.log(chalk10.gray("  3. Run: context build"));
   } catch (err) {
     console.error(formatError(err.message));
     process.exit(1);
@@ -838,15 +1165,15 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
 });
 
 // src/commands/site.ts
-import { Command as Command8 } from "commander";
-import chalk9 from "chalk";
-import path8 from "path";
-import { compile as compile7, loadConfig as loadConfig6, emitManifest as emitManifest2 } from "@runcontext/core";
-var siteCommand = new Command8("site").description("Build a static documentation site from compiled context").option("--context-dir <path>", "Path to context directory").option("--output-dir <path>", "Path to site output directory").action(async (opts) => {
+import { Command as Command10 } from "commander";
+import chalk11 from "chalk";
+import path10 from "path";
+import { compile as compile8, loadConfig as loadConfig8, emitManifest as emitManifest2 } from "@runcontext/core";
+var siteCommand = new Command10("site").description("Build a static documentation site from compiled context").option("--context-dir <path>", "Path to context directory").option("--output-dir <path>", "Path to site output directory").action(async (opts) => {
   try {
-    const config = loadConfig6(process.cwd());
-    const contextDir = opts.contextDir ? path8.resolve(opts.contextDir) : path8.resolve(config.context_dir);
-    const { graph } = await compile7({ contextDir, config, rootDir: process.cwd() });
+    const config = loadConfig8(process.cwd());
+    const contextDir = opts.contextDir ? path10.resolve(opts.contextDir) : path10.resolve(config.context_dir);
+    const { graph } = await compile8({ contextDir, config, rootDir: process.cwd() });
     const manifest = emitManifest2(graph, config);
     let buildSite;
     try {
@@ -856,15 +1183,15 @@ var siteCommand = new Command8("site").description("Build a static documentation
     }
     if (!buildSite) {
       console.log(
-        chalk9.yellow(
+        chalk11.yellow(
           "Site generator is not yet available. Install @runcontext/site to enable this command."
         )
       );
       process.exit(0);
     }
-    const outputDir = opts.outputDir ? path8.resolve(opts.outputDir) : path8.resolve(config.site?.base_path ?? "site");
+    const outputDir = opts.outputDir ? path10.resolve(opts.outputDir) : path10.resolve(config.site?.base_path ?? "site");
     await buildSite(manifest, config, outputDir);
-    console.log(chalk9.green(`Site built to ${outputDir}`));
+    console.log(chalk11.green(`Site built to ${outputDir}`));
   } catch (err) {
     console.error(formatError(err.message));
     process.exit(1);
@@ -872,9 +1199,9 @@ var siteCommand = new Command8("site").description("Build a static documentation
 });
 
 // src/commands/serve.ts
-import { Command as Command9 } from "commander";
-import chalk10 from "chalk";
-var serveCommand = new Command9("serve").description("Start the MCP server (stdio transport)").option("--context-dir <path>", "Path to context directory").action(async (opts) => {
+import { Command as Command11 } from "commander";
+import chalk12 from "chalk";
+var serveCommand = new Command11("serve").description("Start the MCP server (stdio transport)").option("--context-dir <path>", "Path to context directory").action(async (opts) => {
   try {
     let startServer;
     try {
@@ -884,13 +1211,13 @@ var serveCommand = new Command9("serve").description("Start the MCP server (stdi
     }
     if (!startServer) {
       console.log(
-        chalk10.yellow(
+        chalk12.yellow(
           "MCP server is not available. Install @runcontext/mcp to enable this command."
         )
       );
       process.exit(1);
     }
-    console.log(chalk10.blue("Starting MCP server (stdio transport)..."));
+    console.log(chalk12.blue("Starting MCP server (stdio transport)..."));
     await startServer({
       contextDir: opts.contextDir,
       rootDir: process.cwd()
@@ -902,13 +1229,13 @@ var serveCommand = new Command9("serve").description("Start the MCP server (stdi
 });
 
 // src/commands/validate-osi.ts
-import { Command as Command10 } from "commander";
-import chalk11 from "chalk";
-import path9 from "path";
+import { Command as Command12 } from "commander";
+import chalk13 from "chalk";
+import path11 from "path";
 import { parseFile, osiDocumentSchema } from "@runcontext/core";
-var validateOsiCommand = new Command10("validate-osi").description("Validate a single OSI file against the schema").argument("<file>", "Path to the OSI YAML file").option("--format <type>", "Output format: pretty or json", "pretty").action(async (file, opts) => {
+var validateOsiCommand = new Command12("validate-osi").description("Validate a single OSI file against the schema").argument("<file>", "Path to the OSI YAML file").option("--format <type>", "Output format: pretty or json", "pretty").action(async (file, opts) => {
   try {
-    const filePath = path9.resolve(file);
+    const filePath = path11.resolve(file);
     const parsed = await parseFile(filePath, "model");
     const result = osiDocumentSchema.safeParse(parsed.data);
     if (result.success) {
@@ -937,9 +1264,9 @@ var validateOsiCommand = new Command10("validate-osi").description("Validate a s
           })
         );
       } else {
-        console.error(chalk11.red(`Validation failed for ${filePath}:`));
+        console.error(chalk13.red(`Validation failed for ${filePath}:`));
         for (const issue of issues) {
-          console.error(chalk11.red(`  ${issue.path}: ${issue.message}`));
+          console.error(chalk13.red(`  ${issue.path}: ${issue.message}`));
         }
       }
       process.exit(1);
@@ -950,46 +1277,268 @@ var validateOsiCommand = new Command10("validate-osi").description("Validate a s
   }
 });
 
+// src/commands/enrich.ts
+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 * as yaml from "yaml";
+import {
+  compile as compile9,
+  loadConfig as loadConfig9,
+  computeTier as computeTier2,
+  createAdapter as createAdapter4,
+  suggestEnrichments,
+  inferSemanticRole,
+  inferAggregation
+} from "@runcontext/core";
+function findFileRecursive(dir, suffix) {
+  if (!existsSync2(dir)) return void 0;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path12.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursive(fullPath, suffix);
+      if (found) return found;
+    } else if (entry.name.endsWith(suffix)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+var enrichCommand = new Command13("enrich").description("Suggest or apply metadata enrichments to reach a target tier").option("--target <tier>", "Target tier: silver or gold", "silver").option("--apply", "Write suggestions to YAML files").option("--source <name>", "Data source for sample values").option("--db <url>", "Database URL for sample values").option("--context-dir <path>", "Path to context directory").action(async (opts) => {
+  try {
+    const config = loadConfig9(process.cwd());
+    const contextDir = opts.contextDir ? path12.resolve(opts.contextDir) : path12.resolve(config.context_dir);
+    const target = opts.target;
+    if (!["silver", "gold"].includes(target)) {
+      console.error(chalk14.red('--target must be "silver" or "gold"'));
+      process.exit(1);
+    }
+    const { graph } = await compile9({ contextDir, config });
+    for (const [modelName] of graph.models) {
+      const tierScore = computeTier2(modelName, graph);
+      console.log(chalk14.bold(`${modelName}: ${tierScore.tier.toUpperCase()}`));
+      if (tierScore.tier === target || target === "silver" && tierScore.tier === "gold") {
+        console.log(chalk14.green(`  Already at ${target} or above.
+`));
+        continue;
+      }
+      const model = graph.models.get(modelName);
+      const datasetNames = model.datasets.map((d) => d.name);
+      const suggestions = suggestEnrichments(target, tierScore, datasetNames);
+      if (!suggestions.governance && !suggestions.lineage && !suggestions.glossaryTerms && !suggestions.needsRulesFile && !suggestions.needsSampleValues && !suggestions.needsSemanticRoles) {
+        console.log(chalk14.green("  No suggestions needed.\n"));
+        continue;
+      }
+      if (suggestions.governance?.trust) {
+        console.log(chalk14.yellow(`  + Add trust: ${suggestions.governance.trust}`));
+      }
+      if (suggestions.governance?.tags) {
+        console.log(chalk14.yellow(`  + Add tags: [${suggestions.governance.tags.join(", ")}]`));
+      }
+      if (suggestions.governance?.refreshAll) {
+        console.log(chalk14.yellow(`  + Add refresh: ${suggestions.governance.refreshAll}`));
+      }
+      if (suggestions.lineage) {
+        console.log(chalk14.yellow(`  + Add lineage with ${suggestions.lineage.upstream?.length ?? 0} upstream sources`));
+      }
+      if (suggestions.glossaryTerms) {
+        console.log(chalk14.yellow(`  + Generate ${suggestions.glossaryTerms.length} glossary term(s)`));
+      }
+      if (suggestions.needsSampleValues) {
+        console.log(chalk14.yellow("  + Populate sample_values from database"));
+      }
+      if (suggestions.needsSemanticRoles) {
+        console.log(chalk14.yellow("  + Infer semantic_role for all fields"));
+      }
+      if (suggestions.needsRulesFile) {
+        console.log(chalk14.yellow("  + Generate rules file"));
+      }
+      if (!opts.apply) {
+        console.log(chalk14.cyan("\n  Run with --apply to write these changes.\n"));
+        continue;
+      }
+      const govFilePath = findFileRecursive(contextDir, `${modelName}.governance.yaml`);
+      if (govFilePath) {
+        const govContent = readFileSync3(govFilePath, "utf-8");
+        const govDoc = yaml.parse(govContent) ?? {};
+        if (suggestions.governance?.trust) {
+          govDoc.trust = suggestions.governance.trust;
+        }
+        if (suggestions.governance?.tags) {
+          govDoc.tags = suggestions.governance.tags;
+        }
+        if (suggestions.governance?.refreshAll) {
+          for (const dsName of Object.keys(govDoc.datasets ?? {})) {
+            govDoc.datasets[dsName].refresh = suggestions.governance.refreshAll;
+          }
+        }
+        if (suggestions.needsSemanticRoles) {
+          govDoc.fields = govDoc.fields ?? {};
+          let adapter = null;
+          const dsConfig = opts.db ? parseDbUrl(opts.db) : config.data_sources?.[opts.source ?? Object.keys(config.data_sources ?? {})[0]];
+          if (dsConfig) {
+            adapter = await createAdapter4(dsConfig);
+            await adapter.connect();
+          }
+          for (const ds of model.datasets) {
+            let columns = [];
+            if (adapter) {
+              const tableName = ds.source?.split(".").pop() ?? ds.name;
+              try {
+                columns = await adapter.listColumns(tableName);
+              } catch {
+              }
+            }
+            for (const field of ds.fields ?? []) {
+              const fieldKey = `${ds.name}.${field.name}`;
+              if (govDoc.fields[fieldKey]?.semantic_role) continue;
+              const col = columns.find((c) => c.name === field.name);
+              const isPK = col?.is_primary_key ?? field.name.endsWith("_id");
+              const dataType = col?.data_type ?? "VARCHAR";
+              govDoc.fields[fieldKey] = govDoc.fields[fieldKey] ?? {};
+              const role = inferSemanticRole(field.name, dataType, isPK);
+              govDoc.fields[fieldKey].semantic_role = role;
+              if (role === "metric") {
+                govDoc.fields[fieldKey].default_aggregation = inferAggregation(field.name);
+                govDoc.fields[fieldKey].additive = govDoc.fields[fieldKey].default_aggregation === "SUM";
+              }
+            }
+          }
+          if (adapter) await adapter.disconnect();
+        }
+        if (suggestions.needsSampleValues) {
+          govDoc.fields = govDoc.fields ?? {};
+          const dsConfig2 = opts.db ? parseDbUrl(opts.db) : config.data_sources?.[opts.source ?? Object.keys(config.data_sources ?? {})[0]];
+          if (dsConfig2) {
+            const adapter2 = await createAdapter4(dsConfig2);
+            await adapter2.connect();
+            let count = 0;
+            for (const ds of model.datasets) {
+              if (count >= 2) break;
+              const tableName = ds.source?.split(".").pop() ?? ds.name;
+              for (const field of ds.fields ?? []) {
+                if (count >= 2) break;
+                const fieldKey = `${ds.name}.${field.name}`;
+                if (govDoc.fields[fieldKey]?.sample_values?.length > 0) continue;
+                try {
+                  const result = await adapter2.query(
+                    `SELECT DISTINCT CAST("${field.name}" AS VARCHAR) AS val FROM "${tableName}" WHERE "${field.name}" IS NOT NULL LIMIT 5`
+                  );
+                  if (result.rows.length > 0) {
+                    govDoc.fields[fieldKey] = govDoc.fields[fieldKey] ?? {};
+                    govDoc.fields[fieldKey].sample_values = result.rows.map((r) => String(r.val));
+                    count++;
+                  }
+                } catch {
+                }
+              }
+            }
+            await adapter2.disconnect();
+          }
+        }
+        writeFileSync4(govFilePath, yaml.stringify(govDoc, { lineWidth: 120 }), "utf-8");
+        console.log(chalk14.green(`  Updated: ${path12.relative(process.cwd(), govFilePath)}`));
+      }
+      if (suggestions.lineage) {
+        const lineageDir = path12.join(contextDir, "lineage");
+        if (!existsSync2(lineageDir)) mkdirSync2(lineageDir, { recursive: true });
+        const lineagePath = path12.join(lineageDir, `${modelName}.lineage.yaml`);
+        if (!existsSync2(lineagePath)) {
+          const lineageDoc = {
+            model: modelName,
+            upstream: suggestions.lineage.upstream
+          };
+          writeFileSync4(lineagePath, yaml.stringify(lineageDoc, { lineWidth: 120 }), "utf-8");
+          console.log(chalk14.green(`  Created: ${path12.relative(process.cwd(), lineagePath)}`));
+        }
+      }
+      if (suggestions.glossaryTerms) {
+        const glossaryDir = path12.join(contextDir, "glossary");
+        if (!existsSync2(glossaryDir)) mkdirSync2(glossaryDir, { recursive: true });
+        for (const term of suggestions.glossaryTerms) {
+          const termPath = path12.join(glossaryDir, `${term.id}.term.yaml`);
+          if (!existsSync2(termPath)) {
+            writeFileSync4(termPath, yaml.stringify(term, { lineWidth: 120 }), "utf-8");
+            console.log(chalk14.green(`  Created: ${path12.relative(process.cwd(), termPath)}`));
+          }
+        }
+      }
+      if (suggestions.needsRulesFile) {
+        const rulesDir = path12.join(contextDir, "rules");
+        if (!existsSync2(rulesDir)) mkdirSync2(rulesDir, { recursive: true });
+        const rulesPath = path12.join(rulesDir, `${modelName}.rules.yaml`);
+        if (!existsSync2(rulesPath)) {
+          const rulesDoc = {
+            model: modelName,
+            golden_queries: [
+              { question: "TODO: What is the total count?", sql: "SELECT COUNT(*) FROM table_name" },
+              { question: "TODO: What are the top records?", sql: "SELECT * FROM table_name LIMIT 10" },
+              { question: "TODO: What is the distribution?", sql: "SELECT column, COUNT(*) FROM table_name GROUP BY column" }
+            ],
+            business_rules: [
+              { name: "TODO: rule-name", definition: "TODO: describe the business rule" }
+            ],
+            guardrail_filters: [
+              { name: "TODO: filter-name", filter: "column IS NOT NULL", reason: "TODO: explain why" }
+            ],
+            hierarchies: [
+              { name: "TODO: hierarchy-name", levels: ["level1", "level2"], dataset: datasetNames[0] ?? "dataset" }
+            ]
+          };
+          writeFileSync4(rulesPath, yaml.stringify(rulesDoc, { lineWidth: 120 }), "utf-8");
+          console.log(chalk14.green(`  Created: ${path12.relative(process.cwd(), rulesPath)} (with TODOs)`));
+        }
+      }
+      console.log("");
+    }
+  } catch (err) {
+    console.error(chalk14.red(`Enrich failed: ${err.message}`));
+    process.exit(1);
+  }
+});
+
 // src/commands/rules.ts
-import { Command as Command11 } from "commander";
-import chalk12 from "chalk";
-import { ALL_RULES as ALL_RULES4 } from "@runcontext/core";
+import { Command as Command14 } from "commander";
+import chalk15 from "chalk";
+import { ALL_RULES as ALL_RULES5 } from "@runcontext/core";
 function formatRuleTable(rules) {
   if (rules.length === 0) {
-    return chalk12.gray("No rules match the filters.");
+    return chalk15.gray("No rules match the filters.");
   }
   const lines = [];
   const header = `${"ID".padEnd(40)} ${"Tier".padEnd(8)} ${"Severity".padEnd(10)} ${"Fix".padEnd(5)} Description`;
-  lines.push(chalk12.bold(header));
-  lines.push(chalk12.gray("\u2500".repeat(100)));
+  lines.push(chalk15.bold(header));
+  lines.push(chalk15.gray("\u2500".repeat(100)));
   for (const rule of rules) {
     const tier = rule.tier ?? "\u2014";
     const tierCol = colorTier(tier);
-    const fixCol = rule.fixable ? chalk12.green("yes") : chalk12.gray("no");
-    const sevCol = rule.defaultSeverity === "error" ? chalk12.red(rule.defaultSeverity) : chalk12.yellow(rule.defaultSeverity);
-    const deprecated = rule.deprecated ? chalk12.gray(" (deprecated)") : "";
+    const fixCol = rule.fixable ? chalk15.green("yes") : chalk15.gray("no");
+    const sevCol = rule.defaultSeverity === "error" ? chalk15.red(rule.defaultSeverity) : chalk15.yellow(rule.defaultSeverity);
+    const deprecated = rule.deprecated ? chalk15.gray(" (deprecated)") : "";
     lines.push(
       `${rule.id.padEnd(40)} ${tierCol.padEnd(8 + (tierCol.length - tier.length))} ${sevCol.padEnd(10 + (sevCol.length - rule.defaultSeverity.length))} ${fixCol.padEnd(5 + (fixCol.length - (rule.fixable ? 3 : 2)))} ${rule.description}${deprecated}`
     );
   }
   lines.push("");
-  lines.push(chalk12.gray(`${rules.length} rule(s) total`));
+  lines.push(chalk15.gray(`${rules.length} rule(s) total`));
   return lines.join("\n");
 }
 function colorTier(tier) {
   switch (tier) {
     case "gold":
-      return chalk12.yellow(tier);
+      return chalk15.yellow(tier);
     case "silver":
-      return chalk12.white(tier);
+      return chalk15.white(tier);
     case "bronze":
-      return chalk12.hex("#CD7F32")(tier);
+      return chalk15.hex("#CD7F32")(tier);
     default:
-      return chalk12.gray(tier);
+      return chalk15.gray(tier);
   }
 }
-var rulesCommand = new Command11("rules").description("List all lint rules with metadata").option("--tier <tier>", "Filter by tier: bronze, silver, gold").option("--fixable", "Show only fixable rules").option("--format <type>", "Output format: pretty or json", "pretty").action((opts) => {
-  let rules = [...ALL_RULES4];
+var rulesCommand = new Command14("rules").description("List all lint rules with metadata").option("--tier <tier>", "Filter by tier: bronze, silver, gold").option("--fixable", "Show only fixable rules").option("--format <type>", "Output format: pretty or json", "pretty").action((opts) => {
+  let rules = [...ALL_RULES5];
   if (opts.tier) {
     const tier = opts.tier;
     rules = rules.filter((r) => r.tier === tier);
@@ -1013,9 +1562,1029 @@ var rulesCommand = new Command11("rules").description("List all lint rules with
   }
 });
 
+// src/commands/setup.ts
+import { Command as Command15 } from "commander";
+import * as p9 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 yaml2 from "yaml";
+import { loadConfig as loadConfig10, createAdapter as createAdapter5 } from "@runcontext/core";
+function autoDetectDb(cwd) {
+  try {
+    const config = loadConfig10(cwd);
+    if (config.data_sources && Object.keys(config.data_sources).length > 0) {
+      const name = Object.keys(config.data_sources)[0];
+      const ds = config.data_sources[name];
+      const loc = ds.path ?? ds.connection ?? name;
+      return { dsConfig: ds, label: `${ds.adapter} \u2014 ${loc} (from contextkit.config.yaml)` };
+    }
+  } catch {
+  }
+  if (process.env.DATABASE_URL) {
+    try {
+      const ds = parseDbUrl(process.env.DATABASE_URL);
+      return { dsConfig: ds, label: `${ds.adapter} \u2014 $DATABASE_URL` };
+    } catch {
+    }
+  }
+  if (process.env.DUCKDB_PATH && existsSync3(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 mcpConfig = JSON.parse(readFileSync4(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)) {
+            return {
+              dsConfig: { adapter: "duckdb", path: dbPath },
+              label: `duckdb \u2014 ${path13.basename(dbPath)} (from .claude/mcp.json)`
+            };
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function promptForConnection() {
+  const connector = await p.select({
+    message: "Select your database",
+    options: [
+      { value: "duckdb", label: "DuckDB", hint: "Local .duckdb file" },
+      { value: "postgres", label: "PostgreSQL", hint: "Connection string" }
+    ]
+  });
+  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 (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) };
+    }
+  } 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://..." }
+      ]
+    });
+    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 (p.isCancel(url)) return void 0;
+      return { adapter: "postgres", connection: url };
+    }
+  }
+}
+async function runConnectStep() {
+  const cwd = process.cwd();
+  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.");
+      return void 0;
+    }
+    if (useDetected) {
+      dsConfig = detected.dsConfig;
+    } else {
+      const manual = await promptForConnection();
+      if (!manual) {
+        p.cancel("Setup cancelled.");
+        return void 0;
+      }
+      dsConfig = manual;
+    }
+  } else {
+    const manual = await promptForConnection();
+    if (!manual) {
+      p.cancel("Setup cancelled.");
+      return void 0;
+    }
+    dsConfig = manual;
+  }
+  const spin = p.spinner();
+  spin.start("Connecting to database...");
+  let adapter;
+  try {
+    adapter = await createAdapter5(dsConfig);
+    await adapter.connect();
+  } catch (err) {
+    spin.stop("Connection failed");
+    p.log.error(err.message);
+    p.cancel("Could not connect to database.");
+    return void 0;
+  }
+  const tables = await adapter.listTables();
+  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`);
+  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({
+    message: "Model name",
+    initialValue: defaultModel,
+    validate(value) {
+      if (!value) return "Required";
+      if (!/^[a-z0-9-]+$/.test(value)) return "Use lowercase letters, numbers, and hyphens only";
+    }
+  });
+  if (p.isCancel(modelInput)) {
+    p.cancel("Setup cancelled.");
+    await adapter.disconnect();
+    return void 0;
+  }
+  const tierInput = await p.select({
+    message: "Target metadata tier",
+    options: [
+      { value: "bronze", label: "Bronze", hint: "Schema + ownership + grain" },
+      { value: "silver", label: "Silver", hint: "+ trust, lineage, glossary, refresh, sample values" },
+      { value: "gold", label: "Gold", hint: "+ semantic roles, rules, golden queries (needs curation)" }
+    ]
+  });
+  if (p.isCancel(tierInput)) {
+    p.cancel("Setup cancelled.");
+    await adapter.disconnect();
+    return void 0;
+  }
+  const configPath = path13.join(cwd, "contextkit.config.yaml");
+  let config;
+  try {
+    config = loadConfig10(cwd);
+  } catch {
+    config = { context_dir: "./context" };
+  }
+  if (!config.data_sources || Object.keys(config.data_sources).length === 0) {
+    const newConfig = {
+      context_dir: config.context_dir ?? "./context",
+      data_sources: { default: dsConfig }
+    };
+    writeFileSync5(configPath, yaml2.stringify(newConfig, { lineWidth: 120 }), "utf-8");
+    config = loadConfig10(cwd);
+  }
+  const contextDir = path13.resolve(cwd, config.context_dir ?? "./context");
+  return {
+    cwd,
+    contextDir,
+    dsConfig,
+    adapter,
+    tables,
+    columns,
+    modelName: modelInput,
+    targetTier: tierInput
+  };
+}
+
+// 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 { 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";
+function displayTierScore(score) {
+  p2.note(formatTierScore(score), "Tier Scorecard");
+}
+
+// src/setup/steps/scaffold.ts
+async function runScaffoldStep(ctx) {
+  const shouldRun = await p3.confirm({
+    message: "Scaffold Bronze metadata from database schema?"
+  });
+  if (p3.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p3.spinner();
+  spin.start("Scaffolding Bronze metadata...");
+  const result = scaffoldFromSchema2({
+    modelName: ctx.modelName,
+    dataSourceName: "default",
+    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 });
+  }
+  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 }
+  ];
+  for (const f of files) {
+    const fullPath = path14.join(ctx.contextDir, f.rel);
+    writeFileSync6(fullPath, f.content, "utf-8");
+    created.push(f.rel);
+  }
+  const config = loadConfig11(ctx.cwd);
+  const { graph } = await compile10({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = graph;
+  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");
+  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 yaml3 from "yaml";
+import {
+  compile as compile11,
+  computeTier as computeTier4,
+  suggestEnrichments as suggestEnrichments2,
+  loadConfig as loadConfig12
+} from "@runcontext/core";
+function findFileRecursive2(dir, suffix) {
+  if (!existsSync5(dir)) return void 0;
+  const entries = readdirSync2(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path15.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursive2(fullPath, suffix);
+      if (found) return found;
+    } else if (entry.name.endsWith(suffix)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+async function runEnrichSilverStep(ctx) {
+  const config = loadConfig12(ctx.cwd);
+  const { graph } = await compile11({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = graph;
+  const tierScore = computeTier4(ctx.modelName, graph);
+  if (tierScore.silver.passed) {
+    p4.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.`);
+    return { skipped: true, summary: "Model not found" };
+  }
+  const datasetNames = model.datasets.map((d) => d.name);
+  const suggestions = suggestEnrichments2("silver", tierScore, datasetNames);
+  const preview = [];
+  if (suggestions.governance?.trust) preview.push(`+ trust: ${suggestions.governance.trust}`);
+  if (suggestions.governance?.tags) preview.push(`+ tags: [${suggestions.governance.tags.join(", ")}]`);
+  if (suggestions.governance?.refreshAll) preview.push(`+ refresh: ${suggestions.governance.refreshAll} (all datasets)`);
+  if (suggestions.lineage) preview.push(`+ ${suggestions.lineage.upstream?.length ?? 0} lineage upstream source(s)`);
+  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");
+  }
+  const shouldRun = await p4.confirm({
+    message: "Apply Silver enrichments?"
+  });
+  if (p4.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p4.spinner();
+  spin.start("Enriching to Silver...");
+  const govFilePath = findFileRecursive2(ctx.contextDir, `${ctx.modelName}.governance.yaml`);
+  if (govFilePath) {
+    const govContent = readFileSync5(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;
+    if (suggestions.governance?.refreshAll) {
+      for (const dsName of Object.keys(govDoc.datasets ?? {})) {
+        govDoc.datasets[dsName].refresh = suggestions.governance.refreshAll;
+      }
+    }
+    if (suggestions.needsSampleValues) {
+      govDoc.fields = govDoc.fields ?? {};
+      try {
+        let count = 0;
+        for (const ds of model.datasets) {
+          if (count >= 2) break;
+          const tableName = ds.source?.split(".").pop() ?? ds.name;
+          for (const field of ds.fields ?? []) {
+            if (count >= 2) break;
+            const fieldKey = `${ds.name}.${field.name}`;
+            if (govDoc.fields[fieldKey]?.sample_values?.length > 0) continue;
+            try {
+              const result = await ctx.adapter.query(
+                `SELECT DISTINCT CAST("${field.name}" AS VARCHAR) AS val FROM "${tableName}" WHERE "${field.name}" IS NOT NULL LIMIT 5`
+              );
+              if (result.rows.length > 0) {
+                govDoc.fields[fieldKey] = govDoc.fields[fieldKey] ?? {};
+                govDoc.fields[fieldKey].sample_values = result.rows.map((r) => String(r.val));
+                count++;
+              }
+            } catch {
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    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 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 });
+    for (const term of suggestions.glossaryTerms) {
+      const termPath = path15.join(glossaryDir, `${term.id}.term.yaml`);
+      if (!existsSync5(termPath)) {
+        writeFileSync7(termPath, yaml3.stringify(term, { lineWidth: 120 }), "utf-8");
+      }
+    }
+  }
+  const { graph: newGraph } = await compile11({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = newGraph;
+  ctx.tierScore = computeTier4(ctx.modelName, newGraph);
+  spin.stop("Applied Silver enrichments");
+  displayTierScore(ctx.tierScore);
+  return { skipped: false, summary: ctx.tierScore.tier.toUpperCase() };
+}
+
+// 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 yaml4 from "yaml";
+import {
+  compile as compile12,
+  computeTier as computeTier5,
+  suggestEnrichments as suggestEnrichments3,
+  inferSemanticRole as inferSemanticRole2,
+  inferAggregation as inferAggregation2,
+  loadConfig as loadConfig13
+} from "@runcontext/core";
+function findFileRecursive3(dir, suffix) {
+  if (!existsSync6(dir)) return void 0;
+  const entries = readdirSync3(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path16.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursive3(fullPath, suffix);
+      if (found) return found;
+    } else if (entry.name.endsWith(suffix)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+async function runEnrichGoldStep(ctx) {
+  const config = loadConfig13(ctx.cwd);
+  const { graph } = await compile12({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = graph;
+  const tierScore = computeTier5(ctx.modelName, graph);
+  if (tierScore.gold.passed) {
+    p5.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.`);
+    return { skipped: true, summary: "Model not found" };
+  }
+  const datasetNames = model.datasets.map((d) => d.name);
+  const suggestions = suggestEnrichments3("gold", tierScore, datasetNames);
+  const preview = [];
+  if (suggestions.needsSemanticRoles) preview.push("+ Infer semantic_role for all fields");
+  if (suggestions.needsRulesFile) preview.push("+ Generate rules file (golden queries, guardrails, hierarchies)");
+  if (suggestions.governance?.trust) preview.push(`+ trust: ${suggestions.governance.trust}`);
+  preview.push("+ Add version, business_context stubs to governance");
+  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");
+  }
+  p5.log.warning("Gold enrichments create TODO placeholders that need manual curation.");
+  const shouldRun = await p5.confirm({
+    message: "Apply Gold enrichments?"
+  });
+  if (p5.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p5.spinner();
+  spin.start("Enriching to Gold...");
+  const govFilePath = findFileRecursive3(ctx.contextDir, `${ctx.modelName}.governance.yaml`);
+  if (govFilePath) {
+    const govContent = readFileSync6(govFilePath, "utf-8");
+    const govDoc = yaml4.parse(govContent) ?? {};
+    if (suggestions.governance?.trust) govDoc.trust = suggestions.governance.trust;
+    if (suggestions.needsSemanticRoles) {
+      govDoc.fields = govDoc.fields ?? {};
+      for (const ds of model.datasets) {
+        const tableName = ds.source?.split(".").pop() ?? ds.name;
+        let dbColumns = [];
+        try {
+          dbColumns = await ctx.adapter.listColumns(tableName);
+        } catch {
+        }
+        for (const field of ds.fields ?? []) {
+          const fieldKey = `${ds.name}.${field.name}`;
+          if (govDoc.fields[fieldKey]?.semantic_role) continue;
+          const col = dbColumns.find((c) => c.name === field.name);
+          const isPK = col?.is_primary_key ?? field.name.endsWith("_id");
+          const dataType = col?.data_type ?? "VARCHAR";
+          govDoc.fields[fieldKey] = govDoc.fields[fieldKey] ?? {};
+          const role = inferSemanticRole2(field.name, dataType, isPK);
+          govDoc.fields[fieldKey].semantic_role = role;
+          if (role === "metric") {
+            govDoc.fields[fieldKey].default_aggregation = inferAggregation2(field.name);
+            govDoc.fields[fieldKey].additive = govDoc.fields[fieldKey].default_aggregation === "SUM";
+          }
+        }
+      }
+    }
+    if (!govDoc.version) {
+      govDoc.version = "0.1.0";
+    }
+    if (!govDoc.business_context || govDoc.business_context.length === 0) {
+      govDoc.business_context = [
+        { name: "TODO: Use Case Name", description: "TODO: Describe the analytical use case and business value." }
+      ];
+    }
+    writeFileSync8(govFilePath, yaml4.stringify(govDoc, { lineWidth: 120 }), "utf-8");
+  }
+  const modelFilePath = findFileRecursive3(ctx.contextDir, `${ctx.modelName}.osi.yaml`);
+  if (modelFilePath) {
+    const modelContent = readFileSync6(modelFilePath, "utf-8");
+    const modelDoc = yaml4.parse(modelContent) ?? {};
+    const semModels = modelDoc.semantic_model ?? [];
+    let changed = false;
+    for (const sm of semModels) {
+      if (sm.name !== ctx.modelName) continue;
+      if (!sm.ai_context) {
+        sm.ai_context = "TODO: Describe how an AI agent should use this model, common pitfalls, and important filters.";
+        changed = true;
+      }
+      if (!sm.relationships || sm.relationships.length === 0) {
+        const datasets = sm.datasets ?? [];
+        const dsNames = new Set(datasets.map((d) => d.name));
+        const inferred = [];
+        for (const ds of datasets) {
+          for (const field of ds.fields ?? []) {
+            const fname = field.name;
+            const idMatch = fname.match(/^(.+)_id$/);
+            if (idMatch && idMatch[1]) {
+              const targetBase = idMatch[1];
+              for (const targetDs of datasets) {
+                if (targetDs.name === ds.name) continue;
+                const targetName = targetDs.name;
+                if (targetName.includes(targetBase) || targetBase.includes(targetName)) {
+                  const targetHasField = (targetDs.fields ?? []).some((f) => f.name === fname);
+                  if (targetHasField) {
+                    const relName = `${ds.name}-to-${targetName}`;
+                    if (!inferred.some((r) => r.name === relName)) {
+                      inferred.push({
+                        name: relName,
+                        from: ds.name,
+                        to: targetName,
+                        from_columns: [fname],
+                        to_columns: [fname]
+                      });
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        if (inferred.length > 0) {
+          sm.relationships = inferred;
+          changed = true;
+        }
+      }
+    }
+    if (changed) {
+      writeFileSync8(modelFilePath, yaml4.stringify(modelDoc, { lineWidth: 120 }), "utf-8");
+    }
+  }
+  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 rulesDoc = {
+        model: ctx.modelName,
+        golden_queries: [
+          { question: "TODO: What is the total count?", sql: "SELECT COUNT(*) FROM table_name" },
+          { question: "TODO: What are the top records?", sql: "SELECT * FROM table_name LIMIT 10" },
+          { question: "TODO: What is the distribution?", sql: "SELECT column, COUNT(*) FROM table_name GROUP BY column" }
+        ],
+        business_rules: [
+          { name: "TODO: rule-name", definition: "TODO: describe the business rule" }
+        ],
+        guardrail_filters: [
+          { name: "TODO: filter-name", filter: "column IS NOT NULL", reason: "TODO: explain why" }
+        ],
+        hierarchies: [
+          { name: "TODO: hierarchy-name", levels: ["level1", "level2"], dataset: datasetNames[0] ?? "dataset" }
+        ]
+      };
+      writeFileSync8(rulesPath, yaml4.stringify(rulesDoc, { lineWidth: 120 }), "utf-8");
+    }
+  }
+  const { graph: newGraph } = await compile12({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = newGraph;
+  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);
+  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 {
+  compile as compile13,
+  LintEngine as LintEngine5,
+  ALL_RULES as ALL_RULES6,
+  computeTier as computeTier6,
+  loadConfig as loadConfig14
+} from "@runcontext/core";
+async function runVerifyStep(ctx) {
+  const shouldRun = await p6.confirm({
+    message: "Verify metadata against live data?"
+  });
+  if (p6.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p6.spinner();
+  spin.start("Verifying against database...");
+  const config = loadConfig14(ctx.cwd);
+  const { graph } = await compile13({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  graph.dataValidation = await collectDataValidation(ctx.adapter, graph);
+  const engine = new LintEngine5();
+  for (const rule of ALL_RULES6) {
+    if (rule.id.startsWith("data/")) engine.register(rule);
+  }
+  const dataDiags = engine.run(graph);
+  ctx.graph = graph;
+  ctx.tierScore = computeTier6(ctx.modelName, graph);
+  const errors = dataDiags.filter((d) => d.severity === "error").length;
+  const warnings = dataDiags.filter((d) => d.severity === "warning").length;
+  if (dataDiags.length === 0) {
+    spin.stop("All data validation checks passed");
+  } 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");
+  }
+  return {
+    skipped: false,
+    summary: dataDiags.length === 0 ? "Clean" : `${errors} errors, ${warnings} warnings`
+  };
+}
+
+// src/setup/steps/autofix.ts
+import * as p7 from "@clack/prompts";
+import fs4 from "fs";
+import {
+  compile as compile14,
+  LintEngine as LintEngine6,
+  ALL_RULES as ALL_RULES7,
+  applyFixes as applyFixes4,
+  computeTier as computeTier7,
+  loadConfig as loadConfig15
+} from "@runcontext/core";
+async function runAutofixStep(ctx) {
+  const config = loadConfig15(ctx.cwd);
+  const { graph } = await compile14({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  graph.dataValidation = await collectDataValidation(ctx.adapter, graph);
+  const engine = new LintEngine6();
+  for (const rule of ALL_RULES7) engine.register(rule);
+  const diagnostics = engine.run(graph);
+  const fixable = diagnostics.filter((d) => d.fixable);
+  if (fixable.length === 0) {
+    p7.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({
+    message: `Auto-fix ${fixable.length} issue(s)?`
+  });
+  if (p7.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p7.spinner();
+  spin.start("Fixing...");
+  const readFile = (filePath) => fs4.readFileSync(filePath, "utf-8");
+  const fixedFiles = applyFixes4(fixable, readFile);
+  for (const [file, content] of fixedFiles) {
+    fs4.writeFileSync(file, content, "utf-8");
+  }
+  const { graph: newGraph } = await compile14({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = newGraph;
+  ctx.tierScore = computeTier7(ctx.modelName, newGraph);
+  spin.stop(`Fixed ${fixable.length} issue(s) in ${fixedFiles.size} file(s)`);
+  displayTierScore(ctx.tierScore);
+  return { skipped: false, summary: `${fixable.length} issues fixed` };
+}
+
+// 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) {
+  const modelName = ctx.modelName;
+  const tier = ctx.tierScore?.tier?.toUpperCase() ?? "UNKNOWN";
+  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");
+  const failingChecks = [];
+  if (ctx.tierScore) {
+    for (const check of ctx.tierScore.bronze.checks) {
+      if (!check.passed) failingChecks.push(`- ${check.id}: ${check.detail ?? check.label}`);
+    }
+    for (const check of ctx.tierScore.silver.checks) {
+      if (!check.passed) failingChecks.push(`- ${check.id}: ${check.detail ?? check.label}`);
+    }
+    for (const check of ctx.tierScore.gold.checks) {
+      if (!check.passed) failingChecks.push(`- ${check.id}: ${check.detail ?? check.label}`);
+    }
+  }
+  const failingSection = failingChecks.length > 0 ? `### Failing Checks
+
+${failingChecks.join("\n")}` : "All checks passing.";
+  return `# ContextKit Agent Instructions
+
+You have two MCP servers: **duckdb** (query data) and **contextkit** (query metadata).
+
+Model: **${modelName}** | Current Tier: **${tier}**
+
+## The Cardinal Rule: Never Fabricate Metadata
+
+**Every piece of metadata you write must be grounded in evidence from the actual data.**
+
+- NEVER invent owner names, emails, team names, or contact info
+- NEVER write a field description that is just the column name repeated
+- NEVER assign a semantic_role without first querying the column's actual values
+- NEVER mark a field as additive without understanding what summing it means
+- NEVER write lineage entries without knowing the actual data sources
+- 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.
+
+## 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
+
+## When Asked to Reach Gold
+
+Work through ALL failing Gold checks iteratively until \`context tier\` reports 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
+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
+
+You must iterate \u2014 a single pass is never enough. Each \`context tier\` run may reveal new failures after earlier ones are fixed.
+
+## How to Curate Metadata (the right way)
+
+### Before writing ANY metadata, query the database first
+
+For every field you're about to describe or classify:
+
+\`\`\`sql
+-- What type of values does this column contain?
+SELECT DISTINCT column_name FROM table LIMIT 20;
+
+-- For numeric columns: is this a metric or dimension?
+SELECT MIN(col), MAX(col), AVG(col), COUNT(DISTINCT col) FROM table;
+
+-- For potential metrics: does SUM make sense?
+-- If SUM produces a meaningful business number \u2192 additive: true
+-- If SUM is meaningless (e.g., summing percentages, scores, ratings) \u2192 additive: false
+\`\`\`
+
+### Semantic Role Decision Tree
+
+Query the column first, then apply this logic:
+
+1. **Is it a primary key or foreign key?** \u2192 \`identifier\`
+2. **Is it a date or timestamp?** \u2192 \`date\`
+3. **Is it numeric AND does aggregation make business sense?**
+   - Does SUM make sense? (counts, amounts, quantities) \u2192 \`metric\`, \`additive: true\`
+   - Does only AVG/MIN/MAX make sense? (rates, percentages, scores, ratings) \u2192 \`metric\`, \`additive: false\`
+4. **Everything else** \u2192 \`dimension\`
+
+Common mistakes to avoid:
+- \`stars\` (ratings) \u2192 metric with AVG, NOT additive (summing star ratings is meaningless)
+- \`_per_10k_people\` (rates) \u2192 metric with AVG, NOT additive
+- \`_score\` (composite scores) \u2192 metric with AVG, NOT additive
+- \`useful/funny/cool\` (vote counts) \u2192 metric with SUM, additive
+- \`_count\` fields \u2192 metric with SUM, additive (usually)
+
+### Field Descriptions
+
+Write descriptions that help someone who has never seen this database understand what the column contains. Include:
+- What the value represents
+- Units or scale (if applicable)
+- Where the data comes from (if known)
+- Any known quirks or caveats
+
+Bad: \`description: total_population\`
+Good: \`description: Total resident population of the census tract from American Community Survey 5-year estimates\`
+
+Bad: \`description: stars\`
+Good: \`description: Average Yelp star rating (1.0-5.0 scale) based on all reviews for this business\`
+
+### Lineage
+
+Upstream sources are the EXTERNAL systems that feed data into this warehouse. They are NOT the tables in the warehouse itself.
+
+Ask yourself: "Where did this data originally come from before it was loaded here?"
+
+Bad lineage:
+\`\`\`yaml
+upstream:
+  - source: yelp_business    # This is a table IN the warehouse, not an upstream source
+    type: pipeline
+\`\`\`
+
+Good lineage:
+\`\`\`yaml
+upstream:
+  - source: yelp-academic-dataset
+    type: file
+    notes: Yelp Open Dataset (academic use), loaded via CSV import
+\`\`\`
+
+### Owner Files
+
+Do NOT create fake owner identities. If the real owner is unknown:
+- Keep the existing owner file as-is
+- Note in the file that contact info needs to be filled in by a real person
+- NEVER invent email addresses like \`analytics@example.com\`
+
+### Business Context
+
+Write business_context entries that describe real analytical use cases you can verify from the data. Query the data to understand what questions it can answer before writing narratives.
+
+### Golden Queries
+
+Every golden query MUST be tested against the actual database before you write it. Run the SQL, verify it returns sensible results, then document it.
+
+### Data Quality
+
+When you discover data quality issues (null values, broken joins, missing data), FLAG THEM \u2014 don't hide them. Add notes in governance or report them to the user.
+
+## This Project
+
+### Datasets
+
+${datasetList || "(none detected)"}
+
+${failingSection}
+
+## MCP Tools
+
+| Tool | Parameters | What it does |
+|------|-----------|-------------|
+| \`context_search\` | \`query\` | Find models, datasets, fields, terms by keyword |
+| \`context_explain\` | \`model\` | Full model details \u2014 governance, rules, lineage, tier |
+| \`context_validate\` | \u2014 | Run linter, get errors and warnings |
+| \`context_tier\` | \`model\` | Tier scorecard with all check results |
+| \`context_golden_query\` | \`question\` | Find pre-validated SQL for a question |
+| \`context_guardrails\` | \`tables[]\` | Get required WHERE clauses for tables |
+
+## Tier Checks Quick Reference
+
+**Bronze (7):** descriptions, owner, security, grain, table_type
+**Silver (+6):** trust, 2+ tags, glossary linked, lineage, refresh, 2+ sample_values
+**Gold (+21):** semantic_role on ALL fields, metric aggregation/additive, 1+ guardrail, 3+ golden queries, 1+ business rule, 1+ hierarchy, 1+ default_filter, trust=endorsed, contactable owner, 1+ relationship, description \u226550 chars, ai_context (no TODO), 1+ business_context, version, field descriptions not lazy, glossary definitions substantive, lineage references real sources, grain statements specific, ai_context filled in
+
+## YAML Formats
+
+**Governance** (\`context/governance/*.governance.yaml\`):
+\`\`\`yaml
+model: my-model
+owner: team-name
+version: "1.0.0"
+trust: endorsed
+security: internal
+tags: [domain-tag-1, domain-tag-2]
+business_context:
+  - name: Use Case Name
+    description: What analytical question this data answers and for whom.
+datasets:
+  my_table:
+    grain: "One row per [entity] identified by [key]"
+    table_type: fact    # fact | dimension | event | view
+    refresh: daily
+fields:
+  dataset.field:
+    semantic_role: metric        # metric | dimension | identifier | date
+    default_aggregation: SUM     # SUM | AVG | COUNT | COUNT_DISTINCT | MIN | MAX
+    additive: true               # can this metric be summed across dimensions?
+    default_filter: "is_open = 1"
+    sample_values: ["val1", "val2"]
+\`\`\`
+
+**Rules** (\`context/rules/*.rules.yaml\`):
+\`\`\`yaml
+model: my-model
+golden_queries:
+  - question: What are the top items by count?
+    sql: SELECT name, count FROM my_table ORDER BY count DESC LIMIT 10
+    intent: Identify top performers by volume
+    caveats: Filters to active records only
+business_rules:
+  - name: valid-ratings
+    definition: All ratings must be between 1 and 5
+guardrail_filters:
+  - name: active-only
+    filter: "status = 'active'"
+    reason: Exclude inactive records from analytics
+    tables: [my_table]
+hierarchies:
+  - name: geography
+    levels: [state, city, postal_code]
+    dataset: my_table
+\`\`\`
+
+## CLI Commands
+
+\`\`\`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
+\`\`\`
+`;
+}
+async function runClaudeMdStep(ctx) {
+  const instructionsPath = path17.join(ctx.contextDir, "AGENT_INSTRUCTIONS.md");
+  if (existsSync7(instructionsPath)) {
+    const shouldOverwrite = await p8.confirm({
+      message: "context/AGENT_INSTRUCTIONS.md already exists. Overwrite with updated instructions?"
+    });
+    if (p8.isCancel(shouldOverwrite) || !shouldOverwrite) {
+      return { skipped: true, summary: "context/AGENT_INSTRUCTIONS.md already exists, kept existing" };
+    }
+  }
+  const content = buildClaudeMd(ctx);
+  writeFileSync9(instructionsPath, content, "utf-8");
+  p8.log.success("Generated context/AGENT_INSTRUCTIONS.md with agent curation instructions");
+  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 ")));
+  const ctx = await runConnectStep();
+  if (!ctx) return;
+  try {
+    const steps = [
+      { name: "Scaffold Bronze", fn: runScaffoldStep }
+    ];
+    if (ctx.targetTier === "silver" || ctx.targetTier === "gold") {
+      steps.push({ name: "Enrich to Silver", fn: runEnrichSilverStep });
+    }
+    if (ctx.targetTier === "gold") {
+      steps.push({ name: "Enrich to Gold", fn: runEnrichGoldStep });
+    }
+    steps.push(
+      { name: "Verify data", fn: runVerifyStep },
+      { name: "Auto-fix", fn: runAutofixStep },
+      { name: "Generate agent instructions", fn: runClaudeMdStep }
+    );
+    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}`);
+      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");
+    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.`);
+    } else if (ctx.targetTier === "gold" && currentTier !== "gold") {
+      const nextSteps = [
+        `Your metadata is at ${chalk16.bold(currentTier.toUpperCase())} \u2014 Gold needs curation.`,
+        "",
+        `${chalk16.bold("To reach Gold, tell your AI assistant:")}`,
+        "",
+        `  "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."`
+      ];
+      p9.note(nextSteps.join("\n"), "Next Steps");
+      p9.outro(`Run ${chalk16.cyan("context dev")} to watch for changes as you edit.`);
+    } else {
+      p9.outro(`Run ${chalk16.cyan("context tier")} to check your scorecard.`);
+    }
+  } finally {
+    try {
+      await ctx.adapter.disconnect();
+    } catch {
+    }
+  }
+});
+
 // src/index.ts
-var program = new Command12();
-program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.2.1");
+var program = new Command16();
+program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.3.1");
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
 program.addCommand(tierCommand);
@@ -1026,6 +2595,10 @@ program.addCommand(initCommand);
 program.addCommand(siteCommand);
 program.addCommand(serveCommand);
 program.addCommand(validateOsiCommand);
+program.addCommand(introspectCommand);
+program.addCommand(verifyCommand);
+program.addCommand(enrichCommand);
 program.addCommand(rulesCommand);
+program.addCommand(setupCommand);
 program.parse();
 //# sourceMappingURL=index.js.map