@lightdash/cli 3.96.0 → 3.97.0

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

@@ -197,6 +197,10 @@ order, `sortBy` describes result ordering, `totalColumnCount` exposes truncation
   `instructions` prop on `InsightsSummary` (or `useInsights({ instructions })`
   in a custom block). One string per app, max 2000 characters. See "Author
   instructions" in `/app/references/ai-analysis.md`.
+- `analysis-on-load`: only when the user asks for the analysis to run on its
+  own ("analyse as soon as it loads"): set the `analyseOnLoad` prop on
+  `InsightsSummary` (or `useInsights({ analyseOnLoad: true })` in a custom
+  block). See "Analyse on load" in `/app/references/ai-analysis.md`.
 - `ai-prompt`: `useAiPrompt()` returns `{ available, ask, loading, text, error }`;
   `ask({ prompt, sources: [{ result, label }], focus?: { row } })` sends an
   author-written question over loaded `useLightdash` results and resolves to

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

@@ -49,7 +49,7 @@ const view = useInsights();
 // view.analyse()    ask Lightdash to (re)run the analysis
 ```
 
-Render `<InsightsSummary />` near the top of the page. It handles every status (idle, analysing, ready, error, stale) and renders nothing when unavailable. Props: `title`, `idleText`, `instructions`, `className`. Write your own block only when the user asks for a layout the component cannot give, and then keep every status branch.
+Render `<InsightsSummary />` near the top of the page. It handles every status (idle, analysing, ready, error, stale) and renders nothing when unavailable. Props: `title`, `idleText`, `instructions`, `analyseOnLoad`, `className`. Write your own block only when the user asks for a layout the component cannot give, and then keep every status branch.
 
 ### Author instructions for the analysis
 
@@ -63,6 +63,16 @@ Or equivalently `useInsights({ instructions })` in a custom block. One string pe
 
 The organization may also set default instructions in its settings; those apply first and the app's instructions are added after them, so keep app instructions to app-specific guidance (domain vocabulary) and leave org-wide style (language, currency) to the org default when the user says it should apply everywhere.
 
+### Analyse on load
+
+By default the analysis runs when the viewer clicks **Analyse**. When the user wants it to run on its own ("analyse as soon as it loads", "show the summary when the page opens"), set `analyseOnLoad`:
+
+```tsx
+<InsightsSummary analyseOnLoad />
+```
+
+Or equivalently `useInsights({ analyseOnLoad: true })` in a custom block. One value per app (the last value set wins). The host runs the analysis once the page's queries settle and again when the view changes; a stored analysis of the same rows is reused instead of re-run. Do not set it unless the user asked for it.
+
 Rules for the block:
 
 - Say "AI-generated" in the footer. Never name a model or provider.

package/dist/vendor/template/skill.md

@@ -779,7 +779,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 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.
 
 ## Visual Design
 

package/dist/vendor/template/src/components/insights/InsightsSummary.tsx

@@ -6,7 +6,7 @@ import { useInsights } from '@lightdash/query-sdk';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Loader2, RefreshCw, Sparkles } from 'lucide-react';
-import type { ReactNode } from 'react';
+import { useEffect, useState, type ReactNode } from 'react';
 
 type Props = {
     title?: ReactNode;
@@ -15,6 +15,8 @@ type Props = {
     /** Guidance for the analysis model: language/format rules and a line or
      *  two of domain vocabulary. One string per app. */
     instructions?: string;
+    /** Run the analysis when the view loads, without a click. */
+    analyseOnLoad?: boolean;
     className?: string;
 };
 
@@ -22,13 +24,30 @@ export function InsightsSummary({
     title = 'Executive summary',
     idleText = 'Click Analyse for an AI-generated read of everything on this page.',
     instructions,
+    analyseOnLoad,
     className,
 }: Props) {
     // Always pass the options object so clearing the prop clears the
     // guidance instead of leaving the previous value in force.
-    const view = useInsights({ instructions });
+    const view = useInsights({ instructions, analyseOnLoad });
+    // The host only starts once the app reports analyseOnLoad, so show the
+    // run as pending meanwhile; a short cap keeps an older host from
+    // leaving it stuck.
+    const [pendingAutoRun, setPendingAutoRun] = useState(!!analyseOnLoad);
+    useEffect(() => {
+        if (!pendingAutoRun) return undefined;
+        // `unavailable` is also the SDK's state before the host's first push.
+        if (view.status !== 'idle' && view.status !== 'unavailable') {
+            setPendingAutoRun(false);
+            return undefined;
+        }
+        const timer = setTimeout(() => setPendingAutoRun(false), 5000);
+        return () => clearTimeout(timer);
+    }, [pendingAutoRun, view.status]);
     if (view.status === 'unavailable') return null;
-    const busy = view.status === 'analysing';
+    const busy =
+        view.status === 'analysing' ||
+        (pendingAutoRun && view.status === 'idle');
 
     return (
         <Card className={className}>
@@ -52,7 +71,7 @@ export function InsightsSummary({
                 </Button>
             </CardHeader>
             <CardContent className="space-y-3">
-                {view.status === 'idle' && (
+                {view.status === 'idle' && !busy && (
                     <p className="text-sm text-muted-foreground">{idleText}</p>
                 )}
                 {busy && (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "3.96.0",
+  "version": "3.97.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.96.0",
-    "@lightdash/warehouses": "3.96.0",
+    "@lightdash/common": "3.97.0",
+    "@lightdash/warehouses": "3.97.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",