@bonnard/cli 0.2.1 → 0.2.2

package/dist/bin/bon.mjs

@@ -565,17 +565,22 @@ function createAgentTemplates(cwd, env) {
 	const claudeSkillsDir = path.join(cwd, ".claude", "skills");
 	fs.mkdirSync(claudeRulesDir, { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-get-started"), { recursive: true });
+	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	writeTemplateFile(sharedBonnard, path.join(claudeRulesDir, "bonnard.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(claudeSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(claudeSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), createdFiles);
 	mergeSettingsJson(loadJsonTemplate("claude/settings.json"), path.join(cwd, ".claude", "settings.json"), createdFiles);
 	const cursorRulesDir = path.join(cwd, ".cursor", "rules");
 	fs.mkdirSync(cursorRulesDir, { recursive: true });
 	writeTemplateFile(withCursorFrontmatter(sharedBonnard, "Bonnard semantic layer project context", true), path.join(cursorRulesDir, "bonnard.mdc"), createdFiles);
 	writeTemplateFile(loadTemplate("cursor/rules/bonnard-get-started.mdc"), path.join(cursorRulesDir, "bonnard-get-started.mdc"), createdFiles);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-metabase-migrate.mdc"), path.join(cursorRulesDir, "bonnard-metabase-migrate.mdc"), createdFiles);
 	const codexSkillsDir = path.join(cwd, ".agents", "skills");
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-get-started"), { recursive: true });
+	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	writeTemplateFile(sharedBonnard, path.join(cwd, "AGENTS.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(codexSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(codexSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), createdFiles);
 	return createdFiles;
 }
 async function initCommand() {
@@ -867,10 +872,10 @@ async function whoamiCommand(options = {}) {
 *
 * Env vars are resolved at deploy time, not import time.
 */
-const BON_DIR$1 = ".bon";
+const BON_DIR$2 = ".bon";
 const DATASOURCES_FILE$1 = "datasources.yaml";
 function getBonDir(cwd = process.cwd()) {
-	return path.join(cwd, BON_DIR$1);
+	return path.join(cwd, BON_DIR$2);
 }
 function getDatasourcesPath$1(cwd = process.cwd()) {
 	return path.join(getBonDir(cwd), DATASOURCES_FILE$1);
@@ -972,10 +977,10 @@ function resolveEnvVarsInCredentials(credentials) {
 /**
 * Credential utilities (git tracking check)
 */
-const BON_DIR = ".bon";
+const BON_DIR$1 = ".bon";
 const DATASOURCES_FILE = "datasources.yaml";
 function getDatasourcesPath(cwd = process.cwd()) {
-	return path.join(cwd, BON_DIR, DATASOURCES_FILE);
+	return path.join(cwd, BON_DIR$1, DATASOURCES_FILE);
 }
 /**
 * Check if datasources file is tracked by git (it shouldn't be - contains credentials)
@@ -1134,7 +1139,7 @@ function mapDbtConnection(connection) {
 
 //#endregion
 //#region src/commands/datasource/add.ts
-async function prompts() {
+async function prompts$1() {
 	return import("@inquirer/prompts");
 }
 const WAREHOUSE_CONFIGS = [
@@ -1353,7 +1358,7 @@ async function importFromDbt(options) {
 		await importConnections(connections.filter((c) => c.isDefaultTarget));
 		return;
 	}
-	const { checkbox } = await prompts();
+	const { checkbox } = await prompts$1();
 	console.log();
 	console.log(pc.bold(`Found ${connections.length} connections in ~/.dbt/profiles.yml:`));
 	console.log();
@@ -1413,7 +1418,7 @@ async function importConnections(connections) {
 * Add datasource manually (with flags and/or interactive prompts)
 */
 async function addManual(options) {
-	const { input, select, password, confirm } = await prompts();
+	const { input, select, password, confirm } = await prompts$1();
 	const nonInteractive = isNonInteractive(options);
 	if (isDatasourcesTrackedByGit()) console.log(pc.yellow("Warning: .bon/datasources.yaml is tracked by git. Add it to .gitignore!"));
 	let name = options.name;
@@ -2524,6 +2529,1397 @@ async function cubeQueryCommand(queryInput, options = {}) {
 	}
 }
 
+//#endregion
+//#region src/lib/metabase/config.ts
+/**
+* Metabase config storage (.bon/metabase.yaml)
+*
+* Stores API key and URL for Metabase connectivity.
+* File has 0o600 permissions since it contains the API key.
+*/
+const BON_DIR = ".bon";
+const CONFIG_FILE = "metabase.yaml";
+function getConfigPath(cwd = process.cwd()) {
+	return path.join(cwd, BON_DIR, CONFIG_FILE);
+}
+function loadMetabaseConfig(cwd = process.cwd()) {
+	const filePath = getConfigPath(cwd);
+	if (!fs.existsSync(filePath)) return null;
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		return YAML.parse(content)?.metabase ?? null;
+	} catch {
+		return null;
+	}
+}
+function saveMetabaseConfig(config, cwd = process.cwd()) {
+	ensureBonDir(cwd);
+	const filePath = getConfigPath(cwd);
+	const file = { metabase: config };
+	const content = `# Bonnard Metabase configuration
+# This file contains an API key - add .bon/ to .gitignore
+
+` + YAML.stringify(file, { indent: 2 });
+	fs.writeFileSync(filePath, content, { mode: 384 });
+}
+
+//#endregion
+//#region src/lib/metabase/client.ts
+var MetabaseApiError = class extends Error {
+	constructor(status, endpoint, message) {
+		super(message);
+		this.status = status;
+		this.endpoint = endpoint;
+		this.name = "MetabaseApiError";
+	}
+};
+function createMetabaseClient(config) {
+	const baseUrl = config.url.replace(/\/+$/, "");
+	async function metabaseFetch(endpoint, options = {}) {
+		const url = `${baseUrl}/api${endpoint}`;
+		const res = await fetch(url, {
+			...options,
+			headers: {
+				"X-API-KEY": config.apiKey,
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+		if (!res.ok) {
+			let message = `HTTP ${res.status}`;
+			try {
+				const body = await res.text();
+				if (body) message = body;
+			} catch {}
+			throw new MetabaseApiError(res.status, endpoint, message);
+		}
+		return res.json();
+	}
+	return {
+		async getCurrentUser() {
+			return metabaseFetch("/user/current");
+		},
+		async getDatabases() {
+			return (await metabaseFetch("/database")).data;
+		},
+		async getCollections() {
+			return metabaseFetch("/collection");
+		},
+		async getCollectionTree() {
+			return metabaseFetch("/collection/tree");
+		},
+		async getCards() {
+			return metabaseFetch("/card");
+		},
+		async getCard(id) {
+			return metabaseFetch(`/card/${id}`);
+		},
+		async getDashboards() {
+			return metabaseFetch("/dashboard");
+		},
+		async getDashboard(id) {
+			return metabaseFetch(`/dashboard/${id}`);
+		},
+		async convertToNativeSQL(datasetQuery) {
+			return (await metabaseFetch("/dataset/native", {
+				method: "POST",
+				body: JSON.stringify(datasetQuery)
+			})).query;
+		},
+		async getDatabaseMetadata(id) {
+			return metabaseFetch(`/database/${id}/metadata`);
+		},
+		async getPermissionGroups() {
+			return metabaseFetch("/permissions/group");
+		},
+		async getPermissionsGraph() {
+			return metabaseFetch("/permissions/graph");
+		},
+		async getCollectionItems(id) {
+			return (await metabaseFetch(`/collection/${id}/items?models=card&models=dataset&models=metric&models=dashboard`)).data;
+		},
+		async getPopularItems() {
+			return metabaseFetch("/activity/popular_items");
+		}
+	};
+}
+
+//#endregion
+//#region src/commands/metabase/connect.ts
+async function prompts() {
+	return import("@inquirer/prompts");
+}
+async function metabaseConnectCommand(options) {
+	const nonInteractive = !!(options.url && options.apiKey);
+	if (loadMetabaseConfig()) if (options.force) console.log(pc.dim("Overwriting existing Metabase configuration"));
+	else if (nonInteractive) {
+		console.error(pc.red("Metabase is already configured. Use --force to overwrite."));
+		process.exit(1);
+	} else {
+		const { confirm } = await prompts();
+		if (!await confirm({
+			message: "Metabase is already configured. Overwrite?",
+			default: false
+		})) {
+			console.log(pc.yellow("Cancelled."));
+			return;
+		}
+	}
+	let url = options.url;
+	let apiKey = options.apiKey;
+	if (!nonInteractive) {
+		const { input, password } = await prompts();
+		if (!url) url = await input({
+			message: "Metabase URL (e.g. https://metabase.example.com):",
+			validate: (v) => {
+				try {
+					const u = new URL(v);
+					if (u.protocol !== "https:" && u.protocol !== "http:") return "URL must use http or https";
+					return true;
+				} catch {
+					return "Enter a valid URL";
+				}
+			}
+		});
+		if (!apiKey) apiKey = await password({ message: "API key:" });
+	}
+	if (!url || !apiKey) {
+		console.error(pc.red("Both --url and --api-key are required in non-interactive mode."));
+		process.exit(1);
+	}
+	try {
+		new URL(url);
+	} catch {
+		console.error(pc.red(`Invalid URL: ${url}`));
+		process.exit(1);
+	}
+	url = url.replace(/\/+$/, "");
+	console.log();
+	console.log(pc.dim("Testing connection..."));
+	const client = createMetabaseClient({
+		url,
+		apiKey
+	});
+	try {
+		const user = await client.getCurrentUser();
+		console.log(pc.green("✓ Connected to Metabase"));
+		console.log();
+		console.log(`  URL:    ${url}`);
+		console.log(`  User:   ${user.first_name} ${user.last_name} (${user.email})`);
+		console.log(`  Admin:  ${user.is_superuser ? "Yes" : "No"}`);
+		console.log();
+		saveMetabaseConfig({
+			url,
+			apiKey
+		});
+		console.log(pc.green("✓ Configuration saved to .bon/metabase.yaml"));
+		console.log();
+		console.log(pc.dim("Explore your Metabase content: bon metabase explore"));
+	} catch (err) {
+		if (err instanceof MetabaseApiError) if (err.status === 401 || err.status === 403) {
+			console.error(pc.red("Authentication failed. Check your API key."));
+			console.log();
+			console.log(pc.dim("Generate an API key in Metabase:"));
+			console.log(pc.dim("  Admin > Settings > Authentication > API Keys"));
+		} else console.error(pc.red(`Metabase API error (${err.status}): ${err.message}`));
+		else if (err instanceof TypeError && (err.message.includes("fetch") || err.message.includes("ECONNREFUSED"))) {
+			console.error(pc.red(`Could not connect to ${url}`));
+			console.log(pc.dim("Check the URL and ensure Metabase is running."));
+		} else console.error(pc.red(`Connection failed: ${err.message}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/metabase/explore.ts
+function requireConfig() {
+	const config = loadMetabaseConfig();
+	if (!config) {
+		console.error(pc.red("Metabase is not configured."));
+		console.log(pc.dim("Run: bon metabase connect"));
+		process.exit(1);
+	}
+	return createMetabaseClient(config);
+}
+function getCardType$1(card) {
+	if (card.type === "model" || card.dataset) return "model";
+	if (card.type === "metric") return "metric";
+	return "question";
+}
+function padColumn(value, width) {
+	return value.padEnd(width);
+}
+const INACTIVE_MONTHS$1 = 3;
+function isCardActive$1(card) {
+	if (!card.last_used_at) return false;
+	const cutoff = /* @__PURE__ */ new Date();
+	cutoff.setMonth(cutoff.getMonth() - INACTIVE_MONTHS$1);
+	return new Date(card.last_used_at) >= cutoff;
+}
+function activityScore$1(card) {
+	const views = card.view_count || 0;
+	return isCardActive$1(card) ? views : Math.round(views * .1);
+}
+function formatLastUsed$1(card) {
+	if (!card.last_used_at) return "never";
+	const d = new Date(card.last_used_at);
+	const diffMs = (/* @__PURE__ */ new Date()).getTime() - d.getTime();
+	const diffDays = Math.floor(diffMs / (1e3 * 60 * 60 * 24));
+	if (diffDays === 0) return "today";
+	if (diffDays === 1) return "yesterday";
+	if (diffDays < 30) return `${diffDays}d ago`;
+	if (diffDays < 365) return `${Math.floor(diffDays / 30)}mo ago`;
+	return `${Math.floor(diffDays / 365)}y ago`;
+}
+async function showOverview(client) {
+	const [databases, collections, cards, dashboards] = await Promise.all([
+		client.getDatabases(),
+		client.getCollections(),
+		client.getCards(),
+		client.getDashboards()
+	]);
+	const activeCards = cards.filter((c) => !c.archived);
+	const models = activeCards.filter((c) => getCardType$1(c) === "model");
+	const metrics = activeCards.filter((c) => getCardType$1(c) === "metric");
+	const questions = activeCards.filter((c) => getCardType$1(c) === "question");
+	const activeCollections = collections.filter((c) => !c.archived && c.personal_owner_id === null);
+	const activeDashboards = dashboards.filter((d) => !d.archived);
+	const recentlyActive = activeCards.filter(isCardActive$1).length;
+	const inactive = activeCards.length - recentlyActive;
+	console.log();
+	console.log(pc.bold("Metabase Overview"));
+	console.log();
+	console.log(`  Databases:    ${databases.length}`);
+	console.log(`  Collections:  ${activeCollections.length}`);
+	console.log(`  Models:       ${models.length}`);
+	console.log(`  Metrics:      ${metrics.length}`);
+	console.log(`  Questions:    ${questions.length}`);
+	console.log(`  Dashboards:   ${activeDashboards.length}`);
+	console.log();
+	console.log(`  Active (last ${INACTIVE_MONTHS$1}mo):  ${pc.green(String(recentlyActive))}`);
+	console.log(`  Inactive:     ${pc.dim(String(inactive))}`);
+	console.log();
+	console.log(pc.dim("Explore further:"));
+	console.log(pc.dim("  bon metabase explore databases"));
+	console.log(pc.dim("  bon metabase explore collections"));
+	console.log(pc.dim("  bon metabase explore cards"));
+	console.log(pc.dim("  bon metabase explore dashboards"));
+	console.log(pc.dim("  bon metabase explore card <id>"));
+	console.log(pc.dim("  bon metabase explore dashboard <id>"));
+	console.log(pc.dim("  bon metabase explore database <id>"));
+	console.log(pc.dim("  bon metabase explore table <id>"));
+	console.log(pc.dim("  bon metabase explore collection <id>"));
+}
+async function showDatabases(client) {
+	const databases = await client.getDatabases();
+	console.log();
+	console.log(pc.bold("Databases"));
+	console.log();
+	if (databases.length === 0) {
+		console.log(pc.dim("  No databases found."));
+		return;
+	}
+	console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim(padColumn("NAME", 30))}${pc.dim(padColumn("ENGINE", 16))}${pc.dim("SAMPLE")}`);
+	for (const db of databases) console.log(`  ${padColumn(String(db.id), 6)}${padColumn(db.name, 30)}${padColumn(db.engine, 16)}${db.is_sample ? "Yes" : ""}`);
+}
+function printTree(nodes, indent = 0) {
+	for (const node of nodes) {
+		if (node.personal_owner_id !== null) continue;
+		const prefix = indent === 0 ? "  " : "  " + "  ".repeat(indent);
+		const icon = node.children.length > 0 ? "+" : "-";
+		console.log(`${prefix}${pc.dim(icon)} ${node.name} ${pc.dim(`(${node.id})`)}`);
+		if (node.children.length > 0) printTree(node.children, indent + 1);
+	}
+}
+async function showCollections(client) {
+	const tree = await client.getCollectionTree();
+	console.log();
+	console.log(pc.bold("Collections"));
+	console.log();
+	const filtered = tree.filter((n) => n.personal_owner_id === null);
+	if (filtered.length === 0) {
+		console.log(pc.dim("  No collections found."));
+		return;
+	}
+	printTree(filtered);
+}
+async function showCards(client) {
+	const active = (await client.getCards()).filter((c) => !c.archived);
+	const models = active.filter((c) => getCardType$1(c) === "model");
+	const metrics = active.filter((c) => getCardType$1(c) === "metric");
+	const questions = active.filter((c) => getCardType$1(c) === "question");
+	const CAP = 50;
+	console.log();
+	const groups = [
+		{
+			label: "Models",
+			items: models
+		},
+		{
+			label: "Metrics",
+			items: metrics
+		},
+		{
+			label: "Questions",
+			items: questions
+		}
+	];
+	for (const group of groups) {
+		if (group.items.length === 0) continue;
+		const groupActive = group.items.filter(isCardActive$1).length;
+		const groupInactive = group.items.length - groupActive;
+		const sorted = [...group.items].sort((a, b) => activityScore$1(b) - activityScore$1(a));
+		console.log(pc.bold(`${group.label} (${group.items.length})`) + pc.dim(` — ${groupActive} active, ${groupInactive} inactive`));
+		console.log();
+		console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim(padColumn("NAME", 36))}${pc.dim(padColumn("DISPLAY", 14))}${pc.dim(padColumn("LAST USED", 12))}${pc.dim("VIEWS")}`);
+		const display = sorted.slice(0, CAP);
+		for (const card of display) {
+			const lastUsed = formatLastUsed$1(card);
+			const active = isCardActive$1(card);
+			const name = card.name.slice(0, 34);
+			const line = `  ${padColumn(String(card.id), 6)}${padColumn(name, 36)}${padColumn(card.display, 14)}${padColumn(lastUsed, 12)}${card.view_count || 0}`;
+			console.log(active ? line : pc.dim(line));
+		}
+		if (group.items.length > CAP) console.log(pc.dim(`  ... and ${group.items.length - CAP} more`));
+		console.log();
+	}
+	if (models.length === 0 && metrics.length === 0 && questions.length === 0) console.log(pc.dim("  No cards found."));
+	console.log(pc.dim("View details: bon metabase explore card <id>"));
+}
+async function showCardDetail(client, id) {
+	const card = await client.getCard(id);
+	const cardType = getCardType$1(card);
+	console.log();
+	console.log(pc.bold(card.name));
+	if (card.description) console.log(pc.dim(card.description));
+	console.log();
+	const active = isCardActive$1(card);
+	const lastUsed = formatLastUsed$1(card);
+	const activityLabel = active ? pc.green("active") : pc.dim("inactive");
+	console.log(`  Type:       ${cardType}`);
+	console.log(`  Display:    ${card.display}`);
+	console.log(`  Database:   ${card.database_id}`);
+	console.log(`  Views:      ${card.view_count || 0}`);
+	console.log(`  Last used:  ${lastUsed} (${activityLabel})`);
+	console.log();
+	let sql = null;
+	const dq = card.dataset_query;
+	if (dq.type === "native" && dq.native?.query) sql = dq.native.query;
+	else if (dq.stages?.[0]?.["lib/type"] === "mbql.stage/native" && typeof dq.stages[0].native === "string") sql = dq.stages[0].native;
+	else if (dq.type === "query") try {
+		sql = await client.convertToNativeSQL(dq);
+	} catch (err) {
+		if (err instanceof MetabaseApiError) console.log(pc.dim(`  Could not convert MBQL to SQL: ${err.message}`));
+	}
+	else if (dq.stages?.[0]?.["lib/type"] === "mbql.stage/mbql") try {
+		sql = await client.convertToNativeSQL(dq);
+	} catch (err) {
+		if (err instanceof MetabaseApiError) console.log(pc.dim(`  Could not convert MBQL to SQL: ${err.message}`));
+	}
+	if (sql) {
+		console.log(pc.bold("SQL"));
+		console.log();
+		for (const line of sql.trim().split("\n")) console.log(`  ${line}`);
+		console.log();
+	}
+	if (card.result_metadata && card.result_metadata.length > 0) {
+		console.log(pc.bold("Columns"));
+		console.log();
+		console.log(`  ${pc.dim(padColumn("NAME", 30))}${pc.dim(padColumn("DISPLAY NAME", 30))}${pc.dim("TYPE")}`);
+		for (const col of card.result_metadata) console.log(`  ${padColumn(col.name, 30)}${padColumn(col.display_name, 30)}${col.base_type}`);
+	}
+}
+async function showDashboards(client) {
+	const active = (await client.getDashboards()).filter((d) => !d.archived);
+	console.log();
+	console.log(pc.bold(`Dashboards (${active.length})`));
+	console.log();
+	if (active.length === 0) {
+		console.log(pc.dim("  No dashboards found."));
+		return;
+	}
+	console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim("NAME")}`);
+	for (const d of active) console.log(`  ${padColumn(String(d.id), 6)}${d.name}`);
+	console.log();
+	console.log(pc.dim("View details: bon metabase explore dashboard <id>"));
+}
+async function showDashboardDetail(client, id) {
+	const [dashboard, allCards] = await Promise.all([client.getDashboard(id), client.getCards()]);
+	const cardActivityMap = /* @__PURE__ */ new Map();
+	for (const c of allCards) cardActivityMap.set(c.id, c);
+	console.log();
+	console.log(pc.bold(dashboard.name));
+	if (dashboard.description) console.log(pc.dim(dashboard.description));
+	console.log();
+	if (dashboard.parameters.length > 0) {
+		console.log(pc.bold("Parameters"));
+		console.log();
+		console.log(`  ${pc.dim(padColumn("NAME", 25))}${pc.dim(padColumn("TYPE", 20))}${pc.dim("SLUG")}`);
+		for (const p of dashboard.parameters) console.log(`  ${padColumn(p.name, 25)}${padColumn(p.type, 20)}${p.slug}`);
+		console.log();
+	}
+	const cardsOnDashboard = dashboard.dashcards.filter((dc) => dc.card?.id != null);
+	if (cardsOnDashboard.length > 0) {
+		const inactiveOnDash = cardsOnDashboard.filter((dc) => {
+			const full = cardActivityMap.get(dc.card.id);
+			return full ? !isCardActive$1(full) : true;
+		});
+		const activeLabel = cardsOnDashboard.length - inactiveOnDash.length;
+		console.log(pc.bold(`Cards (${cardsOnDashboard.length})`) + pc.dim(` — ${activeLabel} active, ${inactiveOnDash.length} inactive`));
+		console.log();
+		console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim(padColumn("NAME", 31))}${pc.dim(padColumn("DISPLAY", 14))}${pc.dim(padColumn("LAST USED", 12))}${pc.dim("POSITION")}`);
+		for (const dc of cardsOnDashboard) {
+			const card = dc.card;
+			const name = (card.name ?? "(untitled)").slice(0, 29);
+			const pos = `(${dc.col},${dc.row}) ${dc.size_x}x${dc.size_y}`;
+			const full = cardActivityMap.get(card.id);
+			const lastUsed = full ? formatLastUsed$1(full) : "?";
+			const active = full ? isCardActive$1(full) : false;
+			const line = `  ${padColumn(String(card.id), 6)}${padColumn(name, 31)}${padColumn(card.display ?? "", 14)}${padColumn(lastUsed, 12)}${pos}`;
+			console.log(active ? line : pc.dim(line));
+		}
+	} else console.log(pc.dim("  No cards on this dashboard."));
+}
+async function showDatabaseDetail(client, id) {
+	const meta = await client.getDatabaseMetadata(id);
+	console.log();
+	console.log(pc.bold(`${meta.name} (${meta.engine})`));
+	console.log();
+	const bySchema = /* @__PURE__ */ new Map();
+	for (const t of meta.tables) {
+		if (t.visibility_type === "hidden" || t.visibility_type === "retired") continue;
+		if (!bySchema.has(t.schema)) bySchema.set(t.schema, []);
+		bySchema.get(t.schema).push(t);
+	}
+	for (const [schema, tables] of Array.from(bySchema.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+		console.log(pc.bold(`  ${schema}`) + pc.dim(` (${tables.length} tables)`));
+		const sorted = [...tables].sort((a, b) => a.name.localeCompare(b.name));
+		for (const t of sorted) {
+			const fieldCount = t.fields.length;
+			const desc = t.description ? pc.dim(` — ${t.description.slice(0, 50)}`) : "";
+			console.log(`    ${padColumn(String(t.id), 8)}${padColumn(t.name, 40)}${fieldCount} fields${desc}`);
+		}
+		console.log();
+	}
+	console.log(pc.dim("View table fields: bon metabase explore table <id>"));
+}
+function classifyFieldType(field) {
+	const bt = field.base_type || "";
+	const st = field.semantic_type || "";
+	if (bt.includes("Date") || bt.includes("Time") || st.includes("Timestamp") || st === "type/DateTime" || st === "type/Date") return "time";
+	if (st === "type/PK") return "pk";
+	if (st === "type/FK") return "fk";
+	if ([
+		"type/Currency",
+		"type/Percentage",
+		"type/Quantity",
+		"type/Score"
+	].includes(st)) return "measure";
+	if ([
+		"type/Category",
+		"type/Source",
+		"type/City",
+		"type/Country",
+		"type/State",
+		"type/Name",
+		"type/Email",
+		"type/URL"
+	].includes(st)) return "dim";
+	if (bt.includes("Integer") || bt.includes("Float") || bt.includes("Decimal") || bt.includes("Number") || bt.includes("BigInteger")) return "numeric";
+	if (bt.includes("Text") || bt.includes("String")) return "text";
+	if (bt.includes("Boolean")) return "bool";
+	return "";
+}
+async function showTableDetail(client, tableId) {
+	const databases = await client.getDatabases();
+	let foundTable = null;
+	let dbName = "";
+	let meta = null;
+	for (const db of databases) {
+		meta = await client.getDatabaseMetadata(db.id);
+		const table = meta.tables.find((t) => t.id === tableId);
+		if (table) {
+			foundTable = table;
+			dbName = db.name;
+			break;
+		}
+	}
+	if (!foundTable || !meta) {
+		console.error(pc.red(`Table ${tableId} not found.`));
+		process.exit(1);
+	}
+	const fieldIdLookup = /* @__PURE__ */ new Map();
+	for (const t of meta.tables) for (const f of t.fields) fieldIdLookup.set(f.id, {
+		table: t.name,
+		field: f.name
+	});
+	console.log();
+	console.log(pc.bold(`${foundTable.name}`) + pc.dim(` (${dbName} / ${foundTable.schema})`));
+	if (foundTable.description) console.log(pc.dim(foundTable.description));
+	console.log();
+	const fields = foundTable.fields.filter((f) => f.visibility_type !== "hidden" && f.visibility_type !== "retired");
+	console.log(`  ${pc.dim(padColumn("FIELD", 30))}${pc.dim(padColumn("TYPE", 22))}${pc.dim(padColumn("SEMANTIC", 18))}${pc.dim(padColumn("CLASS", 8))}${pc.dim(padColumn("DISTINCT", 10))}${pc.dim(padColumn("NULL%", 8))}${pc.dim("FK TARGET")}`);
+	for (const f of fields) {
+		const cls = classifyFieldType(f);
+		const distinct = f.fingerprint?.global?.["distinct-count"];
+		const nilPct = f.fingerprint?.global?.["nil%"];
+		const fkTarget = f.fk_target_field_id ? (() => {
+			const target = fieldIdLookup.get(f.fk_target_field_id);
+			return target ? `${target.table}.${target.field}` : `field:${f.fk_target_field_id}`;
+		})() : "";
+		console.log(`  ${padColumn(f.name, 30)}${padColumn(f.base_type.replace("type/", ""), 22)}${padColumn(f.semantic_type?.replace("type/", "") || "", 18)}${padColumn(cls, 8)}${padColumn(distinct !== void 0 ? String(distinct) : "", 10)}${padColumn(nilPct !== void 0 ? `${Math.round(nilPct * 100)}%` : "", 8)}${fkTarget}`);
+	}
+	console.log();
+	console.log(pc.dim(`${fields.length} fields (${fields.filter((f) => classifyFieldType(f) === "pk" || classifyFieldType(f) === "fk").length} keys, ${fields.filter((f) => classifyFieldType(f) === "time").length} time, ${fields.filter((f) => classifyFieldType(f) === "measure").length} measures)`));
+}
+async function showCollectionDetail(client, id) {
+	const [items, allCards] = await Promise.all([client.getCollectionItems(id), client.getCards()]);
+	const cardMap = /* @__PURE__ */ new Map();
+	for (const c of allCards) cardMap.set(c.id, c);
+	const cardItems = items.filter((i) => i.model === "card" || i.model === "dataset" || i.model === "metric");
+	const dashboardItems = items.filter((i) => i.model === "dashboard");
+	console.log();
+	console.log(pc.bold(`Collection ${id}`));
+	console.log();
+	if (cardItems.length > 0) {
+		const sorted = cardItems.sort((a, b) => {
+			const ca = cardMap.get(a.id);
+			const cb = cardMap.get(b.id);
+			return (cb ? activityScore$1(cb) : 0) - (ca ? activityScore$1(ca) : 0);
+		});
+		const activeCount = sorted.filter((i) => {
+			const c = cardMap.get(i.id);
+			return c ? isCardActive$1(c) : false;
+		}).length;
+		console.log(pc.bold(`Cards (${sorted.length})`) + pc.dim(` — ${activeCount} active, ${sorted.length - activeCount} inactive`));
+		console.log();
+		console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim(padColumn("NAME", 40))}${pc.dim(padColumn("TYPE", 10))}${pc.dim(padColumn("DISPLAY", 14))}${pc.dim(padColumn("LAST USED", 12))}${pc.dim("VIEWS")}`);
+		for (const item of sorted) {
+			const full = cardMap.get(item.id);
+			const lastUsed = full ? formatLastUsed$1(full) : "?";
+			const views = full ? full.view_count || 0 : 0;
+			const active = full ? isCardActive$1(full) : false;
+			const itemType = item.model === "dataset" ? "model" : item.model;
+			const name = item.name.slice(0, 38);
+			const line = `  ${padColumn(String(item.id), 6)}${padColumn(name, 40)}${padColumn(itemType, 10)}${padColumn(item.display || "", 14)}${padColumn(lastUsed, 12)}${views}`;
+			console.log(active ? line : pc.dim(line));
+		}
+		console.log();
+	}
+	if (dashboardItems.length > 0) {
+		console.log(pc.bold(`Dashboards (${dashboardItems.length})`));
+		console.log();
+		console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim("NAME")}`);
+		for (const d of dashboardItems) console.log(`  ${padColumn(String(d.id), 6)}${d.name}`);
+		console.log();
+	}
+	if (cardItems.length === 0 && dashboardItems.length === 0) console.log(pc.dim("  No items in this collection."));
+	console.log(pc.dim("View card SQL: bon metabase explore card <id>"));
+	console.log(pc.dim("View dashboard: bon metabase explore dashboard <id>"));
+}
+const RESOURCES = [
+	"databases",
+	"collections",
+	"cards",
+	"dashboards",
+	"card",
+	"dashboard",
+	"database",
+	"table",
+	"collection"
+];
+async function metabaseExploreCommand(resource, id) {
+	const client = requireConfig();
+	try {
+		if (!resource) {
+			await showOverview(client);
+			return;
+		}
+		if (!RESOURCES.includes(resource)) {
+			console.error(pc.red(`Unknown resource: ${resource}`));
+			console.log(pc.dim(`Valid resources: ${RESOURCES.join(", ")}`));
+			process.exit(1);
+		}
+		switch (resource) {
+			case "databases":
+				await showDatabases(client);
+				break;
+			case "collections":
+				await showCollections(client);
+				break;
+			case "cards":
+				await showCards(client);
+				break;
+			case "dashboards":
+				await showDashboards(client);
+				break;
+			case "card": {
+				if (!id) {
+					console.error(pc.red("Card ID required: bon metabase explore card <id>"));
+					process.exit(1);
+				}
+				const cardId = parseInt(id, 10);
+				if (isNaN(cardId)) {
+					console.error(pc.red(`Invalid card ID: ${id}`));
+					process.exit(1);
+				}
+				await showCardDetail(client, cardId);
+				break;
+			}
+			case "dashboard": {
+				if (!id) {
+					console.error(pc.red("Dashboard ID required: bon metabase explore dashboard <id>"));
+					process.exit(1);
+				}
+				const dashId = parseInt(id, 10);
+				if (isNaN(dashId)) {
+					console.error(pc.red(`Invalid dashboard ID: ${id}`));
+					process.exit(1);
+				}
+				await showDashboardDetail(client, dashId);
+				break;
+			}
+			case "database": {
+				if (!id) {
+					console.error(pc.red("Database ID required: bon metabase explore database <id>"));
+					process.exit(1);
+				}
+				const dbId = parseInt(id, 10);
+				if (isNaN(dbId)) {
+					console.error(pc.red(`Invalid database ID: ${id}`));
+					process.exit(1);
+				}
+				await showDatabaseDetail(client, dbId);
+				break;
+			}
+			case "table": {
+				if (!id) {
+					console.error(pc.red("Table ID required: bon metabase explore table <id>"));
+					process.exit(1);
+				}
+				const tableId = parseInt(id, 10);
+				if (isNaN(tableId)) {
+					console.error(pc.red(`Invalid table ID: ${id}`));
+					process.exit(1);
+				}
+				await showTableDetail(client, tableId);
+				break;
+			}
+			case "collection": {
+				if (!id) {
+					console.error(pc.red("Collection ID required: bon metabase explore collection <id>"));
+					process.exit(1);
+				}
+				const colId = parseInt(id, 10);
+				if (isNaN(colId)) {
+					console.error(pc.red(`Invalid collection ID: ${id}`));
+					process.exit(1);
+				}
+				await showCollectionDetail(client, colId);
+				break;
+			}
+		}
+	} catch (err) {
+		if (err instanceof MetabaseApiError) {
+			if (err.status === 401 || err.status === 403) console.error(pc.red("Authentication failed. Re-run: bon metabase connect"));
+			else if (err.status === 404) console.error(pc.red(`Not found: ${err.endpoint}`));
+			else console.error(pc.red(`Metabase API error (${err.status}): ${err.message}`));
+			process.exit(1);
+		}
+		throw err;
+	}
+}
+
+//#endregion
+//#region src/commands/metabase/analyze.ts
+const OUTPUT_FILE = ".bon/metabase-analysis.md";
+const TOP_CARDS_LIMIT = 50;
+const TOP_DASHBOARDS_LIMIT = 10;
+function classifyField(field) {
+	const bt = field.base_type || "";
+	const st = field.semantic_type || "";
+	if (bt.includes("Date") || bt.includes("Time") || st.includes("Timestamp") || st === "type/DateTime" || st === "type/Date" || st === "type/Time") return "time";
+	if ([
+		"type/Currency",
+		"type/Percentage",
+		"type/Quantity",
+		"type/Score"
+	].includes(st)) return "measure";
+	if (st === "type/PK" || st === "type/FK") return "dimension";
+	if ([
+		"type/Category",
+		"type/Source",
+		"type/City",
+		"type/Country",
+		"type/State",
+		"type/Name",
+		"type/Title",
+		"type/Email",
+		"type/URL",
+		"type/ZipCode"
+	].includes(st)) return "dimension";
+	if (bt.includes("Integer") || bt.includes("Float") || bt.includes("Decimal") || bt.includes("Number") || bt.includes("BigInteger")) {
+		const distinct = field.fingerprint?.global?.["distinct-count"];
+		if (distinct !== void 0 && distinct < 20) return "dimension";
+		return "measure";
+	}
+	if (bt.includes("Text") || bt.includes("String")) return "dimension";
+	if (bt.includes("Boolean")) return "dimension";
+	return "other";
+}
+function extractSQL(card) {
+	const dq = card.dataset_query;
+	if (dq.type === "native" && dq.native?.query) return dq.native.query;
+	if (dq.stages?.[0]?.["lib/type"] === "mbql.stage/native" && typeof dq.stages[0].native === "string") return dq.stages[0].native;
+	return null;
+}
+/**
+* Returns true if the card uses MBQL (query builder) rather than native SQL.
+*/
+function isMbqlCard(card) {
+	const dq = card.dataset_query;
+	if (dq.type === "query") return true;
+	if (dq.stages?.[0]?.["lib/type"] === "mbql.stage/mbql") return true;
+	return false;
+}
+/**
+* Extracts table references from SQL (FROM and JOIN clauses).
+* Returns a map of table name -> reference count.
+* Excludes CTE names so only real tables are counted.
+*/
+function extractTableReferences(sql) {
+	const refs = /* @__PURE__ */ new Map();
+	const cteNames = /* @__PURE__ */ new Set();
+	const cteMatch = sql.match(/\bWITH\b[\s\S]*?(?=\bSELECT\b(?![\s\S]*\bWITH\b))/gi);
+	if (cteMatch) {
+		const cteDefPattern = /\b(\w+)\s+AS\s*\(/gi;
+		for (const block of cteMatch) {
+			let m;
+			while ((m = cteDefPattern.exec(block)) !== null) cteNames.add(m[1].toLowerCase());
+		}
+	}
+	const tableRefPattern = /(?:FROM|JOIN)\s+("?\w+"?\s*\.\s*"?\w+"?|"?\w+"?)(?:\s+(?:AS\s+)?\w+)?/gi;
+	let match;
+	while ((match = tableRefPattern.exec(sql)) !== null) {
+		let tableName = match[1].replace(/"/g, "").replace(/\s/g, "").toLowerCase();
+		const baseName = tableName.includes(".") ? tableName.split(".").pop() : tableName;
+		if (cteNames.has(baseName)) continue;
+		if ([
+			"select",
+			"where",
+			"group",
+			"order",
+			"having",
+			"limit",
+			"union",
+			"values",
+			"set",
+			"update",
+			"insert",
+			"delete",
+			"into",
+			"table",
+			"create",
+			"alter",
+			"drop",
+			"index",
+			"view",
+			"as",
+			"on",
+			"and",
+			"or",
+			"not",
+			"in",
+			"is",
+			"null",
+			"true",
+			"false",
+			"case",
+			"when",
+			"then",
+			"else",
+			"end",
+			"with",
+			"the",
+			"lateral",
+			"generate_series",
+			"unnest"
+		].includes(baseName)) continue;
+		if (!refs.has(tableName)) refs.set(tableName, 0);
+		refs.set(tableName, refs.get(tableName) + 1);
+	}
+	return refs;
+}
+/**
+* Classifies a card's SQL pattern:
+* - analytical: GROUP BY + aggregation (core semantic layer candidates)
+* - lookup: Single-row lookup (WHERE email={{x}}, no GROUP BY) — CRM/operational
+* - display: UNION-based formatting/layout without aggregation
+* - unknown: non-native or unclassifiable
+*/
+function classifyCardPattern(card, sqlOverride) {
+	const sql = sqlOverride ?? extractSQL(card);
+	if (!sql) return "unknown";
+	const upper = sql.toUpperCase();
+	const hasGroupBy = /\bGROUP\s+BY\b/.test(upper);
+	const hasAgg = /\b(COUNT|SUM|AVG|MIN|MAX|PERCENTILE)\s*\(/.test(upper);
+	const hasUnion = /\bUNION\b/.test(upper);
+	const hasTemplateVar = /\{\{[^}]+\}\}/.test(sql);
+	const hasLookupVar = /\{\{(email|primary_mail|user|customer|name|phone|id)\}\}/i.test(sql);
+	if (hasGroupBy && hasAgg) return "analytical";
+	if (hasLookupVar && !hasGroupBy && !hasAgg) return "lookup";
+	if (hasUnion && !hasGroupBy && !hasAgg) return "display";
+	if (hasAgg && !hasGroupBy) return "analytical";
+	if (hasTemplateVar && hasAgg) return "analytical";
+	return "unknown";
+}
+/**
+* Extracts Metabase template variable names ({{var}}) from SQL.
+*/
+function extractTemplateVars(sql) {
+	const vars = /* @__PURE__ */ new Set();
+	const pattern = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+	let m;
+	while ((m = pattern.exec(sql)) !== null) vars.add(m[1].toLowerCase());
+	return vars;
+}
+const INACTIVE_MONTHS = 3;
+function isCardActive(card) {
+	if (!card.last_used_at) return false;
+	const cutoff = /* @__PURE__ */ new Date();
+	cutoff.setMonth(cutoff.getMonth() - INACTIVE_MONTHS);
+	return new Date(card.last_used_at) >= cutoff;
+}
+/**
+* Score that weights view_count by recency.
+* Active cards (used in last 3 months) keep full view_count.
+* Inactive cards are penalized by 90%.
+*/
+function activityScore(card) {
+	const views = card.view_count || 0;
+	return isCardActive(card) ? views : Math.round(views * .1);
+}
+function formatLastUsed(card) {
+	if (!card.last_used_at) return "never";
+	const d = new Date(card.last_used_at);
+	const diffMs = (/* @__PURE__ */ new Date()).getTime() - d.getTime();
+	const diffDays = Math.floor(diffMs / (1e3 * 60 * 60 * 24));
+	if (diffDays === 0) return "today";
+	if (diffDays === 1) return "yesterday";
+	if (diffDays < 30) return `${diffDays}d ago`;
+	if (diffDays < 365) return `${Math.floor(diffDays / 30)}mo ago`;
+	return `${Math.floor(diffDays / 365)}y ago`;
+}
+function getCardType(card) {
+	if (card.type === "model" || card.dataset) return "model";
+	if (card.type === "metric") return "metric";
+	return "question";
+}
+function extractSchemaAccess(graph, groups, dbId) {
+	const groupMap = new Map(groups.map((g) => [String(g.id), g.name]));
+	const schemaAccessMap = /* @__PURE__ */ new Map();
+	for (const [groupId, dbPerms] of Object.entries(graph.groups)) {
+		const groupName = groupMap.get(groupId) || `Group ${groupId}`;
+		const perms = dbPerms[String(dbId)];
+		if (!perms) continue;
+		const createQueries = perms["create-queries"];
+		if (!createQueries) continue;
+		if (typeof createQueries === "string") {
+			if (createQueries !== "no") {
+				if (!schemaAccessMap.has("*")) schemaAccessMap.set("*", []);
+				schemaAccessMap.get("*").push(groupName);
+			}
+			continue;
+		}
+		for (const [schema, perm] of Object.entries(createQueries)) if (perm !== "no") {
+			if (!schemaAccessMap.has(schema)) schemaAccessMap.set(schema, []);
+			schemaAccessMap.get(schema).push(groupName);
+		}
+	}
+	return Array.from(schemaAccessMap.entries()).map(([schema, grps]) => ({
+		schema,
+		groups: grps
+	})).sort((a, b) => a.schema.localeCompare(b.schema));
+}
+/**
+* Returns the set of schemas accessible to non-admin groups for a given database.
+* Returns null if a non-admin group has wildcard access (all schemas are user-facing),
+* or if no explicit schema permissions are found.
+*/
+function getUserFacingSchemas(graph, groups, dbId) {
+	const adminGroupIds = new Set(groups.filter((g) => g.name === "Administrators").map((g) => String(g.id)));
+	const schemas = /* @__PURE__ */ new Set();
+	for (const [groupId, dbPerms] of Object.entries(graph.groups)) {
+		if (adminGroupIds.has(groupId)) continue;
+		const perms = dbPerms[String(dbId)];
+		if (!perms) continue;
+		const createQueries = perms["create-queries"];
+		if (!createQueries) continue;
+		if (typeof createQueries === "string") {
+			if (createQueries !== "no") return null;
+			continue;
+		}
+		for (const [schema, perm] of Object.entries(createQueries)) if (perm !== "no") schemas.add(schema);
+	}
+	return schemas.size > 0 ? schemas : null;
+}
+function flattenCollections(nodes, parentPath = "") {
+	const result = [];
+	for (const node of nodes) {
+		if (node.personal_owner_id !== null) continue;
+		const p = parentPath ? `${parentPath}/${node.name}` : node.name;
+		result.push({
+			id: node.id,
+			path: p
+		});
+		if (node.children.length > 0) result.push(...flattenCollections(node.children, p));
+	}
+	return result;
+}
+const MAX_TREE_DEPTH = 2;
+function renderTree(nodes, indent = 0) {
+	let out = "";
+	for (const node of nodes) {
+		if (node.personal_owner_id !== null) continue;
+		const prefix = "  ".repeat(indent);
+		const icon = node.children.length > 0 ? "+" : "-";
+		out += `${prefix}${icon} ${node.name} (${node.id})\n`;
+		if (node.children.length > 0 && indent < MAX_TREE_DEPTH - 1) out += renderTree(node.children, indent + 1);
+		else if (node.children.length > 0) {
+			const childCount = node.children.filter((c) => c.personal_owner_id === null).length;
+			if (childCount > 0) out += `${prefix}  ... ${childCount} sub-collections\n`;
+		}
+	}
+	return out;
+}
+function aggregateParameters(dashboards) {
+	const paramMap = /* @__PURE__ */ new Map();
+	for (const d of dashboards) for (const p of d.parameters) {
+		const key = `${p.type}:${p.slug}`;
+		if (!paramMap.has(key)) paramMap.set(key, {
+			name: p.name,
+			type: p.type,
+			slug: p.slug,
+			dashboardCount: 0,
+			dashboards: []
+		});
+		const entry = paramMap.get(key);
+		entry.dashboardCount++;
+		entry.dashboards.push(d.name);
+	}
+	return Array.from(paramMap.values()).sort((a, b) => b.dashboardCount - a.dashboardCount);
+}
+function summarizeTable(table) {
+	let dimensions = 0, measures = 0, timeDimensions = 0;
+	for (const f of table.fields) {
+		if (f.visibility_type === "hidden" || f.visibility_type === "retired") continue;
+		const cls = classifyField(f);
+		if (cls === "dimension") dimensions++;
+		else if (cls === "measure") measures++;
+		else if (cls === "time") timeDimensions++;
+	}
+	return {
+		id: table.id,
+		name: table.name,
+		schema: table.schema,
+		description: table.description,
+		fieldCount: table.fields.length,
+		dimensions,
+		measures,
+		timeDimensions,
+		hasDescription: !!table.description
+	};
+}
+function buildReport(data) {
+	const { instanceUrl, user, databases, cards, dashboardList, dashboardDetails, collectionTree, collectionMap, permissionGroups, permissionsGraph, topCardsLimit, convertedSqlMap } = data;
+	/** Get SQL for a card — native extraction first, then converted MBQL fallback. */
+	function getCardSQL(card) {
+		return extractSQL(card) || convertedSqlMap.get(card.id) || null;
+	}
+	const activeCards = cards.filter((c) => !c.archived);
+	const activeDashboards = dashboardList.filter((d) => !d.archived);
+	const models = activeCards.filter((c) => getCardType(c) === "model");
+	const metrics = activeCards.filter((c) => getCardType(c) === "metric");
+	const questions = activeCards.filter((c) => getCardType(c) === "question");
+	const topCards = [...activeCards].sort((a, b) => activityScore(b) - activityScore(a)).slice(0, topCardsLimit);
+	const activeCount = activeCards.filter(isCardActive).length;
+	const inactiveCount = activeCards.length - activeCount;
+	const userFacingSchemasMap = /* @__PURE__ */ new Map();
+	if (permissionGroups && permissionsGraph) for (const db of databases) userFacingSchemasMap.set(db.id, getUserFacingSchemas(permissionsGraph, permissionGroups, db.id));
+	let report = "";
+	report += `# Metabase Analysis Report\n\n`;
+	report += `Generated: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}\n`;
+	report += `Instance: ${instanceUrl}\n`;
+	report += `User: ${user.name} (${user.email})\n\n`;
+	report += `## How to Use This Report\n\n`;
+	report += `This report maps your Metabase instance to inform semantic layer design:\n\n`;
+	report += `1. **Most Referenced Tables** → Create cubes for these tables first\n`;
+	report += `2. **Top Cards by Activity** → Replicate aggregations (GROUP BY + SUM/COUNT/AVG) as cube measures\n`;
+	report += `3. **Common Filter Variables** → Ensure these are dimensions on relevant cubes\n`;
+	report += `4. **Foreign Key Relationships** → Define joins between cubes\n`;
+	report += `5. **Collection Structure** → Map collections to views (one view per business domain)\n`;
+	report += `6. **Table Inventory** → Use field classification (dims/measures/time) to build each cube\n\n`;
+	report += `Drill deeper with:\n`;
+	report += `- \`bon metabase explore table <id>\` — field types and classification\n`;
+	report += `- \`bon metabase explore card <id>\` — SQL and columns\n`;
+	report += `- \`bon metabase explore collection <id>\` — cards in a collection\n`;
+	report += `- \`bon metabase explore database <id>\` — schemas and tables\n\n`;
+	report += `## Summary\n\n`;
+	report += `| Metric | Count |\n|--------|-------|\n`;
+	report += `| Databases | ${databases.length} |\n`;
+	for (const db of databases) {
+		const visibleTables = db.tables.filter((t) => t.visibility_type !== "hidden" && t.visibility_type !== "retired");
+		report += `| Tables (${db.name}) | ${visibleTables.length} |\n`;
+	}
+	report += `| Models | ${models.length} |\n`;
+	report += `| Metrics | ${metrics.length} |\n`;
+	report += `| Questions | ${questions.length} |\n`;
+	report += `| Dashboards | ${activeDashboards.length} |\n`;
+	report += `| Collections | ${collectionMap.size} |\n`;
+	report += `| Active cards (used in last ${INACTIVE_MONTHS}mo) | ${activeCount} |\n`;
+	report += `| Inactive cards | ${inactiveCount} |\n`;
+	report += `\n`;
+	if (permissionGroups && permissionsGraph) {
+		report += `## Schema Access\n\n`;
+		report += `Schemas accessible to non-admin groups are user-facing and should be prioritized for modeling.\n\n`;
+		for (const db of databases) {
+			const access = extractSchemaAccess(permissionsGraph, permissionGroups, db.id);
+			report += `### ${db.name} (${db.engine})\n\n`;
+			report += `| Schema | Accessible To |\n|--------|---------------|\n`;
+			for (const a of access) report += `| ${a.schema} | ${a.groups.join(", ")} |\n`;
+			report += `\n`;
+		}
+		report += `### Permission Groups\n\n`;
+		report += `| Group | Members |\n|-------|---------|\n`;
+		for (const g of permissionGroups) report += `| ${g.name} | ${g.member_count} |\n`;
+		report += `\n`;
+	}
+	report += `## Collection Structure (Business Domains)\n\n`;
+	report += `Collections represent how users organize content by business area.\n`;
+	report += `Map these to views in the semantic layer.\n\n`;
+	report += "```\n";
+	const filtered = collectionTree.filter((n) => n.personal_owner_id === null);
+	report += renderTree(filtered);
+	report += "```\n\n";
+	report += `## Top ${topCards.length} Cards by Activity\n\n`;
+	report += `Ranked by view count, weighted by recency. Cards not used in the last ${INACTIVE_MONTHS} months are penalized 90%.\n`;
+	report += `Use \`bon metabase explore card <id>\` to view SQL and column details for any card.\n\n`;
+	report += `| Rank | ID | Views | Last Used | Active | Pattern | Type | Display | Collection | Name |\n`;
+	report += `|------|----|-------|-----------|--------|---------|------|---------|------------|------|\n`;
+	for (let i = 0; i < topCards.length; i++) {
+		const c = topCards[i];
+		const ct = getCardType(c);
+		const col = c.collection_id ? collectionMap.get(c.collection_id) || "?" : "Root";
+		const active = isCardActive(c) ? "Yes" : "No";
+		const lastUsed = formatLastUsed(c);
+		const pattern = classifyCardPattern(c, getCardSQL(c));
+		report += `| ${i + 1} | ${c.id} | ${c.view_count || 0} | ${lastUsed} | ${active} | ${pattern} | ${ct} | ${c.display} | ${col} | ${c.name} |\n`;
+	}
+	report += `\n`;
+	if (dashboardDetails.length > 0) {
+		const params = aggregateParameters(dashboardDetails);
+		report += `## Dashboard Filter Parameters\n\n`;
+		report += `Parameters used across dashboards. These represent the most important filter dimensions.\n\n`;
+		if (params.length > 0) {
+			report += `| Parameter | Type | Used In (dashboards) | Dashboard Names |\n`;
+			report += `|-----------|------|----------------------|-----------------|\n`;
+			for (const p of params) {
+				const names = p.dashboards.slice(0, 3).join(", ");
+				const more = p.dashboards.length > 3 ? ` +${p.dashboards.length - 3} more` : "";
+				report += `| ${p.name} | ${p.type} | ${p.dashboardCount} | ${names}${more} |\n`;
+			}
+			report += `\n`;
+		} else report += `No parameters found across analyzed dashboards.\n\n`;
+	}
+	const templateVarCounts = /* @__PURE__ */ new Map();
+	for (const c of activeCards) {
+		const sql = getCardSQL(c);
+		if (!sql) continue;
+		const vars = extractTemplateVars(sql);
+		for (const v of vars) templateVarCounts.set(v, (templateVarCounts.get(v) || 0) + 1);
+	}
+	if (templateVarCounts.size > 0) {
+		const sortedVars = Array.from(templateVarCounts.entries()).sort((a, b) => b[1] - a[1]).filter(([, count]) => count >= 3);
+		if (sortedVars.length > 0) {
+			const totalVars = templateVarCounts.size;
+			report += `## Common Filter Variables (from SQL)\n\n`;
+			report += `Template variables (\`{{var}}\`) used in 3+ cards. These represent key filter dimensions.\n`;
+			report += `${totalVars} unique variables found; showing ${sortedVars.length} most common.\n\n`;
+			report += `| Variable | Used In (cards) |\n|----------|-----------------|\n`;
+			for (const [varName, count] of sortedVars) report += `| ${varName} | ${count} |\n`;
+			report += `\n`;
+		}
+	}
+	const globalTableRefs = /* @__PURE__ */ new Map();
+	for (const c of activeCards) {
+		const sql = getCardSQL(c);
+		if (!sql) continue;
+		const refs = extractTableReferences(sql);
+		for (const [table, count] of refs) globalTableRefs.set(table, (globalTableRefs.get(table) || 0) + count);
+	}
+	if (globalTableRefs.size > 0) {
+		const sortedRefs = Array.from(globalTableRefs.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20);
+		report += `## Most Referenced Tables (from SQL)\n\n`;
+		report += `Tables most frequently referenced in FROM/JOIN clauses across all cards.\n\n`;
+		report += `| Table | References |\n|-------|------------|\n`;
+		for (const [table, count] of sortedRefs) report += `| ${table} | ${count} |\n`;
+		report += `\n`;
+	}
+	const fieldIdLookup = /* @__PURE__ */ new Map();
+	for (const db of databases) for (const t of db.tables) for (const f of t.fields) fieldIdLookup.set(f.id, {
+		schema: t.schema,
+		table: t.name,
+		field: f.name
+	});
+	const fkRelationships = [];
+	for (const db of databases) {
+		const userFacingSchemas = userFacingSchemasMap.get(db.id) ?? null;
+		for (const t of db.tables) {
+			if (userFacingSchemas !== null && !userFacingSchemas.has(t.schema)) continue;
+			for (const f of t.fields) {
+				if (!f.fk_target_field_id) continue;
+				const target = fieldIdLookup.get(f.fk_target_field_id);
+				if (!target) continue;
+				if (userFacingSchemas !== null && !userFacingSchemas.has(target.schema)) continue;
+				fkRelationships.push({
+					fromSchema: t.schema,
+					fromTable: t.name,
+					fromField: f.name,
+					toSchema: target.schema,
+					toTable: target.table,
+					toField: target.field
+				});
+			}
+		}
+	}
+	if (fkRelationships.length > 0) {
+		const referencedFKs = fkRelationships.filter((fk) => {
+			const fromKey = `${fk.fromSchema}.${fk.fromTable}`.toLowerCase();
+			const toKey = `${fk.toSchema}.${fk.toTable}`.toLowerCase();
+			return globalTableRefs.has(fromKey) || globalTableRefs.has(toKey);
+		});
+		if (referencedFKs.length > 0) {
+			report += `## Foreign Key Relationships\n\n`;
+			report += `FK relationships involving tables referenced by cards. Use these to define cube joins.\n`;
+			if (referencedFKs.length < fkRelationships.length) report += `${fkRelationships.length - referencedFKs.length} unreferenced FKs omitted.\n`;
+			report += `\n`;
+			report += `| From | Field | To | Field |\n`;
+			report += `|------|-------|----|-------|\n`;
+			for (const fk of referencedFKs) {
+				const from = fk.fromSchema === fk.toSchema ? fk.fromTable : `${fk.fromSchema}.${fk.fromTable}`;
+				const to = fk.fromSchema === fk.toSchema ? fk.toTable : `${fk.toSchema}.${fk.toTable}`;
+				report += `| ${from} | ${fk.fromField} | ${to} | ${fk.toField} |\n`;
+			}
+			report += `\n`;
+		}
+	}
+	report += `## Table Inventory\n\n`;
+	if (permissionGroups && permissionsGraph) {
+		report += `Showing tables from user-facing schemas only (accessible to non-admin groups).\n`;
+		report += `Staging (\`stg_\`) and intermediate (\`int_\`) tables are excluded.\n`;
+	} else {
+		report += `Permissions data unavailable — showing all schemas.\n`;
+		report += `Staging (\`stg_\`) and intermediate (\`int_\`) tables are excluded.\n`;
+	}
+	report += `Use \`bon metabase explore databases\` for full database details.\n\n`;
+	report += `Field classification: **Dims** = categorical/text/PKs/FKs, **Measures** = numeric, **Time** = date/datetime\n\n`;
+	let skippedSchemas = 0;
+	let skippedTables = 0;
+	for (const db of databases) {
+		const userFacingSchemas = userFacingSchemasMap.get(db.id) ?? null;
+		const bySchema = /* @__PURE__ */ new Map();
+		for (const t of db.tables) {
+			if (t.visibility_type === "hidden" || t.visibility_type === "retired") continue;
+			if (!bySchema.has(t.schema)) bySchema.set(t.schema, []);
+			bySchema.get(t.schema).push(t);
+		}
+		for (const [schema, tables] of Array.from(bySchema.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+			if (userFacingSchemas !== null && !userFacingSchemas.has(schema)) {
+				skippedSchemas++;
+				skippedTables += tables.length;
+				continue;
+			}
+			const filteredTables = tables.filter((t) => !t.name.startsWith("stg_") && !t.name.startsWith("int_"));
+			skippedTables += tables.length - filteredTables.length;
+			if (filteredTables.length === 0) continue;
+			const summaries = filteredTables.map((t) => {
+				const s = summarizeTable(t);
+				const refKey1 = `${s.schema}.${s.name}`.toLowerCase();
+				const refKey2 = s.name.toLowerCase();
+				const refCount = globalTableRefs.get(refKey1) || globalTableRefs.get(refKey2) || 0;
+				return {
+					...s,
+					refCount
+				};
+			}).sort((a, b) => b.refCount - a.refCount || a.name.localeCompare(b.name));
+			if (!summaries.some((s) => s.refCount > 0)) {
+				skippedSchemas++;
+				skippedTables += filteredTables.length;
+				continue;
+			}
+			const referenced = summaries.filter((s) => s.refCount > 0);
+			const unreferenced = summaries.length - referenced.length;
+			report += `### ${db.name} / ${schema} (${referenced.length} referenced`;
+			if (unreferenced > 0) report += `, ${unreferenced} unreferenced`;
+			report += `)\n\n`;
+			report += `| Table | Fields | Dims | Measures | Time | Refs |\n`;
+			report += `|-------|--------|------|----------|------|------|\n`;
+			for (const s of referenced) report += `| ${s.name} | ${s.fieldCount} | ${s.dimensions} | ${s.measures} | ${s.timeDimensions} | ${s.refCount} |\n`;
+			if (unreferenced > 0) skippedTables += unreferenced;
+			report += `\n`;
+		}
+	}
+	if (skippedSchemas > 0 || skippedTables > 0) report += `*${skippedSchemas} admin-only schemas and ${skippedTables} staging/intermediate tables omitted.*\n\n`;
+	report += `## Cards by Domain\n\n`;
+	report += `Card counts and top questions per collection (by view count).\n\n`;
+	const cardsByCollection = /* @__PURE__ */ new Map();
+	for (const c of activeCards) {
+		const col = c.collection_id ? collectionMap.get(c.collection_id) || "Uncategorized" : "Root";
+		if (!cardsByCollection.has(col)) cardsByCollection.set(col, []);
+		cardsByCollection.get(col).push(c);
+	}
+	const sortedCollections = Array.from(cardsByCollection.entries()).map(([col, colCards]) => ({
+		col,
+		colCards,
+		activeCount: colCards.filter(isCardActive).length
+	})).filter((c) => c.activeCount > 0).sort((a, b) => b.activeCount - a.activeCount);
+	for (const { col, colCards, activeCount } of sortedCollections) {
+		const topNames = [...colCards].sort((a, b) => activityScore(b) - activityScore(a)).slice(0, 3).map((c) => c.name).join(", ");
+		report += `- **${col}** (${colCards.length} cards, ${activeCount} active): ${topNames}\n`;
+	}
+	const inactiveCollections = cardsByCollection.size - sortedCollections.length;
+	if (inactiveCollections > 0) report += `\n*${inactiveCollections} collections with no active cards omitted.*\n`;
+	report += `\n`;
+	return report;
+}
+async function metabaseAnalyzeCommand(options) {
+	const config = loadMetabaseConfig();
+	if (!config) {
+		console.error(pc.red("Metabase is not configured."));
+		console.log(pc.dim("Run: bon metabase connect"));
+		process.exit(1);
+	}
+	const client = createMetabaseClient(config);
+	const outputPath = options.output || OUTPUT_FILE;
+	const topCardsLimit = options.topCards ? parseInt(options.topCards, 10) : TOP_CARDS_LIMIT;
+	console.log();
+	console.log(pc.dim("Fetching data from Metabase..."));
+	const [user, cards, databases, collectionTree, dashboardList] = await Promise.all([
+		client.getCurrentUser(),
+		client.getCards(),
+		client.getDatabases(),
+		client.getCollectionTree(),
+		client.getDashboards()
+	]);
+	console.log(pc.dim(`  ${cards.length} cards, ${databases.length} databases, ${dashboardList.filter((d) => !d.archived).length} dashboards`));
+	let permissionGroups = null;
+	let permissionsGraph = null;
+	try {
+		[permissionGroups, permissionsGraph] = await Promise.all([client.getPermissionGroups(), client.getPermissionsGraph()]);
+		console.log(pc.dim(`  ${permissionGroups.length} permission groups`));
+	} catch (err) {
+		if (err instanceof MetabaseApiError && (err.status === 401 || err.status === 403)) console.log(pc.dim("  Permissions: skipped (requires admin API key)"));
+		else throw err;
+	}
+	console.log(pc.dim("Fetching database metadata..."));
+	const dbMetadata = [];
+	for (const db of databases) {
+		const meta = await client.getDatabaseMetadata(db.id);
+		const visibleTables = meta.tables.filter((t) => t.visibility_type !== "hidden" && t.visibility_type !== "retired");
+		console.log(pc.dim(`  ${db.name}: ${visibleTables.length} tables`));
+		dbMetadata.push(meta);
+	}
+	console.log(pc.dim("Fetching top dashboard details..."));
+	const activeDashboards = dashboardList.filter((d) => !d.archived);
+	let popularDashboardIds = /* @__PURE__ */ new Set();
+	try {
+		const popular = await client.getPopularItems();
+		for (const item of popular) if (item.model === "dashboard") popularDashboardIds.add(item.model_id);
+	} catch {}
+	const dashboardsToFetch = [...activeDashboards].sort((a, b) => {
+		const aPopular = popularDashboardIds.has(a.id) ? 1 : 0;
+		return (popularDashboardIds.has(b.id) ? 1 : 0) - aPopular;
+	}).slice(0, TOP_DASHBOARDS_LIMIT);
+	const dashboardDetails = [];
+	for (const d of dashboardsToFetch) try {
+		const detail = await client.getDashboard(d.id);
+		dashboardDetails.push(detail);
+	} catch {}
+	console.log(pc.dim(`  ${dashboardDetails.length} dashboards analyzed`));
+	const MBQL_CONVERT_LIMIT = 100;
+	const activeCards = cards.filter((c) => !c.archived);
+	const mbqlCards = activeCards.filter(isMbqlCard).sort((a, b) => activityScore(b) - activityScore(a)).slice(0, MBQL_CONVERT_LIMIT);
+	const convertedSqlMap = /* @__PURE__ */ new Map();
+	if (mbqlCards.length > 0) {
+		const totalMbql = activeCards.filter(isMbqlCard).length;
+		console.log(pc.dim(`Converting top ${mbqlCards.length} query-builder cards to SQL (${totalMbql} total, capped at ${MBQL_CONVERT_LIMIT})...`));
+		const BATCH_SIZE = 10;
+		for (let i = 0; i < mbqlCards.length; i += BATCH_SIZE) {
+			const batch = mbqlCards.slice(i, i + BATCH_SIZE);
+			const results = await Promise.allSettled(batch.map(async (c) => {
+				const sql = await client.convertToNativeSQL(c.dataset_query);
+				return {
+					id: c.id,
+					sql
+				};
+			}));
+			for (const r of results) if (r.status === "fulfilled") convertedSqlMap.set(r.value.id, r.value.sql);
+		}
+		console.log(pc.dim(`  ${convertedSqlMap.size}/${mbqlCards.length} converted successfully`));
+	}
+	const flatCollections = flattenCollections(collectionTree.filter((n) => n.personal_owner_id === null));
+	const collectionMap = new Map(flatCollections.map((c) => [c.id, c.path]));
+	console.log(pc.dim("Building report..."));
+	const report = buildReport({
+		instanceUrl: config.url,
+		user: {
+			name: `${user.first_name} ${user.last_name}`.trim(),
+			email: user.email,
+			admin: user.is_superuser
+		},
+		databases: dbMetadata,
+		cards,
+		dashboardList,
+		dashboardDetails,
+		collectionTree,
+		collectionMap,
+		permissionGroups,
+		permissionsGraph,
+		topCardsLimit,
+		convertedSqlMap
+	});
+	ensureBonDir();
+	const fullPath = path.resolve(outputPath);
+	fs.writeFileSync(fullPath, report, "utf-8");
+	const allActive = cards.filter((c) => !c.archived);
+	const recentlyUsed = allActive.filter(isCardActive);
+	const topCards = allActive.sort((a, b) => activityScore(b) - activityScore(a)).slice(0, 5);
+	console.log();
+	console.log(pc.green(`✓ Analysis written to ${outputPath}`));
+	console.log();
+	console.log(pc.bold("Key findings:"));
+	console.log();
+	console.log(`  ${databases.length} database(s), ${dbMetadata.reduce((sum, db) => sum + db.tables.filter((t) => t.visibility_type !== "hidden" && t.visibility_type !== "retired").length, 0)} tables`);
+	console.log(`  ${allActive.length} cards (${recentlyUsed.length} active in last ${INACTIVE_MONTHS}mo, ${allActive.length - recentlyUsed.length} inactive)`);
+	console.log(`  ${activeDashboards.length} dashboards across ${collectionMap.size} collections`);
+	if (permissionGroups) {
+		const nonAdminGroups = permissionGroups.filter((g) => g.name !== "Administrators");
+		if (permissionsGraph) for (const db of databases) {
+			const userSchemas = extractSchemaAccess(permissionsGraph, nonAdminGroups, db.id).filter((a) => a.schema !== "*");
+			if (userSchemas.length > 0) console.log(`  User-facing schemas: ${userSchemas.map((s) => s.schema).join(", ")}`);
+		}
+	}
+	console.log();
+	console.log(pc.bold("Top cards (by activity):"));
+	for (const c of topCards) {
+		const lastUsed = formatLastUsed(c);
+		const flag = isCardActive(c) ? "" : pc.dim(" (inactive)");
+		console.log(`  ${String(c.view_count || 0).padStart(6)} views  ${lastUsed.padEnd(12)} ${c.name}${flag}`);
+	}
+	console.log();
+	console.log(pc.dim(`Full report: ${outputPath}`));
+}
+
 //#endregion
 //#region src/bin/bon.ts
 const { version } = createRequire(import.meta.url)("../../package.json");
@@ -2546,6 +3942,10 @@ program.command("annotate").description("Annotate deployment changes with reason
 program.command("mcp").description("MCP connection info and setup instructions").action(mcpCommand).command("test").description("Test MCP server connectivity").action(mcpTestCommand);
 program.command("query").description("Execute a query against the deployed semantic layer").argument("<query>", "JSON query or SQL (with --sql flag)").option("--sql", "Use SQL API instead of JSON format").option("--limit <limit>", "Max rows to return").option("--format <format>", "Output format: toon or json", "toon").action(cubeQueryCommand);
 program.command("docs").description("Browse documentation for building cubes and views").argument("[topic]", "Topic to display (e.g., cubes, cubes.measures)").option("-r, --recursive", "Show topic and all child topics").option("-s, --search <query>", "Search topics for a keyword").option("-f, --format <format>", "Output format: markdown or json", "markdown").action(docsCommand).command("schema").description("Show JSON schema for a type (cube, view, measure, etc.)").argument("<type>", "Schema type to display").action(docsSchemaCommand);
+const metabase = program.command("metabase").description("Connect to and explore Metabase content");
+metabase.command("connect").description("Configure Metabase API connection").option("--url <url>", "Metabase instance URL").option("--api-key <key>", "Metabase API key").option("--force", "Overwrite existing configuration").action(metabaseConnectCommand);
+metabase.command("explore").description("Browse Metabase databases, collections, cards, and dashboards").argument("[resource]", "databases, collections, cards, dashboards, card, dashboard, database, table, collection").argument("[id]", "Resource ID (e.g. card <id>, dashboard <id>, database <id>, table <id>, collection <id>)").action(metabaseExploreCommand);
+metabase.command("analyze").description("Analyze Metabase instance and generate a structured report for semantic layer planning").option("--output <path>", "Output file path", ".bon/metabase-analysis.md").option("--top-cards <n>", "Number of top cards to include in report", "50").action(metabaseAnalyzeCommand);
 program.parse();
 
 //#endregion