@graphit/cli 0.1.0

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

@@ -0,0 +1,148 @@
+---
+alwaysApply: false
+description: "Graphit: Inline CSS/SVG/canvas implementations for dashboards. No external libraries - the iframe CSP blocks all external resources."
+globs: []
+---
+
+# Chart Patterns
+
+Inline CSS/SVG/canvas implementations for dashboards. No external libraries - the iframe CSP blocks all external resources.
+
+## 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>';
+});
+```
+
+## 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>';
+});
+```
+
+## 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;
+});
+```
+
+## 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"/>';
+```
+
+## 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"/>';
+});
+```
+
+## 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"/>';
+```
+
+## 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();
+```
+
+## 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>';
+});
+```
+
+## 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>';
+});
+```
+
+## 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>
+```
+Dynamic: set `background: conic-gradient(var(--graphit-accent) 0% ${pct}%, var(--graphit-surface-sunken) ${pct}% 100%)`.

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

@@ -0,0 +1,89 @@
+---
+alwaysApply: false
+description: "Graphit: Consult when choosing chart types for dashboard elements. Matches data shapes to the right visualization."
+globs: []
+---
+
+# Chart Selection
+
+Consult when choosing chart types for dashboard elements. Matches data shapes to the right visualization.
+
+## Dimension/Measure Defaults
+
+| Dimensions | Measures | Default chart |
+|---|---|---|
+| 1 temporal | 1+ | line |
+| 1 categorical | 1 | bar |
+| 1 categorical | 2+ | bar (grouped or dual axis) |
+| 2 categorical | 1 | bar with series on 2nd dim |
+| 0 | 1 | KPI card |
+| 1 categorical (50+ values) | 1 | table |
+
+When ambiguous, propose 2-3 options and ask the user. Do not guess.
+
+## Full Chart Type Table
+
+| Data shape | Chart type | Required columns |
+|---|---|---|
+| Time series | line | 1 temporal + 1 numeric |
+| Categories | bar | 1 categorical + 1 numeric |
+| Stacked areas | area | 1 temporal/categorical + 1 numeric |
+| Part-whole (max 5 slices) | pie | 1 categorical + 1 numeric |
+| Single metric | KPI card | 1 numeric |
+| Stages | funnel | 1 categorical + 1 numeric |
+| Target/progress | gauge | 1 numeric |
+| Matrix (unpivoted) | heatmap | 2 categorical + 1 numeric |
+| Hierarchy | treemap | 1 categorical + 1 numeric |
+| Flows | sankey | 2 categorical + 1 numeric |
+| Correlation | scatter | 2 numeric |
+| 3 variables | bubble | 3 numeric |
+| Countries | choropleth map | 1 categorical + 1 numeric |
+| Lat/lng | scatter map | 2 numeric (lat + lng) |
+| Detail/raw data | table | any columns |
+
+## Perception Ranking (Cleveland-McGill)
+
+Position > length > angle > area > color.
+
+| Goal | First choice | Never |
+|---|---|---|
+| Trend (8+ points) | line | bar, pie |
+| Trend (2-7 points) | bar (column) | line with dots |
+| Compare (12 or fewer categories) | sorted bar | pie, radar |
+| Compare (13-30 categories) | horizontal bar + top-N | column |
+| Part-to-whole | stacked bar, treemap | pie with 6+ |
+| Distribution | histogram, box | pie, line |
+| Correlation | scatter, bubble | dual-axis |
+| Ranking | sorted bar + min-N | pie, treemap |
+| Funnel | funnel + stage% | pie |
+| KPI vs target | big-number + sparkline | gauge (unbounded) |
+| 2D matrix / cohort | heatmap | bar with 100+ |
+
+## Cardinality Guards
+
+| Cardinality of categorical dim | Action |
+|---|---|
+| 1-5 | Show data labels, no rotation |
+| 6-20 | Default styling |
+| 21-50 | Rotate labels 45 deg, consider Top-N + Other |
+| 50+ | Use table chart or require a filter |
+
+COALESCE categorical dimensions in SQL (`COALESCE(region, 'Other')`) to prevent blank axis labels. For 21+ categories on a bar/line, use a "Top N + Other" window-function pattern:
+
+```sql
+WITH ranked AS (
+  SELECT *, ROW_NUMBER() OVER (ORDER BY metric DESC) AS rn
+  FROM data
+)
+SELECT CASE WHEN rn <= 10 THEN category ELSE 'Other' END AS category,
+       SUM(metric) AS metric
+FROM ranked GROUP BY 1 ORDER BY 2 DESC
+```
+
+## Hard Caps
+
+- Pie: max 5 slices (3 preferred)
+- Line series: max 5-7 (else use small multiples)
+- Stacked bar segments: max 4
+- Categorical colors: max 7 distinct
+- Sort by value DESC unless the axis is ordinal or temporal

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

