@bonnard/cli 0.1.12 → 0.2.0

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

@@ -0,0 +1,60 @@
+# 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.
+
+## Key commands
+
+```bash
+bon init                          # Scaffold project + agent context
+bon datasource add --demo         # Add a demo warehouse instantly
+bon datasource add --from-dbt     # Import connections from dbt
+bon validate --test-connection    # Check YAML syntax + warehouse connectivity
+bon deploy -m "description"       # Ship to production (message required)
+bon query '{"measures":["orders.count"]}'  # Test your semantic layer
+bon preview <ds> "SELECT ..."     # Run raw SQL against a warehouse
+bon deployments                   # List deployment history
+bon diff <id>                     # View changes in a deployment
+bon annotate <id> --data '{...}'  # Add context to deployment changes
+bon mcp                           # Get MCP setup instructions
+bon docs cubes.measures           # Read modeling docs in terminal
+```
+
+## CI/CD ready
+
+Deploy from GitHub Actions, GitLab CI, or any pipeline:
+
+```bash
+bon deploy --ci --push-datasources -m "CI deploy"
+```
+
+Non-interactive mode with automatic datasource sync. 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.
+
+## See Also
+
+- [workflow.deploy](workflow.deploy) — Deployment details
+- [workflow.validate](workflow.validate) — Validation reference

package/dist/docs/topics/features.context-graph.md

@@ -0,0 +1,18 @@
+# Context Graph (Coming Soon)
+
+> Visualize how your metrics connect. Coming soon.
+
+The Business Context Graph will provide an interactive visual map of your entire semantic layer — cubes, views, joins, and field dependencies — so you can understand impact before making changes.
+
+## Planned capabilities
+
+- **Relationship visualization** — See how cubes connect through joins and shared dimensions
+- **Impact analysis** — Understand which views and measures are affected when you change a cube
+- **Field lineage** — Trace any metric back through its dependencies to the source table
+- **Search and filter** — Navigate large models by searching for specific fields or cubes
+
+## Why it matters
+
+As your semantic layer grows, understanding the relationships between dozens of cubes and hundreds of fields becomes critical. The Context Graph gives your team a shared mental model of how metrics are defined and connected — reducing errors and speeding up development.
+
+Interested in early access? Reach out at [hello@bonnard.dev](mailto:hello@bonnard.dev).

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

@@ -0,0 +1,84 @@
+# Governance
+
+> User and group-level permissions for your semantic layer.
+
+Bonnard supports declarative data access policies — define who can see which rows, columns, and views directly in your YAML models. No application code, no database-level workarounds.
+
+## Row-level security
+
+Filter data based on user attributes. A sales manager only sees their region's data:
+
+```yaml
+cubes:
+  - name: orders
+    access_policy:
+      - role: sales_manager
+        row_level:
+          filters:
+            - member: region
+              operator: equals
+              values: ["{ securityContext.region }"]
+```
+
+Every query from that user automatically includes the filter — no way to bypass it.
+
+## Member-level security
+
+Control which measures and dimensions each role can access. Hide sensitive fields from non-privileged users:
+
+```yaml
+cubes:
+  - name: orders
+    access_policy:
+      - role: analyst
+        member_level:
+          includes:
+            - count
+            - total_revenue
+            - status
+            - created_at
+
+      - role: admin
+        member_level:
+          includes: "*"
+```
+
+Roles without a matching policy see nothing.
+
+## View-based governance
+
+Keep cubes private. Expose only curated views to consumers:
+
+```yaml
+cubes:
+  - name: raw_orders
+    public: false
+
+views:
+  - name: sales_overview
+    public: true
+    cubes:
+      - join_path: raw_orders
+        includes:
+          - revenue
+          - order_count
+          - status
+```
+
+Business users, AI agents, and SDK consumers only see the views you choose to expose — with clean names and descriptions.
+
+## Dynamic visibility
+
+Use context variables to show or hide entire cubes based on the user's role:
+
+```yaml
+cubes:
+  - name: executive_metrics
+    public: "{{ 'true' if COMPILE_CONTEXT.role == 'executive' else 'false' }}"
+```
+
+## See Also
+
+- [cubes.public](cubes.public) — Visibility controls reference
+- [views](views) — Creating curated data views
+- [syntax.context-variables](syntax.context-variables) — Context variable reference

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

