plotagents 0.0.0-stage → 0.7.0

package/AGENTS.md

@@ -0,0 +1,98 @@
+# plotagents · guide for AI agents
+
+One function, one JSON object. No design decisions: the library makes them.
+
+```js
+import { plot, safePlot } from 'plotagents';
+const svg = plot({ type, data, x, y, series, title, subtitle, source });
+```
+
+## Rules for a good chart
+
+1. **`title` is the finding**, a full sentence with the key number: "Biobío accounts for 30% of sales", not "Sales by region".
+2. **`subtitle` says how to read it**: measure, unit and period.
+3. **Always set `source`.** If the data is made up, use `source: "illustrative data"`.
+4. `data` is a list of rows (`[{ region: "Biobío", sales: 1240 }]`). For a wide table, pass `y: ["revenue", "costs"]`.
+5. Call `safePlot(spec)` as your tool: it never throws and returns `errors`, `warnings` and `suggestions`, each with a `fix`. If `ok` is `false`, fix the spec and call again.
+6. Set `locale: "en"` for English number formats (default is Spanish: `1.234,5`).
+
+## Which type
+
+| To show | `type` | Key fields |
+|---|---|---|
+| Compare categories | `bar` | `x`, `y`, `series?`, `stack?` (`true` / `"percent"`), `top?` |
+| Count rows per category | `countplot` | `x` |
+| Mean per category with a CI | `barplot` or `point` | `x`, `y`, `hue?` |
+| Change over time | `line` | `x` date (`"2024-03"`) or year, `y`, `series?`; `ci: true` with several observations per x |
+| A project plan or schedule | `gantt` | `task`, `start`, `end` (or `duration`), `group?`, `progress?`, `dependsOn?`, `today?`, `collapsed?` |
+| Volume over time | `area` | like `line`; stacks with `series` |
+| Measures on different scales | `line` + `index: true`, or `facet` | **there is no dual axis** |
+| Exponential growth | `line` + `yScale: "log"` | |
+| Relationship between two measures | `regplot` (fit + CI) / `scatter` / `bubble` | `x`, `y`, `hue?`, `size?`, `label?` |
+| Relationship + marginals | `jointplot` | `x`, `y` |
+| Distribution of one measure | `hist` (`kde: true`), `kde`, `ecdf` | `x`, `hue?` |
+| Distribution by category | `box`, `violin`, `strip`, `swarm` | `x` category, `y` measure, `hue?` |
+| Multi-dimensional profile | `radar` | `axis`, `value`, `series` (≤ 4 series) |
+| Hierarchical part-to-whole | `treemap` or `sunburst` | `path: [level1, level2, …]`, `value` |
+| Part-to-whole, ≤ 6 parts | `donut` / `pie` | `label`, `value`; `half: true` for a semicircle |
+| Magnitude on a grid | `heatmap` | `x`, `y`, `value` |
+| A value per region, state or country | `choropleth` (`symbolmap` for totals) | `geo: "chile" \| "usa" \| "world"` or any GeoJSON/TopoJSON object, `key`, `value` (text → one color per category) |
+| Dots at real places on a street map | `pointmap` | `lon`, `lat` (auto-detected), `size?`, `hue?`, `value?`, `label?`; `tiles: "osm"` (default) / `"esri-gray"` / `"esri-dark"`, or carto-* / mapbox-* with `tilesKey` |
+| Who is connected to whom | `network` | edges `from`, `to`, `value?`; `nodes?` with `group`; `layout?` |
+| Exchanges between a few groups | `chord` | `from`, `to`, `value` |
+| Age structure | `pyramid` | `age`, `sex`, `value` |
+| A process with decisions | `flowchart` | `nodes` (`type`, `lane`), `edges` (`label`) |
+| Flows between stages | `sankey` | `from`, `to`, `value` |
+| One or more numbers | `kpi` | `items: [{ label, value, delta, period, trend, target, good }]` |
+| What comes up most in text | `wordcloud` | `text` (field or raw text), `value?`, `series?`; prefer `bar` + `top` to compare exactly |
+
+seaborn names work (`histplot`, `kdeplot`, `boxplot`, `violinplot`, `lmplot`, `stripplot`, `swarmplot`, `pointplot`), and `hue` is an alias of `series`. Leave `type` out to infer it from the data.
+
+## Most useful options
+
+- `highlight: "Ñuble"`: emphasize one category or series and mute the rest. `exclude: ["Maule"]` drops entries and recomputes the chart; colors stay put.
+- `legend: "top" | "bottom" | "left" | "right" | false`: where the legend goes (top by default).
+- `colorScale: "viridis"`: any matplotlib colormap for heatmaps, maps and treemaps by change (`"RdBu"` diverges around 0; `_r` reverses; or a list of colors). `palette: "tab10"` for categories.
+- `dashed` for what is not a firm number (estimates, projections, provisional figures): a name, a list, or a data field (`dashed: "provisional"`). Shapes keep their color, with a hatched fill and a dashed outline. On a time axis, `dashedFrom: 2025` dashes lines, areas and columns from that year on. **Always set `dashedLabel`** ("Projection", "Preliminary") so readers know what the hatching means.
+- `facet: "region"` (+ `columns`): one panel per value, on a shared scale.
+- `time: "year"`: one period at a time (the latest) with % change vs the previous one. Time controls are **off by default**: add `slider: true` only when the person asks to move through periods (buttons for ≤ 8 periods, a minimal slider otherwise; `"buttons"` / `"slider"` force one, `play: false` hides play). Treemaps can be colored by change with `colorBy: "change"`.
+- `refLines: [{ y: 600, label: "Target" }]` and `annotations: [{ x: "2024-01", label: "New branch" }]`.
+- `format: "percent" | "currency" | "compact" | "integer"` or `{ prefix, suffix, decimals }`.
+- `xScale` / `yScale: "log"`.
+- `theme: "noche"` or a JSON object (`{ extends, categorical, type, marks, font }`); `palette: [...]` for your own colors.
+- `font: "Poppins"` and `textScale: 1.5` (presentation mode); `configure({ font, textScale })` sets them for every chart.
+- `network` + `focus: "node id"`: center a node and highlight its neighbors.
+- Your own map: `geo: <GeoJSON or TopoJSON>`; the matching property is found for you (`featureKey` to force it). Add `markers: [{ lon, lat, label }]`, `layers: [{ geo, label }]` for rivers or routes, and `fitTo: ["Biobío"]` or a `[lonMin, latMin, lonMax, latMax]` box to zoom.
+- `gantt`: day `end` dates are inclusive; a row without `end` is a milestone. Always set `today` on a live plan. `collapsed: ["Phase 2"]` (or `true`) folds phases into one summary bar; in the browser a click on a phase toggles it.
+- `network` + `layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid"` picks the placement; `curveness: 0` straightens edges.
+- `pointmap` draws on OpenStreetMap tiles by default (`tiles: "esri-gray"`, `"mapbox-light"` + `tilesKey`, or your own `{ url, attribution }`). Tiles load only when the SVG is inline or in `toHTML`, not inside `<img>`.
+- Your own look for every chart: `registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font })` then `configure({ theme: "acme" })`.
+- `geo: "usa"`: states match by postal code ("TX"), English or Spanish name, or FIPS ("48"). Alaska and Hawaii are insets; Puerto Rico appears only when your data has it. In the browser, maps zoom on click, Ctrl/⌘ + scroll or pinch.
+
+## Mistakes the library already handles
+
+- More than 8 series → the 9th onward turn gray; `lint` suggests `highlight` or `facet`.
+- Colliding line labels → spread apart with leader lines.
+- Donut with more than 6 parts → folds into "Other".
+- Long category labels → switches to horizontal.
+- Hard-to-tell custom palette → `lint` names the offending pair.
+- Numbers as text ("1.234,5", "12%", "$ 3.000") → parsed automatically.
+- Tens of thousands of points → drawn as batched paths, still fast.
+
+## Dashboards
+
+When someone asks for a dashboard, call `safeDashboard({ title, subtitle, source, data, kpis, charts, filters })` (tool: `toolDefinition({ kind: 'dashboard' })`). Layout, widths, shared colors and filters are decided for you:
+
+- `title` is the **question** the dashboard answers; every chart still gets its finding as title.
+- At most **5 KPIs**, computed from `data` when possible: `{ label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }`.
+- **4–6 charts**. The first time series (or the one with `primary: true`) goes full width; the rest fill balanced rows.
+- `filters: ["region", "channel"]` become buttons that filter every chart and KPI.
+- No more than one donut; one `source` for the page.
+
+## Outputs
+
+- `plot(spec)` → SVG string. Drop it into HTML, Markdown, an `.svg` file or a PDF.
+- `toHTML([spec1, spec2])` → self-contained page with tooltips, sliders and drill-down.
+- `describe(spec)` → alt text for the chart.
+- `schema` / `toolDefinition()` → JSON Schema and tool definition (Anthropic or OpenAI).
+- CLI: `npx plotagents spec.json -o chart.svg`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Navarrete
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+# plotagents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Beautiful charts from a single JSON spec, built for AI agents.**
+
+**[Documentation, live examples and playground →](https://carlosnavarrete.cl/plotagents/)**
+
+Data and field names go in; an accessible SVG comes out, with careful typography, colorblind-safe colors and tooltips. 34 chart types: the ones people reach for in seaborn, multi-level treemaps and sunbursts, choropleth maps of Chile, the United States and the world, networks, chord diagrams, population pyramids, flow charts and Gantt charts, plus word clouds, a dashboard builder with best-practice layouts, opt-in time controls, small multiples and fully JSON-configurable themes. Zero dependencies. Runs in Node, Deno, Bun and the browser.
+
+```bash
+npm install plotagents
+```
+
+```js
+import { plot } from 'plotagents';
+
+const svg = plot({
+  title: 'Biobío accounts for 30% of southern sales',
+  subtitle: 'Sales by region, CLP millions, 2025',
+  source: 'illustrative data',
+  data: [
+    { region: 'Biobío', sales: 1240 },
+    { region: 'Araucanía', sales: 880 },
+    { region: 'Ñuble', sales: 610 },
+  ],
+  x: 'region',
+  y: 'sales',
+  locale: 'en',
+});
+```
+
+![Columns](examples/svg/barras.svg)
+
+The [interactive gallery](https://carlosnavarrete.cl/plotagents/examples/), 61 charts with the code for each one, is also in [`examples/index.html`](examples/index.html). Try any spec live in the [playground](https://carlosnavarrete.cl/plotagents/playground/).
+
+## Why
+
+Agents are good at data and bad at charts: dual axes, 12-slice pies, titles that say nothing. plotagents takes design decisions out of the agent's hands. The rules come from data-visualization teaching for management (Wilke's *Fundamentals of Data Visualization*, the Data Viz Catalogue, the Atlas of Economic Complexity) and are written into the code:
+
+- **The title states the finding.** `lint` nudges toward it and `describe` writes the alt text.
+- **One axis.** There is no dual axis; `index: true` rebases series to 100 and `facet` draws panels on a shared scale.
+- **Labels at the end of every line**, always. When they collide they are spread apart and joined to their point by a thin leader line; a legend appears only when needed.
+- **Every pixel for the data.** The y axis sits inside the plot on its gridline; margins and type scale down on phones; treemaps, sunbursts, horizontal bars, heatmaps and KPI tiles size their own height.
+- **Color follows the entity.** Eight validated colors in a fixed order; "Copper" keeps its color when you filter, drill down or move through periods. One solid color per category.
+- **Legend and chart are connected.** Hover a legend key to light up its marks, click to pin, shift + click to drop that entry (axes and shares recompute, colors stay put). In treemaps a click zooms the whole plot to the category. The legend goes top by default, or `legend: "bottom" | "left" | "right"`.
+- **Tooltips that never cover the title.** They sit next to the hovered mark, stay inside the chart, and their header wears the mark's color with white or dark text picked by contrast. Arrow keys walk through the data.
+- **Estimates look like estimates.** `dashed` hatches the shapes that are projections or provisional figures (same color, striped fill, dashed outline) and `dashedFrom: 2025` turns lines, areas and columns dashed from that point on, over a soft labeled band. The legend says what the hatching means; hovering it lights up just those shapes.
+- **Maps you can explore.** Click a state or region to zoom to it, Ctrl/⌘ + scroll or pinch to zoom, drag to pan; +/−/reset buttons for the keyboard. Hovering outlines the shape instead of dimming the map, and each color class in the legend lights up its regions. Moving through years, colors glide from one to the next.
+- **Networks you can explore.** Curved edges in the source node's color, sized nodes and labels that never pile up. Pick the placement with `layout` (force, circular, radial, concentric, clusters, tree, grid). Click a node and it glides to the center with its connections highlighted; click again or press Esc to go back.
+- **Thin marks, quiet grid.** 4 px rounded data ends, 2.25 px lines, 2 px surface gaps instead of borders.
+- **Locale-aware numbers.** Spanish (Chile) by default: `1.234,5`, `56,1%`, `$18.500`. `locale: 'en'` gives `1,234.5`.
+
+## Chart types
+
+| Purpose | `type` (aliases) |
+|---|---|
+| Compare categories | `bar` (`barplot` with confidence intervals), `count` (`countplot`) |
+| Change over time | `line` (`lineplot`, `ci` for a confidence band), `area` |
+| Relationships | `scatter`, `bubble`, `regplot` (`lmplot`), `residplot`, `jointplot` |
+| Profiles | `radar` (`spider`) |
+| Distributions | `hist` (`histplot`), `kde` (`kdeplot`), `ecdf`, `box` (`boxplot`), `violin`, `strip`, `swarm` (`beeswarm`), `point` (`pointplot`) |
+| Part-to-whole | `treemap` (any depth, with % change over time), `sunburst`, `donut`, `pie` |
+| Maps | `choropleth` (Chile by region, US by state, world by country, or your own GeoJSON / TopoJSON with markers, layers and framing), `symbolmap`, `pointmap` (lat/lon dots over OpenStreetMap or Mapbox tiles) |
+| Projects | `gantt` (`timeline`, `roadmap`): phases that fold and unfold, progress, milestones, dependencies and a today line |
+| Networks and flows | `network`, `chord`, `sankey`, `flowchart` (with swimlanes) |
+| Populations | `pyramid` |
+| Grids | `heatmap` |
+| Numbers | `kpi` |
+| Text | `wordcloud` (words sized by frequency, or raw text to count) |
+| Dashboards | `dashboard({ title, kpis, charts, filters })`: a whole HTML dashboard with best-practice layout ([guide](docs/dashboards.md)) |
+
+Leave `type` out and it is inferred: dates → `line`, two measures → `scatter`, `source`/`target` → `sankey`, `path` → `treemap`, categories → `bar`. Every option is documented in [`docs/charts.md`](docs/charts.md).
+
+| | | |
+|---|---|---|
+| ![](examples/svg/lineas.svg) | ![](examples/svg/treemap-niveles.svg) | ![](examples/svg/regresion.svg) |
+| ![](examples/svg/violin.svg) | ![](examples/svg/sunburst.svg) | ![](examples/svg/histograma.svg) |
+| ![](examples/svg/radar.svg) | ![](examples/svg/sankey.svg) | ![](examples/svg/conjunto.svg) |
+| ![](examples/svg/mapa-chile.svg) | ![](examples/svg/cuerdas.svg) | ![](examples/svg/piramide.svg) |
+
+## Time, panels and drill-down
+
+```js
+// One period at a time (the latest). Controls are opt-in: `slider: true` adds
+// period buttons (few periods) or a minimal slider (many), with a play button.
+plot({ type: 'treemap', data, path: ['sector', 'product'], value: 'value', time: 'year', slider: true });
+
+// Time series: `slider: true` adds a two-handle range in the browser.
+render('#chart', { type: 'line', data, x: 'month', y: 'sales', series: 'region', slider: true });
+
+// Small multiples (seaborn's col / col_wrap) with shared scales and colors.
+plot({ type: 'area', data, x: 'month', y: 'sales', facet: 'region', columns: 3 });
+
+// Treemaps and sunbursts of any depth; click a group to drill down.
+plot({ type: 'sunburst', data, path: ['area', 'unit', 'item'], value: 'amount', focus: ['Teaching'] });
+
+// Log scales with 1-2-5 ticks and no empty decades.
+plot({ type: 'line', data, x: 'month', y: 'users', series: 'platform', yScale: 'log' });
+```
+
+## One switch for fonts and text size
+
+```js
+import { configure } from 'plotagents';
+
+configure({ font: 'Poppins', textScale: 1.5 });   // every chart from now on
+plot({ ...spec, textScale: 2 });                  // or per chart: presentation mode
+configure(null);                                  // back to defaults
+```
+
+`font` takes a Google Fonts name (it is loaded for you in the browser and in `toHTML()`), a CSS stack or `{ family, import }`. `textScale` multiplies every text size and the layout is recomputed with the real sizes, so labels at ×2 still never overlap. `configure()` also accepts `locale`, `theme`, `palette` or any other spec option.
+
+## Themes are JSON
+
+Everything visual is a JSON object merged over a base theme, so an agent can apply a brand without touching code. See [`docs/themes.md`](docs/themes.md).
+
+```js
+plot({
+  ...spec,
+  theme: {
+    extends: 'papel',              // or 'noche' (dark)
+    categorical: 'okabe-ito',      // palette name or a list of colors in fixed order
+    surface: '#FFFFFF',
+    font: { family: "'Poppins', sans-serif" },
+    type: { title: 22, titleWeight: 700 },
+    marks: { lineWidth: 3, barRadius: 8, barMax: 44 },
+    axes: { inside: false },
+  },
+});
+```
+
+Register it once and every chart uses it; the default look never changes unless you ask:
+
+```js
+registerTheme('acme', { background: '#FFF', text: '#111827', grid: { color: '#EEF0F4', dash: '2 3' }, categorical: 'tab10', font: 'Inter' });
+configure({ theme: 'acme' });
+```
+
+Every matplotlib colormap works by name for heatmaps, maps and treemaps by change: `colorScale: 'viridis'`, `'RdBu_r'`, or your own list of colors ([color scales](docs/colorscales.md)).
+
+`validatePalette(colors)` checks a custom palette with the same tests the built-in one passed (lightness band, chroma floor, colorblind separation, normal-vision separation), and `lint` runs it for you.
+
+## SVG, not Canvas
+
+plotagents renders SVG. Dense charts (more than 1,500 points) are drawn automatically as one path per color, with a nearest-point tooltip layer, which paints faster than Canvas while keeping vector output, server-side rendering and accessible text. The benchmark and the reasoning are in [`docs/rendering.md`](docs/rendering.md).
+
+| Points | SVG, one node per point | Canvas | plotagents (batched SVG) |
+|---|---|---|---|
+| 5,000 | 62 ms | 30 ms | 12 ms |
+| 20,000 | 671 ms | 100 ms | 38 ms |
+| 50,000 | 1,468 ms | 357 ms | 123 ms |
+
+## API
+
+```js
+import { plot, safePlot, lint, describe, render, toHTML, schema, toolDefinition, validatePalette } from 'plotagents';
+```
+
+| Function | Returns |
+|---|---|
+| `plot(spec)` | SVG string. Throws `PlotError` with a fix hint. |
+| `safePlot(spec)` | `{ ok, svg, description, errors, warnings, suggestions }`. Never throws. |
+| `lint(spec)` | Review of the spec without drawing: errors and design suggestions. |
+| `describe(spec)` | Alt text ("Highest: Biobío with 1,240 (30%)…"). |
+| `render(el, spec)` | Browser: tooltips, responsive width, drill-down, and time controls when the spec asks for them. |
+| `toHTML(specs)` | A self-contained, interactive HTML page in one file. |
+| `schema` / `toolDefinition({ flavor })` | JSON Schema of the spec and a tool definition for Claude (`anthropic`) or OpenAI (`openai`). |
+| `validatePalette(colors, opts)` | `{ ok, checks }`. |
+
+In the browser without a bundler, `<script src="dist/plotagents.js"></script>` defines `window.plotagents`. Full types are in [`index.d.ts`](index.d.ts) and every option in [`schema.json`](schema.json).
+
+## As an agent tool
+
+```js
+import Anthropic from '@anthropic-ai/sdk';
+import { safePlot, toolDefinition } from 'plotagents';
+
+const client = new Anthropic();
+const res = await client.messages.create({
+  model: process.env.ANTHROPIC_MODEL, // the model you use
+  max_tokens: 4096,
+  tools: [toolDefinition()],
+  messages: [{ role: 'user', content: 'Plot the distribution of service times per clinic: …' }],
+});
+const call = res.content.find((b) => b.type === 'tool_use');
+const { ok, svg, errors, suggestions } = safePlot(call.input);
+// If !ok, send `errors` back as the tool_result: every error carries a `fix`.
+```
+
+[`AGENTS.md`](AGENTS.md) is a short guide meant to be pasted into an agent's system prompt.
+
+## CLI
+
+```bash
+npx plotagents spec.json -o chart.svg       # SVG
+npx plotagents specs.json -o report.html    # several interactive charts on one page
+npx plotagents spec.json --lint             # review and suggestions
+npx plotagents --tool                       # tool definition
+```
+
+## Built-in palette
+
+| Theme | Surface | Categorical (fixed order) |
+|---|---|---|
+| `papel` | `#FCFBF9` | `#3A47B8` `#D42A5E` `#E8A33D` `#1E9C89` `#7B5CD6` `#B5562E` `#5BA3E0` `#8E9A2F` |
+| `noche` | `#0B0F2B` | `#6170E0` `#E63369` `#C4851C` `#22A892` `#9780E8` `#D06A3E` `#499BDA` `#909D2D` |
+
+Both pass the lightness, chroma, colorblind (adjacent ΔE OKLab ≥ 8) and normal-vision (≥ 15) checks. The order is part of the validation. Typeface: Mozilla Text, falling back to `system-ui`.
+
+## Development
+
+```bash
+npm test                 # tests (node:test)
+npm run build            # dist/plotagents.js for the browser
+npm run examples         # regenerates examples/svg and examples/index.html
+npm run site             # builds the GitHub Pages site into _site/ (docs, gallery, playground)
+```
+
+MIT © Carlos Navarrete

package/bin/plotagents.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// CLI: plotagents spec.json [-o salida.svg|.html] [--lint] [--schema] [--tool [openai] [dashboard]]
+//   cat spec.json | plotagents > grafico.svg
+// A spec with a `charts` list is a dashboard: it renders to a self-contained HTML page.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { plot, toHTML, lint, schema, toolDefinition, describe, dashboard, lintDashboard, dashboardSchema } from '../src/index.js';
+
+// `plotagents … | head` closes the pipe early: exit quietly instead of crashing.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (e) => { if (e && e.code === 'EPIPE') process.exit(0); throw e; });
+}
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+const VALUE_FLAGS = new Set(['-o', '--out', '--tool']);
+const TOOL_ARGS = new Set(['openai', 'anthropic', 'dashboard', 'chart']);
+const input = args.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(args[i - 1]) && !(TOOL_ARGS.has(a) && args.slice(0, i).includes('--tool')));
+const print = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n');
+
+if (flag('-h') || flag('--help')) {
+  print(`plotagents — gráficos bellos desde un spec JSON
+
+Uso:
+  plotagents spec.json                 SVG a la salida estándar
+  plotagents spec.json -o grafico.svg  guarda SVG
+  plotagents spec.json -o reporte.html página HTML interactiva (acepta un arreglo de specs)
+  plotagents tablero.json -o tablero.html  dashboard (un spec con \`charts: [...]\`)
+  plotagents spec.json --lint          revisa el spec y sugiere mejoras (JSON)
+  plotagents spec.json --describe      descripción en texto del gráfico
+  plotagents --schema [dashboard]      JSON Schema del spec (o del dashboard)
+  plotagents --tool [openai] [dashboard]  definición de herramienta para agentes
+  cat spec.json | plotagents           también lee de stdin`);
+  process.exit(0);
+}
+// Tool and schema flags accept "openai" and/or "dashboard" in any order after the flag.
+const after = (f) => { const i = args.indexOf(f); return i >= 0 ? args.slice(i + 1).filter((a) => TOOL_ARGS.has(a)) : []; };
+if (flag('--schema')) { print(JSON.stringify(after('--schema').includes('dashboard') ? dashboardSchema : schema, null, 2)); process.exit(0); }
+if (flag('--tool')) {
+  const t = after('--tool');
+  print(JSON.stringify(toolDefinition({ flavor: t.includes('openai') ? 'openai' : 'anthropic', kind: t.includes('dashboard') ? 'dashboard' : 'chart' }), null, 2));
+  process.exit(0);
+}
+
+let raw;
+try { raw = input ? readFileSync(input, 'utf8') : readFileSync(0, 'utf8'); } catch (e) { console.error('No pude leer el spec:', e.message); process.exit(2); }
+let spec;
+try { spec = JSON.parse(raw); } catch (e) { console.error('El spec no es JSON válido:', e.message); process.exit(2); }
+
+const isDashboard = (s) => !!s && typeof s === 'object' && !Array.isArray(s) && Array.isArray(s.charts);
+
+if (flag('--lint')) {
+  const list = Array.isArray(spec) ? spec : [spec];
+  const out = list.map((s) => (isDashboard(s) ? lintDashboard(s) : lint(s)));
+  print(JSON.stringify(Array.isArray(spec) ? out : out[0], null, 2));
+  process.exit(out.every((r) => r.ok) ? 0 : 1);
+}
+try {
+  const outFile = opt('-o') ?? opt('--out');
+  if (isDashboard(spec)) {
+    if (flag('--describe')) { print([spec.title, ...spec.charts.map((c) => { try { return describe({ data: spec.data, ...c }); } catch (e) { return e.message.split('\n')[0]; } })].filter(Boolean).join('\n')); process.exit(0); }
+    const html = dashboard(spec);
+    if (outFile) { writeFileSync(outFile, html); console.error(`✓ ${outFile}`); } else process.stdout.write(html);
+  } else {
+    if (flag('--describe')) { print((Array.isArray(spec) ? spec : [spec]).map(describe).join('\n')); process.exit(0); }
+    const html = (outFile && outFile.endsWith('.html')) || flag('--html') || Array.isArray(spec);
+    const result = html ? toHTML(spec, { title: (Array.isArray(spec) ? spec[0] : spec).title || 'plotagents' }) : plot(spec);
+    if (outFile) { writeFileSync(outFile, result); console.error(`✓ ${outFile}`); } else process.stdout.write(result);
+  }
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}