@bonnard/cli 0.1.13 → 0.2.1

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

@@ -1,15 +1,33 @@
-# workflow.deploy
+# Deploy
 
-> Push cubes and views to Bonnard for querying.
+> 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.
+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
+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 (fails on missing datasources) |
+| `--push-datasources` | Auto-push missing datasources to Bonnard |
+
+### CI/CD
+
+For automated pipelines, combine `--ci` with `--push-datasources`:
+
+```bash
+bon deploy --ci --push-datasources -m "CI deploy"
 ```
 
 ## Prerequisites
@@ -23,12 +41,13 @@ bon deploy
 1. **Validates** — checks cubes and views for errors
 2. **Tests connections** — verifies data source access
 3. **Uploads** — sends cubes and views to Bonnard
-4. **Activates** — makes cubes and views available for queries
+4. **Detects changes** — compares against the previous deployment
+5. **Activates** — makes cubes and views available for queries
 
 ## Example Output
 
 ```
-bon deploy
+bon deploy -m "Add revenue metrics"
 
 ✓ Validating...
   ✓ bonnard/cubes/orders.yaml
@@ -43,14 +62,55 @@ bon deploy
 
 ✓ Deploy complete!
 
-Your semantic layer is now available at:
-  https://api.bonnard.dev/v1/your-org
+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
+bon deploy -m "message"
     │
     ├── 1. bon validate (must pass)
     │
@@ -61,7 +121,9 @@ bon deploy
     │       - views from bonnard/views/
     │       - datasource configs
     │
-    └── 4. Activate deployment
+    ├── 4. Detect changes vs. previous deployment
+    │
+    └── 5. Activate deployment
 ```
 
 ## Error Handling
@@ -111,13 +173,16 @@ Run: bon login
 - **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. **Validate first** — run `bon validate` before deploy
-2. **Test locally** — verify queries work before deploying
-3. **Use version control** — commit cubes and views before deploying
-4. **Monitor after deploy** — check for query errors
+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
 

package/dist/docs/topics/workflow.mcp.md

@@ -1,6 +1,6 @@
-# workflow.mcp
+# MCP
 
-> Connect AI agents to your semantic layer via MCP.
+> Connect AI agents like Claude, ChatGPT, and Cursor to your semantic layer using the Model Context Protocol. MCP gives agents governed access to your metrics and dimensions.
 
 ## Overview
 
@@ -18,37 +18,39 @@ https://mcp.bonnard.dev/mcp
 
 ### Claude Desktop
 
-1. Open **Settings > Connectors**
+1. Click the **+** button in the chat input, then select **Connectors > Manage connectors**
+
+![Claude Desktop — Connectors menu in chat](/images/claude-chat-connectors.png)
+
 2. Click **Add custom connector**
 3. Enter a name (e.g. "Bonnard MCP") and the MCP URL: `https://mcp.bonnard.dev/mcp`
 4. Click **Add**
 
-![Claude Desktop — Settings > Connectors](/images/claude-connectors.png)
-
 ![Claude Desktop — Add custom connector dialog](/images/claude-add-connector.png)
 
-Once added, enable the Bonnard connector in any chat via the **Connectors** menu:
-
-![Claude Desktop — Bonnard MCP enabled in chat](/images/claude-chat-connectors.png)
+Once added, enable the Bonnard connector in any chat via the **Connectors** menu.
 
 Remote MCP servers in Claude Desktop must be added through the Connectors UI, not the JSON config file.
 
 ### ChatGPT
 
