@graphit/cli 0.1.16 → 0.1.19

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

@@ -56,3 +56,68 @@ Use `kb_explore` with max_depth=2 and no edge_type filter. Returns the table's d
 | 3 (max) | Full neighborhood. Use sparingly - can return many results for connected tables. |
 
 Start at depth 1. Only increase if the user's question requires it or the initial results are insufficient.
+
+## Presenting KB Results
+
+**After `graphit kb list <type>`** - count summary + table with bold names:
+
+~~~
+**12 metrics** across 3 tables:
+
+| Metric | Table | Calculation | Params |
+|---|---|---|---|
+| **CPI** | **MARKETING_UA** | `SUM(spend)/SUM(installs)` | - |
+| **ARPU** | **MARKETING_UA** | `SUM(revenue)/COUNT(...)` | DAY |
+| **RETENTION** | **PLAYER_QUALITY** | `COUNT(CASE WHEN ...)` | DAY |
+| ... | | | |
+
+4 parameterized (need `(DAY=N)` syntax), 8 pre-baked.
+~~~
+
+Adapt columns per type: dimensions include semantic type, rules include constraint count, domains include asset count.
+
+**After `graphit kb get <type> <name>`** - entity heading + key-value table:
+
+~~~
+### **CPI** (metric, verified)
+
+*Cost per install*
+
+| | |
+|---:|---|
+| **Table** | **MARKETING_UA** |
+| **Calculation** | `SUM(spend) / SUM(installs)` |
+| **Parameters** | none |
+| **Topics** | ACQUISITION, SPEND |
+| **Default dims** | MEDIA_SOURCE, CAMPAIGN_NAME |
+~~~
+
+Adapt fields per type. Rules: content, constraints, apply-on, override policy. Dimensions: expression, semantic type, output type.
+
+**After `graphit kb search`** - result count + table with type column:
+
+~~~
+**5 results** for "revenue":
+
+| Type | Name | Description |
+|---|---|---|
+| metric | **TOTAL_REVENUE** | Total revenue across all channels |
+| dimension | **REVENUE_BUCKET** | Revenue range segmentation |
+| synonym | GMV | Maps to **TOTAL_REVENUE** (metric) |
+~~~
+
+**After `graphit kb explore`** - tree with bold names, indented by level:
+
+~~~
+**CPI** (metric) on **MARKETING_UA**:
+- **Calculation:** `SUM(spend) / SUM(installs)`
+- **Tables:** **MARKETING_UA**, **MARKETING_UA_6MO** (secondary)
+- **Related dimensions (8):**
+  - **MEDIA_SOURCE** - `media_source` (categorical)
+  - **CAMPAIGN_NAME** - `campaign_name` (categorical)
+  - ...
+- **Rules:** **EXCLUDE_ORGANIC** (filters organic installs)
+- **Domain:** MARKETING
+~~~
+
+For domain exploration, show Domain > Table > Asset hierarchy as a tree.

package/skills/graphit/references/presentations.md

