@graphit/cli 0.1.51 → 0.1.106

package/skills/graphit/VERSION.json

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

package/skills/graphit/cursor/README.md

@@ -0,0 +1,11 @@
+# Cursor references - FROZEN
+
+These `graphit-*.mdc` files are the Cursor mirror of the Graphit CLI skill. They are FROZEN.
+
+- They are kept on disk so existing Cursor users keep working.
+- They are no longer synced from `SKILL.md` + `references/`, and the version stamper no longer touches them.
+- They may be stale relative to the live skill.
+
+The source of truth for the Graphit CLI skill is `cli/skills/graphit/SKILL.md` plus `cli/skills/graphit/references/`. Maintained platforms are Claude Code and Codex.
+
+Do not edit these files to fix a CLI behavior. Fix it in `SKILL.md` / `references/` instead.

package/skills/graphit/graphit.mdc

@@ -1,10 +1,12 @@
 ---
-skill_version: "0.1.51"
+skill_version: "0.1.54"
 alwaysApply: false
 description: "Build Graphit HTML dashboards with KB-aware queries, entity wrapping, and cached data sources"
 globs: []
 ---
 
+> FROZEN - not maintained for Claude Code + Codex; may be stale. Source of truth is SKILL.md + references/.
+
 # Graphit CLI
 
 Build custom HTML dashboards from real data using the Graphit CLI.

package/skills/graphit/references/dashboard-planning.md

@@ -84,13 +84,7 @@ Purpose before data. The first response should mirror the user's intent and ask
 
 ## Performance
 
-`graphit.resolve()` is rate-limited to 120 requests/min per user per dashboard. Each call counts as one request. Design for efficiency:
-
-- **Single refresh function.** All queries in ONE `Promise.all` inside one `refresh()` function. Never scatter `graphit.resolve()` across independent event handlers or timeouts - that turns one user action into multiple bursts.
-- **Count your queries per interaction.** 6 charts = 6 requests per filter change = 20 changes/min budget. 12 charts = 10 changes/min. If you have 10+ charts with 3+ filters, consider debouncing filter changes (300ms) so rapid clicks don't each trigger a full refresh.
-- **Reuse trend data for KPIs.** If you already fetch a weekly time series (`SELECT week, SUM(spend) ...`), derive the KPI total and sparkline from that result set in JS instead of running a separate aggregate query. One query serves both the chart and the KPI card.
-- **Avoid redundant refreshes.** If a filter only affects some charts, split into targeted refresh functions (`refreshKPIs()`, `refreshCharts()`) so unchanged sections don't re-query.
-- **No polling.** Never `setInterval(refresh, ...)`. Data sources update on their own schedule - a dashboard that polls wastes the entire rate budget.
+Live data goes through `graphit.resolve()`, which is rate-limited per user per dashboard. Budget your queries per interaction - batch them, reuse trend data for KPIs, split targeted refreshes, and never poll. The full rate-limit budget and the efficient-refresh patterns live in `runtime.md`.
 
 ## Pre-Build Checklist
 

package/skills/graphit/references/data-sources.md

@@ -1,7 +1,18 @@
-# Data Sources: Building for Speed
+# Data Sources: Routing and Building for Speed
 
 A data source's shape - set by its source SQL at creation - decides how fast every dashboard built on it will be, and whether filter changes feel instant. Get this right when you create the source; it can't be fixed later in the dashboard SQL.
 
+## Routing: which source to query
+
+Always prefer a cached data source over the live warehouse. Check what exists with `graphit ds list` before writing any query.
+
+| Situation | Command | Speed |
+|---|---|---|
+| The table has a cached data source | `graphit query "SQL" --ds <id>` | roughly 100ms, DuckDB |
+| No data source covers the table | `graphit query "SQL" --warehouse --connection <id>` | roughly 10s, Snowflake |
+
+If no data source covers the table the user needs, propose creating one for future speed rather than defaulting to repeated warehouse queries. Dialect differs by route (DuckDB for `--ds`, Snowflake for `--warehouse`); see `sql-reference.md`.
+
 ## Why source shape decides dashboard speed
 
 When you change a dashboard filter (e.g. switch country), Graphit answers from a cached, pre-aggregated result instead of re-scanning the whole source - but only when the source is small and already aggregated to the grain you query. Build the source as one row per the grain you'll chart (e.g. month x country x channel) with only the columns you use, and filter changes return in milliseconds. Pull in raw ungrouped rows, hundreds of columns, or thousands-of-values dimensions and the result is too big to cache - every filter change re-scans the entire source and is slow.
