@graphit/cli 0.1.1 → 0.1.3

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "graphit-cli",
+  "owner": {
+    "name": "Graphit",
+    "email": "support@graphit-app.com",
+    "url": "https://graphit-app.com"
+  },
+  "metadata": {
+    "description": "Graphit CLI plugin for AI coding assistants",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "graphit",
+      "description": "Build custom HTML dashboards from real data. KB-aware queries, entity wrapping, cached data sources.",
+      "source": {
+        "type": "npm",
+        "package": "@graphit/cli"
+      },
+      "version": "0.1.3",
+      "category": "data-visualization",
+      "tags": ["bi", "dashboard", "sql", "data", "visualization"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "graphit",
+  "version": "0.1.3",
+  "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
+  "author": {
+    "name": "Graphit",
+    "email": "support@graphit-app.com",
+    "url": "https://graphit-app.com"
+  },
+  "homepage": "https://graphit-app.com",
+  "repository": "https://github.com/graphit-app/graphit-cli",
+  "license": "UNLICENSED",
+  "keywords": [
+    "graphit",
+    "bi",
+    "dashboard",
+    "custom-dashboard",
+    "data-visualization",
+    "knowledge-base",
+    "sql",
+    "cli"
+  ]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "graphit",
+  "version": "0.1.3",
+  "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
+  "author": {
+    "name": "Graphit",
+    "email": "support@graphit-app.com",
+    "url": "https://graphit-app.com"
+  },
+  "homepage": "https://graphit-app.com",
+  "repository": "https://github.com/graphit-app/graphit-cli",
+  "keywords": [
+    "graphit",
+    "bi",
+    "dashboard",
+    "custom-dashboard",
+    "data-visualization",
+    "knowledge-base",
+    "sql",
+    "cli"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "type": "module",
   "bin": {
@@ -16,7 +16,9 @@
   },
   "files": [
     "dist",
-    "skill"
+    "skills",
+    ".claude-plugin",
+    ".codex-plugin"
   ],
   "keywords": [
     "graphit",

package/{skill → skills/graphit}/SKILL.md

@@ -4,13 +4,24 @@ 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
 
 Build custom HTML dashboards from real data using the Graphit CLI.
 
+## Session Start
+
+Run `graphit --version` at the start of every session to confirm the CLI is installed.
+If the output includes an "Update available" banner, tell the user to update before proceeding and explain that outdated versions may be missing commands or bug fixes.
+
+## Error Recovery
+
+When any `graphit` command fails with an unexpected error (unknown command, unrecognized flag, non-zero exit with unclear message), suggest `npm update -g @graphit/cli` before investigating further. Outdated CLI versions are the most common cause of unexpected errors.
+Do NOT suggest updating for normal operational failures (expired auth, bad SQL syntax, network timeout, entity not found).
+
 ## HARD CONSTRAINTS (violating these produces a broken dashboard)
 
 ### 1. ZERO external resources
@@ -21,8 +32,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 or inline SVG (preferred - crisp at any DPI in the iframe).
-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 +69,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,26 +146,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.
 
-**NEVER use `<canvas>`.** The dashboard renders in a sandboxed iframe where canvas `devicePixelRatio` handling breaks, producing blurry charts. Use SVG (`viewBox` scales perfectly at any DPI) or CSS-based techniques instead.
+**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.
 
-| Data shape | Chart | Inline technique |
-|---|---|---|
-| 1 temporal + 1 numeric | Line | SVG `<polyline>` with `viewBox` |
-| 1 categorical + 1 numeric | Bar | CSS width% divs |
-| Single number | KPI card | Styled div |
-| Part-whole (max 5) | Donut | SVG arc paths |
-| 2 numerics + optional size | Scatter / Bubble | SVG `<circle>` elements |
-| Matrix / cohort | Heatmap | CSS grid + opacity |
-| Stages | Funnel | CSS width% bars, narrowing |
-| Time sparkline | Sparkline | Inline SVG `<polyline>` |
-| Detail / raw data | Table | HTML table + hover rows |
+### Rendering
 
-**SVG tooltip pattern:** Add a shared tooltip `<div>` (position:fixed, pointer-events:none). Attach `mouseenter`/`mouseleave` on SVG `<g>` groups wrapping each data element. For line charts, overlay invisible `<rect>` columns per x-tick as hover targets, with a dashed vertical guide `<line>` toggled on hover.
+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.
 
-For more chart types (scatter, stacked bar, gauge, multi-series) see `references/chart-selection.md`.
-For inline implementations of each, see `references/chart-patterns.md`.
+The iframe also provides optional convenience helpers if you want quick standard charts:
+
+| 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>
+```
 
 ---
 
@@ -165,4 +220,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/skills/graphit/cursor/graphit-chart-patterns.mdc

@@ -0,0 +1,86 @@
+---
+alwaysApply: false
+description: "Graphit: Runtime chart types via graphit.chart() and hand-rolled patterns. All data from graphit.resolve()."
+globs: []
+---
+
+# Chart Patterns
+
+All chart types are available via `graphit.chart()`. All data comes from `graphit.resolve()` - never embed static data.
+
+**NEVER use `<canvas>`.** Canvas produces blurry charts inside the sandboxed iframe due to DPI scaling issues.
+
+## Runtime chart types
+
+### 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.
+
+### 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.
+
+### donut / pie
+SVG pie slices with center hole (58% of radius). Center shows formatted total. Legend below with color swatches.
+
+### 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`.
+
+### 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.
+
+### 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`).
+
+### 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()`:
+
+```html
+<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'; }
+```

package/skills/graphit/graphit.mdc

@@ -0,0 +1,117 @@
+---
+alwaysApply: false
+description: "Build Graphit HTML dashboards with KB-aware queries, entity wrapping, and cached data sources"
+globs: []
+---
+
+# Graphit CLI
+
+Build custom HTML dashboards from real data using the Graphit CLI.
+
+## HARD CONSTRAINTS (violating these produces a broken dashboard)
+
+### 1. ZERO external resources
+The dashboard renders in a sandboxed iframe with a strict CSP. External requests are BLOCKED.
+Your HTML must NEVER contain:
+- `<script src="...">` - no Chart.js, D3.js, Alpine.js, ANY external JS
+- `<link href="...">` - no Tailwind CDN, Google Fonts, ANY external CSS
+- `<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.
+
+### 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"
+     data-graphit-label="Revenue Trend"
+     data-graphit-kb="metric:REVENUE,dimension:REGION,table:ORDERS"
+     data-graphit-sql="SELECT region, SUM(revenue) FROM orders GROUP BY region">
+  <!-- chart/KPI/table content here -->
+</div>
+```
+
+| Attribute | Format | Example |
+|-----------|--------|---------|
+| `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-sql` | SQL query (HTML-encode `<>&"`) | `"SELECT ..."` |
+
+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.
+
+### 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:** 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.
+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.
+
+## 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 }
+```
+
+**Error handling:** Rejects on timeout (60s), bad SQL, or invalid data source ID. Wrap in try/catch.
+
+### 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.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`.
+
+### 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).

package/skills/graphit/references/chart-patterns.md

@@ -0,0 +1,80 @@
+# Chart Patterns
+
+All chart types are available via `graphit.chart()`. All data comes from `graphit.resolve()` - never embed static data.
+
+**NEVER use `<canvas>`.** Canvas produces blurry charts inside the sandboxed iframe due to DPI scaling issues.
+
+## Runtime chart types
+
+### 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.
+
+### 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.
+
+### donut / pie
+SVG pie slices with center hole (58% of radius). Center shows formatted total. Legend below with color swatches. Each slice is a wedge path from center.
+
+### 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`.
+
+### 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.
+
+### heatmap
+CSS grid. X = columns, Y = rows. Background intensity scales linearly (rgba teal, 0.08-0.98). Text flips white at >55% intensity. Headers auto-generated. Capped at 40x40.
+Config: `x` (column), `y` (row), `value` (intensity, falls back to `y`).
+
+### 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 with a manual HTML escape function before passing to `showTooltip()`:
+
+```html
+<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'; }
+```

package/dist/api/client.d.ts

@@ -1,16 +0,0 @@
-export interface ApiError {
-    status: number;
-    detail: string;
-    retry_after_seconds?: number;
-}
-declare class ApiClient {
-    request<T>(method: string, path: string, body?: unknown): Promise<T>;
-    postUnauthed<T>(path: string, body: unknown): Promise<T>;
-    get<T>(path: string): Promise<T>;
-    post<T>(path: string, body: unknown): Promise<T>;
-    put<T>(path: string, body: unknown): Promise<T>;
-    delete<T>(path: string): Promise<T>;
-    private _fetch;
-}
-export declare const apiClient: ApiClient;
-export {};

package/dist/api/client.js

@@ -1,67 +0,0 @@
-import { getValidIdToken } from "../auth/token.js";
-import { getApiBaseUrl } from "../config.js";
-const REQUEST_TIMEOUT_MS = 30_000;
-class ApiClient {
-    async request(method, path, body) {
-        const { id_token } = await getValidIdToken();
-        return this._fetch(method, path, body, {
-            Authorization: `Bearer ${id_token}`,
-        });
-    }
-    async postUnauthed(path, body) {
-        return this._fetch("POST", path, body);
-    }
-    async get(path) {
-        return this.request("GET", path);
-    }
-    async post(path, body) {
-        return this.request("POST", path, body);
-    }
-    async put(path, body) {
-        return this.request("PUT", path, body);
-    }
-    async delete(path) {
-        return this.request("DELETE", path);
-    }
-    async _fetch(method, path, body, extraHeaders) {
-        const url = `${getApiBaseUrl()}${path}`;
-        const headers = {
-            "Content-Type": "application/json",
-            "X-Graphit-Source": "cli",
-            ...extraHeaders,
-        };
-        const resp = await fetch(url, {
-            method,
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-        if (!resp.ok) {
-            let detail = `HTTP ${resp.status}`;
-            try {
-                const errBody = (await resp.json());
-                detail = errBody.detail || detail;
-                if (resp.status === 429) {
-                    const retryAfter = parseInt(resp.headers.get("Retry-After") || "60", 10);
-                    const err = {
-                        status: 429,
-                        detail,
-                        retry_after_seconds: retryAfter,
-                    };
-                    throw err;
-                }
-            }
-            catch (e) {
-                if (e.status === 429)
-                    throw e;
-            }
-            const err = { status: resp.status, detail };
-            throw err;
-        }
-        if (resp.status === 204)
-            return undefined;
-        return (await resp.json());
-    }
-}
-export const apiClient = new ApiClient();
-//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

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

package/dist/auth/credentials.d.ts

@@ -1,15 +0,0 @@
-export interface StoredCredentials {
-    refresh_token: string;
-    user_id: string;
-    email: string;
-    org_id: string;
-    org_name: string;
-    seat_type: string;
-    created_at: string;
-    id_token?: string;
-    id_token_expiry?: number;
-}
-export declare function getCredentialsPath(): string;
-export declare function readCredentials(): Promise<StoredCredentials | null>;
-export declare function writeCredentials(creds: StoredCredentials): Promise<void>;
-export declare function deleteCredentials(): Promise<void>;