-1. Open **Settings > Apps**
-2. Click **Advanced settings** and enable **Developer mode**
+Custom MCP servers must be added in the browser at [chatgpt.com](https://chatgpt.com) — the desktop app does not support this.
+
+1. Go to [chatgpt.com](https://chatgpt.com) in your browser
+2. Open **Settings > Apps**
 
 ![ChatGPT — Settings > Apps](/images/chatgpt-apps.png)
 
-![ChatGPT — Enable Developer mode](/images/chatgpt-developer-mode.png)
+3. Click **Advanced settings**, enable **Developer mode**, then click **Create app**
+
+![ChatGPT — Advanced settings with Developer mode and Create app](/images/advanced-create-app-chatgpt.png)
 
-3. Click **Create app**
 4. Enter a name (e.g. "Bonnard MCP"), the MCP URL `https://mcp.bonnard.dev/mcp`, and select **OAuth** for authentication
 5. Check the acknowledgement box and click **Create**
 
 ![ChatGPT — Create new app with MCP URL](/images/chatgpt-new-app.png)
 
-Once created, the Bonnard connector appears in the **More** menu in any chat:
+Once created, the Bonnard connector appears under **Enabled apps**:
 
 ![ChatGPT — Bonnard MCP available in chat](/images/chatgpt-chat-apps.png)
 
@@ -68,6 +70,8 @@ Open **Settings > MCP** and add the server URL, or add to `.cursor/mcp.json` in
 }
 ```
 
+On first use, your browser will open to sign in and authorize the connection.
+
 ### VS Code / GitHub Copilot
 
 Open the Command Palette and run **MCP: Add Server**, or add to `.vscode/mcp.json` in your project:
@@ -83,6 +87,8 @@ Open the Command Palette and run **MCP: Add Server**, or add to `.vscode/mcp.jso
 }
 ```
 
+On first use, your browser will open to sign in and authorize the connection.
+
 ### Claude Code
 
 Run in your terminal:

package/dist/docs/topics/workflow.md

@@ -1,6 +1,6 @@
-# workflow
+# Workflow
 
-> Development workflow for building and deploying cubes and views.
+> The end-to-end workflow for building a semantic layer with Bonnard: validate your YAML definitions locally, deploy to the platform, and query your metrics via API or MCP.
 
 ## Overview
 
@@ -21,7 +21,7 @@ bon datasource add
 bon validate
 
 # 5. Deploy to Bonnard
-bon deploy
+bon deploy -m "Initial semantic layer"
 ```
 
 ## Project Structure
@@ -81,9 +81,8 @@ views:
 
 Check for syntax errors and test connections:
 
-```yaml
+```bash
 bon validate
-bon validate --test-connection
 ```
 
 ### 4. Deploy
@@ -91,7 +90,17 @@ bon validate --test-connection
 Push cubes and views to Bonnard:
 
 ```bash
-bon deploy
+bon deploy -m "Add orders cube and overview view"
+```
+
+### 5. Review
+
+Check what changed in your deployment:
+
+```bash
+bon deployments                       # List recent deployments
+bon diff <deployment-id>              # View all changes
+bon diff <deployment-id> --breaking   # Breaking changes only
 ```
 
 ## File Organization
@@ -134,10 +143,18 @@ bonnard/cubes/
 |---------|-------------|
 | `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 datasource test <name>` | Test connection |
+| `bon datasource test <name>` | Test connection (requires login) |
 | `bon validate` | Check cube and view syntax |
-| `bon deploy` | Deploy to Bonnard |
+| `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 |
 
 ## See Also

package/dist/docs/topics/workflow.query.md

@@ -1,6 +1,6 @@
-# workflow.query
+# Query
 
-> Query the deployed semantic layer using JSON or SQL.
+> Query your deployed semantic layer using the Bonnard REST API. Send JSON query objects or SQL strings to retrieve measures and dimensions with filtering, grouping, and time ranges.
 
 ## Overview
 

package/dist/docs/topics/workflow.validate.md

@@ -1,19 +1,15 @@
-# workflow.validate
+# Validate
 
-> Check cubes and views for errors before deploying.
+> Run validation checks on your cubes and views before deploying to catch YAML syntax errors, missing references, circular joins, and other issues. Use `bon validate` from the CLI.
 
 ## Overview
 
-The `bon validate` command checks your YAML cubes and views for syntax errors, schema violations, and optionally tests data source connections. Run this before deploying to catch issues early.
+The `bon validate` command checks your YAML cubes and views for syntax errors and schema violations. Run this before deploying to catch issues early.
 
 ## Usage
 
 ```bash
-# Basic validation
 bon validate
-
-# Also test data source connections
-bon validate --test-connection
 ```
 
 ## What Gets Validated
@@ -36,12 +32,6 @@ bon validate --test-connection
 - Referenced members exist
 - Join relationships are valid
 
-### Connection Testing (--test-connection)
-
-- Data source credentials work
-- Database is accessible
-- Tables/schemas exist
-
 ## Example Output
 
 ### Success
