@bonnard/cli 0.2.4 → 0.2.6

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.6",
   "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/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/",
     "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
     "test": "vitest run"
   },