@@ -0,0 +1,48 @@
+# MCP
+
+> Connect your preferred AI agent to your semantic layer.
+
+Bonnard exposes your semantic layer as a remote MCP server. Add one URL to your agent platform and it can explore your data model, run queries, and render charts — all through the Model Context Protocol.
+
+![MCP chat with visualisations](/images/mcp-chat-demo.gif)
+
+## Connect your agent
+
+Bonnard works with any MCP-compatible client:
+
+- **Claude Desktop** — Add as a custom connector
+- **ChatGPT** — Add via Settings > Apps (Pro/Plus)
+- **Cursor** — Add via Settings > MCP or `.cursor/mcp.json`
+- **Microsoft Copilot Studio** — Add as an MCP tool with OAuth 2.0 authentication
+- **VS Code / GitHub Copilot** — Add via Command Palette or `.vscode/mcp.json`
+- **Claude Code** — Add via `claude mcp add` or `.mcp.json`
+- **Windsurf** — Add via MCP config
+- **Gemini CLI** — Add via `.gemini/settings.json`
+
+One URL for all of them:
+
+```
+https://mcp.bonnard.dev/mcp
+```
+
+On first use, your browser opens to sign in — the agent receives a 30-day token automatically. No API keys, no config files, no secrets to rotate.
+
+## Tools your agent gets
+
+| Tool | What it does |
+|------|-------------|
+| `explore_schema` | Browse cubes, views, and fields — or search by keyword |
+| `query` | Run structured queries with measures, dimensions, filters, and time grouping |
+| `sql_query` | Execute raw SQL for complex analysis (CTEs, UNIONs, custom calculations) |
+| `describe_field` | Inspect any field's SQL definition, type, format, and dependencies |
+| `visualize` | Render line, bar, pie, and KPI charts directly inside the conversation |
+
+## Charts in chat
+
+The `visualize` tool renders interactive charts inline — auto-detected from your query shape. Charts support dark mode, currency and percentage formatting, and multi-series data.
+
+Ask "show me revenue by region this quarter" and get a formatted chart in your conversation, not a data dump.
+
+## See Also
+
+- [workflow.mcp](workflow.mcp) — Step-by-step setup for each platform

package/dist/docs/topics/features.md

@@ -0,0 +1,15 @@
+# Features
+
+> Everything you need to define, deploy, and query your semantic layer.
+
+Bonnard is a semantic layer platform built for AI-first analytics. Define your metrics once in YAML, deploy in seconds, and query from anywhere — your IDE, your AI agent, or your own apps.
+
+- **[MCP](features.mcp)** — Connect your preferred AI agent to your semantic layer
+- **[CLI](features.cli)** — Agent-first development workflow for data engineers
+- **[Semantic Layer](features.semantic-layer)** — Hosted, queryable metrics layer across all your warehouses
+- **[Catalog](features.catalog)** — Browse and understand your data model from the browser
+- **[SDK](features.sdk)** — Build custom data apps on top of Bonnard
+- **[Governance](features.governance)** — User and group-level permissions for your data
+- **[Context Graph](features.context-graph)** — Visual map of how your metrics connect (coming soon)
+- **[Slack & Teams](features.slack-teams)** — AI agents in your team chat (coming soon)
+- **[Deployment Versioning](workflow.deploy)** — Change detection, diff, and annotations for every deploy

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