@@ -74,3 +85,21 @@ The CLI fires all refreshes in parallel and polls until every source is ready. L
 ## Deleting data sources
 
 There is no `graphit ds delete` command. Deleting a data source cascades to GCS storage and the KB table, which removes all metrics, dimensions, and rules defined on it. Direct the user to delete from the platform UI (Sources Hub) where the confirmation flow shows what will be affected.
+
+## Presenting data source results
+
+The user cannot see the raw CLI output - you are the rendering layer. After `graphit ds list`, present a markdown table and end with a recommendation of which source to use (or note that none covers the needed table):
+
+~~~
+**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.
+~~~
+
+Bold every data source name. If a source is stale, say so and offer to refresh it before querying.

package/skills/graphit/references/filters-advanced.md

@@ -0,0 +1,61 @@
+# Advanced Filter Controls - Dependent Dropdowns and Date Presets
+
+Load only when you need one of two optional controls on top of the core filters: a dependent dropdown ("only relevant values" that narrows as an upstream filter changes) or a date-preset picker. The base filter, param, bind, wiring, `:name` binding, and saved-view mechanics live in `filters.md`. Both controls below are headless logic - you own all the markup.
+
+## graphit.cascade(el, options) - Only Relevant Values
+
+Dependent dropdowns: fetch a column's DISTINCT values constrained by other filters, and refetch when they change. For example, pick an org and the user list shows only that org's users. Logic only - you build the checkboxes or list in `render`.
+
+```js
+const org = graphit.filter('org', { label: 'Org' })
+const user = graphit.filter('user', { label: 'User', default: [] }) // multi-select
+
+graphit.cascade('#user-list', {
+  column: 'USER_NAME',                  // distinct values of this column
+  source: 'users_table',               // table name (or a subquery)
+  dataSourceId: 'ds_abc',
+  filters: () => ({ ORG: org.get() }),  // upstream constraints; empty values skipped
+  deps: ['org'],                        // refetch when org changes
+  selection: user,                      // optional: prune selected users no longer in this org
+  render: (values, el, ctx) => {
+    // ctx = { loading, empty, error, hasUpstream } - build any markup you like
+    el.innerHTML = values.map(v => `<label><input type="checkbox" value="${v}"> ${v}</label>`).join('')
+  },
+})
+```
+
+- `filters()` returns `{ COLUMN: value }`. A scalar makes `COLUMN = :p`; an array makes `COLUMN IN :p`. Empty values (`null`, `''`, `[]`) are skipped (no constraint), so an empty upstream means "no filter", not "match nothing".
+- `selection` (a filter handle) is auto-pruned to the surviving values when an upstream changes.
+- Returns `{ destroy() }`. Keep the result set small (default `LIMIT 1001`); these parameterized queries skip the result cache, so they hit DuckDB directly.
+- Faster for low-cardinality cascades: add `preload: true` to fetch the full distinct cross-product ONCE (cacheable, no params) and filter in-memory on every change - instant, zero per-change round-trips. Best when the column-by-upstream combinations are small (cap = `limit`, default 1001 tuples); above the cap it auto-falls-back to per-change server queries.
+
+## graphit.dateRange(id, options) - Date Presets
+
+A headless date filter with the standard presets built in (logic only - you render the buttons or inputs). `default` is a preset id or `{ start, end }`.
+
+```js
+const dr = graphit.dateRange('date_range', { label: 'Date Range', default: 'last_30_days' })
+```
+
+Handle:
+- `dr.get()` returns `{ preset, start, end }` (ISO `YYYY-MM-DD`)
+- `dr.set(presetId)` (e.g. `dr.set('this_month')`); `dr.setRange(start, end)` for a custom range
+- `dr.start` / `dr.end` / `dr.preset` convenience getters; `dr.deps` (pass as `deps: dr.deps`); `dr.subscribe(cb)` (cb gets `{ preset, start, end }`)
+
+A `dateRange` registration persists to saved views exactly like a `filter`/`param`, and its `subscribe` callback restores the picker's visual state on view apply or reload (same rule as the core controls in `filters.md`).
+
+Relative presets auto-recompute on reload (a saved "last_7_days" always means the last 7 days from today). The 11 preset ids - also available via `graphit.datePresets` (`[{id,label}]`) and `graphit.datePreset(id)` (`{start,end}`): today, yesterday, last_7_days, last_30_days, this_month, last_month, this_quarter, last_quarter, ytd, last_90_days, last_12_months.
+
+Bind a chart to the range with two scalar params and a `BETWEEN`:
+
+```js
+graphit.bind('#rev', {
+  sql: 'SELECT day, SUM(rev) AS rev FROM orders WHERE day BETWEEN :start_date AND :end_date GROUP BY 1',
+  dataSourceId: 'ds_abc',
+  params: () => ({ start_date: dr.start, end_date: dr.end }),
+  deps: dr.deps,
+  render: (r, el) => graphit.chart(el, { type: 'area', data: r.data, x: 'day', y: 'rev' }),
+})
+```
+
+Name the placeholders `:start_date` / `:end_date`, never `:from` / `:to` - reserved-word placeholders fail SQL validation (see the `:name` rules in `filters.md`).

