@bonnard/cli 0.2.5 → 0.2.7

package/README.md

@@ -0,0 +1,85 @@
+# @bonnard/cli
+
+The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Define metrics in YAML, validate locally, deploy, and query — from your terminal or AI coding agent.
+
+## Install
+
+```bash
+npm install -g @bonnard/cli
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+```bash
+bon init                        # Create project structure + agent templates
+bon datasource add --demo       # Add demo dataset (no warehouse needed)
+bon validate                    # Check syntax
+bon login                       # Authenticate with Bonnard
+bon deploy -m "Initial deploy"  # Deploy to Bonnard
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `bon init` | Create project structure and AI agent templates |
+| `bon login` | Authenticate with Bonnard |
+| `bon logout` | Remove stored credentials |
+| `bon whoami` | Show current login status |
+| `bon datasource add` | Add a data source (interactive) |
+| `bon datasource add --demo` | Add read-only demo dataset |
+| `bon datasource add --from-dbt` | Import from dbt profiles |
+| `bon datasource list` | List configured data sources |
+| `bon datasource remove <name>` | Remove a data source |
+| `bon validate` | Validate cube and view YAML |
+| `bon deploy -m "message"` | Deploy to Bonnard |
+| `bon deployments` | List deployment history |
+| `bon diff <id>` | View changes in a deployment |
+| `bon annotate <id>` | Add context to deployment changes |
+| `bon query '{"measures":["orders.count"]}'` | Query the semantic layer (JSON) |
+| `bon query "SELECT ..." --sql` | Query the semantic layer (SQL) |
+| `bon mcp` | MCP setup instructions for AI agents |
+| `bon mcp test` | Test MCP server connectivity |
+| `bon docs [topic]` | Browse modeling documentation |
+| `bon docs --search "joins"` | Search documentation |
+
+## Agent-ready from the start
+
+`bon init` generates context files for your AI coding tools:
+
+- **Claude Code** — `.claude/rules/` + get-started skill
+- **Cursor** — `.cursor/rules/` with auto-apply frontmatter
+- **Codex** — `AGENTS.md` + skills folder
+
+Your agent understands Bonnard's modeling language from the first prompt.
+
+## Project structure
+
+After `bon init`:
+
+```
+my-project/
+├── bon.yaml              # Project configuration
+├── bonnard/
+│   ├── cubes/            # Cube definitions (measures, dimensions, joins)
+│   └── views/            # View definitions (curated query interfaces)
+└── .bon/                 # Local config (gitignored)
+    └── datasources.yaml  # Data source credentials
+```
+
+## CI/CD
+
+```bash
+bon deploy --ci -m "CI deploy"
+```
+
+Non-interactive mode for pipelines. Datasources are synced automatically.
+
+## Documentation
+
+- [Getting Started](https://docs.bonnard.dev/docs/getting-started)
+- [CLI Reference](https://docs.bonnard.dev/docs/cli)
+- [Modeling Guide](https://docs.bonnard.dev/docs/modeling/cubes)
+- [Querying](https://docs.bonnard.dev/docs/querying)

package/dist/bin/bon.mjs

@@ -2698,11 +2698,11 @@ async function showOverview(client) {
 	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>"));
+	console.log(pc.dim("  bon metabase explore card <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore dashboard <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore database <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore table <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore collection <id-or-name>"));
 }
 async function showDatabases(client) {
 	const databases = await client.getDatabases();
@@ -2778,7 +2778,7 @@ async function showCards(client) {
 		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>"));
+	console.log(pc.dim("View details: bon metabase explore card <id-or-name>"));
 }
 async function showCardDetail(client, id) {
 	const card = await client.getCard(id);
@@ -2835,7 +2835,7 @@ async function showDashboards(client) {
 	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>"));
+	console.log(pc.dim("View details: bon metabase explore dashboard <id-or-name>"));
 }
 async function showDashboardDetail(client, id) {
 	const [dashboard, allCards] = await Promise.all([client.getDashboard(id), client.getCards()]);
@@ -2895,7 +2895,7 @@ async function showDatabaseDetail(client, id) {
 		}
 		console.log();
 	}
-	console.log(pc.dim("View table fields: bon metabase explore table <id>"));
+	console.log(pc.dim("View table fields: bon metabase explore table <id-or-name>"));
 }
 function classifyFieldType(field) {
 	const bt = field.base_type || "";
@@ -3008,8 +3008,105 @@ async function showCollectionDetail(client, id) {
 		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>"));
+	console.log(pc.dim("View card SQL: bon metabase explore card <id-or-name>"));
+	console.log(pc.dim("View dashboard: bon metabase explore dashboard <id-or-name>"));
+}
+function isNumericId(value) {
+	return /^\d+$/.test(value);
+}
+function showDisambiguation(resource, matches) {
+	console.error(pc.yellow(`Multiple ${resource}s match that name:\n`));
+	for (const m of matches) console.log(`  ${padColumn(String(m.id), 8)}${m.label}`);
+	console.log();
+	console.log(pc.dim(`Use the numeric ID to be specific: bon metabase explore ${resource} <id>`));
+	process.exit(1);
+}
+async function resolveCardId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const cards = await client.getCards();
+	const needle = input.toLowerCase();
+	const matches = cards.filter((c) => c.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No card found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("card", matches.map((c) => ({
+		id: c.id,
+		label: c.name
+	})));
+}
+async function resolveDashboardId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const dashboards = await client.getDashboards();
+	const needle = input.toLowerCase();
+	const matches = dashboards.filter((d) => d.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No dashboard found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("dashboard", matches.map((d) => ({
+		id: d.id,
+		label: d.name
+	})));
+}
+async function resolveDatabaseId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const databases = await client.getDatabases();
+	const needle = input.toLowerCase();
+	const matches = databases.filter((d) => d.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No database found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("database", matches.map((d) => ({
+		id: d.id,
+		label: `${d.name} (${d.engine})`
+	})));
+}
+async function resolveTableId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const databases = await client.getDatabases();
+	const needle = input.toLowerCase();
+	const matches = [];
+	for (const db of databases) {
+		const meta = await client.getDatabaseMetadata(db.id);
+		for (const t of meta.tables) {
+			if (t.visibility_type === "hidden" || t.visibility_type === "retired") continue;
+			if (t.name.toLowerCase().includes(needle)) matches.push({
+				id: t.id,
+				name: t.name,
+				schema: t.schema,
+				dbName: db.name
+			});
+		}
+	}
+	if (matches.length === 0) {
+		console.error(pc.red(`No table found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("table", matches.map((m) => ({
+		id: m.id,
+		label: `${m.dbName} / ${m.schema}.${m.name}`
+	})));
+}
+async function resolveCollectionId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const collections = await client.getCollections();
+	const needle = input.toLowerCase();
+	const matches = collections.filter((c) => typeof c.id === "number" && c.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No collection found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("collection", matches.map((c) => ({
+		id: c.id,
+		label: c.name
+	})));
 }
 const RESOURCES = [
 	"databases",
@@ -3047,71 +3144,41 @@ async function metabaseExploreCommand(resource, id) {
 			case "dashboards":
 				await showDashboards(client);
 				break;
-			case "card": {
+			case "card":
 				if (!id) {
-					console.error(pc.red("Card ID required: bon metabase explore card <id>"));
+					console.error(pc.red("Usage: bon metabase explore card <id-or-name>"));
 					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);
+				await showCardDetail(client, await resolveCardId(client, id));
 				break;
-			}
-			case "dashboard": {
+			case "dashboard":
 				if (!id) {
-					console.error(pc.red("Dashboard ID required: bon metabase explore dashboard <id>"));
+					console.error(pc.red("Usage: bon metabase explore dashboard <id-or-name>"));
 					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);
+				await showDashboardDetail(client, await resolveDashboardId(client, id));
 				break;
-			}
-			case "database": {
+			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}`));
+					console.error(pc.red("Usage: bon metabase explore database <id-or-name>"));
 					process.exit(1);
 				}
-				await showDatabaseDetail(client, dbId);
+				await showDatabaseDetail(client, await resolveDatabaseId(client, id));
 				break;
-			}
-			case "table": {
+			case "table":
 				if (!id) {
-					console.error(pc.red("Table ID required: bon metabase explore table <id>"));
+					console.error(pc.red("Usage: bon metabase explore table <id-or-name>"));
 					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);
+				await showTableDetail(client, await resolveTableId(client, id));
 				break;
-			}
-			case "collection": {
+			case "collection":
 				if (!id) {
-					console.error(pc.red("Collection ID required: bon metabase explore collection <id>"));
+					console.error(pc.red("Usage: bon metabase explore collection <id-or-name>"));
 					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);
+				await showCollectionDetail(client, await resolveCollectionId(client, id));
 				break;
-			}
 		}
 	} catch (err) {
 		if (err instanceof MetabaseApiError) {
@@ -3454,10 +3521,10 @@ function buildReport(data) {
 	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 += `- \`bon metabase explore table <id-or-name>\` — field types and classification\n`;
+	report += `- \`bon metabase explore card <id-or-name>\` — SQL and columns\n`;
+	report += `- \`bon metabase explore collection <id-or-name>\` — cards in a collection\n`;
+	report += `- \`bon metabase explore database <id-or-name>\` — schemas and tables\n\n`;
 	report += `## Summary\n\n`;
 	report += `| Metric | Count |\n|--------|-------|\n`;
 	report += `| Databases | ${databases.length} |\n`;
@@ -3497,7 +3564,7 @@ function buildReport(data) {
 	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 += `Use \`bon metabase explore card <id-or-name>\` 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++) {
@@ -3555,8 +3622,18 @@ function buildReport(data) {
 		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`;
+		const tableIdByRef = /* @__PURE__ */ new Map();
+		for (const db of databases) for (const t of db.tables) {
+			const qualified = `${t.schema}.${t.name}`.toLowerCase();
+			const unqualified = t.name.toLowerCase();
+			if (!tableIdByRef.has(qualified)) tableIdByRef.set(qualified, t.id);
+			if (!tableIdByRef.has(unqualified)) tableIdByRef.set(unqualified, t.id);
+		}
+		report += `| ID | Table | References |\n|------|-------|------------|\n`;
+		for (const [table, count] of sortedRefs) {
+			const tid = tableIdByRef.get(table);
+			report += `| ${tid ?? "—"} | ${table} | ${count} |\n`;
+		}
 		report += `\n`;
 	}
 	const fieldIdLookup = /* @__PURE__ */ new Map();
@@ -3656,9 +3733,9 @@ function buildReport(data) {
 			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`;
+			report += `| ID | Table | Fields | Dims | Measures | Time | Refs |\n`;
+			report += `|------|-------|--------|------|----------|------|------|\n`;
+			for (const s of referenced) report += `| ${s.id} | ${s.name} | ${s.fieldCount} | ${s.dimensions} | ${s.measures} | ${s.timeDimensions} | ${s.refCount} |\n`;
 			if (unreferenced > 0) skippedTables += unreferenced;
 			report += `\n`;
 		}

package/dist/docs/_index.md

@@ -52,13 +52,24 @@
 - [syntax.references](syntax.references) - Reference columns, members, and cubes
 - [syntax.context-variables](syntax.context-variables) - CUBE, FILTER_PARAMS, COMPILE_CONTEXT
 
-## Workflow
+## Querying
 
-- [workflow](workflow) - End-to-end development workflow
-- [workflow.validate](workflow.validate) - Validate cubes and views locally
-- [workflow.deploy](workflow.deploy) - Deploy to Bonnard
-- [workflow.query](workflow.query) - Query the deployed semantic layer
-- [workflow.mcp](workflow.mcp) - Connect AI agents via MCP
+- [querying](querying) - Query your deployed semantic layer
+- [querying.mcp](querying.mcp) - Connect AI agents via MCP
+- [querying.rest-api](querying.rest-api) - REST API and SQL query reference
+- [querying.sdk](querying.sdk) - TypeScript SDK for custom apps
+
+## CLI
+
+- [cli](cli) - CLI commands and development workflow
+- [cli.deploy](cli.deploy) - Deploy to Bonnard
+- [cli.validate](cli.validate) - Validate cubes and views locally
+
+## Other
+
+- [governance](governance) - User and group-level permissions
+- [catalog](catalog) - Browse your data model in the browser
+- [slack-teams](slack-teams) - AI agents in team chat (coming soon)
 
 ## Quick Reference
 

package/dist/docs/topics/catalog.md

@@ -0,0 +1,36 @@
+# 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.
+
+## Coming soon
+
+- **Relationship visualization** — An interactive visual map showing how cubes connect through joins and shared dimensions
+- **Impact analysis** — Understand which views and measures are affected when you change a cube, before you deploy
+
+## See Also
+
+- [views](views) — How to create curated views for your team
+- [cubes.public](cubes.public) — Control which cubes are visible

package/dist/docs/topics/cli.deploy.md

@@ -0,0 +1,193 @@
+# Deploy
+
+> Deploy your cubes and views to the Bonnard platform using the CLI. Once deployed, your semantic layer is queryable via the REST API, MCP for AI agents, and connected BI tools.
+
+## Overview
+
+The `bon deploy` command uploads your cubes and views to Bonnard, making them available for querying via the API. It validates and tests connections before deploying, and creates a versioned deployment with change detection.
+
+## Usage
+
+```bash
+bon deploy -m "description of changes"
+```
+
+A `-m` message is **required** — it describes what changed in this deployment.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-m "message"` | **Required.** Deployment description |
+| `--ci` | Non-interactive mode |
+
+Datasources are always synced automatically during deploy.
+
+### CI/CD
+
+For automated pipelines, use `--ci` for non-interactive mode:
+
+```bash
+bon deploy --ci -m "CI deploy"
+```
+
+## Prerequisites
+
+1. **Logged in** — run `bon login` first
+2. **Valid cubes and views** — must pass `bon validate`
+3. **Working connections** — data sources must be accessible
+
+## What Happens
+
+1. **Validates** — checks cubes and views for errors
+2. **Tests connections** — verifies data source access
+3. **Uploads** — sends cubes and views to Bonnard
+4. **Detects changes** — compares against the previous deployment
+5. **Activates** — makes cubes and views available for queries
+
+## Example Output
+
+```
+bon deploy -m "Add revenue metrics"
+
+✓ Validating...
+  ✓ bonnard/cubes/orders.yaml
+  ✓ bonnard/cubes/users.yaml
+  ✓ bonnard/views/orders_overview.yaml
+
+✓ Testing connections...
+  ✓ datasource "default" connected
+
+✓ Deploying to Bonnard...
+  Uploading 2 cubes, 1 view...
+
+✓ Deploy complete!
+
+Changes:
+  + orders.total_revenue (measure)
+  + orders.avg_order_value (measure)
+  ~ orders.count (measure) — type changed
+
+⚠ 1 breaking change detected
+```
+
+## Change Detection
+
+Every deployment is versioned. Bonnard automatically detects:
+
+- **Added** — new cubes, views, measures, dimensions
+- **Modified** — changes to type, SQL, format, description
+- **Removed** — deleted fields (flagged as breaking)
+- **Breaking changes** — removed measures/dimensions, type changes
+
+## Reviewing Deployments
+
+After deploying, use these commands to review history and changes:
+
+### List deployments
+
+```bash
+bon deployments          # Recent deployments
+bon deployments --all    # Full history
+```
+
+### View changes in a deployment
+
+```bash
+bon diff <deployment-id>              # All changes
+bon diff <deployment-id> --breaking   # Breaking changes only
+```
+
+### Annotate changes
+
+Add reasoning or context to deployment changes:
+
+```bash
+bon annotate <deployment-id> --data '{"object": "note about why this changed"}'
+```
+
+Annotations are visible in the schema catalog and help teammates understand why changes were made.
+
+## Deploy Flow
+
+```
+bon deploy -m "message"
+    │
+    ├── 1. bon validate (must pass)
+    │
+    ├── 2. Test all datasource connections (must succeed)
+    │
+    ├── 3. Upload to Bonnard API
+    │       - cubes from bonnard/cubes/
+    │       - views from bonnard/views/
+    │       - datasource configs
+    │
+    ├── 4. Detect changes vs. previous deployment
+    │
+    └── 5. Activate deployment
+```
+
+## Error Handling
+
+### Validation Errors
+
+```
+✗ Validating...
+
+bonnard/cubes/orders.yaml:15:5
+  error: Unknown measure type "counts"
+
+Deploy aborted. Fix validation errors first.
+```
+
+### Connection Errors
+
+```
+✗ Testing connections...
+  ✗ datasource "analytics": Connection refused
+
+Deploy aborted. Fix connection issues:
+  - Check credentials in .bon/datasources.yaml
+  - Verify network access to database
+  - Run: bon datasource add (to reconfigure)
+```
+
+### Auth Errors
+
+```
+✗ Not logged in.
+
+Run: bon login
+```
+
+## What Gets Deployed
+
+| Source | Deployed |
+|--------|----------|
+| `bonnard/cubes/*.yaml` | All cube definitions |
+| `bonnard/views/*.yaml` | All view definitions |
+| `.bon/datasources.yaml` | Connection configs (credentials encrypted) |
+| `bon.yaml` | Project settings |
+
+## Deployment Behavior
+
+- **Replaces** previous deployment (not additive)
+- **All or nothing** — partial deploys don't happen
+- **Instant** — changes take effect immediately
+- **Versioned** — every deployment is tracked with changes
+
+## Best Practices
+
+1. **Always include a meaningful message** — helps teammates understand what changed
+2. **Validate first** — run `bon validate` before deploy
+3. **Test locally** — verify queries work before deploying
+4. **Use version control** — commit cubes and views before deploying
+5. **Review after deploy** — use `bon diff` to check for unintended breaking changes
+6. **Annotate breaking changes** — add context so consumers know what to update
+
+## See Also
+
+- cli
+- cli.validate
+- cubes
+- views