@bonnard/cli 0.1.11 → 0.1.13

package/dist/bin/bon.mjs

@@ -2659,6 +2659,15 @@ function getChildTopics(topicId) {
 function searchTopics(query) {
 	const results = [];
 	const queryLower = query.toLowerCase();
+	const index = loadIndex();
+	if (index) {
+		const indexMatches = [];
+		for (const line of index.split("\n")) if (line.toLowerCase().includes(queryLower)) indexMatches.push(line.trim());
+		if (indexMatches.length > 0) results.push({
+			topic: "(index)",
+			matches: indexMatches.slice(0, 3)
+		});
+	}
 	for (const topic of getAvailableTopics()) {
 		const content = loadTopic(topic);
 		if (!content) continue;

package/dist/docs/topics/getting-started.md

@@ -0,0 +1,157 @@
+# Getting Started
+
+> Set up Bonnard and build your first semantic layer in minutes.
+
+## What is Bonnard?
+
+Bonnard is a semantic layer platform that sits between your data warehouse and your consumers (BI tools, AI agents, applications). You define your metrics and dimensions once in YAML, then query them through a consistent API.
+
+## Prerequisites
+
+- **Node.js 18+** — [Install Node.js](https://nodejs.org)
+- **A data warehouse** — PostgreSQL, Snowflake, BigQuery, or Databricks (or use our demo dataset)
+- **A Bonnard account** — [Sign up at app.bonnard.dev](https://app.bonnard.dev)
+
+## Install the CLI
+
+```bash
+npm install -g @bonnard/cli
+```
+
+Verify the installation:
+
+```bash
+bon --version
+```
+
+## Log in
+
+Authenticate with your Bonnard account:
+
+```bash
+bon login
+```
+
+This opens your browser to complete authentication. Once done, verify with:
+
+```bash
+bon whoami
+```
+
+## Initialize a project
+
+Navigate to your project directory and run:
+
+```bash
+bon init
+```
+
+This creates the project structure:
+
+```
+my-project/
+├── bon.yaml              # Project configuration
+├── bonnard/
+│   ├── cubes/            # Cube definitions (measures + dimensions)
+│   └── views/            # View definitions (curated interfaces)
+└── .bon/                 # Local config (gitignored)
+    └── datasources.yaml
+```
+
+If you have an existing dbt project, `bon init` will detect it and set up your agent context accordingly.
+
+## Connect a data source
+
+Add your warehouse connection:
+
+```bash
+bon datasource add
+```
+
+Follow the interactive prompts to configure your connection. If you use dbt, you can import from your profiles:
+
+```bash
+bon datasource add --from-dbt
+```
+
+**No warehouse yet?** Use our demo dataset — a read-only retail database (Contoso) with sales, products, stores, and customer data:
+
+```bash
+bon datasource add --demo
+```
+
+Test the connection:
+
+```bash
+bon datasource test contoso_demo
+```
+
+## Create your first cube
+
+Create a file at `bonnard/cubes/sales.yaml` (using the demo dataset — adapt table and column names to your own data):
+
+```yaml
+cubes:
+  - name: sales
+    sql_table: contoso.fact_sales
+    data_source: contoso_demo
+
+    measures:
+      - name: count
+        type: count
+
+      - name: total_revenue
+        type: sum
+        sql: sales_amount
+
+    dimensions:
+      - name: sales_key
+        type: number
+        sql: sales_key
+        primary_key: true
+
+      - name: date
+        type: time
+        sql: date_key
+
+      - name: sales_quantity
+        type: number
+        sql: sales_quantity
+```
+
+## Validate
+
+Check your cubes and views for errors:
+
+```bash
+bon validate
+```
+
+## Deploy
+
+Push your semantic layer to Bonnard:
+
+```bash
+bon deploy
+```
+
+## Query
+
+Test your deployed semantic layer:
+
+```bash
+bon query '{"measures": ["sales.count"]}'
+
+# With a dimension
+bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
+
+# Or use SQL format
+bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
+```
+
+## Next steps
+
+- Learn about [cubes](/docs/modeling/cubes) — measures, dimensions, joins
+- Learn about [views](/docs/modeling/views) — curated interfaces for consumers
+- Set up [MCP](/docs/workflow/mcp) — connect AI agents to your semantic layer
+- Read the full [workflow guide](/docs/workflow) — validate, deploy, query

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

@@ -41,65 +41,81 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available:
+Use `bon preview` to understand what tables and columns are available.
+**Always run this before creating cubes** — use the results to decide which
+tables to model and what columns to expose.
 
 ```bash
-# List tables (Postgres)
+# List tables — use the schema from the datasource config
+# For demo data (contoso schema):
+bon preview contoso_demo "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"
+
+# For user's own data (typically public schema):
 bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
 
-# List tables (Snowflake)
+# Snowflake:
 bon preview <datasource> "SHOW TABLES"
 
-# Sample a table
-bon preview <datasource> "SELECT * FROM orders" --limit 10
+# Then sample the key tables to see columns and data:
+bon preview contoso_demo "SELECT * FROM contoso.fact_sales" --limit 10
+bon preview contoso_demo "SELECT * FROM contoso.dim_product" --limit 10
 ```
 
-This helps you understand the schema before writing cubes.
+Note the table names, column names, and data types — you'll use these in Phase 3.
 
 ## Phase 3: Create Your First Cube
 
-Create a file in `bonnard/cubes/` for the most important table. A cube
-typically maps directly to a database table — define measures for the metrics
-you want to track and dimensions for the attributes you want to filter and
-group by.
+Based on what you found in Phase 2, create a file in `bonnard/cubes/` for
+the most important table. A cube maps directly to a database table — define
+measures for the metrics you want to track and dimensions for the attributes
+you want to filter and group by. **Use the actual table and column names from
+Phase 2, not placeholder names.**
 
-Example — `bonnard/cubes/orders.yaml`:
+Example using demo data — `bonnard/cubes/sales.yaml`:
 
 ```yaml
 cubes:
-  - name: orders
-    sql_table: public.orders
+  - name: sales
+    sql_table: contoso.fact_sales
+    data_source: contoso_demo
 
     measures:
       - name: count
         type: count
-        description: Total number of orders
+        description: Total number of sales transactions
 
       - name: total_revenue
         type: sum
-        sql: amount
-        description: Sum of order amounts
+        sql: sales_amount
+        description: Sum of sales revenue
+
+      - name: total_cost
+        type: sum
+        sql: total_cost
+        description: Sum of product costs
 
     dimensions:
-      - name: id
+      - name: sales_key
         type: number
-        sql: id
+        sql: sales_key
         primary_key: true
 
-      - name: status
-        type: string
-        sql: status
-        description: Order status (pending, completed, cancelled)
-
-      - name: created_at
+      - name: date
         type: time
-        sql: created_at
-        description: When the order was placed
+        sql: date_key
+        description: Sale date
+
+      - name: sales_quantity
+        type: number
+        sql: sales_quantity
+        description: Number of units sold
 ```
 
 Key rules:
 - Every cube needs a `primary_key` dimension
 - Every measure and dimension should have a `description`
+- 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
 
 Use `bon docs cubes` for the full reference, `bon docs cubes.measures.types`
@@ -108,21 +124,22 @@ 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/`:
+Create a file in `bonnard/views/` that references the cube from Phase 3.
 
-Example — `bonnard/views/orders_overview.yaml`:
+Example using demo data — `bonnard/views/sales_overview.yaml`:
 
 ```yaml
 views:
-  - name: orders_overview
-    description: High-level order metrics and attributes
+  - name: sales_overview
+    description: High-level sales metrics and attributes
     cubes:
-      - join_path: orders
+      - join_path: sales
         includes:
           - count
           - total_revenue
-          - status
-          - created_at
+          - total_cost
+          - date
+          - sales_quantity
 ```
 
 Use `bon docs views` for the full reference.
@@ -160,17 +177,17 @@ credentials (encrypted) to Bonnard.
 
 ## Phase 7: Test with a Query
 
-Verify the deployment works:
+Verify the deployment works using the cube name from Phase 3:
 
 ```bash
 # Simple count
-bon query '{"measures": ["orders.count"]}'
+bon query '{"measures": ["sales.count"]}'
 
-# Group by a dimension
-bon query '{"measures": ["orders.count"], "dimensions": ["orders.status"]}'
+# With a dimension
+bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
 
 # SQL format
-bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
 ```
 
 ## Phase 8: Connect AI Agents (Optional)

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

@@ -40,65 +40,81 @@ If the test fails, common issues:
 
 ## Phase 2: Explore the Data
 
-Use `bon preview` to understand what tables and columns are available:
+Use `bon preview` to understand what tables and columns are available.
+**Always run this before creating cubes** — use the results to decide which
+tables to model and what columns to expose.
 
 ```bash
-# List tables (Postgres)
+# List tables — use the schema from the datasource config
+# For demo data (contoso schema):
+bon preview contoso_demo "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"
+
+# For user's own data (typically public schema):
 bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
 
-# List tables (Snowflake)
+# Snowflake:
 bon preview <datasource> "SHOW TABLES"
 
-# Sample a table
-bon preview <datasource> "SELECT * FROM orders" --limit 10
+# Then sample the key tables to see columns and data:
+bon preview contoso_demo "SELECT * FROM contoso.fact_sales" --limit 10
+bon preview contoso_demo "SELECT * FROM contoso.dim_product" --limit 10
 ```
 
-This helps you understand the schema before writing cubes.
+Note the table names, column names, and data types — you'll use these in Phase 3.
 
 ## Phase 3: Create Your First Cube
 
-Create a file in `bonnard/cubes/` for the most important table. A cube
-typically maps directly to a database table — define measures for the metrics
-you want to track and dimensions for the attributes you want to filter and
-group by.
+Based on what you found in Phase 2, create a file in `bonnard/cubes/` for
+the most important table. A cube maps directly to a database table — define
+measures for the metrics you want to track and dimensions for the attributes
+you want to filter and group by. **Use the actual table and column names from
+Phase 2, not placeholder names.**
 
-Example — `bonnard/cubes/orders.yaml`:
+Example using demo data — `bonnard/cubes/sales.yaml`:
 
 ```yaml
 cubes:
-  - name: orders
-    sql_table: public.orders
+  - name: sales
+    sql_table: contoso.fact_sales
+    data_source: contoso_demo
 
     measures:
       - name: count
         type: count
-        description: Total number of orders
+        description: Total number of sales transactions
 
       - name: total_revenue
         type: sum
-        sql: amount
-        description: Sum of order amounts
+        sql: sales_amount
+        description: Sum of sales revenue
+
+      - name: total_cost
+        type: sum
+        sql: total_cost
+        description: Sum of product costs
 
     dimensions:
-      - name: id
+      - name: sales_key
         type: number
-        sql: id
+        sql: sales_key
         primary_key: true
 
-      - name: status
-        type: string
-        sql: status
-        description: Order status (pending, completed, cancelled)
-
-      - name: created_at
+      - name: date
         type: time
-        sql: created_at
-        description: When the order was placed
+        sql: date_key
+        description: Sale date
+
+      - name: sales_quantity
+        type: number
+        sql: sales_quantity
+        description: Number of units sold
 ```
 
 Key rules:
 - Every cube needs a `primary_key` dimension
 - Every measure and dimension should have a `description`
+- 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
 
 Use `bon docs cubes` for the full reference, `bon docs cubes.measures.types`
@@ -107,21 +123,22 @@ 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/`:
+Create a file in `bonnard/views/` that references the cube from Phase 3.
 
-Example — `bonnard/views/orders_overview.yaml`:
+Example using demo data — `bonnard/views/sales_overview.yaml`:
 
 ```yaml
 views:
-  - name: orders_overview
-    description: High-level order metrics and attributes
+  - name: sales_overview
+    description: High-level sales metrics and attributes
     cubes:
-      - join_path: orders
+      - join_path: sales
         includes:
           - count
           - total_revenue
-          - status
-          - created_at
+          - total_cost
+          - date
+          - sales_quantity
 ```
 
 Use `bon docs views` for the full reference.
@@ -159,17 +176,17 @@ credentials (encrypted) to Bonnard.
 
 ## Phase 7: Test with a Query
 
-Verify the deployment works:
+Verify the deployment works using the cube name from Phase 3:
 
 ```bash
 # Simple count
-bon query '{"measures": ["orders.count"]}'
+bon query '{"measures": ["sales.count"]}'
 
-# Group by a dimension
-bon query '{"measures": ["orders.count"], "dimensions": ["orders.status"]}'
+# With a dimension
+bon query '{"measures": ["sales.total_revenue"], "dimensions": ["sales.date"]}'
 
 # SQL format
-bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+bon query --sql "SELECT MEASURE(total_revenue) FROM sales"
 ```
 
 ## Phase 8: Connect AI Agents (Optional)

package/dist/templates/shared/datasources.yaml

@@ -0,0 +1,16 @@
+# Bonnard datasources configuration
+# This file contains credentials - add to .gitignore
+# Env vars like {{ env_var('PASSWORD') }} are resolved at deploy time
+
+datasources:
+  - name: contoso_demo
+    type: postgres
+    source: demo
+    config:
+      host: aws-1-eu-west-1.pooler.supabase.com
+      port: "5432"
+      database: postgres
+      schema: contoso
+    credentials:
+      username: demo_reader.yvbfzqogtdsqqkpyztlu
+      password: contoso-demo-2025!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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/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/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"
   },