plotagents 0.5.0 → 0.8.0

package/docs/api.md

@@ -3,7 +3,8 @@
 ```js
 import {
   plot, safePlot, lint, describe, render, toHTML, configure,
-  schema, toolDefinition, validatePalette, registerGeo,
+  dashboard, safeDashboard, renderDashboard, lintDashboard, planDashboard,
+  schema, dashboardSchema, toolDefinition, validatePalette, registerGeo, countWords,
 } from 'plotagents';
 ```
 
@@ -39,7 +40,11 @@ const { ok, svg, type, description, errors, warnings, suggestions } = safePlot(s
 
 ### `lint(spec)`
 
-Reviews a spec without drawing it and returns `{ ok, type, errors, warnings, suggestions }`. Messages are written in Spanish; each one carries a `fix` with the change to make.
+Reviews a spec without drawing it and returns `{ ok, type, errors, warnings, suggestions }`. Messages follow the spec's `locale` (Spanish by default, English with `locale: "en"`); each one carries a `fix` with the change to make.
+
+### `dashboard(spec)` · `safeDashboard(spec)` · `renderDashboard(el, spec)`
+
+A self-contained HTML dashboard with best-practice layout, shared colors, KPIs and filters. `safeDashboard` never throws and returns `{ ok, html, plan, errors, warnings, suggestions }`; `renderDashboard` draws into an element in the browser; `lintDashboard` reviews; `planDashboard` returns the layout decisions. See [Dashboards](dashboards.md).
 
 ### `describe(spec)`
 
@@ -49,7 +54,7 @@ Returns a text description of the chart, such as "Highest: Biobío with 1,240 (3
 
 ### `render(target, spec, opts?)`
 
-Draws into an element (a CSS selector or a DOM node) with tooltips, responsive width, time sliders, a range slider for time series, drill-down for treemaps and sunbursts, and click-to-focus for networks.
+Draws into an element (a CSS selector or a DOM node) with tooltips, responsive width, time controls when the spec asks for them (`slider: true`), drill-down for treemaps and sunbursts, click-to-focus for networks, collapsible Gantt phases, and legend clicks (shift + click excludes an entry; in treemaps and sunbursts a click zooms to the category).
 
 ```js
 const chart = plotagents.render('#chart', spec);
@@ -59,7 +64,7 @@ chart.destroy();                                // remove listeners and markup
 
 | Option | Meaning |
 |---|---|
-| `controls` | `false` hides sliders and play buttons. |
+| `controls` | `false` hides time controls even when the spec asks for them (`slider: true`). |
 
 The handle exposes `svg` (the current `<svg>` element) and `spec`.
 
@@ -89,7 +94,20 @@ configure();       // returns the current defaults
 configure(null);   // clears them
 ```
 
-It accepts any spec option: `font`, `textScale`, `locale`, `theme`, `palette`, `ramp` and so on.
+It accepts any spec option: `font`, `textScale`, `locale`, `theme`, `palette`, `ramp`, `colorScale`, `legend` and so on. A spec's own `theme` object is merged over the global one.
+
+### `registerTheme(name, theme)`
+
+Registers a named theme (merged over `extends`, `papel` by default) so `theme: name` and `configure({ theme: name })` can use it. See [Themes](themes.md#your-own-theme-everywhere).
+
+```js
+registerTheme('acme', { background: '#FFF', text: '#111', categorical: 'tab10', grid: { dash: '2 3' } });
+configure({ theme: 'acme' });
+```
+
+### `colorScaleNames()` · `resolveColorScale(name)`
+
+All color scale names grouped by kind (`sequential`, `diverging`, `cyclic`, `qualitative`), and the stops of one scale: `{ name, stops, kind }`. `interpolateColor(stops, t)` returns the color at `t ∈ [0, 1]` (OKLab).
 
 ### `validatePalette(colors, opts?)`
 

package/docs/charts.md

@@ -15,18 +15,26 @@ Every chart takes a spec with `data` (rows) plus field names for each role. The
 | `highlight` | One name or a list: emphasize these, mute the rest. |
 | `colors` | `{ "name": "#hex" }` to pin an entity's color. |
 | `format`, `xFormat`, `yFormat` | `"number" \| "compact" \| "percent" \| "currency" \| "integer"` or `{ prefix, suffix, decimals, currency }`. |
-| `locale` | `"es"` (default: `1.234,5`) or `"en"` (`1,234.5`). |
+| `locale` | `"es"` (default: `1.234,5`), `"en"` (`1,234.5`), `"pt"`, `"fr"` (`1 234,5`), `"de"`, or `"auto"`: recognized from the title, subtitle, column names and categories. Tables use `"auto"` when `locale` is omitted. |
 | `xLabel`, `yLabel` | Axis titles (horizontal, never rotated). |
 | `xScale`, `yScale` | `"log"` where it makes sense. |
 | `xDomain`, `yDomain` | Fixed `[min, max]`. |
 | `refLines` | `[{ y: 600, label: "Target" }]` (or `x`, or `value` for bars). |
 | `facet` (`col`), `columns`, `sharey`, `sharex` | Small multiples, one panel per value. |
-| `time`, `timeValue`, `slider`, `play` | One period at a time with a slider in the browser; `slider: false` removes it, `play: false` hides only the play button. |
+| `time`, `timeValue` | One period at a time: the latest by default, or `timeValue`. The period is appended to the subtitle. |
+| `slider`, `play` | Browser time controls, **off by default**. `slider: true` adds period buttons when there are few periods (≤ 8) and a minimal slider when there are many; line and area charts get a two-handle range. `"buttons"` or `"slider"` force one; `play: false` hides the play button. |
 | `compare` | With `time`: compare against `"previous"` (default), `"first"`, a given period, or `false`. |
 | `theme`, `palette`, `ramp` | See [themes](themes.md). |
+| `colorScale` (`cmap`) | Any matplotlib colormap (`"viridis"`, `"RdBu_r"`…) or your own list of colors. See [color scales](colorscales.md). |
 | `font`, `textScale` | Typeface (Google Fonts name, CSS stack or `{ family, import }`) and a text-size multiplier (aliases `fontScale`, `labelScale`). Set them for every chart with `configure()`. |
 | `width`, `height`, `padding` | Pixels. Height is automatic for horizontal bars, heatmaps, KPI tiles, and narrow treemaps, sunbursts and radars. |
-| `legend` | `false` hides the legend. |
+| `legend` | Position: `"top"` (default), `"bottom"`, `"left"`, `"right"`, or `false` to hide it. Side legends move to the bottom below 520 px. Setting a position also forces a legend where the chart would otherwise label lines directly. |
+| `exclude` | One name or a list: drop these legend entries (series, first-level groups) and recompute axes, shares and layout. Colors stay fixed and the excluded entries stay in the legend, faded and struck through. |
+
+### In the browser
+
+- **Tooltips** sit next to the hovered mark, never over the title or subtitle, and stay inside the chart. Their header takes the mark's color, with white or dark text depending on contrast.
+- **Legend**: hovering a key highlights its marks; a click pins the highlight. **Shift + click** excludes that entry (click it again to bring it back). In treemaps and sunbursts a plain click zooms the whole plot to that category; click it again, a breadcrumb, or press Esc to go back.
 
 ## Compare
 
@@ -62,7 +70,48 @@ Every chart takes a spec with `data` (rows) plus field names for each role. The
 | `points` | Markers on every point (automatic for short series). |
 | `stack` | Areas: `true` (default with series), `"percent"`, or `false` to overlap. |
 | `fill` | Single line: `false` removes the soft gradient. |
-| `xRange` | Visible range `[from, to]`; this is what the browser slider sets. |
+| `xRange` | Visible range `[from, to]`; this is what the range slider sets (`slider: true`). |
+
+## Projects
+
+### `gantt` (`timeline`, `roadmap`, `schedule`, `cronograma`)
+
+One row per task: `task`, `start` and `end` (or `duration`). Dates like `"2026-03-02"` or `"2026-03"`, or plain numbers for weeks or sprints. Day dates are **inclusive**: a task from March 3 to March 5 lasts 3 days. A row without `end`, or with `end` equal to `start`, is a milestone, drawn as a diamond with its date.
+
+The time axis sits on top, like a calendar. With `group`, each phase opens with its name and a thin summary bar in its color, so no legend is needed. The filled part of each bar is the progress; the rest stays in a light tint of the same color. Dependencies are thin right-angle arrows behind the bars.
+
+```js
+plot({
+  type: 'gantt',
+  title: 'The project goes live on June 15; the ERP integration is the critical path',
+  data: [
+    { phase: 'Design', task: 'Data model', start: '2026-02-09', end: '2026-03-06', progress: 80 },
+    { phase: 'Build', task: 'ERP integration', start: '2026-03-16', end: '2026-04-30', progress: 10, after: 'Data model' },
+    { phase: 'Launch', task: 'Go-live', start: '2026-06-15' },
+  ],
+  task: 'task', start: 'start', end: 'end', group: 'phase', progress: 'progress', dependsOn: 'after',
+  today: '2026-03-12', locale: 'en',
+});
+```
+
+| Option | Meaning |
+|---|---|
+| `task`, `start`, `end` | Field names (detected when they are called `task`/`tarea`, `start`/`inicio`, `end`/`fin`). |
+| `duration` | Length instead of `end`: days on a date axis, units on a numeric one. |
+| `group` (`series`, `hue`) | Phase or team: one colored section per value. `groupHeaders: false` uses a color legend instead. |
+| `progress` | 0–1 or 0–100. Shown as the filled part, with the percentage inside the bar when it fits. |
+| `dependsOn` | Field with the predecessor's name, or several: `"A, B"`. |
+| `milestone` | Boolean field that forces milestones. |
+| `today` | A date (or `true`) for the "today" line, labeled on the axis. `refLines: [{ x, label }]` adds more. |
+| `dashed`, `dashedLabel` | Hatch tentative tasks: a field (`dashed: "tentative"`), names or phases. |
+| `highlight` | Emphasize a task or a whole phase. |
+| `sort` | `"start"` orders tasks by date (default: data order, grouped by phase). |
+| `rowHeight`, `xLabel`, `unit` | Row height in px; axis title and unit for numeric axes. |
+| `collapsed`, `collapsible` | Phases drawn as one summary row (duration-weighted progress, milestone diamonds): a list of names or `true`. In the browser a click on a phase toggles it (Alt + click toggles all); the time axis and name column stay put. `collapsible: false` hides the chevrons. |
+| `critical`, `criticalColor` | Outline the critical path: tasks with zero slack along `dependsOn` (working days on day dates), with accent arrows. |
+| `weekends` | Weekend bands on day-date plans of up to 120 days; `false` turns them off. |
+
+`lint` warns about tasks that end before they start and suggests a `today` line. The alt text names the span, the longest task, the milestones and the overall progress weighted by duration.
 
 ## Relationships
 
@@ -85,6 +134,40 @@ Every chart takes a spec with `data` (rows) plus field names for each role. The
 | `kind` | `jointplot`: `"scatter"` or `"reg"`. |
 | `marginal` | `jointplot`: `"hist"` or `"kde"`. |
 
+### `corr` (`correlation`, `corrplot`) · `clustermap`
+
+Correlation matrix of numeric fields, computed for you from the rows (pairwise complete cases, like `df.corr()`). Each pair appears once, below the diagonal, on a diverging scale fixed at −1 to 1, so the same color means the same strength in every chart. Long labels turn 45°. The tooltip gives r, n and the p-value.
+
+```js
+plot({ type: 'corr', data, vars: ['income', 'schooling', 'poverty', 'density'], alpha: 0.05,
+  title: 'Where schooling is higher, income is higher (r = 0.85) and poverty lower (r = −0.81)' });
+```
+
+| Option | Meaning |
+|---|---|
+| `vars` | Fields to relate, in order. Default: every numeric field. `y: [...]` works too. |
+| `method` | `"pearson"` (default) or `"spearman"` (ranks: monotonic relations, robust to outliers). |
+| `triangle` | `"lower"` (default) or `"full"`. |
+| `cluster` | Reorder by hierarchical clustering (average linkage on 1 − r) and draw the dendrogram on top. `type: "clustermap"` sets it and shows the full matrix; `dendrogram: false` keeps the order without the tree. |
+| `alpha` | Grey out pairs with p ≥ alpha (Fisher's z) and add a legend key. |
+| `order` | Variable order (list). |
+| `highlight` | One variable: its row and column stay, the rest fade. |
+| `labelsFor` | Display names, e.g. `{ areas_verdes: "Green space" }`. |
+| `x`, `y`, `value` | Draw a matrix you already computed, in long form (one row per pair). |
+
+### `pairplot` (`pairs`, `splom`, `scattermatrix`)
+
+Scatter-plot matrix: each pair as a scatter below the diagonal, each variable's distribution on it (histogram, or density with `hue`), and Pearson r above, tinted by strength and split by `hue` group when there is room. Axes are shared by column and row; tick labels sit only on the outer edges.
+
+| Option | Meaning |
+|---|---|
+| `vars` | Fields to plot (3–6 read best). Default: the first 6 numeric fields. |
+| `hue` | Color by group, with a legend. |
+| `diag` | `"hist"` or `"kde"`. |
+| `upper` | `"corr"` (default), `"scatter"` or `false`. `corner: true` keeps only the lower triangle. |
+| `kind` | `"reg"` adds a least-squares line to every scatter panel. |
+| `radius`, `bins`, `panelSize` | Point radius, histogram bins, maximum panel size. |
+
 ### `radar` (`spider`)
 
 Long data (`axis`, `value`, `series`) or wide data (`axes: [fields]`, one row per series with `label`). `normalize` scales each axis to its own maximum (tooltips keep raw values); `grid: "polygon" | "circle"`; `domain`. Best with ≤ 4 series.
@@ -128,7 +211,8 @@ Long data (`axis`, `value`, `series`) or wide data (`axes: [fields]`, one row pe
 | Option | Meaning |
 |---|---|
 | `depth` | Show only the first N levels. |
-| `focus` | Path to drill into, e.g. `["Mining"]`. In the browser, clicking a group does it and breadcrumbs go back. |
+| `focus` | Path to drill into, e.g. `["Mining"]`. In the browser, clicking a group or its legend key does it (the category fills the whole plot) and breadcrumbs or Esc go back. |
+| `exclude` | Level-1 groups to leave out; the rest fill the plane and shares are recomputed. Shift + click on a legend key does it in the browser. |
 | `showValues` | Append values to the labels. |
 | `colorBy` | `"change"` colors tiles by % change vs the comparison period (growth cool, decline warm); `"label"` colors a single-level treemap by item. |
 | `shade` | Subtle lightness steps inside each category. Off by default: one solid color per category. |
@@ -157,26 +241,74 @@ Age groups (`age` or `y`), two sides (`sex`, `series` or `hue`) and a value. Bac
 
 ### `choropleth` (`map`) · `symbolmap` (`bubblemap`)
 
-Chilean regions (`geo: "chile"`, default), US states (`geo: "usa"`) and world countries (`geo: "world"`) ship with the library; any GeoJSON FeatureCollection works too. `key` is the data field to match and `value` the measure. Matching is forgiving: names, codes and aliases, ignoring accents, case and "Región de" ("RM", "Biobio", "XIII", "Aisén", "ARG", "EE.UU.", "TX", "Nueva York", "48").
+Chilean regions (`geo: "chile"`, default), US states (`geo: "usa"`) and world countries (`geo: "world"`) ship with the library, and **any geometry of your own** works too (see below). `key` is the data field to match and `value` the measure; a text `value` (a party, a language, a zone) colors by category with a legend of swatches. Matching is forgiving: names, codes and aliases, ignoring accents, case and "Región de" ("RM", "Biobio", "XIII", "Aisén", "ARG", "EE.UU.", "TX", "Nueva York", "48").
 
 **United States.** 50 states and DC in an Albers equal-area projection (`albersUsa`, the same composite as `d3.geoAlbersUsa`): Alaska (at 0.35×) and Hawaii sit in insets at the bottom left with a fine dashed frame; Puerto Rico gets its own inset only when the data includes it (`territories: true` forces it). Each state shows its postal code, plus the value when it fits; the small northeastern states (VT, NH, MA, RI, CT, NJ, DE, MD, DC) are labeled in a column on the right with leader lines. `values: false` keeps only the codes; `labels: false` removes them.
 
 | Option | Meaning |
 |---|---|
-| `geo` | `"chile"`, `"usa"`, `"world"`, a name registered with `registerGeo()`, or a GeoJSON object. |
-| `featureKey` | Feature property to match (default: tries code, id, ISO-3, name and aliases). |
+| `geo` | `"chile"`, `"usa"`, `"world"`, a name registered with `registerGeo()`, a GeoJSON or TopoJSON object, or (browser) a URL. |
+| `featureKey`, `nameKey` | Feature property to match, and the one with the display name (both detected when omitted). |
+| `fitTo` | Zoom to regions, a `[lonMin, latMin, lonMax, latMax]` box or `"markers"`. |
+| `markers`, `layers` | Points by lon/lat on top; extra GeoJSON lines, polygons or points over or under the map. |
 | `scale`, `classes` | `"quantile"` (default), `"equal"`, `"continuous"` or a list of breaks; 5 classes by default. |
 | `midpoint` / `diverging` | Diverging classes around a value (e.g. 0 for changes). |
 | `missing` | `"plain"` drops the hatch and the "No data" legend entry. |
 | `labels`, `bars` | Chile gets a north-to-south column with name, bar and value; `bars: false` hides the bars. World maps label the top N. |
-| `projection` | `"mercator"`, `"equalEarth"` or `"albersUsa"` (picked automatically). |
+| `projection` | `"mercator"`, `"equalEarth"`, `"albersUsa"`, `"equirectangular"`, `"conic"`, `"identity"`, `"planar"` or `{ type, parallels, rotate }` (picked automatically). |
+| `borderColor`, `borderWidth` | Region borders. |
 | `dashed`, `dashedLabel` | Hatch some regions (preliminary figures, disputed areas): names, codes or a data field. They keep their class color. |
 | `maxRadius` | `symbolmap`: largest circle radius. |
 
+#### Your own geometry: GeoJSON and TopoJSON
+
+`geo` takes whatever you have: a GeoJSON `FeatureCollection`, a single `Feature`, an array of features or a bare geometry, or a TopoJSON `Topology` (`geoObject` picks the object; default the first). Polygons are filled, lines are stroked and points become dots colored by value. In the browser, `render()` also accepts a URL and downloads it once: `geo: "/maps/comunas.topojson"`. In Node, read the file and pass the object.
+
+```js
+import { readFileSync } from 'node:fs';
+const comunas = JSON.parse(readFileSync('comunas-biobio.geojson', 'utf8'));
+plot({
+  type: 'choropleth',
+  geo: comunas,                       // properties: { CUT_COM: "08101", NOM_COM: "Concepción", … }
+  data: [{ comuna: 'Concepción', poverty: 7.1 }, { comuna: 'Coronel', poverty: 12.4 }],
+  key: 'comuna', value: 'poverty',   // NOM_COM is found automatically
+  markers: { data: hospitals, lon: 'lon', lat: 'lat', label: 'name', legend: 'Hospital' },
+  layers: [{ geo: rivers, label: 'Biobío river', stroke: '#5BA3E0', width: 2 }],
+  fitTo: ['Concepción', 'Talcahuano', 'Hualpén'],
+});
+```
+
+- **Matching without configuration.** Rows are matched against the usual keys (code, id, ISO-3, name, aliases); if some rows don't match, plotagents finds the feature property whose values do (`NOM_COM`, `CUT_REG`, `GEOID`, `ADMIN`…). `featureKey` forces one. Display names come from `nameKey`, or the first of `name`, `NOMBRE`, `NAME_1`, `ADMIN` and similar.
+- **Projections.** Picked from the geometry: Mercator for a country or region, Equal Earth for the world, and a plain cartesian plane when coordinates are not longitudes and latitudes (UTM metres, for instance). Set `projection` to `"equirectangular"`, `"conic"` (or `{ type: "conic", parallels: [-30, -45], rotate: 72 }`), `"identity"` (pixel coordinates, y down, for hand-drawn or tile maps) or `"planar"` (y up).
+- **Framing.** `fitTo` zooms to some regions, a box `[lonMin, latMin, lonMax, latMax]` or `"markers"`; the rest of the map stays as clipped context. `tall: false` turns off the side column for elongated shapes.
+- **Markers.** `markers: [{ lon, lat, label, value }]` or `{ data, lon, lat, label, size, color, legend, maxRadius }`: dots on top, area-proportional when there is a `size`, labels placed where they don't collide.
+- **Layers.** `layers: [{ geo, label, stroke, width, fill, dash, opacity, below }]` overlays rivers, roads, routes, faults or district lines (or draws them under the regions with `below: true`). A `label` adds a legend key.
+- **Style.** `borderColor`, `borderWidth`, `pointRadius`, `lineWidth`, `ramp` (a named or custom sequential ramp), `palette` and `colors` (categories).
+- **Register once, use by name.** `registerGeo('biobio', comunas, ['comunas-biobio'])` and then `geo: 'biobio'` in every spec, which keeps tool calls short for an agent.
+
 In the browser (`render()` or `toHTML()`), maps are interactive: hovering outlines the shape; clicking a region zooms to fit it (click again, double-click, Esc or the reset button to go back); Ctrl/⌘ + scroll zooms around the pointer (plain scroll keeps scrolling the page, as `chartjs-plugin-zoom` recommends with its `modifierKey`); pinch zooms on touch screens; drag pans when zoomed; +/− buttons work from the keyboard. Each color class in the legend is a key: hover it to light up its regions, click to pin. With `time`, every region's color transitions into the next period's instead of jumping, and the zoom is kept while the slider plays.
 
 `lint` warns about rows that match no region or country. Sources: Natural Earth 1:110m (public domain) for the world; Biblioteca del Congreso Nacional for Chilean regions (attribution in `src/geo/data/chile-regiones.js`); U.S. Census Bureau cartographic boundaries 1:10m (public domain) via us-atlas 3.0.1 for US states. In the browser, `dist/plotagents-geo.js` adds the geometries; `toHTML()` includes it only when a page has a map.
 
+### `pointmap` (`dotmap`, `tilemap`)
+
+Dots at longitude/latitude over a real basemap in Web Mercator. Fields `lon`/`lat` are found by name (lon, lng, longitude, longitud / lat, latitude, latitud). `size` → circle area (key in the corner, largest labeled); `hue` → category colors with a legend; numeric `value` → sequential ramp (`midpoint` for diverging, `colorScale` for any matplotlib map). Zoom and center fit the points (`zoom`, `center: [lon, lat]` to fix them).
+
+```js
+plot({ type: 'pointmap', data: cities, lon: 'lon', lat: 'lat', size: 'population', label: 'city',
+  title: 'Santiago concentrates 40% of the population', source: 'INE' });
+```
+
+| Option | Meaning |
+|---|---|
+| `tiles` | `"osm"` (default, OpenStreetMap), `"esri-gray"`, `"esri-dark"`, `"carto-light"` / `"carto-dark"` (free key: carto.com/basemaps/apikey), `"mapbox-light"` / `"mapbox-dark"` (public `pk.` token in `tilesKey`; `sk.` tokens are refused), `{ url, attribution, subdomains, maxZoom, retina }`, or `false` (vector world outline only). |
+| `tilesKey` | Key or token for CARTO, Mapbox or Esri. |
+| `tileStyle` | `"muted"` (default) desaturates and tints the tiles to the theme (a navy night map on `noche`); `"original"` keeps them as they are. |
+| `tileOpacity`, `zoom`, `center` | Tile opacity, fixed zoom level and `[lon, lat]` center. |
+| `labels`, `labelValues` | How many dots to name (8 largest by default), or a list; `labelValues: false` hides values. |
+
+The attribution is always drawn. Tiles are external images: they show in inline SVG, `render()` and `toHTML()`, **not** when the SVG is used as `<img>`, opened from a PDF converter, or offline; then the vector world outline underneath still gives context. `await embedTiles(svg)` inlines them as data: URIs (not for OSM, whose tile policy forbids bulk downloads; use `esri-gray` or your own server). For heavy traffic, use a provider with a key or your own tiles: OSM's servers are donated.
+
 ## Dashed shapes: estimates, projections, provisional figures
 
 Some numbers are not firm yet. Instead of a new color (which reads as a new category), plotagents keeps the shape's color and changes its texture: a hatched fill (stripes of the color over a light tint of it) and a dashed outline at 3:1 contrast. Lines get a dashed stroke with hollow points. It works in `bar`, `line`, `area`, `donut`/`pie`, `choropleth` and `symbolmap`.
@@ -193,7 +325,21 @@ This follows the Chart.js advice of using patterns (as `patternomaly` does) and
 
 ### `network` (`graph`)
 
-Edges in `data` (`from`, `to`, optional `value`), optional `nodes` with `id`, `group` and `size`. Deterministic force layout fitted to the whole area, or `layout: "circle"`. `labels` (number or list), `highlight` (a node and its neighbors), `focus` (a node id: it is pinned at the center and highlighted with its neighbors, all of them labeled; in the browser a click does it with a smooth transition, and a second click or Esc returns), `iterations`, `maxRadius`.
+Edges in `data` (`from`, `to`, optional `value`), optional `nodes` with `id`, `group` and `size`. Node area ∝ weight (weighted degree by default), color by group; edges curve in the color of their source node (`curveness`, default 0.3; `0` = straight), 1 px wide without a value field. The largest nodes are named (ink with a halo, never overlapping each other or a node); every name is in the tooltip. Hovering a node lights up its neighbors and their edges.
+
+`layout` picks the placement (all deterministic, all fitted to the area):
+
+| `layout` | Placement |
+|---|---|
+| `force` (default) | Force-directed (Barnes–Hut above 150 nodes). |
+| `circular` (`circle`) | Around a circle by group, a gap between groups, names rotated outward. |
+| `radial` | A tree from `focus` (or the most connected node); each ring is one step further. Links outside the tree are faint. |
+| `concentric` | Rings by weight, the largest in the centre, by group within each ring. |
+| `clusters` | One sunflower cluster per group, space ∝ √size. |
+| `tree` | The radial tree laid flat (left → right on wide areas), S-shaped connectors. |
+| `grid` | A grid ordered by group and weight, every node named. |
+
+`labels` (number, list or `true`), `highlight` (a node and its neighbors), `focus` (a node id: it goes to the center, or the root in `radial`/`tree`, and is highlighted with its neighbors, all labeled; in the browser a click does it with a smooth transition, and a second click or Esc returns), `iterations`, `maxRadius`, `curveness`.
 
 ### `chord`
 
@@ -213,6 +359,79 @@ Edges in `data` (`from`, `to`, optional `value`), optional `nodes` with `id`, `g
 
 `from`, `to`, `value` (also detects `source`/`target`). Color starts at the first stage with more than one node and flows downstream.
 
+### `wordcloud` (`words`, `tagcloud`, `nube`)
+
+Words sized by frequency, done carefully: every word horizontal; each word's **area** proportional to its count (font size grows with the square root); a deterministic spiral layout from the most frequent word outwards, with no collisions; one hue that darkens with frequency, or one color per `series` with a legend. If the important words don't fit, the whole cloud shrinks; the words that still don't fit are named in the alt text, never cut off.
+
+```js
+plot({ type: 'wordcloud', data, text: 'word', value: 'mentions', title: '“Data” dominates what companies ask for' });
+plot({ type: 'wordcloud', text: openAnswers, title: '…', subtitle: 'Mentions in 312 open answers' });  // raw text
+```
+
+| Option | Meaning |
+|---|---|
+| `text` | Field with the words, or the raw text to count (a string or a list of strings). Raw text drops Spanish and English stopwords and numbers. |
+| `textField` | A field of free text in each row (open survey answers): words are counted across rows. |
+| `value` | Weight of each word (default: 1 per row, summed). |
+| `series` | Color by group, with a legend. |
+| `top` | Most words to show (default 80). |
+| `stopwords`, `minLength` | Extra words to ignore; shortest word kept (default 3). |
+| `minFont`, `maxFont` | Font size range. |
+| `highlight` | Words to emphasize; the rest are muted. |
+
+A cloud is good at "what comes up most" and bad at "by how much". `lint` suggests a bar chart (`top: 15`) when there are few words, and asks for a `subtitle` that says what was counted.
+
 ### `kpi`
 
 `items: [{ label, value, delta, previous, period, good: "up" | "down", trend: [...], target, format }]`. Delta is a fraction (`0.12` → +12%); `good: "down"` for costs. Tiles reflow into balanced rows.
+
+## Tables
+
+### `table` (`tabla`, `datatable`)
+
+For when the reader needs to look up the exact number. Thin rules between rows and nothing else; numbers right-aligned in tabular figures with the same decimals down each column; empty cells as a dash. Each column gets the indicator that explains it.
+
+```js
+plot({
+  type: 'table',
+  title: 'Two of six projects are already over budget',
+  data: projects,
+  columns: ['project', 'area',
+    { field: 'progress', type: 'progress' },
+    { field: 'spent', label: 'Spent / budget', type: 'progress', target: 'budget', good: 'down' },
+    'status'],
+  sortBy: 'progress',
+});
+```
+
+| Column `type` | Draws | Inferred when |
+|---|---|---|
+| `bar` | Value + data bar on a shared scale (diverging around 0) | The main numeric column (`value`/`y`, or the first number); `bars: false` turns it off |
+| `delta` | ▲ / ▼ + signed change, green or red by `good` (`"down"` for costs) | Field named var, change, delta, growth, yoy, cambio, variación… |
+| `heat` | Cell tinted by a sequential scale (diverging when it crosses 0); `colorScale` per column | — |
+| `sparkline` | Mini line, last point in the accent | The field holds lists of numbers |
+| `progress` | Percent + meter; against `target` (field or number) or as 0–1 / 0–100 | Field named progress, avance, completion…, or meta/target/goal with fractions |
+| `badge` | Status pill | Values are status words (done, at risk, late, in progress… in es/en/pt/fr/de): good, warning, critical, info colors |
+| `check` | ✓ or a dash, with an accessible label | Booleans, or sí/no, yes/no… |
+| `date` | Readable date in the chart's language | ISO dates |
+| `link` | Underlined link; only `http(s)` and `mailto` get an `href` | URLs |
+| `rank` | Position under the current sort | `rank: true` |
+| `text`, `number` | Text (wraps to 2–3 lines) and plain numbers | Everything else |
+
+| Option | Meaning |
+|---|---|
+| `columns` | Order and type: field names or `{ field, label, type, format, align, width, good, target, colorScale, total, lines }`. Omit to use every field. `x`/`label` picks the row-name column and `y` a list of value columns. |
+| `sortBy`, `sort` | Column and direction (`"desc"` for numbers, `"asc"` for text by default). `sort: "-sales"` works too. Empty cells always go last. |
+| `pageSize`, `page` | Up to 15 rows are shown whole; beyond that, pages of 10. `pageSize: false` shows everything. The pager is numbers and arrows only (`11–20 / 248`, `‹ 1 2 3 … 25 ›`). |
+| `query` | Keep rows that contain these words, ignoring accents and case. |
+| `total` | Totals row: sums numbers, averages percents and progress, leaves changes blank. `{ sales: "mean" }` per column; `totalLabel` renames it. |
+| `group` | Rows under a tinted band per value, with a count. |
+| `highlight` | Rows whose name matches get a tint and an accent mark; the bars of the other rows are muted. |
+| `top` | Keep the first N rows after sorting. |
+| `cards` | `"auto"` (default) turns each row into a card when the columns do not fit (phones): name and main value on top, the bar under them, the other columns as label–value lines. `true` always, `false` never. |
+| `density`, `striped` | `"compact"` / `"comfortable"` rows; zebra stripes for very wide tables. |
+
+In the browser `render()` adds a search box above 20 rows (`search: false` hides it; `true` forces it), click-to-sort headers (natural order, reversed, then the original order), and page buttons; all of them work from the keyboard and announce `aria-sort` and `aria-current`. Resizing re-renders at the new width, so a table becomes cards on a phone and columns again on a desktop.
+
+The language of the few words a table writes (Total, Search, No results) and the number format come from `locale`; without it, the table recognizes the language from its own title, headers and categories.
+

package/docs/colorscales.md

@@ -0,0 +1,46 @@
+# Color scales
+
+Every colormap that ships with matplotlib is available by name, plus your own. Use them wherever a chart maps a number to a color: heatmaps, choropleths, point maps, treemaps colored by change and word clouds.
+
+```js
+plot({ type: 'heatmap', data, x: 'hour', y: 'day', value: 'trips', colorScale: 'viridis' });
+plot({ type: 'choropleth', geo: 'chile', data, key: 'region', value: 'change', colorScale: 'RdBu' });
+plot({ ...spec, colorScale: 'magma_r' });                       // _r reverses any map
+plot({ ...spec, colorScale: ['#FFF7EC', '#FC8D59', '#7F0000'] }); // your own stops
+plot({ ...spec, colorScale: { name: 'coolwarm', mid: 100 } });    // diverging around 100
+```
+
+- **Names are case-insensitive** (`'rdbu'` works) and `_r` reverses any map.
+- **Diverging maps center themselves**: on 0 when the data crosses zero, otherwise on the middle of the data. Set `mid` (or `midpoint`) to choose the center.
+- **Your own scale** is a list of two or more colors, evenly spaced from low to high, or `{ colors, reverse, mid }`.
+- Interpolation happens in OKLab, so steps look even. The stops were sampled from matplotlib 3.9 and stay within 2 ΔE (×100) of the original.
+- `cmap` and `colormap` are aliases of `colorScale`. The older `ramp` option still works.
+
+## Categorical palettes
+
+`palette` takes a list of colors, a plotagents palette, or one of matplotlib's qualitative maps:
+
+```js
+plot({ ...spec, palette: 'tab10' });
+plot({ ...spec, palette: 'Set2' });
+plot({ ...spec, palette: 'viridis' });   // a continuous map, sampled into distinct colors
+```
+
+The default palette is validated for color-vision deficiencies; `lint` checks any other palette you bring (see [Themes](themes.md#validating-a-palette)).
+
+## Which one?
+
+| Data | Use | Avoid |
+|---|---|---|
+| Ordered values, low → high | `viridis`, `cividis`, `magma`, `Blues`, `YlGnBu` | `jet`, `rainbow`, `hsv` (they invent edges where the data has none) |
+| Values around a meaningful center (0, a target, an average) | `RdBu`, `coolwarm`, `PuOr`, `BrBG` | a sequential map |
+| Angles, hours of the day, months | `twilight`, `hsv` | a sequential map |
+| Categories | `palette: 'tab10'`, `'Set2'`, `'Dark2'` | any continuous map as `colorScale` |
+
+`lint` flags the rainbow maps with a suggestion, and refuses a qualitative map used as a continuous scale.
+
+## All scales
+
+{{colorscales}}
+
+The list is also available in code: `colorScaleNames()` returns the names grouped by kind, and `resolveColorScale(name)` returns `{ name, stops, kind }`.

package/docs/dashboards.md

@@ -0,0 +1,79 @@
+# Dashboards
+
+`dashboard(spec)` turns a handful of chart specs into a finished, self-contained HTML dashboard. Like a single chart, the design decisions come built in: you say what goes on the page, and the library decides where and how.
+
+```js
+import { dashboard } from 'plotagents';
+import { writeFileSync } from 'node:fs';
+
+writeFileSync('sales.html', dashboard({
+  title: 'How are southern sales doing?',
+  subtitle: 'Sales by month, region and channel, 2024–2025, CLP millions',
+  source: 'Commercial ERP',
+  updated: '2026-01-05',
+  locale: 'en',
+  data: sales,                              // shared rows
+  kpis: [
+    { label: 'Sales 2025', field: 'sales', agg: 'sum', format: 'compact',
+      compare: { field: 'year', current: 2025, previous: 2024 }, trendBy: 'month' },
+    { label: 'Orders 2025', field: 'orders', agg: 'sum', format: 'compact',
+      compare: { field: 'year', current: 2025, previous: 2024 } },
+    { label: 'Online share', value: 0.361, delta: 0.13, format: 'percent', period: 'vs 2024' },
+  ],
+  filters: ['region', 'channel'],
+  charts: [
+    { type: 'line', x: 'month', y: 'sales', series: 'region', highlight: 'Ñuble',
+      title: 'Ñuble grew 37% this year, faster than any other region' },
+    { type: 'choropleth', geo: 'chile', key: 'region', value: 'sales', fitTo: ['Biobío', 'Ñuble', 'Maule', 'Araucanía'],
+      title: 'Biobío makes 36% of sales' },
+    { type: 'bar', x: 'channel', y: 'sales', series: 'year',
+      title: 'Online is the only channel growing strongly' },
+    { type: 'treemap', path: ['region', 'channel'], value: 'sales',
+      title: 'Physical stores are still half the business' },
+  ],
+}));
+```
+
+The page works without JavaScript: every chart is drawn on the server, so it opens in any browser, prints and converts to PDF. When the browser build is available (it is, in Node), the page also gets tooltips, map zoom and live filters. In a web app, `renderDashboard('#board', spec)` draws the same dashboard into an element.
+
+## What it decides for you
+
+These defaults come from dashboard design practice: Stephen Few's *Information Dashboard Design*, the Z-pattern of reading, and what makes business dashboards hard to read.
+
+| Rule | What plotagents does |
+|---|---|
+| **One question per dashboard** | The `title` is the question ("How are southern sales doing?"). `lintDashboard` warns above 9 charts and suggests splitting above 6. |
+| **Numbers first** | KPIs go in one row at the top, at most 5 (warning above). Each one has a label, the figure, its change with an arrow **and** a sign (never color alone), the comparison period and an optional sparkline. |
+| **Z-pattern reading** | The main chart comes right after the KPIs, at full width: the one marked `primary: true`, or else the first time series. |
+| **Full rows, no holes** | A 12-column grid in balanced rows: 2 charts → 6 + 6 (8 + 4 when one is wide), 3 → 4 + 4 + 4, 4 → two rows of two, 5 → 3 + 2. Panels in a row share a height. |
+| **Width follows the chart** | Time series, Gantt charts, heatmaps and flows read left to right, so they get wide panels. Donuts, KPIs and short rankings get narrow ones. Chile's map gets a narrow column. |
+| **Same thing, same color** | One color map across every chart: "Ñuble" is the same color in the line, the treemap and the bars. `colors` pins colors for the whole page. |
+| **One voice** | One theme, locale and typeface for every panel. The source appears once, at the bottom; a chart keeps its own source only when it differs. |
+| **Filters as buttons** | `filters` become buttons when a field has up to 6 values, and a dropdown when it has more. They filter every chart that has the field, recompute the KPIs and say what is filtered in each subtitle. A filter on a chart's `time` field moves that chart to the chosen period. |
+| **Phones** | One column in reading order; KPIs in two columns. |
+| **Print** | Panels don't break across pages; the filter bar is not sticky on paper. |
+
+## Spec
+
+| Option | Meaning |
+|---|---|
+| `title`, `subtitle` | The question, and the scope (measure, unit, period). |
+| `source`, `updated`, `note` | Footer and header metadata. |
+| `locale`, `theme`, `font`, `palette` | Applied to every chart (`theme: "noche"` for a dark dashboard). |
+| `data` | Shared rows. Charts without `data` use them; computed KPIs and filters work on them. |
+| `kpis` | `[{ label, value, delta, period, trend, good, format }]` (fixed) or `[{ label, field, agg, over, scale, compare, trendBy, format }]` (computed). `agg`: `sum`, `mean`, `median`, `min`, `max`, `count`, `distinct`, `ratio` (with `over`). `compare: { field, current, previous }` shows the current period and its change. `trendBy: "month"` draws the sparkline. |
+| `charts` | Chart specs, as in `plot()`. Per chart: `primary: true`, `size: "full" \| "large" \| "medium" \| "small"` or `span` (of 12). |
+| `filters` | `["region"]` or `[{ field, label, control: "buttons" \| "select", value }]`. |
+| `layout` | `"auto"` (default), `"executive"` (main chart full width, then pairs) or `"grid"` (equal panels). |
+| `colors` | `{ "Biobío": "#3A47B8" }` for every chart. |
+
+## For agents
+
+```js
+import { safeDashboard, toolDefinition } from 'plotagents';
+
+const tool = toolDefinition({ kind: 'dashboard' });   // JSON Schema of the dashboard spec
+const { ok, html, errors, warnings, suggestions } = safeDashboard(input);
+```
+
+`safeDashboard` never throws. It reviews the dashboard as a whole (too many charts or KPIs, several pies, mixed themes, filters on fields no chart has, panels without a title) and every chart in it, tagging each issue with the chart's number and title so the model knows which one to fix. `planDashboard(spec)` returns the layout decisions (panels, widths, rows, colors, filters) without drawing anything.

package/docs/es/agents.md

@@ -0,0 +1,102 @@
+# plotagents · guía para agentes de IA
+
+Una función, un objeto JSON. Sin decisiones de diseño: la biblioteca las toma por ti.
+
+```js
+import { plot, safePlot } from 'plotagents';
+const svg = plot({ type, data, x, y, series, title, subtitle, source });
+```
+
+## Reglas para un buen gráfico
+
+1. **`title` es el hallazgo**, una oración completa con la cifra clave: "Biobío concentra el 30% de las ventas", no "Ventas por región".
+2. **`subtitle` dice cómo leerlo**: medida, unidad y período.
+3. **Define siempre `source`.** Si los datos son inventados, usa `source: "illustrative data"`.
+4. `data` es una lista de filas (`[{ region: "Biobío", sales: 1240 }]`). Para una tabla ancha, pasa `y: ["revenue", "costs"]`.
+5. Usa `safePlot(spec)` como tu herramienta: nunca lanza excepciones y devuelve `errors`, `warnings` y `suggestions`, cada uno con un `fix`. Si `ok` es `false`, corrige el spec y vuelve a llamarla.
+6. Define `locale: "en"` para formatos numéricos en inglés (el valor por defecto es español: `1.234,5`); también hay `"pt"`, `"fr"`, `"de"` o `"auto"` para reconocerlo a partir del texto. Las tablas lo reconocen por sí solas.
+
+## Qué tipo usar
+
+| Para mostrar | `type` | Campos clave |
+|---|---|---|
+| Comparar categorías | `bar` | `x`, `y`, `series?`, `stack?` (`true` / `"percent"`), `top?` |
+| Contar filas por categoría | `countplot` | `x` |
+| Media por categoría con un IC | `barplot` o `point` | `x`, `y`, `hue?` |
+| Cambio en el tiempo | `line` | `x` fecha (`"2024-03"`) o año, `y`, `series?`; `ci: true` con varias observaciones por x |
+| Un plan de proyecto o un cronograma | `gantt` | `task`, `start`, `end` (o `duration`), `group?`, `progress?`, `dependsOn?`, `today?`, `collapsed?` |
+| Volumen en el tiempo | `area` | como `line`; se apila con `series` |
+| Medidas en escalas distintas | `line` + `index: true`, o `facet` | **no hay doble eje** |
+| Crecimiento exponencial | `line` + `yScale: "log"` | |
+| Relación entre dos medidas | `regplot` (ajuste + IC) / `scatter` / `bubble` | `x`, `y`, `hue?`, `size?`, `label?` |
+| Relación + marginales | `jointplot` | `x`, `y` |
+| Qué medidas se mueven juntas | `corr` (`correlation`) | `vars?` (por defecto: todos los campos numéricos), `method?` (`"spearman"`), `alpha?: 0.05`; `cluster: true` o `type: "clustermap"` las agrupa con un dendrograma |
+| Todos los pares de medidas a la vez | `pairplot` (`splom`) | `vars` (3–6), `hue?`, `corner?`, `kind?: "reg"` |
+| Distribución de una medida | `hist` (`kde: true`), `kde`, `ecdf` | `x`, `hue?` |
+| Distribución por categoría | `box`, `violin`, `strip`, `swarm` | `x` categoría, `y` medida, `hue?` |
+| Perfil multidimensional | `radar` | `axis`, `value`, `series` (≤ 4 series) |
+| Parte de un todo jerárquico | `treemap` o `sunburst` | `path: [level1, level2, …]`, `value` |
+| Parte de un todo, ≤ 6 partes | `donut` / `pie` | `label`, `value`; `half: true` para un semicírculo |
+| Magnitud en una grilla | `heatmap` | `x`, `y`, `value` |
+| Un valor por región, estado o país | `choropleth` (`symbolmap` para totales) | `geo: "chile" \| "usa" \| "world"` o cualquier objeto GeoJSON/TopoJSON, `key`, `value` (texto → un color por categoría) |
+| Puntos en lugares reales sobre un mapa de calles | `pointmap` | `lon`, `lat` (se detectan solos), `size?`, `hue?`, `value?`, `label?`; `tiles: "osm"` (por defecto) / `"esri-gray"` / `"esri-dark"`, o carto-* / mapbox-* con `tilesKey` |
+| Quién se conecta con quién | `network` | aristas `from`, `to`, `value?`; `nodes?` con `group`; `layout?` |
+| Intercambios entre pocos grupos | `chord` | `from`, `to`, `value` |
+| Estructura por edad | `pyramid` | `age`, `sex`, `value` |
+| Un proceso con decisiones | `flowchart` | `nodes` (`type`, `lane`), `edges` (`label`) |
+| Flujos entre etapas | `sankey` | `from`, `to`, `value` |
+| Una o más cifras | `kpi` | `items: [{ label, value, delta, period, trend, target, good }]` |
+| Valores exactos para consultar | `table` | `columns?: [field \| { field, type, label, format, good, target }]`, `sortBy?`, `total?`, `group?`; los tipos `bar`, `delta`, `heat`, `sparkline`, `progress`, `badge` y `check` se infieren cuando se omiten |
+| Lo que más aparece en un texto | `wordcloud` | `text` (campo o texto sin procesar), `value?`, `series?`; para comparar con exactitud, prefiere `bar` + `top` |
+
+Los nombres de seaborn funcionan (`histplot`, `kdeplot`, `boxplot`, `violinplot`, `lmplot`, `stripplot`, `swarmplot`, `pointplot`), y `hue` es un alias de `series`. Omite `type` para que se infiera de los datos.
+
+## Opciones más útiles
+
+- `highlight: "Ñuble"`: destaca una categoría o serie y atenúa el resto. `exclude: ["Maule"]` quita entradas y recalcula el gráfico; los colores no cambian.
+- `legend: "top" | "bottom" | "left" | "right" | false`: dónde va la leyenda (arriba por defecto).
+- `colorScale: "viridis"`: cualquier mapa de colores de matplotlib para mapas de calor, mapas y treemaps por variación (`"RdBu"` diverge en torno a 0; `_r` lo invierte; también sirve una lista de colores). `palette: "tab10"` para categorías.
+- `dashed` para lo que no es una cifra firme (estimaciones, proyecciones, cifras provisionales): un nombre, una lista o un campo de los datos (`dashed: "provisional"`). Las formas mantienen su color, con relleno achurado y contorno discontinuo. En un eje de tiempo, `dashedFrom: 2025` dibuja con trazo discontinuo las líneas, áreas y columnas desde ese año. **Define siempre `dashedLabel`** ("Proyección", "Preliminar") para que los lectores sepan qué significa el achurado.
+- `facet: "region"` (+ `columns`): un panel por valor, con una escala compartida.
+- `time: "year"`: un período a la vez (el más reciente) con la variación % respecto del anterior. Los controles de tiempo están **desactivados por defecto**: agrega `slider: true` solo cuando la persona pida recorrer los períodos (botones para ≤ 8 períodos y un deslizador mínimo en los demás casos; `"buttons"` / `"slider"` fuerzan uno de los dos, `play: false` oculta el botón de reproducir). Los treemaps se pueden colorear por variación con `colorBy: "change"`.
+- `refLines: [{ y: 600, label: "Target" }]` y `annotations: [{ x: "2024-01", label: "New branch" }]`.
+- `format: "percent" | "currency" | "compact" | "integer"` o `{ prefix, suffix, decimals }`.
+- `xScale` / `yScale: "log"`.
+- `table`: dale un título que enuncie el hallazgo, como a cualquier gráfico. Con más de 15 filas se pagina de a diez (`pageSize`), en teléfonos cada fila se muestra como una tarjeta y el navegador agrega orden, búsqueda y paginación. Usa `good: "down"` en los costos para que ▲ se vuelva rojo, `progress` con `target: "budget"` para el gasto frente al presupuesto y `total: true` para una fila de totales. Usa entre 4 y 7 columnas.
+- `theme: "noche"` o un objeto JSON (`{ extends, categorical, type, marks, font }`); `palette: [...]` para tus propios colores.
+- `font: "Poppins"` y `textScale: 1.5` (modo presentación); `configure({ font, textScale })` los define para todos los gráficos.
+- `network` + `focus: "node id"`: centra un nodo y destaca sus vecinos.
+- Tu propio mapa: `geo: <GeoJSON or TopoJSON>`; la propiedad que coincide se busca sola (`featureKey` para forzarla). Agrega `markers: [{ lon, lat, label }]`, `layers: [{ geo, label }]` para ríos o rutas, y `fitTo: ["Biobío"]` o una caja `[lonMin, latMin, lonMax, latMax]` para hacer zoom.
+- `gantt`: las fechas `end` por día son inclusivas; una fila sin `end` es un hito. Define siempre `today` en un plan en curso. `collapsed: ["Phase 2"]` (o `true`) pliega las fases en una barra resumen; en el navegador, un clic en una fase la abre o la cierra.
+- `network` + `layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid"` elige la disposición; `curveness: 0` endereza las aristas.
+- `pointmap` dibuja sobre teselas de OpenStreetMap por defecto (`tiles: "esri-gray"`, `"mapbox-light"` + `tilesKey`, o tus propias `{ url, attribution }`). Las teselas solo se cargan cuando el SVG va incrustado en la página o en `toHTML`, no dentro de `<img>`.
+- Tu propio estilo para todos los gráficos: `registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font })` y luego `configure({ theme: "acme" })`.
+- `geo: "usa"`: los estados coinciden por código postal ("TX"), nombre en inglés o en español, o código FIPS ("48"). Alaska y Hawái aparecen en recuadros; Puerto Rico aparece solo cuando tus datos lo incluyen. En el navegador, los mapas hacen zoom con un clic, con Ctrl/⌘ + rueda o pellizcando.
+
+## Errores que la biblioteca ya resuelve
+
+- Más de 8 series → de la 9.ª en adelante se pintan en gris; `lint` sugiere `highlight` o `facet`.
+- Etiquetas de líneas que chocan → se separan con líneas guía.
+- Dona con más de 6 partes → el resto se agrupa en "Otros".
+- Etiquetas de categoría largas → el gráfico pasa a horizontal.
+- Paleta propia difícil de distinguir → `lint` nombra el par problemático.
+- Números como texto ("1.234,5", "12%", "$ 3.000") → se interpretan automáticamente.
+- Decenas de miles de puntos → se dibujan como trazados agrupados y sigue siendo rápido.
+
+## Tableros
+
+Cuando alguien pida un dashboard, llama a `safeDashboard({ title, subtitle, source, data, kpis, charts, filters })` (herramienta: `toolDefinition({ kind: 'dashboard' })`). La disposición, los anchos, los colores compartidos y los filtros se deciden por ti:
+
+- `title` es la **pregunta** que responde el tablero; cada gráfico igual lleva su hallazgo como título.
+- Como máximo **5 KPI**, calculados a partir de `data` cuando sea posible: `{ label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }`.
+- **De 4 a 6 gráficos**. La primera serie de tiempo (o la que tenga `primary: true`) va a todo el ancho; el resto llena filas equilibradas.
+- `filters: ["region", "channel"]` se convierten en botones que filtran todos los gráficos y KPI.
+- No más de una dona; una sola `source` para la página.
+
+## Salidas
+
+- `plot(spec)` → cadena SVG. Insértala en HTML, Markdown, un archivo `.svg` o un PDF.
+- `toHTML([spec1, spec2])` → página autocontenida con tooltips, deslizadores y drill-down.
+- `describe(spec)` → texto alternativo del gráfico.
+- `schema` / `toolDefinition()` → JSON Schema y definición de herramienta (Anthropic u OpenAI).
+- CLI: `npx plotagents spec.json -o chart.svg`.