@graphit/cli 0.1.18 → 0.1.21

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

@@ -1,99 +1,46 @@
-# KB Actions - CLI Parity Matrix
+# KB Actions (CLI)
 
-Every KB action has a CLI equivalent. The tool syntax below maps to CLI commands:
+Every KB asset has full create / update / delete through the `graphit kb` commands - this is the authoring reference. SKILL.md's command table is the quick glance; this file adds the create flags and the task recipes that take more than one command. All names are UPPER_SNAKE_CASE.
 
-| Agent Tool Syntax | CLI Command |
+## Create
+
+| Asset | Command |
 |---|---|
-| `create(entity_type="metric", name=..., calculation=...)` | `graphit kb create metric --name X --sql "..." --table T` (optional `--default-dimensions "D1,D2"`) |
-| `create(entity_type="dimension", name=..., expression=...)` | `graphit kb create dimension --name X --expr "..." --table T` (type auto-inferred; override with `--type` / `--output-type`) |
-| `create(entity_type="rule", name=..., rule_text=...)` | `graphit kb create rule --name X --sql "..." --table T` |
-| `create(entity_type="synonym", term=..., canonical=...)` | `graphit kb create synonym --term X --canonical Y --type metric` |
-| `create(entity_type="domain", name=...)` | `graphit kb create domain --name X --description "..."` |
-| `create(entity_type="relationship", ...)` | `graphit kb create relationship --name X --primary-table T --primary-column C --related-table T2 --related-column C2` |
-| `create(entity_type="topic_metadata", name=...)` | `graphit kb create topic --name X --description "..."` |
-| `edit(entity_type=..., id=..., field=value)` | `graphit kb update <type> NAME --field value` |
-| `edit(entity_type="table", id=..., domain_id=...)` | `graphit kb update table NAME --domain DOMAIN` |
-| `edit(entity_type="metric", id=..., secondary_tables=[...])` | `graphit kb update metric NAME --secondary-tables "TABLE1,TABLE2"` |
-| `edit(entity_type="metric", id=..., default_dimensions=[...])` | `graphit kb update metric NAME --default-dimensions "D1,D2"` |
-| `edit(entity_type="metric", id=..., topics=[...])` | `graphit kb update metric NAME --topics "TOPIC1,TOPIC2"` |
-| `edit(entity_type="metric", id=..., parameters=[...])` | `graphit kb update metric NAME --parameters '<json>' --parameters-file params.json` |
-| `delete(entity_type=..., id=...)` | `graphit kb delete <type> NAME --yes` |
-| `search(query="...")` | `graphit kb search "query"` |
-| `list(entity_type="domain")` | `graphit kb list domains` |
-| `read(entity_type="metric", name=...)` | `graphit kb get metric NAME` |
-| `kb_explore(entity_type="table", entity_name="X")` | `graphit kb explore table X` |
-
-Full CRUD parity: all agent actions have CLI equivalents.
-
-## Asset CRUD
-
-| UI Action | Agent Tool Path |
-|-----------|----------------|
-| Create metric | `create(entity_type="metric", name=..., calculation=..., dependencies=...)` |
-| Create dimension | `create(entity_type="dimension", name=..., table_name=..., expression=...)` |
-| Create rule | `create(entity_type="rule", name=..., rule_text=...)` |
-| Create synonym | `create(entity_type="synonym", term=..., canonical=..., canonical_type=...)` |
-| Create relationship | `create(entity_type="relationship", primary_table=..., primary_column=..., related_table=..., related_column=...)` |
-| Edit any asset | `edit(entity_type=..., id=..., field=new_value)` |
-| Delete any asset | `delete(entity_type=..., id=...)` |
-| Toggle verified | `edit(entity_type=..., id=..., verified=true/false)` |
-
-## Topic Management
-
-| UI Action | Agent Tool Path |
-|-----------|----------------|
-| Create topic | `create(entity_type="topic_metadata", name=..., description=...)` |
-| Edit topic description | `edit(entity_type="topic_metadata", id=..., description=...)` |
-| Delete topic metadata | `delete(entity_type="topic_metadata", id=...)` |
-| Toggle topic verified | `edit(entity_type="topic_metadata", id=..., verified=true/false)` |
-| Add topic to asset | `edit(entity_type="metric", id=..., topics=[...existing, "NEW_TOPIC"])` - append to existing list |
-| Remove topic from asset | `edit(entity_type="metric", id=..., topics=[...without removed])` - filter out the topic |
-| Move asset between topics | `edit(entity_type="metric", id=..., topics=["NEW_TOPIC"])` - replace the list |
-| Rename topic (cascade) | `edit(entity_type="topic_metadata", id=..., name=...)` then batch `edit` on each asset that references the old name |
-| Bulk reassign topics | Present plan via `ask_user`, then execute N `edit` calls on approval |
-
-## Domain Management
-
-| UI Action | Agent Tool Path |
-|-----------|----------------|
-| Create domain | `create(entity_type="domain", name=..., description=..., color=...)` |
-| Edit domain | `edit(entity_type="domain", id=..., description=..., color=...)` |
-| Delete domain | `delete(entity_type="domain", id=...)` |
-
-## Domain Assignment (Cascade Model)
-
-Domain is a single **home** set on the table; every asset on that table inherits it. Assets never store their own home domain - set it on the table, not the asset.
-
-| UI Action | Agent Tool Path |
-|-----------|----------------|
-| Set a table's home domain | `edit(entity_type="table", id=..., domain_id="MARKETING")` - cascades to every asset on that table |
-| Clear a table's home domain | `edit(entity_type="table", id=..., domain_id=None)` - its assets fall back to Uncategorized |
-| Reference asset onto another table | `edit(entity_type="metric", id=..., secondary_tables=["OTHER_TABLE"])` - appears under the target table as a read-only pointer (marked with `*`). Metrics/dimensions require identical columns; rules require only target existence. |
-| Remove a table reference | `edit(entity_type="metric", id=..., secondary_tables=[...without removed])` |
-| Mark a synonym cross-cutting to extra domains | `edit(entity_type="synonym", id=..., extra_domain_ids=["FINANCE"])` - adds badges + filter match, does NOT move it in the tree |
-| Remove cross-cutting domains from synonym | `edit(entity_type="synonym", id=..., extra_domain_ids=[])` |
-
-A table-backed asset's (metric, dimension, rule) domain is derived from its dependency tables plus any `secondary_tables`. A synonym can also carry `extra_domain_ids` for cross-cutting relevance. To re-home a whole table of assets, change `domain_id` on the table once - do not edit assets individually.
-
-## Navigation and Discovery
-
-| UI Action | Agent Tool Path |
-|-----------|----------------|
-| Search KB | `search(query="...", types=[...])` |
-| Filter by topic | `search(query="...", topics=["REVENUE"])` |
-| Filter by domain | `search(query="...", domain="MARKETING")` - matches assets whose dependency or secondary tables are in the MARKETING domain. Synonyms also match via `extra_domain_ids`. |
-| List all domains | `list(entity_type="domain")` - returns every domain with name, description, color, and asset_count; includes an "Uncategorized" entry when tables with no domain exist. Report every domain it returns; do not drop ones with asset_count=0, and do not use `search` or `kb_explore` |
-| List all tables | `list(entity_type="table")` - returns every table with name, domain_id (null if uncategorized), and verified status. Use to see which tables are assigned to which domain, or to find uncategorized tables |
-| Browse by table | `search(query="...", types=["metric", "dimension"])` then filter results by table |
-| What depends on X? | `kb_explore(entity_type="table", entity_name="X", edge_types=["depends_on"])` |
-| What joins with table? | `kb_explore(entity_type="table", entity_name="X", edge_types=["joins"])` |
-| What's in topic X? | `kb_explore(entity_type="topic", entity_name="X", edge_types=["tagged_with"])` |
-| What's in domain X? | `kb_explore(entity_type="domain", entity_name="X")` |
-
-## View Controls (UI-Only, No Agent Parity Needed)
-
-These actions are purely UI navigation state and have no agent equivalent:
-- Switch view mode (Tree / By Topic / By Table / Flat)
-- Filter dropdowns (domain, table, topic, type, verified-only)
-- Expand/collapse tree nodes
-- Drag-drop asset onto topic (maps to "Add topic to asset" above)
+| 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`) |
+| 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` |
+
+## Update and Delete
+
+- Update a field: `graphit kb update <type> NAME --<field> value` (e.g. `--sql`, `--expr`, `--description`, `--table`).
+- Delete: `graphit kb delete <type> NAME --yes`.
+
+## Topic and Reference Recipes (lists REPLACE, so don't clobber)
+
+`--topics`, `--secondary-tables`, and `--default-dimensions` replace the existing list, they do not append. To change one value without losing the others, read the current list first, then write the full intended list:
+
+- **Add a topic**: `graphit kb get metric NAME` to read current topics, then `graphit kb update metric NAME --topics "EXISTING1,EXISTING2,NEW"`.
+- **Remove a topic**: update with the list minus the one removed.
+- **Reference an asset onto another table**: `graphit kb update metric NAME --secondary-tables "OTHER_TABLE"` (works on dimension and rule too). Read-only pointer marked `*`; metrics and dimensions need every referenced column to exist on the target, rules need only the table to exist.
+
+Topics are horizontal - one topic can tag assets across many domains (see `kb-structure.md`).
+
+## Domain Recipes (the home is on the table and cascades)
+
+Domain is set on the TABLE, never per asset, and cascades to every asset on it (see `kb-structure.md` for the model):
+
+- **Re-home a whole table**: `graphit kb update table NAME --domain MARKETING` - moves every asset on that table at once. Change it once on the table, never asset by asset.
+
+## Navigation
+
+To find what exists and how it connects (what depends on a table, what joins, what is in a domain or topic), use the traversal recipes in `kb-traversal.md`. Note: `graphit kb list domains` reports every domain including empty ones - report them all, do not drop ones with a zero asset count.
+
+## UI-Only (no CLI command)
+
+These are platform-UI state or platform-only, not KB data the CLI changes:
+- View mode (Tree / By Topic / By Table / Flat), filter dropdowns, expand / collapse, drag-drop onto a topic.
+- Cross-cutting synonym domains (extra relevance beyond the home domain) are set in the platform UI - there is no CLI flag for them yet.

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

