@lightdash/cli 3.124.0 → 3.126.0

package/dist/vendor/template/.claude/skills/sdk-features/SKILL.md

@@ -208,6 +208,14 @@ order, `sortBy` describes result ordering, `totalColumnCount` exposes truncation
   plain text. `result` is the object `useLightdash` returns (keep a reference
   to it even when destructuring), never a rebuilt `{ data, columns }`. Hide the control when `available` is false; trigger from a user
   action. Full contract in `/app/references/ai-analysis.md`.
+- `shared-ai-commentary`: `useSharedAiCommentary({ selectionKey, prompt,
+  sources, focus? })` saves a generated answer in shared app state keyed to
+  the current selection: the first viewer generates, later viewers of the
+  same selection read the saved text, anyone may edit it (`saveEdit`), and
+  the edited version is what others see. Build `selectionKey` with
+  `commentarySelectionKey(...)` from bounded controls (filters, tabs), never
+  row data. Needs both AI and saved app state available. See "Saved
+  commentary shared between viewers" in `/app/references/ai-analysis.md`.
 - `space-charts`: `useSpaceCharts('<space slug or uuid>')` returns
   `{ available, space, charts, loading, error, refresh }` — the saved charts
   the viewer can see in that space, resolved at runtime with the viewer's own

package/dist/vendor/template/references/ai-analysis.md

