@graphit/cli 0.1.30 → 0.1.38

package/skills/graphit/graphit.mdc

@@ -1,4 +1,5 @@
 ---
+skill_version: "0.1.38"
 alwaysApply: false
 description: "Build Graphit HTML dashboards with KB-aware queries, entity wrapping, and cached data sources"
 globs: []
@@ -8,6 +9,23 @@ globs: []
 
 Build custom HTML dashboards from real data using the Graphit CLI.
 
+## Session Start
+
+Run `graphit plugin status` at the start of every Graphit session and whenever the user asks about Graphit updates, plugin health, or stale instructions. This command is the source of truth for CLI, plugin-bundle, skill, ref, hook, and legacy copied-file version health; do not invent a manual version check.
+If it reports action needed, tell the user the exact remediation it prints before proceeding.
+
+## Install / Update Model
+
+The Graphit plugin bundle is the default and source of truth for Claude Code and Codex. It contains the CLI, skills, refs, hooks, status script, and manifests. Claude Code/Codex users should update Graphit through their assistant plugin manager, not by running copied-skill setup.
+
+`graphit setup` is only for legacy/fallback copied-file installs, mainly Cursor or environments without plugin support. If `graphit plugin status` reports Claude Code/Codex copied snapshots, tell the user to remove them with `graphit setup --remove-legacy-copies` after confirming the plugin is installed. Use `graphit setup --legacy-copy` only when the plugin path is unavailable.
+
+## CLI Health Gate
+
+ALWAYS run `graphit plugin status` before diagnosing, retrying, or inventing a workaround when Graphit CLI behavior looks wrong. This includes unknown commands, unrecognized flags, missing commands described in this rule, stale-looking output, copied-skill warnings, non-zero exits with unclear messages, or the user saying Graphit/CLI/plugin/skill is not working.
+If `graphit plugin status` reports action needed, stop and tell the user the exact remediation first. Do not continue with stale instructions unless the user explicitly asks you to proceed anyway.
+Do NOT suggest updating for normal operational failures (expired auth, bad SQL, entity not found).
+
 ## HARD CONSTRAINTS (violating these produces a broken dashboard)
 
 ### 1. ZERO external resources
@@ -18,14 +36,17 @@ Your HTML must NEVER contain:
 - `<img src="https://...">` - no external images
 
 If you use ANY `src=` or `href=` pointing to a URL, the dashboard will be blank.
-All CSS in `<style>`, all JS in `<script>`, all fonts from system stack. The iframe has a built-in runtime (`graphit.chart`, `graphit.table`, `graphit.kpi`) for standard visualizations - use it instead of importing libraries.
+All CSS in `<style>`, all JS in `<script>`, all fonts from system stack. The iframe has a built-in runtime (`graphit.chart`, `graphit.table`, `graphit.kpi`, `graphit.presentation`) for standard visualizations - use it instead of importing libraries.
 
 ### 2. ALWAYS query through data sources
 NEVER query the warehouse directly when a cached data source covers the table. Data sources return in ~100ms. Warehouse queries take ~10s and cost Snowflake credits.
 
-Run `graphit ds list` FIRST. If a DS covers your table, use `graphit query "SQL" --ds <id>`. Only use `--warehouse` if NO data source exists and the user approves.
+**Before writing ANY query:**
+1. Run `graphit ds list` to see what data sources exist
+2. If a DS covers your table, use `graphit query "SQL" --ds <id>` (DuckDB syntax)
+3. Only use `graphit query "SQL" --warehouse --connection <id>` 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.
+**Use the data source name in SQL** (e.g. `FROM MARKETING_UA_DS`), not the raw source table. The DS is a KB table - governance rules target it directly, and users recognize DS names from the platform.
 
 ### 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 FOUR attributes:
@@ -48,7 +69,7 @@ Without `data-graphit-*` attributes, elements are invisible to the platform. Eve
 
 KB asset references are derived automatically from `{{metric:X}}` / `{{dim:X}}` templates in your SQL.
 
