docs: update embedding docs

.cursor/rules/namings-rule.mdc

@@ -45,6 +45,48 @@ Make sure to use correct terms.
       - Management APIs
         - Orchestration API
   - **Embedding**
-    - Private embedding
-    - Signed embedding
-    - Creator Mode
+    - Iframe embedding (the integration approach where Cube content is embedded via iframes)
+      - What you can embed:
+        - Dashboards
+        - Analytics Chat
+        - Creator Mode
+      - Authentication:
+        - Private embedding (auth mode for internal users with Cube accounts)
+        - Signed embedding (auth mode for external/customer-facing applications; required for Creator Mode)
+    - SDK embedding (the integration approach using the React Embed SDK)
+    - Headless embedding (the integration approach using Cube APIs directly — Embed APIs and Core Data APIs)
+
+# Embedding Terminology
+
+When categorizing embedding approaches, use these three parallel terms:
+
+- **Iframe embedding** — drop-in via iframes; Cube ships the full UI
+- **SDK embedding** — via the React Embed SDK; Cube ships components, you compose
+- **Headless embedding** — via Embed APIs and Core Data APIs; you build the UI
+
+Notes:
+- Do not use `-based` suffixes (e.g., "iframe-based embedding", "API-based embedding"). Prefer the bare terms above.
+- Use **Iframe** (capitalized at sentence start, lowercase mid-sentence). Do not use "iFrame".
+- "API-based embedding" is ambiguous because **API** has specific product meaning (Embed APIs, Core Data APIs, Management APIs, Orchestration API). Use **Headless embedding** instead.
+
+## Iframe embedding axes
+
+Iframe embedding has two independent axes:
+
+- **What you embed** (primary axis): Dashboards, Analytics Chat, Creator Mode
+- **Authentication** (secondary, cross-cutting axis): Private embedding, Signed embedding
+
+Compatibility matrix:
+
+|                  | Private embedding | Signed embedding |
+|------------------|:-----------------:|:----------------:|
+| Dashboards       | ✓                 | ✓                |
+| Analytics Chat   | ✓                 | ✓                |
+| Creator Mode     | —                 | ✓                |
+
+Page naming inside the **Iframe embedding** group:
+
+- Do not prefix page titles with "Embed" or "Embedding" — it is redundant under the group label.
+  - Use **Dashboards**, **Analytics Chat**, **Creator Mode** (not "Embed a dashboard", "Embed Analytics Chat", etc.)
+  - Use **Private embedding**, **Signed embedding** for the auth-mode pages (the word "embedding" is part of the product term itself).
+

docs-mintlify/docs.json

@@ -115,7 +115,8 @@
                       "docs/explore-analyze/dashboards/widgets/controls",
                       "docs/explore-analyze/dashboards/widgets/ai-summary"
                     ]
-                  }
+                  },
+                  "docs/explore-analyze/dashboards/styling"
                 ]
               },
               "docs/explore-analyze/scheduled-refreshes",
@@ -409,11 +410,23 @@
             "group": "Embedding",
             "pages": [
               "embedding/index",
-              "embedding/private-embedding",
-              "embedding/signed-embedding",
-              "embedding/creator-mode",
-              "embedding/react-embed-sdk",
-              "embedding/vizard"
+              "embedding/react-embed-sdk"
+            ]
+          },
+          {
+            "group": "Iframe embedding",
+            "pages": [
+              "embedding/iframe/dashboards",
+              "embedding/iframe/analytics-chat",
+              "embedding/iframe/creator-mode",
+              "embedding/iframe/customization",
+              {
+                "group": "Authentication",
+                "pages": [
+                  "embedding/iframe/auth/private",
+                  "embedding/iframe/auth/signed"
+                ]
+              }
             ]
           },
           {
@@ -691,5 +704,17 @@
     }
   },
   "redirects": [
+    {
+      "source": "/embedding/private-embedding",
+      "destination": "/embedding/iframe/auth/private"
+    },
+    {
+      "source": "/embedding/signed-embedding",
+      "destination": "/embedding/iframe/auth/signed"
+    },
+    {
+      "source": "/embedding/creator-mode",
+      "destination": "/embedding/iframe/creator-mode"
+    }
   ]
 }

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

