@amcharts/amcharts5-mcp 1.2.0 → 1.3.2

package/README.md

@@ -10,6 +10,104 @@ Instead of loading the entire amCharts reference into the AI's context window, t
 
 ## Quick Start
 
+The easiest way is the **hosted server** — no install, just add one URL. Prefer to
+run it yourself? See [Local install](#local-install-npx) below.
+
+### Hosted (no install) — recommended
+
+Point your AI client at:
+
+```
+https://mcp.amcharts.com/mcp
+```
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http amcharts5 https://mcp.amcharts.com/mcp
+```
+
+**Claude Desktop / claude.ai** — Settings → Connectors → **Add custom connector**, then paste `https://mcp.amcharts.com/mcp`.
+
+**Cursor** — `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "url": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**VS Code + GitHub Copilot** — `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "amcharts5": {
+      "type": "http",
+      "url": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**Windsurf** — `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "serverUrl": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**ChatGPT** (Plus/Pro/Enterprise with connectors/developer mode enabled) — Settings → **Connectors** → **Add custom connector**, then paste `https://mcp.amcharts.com/mcp`.
+
+**Cline** (VS Code extension) — open the **MCP Servers** panel → **Remote Servers**, paste `https://mcp.amcharts.com/mcp`, or add to its MCP settings JSON:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "type": "streamableHttp",
+      "url": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**Clients that only support local (stdio) servers** (e.g. Zed, Continue, Amazon Q Developer) — bridge to the hosted URL with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Use this as the server's run command in the client's config:
+
+```bash
+npx mcp-remote https://mcp.amcharts.com/mcp
+```
+
+For example, in a `command`/`args` style config:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.amcharts.com/mcp"]
+    }
+  }
+}
+```
+
+Any other MCP client that accepts a remote server URL works too — use the `/mcp`
+endpoint (Streamable HTTP) or `/sse` (legacy SSE). For URL-only clients that still
+expect a command, use the `mcp-remote` bridge shown above.
+
+## Local install (npx)
+
+Prefer running it yourself? The server is also published to npm and runs over stdio.
+
 ### Claude Code
 
 For **all projects** (global, recommended):

package/content/gantt.md

@@ -47,10 +47,10 @@ var chart = root.container.children.push(
 | `editable` | boolean | `true` | Allow user to add, edit, remove, drag tasks |
 | `durationUnit` | string | `"day"` | `"year"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`, `"second"` |
 | `weekends` | number[] | `[0, 6]` | Non-working days (0=Sun, 1=Mon, ... 6=Sat) |
-| `excludeWeekends` | boolean | `true` | Whether to exclude weekends from task durations |
+| `excludeWeekends` | boolean | `false` | Whether to exclude weekends from task durations |
 | `holidays` | Date[] | `[]` | Specific non-working dates |
 | `snapThreshold` | number | `0.5` | Drag snap position within a period (0–1) |
-| `sidebarWidth` | number | — | Sidebar width in pixels or Percent |
+| `sidebarWidth` | number \| Percent | `30%` | Sidebar width in pixels or Percent |
 
 ## Data structure
 
@@ -134,7 +134,7 @@ Set `duration: 0` to create milestone markers.
 ```js
 chart.yAxis.setAll({
   minCellHeight: 80,    // row height in pixels (default: 70)
-  childCellSize: 1,     // child row size relative to parent (default: 0.7, 1 = same)
+  childCellSize: 1,     // child row size relative to parent (default: 0.8, 1 = same)
   childShift: 0         // child label indent in pixels (default: 25)
 });
 ```

package/content/stock.md

@@ -216,7 +216,7 @@ stockChart.indicators.push(am5stock.Volume.new(root, {
 | Indicator | Class | Needs volumeSeries |
 |-----------|-------|--------------------|
 | Moving Average | `MovingAverage` | No |
-| Moving Average Cross | `MovingAverageCross` | No |
+| Moving Average Cross | `MACross` | No |
 | Moving Average Envelope | `MovingAverageEnvelope` | No |
 | Moving Average Deviation | `MovingAverageDeviation` | No |
 | Bollinger Bands | `BollingerBands` | No |
@@ -281,8 +281,9 @@ var data = [
 ## Events
 
 ```js
