@bonnard/cli 0.2.13 → 0.2.15

package/dist/bin/bon.mjs

@@ -1908,6 +1908,30 @@ async function annotateCommand(id, options = {}) {
 	}
 }
 
+//#endregion
+//#region src/commands/pull.ts
+async function pullCommand() {
+	const paths = getProjectPaths(process.cwd());
+	console.log(pc.dim("Downloading deployed models..."));
+	try {
+		const files = (await get("/api/deploy/files")).files;
+		const fileKeys = Object.keys(files);
+		if (fileKeys.length === 0) {
+			console.log(pc.yellow("No deployed files found. Have you run `bon deploy` yet?"));
+			return;
+		}
+		for (const [relativePath, content] of Object.entries(files)) {
+			const fullPath = path.join(paths.root, relativePath);
+			fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+			fs.writeFileSync(fullPath, content, "utf-8");
+		}
+		console.log(pc.green(`Pulled ${fileKeys.length} file(s) to bonnard/`));
+	} catch (err) {
+		console.log(pc.red(`Pull failed: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
 //#endregion
 //#region src/commands/diff.ts
 async function diffCommand(id, options = {}) {
@@ -3860,6 +3884,7 @@ datasource.command("list").description("List data sources (shows both local and
 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);
 program.command("validate").description("Validate YAML syntax in bonnard/cubes/ and bonnard/views/").action(validateCommand);
 program.command("deploy").description("Deploy cubes and views to Bonnard. Requires login, validates, syncs datasources").option("--ci", "Non-interactive mode").requiredOption("-m, --message <text>", "Deploy message describing your changes").action(deployCommand);
+program.command("pull").description("Download deployed cubes and views from Bonnard").action(pullCommand);
 program.command("deployments").description("List deployment history").option("--all", "Show all deployments (default: last 10)").option("--format <format>", "Output format: table or json", "table").action(deploymentsCommand);
 program.command("diff").description("Show changes in a deployment").argument("<id>", "Deployment ID").option("--format <format>", "Output format: table or json", "table").option("--breaking", "Show only breaking changes").action(diffCommand);
 program.command("annotate").description("Annotate deployment changes with reasoning").argument("<id>", "Deployment ID").option("--data <json>", "Annotations JSON").action(annotateCommand);

package/dist/docs/_index.md

@@ -68,6 +68,7 @@
 ## Other
 
 - [governance](governance) - User and group-level permissions
+- [security-context](security-context) - B2B multi-tenancy with security context
 - [catalog](catalog) - Browse your data model in the browser
 - [slack-teams](slack-teams) - AI agents in team chat (coming soon)
 

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

@@ -172,6 +172,25 @@ Wrap components in a `<Grid>` tag to arrange them in columns:
 |------|------|---------|-------------|
 | `cols` | string | `"2"` | Number of columns in the grid |
 
+### Layout Best Practices
+
+**Use `##` for sections, not `#`.** The `#` heading renders very large and wastes vertical space. Use `##` for section titles and `###` for subsections. Reserve `#` for the dashboard title only (which is set in frontmatter, not in the body).
+
+**Group related charts side by side.** Wrap pairs of charts in `<Grid cols="2">` to avoid long vertical scrolling:
+
+```markdown
+<Grid cols="2">
+<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" />
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="By City" horizontal />
+</Grid>
+```
+
+**Start each section with KPIs.** Place `<BigValue>` cards at the top of a section for at-a-glance metrics, then follow with charts for detail.
+
+**Only Grid together components of similar height.** Don't mix a `<BigValue>` with a chart in the same `<Grid>` row — the grid stretches both cells to the tallest item, leaving the BigValue card with a large empty area. Instead, place KPIs in their own row (consecutive BigValues auto-group) and pair charts with other charts of similar size.
+
+**Keep it compact.** A good dashboard fits key information in 2-3 screens of scrolling. Use Grids, concise titles, and avoid unnecessary headings between every chart.
+
 ## 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.

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

@@ -252,16 +252,89 @@ limit: 10
 
 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.
 
+## Compact Multi-Section Dashboard
+
+A dashboard with multiple sections, side-by-side charts, and compact layout. Uses `##` headings (not `#`), `<Grid>` for horizontal grouping, and keeps all queries near the components that use them.
+
+```markdown
+---
+title: Operations Overview
+description: KPIs, trends, and breakdowns across channels and cities
+---
+
+<DateRange name="period" default="last-30-days" label="Period" />
+
+` ``query channels
+dimensions: [orders.channel]
+` ``
+
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="kpis,trend,by_city" label="Channel" />
+
+## Key Metrics
+
+` ``query kpis
+measures: [orders.total_revenue, orders.count, orders.avg_order_value]
+` ``
+
+<BigValue data={kpis} value="orders.total_revenue" title="Revenue" fmt="eur" />
+<BigValue data={kpis} value="orders.count" title="Orders" fmt="num0" />
+<BigValue data={kpis} value="orders.avg_order_value" title="Avg Order" fmt="eur2" />
+
+## Trends & Breakdown
+
+` ``query trend
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: week
+` ``
+
+` ``query by_channel
+measures: [orders.total_revenue]
+dimensions: [orders.channel]
+orderBy:
+  orders.total_revenue: desc
+` ``
+
+<Grid cols="2">
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" title="Weekly Revenue" yFmt="eur" />
+<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" yFmt="eur" />
+</Grid>
+
+## Top Cities
+
+` ``query by_city
+measures: [orders.total_revenue, orders.count]
+dimensions: [orders.city]
+orderBy:
+  orders.total_revenue: desc
+limit: 10
+` ``
+
+<Grid cols="2">
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="Revenue by City" horizontal yFmt="eur" />
+<DataTable data={by_city} fmt="orders.total_revenue:eur,orders.count:num0" />
+</Grid>
+```
+
+Key patterns:
+- **`##` headings** for sections — compact, no oversized H1s
+- **Consecutive `<BigValue>`** auto-groups into a row (no Grid needed)
+- **`<Grid cols="2">`** pairs a chart with a table or two charts side by side
+- **Queries defined before their Grid** — keeps the layout clean and components grouped
+
 ## Tips
 
-- **Start with KPIs**: Use `BigValue` in a `Grid` at the top for key metrics
+- **Start with KPIs**: Use `BigValue` at the top for key metrics — consecutive BigValues auto-group into a row
 - **One query per chart**: Each component gets its own query — keep them focused
+- **Use `##` headings**: Reserve `#` for the dashboard title (in frontmatter). Use `##` for sections
 - **Use views**: Prefer view names over cube names when available
 - **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="cube.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="orders.revenue,orders.cases"` to show multiple measures on one chart
+- **Side-by-side charts**: Wrap pairs in `<Grid cols="2">` to reduce vertical scrolling
 
 ## See Also
 

package/dist/docs/topics/governance.md

@@ -4,6 +4,8 @@
 
 Bonnard provides admin-managed data governance — control which views, columns, and rows each group of users can access. Policies are configured in the web UI and enforced automatically across MCP queries and the API. Changes take effect within one minute.
 
+> **Building a B2B product?** Governance is for managing _internal_ user access via the dashboard. For tenant isolation in customer-facing apps (where each customer sees only their data), see [security-context](security-context).
+
 ## How It Works
 
 ```
@@ -70,6 +72,21 @@ Policies configured in the web UI are stored in Supabase and injected into the q
 
 No YAML changes are needed — governance is fully managed through the dashboard.
 
+## Governance and Developer-Defined Policies
+
+Governance policies from the dashboard are **merged** with any `access_policy` entries you define in your YAML model files. This lets you combine both approaches:
+
+- **Developer-defined policies** — written in YAML, typically for B2B tenant isolation using `group: "*"` (matches all users, including SDK tokens)
+- **Governance policies** — configured in the dashboard UI for internal user access control
+
+When governance injects policies:
+
+1. If a view has governance policies **and** developer-defined `access_policy` entries, both are merged into a single list
+2. If a view has developer-defined `access_policy` but **no** governance policies, the developer entries are preserved as-is
+3. If a view has **neither**, it receives a default policy restricting access to ungoverned users
+
+This means you can safely define tenant isolation in YAML and layer dashboard governance on top — neither overwrites the other.
+
 ## Best Practices
 
 1. **Start with broad access, then restrict** — give groups all views first, then fine-tune as needed
@@ -81,3 +98,4 @@ No YAML changes are needed — governance is fully managed through the dashboard
 
 - [querying.mcp](querying.mcp) — How AI agents query your semantic layer
 - [views](views) — Creating curated data views
+- [security-context](security-context) — B2B multi-tenancy with security context

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

@@ -39,6 +39,41 @@ const result = await bonnard.sql<OrderRow>(
 // result.data is OrderRow[]
 ```
 
+## Multi-tenant queries
+
+When building B2B apps where each customer should only see their own data, use **security context** with token exchange. Your server exchanges a secret key for a scoped token, then your frontend queries with that token — row-level filters are enforced automatically.
+
+```typescript
+// Server-side: exchange secret key for a scoped token
+const res = await fetch('https://app.bonnard.dev/api/sdk/token', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.BONNARD_SECRET_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    security_context: { tenant_id: currentCustomer.id },
+  }),
+});
+const { token } = await res.json();
+// Pass token to the frontend
+```
+
+```typescript
+// Client-side: query with the scoped token
+const bonnard = createClient({
+  fetchToken: async () => token, // from your server
+});
+
+const result = await bonnard.query({
+  measures: ['orders.revenue'],
+  dimensions: ['orders.status'],
+});
+// Only returns rows where tenant_id matches — enforced server-side
+```
+
+This requires an `access_policy` on your view with a `{securityContext.attrs.tenant_id}` filter. See [security-context](security-context) for the full setup guide.
+
 ## What you can build
 
 - **Custom dashboards** — Query your semantic layer from Next.js, React, or any frontend

package/dist/docs/topics/security-context.md

@@ -0,0 +1,200 @@
+# Security Context
+
+> Implement multi-tenant data isolation for B2B apps using security context and access policies.
+
+Security context lets you build customer-facing applications where each tenant only sees their own data. It works through the SDK's token exchange mechanism — your server sets the context, and row-level filters are enforced automatically on every query.
+
+## When to Use What
+
+| Use case | Mechanism | Configured in |
+|----------|-----------|---------------|
+| Internal users — teams, roles, field/row restrictions | [Governance](governance) | Dashboard UI |
+| B2B apps — each customer sees only their data | Security context | YAML model + SDK |
+| Both — internal governance + tenant isolation | Both (merged) | Dashboard + YAML |
+
+## How It Works
+
+```
+Your server                    Bonnard                        Database
+    │                             │                              │
+    ├─ POST /api/sdk/token        │                              │
+    │  { security_context:        │                              │
+    │    { tenant_id: "acme" } } ─┤                              │
+    │                             │                              │
+    │◄─ { token, expires_at } ────┤                              │
+    │                             │                              │
+    │   (pass token to frontend)  │                              │
+    │                             │                              │
+    ├─ query(measures, dims) ─────┤                              │
+    │   Authorization: Bearer ... │                              │
+    │                             ├─ WHERE tenant_id = 'acme' ──►│
+    │                             │  (injected automatically)    │
+    │◄─ filtered results ─────────┤◄─────────────────────────────┤
+```
+
+1. Your server calls `exchangeToken()` with a `security_context` containing tenant attributes
+2. Bonnard returns a short-lived scoped token (5 min TTL, refreshable via `fetchToken`)
+3. The frontend queries using that token — the query engine injects row-level filters from the `access_policy` matching `{securityContext.attrs.X}` values
+4. Only matching rows are returned — tenants cannot see each other's data
+
+## Step-by-Step Setup
+
+### 1. Define access_policy in your view YAML
+
+Add an `access_policy` entry with `group: "*"` (matches all users, including SDK tokens with empty groups) and a row-level filter referencing security context attributes:
+
+```yaml
+views:
+  - name: orders
+    cubes:
+      - join_path: base_orders
+        includes: "*"
+
+    access_policy:
+      - group: "*"
+        row_level:
+          filters:
+            - member: tenant_id
+              operator: equals
+              values:
+                - "{securityContext.attrs.tenant_id}"
+```
+
+The `{securityContext.attrs.tenant_id}` placeholder is replaced at query time with the value from the token's security context.
+
+### 2. Deploy your model
+
+```bash
+bon deploy
+```
+
+### 3. Exchange a token server-side
+
+In your API route or server action, exchange your secret key for a scoped token by calling the `/api/sdk/token` endpoint:
+
+```typescript
+// In your API route handler:
+export async function GET(request: Request) {
+  const tenantId = await getTenantFromSession(request);
+
+  const res = await fetch('https://app.bonnard.dev/api/sdk/token', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.BONNARD_SECRET_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      security_context: { tenant_id: tenantId },
+    }),
+  });
+
+  const { token } = await res.json();
+  return Response.json({ token });
+}
+```
+
+### 4. Query from the frontend
+
+```typescript
+import { createClient } from '@bonnard/sdk';
+
+const bonnard = createClient({
+  fetchToken: async () => {
+    const res = await fetch('/api/bonnard-token');
+    const { token } = await res.json();
+    return token;
+  },
+});
+
+const result = await bonnard.query({
+  measures: ['orders.revenue', 'orders.count'],
+  dimensions: ['orders.status'],
+});
+// Only returns rows where tenant_id matches the exchanged context
+```
+
+## Multiple Filters
+
+You can filter on multiple attributes. Each filter is AND'd:
+
+```yaml
+access_policy:
+  - group: "*"
+    row_level:
+      filters:
+        - member: tenant_id
+          operator: equals
+          values:
+            - "{securityContext.attrs.tenant_id}"
+        - member: region
+          operator: equals
+          values:
+            - "{securityContext.attrs.region}"
+```
+
+```typescript
+const res = await fetch('https://app.bonnard.dev/api/sdk/token', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.BONNARD_SECRET_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    security_context: { tenant_id: 'acme', region: 'eu' },
+  }),
+});
+const { token } = await res.json();
+```
+
+## Combining with Governance
+
+Security context policies and governance policies are **merged**, not replaced. You can safely use both:
+
+- `group: "*"` entries in YAML handle B2B tenant isolation (matches all users including SDK tokens)
+- Governance policies from the dashboard handle internal user access control (field visibility, row filters by group)
+
+When both are active on the same view, the final `access_policy` contains all entries. Cube evaluates them based on the user's group membership — SDK tokens have `groups: []`, so they match `group: "*"` but not named groups.
+
+```yaml
+# Developer-defined in YAML — always active
+access_policy:
+  - group: "*"
+    row_level:
+      filters:
+        - member: tenant_id
+          operator: equals
+          values:
+            - "{securityContext.attrs.tenant_id}"
+
+# Governance adds these at runtime (configured in dashboard):
+#  - group: sales
+#    member_level:
+#      includes: [revenue, count]
+#  - group: finance
+#    member_level:
+#      includes: [margin, cost]
+```
+
+## Token Exchange Reference
+
+**Endpoint:** `POST /api/sdk/token`
+
+**Headers:** `Authorization: Bearer bon_sk_...` (your secret key)
+
+| Body parameter | Type | Description |
+|----------------|------|-------------|
+| `security_context` | `Record<string, string>` | Key-value pairs. Keys must match `{securityContext.attrs.X}` placeholders in your access_policy. Max 20 keys, key max 64 chars, value max 256 chars. |
+| `expires_in` | `number` | Token TTL in seconds. Min 60, max 3600, default 900. |
+
+**Response:** `{ token: string, expires_at: string }`
+
+**Token properties:**
+- Default TTL: 15 minutes (configurable 1–60 min via `expires_in`)
+- Renewable via `fetchToken` callback (SDK re-fetches automatically before expiry)
+- Contains `groups: []` (empty) — matches `group: "*"` policies only
+
+## See Also
+
+- [governance](governance) — Dashboard-managed access control for internal users
+- [querying.sdk](querying.sdk) — SDK query reference
+- [syntax.context-variables](syntax.context-variables) — Context variable syntax reference

package/dist/docs/topics/syntax.context-variables.md

@@ -142,12 +142,30 @@ dimensions:
 3. **Use COMPILE_CONTEXT** for deployment config — not for per-query logic
 4. **Test filter pushdown** — verify FILTER_PARAMS generates expected SQL
 
-## Deprecated: SECURITY_CONTEXT
+## Row-Level Security via access_policy
 
-`SECURITY_CONTEXT` is deprecated. Use `query_rewrite` for security filtering instead.
+For row-level filtering based on the current user or tenant, use `access_policy` with `{securityContext.attrs.X}` in filter values:
+
+```yaml
+views:
+  - name: orders
+    access_policy:
+      - group: "*"
+        row_level:
+          filters:
+            - member: tenant_id
+              operator: equals
+              values:
+                - "{securityContext.attrs.tenant_id}"
+```
+
+Security context attributes are set during token exchange (SDK) or via governance user attributes (dashboard). See [security-context](security-context) for the full B2B multi-tenancy guide.
+
+> **Note:** The upstream `SECURITY_CONTEXT` SQL variable is deprecated. Use `access_policy` row-level filters with `{securityContext.attrs.X}` instead.
 
 ## See Also
 
 - syntax
 - syntax.references
 - cubes.extends
+- security-context

package/package.json

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