@@ -0,0 +1,78 @@
+# KB Discovery
+
+Consult when starting a dashboard build, or when the user references a business concept that might already exist as a KB asset. The Knowledge Base holds reusable metrics, dimensions, rules, and table schemas - using them keeps formulas consistent across dashboards and makes each new graph faster to build.
+
+## Domain-First Discovery
+
+Work narrow, not broad: **domain -> data source -> assets.** Listing or searching everything is the fallback, not the default.
+
+1. **Scope to the domain.** Ask the user which business area this is about, or infer it and confirm. `graphit kb list domains` shows the groupings (MARKETING, PRODUCT, FINANCE, etc.) if you need to pick one.
+2. **Explore that domain.** `graphit kb explore domain <NAME>` returns the domain's data sources plus the metrics, dimensions, and rules defined on them, in one traversal. This is your working set.
+3. **Reuse the assets.** If a metric fits, read its formula with `graphit kb get metric REVENUE` and reference it by name in SQL as `{{metric:REVENUE}}`.
+4. **Handle gaps.** If the domain's data source is missing something, check `graphit kb list relationships` for a connection to another data source you can join; if the data genuinely does not exist, propose creating the asset or a new data source (see below).
+5. **Broaden only if needed.** Use `graphit kb search "<concept>"` when the domain is unclear or a concept spans domains.
+
+If a domain has tables but no metrics or dimensions, that is the strongest signal to propose foundational assets before building any graph. If the user declines ("just build it", "skip KB"), respect it and work from the table schema.
+
+## Metric vs Dimension
+
+| Property | Metric | Dimension |
+|---|---|---|
+| Formula | Aggregation required (SUM, COUNT, AVG, MIN, MAX) | Row-level only (no aggregates) |
+| Table scope | Can reference multiple tables | Exactly one table |
+| Purpose | Measures - what you count or sum | Grouping axes - how you slice |
+| Example | `SUM(ORDERS.AMOUNT)` | `DATE_TRUNC('month', EVENTS.EVENT_TS)` |
+| Invalid | `ORDERS.AMOUNT` (no aggregate) | `SUM(EVENTS.DURATION)` (has aggregate) |
+
+## When to Propose KB Asset Creation
+
+| Signal | Propose | Why |
+|---|---|---|
+| User requests a business metric (revenue, DAU, conversion rate) with no KB match | Metric | Reusable formula across dashboards |
+| User groups by a derived expression (date bucket, category mapping, JSON extraction) | Dimension | Consistent grouping logic |
+| User describes a business rule ("active = logged in within 30 days") | Rule | Applied automatically to future queries |
+| User uses a business term not in KB ("GMV", "churn", "ARPU") | Synonym | Maps colloquial terms to a defined metric |
+
+Propose creation as the default path, in plain language: "Your KB doesn't have a revenue metric yet. I'd recommend creating one first - then it's reusable across every dashboard with a consistent formula, and I'll build the graph using it. Sound good?"
+
+## Naming Conventions
+
+All KB assets are UPPER_SNAKE_CASE (auto-sanitized on write):
+
+| Pattern | Example | Use when |
+|---|---|---|
+| `TOTAL_*` | `TOTAL_REVENUE`, `TOTAL_ORDERS` | Sum aggregations |
+| `AVG_*` | `AVG_ORDER_VALUE` | Average metrics |
+| `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
+| `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios / percentages |
+
+## Formula Syntax
+
+Metrics reference `TABLE.COLUMN` with UPPERCASE naming:
+
+```sql
+-- Metric formulas (aggregation required)
+SUM(ORDERS.AMOUNT)
+COUNT(DISTINCT EVENTS.USER_ID) WHERE EVENTS.EVENT_TS >= DATEADD(day, -30, CURRENT_DATE)
+SUM(ORDERS.REVENUE) / NULLIF(SUM(ORDERS.COST), 0)
+
+-- Dimension formulas (no aggregates)
+EVENTS.PLATFORM
+DATE_TRUNC('month', EVENTS.EVENT_TS)
+CASE WHEN USERS.AGE >= 18 THEN 'adult' ELSE 'minor' END
+```
+
+Use CASE WHEN for conditionals (Snowflake has no FILTER WHERE). Always guard division with NULLIF.
+
+When creating assets, pass `--topics` to tag the business concept (e.g. `--topics "ACQUISITION"`; check existing topic names first), and `--default-dimensions` on a metric to declare its natural grouping axes. Dimension `output_type` / `semantic_type` are auto-inferred from the column schema - override with `--type` / `--output-type` only when the inference is wrong (e.g. a CASE expression that outputs a category from a numeric column). Full command reference: `kb-actions.md`.
+
+## Reuse Over Reinvention
+
+When a dashboard has several graphs sharing a concept, propose ONE KB asset instead of repeating the formula:
+
+- 3 graphs all using `SUM(ORDERS.AMOUNT)` -> one `TOTAL_REVENUE` metric.
+- 2 graphs grouping by `DATE_TRUNC('month', TS)` -> one `MONTHLY` dimension.
+
+For the same concept on a sibling table with identical columns, **reference** it rather than duplicating: `graphit kb update metric TOTAL_REVENUE --secondary-tables "ORDERS_12M"`. This is a pointer, not a copy - edits propagate to all placements, and referenced placements show a `*` in the KB tree. Metrics and dimensions require every referenced column to exist on the target table (checked on save); rules only require the table to exist. Suggest it when the user has sibling sources (e.g. 6M and 12M windows) or asks to "make X available on Y".
+
+For the KB graph model and structural questions (the vertical domain -> DS -> assets home vs horizontal topics, why assets appear where they do), see `kb-structure.md`; for graph-traversal queries, see `kb-traversal.md`. For the full create / update / delete command matrix, see `kb-actions.md`.

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

