@graphit/cli 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -4,7 +4,8 @@ description: >
   Build HTML dashboards with Graphit. KB-aware queries, entity wrapping, cached data sources.
   Triggers on: "dashboard", "graphit", "KB", "metric", "data source", "build a dashboard",
   "explore the KB", "query data", "custom dashboard".
-version: "0.4.0"
+  Do NOT activate for: editing platform-native dashboard widgets, non-HTML output formats,
+  general data analysis without a dashboard deliverable.
 ---
 
 # Graphit CLI
@@ -21,8 +22,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.
-Build charts with: CSS width% bars, inline SVG paths, or `<canvas>` with inline drawing code.
-All CSS in `<style>`, all JS in `<script>`, all fonts from system stack.
+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.
 
 ### 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.
@@ -59,15 +59,21 @@ Missing any attribute = broken entity. Missing wrapping entirely = invisible to
 
 **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
+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.
+**Right:** Using `graphit.resolve({sql, dataSourceId})` in a `<script>` block so data refreshes automatically.
+
 ---
 
 ## Workflow
 
 1. **Ask the user** what dashboard they want. Don't start querying until you know what they need.
-2. **Explore KB** to understand available metrics, dimensions, tables, and tables.
+2. **Explore KB** to understand available metrics, dimensions, tables, and rules.
 3. **Find a data source** (`graphit ds list`) - prefer cached data sources (~100ms) over live warehouse (~10s).
-4. **Query data** and embed results as inline JS variables.
-5. **Build HTML** - all CSS and JS must be inline. Write to a local `.html` file.
+4. **Query data to validate** - run queries via the CLI to verify SQL and preview results. Show the user what you found.
+5. **Build HTML** - write `graphit.resolve()` calls for live data + `graphit.chart/table/kpi` for rendering. All CSS in `<style>`, all JS in `<script>`. Write to a local `.html` file.
 6. **Save** with `graphit dashboard update-html <id> --file <path>`.
 7. Give the user the dashboard URL so they can open it.
 
@@ -130,21 +136,65 @@ Found **12 metrics** and **8 dimensions** on table MARKETING_UA:
 
 ---
 
-## Chart Type Quick Reference
+## graphit.resolve() - Live Data API
+
+The iframe provides `graphit.resolve()` to fetch live data from cached data sources. This is how your HTML gets its data - never embed static query results.
+
+```js
+const result = await graphit.resolve({
+  sql: "SELECT region, SUM(revenue) as rev FROM orders GROUP BY region",
+  dataSourceId: "ds_abc123",
+  target: "#chart-container",  // optional: shows loading spinner on element
+  maxRows: 10000               // optional: default 10K, max 10K
+});
+// Returns: { columns: string[], data: object[], rowCount: number, truncated: boolean }
+```
+
+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.
+
+### Rendering
+
+You have full creative freedom for how to present data. Build charts with inline SVG, CSS, HTML tables, creative layouts - whatever fits the dashboard best.
 
-| Data shape | Chart | Inline technique |
-|---|---|---|
-| 1 temporal + 1 numeric | Line | SVG path |
-| 1 categorical + 1 numeric | Bar | CSS width% divs |
-| Single number | KPI card | Styled div |
-| Part-whole (max 5) | Donut | Canvas arc |
-| Matrix / cohort | Heatmap | CSS grid + opacity |
-| Stages | Funnel | CSS width% bars, narrowing |
-| Time sparkline | Sparkline | Inline SVG path |
-| Detail / raw data | Table | HTML table + hover rows |
+The iframe also provides optional convenience helpers if you want quick standard charts:
 