-// Period changed
-stockChart.events.on("periodselected", (ev) => {
+// Period changed — the `periodselected` event fires on the PeriodSelector
+// instance, NOT on stockChart. Attach the handler to the selector you created.
+periodSelector.events.on("periodselected", (ev) => {
   console.log("Period:", ev.period);
 });
 

package/content/timeline.md

@@ -48,20 +48,24 @@ const chart = root.container.children.push(
   am5timeline.SerpentineChart.new(root, {
     orientation: "vertical",  // "vertical" | "horizontal"
     levelCount: 3,            // number of bends/turns
-    yAxisRadius: am5.percent(25),   // curve thickness
-    yAxisInnerRadius: -25,          // inner radius (negative = percentage of radius)
+    startLocation: 0,         // relative start of the "road" (0-1)
+    endLocation: 1,           // relative end of the "road" (0-1)
+    yAxisRadius: am5.percent(50),   // band thickness (Percent); applied to the Y axes' radius
   })
 );
 ```
 
-**Serpentine settings:**
+**Serpentine settings** (`ISerpentineChartSettings`):
 
-| Setting | Type | Description |
-|---------|------|-------------|
-| `orientation` | `"vertical"` \| `"horizontal"` | Direction of the snake pattern |
-| `levelCount` | number | Number of turns/bends |
-| `yAxisRadius` | percent/number | Outer radius of the curve |
-| `yAxisInnerRadius` | number | Inner radius (0 = filled, negative = relative) |
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | Direction of the snake pattern |
+| `levelCount` | number | `3` | Number of turns/bends |
+| `startLocation` | number | `0` | Relative location (0-1) of the start |
+| `endLocation` | number | `1` | Relative location (0-1) of the end |
+| `yAxisRadius` | `Percent` | `50%` | Band thickness — applied to every Y axis renderer's radius |
+
+> There is no `yAxisInnerRadius` setting on the chart. Band thickness is controlled by `yAxisRadius` (a `Percent`). For a plain `CurveChart` (no Serpentine/Spiral wrapper) the Y-axis band length is set via `AxisRendererCurveY`'s `axisLength` instead.
 
 ### SpiralChart
 
@@ -71,23 +75,25 @@ Wraps the chart into a spiral shape.
 const chart = root.container.children.push(
   am5timeline.SpiralChart.new(root, {
     levelCount: 3,             // number of spiral rings
-    inversed: true,            // spiral direction
+    startAngle: -90,           // start angle in degrees
     endAngle: -135,            // end angle in degrees
-    yAxisRadius: am5.percent(70),
-    yAxisInnerRadius: 0,
-    innerRadius: am5.percent(30),  // inner hole radius
+    yAxisRadius: am5.percent(60),  // band thickness (Percent)
+    innerRadius: am5.percent(30),  // inner hole radius (Percent)
   })
 );
 ```
 
-**Spiral settings:**
+**Spiral settings** (`ISpiralChartSettings`):
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `levelCount` | number | `3` | Number of spiral rings |
+| `startAngle` | number | `-90` | Where the spiral starts (degrees) |
+| `endAngle` | number | `0` | Where the spiral ends (degrees) |
+| `innerRadius` | `Percent` | `60%` | Size of the center hole |
+| `yAxisRadius` | `Percent` | `50%` | Band thickness — applied to every Y axis renderer's radius |
 
-| Setting | Type | Description |
-|---------|------|-------------|
-| `levelCount` | number | Number of spiral rings |
-| `inversed` | boolean | Spiral direction |
-| `endAngle` | number | Where the spiral ends (degrees) |
-| `innerRadius` | percent/number | Size of the center hole |
+> There is no `inversed` or `yAxisInnerRadius` setting on `SpiralChart`. To reverse direction use the `startAngle`/`endAngle` pair. (`inversed` is a valid axis-renderer setting, but not a chart setting.)
 
 ### CurveChart
 
@@ -306,8 +312,7 @@ chart.get("cursor").events.on("cursormoved", function(ev) {
       am5timeline.SerpentineChart.new(root, {
         orientation: "vertical",
         levelCount: 3,
-        yAxisRadius: am5.percent(25),
-        yAxisInnerRadius: -25
+        yAxisRadius: am5.percent(50)
       })
     );
 
@@ -399,10 +404,9 @@ chart.get("cursor").events.on("cursormoved", function(ev) {
     var chart = root.container.children.push(
       am5timeline.SpiralChart.new(root, {
         levelCount: 3,
-        inversed: true,
+        startAngle: -90,
         endAngle: -135,
-        yAxisRadius: am5.percent(70),
-        yAxisInnerRadius: 0,
+        yAxisRadius: am5.percent(60),
         innerRadius: am5.percent(30)
       })
     );

package/content/ui-elements.md

@@ -81,14 +81,16 @@ button.get("background").states.create("down", {
 ### Togglable button
 
 ```js
+// There is no `togglable` setting on Button. Make it a toggle by setting
+// `toggleKey: "active"` (a Sprite setting) — clicks then flip the `active` boolean.
 var button = container.children.push(am5.Button.new(root, {
-  togglable: true,
+  toggleKey: "active",
   label: am5.Label.new(root, { text: "Toggle" })
 }));
 
-// Check active state
+// Check active state via the `active` setting (there is no isActive() method)
 button.events.on("click", function(ev) {
-  var isActive = ev.target.isActive();
+  var isActive = ev.target.get("active");
   console.log("Active:", isActive);
 });
 ```

package/content/wordcloud.md

@@ -57,10 +57,10 @@ series.appear(1000);
 |---------|------|---------|-------------|
 | `categoryField` | string | — | Data field for word text (required) |
 | `valueField` | string | — | Data field for word weight/size (required) |
-| `maxFontSize` | percent/number | `am5.percent(20)` | Maximum font size |
-| `minFontSize` | percent/number | `am5.percent(2)` | Minimum font size |
-| `angles` | number[] | `[0, -90]` | Allowed rotation angles for words |
-| `randomness` | number (0–1) | `0.2` | Layout randomness (0 = ordered by value, 1 = fully random) |
+| `maxFontSize` | number \| Percent | `100` | Maximum font size (a `Percent` is relative to the smaller chart dimension) |
+| `minFontSize` | number \| Percent | `10` | Minimum font size (a `Percent` is relative to the smaller chart dimension) |
+| `angles` | number[] | `[0]` | Allowed rotation angles for words |
+| `randomness` | number (0–1) | `0` | Layout randomness (0 = ordered by value, 1 = fully random) |
 | `minWordLength` | number | `1` | Skip words shorter than this |
 | `maxCount` | number | — | Maximum number of words to display |
 | `excludeWords` | string[] | `[]` | Words to exclude |

package/content/xy.md

@@ -670,7 +670,7 @@ am5xy.XYChart.new(root, {
   wheelX: "panX",                 // mouse wheel: "panX", "panY", "zoomX", "zoomY", "none"
   wheelY: "zoomX",                // mouse wheel vertical
   pinchZoomX: true,               // mobile pinch zoom on X
-  arrangeFields: false,           // auto-arrange overlapping fields
+  arrangeTooltips: true,          // de-overlap stacked series tooltips (NOTE: there is no `arrangeFields` setting)
   maxTooltipDistance: 0,           // show tooltips for nearby series (-1 = all)
 })
 ```

package/extended/reference/iserpentinechartsettings.md

@@ -75,4 +75,5 @@ Extends: ICurveChartSettings
 - **levelCount** (`undefined | number`) — Default 3 Number of levels in the chart.
 - **orientation** (`"horizontal" | "vertical"`) — Default "vertical" Orientation of the serpatine.
 - **startLocation** (`undefined | number`) — Relative location (0-1) of the start postion. @defult 0
+- **yAxisRadius** (`Percent`) — Default 50% Radius of the Y-axis (band thickness); applied to every Y axis renderer's radius.
 

package/extended/reference/ispiralchartsettings.md

@@ -75,4 +75,5 @@ Extends: ICurveChartSettings
 - **innerRadius** (`Percent`) — Default 60% Inner radius of the spiral in percent.
 - **levelCount** (`undefined | number`) — Default 3 Numer of spiral circles.
 - **startAngle** (`undefined | number`) — Default -90 Start angle of the spiral in degrees.
+- **yAxisRadius** (`Percent`) — Default 50% Y-axis radius in percent (band thickness); applied to every Y axis renderer's radius.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amcharts/amcharts5-mcp",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "mcpName": "io.github.amcharts/amcharts5",
   "description": "On-demand access to amCharts 5 docs, code examples, and API reference",
   "type": "module",
@@ -18,6 +18,10 @@
   "scripts": {
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
+    "test": "node test.js",
+    "build:worker": "node scripts/build-worker-content.js",
+    "dev:worker": "npm run build:worker && wrangler dev",
+    "deploy": "npm run build:worker && wrangler deploy",
     "prepublishOnly": "node -e \"const fs=require('fs');if(!fs.existsSync('content'))fs.mkdirSync('content');fs.cpSync('amcharts5-skill/amcharts5-skill/SKILL.md','content/SKILL.md');for(const f of fs.readdirSync('amcharts5-skill/amcharts5-skill/references').filter(x=>x.endsWith('.md')))fs.cpSync('amcharts5-skill/amcharts5-skill/references/'+f,'content/'+f)\"",
     "postpublish": "node -e \"require('fs').rmSync('content',{recursive:true,force:true})\""
   },
@@ -48,5 +52,9 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "jsdom": "^29.0.0",
     "turndown": "^7.2.2"
+  },
+  "devDependencies": {
+    "agents": "^0.16.2",
+    "wrangler": "^4.102.0"
   }
 }

package/src/content-fs.js

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// Node-only disk loader.
+//
+// Reads raw markdown off the filesystem into the { skillFiles, extendedFiles }
+// shape consumed by buildContent(). Used by the stdio server (src/index.js) and
+// by the Worker content build script (scripts/build-worker-content.js).
+//
+// NOTE: imports `fs` — must NOT be imported by the Worker bundle.
+// ---------------------------------------------------------------------------
+
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { buildContent } from "./content.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+
+// Submodule path (local dev) or content/ fallback (npm install)
+const SUBMODULE_DIR = join(ROOT, "amcharts5-skill", "amcharts5-skill");
+const CONTENT_DIR = join(ROOT, "content");
+const SKILL_DIR = existsSync(SUBMODULE_DIR) ? SUBMODULE_DIR : CONTENT_DIR;
+const REFERENCES_DIR = existsSync(join(SKILL_DIR, "references"))
+  ? join(SKILL_DIR, "references")
+  : SKILL_DIR;
+const EXTENDED_DIR = join(ROOT, "extended");
+
+/**
+ * Read all skill + extended markdown into the raw { skillFiles, extendedFiles }
+ * shape that buildContent() expects.
+ */
+export function readRawFiles() {
+  const skillFiles = {};
+  const extendedFiles = {};
+
+  // Core SKILL.md
+  const skillPath = join(SKILL_DIR, "SKILL.md");
+  if (existsSync(skillPath)) {
+    skillFiles["SKILL"] = readFileSync(skillPath, "utf-8");
+  }
+
+  // Reference files (skip SKILL.md if it lives in the same dir as references)
+  if (existsSync(REFERENCES_DIR)) {
+    for (const file of readdirSync(REFERENCES_DIR)) {
+      if (!file.endsWith(".md") || file === "SKILL.md") continue;
+      skillFiles[file.replace(".md", "")] = readFileSync(join(REFERENCES_DIR, file), "utf-8");
+    }
+  }
+
+  // Extended docs + examples (recursive)
+  walkExtended(EXTENDED_DIR, "", extendedFiles);
+
+  return { skillFiles, extendedFiles };
+}
+
+function walkExtended(dir, prefix, out) {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkExtended(fullPath, prefix ? `${prefix}/${entry.name}` : entry.name, out);
+    } else if (entry.name.endsWith(".md")) {
+      const key = prefix
+        ? `${prefix}/${entry.name.replace(".md", "")}`
+        : entry.name.replace(".md", "");
+      out[key] = readFileSync(fullPath, "utf-8");
+    }
+  }
+}
+
+/** Read from disk and build the in-memory content structures. */
+export function loadContentFromDisk() {
+  return buildContent(readRawFiles());
+}

package/src/content.js

@@ -0,0 +1,214 @@
+// ---------------------------------------------------------------------------
+// Shared, transport-agnostic content layer.
+//
+// Pure logic only — NO filesystem, NO Node built-ins — so this module can be
+// bundled into the Cloudflare Worker as-is. The stdio server reads files from
+// disk (see content-fs.js) and the Worker imports a pre-generated bundle (see
+// scripts/build-worker-content.js); both feed the same buildContent() here so
+// the two deployments behave identically.
+// ---------------------------------------------------------------------------
+
+/** Chart type aliases → reference file mapping */
+export const CHART_TYPE_MAP = {
+  // XY family
+  "xy": "xy", "line": "xy", "area": "xy", "bar": "xy", "column": "xy",
+  "candlestick": "xy", "ohlc": "xy", "scatter": "xy", "bubble": "xy",
+  "stacked": "xy", "stacked-bar": "xy", "stacked-column": "xy",
+  "stacked-area": "xy", "range": "xy", "waterfall": "xy",
+  // Pie family
+  "pie": "pie", "donut": "pie", "funnel": "pie", "pyramid": "pie",
+  "semi-circle": "pie", "pictorial": "pie", "sliced": "pie",
+  // Map
+  "map": "map", "choropleth": "map", "geo": "map", "geographic": "map",
+  "world": "map", "country": "map", "bubble-map": "map", "point-map": "map",
+  // Hierarchy
+  "hierarchy": "hierarchy", "treemap": "hierarchy", "sunburst": "hierarchy",
+  "force-directed": "hierarchy", "pack": "hierarchy", "partition": "hierarchy",
+  "tree": "hierarchy", "org-chart": "hierarchy",
+  // Flow
+  "flow": "flow", "sankey": "flow", "chord": "flow", "arc": "flow",
+  "alluvial": "flow",
+  // Radar
+  "radar": "radar", "spider": "radar", "polar": "radar", "gauge": "radar",
+  "speedometer": "radar", "meter": "radar",
+  // Stock
+  "stock": "stock", "financial": "stock", "trading": "stock",
+  // Timeline
+  "timeline": "timeline", "serpentine": "timeline", "spiral": "timeline",
+  "curve": "timeline",
+  // Gantt
+  "gantt": "gantt", "project-timeline": "gantt",
+  // Word cloud
+  "wordcloud": "wordcloud", "word-cloud": "wordcloud", "tag-cloud": "wordcloud",
+  // Venn
+  "venn": "venn",
+  // UI
+  "ui": "ui-elements", "ui-elements": "ui-elements", "button": "ui-elements",
+  "slider": "ui-elements", "controls": "ui-elements",
+};
+
+export function parseSections(content) {
+  const sections = [];
+  const lines = content.split("\n");
+  let currentHeading = "";
+  let currentBody = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{1,3})\s+(.+)/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const title = headingMatch[2].trim();
+      if (level <= 2) {
+        // Major section boundary (# or ##)
+        if (currentHeading || currentBody.length > 0) {
+          sections.push({ heading: currentHeading, body: currentBody.join("\n") });
+        }
+        currentHeading = title;
+        currentBody = [];
+      } else {
+        // Sub-heading (###) — include in current section body
+        currentBody.push(line);
+      }
+    } else {
+      currentBody.push(line);
+    }
+  }
+  if (currentHeading || currentBody.length > 0) {
+    sections.push({ heading: currentHeading, body: currentBody.join("\n") });
+  }
+  return sections;
+}
+
+/**
+ * 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.
+ */
+export 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();
+}
+
+/**
+ * Build the in-memory content structures from raw markdown files.
+ *
+ * @param {{ skillFiles: Record<string,string>, extendedFiles: Record<string,string> }} raw
+ *   skillFiles  — name (no .md) → raw markdown for SKILL.md + references/*.md
+ *   extendedFiles — path key (no .md) → raw markdown for everything under extended/
+ * @returns {{ docs: Map, extendedDocs: Map, examples: Map }}
+ */
+export function buildContent({ skillFiles = {}, extendedFiles = {} } = {}) {
+  /** @type {Map<string, {title: string, content: string, sections: {heading: string, body: string}[]}>} */
+  const docs = new Map();
+  /** @type {Map<string, {title: string, content: string, sections: {heading: string, body: string}[], path: string}>} */
+  const extendedDocs = new Map();
+  /** @type {Map<string, {title: string, category: string, content: string, source: string}>} */
+  const examples = new Map();
+
+  // Skill docs (SKILL.md + references/*.md)
+  for (const [name, content] of Object.entries(skillFiles)) {
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    const title = titleMatch ? titleMatch[1] : name;
+    docs.set(name, { title, content, sections: parseSections(content) });
+  }
+
+  // Extended docs + examples (frontmatter-tagged markdown)
+  for (const [key, content] of Object.entries(extendedFiles)) {
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    const body = fmMatch ? fmMatch[2].trim() : content;
+    const fm = fmMatch ? fmMatch[1] : "";
+    const titleMatch = fm.match(/title:\s*"(.+?)"/);
+    const categoryMatch = fm.match(/category:\s*"(.+?)"/);
+    const sourceMatch = fm.match(/source:\s*"(.+?)"/);
+    const fallbackTitle = key.split("/").pop();
+    const title = titleMatch ? titleMatch[1] : fallbackTitle;
+
+    if (key.startsWith("examples/")) {
+      examples.set(key, {
+        title,
+        category: categoryMatch ? categoryMatch[1] : "",
+        content: body,
+        source: sourceMatch ? sourceMatch[1] : "",
+      });
+    } else {
+      extendedDocs.set(key, {
+        title,
+        content: body,
+        sections: parseSections(body),
+        path: key,
+      });
+    }
+  }
+
+  return { docs, extendedDocs, examples };
+}
+
+/**
+ * Keyword search over the skill docs and (optionally) the extended docs.
+ * @param {{docs: Map, extendedDocs: Map}} content
+ */
+export function searchDocs(content, 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 content.docs) {
+    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: name,
+          source: "skill",
+          docTitle: doc.title,
+          heading: section.heading,
+          body: section.body.trim(),
+          // 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 content.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);
+}