@bonnard/cli 0.2.4 → 0.2.5

package/dist/templates/cursor/rules/bonnard-get-started.mdc

@@ -40,9 +40,13 @@ The connection will be tested automatically during `bon deploy`.
 
 Before creating cubes, understand what tables and columns are available in your warehouse.
 
+**Important:** `bon query` is for querying the **deployed semantic layer** — it does NOT
+access your database directly. Use your warehouse's native tools to explore tables.
+
 **Options for exploring your data:**
-- Use your database IDE or CLI (e.g., `psql`, Snowflake web UI, BigQuery console) to browse tables
+- Use your database CLI (e.g., `psql` for Postgres/Redshift, `snowsql` for Snowflake, `bq` for BigQuery) to list tables and columns
 - Check your dbt docs or existing documentation for table schemas
+- Ask the user for table names and column details if you don't have direct database access
 - For the demo dataset, the tables are: `contoso.fact_sales`, `contoso.dim_product`, `contoso.dim_store`, `contoso.dim_customer`
 
 Note the table names, column names, and data types — you'll use these in Phase 3.
@@ -78,6 +82,15 @@ cubes:
         sql: total_cost
         description: Sum of product costs
 
+      # Filtered measures — match what users actually see on dashboards
+      - name: return_count
+        type: count
+        description: >-
+          Sales transactions with returns only (return_quantity > 0).
+          For all transactions, use count.
+        filters:
+          - sql: "{CUBE}.return_quantity > 0"
+
     dimensions:
       - name: sales_key
         type: number
@@ -96,8 +109,11 @@ cubes:
 ```
 
 Key rules:
-- Every cube needs a `primary_key` dimension
-- Every measure and dimension should have a `description`
+- Every cube needs a `primary_key` dimension — **it must be unique**. If no column is naturally unique, use `sql` with `ROW_NUMBER()` instead of `sql_table` and add a synthetic key. Non-unique PKs cause dimension queries to silently return empty results.
+- Every measure and dimension should have a `description` — descriptions are how AI agents discover and choose metrics (see `bonnard-design-guide` rule)
+- **Add filtered measures** for any metric users track with filters (e.g., "online revenue" vs "total revenue"). If a dashboard card has a WHERE clause beyond a date range, that filter should be a filtered measure.
+- Measure descriptions should say what's **included and excluded** — e.g., "Online channel only. For all channels, use total_revenue."
+- Dimension descriptions should include **example values** for categorical fields — e.g., "Sales channel (values: Online, Store, Reseller)"
 - Set `data_source` to match the datasource name from Phase 1
 - Use `sql_table` with the full `schema.table` path
 - Use `sql_table` for simple table references, `sql` for complex queries
@@ -107,26 +123,38 @@ for all 12 measure types, `bon docs cubes.dimensions.types` for dimension types.
 
 ## Phase 4: Create a View
 
-Views expose a curated subset of measures and dimensions for consumers.
-Create a file in `bonnard/views/` that references the cube from Phase 3.
+Views expose a curated subset of measures and dimensions for specific
+audiences. **Name views by what they answer** (e.g., `sales_performance`),
+not by what table they wrap (e.g., `sales_view`). A view can combine
+measures and dimensions from multiple cubes via `join_path`.
 
-Example using demo data — `bonnard/views/sales_overview.yaml`:
+The view **description** is critical — it's how AI agents decide which view
+to query. It should answer: what's in here, when to use it, and when to
+use something else instead. Include key dimension values where helpful.
+
+Example using demo data — `bonnard/views/sales_performance.yaml`:
 
 ```yaml
 views:
-  - name: sales_overview
-    description: High-level sales metrics and attributes
+  - name: sales_performance
+    description: >-
+      Retail sales metrics — revenue, cost, and transaction counts by product,
+      store, and date. Default view for sales questions. Includes return_count
+      for return analysis. For customer demographics, use customer_insights
+      instead.
     cubes:
       - join_path: sales
         includes:
           - count
           - total_revenue
+          - return_count
           - total_cost
           - date
           - sales_quantity
 ```
 
-Use `bon docs views` for the full reference.
+Use `bon docs views` for the full reference. See the `bonnard-design-guide`
+rule for principles on naming, descriptions, and view structure.
 
 ## Phase 5: Validate
 
@@ -162,21 +190,26 @@ 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
+## Phase 7: Test with Queries
 
-Verify the deployment works using the cube name from Phase 3:
+Verify the deployment works using the **view name** from Phase 4:
 
 ```bash
 # Simple count
-bon query '{"measures": ["sales.count"]}'
+bon query '{"measures": ["sales_performance.count"]}'
 
 # With a dimension
-bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
+bon query '{"measures": ["sales_performance.total_revenue"], "dimensions": ["sales_performance.date"]}'
 
 # SQL format
-bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
+bon query --sql "SELECT MEASURE(total_revenue) FROM sales_performance"
 ```
 
+**Test with natural language too.** If you've set up MCP (Phase 8), ask
+an AI agent questions like "what's our total revenue?" and check whether
+it picks the right view and measure. If it picks the wrong view, the issue
+is usually the view description — see the `bonnard-design-guide` rule.
+
 ## Phase 8: Connect AI Agents (Optional)
 
 Set up MCP so AI agents can query the semantic layer:
@@ -192,8 +225,9 @@ and other MCP clients. The MCP URL is `https://mcp.bonnard.dev/mcp`.
 
 After the first cube is working:
 
+- **Iterate on descriptions** — test with real questions via MCP, fix agent mistakes by improving view descriptions and adding filtered measures (see `bonnard-design-guide` rule)
 - Add more cubes for other tables
 - Add joins between cubes (`bon docs cubes.joins`)
+- Build audience-centric views that combine multiple cubes — e.g., a `management` view that pulls from `sales`, `users`, and `products` cubes
 - Add calculated measures (`bon docs cubes.measures.calculated`)
 - Add segments for common filters (`bon docs cubes.segments`)
-- Build dashboards (`bon docs dashboards`)

package/dist/templates/cursor/rules/bonnard-metabase-migrate.mdc

@@ -121,11 +121,12 @@ highest-referenced table and work down. Create one file per cube in
 For each cube:
 1. Set `sql_table` to the full `schema.table` path
 2. Set `data_source` to the datasource name from Phase 3
-3. Add a `primary_key` dimension
+3. Add a `primary_key` dimension — **must be unique**. If no column is naturally unique, use `sql` with `ROW_NUMBER()` instead of `sql_table` and add a synthetic key
 4. Add time dimensions for date/datetime columns
 5. Add measures based on card SQL patterns (Phase 4)
-6. Add dimensions for columns used as filters (template vars from Phase 2)
-7. Add `description` to every measure and dimension
+6. **Add filtered measures** for every card with a WHERE clause beyond date range — e.g., "active offers" (status != cancelled). This is the #1 way to match dashboard numbers.
+7. Add dimensions for columns used as filters (template vars from Phase 2)
+8. Add `description` to every measure and dimension — descriptions should say what's **included and excluded**. Dimension descriptions should include **example values** for categorical fields.
 
 Example — `bonnard/cubes/orders.yaml`:
 
@@ -180,15 +181,26 @@ Use `bon docs cubes.joins` for the full reference.
 
 Map Metabase collections to views. Each top-level collection (business domain)
 from the analysis report becomes a view that composes the relevant cubes.
+**Name views by what they answer** (e.g., `sales_pipeline`), not by what
+table they wrap (e.g., `orders_view`).
 
 Create one file per view in `bonnard/views/`.
 
+The view **description** is critical — it's how AI agents decide which view
+to query. It should answer: what's in here, when to use it, and when to use
+something else instead. Cross-reference related views to prevent agents from
+picking the wrong one.
+
 Example — `bonnard/views/sales_analytics.yaml`:
 
 ```yaml
 views:
   - name: sales_analytics
-    description: Sales metrics and dimensions for the sales team
+    description: >-
+      Sales team view — order revenue, counts, and status breakdowns with
+      customer region. Default view for revenue and order questions. Use the
+      status dimension (values: pending, completed, cancelled) to filter.
+      For customer-level analysis, use customer_insights instead.
     cubes:
       - join_path: orders
         includes:
@@ -204,7 +216,8 @@ views:
           - region
 ```
 
-Use `bon docs views` for the full reference.
+Use `bon docs views` for the full reference. See the `bonnard-design-guide`
+rule for principles on view naming, descriptions, and structure.
 
 ## Phase 7: Validate and Deploy
 
@@ -235,23 +248,29 @@ equivalent queries:
 
 ```bash
 # Run a semantic layer query
-bon query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
+bon query '{"measures": ["sales_analytics.total_revenue"], "dimensions": ["sales_analytics.status"]}'
 
 # SQL format
-bon query --sql "SELECT status, MEASURE(total_revenue) FROM orders GROUP BY 1"
+bon query --sql "SELECT status, MEASURE(total_revenue) FROM sales_analytics GROUP BY 1"
 ```
 
 Compare the numbers with the corresponding Metabase card. If they don't match:
 - Check the SQL in the card (`bon metabase explore card <id>`) for filters or transformations
 - Ensure the measure type matches the aggregation (SUM vs COUNT vs AVG)
-- Check for WHERE clauses that should be segments or pre-filters
+- Check for WHERE clauses that should be filtered measures (not segments)
+
+**Test with natural language too.** Set up MCP (`bon mcp`) and ask an agent
+the same questions your Metabase dashboards answer. Check whether it picks
+the right **view** and **measure** — most failures are description problems,
+not data problems. See the `bonnard-design-guide` rule for Principle 6.
 
 ## Next Steps
 
 After the core migration is working:
 