-For more chart types (scatter, stacked bar, gauge, multi-series) see `references/chart-selection.md`.
-For inline implementations of each, see `references/graphit-style.md` (Chart Patterns section).
+| 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.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.
+
+`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 field), `title`, `height` (140-900px), `valueFormat` (`"currency"` | `"percent"` | `"number"`), `colors` (array). Scatter adds: `size` (bubble radius field), `label` (tooltip field). Gauge adds: `min`, `max`, `format`. Sparkline adds: `width`, `showValue`.
+
+`graphit.kpi` config: `value`, `label`, `format` (`"currency"` | `"percent"` | `"number"`), `compareValue`, `compareLabel`.
+
+### Canonical pattern - entity with live data
+
+```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">
+  <div id="spend-chart"></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",
+    dataSourceId: "ds_abc123",
+    target: "#spend-chart"
+  });
+  graphit.chart("#spend-chart", {
+    type: "bar", data: r.data, x: "MEDIA_SOURCE", y: "spend",
+    title: "Ad Spend by Source", valueFormat: "currency"
+  });
+})();
+</script>
+```
 
 ---
 
@@ -160,4 +210,4 @@ Detailed knowledge lives in `references/`. Consult the relevant file when you ne
 | `sql-reference.md` | Writing queries. DuckDB/Snowflake translation, formatting standards, gap-filling, JSON access, data source routing. |
 | `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` | Implementing charts. Inline CSS/SVG/canvas code for: horizontal bar, vertical bar, stacked bar, line/area, multi-series line, sparkline, donut, heatmap grid, funnel, gauge. |
+| `chart-patterns.md` | Custom chart implementations. Inline SVG/CSS code for: scatter/bubble, heatmap, funnel, gauge, sparkline, stacked bar, and the shared tooltip pattern. |

package/skill/cursor/graphit-chart-patterns.mdc

@@ -1,148 +1,86 @@
 ---
 alwaysApply: false
-description: "Graphit: Inline CSS/SVG/canvas implementations for dashboards. No external libraries - the iframe CSP blocks all external resources."
+description: "Graphit: Runtime chart types via graphit.chart() and hand-rolled patterns. All data from graphit.resolve()."
 globs: []
 ---
 
 # Chart Patterns
 
-Inline CSS/SVG/canvas implementations for dashboards. No external libraries - the iframe CSP blocks all external resources.
+All chart types are available via `graphit.chart()`. All data comes from `graphit.resolve()` - never embed static data.
 
-## CSS Horizontal Bar
-```js
-var maxVal = Math.max.apply(null, data.map(function(d){return d.value}));
-data.forEach(function(d) {
-  var pct = (d.value / maxVal * 100).toFixed(1);
-  container.innerHTML += '<div style="display:flex;align-items:center;gap:12px;margin-bottom:8px">'
-    + '<span style="width:100px;font-size:13px;font-weight:500;text-align:right">' + d.name + '</span>'
-    + '<div style="flex:1;height:28px;background:var(--graphit-surface-sunken);border-radius:6px;overflow:hidden">'
-    + '<div style="width:' + pct + '%;height:100%;background:var(--graphit-accent);border-radius:6px;min-width:2px"></div></div>'
-    + '<span style="width:70px;font-size:13px;font-weight:600;text-align:right">' + fmt(d.value) + '</span></div>';
-});
-```
+**NEVER use `<canvas>`.** Canvas produces blurry charts inside the sandboxed iframe due to DPI scaling issues.
 
-## CSS Vertical Bar (Column)
-```js
-var maxVal = Math.max.apply(null, data.map(function(d){return d.value}));
-container.style.cssText = 'display:flex;align-items:flex-end;gap:8px;height:200px;padding-top:20px';
-data.forEach(function(d) {
-  var pct = (d.value / maxVal * 100).toFixed(1);
-  container.innerHTML += '<div style="flex:1;height:' + pct + '%;background:var(--graphit-accent);border-radius:4px 4px 0 0;'
-    + 'position:relative;min-width:30px">'
-    + '<span style="position:absolute;top:-20px;left:50%;transform:translateX(-50%);font-size:12px;font-weight:600">'
-    + d.value + '</span>'
-    + '<span style="position:absolute;bottom:-22px;left:50%;transform:translateX(-50%);font-size:11px;color:var(--graphit-fg-subtle);white-space:nowrap">'
-    + d.name + '</span></div>';
-});
-```
+## Runtime chart types
 
-## CSS Stacked Bar
-```js
-var colors = ['var(--graphit-accent)','#80CBC4','#26A69A','#5FA39B'];
-data.forEach(function(row) {
-  var total = row.segments.reduce(function(a,s){return a+s.value},0);
-  var html = '<div style="display:flex;align-items:center;gap:12px;margin-bottom:8px">'
-    + '<span style="width:100px;font-size:13px;font-weight:500;text-align:right">' + row.name + '</span>'
-    + '<div style="flex:1;height:28px;display:flex;border-radius:6px;overflow:hidden">';
-  row.segments.forEach(function(s, i) {
-    html += '<div style="width:' + (s.value/total*100).toFixed(1) + '%;height:100%;background:' + colors[i%colors.length] + '"></div>';
-  });
-  html += '</div><span style="width:70px;font-size:13px;font-weight:600;text-align:right">' + total + '</span></div>';
-  container.innerHTML += html;
-});
-```
+### bar
+SVG vertical bars. Multi-series: grouped side-by-side. Y-axis: 4 grid lines with formatted labels. X-axis: category labels (sampled if >12). Rounded top corners (rx=3). `<title>` tooltips per bar.
 
-## SVG Line/Area Chart
-```js
-var w = 600, h = 200, pad = 20;
-var maxVal = Math.max.apply(null, data.map(function(d){return d.value}));
-var points = data.map(function(d, i) {
-  var x = pad + (i / (data.length - 1)) * (w - 2*pad);
-  var y = h - pad - ((d.value / maxVal) * (h - 2*pad));
-  return x + ',' + y;
-});
-svg.setAttribute('viewBox', '0 0 ' + w + ' ' + h);
-svg.innerHTML =
-  '<path d="M' + points.join(' L') + ' L' + (w-pad) + ',' + (h-pad) + ' L' + pad + ',' + (h-pad) + ' Z" fill="rgba(77,182,172,0.15)"/>'
-  + '<path d="M' + points.join(' L') + '" fill="none" stroke="var(--graphit-accent)" stroke-width="2"/>';
-```
+### line / area
+SVG line with circle dots at each point. Area adds filled path below (opacity 0.18). Multi-series: separate colored paths. Y-axis scaled to data range (min to max). `<title>` tooltips per dot.
 
-## SVG Multi-Series Line
-```js
-var colors = ['var(--graphit-accent)','#FF7043','#7E57C2','#42A5F5'];
-series.forEach(function(s, si) {
-  var pts = s.values.map(function(v, i) {
-    var x = pad + (i / (s.values.length - 1)) * (w - 2*pad);
-    var y = h - pad - ((v / maxAll) * (h - 2*pad));
-    return x + ',' + y;
-  });
-  svg.innerHTML += '<path d="M' + pts.join(' L') + '" fill="none" stroke="' + colors[si] + '" stroke-width="2"/>';
-});
-```
+### donut / pie
+SVG pie slices with center hole (58% of radius). Center shows formatted total. Legend below with color swatches.
 
-## SVG Sparkline (for KPI cards)
-```js
-var vals = [10,15,12,18,22,19,25];
-var max = Math.max.apply(null,vals), min = Math.min.apply(null,vals);
-var pts = vals.map(function(v,i){
-  return (i/(vals.length-1))*120 + ',' + (30 - ((v-min)/(max-min||1))*26 - 2);
-}).join(' L');
-sparkSvg.innerHTML = '<path d="M' + pts + '" fill="none" stroke="var(--graphit-accent)" stroke-width="1.5"/>';
-```
+### scatter / bubble
+SVG circles positioned by x/y. Size field scales radius (sqrt, 3-40px). Fill opacity 0.6 with solid stroke. 4 horizontal grid lines. Capped at 200 points.
+Config: `x`, `y`, `size` (optional radius), `label` (tooltip), `xFormat`.
 
-## Canvas Donut Chart
-```js
-var ctx = canvas.getContext('2d');
-var slices = [{v:40,c:'var(--graphit-accent)'},{v:25,c:'#80CBC4'},{v:20,c:'#26A69A'},{v:15,c:'#009688'}];
-var total = slices.reduce(function(a,s){return a+s.v},0);
-var cx=150, cy=150, r=120, hole=70, angle = -Math.PI/2;
-slices.forEach(function(s) {
-  var arc = (s.v/total)*Math.PI*2;
-  ctx.beginPath(); ctx.moveTo(cx,cy);
-  ctx.arc(cx,cy,r,angle,angle+arc);
-  ctx.fillStyle=s.c; ctx.fill(); angle+=arc;
-});
-ctx.beginPath(); ctx.arc(cx,cy,hole,0,Math.PI*2);
-ctx.fillStyle='white'; ctx.fill();
-```
+### stacked-bar / stacked
+SVG vertical stacked bars. Segments stacked bottom-to-top per category. Y-axis scaled to max total. Legend shows series names.
+Config: requires `series` field for stacking groups.
 
-## CSS Heatmap Grid
-```js
-var max = Math.max.apply(null, cells.map(function(c){return c.value}));
-container.style.cssText = 'display:grid;grid-template-columns:repeat(' + cols + ',1fr);gap:2px';
-cells.forEach(function(c) {
-  var intensity = c.value / max;
-  var bg = 'rgba(77,182,172,' + (0.1 + intensity*0.9).toFixed(2) + ')';
-  var fg = intensity > 0.6 ? 'white' : 'var(--graphit-fg)';
-  container.innerHTML += '<div style="aspect-ratio:1;border-radius:3px;display:flex;align-items:center;'
-    + 'justify-content:center;font-size:11px;font-weight:600;background:' + bg + ';color:' + fg + '">'
-    + c.value + '</div>';
-});
-```
+### heatmap
+CSS grid. X = columns, Y = rows. Background intensity scales linearly with theme accent token. Text flips to raised surface color at >55% intensity. Headers auto-generated. Capped at 40x40.
+Config: `x` (column), `y` (row), `value` (intensity, falls back to `y`).
 
-## CSS Funnel
-```js
-var maxVal = data[0].value;
-data.forEach(function(d, i) {
-  var pct = (d.value / maxVal * 100).toFixed(1);
-  var rate = i > 0 ? (d.value / data[i-1].value * 100).toFixed(1) + '%' : '';
-  container.innerHTML += '<div style="display:flex;align-items:center;gap:12px;margin-bottom:6px">'
-    + '<span style="width:120px;font-size:13px;text-align:right">' + d.name + '</span>'
-    + '<div style="width:' + pct + '%;height:36px;background:var(--graphit-accent);border-radius:4px;'
-    + 'display:flex;align-items:center;padding:0 12px;color:white;font-weight:600;font-size:13px">'
-    + d.value.toLocaleString() + '</div>'
-    + '<span style="font-size:12px;color:var(--graphit-fg-subtle)">' + rate + '</span></div>';
-});
-```
+### funnel
+CSS horizontal bars narrowing top-to-bottom. First bar = 100% width, rest proportional. Shows step-over-step conversion rate. Colors cycle through palette.
+
+### gauge
+CSS half-circle via `conic-gradient` + `clip-path`. Auto-colors: green (>=70%), yellow (>=40%), red (<40%). Override with `color` config (must be a valid CSS color token).
+Config: `value`, `min` (default 0), `max` (default 100), `format`, `label`, `color`.
+
+### sparkline
+Inline SVG polyline for KPI cards or table cells. No axes, no grid - just trend shape. Single data point renders as a dot.
+Config: `y`, `width` (default 120), `height` (default 32), `label`, `showValue` (default true), `valueFormat`.
+
+## Color tokens
+
+| Token | Usage |
+|---|---|
+| `var(--graphit-accent)` | Primary brand teal |
+| `var(--graphit-success)` | Positive/good |
+| `var(--graphit-warning)` | Caution |
+| `var(--graphit-error)` | Negative/bad |
+| `var(--graphit-fg)` | Primary text |
+| `var(--graphit-fg-muted)` | Secondary text |
+| `var(--graphit-fg-subtle)` | Labels, placeholders |
+| `var(--graphit-border)` | Borders, grid lines |
+| `var(--graphit-surface-raised)` | Card backgrounds |
+| `var(--graphit-surface-sunken)` | Inset areas |
+
+## Tooltip pattern (for hand-rolled charts)
+
+Runtime charts use `<title>` elements for native browser tooltips. For hand-rolled charts, add ONE shared tooltip div and always escape user data before passing to `showTooltip()`:
 
-## CSS Gauge / Progress
 ```html