package/skills/graphit/references/filters.md

@@ -1,10 +1,18 @@
 # Headless Filters, Parameters, and Saved Views
 
+Load when the dashboard needs interactivity: a control the user changes that re-resolves a chart, plus saved views. A static dashboard skips this file. Dependent dropdowns and date presets live in `filters-advanced.md`.
+
+## Contents
+
+Core Concept | `graphit.filter()` / `graphit.param()` | Wiring a Control | `graphit.bind()` | Safe Parameter Binding (`:name`) | Saved Views | Complete Example
+
 ## Core Concept
 
 `graphit.filter()` and `graphit.param()` are headless JS registrations. They create NO DOM elements. You build 100% of the filter control's markup (any HTML, SVG, or CSS). The registration manages state so values can be snapshotted into saved views and survive page reloads.
 
-**Logic vs style.** `filter`, `param`, `bind`, `dateRange`, `cascade` are headless logic - zero imposed styling, you own the markup. `chart`, `table`, `kpi`, `presentation`, `dropdown` render styled output you can use or hand-roll past.
+**Logic vs style.** `filter`, `param`, `bind` are headless logic - zero imposed styling, you own the markup. `chart`, `table`, `kpi`, `presentation`, `dropdown` render styled output you can use or hand-roll past.
+
+These four pieces always work together: register a control, register the binding that reads it, wire your markup to the handle, and let saved views snapshot it. A filter with no `bind` does nothing - plan to include all four when you add interactivity.
 
 ## graphit.filter(id, options)
 
@@ -25,56 +33,15 @@ Handle API:
 
 ## graphit.param(id, options)
 
-Same API as filter but semantically a parameter (not tied to a KB field). Use for user-controlled inputs like date range pickers, threshold sliders, or toggle switches.
+Same API as filter but semantically a parameter (not tied to a KB field). Use for user-controlled inputs like threshold sliders or toggle switches.
 
 ```js
 const topN = graphit.param('top_n', { label: 'Top N', default: 10, options: [5, 10, 20, 50] })
 ```
 
-## graphit.dateRange(id, options)
-
-A headless date filter with the standard presets built in (logic only - you render the buttons/inputs). `default` is a preset id or `{ start, end }`.
-
-```js
-const dr = graphit.dateRange('date_range', { label: 'Date Range', default: 'last_30_days' })
-```
-
-Handle:
-- `dr.get()` -> `{ preset, start, end }` (ISO `YYYY-MM-DD`)
-- `dr.set(presetId)` (e.g. `dr.set('this_month')`); `dr.setRange(start, end)` for a custom range
-- `dr.start` / `dr.end` / `dr.preset` convenience getters; `dr.deps` (pass as `deps: dr.deps`); `dr.subscribe(cb)` (cb gets `{ preset, start, end }`)
-
-Relative presets auto-recompute on reload (a saved "last_7_days" always means the last 7 days from today). The 11 preset ids - also via `graphit.datePresets` (`[{id,label}]`) and `graphit.datePreset(id)` (`{start,end}`): today, yesterday, last_7_days, last_30_days, this_month, last_month, this_quarter, last_quarter, ytd, last_90_days, last_12_months.
-
-Bind a chart to the range with two scalar params and a `BETWEEN`:
-
-```js
-graphit.bind('#rev', {
-  sql: 'SELECT day, SUM(rev) AS rev FROM orders WHERE day BETWEEN :start_date AND :end_date GROUP BY 1',
-  dataSourceId: 'ds_abc',
-  params: () => ({ start_date: dr.start, end_date: dr.end }),
-  deps: dr.deps,
-  render: (r, el) => graphit.chart(el, { type: 'area', data: r.data, x: 'day', y: 'rev' }),
-})
-```
-
 ## Wiring a Control
 
