@graphit/cli 0.1.15 → 0.1.18

package/dist/index.js

@@ -7,19 +7,21 @@ import { registerDSCommands } from "./commands/ds.js";
 import { registerDashboardCommands } from "./commands/dashboard.js";
 import { registerConnectorCommands } from "./commands/connector.js";
 import { registerSetupCommand } from "./commands/setup.js";
+import { registerGovernanceCommands } from "./commands/governance.js";
 import { getCurrentVersion, printUpdateBanner, fireBackgroundCheck, } from "./update-check.js";
 const program = new Command();
 program
     .name("graphit")
     .description("Graphit CLI - Build custom dashboards from any AI coding assistant")
     .version(getCurrentVersion())
-    .option("--output <format>", "Output format: json (default) or table", "json");
+    .option("--output <format>", "Output format: json (default), table, or styled", "json");
 registerAuthCommands(program);
 registerKBCommands(program);
 registerQueryCommands(program);
 registerDSCommands(program);
 registerDashboardCommands(program);
 registerConnectorCommands(program);
+registerGovernanceCommands(program);
 registerSetupCommand(program);
 printUpdateBanner();
 program.parse();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,oEAAoE,CAAC;KACjF,OAAO,CAAC,iBAAiB,EAAE,CAAC;KAC5B,MAAM,CAAC,mBAAmB,EAAE,wCAAwC,EAAE,MAAM,CAAC,CAAC;AAEjF,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAE9B,iBAAiB,EAAE,CAAC;AACpB,OAAO,CAAC,KAAK,EAAE,CAAC;AAChB,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,oEAAoE,CAAC;KACjF,OAAO,CAAC,iBAAiB,EAAE,CAAC;KAC5B,MAAM,CAAC,mBAAmB,EAAE,iDAAiD,EAAE,MAAM,CAAC,CAAC;AAE1F,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,0BAA0B,CAAC,OAAO,CAAC,CAAC;AACpC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAE9B,iBAAiB,EAAE,CAAC;AACpB,OAAO,CAAC,KAAK,EAAE,CAAC;AAChB,mBAAmB,EAAE,CAAC"}

