git:20261008.7b1e5b1 to git:20261009.b984196

# AGENTS.md — chart-dashboard

Instructions for any AI coding agent working in or with this repository.

Vendor-neutral: no Claude-specific tools, formats, or APIs are required.

## What this repo provides

A reusable capability: **turn supplied data into a single self-contained HTML

dashboard, report, slide deck, printable one-pager, email-safe chart snapshot or

Teams post with SVG charts.** No CDN, no npm install, no build step, no runtime dependencies.

The canonical instructions live in

[`plugins/chart-dashboard/skills/chart-dashboard/SKILL.md`](plugins/chart-dashboard/skills/chart-dashboard/SKILL.md). That file

is the source of truth — this one only routes you to it.

## When to use it

Any request to build a dashboard, analytics page, KPI view, chart deck,

illustrated data report, one-page printable brief or handout, charts to paste

into an email, or an insights post to share in Microsoft Teams, from data the

user provides or describes — a table, CSV, pasted numbers, metrics, notes, or a

topic with figures in it.

## How to use it

1. Read [`plugins/chart-dashboard/skills/chart-dashboard/SKILL.md`](plugins/chart-dashboard/skills/chart-dashboard/SKILL.md) and

follow its workflow.

2. Read these before writing chart code — do not guess option names:

- [`references/chart-api.md`](plugins/chart-dashboard/skills/chart-dashboard/references/chart-api.md) — the core API (factories, shared options, sizing); then `references/charts/<type>.md` for only the chart types you use

- [`references/chart-selection.md`](plugins/chart-dashboard/skills/chart-dashboard/references/chart-selection.md) — data shape → chart type

- [`references/layout.md`](plugins/chart-dashboard/skills/chart-dashboard/references/layout.md) — rules shared by every format; routes to `layout-dashboard.md`, `layout-report.md`, `layout-deck.md`, `layout-onepager.md`, `layout-email.md` or `layout-teams.md` (read only the one for your format)

- [`references/annotation.md`](plugins/chart-dashboard/skills/chart-dashboard/references/annotation.md) — callouts, plot bands, forecast vs. measured notation

- [`references/narrative.md`](plugins/chart-dashboard/skills/chart-dashboard/references/narrative.md) — action titles; where a finding goes (title, insight column, or card)

- [`references/controls.md`](plugins/chart-dashboard/skills/chart-dashboard/references/controls.md) — read before adding a filter or dropdown

- [`references/theming.md`](plugins/chart-dashboard/skills/chart-dashboard/references/theming.md) — brand recolour, and the two scripts under `scripts/` that generate it

- [`references/editable.md`](plugins/chart-dashboard/skills/chart-dashboard/references/editable.md) — only when the user asked for an editable page

- [`assets/charts-lib/charts.manifest.json`](plugins/chart-dashboard/skills/chart-dashboard/assets/charts-lib/charts.manifest.json) — quick per-engine facts (data shape, refusals, sizing)

3. Start from a template in `plugins/chart-dashboard/skills/chart-dashboard/templates/`: `dashboard.html`,

`report.html`, `slides.html` (a deck), `onepager.html` (one printed sheet),

`email.html` (a chart block to paste into Outlook or Gmail), `teams.html`

(rich text and chart pictures to paste into a Teams chat or channel), or

`dashboard-editable.html` / `report-editable.html` /