-The registration renders nothing. Wire any HTML element you build:
-
-```html
-<select id="country-picker">
-  <option value="US">US</option>
-  <option value="IL">Israel</option>
-</select>
-<script>
-  const country = graphit.filter('country', { label: 'Country', default: 'US' });
-  const picker = document.getElementById('country-picker');
-  picker.value = country.get();
-  picker.onchange = () => country.set(picker.value);
-  country.subscribe(v => { picker.value = v; }); // restores on view apply or page reload
-</script>
-```
+The registration renders nothing, so connect your own markup to the handle in three steps: set the element's initial value from `handle.get()`, call `handle.set(newValue)` in the change event, and pass `handle.subscribe(v => updateElement(v))` so the control restores its visual state on saved-view apply or page reload. The Complete Example below shows this end to end for a `<select>`.
 
 ## graphit.bind(el, options) - Reactive Data Binding
 
@@ -96,36 +63,9 @@ graphit.bind(document.getElementById('revenue-chart'), {
 - Multi-key changes (e.g. a saved view applying 3 filters) debounce into one re-resolve per element
 - `render` is your code - call `graphit.chart`, `graphit.table`, or hand-roll SVG/CSS
 
-## graphit.cascade(el, options) - Only Relevant Values
-
-Dependent dropdowns: fetch a column's DISTINCT values constrained by other filters, and refetch when they change (e.g. pick an org, the user list shows only that org's users). Logic only - you build the checkboxes/list in `render`.
-
-```js
-const org = graphit.filter('org', { label: 'Org' })
-const user = graphit.filter('user', { label: 'User', default: [] }) // multi-select
-
-graphit.cascade('#user-list', {
-  column: 'USER_NAME',                  // distinct values of this column
-  source: 'users_table',               // table name (or a subquery)
-  dataSourceId: 'ds_abc',
-  filters: () => ({ ORG: org.get() }),  // upstream constraints; empty values skipped
-  deps: ['org'],                        // refetch when org changes
-  selection: user,                      // optional: prune selected users no longer in this org
-  render: (values, el, ctx) => {
-    // ctx = { loading, empty, error, hasUpstream } - build any markup you like
-    el.innerHTML = values.map(v => `<label><input type="checkbox" value="${v}"> ${v}</label>`).join('')
-  },
-})
-```
-
-- `filters()` returns `{ COLUMN: value }`. A scalar makes `COLUMN = :p`; an array makes `COLUMN IN :p`. Empty values (`null`, `''`, `[]`) are skipped (no constraint), so an empty upstream means "no filter", not "match nothing".
-- `selection` (a filter handle) is auto-pruned to the surviving values when an upstream changes.
-- Returns `{ destroy() }`. Keep the result set small (default `LIMIT 1001`); these parameterized queries skip the result cache, so they hit DuckDB directly.
-- **Faster for low-cardinality cascades:** add `preload: true` to fetch the full distinct cross-product ONCE (cacheable, no params) and filter in-memory on every change - instant, zero per-change round-trips. Best when the column x upstream combinations are small (cap = `limit`, default 1001 tuples); above the cap it auto-falls-back to per-change server queries.
-
 ## Safe Parameter Binding (`:name` syntax)
 
-Use `:name` placeholders in SQL for safe server-side parameter binding. Never string-concatenate user values into SQL.
+Use `:name` placeholders in SQL for safe server-side parameter binding. NEVER string-concatenate user values into SQL.
 
 | Shape | SQL | Params |
 |-------|-----|--------|
@@ -133,7 +73,7 @@ Use `:name` placeholders in SQL for safe server-side parameter binding. Never st
 | Multi-select | `WHERE country IN :countries` | `{countries: ['US', 'IL']}` (expands to safe `IN ($0, $1)`) |
 | Date range | `WHERE date BETWEEN :start_date AND :end_date` | `{start_date: '2026-01-01', end_date: '2026-06-01'}` |
 
-**Don't name a param after a SQL keyword** (`from`, `to`, `select`, `order`, `group`, ...). The SQL template is parsed before values bind, so a reserved-word placeholder like `:from` fails with "SQL validation failed". Use names like `:start_date`, `:end_date`.
+Do NOT name a param after a SQL keyword (`from`, `to`, `select`, `order`, `group`, and similar). The SQL template is parsed before values bind, so a reserved-word placeholder like `:from` fails with "SQL validation failed". Use names like `:start_date`, `:end_date`.
 
 Array length capped at 200 elements, max 50 param keys per resolve call.
 
@@ -141,26 +81,20 @@ Array length capped at 200 elements, max 50 param keys per resolve call.
 
 Users can save the current filter/parameter state as a named view and restore it later. The platform snapshots all registered `graphit.filter` and `graphit.param` values automatically. Views survive page reloads (state is baked into the iframe on every render). A default view auto-applies on dashboard open with no flash.
 
-The subscribe callback on each handle restores the control's visual state when a view is applied - this is why every control must include a `subscribe(v => ...)` that updates its appearance.
+The subscribe callback on each handle restores the control's visual state when a view is applied. This is why every control MUST include a `subscribe(v => ...)` that updates its appearance. A control registered without `graphit.filter`/`param` (a hand-rolled `<select>` on its own) will NOT persist to a view.
 
 ## Complete Example
 
+One control, wired to one reactive chart. The `<select>` is your own markup; `bind()` re-resolves the chart whenever the filter changes.
+
 ```html
-<div style="margin-bottom: 16px;">
-  <label style="font-size: 12px; color: var(--graphit-fg-muted);">Region</label>
-  <select id="region-select" style="padding: 6px 12px; border: 1px solid var(--graphit-border); border-radius: 6px; background: var(--graphit-surface-raised); color: var(--graphit-fg);">
-    <option value="ALL">All Regions</option>
-    <option value="NA">North America</option>
-    <option value="EU">Europe</option>
-    <option value="APAC">Asia Pacific</option>
-  </select>
-</div>
-
-<div id="revenue-by-region" data-graphit-id="revenue-by-region"
-     data-graphit-label="Revenue by Region"
-     data-graphit-sql="SELECT month, SUM(revenue) AS revenue FROM sales WHERE region = :region GROUP BY 1 ORDER BY 1"
-     data-graphit-ds="ds_sales">
-</div>
+<label>Region</label>
+<select id="region-select">
+  <option value="ALL">All Regions</option>
+  <option value="NA">North America</option>
+  <option value="EU">Europe</option>
+</select>
+<div id="revenue-by-region"></div>
 
 <script>
   const region = graphit.filter('region', { label: 'Region', field: 'REGION', default: 'ALL' });
@@ -171,11 +105,9 @@ The subscribe callback on each handle restores the control's visual state when a
   region.subscribe(v => { sel.value = v; });
 
   graphit.bind(document.getElementById('revenue-by-region'), {
-    sql: `SELECT month, SUM(revenue) AS revenue FROM sales
-          ${region.get() !== 'ALL' ? 'WHERE region = :region' : ''}
-          GROUP BY 1 ORDER BY 1`,
+    sql: 'SELECT month, SUM(revenue) AS revenue FROM sales WHERE (:region = \'ALL\' OR region = :region) GROUP BY 1 ORDER BY 1',
     dataSourceId: 'ds_sales',
-    params: () => region.get() !== 'ALL' ? { region: region.get() } : {},
+    params: () => ({ region: region.get() }),
     deps: ['region'],
     render: (result, el) => {
       graphit.chart(el, { type: 'area', data: result.data, x: 'month', y: 'revenue', valueFormat: 'currency' });
@@ -183,3 +115,5 @@ The subscribe callback on each handle restores the control's visual state when a
   });
 </script>
 ```
+
+For dependent dropdowns (an "only relevant values" list that narrows as an upstream filter changes) and date-preset pickers, see `filters-advanced.md`.

package/skills/graphit/references/governance.md

@@ -1,113 +1,96 @@
 # Query Governance
 
-Server-side governance ensures consistent, auditable queries across all channels.
+Load this when writing or validating a governed query, working trust tiers, or working the ad-hoc frontier (deciding whether a raw measure run is allowed on a governed source).
 
-## Reference Syntax
+Governance is enforced server-side in the QueryGateway, the same across every channel. You CANNOT weaken it from the CLI; you can only write queries that pass it or, where the mode allows, run a raw measure with explicit approval.
 
-Use KB references instead of inline formulas for governed queries:
+## Reference syntax
 
-```sql
--- Governed: server expands to KB-defined formulas
-SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} as cpi
-FROM MARKETING_UA_DS
-GROUP BY 1
+Write governed queries with KB references, not inline formulas. The server compiles each to its KB expression, injects rule constraints, stamps the trust tier, and caches the result. The syntax is identical in `graphit query` and `graphit.resolve()`.
 
--- Parameterized metric (ARPU requires DAY parameter)
-SELECT {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS
+| Syntax | Expands to | Example |
+|--------|-----------|---------|
+| `{{metric:NAME}}` | Metric calculation (aggregation) | `{{metric:CPI}}` |
+| `{{metric:NAME(K=V)}}` | Parameterized metric | `{{metric:ARPU(DAY=7)}}` |
+| `{{metric_raw:NAME}}` | Raw expression, no outer aggregate | `{{metric_raw:REVENUE}}` |
+| `{{dim:NAME}}` | Dimension expression | `{{dim:INSTALL_MONTH}}` |
 
--- Raw expression (no outer aggregate)
-SELECT {{metric_raw:REVENUE}} FROM orders
+```bash
+graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} AS cpi FROM MARKETING_UA_DS GROUP BY 1" --ds ds_abc123 --verbose
 ```
 
-The server compiles references to actual expressions, injects rule constraints, stamps trust tier, and caches results. Reference syntax works in both `graphit query` and `graphit.resolve()`.
+`--verbose` prints the expanded SQL and trust tier, so you can confirm the reference resolved before presenting the result.
+
+## Parameterized metrics
+
+Some metrics (for example ARPU, ROAS, RETENTION) carry required parameters and cannot resolve without a value. Run `graphit kb list metric` and read the `params` column for the names a metric requires, then supply them inline as `{{metric:ARPU(DAY=7)}}`. Pre-baked variants such as `ARPU_D7` or `ROAS_D30` have the value fixed and need none. Omitting a required parameter returns a clear error naming the exact syntax, so read `params` first.
 
-**Parameterized metrics:** Some metrics (ARPU, ROAS, RETENTION) require parameters. Check `graphit kb list metric` - the `params` column shows required names. Pre-baked variants (ARPU_D7, ROAS_D30) have values hardcoded and need no parameters. Omitting required parameters returns a clear error with the exact syntax to use.
+## Trust tiers
 
-## Trust Tiers
+Every result is stamped with a tier the platform shows the user as a badge on dashboard graphs and canvas entities - your honest signal of how trustworthy the number is.
 
 | Tier | Meaning | Badge |
 |------|---------|-------|
-| **governed** | Used `{{metric:X}}` / `{{dim:X}}` references | Teal dot |
-| **verified** | Raw SQL matches KB definitions (AST matching) | Amber dot |
-| **ad_hoc** | Inline formulas, no KB match | Gray dot |
+| `governed` | Query used `{{metric:X}}` / `{{dim:X}}` references | Teal dot |
+| `verified` | Raw SQL whose expressions match KB definitions | Amber dot |
+| `ad_hoc` | Inline formulas with no KB match | Gray dot |
 
-## Governance Modes
+Prefer the governed tier. The server may upgrade matching raw SQL to verified, but reach for references first so the result is governed by intent.
 
-| Mode | Behavior |
-|------|----------|
-| `observe` | All queries pass, tiers are tracked |
-| `warn` | Ad-hoc **measure** queries on governed DSes ask for approval; exploration warns |
-| `strict` | All ad-hoc queries on governed DSes are blocked |
+## The ad-hoc measure gate
 
-```bash
-graphit governance status     # View mode and conformance stats
-graphit governance set warn   # Change mode (admin only)
-graphit governance audit      # View audit log
-```
+This is the hard frontier, enforced server-side. The rules below are what the QueryGateway does, not a suggestion you can soften.
 
-## Ad-hoc Measure Gate
+An **ad-hoc measure** computes a business measure (an aggregate or `GROUP BY` that produces a metric) on a governed data source WITHOUT `{{metric:NAME}}` references, so it lands at the `ad_hoc` tier. Plain exploration is not a measure: `SELECT *`, raw column selects, `COUNT(*)` row-count peeks, `DISTINCT` value lists.
 
-On a governed data source, an ad-hoc query that computes a business measure (an aggregate or `GROUP BY` producing a metric) is gated. Exploration is exempt and runs free: `SELECT *`, raw column selects, `COUNT(*)` row-count peeks, `DISTINCT` value lists.
+- **warn.** The ad-hoc measure is rejected and asks for approval. First rewrite it with `{{metric:NAME}}` / `{{dim:NAME}}` references (search the KB for a match). Only if the user genuinely needs the raw run, ask them, then re-run the exact command with `--approve-adhoc`. Plain exploration is **exempt**: it runs free, with only a non-blocking warning.
+- **strict.** CRITICAL: every `ad_hoc`-tier query is a HARD BLOCK, including plain exploration that does not match the KB. Rewrite with references or stop. `--approve-adhoc` NEVER bypasses strict and does not weaken it; do not offer it in strict mode.
+- **observe.** All queries run; tiers are tracked, nothing is gated.
 
-- **warn mode:** the measure query is rejected. Rewrite using `{{metric:NAME}}` / `{{dim:NAME}}` references, or - if the user needs the raw run - ask them and re-run with `--approve-adhoc`.
-- **strict mode:** all ad-hoc queries are hard-blocked. Rewrite with references or stop; `--approve-adhoc` does not bypass strict.
+When the gate fires, do not narrate around it or pretend the query ran. Report truthfully: it was blocked or needs approval, name the governed rewrite, and let the user decide.
 
-## Enforceable Rules
+## Enforceable rules and overrides
 
-Rules with typed constraints are enforced automatically via SQL injection:
+Rules with typed constraints are enforced automatically, rewriting the SQL before it runs:
 
 | Type | What it does |
 |------|-------------|
 | `required_where` | Injects a WHERE predicate |
 | `forbidden_column` | NULLifies a column in SELECT |
-| `value_restriction` | Restricts column to allowed values |
-| `required_filter` | Validates column appears in WHERE |
-| `required_aggregation` | Validates GROUP BY includes column |
-
-User-context variables (`${user.team_id}`, `${user.email}`) are resolved server-side for row-level security.
+| `value_restriction` | Restricts a column to allowed values |
+| `required_filter` | Validates a column appears in WHERE |
+| `required_aggregation` | Validates GROUP BY includes a column |
 
-## Override Flow
+User-context variables (`${user.team_id}`, `${user.email}`) resolve server-side for row-level security. Override a rule only when the user explicitly asks and the rule's `override_policy` (anyone / analyst_only / admin_only / never) and the user's role allow it; a `never` policy can never be overridden, and every override is logged. Pass several names to override more than one.
 
 ```bash
