@graphit/cli 0.2.42 → 0.2.50

package/skills/graphit/references/runtime.md

@@ -1,9 +1,9 @@
 <!--
 SIZE EXEMPTION (reference file)
 Hard limit: 7,168 chars | Exempted ceiling: 14,336 chars
-Current: 12,478 chars (content) - intentionally over the base reference limit.
+Current: ~12,990 chars (content) - intentionally over the base reference limit.
 Rationale: runtime.md is the consolidated build-time data + entity contract. Its core - the live-data API, the data-graphit-* entity contract, the first-paint loading state, the helper index, and the canonical example - is a single co-load unit: building one live element needs all of it together, so by the co-load test (split a reference only where the agent needs one part without the other) it cannot be split without creating refs that always load together, which the test forbids. The one use-case-clean seam (cache-friendly resolve SQL + the rate-limit budget, needed only for interactive or large dashboards) was deliberately kept inline to preserve the single authoritative contract. This ref loads only on HTML-deliverable turns (just-in-time, not every turn), so the cache cost is bounded.
-Reviewed: 2026-06-17
+Reviewed: 2026-06-23
 Next review: 2026-09-17
 -->
 # Canvas Runtime: Live Data and the Entity Contract
@@ -27,15 +27,17 @@ The iframe provides `graphit.resolve()` to fetch live data from cached data sour
 ```js
 const result = await graphit.resolve({
   sql: "SELECT region, SUM(revenue) AS rev FROM ORDERS_DS GROUP BY region",
-  dataSourceId: "ds_abc123",
+  dataSourceId: "ORDERS_DS",
   target: "#chart-container",
   maxRows: 10000
 });
 // Returns: { columns: string[], data: object[], rowCount: number, truncated: boolean }
 ```
 
-- `dataSourceId` is the ID from `graphit ds list`.
+- `dataSourceId` is the data source name (the same table you SELECT FROM); its id or a unique id-prefix also works.
 - `target` (optional, a CSS selector or element) shows a blur and spinner overlay while loading and removes it on completion.
+- `targetEntityIds` (optional, `string[]`) - the `data-graphit-id`s of OTHER graphs this one result also renders into; the platform records the live filtered query for each so their details panels reflect filters, not just the `target` graph.
+- `sourceEntityId` (optional) - the `data-graphit-id` of the graph that owns this query, for a `target`-less resolve that feeds several graphs (pair with `targetEntityIds`).
 - `maxRows` (optional) defaults to **10,000 rows** and may be raised up to a cap of **50,000 rows**. A dashboard query should aggregate to a chartable grain well under the default; reach for a higher value only for a genuine row-level export, and never above the cap.
 - `result.data` is an array of row objects you render however you want.
 
@@ -51,7 +53,7 @@ Every visible element - chart, KPI card, table, text section - must be wrapped s
 <div data-graphit-id="revenue-trend"
      data-graphit-label="Revenue Trend"
      data-graphit-sql="SELECT {{dim:REGION}} AS region, {{metric:REVENUE}} AS revenue FROM ORDERS_DS GROUP BY region"
-     data-graphit-ds="ds_abc123">
+     data-graphit-ds="ORDERS_DS">
   <!-- chart, KPI, or table content here -->
 </div>
 ```
@@ -61,7 +63,7 @@ Every visible element - chart, KPI card, table, text section - must be wrapped s
 | `data-graphit-id` | Unique kebab-case | `"spend-by-source"` |
 | `data-graphit-label` | Human-readable name | `"Ad Spend by Source"` |
 | `data-graphit-sql` | Executable SQL (HTML-encode the characters `<`, `>`, `&`, `"`) | `"SELECT ..."` |
-| `data-graphit-ds` | Data source ID from `graphit ds list` | `"ds_abc123"` |
+| `data-graphit-ds` | Data source name (same as the FROM table) or id | `"ORDERS_DS"` |
 
 KB asset references are derived automatically from `{{metric:X}}` / `{{dim:X}}` templates in the SQL; the governance compiler resolves these and shows KB asset chips in the entity details panel. Missing any one attribute breaks the entity; missing the wrapper entirely makes the element invisible to the platform.
 
@@ -72,6 +74,8 @@ KB asset references are derived automatically from `{{metric:X}}` / `{{dim:X}}`
 
 **Label equals the visible title.** The `data-graphit-label` MUST match the card's visible heading exactly. Users find their chart by that label in @ mention dropdowns and entity panels - a mismatch means they cannot find it.
 