@@ -0,0 +1,64 @@
+# KB Structure
+
+How the Knowledge Base is organized, and how to answer structural questions about it. The KB is a labeled property graph: assets carry tags that place them in a tree, but the underlying structure is a graph with typed edges. Answer structural questions in business-friendly language, grounded in actual KB state (verify with `graphit kb get` / `graphit kb explore` when the question names a specific asset).
+
+## Node Types
+
+| Type | Description |
+|------|-------------|
+| metric | Aggregation formula (SUM, COUNT, AVG) that computes a business KPI |
+| dimension | Row-level SQL expression on one table, used for grouping or filtering |
+| rule | Free-text business constraint, optionally scoped to one or more tables |
+| synonym | Maps a business term to a canonical metric, dimension, or column |
+| table | Physical data location in the warehouse, with typed columns |
+| topic | Business-concept tag applied to assets (e.g., REVENUE, ACQUISITION) |
+| domain | High-level business area (e.g., MARKETING, SALES, PRODUCT) |
+| relationship | Documented JOIN pattern between two tables |
+| memory | Org-level context notes, always global scope |
+
+## Edge Types
+
+| Edge | From | To | Meaning |
+|------|------|----|---------|
+| depends_on | metric, dimension | table | Asset's SQL references columns in this table |
+| tagged_with | metric, dimension, rule, synonym | topic | Asset carries this business-concept tag |
+| in_domain | table, metric, dimension, rule, synonym | domain | A table has one home domain; assets inherit it from their primary table, plus any cross-cutting extras |
+| joins | relationship | table, table | Two tables have a documented JOIN on specific columns |
+| references | rule, synonym | table, column | Rule or synonym references a specific table or column name |
+
+## How Membership Works
+
+Two different axes organize the KB - keep them separate:
+
+- **Vertical: the home (domain -> data source -> assets).** This is containment, and it cascades. An asset has ONE home domain, inherited from its primary table (the data source its SQL reads). You set the domain on the **table** - `graphit kb update table NAME --domain MARKETING` - and every asset on that table inherits it; the asset carries no domain tag of its own. To move an asset's home, change its table's domain. Domain-first discovery walks this axis downward.
+- **Horizontal: the concept (topics).** Topics cut ACROSS domains. The same topic (e.g., RETENTION) can tag assets that live in different domains, grouping them by business meaning regardless of where they sit in the vertical hierarchy. An asset can carry several topics at once - `graphit kb update metric NAME --topics "REVENUE,RETENTION"` - and a topic never moves an asset's home. When a concept spans domains, the horizontal (by-topic) view is how you find everything about it.
+
+Other placements layered on top:
+- **Multiple tables**: a metric or dimension can depend on several tables (e.g., a JOIN across ORDERS and CUSTOMERS) and appears under each. Table dependency is structural - derived from the SQL, never tagged manually.
+- **Referencing (`secondary_tables`)**: an asset can be referenced onto additional tables; it shows under the target with a `*` suffix and links back to the original, and stays editable only from its home table. Table-backed assets derive domain membership from all their tables (primary + `secondary_tables`).
+- **Cross-cutting domains**: synonyms can carry extra domains in `extra_domain_ids` for relevance beyond their home - badges that match domain filters without moving the asset in the tree.
+
+Domains are coarse and few (broad business areas); topics are finer and more numerous. A single domain like MARKETING typically spans topics such as ACQUISITION, ATTRIBUTION, and CAMPAIGN_PERFORMANCE.
+
+## Tree Rendering Order
+
+The default tree renders Domain > Table > Topic > Asset, with each table under its one home domain. This is a visualization choice; the model also supports Topic > Table or a flat list. When the user asks "where is X?", an asset lives under its primary table's home domain - report that, plus any domains from its `secondary_tables` placements and its topics.
+
+## Answering Structural Questions (Tier 1)
+
+Structural questions have direct answers - give them in business terms:
+
+| Question | Answer pattern |
+|---|---|
+| What is a topic / domain / table / relationship? | Use the Node Types descriptions above, in plain language |
+| Why is [metric] under [table]? | Its SQL depends on that table's columns (or it is referenced there via `secondary_tables`, shown as `*`) |
+| Why is [asset] in [topic]? | Someone tagged it - topics are manual, not derived. Check its topics list |
+| Why is [asset] in [domain]? | Its primary table's domain cascades to it; it was not tagged directly |
+| What is a relationship? | A documented JOIN between two tables (which columns, which join type) used to build correct cross-table SQL |
+| What is memory? | Org-level context notes (goals, terminology, conventions), global scope, shown at the tree root |
+
+Verify against actual KB state when the question names a specific asset (`graphit kb get`, `graphit kb explore`).
+
+## Semantic Questions (Tier 2 - Different Handling)
+
+Questions about what a business concept MEANS at this org ("what does revenue mean for us?", "how do we define an active user?") are semantic, not structural. For these: search the KB for the relevant metric or rule, read its description and calculation, and present what the KB says - do not interpret or extend it from general knowledge. The KB is the source of truth for this org's definitions.

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