@@ -0,0 +1,53 @@
+# SDK
+
+> Build custom data apps on top of your semantic layer.
+
+The Bonnard SDK (`@bonnard/sdk`) is a lightweight TypeScript client for querying your deployed semantic layer programmatically. Build dashboards, embedded analytics, internal tools, or data pipelines — all backed by your governed metrics.
+
+## Quick start
+
+```bash
+npm install @bonnard/sdk
+```
+
+```typescript
+import { createClient } from '@bonnard/sdk';
+
+const bonnard = createClient({
+  apiKey: 'your-api-key',
+});
+
+const result = await bonnard.query({
+  cube: 'orders',
+  measures: ['revenue', 'count'],
+  dimensions: ['status'],
+  timeDimension: {
+    dimension: 'created_at',
+    granularity: 'month',
+    dateRange: ['2025-01-01', '2025-12-31'],
+  },
+});
+```
+
+## Type-safe queries
+
+Full TypeScript support with inference. Measures, dimensions, filters, time dimensions, and sort orders are all typed. Query results include field annotations with titles and types.
+
+```typescript
+const result = await bonnard.sql<OrderRow>(
+  `SELECT status, MEASURE(revenue) FROM orders GROUP BY 1`
+);
+// result.data is OrderRow[]
+```
+
+## What you can build
+
+- **Custom dashboards** — Query your semantic layer from Next.js, React, or any frontend
+- **Embedded analytics** — Add governed metrics to your product
+- **Data pipelines** — Consume semantic layer data in ETL workflows
+- **Internal tools** — Build admin panels backed by consistent metrics
+
+## See Also
+
+- [features.semantic-layer](features.semantic-layer) — Platform overview
+- [workflow.query](workflow.query) — Query format reference

package/dist/docs/topics/features.semantic-layer.md

@@ -0,0 +1,50 @@
+# Semantic Layer
+
+> Define metrics once. Query from anywhere.
+
+Bonnard hosts your semantic layer so you don't have to. Define cubes and views in YAML, deploy with `bon deploy`, and query via JSON API, SQL, or MCP — no infrastructure to manage.
+
+## Multi-warehouse
+
+Connect any combination of warehouses through a single semantic layer:
+
+- **PostgreSQL** — Direct TCP connection
+- **Snowflake** — Account-based authentication
+- **BigQuery** — GCP service account
+- **Databricks** — Token-based workspace connection
+
+Metrics from different warehouses are queried through the same API. Your consumers never need to know where the data lives.
+
+## Two query formats
+
+**JSON API** — Structured queries with type-safe parameters:
+
+```bash
+bon query '{
+  "measures": ["orders.revenue"],
+  "dimensions": ["orders.status"],
+  "timeDimensions": [{
+    "dimension": "orders.created_at",
+    "granularity": "month",
+    "dateRange": ["2025-01-01", "2025-12-31"]
+  }]
+}'
+```
+
+**SQL** — Full Cube SQL syntax for complex analysis:
+
+```bash
+bon query --sql "SELECT status, MEASURE(revenue) FROM orders GROUP BY 1"
+```
+
+## Fully managed
+
+Your models are stored securely and served from Bonnard's infrastructure. Each organization gets isolated query execution scoped by JWT — no shared data, no noisy neighbors.
+
+Deploy in seconds. Query in milliseconds.
+
+## See Also
+
+- [workflow.query](workflow.query) — Query format reference
+- [cubes](cubes) — Cube modeling guide
+- [views](views) — View modeling guide

package/dist/docs/topics/features.slack-teams.md

@@ -0,0 +1,18 @@
+# Slack & Teams (Coming Soon)
+
+> AI agents in your team chat. Coming soon.
+
+Bonnard will bring semantic layer queries directly into Slack and Microsoft Teams — so anyone on your team can ask questions about data without leaving the conversation.
+
+## Planned capabilities
+
+- **Natural language queries** — Ask "what was revenue last month?" in a channel and get an answer with a chart
+- **Governed responses** — Every answer goes through your semantic layer, so metrics are always consistent
+- **Shared context** — Results posted in channels are visible to the whole team, not siloed in individual AI chats
+- **Proactive alerts** — Get notified when key metrics change beyond thresholds you define
+
+## Why it matters
+
+Your team already lives in Slack and Teams. Instead of asking analysts or switching to a BI tool, anyone can get instant, governed answers right where they work. The same semantic layer that powers your AI agents and dashboards powers your team chat.
+
+Interested in early access? Reach out at [hello@bonnard.dev](mailto:hello@bonnard.dev).