@@ -0,0 +1,60 @@
+---
+title: Styling
+description: Customize the appearance of a dashboard from the Styling panel in the Dashboard Builder.
+---
+
+You can customize the appearance of any dashboard — background, padding, widget cards, borders, titles, and fonts — from the **Styling** panel in the Dashboard Builder.
+
+Styling is **per-dashboard**: settings are saved to the dashboard's configuration and apply equally to the dashboard in Cube and to its [embedded view](/embedding/iframe/dashboards) (both [private](/embedding/iframe/auth/private) and [signed](/embedding/iframe/auth/signed) embedding).
+
+## Open the Styling panel
+
+1. Open your dashboard
+2. Click **Dashboard Builder** in the top bar
+3. Click the gear icon to open the **Styling** panel
+
+Click **Apply** to preview your changes. Click **Reset** to revert to the defaults. Publish the dashboard for the styling to take effect in embedded views.
+
+## Options
+
+All values accept standard CSS — colors as hex (`#1a1a2e`), `rgb()`, or named colors; lengths as CSS units (e.g., `16px`).
+
+### Background
+
+Settings that apply to the dashboard canvas as a whole.
+
+| Option       | Description                                        | Example     |
+|--------------|----------------------------------------------------|-------------|
+| Background   | Dashboard background color                         | `#f9f9fb`   |
+| Padding      | Outer padding around the dashboard grid            | `16px`      |
+
+### Widgets
+
+Settings that apply to every widget (chart card) on the dashboard.
+
+| Option       | Description                                        | Example     |
+|--------------|----------------------------------------------------|-------------|
+| Background   | Widget card background color                       | `#ffffff`   |
+| Padding      | Inner padding within each widget                   | `12px`      |
+
+### Widgets → Borders
+
+Border styling for widget cards.
+
+| Option   | Description                                                          | Example     |
+|----------|----------------------------------------------------------------------|-------------|
+| Color    | Border color                                                         | `#E1E2E8`   |
+| Radius   | Corner radius                                                        | `8px`       |
+| Style    | Border style (`solid`, `dashed`, `dotted`, `double`, `none`)         | `solid`     |
+| Width    | Border thickness                                                     | `1px`       |
+
+### Widgets → Titles
+
+Typography for widget titles.
+
+| Option       | Description                  | Example       |
+|--------------|------------------------------|---------------|
+| Color        | Title text color             | `#1a1a2e`     |
+| Font Size    | Title font size              | `18px`        |
+| Font Weight  | Title font weight            | `600`         |
+| Font Family  | Title font family            | `system-ui`   |

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

@@ -21,5 +21,5 @@ If you want complete control over visualizations and user interfaces, you can us
 [ref-analytics-chat]: /analytics/analytics-chat
 [ref-chat-api]: /reference/embed-apis/chat-api
 [ref-core-apis]: /reference/core-data-apis
-[ref-private-embedding]: /embedding/private-embedding
-[ref-signed-embedding]: /embedding/signed-embedding
+[ref-private-embedding]: /embedding/iframe/auth/private
+[ref-signed-embedding]: /embedding/iframe/auth/signed

docs-mintlify/embedding/iframe/analytics-chat.mdx