@@ -1,61 +1,44 @@
 # KB Traversal - Worked Examples
 
-Common graph queries and which tool to use for each. Agent tool names map to CLI commands: `search` = `graphit kb search`, `read` = `graphit kb get`, `list` = `graphit kb list`, `kb_explore` = `graphit kb explore`.
+Common questions about the KB graph and the CLI command for each. Three commands do most of the work: `graphit kb search "<query>"` (semantic discovery across all types, optional `--type`), `graphit kb get <type> NAME` (full details of one asset), and `graphit kb explore <type> NAME` (walk the graph around one entity).
 
-## Tool Selection Guide
+## Which Command
 
-| Question Shape | Best Tool | Why |
-|----------------|-----------|-----|
-| Semantic ("find things like X") | `search` | Embedding-based discovery across all asset types |
-| Pointed retrieval ("get metric Y") | `read` | Direct fetch by exact name, returns full details |
-| Topic/domain filter ("metrics in REVENUE") | `search` with topics/domain params | Filtered discovery, intersects with query |
-| Connectivity ("what depends on X") | `kb_explore` | Graph walk from a starting entity, returns typed edges |
-| Joins specifically | `kb_explore` with edge_types=["joins"] | Targeted relationship traversal |
-| Multi-hop ("what's 2 hops from X") | `kb_explore` with max_depth=2 | Recursive walk, capped at 3 hops |
+| Question | Command |
+|---|---|
+| Find things like X (semantic) | `graphit kb search "X"` (add `--type metric` to narrow) |
+| Get one asset's full details | `graphit kb get metric NAME` |
+| What connects to X (dependencies, joins, topics, domain) | `graphit kb explore <type> NAME` |
+| What is inside a domain or topic | `graphit kb explore domain NAME` / `graphit kb explore topic NAME` |
+
+`graphit kb explore` returns the whole neighborhood in one call and has no edge-type or depth flags - the response already includes dependents, joins, topics, and domain together, so read the part you need instead of chaining calls.
 
 ## Common Queries
 
 ### "Find all revenue metrics"