@@ -0,0 +1,100 @@
+---
+alwaysApply: false
+description: "Graphit: Consult before building any multi-chart dashboard. Transforms vague requests into structured, cohesive dashboards."
+globs: []
+---
+
+# Dashboard Planning
+
+Consult before building any multi-chart dashboard. Transforms vague requests into structured, cohesive dashboards.
+
+## Frame the Question
+
+Every dashboard answers ONE primary question. Name the shape first:
+
+| Shape | Lead chart | Example question |
+|---|---|---|
+| Trend | line/area | "How is revenue changing?" |
+| Comparison | sorted bar | "Revenue by segment?" |
+| Ranking | sorted bar + top-N | "Top 10 customers?" |
+| Composition | stacked bar/treemap | "Revenue share by product?" |
+| Distribution | histogram | "Spread of order values?" |
+| Correlation | scatter | "Spend vs conversion?" |
+| Funnel | funnel + stage% | "Signup-to-purchase conversion?" |
+| Cohort | heatmap/overlay lines | "D1/D7/D30 retention?" |
+| Deviation | diverging bar | "Budget vs actual variance?" |
+
+Compound intent ("what and why") - sequence trend then root-cause as two charts.
+
+## Pick the Archetype
+
+| Audience | Archetype | KPIs | Charts | Interactivity |
+|---|---|---|---|---|
+| Exec / "are we on track" | Strategic | 4-6 hero | 5-9 | Low |
+| Analyst / "why is X" | Analytical | 3-5 | 6-12 + detail | High |
+| Ops / "what's broken now" | Operational | 8-16 dense | 6-12 | Medium |
+
+Never mix archetypes on a single page.
+
+## Mandatory Rules
+
+- **Time-series**: if data has a date column, include at least 1 line/area trend. A dashboard without a trend is a snapshot - it cannot answer "is it improving?"
+- **Cohort**: if data has install/signup date + retention/LTV, add cohort curves (D0/D3/D7/D30). Period-over-period is NOT a substitute.
+- **Diversity**: 4+ charts must use 3+ distinct chart types. All-bar or all-line wastes the visual encoding.
+- **KPI-first**: lead with 1-3 KPI cards before detail charts unless the user says otherwise.
+- **Distribution over averages**: heavy-tailed metrics (spend, session length, deal size) need percentile bands or tier breakdowns. Median + p90, never bare mean.
+- **Insight titles**: state the takeaway ("Revenue grew 23% Q3"), not the metric name.
+- **Reference lines**: goal-oriented metrics carry target/prior-period/benchmark lines. KPI cards need delta + comparison label.
+
+## Metric Contract
+
+Every KPI or measure needs all 6 properties:
+
+1. **Definition** - what counts, what's excluded (bots, refunds, internal)
+2. **Grain** - per-user-per-day, per-cohort, per-org-per-month
+3. **Window** - rolling 7d/28d, MTD/QTD/YTD, cohort-anchored
+4. **Population** - all users, payers, certified, segment
+5. **Baseline** - vs prior period / target / cohort avg / benchmark
+6. **Direction** - up=good or up=bad (drives color meaning)
+
+Pair lagging + leading: revenue (lagging) needs retention (leading). Replace vanity cumulative counts ("total signups") with cohort/period rates. Never show AVG of a rate column - rates must be weighted. Show denominators on rates (or hide when N < 30).
+
+## Anti-Patterns to Block
+
+- Pie with 6+ slices (max 5, prefer 3)
+- 3D charts of any kind
+- Dual Y-axis without clear justification (use small multiples)
+- Truncated bar baselines (always start at 0)
+- Stacked bar with 5+ segments
+- Gauge for unbounded KPIs (use bullet chart)
+- Rainbow palette on ordinal data
+- Red-green without shape encoding (accessibility)
+- Aggregate-only without segment drill-down (Simpson's paradox)
+- Rate without denominator visible
+- KPI without baseline comparison
+- Vanity cumulative counts ("total signups since launch")
+
+## Asking Good Questions
+
+Purpose before data. The first response should mirror the user's intent and ask ONE narrowing question - never start querying immediately.
+
+**Batch related questions** - ask multiple things at once instead of sequential single questions. Each option should lead to a different path, not variations of the same thing.
+
+**Use open questions for exploration** - "What business decision will this dashboard support?" beats presenting a restrictive multiple-choice.
+
+**Clarification triggers:**
+- User says "revenue" - ask: bookings, ARR, or GAAP recognized?
+- User says "conversion" - ask: what's the start and end event?
+- User says "active users" - ask: what defines active? (logged in? performed action? within what window?)
+- User mentions MQL/SQL - ask: how does your org define the handoff? (Same column can mean 13% or 40%)
+
+## Pre-Build Checklist
+
+Before generating the HTML:
+- [ ] Question shape stated (trend, comparison, funnel, etc.)
+- [ ] Archetype + audience identified
+- [ ] Time-series present if date column exists
+- [ ] Cohort view present if install/signup + retention data
+- [ ] 3+ chart types for 4+ graphs
+- [ ] Every KPI has definition + baseline + direction
+- [ ] No anti-patterns present

package/skill/cursor/graphit-domain-lenses.mdc

@@ -0,0 +1,120 @@
+---
+alwaysApply: false
+description: "Graphit: Consult when the user's data signals match a specific business domain. Each lens provides domain-specific metrics, chart types, and anti-patterns that make dashboards feel expert-built."
+globs: []
+---
+
+# Domain Lenses
+
+Consult when the user's data signals match a specific business domain. Each lens provides domain-specific metrics, chart types, and anti-patterns that make dashboards feel expert-built.
+
+Detect the domain from column names and user intent. Apply universal planning rules first (see dashboard-planning.md), then layer domain-specific patterns.
+
+---
+
+## Marketing & Attribution
+
+**Signals:** utm_*, channel, creative_id, spend, cpi, impressions, clicks, roas, cac, ltv, attribution_*, skan_*, conversions, ctr.
+
+**Key metrics:**
+
+| Metric | Formula pattern | Chart |
+|---|---|---|
+| Blended CAC / Paid CAC | spend / new_customers | bar/KPI, target + YoY |
+| ROAS D7/D30/D90 | revenue_D0-N / spend | cumulative cohort line + 100% breakeven |
+| MER | revenue / marketing_spend | KPI |
+| LTV:CAC Ratio | LTV / CAC | bar, floor 3:1 |
+| Payback Period | days to recoup CAC | cumulative line |
+
+**Must-have charts:** Cumulative cohort ROAS curve with 100% breakeven line. Channel-mix sorted bar (never pie for 6+). Creative scorecard table. Attribution model comparison stacked bar.
+
+**Anti-patterns:** Mismatched attribution windows across channels (7d vs 30d = 30% artifact). ROAS without payback context. Summing self-reported channel conversions without dedup (totals 110-180%). Spend without incrementality context. Creative table without refresh ratio.
+
+**Clarify first:** Attribution model + window? ROAS gross or margin-adjusted?
+
+---
+
+## Financial / Executive
+
+**Signals:** revenue, mrr, arr, cogs, gross_margin, opex, ebitda, budget, forecast, actual, variance, runway, burn, cash_balance, gl_account.
+
+**Key metrics:**
+
+| Metric | Formula pattern | Chart |
+|---|---|---|
+| P&L Cascade | Rev->COGS->GP->Opex->EBITDA->Net | waterfall |
+| Variance $/% | Actual-Plan, sign-aware per line type | semantic-color bar |
+| GM% by segment | (Rev-COGS)/Rev per product/cohort | line + small multiples |
+| Burn Multiple | net_burn / net_new_ARR | KPI + trend |
+| Runway Months | Cash / abs(Net Burn) | KPI color-banded |
+| Rule of 40 | Growth% + EBITDA margin% | KPI + trend |
+
+**Must-have charts:** Waterfall (P&L, variance bridge, ARR bridge). Bullet chart for KPI vs target. Plan vs Forecast vs Actual (3 series, never 2). Variance bars with semantic color (green=favorable, red=unfavorable regardless of direction).
+
+**Anti-patterns:** Direction-based green/red instead of favorable/unfavorable. Blended GM hiding AI inference cost compression. YTD comparison in Jan/Dec (use TTM). Cash burn without runway. Revenue without ASC 606 distinction. "Three-line" missing Forecast (Plan vs Actual vs Forecast = 3).
+
+**Clarify first:** Revenue = bookings, ARR, or GAAP recognized?
+
+---
+
+## Product / Growth
+
+**Signals:** install_date, signup_at, cohort_*, retention_d*, dau, mau, activation_*, payer_*, funnel_step, session_*, ltv, arpu, arpdau.
+
+**Key metrics:**
+
+| Metric | Formula pattern | Chart |
+|---|---|---|
+| D1/D7/D30 Retention | active_dN / cohort_size | heatmap or overlay |
+| Stickiness | DAU/MAU | line + ref bands |
+| ARPDAU | revenue_day / DAU_day | line + 7d MA |
+| Payer Conversion D7 | first_payers_d7 / cohort | cumulative line |
+| Whale Share | sum(rev) top-X% / total_rev | Lorenz / decile bar |
+| Activation Rate | reached_aha / signups | cohort heatmap |
+
+**Must-have charts:** Cohort retention heatmap (X=days since signup, Y=cohort, color=retention%). Cumulative cohort overlay (max 6 series). Lorenz/decile bar for revenue concentration. FTUE funnel with per-cohort drift.
+
+**Anti-patterns:** Period retention instead of cohort retention. Bare ARPU without distribution (whales break every mean). Mean on heavy-tailed metrics (use median + p90). LTV without cohort horizon day. Vanity cumulative tiles.
+
+---
+
+## Operational Monitoring
+
+**Signals:** latency, p50/p95/p99, error_rate, slo, uptime, mttr, throughput, oee, cycle_time, otif, fill_rate, stockout, deployment_frequency.
+
+**Key metrics:**
+
+| Metric | Formula pattern | Chart |
+|---|---|---|
+| Latency p50/p95/p99 | percentile buckets | multi-percentile line + SLO |
+| Error Budget | 100% - (errors/total) rolling 28d | bullet chart |
+| DORA Quartet | deploy freq, lead time, CFR, recovery | 4-tile KPI |
+| OEE | Availability x Performance x Quality | KPI + 3-tile decomp |
+| OTIF | on-time AND in-full | trend + decomp stacked bar |
+
+**Must-have charts:** Multi-percentile line + SLO threshold band. Bullet chart (not gauge). Latency heatmap. Error sources Pareto.
+
+**Anti-patterns:** Averages without percentiles. KPI without threshold band. Vanity uptime % (use error-budget framing). Aggregating across segments (global 0.4% hides a region at 8%).
+
+---
+
+## Sales / Pipeline
+
+**Signals:** opp_id, stage, amount, close_date, forecast_category, mql, sql, arr, acv, tcv, quota, attainment, loss_reason, expansion_arr.
+
+**Key metrics:**
+
+| Metric | Formula pattern | Chart |
+|---|---|---|
+| Pipeline Coverage | open_pipe / quota_remaining | KPI, target=1/win_rate |
+| Sales Velocity | (opps x win_rate x avg_acv) / cycle_days | KPI + trend |
+| Win Rate by ACV | won / (won+lost) per band | sorted bar, min-N 30 |
+| Quota Attainment | closed_won / quota | histogram (bimodal!) |
+| Net New ARR | new + expansion - contraction - churn | waterfall |
+| Forecast MAPE | mean(abs(actual-forecast)/actual) | line + target |
+
+**Must-have charts:** Net New ARR waterfall (start + new + expansion - contraction - churn = end). Forecast convergence curve (13 weeks). Coverage curve by quarter-week. Win rate by ACV band.
+
+**Anti-patterns:** Fixed 3x coverage instead of 1/win_rate per segment. ACV/ARR/TCV/bookings conflated. Quota attainment as bare mean (bimodal - use histogram). Stage-weighted pipe using CRM defaults (30-50% overstate). "No decision" lumped (40-60% of B2B - split it).
+
+**Clarify first:** MQL/SQL definitions (same column = 13-40% conversion depending on org). Revenue = bookings vs ARR vs GAAP. Coverage target: derive from historical win rate per segment, not fixed multiple.

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

@@ -0,0 +1,75 @@
+---
+alwaysApply: false
+description: "Graphit: Consult when starting a dashboard build. The Knowledge Base contains reusable metrics, dimensions, rules, and table schemas that ensure consistent formulas across dashboards."
+globs: []
+---
+
+# KB Exploration
+
+Consult when starting a dashboard build. The Knowledge Base contains reusable metrics, dimensions, rules, and table schemas that ensure consistent formulas across dashboards.
+
+## KB-First Discovery
+
+Before writing raw SQL with inline aggregations or column references:
+
+1. List what exists: `graphit kb list metrics`, `graphit kb list dimensions`, `graphit kb list rules`
+2. If a KB metric matches the user's request, use its formula: `graphit kb get metric REVENUE`
+3. If no match exists, consider whether to build the dashboard from raw columns or suggest KB asset creation first
+4. Explore relationships: `graphit kb explore metric REVENUE` shows which tables and dimensions connect to a metric
+
+KB assets ensure consistent formulas across dashboards. If 3 charts all need `SUM(ORDERS.AMOUNT)`, one TOTAL_REVENUE metric is better than 3 inline aggregations.
+
+## Metric vs Dimension
+
+| Property | Metric | Dimension |
+|---|---|---|
+| Formula | Aggregation required (SUM, COUNT, AVG, MIN, MAX) | Row-level only (no aggregates) |
+| Table scope | Can reference multiple tables | Exactly one table |
+| Purpose | Measures - what you count/sum | Grouping axes - how you slice |
+| Example | `SUM(ORDERS.AMOUNT)` | `DATE_TRUNC('month', EVENTS.EVENT_TS)` |
+| Invalid | `ORDERS.AMOUNT` (no aggregate) | `SUM(EVENTS.DURATION)` (has aggregate) |
+
+## Naming Conventions
+
+All KB assets use UPPER_SNAKE_CASE. The names are auto-sanitized:
+
+| Pattern | Example | Use when |
+|---|---|---|
+| `TOTAL_*` | `TOTAL_REVENUE`, `TOTAL_ORDERS` | Sum aggregations |
+| `AVG_*` | `AVG_ORDER_VALUE` | Average metrics |
+| `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
+| `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios/percentages |
+
+## Reuse Over Reinvention
+
+When building multi-chart dashboards, identify shared concepts:
+- If 3 charts use `SUM(ORDERS.AMOUNT)`, reference one TOTAL_REVENUE metric
+- If 2 charts group by `DATE_TRUNC('month', TS)`, reference one MONTHLY dimension
+- Discover existing assets: `graphit kb search "revenue"`
+
+## When to Suggest KB Asset Creation
+
+| Signal | Propose |
+|---|---|
+| User requests a business metric with no KB match | Metric - reusable formula |
+| User groups by a derived expression | Dimension - consistent grouping |
+| User describes a business rule ("active = logged in within 30d") | Rule - applied to future queries |
+| User uses a business term not in KB | Synonym - maps colloquial to defined |
+
+## Formula Syntax
+
+Metrics require `TABLE.COLUMN` references with UPPERCASE naming:
+
+```sql
+-- Valid metric formulas
+SUM(ORDERS.AMOUNT)
+COUNT(DISTINCT EVENTS.USER_ID) WHERE EVENTS.EVENT_TS >= DATEADD(day, -30, CURRENT_DATE)
+SUM(ORDERS.REVENUE) / NULLIF(SUM(ORDERS.COST), 0)
+
+-- Valid dimension formulas (no aggregates)
+EVENTS.PLATFORM
+DATE_TRUNC('month', EVENTS.EVENT_TS)
+CASE WHEN USERS.AGE >= 18 THEN 'adult' ELSE 'minor' END
+```
+
+Conditionals use CASE WHEN (not FILTER WHERE - Snowflake doesn't support it). Always guard division with NULLIF.

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

@@ -0,0 +1,127 @@
+---
+alwaysApply: false
+description: "Graphit: Consult when writing queries. Data source queries (`graphit query --ds`) run DuckDB. Warehouse queries (`graphit query --warehouse`) run Snowflake. You MUST use the correct dialect."
+globs: []
+---
+
+# SQL Reference
+
+Consult when writing queries. Data source queries (`graphit query --ds`) run DuckDB. Warehouse queries (`graphit query --warehouse`) run Snowflake. You MUST use the correct dialect.
+
+## DuckDB vs Snowflake Translation
+
+| Snowflake | DuckDB equivalent |
+|---|---|
+| `DATEADD(day, N, date)` | `date + INTERVAL N DAY` |
+| `DATEDIFF(day, a, b)` | `DATE_DIFF('day', a, b)` |
+| `NVL(a, b)` | `COALESCE(a, b)` |
+| `NVL2(a, b, c)` | `CASE WHEN a IS NOT NULL THEN b ELSE c END` |
+| `IFF(cond, a, b)` | `CASE WHEN cond THEN a ELSE b END` |
+| `TO_CHAR(date, fmt)` | `strftime(date, fmt)` |
+| `ARRAY_AGG(x) WITHIN GROUP (ORDER BY y)` | `LIST(x ORDER BY y)` |
+| `LISTAGG(col, sep)` | `STRING_AGG(col, sep ORDER BY ...)` |
+| `COUNT_IF(cond)` | `COUNT(*) FILTER (WHERE cond)` |
+| `GENERATOR(ROWCOUNT => N)` | `generate_series(0, N-1)` |
+| `CONVERT_TIMEZONE('tz', ts)` | `timezone('tz', ts)` |
+
+### JSON / VARIANT Access
+
+| Engine | Syntax | Example |
+|---|---|---|
+| Snowflake | Colon notation | `col:field::STRING`, `col:parent:child::NUMBER` |
+| DuckDB | Arrow operators | `col->>'field'` (text), `col->'field'` (JSON) |
+
+NEVER use `->>`  in Snowflake or `:field::STRING` in DuckDB.
+
+### Timezone
+
+| Engine | Correct | Wrong |
+|---|---|---|
+| DuckDB | `timezone('Asia/Jerusalem', ts_col)` | `AT TIME ZONE` chains (reverses direction on TIMESTAMPTZ) |
+| Snowflake | `CONVERT_TIMEZONE('Asia/Jerusalem', ts_col)` (2-arg for _TZ) | `AT TIME ZONE` |
+
+## DuckDB Superpowers (not in Snowflake)
+
+| Feature | Example |
+|---|---|
+| `GROUP BY ALL` | `SELECT region, SUM(sales) FROM t GROUP BY ALL` |
+| `SELECT * EXCLUDE` | `SELECT * EXCLUDE (internal_id) FROM t` |
+| `FILTER (WHERE)` | `COUNT(*) FILTER (WHERE status='active')` |
+| `UNION BY NAME` | `SELECT ... UNION ALL BY NAME SELECT ...` |
+
+## Snowflake Notes
+
+- Use `DATE_TRUNC('month', date)` for grouping (not EXTRACT/MONTH/YEAR)
+- Snowflake does NOT support `FILTER (WHERE)` - use `CASE WHEN` instead
+- `COUNT_IF` MUST receive a boolean expression, not a raw INT column. Use `COUNT_IF(is_active = 1)`, not `COUNT_IF(is_active)`
+- String matching: prefer `ILIKE` (case-insensitive) over `LIKE`
+
+## SQL Formatting Standards (Both Engines)
+
+- Keywords UPPERCASE: `SELECT`, `FROM`, `WHERE`, `JOIN`, `GROUP BY`, `ORDER BY`
+- Table/column names UPPERCASE: `ORDERS`, `CUSTOMER_ID`, `TOTAL_REVENUE`
+- Qualify every column with its table alias: `o.ORDER_DATE`, not bare `ORDER_DATE`
+- Use descriptive aliases: `total_revenue`, not `sum1`
+- String literals in single quotes: `'active'`, `'2024-01-01'`
+- Non-ASCII identifiers MUST be double-quoted: `SELECT * FROM "hebrew_table"`
+
+## CTE Pattern
+
+Use CTEs for queries with 3+ JOINs or complex subqueries:
+
+```sql
+WITH MONTHLY_ORDERS AS (
+  SELECT o.CUSTOMER_ID, DATE_TRUNC('month', o.ORDER_DATE) AS MONTH,
+         SUM(o.AMOUNT) AS MONTHLY_REVENUE
+  FROM ORDERS o WHERE o.STATUS = 'complete'
+  GROUP BY o.CUSTOMER_ID, DATE_TRUNC('month', o.ORDER_DATE)
+)
+SELECT c.SEGMENT, AVG(mo.MONTHLY_REVENUE) AS AVG_MONTHLY_REVENUE
+FROM MONTHLY_ORDERS mo JOIN CUSTOMERS c ON mo.CUSTOMER_ID = c.ID
+GROUP BY c.SEGMENT ORDER BY AVG_MONTHLY_REVENUE DESC
+```
+
+## ORDER BY Rules (Always Include)
+
+| Query type | ORDER BY |
+|---|---|
+| Time series | `ORDER BY date_column ASC` |
+| Category breakdowns | `ORDER BY metric_column DESC` |
+| Rankings / top N | `ORDER BY metric_column DESC LIMIT N` |
+
+Do NOT add LIMIT unless the user requests it or the query is a ranking.
+
+## Gap-Filling Pattern (DuckDB)
+
+For heatmaps or continuous time-series needing every cell (even zeros):
+
+```sql
+WITH grid AS (
+  SELECT UNNEST(generate_series(0, 23)) AS hour_of_day
+)
+SELECT g.hour_of_day, COALESCE(t.count, 0) AS count
+FROM grid g
+LEFT JOIN (SELECT hour, COUNT(*) AS count FROM data_source GROUP BY 1) t
+  ON g.hour_of_day = t.hour
+ORDER BY 1
+```
+
+Date series:
+```sql
+SELECT UNNEST(generate_series(
+  CURRENT_DATE - INTERVAL 30 DAY, CURRENT_DATE, INTERVAL 1 DAY
+))::DATE AS date
+```
+
+## Subquery Column Scope
+
+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.
+
+## Data Source Routing
+
+| Situation | Command | Speed |
+|---|---|---|
+| Table has a cached data source | `graphit query "SQL" --ds <id>` | ~100ms, DuckDB |
+| 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.