@@ -0,0 +1,49 @@
+---
+title: Analytics Chat
+description: Embed Cube Analytics Chat into your applications via iframe.
+---
+
+<Info>
+  Iframe embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing).
+</Info>
+
+Embed [Analytics Chat](/docs/explore-analyze/analytics-chat) into your application using an iframe. Let your users ask questions in plain language and get trusted answers powered by your semantic layer — without leaving your product.
+
+Analytics Chat can be embedded with either authentication mode:
+
+- **[Private embedding](/embedding/iframe/auth/private)** — for internal users with Cube accounts
+- **[Signed embedding](/embedding/iframe/auth/signed)** — for external/customer-facing applications using server-generated sessions
+
+## Embed with private embedding
+
+The embed URL for Analytics Chat is always the same:
+
+```html
+<iframe
+  title="Analytics Chat"
+  src="https://your-account.cubecloud.dev/embed/chat"
+  width="100%"
+  height="800"
+></iframe>
+```
+
+Users will be prompted to sign in with their Cube credentials when accessing the embedded chat. See [Private embedding](/embedding/iframe/auth/private) for details on the auth model.
+
+## Embed with signed embedding
+
+To embed Analytics Chat for external/customer-facing applications, generate a session on your backend and pass the session ID into the iframe:
+
+```html
+<iframe
+  title="Analytics Chat"
+  src="https://your-tenant.cubecloud.dev/embed/chat?sessionId=YOUR_SESSION_ID"
+  width="100%"
+  height="800"
+></iframe>
+```
+
+See [Signed embedding](/embedding/iframe/auth/signed) for the full session generation flow, API key setup, and a complete working example.
+
+## Personalize chat with user attributes
+
+When using signed embedding, you can pass [user attributes](/embedding/iframe/auth/signed#user-attributes) during session generation to personalize chat responses for each user — for example, scoping answers to a specific region, department, or tenant.

docs-mintlify/embedding/private-embedding.mdx → docs-mintlify/embedding/iframe/auth/private.mdx

@@ -1,45 +1,30 @@
 ---
 title: Private embedding
-description: Private embedding is available on Premium and Enterprise plans.
+description: Authenticate iframe-embedded Cube content with users' existing Cube accounts.
 ---
 
 <Info>
   Private embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing).
 </Info>
 
-Private embedding is designed for **internal use cases** where team members already have Cube accounts. Simply drop an iframe into your internal tools—no API keys or complex setup required. Users will authenticate with their existing Cube credentials when accessing embedded content.
+Private embedding is designed for **internal use cases** where team members already have Cube accounts. Simply drop an iframe into your internal tools — no API keys or session generation required. Users authenticate with their existing Cube credentials when accessing embedded content.
 
-## How it works
-
-To embed Cube content, you simply need to paste an `<iframe>` tag into your application or tool. Get the embed code and paste it wherever you want the content to appear.
-
-### Analytics Chat
+Use private embedding to embed:
 
-The embed URL for Analytics Chat is always the same:
+- [Dashboards](/embedding/iframe/dashboards)
+- [Analytics Chat](/embedding/iframe/analytics-chat)
 
-```html
-<iframe
-  title="Analytics Chat"
-  src="https://your-account.cubecloud.dev/embed/chat"
-  width="100%"
-  height="800"
-></iframe>
-```
+<Note>
+  Private embedding does not support [Creator Mode](/embedding/iframe/creator-mode) — use [Signed embedding](/embedding/iframe/auth/signed) instead.
+</Note>
 
-### Dashboards
-
-To embed a dashboard:
-
-1. Open your dashboard in Cube
-2. Click **Share** → **Embed**
-3. Copy the generated iframe code
-
-<img src="https://lgo0ecceic.ucarecd.net/24999bd4-1a7a-4c15-999a-848e6ec3fbe4/" alt="Share embed dialog" />
+## How it works
 
-Then paste the iframe code into your application.
+To embed Cube content with private embedding, paste an `<iframe>` tag into your application or tool. Get the embed code from Cube and paste it wherever you want the content to appear.
 
+When users open the page containing the iframe, they'll be prompted to sign in with their Cube credentials if they're not already authenticated. Access is then governed by their normal Cube [roles and permissions](/admin/users-and-permissions/roles-and-permissions).
 
-## Common Applications
+## Common applications
 
 ### Embedding in Notion
 

docs-mintlify/embedding/signed-embedding.mdx → docs-mintlify/embedding/iframe/auth/signed.mdx

