[pull] master from cube-js:master

.cursor/rules/namings-rule.mdc

@@ -25,6 +25,13 @@ Make sure to use correct terms.
     - **Workbook**
       - Tab
       - Dashboard builder
+        - **Widget**
+          - Charts
+          - Text
+          - Controls 
+            - Filter widget
+            - Time grain switcher
+          - AI summary
     - **Dashboard**
       - Scheduled refresh
     - **Semantic Model**

.cursor/rules/static-assets.mdc

@@ -0,0 +1,135 @@
+---
+description: How to upload and reference static images/assets for Mintlify docs
+globs: docs-mintlify/**
+alwaysApply: false
+---
+
+# Static assets for the Mintlify docs
+
+## Where assets live
+
+- **Editorial assets** (provider logos, UI screenshots, architecture diagrams,
+  recipe images, etc.) → S3 bucket `cube-dev-websites-shared`, served via CDN
+  at `https://static.cube.dev/<key>`. **Never** commit these binaries to the
+  repo.
+- **Site chrome** that ships with Mintlify itself (the favicon and the logos
+  in `docs-mintlify/logo/`) stays in the repo. Don't add new files there.
+
+If you're not sure: anything you'd reference from an `.mdx` page → S3.
+
+## Uploading editorial assets
+
+Use the script in `docs-mintlify/scripts/` (no AWS console clicks needed).
+Run it from the `docs-mintlify/` directory:
+
+```bash
+./scripts/upload-asset.sh <local-file> <dest-key>
+```
+
+Examples:
+
+```bash
+./scripts/upload-asset.sh ./snowflake.svg     icons/snowflake.svg
+./scripts/upload-asset.sh ./architecture.png  docs/getting-started/architecture.png
+./scripts/upload-asset.sh ./flow.svg          diagrams/pre-aggregations-flow.svg
+```
+
+The script prints (and copies to clipboard on macOS) the final
+`https://static.cube.dev/<key>` URL. Paste that URL into the relevant
+`.mdx` file.
+
+Full docs: `docs-mintlify/scripts/README.md`.
+
+## First-time AWS setup
+
+The upload script needs the AWS CLI and credentials for the
+`cube-dev-websites-shared` bucket. If `./scripts/upload-asset.sh` fails with
+`command not found: aws` or an AWS auth error, run through these steps once.
+
+If the user hasn't configured AWS yet, walk them through this — don't try to
+guess credentials or upload without a working profile.
+
+1. **Install the AWS CLI**
+
+   ```bash
+   brew install awscli         # macOS
+   # or: pipx install awscli    # cross-platform
+   ```
+
+2. **Get credentials**
+
+   You need an IAM user / SSO role with `s3:PutObject` and `s3:HeadObject`
+   on `cube-dev-websites-shared`. Ask whoever manages Cube's AWS account
+   (post in the internal infra/ops channel) — don't reuse personal keys.
+
+3. **Configure a local profile**
+
+   The script picks up the `cube-static` profile by default. Use that name
+   to avoid having to set `AWS_PROFILE` every time:
+
+   ```bash
+   aws configure --profile cube-static
+   # AWS Access Key ID:     <your key>
+   # AWS Secret Access Key: <your secret>
+   # Default region name:   us-west-2
+   # Default output format: json
+   ```
+
+   If you must use a different profile name, prefix every invocation:
+
+   ```bash
+   AWS_PROFILE=my-profile ./scripts/upload-asset.sh ./logo.svg icons/foo.svg
+   ```
+
+4. **Verify access** before your first real upload:
+
+   ```bash
+   aws sts get-caller-identity --profile cube-static
+   aws s3 ls s3://cube-dev-websites-shared/icons/ --profile cube-static | head
+   ```
+
+   Both commands should succeed. If `ls` returns an `AccessDenied` error,
+   credentials are wrong or lack S3 permissions — fix that before uploading.
+
+Never commit AWS keys to the repo or paste them into chat. They live only in
+`~/.aws/credentials` (or your SSO config).
+
+## Path conventions
+
+| Prefix                            | Use for                                            |
+| --------------------------------- | -------------------------------------------------- |
+| `icons/<slug>.svg`                | Provider / integration / vendor logos for `<Card>` |
+| `icons/<slug>-light.svg`          | Logo, light variant (use on dark backgrounds)      |
+| `icons/<slug>-dark.svg`           | Logo, dark variant (use on light backgrounds)      |
+| `docs/<section>/<slug>/<file>`    | Screenshots & images for a specific docs page      |
+| `diagrams/<slug>.svg`             | Architecture / flow diagrams                       |
+| `recipes/<slug>/<file>`           | Recipe-specific screenshots                        |
+
+Use kebab-case slugs. Match the existing `icons/<slug>.svg` pattern already
+referenced from pages like `admin/connect-to-data/visualization-tools/index.mdx`
+and `admin/deployment/providers/index.mdx` — don't invent a new top-level
+prefix when one of the above fits.
+
+For provider logos, prefer SVG. For UI screenshots, prefer PNG (or WebP for
+larger images). Compress before uploading — the bucket is cached aggressively.
+
+## Immutability rule
+
+Asset URLs are **immutable by convention** — files are served with
+`Cache-Control: public, max-age=31536000, immutable`. The upload script
+refuses to overwrite existing keys.
+
+When an asset needs to change:
+
+1. Upload a new key with a version suffix (e.g. `snowflake-v2.svg`).
+2. Update the `.mdx` reference in the same PR.
+
+Never use `--force` on an asset that is already live.
+
+## Don't
+
+- Don't commit screenshots, provider logos, or diagrams into `docs-mintlify/`
+  itself — they bloat the repo and Mintlify build, and can't be reused.
+- Don't reference Contentful (`ucarecdn.com`, `images.ctfassets.net`) URLs in
+  new docs content. Mirror to `static.cube.dev` first.
+- Don't reuse the same key for a different image. Bump the version suffix.

docs-mintlify/docs.json

@@ -102,7 +102,22 @@
           {
             "group": "Present & Share",
             "pages": [
-              "docs/explore-analyze/dashboards",
+              {
+                "group": "Dashboards",
+                "root": "docs/explore-analyze/dashboards/index",
+                "pages": [
+                  {
+                    "group": "Widgets",
+                    "root": "docs/explore-analyze/dashboards/widgets/index",
+                    "pages": [
+                      "docs/explore-analyze/dashboards/widgets/charts",
+                      "docs/explore-analyze/dashboards/widgets/text",
+                      "docs/explore-analyze/dashboards/widgets/controls",
+                      "docs/explore-analyze/dashboards/widgets/ai-summary"
+                    ]
+                  }
+                ]
+              },
               "docs/explore-analyze/scheduled-refreshes",
               "docs/explore-analyze/notifications"
             ]

docs-mintlify/docs/explore-analyze/dashboards.mdx → docs-mintlify/docs/explore-analyze/dashboards/index.mdx

@@ -16,6 +16,7 @@ Dashboards enable you to:
 
 ## How it works
 
-Select the reports you want to include from your [workbook][ref-workbooks], arrange them to tell your data story, and publish the dashboard. This gives stakeholders direct access to the insights that matter most, without the complexity of the underlying analysis.
+In the dashboard builder inside your [workbook][ref-workbooks], select the reports you want to include and arrange them on the canvas alongside other [widgets][ref-widgets] to tell your data story, then publish the dashboard. This gives stakeholders direct access to the insights that matter most, without the complexity of the underlying analysis.
 
-[ref-workbooks]: /analytics/workbooks
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-widgets]: /docs/explore-analyze/dashboards/widgets

docs-mintlify/docs/explore-analyze/dashboards/widgets/ai-summary.mdx

@@ -0,0 +1,39 @@
+---
+title: AI summary
+description: Generate natural-language summaries of dashboard data on demand using an AI agent.
+---
+
+AI summary widgets generate a natural-language summary of the data shown on the dashboard. Write a prompt — for example, _"Summarize the key trends and call out anything unusual"_ — and the configured [AI agent][ref-agents] produces a Markdown narrative based on the current dashboard state, including the data behind every chart and the values of any active [controls][ref-controls].
+
+## Adding an AI summary
+
+In the [dashboard builder][ref-workbooks], click **Add AI Summary** in the toolbar. The widget opens with a prompt editor — write your prompt and click **Generate Summary** to produce the first response.
+
+## Use cases
+
+- Add an executive summary at the top of a dashboard
+- Surface anomalies or notable changes since the last refresh
+- Explain numbers to stakeholders who want context without diving into the charts
+- Generate a TL;DR for periodic dashboard distributions
+
+## Writing a prompt
+
+Write the prompt as if you were briefing an analyst — describe the audience, the angle you want, and any specific things to call out. The agent has access to the full dashboard context, so you can reference charts and controls by name.
+
+## Caching
+
+Once generated, the summary is **cached** with the widget. Viewers loading the dashboard see the cached response immediately — they don't pay for regeneration on every page load.
+
+## Staleness detection
+
+The widget keeps a checksum of the dashboard state at the time of generation: the queries behind each chart, the active control values, and the chart configuration. When any of those change, the widget marks the cached summary as **stale** and shows a refresh prompt so viewers know the narrative may no longer match the data.
+
+Click the refresh icon (or open the widget menu and choose **Refresh**) to regenerate using the saved prompt against the latest state.
+
+## Choosing the agent
+
+By default, AI summaries use the agent configured at the dashboard level. You can override the agent per widget when you need a particular [agent's][ref-agents] tooling, model, or guardrails for a specific summary.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-agents]: /admin/ai/spaces-agents-models
+[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls

docs-mintlify/docs/explore-analyze/dashboards/widgets/charts.mdx

@@ -0,0 +1,30 @@
+---
+title: Charts
+description: Display reports from your workbook as visualizations on the dashboard.
+---
+
+Chart widgets display a report from the source [workbook][ref-workbooks] as a visualization on the dashboard. Every chart on a dashboard is backed by a tab in the workbook — when you publish a new version of the workbook, the chart updates accordingly.
+
+## Adding a chart
+
+In the [dashboard builder][ref-workbooks], open the **Charts** picker in the toolbar and select one or more reports from the workbook. A chart is added to the canvas for each selected report, inheriting the report's query, configured visualization, and styling.
+
+If the picker is empty, create the report first in a workbook tab — only published reports are available to add to a dashboard.
+
+## Interaction with controls
+
+Charts respect [controls][ref-controls] — filters and time grain switchers — placed on the same dashboard. A single control can drive multiple charts at once: its value is applied to every chart whose query references the targeted dimension.
+
+## Updating charts
+
+Charts on a published dashboard reflect the most recent published version of the workbook. To change the query, switch the chart type, or restyle the visualization, edit the underlying report in the workbook and publish a new version of the dashboard.
+
+## Title
+
+Each chart shows the name of the underlying workbook tab as its title. To rename it, open the tab in the workbook, rename the tab, and republish the dashboard — the new name flows through to every chart backed by that tab.
+
+Use **Hide Title** in the widget's settings menu to suppress the title on the dashboard — useful when the chart's content already makes the subject obvious, or when an adjacent [text widget][ref-text] provides its own heading. Choose **Show Title** in the same menu to bring it back.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls
+[ref-text]: /docs/explore-analyze/dashboards/widgets/text

docs-mintlify/docs/explore-analyze/dashboards/widgets/controls.mdx

@@ -0,0 +1,98 @@
+---
+title: Controls
+description: Filter and time grain switcher widgets that let dashboard viewers change what's shown on the dashboard.
+---
+
+Controls are widgets that let dashboard viewers change what's shown without leaving the dashboard. The dashboard builder offers two control types — both target a dimension from your semantic model and apply the selected value to every [chart][ref-charts] on the dashboard whose query references that dimension.
+
+- [Filter](#filter) — Narrow the data shown on the dashboard
+- [Time grain switcher](#time-grain-switcher) — Change the granularity of time-based dimensions
+
+## Filter
+
+Filter widgets let viewers narrow down the data shown on the dashboard. In the [dashboard builder][ref-workbooks], click **Add Filter** in the toolbar. The new filter is added in an unconfigured state — click **Configure Filter** (or open the widget's settings menu) to pick a semantic view and a dimension.
+
+### Operators by dimension type
+
+The available operators depend on the type of the underlying dimension:
+
+| Dimension type | Operators |
+|---|---|
+| **String** | `is`, `is not`, `contains`, `not contains`, `starts with`, `not starts with`, `ends with`, `not ends with`, `is null`, `is not null` |
+| **Number** | `is`, `is not`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `is null`, `is not null` |
+| **Time** | `is`, `is not`, `before date`, `before or on date`, `after date`, `after or on date`, `between`, `relative date`, `is null`, `is not null` |
+
+### Single vs. multiple selection
+
+Filters can allow either a single value or multiple values. Configure this when adding or editing the filter — multi-select is the default for string dimensions, while time and number dimensions default to a single value.
+
+### Default values
+
+You can set a default value that's applied when the dashboard loads. Defaults are useful for scoping the dashboard to "this quarter" or "the user's region" without requiring viewers to interact with the filter first.
+
+### Faceted filters
+
+When multiple filters target dimensions from the same semantic view, you can mark them as **faceted**. Faceted filters scope each other's value lists — selecting a value in one filter narrows the options shown in the others, so viewers only see combinations that exist in the data.
+
+For example, on a sales dashboard with a **Country** filter and a **City** filter, marking both as faceted means selecting `United States` in the Country filter limits the City filter to U.S. cities only.
+
+## Time grain switcher
+
+Time grain switchers let viewers change the granularity of time-based dimensions on the dashboard — for example, switching a revenue chart from daily to weekly or monthly. The widget targets a single time dimension and applies the chosen [granularity][ref-granularities] to every chart that groups by that dimension.
+
+In the [dashboard builder][ref-workbooks], click **Add Time Grain** in the toolbar. The new switcher is added in an unconfigured state — open its settings to pick a semantic view and a time dimension.
+
+### Allowed grains
+
+By default, viewers can choose between **day**, **week**, **month**, **quarter**, and **year**. You can narrow this list in the widget's settings to only expose the grains that make sense for the dashboard.
+
+For time dimensions backed by a `TIMESTAMP` or `DATETIME` column, sub-day grains (**second**, **minute**, **hour**) are also available. `DATE`-typed columns don't expose sub-day grains, since they would bucket the entire day into a single point.
+
+Custom granularities defined in the [data model][ref-granularities] appear in the list alongside the built-in grains.
+
+### Default grain
+
+You can configure a default grain that's applied when the dashboard loads. If no default is set, charts use the grain that was saved on the underlying report — viewers can still switch grains, but the dashboard opens with each chart at its original granularity.
+
+## Visibility
+
+Each control has a **Visibility** setting that determines how it appears on the published dashboard. The setting applies to both filters and time grain switchers.
+
+| Visibility | Behavior on the published dashboard |
+|---|---|
+| **Visible** (default) | Shown on the dashboard and viewers can change its value. |
+| **Hidden** | Not shown to viewers, but the control's value is still applied to the charts it targets. Use this to scope a dashboard with a fixed value — e.g., always filter to the current quarter — without exposing the control. |
+| **Disabled** | Shown on the dashboard so viewers can see the active value, but they cannot change it. |
+
+Set the visibility from the **Visibility** dropdown when editing the control. **Hidden** controls remain visible in the dashboard builder so editors can reconfigure them, but disappear from the published view.
+
+## Interaction with charts
+
+When a control is added to a dashboard, it's automatically wired up to every [chart][ref-charts] whose query already uses the same dimension. Charts that don't reference that dimension are left alone, so a dashboard can mix scoped and unscoped views by default. You can override this default per chart from its [Controls mapping](#controls-mapping) — disable the control for that chart, or remap it onto a different dimension.
+
+### Controls mapping
+
+Each chart decides which controls apply to it through its **Controls mapping**. The mapping is resolved automatically in most cases and only needs manual attention when a control targets a dimension the chart doesn't have.
+
+Open **Controls mapping** from a chart's settings menu to inspect or override the mapping for that chart. For each control on the dashboard you can:
+
+- **Toggle the control on or off** for the chart, even when a mapping exists
+- **Pick a different dimension** from the chart's semantic view to remap the control to
+
+Three states show up in the mapping sidebar:
+
+| Status | What it means |
+|---|---|
+| **Mapped automatically** | The control's dimension exists on the chart's semantic view, so it's wired up without configuration. |
+| **Manually mapped** | You (or an AI agent) picked a specific dimension for this chart. **Reset** restores the automatic mapping. |
+| **Can't map automatically** | The control targets a dimension that doesn't exist on the chart's semantic view. The chart is unaffected by the control until you map it manually. |
+
+For [time grain switchers][ref-time-grain], the dimension picker is restricted to time-typed dimensions on the chart's semantic view, since other dimension types can't be resolved by the time grain pipeline.
+
+Mappings are also configurable by AI agents when they build or edit a dashboard, so an agent can wire controls across charts that use different semantic views without you needing to revisit each chart manually.
+
+[ref-time-grain]: #time-grain-switcher
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-charts]: /docs/explore-analyze/dashboards/widgets/charts
+[ref-granularities]: /docs/data-modeling/dimensions

docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Widgets
+description: Building blocks for dashboards — charts, text, controls, and AI summaries that you arrange on the canvas to tell your data story.
+---
+
+Widgets are the building blocks of a dashboard. Each tile placed on the canvas in the [dashboard builder][ref-workbooks] is a widget — a chart, a block of text, a control that viewers interact with, or an AI-generated summary. Combine them to assemble polished, interactive views of your data.
+
+## Widget types
+
+The dashboard builder supports the following widget types:
+
+- [Charts](/docs/explore-analyze/dashboards/widgets/charts) — Visualize reports from your workbook
+- [Text](/docs/explore-analyze/dashboards/widgets/text) — Add titles, descriptions, and rich formatting in Markdown
+- [Controls](/docs/explore-analyze/dashboards/widgets/controls) — Let viewers filter the data or switch the time grain
+- [AI summary](/docs/explore-analyze/dashboards/widgets/ai-summary) — Generate narrative summaries of dashboard data on demand
+
+In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, or click **Add Text**, **Add Filter**, **Add Time Grain**, or **Add AI Summary** for the other types.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks