hive.chart-creation-foundations

1# Chart creation foundations
2 
3These tools render BI/financial-analyst-grade charts and diagrams that show up live in the chat AND save as high-DPI PNGs in the user's queen session dir.
4 
5## The embedding contract — one rule
6 
7> **To put a chart in chat, call `chart_render`. The chat reads `result.spec` and renders the chart live in the message bubble. The download link is `result.file_url`. Do not write `![chart](...)` image markdown by hand — the tool's result drives the UI.**
8 
9That's it. One tool call, one chart in chat, one file on disk. No two-step "remember to also save it" pattern. The chat's chart-rendering UI is fed by the tool result envelope automatically.
10 
11## When to chart at all
12 
13Chart when the data is **visual at heart**: trends over time, distributions, comparisons across categories, hierarchies, flows, geo. Skip the chart when:
14 
15- The point is one number → just say it. ("Revenue was $4.2M, up 12% YoY.")
16- The point is a ranking of 5 things → use a markdown table with bold and emoji indicators.
17- The data is so noisy a chart would mislead → describe the takeaway in prose.
18 
19A chart costs the user attention. It must repay that cost with a takeaway they couldn't get from prose.
20 
21## ECharts vs Mermaid — the picking rule
22 
23| Use ECharts (`kind: "echarts"`) when... | Use Mermaid (`kind: "mermaid"`) when... |
24|---|---|
25| You're plotting **numbers over categories or time** | You're showing **structure, not data** |
26…