-**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).
+**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. It MUST use the real DS table name and only columns that exist in the DS.
 
 **Label = visible title.** The `data-graphit-label` MUST match the card's visible heading exactly.
 
@@ -65,13 +86,63 @@ NEVER embed query results as static JS variables. The dashboard iframe provides
 **Wrong:** Embedding results as `const data = [{...}, ...]` in the HTML.
 **Right:** Using `graphit.resolve({sql, dataSourceId})` in a `<script>` block so data refreshes automatically.
 
+### 6. NEVER build a dashboard on ad-hoc SQL when KB assets are missing
+The KB-readiness gate in Workflow Step 4 is BLOCKING. When you check the KB and find it is missing metrics or dimensions the dashboard needs, you MUST create them before writing any HTML. Do not offer to skip. Do not ask "should I use ad-hoc SQL instead?" Do not frame it as the user's choice. The gate exists because ad-hoc SQL bypasses governance, breaks provenance, and produces untrustworthy graphs. The only question to ask is "here's my KB plan - approve?" not "should I follow my own instructions?"
+
+**Wrong:** "The KB has no metrics defined for caching performance. Should I build the dashboard with ad-hoc SQL or create KB assets first? Your call."
+**Right:** "The KB is missing 3 metrics this dashboard needs: RESULT_CACHE_HIT_RATE, DS_QUERY_LATENCY, QUERY_FAILURE_RATE. Creating them now - here's the plan: [tree]. Approve?"
+
+---
+
+## How to Work (governs both workflows below)
+
+You are a colleague building WITH the user, not a batch job that explores in silence and returns a finished product. Two habits make the difference: **short iterations** and **narration**.
+
+**Short iterations.** Do one thing, show it, let the user react, then do the next: explore the KB and report what you found; validate one query and show the rows; build one section and show it. Each small step is a cheap chance for the user to redirect before you have built in the wrong direction.
+
+**Always narrate.** The user cannot see your command output: the KB you listed, the SQL you ran, the rows that came back are invisible unless you surface them. After each step, say what you found, what it means, and what you are about to do next. Exception: if the user says "just build it" or "go", drop the commentary and work straight through.
+
+**Workflow gates are not optional.** When a step says BLOCKING or STOP, execute it. Do not offer to skip, do not say "your call", do not reframe it as optional. The KB-readiness gate (Step 4) is the most common one: if the KB is missing metrics or dimensions the dashboard needs, create them before writing HTML. The only question to ask is "here's my KB plan - approve?" not "should I follow the plan?"
+
+- **Wrong:** "The KB is empty. Should I skip KB creation and use ad-hoc SQL, or build assets first?"
+- **Right:** "The KB is empty. Here are the 7 metrics and 4 dimensions this dashboard needs: [tree]. Approve so I can create them?"
+
+The difference in practice:
+- **Weak (solo):** silently list the KB, silently run several queries, then save a complete dashboard and announce "Done."
+- **Strong (collaborative):** "Found a **Marketing UA** data source with `{{metric:CPI}}` and `{{metric:ROAS}}` already defined. Starting with a spend-vs-installs trend - querying now." Then, after showing rows: "Spend tracks installs except in March. Want that as the first graph, or should I look at ROAS first?"
+
+---
+
+## Workflow: Dashboard Build
+
+1. **Understand.** Ask what the dashboard should answer. Don't query until you know the goal - one clarifying question beats a wrong dashboard.
+2. **Scope to the domain, then work down: domain -> data source -> assets.** Start narrow, not broad. Ask the user which business domain this dashboard is about (or infer it and confirm). Then `graphit kb explore domain <NAME>` to see that domain's data sources and the metrics and dimensions defined on them. Reach for broad `graphit kb search` only as a fallback. Tell the user what you found - the data source, the metrics and dimensions you'll use, and the graphs you plan - before building.
+3. **Understand the business question.** Before touching SQL, apply the domain lenses to classify the user's goal. Match column names and user intent against the five lens detection signals (Marketing, Finance, Product/Growth, Operational, Sales). Once the lens is identified: check its canonical metrics and clarification questions. Ask at most ONE clarifying question using collaborative phrasing - state your assumption and offer to redirect. Map the user's goal to specific metric and dimension concepts the dashboard needs - name them. Show the user the concept list, then check it against the KB.
+4. **KB-readiness gate (BLOCKING).** Check the KB against the specific concepts from step 3 - not a vague "does the KB have stuff?" but "does the KB have the ROAS, CPI, and LTV:CAC that this marketing dashboard needs?" Show a compact gap table: which concepts exist (with formula) and which are missing. If covered, proceed to step 5. If missing key assets, STOP - do not build on raw ad-hoc SQL. Propose creating the assets, route to KB Build workflow first, return here after.
+5. **Pick the data source, and handle gaps.** Use the cached data source in that domain (~100ms); use its name in SQL (`FROM MARKETING_UA_DS`). If something is missing, look for relationships (`graphit kb list relationships`) before proposing a new data source.
+6. **Validate each query, and show the result.** Write SQL with `{{metric:NAME}}` / `{{dim:NAME}}` reference syntax, run with `--verbose`, and for EVERY query show the user: the reference-syntax query, a small markdown table of rows, the row count, and the trust tier. If zero rows or nulls, diagnose.
+7. **Get approval, then build.** Once the user is happy with data and plan, assemble the HTML: `graphit.resolve()` for live data, `graphit.chart/table/kpi` for rendering, every entity wrapped, all CSS in `<style>`, all JS in `<script>`. For large dashboards, add entities incrementally.
+8. **Save - prefer entity updates - then hand off.** New dashboard: `graphit dashboard update-html <id> --file <path>`. Existing: prefer `graphit dashboard update-entity <id> <entity_id>`. If `entity_sql_warnings` appear, fix and re-save. Give the user the dashboard URL.
+
+## Workflow: KB Build / Onboarding
+
+When the user wants to build or populate their KB from files, schemas, or scratch. Consult companion rules: graphit-kb-graph-structure (graph model), graphit-kb-traversal (tool selection), graphit-kb-actions (CLI commands), graphit-kb-awareness (when to propose assets), graphit-parameterized-metrics (template metrics), graphit-data-sources (shaping sources for speed).
+
+1. **Audit current KB state FIRST.** `graphit kb list domains`, then `graphit kb explore domain <NAME>` for each (returns full tree in one call). Add `graphit kb list synonyms` and `graphit kb list relationships` for globals. Present tree summary.
+2. **Analyze input.** Read the user's files/schema. Classify every concept by asset type (see graphit-kb-explanation for definitions, graphit-kb-awareness for signals).
+3. **Present a tree plan** showing Domain > Table > Topic > Asset hierarchy. Mark existing assets with (exists), new ones with **NEW**. Include global items (synonyms, relationships) at the bottom. Propose parameterized templates for variant metrics (D7/D30/D90).
+4. **Wait for approval.** Do not create anything until confirmed.
+5. **Execute top-down.** Create in order: domains, topics, metrics (with --topics), dimensions, rules, synonyms, relationships, then attachments (domain->table, secondary_tables). Each create validates against real data and returns sample results; if validation fails (422), fix the formula before retrying. Use `--skip-validate` for batch speed.
+6. **After each metric/dimension/rule create**, present the `validation` section: show the sample query, render sample data as a table, surface warnings. If validation was skipped, say why. If it failed (422), show the error and fix.
+7. **Verify.** Re-traverse with `graphit kb explore domain <NAME>`, confirm counts match plan.
+
 ---
 
 ## 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.