-Use `search` with a topic filter to get metrics tagged with the REVENUE topic. If the user means revenue conceptually (not a specific topic), use a semantic search query instead.
+`graphit kb search "revenue" --type metric` for semantic matches. To get the assets tagged with a specific topic, `graphit kb explore topic REVENUE`.
 
-### "What depends on ORDERS table?"
-Use `kb_explore` starting from the table, filtering to depends_on edges. Returns all metrics and dimensions whose SQL references ORDERS columns.
+### "What depends on the ORDERS table?"
+`graphit kb explore table ORDERS` - the response lists every metric and dimension whose SQL references ORDERS columns, plus the relationships it joins through.
 
 ### "What joins with MARKETING_UA_DS?"
-Use `kb_explore` starting from the table, filtering to joins edges. Returns relationship entities that document JOINs involving that table.
+`graphit kb explore table MARKETING_UA_DS`, then read the relationships in the response (the documented JOINs involving that table).
 
 ### "What domains do we have?"
-Use `list` with the domain entity type (`list(entity_type="domain")`). It returns every domain with its description and asset_count, plus an "Uncategorized" entry when tables with no domain exist. Report all of them, including ones with asset_count=0. Do NOT use `search` (domain is not a searchable type) or `kb_explore` (it traverses from one named domain - a wildcard like "*" returns nothing).
-
-### "What's left in uncategorized?"
-Two paths: (1) `list(entity_type="table")` and filter for `domain_id=null` to find unassigned tables, then `kb_explore(entity_type="domain", entity_name="Uncategorized")` to get all tables and assets in the pseudo-domain; or (2) just use `kb_explore(entity_type="domain", entity_name="Uncategorized")` directly to get everything.
+`graphit kb list domains` - returns every domain with its description and asset count, plus an "Uncategorized" entry when tables have no domain. Report all of them, including empty ones. Domain is not a searchable type, so `graphit kb search` will not surface domains.
 
 ### "Show me everything in the MARKETING domain"