+- **Iterate on descriptions** — test with real questions via MCP, fix agent mistakes by improving view descriptions and adding filtered measures (see `bonnard-design-guide` rule)
 - Add remaining tables as cubes (work down the reference count list)
+- Build audience-centric views that combine multiple cubes — match how Metabase collections organize data by business domain
 - Add calculated measures for complex card SQL (`bon docs cubes.measures.calculated`)
-- Add segments for common WHERE clauses (`bon docs cubes.segments`)
 - Set up MCP for AI agent access (`bon mcp`)
 - Review and iterate with `bon deployments` and `bon diff <id>`

package/dist/templates/shared/bonnard.md

@@ -48,9 +48,10 @@ bon datasource add --demo
 ```
 
 This adds a read-only **Contoso** retail database (Postgres) with tables:
-- `fact_sales` — transactions with sales_amount, unit_price, sales_quantity, date_key
+- `fact_sales` — transactions with sales_amount, total_cost, sales_quantity, return_quantity, return_amount, discount_amount, date_key, channel_key, store_key, product_key
 - `dim_product` — product_name, brand_name, manufacturer, unit_cost, unit_price
-- `dim_store` — store_name, store_type, employee_count, selling_area_size
+- `dim_store` — store_name, store_type, employee_count, selling_area_size, status
+- `dim_channel` — channel_name (values: Store, Online, Catalog, Reseller)
 - `dim_customer` — first_name, last_name, gender, yearly_income, education, occupation
 
 All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
@@ -69,7 +70,7 @@ All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
 | `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 query '{...}'` | Query the deployed semantic layer (requires `bon deploy` first, not for raw DB access) |
 | `bon mcp` | Show MCP setup instructions for AI agents |
 | `bon docs` | Browse documentation |
 | `bon metabase connect` | Connect to a Metabase instance (API key) |
@@ -96,15 +97,19 @@ Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to
 
 ## Workflow
 
-1. **Setup datasource** — `bon datasource add --from-dbt` or manual
-2. **Create cubes** — Define measures/dimensions in `bonnard/cubes/*.yaml`
-3. **Create views** — Compose cubes in `bonnard/views/*.yaml`
-4. **Validate** — `bon validate`
-5. **Deploy** — `bon login` then `bon deploy -m "description of changes"`
-6. **Review** — `bon deployments` to list, `bon diff <id>` to inspect changes
+1. **Start from questions** — Collect the most common questions your team asks about data. Group them by audience.
+2. **Setup datasource** — `bon datasource add --from-dbt` or manual
+3. **Create cubes** — Define measures/dimensions in `bonnard/cubes/*.yaml`. Add filtered measures for any metric with a WHERE clause.
+4. **Create views** — Compose cubes in `bonnard/views/*.yaml`. Name views by audience/use case, not by table.
+5. **Write descriptions** — Descriptions are how AI agents choose views and measures. Lead with scope, cross-reference related views, include dimension values.
+6. **Validate** — `bon validate`
+7. **Deploy** — `bon login` then `bon deploy -m "description of changes"`
+8. **Test with questions** — Query via MCP with real user questions. Check the agent picks the right view and measure.
+9. **Iterate** — Fix agent mistakes by improving descriptions and adding filtered measures. Expect 2-4 iterations.
 
 For a guided walkthrough: `/bonnard-get-started`
 For projects migrating from Metabase: `/bonnard-metabase-migrate`
+For design principles: `/bonnard-design-guide`
 
 ## Deployment & Change Tracking
 
@@ -119,8 +124,20 @@ Every deploy creates a versioned deployment with change detection:
 
 For CI/CD pipelines, use `bon deploy --ci -m "message"` (non-interactive, fails on issues). Datasources are always synced automatically during deploy.
 
-## Best Practices
+## Design Principles
+
+Summary — see `/bonnard-design-guide` for examples and details.
+
+1. **Start from questions, not tables** — collect the 10-20 most common questions, build views that answer them
+2. **Views are for audiences, not tables** — name by use case (`sales_pipeline`), not by table (`orders_view`)
+3. **Add filtered measures** — if a dashboard card has a WHERE clause beyond date range, make it a filtered measure
+4. **Descriptions are the discovery API** — lead with scope, cross-reference related views, include dimension values
+5. **Build cross-entity views** — combine cubes when users think across tables; don't force one view per cube
+6. **Test with natural language** — ask an agent real questions via MCP; check it picks the right view and measure
+7. **Iterate** — expect 2-4 rounds; fix agent mistakes by improving descriptions, not data
+
+## Technical Gotchas
 
 - **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.
+- **Primary keys must be unique** — Cube deduplicates on the primary key. If the column isn't unique (e.g., a date with multiple rows per day), dimension queries silently return empty results. For tables without a natural unique column, use a `sql` query with `ROW_NUMBER()` to generate a synthetic key.
 - **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.2.4",
+  "version": "0.2.5",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"