@bonnard/cli 0.2.4 → 0.2.5

package/dist/bin/bon.mjs

@@ -567,21 +567,26 @@ function createAgentTemplates(cwd, env) {
 	fs.mkdirSync(claudeRulesDir, { recursive: true });
 	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 });
 	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);
 	mergeSettingsJson(loadJsonTemplate("claude/settings.json"), path.join(cwd, ".claude", "settings.json"), createdFiles);
 	const cursorRulesDir = path.join(cwd, ".cursor", "rules");
 	fs.mkdirSync(cursorRulesDir, { recursive: true });
 	writeTemplateFile(withCursorFrontmatter(sharedBonnard, "Bonnard semantic layer project context", true), path.join(cursorRulesDir, "bonnard.mdc"), createdFiles);
 	writeTemplateFile(loadTemplate("cursor/rules/bonnard-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);
 	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 });
 	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);
 	return createdFiles;
 }
 async function initCommand() {
@@ -1704,7 +1709,7 @@ async function validateCommand() {
 		console.log(pc.red("No bon.yaml found. Are you in a Bonnard project?"));
 		process.exit(1);
 	}
-	const { validate } = await import("./validate-BdqZBH2n.mjs");
+	const { validate } = await import("./validate-Bc8zGNw7.mjs");
 	const result = await validate(cwd);
 	if (result.cubes.length === 0 && result.views.length === 0 && result.valid) {
 		console.log(pc.yellow(`No cube or view files found in ${BONNARD_DIR}/cubes/ or ${BONNARD_DIR}/views/.`));
@@ -1739,6 +1744,14 @@ async function validateCommand() {
 		console.log(pc.dim("  This can cause issues when multiple warehouses are configured."));
 		console.log(pc.dim(`  ${result.cubesMissingDataSource.join(", ")}`));
 	}
+	if (result.suspectPrimaryKeys.length > 0) {
+		console.log();
+		console.log(pc.yellow(`⚠ ${result.suspectPrimaryKeys.length} primary key(s) on time dimensions`));
+		console.log(pc.dim("  Time dimensions are rarely unique. Non-unique primary keys cause dimension"));
+		console.log(pc.dim("  queries to silently return empty results. Use a unique column or add a"));
+		console.log(pc.dim("  ROW_NUMBER() synthetic key via the cube's sql property."));
+		for (const s of result.suspectPrimaryKeys) console.log(pc.dim(`  ${s.cube}.${s.dimension} (type: ${s.type})`));
+	}
 }
 
 //#endregion
@@ -1770,7 +1783,7 @@ async function deployCommand(options = {}) {
 		process.exit(1);
 	}
 	console.log(pc.dim("Validating cubes and views..."));
-	const { validate } = await import("./validate-BdqZBH2n.mjs");
+	const { validate } = await import("./validate-Bc8zGNw7.mjs");
 	const result = await validate(cwd);
 	if (!result.valid) {
 		console.log(pc.red("Validation failed:\n"));

package/dist/bin/{validate-BdqZBH2n.mjs → validate-Bc8zGNw7.mjs}

@@ -218,11 +218,53 @@ function formatZodError(error, fileName, parsed) {
 		return `${fileName}: ${location ? `${location} — ` : ""}${issue.message}`;
 	});
 }