-# Override a specific rule
 graphit query "SELECT * FROM events" --ds ds_123 --override-rules EXCLUDE_RETARGETING
-
-# Multiple overrides
-graphit query "SELECT * FROM events" --ds ds_123 --override-rules RULE1 RULE2
 ```
 
-Override is checked against the rule's `override_policy` (anyone/analyst_only/admin_only/never) and the user's role. Overrides are always logged to the audit trail.
+## Per-DS settings and governance mode
 
-## Per-DS Settings
+Governed mode and the row cap are set per data source; enabling governed mode activates the ad-hoc gate for that DS. The governance mode is org-wide and admin-only, set with a `--mode` flag, not a positional argument (values `observe`, `warn`, `strict`). Run `graphit ds update --help` and `graphit governance set --help` for exact flag spelling.
 
 ```bash
-graphit ds update <id> --governed-mode on    # Enable governed mode
-graphit ds update <id> --governed-mode off   # Disable
-graphit ds update <id> --max-rows 10000      # Set row cap
+graphit governance set --mode warn
 ```
 
-## Presenting Governance Results
-
-**After `graphit governance status`:**
-
-~~~
-**Governance mode:** strict
+## Presenting governance results
 
-**7-day conformance:**
+The user CANNOT see raw CLI output. Render every result as markdown.
 
-| Tier | Queries | Share |
-|---|---:|---:|
-| Governed | 847 | 72% |
-| Ad-hoc | 328 | 28% |
-| Blocked | 12 | 1% |
+**After a governed query**, append a provenance footer so the trust signal travels with the number: tier, governed DS, KB references used, rules enforced by name, row cap if applied. For an ad-hoc result, state the tier honestly and offer the governed `{{metric:NAME}}` / `{{dim:NAME}}` rewrite.
 
-5 active rules across 3 governed data sources.
 ~~~
+**Trust tier:** governed - governed DS, 2 KB refs, 1 rule enforced (**EXCLUDE_INTERNAL**), max rows 10000
+~~~
+
+**After `graphit governance status`**, show the mode plus the 7-day conformance counts (governed / verified / ad-hoc / total) as a small markdown table headed by `**Governance mode:** <mode>`.
 
-**After governance errors:**
+**When a gate or rule blocks a query**, explain it and the path forward, no raw dump:
 
 ~~~
-**Error:** Query blocked by governance.
+**Blocked by governance.**
 
-Rule **EXCLUDE_ORGANIC** (override policy: `never`) cannot be overridden. Contact your admin to change the policy, or rewrite the query to include the required filter.
+Rule **EXCLUDE_ORGANIC** has override policy `never` and cannot be overridden. Ask your admin to change the policy, or rewrite the query to include the required filter.
 ~~~

package/skills/graphit/references/graphit-style.md

@@ -1,6 +1,6 @@
 # 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.
+Consult when authoring the dashboard HTML. This is the design system: principles, the Graphit aesthetic, typography, the color-token system, and layout CSS. Data wiring (resolve, entity wrapping, the first-paint loading overlay) lives in `runtime.md`; per-chart implementations live in `chart-patterns.md`.
 
 ## Design Principles
 
@@ -84,12 +84,6 @@ Use the system font stack everywhere: `-apple-system, BlinkMacSystemFont, 'Segoe
           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; }
