@graphit/cli 0.1.15 → 0.1.18

package/skills/graphit/graphit.mdc

@@ -25,6 +25,8 @@ NEVER query the warehouse directly when a cached data source covers the table. D
 
 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.
 
+**Use the DS name in SQL, not the source table name.** Write `FROM MARKETING_UA_DS`, not `FROM MARKETING_UA`. The DS name is what users see in the platform. DuckDB resolves both, but the DS name keeps SQL consistent with the UI.
+
 ### 3. EVERY element must have entity wrapping
 Without `data-graphit-*` attributes, elements are invisible to the platform. Every chart, KPI card, table, and text section needs ALL FIVE attributes:
 
@@ -32,7 +34,7 @@ Without `data-graphit-*` attributes, elements are invisible to the platform. Eve
 <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_ds GROUP BY region"
+     data-graphit-sql="SELECT region, SUM(revenue) FROM orders GROUP BY region"
      data-graphit-ds="ds_abc123">
   <!-- chart/KPI/table content here -->
 </div>
@@ -42,17 +44,20 @@ Without `data-graphit-*` attributes, elements are invisible to the platform. Eve
 |-----------|--------|---------|
 | `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-kb` | `type:NAME` comma-separated | `"metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA_DS"` |
 | `data-graphit-sql` | Executable SQL (HTML-encode `<>&"`) | `"SELECT ..."` |
 | `data-graphit-ds` | Data source ID from `graphit ds list` | `"ds_abc123"` |
 
 KB types: `metric`, `dimension`, `table`, `rule`. Names are UPPER_SNAKE_CASE matching the KB exactly. **Names are unique per type per org** - creating a duplicate name will fail. Check `graphit kb list <type>` first; update the existing asset instead of creating a new one.
 
-**SQL must be executable.** The platform runs `data-graphit-sql` against the data source when a user opens the entity's details panel. It MUST use the real DS table name and only columns that exist in the DS - never invented summary columns, CTE aliases, JS variable names, or prose. If the chart's resolve call uses a CTE, put the full WITH query. If JS builds SQL dynamically, store one representative executable variant (e.g. the default date range).
+**SQL must be complete and executable.** The platform runs `data-graphit-sql` against the data source when a user opens the entity's details panel. Write the full query from the `graphit.resolve()` call - never abbreviate, truncate, or use placeholders (`FROM ...`, `SELECT ...`, ellipsis). It MUST use the real DS table name and only columns that exist in the DS - never invented summary columns, CTE aliases, JS variable names, or prose. If the chart's resolve call uses a CTE, put the full WITH query. If JS builds SQL dynamically, store one representative executable variant (e.g. the default date range).
 
 **Label = visible title.** The `data-graphit-label` MUST match the card's visible heading exactly.
 
-### 4. ALWAYS use graphit.resolve() for live data
+### 4. Shared dashboards require Edit mode on the platform
+Dashboards shared with teams are protected by an editing session lock. The CLI cannot acquire editing sessions - mutations (`dashboard update-html`, `dashboard update-entity`) on a shared dashboard will fail with 423. Tell the user to open the dashboard on the Graphit platform and click **Edit** first. Private dashboards are unaffected.
+
+### 5. ALWAYS use graphit.resolve() for live data
 NEVER embed query results as static JS variables. The dashboard iframe provides `graphit.resolve()` which fetches live data from cached data sources on every page load.
 
 **Wrong:** Embedding results as `const data = [{...}, ...]` in the HTML.
@@ -60,6 +65,38 @@ NEVER embed query results as static JS variables. The dashboard iframe provides
 
 ---
 