-<div style="position:relative;width:200px;height:100px;overflow:hidden">
-  <div id="gauge-arc" style="width:200px;height:200px;border-radius:50%;
-       background:conic-gradient(var(--graphit-accent) 0% 72%, var(--graphit-surface-sunken) 72% 100%);
-       clip-path:inset(0 0 50% 0)"></div>
-  <div style="position:absolute;bottom:0;left:50%;transform:translateX(-50%);
-       font-size:28px;font-weight:700">72%</div>
-</div>
+<div id="tooltip" style="position:fixed;pointer-events:none;z-index:100;
+  background:var(--graphit-surface-raised);color:var(--graphit-fg);
+  border:1px solid var(--graphit-border);border-radius:8px;
+  padding:10px 14px;font-size:13px;line-height:1.5;
+  box-shadow:0 4px 12px rgba(0,0,0,0.15);opacity:0;transition:opacity 0.15s;
+  max-width:240px"></div>
+```
+
+```js
+var tooltip = document.getElementById('tooltip');
+function showTooltip(e, html) {
+  tooltip.innerHTML = html;
+  tooltip.style.opacity = '1';
+  var tx = Math.min(e.clientX + 12, window.innerWidth - 260);
+  var ty = e.clientY - tooltip.offsetHeight - 8;
+  tooltip.style.left = tx + 'px';
+  tooltip.style.top = (ty < 4 ? e.clientY + 16 : ty) + 'px';
+}
+function hideTooltip() { tooltip.style.opacity = '0'; }
 ```
-Dynamic: set `background: conic-gradient(var(--graphit-accent) 0% ${pct}%, var(--graphit-surface-sunken) ${pct}% 100%)`.

package/skill/graphit.mdc

@@ -1,6 +1,6 @@
 ---
 alwaysApply: false
-description: "Build Graphit HTML dashboards with KB-aware queries and entity wrapping"
+description: "Build Graphit HTML dashboards with KB-aware queries, entity wrapping, and cached data sources"
 globs: []
 ---
 
@@ -18,11 +18,15 @@ 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.
-Build charts with: CSS width% bars, inline SVG paths, or `<canvas>` with inline drawing code.
-All CSS in `<style>`, all JS in `<script>`, all fonts from system stack.
+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.
 
-### 2. 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 FOUR attributes:
+### 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.
+
+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.
+
+### 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 FOUR attributes:
 
 ```html
 <div data-graphit-id="revenue-trend"
