@bonnard/cli 0.2.7 → 0.2.9

package/dist/docs/topics/dashboards.md

@@ -1,10 +1,12 @@
-# dashboards
+# Dashboards
 
 > Build interactive dashboards from markdown with embedded semantic layer queries.
 
 ## Overview
 
-Dashboards are markdown files with YAML frontmatter, query blocks, and chart components. Write them as `.md` files, deploy with `bon dashboard deploy`, and view them in the Bonnard web app.
+Dashboards let your team track key metrics without leaving the Bonnard app. Define queries once in markdown, deploy them, and every viewer gets live, governed data — no separate BI tool needed. Filters, formatting, and layout are all declared in the same file.
+
+A dashboard is a markdown file with YAML frontmatter, query blocks, and chart components. Write it as a `.md` file, deploy with `bon dashboard deploy`, and view it in the Bonnard web app.
 
 ## Format
 
@@ -60,6 +62,8 @@ slug: revenue-dashboard         # Optional (derived from title if omitted)
 
 ## Deployment
 
+Deploy from the command line or via MCP tools. Each deploy auto-versions the dashboard so you can roll back if needed.
+
 ```bash
 # Deploy a single dashboard
 bon dashboard deploy revenue.md
@@ -76,8 +80,38 @@ bon dashboard remove revenue-dashboard
 
 Via MCP tools, agents can use `deploy_dashboard` with the markdown content as a string.
 
+## Versioning
+
+Every deployment auto-increments the version number and saves a snapshot. You can view version history and restore previous versions:
+
+```bash
+# Via MCP tools:
+# get_dashboard with version parameter to fetch a specific version
+# deploy_dashboard with slug + restore_version to roll back
+```
+
+Restoring a version creates a new version (e.g. restoring v2 from v5 creates v6 with v2's content). Version history is never deleted — only `remove_dashboard` deletes all history.
+
+## Sharing
+
+Dashboard viewers include a **Share** menu in the header with:
+
+- **Copy link** — copies the current URL including any active filter state
+- **Print to PDF** — opens the browser print dialog for PDF export
+
+Filter state (DateRange presets, Dropdown selections) is encoded in URL query params, so shared links preserve the exact filtered view the sender was looking at.
+
+## Governance
+
+Dashboard queries respect the same governance policies as all other queries. When a user views a dashboard:
+
+- **View-level access** — users only see data from views their governance groups allow
+- **Row-level filtering** — user attributes (e.g. region, department) automatically filter query results
+- All org members see the same dashboard list, but may see different data depending on their governance context
+
 ## See Also
 
-- dashboards.queries
-- dashboards.components
-- dashboards.examples
+- [Queries](dashboards.queries) — query syntax and properties
+- [Components](dashboards.components) — chart and display components
+- [Inputs](dashboards.inputs) — interactive filters
+- [Examples](dashboards.examples) — complete dashboard examples

package/dist/docs/topics/dashboards.queries.md

@@ -1,10 +1,12 @@
-# dashboards.queries
+# Queries
 
 > Define data queries in dashboard markdown using YAML code fences.
 
 ## Overview
 
-Query blocks fetch data from the semantic layer. Each query has a unique name and maps to a `QueryOptions` shape. Query results are referenced by chart components using `data={query_name}`.
+Each query fetches data from your semantic layer and makes it available to chart components. Queries use the same measures and dimensions defined in your cubes and views — field names stay consistent whether you're querying from a dashboard, MCP, or the API.
+
+Query blocks have a unique name and map to a `QueryOptions` shape. Components reference them using `data={query_name}`. Field names are unqualified — use `count` not `orders.count` — because the `cube` property provides the context.
 
 ## Syntax
 
@@ -112,6 +114,6 @@ filters:
 
 ## See Also
 
-- dashboards.components
-- dashboards
-- workflow.query
+- [Components](dashboards.components) — chart and display components
+- [Dashboards](dashboards) — overview and deployment
+- [Querying](querying) — query format reference

package/dist/docs/topics/views.md

@@ -6,7 +6,7 @@
 
 Views are facades that expose selected measures and dimensions from one or more cubes. They define which data is available to consumers, control join paths, and organize members into logical groups.
 
-**Views should represent how a team thinks about data**, not mirror your warehouse tables. Name views by what they answer (`sales_pipeline`, `customer_insights`) rather than what table they wrap (`orders_view`, `users_view`). A good semantic layer has 5-10 focused views, not 30+ thin wrappers.
+**Views should represent how a team thinks about data**, not mirror your warehouse tables. Name views by what they answer (`sales_pipeline`, `customer_insights`) rather than what table they wrap (`orders_view`, `users_view`). Build as many views as your audiences need, but make each one purposeful — governance policies control which views each user or role can access.
 
 ## Example
 

package/dist/templates/claude/skills/bonnard-design-guide/SKILL.md

@@ -30,10 +30,11 @@ If you have a BI tool (Metabase, Looker, Tableau), your top dashboards
 by view count are the best source of real questions. If not, ask each team:
 "What 3 numbers do you check every week?"
 
-**Why this matters:** A semantic layer built from questions has 5-10 focused
-views. One built from tables has 30+ views that agents struggle to choose
-between. Fewer, well-scoped views with clear descriptions outperform
-comprehensive but undifferentiated coverage.
+**Why this matters:** A semantic layer built from questions produces focused,
+audience-scoped views. One built from tables produces generic views that agents
+struggle to choose between. Governance policies control which views each user
+or role can access, so build as many views as your audiences need — but make
+each one purposeful with clear descriptions.
 
 ## Principle 2: Views Are for Audiences, Not Tables
 

package/dist/templates/cursor/rules/bonnard-design-guide.mdc

@@ -29,10 +29,11 @@ If you have a BI tool (Metabase, Looker, Tableau), your top dashboards
 by view count are the best source of real questions. If not, ask each team:
 "What 3 numbers do you check every week?"
 
-**Why this matters:** A semantic layer built from questions has 5-10 focused
-views. One built from tables has 30+ views that agents struggle to choose
-between. Fewer, well-scoped views with clear descriptions outperform
-comprehensive but undifferentiated coverage.
+**Why this matters:** A semantic layer built from questions produces focused,
+audience-scoped views. One built from tables produces generic views that agents
+struggle to choose between. Governance policies control which views each user
+or role can access, so build as many views as your audiences need — but make
+each one purposeful with clear descriptions.
 
 ## Principle 2: Views Are for Audiences, Not Tables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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/overview.md ../content/getting-started.md dist/docs/topics/ && 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/overview.md ./content/getting-started.md dist/docs/topics/ && cp ./content/modeling/*.md dist/docs/topics/ && cp ./content/dashboards/*.md dist/docs/topics/",
     "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
     "test": "vitest run"
   },
@@ -27,6 +27,11 @@
     "tsdown": "^0.20.1",
     "vitest": "^2.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meal-inc/bonnard-cli.git"
+  },
+  "license": "MIT",
   "engines": {
     "node": ">=20.0.0"
   }

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

@@ -1,31 +0,0 @@
-# Catalog
-
-> Browse and understand your data model — no code required.
-
-The Bonnard catalog gives everyone on your team a live view of your semantic layer. Browse cubes, views, measures, and dimensions from the browser. Understand what data is available before writing a single query.
-
-## What you can explore
-
-- **Cubes and Views** — See every deployed source with field counts at a glance
-- **Measures** — Aggregation type, SQL expression, format (currency, percentage), and description
-- **Dimensions** — Data type, time granularity options, and custom metadata
-- **Segments** — Pre-defined filters available for queries
-
-## Field-level detail
-
-Click any field to see exactly how it's calculated:
-
-- **SQL expression** — The underlying query logic
-- **Type and format** — How the field is aggregated and displayed
-- **Origin cube** — Which cube a view field traces back to
-- **Referenced fields** — Dependencies this field relies on
-- **Custom metadata** — Tags, labels, and annotations set by your data team
-
-## Built for business users
-
-The catalog is designed for anyone who needs to understand the data, not just engineers. No YAML, no terminal, no warehouse credentials. Browse the schema, read descriptions, and know exactly what to ask your AI agent for.
-
-## See Also
-
-- [views](views) — How to create curated views for your team
-- [cubes.public](cubes.public) — Control which cubes are visible

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

@@ -1,59 +0,0 @@
-# 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                      # Check YAML syntax
-bon deploy -m "description"       # Ship to production (message required)
-bon query '{"measures":["orders.count"]}'  # Test your semantic layer
-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 -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.
-
-## See Also
-
-- [workflow.deploy](workflow.deploy) — Deployment details
-- [workflow.validate](workflow.validate) — Validation reference

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

@@ -1,18 +0,0 @@
-# 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

@@ -1,83 +0,0 @@
-# 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
-
-- [features.mcp](features.mcp) — How AI agents query your semantic layer
-- [views](views) — Creating curated data views

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

@@ -1,48 +0,0 @@
-# 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

@@ -1,15 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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
-- **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.
-
-## 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.
-
-## Built for AI agents
-
-Views and descriptions are the discovery API for AI agents. When an agent calls `explore_schema`, it sees view names and descriptions — that's all it has to decide where to query. Well-written descriptions with scope, disambiguation, and dimension values make agents accurate. See the design guide principles in the CLI (`/bonnard-design-guide`) for details.
-
-## See Also
-
-- [workflow.query](workflow.query) — Query format reference
-- [cubes](cubes) — Cube modeling guide
-- [views](views) — View modeling guide
-- [features.governance](features.governance) — Access control for views and data

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

@@ -1,18 +0,0 @@
-# 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).