@graphit/cli 0.2.0 → 0.2.40

package/skills/graphit/references/data-sources.md

@@ -50,7 +50,7 @@ A wide or raw source is sometimes the right call - row-level drill-down/export,
 
 ## Creating data sources
 
-`graphit ds create` auto-chains: create -> poll until ready -> scan schema -> print verification link. The user must visit the verification link on the platform to review AI-generated column descriptions and activate the DS for KB use.
+`graphit ds create` auto-chains: create -> poll until ready -> scan schema -> print verification link. To activate for KB use, either the user reviews and activates via the link on the platform, or - after you show them the scanned schema and they accept it - run `graphit ds verify <id> --accept-schema` to activate from the CLI.
 
 ```bash
 # Create with auto-scan (recommended)
@@ -60,11 +60,13 @@ graphit ds create --name "MY_DS" --sql "SELECT ..." --connection <id>
 graphit ds create --name "MY_DS" --sql "SELECT ..." --skip-scan
 ```
 
-For existing unverified data sources, use `graphit ds verify <id>` to trigger the scan and get the verification link.
+**From a local file (Excel/CSV):** `graphit ds create --file <path>` uploads the file and creates one data source. Optional: `--name` (defaults to the file name), `--sheet <name>` (only when an Excel workbook has multiple sheets), and `--domain <NAME>` to attach the new table to an existing KB domain (create it first with `graphit kb create domain --name <NAME>` if it doesn't exist). `--file` and `--sql` are mutually exclusive; same auto-scan + verification-link flow as above.
+
+For existing unverified sources, `graphit ds verify <id>` scans and shows the schema; add `--accept-schema` to accept the AI schema and activate a warehouse/SQL source from the CLI (file uploads activate automatically).
 
 ## Refreshing data sources
 
-Data sources cache a snapshot of the Snowflake query result. Refresh when you need current data.
+Data sources cache a snapshot of the Snowflake query result. Refresh when you need current data. **File-upload sources can't be refreshed (no query to re-run) - update them by re-uploading with `graphit ds create --file <path>`.**
 
 ```bash
 # Refresh all data sources and wait for completion (live status table)

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

@@ -10,9 +10,9 @@ Work narrow, not broad: **domain -> data source -> assets.** The first move is a
 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, and it is the primary discovery call.
 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 as a fallback.** Use `graphit kb search "<concept>"` only when an exploration came up empty or the concept name is too fuzzy to match a domain or topic. Search is semantic (matches by meaning, ranked by a relevance `score`) merged with name/text matching, and capped by `--limit` - the result carries `total` and `truncated`. So an empty or unexpected result means *maybe ranked-out or truncated*, never proof an asset is absent: raise `--limit`, narrow `--type`, or confirm a specific name with `kb get` before concluding it doesn't exist. (`graphit kb list domains` enumerates domain names when you need to pick one; it is a name lookup, not the asset-discovery path - explore the domain to see its assets.)
+5. **Broaden only as a fallback.** Use `graphit kb search "<concept>"` only when an exploration came up empty or the concept name is too fuzzy to match a domain or topic. Search is semantic (matches by meaning, ranked by a relevance `score`) merged with name/text matching, and capped by `--limit` - the result carries `total` and `truncated`. So an empty or unexpected result means *maybe ranked-out or truncated*, never proof an asset is absent: raise `--limit`, narrow `--type`, or confirm a specific name with `kb get` before concluding it doesn't exist. `graphit kb list` carries `total`/`truncated` too - fewer rows than `total` means the list was capped, not that assets are missing; raise `--limit`. (`graphit kb list domains` enumerates domain names when you need to pick one; it is a name lookup, not the asset-discovery path - explore the domain to see its assets.)
 
-If a domain has tables but no metrics or dimensions, that is the strongest signal to propose foundational assets before building any graph - this is the KB-readiness gate the build workflow enforces. If the user declines ("just build it", "skip KB"), respect it and work from the table schema.
+If a domain has tables but no metrics or dimensions, that is the strongest signal to propose foundational assets before building any graph - this is the KB-readiness gate the build workflow enforces. If the user declines ("just build it", "skip KB"), respect it and work from the table schema - read it with `graphit kb explore table <NAME>`, which returns the columns (names, types, descriptions).
 
 ## Metric vs Dimension
 

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

@@ -2,14 +2,16 @@
 
 Contents: Which Command (the read-command picker) - Common Queries (worked examples) - Reading the Results - Presenting KB Results (the per-command output templates).
 
-Which `graphit kb` read command answers each question, and how to present the result. Explore is the primary call: `graphit kb explore <type> NAME` walks the graph around one entity and returns its whole neighborhood at once. `graphit kb get <type> NAME` returns one asset's full details, and `graphit kb search "<query>"` is the fallback for semantic discovery when you cannot name the entity.
+Which `graphit kb` read command answers each question, and how to present the result. Each verb owns one role: `graphit kb list <type>` is the **inventory** (how many, and which, assets of a type exist), `graphit kb get <type> NAME` is one asset's **full definition**, and `graphit kb explore <type> NAME` is the **relationships** call - it walks the graph around one entity and returns its whole neighborhood (and, for a template, its concrete variants) in one call. `graphit kb search "<query>"` is the fallback for semantic discovery when you cannot name the entity. Explore is the primary discovery call.
 
 ## Which Command
 
 | Question | Command |
 |---|---|
+| How many / which assets of a type exist (inventory) | `graphit kb list <type>` (metrics collapse to templates; `--include-variants` for the flat set) |
 | What is inside a domain or topic (the build entry point) | `graphit kb explore domain NAME` / `graphit kb explore topic NAME` |
 | What connects to X (dependencies, joins, topics, domain) | `graphit kb explore <type> NAME` |
+| A template's concrete variants | `graphit kb explore metric NAME` |
 | Get one asset's full details | `graphit kb get metric NAME` |
 | Find things like X when you cannot name it (semantic) | `graphit kb search "X"` (add `--type metric` to narrow) |
 
@@ -24,7 +26,10 @@ Which `graphit kb` read command answers each question, and how to present the re
 `graphit kb explore topic REVENUE` returns the assets tagged with that concept across every domain. Fall back to `graphit kb search "revenue" --type metric` only when no topic captures the concept.
 
 ### "What depends on the ORDERS table?"
-`graphit kb explore table ORDERS` - lists every metric and dimension whose SQL references ORDERS columns, plus the relationships it joins through.
+`graphit kb explore table ORDERS` - returns the table's column schema (names, types, descriptions) plus `metric_count`/`dimension_count`/`rule_count` and every bound metric (collapsed to templates, each with a `variant_count`), dimension, and rule whose SQL references ORDERS. The counts include child variants; the lists stay collapsed.
+
+### "What columns does this table or data source have?" (read the schema)
+`graphit kb explore table <NAME>` (or `graphit kb get table <NAME>`) returns the column schema - names, types, descriptions - straight from the knowledge base. This is how you read a table's schema; never `DESCRIBE` it (only read-only SELECT runs through `graphit query`, so DESCRIBE/SHOW/DDL are rejected). If a data source was just created and not yet scanned, the KB has no columns for it yet - read its shape with `graphit query "SELECT * FROM <NAME> LIMIT 0" --ds <id>`, or run `graphit ds verify <id>` to scan it into the KB.
 
 ### "What joins with MARKETING_UA_DS?"
 `graphit kb explore table MARKETING_UA_DS`, then read the relationships in the response (the documented JOINs involving that table).
@@ -42,18 +47,18 @@ Which `graphit kb` read command answers each question, and how to present the re
 
 A single `graphit kb explore` call returns one entity's full neighborhood, so it usually answers the question on its own - scan the response and run a second command only if the first does not contain what you need. The user cannot see raw CLI output; render every result with these per-command templates.
 
-**After `graphit kb list <type>`** - count summary + table with bold names:
+**After `graphit kb list <type>`** - count summary + table with bold names. The list is the **inventory**, and the response carries `total`/`truncated`: if the rows shown are fewer than `total`, the list was capped - raise `--limit` (a missing asset may be truncated, not absent). For metrics the list is **collapsed** - each row is a template or a flat metric, never a child variant; a template's `variant_count` says how many concrete variants it owns. Use `--include-variants` for the full flat set, or `graphit kb explore metric NAME` to enumerate one template's variants.
 
 ~~~
-**12 metrics** across 3 tables:
+**12 metrics** (10 flat + 2 templates, 38 variants) across 3 tables:
 
-| Metric | Table | Calculation | Params |
-|---|---|---|---|
-| **CPI** | **MARKETING_UA** | `SUM(spend)/SUM(installs)` | - |
-| **ARPU** | **MARKETING_UA** | `SUM(revenue)/COUNT(...)` | DAY |
-| **RETENTION** | **PLAYER_QUALITY** | `COUNT(CASE WHEN ...)` | DAY |
+| Metric | Table | Calculation | Params | Variants |
+|---|---|---|---|---|
+| **CPI** | **MARKETING_UA** | `SUM(spend)/SUM(installs)` | - | - |
+| **ARPU** | **MARKETING_UA** | `SUM(revenue)/COUNT(...)` | DAY | 18 |
+| **RETENTION** | **PLAYER_QUALITY** | `COUNT(CASE WHEN ...)` | DAY | 20 |
 
-4 parameterized (need `(DAY=N)` syntax), 8 pre-baked.
+To use a variant, reference `{{metric:ARPU(DAY=7)}}`; to list them, explore the template.
 ~~~
 
 Adapt columns per type: dimensions include semantic type, rules include constraint count, domains include asset count.
@@ -101,4 +106,4 @@ Adapt fields per type. Rules: content, constraints, apply-on, override policy. D
 - **Domain:** MARKETING
 ~~~
 
-For domain exploration, show Domain > Table > Asset hierarchy as a tree.
+For domain exploration, show Domain > Table > Asset hierarchy as a tree. For table exploration, list the table's columns first (`NAME - type - description`), then the metrics, dimensions, and rules defined on it.

package/skills/graphit/references/operations.md

@@ -10,6 +10,7 @@ Load this when the concern is the Graphit CLI or plugin itself, not the analysis
 - [Legacy copied-file setup](#legacy-copied-file-setup)
 - [Permission errors](#permission-errors)
 - [Output contract](#output-contract)
+- [Working artifacts](#working-artifacts)
 - [Reporting failures and partial results](#reporting-failures-and-partial-results)
 
 Governance is enforced server-side by the query gateway. There is no client-side query guard, so never claim to block a query locally; a query is rejected by the platform, not the CLI.
@@ -78,6 +79,12 @@ Commands write only the result payload to stdout; all decoration (progress, tabl
 - Use json for anything you read back, especially nested output (`kb explore`, query rows, `kb get`). `--output table` is a quick flat human view; nested cells render as compact JSON, not `[object Object]`.
 - `--output styled` is the interactive view - never parse it.
 
+## Working artifacts
+
+Keep every local file you create in one place: a `./.graphit/` directory in the working dir (distinct from the `~/.graphit/` credential store). Scratch HTML written before `graphit dashboard update-html <id> --file`, output redirected from `graphit dashboard get-html`, exported PNG/PDF, throwaway SQL - all under `.graphit/`, never scattered across the user's repo. `graphit dashboard export` already defaults its output there (no `--output` needed) and drops a self-ignoring `.gitignore`, so the dir is never committed.
+
+These are ephemeral. The platform dashboard is the source of truth and the durable artifact; anything local re-materializes on demand (`graphit dashboard get-html <id>` for the HTML, `graphit dashboard export <id> --format png|pdf` for a rendered image). When you finish a piece of work, offer to remove `.graphit/` - nothing of value is lost. Keep it a soft suggestion, not a forced step.
+
 ## Reporting failures and partial results
 
 When a command fails or only part of a multi-step task succeeds, report it truthfully. The user cannot see the raw CLI output, so a bare "something went wrong" leaves them stuck. Verify each step before claiming it; never report a step as done that you did not confirm.

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

@@ -31,7 +31,7 @@ Paired with a calculation such as `SUM(${PARAM:REVENUE}) / SUM(cost) * 100 ${PAR
 |------|--------|
 | Token match | Every `${PARAM:NAME}` token in the calculation needs a matching parameter by name |
 | Empty values | Valid as no-ops (e.g. D0 adds no filter) |
-| Variant cap | Max 100 (the Cartesian product of all parameter values) |
+| Variant cap | Max 1000 (the Cartesian product of all parameter values) |
 | Child naming | Auto-generated as `{PARENT}_{VALUE1}_{VALUE2}` (e.g. ROAS_ALL_BOOKINGS_D7) |
 | Validation | Template create skips per-formula validation (children validate on generation) |
 
@@ -52,7 +52,7 @@ If the user targets a child for edit or delete, redirect to the parent: "ROAS_AL
 
 You never substitute tokens by hand. The server resolves a variant when you reference it with the parameter syntax in SQL.
 
-1. Find the template. `graphit kb list metric` shows a `params` column listing each metric's required parameter names (e.g. `REVENUE, DN`); an empty `params` cell means the metric is flat and needs no parameters.
+1. Find the template. `graphit kb list metric` shows the collapsed inventory - templates and flat metrics only, never child variants - with a `params` column (the required parameter names, e.g. `REVENUE, DN`) and a `variant_count`; an empty `params` cell means the metric is flat. To enumerate a template's concrete variants, `graphit kb explore metric NAME`; reach for `graphit kb list metric --include-variants` only when you truly need every child row flat.
 2. Map the user's words to parameter values: "D7 ROAS for new users" maps to `REVENUE=NEW_BOOKINGS` and `DN=D7`.
 3. Reference it with `{{metric:NAME(K=V)}}` in the query SQL, e.g. `{{metric:ROAS(REVENUE=NEW_BOOKINGS, DN=D7)}}`. The server expands it to the pre-validated child calculation at query time.
 
@@ -62,7 +62,7 @@ graphit query "SELECT {{dim:INSTALL_MONTH}}, {{metric:ROAS(REVENUE=NEW_BOOKINGS,
 
 Defaults and errors:
 - Omitting a parameter on a required metric returns a clear error naming the parameter and the valid values. Retry with a value or ask the user which one they meant.
-- A pre-baked variant (ROAS_D7, ARPU_D30) has its value hardcoded in the name, so reference it plainly as `{{metric:ROAS_D7}}` with no parameter clause.
+- A pre-baked variant (ROAS_D7, ARPU_D30) has its value hardcoded in the name, so reference it plainly as `{{metric:ROAS_D7}}` with no parameter clause. Find its exact name via `graphit kb explore metric ROAS` (lists the variants) or `graphit kb list metric --include-variants` - the collapsed `kb list` does not show child variant names.
 
 ## Contrast: Wrong vs Right
 

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

@@ -1,6 +1,6 @@
 # SQL Reference
 
-Consult when writing queries. Data source queries (`graphit query --ds`) run DuckDB. Warehouse queries (`graphit query --warehouse`) run Snowflake. You MUST use the correct dialect.
+Consult when writing queries. Data source queries (`graphit query --ds`) run DuckDB. Warehouse queries (`graphit query --warehouse`) run Snowflake. You MUST use the correct dialect. To read a table's columns, use `graphit kb explore table <NAME>` - never `DESCRIBE`/DDL (`graphit query` runs SELECT only).
 
 ## DuckDB vs Snowflake Translation
 
@@ -192,5 +192,3 @@ For ad-hoc queries, suggest the KB reference equivalent when one exists. This nu
 **Always use `--verbose`** to get the resolved SQL. If the user didn't pass it, re-run with `--verbose` so you can show both the reference query and the expanded SQL.
 
 Zero rows: explain what you checked and hypothesize why (wrong date range, filter too strict, table empty).
-
-The `graphit ds list` output template lives in `data-sources.md`.