@graphit/cli 0.1.0

package/skill/cursor/graphit-style.mdc

@@ -0,0 +1,123 @@
+---
+alwaysApply: false
+description: "Graphit: Consult when building the HTML dashboard. Covers design principles, the Graphit aesthetic, typography, color system, layout patterns, and all inline chart implementations."
+globs: []
+---
+
+# Graphit Visual Style
+
+Consult when building the HTML dashboard. Covers design principles, the Graphit aesthetic, typography, color system, layout patterns, and all inline chart implementations.
+
+## Design Principles
+
+Graphit dashboards are clean, minimal, and data-forward:
+- **Card on themed surface** - content cards on `var(--graphit-surface)` background
+- **Generous whitespace** - 24px page padding, 16px card gaps, 24px card padding
+- **Subtle depth** - `box-shadow: 0 1px 3px rgba(0,0,0,0.08)`, not heavy borders
+- **Uppercase micro-labels** - 12px, 600 weight, `var(--graphit-fg-subtle)`, letter-spacing 0.05em for section headers
+- **Data is hero** - numbers are large and bold; chrome is minimal and muted
+- **Responsive** - grids collapse at 900px breakpoint
+
+## Color Tokens
+
+NEVER use hardcoded hex colors. Use CSS custom properties that automatically adapt to light/dark theme:
+
+| Token | Usage |
+|---|---|
+| `var(--graphit-surface)` | Page background |
+| `var(--graphit-surface-raised)` | Cards, panels |
+| `var(--graphit-surface-sunken)` | Inset areas, wells |
+| `var(--graphit-fg)` | Primary text |
+| `var(--graphit-fg-muted)` | Secondary text |
+| `var(--graphit-fg-subtle)` | Tertiary text, placeholders, labels |
+| `var(--graphit-border)` | Default borders |
+| `var(--graphit-border-strong)` | Emphasized borders |
+| `var(--graphit-accent)` | Brand teal, primary action color |
+| `var(--graphit-error)` | Error/danger text |
+| `var(--graphit-success)` | Success indicators |
+| `var(--graphit-warning)` | Warning indicators |
+| `var(--graphit-highlight)` | Highlighted/selected backgrounds |
+
+### Semantic Colors
+- **Positive / good:** `var(--graphit-accent)` (teal) or `var(--graphit-success)`
+- **Warning:** `var(--graphit-warning)`
+- **Danger / bad:** `var(--graphit-error)`
+
+### Multi-Series
+Use `var(--graphit-accent)` as the primary series. For additional series, choose muted complementary colors that work on both light and dark backgrounds.
+
+### Usage Rules
+- Accent teal for primary bars, lines, and positive indicators
+- Assign series colors consistently across charts sharing a dimension
+- Financial variance: green = favorable, red = unfavorable (regardless of sign direction)
+
+## Typography Scale
+
+Use the system font stack everywhere: `-apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif`
+
+| Element | Size | Weight | Color | Use |
+|---|---|---|---|---|
+| KPI number | 32px | 700 | `var(--graphit-fg)` | Primary metric value |
+| Card title / section header | 12px | 600 | `var(--graphit-fg-subtle)` | Uppercase, letter-spaced |
+| Body text / table cells | 14px | 400 | `var(--graphit-fg)` | Default content |
+| Labels / subtitles | 13px | 500 | `var(--graphit-fg-subtle)` | Supporting text |
+| Badges / deltas | 12px | 700 | contextual | Change indicators |
+| Chart axis labels | 11px | 400 | `var(--graphit-fg-subtle)` | Axis ticks |
+
+## Layout Patterns
+
+### Page Structure
+```html
+<style>
+  * { margin:0; padding:0; box-sizing:border-box; }
+  body { font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',system-ui,sans-serif;
+         background:var(--graphit-surface); color:var(--graphit-fg); padding:24px; }
+  .kpi-grid { display:grid; grid-template-columns:repeat(4,1fr); gap:16px; margin-bottom:24px; }
+  .charts-grid { display:grid; grid-template-columns:1fr 1fr; gap:16px; margin-bottom:24px; }
+  .full-width { grid-column:1/-1; }
+  .card { background:var(--graphit-surface-raised); border-radius:12px; padding:24px;
+          box-shadow:0 1px 3px rgba(0,0,0,0.08); }
+  .card h3 { font-size:12px; font-weight:600; color:var(--graphit-fg-subtle); text-transform:uppercase;
+             letter-spacing:0.05em; margin-bottom:16px; }
+  @media(max-width:900px) {
+    .kpi-grid { grid-template-columns:repeat(2,1fr); }
+    .charts-grid { grid-template-columns:1fr; }
+  }
+</style>
+```
+
+### Dashboard Composition (top to bottom)
+1. **Title row** - dashboard name, optional subtitle with date range
+2. **KPI row** - 3-4 cards in a grid. Each: big number, label, delta badge
+3. **Primary charts** - 2-column grid of detail visualizations
+4. **Detail table** - full-width card at bottom for raw data exploration
+
+### KPI Card
+```html
+<div class="card">
+  <div style="font-size:32px;font-weight:700;line-height:1.2">$144,661</div>
+  <div style="font-size:13px;color:var(--graphit-fg-subtle);margin-top:4px">Total Ad Spend</div>
+  <div style="font-size:12px;margin-top:8px;font-weight:600;color:var(--graphit-accent)">+12% vs prior</div>
+</div>
+```
+
+### Data Table
+```html
+<style>
+  table { width:100%; border-collapse:collapse; }
+  th { text-align:left; font-size:12px; font-weight:600; color:var(--graphit-fg-subtle); text-transform:uppercase;
+       letter-spacing:0.05em; padding:10px 16px; border-bottom:2px solid var(--graphit-border); }
+  th:not(:first-child) { text-align:right; }
+  td { padding:12px 16px; font-size:14px; border-bottom:1px solid var(--graphit-border); }
+  td:not(:first-child) { text-align:right; }
+  tr:hover td { background:var(--graphit-surface-sunken); }
+  .badge { display:inline-block; padding:2px 8px; border-radius:12px; font-size:12px; font-weight:700; }
+  .badge-good { background:var(--graphit-highlight); color:var(--graphit-success); }
+  .badge-warn { background:var(--graphit-highlight); color:var(--graphit-warning); }
+  .badge-bad { background:var(--graphit-highlight); color:var(--graphit-error); }
+</style>
+```
+
+
+
+For inline chart implementations (bar, line, donut, heatmap, funnel, sparkline, gauge, stacked bar, multi-series), see `chart-patterns.md`.

