@bonnard/cli 0.2.4 → 0.2.6

package/dist/docs/topics/querying.rest-api.md

@@ -0,0 +1,198 @@
+# REST API
+
+> Query your deployed semantic layer using the Bonnard REST API. Send JSON query objects or SQL strings to retrieve measures and dimensions with filtering, grouping, and time ranges.
+
+## Overview
+
+After deploying with `bon deploy`, you can query the semantic layer using `bon query`. This tests that your cubes and views work correctly and returns data from your warehouse through Bonnard.
+
+## Query Formats
+
+Bonnard supports two query formats:
+
+### JSON Format (Default)
+
+The JSON format uses the REST API structure:
+
+```bash
+bon query '{"measures": ["orders.count"]}'
+
+bon query '{
+  "measures": ["orders.total_revenue"],
+  "dimensions": ["orders.status"],
+  "filters": [{
+    "member": "orders.created_at",
+    "operator": "inDateRange",
+    "values": ["2024-01-01", "2024-12-31"]
+  }]
+}'
+```
+
+**JSON Query Properties:**
+
+| Property | Description |
+|----------|-------------|
+| `measures` | Array of measures to calculate (e.g., `["orders.count"]`) |
+| `dimensions` | Array of dimensions to group by (e.g., `["orders.status"]`) |
+| `filters` | Array of filter objects |
+| `timeDimensions` | Time-based grouping with granularity |
+| `segments` | Named filters defined in cubes |
+| `limit` | Max rows to return |
+| `offset` | Skip rows (pagination) |
+| `order` | Sort specification |
+
+**Filter Operators:**
+
+| Operator | Use Case |
+|----------|----------|
+| `equals`, `notEquals` | Exact match |
+| `contains`, `notContains` | String contains |
+| `startsWith`, `endsWith` | String prefix/suffix |
+| `gt`, `gte`, `lt`, `lte` | Numeric comparison |
+| `inDateRange`, `beforeDate`, `afterDate` | Time filtering |
+| `set`, `notSet` | NULL checks |
+
+### SQL Format
+
+The SQL format uses the SQL API, where cubes are tables:
+
+```bash
+bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+
+bon query --sql "SELECT
+  city,
+  MEASURE(total_revenue),
+  MEASURE(avg_order_value)
+FROM orders
+WHERE status = 'completed'
+GROUP BY 1
+ORDER BY 2 DESC
+LIMIT 10"
+```
+
+**SQL Syntax Rules:**
+
+1. **Cubes/views are tables** — `FROM orders` references the `orders` cube
+2. **Dimensions are columns** — Include in `SELECT` and `GROUP BY`
+3. **Measures use `MEASURE()`** — Or matching aggregates (`SUM`, `COUNT`, etc.)
+4. **Segments are boolean** — Filter with `WHERE is_completed IS TRUE`
+
+**Examples:**
+
+```sql
+-- Count orders by status
+SELECT status, MEASURE(count) FROM orders GROUP BY 1
+
+-- Revenue by city with filter
+SELECT city, SUM(amount) FROM orders WHERE status = 'shipped' GROUP BY 1
+
+-- Using time dimension with granularity
+SELECT DATE_TRUNC('month', created_at), MEASURE(total_revenue)
+FROM orders
+GROUP BY 1
+ORDER BY 1
+```
+
+## CLI Usage
+
+```bash
+# JSON format (default)
+bon query '{"measures": ["orders.count"]}'
+
+# SQL format
+bon query --sql "SELECT MEASURE(count) FROM orders"
+
+# Limit rows
+bon query '{"measures": ["orders.count"], "dimensions": ["orders.city"]}' --limit 10
+
+# JSON output (instead of table)
+bon query '{"measures": ["orders.count"]}' --format json
+```
+
+## Output Formats
+
+### Table Format (Default)
+
+```
+┌─────────┬───────────────┐
+│ status  │ orders.count  │
+├─────────┼───────────────┤
+│ pending │ 42            │
+│ shipped │ 156           │
+│ done    │ 892           │
+└─────────┴───────────────┘
+```
+
+### JSON Format
+
+```bash
+bon query '{"measures": ["orders.count"]}' --format json
+```
+
+```json
+[
+  { "orders.status": "pending", "orders.count": 42 },
+  { "orders.status": "shipped", "orders.count": 156 },
+  { "orders.status": "done", "orders.count": 892 }
+]
+```
+
+## Common Patterns
+
+### Time Series Analysis
+
+```bash
+bon query '{
+  "measures": ["orders.total_revenue"],
+  "timeDimensions": [{
+    "dimension": "orders.created_at",
+    "granularity": "month",
+    "dateRange": ["2024-01-01", "2024-12-31"]
+  }]
+}'
+```
+
+### Filtering by Dimension
+
+```bash
+bon query '{
+  "measures": ["orders.count"],
+  "dimensions": ["orders.city"],
+  "filters": [{
+    "member": "orders.status",
+    "operator": "equals",
+    "values": ["completed"]
+  }]
+}'
+```
+
+### Multiple Measures
+
+```bash
+bon query '{
+  "measures": ["orders.count", "orders.total_revenue", "orders.avg_order_value"],
+  "dimensions": ["orders.category"]
+}'
+```
+
+## Error Handling
+
+### Common Errors
+
+**"Projection references non-aggregate values"**
+- All dimensions must be in `GROUP BY`
+- All measures must use `MEASURE()` or matching aggregate
+
+**"Cube not found"**
+- Check cube name matches deployed cube
+- Run `bon deploy` if cubes changed
+
+**"Not logged in"**
+- Run `bon login` first
+
+## See Also
+
+- [cli.deploy](cli.deploy) - Deploy before querying
+- [cubes.measures](cubes.measures) - Define measures
+- [cubes.dimensions](cubes.dimensions) - Define dimensions
+- [views](views) - Create focused query interfaces

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

