@graphit/cli 0.1.16 → 0.1.19

package/skills/graphit/SKILL.md

@@ -43,7 +43,7 @@ Your HTML must NEVER contain:
 - `<img src="https://...">` - no external images
 
 If you use ANY `src=` or `href=` pointing to a URL, the dashboard will be blank.
-All CSS in `<style>`, all JS in `<script>`, all fonts from system stack. The iframe has a built-in runtime (`graphit.chart`, `graphit.table`, `graphit.kpi`) for standard visualizations - use it instead of importing libraries.
+All CSS in `<style>`, all JS in `<script>`, all fonts from system stack. The iframe has a built-in runtime (`graphit.chart`, `graphit.table`, `graphit.kpi`, `graphit.presentation`) for standard visualizations - use it instead of importing libraries.
 
 ### 2. ALWAYS query through data sources
 NEVER query the warehouse directly when a cached data source covers the table. Data sources return in ~100ms. Warehouse queries take ~10s and cost Snowflake credits.
@@ -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,7 +75,7 @@ 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"` |
 
@@ -222,42 +224,9 @@ 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.
-
-**After every query**, show the data:
-```
-Queried **MARKETING_UA** (ds_abc123, 6 rows):
+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).
 
-| 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)
-```
-
-**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
+**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.
 
 ---
 
@@ -267,16 +236,22 @@ The platform enforces server-side query governance. Use KB reference syntax for
 
 | Syntax | Expands To | Example |
 |--------|-----------|---------|
-| `{{metric:NAME}}` | Metric calculation (aggregation) | `{{metric:ARPU}}` |
+| `{{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:ARPU}} FROM users GROUP BY 1" --ds ds_abc123
+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 {{dim:INSTALL_MONTH}}, {{metric:ARPU}} FROM users GROUP BY 1" --ds ds_abc123 --verbose
+graphit query "SELECT {{metric:CPI}} as cpi FROM MARKETING_UA_DS" --ds ds_abc123 --verbose
 ```
 
 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.
@@ -287,7 +262,7 @@ Use reference syntax in `graphit.resolve()` calls too - the server expands them
 
 ```js
 graphit.resolve({
-  sql: "SELECT {{dim:INSTALL_MONTH}}, {{metric:ARPU}} FROM users GROUP BY 1",
+  sql: "SELECT {{dim:INSTALL_MONTH}}, {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS GROUP BY 1",
   dataSourceId: "ds_abc123",
   target: "#arpu-chart"
 });
@@ -311,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
 
@@ -322,8 +320,9 @@ 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 |
+| `graphit.presentation(el)` | Full-screen slide deck. Returns builder: `.slide({bg, layout, html})` then `.start()`. See `presentations.md` |
 
 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.
 
@@ -336,15 +335,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"
   });
@@ -378,3 +379,4 @@ Detailed knowledge lives in `references/`. Consult the relevant file when you ne
 | `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. |
+| `presentations.md` | Slide deck presentations. Builder API, layouts (center/split/full), backgrounds, navigation, live data inside slides. |

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-presentations.mdc

