@graphit/cli 0.1.49 → 0.1.51

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Graphit CLI plugin for AI coding assistants",
-    "version": "0.1.49"
+    "version": "0.1.51"
   },
   "plugins": [
     {
@@ -16,9 +16,9 @@
       "source": {
         "source": "npm",
         "package": "@graphit/cli",
-        "version": "0.1.49"
+        "version": "0.1.51"
       },
-      "version": "0.1.49",
+      "version": "0.1.51",
       "category": "data-visualization",
       "tags": [
         "bi",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/package.json

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

package/skills/graphit/SKILL.md

@@ -1,5 +1,5 @@
 ---
-skill_version: "0.1.49"
+skill_version: "0.1.51"
 name: graphit
 description: >
   Build HTML dashboards with Graphit. KB-aware queries, entity wrapping, cached data sources.
@@ -415,7 +415,7 @@ The iframe also provides optional convenience helpers if you want quick standard
 | Helper | Usage |
 |---|---|
 | `graphit.chart(el, {type, data, x, y, ...})` | Bar, line, area, donut, scatter, stacked-bar, heatmap, funnel, gauge, sparkline |
-| `graphit.table(el, {data, columns?, maxRows?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects), defaults to `Object.keys(data[0])` |
+| `graphit.table(el, {data, columns?, maxRows?, columnFormats?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects), defaults to `Object.keys(data[0])`. `columnFormats` maps column name -> `"currency"`/`"percent"`/`"number"` for per-column number formatting (same formats and no-scaling percent rule as chart `valueFormat`); unlisted columns render raw |
 | `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` |
 | `graphit.filter(id, {label, field?, default?})` | Headless filter registration (renders nothing). Returns handle: `{get, set, subscribe}`. See `filters.md` |
@@ -432,6 +432,8 @@ These are shortcuts, not requirements. Use them when a standard chart is all you
 
 `graphit.kpi` config: `value`, `label`, `format` (`"currency"` | `"percent"` | `"number"`), `compareValue`, `compareLabel`.
 
+**Percent does NOT scale.** `"percent"` only appends a `%` sign - it does not multiply by 100. A 0-1 ratio (retention, conversion, share, churn) renders as `0.42%`, not `42%`. Multiply ratios by 100 in SQL so the value is already 0-100, e.g. `SUM(retained) * 100.0 / NULLIF(SUM(cohort), 0) AS retention_pct` charted with `valueFormat: "percent"` -> "42%". Charts use `valueFormat`; `kpi`/`gauge`/`filter` use `format`.
+
 ### Canonical pattern - entity with live data
 
 ```html

package/skills/graphit/VERSION.json

@@ -1,5 +1,5 @@
 {
   "package": "@graphit/cli",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "source": "cli/package.json"
 }

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

@@ -47,6 +47,9 @@ Config: `value`, `min` (default 0), `max` (default 100), `format`, `label`, `col
 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`.
 
+## Value formatting
+`valueFormat` (charts), `format` (`kpi`/`gauge`), and `columnFormats` (`graphit.table`, mapping column name -> format) all take `"currency"`, `"percent"`, or `"number"`. **`"percent"` only appends `%` - it does NOT multiply by 100.** A 0-1 ratio renders as `0.42%`, not `42%`; multiply ratios/rates by 100 in SQL (`* 100.0 ... AS x_pct`) so the value is already 0-100. Table columns without a `columnFormats` entry render raw.
+
 ## Color tokens
 
 | Token | Usage |

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

@@ -39,6 +39,8 @@ All KB assets use UPPER_SNAKE_CASE. The names are auto-sanitized:
 | `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
 | `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios/percentages |
 
+> `*_RATE`/ratio columns are usually 0-1 fractions. To chart them as a percent, multiply by 100 in SQL (`* 100.0`) - `"percent"` format appends `%` without scaling.
+
 ## When to Suggest KB Asset Creation
 
 | Signal | Propose |

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

@@ -133,7 +133,7 @@ Canvas `graphit.resolve()` queries that follow these shapes serve from a semanti
 **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
+- Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves. To display as a percent, multiply by 100 (`* 100.0 ... AS x_pct`): the `"percent"` format only appends `%`, it does not scale (a 0-1 ratio would show as `0.42%`, not `42%`).
 - `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)
 

package/skills/graphit/graphit.mdc

@@ -1,5 +1,5 @@
 ---
-skill_version: "0.1.49"
+skill_version: "0.1.51"
 alwaysApply: false
 description: "Build Graphit HTML dashboards with KB-aware queries, entity wrapping, and cached data sources"
 globs: []
@@ -305,7 +305,7 @@ Add the overlay inside EVERY element you pass as `target:` - and ONLY those elem
 | Helper | Usage |
 |---|---|
 | `graphit.chart(el, {type, data, x, y, ...})` | Bar, horizontal-bar, line, area, donut, scatter, stacked-bar, heatmap, funnel, gauge, sparkline |
-| `graphit.table(el, {data, columns?, maxRows?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects) |
+| `graphit.table(el, {data, columns?, maxRows?, columnFormats?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects). `columnFormats` maps column name -> `"currency"`/`"percent"`/`"number"` (same formats and no-scaling percent rule as chart `valueFormat`); unlisted columns render raw |
 | `graphit.kpi(el, {value, label?, format?})` | KPI card with optional delta (`compareValue`, `compareLabel`) |
 | `graphit.presentation(el)` | Full-screen slide deck. Returns builder: `.slide({bg, layout, html})` then `.start()`. See graphit-presentations rule. |
 | `graphit.filter(id, {label, field?, default?})` | Headless filter (zero DOM). Returns `{get, set, subscribe}` handle. See graphit-filters rule. |
@@ -318,6 +318,8 @@ Add the overlay inside EVERY element you pass as `target:` - and ONLY those elem
 
 `graphit.chart` types: `"bar"`, `"horizontal-bar"` (alias `"hbar"`), `"line"`, `"area"`, `"donut"` (alias `"pie"`), `"scatter"` (alias `"bubble"`), `"stacked-bar"` (alias `"stacked"`), `"heatmap"`, `"funnel"`, `"gauge"`, `"sparkline"`. Config: `x`, `y`, `series`, `title`, `height` (140-900px), `valueFormat` (`"currency"` | `"percent"` | `"number"`), `colors`. Dual axis (bar/line/area): `y2`, `y2Format`, `y2Label`; `y2` and `series` are mutually exclusive. Scatter adds: `size`, `label`. Gauge: `min`, `max`, `format`. Sparkline: `width`, `showValue`.
 
+**Percent does NOT scale.** `"percent"` only appends `%` - it does not multiply by 100. A 0-1 ratio (retention, conversion, share, churn) renders as `0.42%`, not `42%`. Multiply ratios by 100 in SQL (`SUM(retained) * 100.0 / NULLIF(SUM(cohort), 0) AS retention_pct`) then use `valueFormat: "percent"`. Charts use `valueFormat`; `kpi`/`gauge`/`filter` use `format`.
+
 ### Canonical pattern - entity with live data
 
 ```html

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

@@ -44,6 +44,9 @@ Config: `value`, `min` (default 0), `max` (default 100), `format`, `label`, `col
 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`.
 
+## Value formatting
+`valueFormat` (charts), `format` (`kpi`/`gauge`), and `columnFormats` (`graphit.table`, mapping column name -> format) all take `"currency"`, `"percent"`, or `"number"`. **`"percent"` only appends `%` - it does NOT multiply by 100.** A 0-1 ratio renders as `0.42%`, not `42%`; multiply ratios/rates by 100 in SQL (`* 100.0 ... AS x_pct`) so the value is already 0-100. Table columns without a `columnFormats` entry render raw.
+
 ## Saved templates
 
 Templates are reusable chart components saved to the org's KB. At dashboard load, the SDK fetches the org's template bundle and registers them alongside built-in types.

package/skills/graphit/references/kb-discovery.md

@@ -46,6 +46,8 @@ All KB assets are UPPER_SNAKE_CASE (auto-sanitized on write):
 | `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
 | `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios / percentages |
 
+> `*_RATE`/ratio columns are usually 0-1 fractions. To chart them as a percent, multiply by 100 in SQL (`* 100.0`) - `"percent"` format appends `%` without scaling.
+
 ## Formula Syntax
 
 Metrics reference `TABLE.COLUMN` with UPPERCASE naming:

package/skills/graphit/references/sql-reference.md

@@ -127,7 +127,7 @@ Canvas `graphit.resolve()` queries that follow these shapes serve from a semanti
 **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
+- Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves. To display as a percent, multiply by 100 (`* 100.0 ... AS x_pct`): the `"percent"` format only appends `%`, it does not scale (a 0-1 ratio would show as `0.42%`, not `42%`).
 - `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)