@amcharts/amcharts5-mcp 1.1.8 → 1.2.0

package/content/SKILL.md

@@ -164,6 +164,34 @@ series.set("tooltip", am5.Tooltip.new(root, {
 
 **Inline formatting:** `"[bold]{name}[/]: [fontSize: 20px]{value}[/]"`
 
+**A tooltip with no text renders as an empty bubble.** Enabling a `am5.Tooltip` without `labelText` (or `series.tooltipText`) shows a blank tooltip. Series text lives on `tooltip.labelText` or `series.set("tooltipText", ...)`; for column/bar charts the text usually goes on `series.columns.template.set("tooltipText", "{categoryX}: {valueY}")`.
+
+### Styling a tooltip
+
+The tooltip background is a **`PointedRectangle`** (NOT a `RoundedRectangle`), so it has a single `cornerRadius` — there are no `cornerRadiusTL/TR/BL/BR`:
+
+```js
+const tooltip = am5.Tooltip.new(root, { labelText: "{valueY}" });
+
+// Background color + shape — must turn OFF getFillFromSprite, else bg copies the series color
+tooltip.set("getFillFromSprite", false);
+tooltip.get("background").setAll({
+  fill: am5.color(0x000000),
+  fillOpacity: 0.8,
+  stroke: am5.color(0xffffff),
+  strokeOpacity: 0.3,
+  cornerRadius: 6        // single radius — PointedRectangle, not four corners
+});
+
+// Text color — must turn OFF autoTextColor (it auto-picks for contrast), then set on the label
+tooltip.set("autoTextColor", false);
+tooltip.label.setAll({ fill: am5.color(0xffffff) });   // tooltip.label is read-only accessor
+
+series.set("tooltip", tooltip);
+```
+
+`getStrokeFromSprite` (default `false`) copies the sprite's stroke color when `true`.
+
 ## Chart title
 
 Do NOT add titles as HTML elements — they are outside the canvas and won't appear in exports. Add an `am5.Label` to the container BEFORE the chart, and set `verticalLayout`:
@@ -358,8 +386,15 @@ sprite.setAll({ fill: am5.color(0xff0000), strokeWidth: 2 });
 // Read current value
 const fill = sprite.get("fill");
 const width = sprite.getPrivate("width"); // read-only internal values
+
+// set() RETURNS the value — handy for capturing the created object inline:
+const cursor = chart.set("cursor", am5xy.XYCursor.new(root, {}));
 ```
 
+**Reading back a `Percent`:** a `Percent` exposes two numbers — `.percent` is the 0–100 value, `.value` is the normalized 0–1 fraction. `am5.percent(50).percent === 50` but `am5.percent(50).value === 0.5`. When you read a percent setting back (e.g. `sprite.get("x")` after setting `am5.percent(50)`), use `.percent` for a 0–100 number; `.value` gives `0.5`.
+
+**Reading animated settings is unreliable mid-animation.** Right after `series.appear()` / `chart.appear()`, animated settings like `opacity` are still transitioning — `get("opacity")` can return `0` (the start value). Read such settings after the animation completes, or don't persist values read during appear (a common way to accidentally bake `opacity:0` into generated code).
+
 ## Dynamic data
 
 ```js
@@ -639,7 +674,7 @@ onUnmounted(() => { root.dispose(); });
 26. **`VoronoiTreemap` has NO `.rectangles` property** — Unlike `Treemap` (which has `series.rectangles.template`), `VoronoiTreemap` renders organic polygon cells. Style via `series.nodes.template` and its children, not `.rectangles`.
 27. **Labels with data placeholders need `populateText: true`** — When a Label uses data field placeholders like `text: "{name}"`, you MUST also set `populateText: true`. Without it, the placeholder is not resolved and the label appears blank. This applies everywhere Labels display dynamic data — bullet labels, map point labels, etc. Example: `am5.Label.new(root, { text: "{name}", populateText: true, ... })`.
 28. **Easing: `am5.ease.in()` does NOT exist** — amCharts 5 provides base easing functions (`am5.ease.cubic`, `am5.ease.bounce`, `am5.ease.elastic`, `am5.ease.linear`, `am5.ease.quad`, `am5.ease.sine`, `am5.ease.circle`, `am5.ease.exp`, `am5.ease.pow`) and three modifiers: `am5.ease.out()`, `am5.ease.inOut()`, `am5.ease.yoyo()`. Usage: `am5.ease.cubic` (ease-in by default), `am5.ease.out(am5.ease.cubic)` (ease-out), `am5.ease.inOut(am5.ease.cubic)` (ease in+out). There is NO `am5.ease.in()` — using it throws a runtime error. The base functions already ease-in by default.
-29. **Use `forceHidden` instead of `visible: false` when you need to guarantee something stays hidden** — amCharts internally manages `visible` on many elements (cursor lines, labels, ticks, tooltips, grid, etc.), toggling them on/off in response to user interaction or data changes. If you set `visible: false`, the library may set it back to `true`. `forceHidden: true` overrides all system visibility changes and keeps the element hidden regardless. Examples: `cursor.lineX.set("forceHidden", true)`, `yRenderer.labels.template.set("forceHidden", true)`, `xRenderer.grid.template.set("forceHidden", true)`. For cursor lines specifically, always access `cursor.lineX`/`cursor.lineY` after creation — do NOT pass them as constructor options.
+29. **`forceHidden` vs `visible`** — `forceHidden: true` ALWAYS hides an element, immune to states, themes/library and even `show()`. `visible` is weaker: amCharts re-manages it on many elements (notably cursor lines, but also labels, ticks, tooltips, grid) in response to interaction or data changes, so a `visible: false` you set may be flipped back to `true`. Rules of thumb: for a **persistent hide**, use `forceHidden: true` (`cursor.lineX.set("forceHidden", true)`, `yRenderer.labels.template.set("forceHidden", true)`, `xRenderer.grid.template.set("forceHidden", true)`). To **reveal** an element that defaults hidden — notably **axis ticks** (`ticks.template` defaults to `visible:false`) — you must raise `visible: true`; flipping `forceHidden` alone won't show it. For cursor lines specifically, always access `cursor.lineX`/`cursor.lineY` after creation — do NOT pass them as constructor options.
 30. **`snapTooltip: true` on series for cursor tooltip snapping** — When using a cursor and you want tooltips to snap to data points, set `snapTooltip: true` on the series in addition to (or instead of) `snapToSeries` on the cursor. This is especially useful for timeline/curve charts.
 31. **Globe rotation uses negative coordinates** — To center the globe (`geoOrthographic`) on a geographic point, set `rotationX` to **-longitude** and `rotationY` to **-latitude**. E.g., to center on Paris (48.86°N, 2.35°E): `chart.animate({ key: "rotationX", to: -2.35 }); chart.animate({ key: "rotationY", to: -48.86 });`. Using positive values rotates the globe the wrong way.
 32. **`positionOnLine` with multi-segment lines limits per-segment control** — `MapPointSeries` data items can animate along a line via `positionOnLine` (0→1). If the line has 3+ points (multi-segment), position 0.5 is the midpoint of the *entire* path, making per-segment effects (scaling at each segment midpoint, pausing between segments, etc.) difficult. For advanced per-segment animations, use **single-segment lines** (2 points each) and animate the bullet across them sequentially. E.g., instead of one line [A,B,C,D], create [A,B], [B,C], [C,D].
@@ -679,6 +714,32 @@ If you have the ability to run shell commands, validate your generated chart cod
 
 Skip this step entirely if you cannot execute code (e.g., chat-only context with no tool access).
 
+## Recent API changes (newer than the bundled class reference)
+
+The bundled per-class API reference was snapshotted on **2026-03-15**, so it predates the changes below. Prefer these names/settings; for anything newer, verify against the live docs (see next section).
+
+**Renamed settings (old name still works but is deprecated — use the new one):**
+
+| Class(es) | Old | New | Since |
+|-----------|-----|-----|-------|
+| `MovingAverage`, `MovingAverageDeviation`, `MovingAverageEnvelope`, `BollingerBands` | `type` | `maType` | 5.18.0 |
+| `VoronoiTreemap` | `type` | `shapeType` | 5.18.0 |
+
+```js
+// Moving-average indicators: use maType, not type
+am5stock.MovingAverage.new(root, { maType: "exponential", period: 20 });
+am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
+```
+
+**New settings / methods worth knowing:**
+- `Tree`: `fitNodes` (5.18.0, exclude hidden nodes from layout), `nodeSeparation` (5.16.2, custom node-spacing fn), `clustered` (5.16.2, dendrogram layout — leaves at same depth).
+- `ValueAxis`: `syncZeros` (5.16.2, align zero across synced axes — needs `syncWithAxis`).
+- `Hierarchy`: `parentIdField` setting + `setFlatData(data)` method (5.16.2) — feed flat `{id, parentId}` data instead of nested `children`.
+- All entities: `onDebounced(key, cb, delay)` / `offDebounced(key, cb?)` and `onPrivateDebounced` / `offDebouncedPrivate` (5.17.3) — fire once after rapid changes settle.
+- `Label`: `fontFamily: "inherit"` (5.17.3) uses the chart container's computed font.
+- `MapSankeySeries` (5.17.0) — Sankey overlaid on a map; auto-resolves `sourceId`/`targetId` once `polygonSeries` geoJSON loads (5.17.1), so no `datavalidated` wrapper needed. See `references/map.md`.
+- `MapPointSeries` defaults changed to `longitudeField: "longitude"`, `latitudeField: "latitude"` (5.16.1).
+
 ## Verify unfamiliar API before using it
 
 If you are unsure whether a method, property, or setting exists on an amCharts 5 class, **verify it before using it**. Check the class reference (class name in lowercase, e.g. `LineSeries` → `lineseries`):

package/content/map.md

@@ -243,22 +243,20 @@ Two data patterns — polygon IDs or explicit coordinates.
 
 **Pattern 1: `sourceId` / `targetId` (country codes)**
 
-IDs use ISO 3166-1 alpha-2 codes matching the geodata. **CRITICAL:** Data MUST be set inside `polygonSeries.events.once("datavalidated", ...)` — the polygon series needs to finish parsing geoJSON before MapSankeySeries can resolve country IDs to centroids. Without this wrapper, `getDataItemById()` returns null and flows silently don't appear (no errors, no bands).
+IDs use ISO 3166-1 alpha-2 codes matching the geodata. Set data directly — `MapSankeySeries` auto-resolves `sourceId`/`targetId` once the referenced `polygonSeries` finishes loading, so data can be set at any time:
 
 ```js
-polygonSeries.events.once("datavalidated", function() {
-  sankeySeries.data.setAll([
-    { sourceId: "BR", targetId: "DE", value: 350 },
-    { sourceId: "BR", targetId: "US", value: 450 },
-    { sourceId: "DE", targetId: "FR", value: 150 },
-    { sourceId: "DE", targetId: "PL", value: 100 }
-  ]);
-});
+sankeySeries.data.setAll([
+  { sourceId: "BR", targetId: "DE", value: 350 },
+  { sourceId: "BR", targetId: "US", value: 450 },
+  { sourceId: "DE", targetId: "FR", value: 150 },
+  { sourceId: "DE", targetId: "PL", value: 100 }
+]);
 ```
 
-**Pattern 2: Explicit coordinates (no timing needed)**
+**Pattern 2: Explicit coordinates**
 
-When using `sourceLongitude`/`sourceLatitude`/`targetLongitude`/`targetLatitude`, data can be set immediately — no `datavalidated` wrapper required:
+When using `sourceLongitude`/`sourceLatitude`/`targetLongitude`/`targetLatitude`, centroid lookup is skipped entirely:
 ```js
 sankeySeries.data.setAll([
   {
@@ -271,17 +269,15 @@ sankeySeries.data.setAll([
 
 **Waypoints** — route flows through intermediate points:
 ```js
-polygonSeries.events.once("datavalidated", function() {
-  sankeySeries.data.setAll([
-    {
-      sourceId: "GB", targetId: "JP", value: 40,
-      waypoints: [
-        { longitude: 30, latitude: 65 },
-        { longitude: 90, latitude: 55 }
-      ]
-    }
-  ]);
-});
+sankeySeries.data.setAll([
+  {
+    sourceId: "GB", targetId: "JP", value: 40,
+    waypoints: [
+      { longitude: 30, latitude: 65 },
+      { longitude: 90, latitude: 55 }
+    ]
+  }
+]);
 ```
 
 **WARNING:** Never call `polygonSeries.data.setAll()` with custom objects — this replaces all geoJSON-derived data items, breaking MapSankeySeries centroid resolution. To set per-country properties (like colors), iterate existing data items after `datavalidated` instead:
@@ -405,16 +401,14 @@ Bullets automatically hide on the back side of the globe (orthographic projectio
 The same country can be both target and source — incoming and outgoing bands share unified stacking at intermediate nodes:
 
 ```js
-polygonSeries.events.once("datavalidated", function() {
-  sankeySeries.data.setAll([
-    // Level 1: Producers > Hubs
-    { sourceId: "BR", targetId: "DE", value: 350 },
-    { sourceId: "VN", targetId: "DE", value: 200 },
-    // Level 2: Hubs > Consumers
-    { sourceId: "DE", targetId: "FR", value: 150 },
-    { sourceId: "DE", targetId: "PL", value: 100 }
-  ]);
-});
+sankeySeries.data.setAll([
+  // Level 1: Producers > Hubs
+  { sourceId: "BR", targetId: "DE", value: 350 },
+  { sourceId: "VN", targetId: "DE", value: 200 },
+  // Level 2: Hubs > Consumers
+  { sourceId: "DE", targetId: "FR", value: 150 },
+  { sourceId: "DE", targetId: "PL", value: 100 }
+]);
 ```
 
 ### Animating bullets along lines (positionOnLine)
@@ -1222,36 +1216,34 @@ Demonstrates: `MapSankeySeries` with `sourceId`/`targetId` data (country codes),
       });
     });
 
-    // Set data after polygonSeries loads (sourceId/targetId need centroid lookup)
-    // CRITICAL: data MUST be set inside datavalidated handler
-    polygonSeries.events.once("datavalidated", function() {
-      sankeySeries.data.setAll([
-        // Producers > Hubs
-        { sourceId: "BR", targetId: "DE", value: 350 },
-        { sourceId: "BR", targetId: "US", value: 450 },
-        { sourceId: "BR", targetId: "IT", value: 200 },
-        { sourceId: "VN", targetId: "DE", value: 200 },
-        { sourceId: "VN", targetId: "BE", value: 150 },
-        { sourceId: "CO", targetId: "US", value: 250 },
-        { sourceId: "CO", targetId: "DE", value: 80 },
-        { sourceId: "ET", targetId: "DE", value: 60 },
-        { sourceId: "ET", targetId: "BE", value: 40 },
-        { sourceId: "ID", targetId: "US", value: 80 },
-        { sourceId: "HN", targetId: "DE", value: 60 },
-        { sourceId: "HN", targetId: "BE", value: 40 },
-        // Hubs > Consumer Markets
-        { sourceId: "DE", targetId: "FR", value: 150 },
-        { sourceId: "DE", targetId: "PL", value: 100 },
-        { sourceId: "DE", targetId: "SE", value: 80 },
-        { sourceId: "DE", targetId: "RU", value: 120 },
-        { sourceId: "BE", targetId: "GB", value: 100 },
-        { sourceId: "BE", targetId: "NL", value: 80 },
-        { sourceId: "IT", targetId: "GR", value: 50 },
-        { sourceId: "IT", targetId: "AT", value: 40 },
-        { sourceId: "US", targetId: "CA", value: 120 },
-        { sourceId: "US", targetId: "JP", value: 80 }
-      ]);
-    });
+    // Set data directly — MapSankeySeries auto-resolves sourceId/targetId
+    // once polygonSeries finishes loading.
+    sankeySeries.data.setAll([
+      // Producers > Hubs
+      { sourceId: "BR", targetId: "DE", value: 350 },
+      { sourceId: "BR", targetId: "US", value: 450 },
+      { sourceId: "BR", targetId: "IT", value: 200 },
+      { sourceId: "VN", targetId: "DE", value: 200 },
+      { sourceId: "VN", targetId: "BE", value: 150 },
+      { sourceId: "CO", targetId: "US", value: 250 },
+      { sourceId: "CO", targetId: "DE", value: 80 },
+      { sourceId: "ET", targetId: "DE", value: 60 },
+      { sourceId: "ET", targetId: "BE", value: 40 },
+      { sourceId: "ID", targetId: "US", value: 80 },
+      { sourceId: "HN", targetId: "DE", value: 60 },
+      { sourceId: "HN", targetId: "BE", value: 40 },
+      // Hubs > Consumer Markets
+      { sourceId: "DE", targetId: "FR", value: 150 },
+      { sourceId: "DE", targetId: "PL", value: 100 },
+      { sourceId: "DE", targetId: "SE", value: 80 },
+      { sourceId: "DE", targetId: "RU", value: 120 },
+      { sourceId: "BE", targetId: "GB", value: 100 },
+      { sourceId: "BE", targetId: "NL", value: 80 },
+      { sourceId: "IT", targetId: "GR", value: 50 },
+      { sourceId: "IT", targetId: "AT", value: 40 },
+      { sourceId: "US", targetId: "CA", value: 120 },
+      { sourceId: "US", targetId: "JP", value: 80 }
+    ]);
 
     // Set country names on auto-created nodes and animate bullets
     var countryNames = {
@@ -1270,31 +1262,27 @@ Demonstrates: `MapSankeySeries` with `sourceId`/`targetId` data (country codes),
         }
       });
 
-      // Defer bullet animation — bullets are not yet instantiated
-      // when datavalidated fires inside polygonSeries handler
-      setTimeout(function() {
-        am5.array.each(sankeySeries.dataItems, function(dataItem) {
-          var bullets = dataItem.bullets;
-          if (bullets) {
-            am5.array.each(bullets, function(bullet) {
-              var randomDur = 3000 + Math.random() * 3000;
-              var delay = Math.random() * randomDur;
-              setTimeout(function() {
-                var sprite = bullet.get("sprite");
-                if (sprite) sprite.set("visible", true);
-                bullet.animate({
-                  key: "locationX",
-                  from: 0,
-                  to: 1,
-                  duration: randomDur,
-                  easing: am5.ease.linear,
-                  loops: Infinity
-                });
-              }, delay);
-            });
-          }
-        });
-      }, 100);
+      am5.array.each(sankeySeries.dataItems, function(dataItem) {
+        var bullets = dataItem.bullets;
+        if (bullets) {
+          am5.array.each(bullets, function(bullet) {
+            var randomDur = 3000 + Math.random() * 3000;
+            var delay = Math.random() * randomDur;
+            setTimeout(function() {
+              var sprite = bullet.get("sprite");
+              if (sprite) sprite.set("visible", true);
+              bullet.animate({
+                key: "locationX",
+                from: 0,
+                to: 1,
+                duration: randomDur,
+                easing: am5.ease.linear,
+                loops: Infinity
+              });
+            }, delay);
+          });
+        }
+      });
     });
 
     // Title
@@ -1606,7 +1594,6 @@ Demonstrates: `MapSankeySeries` with explicit `sourceLongitude`/`sourceLatitude`
     var wpPortugal    = { longitude: -10, latitude: 39 };
     var viaAtlantic   = [wpHormuz, wpAden, wpSuez, wpSicily, wpPortugal];
 
-    // No datavalidated wrapper needed — explicit coordinates resolve immediately
     sankeySeries.data.setAll([
       // Ras Tanura (Saudi Arabia)
       flow(rasTanura, "Ras Tanura", ningbo,    "Ningbo",    1100, viaChina),

package/content/xy.md

@@ -81,6 +81,8 @@ The field name combines the **value type** + **axis direction**:
 - Date axis on X → `valueXField: "date"` (dates are numeric timestamps)
 - Open/high/low/close → `openValueYField`, `highValueYField`, `lowValueYField`, `valueYField`
 
+**There is NO `dateXField` in v5** (a common wrong guess carried over from v4). A `DateAxis` series reads its date from `valueXField`, pointing at a numeric timestamp (`new Date(...).getTime()`).
+
 ## Common additions
 
 ### Cursor
@@ -109,7 +111,11 @@ legend.data.setAll(chart.series.values);
 series.set("tooltip", am5.Tooltip.new(root, {
   labelText: "{name}: {valueY}"
 }));
+
+// For column/bar series the tooltip text often lives on the columns template instead:
+series.columns.template.set("tooltipText", "{categoryX}: {valueY}");
 ```
+A tooltip enabled with no `labelText`/`tooltipText` shows an empty bubble — always give it text. See SKILL.md → Tooltip for background/text styling.
 
 ### Stacking
 ```js
@@ -253,6 +259,11 @@ renderer.labels.template.setAll({
 });
 ```
 
+**Axis sub-element defaults:** grid and labels are visible by default; **ticks default to `visible:false`**. To show ticks you must raise `visible` (and give them a non-zero `strokeOpacity`) — toggling `forceHidden` won't reveal them:
+```js
+renderer.ticks.template.setAll({ visible: true, strokeOpacity: 0.5, length: 5 });
+```
+
 ## LineSeries
 
 For line and area charts.

package/extended/examples/maps/map-sankey-series.md

@@ -0,0 +1,129 @@
+---
+title: "Map Sankey Series"
+source: "https://www.amcharts.com/docs/v5/charts/map-chart/map-sankey-series/"
+category: "maps"
+added: "2026-06-04"
+---
+
+`MapSankeySeries` (added in amCharts 5.17.0) draws variable-width curved bands between geographic points on a `MapChart` — a Sankey diagram projected onto a map, where band thickness encodes a numeric `value`. It extends `MapPolygonSeries` and generates real GeoJSON geometry, so bands follow the projection during pan, zoom, and globe rotation.
+
+Key implementation details
+A `MapSankeySeries` needs a reference `polygonSeries` (a `MapPolygonSeries` with geodata) to resolve country IDs to geographic centroids. Provide flow data as `{ sourceId, targetId, value }` using ISO 3166-1 alpha-2 country codes, or as explicit `{ sourceLongitude, sourceLatitude, targetLongitude, targetLatitude, value }` coordinates. When using `sourceId`/`targetId`, the series automatically waits for `polygonSeries` to finish parsing its geoJSON before resolving centroids — no `datavalidated` wrapper around `data.setAll()` is needed.
+
+Key settings (on `MapSankeySeries`):
+- `polygonSeries` — the `MapPolygonSeries` used to look up centroids (required for `sourceId`/`targetId` data).
+- `maxWidth` (default `5`) — maximum band width, in geographic degrees.
+- `controlPointDistance` (default `0.5`) — bezier curvature of the bands.
+- `nodeType` (default `"circle"`) — node shape: `"circle"` or `"bar"`.
+- `nodePadding` — extra padding around node shapes, in degrees.
+
+**WARNING:** never call `polygonSeries.data.setAll()` with your own objects — that replaces the geoJSON-derived data items and breaks `MapSankeySeries` centroid resolution. To set per-country properties (e.g. colors), iterate the existing data items inside the polygon series' `datavalidated` event instead.
+
+## JavaScript
+
+```javascript
+// Create root element
+// https://www.amcharts.com/docs/v5/getting-started/#Root_element
+var root = am5.Root.new("chartdiv");
+
+// Set themes
+// https://www.amcharts.com/docs/v5/concepts/themes/
+root.setThemes([am5themes_Animated.new(root)]);
+
+// Create the map chart
+// https://www.amcharts.com/docs/v5/charts/map-chart/
+var chart = root.container.children.push(am5map.MapChart.new(root, {
+  panX: "rotateX",
+  panY: "translateY",
+  projection: am5map.geoNaturalEarth1()
+}));
+
+// Country polygons — also used by the Sankey series to resolve centroids
+// https://www.amcharts.com/docs/v5/charts/map-chart/map-polygon-series/
+var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
+  geoJSON: am5geodata_worldLow
+}));
+polygonSeries.mapPolygons.template.setAll({
+  fill: am5.color(0xdddddd),
+  stroke: am5.color(0xffffff),
+  strokeWidth: 0.5
+});
+
+// Highlight the countries involved (set fills on existing geoJSON data items —
+// do NOT call polygonSeries.data.setAll() with custom objects)
+var endpoints = ["BR", "VN", "CO", "DE", "US", "FR", "JP", "CA"];
+polygonSeries.events.on("datavalidated", function () {
+  am5.array.each(polygonSeries.dataItems, function (di) {
+    if (endpoints.indexOf(di.get("id")) !== -1) {
+      di.get("mapPolygon").set("fill", am5.color(0xb0c4a0));
+    }
+  });
+});
+
+// Map Sankey series
+// https://www.amcharts.com/docs/v5/charts/map-chart/map-sankey-series/
+var sankeySeries = chart.series.push(am5map.MapSankeySeries.new(root, {
+  polygonSeries: polygonSeries,
+  maxWidth: 3,
+  controlPointDistance: 0.4,
+  nodePadding: 0.3
+}));
+
+// Band (link) appearance
+sankeySeries.mapPolygons.template.setAll({
+  fill: am5.color(0x6b4f3a),
+  fillOpacity: 0.6,
+  strokeOpacity: 0,
+  tooltipText: "{sourceNode.name} → {targetNode.name}: {value}"
+});
+
+// Node appearance
+sankeySeries.nodes.mapPolygons.template.setAll({
+  fill: am5.color(0x3c2415),
+  stroke: am5.color(0xffffff),
+  strokeWidth: 1,
+  tooltipText: "{name}: {sum}"
+});
+
+// Flow data — { sourceId, targetId, value } using ISO 3166-1 alpha-2 codes.
+// Set directly: the series auto-resolves IDs once polygonSeries loads its geoJSON.
+sankeySeries.data.setAll([
+  // Producers → hubs
+  { sourceId: "BR", targetId: "US", value: 450 },
+  { sourceId: "BR", targetId: "DE", value: 350 },
+  { sourceId: "VN", targetId: "DE", value: 200 },
+  { sourceId: "CO", targetId: "US", value: 250 },
+  // Hubs → consumer markets
+  { sourceId: "DE", targetId: "FR", value: 150 },
+  { sourceId: "US", targetId: "CA", value: 120 },
+  { sourceId: "US", targetId: "JP", value: 80 }
+]);
+
+// Auto-created nodes only know their id — give them readable names
+var countryNames = {
+  BR: "Brazil", VN: "Vietnam", CO: "Colombia", DE: "Germany",
+  US: "United States", FR: "France", JP: "Japan", CA: "Canada"
+};
+sankeySeries.events.on("datavalidated", function () {
+  am5.array.each(sankeySeries.nodes.dataItems, function (di) {
+    var id = di.get("id");
+    if (id && countryNames[id]) {
+      di.set("name", countryNames[id]);
+    }
+  });
+});
+
+// ALTERNATIVE — explicit coordinates instead of country IDs (no polygonSeries
+// lookup needed for these endpoints). Optional `waypoints` route the band
+// through intermediate points (keys MUST be "longitude"/"latitude"):
+// sankeySeries.data.setAll([
+//   {
+//     sourceLongitude: -47.9, sourceLatitude: -15.8,   // Brasília
+//     targetLongitude: 13.4,  targetLatitude: 52.5,    // Berlin
+//     value: 350,
+//     waypoints: [{ longitude: -25.0, latitude: 20.0 }]
+//   }
+// ]);
+
+chart.appear(1000, 100);
+```

package/extended/reference/hierarchy.md

@@ -32,6 +32,7 @@ Extended by: LinkedHierarchy, Pack, Partition, Treemap, VoronoiTreemap
 - **downDepth** (`undefined | number`) — Number of child levels to open when clicking on a node. Click here for more info
 - **fillField** (`undefined | string`) — A field in data that holds color used for fills for various elements, such as nodes.
 - **initialDepth** (`undefined | number`) — Number of levels to show on chart's first load. Click here for more info
+- **parentIdField** (`undefined | string`) — A field in data that holds the parent node's ID. Used with the `setFlatData(data)` method to build the hierarchy from a flat array (with parent-ID references) instead of nested `children`. @since 5.16.2
 - **patterns** (`PatternSet`) — A PatternSet to use when asigning patterns for nodes. Click here for more info @since 5.10.0
 - **selectedDataItem** (`DataItem`) — A data item for currently selected node. Click here for more info
 - **singleBranchOnly** (`undefined | false | true`) — If set to true will make all other branches collapse when some branch is expanded.

package/extended/reference/ihierarchysettings.md

@@ -99,6 +99,7 @@ Extended by: ILinkedHierarchySettings, IPackSettings, IPartitionSettings, ITreem
 - **downDepth** (`undefined | number`) — Number of child levels to open when clicking on a node. Click here for more info
 - **fillField** (`undefined | string`) — A field in data that holds color used for fills for various elements, such as nodes.
 - **initialDepth** (`undefined | number`) — Number of levels to show on chart's first load. Click here for more info
+- **parentIdField** (`undefined | string`) — A field in data that holds the parent node's ID. Used with the `setFlatData(data)` method to build the hierarchy from a flat array (with parent-ID references) instead of nested `children`. @since 5.16.2
 - **patterns** (`PatternSet`) — A PatternSet to use when asigning patterns for nodes. Click here for more info @since 5.10.0
 - **selectedDataItem** (`DataItem`) — A data item for currently selected node. Click here for more info
 - **singleBranchOnly** (`undefined | false | true`) — If set to true will make all other branches collapse when some branch is expanded.

package/extended/reference/imovingaveragedeviationsettings.md

@@ -73,5 +73,6 @@ Extends: IChartIndicatorSettings
 
 - **decreasingColor** (`Color`) — Decreasing color.
 - **increasingColor** (`Color`) — Increasing color.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.
 - **unit** (`"points" | "percent"`) — Default "points" How units are calculated.

package/extended/reference/imovingaveragesettings.md

@@ -73,4 +73,5 @@ Extended by: IBollingerBandsSettings, IMovingAverageEnvelopeSettings
 ## Properties
 
 - **offset** (`undefined | number`) — Default 0 Offset.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.

package/extended/reference/itreesettings.md

@@ -91,5 +91,8 @@ Extends: ILinkedHierarchySettings
 
 ## Properties
 
+- **clustered** (`undefined | false | true`) — Default false If set to true, uses a cluster (dendrogram) layout where all leaf nodes are placed at the same depth. @since 5.16.2
+- **fitNodes** (`undefined | false | true`) — Default false If set to true, hidden nodes are excluded from the layout, giving more space to visible ones. @since 5.18.0
 - **inversed** (`undefined | false | true`) — Default false If set to true, will flip the tree direction. @since 5.2.4
+- **nodeSeparation** (`undefined | (a: DataItem, b: DataItem) => number`) — Custom node-separation function; receives two data items and returns a numeric spacing value. @since 5.16.2
 - **orientation** (`"horizontal" | "vertical"`) — Default "vertical" Orientation of the diagram.

package/extended/reference/ivalueaxissettings.md

@@ -87,5 +87,6 @@ Extended by: IDateAxisSettings, IDurationAxisSettings
 - **strictMinMax** (`undefined | false | true`) — Force axis scale to be precisely at values as set in min and/or max. In case min and/or max is not set, the axis will fix its scale to precise lowest and highest values available through all of the series attached to it. This effectively locks the axis from auto-zooming itself when chart is zoomed in. If you need to zoom to actual low/high values within currently visible scope, use strictMinMaxSelection instead. Use extraMin and extraMax to add extra "padding". Click here for more info
 - **strictMinMaxSelection** (`undefined | false | true`) — Force axis to auto-zoom to exact lowest and highest values from attached series' data items within currently visible range. This is a good feature when your series is plotted from derivative values, like valueYChangeSelection as it helps to avoid frequent jumping of series to adjusted min and max of the axis. This will not work if strictMinMax is set to true (the axis will not zoom at all in this case). Use extraMin and extraMax to add extra "padding". @since 5.1.11
 - **syncWithAxis** (`ValueAxis`) — This setting can be set to an instance of another ValueAxis. If set the grid of this axis will be synced with grid of the target axis. NOTE: this is not 100% guaranteed to work. In some rare cases perfect sync might not be possible. Click here for more info
+- **syncZeros** (`undefined | false | true`) — Aligns the zero baseline across synced axes. Works only if `syncWithAxis` is set and zero is within the min/max of the axis. @since 5.16.2
 - **tooltipNumberFormat** (`string | NumberFormatOptions`) — A numeric format used for numbers displayed in axis tooltip. Click here for more info
 - **treatZeroAs** (`undefined | number`) — Treat zero values as some other value. Useful in situations where zero would result in error, i.e. logarithmic scale. Click here for more info

package/extended/reference/ivoronoitreemapsettings.md

@@ -95,4 +95,5 @@ Extends: IHierarchySettings
 - **cornerCount** (`undefined | number`) — Default 120 Number of corners when type is "polygon". 120 means the polygoon will look like a circle. NOTE: this setting is ignored if type="rectangle".
 - **maxIterationCount** (`undefined | number`) — Default 100 Maximum allowed number of iterations when computing the layout. Computation is stopped when it number of iterations is reached, even if the convergenceRatio is not yet reached. Bigger number means finer results, but slower performance.
 - **minWeightRatio** (`undefined | number`) — Default 0.005 Minimum weight ratio which allows computing the minimum allowed weight (= [maximum weight] * minWeightRatio). Setting very small minWeigtRatio might result flickering. NOTE: the nodes that have smaller weight will be scaled up and will not represent their true value correctly.
-- **type** (`"rectangle" | "polygon"`) — Default "polygon" Type of the diagram's shape. Click here for more info
+- **shapeType** (`"rectangle" | "polygon"`) — Default "polygon" Type of the diagram's shape. (Renamed from `type` in 5.18.0.) Click here for more info
+- **type** (`"rectangle" | "polygon"`) — *Deprecated since 5.18.0 — use `shapeType` (still works).* Default "polygon" Type of the diagram's shape.

package/extended/reference/movingaverage.md

@@ -24,7 +24,8 @@ Extended by: BollingerBands, MovingAverageEnvelope
 ## Settings
 
 - **offset** (`undefined | number`) — Default 0 Offset.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.
 
 ## Properties
 

package/extended/reference/movingaveragedeviation.md

@@ -24,7 +24,8 @@ Extends: ChartIndicator
 
 - **decreasingColor** (`Color`) — Decreasing color.
 - **increasingColor** (`Color`) — Increasing color.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.
 - **unit** (`"points" | "percent"`) — Default "points" How units are calculated.
 
 ## Properties

package/extended/reference/tree.md

@@ -22,5 +22,8 @@ Extends: LinkedHierarchy
 
 ## Settings
 
+- **clustered** (`undefined | false | true`) — Default false If set to true, uses a cluster (dendrogram) layout where all leaf nodes are placed at the same depth. @since 5.16.2
+- **fitNodes** (`undefined | false | true`) — Default false If set to true, hidden nodes are excluded from the layout, giving more space to visible ones. @since 5.18.0
 - **inversed** (`undefined | false | true`) — Default false If set to true, will flip the tree direction. @since 5.2.4
+- **nodeSeparation** (`undefined | (a: DataItem, b: DataItem) => number`) — Custom node-separation function; receives two data items and returns a numeric spacing value. @since 5.16.2
 - **orientation** (`"horizontal" | "vertical"`) — Default "vertical" Orientation of the diagram.

package/extended/reference/valueaxis.md

@@ -38,5 +38,6 @@ Extended by: DateAxis, DurationAxis
 - **strictMinMax** (`undefined | false | true`) — Force axis scale to be precisely at values as set in min and/or max. In case min and/or max is not set, the axis will fix its scale to precise lowest and highest values available through all of the series attached to it. This effectively locks the axis from auto-zooming itself when chart is zoomed in. If you need to zoom to actual low/high values within currently visible scope, use strictMinMaxSelection instead. Use extraMin and extraMax to add extra "padding". Click here for more info
 - **strictMinMaxSelection** (`undefined | false | true`) — Force axis to auto-zoom to exact lowest and highest values from attached series' data items within currently visible range. This is a good feature when your series is plotted from derivative values, like valueYChangeSelection as it helps to avoid frequent jumping of series to adjusted min and max of the axis. This will not work if strictMinMax is set to true (the axis will not zoom at all in this case). Use extraMin and extraMax to add extra "padding". @since 5.1.11
 - **syncWithAxis** (`ValueAxis`) — This setting can be set to an instance of another ValueAxis. If set the grid of this axis will be synced with grid of the target axis. NOTE: this is not 100% guaranteed to work. In some rare cases perfect sync might not be possible. Click here for more info
+- **syncZeros** (`undefined | false | true`) — Aligns the zero baseline across synced axes. Works only if `syncWithAxis` is set and zero is within the min/max of the axis. @since 5.16.2
 - **tooltipNumberFormat** (`string | NumberFormatOptions`) — A numeric format used for numbers displayed in axis tooltip. Click here for more info
 - **treatZeroAs** (`undefined | number`) — Treat zero values as some other value. Useful in situations where zero would result in error, i.e. logarithmic scale. Click here for more info

package/extended/reference/voronoitreemap.md

@@ -27,7 +27,8 @@ Extends: Hierarchy
 - **cornerCount** (`undefined | number`) — Default 120 Number of corners when type is "polygon". 120 means the polygoon will look like a circle. NOTE: this setting is ignored if type="rectangle".
 - **maxIterationCount** (`undefined | number`) — Default 100 Maximum allowed number of iterations when computing the layout. Computation is stopped when it number of iterations is reached, even if the convergenceRatio is not yet reached. Bigger number means finer results, but slower performance.
 - **minWeightRatio** (`undefined | number`) — Default 0.005 Minimum weight ratio which allows computing the minimum allowed weight (= [maximum weight] * minWeightRatio). Setting very small minWeigtRatio might result flickering. NOTE: the nodes that have smaller weight will be scaled up and will not represent their true value correctly.
-- **type** (`"rectangle" | "polygon"`) — Default "polygon" Type of the diagram's shape. Click here for more info
+- **shapeType** (`"rectangle" | "polygon"`) — Default "polygon" Type of the diagram's shape. (Renamed from `type` in 5.18.0.) Click here for more info
+- **type** (`"rectangle" | "polygon"`) — *Deprecated since 5.18.0 — use `shapeType` (still works).* Default "polygon" Type of the diagram's shape.
 
 ## Properties
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amcharts/amcharts5-mcp",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "mcpName": "io.github.amcharts/amcharts5",
   "description": "On-demand access to amCharts 5 docs, code examples, and API reference",
   "type": "module",

package/src/index.js

@@ -10,6 +10,10 @@ import { fileURLToPath } from "url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 
+// Single source of truth for the server version: package.json
+const PKG = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+const VERSION = PKG.version;
+
 // Submodule path (local dev) or content/ fallback (npm install)
 const SUBMODULE_DIR = join(ROOT, "amcharts5-skill", "amcharts5-skill");
 const CONTENT_DIR = join(ROOT, "content");
@@ -177,10 +181,38 @@ loadExtendedDir(EXTENDED_DIR);
 // Search helpers
 // ---------------------------------------------------------------------------
 
-function searchDocs(query, maxResults = 10) {
+/**
+ * Import sections carry two ### sub-blocks: one for ES modules, one for CDN /
+ * script tags. Return only the requested one (esm | html), or "" if not found.
+ */
+function extractImportBlock(body, format) {
+  const lines = body.split("\n");
+  const wantEsm = format === "esm";
+  let capturing = false;
+  let captured = [];
+  let sawSub = false;
+  for (const line of lines) {
+    const sub = line.match(/^###\s+(.+)/);
+    if (sub) {
+      sawSub = true;
+      const h = sub[1].toLowerCase();
+      const isEsm = /es module|esm|typescript|import/.test(h);
+      // Note: "typescript" contains "script", so match "script tag"/"cdn", not bare "script".
+      const isCdn = /cdn|script tag|<script/.test(h);
+      capturing = wantEsm ? isEsm : isCdn;
+      continue;
+    }
+    if (capturing) captured.push(line);
+  }
+  if (!sawSub) return ""; // no sub-blocks → caller falls back to full body
+  return captured.join("\n").trim();
+}
+
+function searchDocs(query, maxResults = 10, scope = "skill") {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
   const results = [];
 
+  // Skill docs (SKILL.md + references/*.md)
   for (const [name, doc] of docs) {
     for (const section of doc.sections) {
       const text = (section.heading + " " + section.body).toLowerCase();
@@ -188,15 +220,39 @@ function searchDocs(query, maxResults = 10) {
       if (score > 0) {
         results.push({
           file: name,
+          source: "skill",
           docTitle: doc.title,
           heading: section.heading,
           body: section.body.trim(),
-          score,
+          // Nudge skill results slightly ahead of extended on ties — the skill
+          // is the curated layer; extended is the exhaustive API reference.
+          score: score + 0.1,
         });
       }
     }
   }
 
+  // Extended docs (charts/, concepts/, getting-started/, reference/<class>) —
+  // this is where the per-class API + defaults live. Only scanned when scope=all.
+  if (scope === "all") {
+    for (const [key, doc] of extendedDocs) {
+      for (const section of doc.sections) {
+        const text = (section.heading + " " + section.body).toLowerCase();
+        const score = terms.reduce((s, t) => s + (text.includes(t) ? 1 : 0), 0);
+        if (score > 0) {
+          results.push({
+            file: key,
+            source: "extended",
+            docTitle: doc.title,
+            heading: section.heading,
+            body: section.body.trim(),
+            score,
+          });
+        }
+      }
+    }
+  }
+
   results.sort((a, b) => b.score - a.score);
   return results.slice(0, maxResults);
 }
@@ -207,7 +263,7 @@ function searchDocs(query, maxResults = 10) {
 
 const server = new McpServer({
   name: "amcharts5",
-  version: "1.0.0",
+  version: VERSION,
 });
 
 // --- Tool: list_chart_types ---
@@ -269,21 +325,25 @@ server.tool(
 // --- Tool: search_docs ---
 server.tool(
   "search_docs",
-  "Search across all amCharts 5 documentation for a keyword or topic. Returns matching sections ranked by relevance.",
+  "Search the curated amCharts 5 skill docs (SKILL.md + chart references) for a keyword or topic, returning matching sections ranked by relevance. NOTE: by default this scans ONLY the skill layer. The per-class API reference and per-setting DEFAULTS (e.g. tooltip background cornerRadius, axis tick `visible` default, cursor line strokeDasharray) live in the extended docs — pass scope:'all' here, or use search_all / get_api_reference / get_doc, to reach them.",
   {
     query: z.string().describe("Search query, e.g. 'legend', 'axis label rotation', 'tooltip format', 'data processor'"),
     maxResults: z.number().optional().default(5).describe("Maximum number of results to return (default 5)"),
+    scope: z.enum(["skill", "all"]).optional().default("skill").describe("'skill' (default) searches only the curated skill docs; 'all' also searches the extended docs / per-class API reference where settings and defaults live."),
   },
-  async ({ query, maxResults }) => {
-    const results = searchDocs(query, maxResults);
+  async ({ query, maxResults, scope }) => {
+    const results = searchDocs(query, maxResults, scope);
     if (results.length === 0) {
-      return { content: [{ type: "text", text: `No results found for "${query}".` }] };
+      const hint = scope === "skill"
+        ? ` Nothing in the skill docs — retry with scope:'all' to include the API reference, or use search_all.`
+        : "";
+      return { content: [{ type: "text", text: `No results found for "${query}".${hint}` }] };
     }
 
-    let text = `# Search results for "${query}"\n\n`;
+    let text = `# Search results for "${query}" (scope: ${scope})\n\n`;
     for (const r of results) {
       text += `## ${r.docTitle} → ${r.heading}\n`;
-      text += `*(source: ${r.file}.md, relevance: ${r.score})*\n\n`;
+      text += `*(source: ${r.source}/${r.file}.md, relevance: ${r.score})*\n\n`;
       // Truncate very long sections
       const body = r.body.length > 2000 ? r.body.slice(0, 2000) + "\n\n...(truncated)" : r.body;
       text += body + "\n\n---\n\n";
@@ -338,9 +398,16 @@ server.tool(
       };
     }
 
-    // Find the setup/core pattern section
+    // Grab the imports section first so we can exclude it from the setup match.
+    const importSection = doc.sections.find(s =>
+      /import/i.test(s.heading)
+    );
+
+    // Find the setup/core pattern section — must NOT be the imports section
+    // (headings like "Required imports" otherwise win and the actual core
+    // setup pattern is never shown, making esm/html identical).
     const setupSection = doc.sections.find(s =>
-      /setup|core.*pattern|basic|quick.*start|required.*import/i.test(s.heading)
+      s !== importSection && /setup|core.*pattern|basic|quick.*start/i.test(s.heading)
     );
 
     if (!setupSection) {
@@ -349,17 +416,17 @@ server.tool(
       return { content: [{ type: "text", text: intro }] };
     }
 
-    // Also grab the imports section
-    const importSection = doc.sections.find(s =>
-      /import/i.test(s.heading)
-    );
-
     let text = `# Quick Start: ${doc.title}\n\n`;
     if (importSection && importSection !== setupSection) {
+      // Import sections contain both an "ES modules" and a "CDN / script tags"
+      // sub-block. Emit only the one matching the requested format so esm and
+      // html actually differ (instead of relabeling the same body).
+      const esm = extractImportBlock(importSection.body, "esm");
+      const cdn = extractImportBlock(importSection.body, "html");
       if (format === "esm") {
-        text += `## Imports (ES modules)\n${importSection.body}\n\n`;
+        text += `## Imports (ES modules)\n${esm || importSection.body}\n\n`;
       } else {
-        text += `## Imports\n${importSection.body}\n\n`;
+        text += `## Imports (CDN / script tags)\n${cdn || importSection.body}\n\n`;
       }
     }
     text += `## ${setupSection.heading}\n${setupSection.body}`;
@@ -433,7 +500,7 @@ server.tool(
   "get_doc",
   "Get a full documentation page from the extended amCharts 5 docs. Use search_all first to find the right path.",
   {
-    path: z.string().describe("Doc path, e.g. 'charts/xy-chart/cursor', 'concepts/events', 'getting-started/integrations/react'"),
+    path: z.string().describe("Doc path, e.g. 'charts/xy-chart/cursor', 'concepts/events', 'getting-started/integrations/react', 'reference/xycursor' (per-class API). For a class's full settings + defaults prefer get_api_reference."),
   },
   async ({ path: docPath }) => {
     const key = docPath.replace(/^\/|\/$/g, "").replace(/\.md$/, "");
@@ -450,6 +517,56 @@ server.tool(
   }
 );
 
+// --- Tool: get_api_reference ---
+server.tool(
+  "get_api_reference",
+  "Get the per-class API reference for an amCharts 5 class — the class page PLUS its settings table (with DEFAULTS) and, optionally, its private/read-only settings. This is the authoritative source for exact setting names and default values (e.g. tooltip background cornerRadius, axis tick `visible` default). Pass a class name in any casing, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'AxisRendererX'.",
+  {
+    className: z.string().describe("amCharts 5 class name, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'ColumnSeries', 'AxisRendererX'. Casing/punctuation are ignored."),
+    includePrivate: z.boolean().optional().default(false).describe("Also include the private (read-only / internal) settings table. Default false."),
+  },
+  async ({ className, includePrivate }) => {
+    // Normalize: "XYCursor" / "xy-cursor" / "XY Cursor" → "xycursor"
+    const norm = className.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const classDoc = extendedDocs.get(`reference/${norm}`);
+    const settingsDoc = extendedDocs.get(`reference/i${norm}settings`);
+    const privateDoc = extendedDocs.get(`reference/i${norm}private`);
+
+    if (!classDoc && !settingsDoc) {
+      // Friendly not-found: suggest close matches among the class pages
+      // (reference keys that are NOT i…settings / i…private interface pages).
+      const classKeys = [...extendedDocs.keys()]
+        .filter(k => k.startsWith("reference/"))
+        .map(k => k.slice("reference/".length))
+        .filter(k => !k.startsWith("i"));
+      const suggestions = classKeys
+        .filter(k => k.includes(norm) || norm.includes(k))
+        .slice(0, 10);
+      let msg = `No API reference found for "${className}" (normalized "${norm}").`;
+      if (suggestions.length) {
+        msg += `\n\nDid you mean: ${suggestions.join(", ")}?`;
+      }
+      msg += `\n\nTip: use search_all to find the right class, or list_chart_types for chart families.`;
+      return { content: [{ type: "text", text: msg }] };
+    }
+
+    let text = "";
+    if (classDoc) {
+      text += `# ${classDoc.title}\n\n${classDoc.content}\n\n`;
+    }
+    if (settingsDoc) {
+      text += `\n---\n\n# ${settingsDoc.title} (settings + defaults)\n\n${settingsDoc.content}\n\n`;
+    }
+    if (includePrivate && privateDoc) {
+      text += `\n---\n\n# ${privateDoc.title} (private / read-only)\n\n${privateDoc.content}\n\n`;
+    }
+    if (!includePrivate && privateDoc) {
+      text += `\n---\n\n*Private/read-only settings also exist — call get_api_reference("${className}", includePrivate: true) to include them.*\n`;
+    }
+    return { content: [{ type: "text", text: text.trim() }] };
+  }
+);
+
 // --- Tool: list_examples ---
 server.tool(
   "list_examples",