@bonnard/cli 0.2.6 → 0.2.8

package/README.md

@@ -2,24 +2,26 @@
 
 The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Define metrics in YAML, validate locally, deploy, and query — from your terminal or AI coding agent.
 
-## Install
-
-```bash
-npm install -g @bonnard/cli
-```
-
-Requires Node.js 20+.
+**Open source** — [view source on GitHub](https://github.com/meal-inc/bonnard-cli)
 
 ## Quick start
 
 ```bash
-bon init                        # Create project structure + agent templates
+npx @bonnard/cli init           # Create project structure + agent templates
 bon datasource add --demo       # Add demo dataset (no warehouse needed)
 bon validate                    # Check syntax
 bon login                       # Authenticate with Bonnard
 bon deploy -m "Initial deploy"  # Deploy to Bonnard
 ```
 
+No install needed — `npx` runs the CLI directly. Or install globally for shorter commands:
+
+```bash
+npm install -g @bonnard/cli
+```
+
+Requires Node.js 20+.
+
 ## Commands
 
 | Command | Description |

package/dist/bin/bon.mjs

@@ -2698,11 +2698,11 @@ async function showOverview(client) {
 	console.log(pc.dim("  bon metabase explore collections"));
 	console.log(pc.dim("  bon metabase explore cards"));
 	console.log(pc.dim("  bon metabase explore dashboards"));
-	console.log(pc.dim("  bon metabase explore card <id>"));
-	console.log(pc.dim("  bon metabase explore dashboard <id>"));
-	console.log(pc.dim("  bon metabase explore database <id>"));
-	console.log(pc.dim("  bon metabase explore table <id>"));
-	console.log(pc.dim("  bon metabase explore collection <id>"));
+	console.log(pc.dim("  bon metabase explore card <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore dashboard <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore database <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore table <id-or-name>"));
+	console.log(pc.dim("  bon metabase explore collection <id-or-name>"));
 }
 async function showDatabases(client) {
 	const databases = await client.getDatabases();
@@ -2778,7 +2778,7 @@ async function showCards(client) {
 		console.log();
 	}
 	if (models.length === 0 && metrics.length === 0 && questions.length === 0) console.log(pc.dim("  No cards found."));
-	console.log(pc.dim("View details: bon metabase explore card <id>"));
+	console.log(pc.dim("View details: bon metabase explore card <id-or-name>"));
 }
 async function showCardDetail(client, id) {
 	const card = await client.getCard(id);
@@ -2835,7 +2835,7 @@ async function showDashboards(client) {
 	console.log(`  ${pc.dim(padColumn("ID", 6))}${pc.dim("NAME")}`);
 	for (const d of active) console.log(`  ${padColumn(String(d.id), 6)}${d.name}`);
 	console.log();
-	console.log(pc.dim("View details: bon metabase explore dashboard <id>"));
+	console.log(pc.dim("View details: bon metabase explore dashboard <id-or-name>"));
 }
 async function showDashboardDetail(client, id) {
 	const [dashboard, allCards] = await Promise.all([client.getDashboard(id), client.getCards()]);
@@ -2895,7 +2895,7 @@ async function showDatabaseDetail(client, id) {
 		}
 		console.log();
 	}
-	console.log(pc.dim("View table fields: bon metabase explore table <id>"));
+	console.log(pc.dim("View table fields: bon metabase explore table <id-or-name>"));
 }
 function classifyFieldType(field) {
 	const bt = field.base_type || "";
@@ -3008,8 +3008,105 @@ async function showCollectionDetail(client, id) {
 		console.log();
 	}
 	if (cardItems.length === 0 && dashboardItems.length === 0) console.log(pc.dim("  No items in this collection."));
-	console.log(pc.dim("View card SQL: bon metabase explore card <id>"));
-	console.log(pc.dim("View dashboard: bon metabase explore dashboard <id>"));
+	console.log(pc.dim("View card SQL: bon metabase explore card <id-or-name>"));
+	console.log(pc.dim("View dashboard: bon metabase explore dashboard <id-or-name>"));
+}
+function isNumericId(value) {
+	return /^\d+$/.test(value);
+}
+function showDisambiguation(resource, matches) {
+	console.error(pc.yellow(`Multiple ${resource}s match that name:\n`));
+	for (const m of matches) console.log(`  ${padColumn(String(m.id), 8)}${m.label}`);
+	console.log();
+	console.log(pc.dim(`Use the numeric ID to be specific: bon metabase explore ${resource} <id>`));
+	process.exit(1);
+}
+async function resolveCardId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const cards = await client.getCards();
+	const needle = input.toLowerCase();
+	const matches = cards.filter((c) => c.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No card found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("card", matches.map((c) => ({
+		id: c.id,
+		label: c.name
+	})));
+}
+async function resolveDashboardId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const dashboards = await client.getDashboards();
+	const needle = input.toLowerCase();
+	const matches = dashboards.filter((d) => d.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No dashboard found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("dashboard", matches.map((d) => ({
+		id: d.id,
+		label: d.name
+	})));
+}
+async function resolveDatabaseId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const databases = await client.getDatabases();
+	const needle = input.toLowerCase();
+	const matches = databases.filter((d) => d.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No database found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("database", matches.map((d) => ({
+		id: d.id,
+		label: `${d.name} (${d.engine})`
+	})));
+}
+async function resolveTableId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const databases = await client.getDatabases();
+	const needle = input.toLowerCase();
+	const matches = [];
+	for (const db of databases) {
+		const meta = await client.getDatabaseMetadata(db.id);
+		for (const t of meta.tables) {
+			if (t.visibility_type === "hidden" || t.visibility_type === "retired") continue;
+			if (t.name.toLowerCase().includes(needle)) matches.push({
+				id: t.id,
+				name: t.name,
+				schema: t.schema,
+				dbName: db.name
+			});
+		}
+	}
+	if (matches.length === 0) {
+		console.error(pc.red(`No table found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("table", matches.map((m) => ({
+		id: m.id,
+		label: `${m.dbName} / ${m.schema}.${m.name}`
+	})));
+}
+async function resolveCollectionId(client, input) {
+	if (isNumericId(input)) return parseInt(input, 10);
+	const collections = await client.getCollections();
+	const needle = input.toLowerCase();
+	const matches = collections.filter((c) => typeof c.id === "number" && c.name?.toLowerCase().includes(needle));
+	if (matches.length === 0) {
+		console.error(pc.red(`No collection found matching "${input}"`));
+		process.exit(1);
+	}
+	if (matches.length === 1) return matches[0].id;
+	showDisambiguation("collection", matches.map((c) => ({
+		id: c.id,
+		label: c.name
+	})));
 }
 const RESOURCES = [
 	"databases",
@@ -3047,71 +3144,41 @@ async function metabaseExploreCommand(resource, id) {
 			case "dashboards":
 				await showDashboards(client);
 				break;
-			case "card": {
+			case "card":
 				if (!id) {
-					console.error(pc.red("Card ID required: bon metabase explore card <id>"));
+					console.error(pc.red("Usage: bon metabase explore card <id-or-name>"));
 					process.exit(1);
 				}
-				const cardId = parseInt(id, 10);
-				if (isNaN(cardId)) {
-					console.error(pc.red(`Invalid card ID: ${id}`));
-					process.exit(1);
-				}
-				await showCardDetail(client, cardId);
+				await showCardDetail(client, await resolveCardId(client, id));
 				break;
-			}
-			case "dashboard": {
+			case "dashboard":
 				if (!id) {
-					console.error(pc.red("Dashboard ID required: bon metabase explore dashboard <id>"));
+					console.error(pc.red("Usage: bon metabase explore dashboard <id-or-name>"));
 					process.exit(1);
 				}
-				const dashId = parseInt(id, 10);
-				if (isNaN(dashId)) {
-					console.error(pc.red(`Invalid dashboard ID: ${id}`));
-					process.exit(1);
-				}
-				await showDashboardDetail(client, dashId);
+				await showDashboardDetail(client, await resolveDashboardId(client, id));
 				break;
-			}
-			case "database": {
+			case "database":
 				if (!id) {
-					console.error(pc.red("Database ID required: bon metabase explore database <id>"));
-					process.exit(1);
-				}
-				const dbId = parseInt(id, 10);
-				if (isNaN(dbId)) {
-					console.error(pc.red(`Invalid database ID: ${id}`));
+					console.error(pc.red("Usage: bon metabase explore database <id-or-name>"));
 					process.exit(1);
 				}
-				await showDatabaseDetail(client, dbId);
+				await showDatabaseDetail(client, await resolveDatabaseId(client, id));
 				break;
-			}
-			case "table": {
+			case "table":
 				if (!id) {
-					console.error(pc.red("Table ID required: bon metabase explore table <id>"));
+					console.error(pc.red("Usage: bon metabase explore table <id-or-name>"));
 					process.exit(1);
 				}
-				const tableId = parseInt(id, 10);
-				if (isNaN(tableId)) {
-					console.error(pc.red(`Invalid table ID: ${id}`));
-					process.exit(1);
-				}
-				await showTableDetail(client, tableId);
+				await showTableDetail(client, await resolveTableId(client, id));
 				break;
-			}
-			case "collection": {
+			case "collection":
 				if (!id) {
-					console.error(pc.red("Collection ID required: bon metabase explore collection <id>"));
+					console.error(pc.red("Usage: bon metabase explore collection <id-or-name>"));
 					process.exit(1);
 				}
-				const colId = parseInt(id, 10);
-				if (isNaN(colId)) {
-					console.error(pc.red(`Invalid collection ID: ${id}`));
-					process.exit(1);
-				}
-				await showCollectionDetail(client, colId);
+				await showCollectionDetail(client, await resolveCollectionId(client, id));
 				break;
-			}
 		}
 	} catch (err) {
 		if (err instanceof MetabaseApiError) {
@@ -3454,10 +3521,10 @@ function buildReport(data) {
 	report += `5. **Collection Structure** → Map collections to views (one view per business domain)\n`;
 	report += `6. **Table Inventory** → Use field classification (dims/measures/time) to build each cube\n\n`;
 	report += `Drill deeper with:\n`;
-	report += `- \`bon metabase explore table <id>\` — field types and classification\n`;
-	report += `- \`bon metabase explore card <id>\` — SQL and columns\n`;
-	report += `- \`bon metabase explore collection <id>\` — cards in a collection\n`;
-	report += `- \`bon metabase explore database <id>\` — schemas and tables\n\n`;
+	report += `- \`bon metabase explore table <id-or-name>\` — field types and classification\n`;
+	report += `- \`bon metabase explore card <id-or-name>\` — SQL and columns\n`;
+	report += `- \`bon metabase explore collection <id-or-name>\` — cards in a collection\n`;
+	report += `- \`bon metabase explore database <id-or-name>\` — schemas and tables\n\n`;
 	report += `## Summary\n\n`;
 	report += `| Metric | Count |\n|--------|-------|\n`;
 	report += `| Databases | ${databases.length} |\n`;
@@ -3497,7 +3564,7 @@ function buildReport(data) {
 	report += "```\n\n";
 	report += `## Top ${topCards.length} Cards by Activity\n\n`;
 	report += `Ranked by view count, weighted by recency. Cards not used in the last ${INACTIVE_MONTHS} months are penalized 90%.\n`;
-	report += `Use \`bon metabase explore card <id>\` to view SQL and column details for any card.\n\n`;
+	report += `Use \`bon metabase explore card <id-or-name>\` to view SQL and column details for any card.\n\n`;
 	report += `| Rank | ID | Views | Last Used | Active | Pattern | Type | Display | Collection | Name |\n`;
 	report += `|------|----|-------|-----------|--------|---------|------|---------|------------|------|\n`;
 	for (let i = 0; i < topCards.length; i++) {
@@ -3555,8 +3622,18 @@ function buildReport(data) {
 		const sortedRefs = Array.from(globalTableRefs.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20);
 		report += `## Most Referenced Tables (from SQL)\n\n`;
 		report += `Tables most frequently referenced in FROM/JOIN clauses across all cards.\n\n`;
-		report += `| Table | References |\n|-------|------------|\n`;
-		for (const [table, count] of sortedRefs) report += `| ${table} | ${count} |\n`;
+		const tableIdByRef = /* @__PURE__ */ new Map();
+		for (const db of databases) for (const t of db.tables) {
+			const qualified = `${t.schema}.${t.name}`.toLowerCase();
+			const unqualified = t.name.toLowerCase();
+			if (!tableIdByRef.has(qualified)) tableIdByRef.set(qualified, t.id);
+			if (!tableIdByRef.has(unqualified)) tableIdByRef.set(unqualified, t.id);
+		}
+		report += `| ID | Table | References |\n|------|-------|------------|\n`;
+		for (const [table, count] of sortedRefs) {
+			const tid = tableIdByRef.get(table);
+			report += `| ${tid ?? "—"} | ${table} | ${count} |\n`;
+		}
 		report += `\n`;
 	}
 	const fieldIdLookup = /* @__PURE__ */ new Map();
@@ -3656,9 +3733,9 @@ function buildReport(data) {
 			report += `### ${db.name} / ${schema} (${referenced.length} referenced`;
 			if (unreferenced > 0) report += `, ${unreferenced} unreferenced`;
 			report += `)\n\n`;
-			report += `| Table | Fields | Dims | Measures | Time | Refs |\n`;
-			report += `|-------|--------|------|----------|------|------|\n`;
-			for (const s of referenced) report += `| ${s.name} | ${s.fieldCount} | ${s.dimensions} | ${s.measures} | ${s.timeDimensions} | ${s.refCount} |\n`;
+			report += `| ID | Table | Fields | Dims | Measures | Time | Refs |\n`;
+			report += `|------|-------|--------|------|----------|------|------|\n`;
+			for (const s of referenced) report += `| ${s.id} | ${s.name} | ${s.fieldCount} | ${s.dimensions} | ${s.measures} | ${s.timeDimensions} | ${s.refCount} |\n`;
 			if (unreferenced > 0) skippedTables += unreferenced;
 			report += `\n`;
 		}

package/dist/docs/topics/cli.md

@@ -4,6 +4,22 @@
 
 The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Initialize a project, connect your warehouse, define metrics in YAML, validate locally, and deploy — all from your terminal or your AI coding agent.
 
+## Install
+
+Run directly with `npx` — no install needed:
+
+```bash
+npx @bonnard/cli init
+```
+
+Or install globally for shorter commands:
+
+```bash
+npm install -g @bonnard/cli
+```
+
+Requires Node.js 20+.
+
 ## Agent-ready from the start
 
 `bon init` generates context files for your AI coding tools automatically:

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

@@ -1,4 +1,4 @@
-# dashboards.components
+# Components
 
 > Chart and display components for rendering query results in dashboards.
 
@@ -6,6 +6,15 @@
 
 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.
 
+Choose the component that best fits your data:
+
+- **BigValue** — single KPI number (total revenue, order count)
+- **LineChart** — trends over time
+- **BarChart** — comparing categories (vertical or horizontal)
+- **AreaChart** — cumulative or stacked trends
+- **PieChart** — proportional breakdown (best with 5-7 slices)
+- **DataTable** — detailed rows for drilling into data
+
 ## Syntax
 
 ```markdown
@@ -32,53 +41,68 @@ Displays a single KPI metric as a large number.
 | `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 |
+| `fmt` | string | No | Format preset or Excel code (e.g. `fmt="eur2"`, `fmt="$#,##0.00"`) |
 
 ### LineChart
 
-Renders a line chart, typically for time series.
+Renders a line chart, typically for time series. Supports multiple y columns and series splitting.
 
 ```markdown
 <LineChart data={monthly_revenue} x="created_at" y="total_revenue" title="Revenue Trend" />
+<LineChart data={trend} x="date" y="revenue,cases" />
+<LineChart data={revenue_by_type} x="created_at" y="total_revenue" series="type" />
 ```
 
 | 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) |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
 | `title` | string | No | Chart title |
+| `series` | string | No | Column to split data into separate colored lines |
+| `type` | string | No | `"stacked"` for stacked lines (default: no stacking) |
+| `yFmt` | string | No | Format preset or Excel code for tooltip values (e.g. `yFmt="eur2"`) |
 
 ### BarChart
 
-Renders a vertical bar chart. Add `horizontal` for horizontal bars.
+Renders a vertical bar chart. Add `horizontal` for horizontal bars. Supports multi-series with stacked or grouped display.
 
 ```markdown
 <BarChart data={revenue_by_city} x="city" y="total_revenue" />
 <BarChart data={revenue_by_city} x="city" y="total_revenue" horizontal />
+<BarChart data={revenue_by_type} x="month" y="total_revenue" series="type" />
+<BarChart data={revenue_by_type} x="month" y="total_revenue" series="type" type="grouped" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for category axis |
-| `y` | string | Yes | Field for value axis |
+| `y` | string | Yes | Field(s) for value axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
 | `title` | string | No | Chart title |
 | `horizontal` | boolean | No | Render as horizontal bar chart |
+| `series` | string | No | Column to split data into separate colored bars |
+| `type` | string | No | `"stacked"` (default) or `"grouped"` for multi-series display |
+| `yFmt` | string | No | Format preset or Excel code for tooltip values (e.g. `yFmt="usd"`) |
 
 ### AreaChart
 
-Renders a filled area chart.
+Renders a filled area chart. Supports series splitting and stacked areas.
 
 ```markdown
 <AreaChart data={monthly_revenue} x="created_at" y="total_revenue" />
+<AreaChart data={revenue_by_source} x="created_at" y="total_revenue" series="source" type="stacked" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for x-axis |
-| `y` | string | Yes | Field for y-axis |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
 | `title` | string | No | Chart title |
+| `series` | string | No | Column to split data into separate colored areas |
+| `type` | string | No | `"stacked"` for stacked areas (default: no stacking) |
+| `yFmt` | string | No | Format preset or Excel code for tooltip values (e.g. `yFmt="pct1"`) |
 
 ### PieChart
 
@@ -97,11 +121,13 @@ Renders a pie/donut chart.
 
 ### DataTable
 
-Renders query results as a table.
+Renders query results as a sortable, paginated table. Click any column header to sort ascending/descending.
 
 ```markdown
 <DataTable data={top_products} />
 <DataTable data={top_products} columns="name,revenue,count" />
+<DataTable data={top_products} rows="25" />
+<DataTable data={top_products} rows="all" />
 ```
 
 | Prop | Type | Required | Description |
@@ -109,8 +135,28 @@ Renders query results as a table.
 | `data` | query ref | Yes | Query name |
 | `columns` | string | No | Comma-separated list of columns to show (default: all) |
 | `title` | string | No | Table title |
+| `fmt` | string | No | Column format map: `fmt="revenue:eur2,date:shortdate"` |
+| `rows` | string | No | Rows per page. Default `10`. Use `rows="all"` to disable pagination. |
+
+**Sorting:** Click a column header to sort ascending. Click again to sort descending. Null values always sort to the end. Numbers sort numerically, strings sort case-insensitively.
+
+**Formatting:** Numbers right-align with tabular figures. Dates auto-detect and won't wrap. Use `fmt` for explicit formatting per column.
+
+## Layout
+
+### Auto BigValue Grouping
+
+Consecutive `<BigValue>` components are automatically wrapped in a responsive grid — no `<Grid>` tag needed:
+
+```markdown
+<BigValue data={total_revenue} value="total_revenue" title="Revenue" />
+<BigValue data={order_count} value="count" title="Orders" />
+<BigValue data={avg_order} value="avg_order_value" title="Avg Order" />
+```
+
+This renders as a 3-column row. The grid auto-sizes up to 4 columns based on the number of consecutive BigValues. For more control, use an explicit `<Grid>` tag.
 
-## Layout: Grid
+### Grid
 
 Wrap components in a `<Grid>` tag to arrange them in columns:
 
@@ -126,12 +172,56 @@ Wrap components in a `<Grid>` tag to arrange them in columns:
 |------|------|---------|-------------|
 | `cols` | string | `"2"` | Number of columns in the grid |
 
+## Formatting
+
+Values are auto-formatted by default — numbers get locale grouping (1,234.56), dates display as "13 Jan 2025", and nulls show as "—". Override with named presets for common currencies and percentages, or use raw Excel format codes for full control.
+
+### Format Presets
+
+| Preset | Excel code | Example output |
+|--------|-----------|---------------|
+| `num0` | `#,##0` | 1,234 |
+| `num1` | `#,##0.0` | 1,234.6 |
+| `num2` | `#,##0.00` | 1,234.56 |
+| `usd` | `$#,##0` | $1,234 |
+| `usd2` | `$#,##0.00` | $1,234.56 |
+| `eur` | `#,##0 "€"` | 1,234 € |
+| `eur2` | `#,##0.00 "€"` | 1,234.56 € |
+| `gbp` | `£#,##0` | £1,234 |
+| `gbp2` | `£#,##0.00` | £1,234.56 |
+| `chf` | `"CHF "#,##0` | CHF 1,234 |
+| `chf2` | `"CHF "#,##0.00` | CHF 1,234.56 |
+| `pct` | `0%` | 45% |
+| `pct1` | `0.0%` | 45.1% |
+| `pct2` | `0.00%` | 45.12% |
+| `shortdate` | `d mmm yyyy` | 13 Jan 2025 |
+| `longdate` | `d mmmm yyyy` | 13 January 2025 |
+| `monthyear` | `mmm yyyy` | Jan 2025 |
+
+Any string that isn't a preset name is treated as a raw Excel format code (ECMA-376). For example: `fmt="revenue:$#,##0.00"`.
+
+Note: Percentage presets (`pct`, `pct1`, `pct2`) multiply by 100 per Excel convention — 0.45 displays as "45%".
+
+### Usage Examples
+
+```markdown
+<!-- BigValue with currency -->
+<BigValue data={total_revenue} value="total_revenue" title="Revenue" fmt="eur2" />
+
+<!-- DataTable with per-column formatting -->
+<DataTable data={sales} fmt="total_revenue:usd2,created_at:shortdate,margin:pct1" />
+
+<!-- Chart with formatted tooltips -->
+<BarChart data={monthly} x="month" y="revenue" yFmt="usd" />
+<LineChart data={trend} x="date" y="growth" yFmt="pct1" />
+```
+
 ## 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
+- [Queries](dashboards.queries) — query syntax and properties
+- [Examples](dashboards.examples) — complete dashboard examples
+- [Dashboards](dashboards) — overview and deployment

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

@@ -1,10 +1,10 @@
-# dashboards.examples
+# Examples
 
 > Complete dashboard examples showing common patterns.
 
 ## Revenue Overview Dashboard
 
-A KPI + trend + breakdown dashboard:
+The most common dashboard pattern: KPI cards at the top for at-a-glance metrics, a time series chart for trends, and a bar chart with data table for category breakdown.
 
 ```markdown
 ---
@@ -64,7 +64,7 @@ orderBy:
 
 ## Sales Pipeline Dashboard
 
-Filtered data with pie chart:
+A status-focused dashboard using a pie chart for proportional breakdown, a horizontal bar chart for ranking, and filters to drill into a specific segment.
 
 ```markdown
 ---
@@ -114,6 +114,161 @@ filters:
 <AreaChart data={completed_trend} x="created_at" y="total_revenue" title="Completed Order Revenue" />
 ```
 
+## Multi-Series Dashboard
+
+When you need to compare segments side-by-side, use the `series` prop to split data by a dimension into colored segments. This example shows stacked bars, grouped bars, multi-line, and stacked area — all from the same data.
+
+```markdown
+---
+title: Revenue by Channel
+description: Multi-series charts showing revenue breakdown by sales channel
+---
+
+# Revenue by Channel
+
+` ``query revenue_by_channel
+cube: orders
+measures: [total_revenue]
+dimensions: [channel]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+## Stacked Bar (default)
+
+<BarChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" title="Revenue by Channel" />
+
+## Grouped Bar
+
+<BarChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" type="grouped" title="Revenue by Channel (Grouped)" />
+
+## Multi-Line
+
+` ``query trend
+cube: orders
+measures: [total_revenue, count]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+<LineChart data={trend} x="created_at" y="total_revenue,count" title="Revenue vs Orders" />
+
+## Stacked Area by Channel
+
+<AreaChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" type="stacked" title="Revenue by Channel" />
+```
+
+## Formatted Dashboard
+
+Use format presets to display currencies, percentages, and number styles consistently across KPIs, charts, and tables.
+
+```markdown
+---
+title: Sales Performance
+description: Formatted revenue metrics and trends
+---
+
+# Sales Performance
+
+` ``query totals
+cube: orders
+measures: [total_revenue, count, avg_order_value]
+` ``
+
+<Grid cols="3">
+<BigValue data={totals} value="total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={totals} value="count" title="Orders" fmt="num0" />
+<BigValue data={totals} value="avg_order_value" title="Avg Order" fmt="eur2" />
+</Grid>
+
+## Revenue Trend
+
+` ``query monthly
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+<LineChart data={monthly} x="created_at" y="total_revenue" title="Monthly Revenue" yFmt="eur" />
+
+## Detail Table
+
+` ``query details
+cube: orders
+measures: [total_revenue, count]
+dimensions: [category]
+orderBy:
+  total_revenue: desc
+` ``
+
+<DataTable data={details} fmt="total_revenue:eur2,count:num0" />
+```
+
+## Interactive Dashboard
+
+Combine a DateRange picker and Dropdown filter to let viewers explore the data. Filter state syncs to the URL, so shared links preserve the exact filtered view.
+
+```markdown
+---
+title: Interactive Sales
+description: Sales dashboard with date and channel filters
+---
+
+# Interactive Sales
+
+<DateRange name="period" default="last-6-months" label="Time Period" />
+<Dropdown name="channel" dimension="channel" data={channels} queries="trend,by_city" label="Channel" />
+
+` ``query channels
+cube: orders
+dimensions: [channel]
+` ``
+
+` ``query kpis
+cube: orders
+measures: [total_revenue, count]
+` ``
+
+<Grid cols="2">
+<BigValue data={kpis} value="total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={kpis} value="count" title="Orders" fmt="num0" />
+</Grid>
+
+## Revenue Trend
+
+` ``query trend
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+` ``
+
+<LineChart data={trend} x="created_at" y="total_revenue" title="Monthly Revenue" yFmt="eur" />
+
+## By City
+
+` ``query by_city
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+orderBy:
+  total_revenue: desc
+limit: 10
+` ``
+
+<BarChart data={by_city} x="city" y="total_revenue" title="Top Cities" yFmt="eur" />
+```
+
+The `<DateRange>` automatically applies to all queries with a `timeDimension` (here: `trend`). The `<Dropdown>` filters `trend` and `by_city` by channel. The `channels` query populates the dropdown and is never filtered by it.
+
 ## Tips
 
 - **Start with KPIs**: Use `BigValue` in a `Grid` at the top for key metrics
@@ -122,9 +277,11 @@ filters:
 - **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
+- **Multi-series**: Use `series="column"` to split data by a dimension. For bars, default is stacked; use `type="grouped"` for side-by-side
+- **Multiple y columns**: Use comma-separated values like `y="revenue,cases"` to show multiple measures on one chart
 
 ## See Also
 
-- dashboards
-- dashboards.queries
-- dashboards.components
+- [Dashboards](dashboards) — overview and deployment
+- [Queries](dashboards.queries) — query syntax and properties
+- [Components](dashboards.components) — chart and display components

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

@@ -0,0 +1,179 @@
+# Inputs
+
+> Interactive filter inputs for dashboards — date range pickers and dropdown selectors.
+
+## Overview
+
+Inputs add interactivity to dashboards. They render as a filter bar above the charts and re-execute queries when values change. Inspired by Evidence.dev's inputs pattern, adapted for the Cube semantic layer.
+
+Two input types are available:
+
+- **DateRange** — preset date range picker that overrides `timeDimension.dateRange`
+- **Dropdown** — dimension value selector that adds/replaces filters
+
+## DateRange
+
+Renders a date range preset picker. When changed, overrides `timeDimension.dateRange` on targeted queries.
+
+```markdown
+<DateRange name="period" default="last-6-months" label="Time Period" />
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | Yes | Unique input name |
+| `default` | preset key | No | Initial preset (default: `last-6-months`) |
+| `label` | string | No | Label shown above the picker |
+| `queries` | string | No | Comma-separated query names to target |
+
+### Targeting
+
+Targeting lets you control which queries a filter affects — useful when some charts should stay fixed while others respond to filter changes.
+
+- **No `queries` prop** — applies to ALL queries that have a `timeDimension`
+- **With `queries` prop** — only applies to the listed queries
+
+### Presets
+
+| Key | Label |
+|-----|-------|
+| `last-7-days` | Last 7 Days |
+| `last-30-days` | Last 30 Days |
+| `last-3-months` | Last 3 Months |
+| `last-6-months` | Last 6 Months |
+| `last-12-months` | Last 12 Months |
+| `month-to-date` | Month to Date |
+| `year-to-date` | Year to Date |
+| `last-year` | Last Year |
+| `all-time` | All Time |
+
+## Dropdown
+
+Renders a dropdown selector populated from a query's dimension values. Adds a filter on the specified dimension to targeted queries.
+
+```markdown
+<Dropdown name="channel" dimension="channel" data={channels} queries="main,trend" label="Channel" />
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | Yes | Unique input name |
+| `dimension` | string | Yes | Dimension to filter on |
+| `data` | query ref | Yes | Query that provides the dropdown options |
+| `queries` | string | Yes | Comma-separated query names to filter |
+| `label` | string | No | Label shown above the dropdown |
+| `default` | string | No | Initial selected value (default: All) |
+
+### Behavior
+
+- Always includes an "All" option that removes the filter
+- The dropdown's own `data` query is never filtered by itself (prevents circular dependencies)
+- `queries` is required — the dropdown only filters explicitly listed queries
+
+## Examples
+
+### DateRange only
+
+```markdown
+---
+title: Revenue Trends
+---
+
+<DateRange name="period" default="last-6-months" label="Time Period" />
+
+` ``query monthly_revenue
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+` ``
+
+<LineChart data={monthly_revenue} x="created_at" y="total_revenue" />
+```
+
+The DateRange automatically applies to `monthly_revenue` because it has a `timeDimension`. No hardcoded `dateRange` needed in the query.
+
+### Dropdown with query binding
+
+```markdown
+---
+title: Sales by Channel
+---
+
+` ``query channels
+cube: orders
+dimensions: [channel]
+` ``
+
+<Dropdown name="ch" dimension="channel" data={channels} queries="main" label="Channel" />
+
+` ``query main
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+` ``
+
+<BarChart data={main} x="city" y="total_revenue" />
+```
+
+### Combined inputs
+
+```markdown
+---
+title: Sales Dashboard
+---
+
+<DateRange name="period" default="last-6-months" label="Time Period" />
+<Dropdown name="channel" dimension="channel" data={channels} queries="trend,by_city" label="Channel" />
+
+` ``query channels
+cube: orders
+dimensions: [channel]
+` ``
+
+` ``query trend
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+` ``
+
+<LineChart data={trend} x="created_at" y="total_revenue" />
+
+` ``query by_city
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+` ``
+
+<BarChart data={by_city} x="city" y="total_revenue" />
+```
+
+Both inputs work together: the DateRange scopes the time window on `trend` (which has a timeDimension), and the Dropdown filters both `trend` and `by_city` by channel.
+
+## Shareable URLs
+
+Input values automatically sync to URL query params. When a user changes a filter, the URL updates to reflect the current state — for example:
+
+```
+/dashboards/sales?period=last-30-days&channel=Online
+```
+
+- **Default values are omitted** from the URL for clean links
+- **Sharing a URL** preserves the current filter state — recipients see exactly the same filtered view
+- **Refreshing the page** restores the active filters from the URL
+- The **Copy Link** button in the dashboard header copies the full URL including filter params
+
+DateRange inputs store the preset key (e.g. `last-30-days`), so shared URLs stay relative to today. Dropdown inputs store the selected value string.
+
+## See Also
+
+- [Dashboards](dashboards) — overview and deployment
+- [Components](dashboards.components) — chart and display components
+- [Examples](dashboards.examples) — complete dashboard examples

package/dist/docs/topics/dashboards.md

@@ -1,10 +1,12 @@
-# dashboards
+# 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.
+Dashboards let your team track key metrics without leaving the Bonnard app. Define queries once in markdown, deploy them, and every viewer gets live, governed data — no separate BI tool needed. Filters, formatting, and layout are all declared in the same file.
+
+A dashboard is a markdown file with YAML frontmatter, query blocks, and chart components. Write it as a `.md` file, deploy with `bon dashboard deploy`, and view it in the Bonnard web app.
 
 ## Format
 
@@ -60,6 +62,8 @@ slug: revenue-dashboard         # Optional (derived from title if omitted)
 
 ## Deployment
 
+Deploy from the command line or via MCP tools. Each deploy auto-versions the dashboard so you can roll back if needed.
+
 ```bash
 # Deploy a single dashboard
 bon dashboard deploy revenue.md
@@ -76,8 +80,38 @@ bon dashboard remove revenue-dashboard
 
 Via MCP tools, agents can use `deploy_dashboard` with the markdown content as a string.
 
+## Versioning
+
+Every deployment auto-increments the version number and saves a snapshot. You can view version history and restore previous versions:
+
+```bash
+# Via MCP tools:
+# get_dashboard with version parameter to fetch a specific version
+# deploy_dashboard with slug + restore_version to roll back
+```
+
+Restoring a version creates a new version (e.g. restoring v2 from v5 creates v6 with v2's content). Version history is never deleted — only `remove_dashboard` deletes all history.
+
+## Sharing
+
+Dashboard viewers include a **Share** menu in the header with:
+
+- **Copy link** — copies the current URL including any active filter state
+- **Print to PDF** — opens the browser print dialog for PDF export
+
+Filter state (DateRange presets, Dropdown selections) is encoded in URL query params, so shared links preserve the exact filtered view the sender was looking at.
+
+## Governance
+
+Dashboard queries respect the same governance policies as all other queries. When a user views a dashboard:
+
+- **View-level access** — users only see data from views their governance groups allow
+- **Row-level filtering** — user attributes (e.g. region, department) automatically filter query results
+- All org members see the same dashboard list, but may see different data depending on their governance context
+
 ## See Also
 
-- dashboards.queries
-- dashboards.components
-- dashboards.examples
+- [Queries](dashboards.queries) — query syntax and properties
+- [Components](dashboards.components) — chart and display components
+- [Inputs](dashboards.inputs) — interactive filters
+- [Examples](dashboards.examples) — complete dashboard examples

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

@@ -1,10 +1,12 @@
-# dashboards.queries
+# 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}`.
+Each query fetches data from your semantic layer and makes it available to chart components. Queries use the same measures and dimensions defined in your cubes and views — field names stay consistent whether you're querying from a dashboard, MCP, or the API.
+
+Query blocks have a unique name and map to a `QueryOptions` shape. Components reference them using `data={query_name}`. Field names are unqualified — use `count` not `orders.count` — because the `cube` property provides the context.
 
 ## Syntax
 
@@ -112,6 +114,6 @@ filters:
 
 ## See Also
 
-- dashboards.components
-- dashboards
-- workflow.query
+- [Components](dashboards.components) — chart and display components
+- [Dashboards](dashboards) — overview and deployment
+- [Querying](querying) — query format reference

package/dist/docs/topics/views.md

@@ -6,7 +6,7 @@
 
 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.
+**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`). Build as many views as your audiences need, but make each one purposeful — governance policies control which views each user or role can access.
 
 ## Example
 

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

@@ -30,10 +30,11 @@ 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.
+**Why this matters:** A semantic layer built from questions produces focused,
+audience-scoped views. One built from tables produces generic views that agents
+struggle to choose between. Governance policies control which views each user
+or role can access, so build as many views as your audiences need — but make
+each one purposeful with clear descriptions.
 
 ## Principle 2: Views Are for Audiences, Not Tables
 

package/dist/templates/cursor/rules/bonnard-design-guide.mdc

@@ -29,10 +29,11 @@ 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.
+**Why this matters:** A semantic layer built from questions produces focused,
+audience-scoped views. One built from tables produces generic views that agents
+struggle to choose between. Governance policies control which views each user
+or role can access, so build as many views as your audiences need — but make
+each one purposeful with clear descriptions.
 
 ## Principle 2: Views Are for Audiences, Not Tables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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/overview.md ../content/getting-started.md dist/docs/topics/ && cp ../content/modeling/*.md dist/docs/topics/",
+    "build": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin && cp -r src/templates dist/ && mkdir -p dist/docs/topics dist/docs/schemas && cp ../content/index.md dist/docs/_index.md && cp ../content/overview.md ../content/getting-started.md dist/docs/topics/ && cp ../content/modeling/*.md dist/docs/topics/ && cp ../content/dashboards/*.md dist/docs/topics/",
     "dev": "tsdown src/bin/bon.ts --format esm --out-dir dist/bin --watch",
     "test": "vitest run"
   },
@@ -27,6 +27,11 @@
     "tsdown": "^0.20.1",
     "vitest": "^2.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meal-inc/bonnard-cli.git"
+  },
+  "license": "MIT",
   "engines": {
     "node": ">=20.0.0"
   }