@graphit/cli 0.1.4 → 0.1.6

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

@@ -0,0 +1,82 @@
+# KB-Aware Planning
+
+> Load when: planning graphs that involve metrics (aggregations) or dimensions (grouping/filtering columns), or when the user references a business concept that might already exist as a KB asset.
+
+Before writing inline SQL with raw aggregations or column references, check whether a KB asset already defines the concept. Using KB assets ensures consistent formulas across dashboards and makes future graphs faster to create.
+
+## KB-First Discovery
+
+Before proposing graphs with inline aggregations or custom column expressions:
+
+1. Check the KB Overview in the system prompt for existing metrics and dimensions
+2. If the KB Overview shows assets that match the user's request, reference them by name
+3. If no matching asset exists, recommend creating it first, then build the graph referencing the new asset
+
+If the KB Overview shows tables but no metrics or dimensions, this is the strongest signal to suggest KB asset creation. Propose foundational metrics and dimensions based on the table schema before planning any graphs. If the user explicitly declines ("just build it", "skip KB"), respect that and work from table schema.
+
+## When to Propose KB Asset Creation
+
+| Signal | Proposed asset | 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 means 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 defined metrics |
+
+Propose creation as the default path: "Your KB doesn't have a revenue metric yet. I'd recommend creating one first - that way it's reusable across all your dashboards with a consistent formula. Then I'll build the graph using it. Sound good?"
+
+## Metric vs Dimension Distinction
+
+| Property | Metric | Dimension |
+|----------|--------|-----------|
+| Formula type | 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/sum) | Grouping axes (how you slice) |
+| Example | `SUM(ORDERS.AMOUNT)` | `DATE_TRUNC('month', EVENTS.EVENT_TS)` |
+| Invalid example | `ORDERS.AMOUNT` (no aggregate) | `SUM(EVENTS.DURATION)` (has aggregate) |
+
+## Topics
+
+When creating any KB asset, consider which business topic it belongs to and pass `topics` (e.g., `["ACQUISITION"]`, `["MONETIZATION"]`). Check the KB Overview for existing topic names first to avoid duplicates. UPPER_SNAKE_CASE.
+
+## Reuse Over Reinvention
+
+When planning multi-graph dashboards, identify shared concepts across graphs and propose KB assets for them:
+
+- If 3 graphs all use `SUM(ORDERS.AMOUNT)`, propose a TOTAL_REVENUE metric once
+- If 2 graphs group by `DATE_TRUNC('month', TS)`, propose a MONTHLY dimension once
+- Reference the KB asset by name in subsequent graphs instead of repeating the formula
+
+## Cross-Table Referencing
+
+When a metric or dimension already exists on one table and the user wants the same concept on a sibling table with identical columns, **reference it** instead of creating a duplicate:
+
+`edit(entity_type="metric", id="TOTAL_REVENUE", secondary_tables=["ORDERS_12M"])`
+
+- Metrics/dimensions: the target table must contain every column the formula references (validated on save).
+- Rules: the target table just needs to exist (no column check).
+- This is a pointer, not a copy. Edits propagate to all placements.
+- In the KB tree, referenced placements appear with a `*` suffix and link back to the original.
+
+Suggest referencing when: the user has sibling data sources with the same schema (e.g., 6M and 12M windows), or asks to "make X available on Y table".
+
+> For metric formula syntax, aggregation patterns, and WHERE clause rules, see `kb_authoring/references/formula-syntax.md`. For creating KB assets, hand off to `kb_authoring`.
+
+## KB Graph Navigation
+
+For structural questions about the KB (what is a topic, what depends on X, how do domains work), graph traversal, or KB organization requests, activate the `kb_navigation` shared skill. It provides:
+
+- `kb_explore` tool for graph traversal (what depends on X, what joins with Y)
+- Structural explanations grounded in actual KB data
+- Full action parity with the manual KB page UI
+- Topic and domain filtering via `search` tool
+
+**When to activate kb_navigation vs stay in current skill:**
+
+| User Intent | Activate kb_navigation? |
+|-------------|------------------------|
+| "What is a topic?" or "How do domains work?" | Yes - structural question |
+| "What depends on this table?" | Yes - graph traversal |
+| "Organize my KB" or "Clean up topics" | Yes - KB management |
+| "Show me revenue metrics for my graph" | No - use search + read, stay in current skill |
+| "Create a metric called X" | No - use kb_expert or kb_authoring |

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