-Use `kb_explore` starting from the domain. Returns tables (via in_domain edge) and all assets within those tables (via depends_on edges at depth 2).
+`graphit kb explore domain MARKETING` - returns the domain's tables and the assets on them.
 
 ### "What topics does ARPU_D1 belong to?"
-Use `kb_explore` starting from the metric, filtering to tagged_with edges. Returns all topic nodes the metric is tagged with.
-
-### "Find metrics in same table as ARPU_D1 but different topic"
-Two-step query:
-1. Use `kb_explore` on ARPU_D1 to find its table(s) and topic(s)
-2. Use `search` filtered to that table's metrics, then compare topics in the results
-
-### "What domains have retention metrics?"
-Use `search` with topics=["RETENTION"] and types=["metric"]. A metric's domain is derived from its dependency tables and secondary_tables - there is no domain field directly on the metric. Group the results by that effective domain. To get the home domain for one metric, `kb_explore` from the metric with edge_types=["in_domain"] returns it.
-
-### "Show me the full graph around table X"
-Use `kb_explore` with max_depth=2 and no edge_type filter. Returns the table's domain, all dependent assets, all topics those assets carry, and all relationships the table participates in.
+`graphit kb explore metric ARPU_D1` - the response includes its topics, along with its tables, dimensions, and home domain.
 
