@graphit/cli 0.2.320 → 0.2.321

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Graphit CLI plugin for AI coding assistants",
-    "version": "0.2.320"
+    "version": "0.2.321"
   },
   "plugins": [
     {
@@ -16,9 +16,9 @@
       "source": {
         "source": "npm",
         "package": "@graphit/cli",
-        "version": "0.2.320"
+        "version": "0.2.321"
       },
-      "version": "0.2.320",
+      "version": "0.2.321",
       "category": "data-visualization",
       "tags": [
         "bi",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.2.320",
+  "version": "0.2.321",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.2.320",
+  "version": "0.2.321",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/bin/graphit

@@ -14,7 +14,7 @@ if [ -z "${GRAPHIT_PLUGIN_ROOT:-}" ]; then
 fi
 
 # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
-FLOOR_VERSION="0.2.320"
+FLOOR_VERSION="0.2.321"
 
 PACKAGE_NAME="@graphit/cli"
 # Strict semver: anything else is rejected so a tampered cache cannot inject.

package/bin/graphit.ps1

@@ -7,7 +7,7 @@ if (-not $env:GRAPHIT_PLUGIN_ROOT) {
 }
 
 # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
-$FloorVersion = "0.2.320"
+$FloorVersion = "0.2.321"
 
 $PackageName = "@graphit/cli"
 # Strict semver: anything else is rejected so a tampered cache cannot inject.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.2.320",
+  "version": "0.2.321",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "repository": {
     "type": "git",

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.2.320"
+skill_version: "0.2.321"
 ---
 
 <!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 31,872. Always-loaded: the collaboration/pace spine, hard constraints + scope gate, the loop, and the generated command table (COMMANDS markers, scripts/generate-commands-doc.mjs) - needed every turn, cannot defer to a reference. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Reviewed 2026-08-02. Raised from 29,952 on 2026-08-07 (founder-directed): a domain is now an access boundary, so loop step 2 must say that picking one decides who ever sees the work - load-bearing before any reference load can be relied on. Raised from 30,592 on 2026-08-13 (founder-directed): the living-context MUST bullet - explore placements answer path + pre-create fork. SIZING.md rules raises pay only for command-table growth; both raises are deliberate exceptions. Raised from 31,232 on 2026-08-16: the generated table gained `dashboard check` and its flags - table growth, the sanctioned kind - plus that verb's one router row. -->
@@ -157,7 +157,7 @@ Read the one that matches what you are doing now. Do not preload them. Exact com
 
 ## 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.2.320 <command>` (a stamped version, kept current by the build; pin an exact version for a reproducible run). The table below is generated from the CLI itself. For exact flags, 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.321 <command>` (a stamped version, kept current by the build; pin an exact version for a reproducible run). The table below is generated from the CLI itself. For exact flags, run `graphit <command> --help` - never guess a flag.
 
 <!-- COMMANDS:START -->
 

package/skills/graphit/VERSION.json

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

package/skills/graphit/references/table.md

@@ -17,3 +17,27 @@ graphit.table('#detail-table', {
 ```
 
 `columns` entries are row keys, not display configs - there is no rename mapping. For readable headers, alias in SQL with quoted identifiers (`SELECT SUM(CREDIT_USED) AS "Total Credits"`) so the key itself is the display name, and use the same key in `columnFormats`. Columns without a `columnFormats` entry render raw. Percent values follow the non-scaling rule: multiply 0-1 ratios by 100 in SQL first.
+
+## Downloads: declare the columns a hand-rolled table shows
+
+The entity kebab menu offers Download CSV / Excel. It re-runs the entity's recorded query and serializes **every column that query returned**, which is correct for rows (the runtime caps rows after the query, so the file is deliberately fuller than the screen) and wrong for columns whenever the table shows fewer than it fetches.
+
+That gap is easy to create on purpose. A table with a column picker usually fetches a wide catalogue once so adding a column is instant with no re-query, and a table with rich tooltips may fetch helper columns (a ratio's numerator and denominator, a rank used only for ordering) that are never a visible column at all. One production dashboard fetched 235 columns to render 12; 136 of them existed only to feed a hover tooltip. Every one of them landed in the user's file.
+
+**`graphit.table` is not exempt.** Its `columns` list selects a subset, and rows are often reshaped or renamed in JS before being handed over, so the file can carry both extra columns and the raw SQL aliases (`active_players`) where the table shows the display names (`Active Players`). Declare whenever the table's `columns` differ from what the query returned, for either reason. A table that renders every column its query returned, under those names, needs nothing.
+
+```js
+// call it wherever you build the header row, with the SAME list, in the same order
+if (graphit.exportColumns) {
+  graphit.exportColumns('summary-table', [
+    { key: 'rowkey', label: 'Install Day' },      // row-label columns first
+    ...visibleCols.map(c => ({ key: c.key, label: c.label })),
+  ])
+}
+```
+
+- **Call it from the render path, not from setup.** The single function every consumer already goes through (headers, cells, totals) is the right place, because then the file cannot drift from the table. Calling it once at load leaves the declaration stale the moment the user hides a column.
+- **`label` becomes the file's header text**, so pass what the user is looking at, not the SQL alias. If a column renders as a percentage while the exported value is the raw count, name it for the value in the file, not the one on screen.
+- **Add the row-label columns yourself.** A visible-column list usually holds measure columns only, while the row label is rendered separately, so it has to be prepended or the file loses its key column.
+- **Guard with `if (graphit.exportColumns)`.** On an older platform build the call throws, and a throw inside a render function takes the whole table down with it.
+- **Declaring nothing is fine and is the default.** No declaration means the download is unchanged, which is right for any table whose query already matches what it shows. A declared key the query did not return is dropped, never invented, and a declaration matching nothing falls back to the full result rather than producing an empty file.