@@ -0,0 +1,50 @@
+# KB Explanation - Structural Q&A Patterns
+
+Tier 1 structural questions about KB concepts. Answer these using the patterns below, grounded in actual KB data when possible. Use business-friendly language - no implementation details.
+
+## Tier 1: Structural (In Scope)
+
+Answer directly using these patterns. Always verify against actual KB state when the question involves specific entities.
+
+### What is a topic?
+A topic is a business concept tag you apply to metrics, dimensions, rules, and synonyms. Examples: REVENUE, ACQUISITION, RETENTION. Any asset can have multiple topics. Topics help organize the KB by business meaning rather than physical table location.
+
+### What is a domain?
+A domain is a high-level business area like MARKETING, SALES, or PRODUCT. Domains are broader than topics - think of them as departments or business units. A domain is set on a table, and every metric, dimension, and rule built on that table belongs to that domain automatically. An org typically has 3-10 domains and 10-30+ topics.
+
+### How do domains and topics differ?
+The difference is granularity and how they attach:
+- A **domain** is coarse (5-10 per org: MARKETING, FINANCE, PRODUCT) and is set on the table. Each asset has one home domain, inherited from the table its data comes from. An asset can also be marked relevant to a few extra domains when it genuinely spans areas.
+- A **topic** is fine (10-30+ per org: REVENUE, ACQUISITION, RETENTION) and is tagged directly on assets. An asset can carry several topics at once.
+
+A single domain like MARKETING might contain topics like ACQUISITION, ATTRIBUTION, and CAMPAIGN_PERFORMANCE.
+
+### What is a table in the KB?
+A table represents a physical data location in the warehouse. Metrics and dimensions depend on tables because their SQL formulas reference table columns. Tables are structural, not tags - the dependency is derived from the SQL, not manually assigned.
+
+### What is a relationship?
+A relationship documents a JOIN between two tables. It specifies which columns connect them and what kind of join to use. When the agent writes SQL across multiple tables, it uses relationships to build correct JOINs.
+
+### Why is [metric] under [table]?
+A metric appears under a table because the metric's SQL formula depends on columns in that table. Check the metric's dependencies to see exactly which columns it uses. A metric can depend on multiple tables - it appears under each one, with the first listed as primary. An asset can also appear under a table via **referencing** (`secondary_tables`) - this shows as a `*` marker in the tree and means the asset was made available on that table as a read-only pointer. The original lives on its home table.
+
+### Why is [asset] in [topic]?
+An asset appears under a topic because someone (user, agent, or scanner) tagged it with that topic. Topics are manually assigned tags, not automatically derived. Check the asset's topics list to see all its topic assignments.
+
+### Why is [asset] in [domain]?
+An asset's domain comes from the table its data lives in: whoever set the table's domain, every asset on that table inherits it. So a metric is in MARKETING because its primary table is a MARKETING table, not because the metric itself was tagged. If an asset genuinely spans areas, it can also be marked relevant to extra domains, which show as badges and match domain filters without moving it in the tree. To change a metric's home domain, change the domain on its table.
+
+### How do tables and topics differ?
+Tables are physical (where the data lives in the warehouse). Topics are conceptual (what the data is about). One table can have assets tagged with many different topics, and one topic can span assets across multiple tables.
+
+### What is memory?
+Memory stores org-level context notes - background information about the organization, its goals, terminology, or conventions. Memory is global (not scoped to any table, domain, or topic) and appears at the root of the KB tree.
+
+## Tier 2: Semantic (Out of Scope for This Skill)
+
+Questions about what a specific business concept means at this organization (e.g., "what does revenue mean for us?", "how do we define an active user?") are semantic questions, not structural ones. For these:
+1. Search the KB for the relevant metric or rule
+2. Read its description and calculation
+3. Present what the KB says - do not interpret or extend it
+
+Do not attempt to answer semantic questions from general knowledge. The KB is the source of truth for this org's definitions.

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

@@ -6,12 +6,11 @@ Consult when starting a dashboard build. The Knowledge Base contains reusable me
 
 Before writing raw SQL with inline aggregations or column references:
 
-1. List what exists: `graphit kb list metrics`, `graphit kb list dimensions`, `graphit kb list rules`
-2. If a KB metric matches the user's request, use its formula: `graphit kb get metric REVENUE`
-3. If no match exists, consider whether to build the dashboard from raw columns or suggest KB asset creation first
-4. Explore relationships: `graphit kb explore metric REVENUE` shows which tables and dimensions connect to a metric
-
-KB assets ensure consistent formulas across dashboards. If 3 charts all need `SUM(ORDERS.AMOUNT)`, one TOTAL_REVENUE metric is better than 3 inline aggregations.
+1. Understand organization: `graphit kb list domains` shows business-area groupings (MARKETING, PRODUCT, FINANCE, etc.)
+2. List what exists: `graphit kb list metrics`, `graphit kb list dimensions`, `graphit kb list rules`
+3. If a KB metric matches the user's request, use its formula: `graphit kb get metric REVENUE`
+4. If no match exists, consider whether to build the dashboard from raw columns or suggest KB asset creation first
+5. Explore relationships: `graphit kb explore metric REVENUE` shows which tables and dimensions connect to a metric
 
 ## Metric vs Dimension
 
