@bonnard/cli 0.2.4 → 0.2.6

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

@@ -567,21 +567,26 @@ function createAgentTemplates(cwd, env) {
 	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 });
+	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-design-guide"), { 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);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(claudeSkillsDir, "bonnard-design-guide", "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);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-design-guide.mdc"), path.join(cursorRulesDir, "bonnard-design-guide.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 });
+	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-design-guide"), { 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);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(codexSkillsDir, "bonnard-design-guide", "SKILL.md"), createdFiles);
 	return createdFiles;
 }
 async function initCommand() {
@@ -1704,7 +1709,7 @@ async function validateCommand() {
 		console.log(pc.red("No bon.yaml found. Are you in a Bonnard project?"));
 		process.exit(1);
 	}
-	const { validate } = await import("./validate-BdqZBH2n.mjs");
+	const { validate } = await import("./validate-Bc8zGNw7.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/.`));
@@ -1739,6 +1744,14 @@ async function validateCommand() {
 		console.log(pc.dim("  This can cause issues when multiple warehouses are configured."));
 		console.log(pc.dim(`  ${result.cubesMissingDataSource.join(", ")}`));
 	}
+	if (result.suspectPrimaryKeys.length > 0) {
+		console.log();
+		console.log(pc.yellow(`⚠ ${result.suspectPrimaryKeys.length} primary key(s) on time dimensions`));
+		console.log(pc.dim("  Time dimensions are rarely unique. Non-unique primary keys cause dimension"));
+		console.log(pc.dim("  queries to silently return empty results. Use a unique column or add a"));
+		console.log(pc.dim("  ROW_NUMBER() synthetic key via the cube's sql property."));
+		for (const s of result.suspectPrimaryKeys) console.log(pc.dim(`  ${s.cube}.${s.dimension} (type: ${s.type})`));
+	}
 }
 
 //#endregion
@@ -1770,7 +1783,7 @@ async function deployCommand(options = {}) {
 		process.exit(1);
 	}
 	console.log(pc.dim("Validating cubes and views..."));
-	const { validate } = await import("./validate-BdqZBH2n.mjs");
+	const { validate } = await import("./validate-Bc8zGNw7.mjs");
 	const result = await validate(cwd);
 	if (!result.valid) {
 		console.log(pc.red("Validation failed:\n"));

package/dist/bin/{validate-BdqZBH2n.mjs → validate-Bc8zGNw7.mjs}

@@ -218,11 +218,53 @@ function formatZodError(error, fileName, parsed) {
 		return `${fileName}: ${location ? `${location} — ` : ""}${issue.message}`;
 	});
 }