+**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, $, %). Narrate between steps.
 
 **After `graphit query`** - ground in KB, show five sections:
 1. **KB Assets:** bold names of all referenced metrics/dimensions/tables
@@ -81,48 +152,91 @@ You are the rendering layer - format and present every CLI result using markdown
 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 list`** - count summary + table with bold names
+**After `graphit kb get`** - entity heading + key-value table
 **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 ds create`** - shows creation progress (materializing -> scanning schema -> verification link). User must verify on the platform before the DS is usable in KB.
-**After `graphit ds verify <id>`** - scans schema (if not already scanned) and prints verification link. Use for existing unverified data sources.
-**After `graphit ds refresh --all`** - live status table showing each DS name, status (refreshing/ready/error), and row count. Suggest `--skip-empty` if many 0-row sources exist.
-**After `graphit governance status`** - mode + conformance table (Governed/Ad-hoc/Blocked with counts and %)
+**After `graphit ds create`** - shows creation progress (materializing -> scanning schema -> verification link)
+**After `graphit ds verify <id>`** - scans schema and prints verification link
+**After `graphit ds refresh --all`** - live status table showing each DS name, status, row count
+**After `graphit governance status`** - mode + conformance table
 **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
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `graphit auth login` | Authenticate with Graphit |
+| `graphit auth status` | Show current auth status |
+| `graphit auth logout` | Clear stored credentials |
+| `graphit plugin status` | Check plugin bundle, CLI, skill, refs, hooks, copied legacy files, and update health |
+| `graphit setup` | Legacy copied-file fallback for Cursor/non-plugin environments |
+| `graphit setup --remove-legacy-copies` | Remove old Claude Code/Codex copied snapshots so the plugin bundle is source of truth |
+| `graphit kb list <type>` | List entities: metric, dimension, table, rule, domain, synonym, template, relationship, topic |
+| `graphit kb get <type> <name>` | Full entity details by name |
+| `graphit kb search <query>` | Search across all KB types (optional `--type` filter) |
+| `graphit kb explore metric <name>` | Metric -> tables -> dimensions graph |
+| `graphit kb explore domain <name>` | Domain -> tables -> assets full tree (preferred starting point) |
+| `graphit kb create metric --name X --sql "..." --table T` | Create a metric (optional `--default-dimensions "D1,D2"`). Validates against real data; blocks on failure (422). Use `--skip-validate` to bypass. |
+| `graphit kb create dimension --name X --expr "..." --table T` | Create a dimension (type auto-inferred; override with `--type` / `--output-type`). Validates; shows cardinality + NULL rate. |
+| `graphit kb create rule --name X --sql "..." --table T` | Create a rule. Validates as WHERE clause; warns if zero rows match. |
+| `graphit kb create synonym --term X --canonical Y --type metric` | Create a synonym (type: metric, column, table) |
+| `graphit kb create domain --name X` | Create a domain (optional `--color "#hex"`) |
+| `graphit kb create relationship --name X --primary-table T --primary-column C --related-table T2 --related-column C2` | Create a JOIN relationship |
+| `graphit kb create topic --name X` | Create a topic (business-concept tag) |
+| `graphit kb create template --name X --file template.html` | Save a reusable chart template (--file or --render-code) |
+| `graphit kb update metric NAME --topics "A,B"` | Attach topics to a metric (also works on dimension, rule) |
+| `graphit kb update metric NAME --default-dimensions "D1,D2"` | Set default grouping dimensions for a metric |
+| `graphit kb update metric NAME --secondary-tables "T1,T2"` | Reference metric onto additional tables (also dimension, rule) |
+| `graphit kb update metric NAME --parameters '<json>'` | Set parameterized metric template (JSON array, or `--parameters-file`) |
+| `graphit kb update table NAME --domain DOMAIN` | Assign domain to table (cascades to all assets on table) |
+| `graphit kb update domain NAME --color "#hex"` | Update domain color |
+| `graphit kb update synonym TERM --canonical Y` | Update synonym target |
+| `graphit kb update relationship NAME --primary-column C` | Update relationship columns |
+| `graphit kb update topic NAME --description "..."` | Update topic description |
+| `graphit kb update template NAME --file template.html` | Update template render code |
+| `graphit kb update <type> <name> --description "..."` | Update description (all types) |
+| `graphit kb delete <type> <name> --yes` | Delete any entity (all types supported) |
+| `graphit ds list` | List cached data sources (use these for fast queries) |
+| `graphit ds create --name "..." --sql "..."` | Create DS, poll until ready, auto-scan schema, print verification link |
+| `graphit ds create --name "..." --sql "..." --skip-scan` | Create DS without auto-scan |
+| `graphit ds verify <id>` | Scan schema and print verification link for an unverified DS |
+| `graphit ds refresh --all` | Refresh all data sources, wait for completion with live status |
+| `graphit ds refresh --all --skip-empty` | Refresh non-empty data sources only |
+| `graphit ds refresh --all --no-wait` | Trigger all refreshes without waiting |
+| `graphit ds refresh <id> [id2...]` | Refresh one or more data sources by ID |
+| `graphit ds update <id> --governed-mode on\|off` | Enable/disable governed mode on a data source |
+| `graphit ds update <id> --max-rows N` | Set max rows cap on a data source |
+| `graphit query "<sql>" --ds <id>` | Query cached data source (~100ms) |
+| `graphit query "<sql>" --ds <id> --override-rules RULE1 RULE2` | Query with governance rule overrides |
+| `graphit query "<sql>" --ds <id> --verbose` | Show expanded SQL and trust tier |
+| `graphit query "<sql>" --warehouse --connection <id>` | Query live Snowflake (~10s) |
+| `graphit governance status` | Show governance mode and conformance stats |
+| `graphit governance set <mode>` | Set governance mode (observe/warn/strict) |
+| `graphit governance audit` | View recent governance audit events |
+| `graphit dashboard create --name "..."` | Create dashboard (returns ID) |
+| `graphit dashboard get-html <id>` | Get current HTML content of a dashboard |
+| `graphit dashboard update-html <id> --file <path>` | Upload HTML to dashboard (full page replace) |
+| `graphit dashboard update-entity <id> <entity_id> --file <path>` | Update a single entity's inner HTML (optional `--title`, `--stdin`) |
+| `graphit dashboard list` | List dashboards with sharing metadata (permission, visibility, teams, is_locked) |
+| `graphit dashboard list --view mine` | Only dashboards you own |
+| `graphit dashboard list --view shared` | Only dashboards shared with you |
+| `graphit dashboard list --team <id>` | Only dashboards shared with a specific team |
+| `graphit team list` | List teams you belong to (org admins see all) |
+| `graphit dashboard export <id>` | Export as PNG (default) or PDF (`--format pdf`, `--output <path>`). Presentations auto-export as multi-page PDF. Custom multi-page: `data-graphit-page="N"` (0-indexed). |
+| `graphit metadata schemas --connection <id>` | List Snowflake schemas |
+| `graphit metadata tables --schema <name> --connection <id>` | List tables in a Snowflake schema |
+| `graphit connector list` | List active connections |
+| `graphit connector add snowflake-keypair --account X --user Y --key <path> --warehouse W` | Add Snowflake keypair connection (admin only). OAuth and GitHub connections are configured via the web app. |
+| `graphit connector test <id>` | Test a connection |
+| `graphit connector remove <id> --yes` | Remove a connection (admin only) |
 