@@ -34,13 +33,6 @@ All KB assets use UPPER_SNAKE_CASE. The names are auto-sanitized:
 | `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
 | `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios/percentages |
 
-## Reuse Over Reinvention
-
-When building multi-chart dashboards, identify shared concepts:
-- If 3 charts use `SUM(ORDERS.AMOUNT)`, reference one TOTAL_REVENUE metric
-- If 2 charts group by `DATE_TRUNC('month', TS)`, reference one MONTHLY dimension
-- Discover existing assets: `graphit kb search "revenue"`
-
 ## When to Suggest KB Asset Creation
 
 | Signal | Propose |
@@ -67,3 +59,5 @@ CASE WHEN USERS.AGE >= 18 THEN 'adult' ELSE 'minor' END
 ```
 
 Conditionals use CASE WHEN (not FILTER WHERE - Snowflake doesn't support it). Always guard division with NULLIF.
+
+For deeper coverage, consult: `kb-graph-structure.md` (graph model), `kb-awareness.md` (KB-first planning), `kb-explanation.md` (structural Q&A), `parameterized-metrics.md` (metric templates), `kb-traversal.md` (graph queries), `kb-actions.md` (full CRUD).

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

@@ -0,0 +1,55 @@
+# KB Graph Structure
+
+The Knowledge Base is a labeled property graph. Assets carry tags that place them in a tree, but the underlying structure is a graph with typed edges.
+
+## Node Types
+
+| Type | Count Range | Description |
+|------|-------------|-------------|
+| metric | 10-200+ | Aggregation formula (SUM, COUNT, AVG) that computes a business KPI |
+| dimension | 20-500+ | Row-level SQL expression on one table, used for grouping or filtering |
+| rule | 5-100+ | Free-text business constraint, optionally scoped to one or more tables |
+| synonym | 10-100+ | Maps a business term to a canonical metric, dimension, or column |
+| table | 2-50+ | Physical data location in the warehouse, with typed columns |
+| topic | 5-30+ | Business-concept tag applied to assets (e.g., REVENUE, ACQUISITION) |
+| domain | 3-10 | High-level business area (e.g., MARKETING, SALES, PRODUCT) |
+| relationship | 2-30+ | Documented JOIN pattern between two tables |
+| memory | 1-5 | 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 that home 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 |
+
+## Multi-Membership Semantics
+
+Tables and topics are multi-valued; domain works differently - a single **home** that cascades:
+
+- A metric can depend on **multiple tables** (e.g., JOIN across ORDERS and CUSTOMERS), and appears under each.
+- An asset has **one home domain**, inherited from its primary table (the first table its SQL depends on). The asset does not carry its own domain tag - set the domain on the table and every asset on that table inherits it.
+- An asset can carry **multiple topics** (e.g., ARPU tagged with both REVENUE and MONETIZATION).
+- An asset can be **referenced** onto additional tables via `secondary_tables`. Referenced placements appear in the tree under the target table with a `*` suffix and link back to the original. The asset is editable only from its home table.
+- Synonyms can carry **cross-cutting domains** in `extra_domain_ids` for relevance beyond the home domain. Table-backed assets (metrics, dimensions, rules) derive domain membership entirely from their tables.
+
+For multiple tables, the tree shows the asset under each table with a link icon. For domain, the tree places each table (and its assets) under its one home domain only - cross-cutting extras are badges, not duplicate placements.
+
+## Tags vs Structure
+
+| Concept | Type | Cardinality | Notes |
+|---------|------|-------------|-------|
+| Domain | Home (on table) + secondary_tables | One home per asset (from its table); domain derived from all tables | Coarser grouping (~5-10 per org). Home cascades from the primary table; `secondary_tables` extends reach; synonyms use `extra_domain_ids` |
+| Topic | Pure tag | Any (typically 1-3) | Finer grouping (~10-30+ per org) |
+| Table | Structural dependency | Any (typically 1-2) | Based on SQL dependencies, not manual tagging |
+| Relationship | First-class edge | Exactly 2 tables | Explicit JOIN documentation |
+| Memory | Global | N/A | Not scoped to any table, domain, or topic |
+
+**Key insight for traversal:** Topics are multi-valued tags on assets (agent adds/removes via `edit`). Domain is a single home set on the **table** (`edit(entity_type="table", domain_id=...)`), which cascades to every asset on that table. Table-backed assets derive domain membership from all their tables (primary + `secondary_tables`). Synonyms use `extra_domain_ids` for cross-cutting domain relevance. Table dependencies are structural (derived from SQL). Relationships are explicit edges between tables.
+
+## Tree Rendering Order
+
+The default tree renders as: Domain > Table > Topic > Asset, where each table sits under its one home domain. This is a visualization choice; the data model also supports other groupings (Topic > Table, 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.

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

@@ -0,0 +1,58 @@
+# 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`.
+
+## Tool Selection Guide
+
+| 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 |
+
+## 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.
+
+### "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 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.
+
+### "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.
+
+### "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).
+
+### "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.
+
+## Depth Guidelines
+
+| 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. |
+
+Start at depth 1. Only increase if the user's question requires it or the initial results are insufficient.

