@bonnard/cli 0.2.15 → 0.2.16

package/README.md

@@ -98,7 +98,7 @@ Agent support:
 Set up your MCP server so agents can query your semantic layer directly:
 
 ```bash
-bon mcp setup                 # Configure MCP server
+bon mcp                       # Show MCP server setup instructions
 bon mcp test                  # Verify the connection
 ```
 
@@ -172,7 +172,7 @@ Handles automatic datasource synchronisation and skips interactive prompts. Fits
 | `bon diff` | Preview changes before deploying |
 | `bon annotate` | Add metadata and descriptions to models |
 | `bon query` | Run queries from the terminal (JSON or SQL) |
-| `bon mcp setup` | Configure MCP server for agent access |
+| `bon mcp` | Show MCP server setup instructions |
 | `bon mcp test` | Test MCP connection |
 | `bon docs` | Browse or search documentation from the CLI |
 | `bon login` / `bon logout` | Manage authentication |

package/dist/bin/bon.mjs

@@ -13,6 +13,8 @@ import YAML from "yaml";
 import http from "node:http";
 import crypto from "node:crypto";
 import { encode } from "@toon-format/toon";
+import { createInterface } from "node:readline";
+import open from "open";
 
 //#region \0rolldown/runtime.js
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -611,10 +613,12 @@ function createAgentTemplates(cwd, env) {
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-get-started"), { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-design-guide"), { recursive: true });
+	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-build-dashboard"), { recursive: true });
 	writeTemplateFile(sharedBonnard, path.join(claudeRulesDir, "bonnard.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(claudeSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(claudeSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(claudeSkillsDir, "bonnard-design-guide", "SKILL.md"), createdFiles);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-build-dashboard/SKILL.md"), path.join(claudeSkillsDir, "bonnard-build-dashboard", "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 });
@@ -622,14 +626,17 @@ function createAgentTemplates(cwd, env) {
 	writeTemplateFile(loadTemplate("cursor/rules/bonnard-get-started.mdc"), path.join(cursorRulesDir, "bonnard-get-started.mdc"), createdFiles);
 	writeTemplateFile(loadTemplate("cursor/rules/bonnard-metabase-migrate.mdc"), path.join(cursorRulesDir, "bonnard-metabase-migrate.mdc"), createdFiles);
 	writeTemplateFile(loadTemplate("cursor/rules/bonnard-design-guide.mdc"), path.join(cursorRulesDir, "bonnard-design-guide.mdc"), createdFiles);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-build-dashboard.mdc"), path.join(cursorRulesDir, "bonnard-build-dashboard.mdc"), createdFiles);
 	const codexSkillsDir = path.join(cwd, ".agents", "skills");
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-get-started"), { recursive: true });
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-design-guide"), { recursive: true });
+	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-build-dashboard"), { recursive: true });
 	writeTemplateFile(sharedBonnard, path.join(cwd, "AGENTS.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(codexSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(codexSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), createdFiles);
 	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(codexSkillsDir, "bonnard-design-guide", "SKILL.md"), createdFiles);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-build-dashboard/SKILL.md"), path.join(codexSkillsDir, "bonnard-build-dashboard", "SKILL.md"), createdFiles);
 	return createdFiles;
 }
 async function initCommand() {
@@ -670,12 +677,12 @@ async function initCommand() {
 
 //#endregion
 //#region src/commands/login.ts
-const APP_URL = process.env.BON_APP_URL || "https://app.bonnard.dev";
+const APP_URL$3 = process.env.BON_APP_URL || "https://app.bonnard.dev";
 const TIMEOUT_MS = 120 * 1e3;
 async function loginCommand() {
 	const state = crypto.randomUUID();
 	const { port, close } = await startCallbackServer(state);
-	const url = `${APP_URL}/auth/device?state=${state}&port=${port}`;
+	const url = `${APP_URL$3}/auth/device?state=${state}&port=${port}`;
 	console.log(pc.dim(`Opening browser to ${url}`));
 	const open = (await import("open")).default;
 	await open(url);
@@ -3870,6 +3877,140 @@ async function keysRevokeCommand(nameOrPrefix) {
 	}
 }
 
+//#endregion
+//#region src/commands/dashboard/deploy.ts
+const APP_URL$2 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+/**
+* Extract <title> content from HTML string
+*/
+function extractTitle(html) {
+	const match = html.match(/<title[^>]*>(.*?)<\/title>/is);
+	return match ? match[1].trim() : null;
+}
+/**
+* Derive slug from filename: strip extension, lowercase, replace non-alphanumeric with hyphens
+*/
+function slugFromFilename(filename) {
+	return path.basename(filename, path.extname(filename)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+async function dashboardDeployCommand(file, options) {
+	const filePath = path.resolve(file);
+	if (!fs.existsSync(filePath)) {
+		console.error(pc.red(`File not found: ${file}`));
+		process.exit(1);
+	}
+	const content = fs.readFileSync(filePath, "utf-8");
+	if (content.length > 2 * 1024 * 1024) {
+		console.error(pc.red("File exceeds 2MB limit."));
+		process.exit(1);
+	}
+	const slug = options.slug || slugFromFilename(file);
+	const title = options.title || extractTitle(content) || slug;
+	console.log(pc.dim(`Deploying dashboard "${slug}"...`));
+	try {
+		const dashboard = (await post("/api/dashboards", {
+			slug,
+			title,
+			content
+		})).dashboard;
+		const url = `${APP_URL$2}/d/${dashboard.org_slug}/${dashboard.slug}`;
+		console.log(pc.green(`Dashboard deployed successfully`));
+		console.log();
+		console.log(`  ${pc.bold("Slug")}     ${dashboard.slug}`);
+		console.log(`  ${pc.bold("Title")}    ${dashboard.title}`);
+		console.log(`  ${pc.bold("Version")}  ${dashboard.version}`);
+		console.log(`  ${pc.bold("URL")}      ${url}`);
+	} catch (err) {
+		console.error(pc.red(`Deploy failed: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/list.ts
+const APP_URL$1 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+async function dashboardListCommand() {
+	try {
+		const dashboards = (await get("/api/dashboards")).dashboards;
+		if (dashboards.length === 0) {
+			console.log(pc.dim("No dashboards deployed yet. Run `bon dashboard deploy <file>` to publish."));
+			return;
+		}
+		const slugWidth = Math.max(4, ...dashboards.map((d) => d.slug.length));
+		const titleWidth = Math.max(5, ...dashboards.map((d) => d.title.length));
+		const versionWidth = 7;
+		const dateWidth = 10;
+		const header = [
+			"SLUG".padEnd(slugWidth),
+			"TITLE".padEnd(titleWidth),
+			"VERSION".padEnd(versionWidth),
+			"UPDATED".padEnd(dateWidth),
+			"URL"
+		].join("  ");
+		console.log(pc.dim(header));
+		for (const d of dashboards) {
+			const url = `${APP_URL$1}/d/${d.org_slug}/${d.slug}`;
+			const date = new Date(d.updated_at).toLocaleDateString();
+			const row = [
+				d.slug.padEnd(slugWidth),
+				d.title.padEnd(titleWidth),
+				`v${d.version}`.padEnd(versionWidth),
+				date.padEnd(dateWidth),
+				url
+			].join("  ");
+			console.log(row);
+		}
+	} catch (err) {
+		console.error(pc.red(`Failed to list dashboards: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/remove.ts
+async function confirm(message) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		rl.question(`${message} (y/N) `, (answer) => {
+			rl.close();
+			resolve(answer.toLowerCase() === "y");
+		});
+	});
+}
+async function dashboardRemoveCommand(slug, options) {
+	if (!options.force) {
+		if (!await confirm(`Remove dashboard "${slug}"? This cannot be undone.`)) {
+			console.log(pc.dim("Cancelled."));
+			return;
+		}
+	}
+	try {
+		await del(`/api/dashboards/${encodeURIComponent(slug)}`);
+		console.log(pc.green(`Dashboard "${slug}" removed.`));
+	} catch (err) {
+		console.error(pc.red(`Failed to remove dashboard: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/open.ts
+const APP_URL = process.env.BON_APP_URL || "https://app.bonnard.dev";
+async function dashboardOpenCommand(slug) {
+	try {
+		const result = await get(`/api/dashboards/${encodeURIComponent(slug)}`);
+		const url = `${APP_URL}/d/${result.dashboard.org_slug}/${result.dashboard.slug}`;
+		console.log(pc.dim(`Opening ${url}`));
+		await open(url);
+	} catch (err) {
+		console.error(pc.red(`Failed to open dashboard: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
 //#endregion
 //#region src/bin/bon.ts
 const { version } = createRequire(import.meta.url)("../../package.json");
@@ -3895,6 +4036,11 @@ const keys = program.command("keys").description("Manage API keys for the Bonnar
 keys.command("list").description("List all API keys for your organization").action(keysListCommand);
 keys.command("create").description("Create a new API key").requiredOption("--name <name>", "Key name (e.g. 'Production SDK')").requiredOption("--type <type>", "Key type: publishable or secret").action(keysCreateCommand);
 keys.command("revoke").description("Revoke an API key by name or prefix").argument("<name-or-prefix>", "Key name or key prefix to revoke").action(keysRevokeCommand);
+const dashboard = program.command("dashboard").description("Manage hosted HTML dashboards");
+dashboard.command("deploy").description("Deploy an HTML file as a hosted dashboard").argument("<file>", "Path to HTML file").option("--slug <slug>", "Dashboard slug (defaults to filename)").option("--title <title>", "Dashboard title (defaults to <title> tag or slug)").action(dashboardDeployCommand);
+dashboard.command("list").description("List deployed dashboards").action(dashboardListCommand);
+dashboard.command("remove").description("Remove a deployed dashboard").argument("<slug>", "Dashboard slug to remove").option("--force", "Skip confirmation prompt").action(dashboardRemoveCommand);
+dashboard.command("open").description("Open a deployed dashboard in the browser").argument("<slug>", "Dashboard slug to open").action(dashboardOpenCommand);
 const metabase = program.command("metabase").description("Connect to and explore Metabase content");
 metabase.command("connect").description("Configure Metabase API connection").option("--url <url>", "Metabase instance URL").option("--api-key <key>", "Metabase API key").option("--force", "Overwrite existing configuration").action(metabaseConnectCommand);
 metabase.command("explore").description("Browse Metabase databases, collections, cards, and dashboards").argument("[resource]", "databases, collections, cards, dashboards, card, dashboard, database, table, collection").argument("[id]", "Resource ID (e.g. card <id>, dashboard <id>, database <id>, table <id>, collection <id>)").action(metabaseExploreCommand);

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

@@ -0,0 +1,281 @@
+# ApexCharts + Bonnard SDK
+
+> Build HTML dashboards with ApexCharts and the Bonnard SDK. No build step required.
+
+ApexCharts has the best visual defaults out of the box — no configuration needed for tooltips, responsive behavior, or dark mode. SVG-based rendering produces sharp visuals at any resolution. Moderate payload (~130KB gzip).
+
+## Starter template
+
+Copy this complete HTML file as a starting point. Replace `bon_pk_YOUR_KEY_HERE` with your publishable API key, and update the view/measure/dimension names to match your schema.
+
+Use `explore()` to discover available views and fields — see [sdk.query-reference](sdk.query-reference).
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard</title>
+  <script src="https://cdn.jsdelivr.net/npm/apexcharts@3/dist/apexcharts.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@bonnard/sdk/dist/bonnard.iife.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #09090b; color: #fafafa; padding: 24px;
+    }
+    h1 { font-size: 24px; font-weight: 600; margin-bottom: 24px; }
+    .error { color: #ef4444; background: #1c0a0a; padding: 12px; border-radius: 8px; margin-bottom: 16px; display: none; }
+    .kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 16px; margin-bottom: 32px; }
+    .kpi { background: #18181b; border: 1px solid #27272a; border-radius: 12px; padding: 20px; }
+    .kpi-label { font-size: 14px; color: #a1a1aa; margin-bottom: 8px; }
+    .kpi-value { font-size: 32px; font-weight: 600; }
+    .kpi-value.loading { color: #3f3f46; }
+    .charts { display: grid; grid-template-columns: repeat(auto-fit, minmax(400px, 1fr)); gap: 24px; }
+    .chart-card { background: #18181b; border: 1px solid #27272a; border-radius: 12px; padding: 20px; }
+    .chart-title { font-size: 16px; font-weight: 500; margin-bottom: 16px; }
+    .chart-container { height: 300px; }
+  </style>
+</head>
+<body>
+  <h1>Dashboard</h1>
+  <div id="error" class="error"></div>
+
+  <div class="kpis">
+    <div class="kpi">
+      <div class="kpi-label">Revenue</div>
+      <div class="kpi-value loading" id="kpi-revenue">--</div>
+    </div>
+    <div class="kpi">
+      <div class="kpi-label">Orders</div>
+      <div class="kpi-value loading" id="kpi-orders">--</div>
+    </div>
+    <div class="kpi">
+      <div class="kpi-label">Avg Value</div>
+      <div class="kpi-value loading" id="kpi-avg">--</div>
+    </div>
+  </div>
+
+  <div class="charts">
+    <div class="chart-card">
+      <div class="chart-title">Revenue by City</div>
+      <div class="chart-container" id="bar-chart"></div>
+    </div>
+    <div class="chart-card">
+      <div class="chart-title">Revenue Trend</div>
+      <div class="chart-container" id="line-chart"></div>
+    </div>
+  </div>
+
+  <script>
+    const bon = Bonnard.createClient({
+      apiKey: 'bon_pk_YOUR_KEY_HERE',
+    });
+
+    // --- Helpers ---
+    function showError(msg) {
+      const el = document.getElementById('error');
+      el.textContent = msg;
+      el.style.display = 'block';
+    }
+
+    function formatNumber(v) {
+      return new Intl.NumberFormat().format(v);
+    }
+
+    function formatCurrency(v) {
+      return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }).format(v);
+    }
+
+    // ApexCharts dark mode defaults
+    const darkTheme = {
+      chart: { background: 'transparent', foreColor: '#a1a1aa' },
+      theme: { mode: 'dark' },
+      grid: { borderColor: '#27272a' },
+      tooltip: { theme: 'dark' },
+    };
+
+    // --- Load data ---
+    (async () => {
+      try {
+        // KPIs
+        const kpis = await bon.query({
+          measures: ['orders.revenue', 'orders.count', 'orders.avg_value'],
+        });
+        if (kpis.data.length > 0) {
+          const row = kpis.data[0];
+          document.getElementById('kpi-revenue').textContent = formatCurrency(row['orders.revenue']);
+          document.getElementById('kpi-revenue').classList.remove('loading');
+          document.getElementById('kpi-orders').textContent = formatNumber(row['orders.count']);
+          document.getElementById('kpi-orders').classList.remove('loading');
+          document.getElementById('kpi-avg').textContent = formatCurrency(row['orders.avg_value']);
+          document.getElementById('kpi-avg').classList.remove('loading');
+        }
+
+        // Bar chart — revenue by city
+        const byCity = await bon.query({
+          measures: ['orders.revenue'],
+          dimensions: ['orders.city'],
+          orderBy: { 'orders.revenue': 'desc' },
+          limit: 10,
+        });
+
+        new ApexCharts(document.getElementById('bar-chart'), {
+          ...darkTheme,
+          chart: { ...darkTheme.chart, type: 'bar', height: 300 },
+          series: [{ name: 'Revenue', data: byCity.data.map(d => d['orders.revenue']) }],
+          xaxis: { categories: byCity.data.map(d => d['orders.city']) },
+          yaxis: { labels: { formatter: v => formatCurrency(v) } },
+          plotOptions: { bar: { borderRadius: 4, columnWidth: '60%' } },
+          colors: ['#3b82f6'],
+          dataLabels: { enabled: false },
+        }).render();
+
+        // Line chart — revenue trend
+        const trend = await bon.query({
+          measures: ['orders.revenue'],
+          timeDimension: {
+            dimension: 'orders.created_at',
+            granularity: 'month',
+            dateRange: 'last 12 months',
+          },
+        });
+
+        new ApexCharts(document.getElementById('line-chart'), {
+          ...darkTheme,
+          chart: { ...darkTheme.chart, type: 'area', height: 300 },
+          series: [{ name: 'Revenue', data: trend.data.map(d => d['orders.revenue']) }],
+          xaxis: {
+            categories: trend.data.map(d => {
+              const date = new Date(d['orders.created_at']);
+              return date.toLocaleDateString('en-US', { month: 'short', year: '2-digit' });
+            }),
+          },
+          yaxis: { labels: { formatter: v => formatCurrency(v) } },
+          colors: ['#3b82f6'],
+          fill: { type: 'gradient', gradient: { opacityFrom: 0.3, opacityTo: 0.05 } },
+          stroke: { curve: 'smooth', width: 2 },
+          dataLabels: { enabled: false },
+        }).render();
+      } catch (err) {
+        showError('Failed to load dashboard: ' + err.message);
+      }
+    })();
+  </script>
+</body>
+</html>
+```
+
+## Chart types
+
+### Bar chart
+
+```javascript
+new ApexCharts(el, {
+  chart: { type: 'bar', height: 300 },
+  series: [{ name: 'Revenue', data: data.map(d => d['view.measure']) }],
+  xaxis: { categories: data.map(d => d['view.dimension']) },
+  plotOptions: { bar: { borderRadius: 4 } },
+  colors: ['#3b82f6'],
+}).render();
+```
+
+### Horizontal bar chart
+
+```javascript
+new ApexCharts(el, {
+  chart: { type: 'bar', height: 300 },
+  series: [{ name: 'Revenue', data: data.map(d => d['view.measure']) }],
+  xaxis: { categories: data.map(d => d['view.dimension']) },
+  plotOptions: { bar: { horizontal: true, borderRadius: 4 } },
+}).render();
+```
+
+### Line chart
+
+```javascript
+new ApexCharts(el, {
+  chart: { type: 'line', height: 300 },
+  series: [{ name: 'Revenue', data: values }],
+  xaxis: { categories: labels },
+  stroke: { curve: 'smooth', width: 2 },
+}).render();
+```
+
+### Area chart
+
+```javascript
+new ApexCharts(el, {
+  chart: { type: 'area', height: 300 },
+  series: [{ name: 'Revenue', data: values }],
+  xaxis: { categories: labels },
+  fill: { type: 'gradient', gradient: { opacityFrom: 0.3, opacityTo: 0.05 } },
+  stroke: { curve: 'smooth', width: 2 },
+}).render();
+```
+
+### Pie / donut chart
+
+```javascript
+new ApexCharts(el, {
+  chart: { type: 'donut', height: 300 }, // or 'pie'
+  series: data.map(d => d['view.measure']),
+  labels: data.map(d => d['view.dimension']),
+  colors: ['#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#8b5cf6'],
+}).render();
+```
+
+### Multi-series line chart
+
+```javascript
+const cities = [...new Set(data.map(d => d['orders.city']))];
+const dates = [...new Set(data.map(d => d['orders.created_at']))];
+
+new ApexCharts(el, {
+  chart: { type: 'line', height: 300 },
+  series: cities.map(city => ({
+    name: city,
+    data: dates.map(date =>
+      data.find(d => d['orders.city'] === city && d['orders.created_at'] === date)?.['orders.revenue'] || 0
+    ),
+  })),
+  xaxis: { categories: dates.map(d => new Date(d).toLocaleDateString()) },
+  stroke: { curve: 'smooth', width: 2 },
+}).render();
+```
+
+## Dark mode
+
+ApexCharts has built-in dark mode support:
+
+```javascript
+const darkTheme = {
+  chart: { background: 'transparent', foreColor: '#a1a1aa' },
+  theme: { mode: 'dark' },
+  grid: { borderColor: '#27272a' },
+  tooltip: { theme: 'dark' },
+};
+
+new ApexCharts(el, {
+  ...darkTheme,
+  chart: { ...darkTheme.chart, type: 'bar', height: 300 },
+  // ... rest of config
+}).render();
+```
+
+## Color palette
+
+```javascript
+const COLORS = ['#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#8b5cf6', '#ec4899', '#14b8a6', '#f97316'];
+
+// Apply globally:
+colors: COLORS,
+```
+
+## See also
+
+- [sdk.browser](sdk.browser) — Browser / CDN quickstart
+- [sdk.query-reference](sdk.query-reference) — Full query API
+- [sdk.chartjs](sdk.chartjs) — Chart.js alternative (smallest payload)
+- [sdk.echarts](sdk.echarts) — ECharts alternative (more chart types)

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

@@ -0,0 +1,130 @@
+# Authentication
+
+> How to authenticate SDK requests — publishable keys for public dashboards, token exchange for multi-tenant apps.
+
+## Publishable keys
+
+Publishable keys (`bon_pk_...`) are safe to use in client-side code — HTML pages, browser apps, mobile apps. They grant read-only access to your org's semantic layer.
+
+```javascript
+const bon = Bonnard.createClient({
+  apiKey: 'bon_pk_...',
+});
+```
+
+Create publishable keys in the Bonnard web app under **Settings > API Keys**.
+
+**What publishable keys can do:**
+- Query measures and dimensions
+- Explore schema (views, fields)
+
+**What they cannot do:**
+- Modify data or schema
+- Access other orgs' data
+- Bypass governance policies (if configured at org level)
+
+## Token exchange (multi-tenant)
+
+For B2B apps where each customer should only see their own data, use **secret key token exchange**. Your server exchanges a secret key for a short-lived JWT with a security context, then your frontend queries with that token.
+
+### Server-side: exchange secret key for scoped token
+
+```javascript
+// Your backend (Node.js, Python, etc.)
+const res = await fetch('https://app.bonnard.dev/api/sdk/token', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.BONNARD_SECRET_KEY}`, // bon_sk_...
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    security_context: {
+      tenant_id: currentCustomer.id, // your tenant identifier
+    },
+  }),
+});
+
+const { token } = await res.json();
+// Pass this token to your frontend
+```
+
+### Client-side: query with scoped token
+
+```javascript
+const bon = Bonnard.createClient({
+  fetchToken: async () => {
+    const res = await fetch('/my-backend/bonnard-token');
+    const { token } = await res.json();
+    return token;
+  },
+});
+
+const { data } = await bon.query({
+  measures: ['orders.revenue'],
+  dimensions: ['orders.status'],
+});
+// Only returns rows matching the tenant's security context
+```
+
+### How token refresh works
+
+The SDK automatically:
+1. Calls `fetchToken()` on the first query
+2. Caches the returned JWT
+3. Parses the JWT `exp` claim
+4. Refreshes 60 seconds before expiry by calling `fetchToken()` again
+
+You don't need to manage token lifecycle — just provide the `fetchToken` callback.
+
+### Security context and governance
+
+The `security_context` object you pass during token exchange becomes available in your Cube models as `{securityContext.attrs.*}`. Use it in access policies to enforce row-level security:
+
+```yaml
+# In your Cube view definition
+access_policy:
+  - role: "*"
+    conditions:
+      - sql: "{TABLE}.tenant_id = '{securityContext.attrs.tenant_id}'"
+```
+
+See [security-context](security-context) for the full governance setup guide.
+
+## Browser HTML with token exchange
+
+For HTML dashboards that need multi-tenant auth, your page fetches a token from your backend:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@bonnard/sdk/dist/bonnard.iife.js"></script>
+<script>
+  const bon = Bonnard.createClient({
+    fetchToken: async () => {
+      const res = await fetch('/api/bonnard-token');
+      const { token } = await res.json();
+      return token;
+    },
+  });
+
+  (async () => {
+    const { data } = await bon.query({
+      measures: ['orders.revenue'],
+    });
+    // Data is scoped to the authenticated tenant
+  })();
+</script>
+```
+
+## When to use which
+
+| Scenario | Auth method | Key type |
+|----------|------------|----------|
+| Internal dashboard (your team) | Publishable key | `bon_pk_...` |
+| Public dashboard (anyone can view) | Publishable key | `bon_pk_...` |
+| Embedded analytics (customer sees their data only) | Token exchange | `bon_sk_...` → JWT |
+| Server-side data pipeline | Secret key directly | `bon_sk_...` |
+
+## See also
+
+- [sdk.browser](sdk.browser) — Browser / CDN quickstart
+- [sdk.query-reference](sdk.query-reference) — Full query API
+- [security-context](security-context) — Row-level security setup