@@ -42,94 +46,72 @@ Without `data-graphit-*` attributes, elements are invisible to the platform - no
 
 KB types: `metric`, `dimension`, `table`, `rule`. Names are UPPER_SNAKE_CASE matching the KB exactly.
 
-**Label = visible title.** The `data-graphit-label` MUST match the card's visible heading exactly. Users see labels in @ mention dropdowns - mismatched labels mean they can't find their chart.
+**Label = visible title.** The `data-graphit-label` MUST match the card's visible heading exactly.
 
-### 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.
+### 4. 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.
 
-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.
+**Wrong:** Embedding results as `const data = [{...}, ...]` in the HTML.
+**Right:** Using `graphit.resolve({sql, dataSourceId})` in a `<script>` block so data refreshes automatically.
 
 ---
 
 ## Workflow
 
-1. **Ask the user** what dashboard they want. Don't start querying until you know what they need.
-2. **Explore KB** to understand available metrics, dimensions, tables, and tables.
-3. **Find a data source** (`graphit ds list`) - prefer cached data sources (~100ms) over live warehouse (~10s).
-4. **Query data** and embed results as inline JS variables.
-5. **Build HTML** - all CSS and JS must be inline. Write to a local `.html` file.
+1. **Ask the user** what dashboard they want.
+2. **Explore KB** to understand available metrics, dimensions, tables, and rules.
+3. **Find a data source** (`graphit ds list`) - prefer cached data sources over live warehouse.
+4. **Query data to validate** - run queries via the CLI to verify SQL and preview results.
+5. **Build HTML** - write `graphit.resolve()` calls for live data + `graphit.chart/table/kpi` for rendering. All CSS in `<style>`, all JS in `<script>`.
 6. **Save** with `graphit dashboard update-html <id> --file <path>`.
