diff --git a/docs-mintlify/docs/explore-analyze/charts/chart-types/index.mdx b/docs-mintlify/docs/explore-analyze/charts/chart-types/index.mdx
index a29a4ce8b1866..f28de9d5a8024 100644
--- a/docs-mintlify/docs/explore-analyze/charts/chart-types/index.mdx
+++ b/docs-mintlify/docs/explore-analyze/charts/chart-types/index.mdx
@@ -18,3 +18,71 @@ Cube includes a library of built-in chart types covering the most common visuali
 - [HTML](/docs/explore-analyze/charts/chart-types/html)
 
 For configuration options that apply across chart types — axes, color, series settings, tooltips — see [Configure charts](/docs/explore-analyze/charts/configuration).
+
+## Recommended chart type
+
+When your query returns a result, Cube outlines the one chart type that best fits it and labels it
+**Recommended**. It is a suggestion: every other available type stays selectable, and the outline
+disappears once you pick a type yourself.
+
+On a report that has no chart yet, a recommendation Cube is confident about is applied for you, and
+the report names the rule it followed — for example, *Applied Line — a measure over time*. Anywhere
+else the recommendation is only outlined, never applied.
+
+### What Cube looks at
+
+The recommendation reads the shape of your query and its result: how many measures, dimensions and
+time dimensions you selected, how many distinct values each dimension has, how long the category
+labels are, and how many rows came back. Nothing is sent anywhere and nothing is saved — the
+suggestion lasts for the current session only.
+
+Where a threshold is involved, it comes from
+[Draco](https://ieeexplore.ieee.org/document/8440847) (Moritz et al., *Formalizing Visualization
+Design Knowledge as Constraints*, IEEE VIS 2018), which encodes established visualization research
+as rules: a category axis becomes crowded past 12 values, a color or stacking channel saturates
+past 10 series, and no axis reads past 30 values.
+
+Two numbers are Cube's own rather than Draco's, and are tuned by us: a mean label length of **16
+characters** counts as long, and a result over **5,000 rows** counts as large.
+
+### The conditions
+
+Cube checks these in order and takes the first that matches.
+
+| Recommendation | When |
+| -- | -- |
+| **Map** | The query contains latitude and longitude |
+| **KPI** | One measure, no dimensions, and a single row |
+| **Line** | A measure over a time dimension, optionally split by one category of up to 10 values |
+| **Scatter** | Two or more measures with no time dimension — the shape for correlating them |
+| **Stacked bar** | One measure split by two categories, the first up to 12 values and the second up to 10 |
+| **Heatmap** | One measure split by two larger categories that fill enough of the grid to be worth drawing |
+| **Bar** | One measure across a few categories with short labels |
+| **Horizontal bar** | The same, where the labels are long or the categories too many for a vertical axis |
+| **Table** | The query has no measure, two time dimensions, three or more dimensions, a category past 30 values, or a result over 5,000 rows |
+
+Pie is not recommended. Its shape — one measure across a few categories — is the same one Bar
+answers, and a bar chart compares those values more accurately, so Cube recommends Bar and leaves
+Pie to you. It remains available in the picker like any other chart type.
+
+Table's conditions are disqualifiers rather than a last preference: a query that meets any of them
+has no chart encoding that reads well, so the table is the honest answer. Maps are the exception —
+a map has no category axis to crowd, so a large number of plotted places is normal rather than
+unreadable.
+
+### When nothing is recommended
+
+Cube suppresses the recommendation rather than guessing. You will see no outline when:
+
+- no rule matches the query cleanly;
+- a value it needs is still unknown, such as the number of distinct values in a dimension;
+- the result was truncated by a row limit, so the counts it would read are incomplete;
+- the best fit is the chart type you already applied;
+- you have already picked a type by hand in the picker you are looking at.
+
+Automatic application on an empty report clears a higher bar than the outline does. It happens only
+for Map, KPI, Line, Scatter and vertical Bar, only when no threshold sits within 20% of the observed
+value — so a row either way would not change the answer — and never on a truncated result. Stacked
+bar, heatmap and horizontal bar are offered but never applied for you: stacking asserts that the
+parts compose the whole, which Cube cannot verify from a filtered result, and the others turn on a
+judgment of Cube's own.