package/dist/output/format.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-export type OutputFormat = "json" | "table";
+export type OutputFormat = "json" | "table" | "styled";
 export declare function getOutputFormat(cmd: Command): OutputFormat;
 export declare function output(cmd: Command, data: unknown, opts?: {
     columns?: string[];

package/dist/output/format.js

@@ -3,6 +3,8 @@ import { formatTable, formatKeyValue } from "./table.js";
 export function getOutputFormat(cmd) {
     const root = cmd.parent ?? cmd;
     const format = root.opts().output;
+    if (format === "styled")
+        return "styled";
     return format === "table" ? "table" : "json";
 }
 export function output(cmd, data, opts) {

package/dist/output/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/output/format.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIzD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,MAAgB,CAAC;IAC5C,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,GAAY,EACZ,IAAa,EACb,IAAiD;IAEjD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IAED,IAAI,IAAI,EAAE,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAA+B,CAAC,CAAC,CAAC;QAC7D,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAiC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAe,CAAC;IACpB,IAAI,UAA8B,CAAC;IAEnC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACxB,CAAC;SAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,OAAO,GAAI,GAAG,CAAC,MAAiB,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,OAAO,GAAG,CAAC,mBAAmB,KAAK,QAAQ,EAAE,CAAC;YAChD,UAAU,GAAG,GAAG,CAAC,mBAAmB,CAAC;QACvC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,GAAG,GAAG,OAAO,aAAa,UAAU,IAAI,CAAC;IAClD,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/output/format.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIzD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,MAAgB,CAAC;IAC5C,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACzC,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,GAAY,EACZ,IAAa,EACb,IAAiD;IAEjD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IAED,IAAI,IAAI,EAAE,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAA+B,CAAC,CAAC,CAAC;QAC7D,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAiC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAe,CAAC;IACpB,IAAI,UAA8B,CAAC;IAEnC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACxB,CAAC;SAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,OAAO,GAAI,GAAG,CAAC,MAAiB,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,OAAO,GAAG,CAAC,mBAAmB,KAAK,QAAQ,EAAE,CAAC;YAChD,UAAU,GAAG,GAAG,CAAC,mBAAmB,CAAC;QACvC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,GAAG,GAAG,OAAO,aAAa,UAAU,IAAI,CAAC;IAClD,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/output/styled.d.ts

@@ -0,0 +1,19 @@
+export declare function styledIntro(command: string): void;
+export declare function styledOutro(message?: string): void;
+export declare function styledWarn(message: string): void;
+export declare function styledError(message: string): void;
+export declare function styledSuccess(message: string): void;
+export declare function styledInfo(message: string): void;
+export declare function styledMessage(content: string): void;
+export declare function styledNote(content: string, title: string): void;
+export declare function styledTable(headers: string[], rows: (string | number | null | undefined)[][], opts?: {
+    rightAlign?: number[];
+}): string;
+export declare function styledKeyValue(pairs: [string, string][]): string;
+export declare function formatBold(text: string): string;
+export declare function formatDim(text: string): string;
+export declare function formatCyan(text: string): string;
+export declare function formatGreen(text: string): string;
+export declare function formatYellow(text: string): string;
+export declare function formatRed(text: string): string;
+export declare function formatSeparator(): string;

package/dist/output/styled.js

@@ -0,0 +1,70 @@
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+export function styledIntro(command) {
+    p.intro(chalk.bgCyan.black(` ${command} `));
+}
+export function styledOutro(message = "Done") {
+    p.outro(message);
+}
+export function styledWarn(message) {
+    p.log.warn(message);
+}
+export function styledError(message) {
+    p.log.error(message);
+}
+export function styledSuccess(message) {
+    p.log.success(message);
+}
+export function styledInfo(message) {
+    p.log.info(message);
+}
+export function styledMessage(content) {
+    p.log.message(content);
+}
+export function styledNote(content, title) {
+    p.note(content, title);
+}
+export function styledTable(headers, rows, opts) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)));
+    const headerLine = headers
+        .map((h, i) => chalk.cyan.bold(h.padEnd(widths[i])))
+        .join("   ");
+    const sep = widths.map((w) => "─".repeat(w)).join("   ");
+    const body = rows.map((row) => row
+        .map((cell, i) => {
+        const s = String(cell ?? "");
+        return opts?.rightAlign?.includes(i)
+            ? s.padStart(widths[i])
+            : s.padEnd(widths[i]);
+    })
+        .join("   "));
+    return [headerLine, chalk.dim(sep), ...body].join("\n");
+}
+export function styledKeyValue(pairs) {
+    const maxKey = Math.max(...pairs.map(([k]) => k.length));
+    return pairs
+        .map(([k, v]) => `${chalk.dim(k.padStart(maxKey))}  ${v}`)
+        .join("\n");
+}
+export function formatBold(text) {
+    return chalk.bold(text);
+}
+export function formatDim(text) {
+    return chalk.dim(text);
+}
+export function formatCyan(text) {
+    return chalk.cyan(text);
+}
+export function formatGreen(text) {
+    return chalk.green(text);
+}
+export function formatYellow(text) {
+    return chalk.yellow(text);
+}
+export function formatRed(text) {
+    return chalk.red(text);
+}
+export function formatSeparator() {
+    return chalk.dim("  ·  ");
+}
+//# sourceMappingURL=styled.js.map

package/dist/output/styled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styled.js","sourceRoot":"","sources":["../../src/output/styled.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.1.15",
+  "version": "0.1.18",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "type": "module",
   "bin": {
@@ -29,6 +29,8 @@
   ],
   "license": "UNLICENSED",
   "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "chalk": "^5.6.2",
     "commander": "^13.0.0",
     "open": "^10.0.0"
   },

