@bonnard/cli 0.1.12 → 0.2.0

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
@@ -91,7 +91,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 +144,20 @@ 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 preview <ds> "SQL"` | Run raw SQL against a warehouse |
 | `bon validate` | Check cube and view syntax |
-| `bon deploy` | Deploy to Bonnard |
+| `bon validate --test-connection` | Validate + test warehouse connections |
+| `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,6 +1,6 @@
-# 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
 

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

@@ -157,6 +157,10 @@ Fix any errors before proceeding. Common issues:
 - Unknown measure/dimension types (e.g., `text` should be `string`)
 - Bad YAML indentation
 
+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
+
 Optionally test the datasource connection too:
 
 ```bash
@@ -169,11 +173,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

@@ -156,6 +156,10 @@ Fix any errors before proceeding. Common issues:
 - Unknown measure/dimension types (e.g., `text` should be `string`)
 - Bad YAML indentation
 
+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
+
 Optionally test the datasource connection too:
 
 ```bash
@@ -168,11 +172,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

@@ -64,9 +64,16 @@ All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
 | `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 validate` | Validate YAML syntax, warn on missing descriptions and `data_source` |
+| `bon validate --test-connection` | Validate + test warehouse connections |
+| `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 preview <ds> "SQL"` | Run raw SQL against a warehouse |
+| `bon mcp` | Show MCP setup instructions for AI agents |
 | `bon docs` | Browse documentation |
 
 ## Learning YAML Syntax
@@ -93,6 +100,26 @@ Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to
 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`
+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.12",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"
@@ -9,7 +9,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin && cp -r src/templates dist/ && mkdir -p dist/docs/topics dist/docs/schemas && cp ../content/index.md dist/docs/_index.md && cp ../content/modeling/*.md dist/docs/topics/",
+    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin && cp -r src/templates dist/ && mkdir -p dist/docs/topics dist/docs/schemas && cp ../content/index.md dist/docs/_index.md && cp ../content/getting-started.md dist/docs/topics/ && cp ../content/modeling/*.md dist/docs/topics/",
     "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
     "test": "vitest run"
   },