@lightdash/cli 3.135.2 → 3.136.2

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

@@ -22,6 +22,7 @@ Users describe features by what they see in the Lightdash editor. Translate:
 | drill down, click into a chart | `drill-down` | app code opt-in |
 | drill into a viz data point (reusable visualization) | `viz-drill-down` | app code opt-in |
 | "ask the AI", one-line takeaway, explain this row | `ai-prompt` | app code opt-in |
+| "investigate this", act on a recommendation, agent digs beyond the page | `instruction-investigations` | app code opt-in |
 | "share this view", URL that restores state | `url-state` | app code opt-in |
 | "remember my filters", "keep my inputs", shared comments/targets/notes, "who changed this" | `app-state` | app code opt-in — only when the host has it enabled |
 | Google Sheets export | `gsheet-export` | app code opt-in |
@@ -208,6 +209,17 @@ 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`.
+- `instruction-investigations`: `useInvestigation()` returns `{ available,
+  investigate, status, explanation, partial, error, canContinue,
+  continueInAskAi }`; `investigate({ instruction, sources: [{ result, label }] })`
+  sends an author-written brief to the AI agent, which starts from those
+  loaded results and may run further read-only semantic-layer queries beyond
+  the page. One hook instance per control; the explanation is Markdown and
+  the run takes up to a couple of minutes, so show a running state. Hide the
+  control when `available` is false; trigger from a user action. Use it for
+  "investigate why" actions; keep `ai-prompt` for answers over loaded rows
+  only. Full contract in "Agent investigations on demand" 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

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

@@ -234,6 +234,59 @@ 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.
 
+## Agent investigations on demand (`useInvestigation`)
+
+> Use this when the user wants a button or pill that sends a written instruction to the AI **agent** so it can dig into the question using other data in Lightdash — "investigate what drove this", "act on this recommendation", "analyse the drivers" — with the findings shown inside the app. `useAiPrompt` only sees rows the app already loaded; `useInvestigation` runs the same agent as an anomaly Investigate, which can query other explores (read-only) to test drivers.
+
+```tsx
+import { useInvestigation, useLightdash } from '@lightdash/query-sdk';
+
+function DriverPill({ recommendation }: { recommendation: string }) {
+    // Keep the hook result itself: `sources` needs the object useLightdash
+    // returns, not a rebuilt { data, columns, ... }.
+    const revenue = useLightdash(revenueByMonth);
+    const investigation = useInvestigation();
+
+    if (!investigation.available || revenue.loading) return null;
+
+    return (
+        <div>
+            <button
+                disabled={investigation.status === 'running'}
+                onClick={() =>
+                    investigation.investigate({
+                        instruction: recommendation,
+                        sources: [{ result: revenue, label: 'Revenue by month' }],
+                    })
+                }
+            >
+                {investigation.status === 'running'
+                    ? 'Investigating…'
+                    : 'Investigate'}
+            </button>
+            {investigation.explanation && (
+                <Markdown>{investigation.explanation}</Markdown>
+            )}
+            {investigation.partial && (
+                <p>Stopped at the query budget; findings may be incomplete.</p>
+            )}
+            {investigation.error && <p role="alert">{investigation.error}</p>}
+            {investigation.canContinue && (
+                <button onClick={investigation.continueInAskAi}>
+                    Continue in Ask AI
+                </button>
+            )}
+        </div>
+    );
+}
+```
+
+- One `useInvestigation()` per control; a re-run replaces that control's result. Several pills mean several hook instances.
+- `sources` work exactly as in `useAiPrompt`: pass the object `useLightdash` returns, with an optional `label` the agent sees as the section title. The agent starts from these rows and may run further read-only semantic-layer queries under the viewer's own access.
+- The run takes up to a couple of minutes and the explanation is **Markdown** (the anomaly `InvestigationCard`'s rendering is a good model). Show a clear running state.
+- `available` is false outside a Lightdash host, when the organisation has AI off for data apps, on hosts that predate the capability, or while the viewer has no agent to run with. Hide the control; do not fall back to `useAiPrompt` silently for "investigate" asks — tell the user the host can't run investigations.
+- Trigger `investigate` only from a viewer's click; runs share the organisation's investigation rate limits and daily caps. Instructions are capped at 2000 characters; write them as a brief to an analyst.
+
 ## 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).

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 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.
+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. For a button that sends an author-written brief to the AI agent so it can investigate using data beyond the page ("investigate what drove this", "act on this recommendation"), use `useInvestigation` from the same reference ("Agent investigations on demand"); `useAiPrompt` cannot look at other explores. 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.135.2",
+  "version": "3.136.2",
   "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.135.2",
-    "@lightdash/warehouses": "3.135.2",
+    "@lightdash/common": "3.136.2",
+    "@lightdash/warehouses": "3.136.2",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",