@bonnard/cli 0.1.13 → 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

@@ -1,153 +1,12 @@
 # Getting Started
 
-> Set up Bonnard and build your first semantic layer in minutes.
+> 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.
 
-## Prerequisites
-
-- **Node.js 18+** — [Install Node.js](https://nodejs.org)
-- **A data warehouse** — PostgreSQL, Snowflake, BigQuery, or Databricks (or use our demo dataset)
-- **A Bonnard account** — [Sign up at app.bonnard.dev](https://app.bonnard.dev)
-
-## Install the CLI
-
-```bash
-npm install -g @bonnard/cli
-```
-
-Verify the installation:
-
-```bash
-bon --version
-```
-
-## Log in
-
-Authenticate with your Bonnard account:
-
-```bash
-bon login
-```
-
-This opens your browser to complete authentication. Once done, verify with:
-
-```bash
-bon whoami
-```
-
-## Initialize a project
-
-Navigate to your project directory and run:
-
-```bash
-bon init
-```
-
-This creates the project structure:
-
-```
-my-project/
-├── bon.yaml              # Project configuration
-├── bonnard/
-│   ├── cubes/            # Cube definitions (measures + dimensions)
-│   └── views/            # View definitions (curated interfaces)
-└── .bon/                 # Local config (gitignored)
-    └── datasources.yaml
-```
-
-If you have an existing dbt project, `bon init` will detect it and set up your agent context accordingly.
-
-## Connect a data source
-
-Add your warehouse connection:
-
-```bash
-bon datasource add
-```
-
-Follow the interactive prompts to configure your connection. If you use dbt, you can import from your profiles:
-
-```bash
-bon datasource add --from-dbt
-```
-
-**No warehouse yet?** Use our demo dataset — a read-only retail database (Contoso) with sales, products, stores, and customer data:
-
-```bash
-bon datasource add --demo
-```
-
-Test the connection:
-
-```bash
-bon datasource test contoso_demo
-```
-
-## Create your first cube
-
-Create a file at `bonnard/cubes/sales.yaml` (using the demo dataset — adapt table and column names to your own data):
-
-```yaml
-cubes:
-  - name: sales
-    sql_table: contoso.fact_sales
-    data_source: contoso_demo
-
-    measures:
-      - name: count
-        type: count
-
-      - name: total_revenue
-        type: sum
-        sql: sales_amount
-
-    dimensions:
-      - name: sales_key
-        type: number
-        sql: sales_key
-        primary_key: true
-
-      - name: date
-        type: time
-        sql: date_key
-
-      - name: sales_quantity
-        type: number
-        sql: sales_quantity
-```
-
-## Validate
-
-Check your cubes and views for errors:
-
-```bash
-bon validate
-```
-
-## Deploy
-
-Push your semantic layer to Bonnard:
-
-```bash
-bon deploy
-```
-
-## Query
-
-Test your deployed semantic layer:
-
-```bash
-bon query '{"measures": ["sales.count"]}'
-
-# With a dimension
-bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
-
-# Or use SQL format
-bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
-```
+<GettingStartedSteps />
 
 ## Next steps
 

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