-7. Give the user the dashboard URL so they can open it.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `graphit kb list <type>` | List metrics, dimensions, tables, rules, domains, synonyms |
-| `graphit kb get <type> <name>` | Full entity details by name |
-| `graphit kb search <query>` | Search across all KB types |
-| `graphit kb explore metric <name>` | Metric -> tables -> dimensions graph |
-| `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>" --warehouse --connection <id>` | Query live Snowflake (~10s) |
-| `graphit dashboard create --name "..."` | Create dashboard (returns ID) |
-| `graphit dashboard update-html <id> --file <path>` | Upload HTML to dashboard |
-| `graphit dashboard list` | List existing dashboards |
-| `graphit metadata schemas --connection <id>` | List Snowflake schemas |
-| `graphit connector list` | List active connections |
-
-## 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:
+7. Give the user the dashboard URL.
+
+## graphit.resolve() - Live Data API
+
+```js
+const result = await graphit.resolve({
+  sql: "SELECT region, SUM(revenue) as rev FROM orders GROUP BY region",
+  dataSourceId: "ds_abc123",
+  target: "#chart-container",  // optional: shows loading spinner
+  maxRows: 10000               // optional: default 10K, max 10K
+});
+// Returns: { columns: string[], data: object[], rowCount: number, truncated: boolean }
 ```
