@graphit/cli 0.1.0

package/skill/references/domain-lenses.md

@@ -0,0 +1,114 @@
+# 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/references/graphit-style.md

@@ -0,0 +1,117 @@
+# 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/references/kb-exploration.md

@@ -0,0 +1,69 @@
+# 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/references/sql-reference.md

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