@@ -234,6 +234,76 @@ function RevenueTakeaway() {
 - Trigger `ask` from a user action, or at most once per loaded view. Never on a timer, never per row. Prompts are rate limited per viewer.
 - Prompts are capped at 2000 characters; write them as instructions to an analyst, and name the audience and the length you want.
 
+## Saved commentary shared between viewers (`useSharedAiCommentary`)
+
+> Use this when the user wants generated commentary to be **saved** — "save the summary for the team", "everyone should see the same commentary", "let people edit the AI text", "keep the narrative with this view". It needs BOTH AI analysis and saved app state available (see the prompt's availability lines); without either, fall back to `useAiPrompt` (no saving) or plain `useSharedAppState` (no generation).
+
+`useAiPrompt` answers one viewer once; `useSharedAiCommentary` keys the answer to the current selection and stores it in shared app state, so the first viewer generates it, later viewers of the same selection read the saved text, and anyone may edit it. The edited text is what later viewers see.
+
+```tsx
+import {
+    commentarySelectionKey,
+    useLightdash,
+    useSharedAiCommentary,
+} from '@lightdash/query-sdk';
+
+function RegionCommentary({ region, period }: { region: string; period: string }) {
+    const revenue = useLightdash(revenueQuery);
+    const c = useSharedAiCommentary({
+        // Same selection => same saved commentary, for every viewer.
+        selectionKey: commentarySelectionKey('region', region, 'period', period),
+        prompt: `In three sentences, what should a sales lead know about ${region} revenue for ${period}?`,
+        sources: [{ result: revenue, label: 'Revenue' }],
+    });
+    const [draft, setDraft] = useState<string | null>(null);
+
+    if (c.meta.loading || revenue.loading) return null;
+    return (
+        <section>
+            {c.commentary ? (
+                draft === null ? (
+                    <>
+                        <p>{c.commentary.text}</p>
+                        <footer className="text-xs text-muted-foreground">
+                            {c.commentary.edited
+                                ? `Edited by ${c.meta.updatedBy?.name ?? 'a viewer'}`
+                                : 'AI-generated'}
+                        </footer>
+                        <button onClick={() => setDraft(c.commentary!.text)}>Edit</button>
+                        {c.canGenerate && (
+                            <button disabled={c.generating} onClick={() => c.generate()}>
+                                Regenerate
+                            </button>
+                        )}
+                    </>
+                ) : (
+                    <>
+                        <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
+                        <button onClick={() => { c.saveEdit(draft); setDraft(null); }}>Save</button>
+                        <button onClick={() => setDraft(null)}>Cancel</button>
+                    </>
+                )
+            ) : (
+                c.canGenerate && (
+                    <button disabled={c.generating} onClick={() => c.generate()}>
+                        {c.generating ? 'Generating…' : 'Generate commentary'}
+                    </button>
+                )
+            )}
+        </section>
+    );
+}
+```
+
+Rules:
+
+- **`selectionKey` names the selection, not the data**: build it with `commentarySelectionKey(...)` from the filter values, segment ids or tab names that define what the viewer is looking at. Never include row values or timestamps. One key per distinct selection; shared app state allows 200 keys per app, so key on controls with bounded choices (a region picker, a period), not free-text search terms.
+- `prompt`, `sources` and `focus` work exactly as in `useAiPrompt`; the generated text is saved with the prompt and a `promptId` for provenance, `edited: false`.
+- Generation replaces any saved text (the Regenerate case) — trigger it from a click, never on load. Reading saved commentary is free and works even when `canGenerate` is false, so always render saved text regardless.
+- Label the text "AI-generated" until `commentary.edited` is true; then show who edited it from `meta.updatedBy`.
+- The saved text is visible to **every** viewer of the app, including viewers whose data permissions would show them different rows. That is the point of the feature — it behaves like a comment — but do not build it over data some viewers must not see described in words.
+- Storage errors surface on `meta.error`; generation errors on `error`. Handle both like any other state.
+
 ## What the app must not do
 
 - Do not send rows or field values anywhere. The hooks expose results; Lightdash already has the data.

package/dist/vendor/template/skill.md

@@ -781,7 +781,7 @@ For any external HTTP API call, read `/app/references/external-apis.md` and use
 
 ### AI analysis — executive summary and anomalies
 
-When the user asks for AI analysis, an executive summary, "what changed and why", anomaly callouts, or any AI-generated insight about the data on the page, read `/app/references/ai-analysis.md` and build its **Default build** with the shipped components in `src/components/insights/` (`InsightsSummary`, `InsightMarker` / `insightCellProps`, `InvestigateMenuItem`, `InvestigationCard`): summary block at the top, markers on every query-bound chart, Investigate in every point menu, the investigation card under the chart. A short ask gets the whole set; only a narrower ask ("just a summary") gets a subset. Never rewrite those components. Lightdash runs the analysis over the queries the app already loaded and pushes the result in; the app renders it and never sends rows or keys. The components render nothing when the host has no analysis to offer. For an author-written question over loaded results (a takeaway under a chart, "explain this row"), use `useAiPrompt` from the same reference. When the user wants the summaries written a certain way (language, currency, domain vocabulary), pass it via the `instructions` prop on `InsightsSummary` — see "Author instructions" in the same reference. When the user wants the analysis to run as soon as the app loads, set the `analyseOnLoad` prop on `InsightsSummary` — see "Analyse on load" in the same reference; never set it unasked.
+When the user asks for AI analysis, an executive summary, "what changed and why", anomaly callouts, or any AI-generated insight about the data on the page, read `/app/references/ai-analysis.md` and build its **Default build** with the shipped components in `src/components/insights/` (`InsightsSummary`, `InsightMarker` / `insightCellProps`, `InvestigateMenuItem`, `InvestigationCard`): summary block at the top, markers on every query-bound chart, Investigate in every point menu, the investigation card under the chart. A short ask gets the whole set; only a narrower ask ("just a summary") gets a subset. Never rewrite those components. Lightdash runs the analysis over the queries the app already loaded and pushes the result in; the app renders it and never sends rows or keys. The components render nothing when the host has no analysis to offer. For an author-written question over loaded results (a takeaway under a chart, "explain this row"), use `useAiPrompt` from the same reference. When the user wants the summaries written a certain way (language, currency, domain vocabulary), pass it via the `instructions` prop on `InsightsSummary` — see "Author instructions" in the same reference. When the user wants the analysis to run as soon as the app loads, set the `analyseOnLoad` prop on `InsightsSummary` — see "Analyse on load" in the same reference; never set it unasked. When the user wants generated commentary **saved and shared** — "save the summary for the team", "everyone sees the same commentary", "let people edit the AI text" — and the prompt says saved app state is available, use `useSharedAiCommentary` from the same reference ("Saved commentary shared between viewers") instead of `useAiPrompt`; it keys the text to the current selection so later viewers read and edit the saved version instead of regenerating.
 
 ## Visual Design
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "3.124.0",
+  "version": "3.126.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "3.124.0",
-    "@lightdash/warehouses": "3.124.0",
+    "@lightdash/common": "3.126.0",
+    "@lightdash/warehouses": "3.126.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",