@@ -0,0 +1,56 @@
+---
+alwaysApply: false
+description: "Graphit: Build full-screen slide deck presentations inside canvas dashboards using graphit.presentation(). Builder pattern with layouts, backgrounds, and keyboard navigation."
+globs: []
+---
+
+# Presentations
+
+Build slide deck presentations inside Graphit canvas dashboards using `graphit.presentation()`.
+
+## API
+
+```js
+var deck = graphit.presentation('#my-deck');
+deck.slide({ bg: 'dark', layout: 'center', html: '<h1>Title</h1>' });
+deck.slide({ bg: 'white', layout: 'split', html: '<div>Left</div><div>Right</div>' });
+deck.slide({ bg: 'paper', layout: 'full', html: '<div id="charts">...</div>' });
+var ctrl = deck.start();
+```
+
+## Slide Config
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `layout` | `'center'` / `'split'` / `'full'` | `'center'` | Content arrangement |
+| `bg` | `'paper'` / `'white'` / `'dark'` / `'teal'` / hex | `'paper'` | Fixed background |
+| `html` | `string` | `''` | Raw HTML content |
+
+## Layouts
+
+- **center**: Centered horizontally/vertically. Title slides, CTAs.
+- **split**: First two child elements become left/right panels. Text + image.
+- **full**: Top-to-bottom flow. Tables, grids, live data.
+
+## Backgrounds (fixed, not theme-aware)
+
+| Name | Background | Text |
+|------|-----------|------|
+| `paper` | `#F7F6F2` | `#222224` |
+| `white` | `#FFFFFF` | `#222224` |
+| `dark` | `#222224` | `#F7F6F2` |
+| `teal` | `#4DB6AC` | `#FFFFFF` |
+
+## Navigation
+
+Arrow keys, spacebar, Home/End. Prev/Next buttons bottom-right with slide counter.
+
+## Live data works inside slides
+
+`graphit.resolve()` + `graphit.chart/table/kpi` work inside slides. Entity wrapping (`data-graphit-*`) works normally.
+
+## Anti-Patterns
+
+- Don't use external fonts/images (CSP blocks). Embed as base64 or use system fonts.
+- Don't put scrollable content on slides. Split into multiple slides.
+- One `graphit.presentation()` per dashboard.

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

@@ -117,6 +117,26 @@ 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
+- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY
+
+**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
+- Top-N with aggregate only in ORDER BY (`SELECT dim FROM t GROUP BY dim ORDER BY SUM(metric) DESC LIMIT N` - no decomposable aggregate in SELECT)
+
 ## Data Source Routing
 
 | Situation | Command | Speed |
@@ -125,3 +145,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`.

package/skills/graphit/graphit.mdc

@@ -25,6 +25,8 @@ NEVER query the warehouse directly when a cached data source covers the table. D
 
 Run `graphit ds list` FIRST. If a DS covers your table, use `graphit query "SQL" --ds <id>`. Only use `--warehouse` if NO data source exists and the user approves.
 
+**Use the DS name in SQL, not the source table name.** Write `FROM MARKETING_UA_DS`, not `FROM MARKETING_UA`. The DS name is what users see in the platform. DuckDB resolves both, but the DS name keeps SQL consistent with the UI.
+
 ### 3. EVERY element must have entity wrapping
 Without `data-graphit-*` attributes, elements are invisible to the platform. Every chart, KPI card, table, and text section needs ALL FIVE attributes:
 
@@ -32,7 +34,7 @@ Without `data-graphit-*` attributes, elements are invisible to the platform. Eve
 <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>
@@ -42,7 +44,7 @@ Without `data-graphit-*` attributes, elements are invisible to the platform. Eve
 |-----------|--------|---------|
 | `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"` |
 
@@ -63,6 +65,38 @@ NEVER embed query results as static JS variables. The dashboard iframe provides
 
 ---
 