package/skill/graphit.mdc

@@ -0,0 +1,135 @@
+---
+alwaysApply: false
+description: "Build Graphit HTML dashboards with KB-aware queries and entity wrapping"
+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.
+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.
+
+### 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:
+
+```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. Users see labels in @ mention dropdowns - mismatched labels mean they can't find their chart.
+
+### 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.
+
+---
+
+## 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.
+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:
+```
+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 |
+```
+```
+
+**After KB exploration**, summarize what you found:
+```
+Found **12 metrics** and **8 dimensions** on table MARKETING_UA:
+- **Metrics:** TOTAL_SPEND, CPI, ROAS_D7, ROAS_D30, INSTALLS, ...
+- **Dimensions:** MEDIA_SOURCE, CAMPAIGN_NAME, COUNTRY, PLATFORM, ...
+- **Rules:** EXCLUDE_ORGANIC (filters organic installs from paid metrics)
+```
+
+**Formatting rules:**
+- **Bold** metric names, table names, and key numbers
+- Use **markdown tables** for any tabular data (query results, entity lists, comparisons)
+- Format numbers: commas for thousands (`12,400`), `$` for currency, `%` for rates
+- After KB or data source discovery, list what's available before asking what to build
+- Show the SQL you ran (in a code block) so the user can validate the logic
+- When a query returns nulls or zero rows, explain what you checked and what went wrong
+- Narrate your progress between steps: "Found 3 data sources. Using **Marketing UA DS** (ds_abc123) which covers spend, installs, and ROAS columns."
+
+**Never do these:**
+- Run 3 queries silently then jump to building HTML
+- Say "I found the data" without showing what the data looks like
+- Present raw JSON output without formatting
+- Skip showing KB exploration results before proposing a dashboard
+
+---
+
+## 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 |
+
+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/skill/references/chart-patterns.md

@@ -0,0 +1,142 @@
+# 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/references/chart-selection.md

@@ -0,0 +1,83 @@
+# 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/references/dashboard-planning.md

@@ -0,0 +1,94 @@
+# 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