-## Depth Guidelines
+### "What's left uncategorized?"
+`graphit kb explore domain Uncategorized` - returns the tables with no home domain and their assets.
 
-| Depth | Use When |
-|-------|----------|
-| 1 (default) | Direct neighbors only. Best for most questions. |
-| 2 | When you need one extra hop (e.g., table's assets AND their topics) |
-| 3 (max) | Full neighborhood. Use sparingly - can return many results for connected tables. |
+## Reading the Results
 
-Start at depth 1. Only increase if the user's question requires it or the initial results are insufficient.
+A single `graphit kb explore` call returns one entity's full neighborhood, so it usually answers the question on its own - scan the response rather than chaining many calls. Start there, and only run a second command if the first response does not contain what you need.
 
 ## Presenting KB Results
 
@@ -69,7 +52,6 @@ Start at depth 1. Only increase if the user's question requires it or the initia
 | **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.
 ~~~
@@ -115,7 +97,6 @@ Adapt fields per type. Rules: content, constraints, apply-on, override policy. D
 - **Related dimensions (8):**
   - **MEDIA_SOURCE** - `media_source` (categorical)
   - **CAMPAIGN_NAME** - `campaign_name` (categorical)
-  - ...
 - **Rules:** **EXCLUDE_ORGANIC** (filters organic installs)
 - **Domain:** MARKETING
 ~~~

package/skills/graphit/references/presentations.md

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

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

@@ -122,12 +122,14 @@ Canvas `graphit.resolve()` queries that follow these shapes serve from a semanti
 - Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions
 - GROUP BY column names or ordinals; ORDER BY / LIMIT allowed (outer only)
 - CTEs are fine when the CTE body follows the same rules
+- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY
 
 **Shapes that skip the cache** (fall back to normal execution, still correct):
 - `COUNT(DISTINCT x)`, window functions, HAVING, QUALIFY
 - OR / NOT in WHERE
 - Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves
 - `CURRENT_DATE`-relative predicates
+- Top-N with aggregate only in ORDER BY (`SELECT dim FROM t GROUP BY dim ORDER BY SUM(metric) DESC LIMIT N` - no decomposable aggregate in SELECT)
 
 ## Data Source Routing