-Queried **MARKETING_UA** (ds_abc123, 6 rows):
 
-| 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 |
-```
-```
+**Error handling:** Rejects on timeout (60s), bad SQL, or invalid data source ID. Wrap in try/catch.
 
-**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)
-```
+### Runtime chart helpers
 
-**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
+| 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.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`.
 
-## Chart Type Quick Reference
-
-| Data shape | Chart | Inline technique |
-|---|---|---|
-| 1 temporal + 1 numeric | Line | SVG path |
-| 1 categorical + 1 numeric | Bar | CSS width% divs |
-| Single number | KPI card | Styled div |
-| Part-whole (max 5) | Donut | Canvas arc |
-| Matrix / cohort | Heatmap | CSS grid + opacity |
-| Stages | Funnel | CSS width% bars, narrowing |
-| Time sparkline | Sparkline | Inline SVG path |
-| Detail / raw data | Table | HTML table + hover rows |
+### Canonical pattern - entity with live data
+
+```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">
+  <div id="spend-chart"></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",
+    dataSourceId: "ds_abc123",
+    target: "#spend-chart"
+  });
+  graphit.chart("#spend-chart", {
+    type: "bar", data: r.data, x: "MEDIA_SOURCE", y: "spend",
+    title: "Ad Spend by Source", valueFormat: "currency"
+  });
+})();
+</script>
+```
 
 For detailed chart selection logic, dashboard planning, SQL reference, domain-specific lenses, Graphit visual style, and chart pattern implementations, see the companion rule files (graphit-planning, graphit-sql, graphit-lenses, graphit-style, graphit-kb, graphit-patterns).