+function checkViewMemberConflicts(parsedFiles, cubeMap) {
+	const errors = [];
+	for (const { fileName, parsed } of parsedFiles) for (const view of parsed.views ?? []) {
+		if (!view.name || !view.cubes) continue;
+		const seen = /* @__PURE__ */ new Map();
+		for (const m of view.measures ?? []) if (m.name) seen.set(m.name, `${view.name} (direct)`);
+		for (const d of view.dimensions ?? []) if (d.name) seen.set(d.name, `${view.name} (direct)`);
+		for (const s of view.segments ?? []) if (s.name) seen.set(s.name, `${view.name} (direct)`);
+		for (const cubeRef of view.cubes) {
+			const joinPath = cubeRef.join_path;
+			if (!joinPath) continue;
+			const segments = joinPath.split(".");
+			const targetCubeName = segments[segments.length - 1];
+			let memberNames = [];
+			if (cubeRef.includes === "*") {
+				const cube = cubeMap.get(targetCubeName);
+				if (!cube) continue;
+				memberNames = [
+					...cube.measures,
+					...cube.dimensions,
+					...cube.segments
+				];
+			} else if (Array.isArray(cubeRef.includes)) {
+				for (const item of cubeRef.includes) if (typeof item === "string") memberNames.push(item);
+				else if (item && typeof item === "object" && item.name) memberNames.push(item.alias || item.name);
+			} else continue;
+			if (Array.isArray(cubeRef.excludes)) {
+				const excludeSet = new Set(cubeRef.excludes);
+				memberNames = memberNames.filter((n) => !excludeSet.has(n));
+			}
+			for (const rawName of memberNames) {
+				const finalName = cubeRef.prefix ? `${targetCubeName}_${rawName}` : rawName;
+				const existingSource = seen.get(finalName);
+				if (existingSource) errors.push(`${fileName}: view '${view.name}' — member '${finalName}' from '${joinPath}' conflicts with '${existingSource}'. Use prefix: true or an alias.`);
+				else seen.set(finalName, joinPath);
+			}
+		}
+	}
+	return errors;
+}
 function validateFiles(files) {
 	const errors = [];
 	const cubes = [];
 	const views = [];
 	const allNames = /* @__PURE__ */ new Map();
+	const parsedFiles = [];
+	const cubeMap = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		let parsed;
 		try {
@@ -240,12 +282,21 @@ function validateFiles(files) {
 			errors.push(...formatZodError(result.error, file.fileName, parsed));
 			continue;
 		}
+		parsedFiles.push({
+			fileName: file.fileName,
+			parsed
+		});
 		for (const cube of parsed.cubes ?? []) if (cube.name) {
 			const existing = allNames.get(cube.name);
 			if (existing) errors.push(`${file.fileName}: duplicate name '${cube.name}' (also defined in ${existing})`);
 			else {
 				allNames.set(cube.name, file.fileName);
 				cubes.push(cube.name);
+				cubeMap.set(cube.name, {
+					measures: (cube.measures ?? []).map((m) => m.name).filter(Boolean),
+					dimensions: (cube.dimensions ?? []).map((d) => d.name).filter(Boolean),
+					segments: (cube.segments ?? []).map((s) => s.name).filter(Boolean)
+				});
 			}
 		}
 		for (const view of parsed.views ?? []) if (view.name) {
@@ -257,6 +308,7 @@ function validateFiles(files) {
 			}
 		}
 	}
+	if (errors.length === 0) errors.push(...checkViewMemberConflicts(parsedFiles, cubeMap));
 	return {
 		errors,
 		cubes,
@@ -320,6 +372,22 @@ function checkMissingDescriptions(files) {
 	} catch {}
 	return missing;
 }
+function checkSuspectPrimaryKeys(files) {
+	const suspects = [];
+	for (const file of files) try {
+		const parsed = YAML.parse(file.content);
+		if (!parsed) continue;
+		for (const cube of parsed.cubes || []) {
+			if (!cube.name) continue;
+			for (const dim of cube.dimensions || []) if (dim.primary_key && dim.type === "time") suspects.push({
+				cube: cube.name,
+				dimension: dim.name,
+				type: dim.type
+			});
+		}
+	} catch {}
+	return suspects;
+}
 function checkMissingDataSource(files) {
 	const missing = [];
 	for (const file of files) try {
@@ -338,7 +406,8 @@ async function validate(projectPath) {
 		cubes: [],
 		views: [],
 		missingDescriptions: [],
-		cubesMissingDataSource: []
+		cubesMissingDataSource: [],
+		suspectPrimaryKeys: []
 	};
 	const result = validateFiles(files);
 	if (result.errors.length > 0) return {
@@ -347,17 +416,20 @@ async function validate(projectPath) {
 		cubes: [],
 		views: [],
 		missingDescriptions: [],
-		cubesMissingDataSource: []
+		cubesMissingDataSource: [],
+		suspectPrimaryKeys: []
 	};
 	const missingDescriptions = checkMissingDescriptions(files);
 	const cubesMissingDataSource = checkMissingDataSource(files);
+	const suspectPrimaryKeys = checkSuspectPrimaryKeys(files);
 	return {
 		valid: true,
 		errors: [],
 		cubes: result.cubes,
 		views: result.views,
 		missingDescriptions,
-		cubesMissingDataSource
+		cubesMissingDataSource,
+		suspectPrimaryKeys
 	};
 }
 

package/dist/docs/topics/features.governance.md

@@ -1,84 +1,83 @@
 # Governance
 
-> User and group-level permissions for your semantic layer.
+> Control who can see which views, columns, and rows in your semantic layer.
 
-Bonnard supports declarative data access policies — define who can see which rows, columns, and views directly in your YAML models. No application code, no database-level workarounds.
+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.
 
-## Row-level security
+## How It Works
 
-Filter data based on user attributes. A sales manager only sees their region's data:
+```
+Admin configures in web UI:
+  Groups → Views → Field/Row restrictions
 
-```yaml
-cubes:
-  - name: orders
-    access_policy:
-      - role: sales_manager
-        row_level:
-          filters:
-            - member: region
-              operator: equals
-              values: ["{ securityContext.region }"]
+Enforced automatically:
+  MCP queries + API → only see what policies allow
 ```
 
-Every query from that user automatically includes the filter — no way to bypass it.
+Governance uses **groups** as the unit of access. Each group has a set of **policies** that define which views its members can see, and optionally restrict specific columns or rows within those views.
 
-## Member-level security
+## Groups
 
-Control which measures and dimensions each role can access. Hide sensitive fields from non-privileged users:
+Groups represent teams or roles in your organization — "Sales Team", "Finance", "Executive". Create and manage groups from the **Governance** page in the Bonnard dashboard.
 
-```yaml
-cubes:
-  - name: orders
-    access_policy:
-      - role: analyst
-        member_level:
-          includes:
-            - count
-            - total_revenue
-            - status
-            - created_at
+Each group has:
+- **Name** and optional description
+- **Color** for visual identification
+- **View access** — which views the group can query
+- **Members** — which users belong to the group
 
-      - role: admin
-        member_level:
-          includes: "*"
-```
+Users can belong to multiple groups. Their effective access is the **union** of all group policies.
 
-Roles without a matching policy see nothing.
+## View-Level Access (Level 1)
 
-## View-based governance
+The simplest control: toggle which views a group can see. Unchecked views are completely invisible to group members — they won't appear in `explore_schema` or be queryable.
 
-Keep cubes private. Expose only curated views to consumers:
+From the group detail page, check the views you want to grant access to and click **Save changes**. New policies default to "All fields" with no row filters.
 
-```yaml
-cubes:
-  - name: raw_orders
-    public: false
+## Field-Level Access (Level 2)
 
-views:
-  - name: sales_overview
-    public: true
-    cubes:
-      - join_path: raw_orders
-        includes:
-          - revenue
-          - order_count
-          - status
-```
+Fine-tune which measures and dimensions a group can see within a view. Click the gear icon on any granted view to open the fine-tune dialog.
 
-Business users, AI agents, and SDK consumers only see the views you choose to expose — with clean names and descriptions.
+Three modes:
+- **All fields** — full access to every measure and dimension (default)
+- **Only these** — whitelist specific fields; everything else is hidden
+- **All except** — blacklist specific fields; everything else is visible
 
-## Dynamic visibility
+Hidden fields are removed from the schema — they don't appear in `explore_schema` and can't be used in queries.
 
-Use context variables to show or hide entire cubes based on the user's role:
+## Row-Level Filters (Level 2)
 
-```yaml
-cubes:
-  - name: executive_metrics
-    public: "{{ 'true' if COMPILE_CONTEXT.role == 'executive' else 'false' }}"
-```
+Restrict which rows a group can see. Add row filters in the fine-tune dialog to limit data by dimension values.
+
+For example, filter `traffic_source` to `equals B2B, Organic` so the group only sees rows where traffic_source is B2B or Organic. Multiple values in a single filter are OR'd (any match). Multiple separate filters are AND'd (all must match).
+
+Row filters are applied server-side on every query — users cannot bypass them.
+
+## Members
+
+Assign users to groups from the **Members** tab. Each user shows which groups they belong to and a preview of their effective access (which views they can query, any field or row restrictions).
+
+Users without any group assignment see nothing — they must be added to at least one group to query governed views.
+
+## How Policies Are Enforced
+
+Policies configured in the web UI are stored in Supabase and injected into the query engine at runtime. When a user queries via MCP or the API:
+
+1. Their JWT is enriched with group memberships
+2. The query engine loads policies for those groups
+3. View visibility, field restrictions, and row filters are applied automatically
+4. The user only sees data their policies allow
+
+No YAML changes are needed — governance is fully managed through the dashboard.
+
+## Best Practices
+
+1. **Start with broad access, then restrict** — give groups all views first, then fine-tune as needed
+2. **Use groups for teams, not individuals** — easier to manage and audit
+3. **Test with MCP** — after changing policies, query via MCP to verify the restrictions work as expected
+4. **Review after schema deploys** — new views need to be added to group policies to become visible
 
 ## See Also
 
-- [cubes.public](cubes.public) — Visibility controls reference
+- [features.mcp](features.mcp) — How AI agents query your semantic layer
 - [views](views) — Creating curated data views
-- [syntax.context-variables](syntax.context-variables) — Context variable reference

package/dist/docs/topics/features.semantic-layer.md

@@ -9,6 +9,7 @@ Bonnard hosts your semantic layer so you don't have to. Define cubes and views i
 Connect any combination of warehouses through a single semantic layer:
 
 - **PostgreSQL** — Direct TCP connection
+- **Redshift** — Cluster or serverless endpoint
 - **Snowflake** — Account-based authentication
 - **BigQuery** — GCP service account
 - **Databricks** — Token-based workspace connection
@@ -43,8 +44,13 @@ Your models are stored securely and served from Bonnard's infrastructure. Each o
 
 Deploy in seconds. Query in milliseconds.
 
+## Built for AI agents
+
+Views and descriptions are the discovery API for AI agents. When an agent calls `explore_schema`, it sees view names and descriptions — that's all it has to decide where to query. Well-written descriptions with scope, disambiguation, and dimension values make agents accurate. See the design guide principles in the CLI (`/bonnard-design-guide`) for details.
+
 ## See Also
 
 - [workflow.query](workflow.query) — Query format reference
 - [cubes](cubes) — Cube modeling guide
 - [views](views) — View modeling guide
+- [features.governance](features.governance) — Access control for views and data

package/dist/docs/topics/views.md

@@ -6,11 +6,18 @@
 
 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.
+
 ## Example
 
 ```yaml
 views:
-  - name: orders_overview
+  - name: sales_analytics
+    description: >-
+      Sales team view — order revenue, counts, and status breakdowns with
+      customer details. Default view for revenue and order questions. Use the
+      status dimension (values: pending, completed, cancelled) to filter.
+      For customer-level analysis, use customer_insights instead.
     cubes:
       - join_path: orders
         includes:
@@ -39,13 +46,13 @@ views:
 
 ## Why Use Views?
 
-### 1. Simplify Data Access
+### 1. Curate for Audiences
 
-Expose only relevant members instead of entire cubes:
+Expose only the measures and dimensions a specific audience needs. A single `orders` cube might contribute to a `sales_analytics` view (revenue by status), a `management_kpis` view (high-level totals), and a `finance_reporting` view (invoice amounts). Each view shows different slices of the same data.
 
 ```yaml
 views:
-  - name: sales_dashboard
+  - name: sales_analytics
     cubes:
       - join_path: orders
         includes:
@@ -124,11 +131,12 @@ bonnard/views/
 
 ## Best Practices
 
-1. **Create purpose-specific views** — one view per dashboard/use case
-2. **Use meaningful names** — describe what the view is for
-3. **Be explicit with includes** — list members rather than using "*"
-4. **Alias for clarity** — rename members when needed
-5. **Organize with folders** — group related members together
+1. **Name views by audience/use case** — `sales_pipeline` not `opportunities_view`. Views represent how teams think about data, not your warehouse schema.
+2. **Write descriptions that help AI agents choose** — Lead with scope ("Sales team — revenue, order counts..."), cross-reference related views ("For customer demographics, use customer_insights instead"), and include key dimension values.
+3. **Combine multiple cubes** — A view should pull from whichever cubes answer a team's questions. Don't limit views to one cube each.
+4. **Be explicit with includes** — list members rather than using "*"
+5. **Alias for clarity** — rename members when needed
+6. **Organize with folders** — group related members together
 
 ## See Also
 

package/dist/docs/topics/workflow.md

@@ -131,11 +131,12 @@ bonnard/cubes/
 
 ## Best Practices
 
-1. **Start simple** — begin with one cube, add complexity gradually
-2. **Validate often** — run `bon validate` after each change
-3. **Use version control** — commit cubes and views to git
-4. **Document with descriptions** — add `description` to measures/dimensions
-5. **Test with queries** — verify models produce expected results
+1. **Start from questions** — collect the most common questions your team asks, then build views that answer them. Don't just mirror your warehouse tables.
+2. **Add filtered measures** — if a dashboard card has a WHERE clause beyond a date range, that filter should be a filtered measure. This is the #1 way to match real dashboard numbers.
+3. **Write descriptions for agents** — descriptions are how AI agents choose which view and measure to use. Lead with scope, cross-reference related views, include dimension values.
+4. **Validate often** — run `bon validate` after each change
+5. **Test with real questions** — after deploying, ask an AI agent via MCP the same questions your team asks. Check it picks the right view and measure.
+6. **Iterate** — expect 2-4 rounds of deploying, testing with questions, and improving descriptions before agents reliably answer the top 10 questions.
 
 ## Commands Reference