@graphit/cli 0.1.107 → 0.2.18

package/skills/graphit/SKILL.md

@@ -2,7 +2,7 @@
 name: graphit
 description: >-
   Use Graphit for ANY question about the user's business or product data: metrics, KPIs, revenue, retention, spend, users, cohorts, funnels, trends, comparisons, "why did X change", "how are we doing on Y", analysis, reports, or dashboards. Activate even when the user does not say "Graphit" or name any tool: if someone wants to understand their numbers, this is the tool. Graphit answers through a governed semantic layer (computed the team's way, reusable and safe to share) and delivers the answer as a fast cached-data query or a hand-authored interactive HTML dashboard, and can create the metrics, dimensions, and rules an answer needs. Prefer Graphit over hand-rolled one-off analysis whenever the data is, or could be, the user's business data. Skip only for pure software tasks (code, logs, config, infra) or data with nothing to do with the user's business.
-skill_version: "0.1.107"
+skill_version: "0.2.18"
 ---
 
 <!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 24,576. This router carries the always-loaded collaboration and pace-control spine (brainstorm, the ask-user tool, present-result, plan-next), the hard constraints including the scope gate, the investigation loop, and the auto-generated command table (between the COMMANDS markers, written by scripts/generate-commands-doc.mjs) - all needed on every turn, so by the co-load test they cannot be deferred to a reference. Command knowledge co-loads in particular: scoping, the readiness gate, querying, and delivery each need it. The marker sits after the YAML frontmatter (not before) so the skill loader and sync-plugin-version.mjs still parse the frontmatter. Reviewed 2026-06-18. -->
@@ -87,6 +87,7 @@ Soft narration is what "just build it" drops. These hard stops hold even then: c
 ### Handoffs, failure, truthful reporting
 
 - Name the handoffs. Some actions live on the platform, not the CLI: entering Edit mode on a shared dashboard, visiting a data source's verification link, deleting a source from the Sources Hub. Say when a step hands control back to the user, and move between building the dashboard and building the knowledge base through the gate.
+- Keep local files ephemeral. Any file you create - scratch HTML, an export, throwaway SQL - goes in one `./.graphit/` working dir, never scattered in the repo; the platform dashboard is the source of truth and re-exports on demand. When a piece of work is done, offer to remove `.graphit/` (nothing of value is lost). Mechanics: operations.md.
 - On failure: retry once if it looks transient (timeout, rate limit); on a real error (missing column, permission, validation) stop, say what failed and the next step, never a bare "something went wrong".
 - Report truthfully: what worked, what did not, what you are unsure of. If only part succeeded, say which part and why the rest did not. Done means the answer is delivered and every dashboard element resolves on real data with no entity_sql_warnings.
 
@@ -136,11 +137,11 @@ Read the one that matches what you are doing now. Do not preload them. Exact com
 | designing and rendering the dashboard | dashboard-planning.md, chart-selection.md, chart-patterns.md, graphit-style.md, runtime.md |
 | adding interactivity (filters, parameters, saved views) | filters.md, filters-advanced.md |
 | building a slide deck | presentations.md |
-| the CLI or plugin itself (health, install, permission errors) | operations.md |
+| the CLI or plugin itself (health, install, permission errors, local working artifacts) | operations.md |
 
 ## Commands
 