@@ -1,6 +1,6 @@
 ---
 title: Signed embedding
-description: Signed embedding is available on Premium and Enterprise plans.
+description: Authenticate iframe-embedded Cube content with secure, server-generated sessions.
 ---
 
 <Info>
@@ -16,7 +16,13 @@ Signed embedding is designed for **external, customer-facing analytics**. It use
 
 Users authenticate through your application without needing Cube accounts, providing a seamless experience. The session tokens are cryptographically signed to ensure secure access with user-specific permissions.
 
-## Getting started
+Use signed embedding to embed:
+
+- [Dashboards](/embedding/iframe/dashboards)
+- [Analytics Chat](/embedding/iframe/analytics-chat)
+- [Creator Mode](/embedding/iframe/creator-mode) (signed embedding is required)
+
+## How it works
 
 Signed embedding works through a two-step authentication flow:
 
@@ -30,13 +36,15 @@ Signed embedding works through a two-step authentication flow:
 
 This ensures secure authentication while maintaining a smooth user experience.
 
+## Getting started
+
 ### Get your API key
 
-To use the embedded chat or dashboard, you need an [API key][ref-api-keys]:
+To use signed embedding, you need an [API key][ref-api-keys]:
 
 - Go to **Access → API Keys** in your Cube admin panel
-- Generate or copy your existing API key.
-- You'll use this key to authenticate API calls for generating embed sessions.
+- Generate or copy your existing API key
+- You'll use this key to authenticate API calls for generating embed sessions
 
 ### Generate an embed session
 
@@ -83,24 +91,9 @@ const data = await session.json();
 const sessionId = data.sessionId;
 ```
 
-### Embedding via iframe
+### Embed via iframe
 
-Use the session ID to embed the chat UI or the dashboard UI in your application:
-
-```html
-<iframe
-  title="Analytics Chat"
-  src="https://your-tenant.cubecloud.dev/embed/chat?sessionId=YOUR_SESSION_ID"
-></iframe>
-```
-
-```html
-<iframe
-  title="Dashboard"
-  src="https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID"
-  width="100%"
-></iframe>
-```
+Use the session ID to embed the dashboard or chat UI in your application. See [Dashboards](/embedding/iframe/dashboards) and [Analytics Chat](/embedding/iframe/analytics-chat) for the full iframe snippets.
 
 #### Complete example
 
@@ -155,31 +148,6 @@ Here's a complete HTML example that demonstrates the full flow for embedding a d
 </html>
 ```
 
-## Pre-setting dashboard filters via URL
-
-You can pre-set dashboard filter values by adding URL parameters in the format
-`?f_<semantic_view>.<dimension>=<JSON>`. The `<semantic_view>` and `<dimension>`
-must match the internal names (not display titles) of the semantic view and
-dimension configured on the filter widget. If the filter type is omitted, it
-defaults to `equals`.
-
-Example:
-
-```text
-https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&f_orders_transactions.users_country={"value":"USA"}
-```
-
-This works on both regular and published (embedded) dashboards. The filter is
-only applied if a matching filter widget for that dimension already exists on the
-dashboard.
-
-## Customize dashboard style
-
-You can customize the appearance of your dashboard — including background, widget
-styling, borders, titles, and fonts — using the **Styling** pane in the
-Dashboard Builder. Open your dashboard, click **Dashboard Builder** in the
-top bar, then click the gear icon to open the **Styling** panel.
-
 ## User attributes
 
 User attributes enable row-level security and personalized chat responses by filtering data based on user permissions. The attributes you pass during session generation automatically filter data queries and responses.
@@ -215,4 +183,4 @@ For a complete working example of signed embedding, check out the [cube-embeddin
 You can clone the repository, configure it with your Cube credentials, and run it locally to test embedding functionality or use it as a reference implementation for your own application.
 
 [ref-api-keys]: /admin/account-billing/api-keys
-[ref-generate-session]: /reference/embed-apis/generate-session
+[ref-generate-session]: /reference/embed-apis/generate-session