package/skills/graphit/references/parameterized-metrics.md

@@ -0,0 +1,89 @@
+# Parameterized Metrics
+
+A parameterized metric is a template with `${PARAM:NAME}` tokens in its calculation. Each token maps to a named parameter with a list of values (value_name to SQL fragment). The system auto-generates child variants for every combination of parameter values.
+
+Example: ROAS with parameters REVENUE (9 values) and DN (4 values) produces 36 validated child metrics from 1 template.
+
+## When to Parameterize
+
+**Create parameterized** when columns follow a variant pattern:
+- `total_iap`, `total_iap_new_users`, `estimated_gross_iap` -> one REVENUE parameter
+- Metrics that differ only by a WHERE clause (D7, D30, D90) -> one DN parameter
+
+**Stay standalone** when:
+- Metric has no natural variants
+- Only 1-2 variants (template overhead not worth it)
+- Variants use fundamentally different formulas
+
+## Creating a Parameterized Metric
+
+Use `${PARAM:NAME}` tokens in the calculation, then pass `parameters` with the value map. The `placeholder` field is optional (omit it for the new token format):
+
+```json
+"calculation": "SUM(${PARAM:REVENUE}) / SUM(cost) * 100 ${PARAM:DN}",
+"parameters": [
+  {
+    "name": "REVENUE",
+    "values": {"ALL_BOOKINGS": "total_iap", "NEW_BOOKINGS": "total_iap_new_users"},
+    "default_value": "ALL_BOOKINGS"
+  },
+  {
+    "name": "DN",
+    "values": {"D0": "", "D7": "WHERE day <= 7"},
+    "default_value": "D0"
+  }
+]
+```
+
+| Rule | Detail |
+|------|--------|
+| Token matching | Every `${PARAM:NAME}` in the calculation must have a matching parameter by name |
+| Empty values | Valid as no-ops (e.g. D0 adds no filter) |
+| Variant cap | Max 100 (Cartesian product of all parameter values) |
+| Child naming | Auto-generated: `{PARENT}_{VALUE1}_{VALUE2}` (e.g. ROAS_ALL_BOOKINGS_D7) |
+
+## Editing a Template
+
+All edits go through the parent template. Children are read-only.
+
+| User intent | Edit action |
+|-------------|-------------|
+| Change formula | Edit `calculation` on the template - children re-generate |
+| Add a variant (e.g. D120) | Edit `parameters`, add the new value to the relevant parameter |
+| Remove variants | Edit `parameters`, remove values from the relevant parameter |
+| Change description/topics | Edit those fields on the template - no child re-generation |
+
+If a child metric is targeted for edit or delete, redirect to the parent:
+"ROAS_ALL_BOOKINGS_D7 is a variant of ROAS. Edit the parent template ROAS instead."
+
+## Using Parameterized Metrics in Queries
+
+When a user asks for a specific variant (e.g. "show me D7 ROAS for new users"):
+
+1. Find the template in KB context (marked with `[P:N]` in the tree)
+2. Infer axis values from the user's message: REVENUE=NEW_BOOKINGS, DN=D7
+3. Use `read` with `entity_type="metric"` and pass `axis_values` to get the resolved child
+4. Use the returned validated child calculation in your graph SQL
+
+### NEVER
+- Substitute tokens manually in the template formula. Always use the backend-returned child SQL, which has been pre-validated.
+
+### Defaults and Errors
+- **Default resolution:** When the user doesn't specify parameters, pass empty `axis_values` - the backend fills defaults.
+- **Invalid values:** If you pass an invalid axis value, the backend returns valid options. Retry with a valid value or ask the user.
+
+## Contrast: Wrong vs Right
+
+| Wrong | Right |
+|-------|-------|
+| Manually replace `${PARAM:REVENUE}` with `total_iap` in the formula and pass to graph SQL | Use `read` with `axis_values` to get pre-validated child calculation |
+| Create separate ROAS_ALL_BOOKINGS, ROAS_NEW_BOOKINGS as standalone metrics | Create one ROAS template with a REVENUE parameter |
+| Edit ROAS_ALL_BOOKINGS_D7 directly | Edit the parent ROAS template instead |
+
+## Deleting a Template
+
+Delete on the parent cascade-deletes all children. Blast radius includes all children plus their downstream refs (graphs, rules, synonyms).
+
+## Verification
+
+Verify on a template sets `verified=True` on the parent and all children.