[pull] master from cube-js:master

docs-mintlify/docs.json

@@ -52,6 +52,7 @@
                 "root": "docs/explore-analyze/workbooks/index",
                 "pages": [
                   "docs/explore-analyze/workbooks/querying-data",
+                  "docs/explore-analyze/workbooks/calculated-fields",
                   "docs/explore-analyze/workbooks/source-sql-tabs",
                   "docs/explore-analyze/workbooks/charts"
                 ]
@@ -68,6 +69,13 @@
               "docs/explore-analyze/notifications"
             ]
           },
+          {
+            "group": "Organize content",
+            "pages": [
+              "docs/organize-content/folders",
+              "docs/organize-content/sharing"
+            ]
+          },
           {
             "group": "Data Modeling",
             "pages": [

docs-mintlify/docs/data-modeling/ai-context.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI context
-description: Optimize your data model for AI by using descriptions and the meta ai_context property to provide additional context.
+description: Improve AI accuracy and trust by enriching your semantic layer with descriptions and AI-specific context that helps agents generate better insights.
 ---
 
 When using [Analytics Chat][ref-analytics-chat] or other AI-powered features,

docs-mintlify/docs/data-modeling/overview.mdx

@@ -1,6 +1,6 @@
 ---
 title: Getting started
-description: Introduces how Cube turns warehouse tables into a reusable semantic layer that powers metrics, dimensions, and API-driven analytics without ad hoc SQL per question.
+description: Build a reusable semantic layer that provides the shared context for AI agents, BI dashboards, and embedded analytics — turning warehouse tables into governed metrics and dimensions.
 ---
 
 The data model is used to transform raw data into meaningful business

docs-mintlify/docs/explore-analyze/analytics-chat.mdx

@@ -1,9 +1,9 @@
 ---
 title: Analytics Chat
-description: Overview of the AI chat experience for asking natural-language questions against your semantic layer with optional embedding and Workbook handoff.
+description: Conversational analytics interface for asking plain-language questions and getting trusted, AI-powered insights from your semantic layer.
 ---
 
-Analytics Chat is a conversational interface that allows you to explore your data using natural language. Ask questions and get AI-powered insights without writing queries or building visualizations manually.
+Analytics Chat is Cube's conversational analytics experience — ask questions in plain language and get trusted, AI-powered insights without writing queries or building visualizations.
 
 ## How it works
 

docs-mintlify/docs/explore-analyze/explore.mdx

@@ -1,6 +1,6 @@
 ---
 title: Explore
-description: Start governed, shareable explorations from Analytics Chat or dashboards without creating a workbook, then graduate analysis into Workbooks when needed.
+description: Self-serve data exploration from Analytics Chat, dashboards, or any semantic view — governed by your data model, shareable via URL.
 ---
 
 Explore is a quick way to explore data in your semantic layer either by point and click or with an AI agent. Unlike workbooks, Explore doesn't require you to create a workbook—you can start exploring immediately from dashboard, analytics chat or any semantic view.

docs-mintlify/docs/explore-analyze/workbooks/calculated-fields.mdx

@@ -0,0 +1,89 @@
+---
+title: Calculated fields
+description: Create ad-hoc custom dimensions and measures with Semantic SQL in workbooks, with help from AI or the field picker.
+---
+
+Calculated fields are ad-hoc dimensions and measures you add only to the current
+workbook report. They do not change the shared data model.
+
+As described in [Semantic SQL](/docs/introduction#semantic-sql), Cube routes
+analysis through the semantic layer instead of sending arbitrary SQL straight to
+the warehouse. The runtime validates every request and applies your security
+policies. Semantic SQL builds on Postgres-compatible SQL—including the
+`MEASURE()` function—so you can express derived logic on top of existing
+semantic definitions with both flexibility and governance.
+
+Calculated fields are expressed as Semantic SQL and pushed down to the Cube
+backend for evaluation. The semantic layer compiles them with the rest of the
+query—rather than applying them only in the browser—so the same validation,
+governance, and warehouse execution path apply as for any other Semantic SQL
+analysis.
+
+## Using AI to create calculated fields
+
+You can ask the Cube AI agent to create custom calculations in natural language.
+The agent can add or refine calculated fields from different parts of the
+product—for example while exploring in **Analytics chat** or working in
+**Workbooks**—so you are not limited to a single entry point when you want a new
+metric or dimension for the analysis in front of you.
+
+## Creating calculated fields in UI
+
+You can also build and edit calculated fields directly in the workbook. New
+fields appear in the **Calculated fields** section of the field picker sidebar.
+
+### Aggregations from existing dimensions
+
+Right-click a dimension column header and choose an aggregation to create a
+calculated field automatically. Available aggregations depend on the column type:
+
+| Column type | Available aggregations |
+| --- | --- |
+| Number | Count Distinct, Sum, Average, Min, Max |
+| Time | Count Distinct, Min, Max |
+| String, Boolean | Count Distinct |
+
+### Calculations from existing measures
+
+Open the menu on a measure column header and use the **Calculations** submenu
+for derived calculations:
+
+| Calculation | Description |
+| --- | --- |
+| % of total | Ratio of the measure value to the total across all rows |
+| % of previous | Ratio of the measure value to the previous row's value |
+| % change from previous | Percentage change compared to the previous row |
+| Running total | Cumulative sum of the measure across rows |
+
+<Info>
+
+**% of previous**, **% change from previous**, and **Running total** require at
+least one dimension in the query.
+
+</Info>
+
+Which calculations are offered depends on the measure’s aggregation type:
+
+| Aggregation type | Available calculations |
+| --- | --- |
+| Count, Sum | All calculations |
+| Min, Max | Running total |
+| Average, Count Distinct | None |
+
+### Filtered measures
+
+When working with query **Results**, pivot so at least one dimension is on
+columns, then open the header menu on a **pivoted measure column** and choose
+**Create filtered measure**. Cube adds a calculated measure that applies the
+column’s slice—for example, from **Count** broken down by **Status**, you get a
+measure that only aggregates rows matching that status (such as completed
+orders only).
+
+The option appears only for **native** measures on pivoted columns, not for
+calculated fields. The same flow works in **Explore** when results are pivoted
+the same way.
+
+### Editing a calculated field
+
+Select a calculated field in the sidebar to open the editor. You can change its
+**name** and **SQL expression**, then choose **Update** to apply.

docs-mintlify/docs/explore-analyze/workbooks/index.mdx

@@ -1,10 +1,10 @@
 ---
-description: "Build reports with an AI agent, organize analyses across multiple tabs, and share insights with your team."
+description: "Build reports and explore data with AI agents, organize analyses across multiple tabs, and share trusted insights with your team."
 title: Workbooks
 ---
 
-Workbooks allow you to build reports with an AI agent, organize the results of your
-analysis, and share insights with your team.
+Workbooks allow you to build reports and explore data with AI agents, organize the results of your
+analysis, and share trusted insights with your team.
 
 ## Tabs
 

docs-mintlify/docs/getting-started/embed-analytics.mdx

@@ -1,9 +1,9 @@
 ---
 title: Embed analytics
-description: Choose among iframe embeds, the Analytics Chat API, and headless core APIs depending on how much UI and authentication control you need.
+description: Ship agentic embedded analytics in your product — choose among iframe embeds, the conversational Chat API, or headless core APIs for full control.
 ---
 
-Cube offers rich options for embedded analytics. You can embed [dashboards][ref-dashboards] and [analytics chat][ref-analytics-chat] as iframes, use the [Analytics Chat API][ref-chat-api] directly to create your own conversational analytics experience, or use [Core Data APIs][ref-core-apis] directly to build custom visualizations, reporting, and dashboarding experiences.
+Cube offers rich options for embedded analytics. You can embed [dashboards][ref-dashboards] and [analytics chat][ref-analytics-chat] as iframes, use the [Chat API][ref-chat-api] directly to create your own conversational analytics experience, or use [Core Data APIs][ref-core-apis] directly to build custom visualization, reporting, and dashboarding experiences.
 
 ## Embed with iframes
 

docs-mintlify/docs/introduction.mdx

@@ -1,10 +1,10 @@
 ---
 title: Introduction
-description: Cube is the business intelligence platform powered by the open-source semantic layer.
+description: Cube is the agentic analytics platform for business intelligence and embedded analytics, powered by the open-source semantic layer.
 hideTableOfContents: true
 ---
 
-Cube uses AI agents to build data models and enable data consumers to perform analysis. Use AI to quickly build semantic layer and fully control the analytics context.
+The AI analytics platform that combines self-serve conversational analytics, governed data modeling, and embedded analytics — all powered by an open-source semantic layer.
 
 <iframe
   width="100%"
@@ -16,15 +16,15 @@ Cube uses AI agents to build data models and enable data consumers to perform an
   allowFullScreen
 />
 
-Cube is a new generation of a business intelligence and embedded analytics platform built to be used by both humans and AI agents. It empowers different personas across your organization:
+Cube is an AI analytics platform for the whole organization — built to be used by both humans and AI agents. It combines self-serve conversational analytics, governed data modeling, and embedded analytics experiences, all on top of an open-source semantic layer. It empowers different personas across your organization:
 
-- **Data Engineers** can quickly curate data models with AI assistance, accelerating the development and maintenance of semantic layers
-- **Data Analysts** can perform deep analysis with AI assistance, diving into complex data relationships and patterns
-- **Business Users** benefit from workbooks and dashboards that Cube can automatically build and maintain
+- **Data Engineers** can quickly curate data models with AI assistance, accelerating development and reducing time-to-insight for the whole organization
+- **Data Analysts** can perform deep analysis with AI assistance, getting trusted answers without writing ad-hoc SQL
+- **Business Users** can self-serve with natural language questions, workbooks, and dashboards — no tickets to the data team required
 
 ## How is Cube different?
 
-At the foundation of Cube's agentic analytics platform is an [open-source semantic layer](https://github.com/cube-js/cube)—the critical infrastructure that enables both AI agents and humans to work with trusted, consistent data.
+At the foundation of Cube's agentic analytics platform is an [open-source semantic layer](https://github.com/cube-js/cube) — the shared context that enables both AI agents and humans to work with trusted, consistent data.
 
 The semantic layer provides the governed data foundation that makes agentic analytics possible. It organizes data from your cloud data warehouses into centralized, consistent definitions that AI agents can reliably query, explore, and reason about. Without a semantic layer, AI agents would struggle with inconsistent metrics, scattered business logic, and ungoverned data access—making their outputs unreliable and potentially dangerous.
 

docs-mintlify/docs/organize-content/folders.mdx

@@ -0,0 +1,144 @@
+---
+title: Folders
+description: Organize workbooks, dashboards, and explorations into a hierarchical folder structure for easy navigation and access control.
+---
+
+As your team creates workbooks, dashboards, and explorations, folders help you
+keep content organized and easy to find. Folders provide a hierarchical
+structure that mirrors how your team thinks about its data — by team,
+project, domain, or any other grouping that makes sense.
+
+## Creating folders
+
+To create a folder:
+
+1. Navigate to the **Workspace** page.
+2. Click **New folder**.
+3. Enter a name for the folder (up to 255 characters).
+4. Click **Create**.
+
+You can also create folders inside existing folders to build a nested
+hierarchy. Open the parent folder first, then follow the same steps.
+
+{/* Screenshot: Workspace page with the "New folder" button visible in the
+toolbar and the folder name dialog open, showing the name input field and
+Create button. */}
+
+<Info>
+
+Folder names must be unique within the same parent folder.
+
+</Info>
+
+## Nesting folders
+
+Folders support up to **10 levels** of nesting, allowing you to build
+detailed hierarchies. For example:
+
+```text
+Workspace (root)
+└── Marketing
+    └── Campaigns
+        └── Q1 2025
+            └── Email Performance
+```
+
+Each level provides further categorization while keeping content accessible
+through the folder tree.
+
+## What can go in a folder
+
+Folders can contain the following content types:
+
+- **Workbooks** — multi-tab analyses built with the semantic layer or
+  source SQL
+- **Dashboards** — published views of workbook reports
+- **Explorations** — saved explorations from Analytics Chat or the Explore
+  page
+
+Content that is not placed in a folder appears at the root level of your
+workspace.
+
+{/* Screenshot: Workspace page showing a folder containing a mix of content
+types — at least one workbook, one dashboard, and one exploration visible
+in the list. */}
+
+## Moving content into folders
+
+To move a workbook, dashboard, or exploration into a folder, open the
+item's action menu and select **Move**. Choose the target folder from the
+folder picker and confirm. You can also move items to the root level by
+selecting the workspace root as the destination.
+
+{/* Screenshot: The folder picker dialog that appears after clicking "Move" on
+a workbook, showing the folder tree with nested folders to choose from and
+a confirm button. */}
+
+## Renaming folders
+
+To rename a folder:
+
+1. Open the folder's action menu.
+2. Select **Rename**.
+3. Enter the new name.
+4. Click **Save**.
+
+{/* Screenshot: A folder's action menu (three-dot / context menu) open, showing
+options including Rename, Move, Share, and Delete. */}
+
+<Info>
+
+The new name must be unique within the same parent folder.
+
+</Info>
+
+## Moving folders
+
+You can rearrange your folder hierarchy by moving folders to a different
+parent:
+
+1. Open the folder's action menu.
+2. Select **Move**.
+3. Choose the new parent folder (or the workspace root).
+4. Confirm the move.
+
+<Warning>
+
+A folder cannot be moved into one of its own subfolders.
+
+</Warning>
+
+## Deleting folders
+
+To delete a folder:
+
+1. Open the folder's action menu.
+2. Select **Delete**.
+
+<Warning>
+
+A folder can only be deleted if it contains no subfolders. Move or delete
+any subfolders first.
+
+</Warning>
+
+## Folder permissions
+
+Folder access is controlled through three permission levels:
+
+| Level | Allows |
+| --- | --- |
+| **Can view** | View the folder and its contents |
+| **Can edit** | Rename the folder, move content into it, and create subfolders |
+| **Full access** | Full control including moving and deleting the folder, and managing folder permissions |
+
+The creator of a folder automatically receives **Full access**.
+
+To learn how to share folders with users, groups, or your entire
+organization — and how permissions are inherited by content inside
+folders — see [Share content][ref-sharing].
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-dashboards]: /docs/explore-analyze/dashboards
+[ref-sharing]: /docs/organize-content/sharing
+[ref-roles]: /admin/users-and-permissions/roles-and-permissions