-1. **Ask the user** what dashboard they want.
-2. **Explore KB** to understand available metrics, dimensions, tables, and rules.
-3. **Find a data source** (`graphit ds list`) - prefer cached data sources over live warehouse.
-4. **Query data to validate** - run queries via the CLI to verify SQL and preview results.
-5. **Build HTML** - write `graphit.resolve()` calls for live data + `graphit.chart/table/kpi` for rendering. All CSS in `<style>`, all JS in `<script>`.
-6. **Save** with `graphit dashboard update-html <id> --file <path>`. If the response contains `entity_sql_warnings`, an entity's `data-graphit-sql` is missing, matches no data source, or fails against the DS schema - fix the flagged entities and save again before finishing.
-7. Give the user the dashboard URL.
-8. **Export** with `graphit dashboard export <id> --format pdf`. Presentations export as multi-page PDF automatically. For custom multi-page layouts, add `data-graphit-page="N"` (0-indexed) to each section.
-
-## Workflow: KB Build / Onboarding
-
-When the user wants to build or populate their KB from files, schemas, or scratch. Consult companion rules: graphit-kb-graph-structure (graph model), graphit-kb-traversal (tool selection), graphit-kb-actions (CLI commands), graphit-kb-awareness (when to propose assets), graphit-parameterized-metrics (template metrics), graphit-data-sources (shaping sources for speed: pre-aggregate to grain, narrow columns, keep high-cardinality dimensions out of the base).
-
-1. **Audit current KB state FIRST.** Traverse, don't just list: `graphit kb list domains`, then `graphit kb explore domain <NAME>` for each (returns full tree in one call). Add `graphit kb list synonyms` and `graphit kb list relationships` for globals. Present tree summary.
-2. **Analyze input.** Read the user's files/schema. Classify every concept by asset type (see graphit-kb-explanation for definitions, graphit-kb-awareness for signals).
-3. **Present a tree plan** showing Domain > Table > Topic > Asset hierarchy. Mark existing assets with (exists), new ones with **NEW**. Include global items (synonyms, relationships) at the bottom. Propose parameterized templates for variant metrics (D7/D30/D90).
-4. **Wait for approval.** Do not create anything until confirmed.
-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
 
