@bonnard/cli 0.1.13 → 0.2.0

package/dist/bin/bon.mjs

@@ -2279,7 +2279,7 @@ async function validateCommand(options = {}) {
 		console.log(pc.red("No bon.yaml found. Are you in a Bonnard project?"));
 		process.exit(1);
 	}
-	const { validate } = await import("./validate-DiN3DaTl.mjs");
+	const { validate } = await import("./validate-C31hmPk8.mjs");
 	const result = await validate(cwd);
 	if (result.cubes.length === 0 && result.views.length === 0 && result.valid) {
 		console.log(pc.yellow(`No cube or view files found in ${BONNARD_DIR}/cubes/ or ${BONNARD_DIR}/views/.`));
@@ -2307,6 +2307,13 @@ async function validateCommand(options = {}) {
 		}
 		for (const [parent, items] of byParent) console.log(pc.dim(`  ${parent}: ${items.join(", ")}`));
 	}
+	if (result.cubesMissingDataSource.length > 0) {
+		console.log();
+		console.log(pc.yellow(`⚠ ${result.cubesMissingDataSource.length} cube(s) missing data_source`));
+		console.log(pc.dim("  Without an explicit data_source, cubes use the default warehouse."));
+		console.log(pc.dim("  This can cause issues when multiple warehouses are configured."));
+		console.log(pc.dim(`  ${result.cubesMissingDataSource.join(", ")}`));
+	}
 	if (options.testConnection) {
 		console.log();
 		await testReferencedConnections(cwd);
@@ -2383,6 +2390,9 @@ function collectFiles(dir, rootDir) {
 	walk(dir);
 	return files;
 }
+function capitalize$1(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
 async function deployCommand(options = {}) {
 	const cwd = process.cwd();
 	const paths = getProjectPaths(cwd);
@@ -2391,7 +2401,7 @@ async function deployCommand(options = {}) {
 		process.exit(1);
 	}
 	console.log(pc.dim("Validating cubes and views..."));
-	const { validate } = await import("./validate-DiN3DaTl.mjs");
+	const { validate } = await import("./validate-C31hmPk8.mjs");
 	const result = await validate(cwd);
 	if (!result.valid) {
 		console.log(pc.red("Validation failed:\n"));
@@ -2412,10 +2422,40 @@ async function deployCommand(options = {}) {
 	console.log(pc.dim(`Deploying ${fileCount} file(s)...`));
 	console.log();
 	try {
-		const response = await post("/api/deploy", { files });
+		const response = await post("/api/deploy", {
+			files,
+			...options.message && { message: options.message }
+		});
 		console.log(pc.green("Deploy successful!"));
 		console.log(`Deployment ID: ${pc.cyan(response.deployment.id)}`);
-		console.log(`API: ${pc.cyan(response.deployment.cubeApiUrl)}`);
+		console.log();
+		if (response.deployment.isFirstDeploy) console.log(pc.dim(`  First deployment — ${response.deployment.fileCount} files uploaded`));
+		else if (response.deployment.changes && response.deployment.changes.details.length > 0) {
+			const { changes } = response.deployment;
+			console.log(pc.dim("Changes from previous deploy:"));
+			console.log();
+			for (const c of changes.details) {
+				const prefix = c.changeType === "added" ? pc.green("+") : c.changeType === "removed" ? pc.red("-") : pc.yellow("~");
+				const label = `${capitalize$1(c.changeType)} ${c.objectType}: ${c.objectName}`;
+				const breakingTag = c.breaking ? pc.red(" BREAKING") : "";
+				const summaryTag = c.summary ? pc.dim(` — ${c.summary}`) : "";
+				console.log(`  ${prefix} ${label}${summaryTag}${breakingTag}`);
+			}
+			if (changes.breaking > 0) {
+				console.log();
+				console.log(pc.red(`${changes.breaking} breaking change${changes.breaking > 1 ? "s" : ""} detected`));
+			}
+			console.log();
+			console.log(pc.bold("Annotate these changes with reasoning:"));
+			console.log();
+			const annotationTemplate = { annotations: changes.details.map((c) => ({
+				objectName: c.objectName,
+				annotation: `Why ${c.objectName} was ${c.changeType}`
+			})) };
+			console.log(`  bon annotate ${response.deployment.id} --data '${JSON.stringify(annotationTemplate)}'`);
+			console.log();
+			console.log(pc.dim("Replace each annotation value with the reasoning behind the change."));
+		} else console.log(pc.dim("  No changes detected from previous deployment."));
 		console.log();
 		console.log(pc.bold("Connect AI agents via MCP:"));
 		console.log(`  MCP URL: ${pc.cyan("https://mcp.bonnard.dev/mcp")}`);
@@ -2532,6 +2572,207 @@ async function testAndSyncDatasources(cwd, options = {}) {
 	return false;
 }
 
+//#endregion
+//#region src/commands/deployments.ts
+function relativeTime(dateStr) {
+	const now = Date.now();
+	const then = new Date(dateStr).getTime();
+	const seconds = Math.floor((now - then) / 1e3);
+	if (seconds < 60) return "just now";
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes} min ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours} hour${hours > 1 ? "s" : ""} ago`;
+	const days = Math.floor(hours / 24);
+	return `${days} day${days > 1 ? "s" : ""} ago`;
+}
+function truncate(str, max) {
+	if (str.length <= max) return str;
+	return str.slice(0, max - 1) + "…";
+}
+function statusColor(status) {
+	switch (status) {
+		case "success": return pc.green(status);
+		case "failed": return pc.red(status);
+		case "processing": return pc.yellow(status);
+		default: return pc.dim(status);
+	}
+}
+async function deploymentsCommand(options = {}) {
+	const limit = options.all ? 100 : 10;
+	let response;
+	try {
+		response = await get(`/api/deploy/history?limit=${limit}`);
+	} catch (err) {
+		console.log(pc.red(`Failed to fetch deployments: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+	const { deployments } = response;
+	if (options.format === "json") {
+		console.log(JSON.stringify(deployments, null, 2));
+		return;
+	}
+	console.log();
+	console.log(pc.bold("Deployments for Bonnard"));
+	console.log();
+	if (deployments.length === 0) {
+		console.log(pc.dim("  No deployments found."));
+		console.log();
+		return;
+	}
+	const colId = 10;
+	const colStatus = 12;
+	const colFiles = 7;
+	const colMessage = 32;
+	console.log(pc.dim("  " + "ID".padEnd(colId) + "Status".padEnd(colStatus) + "Files".padEnd(colFiles) + "Message".padEnd(colMessage) + "Deployed"));
+	for (const d of deployments) {
+		const id = d.id.slice(0, 8);
+		const status = statusColor(d.status);
+		const statusPad = " ".repeat(Math.max(0, colStatus - d.status.length));
+		const files = String(d.fileCount);
+		const message = d.message ? truncate(d.message, 30) : "—";
+		const time = relativeTime(d.createdAt);
+		console.log("  " + id.padEnd(colId) + status + statusPad + files.padEnd(colFiles) + message.padEnd(colMessage) + pc.dim(time));
+	}
+	console.log();
+	console.log(pc.dim(`Showing ${deployments.length} deployment${deployments.length !== 1 ? "s" : ""}.`));
+	console.log();
+}
+
+//#endregion
+//#region src/commands/annotate.ts
+function readStdin() {
+	return new Promise((resolve) => {
+		if (process.stdin.isTTY) {
+			resolve(null);
+			return;
+		}
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => data += chunk);
+		process.stdin.on("end", () => resolve(data.trim() || null));
+		setTimeout(() => resolve(data.trim() || null), 100);
+	});
+}
+function parseAnnotations(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error("Invalid JSON. Expected: {\"annotations\": [{\"objectName\": \"...\", \"annotation\": \"...\"}]}");
+	}
+	const obj = parsed;
+	if (!obj.annotations || !Array.isArray(obj.annotations) || obj.annotations.length === 0) throw new Error("JSON must contain a non-empty \"annotations\" array");
+	for (const entry of obj.annotations) {
+		const e = entry;
+		if (!e.objectName || typeof e.objectName !== "string") throw new Error("Each annotation must have a string \"objectName\"");
+		if (!e.annotation || typeof e.annotation !== "string") throw new Error(`Missing \"annotation\" text for \"${e.objectName}\"`);
+		if (e.annotation.length > 1e3) throw new Error(`Annotation for \"${e.objectName}\" exceeds 1000 chars`);
+	}
+	return { annotations: obj.annotations };
+}
+async function annotateCommand(id, options = {}) {
+	const raw = options.data || await readStdin();
+	if (!raw) {
+		try {
+			const { changes } = await get(`/api/deploy/changes/${id}`);
+			if (changes.length === 0) {
+				console.log(pc.dim("No changes recorded for this deployment."));
+				return;
+			}
+			console.log();
+			console.log(pc.bold(`Changes in deployment ${id.slice(0, 8)}`));
+			console.log();
+			for (const c of changes) {
+				const prefix = c.changeType === "added" ? pc.green("+") : c.changeType === "removed" ? pc.red("-") : pc.yellow("~");
+				const label = `${c.changeType} ${c.objectType}: ${c.objectName}`;
+				const breakingTag = c.breaking ? pc.red(" BREAKING") : "";
+				console.log(`  ${prefix} ${label}${breakingTag}`);
+				if (c.annotation) console.log(pc.dim(`      "${c.annotation}"`));
+			}
+			console.log();
+			console.log(pc.dim("To annotate, provide JSON via --data or stdin:"));
+			console.log(pc.dim(`  bon annotate ${id.slice(0, 8)} --data '{"annotations":[{"objectName":"...","annotation":"..."}]}'`));
+			console.log();
+		} catch (err) {
+			console.log(pc.red(`Failed to fetch changes: ${err instanceof Error ? err.message : err}`));
+			process.exit(1);
+		}
+		return;
+	}
+	let payload;
+	try {
+		payload = parseAnnotations(raw);
+	} catch (err) {
+		console.log(pc.red(err instanceof Error ? err.message : String(err)));
+		process.exit(1);
+	}
+	try {
+		const response = await post(`/api/deploy/annotate/${id}`, payload);
+		console.log(pc.green(`Annotated ${response.updated}/${response.total} changes.`));
+	} catch (err) {
+		console.log(pc.red(`Failed to submit annotations: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/diff.ts
+async function diffCommand(id, options = {}) {
+	let response;
+	try {
+		response = await get(`/api/deploy/changes/${id}`);
+	} catch (err) {
+		console.log(pc.red(`Failed to fetch changes: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+	let { changes } = response;
+	if (options.breaking) changes = changes.filter((c) => c.breaking);
+	if (options.format === "json") {
+		console.log(JSON.stringify(changes, null, 2));
+		return;
+	}
+	console.log();
+	console.log(pc.bold(`Changes in deployment ${id.slice(0, 8)}`));
+	console.log();
+	if (changes.length === 0) {
+		console.log(pc.dim("  No changes recorded."));
+		console.log();
+		return;
+	}
+	for (const c of changes) {
+		const prefix = c.changeType === "added" ? pc.green("+") : c.changeType === "removed" ? pc.red("-") : pc.yellow("~");
+		const label = `${capitalize(c.changeType)} ${c.objectType}: ${c.objectName}`;
+		const breakingTag = c.breaking ? pc.red(" BREAKING") : "";
+		console.log(`  ${prefix} ${label}${breakingTag}`);
+		const details = [];
+		if (c.summary) details.push(c.summary);
+		if (details.length > 0) console.log(pc.dim(`      ${details.join(" | ")}`));
+		if (c.changeType === "modified" && c.previousDefinition && c.newDefinition) for (const key of Object.keys(c.newDefinition)) {
+			const oldVal = c.previousDefinition[key];
+			const newVal = c.newDefinition[key];
+			if (oldVal !== newVal && oldVal !== void 0 && newVal !== void 0) console.log(pc.dim(`      ${key}: ${JSON.stringify(oldVal)} -> ${JSON.stringify(newVal)}`));
+		}
+		if (c.annotation) console.log(`      ${pc.cyan("\"" + c.annotation + "\"")}`);
+		console.log();
+	}
+	const added = changes.filter((c) => c.changeType === "added").length;
+	const modified = changes.filter((c) => c.changeType === "modified").length;
+	const removed = changes.filter((c) => c.changeType === "removed").length;
+	const breaking = changes.filter((c) => c.breaking).length;
+	const parts = [
+		`${added} added`,
+		`${modified} modified`,
+		`${removed} removed`
+	];
+	if (breaking > 0) parts.push(pc.red(`${breaking} breaking`));
+	console.log(pc.dim(`Summary: ${parts.join(", ")}`));
+	console.log();
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
 //#endregion
 //#region src/commands/mcp.ts
 const MCP_URL = "https://mcp.bonnard.dev/mcp";
@@ -2857,7 +3098,10 @@ datasource.command("remove").description("Remove a data source from .bon/datasou
 datasource.command("push").description("Push a local data source to Bonnard server (requires login)").argument("<name>", "Data source name from .bon/datasources.yaml").option("--force", "Overwrite if already exists on remote").action(datasourcePushCommand);
 program.command("preview").description("Preview data from a local warehouse using raw SQL (for development/exploration)").argument("<datasource>", "Data source name from .bon/datasources.yaml").argument("<sql>", "SQL query to execute").option("--schema <schema>", "Override schema").option("--database <database>", "Override database").option("--limit <limit>", "Max rows to return", "1000").option("--format <format>", "Output format: toon or json", "toon").action(previewCommand);
 program.command("validate").description("Validate YAML syntax in bonnard/cubes/ and bonnard/views/").option("--test-connection", "Also test datasource connections (warns on failure, doesn't block)").action(validateCommand);
-program.command("deploy").description("Deploy cubes and views to Bonnard. Requires login, validates, tests connections (fails on error)").option("--ci", "Non-interactive mode (fail if missing datasources)").option("--push-datasources", "Auto-push missing datasources without prompting").action(deployCommand);
+program.command("deploy").description("Deploy cubes and views to Bonnard. Requires login, validates, tests connections (fails on error)").option("--ci", "Non-interactive mode (fail if missing datasources)").option("--push-datasources", "Auto-push missing datasources without prompting").requiredOption("-m, --message <text>", "Deploy message describing your changes").action(deployCommand);
+program.command("deployments").description("List deployment history").option("--all", "Show all deployments (default: last 10)").option("--format <format>", "Output format: table or json", "table").action(deploymentsCommand);
+program.command("diff").description("Show changes in a deployment").argument("<id>", "Deployment ID").option("--format <format>", "Output format: table or json", "table").option("--breaking", "Show only breaking changes").action(diffCommand);
+program.command("annotate").description("Annotate deployment changes with reasoning").argument("<id>", "Deployment ID").option("--data <json>", "Annotations JSON").action(annotateCommand);
 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);

package/dist/bin/{validate-DiN3DaTl.mjs → validate-C31hmPk8.mjs}

@@ -59,6 +59,15 @@ function checkMissingDescriptions(files) {
 	} catch {}
 	return missing;
 }
+function checkMissingDataSource(files) {
+	const missing = [];
+	for (const file of files) try {
+		const parsed = YAML.parse(file.content);
+		if (!parsed) continue;
+		for (const cube of parsed.cubes || []) if (cube.name && !cube.data_source) missing.push(cube.name);
+	} catch {}
+	return missing;
+}
 function createModelRepository(projectPath) {
 	const paths = getProjectPaths(projectPath);
 	const cubesDir = paths.cubes;
@@ -79,7 +88,8 @@ async function validate(projectPath) {
 		errors: [],
 		cubes: [],
 		views: [],
-		missingDescriptions: []
+		missingDescriptions: [],
+		cubesMissingDataSource: []
 	};
 	try {
 		const { cubeEvaluator } = await compile(repo, {});
@@ -92,7 +102,8 @@ async function validate(projectPath) {
 			errors: [],
 			cubes,
 			views,
-			missingDescriptions: checkMissingDescriptions(files)
+			missingDescriptions: checkMissingDescriptions(files),
+			cubesMissingDataSource: checkMissingDataSource(files)
 		};
 	} catch (err) {
 		const raw = err.messages ?? err.message ?? String(err);
@@ -101,7 +112,8 @@ async function validate(projectPath) {
 			errors: Array.isArray(raw) ? raw : [raw],
 			cubes: [],
 			views: [],
-			missingDescriptions: []
+			missingDescriptions: [],
+			cubesMissingDataSource: []
 		};
 	}
 }

package/dist/docs/_index.md

@@ -1,6 +1,6 @@
 # Bonnard Documentation
 
-> Build semantic layers with cubes and views.
+> Learn how to build, deploy, and query a semantic layer with Bonnard. Define metrics once in YAML cubes and views, then query from any BI tool or AI agent.
 
 ## Cubes
 

package/dist/docs/topics/cubes.data-source.md

@@ -1,6 +1,6 @@
-# cubes.data-source
+# Data Source
 
-> Connect cubes to specific data warehouses.
+> The data_source property connects cubes to specific data warehouse connections. Use it when your semantic layer spans multiple databases like PostgreSQL, Snowflake, or BigQuery.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.format.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.format
+# Dimension Format
 
-> Control how dimension values are displayed.
+> The format property controls how dimension values are displayed to consumers. Apply date formatting, number formatting, or custom patterns to make dimension output human-readable.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.md

@@ -1,6 +1,6 @@
-# cubes.dimensions
+# Dimensions
 
-> Define attributes for grouping and filtering data.
+> Dimensions define the attributes used for grouping and filtering data in your semantic layer. They map to table columns and provide the axes for slicing measures in queries.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.primary-key.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.primary-key
+# Primary Key
 
-> Mark the unique identifier dimension for a cube.
+> The primary_key property marks a dimension as the unique identifier for a cube. Primary keys are required for count_distinct measures and for establishing correct join relationships.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.sub-query.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.sub-query
+# Sub-Query Dimensions
 
-> Bring measures from other cubes into a dimension.
+> Sub-query dimensions let you bring a measure from another cube into a dimension using a correlated subquery. Useful for denormalizing aggregated values like "lifetime revenue per user."
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.time.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.time
+# Time Dimensions
 
-> Enable time-based analysis with time dimensions.
+> Time dimensions enable date and time-based analysis in your semantic layer. They support automatic granularity (day, week, month, year) and power time-series queries and date filters.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.types.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.types
+# Dimension Types
 
-> The 6 dimension types for categorizing and filtering data.
+> Reference for all 6 dimension types in Bonnard: string, number, boolean, time, geo, and json. Each type determines how the dimension is stored, indexed, and queried.
 
 ## Overview
 

package/dist/docs/topics/cubes.extends.md

@@ -1,6 +1,6 @@
-# cubes.extends
+# Extends
 
-> Reuse members from other cubes to reduce duplication.
+> Extends lets you inherit measures, dimensions, and joins from other cubes to reduce duplication. Build base cubes with shared logic and extend them for specific use cases.
 
 ## Overview
 

package/dist/docs/topics/cubes.hierarchies.md

@@ -1,6 +1,6 @@
-# cubes.hierarchies
+# Hierarchies
 
-> Define drill-down paths for dimensional analysis.
+> Hierarchies define drill-down paths for dimensional analysis in your semantic layer. Set up parent-child relationships between dimensions so consumers can explore data at different levels.
 
 ## Overview
 

package/dist/docs/topics/cubes.joins.md

@@ -1,6 +1,6 @@
-# cubes.joins
+# Joins
 
-> Connect cubes together to enable cross-cube analysis.
+> Joins connect cubes together so you can query measures and dimensions across multiple tables. Define one-to-many, many-to-one, and one-to-one relationships between cubes.
 
 ## Overview
 

package/dist/docs/topics/cubes.md

@@ -1,6 +1,6 @@
-# cubes
+# Cubes
 
-> Define cubes that map to your database tables.
+> Cubes are the core building blocks of a Bonnard semantic layer. Each cube maps to a database table and defines the measures, dimensions, and joins available for querying.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.calculated.md

@@ -1,6 +1,6 @@
-# cubes.measures.calculated
+# Calculated Measures
 
-> Build complex metrics from other measures.
+> Calculated measures let you build complex metrics from other measures in the same cube. Combine existing aggregations to create ratios, percentages, and derived metrics without raw SQL.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.drill-members.md

@@ -1,6 +1,6 @@
-# cubes.measures.drill-members
+# Drill Members
 
-> Define which dimensions to show when drilling into a measure.
+> Drill members define which dimensions are shown when a user drills into a measure. Configure drill-down paths so consumers can explore aggregated numbers down to individual records.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.filters.md

@@ -1,6 +1,6 @@
-# cubes.measures.filters
+# Measure Filters
 
-> Apply permanent filters to measures for conditional aggregations.
+> Measure filters apply permanent WHERE conditions to measures for conditional aggregations. Create filtered metrics like "revenue from paid plans" or "active users in the last 30 days."
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.format.md

@@ -1,6 +1,6 @@
-# cubes.measures.format
+# Measure Format
 
-> Specify how measure values should be displayed.
+> The format property controls how measure values are displayed to consumers. Specify currency symbols, decimal places, percentage formatting, and custom number patterns.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.md

@@ -1,6 +1,6 @@
-# cubes.measures
+# Measures
 
-> Define metrics and aggregations for analytical queries.
+> Measures define the metrics and aggregations in your semantic layer. Use them to calculate sums, counts, averages, and custom expressions that stay consistent across every consumer.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.rolling.md

@@ -1,6 +1,6 @@
-# cubes.measures.rolling
+# Rolling Measures
 
-> Calculate rolling window aggregations (7-day average, 30-day sum, etc).
+> Rolling measures calculate aggregations over sliding time windows like 7-day averages, 30-day sums, and month-to-date totals. Define the window type, trailing period, and offset.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.types.md

@@ -1,6 +1,6 @@
-# cubes.measures.types
+# Measure Types
 
-> The 12 measure types available for aggregating data.
+> Reference for all 12 measure types available in Bonnard: count, sum, avg, min, max, count_distinct, running_total, and more. Each type maps to a specific SQL aggregation.
 
 ## Overview
 

package/dist/docs/topics/cubes.public.md

@@ -1,6 +1,6 @@
-# cubes.public
+# Public
 
-> Control visibility of cubes, measures, and dimensions in the API.
+> The public property controls whether cubes, measures, and dimensions are exposed in the API. Set public to false to hide internal implementation details from consumers.
 
 ## Overview
 

package/dist/docs/topics/cubes.refresh-key.md

@@ -1,6 +1,6 @@
-# cubes.refresh-key
+# Refresh Key
 
-> Control when cube data is refreshed in the cache.
+> The refresh_key property controls when cube data is refreshed in the cache. Define time-based or query-based refresh strategies to balance data freshness with query performance.
 
 ## Overview
 

package/dist/docs/topics/cubes.segments.md

@@ -1,6 +1,6 @@
-# cubes.segments
+# Segments
 
-> Define reusable row-level filters.
+> Segments define reusable row-level filters that can be applied to any query on a cube. Use them for common filters like "active users" or "paid orders" that multiple consumers need.
 
 ## Overview
 

package/dist/docs/topics/cubes.sql.md

@@ -1,6 +1,6 @@
-# cubes.sql
+# SQL
 
-> Define the SQL table or subquery that powers a cube.
+> Define the SQL table or subquery that powers a cube. Use the sql property to point to a physical table, or write a SELECT statement for derived datasets and transformations.
 
 ## Overview
 

package/dist/docs/topics/features.catalog.md

@@ -0,0 +1,31 @@
+# Catalog
+
+> Browse and understand your data model — no code required.
+
+The Bonnard catalog gives everyone on your team a live view of your semantic layer. Browse cubes, views, measures, and dimensions from the browser. Understand what data is available before writing a single query.
+
+## What you can explore
+
+- **Cubes and Views** — See every deployed source with field counts at a glance
+- **Measures** — Aggregation type, SQL expression, format (currency, percentage), and description
+- **Dimensions** — Data type, time granularity options, and custom metadata
+- **Segments** — Pre-defined filters available for queries
+
+## Field-level detail
+
+Click any field to see exactly how it's calculated:
+
+- **SQL expression** — The underlying query logic
+- **Type and format** — How the field is aggregated and displayed
+- **Origin cube** — Which cube a view field traces back to
+- **Referenced fields** — Dependencies this field relies on
+- **Custom metadata** — Tags, labels, and annotations set by your data team
+
+## Built for business users
+
+The catalog is designed for anyone who needs to understand the data, not just engineers. No YAML, no terminal, no warehouse credentials. Browse the schema, read descriptions, and know exactly what to ask your AI agent for.
+
+## See Also
+
+- [views](views) — How to create curated views for your team
+- [cubes.public](cubes.public) — Control which cubes are visible