@bonnard/cli 0.1.9 → 0.1.11

package/dist/bin/bon.mjs

@@ -564,23 +564,18 @@ function createAgentTemplates(cwd, env) {
 	const claudeRulesDir = path.join(cwd, ".claude", "rules");
 	const claudeSkillsDir = path.join(cwd, ".claude", "skills");
 	fs.mkdirSync(claudeRulesDir, { recursive: true });
-	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-cli"), { recursive: true });
-	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-queries"), { recursive: true });
+	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-get-started"), { recursive: true });
 	writeTemplateFile(sharedBonnard, path.join(claudeRulesDir, "bonnard.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-cli/SKILL.md"), path.join(claudeSkillsDir, "bonnard-cli", "SKILL.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-queries/SKILL.md"), path.join(claudeSkillsDir, "bonnard-queries", "SKILL.md"), createdFiles);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(claudeSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
 	mergeSettingsJson(loadJsonTemplate("claude/settings.json"), path.join(cwd, ".claude", "settings.json"), createdFiles);
 	const cursorRulesDir = path.join(cwd, ".cursor", "rules");
 	fs.mkdirSync(cursorRulesDir, { recursive: true });
 	writeTemplateFile(withCursorFrontmatter(sharedBonnard, "Bonnard semantic layer project context", true), path.join(cursorRulesDir, "bonnard.mdc"), createdFiles);
-	writeTemplateFile(loadTemplate("cursor/rules/bonnard-cli.mdc"), path.join(cursorRulesDir, "bonnard-cli.mdc"), createdFiles);
-	writeTemplateFile(loadTemplate("cursor/rules/bonnard-queries.mdc"), path.join(cursorRulesDir, "bonnard-queries.mdc"), createdFiles);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-get-started.mdc"), path.join(cursorRulesDir, "bonnard-get-started.mdc"), createdFiles);
 	const codexSkillsDir = path.join(cwd, ".agents", "skills");
-	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-cli"), { recursive: true });
-	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-queries"), { recursive: true });
+	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-get-started"), { recursive: true });
 	writeTemplateFile(sharedBonnard, path.join(cwd, "AGENTS.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-cli/SKILL.md"), path.join(codexSkillsDir, "bonnard-cli", "SKILL.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-queries/SKILL.md"), path.join(codexSkillsDir, "bonnard-queries", "SKILL.md"), createdFiles);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(codexSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
 	return createdFiles;
 }
 async function initCommand() {
@@ -1493,10 +1488,45 @@ async function addManual(options) {
 	console.log(pc.dim(`Test connection: bon datasource test ${name}`));
 }
 /**
+* Add the Contoso demo datasource (read-only retail dataset)
+*/
+async function addDemo(options) {
+	const name = "contoso_demo";
+	if (datasourceExists(name) && !options.force) {
+		console.log(pc.yellow(`Datasource "${name}" already exists. Use --force to overwrite.`));
+		return;
+	}
+	if (isDatasourcesTrackedByGit()) console.log(pc.yellow("Warning: .bon/datasources.yaml is tracked by git. Add it to .gitignore!"));
+	addLocalDatasource({
+		name,
+		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!"
+		}
+	});
+	console.log();
+	console.log(pc.green(`✓ Demo datasource "${name}" saved to .bon/datasources.yaml`));
+	console.log();
+	console.log(pc.dim("Contoso is a read-only retail dataset with tables like:"));
+	console.log(pc.dim("  fact_sales, dim_product, dim_store, dim_customer"));
+	console.log();
+	console.log(pc.dim(`Test connection: bon datasource test ${name}`));
+	console.log(pc.dim(`Explore tables:  bon preview ${name} "SELECT table_name FROM information_schema.tables WHERE table_schema = 'contoso'"`));
+}
+/**
 * Main datasource add command
 */
 async function datasourceAddCommand(options = {}) {
-	if (options.fromDbt !== void 0) await importFromDbt(options);
+	if (options.demo) await addDemo(options);
+	else if (options.fromDbt !== void 0) await importFromDbt(options);
 	else await addManual(options);
 }
 
@@ -1786,7 +1816,10 @@ async function queryPostgres(config, credentials, sql, options = {}) {
 	try {
 		await client.connect();
 		const schema = options.schema || config.schema;
-		if (schema) await client.query(`SET search_path TO ${schema}`);
+		if (schema) {
+			if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema)) throw new Error("Invalid schema name");
+			await client.query(`SET search_path TO "${schema}"`);
+		}
 		const result = await client.query(sql);
 		await client.end();
 		const columns = result.fields?.map((f) => f.name) || [];
@@ -2808,7 +2841,7 @@ program.command("login").description("Authenticate with Bonnard via your browser
 program.command("logout").description("Remove stored credentials").action(logoutCommand);
 program.command("whoami").description("Show current login status").option("--verify", "Verify session is still valid with the server").action(whoamiCommand);
 const datasource = program.command("datasource").description("Manage warehouse data source connections");
-datasource.command("add").description("Add a data source to .bon/datasources.yaml. Use --name and --type together for non-interactive mode").option("--from-dbt [profile]", "Import from dbt profiles.yml (optionally specify profile/target)").option("--target <target>", "Target name when using --from-dbt").option("--all", "Import all connections from dbt profiles").option("--default-targets", "Import only default targets from dbt profiles (non-interactive)").option("--name <name>", "Datasource name (required for non-interactive mode)").option("--type <type>", "Warehouse type: snowflake, postgres, bigquery, databricks (required for non-interactive mode)").option("--account <account>", "Snowflake account identifier").option("--database <database>", "Database name").option("--schema <schema>", "Schema name").option("--warehouse <warehouse>", "Warehouse name (Snowflake)").option("--role <role>", "Role (Snowflake)").option("--host <host>", "Host (Postgres)").option("--port <port>", "Port (Postgres, default: 5432)").option("--project-id <projectId>", "GCP Project ID (BigQuery)").option("--dataset <dataset>", "Dataset name (BigQuery)").option("--location <location>", "Location (BigQuery)").option("--hostname <hostname>", "Server hostname (Databricks)").option("--http-path <httpPath>", "HTTP path (Databricks)").option("--catalog <catalog>", "Catalog name (Databricks)").option("--user <user>", "Username").option("--password <password>", "Password (use --password-env for env var reference)").option("--token <token>", "Access token (use --token-env for env var reference)").option("--service-account-json <json>", "Service account JSON (BigQuery)").option("--keyfile <path>", "Path to service account key file (BigQuery)").option("--password-env <varName>", "Env var name for password, stores as {{ env_var('NAME') }}").option("--token-env <varName>", "Env var name for token, stores as {{ env_var('NAME') }}").option("--force", "Overwrite existing datasource without prompting").action(datasourceAddCommand);
+datasource.command("add").description("Add a data source to .bon/datasources.yaml. Use --name and --type together for non-interactive mode").option("--demo", "Add a read-only demo datasource (Contoso retail dataset) for testing").option("--from-dbt [profile]", "Import from dbt profiles.yml (optionally specify profile/target)").option("--target <target>", "Target name when using --from-dbt").option("--all", "Import all connections from dbt profiles").option("--default-targets", "Import only default targets from dbt profiles (non-interactive)").option("--name <name>", "Datasource name (required for non-interactive mode)").option("--type <type>", "Warehouse type: snowflake, postgres, bigquery, databricks (required for non-interactive mode)").option("--account <account>", "Snowflake account identifier").option("--database <database>", "Database name").option("--schema <schema>", "Schema name").option("--warehouse <warehouse>", "Warehouse name (Snowflake)").option("--role <role>", "Role (Snowflake)").option("--host <host>", "Host (Postgres)").option("--port <port>", "Port (Postgres, default: 5432)").option("--project-id <projectId>", "GCP Project ID (BigQuery)").option("--dataset <dataset>", "Dataset name (BigQuery)").option("--location <location>", "Location (BigQuery)").option("--hostname <hostname>", "Server hostname (Databricks)").option("--http-path <httpPath>", "HTTP path (Databricks)").option("--catalog <catalog>", "Catalog name (Databricks)").option("--user <user>", "Username").option("--password <password>", "Password (use --password-env for env var reference)").option("--token <token>", "Access token (use --token-env for env var reference)").option("--service-account-json <json>", "Service account JSON (BigQuery)").option("--keyfile <path>", "Path to service account key file (BigQuery)").option("--password-env <varName>", "Env var name for password, stores as {{ env_var('NAME') }}").option("--token-env <varName>", "Env var name for token, stores as {{ env_var('NAME') }}").option("--force", "Overwrite existing datasource without prompting").action(datasourceAddCommand);
 datasource.command("list").description("List data sources (shows both local and remote by default)").option("--local", "Show only local data sources from .bon/datasources.yaml").option("--remote", "Show only remote data sources from Bonnard server (requires login)").action(datasourceListCommand);
 datasource.command("test").description("Test data source connectivity by connecting directly to the warehouse").argument("<name>", "Data source name from .bon/datasources.yaml").option("--remote", "Test via Bonnard API instead of direct connection (requires login)").action(datasourceTestCommand);
 datasource.command("remove").description("Remove a data source from .bon/datasources.yaml (local by default)").argument("<name>", "Data source name").option("--remote", "Remove from Bonnard server instead of local (requires login)").action(datasourceRemoveCommand);

package/dist/docs/topics/dashboards.components.md

@@ -0,0 +1,137 @@
+# dashboards.components
+
+> Chart and display components for rendering query results in dashboards.
+
+## Overview
+
+Components are self-closing HTML-style tags that render query results as charts, tables, or KPI cards. Each component takes a `data` prop referencing a named query.
+
+## Syntax
+
+```markdown
+<ComponentName data={query_name} prop="value" />
+```
+
+- Components are self-closing (`/>`)
+- `data` uses curly braces: `data={query_name}`
+- Other props use quotes: `x="field_name"`
+- Boolean props can be shorthand: `horizontal`
+
+## Component Reference
+
+### BigValue
+
+Displays a single KPI metric as a large number.
+
+```markdown
+<BigValue data={total_revenue} value="total_revenue" title="Revenue" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name (should return a single row) |
+| `value` | string | Yes | Measure field name to display |
+| `title` | string | No | Label above the value |
+
+### LineChart
+
+Renders a line chart, typically for time series.
+
+```markdown
+<LineChart data={monthly_revenue} x="created_at" y="total_revenue" title="Revenue Trend" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `x` | string | Yes | Field for x-axis (typically a time dimension) |
+| `y` | string | Yes | Field for y-axis (typically a measure) |
+| `title` | string | No | Chart title |
+
+### BarChart
+
+Renders a vertical bar chart. Add `horizontal` for horizontal bars.
+
+```markdown
+<BarChart data={revenue_by_city} x="city" y="total_revenue" />
+<BarChart data={revenue_by_city} x="city" y="total_revenue" horizontal />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `x` | string | Yes | Field for category axis |
+| `y` | string | Yes | Field for value axis |
+| `title` | string | No | Chart title |
+| `horizontal` | boolean | No | Render as horizontal bar chart |
+
+### AreaChart
+
+Renders a filled area chart.
+
+```markdown
+<AreaChart data={monthly_revenue} x="created_at" y="total_revenue" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `x` | string | Yes | Field for x-axis |
+| `y` | string | Yes | Field for y-axis |
+| `title` | string | No | Chart title |
+
+### PieChart
+
+Renders a pie/donut chart.
+
+```markdown
+<PieChart data={by_status} name="status" value="count" title="Order Status" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `name` | string | Yes | Field for slice labels |
+| `value` | string | Yes | Field for slice values |
+| `title` | string | No | Chart title |
+
+### DataTable
+
+Renders query results as a table.
+
+```markdown
+<DataTable data={top_products} />
+<DataTable data={top_products} columns="name,revenue,count" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `columns` | string | No | Comma-separated list of columns to show (default: all) |
+| `title` | string | No | Table title |
+
+## Layout: Grid
+
+Wrap components in a `<Grid>` tag to arrange them in columns:
+
+```markdown
+<Grid cols="3">
+<BigValue data={total_orders} value="count" title="Orders" />
+<BigValue data={total_revenue} value="total_revenue" title="Revenue" />
+<BigValue data={avg_order} value="avg_order_value" title="Avg Order" />
+</Grid>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cols` | string | `"2"` | Number of columns in the grid |
+
+## Field Names
+
+Component field names (e.g. `x="city"`, `value="total_revenue"`) use the **unqualified** measure or dimension name — the same names defined in your cube. For example, if your cube has `measures: [{ name: total_revenue, ... }]`, use `value="total_revenue"`.
+
+## See Also
+
+- dashboards.queries
+- dashboards.examples
+- dashboards

package/dist/docs/topics/dashboards.examples.md

@@ -0,0 +1,130 @@
+# dashboards.examples
+
+> Complete dashboard examples showing common patterns.
+
+## Revenue Overview Dashboard
+
+A KPI + trend + breakdown dashboard:
+
+```markdown
+---
+title: Revenue Overview
+description: Monthly revenue trends and breakdowns
+---
+
+# Revenue Overview
+
+` ``query total_revenue
+cube: orders
+measures: [total_revenue]
+` ``
+
+` ``query order_count
+cube: orders
+measures: [count]
+` ``
+
+` ``query avg_order
+cube: orders
+measures: [avg_order_value]
+` ``
+
+<Grid cols="3">
+<BigValue data={total_revenue} value="total_revenue" title="Total Revenue" />
+<BigValue data={order_count} value="count" title="Orders" />
+<BigValue data={avg_order} value="avg_order_value" title="Avg Order" />
+</Grid>
+
+## Monthly Trend
+
+` ``query monthly_revenue
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+<LineChart data={monthly_revenue} x="created_at" y="total_revenue" title="Monthly Revenue" />
+
+## By Category
+
+` ``query by_category
+cube: orders
+measures: [total_revenue, count]
+dimensions: [category]
+orderBy:
+  total_revenue: desc
+` ``
+
+<BarChart data={by_category} x="category" y="total_revenue" title="Revenue by Category" />
+<DataTable data={by_category} />
+```
+
+## Sales Pipeline Dashboard
+
+Filtered data with pie chart:
+
+```markdown
+---
+title: Sales Pipeline
+description: Order status breakdown and city analysis
+---
+
+# Sales Pipeline
+
+` ``query by_status
+cube: orders
+measures: [count]
+dimensions: [status]
+` ``
+
+<PieChart data={by_status} name="status" value="count" title="Order Status" />
+
+## Top Cities
+
+` ``query top_cities
+cube: orders
+measures: [total_revenue, count]
+dimensions: [city]
+orderBy:
+  total_revenue: desc
+limit: 10
+` ``
+
+<BarChart data={top_cities} x="city" y="total_revenue" horizontal />
+<DataTable data={top_cities} />
+
+## Completed Orders Over Time
+
+` ``query completed_trend
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: week
+  dateRange: [2025-01-01, 2025-06-30]
+filters:
+  - dimension: status
+    operator: equals
+    values: [completed]
+` ``
+
+<AreaChart data={completed_trend} x="created_at" y="total_revenue" title="Completed Order Revenue" />
+```
+
+## Tips
+
+- **Start with KPIs**: Use `BigValue` in a `Grid` at the top for key metrics
+- **One query per chart**: Each component gets its own query — keep them focused
+- **Use views**: Prefer view names over cube names when available for cleaner field names
+- **Name queries descriptively**: `monthly_revenue` is better than `q1`
+- **Limit large datasets**: Add `limit` to dimension queries to avoid oversized charts
+- **Time series**: Always use `timeDimension` with `granularity` for time-based charts
+
+## See Also
+
+- dashboards
+- dashboards.queries
+- dashboards.components

package/dist/docs/topics/dashboards.md

@@ -0,0 +1,83 @@
+# dashboards
+
+> Build interactive dashboards from markdown with embedded semantic layer queries.
+
+## Overview
+
+Dashboards are markdown files with YAML frontmatter, query blocks, and chart components. Write them as `.md` files, deploy with `bon dashboard deploy`, and view them in the Bonnard web app.
+
+## Format
+
+A dashboard file has three parts:
+
+1. **Frontmatter** — YAML metadata between `---` delimiters
+2. **Query blocks** — Named data queries in ` ```query ` code fences
+3. **Content** — Markdown text and chart component tags
+
+## Minimal Example
+
+```markdown
+---
+title: Order Summary
+description: Key metrics for the orders pipeline
+---
+
+# Order Summary
+
+` ``query order_count
+cube: orders
+measures: [count]
+` ``
+
+<BigValue data={order_count} value="count" title="Total Orders" />
+
+` ``query by_status
+cube: orders
+measures: [count]
+dimensions: [status]
+` ``
+
+<BarChart data={by_status} x="status" y="count" />
+```
+
+## Frontmatter
+
+The YAML frontmatter is required and must include `title`:
+
+```yaml
+---
+title: Revenue Dashboard        # Required
+description: Monthly trends     # Optional
+slug: revenue-dashboard         # Optional (derived from title if omitted)
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Dashboard title displayed in the viewer and listings |
+| `description` | No | Short description shown in dashboard listings |
+| `slug` | No | URL-safe identifier. Auto-derived from title if omitted |
+
+## Deployment
+
+```bash
+# Deploy a single dashboard
+bon dashboard deploy revenue.md
+
+# Deploy all dashboards in a directory
+bon dashboard deploy dashboards/
+
+# List deployed dashboards
+bon dashboard list
+
+# Remove a dashboard
+bon dashboard remove revenue-dashboard
+```
+
+Via MCP tools, agents can use `deploy_dashboard` with the markdown content as a string.
+
+## See Also
+
+- dashboards.queries
+- dashboards.components
+- dashboards.examples

package/dist/docs/topics/dashboards.queries.md

@@ -0,0 +1,117 @@
+# dashboards.queries
+
+> Define data queries in dashboard markdown using YAML code fences.
+
+## Overview
+
+Query blocks fetch data from the semantic layer. Each query has a unique name and maps to a `QueryOptions` shape. Query results are referenced by chart components using `data={query_name}`.
+
+## Syntax
+
+Query blocks use fenced code with the `query` language tag followed by a name:
+
+````markdown
+```query revenue_trend
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+```
+````
+
+## Query Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `cube` | string | Yes | The cube or view to query (e.g. `orders`) |
+| `measures` | string[] | No | Measures to aggregate (e.g. `[count, total_revenue]`) |
+| `dimensions` | string[] | No | Dimensions to group by (e.g. `[status, city]`) |
+| `filters` | Filter[] | No | Row-level filters |
+| `timeDimension` | object | No | Time-based grouping and date range |
+| `orderBy` | object | No | Sort specification (e.g. `{total_revenue: desc}`) |
+| `limit` | number | No | Maximum rows to return |
+
+### timeDimension
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `dimension` | string | Yes | Time dimension name (e.g. `created_at`) |
+| `granularity` | string | No | `day`, `week`, `month`, `quarter`, or `year` |
+| `dateRange` | string[] | No | `[start, end]` in `YYYY-MM-DD` format |
+
+### filters
+
+Each filter is an object with:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dimension` | string | Dimension to filter on |
+| `operator` | string | `equals`, `notEquals`, `contains`, `gt`, `gte`, `lt`, `lte` |
+| `values` | array | Values to filter by |
+
+## Examples
+
+### Simple aggregation
+
+````markdown
+```query total_orders
+cube: orders
+measures: [count]
+```
+````
+
+### Grouped by dimension
+
+````markdown
+```query revenue_by_city
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+orderBy:
+  total_revenue: desc
+limit: 10
+```
+````
+
+### Time series
+
+````markdown
+```query monthly_revenue
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+```
+````
+
+### With filters
+
+````markdown
+```query completed_orders
+cube: orders
+measures: [count, total_revenue]
+dimensions: [category]
+filters:
+  - dimension: status
+    operator: equals
+    values: [completed]
+```
+````
+
+## Rules
+
+- Query names must be valid identifiers (letters, numbers, `_`, `$`)
+- Query names must be unique within a dashboard
+- Every query must specify a `cube`
+- Field names are unqualified (use `count` not `orders.count`) — the `cube` provides the context
+- Components reference queries by name: `data={query_name}`
+
+## See Also
+
+- dashboards.components
+- dashboards
+- workflow.query

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

@@ -0,0 +1,195 @@
+---
+name: bonnard-get-started
+description: Guide a user through setting up their first semantic layer after bon init. Use when user says "get started", "what next", "help me set up", or has just run bon init.
+allowed-tools: Bash(bon *)
+---
+
+# Get Started with Bonnard
+
+This skill guides you through building and deploying a semantic layer.
+The user has already run `bon init`. Walk through each phase in order,
+confirming progress before moving on.
+
+## Phase 1: Connect a Data Source
+
+Ask the user if they have a warehouse to connect, or want to try a demo dataset first:
+
+```bash
+# Option A: Import from dbt (if they use it)
+bon datasource add --from-dbt
+
+# Option B: Add manually (interactive)
+bon datasource add
+
+# Option C: Use demo data (no warehouse needed)
+bon datasource add --demo
+```
+
+The demo option adds a read-only Contoso retail dataset with tables like
+`fact_sales`, `dim_product`, `dim_store`, and `dim_customer`.
+
+Then verify the connection works:
+
+```bash
+bon datasource test <name>
+```
+
+If the test fails, common issues:
+- Wrong credentials — re-run `bon datasource add`
+- Network/firewall — check warehouse allows connections from this machine
+- SSL issues (Postgres) — may need `sslmode` in connection config
+
+## Phase 2: Explore the Data
+
+Use `bon preview` to understand what tables and columns are available:
+
+```bash
+# List tables (Postgres)
+bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
+
+# List tables (Snowflake)
+bon preview <datasource> "SHOW TABLES"
+
+# Sample a table
+bon preview <datasource> "SELECT * FROM orders" --limit 10
+```
+
+This helps you understand the schema before writing cubes.
+
+## 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.
+
+Example — `bonnard/cubes/orders.yaml`:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+
+    measures:
+      - name: count
+        type: count
+        description: Total number of orders
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+        description: Sum of order amounts
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: status
+        type: string
+        sql: status
+        description: Order status (pending, completed, cancelled)
+
+      - name: created_at
+        type: time
+        sql: created_at
+        description: When the order was placed
+```
+
+Key rules:
+- Every cube needs a `primary_key` dimension
+- Every measure and dimension should have a `description`
+- Use `sql_table` for simple table references, `sql` for complex queries
+
+Use `bon docs cubes` for the full reference, `bon docs cubes.measures.types`
+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/`:
+
+Example — `bonnard/views/orders_overview.yaml`:
+
+```yaml
+views:
+  - name: orders_overview
+    description: High-level order metrics and attributes
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - status
+          - created_at
+```
+
+Use `bon docs views` for the full reference.
+
+## Phase 5: Validate
+
+Check for errors:
+
+```bash
+bon validate
+```
+
+Fix any errors before proceeding. Common issues:
+- Missing required fields (`name`, `type`, `sql`)
+- Unknown measure/dimension types (e.g., `text` should be `string`)
+- Bad YAML indentation
+
+Optionally test the datasource connection too:
+
+```bash
+bon validate --test-connection
+```
+
+## Phase 6: Deploy
+
+Log in (if not already) and deploy:
+
+```bash
+bon login
+bon deploy
+```
+
+Deploy validates, tests connections, uploads cubes/views, and syncs datasource
+credentials (encrypted) to Bonnard.
+
+## Phase 7: Test with a Query
+
+Verify the deployment works:
+
+```bash
+# Simple count
+bon query '{"measures": ["orders.count"]}'
+
+# Group by a dimension
+bon query '{"measures": ["orders.count"], "dimensions": ["orders.status"]}'
+
+# SQL format
+bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+```
+
+## Phase 8: Connect AI Agents (Optional)
+
+Set up MCP so AI agents can query the semantic layer:
+
+```bash
+bon mcp
+```
+
+This shows setup instructions for Claude Desktop, ChatGPT, Cursor, VS Code,
+and other MCP clients. The MCP URL is `https://mcp.bonnard.dev/mcp`.
+
+## Next Steps
+
+After the first cube is working:
+
+- Add more cubes for other tables
+- Add joins between cubes (`bon docs cubes.joins`)
+- 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-get-started.mdc

@@ -0,0 +1,194 @@
+---
+description: "Guide a user through setting up their first semantic layer after bon init. Use when user says 'get started', 'what next', 'help me set up', or has just run bon init."
+alwaysApply: false
+---
+
+# Get Started with Bonnard
+
+This skill guides you through building and deploying a semantic layer.
+The user has already run `bon init`. Walk through each phase in order,
+confirming progress before moving on.
+
+## Phase 1: Connect a Data Source
+
+Ask the user if they have a warehouse to connect, or want to try a demo dataset first:
+
+```bash
+# Option A: Import from dbt (if they use it)
+bon datasource add --from-dbt
+
+# Option B: Add manually (interactive)
+bon datasource add
+
+# Option C: Use demo data (no warehouse needed)
+bon datasource add --demo
+```
+
+The demo option adds a read-only Contoso retail dataset with tables like
+`fact_sales`, `dim_product`, `dim_store`, and `dim_customer`.
+
+Then verify the connection works:
+
+```bash
+bon datasource test <name>
+```
+
+If the test fails, common issues:
+- Wrong credentials — re-run `bon datasource add`
+- Network/firewall — check warehouse allows connections from this machine
+- SSL issues (Postgres) — may need `sslmode` in connection config
+
+## Phase 2: Explore the Data
+
+Use `bon preview` to understand what tables and columns are available:
+
+```bash
+# List tables (Postgres)
+bon preview <datasource> "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
+
+# List tables (Snowflake)
+bon preview <datasource> "SHOW TABLES"
+
+# Sample a table
+bon preview <datasource> "SELECT * FROM orders" --limit 10
+```
+
+This helps you understand the schema before writing cubes.
+
+## 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.
+
+Example — `bonnard/cubes/orders.yaml`:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+
+    measures:
+      - name: count
+        type: count
+        description: Total number of orders
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+        description: Sum of order amounts
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: status
+        type: string
+        sql: status
+        description: Order status (pending, completed, cancelled)
+
+      - name: created_at
+        type: time
+        sql: created_at
+        description: When the order was placed
+```
+
+Key rules:
+- Every cube needs a `primary_key` dimension
+- Every measure and dimension should have a `description`
+- Use `sql_table` for simple table references, `sql` for complex queries
+
+Use `bon docs cubes` for the full reference, `bon docs cubes.measures.types`
+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/`:
+
+Example — `bonnard/views/orders_overview.yaml`:
+
+```yaml
+views:
+  - name: orders_overview
+    description: High-level order metrics and attributes
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - status
+          - created_at
+```
+
+Use `bon docs views` for the full reference.
+
+## Phase 5: Validate
+
+Check for errors:
+
+```bash
+bon validate
+```
+
+Fix any errors before proceeding. Common issues:
+- Missing required fields (`name`, `type`, `sql`)
+- Unknown measure/dimension types (e.g., `text` should be `string`)
+- Bad YAML indentation
+
+Optionally test the datasource connection too:
+
+```bash
+bon validate --test-connection
+```
+
+## Phase 6: Deploy
+
+Log in (if not already) and deploy:
+
+```bash
+bon login
+bon deploy
+```
+
+Deploy validates, tests connections, uploads cubes/views, and syncs datasource
+credentials (encrypted) to Bonnard.
+
+## Phase 7: Test with a Query
+
+Verify the deployment works:
+
+```bash
+# Simple count
+bon query '{"measures": ["orders.count"]}'
+
+# Group by a dimension
+bon query '{"measures": ["orders.count"], "dimensions": ["orders.status"]}'
+
+# SQL format
+bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+```
+
+## Phase 8: Connect AI Agents (Optional)
+
+Set up MCP so AI agents can query the semantic layer:
+
+```bash
+bon mcp
+```
+
+This shows setup instructions for Claude Desktop, ChatGPT, Cursor, VS Code,
+and other MCP clients. The MCP URL is `https://mcp.bonnard.dev/mcp`.
+
+## Next Steps
+
+After the first cube is working:
+
+- Add more cubes for other tables
+- Add joins between cubes (`bon docs cubes.joins`)
+- 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/shared/bonnard.md

@@ -39,12 +39,29 @@ my-project/
     └── datasources.yaml  # Warehouse connections
 ```
 
+## Demo Data
+
+No warehouse? Use the built-in demo dataset to try Bonnard:
+
+```bash
+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
+- `dim_product` — product_name, brand_name, manufacturer, unit_cost, unit_price
+- `dim_store` — store_name, store_type, employee_count, selling_area_size
+- `dim_customer` — first_name, last_name, gender, yearly_income, education, occupation
+
+All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
+
 ## Quick Reference
 
 | Command | Purpose |
 |---------|---------|
 | `bon init` | Initialize new project |
 | `bon datasource add` | Add warehouse connection |
+| `bon datasource add --demo` | Add demo dataset (no warehouse needed) |
 | `bon datasource add --from-dbt` | Import from dbt profiles |
 | `bon datasource test <name>` | Test connection |
 | `bon validate` | Validate YAML syntax |
@@ -78,5 +95,4 @@ Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to
 4. **Validate** — `bon validate --test-connection`
 5. **Deploy** — `bon login` then `bon deploy`
 
-For CLI details: `/bonnard-cli`
-For YAML patterns: `/bonnard-queries`
+For a guided walkthrough: `/bonnard-get-started`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"

package/dist/templates/claude/skills/bonnard-cli/SKILL.md

@@ -1,59 +0,0 @@
----
-name: bonnard-cli
-description: Bonnard CLI reference. Use when user needs help with bon commands, data sources, or deployments.
-allowed-tools: Bash(bon *)
----
-
-# Bonnard CLI
-
-## Commands
-
-### Project Setup
-```bash
-bon init              # Initialize new project
-bon login             # Authenticate with Bonnard
-bon logout            # Clear credentials
-```
-
-### Data Sources
-```bash
-bon datasource add              # Add new data source (interactive)
-bon datasource list             # List all data sources
-bon datasource test <name>      # Test connection
-bon datasource remove <name>    # Remove data source
-```
-
-### Development
-```bash
-bon validate          # Validate cubes and views
-bon deploy            # Deploy to Bonnard
-```
-
-### Data Exploration (Local)
-```bash
-bon preview <datasource> "<sql>"              # Preview data with raw SQL
-bon preview <datasource> "<sql>" --format json  # JSON output
-bon preview <datasource> "<sql>" --limit 100    # Limit rows
-```
-
-### Semantic Layer Queries (Deployed)
-```bash
-# JSON format (default)
-bon query '{"measures": ["orders.count"]}'
-bon query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
-
-# SQL format
-bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
-bon query --sql "SELECT city, SUM(amount) FROM orders GROUP BY 1" --limit 10
-```
-
-### Documentation
-```bash
-bon docs                          # Show all topics
-bon docs <topic>                  # View topic (e.g., cubes.measures)
-bon docs <topic> --recursive      # Topic + all children
-bon docs --search "<query>"       # Search all docs
-bon docs <topic> --format json    # Structured output
-```
-
-**Key topics:** `cubes`, `cubes.measures`, `cubes.dimensions`, `cubes.joins`, `views`, `pre-aggregations`, `syntax`

package/dist/templates/claude/skills/bonnard-queries/SKILL.md

@@ -1,68 +0,0 @@
----
-name: bonnard-queries
-description: How to write queries and work with cubes and views. Use when user asks about metrics, dimensions, or data modeling.
----
-
-# Bonnard Query Patterns
-
-## Cube Structure (YAML)
-
-```yaml
-cubes:
-  - name: orders
-    sql: SELECT * FROM public.orders
-
-    measures:
-      - name: count
-        type: count
-        description: Total number of orders
-
-      - name: total_amount
-        type: sum
-        sql: amount
-        description: Sum of order amounts in dollars
-
-    dimensions:
-      - name: status
-        type: string
-        sql: status
-        description: Order status (pending, completed, cancelled)
-
-      - name: created_at
-        type: time
-        sql: created_at
-        description: When the order was placed
-```
-
-## View Structure (YAML)
-
-```yaml
-views:
-  - name: orders_overview
-    cubes:
-      - join_path: orders
-        includes:
-          - count
-          - total_amount
-          - status
-```
-
-## Workflow
-
-1. Define cubes in `bonnard/cubes/*.yaml`
-2. Define views in `bonnard/views/*.yaml`
-3. Run `bon validate` to check syntax
-4. Run `bon deploy` to publish
-
-## Learn More
-
-Use `bon docs` for comprehensive documentation:
-
-```bash
-bon docs cubes.measures.types    # All 12 measure types
-bon docs cubes.dimensions.types  # All 6 dimension types
-bon docs cubes.joins             # Relationship types
-bon docs cubes.segments          # Predefined filters
-bon docs views.cubes             # View composition
-bon docs --search "rolling"      # Search for concepts
-```

package/dist/templates/cursor/rules/bonnard-cli.mdc

@@ -1,47 +0,0 @@
----
-description: "Bonnard CLI reference. Use when user needs help with bon commands, data sources, or deployments."
-alwaysApply: false
----
-
-# Bonnard CLI
-
-## Commands
-
-### Project Setup
-```bash
-bon init              # Initialize new project
-bon login             # Authenticate with Bonnard
-bon logout            # Clear credentials
-```
-
-### Data Sources
-```bash
-bon datasource add              # Add new data source (interactive)
-bon datasource list             # List all data sources
-bon datasource test <name>      # Test connection
-bon datasource remove <name>    # Remove data source
-```
-
-### Development
-```bash
-bon validate          # Validate cubes and views
-bon deploy            # Deploy to Bonnard
-```
-
-### Data Exploration (Local)
-```bash
-bon preview <datasource> "<sql>"              # Preview data with raw SQL
-bon preview <datasource> "<sql>" --format json  # JSON output
-bon preview <datasource> "<sql>" --limit 100    # Limit rows
-```
-
-### Semantic Layer Queries (Deployed)
-```bash
-# JSON format (default)
-bon query '{"measures": ["orders.count"]}'
-bon query '{"measures": ["orders.total_revenue"], "dimensions": ["orders.status"]}'
-
-# SQL format
-bon query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
-bon query --sql "SELECT city, SUM(amount) FROM orders GROUP BY 1" --limit 10
-```

package/dist/templates/cursor/rules/bonnard-queries.mdc

@@ -1,49 +0,0 @@
----
-description: "How to write queries and work with cubes and views. Use when user asks about metrics, dimensions, or data modeling."
-alwaysApply: false
----
-
-# Bonnard Query Patterns
-
-## Cube Structure (YAML)
-
-```yaml
-cubes:
-  - name: orders
-    sql: SELECT * FROM public.orders
-
-    measures:
-      - name: count
-        type: count
-      - name: total_amount
-        type: sum
-        sql: amount
-
-    dimensions:
-      - name: status
-        type: string
-        sql: status
-      - name: created_at
-        type: time
-        sql: created_at
-```
-
-## View Structure (YAML)
-
-```yaml
-views:
-  - name: orders_overview
-    cubes:
-      - join_path: orders
-        includes:
-          - count
-          - total_amount
-          - status
-```
-
-## Workflow
-
-1. Define cubes in `bonnard/cubes/*.yaml`
-2. Define views in `bonnard/views/*.yaml`
-3. Run `bon validate` to check syntax
-4. Run `bon deploy` to publish