diff --git a/.cursor/rules/namings-rule.mdc b/.cursor/rules/namings-rule.mdc deleted file mode 100644 index a62a1dde76e1a..0000000000000 --- a/.cursor/rules/namings-rule.mdc +++ /dev/null @@ -1,205 +0,0 @@ ---- -globs: docs-mintlify/** -alwaysApply: true ---- - -# Product Naming Conventions - -- **Cube Core** — our open-source product -- **Cube** — our commercial product (default name in most contexts) -- **Cube cloud platform** — use only when you need to explicitly differentiate the commercial product from Cube Core -- **Cube Cloud** — legacy naming, do not use in new content - -# Deployment Type Naming - -- **Development** — development deployment type (legacy: "Development instance") -- **Production** — production deployment type (legacy: "Production cluster") -- **Multi-cluster** — multi-cluster production deployment type (legacy: "Production multi-cluster") - -# Plan Tier Naming - -Cube's commercial plan tiers, in order: **Free**, **Starter**, **Premium**, -**Enterprise**. **Enterprise is the top tier — nothing is above it.** - -When describing plan availability: - -- ✅ "Available on the [Enterprise plan]" (single tier, top of stack) -- ✅ "Available on [Premium and above plans]" (Premium + Enterprise) -- ✅ "Available on [Starter and above plans]" (Starter + Premium + Enterprise) -- ❌ Do **not** write "Enterprise and above plans" — there is nothing above - Enterprise. Use "Enterprise plan" (singular) instead. -- For Enterprise-only features that require an additional purchase, use - "Available as an add-on on the [Enterprise plan]". -- For features that depend on another add-on, name the dependency: - "Available on the [Enterprise plan] with the [Single-tenant infrastructure] - add-on." - -## Plan availability callouts - -Use Mintlify's `` (gray) component — **not** `` (blue) — for -plan-availability messages. `` is the catch-all blue callout used -heavily throughout the docs for general "by the way" notes; using a different -color for plan gating makes it visually distinct and scannable. - -```mdx - - -Available on the [Enterprise plan](https://cube.dev/pricing). - - -``` - -Place the callout immediately after the section heading it applies to. - -# Infrastructure Naming - -Infrastructure options are a separate, orthogonal concept from deployment types. -A deployment of any type runs on top of one of these infrastructure options: - -- **Multi-tenant infrastructure** — deployments share compute and network with - other customers. Legacy: "Shared infrastructure". -- **Single-tenant infrastructure** — deployments run in a dedicated VPC inside - a Cube Cloud account; not shared with any other customer. Legacy: "Dedicated - infrastructure". -- **Single-tenant infrastructure with CSPS** — same as single-tenant, but - data at-rest is stored in a customer-supplied object store. Legacy: - "Dedicated infrastructure with CSPS". -- **BYOC (Bring Your Own Cloud)** — Cube Cloud data plane is fully hosted in - the customer's cloud account. - -Guidance: - -- Always use **single-tenant** / **multi-tenant** in customer-facing prose, - headings, navigation labels, and card titles. These terms are an industry - standard and remove the naming collision with the **Shared** and **Dedicated** - deployment types. -- Do **not** rename URL anchors (`#shared-infrastructure`, - `#dedicated-infrastructure`, `#dedicated-infrastructure-with-csps`) or - internal link reference IDs (e.g., `[ref-dedicated-infra]`); keep these - stable so external inbound links keep working. Use Mintlify's explicit - anchor syntax (`## Single-tenant infrastructure {#dedicated-infrastructure}`) - to preserve them. -- Do **not** rename product/region identifier slugs that contain `shared`, - `dedicated`, or `byoc` (e.g., `aws-us-east-1-shared`, `aws-us-east-1-t-12345-prod`). - These are literal strings used by the product. -- Avoid bare adjectives like "dedicated infrastructure" when you mean a - Dedicated **deployment type** running on its own compute. Prefer phrases - like "compute dedicated to your deployment" to avoid implying single-tenant - infrastructure. - -# Product Taxonomy -Make sure to use correct terms. On billing, pricing, and support pages, use **on-demand customers** for the on-demand payment plan (legacy billing copy: "self-serve customers") and **contract customers** for the commit payment plan (legacy: "order form customers"). Elsewhere, **self-serve** (e.g. self-serve analytics) describes end-user exploration, not the billing segment. - -- **Account** - - **Deployment** - - **Agent** (one per deployment by default; multi-agent is also supported) - - Rules - - Certified queries - - **Analytics Chat** - - **Workbook** - - Tab - - Dashboard builder - - **Widget** - - Charts - - Text - - Controls - - Filter widget - - Time grain switcher - - AI summary - - **Dashboard** - - Scheduled refresh - - **Semantic Model** - - Semantic Model IDE (short: "IDE") - - Semantic Model Agent - - **Explore** - - Explorations - - **API** - - Embed APIs - - Core Data APIs - - SQL API - - DAX API - - REST (JSON) API (transitional name; previously "REST API", will eventually become "JSON API") - - GraphQL API - - Management APIs - - Orchestration API - - **Embedding** - - 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). - -# Core Data API Naming - -The Core Data APIs are: **SQL API**, **DAX API**, **REST (JSON) API**, and **GraphQL API**. - -## REST (JSON) API - -We are transitioning the name of our HTTP/JSON-based Core Data API: - -- Previous name: **REST API** -- Current (transitional) name: **REST (JSON) API** — use this in all new and updated content -- Future name: **JSON API** - -Guidance for the transitional period: - -- In prose, link references, headings, navigation labels, and card titles, use **REST (JSON) API** in place of **REST API**. -- Do not change URL paths, route segments, file/directory names, code identifiers, env vars, or config option names (e.g., `/reference/core-data-apis/rest-api`, `rest-api/index.mdx`, the `rest` query format value, internal link slugs like `[ref-rest-api]`). -- Do not rewrite third-party UI literals where "REST API" is a verbatim label in another product (e.g., Retool's `"REST API"` resource type, Budibase's `"REST API"` data source). Quote them as the third-party tool spells them. -- Plural form ("REST APIs") is not currently used and should be avoided; refer to the API in the singular. - -# Agent Terminology - -Every [Deployment](#product-taxonomy) ships with **one agent** by default. The agent powers AI features (Analytics Chat, ad-hoc queries, etc.) and is configured per-deployment with rules, certified queries, and other customizations. Multi-agent (multiple agents per deployment) is also supported, but the documentation primarily covers the default single-agent setup; multi-agent docs will follow. - -## Naming - -- **the agent** — default term in single-agent contexts. No qualifier needed because every deployment has exactly one by default. Example: "configure rules for the agent", "add a certified query to the agent". -- **Cube agent** — use only when referring to the agent feature in the abstract (product-level), not a specific instance. Example: "Cube agent supports certified queries." -- **Avoid "default agent"** — it implies non-default agents exist. Reserve this term for multi-agent docs where it contrasts with custom-created agents. -- **Avoid "deployment agent"** — wordy and doesn't add useful contrast in multi-agent contexts. - -## In multi-agent contexts - -- Refer to specific agents by their user-given names. -- Use **default agent** to contrast against user-created agents within a deployment. -- Continue to use **Cube agent** for product-level / abstract references. diff --git a/docs-mintlify/CLAUDE.md b/docs-mintlify/CLAUDE.md index 0bf4c484c5310..f32dade7c0fce 100644 --- a/docs-mintlify/CLAUDE.md +++ b/docs-mintlify/CLAUDE.md @@ -16,10 +16,226 @@ yarn dev # Start the Mintlify dev server ## Naming conventions Product naming conventions (product names, taxonomy, deployment types, plan -tiers, API names) are maintained in a shared rules file — follow it in all -docs content: +tiers, API names) are defined below — follow them in all docs content. -@../.cursor/rules/namings-rule.mdc +### Product Naming Conventions + +- **Cube Core** — our open-source product +- **Cube** — our commercial product (default name in most contexts) +- **Cube cloud platform** — use only when you need to explicitly differentiate the commercial product from Cube Core +- **Cube Cloud** — legacy naming, do not use in new content + +### Deployment Type Naming + +- **Development** — development deployment type (legacy: "Development instance") +- **Production** — production deployment type (legacy: "Production cluster") +- **Multi-cluster** — multi-cluster production deployment type (legacy: "Production multi-cluster") + +### Plan Tier Naming + +Cube's commercial plan tiers, in order: **Free**, **Starter**, **Premium**, +**Enterprise**. **Enterprise is the top tier — nothing is above it.** + +When describing plan availability: + +- ✅ "Available on the [Enterprise plan]" (single tier, top of stack) +- ✅ "Available on [Premium and above plans]" (Premium + Enterprise) +- ✅ "Available on [Starter and above plans]" (Starter + Premium + Enterprise) +- ❌ Do **not** write "Enterprise and above plans" — there is nothing above + Enterprise. Use "Enterprise plan" (singular) instead. +- For Enterprise-only features that require an additional purchase, use + "Available as an add-on on the [Enterprise plan]". +- For features that depend on another add-on, name the dependency: + "Available on the [Enterprise plan] with the [Single-tenant infrastructure] + add-on." + +#### Plan availability callouts + +Use Mintlify's `` (gray) component — **not** `` (blue) — for +plan-availability messages. `` is the catch-all blue callout used +heavily throughout the docs for general "by the way" notes; using a different +color for plan gating makes it visually distinct and scannable. + +```mdx + + +Available on the [Enterprise plan](https://cube.dev/pricing). + + +``` + +Place the callout immediately after the section heading it applies to. + +### Infrastructure Naming + +Infrastructure options are a separate, orthogonal concept from deployment types. +A deployment of any type runs on top of one of these infrastructure options: + +- **Multi-tenant infrastructure** — deployments share compute and network with + other customers. Legacy: "Shared infrastructure". +- **Single-tenant infrastructure** — deployments run in a dedicated VPC inside + a Cube Cloud account; not shared with any other customer. Legacy: "Dedicated + infrastructure". +- **Single-tenant infrastructure with CSPS** — same as single-tenant, but + data at-rest is stored in a customer-supplied object store. Legacy: + "Dedicated infrastructure with CSPS". +- **BYOC (Bring Your Own Cloud)** — Cube Cloud data plane is fully hosted in + the customer's cloud account. + +Guidance: + +- Always use **single-tenant** / **multi-tenant** in customer-facing prose, + headings, navigation labels, and card titles. These terms are an industry + standard and remove the naming collision with the **Shared** and **Dedicated** + deployment types. +- Do **not** rename URL anchors (`#shared-infrastructure`, + `#dedicated-infrastructure`, `#dedicated-infrastructure-with-csps`) or + internal link reference IDs (e.g., `[ref-dedicated-infra]`); keep these + stable so external inbound links keep working. Use Mintlify's explicit + anchor syntax (`## Single-tenant infrastructure {#dedicated-infrastructure}`) + to preserve them. +- Do **not** rename product/region identifier slugs that contain `shared`, + `dedicated`, or `byoc` (e.g., `aws-us-east-1-shared`, `aws-us-east-1-t-12345-prod`). + These are literal strings used by the product. +- Avoid bare adjectives like "dedicated infrastructure" when you mean a + Dedicated **deployment type** running on its own compute. Prefer phrases + like "compute dedicated to your deployment" to avoid implying single-tenant + infrastructure. + +### Product Taxonomy + +Make sure to use correct terms. On billing, pricing, and support pages, use **on-demand customers** for the on-demand payment plan (legacy billing copy: "self-serve customers") and **contract customers** for the commit payment plan (legacy: "order form customers"). Elsewhere, **self-serve** (e.g. self-serve analytics) describes end-user exploration, not the billing segment. + +- **Account** + - **Deployment** + - **Agent** (one per deployment by default; multi-agent is also supported) + - Rules + - Certified queries + - **Evals** + - Questions (the benchmark set) + - Eval run (one execution of the agent against the question set) + - **Analytics Chat** + - **Workbook** + - Tab + - Dashboard builder + - **Widget** + - Charts + - Text + - Controls + - Filter widget + - Time grain switcher + - AI summary + - **Dashboard** + - Scheduled refresh + - **Semantic Model** + - Semantic Model IDE (short: "IDE") + - Semantic Model Agent + - **Explore** + - Explorations + - **API** + - Embed APIs + - Core Data APIs + - SQL API + - DAX API + - REST (JSON) API (transitional name; previously "REST API", will eventually become "JSON API") + - GraphQL API + - Management APIs + - Orchestration API + - **Embedding** + - 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). + +### Core Data API Naming + +The Core Data APIs are: **SQL API**, **DAX API**, **REST (JSON) API**, and **GraphQL API**. + +#### REST (JSON) API + +We are transitioning the name of our HTTP/JSON-based Core Data API: + +- Previous name: **REST API** +- Current (transitional) name: **REST (JSON) API** — use this in all new and updated content +- Future name: **JSON API** + +Guidance for the transitional period: + +- In prose, link references, headings, navigation labels, and card titles, use **REST (JSON) API** in place of **REST API**. +- Do not change URL paths, route segments, file/directory names, code identifiers, env vars, or config option names (e.g., `/reference/core-data-apis/rest-api`, `rest-api/index.mdx`, the `rest` query format value, internal link slugs like `[ref-rest-api]`). +- Do not rewrite third-party UI literals where "REST API" is a verbatim label in another product (e.g., Retool's `"REST API"` resource type, Budibase's `"REST API"` data source). Quote them as the third-party tool spells them. +- Plural form ("REST APIs") is not currently used and should be avoided; refer to the API in the singular. + +### Agent Terminology + +Every [Deployment](#product-taxonomy) ships with **one agent** by default. The agent powers AI features (Analytics Chat, ad-hoc queries, etc.) and is configured per-deployment with rules, certified queries, and other customizations. Multi-agent (multiple agents per deployment) is also supported, but the documentation primarily covers the default single-agent setup; multi-agent docs will follow. + +#### Naming + +- **the agent** — default term in single-agent contexts. No qualifier needed because every deployment has exactly one by default. Example: "configure rules for the agent", "add a certified query to the agent". +- **Cube agent** — use only when referring to the agent feature in the abstract (product-level), not a specific instance. Example: "Cube agent supports certified queries." +- **Avoid "default agent"** — it implies non-default agents exist. Reserve this term for multi-agent docs where it contrasts with custom-created agents. +- **Avoid "deployment agent"** — wordy and doesn't add useful contrast in multi-agent contexts. + +#### In multi-agent contexts + +- Refer to specific agents by their user-given names. +- Use **default agent** to contrast against user-created agents within a deployment. +- Continue to use **Cube agent** for product-level / abstract references. + +### Evals Terminology + +Benchmarking the agent's answers against a known-correct ground truth. + +- **Evals** — the feature, the model IDE tab, and the runs sub-tab. Use this + everywhere the feature or its UI is named. +- **eval run** — a single execution of the agent against the question set. + Action label: **Run eval**; column label: **Eval run**. +- **Question** — a natural-language question plus its ground truth; lives under + the **Questions** sub-tab. +- **Avoid "Evaluate" / "Evaluation" / "Evaluations"** — legacy UI labels, + replaced by **Evals**. (Generic verb uses like "evaluate the expression" are + unrelated and fine.) ## Writing style diff --git a/docs-mintlify/admin/ai/evals.mdx b/docs-mintlify/admin/ai/evals.mdx index 9b5f3dccdf9a9..890dc08cecb10 100644 --- a/docs-mintlify/admin/ai/evals.mdx +++ b/docs-mintlify/admin/ai/evals.mdx @@ -18,11 +18,11 @@ answer, run your agent against them, and get a per-question pass/fail plus an accuracy score for the run — so you can see, objectively, whether a data-model or agent change made the agent better or worse. -You'll find evals in the model IDE under the **Evaluate** tab, with two -sub-tabs: **Evaluations** (runs) and **Questions** (the benchmark set). +You'll find evals in the model IDE under the **Evals** tab, with two +sub-tabs: **Evals** (runs) and **Questions** (the benchmark set). - Evaluation run results showing the question list with pass/fail icons and a selected question's detail with the agent's SQL next to the ground truth SQL + Eval run results showing the question list with pass/fail icons and a selected question's detail with the agent's SQL next to the ground truth SQL ## Concepts @@ -30,7 +30,7 @@ sub-tabs: **Evaluations** (runs) and **Questions** (the benchmark set). | Term | What it is | |------|------------| | **Question** | A natural-language question plus its **ground truth** (the correct answer, as SQL or a certified-query reference). Authored as code in your data model. | -| **Evaluation (run)** | One execution of the agent against the whole question set, on a specific branch and agent. | +| **Eval (run)** | One execution of the agent against the whole question set, on a specific branch and agent. | | **Result** | The agent's answer to a single question in a run, graded against that question's ground truth. | | **Accuracy** | `passed / total` for a run, shown as `NN% (passed/total)`. | @@ -80,9 +80,9 @@ question editor yet. -## Running an evaluation +## Running an eval -On the **Evaluations** tab, click **New evaluation** and choose: +On the **Evals** tab, click **Run eval** and choose: - **Branch** — which branch's data model and agent configuration to run against. Defaults to the active branch. @@ -93,7 +93,7 @@ background. The run list shows live progress and then the outcome: | Column | Meaning | |--------|---------| -| **Evaluation name** | When the run was created. | +| **Eval run** | When the run was created. | | **Environment** | Where it ran — **dev** (your personal dev-mode branch, shown as "*Name* Dev Mode"), **staging**, or **prod** (the deploy branch, e.g. `master` or `main`). | | **Agent** | The agent used. | | **Execution status** | Running, Completed, or Failed. |