AGENTS.md · git:20261008.7b1e5b1 · 2026-10-08 · sha256 1cf16c24fef7fefc

AGENTS.md git:20261008.7b1e5b1A

Immutable. This exact content never changes and is served at /api/v1/blob/1cf16c24fef7fefc.

# 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`.
```

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.