@graphit/cli 0.1.18 → 0.1.21

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

@@ -1,90 +0,0 @@
-# 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.
-
-## Dimension Type Inference
-
-When creating dimensions, `output_type` and `semantic_type` are auto-inferred from the table's column schema for simple column references (e.g., a DATE column becomes `output_type=DATE`, `semantic_type=temporal`). Only override with `--type` / `--output-type` when the inferred type is wrong (e.g., a CASE expression that produces categorical output from a numeric column).
-
-## Metric Default Dimensions
-
-When creating metrics, pass `--default-dimensions "D1,D2"` to declare which dimensions the metric naturally groups by. This populates the "USED BY METRICS" section on dimension detail views and helps users discover natural slicing axes.
-
-## 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

@@ -1,50 +0,0 @@
-# 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

@@ -1,63 +0,0 @@
-# KB Exploration
-
-Consult when starting a dashboard build. The Knowledge Base contains reusable metrics, dimensions, rules, and table schemas that ensure consistent formulas across dashboards.
-
-## KB-First Discovery
-
-Before writing raw SQL with inline aggregations or column references:
-
-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
-
-| 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/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) |
-
-## Naming Conventions
-
-All KB assets use UPPER_SNAKE_CASE. The names are auto-sanitized:
-
-| 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 |
-
-## When to Suggest KB Asset Creation
-
-| Signal | Propose |
-|---|---|
-| User requests a business metric with no KB match | Metric - reusable formula |
-| User groups by a derived expression | Dimension - consistent grouping |
-| User describes a business rule ("active = logged in within 30d") | Rule - applied to future queries |
-| User uses a business term not in KB | Synonym - maps colloquial to defined |
-
-## Formula Syntax
-
-Metrics require `TABLE.COLUMN` references with UPPERCASE naming:
-
-```sql
--- Valid metric formulas
-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)
-
--- Valid dimension formulas (no aggregates)
-EVENTS.PLATFORM
-DATE_TRUNC('month', EVENTS.EVENT_TS)
-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

@@ -1,55 +0,0 @@
-# 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.