> ## Documentation Index > Fetch the complete documentation index at: https://cubed3-remove-legacy-docs-folder.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # CLAUDE # Cube Documentation (Mintlify) The Cube documentation site, built with [Mintlify](https://mintlify.com). All documentation work should happen here. ## Local development ```bash theme={null} cd docs-mintlify yarn dev # Start the Mintlify dev server ``` ## Naming conventions Product naming conventions (product names, taxonomy, deployment types, plan tiers, API names) are defined below — follow them in all docs content. ### 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 theme={null} 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 * Time granularity * Field switcher * Parent * AI summary * Layout * Spacer * Divider * Stack * Grid * **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 * **Tone**: professional, direct, instructive. Address the reader as "you" (second person). * **Headings**: one H1 is provided by the frontmatter `title` — start body sections at H2 (`##`). * **Code**: always specify a language fence (` ```yaml`, ` ```markdown`, ` ```text`). Use inline backticks for identifiers (`accessible_views`, `agents/rules/`). * **Paragraphs**: keep them short; use `-` bullet lists for multiple items. ### Be concise; prefer surgical edits over new content **Be explicit with yourself about length: most doc changes are small.** Do not produce walls of text. Be less verbose. Write the shortest version that fully answers "how do I use this?" and stop. * **Default to editing existing pages, not creating new ones.** A new feature usually extends a page that already exists — add a row to a table, a config option to a reference page, a sentence to the relevant section. Search the docs first and integrate there. Only create a new page when the topic genuinely has no home. * **Do not pad.** No "Overview" / "Use cases" / "Best practices" scaffolding for a small feature. A single config option is usually a paragraph plus a code block — not a multi-section page. * **Say it once.** Don't restate the same point in prose and again in a callout, and don't explain what the code sample already shows. * **One good example beats three near-identical ones.** ## File and frontmatter conventions * Content is `.mdx`, organized by topic directory (e.g. `admin/ai/`, `docs/explore-analyze/`). * The file path maps to the URL: `admin/ai/rules.mdx` → `/admin/ai/rules`. * Every page starts with YAML frontmatter using `title` and `description`: ```mdx theme={null} --- title: Rules description: One-sentence summary used for SEO and navigation previews. --- ``` * **Do not** add an H1 in the body — the `title` is the page heading. ## Navigation Navigation is defined in `docs-mintlify/docs.json`. A new page only appears in the sidebar once its path (without the `.mdx` extension) is added to the appropriate `group` in `docs.json`. After adding a page, update `docs.json` and verify it is still valid JSON. ## Components Mintlify provides these components (used throughout the docs): * Callouts: ``, ``, ``, ``, `` * `` with nested `` for sequential instructions * `` with nested `` * `` / ``, `` / ``, `` for images Content inside callouts and steps is plain MDX. Internal links are root-relative (`/admin/ai/skills`), not file paths. ## Preview features Every page documenting a feature that is in **preview** must open with a `` callout — placed right after the frontmatter, before the body — saying the feature is in preview and that the user should reach out to the Cube support team to activate it for their account: ```mdx theme={null} is currently in preview, and the user experience and file format may still change. Reach out to the [Cube support team](/admin/account-billing/support) to activate this feature for your account. ``` Adapt the "may still change" sentence per feature; the "in preview" + "reach out to the Cube support team to activate it for your account" parts are required. Do not expose internal feature-flag names in public docs. ## Images and screenshots **Do not commit images or other binaries to the repo.** Editorial media — screenshots, diagrams, logos, video — is uploaded to the `cube-dev-websites-shared` S3 bucket and served from `https://static.cube.dev/`. Reference that URL from the `.mdx`. Wrap screenshots in ``. When a screenshot is needed but not yet available, leave an MDX comment placeholder: `{/* TODO: screenshot — ... */}`. > The `images/` directory holds a handful of older assets that predate this rule. Don't > add to it — and don't take it as precedent. ### Uploading Run from `docs-mintlify/` (**not** `pnpm upload-asset` — that's the landing repo's wrapper; this repo uses the script directly): ```bash theme={null} ./scripts/upload-asset.sh ``` It prints the `https://static.cube.dev/` URL and copies it to the clipboard on macOS. Full setup and the complete path table are in `scripts/README.md`. Key prefixes — use kebab-case filenames: | Prefix | Purpose | | ------------------------------ | ----------------------------------------- | | `docs/
//` | Screenshots for a specific docs page | | `icons/.svg` | Provider / integration logos for `` | | `diagrams/.svg` | Architecture / flow diagrams | | `recipes//` | Recipe-specific screenshots | **Verify every upload before editing any `.mdx`:** ```bash theme={null} curl -sI https://static.cube.dev/ ``` Expect `200`, the right `content-type`, and a `content-length` matching the local file. Cheaper than finding a bad upload after rewriting ten pages. **Compress before uploading.** Nothing resizes these — the blog's image optimizer only rewrites Uploadcare (`ucarecdn.com`) URLs, and `static.cube.dev` passes through untouched. Retina screenshots straight from CleanShot are often 3000px+ and multiple megabytes; scale them down first. Prefer PNG for UI screenshots, WebP for large ones, SVG for logos. **Paths are immutable.** The script refuses to overwrite an existing key; upload a new one with a version suffix (`foo-v2.png`) and update the reference in the same PR. `--force` exists but objects carry `Cache-Control: max-age=31536000, immutable`, so an overwrite can sit stale in caches for a year — avoid it for anything already live. Credentials: AWS CLI plus a `cube-static` profile (region `us-west-2`) with `s3:PutObject` and `s3:HeadObject`. Check with `aws sts get-caller-identity --profile cube-static`. If it isn't configured, ask — don't guess credentials. ## AI / agent docs structure The agent configuration (code-first, developer-facing) lives under `admin/ai/`: `rules.mdx`, `certified-queries.mdx`, `skills.mdx`, `memory-isolation.mdx`, `multi-agent.mdx`, `bring-your-own-model.mdx`. The end-user chat experience (explorer/viewer-facing) lives under `docs/explore-analyze/` (e.g. `analytics-chat.mdx`, `skills.mdx`). Keep authoring docs in `admin/ai/` and usage docs in `docs/explore-analyze/`, and cross-link the two.