@@ -73,17 +63,6 @@ bonnard/cubes/orders.yaml:15:5
 1 error found.
 ```
 
-### Connection Warnings
-
-```
-✓ Validating YAML syntax...
-✓ All cubes and views valid.
-
-⚠ Testing connections...
-  ⚠ datasource "analytics": Connection timed out
-    (This won't block deploy, but queries may fail)
-```
-
 ## Common Errors
 
 ### Missing Required Field
@@ -125,12 +104,6 @@ measures:
   type: count
 ```
 
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--test-connection` | Also test datasource connections |
-
 ## Exit Codes
 
 | Code | Meaning |
@@ -143,7 +116,7 @@ measures:
 1. **Run before every deploy** — `bon validate && bon deploy`
 2. **Add to CI/CD** — validate on pull requests
 3. **Fix errors first** — don't deploy with validation errors
-4. **Test connections periodically** — catch credential issues early
+4. **Test connections** — use `bon datasource test <name>` to check connectivity
 
 ## See Also
 

package/dist/templates/claude/skills/bonnard-get-started/SKILL.md

@@ -41,25 +41,12 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available.
-**Always run this before creating cubes** — use the results to decide which
-tables to model and what columns to expose.
+Before creating cubes, understand what tables and columns are available in your warehouse.
 
-```bash
-# List tables — use the schema from the datasource config
-# For demo data (contoso schema):
-bon preview contoso_demo "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"
-
-# For user's own data (typically public schema):
-bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
-
-# Snowflake:
-bon preview <datasource> "SHOW TABLES"
-
-# Then sample the key tables to see columns and data:
-bon preview contoso_demo "SELECT * FROM contoso.fact_sales" --limit 10
-bon preview contoso_demo "SELECT * FROM contoso.dim_product" --limit 10
-```
+**Options for exploring your data:**
+- Use your database IDE or CLI (e.g., `psql`, Snowflake web UI, BigQuery console) to browse tables
+- Check your dbt docs or existing documentation for table schemas
+- For the demo dataset, the tables are: `contoso.fact_sales`, `contoso.dim_product`, `contoso.dim_store`, `contoso.dim_customer`
 
 Note the table names, column names, and data types — you'll use these in Phase 3.
 
@@ -157,11 +144,9 @@ Fix any errors before proceeding. Common issues:
 - Unknown measure/dimension types (e.g., `text` should be `string`)
 - Bad YAML indentation
 
-Optionally test the datasource connection too:
-
-```bash
-bon validate --test-connection
-```
+Validate also warns about:
+- **Missing descriptions** — descriptions help AI agents and analysts discover metrics
+- **Missing `data_source`** — cubes without an explicit `data_source` use the default warehouse, which can cause issues when multiple warehouses are configured
 
 ## Phase 6: Deploy
 
@@ -169,11 +154,16 @@ Log in (if not already) and deploy:
 
 ```bash
 bon login
-bon deploy
+bon deploy -m "Initial semantic layer with sales cube and overview view"
 ```
 
-Deploy validates, tests connections, uploads cubes/views, and syncs datasource
-credentials (encrypted) to Bonnard.
+Deploy requires a `-m` message describing the changes. It validates, tests
+connections, uploads cubes/views, and syncs datasource credentials (encrypted)
+to Bonnard.
+
+After deploying, the output shows what changed (added/modified/removed) and
+flags any breaking changes. Use `bon deployments` to see history and
+`bon diff <id>` to review changes from any deployment.
 
 ## Phase 7: Test with a Query
 

package/dist/templates/cursor/rules/bonnard-get-started.mdc

@@ -40,25 +40,12 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available.
-**Always run this before creating cubes** — use the results to decide which
-tables to model and what columns to expose.
+Before creating cubes, understand what tables and columns are available in your warehouse.
 
-```bash
-# List tables — use the schema from the datasource config
-# For demo data (contoso schema):
-bon preview contoso_demo "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"
-
-# For user's own data (typically public schema):
-bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
-
-# Snowflake:
-bon preview <datasource> "SHOW TABLES"
-
-# Then sample the key tables to see columns and data:
-bon preview contoso_demo "SELECT * FROM contoso.fact_sales" --limit 10
-bon preview contoso_demo "SELECT * FROM contoso.dim_product" --limit 10
-```
+**Options for exploring your data:**
+- Use your database IDE or CLI (e.g., `psql`, Snowflake web UI, BigQuery console) to browse tables
+- Check your dbt docs or existing documentation for table schemas
+- For the demo dataset, the tables are: `contoso.fact_sales`, `contoso.dim_product`, `contoso.dim_store`, `contoso.dim_customer`
 
 Note the table names, column names, and data types — you'll use these in Phase 3.
 
@@ -156,11 +143,9 @@ Fix any errors before proceeding. Common issues:
 - Unknown measure/dimension types (e.g., `text` should be `string`)
 - Bad YAML indentation
 
-Optionally test the datasource connection too:
-
-```bash
-bon validate --test-connection
-```
+Validate also warns about:
+- **Missing descriptions** — descriptions help AI agents and analysts discover metrics
+- **Missing `data_source`** — cubes without an explicit `data_source` use the default warehouse, which can cause issues when multiple warehouses are configured
 
 ## Phase 6: Deploy
 
@@ -168,11 +153,16 @@ Log in (if not already) and deploy:
 
 ```bash
 bon login
-bon deploy
+bon deploy -m "Initial semantic layer with sales cube and overview view"
 ```
 
-Deploy validates, tests connections, uploads cubes/views, and syncs datasource
-credentials (encrypted) to Bonnard.
+Deploy requires a `-m` message describing the changes. It validates, tests
+connections, uploads cubes/views, and syncs datasource credentials (encrypted)
+to Bonnard.
+
+After deploying, the output shows what changed (added/modified/removed) and
+flags any breaking changes. Use `bon deployments` to see history and
+`bon diff <id>` to review changes from any deployment.
 
 ## Phase 7: Test with a Query
 

package/dist/templates/shared/bonnard.md

@@ -63,10 +63,15 @@ All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
 | `bon datasource add` | Add warehouse connection |
 | `bon datasource add --demo` | Add demo dataset (no warehouse needed) |
 | `bon datasource add --from-dbt` | Import from dbt profiles |
-| `bon datasource test <name>` | Test connection |
-| `bon validate` | Validate YAML syntax |
-| `bon validate --test-connection` | Validate + test connections |
-| `bon deploy` | Deploy to Bonnard (requires login) |
+| `bon datasource test <name>` | Test connection (requires login) |
+| `bon validate` | Validate YAML syntax, warn on missing descriptions and `data_source` |
+| `bon deploy -m "message"` | Deploy to Bonnard (requires login, message required) |
+| `bon deploy --ci` | Non-interactive deploy (fails on missing datasources) |
+| `bon deployments` | List recent deployments (add `--all` for full history) |
+| `bon diff <deployment-id>` | Show changes in a deployment (`--breaking` for breaking only) |
+| `bon annotate <deployment-id>` | Add reasoning/context to deployment changes |
+| `bon query '{...}'` | Execute a semantic layer query (JSON or `--sql` format) |
+| `bon mcp` | Show MCP setup instructions for AI agents |
 | `bon docs` | Browse documentation |
 
 ## Learning YAML Syntax
@@ -92,7 +97,27 @@ Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to
 1. **Setup datasource** — `bon datasource add --from-dbt` or manual
 2. **Create cubes** — Define measures/dimensions in `bonnard/cubes/*.yaml`
 3. **Create views** — Compose cubes in `bonnard/views/*.yaml`
-4. **Validate** — `bon validate --test-connection`
-5. **Deploy** — `bon login` then `bon deploy`
+4. **Validate** — `bon validate`
+5. **Deploy** — `bon login` then `bon deploy -m "description of changes"`
+6. **Review** — `bon deployments` to list, `bon diff <id>` to inspect changes
 
 For a guided walkthrough: `/bonnard-get-started`
+
+## Deployment & Change Tracking
+
+Every deploy creates a versioned deployment with change detection:
+
+- **Deploy** requires a message: `bon deploy -m "Add revenue metrics"`
+- **Changes** are detected automatically: added, modified, removed fields
+- **Breaking changes** (removed measures/dimensions, type changes) are flagged
+- **Deployment history**: `bon deployments` lists recent deploys with IDs
+- **Diff**: `bon diff <id>` shows all changes; `bon diff <id> --breaking` filters to breaking only
+- **Annotate**: `bon annotate <id> --data '{"object": "note"}'` adds context to changes
+
+For CI/CD pipelines, use `bon deploy --ci -m "message"` (non-interactive, fails on issues) or `bon deploy --push-datasources -m "message"` to auto-push missing datasources.
+
+## Best Practices
+
+- **Always set `data_source`** on cubes — without it, cubes silently use the default warehouse, which breaks when multiple warehouses are added later. `bon validate` warns about this.
+- **Add descriptions** to all cubes, views, measures, and dimensions — these power AI agent discovery and the schema catalog.
+- **Use `sql_table` with full schema path** (e.g., `schema.table_name`) for clarity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"
@@ -18,16 +18,12 @@
     "@toon-format/toon": "^2.1.0",
     "commander": "^12.0.0",
     "open": "^11.0.0",
-    "@cubejs-backend/schema-compiler": "^1.6.7",
-    "@cubejs-backend/shared": "^1.6.7",
     "picocolors": "^1.0.0",
-    "yaml": "^2.8.0"
-  },
-  "optionalDependencies": {
-    "snowflake-sdk": "^2.3.3",
-    "pg": "^8.18.0"
+    "yaml": "^2.8.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@types/node": "^20.0.0",
     "tsdown": "^0.20.1",
     "vitest": "^2.0.0"
   },