package/skills/graphit/SKILL.md

@@ -54,7 +54,9 @@ NEVER query the warehouse directly when a cached data source covers the table. D
 3. Only use `graphit query "SQL" --warehouse --connection <id>` if NO data source exists and the user approves
 
 **Wrong:** Jumping straight to `graphit query "SELECT SUM(cost) FROM marketing_ua" --warehouse` when a data source already caches that table.
-**Right:** `graphit ds list` first, find the DS ID, then `graphit query "SELECT SUM(cost) FROM marketing_ua" --ds ds_abc123`.
+**Right:** `graphit ds list` first, find the DS ID, then `graphit query "SELECT SUM(cost) FROM marketing_ua_ds" --ds ds_abc123`.
+
+**Use the data source name in SQL** (e.g. `FROM MARKETING_UA_DS`), not the raw source table. The DS is a KB table - governance rules target it directly, and users recognize DS names from the platform.
 
 ### 3. EVERY element must have entity wrapping
 Without `data-graphit-*` attributes, elements are invisible to the platform - no click info, no mentions, no KB provenance. Every chart, KPI card, table, and text section needs ALL FIVE attributes:
@@ -63,7 +65,7 @@ Without `data-graphit-*` attributes, elements are invisible to the platform - no
 <div data-graphit-id="revenue-trend"
      data-graphit-label="Revenue Trend"
      data-graphit-kb="metric:REVENUE,dimension:REGION,table:ORDERS"
-     data-graphit-sql="SELECT region, SUM(revenue) FROM orders_ds GROUP BY region"
+     data-graphit-sql="SELECT region, SUM(revenue) FROM orders GROUP BY region"
      data-graphit-ds="ds_abc123">
   <!-- chart/KPI/table content here -->
 </div>
@@ -73,21 +75,32 @@ Without `data-graphit-*` attributes, elements are invisible to the platform - no
 |-----------|--------|---------|
 | `data-graphit-id` | Unique kebab-case | `"spend-by-source"` |
 | `data-graphit-label` | Human-readable name | `"Ad Spend by Source"` |
-| `data-graphit-kb` | `type:NAME` comma-separated | `"metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA"` |
+| `data-graphit-kb` | `type:NAME` comma-separated | `"metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA_DS"` |
 | `data-graphit-sql` | Executable SQL (HTML-encode `<>&"`) | `"SELECT ..."` |
 | `data-graphit-ds` | Data source ID from `graphit ds list` | `"ds_abc123"` |
 
 KB types: `metric`, `dimension`, `table`, `rule`. Names are UPPER_SNAKE_CASE matching the KB exactly. **Names are unique per type per org** - creating a duplicate name will fail. Check `graphit kb list <type>` first; update the existing asset instead of creating a new one.
 Missing any attribute = broken entity. Missing wrapping entirely = invisible to the platform.
 
-**SQL must be executable.** The platform runs `data-graphit-sql` against the data source when a user opens the entity's details panel. It MUST use the real DS table name and only columns that exist in the DS - never invented summary columns, CTE aliases, JS variable names, or prose. If the chart's resolve call uses a CTE, put the full WITH query. If JS builds SQL dynamically, store one representative executable variant (e.g. the default date range).
+**SQL must be complete and executable.** The platform runs `data-graphit-sql` against the data source when a user opens the entity's details panel. Write the full query from the `graphit.resolve()` call - never abbreviate, truncate, or use placeholders (`FROM ...`, `SELECT ...`, ellipsis). It MUST use the real DS table name and only columns that exist in the DS - never invented summary columns, CTE aliases, JS variable names, or prose. If the chart's resolve call uses a CTE, put the full WITH query. If JS builds SQL dynamically, store one representative executable variant (e.g. the default date range).
 
 **Wrong:** `data-graphit-sql="SELECT INSTALL_TIME, ROIAP_D0, ROIAP_D3 FROM UA_DS"` when the DS has no ROIAP_D0 column (the chart computes it via CASE) - the details panel errors.
 **Right:** `data-graphit-sql="SELECT INSTALL_TIME, SUM(CASE WHEN SENIORITY=0 THEN TOTAL_IAP END)/NULLIF(SUM(COST),0) AS ROIAP_D0 FROM UA_DS GROUP BY 1"` - same derivation the chart runs.
 
 **Label = visible title.** The `data-graphit-label` MUST match the card's visible heading exactly. Users see the label in @ mention dropdowns and entity panels - if it doesn't match the title on screen, they can't find their chart.
 