-  @keyframes gh-spin{to{transform:rotate(360deg)}}
-  .gh-loading { position:relative; min-height:120px; }
-  .gh-loading-overlay { position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
-                        z-index:9998; backdrop-filter:blur(3px); -webkit-backdrop-filter:blur(3px);
-                        background:color-mix(in srgb,var(--graphit-surface-raised,#fff) 50%,transparent); border-radius:inherit; }
-  .gh-loading-spin { animation:gh-spin .7s linear infinite; }
   @media(max-width:900px) {
     .kpi-grid { grid-template-columns:repeat(2,1fr); }
     .charts-grid { grid-template-columns:1fr; }
@@ -97,6 +91,8 @@ Use the system font stack everywhere: `-apple-system, BlinkMacSystemFont, 'Segoe
 </style>
 ```
 
+Also add the first-paint loading-overlay CSS (the `gh-loading` family) to the page `<style>` and wrap every resolve target with it. That overlay is the SDK contract - the canonical CSS and rules are in `runtime.md`.
+
 ### 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
@@ -129,16 +125,8 @@ Use the system font stack everywhere: `-apple-system, BlinkMacSystemFont, 'Segoe
 </style>
 ```
 
-### Loading State
-
-Bake this overlay inside every element passed as `target:` to `graphit.resolve()` - and only those (static text/title cards would spin forever). It shows from the first paint, before the SDK connects; the SDK removes it when the resolve settles. Class names are the SDK contract - keep them exactly:
-
-```html
-<div id="spend-chart" 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="var(--graphit-border,#e5e5e5)" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="var(--graphit-accent,#4DB6AC)" stroke-width="2.5" stroke-linecap="round"/></svg></div>
-</div>
-```
+### Loading state
 
-Never write "Loading..." text placeholders - they don't animate and make slow loads look stuck.
+The first-paint loading overlay (the `gh-loading` overlay baked into every resolve target) is part of the data-wiring contract with the SDK. Its canonical CSS, the markup, and the rule about which elements get it live in `runtime.md`.
 
-For inline chart implementations (bar, line, donut, heatmap, funnel, sparkline, gauge, stacked bar, multi-series), see `chart-patterns.md`.
+For per-chart implementations (bar, line, donut, heatmap, funnel, sparkline, gauge, stacked bar, multi-series), see `chart-patterns.md`.