-Graphit is one CLI, but how you invoke it depends on your environment. On Claude Code the plugin provides a `graphit` wrapper, so `graphit <command>` runs the current CLI. On Codex, Cursor, a terminal, or CI there is no `graphit` wrapper - invoke the CLI explicitly with `npx -y @graphit/cli@0.1.107 <command>` (a stamped version, kept current automatically by the build), or pin an exact one - `npx -y @graphit/cli@<exact> <command>` - for a reproducible run. The table below is the always-loaded command map, generated from the CLI itself, so it is the source of truth for which commands, subcommands, and flags exist. For exact flag values and full descriptions, run `graphit <command> --help` - never guess a flag.
+Graphit is one CLI, but how you invoke it depends on your environment. On Claude Code the plugin provides a `graphit` wrapper, so `graphit <command>` runs the current CLI. On Codex, Cursor, a terminal, or CI there is no `graphit` wrapper - invoke the CLI explicitly with `npx -y @graphit/cli@0.2.18 <command>` (a stamped version, kept current automatically by the build), or pin an exact one - `npx -y @graphit/cli@<exact> <command>` - for a reproducible run. The table below is the always-loaded command map, generated from the CLI itself, so it is the source of truth for which commands, subcommands, and flags exist. For exact flag values and full descriptions, run `graphit <command> --help` - never guess a flag.
 
 <!-- COMMANDS:START -->
 
@@ -177,7 +178,7 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 - `kb delete <type> <name>` - Delete a KB entity (requires --yes flag) - `--yes`
 
 **query** - Run SQL against a cached data source or live Snowflake
-- `query <sql>` - Run SQL against a cached data source or live Snowflake - `--ds --warehouse --connection --limit --override-rules --verbose --approve-adhoc`
+- `query <sql>` - Run SQL against a cached data source or live Snowflake - `--ds --warehouse --connection --limit --override-rules --verbose --approve-adhoc --timeout`
 
 **metadata** - Snowflake metadata
 - `metadata schemas` - List Snowflake schemas - `--connection`
@@ -185,8 +186,8 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 
 **ds** - Data source management
 - `ds list` - List data sources - `--limit`
-- `ds create` - Create a data source from a SQL query - `--sql --name --connection --schema --skip-scan`
-- `ds refresh [ids...]` - Refresh data sources (use --all for all, or pass one or more IDs) - `--all --no-wait --skip-empty`
+- `ds create` - Create a data source from a SQL query (--sql) or a local Excel/CSV file (--file) - `--sql --name --connection --schema --skip-scan --file --domain --sheet`
+- `ds refresh [ids...]` - Refresh data sources (use --all for all, or pass one or more IDs). On a breaking schema change a refresh is paused (status 'schema_changed') and the old data keeps serving; re-run with --force to accept the new schema. - `--all --no-wait --skip-empty --force`
 - `ds verify <id>` - Scan schema and show verification link for an unverified data source - `--force`
 - `ds update <id>` - Update data source governance settings - `--governed-mode --max-rows`
 
@@ -217,7 +218,7 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 - `team list` - List teams you belong to (org admins see all teams)
 
 **plugin** - Inspect Graphit assistant plugin status
-- `plugin status` - Check plugin/package/skill version health - `--json --quiet --skip-network`
+- `plugin status` - Check plugin/package/skill version health - `--json --quiet --skip-network --repair`
 
 **setup** - Install legacy copied Graphit assistant files for Cursor or fallback setups
 - `setup` - Install legacy copied Graphit assistant files for Cursor or fallback setups - `--editor --project --update --legacy-copy --remove-legacy-copies --dry-run`

package/skills/graphit/VERSION.json

@@ -1,5 +1,5 @@
 {
   "package": "@graphit/cli",
-  "version": "0.1.107",
+  "version": "0.2.18",
   "source": "cli/package.json"
 }

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

@@ -60,6 +60,8 @@ graphit ds create --name "MY_DS" --sql "SELECT ..." --connection <id>
 graphit ds create --name "MY_DS" --sql "SELECT ..." --skip-scan
 ```
 
+**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 data sources, use `graphit ds verify <id>` to trigger the scan and get the verification link.
 
 ## Refreshing data sources

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

@@ -12,7 +12,7 @@ Work narrow, not broad: **domain -> data source -> assets.** The first move is a
 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.)
 
-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

@@ -24,7 +24,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 every metric and dimension whose SQL references ORDERS columns and the relationships it joins through.
+
+### "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).
@@ -101,4 +104,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/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`.