+**Editing one existing entity.** Edit a single element surgically rather than rewriting the page: `graphit dashboard list-entities <id>` lists every entity (id, label, KB refs, data source) to find the right `data-graphit-id`; `graphit dashboard get-entity <id> <entityId>` returns just that entity's inner HTML - the exact fragment `graphit dashboard update-entity <id> <entityId>` accepts - which you change and write back. Reach for full-page `get-html` / `update-html` only when restructuring the whole layout.
+
 ## First-paint loading state
 
 The dashboard HTML paints before the SDK connects (iframe load plus handshake), so the SDK's own spinner cannot cover the first moments. Bake a pure-CSS overlay into the HTML so every chart shows a spinner from the first frame; the SDK adopts that overlay and removes it when the element's `graphit.resolve()` settles (success or error).
@@ -123,7 +127,7 @@ A resolve query that follows these shapes serves from a semantic cache in roughl
 
 - **Single refresh function.** Put all queries in ONE `Promise.all` inside one `refresh()` function so they share the same time window. NEVER scatter `graphit.resolve()` across independent event handlers or timeouts - that turns one user action into several bursts.
 - **Count queries per interaction.** 6 charts is 6 requests per filter change, about 20 changes per minute of budget; 12 charts is about 10 changes per minute. With 10 or more charts and 3 or more filters, debounce filter changes (300ms) so rapid clicks do not each trigger a full refresh.
-- **Reuse trend data for KPIs.** If you already fetch a weekly time series, derive the KPI total and its sparkline from that result in JS instead of running a separate aggregate query - one query serves both.
+- **Reuse trend data for KPIs.** If you already fetch a weekly time series, derive the KPI total and its sparkline from that result in JS instead of running a separate aggregate query - one query serves both. When one result serves several graphs like this, anchor every graph it feeds with `targetEntityIds` (keep `target` on the primary) so each graph's details panel shows the live filtered query, not stale base SQL.
 - **Avoid redundant refreshes.** If a filter affects only some charts, split into targeted refresh functions (`refreshKPIs()`, `refreshCharts()`) so unchanged sections do not re-query.
 - **No polling.** NEVER use `setInterval(refresh, ...)`. Data sources update on their own schedule; a polling dashboard burns the entire budget.
 
@@ -151,7 +155,7 @@ You have full creative freedom: build charts with inline SVG, CSS, and HTML tabl
 <div data-graphit-id="spend-by-source"
      data-graphit-label="Ad Spend by Source"
      data-graphit-sql="SELECT {{dim:MEDIA_SOURCE_DIMENSION}} AS source, {{metric:TOTAL_AD_SPEND}} AS spend FROM MARKETING_UA_DS GROUP BY source ORDER BY spend DESC"
-     data-graphit-ds="ds_abc123">
+     data-graphit-ds="MARKETING_UA_DS">
   <div id="spend-chart" class="gh-loading">
     <!-- gh-loading-overlay spinner from the First-paint section -->
   </div>
@@ -160,7 +164,7 @@ You have full creative freedom: build charts with inline SVG, CSS, and HTML tabl
 (async function() {
   var r = await graphit.resolve({
     sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY MEDIA_SOURCE ORDER BY spend DESC",
-    dataSourceId: "ds_abc123",
+    dataSourceId: "MARKETING_UA_DS",
     target: "#spend-chart"
   });
   graphit.chart("#spend-chart", {

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

@@ -117,7 +117,7 @@ When the query feeds a canvas `graphit.resolve()` call, write it in the cache-fr
 
 ## Data source routing
 
-Always prefer a cached data source (`graphit query "SQL" --ds <id>`, roughly 100ms via DuckDB) over a live warehouse query (`graphit query "SQL" --warehouse --connection <id>`, roughly 10s via Snowflake). The full routing table, the `ds list` output template, and the source-shape guidance live in `data-sources.md`.
+Always prefer a cached data source (`graphit query "SQL" --ds <NAME>`, roughly 100ms via DuckDB) over a live warehouse query (`graphit query "SQL" --warehouse --connection <id>`, roughly 10s via Snowflake). Pass the data source name to `--ds` - the same name you SELECT FROM (a full id or unique id-prefix also works). The full routing table, the `ds list` output template, and the source-shape guidance live in `data-sources.md`.
 
 ## Percent scaling