# Cube Documentation (Mintlify)

This is the **active** Cube documentation site, built with [Mintlify](https://mintlify.com).
All documentation work should happen here.

> The `/docs` directory at the repo root is the **legacy** Nextra docs site and is
> **deprecated** — do not add or edit content there.

## Local development

```bash
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 `<Note>` (gray) component — **not** `<Info>` (blue) — for
plan-availability messages. `<Info>` 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
<Note>

Available on the [Enterprise plan](https://cube.dev/pricing).

</Note>
```

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
    - **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
  ---
  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: `<Note>`, `<Warning>`, `<Info>`, `<Tip>`, `<Check>`
- `<Steps>` with nested `<Step title="...">` for sequential instructions
- `<CardGroup cols={2}>` with nested `<Card title="..." icon="..." href="...">`
- `<Tabs>` / `<Tab>`, `<Accordion>` / `<AccordionGroup>`, `<Frame>` 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 `<Warning>`
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
<Warning>

<Feature name> 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.

</Warning>
```

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/<key>`. Reference that URL from the `.mdx`.

Wrap screenshots in `<Frame>`. 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
./scripts/upload-asset.sh <local-file> <dest-key>
```

It prints the `https://static.cube.dev/<key>` 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/<section>/<slug>/<file>` | Screenshots for a specific docs page |
| `icons/<slug>.svg` | Provider / integration logos for `<Card>` |
| `diagrams/<slug>.svg` | Architecture / flow diagrams |
| `recipes/<slug>/<file>` | Recipe-specific screenshots |

**Verify every upload before editing any `.mdx`:**

```bash
curl -sI https://static.cube.dev/<key>
```

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.
