@bonnard/cli 0.2.3 → 0.2.5

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

@@ -0,0 +1,233 @@
+---
+name: bonnard-design-guide
+description: Design principles for building semantic layers that work well for AI agents and business users. Use when building views, writing descriptions, or improving agent accuracy.
+allowed-tools: Bash(bon *)
+---
+
+# Semantic Layer Design Guide
+
+This guide covers design decisions that determine whether your semantic layer
+works for end users and AI agents. It complements the setup guides
+(`/bonnard-get-started`, `/bonnard-metabase-migrate`) which cover mechanics.
+
+Read this before building views, or revisit it when agents return wrong
+answers or users can't find the right metrics.
+
+## Principle 1: Start from Questions, Not Tables
+
+The natural instinct is: look at tables, build cubes, expose everything.
+This produces a semantic layer that mirrors your warehouse schema —
+technically correct but useless to anyone who doesn't already know the schema.
+
+**Instead, start from what people ask:**
+
+1. Collect the 10-20 most common questions your team asks about data
+2. For each question, identify which tables/columns are needed to answer it
+3. Group questions by audience (who asks them)
+4. Build views that answer those question groups
+
+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.
+
+## Principle 2: Views Are for Audiences, Not Tables
+
+A common mistake is creating one view per cube (table). This produces views
+like `orders_view`, `users_view`, `invoices_view` — which is just the
+warehouse schema with extra steps.
+
+**Views should represent how a team thinks about data:**
+
+```
+BAD (model-centric):                 GOOD (audience-centric):
+views/                               views/
+  orders_view.yaml       (1 cube)      management.yaml      (revenue + users)
+  users_view.yaml        (1 cube)      sales.yaml           (opportunities + invoices)
+  invoices_view.yaml     (1 cube)      product.yaml         (users + funnel + contracts)
+  opportunities_view.yaml (1 cube)     partners.yaml        (partners + billing)
+```
+
+The same cube often appears in multiple views. An `opportunities` cube might
+contribute to `sales_opportunities` (filtered to active offers), a management
+KPI view, and a partner performance view. Each view exposes different
+measures and dimensions because different audiences need different slices.
+
+**Name views by what they answer**, not what table they wrap:
+`sales_pipeline` not `opportunities_overview`.
+
+## Principle 3: Add Filtered Measures
+
+This is the single most impactful thing you can do. Look at any real
+dashboard: it almost never shows `COUNT(*)` from a raw table. It shows
+"active offers" (type=Angebot AND status!=Cancelled), "unpaid invoices"
+(status NOT IN terminal states).
+
+Without filtered measures, agents return unfiltered totals that don't match
+what users see in their dashboards. Users lose trust immediately.
+
+**For every important dashboard card, check the WHERE clause:**
+
+```yaml
+# Dashboard shows "Active Offers: 7,500"
+# But raw COUNT(*) on opportunities returns 29,000
+# The card SQL has: WHERE type = 'Angebot' AND status != 'Abgesagt'
+
+measures:
+  - name: count
+    type: count
+    description: Total opportunities (all types and statuses)
+
+  - name: active_offer_count
+    type: count
+    description: Non-cancelled offers only (type=Angebot, status!=Abgesagt)
+    filters:
+      - sql: "{CUBE}.type = 'Angebot'"
+      - sql: "{CUBE}.status != 'Abgesagt'"
+```
+
+**Common patterns that need filtered measures:**
+- Status filters: active/open/pending items vs all items
+- Type filters: specific transaction types vs all transactions
+- Boolean flags: completed, paid, verified subsets
+- Exclusions: excluding test data, internal users, cancelled records
+
+A good rule of thumb: if a BI dashboard card has a WHERE clause beyond just
+a date range, that filter should probably be a filtered measure.
+
+## Principle 4: Descriptions Are the Discovery API
+
+For AI agents, descriptions are not documentation — they are the **primary
+mechanism for choosing which view and measure to use**. When an agent calls
+`explore_schema`, it sees view names and descriptions. That's all it has
+to decide where to query.
+
+### View descriptions must answer three questions:
+
+1. **What's in here?** — Lead with the scope and content
+2. **When should I use this?** — The default use case
+3. **When should I use something else?** — Explicit disambiguation
+
+```yaml
+# BAD: Generic, doesn't help agent choose
+description: User metrics and dimensions
+
+# GOOD: Scoped, navigational, includes data values
+description: >-
+  Sales pipeline — active and historical opportunities with contract values
+  and assignee details. Default view for pipeline questions, deal counts,
+  and contract value analysis. Use the type dimension (values: Angebot,
+  Auftrag) to filter by opportunity type. For invoice-level detail, use
+  sales_invoices instead.
+```
+
+### Description writing rules:
+
+**Lead with scope, not mechanics.** "All users across both products" not
+"Wraps the all_users cube." Agents match question keywords against
+description keywords.
+
+**Include actual dimension values.** If a dimension has known categorical
+values, list them: `(values: erben, vererben)`, `(values: B2B, Organic)`.
+This helps agents map user language to filter values.
+
+**Use the same vocabulary as your users.** If your team says "testaments"
+not "will_and_testament", the description should say "testaments."
+
+**Cross-reference related views.** When two views could plausibly answer the
+same question, both descriptions should point to each other: "For company-wide
+totals, use company_users instead." This is the most effective way to
+prevent agents from picking the wrong view.
+
+### Measure descriptions should say what's included/excluded:
+
+```yaml
+# BAD
+description: Count of orders
+
+# GOOD
+description: >-
+  Orders with status 'completed' or 'shipped' only.
+  Excludes cancelled and pending. For all orders, use total_order_count.
+```
+
+## Principle 5: Build Cross-Entity Views When Users Think Across Tables
+
+Sometimes the most common question doesn't map to any single table.
+"How many total signups do we have?" might require combining users from
+two separate product tables.
+
+**Options:**
+
+1. **Database view/UNION table** — If your warehouse has a combined
+   view, build a cube on it. Cleanest approach.
+2. **Multiple cubes in one view via joins** — If cubes can be joined
+   through foreign keys, include both in a view using `join_path`.
+3. **Separate views with clear descriptions** — If data can't be combined,
+   create separate views and describe how they relate.
+
+Don't force everything into one view. It's better to have an agent make
+two clear queries than one confused query against an over-joined view.
+
+## Principle 6: Test with Natural Language, Not Just Numbers
+
+Verifying that `bon query '{"measures": ["orders.count"]}'` returns the
+right number is necessary but not sufficient. The actual failure mode is:
+
+> User asks "how many active offers do we have?"
+> Agent queries `orders.count` instead of `sales_pipeline.active_offer_count`
+> Returns 29,000 instead of 7,500
+
+**To test properly, give real questions to an AI agent via MCP and check:**
+
+1. Did it find the right **view**?
+2. Did it pick the right **measure**?
+3. Did it apply the right **filters/date range**?
+4. Is the final **number** correct?
+
+Steps 1-3 are where most failures happen, caused by description and view
+structure problems — not wrong data.
+
+**Build a small eval set:**
+- Write 5-10 questions that your users actually ask
+- For each question, record the expected view, measure, and answer
+- Run each question through an agent 3-5 times (agents are non-deterministic)
+- If pass rate is below 80%, the issue is almost always the view description
+  or view structure, not the data
+
+## Principle 7: Iterate — The First Deploy Is Never Right
+
+The semantic layer is not a one-time build. The effective workflow is:
+
+```
+Build views -> Deploy -> Test with questions -> Find agent mistakes
+     ^                                              |
+     +---- Improve descriptions/measures <----------+
+```
+
+Expect 2-4 iterations before agents reliably answer the top 10 questions.
+Each iteration typically involves:
+
+- Rewriting 1-2 view descriptions to improve disambiguation
+- Adding 1-3 filtered measures that match dashboard WHERE clauses
+- Occasionally restructuring a view (splitting or merging)
+
+**Don't try to get it perfect before deploying.** Deploy early with your
+best guess, test with real questions, and fix what breaks.
+
+## Quick Checklist
+
+Before deploying, review each view against this checklist:
+
+- [ ] **View name** describes the audience/use case, not the underlying table
+- [ ] **View description** leads with scope ("All users..." / "Sales team only...")
+- [ ] **View description** cross-references related views ("For X, use Y instead")
+- [ ] **View description** includes key dimension values where helpful
+- [ ] **Filtered measures** exist for every dashboard card with a WHERE clause
+- [ ] **Measure descriptions** say what's included AND excluded
+- [ ] **Dimension descriptions** include example values for categorical fields
+- [ ] **No two views** could plausibly answer the same question without disambiguation

