@bonnard/cli 0.2.12 → 0.2.14

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

@@ -23,7 +23,7 @@ Choose the component that best fits your data:
 
 - Components are self-closing (`/>`)
 - `data` uses curly braces: `data={query_name}`
-- Other props use quotes: `x="field_name"`
+- Other props use quotes: `x="orders.city"`
 - Boolean props can be shorthand: `horizontal`
 
 ## Component Reference
@@ -33,13 +33,13 @@ Choose the component that best fits your data:
 Displays a single KPI metric as a large number.
 
 ```markdown
-<BigValue data={total_revenue} value="total_revenue" title="Revenue" />
+<BigValue data={total_revenue} value="orders.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 |
+| `value` | string | Yes | Fully qualified 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"`) |
 
@@ -48,16 +48,16 @@ Displays a single KPI metric as a large number.
 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" />
+<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" title="Revenue Trend" />
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue,orders.count" />
+<LineChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.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(s) for y-axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="orders.total_revenue,orders.count"`) |
 | `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) |
@@ -68,17 +68,17 @@ Renders a line chart, typically for time series. Supports multiple y columns and
 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" />
+<BarChart data={revenue_by_city} x="orders.city" y="orders.total_revenue" />
+<BarChart data={revenue_by_city} x="orders.city" y="orders.total_revenue" horizontal />
+<BarChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" />
+<BarChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" type="grouped" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for category axis |
-| `y` | string | Yes | Field(s) for value axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
+| `y` | string | Yes | Field(s) for value axis. Comma-separated for multiple (e.g. `y="orders.total_revenue,orders.count"`) |
 | `title` | string | No | Chart title |
 | `horizontal` | boolean | No | Render as horizontal bar chart |
 | `series` | string | No | Column to split data into separate colored bars |
@@ -90,15 +90,15 @@ Renders a vertical bar chart. Add `horizontal` for horizontal bars. Supports mul
 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" />
+<AreaChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" />
+<AreaChart data={revenue_by_source} x="orders.created_at" y="orders.total_revenue" series="orders.source" type="stacked" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for x-axis |
-| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="orders.total_revenue,orders.count"`) |
 | `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) |
@@ -109,7 +109,7 @@ Renders a filled area chart. Supports series splitting and stacked areas.
 Renders a pie/donut chart.
 
 ```markdown
-<PieChart data={by_status} name="status" value="count" title="Order Status" />
+<PieChart data={by_status} name="orders.status" value="orders.count" title="Order Status" />
 ```
 
 | Prop | Type | Required | Description |
@@ -125,7 +125,7 @@ Renders query results as a sortable, paginated table. Click any column header to
 
 ```markdown
 <DataTable data={top_products} />
-<DataTable data={top_products} columns="name,revenue,count" />
+<DataTable data={top_products} columns="orders.category,orders.total_revenue,orders.count" />
 <DataTable data={top_products} rows="25" />
 <DataTable data={top_products} rows="all" />
 ```
@@ -135,7 +135,7 @@ Renders query results as a sortable, paginated table. Click any column header to
 | `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"` |
+| `fmt` | string | No | Column format map: `fmt="orders.total_revenue:eur2,orders.created_at: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.
@@ -149,9 +149,9 @@ Renders query results as a sortable, paginated table. Click any column header to
 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" />
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
+<BigValue data={order_count} value="orders.count" title="Orders" />
+<BigValue data={avg_order} value="orders.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.
@@ -162,9 +162,9 @@ 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" />
+<BigValue data={total_orders} value="orders.count" title="Orders" />
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
+<BigValue data={avg_order} value="orders.avg_order_value" title="Avg Order" />
 </Grid>
 ```
 
@@ -198,7 +198,7 @@ Values are auto-formatted by default — numbers get locale grouping (1,234.56),
 | `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"`.
+Any string that isn't a preset name is treated as a raw Excel format code (ECMA-376). For example: `fmt="orders.total_revenue:$#,##0.00"`.
 
 Note: Percentage presets (`pct`, `pct1`, `pct2`) multiply by 100 per Excel convention — 0.45 displays as "45%".
 
@@ -206,19 +206,19 @@ Note: Percentage presets (`pct`, `pct1`, `pct2`) multiply by 100 per Excel conve
 
 ```markdown
 <!-- BigValue with currency -->
-<BigValue data={total_revenue} value="total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" fmt="eur2" />
 
 <!-- DataTable with per-column formatting -->
-<DataTable data={sales} fmt="total_revenue:usd2,created_at:shortdate,margin:pct1" />
+<DataTable data={sales} fmt="orders.total_revenue:usd2,orders.created_at:shortdate,orders.margin:pct1" />
 
 <!-- Chart with formatted tooltips -->
-<BarChart data={monthly} x="month" y="revenue" yFmt="usd" />
-<LineChart data={trend} x="date" y="growth" yFmt="pct1" />
+<BarChart data={monthly} x="orders.created_at" y="orders.total_revenue" yFmt="usd" />
+<LineChart data={trend} x="orders.created_at" y="orders.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"`.
+All field names in component props must be **fully qualified** with the view or cube name — the same format used in query blocks. For example, use `value="orders.total_revenue"` not `value="total_revenue"`.
 
 ## 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.12",
+  "version": "0.2.14",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"