+function checkViewMemberConflicts(parsedFiles, cubeMap) {
+	const errors = [];
+	for (const { fileName, parsed } of parsedFiles) for (const view of parsed.views ?? []) {
+		if (!view.name || !view.cubes) continue;
+		const seen = /* @__PURE__ */ new Map();
+		for (const m of view.measures ?? []) if (m.name) seen.set(m.name, `${view.name} (direct)`);
+		for (const d of view.dimensions ?? []) if (d.name) seen.set(d.name, `${view.name} (direct)`);
+		for (const s of view.segments ?? []) if (s.name) seen.set(s.name, `${view.name} (direct)`);
+		for (const cubeRef of view.cubes) {
+			const joinPath = cubeRef.join_path;
+			if (!joinPath) continue;
+			const segments = joinPath.split(".");
+			const targetCubeName = segments[segments.length - 1];
+			let memberNames = [];
+			if (cubeRef.includes === "*") {
+				const cube = cubeMap.get(targetCubeName);
+				if (!cube) continue;
+				memberNames = [
+					...cube.measures,
+					...cube.dimensions,
+					...cube.segments
+				];
+			} else if (Array.isArray(cubeRef.includes)) {
+				for (const item of cubeRef.includes) if (typeof item === "string") memberNames.push(item);
+				else if (item && typeof item === "object" && item.name) memberNames.push(item.alias || item.name);
+			} else continue;
+			if (Array.isArray(cubeRef.excludes)) {
+				const excludeSet = new Set(cubeRef.excludes);
+				memberNames = memberNames.filter((n) => !excludeSet.has(n));
+			}
+			for (const rawName of memberNames) {
+				const finalName = cubeRef.prefix ? `${targetCubeName}_${rawName}` : rawName;
+				const existingSource = seen.get(finalName);
+				if (existingSource) errors.push(`${fileName}: view '${view.name}' — member '${finalName}' from '${joinPath}' conflicts with '${existingSource}'. Use prefix: true or an alias.`);
+				else seen.set(finalName, joinPath);
+			}
+		}
+	}
+	return errors;
+}
 function validateFiles(files) {
 	const errors = [];
 	const cubes = [];
 	const views = [];
 	const allNames = /* @__PURE__ */ new Map();
+	const parsedFiles = [];
+	const cubeMap = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		let parsed;
 		try {
@@ -240,12 +282,21 @@ function validateFiles(files) {
 			errors.push(...formatZodError(result.error, file.fileName, parsed));
 			continue;
 		}
+		parsedFiles.push({
+			fileName: file.fileName,
+			parsed
+		});
 		for (const cube of parsed.cubes ?? []) if (cube.name) {
 			const existing = allNames.get(cube.name);
 			if (existing) errors.push(`${file.fileName}: duplicate name '${cube.name}' (also defined in ${existing})`);
 			else {
 				allNames.set(cube.name, file.fileName);
 				cubes.push(cube.name);
+				cubeMap.set(cube.name, {
+					measures: (cube.measures ?? []).map((m) => m.name).filter(Boolean),
+					dimensions: (cube.dimensions ?? []).map((d) => d.name).filter(Boolean),
+					segments: (cube.segments ?? []).map((s) => s.name).filter(Boolean)
+				});
 			}
 		}
 		for (const view of parsed.views ?? []) if (view.name) {
@@ -257,6 +308,7 @@ function validateFiles(files) {
 			}
 		}
 	}
+	if (errors.length === 0) errors.push(...checkViewMemberConflicts(parsedFiles, cubeMap));
 	return {
 		errors,
 		cubes,
@@ -320,6 +372,22 @@ function checkMissingDescriptions(files) {
 	} catch {}
 	return missing;
 }
+function checkSuspectPrimaryKeys(files) {
+	const suspects = [];
+	for (const file of files) try {
+		const parsed = YAML.parse(file.content);
+		if (!parsed) continue;
+		for (const cube of parsed.cubes || []) {
+			if (!cube.name) continue;
+			for (const dim of cube.dimensions || []) if (dim.primary_key && dim.type === "time") suspects.push({
+				cube: cube.name,
+				dimension: dim.name,
+				type: dim.type
+			});
+		}
+	} catch {}
+	return suspects;
+}
 function checkMissingDataSource(files) {
 	const missing = [];
 	for (const file of files) try {
@@ -338,7 +406,8 @@ async function validate(projectPath) {
 		cubes: [],
 		views: [],
 		missingDescriptions: [],
-		cubesMissingDataSource: []
+		cubesMissingDataSource: [],
+		suspectPrimaryKeys: []
 	};
 	const result = validateFiles(files);
 	if (result.errors.length > 0) return {
@@ -347,17 +416,20 @@ async function validate(projectPath) {
 		cubes: [],
 		views: [],
 		missingDescriptions: [],
-		cubesMissingDataSource: []
+		cubesMissingDataSource: [],
+		suspectPrimaryKeys: []
 	};
 	const missingDescriptions = checkMissingDescriptions(files);
 	const cubesMissingDataSource = checkMissingDataSource(files);
+	const suspectPrimaryKeys = checkSuspectPrimaryKeys(files);
 	return {
 		valid: true,
 		errors: [],
 		cubes: result.cubes,
 		views: result.views,
 		missingDescriptions,
-		cubesMissingDataSource
+		cubesMissingDataSource,
+		suspectPrimaryKeys
 	};
 }
 

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

package/dist/docs/topics/cli.md

@@ -0,0 +1,113 @@
+# CLI
+
+> Built for agent-first development by data engineers.
+
+The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Initialize a project, connect your warehouse, define metrics in YAML, validate locally, and deploy — all from your terminal or your AI coding agent.
+
+## Agent-ready from the start
+
+`bon init` generates context files for your AI coding tools automatically:
+
+- **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`, your project has:
+
+```
+my-project/
+├── bon.yaml              # Project configuration
+├── bonnard/              # Semantic layer definitions
+│   ├── cubes/            # Cube definitions
+│   │   └── orders.yaml
+│   └── views/            # View definitions
+│       └── orders_overview.yaml
+└── .bon/                 # Local config (gitignored)
+    └── datasources.yaml  # Data source credentials
+```
+
+## File Organization
+
+### One Cube Per File
+
+```
+bonnard/cubes/
+├── orders.yaml
+├── users.yaml
+├── products.yaml
+└── line_items.yaml
+```
+
+### Related Cubes Together
+
+```
+bonnard/cubes/
+├── sales/
+│   ├── orders.yaml
+│   └── line_items.yaml
+├── users/
+│   ├── users.yaml
+│   └── profiles.yaml
+└── products/
+    └── products.yaml
+```
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `bon init` | Create project structure |
+| `bon datasource add` | Add a data source |
+| `bon datasource add --demo` | Add demo dataset (no warehouse needed) |
+| `bon datasource add --from-dbt` | Import from dbt profiles |
+| `bon datasource list` | List configured sources |
+| `bon validate` | Check cube and view syntax |
+| `bon deploy -m "message"` | Deploy to Bonnard (message required) |
+| `bon deploy --ci` | Non-interactive deploy |
+| `bon deployments` | List deployment history |
+| `bon diff <id>` | View changes in a deployment |
+| `bon annotate <id>` | Add context to deployment changes |
+| `bon query '{...}'` | Query the semantic layer |
+| `bon mcp` | MCP setup instructions for AI agents |
+| `bon docs` | Browse documentation |
+
+## CI/CD ready
+
+Deploy from GitHub Actions, GitLab CI, or any pipeline:
+
+```bash
+bon deploy --ci -m "CI deploy"
+```
+
+Non-interactive mode. Datasources are synced automatically. Fails fast if anything is misconfigured.
+
+## Deployment versioning
+
+Every deploy creates a versioned deployment with automatic change detection — added, modified, removed, and breaking changes are flagged. Review history with `bon deployments`, inspect changes with `bon diff`, and add context with `bon annotate`.
+
+## Built-in documentation
+
+```bash
+bon docs cubes.measures       # Read modeling docs in your terminal
+bon docs --search "joins"     # Search across all topics
+```
+
+No context-switching. Learn and build in the same workflow.
+
+## Best Practices
+
+1. **Start from questions** — collect the most common questions your team asks, then build views that answer them. Don't just mirror your warehouse tables.
+2. **Add filtered measures** — if a dashboard card has a WHERE clause beyond a date range, that filter should be a filtered measure. This is the #1 way to match real dashboard numbers.
+3. **Write descriptions for agents** — descriptions are how AI agents choose which view and measure to use. Lead with scope, cross-reference related views, include dimension values.
+4. **Validate often** — run `bon validate` after each change
+5. **Test with real questions** — after deploying, ask an AI agent via MCP the same questions your team asks. Check it picks the right view and measure.
+6. **Iterate** — expect 2-4 rounds of deploying, testing with questions, and improving descriptions before agents reliably answer the top 10 questions.
+
+## See Also
+
+- [cli.deploy](cli.deploy) — Deployment details
+- [cli.validate](cli.validate) — Validation reference