package/dist/templates/claude/skills/bonnard-get-started/SKILL.md

@@ -30,7 +30,7 @@ bon datasource add --name my_warehouse --type postgres \
 bon datasource add
 ```
 
-Supported types: `postgres` (also works for Redshift), `snowflake`, `bigquery`, `databricks`.
+Supported types: `postgres`, `redshift`, `snowflake`, `bigquery`, `databricks`.
 
 The demo option adds a read-only Contoso retail dataset with tables like
 `fact_sales`, `dim_product`, `dim_store`, and `dim_customer`.
@@ -41,9 +41,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.
@@ -79,6 +83,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
@@ -97,8 +110,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`)
+- **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
@@ -108,26 +124,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 `/bonnard-design-guide`
+for principles on naming, descriptions, and view structure.
 
 ## Phase 5: Validate
 
@@ -163,21 +191,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 `/bonnard-design-guide` Principle 4.
+
 ## Phase 8: Connect AI Agents (Optional)
 
 Set up MCP so AI agents can query the semantic layer:
@@ -193,8 +226,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 (`/bonnard-design-guide`)
 - 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/claude/skills/bonnard-metabase-migrate/SKILL.md

@@ -65,7 +65,7 @@ bon datasource add --from-dbt
 bon datasource add
 ```
 
-Supported types: `postgres` (also works for Redshift), `snowflake`, `bigquery`, `databricks`.
+Supported types: `postgres`, `redshift`, `snowflake`, `bigquery`, `databricks`.
 
 The connection will be tested automatically during `bon deploy`.
 
@@ -122,11 +122,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`:
 
@@ -181,15 +182,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:
@@ -205,7 +217,8 @@ views:
           - region
 ```
 
-Use `bon docs views` for the full reference.
+Use `bon docs views` for the full reference. See `/bonnard-design-guide`
+for principles on view naming, descriptions, and structure.
 
 ## Phase 7: Validate and Deploy
 
@@ -236,23 +249,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 `/bonnard-design-guide` 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 (`/bonnard-design-guide`)
 - 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>`