package/dist/docs/topics/getting-started.md

@@ -0,0 +1,16 @@
+# Getting Started
+
+> Install the Bonnard CLI, connect your data warehouse, and define your first semantic layer with cubes and views in under five minutes.
+
+## What is Bonnard?
+
+Bonnard is a semantic layer platform that sits between your data warehouse and your consumers (BI tools, AI agents, applications). You define your metrics and dimensions once in YAML, then query them through a consistent API.
+
+<GettingStartedSteps />
+
+## Next steps
+
+- Learn about [cubes](/docs/modeling/cubes) — measures, dimensions, joins
+- Learn about [views](/docs/modeling/views) — curated interfaces for consumers
+- Set up [MCP](/docs/workflow/mcp) — connect AI agents to your semantic layer
+- Read the full [workflow guide](/docs/workflow) — validate, deploy, query

package/dist/docs/topics/pre-aggregations.md

@@ -1,6 +1,6 @@
-# pre-aggregations
+# Pre-Aggregations
 
-> Materialize query results for faster analytics performance.
+> Pre-aggregations materialize query results into summary tables for faster analytics performance. Define rollups to speed up dashboards, AI agent queries, and API responses.
 
 ## Overview
 

package/dist/docs/topics/pre-aggregations.rollup.md

@@ -1,6 +1,6 @@
-# pre-aggregations.rollup
+# Rollups
 
-> Create summarized data tables for high-performance queries.
+> Rollups are pre-aggregation tables that store summarized data for high-performance queries. Define which measures and dimensions to materialize, and Bonnard generates and refreshes them automatically.
 
 ## Overview
 

package/dist/docs/topics/syntax.context-variables.md

@@ -1,6 +1,6 @@
-# syntax.context-variables
+# Context Variables
 
-> Access runtime context in SQL expressions.
+> Context variables give you access to runtime information inside SQL expressions. Use them to implement row-level security, multi-tenancy, dynamic date ranges, and environment-specific logic.
 
 ## Overview
 

package/dist/docs/topics/syntax.md

@@ -1,6 +1,6 @@
-# syntax
+# Syntax
 
-> YAML syntax and conventions for cubes and views.
+> YAML syntax reference for defining cubes and views in Bonnard. Covers naming conventions, property formats, SQL expressions, Jinja templating, and member references.
 
 ## Overview
 

package/dist/docs/topics/syntax.references.md

@@ -1,6 +1,6 @@
-# syntax.references
+# References
 
-> Reference columns, members, and other cubes in SQL expressions.
+> References let you point to columns, measures, dimensions, and other cubes inside SQL expressions. Use curly-brace syntax to create type-safe, refactor-friendly cross-cube references.
 
 ## Overview
 

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

@@ -1,6 +1,6 @@
-# views.cubes
+# View Cubes
 
-> Select which cubes and members to expose in a view.
+> The cubes property in a view selects which cubes and members to expose. Pick specific measures and dimensions from multiple cubes to create focused, consumer-ready interfaces.
 
 ## Overview
 

package/dist/docs/topics/views.folders.md

@@ -1,6 +1,6 @@
-# views.folders
+# View Folders
 
-> Organize view members into logical groups.
+> Folders organize a view's measures and dimensions into logical groups. Use folders to structure large views so consumers can navigate fields by category instead of a flat list.
 
 ## Overview
 

package/dist/docs/topics/views.includes.md

@@ -1,6 +1,6 @@
-# views.includes
+# View Includes
 
-> Control which cube members appear in a view.
+> The includes and excludes properties control which cube members appear in a view. Include everything from a cube and selectively exclude fields, or cherry-pick specific members.
 
 ## Overview
 

package/dist/docs/topics/views.md

@@ -1,6 +1,6 @@
-# views
+# Views
 
-> Compose cubes into focused interfaces for specific use cases.
+> Views compose measures and dimensions from multiple cubes into focused, consumer-friendly interfaces. Use views to expose curated data to BI tools, AI agents, and applications.
 
 ## Overview
 

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