@@ -145,6 +259,8 @@ 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
@@ -163,7 +279,7 @@ const result = await graphit.resolve({
 
 ### 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>`:
+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. Add once to the page `<style>`:
 
 ```css
 @keyframes gh-spin{to{transform:rotate(360deg)}}
@@ -172,17 +288,21 @@ The HTML paints before the SDK connects, so bake a pure-CSS spinner overlay into
 .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.
+Add the overlay inside EVERY element you pass as `target:` - and ONLY those elements. Keep the class names exactly as shown; they are the contract the SDK uses. NEVER write text placeholders ("Loading...") - 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?, 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(el, {type, data, x, y, ...})` | Bar, horizontal-bar, line, area, donut, scatter, stacked-bar, heatmap, funnel, gauge, sparkline |
+| `graphit.table(el, {data, columns?, maxRows?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects) |
+| `graphit.kpi(el, {value, label?, format?})` | KPI card with optional delta (`compareValue`, `compareLabel`) |
+| `graphit.presentation(el)` | Full-screen slide deck. Returns builder: `.slide({bg, layout, html})` then `.start()`. See graphit-presentations rule. |
+| `graphit.filter(id, {label, field?, default?})` | Headless filter (zero DOM). Returns `{get, set, subscribe}` handle. See graphit-filters rule. |
+| `graphit.param(id, {label, default?, options?})` | Headless parameter (zero DOM). Same handle API. |
+| `graphit.bind(el, {sql, dataSourceId, params, deps?, render})` | Auto re-resolve on filter/param change. See graphit-filters rule. |
 
-`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`.
+`graphit.chart` types: `"bar"`, `"horizontal-bar"` (alias `"hbar"`), `"line"`, `"area"`, `"donut"` (alias `"pie"`), `"scatter"` (alias `"bubble"`), `"stacked-bar"` (alias `"stacked"`), `"heatmap"`, `"funnel"`, `"gauge"`, `"sparkline"`. Config: `x`, `y`, `series`, `title`, `height` (140-900px), `valueFormat` (`"currency"` | `"percent"` | `"number"`), `colors`. Dual axis (bar/line/area): `y2`, `y2Format`, `y2Label`; `y2` and `series` are mutually exclusive. Scatter adds: `size`, `label`. Gauge: `min`, `max`, `format`. Sparkline: `width`, `showValue`.
 
 ### Canonical pattern - entity with live data
 
@@ -210,4 +330,4 @@ Add the overlay inside EVERY element you pass as `target:` - and ONLY those elem
 </script>
 ```
 
-For detailed chart selection logic, dashboard planning, SQL reference, domain-specific lenses, Graphit visual style, and chart pattern implementations, see the companion rule files (graphit-planning, graphit-sql, graphit-lenses, graphit-style, graphit-kb, graphit-patterns).
+For detailed chart selection, dashboard planning, SQL reference, domain lenses, visual style, KB structure, chart patterns, governance, presentations, filters, and data source shaping, see the companion rule files.

package/skills/graphit/references/filters.md

@@ -0,0 +1,127 @@
+# Headless Filters, Parameters, and Saved Views
+
+## 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.
+
+## graphit.filter(id, options)
+
+Register a named filter. Returns a handle for reading, writing, and subscribing to value changes.
+
+```js
+const country = graphit.filter('country', {
+  label: 'Country',       // display label (used in saved view UI)
+  field: 'COUNTRY',       // metadata for the platform (optional)
+  default: 'US',          // initial value if no saved view overrides it
+})
+```
+
+Handle API:
+- `country.get()` - current value
+- `country.set(value)` - update value (triggers subscribers + bound re-resolves)
+- `country.subscribe(cb)` - called on change; returns unsubscribe fn
+
+## 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.
+
+```js
+const topN = graphit.param('top_n', { label: 'Top N', default: 10, options: [5, 10, 20, 50] })
+```
+
+## 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>
+```
+
+## graphit.bind(el, options) - Reactive Data Binding
+
+Connects a data entity to filter dependencies so it re-resolves automatically on change.
+
+```js
+graphit.bind(document.getElementById('revenue-chart'), {
+  sql: 'SELECT date, SUM(revenue) AS revenue FROM orders WHERE country = :country GROUP BY 1',
+  dataSourceId: 'ds_abc123',
+  params: () => ({ country: graphit.state.get('country') }),
+  deps: ['country'],      // state keys that trigger re-resolve (inferred from params if omitted)
+  render: (result, el) => {
+    graphit.chart(el, { type: 'line', data: result.data, x: 'date', y: 'revenue' });
+  }
+});
+```
+
+- Runs once immediately, then re-runs on any dep change
+- 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
+
+## Safe Parameter Binding (`:name` syntax)
+
+Use `:name` placeholders in SQL for safe server-side parameter binding. Never string-concatenate user values into SQL.
+
+| Shape | SQL | Params |
+|-------|-----|--------|
+| Scalar | `WHERE country = :country` | `{country: 'US'}` |
+| Multi-select | `WHERE country IN :countries` | `{countries: ['US', 'IL']}` (expands to safe `IN ($0, $1)`) |
+| Date range | `WHERE date BETWEEN :from AND :to` | `{from: '2026-01-01', to: '2026-06-01'}` |
+
+Array length capped at 200 elements, max 50 param keys per resolve call.
+
+## Saved Views
+
+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.
+
+## Complete Example
+
+```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>
+
+<script>
+  const region = graphit.filter('region', { label: 'Region', field: 'REGION', default: 'ALL' });
+
+  const sel = document.getElementById('region-select');
+  sel.value = region.get();
+  sel.onchange = () => region.set(sel.value);
+  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`,
+    dataSourceId: 'ds_sales',
+    params: () => region.get() !== 'ALL' ? { region: region.get() } : {},
+    deps: ['region'],
+    render: (result, el) => {
+      graphit.chart(el, { type: 'area', data: result.data, x: 'month', y: 'revenue', valueFormat: 'currency' });
+    }
+  });
+</script>
+```

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

@@ -6,14 +6,52 @@ Every KB asset has full create / update / delete through the `graphit kb` comman
 
 | Asset | Command |
 |---|---|
-| Metric | `graphit kb create metric --name X --sql "<expr>" --table T` (optional `--topics "A,B"`, `--default-dimensions "D1,D2"`) |
-| Dimension | `graphit kb create dimension --name X --expr "<expr>" --table T` (type auto-inferred; override with `--type` / `--output-type`) |
-| Rule | `graphit kb create rule --name X --sql "<text>" --table T` (optional `--apply-on table:USERS metric:ARPU`) |
+| Metric | `graphit kb create metric --name X --sql "<expr>" --table T` (optional `--topics "A,B"`, `--default-dimensions "D1,D2"`, `--skip-validate`) |
+| Dimension | `graphit kb create dimension --name X --expr "<expr>" --table T` (type auto-inferred; override with `--type` / `--output-type`, `--skip-validate`) |
+| Rule | `graphit kb create rule --name X --sql "<text>" --table T` (optional `--apply-on table:USERS metric:ARPU`, `--skip-validate`) |
 | Synonym | `graphit kb create synonym --term X --canonical Y --type metric` |
 | Domain | `graphit kb create domain --name X` (optional `--color "#4DB6AC"`) |
 | Topic | `graphit kb create topic --name X` |
 | Relationship | `graphit kb create relationship --name X --primary-table T --primary-column C --related-table T2 --related-column C2` |
 
+## Pre-Creation Validation
+
+Metric, dimension, and rule creates validate the formula against real data before writing to Firestore. On success, the response includes sample results. On failure, creation is blocked with a 422 error showing the failing query.
+
+- **Metric**: runs `SELECT {formula} FROM {table} GROUP BY {default_dims} LIMIT 5`
+- **Dimension**: runs `SELECT {expr} AS val, COUNT(*) AS cnt FROM {table} GROUP BY 1 ORDER BY cnt DESC LIMIT 10` (reports cardinality, NULL rate)
+- **Rule**: runs `SELECT COUNT(*) FROM {table} WHERE {rule}` (warns if zero rows match)
+
+Skip conditions (validation returns "skipped", asset still created):
+- Template metrics with `${PARAM:X}` placeholders
+- Constraint-based rules (non-empty `--constraint`)
+- Table has no data source and no Snowflake connections
+- Data source mid-refresh or unverified
+
+Use `--skip-validate` on any create command to bypass validation entirely (useful for batch creation where speed matters more than per-asset checks).
+
+### Presenting validation results to the user
+
+The JSON response from every metric/dimension/rule create includes a `validation` object. You MUST present it to the user after each create:
+
+```
+validation: {
+  status: "pass" | "fail" | "skipped",
+  sample_query: "SELECT ...",        // the SQL that ran
+  sample_data: [{...}, ...],         // rows from real data
+  sample_columns: ["col1", "col2"],  // column names
+  warnings: ["..."],                 // quality warnings
+  skip_reason: "...",                // why validation was skipped
+}
+```
+
+How to present each status:
+- **pass**: render `sample_data` as a markdown table using `sample_columns` as headers. For metrics, this shows computed values. For dimensions, this shows top values with row counts. For rules, this shows the matching row count. Surface any `warnings` below the table.
+- **skipped**: tell the user validation was skipped and quote the `skip_reason`.
+- **fail** (HTTP 422, create was blocked): show the error message and `sample_query`. The asset was NOT created. Fix the formula and retry.
+
+Never silently swallow validation results. The user needs to see that their formula actually works against real data.
+
 ## Update and Delete
 
 - Update a field: `graphit kb update <type> NAME --<field> value` (e.g. `--sql`, `--expr`, `--description`, `--table`).