`slides-editable.html` / `email-editable.html` (only when an editable page

was asked for; a one-pager has no editable template and isn't offered one).

4. When you want a worked reference, read one of the finished pages in

`examples/` — `logistics-network-dashboard/` (dashboard, most chart types),

`coffee-pricing-deck/` (deck with the full spine), `ev-retrospective/`

(report). Read the templates and references first; the examples show how one

finished page turned out, not what every page should look like.

5. Stage the library beside your output while you build and verify it, then

fold it in and ship one file:

```bash

node plugins/chart-dashboard/skills/chart-dashboard/scripts/finalize.js index.html --stage # verify against this: run charts-lib/audit.js in the page (SKILL.md step 7)

node plugins/chart-dashboard/skills/chart-dashboard/scripts/finalize.js index.html # inline, clean up, gate

```

## Non-negotiables

- `theme.js` must load **before** `charts.js`. Reversed, `charts.js` starts on

its built-in defaults and logs a missing-theme warning; keep the order so the

page's theme is in place before any chart code runs.

- Donut and pie options (`centerText`, `valueSuffix`, `variableRadius`,

`startAngle`/`endAngle`, `showPercentages`) live under `plotOptions.pie`, not

at the top level. At the top level they are silently ignored.

- Never invent numbers that read as real measurements. If the user gave a topic

with no data, say so and label the figures illustrative on the page itself.

- Do not add a CDN link, npm dependency, or build step. The output must open

offline by double-click.

- Build static pages unless the user asked for an editable one. An editable page

ships as two files: `<name>.html` (final) and `<name> (working copy).html`.

- In a deck, lay the fixed spine first — cover, agenda, section dividers,

closing statement — then choose a layout per claim (`references/layout-deck.md`).

- A one-pager is a **report set in columns**, not a dashboard on paper: a fixed

730x990 sheet (990x730 landscape) whose body is columns of headings,

paragraphs, lists and figures. Prose carries the argument and the charts are

evidence. Never build a KPI tile row there. Nothing about the page's shape is

fixed except the sheet — pick the column tracks (`--cols`) and each figure's

height (`--fig-h`) from the content, and the template ships no arrangement on

purpose. Charts go **in** the columns: at the format's reduced type scale a

357px column holds a line, column or bar chart, and the manifest's minWidth is

the size a chart wants on a screen, not one it refuses below. Pack the page —

1660px of column run is about five figures and eight text blocks, and

under-filling it is the commonest failure. No controls and nothing hover-only,

because paper has no pointer. Budget and measured figure heights in

`references/layout-onepager.md`; `scripts/check-page.js` reports how full each

column is.

- An email snapshot is a 600px **table** block with every style inline, its

titles as text, and its charts frozen into PNGs when the page opens, because

Gmail and Outlook delete SVG, strip style sheets and run no script. Draw each

chart through `EmailSnapshot.draw(Charts.x, 'id', config)` so it freezes,

give it `data-alt` text that states the finding with its numbers, and keep

it to one to three findings. No controls and nothing hover-only. Rules and

budget are in `references/layout-email.md`, and `scripts/check-page.js`

lints the block.

- A Teams post is the email snapshot's freeze with the opposite markup:

Teams keeps headings, paragraphs, lists and pictures and drops every style,

so its block is plain semantic HTML with no class, style or colour, and its

charts are drawn through `TeamsSnapshot.draw` so they freeze to PNG. Never

reuse the email block for Teams, or the reverse. Rules are in

`references/layout-teams.md`.

- Derive the grid from the shape of the analysis; the dashboard template ships

without a starter arrangement on purpose. A wide hero cell goes to a finding

that genuinely leads, not to whatever panel was written first.

- A line chart needs an ordered x. Named categories — and a shuffled or partial

run like `['Jan', 'Mar', 'Feb']` — render an error panel. Write dates

(`'Jan 2025'`), a complete rising run (`'Jan'…'Jun'`, `'Q1'…'Q4'`), or use a

column chart (`references/charts/line.md`).

- `assets/charts-lib/` is a **vendored copy** of a library that lives in another

repo (`svg-charts`). Never fix a library bug here — a future sync would wipe

it, and the two copies would disagree in the meantime. Write the fix up in

[`CHARTS-LIB-UPSTREAM.md`](CHARTS-LIB-UPSTREAM.md) instead, as a diff against

the upstream engine file, and leave the copy alone; see *Recording a new

change* there. Patch the copy only when the skill cannot work without it, and

then say so in the same note. `node --test

plugins/chart-dashboard/skills/chart-dashboard/tests/upstream-notes.test.js` checks the copy against

what the note claims. Docs under `references/` are the skill's own — when the

library behaves surprisingly, saying so there is the fix to make here.

- If the page has a control, wire it completely: filter the data, redraw every

dependent panel and KPI, and recompute any title that states a finding. A

static page is fine; a half-wired dropdown is not.

## Using this skill in a different project

Copy the skill folder into the target project and point your agent at it:

```bash

cp -r plugins/chart-dashboard/skills/chart-dashboard /path/to/your-project/.agent-skills/chart-dashboard

```

Then add this block to whichever file that project's agent reads at startup:

```markdown

## Dashboards, reports and decks

When asked to build a dashboard, analytics page, data report or slide deck,

follow `.agent-skills/chart-dashboard/SKILL.md`.

```

| Tool | File |

|:--|:--|

| OpenAI Codex, Cursor, Zed, Aider, Jules, opencode | `AGENTS.md` |

| Gemini CLI, Gemini Code Assist | `GEMINI.md` |

| GitHub Copilot | `.github/copilot-instructions.md` |

| Windsurf | `.windsurf/rules/chart-dashboard.md` |

| Cline / Roo Code | `.clinerules/chart-dashboard.md` |

| Claude Code / Desktop / claude.ai | install as a skill, or `CLAUDE.md` |

Agents that discover skills from a manifest can read `.agents/skills.json`

instead, which points at `skills/` and needs no instruction file.

## Repo layout

This repo is a **marketplace of independent plugins**, one directory each. Every plugin

owns its own `.claude-plugin/plugin.json`, its own version, and its own `skills/`, so a

plugin can be installed on its own without dragging the others along.

```

plugins/chart-dashboard/

.claude-plugin/plugin.json

skills/chart-dashboard/ the skill: SKILL.md, references/, templates/, assets/, scripts/

plugins/decisions-only/

.claude-plugin/plugin.json

skills/decisions-only/ SKILL.md, references/, evals/

plugins/whats-changed/ same shape as decisions-only

plugins/sanity-check/ same shape as decisions-only

plugins/exec-brief/ same shape as decisions-only

examples/ six finished outputs (two dashboards, deck, report, one-pager, email snapshot)

docs/ GitHub Pages landing page

.claude-plugin/ the marketplace manifest listing every plugin

```

`examples/` and `docs/` sit **outside** every plugin on purpose: they are browsable on

GitHub but are not shipped to anyone who installs a plugin.

## Contributing

New chart types need an entry in `references/chart-selection.md` — when to use

it and when not to — alongside the engine code. The selection guidance is what

makes the output good, not the renderer.