@bonnard/cli 0.2.5 → 0.2.7

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

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

@@ -0,0 +1,125 @@
+# Validate
+
+> 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 and schema violations. Run this before deploying to catch issues early.
+
+## Usage
+
+```bash
+bon validate
+```
+
+## What Gets Validated
+
+### YAML Syntax
+
+- Valid YAML format
+- Proper indentation
+- Correct quoting
+
+### Schema Compliance
+
+- Required fields present (name, type, sql)
+- Valid field values (known measure types, relationship types)
+- Consistent naming conventions
+
+### Reference Integrity
+
+- Referenced cubes exist
+- Referenced members exist
+- Join relationships are valid
+
+## Example Output
+
+### Success
+
+```
+✓ Validating YAML syntax...
+✓ Checking bonnard/cubes/orders.yaml
+✓ Checking bonnard/cubes/users.yaml
+✓ Checking bonnard/views/orders_overview.yaml
+
+All cubes and views valid.
+```
+
+### Errors
+
+```
+✗ Validating YAML syntax...
+
+bonnard/cubes/orders.yaml:15:5
+  error: Unknown measure type "counts"
+
+  Did you mean "count"?
+
+  14:   measures:
+  15:     - name: order_count
+  16:       type: counts  <-- here
+  17:       sql: id
+
+1 error found.
+```
+
+## Common Errors
+
+### Missing Required Field
+
+```yaml
+# Error: "sql" is required
+measures:
+  - name: count
+    type: count
+    # Missing: sql: id
+```
+
+### Invalid Type
+
+```yaml
+# Error: Unknown dimension type "text"
+dimensions:
+  - name: status
+    type: text    # Should be: string
+    sql: status
+```
+
+### Reference Not Found
+
+```yaml
+# Error: Cube "user" not found (did you mean "users"?)
+joins:
+  - name: user
+    relationship: many_to_one
+    sql: "{CUBE}.user_id = {user.id}"
+```
+
+### YAML Syntax
+
+```yaml
+# Error: Bad indentation
+measures:
+- name: count  # Should be indented
+  type: count
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All validations passed |
+| 1 | Validation errors found |
+
+## Best Practices
+
+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** — connections are tested automatically during `bon deploy`
+
+## See Also
+
+- cli
+- cli.deploy
+- syntax

package/dist/docs/topics/cubes.data-source.md

@@ -89,4 +89,4 @@ Cubes from different data sources cannot be directly joined. Use views or pre-ag
 
 - cubes
 - cubes.sql
-- workflow.deploy
+- cli.deploy

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

@@ -12,5 +12,5 @@ Bonnard is a semantic layer platform that sits between your data warehouse and y
 
 - 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
+- Set up [MCP](/docs/querying/mcp) — connect AI agents to your semantic layer
+- Read the [CLI guide](/docs/cli) — validate, deploy, query

package/dist/docs/topics/governance.md

@@ -0,0 +1,83 @@
+# Governance
+
+> Control who can see which views, columns, and rows in your semantic layer.
+
+Bonnard provides admin-managed data governance — control which views, columns, and rows each group of users can access. Policies are configured in the web UI and enforced automatically across MCP queries and the API. Changes take effect within one minute.
+
+## How It Works
+
+```
+Admin configures in web UI:
+  Groups → Views → Field/Row restrictions
+
+Enforced automatically:
+  MCP queries + API → only see what policies allow
+```
+
+Governance uses **groups** as the unit of access. Each group has a set of **policies** that define which views its members can see, and optionally restrict specific columns or rows within those views.
+
+## Groups
+
+Groups represent teams or roles in your organization — "Sales Team", "Finance", "Executive". Create and manage groups from the **Governance** page in the Bonnard dashboard.
+
+Each group has:
+- **Name** and optional description
+- **Color** for visual identification
+- **View access** — which views the group can query
+- **Members** — which users belong to the group
+
+Users can belong to multiple groups. Their effective access is the **union** of all group policies.
+
+## View-Level Access (Level 1)
+
+The simplest control: toggle which views a group can see. Unchecked views are completely invisible to group members — they won't appear in `explore_schema` or be queryable.
+
+From the group detail page, check the views you want to grant access to and click **Save changes**. New policies default to "All fields" with no row filters.
+
+## Field-Level Access (Level 2)
+
+Fine-tune which measures and dimensions a group can see within a view. Click the gear icon on any granted view to open the fine-tune dialog.
+
+Three modes:
+- **All fields** — full access to every measure and dimension (default)
+- **Only these** — whitelist specific fields; everything else is hidden
+- **All except** — blacklist specific fields; everything else is visible
+
+Hidden fields are removed from the schema — they don't appear in `explore_schema` and can't be used in queries.
+
+## Row-Level Filters (Level 2)
+
+Restrict which rows a group can see. Add row filters in the fine-tune dialog to limit data by dimension values.
+
+For example, filter `traffic_source` to `equals B2B, Organic` so the group only sees rows where traffic_source is B2B or Organic. Multiple values in a single filter are OR'd (any match). Multiple separate filters are AND'd (all must match).
+
+Row filters are applied server-side on every query — users cannot bypass them.
+
+## Members
+
+Assign users to groups from the **Members** tab. Each user shows which groups they belong to and a preview of their effective access (which views they can query, any field or row restrictions).
+
+Users without any group assignment see nothing — they must be added to at least one group to query governed views.
+
+## How Policies Are Enforced
+
+Policies configured in the web UI are stored in Supabase and injected into the query engine at runtime. When a user queries via MCP or the API:
+
+1. Their JWT is enriched with group memberships
+2. The query engine loads policies for those groups
+3. View visibility, field restrictions, and row filters are applied automatically
+4. The user only sees data their policies allow
+
+No YAML changes are needed — governance is fully managed through the dashboard.
+
+## Best Practices
+
+1. **Start with broad access, then restrict** — give groups all views first, then fine-tune as needed
+2. **Use groups for teams, not individuals** — easier to manage and audit
+3. **Test with MCP** — after changing policies, query via MCP to verify the restrictions work as expected
+4. **Review after schema deploys** — new views need to be added to group policies to become visible
+
+## See Also
+
+- [querying.mcp](querying.mcp) — How AI agents query your semantic layer
+- [views](views) — Creating curated data views

package/dist/docs/topics/overview.md

@@ -0,0 +1,49 @@
+# Overview
+
+> Define your metrics once. Query governed data from any AI tool, dashboard, or application.
+
+Bonnard is a semantic layer platform. Your data team defines metrics once, and everyone else gets reliable answers from the AI tools they already use — Claude, ChatGPT, Cursor, Copilot — in whatever form they need. No new interface to learn.
+
+## Architecture
+
+```
+Data Warehouse → Cubes (metrics) → Views (interfaces) → Query Surfaces
+                                                          ├── MCP (AI agents)
+                                                          ├── REST API
+                                                          └── SDK (custom apps)
+```
+
+**Cubes** map to your database tables and define measures (revenue, count) and dimensions (status, date). **Views** compose cubes into focused interfaces for specific teams or use cases. Once deployed, your semantic layer is queryable through MCP, REST API, or the TypeScript SDK.
+
+## Multi-warehouse
+
+Connect any combination of warehouses through a single semantic layer:
+
+- **PostgreSQL** — Direct TCP connection
+- **Redshift** — Cluster or serverless endpoint
+- **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.
+
+## One source of truth for every AI
+
+Bonnard exposes your semantic layer as a remote MCP server. Add one URL to any MCP-compatible client — Claude, ChatGPT, Cursor, VS Code, Windsurf, Gemini — and it can explore your data model, run queries, and render charts. Every query is governed and scoped to the user's permissions automatically.
+
+## Governed by default
+
+Metrics are version-controlled and deployed from the terminal. Access, roles, and row-level security are managed by admins from the dashboard. Every query — whether from an AI agent, the API, or the SDK — is scoped to the user's permissions. No ungoverned access.
+
+## Your data stays where it is
+
+Your data stays in your warehouse. Bonnard adds a governed semantic layer on top — hosted, queryable, and managed. Each organization gets isolated query execution. Deploy from your terminal in minutes, not quarters.
+
+## Where to go next
+
+- **[Getting Started](/docs/getting-started)** — Install the CLI and build your first semantic layer
+- **[Modeling](/docs/modeling)** — Define cubes, views, and pre-aggregations
+- **[Querying](/docs/querying)** — Query via MCP, REST API, or SDK
+- **[CLI](/docs/cli)** — Commands, deployment, and validation
+- **[Governance](/docs/governance)** — Control access to views, columns, and rows
+- **[Catalog](/docs/catalog)** — Browse your data model in the browser

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

@@ -0,0 +1,200 @@
+# MCP
+
+> Connect AI agents like Claude, ChatGPT, and Cursor to your semantic layer using the Model Context Protocol. One URL, governed access to your metrics and dimensions.
+
+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)
+
+## MCP URL
+
+```
+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.
+
+## 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`
+
+## Setup
+
+### Claude Desktop
+
+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 — Add custom connector dialog](/images/claude-add-connector.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
+
+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)
+
+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)
+
+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 under **Enabled apps**:
+
+![ChatGPT — Bonnard MCP available in chat](/images/chatgpt-chat-apps.png)
+
+Available on Pro and Plus plans.
+
+### Cursor
+
+Open **Settings > MCP** and add the server URL, or add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "bonnard": {
+      "url": "https://mcp.bonnard.dev/mcp"
+    }
+  }
+}
+```
+
+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:
+
+```json
+{
+  "servers": {
+    "bonnard": {
+      "type": "http",
+      "url": "https://mcp.bonnard.dev/mcp"
+    }
+  }
+}
+```
+
+On first use, your browser will open to sign in and authorize the connection.
+
+### Claude Code
+
+Run in your terminal:
+
+```bash
+claude mcp add --transport http bonnard https://mcp.bonnard.dev/mcp
+```
+
+Or add to `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "bonnard": {
+      "type": "http",
+      "url": "https://mcp.bonnard.dev/mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+Open **Settings > Plugins > Manage plugins > View raw config**, or edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bonnard": {
+      "serverUrl": "https://mcp.bonnard.dev/mcp"
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `.gemini/settings.json` in your project or `~/.gemini/settings.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "bonnard": {
+      "url": "https://mcp.bonnard.dev/mcp"
+    }
+  }
+}
+```
+
+## Authentication
+
+MCP uses OAuth 2.0 with PKCE. When an agent first connects:
+
+1. Agent discovers OAuth endpoints automatically
+2. You are redirected to Bonnard to sign in and authorize
+3. Agent receives an access token (valid for 30 days)
+
+No API keys or manual token management needed.
+
+## Available Tools
+
+Once connected, AI agents can use these MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `explore_schema` | Discover views and cubes, list their measures, dimensions, and segments. Supports browsing a specific source by name or searching across all fields by keyword. |
+| `query` | Query the semantic layer with measures, dimensions, time dimensions, filters, segments, and pagination. |
+| `sql_query` | Execute raw SQL against the semantic layer using Cube SQL syntax with `MEASURE()` for aggregations. Use for CTEs, UNIONs, and custom calculations. |
+| `describe_field` | Get detailed metadata for a field — SQL expression, type, format, origin cube, and referenced fields. |
+| `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.
+
+## Testing
+
+```bash
+# Verify the MCP server is reachable
+bon mcp test
+
+# View connection info
+bon mcp
+```
+
+## Managing Connections
+
+Active MCP connections can be viewed and revoked in the Bonnard dashboard under **MCP**.
+
+## See Also
+
+- [querying.rest-api](querying.rest-api) — Query format reference
+- [querying.sdk](querying.sdk) — TypeScript SDK for custom apps
+- [cli.deploy](cli.deploy) — Deploy before querying

package/dist/docs/topics/querying.md

@@ -0,0 +1,11 @@
+# Querying
+
+> Once deployed, query your semantic layer three ways: MCP for AI agents, REST API for structured queries, and SDK for custom applications.
+
+Once your semantic layer is deployed, it's queryable through three interfaces:
+
+- **[MCP](querying.mcp)** — Connect AI agents like Claude, ChatGPT, and Cursor to explore and query your data model through the Model Context Protocol
+- **[REST API](querying.rest-api)** — Send JSON query objects or SQL strings for structured, programmatic access
+- **[SDK](querying.sdk)** — Build custom dashboards, embedded analytics, and data pipelines with the TypeScript client
+
+All three interfaces query the same governed semantic layer — same metrics, same access controls, same results.