@@ -0,0 +1,143 @@
+# Presentations
+
+Build full-screen slide deck presentations inside Graphit canvas dashboards using `graphit.presentation()`.
+
+## API
+
+```js
+var deck = graphit.presentation('#my-deck');
+
+deck.slide({ bg: 'dark', layout: 'center', html: '<h1>Title</h1><p>Subtitle</p>' });
+deck.slide({ bg: 'white', layout: 'split', html: '<div>Left panel</div><div>Right panel</div>' });
+deck.slide({ bg: 'paper', layout: 'full', html: '<div id="charts">...</div>' });
+
+var ctrl = deck.start();
+// ctrl.go(3)  - jump to slide 4
+// ctrl.total  - number of slides
+```
+
+`graphit.presentation(el)` returns a **builder**. Call `.slide()` to add slides (chainable), then `.start()` to render and wire navigation. `start()` returns a controller with `go(n)` and `total`.
+
+## Slide Config
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `layout` | `'center'` / `'split'` / `'full'` | `'center'` | How content is arranged inside the slide |
+| `bg` | `'paper'` / `'white'` / `'dark'` / `'teal'` / hex | `'paper'` | Fixed background color (not theme-aware) |
+| `html` | `string` | `''` | Raw HTML content for the slide |
+
+## Layouts
+
+### `center` (default)
+Content is centered horizontally and vertically. Use for title slides, quotes, big stats, CTAs.
+
+### `split`
+The first two child elements in `html` become left and right panels (50/50 flex). Use for text + image, comparison, side-by-side content. On mobile (<700px), panels stack vertically.
+
+```js
+deck.slide({
+  layout: 'split',
+  bg: 'white',
+  html: '<div><h2>Left Title</h2><p>Text content</p></div><div><img src="data:..."></div>'
+});
+```
+
+### `full`
+Content flows top-to-bottom with generous padding. Use for tables, grids, live data dashboards, complex layouts that need the full slide width.
+
+## Background Themes
+
+Backgrounds are **fixed colors** - they do not change with the app's light/dark mode. A dark slide stays dark. Content inside CAN use `var(--graphit-*)` tokens.
+
+| Name | Background | Text Color |
+|------|-----------|------------|
+| `paper` | `#F7F6F2` (warm cream) | `#222224` (charcoal) |
+| `white` | `#FFFFFF` | `#222224` |
+| `dark` | `#222224` (charcoal) | `#F7F6F2` (cream) |
+| `teal` | `#4DB6AC` (brand teal) | `#FFFFFF` |
+| hex string | Custom (e.g. `#1a1a2e`) | Inherited from content HTML |
+
+## Navigation
+
+The slide deck includes built-in navigation:
+- **Arrow keys**: Left/Right to navigate (guarded - skips when focus is on input/textarea)
+- **Spacebar**: Next slide
+- **Home/End**: First/last slide
+- **Prev/Next buttons**: Bottom-right corner with slide counter
+
+## Live Data Inside Slides
+
+`graphit.resolve()` and `graphit.chart/table/kpi` work inside slides. All resolve calls fire on page load (cached queries are fast). Charts render into their target elements regardless of which slide is visible.
+
+```js
+// Slide with live entities
+deck.slide({
+  layout: 'full',
+  bg: 'white',
+  html: `
+    <h2>Live Data</h2>
+    <div data-graphit-id="spend-chart" data-graphit-label="Ad Spend"
+         data-graphit-kb="metric:TOTAL_AD_SPEND,table:MARKETING_UA"
+         data-graphit-sql="SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6"
+         data-graphit-ds="ds_abc123">
+      <div id="chart1" class="gh-loading">
+        <div class="gh-loading-overlay"><svg class="gh-loading-spin" width="24" height="24" viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="10" stroke="#e5e5e5" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="#4DB6AC" stroke-width="2.5" stroke-linecap="round"/></svg></div>
+      </div>
+    </div>
+  `
+});
+
+// After deck.start(), fire resolve calls
+deck.start();
+
+graphit.resolve({
+  sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6",
+  dataSourceId: "ds_abc123",
+  target: "#chart1"
+}).then(function(r) {
+  graphit.chart("#chart1", { type: "bar", data: r.data, x: "MEDIA_SOURCE", y: "spend", valueFormat: "currency" });
+});
+```
+
+## Entity Wrapping
+
+Every data element inside slides should have full `data-graphit-*` entity wrapping, same as regular dashboards. The entity provenance panel, @ mentions, and click-to-inspect all work inside slides.
+
+## Example: Complete Pitch Deck
+
+```js
+var deck = graphit.presentation('#deck');
+
+deck.slide({
+  bg: 'paper',
+  layout: 'center',
+  html: '<h1 style="font-size:6rem;font-weight:300">Company Update</h1><p style="font-size:1.5rem;color:#6B7280;margin-top:16px">Q2 2026</p>'
+});
+
+deck.slide({
+  bg: 'dark',
+  layout: 'split',
+  html: '<div style="color:#F7F6F2"><h2 style="font-size:3rem">The Problem</h2><p style="font-size:1.25rem;opacity:0.7;margin-top:16px">Analysts spend 80% of their time assembling dashboards instead of finding insights.</p></div><div style="display:flex;align-items:center;justify-content:center"><img src="data:image/webp;base64,..." style="max-height:60vh;border-radius:16px"></div>'
+});
+
+deck.slide({
+  bg: 'white',
+  layout: 'full',
+  html: '<h2 style="font-size:2.5rem;margin-bottom:24px">Key Metrics</h2><div style="display:grid;grid-template-columns:repeat(3,1fr);gap:16px">...</div>'
+});
+
+deck.slide({
+  bg: 'teal',
+  layout: 'center',
+  html: '<h2 style="font-size:4rem;color:#fff">Thank You</h2><p style="font-size:1.25rem;color:rgba(255,255,255,0.7);margin-top:16px">company.com</p>'
+});
+
+deck.start();
+```
+
+## Anti-Patterns
+
+- **Don't put too much content on one slide.** If it scrolls, split into multiple slides.
+- **Don't use external fonts via @import or link.** The iframe CSP blocks them. Embed as base64 @font-face or use system fonts.
+- **Don't use external images.** Use data URIs (base64) or inline SVG.
+- **Don't nest presentations.** One `graphit.presentation()` per dashboard.

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