@@ -0,0 +1,53 @@
+# 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
+
+- [Overview](/docs/overview) — Platform overview
+- [querying.rest-api](querying.rest-api) — Query format reference

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

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

package/dist/docs/topics/views.md

@@ -6,11 +6,18 @@
 
 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.
+
 ## Example
 
 ```yaml
 views:
-  - name: orders_overview
+  - name: sales_analytics
+    description: >-
+      Sales team view — order revenue, counts, and status breakdowns with
+      customer details. 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:
@@ -39,13 +46,13 @@ views:
 
 ## Why Use Views?
 
-### 1. Simplify Data Access
+### 1. Curate for Audiences
 
-Expose only relevant members instead of entire cubes:
+Expose only the measures and dimensions a specific audience needs. A single `orders` cube might contribute to a `sales_analytics` view (revenue by status), a `management_kpis` view (high-level totals), and a `finance_reporting` view (invoice amounts). Each view shows different slices of the same data.
 
 ```yaml
 views:
-  - name: sales_dashboard
+  - name: sales_analytics
     cubes:
       - join_path: orders
         includes:
@@ -124,11 +131,12 @@ bonnard/views/
 
 ## Best Practices
 
-1. **Create purpose-specific views** — one view per dashboard/use case
-2. **Use meaningful names** — describe what the view is for
-3. **Be explicit with includes** — list members rather than using "*"
-4. **Alias for clarity** — rename members when needed
-5. **Organize with folders** — group related members together
+1. **Name views by audience/use case** — `sales_pipeline` not `opportunities_view`. Views represent how teams think about data, not your warehouse schema.
+2. **Write descriptions that help AI agents choose** — Lead with scope ("Sales team — revenue, order counts..."), cross-reference related views ("For customer demographics, use customer_insights instead"), and include key dimension values.
+3. **Combine multiple cubes** — A view should pull from whichever cubes answer a team's questions. Don't limit views to one cube each.
+4. **Be explicit with includes** — list members rather than using "*"
+5. **Alias for clarity** — rename members when needed
+6. **Organize with folders** — group related members together
 
 ## See Also
 

package/dist/docs/topics/workflow.md

@@ -131,11 +131,12 @@ bonnard/cubes/
 
 ## Best Practices
 
-1. **Start simple** — begin with one cube, add complexity gradually
-2. **Validate often** — run `bon validate` after each change
-3. **Use version control** — commit cubes and views to git
-4. **Document with descriptions** — add `description` to measures/dimensions
-5. **Test with queries** — verify models produce expected results
+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.
 
 ## Commands Reference
 

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