-### 4. ALWAYS use graphit.resolve() for live data
+### 4. Shared dashboards require Edit mode on the platform
+Dashboards shared with teams are protected by an editing session lock. The CLI cannot acquire editing sessions - mutations (`dashboard update-html`, `dashboard update-entity`) on a shared dashboard will fail with **423: "Shared dashboard requires an active editing session"**.
+
+**When you see a 423 from a dashboard command:**
+1. Tell the user to open the dashboard on the Graphit platform and click the **Edit** button in the header
+2. Once they're in edit mode (draft active), CLI mutations will work because the session is held
+3. When done, the user publishes or discards from the platform UI
+4. Private dashboards (not shared with any team) are unaffected - the CLI can mutate them directly
+
+**Note:** another team member may already hold the editing session. Only one editor at a time. The user can check who's editing on the platform.
+
+### 5. ALWAYS use graphit.resolve() for live data
 NEVER embed query results as static JS variables. The dashboard iframe provides `graphit.resolve()` which fetches live data from cached data sources on every page load.
 
 **Wrong:** Running queries at build time, embedding results as `const data = [{...}, ...]` in the HTML.
@@ -193,7 +206,14 @@ For metrics with natural variant axes (D7/D30/D90, gross/net), propose parameter
 | `graphit kb delete <type> <name> --yes` | Delete any entity (all types supported) |
 | `graphit ds list` | List cached data sources (use these for fast queries) |
 | `graphit query "<sql>" --ds <id>` | Query cached data source (~100ms) |
+| `graphit query "<sql>" --ds <id> --override-rules RULE1 RULE2` | Query with governance rule overrides |
+| `graphit query "<sql>" --ds <id> --verbose` | Show expanded SQL and trust tier |
 | `graphit query "<sql>" --warehouse --connection <id>` | Query live Snowflake (~10s) |
+| `graphit governance status` | Show governance mode and conformance stats |
+| `graphit governance set <mode>` | Set governance mode (observe/warn/strict) |
+| `graphit governance audit` | View recent governance audit events |
+| `graphit ds update <id> --governed-mode on\|off` | Enable/disable governed mode on a data source |
+| `graphit ds update <id> --max-rows N` | Set max rows cap on a data source |
 | `graphit dashboard create --name "..."` | Create dashboard (returns ID) |
 | `graphit dashboard get-html <id>` | Get current HTML content of a dashboard |
 | `graphit dashboard update-html <id> --file <path>` | Upload HTML to dashboard (full page replace) |
@@ -204,42 +224,49 @@ For metrics with natural variant axes (D7/D30/D90, gross/net), propose parameter
 
 ## Presenting Results to the User
 
-The user CANNOT see raw CLI output clearly. You MUST format and present every result - never silently consume tool output and move on.
+The user CANNOT see raw CLI JSON output. You are the rendering layer - format and present every result using markdown. Per-command templates are in the reference file for each domain: `sql-reference.md` (query + DS results), `kb-traversal.md` (KB list/get/search/explore), `governance.md` (governance status + errors), `dashboard-planning.md` (dashboard + connector lists).
 
-**After every query**, show the data:
-```
-Queried **MARKETING_UA** (ds_abc123, 6 rows):
+**Core rules:** Ground every result in the KB - list referenced metrics/dimensions/tables, show both the `{{metric:X}}` query and resolved SQL, always use `--verbose`. Bold every KB asset/table/DS name. Markdown tables for tabular data. SQL in ```sql code blocks. Format numbers (commas, $, %). Governance provenance footer after every query. For ad-hoc queries, suggest the KB reference equivalent. Never silently consume output.
 