@@ -111,6 +111,26 @@ SELECT UNNEST(generate_series(
 
 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.
 
+## Cache-Friendly SQL (Canvas Resolve)
+
+Canvas `graphit.resolve()` queries that follow these shapes serve from a semantic cache in ~10ms on filter changes instead of a full DuckDB recompute (5-37s on wide data sources). Write resolve SQL in this style by default.
+
+**Shape rules:**
+- Single table (no JOIN/UNION)
+- WHERE as flat AND of `column = literal`, `column IN (...)`, `column BETWEEN ... AND ...` conjuncts
+- Bare aggregates only: `SUM(col)`, `COUNT(*)`, `MIN(col)`, `MAX(col)` - no wrapping functions (`ROUND(SUM(x))`), no aggregate arithmetic (`SUM(a)/NULLIF(SUM(b),0)`), no `AVG` (v2)
+- Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions
+- GROUP BY column names or ordinals; ORDER BY / LIMIT allowed (outer only)
+- CTEs are fine when the CTE body follows the same rules
+- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY
+
+**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
+- `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)
+
 ## Data Source Routing
 
 | Situation | Command | Speed |
@@ -119,3 +139,91 @@ The outer SELECT can ONLY reference columns the subquery exposes (its aliases).
 | 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.
+
+## Presenting Query Results
+
+After every `graphit query`, present results grounded in the KB. Always show which KB assets were used - this is what makes governed queries valuable.
+
+**When using KB reference syntax** (`{{metric:X}}`, `{{dim:X}}`), show all five sections:
+
+~~~
+**KB Assets:** dimension **CAMPAIGN_CATEGORY**, metric **TOTAL_INSTALLS**, metric **CPI**, table **MARKETING_UA_DS**
+
+**Query:**
+```sql
+SELECT
+    {{dim:CAMPAIGN_CATEGORY}} AS category,
+    {{metric:TOTAL_INSTALLS}} AS installs,
+    {{metric:CPI}} AS cpi
+FROM MARKETING_UA_DS
+WHERE ACTIVITY_TIME >= '2026-01-01'
+GROUP BY {{dim:CAMPAIGN_CATEGORY}}
+ORDER BY installs DESC
+```
+
+**Resolved SQL:**
+```sql
+SELECT
+    CASE WHEN IS_RETARGETING THEN 'Retargeting'
+         WHEN IS_CTV THEN 'Connected TV'
+         ELSE 'User Acquisition' END AS category,
+    SUM(INSTALLS) AS installs,
+    SUM(APPSFLYER_COST) / NULLIF(SUM(INSTALLS), 0) AS cpi
+FROM MARKETING_UA_DS
+WHERE ACTIVITY_TIME >= '2026-01-01'
+GROUP BY 1
+ORDER BY installs DESC
+```
+
+**Results** (3 rows via **ds_abc123**):
+
+| Category | Installs | CPI |
+|---|---:|---:|
+| User Acquisition | 80,605 | $0.79 |
+| Retargeting | 12,300 | $1.24 |
+| Connected TV | 3,100 | $2.80 |
+
+**Governance:** governed - 3 KB refs, 2 rules enforced (**EXCLUDE_ORGANIC**, **MIN_SPEND**). Max rows: 1,000.
+~~~
+
+**When using inline SQL** (no `{{metric:X}}`), show query + results + governance:
+
+~~~
+**Query:**
+```sql
+SELECT media_source, SUM(spend) AS spend FROM MARKETING_UA_DS GROUP BY 1
+```
+
+**Results** (6 rows via **ds_abc123**):
+
+| Media Source | Spend |
+|---|---:|
+| Facebook | $42,100 |
+| Google UAC | $38,500 |
+
+**Governance:** ad-hoc - 0 KB refs. Consider using `{{metric:TOTAL_SPEND}}` for governed tier.
+~~~
+
+For ad-hoc queries, suggest the KB reference equivalent when one exists. This nudges users toward governed queries.
+
+**Always use `--verbose`** to get the resolved SQL. If the user didn't pass it, re-run with `--verbose` so you can show both the reference query and the expanded SQL.
+
+Zero rows: explain what you checked and hypothesize why (wrong date range, filter too strict, table empty).
+
+## Presenting Data Source Results
+
+After `graphit ds list`:
+
+~~~
+**3 data sources:**
+
+| Name | ID | Rows | Status | Governed |
+|---|---|---:|---|---|
+| **MARKETING_UA_DS** | ds_abc123 | 1,247,832 | active | yes |
+| **PLAYER_QUALITY** | ds_def456 | 892,104 | active | no |
+| **REVENUE_EVENTS** | ds_ghi789 | 3,412,006 | stale | yes |
+
+Using **MARKETING_UA_DS** (ds_abc123) which covers spend, installs, and ROAS columns.
+~~~
+
+End with a recommendation of which DS to use, or note if none covers the needed table.