+## Presenting Results to the User
+
+You are the rendering layer - format and present every CLI result using markdown. Never silently consume output.
+
+**Formatting fundamentals:** Bold every KB asset/table/DS name (**CPI**, **MARKETING_UA_DS**). Markdown tables for tabular data. Code blocks (```sql) for every SQL query. Format numbers: commas (12,400), $ for currency, % for rates. Narrate between steps.
+
+**After `graphit query`** - ground in KB, show five sections:
+1. **KB Assets:** bold names of all referenced metrics/dimensions/tables
+2. **Query:** original SQL with `{{metric:X}}` references in ```sql block
+3. **Resolved SQL:** expanded SQL (always use `--verbose`) in ```sql block
+4. **Results:** markdown table, row count, DS ID
+5. **Governance:** tier, KB refs, rules enforced (**bold names**)
+- For ad-hoc queries: show query + results + governance, suggest KB reference equivalent
+
+**After `graphit kb list`** - count summary + table with bold names:
+- `**12 metrics** across 3 tables:` then table with **bold name**, table, calculation, params
+- Footer summarizing parameterized vs pre-baked
+
+**After `graphit kb get`** - entity heading + key-value table:
+- `### **CPI** (metric, verified)` with description in italics
+- Key-value table: Table, Calculation, Parameters, Topics, Dimensions
+
+**After `graphit kb search`** - result count + table with type column
+**After `graphit kb explore`** - tree structure: Asset > Tables > Dimensions > Rules
+**After `graphit ds list`** - table with Name, ID, Rows, Status, Governed + recommend which DS to use
+**After `graphit governance status`** - mode + conformance table (Governed/Ad-hoc/Blocked with counts and %)
+**After errors** - bold error message + actionable fix suggestion
+
+**Never:** run queries silently, present raw JSON, skip governance footer, omit SQL code blocks, show tables without bold asset names.
+
+---
+
 ## Workflow: Dashboard Build
 
 1. **Ask the user** what dashboard they want.
@@ -81,6 +118,27 @@ When the user wants to build or populate their KB from files, schemas, or scratc
 5. **Execute top-down.** Create in order: domains, topics, metrics (with --topics), dimensions, rules, synonyms, relationships, then attachments (domain->table, secondary_tables).
 6. **Verify.** Re-traverse with `graphit kb explore domain <NAME>`, confirm counts match plan.
 
+## Query Governance and Reference Syntax
+
+Use KB references for governed queries:
+- `{{metric:NAME}}` - expands to metric calculation, e.g. `{{metric:CPI}}`
+- `{{metric:NAME(K=V)}}` - parameterized metric, e.g. `{{metric:ARPU(DAY=7)}}`
+- `{{dim:NAME}}` - expands to dimension expression
+- `{{metric_raw:NAME}}` - raw expression (no aggregate)
+
+**Parameterized metrics:** Some metrics require parameters (check `graphit kb list metric` - `params` column). Use `{{metric:ARPU(DAY=7)}}` to resolve `${PARAM:DAY}`. Pre-baked variants (ARPU_D7, ROAS_D30) need no parameters.
+
+```bash
+graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} as cpi FROM MARKETING_UA_DS GROUP BY 1" --ds ds_abc123
+graphit query "SELECT {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS" --ds ds_abc123  # parameterized
+graphit query "SELECT * FROM events" --ds ds_123 --override-rules EXCLUDE_RETARGETING   # bypass rule
+graphit governance status   # view mode and conformance
+graphit governance set warn # change mode (admin)
+graphit ds update <id> --governed-mode on  # enable governance on DS
+```
+
+Reference syntax in `graphit.resolve()` calls works the same way - server expands at query time. Trust tiers: **governed** (KB refs), **verified** (matches KB), **ad-hoc** (inline). Strict mode blocks ad-hoc on governed DSes.
+
 ## graphit.resolve() - Live Data API
 
 ```js
@@ -93,14 +151,27 @@ const result = await graphit.resolve({
 // Returns: { columns: string[], data: object[], rowCount: number, truncated: boolean }
 ```
 
-**Error handling:** Rejects on timeout (60s), bad SQL, or invalid data source ID. Wrap in try/catch.
+**Error handling:** Rejects on timeout (120s), bad SQL, or invalid data source ID. Wrap in try/catch.
+
+### First-paint loading state
+
+The HTML paints before the SDK connects, so bake a pure-CSS spinner overlay into the page; the SDK adopts it and removes it when that element's `graphit.resolve()` settles (success or error). Add once to the page `<style>`:
+
+```css
+@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}
+```
+
+Add the overlay inside EVERY element you pass as `target:` - and ONLY those elements (a static text/title section with no resolve call would spin forever). Keep the class names exactly as shown; they are the contract the SDK uses to adopt and remove the overlay. NEVER write text placeholders ("Loading...", "Fetching data...") - they never animate and make slow loads look stuck. See the canonical pattern below for the overlay markup.
 
 ### Runtime chart helpers
 
 | Helper | Usage |
 |---|---|
 | `graphit.chart(el, {type, data, x, y, ...})` | Bar, line, area, donut, scatter, stacked-bar, heatmap, funnel, gauge, sparkline |
-| `graphit.table(el, {data, columns?, ...})` | Styled HTML table |
+| `graphit.table(el, {data, columns?, maxRows?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects), defaults to `Object.keys(data[0])` |
 | `graphit.kpi(el, {value, label?, format?})` | KPI card with optional delta |
 
 `graphit.chart` types: `"bar"`, `"line"`, `"area"`, `"donut"` (alias `"pie"`), `"scatter"` (alias `"bubble"`), `"stacked-bar"` (alias `"stacked"`), `"heatmap"`, `"funnel"`, `"gauge"`, `"sparkline"`. Config: `x` (category field), `y` (value field), `series` (group-by), `title`, `height` (140-900px), `valueFormat` (`"currency"` | `"percent"` | `"number"`), `colors` (array). Scatter adds: `size`, `label`. Gauge adds: `min`, `max`, `format`. Sparkline adds: `width`, `showValue`.
@@ -110,15 +181,17 @@ const result = await graphit.resolve({
 ```html
 <div data-graphit-id="spend-by-source"
      data-graphit-label="Ad Spend by Source"
-     data-graphit-kb="metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA"
-     data-graphit-sql="SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA GROUP BY MEDIA_SOURCE ORDER BY spend DESC"
+     data-graphit-kb="metric:CPI,dimension:MEDIA_SOURCE,table:MARKETING_UA_DS"
+     data-graphit-sql="SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA_DS GROUP BY MEDIA_SOURCE ORDER BY spend DESC"
      data-graphit-ds="ds_abc123">
-  <div id="spend-chart"></div>
+  <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>
 </div>
 <script>
 (async function() {
   var r = await graphit.resolve({
-    sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA GROUP BY MEDIA_SOURCE ORDER BY spend DESC",
+    sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) as spend FROM MARKETING_UA_DS GROUP BY MEDIA_SOURCE ORDER BY spend DESC",
     dataSourceId: "ds_abc123",
     target: "#spend-chart"
   });

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

@@ -92,3 +92,27 @@ Before generating the HTML:
 - [ ] 3+ chart types for 4+ graphs
 - [ ] Every KPI has definition + baseline + direction
 - [ ] No anti-patterns present
+
+## Presenting Dashboard & Connector Results
+
+**After `graphit dashboard list`:**
+
+~~~
+**4 dashboards:**
+
+| Name | ID | URL |
+|---|---|---|
+| **UA Command Center** | dash_abc | https://app.graphit-app.com/custom-dashboard/dash_abc |
+| **Player Quality** | dash_def | https://app.graphit-app.com/custom-dashboard/dash_def |
+~~~
+
+**After `graphit connector list`:**
+
+~~~
+**2 connections:**
+
+| Name | Account | Auth |
+|---|---|---|
+| **prod-snowflake** | xy12345.us-east-1 | OAuth |
+| **staging-sf** | ab67890.us-east-1 | Keypair |
+~~~

package/skills/graphit/references/governance.md

@@ -0,0 +1,106 @@
+# Query Governance
+
+Server-side governance ensures consistent, auditable queries across all channels.
+
+## Reference Syntax
+
+Use KB references instead of inline formulas for governed queries:
+
+```sql
+-- Governed: server expands to KB-defined formulas
+SELECT {{dim:INSTALL_MONTH}}, {{metric:CPI}} as cpi
+FROM MARKETING_UA_DS
+GROUP BY 1
+
+-- Parameterized metric (ARPU requires DAY parameter)
+SELECT {{metric:ARPU(DAY=7)}} as arpu FROM MARKETING_UA_DS
+
+-- Raw expression (no outer aggregate)
+SELECT {{metric_raw:REVENUE}} FROM orders
+```
+
+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()`.
+
+**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
+
+| 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 |
+
+## Governance Modes
+
+| Mode | Behavior |
+|------|----------|
+| `observe` | All queries pass, tiers are tracked |
+| `warn` | Ad-hoc queries on governed DSes produce warnings |
+| `strict` | Ad-hoc queries on governed DSes are blocked |
+
+```bash
+graphit governance status     # View mode and conformance stats
+graphit governance set warn   # Change mode (admin only)
+graphit governance audit      # View audit log
+```
+
+## Enforceable Rules
+
+Rules with typed constraints are enforced automatically via SQL injection:
+
+| 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.
+
+## Override Flow
+
+```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
+
+```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
+```
+
+## Presenting Governance Results
+
+**After `graphit governance status`:**
+
+~~~
+**Governance mode:** strict
+
+**7-day conformance:**
+
+| Tier | Queries | Share |
+|---|---:|---:|
+| Governed | 847 | 72% |
+| Ad-hoc | 328 | 28% |
+| Blocked | 12 | 1% |
+
+5 active rules across 3 governed data sources.
+~~~
+
+**After governance errors:**
+
+~~~
+**Error:** Query 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.
+~~~

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

@@ -73,6 +73,12 @@ 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; }
@@ -112,6 +118,16 @@ 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>
+```
+
+Never write "Loading..." text placeholders - they don't animate and make slow loads look stuck.
 
 For inline chart implementations (bar, line, donut, heatmap, funnel, sparkline, gauge, stacked bar, multi-series), see `chart-patterns.md`.

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/sql-reference.md

@@ -111,6 +111,24 @@ 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
+
+**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
+
 ## Data Source Routing
 
 | Situation | Command | Speed |
@@ -119,3 +137,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.