-| Channel     | Spend    | Installs | CPI   |
-|-------------|----------|----------|-------|
-| Facebook    | $42,100  | 12,400   | $3.40 |
-| Google UAC  | $38,500  | 9,800    | $3.93 |
-| TikTok      | $21,300  | 8,200    | $2.60 |
-```
-```
+---
 
-**After KB exploration**, summarize what you found:
-```
-Found **12 metrics** and **8 dimensions** on table MARKETING_UA:
-- **Metrics:** TOTAL_SPEND, CPI, ROAS_D7, ROAS_D30, INSTALLS, ...
-- **Dimensions:** MEDIA_SOURCE, CAMPAIGN_NAME, COUNTRY, PLATFORM, ...
-- **Rules:** EXCLUDE_ORGANIC (filters organic installs from paid metrics)
+## Query Governance and Reference Syntax
+
+The platform enforces server-side query governance. Use KB reference syntax for governed queries:
+
+| Syntax | Expands To | Example |
+|--------|-----------|---------|
+| `{{metric:NAME}}` | Metric calculation (aggregation) | `{{metric:CPI}}` |
+| `{{metric:NAME(K=V)}}` | Parameterized metric | `{{metric:ARPU(DAY=7)}}` |
+| `{{metric_raw:NAME}}` | Raw expression (no aggregate) | `{{metric_raw:REVENUE}}` |
+| `{{dim:NAME}}` | Dimension expression | `{{dim:INSTALL_MONTH}}` |
+
+**Parameterized metrics:** Some metrics (ARPU, ROAS, RETENTION) contain `${PARAM:X}` tokens and require explicit parameter values. Run `graphit kb list metric` - the `params` column shows required parameter names. Use `{{metric:ARPU(DAY=7)}}` to resolve `${PARAM:DAY}` to `7`. Omitting required parameters returns a clear error with the exact syntax to use. Pre-baked variants (ARPU_D7, ROAS_D30) have the value hardcoded and need no parameters.
+
+```bash
+# Governed query using reference syntax
+graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} as cpi FROM MARKETING_UA_DS GROUP BY 1" --ds ds_abc123
+
+# Parameterized metric
+graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS GROUP BY 1" --ds ds_abc123
+
+# Verbose shows expanded SQL and trust tier
+graphit query "SELECT {{metric:CPI}} as cpi FROM MARKETING_UA_DS" --ds ds_abc123 --verbose
 ```
 
-**Formatting rules:**
-- **Bold** metric names, table names, and key numbers
-- Use **markdown tables** for any tabular data (query results, entity lists, comparisons)
-- Format numbers: commas for thousands (`12,400`), `$` for currency, `%` for rates
-- After KB or data source discovery, list what's available before asking what to build
-- Show the SQL you ran (in a code block) so the user can validate the logic
-- When a query returns nulls or zero rows, explain what you checked and what went wrong
-- Narrate your progress between steps: "Found 3 data sources. Using **Marketing UA DS** (ds_abc123) which covers spend, installs, and ROAS columns."
-
-**Never do these:**
-- Run 3 queries silently then jump to building HTML
-- Say "I found the data" without showing what the data looks like
-- Present raw JSON output without formatting
-- Skip showing KB exploration results before proposing a dashboard
+Queries using reference syntax produce **governed** trust tier. Inline formulas produce **ad-hoc** tier, which may be blocked in strict mode. Use `--override-rules RULE_NAME` to bypass specific enforceable rules when the user explicitly requests it.
+
+Trust tiers: **governed** (used KB references), **verified** (raw SQL matches KB definitions), **ad-hoc** (inline formulas). Badges appear on dashboard graphs and canvas entities.
+
+Use reference syntax in `graphit.resolve()` calls too - the server expands them at query time:
+
+```js
+graphit.resolve({
+  sql: "SELECT {{dim:INSTALL_MONTH}}, {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS GROUP BY 1",
+  dataSourceId: "ds_abc123",
+  target: "#arpu-chart"
+});
+```
 
 ---
 
@@ -259,7 +286,30 @@ const result = await graphit.resolve({
 
 The `dataSourceId` is the ID from `graphit ds list`. The `target` parameter (CSS selector or element) shows a blur + spinner overlay while loading and removes it on completion. `result.data` is an array of row objects you can render however you want.
 
-**Error handling:** `graphit.resolve()` rejects on timeout (60s), bad SQL, or invalid data source ID. Wrap calls in try/catch and show a user-visible error message in the target element on failure. Verify SQL returns data via the CLI before embedding it in HTML.
+**Error handling:** `graphit.resolve()` rejects on timeout (120s), bad SQL, or invalid data source ID. Wrap calls in try/catch and show a user-visible error message in the target element on failure. Verify SQL returns data via the CLI before embedding it in HTML.
+
+### First-paint loading state
+
+The dashboard HTML paints before the SDK connects (iframe load + handshake), so the SDK's own spinner cannot cover the first moments. Bake this pure-CSS overlay into the HTML so every chart shows a spinner from the first frame; the SDK adopts it and removes it when that element's `graphit.resolve()` settles (success or error).
+
+Add once to the page `<style>`:
+
+```css
+@keyframes gh-spin{to{transform:rotate(360deg)}}
+.gh-loading{position:relative;min-height:120px}
+.gh-loading-overlay{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;z-index:9998;backdrop-filter:blur(3px);-webkit-backdrop-filter:blur(3px);background:color-mix(in srgb,var(--graphit-surface-raised,#fff) 50%,transparent);border-radius:inherit}
+.gh-loading-spin{animation:gh-spin .7s linear infinite}
+```
+
+Add inside EVERY element you pass as `target:` to `graphit.resolve()` - and ONLY those elements (a static text or title section with no resolve call would spin forever):
+
+```html
+<div id="spend-chart" class="gh-loading">
+  <div class="gh-loading-overlay"><svg class="gh-loading-spin" width="24" height="24" viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="10" stroke="var(--graphit-border,#e5e5e5)" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="var(--graphit-accent,#4DB6AC)" stroke-width="2.5" stroke-linecap="round"/></svg></div>
+</div>
+```
+
+The class names are a contract with the SDK (`gh-loading`, `gh-loading-overlay`, `gh-loading-spin`, `gh-spin`) - keep them exactly as shown or the SDK cannot adopt and remove the overlay. NEVER write text placeholders ("Loading...", "Fetching data...") - they never animate and make slow loads look stuck.
 
 ### Rendering
 
@@ -270,7 +320,7 @@ The iframe also provides optional convenience helpers if you want quick standard
 | Helper | Usage |
 |---|---|
 | `graphit.chart(el, {type, data, x, y, ...})` | Bar, line, area, donut, scatter, stacked-bar, heatmap, funnel, gauge, sparkline |
-| `graphit.table(el, {data, columns?, ...})` | Styled HTML table |
+| `graphit.table(el, {data, columns?, maxRows?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects), defaults to `Object.keys(data[0])` |
 | `graphit.kpi(el, {value, label?, format?})` | KPI card with optional delta |
 
 These are shortcuts, not requirements. Use them when a standard chart is all you need. Hand-roll when you want full control over the visualization.
@@ -284,15 +334,17 @@ These are shortcuts, not requirements. Use them when a standard chart is all you
 ```html
 <div data-graphit-id="spend-by-source"
      data-graphit-label="Ad Spend by Source"
-     data-graphit-kb="metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA"
-     data-graphit-sql="SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA GROUP BY MEDIA_SOURCE ORDER BY spend DESC"
+     data-graphit-kb="metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA_DS"
+     data-graphit-sql="SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA_DS GROUP BY MEDIA_SOURCE ORDER BY spend DESC"
      data-graphit-ds="ds_abc123">
-  <div id="spend-chart"></div>
+  <div id="spend-chart" class="gh-loading">
+    <div class="gh-loading-overlay"><svg class="gh-loading-spin" width="24" height="24" viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="10" stroke="var(--graphit-border,#e5e5e5)" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="var(--graphit-accent,#4DB6AC)" stroke-width="2.5" stroke-linecap="round"/></svg></div>
+  </div>
 </div>
 <script>
 (async function() {
   var r = await graphit.resolve({
-    sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA GROUP BY MEDIA_SOURCE ORDER BY spend DESC",
+    sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA_DS GROUP BY MEDIA_SOURCE ORDER BY spend DESC",
     dataSourceId: "ds_abc123",
     target: "#spend-chart"
   });
@@ -325,3 +377,4 @@ Detailed knowledge lives in `references/`. Consult the relevant file when you ne
 | `domain-lenses.md` | Data matches a business domain. Marketing, finance, product/growth, ops, sales - signals, key metrics, must-have charts, anti-patterns. |
 | `graphit-style.md` | Building the HTML. Design principles, typography scale, color system with usage rules, layout patterns (page structure, KPI cards, data tables). |
 | `chart-patterns.md` | Custom chart implementations. Inline SVG/CSS code for: scatter/bubble, heatmap, funnel, gauge, sparkline, stacked bar, and the shared tooltip pattern. |
+| `governance.md` | Query governance. Reference syntax, trust tiers, enforceable rules, override flow, governance commands. |

package/skills/graphit/cursor/graphit-dashboard-planning.mdc

@@ -98,3 +98,8 @@ Before generating the HTML:
 - [ ] 3+ chart types for 4+ graphs
 - [ ] Every KPI has definition + baseline + direction
 - [ ] No anti-patterns present
+
+## Presenting Dashboard & Connector Results
+
+**dashboard list**: table with **bold Name**, ID, URL.
+**connector list**: table with **bold Name**, Account, Auth.

package/skills/graphit/cursor/graphit-kb-traversal.mdc

@@ -62,3 +62,10 @@ Use `kb_explore` with max_depth=2 and no edge_type filter. Returns the table's d
 | 3 (max) | Full neighborhood. Use sparingly - can return many results for connected tables. |
 
 Start at depth 1. Only increase if the user's question requires it or the initial results are insufficient.
+
+## Presenting KB Results
+
+**kb list**: `**12 metrics** across 3 tables:` then table with **bold name**, table, calculation. Adapt columns per type.
+**kb get**: `### **CPI** (metric, verified)` + *description* + key-value table (Table, Calculation, Parameters, Topics, Dims).
+**kb search**: `**5 results** for "query":` then table with Type, **bold Name**, Description.
+**kb explore**: tree with bold names indented by level: Asset > Tables > Dimensions > Rules > Domain.

package/skills/graphit/cursor/graphit-sql-reference.mdc

@@ -117,6 +117,24 @@ SELECT UNNEST(generate_series(
 
 The outer SELECT can ONLY reference columns the subquery exposes (its aliases). Base-table columns aggregated away in the subquery do NOT exist at the outer level.
 
+## Cache-Friendly SQL (Canvas Resolve)
+
+Canvas `graphit.resolve()` queries that follow these shapes serve from a semantic cache in ~10ms on filter changes instead of a full DuckDB recompute (5-37s on wide data sources). Write resolve SQL in this style by default.
+
+**Shape rules:**
+- Single table (no JOIN/UNION)
+- WHERE as flat AND of `column = literal`, `column IN (...)`, `column BETWEEN ... AND ...` conjuncts
+- Bare aggregates only: `SUM(col)`, `COUNT(*)`, `MIN(col)`, `MAX(col)` - no wrapping functions (`ROUND(SUM(x))`), no aggregate arithmetic (`SUM(a)/NULLIF(SUM(b),0)`), no `AVG` (v2)
+- Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions
+- GROUP BY column names or ordinals; ORDER BY / LIMIT allowed (outer only)
+- CTEs are fine when the CTE body follows the same rules
+
+**Shapes that skip the cache** (fall back to normal execution, still correct):
+- `COUNT(DISTINCT x)`, window functions, HAVING, QUALIFY
+- OR / NOT in WHERE
+- Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves
+- `CURRENT_DATE`-relative predicates
+
 ## Data Source Routing
 
 | Situation | Command | Speed |
@@ -125,3 +143,18 @@ The outer SELECT can ONLY reference columns the subquery exposes (its aliases).
 | No data source | `graphit query "SQL" --warehouse --connection <id>` | ~10s, Snowflake |
 
 Always prefer cached data sources. Check with `graphit ds list`. If no data source covers the table, suggest creating one for future speed.
+
+## Presenting Query Results
+
+Ground every query in the KB. When using `{{metric:X}}`/`{{dim:X}}` references, show five sections:
+1. **KB Assets:** list all referenced metrics, dimensions, tables as bold names
+2. **Query:** original SQL with `{{metric:X}}` references in ```sql block
+3. **Resolved SQL:** expanded SQL (always use `--verbose`) in ```sql block
+4. **Results:** markdown table with right-aligned numbers, row count, DS ID
+5. **Governance:** tier, KB refs count, rules enforced (**bold names**), max rows
+
+For inline SQL (no KB refs): show query + results + governance, and suggest the KB reference equivalent to nudge toward governed tier.
+
+## Presenting Data Source Results
+
+After `graphit ds list`: table with **bold Name**, ID, Rows (right-aligned), Status, Governed. End with DS recommendation for current task.

package/skills/graphit/cursor/graphit-style.mdc

@@ -79,6 +79,12 @@ Use the system font stack everywhere: `-apple-system, BlinkMacSystemFont, 'Segoe
           box-shadow:0 1px 3px rgba(0,0,0,0.08); }
   .card h3 { font-size:12px; font-weight:600; color:var(--graphit-fg-subtle); text-transform:uppercase;
              letter-spacing:0.05em; margin-bottom:16px; }
+  @keyframes gh-spin{to{transform:rotate(360deg)}}
+  .gh-loading { position:relative; min-height:120px; }
+  .gh-loading-overlay { position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
+                        z-index:9998; backdrop-filter:blur(3px); -webkit-backdrop-filter:blur(3px);
+                        background:color-mix(in srgb,var(--graphit-surface-raised,#fff) 50%,transparent); border-radius:inherit; }
+  .gh-loading-spin { animation:gh-spin .7s linear infinite; }
   @media(max-width:900px) {
     .kpi-grid { grid-template-columns:repeat(2,1fr); }
     .charts-grid { grid-template-columns:1fr; }
@@ -118,6 +124,16 @@ Use the system font stack everywhere: `-apple-system, BlinkMacSystemFont, 'Segoe
 </style>
 ```
 
+### Loading State
 
+Bake this overlay inside every element passed as `target:` to `graphit.resolve()` - and only those (static text/title cards would spin forever). It shows from the first paint, before the SDK connects; the SDK removes it when the resolve settles. Class names are the SDK contract - keep them exactly:
+
+```html
+<div id="spend-chart" class="gh-loading">
+  <div class="gh-loading-overlay"><svg class="gh-loading-spin" width="24" height="24" viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="10" stroke="var(--graphit-border,#e5e5e5)" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="var(--graphit-accent,#4DB6AC)" stroke-width="2.5" stroke-linecap="round"/></svg></div>
+</div>
+```
+
+Never write "Loading..." text placeholders - they don't animate and make slow loads look stuck.
 
 For inline chart implementations (bar, line, donut, heatmap, funnel, sparkline, gauge, stacked bar, multi-series), see `chart-patterns.md`.