+## Presenting Results to the User
+
+You are the rendering layer - format and present every CLI result using markdown. Never silently consume output.
+
+**Formatting fundamentals:** Bold every KB asset/table/DS name (**CPI**, **MARKETING_UA_DS**). Markdown tables for tabular data. Code blocks (```sql) for every SQL query. Format numbers: commas (12,400), $ for currency, % for rates. Narrate between steps.
+
+**After `graphit query`** - ground in KB, show five sections:
+1. **KB Assets:** bold names of all referenced metrics/dimensions/tables
+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, row count, DS ID
+5. **Governance:** tier, KB refs, rules enforced (**bold names**)
+- For ad-hoc queries: show query + results + governance, suggest KB reference equivalent
+
+**After `graphit kb list`** - count summary + table with bold names:
+- `**12 metrics** across 3 tables:` then table with **bold name**, table, calculation, params
+- Footer summarizing parameterized vs pre-baked
+
+**After `graphit kb get`** - entity heading + key-value table:
+- `### **CPI** (metric, verified)` with description in italics
+- Key-value table: Table, Calculation, Parameters, Topics, Dimensions
+
+**After `graphit kb search`** - result count + table with type column
+**After `graphit kb explore`** - tree structure: Asset > Tables > Dimensions > Rules
+**After `graphit ds list`** - table with Name, ID, Rows, Status, Governed + recommend which DS to use
+**After `graphit governance status`** - mode + conformance table (Governed/Ad-hoc/Blocked with counts and %)
+**After errors** - bold error message + actionable fix suggestion
+
+**Never:** run queries silently, present raw JSON, skip governance footer, omit SQL code blocks, show tables without bold asset names.
+
+---
+
 ## Workflow: Dashboard Build
 
 1. **Ask the user** what dashboard they want.
@@ -87,13 +121,17 @@ When the user wants to build or populate their KB from files, schemas, or scratc
 ## Query Governance and Reference Syntax
 
 Use KB references for governed queries:
-- `{{metric:NAME}}` - expands to metric calculation
+- `{{metric:NAME}}` - expands to metric calculation, e.g. `{{metric:CPI}}`
+- `{{metric:NAME(K=V)}}` - parameterized metric, e.g. `{{metric:ARPU(DAY=7)}}`
 - `{{dim:NAME}}` - expands to dimension expression
 - `{{metric_raw:NAME}}` - raw expression (no aggregate)
 
+**Parameterized metrics:** Some metrics require parameters (check `graphit kb list metric` - `params` column). Use `{{metric:ARPU(DAY=7)}}` to resolve `${PARAM:DAY}`. Pre-baked variants (ARPU_D7, ROAS_D30) need no parameters.
+
 ```bash
-graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:ARPU}} FROM users GROUP BY 1" --ds ds_abc123
-graphit query "SELECT * FROM events" --ds ds_123 --override-rules EXCLUDE_RETARGETING  # bypass rule
+graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} as cpi FROM MARKETING_UA_DS GROUP BY 1" --ds ds_abc123
+graphit query "SELECT {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS" --ds ds_abc123  # parameterized
+graphit query "SELECT * FROM events" --ds ds_123 --override-rules EXCLUDE_RETARGETING   # bypass rule
 graphit governance status   # view mode and conformance
 graphit governance set warn # change mode (admin)
 graphit ds update <id> --governed-mode on  # enable governance on DS
@@ -113,14 +151,27 @@ const result = await graphit.resolve({
 // Returns: { columns: string[], data: object[], rowCount: number, truncated: boolean }
 ```
 
-**Error handling:** Rejects on timeout (60s), bad SQL, or invalid data source ID. Wrap in try/catch.
+**Error handling:** Rejects on timeout (120s), bad SQL, or invalid data source ID. Wrap in try/catch.
+
+### First-paint loading state
+
+The HTML paints before the SDK connects, so bake a pure-CSS spinner overlay into the page; 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 the overlay inside EVERY element you pass as `target:` - and ONLY those elements (a static text/title section with no resolve call would spin forever). Keep the class names exactly as shown; they are the contract the SDK uses to adopt and remove the overlay. NEVER write text placeholders ("Loading...", "Fetching data...") - they never animate and make slow loads look stuck. See the canonical pattern below for the overlay markup.
 
 ### Runtime chart helpers
 
 | 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 |
 
 `graphit.chart` types: `"bar"`, `"line"`, `"area"`, `"donut"` (alias `"pie"`), `"scatter"` (alias `"bubble"`), `"stacked-bar"` (alias `"stacked"`), `"heatmap"`, `"funnel"`, `"gauge"`, `"sparkline"`. Config: `x` (category field), `y` (value field), `series` (group-by), `title`, `height` (140-900px), `valueFormat` (`"currency"` | `"percent"` | `"number"`), `colors` (array). Scatter adds: `size`, `label`. Gauge adds: `min`, `max`, `format`. Sparkline adds: `width`, `showValue`.
@@ -130,15 +181,17 @@ const result = await graphit.resolve({
 ```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"
   });

package/skills/graphit/references/dashboard-planning.md

@@ -92,3 +92,27 @@ Before generating the HTML:
 - [ ] 3+ chart types for 4+ graphs
 - [ ] Every KPI has definition + baseline + direction
 - [ ] No anti-patterns present
+
+## Presenting Dashboard & Connector Results
+
+**After `graphit dashboard list`:**
+
+~~~
+**4 dashboards:**
+
+| Name | ID | URL |
+|---|---|---|
+| **UA Command Center** | dash_abc | https://app.graphit-app.com/custom-dashboard/dash_abc |
+| **Player Quality** | dash_def | https://app.graphit-app.com/custom-dashboard/dash_def |
+~~~
+
+**After `graphit connector list`:**
+
+~~~
+**2 connections:**
+
+| Name | Account | Auth |
+|---|---|---|
+| **prod-snowflake** | xy12345.us-east-1 | OAuth |
+| **staging-sf** | ab67890.us-east-1 | Keypair |
+~~~

package/skills/graphit/references/governance.md

@@ -8,12 +8,12 @@ Use KB references instead of inline formulas for governed queries:
 
 ```sql
 -- Governed: server expands to KB-defined formulas
-SELECT {{dim:INSTALL_MONTH}}, {{metric:ARPU}}
-FROM users
+SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} as cpi
+FROM MARKETING_UA_DS
 GROUP BY 1
 
--- Parameterized metric
-SELECT {{metric:ARPU(period=monthly)}} FROM users
+-- Parameterized metric (ARPU requires DAY parameter)
+SELECT {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS
 
 -- Raw expression (no outer aggregate)
 SELECT {{metric_raw:REVENUE}} FROM orders
@@ -21,6 +21,8 @@ SELECT {{metric_raw:REVENUE}} FROM orders
 
 The server compiles references to actual expressions, injects rule constraints, stamps trust tier, and caches results. Reference syntax works in both `graphit query` and `graphit.resolve()`.
 
+**Parameterized metrics:** Some metrics (ARPU, ROAS, RETENTION) require parameters. Check `graphit kb list metric` - the `params` column shows required names. Pre-baked variants (ARPU_D7, ROAS_D30) have values hardcoded and need no parameters. Omitting required parameters returns a clear error with the exact syntax to use.
+
 ## Trust Tiers
 
 | Tier | Meaning | Badge |
@@ -76,3 +78,29 @@ graphit ds update <id> --governed-mode on    # Enable governed mode
 graphit ds update <id> --governed-mode off   # Disable
 graphit ds update <id> --max-rows 10000      # Set row cap
 ```
+
+## Presenting Governance Results
+
+**After `graphit governance status`:**
+
+~~~
+**Governance mode:** strict
+
+**7-day conformance:**
+
+| Tier | Queries | Share |
+|---|---:|---:|
+| Governed | 847 | 72% |
+| Ad-hoc | 328 | 28% |
+| Blocked | 12 | 1% |
+
+5 active rules across 3 governed data sources.
+~~~
+
+**After governance errors:**
+
+~~~
+**Error:** Query blocked by governance.
+
+Rule **EXCLUDE_ORGANIC** (override policy: `never`) cannot be overridden. Contact your admin to change the policy, or rewrite the query to include the required filter.
+~~~

package/skills/graphit/references/graphit-style.md

@@ -37,6 +37,17 @@ NEVER use hardcoded hex colors. Use CSS custom properties that automatically ada
 - **Warning:** `var(--graphit-warning)`
 - **Danger / bad:** `var(--graphit-error)`
 
+### Custom Colors
+
+When the user explicitly requests specific colors or a custom color theme, ask for both light and dark mode variants. Write explicit CSS with `.dark` class overrides so the dashboard adapts to both modes:
+
+```css
+.revenue-card { background: #001f3f; color: #ffffff; }
+.dark .revenue-card { background: #0a3d6b; color: #e0e0e0; }
+```
+
+NEVER hardcode a structural color (background, color, border-color) without a `.dark` counterpart. Data/chart series colors (bar fills, line strokes) are exempt - they work in both modes.
+
 ### Multi-Series
 Use `var(--graphit-accent)` as the primary series. For additional series, choose muted complementary colors that work on both light and dark backgrounds.
 
@@ -73,6 +84,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; }
@@ -112,6 +129,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`.